@ashley-shrok/viewmodel-shell 3.2.0 → 3.3.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.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) {
@@ -771,6 +783,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";
@@ -868,6 +885,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 +907,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 +1047,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";

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.0",
+  "version": "3.3.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
@@ -439,6 +439,14 @@ body {
   flex-wrap: wrap;
 }
 .vms-form--inline > .vms-field { flex: 1 1 12rem; }
+/* #23 — inline forms bottom-align their row (align-items: flex-end), but the
+   base align-self: flex-start on the implicit submit button and the buttons[]
+   row escapes that (an item's align-self beats the parent's align-items), so
+   the submit would top-anchor while the fields hang at the bottom. Drop those
+   direct children back to auto so the parent's flex-end wins — the same
+   override the modal footer already applies to .vms-button. */
+.vms-form--inline > .vms-button,
+.vms-form--inline > .vms-form__buttons { align-self: auto; }
 /* Multi-action submit buttons row (0.10.0 / #15) — groups the form's
    buttons[] entries on one line, like a dialog action bar. align-self
    flex-start keeps the row from stretching full-width in the stacked form. */