@12-apps/ui 6.17.1 → 6.19.0

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

@@ -0,0 +1,56 @@
+import MuiBox from '@mui/material/Box/index.js';
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+import * as React from 'react';
+
+import { resolveBoxLayout, splitBoxProps, type BoxLayout } from './box-layout';
+import type { BoxProps } from './Box.types';
+import { resolveTestId } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme';
+
+/**
+ * `sx` is not CSS: it reads a bare number on `padding`, `margin` or `gap` as
+ * SPACING UNITS, on `borderRadius` as a multiple of `shape.borderRadius`, and a
+ * `width` of `1` or less as a fraction. The resolver's numbers are already px,
+ * so every one of them is written as a px string — otherwise a `p={2}` box
+ * renders 128px of padding on the web and 16dp on native, which is the one
+ * thing this component exists to rule out.
+ */
+const PX_KEYS = new Set<keyof BoxLayout>([
+  'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft',
+  'marginTop', 'marginRight', 'marginBottom', 'marginLeft',
+  'gap', 'borderRadius', 'borderWidth', 'width', 'height',
+]);
+
+export function layoutToSx(layout: BoxLayout): Record<string, string | number> {
+  return Object.fromEntries(
+    Object.entries(layout).map(([key, value]) => [
+      key,
+      typeof value === 'number' && PX_KEYS.has(key as keyof BoxLayout) ? `${value}px` : value,
+    ]),
+  );
+}
+
+/**
+ * The web `Box`: MUI's, with the neutral layout props resolved into `sx` ahead
+ * of whatever `sx` the caller adds — so the caller's escape hatch still wins.
+ */
+export const Box = React.forwardRef<HTMLDivElement, BoxProps>(
+  ({ children, sx, ...props }, ref) => {
+    const theme = useUiTheme();
+    const { layout, rest } = splitBoxProps(props);
+    const resolved = layoutToSx(resolveBoxLayout(layout, theme)) as SxProps<Theme>;
+    const testId = resolveTestId(layout);
+    const merged: SxProps<Theme> = [
+      resolved,
+      ...(Array.isArray(sx) ? sx : sx === undefined ? [] : [sx]),
+    ] as SxProps<Theme>;
+
+    return (
+      <MuiBox ref={ref} sx={merged} data-testid={testId} {...rest}>
+        {children}
+      </MuiBox>
+    );
+  },
+);
+
+Box.displayName = 'Box';

package/src/components/layout/Box/Box.types.native.ts

@@ -0,0 +1,21 @@
+import type { StyleProp, ViewProps, ViewStyle } from 'react-native';
+
+import type { BoxBaseProps } from './Box.base';
+
+export type {
+  BoxAlign,
+  BoxBackground,
+  BoxBaseProps,
+  BoxDimension,
+  BoxDirection,
+  BoxJustify,
+  BoxRadius,
+  BoxSpacingProps,
+} from './Box.base';
+export { BOX_BASE_KEYS } from './Box.base';
+
+/** The native `Box`: the neutral props, plus a `View`'s own where they do not overlap. */
+export type BoxProps = BoxBaseProps &
+  Omit<ViewProps, keyof BoxBaseProps | 'style'> & {
+    style?: StyleProp<ViewStyle>;
+  };

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

@@ -0,0 +1,22 @@
+import type { BoxProps as MuiBoxProps } from '@mui/material/Box/index.js';
+
+import { BOX_BASE_KEYS, type BoxBaseProps } from './Box.base';
+
+export type {
+  BoxAlign,
+  BoxBackground,
+  BoxBaseProps,
+  BoxDimension,
+  BoxDirection,
+  BoxJustify,
+  BoxRadius,
+  BoxSpacingProps,
+} from './Box.base';
+export { BOX_BASE_KEYS } from './Box.base';
+
+/**
+ * The web `Box`: the neutral props, plus whatever MUI's `Box` accepts that they
+ * do not already name. `sx` stays available — it is the web's escape hatch and
+ * the reason nothing a web screen does today has to change.
+ */
+export type BoxProps = BoxBaseProps & Omit<MuiBoxProps, (typeof BOX_BASE_KEYS)[number] | 'children'>;

