@12-apps/ui 6.17.1 → 6.19.0

package/src/icons/Icon.tsx

@@ -0,0 +1,47 @@
+import SvgIcon from '@mui/material/SvgIcon/index.js';
+import * as React from 'react';
+
+import { iconFill } from './icon-color';
+import { iconSize, type IconBaseProps } from './Icon.types';
+import { ICON_PATHS } from './paths.generated';
+import { resolveTestId } from '../platform/test-id';
+import { useUiTheme } from '../provider/use-ui-theme';
+
+export interface IconProps extends IconBaseProps {
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+/**
+ * The web `Icon`: MUI's `SvgIcon` drawing the generated path, so a glyph named
+ * here is pixel-for-pixel the one `@mui/icons-material` would draw — and the one
+ * the native `Icon` draws from the same path data.
+ */
+export const Icon = React.forwardRef<SVGSVGElement, IconProps>(
+  ({ name, size, color, label, className, style, ...rest }, ref) => {
+    const theme = useUiTheme();
+    const px = iconSize(size);
+    const fill = iconFill(theme, color, 'currentColor');
+    const testId = resolveTestId(rest, `icon-${name}`);
+
+    return (
+      <SvgIcon
+        ref={ref}
+        viewBox="0 0 24 24"
+        className={className}
+        style={style}
+        sx={{ fontSize: px, color: fill }}
+        titleAccess={label}
+        aria-hidden={label ? undefined : true}
+        data-testid={testId}
+        data-icon={name}
+      >
+        {ICON_PATHS[name].map((d) => (
+          <path key={d} d={d} />
+        ))}
+      </SvgIcon>
+    );
+  },
+);
+
+Icon.displayName = 'Icon';

package/src/icons/Icon.types.ts

@@ -0,0 +1,40 @@
+import type { IconName } from './paths.generated';
+import type { ColorValue, SizeValue } from '../tokens/vocabulary';
+
+export type { IconName };
+
+/**
+ * The glyph sizes, in px. `md` is MUI's `SvgIcon` default (24) and `sm` its
+ * `small` (20); the rest continue the house scale in 4px steps either side.
+ */
+export const ICON_SIZES: Record<SizeValue, number> = {
+  xs: 16,
+  sm: 20,
+  md: 24,
+  lg: 32,
+  xl: 40,
+};
+
+export interface IconBaseProps {
+  /** Which glyph. The list is `src/icons/glyphs.json`; both renderers draw the same paths. */
+  name: IconName;
+  /** A step of the house scale, or an exact px size. */
+  size?: SizeValue | number;
+  /**
+   * A house colour, `inherit` (the surrounding text's colour on the web, the
+   * theme's primary text on native, which has no `currentColor`), or any CSS
+   * colour string.
+   */
+  color?: ColorValue | 'inherit' | string;
+  /**
+   * The name a screen reader gives the glyph. Omit for a decorative icon: it
+   * is then hidden from assistive technology on both renderers.
+   */
+  label?: string;
+  testID?: string;
+  dataTestId?: string;
+}
+
+/** The px size for either spelling of `size`. */
+export const iconSize = (size: SizeValue | number | undefined): number =>
+  typeof size === 'number' ? size : ICON_SIZES[size ?? 'md'];

package/src/icons/glyphs.json

@@ -0,0 +1,39 @@
+[
+  "Add",
+  "ArrowBack",
+  "ArrowDownward",
+  "ArrowForward",
+  "ArrowUpward",
+  "Check",
+  "CheckCircle",
+  "ChevronLeft",
+  "ChevronRight",
+  "Close",
+  "ContentCopy",
+  "Delete",
+  "Edit",
+  "Error",
+  "ErrorOutline",
+  "ExpandLess",
+  "ExpandMore",
+  "FilterList",
+  "Info",
+  "InfoOutlined",
+  "KeyboardArrowDown",
+  "KeyboardArrowUp",
+  "Menu",
+  "MoreHoriz",
+  "MoreVert",
+  "NavigateBefore",
+  "NavigateNext",
+  "Person",
+  "Refresh",
+  "Remove",
+  "Save",
+  "Search",
+  "Settings",
+  "Visibility",
+  "VisibilityOff",
+  "Warning",
+  "WarningAmber"
+]

package/src/icons/icon-color.ts

@@ -0,0 +1,20 @@
+import { COLOR_VALUES, type ColorValue } from '../tokens/vocabulary';
+import type { UiTheme } from '../tokens/theme';
+
+const isColorValue = (color: string): color is ColorValue =>
+  (COLOR_VALUES as readonly string[]).includes(color);
+
+/**
+ * The fill for an icon's `color` prop, on either renderer.
+ *
+ * A house colour resolves to the palette slot's `main`; `inherit` is the
+ * caller's problem (the web passes `currentColor`, native the text colour); any
+ * other string is taken as a CSS colour and passed through.
+ */
+export function iconFill(theme: UiTheme, color: string | undefined, inherit: string): string {
+  if (color === undefined || color === 'inherit') return inherit;
+  if (isColorValue(color)) {
+    return color === 'neutral' ? theme.palette.text.secondary : theme.palette[color].main;
+  }
+  return color;
+}

package/src/icons/index.native.ts

@@ -0,0 +1,5 @@
+export { Icon } from './Icon.native';
+export type { IconProps } from './Icon.native';
+export { ICON_SIZES, iconSize } from './Icon.types';
+export type { IconBaseProps, IconName } from './Icon.types';
+export { ICON_NAMES, ICON_PATHS } from './paths.generated';

package/src/icons/index.ts

@@ -0,0 +1,5 @@
+export { Icon } from './Icon';
+export type { IconProps } from './Icon';
+export { ICON_SIZES, iconSize } from './Icon.types';
+export type { IconBaseProps, IconName } from './Icon.types';
+export { ICON_NAMES, ICON_PATHS } from './paths.generated';

package/src/icons/paths.generated.ts

@@ -0,0 +1,51 @@
+// GENERATED by scripts/generate-icon-paths.mjs from src/icons/glyphs.json.
+// Do not edit: run `pnpm icons:generate`; `pnpm icons:check` fails CI on drift.
+//
+// Each entry is the `d` of every <path> in the matching @mui/icons-material
+// module, in a 24x24 viewBox — the SAME geometry the web renders through
+// SvgIcon, so the native Icon draws the identical glyph.
+
+/** Path data per glyph, in a 0 0 24 24 viewBox. */
+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"],
+  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"],
+  Check: ["M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"],
+  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"],
+  Close: ["M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"],
+  ContentCopy: ["M16 1H4c-1.1 0-2 .9-2 2v14h2V3h12zm3 4H8c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h11c1.1 0 2-.9 2-2V7c0-1.1-.9-2-2-2m0 16H8V7h11z"],
+  Delete: ["M6 19c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V7H6zM19 4h-3.5l-1-1h-5l-1 1H5v2h14z"],
+  Edit: ["M3 17.25V21h3.75L17.81 9.94l-3.75-3.75zM20.71 7.04c.39-.39.39-1.02 0-1.41l-2.34-2.34a.996.996 0 0 0-1.41 0l-1.83 1.83 3.75 3.75z"],
+  Error: ["M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m1 15h-2v-2h2zm0-4h-2V7h2z"],
+  ErrorOutline: ["M11 15h2v2h-2zm0-8h2v6h-2zm.99-5C6.47 2 2 6.48 2 12s4.47 10 9.99 10C17.52 22 22 17.52 22 12S17.52 2 11.99 2M12 20c-4.42 0-8-3.58-8-8s3.58-8 8-8 8 3.58 8 8-3.58 8-8 8"],
+  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"],
+  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"],
+  KeyboardArrowUp: ["M7.41 15.41 12 10.83l4.59 4.58L18 14l-6-6-6 6z"],
+  Menu: ["M3 18h18v-2H3zm0-5h18v-2H3zm0-7v2h18V6z"],
+  MoreHoriz: ["M6 10c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2m12 0c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2m-6 0c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2"],
+  MoreVert: ["M12 8c1.1 0 2-.9 2-2s-.9-2-2-2-2 .9-2 2 .9 2 2 2m0 2c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2m0 6c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2"],
+  NavigateBefore: ["M15.41 7.41 14 6l-6 6 6 6 1.41-1.41L10.83 12z"],
+  NavigateNext: ["M10 6 8.59 7.41 13.17 12l-4.58 4.59L10 18l6-6z"],
+  Person: ["M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4m0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4"],
+  Refresh: ["M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4z"],
+  Remove: ["M19 13H5v-2h14z"],
+  Save: ["M17 3H5c-1.11 0-2 .9-2 2v14c0 1.1.89 2 2 2h14c1.1 0 2-.9 2-2V7zm-5 16c-1.66 0-3-1.34-3-3s1.34-3 3-3 3 1.34 3 3-1.34 3-3 3m3-10H5V5h10z"],
+  Search: ["M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14"],
+  Settings: ["M19.14 12.94c.04-.3.06-.61.06-.94 0-.32-.02-.64-.07-.94l2.03-1.58c.18-.14.23-.41.12-.61l-1.92-3.32c-.12-.22-.37-.29-.59-.22l-2.39.96c-.5-.38-1.03-.7-1.62-.94l-.36-2.54c-.04-.24-.24-.41-.48-.41h-3.84c-.24 0-.43.17-.47.41l-.36 2.54c-.59.24-1.13.57-1.62.94l-2.39-.96c-.22-.08-.47 0-.59.22L2.74 8.87c-.12.21-.08.47.12.61l2.03 1.58c-.05.3-.09.63-.09.94s.02.64.07.94l-2.03 1.58c-.18.14-.23.41-.12.61l1.92 3.32c.12.22.37.29.59.22l2.39-.96c.5.38 1.03.7 1.62.94l.36 2.54c.05.24.24.41.48.41h3.84c.24 0 .44-.17.47-.41l.36-2.54c.59-.24 1.13-.56 1.62-.94l2.39.96c.22.08.47 0 .59-.22l1.92-3.32c.12-.22.07-.47-.12-.61zM12 15.6c-1.98 0-3.6-1.62-3.6-3.6s1.62-3.6 3.6-3.6 3.6 1.62 3.6 3.6-1.62 3.6-3.6 3.6"],
+  Visibility: ["M12 4.5C7 4.5 2.73 7.61 1 12c1.73 4.39 6 7.5 11 7.5s9.27-3.11 11-7.5c-1.73-4.39-6-7.5-11-7.5M12 17c-2.76 0-5-2.24-5-5s2.24-5 5-5 5 2.24 5 5-2.24 5-5 5m0-8c-1.66 0-3 1.34-3 3s1.34 3 3 3 3-1.34 3-3-1.34-3-3-3"],
+  VisibilityOff: ["M12 7c2.76 0 5 2.24 5 5 0 .65-.13 1.26-.36 1.83l2.92 2.92c1.51-1.26 2.7-2.89 3.43-4.75-1.73-4.39-6-7.5-11-7.5-1.4 0-2.74.25-3.98.7l2.16 2.16C10.74 7.13 11.35 7 12 7M2 4.27l2.28 2.28.46.46C3.08 8.3 1.78 10.02 1 12c1.73 4.39 6 7.5 11 7.5 1.55 0 3.03-.3 4.38-.84l.42.42L19.73 22 21 20.73 3.27 3zM7.53 9.8l1.55 1.55c-.05.21-.08.43-.08.65 0 1.66 1.34 3 3 3 .22 0 .44-.03.65-.08l1.55 1.55c-.67.33-1.41.53-2.2.53-2.76 0-5-2.24-5-5 0-.79.2-1.53.53-2.2m4.31-.78 3.15 3.15.02-.16c0-1.66-1.34-3-3-3z"],
+  Warning: ["M1 21h22L12 2zm12-3h-2v-2h2zm0-4h-2v-4h2z"],
+  WarningAmber: ["M12 5.99 19.53 19H4.47zM12 2 1 21h22z","M13 16h-2v2h2zm0-6h-2v5h2z"],
+} as const;
+
+export type IconName = keyof typeof ICON_PATHS;
+
+export const ICON_NAMES = Object.keys(ICON_PATHS) as readonly IconName[];

