@12-apps/ui 6.18.0 → 6.19.0

package/src/components/typography/Heading/Heading.native.tsx

@@ -0,0 +1,105 @@
+import * as React from 'react';
+import { Text as RNText, type GestureResponderEvent, type TextStyle } from 'react-native';
+
+import type { HeadingWeight } from './Heading.base';
+import {
+  HEADING_DEFAULT_COLOR,
+  HEADING_DEFAULT_LEVEL,
+  HEADING_DEFAULT_WEIGHT,
+  HEADING_RANK,
+  headingGradientStops,
+  headingWeight,
+  stepOf,
+} from './Heading.metrics';
+import type { HeadingProps } from './Heading.types.native';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import type { HeadingLevel } from '../../../tokens/heading-scale';
+import type { UiTheme } from '../../../tokens/theme';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+/** Same mapping as the web `getColorFromTheme`: neutral is body ink, every other colour its slot's main. */
+const inkFor = (theme: UiTheme, color: ColorValue): string =>
+  color === 'neutral' ? theme.palette.text.primary : theme.palette[color].main;
+
+export interface HeadingStyleArgs {
+  /** The step to DRAW — `size ?? level`, already resolved to a name the scale has. */
+  size: HeadingLevel;
+  color: ColorValue;
+  weight: HeadingWeight;
+  gradient: boolean;
+}
+
+/**
+ * The style the web `headingSx` computes, in absolute numbers. The step comes
+ * from the theme's heading scale (`HEADING_SCALE` unless the host built its
+ * own), and its `lineHeight` ratio and `letterSpacing` em are multiplied out
+ * because React Native has neither unit.
+ *
+ * `gradient` is the one honest gap: React Native has no `background-clip:
+ * text` and no gradient fill in core, so the glyphs take the gradient's first
+ * stop as a flat colour — the same choice the native `Button` makes.
+ */
+export function headingStyle(theme: UiTheme, a: HeadingStyleArgs): TextStyle {
+  const step = theme.typography.heading[a.size];
+  return {
+    fontFamily: theme.typography.fontFamily,
+    fontSize: step.fontSize,
+    lineHeight: step.fontSize * step.lineHeight,
+    letterSpacing: step.letterSpacing === undefined ? undefined : step.letterSpacing * step.fontSize,
+    fontWeight: String(headingWeight(a.weight, step.normalWeight)) as TextStyle['fontWeight'],
+    color: a.gradient ? headingGradientStops(theme, a.color)[0] : inkFor(theme, a.color),
+  };
+}
+
+export const Heading = React.forwardRef<RNText, HeadingProps>(
+  (
+    {
+      level = HEADING_DEFAULT_LEVEL,
+      size,
+      color = HEADING_DEFAULT_COLOR,
+      weight = HEADING_DEFAULT_WEIGHT,
+      gradient = false,
+      children,
+      style,
+      onClick,
+      onPress,
+      ...others
+    },
+    ref,
+  ) => {
+    const rest = withoutTestIdProps(others);
+    const theme = useUiTheme();
+    // The rank is `level`'s; the drawn step is `size`'s, falling back to the
+    // rank's — the same two derivations the web makes from the same two props.
+    const rank = HEADING_RANK[stepOf(level)];
+    const step = stepOf(size ?? level);
+    const resolved = React.useMemo(
+      () => headingStyle(theme, { size: step, color, weight, gradient }),
+      [theme, step, color, weight, gradient],
+    );
+    const handlePress =
+      onClick || onPress
+        ? (event: GestureResponderEvent): void => {
+            onClick?.(event);
+            onPress?.(event);
+          }
+        : undefined;
+
+    return (
+      <RNText
+        ref={ref}
+        role="heading"
+        aria-level={rank}
+        style={[resolved, style]}
+        testID={resolveTestId(others)}
+        onPress={handlePress}
+        {...rest}
+      >
+        {children}
+      </RNText>
+    );
+  },
+);
+
+Heading.displayName = 'Heading';

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

@@ -1,11 +1,16 @@
 import type { CSSObject, Theme } from '@mui/material/styles/index.js';
 
-import type { HeadingProps } from './Heading.types';
-import { HEADING_SCALE, headingMetrics, type HeadingLevel } from '../../../tokens/typography';
+import {
+  HEADING_DEFAULT_COLOR,
+  HEADING_DEFAULT_WEIGHT,
+  NEUTRAL_GRADIENT_STEPS,
+  headingGradient,
+  headingWeight,
+  stepOf,
+} from './Heading.metrics';
+import { headingMetrics } from '../../../tokens/typography';
 import type { ColorValue } from '../../../tokens/scales';
 
