@dxos/react-ui 0.8.4-main.c85a9c8dae → 0.8.4-main.d05539e30a

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,31 +25,47 @@ 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.Segment asChild>
-        <div className='py-2'>
+      <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.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>
   );
 };
@@ -70,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>
+    );
+  },
+};

package/src/primitives/Column/Column.tsx

@@ -4,8 +4,9 @@
 
 import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
-import React, { type CSSProperties, forwardRef } from 'react';
+import React, { type CSSProperties } from 'react';
 
+import { composableProps, slottable } from '@dxos/ui-theme';
 import { type SlottableProps } from '@dxos/ui-types';
 
 import { useThemeContext } from '../../hooks';
@@ -16,53 +17,61 @@ import { useThemeContext } from '../../hooks';
 
 const COLUMN_ROOT_NAME = 'Column.Root';
 
-type GutterSize = 'sm' | 'md' | 'lg' | 'rail';
+type GutterSize = 'xs' | 'sm' | 'md' | 'lg';
 
 const gutterSizes: Record<GutterSize, string> = {
+  xs: 'var(--dx-gutter-xs)',
   sm: 'var(--dx-gutter-sm)',
   md: 'var(--dx-gutter-md)',
   lg: 'var(--dx-gutter-lg)',
-  rail: 'var(--dx-rail-item)',
 };
 
-type ColumnRootProps = SlottableProps<HTMLDivElement> & { gutter?: GutterSize };
+type ColumnRootProps = { gutter?: GutterSize };
 
 /**
- * Creates a vertical channel with left/right gutter columns.
- * The `--gutter` CSS variable is set for nested components (Dialog, ScrollArea, Form.Viewport, etc.).
- * Use `gutter='rail'` for icon-slot row layouts (Card); `gutter='md'` for whitespace layouts (Dialog).
- * Direct children must use Column.Row (spans all 3 cols) or Column.Segment (center col only).
+ * Creates a 3-column CSS grid with left/right gutter columns and a center content column.
+ * Sets `--gutter` and `--dx-col` CSS variables for nested components.
  *
- * NOTE: The theme applies a `dx-column` marker class to this element.
- * ScrollArea.Root detects this via `[.dx-column_&]:col-span-full` to span all 3 grid columns,
- * ensuring scroll content extends under the gutters rather than being confined to the center column.
- * The `--gutter` CSS variable is also consumed by ScrollArea's `margin` option to align scrollbar spacing.
+ * `--dx-col` defaults to `2 / span 1` (center column),
+ * enabling `withColumn` utilities to cascade the correct grid placement to slotted children.
+ *
+ * Direct children participate in the grid in one of several ways:
+ * - **Column.Center** — places element in the center column (col 2). Preferred for plain content.
+ * - **Column.Bleed** — spans all 3 columns gutter-to-gutter. Preferred for `ScrollArea` and
+ *   other content that should ignore the gutters.
+ * - **Column.Row** — 3-col subgrid row (icons in gutters, content in center).
+ *
+ * Use `withColumn.center()` / `withColumn.bleed()` helpers to apply placement on slotted elements.
+ *
+ * Gutter sizes: `'sm'` for compact layouts (Dialog); `'md'` (default); `'lg'` for wider spacing.
  */