package/src/platform/aria.ts

@@ -0,0 +1,32 @@
+/**
+ * ARIA 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.
+ * react-native-web forwards all three to the DOM — and `aria-level` also
+ * picks the heading tag, so a `role="heading"` at level 3 renders an `<h3>`
+ * exactly as the MUI half's `component="h3"` does — while a device ignores
+ * them. A native component spreads them through here rather than widening
+ * the element's props type or casting at every call site.
+ */
+export interface WebAria {
+  'aria-level'?: 1 | 2 | 3 | 4 | 5 | 6;
+  'aria-atomic'?: 'true' | 'false';
+  'aria-describedby'?: string;
+}
+
+/**
+ * `attrs` as something JSX can spread onto a react-native element without
+ * that element's props type having to know them.
+ *
+ * `aria-atomic` travels under react-native-web's own older name. Its
+ * `createDOMProps` (0.20.0) reads `aria-activedescendant` where it means
+ * `aria-atomic` — `_ariaAtomic = ariaAtomic != null ? ariaActiveDescendant :
+ * accessibilityAtomic` — so the modern spelling never reaches the DOM and
+ * the legacy one, still accepted and still emitted as `aria-atomic`, does.
+ * Neither name exists on a device, so nothing is lost there.
+ */
+export function webAria(attrs: WebAria): object {
+  const { 'aria-atomic': atomic, ...rest } = attrs;
+  return atomic === undefined ? rest : { ...rest, accessibilityAtomic: atomic };
+}

