@dxos/react-ui 0.8.4-main.d05673bc65 → 0.8.4-main.d9fc60f731

package/src/components/ErrorFallback/ErrorStack.tsx

@@ -9,11 +9,45 @@ import { mx } from '@dxos/ui-theme';
 
 type LocalFrame = { href: string; fileName: string };
 
+export type ParsedStackFrame = ReturnType<typeof ErrorStackParser.parse>[number];
+
+export type ErrorStackProps = {
+  /** 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 }: { error: Error }) => {
-  const frames = ErrorStackParser.parse(error);
+export const ErrorStack = ({ error, frames: framesProp }: ErrorStackProps) => {
+  const frames = framesProp ?? (error ? ErrorStackParser.parse(error) : []);
+  if (frames.length === 0) {
+    return null;
+  }
 
   return (
     <div className='font-mono text-sm'>
@@ -22,7 +56,7 @@ export const ErrorStack = ({ error }: { error: Error }) => {
         const local = frame.fileName
           ? parseLocalFrame(frame.fileName, frame.lineNumber, frame.columnNumber)
           : undefined;
-        const name = frame.functionName ?? '<anonymous>';
+        const functionName = frame.functionName ?? '<anonymous>';
         return (
           <div
             key={i}
@@ -41,14 +75,15 @@ export const ErrorStack = ({ error }: { error: Error }) => {
               />
               <div className='absolute top-1/2 -translate-y-1/2 left-1/2 right-0 h-px bg-neutral-500' />
             </div>
+
             {local ? (
               <a href={local.href} className='truncate self-center'>
-                {name}
+                {functionName}
               </a>
             ) : (
-              <span className='text-subdued truncate self-center'>{name}</span>
+              <span className='text-subdued truncate self-center'>{functionName}</span>
             )}
-            <span className='text-xs text-subdued truncate self-center'>{local?.fileName ?? ''}</span>
+            <span className='text-xs text-subdued truncate self-center truncate'>{local?.fileName ?? ''}</span>
             <span className='text-xs text-subdued text-right self-center'>
               {local ? `${frame.lineNumber}:${frame.columnNumber}` : ''}
             </span>
@@ -69,10 +104,15 @@ const parseLocalFrame = (fileUrl: string, line?: number, col?: number): LocalFra
     if (!pathname.startsWith('/@fs/')) {
       return undefined;
     }
-    const localPath = pathname.slice(4); // /@fs/Users/... → /Users/...
+
+    const FILE_PREFIX = '/@fs';
+    const localPath = pathname.slice(FILE_PREFIX.length); // /@fs/Users/... → /Users/...
+    const PKG_PREFIX = '/packages/';
+    const i = localPath.indexOf(PKG_PREFIX);
+    const path = i === -1 ? localPath : localPath.substring(i + PKG_PREFIX.length);
     return {
       href: `vscode://file/${localPath}:${line ?? 1}:${col ?? 1}`,
-      fileName: pathname.split('/').pop() ?? localPath,
+      fileName: path,
     };
   } catch {
     return undefined;

package/src/components/Focus/AUDIT.md

@@ -0,0 +1,43 @@
+# Focus
+
+## Problem
+
+Grid cells use `overflow-hidden` which clips outward CSS `ring` (box-shadow) and `outline` styles.
+Using `border` for focus indicators creates doubled lines at grid cell boundaries.
+Inset `box-shadow` alone is obscured by child elements with backgrounds (e.g., toolbar headers).
+
+## Solution
+
+Uses a `::after` pseudo-element overlay with `ring-inset` to paint the focus ring above all child content.
+The pseudo-element is absolutely positioned, `pointer-events-none`, and inherits `border-radius`.
+
+- **Default**: ring is transparent (invisible until focused).
+- **`border` prop**: shows a CSS `border-separator` when unfocused (e.g., for grid cell edges).
+- **Focus/active/error states**: ring color changes to the appropriate indicator color.
+
+Both `Focus.Group` and `Focus.Item` support the `border` prop.
+
+## Why `::after` overlay
+
+| Approach                 | Clipped? | Obscured by children? | Notes                                                                 |
+| ------------------------ | -------- | --------------------- | --------------------------------------------------------------------- |
+| `ring` (outward)         | Yes      | N/A                   | Extends outside bounds, clipped by parent `overflow-hidden`.          |
+| `ring-inset`             | No       | Yes                   | Inset box-shadow is part of background layer; children paint over it. |
+| `::after` + `ring-inset` | No       | No                    | Pseudo-element paints above children. Requires `position: relative`.  |
+
+## Relationship to `dx-focus-ring-inset-over-all`
+
+The CSS class `dx-focus-ring-inset-over-all` (in `focus-ring.css`) uses the same `::after` technique
+but only reacts to `:focus-visible`. `Focus.Group/Item` additionally support programmatic states
+via `data-focus-state` (`active`, `error`).
+
+## Clean-up
+
+- [ ] Unify: extend `dx-focus-ring-inset-over-all` to support `data-focus-state` attributes,
+      then have `Focus.Group/Item` use the CSS class instead of inline Tailwind utilities.
+      Consumers: Plank, StackItem, Tabs, AttentionProvider, main sidebar.
+
+## Audit
+
+- [ ] Create a list of all container components (outside of `react-ui`) that directly use `overflow-hidden`;
+      Consider containers to be components that have `children` and expand (e.g., `grid`, `grow`, `h-full`, `w-full`).

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

@@ -0,0 +1,230 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { type PropsWithChildren, useState } from 'react';
+
+import { mx } from '@dxos/ui-theme';
+
+import { withLayout, withTheme } from '../../testing';
+import { type ThemedClassName } from '../../util';
+import { Focus } from './Focus';
+
+type Item = { id: string; label: string };
+
+const ITEMS: Item[] = [
+  { id: '1', label: 'Item 1' },
+  { id: '2', label: 'Item 2' },
+  { id: '3', label: 'Item 3' },
+  { id: '4', label: 'Item 4' },
+  { id: '5', label: 'Item 5' },
+];
+
+const itemClassName = 'flex items-center gap-3 px-3 py-2 aria-current:bg-neutral-75 dark:aria-current:bg-neutral-800';
+
+const Container = ({ classNames, children }: ThemedClassName<PropsWithChildren>) => {
+  return (
+    <div className='dx-container grid grid-cols-[1fr_2fr_1fr]'>
+      <div className='border-e border-separator' />
+      <div className='dx-expander grid grid-rows-[1fr_2fr_1fr]'>
+        <div className='border-b border-separator' />
+        <div className={mx('h-full flex flex-col gap-2', classNames)}>{children}</div>
+        <div className='border-t border-separator' />
+      </div>
+      <div className='border-s border-separator' />
+    </div>
+  );
+};
+
+const Text = ({ children }: PropsWithChildren) => {
+  return <p className='p-1 text-sm text-subdued'>{children}</p>;
+};
+
+//
+// Default (vertical list)
+//
+
+const DefaultStory = () => {
+  const [current, setCurrent] = useState<string | undefined>('1');
+
+  return (
+    <Container>
+      <Text>Tab into the group, then use arrow keys to navigate. Press Enter to select.</Text>
+      <Focus.Group classNames='h-full'>
+        {ITEMS.map((item) => (
+          <Focus.Item
+            key={item.id}
+            current={current === item.id}
+            onCurrentChange={() => setCurrent(item.id)}
+            className={itemClassName}
+          >
+            <span className='size-2 bg-primary-500 opacity-0 aria-[current]:opacity-100' />
+            <span>{item.label}</span>
+          </Focus.Item>
+        ))}
+      </Focus.Group>
+      <Text>Selected: {current ?? 'none'}</Text>
+    </Container>
+  );
+};
+
+//
+// Horizontal group
+//
+
+const HorizontalStory = () => {
+  const [current, setCurrent] = useState<string | undefined>();
+
+  return (
+    <Container>
+      <Text>Horizontal arrow-key navigation between cards.</Text>
+      <Focus.Group classNames='h-full flex flex-row gap-2 items-center justify-center' orientation='horizontal'>
+        {ITEMS.map((item) => (
+          <Focus.Item
+            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'
+          >
+            <span className='text-xs mt-1'>{item.label}</span>
+          </Focus.Item>
+        ))}
+      </Focus.Group>
+      <Text>Selected: {current ?? 'none'}</Text>
+    </Container>
+  );
+};
+
+//
+// Grid (demonstrates border prop and overflow-hidden clipping)
+//
+
+const GridCell = ({ border, items }: { border?: boolean; items: Item[] }) => {
+  const [current, setCurrent] = useState<string | undefined>();
+  return (
+    <div className='overflow-hidden bg-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}
+          >
+            <span>{item.label}</span>
+          </Focus.Item>
+        ))}
+      </Focus.Group>
+    </div>
+  );
+};
+
+const GridStory = () => {
+  return (
+    <div className='p-8 space-y-8'>
+      <Text>Tab between groups to compare. Each cell has overflow-hidden.</Text>
+
+      {/* Default vs border. */}
+      <div className='grid grid-cols-2 gap-4'>
+        <div className='space-y-2'>
+          <p className='text-xs font-mono text-subdued'>Default (invisible until focused)</p>
+          <div className='h-48'>
+            <GridCell items={ITEMS} />
+          </div>
+        </div>
+        <div className='space-y-2'>
+          <p className='text-xs font-mono text-subdued'>border (always visible)</p>
+          <div className='h-48'>
+            <GridCell border items={ITEMS} />
+          </div>
+        </div>
+      </div>
+
+      {/* Tight grid — border. */}
+      <p className='text-xs font-mono text-subdued'>Tight grid — border</p>
+      <div className='grid grid-cols-3'>
+        {[0, 1, 2].map((col) => (
+          <div key={col} className='overflow-hidden'>
+            <GridCell border items={ITEMS.slice(0, 3)} />
+          </div>
+        ))}
+      </div>
+
+      {/* Tight grid — default. */}
+      <p className='text-xs font-mono text-subdued'>Tight grid — default</p>
+      <div className='grid grid-cols-3'>
+        {[0, 1, 2].map((col) => (
+          <div key={col} className='overflow-hidden'>
+            <GridCell items={ITEMS.slice(0, 3)} />
+          </div>
+        ))}
+      </div>
+
+      {/* Item-level border. */}
+      <p className='text-xs font-mono text-subdued'>Item-level border</p>
+      <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}>
+              <span>{item.label}</span>
+            </Focus.Item>
+          ))}
+        </Focus.Group>
+      </div>
+
+      {/* Error state. */}
+      <p className='text-xs font-mono text-subdued'>Error state</p>
+      <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}>
+              <span>{item.label}</span>
+            </Focus.Item>
+          ))}
+        </Focus.Group>
+      </div>
+    </div>
+  );
+};
+
+//
+// asChild (slot) usage
+//
+
+const AsChildStory = () => {
+  const [current, setCurrent] = useState<string | undefined>();
+
+  return (
+    <Container>
+      <Text>Focus.Item rendered as a custom element via asChild.</Text>
+      <Focus.Group classNames='h-full'>
+        {ITEMS.slice(0, 3).map((item) => (
+          <Focus.Item key={item.id} asChild current={current === item.id} onCurrentChange={() => setCurrent(item.id)}>
+            <button className='flex w-full items-center gap-3 px-3 py-2 text-left hover:bg-neutral-75 dark:hover:bg-neutral-800 aria-current:bg-primary-50 dark:aria-current:bg-primary-900/20 aria-current:text-primary-600'>
+              <span>{item.label}</span>
+            </button>
+          </Focus.Item>
+        ))}
+      </Focus.Group>
+    </Container>
+  );
+};
+
+//
+// Meta
+//
+
+const meta: Meta = {
+  title: 'ui/react-ui-core/components/Focus',
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { render: DefaultStory };
+export const Horizontal: Story = { render: HorizontalStory };
+export const Grid: Story = { render: GridStory };
+export const AsChild: Story = { render: AsChildStory };

package/src/components/Focus/Focus.theme.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { mx } from '@dxos/ui-theme';
+import { type ComponentFunction, type Theme } from '@dxos/ui-types';
+
+export type FocusStyleProps = {
+  border?: boolean;
+};
+
+/**
+ * Focus ring styles shared by Focus.Group and Focus.Item.
+ * Uses a `::after` pseudo-element overlay so the ring paints above child content
+ * (inset box-shadow alone is obscured by children with backgrounds).
+ * The pseudo-element is `pointer-events-none` and absolutely positioned over the element.
+ * When `border` is true, a subdued CSS border is always visible (e.g., for grid cell edges).
+ */
+const ring: ComponentFunction<FocusStyleProps> = ({ border }, ...etc) =>
+  mx(
+    'dx-ring-pseudo outline-hidden',
+    'focus:after:ring-focus-ring-subtle',
+    'data-[focus-state=active]:after:ring-focus-ring-subtle',
+    'data-[focus-state=error]:after:ring-rose-500',
+    border && 'border border-separator',
+    ...etc,
+  );
+
+export const focusTheme: Theme<FocusStyleProps> = {
+  group: ring,
+  item: ring,
+};

package/src/components/Focus/Focus.tsx

@@ -0,0 +1,201 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import {
+  useArrowNavigationGroup,
+  useFocusableGroup,
+  useMergedTabsterAttributes_unstable,
+} from '@fluentui/react-tabster';
+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 { 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);
+
+//
+// Group
+//
+
+type GroupProps = {
+  orientation?: Axis;
+  /** Show a subdued ring when unfocused (e.g., as a cell border). */
+  border?: boolean;
+  onKeyDown?: (event: KeyboardEvent<HTMLDivElement>) => void;
+};
+
+/**
+ * Provides arrow-key navigation across focusable children via tabster.
+ * Does not manage `aria-current` — use `Focus.Item` on each child for that.
+ */
+// TODO(wittjosiah): Consider how this could integrate with with react-ui-attention.
+//   Perhaps react-ui-attention comes under the mosaic umbrella as it supports selection?
+const Group = slottable<HTMLDivElement, GroupProps>(
+  ({ children, asChild, orientation = 'vertical', border = false, ...props }, forwardedRef) => {
+    const Comp = asChild ? Slot : Primitive.div;
+    const { tx } = useThemeContext();
+    const rootRef = useRef<HTMLDivElement>(null);
+    const focusableGroupAttrs = useFocusableGroup({ tabBehavior: 'limited-trap-focus' });
+    const arrowNavigationAttrs = useArrowNavigationGroup({ axis: orientation, memorizeCurrent: true });
+    const tabsterAttrs = useMergedTabsterAttributes_unstable(focusableGroupAttrs, arrowNavigationAttrs);
+    const [state, setState] = useState<FocusState | undefined>();
+    const [groupHasFocus, setGroupHasFocus] = useState(false);
+
+    const handleFocusIn = useCallback(() => setGroupHasFocus(true), []);
+    const handleFocusOut = useCallback((event: FocusEvent<HTMLDivElement>) => {
+      const related = event.relatedTarget as HTMLElement | null;
+      if (!related || !rootRef.current?.contains(related)) {
+        setGroupHasFocus(false);
+      }
+    }, []);
+
+    const { className, ...rest } = composableProps(props);
+    return (
+      <FocusContext.Provider value={{ setFocus: setState, groupHasFocus }}>
+        <Comp
+          {...rest}
+          tabIndex={0}
+          className={tx('focus.group', { border }, className)}
+          {...tabsterAttrs}
+          {...(state && {
+            [`data-${FOCUS_STATE_ATTR}`]: state,
+          })}
+          onBlur={handleFocusOut}
+          onFocus={handleFocusIn}
+          ref={useComposedRefs<HTMLDivElement>(rootRef, forwardedRef)}
+        >
+          {children}
+        </Comp>
+      </FocusContext.Provider>
+    );
+  },
+);
+
+//
+// Item
+//
+
+type ItemProps = {
+  current?: boolean;
+  /** Show a subdued ring when unfocused (e.g., as a cell border). */
+  border?: boolean;
+  onCurrentChange?: () => void;
+};
+
+/**
+ * Focusable item within a `Focus.Group`.
+ * Uses `useFocusableGroup` so the parent Group's arrow navigation treats this as a single unit
+ * (internal buttons are not arrow-navigation targets; Enter/Escape to go in/out).
+ * Supports controlled (`current` prop) and uncontrolled (focus-driven) `aria-current`.
+ */
+const Item = slottable<HTMLDivElement, ItemProps>(
+  (
+    { children, asChild, current, border = false, onCurrentChange, onClick, onFocus, onBlur, ...props },
+    forwardedRef,
+  ) => {
+    const Comp = asChild ? Slot : Primitive.div;
+    const { tx } = useThemeContext();
+    // Tell tabster's groupper to ignore Enter so it doesn't move focus into the group.
+    const focusableGroupAttrs = useFocusableGroup({ ignoreDefaultKeydown: { Enter: true } });
+    const [focused, setFocused] = useState(false);
+
+    const handleClick = useCallback(
+      (event: MouseEvent<HTMLDivElement>) => {
+        onCurrentChange?.();
+        onClick?.(event);
+      },
+      [onCurrentChange, onClick],
+    );
+
+    const handleKeyDown = useCallback(
+      (event: KeyboardEvent<HTMLDivElement>) => {
+        if (event.key === 'Enter') {
+          onCurrentChange?.();
+        }
+      },
+      [onCurrentChange],
+    );
+
+    const handleFocus = useCallback(
+      (event: FocusEvent<HTMLDivElement>) => {
+        setFocused(true);
+        onFocus?.(event);
+      },
+      [onFocus],
+    );
+
+    const handleBlur = useCallback(
+      (event: FocusEvent<HTMLDivElement>) => {
+        setFocused(false);
+        onBlur?.(event);
+      },
+      [onBlur],
+    );
+
+    // Controlled `current` prop takes precedence (e.g., virtualized items that scroll back into view).
+    // Otherwise fall back to DOM focus state.
+    const isCurrent = current ?? focused;
+
+    const { className, ...rest } = composableProps(props);
+    return (
+      <Comp
+        {...rest}
+        tabIndex={0}
+        className={tx('focus.item', { border }, className)}
+        {...focusableGroupAttrs}
+        aria-current={isCurrent || undefined}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        ref={forwardedRef}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+//
+// Focus
+//
+
+export const Focus = {
+  Group,
+  Item,
+};
+
+export type { GroupProps as FocusGroupProps, ItemProps as FocusItemProps };
+
+export { useFocus };

package/src/components/Focus/index.ts

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

package/src/components/Icon/Icon.stories.tsx

@@ -6,10 +6,9 @@ import { IconBase, type IconProps, type IconWeight } from '@phosphor-icons/react
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { type FC, type ReactElement, type SVGProps, forwardRef } from 'react';
 
-import { getSize, mx } from '@dxos/ui-theme';
+import { getSize, iconSize, mx } from '@dxos/ui-theme';
 
 import { withTheme } from '../../testing';
-
 import { Icon } from './Icon';
 
 /**
@@ -50,29 +49,60 @@ const createIcon = ({
   return CustomIcon;
 };
 
-const DefaultStory = ({ CustomIcon }: { CustomIcon: FC<IconProps> }) => {
-  return (
-    <div className='grid grid-cols-2 gap-8'>
-      <CustomIcon weight={'regular'} className={mx(getSize(16))} />
-      <Icon icon='ph--github-logo--regular' classNames={mx(getSize(16))} />
-    </div>
-  );
-};
-
 const meta = {
   title: 'ui/react-ui-core/components/Icon',
-  render: DefaultStory,
+  component: Icon,
   decorators: [withTheme()],
   parameters: {
     layout: 'centered',
   },
-} satisfies Meta<typeof DefaultStory>;
+} satisfies Meta<typeof Icon>;
 
 export default meta;
 
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
+  args: {
+    icon: 'ph--github-logo--regular',
+  },
+};
+
+export const Static: Story = {
+  args: {
+    icon: 'ph--github-logo--regular',
+    classNames: getSize(8),
+  },
+};
+
+export const Dynamic: Story = {
+  args: {
+    icon: 'ph--github-logo--regular',
+  },
+  render: (args) => {
+    return (
+      <div className='flex gap-4'>
+        <Icon {...args} />
+        <div className='flex gap-4' style={iconSize(8)}>
+          <Icon {...args} />
+          <div className='flex gap-4' style={iconSize(null)}>
+            <Icon {...args} />
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Custom = {
+  render: ({ CustomIcon }: { CustomIcon: FC<IconProps> }) => {
+    return (
+      <div className='grid grid-cols-2 gap-8'>
+        <CustomIcon weight={'regular'} className={mx(getSize(16))} />
+        <Icon icon='ph--github-logo--regular' classNames={mx(getSize(16))} />
+      </div>
+    );
+  },
   args: {
     CustomIcon: createIcon({
       name: 'GithubLogo',