@multiplatform.one/components 7.4.1 → 7.5.0

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,3 +1,6 @@
+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 * as pkg from "./index";
@@ -6,6 +9,8 @@ import {
   CardFooter,
   CardHeader,
   DialogContent,
+  AlertDialogContent,
+  AlertDialogOverlay,
   KnobCard,
   KnobDialogContent,
   KnobPanel,
@@ -37,6 +42,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 +56,33 @@ 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");
+  });
+});

package/src/surfaces.tsx

@@ -2,18 +2,18 @@ import { Preset, Surface, useResolvedKnobs } from "@multiplatform.one/theme";
 import type { ReactNode } from "react";
 import { createContext, forwardRef, useContext } from "react";
 import {
-  Card as TamaguiCard,
+  AlertDialog,
   Dialog,
   Popover,
   Sheet,
   View,
-  type CardProps as TamaguiCardProps,
   type DialogContentProps as TamaguiDialogContentProps,
   type DialogOverlayProps as TamaguiDialogOverlayProps,
   type TamaguiElement,
   type ViewProps,
-  withStaticProperties,
 } from "tamagui";
+export { Card, CardFooter, CardHeader } from "./Card";
+export type { CardFooterProps, CardHeaderProps, CardProps, SurfaceTier } from "./Card";
 
 /**
  * Knob-aware surface wrappers.
@@ -56,73 +56,7 @@ const overlayFrameFocusStyle = {
   outlineStyle: "none" as any,
 } as const;
 
-// ── Card ──────────────────────────────────────────────────────────────────
-
-/**
- * Bento surface tiers:
- * - `content` (default): padded frame, bg only — no border, no shadow.
- * - `elevated`: bordered + elevated (overlay grammar — popovers, dropdowns).
- * - `feature`: big radius + ultra-soft wide shadow (marketing/auth cards).
- *
- * Padding contract: Card owns the inset (knob `panelPadding`, so the space
- * knob scales it) on every tier — bare children never touch the border.
- * Header/Footer are zero-padding rows; vertical rhythm comes from the
- * Card's knob `gap`.
- */
-export type SurfaceTier = "content" | "elevated" | "feature";
-
-export interface CardProps extends TamaguiCardProps {
-  tier?: SurfaceTier;
-}
-
-function CardRoot({ children, tier = "content", ...props }: CardProps) {
-  const { knobProps } = useResolvedKnobs({ component: "Card" });
-  // Axiom 1 child-clip cap: the padded container's radius may not exceed its
-  // own inset. cardSurface carries the cap already; the elevated tier layers
-  // containerRadius over elevatedSurface (which other, row-owning overlays
-  // consume uncapped). The feature tier is a fixed Bento recipe (radius is
-  // not knob-driven), so the knob cap does not apply.
-  const tierProps =
-    tier === "elevated"
-      ? { ...knobProps.elevatedSurface, ...knobProps.containerRadius }
-      : tier === "feature"
-        ? knobProps.featureSurface
-        : knobProps.cardSurface;
-  // panelPadding first so tier recipes may override (feature uses a larger
-  // inset); elevatedSurface carries no padding of its own, so this is what
-  // keeps bare children off the border on that tier.
-  return (
-    <TamaguiCard {...knobProps.panelPadding} {...tierProps} {...knobProps.gap} {...props}>
-      <NestedScale density={knobProps.density}>{children}</NestedScale>
-    </TamaguiCard>
-  );
-}
-
-// padding={0} kills the tamagui size-variant default padding — the Card
-// frame already owns the inset (LC-09), so Header/Footer padding would
-// double it. heading/body/gap ride the nested scale of the Card children.
-export function CardHeader({ children, ...props }: ViewProps & { children?: ReactNode }) {
-  const { knobProps } = useResolvedKnobs({ component: "Card" });
-  return (
-    <TamaguiCard.Header padding={0} {...knobProps.heading} {...knobProps.gap} {...props}>
-      {children}
-    </TamaguiCard.Header>
-  );
-}
-
-export function CardFooter({ children, ...props }: ViewProps & { children?: ReactNode }) {
-  const { knobProps } = useResolvedKnobs({ component: "Card" });
-  return (
-    <TamaguiCard.Footer padding={0} {...knobProps.body} {...knobProps.gap} {...props}>
-      {children}
-    </TamaguiCard.Footer>
-  );
-}
-
-export const Card = withStaticProperties(CardRoot, {
-  Header: CardHeader,
-  Footer: CardFooter,
-});
+// Card / CardHeader / CardFooter live in ./Card (NestedScale only; no Tint — R12).
 
 // ── Dialog region context (DG-OVL-04) ───────────────────────────────────
 
@@ -132,7 +66,7 @@ export interface DialogRegionContextValue {
 }
 
 /**
- * `DialogContent` provides this automatically. Wrap custom dialog-like
+ * `DialogContent` and `AlertDialogContent` provide this automatically. Wrap custom dialog-like
  * surfaces (sheet-as-dialog, hand-rolled dialog chrome) so their action rows
  * inherit dialog rules such as the max-2-actions cap (DG-OVL-04).
  */
