@ashley-shrok/viewmodel-shell 6.0.0 → 6.2.0

package/dist/browser.js

@@ -832,6 +832,8 @@ export class BrowserAdapter {
             const el = document.createElement("details");
             el.className = `vms-section vms-section--collapsible${n.variant === "card" ? " vms-section--card" : ""}${n.tone ? ` vms-section--${n.tone}` : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.fill === true ? " vms-section--fill" : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}${n.alignSelf ? ` vms-self--${n.alignSelf}` : ""}${n.maxWidth ? ` vms-maxw--${n.maxWidth}` : ""}`;
             el.dataset.sectionKey = finalKey;
+            if (n.id)
+                el.id = n.id; // addressable DOM id (e.g. CopyButtonNode.copyTargetId target)
             // Initial render is always closed — the post-render restore loop in
             // render() re-applies `open=true` for keys the user had open before.
             const summary = document.createElement("summary");
@@ -856,6 +858,8 @@ export class BrowserAdapter {
             const a = document.createElement("a");
             a.className = `vms-section vms-section--linked${n.variant === "card" ? " vms-section--card" : ""}${n.tone ? ` vms-section--${n.tone}` : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.fill === true ? " vms-section--fill" : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}${n.alignSelf ? ` vms-self--${n.alignSelf}` : ""}${n.maxWidth ? ` vms-maxw--${n.maxWidth}` : ""}`;
             a.href = n.link.url;
+            if (n.id)
+                a.id = n.id; // addressable DOM id (e.g. CopyButtonNode.copyTargetId target)
             // Mirror LinkNode's external-attribute pattern (browser.ts ~line 666)
             // byte-for-byte: target=_blank + rel=noopener noreferrer when external.
             if (n.link.external) {
@@ -899,6 +903,8 @@ export class BrowserAdapter {
         }
         const el = document.createElement("section");
         el.className = `vms-section${n.variant === "card" ? " vms-section--card" : ""}${n.tone ? ` vms-section--${n.tone}` : ""}${n.layout && n.layout !== "stack" ? ` vms-section--${n.layout}` : ""}${n.fill === true ? " vms-section--fill" : ""}${n.arrange ? ` vms-arrange--${n.arrange}` : ""}${n.align ? ` vms-align--${n.align}` : ""}${n.threshold ? ` vms-switch--${n.threshold}` : ""}${n.limit ? ` vms-switch-limit--${n.limit}` : ""}${n.minItem ? ` vms-cards-min--${n.minItem}` : ""}${n.alignSelf ? ` vms-self--${n.alignSelf}` : ""}${n.maxWidth ? ` vms-maxw--${n.maxWidth}` : ""}${n.action ? " vms-section--clickable" : ""}`;
+        if (n.id)
+            el.id = n.id; // addressable DOM id (e.g. CopyButtonNode.copyTargetId target)
         // SectionNode.followTail — mark this as an append-only feed so render()'s
         // snapshot/restore keeps its newest content in view (see render() + the
         // FOLLOW_TAIL_STICK_THRESHOLD_PX constant). No CSS/class — the scroll comes
@@ -954,8 +960,8 @@ export class BrowserAdapter {
         parent.appendChild(el);
     }
     list(n, parent, on) {
-        const ul = document.createElement("ul");
-        ul.className = "vms-list";
+        const ul = document.createElement(n.ordered ? "ol" : "ul");
+        ul.className = `vms-list${n.ordered ? " vms-list--ordered" : ""}`;
         if (n.id)
             ul.id = n.id;
         this.kids(n.children, ul, on);
@@ -3274,25 +3280,67 @@ export class BrowserAdapter {
         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.textContent = n.label ?? "Copy";
-        btn.addEventListener("click", () => {
-            const write = navigator.clipboard?.writeText(n.text);
+        const showCopied = () => {
+            btn.textContent = n.copiedLabel ?? "Copied!";
+            setTimeout(() => { btn.textContent = n.label ?? "Copy"; }, 1500);
+        };
+        // Plain-text copy (today's behavior, unchanged): async writeText with the
+        // execCommand fallback for engines without the async Clipboard API.
+        const copyPlain = (text) => {
+            const write = navigator.clipboard?.writeText(text);
             if (write) {
-                write.then(() => {
-                    btn.textContent = n.copiedLabel ?? "Copied!";
-                    setTimeout(() => { btn.textContent = n.label ?? "Copy"; }, 1500);
-                }).catch(() => {
-                    if (legacyCopy(n.text)) {
-                        btn.textContent = n.copiedLabel ?? "Copied!";
-                        setTimeout(() => { btn.textContent = n.label ?? "Copy"; }, 1500);
-                    }
-                });
+                write.then(showCopied).catch(() => { if (legacyCopy(text))
+                    showCopied(); });
             }
             else {
-                if (legacyCopy(n.text)) {
-                    btn.textContent = n.copiedLabel ?? "Copied!";
-                    setTimeout(() => { btn.textContent = n.label ?? "Copy"; }, 1500);
+                if (legacyCopy(text))
+                    showCopied();
+            }
+        };
+        btn.addEventListener("click", () => {
+            // RICH COPY — resolve the two representations by precedence: copyTargetId > html > plain.
+            let html = null;
+            let plain = n.text;
+            if (n.copyTargetId != null) {
+                // Harvest route: lift both representations off the already-rendered region.
+                const target = document.getElementById(n.copyTargetId);
+                if (target) {
+                    html = target.outerHTML;
+                    plain = target.textContent ?? n.text;
+                }
+                else {
+                    // Fail LOUD — a copy target that resolves to nothing is a bug, not a
+                    // silent no-op — then still give the user the plain fallback.
+                    console.error(`[viewmodel-shell] CopyButtonNode.copyTargetId "${n.copyTargetId}" matched no ` +
+                        `element on the page; falling back to plain-text copy. The target must be a ` +
+                        `described region that emits that DOM id (e.g. SectionNode.id / ListNode.id).`);
+                    copyPlain(n.text);
+                    return;
                 }
             }
+            else if (n.html != null) {
+                // Server-provided route: the formatted representation the server authored.
+                html = n.html;
+            }
+            // No rich representation → today's plain-text write.
+            if (html === null) {
+                copyPlain(plain);
+                return;
+            }
+            // Two representations at once via the async Clipboard API. A destination that
+            // understands formatting takes text/html; a plain one takes text/plain. If the
+            // API is unavailable or the write is rejected (permissions, older engine),
+            // degrade to the plain representation so the button is never dead.
+            if (navigator.clipboard?.write && typeof ClipboardItem === "function") {
+                const item = new ClipboardItem({
+                    "text/html": new Blob([html], { type: "text/html" }),
+                    "text/plain": new Blob([plain], { type: "text/plain" }),
+                });
+                navigator.clipboard.write([item]).then(showCopied).catch(() => copyPlain(plain));
+            }
+            else {
+                copyPlain(plain);
+            }
         });
         parent.appendChild(btn);
     }

package/dist/index.d.ts

@@ -154,7 +154,14 @@ export interface SectionNode {
     alignSelf?: "start" | "center" | "end";
     /** Bounded content-width cap — a CLOSED token set (NOT raw CSS, per P2), implemented with `max-inline-size` (writing-mode-safe). Fractional values are proportional to the container (half→50%, two-thirds→66.6667%, three-quarters→75%) — the chat-gutter case, scaling with width; `prose` caps at the readable measure (min(65ch,100%), the Tailwind `max-w-prose` / Every-Layout `--measure` cap). The section still shrinks to its content below the cap. Omitted = no class → no cap (today's full-width behavior) = byte-identical. Emits .vms-maxw--{value}. Closed union (CHILD-02). */
     maxWidth?: "half" | "two-thirds" | "three-quarters" | "prose";
-    /** 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. */
+    /** Optional stable identifier for the section. Two uses: (1) it is emitted as the
+     *  rendered element's DOM `id`, which makes the section addressable — e.g. as a
+     *  `CopyButtonNode.copyTargetId` harvest target; and (2) when `collapsible: true`
+     *  it is the renderer's open-state preservation key. Provide when `heading` isn't
+     *  unique within a page or is absent — otherwise the collapsible snapshot falls
+     *  back to `heading ?? "vms-section-anon"`, disambiguated by per-render ordinal.
+     *  DOM ids must be unique on a page (the same uniqueness the collapse-key already
+     *  wants). Omitted = no DOM id emitted and the heading fallback is used for collapse. */
     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;
@@ -233,6 +240,14 @@ export interface SectionNode {
 export interface ListNode {
     type: "list";
     id?: string;
+    /** When true, this is an ORDERED list — renders `<ol>` (numbered) instead of
+     *  `<ul>`. The semantic element gives real ordinal meaning (a11y: screen
+     *  readers announce position/count; agent-legibility: the order is structural,
+     *  not baked into item text). The visible "1." / "2." markers come from a CSS
+     *  counter (`.vms-list--ordered`), not native list markers, because `.vms-list`
+     *  is a flex column with `list-style:none` — so numbering survives the styled
+     *  list-item layout. Omitted/false = `<ul>` (byte-identical to today). */
+    ordered?: boolean;
     children: ViewNode[];
 }
 export interface ListItemNode {
@@ -856,8 +871,38 @@ export interface TableNode {
 }
 export interface CopyButtonNode {
     type: "copy-button";
-    /** The string to write to the clipboard on click. */
+    /** The plain-text string written to the clipboard on click. Always the
+     *  `text/plain` representation and the universal fallback: it is what a plain
+     *  destination (a code box, a terminal, a plain-text field) receives, and what
+     *  is copied when neither rich-copy route below applies. Required. */
     text: string;
+    /** RICH COPY — harvest route (adapter-side, the default; no server authoring).
+     *  The DOM id of an already-rendered region to copy. On click the adapter reads
+     *  that element's rendered markup as the `text/html` representation and its plain
+     *  text as `text/plain`, writing BOTH to the clipboard at once — so a paste into a
+     *  formatted destination (email, doc) keeps its structure while a plain
+     *  destination still gets clean text. The framework carries its look in
+     *  class-keyed styling rather than inline, so the app's theme naturally falls away
+     *  on paste and the *semantic structure* (headings, tables, bold, lists) survives —
+     *  the desired outcome, achieved by the conventional native-copy mechanism (the
+     *  destination sanitizes; the framework invents no cleaning pass). The target must
+     *  be a described region carrying an emitted DOM id (e.g. `SectionNode.id`,
+     *  `ListNode.id`); because ids only live on described nodes, this can never point
+     *  at undescribed chrome, so the intent stays fully readable from the wire. Point
+     *  it at a *content* region, not one containing this button. If the id resolves to
+     *  no element the adapter fails LOUD (console error) and falls back to writing
+     *  `text` — never a silent dead button. Absent = no harvest.
+     *  Precedence: `copyTargetId` > `html` > plain `text`. */
+    copyTargetId?: string;
+    /** RICH COPY — server-provided route (opt-in). A ready-made formatted
+     *  representation the server authored, written as `text/html` alongside `text`
+     *  (`text/plain`). Reach for this only when the content to copy is NOT already
+     *  rendered on the page (a cleaner or richer export than what's shown) — otherwise
+     *  prefer `copyTargetId`, which authors nothing. This is a WRITE-ONLY clipboard
+     *  export bound for a foreign destination; it never re-enters the rendered view
+     *  (that would be decoration and is forbidden). Ignored when `copyTargetId` is set.
+     *  Absent = no server-provided rich representation. */
+    html?: string;
     /** Label shown on the button before copying. Adapter default: "Copy". */
     label?: string;
     /** Ephemeral label shown after a successful copy, reverts after ~1.5 s. Adapter default: "Copied!". */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "6.0.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 \u2014 a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
+  "version": "6.2.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",
   "author": "ashley-shrok",

package/styles/default.css

@@ -1043,6 +1043,22 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
 .vms-list-item--success:hover { border-left-color: var(--vms-success); }
 .vms-list-item--info:hover    { border-left-color: var(--vms-info); }
 
+/* Ordered list — <ol>. `.vms-list` sets list-style:none for the styled
+   flex-column layout, so native markers never show; a CSS counter supplies the
+   number as the first flex child of each item (spaced by the item's own gap).
+   tabular-nums + right-aligned min-width keeps multi-digit numbers aligned. */
+.vms-list--ordered { counter-reset: vms-li; }
+.vms-list--ordered > .vms-list-item { counter-increment: vms-li; }
+.vms-list--ordered > .vms-list-item::before {
+  content: counter(vms-li) ".";
+  flex: 0 0 auto;
+  min-width: 1.5em;
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  color: var(--vms-text-muted);
+}
+
 /* Selection state for master-detail / list-detail patterns (D-27). The
    currently-selected row. Stronger than the semantic hints (selection is
    the primary state) and stable through hover. Themable: uses only seam