package/src/components/layout/Box/box-layout.ts

@@ -0,0 +1,144 @@
+import { BOX_BASE_KEYS, type BoxAlign, type BoxBaseProps, type BoxDimension, type BoxJustify } from './Box.base';
+import type { UiTheme } from '../../../tokens/theme';
+
+/**
+ * The resolved style, in React Native's property names.
+ *
+ * They are also valid CSS-in-JS names, and every number is px on the web and
+ * dp on native, so ONE resolver feeds both `Box.tsx` (into `sx`) and
+ * `Box.native.tsx` (into `style`). That is the alignment guarantee: there is no
+ * second table of numbers for the native side to drift from.
+ */
+export interface BoxLayout {
+  display?: 'flex';
+  flexDirection?: BoxBaseProps['direction'];
+  alignItems?: 'flex-start' | 'center' | 'flex-end' | 'stretch' | 'baseline';
+  justifyContent?: 'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly';
+  flexWrap?: 'wrap';
+  flex?: number;
+  gap?: number;
+  paddingTop?: number;
+  paddingRight?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+  marginTop?: number;
+  marginRight?: number;
+  marginBottom?: number;
+  marginLeft?: number;
+  backgroundColor?: string;
+  borderRadius?: number;
+  borderWidth?: number;
+  borderStyle?: 'solid';
+  borderColor?: string;
+  width?: BoxDimension;
+  height?: BoxDimension;
+}
+
+const ALIGN: Record<BoxAlign, NonNullable<BoxLayout['alignItems']>> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+  baseline: 'baseline',
+};
+
+const JUSTIFY: Record<BoxJustify, NonNullable<BoxLayout['justifyContent']>> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+  evenly: 'space-evenly',
+};
+
+function background(theme: UiTheme, bg: NonNullable<BoxBaseProps['bg']>): string {
+  if (bg === 'transparent') return 'transparent';
+  if (bg === 'default' || bg === 'paper') return theme.palette.background[bg];
+  return theme.palette[bg].main;
+}
+
+type SpacingKey = keyof Pick<
+  BoxLayout,
+  | 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft'
+  | 'marginTop' | 'marginRight' | 'marginBottom' | 'marginLeft'
+>;
+
+/**
+ * Each side reads the most specific prop that is set: the side, then its axis,
+ * then the shorthand — the precedence MUI's `Box` gives `pt`/`py`/`p`.
+ */
+const SIDES: ReadonlyArray<readonly [SpacingKey, ReadonlyArray<keyof BoxBaseProps>]> = [
+  ['paddingTop', ['pt', 'py', 'p']],
+  ['paddingRight', ['pr', 'px', 'p']],
+  ['paddingBottom', ['pb', 'py', 'p']],
+  ['paddingLeft', ['pl', 'px', 'p']],
+  ['marginTop', ['mt', 'my', 'm']],
+  ['marginRight', ['mr', 'mx', 'm']],
+  ['marginBottom', ['mb', 'my', 'm']],
+  ['marginLeft', ['ml', 'mx', 'm']],
+];
+
+function spacingLayout(props: BoxBaseProps, theme: UiTheme): BoxLayout {
+  const layout: BoxLayout = {};
+  for (const [key, sources] of SIDES) {
+    const units = sources.map((source) => props[source]).find((value) => value !== undefined);
+    if (typeof units === 'number') layout[key] = theme.spacing(units);
+  }
+  return layout;
+}
+
+/** A flex container whenever any flex prop is set; a plain box otherwise. */
+function flexLayout(props: BoxBaseProps, theme: UiTheme): BoxLayout {
+  const layout: BoxLayout = {};
+  const isFlex =
+    [props.direction, props.align, props.justify, props.gap].some((value) => value !== undefined) ||
+    props.wrap === true;
+  if (!isFlex) return layout;
+
+  layout.display = 'flex';
+  layout.flexDirection = props.direction ?? 'column';
+  if (props.gap !== undefined) layout.gap = theme.spacing(props.gap);
+  if (props.align !== undefined) layout.alignItems = ALIGN[props.align];
+  if (props.justify !== undefined) layout.justifyContent = JUSTIFY[props.justify];
+  if (props.wrap) layout.flexWrap = 'wrap';
+  return layout;
+}
+
+function surfaceLayout(props: BoxBaseProps, theme: UiTheme): BoxLayout {
+  const layout: BoxLayout = {};
+  if (props.flex !== undefined) layout.flex = props.flex;
+  if (props.bg !== undefined) layout.backgroundColor = background(theme, props.bg);
+  if (props.radius !== undefined) layout.borderRadius = theme.radius[props.radius];
+  if (props.bordered) {
+    // `borderStyle` spelled out: CSS defaults it to `none`, under which a
+    // border-width computes to 0 and nothing paints. React Native's default is
+    // `solid`, which is how a box can pass natively and vanish on the web.
+    layout.borderWidth = 1;
+    layout.borderStyle = 'solid';
+    layout.borderColor = theme.palette.divider;
+  }
+  if (props.width !== undefined) layout.width = props.width;
+  if (props.height !== undefined) layout.height = props.height;
+  return layout;
+}
+
+/** The style for a box's neutral props. Unset props produce no key at all. */
+export function resolveBoxLayout(props: BoxBaseProps, theme: UiTheme): BoxLayout {
+  return { ...spacingLayout(props, theme), ...flexLayout(props, theme), ...surfaceLayout(props, theme) };
+}
+
+/** The neutral props on one side, everything else — the renderer's own — on the other. */
+export function splitBoxProps<P extends BoxBaseProps>(
+  props: P,
+): { layout: BoxBaseProps; rest: Omit<P, (typeof BOX_BASE_KEYS)[number]> } {
+  const layout: Record<string, unknown> = {};
+  const rest: Record<string, unknown> = {};
+  const own = new Set<string>([...BOX_BASE_KEYS, 'data-testid']);
+  for (const [key, value] of Object.entries(props)) {
+    (own.has(key) ? layout : rest)[key] = value;
+  }
+  return {
+    layout: layout as BoxBaseProps,
+    rest: rest as Omit<P, (typeof BOX_BASE_KEYS)[number]>,
+  };
+}