package/src/platform/test-id.ts

@@ -0,0 +1,34 @@
+/**
+ * One test id, three spellings.
+ *
+ * The web components take `dataTestId` and forward it as `data-testid`; the
+ * existing test stories pass `'data-testid'` straight through as an unknown
+ * prop; React Native calls the same thing `testID`, and react-native-web turns
+ * THAT back into `data-testid`. A native component that honoured only one of
+ * the three would pass its own unit tests and fail the shared stories.
+ */
+export interface TestIdProps {
+  testID?: string;
+  dataTestId?: string;
+  'data-testid'?: string;
+}
+
+/** The id the caller asked for under any of the three names, else `fallback`. */
+export function resolveTestId(props: TestIdProps, fallback?: string): string | undefined {
+  return props.testID ?? props.dataTestId ?? props['data-testid'] ?? fallback;
+}
+
+/** `${id}-${suffix}` for a sub-element, or `${fallback}-${suffix}` when unnamed. */
+export function childTestId(
+  props: TestIdProps,
+  suffix: string,
+  fallback: string,
+): string {
+  return `${resolveTestId(props, fallback) ?? fallback}-${suffix}`;
+}
+
+/** `props` without any of the three spellings, for spreading onto a native element. */
+export function withoutTestIdProps<P extends TestIdProps>(props: P): Omit<P, keyof TestIdProps> {
+  const { testID: _testID, dataTestId: _dataTestId, 'data-testid': _dataTestid, ...rest } = props;
+  return rest;
+}

