@ashley-shrok/viewmodel-shell 1.3.0 → 1.4.0

package/dist/browser.js

@@ -266,7 +266,7 @@ export class BrowserAdapter {
             return;
         }
         const el = document.createElement("section");
-        el.className = `vms-section${n.variant === "card" ? " vms-section--card" : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}`;
+        el.className = `vms-section${n.variant === "card" ? " vms-section--card" : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.action ? " vms-section--clickable" : ""}`;
         if (n.heading) {
             const h = document.createElement("h2");
             h.className = "vms-section__heading";
@@ -274,6 +274,45 @@ export class BrowserAdapter {
             el.appendChild(h);
         }
         this.kids(n.children, el, on);
+        // SectionNode.action — click-anywhere + keyboard + ARIA. Mirrors
+        // TableRow.action (1.1.0). Containment via stopPropagation on nested
+        // interactive controls AFTER kids() has rendered them.
+        if (n.action) {
+            const actionName = n.action.name;
+            el.tabIndex = 0;
+            el.setAttribute("role", "button");
+            // aria-label derivation: heading > flattened descendant text (capped) > "Card".
+            // Whitespace runs (textContent collapses across child elements, so we
+            // get long runs of spaces / newlines from the DOM tree) are collapsed
+            // to a single space — preserving normal in-text spacing like
+            // "Choose plan" intact instead of mangling it to "Choose · plan".
+            let ariaLabel = "";
+            if (n.heading && n.heading.trim().length > 0) {
+                ariaLabel = n.heading.trim();
+            }
+            else {
+                const text = (el.textContent ?? "").replace(/\s+/g, " ").trim();
+                ariaLabel = text.length > 0 ? text.slice(0, 200) : "Card";
+            }
+            el.setAttribute("aria-label", ariaLabel);
+            el.addEventListener("click", () => { on({ name: actionName }); });
+            el.addEventListener("keydown", (e) => {
+                if (e.key === "Enter") {
+                    on({ name: actionName });
+                }
+                else if (e.key === " " || e.key === "Spacebar") {
+                    e.preventDefault(); // suppress page scroll
+                    on({ name: actionName });
+                }
+            });
+            // Containment: clicks on nested interactive controls must NOT bubble to
+            // the section's click handler. Selectors mirror the TableRow.action
+            // wiring (per-row button / checkbox / linkLabel anchor) plus a catch-all
+            // for any anchor inside the card (LinkNode renders as <a>).
+            el.querySelectorAll(".vms-button, .vms-checkbox__input, .vms-checkbox, .vms-table__link, a[href]").forEach(ctrl => {
+                ctrl.addEventListener("click", (e) => { e.stopPropagation(); });
+            });
+        }
         parent.appendChild(el);
     }
     list(n, parent, on) {

package/dist/index.d.ts

@@ -86,6 +86,31 @@ export interface SectionNode {
     id?: string;
     /** When true, the section renders as a native `<details>`/`<summary>` disclosure widget (closed by default). Aesthetic, client-side primitive — the open/closed state is DOM-local and the server does NOT round-trip it (same conceptual model as draft text values in unsubmitted form inputs). The browser adapter snapshots `<details>.open` before each re-render and restores it after, keyed by `id ?? heading ?? "vms-section-anon"` (disambiguated by per-render ordinal); a re-key drops the preserved state (the documented escape hatch for rare server-driven expansion). The summary label is the section's `heading`; a headingless collapsible section uses the fallback string `"Show details"`. If a section needs to start open, do not mark it collapsible. Omitted/false = today's `<section>` rendering, byte-identical. */
     collapsible?: boolean;
+    /** Click-anywhere section dispatch primitive — mirrors `TableRow.action` (1.1.0)
+     *  at the section level. When set, the renderer makes the entire section
+     *  clickable AND keyboard-activatable (Enter / Space — Space preventDefaults
+     *  page scroll) AND exposes accessibility (role="button", tabindex=0,
+     *  aria-label derived from `heading` when set, else from joined text content
+     *  of descendants, else fallback `"Card"`). The per-section identity is
+     *  encoded in the action name (e.g. `select-card-1`) — no context field,
+     *  consistent with the Phase 6 wire. Clicks on nested ButtonNode / CheckboxNode /
+     *  LinkNode / cell `linkLabel` anchors INSIDE the section do NOT also fire
+     *  `action` (the renderer stops propagation on those targets).
+     *
+     *  Tree validation rejects two invalid combos at the server edge with
+     *  `invalid_tree`:
+     *    (a) `action` set together with `collapsible: true` on the same section
+     *        (a collapsible section's `<summary>` IS the click target; a clickable
+     *        card makes the whole section the click target — pick one).
+     *    (b) a SectionNode with `action` nested inside another SectionNode with
+     *        `action` (nested role="button" is an a11y violation; click-ownership
+     *        in the overlap is ambiguous). A styling-only `variant: "card"`
+     *        section (no `action`) with internal buttons inside a clickable card
+     *        is VALID — only nested `action` errors.
+     *
+     *  Omitted = today's section rendering, byte-identical (no class drift, no
+     *  extra attrs, no listeners). */
+    action?: ActionEvent;
     children: ViewNode[];
 }
 export interface ListNode {

package/dist/server.d.ts

@@ -15,6 +15,16 @@ export * from "./index.js";
  *   same enclosing form).
  */
 export declare function validateActionNames(vm: ViewNode): void;
+/**
+ * Walk a ViewNode tree and reject two invalid SectionNode.action combos:
+ * (a) action + collapsible:true on the same section, and (b) a clickable
+ * section nested inside another clickable section. Pure check — does not
+ * mutate the tree.
+ *
+ * @throws Error when either invalid combo is found. The message names the
+ *   offending section(s) by heading (or `(headingless)`).
+ */
+export declare function validateSectionAction(vm: ViewNode): void;
 export interface ActionPayload<TState> {
     name: string;
     state: TState;

package/dist/server.js

@@ -174,6 +174,107 @@ function collectActions(node, enclosingForm, out) {
 function recordAction(action, enclosingForm, out) {
     out.push({ name: action.name, enclosingForm });
 }
+// ─── SectionNode.action shape check (1.4.0 / 260614-9hq) ─────────────────────
+//
+// Two invalid combos a clickable-card primitive can produce at build time:
+//   (a) SectionNode.action set together with collapsible:true on the same
+//       section — a collapsible section's <summary> IS the click target; a
+//       clickable card makes the whole section the click target. Pick one.
+//   (b) A SectionNode with .action nested inside another SectionNode with
+//       .action — nested role="button" is an a11y violation, and
+//       click-ownership in the overlap is ambiguous.
+// A styling-only SectionNode { variant: "card" } (no .action) inside a
+// clickable card with internal buttons is VALID — only nested .action errors.
+//
+// Mirrors viewmodel-shell-dotnet/ViewModels.cs's
+// ViewTreeValidation.ValidateSectionAction. The createAction wrapper invokes
+// this alongside validateActionNames so a server-built tree that violates
+// either rule surfaces as a 500 with code "invalid_tree" before the response
+// leaves the wire.
+/**
+ * Walk a ViewNode tree and reject two invalid SectionNode.action combos:
+ * (a) action + collapsible:true on the same section, and (b) a clickable
+ * section nested inside another clickable section. Pure check — does not
+ * mutate the tree.
+ *
+ * @throws Error when either invalid combo is found. The message names the
+ *   offending section(s) by heading (or `(headingless)`).
+ */
+export function validateSectionAction(vm) {
+    walkForSectionAction(vm, null);
+}
+function walkForSectionAction(node, outerClickable) {
+    switch (node.type) {
+        case "page": {
+            const page = node;
+            for (const child of page.children)
+                walkForSectionAction(child, outerClickable);
+            return;
+        }
+        case "section": {
+            const section = node;
+            // (a) action + collapsible:true — invalid.
+            if (section.action != null && section.collapsible === true) {
+                const hdr = section.heading && section.heading.length > 0
+                    ? section.heading
+                    : "(headingless)";
+                throw new Error(`SectionNode '${hdr}' has both Action and Collapsible: true set. ` +
+                    "A collapsible section's summary IS the click target; a clickable card " +
+                    "makes the whole section the click target. Pick one.");
+            }
+            // (b) nested action-in-action — invalid.
+            if (section.action != null && outerClickable !== null) {
+                const innerHdr = section.heading && section.heading.length > 0
+                    ? section.heading
+                    : "(headingless)";
+                const outerHdr = outerClickable.heading && outerClickable.heading.length > 0
+                    ? outerClickable.heading
+                    : "(headingless)";
+                throw new Error(`Nested SectionNode.Action: inner section '${innerHdr}' is inside clickable outer ` +
+                    `section '${outerHdr}'. Nested role='button' elements are an accessibility violation, ` +
+                    "and click-ownership in the overlap is ambiguous. Use a styling-only inner section " +
+                    "(variant: 'card', no Action) with internal buttons instead.");
+            }
+            const nextOuter = section.action != null ? section : outerClickable;
+            for (const child of section.children)
+                walkForSectionAction(child, nextOuter);
+            return;
+        }
+        case "list": {
+            const list = node;
+            for (const child of list.children)
+                walkForSectionAction(child, outerClickable);
+            return;
+        }
+        case "list-item": {
+            const li = node;
+            for (const child of li.children)
+                walkForSectionAction(child, outerClickable);
+            return;
+        }
+        case "form": {
+            const form = node;
+            for (const child of form.children)
+                walkForSectionAction(child, outerClickable);
+            return;
+        }
+        case "modal": {
+            const modal = node;
+            for (const child of modal.children)
+                walkForSectionAction(child, outerClickable);
+            if (modal.footer) {
+                for (const child of modal.footer)
+                    walkForSectionAction(child, outerClickable);
+            }
+            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.
+        default:
+            return;
+    }
+}
 /** Parse a multipart/form-data action body — the wire format the TypeScript shell uses. */
 export function parseFormDataAction(formData) {
     const actionRaw = formData.get("_action");
@@ -374,6 +475,9 @@ export function createAction(handler) {
         if (result.vm) {
             try {
                 validateActionNames(result.vm);
+                // 1.4.0 — SectionNode.action shape checks (action+collapsible,
+                // nested action-in-action). Same invalid_tree exit path.
+                validateSectionAction(result.vm);
             }
             catch (err) {
                 return jsonResponse(errorEnvelope([{ message: err.message, code: ERR_CODES.INVALID_TREE }]), 500);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "1.3.0",
+  "version": "1.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

@@ -221,6 +221,19 @@ body {
   padding: var(--vms-space-md);
 }
 
+/* ── Section: clickable (1.4.0 — SectionNode.action click-anywhere primitive) ──
+   Mirrors the 1.1.0 .vms-table__row--clickable idiom one level up the tree.
+   Hover uses a 1px accent-dim ring (rather than a background swap — cards
+   already paint --vms-surface as their background, so a background change
+   would be invisible). :focus-visible outline lives OUTSIDE the box edge
+   (positive outline-offset) since a section is a box, not a table row. */
+.vms-section--clickable { cursor: pointer; }
+.vms-section--clickable:hover { box-shadow: 0 0 0 1px var(--vms-accent-dim); }
+.vms-section--clickable:focus-visible {
+  outline: 2px solid var(--vms-accent);
+  outline-offset: 2px;
+}
+
 /* ── Section: collapsible (1.2.0 — client-side disclosure via native <details>) ──
    Open/closed state is DOM-local; the BrowserAdapter snapshots and restores it
    across server-driven re-renders the same way it does for focus and scroll.