@ashley-shrok/viewmodel-shell 1.9.0 → 1.11.0

package/agent-skill.md

@@ -62,6 +62,7 @@ Optional success-path fields, which may appear alone or alongside `vm`/`state`:
 | `nextPollIn` | Milliseconds. Schedule a `{"name": "poll"}` dispatch after this delay. |
 | `busy` | Boolean. While `true`, drop user-initiated dispatches. Polls bypass. The next response that omits or sets `false` clears the lock. |
 | `preventUnload` | Boolean. While `true`, treat the page as having unsaved work — warn before navigating away. |
+| `rejected` | A SOFT (domain/validation) rejection — see below. The action was refused, but `vm`/`state` are still returned. |
 
 **Failure:**
 
@@ -71,6 +72,17 @@ Optional success-path fields, which may appear alone or alongside `vm`/`state`:
 
 `errors[].path` and `errors[].code` are optional. HTTP status is 4xx or 5xx on failure. Check `ok` once at the response edge; do not branch on HTTP status.
 
+**Soft rejections (`rejected`) — important for wire-driving agents.** `ok:false` means the framework could not give you a view. A *domain/validation* rejection is different: the app refused the action (e.g. "targets must be non-negative", "can't remove the only person") but it is still a normal `ok:true` render that preserves the user's input. So `ok` alone does NOT tell you the action succeeded — **on an `ok:true` response, also check for `rejected`.** When present:
+
+```json
+{ "ok": true, "vm": { /* … */ }, "state": { /* … */ },
+  "rejected": { "violations": [ { "path": "targets.protein", "message": "must be non-negative" } ] } }
+```
+
+- The write **did not take effect.** Do not treat it as success. Surface the violation(s); `vm`/`state` still hold the input the user typed, so you can correct and re-dispatch.
+- Each violation reuses the `errors[]` entry shape (`{ path?, message, code? }`). **`path` is optional**: present → the violation is bound to that field; **absent → it's a form/action-level rejection** with no single field (like the "only person" case).
+- `rejected` only appears on `ok:true`. It never coexists with `ok:false` (that channel carries no view).
+
 ## Side-effect verbs
 
 `sideEffects[]` entries each carry a `type` discriminator. Built-in verbs as of `viewmodel-shell/1.0`:

package/dist/browser.js

@@ -265,6 +265,29 @@ export class BrowserAdapter {
             parent.appendChild(el);
             return;
         }
+        // 1.11.0 — flyout:true overlay disclosure. The hover/focus sibling of
+        // collapsible's inline <details>: heading => focusable <button> trigger,
+        // children => an absolutely-positioned panel revealed on :hover /
+        // :focus-within (pure CSS — see default.css; no JS, no listeners, no
+        // round-tripped open state). Precedence: collapsible (checked above) wins,
+        // so reaching here means collapsible is not set; flyout in turn wins over
+        // link/action below. Omitted/false renders byte-identical to <section>.
+        if (n.flyout === true) {
+            const el = document.createElement("div");
+            el.className = `vms-section vms-section--flyout${n.variant === "card" ? " vms-section--card" : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}`;
+            const trigger = document.createElement("button");
+            trigger.type = "button";
+            trigger.className = "vms-section__trigger";
+            // Headingless fallback label — mirrors collapsible's "Show details".
+            trigger.textContent = n.heading ?? "Menu";
+            el.appendChild(trigger);
+            const panel = document.createElement("div");
+            panel.className = "vms-section__panel";
+            this.kids(n.children, panel, on);
+            el.appendChild(panel);
+            parent.appendChild(el);
+            return;
+        }
         // 1.5.0 — SectionNode.link URL-wrapper variant (issue #21). When set,
         // emit a wrapping <a href> element instead of <section> so every native
         // browser link affordance works for free (middle-click / Ctrl/Cmd-click

package/dist/index.d.ts

