@ashley-shrok/viewmodel-shell 5.1.2 → 6.0.0

package/dist/index.d.ts

@@ -281,18 +281,62 @@ export interface FormNode {
     submitOnEnter?: boolean;
     children: ViewNode[];
 }
+/**
+ * Phase 21 (LOOK-01) — one reference in a `lookup` / `lookup-multiple` field:
+ * an id, optionally the label to show for it, optionally what KIND of thing it
+ * is. Used by BOTH `FieldNode.selected` (what is currently chosen) and
+ * `FieldNode.candidates` (the current search results) — the same shape in both
+ * places, which is what lets a picked value and an invented one stay
+ * homogeneous (see `allowCustom`).
+ *
+ * `value` is the id and the only thing that ever round-trips. It is typed as a
+ * `string` deliberately — not `string | number` — so the wire stays
+ * byte-identical across backends (the same rationale as `min`/`max`/`step`
+ * above): a numeric id serialized by System.Text.Json and by `JSON.stringify`
+ * must produce the same bytes, and a union invites exactly that drift.
+ *
+ * `label` is OPTIONAL and MUST be **omitted when it equals `value`** — an
+ * option not set is simply absent, and a label that merely repeats the id
+ * carries no information. This is exactly the free-form-tag case: a tag is a
+ * value whose label is itself, so the label is absent. (Salesforce models the
+ * same rule: `displayValue` is null for a plain string field and populated
+ * only when it carries something `value` doesn't — a localization, a format,
+ * or a related record's name.)
+ *
+ * `type` is the polymorphic-reference tag, and it exists because an id alone is
+ * not an identity. Microsoft, on Dataverse's `_ownerid_value`, verbatim: the
+ * GUID *"doesn't tell you whether the owner of the record is a user or a
+ * team."* Set it when one field can reference more than one kind of record;
+ * **omit it for monomorphic references**, where it would say nothing the field
+ * doesn't already say.
+ */
+export interface LookupItem {
+    /** The id. The only half that round-trips. */
+    value: string;
+    /** Display text for `value`. Omitted = the label equals the value. */
+    label?: string;
+    /** What KIND of record `value` names. Omitted = a monomorphic reference. */
+    type?: string;
+}
 export interface FieldNode {
     type: "field";
     name: string;
-    inputType: "text" | "email" | "password" | "number" | "date" | "time" | "datetime-local" | "textarea" | "hidden" | "file" | "select" | "select-multiple" | "checkbox" | "code";
+    inputType: "text" | "email" | "password" | "number" | "date" | "time" | "datetime-local" | "textarea" | "hidden" | "file" | "select" | "select-multiple" | "checkbox" | "lookup" | "lookup-multiple" | "code";
     /** Path into state where this input reads its current value and writes user
      *  changes (e.g. `fields.title`). REQUIRED for value-bearing inputs
      *  (text/email/password/number/date/time/datetime-local/textarea/select/
-     *  select-multiple/checkbox/code) and OPTIONAL for `file` inputs — a file
+     *  select-multiple/checkbox/lookup/lookup-multiple/code) and OPTIONAL for
+     *  `file` inputs — a file
      *  input's binary rides the multipart side channel (fileRegistry keyed on
      *  `name`), so omit `bind` on a file input to avoid writing a
      *  `{filename,size}` placeholder object into state (which breaks a
-     *  string/string-map state slot on round-trip). */
+     *  string/string-map state slot on round-trip).
+     *
+     *  For the lookup inputTypes this path holds the ID and NOTHING ELSE:
+     *  `lookup` binds a `string` (one id), `lookup-multiple` binds a `string[]`
+     *  (the ids). The human-readable label never lives here — it travels on
+     *  `selected`, server→client only (see the `selected` doc). The id is state;
+     *  the label is view. */
     bind?: string;
     label?: string;
     placeholder?: string;
