@wildwinter/app-shell 0.1.0 → 0.14.0

package/dist/index.d.cts

@@ -1,11 +1,35 @@
+export { EDIT_MENU, MenuLabel, PANE_MENU } from './menu.cjs';
+export { JOB_PROGRESS, JobProgress } from './job.cjs';
+
 type Child = Node | string | null | undefined;
 interface ElProps {
     className?: string;
     text?: string;
+    /** A NATIVE rollover. Prefer `tip`: `title` is OS chrome on the platform's own
+     *  slow delay, which is the seam the themed tooltip exists to close. */
     title?: string;
+    /** A themed rollover (`data-tip`, picked up by the delegated controller that
+     *  `initTooltips()` wires). Also the accessible name, since the elements that
+     *  want one are usually icon buttons with no text of their own. */
+    tip?: string;
     onClick?: (event: MouseEvent) => void;
 }
 declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, classNameOrProps?: string | ElProps, ...children: Child[]): HTMLElementTagNameMap[K];
+/** A small square glyph button (the move/delete controls list editors share).
+ *  Its rollover is the THEMED one (`data-tip`), so an app that has called
+ *  `initTooltips()` gets our bubble rather than the platform's. */
+declare function iconBtn(glyph: string, title: string, onClick: () => void, disabled?: boolean, danger?: boolean): HTMLButtonElement;
+/** A captioned field: `<label class="shell-labelled"><span class="shell-fieldcap">…</span>control</label>`. */
+declare function labelled(label: string, control: HTMLElement): HTMLElement;
+/** Swap item `i` with its neighbour `i + delta` IN PLACE (the up/down reorder list editors share);
+ *  a no-op when the target is out of range. Returns whether anything moved. */
+declare function moveItem<T>(arr: T[], i: number, delta: number): boolean;
+/** A tag-style editor for a string-list field (an enum's allowed values / flags): removable chips + an
+ *  add input (Enter or "," commits; blank / duplicate ignored). Mutates `holder.values` in place (read
+ *  back on save). `onChange` fires after any add / remove so callers can refresh a dependent control. */
+declare function tagChips(holder: {
+    values?: string[];
+}, onChange?: () => void): HTMLElement;
 
 /** Curated colour slots; must match the `--char-*` set defined per theme. */
 declare const PALETTE_SIZE = 12;
@@ -16,4 +40,467 @@ declare function colourIndex(name: string): number;
 /** The theme-aware CSS variable reference for a name's slot. */
 declare function colourFor(name: string): string;
 
