@12-apps/ui 6.17.1 → 6.18.0

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,14 @@
+import type * as React from 'react';
+
+import type { BoxBaseProps } from '../Box/Box.base';
+
+/**
+ * A `Box` that is always a flex container, with an optional divider between
+ * children — MUI's `Stack`, on the neutral prop set. `direction` defaults to
+ * `column` and `gap` to `0`, as MUI's does.
+ */
+export interface StackBaseProps extends Omit<BoxBaseProps, 'direction'> {
+  direction?: 'row' | 'column';
+  /** Rendered between every pair of children. */
+  divider?: React.ReactNode;
+}

package/src/components/layout/Stack/Stack.md

@@ -0,0 +1,19 @@
+# Stack
+
+A `Box` that is always a flex container, with an optional divider between
+children — MUI's `Stack` on the neutral prop set, so it renders on both the web
+and React Native.
+
+```tsx
+import { Stack } from '@12-apps/ui/layout/Stack';
+
+<Stack direction="row" gap={2} align="center" divider={<Box width={1} bg="neutral" />}>
+  …
+</Stack>
+```
+
+`direction` defaults to `column` and `gap` to `0`, as MUI's does. Every other
+prop is `Box`'s (see `layout/Box`). `divider` is cloned between each adjacent
+pair of children and never outside them.
+
+`@12-apps/ui/mui/Stack` remains raw MUI and web-only.

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

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import type { View } from 'react-native';
+
+import type { StackProps } from './Stack.types.native';
+import { withDividers } from './with-dividers';
+import { Box } from '../Box/Box.native';
+
+export const Stack = React.forwardRef<View, StackProps>(
+  ({ direction = 'column', gap = 0, divider, children, ...rest }, ref) => (
+    <Box ref={ref} direction={direction} gap={gap} {...rest}>
+      {withDividers(children, divider)}
+    </Box>
+  ),
+);
+
+Stack.displayName = 'Stack';

package/src/components/layout/Stack/Stack.tsx

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+import type { StackProps } from './Stack.types';
+import { withDividers } from './with-dividers';
+import { Box } from '../Box/Box';
+
+export const Stack = React.forwardRef<HTMLDivElement, StackProps>(
+  ({ direction = 'column', gap = 0, divider, children, ...rest }, ref) => (
+    <Box ref={ref} direction={direction} gap={gap} {...rest}>
+      {withDividers(children, divider)}
+    </Box>
+  ),
+);
+
+Stack.displayName = 'Stack';

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

@@ -0,0 +1,6 @@
+import type { StackBaseProps } from './Stack.base';
+import type { BoxProps } from '../Box/Box.types.native';
+
+export type { StackBaseProps } from './Stack.base';
+
+export type StackProps = StackBaseProps & Omit<BoxProps, keyof StackBaseProps>;

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

@@ -0,0 +1,6 @@
+import type { StackBaseProps } from './Stack.base';
+import type { BoxProps } from '../Box/Box.types';
+
+export type { StackBaseProps } from './Stack.base';
+
+export type StackProps = StackBaseProps & Omit<BoxProps, keyof StackBaseProps>;

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

@@ -0,0 +1,2 @@
+export { Stack } from './Stack.native';
+export type { StackBaseProps, StackProps } from './Stack.types.native';

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

@@ -0,0 +1,2 @@
+export { Stack } from './Stack';
+export type { StackBaseProps, StackProps } from './Stack.types';

package/src/components/layout/Stack/with-dividers.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+/** The children with `divider` cloned between each adjacent pair. */
+export function withDividers(
+  children: React.ReactNode,
+  divider: React.ReactNode | undefined,
+): React.ReactNode {
+  if (divider === undefined || divider === null) return children;
+  const items = React.Children.toArray(children);
+  return items.flatMap((child, index) =>
+    index === 0
+      ? [child]
+      : [React.createElement(React.Fragment, { key: `divider-${index}` }, divider), child],
+  );
+}

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

