@wildwinter/app-shell 0.16.0 → 0.18.0

package/dist/index.d.cts

@@ -76,6 +76,15 @@ declare const icon: {
     readonly dot: "●";
     /** Play, in the sense of "run this". */
     readonly play: "▶";
+    /** Start the thing again from the top: a play session, a sweep. Named for the
+     *  act, not the arrow, which is the table's rule. */
+    readonly restart: "⟲";
+    /** The three ways a collection can be shown. Named by what you get rather than
+     *  by the glyph, so a second app can pick the same three without copying
+     *  somebody's taste in symbols. */
+    readonly viewCards: "▦";
+    readonly viewTable: "☰";
+    readonly viewNode: "◈";
     /** The drag grip on a reorderable row. */
     readonly grip: "⠿";
     /** Add one of whatever this list holds. */
@@ -561,4 +570,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, 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

@@ -76,6 +76,15 @@ declare const icon: {
     readonly dot: "●";
     /** Play, in the sense of "run this". */
     readonly play: "▶";
+    /** Start the thing again from the top: a play session, a sweep. Named for the
+     *  act, not the arrow, which is the table's rule. */
+    readonly restart: "⟲";
+    /** The three ways a collection can be shown. Named by what you get rather than
+     *  by the glyph, so a second app can pick the same three without copying
+     *  somebody's taste in symbols. */
+    readonly viewCards: "▦";
+    readonly viewTable: "☰";
+    readonly viewNode: "◈";
     /** The drag grip on a reorderable row. */
     readonly grip: "⠿";
     /** Add one of whatever this list holds. */
@@ -561,4 +570,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, 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

@@ -137,6 +137,15 @@ var icon = {
   dot: "\u25CF",
   /** Play, in the sense of "run this". */
   play: "\u25B6",
+  /** Start the thing again from the top: a play session, a sweep. Named for the
+   *  act, not the arrow, which is the table's rule. */
+  restart: "\u27F2",
+  /** The three ways a collection can be shown. Named by what you get rather than
+   *  by the glyph, so a second app can pick the same three without copying
+   *  somebody's taste in symbols. */
+  viewCards: "\u25A6",
+  viewTable: "\u2630",
+  viewNode: "\u25C8",
   // --- handling -------------------------------------------------------------
   /** The drag grip on a reorderable row. */
   grip: "\u283F",
@@ -1364,6 +1373,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, 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