-export { type Child, type ElProps, PALETTE, PALETTE_SIZE, colourFor, colourIndex, el };
+/**
+ * Named by what it MEANS. Grouped by the job, because that is how a caller
+ * looks for one.
+ */
+declare const icon: {
+    /** Close a panel, a dialog, a popover. Patterpad's, twelve times over. */
+    readonly close: "✕";
+    /** The overflow menu on a document or a row: "more about this". */
+    readonly more: "⋯";
+    /** Collapsed disclosure, pointing at what would open. */
+    readonly collapsed: "▸";
+    /** Expanded disclosure. */
+    readonly expanded: "▾";
+    /** A dropdown's affordance, where it is not a real <select>. */
+    readonly dropdown: "▾";
+    /** Back / previous, in a breadcrumb or a stepper. */
+    readonly back: "‹";
+    /** Forward / next. */
+    readonly forward: "›";
+    /** Up one, in a list. */
+    readonly up: "↑";
+    /** Down one. */
+    readonly down: "↓";
+    /** Done, applied, agreed. */
+    readonly tick: "✓";
+    /** Somebody else holds this: the version-control lock. */
+    readonly locked: "⊘";
+    /** Read-only on disk with no other holder: the resting state of everything
+     *  in a lock-based working copy that nobody has checked out yet. */
+    readonly readOnly: "○";
+    /** Something needs attention but is not fatal. */
+    readonly warning: "‼";
+    /** A live thing: the running position, an active marker. */
+    readonly dot: "●";
+    /** Play, in the sense of "run this". */
+    readonly play: "▶";
+    /** The drag grip on a reorderable row. */
+    readonly grip: "⠿";
+    /** Add one of whatever this list holds. */
+    readonly add: "+";
+    /** Documentation notes: the pencil. Both apps had chosen it independently,
+     *  which is the happiest way for a vocabulary entry to arrive. */
+    readonly note: "✎";
+    /** A comment thread. Speech, not a pencil: documentation states the reason,
+     *  comments are the conversation, and the two must never look alike. */
+    readonly comment: "❝";
+};
+type IconName = keyof typeof icon;
+/**
+ * The few shapes no glyph says honestly, as inline SVG.
+ *
+ * `currentColor` throughout, so they take the colour of the button they sit in
+ * exactly as the glyphs do, and sized in the markup for the same reason: an icon
+ * that needs a CSS rule to be the right size is an icon that will be the wrong
+ * size somewhere.
+ *
+ * Lifted from Patterpad, which drew them first.
+ */
+declare const iconSvg: {
+    /** A document with lines: notes exist on this thing. */
+    readonly noteFilled: "<svg viewBox=\"0 0 16 16\" width=\"13\" height=\"13\" fill=\"currentColor\" fill-rule=\"evenodd\" aria-hidden=\"true\"><path d=\"M3.4 1.4h5.3L12.6 5.3v8.1a1.2 1.2 0 0 1-1.2 1.2H3.4a1.2 1.2 0 0 1-1.2-1.2V2.6A1.2 1.2 0 0 1 3.4 1.4ZM4.9 6.8h6.2v1.1H4.9Zm0 2.1h6.2v1.1H4.9Zm0 2.1h3.7v1.1H4.9Z\"/></svg>";
+    /** The same document, empty: nothing written here yet. */
+    readonly noteOutline: "<svg viewBox=\"0 0 16 16\" width=\"13\" height=\"13\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.1\" stroke-linejoin=\"round\" stroke-linecap=\"round\" aria-hidden=\"true\"><path d=\"M3.4 2h4.9l3.9 3.9v7.5a1 1 0 0 1-1 1H3.4a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1Z\"/><path d=\"M8.3 2.2v3.8h3.8\"/><path d=\"M4.9 8h6.2M4.9 10h6.2M4.9 12h3.7\" stroke-width=\"0.95\"/></svg>";
+};
+type IconSvgName = keyof typeof iconSvg;
+
+type PaneSide = "nav" | "inspector";
+interface PaneSideConfig {
+    /** The open width as a CSS length, e.g. "14rem" or "224px". */
+    defaultWidth: string;
+    /** Drag floor in px (default 160). */
+    minWidth?: number;
+    /** Drag ceiling in px from the window width (default w => min(640, w - 420)). */
+    maxWidth?: (innerWidth: number) => number;
+    /** Whether a drag seam is offered (default true). */
+    resizable?: boolean;
+    /** Noun for the toggle's tooltip/aria, e.g. "navigator" / "inspector". */
+    label?: string;
+    /** Shortcut hint appended to the tooltip, e.g. "Cmd+1". */
+    shortcutHint?: string;
+}
+interface PaneShellState {
+    open: Record<PaneSide, boolean>;
+    /** Dragged widths in px; absent = the config default. */
+    width: Partial<Record<PaneSide, number>>;
+}
+interface PaneShellOptions {
+    nav: PaneSideConfig;
+    inspector: PaneSideConfig;
+    /** Initial open + width state (from the host's store). */
+    initial?: Partial<PaneShellState>;
+    /** Persist state after any toggle or resize (host wires it to its store). */
+    onChange?: (state: PaneShellState) => void;
+}
+interface PaneShell {
+    /** The frame element (top bar + panes); mount it into the app container. */
+    readonly root: HTMLElement;
+    readonly topbar: HTMLElement;
+    /** Top-bar host slots: leading (title) and trailing (status), the host fills. */
+    readonly topbarLead: HTMLElement;
+    readonly topbarTrail: HTMLElement;
+    /** Pane bodies the host fills (the fixed-width inner that clips on collapse). */
+    readonly nav: HTMLElement;
+    readonly centre: HTMLElement;
+    readonly inspector: HTMLElement;
+    togglePane(side: PaneSide): void;
+    setPaneOpen(side: PaneSide, open: boolean): void;
+    isOpen(side: PaneSide): boolean;
+    /** Clear dragged widths back to the config defaults. */
+    resetWidths(): void;
+    /** A snapshot of the current state (open + widths). */
+    state(): PaneShellState;
+    destroy(): void;
+}
+declare function mountPaneShell(host: HTMLElement, opts: PaneShellOptions): PaneShell;
+
+/** A compact list row: a single `.set-rowline` (inline controls) plus, when
+ *  `details` are given, a disclosure that reveals a `.set-details` panel below,
+ *  so a list scans like a table with secondary fields tucked away. */
+declare function expandableRow(opts: {
+    line: HTMLElement[];
+    details?: HTMLElement[];
+}): HTMLElement;
+/** After a "+ Add" re-renders a list, bring the new (last) row into view and
+ *  focus its name input (`.set-name`, else the first input). */
+declare function focusNewRow(listEl: HTMLElement | null | undefined): void;
+interface DupGuard {
+    /** Forget the previous render's inputs (call at the top of render). */
+    reset(): void;
+    /** Register a name input; `key` returns the comparison string (default the
+     *  input's value). Re-checks live on input. `also` = extra inputs that change the key. */
+    track(input: HTMLInputElement, key?: () => string, also?: HTMLInputElement[]): void;
+    /** Re-paint duplicates; true if any two non-blank keys collide. */
+    check(): boolean;
+    /** The first input currently flagged (after a fresh check), or null. */
+    firstDuplicate(): HTMLInputElement | null;
+}
+/** Case-insensitive duplicate-name detection: paints clashing inputs `.invalid`
+ *  and lets a Save gate block + jump via `firstDuplicate()`. */
+declare function dupGuard(): DupGuard;
+interface SettingsSectionHandle {
+    /** The first invalid control to jump to, blocking Save (e.g. a duplicate name). */
+    firstInvalid?(): HTMLElement | null;
+}
+interface SettingsSection {
+    id: string;
+    label: string;
+    /** Optional left-rail group heading above this tab. */
+    group?: string;
+    /** Build the section body into `host`; called fresh on each open so it reads
+     *  the current data. Return a handle (for the Save gate). */
+    mount(host: HTMLElement): SettingsSectionHandle;
+}
+interface SettingsDialogOptions {
+    title: string;
+    sections: SettingsSection[];
+    /** Fired when Save is clicked and every section validates. The app reads its
+     *  own section state and persists. May be async; the dialog stays open until
+     *  it resolves, then closes. */
+    onSave: () => void | Promise<void>;
+}
+interface SettingsDialog {
+    /** Open (optionally on a given tab id). Sections re-mount from current data. */
+    open(tabId?: string): void;
+    destroy(): void;
+}
+/** Build a settings dialog. The frame owns the modal, the tab rail, save-on-Save
+ *  (with a validation gate), and Cancel; the sections own their content + state. */
+declare function mountSettingsDialog(opts: SettingsDialogOptions): SettingsDialog;
+
+interface PinButtonOptions {
+    pinned: boolean;
+    /** Persist the choice (the button keeps its own visual state). */
+    onToggle: (on: boolean) => void;
+}
+/** The always-on-top pin: `.swin-pin`, aria-pressed, and a tooltip that says
+ *  what a click will do (the richest of the family's variants, kept). */
+declare function pinButton(opts: PinButtonOptions): HTMLButtonElement;
+
+interface ConfirmOptions {
+    title: string;
+    body: string;
+    /** The destructive button's label ("Delete box", "Restart"). */
+    confirmLabel: string;
+}
+/** Resolves true on confirm; false on Cancel / Esc / backdrop. */
+declare function confirmDialog(opts: ConfirmOptions): Promise<boolean>;
+
+interface AboutOptions {
+    /** The product's name, large. */
+    appName: string;
+    /** "1.4.2" - shown as "Version 1.4.2". */
+    version: string;
+    /** One or two sentences: what this app is for. */
+    blurb?: string;
+    /** Licence, authorship, the suite it belongs to. Newlines are respected. */
+    credits?: string;
+    links?: {
+        label: string;
+        url: string;
+    }[];
+    /** Inline SVG for the product wordmark, if it has one. */
+    wordmark?: string;
+    /** Open a URL in the real browser. Omit and the links render as text. */
+    onOpenLink?: (url: string) => void;
+}
+/** Show the About dialog. Resolves when it closes. */
+declare function showAbout(opts: AboutOptions): Promise<void>;
+
+interface AnchoredPanel {
+    panel: HTMLElement;
+    /** The content area to populate: the header is built for you. */
+    body: HTMLElement;
+    /** Idempotent; fires the caller's `onClose` exactly once. */
+    close: () => void;
+}
+interface AnchoredPanelOptions {
+    anchor: HTMLElement;
+    /** Extra class(es) on the panel, for app-specific sizing or colour. */
+    className?: string;
+    title: string;
+    width: number;
+    /**
+     * Which side to try first.
+     *
+     * `"left"` suits a panel hung off a row in a right-hand pane (Patterpad's
+     * inspector); `"below"` suits one hung off a button in a document's header
+     * (Storyletter's topline). Either way it flips when the room is not there.
+     */
+    prefer?: "left" | "below";
+    /** Selectors for chrome the panel must not cover - a problems bar, a review
+     *  bar - so those stay usable while it is open. */
+    keepClear?: string[];
+    /** A pointerdown inside something matching this does NOT close the panel. */
+    ignoreDown?: string;
+    /** While something matching this exists, Escape belongs to it, not to us. */
+    deferEscape?: string;
+    onClose?: () => void;
+}
+declare function openAnchoredPanel(opts: AnchoredPanelOptions): AnchoredPanel | null;
+/** Close whatever is open. For a navigation or a re-render: a panel anchored to
+ *  an element that no longer exists would hang in the air. */
+declare function closeAnchoredPanel(): void;
+/** Patterpad's placement, with the side as a parameter. */
+declare function placeAnchored(panel: HTMLElement, anchor: HTMLElement, width: number, prefer: "left" | "below", keepClear: string[]): void;
+
+/** One shard's state as the renderer sees it. The app's own DTO will be this
+ *  shape (it crosses its own bridge); this is what the view needs. */
+interface ShardVc {
+    key: string;
+    writable: boolean;
+    lockedBy?: string[];
+    outOfDate?: boolean;
+}
+/** A snapshot, keyed by shard key. Absent = clean, writable, up to date. */
+type VcMap = ReadonlyMap<string, ShardVc>;
+/** Fold the state of the shard key(s) an item stands for (a box row spans its
+ *  box + tags + hands shards), most actionable winning: any holder locks it,
+ *  any stale shard makes it stale, any read-only shard makes it read-only. */
+declare function foldVc(shards: VcMap, keys: string | undefined): ShardVc | undefined;
+/** The one badge an item flies, by priority, or null when there is nothing to
+ *  say. Monochrome typographic glyphs (never colour emoji), so each inherits
+ *  its themed colour and reads the same in Linen and Baize. */
+declare function vcBadgeFor(s: ShardVc | undefined): {
+    glyph: string;
+    cls: string;
+    title: string;
+} | null;
+/** Repaint the badge on every item under `root` that names a shard (its
+ *  `data-vc`). In place: no re-render, so nothing loses focus or scroll. */
+declare function paintVcBadges(root: ParentNode, shards: VcMap): void;
+/** Turn a region's editing controls off - or back on, but only the ones WE
+ *  turned off, so a control disabled for its own reasons (the first card's
+ *  "previous", a redraw-turns box on "always") stays disabled. */
+declare function lockControls(host: HTMLElement, off: boolean, staysLive: string): void;
+/** The notice a locked document opens with: who holds it, and why nothing types. */
+declare function lockNotice(holders: string[]): HTMLElement;
+
+interface Identity {
+    name: string;
+    email?: string;
+}
+interface IdentityOptions {
+    /** What it already says, if anything. */
+    current?: Identity;
+    /** A name to offer when there is none: the VCS's, one day. */
+    suggested?: Identity;
+}
+/** Ask, and record the answer. Resolves when the dialog closes, either way. */
+declare function askIdentity(opts?: IdentityOptions): Promise<Identity | undefined>;
+
+/** One line of documentation. `type` names its class; absent = editor-only. */
+interface DocLine {
+    type?: string;
+    text: string;
+}
+/** What applies to one thing: its own notes, and the ancestors' that reach it.
+ *  Inherited notes are READ-ONLY - they are edited where they live, which is
+ *  what stops a note being copied down and then disagreeing with itself. */
+interface Notes {
+    own: DocLine[];
+    inherited: {
+        id: string;
+        label: string;
+        lines: DocLine[];
+    }[];
+    /** The classes this app offers, in the order they should appear. */
+    classes: string[];
+}
+interface NotesEditorOptions {
+    /** What this is about, for the dialog's title ("Notes: Arrive at the gate"). */
+    subject: string;
+    notes: Notes;
+    /** Commit. Called once, on close, and only when something changed. */
+    save: (lines: DocLine[]) => void;
+}
+/** Open the notes modal. Resolves when it closes. */
+declare function openNotesEditor(opts: NotesEditorOptions): void;
+
+/** One message. The author is a NAME stamped at posting time, not a reference:
+ *  people leave projects and their words stay. */
+interface CommentMessage {
+    author: string;
+    ts: string;
+    body: string;
+}
+/** A thread, anchored to the id of whatever it is about. */
+interface Comment {
+    id: string;
+    anchor: string;
+    resolved?: boolean;
+    messages: CommentMessage[];
+}
+interface CommentsOptions {
+    anchor: HTMLElement;
+    /** What is being discussed, for the panel's title. */
+    subject: string;
+    /** Every thread on this thing, resolved ones included. */
+    threads: Comment[];
+    /** Review ▸ Show Resolved Comments. */
+    showResolved: boolean;
+    /** A fresh thread id, minted by the caller so main never has to. */
+    newThreadId: () => string;
+    post: (threadId: string, body: string) => void;
+    setResolved: (threadId: string, resolved: boolean) => void;
+}
+declare function openComments(opts: CommentsOptions): void;
+
+interface JobProgressView {
+    /** The strip; mount it where the job belongs. */
+    readonly element: HTMLElement;
+    /** Show the strip, reset to zero, and (optionally) name what is running. */
+    begin(label?: string): void;
+    /** Feed it a progress message from the main-side host. */
+    update(done: number, total: number, elapsedMs: number): void;
+    /** Hide the strip (the job finished, failed, or was cancelled). */
+    end(): void;
+    readonly visible: boolean;
+}
+interface JobProgressOptions {
+    /** Called when Cancel is clicked. The button disables itself and says so;
+     *  the job stops at its next yield, and the host then calls end(). */
+    onCancel: () => void;
+    /** The word for the units, for the count readout (default "runs"). */
+    units?: string;
+}
+declare function mountJobProgress(host: HTMLElement, opts: JobProgressOptions): JobProgressView;
+
+/** Wrap `s` so it renders bold inside a tooltip (see the marker note above). */
+declare function tipBold(s: string): string;
+interface TooltipOptions {
+    /** Called before every show: return true to keep the bubble down. For a mode
+     *  that wants no chrome at all (Patterpad's Writing View). */
+    suppressed?: () => boolean;
+}
+/** A rectangle in VIEWPORT coordinates, for anchoring a tip to something that is
+ *  not a DOM element: a shape on a canvas, a run of text inside one. */
+interface TipRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Show a tip for something that has no DOM node of its own: a card on a canvas,
+ * a zone, a pin. The caller says WHERE (a viewport rectangle) and WHAT, and
+ * identifies the subject with `key`.
+ *
+ * The key is what makes this usable from a canvas. Re-calling with the same key
+ * re-places the bubble WITHOUT restarting the delay, so a tip can follow its
+ * shape while the camera moves; calling with a different key starts the wait
+ * again, so sweeping the pointer across a dense board does not strobe.
+ *
+ * The bubble is ordinary DOM, so it holds its size whatever the canvas is
+ * zoomed to. That is the point of it: the label it stands in for is the one
+ * thing on a canvas that must not shrink with everything else.
+ */
+declare function tipAt(key: string, rect: TipRect, text: string): void;
+/** Take any tip down: the pointer has left, or a gesture has started. */
+declare function hideTip(): void;
+/** Wire the one delegated controller. Idempotent; later options are ignored. */
+declare function initTooltips(opts?: TooltipOptions): void;
+
+/**
+ * Three states, not a boolean.
+ *
+ * "saving" earns its place: on a slow disk or a slow VC hook a save takes long
+ * enough to see, and a status that flips straight from unsaved to saved leaves
+ * the author wondering whether the click did anything.
+ */
+type SaveStatus = "saved" | "unsaved" | "saving";
+interface SaveControllerOptions {
+    /**
+     * Write whatever is pending. Return false if it failed: the controller stays
+     * "unsaved" and will try again on the next touch or flush, rather than
+     * quietly reporting success over a write that did not happen.
+     *
+     * Called only when something is pending, and never twice at once.
+     */
+    write: () => Promise<boolean> | boolean;
+    /** Told every time the status changes, and only when it changes. */
+    onStatus?: (status: SaveStatus) => void;
+    /** How long after the last edit to write. Storyletter's 700ms by default. */
+    delayMs?: number;
+    /**
+     * The longest an edit may go unwritten while more keep arriving.
+     *
+     * This is the interval half of the two apps put back in: without it, steady
+     * typing defers the write for as long as the typing lasts.
+     */
+    maxWaitMs?: number;
+}
+interface SaveController {
+    /** What the indicator should say. */
+    readonly status: SaveStatus;
+    /** Is anything unwritten? For a close guard, or an updater asking whether it
+     *  may restart. True while a write is in flight, too: it is not on disk yet. */
+    readonly pending: boolean;
+    /** Something changed. Starts (or extends) the countdown. */
+    touch(): void;
+    /**
+     * Write now, and wait for it.
+     *
+     * Call on every transition that must see current bytes: switching what is
+     * being edited, opening a tool window that reads the disk, closing the
+     * window, Cmd+S. Safe to call when nothing is pending (it does nothing) and
+     * safe to call during a write (it waits for it, then writes again if more
+     * arrived while it ran).
+     */
+    flush(): Promise<void>;
+    /** Give up on what is pending without writing it. For a project close after
+     *  the author has said to discard, and for teardown. */
+    cancel(): void;
+    /**
+     * Autosave on or off (Patterpad's per-project setting).
+     *
+     * Off does not mean "never write": touch() still marks the work unsaved, and
+     * flush() still writes on transitions and on Cmd+S. It only stops the clock.
+     */
+    setAuto(on: boolean): void;
+}
+declare function createSaveController(opts: SaveControllerOptions): SaveController;
+
+export { type AboutOptions, type AnchoredPanel, type AnchoredPanelOptions, type Child, type Comment, type CommentMessage, type CommentsOptions, type ConfirmOptions, type DocLine, type DupGuard, type ElProps, type IconName, type IconSvgName, type Identity, type IdentityOptions, type JobProgressOptions, type JobProgressView, type Notes, type NotesEditorOptions, PALETTE, PALETTE_SIZE, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButtonOptions, type SaveController, type SaveControllerOptions, type SaveStatus, type SettingsDialog, type SettingsDialogOptions, type SettingsSection, type SettingsSectionHandle, type ShardVc, type TipRect, type TooltipOptions, type VcMap, askIdentity, closeAnchoredPanel, colourFor, colourIndex, confirmDialog, createSaveController, dupGuard, el, expandableRow, focusNewRow, foldVc, hideTip, icon, iconBtn, iconSvg, initTooltips, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openNotesEditor, paintVcBadges, pinButton, placeAnchored, showAbout, tagChips, tipAt, tipBold, vcBadgeFor };