@wildwinter/app-shell 0.28.0 → 0.30.0

package/dist/index.d.cts

@@ -339,6 +339,76 @@ declare function gameIdify(text: string): string;
  *  "derive one", which is a different thing from an address. */
 declare function isValidGameId(gameId: string): boolean;
 
+/** The five words `@wildwinter/expr` lexes as keywords, so a property may not be
+ *  called any of them: the reference does not resolve, it fails to parse. Kept
+ *  here as a copy for the same reason the rules are (no dependency), and each
+ *  app probes the real parser to prove the list is still true. */
+declare const RESERVED_PROPERTY_NAMES: readonly string[];
+/** What an editor should tell an author, in one line. */
+declare const PROPERTY_NAME_HINT = "Lower case letters, digits and underscores. Cannot start with a digit. No hyphens or spaces.";
+/**
+ * Coerce a label into a legal property name: lower case, apostrophes dropped,
+ * runs of anything else to a single underscore, no trailing underscore, an
+ * underscore in front if it would otherwise start with a digit, and one behind
+ * if it would otherwise be a keyword.
+ *
+ * A LEADING underscore is kept where the author typed one, because `_private` is
+ * a legal name and a meaningful choice; only the ends that would be illegal are
+ * touched.
+ *
+ * May return "", when there was nothing usable in the input. Callers treat that
+ * as "no name yet" rather than as a name.
+ */
+declare function propertyNameify(text: string): string;
+/**
+ * Is this a name the expression language can actually reach? Lower case letters,
+ * digits and underscores, not starting with a digit, and not a keyword.
+ *
+ * "" is NOT legal: an unnamed declaration is an unfinished row, which is a
+ * different thing from an illegal one, and callers distinguish them.
+ */
+declare function isValidPropertyName(name: string): boolean;
+/**
+ * The one thing that is only a case difference, e.g. `isNight` -> `isnight`.
+ *
+ * Worth its own question because it is the only violation that can be repaired
+ * without guessing at intent: the language already folds every REFERENCE, so
+ * folding the declaration to match changes nothing observable, where inventing
+ * an underscore for a space is a decision about what the author meant. Loaders
+ * fold this class silently and report the rest.
+ */
+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 GameIdEditorOptions {
     anchor: HTMLElement;
     /** The pinned address, or "" when it is being derived. */
@@ -719,4 +789,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, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButton, 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, closeWithExit, 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 };
+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 };

package/dist/index.d.ts

@@ -339,6 +339,76 @@ declare function gameIdify(text: string): string;
  *  "derive one", which is a different thing from an address. */
 declare function isValidGameId(gameId: string): boolean;
 
+/** The five words `@wildwinter/expr` lexes as keywords, so a property may not be
+ *  called any of them: the reference does not resolve, it fails to parse. Kept
+ *  here as a copy for the same reason the rules are (no dependency), and each
+ *  app probes the real parser to prove the list is still true. */
+declare const RESERVED_PROPERTY_NAMES: readonly string[];
+/** What an editor should tell an author, in one line. */
+declare const PROPERTY_NAME_HINT = "Lower case letters, digits and underscores. Cannot start with a digit. No hyphens or spaces.";
+/**
+ * Coerce a label into a legal property name: lower case, apostrophes dropped,
+ * runs of anything else to a single underscore, no trailing underscore, an
+ * underscore in front if it would otherwise start with a digit, and one behind
+ * if it would otherwise be a keyword.
+ *
+ * A LEADING underscore is kept where the author typed one, because `_private` is
+ * a legal name and a meaningful choice; only the ends that would be illegal are
+ * touched.
+ *
+ * May return "", when there was nothing usable in the input. Callers treat that
+ * as "no name yet" rather than as a name.
+ */
+declare function propertyNameify(text: string): string;
+/**
+ * Is this a name the expression language can actually reach? Lower case letters,
+ * digits and underscores, not starting with a digit, and not a keyword.
+ *
+ * "" is NOT legal: an unnamed declaration is an unfinished row, which is a
+ * different thing from an illegal one, and callers distinguish them.
+ */
+declare function isValidPropertyName(name: string): boolean;
+/**
+ * The one thing that is only a case difference, e.g. `isNight` -> `isnight`.
+ *
+ * Worth its own question because it is the only violation that can be repaired
+ * without guessing at intent: the language already folds every REFERENCE, so
+ * folding the declaration to match changes nothing observable, where inventing
+ * an underscore for a space is a decision about what the author meant. Loaders
+ * fold this class silently and report the rest.
+ */
+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 GameIdEditorOptions {
     anchor: HTMLElement;
     /** The pinned address, or "" when it is being derived. */
@@ -719,4 +789,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, type PaneShell, type PaneShellOptions, type PaneShellState, type PaneSide, type PaneSideConfig, type PinButton, 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, closeWithExit, 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 };
+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 };

package/dist/index.js

@@ -860,6 +860,73 @@ function isValidGameId(gameId) {
   return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(gameId);
 }
 
+// src/property-names.ts
+var RESERVED_PROPERTY_NAMES = ["true", "false", "and", "or", "not"];
+var PROPERTY_NAME_HINT = "Lower case letters, digits and underscores. Cannot start with a digit. No hyphens or spaces.";
+function propertyNameify(text) {
+  const trimmed = text.trim();
+  const deliberateLeading = trimmed.startsWith("_");
+  let out = trimmed.toLowerCase().replace(/['’]/g, "").replace(/[^a-z0-9_]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  if (out === "") return "";
+  if (deliberateLeading || /^[0-9]/.test(out)) out = `_${out}`;
+  if (RESERVED_PROPERTY_NAMES.includes(out)) out = `${out}_`;
+  return out;
+}
+function isValidPropertyName(name) {
+  return /^[a-z_][a-z0-9_]*$/.test(name) && !RESERVED_PROPERTY_NAMES.includes(name);
+}
+function isCaseOnlyPropertyName(name) {
+  return !isValidPropertyName(name) && isValidPropertyName(name.toLowerCase());
+}
+
+// src/property-name-field.ts
+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");
+}
+
 // src/id-editor.ts
 function openGameIdEditor(opts) {
   const slugify = opts.slugify ?? gameIdify;
@@ -1520,6 +1587,6 @@ function renderStepperBar(host, opts) {
   );
 }
 
-export { PALETTE, PALETTE_SIZE, askIdentity, closeAnchoredPanel, closeWithExit, 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 };
+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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map