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

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

@@ -4,11 +4,11 @@
 
 import { useContext } from 'react';
 
-import { type Density } from '@dxos/react-ui-types';
+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/hooks/useElevationContext.ts

@@ -4,7 +4,7 @@
 
 import { useContext } from 'react';
 
-import { type Elevation } from '@dxos/react-ui-types';
+import { type Elevation } from '@dxos/ui-types';
 
 import { ElevationContext } from '../components';
 

package/src/hooks/useSafeArea.ts

@@ -4,7 +4,7 @@
 
 import { useCallback, useState } from 'react';
 
-import { useResize } from '@dxos/react-hooks';
+import { useViewportResize } from '@dxos/react-hooks';
 
 export type SafeAreaPadding = Record<'top' | 'right' | 'bottom' | 'left', number>;
 
@@ -20,6 +20,7 @@ export const useSafeArea = (): SafeAreaPadding => {
       left: parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--safe-area-left')),
     });
   }, []);
-  useResize(handleResize);
+
+  useViewportResize(handleResize);
   return padding;
 };

package/src/hooks/useVisualViewport.ts

@@ -2,11 +2,11 @@
 // Copyright 2023 DXOS.org
 //
 
-import { useCallback, type useEffect, useState } from 'react';
+import { useCallback, useState } from 'react';
 
-import { useResize } from '@dxos/react-hooks';
+import { useViewportResize } from '@dxos/react-hooks';
 
-export const useVisualViewport = (deps?: Parameters<typeof useEffect>[1]) => {
+export const useVisualViewport = (deps?: Parameters<typeof useViewportResize>[1]) => {
   const [width, setWidth] = useState<number | null>(null);
   const [height, setHeight] = useState<number | null>(null);
 
@@ -17,7 +17,7 @@ export const useVisualViewport = (deps?: Parameters<typeof useEffect>[1]) => {
     }
   }, []);
 
-  useResize(handleResize);
+  useViewportResize(handleResize, deps);
 
   return { width, height };
 };

package/src/index.ts

@@ -6,8 +6,9 @@ export { type Resource, type TFunction } from 'i18next';
 export { Trans } from 'react-i18next';
 
 export * from '@dxos/react-hooks';
-export type * from '@dxos/react-ui-types';
+export * from '@dxos/ui-types';
 
 export * from './components';
 export * from './hooks';
+export * from './primitives';
 export * from './util';

package/src/playground/Controls.stories.tsx

@@ -2,13 +2,11 @@
 // Copyright 2022 DXOS.org
 //
 
-import '@dxos-theme';
-
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useState } from 'react';
 
 import { Icon, Input, Select, Toggle, Toolbar } from '../components';