package/src/components/layout/Box/index.native.ts

@@ -0,0 +1,14 @@
+export { Box } from './Box.native';
+export type {
+  BoxAlign,
+  BoxBackground,
+  BoxBaseProps,
+  BoxDimension,
+  BoxDirection,
+  BoxJustify,
+  BoxProps,
+  BoxRadius,
+  BoxSpacingProps,
+} from './Box.types.native';
+export { resolveBoxLayout } from './box-layout';
+export type { BoxLayout } from './box-layout';

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

@@ -0,0 +1,14 @@
+export { Box } from './Box';
+export type {
+  BoxAlign,
+  BoxBackground,
+  BoxBaseProps,
+  BoxDimension,
+  BoxDirection,
+  BoxJustify,
+  BoxProps,
+  BoxRadius,
+  BoxSpacingProps,
+} from './Box.types';
+export { resolveBoxLayout } from './box-layout';
+export type { BoxLayout } from './box-layout';

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

@@ -0,0 +1,32 @@
+import type React from 'react';
+
+/**
+ * THE CONTRACT BOTH `Container` RENDERERS HONOUR — and nothing else.
+ *
+ * No MUI and no react-native here, on purpose: this file ships in both
+ * declaration outputs (`dist/types` and `dist/types-native`), and a native
+ * consumer has no `@mui/material` to resolve a type import against. The web
+ * adds MUI `Container`'s own props in `Container.types.ts`; the native side
+ * adds a `View`'s in `Container.types.native.ts`.
+ */
+export type ContainerMaxWidth = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false;
+export type ContainerVariant = 'default' | 'fluid' | 'centered' | 'padded';
+export type ContainerPadding = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export interface ContainerBaseProps {
+  children: React.ReactNode;
+  /**
+   * The widest the content column gets, as one of MUI's breakpoints — see
+   * `CONTAINER_MAX_WIDTHS`. `false` removes the limit. Any other string is
+   * read as `lg`, as the web has always done.
+   */
+  maxWidth?: ContainerMaxWidth | string;
+  /** `fluid` drops the limit, `centered` centres the content in the viewport, `padded` is a main content area. */
+  variant?: ContainerVariant;
+  /** The inset on every side, on the spacing scale — see `CONTAINER_PADDING_UNITS`. */
+  padding?: ContainerPadding;
+  /** Tighten the inset under MUI's `sm` breakpoint (600px). */
+  responsive?: boolean;
+  testID?: string;
+  dataTestId?: string;
+}