@@ -0,0 +1,25 @@
+import type React from 'react';
+
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+
+/** The contract both renderers honour; see `Button.base.ts` for why it is its own file. */
+export type TextVariant = 'body' | 'heading' | 'caption' | 'code';
+export type TextWeight = 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
+
+/**
+ * The contract both renderers honour. Nothing here names a DOM or a React
+ * Native type: the web adds `HTMLAttributes` and `as` below, the native side
+ * adds `TextProps` from react-native in `Text.types.native.ts`.
+ */
+export interface TextBaseProps {
+  variant?: TextVariant;
+  color?: ColorValue;
+  size?: SizeValue;
+  weight?: TextWeight;
+  italic?: boolean;
+  underline?: boolean;
+  strikethrough?: boolean;
+  children: React.ReactNode;
+  testID?: string;
+  dataTestId?: string;
+}

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

@@ -0,0 +1,30 @@
+import { FONT_WEIGHTS, TYPE_SIZES } from '../../../tokens/theme';
+
+/**
+ * THE NUMBERS BOTH `Text` RENDERERS DRAW WITH.
+ *
+ * `Text.tsx` used to hold these as rem strings and `Text.native.tsx` would have
+ * held them again as numbers — two tables, one of which drifts. Now there is
+ * one, in px, and the web derives its rem from it (see `px()` in the theme).
+ * Ratios stay ratios; the native side multiplies them out because React
+ * Native's `lineHeight` and `letterSpacing` are absolute.
+ */
+export const TEXT_SIZES = TYPE_SIZES;
+export const TEXT_WEIGHTS = FONT_WEIGHTS;
+
+/** The `heading` variant: heavier by default, tighter tracking. */
+export const HEADING_DEFAULT_WEIGHT = 600;
+export const HEADING_LETTER_SPACING_EM = -0.01;
+
+/** The `caption` variant: a step down at the default size, faded and looser. */
+export const CAPTION_FONT_SIZE = 12;
+export const CAPTION_OPACITY = 0.8;
+export const CAPTION_LETTER_SPACING_EM = 0.02;
+
+/** The `code` variant: a step down, on a faint primary wash inside a hairline. */
+export const CODE_FONT_SIZE = 14;
+export const CODE_BACKGROUND_ALPHA = 0.08;
+export const CODE_BORDER_ALPHA = 0.12;
+export const CODE_PADDING = { vertical: 2, horizontal: 6 } as const;
+/** Half the theme's `md` radius, as `Text.tsx` has always drawn it. */
+export const CODE_RADIUS_FACTOR = 0.5;

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