package/src/platform/text-children.tsx

@@ -0,0 +1,68 @@
+import * as React from 'react';
+import { Text as RNText, type TextStyle } from 'react-native';
+
+/**
+ * FREE-FORM CHILDREN, FLOWING AS THE WEB FLOWS THEM.
+ *
+ * `<Alert>O total é {total}.</Alert>` is THREE children — a string, a number
+ * and another string. The web lays them out inline, as one sentence. React
+ * Native has no inline text outside a `Text`, so a native component has to
+ * wrap them; wrapping each child on its own puts every fragment on its own
+ * line, which is what the harness caught: an alert body reading
+ *
+ *     O corpo do alerta na variante
+ *     success
+ *     .
+ *
+ * So CONSECUTIVE text children are grouped into one `Text` — the run flows as
+ * a sentence — and any element child ends the run and renders as given, the
+ * way a block element interrupts a paragraph on the web.
+ */
+const isText = (child: React.ReactNode): child is string | number =>
+  typeof child === 'string' || typeof child === 'number';
+
+/**
+ * Fragments are flattened first. A caller writing `<Alert><>{a} de {b}</></Alert>`
+ * hands over ONE child, and `React.Children.toArray` does not look inside it —
+ * so without this the fragment would reach React Native holding bare strings,
+ * which throws "Text strings must be rendered within a <Text> component".
+ */
+function flatten(children: React.ReactNode): React.ReactNode[] {
+  return React.Children.toArray(children).flatMap((child) =>
+    React.isValidElement(child) && child.type === React.Fragment
+      ? flatten((child.props as { children?: React.ReactNode }).children)
+      : [child],
+  );
+}
+
+export function renderTextChildren(
+  children: React.ReactNode,
+  style: TextStyle,
+  /** Passed to each run, for a surface that clips rather than wraps (a button label). */
+  numberOfLines?: number,
+): React.ReactNode {
+  const out: React.ReactNode[] = [];
+  let run: Array<string | number> = [];
+
+  const flush = (): void => {
+    if (run.length === 0) return;
+    out.push(
+      <RNText key={`text-${out.length}`} style={style} numberOfLines={numberOfLines}>
+        {run}
+      </RNText>,
+    );
+    run = [];
+  };
+
+  for (const child of flatten(children)) {
+    if (isText(child)) {
+      run.push(child);
+      continue;
+    }
+    flush();
+    out.push(child);
+  }
+  flush();
+
+  return out;
+}

