@12-apps/ui 6.17.1 → 6.18.0

package/src/components/form/Button/Button.native.tsx

@@ -0,0 +1,339 @@
+import * as React from 'react';
+import {
+  ActivityIndicator,
+  Animated,
+  Easing,
+  Platform,
+  Pressable,
+  StyleSheet,
+  Text as RNText,
+  View,
+  type GestureResponderEvent,
+  type PressableStateCallbackType,
+  type StyleProp,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native';
+
+import { resolveButtonProps } from './Button.helpers';
+import {
+  BUTTON_FONT_WEIGHT,
+  BUTTON_ICON_GAP_UNITS,
+  BUTTON_LINE_HEIGHT,
+  BUTTON_RADIUS_UNITS,
+  BUTTON_SIZES,
+  BUTTON_SPINNER_SIZE,
+  BUTTON_WASH_ALPHA,
+  GLASS_BACKGROUND_ALPHA,
+  GLASS_BACKGROUND_ALPHA_PRESSED,
+  GLASS_BORDER_ALPHA,
+  GLOW_INNER_ALPHA,
+  GLOW_RADIUS,
+  ICON_ONLY_PADDING,
+  PULSE_ALPHA,
+  PULSE_DURATION_MS,
+  PULSE_SPREAD,
+  buttonPalette,
+  gradientStops,
+  quietInk,
+} from './Button.metrics';
+import type { ButtonProps, ButtonVariant } from './Button.types.native';
+import { childTestId, resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import { alpha } from '../../../tokens/color';
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+import type { UiPaletteColor, UiTheme } from '../../../tokens/theme';
+
+/** MUI's `min-width` for a button that carries a label. */
+const MIN_WIDTH = 64;
+
+interface Paint {
+  container: ViewStyle;
+  pressed: ViewStyle;
+  label: TextStyle;
+}
+
+/**
+ * What the web's `VARIANT_STYLES` paint, as three React Native styles: at rest,
+ * while pressed (the web's `:hover`, which touch has no equivalent of), and the
+ * label. Same palette arithmetic, same alphas.
+ *
+ * `gradient` is the one honest gap: React Native core has no gradient fill, so
+ * it paints the gradient's first stop. A host wanting the real thing adds a
+ * gradient library; the parity ledger records this.
+ */
+function paintFor(
+  theme: UiTheme,
+  variant: ButtonVariant,
+  color: ColorValue,
+  palette: UiPaletteColor,
+  active: boolean,
+): Paint {
+  const wash = alpha(palette.main, BUTTON_WASH_ALPHA);
+  switch (variant) {
+    case 'outline':
+      return {
+        container: { backgroundColor: 'transparent', borderWidth: 1, borderColor: palette.main },
+        pressed: { backgroundColor: wash, borderColor: palette.dark },
+        label: { color: palette.main },
+      };
+    case 'ghost':
+      return {
+        container: { backgroundColor: 'transparent' },
+        pressed: { backgroundColor: wash },
+        label: { color: quietInk(theme, palette) },
+      };
+    case 'text':
+      return {
+        container: { backgroundColor: active ? wash : 'transparent' },
+        pressed: { backgroundColor: wash },
+        label: { color: quietInk(theme, palette) },
+      };
+    case 'glass':
+      return {
+        container: {
+          backgroundColor: alpha(theme.palette.background.paper, GLASS_BACKGROUND_ALPHA),
+          borderWidth: 1,
+          borderColor: alpha(theme.palette.divider, GLASS_BORDER_ALPHA),
+        },
+        pressed: { backgroundColor: alpha(theme.palette.background.paper, GLASS_BACKGROUND_ALPHA_PRESSED) },
+        label: { color: palette.main },
+      };
+    case 'gradient': {
+      const [from, to] = gradientStops(theme, color, palette);
+      return {
+        container: { backgroundColor: from },
+        pressed: { backgroundColor: to },
+        label: { color: '#fff' },
+      };
+    }
+    default:
+      return {
+        container: { backgroundColor: palette.main },
+        pressed: { backgroundColor: palette.dark },
+        label: { color: palette.contrastText || '#fff' },
+      };
+  }
+}
+
+/** MUI's disabled treatment per variant family, so a disabled button reads as one on both sides. */
+function disabledPaint(theme: UiTheme, variant: ButtonVariant): Paint {
+  const filled = variant === 'solid' || variant === 'gradient' || variant === 'glass';
+  return {
+    container: filled
+      ? { backgroundColor: theme.palette.action.disabledBackground, borderWidth: 0 }
+      : variant === 'outline'
+        ? { backgroundColor: 'transparent', borderWidth: 1, borderColor: theme.palette.action.disabledBackground }
+        : { backgroundColor: 'transparent' },
+    pressed: {},
+    label: { color: theme.palette.action.disabled },
+  };
+}
+
+function sizeStyle(theme: UiTheme, size: SizeValue, iconOnly: boolean, hasIcon: boolean): ViewStyle {
+  const metrics = BUTTON_SIZES[size];
+  if (iconOnly) {
+    return { padding: ICON_ONLY_PADDING[size], minWidth: 0 };
+  }
+  return {
+    paddingVertical: metrics.paddingVertical,
+    paddingHorizontal: metrics.paddingHorizontal,
+    minWidth: MIN_WIDTH,
+    gap: hasIcon ? theme.spacing(BUTTON_ICON_GAP_UNITS) : undefined,
+  };
+}
+
+function glowStyle(palette: UiPaletteColor): ViewStyle {
+  return Platform.select<ViewStyle>({
+    android: { elevation: 8 },
+    default: {
+      shadowColor: palette.main,
+      shadowOpacity: GLOW_INNER_ALPHA,
+      shadowRadius: GLOW_RADIUS,
+      shadowOffset: { width: 0, height: 0 },
+    },
+  });
+}
+
+/** The web's `::after` pulse ring: a looped scale-and-fade behind the button. */
+function Pulse({ color, radius, testID }: { color: string; radius: number; testID: string }): React.JSX.Element {
+  const progress = React.useRef(new Animated.Value(0)).current;
+
+  React.useEffect(() => {
+    const loop = Animated.loop(
+      Animated.timing(progress, {
+        toValue: 1,
+        duration: PULSE_DURATION_MS,
+        easing: Easing.out(Easing.ease),
+        useNativeDriver: Platform.OS !== 'web',
+      }),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [progress]);
+
+  return (
+    <Animated.View
+      testID={testID}
+      aria-hidden
+      style={[
+        StyleSheet.absoluteFill,
+        {
+          pointerEvents: 'none',
+          borderRadius: radius,
+          backgroundColor: color,
+          opacity: progress.interpolate({ inputRange: [0, 0.7, 1], outputRange: [PULSE_ALPHA, 0, 0] }),
+          transform: [
+            { scale: progress.interpolate({ inputRange: [0, 0.7, 1], outputRange: [1, 1 + PULSE_SPREAD / 40, 1] }) },
+          ],
+        },
+      ]}
+    />
+  );
+}
+
+/**
+ * A string or number child is the label and gets the label style; anything
+ * else is rendered as given. No test id of its own: the web puts none on the
+ * label, and a shared story that counts `/perf-button-/` must count buttons.
+ */
+function renderChildren(children: React.ReactNode, label: TextStyle): React.ReactNode {
+  return React.Children.map(children, (child) =>
+    typeof child === 'string' || typeof child === 'number' ? (
+      <RNText style={label} numberOfLines={1}>
+        {child}
+      </RNText>
+    ) : (
+      child
+    ),
+  );
+}
+
+type ResolvedProps = ReturnType<typeof resolveButtonProps<ButtonProps>>;
+
+interface ButtonLook {
+  inactive: boolean;
+  palette: UiPaletteColor;
+  radius: number;
+  label: TextStyle;
+  container: (state: PressableStateCallbackType) => StyleProp<ViewStyle>;
+}
+
+/**
+ * Everything the button paints, decided once per render from the resolved
+ * props and the theme. Kept out of the component so the component reads as
+ * structure — what renders where — and this reads as arithmetic.
+ */
+function buttonLook(theme: UiTheme, props: ResolvedProps): ButtonLook {
+  const { variant, color, size, loading, icon, children, glow, pulse, active, disabled, style } = props;
+  const palette = buttonPalette(theme, color);
+  const iconOnly = !loading && icon != null && children == null;
+  const inactive = Boolean(disabled) || loading;
+  const paint = inactive ? disabledPaint(theme, variant) : paintFor(theme, variant, color, palette, active);
+  const radius = theme.spacing(BUTTON_RADIUS_UNITS);
+  const metrics = BUTTON_SIZES[size];
+  // The web button is `overflow: hidden` (its ripple needs it) unless the pulse
+  // ring turns it visible; on native the glow's shadow needs it visible too,
+  // because a view's own shadow is clipped by its own overflow there.
+  const overflow: ViewStyle['overflow'] = pulse || glow ? 'visible' : 'hidden';
+  const sized = sizeStyle(theme, size, iconOnly, icon != null && !loading);
+  const glowing = glow && !inactive ? glowStyle(palette) : null;
+
+  return {
+    inactive,
+    palette,
+    radius,
+    label: {
+      fontFamily: theme.typography.fontFamily,
+      fontSize: metrics.fontSize,
+      lineHeight: metrics.fontSize * BUTTON_LINE_HEIGHT,
+      fontWeight: String(BUTTON_FONT_WEIGHT) as TextStyle['fontWeight'],
+      textAlign: 'center',
+      ...paint.label,
+    },
+    container: (state) => [
+      styles.base,
+      { borderRadius: radius, overflow },
+      sized,
+      paint.container,
+      state.pressed && !inactive ? paint.pressed : null,
+      glowing,
+      style,
+    ],
+  };
+}
+
+/** The spinner that replaces the label while loading; `role` comes from react-native's ActivityIndicator. */
+function Spinner({ color, testID }: { color: string; testID: string }): React.JSX.Element {
+  return (
+    <ActivityIndicator
+      size={Platform.OS === 'ios' ? 'small' : BUTTON_SPINNER_SIZE}
+      color={color}
+      testID={testID}
+      accessibilityLabel="loading"
+    />
+  );
+}
+
+export const Button = React.forwardRef<View, ButtonProps>((rawProps, ref) => {
+  const resolved = resolveButtonProps(rawProps);
+  const { loading, icon, iconPosition, pulse, ripple, children, onClick, onPress, ...others } = resolved;
+  const theme = useUiTheme();
+  const look = buttonLook(theme, resolved);
+
+  // The shared stories pass `'data-testid'` as a plain prop; honour it here and
+  // keep all three spellings off the element (react-native-web would drop them).
+  const testId = resolveTestId(others, 'button');
+  const idFor = (suffix: string) => childTestId(others, suffix, 'button');
+  const rest = withoutTestIdProps(others);
+  // `buttonLook` consumed these; they are not Pressable props.
+  const { variant: _v, color: _c, size: _s, glow: _g, active: _a, disabled: _d, style: _st, ...pressable } = rest;
+
+  const handlePress = (event: GestureResponderEvent): void => {
+    onClick?.(event);
+    onPress?.(event);
+  };
+
+  const iconNode =
+    !loading && icon ? (
+      <View style={styles.icon} testID={idFor('icon')}>
+        {icon}
+      </View>
+    ) : null;
+
+  return (
+    <Pressable
+      ref={ref}
+      role="button"
+      aria-disabled={look.inactive}
+      aria-busy={loading}
+      disabled={look.inactive}
+      onPress={handlePress}
+      android_ripple={ripple && !look.inactive ? { color: alpha(look.palette.main, 0.2), borderless: false } : undefined}
+      style={look.container}
+      testID={testId}
+      {...pressable}
+    >
+      {pulse && !look.inactive ? <Pulse color={look.palette.main} radius={look.radius} testID={idFor('pulse')} /> : null}
+      {iconPosition === 'left' ? iconNode : null}
+      {loading ? <Spinner color={look.label.color as string} testID={idFor('loading')} /> : renderChildren(children, look.label)}
+      {iconPosition === 'right' ? iconNode : null}
+    </Pressable>
+  );
+});
+
+Button.displayName = 'Button';
+
+const styles = StyleSheet.create({
+  base: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    alignSelf: 'flex-start',
+    position: 'relative',
+  },
+  icon: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+});

package/src/components/form/Button/Button.styles.ts

@@ -1,6 +1,9 @@
 import { alpha, darken, keyframes, lighten } from '@mui/material/styles/index.js';
 import type { CSSObject, Theme } from '@mui/material/styles/index.js';
 
+import { BUTTON_SIZES, ICON_ONLY_PADDING as ICON_ONLY_PADDING_PX } from './Button.metrics';
+import { px } from '../../../tokens/theme';
+
 // Define pulse animation globally
 const pulseAnimation = keyframes`
   0% {
@@ -62,16 +65,17 @@ export const getColorFromTheme = (theme: Theme, color: string): ColorPalette =>
   };
 };
 
-/** What an unrecognised size falls back to, named so indexing can never be undefined. */
-const DEFAULT_SIZE: CSSObject = { padding: '8px 16px', fontSize: '1rem' };
+// Derived from `Button.metrics.ts`, which the native `Button` reads too — one
+// table, so a size cannot differ between the renderers.
+const SIZE_MAP: Record<string, CSSObject> = Object.fromEntries(
+  Object.entries(BUTTON_SIZES).map(([size, m]) => [
+    size,
+    { padding: `${m.paddingVertical}px ${m.paddingHorizontal}px`, fontSize: px(m.fontSize) },
+  ]),
+);
 
-const SIZE_MAP: Record<string, CSSObject> = {
-  xs: { padding: '2px 8px', fontSize: '0.75rem' },
-  sm: { padding: '6px 12px', fontSize: '0.875rem' },
-  md: DEFAULT_SIZE,
-  lg: { padding: '10px 20px', fontSize: '1.125rem' },
-  xl: { padding: '12px 24px', fontSize: '1.25rem' },
-};
+/** What an unrecognised size falls back to, named so indexing can never be undefined. */
+const DEFAULT_SIZE: CSSObject = SIZE_MAP.md as CSSObject;
 
 /**
  * A BUTTON THAT IS ONLY AN ICON IS SQUARE.
@@ -86,13 +90,9 @@ const SIZE_MAP: Record<string, CSSObject> = {
  * Derived, not declared: a button with an `icon` and no children can only be an
  * icon button, so no consumer has to opt in and none can forget to.
  */
-const ICON_ONLY_PADDING: Record<string, string> = {
-  xs: '2px',
-  sm: '5px',
-  md: '7px',
-  lg: '9px',
-  xl: '11px',
-};
+const ICON_ONLY_PADDING: Record<string, string> = Object.fromEntries(
+  Object.entries(ICON_ONLY_PADDING_PX).map(([size, padding]) => [size, `${padding}px`]),
+);
 
 const iconOnlySize = (size: string): CSSObject => ({
   minWidth: 0,

package/src/components/form/Button/Button.tsx

@@ -4,6 +4,7 @@ import { styled } from '@mui/material/styles/index.js';
 import * as React from 'react';
 
 import { resolveButtonProps } from './Button.helpers';
+import { childTestId, resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
 import {
   buttonEmphasisStyles,
   buttonVariantStyles,
@@ -88,11 +89,13 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
       onClick,
       onFocus,
       onBlur,
-      dataTestId,
-      ...props
+      ...others
     } = resolveButtonProps(rawProps);
-    const testId = (suffix: string) =>
-      dataTestId ? `${dataTestId}-${suffix}` : `button-${suffix}`;
+    // Every spelling of the test id the shared contract allows, mapped to the
+    // one the DOM reads; the native Button does the same in reverse.
+    const ownTestId = resolveTestId(others, 'button');
+    const testId = (suffix: string) => childTestId(others, suffix, 'button');
+    const props = withoutTestIdProps(others);
 
     // Wrap icon with testId if provided
     const iconWithTestId =
@@ -122,7 +125,7 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
         onFocus={onFocus}
         onBlur={onBlur}
         sx={buttonSize(size, iconOnly)}
-        data-testid={dataTestId || 'button'}
+        data-testid={ownTestId}
         {...props}
         className={mergedClassName}
       >

package/src/components/form/Button/Button.types.native.ts

@@ -0,0 +1,27 @@
+import type {
+  GestureResponderEvent,
+  NativeSyntheticEvent,
+  PressableProps,
+  StyleProp,
+  TargetedEvent,
+  ViewStyle,
+} from 'react-native';
+
+import type { ButtonBaseProps } from './Button.base';
+
+export type { ButtonBaseProps, ButtonVariant } from './Button.base';
+
+/**
+ * The native `Button`. `onClick` keeps its web name — the 179 call sites in
+ * the origin apps spell it that way and a shared screen should not have to
+ * know which renderer it is on — and `onPress` is accepted too, because that is
+ * what a React Native developer will reach for. Both fire.
+ */
+export type ButtonProps = ButtonBaseProps &
+  Omit<PressableProps, keyof ButtonBaseProps | 'style' | 'onPress' | 'onFocus' | 'onBlur'> & {
+    onClick?: (event: GestureResponderEvent) => void;
+    onPress?: (event: GestureResponderEvent) => void;
+    onFocus?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
+    onBlur?: (event: NativeSyntheticEvent<TargetedEvent>) => void;
+    style?: StyleProp<ViewStyle>;
+  };

package/src/components/form/Button/Button.types.ts

@@ -1,75 +1,25 @@
-import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { ButtonProps as MuiButtonProps } from '@mui/material/Button/index.js';
 import type * as React from 'react';
 
-export interface ButtonProps extends Omit<MuiButtonProps, 'variant' | 'color' | 'size'> {
-  /**
-   * The variant of the button
-   */
-  variant?: 'solid' | 'outline' | 'ghost' | 'text' | 'glass' | 'gradient';
+import type { ButtonBaseProps } from './Button.base';
 
-  /**
-   * The color of the button
-   */
-  color?: ColorValue;
-  
-  /**
-   * The size of the button
-   */
-  size?: SizeValue;
-  
-  /**
-   * Whether the button is in loading state
-   */
-  loading?: boolean;
-  
-  /**
-   * Icon to display in the button
-   */
-  icon?: React.ReactNode;
-  
-  /**
-   * Position of the icon
-   */
-  iconPosition?: 'left' | 'right';
-
-  /**
-   * Whether the button should have a glow effect
-   */
-  glow?: boolean;
-  
-  /**
-   * Whether the button should have a pulse animation
-   */
-  pulse?: boolean;
-  
-  /**
-   * Whether to show ripple effect on click
-   */
-  ripple?: boolean;
-
-  /**
-   * Whether the button is in active state
-   */
-  active?: boolean;
+export type { ButtonBaseProps, ButtonVariant } from './Button.base';
 
+export interface ButtonProps
+  extends ButtonBaseProps,
+    Omit<MuiButtonProps, 'variant' | 'color' | 'size' | keyof ButtonBaseProps> {
   /**
    * Click handler
    */
   onClick?: React.MouseEventHandler<HTMLButtonElement>;
-  
+
   /**
    * Focus handler
    */
   onFocus?: React.FocusEventHandler<HTMLButtonElement>;
-  
+
   /**
    * Blur handler
    */
   onBlur?: React.FocusEventHandler<HTMLButtonElement>;
-
-  /**
-   * Test ID for testing purposes
-   */
-  dataTestId?: string;
-}
+}

package/src/components/form/Button/index.native.ts

@@ -0,0 +1,2 @@
+export { Button } from './Button.native';
+export type { ButtonBaseProps, ButtonProps, ButtonVariant } from './Button.types.native';

package/src/components/form/Button/index.ts

@@ -1,2 +1,2 @@
 export { Button } from './Button';
-export type { ButtonProps } from './Button.types';
+export type { ButtonBaseProps, ButtonProps, ButtonVariant } from './Button.types';

package/src/components/layout/Box/Box.base.ts

@@ -0,0 +1,69 @@
+import type * as React from 'react';
+
+import type { UiPaletteKey, UiTheme } from '../../../tokens/theme';
+
+/**
+ * THE LAYOUT PRIMITIVE BOTH RENDERERS SHARE.
+ *
+ * Half of every screen in the origin apps is `@12-apps/ui/mui/Box` with an `sx`
+ * — raw MUI, which no native renderer can ever answer to. This `Box` is the
+ * one a screen meant for both platforms writes instead: a fixed set of layout
+ * props on the spacing scale, resolved by `box-layout.ts` into the same
+ * numbers on each side. `p={2}` is 16px on the web and 16dp on native, because
+ * both are `theme.spacing(2)`.
+ *
+ * Spacing props are in SPACING UNITS, exactly as MUI's own `Box` reads them.
+ */
+export type BoxDirection = 'row' | 'column' | 'row-reverse' | 'column-reverse';
+export type BoxAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+export type BoxJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+export type BoxBackground = 'default' | 'paper' | 'transparent' | UiPaletteKey;
+export type BoxRadius = keyof UiTheme['radius'];
+/** What both renderers accept as a size: px, a percentage, or `auto`. */
+export type BoxDimension = number | 'auto' | `${number}%`;
+
+export interface BoxSpacingProps {
+  p?: number;
+  px?: number;
+  py?: number;
+  pt?: number;
+  pr?: number;
+  pb?: number;
+  pl?: number;
+  m?: number;
+  mx?: number;
+  my?: number;
+  mt?: number;
+  mr?: number;
+  mb?: number;
+  ml?: number;
+  /** Between children. Setting it makes the box a flex container. */
+  gap?: number;
+}
+
+export interface BoxBaseProps extends BoxSpacingProps {
+  children?: React.ReactNode;
+  /** Setting any of these four makes the box a flex container. */
+  direction?: BoxDirection;
+  align?: BoxAlign;
+  justify?: BoxJustify;
+  wrap?: boolean;
+  flex?: number;
+  /** A surface, `transparent`, or a palette slot's main colour. */
+  bg?: BoxBackground;
+  radius?: BoxRadius;
+  /** A 1px border in the theme's divider colour. */
+  bordered?: boolean;
+  width?: BoxDimension;
+  height?: BoxDimension;
+  testID?: string;
+  dataTestId?: string;
+}
+
+/** Every prop {@link BoxBaseProps} owns, so a renderer can split them from its own. */
+export const BOX_BASE_KEYS = [
+  'p', 'px', 'py', 'pt', 'pr', 'pb', 'pl',
+  'm', 'mx', 'my', 'mt', 'mr', 'mb', 'ml',
+  'gap', 'direction', 'align', 'justify', 'wrap', 'flex',
+  'bg', 'radius', 'bordered', 'width', 'height', 'testID', 'dataTestId',
+] as const satisfies readonly (keyof Omit<BoxBaseProps, 'children'>)[];

package/src/components/layout/Box/Box.md

@@ -0,0 +1,46 @@
+# Box
+
+The layout primitive both renderers share.
+
+`@12-apps/ui/mui/Box` is raw MUI: an `sx` prop and nothing a React Native
+renderer could ever answer to. This `Box` is what a screen meant for both
+platforms writes instead. Its props are a fixed vocabulary on the spacing
+scale, and one resolver (`box-layout.ts`) turns them into the same numbers on
+each side — `p={2}` is `theme.spacing(2)`, 16px on the web and 16dp on native.
+
+```tsx
+import { Box } from '@12-apps/ui/layout/Box';
+
+<Box direction="row" gap={2} align="center" p={2} bg="paper" radius="lg" bordered>
+  …
+</Box>
+```
+
+## Props
+
+| prop | type | notes |
+|---|---|---|
+| `p` `px` `py` `pt` `pr` `pb` `pl` | `number` | padding, in spacing units; the specific side wins over the axis, the axis over `p` |
+| `m` `mx` `my` `mt` `mr` `mb` `ml` | `number` | margin, same rules |
+| `gap` | `number` | between children; makes the box a flex container |
+| `direction` | `row` `column` `row-reverse` `column-reverse` | makes the box a flex container (`column` when only `gap`/`align`/`justify` is set) |
+| `align` | `start` `center` `end` `stretch` `baseline` | `alignItems` |
+| `justify` | `start` `center` `end` `between` `around` `evenly` | `justifyContent` |
+| `wrap` | `boolean` | `flexWrap: wrap` |
+| `flex` | `number` | |
+| `bg` | `default` `paper` `transparent` or a palette slot | a surface, or the slot's `main` |
+| `radius` | `sm` `md` `lg` `xl` `full` | the theme's radius scale (2, 4, 8, 16 px by default) |
+| `bordered` | `boolean` | a 1px border in the divider colour |
+| `width` `height` | `number` `'auto'` `'50%'` | what both renderers accept as a size |
+| `testID` / `dataTestId` | `string` | either spelling; rendered as `data-testid` on the web |
+
+On the **web** every other prop of MUI's `Box` is accepted too, `sx` included —
+it is applied after the resolved layout, so it still wins. On **native** the
+extras are a `View`'s own (`style`, `onLayout`, `accessibilityLabel`…).
+
+## What differs between renderers
+
+A `View` is always a flex column; MUI's `Box` is a `div`, a block, until a
+layout prop makes it flex. Children stack the same way in both, so the only
+observable difference is `display` on a box with no layout props — which is
+why the `BlockByDefault` test story is tagged `native-skip`.

package/src/components/layout/Box/Box.native.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { View } from 'react-native';
+
+import { resolveBoxLayout, splitBoxProps } from './box-layout';
+import type { BoxProps } from './Box.types.native';
+import { resolveTestId } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+
+/** The native `Box`: a `View` with the same resolved numbers the web `Box` puts in `sx`. */
+export const Box = React.forwardRef<View, BoxProps>(({ children, style, ...props }, ref) => {
+  const theme = useUiTheme();
+  const { layout, rest } = splitBoxProps(props);
+  const resolved = resolveBoxLayout(layout, theme);
+
+  return (
+    <View ref={ref} style={[resolved, style]} testID={resolveTestId(layout)} {...rest}>
+      {children}
+    </View>
+  );
+});
+
+Box.displayName = 'Box';