@12-apps/ui 6.39.19 → 6.40.0

package/src/components/data-display/LazyImage/LazyImage.hooks.ts

@@ -21,7 +21,8 @@ type LazyImageDefaultedKeys =
   | 'skeletonProps'
   | 'spinnerProps'
   | 'sx'
-  | 'role';
+  | 'role'
+  | 'data-testid';
 
 export type ResolvedLazyImageProps = LazyImageProps &
   Required<Pick<LazyImageProps, LazyImageDefaultedKeys>>;
@@ -43,6 +44,10 @@ const LAZY_IMAGE_DEFAULTS: Pick<LazyImageProps, LazyImageDefaultedKeys> = {
   spinnerProps: {},
   sx: {},
   role: 'img',
+  // FUT-2774 #3: with no default, every derived id (`${testId}-img`, …) read
+  // literally as `"undefined-img"` for a caller that omitted it — and every
+  // such instance on a page collided on the same ids.
+  'data-testid': 'lazy-image',
 };
 
 // Strips explicitly-undefined props before the merge, so `lazy={undefined}` still
@@ -141,7 +146,7 @@ const usePlaceholderPhase = (
   props: ResolvedLazyImageProps,
   loadingState: NonNullable<LazyImageProps['loadingState']>,
 ) => {
-  const { placeholder, fadeIn, fadeInDuration } = props;
+  const { placeholder, fadeIn, fadeInDuration, src } = props;
   // Only this mode draws a placeholder. Otherwise the real image settling
   // retires the phase at once — batched into the load's own render, with no
   // timer — so a placeholder switched on afterwards never covers a loaded image.
@@ -149,6 +154,18 @@ const usePlaceholderPhase = (
   const [retired, setRetired] = useState(false);
   const fadeTimeoutRef = useTimeoutRef();
 
+  // FUT-2774 #2: `retired` was set once and never reset, and this hook took
+  // no `src` at all — so a mounted instance reused for a NEW image (a
+  // carousel swapping `src` rather than remounting) never showed the
+  // placeholder again for it. Reset on every `src` change, the same way
+  // `useImageSource` already resets `currentSrc`/`isLoading`/`hasError`; drop
+  // any fade timer left over from the PREVIOUS image, or it would retire the
+  // new placeholder on a schedule that has nothing to do with it.
+  useEffect(() => {
+    clearTimeout(fadeTimeoutRef.current);
+    setRetired(false);
+  }, [src, fadeTimeoutRef]);
+
   const retire = useCallback(() => setRetired(true), []);
 
   // The real image fades in over the placeholder, so it goes when the fade ends.
@@ -186,23 +203,49 @@ const useImageSource = (
     retryCount: 0,
     currentSrc: lazy ? null : src,
   });
+  // FUT-2774 #1: the last `src` PROP this hook has already requested — as
+  // opposed to `state.currentSrc`, which a retry deliberately diverges from
+  // `src` (its cache-busting query string) without a NEW image having
+  // arrived. Comparing the effect's guard against `src` itself let a retry's
+  // own state update immediately retrigger this effect, which overwrote the
+  // cache-busted value back to the plain `src` before the browser ever
+  // re-requested it — so `retryOnError` silently never re-fetched anything.
+  const requestedSrcRef = useRef<string | null>(lazy ? null : src);
+  // `handleImageError` (in `useLazyImage`) owns the retry timer itself, but
+  // it schedules against THIS src's identity: read together, the two hooks
+  // can tell a timeout meant for an image that is no longer the current one
+  // apart from one that still is (FUT-2774, src-changing-mid-retry).
+  const retryTimeoutRef = useTimeoutRef();
 
-  const markVisible = useCallback(
-    () => setState((prev) => ({ ...prev, isVisible: true, currentSrc: src })),
-    [src],
-  );
+  const markVisible = useCallback(() => {
+    requestedSrcRef.current = src;
+    setState((prev) => ({ ...prev, isVisible: true, currentSrc: src }));
+  }, [src]);
   useVisibility(props, containerRef, state.isVisible, markVisible);
 
-  // Load image when it becomes visible
+  // Load image when it becomes visible, or when `src` itself changes to a
+  // genuinely new value — never when only `state.currentSrc` has (a retry).
   useEffect(() => {
-    if (!state.isVisible || !src || state.currentSrc === src) {
+    if (!state.isVisible || !src || requestedSrcRef.current === src) {
       return;
     }
 
-    setState((prev) => ({ ...prev, currentSrc: src, isLoading: true, hasError: false }));
-  }, [state.isVisible, src, state.currentSrc]);
-
-  return [state, setState] as const;
+    // A retry scheduled for the PREVIOUS src must not land on this one: left
+    // pending, its stale `setTimeout` would fire later and overwrite this
+    // fresh `currentSrc` with `${oldSrc}?retry=N` — cache-busting an image
+    // nothing asked for again, and never re-syncing back (FUT-2774).
+    clearTimeout(retryTimeoutRef.current);
+    requestedSrcRef.current = src;
+    setState((prev) => ({
+      ...prev,
+      currentSrc: src,
+      isLoading: true,
+      hasError: false,
+      retryCount: 0,
+    }));
+  }, [state.isVisible, src, retryTimeoutRef]);
+
+  return { state, setState, requestedSrcRef, retryTimeoutRef };
 };
 
 /**
@@ -215,8 +258,7 @@ export const useLazyImage = (props: ResolvedLazyImageProps) => {
   const { onLoad, onError, retryOnError, maxRetries, retryDelay } = props;
 
   const containerRef = useRef<HTMLDivElement>(null);
-  const retryTimeoutRef = useTimeoutRef();
-  const [state, setState] = useImageSource(props, containerRef);
+  const { state, setState, requestedSrcRef, retryTimeoutRef } = useImageSource(props, containerRef);
 
   // Handle deprecated showSpinner prop
   const effectiveLoadingState = showSpinner ? 'spinner' : loadingState;
@@ -244,6 +286,13 @@ export const useLazyImage = (props: ResolvedLazyImageProps) => {
       }
 
       retryTimeoutRef.current = setTimeout(() => {
+        // Belt and suspenders alongside `useImageSource`'s own cancel-on-src-
+        // change: if `src` moved on since this timeout was scheduled, this
+        // retry is for an image that is no longer live at all — applying it
+        // would cache-bust the WRONG `<img>` (FUT-2774).
+        if (requestedSrcRef.current !== src) {
+          return;
+        }
         setState((prev) => ({
           ...prev,
           retryCount: prev.retryCount + 1,
@@ -251,7 +300,7 @@ export const useLazyImage = (props: ResolvedLazyImageProps) => {
         }));
       }, retryDelay);
     },
-    [onError, retryOnError, state.retryCount, maxRetries, retryDelay, src, retirePlaceholder],
+    [onError, retryOnError, state.retryCount, maxRetries, retryDelay, src, retirePlaceholder, requestedSrcRef, retryTimeoutRef],
   );
 
   return {

package/src/components/data-display/LazyImage/LazyImage.md

@@ -16,7 +16,7 @@ The LazyImage component optimizes image loading performance by:
 ### Basic Usage
 
 ```tsx
-import { LazyImage } from '@app-services-monitoring/ui';
+import { LazyImage } from '@12-apps/ui';
 
 function App() {
   return (
@@ -225,7 +225,7 @@ wrapping element, rounded to match the image:
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `decoding` | `'async' \| 'sync' \| 'auto'` | `'async'` | Image decoding hint |
-| `loading` | `'eager' \| 'lazy' \| 'auto'` | `'auto'` | Native loading attribute |
+| `loading` | `'eager' \| 'lazy'` | - | Native `loading` attribute; independent of `lazy` (which gates the `IntersectionObserver`) |
 | `fetchPriority` | `'high' \| 'low' \| 'auto'` | - | Fetch priority hint |
 
 ### Customization Props
@@ -334,48 +334,9 @@ The LazyImage component follows accessibility best practices:
 1. **Lazy Loading**: Images load only when needed, reducing initial page load
 2. **Intersection Observer**: Efficient viewport detection with configurable margins
 3. **Progressive Loading**: Support for placeholder images during load
-4. **Retry Logic**: Automatic retry for failed loads with exponential backoff
+4. **Retry Logic**: Automatic retry for failed loads, at a fixed `retryDelay` — the delay does NOT grow between attempts
 5. **Native Loading**: Leverages browser's native lazy loading when available
 
-## Migration from Original LazyImage
-
-If migrating from the original LazyImage in status-site:
-
-```tsx
-// Old usage
-import { LazyImage } from '../components/LazyImage';
-
-<LazyImage
-  src="image.jpg"
-  alt="Description"
-  width={400}
-  height={300}
-  sx={{ borderRadius: 4 }}
-/>
-
-// New usage (fully backward compatible)
-import { LazyImage } from '@app-services-monitoring/ui';
-
-<LazyImage
-  src="image.jpg"
-  alt="Description"
-  width={400}
-  height={300}
-  sx={{ borderRadius: 4 }}
-/>
-```
-
-### New Features Available After Migration
-
-- Error handling with fallback
-- Multiple loading states
-- Retry mechanism
-- Placeholder support
-- Spinner overlay option
-- Event callbacks
-- Better TypeScript support
-- Performance optimizations
-
 ## Related Components
 
 - [Avatar](../Avatar/Avatar.md) - For user profile images

package/src/components/data-display/LazyImage/LazyImage.tsx

@@ -88,6 +88,18 @@ const innerLength = (theme: Theme, value: Length): string | undefined =>
 const orDefault = (value: Length, fallback: number | string): number | string =>
   value === undefined || value === '' ? fallback : value;
 
+/**
+ * A width/height as `metrics` and the `ReactNode` `ErrorFallback` read it
+ * (FUT-2774 #4): an explicit empty string is normalized to "as if unset"
+ * rather than mapped to a component-wide default. Unlike `SkeletonIndicator`
+ * (a content-less box with nothing else to size by, hence its own deliberate
+ * `'100%'`/`'auto'` fallback), these draw the real image or a `ReactNode`
+ * fallback — both have their own intrinsic size, so leaving an unset width
+ * unset lets it size naturally (`brand-link.tsx`'s logo relies on exactly
+ * this: an unset width capped by its own `sx.maxWidth`).
+ */
+const emptyToUnset = (value: Length): Length => (value === '' ? undefined : value);
+
 /** The box the image occupies, as CSS, shared by the real image and every stand-in for it. */
 interface BoxMetrics {
   width?: string;
@@ -106,10 +118,14 @@ const SkeletonIndicator: React.FC<IndicatorProps> = ({ props }) => {
   const theme = useTheme();
   return (
     <Skeleton
-      variant="rectangular"
+      // FUT-2774 #5: `skeletonProps.variant` was typed but never read — the
+      // variant was hard-coded regardless of what a caller passed.
+      variant={props.skeletonProps.variant ?? 'rectangular'}
       width={innerLength(theme, orDefault(props.width, '100%'))}
       height={innerLength(theme, orDefault(props.height, 'auto'))}
-      animation={props.skeletonProps.animation || 'pulse'}
+      // FUT-2774 #5: `||` reads a caller's `false` the same as "unset", so
+      // `skeletonProps.animation={false}` could never turn the animation off.
+      animation={props.skeletonProps.animation ?? 'pulse'}
       intensity={props.skeletonProps.intensity}
       borderRadius={styleLength(theme, props.borderRadius)}
       data-testid={`${props['data-testid']}-skeleton`}
@@ -124,8 +140,11 @@ const SpinnerIndicator: React.FC<IndicatorProps> = ({ props }) => {
   return (
     <SpinnerOverlay>
       <CircularProgress
-        size={styleLength(theme, spinnerProps.size || 40)}
-        thickness={spinnerProps.thickness || 4}
+        // FUT-2774 #5: `||` read `spinnerProps.size`/`thickness` of `0` the
+        // same as unset — the same class of bug FUT-2669 fixed for
+        // `width`/`height`, missed here.
+        size={styleLength(theme, spinnerProps.size ?? 40)}
+        thickness={spinnerProps.thickness ?? 4}
         sx={{ color: spinnerProps.color || theme.palette.primary.main }}
         data-testid={`${props['data-testid']}-spinner`}
       />
@@ -209,8 +228,19 @@ const ErrorFallback: React.FC<IndicatorProps> = ({ props, metrics }) => {
   return (
     <FallbackContainer
       sx={{
-        width: innerLength(theme, width),
-        height: innerLength(theme, height),
+        // FUT-2774 #4 (see `emptyToUnset`). Does NOT change the confirmed
+        // height collapse — `ImageContainer`'s own height was already `'auto'`
+        // either way; see `LazyImage.test.stories.tsx` for that separate,
+        // unresolved defect. `orDefault(height, 'auto')` is safe to share with
+        // `SkeletonIndicator` (unlike width's `'100%'`, deliberately NOT
+        // shared — see `emptyToUnset`): a PERCENTAGE height against an
+        // auto-height containing block computes to `auto` by spec regardless,
+        // so whether `sx.height` is omitted (falling through to
+        // `FallbackContainer`'s own `height: '100%'`) or set to the literal
+        // `'auto'` here, an unset-height container gives the same result
+        // either way — nothing for this fallback to protect against.
+        width: innerLength(theme, emptyToUnset(width)),
+        height: innerLength(theme, orDefault(height, 'auto')),
         borderRadius: styleLength(theme, borderRadius),
       }}
       data-testid={`${testId}-fallback`}
@@ -242,8 +272,14 @@ export const LazyImage = React.memo<LazyImageProps>(function LazyImage(rawProps)
   const { width, height, borderRadius, alt } = props;
   const testId = props['data-testid'];
   const metrics: BoxMetrics = {
-    width: innerLength(theme, width),
-    height: innerLength(theme, height),
+    // FUT-2774 #4 (see `emptyToUnset`): `metrics` also sizes the REAL `<img>`,
+    // where an unset width means "the image's own intrinsic size" —
+    // `brand-link.tsx`'s logo relies on exactly that. `height`'s `'auto'`
+    // fallback has no such live case to protect: a percentage height against
+    // an auto-height containing block computes to `auto` regardless, so
+    // sharing `SkeletonIndicator`'s fallback changes nothing observable.
+    width: innerLength(theme, emptyToUnset(width)),
+    height: innerLength(theme, orDefault(height, 'auto')),
     objectFit: props.objectFit,
     objectPosition: props.objectPosition,
     borderRadius: styleLength(theme, borderRadius),

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/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