@12-apps/ui 6.20.0 → 6.22.0

package/src/components/layout/Card/CardParts.native.tsx

@@ -0,0 +1,262 @@
+import * as React from 'react';
+import {
+  Image,
+  StyleSheet,
+  Text as RNText,
+  View,
+  type DimensionValue,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native';
+
+import {
+  CARD_ACTIONS,
+  CARD_CONTENT_PADDING_UNITS,
+  CARD_HEADER,
+  CARD_HEADER_CHILDREN_PADDING_UNITS,
+  CARD_MEDIA_HEIGHT,
+} from './Card.metrics';
+import type {
+  CardActionsAlignment,
+  CardActionsProps,
+  CardContentProps,
+  CardHeaderProps,
+  CardMediaProps,
+} from './Card.types.native';
+import { childTestId, resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { renderTextChildren } from '../../../platform/text-children';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import { muiTypeStyle } from '../../../tokens/mui-type';
+import type { UiTheme } from '../../../tokens/theme';
+
+/**
+ * THE FOUR SLOTS A CARD IS BUILT OUT OF, ON REACT NATIVE.
+ *
+ * Each one is a `View` carrying the padding MUI's own `CardHeader`,
+ * `CardContent`, `CardActions` and `CardMedia` declare in px — the web half
+ * overrides only `padding` and `justify-content`, so the rest of the numbers
+ * come from MUI and are restated in `Card.metrics.ts` rather than re-invented.
+ */
+
+/**
+ * THE INK A CARD PUBLISHES TO ITS SLOTS.
+ *
+ * `Card.styles.ts` puts `color: primary.contrastText` on the gradient card
+ * ITSELF and lets CSS inheritance carry it into the header and the body. React
+ * Native inherits nothing across views, so the card publishes its ink here and
+ * every slot reads it — which is the difference between a legible gradient card
+ * and near-black text on indigo.
+ *
+ * `null` is "no card above me": a slot rendered on its own falls back to the
+ * body ink, exactly as it would on the web.
+ */
+export const CardInkContext = React.createContext<string | null>(null);
+
+/** The body text of a slot, in MUI's `body1`, so a bare string is not unstyled. */
+const slotTextStyle = (theme: UiTheme, ink: string | null): TextStyle => ({
+  ...muiTypeStyle(theme, 'body1'),
+  color: ink ?? theme.palette.text.primary,
+});
+
+/** MUI's header title: `h5`, or `body2` when an avatar shares the row. */
+export const cardTitleStyle = (
+  theme: UiTheme,
+  hasAvatar: boolean,
+  ink: string | null = null,
+): TextStyle => ({
+  ...muiTypeStyle(theme, hasAvatar ? 'body2' : 'h5'),
+  color: ink ?? theme.palette.text.primary,
+});
+
+/**
+ * MUI's header subheader: `body1` (or `body2` beside an avatar), in the muted
+ * ink — which does NOT follow the card's own ink, because MUI's `CardHeader`
+ * pins the subheader to `textSecondary` explicitly rather than inheriting.
+ */
+export const cardSubtitleStyle = (theme: UiTheme, hasAvatar: boolean): TextStyle => ({
+  ...muiTypeStyle(theme, hasAvatar ? 'body2' : 'body1'),
+  color: theme.palette.text.secondary,
+});
+
+export function CardHeader({
+  title,
+  subtitle,
+  action,
+  avatar,
+  children,
+  ...others
+}: CardHeaderProps): React.JSX.Element {
+  const theme = useUiTheme();
+  const ink = React.useContext(CardInkContext);
+  const testID = resolveTestId(others, 'card-header');
+  const { style, ...viewProps } = withoutTestIdProps(others);
+
+  if (children) {
+    return (
+      <View
+        testID={testID}
+        style={[{ padding: theme.spacing(CARD_HEADER_CHILDREN_PADDING_UNITS) }, style]}
+        {...viewProps}
+      >
+        {renderTextChildren(children, slotTextStyle(theme, ink))}
+      </View>
+    );
+  }
+
+  const hasAvatar = avatar != null;
+  return (
+    <View testID={testID} style={[styles.header, style]} {...viewProps}>
+      {hasAvatar ? <View style={styles.headerAvatar}>{avatar}</View> : null}
+      <View style={styles.headerContent}>
+        {title != null ? (
+          <RNText testID={childTestId(others, 'title', 'card')} style={cardTitleStyle(theme, hasAvatar, ink)}>
+            {title}
+          </RNText>
+        ) : null}
+        {subtitle != null ? (
+          <RNText
+            testID={childTestId(others, 'subtitle', 'card')}
+            style={cardSubtitleStyle(theme, hasAvatar)}
+          >
+            {subtitle}
+          </RNText>
+        ) : null}
+      </View>
+      {action != null ? <View style={styles.headerAction}>{action}</View> : null}
+    </View>
+  );
+}
+
+CardHeader.displayName = 'CardHeader';
+
+export function CardContent({
+  children,
+  dense = false,
+  ...others
+}: CardContentProps): React.JSX.Element {
+  const theme = useUiTheme();
+  const ink = React.useContext(CardInkContext);
+  const testID = resolveTestId(others, 'card-content');
+  const { style, ...viewProps } = withoutTestIdProps(others);
+  const padding = theme.spacing(
+    dense ? CARD_CONTENT_PADDING_UNITS.dense : CARD_CONTENT_PADDING_UNITS.normal,
+  );
+
+  return (
+    <View testID={testID} style={[{ padding }, style]} {...viewProps}>
+      {renderTextChildren(children, slotTextStyle(theme, ink))}
+    </View>
+  );
+}
+
+CardContent.displayName = 'CardContent';
+
+const JUSTIFY: Record<CardActionsAlignment, NonNullable<ViewStyle['justifyContent']>> = {
+  left: 'flex-start',
+  center: 'center',
+  right: 'flex-end',
+  'space-between': 'space-between',
+};
+
+export function CardActions({
+  children,
+  disableSpacing = false,
+  alignment = 'left',
+  ...others
+}: CardActionsProps): React.JSX.Element {
+  const theme = useUiTheme();
+  const ink = React.useContext(CardInkContext);
+  const testID = resolveTestId(others, 'card-actions');
+  const { style, ...viewProps } = withoutTestIdProps(others);
+
+  return (
+    <View
+      testID={testID}
+      style={[
+        styles.actions,
+        { justifyContent: JUSTIFY[alignment], gap: disableSpacing ? undefined : CARD_ACTIONS.gap },
+        style,
+      ]}
+      {...viewProps}
+    >
+      {renderTextChildren(children, slotTextStyle(theme, ink))}
+    </View>
+  );
+}
+
+CardActions.displayName = 'CardActions';
+
+/**
+ * `height` accepts the web's spellings: a number, a numeric string (`"200"`, as
+ * an `<img height>` takes) or a percentage.
+ */
+export function mediaHeight(height: number | string): DimensionValue {
+  if (typeof height === 'number') return height;
+  const parsed = Number(height);
+  return Number.isFinite(parsed) ? parsed : (height as DimensionValue);
+}
+
+export function CardMedia({
+  image,
+  title,
+  height = CARD_MEDIA_HEIGHT,
+  children,
+  ...others
+}: CardMediaProps): React.JSX.Element {
+  const testID = resolveTestId(others, 'card-media');
+  const { style, ...viewProps } = withoutTestIdProps(others);
+
+  return (
+    <View
+      testID={testID}
+      style={[{ height: mediaHeight(height), width: '100%', overflow: 'hidden' }, style]}
+      {...viewProps}
+    >
+      {image != null ? (
+        <Image
+          source={{ uri: image }}
+          accessibilityLabel={title}
+          resizeMode="cover"
+          style={StyleSheet.absoluteFill}
+        />
+      ) : null}
+      {children}
+    </View>
+  );
+}
+
+CardMedia.displayName = 'CardMedia';
+
+const styles = StyleSheet.create({
+  header: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    padding: CARD_HEADER.padding,
+  },
+  headerAvatar: {
+    flexGrow: 0,
+    flexShrink: 0,
+    flexBasis: 'auto',
+    marginRight: CARD_HEADER.avatarGap,
+  },
+  headerContent: {
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: 'auto',
+    minWidth: 0,
+  },
+  headerAction: {
+    flexGrow: 0,
+    flexShrink: 0,
+    flexBasis: 'auto',
+    alignSelf: 'flex-start',
+    marginTop: CARD_HEADER.action.marginTop,
+    marginRight: CARD_HEADER.action.marginRight,
+    marginBottom: CARD_HEADER.action.marginBottom,
+  },
+  actions: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    padding: CARD_ACTIONS.padding,
+  },
+});

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

