@12-apps/ui 6.17.1 → 6.19.0

package/dist/types-native/provider/UiProvider.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UiProvider.types.d.ts","sourceRoot":"","sources":["../../../src/provider/UiProvider.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE/D,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IACjC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,GAAG,cAAc,GAAG,SAAS,KAAG,KAAK,IAAI,OACuB,CAAC"}

package/dist/types-native/provider/index.native.d.ts

@@ -0,0 +1,4 @@
+export { UiProvider } from './UiProvider.native';
+export type { UiProviderProps } from './UiProvider.types';
+export { useUiTheme } from './use-ui-theme.native';
+//# sourceMappingURL=index.native.d.ts.map

package/dist/types-native/provider/index.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.native.d.ts","sourceRoot":"","sources":["../../../src/provider/index.native.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types-native/provider/ui-theme-context.d.ts

@@ -0,0 +1,12 @@
+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 declare const UiThemeContext: React.Context<UiTheme | null>;
+//# sourceMappingURL=ui-theme-context.d.ts.map

package/dist/types-native/provider/ui-theme-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-theme-context.d.ts","sourceRoot":"","sources":["../../../src/provider/ui-theme-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,+BAA4C,CAAC"}

package/dist/types-native/provider/use-ui-theme.native.d.ts

@@ -0,0 +1,4 @@
+import { type UiTheme } from '../tokens/theme';
+/** The theme the nearest `UiProvider` set, or the package default without one. */
+export declare function useUiTheme(): UiTheme;
+//# sourceMappingURL=use-ui-theme.native.d.ts.map

package/dist/types-native/provider/use-ui-theme.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ui-theme.native.d.ts","sourceRoot":"","sources":["../../../src/provider/use-ui-theme.native.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAEjE,kFAAkF;AAClF,wBAAgB,UAAU,IAAI,OAAO,CAEpC"}

package/dist/types-native/tokens/color.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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[];
+}
+/** `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` to its `rgb()` / `rgba()` string. */
+export declare function hexToRgb(color: string): string;
+/** Any supported colour string to its type and numeric channels. */
+export declare function decomposeColor(color: string): DecomposedColor;
+/** The inverse of {@link decomposeColor}, with MUI's channel truncation. */
+export declare function recomposeColor({ type, values }: DecomposedColor): string;
+/** An `hsl()` / `hsla()` string to its `rgb()` / `rgba()` equivalent. */
+export declare function hslToRgb(color: string): string;
+/** Relative luminance (WCAG 2.0), to three decimals like MUI. */
+export declare function getLuminance(color: string): number;
+/** WCAG contrast ratio between two colours, 1 to 21. */
+export declare function getContrastRatio(foreground: string, background: string): number;
+/** The colour with its alpha channel set to `value` (0 to 1). */
+export declare function alpha(color: string, value: number): string;
+/** The colour moved `coefficient` (0 to 1) of the way towards black. */
+export declare function darken(color: string, coefficient: number): string;
+/** The colour moved `coefficient` (0 to 1) of the way towards white. */
+export declare function lighten(color: string, coefficient: number): string;
+/** Darken a light colour or lighten a dark one, by `coefficient`. */
+export declare function emphasize(color: string, coefficient?: number): string;
+//# sourceMappingURL=color.d.ts.map

package/dist/types-native/tokens/color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../../src/tokens/color.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAa9C;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAmB7D;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,eAAe,GAAG,MAAM,CAMxE;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAc9C;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYlD;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAI/E;AAED,iEAAiE;AACjE,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED,wEAAwE;AACxE,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAajE;AAED,wEAAwE;AACxE,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAalE;AAED,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,SAAO,GAAG,MAAM,CAEnE"}

