@leef-l/macos-ui-kit 0.0.0-stage → 0.1.1

package/dist/mobile/shell.d.ts

@@ -0,0 +1,59 @@
+import { Component } from "../component";
+import "./shell.css";
+export interface MobileTab {
+    /** Stable key. */
+    id: string;
+    /** Short label under the icon. */
+    label: string;
+    /** SVG path data for the tab icon. */
+    icon: string;
+}
+export interface MobileShellOptions {
+    /** Large navigation title shown above the content. */
+    title: string;
+    /** Tab bar entries. Empty hides the bar (a single-pane screen). */
+    tabs?: MobileTab[];
+    /** Initially visible tab. */
+    selected?: string;
+    /** Fired when the tab changes. */
+    onTabChange?: (id: string) => void;
+    /** Optional trailing action on the navigation bar. */
+    action?: HTMLElement;
+}
+/**
+ * The mobile counterpart of the desktop shell.
+ *
+ * Deliberately separate from `layout/TitleBar` rather than a media-query variant
+ * of it. A phone has no draggable window, no traffic lights and no persistent
+ * sidebar; navigation lives in a bottom tab bar, which is the platform-native
+ * pattern. Sharing markup between the two would mean every style rule carrying
+ * a device exception, which is harder to reason about than two focused modules.
+ *
+ * Panes are plain containers the host app fills, so this stays layout-only.
+ */
+export declare class MobileShell extends Component<HTMLElement> {
+    protected readonly root: HTMLElement;
+    private readonly titleNode;
+    private readonly contentNode;
+    private readonly tabBar;
+    private readonly onTabChange?;
+    private currentId;
+    constructor(options: MobileShellOptions);
+    /** The region host panes are appended to. */
+    get content(): HTMLElement;
+    /** Update the large title. */
+    setTitle(title: string): void;
+    /** Switch the active tab. */
+    setSelected(id: string, notify?: boolean): void;
+    /** The active tab id, or null when the shell has no tabs. */
+    get selected(): string | null;
+}
+/**
+ * Detect whether this build is running inside a mobile Wails shell.
+ *
+ * Wails reports the host through `runtime.GOOS` on the Go side, but the
+ * frontend also needs an answer before any binding round-trip, so this checks
+ * the viewport instead: a coarse pointer plus a narrow window is a phone or
+ * tablet. The host app can override the decision either way.
+ */
+export declare function looksLikeMobile(): boolean;

package/dist/overlay.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Overlay plumbing shared by Menu, Tooltip and Dialog.
+ *
+ * Positioning is the part every hand-written popover gets wrong: it clamps in
+ * one direction, forgets the scroll offset, or escapes the viewport when the
+ * anchor sits near an edge. This module resolves a placement against the
+ * viewport, flips when there is no room, and re-resolves on scroll and resize
+ * (via rAF so a burst of events costs one layout pass).
+ */
+export type Placement = "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "right";
+export interface PositionOptions {
+    /** Element the overlay points at. */
+    anchor: HTMLElement;
+    /** Overlay to place. Must already be in the document. */
+    panel: HTMLElement;
+    /** Preferred side; flips automatically when there is no room. */
+    placement?: Placement;
+    /** Gap between the anchor and the panel, in px. */
+    offset?: number;
+    /** Keep this much space from the viewport edges. */
+    padding?: number;
+    /** Align the panel to the anchor's width (menus attached to fields). */
+    matchWidth?: boolean;
+}
+/** Resolve coordinates for a placement and write them to the panel. */
+export declare function positionOverlay(options: PositionOptions): void;
+/**
+ * Keep an overlay placed while the page changes.
+ *
+ * Returns a disposer. Callers must invoke it when the overlay closes;
+ * otherwise the scroll listener outlives the panel.
+ */
+export declare function trackOverlay(options: PositionOptions): () => void;
+export declare function nextZIndex(): number;
+/** All focusable descendants of a container, in DOM order. */
+export declare function focusableWithin(container: HTMLElement): HTMLElement[];
+/**
+ * Trap Tab focus inside a container (dialogs).
+ * Returns a disposer that also restores the previously focused element.
+ */
+export declare function trapFocus(container: HTMLElement): () => void;

package/dist/overlays/dialog.d.ts

