@wildwinter/app-shell 0.38.0 → 0.40.0

package/dist/property-list-D3VZCJzi.d.ts

@@ -0,0 +1,162 @@
+/** 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. `name` is
+ *  what the row declares (a property's name, a field's), stamped on it as
+ *  `data-name` so `revealRow` can land on it. */
+declare function expandableRow(opts: {
+    line: HTMLElement[];
+    details?: HTMLElement[];
+    name?: string;
+}): HTMLElement;
+/**
+ * Land on one row of a list by the `name` it was built with: open its details
+ * (an enum's values sit behind the disclosure, and they are usually what the
+ * jump was for), bring it to the middle of its scroller, and light it for a
+ * moment (`.set-row.landed` in settings.css). "Go to definition" in both apps
+ * used to open the page a property is declared on and stop there, with the
+ * declaration below the fold and nothing marking it (Storyletter, 2026-09-14).
+ *
+ * Returns false when no row carries the name, so a host whose page fills in
+ * asynchronously can ask again on a later frame; asking again is the host's,
+ * since only the host knows what opens on its own time. The row is matched by
+ * reading the stamp rather than by an attribute selector, so a name needs no
+ * escaping.
+ */
+declare function revealRow(within: ParentNode, name: string): boolean;
+/**
+ * `revealRow`, retried over the next frames until the row exists or the tries
+ * run out: for a page that fills in on its own time after a navigation. Both
+ * apps hand-rolled this as `landOn` with the same twelve tries
+ * (ui-review-2026-09, finding 29). Resolves true when it landed, false when it
+ * gave up, and giving up is quiet: a name no page shows as a row is not a fault.
+ */
+declare function revealRowWhenReady(within: ParentNode, name: string, tries?: number): Promise<boolean>;
+/** 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). Return `{ el, message }` to say WHICH fault in the error line;
+     *  a bare element says it through its own `data-tip` (the dup guard's, a
+     *  property-name field's), and the line falls back to a generic sentence
+     *  when it has neither. */
+    firstInvalid?(): HTMLElement | {
+        el: HTMLElement;
+        message?: string;
+    } | 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;
+    /** Why this tab cannot be used right now, or null when it can. A reason
+     *  renders the tab dimmed and inert with the reason as its rollover
+     *  (Patterpad's Audio tab while the project is not voiced). Read on open
+     *  and on `refreshTabs()`, so a control inside the dialog can flip it. */
+    disabled?: () => string | null;
+}
+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;
+    /** Re-read every section's `disabled()`; a tab that has just become
+     *  disabled while showing hands over to the first usable one. */
+    refreshTabs(): 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;
+
+/** The six types both apps declare. */
+type PropertyListType = "number" | "boolean" | "string" | "enum" | "flags" | "quality";
+/** The shape a row edits. Apps' DTOs carry more (shared, writable, durable);
+ *  those ride through untouched. */
+interface PropertyDeclLike {
+    name: string;
+    type: string;
+    default?: unknown;
+    /** enum / flags */
+    values?: string[];
+    /** quality: the ladder, in order */
+    stages?: string[];
+    purpose?: string;
+}
+/** The type list, in the family's order, with the words the select shows. */
+declare const PROPERTY_TYPES: ReadonlyArray<readonly [PropertyListType, string]>;
+interface DefaultControlOptions {
+    /**
+     * How the default is stored. `false` (default): the string the field shows,
+     * "" for none (Storyletter's DTO). `true`: a typed value (boolean, number,
+     * string), and none DELETES the key (Patterpad's model).
+     */
+    typed?: boolean;
+}
+/**
+ * The type-appropriate control for a declaration's DEFAULT: a true / false
+ * picker for a boolean, the value list for an enum, the stage list for a
+ * quality (blank = the first rung), a note for flags (a set starts empty), a
+ * number or text field otherwise. The one label for "no default" is "(none)".
+ */
+declare function defaultControl(p: PropertyDeclLike, onChange?: () => void, opts?: DefaultControlOptions): HTMLElement;
+interface PropertyListOptions<T extends PropertyDeclLike> extends DefaultControlOptions {
+    /** Called after every mutation; a centre editor feeds its autosave here. */
+    onChange?: () => void;
+    /** The add button's label. Default "+ Add property". */
+    addLabel?: string;
+    /** The empty sentence. Default "No properties yet." */
+    emptyText?: string;
+    /** The type select's entries; default `PROPERTY_TYPES`. */
+    types?: ReadonlyArray<readonly [string, string]>;
+    /** A fresh declaration for the add button. Default: a blank of the first type. */
+    newDecl?: () => T;
+    /** Controls on the row's line, between the default and the movers
+     *  (Storyletter's "uses" affordance). */
+    extraLine?: (decl: T, index: number) => (HTMLElement | null)[];
+    /** Fields behind the disclosure, before Values / Stages / Purpose
+     *  (Shared, Temporary, Read-only, Durable). */
+    extraDetails?: (decl: T, index: number) => (HTMLElement | null)[];
+    /** Offer the Purpose field. Default true. */
+    purpose?: boolean;
+}
+interface PropertyListHandle extends SettingsSectionHandle {
+    /** Both faults, for the Save gate: a duplicate first, then an illegal name. */
+    firstInvalid(): HTMLInputElement | null;
+    /** The first name that clashes with another, or null. */
+    firstDuplicate(): HTMLInputElement | null;
+    /** The first name no expression could reach, or null. */
+    firstIllegalName(): HTMLInputElement | null;
+    /** Redraw from `decls` (after an outside change). */
+    render(): void;
+}
+/** Mount the list into `host`. Mutates `decls` in place; the caller reads
+ *  them back on save (pruning blank names is the caller's, since only it
+ *  knows its DTO). */
+declare function mountPropertyList<T extends PropertyDeclLike>(host: HTMLElement, decls: T[], opts?: PropertyListOptions<T>): PropertyListHandle;
+
+export { type DefaultControlOptions as D, PROPERTY_TYPES as P, type SettingsDialog as S, type DupGuard as a, type PropertyDeclLike as b, type PropertyListHandle as c, type PropertyListOptions as d, type PropertyListType as e, type SettingsDialogOptions as f, type SettingsSection as g, type SettingsSectionHandle as h, defaultControl as i, dupGuard as j, expandableRow as k, focusNewRow as l, mountPropertyList as m, mountSettingsDialog as n, revealRowWhenReady as o, revealRow as r };