@12-apps/ui 6.17.0 → 6.18.0

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]);
+}

package/src/tokens/color.ts

@@ -0,0 +1,163 @@
+/**
+ * COLOUR ARITHMETIC WITH NO RENDERER BEHIND IT.
+ *
+ * Every shade the web components paint comes out of MUI's colour manipulator:
+ * `lighten(main, 0.2)` is a palette's `light`, `darken(main, 0.3)` its `dark`,
+ * `alpha(main, 0.1)` the hover wash on an outline button. A native component
+ * that wants the SAME pixel has to run the SAME arithmetic, and it cannot
+ * import it — `@mui/material/styles` drags emotion and the DOM in behind it.
+ *
+ * So the arithmetic lives here, once, with nothing behind it. It is a faithful
+ * port of `@mui/system/colorManipulator` (MIT), down to the truncation:
+ * `lighten('#6366F1', 0.2)` is `rgb(130, 132, 243)` on both sides because both
+ * TRUNCATE 132.6 rather than round it. A port that rounded would be one pixel
+ * of tint away from the web on every button, forever, and nothing would flag it.
+ *
+ * `color()` space strings are deliberately unsupported: nothing in this package
+ * emits one, and a smaller surface is a smaller thing to keep identical.
+ */
+
+export type ColorFormat = 'rgb' | 'rgba' | 'hsl' | 'hsla';
+
+export interface DecomposedColor {
+  type: ColorFormat;
+  values: number[];
+}
+
+const FORMATS: readonly ColorFormat[] = ['rgb', 'rgba', 'hsl', 'hsla'];
+
+const clamp = (value: number, min = 0, max = 1): number => Math.min(Math.max(min, value), max);
+
+/** `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` to its `rgb()` / `rgba()` string. */
+export function hexToRgb(color: string): string {
+  const hex = color.slice(1);
+  const pair = new RegExp(`.{1,${hex.length >= 6 ? 2 : 1}}`, 'g');
+  let channels: string[] | null = hex.match(pair);
+  if (channels && channels[0]?.length === 1) {
+    channels = channels.map((channel) => channel + channel);
+  }
+  if (!channels) return '';
+
+  const parts = channels.map((channel, index) =>
+    index < 3 ? parseInt(channel, 16) : Math.round((parseInt(channel, 16) / 255) * 1000) / 1000,
+  );
+  return `rgb${channels.length === 4 ? 'a' : ''}(${parts.join(', ')})`;
+}
+
+/** Any supported colour string to its type and numeric channels. */
+export function decomposeColor(color: string): DecomposedColor {
+  if (color.charAt(0) === '#') {
+    return decomposeColor(hexToRgb(color));
+  }
+
+  const marker = color.indexOf('(');
+  const type = color.substring(0, marker) as ColorFormat;
+  if (!FORMATS.includes(type)) {
+    throw new Error(
+      `@12-apps/ui: unsupported colour "${color}". Use #nnn, #nnnnnn, rgb(), rgba(), hsl() or hsla().`,
+    );
+  }
+
+  const values = color
+    .substring(marker + 1, color.length - 1)
+    .split(',')
+    .map((value) => parseFloat(value));
+
+  return { type, values };
+}
+
+/** The inverse of {@link decomposeColor}, with MUI's channel truncation. */
+export function recomposeColor({ type, values }: DecomposedColor): string {
+  const parts: Array<number | string> = type.startsWith('rgb')
+    ? values.map((value, index) => (index < 3 ? Math.trunc(value) : value))
+    : [values[0] ?? 0, `${values[1] ?? 0}%`, `${values[2] ?? 0}%`, ...values.slice(3)];
+
+  return `${type}(${parts.join(', ')})`;
+}
+
+/** An `hsl()` / `hsla()` string to its `rgb()` / `rgba()` equivalent. */
+export function hslToRgb(color: string): string {
+  const { type, values } = decomposeColor(color);
+  const h = values[0] ?? 0;
+  const s = (values[1] ?? 0) / 100;
+  const l = (values[2] ?? 0) / 100;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number, k = (n + h / 30) % 12): number =>
+    l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
+
+  const rgb = [Math.round(f(0) * 255), Math.round(f(8) * 255), Math.round(f(4) * 255)];
+  if (type === 'hsla') {
+    return recomposeColor({ type: 'rgba', values: [...rgb, values[3] ?? 1] });
+  }
+  return recomposeColor({ type: 'rgb', values: rgb });
+}
+
+/** Relative luminance (WCAG 2.0), to three decimals like MUI. */
+export function getLuminance(color: string): number {
+  const decomposed = decomposeColor(color);
+  const channels = decomposed.type.startsWith('hsl')
+    ? decomposeColor(hslToRgb(color)).values
+    : decomposed.values;
+
+  const [r, g, b] = channels.slice(0, 3).map((value) => {
+    const c = value / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+
+  return Number((0.2126 * (r ?? 0) + 0.7152 * (g ?? 0) + 0.0722 * (b ?? 0)).toFixed(3));
+}
+
+/** WCAG contrast ratio between two colours, 1 to 21. */
+export function getContrastRatio(foreground: string, background: string): number {
+  const lumA = getLuminance(foreground);
+  const lumB = getLuminance(background);
+  return (Math.max(lumA, lumB) + 0.05) / (Math.min(lumA, lumB) + 0.05);
+}
+
+/** The colour with its alpha channel set to `value` (0 to 1). */
+export function alpha(color: string, value: number): string {
+  const decomposed = decomposeColor(color);
+  const type: ColorFormat = decomposed.type.endsWith('a')
+    ? decomposed.type
+    : (`${decomposed.type}a` as ColorFormat);
+  const values = decomposed.values.slice(0, 3);
+  values[3] = clamp(value);
+  return recomposeColor({ type, values });
+}
+
+/** The colour moved `coefficient` (0 to 1) of the way towards black. */
+export function darken(color: string, coefficient: number): string {
+  const decomposed = decomposeColor(color);
+  const amount = clamp(coefficient);
+  const values = [...decomposed.values];
+
+  if (decomposed.type.startsWith('hsl')) {
+    values[2] = (values[2] ?? 0) * (1 - amount);
+  } else {
+    for (let index = 0; index < 3; index += 1) {
+      values[index] = (values[index] ?? 0) * (1 - amount);
+    }
+  }
+  return recomposeColor({ type: decomposed.type, values });
+}
+
+/** The colour moved `coefficient` (0 to 1) of the way towards white. */
+export function lighten(color: string, coefficient: number): string {
+  const decomposed = decomposeColor(color);
+  const amount = clamp(coefficient);
+  const values = [...decomposed.values];
+
+  if (decomposed.type.startsWith('hsl')) {
+    values[2] = (values[2] ?? 0) + (100 - (values[2] ?? 0)) * amount;
+  } else {
+    for (let index = 0; index < 3; index += 1) {
+      values[index] = (values[index] ?? 0) + (255 - (values[index] ?? 0)) * amount;
+    }
+  }
+  return recomposeColor({ type: decomposed.type, values });
+}
+
+/** Darken a light colour or lighten a dark one, by `coefficient`. */
+export function emphasize(color: string, coefficient = 0.15): string {
+  return getLuminance(color) > 0.5 ? darken(color, coefficient) : lighten(color, coefficient);
+}

package/src/tokens/css-units.ts

@@ -0,0 +1,28 @@
+/**
+ * THE ONE READER OF CSS LENGTHS.
+ *
+ * `HEADING_SCALE` and a host's MUI overrides speak CSS — `'2rem'`, `'-0.02em'`
+ * — and both `tokens/theme.ts` and `provider/mui-bridge.ts` need them as
+ * numbers. Two private parsers drifted (one multiplied `em` by 16, one did
+ * not), so there is one, here, with the rule spelled out: a length becomes px
+ * against a 16px root, a tracking value becomes em.
+ */
+
+const ROOT_PX = 16;
+
+/** `'1.5rem'` → 24, `'1.5em'` → 24, `'20px'` → 20, `20` → 20, unparseable → `fallback`. */
+export function cssLengthToPx(value: string | number | undefined, fallback: number): number {
+  if (typeof value === 'number') return value;
+  if (value === undefined) return fallback;
+  const parsed = Number.parseFloat(value);
+  if (Number.isNaN(parsed)) return fallback;
+  return value.endsWith('rem') || value.endsWith('em') ? parsed * ROOT_PX : parsed;
+}
+
+/** `'-0.02em'` → -0.02, `'0.5px'` → 0.5 / 16, `undefined` → `undefined` ("normal"). */
+export function cssTrackingToEm(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number.parseFloat(value);
+  if (Number.isNaN(parsed)) return undefined;
+  return value.endsWith('px') ? parsed / ROOT_PX : parsed;
+}

package/src/tokens/heading-scale.ts

@@ -0,0 +1,87 @@
+
+/**
+ * THE THIRD VOCABULARY: the type scale.
+ *
+ * `scales.ts` opens by saying the package had both halves of every argument at
+ * once until the size and colour vocabularies were declared in one place and
+ * every component derived from them. The type scale was the one that never got
+ * that treatment — it lived as a private `LEVELS` table inside
+ * `Heading.styles.ts`, which is exactly the shape that file exists to refuse.
+ *
+ * Two things follow from it being private, and the second is the expensive one.
+ *
+ * **It could not be re-themed.** `Heading` read `theme.typography.h1.fontFamily`
+ * from the theme and then ignored the theme for every other metric, so a host
+ * calling `createTheme({ typography: { h1: { fontSize: '2rem' } } })` changed
+ * `<Typography variant="h1">` and left `<Heading level="h1">` at 48px. A design
+ * system whose type scale cannot be set by the design is not a system.
+ *
+ * **And the numbers were a landing page's.** `h1` at 3rem and `h2` at 2.5rem are
+ * hero metrics. Dropped into an operations console they put a 48px title
+ * directly above 14px body copy — a 3.4x jump with nothing in between — so
+ * product teams stopped reaching for the component. Measured in one consuming
+ * repo: `<Heading>` appeared four times in the entire codebase while raw
+ * `fontSize` appeared in dozens of files. The component was not disliked, it was
+ * unusable at app scale, and every host paid for that in hand-rolled CSS.
+ *
+ * So the defaults below are an APP scale, and `display` keeps the hero size for
+ * the screens that actually want one. A marketing page asks for `display`; a
+ * console asks for `h1` and gets something it can put on a page.
+ */
+
+/**
+ * A step on the scale.
+ *
+ * `display` is a SIZE, not a rank — see `Heading`, which renders it as `h1` so
+ * the document still gets exactly one level-one heading.
+ */
+export type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'display';
+
+/**
+ * The runtime list, declared beside the union for the reason `SIZE_VALUES`
+ * gives: a story's `argTypes.options` spelled by hand drifts from the type, and
+ * the direction it drifts is "documents less than the component accepts".
+ */
+export const HEADING_LEVELS = [
+  'display',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+] as const satisfies readonly HeadingLevel[];
+
+/** Everything one step of the scale decides. */
+export interface HeadingMetrics {
+  fontSize: string;
+  lineHeight: number;
+  letterSpacing?: string;
+  /**
+   * The weight this step carries when the caller asks for `normal`. A heading's
+   * "normal" is not body text's 400 — it is the weight the step is meant to
+   * carry, which gets heavier as the step gets larger.
+   */
+  normalWeight: number;
+}
+
+/**
+ * The house default, in CODE rather than in a component.
+ *
+ * ~1.15x per step from a 1rem `h6`, which keeps six distinguishable ranks inside
+ * the range an application actually uses. The old table ran 1.125rem → 4rem and
+ * spent its top three steps above anything a product screen wants.
+ */
+export const HEADING_SCALE: Record<HeadingLevel, HeadingMetrics> = {
+  // The hero size the old `h1` was really offering, under the name that says so.
+  display: { fontSize: '3rem', lineHeight: 1.05, letterSpacing: '-0.03em', normalWeight: 800 },
+  h1: { fontSize: '2rem', lineHeight: 1.2, letterSpacing: '-0.02em', normalWeight: 700 },
+  h2: { fontSize: '1.75rem', lineHeight: 1.25, letterSpacing: '-0.015em', normalWeight: 700 },
+  h3: { fontSize: '1.5rem', lineHeight: 1.3, letterSpacing: '-0.01em', normalWeight: 600 },
+  h4: { fontSize: '1.25rem', lineHeight: 1.35, letterSpacing: '-0.005em', normalWeight: 600 },
+  h5: { fontSize: '1.125rem', lineHeight: 1.4, normalWeight: 600 },
+  h6: { fontSize: '1rem', lineHeight: 1.5, normalWeight: 600 },
+};
+
+/** A host's overrides: any subset of the steps, any subset of each step's metrics. */
+export type HeadingScaleOverrides = Partial<Record<HeadingLevel, Partial<HeadingMetrics>>>;

package/src/tokens/index.native.ts

@@ -0,0 +1,9 @@
+/**
+ * `@12-apps/ui/tokens` on React Native: the vocabulary, the type scale, the
+ * theme and the colour arithmetic. NOT `accentFor` or `headingMetrics`, which
+ * read a MUI `Theme` and belong to the web build — a native component reads
+ * `useUiTheme()` from `@12-apps/ui/provider` instead.
+ */
+export * from './vocabulary';
+export * from './theme';
+export * from './color';