package/src/provider/UiProvider.native.tsx

@@ -0,0 +1,13 @@
+import * as React from 'react';
+
+import { UiThemeContext } from './ui-theme-context';
+import { isUiTheme, type UiProviderProps } from './UiProvider.types';
+import { createUiTheme } from '../tokens/theme';
+
+/** The native `UiProvider`: the theme every native component reads. */
+export function UiProvider({ theme, children }: UiProviderProps): React.JSX.Element {
+  const ui = React.useMemo(() => (isUiTheme(theme) ? theme : createUiTheme(theme)), [theme]);
+  return <UiThemeContext.Provider value={ui}>{children}</UiThemeContext.Provider>;
+}
+
+UiProvider.displayName = 'UiProvider';

package/src/provider/UiProvider.tsx

@@ -0,0 +1,22 @@
+import { createTheme, ThemeProvider } from '@mui/material/styles/index.js';
+import * as React from 'react';
+
+import { muiThemeOptionsFrom } from './mui-bridge';
+import { isUiTheme, type UiProviderProps } from './UiProvider.types';
+import { createUiTheme } from '../tokens/theme';
+
+/**
+ * The same provider name on both renderers.
+ *
+ * On the web it is a MUI `ThemeProvider` fed from a `UiTheme`, for a host that
+ * has no MUI theme of its own. A host that already mounts one (every origin app
+ * does) needs nothing from this file: the web components read MUI's theme, and
+ * `useUiTheme` derives the neutral view from it.
+ */
+export function UiProvider({ theme, children }: UiProviderProps): React.JSX.Element {
+  const ui = React.useMemo(() => (isUiTheme(theme) ? theme : createUiTheme(theme)), [theme]);
+  const mui = React.useMemo(() => createTheme(muiThemeOptionsFrom(ui)), [ui]);
+  return <ThemeProvider theme={mui}>{children}</ThemeProvider>;
+}
+
+UiProvider.displayName = 'UiProvider';

package/src/provider/UiProvider.types.ts

@@ -0,0 +1,20 @@
+import type * as React from 'react';
+
+import type { UiTheme, UiThemeOptions } from '../tokens/theme';
+
+export interface UiProviderProps {
+  /**
+   * A built `UiTheme`, or the options to build one. Omit for the package
+   * default: the platform's light theme.
+   */
+  theme?: UiTheme | UiThemeOptions;
+  children: React.ReactNode;
+}
+
+/**
+ * Options may carry a `palette` too (the seeds), so the discriminant is the
+ * one thing only a BUILT theme has: `spacing` as a function. Options carry a
+ * numeric `spacingUnit` instead.
+ */
+export const isUiTheme = (theme: UiTheme | UiThemeOptions | undefined): theme is UiTheme =>
+  theme !== undefined && 'palette' in theme && 'spacing' in theme && typeof theme.spacing === 'function';

