npm - @ashley-shrok/viewmodel-shell - Versions diffs - 3.4.0 → 3.5.0 - Mend

@ashley-shrok/viewmodel-shell 3.4.0 → 3.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/agent-skill.md CHANGED Viewed

@@ -91,7 +91,8 @@ Optional success-path fields, which may appear alone or alongside `vm`/`state`:
 { "sideEffects": [
   { "type": "set-local-storage", "key": "auth_jwt", "value": "eyJ..." },
   { "type": "set-session-storage", "key": "draft_id", "value": "42" },
-  { "type": "download", "url": "/api/invoices/42/pdf", "filename": "invoice-42.pdf" }
+  { "type": "download", "url": "/api/invoices/42/pdf", "filename": "invoice-42.pdf" },
+  { "type": "toast", "message": "Ticket #4012 closed.", "tone": "success" }
 ] }
 ```
@@ -100,6 +101,7 @@ Optional success-path fields, which may appear alone or alongside `vm`/`state`:
 | `set-local-storage` | Write `key`/`value` to platform localStorage (or your agent's equivalent persistent store). |
 | `set-session-storage` | Same as above for session-scoped storage. |
 | `download` | Fetch `url` (re-presenting your auth headers — see *Auth*) and save the bytes. Filename precedence: `Content-Disposition` > side-effect `filename` > URL basename > `"download"`. |
+| `toast` | Show a transient confirmation: `message` (required) + optional `tone` (`danger`\|`warning`\|`success`\|`info`) + `durationMs`. A UX nicety — **fail-quiet**: an agent/adapter with no toast surface simply ignores it (nothing to persist or act on), so it carries no state and needs no acknowledgement. |
 **Forward-compat rule — silently ignore unknown verbs.** A future minor release may add new verbs. If you see a `type` you do not recognize, skip it; do not error. Honor or ignore per your policy.

package/dist/browser.d.ts CHANGED Viewed

@@ -12,6 +12,17 @@ export declare class BrowserAdapter implements Adapter {
     storage(scope: "local" | "session", key: string, value: string): void;
     saveFile(data: Blob, filename: string, _contentType: string): void;
     setBusy(active: boolean): void;
+    /** Transient confirmation toast. Lazily creates/reuses a single fixed-corner
+     *  host region (.vms-toast-region) appended to <body> so toasts stack and
+     *  survive the container's innerHTML wipe on each render(); appends a
+     *  .vms-toast element (+ tone modifier) and auto-removes it after
+     *  durationMs (default 4000), with a brief fade-out. This is the ONLY place
+     *  toast DOM lives — core stays platform-agnostic (it just calls this verb).
+     *  Fail-quiet by absence is the core's concern (it optional-chains the call). */
+    toast(message: string, opts?: {
+        tone?: string;
+        durationMs?: number;
+    }): void;
     private unloadHandler;
     setPreventUnload(active: boolean): void;
     transport(input: string, init: {
@@ -96,4 +107,11 @@ export declare class BrowserAdapter implements Adapter {
      *  concept. */
     private table;
     private copyButton;
+    /** EmptyStateNode — a centered "nothing here" block: a heading, an optional
+     *  message, then the optional CTA ButtonNode (rendered via the shared button
+     *  renderer so it dispatches like any other button). */
+    private emptyState;
+    /** BadgeNode — a compact inline status pill / count. Leaf node: label text +
+     *  tone/emphasis modifier classes. */
+    private badge;
 }

package/dist/browser.js CHANGED Viewed

@@ -162,6 +162,38 @@ export class BrowserAdapter {
     setBusy(active) {
         this.container.classList.toggle("vms-busy", active);
     }
+    /** Transient confirmation toast. Lazily creates/reuses a single fixed-corner
+     *  host region (.vms-toast-region) appended to <body> so toasts stack and
+     *  survive the container's innerHTML wipe on each render(); appends a
+     *  .vms-toast element (+ tone modifier) and auto-removes it after
+     *  durationMs (default 4000), with a brief fade-out. This is the ONLY place
+     *  toast DOM lives — core stays platform-agnostic (it just calls this verb).
+     *  Fail-quiet by absence is the core's concern (it optional-chains the call). */
+    toast(message, opts) {
+        let region = document.querySelector(".vms-toast-region");
+        if (!region) {
+            region = document.createElement("div");
+            region.className = "vms-toast-region";
+            document.body.appendChild(region);
+        }
+        const el = document.createElement("div");
+        el.className = `vms-toast${opts?.tone ? ` vms-toast--${opts.tone}` : ""}`;
+        el.setAttribute("role", "status");
+        el.setAttribute("aria-live", "polite");
+        el.textContent = message;
+        region.appendChild(el);
+        const duration = opts?.durationMs ?? 4000;
+        setTimeout(() => {
+            el.classList.add("vms-toast--leaving");
+            // Remove after the fade-out transition; a short fixed delay keeps it
+            // simple (no transitionend bookkeeping). Clean up the region if it empties.
+            setTimeout(() => {
+                el.remove();
+                if (region && region.childElementCount === 0)
+                    region.remove();
+            }, 200);
+        }, duration);
+    }
     unloadHandler = null;
     setPreventUnload(active) {
         if (active && this.unloadHandler == null) {
@@ -240,6 +272,8 @@ 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);
+            case "empty-state": return this.emptyState(n, parent, on);
+            case "badge": return this.badge(n, parent);
             default: {
                 // Fail loud, not silent (AGENTS.md: "Nothing important fails quietly").
                 // Runtime trees are server-controlled JSON, so an unknown/forward-version
@@ -1293,4 +1327,32 @@ export class BrowserAdapter {
         });
         parent.appendChild(btn);
     }
+    /** EmptyStateNode — a centered "nothing here" block: a heading, an optional
+     *  message, then the optional CTA ButtonNode (rendered via the shared button
+     *  renderer so it dispatches like any other button). */
+    emptyState(n, parent, on) {
+        const el = document.createElement("div");
+        el.className = "vms-empty-state";
+        const heading = document.createElement("div");
+        heading.className = "vms-empty-state__heading";
+        heading.textContent = n.heading;
+        el.appendChild(heading);
+        if (n.message != null && n.message !== "") {
+            const msg = document.createElement("div");
+            msg.className = "vms-empty-state__message";
+            msg.textContent = n.message;
+            el.appendChild(msg);
+        }
+        if (n.action)
+            this.button(n.action, el, on);
+        parent.appendChild(el);
+    }
+    /** BadgeNode — a compact inline status pill / count. Leaf node: label text +
+     *  tone/emphasis modifier classes. */
+    badge(n, parent) {
+        const span = document.createElement("span");
+        span.className = `vms-badge${n.tone ? ` vms-badge--${n.tone}` : ""}${n.emphasis ? ` vms-badge--${n.emphasis}` : ""}`;
+        span.textContent = n.label;
+        parent.appendChild(span);
+    }
 }

package/dist/index.d.ts CHANGED Viewed

@@ -62,8 +62,20 @@ export interface Adapter {
      *  none), so a rapid checkbox click during an in-flight round-trip never
      *  visually flips the box. Fail-quiet by absence (TUI has no equivalent). */
     setBusy?(active: boolean): void;
+    /** Show a transient confirmation toast, driven by a `{ type: "toast" }`
+     *  ShellSideEffect. `BrowserAdapter` stacks toasts in a single fixed-corner
+     *  host region and auto-dismisses each after `opts.durationMs` (default
+     *  ~4000ms). FAIL-QUIET BY ABSENCE — modeled on setPreventUnload/setBusy,
+     *  NOT on navigate/storage/saveFile: a dropped toast is a missed UX nicety,
+     *  never a correctness/security bug, so the core MUST NOT call failCapability
+     *  when this verb is absent (non-browser targets like the TUI simply have no
+     *  toast surface and the effect is a no-op). */
+    toast?(message: string, opts?: {
+        tone?: string;
+        durationMs?: number;
+    }): void;
 }
-export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode | DividerNode | FitsNode;
+export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode | DividerNode | FitsNode | EmptyStateNode | BadgeNode;
 export interface PageNode {
     type: "page";
     title?: string;
@@ -488,6 +500,47 @@ export interface CopyButtonNode {
      *  = content-width (the default hug). Orthogonal to emphasis/tone/size. */
     width?: "auto" | "full";
 }
+/**
+ * A first-class "nothing here" presentation — the empty-state primitive
+ * (MUI/Ant `<Empty>`, the standard zero-data placeholder). A centered block
+ * with a required heading, an optional supporting message, and an optional
+ * call-to-action ButtonNode (e.g. "Create your first ticket"). No icon field —
+ * the framework ships no icon set.
+ *
+ * The `action` ButtonNode carries a real action name and is a dispatch-bearing
+ * descendant, so EVERY tree-walk (action-name uniqueness collector, section
+ * shape validator) descends into it — exactly like `modal.footer` / `fits`
+ * candidates / `section.action`. A missed walk would silently exempt the CTA
+ * from the one-name-one-operation rule.
+ */
+export interface EmptyStateNode {
+    type: "empty-state";
+    /** The primary line — what's missing / what to do. Required. */
+    heading: string;
+    /** Optional supporting line below the heading. */
+    message?: string;
+    /** Optional call-to-action button (e.g. "Add the first item"). */
+    action?: ButtonNode;
+}
+/**
+ * A compact status pill / count — the badge primitive (MUI/Ant `<Badge>`,
+ * `<Tag>`). A leaf inline node (no children, no action) for a short label or
+ * count that appears inside text/section/list/table contexts. Appearance is
+ * the universal `tone` (semantic color) + `emphasis` (filled vs outline) axes,
+ * matching the rest of the framework's appearance vocabulary.
+ */
+export interface BadgeNode {
+    type: "badge";
+    /** The pill text — a short label or count (e.g. "New", "3", "Beta"). */
+    label: string;
+    /** Semantic intent/severity — the universal status tone axis. Emits
+     *  .vms-badge--{tone}. Omitted = neutral. Closed union. */
+    tone?: "danger" | "warning" | "success" | "info";
+    /** Visual weight — `primary` = filled solid tone, `secondary` = outline.
+     *  Mirrors ButtonNode's emphasis semantics. Emits .vms-badge--{emphasis}.
+     *  Omitted = the default filled tint. Closed union. */
+    emphasis?: "primary" | "secondary";
+}
 /**
  * The SwiftUI `ViewThatFits` port. The renderer picks the FIRST child whose
  * intrinsic size FITS the available container (no axis overflow), else the next,
@@ -563,7 +616,7 @@ export interface ShellOptions {
     pollInterval?: number;
 }
 export interface ShellSideEffect {
-    /** "set-local-storage" | "set-session-storage" | "download" — unknown types are silently ignored. */
+    /** "set-local-storage" | "set-session-storage" | "download" | "toast" — unknown types are silently ignored. */
     type: string;
     /** For "set-local-storage" / "set-session-storage": the storage key. */
     key?: string;
@@ -574,6 +627,13 @@ export interface ShellSideEffect {
     /** For "download": optional filename hint. Response Content-Disposition wins
      *  when present; this is the fallback before the URL basename. */
     filename?: string;
+    /** For "toast": the text shown in the transient confirmation. Required for a
+     *  toast effect (the shell guards `message != null` before routing). */
+    message?: string;
+    /** For "toast": optional semantic tone — "danger" | "warning" | "success" | "info". */
+    tone?: string;
+    /** For "toast": optional auto-dismiss delay in ms (adapter default ~4000). */
+    durationMs?: number;
 }
 /** One entry in the structured error payload returned on `ok: false`. */
 export interface ErrorEntry {

package/dist/index.js CHANGED Viewed

@@ -290,6 +290,16 @@ export class ViewModelShell {
                 // storage, and a slow download MUST NOT delay the user-visible update.
                 void this.download(effect.url, effect.filename);
             }
+            else if (effect.type === "toast" && effect.message != null) {
+                // FAIL-QUIET (cf. setPreventUnload/setBusy): a toast is a UX nicety,
+                // not a correctness/security guarantee, so an adapter without the
+                // capability simply drops it — NO failCapability, no onError. The
+                // optional-chaining call is the entire contract.
+                adapter.toast?.(effect.message, {
+                    tone: effect.tone,
+                    durationMs: effect.durationMs,
+                });
+            }
         }
         // 0.14.0 — apply the unload guard before the redirect/render branch so it's
         // in place (or cleared) consistently across both branches. A server that

package/dist/server.d.ts CHANGED Viewed

@@ -87,6 +87,14 @@ export declare const shellSideEffect: {
      *  The conditional spread keeps `filename` ABSENT (not undefined) on the
      *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
     download: (url: string, filename?: string) => ShellSideEffect;
+    /** Transient confirmation toast (a UX nicety, fail-quiet by absence — see
+     *  Adapter.toast). `message` is required; `tone`/`durationMs` are optional and
+     *  kept ABSENT (not undefined) from the JSON wire via conditional spread,
+     *  matching the .NET WhenWritingNull null-omission contract. */
+    toast: (message: string, opts?: {
+        tone?: string;
+        durationMs?: number;
+    }) => ShellSideEffect;
 };
 /**
  * Mount the canonical VMS agent skill markdown as an HTTP handler.

package/dist/server.js CHANGED Viewed

@@ -190,8 +190,18 @@ function collectActions(node, enclosingForm, out) {
                 collectActions(child, enclosingForm, out);
             return;
         }
+        case "empty-state": {
+            // EmptyStateNode.action is an optional ButtonNode carrying a real action
+            // name. It is a dispatch-bearing descendant, so the uniqueness collector
+            // MUST descend into it — otherwise the CTA is silently exempt from the
+            // one-name-one-operation rule (the 3.3.0 missed-walk failure class).
+            const es = node;
+            if (es.action)
+                collectActions(es.action, enclosingForm, out);
+            return;
+        }
         // Nodes with no dispatch-bearing actions of their own:
-        //   text, link, image, stat-bar, progress, copy-button
+        //   text, link, image, stat-bar, progress, copy-button, badge
         default:
             return;
     }
@@ -346,9 +356,18 @@ function walkForSectionAction(node, outerInteractive) {
                 walkForSectionAction(child, outerInteractive);
             return;
         }
+        case "empty-state": {
+            // EmptyStateNode.action is a ButtonNode (no SectionNode descendants), but
+            // descend for consistency with every other walk so a future shape can't
+            // slip an interactive section past this validator.
+            const es = node;
+            if (es.action)
+                walkForSectionAction(es.action, 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.
+        // tabs, progress, table, copy-button, badge) carry no SectionNode
+        // descendants — TableNode rows hold strings + per-row controls, not sections.
         default:
             return;
     }
@@ -427,6 +446,16 @@ export const shellSideEffect = {
      *  The conditional spread keeps `filename` ABSENT (not undefined) on the
      *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
     download: (url, filename) => ({ type: "download", url, ...(filename != null ? { filename } : {}) }),
+    /** Transient confirmation toast (a UX nicety, fail-quiet by absence — see
+     *  Adapter.toast). `message` is required; `tone`/`durationMs` are optional and
+     *  kept ABSENT (not undefined) from the JSON wire via conditional spread,
+     *  matching the .NET WhenWritingNull null-omission contract. */
+    toast: (message, opts) => ({
+        type: "toast",
+        message,
+        ...(opts?.tone != null ? { tone: opts.tone } : {}),
+        ...(opts?.durationMs != null ? { durationMs: opts.durationMs } : {}),
+    }),
 };
 // ─── Canonical agent skill mount helper (1.6.0 / 1.5.0) ──────────────────────
 /**

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "3.4.0",
+  "version": "3.5.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",
@@ -26,7 +26,7 @@
     "LICENSE"
   ],
   "bin": {
-    "vms-tui": "./dist/tui-cli.js"
+    "vms-tui": "dist/tui-cli.js"
   },
   "scripts": {
     "build": "tsc -b tsconfig.tui.json",

package/styles/default.css CHANGED Viewed

@@ -977,3 +977,117 @@ select.vms-field__input  { cursor: pointer; padding-right: var(--vms-space-xl);
   cursor: pointer;
   font-size: var(--vms-text-lg);
 }
+/* ── Toast (side-effect-driven transient confirmation) ──
+   The BrowserAdapter lazily creates ONE .vms-toast-region pinned to the
+   bottom-right corner and stacks .vms-toast elements into it; each auto-removes
+   after its durationMs with a brief fade. The region is click-through
+   (pointer-events:none) so it never blocks the UI under it; individual toasts
+   re-enable pointer events for their own content. Framework-owned styling —
+   this is the framework owning its presentation, not app CSS. */
+.vms-toast-region {
+  position: fixed;
+  bottom: var(--vms-space-md);
+  right: var(--vms-space-md);
+  z-index: 1100; /* above .vms-modal-backdrop (1000) */
+  display: flex;
+  flex-direction: column;
+  gap: var(--vms-space-xs);
+  align-items: flex-end;
+  pointer-events: none;
+  max-width: min(24rem, calc(100vw - 2 * var(--vms-space-md)));
+}
+.vms-toast {
+  pointer-events: auto;
+  /* Neutral toast = high-contrast inverted chip (the snackbar pattern): the
+     theme's text color as the surface, the theme's surface as the text. This
+     stands clear of the page background it sits on in EITHER theme — a
+     surface-colored toast was nearly invisible against the page surface. */
+  background: var(--vms-text);
+  color: var(--vms-surface);
+  border: 1px solid transparent;
+  border-radius: var(--vms-radius);
+  font-size: var(--vms-text-base);
+  font-weight: 500;
+  padding: var(--vms-space-sm) var(--vms-space-md);
+  box-shadow: 0 6px 22px rgba(0, 0, 0, 0.30);
+  opacity: 1;
+  transition: opacity var(--vms-t), transform var(--vms-t);
+}
+/* tone — a FULLY filled chip in the status color (not a thin accent rail), so
+   an important toast (especially danger) is impossible to miss. error/warning
+   are dark enough for white body text to clear WCAG-AA on their pure tokens;
+   success/info are deepened (color-mix w/ black) so white at 14px also clears
+   4.5:1 (their pure tokens sit at 3.2 / 4.4:1). */
+.vms-toast--danger  { background: var(--vms-error);   color: #fff; }
+.vms-toast--warning { background: var(--vms-warning); color: #fff; }
+.vms-toast--success { background: color-mix(in srgb, var(--vms-success) 80%, #000); color: #fff; }
+.vms-toast--info    { background: color-mix(in srgb, var(--vms-info) 88%, #000);    color: #fff; }
+/* fade-out applied just before removal. */
+.vms-toast--leaving { opacity: 0; transform: translateY(0.25rem); }
+/* ── Empty state (first-class "nothing here" presentation) ──
+   A centered block: heading, optional message, optional CTA button. */
+.vms-empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--vms-space-sm);
+  text-align: center;
+  padding: var(--vms-space-xl) var(--vms-space-md);
+  color: var(--vms-text-muted);
+}
+.vms-empty-state__heading {
+  font-size: var(--vms-text-lg);
+  font-weight: 600;
+  color: var(--vms-text);
+}
+.vms-empty-state__message {
+  font-size: var(--vms-text-base);
+  color: var(--vms-text-muted);
+  max-width: min(40ch, 100%);
+}
+/* The CTA button inside an empty state centers (override the button's default
+   align-self:flex-start) so it sits under the centered heading/message. */
+.vms-empty-state .vms-button { align-self: center; }
+/* ── Badge (compact inline status pill / count) ──
+   Leaf inline element. Default = neutral filled tint; tone recolors it; emphasis
+   switches between a solid fill (primary) and an outline (secondary). */
+.vms-badge {
+  --_badge-tone: var(--vms-text-muted);
+  display: inline-flex;
+  align-items: center;
+  /* Center the pill on the surrounding text instead of baselining it (an
+     inline-flex pill otherwise hangs below the baseline of adjacent text). */
+  vertical-align: middle;
+  gap: var(--vms-space-2xs);
+  font-size: var(--vms-text-xs);
+  font-weight: 600;
+  line-height: 1;
+  padding: 0.2em 0.6em;
+  border-radius: 999px;
+  white-space: nowrap;
+  /* default (no tone, no emphasis): subtle neutral tint pill. */
+  background: color-mix(in srgb, var(--_badge-tone) 16%, var(--vms-surface));
+  color: var(--_badge-tone);
+  border: 1px solid transparent;
+}
+/* tone — the universal status color, sets the pill's working color. */
+.vms-badge--danger  { --_badge-tone: var(--vms-error); }
+.vms-badge--warning { --_badge-tone: var(--vms-warning); }
+.vms-badge--success { --_badge-tone: var(--vms-success); }
+.vms-badge--info    { --_badge-tone: var(--vms-info); }
+/* emphasis — primary = solid filled tone (white text); secondary = outline.
+   Declared after tone so the chosen --_badge-tone drives both. */
+.vms-badge--primary {
+  background: var(--_badge-tone);
+  border-color: var(--_badge-tone);
+  color: #fff;
+}
+.vms-badge--secondary {
+  background: transparent;
+  border-color: var(--_badge-tone);
+  color: var(--_badge-tone);
+}