@@ -0,0 +1,149 @@
+import * as React from 'react';
+import { Platform, Text as RNText, type TextStyle } from 'react-native';
+
+import {
+  CAPTION_FONT_SIZE,
+  CAPTION_LETTER_SPACING_EM,
+  CAPTION_OPACITY,
+  CODE_BACKGROUND_ALPHA,
+  CODE_BORDER_ALPHA,
+  CODE_FONT_SIZE,
+  CODE_PADDING,
+  CODE_RADIUS_FACTOR,
+  HEADING_DEFAULT_WEIGHT,
+  HEADING_LETTER_SPACING_EM,
+  TEXT_SIZES,
+  TEXT_WEIGHTS,
+} from './Text.metrics';
+import type { TextProps, TextVariant, TextWeight } from './Text.types.native';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+import { alpha } from '../../../tokens/color';
+import type { UiTheme } from '../../../tokens/theme';
+
+/** Same mapping as the web `getColorFromTheme`: neutral is body ink, secondary the muted ink. */
+const inkFor = (theme: UiTheme, color: ColorValue): string => {
+  if (color === 'neutral') return theme.palette.text.primary;
+  if (color === 'secondary') return theme.palette.text.secondary;
+  return theme.palette[color].main;
+};
+
+/** React Native wants the weight as a string. */
+const weightOf = (weight: number): TextStyle['fontWeight'] => String(weight) as TextStyle['fontWeight'];
+
+/** Captions and code shrink relative to the body scale, but only at the default size. */
+const sizeOverride = (size: SizeValue, atDefault: number): number =>
+  size === 'md' ? atDefault : TEXT_SIZES[size].fontSize;
+
+const decoration = (underline: boolean, strikethrough: boolean): TextStyle['textDecorationLine'] => {
+  if (underline && strikethrough) return 'underline line-through';
+  if (underline) return 'underline';
+  return strikethrough ? 'line-through' : 'none';
+};
+
+interface TextStyleArgs {
+  variant: TextVariant;
+  color: ColorValue;
+  size: SizeValue;
+  weight: TextWeight;
+  italic: boolean;
+  underline: boolean;
+  strikethrough: boolean;
+}
+
+const monospace = (theme: UiTheme): string | undefined =>
+  theme.typography.monospaceFontFamily ?? Platform.select({ ios: 'Menlo', android: 'monospace', default: 'monospace' });
+
+/**
+ * The style the web `Text` computes, in absolute numbers. `lineHeight` and
+ * `letterSpacing` 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 textStyle(theme: UiTheme, a: TextStyleArgs): TextStyle {
+  const step = TEXT_SIZES[a.size];
+  const base: TextStyle = {
+    color: inkFor(theme, a.color),
+    fontFamily: theme.typography.fontFamily,
+    fontSize: step.fontSize,
+    lineHeight: step.fontSize * step.lineHeight,
+    fontWeight: weightOf(TEXT_WEIGHTS[a.weight]),
+    fontStyle: a.italic ? 'italic' : 'normal',
+    textDecorationLine: decoration(a.underline, a.strikethrough),
+  };
+
+  switch (a.variant) {
+    case 'heading':
+      return {
+        ...base,
+        fontWeight: weightOf(a.weight === 'normal' ? HEADING_DEFAULT_WEIGHT : TEXT_WEIGHTS[a.weight]),
+        letterSpacing: HEADING_LETTER_SPACING_EM * step.fontSize,
+      };
+    case 'caption': {
+      const fontSize = sizeOverride(a.size, CAPTION_FONT_SIZE);
+      return {
+        ...base,
+        fontSize,
+        lineHeight: fontSize * step.lineHeight,
+        opacity: CAPTION_OPACITY,
+        letterSpacing: CAPTION_LETTER_SPACING_EM * fontSize,
+      };
+    }
+    case 'code': {
+      const fontSize = sizeOverride(a.size, CODE_FONT_SIZE);
+      return {
+        ...base,
+        fontFamily: monospace(theme),
+        fontSize,
+        lineHeight: fontSize * step.lineHeight,
+        backgroundColor: alpha(theme.palette.primary.main, CODE_BACKGROUND_ALPHA),
+        paddingVertical: CODE_PADDING.vertical,
+        paddingHorizontal: CODE_PADDING.horizontal,
+        borderRadius: theme.radius.md * CODE_RADIUS_FACTOR,
+        borderWidth: 1,
+        borderColor: alpha(theme.palette.primary.main, CODE_BORDER_ALPHA),
+      };
+    }
+    default:
+      return base;
+  }
+}
+
+export const Text = React.forwardRef<RNText, TextProps>(
+  (
+    {
+      variant = 'body',
+      color = 'neutral',
+      size = 'md',
+      weight = 'normal',
+      italic = false,
+      underline = false,
+      strikethrough = false,
+      children,
+      style,
+      ...others
+    },
+    ref,
+  ) => {
+    const rest = withoutTestIdProps(others);
+    const theme = useUiTheme();
+    const resolved = React.useMemo(
+      () => textStyle(theme, { variant, color, size, weight, italic, underline, strikethrough }),
+      [theme, variant, color, size, weight, italic, underline, strikethrough],
+    );
+
+    return (
+      <RNText
+        ref={ref}
+        style={[resolved, style]}
+        testID={resolveTestId(others)}
+        role={variant === 'heading' ? 'heading' : undefined}
+        {...rest}
+      >
+        {children}
+      </RNText>
+    );
+  },
+);
+
+Text.displayName = 'Text';