@@ -167,11 +101,23 @@ export const DialogContent = forwardRef<
   );
 });
 
+/** Reference §8 overlay shadow — rgba(0,0,0,0.12) 0 12px 24px. Not Button $1. */
+const overlayElevationShadow = {
+  shadowColor: "rgba(0,0,0,0.12)",
+  shadowOffset: { width: 0, height: 12 },
+  shadowOpacity: 1,
+  shadowRadius: 24,
+} 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.
   return (
     <Dialog.Content
       ref={ref}
@@ -179,6 +125,8 @@ const DialogContentInner = forwardRef<
       {...knobProps.containerRadius}
       {...knobProps.panelPadding}
       {...knobProps.gap}
+      elevate={false}
+      {...overlayElevationShadow}
       transition={knobProps.transition}
       enterStyle={overlayEnterExit}
       exitStyle={overlayEnterExit}
@@ -226,6 +174,71 @@ export const DialogOverlay = forwardRef<
   );
 });
 
+// ── AlertDialogContent (MPO-21 G6) ───────────────────────────────────────
+// Tamagui's AlertDialog.Content is Dialog.Content under a different name:
+// the styled frame bakes `elevate: true` (plus bg/border/radius/padding).
+// `unstyled` drops that chrome so elevatedSurface is the only surface source.
+
+export const AlertDialogContent = forwardRef<
+  TamaguiElement,
+  TamaguiDialogContentProps & { children?: ReactNode }
+>(function AlertDialogContent({ children, ...props }, ref) {
+  return (
+    <Surface size="md">
+      <AlertDialogContentInner ref={ref} {...props}>
+        {children}
+      </AlertDialogContentInner>
+    </Surface>
+  );
+});
+
+const AlertDialogContentInner = forwardRef<
+  TamaguiElement,
+  TamaguiDialogContentProps & { children?: ReactNode }
+>(function AlertDialogContentInner({ children, ...props }, ref) {
+  const { knobProps } = useResolvedKnobs({ component: "AlertDialogContent" });
+  return (
+    <AlertDialog.Content
+      ref={ref}
+      unstyled
+      {...knobProps.elevatedSurface}
+      {...knobProps.containerRadius}
+      {...knobProps.panelPadding}
+      {...knobProps.gap}
+      transition={knobProps.transition}
+      enterStyle={overlayEnterExit}
+      exitStyle={overlayEnterExit}
+      {...overlayFrameFocus}
+      focusStyle={overlayFrameFocusStyle}
+      focusVisibleStyle={overlayFrameFocusStyle}
+      {...props}
+    >
+      <DialogRegionContext.Provider value={IN_DIALOG_REGION}>
+        <NestedScale density={knobProps.density}>{children}</NestedScale>
+      </DialogRegionContext.Provider>
+    </AlertDialog.Content>
+  );
+});
+
+export const AlertDialogOverlay = forwardRef<
+  TamaguiElement,
+  TamaguiDialogOverlayProps & { children?: ReactNode }
+>(function AlertDialogOverlay({ children, ...props }, ref) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <AlertDialog.Overlay
+      ref={ref}
+      backgroundColor="$shadow6"
+      transition={knobProps.transition}
+      enterStyle={scrimFade}
+      exitStyle={scrimFade}
+      {...props}
+    >
+      {children}
+    </AlertDialog.Overlay>
+  );
+});
+
 // ── PopoverContent ───────────────────────────────────────────────────────
 // OVERLAY_ANCHOR_GAP rule (theme/layoutTokens): free popovers size to
 // content, start-aligned to their anchor with the shared gap (the caller's
@@ -256,15 +269,22 @@ export const PopoverContent = forwardRef<TamaguiElement, ViewProps & { children?
 );
 
 // ── SheetFrame ───────────────────────────────────────────────────────────
