@ashley-shrok/viewmodel-shell 6.2.1 → 6.3.0

package/dist/browser.d.ts

@@ -240,4 +240,14 @@ export declare class BrowserAdapter implements Adapter {
      *  conveyed by color alone. The stepper is NOT focusable and is NOT
      *  `role="progressbar"` (that's a continuous %). All text via textContent. */
     private steps;
+    /** TrackerNode — a status/heat strip: a tight horizontal row of discrete
+     *  colored cells, one per time bucket. The framework owns ALL appearance and
+     *  a11y (never on the wire): the hairline gap, the intrinsic
+     *  shrink-to-a-min-then-scroll overflow, and the baked colorblind-safe palette
+     *  (success=blue / danger=red / warning=amber / muted=gray) via the
+     *  .vms-tracker__cell--{state} classes. A cell with a `label` carries it as both
+     *  the native tooltip AND aria-label (meaning as text, not color-only). A cell
+     *  with an `action` becomes a role="button" tabstop with Enter/Space activation
+     *  (Space suppresses page scroll), mirroring TableRow.action / SectionNode.action. */
+    private tracker;
 }

package/dist/browser.js

@@ -508,6 +508,7 @@ export class BrowserAdapter {
             case "chart": return this.chart(n, parent);
             case "breadcrumb": return this.breadcrumb(n, parent, on);
             case "steps": return this.steps(n, parent);
+            case "tracker": return this.tracker(n, parent, on);
             default: {
                 // Fail loud, not silent (AGENTS.md: "Nothing important fails quietly").
                 // Runtime trees are server-controlled JSON, so an unknown/forward-version
@@ -3491,4 +3492,53 @@ export class BrowserAdapter {
         });
         parent.appendChild(ol);
     }
+    /** TrackerNode — a status/heat strip: a tight horizontal row of discrete
+     *  colored cells, one per time bucket. The framework owns ALL appearance and
+     *  a11y (never on the wire): the hairline gap, the intrinsic
+     *  shrink-to-a-min-then-scroll overflow, and the baked colorblind-safe palette
+     *  (success=blue / danger=red / warning=amber / muted=gray) via the
+     *  .vms-tracker__cell--{state} classes. A cell with a `label` carries it as both
+     *  the native tooltip AND aria-label (meaning as text, not color-only). A cell
+     *  with an `action` becomes a role="button" tabstop with Enter/Space activation
+     *  (Space suppresses page scroll), mirroring TableRow.action / SectionNode.action. */
+    tracker(n, parent, on) {
+        const strip = document.createElement("div");
+        strip.className = "vms-tracker";
+        if (n.id != null)
+            strip.id = n.id;
+        // The strip is a graphical status summary — expose it as an img group with a
+        // label so a screen reader announces it as one thing; per-cell state is on
+        // each cell's aria-label.
+        strip.setAttribute("role", "img");
+        strip.setAttribute("aria-label", "status tracker");
+        for (const cell of n.cells) {
+            const state = cell.state ?? "muted";
+            const el = document.createElement("div");
+            el.className = `vms-tracker__cell vms-tracker__cell--${state}`;
+            // label → native tooltip + aria-label (non-color channel). When absent,
+            // the state name is still the a11y fallback so a cell is never color-only.
+            const aria = cell.label != null && cell.label !== "" ? cell.label : state;
+            el.setAttribute("aria-label", aria);
+            if (cell.label != null && cell.label !== "")
+                el.title = cell.label;
+            if (cell.action) {
+                const action = cell.action;
+                el.classList.add("vms-tracker__cell--clickable");
+                el.tabIndex = 0;
+                el.setAttribute("role", "button");
+                el.addEventListener("click", () => { on(action); });
+                el.addEventListener("keydown", (e) => {
+                    if (e.key === "Enter") {
+                        on(action);
+                    }
+                    else if (e.key === " " || e.key === "Spacebar") {
+                        e.preventDefault(); // suppress page scroll
+                        on(action);
+                    }
+                });
+            }
+            strip.appendChild(el);
+        }
+        parent.appendChild(strip);
+    }
 }

package/dist/index.d.ts

@@ -103,7 +103,7 @@ export interface Adapter {
      *  concept). */
     reload?(): void;
 }