-type Weight = NonNullable<HeadingProps['weight']>;
-
 // Exhaustive over ColorValue, and deliberately without a fallback. The map
 // happened to hold all seven already, but it was `Record<string, string>` with
 // `|| text.primary` behind it — so nothing kept it that way, and the eighth
@@ -29,14 +34,6 @@ const getColorFromTheme = (theme: Theme, color: ColorValue): string => {
   return colorMap[color];
 };
 
-const WEIGHTS: Record<Weight, number> = {
-  light: 300,
-  normal: 400,
-  medium: 500,
-  semibold: 600,
-  bold: 700,
-};
-
 /** The two-stop gradient each colour paints its glyphs with. */
 const PRIMARY_STOPS = (theme: Theme): [string, string] => [
   theme.palette.primary.main,
@@ -47,6 +44,9 @@ const PRIMARY_STOPS = (theme: Theme): [string, string] => [
 // stops were missing — `info` and `neutral` — so a gradient heading in either
 // colour painted the PRIMARY gradient and looked deliberate while ignoring the
 // prop entirely. The fallback is what hid it, so the fallback is gone.
+//
+// The MUI-typed twin of `headingGradientStops` in `Heading.metrics.ts`, which
+// the native renderer reads off a `UiTheme`; the pairs are the same.
 const GRADIENT_STOPS: Record<ColorValue, (theme: Theme) => [string, string]> = {
   primary: PRIMARY_STOPS,
   secondary: (theme) => [theme.palette.secondary.main, theme.palette.primary.main],
@@ -56,12 +56,15 @@ const GRADIENT_STOPS: Record<ColorValue, (theme: Theme) => [string, string]> = {
   danger: (theme) => [theme.palette.error.light, theme.palette.error.dark],
   // The grey ramp has no light/dark pair, and every stop on it is
   // `string | undefined` under `noUncheckedIndexedAccess`.
-  neutral: (theme) => [theme.palette.grey[500] ?? '#9e9e9e', theme.palette.grey[900] ?? '#212121'],
+  neutral: (theme) => [
+    theme.palette.grey[NEUTRAL_GRADIENT_STEPS.from] ?? '#9e9e9e',
+    theme.palette.grey[NEUTRAL_GRADIENT_STEPS.to] ?? '#212121',
+  ],
 };
 
 const gradientFor = (theme: Theme, color: ColorValue) => {
   const [from, to] = GRADIENT_STOPS[color](theme);
-  return `linear-gradient(135deg, ${from} 0%, ${to} 100%)`;
+  return headingGradient(from, to);
 };
 
 export interface HeadingFlags {
@@ -77,12 +80,8 @@ export interface HeadingFlags {
   gradient?: boolean;
 }
 
-/** A step name the scale actually has, or `h2` — the documented default. */
-const stepOf = (value: string | undefined): HeadingLevel =>
-  value !== undefined && value in HEADING_SCALE ? (value as HeadingLevel) : 'h2';
-
 export const headingSx = (theme: Theme, flags: HeadingFlags): CSSObject => {
-  const { customSize, customColor = 'neutral', customWeight = 'bold', gradient } = flags;
+  const { customSize, customColor = HEADING_DEFAULT_COLOR, customWeight = HEADING_DEFAULT_WEIGHT, gradient } = flags;
   // From the THEME, with the package default underneath — never from a table in
   // this file. A host's `createTheme({ typography: { headingScale } })` is what
   // sets the house scale now; see `tokens/typography.ts` for why it is our own
@@ -94,8 +93,7 @@ export const headingSx = (theme: Theme, flags: HeadingFlags): CSSObject => {
     margin: 0,
     transition: 'all 0.2s ease',
     ...metrics,
-    fontWeight:
-      customWeight === 'normal' ? normalWeight : (WEIGHTS[customWeight as Weight] ?? WEIGHTS.bold),
+    fontWeight: headingWeight(customWeight, normalWeight),
   };
 
   if (!gradient) {

package/src/components/typography/Heading/Heading.tsx

@@ -1,9 +1,11 @@
 import { styled } from '@mui/material/styles/index.js';
 import React from 'react';
 
+import { HEADING_DEFAULT_COLOR, HEADING_DEFAULT_LEVEL, HEADING_DEFAULT_WEIGHT, HEADING_RANK, stepOf } from './Heading.metrics';
 import { headingSx } from './Heading.styles';
 import type { HeadingFlags } from './Heading.styles';
 import type { HeadingProps } from './Heading.types';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
 
 const styledHeading = () =>
   styled('h1', {
@@ -26,38 +28,39 @@ const STYLED_BY_TAG = {
 } as const;
 
 /**
- * Which tag each level renders. `display` is a size, not a rank, so it uses the
- * h1 element — the document still gets one level-one heading rather than an
- * unnamed tag outside the outline.
- */
-const TAG_FOR_LEVEL: Record<string, keyof typeof STYLED_BY_TAG> = {
-  display: 'h1',
-  h1: 'h1',
-  h2: 'h2',
-  h3: 'h3',
-  h4: 'h4',
-  h5: 'h5',
-  h6: 'h6',
-};
-
-/**
- * The rank and the size were ALREADY independent in here — `TAG_FOR_LEVEL[level]`
- * and `customLevel={level}` are two separate derivations from one prop. The
- * component just never let a caller set them apart, so anyone who needed an
- * `h1` at a smaller size had to reach around the component and restyle it.
- * `size` is that seam, exposed: it defaults to `level`, so nothing that exists
- * renders differently.
+ * The rank and the size were ALREADY independent in here — the tag and the
+ * `customSize` are two separate derivations from one prop. The component just
+ * never let a caller set them apart, so anyone who needed an `h1` at a smaller
+ * size had to reach around the component and restyle it. `size` is that seam,
+ * exposed: it defaults to `level`, so nothing that exists renders differently.
+ *
+ * Which tag each level renders is `HEADING_RANK` in the shared metrics (the
+ * native `Heading` announces the same number as `aria-level`); `display` is a
+ * size, not a rank, so it uses the h1 element.
  */
 export const Heading = React.forwardRef<globalThis.HTMLHeadingElement, HeadingProps>(
   (
-    { level = 'h2', size, color = 'neutral', weight = 'bold', gradient = false, children, ...props },
+    {
+      level = HEADING_DEFAULT_LEVEL,
+      size,
+      color = HEADING_DEFAULT_COLOR,
+      weight = HEADING_DEFAULT_WEIGHT,
+      gradient = false,
+      children,
+      ...others
+    },
     ref,
   ) => {
-    const Styled = STYLED_BY_TAG[TAG_FOR_LEVEL[level] ?? 'h2'];
+    const Styled = STYLED_BY_TAG[`h${HEADING_RANK[stepOf(level)]}`];
+    // `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);
+    const props = withoutTestIdProps(others);
 
     return (
       <Styled
         ref={ref}
+        data-testid={testId}
         customSize={size ?? level}
         customColor={color}
         customWeight={weight}

package/src/components/typography/Heading/Heading.types.native.ts

@@ -0,0 +1,17 @@
+import type { GestureResponderEvent, StyleProp, TextProps as RNTextProps, TextStyle } from 'react-native';
+
+import type { HeadingBaseProps } from './Heading.base';
+
+export type { HeadingBaseProps, HeadingLevel, HeadingWeight } from './Heading.base';
+
+/**
+ * The native `Heading`: the shared contract, plus a react-native `Text`'s own
+ * props. `onClick` keeps its web name and `onPress` is accepted too, as on
+ * `Button`; both fire.
+ */
+export type HeadingProps = HeadingBaseProps &
+  Omit<RNTextProps, keyof HeadingBaseProps | 'style' | 'onPress'> & {
+    onClick?: (event: GestureResponderEvent) => void;
+    onPress?: (event: GestureResponderEvent) => void;
+    style?: StyleProp<TextStyle>;
+  };

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

@@ -1,44 +1,16 @@
-import type { HeadingLevel } from '../../../tokens/typography';
-import type { ColorValue } from '../../../tokens/scales';
 import type React from 'react';
 
+import type { HeadingBaseProps } from './Heading.base';
+
 /**
- * Re-exported, not re-declared. It was spelled out here AND (as `Level`) inside
- * `Heading.styles.ts`, so the union and the metrics table were two lists nothing
- * kept in step — the failure `tokens/scales.ts` was written to end.
+ * Re-exported, not re-declared. `HeadingLevel` was spelled out here AND (as
+ * `Level`) inside `Heading.styles.ts`, so the union and the metrics table were
+ * two lists nothing kept in step — the failure `tokens/scales.ts` was written
+ * to end.
  */
-export type { HeadingLevel };
+export type { HeadingBaseProps, HeadingLevel, HeadingWeight } from './Heading.base';
 
-export interface HeadingProps extends React.HTMLAttributes<globalThis.HTMLHeadingElement> {
-  /**
-   * The heading's RANK — which tag it renders and where it sits in the document
-   * outline. Not its size; see {@link HeadingProps.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;
-  weight?: 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
-  gradient?: boolean;
-  children: React.ReactNode;
-}
+/** The web `Heading`: the shared contract, plus everything an `<h1>`…`<h6>` accepts. */
+export interface HeadingProps
+  extends HeadingBaseProps,
+    Omit<React.HTMLAttributes<globalThis.HTMLHeadingElement>, 'color' | 'children'> {}

package/src/components/typography/Heading/NATIVE-NOTES.md

@@ -0,0 +1,3 @@
+# Heading on React Native — known gaps
+
+- `gradient` paints the gradient's first stop as a flat colour: React Native has no `background-clip: text` and no gradient fill in core. A host wanting the real thing adds a masked-gradient library.

package/src/components/typography/Heading/index.native.ts

@@ -0,0 +1,2 @@
+export { Heading, headingStyle } from './Heading.native';
+export type { HeadingBaseProps, HeadingLevel, HeadingProps, HeadingWeight } from './Heading.types.native';

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

@@ -1,2 +1,2 @@
 export { Heading } from './Heading';
-export type { HeadingLevel,HeadingProps } from './Heading.types';
+export type { HeadingBaseProps, HeadingLevel, HeadingProps, HeadingWeight } from './Heading.types';

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

@@ -0,0 +1,25 @@
+import type React from 'react';
+
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE CONTRACT BOTH `Paragraph` 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 `<p>`'s attributes in `Paragraph.types.ts`; the native side adds a
+ * react-native `Text`'s props in `Paragraph.types.native.ts`.
+ */
+export type ParagraphVariant = 'default' | 'lead' | 'muted' | 'small';
+
+export interface ParagraphBaseProps {
+  /** `lead` is larger and looser, `muted` faded, `small` a step down — all at the default size. */
+  variant?: ParagraphVariant;
+  /** Ignored by `muted` and `small`, which always paint the secondary ink. */
+  color?: ColorValue;
+  size?: SizeValue;
+  children: React.ReactNode;
+  testID?: string;
+  dataTestId?: string;
+}

package/src/components/typography/Paragraph/Paragraph.md

@@ -62,6 +62,17 @@ A semantic paragraph component with multiple visual variants for different conte
 </Paragraph>
 ```
 
+## React Native
+
+The same import renders natively (`@12-apps/ui/typography/Paragraph` resolves
+to `Paragraph.native.tsx` under Metro): a react-native `Text` styled from the
+same `Paragraph.metrics.ts` the web derives its rem strings from — the same
+five font sizes, the same line-height ratios multiplied out, the `1em` bottom
+margin as an absolute number. `testID`, `dataTestId` and `data-testid` all
+name the element; `onClick` and `onPress` both fire. There is no `<p>` on
+native, so the element carries no paragraph semantics. See
+[NATIVE.md](../../../../NATIVE.md).
+
 ## Accessibility Notes
 
 - Uses semantic `<p>` element for proper document structure

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

@@ -0,0 +1,41 @@
+import type { UiTypeStep } from '../../../tokens/theme';
+import type { SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE NUMBERS BOTH `Paragraph` RENDERERS DRAW WITH.
+ *
+ * `Paragraph.tsx` used to hold these as rem strings inside its styled
+ * callback, and `Paragraph.native.tsx` would have held them again as numbers.
+ * Now there is one table, in px, and the web derives its rem from it (`px()`
+ * in the theme). Ratios and `em` values stay relative; the native side
+ * multiplies them out because React Native's `lineHeight`, `letterSpacing` and
+ * margins are absolute.
+ *
+ * NOT `TYPE_SIZES`: a paragraph is set looser than `Text`'s body scale (1.6
+ * against 1.5 at `md`), because it is read in runs of lines rather than as a
+ * label. The font sizes are the same five steps.
+ */
+export const PARAGRAPH_SIZES: Record<SizeValue, UiTypeStep> = {
+  xs: { fontSize: 12, lineHeight: 1.4 },
+  sm: { fontSize: 14, lineHeight: 1.5 },
+  md: { fontSize: 16, lineHeight: 1.6 },
+  lg: { fontSize: 18, lineHeight: 1.6 },
+  xl: { fontSize: 20, lineHeight: 1.7 },
+};
+
+export const PARAGRAPH_FONT_WEIGHT = 400;
+
+/** `margin: 0 0 1em 0` — one line of its own type below each paragraph. */
+export const PARAGRAPH_MARGIN_BOTTOM_EM = 1;
+
+/** The `lead` variant: a step up at the default size, looser leading and tracking. */
+export const LEAD_FONT_SIZE = 18;
+export const LEAD_LINE_HEIGHT = 1.7;
+export const LEAD_LETTER_SPACING_EM = 0.01;
+
+/** The `muted` variant: the secondary ink, faded further. */
+export const MUTED_OPACITY = 0.8;
+
+/** The `small` variant: a step down at the default size, on the secondary ink. */
+export const SMALL_FONT_SIZE = 14;
+export const SMALL_LINE_HEIGHT = 1.5;

package/src/components/typography/Paragraph/Paragraph.native.tsx

@@ -0,0 +1,100 @@
+import * as React from 'react';
+import { Text as RNText, type GestureResponderEvent, type TextStyle } from 'react-native';
+
+import {
+  LEAD_FONT_SIZE,
+  LEAD_LETTER_SPACING_EM,
+  LEAD_LINE_HEIGHT,
+  MUTED_OPACITY,
+  PARAGRAPH_FONT_WEIGHT,
+  PARAGRAPH_MARGIN_BOTTOM_EM,
+  PARAGRAPH_SIZES,
+  SMALL_FONT_SIZE,
+  SMALL_LINE_HEIGHT,
+} from './Paragraph.metrics';
+import type { ParagraphProps, ParagraphVariant } from './Paragraph.types.native';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import type { UiTheme } from '../../../tokens/theme';
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+
+/** Same mapping as the web `getColorFromTheme`: neutral is body ink, every other colour its slot's main. */
+const inkFor = (theme: UiTheme, color: ColorValue): string =>
+  color === 'neutral' ? theme.palette.text.primary : theme.palette[color].main;
+
+/** `lead` and `small` step up or down relative to the scale, but only at the default size. */
+const sizeOverride = (size: SizeValue, atDefault: number): number =>
+  size === 'md' ? atDefault : PARAGRAPH_SIZES[size].fontSize;
+
+/** React Native wants the weight as a string. */
+const WEIGHT = String(PARAGRAPH_FONT_WEIGHT) as TextStyle['fontWeight'];
+
+export interface ParagraphStyleArgs {
+  variant: ParagraphVariant;
+  color: ColorValue;
+  size: SizeValue;
+}
+
+/**
+ * The style the web `Paragraph` computes, in absolute numbers. `lineHeight`,
+ * `letterSpacing` and the `1em` bottom margin are multiplied out here because
+ * React Native has no ratio or `em` unit — the web keeps them relative and the
+ * browser does this step.
+ */
+export function paragraphStyle(theme: UiTheme, a: ParagraphStyleArgs): TextStyle {
+  const step = PARAGRAPH_SIZES[a.size];
+  const metrics = (fontSize: number, lineHeight: number): TextStyle => ({
+    fontFamily: theme.typography.fontFamily,
+    fontSize,
+    lineHeight: fontSize * lineHeight,
+    marginBottom: fontSize * PARAGRAPH_MARGIN_BOTTOM_EM,
+    fontWeight: WEIGHT,
+  });
+
+  switch (a.variant) {
+    case 'lead': {
+      const fontSize = sizeOverride(a.size, LEAD_FONT_SIZE);
+      return {
+        ...metrics(fontSize, LEAD_LINE_HEIGHT),
+        color: inkFor(theme, a.color),
+        letterSpacing: LEAD_LETTER_SPACING_EM * fontSize,
+      };
+    }
+    case 'muted':
+      return {
+        ...metrics(step.fontSize, step.lineHeight),
+        color: theme.palette.text.secondary,
+        opacity: MUTED_OPACITY,
+      };
+    case 'small':
+      return {
+        ...metrics(sizeOverride(a.size, SMALL_FONT_SIZE), SMALL_LINE_HEIGHT),
+        color: theme.palette.text.secondary,
+      };
+    default:
+      return { ...metrics(step.fontSize, step.lineHeight), color: inkFor(theme, a.color) };
+  }
+}
+
+export const Paragraph = React.forwardRef<RNText, ParagraphProps>(
+  ({ variant = 'default', color = 'neutral', size = 'md', children, style, onClick, onPress, ...others }, ref) => {
+    const rest = withoutTestIdProps(others);
+    const theme = useUiTheme();
+    const resolved = React.useMemo(() => paragraphStyle(theme, { variant, color, size }), [theme, variant, color, size]);
+    const handlePress =
+      onClick || onPress
+        ? (event: GestureResponderEvent): void => {
+            onClick?.(event);
+            onPress?.(event);
+          }
+        : undefined;
+
+    return (
+      <RNText ref={ref} style={[resolved, style]} testID={resolveTestId(others)} onPress={handlePress} {...rest}>
+        {children}
+      </RNText>
+    );
+  },
+);
+
+Paragraph.displayName = 'Paragraph';