@wildwinter/app-shell 0.17.0 → 0.19.0

package/dist/index.d.cts

@@ -237,6 +237,16 @@ interface ConfirmOptions {
 /** Resolves true on confirm; false on Cancel / Esc / backdrop. */
 declare function confirmDialog(opts: ConfirmOptions): Promise<boolean>;
 
+/**
+ * Play the close animation on `element`, then run `done` exactly once.
+ *
+ * `done` does the real teardown: remove the node, drop listeners, unmount
+ * whatever was inside it. Under `prefers-reduced-motion` the duration reads 0
+ * and `done` runs synchronously, so reduced motion means instant rather than
+ * an invisible wait.
+ */
+declare function closeWithExit(element: HTMLElement, done: () => void): void;
+
 interface AboutOptions {
     /** The product's name, large. */
     appName: string;
@@ -452,6 +462,19 @@ interface CommentsOptions {
     deleteMessage?: (threadId: string, index: number) => void;
     /** Where the panel sits: "centre" for a point on a canvas (see anchored.ts). */
     prefer?: "left" | "below" | "centre";
+    /**
+     * The text a thread is pinned to, shown above it as a quotation.
+     *
+     * A callback rather than a field on `Comment`, because resolving an anchor is
+     * the APP's half of the seam and this is only that resolution rendered: an app
+     * that pins threads to a span of prose can quote it, one that pins them to a
+     * whole card has nothing to quote and passes nothing. Keeping it out of the
+     * thread type also means no change to what is written to disk, which matters
+     * for files living in version control.
+     *
+     * Return undefined (or "") for a thread with no quotable anchor.
+     */
+    quoteFor?: (thread: Comment) => string | undefined;
 }
 declare function openComments(opts: CommentsOptions): void;
 
@@ -570,4 +593,81 @@ interface SaveController {
 }
 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 };
+interface SaveIndicator {
+    /** Put it in the topbar. */
+    readonly el: HTMLElement;
+    /** Wire straight to the controller's `onStatus`. */
+    set(status: SaveStatus): void;
+}
+declare function saveIndicator(initial?: SaveStatus): SaveIndicator;
+
+interface StaleBarOptions {
+    /**
+     * What went out of date, as a capitalised noun phrase: "The project", "The
+     * scene". Written into "<subject> changed in the editor."
+     */
+    subject: string;
+    /** Start again from the current source. */
+    onRestart: () => void;
+    /** The button, when "Restart" is not the app's word for it. */
+    restartLabel?: string;
+    /**
+     * The rest of the sentence, for an app whose session is not a PLAY: the
+     * default is "Restart to play the new version."
+     */
+    advice?: string;
+}
+declare function staleBar(opts: StaleBarOptions): HTMLElement;
+
+interface StepperItem {
+    /**
+     * One word for what kind of thing this is: "error", "comment", "resolved".
+     * Absent when the bar carries one kind of thing only.
+     */
+    kind?: string;
+    /** An extra class on the kind chip, so an app can colour its own kinds
+     *  (Storyletter's `sev-error`, and `done` for a resolved thread). */
+    kindClass?: string;
+    /** Where it is, in the app's own address. Set in the mono face. */
+    where?: string;
+    /** The entry itself, in one line. Overflow is clipped, not wrapped: the bar
+     *  is one row high and stays that way however long the sentence is. */
+    text: string;
+}
+/** How loud the count is. The app picks; the palette supplies the value. */
+type StepperTone = "danger" | "warn" | "accent" | "muted";
+interface StepperBarOptions {
+    items: StepperItem[];
+    /** Which one is current. Clamped, so a shrinking list cannot point off the end. */
+    at: number;
+    tone?: StepperTone;
+    /** Go to another index. The bar wraps, so this is always in range. */
+    onStep: (next: number) => void;
+    /** Take me to what the current entry is about. */
+    onGo: (index: number) => void;
+    /** What the three controls say they do. Keyboard shortcuts belong in here. */
+    tips?: {
+        prev?: string;
+        next?: string;
+        go?: string;
+    };
+    /**
+     * What to say when the list is empty.
+     *
+     * Absent hides the bar, which is right for an AMBIENT bar: no problems, no
+     * problems bar. Present keeps it up, which is right for a MODE: entering the
+     * walk and seeing nothing at all reads as a broken command rather than as
+     * "there is no feedback".
+     */
+    empty?: string;
+    /** Leave the mode. Drawn as the last control, hard right. */
+    onClose?: () => void;
+    closeTip?: string;
+    /** The right-hand end before the close: a quick fix, say. Nulls are skipped,
+     *  so a caller can pass a conditional straight in. */
+    actions?: (HTMLElement | null | undefined)[];
+}
+/** Draw (or hide) the bar in `host`. Idempotent: call it again with new state. */
+declare function renderStepperBar(host: HTMLElement, opts: StepperBarOptions): void;
+
+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 SaveIndicator, type SaveStatus, type SettingsDialog, type SettingsDialogOptions, type SettingsSection, type SettingsSectionHandle, type ShardVc, type StaleBarOptions, type StepperBarOptions, type StepperItem, type StepperTone, type TipRect, type TooltipOptions, type VcMap, askIdentity, closeAnchoredPanel, closeWithExit, 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, renderStepperBar, saveIndicator, showAbout, staleBar, tagChips, tipAt, tipBold, vcBadgeFor };