@@ -0,0 +1,15 @@
+# Card on React Native
+
+Known rendering gaps, one bullet each; `pnpm native:ledger` reads them.
+
+- `glass` paints its 0.1 paper wash and primary hairline without the 20px backdrop blur — React Native has no backdrop filter.
+- `gradient` paints the gradient's first stop flat (`primary.main`, `primary.dark` under a press) — React Native core has no gradient fill.
+- Hover has no touch equivalent: what a variant changes on `:hover` (border colour, wash, shadow) is applied while PRESSED, and the 2px lift is not — the web itself returns an interactive card to `translateY(0)` under the pointer, which is where a finger leaves it.
+- The pulse ring is an expanding hollow border rather than a `box-shadow` spread behind the paper: React Native cannot paint a child behind its parent's own background, so the ring grows outward from the card's edge instead of from under it, and its corner radius stays the card's rather than widening with the ring.
+- A `glow`ing card stops clipping its children to its corners: a view's own shadow is clipped by its own overflow on a device, so the halo the caller asked for would not paint. The web keeps `overflow: hidden` there and shows both.
+- `elevated` restates MUI's `shadows[1]`, the elevation every card inherits from `Paper` on the web, because React Native has no Paper to inherit it from; the variant's own `elevation: 4`/`8` are not CSS properties and paint nothing on either renderer.
+- The loading spinner is the platform's `ActivityIndicator` at MUI's 40px `CircularProgress` diameter, not MUI's arc; on iOS the built-in `large` stands in for the exact size.
+- `CardMedia` draws its image with `resizeMode="cover"` inside the sized box. MUI's `component` and the DOM `title` attribute are web-only — a device names the image through `accessibilityLabel`.
+- `CardActions` spaces its children with `gap` where MUI uses `& > :not(style) ~ :not(style) { margin-left: 8px }`: the same 8px, applied by the container rather than by a sibling selector.
+- A `gradient` card's `primary.contrastText` reaches its own text children and the house slots (`CardHeader`'s title, `CardContent`, `CardActions`) through a context; the web puts one `color` on the card and lets CSS inherit it into everything below. So a consumer's own `Text` nested inside a gradient card keeps the body ink unless it reads that colour itself. The header's SUBTITLE stays `text.secondary` on both, because MUI's `CardHeader` pins the subheader to `textSecondary` rather than inheriting.
+- Title, subtitle and raw text children are set in MUI's default `h5`/`body1`/`body2` numbers; a host that re-themes MUI's typography variants moves the web only.

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

