@wildwinter/app-shell 0.30.0 → 0.31.0

package/dist/index.d.cts

@@ -408,6 +408,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 +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, 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

@@ -408,6 +408,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 +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, 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

@@ -880,6 +880,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 +927,93 @@ 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);
+  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) {
@@ -1587,6 +1675,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