@multiplatform.one/components 6.1.0 → 6.3.0

package/src/surfaces.tsx

@@ -1,13 +1,14 @@
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import type { ReactNode } from "react";
-import { forwardRef } from "react";
+import { createContext, forwardRef, useContext } from "react";
 import {
-  Card,
+  Card as TamaguiCard,
   Dialog,
   Popover,
   Sheet,
   View,
-  type CardProps,
+  type CardProps as TamaguiCardProps,
+  type DialogContentProps as TamaguiDialogContentProps,
   type TamaguiElement,
   type ViewProps,
   withStaticProperties,
@@ -16,84 +17,151 @@ import {
 /**
  * Knob-aware surface wrappers.
  *
- * These apply `knobProps.surface`, `borderRadius`, `elevation`, `gap`,
- * and `panelPadding` by default so consumers don't need to manually
- * spread knob props for the common cases.  All applied props can be
- * overridden via the usual Tamagui prop spread.
+ * These apply the knob surface-tier recipes (`cardSurface`,
+ * `elevatedSurface`, `featureSurface`) plus `gap` / `panelPadding` by
+ * default so consumers don't need to manually spread knob props for the
+ * common cases.  All applied props can be overridden via the usual
+ * Tamagui prop spread.
+ *
+ * Every MP1 component consumes knobs, so these carry the plain names
+ * (`Card`, `Panel`, ...). They shadow the raw tamagui primitives in the
+ * package export; the unthemed originals stay reachable via the
+ * `tamagui` import path.
  */
 
-// ── KnobCard ──────────────────────────────────────────────────────────────
+// ── 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 KnobCardRoot({ children, ...props }: CardProps) {
+function CardRoot({ children, tier = "content", ...props }: CardProps) {
   const { knobProps } = useResolvedKnobs();
+  // 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 (
-    <Card
-      {...knobProps.surface}
-      {...knobProps.borderRadius}
-      elevation={knobProps.elevation}
-      {...knobProps.gap}
-      {...props}
-    >
+    <TamaguiCard {...knobProps.panelPadding} {...tierProps} {...knobProps.gap} {...props}>
       {children}
-    </Card>
+    </TamaguiCard>
   );
 }
 
-function KnobCardHeader({ children, ...props }: ViewProps & { children?: ReactNode }) {
-  const { knobProps } = useResolvedKnobs();
+// padding={0} kills the tamagui size-variant default padding — the Card
+// frame already owns the inset, so Header/Footer padding would double it.
+export function CardHeader({ children, ...props }: ViewProps & { children?: ReactNode }) {
   return (
-    <Card.Header {...knobProps.panelPadding} {...props}>
+    <TamaguiCard.Header padding={0} {...props}>
       {children}
-    </Card.Header>
+    </TamaguiCard.Header>
   );
 }
 
-function KnobCardFooter({ children, ...props }: ViewProps & { children?: ReactNode }) {
-  const { knobProps } = useResolvedKnobs();
+export function CardFooter({ children, ...props }: ViewProps & { children?: ReactNode }) {
   return (
-    <Card.Footer {...knobProps.panelPadding} {...props}>
+    <TamaguiCard.Footer padding={0} {...props}>
       {children}
-    </Card.Footer>
+    </TamaguiCard.Footer>
   );
 }
 
-export const KnobCard = withStaticProperties(KnobCardRoot, {
-  Header: KnobCardHeader,
-  Footer: KnobCardFooter,
+export const Card = withStaticProperties(CardRoot, {
+  Header: CardHeader,
+  Footer: CardFooter,
 });
 
-// ── KnobDialogContent ────────────────────────────────────────────────────
+// ── Dialog region context (DG-OVL-04) ───────────────────────────────────
 
-export const KnobDialogContent = forwardRef<TamaguiElement, ViewProps & { children?: ReactNode }>(
-  function KnobDialogContent({ children, ...props }, ref) {
-    const { knobProps } = useResolvedKnobs();
-    return (
-      <Dialog.Content
-        ref={ref}
-        {...knobProps.surface}
-        {...knobProps.borderRadius}
-        elevation={knobProps.elevation}
-        {...knobProps.panelPadding}
-        {...knobProps.gap}
-        {...props}
-      >
+export interface DialogRegionContextValue {
+  /** True inside a dialog surface — dialog action rules apply (DG-OVL-04). */
+  inDialogRegion: boolean;
+}
+
+/**
+ * `DialogContent` provides 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).
+ */
+export const DialogRegionContext = createContext<DialogRegionContextValue>({
+  inDialogRegion: false,
+});
+
+export function useDialogRegionContext(): DialogRegionContextValue {
+  return useContext(DialogRegionContext);
+}
+
+export function useIsInDialogRegion(): boolean {
+  return useDialogRegionContext().inDialogRegion;
+}
+
+const IN_DIALOG_REGION: DialogRegionContextValue = { inDialogRegion: true };
+
+// ── DialogContent ────────────────────────────────────────────────────────
+
+const overlayEnterExit = { opacity: 0, y: -4, scale: 0.97 } as const;
+
+export const DialogContent = forwardRef<
+  TamaguiElement,
+  TamaguiDialogContentProps & { children?: ReactNode }
+>(function DialogContent({ children, ...props }, ref) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <Dialog.Content
+      ref={ref}
+      {...knobProps.surface}
+      {...knobProps.borderRadius}
+      {...knobProps.containerRadius}
+      elevation={knobProps.elevation}
+      {...knobProps.panelPadding}
+      {...knobProps.gap}
+      transition={knobProps.transition}
+      enterStyle={overlayEnterExit}
+      exitStyle={overlayEnterExit}
+      {...props}
+    >
+      <DialogRegionContext.Provider value={IN_DIALOG_REGION}>
         {children}
-      </Dialog.Content>
-    );
-  },
-);
+      </DialogRegionContext.Provider>
+    </Dialog.Content>
+  );
+});
 
-// ── KnobPopoverContent ───────────────────────────────────────────────────
+// ── PopoverContent ───────────────────────────────────────────────────────
 
-export const KnobPopoverContent = forwardRef<TamaguiElement, ViewProps & { children?: ReactNode }>(
-  function KnobPopoverContent({ children, ...props }, ref) {
+export const PopoverContent = forwardRef<TamaguiElement, ViewProps & { children?: ReactNode }>(
+  function PopoverContent({ children, ...props }, ref) {
     const { knobProps } = useResolvedKnobs();
     return (
       <Popover.Content
         ref={ref}
-        {...knobProps.surface}
-        {...knobProps.borderRadius}
-        elevation={knobProps.elevation}
+        {...knobProps.elevatedSurface}
+        transition={knobProps.transition}
+        enterStyle={overlayEnterExit}
+        exitStyle={overlayEnterExit}
         {...props}
       >
         {children}
@@ -102,10 +170,10 @@ export const KnobPopoverContent = forwardRef<TamaguiElement, ViewProps & { child
   },
 );
 
-// ── KnobSheetFrame ───────────────────────────────────────────────────────
+// ── SheetFrame ───────────────────────────────────────────────────────────
 
-export const KnobSheetFrame = forwardRef<TamaguiElement, ViewProps & { children?: ReactNode }>(
-  function KnobSheetFrame({ children, ...props }, ref) {
+export const SheetFrame = forwardRef<TamaguiElement, ViewProps & { children?: ReactNode }>(
+  function SheetFrame({ children, ...props }, ref) {
     const { knobProps } = useResolvedKnobs();
     const frameProps = {
       ref,
@@ -118,17 +186,26 @@ export const KnobSheetFrame = forwardRef<TamaguiElement, ViewProps & { children?
   },
 );
 
-// ── KnobPanel ────────────────────────────────────────────────────────────
+// ── SheetModal ───────────────────────────────────────────────────────────
+// Modal bottom-sheet presentation: tamagui Sheet on web, RN Modal on native
+// (raw `Sheet modal` cannot (re)present from a trigger tap on device — the
+// FloatingPanel-proven workaround). Lives in ./SheetModal (platform pair).
+
+export { SheetModal } from "./SheetModal";
+export type { SheetModalProps } from "./SheetModal";
+
+// ── Panel ────────────────────────────────────────────────────────────────
 // A plain View that applies surface + borderRadius + elevation + padding.
 // Useful as a generic knob-aware container.
 
-export const KnobPanel = forwardRef<TamaguiElement, ViewProps & { children?: ReactNode }>(
-  function KnobPanel({ children, ...props }, ref) {
+export const Panel = forwardRef<TamaguiElement, ViewProps & { children?: ReactNode }>(
+  function Panel({ children, ...props }, ref) {
     const { knobProps } = useResolvedKnobs();
     const viewProps = {
       ref,
       ...knobProps.surface,
       ...knobProps.borderRadius,
+      ...knobProps.containerRadius,
       elevation: knobProps.elevation,
       ...knobProps.panelPadding,
       ...knobProps.gap,
@@ -137,3 +214,20 @@ export const KnobPanel = forwardRef<TamaguiElement, ViewProps & { children?: Rea
     return <View {...viewProps}>{children}</View>;
   },
 );
+
+// ── Deprecated Knob* aliases ─────────────────────────────────────────────
+// The Knob prefix was a tautology (every MP1 component is knob driven).
+// These aliases keep old imports working; a later sweep removes them.
+
+/** @deprecated Use `CardProps` instead. */
+export type KnobCardProps = CardProps;
+/** @deprecated Use `Card` instead. */
+export const KnobCard = Card;
+/** @deprecated Use `DialogContent` instead. */
+export const KnobDialogContent = DialogContent;
+/** @deprecated Use `PopoverContent` instead. */
+export const KnobPopoverContent = PopoverContent;
+/** @deprecated Use `SheetFrame` instead. */
+export const KnobSheetFrame = SheetFrame;
+/** @deprecated Use `Panel` instead. */
+export const KnobPanel = Panel;

package/src/tamagui.spec.ts

@@ -0,0 +1,182 @@
+/**
+ * Guardrail for the curated tamagui re-export surface (./tamagui.ts).
+ *
+ * The barrel used to `export * from "tamagui"`, leaking raw interactive
+ * primitives under the house package name (the todos Checkbox incident:
+ * a childless raw Checkbox renders no indicator, ever, while passing every
+ * lint rule). This spec locks the curation both ways:
+ *
+ *  1. EXCLUDED bare names must never come back — each has a house
+ *     equivalent in @multiplatform.one/forms.
+ *  2. The ALLOWLIST (layout/text/styling/theme utilities + overlay
+ *     composition roots) must not be accidentally removed.
+ *  3. The explicit `Tamagui*`-prefixed escape hatches must stay identical
+ *     to the raw tamagui primitives (deliberate raw usage stays possible,
+ *     but visible at the import site).
+ *  4. House shadows (Tabs, Tooltip, Card, Toast, …) must stay the house
+ *     versions, not the tamagui primitives.
+ */
+import * as tamagui from "tamagui";
+import { describe, expect, it } from "vitest";
+import * as pkg from "./index";
+
+const EXCLUDED_BARE_NAMES = [
+  "Checkbox",
+  "Form",
+  "Input",
+  "Label",
+  "Progress",
+  "RadioGroup",
+  "Select",
+  "Slider",
+  "Switch",
+  "TextArea",
+] as const;
+
+const ALLOWLIST_VALUE_NAMES = [
+  // layout
+  "Circle",
+  "Group",
+  "ListItem",
+  "ScrollView",
+  "Separator",
+  "Spacer",
+  "Square",
+  "View",
+  "XGroup",
+  "XStack",
+  "YGroup",
+  "YStack",
+  // text
+  "Anchor",
+  "H1",
+  "H2",
+  "H3",
+  "H4",
+  "H5",
+  "H6",
+  "Heading",
+  "Paragraph",
+  "SizableText",
+  "Text",
+  // actions / feedback (standalone-safe)
+  "Button",
+  "Spinner",
+  // overlay composition roots
+  "Adapt",
+  "AlertDialog",
+  "Dialog",
+  "Popover",
+  "Portal",
+  "PortalProvider",
+  "Sheet",
+  // providers / theme / animation
+  "AnimatePresence",
+  "TamaguiProvider",
+  "Theme",
+  // hooks
+  "useControllableState",
+  "useDidFinishSSR",
+  "useEvent",
+  "useMedia",
+  "usePropsAndStyle",
+  "useTheme",
+  "useThemeName",
+  // styling utilities
+  "createStyledContext",
+  "getToken",
+  "getTokens",
+  "getTokenValue",
+  "isClient",
+  "isWeb",
+  "styled",
+  "withStaticProperties",
+] as const;
+
+const ESCAPE_HATCHES: ReadonlyArray<[prefixed: string, raw: string]> = [
+  ["TamaguiCheckbox", "Checkbox"],
+  ["TamaguiInput", "Input"],
+  ["TamaguiLabel", "Label"],
+  ["TamaguiProgress", "Progress"],
+  ["TamaguiRadioGroup", "RadioGroup"],
+  ["TamaguiSelect", "Select"],
+  ["TamaguiSlider", "Slider"],
+  ["TamaguiSwitch", "Switch"],
+  ["TamaguiTextArea", "TextArea"],
+  ["TamaguiToggleGroup", "ToggleGroup"],
+];
+
+const HOUSE_SHADOWS = ["Avatar", "Card", "Fieldset", "Image", "Menu", "Tabs", "Toast", "Tooltip"];
+
+describe("curated tamagui surface", () => {
+  it("does not export bare interactive primitives that have house forms equivalents", () => {
+    for (const name of EXCLUDED_BARE_NAMES) {
+      expect(
+        (pkg as Record<string, unknown>)[name],
+        `barrel must not export bare "${name}"`,
+      ).toBeUndefined();
+    }
+  });
+
+  it("exports the benign allowlist (layout, text, styling, theme, overlay roots)", () => {
+    for (const name of ALLOWLIST_VALUE_NAMES) {
+      expect((pkg as Record<string, unknown>)[name], `barrel must export "${name}"`).toBeDefined();
+      expect(
+        (pkg as Record<string, unknown>)[name],
+        `barrel "${name}" must be the tamagui export`,
+      ).toBe((tamagui as Record<string, unknown>)[name]);
+    }
+  });
+
+  it("exposes deliberate raw usage only through Tamagui*-prefixed escape hatches", () => {
+    for (const [prefixed, raw] of ESCAPE_HATCHES) {
+      expect(
+        (pkg as Record<string, unknown>)[prefixed],
+        `barrel must export escape hatch "${prefixed}"`,
+      ).toBe((tamagui as Record<string, unknown>)[raw]);
+    }
+  });
+
+  it("keeps house shadows as the house versions, not the tamagui primitives", () => {
+    for (const name of HOUSE_SHADOWS) {
+      const houseExport = (pkg as Record<string, unknown>)[name];
+      expect(houseExport, `barrel must export house "${name}"`).toBeDefined();
+      const rawExport = (tamagui as Record<string, unknown>)[name];
+      if (rawExport !== undefined) {
+        expect(houseExport, `barrel "${name}" must not be the raw tamagui primitive`).not.toBe(
+          rawExport,
+        );
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Type-level locks (checked by `tsc --noEmit`, not vitest): excluded Props
+// types must not be re-exported either, and allowlisted types must exist.
+// If an excluded type comes back, the @ts-expect-error goes unused and the
+// package typecheck fails — same lock, opposite direction.
+// ---------------------------------------------------------------------------
+// @ts-expect-error CheckboxProps is intentionally not exported (house: forms)
+type _NoCheckboxProps = import("./index").CheckboxProps;
+// @ts-expect-error SwitchProps is intentionally not exported (house: forms)
+type _NoSwitchProps = import("./index").SwitchProps;
+// @ts-expect-error InputProps is intentionally not exported (house: forms)
+type _NoInputProps = import("./index").InputProps;
+// @ts-expect-error SelectProps is intentionally not exported (house: forms)
+type _NoSelectProps = import("./index").SelectProps;
+// @ts-expect-error SliderProps is intentionally not exported (house: forms)
+type _NoSliderProps = import("./index").SliderProps;
+// @ts-expect-error LabelProps is intentionally not exported (house: forms)
+type _NoLabelProps = import("./index").LabelProps;
+
+type _HasViewProps = import("./index").ViewProps;
+type _HasXStackProps = import("./index").XStackProps;
+type _HasYStackProps = import("./index").YStackProps;
+type _HasTextProps = import("./index").TextProps;
+type _HasButtonProps = import("./index").ButtonProps;
+type _HasSizeTokens = import("./index").SizeTokens;
+type _HasFontSizeTokens = import("./index").FontSizeTokens;
+type _HasThemeName = import("./index").ThemeName;
+type _HasTamaguiElement = import("./index").TamaguiElement;
+type _HasGetProps = import("./index").GetProps<typeof pkg.View>;

package/src/tamagui.ts

@@ -0,0 +1,126 @@
+// Curated tamagui re-export surface for @multiplatform.one/components.
+//
+// This module replaces the old `export * from "tamagui"` star export, which
+// leaked every raw tamagui primitive under the house package name. That leak
+// let consumers grab interactive primitives (Checkbox, Switch, Select, …)
+// that have house equivalents in @multiplatform.one/forms — raw compounds
+// render broken without composed children (see the todos Checkbox incident),
+// while still passing the "no raw tamagui outside public/" lint rule.
+//
+// Rules for this file:
+// - Re-export ONLY benign building blocks: layout, text, styling/theme
+//   utilities, and overlay composition roots that house surfaces
+//   (DialogContent, PopoverContent, SheetFrame) are designed to compose with.
+// - NEVER re-export a bare interactive primitive that has a house equivalent
+//   in @multiplatform.one/forms (Checkbox, Switch, RadioGroup, Select,
+//   Slider, ToggleGroup, Input, TextArea, Label, Form, Progress).
+// - Deliberate raw usage goes through the explicit `Tamagui*`-prefixed
+//   escape hatches below (same precedent as TamaguiToast in index.ts) so the
+//   rawness is visible and greppable at the import site.
+// - The curation is locked by tamagui.spec.ts — update both together.
+
+// Layout primitives (no house replacement)
+export {
+  Circle,
+  Group,
+  ListItem,
+  ScrollView,
+  Separator,
+  Spacer,
+  Square,
+  View,
+  XGroup,
+  XStack,
+  YGroup,
+  YStack,
+} from "tamagui";
+
+// Text primitives (no house replacement)
+export { Anchor, H1, H2, H3, H4, H5, H6, Heading, Paragraph, SizableText, Text } from "tamagui";
+
+// Actions / feedback primitives that work standalone (no footgun anatomy)
+export { Button, Spinner } from "tamagui";
+
+// Overlay composition roots — the house DialogContent / PopoverContent /
+// SheetFrame surfaces are designed to compose inside these raw roots.
+export { Adapt, AlertDialog, Dialog, Popover, Portal, PortalProvider, Sheet } from "tamagui";
+
+// Providers / theme / animation
+export { AnimatePresence, TamaguiProvider, Theme } from "tamagui";
+
+// Hooks
+export {
+  useControllableState,
+  useDidFinishSSR,
+  useEvent,
+  useMedia,
+  usePropsAndStyle,
+  useTheme,
+  useThemeName,
+} from "tamagui";
+
+// Styling utilities
+export {
+  createStyledContext,
+  getToken,
+  getTokens,
+  getTokenValue,
+  isClient,
+  isWeb,
+  styled,
+  withStaticProperties,
+} from "tamagui";
+
+// Types for the allowlisted surface
+export type {
+  AnchorProps,
+  ButtonProps,
+  CircleProps,
+  ColorTokens,
+  DialogProps,
+  FontSizeTokens,
+  GetProps,
+  GetRef,
+  GroupProps,
+  HeadingProps,
+  ListItemProps,
+  ParagraphProps,
+  PopoverProps,
+  RadiusTokens,
+  ScrollViewProps,
+  SheetProps,
+  SizableTextProps,
+  SizeTokens,
+  SpaceTokens,
+  SpinnerProps,
+  SquareProps,
+  TamaguiConfig,
+  TamaguiElement,
+  TamaguiProviderProps,
+  TamaguiTextElement,
+  TextProps,
+  ThemeName,
+  ThemeProps,
+  ViewProps,
+  XStackProps,
+  YStackProps,
+} from "tamagui";
+
+// Explicit raw escape hatches (TamaguiToast precedent): these primitives are
+// EXCLUDED under their bare names because @multiplatform.one/forms owns the
+// house version. Deliberate, correctly-composed raw usage (playground
+// showcases, settings toggles that compose Thumb/Indicator themselves)
+// imports the prefixed name so the choice is explicit at the call site.
+// Prefer the forms field for new code.
+export {
+  Checkbox as TamaguiCheckbox,
+  Input as TamaguiInput,
+  Label as TamaguiLabel,
+  Progress as TamaguiProgress,
+  RadioGroup as TamaguiRadioGroup,
+  Select as TamaguiSelect,
+  Slider as TamaguiSlider,
+  Switch as TamaguiSwitch,
+  TextArea as TamaguiTextArea,
+  ToggleGroup as TamaguiToggleGroup,
+} from "tamagui";