@dxos/react-ui 0.10.0 → 0.11.0

package/src/playground/Elevation.stories.tsx

@@ -0,0 +1,348 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo, useState } from 'react';
+
+import { random } from '@dxos/random';
+import { mx } from '@dxos/ui-theme';
+
+import {
+  Avatar,
+  Button,
+  Card,
+  Dialog,
+  DropdownMenu,
+  Icon,
+  IconButton,
+  Input,
+  Main,
+  Message,
+  Panel,
+  ScrollArea,
+  Select,
+  Tag,
+  Toolbar,
+  useSidebars,
+} from '../components';
+import { withLayout, withTheme } from '../testing';
+
+random.seed(1);
+
+/**
+ * Kitchen-sink app frame built only from `@dxos/react-ui` primitives at their default props, so
+ * every surface shown is the one the app actually paints — the review harness for the elevation
+ * ladder (`theme/surfaces.css`) and the aspects derived from it.
+ *
+ * Reading the frame outward: the sidebars and topbar are `chrome` (below the canvas), the content
+ * region is `base`, cards are `raised` (above the canvas), the dialog is `overlay`, and the popover
+ * is `popup`. Toolbars and inputs take no level of their own — they step off whichever surface
+ * hosts them, which is why the toolbar in the sidebar and the toolbar on the canvas differ.
+ */
+
+const NavigationToggle = ({ close }: { close?: boolean }) => {
+  const { toggleNavigationSidebar } = useSidebars('StoryElevation__NavigationToggle');
+  return (
+    <IconButton
+      icon={close ? 'ph--caret-left--regular' : 'ph--sidebar-simple--regular'}
+      iconOnly
+      label='Toggle navigation sidebar'
+      onClick={toggleNavigationSidebar}
+    />
+  );
+};
+
+const ComplementaryToggle = ({ close }: { close?: boolean }) => {
+  const { toggleComplementarySidebar } = useSidebars('StoryElevation__ComplementaryToggle');
+  return (
+    <IconButton
+      icon={close ? 'ph--caret-right--regular' : 'ph--sidebar-simple--regular'}
+      iconOnly
+      label='Toggle complementary sidebar'
+      onClick={toggleComplementarySidebar}
+    />
+  );
+};
+
+const NavigationCard = () => (
+  <Card.Root fullWidth>
+    <Card.Header>
+      <Card.Block>
+        <Icon icon='ph--folder--regular' />
+      </Card.Block>
+      <Card.Title>Workspace</Card.Title>
+      <Card.Menu items={[{ label: 'Rename', icon: 'ph--pencil--regular', onClick: () => {} }]} />
+    </Card.Header>
+    <Card.Body>
+      <Card.Action icon='ph--article--regular' label='Documents' annotation='12' onClick={() => {}} />
+      <Card.Action icon='ph--table--regular' label='Tables' annotation='3' onClick={() => {}} />
+      <Card.Action icon='ph--chats-circle--regular' label='Threads' annotation='8' onClick={() => {}} />
+      <Card.Link label='dxos.org' href='https://dxos.org' />
+    </Card.Body>
+  </Card.Root>
+);
+
+const ContactCard = () => (
+  <Card.Root fullWidth>
+    <Card.Header>
+      <Card.DragHandle />
+      <Card.Title>Card on the canvas</Card.Title>
+      <Card.ActionIconButton action='close' onClick={() => {}} />
+    </Card.Header>
+    <Card.Body>
+      <Card.Row>
+        <Card.Block>
+          <Icon icon='ph--user--regular' />
+        </Card.Block>
+        <Card.Text>Card.Text sitting in the content track.</Card.Text>
+      </Card.Row>
+      <Card.Row>
+        <Card.Block>
+          <Icon icon='ph--tag--regular' />
+        </Card.Block>
+        <Card.Text>
+          <Tag hue='blue'>design</Tag> <Tag hue='emerald'>theme</Tag>
+        </Card.Text>
+      </Card.Row>
+      <Card.Section title='Inputs'>
+        <Input.Root>
+          <Input.Label>Text</Input.Label>
+          <Input.TextInput placeholder='Input.TextInput' />
+        </Input.Root>
+        <Input.Root>
+          <Input.Label>Switch</Input.Label>
+          <Input.Block>
+            <Input.Switch />
+          </Input.Block>
+        </Input.Root>
+        <Input.Root>
+          <Input.Label>Checkbox</Input.Label>
+          <Input.Block>
+            <Input.Checkbox />
+          </Input.Block>
+        </Input.Root>
+      </Card.Section>
+      <Card.Row>
+        <Card.Text variant='description'>Card.Text with the description variant.</Card.Text>
+      </Card.Row>
+    </Card.Body>
+  </Card.Root>
+);
+
+const CompanionCard = ({ index }: { index: number }) => {
+  const text = useMemo(() => random.lorem.paragraph(), []);
+  return (
+    <Card.Root fullWidth>
+      <Card.Header>
+        <Card.Block>
+          <Avatar.Root>
+            <Avatar.Content fallback={`${index}`} size={6} variant='circle' />
+          </Avatar.Root>
+        </Card.Block>
+        <Card.Title>{`Companion card ${index}`}</Card.Title>
+        <Card.Menu items={[{ label: 'Dismiss', icon: 'ph--x--regular', onClick: () => {} }]} />
+      </Card.Header>
+      <Card.Body>
+        <Card.Row>
+          <Card.Text variant='description'>{text}</Card.Text>
+        </Card.Row>
+      </Card.Body>
+    </Card.Root>
+  );
+};
+
+const SettingsDialog = ({ open, onOpenChange }: { open: boolean; onOpenChange: (open: boolean) => void }) => (
+  <Dialog.Root open={open} onOpenChange={onOpenChange} modal>
+    <Dialog.Overlay>
+      <Dialog.Content>
+        <Dialog.Header>
+          <Dialog.Title>Dialog on the modal surface</Dialog.Title>
+          <Dialog.Close asChild>
+            <Dialog.ActionIconButton action='close' />
+          </Dialog.Close>
+        </Dialog.Header>
+        <Dialog.Body>
+          <Dialog.Description>Nested surfaces inside a dialog: card, input, popover.</Dialog.Description>
+          <ContactCard />
+        </Dialog.Body>
+        <Dialog.ActionBar>
+          <Dialog.Close asChild>
+            <Button variant='primary'>Done</Button>
+          </Dialog.Close>
+        </Dialog.ActionBar>
+      </Dialog.Content>
+    </Dialog.Overlay>
+  </Dialog.Root>
+);
+
+/**
+ * The narrow outer rails. In the app these are separate elements beside the L1/R1 sidebars
+ * (`L0Menu`, the companion tab strip), and they are the only consumers of `dx-l0-surface` /
+ * `dx-r0-surface` — so without them here nothing guards the rails collapsing back onto the
+ * sidebar tone.
+ */
+const Rail = ({ side }: { side: 'l0' | 'r0' }) => (
+  <div
+    role='none'
+    className={mx(
+      'shrink-0 grid grid-rows-[1fr_min-content] place-items-center py-2 w-(--dx-rail-size)',
+      side === 'l0' ? 'dx-l0-surface' : 'dx-r0-surface',
+    )}
+  >
+    <div className='grid gap-1 place-items-center'>
+      <IconButton iconOnly icon='ph--house--regular' label='Home' variant='ghost' />
+      <IconButton iconOnly icon='ph--folder--regular' label='Collections' variant='ghost' />
+    </div>
+    <IconButton iconOnly icon='ph--gear--regular' label='Settings' variant='ghost' />
+  </div>
+);
+
+const AppFrame = () => {
+  const [dialogOpen, setDialogOpen] = useState(false);
+
+  return (
+    <Main.Root defaultNavigationSidebarState='expanded' defaultComplementarySidebarState='expanded'>
+      <Main.Overlay />
+
+      <Main.NavigationSidebar label='Navigation' classNames='flex flex-row'>
+        <Rail side='l0' />
+        <Panel.Root>
+          <Panel.Toolbar asChild>
+            <Toolbar.Root>
+              <Toolbar.Text>Navigation</Toolbar.Text>
+              <Toolbar.Separator />
+              <NavigationToggle close />
+            </Toolbar.Root>
+          </Panel.Toolbar>
+          <Panel.Content asChild>
+            <ScrollArea.Root centered thin classNames='py-trim-sm'>
+              <ScrollArea.Viewport>
+                <NavigationCard />
+              </ScrollArea.Viewport>
+            </ScrollArea.Root>
+          </Panel.Content>
+        </Panel.Root>
+      </Main.NavigationSidebar>
+
+      <Main.Content classNames='w-full'>
+        <Panel.Root>
+          <Panel.Toolbar asChild>
+            <Toolbar.Root>
+              <NavigationToggle />
+              <Toolbar.Separator />
+              <Toolbar.IconButton icon='ph--plus--regular' variant='primary' label='Add' />
+              <Input.Root>
+                <Input.Label srOnly>Search</Input.Label>
+                <Input.TextInput placeholder='Search' />
+              </Input.Root>
+              <Select.Root defaultValue='all'>
+                <Select.TriggerButton placeholder='Filter' />
+                <Select.Portal>
+                  <Select.Content>
+                    <Select.Viewport>
+                      <Select.Option value='all'>All</Select.Option>
+                      <Select.Option value='mine'>Mine</Select.Option>
+                    </Select.Viewport>
+                    <Select.Arrow />
+                  </Select.Content>
+                </Select.Portal>
+              </Select.Root>
+              <DropdownMenu.Root>
+                <DropdownMenu.Trigger asChild>
+                  <Toolbar.IconButton icon='ph--dots-three-vertical--regular' iconOnly label='Menu' />
+                </DropdownMenu.Trigger>
+                <DropdownMenu.Portal>
+                  <DropdownMenu.Content>
+                    <DropdownMenu.Viewport>
+                      <DropdownMenu.Item onSelect={() => setDialogOpen(true)}>
+                        <Icon icon='ph--gear--regular' />
+                        Open dialog
+                      </DropdownMenu.Item>
+                      <DropdownMenu.Item>
+                        <Icon icon='ph--copy--regular' />
+                        Duplicate
+                      </DropdownMenu.Item>
+                      <DropdownMenu.Item>
+                        <Icon icon='ph--trash--regular' />
+                        Delete
+                      </DropdownMenu.Item>
+                    </DropdownMenu.Viewport>
+                    <DropdownMenu.Arrow />
+                  </DropdownMenu.Content>
+                </DropdownMenu.Portal>
+              </DropdownMenu.Root>
+              <Toolbar.Separator />
+              <ComplementaryToggle />
+            </Toolbar.Root>
+          </Panel.Toolbar>
+
+          <Panel.Content>
+            <Message.Root valence='warning'>
+              <Message.Content>
+                <Message.Title>Message.Root</Message.Title>
+                <Message.Body>A valence surface nested inside a card.</Message.Body>
+              </Message.Content>
+            </Message.Root>
+            <ScrollArea.Root centered>
+              <ScrollArea.Viewport classNames='flex flex-col gap-trim-md'>
+                <ContactCard />
+              </ScrollArea.Viewport>
+            </ScrollArea.Root>
+          </Panel.Content>
+
+          <Panel.Statusbar asChild>
+            <Toolbar.Root>
+              <Toolbar.IconButton variant='ghost' icon='ph--house--regular' iconOnly label='Home' />
+              <Toolbar.Separator />
+              <Toolbar.Text>Statusbar</Toolbar.Text>
+              <Toolbar.Separator />
+              <Toolbar.IconButton variant='ghost' icon='ph--alarm--regular' iconOnly label='Status' />
+            </Toolbar.Root>
+          </Panel.Statusbar>
+        </Panel.Root>
+      </Main.Content>
+
+      <Main.ComplementarySidebar label='Complementary' classNames='flex flex-row-reverse'>
+        <Rail side='r0' />
+        <Panel.Root>
+          <Panel.Toolbar asChild>
+            <Toolbar.Root>
+              <ComplementaryToggle close />
+              <Toolbar.Separator />
+              <Toolbar.Text>Companion</Toolbar.Text>
+            </Toolbar.Root>
+          </Panel.Toolbar>
+          <Panel.Content asChild>
+            <ScrollArea.Root centered padding>
+              <ScrollArea.Viewport classNames='flex flex-col items-center py-3 gap-3'>
+                {Array.from({ length: 20 }, (_, index) => (
+                  <CompanionCard key={index} index={index + 1} />
+                ))}
+              </ScrollArea.Viewport>
+            </ScrollArea.Root>
+          </Panel.Content>
+        </Panel.Root>
+      </Main.ComplementarySidebar>
+
+      <SettingsDialog open={dialogOpen} onOpenChange={setDialogOpen} />
+    </Main.Root>
+  );
+};
+
+const DefaultStory = () => <AppFrame />;
+
+const meta = {
+  title: 'ui/react-ui-core/playground/Elevation',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/primitives/DensityProvider/DensityContext.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { createContext } from 'react';
+
+import { type Density } from '@dxos/ui-types';
+
+export interface DensityContextValue {
+  density?: Density;
+}
+
+// Kept out of `DensityProvider.tsx`: react-refresh only fast-refreshes a module whose exports are
+// all components, so a context exported beside one forces a full page reload on every edit.
+export const DensityContext = createContext<DensityContextValue>({ density: 'md' });

package/src/primitives/DensityProvider/DensityProvider.tsx

@@ -2,20 +2,26 @@
 // Copyright 2023 DXOS.org
 //
 
-import React, { type PropsWithChildren, createContext } from 'react';
+import React, { type PropsWithChildren } from 'react';
 
 import { type Density } from '@dxos/ui-types';
 
-export interface DensityContextValue {
-  density?: Density;
-}
+import { DensityContext } from './DensityContext';
 
 export type DensityProviderProps = PropsWithChildren<{
   density?: Density;
 }>;
 
-export const DensityContext = createContext<DensityContextValue>({ density: 'md' });
-
+/**
+ * Provides density through React context only — controls opt in by reading it and emitting
+ * `data-density`, which applies the `--dx-control*` override for that element alone.
+ *
+ * It deliberately does NOT emit a `dx-density-*` class. Doing so set the knobs for the entire
+ * subtree, so a provider intended for one region (the deck's `lg` pane toolbar) silently resized
+ * unrelated descendants that read `--dx-control` — form labels, for instance. A region that wants
+ * subtree-wide density applies the class itself, where its scope is visible at the call site
+ * (see `Toolbar.Root`).
+ */
 export const DensityProvider = ({ density, children }: DensityProviderProps) => (
   <DensityContext.Provider value={{ density }}>{children}</DensityContext.Provider>
 );

package/src/primitives/DensityProvider/index.ts

@@ -2,4 +2,5 @@
 // Copyright 2023 DXOS.org
 //
 
+export * from './DensityContext';
 export * from './DensityProvider';

package/src/primitives/Flex/Flex.stories.tsx

@@ -11,7 +11,7 @@ import { withLayout, withTheme } from '../../testing';
 import { Flex } from './Flex';
 
 const Cell = ({ label, hue }: { label: string; hue: ChromaticPalette }) => (
-  <div data-hue={hue} className='flex w-full dx-panel p-2 text-sm font-mono border rounded-sm'>
+  <div data-hue={hue} className='flex w-full dx-callout p-2 text-sm font-mono border rounded-sm'>
     {label}
   </div>
 );

package/src/primitives/Grid/Grid.stories.tsx

@@ -11,7 +11,7 @@ import { withLayout, withTheme } from '../../testing';
 import { Grid } from './Grid';
 
 const Cell = ({ label, hue }: { label: string; hue: ChromaticPalette }) => (
-  <div data-hue={hue} className='dx-panel p-2 text-sm font-mono border rounded-sm'>
+  <div data-hue={hue} className='dx-callout p-2 text-sm font-mono border rounded-sm'>
     {label}
   </div>
 );

package/src/primitives/ThemeProvider/IconRegistry.tsx

@@ -0,0 +1,42 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type PropsWithChildren, useEffect, useState } from 'react';
+
+import {
+  type IconRegistry,
+  IconRegistryContext,
+  type IconSource,
+  NoopRegistry,
+  acquireRegistry,
+  defaultSources,
+} from './icon-registry';
+
+export type IconRegistryProviderProps = PropsWithChildren<{
+  /**
+   * Icon sets resolvable at runtime; defaults to Phosphor at `/phosphor`. Only the first
+   * mounted provider's sources apply, since the registry is shared across a document.
+   */
+  sources?: IconSource[];
+}>;
+
+/**
+ * Provides the shared icon registry to descendants (consumed by `useIconHref`), acquiring
+ * the refcounted document-level singleton on mount and releasing it on unmount.
+ */
+export const IconRegistryProvider = ({ children, sources = defaultSources }: IconRegistryProviderProps) => {
+  const [registry, setRegistry] = useState<IconRegistry>(NoopRegistry);
+
+  useEffect(() => {
+    if (typeof document === 'undefined') {
+      return;
+    }
+    const { registry, release } = acquireRegistry(sources);
+    setRegistry(registry);
+    return release;
+    // Sources are read once when the shared registry is created; later changes are ignored by design.
+  }, []);
+
+  return <IconRegistryContext.Provider value={registry}>{children}</IconRegistryContext.Provider>;
+};