package/dist/index.d.ts

@@ -237,6 +237,16 @@ interface ConfirmOptions {
 /** Resolves true on confirm; false on Cancel / Esc / backdrop. */
 declare function confirmDialog(opts: ConfirmOptions): Promise<boolean>;
 
+/**
+ * Play the close animation on `element`, then run `done` exactly once.
+ *
+ * `done` does the real teardown: remove the node, drop listeners, unmount
+ * whatever was inside it. Under `prefers-reduced-motion` the duration reads 0
+ * and `done` runs synchronously, so reduced motion means instant rather than
+ * an invisible wait.
+ */
+declare function closeWithExit(element: HTMLElement, done: () => void): void;
+
 interface AboutOptions {
     /** The product's name, large. */
     appName: string;
@@ -452,6 +462,19 @@ interface CommentsOptions {
     deleteMessage?: (threadId: string, index: number) => void;
     /** Where the panel sits: "centre" for a point on a canvas (see anchored.ts). */
     prefer?: "left" | "below" | "centre";
+    /**
+     * The text a thread is pinned to, shown above it as a quotation.
+     *
+     * A callback rather than a field on `Comment`, because resolving an anchor is
+     * the APP's half of the seam and this is only that resolution rendered: an app
+     * that pins threads to a span of prose can quote it, one that pins them to a
+     * whole card has nothing to quote and passes nothing. Keeping it out of the
+     * thread type also means no change to what is written to disk, which matters
+     * for files living in version control.
+     *
+     * Return undefined (or "") for a thread with no quotable anchor.
+     */
+    quoteFor?: (thread: Comment) => string | undefined;
 }
 declare function openComments(opts: CommentsOptions): void;
 
@@ -570,4 +593,81 @@ interface SaveController {
 }
 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 };
+interface SaveIndicator {
+    /** Put it in the topbar. */
+    readonly el: HTMLElement;
+    /** Wire straight to the controller's `onStatus`. */
+    set(status: SaveStatus): void;
+}
+declare function saveIndicator(initial?: SaveStatus): SaveIndicator;
+
+interface StaleBarOptions {
+    /**
+     * What went out of date, as a capitalised noun phrase: "The project", "The
+     * scene". Written into "<subject> changed in the editor."
+     */
+    subject: string;
+    /** Start again from the current source. */
+    onRestart: () => void;
+    /** The button, when "Restart" is not the app's word for it. */
+    restartLabel?: string;
+    /**
+     * The rest of the sentence, for an app whose session is not a PLAY: the
+     * default is "Restart to play the new version."
+     */
+    advice?: string;
+}
+declare function staleBar(opts: StaleBarOptions): HTMLElement;
+
+interface StepperItem {
+    /**
+     * One word for what kind of thing this is: "error", "comment", "resolved".
+     * Absent when the bar carries one kind of thing only.
+     */
+    kind?: string;
+    /** An extra class on the kind chip, so an app can colour its own kinds
+     *  (Storyletter's `sev-error`, and `done` for a resolved thread). */
+    kindClass?: string;
+    /** Where it is, in the app's own address. Set in the mono face. */
+    where?: string;
+    /** The entry itself, in one line. Overflow is clipped, not wrapped: the bar
+     *  is one row high and stays that way however long the sentence is. */
+    text: string;
+}
+/** How loud the count is. The app picks; the palette supplies the value. */
+type StepperTone = "danger" | "warn" | "accent" | "muted";
+interface StepperBarOptions {
+    items: StepperItem[];
+    /** Which one is current. Clamped, so a shrinking list cannot point off the end. */
+    at: number;
+    tone?: StepperTone;
+    /** Go to another index. The bar wraps, so this is always in range. */
+    onStep: (next: number) => void;
+    /** Take me to what the current entry is about. */
+    onGo: (index: number) => void;
+    /** What the three controls say they do. Keyboard shortcuts belong in here. */
+    tips?: {
+        prev?: string;
+        next?: string;
+        go?: string;
+    };
+    /**
+     * What to say when the list is empty.
+     *
+     * Absent hides the bar, which is right for an AMBIENT bar: no problems, no
+     * problems bar. Present keeps it up, which is right for a MODE: entering the
+     * walk and seeing nothing at all reads as a broken command rather than as
+     * "there is no feedback".
+     */
+    empty?: string;
+    /** Leave the mode. Drawn as the last control, hard right. */
+    onClose?: () => void;
+    closeTip?: string;
+    /** The right-hand end before the close: a quick fix, say. Nulls are skipped,
+     *  so a caller can pass a conditional straight in. */
+    actions?: (HTMLElement | null | undefined)[];
+}
+/** Draw (or hide) the bar in `host`. Idempotent: call it again with new state. */
+declare function renderStepperBar(host: HTMLElement, opts: StepperBarOptions): void;
+
+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 SaveIndicator, type SaveStatus, type SettingsDialog, type SettingsDialogOptions, type SettingsSection, type SettingsSectionHandle, type ShardVc, type StaleBarOptions, type StepperBarOptions, type StepperItem, type StepperTone, type TipRect, type TooltipOptions, type VcMap, askIdentity, closeAnchoredPanel, closeWithExit, 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, renderStepperBar, saveIndicator, showAbout, staleBar, tagChips, tipAt, tipBold, vcBadgeFor };

