@12-apps/ui 6.17.1 → 6.18.0

package/src/tokens/theme.ts

@@ -0,0 +1,334 @@
+import { darken, getContrastRatio, lighten } from './color';
+import { cssLengthToPx, cssTrackingToEm } from './css-units';
+import { HEADING_SCALE, type HeadingLevel } from './heading-scale';
+
+import type { SizeValue } from './vocabulary';
+
+/**
+ * THE THEME BOTH RENDERERS READ.
+ *
+ * On the web every component styles itself from MUI's `Theme`, which is built
+ * by the host (`@12-apps/app-shell`'s `createAppTheme` in the origin apps) and
+ * reaches a component through emotion's context. React Native has no emotion,
+ * no CSS and no MUI, so a native `Button` needs the same decisions — the
+ * palette, the spacing unit, the radius, the type scale — from somewhere that
+ * does not import a renderer.
+ *
+ * This is that somewhere. `UiTheme` is a plain object of numbers and colour
+ * strings. `createUiTheme` derives it the way MUI's `createPalette` derives its
+ * own: a `light` shade is `lighten(main, 0.2)`, a `dark` shade `darken(main,
+ * 0.3)`, `contrastText` flips at a 3:1 ratio against `rgba(0, 0, 0, 0.87)`.
+ * Same seeds in, same shades out, on both sides — that is the whole basis for
+ * a native button being the web button's colour and not a near miss.
+ *
+ * Numbers are in px on the web and dp on native; both are the CSS-pixel unit
+ * a design is drawn in, so a `fontSize: 16` here IS `1rem` in a web style
+ * and `16` in a `StyleSheet`. The web components keep their `rem` strings and
+ * derive them from these numbers where the two meet (see `px()` below and the
+ * `*.metrics.ts` file beside each ported component).
+ *
+ * `danger` and `neutral` are this package's names (see `./scales`); `danger`
+ * is MUI's `error` and `neutral` is drawn from the grey ramp the way
+ * `Button.styles.ts` has always drawn it.
+ */
+
+export type UiThemeMode = 'light' | 'dark';
+
+export interface UiPaletteColor {
+  main: string;
+  light: string;
+  dark: string;
+  contrastText: string;
+}
+
+export type UiGreyStep = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+
+export interface UiPalette {
+  mode: UiThemeMode;
+  primary: UiPaletteColor;
+  secondary: UiPaletteColor;
+  success: UiPaletteColor;
+  warning: UiPaletteColor;
+  info: UiPaletteColor;
+  danger: UiPaletteColor;
+  neutral: UiPaletteColor;
+  text: { primary: string; secondary: string; disabled: string };
+  background: { default: string; paper: string };
+  divider: string;
+  action: {
+    active: string;
+    hover: string;
+    selected: string;
+    disabled: string;
+    disabledBackground: string;
+    focus: string;
+  };
+  grey: Record<UiGreyStep, string>;
+}
+
+/** One step of the body scale: `fontSize` in px, `lineHeight` as a ratio. */
+export interface UiTypeStep {
+  fontSize: number;
+  lineHeight: number;
+}
+
+export type UiFontWeight = 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
+
+export interface UiHeadingStep extends UiTypeStep {
+  /** In em, so it scales with the step. `undefined` is "normal". */
+  letterSpacing?: number;
+  normalWeight: number;
+}
+
+export interface UiTypography {
+  /**
+   * Native has no fallback stacks: a font is either installed and named, or
+   * `undefined` and the platform's own. The web default is MUI's Roboto stack.
+   */
+  fontFamily: string | undefined;
+  monospaceFontFamily: string | undefined;
+  sizes: Record<SizeValue, UiTypeStep>;
+  weights: Record<UiFontWeight, number>;
+  heading: Record<HeadingLevel, UiHeadingStep>;
+}
+
+export interface UiTheme {
+  mode: UiThemeMode;
+  palette: UiPalette;
+  /** MUI's `theme.spacing(n)`: `n` units of {@link UiTheme.spacingUnit}, in px. */
+  spacing: (units: number) => number;
+  spacingUnit: number;
+  /** `md` is MUI's `shape.borderRadius`; the others are its halves and doubles. */
+  radius: { sm: number; md: number; lg: number; xl: number; full: number };
+  typography: UiTypography;
+  zIndex: { appBar: number; drawer: number; modal: number; snackbar: number; tooltip: number };
+}
+
+/** A seed for one palette slot: a hex `main`, or any subset of the four shades. */
+export type UiPaletteSeed = string | Partial<UiPaletteColor>;
+
+export interface UiThemeOptions {
+  mode?: UiThemeMode;
+  palette?: Partial<{
+    primary: UiPaletteSeed;
+    secondary: UiPaletteSeed;
+    success: UiPaletteSeed;
+    warning: UiPaletteSeed;
+    info: UiPaletteSeed;
+    danger: UiPaletteSeed;
+    background: Partial<UiPalette['background']>;
+  }>;
+  typography?: Partial<Pick<UiTypography, 'fontFamily' | 'monospaceFontFamily'>>;
+  spacingUnit?: number;
+}
+
+const ROOT_FONT_PX = 16;
+
+/** The px value as the rem string the web components write. */
+export const px = (value: number): string => `${value / ROOT_FONT_PX}rem`;
+
+/** MUI's `createPalette` defaults, exactly. */
+const TONAL_OFFSET = 0.2;
+const CONTRAST_THRESHOLD = 3;
+const DARK_TEXT_PRIMARY = 'rgba(0, 0, 0, 0.87)';
+const LIGHT_TEXT_PRIMARY = '#fff';
+
+export const GREY: Record<UiGreyStep, string> = {
+  50: '#fafafa',
+  100: '#f5f5f5',
+  200: '#eeeeee',
+  300: '#e0e0e0',
+  400: '#bdbdbd',
+  500: '#9e9e9e',
+  600: '#757575',
+  700: '#616161',
+  800: '#424242',
+  900: '#212121',
+};
+
+/**
+ * The platform's own seeds. The pair `@12-apps/ui`'s Storybook preview and
+ * `@12-apps/app-shell`'s `DEFAULT_THEME_TOKENS` both carry — keep the three in
+ * step if the design tokens change.
+ */
+export const DEFAULT_BRAND: Record<UiThemeMode, { primary: string; secondary: string }> = {
+  light: { primary: '#6366F1', secondary: '#8B5CF6' },
+  dark: { primary: '#818CF8', secondary: '#A78BFA' },
+};
+
+/** MUI's semantic defaults per mode. These are declared shades, not derived. */
+const SEMANTIC_DEFAULTS: Record<
+  UiThemeMode,
+  Record<'success' | 'warning' | 'info' | 'danger', UiPaletteColor>
+> = {
+  light: {
+    success: { main: '#2e7d32', light: '#4caf50', dark: '#1b5e20', contrastText: '#fff' },
+    warning: { main: '#ed6c02', light: '#ff9800', dark: '#e65100', contrastText: '#fff' },
+    info: { main: '#0288d1', light: '#03a9f4', dark: '#01579b', contrastText: '#fff' },
+    danger: { main: '#d32f2f', light: '#ef5350', dark: '#c62828', contrastText: '#fff' },
+  },
+  dark: {
+    success: { main: '#66bb6a', light: '#81c784', dark: '#388e3c', contrastText: DARK_TEXT_PRIMARY },
+    warning: { main: '#ffa726', light: '#ffb74d', dark: '#f57c00', contrastText: DARK_TEXT_PRIMARY },
+    info: { main: '#29b6f6', light: '#4fc3f7', dark: '#0288d1', contrastText: DARK_TEXT_PRIMARY },
+    danger: { main: '#f44336', light: '#e57373', dark: '#d32f2f', contrastText: '#fff' },
+  },
+};
+
+const MODE_DEFAULTS: Record<
+  UiThemeMode,
+  Pick<UiPalette, 'text' | 'background' | 'divider' | 'action'>
+> = {
+  light: {
+    text: { primary: DARK_TEXT_PRIMARY, secondary: 'rgba(0, 0, 0, 0.6)', disabled: 'rgba(0, 0, 0, 0.38)' },
+    background: { default: '#fff', paper: '#fff' },
+    divider: 'rgba(0, 0, 0, 0.12)',
+    action: {
+      active: 'rgba(0, 0, 0, 0.54)',
+      hover: 'rgba(0, 0, 0, 0.04)',
+      selected: 'rgba(0, 0, 0, 0.08)',
+      disabled: 'rgba(0, 0, 0, 0.26)',
+      disabledBackground: 'rgba(0, 0, 0, 0.12)',
+      focus: 'rgba(0, 0, 0, 0.12)',
+    },
+  },
+  dark: {
+    text: { primary: '#fff', secondary: 'rgba(255, 255, 255, 0.7)', disabled: 'rgba(255, 255, 255, 0.5)' },
+    background: { default: '#121212', paper: '#121212' },
+    divider: 'rgba(255, 255, 255, 0.12)',
+    action: {
+      active: '#fff',
+      hover: 'rgba(255, 255, 255, 0.08)',
+      selected: 'rgba(255, 255, 255, 0.16)',
+      disabled: 'rgba(255, 255, 255, 0.3)',
+      disabledBackground: 'rgba(255, 255, 255, 0.12)',
+      focus: 'rgba(255, 255, 255, 0.12)',
+    },
+  },
+};
+
+/**
+ * MUI's `getContrastText`: white where white reads at 3:1 on the colour, the
+ * light mode's dark ink otherwise. (MUI's source spells the white as the DARK
+ * palette's `text.primary`, which is what made it easy to read backwards.)
+ */
+export function contrastText(background: string): string {
+  return getContrastRatio(background, LIGHT_TEXT_PRIMARY) >= CONTRAST_THRESHOLD
+    ? LIGHT_TEXT_PRIMARY
+    : DARK_TEXT_PRIMARY;
+}
+
+/**
+ * MUI's `augmentColor` for a custom colour: derive whatever shade the seed
+ * left out. `light` is one tonal offset up, `dark` one and a half down.
+ */
+export function augmentColor(seed: UiPaletteSeed): UiPaletteColor {
+  const partial = typeof seed === 'string' ? { main: seed } : seed;
+  const main = partial.main ?? partial.light ?? partial.dark;
+  if (!main) {
+    throw new Error('@12-apps/ui: a palette seed needs at least a `main` colour.');
+  }
+  return {
+    main,
+    light: partial.light ?? lighten(main, TONAL_OFFSET),
+    dark: partial.dark ?? darken(main, TONAL_OFFSET * 1.5),
+    contrastText: partial.contrastText ?? contrastText(main),
+  };
+}
+
+const semantic = (
+  mode: UiThemeMode,
+  key: 'success' | 'warning' | 'info' | 'danger',
+  seed: UiPaletteSeed | undefined,
+): UiPaletteColor => (seed === undefined ? SEMANTIC_DEFAULTS[mode][key] : augmentColor(seed));
+
+/** `neutral` as `accentFor` in `./scales` has always drawn it: three greys and white. */
+export const NEUTRAL: UiPaletteColor = {
+  main: GREY[600],
+  light: GREY[400],
+  dark: GREY[800],
+  contrastText: '#fff',
+};
+
+/** The body scale `Text` renders, in px. `Text.tsx`'s rem map is this, divided by 16. */
+export const TYPE_SIZES: Record<SizeValue, UiTypeStep> = {
+  xs: { fontSize: 12, lineHeight: 1.2 },
+  sm: { fontSize: 14, lineHeight: 1.3 },
+  md: { fontSize: 16, lineHeight: 1.5 },
+  lg: { fontSize: 18, lineHeight: 1.4 },
+  xl: { fontSize: 20, lineHeight: 1.3 },
+};
+
+export const FONT_WEIGHTS: Record<UiFontWeight, number> = {
+  light: 300,
+  normal: 400,
+  medium: 500,
+  semibold: 600,
+  bold: 700,
+};
+
+// `HEADING_SCALE` speaks CSS, this theme speaks numbers; `./css-units` is the
+// one place that conversion is written.
+const HEADING_STEPS = Object.fromEntries(
+  Object.entries(HEADING_SCALE).map(([level, metrics]) => [
+    level,
+    {
+      fontSize: cssLengthToPx(metrics.fontSize, ROOT_FONT_PX),
+      lineHeight: metrics.lineHeight,
+      letterSpacing: cssTrackingToEm(metrics.letterSpacing),
+      normalWeight: metrics.normalWeight,
+    },
+  ]),
+) as Record<HeadingLevel, UiHeadingStep>;
+
+export const WEB_FONT_FAMILY = '"Roboto", "Helvetica", "Arial", sans-serif';
+export const WEB_MONOSPACE_FONT_FAMILY = 'Monaco, Menlo, "Ubuntu Mono", "Courier New", monospace';
+
+/**
+ * Build the theme. Every field is derived here so a host that changes one
+ * seed gets every dependent shade recomputed, on both renderers, identically.
+ */
+export function createUiTheme(options: UiThemeOptions = {}): UiTheme {
+  const mode = options.mode ?? 'light';
+  const seeds = options.palette ?? {};
+  const brand = DEFAULT_BRAND[mode];
+  const defaults = MODE_DEFAULTS[mode];
+  const spacingUnit = options.spacingUnit ?? 8;
+
+  const palette: UiPalette = {
+    mode,
+    primary: augmentColor(seeds.primary ?? brand.primary),
+    secondary: augmentColor(seeds.secondary ?? brand.secondary),
+    success: semantic(mode, 'success', seeds.success),
+    warning: semantic(mode, 'warning', seeds.warning),
+    info: semantic(mode, 'info', seeds.info),
+    danger: semantic(mode, 'danger', seeds.danger),
+    neutral: NEUTRAL,
+    text: defaults.text,
+    background: { ...defaults.background, ...seeds.background },
+    divider: defaults.divider,
+    action: defaults.action,
+    grey: GREY,
+  };
+
+  return {
+    mode,
+    palette,
+    spacing: (units: number) => units * spacingUnit,
+    spacingUnit,
+    radius: { sm: 2, md: 4, lg: 8, xl: 16, full: 9999 },
+    typography: {
+      fontFamily: options.typography?.fontFamily,
+      monospaceFontFamily: options.typography?.monospaceFontFamily,
+      sizes: TYPE_SIZES,
+      weights: FONT_WEIGHTS,
+      heading: HEADING_STEPS,
+    },
+    zIndex: { appBar: 1100, drawer: 1200, modal: 1300, snackbar: 1400, tooltip: 1500 },
+  };
+}
+
+/** The palette slot a house colour name resolves to. */
+export type UiPaletteKey = 'primary' | 'secondary' | 'success' | 'warning' | 'info' | 'danger' | 'neutral';
+
+export const DEFAULT_UI_THEME: UiTheme = createUiTheme();