-import { withSurfaceVariantsLayout, withTheme } from '../testing';
+import { withLayoutVariants, withTheme } from '../testing';
 
 const DefaultStory = () => {
   const [checked, setChecked] = useState<boolean>(false);
@@ -33,9 +31,6 @@ const DefaultStory = () => {
             </Select.Content>
           </Select.Portal>
         </Select.Root>
-        {/* TODO(burdon): Highlight is cyan. */}
-        {/* TODO(burdon): Show vertical divider by default. */}
-        {/* TODO(burdon): Icon sizes should adapt to density. */}
         <Toolbar.ToggleGroup type='multiple'>
           <Toolbar.ToggleGroupItem value='a'>
             <Icon icon='ph--text-b--regular' />
@@ -47,7 +42,6 @@ const DefaultStory = () => {
             <Icon icon='ph--text-underline--regular' />
           </Toolbar.ToggleGroupItem>
         </Toolbar.ToggleGroup>
-        {/* TODO(burdon): Highlight isn't shown. */}
         <Toolbar.ToggleGroup type='single' defaultValue='a'>
           <Toolbar.ToggleGroupItem value='a'>
             <Icon icon='ph--file-ts--regular' />
@@ -61,11 +55,9 @@ const DefaultStory = () => {
             <Icon icon='ph--bug--regular' />
           </Toggle>
         </Toolbar.Button>
-        {/* TODO(burdon): Should not be 'is-full' by default. */}
         <Input.Root>
           <Input.TextInput placeholder='Enter text...' />
         </Input.Root>
-        {/* TODO(burdon): Checkbox collapsed. */}
         <Input.Root>
           <Input.Checkbox checked={checked} onCheckedChange={(value) => setChecked(!!value)} />
           <Input.Label>Checkbox</Input.Label>
@@ -83,10 +75,9 @@ const DefaultStory = () => {
 };
 
 const meta = {
-  title: 'ui/react-ui-core/Playground/Controls',
+  title: 'ui/react-ui-core/playground/Controls',
   render: DefaultStory,
-  decorators: [withSurfaceVariantsLayout(), withTheme],
-  parameters: { chromatic: { disableSnapshot: false } },
+  decorators: [withTheme(), withLayoutVariants()],
 } satisfies Meta<typeof Icon>;
 
 export default meta;

package/src/playground/Custom.stories.tsx

@@ -2,23 +2,12 @@
 // Copyright 2022 DXOS.org
 //
 
-import '@dxos-theme';
-
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
 import { Button, type ButtonProps, IconButton, Tooltip } from '../components';
 import { withTheme } from '../testing';
 
-// TODO(burdon): Change density to 3 or 4 sizes: (large, medium, small; or 22, 28, 32, 40)
-// TODO(burdon): IconButton should be square if no text.
-// TODO(burdon): IconButton icon should be auto-sized based on density.
-
-// TODO(burdon): Remove custom padding from all Buttons.
-
-// TODO(burdon): Forms w/ labels.
-// TODO(burdon): Card preview with sections.
-
 const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
   return (
     <Tooltip.Provider>
@@ -31,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'
             />
@@ -54,15 +42,14 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
             </Button>
           </div>
           <div className='flex justify-center'>
-            <IconButton {...args} label='Test' icon='ph--atom--regular' size={5} 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
-              size={5}
               density='fine'
               classNames='py-1 px-1.5'
             />
@@ -72,7 +59,7 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
         {/* Small */}
         <div className='grid grid-cols-3 gap-4'>
           <div className='flex justify-center'>
-            <Button {...args} density='fine' classNames={'!h-[24px] !text-[14px] p-0 px-1.5 min-bs-0'}>
+            <Button {...args} density='fine' classNames={'!h-[24px] !text-[14px] p-0 px-1.5 min-h-0'}>
               {children}
             </Button>
           </div>
@@ -80,39 +67,36 @@ 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-bs-0 gap-0.5'}
+              classNames={'!h-[24px] !text-[14px] p-1 min-h-0 gap-0.5'}
             />
           </div>
           <div className='flex justify-center'>
             <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-bs-0'}
+              classNames={'!h-[24px] !text-[14px] p-1 min-h-0'}
             />
           </div>
         </div>
 
         {/* TODO(burdon): Full variant with max width. */}
         <div className='flex justify-center'>
-          <Button classNames='w-full max-w-[15rem] rounded' variant='default'>
+          <Button classNames='w-full max-w-[15rem] rounded-sm' variant='default'>
             Test
           </Button>
         </div>
         <div className='flex justify-center'>
           {/* TODO(burdon): Option to have button on RHS. Default size for icon should be 5 for this (medium) density. */}
           <IconButton
-            classNames='w-full max-w-[15rem] rounded'
+            classNames='w-full max-w-[15rem] rounded-sm'
             variant='primary'
             icon='ph--arrows-clockwise--regular'
             label='Test'
-            size={5}
           />
         </div>
       </div>
@@ -121,11 +105,13 @@ const DefaultStory = ({ children, ...args }: Omit<ButtonProps, 'ref'>) => {
 };
 
 const meta = {
-  title: 'ui/react-ui-core/Playground/Custom',
+  title: 'ui/react-ui-core/playground/Custom',
   component: Button,
   render: DefaultStory,
-  decorators: [withTheme],
-  parameters: { layout: 'centered' },
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
 } satisfies Meta<typeof Button>;
 
 export default meta;

package/src/playground/Typography.stories.tsx

@@ -2,8 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
-
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
@@ -11,7 +9,7 @@ import { withTheme } from '../testing';
 
 const DefaultStory = () => {
   return (
-    <div className='mli-auto p-8 max-is-[60rem] space-b-4'>
+    <div className='mx-auto p-8 max-w-[60rem] space-b-4'>
       <h1 className='text-4xl font-medium'>
         Việc <span className='italic'>thừa</span> nhận{' '}
         <span className='font-mono bg-neutral-500/10'>
@@ -45,10 +43,9 @@ const DefaultStory = () => {
 };
 
 const meta = {
-  title: 'ui/react-ui-core/Playground/Typography',
+  title: 'ui/react-ui-core/playground/Typography',
   render: DefaultStory,
-  decorators: [withTheme],
-  parameters: { chromatic: { disableSnapshot: false } },
+  decorators: [withTheme()],
 } satisfies Meta<typeof DefaultStory>;
 
 export default meta;

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

@@ -0,0 +1,181 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { Input, ScrollArea } from '../../components';
+import { withLayout, withTheme } from '../../testing';
+import { Column } from './Column';
+
+const List = () => {
+  return (
+    <ScrollArea.Root centered>
+      <ScrollArea.Viewport>
+        {Array.from({ length: 100 }).map((_, i) => (
+          <Input.Root key={i}>
+            <Input.TextInput value={`Item ${i}`} readOnly />
+          </Input.Root>
+        ))}
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};
+
+const DefaultStory = () => {
+  return (
+    <Column.Root classNames='overflow-hidden' gutter='md'>
+      <Column.Center>
+        <h1 className='p-1 bg-blue-500 text-black'>Header</h1>
+      </Column.Center>
+
+      <Column.Row>
+        <div className='p-1 bg-blue-500'>A</div>
+        <div className='p-1 bg-red-500'>B</div>
+        <div className='p-1 bg-blue-500'>C</div>
+      </Column.Row>
+
+      <Column.Center asChild>
+        <div>
+          <Input.Root>
+            <Input.TextInput placeholder='Search' />
+          </Input.Root>
+        </div>
+      </Column.Center>
+
+      <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.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>
+        </div>
+      </Column.Center>
+
+      <Column.Center>
+        <div className='p-1 bg-green-500 text-black'>Footer</div>
+      </Column.Center>
+    </Column.Root>
+  );
+};
+
+const meta: Meta = {
+  title: 'ui/react-ui-core/primitives/Column',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'w-[25rem]' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+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>
+    );
+  },
+};