Skip to content
robbiebyrdPublic

About

A collection of React components that make it easy to add a customizable Webtop to your app with a unique & retro look.

Topics

Resources

Stars

154 stars

Watchers

2 watching

Forks

Repository files navigation

Previously Platinum

A UI framework using native CSS/JS replications of the Mac OS 8 interface components.

Just curious? Visit our website to learn more.

Demo

UI Components

Using Classicy in a Vite app

Classicy is a framework, @classicy/classicy, and the looks it draws, its Appearance Packages: @classicy/appearance-platinum, the Platinum look (Mac OS 8), and @classicy/appearance-system7, System 7 (below). Install the framework and a package, at the same version:

pnpm add @classicy/classicy @classicy/appearance-platinum
pnpm add react react-dom # for a new app

Import Platinum once, at your app's entry, before you render. The framework registers no Appearance Package of its own:

import "@classicy/appearance-platinum";
import {
  ClassicyAppManagerProvider,
  ClassicyDesktop,
} from "@classicy/classicy";
import { createRoot } from "react-dom/client";

createRoot(document.getElementById("root")!).render(
  <ClassicyAppManagerProvider>
    <ClassicyDesktop>{/* your ClassicyApp components */}</ClassicyDesktop>
  </ClassicyAppManagerProvider>,
);

Without that import, ClassicyDesktop draws a "No Appearance Package is loaded" message (showing the import line) instead of the desktop, mounts none of its children, and logs one error per page. The desktop appears as soon as a package registers. Platinum's own names (PLATINUM_APPEARANCE_PACKAGE_ID, platinumAppearanceHooks, platinumSoundPack) are exports of @classicy/appearance-platinum, which ships its type declarations (bundler, node16 and nodenext resolution).

Browser support: Chrome/Edge 120+, Safari 16.2+, Firefox 113+. Theme colors are mixed in CSS with color-mix() (Safari 16.2, Firefox 113), and icons are drawn with unprefixed mask-image and mask compositing (Chrome 120); in an older browser those declarations are dropped, so tints, overlays and icon art go missing.

Upgrading from 2.1.x? docs/RELEASE-NOTES-APPEARANCE-PACKAGES.md lists every breaking change below, and the rest of the release, with its migration step.

Upgrading from 3.0.x? docs/RELEASE-NOTES-3.1.md: the screen savers (and their logo registry) now ship with @classicy/appearance-platinum; a host importing one from @classicy/classicy changes the import specifier.