+// Overlay chrome (SF-OVERLAY / E-OVERLAY): elevatedSurface binds border +
+// elevation even at `none`. The modal scrim is not a substitute. Fill is
+// `$background` (scheme token — never an invented hex, and not the shared
+// recipe's `$color1`) so the sheet tracks the page. Motion driver lives on
+// the Frame; SheetModal also drives the Sheet root (LC-24).
 
 export const SheetFrame = forwardRef<TamaguiElement, ViewProps & { children?: ReactNode }>(
   function SheetFrame({ children, ...props }, ref) {
     const { knobProps } = useResolvedKnobs({ component: "SheetFrame" });
     const frameProps = {
       ref,
-      ...knobProps.surface,
-      ...knobProps.borderRadius,
+      ...knobProps.elevatedSurface,
+      ...knobProps.containerRadius,
+      backgroundColor: "$background",
       ...knobProps.panelPadding,
+      transition: knobProps.transition,
       ...overlayFrameFocus,
       focusStyle: overlayFrameFocusStyle,
       focusVisibleStyle: overlayFrameFocusStyle,
@@ -314,9 +334,9 @@ export const Panel = forwardRef<TamaguiElement, ViewProps & { children?: ReactNo
 // These aliases keep old imports working; a later sweep removes them.
 
 /** @deprecated Use `CardProps` instead. */
-export type KnobCardProps = CardProps;
+export type { CardProps as KnobCardProps } from "./Card";
 /** @deprecated Use `Card` instead. */
-export const KnobCard = Card;
+export { Card as KnobCard } from "./Card";
 /** @deprecated Use `DialogContent` instead. */
 export const KnobDialogContent = DialogContent;
 /** @deprecated Use `PopoverContent` instead. */

package/src/tamagui.spec.ts

@@ -47,25 +47,18 @@ const ALLOWLIST_VALUE_NAMES = [
   "XStack",
   "YGroup",
   "YStack",
-  // text
-  "Anchor",
-  "H1",
-  "H2",
-  "H3",
-  "H4",
-  "H5",
-  "H6",
-  "Heading",
-  "Paragraph",
-  "SizableText",
-  "Text",
+  // text: none left (MPO-20). The raw primitives were knob-dead on native
+  // and fontWeight/textAccent/pageTitleScale-dead everywhere — bare
+  // Text/SizableText/Paragraph/Anchor and Heading/H1–H6 are the house
+  // shadows in ./Text.tsx and ./Heading.tsx. Raw rides the TamaguiText /
+  // TamaguiHeading / TamaguiH1… escape hatches.
   // actions / feedback: none left. Button left this list 2026-08-13 (raw
   // primitive knob-dead, LC-18 — bare `Button` is the house shadow in
   // ./Button.tsx); Spinner followed the same day (LC-70 census: raw Spinner
   // spins at animation "none" — bare `Spinner` is the forms house version).
   // Raw rides the TamaguiButton / TamaguiSpinner escape hatches.
-  // overlay composition roots
-  "Adapt",
+  // overlay composition roots — Adapt is dropped (R9 G8); compact vs
+  // regular overlays use useViewportGtSm / AdaptivePopup / FloatingPanel.
   "AlertDialog",
   "Dialog",
   "Popover",
@@ -96,29 +89,51 @@ const ALLOWLIST_VALUE_NAMES = [
 ] as const;
 
 const ESCAPE_HATCHES: ReadonlyArray<[prefixed: string, raw: string]> = [
+  ["TamaguiAnchor", "Anchor"],
   ["TamaguiButton", "Button"],
   ["TamaguiCheckbox", "Checkbox"],
+  ["TamaguiH1", "H1"],
+  ["TamaguiH2", "H2"],
+  ["TamaguiH3", "H3"],
+  ["TamaguiH4", "H4"],
+  ["TamaguiH5", "H5"],
+  ["TamaguiH6", "H6"],
+  ["TamaguiHeading", "Heading"],
   ["TamaguiInput", "Input"],
   ["TamaguiLabel", "Label"],
+  ["TamaguiParagraph", "Paragraph"],
   ["TamaguiProgress", "Progress"],
   ["TamaguiRadioGroup", "RadioGroup"],
   ["TamaguiSelect", "Select"],
+  ["TamaguiSizableText", "SizableText"],
   ["TamaguiSlider", "Slider"],
   ["TamaguiSpinner", "Spinner"],
   ["TamaguiSwitch", "Switch"],
+  ["TamaguiText", "Text"],
   ["TamaguiTextArea", "TextArea"],
   ["TamaguiToggleGroup", "ToggleGroup"],
 ];
 
 const HOUSE_SHADOWS = [
+  "Anchor",
   "Avatar",
   "Button",
   "Card",
   "Fieldset",
+  "H1",
+  "H2",
+  "H3",
+  "H4",
+  "H5",
+  "H6",
+  "Heading",
   "Image",
   "Menu",
+  "Paragraph",
+  "SizableText",
   "Spinner",
   "Tabs",
+  "Text",
   "Toast",
   "Tooltip",
 ];
@@ -164,6 +179,23 @@ describe("curated tamagui surface", () => {
       }
     }
   });
+
+  it("does not export Adapt (R9 G8 DROP)", () => {
+    expect(
+      (pkg as Record<string, unknown>).Adapt,
+      "Adapt is off the house barrel; useViewportGtSm / AdaptivePopup / FloatingPanel",
+    ).toBeUndefined();
+  });
+
+  it("keeps overlay composition roots Dialog, Sheet, Popover, and Portal", () => {
+    for (const name of ["Dialog", "Sheet", "Popover", "Portal"] as const) {
+      expect((pkg as Record<string, unknown>)[name], `barrel must keep "${name}"`).toBeDefined();
+      expect(
+        (pkg as Record<string, unknown>)[name],
+        `barrel "${name}" must be the tamagui export`,
+      ).toBe((tamagui as Record<string, unknown>)[name]);
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -184,6 +216,8 @@ type _NoSelectProps = import("./index").SelectProps;
 type _NoSliderProps = import("./index").SliderProps;
 // @ts-expect-error LabelProps is intentionally not exported (house: forms)
 type _NoLabelProps = import("./index").LabelProps;
+// @ts-expect-error Adapt is dropped from the house barrel (R9 G8)
+type _NoAdapt = import("./index").Adapt;
 
 type _HasViewProps = import("./index").ViewProps;
 type _HasXStackProps = import("./index").XStackProps;