@12-apps/ui 6.39.20 → 6.41.0

package/src/components/layout/SettingCard/track.md

@@ -0,0 +1,54 @@
+# SettingCard family
+
+Four settings-screen building blocks under one subpath,
+`@12-apps/ui/layout/SettingCard` (FUT-2823). `SettingCard` summarises a setting
+while closed and edits it in place, with an async save that stays open on
+failure and a focus round trip. `SettingToggle` is a switch that saves as it
+flips. `SettingGroup` is one subject's main switch with dependent rows that dim
+(never vanish) while it is off. `SettingGrid` lays them out in 1–3 columns by
+container query, with equal-height rows and a full-row span for an open card.
+App-agnostic: every word comes in through props (`SettingCardCopy`,
+`SettingSwitchCopy`, titles, summaries, hints).
+
+## Props
+
+- **SettingCard** — `copy`, `title`, `onSave` (may be async), `children` (the
+  form), `summary`, `status`, `learnMore`, `onCancel`, `open` / `defaultOpen` /
+  `onOpenChange`, `disabled`, `saveDisabled`, `formatError`, `headingLevel`,
+  `icon`, `dataTestId`, `className`, `sx`.
+- **SettingToggle** — `copy`, `title`, `checked`, `onChange` (may be async),
+  `summary`, `variant` (`card` | `row`), `disabled`, `formatError`, `icon`,
+  `dataTestId`, `className`, `sx`.
+- **SettingGroup** — `SettingToggle`'s switch props plus `inactiveHint` and
+  `children` (the dependent rows).
+- **SettingGrid** — `children`, `minColumnWidth`, `maxColumns`, `gap`,
+  `aria-label`, `dataTestId`, `className`, `sx`.
+
+## Lint
+
+- Clean (`pnpm lint:files src/components/layout/SettingCard`), plus the
+  complexity and flakiness gates.
+
+## Type Errors
+
+- None (`pnpm typecheck`, `tsc -p tsconfig.stories.json`).
+
+## Testing Scenarios
+
+- Closed/open rendering, in-place open, Escape, controlled mode, no focus steal
+  on mount; save pending / resolved / rejected / thrown / double-press /
+  `saveDisabled`; cancel discarding uncontrolled drafts; toggle optimistic flip,
+  revert, ignored second flip; group inert rows, hint, activation only after
+  the save lands; grid container-query CSS, row sizing, open-card span; layout
+  measured in Chromium by the test stories.
+
+## Storybook Tests List
+
+- Layout/SettingCard/Tests → 8, Layout/SettingToggle/Tests → 4,
+  Layout/SettingGroup/Tests → 3, Layout/SettingGrid/Tests → 3.
+
+## Current
+
+- 2026-09-26 16:40 BRT — v1: all four components, copy packs in both locales,
+  docs per component. Remaining TODO: first host adoption in the origin host
+  (FUT-1659 is the admin screens that would fold onto it).

package/src/components/layout/index.ts

@@ -8,6 +8,7 @@ export * from './Drawer';
 export * from './Resizable';
 export * from './ScrollArea';
 export * from './Separator';
+export * from './SettingCard';
 export * from './Sidebar';
 export * from './Skeleton/Skeleton';
 export * from './TableFilter';

package/src/copy/layout.ts

@@ -16,3 +16,32 @@ export interface TableFilterCopy {
   rangeMin: string;
   rangeMax: string;
 }
+
+/**
+ * The chrome words of an editable `SettingCard`. The card's own title, summary
+ * and status are per-card props; these are the words every card repeats.
+ */
+export interface SettingCardCopy {
+  /** The closed card's trigger. Its accessible name also carries the card's title. */
+  edit: string;
+  /** Discard the draft and close. */
+  cancel: string;
+  save: string;
+  /** Announced (and shown to sighted users as the Save label) while the save is pending. */
+  saving: string;
+  /** The disclosure that reveals the card's longer explanation. */
+  learnMore: string;
+  /** Shown when the save rejected and the host's `formatError` gave no sentence of its own. */
+  saveFailed: string;
+}
+
+/**
+ * What a switch that saves the moment it flips says about that save — shared
+ * by `SettingToggle` and `SettingGroup`'s main switch.
+ */
+export interface SettingSwitchCopy {
+  /** Announced while the flip is being saved. */
+  saving: string;
+  /** Shown when the save rejected and the host's `formatError` gave no sentence of its own. */
+  saveFailed: string;
+}