package/dist/types-native/tokens/css-units.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+/** `'1.5rem'` → 24, `'1.5em'` → 24, `'20px'` → 20, `20` → 20, unparseable → `fallback`. */
+export declare function cssLengthToPx(value: string | number | undefined, fallback: number): number;
+/** `'-0.02em'` → -0.02, `'0.5px'` → 0.5 / 16, `undefined` → `undefined` ("normal"). */
+export declare function cssTrackingToEm(value: string | undefined): number | undefined;
+//# sourceMappingURL=css-units.d.ts.map

package/dist/types-native/tokens/css-units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css-units.d.ts","sourceRoot":"","sources":["../../../src/tokens/css-units.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM1F;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAK7E"}

package/dist/types-native/tokens/heading-scale.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 declare const HEADING_LEVELS: readonly ["display", "h1", "h2", "h3", "h4", "h5", "h6"];
+/** 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 declare const HEADING_SCALE: Record<HeadingLevel, HeadingMetrics>;
+/** A host's overrides: any subset of the steps, any subset of each step's metrics. */
+export type HeadingScaleOverrides = Partial<Record<HeadingLevel, Partial<HeadingMetrics>>>;
+//# sourceMappingURL=heading-scale.d.ts.map

package/dist/types-native/tokens/heading-scale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-scale.d.ts","sourceRoot":"","sources":["../../../src/tokens/heading-scale.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,cAAc,0DAQiB,CAAC;AAE7C,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE,cAAc,CAS9D,CAAC;AAEF,sFAAsF;AACtF,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC"}

package/dist/types-native/tokens/index.native.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@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';
+//# sourceMappingURL=index.native.d.ts.map

package/dist/types-native/tokens/index.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.native.d.ts","sourceRoot":"","sources":["../../../src/tokens/index.native.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}

package/dist/types-native/tokens/mui-type.d.ts

@@ -0,0 +1,42 @@
+import type { UiTheme } from './theme';
+/**
+ * MUI'S DEFAULT `Typography` VARIANTS, AS NUMBERS.
+ *
+ * Several web components render a title or a message BY NAME —
+ * `<Typography variant="h6">` — and let MUI's theme turn the name into a
+ * size. The native halves have no MUI theme, so they need the numbers MUI's
+ * `createTypography` produces for those names. These are those numbers, for
+ * the variants the ported components use: `fontSize` in px, `lineHeight` as
+ * a ratio, `letterSpacing` in em exactly as MUI rounds it
+ * (`round(letterSpacing / size)`, five decimals).
+ *
+ * Only the DEFAULTS. A host that re-themes `typography.h6` moves the web
+ * halves and not these; each component that reads this records that as a
+ * known gap in its `NATIVE-NOTES.md`.
+ */
+export type MuiTypeVariantName = 'h6' | 'body1' | 'body2';
+export interface MuiTypeVariant {
+    fontSize: number;
+    lineHeight: number;
+    fontWeight: 400 | 500;
+    letterSpacingEm: number;
+}
+export declare const MUI_TYPE: Record<MuiTypeVariantName, MuiTypeVariant>;
+/** MUI's `theme.typography.fontWeightMedium`, which several web styles name outright. */
+export declare const MUI_FONT_WEIGHT_MEDIUM = 500;
+/** A variant multiplied out for a renderer whose `lineHeight` and `letterSpacing` are absolute. */
+export interface MuiTypeStyle {
+    fontFamily: string | undefined;
+    fontSize: number;
+    lineHeight: number;
+    fontWeight: `${MuiTypeVariant['fontWeight']}`;
+    letterSpacing: number;
+}
+/**
+ * The variant as absolute numbers, in the theme's font. `fontSize` may be
+ * overridden — the Alert's title is `body1` at 1.05rem — and the ratios
+ * follow it, which is what the browser does with `em` and a unitless
+ * line-height.
+ */
+export declare function muiTypeStyle(theme: Pick<UiTheme, 'typography'>, variant: MuiTypeVariantName, fontSize?: number): MuiTypeStyle;
+//# sourceMappingURL=mui-type.d.ts.map

