@dxos/react-ui 0.10.0 → 0.11.0

package/src/components/Column/Column.tsx

@@ -10,6 +10,7 @@ import { type SlottableProps } from '@dxos/ui-types';
 
 import { useThemeContext } from '../../hooks';
 import { composableProps, slottable } from '../../util';
+import { ColumnContext } from './ColumnContext';
 
 //
 // Root
@@ -25,7 +26,7 @@ const gutterSizes: Record<GutterSize, string> = {
   lg: 'var(--dx-gutter-lg)',
 };
 
-type ColumnRootProps = { gutter?: GutterSize };
+type ColumnRootProps = { gutter?: GutterSize; subgrid?: boolean };
 
 /**
  * Creates a 3-column CSS grid with left/right gutter columns and a center content column.
@@ -34,37 +35,45 @@ type ColumnRootProps = { gutter?: GutterSize };
  * `--dx-col` defaults to `2 / span 1` (center column),
  * enabling `withColumn` utilities to cascade the correct grid placement to slotted children.
  *
+ * With `subgrid`, the root adopts the parent grid's tracks instead of defining its own — it spans
+ * all parent columns (`grid-column: 1 / -1`) and its column template becomes `subgrid`, so a Column
+ * (or Card) nested inside another 3-track grid aligns its gutters/center to the outer columns. The
+ * parent must expose (at least) three tracks; `--dx-col`/gutter placement still targets track 2/1/3.
+ *
  * 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.
+ * Use the `withColumn.center()` helper to apply placement on slotted elements.
  */
 const ColumnRoot = slottable<HTMLDivElement, ColumnRootProps>(
-  ({ children, asChild, role, gutter = 'lg', ...props }, forwardedRef) => {
+  ({ children, asChild, role, gutter = 'lg', subgrid, ...props }, forwardedRef) => {
     const { className, ...rest } = composableProps(props);
     const Comp = asChild ? Slot : Primitive.div;
     const { tx } = useThemeContext();
     const gutterSize = gutterSizes[gutter];
+    // The provider wraps `Comp` rather than the children: under `asChild`, `Comp` is a Slot that
+    // merges its props into its single child, and a Provider in that position would swallow them.
     return (
-      <Comp
-        {...rest}
-        role={role ?? 'none'}
-        style={
-          {
-            ...rest.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>
+      <ColumnContext.Provider value={true}>
+        <Comp
+          {...rest}
+          role={role ?? 'none'}
+          style={
+            {
+              ...rest.style,
+              '--gutter': gutterSize,
+              '--dx-col': '2 / span 1',
+              'gridTemplateColumns': subgrid ? 'subgrid' : [gutterSize, 'minmax(0,1fr)', gutterSize].join(' '),
+              ...(subgrid && { gridColumn: '1 / -1' }),
+            } as CSSProperties
+          }
+          className={tx('column.root', { gutter }, className)}
+          ref={forwardedRef}
+        >
+          {children}
+        </Comp>
+      </ColumnContext.Provider>
     );
   },
 );
@@ -97,32 +106,6 @@ const ColumnRow = slottable<HTMLDivElement, ColumnRowProps>(({ children, asChild
 
 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
 //
@@ -160,8 +143,9 @@ type ColumnBlockProps = SlottableProps<{ end?: boolean; compact?: boolean; squar
 /**
  * A gutter slot inside a Column.Row. Sized to `--dx-rail-item` and centers its child so a passive
  * `<Icon>` and an interactive `IconButton` align to the pixel. `end` opts into the trailing gutter
- * (column 3); default is the leading gutter (column 1). Placement is via `data-slot`, so it is
- * robust to conditional rendering and source order.
+ * (column 3); default is the leading gutter (column 1). Placement is class-based (`col-start-*`
+ * plus the `dx-gutter` marker — see `Column.theme.ts`), so it is robust to conditional rendering
+ * and source order.
  */
 const ColumnBlock = slottable<HTMLDivElement, ColumnBlockProps>(
   ({ children, asChild, end, compact, square, ...props }, forwardedRef) => {
@@ -169,12 +153,7 @@ const ColumnBlock = slottable<HTMLDivElement, ColumnBlockProps>(
     const { className, ...rest } = composableProps(props);
     const Comp = asChild ? Slot : Primitive.div;
     return (
-      <Comp
-        {...rest}
-        data-slot={end ? 'end' : 'start'}
-        className={tx('column.block', { end, compact, square }, className)}
-        ref={forwardedRef}
-      >
+      <Comp {...rest} className={tx('column.block', { end, compact, square }, className)} ref={forwardedRef}>
         {children}
       </Comp>
     );
@@ -191,8 +170,7 @@ export const Column = {
   Root: ColumnRoot,
   Row: ColumnRow,
   Block: ColumnBlock,
-  Bleed: ColumnBleed,
   Center: ColumnCenter,
 };
 
-export type { ColumnBleedProps, ColumnBlockProps, ColumnCenterProps, ColumnRootProps, ColumnRowProps };
+export type { ColumnBlockProps, ColumnCenterProps, ColumnRootProps, ColumnRowProps };

package/src/components/Column/ColumnContext.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext, useContext } from 'react';
+
+// Kept out of `Column.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so a context and its hook exported beside them force a full page reload on every edit.
+
+//
+// Context
+//
+
+export const ColumnContext = createContext(false);
+
+/**
+ * Whether the caller is already inside a `Column.Root`. A component that would otherwise establish
+ * its own gutter grid (a form viewport, say) should use this to place itself in the host's content
+ * track instead — nesting a second grid is what makes a form's fields inset differently from the
+ * card title above them.
+ */
+export const useInColumn = () => useContext(ColumnContext);

package/src/components/Column/index.ts

@@ -2,5 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+export { useInColumn } from './ColumnContext';
+
 export * from './Column';
 export * from './withColumn';

package/src/components/Column/withColumn.ts

@@ -12,16 +12,53 @@
  * - ScrollArea.Viewport resets `--dx-col: auto` after consuming `--gutter`.
  * - Components apply `grid-column: var(--dx-col, auto)` to auto-center in Column
  *   or do nothing outside Column / inside ScrollArea.
+ *
+ * ## Which one to use
+ *
+ * Three placement mechanisms coexist because they solve different problems. An earlier plan was to
+ * collapse them onto `--dx-col` alone; that was tried and abandoned — the other two are each the
+ * only way to express their case (see AUDIT.md §3).
+ *
+ * | Mechanism         | Places                        | Reach for it when                                  |
+ * | ----------------- | ----------------------------- | -------------------------------------------------- |
+ * | `center()`        | the element itself            | one element belongs in the content track            |
+ * | `placeContent()`  | the element's children        | a subgrid row mixes gutter slots with content       |
+ * | `propagate()`     | opens the tracks to children  | a child must reach the gutters                      |
+ *
+ * - **`center()`** is inheritance-based, so it survives a `display: contents` wrapper — the case
+ *   where a child selector or subgrid silently fails. Prefer it whenever it is sufficient.
+ * - **`placeContent()`** needs the element to already be a subgrid row (`col-span-3 grid
+ *   grid-cols-subgrid`). It reaches grandchildren too, so a wrapper element (a link, a button)
+ *   doesn't strand its content in column 1.
+ * - **`propagate()`** is the only one that lets a *descendant* address the gutters: it spans the
+ *   element across all tracks and re-exposes them via subgrid, with `.dx-container` exempted so a
+ *   ScrollArea can span full width and keep its scrollbar in the gutter. `Dialog.Body` depends on
+ *   this — replacing it with `center()` confines the body's ScrollArea to the content track and
+ *   pulls the scrollbar 32px inboard.
  */
 export const withColumn = {
-  /** Centers element in the Column grid via --dx-col. No-op outside Column or inside ScrollArea. */
+  /**
+   * Centers element in the Column grid via --dx-col. No-op outside Column or inside ScrollArea.
+   */
   center: () => '[grid-column:var(--dx-col,auto)]',
 
-  /** Propagates the Column grid to children via subgrid. No-op outside Column.
-   *  Direct children default to center column unless they are a dx-container (ScrollArea). */
+  /**
+   * Places a subgrid row's content children in the center track, leaving `.dx-gutter` slots to
+   * their own explicit `col-start`. Covers grandchildren too, so a wrapper element (a link, a
+   * button) doesn't strand its content in column 1 — and excludes gutters at that depth as well,
+   * since a `display: contents` wrapper promotes its children into this grid.
+   */
+  placeContent: () => '[&>*:not(.dx-gutter)]:col-start-2 [&>*:not(.dx-gutter)>*:not(.dx-gutter)]:col-start-2',
+
+  /**
+   * Propagates the Column grid to children via subgrid. No-op outside Column.
+   * Direct children default to center column unless they are a dx-container (ScrollArea).
+   */
   propagate: () =>
     '[.dx-column-root_&]:col-span-full [.dx-column-root_&]:grid [.dx-column-root_&]:grid-cols-subgrid [.dx-column-root_&]:[&>*:not(.dx-container)]:[grid-column:var(--dx-col,auto)]',
 
-  /** Resets --dx-col after consuming --gutter. Applied by ScrollArea.Viewport. */
+  /**
+   * Resets --dx-col after consuming --gutter. Applied by ScrollArea.Viewport.
+   */
   consumed: () => '[--dx-col:auto]',
 };

package/src/components/DatePicker/DatePicker.theme.ts

@@ -12,13 +12,13 @@ export type DatePickerStyleProps = Partial<{
 const trigger: ComponentFunction<DatePickerStyleProps> = ({ hasValue }, ...etc) =>
   mx(
     'inline-flex w-fit items-center gap-2 px-2 rounded-sm border border-separator',
-    'bg-input-surface text-base-fg',
+    'dx-input-surface text-base-fg',
     'hover:bg-hover-surface focus-visible:outline-2 focus-visible:outline-primary-500',
     !hasValue && 'text-description',
     ...etc,
   );
 
-const content: ComponentFunction<DatePickerStyleProps> = (_p, ...etc) => mx('flex flex-col gap-2 p-2', ...etc);
+const content: ComponentFunction<DatePickerStyleProps> = (_p, ...etc) => mx('flex flex-col gap-2', ...etc);
 
 const timeField: ComponentFunction<DatePickerStyleProps> = (_p, ...etc) =>
   mx(

package/src/components/DatePicker/DatePicker.tsx

@@ -2,7 +2,6 @@
 // Copyright 2026 DXOS.org
 //
 
-import { createContext } from '@radix-ui/react-context';
 import { format as formatDate } from 'date-fns';
 import React, {
   type ComponentPropsWithoutRef,
@@ -20,6 +19,7 @@ import { type ThemedClassName } from '../../util';
 import { Calendar, type DateRange } from '../Calendar';
 import { Icon } from '../Icon';
 import { Popover } from '../Popover';
+import { DatePickerProvider, useDatePickerContext } from './DatePickerContext';
 
 //
 // Public API.
@@ -37,17 +37,6 @@ type ValueByMode = {
   range: DateRange | undefined;
 };
 
-type DatePickerContextValue = {
-  mode: DatePickerMode;
-  value: ValueByMode[DatePickerMode];
-  setValue: (next: ValueByMode[DatePickerMode]) => void;
-  withTime: boolean;
-  open: boolean;
-  onOpenChange: (open: boolean) => void;
-};
-
-const [DatePickerProvider, useDatePickerContext] = createContext<DatePickerContextValue>('DatePicker');
-
 //
 // Root.
 //
@@ -274,6 +263,4 @@ export const DatePicker = {
   Calendar: DatePickerCalendar,
 };
 
-export { useDatePickerContext };
-
 export type { ValueByMode };

package/src/components/DatePicker/DatePickerContext.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+
+import { type DatePickerMode, type ValueByMode } from './DatePicker';
+
+// Kept out of `DatePicker.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so a context and its hook exported beside them force a full page reload on every edit.
+
+export type DatePickerContextValue = {
+  mode: DatePickerMode;
+  value: ValueByMode[DatePickerMode];
+  setValue: (next: ValueByMode[DatePickerMode]) => void;
+  withTime: boolean;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+};
+
+export const [DatePickerProvider, useDatePickerContext] = createContext<DatePickerContextValue>('DatePicker');

package/src/components/DatePicker/index.ts

@@ -2,4 +2,6 @@
 // Copyright 2026 DXOS.org
 //
 
+export { useDatePickerContext } from './DatePickerContext';
+
 export * from './DatePicker';

package/src/components/ErrorFallback/ErrorStack.tsx

@@ -7,50 +7,30 @@ import React from 'react';
 
 import { mx } from '@dxos/ui-theme';
 
-type LocalFrame = { href: string; fileName: string };
+import { ThemedClassName } from '../../util';
+import { type ParsedStackFrame } from './parse-stack';
 
-export type ParsedStackFrame = ReturnType<typeof ErrorStackParser.parse>[number];
+/** A stack frame resolved to a local (workspace) source location. */
+type LocalFrame = { href: string; fileName: string };
 
-export type ErrorStackProps = {
+export type ErrorStackProps = ThemedClassName<{
   /** When set, these frames are shown instead of parsing `error`. */
   frames?: ParsedStackFrame[];
   /** Used when `frames` is omitted. */
   error?: Error;
-};
-
-/**
- * Parses `captureOwnerStack()` output (React dev) into frames for {@link ErrorStack}.
- * Prefixes a synthetic Error line when needed so `error-stack-parser` can read V8-style stacks.
- */
-export const parseCaptureOwnerStack = (stack: string | null): ParsedStackFrame[] | null => {
-  if (stack == null || stack.length === 0) {
-    return null;
-  }
-  const err = new Error();
-  err.stack = stack;
-  try {
-    return ErrorStackParser.parse(err);
-  } catch {
-    err.stack = `Error\n${stack}`;
-    try {
-      return ErrorStackParser.parse(err);
-    } catch {
-      return null;
-    }
-  }
-};
+}>;
 
 /**
  * Renders a parsed error stack trace with tree connector symbols and clickable vscode:// links for local frames.
  */
-export const ErrorStack = ({ error, frames: framesProp }: ErrorStackProps) => {
+export const ErrorStack = ({ classNames, error, frames: framesProp }: ErrorStackProps) => {
   const frames = framesProp ?? (error ? ErrorStackParser.parse(error) : []);
   if (frames.length === 0) {
     return null;
   }
 
   return (
-    <div className='font-mono text-sm'>
+    <div className={mx('font-mono text-sm', classNames)}>
       {frames.map((frame, i) => {
         const isLast = i === frames.length - 1;
         const local = frame.fileName

package/src/components/ErrorFallback/index.ts

@@ -5,5 +5,6 @@
 export { ErrorBoundary, type ErrorBoundaryProps, type FallbackProps } from '@dxos/react-error-boundary';
 
 export * from './ErrorFallback';
+export { type ParsedStackFrame, parseCaptureOwnerStack } from './parse-stack';
 export * from './ErrorStack';
 export * from './ThrowError';

package/src/components/ErrorFallback/parse-stack.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import ErrorStackParser from 'error-stack-parser';
+
+// Kept out of `ErrorStack.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so a context and its hook exported beside them force a full page reload on every edit.
+
+export type ParsedStackFrame = ReturnType<typeof ErrorStackParser.parse>[number];
+
+/**
+ * Parses `captureOwnerStack()` output (React dev) into frames for {@link ErrorStack}.
+ * Prefixes a synthetic Error line when needed so `error-stack-parser` can read V8-style stacks.
+ */
+export const parseCaptureOwnerStack = (stack: string | null): ParsedStackFrame[] | null => {
+  if (stack == null || stack.length === 0) {
+    return null;
+  }
+
+  const err = new Error();
+  err.stack = stack;
+  try {
+    return ErrorStackParser.parse(err);
+  } catch {
+    err.stack = `Error\n${stack}`;
+    try {
+      return ErrorStackParser.parse(err);
+    } catch {
+      return null;
+    }
+  }
+};

package/src/components/Focus/Focus.stories.tsx

@@ -57,7 +57,7 @@ const DefaultStory = () => {
             key={item.id}
             current={current === item.id}
             onCurrentChange={() => setCurrent(item.id)}
-            className={itemClassName}
+            classNames={itemClassName}
           >
             <span className='size-2 bg-primary-500 opacity-0 aria-[current]:opacity-100' />
             <span>{item.label}</span>
@@ -85,7 +85,7 @@ const HorizontalStory = () => {
             key={item.id}
             current={current === item.id}
             onCurrentChange={() => setCurrent(item.id)}
-            className='flex flex-col items-center justify-center w-20 h-20 border border-separator aria-current:border-primary-500 aria-current:bg-primary-50 dark:aria-current:bg-primary-900/20 cursor-pointer'
+            classNames='flex flex-col items-center justify-center w-20 h-20 border border-separator aria-current:border-primary-500 aria-current:bg-primary-50 dark:aria-current:bg-primary-900/20 cursor-pointer'
           >
             <span className='text-xs mt-1'>{item.label}</span>
           </Focus.Item>
@@ -103,14 +103,14 @@ const HorizontalStory = () => {
 const GridCell = ({ border, items }: { border?: boolean; items: Item[] }) => {
   const [current, setCurrent] = useState<string | undefined>();
   return (
-    <div className='overflow-hidden bg-base-surface'>
+    <div className='overflow-hidden dx-base-surface'>
       <Focus.Group classNames='h-full' border={border}>
         {items.map((item) => (
           <Focus.Item
             key={item.id}
             current={current === item.id}
             onCurrentChange={() => setCurrent(item.id)}
-            className={itemClassName}
+            classNames={itemClassName}
           >
             <span>{item.label}</span>
           </Focus.Item>
@@ -166,7 +166,7 @@ const GridStory = () => {
       <div className='h-48 overflow-hidden'>
         <Focus.Group classNames='h-full'>
           {ITEMS.slice(0, 3).map((item) => (
-            <Focus.Item key={item.id} border className={itemClassName}>
+            <Focus.Item key={item.id} border classNames={itemClassName}>
               <span>{item.label}</span>
             </Focus.Item>
           ))}
@@ -178,7 +178,7 @@ const GridStory = () => {
       <div className='h-48 overflow-hidden'>
         <Focus.Group classNames='h-full' data-focus-state='error'>
           {ITEMS.slice(0, 3).map((item) => (
-            <Focus.Item key={item.id} className={itemClassName}>
+            <Focus.Item key={item.id} classNames={itemClassName}>
               <span>{item.label}</span>
             </Focus.Item>
           ))}

package/src/components/Focus/Focus.tsx

@@ -10,39 +10,13 @@ import {
 import { useComposedRefs } from '@radix-ui/react-compose-refs';
 import { Primitive } from '@radix-ui/react-primitive';
 import { Slot } from '@radix-ui/react-slot';
-import React, {
-  type FocusEvent,
-  type KeyboardEvent,
-  type MouseEvent,
-  createContext,
-  useCallback,
-  useContext,
-  useRef,
-  useState,
-} from 'react';
+import React, { type FocusEvent, type KeyboardEvent, type MouseEvent, useCallback, useRef, useState } from 'react';
 
 import { type Axis } from '@dxos/ui-types';
 
 import { useThemeContext } from '../../hooks';
 import { composableProps, slottable } from '../../util';
-
-//
-// Context
-//
-
-type FocusState = 'active' | 'error';
-
-const FOCUS_STATE_ATTR = 'focus-state';
-
-type ContextValue = {
-  setFocus?: (state: FocusState | undefined) => void;
-  /** True when any item within the group has DOM focus. */
-  groupHasFocus?: boolean;
-};
-
-const FocusContext = createContext<ContextValue>({});
-
-const useFocus = () => useContext(FocusContext);
+import { FOCUS_STATE_ATTR, FocusContext, type FocusState } from './FocusContext';
 
 //
 // Group
@@ -197,5 +171,3 @@ export const Focus = {
 };
 
 export type { GroupProps as FocusGroupProps, ItemProps as FocusItemProps };
-
-export { useFocus };

package/src/components/Focus/FocusContext.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createContext, useContext } from 'react';
+
+// Kept out of `Focus.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so a context and its hook exported beside them force a full page reload on every edit.
+
+export type FocusState = 'active' | 'error';
+
+export const FOCUS_STATE_ATTR = 'focus-state';
+
+export type ContextValue = {
+  setFocus?: (state: FocusState | undefined) => void;
+  /** True when any item within the group has DOM focus. */
+  groupHasFocus?: boolean;
+};
+
+export const FocusContext = createContext<ContextValue>({});
+
+export const useFocus = () => useContext(FocusContext);

package/src/components/Focus/index.ts

@@ -2,4 +2,6 @@
 // Copyright 2026 DXOS.org
 //
 
+export { useFocus } from './FocusContext';
+
 export * from './Focus';

package/src/components/Image/Image.tsx

@@ -82,7 +82,7 @@ export const Image = ({
       // `dx-ring-pseudo` `::after`) painted on ancestors — most visibly,
       // the focus ring on a Card containing a Card.Poster.
       className={mx(
-        `relative flex w-full justify-center overflow-hidden transition-all duration-700 isolate`,
+        `relative shrink-0 flex w-full justify-center overflow-hidden transition-all duration-700 isolate`,
         classNames,
       )}
       style={{