package/src/en-US.layout.ts

@@ -3,6 +3,8 @@
  * is — see `en-US.ts` for why the packs live in per-family files.
  */
 import type {
+  SettingCardCopy,
+  SettingSwitchCopy,
   TableFilterCopy,
 } from './copy';
 
@@ -13,3 +15,17 @@ export const EN_US_TABLE_FILTER_COPY: TableFilterCopy = {
   rangeMin: "Minimum",
   rangeMax: "Maximum",
 };
+
+export const EN_US_SETTING_CARD_COPY: SettingCardCopy = {
+  edit: "Edit",
+  cancel: "Cancel",
+  save: "Save",
+  saving: "Saving…",
+  learnMore: "Learn more",
+  saveFailed: "Could not save. Please try again.",
+};
+
+export const EN_US_SETTING_SWITCH_COPY: SettingSwitchCopy = {
+  saving: "Saving…",
+  saveFailed: "Could not save. Please try again.",
+};

package/src/locales.ts

@@ -38,6 +38,8 @@ import type {
   PhoneInputCopy,
   RichEditorToolbarCopy,
   SectionOnboardingCopy,
+  SettingCardCopy,
+  SettingSwitchCopy,
   SocialLoginCopy,
   TableFilterCopy,
   TimingDiagramCopy,
@@ -115,6 +117,14 @@ export const TABLE_FILTER_COPY = pack<TableFilterCopy>(
   pt.PT_BR_TABLE_FILTER_COPY,
   en.EN_US_TABLE_FILTER_COPY,
 );
+export const SETTING_CARD_COPY = pack<SettingCardCopy>(
+  pt.PT_BR_SETTING_CARD_COPY,
+  en.EN_US_SETTING_CARD_COPY,
+);
+export const SETTING_SWITCH_COPY = pack<SettingSwitchCopy>(
+  pt.PT_BR_SETTING_SWITCH_COPY,
+  en.EN_US_SETTING_SWITCH_COPY,
+);
 
 // navigation
 export const COMMAND_PALETTE_COPY = pack<CommandPaletteCopy>(

package/src/provider/mui-bridge.ts

@@ -1,8 +1,9 @@
 import type { PaletteColor, Theme, ThemeOptions } from '@mui/material/styles/index.js';
 
 import { cssLengthToPx, cssTrackingToEm } from '../tokens/css-units';
+import { densityFontSize, resolveDensityFactor } from '../tokens/density';
 import { resolveFieldHeight } from '../tokens/field-height.core';
-import { fieldOverrides } from '../tokens/field-height';
+import { fieldOverrides, mergeMuiComponents } from '../tokens/field-height';
 import { fieldRadius } from '../tokens/field-radius';
 import { accentFor } from '../tokens/scales';
 import {
@@ -102,6 +103,9 @@ export function uiThemeFromMui(theme: Theme): UiTheme {
     spacingUnit: unit,
     radius: { sm: md / 2, md, lg: md * 2, xl: md * 4, full: 9999, field: fieldRadius(theme) },
     fieldHeight: resolveFieldHeight(theme.fieldHeight),
+    // A bare MUI theme (never built through `createUiTheme`/`muiThemeOptionsFrom`)
+    // carries no `theme.density` — read back as `'normal'`, factor `1`.
+    density: theme.density ?? resolveDensityFactor(),
     typography: {
       fontFamily: theme.typography.fontFamily ?? WEB_FONT_FAMILY,
       monospaceFontFamily: WEB_MONOSPACE_FONT_FAMILY,
@@ -140,9 +144,19 @@ export function muiThemeOptionsFrom(ui: UiTheme): ThemeOptions {
     shape: { borderRadius: ui.radius.md },
     fieldRadius: ui.radius.field,
     fieldHeight: ui.fieldHeight,
-    components: fieldOverrides(ui.radius.field, ui.fieldHeight),
+    // Additive: children 2–4 (FUT-2766–2768) each add one more source here as
+    // their own geometry overrides land — this PR wires the merge helper to
+    // `fieldOverrides` alone, since no geometry override exists yet.
+    components: mergeMuiComponents(fieldOverrides(ui.radius.field, ui.fieldHeight)),
     spacing: ui.spacingUnit,
-    typography: { fontFamily: ui.typography.fontFamily ?? WEB_FONT_FAMILY },
+    density: ui.density,
+    typography: {
+      fontFamily: ui.typography.fontFamily ?? WEB_FONT_FAMILY,
+      // MUI multiplies every `pxToRem` size by `fontSize / 14` — the lever a
+      // density mode moves (`./tokens/relative.ts`). `htmlFontSize` stays
+      // untouched: that is a reader's own zoom/accessibility setting, not this.
+      fontSize: densityFontSize(ui.density.factor),
+    },
     zIndex: { ...ui.zIndex },
   };
 }

package/src/pt-BR.layout.ts

@@ -3,6 +3,8 @@
  * barrel over this folder — see that file for why.
  */
 import type {
+  SettingCardCopy,
+  SettingSwitchCopy,
   TableFilterCopy,
 } from './copy';
 
@@ -13,3 +15,17 @@ export const PT_BR_TABLE_FILTER_COPY: TableFilterCopy = {
   rangeMin: "Mínimo",
   rangeMax: "Máximo",
 };
+
+export const PT_BR_SETTING_CARD_COPY: SettingCardCopy = {
+  edit: "Editar",
+  cancel: "Cancelar",
+  save: "Salvar",
+  saving: "Salvando…",
+  learnMore: "Saiba mais",
+  saveFailed: "Não foi possível salvar. Tente novamente.",
+};
+
+export const PT_BR_SETTING_SWITCH_COPY: SettingSwitchCopy = {
+  saving: "Salvando…",
+  saveFailed: "Não foi possível salvar. Tente novamente.",
+};

package/src/tokens/density.core.ts

@@ -0,0 +1,118 @@
+/**
+ * THE ONE DENSITY KNOB, WITH NO RENDERER BEHIND IT.
+ *
+ * A host that wants a compact admin or a roomy kiosk should say so once, in
+ * the theme — not hunt through every component's own numbers. Because every
+ * size already goes through `rem(theme, px)` / `theme.spacing()` / `fieldHeight()`
+ * (FUT-2585, `./relative.ts`), moving the type scale, the spacing unit and the
+ * field height BY THE SAME FACTOR is enough to make the whole package denser
+ * or roomier — no `size` step is rewritten, no component is touched (FUT-2764
+ * Decision 3).
+ *
+ * Three named levels, or a raw factor for a repository the three names don't
+ * fit (a kiosk app, say). A repository can also redefine what a named level
+ * itself means (`densityFactors`). Precedence, highest first, ABOVE
+ * `resolveDensityFactor` itself — this file's own resolver has no notion of an
+ * "explicit option" to defer to, that is each CALLER's job:
+ *
+ * - On the `createUiTheme` path (`./theme.ts`): an explicit `spacingUnit` /
+ *   `fieldHeight` option (`UiThemeOptions` carries no `typography.fontSize` —
+ *   only `fontFamily`/`monospaceFontFamily`) still wins over EVERYTHING below,
+ *   unchanged.
+ * - On the MUI-native path (`densityThemeOptions`'s output, or a host's own
+ *   `createTheme()` options merged around it): whichever `typography.fontSize`
+ *   / `spacing` a host's OWN object literal states last wins — plain
+ *   JavaScript object-spread order, not a rule this package enforces. See
+ *   `./density.ts` for exactly where to put it.
+ *
+ * Below that: a numeric `density` (used as the factor directly, no table
+ * lookup, and only when it is a USABLE one — see `resolveDensityFactor`) >
+ * `densityFactors[level]` (a repository's own override for a named level,
+ * same usability rule) > the built-in table below. No `density` at all
+ * resolves to `{ level: 'normal', factor: 1 }` — today, byte-for-byte.
+ *
+ * This file is the resolver alone, so the native renderer and `./theme.ts`
+ * read it without importing MUI. The web reader — `useDensity()`, the MUI
+ * theme channel, and the standalone `densityThemeOptions()` — is in
+ * `./density.ts`.
+ */
+
+export type DensityLevel = 'compact' | 'normal' | 'comfortable';
+
+export const DEFAULT_DENSITY: DensityLevel = 'normal';
+
+/**
+ * The built-in factor table — the LOWEST-precedence source. A repository's
+ * own `densityFactors` entry for a level wins over it; a numeric `density`
+ * bypasses it entirely. Confirmed against screenshots before this PR merges
+ * (see the ticket's Done when) — `compact` 0.9, `normal` 1 (no-op),
+ * `comfortable` 1.1.
+ */
+export const DENSITY_FACTOR: Record<DensityLevel, number> = {
+  compact: 0.9,
+  normal: 1,
+  comfortable: 1.1,
+};
+
+export interface ResolvedDensity {
+  /** Present only when a NAMED level was given; a raw numeric `density` has no name. */
+  level?: DensityLevel;
+  factor: number;
+}
+
+/**
+ * A usable factor — a positive, finite number. The same shape
+ * `resolveFieldHeight` (`./field-height.core`) already accepts for a `height`;
+ * a numeric `density` and a `densityFactors` entry are held to the same rule
+ * so an unusable one falls back exactly the way an unusable `fieldHeight`
+ * option already does, rather than baking a `0`, a negative or a `NaN`/
+ * `Infinity` into `spacingUnit`/`fieldHeight`/`typography.fontSize`.
+ */
+function isUsableFactor(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
+/**
+ * Precedence (highest first): a numeric `density` IS the factor, no table lookup —
+ * but only when it is a usable one (a positive, finite number); `0`, a negative
+ * number, `NaN` or `Infinity` are not a density anyone meant, so they fall back
+ * to `'normal'`, factor `1`, exactly as no `density` at all does. A named
+ * `density` resolves through `factors?.[level] ?? DENSITY_FACTOR[level]` — a
+ * repository's own `densityFactors` override wins over the built-in table, but
+ * only when IT is usable too; an unusable entry falls back to the BUILT-IN
+ * table's value for that same level (not to `'normal'` — the level itself is
+ * still the one asked for, only its factor is unusable). No `density` at all
+ * resolves to `{ level: 'normal', factor: 1 }`.
+ */
+export function resolveDensityFactor(
+  density?: DensityLevel | number,
+  factors?: Partial<Record<DensityLevel, number>>,
+): ResolvedDensity {
+  if (typeof density === 'number') {
+    if (isUsableFactor(density)) return { factor: density };
+    density = undefined; // not usable — fall through to 'normal', below
+  }
+  const level = density ?? DEFAULT_DENSITY;
+  const override = factors?.[level];
+  const factor = isUsableFactor(override) ? override : DENSITY_FACTOR[level];
+  return { level, factor };
+}
+
+const BASE_FONT_SIZE = 14; // MUI's own typography.fontSize baseline
+const BASE_SPACING_UNIT = 8; // theme.ts's literal default
+const BASE_FIELD_HEIGHT = 2.5; // field-height.core.ts's DEFAULT_FIELD_HEIGHT
+
+/** MUI's own `typography.fontSize` at this factor. `htmlFontSize` is never touched. */
+export function densityFontSize(factor: number): number {
+  return BASE_FONT_SIZE * factor;
+}
+
+/** The theme's `spacingUnit` at this factor. */
+export function densitySpacingUnit(factor: number): number {
+  return BASE_SPACING_UNIT * factor;
+}
+
+/** The standard field height (multiples of the default font size) at this factor. */
+export function densityFieldHeight(factor: number): number {
+  return BASE_FIELD_HEIGHT * factor;
+}

package/src/tokens/density.ts

@@ -0,0 +1,134 @@
+import { useTheme } from '@mui/material/styles/index.js';
+import type { ThemeOptions } from '@mui/material/styles/index.js';
+
+import {
+  densityFieldHeight,
+  densityFontSize,
+  densitySpacingUnit,
+  resolveDensityFactor,
+  type DensityLevel,
+  type ResolvedDensity,
+} from './density.core';
+import { fieldOverrides, mergeMuiComponents } from './field-height';
+import { DEFAULT_FIELD_RADIUS } from './field-radius.core';
+
+/**
+ * DENSITY ON THE WEB: the MUI theme channel, the reader, and the standalone
+ * entry point for a host that never calls `createUiTheme`/`UiProvider`.
+ *
+ * The argument for one density knob, the factor table and its precedence are
+ * in `./density.core.ts`.
+ */
+
+export {
+  DEFAULT_DENSITY,
+  DENSITY_FACTOR,
+  densityFieldHeight,
+  densityFontSize,
+  densitySpacingUnit,
+  resolveDensityFactor,
+  type DensityLevel,
+  type ResolvedDensity,
+} from './density.core';
+
+declare module '@mui/material/styles' {
+  interface Theme {
+    /** The density this theme renders at. See `@12-apps/ui/tokens`' `useDensity`. */
+    density?: ResolvedDensity;
+  }
+  interface ThemeOptions {
+    /** The density this theme renders at. See `@12-apps/ui/tokens`' `useDensity`. */
+    density?: ResolvedDensity;
+  }
+}
+
+/**
+ * The theme's resolved density — a plain theme read, not a step-shifting
+ * resolver (`size` stays hierarchy; see `./density.core.ts`). A `styleOverrides`
+ * callback already gets `{ theme }` and can read `theme.density` directly;
+ * this is for a component that needs the level in its own render logic
+ * (`Table`/`DataGrid`/`DataViews` each read it once to source their own
+ * `density` prop's default).
+ *
+ * Falls back to `resolveDensityFactor()` (`'normal'`, factor `1`) for a bare
+ * MUI theme built without `createUiTheme`/`muiThemeOptionsFrom`.
+ */
+export function useDensity(): ResolvedDensity {
+  return useTheme().density ?? resolveDensityFactor();
+}
+
+/**
+ * The density factor as a MUI `ThemeOptions` fragment, for a host that builds
+ * `createTheme()` directly and never calls `createUiTheme`/`UiProvider` — the
+ * same precedence `resolveDensityFactor` gives `createUiTheme`, so the two
+ * consumption paths agree on `typography`/`spacing`/`fieldHeight`/`components`
+ * (FUT-2764's Design section), not just the first two. `fieldHeight` matters
+ * on its own: `Input`/`Select`/`Button` each read `theme.fieldHeight` directly
+ * (`Input.tsx`, `Select.tsx`, `Button.styles.ts`'s `buttonSize`), so a fragment
+ * that carried only `typography`/`spacing` left every field standing at the
+ * DEFAULT height (2.5) at every density on this path — the two paths would
+ * agree on the type scale and disagree on the one number three components key
+ * their own layout off.
+ *
+ * `components` is the matching MUI-native override (`fieldOverrides`) for a
+ * HOST's own bare `TextField`/`Select`, mirroring `muiThemeOptionsFrom`'s own
+ * `components: mergeMuiComponents(fieldOverrides(...))`. It carries ONLY the
+ * field overrides this function knows about (`MuiOutlinedInput`'s `root`,
+ * `input` and `notchedOutline`; `MuiInputLabel`'s `outlined`) — a host with
+ * ITS OWN overrides for OTHER components merges them in with
+ * `mergeMuiComponents(densityThemeOptions(density).components, hostOverrides)`,
+ * which keeps a component only ONE side touches untouched. For a component
+ * BOTH sides style, the merge is by INNER key (`root`/`input`/…): a key only
+ * one side sets survives from that side, but a key BOTH set is replaced
+ * WHOLESALE by whichever source is passed LAST — not deep-merged — so a host
+ * wanting to ADD to, say, `MuiOutlinedInput`'s `root` alongside the radius
+ * override needs to write that one key's object out in full itself.
+ *
+ * `fieldRadius` (3rd argument, optional) exists because density does NOT touch
+ * the field's CORNER — this is only for a host that already draws its OWN,
+ * non-default radius and wants `components` to match it instead of clashing;
+ * it defaults
+ * to the same {@link DEFAULT_FIELD_RADIUS} `createUiTheme` itself falls back
+ * to when a host names no `fieldRadius`, so the two paths still agree with no
+ * argument passed at all — the existing 2-argument call keeps working
+ * unchanged.
+ *
+ * **Where to spread it — the first `createTheme()` call, not a later layering
+ * one.** `createTheme(options, ...args)` (`createThemeNoVars.js`) only runs
+ * `createSpacing`/`createTypography` on `options`, the FIRST argument; every
+ * later argument is deep-merged onto the theme those two already built, with
+ * no such reprocessing. So a host with a base theme and a SECOND, layering
+ * `createTheme()` call on top of it — exactly the shape a two-theme host uses,
+ * `createTheme(outer, { palette: { ... } })` — must apply density at the
+ * FIRST call (where the base itself is built), never spread onto `outer` in
+ * the second one:
+ *
+ * ```ts
+ * // RIGHT — density goes into the base's OWN construction. The second,
+ * // layering call is unaffected: it never restates spacing/typography/
+ * // fieldHeight/components itself, so `theme.spacing`/`pxToRem`/`fieldHeight`
+ * // carry over from `base` UNCHANGED, already correctly scaled.
+ * const base = createTheme({ palette: { primary: { main }, ... }, ...densityThemeOptions('compact') });
+ * const themed = createTheme(base, { palette: { primary: { main: brand } } });
+ *
+ * // WRONG — a second, layering argument onto an ALREADY-BUILT theme is
+ * // deepmerged with no reprocessing: `spacing`/`typography.fontSize` would
+ * // overwrite the already-resolved `theme.spacing` function/`pxToRem` ratio
+ * // instead of rescaling them.
+ * createTheme(outer, { ...densityThemeOptions('compact') });
+ * ```
+ */
+export function densityThemeOptions(
+  density: DensityLevel | number,
+  factors?: Partial<Record<DensityLevel, number>>,
+  fieldRadius: number = DEFAULT_FIELD_RADIUS,
+): Pick<ThemeOptions, 'typography' | 'spacing' | 'fieldHeight' | 'components'> {
+  const { factor } = resolveDensityFactor(density, factors);
+  const fieldHeight = densityFieldHeight(factor);
+  return {
+    typography: { fontSize: densityFontSize(factor) },
+    spacing: densitySpacingUnit(factor),
+    fieldHeight,
+    components: mergeMuiComponents(fieldOverrides(fieldRadius, fieldHeight)),
+  };
+}

package/src/tokens/field-height.core.ts

@@ -44,9 +44,14 @@ export const FIELD_HEIGHT_SCALE: Record<SizeValue, number> = {
   xl: 1.4,
 };
 
-/** A usable standard height: the given one when it is a positive number, the default otherwise. */
-export function resolveFieldHeight(height: unknown): number {
-  return typeof height === 'number' && Number.isFinite(height) && height > 0 ? height : DEFAULT_FIELD_HEIGHT;
+/**
+ * A usable standard height: the given one when it is a positive number, a
+ * caller's own `fallback` otherwise — {@link DEFAULT_FIELD_HEIGHT} unless a
+ * density factor (`./density.core`) already worked out a denser or roomier
+ * one to fall back to instead.
+ */
+export function resolveFieldHeight(height: unknown, fallback: number = DEFAULT_FIELD_HEIGHT): number {
+  return typeof height === 'number' && Number.isFinite(height) && height > 0 ? height : fallback;
 }
 
 /** A field's height for a size, in multiples of the default font size (`rem`). */

package/src/tokens/field-height.ts

@@ -120,23 +120,34 @@ export function fieldHeightOverrides(height: number = DEFAULT_FIELD_HEIGHT): Com
 }
 
 /**
- * Both field overrides — the corner and the height — merged per component.
- * They meet on `MuiOutlinedInput` (`root` from the radius, `input` from the
- * height), so a plain spread would lose one of them.
+ * Several `Components<Theme>` override sets, merged per component name — a
+ * later source's `styleOverrides` win over an earlier one's for the SAME
+ * inner key, but neither erases the other's keys. A plain spread of the
+ * top-level objects would drop every override but the last source's for a
+ * component two sources both style (`fieldOverrides` below merges exactly
+ * two; density's geometry overrides, FUT-2766–2768, add more).
  */
-export function fieldOverrides(radius: number | undefined, height: number | undefined): Components<Theme> {
+export function mergeMuiComponents(...sources: Components<Theme>[]): Components<Theme> {
   type Entry = { styleOverrides?: Record<string, unknown> };
-  const corner = fieldRadiusOverrides(radius) as Record<string, Entry>;
-  const tall = fieldHeightOverrides(height) as Record<string, Entry>;
-  const names = new Set([...Object.keys(corner), ...Object.keys(tall)]);
+  const maps = sources as unknown as Record<string, Entry>[];
+  const names = new Set(maps.flatMap((map) => Object.keys(map)));
   return Object.fromEntries(
     [...names].map((name) => [
       name,
-      { styleOverrides: { ...corner[name]?.styleOverrides, ...tall[name]?.styleOverrides } },
+      { styleOverrides: Object.assign({}, ...maps.map((map) => map[name]?.styleOverrides)) },
     ]),
   ) as Components<Theme>;
 }
 
+/**
+ * Both field overrides — the corner and the height — merged per component.
+ * They meet on `MuiOutlinedInput` (`root` from the radius, `input` from the
+ * height), so a plain spread would lose one of them.
+ */
+export function fieldOverrides(radius: number | undefined, height: number | undefined): Components<Theme> {
+  return mergeMuiComponents(fieldRadiusOverrides(radius), fieldHeightOverrides(height));
+}
+
 /**
  * THE field standard on a MUI `TextField` / `Select` / `Autocomplete`, for a
  * composite that renders MUI's own: the field radius, the field height for

package/src/tokens/index.native.ts

@@ -15,5 +15,16 @@ export {
   fieldHeightPx,
   fieldHeightRem,
 } from './field-height.core';
+// The density knob's factor table and resolver (FUT-2764); `DensityLevel`/
+// `ResolvedDensity` are already exported above, through `./theme`. NOT
+// `useDensity`, which reads a MUI theme and belongs to the web build.
+export {
+  DEFAULT_DENSITY,
+  DENSITY_FACTOR,
+  densityFieldHeight,
+  densityFontSize,
+  densitySpacingUnit,
+  resolveDensityFactor,
+} from './density.core';
 // The named colour sets a *.metrics.ts table reads (FUT-2593); no MUI behind them.
 export * from './ink.core';

package/src/tokens/scales.ts

@@ -33,7 +33,22 @@ export {
   fieldHeightRem,
   fieldOverrides,
   fieldTextFieldStyles,
+  mergeMuiComponents,
 } from './field-height';
+// The theme's density knob (FUT-2764): the factor table, the resolver, the
+// per-repository override and the standalone entry for a host that builds
+// `createTheme()` directly. `DensityLevel`/`ResolvedDensity` are already
+// exported above, through `./theme`.
+export {
+  DEFAULT_DENSITY,
+  DENSITY_FACTOR,
+  densityFieldHeight,
+  densityFontSize,
+  densitySpacingUnit,
+  densityThemeOptions,
+  resolveDensityFactor,
+  useDensity,
+} from './density';
 
 export interface Accent {
   main: string;

package/src/tokens/theme.ts

@@ -8,12 +8,23 @@ import { contrastText, DARK_TEXT_PRIMARY, inkOver } from './ink-over';
 */
 export { contrastText, inkOver };
 import { cssLengthToPx, cssTrackingToEm } from './css-units';
+import {
+  densityFieldHeight,
+  densitySpacingUnit,
+  resolveDensityFactor,
+  type DensityLevel,
+  type ResolvedDensity,
+} from './density.core';
 import { resolveFieldHeight } from './field-height.core';
 import { DEFAULT_FIELD_RADIUS } from './field-radius.core';
 import { HEADING_SCALE, type HeadingLevel } from './heading-scale';
 
 import type { SizeValue } from './vocabulary';
 
+// Re-exported so a caller of `@12-apps/ui/tokens` (or `./theme` directly) gets
+// the density types alongside `UiThemeOptions.density` without a second import.
+export type { DensityLevel, ResolvedDensity };
+
 /**
  * THE THEME BOTH RENDERERS READ.
  *
@@ -120,6 +131,14 @@ export interface UiTheme {
    * (`./field-height.core`) is the dp a field of `size` lays out at.
    */
   fieldHeight: number;
+  /**
+   * The resolved density (FUT-2764): `factor` scales the type scale, the
+   * spacing unit and `fieldHeight` together (see `./density.core`); `level`
+   * is present only when a NAMED level was given, absent for a raw numeric
+   * `density`. Always resolved — `factor` is never optional. Unset resolves
+   * to `{ level: 'normal', factor: 1 }`, today's numbers exactly.
+   */
+  density: ResolvedDensity;
   typography: UiTypography;
   zIndex: { appBar: number; drawer: number; modal: number; snackbar: number; tooltip: number };
 }
@@ -139,6 +158,26 @@ export interface UiThemeOptions {
     background: Partial<UiPalette['background']>;
   }>;
   typography?: Partial<Pick<UiTypography, 'fontFamily' | 'monospaceFontFamily'>>;
+  /**
+   * `spacingUnit` and `fieldHeight` below still win over EVERYTHING, including
+   * this — density only supplies THEIR fallback, the same `??` pattern those
+   * two already use. Precedence, highest first: an explicit `spacingUnit` /
+   * `fieldHeight` option > a numeric `density` (used as the factor directly,
+   * no table lookup) > `densityFactors[level]` (below) > the built-in table
+   * (`compact` 0.9 / `normal` 1 / `comfortable` 1.1). No `density` at all is
+   * `'normal'`, factor `1` — today, byte-for-byte. A numeric `density` that is
+   * not a positive, finite number (`0`, negative, `NaN`, `Infinity`) falls back
+   * to `'normal'` the same way; a `densityFactors` entry that isn't falls back
+   * to the built-in table's value for that level (see `./density.core`).
+   *
+   * A named level (`density: 'compact'`, e.g. a backoffice app), no
+   * `density` at all (`'normal'`, e.g. a storefront), or a raw factor
+   * (`density: 1.15`, e.g. a kiosk app whose own hardware needs a value
+   * none of the three names fit).
+   */
+  density?: DensityLevel | number;
+  /** A repository's own factor for a named level, overriding the built-in table above. */
+  densityFactors?: Partial<Record<DensityLevel, number>>;
   spacingUnit?: number;
   /** The radius every field is drawn with, in dp. Defaults to {@link DEFAULT_FIELD_RADIUS}. */
   fieldRadius?: number;
@@ -304,7 +343,8 @@ export function createUiTheme(options: UiThemeOptions = {}): UiTheme {
   const seeds = options.palette ?? {};
   const brand = DEFAULT_BRAND[mode];
   const defaults = MODE_DEFAULTS[mode];
-  const spacingUnit = options.spacingUnit ?? 8;
+  const density = resolveDensityFactor(options.density, options.densityFactors);
+  const spacingUnit = options.spacingUnit ?? densitySpacingUnit(density.factor);
 
   const palette: UiPalette = {
     mode,
@@ -328,7 +368,8 @@ export function createUiTheme(options: UiThemeOptions = {}): UiTheme {
     spacing: (units: number) => units * spacingUnit,
     spacingUnit,
     radius: { sm: 2, md: 4, lg: 8, xl: 16, full: 9999, field: options.fieldRadius ?? DEFAULT_FIELD_RADIUS },
-    fieldHeight: resolveFieldHeight(options.fieldHeight),
+    fieldHeight: resolveFieldHeight(options.fieldHeight, densityFieldHeight(density.factor)),
+    density,
     typography: {
       fontFamily: options.typography?.fontFamily,
       monospaceFontFamily: options.typography?.monospaceFontFamily,