@dxos/react-ui 0.8.4-main.d05673bc65 → 0.8.4-main.dfabb4ec29

package/src/exemplars/generics.stories.tsx

@@ -3,13 +3,16 @@
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { type ReactElement, type Ref, forwardRef } from 'react';
+import React from 'react';
 
-import { type SlottableProps } from '@dxos/ui-types';
+import { slottable } from '@dxos/ui-theme';
 
 import { withTheme } from '../testing';
 
-const ComponentInner = forwardRef<HTMLDivElement, ComponentProps>(({ children, ...props }, forwardedRef) => {
+/**
+ * Generic component pattern using the slottable factory.
+ */
+const Component = slottable<HTMLDivElement>(({ children, ...props }, forwardedRef) => {
   return (
     <div {...props} ref={forwardedRef}>
       {children}
@@ -17,21 +20,10 @@ const ComponentInner = forwardRef<HTMLDivElement, ComponentProps>(({ children, .
   );
 });
 
-ComponentInner.displayName = 'Component';
-
-/**
- * Generic component pattern.
- */
-type ComponentProps<P extends HTMLElement = any> = SlottableProps<P>;
-
-const Component = ComponentInner as <P extends HTMLElement>(
-  props: SlottableProps<P> & { ref?: Ref<P> },
-) => ReactElement;
-
 const meta = {
   title: 'ui/react-ui-core/exemplars/generics',
   component: Component,
-  render: (props) => <Component<HTMLDivElement> {...props} />,
+  render: (props) => <Component {...props} />,
   decorators: [withTheme()],
   parameters: {
     layout: 'centered',

package/src/exemplars/slot.stories.tsx

@@ -3,84 +3,64 @@
 //
 
 import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { HTMLAttributes, type PropsWithChildren, forwardRef } from 'react';
+import React, { PropsWithChildren } from 'react';
 
-import { composableProps } from '@dxos/ui-theme';
-import { type ComposableProps, type SlottableProps, type ThemedClassName } from '@dxos/ui-types';
+import { composable, composableProps, mx, slottable } from '@dxos/ui-theme';
 
 import { withTheme } from '../testing';
-import { Slot } from '@radix-ui/react-slot';
+import { ThemedClassName } from '../util';
 
 /**
- * Composition
- *
+ * Radix-style composition.
  * All Radix primitive parts that render a DOM element accept an asChild prop.
- * When asChild is set to true, Radix will not render a default DOM element, instead cloning the part's child and passing it the props and behavior required to make it functional.
+ * When asChild is set to true, Radix will not render a default DOM element,
+ * instead cloning the part's child and passing it the props and behavior required to make it functional.
  * https://www.radix-ui.com/primitives/docs/guides/composition
  */
 
-const Outer = forwardRef<HTMLDivElement, SlottableProps<HTMLDivElement>>(
-  ({ children, asChild, ...props }, forwardedRef) => {
+const Outer = slottable<HTMLDivElement, { priority?: number }>(
+  ({ children, asChild, priority, ...props }, forwardedRef) => {
     const Comp = asChild ? Slot : Primitive.div;
     return (
-      <Comp {...composableProps<HTMLDivElement>(props, { role: 'none' })} ref={forwardedRef}>
+      <Comp
+        {...composableProps<HTMLDivElement>(props, { classNames: 'p-2 border border-red-500 rounded' })}
+        ref={forwardedRef}
+      >
         {children}
       </Comp>
     );
   },
 );
 
-const Middle = forwardRef<HTMLDivElement, SlottableProps<HTMLDivElement>>(
-  ({ children, asChild, ...props }, forwardedRef) => {
-    const Comp = asChild ? Slot : Primitive.div;
-    return (
-      <Comp {...composableProps<HTMLDivElement>(props, { role: 'none' })} ref={forwardedRef}>
-        {children}
-      </Comp>
-    );
-  },
-);
-
-const Leaf = forwardRef<HTMLButtonElement, ComposableProps<HTMLButtonElement>>(
-  ({ children, ...props }, forwardedRef) => {
-    return (
-      <button {...composableProps<HTMLButtonElement>(props, { role: 'none' })} ref={forwardedRef}>
-        {children}
-      </button>
-    );
-  },
-);
-
-const TestSingle = (props: ThemedClassName<{ role?: string }>) => {
+const Middle = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const Comp = asChild ? Slot : Primitive.div;
   return (
-    <Outer asChild {...composableProps<HTMLDivElement>(props, { role: 'none' })}>
-      <Leaf>Single asChild (non-compliant — see console)</Leaf>
-    </Outer>
+    <Comp
+      {...composableProps<HTMLDivElement>(props, { classNames: 'p-2 border border-red-500 rounded' })}
+      ref={forwardedRef}
+    >
+      {children}
+    </Comp>
   );
-};
+});
 
-const TestNested = (props: ThemedClassName<{ role?: string }>) => {
+const Leaf = composable<HTMLButtonElement>(({ children, ...props }, forwardedRef) => {
   return (
-    <Outer asChild {...composableProps<HTMLDivElement>(props, { role: 'none' })}>
-      <Middle asChild>
-        <Leaf>Nested asChild</Leaf>
-      </Middle>
-    </Outer>
+    <button
+      {...composableProps<HTMLButtonElement>(props, { classNames: 'p-2 border border-red-500 rounded' })}
+      ref={forwardedRef}
+    >
+      {children}
+    </button>
   );
-};
+});
 
-const TestInner = (props: ThemedClassName<{ role?: string }>) => {
-  return (
-    <Outer asChild {...composableProps<HTMLDivElement>(props, { role: 'none' })}>
-      <Middle asChild>
-        <Leaf>
-          <div role='none'>Leaf</div>
-        </Leaf>
-      </Middle>
-    </Outer>
-  );
-};
+/** This isn't a valid child for a `slottable` component. */
+const Simple = ({ children, classNames }: ThemedClassName<PropsWithChildren>) => (
+  <div className={mx(classNames)}>{children}</div>
+);
 
 const meta = {
   title: 'ui/react-ui-core/exemplars/slot',
@@ -95,13 +75,41 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Single: Story = {
-  render: () => <TestSingle role='listitem' classNames='border-red-500' />,
+  render: () => (
+    <Outer asChild role='article' classNames='border-green-500' priority={1}>
+      <Leaf>Single asChild (non-compliant — see console)</Leaf>
+    </Outer>
+  ),
 };
 
 export const Nested: Story = {
-  render: () => <TestNested role='listitem' classNames='border-green-500' />,
+  render: () => (
+    <Outer asChild role='article' classNames='border-blue-500'>
+      <Middle asChild>
+        <Leaf>Nested asChild</Leaf>
+      </Middle>
+    </Outer>
+  ),
 };
 
 export const Inner: Story = {
-  render: () => <TestInner role='listitem' classNames='border-blue-500' />,
+  render: () => (
+    <Outer asChild role='article' classNames='border-orange-500'>
+      <Middle asChild>
+        <Leaf>
+          <div>Leaf</div>
+        </Leaf>
+      </Middle>
+    </Outer>
+  ),
+};
+
+export const Error: Story = {
+  render: () => (
+    <Outer asChild role='none' classNames='p-2 border border-green-500 rounded'>
+      <Middle asChild>
+        <Simple>Simple</Simple>
+      </Middle>
+    </Outer>
+  ),
 };

package/src/exemplars/tabster.stories.tsx

@@ -43,7 +43,7 @@ const Column = forwardRef<HTMLDivElement, { items: string[] }>(({ items }, ref)
   const tabsterAttrs = useMergedTabsterAttributes_unstable(focusableGroupAttrs, arrowNavigationAttrs);
 
   return (
-    <ScrollArea.Root tabIndex={0} orientation='vertical' classNames={mx('w-[25rem]', border)}>
+    <ScrollArea.Root orientation='vertical' classNames={mx('w-[25rem]', border)}>
       <ScrollArea.Viewport {...tabsterAttrs} classNames='p-4 gap-4' ref={ref}>
         {items.map((item) => (
           <Item key={item} value={item} />

package/src/exemplars/virtualizer.stories.tsx

@@ -6,11 +6,11 @@ import { type Meta } from '@storybook/react-vite';
 import { useVirtualizer } from '@tanstack/react-virtual';
 import React, { useEffect, useMemo, useRef, useState } from 'react';
 
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 import { Panel, ScrollArea, Toolbar } from '@dxos/react-ui';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
-faker.seed(999);
+random.seed(999);
 
 type TestItem = {
   name: string;
@@ -37,7 +37,7 @@ export const Default = {
     const items = useMemo<TestItem[]>(
       () =>
         Array.from({ length: NUM_ITEMS }, () => ({
-          name: faker.lorem.paragraph(),
+          name: random.lorem.paragraph(),
         })),
       [],
     );
@@ -63,10 +63,9 @@ export const Default = {
           <ScrollToolbar items={items} index={index} setIndex={setIndex} />
         </Panel.Toolbar>
         <Panel.Content asChild>
-          <ScrollArea.Root orientation='vertical' margin>
+          <ScrollArea.Root orientation='vertical' centered>
             <ScrollArea.Viewport classNames='p-2' ref={setViewport}>
               <div
-                role='none'
                 style={{
                   position: 'relative',
                   height: virtualizer.getTotalSize(),

package/src/hooks/index.ts

@@ -6,6 +6,7 @@ export * from './useDensityContext';
 export * from './useElevationContext';
 export * from './useIconHref';
 export * from './useSafeArea';
+export * from './useSafeCollisionPadding';
 export * from './useTranslationsContext';
 export * from './useThemeContext';
 export * from './useVisualViewport';

package/src/hooks/useDensityContext.ts

@@ -8,7 +8,7 @@ import { type Density } from '@dxos/ui-types';
 
 import { DensityContext } from '../components';
 
-export const useDensityContext = (propsDensity?: Density) => {
+export const useDensityContext = (densityProp?: Density): Density | undefined => {
   const { density } = useContext(DensityContext);
-  return propsDensity ?? density;
+  return densityProp ?? density;
 };

package/src/playground/Custom.stories.tsx

@@ -20,15 +20,14 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
             </Button>
           </div>
           <div className='flex justify-center'>
-            <IconButton {...args} label='Test' icon='ph--atom--regular' size={7} density='coarse' />
+            <IconButton {...args} label='Test' icon='ph--circle--regular' density='coarse' />
           </div>
           <div className='flex justify-center'>
             <IconButton
               {...args}
               label='Test'
-              icon='ph--atom--regular'
+              icon='ph--circle--regular'
               iconOnly
-              size={7}
               density='coarse'
               classNames='px-1.5'
             />
@@ -43,13 +42,13 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
             </Button>
           </div>
           <div className='flex justify-center'>
-            <IconButton {...args} label='Test' icon='ph--atom--regular' density='fine' classNames='px-2' />
+            <IconButton {...args} label='Test' icon='ph--circle--regular' density='fine' classNames='px-2' />
           </div>
           <div className='flex justify-center'>
             <IconButton
               {...args}
               label='Test'
-              icon='ph--atom--regular'
+              icon='ph--circle--regular'
               iconOnly
               density='fine'
               classNames='py-1 px-1.5'
@@ -68,9 +67,8 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
             <IconButton
               {...args}
               label='Test'
-              icon='ph--atom--regular'
+              icon='ph--circle--regular'
               density='fine'
-              size={4}
               classNames={'!h-[24px] !text-[14px] p-1 min-h-0 gap-0.5'}
             />
           </div>
@@ -78,10 +76,9 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
             <IconButton
               {...args}
               label='Test'
-              icon='ph--atom--regular'
+              icon='ph--circle--regular'
               iconOnly
               density='fine'
-              size={4}
               classNames={'!h-[24px] !text-[14px] p-1 min-h-0'}
             />
           </div>

package/src/primitives/Column/AUDIT.md

@@ -0,0 +1,148 @@
+# Column architecture reference
+
+## Background
+
+`Column` establishes a 3-column CSS grid with left/right gutter columns and a center content
+channel. Two CSS custom properties drive the system:
+
+- `--gutter` — the gutter track width (e.g. `var(--dx-gutter-md)`); consumed by `ScrollArea.Viewport` for padding.
+- `--dx-col` — the grid-column placement token; set by `Column.Root` and consumed by `withColumn` utilities.
+
+## Column primitives
+
+### Column.Root
+
+```css
+/* column.ts — columnRoot */
+dx-column grid
+/* inline style */
+--gutter: <gutterSize>
+--dx-col: 2 / span 1
+grid-template-columns: <gutter> minmax(0,1fr) <gutter>
+```
+
+Sets the 3-column grid and both CSS variables. All `withColumn` utilities are no-ops outside this context.
+
+### Column.Center
+
+```css
+/* column.ts — columnCenter */
+[grid-column:var(--dx-col,auto)] min-h-0
+```
+
+Places a single element in col 2 (the center track). Does not use subgrid — placement is explicit
+on this element only, so arbitrary compound components (including `display: contents` wrappers) can
+be nested safely.
+
+### Column.Bleed
+
+```css
+/* column.ts — columnBleed */
+col-span-full grid grid-cols-subgrid min-h-0
+```
+
+Spans all 3 columns and propagates the subgrid. Use for `ScrollArea`, full-width dividers, and
+any content that should ignore the gutters.
+
+### Column.Row
+
+```css
+/* column.ts — columnRow */
+col-span-3 grid grid-cols-subgrid
+```
+
+Three-slot icon row. Children map to: `[col-1: icon/slot] [col-2: content] [col-3: icon/action]`.
+Must be a direct child of `Column.Root`.
+
+## withColumn theme utilities
+
+Exported from `@dxos/ui-theme`. Components import and call these in their theme functions to
+participate in the Column grid without importing Column React components.
+
+```ts
+withColumn.center();
+// → '[grid-column:var(--dx-col,auto)]'
+
+withColumn.propagate();
+// → '[.dx-column_&]:col-span-full [.dx-column_&]:grid [.dx-column_&]:grid-cols-subgrid'
+
+withColumn.consumed();
+// → '[--dx-col:auto]'
+```
+
+| Utility       | Purpose                                                                           | Where used                                                                    |
+| :------------ | :-------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |
+| `center()`    | Place element in col 2 via `--dx-col`. No-op outside Column or inside ScrollArea. | Dialog.Header, Dialog.ActionBar, Form.Content, Form.Actions, SearchList.Input |
+| `propagate()` | Extend Column subgrid to children. No-op outside Column.                          | Dialog.Body, SearchList.Content                                               |
+| `consumed()`  | Reset `--dx-col` after `--gutter` is consumed.                                    | ScrollArea.Viewport                                                           |
+
+## CSS custom property cascade
+
+```text
+Column.Root
+  sets --gutter = var(--dx-gutter-<size>)
+  sets --dx-col = 2 / span 1
+    │
+    ├─ Column.Center        → grid-column: var(--dx-col)   ← consumes --dx-col
+    ├─ Column.Bleed         → col-span-full, subgrid
+    ├─ Column.Row           → col-span-3, subgrid
+    │
+    └─ withColumn.center()  → grid-column: var(--dx-col)   ← consumes --dx-col
+       withColumn.propagate() → col-span-full, grid, subgrid (inside .dx-column only)
+         │
+         └─ ScrollArea.Root → col-span-full (inside .dx-column only)
+              ScrollArea.Viewport
+                applies pl/pr using --gutter
+                withColumn.consumed() → sets --dx-col: auto
+                  │
+                  └─ (nested components no longer auto-position)
+```
+
+## Component integration
+
+### Dialog
+
+| Sub-component      | withColumn applied            | Effect                        |
+| :----------------- | :---------------------------- | :---------------------------- |
+| `Dialog.Content`   | `Column.Root` (gutter `'sm'`) | Establishes the 3-col grid.   |
+| `Dialog.Header`    | `withColumn.center()`         | Placed in col 2.              |
+| `Dialog.Body`      | `withColumn.propagate()`      | Children inherit the subgrid. |
+| `Dialog.ActionBar` | `withColumn.center()`         | Placed in col 2.              |
+
+### Form
+
+| Sub-component  | withColumn applied    | Effect                              |
+| :------------- | :-------------------- | :---------------------------------- |
+| `Form.Content` | `withColumn.center()` | Placed in col 2 when inside Column. |
+| `Form.Actions` | `withColumn.center()` | Placed in col 2 when inside Column. |
+
+### SearchList
+
+| Sub-component              | withColumn applied       | Effect                                          |
+| :------------------------- | :----------------------- | :---------------------------------------------- |
+| `SearchList.Content`       | `withColumn.propagate()` | Extends subgrid to children when inside Column. |
+| `SearchList.Input` wrapper | `withColumn.center()`    | Input row placed in col 2.                      |
+
+### Card
+
+`Card.Row` uses its own inline subgrid CSS (`col-span-3 grid grid-cols-subgrid`) and does not
+participate in an outer Column grid. `Card.Root` establishes a separate 3-column grid for its
+own icon-slot layout.
+
+## Subgrid chain integrity
+
+Every intermediate container between `Column.Root` and a `ScrollArea.Root` must propagate the
+subgrid, otherwise `ScrollArea.Root`'s `[.dx-column_&]:col-span-full` selector will not match
+and the scrollbar will not extend to the gutter.
+
+Required chain:
+
+```
+Column.Root (.dx-column)
+  → withColumn.propagate() container   (col-span-full, grid, grid-cols-subgrid)
+    → ScrollArea.Root                  (.dx-container, [.dx-column_&]:col-span-full)
+      → ScrollArea.Viewport            (applies --gutter padding, resets --dx-col)
+```
+
+If any intermediate element wraps the ScrollArea without propagating, use `Column.Bleed` or
+apply `withColumn.propagate()` to that wrapper.

package/src/primitives/Column/Column.stories.tsx

@@ -7,18 +7,16 @@ import React from 'react';
 
 import { Input, ScrollArea } from '../../components';
 import { withLayout, withTheme } from '../../testing';
-import { Flex } from '../Flex';
-
 import { Column } from './Column';
 
 const List = () => {
   return (
-    <ScrollArea.Root margin role='list'>
+    <ScrollArea.Root centered>
       <ScrollArea.Viewport>
         {Array.from({ length: 100 }).map((_, i) => (
-          <div key={i} role='listitem' className='p-1 hover:bg-hover-surface'>
-            Item {i}
-          </div>
+          <Input.Root key={i}>
+            <Input.TextInput value={`Item ${i}`} readOnly />
+          </Input.Root>
         ))}
       </ScrollArea.Viewport>
     </ScrollArea.Root>
@@ -27,10 +25,10 @@ const List = () => {
 
 const DefaultStory = () => {
   return (
-    <Column.Root className='h-full overflow-hidden' gutter='md'>
-      <Column.Segment asChild>
+    <Column.Root classNames='overflow-hidden' gutter='md'>
+      <Column.Center>
         <h1 className='p-1 bg-blue-500 text-black'>Header</h1>
-      </Column.Segment>
+      </Column.Center>
 
       <Column.Row>
         <div className='p-1 bg-blue-500'>A</div>
@@ -38,26 +36,36 @@ const DefaultStory = () => {
         <div className='p-1 bg-blue-500'>C</div>
       </Column.Row>
 
-      <Column.Segment asChild>
-        <div className='py-2'>
+      <Column.Center asChild>
+        <div>
           <Input.Root>
             <Input.TextInput placeholder='Search' />
           </Input.Root>
         </div>
-      </Column.Segment>
+      </Column.Center>
 
-      <List />
+      <ScrollArea.Root orientation='vertical' padding>
+        <ScrollArea.Viewport>
+          <div className='flex flex-col gap-2'>
+            {Array.from({ length: 100 }).map((_, i) => (
+              <Input.Root key={i}>
+                <Input.TextInput value={`Item ${i}`} readOnly />
+              </Input.Root>
+            ))}
+          </div>
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
 
-      <Column.Segment asChild>
-        <Flex column>
+      <Column.Center asChild>
+        <div className='flex flex-col'>
           <h1 className='p-1 bg-red-500 text-black'>Section with overflow</h1>
           <pre className='p-1 text-xs text-subdued overflow-auto'>{new Error().stack}</pre>
-        </Flex>
-      </Column.Segment>
+        </div>
+      </Column.Center>
 
-      <Column.Segment asChild>
+      <Column.Center>
         <div className='p-1 bg-green-500 text-black'>Footer</div>
-      </Column.Segment>
+      </Column.Center>
     </Column.Root>
   );
 };
@@ -76,3 +84,98 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
+
+const InputList = ({ items = 50 }: { items?: number }) => (
+  <div className='flex flex-col gap-2'>
+    {Array.from({ length: items }).map((_, index) => (
+      <Input.Root key={index}>
+        <Input.TextInput value={`Item ${index + 1}`} readOnly />
+      </Input.Root>
+    ))}
+  </div>
+);
+
+export const WithScrollArea = {
+  decorators: [withLayout({ layout: 'column' })],
+  render: () => (
+    <Column.Root classNames='overflow-hidden' gutter='md'>
+      <Column.Center>
+        <h2>Header</h2>
+      </Column.Center>
+      <ScrollArea.Root padding centered orientation='vertical'>
+        <ScrollArea.Viewport>
+          <InputList items={30} />
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
+      <Column.Center>
+        <h2>Footer</h2>
+      </Column.Center>
+    </Column.Root>
+  ),
+};
+
+/**
+ * Column.Center places a single element in the center column of the parent grid.
+ * Preferred for centered content — safe to nest
+ * compound components (Form.Root, Editor.Root, etc.) that render `display: contents`.
+ */
+export const WithCenter: Story = {
+  decorators: [withLayout({ classNames: 'w-[25rem]' })],
+  render: () => (
+    <Column.Root gutter='md'>
+      <Column.Center>
+        <h2>Header (Column.Center)</h2>
+      </Column.Center>
+      <Column.Center classNames='flex flex-col'>
+        <p>This text is inside Column.Center. It sits in the central column between the gutters.</p>
+        <Input.Root>
+          <Input.Label>Name</Input.Label>
+          <Input.TextInput placeholder='Enter name' />
+        </Input.Root>
+      </Column.Center>
+      <Column.Center>
+        <h2>Footer (Column.Center)</h2>
+      </Column.Center>
+    </Column.Root>
+  ),
+};
+
+/**
+ * ScrollArea auto-bleeds inside Column.Root (via [.dx-column_&]:col-span-full).
+ * No Column.Bleed wrapper needed.
+ */
+export const WithScrollAreaAutoBleed: Story = {
+  decorators: [withLayout({ layout: 'column', classNames: 'w-[25rem]' })],
+  render: () => (
+    <Column.Root classNames='overflow-hidden' gutter='md'>
+      <Column.Center>
+        <h2>Header (Column.Center)</h2>
+      </Column.Center>
+      <ScrollArea.Root orientation='vertical' padding thin>
+        <ScrollArea.Viewport>
+          <InputList items={30} />
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
+      <Column.Center>
+        <h2>Footer (Column.Center)</h2>
+      </Column.Center>
+    </Column.Root>
+  ),
+};
+
+export const Experimental = {
+  render: () => {
+    return (
+      <div className='grid grid-cols-[2rem_1fr_2rem]'>
+        <div className='col-span-full grid grid-cols-subgrid'>
+          <div className='bg-red-surface'>A</div>
+          <div className='bg-green-surface'>B</div>
+          <div className='bg-blue-surface'>C</div>
+        </div>
+        <div className='col-span-full grid grid-cols-subgrid col-start-2'>
+          <div className='bg-green-surface'>B</div>
+        </div>
+      </div>
+    );
+  },
+};