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

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 }) => (

package/src/primitives/Flex/Flex.tsx

@@ -2,26 +2,26 @@
 // Copyright 2026 DXOS.org
 //
 
-import React, { type HTMLAttributes } from 'react';
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React from 'react';
 
-import { mx } from '@dxos/ui-theme';
-import { type ComposableProps } from '@dxos/ui-types';
+import { composableProps, mx, slottable } from '@dxos/ui-theme';
 
-export type FlexProps = ComposableProps<
-  HTMLAttributes<HTMLDivElement> & {
-    column?: boolean;
-    grow?: boolean;
-  }
->;
+export type FlexProps = { column?: boolean; grow?: boolean };
 
-export const Flex = ({ children, classNames, className, role, column, grow, ...props }: FlexProps) => {
-  return (
-    <div
-      {...props}
-      role={role ?? 'none'}
-      className={mx('flex', column && 'flex-col', grow && 'flex-1 overflow-hidden', className, classNames)}
-    >
-      {children}
-    </div>
-  );
-};
+export const Flex = slottable<HTMLDivElement, FlexProps>(
+  ({ children, asChild, column, grow, ...props }, forwardedRef) => {
+    const { className, ...rest } = composableProps(props);
+    const Comp = asChild ? Slot : Primitive.div;
+    return (
+      <Comp
+        ref={forwardedRef}
+        {...rest}
+        className={mx('flex', column && 'flex-col', grow && 'flex-1 overflow-hidden', className)}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);

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

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

package/src/primitives/Grid/Grid.tsx

@@ -2,42 +2,29 @@
 // Copyright 2026 DXOS.org
 //
 
-import React, { type HTMLAttributes } from 'react';
+import React from 'react';
 
-import { mx } from '@dxos/ui-theme';
-import { type ComposableProps } from '@dxos/ui-types';
+import { composable, composableProps, mx } from '@dxos/ui-theme';
 
-export type GridProps = ComposableProps<
-  HTMLAttributes<HTMLDivElement> & {
-    cols?: number;
-    rows?: number;
-    grow?: boolean;
-  }
->;
+export type GridProps = { cols?: number; rows?: number; grow?: boolean };
 
-export const Grid = ({
-  children,
-  classNames,
-  className,
-  style,
-  role,
-  cols,
-  rows,
-  grow = true,
-  ...props
-}: GridProps) => {
-  return (
-    <div
-      {...props}
-      role={role ?? 'none'}
-      style={{
-        gridTemplateColumns: cols ? `repeat(${cols}, 1fr)` : undefined,
-        gridTemplateRows: rows ? `repeat(${rows}, 1fr)` : undefined,
-        ...style,
-      }}
-      className={mx('grid overflow-hidden', grow && 'dx-container', className, classNames)}
-    >
-      {children}
-    </div>
-  );
-};
+export const Grid = composable<HTMLDivElement, GridProps>(
+  ({ children, style, role, cols, rows, grow = true, ...props }, forwardedRef) => {
+    const { className, ...rest } = composableProps(props);
+    return (
+      <div
+        ref={forwardedRef}
+        {...rest}
+        role={role ?? 'none'}
+        className={mx('grid overflow-hidden', grow && 'dx-container', className)}
+        style={{
+          gridTemplateColumns: cols ? `repeat(${cols}, 1fr)` : undefined,
+          gridTemplateRows: rows ? `repeat(${rows}, 1fr)` : undefined,
+          ...style,
+        }}
+      >
+        {children}
+      </div>
+    );
+  },
+);

package/src/primitives/Panel/Panel.stories.tsx

@@ -5,14 +5,15 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { Input, ScrollArea, Toolbar } from '../../components';
-import { withLayout, withTheme } from '../../testing';
+import { composable, composableProps } from '@dxos/ui-theme';
 
+import { Input, ScrollArea, ScrollAreaRootProps, Toolbar } from '../../components';
+import { withLayout, withTheme } from '../../testing';
 import { Panel } from './Panel';
 
-const List = () => {
+const List = composable<HTMLDivElement, ScrollAreaRootProps>((props, forwardedRef) => {
   return (
-    <ScrollArea.Root margin role='list'>
+    <ScrollArea.Root centered {...composableProps(props, { role: 'list' })} ref={forwardedRef}>
       <ScrollArea.Viewport>
         {Array.from({ length: 100 }).map((_, i) => (
           <div key={i} role='listitem' className='p-1 hover:bg-hover-surface'>
@@ -22,11 +23,11 @@ const List = () => {
       </ScrollArea.Viewport>
     </ScrollArea.Root>
   );
-};
+});
 
 const DefaultStory = () => {
   return (
-    <Panel.Root className='dx-article'>
+    <Panel.Root className='dx-document'>
       <Panel.Toolbar asChild>
         <Toolbar.Root classNames='gap-2'>
           <Toolbar.IconButton icon='ph--plus--regular' variant='primary' label='Add' />
@@ -43,8 +44,8 @@ const DefaultStory = () => {
 
       <Panel.Statusbar asChild>
         <Toolbar.Root classNames='justify-between'>
-          <Toolbar.IconButton variant='ghost' icon='ph--house--regular' iconOnly label='Add' size={4} />
-          <Toolbar.IconButton variant='ghost' icon='ph--alarm--regular' iconOnly label='Status' size={4} />
+          <Toolbar.IconButton variant='ghost' icon='ph--house--regular' iconOnly label='Add' />
+          <Toolbar.IconButton variant='ghost' icon='ph--alarm--regular' iconOnly label='Status' />
         </Toolbar.Root>
       </Panel.Statusbar>
     </Panel.Root>

package/src/primitives/Panel/Panel.tsx

@@ -4,8 +4,9 @@
 
 import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
-import React, { forwardRef } from 'react';
+import React, { type CSSProperties } from 'react';
 
+import { composableProps, PanelStyleProps, slottable } from '@dxos/ui-theme';
 import { type SlottableProps } from '@dxos/ui-types';
 
 import { useThemeContext } from '../../hooks';
@@ -17,23 +18,24 @@ import { useThemeContext } from '../../hooks';
 const GRID_TEMPLATE_ROWS = 'auto 1fr auto';
 const GRID_TEMPLATE_AREAS = '"toolbar" "content" "statusbar"';
 
-type PanelRootProps = SlottableProps<HTMLDivElement>;
+type PanelRootProps = SlottableProps<{ style?: CSSProperties }>;
 
-const Root = forwardRef<HTMLDivElement, PanelRootProps>(
-  ({ classNames, className, asChild, children, role, ...props }, forwardedRef) => {
-    const { tx } = useThemeContext();
+const PanelRoot = slottable<HTMLDivElement, { style?: CSSProperties }>(
+  ({ children, asChild, role, style, ...props }, forwardedRef) => {
+    const { className, ...rest } = composableProps(props);
     const Comp = asChild ? Slot : Primitive.div;
+    const { tx } = useThemeContext();
     return (
       <Comp
-        ref={forwardedRef}
+        {...rest}
         role={role ?? 'none'}
-        {...props}
         style={{
           gridTemplateRows: GRID_TEMPLATE_ROWS,
           gridTemplateAreas: GRID_TEMPLATE_AREAS,
-          ...props.style,
+          ...style,
         }}
-        className={tx('panel.root', {}, [className, classNames])}
+        className={tx('panel.root', {}, className)}
+        ref={forwardedRef}
       >
         {children}
       </Comp>
@@ -41,97 +43,78 @@ const Root = forwardRef<HTMLDivElement, PanelRootProps>(
   },
 );
 
-Root.displayName = 'Panel.Root';
+PanelRoot.displayName = 'Panel.Root';
 
 //
 // Toolbar
 //
 
-type ToolbarProps = SlottableProps<HTMLDivElement>;
+type PanelToolbarProps = SlottableProps & Pick<PanelStyleProps, 'size'>;
 
-const Toolbar = forwardRef<HTMLDivElement, ToolbarProps>(
-  ({ classNames, className, asChild, children, ...props }, forwardedRef) => {
-    const { tx } = useThemeContext();
+const PanelToolbar = slottable<HTMLDivElement, Pick<PanelStyleProps, 'size'>>(
+  ({ children, asChild, size, ...props }, forwardedRef) => {
+    const { className, ...rest } = composableProps(props);
     const Comp = asChild ? Slot : Primitive.div;
+    const { tx } = useThemeContext();
     return (
-      <Comp
-        ref={forwardedRef}
-        data-slot='toolbar'
-        {...props}
-        className={tx('panel.toolbar', {}, [className, classNames])}
-      >
+      <Comp {...rest} data-slot='toolbar' className={tx('panel.toolbar', { size }, className)} ref={forwardedRef}>
         {children}
       </Comp>
     );
   },
 );
 
-Toolbar.displayName = 'Panel.Toolbar';
+PanelToolbar.displayName = 'Panel.Toolbar';
 
 //
 // Content
 //
 
-type ContentProps = SlottableProps<HTMLDivElement>;
+type PanelContentProps = SlottableProps;
 
-const Content = forwardRef<HTMLDivElement, ContentProps>(
-  ({ classNames, className, asChild, children, ...props }, forwardedRef) => {
-    const { tx } = useThemeContext();
-    const Comp = asChild ? Slot : Primitive.div;
-    return (
-      <Comp
-        ref={forwardedRef}
-        data-slot='content'
-        {...props}
-        className={tx('panel.content', {}, [className, classNames])}
-      >
-        {children}
-      </Comp>
-    );
-  },
-);
+const PanelContent = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const { className, ...rest } = composableProps(props);
+  const Comp = asChild ? Slot : Primitive.div;
+  const { tx } = useThemeContext();
+  return (
+    <Comp {...rest} data-slot='content' className={tx('panel.content', {}, className)} ref={forwardedRef}>
+      {children}
+    </Comp>
+  );
+});
 
-Content.displayName = 'Panel.Content';
+PanelContent.displayName = 'Panel.Content';
 
 //
 // Statusbar
 //
 
-type StatusbarProps = SlottableProps<HTMLDivElement>;
+type PanelStatusbarProps = SlottableProps & Pick<PanelStyleProps, 'size'>;
 
-const Statusbar = forwardRef<HTMLDivElement, StatusbarProps>(
-  ({ classNames, className, asChild, children, ...props }, forwardedRef) => {
-    const { tx } = useThemeContext();
+const PanelStatusbar = slottable<HTMLDivElement, Pick<PanelStyleProps, 'size'>>(
+  ({ children, asChild, size, ...props }, forwardedRef) => {
+    const { className, ...rest } = composableProps(props);
     const Comp = asChild ? Slot : Primitive.div;
+    const { tx } = useThemeContext();
     return (
-      <Comp
-        ref={forwardedRef}
-        data-slot='statusbar'
-        {...props}
-        className={tx('panel.statusbar', {}, [className, classNames])}
-      >
+      <Comp {...rest} data-slot='statusbar' className={tx('panel.statusbar', { size }, className)} ref={forwardedRef}>
         {children}
       </Comp>
     );
   },
 );
 
-Statusbar.displayName = 'Panel.Statusbar';
+PanelStatusbar.displayName = 'Panel.Statusbar';
 
 //
 // Panel
 //
 
 export const Panel = {
-  Root,
-  Toolbar,
-  Content,
-  Statusbar,
+  Root: PanelRoot,
+  Toolbar: PanelToolbar,
+  Content: PanelContent,
+  Statusbar: PanelStatusbar,
 };
 
-export type {
-  PanelRootProps,
-  ToolbarProps as PanelToolbarProps,
-  ContentProps as PanelContentProps,
-  StatusbarProps as PanelStatusbarProps,
-};
+export type { PanelRootProps, PanelToolbarProps, PanelContentProps, PanelStatusbarProps };

package/src/primitives/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './Column';
+export * from './Container';
 export * from './Flex';
 export * from './Grid';
 export * from './Panel';