@@ -69,8 +69,8 @@ export interface PageNode {
     title?: string;
     /** Density of global spacing. Omitted or "comfortable" = current behavior (no modifier class). "compact" emits .vms-page--compact. Closed union (D-03). */
     density?: "comfortable" | "compact";
-    /** Layout preset arranging direct children. Omitted or "stack" = current vertical flow (no modifier class). "split" (equal 2-up), "cards" (uniform grid), "sidebar" (thin + wide app shell) emit .vms-page--{value}. Closed union (D-01/D-02; sidebar D-28). */
-    layout?: "stack" | "split" | "cards" | "sidebar";
+    /** Layout preset arranging direct children. Omitted or "stack" = current vertical flow (no modifier class). "split" (equal 2-up), "cards" (uniform grid), "sidebar" (thin + wide app shell), "row" (left-aligned wrapping horizontal row; items hug content) emit .vms-page--{value}. Closed union (D-01/D-02; sidebar D-28; row D-30). */
+    layout?: "stack" | "split" | "cards" | "sidebar" | "row";
     /** Page-shell max-width override. Omitted = framework default cap (`--vms-page-max`, 1080px). "wide" = `--vms-page-max-wide` (1440px default), for data-heavy pages with wide tables. "full" = uncapped (max-width: none), for full-bleed dashboards. TUI ignores this (terminals fill naturally). Closed union (D-13 / issue #13). */
     width?: "wide" | "full";
     children: ViewNode[];
@@ -80,12 +80,34 @@ export interface SectionNode {
     heading?: string;
     /** Section surface variant. Omitted = current behavior (no modifier class). "card" emits .vms-section--card. Closed union (D-03). */
     variant?: "card";
-    /** Layout preset arranging direct children. Omitted or "stack" = current vertical flow (no modifier class). "split" (equal 2-up), "cards" (uniform grid), "sidebar" (thin + wide app shell) emit .vms-section--{value}. Closed union (D-01/D-02; sidebar D-28). */
-    layout?: "stack" | "split" | "cards" | "sidebar";
+    /** Layout preset arranging direct children. Omitted or "stack" = current vertical flow (no modifier class). "split" (equal 2-up), "cards" (uniform grid), "sidebar" (thin + wide app shell), "row" (left-aligned wrapping horizontal row; items hug content) emit .vms-section--{value}. Closed union (D-01/D-02; sidebar D-28; row D-30). */
+    layout?: "stack" | "split" | "cards" | "sidebar" | "row";
     /** Optional stable preservation key for the renderer's collapsible-section open-state snapshot. Used only when `collapsible: true`. Provide when `heading` isn't unique within a page or is absent — otherwise the renderer falls back to `heading ?? "vms-section-anon"`, disambiguated by per-render ordinal. Omitted = use the heading fallback. */
     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;
+    /** When true, the section renders as an OVERLAY disclosure ("flyout") — the
+     *  hover/focus sibling of `collapsible`'s inline `<details>` reveal. The
+     *  `heading` becomes a focusable `<button class="vms-section__trigger">`
+     *  trigger; the `children` are wrapped in a `<div class="vms-section__panel">`
+     *  that is absolutely positioned and revealed on `:hover` / `:focus-within`
+     *  (pure CSS — no JavaScript, no state machine). Hover (desktop), tap-to-focus
+     *  (touch), and keyboard Tab-to-trigger (a11y) all reveal it for free; it hides
+     *  on blur / pointer-leave. Unlike `collapsible`, the open state is EPHEMERAL
+     *  (driven by `:hover`/`:focus-within`), so it is NOT round-tripped and NOT
+     *  snapshotted across re-renders — there is nothing to preserve.
+     *
+     *  Use a flyout (overlay) rather than `collapsible` (inline) when the revealed
+     *  content should float over siblings instead of pushing them — e.g. a menu
+     *  inside a `layout:"row"` bar, where an inline disclosure would shove the bar
+     *  open. A headingless flyout uses the fallback trigger label `"Menu"`.
+     *
+     *  Mutually exclusive with the other section modes; the renderer resolves a
+     *  fixed precedence and never combines them: `collapsible` > `flyout` > `link`
+     *  > `action`. So `collapsible: true` wins if both are set, and a flyout
+     *  section ignores `link`/`action`. Omitted/false = today's `<section>`
+     *  rendering, byte-identical (no class drift, no extra elements). */
+    flyout?: 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

package/dist/server.d.ts

@@ -53,9 +53,29 @@ export interface ShellResponseBody<TState> {
      *  clear the state. Naturally paired with `preventUnload` for long-running
      *  server actions. */
     busy?: boolean;
+    /** A SOFT (domain/validation) rejection that rides on an ok:true render —
+     *  the action was refused but vm/state are still returned so the form keeps
+     *  the user's input. Distinct from the ok:false + errors[] channel (which
+     *  carries NO view): ok:false = "no view for you"; ok:true + rejected =
+     *  "here's your view back, but the action did not take". An agent driving the
+     *  wire checks `rejected` IN ADDITION to `ok`. Each violation reuses the
+     *  ErrorEntry {path?, message, code?} shape; `path` is OPTIONAL — a violation
+     *  with no path is a form/action-level rejection (vs field-bound when set). */
+    rejected?: ShellRejection;
+}
+/** Wrapper for a soft-validation rejection on an ok:true response. */
+export interface ShellRejection {
+    violations: ErrorEntry[];
 }
 /** Build a redirect response (Vm and State omitted; shell navigates the browser). */
 export declare function shellRedirect<TState = unknown>(url: string): ShellResponseBody<TState>;
+/** Attach a soft-validation rejection to a normal re-render. Spread alongside
+ *  vm/state — unlike a redirect, a rejection KEEPS the view:
+ *    return { vm, state, ...shellRejection([{ path: "x", message: "…" }]) };
+ *  Mirrors the C# `ShellResponse<T>.WithRejection(...)` fluent helper. */
+export declare function shellRejection(violations: ErrorEntry[]): {
+    rejected: ShellRejection;
+};
 /** Side-effect factories matching the C# ShellSideEffect static methods. */
 export declare const shellSideEffect: {
     setLocalStorage: (key: string, value: string) => ShellSideEffect;

package/dist/server.js

@@ -379,6 +379,13 @@ export function parseJsonAction(body) {
 export function shellRedirect(url) {
     return { redirect: url };
 }
+/** Attach a soft-validation rejection to a normal re-render. Spread alongside
+ *  vm/state — unlike a redirect, a rejection KEEPS the view:
+ *    return { vm, state, ...shellRejection([{ path: "x", message: "…" }]) };
+ *  Mirrors the C# `ShellResponse<T>.WithRejection(...)` fluent helper. */
+export function shellRejection(violations) {
+    return { rejected: { violations } };
+}
 /** Side-effect factories matching the C# ShellSideEffect static methods. */
 export const shellSideEffect = {
     setLocalStorage: (key, value) => ({ type: "set-local-storage", key, value }),

package/dist/tui.js

@@ -781,6 +781,11 @@ function layoutProps(layout, _sidebarFraction) {
             return { flexDirection: "row", gap: 1, flexGrow: 1, flexShrink: 1 };
         case "cards":
             return { flexDirection: "row", flexWrap: "wrap", gap: 1 };
+        case "row":
+            // 1.11.0 — left-aligned wrapping horizontal row; items hug content.
+            // (Section flyout has no TUI overlay; it degrades to a plain labeled
+            // section — SectionView ignores the flag and renders children inline.)
+            return { flexDirection: "row", flexWrap: "wrap", gap: 1 };
         case "sidebar":
             return { flexDirection: "row", gap: 1, flexGrow: 1, flexShrink: 1 };
         case "stack":

package/package.json

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

@@ -213,6 +213,21 @@ body {
 .vms-page--sidebar > .vms-page__title,
 .vms-section--sidebar > .vms-section__heading { flex: 0 0 100%; }
 
+/* ── Layout preset: row (D-30 / 1.11.0) — left-aligned wrapping horizontal row;
+   children hug their content (no forced grow), wrap to the next line on overflow.
+   The general horizontal-row primitive — a navbar composes from this + flyout.
+   Title/heading takes its own full-width row, like the other presets. gap
+   inherited from .vms-page/.vms-section — NOT redeclared. ── */
+.vms-page--row,
+.vms-section--row {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  align-items: center;
+}
+.vms-page--row > .vms-page__title,
+.vms-section--row > .vms-section__heading { flex: 0 0 100%; }
+
 /* ── Section variant: card (THEME-04) — grouped surface, existing seam vars ── */
 .vms-section--card {
   background: var(--vms-surface);
@@ -271,6 +286,57 @@ body {
   outline-offset: 2px;
 }
 
+/* ── Section: flyout (1.11.0 — overlay disclosure, the hover/focus sibling of
+   collapsible) ── The heading renders as a focusable .vms-section__trigger button;
+   the children are wrapped in an absolutely-positioned .vms-section__panel revealed
+   on :hover / :focus-within. Pure CSS — hover (desktop), tap-to-focus (touch), and
+   Tab-to-trigger (keyboard a11y) all reveal it; it hides on blur / pointer-leave.
+   No JS, no round-tripped open state. The panel overlays (out of flow) so a flyout
+   inside a .vms-section--row bar does not reflow its siblings. */
+.vms-section--flyout {
+  position: relative;
+  flex-direction: column;   /* trigger stacks above the (absolute) panel; wrapper hugs the trigger */
+  align-items: flex-start;
+}
+.vms-section__trigger {
+  font-size: var(--vms-text-xs);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--vms-text-muted);
+  cursor: pointer;
+  background: none;
+  border: none;
+  padding: 0;
+  font-family: inherit;
+}
+.vms-section__trigger:focus-visible {
+  outline: 2px solid var(--vms-accent);
+  outline-offset: 2px;
+}
+.vms-section__panel {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  z-index: 50;
+  min-width: max-content;
+  display: flex;
+  flex-direction: column;
+  gap: var(--vms-space-sm);
+  margin-top: var(--vms-space-xs);
+  padding: var(--vms-space-sm);
+  background: var(--vms-surface);
+  border: 1px solid var(--vms-border);
+  border-radius: var(--vms-radius);
+  visibility: hidden;
+  opacity: 0;
+  transition: opacity var(--vms-t);
+}
+.vms-section--flyout:hover > .vms-section__panel,
+.vms-section--flyout:focus-within > .vms-section__panel {
+  visibility: visible;
+  opacity: 1;
+}
+
 /* ── Stat bar ── */
 .vms-stat-bar { display: flex; gap: var(--vms-space-lg); flex-wrap: wrap; }
 .vms-stat-bar__item { display: flex; align-items: baseline; gap: var(--vms-space-xs); }