@@ -0,0 +1,46 @@
+import { Component } from "../component";
+import { type Child } from "../dom";
+import "./dialog.css";
+export interface DialogOptions {
+    title: string;
+    /** Body content: a string, or any node for rich content. */
+    body?: Child;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    /** Fires when the user confirms. */
+    onConfirm?: () => void;
+    /** Fires when the user cancels, presses Escape or clicks the scrim. */
+    onCancel?: () => void;
+}
+/**
+ * A modal macOS alert.
+ *
+ * Three things a dialog must get right, and this one does because it delegates
+ * to `trapFocus` from overlay.ts:
+ *
+ * - Tab cycles inside the dialog instead of escaping to the page behind it.
+ * - Escape closes it, which is what a mac user reaches for.
+ * - Focus returns to whatever had it before the dialog opened.
+ *
+ * The scrim absorbs clicks on the "outside", treating them as a cancel.
+ */
+export declare class Dialog extends Component<HTMLDivElement> {
+    protected readonly root: HTMLDivElement;
+    private readonly scrim;
+    private readonly onCancel?;
+    private readonly onConfirm?;
+    private releaseFocus;
+    private opened;
+    constructor(options: DialogOptions);
+    /** Show the dialog modally. */
+    open(): void;
+    /** Hide the dialog and restore focus. */
+    close(): void;
+    /** Confirm and close. */
+    confirm(): void;
+    /** Cancel and close. */
+    cancel(): void;
+    /** Whether the dialog is on screen. */
+    get isOpen(): boolean;
+    destroy(): void;
+}

package/dist/overlays/menu.d.ts

@@ -0,0 +1,58 @@
+import { Component } from "../component";
+import { type Placement } from "../overlay";
+import "./menu.css";
+export interface MenuItem {
+    label: string;
+    value: string;
+    /** Leading SVG path data. */
+    icon?: string;
+    disabled?: boolean;
+    /** Show a checkmark (set `role=menuitemcheckbox` semantics). */
+    checked?: boolean;
+    /** Draw a separator instead of an item. */
+    separator?: boolean;
+    /** Grey trailing text, e.g. "⌘S". */
+    shortcut?: string;
+}
+export interface MenuOptions {
+    items: MenuItem[];
+    placement?: Placement;
+    /** Fires with the chosen value. */
+    onSelect?: (value: string) => void;
+}
+/**
+ * A macOS pop-up menu.
+ *
+ * Appended to `document.body` rather than the trigger's parent: a menu inside a
+ * scrolling pane or an `overflow: hidden` card would otherwise be clipped.
+ *
+ * Keyboard support follows the native menu: arrows move the highlight, Home/End
+ * jump, Enter selects, Escape closes and returns focus to the trigger.
+ */
+export declare class Menu extends Component<HTMLDivElement> {
+    protected readonly root: HTMLDivElement;
+    private readonly items;
+    private readonly onSelect?;
+    private readonly menuItems;
+    private opened;
+    private disposeTracking;
+    private restoreFocusTo;
+    private highlighted;
+    constructor(options: MenuOptions);
+    /** Open the menu anchored to an element. */
+    open(anchor: HTMLElement): void;
+    /** Close the menu and restore focus to whatever opened it. */
+    close(): void;
+    /** Whether the menu is currently open. */
+    get isOpen(): boolean;
+    private choose;
+    /** Move the keyboard highlight to an index, skipping disabled and separator
+        rows. */
+    private highlight;
+    /** Step the highlight by ±1, wrapping and skipping disabled entries. */
+    private step;
+    private onKeyDown;
+    destroy(): void;
+}
+/** Convenience: build a menu, open it at an anchor, and release it on close. */
+export declare function showMenu(anchor: HTMLElement, options: MenuOptions): Menu;

package/dist/overlays/popover.d.ts

