@multiplatform.one/components 7.10.0 → 7.15.0

package/src/surfaces.tsx

@@ -7,7 +7,6 @@ import {
   Popover,
   Sheet,
   View,
-  isWeb,
   type DialogContentProps as TamaguiDialogContentProps,
   type DialogOverlayProps as TamaguiDialogOverlayProps,
   type TamaguiElement,
@@ -103,42 +102,16 @@ export const DialogContent = forwardRef<
   );
 });
 
-/**
- * Reference §8 overlay shadow — rgba(0,0,0,0.12) 0 12px 24px. Not Button $1,
- * and not the `$2` fragment `elevatedSurface` carries either: that fragment's
- * web paint arrives as an INLINE style (`elevationPaint` emits
- * `style.boxShadow`, and Tamagui stamps `!important` only on pseudo atoms),
- * so a shadow expressed only as `shadow*` props is a dead class atom under a
- * live `$2` paint. The §8 value must land on the `style` prop too, replacing
- * the fragment's. Dark inverts the hue and keeps the geometry — LC-85
- * DARK-ELEVATION-TINT forbids a black umbra on a dark ground.
- */
-const overlayElevationShadow = {
-  light: {
-    shadowColor: "rgba(0,0,0,0.12)",
-    shadowOffset: { width: 0, height: 12 },
-    shadowOpacity: 1,
-    shadowRadius: 24,
-    ...(isWeb ? { style: { boxShadow: "0px 12px 24px rgba(0,0,0,0.12)" } } : null),
-  },
-  dark: {
-    shadowColor: "rgba(255,255,255,0.12)",
-    shadowOffset: { width: 0, height: 12 },
-    shadowOpacity: 1,
-    shadowRadius: 24,
-    ...(isWeb ? { style: { boxShadow: "0px 12px 24px rgba(255,255,255,0.12)" } } : null),
-  },
-} as const;
-
 const DialogContentInner = forwardRef<
   TamaguiElement,
   TamaguiDialogContentProps & { children?: ReactNode }
 >(function DialogContentInner({ children, ...props }, ref) {
   const { knobProps } = useResolvedKnobs({ component: "DialogContent" });
   // ThemeableStack unstyled:false defaults `elevate: true`, which paints
-  // getElevation(size) — `$true` is the same $1 stop every Button carries.
-  // Bind the §8 overlay shadow instead. Geometry (panelPadding 18,
-  // containerRadius 9, border 1px) stays on the recipe fragments below.
+  // getElevation(size) — `$true` is a control stop. `elevate={false}` leaves
+  // the overlay ladder in `elevatedSurface` as the only shadow (MPO-99).
+  // Geometry (panelPadding 18, containerRadius 9, border 1px) stays on the
+  // recipe fragments below.
   return (
     <Dialog.Content
       ref={ref}
@@ -147,7 +120,6 @@ const DialogContentInner = forwardRef<
       {...knobProps.panelPadding}
       {...knobProps.gap}
       elevate={false}
-      {...overlayElevationShadow[knobProps.scheme]}
       transition={knobProps.transition}
       enterStyle={overlayEnterExit}
       exitStyle={overlayEnterExit}
@@ -227,7 +199,6 @@ const AlertDialogContentInner = forwardRef<
       {...knobProps.panelPadding}
       {...knobProps.gap}
       elevate={false}
-      {...overlayElevationShadow[knobProps.scheme]}
       transition={knobProps.transition}
       enterStyle={overlayEnterExit}
       exitStyle={overlayEnterExit}

package/src/tamagui.spec.ts

@@ -48,11 +48,11 @@ const ALLOWLIST_VALUE_NAMES = [
   // barrel and had been red ever since. MPO-78: CI runs `turbo run build`
   // only, so nothing caught it.)
   "Circle",
-  // MPO-21 G1 / G3 / G4. Restored by MPO-148; MPO-169 locks them here so a
+  // MPO-21 G3 / G4. Restored by MPO-148; MPO-169 locks them here so a
   // later Adapt-style rewrite cannot drop them without this spec going red.
   // LinearGradient (G2) is not on the main tamagui barrel — see the dedicated
-  // assertion below rather than this identity check.
-  "Collapsible",
+  // assertion below rather than this identity check. Collapsible (G1) is a
+  // house shadow since MPO-265: its Trigger defaults to type="button".
   "Group",
   "ListItem",
   "ScrollView",
@@ -138,6 +138,7 @@ const HOUSE_SHADOWS = [
   "Avatar",
   "Button",
   "Card",
+  "Collapsible",
   "Fieldset",
   "H1",
   "H2",

package/src/textAccentSecondary.spec.tsx

@@ -18,9 +18,9 @@
  */
 import { cleanup, screen } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
-import { Preset } from "@multiplatform.one/theme";
+import { Preset, useResolvedKnobs } from "@multiplatform.one/theme";
 import type { ReactElement } from "react";
-import { Theme } from "tamagui";
+import { SizableText, Theme } from "tamagui";
 import { afterEach, describe, expect, it } from "vitest";
 import { Accordion } from "./Accordion";
 import { componentColors } from "./componentColors";
@@ -177,6 +177,104 @@ describe("Meter — textAccent reaches the ok-zone value readout (MPO-154)", ()
   });
 });
 
+/**
+ * low == medium alone also passes a surface pinned to a static step, so the
+ * dim stops are checked against a probe painting the resolver's own colour.
+ */
+function restInk(el: Element): string | undefined {
+  for (const cls of Array.from(el.classList)) {
+    if (!cls.startsWith("_col-")) continue;
+    const value = cls.slice("_col-".length);
+    if (/^\d*(hover|active|focus|press|disabled)/.test(value)) continue;
+    return value;
+  }
+  return undefined;
+}
+
+function ResolverInk() {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <SizableText data-resolver-ink={knobProps.textAccentColor} color={knobProps.textAccentColor}>
+      resolver ink
+    </SizableText>
+  );
+}
+
+function againstResolver(
+  scheme: Scheme,
+  accent: Accent,
+  node: ReactElement,
+  pick: (container: HTMLElement) => Element | null,
+) {
+  const { container } = renderWithProviders(
+    inScheme(
+      scheme,
+      <Preset overrides={{ textAccent: accent }}>
+        {node}
+        <ResolverInk />
+      </Preset>,
+    ),
+  );
+  const surface = pick(container);
+  const probe = container.querySelector("[data-resolver-ink]");
+  const result = {
+    surface: surface ? restInk(surface) : undefined,
+    resolver: probe ? restInk(probe) : undefined,
+    token: probe?.getAttribute("data-resolver-ink") ?? null,
+  };
+  cleanup();
+  return result;
+}
+
+describe("the dim stops paint the resolver's AA floor, not a pinned step (MPO-154)", () => {
+  const surfaces: Array<[string, ReactElement, (container: HTMLElement) => Element | null]> = [
+    [
+      "Tabs inactive label",
+      <Tabs
+        key="tabs"
+        items={[
+          { value: "address", label: "Address & Contact", content: <>address panel</> },
+          { value: "settings", label: "Settings", content: <>settings panel</> },
+        ]}
+        defaultValue="address"
+      />,
+      () => screen.getByText("Settings"),
+    ],
+    [
+      "Accordion description",
+      <Accordion key="accordion" defaultValue="shipping">
+        <Accordion.Item value="shipping">
+          <Accordion.Trigger description="Where should we deliver the order?">
+            Shipping details
+          </Accordion.Trigger>
+          <Accordion.Content>ship</Accordion.Content>
+        </Accordion.Item>
+      </Accordion>,
+      () => screen.getByText("Where should we deliver the order?"),
+    ],
+    [
+      "Quote attribution",
+      <Quote key="quote" cite="Alan Kay">
+        The best way to predict the future.
+      </Quote>,
+      (container) => container.querySelector("cite"),
+    ],
+  ];
+
+  for (const scheme of schemes) {
+    for (const [name, node, pick] of surfaces) {
+      for (const accent of ["low", "medium"] as const) {
+        it(`${scheme}: ${name} at ${accent} equals the resolver's textAccentColor`, () => {
+          const { surface, resolver, token } = againstResolver(scheme, accent, node, pick);
+          expect(token).toBe("$color11");
+          expect(resolver).toBeDefined();
+          expect(surface).toBe(resolver);
+        });
+      }
+    }
+  }
+});
+
 describe("componentColors keeps no second answer for secondary ink (MPO-154)", () => {
   it("the text table exposes no static secondary or muted step", () => {
     const text = componentColors.text as Record<string, string | undefined>;

package/src/views/List.tsx

@@ -13,6 +13,7 @@ import {
   useReadableTextOn,
   useResolvedKnobs,
   wasKeyboardFocus,
+  transitionProps,
 } from "@multiplatform.one/theme";
 import { useHotkey } from "@tanstack/react-hotkeys";
 import type { RegisterableHotkey } from "@tanstack/react-hotkeys";
@@ -513,7 +514,7 @@ export function List<T>({
                     ...corners,
                   }}
                   cursor="pointer"
-                  {...(knobProps.transition ? { transition: knobProps.transition } : {})}
+                  {...transitionProps(knobProps.transition)}
                   onPress={() => {
                     commitSelection(index);
                     onItemClick?.(item);

package/src/views/Matrix.spec.tsx

@@ -0,0 +1,339 @@
+import { cleanup, fireEvent, screen } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { formatMonthYear } from "@multiplatform.one/theme";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { MatrixView, type MatrixRow } from "./Matrix";
+import { generateBuckets, type MatrixCell } from "./matrixMath";
+
+afterEach(cleanup);
+
+const rows: MatrixRow[] = [
+  { id: "a", label: "Checking" },
+  { id: "b", label: "Savings" },
+  { id: "c", label: "HSA" },
+];
+
+// Checking spans Jan–Mar with two points in January (folded to 10, the grid
+// max); Savings carries a real zero in January and an error in March; HSA
+// has no point at all.
+const cells: MatrixCell[] = [
+  { rowId: "a", date: new Date(2026, 0, 12), value: 4 },
+  { rowId: "a", date: new Date(2026, 0, 20), value: 6 },
+  { rowId: "a", date: new Date(2026, 1, 3), value: 2 },
+  { rowId: "a", date: new Date(2026, 2, 9), value: 10 },
+  { rowId: "b", date: new Date(2026, 0, 5), value: 0 },
+  { rowId: "b", date: new Date(2026, 2, 2), value: 3, intent: "error" },
+];
+
+const cell = (container: HTMLElement, id: string) =>
+  container.querySelector(`[data-matrix-cell="${id}"]`) as HTMLElement;
+
+describe("MatrixView", () => {
+  it("generates the column axis from the rule over the data's range, one row per subject", () => {
+    const { container } = renderWithProviders(
+      <MatrixView rows={rows} cells={cells} rule="month" />,
+    );
+
+    const columns = Array.from(container.querySelectorAll("[data-matrix-column]"));
+    expect(columns.map((el) => el.getAttribute("data-matrix-column"))).toEqual([
+      "2026-01-01",
+      "2026-02-01",
+      "2026-03-01",
+    ]);
+    expect(columns[0].textContent).toBe(formatMonthYear(new Date(2026, 0, 1)));
+    expect(columns[0].getAttribute("aria-label")).toBe(formatMonthYear(new Date(2026, 0, 1)));
+    expect(container.querySelector('[data-matrix-view="month"]')).toBeTruthy();
+
+    const labels = Array.from(container.querySelectorAll("[data-matrix-row-label]"));
+    expect(labels.map((el) => el.textContent)).toEqual(["Checking", "Savings", "HSA"]);
+    expect(container.querySelectorAll("[data-matrix-row]")).toHaveLength(3);
+    expect(container.querySelectorAll("[data-matrix-cell]")).toHaveLength(9);
+    expect(screen.getByText("Subject")).toBeInTheDocument();
+  });
+
+  it("regenerates the axis when the rule is switched, nothing re-declared", () => {
+    const onRuleChange = vi.fn();
+    const { container } = renderWithProviders(
+      <MatrixView rows={rows} cells={cells} rule="month" onRuleChange={onRuleChange} />,
+    );
+
+    fireEvent.click(screen.getByText("Week"));
+
+    expect(onRuleChange).toHaveBeenCalledWith("week");
+    expect(container.querySelector('[data-matrix-view="week"]')).toBeTruthy();
+    const expected = generateBuckets(
+      { start: new Date(2026, 0, 5), end: new Date(2026, 2, 10) },
+      "week",
+    );
+    const columns = Array.from(container.querySelectorAll("[data-matrix-column]"));
+    expect(columns.map((el) => el.getAttribute("data-matrix-column"))).toEqual(
+      expected.map((b) => b.key),
+    );
+    expect(columns.length).toBeGreaterThan(3);
+  });
+
+  it("snaps an explicit window to bucket boundaries", () => {
+    const { container } = renderWithProviders(
+      <MatrixView
+        rows={rows}
+        cells={cells}
+        rule="month"
+        range={{ start: new Date(2025, 10, 20), end: new Date(2026, 4, 2) }}
+      />,
+    );
+    const columns = Array.from(container.querySelectorAll("[data-matrix-column]"));
+    expect(columns.map((el) => el.getAttribute("data-matrix-column"))).toEqual([
+      "2025-11-01",
+      "2025-12-01",
+      "2026-01-01",
+      "2026-02-01",
+      "2026-03-01",
+      "2026-04-01",
+      "2026-05-01",
+    ]);
+  });
+
+  it("a cell carries its folded value and a paint strength; an intent rides the theme ramp", () => {
+    const { container } = renderWithProviders(
+      <MatrixView rows={rows} cells={cells} rule="month" />,
+    );
+
+    const aJan = cell(container, "a:2026-01-01");
+    expect(aJan.textContent).toBe("10");
+    expect(aJan.getAttribute("data-matrix-cell-state")).toBe("value");
+    expect(aJan.querySelector("[data-matrix-fill]")!.getAttribute("data-matrix-fill")).toBe("1");
+    expect(aJan.getAttribute("aria-label")).toBe(
+      `Checking, ${formatMonthYear(new Date(2026, 0, 1))}: 10`,
+    );
+
+    const aFeb = cell(container, "a:2026-02-01");
+    expect(aFeb.textContent).toBe("2");
+    expect(aFeb.querySelector("[data-matrix-fill]")!.getAttribute("data-matrix-fill")).toBe("0.2");
+
+    const bMar = cell(container, "b:2026-03-01");
+    expect(bMar.getAttribute("data-matrix-cell-intent")).toBe("error");
+    expect(cell(container, "a:2026-03-01").getAttribute("data-matrix-cell-intent")).toBeNull();
+  });
+
+  it("an empty bucket is a different state from a zero", () => {
+    const { container } = renderWithProviders(
+      <MatrixView rows={rows} cells={cells} rule="month" />,
+    );
+
+    const zero = cell(container, "b:2026-01-01");
+    expect(zero.getAttribute("data-matrix-cell-state")).toBe("zero");
+    expect(zero.textContent).toBe("0");
+    expect(zero.querySelector("[data-matrix-fill]")!.getAttribute("data-matrix-fill")).toBe("0");
+
+    const gap = cell(container, "c:2026-01-01");
+    expect(gap.getAttribute("data-matrix-cell-state")).toBe("empty");
+    expect(gap.querySelector("[data-matrix-fill]")).toBeNull();
+    expect(gap.textContent).toBe("·");
+    expect(gap.getAttribute("aria-label")).toBe(
+      `HSA, ${formatMonthYear(new Date(2026, 0, 1))}: No data`,
+    );
+    expect(cell(container, "b:2026-02-01").getAttribute("data-matrix-cell-state")).toBe("empty");
+  });
+
+  it("carries a legend naming the empty state and the ramp, plus the caller's entries", () => {
+    const { container } = renderWithProviders(
+      <MatrixView
+        rows={rows}
+        cells={cells}
+        rule="month"
+        legendItems={[{ label: "Failed import", intent: "error" }]}
+      />,
+    );
+    const legend = container.querySelector("[data-matrix-legend]")!;
+    expect(legend).toBeTruthy();
+    expect(legend.textContent).toContain("No data");
+    expect(legend.textContent).toContain("Less");
+    expect(legend.textContent).toContain("More");
+    expect(legend.textContent).toContain("Failed import");
+    const swatches = Array.from(legend.querySelectorAll("[data-matrix-legend-swatch]")).map((el) =>
+      el.getAttribute("data-matrix-legend-swatch"),
+    );
+    expect(swatches).toEqual(["empty", "0", "0.25", "0.5", "0.75", "1", "1"]);
+
+    cleanup();
+    const { container: bare } = renderWithProviders(
+      <MatrixView rows={rows} cells={cells} rule="month" showLegend={false} />,
+    );
+    expect(bare.querySelector("[data-matrix-legend]")).toBeNull();
+  });
+
+  it("anchors every inset fill to its own swatch or cell, so no fill resolves against the viewport", () => {
+    const { container } = renderWithProviders(
+      <MatrixView
+        rows={rows}
+        cells={cells}
+        rule="month"
+        legendItems={[{ label: "Failed import", intent: "error" }]}
+      />,
+    );
+    const swatches = Array.from(
+      container.querySelectorAll(
+        '[data-matrix-legend-swatch]:not([data-matrix-legend-swatch="empty"])',
+      ),
+    ) as HTMLElement[];
+    const cellFills = Array.from(container.querySelectorAll("[data-matrix-fill]")) as HTMLElement[];
+    expect(swatches).toHaveLength(6);
+    expect(cellFills.length).toBeGreaterThan(0);
+
+    const fills = [
+      ...swatches.map((swatch) => swatch.firstElementChild as HTMLElement),
+      ...cellFills,
+    ];
+    for (const fill of fills) {
+      expect(getComputedStyle(fill).position).toBe("absolute");
+      expect(getComputedStyle(fill.parentElement!).position).toBe("relative");
+    }
+  });
+
+  it("a cell press reports its row, bucket and summary; an empty bucket presses too", () => {
+    const onCellPress = vi.fn();
+    const { container } = renderWithProviders(
+      <MatrixView rows={rows} cells={cells} rule="month" onCellPress={onCellPress} />,
+    );
+
+    const aJan = cell(container, "a:2026-01-01");
+    expect(aJan.getAttribute("role")).toBe("button");
+    fireEvent.click(aJan);
+    expect(onCellPress).toHaveBeenCalledTimes(1);
+    const ref = onCellPress.mock.calls[0][0];
+    expect(ref.row.id).toBe("a");
+    expect(ref.bucket.key).toBe("2026-01-01");
+    expect(ref.bucket.start).toEqual(new Date(2026, 0, 1));
+    expect(ref.summary.value).toBe(10);
+    expect(ref.summary.count).toBe(2);
+
+    fireEvent.click(cell(container, "c:2026-02-01"));
+    expect(onCellPress).toHaveBeenCalledTimes(2);
+    expect(onCellPress.mock.calls[1][0].summary).toBeUndefined();
+    expect(onCellPress.mock.calls[1][0].row.id).toBe("c");
+
+    fireEvent.keyDown(aJan, { key: "Enter" });
+    expect(onCellPress).toHaveBeenCalledTimes(3);
+    fireEvent.keyDown(aJan, { key: " " });
+    expect(onCellPress).toHaveBeenCalledTimes(4);
+    fireEvent.keyDown(aJan, { key: "a" });
+    expect(onCellPress).toHaveBeenCalledTimes(4);
+  });
+
+  it("without onCellPress a cell is not a control", () => {
+    const { container } = renderWithProviders(
+      <MatrixView rows={rows} cells={cells} rule="month" />,
+    );
+    expect(cell(container, "a:2026-01-01").getAttribute("role")).toBeNull();
+    expect(container.querySelectorAll('[data-matrix-cell][role="button"]')).toHaveLength(0);
+  });
+
+  it("keeps the header row and subject column outside the grid scrollers, and the header follows the grid scroll", () => {
+    const scrolls: { target: HTMLElement; left: number }[] = [];
+    const original = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "scroll");
+    Object.defineProperty(HTMLElement.prototype, "scroll", {
+      configurable: true,
+      writable: true,
+      value(this: HTMLElement, options: { left?: number }) {
+        if (typeof options?.left === "number") scrolls.push({ target: this, left: options.left });
+      },
+    });
+    try {
+      const { container } = renderWithProviders(
+        <MatrixView rows={rows} cells={cells} rule="month" />,
+      );
+
+      const axisRow = container.querySelector("[data-matrix-axis-row]") as HTMLElement;
+      const axis = container.querySelector("[data-matrix-axis]") as HTMLElement;
+      const body = container.querySelector("[data-matrix-scroll-body]") as HTMLElement;
+      const labels = container.querySelector("[data-matrix-labels]") as HTMLElement;
+      const canvas = container.querySelector("[data-matrix-canvas]") as HTMLElement;
+      expect(axisRow).toBeTruthy();
+      expect(body.contains(axisRow)).toBe(false);
+      expect(axisRow.contains(axis)).toBe(true);
+      expect(body.contains(labels)).toBe(true);
+      expect(body.contains(canvas)).toBe(true);
+
+      let scroller: HTMLElement | null = canvas.parentElement;
+      while (scroller && scroller !== body && !scroller.contains(labels)) {
+        scroller = scroller.parentElement;
+      }
+      expect(scroller).toBe(body);
+
+      let node: HTMLElement | null = canvas.parentElement;
+      let followed = false;
+      while (node && node !== body && !followed) {
+        Object.defineProperty(node, "scrollLeft", { configurable: true, value: 300 });
+        fireEvent.scroll(node);
+        followed = scrolls.some((call) => call.left === 300 && call.target.contains(axis));
+        node = node.parentElement;
+      }
+      expect(followed).toBe(true);
+      expect(scrolls.some((call) => call.target.contains(canvas))).toBe(false);
+    } finally {
+      if (original) Object.defineProperty(HTMLElement.prototype, "scroll", original);
+      else delete (HTMLElement.prototype as any).scroll;
+    }
+  });
+
+  it("shows the matrix skeleton while loading with no rows (W9 / DG-ST-02)", () => {
+    const { container } = renderWithProviders(<MatrixView rows={[]} cells={[]} isLoading />);
+    expect(container.querySelector('[data-async-skeleton="matrix"]')).toBeTruthy();
+    expect(container.querySelector("[data-matrix-column]")).toBeNull();
+  });
+
+  it("forbids empty chrome when error is set, and shows the empty state otherwise (W9 / DG-ST-01)", () => {
+    renderWithProviders(
+      <MatrixView rows={[]} cells={[]} emptyTitle="No accounts yet" error="Coverage failed" />,
+    );
+    expect(screen.queryByText("No accounts yet")).toBeNull();
+    expect(screen.getByText("Coverage failed")).toBeInTheDocument();
+    cleanup();
+
+    renderWithProviders(<MatrixView rows={[]} cells={[]} emptyTitle="No accounts yet" />);
+    expect(screen.getByText("No accounts yet")).toBeInTheDocument();
+  });
+
+  it("formatCell overrides the visible text and a point label wins over the number", () => {
+    const { container } = renderWithProviders(
+      <MatrixView
+        rows={rows}
+        cells={[...cells, { rowId: "c", date: new Date(2026, 1, 10), value: 7, label: "7 new" }]}
+        rule="month"
+        formatCell={(summary) => summary.label ?? `${summary.count}p`}
+      />,
+    );
+    expect(cell(container, "a:2026-01-01").textContent).toBe("2p");
+    expect(cell(container, "c:2026-02-01").textContent).toBe("7 new");
+    cleanup();
+
+    const { container: plain } = renderWithProviders(
+      <MatrixView
+        rows={rows}
+        cells={[...cells, { rowId: "c", date: new Date(2026, 1, 10), value: 7, label: "7 new" }]}
+        rule="month"
+      />,
+    );
+    expect(cell(plain, "a:2026-01-01").textContent).toBe("10");
+    expect(cell(plain, "c:2026-02-01").textContent).toBe("7 new");
+  });
+
+  it("scales intensity against the largest value on screen, not one outside the window or the rows", () => {
+    const { container } = renderWithProviders(
+      <MatrixView
+        rows={rows}
+        cells={[
+          ...cells,
+          { rowId: "a", date: new Date(2025, 5, 1), value: 1000 },
+          { rowId: "zz", date: new Date(2026, 0, 3), value: 500 },
+        ]}
+        rule="month"
+        range={{ start: new Date(2026, 0, 1), end: new Date(2026, 3, 1) }}
+      />,
+    );
+    const fill = (id: string) =>
+      cell(container, id).querySelector("[data-matrix-fill]")!.getAttribute("data-matrix-fill");
+    expect(fill("a:2026-01-01")).toBe("1");
+    expect(fill("a:2026-02-01")).toBe("0.2");
+  });
+});

package/src/views/Matrix.stories.spec.tsx

@@ -0,0 +1,68 @@
+/**
+ * The Matrix stories are the only in-repo render of the view (MPO-254 AC5:
+ * a subject-by-month grid with gaps). happy-dom runs no layout, so the
+ * pinned scrollers are not exercised here; what is asserted is that every
+ * story mounts and that the Main story's data really does put a zero and a
+ * gap on screen as two different cell states.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import meta, { Default, Intents, WeekRule } from "./Matrix.stories";
+
+vi.mock("@multiplatform.one/storybook", () => ({ action: () => () => undefined }));
+
+afterEach(cleanup);
+
+describe("Matrix stories", () => {
+  it("declares the Components/Matrix title", () => {
+    expect(meta.title).toBe("Components/Matrix");
+  });
+
+  it("every exported story mounts", () => {
+    for (const story of [Default, Intents, WeekRule]) {
+      const { container } = renderWithProviders(<>{story.render()}</>);
+      expect(container.querySelector("[data-matrix-view]")).toBeTruthy();
+      cleanup();
+    }
+  });
+
+  it("the Main story renders a subject-by-month grid where a gap and a zero are different states", () => {
+    const { container } = renderWithProviders(<>{Default.render()}</>);
+    expect(container.querySelector('[data-matrix-view="month"]')).toBeTruthy();
+    expect(container.querySelectorAll("[data-matrix-column]")).toHaveLength(12);
+    expect(container.querySelectorAll("[data-matrix-row-label]")).toHaveLength(6);
+
+    const zero = container.querySelector('[data-matrix-cell="savings:2026-04-01"]')!;
+    expect(zero.getAttribute("data-matrix-cell-state")).toBe("zero");
+    expect(zero.querySelector("[data-matrix-fill]")).toBeTruthy();
+    expect(zero.textContent).toBe("0");
+
+    const gap = container.querySelector('[data-matrix-cell="credit:2026-05-01"]')!;
+    expect(gap.getAttribute("data-matrix-cell-state")).toBe("empty");
+    expect(gap.querySelector("[data-matrix-fill]")).toBeNull();
+    expect(gap.textContent).not.toBe("0");
+
+    const hsaRow = container.querySelector('[data-matrix-row="hsa"]')!;
+    expect(hsaRow.querySelectorAll('[data-matrix-cell-state="empty"]')).toHaveLength(12);
+
+    const filled = container.querySelector('[data-matrix-cell="checking:2026-12-01"]')!;
+    expect(filled.getAttribute("data-matrix-cell-state")).toBe("value");
+    expect(filled.querySelector("[data-matrix-fill]")?.getAttribute("data-matrix-fill")).toBe("1");
+  });
+
+  it("the Intents story rides the theme ramps and names them in the legend", () => {
+    const { container } = renderWithProviders(<>{Intents.render()}</>);
+    const down = container.querySelector('[data-matrix-cell="auth:2026-03-05"]')!;
+    expect(down.getAttribute("data-matrix-cell-intent")).toBe("error");
+    expect(
+      container
+        .querySelector('[data-matrix-cell="search:2026-03-01"]')!
+        .getAttribute("data-matrix-cell-state"),
+    ).toBe("empty");
+    const legend = container.querySelector("[data-matrix-legend]")!;
+    expect(legend.textContent).toContain("Healthy");
+    expect(legend.textContent).toContain("Degraded");
+    expect(legend.textContent).toContain("Down");
+  });
+});