package/src/components/layout/Container/Container.md

@@ -100,6 +100,20 @@ Adds extra vertical padding, useful for main content areas.
 - **lg**: 32px padding
 - **xl**: 48px padding
 
+## React Native
+
+The same import renders natively (`@12-apps/ui/layout/Container` resolves to
+`Container.native.tsx` under Metro): a `View` that is `width: 100%` between
+auto margins, limited to the same MUI breakpoint widths
+(`CONTAINER_MAX_WIDTHS`), inset from the same spacing units
+(`CONTAINER_PADDING_UNITS`). The `responsive` media query becomes a
+`useWindowDimensions().width < 600` test and `centered`'s `100vh` the window
+height. `testID`, `dataTestId` and `data-testid` all name the element;
+`container` is the default. Both renderers read one `containerPaddingUnits`,
+which paints what the web paints today — including two quirks recorded in
+`NATIVE-NOTES.md` (`padding="none"` and `variant="padded"` both paint the
+default inset). See [NATIVE.md](../../../../NATIVE.md).
+
 ## Accessibility
 
 - The component maintains semantic HTML structure

package/src/components/layout/Container/Container.metrics.ts

@@ -0,0 +1,87 @@
+import type { ContainerMaxWidth, ContainerPadding, ContainerVariant } from './Container.base';
+
+/**
+ * THE NUMBERS BOTH `Container` RENDERERS DRAW WITH.
+ *
+ * `Container.tsx` used to hold these as `theme.spacing(…)` calls and MUI's
+ * breakpoint names inside the component; the native renderer has no MUI
+ * breakpoints to name, so the values live here in SPACING UNITS and px, and
+ * each renderer multiplies the units out through its own `theme.spacing`.
+ */
+export type ContainerMaxWidthKey = Exclude<ContainerMaxWidth, false>;
+
+/**
+ * MUI's default breakpoints, which its `Container` reads as `max-width`
+ * (`xs` is `Math.max(values.xs, 444)`). MUI applies each under
+ * `min-width: <breakpoint>`, but below it the column is `width: 100%` and
+ * narrower anyway, so a plain `maxWidth` paints the same.
+ */
+export const CONTAINER_MAX_WIDTHS: Record<ContainerMaxWidthKey, number> = {
+  xs: 444,
+  sm: 600,
+  md: 900,
+  lg: 1200,
+  xl: 1536,
+};
+
+export const CONTAINER_DEFAULT_MAX_WIDTH: ContainerMaxWidthKey = 'lg';
+/** The `centered` variant reads at `md`, whatever `maxWidth` says. */
+export const CONTAINER_CENTERED_MAX_WIDTH: ContainerMaxWidthKey = 'md';
+
+export const CONTAINER_PADDING_UNITS: Record<ContainerPadding, number> = {
+  none: 0,
+  xs: 1,
+  sm: 2,
+  md: 3,
+  lg: 4,
+  xl: 6,
+};
+
+export const CONTAINER_DEFAULT_PADDING: ContainerPadding = 'md';
+
+/** What `variant="padded"` declares above and below, in spacing units. */
+export const CONTAINER_PADDED_VERTICAL_UNITS = 8;
+
+/** Under {@link CONTAINER_COMPACT_BELOW}, a `responsive` container tightens to this. */
+export const CONTAINER_COMPACT_PADDING_UNITS = 2;
+
+/** MUI's `sm` breakpoint: `theme.breakpoints.down('sm')` is `max-width: 599.95px`. */
+export const CONTAINER_COMPACT_BELOW = 600;
+
+const isMaxWidthKey = (value: string): value is ContainerMaxWidthKey => value in CONTAINER_MAX_WIDTHS;
+
+/**
+ * The breakpoint the column is limited to, or `false` for none. `fluid` drops
+ * the limit, `centered` fixes it at `md`, and a string outside the vocabulary
+ * reads as the default — the rules `Container.tsx` has always applied.
+ */
+export function resolveContainerMaxWidth(
+  variant: ContainerVariant,
+  maxWidth: ContainerMaxWidth | string,
+): ContainerMaxWidthKey | false {
+  if (variant === 'fluid') return false;
+  if (variant === 'centered') return CONTAINER_CENTERED_MAX_WIDTH;
+  if (typeof maxWidth === 'string' && isMaxWidthKey(maxWidth)) return maxWidth;
+  return maxWidth === false ? false : CONTAINER_DEFAULT_MAX_WIDTH;
+}
+
+/**
+ * The inset every side of the container is PAINTED with, in spacing units.
+ *
+ * This is the web's painted result, not its declared intent, and two of its
+ * rules are worth knowing before reaching for them:
+ *
+ * - `padding="none"` paints the default. The web reads its map with `||`, so
+ *   `none`'s 0 falls through to `md`.
+ * - `variant="padded"` paints the same inset as `default`. The web declares its
+ *   {@link CONTAINER_PADDED_VERTICAL_UNITS} above and below BEFORE the
+ *   `padding` shorthand, which therefore overrides them.
+ *
+ * Both renderers read this one function so they agree today; either fix is a
+ * change to the web's emitted CSS and to this function, made together.
+ */
+export function containerPaddingUnits(padding: ContainerPadding | string, compact: boolean): number {
+  if (compact) return CONTAINER_COMPACT_PADDING_UNITS;
+  const units = (CONTAINER_PADDING_UNITS as Record<string, number | undefined>)[padding];
+  return units || CONTAINER_PADDING_UNITS[CONTAINER_DEFAULT_PADDING];
+}

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