package/dist/types-native/tokens/mui-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mui-type.d.ts","sourceRoot":"","sources":["../../../src/tokens/mui-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,GAAG,GAAG,GAAG,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,kBAAkB,EAAE,cAAc,CAI/D,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,mGAAmG;AACnG,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,GAAG,cAAc,CAAC,YAAY,CAAC,EAAE,CAAC;IAC9C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAClC,OAAO,EAAE,kBAAkB,EAC3B,QAAQ,GAAE,MAAmC,GAC5C,YAAY,CASd"}

package/dist/types-native/tokens/theme.d.ts

@@ -0,0 +1,166 @@
+import { 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;
+}
+/** The px value as the rem string the web components write. */
+export declare const px: (value: number) => string;
+export declare const GREY: Record<UiGreyStep, string>;
+/**
+ * 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 declare const DEFAULT_BRAND: Record<UiThemeMode, {
+    primary: string;
+    secondary: string;
+}>;
+/**
+ * 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 declare function contrastText(background: string): string;
+/**
+ * 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 declare function augmentColor(seed: UiPaletteSeed): UiPaletteColor;
+/** `neutral` as `accentFor` in `./scales` has always drawn it: three greys and white. */
+export declare const NEUTRAL: UiPaletteColor;
+/** The body scale `Text` renders, in px. `Text.tsx`'s rem map is this, divided by 16. */
+export declare const TYPE_SIZES: Record<SizeValue, UiTypeStep>;
+export declare const FONT_WEIGHTS: Record<UiFontWeight, number>;
+export declare const WEB_FONT_FAMILY = "\"Roboto\", \"Helvetica\", \"Arial\", sans-serif";
+export declare 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 declare function createUiTheme(options?: UiThemeOptions): UiTheme;
+/** The palette slot a house colour name resolves to. */
+export type UiPaletteKey = 'primary' | 'secondary' | 'success' | 'warning' | 'info' | 'danger' | 'neutral';
+export declare const DEFAULT_UI_THEME: UiTheme;
+//# sourceMappingURL=theme.d.ts.map

package/dist/types-native/tokens/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../src/tokens/theme.ts"],"names":[],"mappings":"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"}

package/dist/types-native/tokens/vocabulary.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 declare const SIZE_VALUES: readonly ["xs", "sm", "md", "lg", "xl"];
+/**
+ * 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 declare const COLOR_VALUES: readonly ["primary", "secondary", "success", "warning", "info", "danger", "neutral"];
+/** 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 declare const muiSize: (size: SizeValue) => MuiSize;
+/** 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 declare function muiColor<N extends string>(color: ColorValue, neutralAs: N): MuiColor | N;
+/**
+ * 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 declare const paletteKey: (color: ColorValue) => PaletteKey;
+/**
+ * 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.
+ */
+//# sourceMappingURL=vocabulary.d.ts.map

package/dist/types-native/tokens/vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.d.ts","sourceRoot":"","sources":["../../../src/tokens/vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;GAWG;AACH;;;;;GAKG;AACH,OAAO,EACL,cAAc,EACd,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzD,eAAO,MAAM,WAAW,yCAAyE,CAAC;AAElG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,WAAW,GACX,SAAS,GACT,SAAS,GACT,MAAM,GACN,QAAQ,GACR,SAAS,CAAC;AAEd,eAAO,MAAM,YAAY,sFAQiB,CAAC;AAmC3C,6DAA6D;AAC7D,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,SAAS,KAAG,OAGzC,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1F;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,GAAG,QAAQ,GAAG,CAAC,CAGxF;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3C,eAAO,MAAM,UAAU,GAAI,OAAO,UAAU,KAAG,UACsB,CAAC;AAEtE;;;;;;;;;;;GAWG"}

package/dist/typography/Heading.js