package/src/primitives/ThemeProvider/ThemeProvider.tsx

@@ -11,6 +11,7 @@ import { type SafeAreaPadding, useSafeArea } from '../../hooks';
 import { hasIosKeyboard } from '../../util';
 import { DensityProvider } from '../DensityProvider';
 import { ElevationProvider } from '../ElevationProvider';
+import { IconRegistryProvider } from './IconRegistry';
 import { TranslationsProvider, type TranslationsProviderProps } from './TranslationsProvider';
 
 export type ThemeContextValue = {
@@ -18,7 +19,6 @@ export type ThemeContextValue = {
   themeMode: ThemeMode;
   hasIosKeyboard: boolean;
   safeAreaPadding?: SafeAreaPadding;
-  noCache?: boolean;
   platform?: 'mobile' | 'desktop';
 };
 
@@ -42,7 +42,6 @@ export const ThemeProvider = ({
   tx = (_path, _styleProps, ..._options) => undefined,
   themeMode = 'dark',
   rootDensity = 'md',
-  noCache,
   platform,
 }: ThemeProviderProps) => {
   useEffect(() => {
@@ -56,23 +55,25 @@ export const ThemeProvider = ({
   const safeAreaPadding = useSafeArea();
   // Destructure all props explicitly so useMemo deps are stable primitives, not a new `rest` object every render.
   const contextValue = useMemo(
-    () => ({ tx, themeMode, hasIosKeyboard: hasIosKeyboard(), safeAreaPadding, noCache, platform }),
-    [tx, themeMode, safeAreaPadding, noCache, platform],
+    () => ({ tx, themeMode, hasIosKeyboard: hasIosKeyboard(), safeAreaPadding, platform }),
+    [tx, themeMode, safeAreaPadding, platform],
   );
 
   return (
     <ThemeContext.Provider value={contextValue}>
-      <TranslationsProvider
-        {...{
-          fallback,
-          resourceExtensions,
-          appNs,
-        }}
-      >
-        <ElevationProvider elevation='base'>
-          <DensityProvider density={rootDensity}>{children}</DensityProvider>
-        </ElevationProvider>
-      </TranslationsProvider>
+      <IconRegistryProvider>
+        <TranslationsProvider
+          {...{
+            fallback,
+            resourceExtensions,
+            appNs,
+          }}
+        >
+          <ElevationProvider elevation='base'>
+            <DensityProvider density={rootDensity}>{children}</DensityProvider>
+          </ElevationProvider>
+        </TranslationsProvider>
+      </IconRegistryProvider>
     </ThemeContext.Provider>
   );
 };

package/src/primitives/ThemeProvider/TranslationsContext.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { enUS as dtLocaleEnUs } from 'date-fns/locale';
+import { createContext, useContext } from 'react';
+import { useTranslation as useI18NextTranslation } from 'react-i18next';
+
+// Kept out of `TranslationsProvider.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 const initialNs = 'dxos-common';
+export const initialDtLocale = dtLocaleEnUs;
+
+export const TranslationsContext = createContext({
+  appNs: initialNs,
+  dtLocale: initialDtLocale,
+});
+
+export const useTranslation = (...args: Parameters<typeof useI18NextTranslation>) => {
+  const result = useI18NextTranslation(...args);
+  const { dtLocale } = useContext(TranslationsContext);
+  return { ...result, dtLocale };
+};

package/src/primitives/ThemeProvider/TranslationsProvider.tsx

@@ -2,14 +2,13 @@
 // Copyright 2022 DXOS.org
 //
 
-import { type Locale, enUS as dtLocaleEnUs } from 'date-fns/locale';
-import React, { type ReactNode, Suspense, createContext, useContext, useEffect, useState } from 'react';
-import { I18nextProvider, useTranslation as useI18NextTranslation } from 'react-i18next';
+import { type Locale } from 'date-fns/locale';
+import React, { type ReactNode, Suspense, useEffect, useState } from 'react';
+import { I18nextProvider } from 'react-i18next';
 
 import { type Resource, addResources, i18n } from '@dxos/i18n';
 
-const initialNs = 'dxos-common';
-const initialDtLocale = dtLocaleEnUs;
+import { TranslationsContext, initialDtLocale, initialNs } from './TranslationsContext';
 
 export interface TranslationsProviderProps {
   children?: ReactNode;
@@ -21,17 +20,6 @@ export interface TranslationsProviderProps {
   dtLocale?: Locale;
 }
 
-export const TranslationsContext = createContext({
-  appNs: initialNs,
-  dtLocale: initialDtLocale,
-});
-
-export const useTranslation = (...args: Parameters<typeof useI18NextTranslation>) => {
-  const result = useI18NextTranslation(...args);
-  const { dtLocale } = useContext(TranslationsContext);
-  return { ...result, dtLocale };
-};
-
 export const TranslationsProvider = ({
   fallback,
   resourceExtensions,