@@ -0,0 +1,71 @@
+import * as React from 'react';
+import { View, useWindowDimensions, type ViewStyle } from 'react-native';
+
+import {
+  CONTAINER_COMPACT_BELOW,
+  CONTAINER_MAX_WIDTHS,
+  containerPaddingUnits,
+  resolveContainerMaxWidth,
+} from './Container.metrics';
+import type { ContainerMaxWidth, ContainerPadding, ContainerProps, ContainerVariant } from './Container.types.native';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import type { UiTheme } from '../../../tokens/theme';
+
+export interface ContainerStyleArgs {
+  variant: ContainerVariant;
+  maxWidth: ContainerMaxWidth | string;
+  padding: ContainerPadding;
+  responsive: boolean;
+  /** The window, for the two things CSS answers with a media query and `100vh`. */
+  window: { width: number; height: number };
+}
+
+/**
+ * The style MUI's `Container` plus the web `sx` paint, in absolute numbers.
+ *
+ * `width: 100%` between auto margins is MUI's own centring rule; `maxWidth` is
+ * the breakpoint the web applies under `min-width` (below it the column is
+ * narrower anyway); the `responsive` media query becomes a window-width test;
+ * `centered`'s `100vh` becomes the window height. `padded` and `padding="none"`
+ * paint what the web paints — see `containerPaddingUnits`.
+ */
+export function containerStyle(theme: UiTheme, a: ContainerStyleArgs): ViewStyle {
+  const compact = a.responsive && a.window.width < CONTAINER_COMPACT_BELOW;
+  const limit = resolveContainerMaxWidth(a.variant, a.maxWidth);
+  return {
+    width: '100%',
+    marginLeft: 'auto',
+    marginRight: 'auto',
+    maxWidth: limit === false ? undefined : CONTAINER_MAX_WIDTHS[limit],
+    padding: theme.spacing(containerPaddingUnits(a.padding, compact)),
+    ...(a.variant === 'centered'
+      ? { alignItems: 'center', justifyContent: 'center', minHeight: a.window.height }
+      : null),
+  };
+}
+
+/** The native `Container`: a `View` sized by the same rules MUI's `Container` and the web `sx` apply. */
+export const Container = React.forwardRef<View, ContainerProps>(
+  ({ children, maxWidth = 'lg', variant = 'default', padding = 'md', responsive = true, style, ...others }, ref) => {
+    const theme = useUiTheme();
+    const window = useWindowDimensions();
+    const resolved = React.useMemo(
+      () => containerStyle(theme, { variant, maxWidth, padding, responsive, window }),
+      [theme, variant, maxWidth, padding, responsive, window],
+    );
+
+    return (
+      <View
+        ref={ref}
+        style={[resolved, style]}
+        testID={resolveTestId(others, 'container')}
+        {...withoutTestIdProps(others)}
+      >
+        {children}
+      </View>
+    );
+  },
+);
+
+Container.displayName = 'Container';