package/dist/index.js

@@ -476,6 +476,29 @@ function pinButton(opts) {
   return b;
 }
 
+// src/exit.ts
+function closeWithExit(element, done) {
+  element.classList.add("closing");
+  const seconds = parseFloat(getComputedStyle(element).animationDuration) || 0;
+  if (seconds === 0) {
+    done();
+    return;
+  }
+  let fired = false;
+  const finish = () => {
+    if (fired) return;
+    fired = true;
+    element.removeEventListener("animationend", onEnd);
+    clearTimeout(timer2);
+    done();
+  };
+  const onEnd = (e) => {
+    if (e.target === element) finish();
+  };
+  element.addEventListener("animationend", onEnd);
+  const timer2 = setTimeout(finish, seconds * 1e3 + 120);
+}
+
 // src/confirm.ts
 function confirmDialog(opts) {
   return new Promise((resolve) => {
@@ -497,21 +520,9 @@ function confirmDialog(opts) {
       if (done) return;
       done = true;
       resolve(ok);
-      dlg.classList.add("closing");
-      const dur = parseFloat(getComputedStyle(dlg).animationDuration) || 0;
-      const teardown = () => {
+      closeWithExit(dlg, () => {
         dlg.close();
         dlg.remove();
-      };
-      if (dur === 0) {
-        teardown();
-        return;
-      }
-      const timer2 = setTimeout(teardown, dur * 1e3 + 120);
-      dlg.addEventListener("animationend", (e) => {
-        if (e.target !== dlg) return;
-        clearTimeout(timer2);
-        teardown();
       });
     };
     cancel.addEventListener("click", () => finish(false));
@@ -604,8 +615,10 @@ function openAnchoredPanel(opts) {
     if (current?.panel === panel) current = null;
     document.removeEventListener("pointerdown", onDown, true);
     document.removeEventListener("keydown", onKey, true);
-    panel.remove();
-    opts.onClose?.();
+    closeWithExit(panel, () => {
+      opts.onClose?.();
+      panel.remove();
+    });
   };
   closeBtn.addEventListener("click", close);
   const onDown = (e) => {
@@ -1025,6 +1038,10 @@ function openComments(opts) {
     }
     const thread = open;
     if (thread) {
+      const quote = opts.quoteFor?.(thread);
+      if (quote !== void 0 && quote !== "") {
+        body.append(el("blockquote", { className: "shell-cmt-quote", text: quote }));
+      }
       const list = el("div", { className: `shell-cmt-list${thread.resolved === true ? " resolved" : ""}` });
       thread.messages.forEach((message, index) => {
         const head = el(
@@ -1373,6 +1390,99 @@ function createSaveController(opts) {
   };
 }
 
-export { PALETTE, PALETTE_SIZE, 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 };
+// src/save-view.ts
+var WORDS = {
+  saved: "Saved",
+  saving: "Saving\u2026",
+  unsaved: "Unsaved"
+};
+function saveIndicator(initial = "saved") {
+  const node = el("span");
+  const set = (status) => {
+    node.className = `savestat ${status}`;
+    node.textContent = WORDS[status];
+  };
+  set(initial);
+  return { el: node, set };
+}
+
+// src/stale.ts
+function staleBar(opts) {
+  const label2 = opts.restartLabel ?? "Restart";
+  return el(
+    "div",
+    { className: "stale-bar" },
+    el("span", {
+      className: "stale-bar-msg",
+      text: `${opts.subject} changed in the editor. ${opts.advice ?? "Restart to play the new version."}`
+    }),
+    el("button", {
+      className: "stale-bar-go",
+      text: `${icon.restart} ${label2}`,
+      onClick: () => opts.onRestart()
+    })
+  );
+}
+
+// src/stepper.ts
+function renderStepperBar(host, opts) {
+  const { items } = opts;
+  const close = opts.onClose === void 0 ? null : el("button", {
+    className: "stepbar-nav stepbar-close",
+    text: icon.close,
+    tip: opts.closeTip ?? "Close",
+    onClick: opts.onClose
+  });
+  const actions = (opts.actions ?? []).filter((a) => a !== null && a !== void 0);
+  if (items.length === 0) {
+    if (opts.empty === void 0) {
+      host.hidden = true;
+      host.replaceChildren();
+      return;
+    }
+    host.hidden = false;
+    host.replaceChildren(
+      el("span", { className: "stepbar-count muted", text: "0" }),
+      el("span", { className: "stepbar-empty", text: opts.empty }),
+      ...actions,
+      ...close ? [close] : []
+    );
+    return;
+  }
+  host.hidden = false;
+  const index = Math.min(Math.max(opts.at, 0), items.length - 1);
+  const item = items[index];
+  const step = (delta) => opts.onStep((index + delta + items.length) % items.length);
+  const nav = items.length > 1 ? [
+    el("button", {
+      className: "stepbar-nav",
+      text: icon.back,
+      tip: opts.tips?.prev ?? "Previous",
+      onClick: () => step(-1)
+    }),
+    el("span", { className: "stepbar-of", text: `${index + 1}/${items.length}` }),
+    el("button", {
+      className: "stepbar-nav",
+      text: icon.forward,
+      tip: opts.tips?.next ?? "Next",
+      onClick: () => step(1)
+    })
+  ] : [];
+  host.replaceChildren(
+    el("span", { className: `stepbar-count ${opts.tone ?? "muted"}`, text: String(items.length) }),
+    ...nav,
+    el(
+      "button",
+      { className: "stepbar-cur", tip: opts.tips?.go ?? "Go to this", onClick: () => opts.onGo(index) },
+      item.kind === void 0 ? null : el("span", { className: `stepbar-cat${item.kindClass ? ` ${item.kindClass}` : ""}`, text: item.kind }),
+      item.where === void 0 ? null : el("span", { className: "stepbar-where", text: item.where }),
+      el("span", { className: "stepbar-msg", text: item.text })
+    ),
+    ...actions,
+    ...close ? [close] : []
+  );
+}
+
+export { PALETTE, PALETTE_SIZE, askIdentity, closeAnchoredPanel, closeWithExit, 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, renderStepperBar, saveIndicator, showAbout, staleBar, tagChips, tipAt, tipBold, vcBadgeFor };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map