package/src/provider/index.native.ts

@@ -0,0 +1,3 @@
+export { UiProvider } from './UiProvider.native';
+export type { UiProviderProps } from './UiProvider.types';
+export { useUiTheme } from './use-ui-theme.native';

package/src/provider/index.ts

@@ -0,0 +1,4 @@
+export { UiProvider } from './UiProvider';
+export type { UiProviderProps } from './UiProvider.types';
+export { useUiTheme } from './use-ui-theme';
+export { muiThemeOptionsFrom, uiThemeFromMui } from './mui-bridge';

package/src/provider/mui-bridge.ts

@@ -0,0 +1,141 @@
+import type { PaletteColor, Theme, ThemeOptions } from '@mui/material/styles/index.js';
+
+import { cssLengthToPx, cssTrackingToEm } from '../tokens/css-units';
+import { accentFor } from '../tokens/scales';
+import {
+  FONT_WEIGHTS,
+  TYPE_SIZES,
+  WEB_FONT_FAMILY,
+  WEB_MONOSPACE_FONT_FAMILY,
+  type UiHeadingStep,
+  type UiPaletteColor,
+  type UiTheme,
+} from '../tokens/theme';
+import { HEADING_LEVELS, headingMetrics, type HeadingLevel } from '../tokens/typography';
+
+/**
+ * THE TWO DIRECTIONS BETWEEN MUI'S THEME AND OURS. Web only.
+ *
+ * `uiThemeFromMui` is how a web component — or a shared style resolver such
+ * as `box-layout.ts` — reads the host's MUI theme in the neutral shape the
+ * native renderer reads natively. `muiThemeOptionsFrom` is the reverse, for
+ * a host that has a `UiTheme` and no MUI theme yet: `UiProvider` on the web is
+ * a MUI `ThemeProvider` fed by it.
+ *
+ * Both are field-by-field on purpose. A spread would carry MUI's extra keys
+ * across and the native side would silently depend on one.
+ */
+
+const slot = (color: PaletteColor): UiPaletteColor => ({
+  main: color.main,
+  light: color.light,
+  dark: color.dark,
+  contrastText: color.contrastText,
+});
+
+function headingSteps(theme: Theme): Record<HeadingLevel, UiHeadingStep> {
+  return Object.fromEntries(
+    HEADING_LEVELS.map((level) => {
+      const metrics = headingMetrics(theme, level);
+      return [
+        level,
+        {
+          fontSize: cssLengthToPx(metrics.fontSize, 16),
+          lineHeight: metrics.lineHeight,
+          letterSpacing: cssTrackingToEm(metrics.letterSpacing),
+          normalWeight: metrics.normalWeight,
+        },
+      ];
+    }),
+  ) as Record<HeadingLevel, UiHeadingStep>;
+}
+
+/** The host's MUI theme in the shape the native renderer reads. */
+export function uiThemeFromMui(theme: Theme): UiTheme {
+  const { palette } = theme;
+  const unit = cssLengthToPx(theme.spacing(1), 8);
+  const md = cssLengthToPx(theme.shape.borderRadius, 4);
+
+  return {
+    mode: palette.mode,
+    palette: {
+      mode: palette.mode,
+      primary: slot(palette.primary),
+      secondary: slot(palette.secondary),
+      success: slot(palette.success),
+      warning: slot(palette.warning),
+      info: slot(palette.info),
+      danger: slot(palette.error),
+      neutral: accentFor(theme, 'neutral'),
+      text: {
+        primary: palette.text.primary,
+        secondary: palette.text.secondary,
+        disabled: palette.text.disabled,
+      },
+      background: { default: palette.background.default, paper: palette.background.paper },
+      divider: palette.divider,
+      action: {
+        active: palette.action.active,
+        hover: palette.action.hover,
+        selected: palette.action.selected,
+        disabled: palette.action.disabled,
+        disabledBackground: palette.action.disabledBackground,
+        focus: palette.action.focus,
+      },
+      grey: {
+        50: palette.grey[50],
+        100: palette.grey[100],
+        200: palette.grey[200],
+        300: palette.grey[300],
+        400: palette.grey[400],
+        500: palette.grey[500],
+        600: palette.grey[600],
+        700: palette.grey[700],
+        800: palette.grey[800],
+        900: palette.grey[900],
+      },
+    },
+    spacing: (units: number) => units * unit,
+    spacingUnit: unit,
+    radius: { sm: md / 2, md, lg: md * 2, xl: md * 4, full: 9999 },
+    typography: {
+      fontFamily: theme.typography.fontFamily ?? WEB_FONT_FAMILY,
+      monospaceFontFamily: WEB_MONOSPACE_FONT_FAMILY,
+      sizes: TYPE_SIZES,
+      weights: FONT_WEIGHTS,
+      heading: headingSteps(theme),
+    },
+    zIndex: {
+      appBar: theme.zIndex.appBar,
+      drawer: theme.zIndex.drawer,
+      modal: theme.zIndex.modal,
+      snackbar: theme.zIndex.snackbar,
+      tooltip: theme.zIndex.tooltip,
+    },
+  };
+}
+
+/** A `UiTheme` as the options MUI's `createTheme` builds the same palette from. */
+export function muiThemeOptionsFrom(ui: UiTheme): ThemeOptions {
+  const { palette } = ui;
+  return {
+    palette: {
+      mode: palette.mode,
+      primary: { ...palette.primary },
+      secondary: { ...palette.secondary },
+      success: { ...palette.success },
+      warning: { ...palette.warning },
+      info: { ...palette.info },
+      error: { ...palette.danger },
+      text: { ...palette.text },
+      background: { ...palette.background },
+      divider: palette.divider,
+      action: { ...palette.action },
+      grey: { ...palette.grey },
+    },
+    shape: { borderRadius: ui.radius.md },
+    spacing: ui.spacingUnit,
+    typography: { fontFamily: ui.typography.fontFamily ?? WEB_FONT_FAMILY },
+    zIndex: { ...ui.zIndex },
+  };
+}