@@ -0,0 +1,90 @@
+import { Component } from "../component";
+import { type Placement } from "../overlay";
+import "./popover.css";
+export interface PopoverOptions {
+    /** Arbitrary content: a string becomes text, a node is adopted as-is. */
+    content: Node | string;
+    /** Preferred side; flips automatically when there is no room. */
+    placement?: Placement;
+    /** Gap between the anchor and the panel, in px. */
+    offset?: number;
+    /** Draw a pointer aimed at the anchor. */
+    arrow?: boolean;
+    /** Accessible name for the dialog; a popover has no title of its own. */
+    ariaLabel?: string;
+    /** Fires whenever the popover closes, whatever closed it. */
+    onClose?: () => void;
+}
+/**
+ * A macOS popover: arbitrary content attached to an anchor element.
+ *
+ * This is the generalisation of `Menu` — the same anchoring plumbing, but the
+ * content is the caller's and the panel is non-modal, so the page behind stays
+ * interactive. Three consequences shape the implementation:
+ *
+ * - The panel is appended to `document.body`, never inside the trigger: a
+ *   popover opened from a scrolling pane or an `overflow: hidden` card would
+ *   otherwise be clipped.
+ * - It carries `role="dialog"` with `aria-modal="false"`, so assistive tech
+ *   announces a dialog without promising that the rest of the page is inert.
+ * - Focus returns to the anchor on close, but only while the popover still owns
+ *   it — clicking another field must not yank focus back.
+ *
+ * The markup is root → surface → body. The split exists because
+ * `positionOverlay` measures with `getBoundingClientRect`, which *includes*
+ * transforms: any entrance transform on the element being positioned would make
+ * the overlay place itself against a shrunken box. The root therefore stays
+ * untransformed and is what overlay.ts positions; only `__surface` animates.
+ */
+export declare class Popover extends Component<HTMLDivElement> {
+    protected readonly root: HTMLDivElement;
+    private readonly placement;
+    private readonly offset;
+    private readonly onClose?;
+    private readonly surface;
+    private readonly arrowNode;
+    private anchor;
+    private opened;
+    private disposeTracking;
+    private closeTimer;
+    private arrowFrame;
+    constructor(options: PopoverOptions);
+    /** Show the popover next to an anchor. Re-opening with a new anchor moves it. */
+    open(anchor: HTMLElement): void;
+    /** Hide the popover and hand focus back to the anchor. */
+    close(): void;
+    /** Whether the popover is currently on screen. */
+    get isOpen(): boolean;
+    /** Position options shared by the one-shot placement and the tracker. */
+    private positionOptions;
+    /** Resolve the panel against the current anchor. */
+    private place;
+    /**
+     * Re-aim the pointer one frame after a scroll or resize.
+     *
+     * Placement is itself rAF-throttled inside `trackOverlay`, and this callback
+     * may run before that pass, so it re-places first: measuring the panel where
+     * it is about to be drawn is the only reading that matters.
+     */
+    private scheduleArrowUpdate;
+    private cancelArrowUpdate;
+    /**
+     * Aim the pointer at the anchor's centre.
+     *
+     * Only the position *along* the panel's edge is measured here; CSS owns the
+     * side, taken from `data-side`, which positionOverlay sets. Both ends are
+     * clamped by half the arrow's own width, so a rotated square never pokes
+     * past a rounded corner — and no pixel constant has to be invented for it.
+     *
+     * `offsetLeft`/`offsetTop` are used instead of a rect because they report
+     * layout position and ignore transforms: the surface is mid-transition when
+     * this first runs, and a rect would describe the sliding box rather than the
+     * box the pointer is attached to. `clientLeft`/`clientWidth` then move the
+     * origin to the padding edge, which is what an absolutely positioned child
+     * is offset from — so the surface's own hairline border cannot skew it.
+     */
+    private positionArrow;
+    /** Put focus on the first control inside, or on the panel itself. */
+    private focusInto;
+    destroy(): void;
+}

package/dist/overlays/sheet.d.ts

@@ -0,0 +1,56 @@
+import { Component } from "../component";
+import { type Child } from "../dom";
+import "./sheet.css";
+export interface SheetOptions {
+    /** Sheet heading, also the accessible name of the dialog. */
+    title: string;
+    /** Body content: a string, or any node for rich content. */
+    body?: Child;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    /** Fires when the user confirms. */
+    onConfirm?: () => void;
+    /** Fires when the user cancels, presses Escape or clicks the scrim. */
+    onCancel?: () => void;
+}
+/**
+ * A macOS sheet: a modal attached to the window's top edge that slides down.
+ *
+ * Sheets differ from `Dialog` in two ways that shape the implementation:
+ *
+ * - **Geometry.** A dialog is centred in the viewport; a sheet is pinned to the
+ *   top and grows downward, so the window's title bar stays visible behind it.
+ *   That is the point of the pattern: it reads as belonging to *this* window
+ *   rather than to the application.
+ * - **Motion.** The entrance is `transform: translateY()` on the panel, never
+ *   `top` or `height`. A compositor-animated transform leaves the sheet's own
+ *   layout untouched, so a form inside it does not reflow while it slides in.
+ *
+ * Modal behaviour is delegated to `trapFocus` from overlay.ts: Tab cycles inside
+ * the sheet, and the disposer restores focus to whatever had it before.
+ */
+export declare class Sheet extends Component<HTMLDivElement> {
+    protected readonly root: HTMLDivElement;
+    private readonly scrim;
+    private readonly panel;
+    private readonly bodyNode;
+    private readonly onConfirm?;
+    private readonly onCancel?;
+    private releaseFocus;
+    private opened;
+    private closeTimer;
+    constructor(options: SheetOptions);
+    /** Slide the sheet in. Idempotent. */
+    open(): void;
+    /** Slide the sheet out and restore focus. Idempotent. */
+    close(): void;
+    /** Confirm and close. */
+    confirm(): void;
+    /** Cancel and close. */
+    cancel(): void;
+    /** Whether the sheet is on screen. */
+    get isOpen(): boolean;
+    /** The body element, for callers that fill it after construction. */
+    get content(): HTMLElement;
+    destroy(): void;
+}

