@wildwinter/app-shell 0.30.0 → 0.32.0

package/dist/index.d.cts

@@ -19,7 +19,20 @@ declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, classNameOrPr
  *  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>`. */
+/**
+ * A captioned field: `<label class="shell-labelled"><span class="shell-fieldcap">…</span>control</label>`.
+ *
+ * The label is pointed at the field it captions, EXPLICITLY, and never at a button. A `<label>` with no
+ * `for` forwards a click to its first labelable descendant, and buttons are labelable - so a caption
+ * wrapped around a control containing buttons (`tagChips`, whose every chip carries a remove button)
+ * turns every click on the row's dead space into a press of the FIRST button in it. That shipped:
+ * patterkit/patter#44, where clicking a Game Data list value anywhere but its ✕ deleted the first value
+ * in the list. Reported as "clicking a value removes the wrong one", which is not a wrong-index bug at
+ * all - the click never reached the chip.
+ *
+ * When the control holds no labelable field (a chips editor with the add input removed, say), this is a
+ * plain `<div>`: no caption behaviour is better than a caption that presses something.
+ */
 declare function labelled(label: string, control: HTMLElement): HTMLElement;
 /** Swap item `i` with its neighbour `i + delta` IN PLACE (the up/down reorder list editors share);
  *  a no-op when the target is out of range. Returns whether anything moved. */
@@ -408,6 +421,35 @@ declare function bindPropertyName(input: HTMLInputElement, onCommit: (value: str
  * sets of words, one gate.
  */
 declare function firstIllegalPropertyName(host: ParentNode): HTMLInputElement | null;
+interface PropertyRefOptions {
+    /** The names that exist, read fresh on every check so a declaration added in the
+     *  same dialog clears the complaint. Compared case-insensitively, since the
+     *  parser folds. */
+    known: () => string[];
+    /** The scope token this field addresses, for the wording ("no @world property..."). */
+    scope?: string;
+    /** Shown on the field when there is nothing to complain about. */
+    hint?: string;
+}
+/** Why this reference cannot be used, or undefined when it can. */
+declare function propertyRefProblem(name: string, opts: PropertyRefOptions): string | undefined;
+/**
+ * Wire a field that POINTS at a declared property: same manners as a declaration
+ * field (mark, do not rewrite, Tab coerces), plus the declared names offered as a
+ * datalist, because the rule is declare-then-reference and a picker makes that
+ * painless rather than pedantic.
+ *
+ * Marks `.illegal` for an undeclared name too, which gates Save wherever the host
+ * already asks `firstIllegalPropertyName`.
+ */
+declare function bindPropertyRef(input: HTMLInputElement, onCommit: (value: string) => void, opts: PropertyRefOptions): void;
+/**
+ * Re-check every bound reference field inside `host`. Hosts call this when the
+ * DECLARATIONS change, since a reference's validity depends on a list it does not
+ * own: rename a property and the driver pointing at it is wrong from that moment,
+ * with nothing typed into it.
+ */
+declare function revalidatePropertyRefs(host: ParentNode): void;
 
 interface GameIdEditorOptions {
     anchor: HTMLElement;
@@ -789,4 +831,4 @@ interface StepperBarOptions {
 /** 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, PROPERTY_NAME_HINT, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButton, type PinButtonOptions, 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, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createSaveController, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, icon, iconBtn, iconSvg, initTooltips, isCaseOnlyPropertyName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, renderStepperBar, 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 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, createSaveController, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, 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 };

package/dist/index.d.ts

@@ -19,7 +19,20 @@ declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, classNameOrPr
  *  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>`. */
+/**
+ * A captioned field: `<label class="shell-labelled"><span class="shell-fieldcap">…</span>control</label>`.
+ *
+ * The label is pointed at the field it captions, EXPLICITLY, and never at a button. A `<label>` with no
+ * `for` forwards a click to its first labelable descendant, and buttons are labelable - so a caption
+ * wrapped around a control containing buttons (`tagChips`, whose every chip carries a remove button)
+ * turns every click on the row's dead space into a press of the FIRST button in it. That shipped:
+ * patterkit/patter#44, where clicking a Game Data list value anywhere but its ✕ deleted the first value
+ * in the list. Reported as "clicking a value removes the wrong one", which is not a wrong-index bug at
+ * all - the click never reached the chip.
+ *
+ * When the control holds no labelable field (a chips editor with the add input removed, say), this is a
+ * plain `<div>`: no caption behaviour is better than a caption that presses something.
+ */
 declare function labelled(label: string, control: HTMLElement): HTMLElement;
 /** Swap item `i` with its neighbour `i + delta` IN PLACE (the up/down reorder list editors share);
  *  a no-op when the target is out of range. Returns whether anything moved. */