package/src/tokens/typography.ts

@@ -1,91 +1,14 @@
 import type { Theme } from '@mui/material/styles/index.js';
 
-/**
- * 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';
+import { HEADING_SCALE, type HeadingLevel, type HeadingMetrics, type HeadingScaleOverrides } from './heading-scale';
 
 /**
- * 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".
+ * The MUI half of the type scale: the theme augmentation and the reader that
+ * merges a host's overrides. The scale itself is in `./heading-scale`, which
+ * imports nothing, so `src/tokens/theme.ts` and the native renderer read it
+ * without dragging MUI's `Theme` into `dist/types-native`.
  */
-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>>>;
+export * from './heading-scale';
 
 /**
  * The theme channel, under our OWN key rather than MUI's `typography.h1…h6`.

package/src/tokens/vocabulary.ts

@@ -0,0 +1,189 @@
+/**
+ * THE TWO VOCABULARIES EVERY COMPONENT SPEAKS.
+ *
+ * Before this file the package had both halves of every argument at once: 26
+ * components sized themselves `xs|sm|md|lg|xl` and four used MUI's
+ * `small|medium|large`; 14 coloured themselves `danger|neutral` and 15 used
+ * MUI's `error`. Nothing enforced either, because most of these props were
+ * spelled out as inline unions and a couple were plain `string`.
+ *
+ * That is not a tidiness problem. A caller learns the vocabulary from whichever
+ * component they used first, and the wrong half is not rejected — it reaches MUI
+ * as an unknown value and silently falls back. `Chip` shipped with `color?:
+ * string` and MUI's `small|medium`, so `color="danger"` rendered grey and
+ * `size="sm"` rendered medium; twelve live call sites were doing exactly that,
+ * and every test passed because they all asserted on text.
+ *
+ * So the vocabulary is declared once, here, and components derive from it.
+ *
+ * DERIVE, DON'T COPY — AND TAKE THE WHOLE VOCABULARY. Every size prop is
+ * `SizeValue` and every colour prop is `ColorValue`, with no `Extract` and no
+ * `Exclude`. Handing a component a slice was tried and undone: it is the same
+ * fragmentation wearing the canonical type's name, and it leaves a caller having
+ * to remember which components accept `xs` and which accept `info`. Where the
+ * underlying widget draws fewer steps than five, that is a rendering detail and
+ * belongs at the MUI boundary below — not in the prop's type.
+ *
+ * A component whose size or colour is not this concept at all keeps its own type
+ * — `Scrollbar`'s `thin|medium|thick` is a track width, `Sheet`'s `full` is a
+ * viewport fraction, `LazyImage`'s size is pixels. Forcing those into the scale
+ * would be consistency for its own sake.
+ */
+
+/**
+ * The house size scale.
+ *
+ * Abbreviated, because that is what 26 of the 30 components with a real size
+ * already used and what every caller has been taught to write.
+ *
+ * Declared as the array and the type together so the two cannot disagree. The
+ * runtime list is what Storybook `argTypes.options` and the demo grids iterate;
+ * spelled by hand in each story it drifts, and it had — twelve colour lists
+ * omitted `info`, so the control that documents the vocabulary offered a
+ * component less than the component accepted.
+ */
+/**
+ * The type scale is the THIRD vocabulary, and it lives in `./typography.ts`
+ * because it is metrics rather than a prop union. Re-exported here so
+ * `@12-apps/ui/tokens` stays the one import path for "what words does this
+ * package speak" — a second entry point is how a vocabulary gets missed.
+ */
+export {
+  HEADING_LEVELS,
+  HEADING_SCALE,
+  type HeadingLevel,
+  type HeadingMetrics,
+  type HeadingScaleOverrides,
+} from './heading-scale';
+
+export type SizeValue = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export const SIZE_VALUES = ['xs', 'sm', 'md', 'lg', 'xl'] as const satisfies readonly SizeValue[];
+
+/**
+ * The house colour vocabulary.
+ *
+ * `danger` and `neutral` are OURS; the rest are MUI's own names already. That
+ * sentence started life in `Button.tsx`, which is the component most callers
+ * meet first and therefore the one that taught the vocabulary — so it is the one
+ * the rest of the package follows.
+ *
+ * Components that hand these to MUI translate at the boundary (`danger` →
+ * `error`, `neutral` → `default` or `inherit` depending on what the underlying
+ * component calls its unaccented state). The translation must be a real mapping
+ * and never a cast: a cast is precisely what let `danger` through untouched and
+ * had MUI fall back to grey.
+ *
+ * Array and type declared together, for the reason given on {@link SIZE_VALUES}.
+ */
+export type ColorValue =
+  | 'primary'
+  | 'secondary'
+  | 'success'
+  | 'warning'
+  | 'info'
+  | 'danger'
+  | 'neutral';
+
+export const COLOR_VALUES = [
+  'primary',
+  'secondary',
+  'success',
+  'warning',
+  'info',
+  'danger',
+  'neutral',
+] as const satisfies readonly ColorValue[];
+
+/* ── Array and union, pinned to each other ────────────────────────────────── */
+
+/**
+ * The arrays above are written out rather than derived, because deriving the
+ * union from the array (`(typeof COLOR_VALUES)[number]`) costs the alias its
+ * name: TypeScript resolves the indexed access eagerly, and every error in the
+ * package stops saying `not assignable to type 'ColorValue'` and starts dumping
+ * seven string literals. In a package whose entire purpose is teaching this
+ * vocabulary, the name in the error message is worth keeping.
+ *
+ * Writing both means they could disagree, so both directions are checked here.
+ * `satisfies` above catches an entry that is not a member. These catch the other
+ * half — a member missing from the array — which `satisfies` cannot see and
+ * which is the direction that actually bit: twelve story control lists offered
+ * six colours for a vocabulary of seven, so `info` was undocumented everywhere.
+ *
+ * A gap makes the assignment below fail, and the error names the missing member.
+ */
+type Missing<Union extends string, Listed extends string> = Exclude<Union, Listed>;
+
+const _allSizesListed: Missing<SizeValue, (typeof SIZE_VALUES)[number]> extends never
+  ? true
+  : never = true;
+
+const _allColorsListed: Missing<ColorValue, (typeof COLOR_VALUES)[number]> extends never
+  ? true
+  : never = true;
+
+void _allSizesListed;
+void _allColorsListed;
+
+/* ── The MUI boundary ─────────────────────────────────────────────────────── */
+
+/** What MUI calls a size. Three entries against our five. */
+export type MuiSize = 'small' | 'medium' | 'large';
+
+/**
+ * The house scale collapsed onto MUI's three.
+ *
+ * Five onto three loses information, and it loses it at the ends on purpose:
+ * `xs`/`sm` both draw small and `lg`/`xl` both draw large, because MUI has no
+ * fourth and fifth step to give them. A component that genuinely needs five
+ * distinct sizes styles them itself rather than routing through here — this is
+ * for the ones that just forward the prop.
+ */
+export const muiSize = (size: SizeValue): MuiSize => {
+  if (size === 'xs' || size === 'sm') return 'small';
+  return size === 'md' ? 'medium' : 'large';
+};
+
+/** What MUI calls a semantic colour on most components. */
+export type MuiColor = 'primary' | 'secondary' | 'success' | 'warning' | 'info' | 'error';
+
+/**
+ * The house vocabulary translated for MUI, with the caller naming its neutral.
+ *
+ * `neutral` is the awkward one: MUI spells the unaccented state `default` on a
+ * chip, `inherit` on a button and an icon button, and `grey` in the palette. So
+ * the caller passes the word its own MUI component uses rather than this
+ * pretending there is one answer.
+ *
+ * A MAPPING, NEVER A CAST. The cast is what let `danger` reach MUI untouched and
+ * silently fall back to grey.
+ */
+export function muiColor<N extends string>(color: ColorValue, neutralAs: N): MuiColor | N {
+  if (color === 'danger') return 'error';
+  return color === 'neutral' ? neutralAs : color;
+}
+
+/**
+ * The house vocabulary as a `theme.palette` key.
+ *
+ * Separate from {@link muiColor} because the palette has no `default` and no
+ * `inherit` — an unaccented colour there is `grey`.
+ */
+export type PaletteKey = MuiColor | 'grey';
+
+export const paletteKey = (color: ColorValue): PaletteKey =>
+  color === 'danger' ? 'error' : color === 'neutral' ? 'grey' : color;
+
+/**
+ * A `ColorValue` resolved to a four-stop accent from the theme.
+ *
+ * `paletteKey` is not enough on its own for anything that reads `.main`: MUI's
+ * palette has no neutral `PaletteColor`, and `palette.grey` is a 50–900 ramp
+ * with no `main`, `light`, `dark` or `contrastText` on it at all. So `neutral`
+ * is resolved from the ramp here, once, instead of every component discovering
+ * the same hole and branching around it.
+ *
+ * Typed against the theme structurally so this file does not drag in MUI's
+ * `Theme` and become a dependency of everything that imports a token.
+ */

