@ashley-shrok/viewmodel-shell 1.10.0 → 1.11.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/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.10.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); }