@dxos/react-ui 0.10.0 → 0.11.0

package/src/components/Slider/Slider.test.tsx

@@ -0,0 +1,105 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { cleanup, render, screen } from '@testing-library/react';
+import React, { type PropsWithChildren } from 'react';
+import { afterEach, describe, test } from 'vitest';
+
+import { ThemeProvider } from '../../primitives';
+import { defaultTx } from '../../theme';
+import { Slider } from './Slider';
+
+describe('Slider', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  test('renders one thumb per value with real (non-logical) size utility classes', ({ expect }) => {
+    render(<Slider defaultValue={[25, 75]} max={100} step={1} thumbLabels={['Minimum', 'Maximum']} />, {
+      wrapper: Wrapper,
+    });
+
+    const thumbs = screen.getAllByRole('slider');
+    expect(thumbs).toHaveLength(2);
+
+    // Regression guard for the invisible-thumb bug: `is-4`/`bs-4` are not real Tailwind utilities
+    // in this repo's config (no logical inline-/block-size plugin is configured), so they generated
+    // no CSS and the thumb collapsed to zero size. happy-dom has no layout engine, so a computed
+    // `getBoundingClientRect`/`getComputedStyle` size assertion cannot fail meaningfully here (it
+    // would pass or fail independent of the actual applied CSS) — asserting the class list carries
+    // real (non-logical) sizing utilities, and never the invalid `is-*`/`bs-*` ones, is the
+    // strongest check available in this environment. Matches any size value, not a specific one.
+    for (const thumb of thumbs) {
+      expect(thumb.className).toMatch(/\bh-\d+\b/);
+      expect(thumb.className).toMatch(/\bw-\d+\b/);
+      expect(thumb.className).not.toMatch(/\bis-\d+\b/);
+      expect(thumb.className).not.toMatch(/\bbs-\d+\b/);
+    }
+  });
+
+  test('keeps the thumb rendered (never removed) when disabled', ({ expect }) => {
+    render(<Slider defaultValue={[50]} max={100} step={1} disabled aria-label='Value' />, { wrapper: Wrapper });
+
+    // Disabled state is expressed via the root's `opacity-50` (visually muted), not by unmounting
+    // the thumb — assert it is still present with its sizing classes intact.
+    const thumb = screen.getByRole('slider');
+    expect(thumb.className).toMatch(/\bh-\d+\b/);
+    expect(thumb.className).toMatch(/\bw-\d+\b/);
+  });
+
+  test('gives each thumb an accessible name via thumbLabels', ({ expect }) => {
+    render(<Slider defaultValue={[25, 75]} max={100} step={1} thumbLabels={['Minimum', 'Maximum']} />, {
+      wrapper: Wrapper,
+    });
+
+    // `role="slider"` has no visible text an `Input.Label`'s `htmlFor` can reach; `thumbLabels`
+    // is the only way to give it a name exposed to assistive tech.
+    expect(screen.getByRole('slider', { name: 'Minimum' })).toBeTruthy();
+    expect(screen.getByRole('slider', { name: 'Maximum' })).toBeTruthy();
+  });
+
+  test('gives a single thumb an accessible name via a plain aria-label', ({ expect }) => {
+    render(<Slider defaultValue={[50]} max={100} step={1} aria-label='Volume' />, { wrapper: Wrapper });
+
+    // Ergonomic shorthand for the common one-thumb case: no need to wrap the label in `thumbLabels`.
+    expect(screen.getByRole('slider', { name: 'Volume' })).toBeTruthy();
+  });
+
+  test('every rendered thumb, across default and multi-thumb usage, exposes an accessible name', ({ expect }) => {
+    const { unmount } = render(<Slider defaultValue={[50]} max={100} step={1} aria-label='Value' />, {
+      wrapper: Wrapper,
+    });
+    for (const thumb of screen.getAllByRole('slider')) {
+      expect(thumb.getAttribute('aria-label')).toBeTruthy();
+    }
+    unmount();
+
+    render(<Slider defaultValue={[25, 75]} max={100} step={1} thumbLabels={['Minimum', 'Maximum']} />, {
+      wrapper: Wrapper,
+    });
+    for (const thumb of screen.getAllByRole('slider')) {
+      expect(thumb.getAttribute('aria-label')).toBeTruthy();
+    }
+  });
+
+  test('throws when thumbLabels covers only some of the rendered thumbs', ({ expect }) => {
+    // Matching the invariant's own message, not just "it threw": a bare `toThrow()` would also be
+    // satisfied by an unrelated render crash, which is exactly what this guard must not accept.
+    expect(() =>
+      render(<Slider defaultValue={[25, 75]} max={100} step={1} thumbLabels={['Minimum']} />, { wrapper: Wrapper }),
+    ).toThrow('Slider: thumbLabels has 1 entries but 2 thumb(s) are rendered.');
+  });
+
+  test('throws when a multi-thumb slider is given no labels at all', ({ expect }) => {
+    // The other half of the guard: `aria-label` names only a single thumb, so omitting `thumbLabels`
+    // on a two-thumb slider would silently leave one thumb unnamed.
+    expect(() =>
+      render(<Slider defaultValue={[25, 75]} max={100} step={1} aria-label='Range' />, { wrapper: Wrapper }),
+    ).toThrow('Slider: pass thumbLabels (2 entries) or, for a single thumb, aria-label.');
+  });
+});
+
+// `ThemeProvider`'s default `tx` is a no-op (`() => undefined`) — pass `defaultTx` explicitly so
+// `tx('slider.thumb', ...)` actually resolves classes, matching `useThemeContext.test.tsx`'s pattern.
+const Wrapper = ({ children }: PropsWithChildren) => <ThemeProvider tx={defaultTx}>{children}</ThemeProvider>;