package/src/components/layout/Container/Container.tsx

@@ -3,7 +3,14 @@ import { useTheme } from '@mui/material/styles/index.js';
 import type { SxProps, Theme } from '@mui/material/styles/index.js';
 import React from 'react';
 
+import {
+  CONTAINER_COMPACT_PADDING_UNITS,
+  CONTAINER_PADDED_VERTICAL_UNITS,
+  containerPaddingUnits,
+  resolveContainerMaxWidth,
+} from './Container.metrics';
 import type { ContainerProps } from './Container.types';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
 
 export const Container: React.FC<ContainerProps> = ({
   children,
@@ -11,34 +18,18 @@ export const Container: React.FC<ContainerProps> = ({
   variant = 'default',
   padding = 'md',
   responsive = true,
-  dataTestId,
   sx,
-  ...props
+  ...others
 }) => {
   const theme = useTheme();
+  // `testID` and `dataTestId` are the shared contract's spellings; the DOM
+  // wants `data-testid`, and must not see the other two as attributes.
+  const testId = resolveTestId(others, 'container');
+  const props = withoutTestIdProps(others);
 
-  const getPadding = () => {
-    const paddingMap = {
-      none: 0,
-      xs: theme.spacing(1),
-      sm: theme.spacing(2),
-      md: theme.spacing(3),
-      lg: theme.spacing(4),
-      xl: theme.spacing(6),
-    };
-    return paddingMap[padding] || theme.spacing(3);
-  };
-
-  const getMaxWidth = (): 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false => {
-    if (variant === 'fluid') return false;
-    if (variant === 'centered') return 'md';
-    if (typeof maxWidth === 'string' && ['xs', 'sm', 'md', 'lg', 'xl'].includes(maxWidth)) {
-      return maxWidth as 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-    }
-    if (maxWidth === false) return false;
-    return 'lg'; // default fallback
-  };
-
+  // From the shared metrics, not tables of our own: the native `Container`
+  // reads the same units and the same max-width rule, so the two renderers
+  // cannot disagree on an inset or a column width.
   const containerStyles: SxProps<Theme> = {
     ...(variant === 'centered' && {
       display: 'flex',
@@ -48,13 +39,13 @@ export const Container: React.FC<ContainerProps> = ({
       minHeight: '100vh',
     }),
     ...(variant === 'padded' && {
-      paddingTop: theme.spacing(8),
-      paddingBottom: theme.spacing(8),
+      paddingTop: theme.spacing(CONTAINER_PADDED_VERTICAL_UNITS),
+      paddingBottom: theme.spacing(CONTAINER_PADDED_VERTICAL_UNITS),
     }),
-    padding: getPadding(),
+    padding: theme.spacing(containerPaddingUnits(padding, false)),
     ...(responsive && {
       [theme.breakpoints.down('sm')]: {
-        padding: theme.spacing(2),
+        padding: theme.spacing(CONTAINER_COMPACT_PADDING_UNITS),
       },
     }),
     ...(sx || {}),
@@ -62,9 +53,9 @@ export const Container: React.FC<ContainerProps> = ({
 
   return (
     <MuiContainer
-      maxWidth={getMaxWidth()}
+      maxWidth={resolveContainerMaxWidth(variant, maxWidth)}
       sx={containerStyles}
-      data-testid={dataTestId || 'container'}
+      data-testid={testId}
       {...props}
     >
       {children}

package/src/components/layout/Container/Container.types.native.ts

@@ -0,0 +1,11 @@
+import type { StyleProp, ViewProps, ViewStyle } from 'react-native';
+
+import type { ContainerBaseProps } from './Container.base';
+
+export type { ContainerBaseProps, ContainerMaxWidth, ContainerPadding, ContainerVariant } from './Container.base';
+
+/** The native `Container`: the shared contract, plus a `View`'s own props where they do not overlap. */
+export type ContainerProps = ContainerBaseProps &
+  Omit<ViewProps, keyof ContainerBaseProps | 'style'> & {
+    style?: StyleProp<ViewStyle>;
+  };

package/src/components/layout/Container/Container.types.ts

@@ -1,11 +1,10 @@
 import type { ContainerProps as MuiContainerProps } from '@mui/material/Container/index.js';
-import type { ReactNode } from 'react';
 
-export interface ContainerProps extends Omit<MuiContainerProps, 'maxWidth'> {
-  children: ReactNode;
-  maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false | string;
-  variant?: 'default' | 'fluid' | 'centered' | 'padded';
-  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-  responsive?: boolean;
-  dataTestId?: string;
-}
+import type { ContainerBaseProps } from './Container.base';
+
+export type { ContainerBaseProps, ContainerMaxWidth, ContainerPadding, ContainerVariant } from './Container.base';
+
+/** The web `Container`: the shared contract, plus whatever MUI's `Container` accepts that it does not already name. */
+export interface ContainerProps
+  extends ContainerBaseProps,
+    Omit<MuiContainerProps, keyof ContainerBaseProps> {}

package/src/components/layout/Container/NATIVE-NOTES.md

@@ -0,0 +1,5 @@
+# Container on React Native — known gaps
+
+- `variant="padded"` adds no vertical padding on either renderer: the web declares its 64px above and below BEFORE the `padding` shorthand, which overrides them, and native paints the same insets so the two agree. The fix is a web change (`Container.tsx` order) plus `containerPaddingUnits`, made together.
+- `padding="none"` paints the `md` inset on either renderer: the web reads its map with `||`, so `none`'s 0 falls through to the default. Same one-place fix.
+- `responsive` reads `useWindowDimensions().width < 600` in place of MUI's `sm` media query, and `centered` reads the window height in place of `100vh`; both track the window, as CSS would, but a container inside a narrower parent still measures the window, not the parent.

package/src/components/layout/Container/index.native.ts

@@ -0,0 +1,8 @@
+export { Container, containerStyle } from './Container.native';
+export type {
+  ContainerBaseProps,
+  ContainerMaxWidth,
+  ContainerPadding,
+  ContainerProps,
+  ContainerVariant,
+} from './Container.types.native';

package/src/components/layout/Container/index.ts

@@ -1,2 +1,8 @@
 export { Container } from './Container';
-export type { ContainerProps } from './Container.types';
+export type {
+  ContainerBaseProps,
+  ContainerMaxWidth,
+  ContainerPadding,
+  ContainerProps,
+  ContainerVariant,
+} from './Container.types';