@dxos/react-ui 0.8.4-main.406dc2a → 0.8.4-main.4a85c3132b

package/src/primitives/Column/Column.tsx

@@ -0,0 +1,156 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, { type CSSProperties, forwardRef } from 'react';
+
+import { type SlottableProps } from '@dxos/ui-types';
+
+import { useThemeContext } from '../../hooks';
+
+//
+// Root
+//
+
+const COLUMN_ROOT_NAME = 'Column.Root';
+
+type GutterSize = 'sm' | 'md' | 'lg' | 'rail';
+
+const gutterSizes: Record<GutterSize, string> = {
+  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 };
+
+/**
+ * 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).
+ *
+ * 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.
+ */
+const Root = forwardRef<HTMLDivElement, ColumnRootProps>(
+  ({ classNames, className, asChild, role, children, gutter = 'md', ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    const Component = asChild ? Slot : Primitive.div;
+    const gutterSize = gutterSizes[gutter];
+    return (
+      <Component
+        {...props}
+        role={role ?? 'none'}
+        style={
+          {
+            '--gutter': gutterSize,
+            gridTemplateColumns: [gutterSize, 'minmax(0,1fr)', gutterSize].join(' '),
+          } as CSSProperties
+        }
+        className={tx('column.root', { gutter }, [className, classNames])}
+        ref={forwardedRef}
+      >
+        {children}
+      </Component>
+    );
+  },
+);
+
+Root.displayName = COLUMN_ROOT_NAME;
+
+//
+// Row
+//
+
+const COLUMN_ROW_NAME = 'Column.Row';
+
+type ColumnRowProps = SlottableProps<HTMLDivElement>;
+
+/**
+ * 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;
+
+//
+// Segment
+//
+
+const COLUMN_SEGMENT_NAME = 'Column.Segment';
+
+type ColumnSegmentProps = SlottableProps<HTMLDivElement>;
+
+/**
+ * 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.
+ */
+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>
+      );
+    }
+
+    return (
+      <Component
+        {...props}
+        className={tx('column.segment', {}, [className, classNames])}
+        role={role}
+        ref={forwardedRef}
+      >
+        <div className='contents'>{children}</div>
+      </Component>
+    );
+  },
+);
+
+Segment.displayName = COLUMN_SEGMENT_NAME;
+
+//
+// Column
+//
+
+export const Column = {
+  Root,
+  Row,
+  Segment,
+};
+
+export type { ColumnRootProps, ColumnRowProps, ColumnSegmentProps };

package/src/primitives/Column/index.ts

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

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

@@ -0,0 +1,58 @@
+//
+// 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

@@ -0,0 +1,27 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type HTMLAttributes } from 'react';
+
+import { mx } from '@dxos/ui-theme';
+import { type ComposableProps } from '@dxos/ui-types';
+
+export type FlexProps = ComposableProps<
+  HTMLAttributes<HTMLDivElement> & {
+    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>
+  );
+};

package/src/primitives/Flex/index.ts

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

package/src/primitives/Grid/Grid.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 { 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 };

package/src/primitives/Grid/Grid.tsx

@@ -0,0 +1,43 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type HTMLAttributes } from 'react';
+
+import { mx } from '@dxos/ui-theme';
+import { type ComposableProps } from '@dxos/ui-types';
+
+export type GridProps = ComposableProps<
+  HTMLAttributes<HTMLDivElement> & {
+    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>
+  );
+};