package/src/components/Slider/Slider.theme.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { mx } from '@dxos/ui-theme';
+import { type ComponentFunction, type Theme } from '@dxos/ui-types';
+
+export type SliderStyleProps = {
+  orientation?: 'horizontal' | 'vertical';
+  disabled?: boolean;
+};
+
+const root: ComponentFunction<SliderStyleProps> = ({ orientation, disabled }, ...etc) =>
+  mx(
+    'relative flex touch-none select-none items-center',
+    orientation === 'vertical' ? 'h-full w-3 flex-col' : 'w-full h-3',
+    disabled && 'opacity-50 pointer-events-none',
+    ...etc,
+  );
+
+const track: ComponentFunction<SliderStyleProps> = ({ orientation }, ...etc) =>
+  mx(
+    'relative grow overflow-hidden rounded-full bg-input-surface',
+    orientation === 'vertical' ? 'w-1 h-full' : 'h-1 w-full',
+    ...etc,
+  );
+
+const range: ComponentFunction<SliderStyleProps> = ({ orientation }, ...etc) =>
+  mx('absolute bg-accent-bg', orientation === 'vertical' ? 'w-full' : 'h-full', ...etc);
+
+const thumb: ComponentFunction<SliderStyleProps> = (_props, ...etc) =>
+  mx(
+    'block h-3 w-3 shrink-0 rounded-full bg-base-surface border-2 border-accent-bg shadow-sm transition-colors dx-focus-ring',
+    'hover:bg-hover-surface',
+    ...etc,
+  );
+
+export const sliderTheme: Theme<SliderStyleProps> = { root, track, range, thumb };

package/src/components/Slider/Slider.tsx