@@ -310,7 +354,27 @@ export interface FieldNode {
      *  `.vms-field--error`, the control's `aria-invalid="true"`, and wires the
      *  message into `aria-describedby`. The view-side complement to the
      *  response-level `rejected` channel — set it on the offending field when you
-     *  build the tree. Omitted = no error shown. */
+     *  build the tree. Omitted = no error shown.
+     *
+     *  **Lookup note (5.2.0, OPEN-5): a SEARCH failure reuses this slot** — if the
+     *  directory query behind a `lookup` / `lookup-multiple` fails, put the message
+     *  here. Do NOT swallow it: react-select actively discards fetch errors
+     *  (`loader.then(callback, () => callback())`), which makes a dead backend
+     *  indistinguishable from "no results" — a direct violation of principle 8
+     *  (nothing important fails quietly), and no surveyed library has a
+     *  search-error state at all. Reusing `error` closes that gap at zero wire
+     *  cost, and §7 item 9 reserves the assertive channel for errors, so a genuine
+     *  search failure is a correct fit for this slot's `role="alert"`.
+     *
+     *  ⚠️ **The known, accepted wart:** this overloads the slot. "The server is
+     *  down" is NOT "your input is invalid", so the `aria-invalid="true"` it sets
+     *  on the combobox is semantically wrong for a search failure; and one slot
+     *  with two meanings COLLIDES if a field has a live search failure and a
+     *  pending validation error at once (last writer wins). Accepted for v1: the
+     *  app owns which message it puts here, the collision needs both conditions
+     *  simultaneously on the same field, and a distinct search-error slot is
+     *  purely additive later. Recorded rather than hidden, so a future phase can
+     *  promote it with the reasoning already written down. */
     error?: string;
     /** Hint/help text rendered below the control as `.vms-field__help` and wired
      *  into the control's `aria-describedby`. Omitted = no hint. */
@@ -330,6 +394,198 @@ export interface FieldNode {
         value: string;
         label: string;
     }>;
+    /**
+     * LOOKUP INPUTS ONLY (Phase 21, LOOK-01). What is currently chosen, resolved
+     * to display text by the server.
+     *
+     * 🚨 **THE LOAD-BEARING INVARIANT: `selected` is VIEW, not STATE.** It travels
+     * **server→client ONLY**, is recomputed on every render, and is **NEVER
+     * authoritative and NEVER trusted coming back from the client.** `bind` holds
+     * the id and is the only authoritative thing. **Direction is the entire safety
+     * argument** — a client cannot forge a label into a handler because a client
+     * never sends one. Why, from our own principles: the view is a pure function
+     * of state; the id persists and round-trips (state), while the label is
+     * derived, server-owned, and recomputed every render (view). Putting the label
+     * in the bind is putting view into state, and it manufactures a
+     * cache-invalidation problem that every mature enterprise reference field
+     * designed away by storing the id alone — rename a user and every label on
+     * every referencing record changes with zero writes.
+     *
+     * 🚨 **`selected` and `candidates` are SEPARATE FIELDS ON PURPOSE, and the
+     * selected label is NEVER resolved from `candidates`.** Fusing them is the
+     * original sin. With an id-valued field, *"filter the candidate list"* and
+     * *"forget what's selected"* are **the same operation** — so a picker that
+     * resolves its label out of the candidate list renders a raw database id the
+     * moment a form loads with a value already set and no search has occurred
+     * (the cold-start case, which is the case that matters most). Ant Design ships
+     * this failure silently (`label: ... ?? item.value`); Zag chased it across
+     * four changelog entries and two years. Read the label from `selected` and
+     * only from `selected`.
+     *
+     * **Always an array**, including for single `lookup`, where it holds 0 or 1
+     * entries. This is deliberate and there is no precedent for it elsewhere in
+     * this file, so the reasoning lives here: a `T | T[]` union drifts across
+     * backends (it does not serialize byte-identically under both
+     * System.Text.Json and `JSON.stringify`), and the banked parity lesson is to
+     * prefer the shape that cannot drift over the shape that reads nicer.
+     *
+     * `selected[].value` duplicating `bind` is **accepted, deliberate
+     * redundancy** — keying by value is robust; positional parallel arrays are
+     * not.
+     *
+     * Omitted = nothing currently selected.
+     */
+    selected?: LookupItem[];
+    /**
+     * LOOKUP INPUTS ONLY (Phase 21, LOOK-01). The current search results — what
+     * the popup listbox offers. Feeds the popup and **nothing else**. **NEVER the
+     * source of a selected label** (see `selected`).
+     *
+     * 🚨 **ORDER IS MEANINGFUL APP DATA. The renderer presents candidates AS
+     * GIVEN — it sorts nothing, dedupes nothing, and truncates nothing.** The app
+     * decides what comes back and in what order; **relevance ordering is the
+     * SERVER's judgment, never the widget's.** This is universal in mature
+     * pickers: Salesforce's picker `searchType` **defaults to `Recent`**, and
+     * Dynamics shows the five most-recently-used rows plus five favourites,
+     * explicitly NOT filtered by the search term. A renderer that "helpfully"
+     * alphabetized for tidiness would **silently destroy a server-side ranking
+     * with no way for the app to stop it** — a real consumer sorts candidates by
+     * recency-weighted mention frequency in their own provider handler, and that
+     * ranking is the whole product. (Scope: this governs the PRESENTATION of
+     * `candidates`. It is not a ban on the renderer having logic — deduping
+     * `bind` on commit in `lookup-multiple` is a state write about the user's own
+     * accumulated selection, and is correct.)
+     *
+     * 🚨 **Any cap MUST be VISIBLE in the tree. Nothing truncates silently.**
+     * There is no wire field for a cap: the app renders a `TextNode` saying so —
+     * *"Refine your filter — N matches, max is X"*, the canonical table-workflow
+     * pattern. The anti-pattern is ServiceNow's 15-result cap applied post-ACL
+     * behind a hard 250-row SQL ceiling, where **an exact-match record can be
+     * silently invisible** in a large table. A cap the user cannot see is a
+     * correctness bug wearing a performance knob's clothes.
+     *
+     * 🚨 **The picker's filter is UX, NEVER authorization.** Narrowing what is
+     * *offered* is not a security boundary, and a filter that looks like one is
+     * precisely what gets trusted by mistake. ServiceNow says it outright: *"To
+     * restrict what data specific users can access, use ACLs not reference
+     * qualifiers."* Salesforce runs two separate layers for exactly this reason —
+     * a metadata `lookupFilter` enforced server-side on save, versus the
+     * component's UI-only `filter`. **The server authorizes in the action
+     * handler, with the real auth context, exactly as every other VMS action
+     * does.** Omitting a record from `candidates` hides it from the dropdown and
+     * from nothing else — a client that already knows an id can still put it in
+     * `bind`, so the handler is the only thing standing between a user and a
+     * record they may not touch.
+     *
+     * Omitted = no results to offer.
+     */
+    candidates?: LookupItem[];
+    /**
+     * LOOKUP INPUTS ONLY (Phase 21, LOOK-04). Path into state where the typed
+     * query lives, so the server can see it and the view stays a pure function of
+     * state. Separate from `bind`, which holds the id — the query and the
+     * selection are different facts and never share a slot.
+     *
+     * Required for a working search: with a `searchAction` but no `searchBind`,
+     * the query is dispatched but the server can never read what was typed — a
+     * silently dead search that renders perfectly and returns nothing forever. The
+     * browser warns `[vms:lookup-no-searchbind]`.
+     *
+     * Keystrokes write here immediately (the query is state); **Enter** dispatches
+     * `searchAction`. That is the same cadence `TableNode.filterAction` uses.
+     *
+     * 🚨 The query is what the user TYPED. It is **not** the display text: an
+     * input showing the selected label (a form loaded with a reference already
+     * set) holds a label, not a query, and the renderer does not flush it here.
+     * Clearing the box clears the query and reveals the label again — clearing the
+     * SEARCH TEXT is not clearing the SELECTION (only `bind` holds that).
+     *
+     * Omitted = the query is not round-tripped.
+     */
+    searchBind?: string;
+    /**
+     * LOOKUP INPUTS ONLY (Phase 21). Dispatched **on ENTER**, as an **ordinary
+     * action** — the same cadence `TableNode.filterAction` uses, and the same one
+     * `action` above uses. Keystrokes write `searchBind` and dispatch nothing;
+     * there is **no debounce** and **no live-query lane**.
+     *
+     * 🚨 **`blocking` means exactly what it means everywhere else, and the
+     * framework NEVER sets it.** Your `ActionEvent` is dispatched as you declared
+     * it — omit `blocking` (the default, blocking/serialized lane) unless you have
+     * a specific reason not to.
+     *
+     * **Leaving it blocking is the recommended default, and it is a correctness
+     * property, not a preference:** a blocking action is serialized by the shell's
+     * dispatch guard (a second action cannot dispatch while a round trip is in
+     * flight), so a stale search response can never land after — and clobber — a
+     * newer action. Opting into `blocking: false` means *this response may be
+     * discarded, may arrive out of order, and may coexist with another in flight*;
+     * that is yours to choose, and yours to handle.
+     *
+     * 🚨 **Do NOT combine with {@link FieldNode.allowCustom} — it is UNSUPPORTED
+     * in v1 and warns `[vms:lookup-ambiguous-enter]`.** One Enter cannot both
+     * invent a value and run a search. The two supported shapes are: this field
+     * WITHOUT `allowCustom` (a directory/reference picker — Enter searches,
+     * arrow+Enter accepts a candidate), or `allowCustom` WITHOUT `searchAction`
+     * (a free-form tags field — Enter invents). Declaring both is ignored in
+     * favour of the search, loudly.
+     *
+     * ⚠️ **`searchAction` OCCUPIES Enter, so {@link FieldNode.action} is
+     * unreachable on a lookup that declares one.** This is a deliberate
+     * limitation, not a bug: Enter is this control's only dispatch key and the
+     * search owns it — there is no second Enter to give `action`, and inventing a
+     * second submit gesture is a keybinding no combobox pattern sanctions. **On a
+     * searching lookup, put the submit on a `ButtonNode`.**
+     *
+     * **There is NO minimum-character gate**, deliberately. **An EMPTY query is a
+     * legitimate query and IS dispatched**, so an app may answer it with
+     * most-recently-used candidates rather than nothing (Salesforce's picker
+     * `searchType` defaults to `Recent`).
+     *
+     * Omitted = no search; the field is a plain id input.
+     */
+    searchAction?: ActionEvent;
+    /**
+     * LOOKUP INPUTS ONLY (Phase 21, LOOK-06). The **declared** custom-entry axis:
+     * may the user commit a value that isn't one of the offered candidates?
+     *
+     * **Never inferred from behavior.** *Choosing somebody to mention* is very
+     * different from *inventing a new tag* — different ACTS sharing one widget —
+     * so the control DECLARES which it is doing rather than leaving it to be
+     * guessed from what the user typed.
+     *
+     * An invented value stays a homogeneous {@link LookupItem}, **never a bare
+     * string**, so no `LookupItem | string` union ever arises. MUI's `multiple +
+     * freeSolo` yields exactly that heterogeneous union — forcing every consumer
+     * to branch on `typeof`, and their own docs warn it *"may cause type
+     * mismatch."* We never admit a bare string, so it cannot happen here. A
+     * free-form tag is simply a value whose label equals itself (and is therefore
+     * omitted — see {@link LookupItem}).
+     *
+     * ⇒ `allowCustom: true` + no `candidates` + labels omitted **is a free-form
+     * tags input, with NO special case in the renderer.** This supersedes the
+     * separately-designed `inputType: "tags"` proposal.
+     *
+     * 🚨 **Do NOT combine with {@link FieldNode.searchAction} — it is UNSUPPORTED
+     * in v1 and warns `[vms:lookup-ambiguous-enter]`.** Type "urgent", press
+     * Enter: invent the tag, or search for it? Both are legitimate readings of the
+     * same keystroke, and no precedence serves both (invent-first starves the
+     * search; search-first starves invention forever) — that there is no good
+     * ordering is the tell that the shape is wrong, so v1 does not guess.
+     * Suggestions on a tags field are deferred, exactly as the parked `tags`
+     * design already deferred them. Declaring both ignores `allowCustom`.
+     *
+     * Whether a given value was picked or invented is **server-decidable** — the
+     * server produced every candidate it ever offered, so it can test the id
+     * against its own id space. There is deliberately no wire marker for
+     * provenance (no `__isNew__`): react-select needs one because it is
+     * client-only and has no server to ask; we have a server. The explicitness
+     * this decision demands is satisfied by `allowCustom` being a declared axis on
+     * the node — the app declares the act — not by a per-value flag.
+     *
+     * Omitted = false (custom entries rejected; only offered candidates commit).
+     */
+    allowCustom?: boolean;
     /** Optional language hint for `inputType: "code"`. Emitted as a class
      *  (`vms-field--code-{language}`) so apps can attach a syntax-highlighter
      *  library (CodeMirror, Monaco, etc.) — the framework only ships
@@ -466,7 +722,21 @@ export interface StatBarNode {
     type: "stat-bar";
     stats: Array<{
         label: string;
-        value: string | number;
+        /** The stat's value. Typed `string` (not `string | number`) so the TS and
+         *  .NET backends emit BYTE-IDENTICAL wire — a bare number would serialize as
+         *  JSON `12` in TS but the .NET twin's `string Value` can only emit `"12"`,
+         *  a real cross-backend drift the parity suite never exercised. Format the
+         *  number server-side (`String(n)`, `n.toFixed(2)`, `$${n}`) — the value is
+         *  display text, and any formatting an app wants is richer than a bare
+         *  number anyway. (Narrowed in 6.0.0 — see CHANGELOG; the field was unused.) */
+        value: string;
+        /** Optional semantic status tone for this tile — the universal status color
+         *  axis (same closed set as Section/Button/ListItem/TableRow). Renders the
+         *  tile as a subtly tinted chip (surface tint + colored border, reusing the
+         *  --vms-error/-warning/-success/-info tokens), so an unhealthy stat reads at
+         *  a glance rather than via one small line of text. Omitted = today's neutral
+         *  inline stat. Closed union. */
+        tone?: "danger" | "warning" | "success" | "info";
     }>;
 }
 export interface TabsNode {
@@ -737,6 +1007,16 @@ export interface StepItem {
     label: string;
     /** Optional one-line supporting text shown beside/under the label. */
     description?: string;
+    /** Optional semantic status tone for this step — the universal status color
+     *  axis (same closed set as Section/Button/ListItem/TableRow). ORTHOGONAL to
+     *  the done/current/upcoming state the framework DERIVES from `current`: tone
+     *  overlays a semantic color onto the marker (e.g. a failed/blocked stage read
+     *  as `danger`, a stage needing attention as `warning`) regardless of its
+     *  position in the sequence. Omitted = the derived state's default appearance
+     *  (accent for done/current, muted for upcoming). Because tone is app-authored
+     *  status reinforced by the step's own label text, it is NOT color-only (same
+     *  posture as Section tone). Closed union. */
+    tone?: "danger" | "warning" | "success" | "info";
 }
 /** A discrete step / stepper / wizard progress indicator — an ordered list of
  *  stages with a single 0-based `current` index. Per-step status DERIVES from

package/dist/server.js

@@ -107,6 +107,12 @@ function collectActions(node, enclosingForm, out) {
             const field = node;
             if (field.action)
                 recordAction(field.action, enclosingForm, out);
+            // Phase 21 (LOOK-01) — a lookup's debounced search is a real dispatch to a
+            // real handler, so its name participates in uniqueness like every other
+            // dispatch site. `action` and `searchAction` are independent: a lookup may
+            // carry both (Enter commits, typing searches).
+            if (field.searchAction)
+                recordAction(field.searchAction, enclosingForm, out);
             return;
         }
         case "checkbox": {

package/dist/tui.js

@@ -1254,6 +1254,26 @@ function FormView({ node, ctx }) {
 //                                B3 ships single-select; select-multiple semantics
 //                                are deferred (no native OpenTUI multi-select
 //                                widget; would need a custom focusable list — B5).
+//   lookup / lookup-multiple  → <text label> + <input value=the ID at `bind`> +
+//                                a <text> line listing the `selected` labels
+//                                (label ?? value, per the wire's "label omitted
+//                                = label equals value" rule). Both inputTypes get
+//                                the SAME layout; lookup-multiple joins its
+//                                selected labels with ", ".
+//                                🚨 The debounced `searchAction`, the popup
+//                                listbox, the chips, the roving tabindex, and the
+//                                aria-live region are DELIBERATELY NOT ported.
+//                                This is the ARCHITECTURE WORKING AS DESIGNED,
+//                                not a gap: `bind` holds the id and nothing else,
+//                                so — per the lookup design of record §6 — "an
+//                                agent sets `bind` to the id and never touches the
+//                                search UI. It does not need to know the label."
+//                                A terminal user does exactly what an agent does.
+//                                Everything omitted here is a browser/DOM concept
+//                                with no OpenTUI analog (the a11y spec is a
+//                                screen-reader contract that means nothing in a
+//                                terminal). Same honest-degradation precedent as
+//                                select-multiple → single-select above.
 //   checkbox                  → <text "[x] label" or "[ ] label"> — decorative
 //                                for B3 (toggle interactivity in B5).
 //   file                      → <text "{label}: [file: …]"> placeholder —
@@ -1327,6 +1347,27 @@ function FieldView({ node, ctx }) {
                         handleSubmit(next);
                     } }, `${node.name}::wire::${wireValue}`)] }));
     }
+    // ── lookup / lookup-multiple: honest degradation to a bound id input ───
+    // See the per-inputType layout contract in the header comment above for WHY
+    // this is a complete implementation for the terminal rather than a stub: the
+    // id is the only thing that round-trips, and typing it directly is precisely
+    // the agent-drivable path the design of record §6 describes. No search
+    // machinery is ported (no debounce, no searchAction dispatch, no popup, no
+    // chips, no live region) — those are DOM concepts, and the a11y baseline they
+    // implement is a screen-reader contract with no terminal meaning.
+    if (node.inputType === "lookup" || node.inputType === "lookup-multiple") {
+        // Read the display text from `selected` and ONLY from `selected` — never
+        // from `candidates`. That is the load-bearing invariant of the whole
+        // primitive (the label is view, server-owned, recomputed every render;
+        // `candidates` is the search result set and says nothing about what is
+        // currently chosen). `label ?? value` implements the wire rule that a label
+        // equal to its value is omitted — a free-form tag shows as its own id.
+        const selectedLabels = (node.selected ?? []).map((s) => s.label ?? s.value);
+        const selectedLine = selectedLabels.length > 0 ? selectedLabels.join(", ") : "(none selected)";
+        return (_jsxs("box", { flexDirection: "column", gap: 0, children: [_jsx("text", { fg: "#888888", children: label }), _jsx("input", { value: currentValue, placeholder: node.placeholder ?? "", focused: focused, onInput: (v) => ctx.setFieldValue(node.name, v), onSubmit: (v) => {
+                        handleSubmit(typeof v === "string" ? v : undefined);
+                    } }, `${node.name}::wire::${wireValue}`), _jsxs("text", { fg: "#888888", children: ["Selected: ", selectedLine] })] }));
+    }
     // ── checkbox: decorative glyph for B3 (toggle wiring is B5) ───────────
     if (node.inputType === "checkbox") {
         // Wire contract: checkbox-typed field's value is "true" | "false".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "5.1.2",
+  "version": "6.0.0",
   "description": "A server-driven UI framework where the wire format is structured enough that agents can build full-stack apps without ever opening a browser and all UI tests are pure unit tests with no browser runtime. Server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to DOM. Backend-agnostic \u2014 a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,8 @@
   "scripts": {
     "build": "tsc -b tsconfig.tui.json",
     "check:core-globals": "node scripts/check-core-platform-globals.mjs",
+    "check:test-types": "tsc -p tsconfig.test.json --noEmit",
+    "check:demo-types": "node scripts/check-demo-types.mjs",
     "check:aa-contrast": "node scripts/check-aa-contrast.mjs",
     "check:no-demo-style": "node scripts/check-no-demo-style.mjs",
     "check:theme-byte-identity": "node scripts/check-theme-byte-identity.mjs",