@@ -0,0 +1,18 @@
+export { Card } from './Card.native';
+export { CardActions, CardContent, CardHeader, CardMedia } from './CardParts.native';
+export type {
+  CardActionsAlignment,
+  CardActionsBaseProps,
+  CardActionsProps,
+  CardBaseProps,
+  CardBorderRadius,
+  CardContentBaseProps,
+  CardContentProps,
+  CardEntranceAnimation,
+  CardHeaderBaseProps,
+  CardHeaderProps,
+  CardMediaBaseProps,
+  CardMediaProps,
+  CardProps,
+  CardVariant,
+} from './Card.types.native';

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

@@ -1,8 +1,17 @@
 export { Card, CardActions, CardContent, CardHeader, CardMedia } from './Card';
 export type {
+  CardActionsAlignment,
+  CardActionsBaseProps,
   CardActionsProps,
+  CardBaseProps,
+  CardBorderRadius,
+  CardContentBaseProps,
   CardContentProps,
+  CardEntranceAnimation,
+  CardHeaderBaseProps,
   CardHeaderProps,
+  CardMediaBaseProps,
   CardMediaProps,
   CardProps,
+  CardVariant,
 } from './Card.types';

package/src/icons/glyphs.json

@@ -2,11 +2,14 @@
   "Add",
   "ArrowBack",
   "ArrowDownward",