@@ -0,0 +1,64 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as SliderPrimitive from '@radix-ui/react-slider';
+import React, { forwardRef } from 'react';
+
+import { invariant } from '@dxos/invariant';
+
+import { useThemeContext } from '../../hooks';
+import { type ThemedClassName } from '../../util';
+
+type SliderProps = ThemedClassName<SliderPrimitive.SliderProps> & {
+  /**
+   * Accessible name per thumb, by index — `role="slider"` has no visible text a label's `htmlFor`
+   * can reach, so this is the only way to name it for assistive tech. Required whenever there is
+   * more than one thumb; for the common single-thumb case, a plain `aria-label` works instead.
+   */
+  thumbLabels?: string[];
+};
+
+/** Range input built on the Radix slider primitive; supports one or more thumbs. */
+const Slider = forwardRef<HTMLSpanElement, SliderProps>(
+  (
+    { classNames, orientation = 'horizontal', disabled, thumbLabels, 'aria-label': ariaLabel, ...props },
+    forwardedRef,
+  ) => {
+    const { tx } = useThemeContext();
+    const styleProps = { orientation, disabled };
+    const thumbCount = props.value?.length ?? props.defaultValue?.length ?? 1;
+
+    // Every thumb must expose an accessible name: either one label per thumb, or (for the common
+    // single-thumb case) a plain `aria-label` passthrough — never silently render an unnamed thumb.
+    invariant(
+      thumbLabels ? thumbLabels.length === thumbCount : thumbCount === 1 && ariaLabel !== undefined,
+      thumbLabels
+        ? `Slider: thumbLabels has ${thumbLabels.length} entries but ${thumbCount} thumb(s) are rendered.`
+        : `Slider: pass thumbLabels (${thumbCount} entries) or, for a single thumb, aria-label.`,
+    );
+
+    const labelFor = (index: number) => thumbLabels?.[index] ?? ariaLabel;
+
+    return (
+      <SliderPrimitive.Root
+        {...props}
+        orientation={orientation}
+        disabled={disabled}
+        className={tx('slider.root', styleProps, classNames)}
+        ref={forwardedRef}
+      >
+        <SliderPrimitive.Track className={tx('slider.track', styleProps)}>
+          <SliderPrimitive.Range className={tx('slider.range', styleProps)} />
+        </SliderPrimitive.Track>
+        {Array.from({ length: thumbCount }, (_unused, index) => (
+          <SliderPrimitive.Thumb key={index} className={tx('slider.thumb', styleProps)} aria-label={labelFor(index)} />
+        ))}
+      </SliderPrimitive.Root>
+    );
+  },
+);
+
+export type { SliderProps };
+
+export { Slider };

package/src/components/Slider/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './Slider';

package/src/components/Status/Status.theme.ts