-export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode | DividerNode | FitsNode | EmptyStateNode | BadgeNode | ChartNode | BreadcrumbNode | StepsNode;
+export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | ImageNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode | DividerNode | FitsNode | EmptyStateNode | BadgeNode | ChartNode | BreadcrumbNode | StepsNode | TrackerNode;
 export interface PageNode {
     type: "page";
     title?: string;
@@ -1087,6 +1087,49 @@ export interface StepsNode {
      *  left, connector running down, descriptions beside each step). */
     orientation?: "horizontal" | "vertical";
 }
+/** One bucket in a TrackerNode strip — a single time slot's status. Carries only
+ *  display data: the semantic state, an optional hover label, and an optional
+ *  click-through action. */
+export interface TrackerCell {
+    /** Semantic status for this bucket. A CLOSED set specific to a status strip:
+     *  `success` (good), `danger` (bad), `warning` (soft flag), `muted` (no data /
+     *  no run this slot — the universal honest-uncertainty convention). Omitted =
+     *  `muted`. NOTE the color axis differs from the rest of the framework on
+     *  PURPOSE: a dense, color-ONLY strip must survive colorblindness by color
+     *  alone, so the framework bakes a colorblind-safe palette where `success`
+     *  renders BLUE (not the global green success tone), `danger` red, `warning`
+     *  amber, `muted` gray — no "colorblind mode" needed. Only the rendered color
+     *  diverges; the state NAME stays semantic on the wire (agent-legible). `info`
+     *  is intentionally NOT a member — it would collide with `success`=blue and has
+     *  no meaning in a pass/fail history. */
+    state?: "success" | "danger" | "warning" | "muted";
+    /** Optional hover label for this bucket (e.g. "2026-07-15 14:22 UTC · Success").
+     *  Rendered as the cell's native tooltip AND its aria-label, so the strip's
+     *  meaning is carried by TEXT, not color alone — the a11y + agent-legibility
+     *  channel a color-only glyph strip could never provide. */
+    label?: string;
+    /** Optional click-through: dispatches this action when the bucket is clicked or
+     *  keyboard-activated (Enter / Space — Space preventDefaults page scroll). Makes
+     *  the cell a `role="button"` tabstop. Per-bucket identity is encoded in the
+     *  action name (e.g. `open-run-4021`), consistent with `TableRow.action` — no
+     *  context field. Omitted = a non-interactive status swatch (no tabstop). */
+    action?: ActionEvent;
+}
+/** A status tracker / heat strip — a tight horizontal row of discrete colored
+ *  cells, one per time bucket, where color encodes each bucket's semantic status.
+ *  This is the "uptime strip" / "sentinel history" primitive (industry precedent:
+ *  Tremor Tracker, Grafana Status History, Statuspage), NOT a numeric value
+ *  sparkline (a tiny line chart — a separate, chart-family concern, deliberately
+ *  not built here). The framework owns ALL appearance and a11y: the hairline gap,
+ *  the intrinsic shrink-to-a-min-then-scroll overflow (zero viewport
+ *  breakpoints), and the baked colorblind-safe palette (see TrackerCell.state).
+ *  Bucket count is simply `cells.length` (60 slots, 24 hourly, 7 daily…). */
+export interface TrackerNode {
+    type: "tracker";
+    id?: string;
+    /** Ordered buckets, oldest → newest (rendered left → right). */
+    cells: TrackerCell[];
+}
 export interface ShellOptions {
     endpoint: string;
     actionEndpoint: string;

package/dist/server.js

@@ -224,6 +224,20 @@ function collectActions(node, enclosingForm, out) {
             }
             return;
         }
+        case "tracker": {
+            // A TrackerCell can carry an optional per-bucket click-through action
+            // (per-bucket identity in the name, like row.action). Each is a
+            // dispatch-bearing descendant, so the uniqueness collector MUST descend
+            // into the cells — otherwise tracker actions are silently exempt from the
+            // one-name-one-operation rule (the missed-walk failure class). Guard the
+            // optional action the way the empty-state / breadcrumb arms do.
+            const tracker = node;
+            for (const cell of tracker.cells) {
+                if (cell.action)
+                    recordAction(cell.action, enclosingForm, out);
+            }
+            return;
+        }
         // Nodes with no dispatch-bearing actions of their own:
         //   text, link, image, stat-bar, progress, copy-button, badge, chart, steps
         //   (breadcrumb crumb actions ARE recorded above via the "breadcrumb" arm)
