@multiplatform.one/components 7.4.1 → 7.6.0

package/src/overlayElevation.spec.tsx

@@ -0,0 +1,154 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset } from "@multiplatform.one/theme";
+import { cleanup } from "@testing-library/react";
+import { AlertDialog, Dialog, Theme } from "tamagui";
+import { afterEach, describe, expect, it } from "vitest";
+import { Button } from "./Button";
+import { AlertDialogContent, DialogContent } from "./surfaces";
+
+afterEach(cleanup);
+
+// ── What this file measures, and why not the class list ──────────────────
+//
+// MPO-49 AC: "DialogContent paints the reference §8 overlay shadow" and "a
+// spec asserts the dialog shadow differs from the Button shadow".
+//
+// The obvious probe — read the frame's `_bxsh-*` atom — passes on a frame
+// that paints something else entirely. `resolveKnobs.elevationPaint` emits
+// its web paint as `style: { boxShadow }`, an INLINE style, and Tamagui only
+// stamps `!important` on PSEUDO atoms (`getCSSStylesAtomic`: `const
+// important = !!pseudo`). A base atom therefore loses the cascade to any
+// inline style on the same node. Measured on `6eb0995`, before this lane:
+//
+//   class  _bxsh-0px12px24px…                      (the §8 value — dead)
+//   style  0 3px 6px rgba(0,0,0,0.15), 0 2px 4px … (the `$2` value — painted)
+//
+// So these assert the INLINE style, which is what a browser paints, and read
+// the class only to prove the two now agree. Reading the class alone is the
+// same hole MPO-40 / MPO-44 / MPO-48 all fell through, one layer further in:
+// the fragment reaches the frame and still never reaches the pixel.
+
+/** Reference §8, tamagui-rendered-reference.md — the one dialog shadow. */
+const referenceOverlayShadow = "0px 12px 24px rgba(0,0,0,0.12)";
+/** Same §8 geometry and alpha, hue inverted — LC-85 forbids a dark umbra. */
+const referenceOverlayShadowDark = "0px 12px 24px rgba(255,255,255,0.12)";
+/** `webShadowLight.$1` — the in-page control stop every Button carries. */
+const controlStopPaint = "0 1px 2px rgba(0,0,0,0.12), 0 0 1px rgba(0,0,0,0.08)";
+/** `webShadowLight.$2` — `elevatedSurface`'s own overlay paint. */
+const elevatedSurfacePaint = "0 3px 6px rgba(0,0,0,0.15), 0 2px 4px rgba(0,0,0,0.10)";
+
+function frame(id: string): HTMLElement {
+  const el = document.querySelector(`[data-testid="${id}"]`);
+  if (!el) throw new Error(`no frame rendered for ${id}`);
+  return el as HTMLElement;
+}
+
+/** The value a browser paints: the inline style wins over every base atom. */
+function paintedShadow(id: string): string {
+  return frame(id).style.boxShadow;
+}
+
+function shadowAtoms(id: string): string[] {
+  return String(frame(id).className || "")
+    .split(/\s+/)
+    .filter((c) => c.startsWith("_bxsh-"))
+    .sort();
+}
+
+function bgAtoms(id: string): string[] {
+  return String(frame(id).className || "")
+    .split(/\s+/)
+    .filter((c) => c.startsWith("_bg-"));
+}
+
+function renderDialogsBesideAButton() {
+  renderWithProviders(
+    <Preset>
+      <Button testID="control">Save</Button>
+      <Dialog modal open>
+        <Dialog.Portal>
+          <DialogContent testID="dialog">dialog</DialogContent>
+        </Dialog.Portal>
+      </Dialog>
+      <AlertDialog open>
+        <AlertDialog.Portal>
+          <AlertDialogContent testID="alertdialog">confirm</AlertDialogContent>
+        </AlertDialog.Portal>
+      </AlertDialog>
+    </Preset>,
+  );
+}
+
+describe("overlay elevation is a different distance off the surface (MPO-49)", () => {
+  it("DialogContent PAINTS the reference §8 shadow, not the $2 fragment underneath it", () => {
+    renderDialogsBesideAButton();
+    expect(paintedShadow("dialog")).toBe(referenceOverlayShadow);
+    expect(paintedShadow("dialog")).not.toBe(elevatedSurfacePaint);
+    expect(paintedShadow("dialog")).not.toBe(controlStopPaint);
+  });
+
+  it("the atom and the inline style agree — no dead §8 class over a live $2 paint", () => {
+    renderDialogsBesideAButton();
+    // The atom half alone does NOT discriminate: it reads `_bxsh-0px12px24px…`
+    // with the defect present too, which is why a class-only probe passes
+    // against a frame painting `$2`. Pair it with the painted value.
+    expect(shadowAtoms("dialog")).toHaveLength(1);
+    expect(shadowAtoms("dialog")[0]).toMatch(/^_bxsh-0px12px24px/);
+    expect(paintedShadow("dialog")).toContain("12px 24px");
+  });
+
+  it("the dialog shadow differs from the Button shadow, and the Button keeps the $1 stop", () => {
+    renderDialogsBesideAButton();
+    // "differs" alone does not discriminate: with the defect present the
+    // dialog paints `$2` and the Button `$1`, which also differ. The §8 value
+    // itself is pinned by the first case in this file; here the control side
+    // is pinned to `$1` so a Button regression cannot fake this one either.
+    expect(paintedShadow("control")).toBe(controlStopPaint);
+    expect(paintedShadow("dialog")).not.toBe(paintedShadow("control"));
+    expect(shadowAtoms("dialog")).not.toEqual(shadowAtoms("control"));
+  });
+
+  it("AlertDialogContent wears the same §8 shadow — one dialog row, one distance", () => {
+    // Tamagui's AlertDialog.Content IS Dialog.Content, and reference §8
+    // carries a single dialog row. confirm-dialog-{destructive,gated,warning}
+    // render through this frame.
+    renderDialogsBesideAButton();
+    expect(paintedShadow("alertdialog")).toBe(referenceOverlayShadow);
+    expect(paintedShadow("alertdialog")).toBe(paintedShadow("dialog"));
+  });
+
+  it("dark inverts the hue and keeps the §8 geometry; the ground steps up the ramp (LC-85)", () => {
+    renderWithProviders(
+      <Preset>
+        <Dialog modal open>
+          <Dialog.Portal>
+            <DialogContent testID="dialog">dialog</DialogContent>
+          </Dialog.Portal>
+        </Dialog>
+      </Preset>,
+    );
+    expect(paintedShadow("dialog")).toBe(referenceOverlayShadow);
+    expect(bgAtoms("dialog")).toEqual(["_bg-background"]);
+    cleanup();
+
+    renderWithProviders(
+      <Theme name="dark">
+        <Preset>
+          <Dialog modal open>
+            <Dialog.Portal>
+              <DialogContent testID="dialog">dialog</DialogContent>
+            </Dialog.Portal>
+          </Dialog>
+        </Preset>
+      </Theme>,
+    );
+    // LC-85 DARK-ELEVATION-TINT: light-coloured shadow, never a black umbra.
+    expect(paintedShadow("dialog")).toBe(referenceOverlayShadowDark);
+    expect(paintedShadow("dialog")).not.toBe(referenceOverlayShadow);
+    expect(paintedShadow("dialog")).not.toMatch(/rgba\(0,\s*0,\s*0/);
+    // resolveKnobs owns the dark ground: `overlayFill` steps the filled rest
+    // fill up the ramp under dark + elevation (LC-85). Asserted so a later
+    // change to that rule shows up here rather than silently on a board.
+    expect(bgAtoms("dialog")).toEqual(["_bg-color2"]);
+  });
+});

package/src/primitives.spec.tsx

@@ -0,0 +1,98 @@
+/**
+ * @vitest-environment jsdom
+ *
+ * MPO-21 G1-G4, G6 — five primitives the house barrel could not express.
+ *
+ * G1 Collapsible / G2 LinearGradient / G3 VisuallyHidden / G4 Unspaced are
+ * knob-immune raw re-exports (registry rows). G6 AlertDialogContent is a
+ * house surface: `unstyled` drops Tamagui's baked elevate chrome so the
+ * overlay elevation token is the only surface source.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup } from "@testing-library/react";
+import { AlertDialog } from "tamagui";
+import * as tamagui from "tamagui";
+import * as tamaguiLinearGradient from "tamagui/linear-gradient";
+import { afterEach, describe, expect, it } from "vitest";
+import * as pkg from "./index";
+import { AlertDialogContent, AlertDialogOverlay } from "./surfaces";
+
+afterEach(cleanup);
+
+describe("MPO-21 G1-G4 — knob-immune primitives on the house barrel", () => {
+  it("exports Collapsible, Unspaced, VisuallyHidden as the tamagui primitives", () => {
+    expect(pkg.Collapsible).toBe(tamagui.Collapsible);
+    expect(pkg.Unspaced).toBe(tamagui.Unspaced);
+    expect(pkg.VisuallyHidden).toBe(tamagui.VisuallyHidden);
+    expect(pkg.Collapsible.Trigger).toBe(tamagui.Collapsible.Trigger);
+    expect(pkg.Collapsible.Content).toBe(tamagui.Collapsible.Content);
+  });
+
+  it("exports LinearGradient from the tamagui/linear-gradient subpath (not the main barrel)", () => {
+    expect((tamagui as Record<string, unknown>).LinearGradient).toBeUndefined();
+    expect(pkg.LinearGradient).toBe(tamaguiLinearGradient.LinearGradient);
+  });
+
+  it("renders Collapsible open with trigger and content", () => {
+    const { getByText } = renderWithProviders(
+      <pkg.Collapsible defaultOpen>
+        <pkg.Collapsible.Trigger>Toggle</pkg.Collapsible.Trigger>
+        <pkg.Collapsible.Content>Fold substrate</pkg.Collapsible.Content>
+      </pkg.Collapsible>,
+    );
+    expect(getByText("Toggle")).toBeTruthy();
+    expect(getByText("Fold substrate")).toBeTruthy();
+  });
+
+  it("renders VisuallyHidden into the tree without a visible box", () => {
+    const { getByText } = renderWithProviders(
+      <pkg.VisuallyHidden>Hidden label for assistive technology</pkg.VisuallyHidden>,
+    );
+    const node = getByText("Hidden label for assistive technology");
+    expect(node).toBeTruthy();
+    expect(node.className).toMatch(/_o-/);
+  });
+
+  it("renders Unspaced as a transparent spacing marker", () => {
+    const { getByText } = renderWithProviders(
+      <pkg.Unspaced>
+        <pkg.Text>unspaced child</pkg.Text>
+      </pkg.Unspaced>,
+    );
+    expect(getByText("unspaced child")).toBeTruthy();
+  });
+
+  it("renders LinearGradient with theme-token stops", () => {
+    const { container } = renderWithProviders(
+      <pkg.LinearGradient width={80} height={40} colors={["$color4", "$background"]} />,
+    );
+    expect(container.firstChild).toBeTruthy();
+  });
+});
+
+describe("MPO-21 G6 — house AlertDialog surface", () => {
+  it("is not the raw AlertDialog.Content (baked elevate chrome)", () => {
+    expect(pkg.AlertDialogContent).toBe(AlertDialogContent);
+    expect(pkg.AlertDialogContent).not.toBe(AlertDialog.Content);
+    expect(pkg.AlertDialogOverlay).toBe(AlertDialogOverlay);
+    expect(pkg.AlertDialogOverlay).not.toBe(AlertDialog.Overlay);
+  });
+
+  it("renders role=alertdialog through the house surface", () => {
+    renderWithProviders(
+      <AlertDialog defaultOpen>
+        <AlertDialog.Portal>
+          <AlertDialogOverlay />
+          <AlertDialogContent role="alertdialog" data-testid="house-alertdialog">
+            <AlertDialog.Title>Delete customer?</AlertDialog.Title>
+            <AlertDialog.Description>This cannot be undone.</AlertDialog.Description>
+          </AlertDialogContent>
+        </AlertDialog.Portal>
+      </AlertDialog>,
+    );
+    const surface = document.querySelector('[data-testid="house-alertdialog"]');
+    expect(surface).toBeTruthy();
+    expect(surface?.getAttribute("role")).toBe("alertdialog");
+    expect(document.body.textContent).toContain("Delete customer?");
+  });
+});

package/src/shared/useKeyboardInset.ts

@@ -0,0 +1,43 @@
+/**
+ * How many points of the screen the software keyboard currently covers.
+ *
+ * A sheet that ignores this draws its frame UNDER the keyboard: the last row
+ * is sliced mid-glyph, the rounded top edge lands on top of the autocomplete
+ * suggestion strip, and the field being typed into can be occluded by it
+ * (MPO-64). KeyboardAvoidingView is not enough inside a `Modal` — it pads the
+ * container but the sheet keeps whatever fixed height it was given, so it
+ * simply overflows off the top instead of shrinking.
+ *
+ * The number comes from the platform, never from a constant: the suggestion
+ * strip is exactly the band that overlapped, and its height varies with the
+ * field, the language and whether QuickType is on.
+ */
+
+import { useEffect, useState } from "react";
+import { Dimensions, Keyboard, Platform } from "react-native";
+
+export function useKeyboardInset(): number {
+  const [inset, setInset] = useState(0);
+
+  useEffect(() => {
+    // iOS fires the *Will* pair one frame before the animation, so the sheet
+    // resizes with the keyboard rather than after it. Android has no *Will*.
+    const showEvent = Platform.OS === "ios" ? "keyboardWillChangeFrame" : "keyboardDidShow";
+    const hideEvent = Platform.OS === "ios" ? "keyboardWillHide" : "keyboardDidHide";
+
+    const show = Keyboard.addListener(showEvent, (event) => {
+      const screen = event?.endCoordinates;
+      if (!screen) return;
+      const windowHeight = Dimensions.get("window").height;
+      setInset(Math.max(0, Math.round(windowHeight - screen.screenY)));
+    });
+    const hide = Keyboard.addListener(hideEvent, () => setInset(0));
+
+    return () => {
+      show.remove();
+      hide.remove();
+    };
+  }, []);
+
+  return inset;
+}

package/src/surfaces.spec.tsx

@@ -1,11 +1,20 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset } from "@multiplatform.one/theme";
+import { cleanup } from "@testing-library/react";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Card as TamaguiCard, Dialog, Popover, Sheet } from "tamagui";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
+import { Button } from "./Button";
 import * as pkg from "./index";
 import {
   Card,
   CardFooter,
   CardHeader,
   DialogContent,
+  AlertDialogContent,
+  AlertDialogOverlay,
   KnobCard,
   KnobDialogContent,
   KnobPanel,
@@ -16,6 +25,8 @@ import {
   SheetFrame,
 } from "./surfaces";
 
+afterEach(cleanup);
+
 describe("surfaces package exports", () => {
   it("package Card is the themed surface, not the tamagui primitive", () => {
     expect(pkg.Card).toBe(Card);
@@ -37,6 +48,8 @@ describe("surfaces package exports", () => {
     expect(pkg.SheetFrame).toBe(SheetFrame);
     expect(pkg.SheetFrame).not.toBe(Sheet.Frame);
     expect(pkg.Panel).toBe(Panel);
+    expect(pkg.AlertDialogContent).toBe(AlertDialogContent);
+    expect(pkg.AlertDialogOverlay).toBe(AlertDialogOverlay);
   });
 
   it("deprecated Knob* aliases still point at the renamed components", () => {
@@ -49,3 +62,124 @@ describe("surfaces package exports", () => {
     expect(pkg.KnobPanel).toBe(Panel);
   });
 });
+
+describe("SheetFrame overlay chrome", () => {
+  it("binds elevatedSurface, $background, and transition — not surface-without-elevation", () => {
+    const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "surfaces.tsx"), "utf8");
+    const start = src.indexOf("// ── SheetFrame");
+    const end = src.indexOf("// ── SheetModal");
+    const sheet = src.slice(start, end);
+    expect(sheet).toContain("elevatedSurface");
+    expect(sheet).toContain('backgroundColor: "$background"');
+    expect(sheet).toContain("knobProps.transition");
+    expect(sheet).toContain("containerRadius");
+    expect(sheet).not.toContain("knobProps.surface");
+    expect(sheet).not.toMatch(/#[0-9A-Fa-f]{3,8}/);
+  });
+});
+
+describe("DialogContent overlay elevation (MPO-49)", () => {
+  it("binds overlayElevation, elevate=false, and the §8 overlay shadow — not Tamagui $1 elevate", () => {
+    const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "surfaces.tsx"), "utf8");
+    const start = src.indexOf("// ── DialogContent");
+    const end = src.indexOf("// ── DialogOverlay");
+    const dialog = src.slice(start, end);
+    expect(dialog).toContain("elevate={false}");
+    expect(dialog).toContain("overlayElevationShadow");
+    expect(dialog).toContain("rgba(0,0,0,0.12)");
+    expect(dialog).toContain("elevatedSurface");
+    expect(dialog).toContain("containerRadius");
+    expect(dialog).toContain("panelPadding");
+  });
+});
+
+// ── Render proofs ────────────────────────────────────────────────────────
+//
+// The source-text assertions above prove the CALL SITE. These prove the
+// FRAME, which is the distinction MPO-40 / MPO-44 / MPO-48 all fell through:
+// a fragment that exists in source and dies on the way to the frame reads
+// identical to one that never existed.
+//
+// happy-dom cannot cascade Tamagui's class CSS, so — as in Button.spec.tsx —
+// these read the atomic classes the knob emits. The atom name is hashed from
+// the VALUE, so the class IS the value, and no theme config is needed: what
+// the fragment addresses is visible in the class name itself.
+//
+// Measured both ways on 2026-09-01 by reverting each defect in the working
+// tree and re-running (see the MR description):
+//
+//   surface addressing   defect `$color1`  -> `_bg-color1`
+//                        fixed  `$background` -> `_bg-background`
+//   dialog elevation     defect Button/control `$1` -> `_bxsh-0px1px2px…`
+//                        fixed  reference §8        -> `_bxsh-0px12px24px…`
+//
+// A "differs from the Button" assertion does NOT discriminate: the Button
+// paints `0 6px 12px` from its own source in both states, so that comparison
+// passes with the defect present. Assert against the $1 CONTROL stop.
+
+function atomsWithPrefix(el: Element | null, prefix: string): string[] {
+  if (!el) return [];
+  return String((el as HTMLElement).className || "")
+    .split(/\s+/)
+    .filter((c) => c.startsWith(prefix))
+    .sort();
+}
+
+/** The `$1` control paint — `webShadowLight.$1`, "0 1px 2px …" (resolveKnobs.ts). */
+const controlStopShadowAtom = /^_bxsh-0px1px2px/;
+/** Rendered reference §8 DialogContent — `rgba(0,0,0,0.12) 0 12px 24px`. */
+const overlayStopShadowAtom = /^_bxsh-0px12px24px/;
+
+describe("surfaces address $background at the FRAME (MPO-19 X5/X6)", () => {
+  it("Card, Panel and DialogContent all paint _bg-background, never a raw ramp step", () => {
+    renderWithProviders(
+      <Preset>
+        <Card testID="mpo-card">card</Card>
+        <Panel testID="mpo-panel">panel</Panel>
+        <Dialog modal open>
+          <Dialog.Portal>
+            <DialogContent testID="mpo-dialog">dialog</DialogContent>
+          </Dialog.Portal>
+        </Dialog>
+      </Preset>,
+    );
+
+    for (const id of ["mpo-card", "mpo-panel", "mpo-dialog"]) {
+      const frame = document.querySelector(`[data-testid="${id}"]`);
+      expect(frame, `${id} frame`).toBeTruthy();
+      const bg = atomsWithPrefix(frame, "_bg-");
+      expect(bg, `${id} background atom`).toEqual(["_bg-background"]);
+      expect(bg.join(" "), `${id} must not address a raw ramp step`).not.toMatch(/_bg-color[12]\b/);
+    }
+  });
+});
+
+describe("DialogContent paints the OVERLAY elevation stop, not the control one (MPO-49)", () => {
+  it("renders the reference §8 shadow and not the Button $1 stop", () => {
+    renderWithProviders(
+      <Preset>
+        <Button testID="mpo-button-control">Save</Button>
+        <Dialog modal open>
+          <Dialog.Portal>
+            <DialogContent testID="mpo-dialog-overlay">body</DialogContent>
+          </Dialog.Portal>
+        </Dialog>
+      </Preset>,
+    );
+
+    const dialog = document.querySelector('[data-testid="mpo-dialog-overlay"]');
+    const button = document.querySelector('[data-testid="mpo-button-control"]');
+    expect(dialog, "DialogContent frame").toBeTruthy();
+    expect(button, "Button frame").toBeTruthy();
+
+    const dialogShadow = atomsWithPrefix(dialog, "_bxsh-");
+    expect(dialogShadow, "DialogContent paints exactly one shadow atom").toHaveLength(1);
+    expect(dialogShadow[0], "dialog wears the §8 overlay shadow").toMatch(overlayStopShadowAtom);
+    expect(dialogShadow[0], "dialog must not wear the $1 control stop").not.toMatch(
+      controlStopShadowAtom,
+    );
+    expect(dialogShadow, "dialog and control are different distances off the surface").not.toEqual(
+      atomsWithPrefix(button, "_bxsh-"),
+    );
+  });
+});