@@ -408,6 +421,35 @@ declare function bindPropertyName(input: HTMLInputElement, onCommit: (value: str
  * sets of words, one gate.
  */
 declare function firstIllegalPropertyName(host: ParentNode): HTMLInputElement | null;
+interface PropertyRefOptions {
+    /** The names that exist, read fresh on every check so a declaration added in the
+     *  same dialog clears the complaint. Compared case-insensitively, since the
+     *  parser folds. */
+    known: () => string[];
+    /** The scope token this field addresses, for the wording ("no @world property..."). */
+    scope?: string;
+    /** Shown on the field when there is nothing to complain about. */
+    hint?: string;
+}
+/** Why this reference cannot be used, or undefined when it can. */
+declare function propertyRefProblem(name: string, opts: PropertyRefOptions): string | undefined;
+/**
+ * Wire a field that POINTS at a declared property: same manners as a declaration
+ * field (mark, do not rewrite, Tab coerces), plus the declared names offered as a
+ * datalist, because the rule is declare-then-reference and a picker makes that
+ * painless rather than pedantic.
+ *
+ * Marks `.illegal` for an undeclared name too, which gates Save wherever the host
+ * already asks `firstIllegalPropertyName`.
+ */
+declare function bindPropertyRef(input: HTMLInputElement, onCommit: (value: string) => void, opts: PropertyRefOptions): void;
+/**
+ * Re-check every bound reference field inside `host`. Hosts call this when the
+ * DECLARATIONS change, since a reference's validity depends on a list it does not
+ * own: rename a property and the driver pointing at it is wrong from that moment,
+ * with nothing typed into it.
+ */
+declare function revalidatePropertyRefs(host: ParentNode): void;
 
 interface GameIdEditorOptions {
     anchor: HTMLElement;
@@ -789,4 +831,4 @@ interface StepperBarOptions {
 /** 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, PROPERTY_NAME_HINT, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButton, type PinButtonOptions, 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, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createSaveController, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, icon, iconBtn, iconSvg, initTooltips, isCaseOnlyPropertyName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, renderStepperBar, 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 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, createSaveController, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, 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 };

package/dist/index.js

@@ -181,8 +181,13 @@ function iconBtn(glyph, title, onClick, disabled = false, danger = false) {
   return b;
 }
 function labelled(label2, control) {
-  const w = el("label", "shell-labelled");
+  const target = control.matches("input, select, textarea") ? control : control.querySelector("input:not([type=button]):not([type=submit]), select, textarea");
+  const w = el(target ? "label" : "div", "shell-labelled");
   w.append(el("span", "shell-fieldcap", label2), control);
+  if (target) {
+    if (!target.id) target.id = `shell-f-${Math.random().toString(36).slice(2, 9)}`;
+    w.htmlFor = target.id;
+  }
   return w;
 }
 function moveItem(arr, i, delta) {
@@ -880,6 +885,7 @@ function isCaseOnlyPropertyName(name) {
 }
 
 // src/property-name-field.ts
+var refSyncs = /* @__PURE__ */ new WeakMap();
 function propertyNameProblem(name) {
   if (isValidPropertyName(name)) return void 0;
   const suggestion = propertyNameify(name);
@@ -926,6 +932,96 @@ function bindPropertyName(input, onCommit, opts = {}) {
 function firstIllegalPropertyName(host) {
   return host.querySelector("input.illegal");
 }
+function nearest(name, known) {
+  const n = name.toLowerCase();
+  const byPrefix = known.filter((k) => k.toLowerCase().startsWith(n) || n.startsWith(k.toLowerCase()));
+  if (byPrefix.length === 1) return byPrefix[0];
+  let best;
+  let bestScore = 3;
+  for (const k of known) {
+    const a = k.toLowerCase();
+    if (Math.abs(a.length - n.length) > 2) continue;
+    let prev = Array.from({ length: n.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+      const row = [i];
+      for (let j = 1; j <= n.length; j++) {
+        row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === n[j - 1] ? 0 : 1));
+      }
+      prev = row;
+    }
+    const d = prev[n.length];
+    if (d < bestScore) {
+      bestScore = d;
+      best = k;
+    }
+  }
+  return best;
+}
+function propertyRefProblem(name, opts) {
+  const scope = opts.scope ? `@${opts.scope}` : "that scope";
+  const folded = name.toLowerCase();
+  if (!isValidPropertyName(folded)) {
+    const suggestion = propertyNameify(name);
+    const tail = suggestion ? ` Try "${suggestion}", or press Tab.` : "";
+    if (RESERVED_PROPERTY_NAMES.includes(folded)) return `Cannot be used: "${folded}" is a keyword in expressions.${tail}`;
+    if (name.includes("-")) return `Cannot be used: a hyphen reads as subtraction in an expression.${tail}`;
+    if (/^[0-9]/.test(name)) return `Cannot be used: a name cannot start with a digit.${tail}`;
+    return `Cannot be used: only lower case letters, digits and underscores.${tail}`;
+  }
+  const known = opts.known();
+  if (known.some((k) => k.toLowerCase() === folded)) return void 0;
+  const near = nearest(folded, known);
+  if (near) return `No ${scope} property is called "${name}". Did you mean "${near}"?`;
+  if (known.length === 0) return `No ${scope} properties are declared yet. Declare one above first.`;
+  const shown = known.slice(0, 3).map((k) => `"${k}"`).join(", ");
+  const more = known.length > 3 ? `, and ${known.length - 3} more` : "";
+  return `No ${scope} property is called "${name}". Declared: ${shown}${more}.`;
+}
+function bindPropertyRef(input, onCommit, opts) {
+  const list = document.createElement("datalist");
+  list.id = `shell-propref-${Math.random().toString(36).slice(2, 9)}`;
+  input.setAttribute("list", list.id);
+  const attach = () => {
+    if (!list.isConnected && input.parentNode) input.after(list);
+  };
+  const sync = () => {
+    attach();
+    const known = opts.known();
+    list.replaceChildren(...known.map((k) => {
+      const o = document.createElement("option");
+      o.value = k;
+      return o;
+    }));
+    const v = input.value.trim();
+    const problem = v === "" ? void 0 : propertyRefProblem(v, opts);
+    input.classList.toggle("illegal", !!problem);
+    if (problem) input.title = problem;
+    else if (input.title.startsWith("Cannot be used") || input.title.startsWith("No ")) {
+      if (opts.hint) input.title = opts.hint;
+      else input.removeAttribute("title");
+    }
+  };
+  refSyncs.set(input, sync);
+  input.addEventListener("input", () => {
+    onCommit(input.value);
+    sync();
+  });
+  input.addEventListener("keydown", (e) => {
+    if (e.key !== "Tab" || e.shiftKey) return;
+    const typed = input.value.trim();
+    if (typed === "" || isValidPropertyName(typed.toLowerCase())) return;
+    const coerced = propertyNameify(typed);
+    if (!coerced || coerced === input.value) return;
+    e.preventDefault();
+    input.value = coerced;
+    onCommit(coerced);
+    sync();
+  });
+  sync();
+}
+function revalidatePropertyRefs(host) {
+  for (const input of host.querySelectorAll("input")) refSyncs.get(input)?.();
+}
 
 // src/id-editor.ts
 function openGameIdEditor(opts) {
@@ -1587,6 +1683,6 @@ function renderStepperBar(host, opts) {
   );
 }
 
-export { PALETTE, PALETTE_SIZE, PROPERTY_NAME_HINT, RESERVED_PROPERTY_NAMES, askIdentity, bindPropertyName, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createSaveController, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, icon, iconBtn, iconSvg, initTooltips, isCaseOnlyPropertyName, isValidGameId, isValidPropertyName, labelled, lockControls, lockNotice, mountJobProgress, mountPaneShell, mountSettingsDialog, moveItem, openAnchoredPanel, openComments, openGameIdEditor, openNotesEditor, paintVcBadges, pinButton, placeAnchored, propertyNameProblem, propertyNameify, renderStepperBar, 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, createSaveController, dupGuard, el, expandableRow, firstIllegalPropertyName, focusNewRow, foldVc, gameIdify, hideTip, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map