+  "ArrowDropDown",
   "ArrowForward",
   "ArrowUpward",
   "BrokenImage",
   "Cancel",
   "Check",
+  "CheckBox",
+  "CheckBoxOutlineBlank",
   "CheckCircle",
   "ChevronLeft",
   "ChevronRight",
@@ -19,6 +22,7 @@
   "ExpandLess",
   "ExpandMore",
   "FilterList",
+  "IndeterminateCheckBox",
   "Info",
   "InfoOutlined",
   "KeyboardArrowDown",

package/src/icons/paths.generated.ts

@@ -10,11 +10,14 @@ export const ICON_PATHS = {
   Add: ["M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6z"],
   ArrowBack: ["M20 11H7.83l5.59-5.59L12 4l-8 8 8 8 1.41-1.41L7.83 13H20z"],
   ArrowDownward: ["m20 12-1.41-1.41L13 16.17V4h-2v12.17l-5.58-5.59L4 12l8 8z"],
+  ArrowDropDown: ["m7 10 5 5 5-5z"],
   ArrowForward: ["m12 4-1.41 1.41L16.17 11H4v2h12.17l-5.58 5.59L12 20l8-8z"],
   ArrowUpward: ["m4 12 1.41 1.41L11 7.83V20h2V7.83l5.58 5.59L20 12l-8-8z"],
   BrokenImage: ["M21 5v6.59l-3-3.01-4 4.01-4-4-4 4-3-3.01V5c0-1.1.9-2 2-2h14c1.1 0 2 .9 2 2m-3 6.42 3 3.01V19c0 1.1-.9 2-2 2H5c-1.1 0-2-.9-2-2v-6.58l3 2.99 4-4 4 4z"],
   Cancel: ["M12 2C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2m5 13.59L15.59 17 12 13.41 8.41 17 7 15.59 10.59 12 7 8.41 8.41 7 12 10.59 15.59 7 17 8.41 13.41 12z"],
   Check: ["M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"],
+  CheckBox: ["M19 3H5c-1.11 0-2 .9-2 2v14c0 1.1.89 2 2 2h14c1.11 0 2-.9 2-2V5c0-1.1-.89-2-2-2m-9 14-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8z"],
+  CheckBoxOutlineBlank: ["M19 5v14H5V5zm0-2H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2"],
   CheckCircle: ["M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m-2 15-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8z"],
   ChevronLeft: ["M15.41 7.41 14 6l-6 6 6 6 1.41-1.41L10.83 12z"],
   ChevronRight: ["M10 6 8.59 7.41 13.17 12l-4.58 4.59L10 18l6-6z"],
@@ -27,6 +30,7 @@ export const ICON_PATHS = {
   ExpandLess: ["m12 8-6 6 1.41 1.41L12 10.83l4.59 4.58L18 14z"],
   ExpandMore: ["M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z"],
   FilterList: ["M10 18h4v-2h-4zM3 6v2h18V6zm3 7h12v-2H6z"],
+  IndeterminateCheckBox: ["M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2m-2 10H7v-2h10z"],
   Info: ["M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m1 15h-2v-6h2zm0-8h-2V7h2z"],
   InfoOutlined: ["M11 7h2v2h-2zm0 4h2v6h-2zm1-9C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8"],
   KeyboardArrowDown: ["M7.41 8.59 12 13.17l4.59-4.58L18 10l-6 6-6-6z"],

package/src/platform/aria.ts

@@ -1,5 +1,5 @@
 /**
- * ARIA ATTRIBUTES REACT NATIVE DOES NOT DECLARE.
+ * WEB ATTRIBUTES REACT NATIVE DOES NOT DECLARE.
  *
  * React Native's `ViewProps` (0.83) type a dozen `aria-*` props and stop:
  * `aria-level`, `aria-atomic` and `aria-describedby` are not among them.
@@ -13,6 +13,20 @@ export interface WebAria {
   'aria-level'?: 1 | 2 | 3 | 4 | 5 | 6;
   'aria-atomic'?: 'true' | 'false';
   'aria-describedby'?: string;
+  /**
+   * A field's validity and whether it must be filled. React Native's
+   * `accessibilityState` has neither — its five flags are disabled, selected,
+   * checked, busy and expanded — so these are web-only, and a device reads the
+   * error text instead. react-native-web forwards both.
+   */
+  'aria-invalid'?: boolean;
+  'aria-required'?: boolean;
+  /**
+   * What a control pops open. React Native has `aria-expanded` and no
+   * `aria-haspopup`, so a `combobox` needs this one from here to say the thing
+   * it expands is a listbox — which is what the web's own trigger carries.
+   */
+  'aria-haspopup'?: 'listbox' | 'menu' | 'dialog' | 'true';
 }
 
 /**
@@ -30,3 +44,60 @@ export function webAria(attrs: WebAria): object {
   const { 'aria-atomic': atomic, ...rest } = attrs;
   return atomic === undefined ? rest : { ...rest, accessibilityAtomic: atomic };
 }
+
+/**
+ * `disabled` for a react-native-web form control.
+ *
+ * React Native's `TextInput` has `editable` and no `disabled`, because a
+ * device has no disabled state to speak of — an uneditable field simply does
+ * not take the keyboard. The DOM does: only a real `disabled` attribute takes
+ * an `<input>` out of the tab order, and it is what `toBeDisabled()` reads. So
+ * a native field spreads this ALONGSIDE `editable={false}` and
+ * `aria-disabled`: react-native-web puts the attribute on the input, and a
+ * device ignores a prop it does not know.
+ */
+export function webDisabled(disabled: boolean): object {
+  return disabled ? { disabled: true } : {};
+}
+
+/**
+ * `onClick` for a react-native-web element whose React Native twin has no
+ * click of its own.
+ *
+ * react-native-web's `TextInput` forwards `onClick` to the DOM input and drops
+ * `onPressIn`; a device does the opposite. A field that must answer a press on
+ * both renderers spreads this ALONGSIDE `onPressIn`, and exactly one of the two
+ * fires on each side — never both.
+ */
+export function webClick<E>(handler: ((event: E) => void) | undefined): object {
+  return handler === undefined ? {} : { onClick: handler };
+}
+
+/**
+ * A `role` React Native's own union does not carry.
+ *
+ * `Role` (0.83) stops at `list` and `menu`: `listbox`, the role a dropdown's
+ * option list owes a screen reader, is not in it. react-native-web forwards
+ * whatever string it is given, and a device ignores a role it does not know —
+ * the same trade `webAria` makes for the attributes below it.
+ */
+export function webRole(role: string): object {
+  return { role };
+}
+
+/** The half of a DOM keyboard event a component needs, without the DOM lib. */
+export interface WebKeyEvent {
+  key: string;
+}
+
+/**
+ * `onKeyDown` for a react-native-web element.
+ *
+ * React Native has no key events on a `View` — a phone has no keyboard to
+ * press Escape on — so nothing here is typed by react-native and nothing here
+ * fires on a device. react-native-web forwards it to the DOM, which is what
+ * lets a native dropdown still answer Escape and the arrow keys in a browser.
+ */
+export function webKeyDown(handler: (event: WebKeyEvent) => void): object {
+  return { onKeyDown: handler };
+}

package/src/platform/pulse-ring.native.tsx

@@ -0,0 +1,82 @@
+import * as React from 'react';
+import { Animated, Easing } from 'react-native';
+
+/**
+ * THE `::after` PULSE, AS A REACT NATIVE VIEW.
+ *
+ * `Card` and `Dialog` pulse the same way on the web: an `::after` that fills
+ * the element, carries `box-shadow: 0 0 0 <spread>px currentColor` and animates
+ * that spread out and back while fading, once every two seconds, from BEHIND
+ * the element (`z-index: -1`). Those two read this; `Button.native.tsx` still
+ * carries its own `Pulse`, a filled overlay that scales and fades rather than a
+ * ring, and folding it onto this is a `form/Button` change.
+ *
+ * React Native cannot paint a child behind its parent's own background, so a
+ * filled overlay would wash the surface instead of haloing it. This draws a
+ * HOLLOW ring instead: the view is inset by the current spread and carries a
+ * border of exactly that width, so the band it paints is precisely the region
+ * from the surface's edge to `spread` outside it — the same band the box-shadow
+ * spread covers, and nothing over the surface itself.
+ *
+ * Layout props cannot run on the native driver, so this animates on the JS one.
+ */
+export interface PulseRingProps {
+  color: string;
+  /** The surface's own corner radius, which the ring follows. */
+  radius: number | string;
+  /** How far out of the edge the ring grows, in px. */
+  spread: number;
+  durationMs: number;
+  /** The fraction of the cycle the ring is still visible for. */
+  fadeAt: number;
+  /** The ring's opacity at the start of a cycle. */
+  opacity: number;
+  testID: string;
+}
+
+export function PulseRing({
+  color,
+  radius,
+  spread,
+  durationMs,
+  fadeAt,
+  opacity,
+  testID,
+}: PulseRingProps): React.JSX.Element {
+  const progress = React.useRef(new Animated.Value(0)).current;
+
+  React.useEffect(() => {
+    const loop = Animated.loop(
+      Animated.timing(progress, {
+        toValue: 1,
+        duration: durationMs,
+        easing: Easing.linear,
+        useNativeDriver: false,
+      }),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [durationMs, progress]);
+
+  const grow = progress.interpolate({ inputRange: [0, fadeAt, 1], outputRange: [0, spread, 0] });
+  const inset = Animated.multiply(grow, -1);
+
+  return (
+    <Animated.View
+      testID={testID}
+      aria-hidden
+      style={{
+        position: 'absolute',
+        pointerEvents: 'none',
+        top: inset,
+        left: inset,
+        right: inset,
+        bottom: inset,
+        borderWidth: grow,
+        borderColor: color,
+        borderRadius: radius,
+        opacity: progress.interpolate({ inputRange: [0, fadeAt, 1], outputRange: [opacity, 0, 0] }),
+      }}
+    />
+  );
+}

package/src/platform/test-id.ts

@@ -18,6 +18,19 @@ export function resolveTestId(props: TestIdProps, fallback?: string): string | u
   return props.testID ?? props.dataTestId ?? props['data-testid'] ?? fallback;
 }
 
+/**
+ * The id under whichever of the three spellings the caller used, together with
+ * the props stripped of all three — so a web component can put `data-testid`
+ * where the DOM wants it without React seeing `testID` or `dataTestId` and
+ * warning that it does not recognise them.
+ */
+export function splitTestId<T extends TestIdProps>(
+  props: T,
+  fallback?: string,
+): { testId: string | undefined; rest: Omit<T, keyof TestIdProps> } {
+  return { testId: resolveTestId(props, fallback), rest: withoutTestIdProps(props) };
+}
+
 /** `${id}-${suffix}` for a sub-element, or `${fallback}-${suffix}` when unnamed. */
 export function childTestId(
   props: TestIdProps,
@@ -32,3 +45,20 @@ export function withoutTestIdProps<P extends TestIdProps>(props: P): Omit<P, key
   const { testID: _testID, dataTestId: _dataTestId, 'data-testid': _dataTestid, ...rest } = props;
   return rest;
 }
+
+/**
+ * A SLOT's own test id, where a raw id means "this element" and `dataTestId`
+ * means "the surface I belong to".
+ *
+ * `Dialog` names its parts by derivation — `d` gives `d-title`, `d-content`,
+ * `d-actions` — and a slot receives the DIALOG's id in `dataTestId` to derive
+ * from. A raw `data-testid` (or React Native's `testID`) is something else: it
+ * is the id the caller wants ON THIS ELEMENT, which is how the shared stories
+ * address a `DialogContent`, so it is taken verbatim and no suffix is added.
+ *
+ * Both renderers read this one function, which is the only way the web and the
+ * native slot can agree about what `<DialogContent data-testid="x">` is called.
+ */
+export function slotTestId(props: TestIdProps, suffix: string, fallback: string): string {
+  return props.testID ?? props['data-testid'] ?? childTestId(props, suffix, fallback);
+}

package/src/tokens/field-edge.core.ts

@@ -0,0 +1,87 @@
+import {
+  darken,
+  decomposeColor,
+  getContrastRatio,
+  getLuminance,
+  hslToRgb,
+  lighten,
+  recomposeColor,
+} from './color';
+
+/**
+ * THE FIELD EDGE, WITH NO RENDERER BEHIND IT.
+ *
+ * The argument for why an outlined control cannot draw its resting boundary
+ * from `alpha(theme.palette.divider, 0.23)` is in `./field-edge.ts`, next to
+ * the MUI-typed `fieldEdge` the web components call. This file is the WALK
+ * itself, over two colour strings, so the native renderer can run it too:
+ * `Input.native.tsx` and `Select.native.tsx` have no MUI `Theme` to pass and no
+ * `@mui/material/styles` to import, and a second copy of the walk beside them
+ * is a second answer to "where is this field's border" waiting to drift.
+ *
+ * `./color` is a faithful port of MUI's colour manipulator (asserted equal to
+ * it in `./__tests__/color.test.ts`), so the string this returns is the string
+ * the web has always emitted.
+ */
+
+/**
+ * WCAG 2.1 SC 1.4.11 — the contrast a control's own boundary owes the surface
+ * behind it. See `./field-edge.ts` for why 3:1 and why it is a floor.
+ */
+export const MIN_UI_CONTRAST = 3;
+
+/** How far one step of the walk moves, and how many steps before it gives up. */
+const STEP = 0.05;
+const MAX_STEPS = 20;
+
+/** A colour's red, green, blue and alpha, with `hsl()` converted on the way. */
+function channels(colour: string): [number, number, number, number] {
+  const decomposed = decomposeColor(colour);
+  const rgb = decomposed.type.startsWith('hsl') ? decomposeColor(hslToRgb(colour)) : decomposed;
+  const [r, g, b, a] = rgb.values;
+  return [r ?? 0, g ?? 0, b ?? 0, a ?? 1];
+}
+
+/**
+ * A colour as an opaque `rgb()`, with any translucency resolved against
+ * `surface`.
+ *
+ * Needed because `getContrastRatio` reads the channels it is given and ignores
+ * the alpha, so handing it an `rgba()` measures a colour nobody sees.
+ */
+function flatten(colour: string, surface: string): string {
+  const [r, g, b, alpha] = channels(colour);
+  if (alpha >= 1) return recomposeColor({ type: 'rgb', values: [r, g, b] });
+
+  const [baseR, baseG, baseB] = channels(surface);
+  const blend = (fg: number, bg: number): number => Math.round(alpha * fg + (1 - alpha) * bg);
+  return recomposeColor({
+    type: 'rgb',
+    values: [blend(r, baseR), blend(g, baseG), blend(b, baseB)],
+  });
+}
+
+/**
+ * The resting boundary a control draws on `surface`, from the theme's own
+ * `divider` as the seed: the seed itself when it already clears
+ * {@link MIN_UI_CONTRAST}, otherwise the nearest tone of it that does.
+ */
+export function resolveFieldEdge(divider: string, surface: string): string {
+  const ground = flatten(surface, '#FFFFFF');
+  const seed = flatten(divider, ground);
+  if (getContrastRatio(seed, ground) >= MIN_UI_CONTRAST) return seed;
+
+  // Away from the surface, whichever way that is — so one rule serves both
+  // modes, and a dark card in a light theme is still handled by the pair rather
+  // than by `palette.mode`.
+  const away = getLuminance(ground) > 0.5 ? darken : lighten;
+  for (let step = 1; step <= MAX_STEPS; step += 1) {
+    // From the SEED each time rather than compounding the previous result, so
+    // the walk lands on the nearest passing tone instead of overshooting past it.
+    const candidate = away(seed, step * STEP);
+    if (getContrastRatio(candidate, ground) >= MIN_UI_CONTRAST) return candidate;
+  }
+  // Unreachable for any real surface — black clears 21:1 on white and white
+  // clears it on black — but a caller must never be handed `undefined`.
+  return getLuminance(ground) > 0.5 ? '#000000' : '#FFFFFF';
+}