package/src/primitives/Grid/index.ts

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

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

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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 { Panel } from './Panel';
+
+const List = () => {
+  return (
+    <ScrollArea.Root margin role='list'>
+      <ScrollArea.Viewport>
+        {Array.from({ length: 100 }).map((_, i) => (
+          <div key={i} role='listitem' className='p-1 hover:bg-hover-surface'>
+            Item {i}
+          </div>
+        ))}
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};
+
+const DefaultStory = () => {
+  return (
+    <Panel.Root className='dx-article'>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root classNames='gap-2'>
+          <Toolbar.IconButton icon='ph--plus--regular' variant='primary' label='Add' />
+          <Input.Root>
+            <Input.TextInput placeholder='Search' />
+          </Input.Root>
+          <Toolbar.IconButton icon='ph--dots-three-vertical--regular' iconOnly label='Menu' />
+        </Toolbar.Root>
+      </Panel.Toolbar>
+
+      <Panel.Content asChild>
+        <List />
+      </Panel.Content>
+
+      <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.Root>
+      </Panel.Statusbar>
+    </Panel.Root>
+  );
+};
+
+const meta: Meta = {
+  title: 'ui/react-ui-core/primitives/Panel',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/primitives/Panel/Panel.tsx

@@ -0,0 +1,137 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, { forwardRef } from 'react';
+
+import { type SlottableProps } from '@dxos/ui-types';
+
+import { useThemeContext } from '../../hooks';
+
+//
+// Root
+//
+
+const GRID_TEMPLATE_ROWS = 'auto 1fr auto';
+const GRID_TEMPLATE_AREAS = '"toolbar" "content" "statusbar"';
+
+type PanelRootProps = SlottableProps<HTMLDivElement>;
+
+const Root = forwardRef<HTMLDivElement, PanelRootProps>(
+  ({ classNames, className, asChild, children, role, ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    const Comp = asChild ? Slot : Primitive.div;
+    return (
+      <Comp
+        ref={forwardedRef}
+        role={role ?? 'none'}
+        {...props}
+        style={{
+          gridTemplateRows: GRID_TEMPLATE_ROWS,
+          gridTemplateAreas: GRID_TEMPLATE_AREAS,
+          ...props.style,
+        }}
+        className={tx('panel.root', {}, [className, classNames])}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+Root.displayName = 'Panel.Root';
+
+//
+// Toolbar
+//
+
+type ToolbarProps = SlottableProps<HTMLDivElement>;
+
+const Toolbar = forwardRef<HTMLDivElement, ToolbarProps>(
+  ({ classNames, className, asChild, children, ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    const Comp = asChild ? Slot : Primitive.div;
+    return (
+      <Comp
+        ref={forwardedRef}
+        data-slot='toolbar'
+        {...props}
+        className={tx('panel.toolbar', {}, [className, classNames])}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+Toolbar.displayName = 'Panel.Toolbar';
+
+//
+// Content
+//
+
+type ContentProps = SlottableProps<HTMLDivElement>;
+
+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>
+    );
+  },
+);
+
+Content.displayName = 'Panel.Content';
+
+//
+// Statusbar
+//
+
+type StatusbarProps = SlottableProps<HTMLDivElement>;
+
+const Statusbar = forwardRef<HTMLDivElement, StatusbarProps>(
+  ({ classNames, className, asChild, children, ...props }, forwardedRef) => {
+    const { tx } = useThemeContext();
+    const Comp = asChild ? Slot : Primitive.div;
+    return (
+      <Comp
+        ref={forwardedRef}
+        data-slot='statusbar'
+        {...props}
+        className={tx('panel.statusbar', {}, [className, classNames])}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+Statusbar.displayName = 'Panel.Statusbar';
+
+//
+// Panel
+//
+
+export const Panel = {
+  Root,
+  Toolbar,
+  Content,
+  Statusbar,
+};
+
+export type {
+  PanelRootProps,
+  ToolbarProps as PanelToolbarProps,
+  ContentProps as PanelContentProps,
+  StatusbarProps as PanelStatusbarProps,
+};

package/src/primitives/Panel/index.ts

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

package/src/primitives/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './Column';
+export * from './Flex';
+export * from './Grid';
+export * from './Panel';

package/src/testing/decorators/index.ts

@@ -3,5 +3,5 @@
 //
 
 export * from './withLayout';
-export * from './withSurfaceVariantsLayout';
+export * from './withLayoutVariants';
 export * from './withTheme';

package/src/testing/decorators/withLayout.tsx

@@ -3,52 +3,73 @@
 //
 
 import { type Decorator } from '@storybook/react';
-import React, { type FC, type PropsWithChildren } from 'react';
+import React, { type FC, type PropsWithChildren, memo } from 'react';
 
 import { type ClassNameValue, type ThemedClassName } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 
 export type ContainerProps = ThemedClassName<PropsWithChildren>;
 
-export type ContainerType = 'default' | 'column';
+export type ContainerType = 'default' | 'fullscreen' | 'centered' | 'column';
 
 export type WithLayoutProps =
   | FC<ContainerProps>
-  | { classNames?: ClassNameValue; container?: ContainerType; scroll?: boolean };
+  | {
+      classNames?: ClassNameValue;
+      layout?: ContainerType;
+      scroll?: boolean;
+    };
 
 /**
  * Adds layout container.
  */
 export const withLayout =
-  (props: WithLayoutProps): Decorator =>
+  (props: WithLayoutProps = {}): Decorator =>
   (Story) => {
+    // Prevent re-rendering of the story.
+    const MemoizedStory = memo(Story);
     if (typeof props === 'function') {
       const Container = props;
       return (
         <Container>
-          <Story />
+          <MemoizedStory />
+        </Container>
+      );
+    } else {
+      const { layout = 'default', classNames, scroll } = props;
+      const Container = layouts[layout] ?? layouts.fullscreen;
+      return (
+        <Container classNames={mx(classNames, scroll ? 'overflow-y-auto' : 'overflow-hidden')}>
+          <MemoizedStory />
         </Container>
       );
     }
-
-    const Container = layouts[(props as any).container as ContainerType] ?? layouts.default;
-    return (
-      <Container classNames={mx(props.classNames, props.scroll ? 'overflow-y-auto' : 'overflow-hidden')}>
-        <Story />
-      </Container>
-    );
   };
 
 const layouts: Record<ContainerType, FC<ContainerProps>> = {
-  default: ({ children, classNames }: ContainerProps) => (
-    <div role='none' className={mx(classNames)}>
+  default: ({ classNames, children }: ContainerProps) => (
+    <div role='none' className={mx('p-4', classNames)}>
       {children}
     </div>
   ),
 
-  column: ({ children, classNames }: ContainerProps) => (
-    <div role='none' className='fixed inset-0 flex justify-center overflow-hidden bg-deckSurface'>
-      <div role='none' className={mx('flex flex-col is-[40rem] bg-baseSurface', classNames)}>
+  fullscreen: ({ classNames, children }: ContainerProps) => (
+    <div role='none' className={mx('fixed inset-0 flex overflow-hidden bg-base-surface', classNames)}>
+      {children}
+    </div>
+  ),
+
+  centered: ({ classNames, children }: ContainerProps) => (
+    <div role='none' className={mx('fixed inset-0 grid overflow-hidden place-items-center bg-base-surface')}>
+      <div role='none' className={mx('flex flex-col w-[40rem] bg-group-surface', classNames)}>
+        {children}
+      </div>
+    </div>
+  ),
+
+  column: ({ classNames, children }: ContainerProps) => (
+    <div role='none' className='fixed inset-0 flex overflow-hidden justify-center bg-base-surface'>
+      <div role='none' className={mx('flex flex-col w-[40rem] bg-group-surface', classNames)}>
         {children}
       </div>
     </div>