@wildwinter/app-shell 0.36.0 → 0.38.0

package/dist/index.d.cts

@@ -193,11 +193,29 @@ declare function mountPaneShell(host: HTMLElement, opts: PaneShellOptions): Pane
 
 /** 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. */
+ *  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;
 /** 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;
@@ -785,6 +803,25 @@ interface StaleBarOptions {
 }
 declare function staleBar(opts: StaleBarOptions): HTMLElement;
 
+/** What the remark is about. `info` is the plain case; `ok` says a thing you
+ *  asked for happened; `error` says it did not. */
+type ToastKind = "info" | "ok" | "error";
+interface ToastOptions {
+    /** How long it stays, in ms, before the exit plays. Defaults to 4000, or
+     *  7000 for an error. */
+    duration?: number;
+}
+/**
+ * Show a toast. Replaces any toast already showing.
+ *
+ * `message` is shown as written; a newline breaks the line ("Bundle
+ * published\n<path>"), and a long unbroken token such as a path wraps inside
+ * the card rather than spilling past it.
+ */
+declare function toast(message: string, kind?: ToastKind, opts?: ToastOptions): void;
+/** Dismiss the current toast now, if any. Plays the exit. */
+declare function dismissToast(): void;
+
 interface StepperItem {
     /**
      * One word for what kind of thing this is: "error", "comment", "resolved".
@@ -881,4 +918,4 @@ declare function historyNav(onBack: () => void, onForward: () => void): {
     set(canBack: boolean, canForward: boolean): 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 NavHistory, type NavHistoryOptions, type Notes, type NotesEditorOptions, PALETTE, PALETTE_SIZE, PROPERTY_NAME_HINT, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButton, type PinButtonOptions, type PropertyRefOptions, RESERVED_PROPERTY_NAMES, 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, bindPropertyName, bindPropertyRef, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createNavHistory, createSaveController, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, historyNav, icon, iconBtn, iconSvg, initTooltips, isCaseOnlyPropertyName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, propertyRefProblem, renderStepperBar, revalidatePropertyRefs, saveIndicator, showAbout, staleBar, tagChips, tipAt, tipBold, vcBadgeFor };
+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 NavHistory, type NavHistoryOptions, type Notes, type NotesEditorOptions, PALETTE, PALETTE_SIZE, PROPERTY_NAME_HINT, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButton, type PinButtonOptions, type PropertyRefOptions, RESERVED_PROPERTY_NAMES, 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 ToastKind, type ToastOptions, type TooltipOptions, type VcMap, askIdentity, bindPropertyName, bindPropertyRef, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createNavHistory, createSaveController, dismissToast, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, historyNav, icon, iconBtn, iconSvg, initTooltips, isCaseOnlyPropertyName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, propertyRefProblem, renderStepperBar, revalidatePropertyRefs, revealRow, saveIndicator, showAbout, staleBar, tagChips, tipAt, tipBold, toast, vcBadgeFor };

package/dist/index.d.ts

@@ -193,11 +193,29 @@ declare function mountPaneShell(host: HTMLElement, opts: PaneShellOptions): Pane
 
 /** 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. */
+ *  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;
 /** 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;
@@ -785,6 +803,25 @@ interface StaleBarOptions {
 }
 declare function staleBar(opts: StaleBarOptions): HTMLElement;
 
+/** What the remark is about. `info` is the plain case; `ok` says a thing you
+ *  asked for happened; `error` says it did not. */
+type ToastKind = "info" | "ok" | "error";
+interface ToastOptions {
+    /** How long it stays, in ms, before the exit plays. Defaults to 4000, or
+     *  7000 for an error. */
+    duration?: number;
+}
+/**
+ * Show a toast. Replaces any toast already showing.
+ *
+ * `message` is shown as written; a newline breaks the line ("Bundle
+ * published\n<path>"), and a long unbroken token such as a path wraps inside
+ * the card rather than spilling past it.
+ */
+declare function toast(message: string, kind?: ToastKind, opts?: ToastOptions): void;
+/** Dismiss the current toast now, if any. Plays the exit. */
+declare function dismissToast(): void;
+
 interface StepperItem {
     /**
      * One word for what kind of thing this is: "error", "comment", "resolved".
@@ -881,4 +918,4 @@ declare function historyNav(onBack: () => void, onForward: () => void): {
     set(canBack: boolean, canForward: boolean): 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 NavHistory, type NavHistoryOptions, type Notes, type NotesEditorOptions, PALETTE, PALETTE_SIZE, PROPERTY_NAME_HINT, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButton, type PinButtonOptions, type PropertyRefOptions, RESERVED_PROPERTY_NAMES, 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, bindPropertyName, bindPropertyRef, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createNavHistory, createSaveController, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, historyNav, icon, iconBtn, iconSvg, initTooltips, isCaseOnlyPropertyName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, propertyRefProblem, renderStepperBar, revalidatePropertyRefs, saveIndicator, showAbout, staleBar, tagChips, tipAt, tipBold, vcBadgeFor };
+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 NavHistory, type NavHistoryOptions, type Notes, type NotesEditorOptions, PALETTE, PALETTE_SIZE, PROPERTY_NAME_HINT, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButton, type PinButtonOptions, type PropertyRefOptions, RESERVED_PROPERTY_NAMES, 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 ToastKind, type ToastOptions, type TooltipOptions, type VcMap, askIdentity, bindPropertyName, bindPropertyRef, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createNavHistory, createSaveController, dismissToast, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, historyNav, icon, iconBtn, iconSvg, initTooltips, isCaseOnlyPropertyName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, propertyRefProblem, renderStepperBar, revalidatePropertyRefs, revealRow, saveIndicator, showAbout, staleBar, tagChips, tipAt, tipBold, toast, vcBadgeFor };

package/dist/index.js

@@ -152,23 +152,23 @@ function initTooltips(opts = {}) {
 
 // src/dom.ts
 function el(tag, classNameOrProps, ...children) {
-  const node = document.createElement(tag);
+  const node2 = document.createElement(tag);
   const props = typeof classNameOrProps === "string" ? { className: classNameOrProps } : classNameOrProps ?? {};
-  if (props.className) node.className = props.className;
-  if (props.text !== void 0 && props.text !== null) node.textContent = props.text;
-  if (props.title !== void 0) node.title = props.title;
+  if (props.className) node2.className = props.className;
+  if (props.text !== void 0 && props.text !== null) node2.textContent = props.text;
+  if (props.title !== void 0) node2.title = props.title;
   if (props.tip !== void 0) {
-    node.dataset["tip"] = props.tip;
-    node.setAttribute("aria-label", props.tip);
+    node2.dataset["tip"] = props.tip;
+    node2.setAttribute("aria-label", props.tip);
     ensureTooltipHost();
   }
-  if (props.onClick) node.addEventListener("click", props.onClick);
+  if (props.onClick) node2.addEventListener("click", props.onClick);
   for (const child of children) {
     if (child === null || child === void 0) continue;
-    node.append(child);
+    node2.append(child);
   }
   checkTooltipHost();
-  return node;
+  return node2;
 }
 function iconBtn(glyph, title, onClick, disabled = false, danger = false) {
   const b = el("button", `shell-icon${danger ? " danger" : ""}`);
@@ -200,7 +200,7 @@ function tagChips(holder, onChange) {
   const wrap = el("div", "shell-tags");
   const input = el("input", "shell-tag-input");
   input.type = "text";
-  input.placeholder = "add value";
+  input.placeholder = "Add value";
   input.spellcheck = false;
   const makeChip = (v) => {
     const chip = el("span", "shell-tag", v);
@@ -470,6 +470,7 @@ function mountPaneShell(host, opts) {
 // src/settings.ts
 function expandableRow(opts) {
   const row = el("div", "set-row");
+  if (opts.name !== void 0) row.dataset.name = opts.name;
   const line = el("div", "set-rowline");
   if (opts.details && opts.details.length) {
     const details = el("div", "set-details");
@@ -495,6 +496,19 @@ function expandableRow(opts) {
   }
   return row;
 }
+function revealRow(within, name) {
+  const row = [...within.querySelectorAll(".set-row")].find((r) => r.dataset.name === name);
+  if (!row) return false;
+  const toggle = row.querySelector(".set-rowline > .set-expand");
+  if (toggle && toggle.getAttribute("aria-expanded") !== "true") toggle.click();
+  const still = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+  row.scrollIntoView({ block: "center", behavior: still ? "auto" : "smooth" });
+  row.classList.remove("landed");
+  void row.offsetWidth;
+  row.classList.add("landed");
+  row.addEventListener("animationend", () => row.classList.remove("landed"), { once: true });
+  return true;
+}
 function focusNewRow(listEl) {
   const last = listEl?.lastElementChild;
   if (!(last instanceof HTMLElement)) return;
@@ -664,14 +678,14 @@ function closeWithExit(element, done) {
     if (fired) return;
     fired = true;
     element.removeEventListener("animationend", onEnd);
-    clearTimeout(timer2);
+    clearTimeout(timer3);
     done();
   };
   const onEnd = (e) => {
     if (e.target === element) finish();
   };
   element.addEventListener("animationend", onEnd);
-  const timer2 = setTimeout(finish, seconds * 1e3 + 120);
+  const timer3 = setTimeout(finish, seconds * 1e3 + 120);
 }
 
 // src/confirm.ts
@@ -1511,7 +1525,7 @@ function createSaveController(opts) {
   let auto = true;
   let dirty = false;
   let dirtySince = 0;
-  let timer2;
+  let timer3;
   let inFlight;
   const setStatus = (next) => {
     if (next === status) return;
@@ -1519,17 +1533,17 @@ function createSaveController(opts) {
     opts.onStatus?.(status);
   };
   const clearTimer = () => {
-    if (timer2 === void 0) return;
-    clearTimeout(timer2);
-    timer2 = void 0;
+    if (timer3 === void 0) return;
+    clearTimeout(timer3);
+    timer3 = void 0;
   };
   const arm = () => {
     clearTimer();
     if (!auto) return;
     const deadline = dirtySince + maxWaitMs;
     const wait = Math.max(0, Math.min(delayMs, deadline - Date.now()));
-    timer2 = setTimeout(() => {
-      timer2 = void 0;
+    timer3 = setTimeout(() => {
+      timer3 = void 0;
       void run();
     }, wait);
   };
@@ -1603,13 +1617,13 @@ var WORDS = {
   unsaved: "Unsaved"
 };
 function saveIndicator(initial = "saved") {
-  const node = el("span");
+  const node2 = el("span");
   const set = (status) => {
-    node.className = `savestat ${status}`;
-    node.textContent = WORDS[status];
+    node2.className = `savestat ${status}`;
+    node2.textContent = WORDS[status];
   };
   set(initial);
-  return { el: node, set };
+  return { el: node2, set };
 }
 
 // src/stale.ts
@@ -1630,6 +1644,43 @@ function staleBar(opts) {
   );
 }
 
+// src/toast.ts
+var DURATION = { info: 4e3, ok: 4e3, error: 7e3 };
+var node;
+var timer2 = 0;
+var seq = 0;
+function mount() {
+  if (node && node.isConnected) return node;
+  node = el("div", { className: "shell-toast" });
+  node.setAttribute("role", "status");
+  node.setAttribute("aria-live", "polite");
+  node.hidden = true;
+  document.body.append(node);
+  return node;
+}
+function toast(message, kind = "info", opts = {}) {
+  const t = mount();
+  const id = ++seq;
+  t.textContent = message;
+  t.className = `shell-toast ${kind}`;
+  t.hidden = false;
+  window.clearTimeout(timer2);
+  timer2 = window.setTimeout(() => {
+    closeWithExit(t, () => {
+      if (seq === id) t.hidden = true;
+    });
+  }, opts.duration ?? DURATION[kind]);
+}
+function dismissToast() {
+  if (!node || node.hidden) return;
+  window.clearTimeout(timer2);
+  const id = seq;
+  const t = node;
+  closeWithExit(t, () => {
+    if (seq === id) t.hidden = true;
+  });
+}
+
 // src/stepper.ts
 function renderStepperBar(host, opts) {
   const { items } = opts;
@@ -1752,6 +1803,6 @@ function historyNav(onBack, onForward) {
   };
 }
 
-export { PALETTE, PALETTE_SIZE, PROPERTY_NAME_HINT, RESERVED_PROPERTY_NAMES, askIdentity, bindPropertyName, bindPropertyRef, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createNavHistory, createSaveController, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, historyNav, icon, iconBtn, iconSvg, initTooltips, isCaseOnlyPropertyName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, propertyRefProblem, renderStepperBar, revalidatePropertyRefs, saveIndicator, showAbout, staleBar, tagChips, tipAt, tipBold, vcBadgeFor };
+export { PALETTE, PALETTE_SIZE, PROPERTY_NAME_HINT, RESERVED_PROPERTY_NAMES, askIdentity, bindPropertyName, bindPropertyRef, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createNavHistory, createSaveController, dismissToast, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, historyNav, icon, iconBtn, iconSvg, initTooltips, isCaseOnlyPropertyName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, propertyRefProblem, renderStepperBar, revalidatePropertyRefs, revealRow, saveIndicator, showAbout, staleBar, tagChips, tipAt, tipBold, toast, vcBadgeFor };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map