package/src/provider/ui-theme-context.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+
+import type { UiTheme } from '../tokens/theme';
+
+/**
+ * The native renderer's theme channel.
+ *
+ * Only the native files read it. On the web the theme every component paints
+ * from is MUI's, reached through emotion's own context, and `use-ui-theme.ts`
+ * derives a `UiTheme` view of it — so there is exactly one source of truth per
+ * renderer rather than two that can disagree.
+ */
+export const UiThemeContext = React.createContext<UiTheme | null>(null);

package/src/provider/use-ui-theme.native.ts

@@ -0,0 +1,9 @@
+import * as React from 'react';
+
+import { UiThemeContext } from './ui-theme-context';
+import { DEFAULT_UI_THEME, type UiTheme } from '../tokens/theme';
+
+/** The theme the nearest `UiProvider` set, or the package default without one. */
+export function useUiTheme(): UiTheme {
+  return React.useContext(UiThemeContext) ?? DEFAULT_UI_THEME;
+}

package/src/provider/use-ui-theme.ts

@@ -0,0 +1,18 @@
+import { useTheme } from '@mui/material/styles/index.js';
+import * as React from 'react';
+
+import { uiThemeFromMui } from './mui-bridge';
+import type { UiTheme } from '../tokens/theme';
+
+/**
+ * The web reading of the theme: MUI's, as a `UiTheme`.
+ *
+ * Derived rather than provided on purpose. A host that already mounts its own
+ * `ThemeProvider` (every origin app does, through `@12-apps/app-shell`) gets
+ * the same numbers a MUI-styled sibling paints with, and nothing has to be
+ * mounted twice or kept in step.
+ */
+export function useUiTheme(): UiTheme {
+  const theme = useTheme();
+  return React.useMemo(() => uiThemeFromMui(theme), [theme]);
+}