Upgrading from 3.4.x? docs/RELEASE-NOTES-3.5.md: the new System 7 package, and the core capabilities it brought (per-theme asset variants, 16 px icon images, alert sounds from the sound pack, Classicy's own scroll bars); ClassicyControlGroup no longer paints its title's background inline.

Breaking change: the package is renamed. classicy is now @classicy/classicy (the unscoped name stops at 2.x). Replace the dependency, and rewrite every specifier, strings included: from "classicy", deep paths (classicy/dist/classicy.css, classicy/scss/*), vi.mock("classicy", …) and typeof import("classicy"). A host that auto-bumps dependencies (Renovate, a script, pnpm's minimumReleaseAgeExclude) must list every Classicy package it loads (@classicy/classicy, @classicy/appearance-platinum and, when you load it, @classicy/appearance-system7) and move them together. The core and Platinum exist from 3.0.0 on, System 7 from 3.5.0; a lower range does not resolve. The release notes give a one-pass sed.

Importing @classicy/classicy injects its stylesheet. Platinum's fonts, art, wallpapers and sound sprites are files in @classicy/appearance-platinum's dist/assets/. Breaking change for Vite consumers: Vite's dev server pre-bundles dependencies into node_modules/.vite/deps/, which breaks those file URLs (they return the SPA fallback page). Exclude both packages from the pre-bundle (and @classicy/appearance-system7, when you load it, as example/vite.config.ts does):

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    exclude: [
      "@classicy/classicy",
      "@classicy/appearance-platinum",
      "@classicy/appearance-system7", // when you load it
    ],
  },
})

Any CommonJS dependency they pull in may then need to go in optimizeDeps.include. Bundlers that handle new URL(…, import.meta.url) (a Vite production build, webpack 5, Rollup with a URL plugin) need no setting; with any other (plain esbuild, Rollup without such a plugin), copy each package's dist/assets/ (Platinum's, and System 7's when you load it) next to your bundle. import "@classicy/classicy/fonts" is now a deprecated no-op (the Platinum package registers its fonts), and classicy/dist/fonts.css is gone: a strict-CSP host links @classicy/appearance-platinum/classicy-platinum.fonts.css in its place (below).

Breaking change: system art and cursors are no longer icons. The ClassicyIcons constant is now only the Platinum icon tree as shipped: it does not reflect later registerClassicyIcons calls (ClassicyIcons.myApp.icon is undefined at runtime), so read icons through useClassicyAsset (in a component) or resolveClassicyAsset (elsewhere), never the constant. In particular, registerClassicyIcons({ applications: { ...ClassicyIcons.applications, mine } }) followed by a read of ClassicyIcons.applications.mine now returns undefined (usually behind a cast, so tsc is silent): drop the spread and read through the value registerClassicyIcons returns, or resolveClassicyAsset("icons", "applications.mine"). And Platinum draws these as system art and cursors, so registering them under registerClassicyIcons no longer changes what is drawn (most of them are gone from the icon tree, below). Register the replacement instead:

Icon path you used to register Register now
system.alias registerClassicySystemArt("platinum", { aliasBadge })
system.apple registerClassicySystemArt("platinum", { appleMenu })
system.desktop.trashEmpty registerClassicySystemArt("platinum", { trashEmpty })
system.desktop.trashFull registerClassicySystemArt("platinum", { trashFull })
ui.helpButton registerClassicySystemArt("platinum", { helpButton })
classicy.logo registerClassicySystemArt("platinum", { aboutLogo })
system.macosSvg registerClassicySystemArt("platinum", { startupLogo })
ui.cursors.watch, .hand, .resizeLr, .resizeUd, .resizeU, .resizeD, .resizeL, .resizeR registerClassicyCursors("platinum", { watch, hand, resizeLr, resizeUd, resizeU, resizeD, resizeL, resizeR })

Seven icon paths are gone from ClassicyIcons and the Platinum icon tree. Nothing in Classicy drew any of them; register your own image under a path to keep it (registerClassicyIcons({ system: { bomb } }); the 2.1.7 images are in that release's assets/img/):

Removed icon path Replacement
system.bomb None
system.files._229, system.files._232Messages None (their files never existed: both were "" in 2.1.x)
ui.halftoneSmall None (Classicy's halftone is the system art halftone, a different image)
ui.menuDropdownArrows System art popupArrows (the same arrows, in currentColor)
ui.stripe None (a diagonal hatch; the title-bar stripes, system art windowStripes, are a different pattern)
ui.tab Nearest: system art tabOutline (the same shape as an open outline, not filled)

Thirteen more icon paths are gone in 3.0: their files were Platinum's alone, and moved into the Platinum package. Read what Platinum registers in their place, the same image (useClassicyAsset or resolveClassicyAsset):

Removed icon path Read instead
system.apple system art appleMenu
system.alias system art aliasBadge
system.desktop.trashEmpty, system.desktop.trashFull system art trashEmpty, trashFull
ui.helpButton system art helpButton
ui.cursors.watch, .resizeLr, .resizeUd, .resizeU, .resizeD, .resizeL, .resizeR the cursor role of the same name
controlPanels.appearanceManager.platinum the Platinum package's icon (getClassicyAppearancePackage("platinum")?.icon)
ui.cursors.add, eyedropper, handCounting, highlight, menu, plus, precision, rom, shortcut, spin None (the files were unread and are deleted; register your own at the path with registerClassicyIcons to keep one)

docs/AGENT-REFERENCE.md §5 has the full asset-registry reference.

Breaking change: shared state classes and cascade layers. A component's state is now a bare class beside its root class, so the classes that folded a state into their name are gone, and data-state is no longer set anywhere. Update host CSS and tests that select them:

Old class Now
classicyWindowActive, classicyWindowInactive .classicyWindow.active, .classicyWindow.inactive
classicyWindowCollapsed, classicyWindowDragging .classicyWindow.collapsed, .classicyWindow.dragging
classicyButtonDefault, classicyButtonDepressed .classicyButton.default, .classicyButton.pressed
classicyMenuItemDisabled, classicyMenuItemOpen .classicyMenuItem.disabled, .classicyMenuItem.open
classicyTabButtonActive .classicyTabButton.selected
classicyDesktopIconActive, classicyDesktopIconOpen, classicyDesktopIconActiveAndOpen .classicyDesktopIcon.selected, .open, .selected.open
classicyIconActive .classicyIcon.selected
classicyListBoxOptionSelected, classicyTableRowSelected .classicyListBoxOption.selected, .classicyTableRow.selected
classicyDesktopMenuAppleMenu classicyDesktopMenuApple
[data-state="…"] on BevelButton, Placard, ImageWell .checked, .pressed, .mixed, .disabled, .selected, .open

The exported type ClassicyBevelButtonState is deleted. @classicy/classicy/scss/* now resolves to the vocabulary (@use "@classicy/classicy/scss/vocabulary"); the old theme partials are Platinum's, at @classicy/appearance-platinum/scss/* (see Appearance Packages below). The global .hidden utility and classicyWindowZoomed are gone, and a zIndex passed in style to ClassicyWindow, ClassicyIcon or ClassicyDesktopIcon is dropped.

Classicy's stylesheet is now in cascade layers (@layer classicy.base, classicy.package, classicy.user), so unlayered host CSS and every host layer beat Classicy whatever the specificity: a host button { … } or Tailwind v4's Preflight now restyles Classicy's controls. Keep resets in the reserved classicy.base.host sublayer (for Tailwind v4, replace @import "tailwindcss"; with the granular form in docs/AGENT-REFERENCE.md §1). Because the state classes are bare generic names (active, open, error, selected, …), a host's global .active { … } now matches Classicy elements too: scope such rules to your own markup. The screen saver's hidden cursor no longer beats an unlayered host * { cursor: … }.

The full old → new table (every renamed class) is in docs/AGENT-REFERENCE.md §5, "Migrating to the shared vocabulary". Markup you build by hand to look like Classicy's needs the same vocabulary: the bare state classes, plus data-classicy-part on menu-bar clusters and data-classicy-control on title-bar boxes, which flex order now keys on (without them a zoom box sorts left of the title).

Breaking change: the look is an Appearance Package. Classicy's stylesheet now holds structure only; the Platinum look (every bevel, border, gradient and piece of art) is the Platinum Appearance Package's own stylesheet, in @layer classicy.package and scoped under .classicyDesktop[data-classicy-appearance="platinum"]. Importing @classicy/appearance-platinum registers it, and everything inside ClassicyDesktop looks as before.

  • Components outside a desktop get structure only, no look. Wrap a standalone component in an element carrying class="classicyDesktop" and data-classicy-appearance="platinum", with the theme and asset variables on it (getThemeVars(getTheme("default")) and useClassicyAssetVars()); give it id="classicyDesktop" so portals (menus, balloons) render inside it rather than falling back, unstyled, to document.body.

  • Strict-CSP hosts link three files, first in <head> and in this order: @classicy/classicy/dist/classicy.css (structure, the core's), then the Platinum package's @classicy/appearance-platinum/classicy-platinum.css (the look) and @classicy/appearance-platinum/classicy-platinum.fonts.css (the Platinum fonts). Those are the packages' exports; a plain <link> names the files themselves:

    <link rel="stylesheet" href="/node_modules/@classicy/classicy/dist/classicy.css">
    <link rel="stylesheet" href="/node_modules/@classicy/appearance-platinum/dist/classicy-platinum.css">
    <link rel="stylesheet" href="/node_modules/@classicy/appearance-platinum/dist/classicy-platinum.fonts.css">

    A policy that blocks inline <style> blocks all three runtime injections; the fonts file holds the same @font-face rules the package writes, each pointing at its .woff2 in the Platinum package's dist/assets/ (serve that folder beside it, and allow it in font-src). Allow data: in img-src too (img-src 'self' data:): a dimmed icon (a hidden application's in the Application menu, a disabled list row's) is drawn on a canvas and shown from a data: URL, and a few masks and glyphs are inline data: images, which a policy without it shows broken. Link the files rather than importing them through your bundler: Vite inlines the small Monaco font as a data: URL, which font-src 'self' blocks. If you must import them, set build.assetsInlineLimit: 0 or allow font-src data:. Linking (copied, or served from node_modules) is the recommended way.

  • The theme partials moved. classicy/scss/appearance, classicy/scss/scrollbars and classicy/scss/assets (2.1.x; pre-release builds called them classicy/scss-platinum/*) are now @classicy/appearance-platinum/scss/mixins, …/scrollbars and …/assets. The mixins are renamed to kebab-case with a platinum- prefix (appearance.platinumWindowControlBoxBorder → mixins.platinum-window-control-box-border; scrollbars.scrollbars → scrollbars.platinum-scrollbars), except scrollbars.scrollbars-inactive, which is removed (it never drew in Classicy's own windows; copy its rules from the 2.1.7 source if you used it), and px-rect/no-select moved to the vocabulary as classicy-px-rect/classicy-no-select (@classicy/classicy/scss/layout). The full rename table is in docs/AGENT-REFERENCE.md, "Migrating to Appearance Packages". classicy/scss/themes.json is gone: call getAllThemes(). Platinum's partials reach the vocabulary as pkg:@classicy/classicy/scss/*, so a host that @uses them compiles with Sass's NodePackageImporter (Vite: css.preprocessorOptions.scss.importers: [new NodePackageImporter()]), imported from the Sass package your build uses: sass-embedded for a host on sass-embedded, sass for one on sass. @classicy/classicy/appearance/platinum and @classicy/classicy/appearance/platinum/scss/* are gone: import @classicy/appearance-platinum, which registers Platinum and exports its names (PLATINUM_APPEARANCE_PACKAGE_ID, platinumAppearanceHooks, platinumSoundPack), which are no longer @classicy/classicy exports.

  • platinum-halftone takes a token name. The mixin now takes a color token NAME (@include mixins.platinum-halftone("--color-black"), not a color) and paints the dither on a ::before child, which sets position: relative and isolation: isolate on the element it is included in. The encode-color SCSS function is removed.

  • Platinum's art is registered system art (--classicy-art-<key>, published by ClassicyDesktop): the assets.$… art variables are gone, and a standalone component needs useClassicyAssetVars() on its wrapper (above) or its art is missing. ClassicyWindowFrame now draws the window's title bar (ClassicyWindowTitleBar): target .classicyWindowFrame .classicyWindowTitleBar instead of the removed classicyWindowFrameTitleBar/classicyWindowFrameTitleText. The Control Strip and pop-up slider row constants (controlStripTab, popUpSliderTrack, …) are no longer exported: read them with useClassicyPixelArtRows(key) or draw <ClassicyPixelArt art={key} />. The published platinum-window-control-box and platinum-window-control-box-depressable mixins draw their dither from --classicy-art-window-dither, so a host using them outside a desktop must define it (or accept no dither). They and platinum-menu-divider now draw only the look: the box's size and its ::before/::after geometry, and the divider's full-width stretch, are base structure, so a host including them on an element of its own sets those itself.

  • Text glyphs are package CSS. The menu check and dash, the pop-up and combo-box check, the bevel button's ▸ ▾, the placard's ▾, the file input's ✕ and the HyperCard tools palette's ✓ are now empty aria-hidden spans the package fills with ::before/::after content: their textContent is "", and getByText("✓") finds nothing.

  • Checkable roles. A menu item with checked set is role="menuitemcheckbox" with aria-checked, so getByRole("menuitem", { name }) misses it; a HyperCard tools-palette entry is role="button" with aria-pressed.

  • Caption colors are custom properties. A captionStyle reaches the cue as --classicy-caption-* properties, not inline color and background-color (style.color reads ""), so it no longer carries inline precedence: host CSS in classicy.user, or unlayered, overrides it. Theme captions through .quickTimePlayerCaptions:not(.quickTimePlayerCaptionsCustomStyle) to keep the viewer's choice.

  • ClassicyKbd wraps each modifier in its own <span class="classicyKbdModifier" data-classicy-part="modifier-<name>">. The text is unchanged; snapshots of its children change.

  • Fixed: Firefox no longer shows a scroll bar under tab strips in the built library (the desktop's scroll-bar fallback used to beat the tab scroller's scrollbar-width: none).

The full mixin table and the package API are in docs/AGENT-REFERENCE.md §5, "Migrating to Appearance Packages", and §8, "Appearance Packages".

Changed: sizes and colors derive from the theme.

  • Overriding an input no longer rescales the derived sizes. Stylesheets read named sizes that getThemeVars computes from the theme (--menu-min-width, --popup-height, --ui-font-size-small, …) instead of calc(var(--window-control-size) * N). A host that overrides an input such as --window-control-size on the desktop now changes only that variable. Change the theme's measurement instead, or override the derived variable itself (docs/AGENT-REFERENCE.md §8, "Overriding sizes from a host").
  • Error title bars are #ffcccc, classicy-tint("--color-error", 80%), instead of #f7cecd, so they follow a theme's error color. New SCSS helpers classicy-tint, classicy-shade and classicy-alpha are at @classicy/classicy/scss/color.
  • ClassicyWindowOpen no longer treats [0, 0] as "no position". A new window opens where its position says, [0, 0] included. To have it cascaded (30 + 10·n), omit position or pass autoPosition: true. ClassicyWindow always supplies a position, so its windows are unaffected (default [110, 110]).
  • A package knob that would make a variable Classicy sets itself (menu.minWidth → --menu-min-width) is skipped with a warning and left out of the Options tab.

New: Appearance Packages can rename and re-icon apps. A package's optional apps field ({ "MoviePlayer.app": { name: "Media Player", icon, description } }, keyed by app id, bundled or your own) changes how an app is shown everywhere its name or icon is drawn. It is display only: ids, action types, records and persisted state keep the app's own name, and analytics paths are built from the app id (window titles still reach GA as drawn), so build nothing from a displayed name, and read useClassicyAppIdentity(id, { name, icon }) for text that names an app. Under any package:

  • File-system adapters see one snapshot-hash change on the first save after upgrading: the derived Applications, Extensions and Control Strip Modules entries are no longer persisted or sent in snapshots.
  • A derived folder never overwrites a static entry. A user's file named like an app is kept, and the app is listed beside it as " ()"; only Platinum's untouched placeholders (_placeholder) give way.
  • App records and desktop icon balloons follow the code. apps[id].name and icon are refreshed from ClassicyApp's props on every mount, and a desktop icon's balloon is stored only when desktopIconBalloonHelp is given (the manifest description is resolved at render).
  • PDF Viewer's close action type is fixed. It dispatched "ClassicyAppPDF ViewerCloseFile" (with a space); it now dispatches ClassicyAppPDFViewerCloseFile. A host matching the old string must match the new one.
  • Every asset url() is quoted. CSS variables and styles that carry an asset (--classicy-icon-mask, --desktop-background-image, the cursor, …) are written url("…"), so a data: SVG icon keeps its mask. Tests that matched the unquoted string must expect the quotes.
  • Error alerts are session-only. Desktop.errorDialog is no longer persisted, so a reload never re-shows an open alert.

Details: docs/AGENT-REFERENCE.md §8, "App display overrides".

Changed: pixel sizes are theme knobs. Platinum looks the same; the Control Strip, menu frame, Pager, Balloon Help, pop-up slider, dialogs and the other pixel-matched surfaces now read measurements.<family> knobs from the theme (--<family>-<key>) instead of Npx literals.

  • Breaking: POPUP_MENU_MAX_HEIGHT is removed. The pop-up menu's cap is the theme variable --menu-pop-up-max-height (300 under Platinum); classicyPopUpMenuPlacement takes it as an optional last argument.
  • Breaking: no pixel fallbacks. Stylesheets read var(--x) with no Npx fallback, so a component outside ClassicyDesktop needs the full getThemeVars(theme) on its wrapper.
  • Breaking for packages: a measurement whose variable starts with --color-, or names one of the 119 named derivations, is skipped.
  • Breaking for host CSS: 84 more sizes are named derivations that getThemeVars sets, so overriding an input variable such as --window-padding-size no longer moves them: change the theme, or override the derived variable.
  • Breaking for SCSS hosts: Platinum's published platinum-menu-frame and platinum-scrollbars mixins read knob variables that only getThemeVars emits.
  • The Options tab shows six groups of Platinum knobs.
  • withDefaultThemeMetrics(theme, defaults?) takes the defaults to fill from; pass classicyThemeMeasurementDefaults(theme.package) to complete a package's families.

Details: docs/AGENT-REFERENCE.md §5, "Upgrading: package knobs and the pixel-literal purge (Part H)", and §8, "Package knob families".

System 7

@classicy/appearance-system7 draws System 7.5, in black and white ("System 7") and in color ("System 7 Color"), with System 7.5's own icons, art, cursors, desktop pattern and alert sounds, and the same twelve screen savers. Use it alone or beside Platinum; the Appearance Manager switches between them. Install every package you load at one version, and bump them together:

pnpm add @classicy/classicy @classicy/appearance-system7
# or, with both looks:
pnpm add @classicy/classicy @classicy/appearance-platinum @classicy/appearance-system7
import "@classicy/appearance-platinum"; // optional
import "@classicy/appearance-system7";

A Vite host lists it in optimizeDeps.exclude too (above). Its README, packages/appearance/system7/README.md, has its exports and its strict-CSP stylesheets.

Building and running on localhost

This project uses pnpm (enable it with corepack enable). First install dependencies:

pnpm install

To create a production build:

pnpm build

To create a development build:

pnpm dev

Running

To run the example site locally (builds the package and starts the example dev server):

pnpm preview

Then visit the site in your browser at http://localhost:3000.

(For iterative package development you can also use pnpm dev, which builds the source. The example/ app consumes it directly through the pnpm workspace — no linking step required.)

Browser app — TimeMachine Proxy

The Browser app requires the TimeMachine Web Proxy to fetch archived web pages. A Docker Compose setup is included in the example/ folder:

cd example
cp .env.example .env   # adjust if needed
docker compose up -d

The proxy runs on http://localhost:8765 by default. Enable it in the Browser app under File → Settings → Enable TimeMachine Proxy.

Acknowledgments

Features

Legend

✅ ℹ️ ⚠️
Complete Partially complete. Experimental
Subject to change
  • Desktop
    • ✅ The ubiquitous Finder
    • Menubar
      • ✅ System Menu
      • ✅ App Switcher
      • ✅ Widgets
        • ✅ Date/Time
        • ✅ Sound
    • Icons
      • ✅ App Shortcuts
      • ✅ Cleanup
      • Arrange By…
  • Sounds
    • ✅ Sound Provider
    • ✅ Load sound theme from JSON
    • ✅ Audio Sprites support
    • ✅ Sound Manager Control Panel
      • ✅ Sound Event Handler
        • ✅ Event dispatcher/player
        • ✅ Automatic event intercept and play for known events (map audio sprites to events)
  • Logging & Diagnostics
    • ✅ registerClassicyLogSink — host apps receive Classicy logs, errors, and crash reports (production builds included)
  • Screen Saver
    • ✅ Idle-activated full-screen screensavers (After Dark CSS ports: Flying Toasters, Fish, Warp, and 9 more, shipped by @classicy/appearance-platinum; each Appearance Package offers its own)
    • ✅ Screen Saver Control Panel (pick saver, timeout, per-saver options)
    • ✅ registerClassicyScreenSaver API with custom or schema-derived options UI
  • Appearance Manager Control Panel (Theme Manager)
    • ✅ Appearance Manager Control Panel
    • ✅ System
      • ✅ Load theme from JSON
      • ✅ System events for modifying theme
    • UI
      • ✅ Typography settings
      • ✅ Measurement settings
      • ✅ Desktop settings
      • ✅ System colors
      • ✅ Configurable color variables
    • ✅ Color Theme-able components
  • App Template
    • ✅ App Context/Event Handler
    • ✅ App Switcher
  • Window
    • Controls
      • ✅ Zoom
      • ✅ Resize
      • ✅ Collapse
      • ✅ Close
      • ✅ Placard
      • ✅ Header
    • Dialog
      • Modal
        • Dialog
          • ✅ Movable
          • ✅ Non-movable
        • Alert
          • ✅ Movable
          • ✅ Non-movable
      • ✅ Modeless
    • ✅ Standard
  • System
    • ✅ File System
      • ✅ Integrated into Finder.app
  • UI Components
    • ✅ Text Input
    • ✅ Text Area
    • ✅ Button
    • ✅ Tabs
    • ✅ Radio Button
    • ✅ Drop-down menu
    • ✅ Drop-down menu groups (optgroup)
    • ✅ Form (dialog layout, safe submit)
    • ✅ Multi-select menu (List Box)
    • ✅ Combo box (autocomplete)
    • ✅ Table (Platinum list view)
    • ✅ Checkbox
    • ✅ Bevel Button
    • ✅ Slider
    • ✅ Spinner
    • ✅ Date Picker
    • ✅ Time Picker
    • ✅ Expandable (Disclosure)
    • ✅ Fieldset
    • ✅ Separator
    • ✅ Progress
    • ✅ Balloon Help (tooltip)
    • ✅ Link (desktop-routed hyperlink)
    • ✅ Meter (gauge with zones)
    • ✅ Output (read-only result)
    • ✅ Keyboard shortcut display (kbd)
    • ✅ Menu
      • ✅ Desktop Menu
      • ✅ Contextual Menu
      • ✅ Submenu
    • Gallery Picker (Slider)
    • ✅ Color Picker

Component Reference

All components are exported from the @classicy/classicy package. Import them by name:

import { ClassicyWindow, ClassicyButton, ClassicyBalloonHelp } from '@classicy/classicy';

Building an app? docs/BUILDING-APPS.md is the step-by-step guide: ClassicyApp and ClassicyWindow prop-by-prop, manifests, reducers, menus, icons, files, dialogs, balloon help, sound, analytics, extensions, persistence, and testing — plus the traps that cost the most time. It ships with the package at node_modules/@classicy/classicy/docs/BUILDING-APPS.md.

Using an AI coding agent? A complete machine-oriented reference to the public API — every component's props, app/event/icon registration, theming, analytics, sound, and the untrusted-action rules — ships with the package at docs/AGENT-REFERENCE.md (node_modules/@classicy/classicy/docs/AGENT-REFERENCE.md). Point your agent at it.

Each table below lists the raw HTML element the component replaces — inside a Classicy desktop, prefer the component over the raw tag (e.g. ClassicyButton instead of <button>) to get theming, sounds, and balloon help for free. The full two-way map, including HTML elements that have no Classicy equivalent, is in docs/AGENT-REFERENCE.md §4.0.

Application Shell

Component Description HTML equivalent
ClassicyDesktop Root desktop surface — icons, menu bar, wallpaper, drag-select — (desktop metaphor)
ClassicyDesktopMenuBar Top menu bar with system menu, app menu, and widget tray <nav>
ClassicyApp Application container. Props: id, name, icon, defaultWindow —
ClassicyWindow Window chrome with title bar and controls. Props: id, appId, title, closable, zoomable, collapsable, resizable, modal, initialSize, initialPosition, minimumSize <dialog> (non-modal; modal prop for modal)
ClassicyBoot Boot screen shown on first load —
ClassicyScreenSaver Idle-activated screensaver extension (auto-mounted by ClassicyDesktop); register your own savers with registerClassicyScreenSaver (packages names the Appearance Packages that offer one) —
ClassicyAboutWindow Standard "About This App" dialog. Props: appId, appName, appIcon <dialog>

Inputs

Component Description HTML equivalent
ClassicyButton Push button. Accepts children as label <button>
ClassicyCheckbox Checkbox with optional label. Props: checked, label, onChangeFunc <input type="checkbox">
ClassicyRadioInput Radio button group. Props: label, options (array of { label, value }) <input type="radio"> group
ClassicyInput Single-line text field. Props: placeholder, value, onChangeFunc <input type="text"> (any text-like type)
ClassicySpinner Numeric stepper (up/down arrows). Props: value, min, max, step <input type="number">
ClassicyPopUpMenu Drop-down selector. Props: label, options ({ label, value } items or { groupLabel, options } groups), value <select> / <option> / <optgroup>
ClassicyListBox Scrolling list with single or multi selection (⌘-toggle, Shift-range). Props: options, selectionMode, selected, onChangeFunc, visibleRows <select multiple>
ClassicyComboBox Editable field with filtering suggestions and a pop-up arrow. Props: options, filter, freeText, onSelectFunc <datalist>
ClassicyDatePicker Date input with calendar picker. Props: value, placeholder, onChangeFunc <input type="date">
ClassicyTimePicker Time input with clock picker. Props: value, placeholder, onChangeFunc <input type="time">

Text Editing

Component Description HTML equivalent
ClassicyTextEditor Plain-text editor area. Props: content, onChangeFunc <textarea>
ClassicyRichTextEditor Rich-text editor (bold, italic, lists). Props: content, onChangeFunc contenteditable region

Layout & Structure

Component Description HTML equivalent
ClassicyTabs Tabbed container. Children must be ClassicyTab items with a title prop — (ARIA role="tablist" pattern)
ClassicyDisclosure Collapsible section (expand/collapse). Props: label, open <details> / <summary>
ClassicyControlGroup Labeled fieldset grouping form controls. Props: label <fieldset> / <legend>
ClassicyControlLabel Inline label for a control. Props: label <label>
ClassicySplitView Resizable two- or three-pane container with a draggable, keyboard-accessible divider. Props: direction, defaultSizes, minPaneSize, onResize, onResizeCommit — (nearest: obsolete <frameset>)
ClassicyForm Form wrapper with HIG row/dialog spacing; submit never navigates. Props: onSubmitFunc, layout. Pair with ClassicyFormButtonRow for the Cancel/OK row <form>
ClassicyTable Platinum list view over arbitrary data: sortable/resizable columns, Mac row selection, keyboard navigation. Props: columns, rows, getRowId, selectionMode, onActivateRow <table>

Menus

Component Description HTML equivalent
ClassicyMenu Drop-down menu used in the menu bar. Props: id, title, menuChildren <menu>
ClassicyContextualMenu Right-click context menu. Renders at pointer position <menu> (the old contextmenu attribute)

Feedback & Display

Component Description HTML equivalent
ClassicyProgressBar Determinate progress bar. Props: value, max, label <progress>
ClassicyMeter Gauge with native meter zone semantics (theme accent / alert / error). Props: value, low, high, optimum, segments <meter>
ClassicyOutput Read-only calculation result — static text or inset well. Props: value, htmlFor, variant <output>
ClassicyKbd Keyboard shortcut display in Platinum glyph order (⇧⌘S), inline or as key caps. Props: shortcut, variant <kbd>
ClassicyLink Themed hyperlink routed through the desktop URL opener (WebViewer, browser, or new tab). Props: href, disposition, event <a>
ClassicyBalloonHelp Mac OS 8-style speech-bubble tooltip. Wraps any element. Props: content, title, position, delay title attribute (tooltip)
ClassicyIcon System icon image with optional label. Props: src, label <img> + caption

File System

Component Description HTML equivalent
ClassicyFileBrowser File browser with icon and list views. Props: path, onSelect —

Media

Component Description HTML equivalent
QuickTimeMovieEmbed Embedded QuickTime-style video player. Props: url <video> / <audio>

Menu Bar Widgets

Component Description HTML equivalent
ClassicyDesktopMenuWidgetTime Clock widget for the menu bar —
ClassicyDesktopMenuWidgetSound Deprecated. Mute toggle for the menu bar, no longer mounted by default. Use the Control Strip's built-in Sound module instead (classicy-sound; turn it off with ClassicyDesktop's controlStrip={{ disabledModules }}). Still exported; logs a one-time dev warning when mounted —

Control Strip

Component Description HTML equivalent
ClassicyControlStrip Mac OS 8 Control Strip at the desktop's lower left, showing every registered module — the built-in Sound and Screen Saver modules plus any an app or extension registers. Mounted by ClassicyDesktop; configure with its controlStrip prop (disabledModules, defaultCollapsed, defaultWidth), or pass false to hide it. Its collapsed state, width, and the user's module choices persist role="toolbar"
registerClassicyControlStripModule Adds a module (id, label, 16 px icon, menuItems or content, optional owning appId and order). Call at module scope; the strip updates live. Each module is also listed in System Folder:Control Strip Modules —
ClassicyControlStripManager The Control Strip control panel: show or hide the strip, and show, hide or reorder its modules —
ClassicyPopUpSlider Compact vertical slider for a pop-up bevel button (the Control Strip volume slider). Props: value, onChange, ariaLabel <input type="range">

Architecture

Component Organization

  • <ClassicyAppManagerProvider>
    • <ClassicyDesktop>
      • <ClassicyDesktopMenuBar>
      • <ClassicyDesktopIcon?>
      • <YourClassicyApp>
        • <ClassicyApp>
          • <ClassicyWindow?>
            • <ClassicyUIControls?>
            • <OtherReactNodes?>

ClassicyDesktop must be imported eagerly. Mounting it lazily, a tick after ClassicyAppManagerProvider, corrupts manager state: early dispatches reach a reducer whose state the desktop has not seeded yet, and every dispatch after that throws.

Writing an app? Start with docs/BUILDING-APPS.md — a step-by-step guide covering ClassicyApp, ClassicyWindow, manifests, reducers, menus, files, dialogs, sound, analytics, persistence, and testing.

Seeding default state

ClassicyAppManagerProvider accepts an optional defaultState — a deep-partial ClassicyStore merged over the built-in defaults on first load only (when no saved state exists in localStorage). Returning visitors keep their persisted state.

<ClassicyAppManagerProvider
  defaultState={{
    System: { Manager: { DateAndTime: {
      dateTime: "2001-09-11T12:40:00.000Z", // 8:40 AM US Eastern (EDT, UTC-4)
      timeZoneOffset: "-4",
    } } },
  }}
>
  {/* ... */}
</ClassicyAppManagerProvider>

Arrays in defaultState replace their default counterparts wholesale (they are not concatenated). To force a value on every load regardless of saved state, clear localStorage["classicyDesktopState"] or dispatch the change at runtime.

Seeding the default filesystem

ClassicyAppManagerProvider accepts optional defaultFileSystem and defaultFileSystemMode props to seed the virtual filesystem used by Finder and other file-aware apps on first load only (when no saved filesystem exists in localStorage["classicyStorage"]). Returning visitors keep their persisted filesystem.

<ClassicyAppManagerProvider
  defaultFileSystem={{
    "Macintosh HD": {
      _type: "drive",
      _icon: ClassicyIcons.system.drives.disk,
      Documents: {
        _type: "directory",
        _icon: ClassicyIcons.system.folders.directory,
        "My Document.txt": {
          _type: "text_file",
          _mimeType: "text/plain",
          _data: "Hello, Classicy!",
        },
      },
    },
  }}
  defaultFileSystemMode="merge"
>
  {/* ... */}
</ClassicyAppManagerProvider>

defaultFileSystemMode controls how the filesystem is constructed:

  • "merge" (default) deep-merges your tree onto the library's DefaultFSContent
  • "exclusive" uses your tree as the entire filesystem, ignoring DefaultFSContent

Like defaultState, filesystem trees are seed-only. To force a filesystem value on every load regardless of saved state, clear localStorage["classicyStorage"] or rebuild the filesystem at runtime.

To correct a returning visitor's already-persisted tree — renaming a seeded file, fixing a bad URL — pass defaultFileSystemSeedMigrations, a list of one-time corrections applied against stored state (see ClassicyFileSystemSeedMigrations.ts).

Default apps

ClassicyDesktop automatically mounts seven built-in apps — SimpleText, PDFViewer, MoviePlayer, PictureViewer, HyperCard, WebViewer, and Calculator — the same way it always mounts Finder. Each can be disabled individually via a prop on ClassicyAppManagerProvider:

<ClassicyAppManagerProvider
  disableSimpleText={false}    // default: false (loads)
  disablePDFViewer={false}     // default: false (loads)
  disableMoviePlayer={true}    // opt out of Movie Player
  disablePictureViewer={true}  // opt out of Picture Viewer
  disableHyperCard={true}      // opt out of HyperCard
  disableWebViewer={true}      // opt out of Web Viewer
  disableCalculator={true}     // opt out of Calculator
>
  <ClassicyDesktop />
</ClassicyAppManagerProvider>

A disabled app is also cleared from what a visitor saved before you disabled it: its Apple-menu entry, its Applications listing and an open window go away on their next visit. Disabling only stops the app from auto-mounting — it remains available to import and render yourself (e.g. import { PDFViewer } from "@classicy/classicy") if you want custom placement, and an app you render yourself keeps its entries.

Events

  • ClassicyDesktop

    • ClassicyDesktopClick
    • ClassicyDesktopDrag
    • ClassicyDesktopSetBalloonHelp
  • ClassicySoundPlay

    • ClassicyAlertSosumi
    • ClassicyAlertWildEep
    • ClassicyAlertIndigo
    • ClassicyBeep
    • ClassicyBoot
    • ClassicyButtonClickDown
    • ClassicyButtonClickUp
    • ClassicyInputRadioClickDown
    • ClassicyInputRadioClickUp
    • ClassicyMenuClose
    • ClassicyMenuItemClick
    • ClassicyMenuItemHover
    • ClassicyMenuOpen
    • ClassicyWindowClose
    • ClassicyWindowCollapse
    • ClassicyWindowControlClickDown
    • ClassicyWindowControlClickUp
    • ClassicyWindowExpand
    • ClassicyWindowFocus
    • ClassicyWindowMoveIdle
    • ClassicyWindowMoveMoving
    • ClassicyWindowMoveStop
    • ClassicyWindowOpen
    • ClassicyWindowResizeIdle
    • ClassicyWindowResizeResizing
    • ClassicyWindowResizeStop
    • ClassicyWindowZoomMaximize
    • ClassicyWindowZoomMinimize
  • ClassicyDesktopIcon

    • ClassicyDesktopClick
    • ClassicyDesktopAltClick
    • ClassicyDesktopDoubleClick
    • ClassicyDesktopDrag
  • ClassicyApp

    • ClassicyAppOpen
    • ClassicyAppClose
    • ClassicyAppHide
    • ClassicyAppFocus
  • ClassicyWindow

    • ClassicyWindowOpen
    • ClassicyWindowClose
    • ClassicyWindowZoom
    • ClassicyWindowCollapse
    • ClassicyWindowResize
    • ClassicyWindowDrag
    • ClassicyWindowFocus
    • ClassicyWindowContentScroll
    • ClassicyWindowContentClick
  • ClassicyMenu

    • ClassicyMenuHover
    • ClassicyMenuClick
    • ClassicyMenuChange

License

This software is provided free and in the public domain under The Unlicense.

About

A collection of React components that make it easy to add a customizable Webtop to your app with a unique & retro look.

Topics

Resources

Stars

154 stars

Watchers

2 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages