@ashley-shrok/viewmodel-shell 3.2.1 → 3.4.0

package/README.md

@@ -33,7 +33,7 @@ const shell = new ViewModelShell({
 shell.load();
 ```
 
-If your backend is .NET: copy `demo/Tasks/AspNetCore/ViewModels.cs` from the [GitHub repo](https://github.com/ashley-shrok/ViewModelShell) into your project and update the namespace — that file is the full backend record set (`ViewNode`, `PageNode`, `FormNode`, `ShellResponse<TState>`, `ActionPayload<TState>`, etc.).
+If your backend is .NET: install the [`AshleyShrok.ViewModelShell`](https://www.nuget.org/packages/AshleyShrok.ViewModelShell) NuGet package (`dotnet add package AshleyShrok.ViewModelShell`). It ships the full backend record set under the `ViewModelShell` namespace (`ViewNode`, `PageNode`, `FormNode`, `ShellResponse<TState>`, `ActionPayload<TState>`, etc.) — version-aligned with this npm package on major.minor.
 
 For other backends, implement the same JSON shape: a `GET` returning `{ vm, state }`, and a `POST` that takes `multipart/form-data` with `_action` and `_state` form fields and returns the next `{ vm, state }`. See [AGENTS.md](https://github.com/ashley-shrok/ViewModelShell/blob/main/AGENTS.md) for the full wire format.
 

package/dist/browser.d.ts

@@ -60,6 +60,11 @@ export declare class BrowserAdapter implements Adapter {
      *  When `action` is set, it fires on Enter (text-like) or change (select) —
      *  the new value is already in state by that point. */
     private field;
+    /** Forms-completeness (3.4.0) — apply disabled/readonly to the control and
+     *  render help + error text below it, wiring aria-describedby / aria-invalid.
+     *  Runs on the main field path (the hidden + checkbox-FieldNode variants
+     *  return before this). */
+    private decorateField;
     /** CheckboxNode (standalone, immediate-dispatch) — bound boolean; on toggle,
      *  write to state then dispatch the action name (if any). */
     private checkbox;

package/dist/browser.js

@@ -240,6 +240,18 @@ export class BrowserAdapter {
             case "copy-button": return this.copyButton(n, parent);
             case "divider": return this.divider(n, parent);
             case "fits": return this.fits(n, parent, on);
+            default: {
+                // Fail loud, not silent (AGENTS.md: "Nothing important fails quietly").
+                // Runtime trees are server-controlled JSON, so an unknown/forward-version
+                // node type CAN reach here at runtime even though the union is
+                // exhaustive at compile time. We keep rendering the rest of the tree
+                // (forward-compatible, like unknown sideEffect types) but warn so the
+                // node doesn't just vanish without a trace.
+                const unknownType = n.type;
+                console.warn(`[viewmodel-shell] Unknown node type ${JSON.stringify(unknownType)} — ` +
+                    `rendering nothing for it. The client may be older than the server's tree.`);
+                return;
+            }
         }
     }
     kids(nodes, parent, on) {
@@ -760,8 +772,61 @@ export class BrowserAdapter {
             }
             wrapper.appendChild(inp);
         }
+        this.decorateField(wrapper, n);
         parent.appendChild(wrapper);
     }
+    /** Forms-completeness (3.4.0) — apply disabled/readonly to the control and
+     *  render help + error text below it, wiring aria-describedby / aria-invalid.
+     *  Runs on the main field path (the hidden + checkbox-FieldNode variants
+     *  return before this). */
+    decorateField(wrapper, n) {
+        const control = wrapper.querySelector(".vms-field__input");
+        if (n.disabled) {
+            if (control)
+                control.disabled = true;
+            wrapper.classList.add("vms-field--disabled");
+        }
+        if (n.readonly && control && "readOnly" in control) {
+            control.readOnly = true;
+        }
+        // Native input constraints — min/max/step on <input>, maxLength on
+        // <input>/<textarea>. Strings pass straight to the attribute.
+        if (control instanceof HTMLInputElement) {
+            if (n.min != null)
+                control.min = n.min;
+            if (n.max != null)
+                control.max = n.max;
+            if (n.step != null)
+                control.step = n.step;
+        }
+        if (n.maxLength != null &&
+            (control instanceof HTMLInputElement || control instanceof HTMLTextAreaElement)) {
+            control.maxLength = n.maxLength;
+        }
+        const describedBy = [];
+        if (n.help != null && n.help !== "") {
+            const helpEl = document.createElement("div");
+            helpEl.className = "vms-field__help";
+            helpEl.id = `vms-${n.name}-help`;
+            helpEl.textContent = n.help;
+            wrapper.appendChild(helpEl);
+            describedBy.push(helpEl.id);
+        }
+        if (n.error != null && n.error !== "") {
+            wrapper.classList.add("vms-field--error");
+            const errEl = document.createElement("div");
+            errEl.className = "vms-field__error";
+            errEl.id = `vms-${n.name}-error`;
+            errEl.setAttribute("role", "alert");
+            errEl.textContent = n.error;
+            wrapper.appendChild(errEl);
+            describedBy.push(errEl.id);
+            control?.setAttribute("aria-invalid", "true");
+        }
+        if (control && describedBy.length > 0) {
+            control.setAttribute("aria-describedby", describedBy.join(" "));
+        }
+    }
     /** CheckboxNode (standalone, immediate-dispatch) — bound boolean; on toggle,
      *  write to state then dispatch the action name (if any). */
     checkbox(n, parent, on) {
@@ -771,6 +836,11 @@ export class BrowserAdapter {
         inp.type = "checkbox";
         inp.className = "vms-checkbox__input";
         inp.name = n.name;
+        // Stable id so keyboard focus survives a re-render (poll or action). The
+        // wrapping <label> gives the click/label association; the id is purely for
+        // focus restore. Namespaced distinctly from field() ids (vms-${name}) to
+        // avoid an id collision when a field and a standalone checkbox share a name.
+        inp.id = `vms-checkbox-${n.name}`;
         inp.checked = Boolean(this.sa.read(n.bind));
         const mark = document.createElement("span");
         mark.className = "vms-checkbox__mark";
@@ -792,9 +862,16 @@ export class BrowserAdapter {
     button(n, parent, on) {
         const btn = document.createElement("button");
         btn.type = "button";
-        btn.className = `vms-button${n.emphasis ? ` vms-button--${n.emphasis}` : ""}${n.tone ? ` vms-button--${n.tone}` : ""}${n.size ? ` vms-button--${n.size}` : ""}${n.width === "full" ? " vms-button--full" : ""}`;
+        btn.className = `vms-button${n.emphasis ? ` vms-button--${n.emphasis}` : ""}${n.tone ? ` vms-button--${n.tone}` : ""}${n.size ? ` vms-button--${n.size}` : ""}${n.width === "full" ? " vms-button--full" : ""}${n.disabled ? " vms-button--disabled" : ""}`;
         btn.textContent = n.label;
+        if (n.disabled)
+            btn.disabled = true;
         btn.addEventListener("click", () => {
+            // Forms-completeness (3.4.0): a disabled button never dispatches. (Native
+            // `disabled` already suppresses the click, but guard anyway in case the
+            // attribute was cleared out-of-band.)
+            if (n.disabled)
+                return;
             // pendingLabel: instant client-side feedback. Swap text + add
             // .vms-button--pending BEFORE handing off to the dispatcher. On
             // success the next render replaces the button entirely. On dispatch
@@ -868,6 +945,9 @@ export class BrowserAdapter {
             const btn = document.createElement("button");
             btn.className = `vms-tabs__tab${tab.value === n.selected ? " vms-tabs__tab--active" : ""}`;
             btn.textContent = tab.label;
+            // Stable id so focus survives the re-render a tab click triggers (and any
+            // poll re-render) — render()'s restore keys off id.
+            btn.id = `vms-tab-${n.bind}-${tab.value}`;
             btn.setAttribute("role", "tab");
             btn.setAttribute("aria-selected", String(tab.value === n.selected));
             btn.addEventListener("click", () => {
@@ -887,16 +967,25 @@ export class BrowserAdapter {
             cls += ` vms-image--${n.shape}`;
         img.className = cls;
         img.src = n.src;
-        if (n.alt != null)
-            img.alt = n.alt;
+        // Always set alt: a present alt for meaningful images, an explicit empty
+        // string for decorative ones (alt="" tells assistive tech to skip it,
+        // whereas a missing alt may make it announce the src/URL).
+        img.alt = n.alt ?? "";
         parent.appendChild(img);
     }
     progress(n, parent) {
         const track = document.createElement("div");
         track.className = "vms-progress";
+        // Clamp to 0–100 (the documented range): an out-of-range value would
+        // otherwise overflow the track or render a negative-width bar.
+        const value = Math.max(0, Math.min(100, n.value));
+        track.setAttribute("role", "progressbar");
+        track.setAttribute("aria-valuemin", "0");
+        track.setAttribute("aria-valuemax", "100");
+        track.setAttribute("aria-valuenow", String(value));
         const bar = document.createElement("div");
         bar.className = "vms-progress__bar";
-        bar.style.width = `${n.value}%`;
+        bar.style.width = `${value}%`;
         track.appendChild(bar);
         parent.appendChild(track);
     }
@@ -1018,6 +1107,12 @@ export class BrowserAdapter {
                     inp.type = "text";
                     inp.className = "vms-table__filter-input";
                     inp.dataset.col = col.key;
+                    // Stable id so render()'s focus+caret restore can re-find this input
+                    // after a re-render — critical because a silent poll can fire mid-
+                    // keystroke while the user is typing a filter (the canonical
+                    // workflow-table pattern). Without an id the value survives (it's
+                    // bound state) but focus/caret are lost on every poll tick.
+                    inp.id = `vms-tablefilter-${col.key}`;
                     const bindPath = n.filterBinds?.[col.key];
                     const bound = bindPath != null ? this.sa.read(bindPath) : undefined;
                     inp.value = bound != null

package/dist/index.d.ts

@@ -192,7 +192,7 @@ export interface ListNode {
 export interface ListItemNode {
     type: "list-item";
     id?: string;
-    /** Row lifecycle/selection STATE (NOT severity — that's `tone`). A freeform, app-extensible token; the framework ships styling for `active` (selected), `done`, `disabled`, `high` (priority), `running`, `moving`. Appended as a BEM modifier: vms-list-item--{state}. Orthogonal to `tone` (a row can be `state:"active"` AND `tone:"danger"`). */
+    /** Row lifecycle/selection STATE (NOT severity — that's `tone`). A freeform, app-extensible token; the framework ships list-item styling for `active` (selected), `done`, `disabled`, and `high` (priority). Appended as a BEM modifier: vms-list-item--{state}. An unrecognized state renders an unstyled class (it still round-trips; just no shipped rule). Orthogonal to `tone` (a row can be `state:"active"` AND `tone:"danger"`). (TableRow additionally ships a `running` style; ListItem does not yet.) */
     state?: string;
     /** Semantic intent/severity — the universal status tone axis (closed). Emits .vms-list-item--{tone} (colored accent border, reusing the shared tokens). Omitted = neutral. */
     tone?: "danger" | "warning" | "success" | "info";
@@ -241,6 +241,35 @@ export interface FieldNode {
     label?: string;
     placeholder?: string;
     required?: boolean;
+    /** Disables the control (greys it out, blocks input, excludes it from form
+     *  submission). Server-owned. Emits `.vms-field--disabled` on the wrapper +
+     *  the native `disabled` attribute. Omitted = enabled. */
+    disabled?: boolean;
+    /** Read-only: the value is shown and submitted but the user can't edit it
+     *  (distinct from `disabled`, which also greys out + excludes from submit).
+     *  Text-like inputs + textarea only. Emits the native `readonly` attribute. */
+    readonly?: boolean;
+    /** Per-field validation error message, rendered inline below the control as
+     *  `.vms-field__error` (role="alert"); also sets the wrapper's
+     *  `.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. */
+    error?: string;
+    /** Hint/help text rendered below the control as `.vms-field__help` and wired
+     *  into the control's `aria-describedby`. Omitted = no hint. */
+    help?: string;
+    /** `min`/`max`/`step` passed through to the native input attribute for
+     *  `number`/`range`/date-time inputs. STRINGS (HTML-attribute semantics): a
+     *  numeric bound (`"0"`), a date bound (`"2020-01-01"`), and `step` also
+     *  accepts `"any"`. Typed as strings (not numbers) so the wire stays
+     *  byte-identical across backends. Omitted = no constraint. */
+    min?: string;
+    max?: string;
+    step?: string;
+    /** Maximum input length (characters) for text-like inputs + textarea →
+     *  native `maxlength`. Integer. Omitted = no cap. */
+    maxLength?: number;
     options?: Array<{
         value: string;
         label: string;
@@ -279,6 +308,10 @@ export interface ButtonNode {
      *  `block`, Chakra `width="full"`). Emits `.vms-button--full`. Omitted/`"auto"`
      *  = content-width (the default hug). Orthogonal to emphasis/tone/size. */
     width?: "auto" | "full";
+    /** Disables the button — greys it out (`.vms-button--disabled` + native
+     *  `disabled`) and the renderer will NOT dispatch its action on click.
+     *  Server-owned (e.g. a submit gated on a precondition). Omitted = enabled. */
+    disabled?: boolean;
     /** Transient label shown from click until the dispatch resolves (response
      *  arrives or dispatch errors). Mirrors `CopyButtonNode.copiedLabel`'s
      *  lifecycle pattern at a different beat: shown DURING the round-trip

package/dist/index.js

@@ -311,9 +311,21 @@ export class ViewModelShell {
             }
             return;
         }
-        this.currentVm = body.vm;
-        this.currentState = body.state;
-        this.options.adapter.render(body.vm, (a) => this.dispatch(a), this.stateAccessForAdapter());
+        // C2 (3.3.0) — a non-redirect response MAY legitimately omit `vm` (e.g. a
+        // side-effects-only or poll-keepalive response: "persist to storage and
+        // keep polling, but don't rebuild the view"). Do NOT blank the screen by
+        // rendering `undefined` — keep the current view, update state only if the
+        // server sent fresh state, and still schedule the next poll. Render only
+        // when a fresh tree actually arrived.
+        if (body.vm != null) {
+            this.currentVm = body.vm;
+            if (body.state !== undefined)
+                this.currentState = body.state;
+            this.options.adapter.render(body.vm, (a) => this.dispatch(a), this.stateAccessForAdapter());
+        }
+        else if (body.state !== undefined) {
+            this.currentState = body.state;
+        }
         this.schedulePoll(body.nextPollIn);
     }
     schedulePoll(nextPollIn) {

package/dist/server.js

@@ -180,6 +180,16 @@ function collectActions(node, enclosingForm, out) {
             }
             return;
         }
+        case "fits": {
+            // FitsNode.children are full ViewNode[] (can hold forms, buttons,
+            // sections with action/link) — the renderer picks ONE at runtime but
+            // every candidate ships on the wire, so all must be validated. Without
+            // this arm the entire fits subtree skipped action-name uniqueness checks.
+            const fits = node;
+            for (const child of fits.children)
+                collectActions(child, enclosingForm, out);
+            return;
+        }
         // Nodes with no dispatch-bearing actions of their own:
         //   text, link, image, stat-bar, progress, copy-button
         default:
@@ -328,6 +338,14 @@ function walkForSectionAction(node, outerInteractive) {
             }
             return;
         }
+        case "fits": {
+            // A fits candidate can itself be a section with action/link (or contain
+            // one), so the nested-section-interaction rules must descend here too.
+            const fits = node;
+            for (const child of fits.children)
+                walkForSectionAction(child, outerInteractive);
+            return;
+        }
         // Leaf-like nodes (field, checkbox, button, text, link, image, stat-bar,
         // tabs, progress, table, copy-button) carry no SectionNode descendants —
         // TableNode rows hold strings + per-row controls, not sections.
@@ -369,6 +387,18 @@ export function parseJsonAction(body) {
     if (typeof parsed.name !== "string" || parsed.name === "") {
         throw new Error("Missing required 'name' field in action payload");
     }
+    // C4 (3.3.0) — require `state`. The shell always sends it, but a hand-rolled
+    // curl/agent caller that posts `{name}` only would otherwise run the handler
+    // with `undefined` state and crash on the first property access → a 500
+    // uncaught_exception, the wrong error class. A missing/null state is a
+    // malformed request the caller can fix, so surface it as a 400 parse_error
+    // (this throw is caught by createAction's parse arm). An EMPTY object `{}` is
+    // a valid state and is left alone.
+    if (parsed.state == null) {
+        throw new Error("Missing required 'state' field in action payload. The action wire is " +
+            "{name, state} — echo back the state from the GET response (or the prior " +
+            "action response); send {} only if the app's state really is empty.");
+    }
     return {
         name: parsed.name,
         state: parsed.state,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "3.2.1",
+  "version": "3.4.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 — a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",

package/styles/default.css

@@ -296,7 +296,7 @@ body {
 .vms-maxw--three-quarters { max-inline-size: 75%; }
 .vms-maxw--prose          { max-inline-size: min(65ch, 100%); }
 
-/* ── Layout preset: switcher (SWITCH-01/02 / 1.13.0) — the Every-Layout Switcher,
+/* ── Layout preset: switcher (SWITCH-01/02 / npm 1.12.0) — the Every-Layout Switcher,
    zero @media. N equal items flip all-row ↔ all-stack ATOMICALLY via a negative
    `flex-basis`: above the threshold the basis `(threshold - 100%) * 999` goes
    hugely negative → clamped to 0 → all children share one row; below it the
@@ -494,6 +494,27 @@ body {
 textarea.vms-field__input { min-height: 80px; }
 select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl); }
 
+/* Forms-completeness (3.4.0) — help/error text + disabled/readonly/error states.
+   help is the muted hint; error is the danger message (role="alert"). */
+.vms-field__help  { font-size: var(--vms-text-sm); color: var(--vms-text-muted); }
+.vms-field__error { font-size: var(--vms-text-sm); color: var(--vms-error); }
+.vms-field--error .vms-field__input { border-color: var(--vms-error); }
+.vms-field--error .vms-field__input:focus {
+  border-color: var(--vms-error);
+  box-shadow: 0 0 0 3px var(--vms-error-glow);
+}
+.vms-field__input:disabled,
+.vms-field--disabled .vms-field__input {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+.vms-field--disabled .vms-field__label { opacity: 0.7; }
+/* read-only: editable-looking but visibly inert background (not greyed like disabled). */
+.vms-field__input:read-only:not([type="file"]) {
+  background: color-mix(in srgb, var(--vms-surface) 70%, var(--vms-border));
+  cursor: default;
+}
+
 /* Code editor field — monospaced, tab-aware, no spell-check chrome.
    Apps add syntax highlighting via .vms-field--code-{language} hooks. */
 .vms-field__input--code {
@@ -617,6 +638,14 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
   pointer-events: none;
 }
 
+/* Forms-completeness (3.4.0) — server-declared disabled button. */
+.vms-button:disabled,
+.vms-button--disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
 /* Inside a list item, a danger button is treated as the row's "X" affordance:
    muted and hidden until the row is hovered, then visible and red on hover. */
 .vms-list-item .vms-button--danger {