@wildwinter/app-shell 0.29.0 → 0.31.0

package/dist/index.d.cts

@@ -379,6 +379,65 @@ declare function isValidPropertyName(name: string): boolean;
  */
 declare function isCaseOnlyPropertyName(name: string): boolean;
 
+/**
+ * One line saying what is wrong with this name, or undefined when nothing is.
+ *
+ * Each branch names what actually HAPPENS rather than reciting the rule, because
+ * the person reading it is usually somebody wondering why a condition does
+ * nothing. Kept to one line: it lands in a rollover on the field, and hosts
+ * repeat it in the Save error rather than inventing a summary of their own.
+ */
+declare function propertyNameProblem(name: string): string | undefined;
+/**
+ * Wire a name field: mark it live, explain the fault in its rollover, and coerce
+ * on Tab. `onCommit` receives what the author typed, VERBATIM, on every input.
+ *
+ * `.illegal` rather than dupGuard's `.invalid`, because both can be true of one
+ * field and `dupGuard.check()` owns that class: it would clear this marking every
+ * time it ran, including at the moment of a blocked Save.
+ *
+ * An empty field is not marked. An unfinished row is a different thing from an
+ * illegal one, and hosts prune blank names on save.
+ */
+declare function bindPropertyName(input: HTMLInputElement, onCommit: (value: string) => void, opts?: {
+    hint?: string;
+}): void;
+/**
+ * The first field in `host` holding a name no expression could reach, for a Save
+ * gate. Hosts hand this back beside `dupGuard.firstDuplicate()`: two faults, two
+ * 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;
     /** The pinned address, or "" when it is being derived. */
@@ -759,4 +818,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, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createSaveController, dupGuard, el, expandableRow, 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, 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

@@ -379,6 +379,65 @@ declare function isValidPropertyName(name: string): boolean;
  */
 declare function isCaseOnlyPropertyName(name: string): boolean;
 
+/**
+ * One line saying what is wrong with this name, or undefined when nothing is.
+ *
+ * Each branch names what actually HAPPENS rather than reciting the rule, because
+ * the person reading it is usually somebody wondering why a condition does
+ * nothing. Kept to one line: it lands in a rollover on the field, and hosts
+ * repeat it in the Save error rather than inventing a summary of their own.
+ */
+declare function propertyNameProblem(name: string): string | undefined;
+/**
+ * Wire a name field: mark it live, explain the fault in its rollover, and coerce
+ * on Tab. `onCommit` receives what the author typed, VERBATIM, on every input.
+ *
+ * `.illegal` rather than dupGuard's `.invalid`, because both can be true of one
+ * field and `dupGuard.check()` owns that class: it would clear this marking every
+ * time it ran, including at the moment of a blocked Save.
+ *
+ * An empty field is not marked. An unfinished row is a different thing from an
+ * illegal one, and hosts prune blank names on save.
+ */
+declare function bindPropertyName(input: HTMLInputElement, onCommit: (value: string) => void, opts?: {
+    hint?: string;
+}): void;
+/**
+ * The first field in `host` holding a name no expression could reach, for a Save
+ * gate. Hosts hand this back beside `dupGuard.firstDuplicate()`: two faults, two
+ * 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;
     /** The pinned address, or "" when it is being derived. */
@@ -759,4 +818,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, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createSaveController, dupGuard, el, expandableRow, 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, 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

@@ -879,6 +879,142 @@ function isCaseOnlyPropertyName(name) {
   return !isValidPropertyName(name) && isValidPropertyName(name.toLowerCase());
 }
 
+// src/property-name-field.ts
+var refSyncs = /* @__PURE__ */ new WeakMap();
+function propertyNameProblem(name) {
+  if (isValidPropertyName(name)) return void 0;
+  const suggestion = propertyNameify(name);
+  const tail = suggestion ? ` Try "${suggestion}", or press Tab.` : "";
+  if (RESERVED_PROPERTY_NAMES.includes(name.toLowerCase())) {
+    return `Cannot be used: "${name.toLowerCase()}" 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}`;
+  if (name !== name.toLowerCase()) {
+    return `Cannot be used: expressions fold names, so this would look for "${name.toLowerCase()}".${tail}`;
+  }
+  return `Cannot be used: only lower case letters, digits and underscores.${tail}`;
+}
+function bindPropertyName(input, onCommit, opts = {}) {
+  const hint = opts.hint;
+  const sync = () => {
+    const v = input.value.trim();
+    const problem = v === "" ? void 0 : propertyNameProblem(v);
+    input.classList.toggle("illegal", !!problem);
+    if (problem) input.title = problem;
+    else if (input.title.startsWith("Cannot be used")) {
+      if (hint) input.title = hint;
+      else input.removeAttribute("title");
+    }
+  };
+  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)) return;
+    const coerced = propertyNameify(typed);
+    if (!coerced || coerced === input.value) return;
+    e.preventDefault();
+    input.value = coerced;
+    onCommit(coerced);
+    sync();
+  });
+  sync();
+}
+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);
+  input.after(list);
+  const sync = () => {
+    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) {
   const slugify = opts.slugify ?? gameIdify;
@@ -1539,6 +1675,6 @@ function renderStepperBar(host, opts) {
   );
 }
 
-export { PALETTE, PALETTE_SIZE, PROPERTY_NAME_HINT, RESERVED_PROPERTY_NAMES, askIdentity, closeAnchoredPanel, closeWithExit, colourFor, colourIndex, confirmDialog, createSaveController, dupGuard, el, expandableRow, 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, 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