-const Root = forwardRef<HTMLDivElement, ColumnRootProps>(
-  ({ classNames, className, asChild, role, children, gutter = 'md', ...props }, forwardedRef) => {
+const ColumnRoot = slottable<HTMLDivElement, ColumnRootProps>(
+  ({ children, asChild, role, gutter = 'md', ...props }, forwardedRef) => {
+    const { className, ...rest } = composableProps(props);
+    const Comp = asChild ? Slot : Primitive.div;
     const { tx } = useThemeContext();
-    const Component = asChild ? Slot : Primitive.div;
     const gutterSize = gutterSizes[gutter];
     return (
-      <Component
-        {...props}
+      <Comp
+        {...rest}
         role={role ?? 'none'}
         style={
           {
             '--gutter': gutterSize,
+            '--dx-col': '2 / span 1',
             gridTemplateColumns: [gutterSize, 'minmax(0,1fr)', gutterSize].join(' '),
           } as CSSProperties
         }
-        className={tx('column.root', { gutter }, [className, classNames])}
+        className={tx('column.root', { gutter }, className)}
         ref={forwardedRef}
       >
         {children}
-      </Component>
+      </Comp>
     );
   },
 );
 
-Root.displayName = COLUMN_ROOT_NAME;
+ColumnRoot.displayName = COLUMN_ROOT_NAME;
 
 //
 // Row
@@ -70,87 +79,87 @@ Root.displayName = COLUMN_ROOT_NAME;
 
 const COLUMN_ROW_NAME = 'Column.Row';
 
-type ColumnRowProps = SlottableProps<HTMLDivElement>;
+type ColumnRowProps = {};
 
 /**
  * Spans all 3 columns of the parent Column.Root and uses CSS subgrid to inherit their sizing.
  * Children map to: [col-1: icon/slot] [col-2: content] [col-3: icon/action].
  * Must be a direct child of Column.Root.
  */
-const Row = forwardRef<HTMLDivElement, ColumnRowProps>(
-  ({ classNames, className, asChild, role, children, ...props }, forwardedRef) => {
-    const { tx } = useThemeContext();
-    const Component = asChild ? Slot : Primitive.div;
-    return (
-      <Component
-        {...props}
-        className={tx('column.row', {}, [className, classNames])}
-        role={role ?? 'none'}
-        ref={forwardedRef}
-      >
-        {children}
-      </Component>
-    );
-  },
-);
-
-Row.displayName = COLUMN_ROW_NAME;
+const ColumnRow = slottable<HTMLDivElement, ColumnRowProps>(({ children, asChild, role, ...props }, forwardedRef) => {
+  const { className, ...rest } = composableProps(props);
+  const Comp = asChild ? Slot : Primitive.div;
+  const { tx } = useThemeContext();
+  return (
+    <Comp {...rest} role={role ?? 'none'} className={tx('column.row', {}, className)} ref={forwardedRef}>
+      {children}
+    </Comp>
+  );
+});
+
+ColumnRow.displayName = COLUMN_ROW_NAME;
 
 //
-// Segment
+// Bleed
 //
 
-const COLUMN_SEGMENT_NAME = 'Column.Segment';
+const COLUMN_BLEED_NAME = 'Column.Bleed';
 
-type ColumnSegmentProps = SlottableProps<HTMLDivElement>;
+type ColumnBleedProps = SlottableProps;
 
 /**
- * Occupies only the center column (col-2) of the parent Column.Root grid.
- * Use `asChild` to merge grid positioning onto the child element, eliminating the wrapper div.
- * NOTE: Must not use overflow-hidden here since it will clip input focus rings.
+ * Spans all 3 columns of the parent Column.Root (gutter-to-gutter).
+ * Establishes a CSS subgrid so that grandchildren can participate in the parent column tracks.
+ * Use for `ScrollArea`, full-width dividers, tables, or any content that should ignore the gutters.
  */
-const Segment = forwardRef<HTMLDivElement, ColumnSegmentProps>(
-  ({ classNames, className, asChild, role, children, ...props }, forwardedRef) => {
-    const { tx } = useThemeContext();
-    const Component = asChild ? Slot : Primitive.div;
-
-    if (asChild) {
-      // With asChild, merge col-start-2 directly onto the child — no contents wrapper needed.
-      return (
-        <Component
-          {...props}
-          role={role ?? 'none'}
-          className={tx('column.segment', {}, [className, classNames])}
-          ref={forwardedRef}
-        >
-          {children}
-        </Component>
-      );
-    }
+const ColumnBleed = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const { tx } = useThemeContext();
+  const { className, ...rest } = composableProps(props);
+  const Comp = asChild ? Slot : Primitive.div;
+  return (
+    <Comp {...rest} className={tx('column.bleed', {}, className)} ref={forwardedRef}>
+      {children}
+    </Comp>
+  );
+});
+
+ColumnBleed.displayName = COLUMN_BLEED_NAME;
 
-    return (
-      <Component
-        {...props}
-        className={tx('column.segment', {}, [className, classNames])}
-        role={role}
-        ref={forwardedRef}
-      >
-        <div className='contents'>{children}</div>
-      </Component>
-    );
-  },
-);
+//
+// Center
+//
+
+const COLUMN_CENTER_NAME = 'Column.Center';
 
-Segment.displayName = COLUMN_SEGMENT_NAME;
+type ColumnCenterProps = SlottableProps;
+
+/**
+ * Places its element in column 2 (the center track between gutters) of the parent Column.Root.
+ * Does NOT use subgrid — placement is explicit on this element only, so it is safe to nest
+ * arbitrary compound components (including ones that render `display: contents` wrappers).
+ */
+const ColumnCenter = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const { tx } = useThemeContext();
+  const { className, ...rest } = composableProps(props);
+  const Comp = asChild ? Slot : Primitive.div;
+  return (
+    <Comp {...rest} className={tx('column.center', {}, className)} ref={forwardedRef}>
+      {children}
+    </Comp>
+  );
+});
+
+ColumnCenter.displayName = COLUMN_CENTER_NAME;
 
 //
 // Column
 //
 
 export const Column = {
-  Root,
-  Row,
-  Segment,
+  Root: ColumnRoot,
+  Row: ColumnRow,
+  Bleed: ColumnBleed,
+  Center: ColumnCenter,
 };
 
-export type { ColumnRootProps, ColumnRowProps, ColumnSegmentProps };
+export type { ColumnRootProps, ColumnRowProps, ColumnBleedProps, ColumnCenterProps };

package/src/primitives/Container/Container.stories.tsx

@@ -0,0 +1,29 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { withLayout, withTheme } from '../../testing';
+import { Container } from './Container';
+
+const DefaultStory = () => (
+  <Container asChild>
+    <div className='grid place-items-center border border-red-500'>Hello</div>
+  </Container>
+);
+
+const meta: Meta = {
+  title: 'ui/react-ui-core/primitives/Container',
+  component: Container,
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/primitives/Container/Container.tsx

@@ -0,0 +1,19 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React from 'react';
+
+import { composableProps, mx, slottable } from '@dxos/ui-theme';
+
+export const Container = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const { className, ...rest } = composableProps<HTMLDivElement>(props);
+  const Comp = asChild ? Slot : Primitive.div;
+  return (
+    <Comp {...rest} className={mx('dx-container', className)} ref={forwardedRef}>
+      {children}
+    </Comp>
+  );
+});

package/src/primitives/Container/index.ts

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

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

@@ -8,7 +8,6 @@ import React from 'react';
 import { type ChromaticPalette } from '@dxos/ui-types';
 
 import { withLayout, withTheme } from '../../testing';
-
 import { Flex } from './Flex';
 
 const Cell = ({ label, hue }: { label: string; hue: ChromaticPalette }) => (