package/dist/overlays/toast.d.ts

@@ -0,0 +1,37 @@
+import { Component } from "../component";
+import "./toast.css";
+export type ToastVariant = "default" | "success" | "error";
+export interface ToastOptions {
+    message?: string;
+    /** Secondary line under the message. */
+    detail?: string;
+    /** Auto-dismiss delay in ms; 0 keeps it until dismissed. */
+    duration?: number;
+    variant?: ToastVariant;
+}
+/**
+ * A macOS-style toast.
+ *
+ * Announced through `role="status"` with `aria-live="polite"`, so screen
+ * readers read it without stealing focus from whatever the user is doing.
+ */
+export declare class Toast extends Component<HTMLDivElement> {
+    protected readonly root: HTMLDivElement;
+    private readonly messageNode;
+    private readonly detailNode;
+    private duration;
+    private timer;
+    private visible;
+    constructor(options?: ToastOptions);
+    /** Show the toast, replacing its text. Mounts itself into the shared stack. */
+    show(message?: string, detail?: string): void;
+    /** Update the auto-dismiss delay for subsequent shows. */
+    setDuration(duration: number): void;
+    /** Dismiss immediately. */
+    hide(): void;
+    private scheduleDismiss;
+    private clearTimer;
+    destroy(): void;
+}
+/** Fire-and-forget helper for the common case. */
+export declare function showToast(message: string, options?: Omit<ToastOptions, "message">): Toast;

package/dist/overlays/tooltip.d.ts

@@ -0,0 +1,48 @@
+import { Component } from "../component";
+import { type Placement } from "../overlay";
+import "./tooltip.css";
+export interface TooltipOptions {
+    content: string;
+    placement?: Placement;
+    /** Delay before showing, in ms. macOS uses a noticeable pause. */
+    delay?: number;
+}
+/**
+ * A macOS tooltip.
+ *
+ * Two things make tooltips usable that hand-written ones usually miss:
+ *
+ * 1. **Focus triggers it too.** Keyboard and screen-reader users never hover,
+ *    so the tooltip opens on focus as well and the trigger is linked with
+ *    `aria-describedby`.
+ * 2. **The delay cancels.** A quick pointer sweep across a toolbar must not
+ *    flash a tooltip on every button, so leaving clears the pending timer.
+ */
+export declare class Tooltip extends Component<HTMLDivElement> {
+    protected readonly root: HTMLDivElement;
+    private readonly content;
+    private readonly placement;
+    private readonly delay;
+    private trigger;
+    private disposeTracking;
+    private showTimer;
+    private visible;
+    /**
+     * Listeners bound to the current trigger. Tracked separately from the
+     * component's own list because `attachTo` can rebind many times over one
+     * component's life; `listen()` alone would accumulate every binding.
+     */
+    private triggerListeners;
+    constructor(options: TooltipOptions);
+    /** Bind the tooltip to an element. A tooltip serves one trigger at a time. */
+    attachTo(trigger: HTMLElement): void;
+    /** Unbind from the current trigger and remove the tooltip. */
+    detach(): void;
+    private schedule;
+    private cancelTimer;
+    /** Show the bubble next to the trigger. */
+    open(): void;
+    /** Hide the bubble. */
+    close(): void;
+    destroy(): void;
+}

package/dist/style.css.d.ts

@@ -0,0 +1,2 @@
+/** Side-effect only stylesheet. Import it once, for its rules. */
+export {};