@@ -394,8 +408,9 @@ function walkForSectionAction(node, outerInteractive) {
             return;
         }
         // Leaf-like nodes (field, checkbox, button, text, link, image, stat-bar,
-        // tabs, progress, table, copy-button, badge, chart, breadcrumb, steps) carry
-        // no SectionNode descendants — TableNode rows hold strings + per-row controls,
+        // tabs, progress, table, copy-button, badge, chart, breadcrumb, steps,
+        // tracker) carry no SectionNode descendants — TrackerNode cells hold plain
+        // { state, label, action } records; TableNode rows hold strings + per-row controls,
         // not sections; ChartNode (CHART-05) is a childless/action-free data leaf;
         // BreadcrumbNode/StepsNode (NAV-01..03) hold plain { label, ... } records,
         // not ViewNode children, so no recursion is needed here (deliberate, not a

package/package.json

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

@@ -1724,3 +1724,54 @@ button.vms-breadcrumb__link {
     transform: translateX(-1px);
   }
 }
+
+/* ── Status tracker / heat strip (TrackerNode) ──
+   A tight horizontal row of discrete colored cells, one per time bucket (uptime
+   strip / sentinel history). The palette is a FIXED, colorblind-safe scheme —
+   blue=good / red=bad / amber=warn / gray=no-data — deliberately NOT the theme's
+   success(green)/danger(red) tones: a dense, color-ONLY strip has to survive
+   colorblindness by color alone (verified separable under deuteranopia /
+   protanopia / tritanopia), so "blue means good" is baked in and needs no mode.
+   It is intentionally the SAME across all themes for a11y consistency (only the
+   no-data gray adapts to the surface). Overflow is intrinsic: cells flex-shrink
+   to a min, then the strip scrolls (zero viewport breakpoints). Overridable via
+   the --vms-tracker-* seam like any other token. */
+:root {
+  /* Fixed palette, verified separable (deltaE >= 28 worst-pair) under normal +
+     deuteranopia + protanopia + tritanopia. fail is a deep red and warn a bright
+     amber ON PURPOSE — under red-green colorblindness red and amber converge in
+     hue, so they're separated by LIGHTNESS (deep vs bright), which the achromatic
+     channel preserves. pass(blue)/fail is the huge, always-obvious pair. */
+  --vms-tracker-pass:   #4a9eff;   /* good  — blue anchor */
+  --vms-tracker-fail:   #cc2936;   /* bad   — deep red */
+  --vms-tracker-warn:   #f2c94c;   /* warn  — bright amber */
+  /* no-data recedes into the surface, adapting per theme (light→light gray, dark→dark gray) */
+  --vms-tracker-nodata: color-mix(in srgb, var(--vms-text-muted) 42%, var(--vms-surface));
+}
+.vms-tracker {
+  display: flex;
+  gap: 1px;                 /* hairline separation — cells read as discrete, not one smeared bar */
+  align-items: stretch;
+  width: 100%;
+  overflow-x: auto;         /* shrink-to-a-min-then-scroll (see cell min-width) */
+  border-radius: var(--vms-radius);
+}
+.vms-tracker__cell {
+  flex: 1 1 0;
+  min-width: 3px;           /* legibility floor; once cells hit it the strip scrolls instead of vanishing */
+  height: 2rem;
+  background: var(--vms-tracker-nodata);
+}
+.vms-tracker__cell--success { background: var(--vms-tracker-pass); }
+.vms-tracker__cell--danger  { background: var(--vms-tracker-fail); }
+.vms-tracker__cell--warning { background: var(--vms-tracker-warn); }
+.vms-tracker__cell--muted   { background: var(--vms-tracker-nodata); }
+/* clickable cell: gentle brighten on hover (NO border), keyboard focus ring for a11y */
+.vms-tracker__cell--clickable { cursor: pointer; }
+.vms-tracker__cell--clickable:hover { filter: brightness(1.32); }
+.vms-tracker__cell--clickable:focus-visible {
+  outline: 2px solid var(--vms-accent);
+  outline-offset: 1px;
+  position: relative; /* lift the ring above neighbors */
+  z-index: 1;
+}