@@ -1,9 +1,15 @@
 import "../chunk-6GP2DOOO.js";
 import {
   Heading
-} from "../chunk-HQJ75HHI.js";
-import "../chunk-QCIWROKG.js";
-import "../chunk-7CA6GVBO.js";
+} from "../chunk-Z7JNCB5Q.js";
+import "../chunk-PWR7K5OP.js";
+import "../chunk-3N6EK6K5.js";
+import "../chunk-QLWBQQW7.js";
+import "../chunk-PT6TCWIW.js";
+import "../chunk-NQN5Z36J.js";
+import "../chunk-AG66JBNH.js";
+import "../chunk-6JAIFIPW.js";
+import "../chunk-FZXKH2ZT.js";
 import "../chunk-PZ5AY32C.js";
 export {
   Heading

package/dist/typography/Paragraph.js

@@ -1,6 +1,12 @@
 import {
   Paragraph
-} from "../chunk-A2GGT4OC.js";
+} from "../chunk-V3SBJ3PB.js";
+import "../chunk-QKLGH3RZ.js";
+import "../chunk-QLWBQQW7.js";
+import "../chunk-NQN5Z36J.js";
+import "../chunk-AG66JBNH.js";
+import "../chunk-6JAIFIPW.js";
+import "../chunk-FZXKH2ZT.js";
 import "../chunk-PZ5AY32C.js";
 export {
   Paragraph

package/dist/typography/Text.js

@@ -1,7 +1,13 @@
 import "../chunk-VUHLNYAE.js";
 import {
   Text
-} from "../chunk-VRHBJXZ7.js";
+} from "../chunk-2PCOC3PT.js";
+import "../chunk-V3PLFYKO.js";
+import "../chunk-QLWBQQW7.js";
+import "../chunk-NQN5Z36J.js";
+import "../chunk-AG66JBNH.js";
+import "../chunk-6JAIFIPW.js";
+import "../chunk-FZXKH2ZT.js";
 import "../chunk-PZ5AY32C.js";
 export {
   Text

package/dist/user-avatar.js

@@ -1,7 +1,7 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-DQIQKIEA.js";
+} from "./chunk-HKZHEK3Z.js";
 import "./chunk-UDQSIRAP.js";
 import "./chunk-QIV73V2X.js";
 import "./chunk-LYNJJV2X.js";
@@ -12,10 +12,17 @@ import "./chunk-D2IASECY.js";
 import "./chunk-VMF3UXM4.js";
 import "./chunk-RI5JZLZL.js";
 import "./chunk-BA4RHQ3B.js";
-import "./chunk-IAQFQNBL.js";
-import "./chunk-AUYC5K5K.js";
-import "./chunk-NYUGX76C.js";
-import "./chunk-VRHBJXZ7.js";
+import "./chunk-SL4NFGOL.js";
+import "./chunk-TAMIZE4Q.js";
+import "./chunk-JT6TERQL.js";
+import "./chunk-ITGG5OKP.js";
+import "./chunk-2PCOC3PT.js";
+import "./chunk-V3PLFYKO.js";
+import "./chunk-QLWBQQW7.js";
+import "./chunk-NQN5Z36J.js";
+import "./chunk-AG66JBNH.js";
+import "./chunk-6JAIFIPW.js";
+import "./chunk-FZXKH2ZT.js";
 import "./chunk-PZ5AY32C.js";
 export {
   UserAvatar,

package/dist/utility/InstallPrompt.js

@@ -1,8 +1,7 @@
 import "../chunk-3QQVEYOR.js";
 import {
   InstallPrompt
-} from "../chunk-5ZOJLYD2.js";
-import "../chunk-GY62N32G.js";
+} from "../chunk-JE6RZ5L6.js";
 import {
   usePwaInstall
 } from "../chunk-5GMHJ7Y5.js";
@@ -14,6 +13,7 @@ import {
   readPwaInstallStash,
   resetPwaInstallStash
 } from "../chunk-UUL44SUX.js";
+import "../chunk-GY62N32G.js";
 import "../chunk-PZ5AY32C.js";
 export {
   InstallPrompt,