package/dist/theme.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Runtime theme system.
+ *
+ * Two-layer tokens (see tokens.css) split the problem in half:
+ *
+ *  - The built-in `macos-dark` / `macos-light` appearances are **pure CSS**. They
+ *    apply through `[data-appearance]` with no JavaScript at all, so the first
+ *    paint is already correct — a theme applied by script would flash the wrong
+ *    colours for one frame.
+ *
+ *  - Everything else is a *custom* theme: an appearance plus a handful of
+ *    semantic-token overrides. Overrides land as inline custom properties on
+ *    <html>, which beat the stylesheet, so a brand theme ships 3 values instead
+ *    of 60.
+ *
+ * The rule that keeps this honest: custom themes may only override **semantic**
+ * tokens (`accent`, `bg-window`, …), never base ones (`base-gray-800`). Base
+ * tokens are shared by both appearances; overriding one would silently damage
+ * the other.
+ */
+export type Appearance = "light" | "dark";
+export interface ThemeDefinition {
+    /** Unique name, written to `data-theme`. */
+    name: string;
+    /** Which built-in appearance the theme starts from. */
+    appearance: Appearance;
+    /**
+     * Semantic-token overrides. Keys are written **without** the `--mac-`
+     * prefix for brevity, e.g. `{accent: "#ff6b35"}` not
+     * `{"--mac-accent": "#ff6b35"}`.
+     */
+    tokens?: Record<string, string>;
+}
+/** The built-in appearances. No tokens: their values live in tokens.css. */
+export declare const BUILTIN_THEMES: ThemeDefinition[];
+/**
+ * Owns the appearance on <html> and any custom-token overrides.
+ *
+ * One instance per document; `themeManager` below is the shared one.
+ */
+export declare class ThemeManager {
+    private readonly root;
+    private readonly themes;
+    /** Custom properties this manager wrote, so they can be removed cleanly. */
+    private applied;
+    private current;
+    private mediaQuery;
+    private systemListener;
+    private listeners;
+    constructor(root?: HTMLElement);
+    /** Register a custom theme. Throws on an empty or duplicate name. */
+    register(theme: ThemeDefinition): void;
+    /** Remove a custom theme. Built-in appearances cannot be removed. */
+    unregister(name: string): void;
+    /** Names of every registered theme. */
+    list(): string[];
+    /** The theme currently applied. */
+    get active(): ThemeDefinition;
+    /**
+     * Apply a theme by name.
+     *
+     * Applies the appearance first (pure CSS takes over), then the token
+     * overrides. Re-applying the same theme is a no-op when nothing changed.
+     */
+    apply(name: string): void;
+    /**
+     * Follow the OS appearance: dark when the system is dark, light otherwise.
+     * Re-applies automatically when the user flips the system setting.
+     */
+    followSystem(): void;
+    /** True while the OS appearance drives the theme. */
+    get isFollowingSystem(): boolean;
+    /** Subscribe to theme changes. Returns an unsubscribe function. */
+    onChange(listener: (theme: ThemeDefinition) => void): () => void;
+    /**
+     * Export the active theme as a definition.
+     *
+     * Reads the computed custom properties, so it captures values that came from
+     * the stylesheet as well as inline overrides — useful for "save this look".
+     */
+    exportActive(): ThemeDefinition;
+    /** Drop listeners. Call when tearing the app down. */
+    destroy(): void;
+    private applyDefinition;
+    /** Remove every inline custom property this manager wrote. */
+    private clearOverrides;
+    private stopFollowingSystem;
+}
+/** The application-wide theme manager. */
+export declare const themeManager: ThemeManager;
+/**
+ * Set the density preset ("compact" | "comfortable" | "touch").
+ *
+ * Density is pure CSS: it only moves `--mac-scale`, which every scalable token
+ * multiplies. Removing the attribute hands control back to the media query that
+ * enlarges controls on touch devices.
+ */
+export declare function setDensity(density: "compact" | "comfortable" | "touch" | null): void;
+/** The density currently in effect, including the automatic touch default. */
+export declare function getDensity(): string;

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@leef-l/macos-ui-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "macOS-style UI components in dependency-free TypeScript, for Wails v3 desktop apps and plain web pages",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "macos",
+    "ui",
+    "components",
+    "vanilla",
+    "typescript",
+    "wails"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leef-l/macos-ui-kit.git",
+    "directory": "packages/macos-ui-kit"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": {
+      "types": "./dist/style.css.d.ts",
+      "default": "./dist/macos-ui-kit.css"
+    },
+    "./global": "./dist/macos-ui-kit.iife.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.css",
+    "src/index.ts",
+    "dist/index.js"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json && node scripts/finalize-dist.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vite": "^8.2.4"
+  }
+}