package/dist/chunk-7CA6GVBO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/tokens/typography.ts"],"sourcesContent":["import type { Theme } from '@mui/material/styles/index.js';\n\n/**\n * THE THIRD VOCABULARY: the type scale.\n *\n * `scales.ts` opens by saying the package had both halves of every argument at\n * once until the size and colour vocabularies were declared in one place and\n * every component derived from them. The type scale was the one that never got\n * that treatment — it lived as a private `LEVELS` table inside\n * `Heading.styles.ts`, which is exactly the shape that file exists to refuse.\n *\n * Two things follow from it being private, and the second is the expensive one.\n *\n * **It could not be re-themed.** `Heading` read `theme.typography.h1.fontFamily`\n * from the theme and then ignored the theme for every other metric, so a host\n * calling `createTheme({ typography: { h1: { fontSize: '2rem' } } })` changed\n * `<Typography variant=\"h1\">` and left `<Heading level=\"h1\">` at 48px. A design\n * system whose type scale cannot be set by the design is not a system.\n *\n * **And the numbers were a landing page's.** `h1` at 3rem and `h2` at 2.5rem are\n * hero metrics. Dropped into an operations console they put a 48px title\n * directly above 14px body copy — a 3.4x jump with nothing in between — so\n * product teams stopped reaching for the component. Measured in one consuming\n * repo: `<Heading>` appeared four times in the entire codebase while raw\n * `fontSize` appeared in dozens of files. The component was not disliked, it was\n * unusable at app scale, and every host paid for that in hand-rolled CSS.\n *\n * So the defaults below are an APP scale, and `display` keeps the hero size for\n * the screens that actually want one. A marketing page asks for `display`; a\n * console asks for `h1` and gets something it can put on a page.\n */\n\n/**\n * A step on the scale.\n *\n * `display` is a SIZE, not a rank — see `Heading`, which renders it as `h1` so\n * the document still gets exactly one level-one heading.\n */\nexport type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'display';\n\n/**\n * The runtime list, declared beside the union for the reason `SIZE_VALUES`\n * gives: a story's `argTypes.options` spelled by hand drifts from the type, and\n * the direction it drifts is \"documents less than the component accepts\".\n */\nexport const HEADING_LEVELS = [\n  'display',\n  'h1',\n  'h2',\n  'h3',\n  'h4',\n  'h5',\n  'h6',\n] as const satisfies readonly HeadingLevel[];\n\n/** Everything one step of the scale decides. */\nexport interface HeadingMetrics {\n  fontSize: string;\n  lineHeight: number;\n  letterSpacing?: string;\n  /**\n   * The weight this step carries when the caller asks for `normal`. A heading's\n   * \"normal\" is not body text's 400 — it is the weight the step is meant to\n   * carry, which gets heavier as the step gets larger.\n   */\n  normalWeight: number;\n}\n\n/**\n * The house default, in CODE rather than in a component.\n *\n * ~1.15x per step from a 1rem `h6`, which keeps six distinguishable ranks inside\n * the range an application actually uses. The old table ran 1.125rem → 4rem and\n * spent its top three steps above anything a product screen wants.\n */\nexport const HEADING_SCALE: Record<HeadingLevel, HeadingMetrics> = {\n  // The hero size the old `h1` was really offering, under the name that says so.\n  display: { fontSize: '3rem', lineHeight: 1.05, letterSpacing: '-0.03em', normalWeight: 800 },\n  h1: { fontSize: '2rem', lineHeight: 1.2, letterSpacing: '-0.02em', normalWeight: 700 },\n  h2: { fontSize: '1.75rem', lineHeight: 1.25, letterSpacing: '-0.015em', normalWeight: 700 },\n  h3: { fontSize: '1.5rem', lineHeight: 1.3, letterSpacing: '-0.01em', normalWeight: 600 },\n  h4: { fontSize: '1.25rem', lineHeight: 1.35, letterSpacing: '-0.005em', normalWeight: 600 },\n  h5: { fontSize: '1.125rem', lineHeight: 1.4, normalWeight: 600 },\n  h6: { fontSize: '1rem', lineHeight: 1.5, normalWeight: 600 },\n};\n\n/** A host's overrides: any subset of the steps, any subset of each step's metrics. */\nexport type HeadingScaleOverrides = Partial<Record<HeadingLevel, Partial<HeadingMetrics>>>;\n\n/**\n * The theme channel, under our OWN key rather than MUI's `typography.h1…h6`.\n *\n * Those are spoken for: MUI ships its own values there (`h1` is 6rem) and\n * `<Typography variant=\"h1\">` renders them. Reading them here would hand an\n * un-themed host a 96px `h1` — worse than the number this change exists to fix —\n * and would make `Heading` and `Typography` impossible to size apart. A separate\n * key means a host that sets nothing gets {@link HEADING_SCALE}, and a host that\n * sets something gets exactly what it asked for.\n */\ndeclare module '@mui/material/styles' {\n  interface TypographyVariants {\n    headingScale?: HeadingScaleOverrides;\n  }\n  interface TypographyVariantsOptions {\n    headingScale?: HeadingScaleOverrides;\n  }\n}\n\n/**\n * One step of the scale, with the host's theme layered over the default.\n *\n * Merged PER METRIC, so a host that only wants a different `fontSize` keeps the\n * line height and letter spacing the step was designed with instead of having to\n * restate them — restating is how a partial override silently loses the tracking\n * that made the size readable.\n */\nexport function headingMetrics(theme: Theme, level: HeadingLevel): HeadingMetrics {\n  return { ...HEADING_SCALE[level], ...theme.typography.headingScale?.[level] };\n}\n"],"mappings":";AA6CO,IAAM,iBAAiB;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAsBO,IAAM,gBAAsD;AAAA;AAAA,EAEjE,SAAS,EAAE,UAAU,QAAQ,YAAY,MAAM,eAAe,WAAW,cAAc,IAAI;AAAA,EAC3F,IAAI,EAAE,UAAU,QAAQ,YAAY,KAAK,eAAe,WAAW,cAAc,IAAI;AAAA,EACrF,IAAI,EAAE,UAAU,WAAW,YAAY,MAAM,eAAe,YAAY,cAAc,IAAI;AAAA,EAC1F,IAAI,EAAE,UAAU,UAAU,YAAY,KAAK,eAAe,WAAW,cAAc,IAAI;AAAA,EACvF,IAAI,EAAE,UAAU,WAAW,YAAY,MAAM,eAAe,YAAY,cAAc,IAAI;AAAA,EAC1F,IAAI,EAAE,UAAU,YAAY,YAAY,KAAK,cAAc,IAAI;AAAA,EAC/D,IAAI,EAAE,UAAU,QAAQ,YAAY,KAAK,cAAc,IAAI;AAC7D;AAgCO,SAAS,eAAe,OAAc,OAAqC;AAChF,SAAO,EAAE,GAAG,cAAc,KAAK,GAAG,GAAG,MAAM,WAAW,eAAe,KAAK,EAAE;AAC9E;","names":[]}

package/dist/chunk-AUYC5K5K.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/form/Button/Button.helpers.ts"],"sourcesContent":["import type { ButtonProps } from './Button.types';\n\ntype ButtonDefaultedKeys =\n  | 'variant'\n  | 'color'\n  | 'size'\n  | 'loading'\n  | 'iconPosition'\n  | 'glow'\n  | 'pulse'\n  | 'ripple'\n  | 'active';\n\ntype ResolvedButtonProps = ButtonProps & Required<Pick<ButtonProps, ButtonDefaultedKeys>>;\n\nconst BUTTON_DEFAULTS: Pick<ButtonProps, ButtonDefaultedKeys> = {\n  variant: 'solid',\n  color: 'primary',\n  size: 'md',\n  loading: false,\n  iconPosition: 'left',\n  glow: false,\n  pulse: false,\n  ripple: true,\n  active: false,\n};\n\n// Strips explicitly-undefined props before the merge, so `size={undefined}` still\n// falls back to the default exactly as a destructuring default would.\nconst definedProps = (props: ButtonProps): Partial<ButtonProps> =>\n  Object.fromEntries(\n    Object.entries(props).filter(([, value]) => value !== undefined),\n  ) as Partial<ButtonProps>;\n\nexport const resolveButtonProps = (props: ButtonProps): ResolvedButtonProps =>\n  ({ ...BUTTON_DEFAULTS, ...definedProps(props) }) as ResolvedButtonProps;\n"],"mappings":";AAeA,IAAM,kBAA0D;AAAA,EAC9D,SAAS;AAAA,EACT,OAAO;AAAA,EACP,MAAM;AAAA,EACN,SAAS;AAAA,EACT,cAAc;AAAA,EACd,MAAM;AAAA,EACN,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,QAAQ;AACV;AAIA,IAAM,eAAe,CAAC,UACpB,OAAO;AAAA,EACL,OAAO,QAAQ,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,MAAM,UAAU,MAAS;AACjE;AAEK,IAAM,qBAAqB,CAAC,WAChC,EAAE,GAAG,iBAAiB,GAAG,aAAa,KAAK,EAAE;","names":[]}