@12-apps/ui 6.18.0 → 6.19.0

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';

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

@@ -0,0 +1,32 @@
+import type { SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE CONTRACT BOTH `Spacer` 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.
+ */
+export type SpacerSize = SizeValue;
+export type SpacerDirection = 'horizontal' | 'vertical' | 'both';
+
+/**
+ * An explicit dimension: a px number, a percentage, `auto`, or any CSS length.
+ * The web hands a string to the DOM as it is; the native renderer reads the CSS
+ * lengths it can (`rem`, `em`, `px`) against a 16px root and ignores the rest.
+ */
+export type SpacerDimension = number | string;
+
+export interface SpacerBaseProps {
+  /** A step of the house scale, in spacing units — see `SPACER_SIZE_UNITS`. */
+  size?: SpacerSize;
+  /** Which axes the step applies to; the other keeps whatever `width`/`height` says. */
+  direction?: SpacerDirection;
+  /** Overrides the step on that axis, whatever `direction` is. */
+  width?: SpacerDimension;
+  height?: SpacerDimension;
+  /** Grow to fill the free space in a flex row or column. */
+  flex?: boolean;
+  testID?: string;
+  dataTestId?: string;
+}

package/src/components/layout/Spacer/Spacer.md

@@ -13,7 +13,8 @@ The Spacer component creates consistent spacing between elements in layouts. It'
 | width     | number \| string                     | -       | Custom width value (overrides size when provided)           |
 | height    | number \| string                     | -       | Custom height value (overrides size when provided)          |
 | flex      | boolean                              | false   | When true, spacer flexes to fill available space            |
-| className | string                               | -       | Additional CSS class for custom styling                     |
+| className | string                               | -       | Additional CSS class for custom styling (web only)          |
+| testID / dataTestId | string                     | -       | Test id, on both renderers (`data-testid` on the web)       |
 
 ## Usage Examples
 
@@ -57,6 +58,17 @@ The Spacer component creates consistent spacing between elements in layouts. It'
 <Spacer direction="vertical" size="sm" />
 ```
 
+## React Native
+
+The same import renders natively (`@12-apps/ui/layout/Spacer` resolves to
+`Spacer.native.tsx` under Metro): an empty `View` sized from the same
+`SPACER_SIZE_UNITS` the web hands to `theme.spacing`, so an `md` spacer is 16
+wide on both sides. `width`/`height` take a number, a percentage or `auto` on
+both renderers; a CSS length string (`2rem`, `20px`) is read against the 16px
+root on native, and anything else (`calc()`, `vw`) yields to the size step.
+`testID`, `dataTestId` and `data-testid` all name the element. See
+[NATIVE.md](../../../../NATIVE.md).
+
 ## Accessibility Notes
 
 - The Spacer component is purely presentational and has `aria-hidden="true"` to prevent screen readers from announcing it

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

@@ -0,0 +1,55 @@
+import type { SpacerDirection, SpacerSize } from './Spacer.base';
+
+/**
+ * THE NUMBERS BOTH `Spacer` RENDERERS DRAW WITH.
+ *
+ * `Spacer.tsx` used to hold the size steps as a `switch` over
+ * `theme.spacing(…)` calls, and `Spacer.native.tsx` would have held them again
+ * as a second table. Now there is one, in SPACING UNITS, and each renderer
+ * multiplies it out through its own `theme.spacing` — `'16px'` on the web,
+ * `16` on native — so an `md` spacer is 16 wide on both sides by construction.
+ */
+export const SPACER_SIZE_UNITS: Record<SpacerSize, number> = {
+  xs: 0.5,
+  sm: 1,
+  md: 2,
+  lg: 3,
+  xl: 4,
+};
+
+export const SPACER_DEFAULT_SIZE: SpacerSize = 'md';
+export const SPACER_DEFAULT_DIRECTION: SpacerDirection = 'both';
+
+/** `flex` grows the spacer by one share of the free space; every spacer refuses to shrink. */
+export const SPACER_FLEX_GROW = 1;
+export const SPACER_FLEX_SHRINK = 0;
+
+/** The geometry props, with the dimension type left to the renderer. */
+export interface SpacerGeometry<Dimension> {
+  size?: SpacerSize;
+  direction?: SpacerDirection;
+  width?: Dimension;
+  height?: Dimension;
+}
+
+/**
+ * The width and height a spacer occupies, on either renderer.
+ *
+ * An explicit `width`/`height` wins on its axis whatever `direction` says; the
+ * step fills only the axes `direction` names. `spacing` is the renderer's own
+ * `theme.spacing`, so the same units come out as `'16px'` on the web and `16`
+ * on native — the one resolver is what keeps the two from disagreeing.
+ */
+export function spacerDimensions<Dimension, Spacing>(
+  geometry: SpacerGeometry<Dimension>,
+  spacing: (units: number) => Spacing,
+): { width: Dimension | Spacing | undefined; height: Dimension | Spacing | undefined } {
+  const { size = SPACER_DEFAULT_SIZE, direction = SPACER_DEFAULT_DIRECTION, width, height } = geometry;
+  // A size outside the vocabulary (a story control, an untyped caller) draws `md`,
+  // exactly as the old `switch` did in its `default` arm.
+  const step = spacing(SPACER_SIZE_UNITS[size] ?? SPACER_SIZE_UNITS[SPACER_DEFAULT_SIZE]);
+  return {
+    width: direction === 'vertical' ? width : (width ?? step),
+    height: direction === 'horizontal' ? height : (height ?? step),
+  };
+}

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

@@ -0,0 +1,68 @@
+import * as React from 'react';
+import { View, type ViewStyle } from 'react-native';
+
+import { SPACER_FLEX_GROW, SPACER_FLEX_SHRINK, spacerDimensions } from './Spacer.metrics';
+import type { SpacerDimension, SpacerProps } from './Spacer.types.native';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import { cssLengthToPx } from '../../../tokens/css-units';
+import type { BoxDimension } from '../Box/Box.base';
+
+const PERCENTAGE = /^-?\d+(\.\d+)?%$/;
+/** The lengths a 16px root can resolve. `vw`, `vh`, `ch`, `pt` and `calc()` cannot. */
+const RESOLVABLE_LENGTH = /^-?\d+(\.\d+)?(px|rem|em)$/;
+
+/**
+ * A caller's dimension as React Native can take it. Numbers, percentages and
+ * `auto` pass through; a CSS length (`2rem`, `1.5em`, `20px`) is read against
+ * the 16px root the web would use, so the same string measures the same on
+ * both sides. Anything else (`calc()`, `vw`) is not a length React Native has,
+ * and yields to the size step — the same fallback an unset dimension takes.
+ */
+export function toNativeDimension(value: SpacerDimension | undefined): BoxDimension | undefined {
+  if (typeof value === 'number') return value;
+  if (typeof value !== 'string') return undefined;
+  if (value === 'auto') return 'auto';
+  if (PERCENTAGE.test(value)) return value as `${number}%`;
+  // Matched before conversion, because `cssLengthToPx` reads any string
+  // `parseFloat` can start — `50vw` would silently become 50 px.
+  if (!RESOLVABLE_LENGTH.test(value)) return undefined;
+  const px = cssLengthToPx(value, Number.NaN);
+  return Number.isNaN(px) ? undefined : px;
+}
+
+/**
+ * The native `Spacer`: an empty `View` sized from the same metrics the web
+ * puts in `sx`. Hidden from assistive technology and deaf to touches, as the
+ * web one is to the pointer.
+ */
+export const Spacer = React.forwardRef<View, SpacerProps>(
+  ({ size, direction, width, height, flex = false, style, ...others }, ref) => {
+    const theme = useUiTheme();
+    const dimensions = spacerDimensions(
+      { size, direction, width: toNativeDimension(width), height: toNativeDimension(height) },
+      theme.spacing,
+    );
+    // `userSelect` is the one web declaration with no View equivalent: a
+    // React Native view holds no text to select.
+    const resolved: ViewStyle = {
+      width: dimensions.width,
+      height: dimensions.height,
+      flex: flex ? SPACER_FLEX_GROW : undefined,
+      flexShrink: SPACER_FLEX_SHRINK,
+      pointerEvents: 'none',
+    };
+
+    return (
+      <View
+        ref={ref}
+        aria-hidden
+        style={[resolved, style]}
+        testID={resolveTestId(others)}
+        {...withoutTestIdProps(others)}
+      />
+    );
+  },
+);
+
+Spacer.displayName = 'Spacer';

package/src/components/layout/Spacer/Spacer.tsx

@@ -2,64 +2,34 @@ import Box from '@mui/material/Box/index.js';
 import { useTheme } from '@mui/material/styles/index.js';
 import React from 'react';
 
+import { SPACER_FLEX_GROW, SPACER_FLEX_SHRINK, spacerDimensions } from './Spacer.metrics';
 import type { SpacerProps } from './Spacer.types';
+import { resolveTestId } from '../../../platform/test-id';
 
 export const Spacer: React.FC<SpacerProps> = ({
-  size = 'md',
-  direction = 'both',
+  size,
+  direction,
   width,
   height,
   flex = false,
   className,
-  'data-testid': dataTestId,
+  ...testIdProps
 }) => {
   const theme = useTheme();
 
-  const getSpacing = () => {
-    switch (size) {
-      case 'xs':
-        return theme.spacing(0.5);
-      case 'sm':
-        return theme.spacing(1);
-      case 'md':
-        return theme.spacing(2);
-      case 'lg':
-        return theme.spacing(3);
-      case 'xl':
-        return theme.spacing(4);
-      default:
-        return theme.spacing(2);
-    }
-  };
-
-  const getDimensions = () => {
-    const spacing = getSpacing();
-
-    let finalWidth = width;
-    let finalHeight = height;
-
-    if (direction === 'horizontal' || direction === 'both') {
-      finalWidth = width ?? spacing;
-    }
-
-    if (direction === 'vertical' || direction === 'both') {
-      finalHeight = height ?? spacing;
-    }
-
-    return { width: finalWidth, height: finalHeight };
-  };
-
-  const dimensions = getDimensions();
+  // From the shared metrics, not a table of our own: the native `Spacer` reads
+  // the same units, so the two renderers cannot disagree on a step.
+  const dimensions = spacerDimensions({ size, direction, width, height }, (units) => theme.spacing(units));
 
   return (
     <Box
       className={className}
-      data-testid={dataTestId}
+      data-testid={resolveTestId(testIdProps)}
       sx={{
         width: dimensions.width,
         height: dimensions.height,
-        flex: flex ? 1 : undefined,
-        flexShrink: 0,
+        flex: flex ? SPACER_FLEX_GROW : undefined,
+        flexShrink: SPACER_FLEX_SHRINK,
         pointerEvents: 'none',
         userSelect: 'none',
       }}

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

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

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

@@ -1,13 +1,9 @@
-import type { SizeValue } from '../../../tokens/scales';
-export type SpacerSize = SizeValue;
-export type SpacerDirection = 'horizontal' | 'vertical' | 'both';
+import type { SpacerBaseProps } from './Spacer.base';
 
-export interface SpacerProps {
-  size?: SpacerSize;
-  direction?: SpacerDirection;
-  width?: number | string;
-  height?: number | string;
-  flex?: boolean;
+export type { SpacerBaseProps, SpacerDimension, SpacerDirection, SpacerSize } from './Spacer.base';
+
+/** The web `Spacer`: the shared contract, plus the DOM's class hook and its own test-id spelling. */
+export interface SpacerProps extends SpacerBaseProps {
   className?: string;
   'data-testid'?: string;
 }

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

@@ -0,0 +1,2 @@
+export { Spacer } from './Spacer.native';
+export type { SpacerBaseProps, SpacerDimension, SpacerDirection, SpacerProps, SpacerSize } from './Spacer.types.native';

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

@@ -1,2 +1,2 @@
 export { Spacer } from './Spacer';
-export type { SpacerProps } from './Spacer.types';
+export type { SpacerBaseProps, SpacerDimension, SpacerDirection, SpacerProps, SpacerSize } from './Spacer.types';

package/src/components/typography/Heading/Heading.base.ts

@@ -0,0 +1,55 @@
+import type React from 'react';
+
+import type { HeadingLevel } from '../../../tokens/heading-scale';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE CONTRACT BOTH `Heading` 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 a heading element's attributes in `Heading.types.ts`; the native side
+ * adds a react-native `Text`'s props in `Heading.types.native.ts`.
+ */
+export type { HeadingLevel };
+
+export type HeadingWeight = 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
+
+export interface HeadingBaseProps {
+  /**
+   * The heading's RANK — which tag it renders (`aria-level` on native) and
+   * where it sits in the document outline. Not its size; see {@link HeadingBaseProps.size}.
+   */
+  level?: HeadingLevel;
+  /**
+   * The step of the type scale to DRAW, when it differs from the rank. Defaults
+   * to `level`, so every call written before this prop existed renders exactly
+   * as it did.
+   *
+   * It exists because `level` used to do three jobs at once — pick the tag, set
+   * the outline rank, set the font size — with no way to separate them. A page
+   * title is an `h1` to a screen reader whatever it looks like, and a dense
+   * screen may not want it drawn at the rank's size. Before this the only way to
+   * say that was to override the component's CSS from outside, which each
+   * consuming app ended up doing in its own dialect.
+   *
+   * ```tsx
+   * <Heading level="h1" size="h3">Visão geral</Heading>
+   * ```
+   *
+   * Reach for it when the two genuinely differ for ONE heading. If a whole
+   * product wants a different scale, set `typography.headingScale` on the theme
+   * instead — that is the knob for "our headings are smaller", and this is the
+   * one for "this heading is".
+   */
+  size?: HeadingLevel;
+  color?: ColorValue;
+  /** `normal` is the weight the step was designed to carry, not body text's 400. */
+  weight?: HeadingWeight;
+  /** Paint the glyphs with the colour's two-stop gradient (the first stop, flat, on native). */
+  gradient?: boolean;
+  children: React.ReactNode;
+  testID?: string;
+  dataTestId?: string;
+}

package/src/components/typography/Heading/Heading.md

@@ -164,6 +164,19 @@ Gradient text uses CSS `background-clip: text` with fallback support:
 - **Danger**: Linear gradient from error.light to error.dark
 - **Default**: Primary to secondary gradient
 
+## React Native
+
+The same import renders natively (`@12-apps/ui/typography/Heading` resolves
+to `Heading.native.tsx` under Metro): a react-native `Text` with
+`role="heading"` and `aria-level` set from `level` (`display` announces 1),
+drawn at `size ?? level` from the theme's heading scale
+(`UiTheme.typography.heading`, `HEADING_SCALE` unless the host built its own)
+with the same weights and colour mapping. `gradient` paints the gradient's
+first stop as a flat colour — React Native has no `background-clip: text`
+(see `NATIVE-NOTES.md`). `testID`, `dataTestId` and `data-testid` all name the
+element; `onClick` and `onPress` both fire. See
+[NATIVE.md](../../../../NATIVE.md).
+
 ## Accessibility
 
 - Maintains proper semantic heading hierarchy

package/src/components/typography/Heading/Heading.metrics.ts

@@ -0,0 +1,84 @@
+import type { HeadingWeight } from './Heading.base';
+import { HEADING_SCALE, type HeadingLevel } from '../../../tokens/heading-scale';
+import { FONT_WEIGHTS, type UiTheme } from '../../../tokens/theme';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE NUMBERS BOTH `Heading` RENDERERS DRAW WITH.
+ *
+ * The type scale itself is `HEADING_SCALE` in `tokens/heading-scale.ts` (the
+ * web reads it through the MUI theme's `headingScale` overrides, native
+ * through `UiTheme.typography.heading`). What lives here is everything ELSE
+ * `Heading.styles.ts` used to declare inline: the weight table, the defaults,
+ * the rank each level announces, and the gradient's angle and stops.
+ */
+export const HEADING_WEIGHTS: Record<HeadingWeight, number> = FONT_WEIGHTS;
+
+export const HEADING_DEFAULT_LEVEL: HeadingLevel = 'h2';
+export const HEADING_DEFAULT_WEIGHT: HeadingWeight = 'bold';
+export const HEADING_DEFAULT_COLOR: ColorValue = 'neutral';
+
+export type HeadingRank = 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * The outline rank each level announces — the tag on the web, `aria-level` on
+ * native. `display` is a SIZE, not a rank, so it is an h1: the document still
+ * gets one level-one heading rather than an unnamed tag outside the outline.
+ */
+export const HEADING_RANK: Record<HeadingLevel, HeadingRank> = {
+  display: 1,
+  h1: 1,
+  h2: 2,
+  h3: 3,
+  h4: 4,
+  h5: 5,
+  h6: 6,
+};
+
+/** A step name the scale actually has, or the documented default (`h2`). */
+export const stepOf = (value: string | undefined): HeadingLevel =>
+  value !== undefined && value in HEADING_SCALE ? (value as HeadingLevel) : HEADING_DEFAULT_LEVEL;
+
+const isHeadingWeight = (value: string): value is HeadingWeight => value in HEADING_WEIGHTS;
+
+/**
+ * The weight a heading draws: `normal` is the weight the step was designed to
+ * carry (heavier as the step gets larger), anything else its table entry, and
+ * a name outside the vocabulary the default — as `Heading.styles.ts` has
+ * always fallen back.
+ */
+export function headingWeight(weight: string, normalWeight: number): number {
+  if (weight === 'normal') return normalWeight;
+  return HEADING_WEIGHTS[isHeadingWeight(weight) ? weight : HEADING_DEFAULT_WEIGHT];
+}
+
+/** The gradient runs corner to corner. */
+export const HEADING_GRADIENT_ANGLE = 135;
+
+/**
+ * `neutral` has no light/dark pair, so its gradient runs between two steps of
+ * the grey ramp.
+ */
+export const NEUTRAL_GRADIENT_STEPS = { from: 500, to: 900 } as const;
+
+/** The CSS the web paints the glyphs with, from the two stops. */
+export const headingGradient = (from: string, to: string): string =>
+  `linear-gradient(${HEADING_GRADIENT_ANGLE}deg, ${from} 0%, ${to} 100%)`;
+
+/**
+ * The two stops each colour paints its glyphs with, read off a `UiTheme`. The
+ * web's `Heading.styles.ts` keeps its MUI-typed twin of this table; the pairs
+ * are the same, and `Heading.native.test.tsx` asserts as much.
+ */
+export function headingGradientStops(theme: UiTheme, color: ColorValue): [string, string] {
+  switch (color) {
+    case 'primary':
+      return [theme.palette.primary.main, theme.palette.secondary.main];
+    case 'secondary':
+      return [theme.palette.secondary.main, theme.palette.primary.main];
+    case 'neutral':
+      return [theme.palette.grey[NEUTRAL_GRADIENT_STEPS.from], theme.palette.grey[NEUTRAL_GRADIENT_STEPS.to]];
+    default:
+      return [theme.palette[color].light, theme.palette[color].dark];
+  }
+}