@@ -13,7 +13,7 @@ export type StatusStyleProps = {
 const root: ComponentFunction<StatusStyleProps> = ({ variant = 'default' }, ...etc) =>
   mx(
     'h-1 relative rounded-full overflow-hidden',
-    variant === 'main-bottom' ? 'w-full block' : 'inline-20 inline-block bg-base-surface',
+    variant === 'main-bottom' ? 'w-full block' : 'inline-block bg-base-surface',
     ...etc,
   );
 

package/src/components/Status/Status.tsx

@@ -26,7 +26,6 @@ const Status = forwardRef<HTMLSpanElement, StatusProps>(
         ref={forwardedRef}
       >
         <span
-          role='none'
           className={tx('status.bar', { indeterminate, variant }, classNames)}
           {...(!indeterminate && { style: { width: `${Math.round(progress * 100)}%` } })}
         />

package/src/components/Tag/Tag.stories.tsx

@@ -5,7 +5,7 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { hues } from '@dxos/ui-theme';
+import { hues } from '@dxos/ui-types';
 import { type ChromaticPalette, type MessageValence } from '@dxos/ui-types';
 
 import { withLayout, withTheme } from '../../testing';

package/src/components/Toolbar/Toolbar.theme.ts

@@ -14,12 +14,21 @@ export type ToolbarStyleProps = Partial<{
 const layout =
   'w-full shrink-0 flex flex-nowrap p-1 gap-1 items-center overflow-x-auto scrollbar-none dx-contain-layout';
 
+// The bar declares its density so the shared rule (theme/spacing.css) resizes both the bar and
+// every control inside it; the height then follows the same knob rather than a hard-coded step.
 const root: ComponentFunction<ToolbarStyleProps> = ({ density, disabled, layoutManaged }, ...etc) => {
   return mx(
-    'bg-toolbar-surface dx-toolbar shadow-sm',
-    density === 'lg' && 'h-(--dx-rail-size) px-3!',
-    density === 'sm' && 'h-7 px-2!',
-    density === 'xs' && 'h-6 px-1!',
+    // No shadow here: `Panel.Toolbar` casts the bar's edge shadow, and a toolbar reaches that slot
+    // two ways — as a descendant, or merged into it via `asChild`. Only the descendant form can be
+    // detected in CSS, so a shadow on this element would double up in the merged form and read as a
+    // floating bar. The slot owns it in both.
+    'dx-toolbar-surface',
+    // As a descendant of a Panel slot the slot has already painted the surface full-width; painting
+    // again clamps it to this element, which a `classNames='dx-document'` toolbar renders as a strip
+    // floating inside the bar. (Merged via `asChild` there is one element, which must keep it.)
+    '[[data-slot=toolbar]_&]:bg-transparent',
+    '[[data-slot=statusbar]_&]:bg-transparent',
+    density && `dx-density-${density}`,
     disabled && '*:opacity-20',
     !layoutManaged && layout,
     ...etc,
@@ -27,7 +36,7 @@ const root: ComponentFunction<ToolbarStyleProps> = ({ density, disabled, layoutM
 };
 
 const text: ComponentFunction<ToolbarStyleProps> = (_, ...etc) => {
-  return mx('px-2 grow truncate items-center', ...etc);
+  return mx('px-2 truncate items-center', ...etc);
 };
 
 export const toolbarTheme: Theme<ToolbarStyleProps> = {

package/src/components/Toolbar/Toolbar.tsx

@@ -27,6 +27,7 @@ import {
   type ToggleGroupItemProps,
   type ToggleProps,
 } from '../Button';
+import { Icon } from '../Icon';
 import { Link, type LinkProps } from '../Link';
 import { DropdownMenu } from '../Menu';
 import { Separator, type SeparatorProps } from '../Separator';
@@ -303,6 +304,8 @@ ToolbarActionIconButton.displayName = 'Toolbar.ActionIconButton';
 
 type ToolbarMenuItem<T extends any | void = void> = {
   label: string;
+  /** Optional leading icon (e.g. `ph--trash--regular`). */
+  icon?: string;
   onClick: (context: T) => void;
 };
 
@@ -329,8 +332,9 @@ function ToolbarMenu<T extends any | void = void>({ context, items }: ToolbarMen
         <DropdownMenu.Portal>
           <DropdownMenu.Content>
             <DropdownMenu.Viewport>
-              {items?.map(({ label, onClick: onSelect }, index) => (
+              {items?.map(({ label, icon, onClick: onSelect }, index) => (
                 <DropdownMenu.Item key={index} onSelect={() => onSelect(context as T)}>
+                  {icon && <Icon icon={icon} />}
                   {label}
                 </DropdownMenu.Item>
               ))}

package/src/components/Tooltip/TextTooltip.tsx

@@ -12,7 +12,8 @@ import React, {
   useRef,
 } from 'react';
 
-import { Tooltip, type TooltipScopedProps, type TooltipTriggerProps } from './Tooltip';
+import { Tooltip, type TooltipTriggerProps } from './Tooltip';
+import { type TooltipScopedProps } from './TooltipContext';
 
 export type TextTooltipProps = PropsWithChildren<
   {

package/src/components/Tooltip/Tooltip.tsx

@@ -7,12 +7,10 @@
 
 import { composeEventHandlers } from '@radix-ui/primitive';
 import { useComposedRefs } from '@radix-ui/react-compose-refs';
-import { createContextScope } from '@radix-ui/react-context';
-import type { Scope } from '@radix-ui/react-context';
 import { DismissableLayer } from '@radix-ui/react-dismissable-layer';
 import { useId } from '@radix-ui/react-id';
 import * as PopperPrimitive from '@radix-ui/react-popper';
-import { type PopperAnchorProps, createPopperScope } from '@radix-ui/react-popper';
+import { type PopperAnchorProps } from '@radix-ui/react-popper';
 import { Portal as PortalPrimitive } from '@radix-ui/react-portal';
 import { Presence } from '@radix-ui/react-presence';
 import { Primitive } from '@radix-ui/react-primitive';
@@ -36,35 +34,16 @@ import React, {
 } from 'react';
 
 import { useElevationContext, useThemeContext } from '../../hooks';
-
-type TooltipScopedProps<P = {}> = P & { __scopeTooltip?: Scope };
-const [createTooltipContext, createTooltipScope] = createContextScope('Tooltip', [createPopperScope]);
-const usePopperScope = createPopperScope();
-
-//
-// Tooltip
-//
-
-const DEFAULT_DELAY_DURATION = 700;
-const TOOLTIP_OPEN = 'tooltip.open';
-const TOOLTIP_NAME = 'Tooltip';
-
-type TooltipContextValue = {
-  contentId: string;
-  open: boolean;
-  stateAttribute: 'closed' | 'delayed-open' | 'instant-open';
-  trigger: TooltipTriggerElement | null;
-  onTriggerChange(trigger: TooltipTriggerElement | null, content?: ReactNode, side?: TooltipSide): void;
-  onTriggerEnter(): void;
-  onTriggerLeave(): void;
-  onOpen(): void;
-  onClose(): void;
-  onPointerInTransitChange(inTransit: boolean): void;
-  isPointerInTransitRef: RefObject<boolean>;
-  disableHoverableContent: boolean;
-};
-
-const [TooltipContextProvider, useTooltipContext] = createTooltipContext<TooltipContextValue>(TOOLTIP_NAME);
+import {
+  DEFAULT_DELAY_DURATION,
+  TOOLTIP_NAME,
+  TOOLTIP_OPEN,
+  TooltipContextProvider,
+  type TooltipScopedProps,
+  createTooltipContext,
+  usePopperScope,
+  useTooltipContext,
+} from './TooltipContext';
 
 type TooltipProviderProps = {
   children?: ReactNode;
@@ -763,6 +742,4 @@ export const Tooltip = {
   Trigger: TooltipTrigger,
 };
 
-export { createTooltipScope, useTooltipContext };
-
-export type { TooltipProviderProps, TooltipScopedProps, TooltipSide, TooltipTriggerProps };
+export type { TooltipProviderProps, TooltipSide, TooltipTriggerElement, TooltipTriggerProps };

package/src/components/Tooltip/TooltipContext.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Scope, createContextScope } from '@radix-ui/react-context';
+import { createPopperScope } from '@radix-ui/react-popper';
+import { type ReactNode, type RefObject } from 'react';
+
+import { type TooltipSide, type TooltipTriggerElement } from './Tooltip';
+
+// Kept out of `Tooltip.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so a context and its hook exported beside them force a full page reload on every edit.
+
+export type TooltipScopedProps<P = {}> = P & { __scopeTooltip?: Scope };
+export const [createTooltipContext, createTooltipScope] = createContextScope('Tooltip', [createPopperScope]);
+export const usePopperScope = createPopperScope();
+
+//
+// Tooltip
+//
+
+export const DEFAULT_DELAY_DURATION = 700;
+export const TOOLTIP_OPEN = 'tooltip.open';
+export const TOOLTIP_NAME = 'Tooltip';
+
+export type TooltipContextValue = {
+  contentId: string;
+  open: boolean;
+  stateAttribute: 'closed' | 'delayed-open' | 'instant-open';
+  trigger: TooltipTriggerElement | null;
+  onTriggerChange(trigger: TooltipTriggerElement | null, content?: ReactNode, side?: TooltipSide): void;
+  onTriggerEnter(): void;
+  onTriggerLeave(): void;
+  onOpen(): void;
+  onClose(): void;
+  onPointerInTransitChange(inTransit: boolean): void;
+  isPointerInTransitRef: RefObject<boolean>;
+  disableHoverableContent: boolean;
+};
+
+export const [TooltipContextProvider, useTooltipContext] = createTooltipContext<TooltipContextValue>(TOOLTIP_NAME);

package/src/components/Tooltip/index.ts

@@ -3,5 +3,7 @@
 //
 
 export * from './TextTooltip';
+export { type TooltipScopedProps, createTooltipScope, useTooltipContext } from './TooltipContext';
+
 export * from './Tooltip';
 export * from './tooltipContent';

package/src/components/index.ts

@@ -29,6 +29,7 @@ export * from './ScrollContainer';
 export * from './Select';
 export * from './Separator';
 export * from './Skeleton';
+export * from './Slider';
 export * from './Splitter';
 export * from './Status';
 export * from './Tag';

package/src/hooks/useIconHref.ts

@@ -2,12 +2,33 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useThemeContext } from './useThemeContext';
+import { useCallback, useSyncExternalStore } from 'react';
 
-const ICONS_URL = '/icons.svg';
+import { useIconRegistry } from '../primitives/ThemeProvider/icon-registry';
 
+/**
+ * Resolves an icon name to a same-document `<use href>`.
+ *
+ * Returns `undefined` while the icon is not yet present in the in-DOM sprite — kicking off
+ * a runtime fetch as a side effect. Once the registry has the symbol (either because the
+ * static sprite finished ingesting or because the resolver injected it), the component
+ * re-renders via `useSyncExternalStore` and we return `#name`.
+ */
 export const useIconHref = (icon?: string) => {
-  const { noCache } = useThemeContext();
-  const url = noCache ? `${ICONS_URL}?nocache=${new Date().getMinutes()}` : ICONS_URL;
-  return icon ? `${url}#${icon}` : undefined;
+  const registry = useIconRegistry();
+
+  const subscribe = useCallback((listener: () => void) => registry.subscribe(listener), [registry]);
+  const getSnapshot = useCallback(() => (icon ? registry.hasIcon(icon) : false), [icon, registry]);
+  const getServerSnapshot = useCallback(() => false, []);
+
+  const hasIcon = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+  if (!icon) {
+    return undefined;
+  }
+  if (!hasIcon) {
+    registry.requestIcon(icon);
+    return undefined;
+  }
+  return `#${icon}`;
 };

package/src/hooks/useThemeContext.test.tsx

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { renderHook } from '@testing-library/react';
+import React, { type PropsWithChildren } from 'react';
+import { describe, expect, test } from 'vitest';
+
+import { ThemeProvider } from '../primitives';
+import { defaultTx } from '../theme';
+import { useThemeContext } from './useThemeContext';
+
+describe('useThemeContext', () => {
+  // Error-reporting surfaces (e.g. the fatal dialog) must be able to render even
+  // when the provider is missing — including the vite dev dual-module case where
+  // the provider supplied a different ThemeContext identity than the consumer's.
+  test('falls back to the default theme without a provider', () => {
+    const { result } = renderHook(() => useThemeContext());
+    expect(result.current.tx).toBe(defaultTx);
+    expect(result.current.themeMode).toBe('dark');
+  });
+
+  test('returns the provider value when present', () => {
+    const wrapper = ({ children }: PropsWithChildren) => (
+      <ThemeProvider tx={defaultTx} themeMode='light'>
+        {children}
+      </ThemeProvider>
+    );
+    const { result } = renderHook(() => useThemeContext(), { wrapper });
+    expect(result.current.tx).toBe(defaultTx);
+    expect(result.current.themeMode).toBe('light');
+  });
+});

package/src/hooks/useThemeContext.ts

@@ -4,8 +4,33 @@
 
 import { useContext } from 'react';
 
-import { raise } from '@dxos/debug';
+import { log } from '@dxos/log';
 
-import { ThemeContext } from '../primitives';
+import { ThemeContext, type ThemeContextValue } from '../primitives';
+import { defaultTx } from '../theme';
 
-export const useThemeContext = () => useContext(ThemeContext) ?? raise(new Error('Missing ThemeContext'));
+// Failing soft (rather than throwing) keeps error-reporting surfaces renderable:
+// the fatal dialog itself consumes this hook, and a missing provider — including
+// the vite dev dual-module split, where the mounted ThemeProvider holds a
+// different ThemeContext identity than this consumer — would otherwise crash the
+// dialog meant to report the original error.
+const fallbackContextValue: ThemeContextValue = {
+  tx: defaultTx,
+  themeMode: 'dark',
+  hasIosKeyboard: false,
+};
+
+let warned = false;
+
+export const useThemeContext = (): ThemeContextValue => {
+  const contextValue = useContext(ThemeContext);
+  if (!contextValue) {
+    if (!warned) {
+      warned = true;
+      log.warn('Missing ThemeContext; falling back to the default theme.');
+    }
+    return fallbackContextValue;
+  }
+
+  return contextValue;
+};

package/src/playground/Density.stories.tsx

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { IconButton } from '../components/Button';
+import { Input } from '../components/Input';
+import { withLayoutVariants, withTheme } from '../testing';
+
+/**
+ * The three control sizes side by side, across control types — a density change must read the same
+ * on a checkbox, a text field and an icon button, since they share the `--dx-control*` knobs.
+ */
+const DensityStory = () => (
+  <div className='flex flex-col gap-4'>
+    {(['lg', 'md', 'sm'] as const).map((density) => (
+      <Input.Root key={density}>
+        <Input.Label>{`density="${density}"`}</Input.Label>
+        <div className='flex items-center gap-2'>
+          <Input.Checkbox size={density === 'lg' ? 5 : 4} />
+          <Input.TextInput density={density} classNames='grow' placeholder={`This is a density:${density} input`} />
+          <IconButton density={density} iconOnly icon='ph--gear--regular' label='Settings' />
+        </div>
+      </Input.Root>
+    ))}
+  </div>
+);
+
+const meta = {
+  title: 'ui/react-ui-core/playground/Density',
+  render: DensityStory,
+  decorators: [withTheme(), withLayoutVariants()],
+} satisfies Meta<typeof DensityStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};