@wildwinter/app-shell 0.4.1 → 0.15.0

package/dist/index.d.cts

@@ -1,14 +1,23 @@
-export { MenuLabel, PANE_MENU } from './menu.cjs';
+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). */
+/** 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;
@@ -31,6 +40,72 @@ declare function colourIndex(name: string): number;
 /** The theme-aware CSS variable reference for a name's slot. */
 declare function colourFor(name: string): string;
 
+/**
+ * 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". */
@@ -135,4 +210,355 @@ interface SettingsDialog {
  *  (with a validation gate), and Cancel; the sections own their content + state. */
 declare function mountSettingsDialog(opts: SettingsDialogOptions): SettingsDialog;
 
-export { type Child, type DupGuard, type ElProps, PALETTE, PALETTE_SIZE, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type SettingsDialog, type SettingsDialogOptions, type SettingsSection, type SettingsSectionHandle, colourFor, colourIndex, dupGuard, el, expandableRow, focusNewRow, iconBtn, labelled, mountPaneShell, mountSettingsDialog, moveItem, tagChips };
+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" | "centre";
+    /** 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" | "centre", keepClear: string[]): void;
+
+/**
+ * Slugify a name into hyphen form: lower case, apostrophes dropped, runs of
+ * anything else to a single hyphen, no leading or trailing hyphen.
+ *
+ * May return "", when there was nothing usable in the input. Callers treat that
+ * as "no pinned address" rather than as an address.
+ */
+declare function gameIdify(text: string): string;
+/** Is this a legal address? Lower case, digits and hyphens, starting and ending
+ *  with a letter or a digit. Note "" is NOT legal: an empty pinned address means
+ *  "derive one", which is a different thing from an address. */
+declare function isValidGameId(gameId: string): boolean;
+
+interface GameIdEditorOptions {
+    anchor: HTMLElement;
+    /** The pinned address, or "" when it is being derived. */
+    value: string;
+    /** What it derives to, shown as the placeholder. */
+    derived: string;
+    /** Persist. "" means "stop pinning, go back to deriving". */
+    onCommit: (gameId: string) => void;
+    /** The panel's title. Both apps say "Game ID"; a third may not. */
+    title?: string;
+    /** Override the rules. Defaults are the shell's, which is what a new app
+     *  should use; an app whose domain layer owns them can pass its own. */
+    slugify?: (text: string) => string;
+    validate?: (gameId: string) => boolean;
+    /** Where the panel goes, for hosts that anchor it somewhere tight. */
+    prefer?: "left" | "below" | "centre";
+}
+/**
+ * Open it. Returns false when that click TOGGLED the panel shut, which is the
+ * anchored panel's contract and worth passing on: a caller that repaints on open
+ * needs to know it did not.
+ */
+declare function openGameIdEditor(opts: GameIdEditorOptions): boolean;
+
+/** 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 TOMBSTONE: the words are gone, the turn in the conversation is not.
+     *  Deleting a reply out of a thread would renumber the argument around it, so
+     *  what is left says who spoke and when and that they withdrew it. The body is
+     *  emptied on the way out, so "deleted" means deleted from the file too. */
+    deleted?: boolean;
+}
+/** 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;
+    /**
+     * Withdraw one message. Absent = the host does not offer deletion.
+     *
+     * By INDEX, because a message has no id of its own and giving every message
+     * one would be a format change to every stored thread for the sake of one
+     * verb. The index is read off the list the reader is looking at, and these
+     * files are edited by one person at a time with a VCS underneath.
+     *
+     * The host decides what deleting MEANS: the agreed rule is that the message
+     * becomes a tombstone, and the whole thread goes when nothing readable would
+     * be left (which covers the common case of withdrawing a comment nobody had
+     * replied to).
+     */
+    deleteMessage?: (threadId: string, index: number) => void;
+    /** Where the panel sits: "centre" for a point on a canvas (see anchored.ts). */
+    prefer?: "left" | "below" | "centre";
+}
+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 GameIdEditorOptions, 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, gameIdify, hideTip, icon, iconBtn, iconSvg, initTooltips, isValidGameId, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, showAbout, tagChips, tipAt, tipBold, vcBadgeFor };