@dxos/react-ui 0.8.4-main.3eb6e50203 → 0.8.4-main.3fbcb4aa9b

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>
+    );
+  },
+};

package/src/primitives/Column/Column.tsx

@@ -0,0 +1,165 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, { type CSSProperties } from 'react';
+
+import { composableProps, slottable } from '@dxos/ui-theme';
+import { type SlottableProps } from '@dxos/ui-types';
+
+import { useThemeContext } from '../../hooks';
+
+//
+// Root
+//
+
+const COLUMN_ROOT_NAME = 'Column.Root';
+
+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)',
+};
+
+type ColumnRootProps = { gutter?: GutterSize };
+
+/**
+ * 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.
+ *
+ * `--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 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 gutterSize = gutterSizes[gutter];
+    return (
+      <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)}
+        ref={forwardedRef}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+ColumnRoot.displayName = COLUMN_ROOT_NAME;
+
+//
+// Row
+//
+
+const COLUMN_ROW_NAME = 'Column.Row';
+
+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 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;
+
+//
+// Bleed
+//
+
+const COLUMN_BLEED_NAME = 'Column.Bleed';
+
+type ColumnBleedProps = SlottableProps;
+
+/**
+ * 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 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;
+
+//
+// Center
+//
+
+const COLUMN_CENTER_NAME = 'Column.Center';
+
+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: ColumnRoot,
+  Row: ColumnRow,
+  Bleed: ColumnBleed,
+  Center: ColumnCenter,
+};
+
+export type { ColumnRootProps, ColumnRowProps, ColumnBleedProps, ColumnCenterProps };

package/src/primitives/Column/index.ts

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

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

@@ -1,67 +1,29 @@
 //
-// Copyright 2025 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { Input } from '../../components';
-import { withTheme } from '../../testing';
+import { withLayout, withTheme } from '../../testing';
+import { Container } from './Container';
 
-import { Container, type ContainerRootProps } from './Container';
+const DefaultStory = () => (
+  <Container asChild>
+    <div className='grid place-items-center border border-red-500'>Hello</div>
+  </Container>
+);
 
-const DefaultStory = (props: ContainerRootProps) => {
-  return (
-    <div className='plb-2 is-[20rem] border border-separator rounded-sm'>
-      <Container.Root {...props}>
-        <Container.Column>
-          <Input.Root>
-            <Input.Label>Label</Input.Label>
-            <Input.TextInput />
-          </Input.Root>
-        </Container.Column>
-      </Container.Root>
-    </div>
-  );
-};
-
-const meta: Meta<typeof Container.Root> = {
+const meta: Meta = {
   title: 'ui/react-ui-core/primitives/Container',
-  component: Container.Root,
+  component: Container,
   render: DefaultStory,
-  decorators: [withTheme()],
-  parameters: {
-    layout: 'centered',
-  },
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: { layout: 'fullscreen' },
 };
 
 export default meta;
 
 type Story = StoryObj<typeof meta>;
 
-// TODO(burdon): Requires container.
-export const Default = () => {
-  return (
-    <Container.Root>
-      <Container.Column>Column</Container.Column>
-    </Container.Root>
-  );
-};
-
-export const SM: Story = {
-  args: {
-    variant: 'sm',
-  },
-};
-
-export const MD: Story = {
-  args: {
-    variant: 'md',
-  },
-};
-
-export const LG: Story = {
-  args: {
-    variant: 'lg',
-  },
-};
+export const Default: Story = {};

package/src/primitives/Container/Container.tsx

@@ -1,79 +1,19 @@
 //
-// Copyright 2025 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
-import { createContext } from '@radix-ui/react-context';
 import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
-import React, { type PropsWithChildren, type Ref, forwardRef } from 'react';
-
-import { type ColumnPadding } from '@dxos/ui-theme';
-import { type SlottableProps } from '@dxos/ui-types';
-
-import { useThemeContext } from '../../hooks';
-
-// TODO(burdon): Replace Form, Container, Card spacing.
-// TODO(burdon): Scrolling (reconcile with Mosaic Viewport).
-// TODO(burdon): Reconcile AnchoredOverflow.
-
-//
-// Context
-//
-
-type ContainerContext = {
-  variant?: ColumnPadding;
-};
-
-const [ContainerProvider, useContext] = createContext<ContainerContext>('Container');
-
-//
-// Root
-//
-
-type RootProps = PropsWithChildren<Partial<ContainerContext>>;
-
-const Root = ({ variant, children }: RootProps) => {
-  return <ContainerProvider {...{ variant }}>{children}</ContainerProvider>;
-};
-
-//
-// Column
-//
-
-const CONTAINER_COLUMN_NAME = 'Container.Column';
-
-type ColumnProps = SlottableProps<HTMLDivElement> & { variant?: ColumnPadding };
-
-const Column = forwardRef(
-  (
-    { classNames, className, asChild, role = 'none', children, variant, ...props }: ColumnProps,
-    ref: Ref<HTMLDivElement>,
-  ) => {
-    const { tx } = useThemeContext();
-    const Root = asChild ? Slot : Primitive.div;
-    const context = useContext(CONTAINER_COLUMN_NAME);
-    return (
-      <Root
-        {...props}
-        className={tx('container.column', { variant: variant ?? context.variant }, [className, classNames])}
-        role={role}
-        ref={ref}
-      >
-        {children}
-      </Root>
-    );
-  },
-);
-
-Column.displayName = CONTAINER_COLUMN_NAME;
-
-//
-// Container
-//
-
-export const Container = {
-  Root,
-  Column,
-};
-
-export type { RootProps as ContainerRootProps, ColumnProps as ContainerColumnProps };
+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

@@ -3,4 +3,3 @@
 //
 
 export * from './Container';
-export * from './Layout';

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

@@ -0,0 +1,57 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+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 }) => (
+  <div data-hue={hue} className='flex w-full dx-panel p-2 text-sm font-mono border rounded-sm'>
+    {label}
+  </div>
+);
+
+const RowStory = () => (
+  <Flex classNames='gap-2 p-2'>
+    <Cell label='A' hue='red' />
+    <Cell label='B' hue='green' />
+    <Cell label='C' hue='blue' />
+  </Flex>
+);
+
+const ColumnStory = () => (
+  <Flex column classNames='gap-2 p-2'>
+    <Cell label='A' hue='red' />
+    <Cell label='B' hue='green' />
+    <Cell label='C' hue='blue' />
+  </Flex>
+);
+
+const GrowStory = () => (
+  <Flex column grow classNames='gap-2 p-2'>
+    <Cell label='Header' hue='yellow' />
+    <Flex grow>
+      <Cell label='Content (grows)' hue='blue' />
+    </Flex>
+    <Cell label='Footer' hue='orange' />
+  </Flex>
+);
+
+const meta: Meta = {
+  title: 'ui/react-ui-core/primitives/Flex',
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Row: Story = { render: RowStory };
+export const Column: Story = { render: ColumnStory };
+export const Grow: Story = { render: GrowStory };

package/src/primitives/Flex/Flex.tsx

@@ -2,25 +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 ThemedClassName } from '@dxos/ui-types';
+import { composableProps, mx, slottable } from '@dxos/ui-theme';
 
-export type FlexProps = ThemedClassName<
-  HTMLAttributes<HTMLDivElement> & {
-    column?: boolean;
-    grow?: boolean;
-  }
->;
+export type FlexProps = { column?: boolean; grow?: boolean };
 
-export const Flex = ({ children, classNames, role, column, grow }: FlexProps) => {
-  return (
-    <div
-      role={role ?? 'none'}
-      className={mx('flex', column && 'flex-col', grow && 'flex-1 overflow-hidden', 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

@@ -0,0 +1,56 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+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 }) => (
+  <div data-hue={hue} className='dx-panel p-2 text-sm font-mono border rounded-sm'>
+    {label}
+  </div>
+);
+
+const ColsStory = () => (
+  <Grid cols={3} classNames='gap-2 p-2'>
+    <Cell label='Row 1' hue='red' />
+    <Cell label='Row 2' hue='green' />
+    <Cell label='Row 3' hue='blue' />
+  </Grid>
+);
+
+const RowsStory = () => (
+  <Grid rows={3} classNames='gap-2 p-2'>
+    <Cell label='Row 1' hue='red' />
+    <Cell label='Row 2' hue='green' />
+    <Cell label='Row 3' hue='blue' />
+  </Grid>
+);
+
+const MixedStory = () => (
+  <Grid cols={2} rows={2} classNames='gap-2 p-2'>
+    <Cell label='A' hue='red' />
+    <Cell label='B' hue='green' />
+    <Cell label='C' hue='blue' />
+    <Cell label='D' hue='yellow' />
+  </Grid>
+);
+
+const meta: Meta = {
+  title: 'ui/react-ui-core/primitives/Grid',
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Cols: Story = { render: ColsStory };
+export const Rows: Story = { render: RowsStory };
+export const Mixed: Story = { render: MixedStory };