@dxos/react-ui-list 0.9.0 → 0.9.1-main.c7dcc2e112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-list",
-  "version": "0.9.0",
+  "version": "0.9.1-main.c7dcc2e112",
   "description": "A list component.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -26,6 +26,7 @@
   ],
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "1.7.7",
+    "@atlaskit/pragmatic-drag-and-drop-auto-scroll": "^2.1.2",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "1.1.0",
     "@effect-atom/atom-react": "^0.5.0",
     "@fluentui/react-tabster": "9.26.11",
@@ -33,33 +34,35 @@
     "@radix-ui/react-context": "1.1.1",
     "@radix-ui/react-slot": "1.1.2",
     "@radix-ui/react-use-controllable-state": "1.1.0",
-    "@dxos/debug": "0.9.0",
-    "@dxos/invariant": "0.9.0",
-    "@dxos/react-list": "0.9.0",
-    "@dxos/react-ui": "0.9.0",
-    "@dxos/ui-theme": "0.9.0",
-    "@dxos/log": "0.9.0",
-    "@dxos/react-ui-text-tooltip": "0.9.0",
-    "@dxos/echo": "0.9.0",
-    "@dxos/ui-types": "0.9.0",
-    "@dxos/util": "0.9.0"
+    "@dxos/debug": "0.9.1-main.c7dcc2e112",
+    "@dxos/echo": "0.9.1-main.c7dcc2e112",
+    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
+    "@dxos/react-list": "0.9.1-main.c7dcc2e112",
+    "@dxos/react-ui": "0.9.1-main.c7dcc2e112",
+    "@dxos/log": "0.9.1-main.c7dcc2e112",
+    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112",
+    "@dxos/ui-types": "0.9.1-main.c7dcc2e112",
+    "@dxos/util": "0.9.1-main.c7dcc2e112"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
     "@types/react": "~19.2.7",
     "@types/react-dom": "~19.2.3",
     "effect": "3.21.3",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
+    "resize-observer-polyfill": "^1.5.1",
     "vite": "^8.0.16",
-    "@dxos/storybook-utils": "0.9.0",
-    "@dxos/random": "0.9.0"
+    "@dxos/random": "0.9.1-main.c7dcc2e112",
+    "@dxos/storybook-utils": "0.9.1-main.c7dcc2e112"
   },
   "peerDependencies": {
     "effect": "3.21.3",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "@dxos/ui-theme": "0.9.0",
-    "@dxos/react-ui": "0.9.0"
+    "@dxos/react-ui": "0.9.1-main.c7dcc2e112",
+    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112"
   },
   "publishConfig": {
     "access": "public"

package/src/aspects/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './useListDisclosure';
+export * from './useListGrid';
+export * from './useListNavigation';
+export * from './useListSelection';
+export * from './useReorder';

package/src/aspects/useListDisclosure.test.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { act, renderHook } from '@testing-library/react';
+import { describe, test, vi } from 'vitest';
+
+import { useListDisclosure } from './useListDisclosure';
+
+describe('useListDisclosure', () => {
+  describe('single mode', () => {
+    test('expanding an item sets it as the value', ({ expect }) => {
+      const onValueChange = vi.fn();
+      const { result } = renderHook(() => useListDisclosure({ mode: 'single', onValueChange }));
+      expect(result.current.bind('a').expanded).toBe(false);
+      act(() => result.current.bind('a').toggle());
+      expect(onValueChange).toHaveBeenLastCalledWith('a');
+    });
+
+    test('expanding a second item collapses the first', ({ expect }) => {
+      const { result, rerender } = renderHook(({ value }) => useListDisclosure({ mode: 'single', value }), {
+        initialProps: { value: 'a' as string | undefined },
+      });
+      expect(result.current.bind('a').expanded).toBe(true);
+      expect(result.current.bind('b').expanded).toBe(false);
+      rerender({ value: 'b' });
+      expect(result.current.bind('a').expanded).toBe(false);
+      expect(result.current.bind('b').expanded).toBe(true);
+    });
+
+    test('toggling an expanded item collapses it to undefined', ({ expect }) => {
+      const onValueChange = vi.fn();
+      const { result } = renderHook(() => useListDisclosure({ mode: 'single', defaultValue: 'a', onValueChange }));
+      expect(result.current.bind('a').expanded).toBe(true);
+      act(() => result.current.bind('a').toggle());
+      expect(onValueChange).toHaveBeenLastCalledWith(undefined);
+    });
+  });
+
+  describe('multi mode', () => {
+    test('expanding multiple items keeps all open', ({ expect }) => {
+      const onValueChange = vi.fn();
+      const { result } = renderHook(() => useListDisclosure({ mode: 'multi', onValueChange }));
+      act(() => result.current.bind('a').toggle());
+      act(() => result.current.bind('b').toggle());
+      const lastCallSet = onValueChange.mock.lastCall?.[0] as Set<string>;
+      expect(lastCallSet.has('a')).toBe(true);
+      expect(lastCallSet.has('b')).toBe(true);
+    });
+
+    test('toggling a multi-expanded item removes it from the set', ({ expect }) => {
+      const onValueChange = vi.fn();
+      const { result } = renderHook(() =>
+        useListDisclosure({ mode: 'multi', defaultValue: new Set(['a', 'b']), onValueChange }),
+      );
+      act(() => result.current.bind('a').toggle());
+      const lastCallSet = onValueChange.mock.lastCall?.[0] as Set<string>;
+      expect(lastCallSet.has('a')).toBe(false);
+      expect(lastCallSet.has('b')).toBe(true);
+    });
+  });
+
+  test('emits a stable trigger/panel id pair per item', ({ expect }) => {
+    const { result } = renderHook(() => useListDisclosure({ mode: 'single' }));
+    const first = result.current.bind('x');
+    const second = result.current.bind('x');
+    expect(first.triggerId).toBe(second.triggerId);
+    expect(first.panelId).toBe(second.panelId);
+    expect(first.triggerProps['aria-controls']).toBe(first.panelId);
+    expect(first.panelProps['aria-labelledby']).toBe(first.triggerId);
+  });
+});

package/src/aspects/useListDisclosure.ts

@@ -0,0 +1,160 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type MouseEvent, useCallback, useEffect, useId, useRef, useState } from 'react';
+
+export type ListDisclosureMode = 'single' | 'multi';
+
+type SingleValue = string | undefined;
+type MultiValue = ReadonlySet<string>;
+
+type ValueFor<M extends ListDisclosureMode> = M extends 'single' ? SingleValue : MultiValue;
+
+export type UseListDisclosureOptions<M extends ListDisclosureMode = ListDisclosureMode> = {
+  mode: M;
+  /** Controlled value: a single id (single mode) or a set of ids (multi mode). */
+  value?: ValueFor<M>;
+  defaultValue?: ValueFor<M>;
+  /** Called whenever the disclosure value changes. */
+  onValueChange?: (next: ValueFor<M>) => void;
+};
+
+export type DisclosureItemBinding = {
+  expanded: boolean;
+  toggle: () => void;
+  /** Stable id on the disclosure trigger; the controlled panel references it via aria-labelledby. */
+  triggerId: string;
+  /** Stable id on the controlled panel; the trigger references it via aria-controls. */
+  panelId: string;
+  /** Spread onto the trigger element (button, title row, …). */
+  triggerProps: {
+    id: string;
+    'aria-expanded': boolean;
+    'aria-controls': string;
+    onClick: (event: MouseEvent) => void;
+  };
+  /** Spread onto the disclosed panel; carries role=region for SR navigation. */
+  panelProps: {
+    id: string;
+    role: 'region';
+    'aria-labelledby': string;
+  };
+};
+
+export type UseListDisclosureReturn = {
+  /** Return the disclosure binding for a single item by id. */
+  bind: (id: string) => DisclosureItemBinding;
+};
+
+const isMulti = (value: SingleValue | MultiValue): value is MultiValue => value instanceof Set;
+
+/**
+ * Disclosure (open/close) aspect for list items. Owns single- or multi-expand state and
+ * generates the trigger/panel ids needed for `aria-controls` / `aria-labelledby`. Pairs
+ * with `useListGrid`'s expand-caret slot.
+ *
+ * `single` mode tracks one expanded id; expanding another collapses the previous (matches
+ * the existing `OrderedList` behaviour).
+ *
+ * `multi` mode tracks a `Set<string>` of expanded ids; intended for `Tree` and other
+ * multi-branch disclosure surfaces.
+ *
+ * Controlled-ness keys on `onValueChange` rather than on the value's presence so that
+ * `undefined` (single mode) and the empty set (multi mode) remain valid "nothing expanded"
+ * values. Radix's `useControllableState` (1.1.0) flips to uncontrolled when a controlled
+ * value clears to `undefined`, then re-reads the stale internal state and fails to collapse —
+ * a hand-rolled controller is the only correct option here.
+ */
+export const useListDisclosure: {
+  <M extends ListDisclosureMode>(opts: UseListDisclosureOptions<M>): UseListDisclosureReturn;
+} = (opts) => {
+  const { mode, value, defaultValue, onValueChange } = opts;
+  const idPrefix = useId();
+
+  // Latches whenever the consumer passes the `value` prop key, regardless of whether the
+  // current value is `undefined`. A controlled single-expand parent (`expandedId: string | undefined`)
+  // must be able to clear to undefined without the row falling back to stale internal state —
+  // detecting controlled-ness by `value !== undefined` would misclassify "controlled and currently
+  // empty" as uncontrolled.
+  const wasControlledRef = useRef(Object.prototype.hasOwnProperty.call(opts, 'value'));
+  if (Object.prototype.hasOwnProperty.call(opts, 'value')) {
+    wasControlledRef.current = true;
+  }
+  const isControlled = wasControlledRef.current;
+
+  const [internalValue, setInternalValue] = useState<SingleValue | MultiValue>(() => defaultValue);
+
+  // Mirror the controlled prop into internal state so going uncontrolled in a later render
+  // doesn't surface a stale internal value (and so consumers can read `internalValue`
+  // uniformly regardless of mode).
+  useEffect(() => {
+    if (isControlled) {
+      setInternalValue(value);
+    }
+  }, [isControlled, value]);
+
+  const resolvedValue = isControlled ? value : internalValue;
+
+  const isExpanded = useCallback(
+    (id: string) => {
+      if (mode === 'multi') {
+        return isMulti(resolvedValue) && resolvedValue.has(id);
+      }
+      return resolvedValue === id;
+    },
+    [mode, resolvedValue],
+  );
+
+  const setExpanded = useCallback(
+    (id: string, expanded: boolean) => {
+      const computeNext = (): SingleValue | MultiValue => {
+        if (mode === 'multi') {
+          const current = isMulti(resolvedValue) ? resolvedValue : new Set<string>();
+          const next = new Set(current);
+          if (expanded) {
+            next.add(id);
+          } else {
+            next.delete(id);
+          }
+          return next;
+        }
+        return expanded ? id : undefined;
+      };
+      const next = computeNext();
+      if (!isControlled) {
+        setInternalValue(next);
+      }
+      onValueChange?.(next as ValueFor<typeof mode>);
+    },
+    [mode, resolvedValue, isControlled, onValueChange],
+  );
+
+  const bind = useCallback(
+    (id: string): DisclosureItemBinding => {
+      const expanded = isExpanded(id);
+      const triggerId = `${idPrefix}-${id}-trigger`;
+      const panelId = `${idPrefix}-${id}-panel`;
+      return {
+        expanded,
+        toggle: () => setExpanded(id, !expanded),
+        triggerId,
+        panelId,
+        triggerProps: {
+          id: triggerId,
+          'aria-expanded': expanded,
+          'aria-controls': panelId,
+          onClick: () => setExpanded(id, !expanded),
+        },
+        panelProps: {
+          id: panelId,
+          role: 'region',
+          'aria-labelledby': triggerId,
+        },
+      };
+    },
+    [idPrefix, isExpanded, setExpanded],
+  );
+
+  return { bind };
+};

package/src/aspects/useListGrid.test.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { renderHook } from '@testing-library/react';
+import { describe, test } from 'vitest';
+
+import { useListGrid } from './useListGrid';
+
+describe('useListGrid', () => {
+  test('emits handle + title only by default', ({ expect }) => {
+    const { result } = renderHook(() => useListGrid());
+    expect(result.current.rowProps.style.gridTemplateColumns).toBe('var(--dx-rail-item) 1fr');
+  });
+
+  test('appends action slots between title and trailing', ({ expect }) => {
+    const { result } = renderHook(() => useListGrid({ actionSlots: 2 }));
+    expect(result.current.rowProps.style.gridTemplateColumns).toBe(
+      'var(--dx-rail-item) 1fr var(--dx-rail-item) var(--dx-rail-item)',
+    );
+  });
+
+  test('reserves expand and trailing slots when requested', ({ expect }) => {
+    const { result } = renderHook(() => useListGrid({ expandable: true, trailing: true }));
+    expect(result.current.rowProps.style.gridTemplateColumns).toBe(
+      'var(--dx-rail-item) 1fr var(--dx-rail-item) var(--dx-rail-item)',
+    );
+  });
+
+  test('combines actions, expand, and trailing in declared order', ({ expect }) => {
+    const { result } = renderHook(() => useListGrid({ actionSlots: 1, expandable: true, trailing: true }));
+    expect(result.current.rowProps.style.gridTemplateColumns).toBe(
+      'var(--dx-rail-item) 1fr var(--dx-rail-item) var(--dx-rail-item) var(--dx-rail-item)',
+    );
+  });
+
+  test('anchors columns to the row top so trailing does not shift on body growth', ({ expect }) => {
+    const { result } = renderHook(() => useListGrid({ trailing: true }));
+    expect(result.current.rowProps.className).toContain('items-start');
+  });
+});

package/src/aspects/useListGrid.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type CSSProperties, useMemo } from 'react';
+
+export type UseListGridOptions = {
+  /**
+   * Number of inline action slots between title and expand caret. Each slot is sized to
+   * `var(--dx-rail-item)` so an `IconButton` lands on the same baseline as the trailing icon.
+   */
+  actionSlots?: number;
+  /** Reserve an expand-caret slot at the end of the title row. */
+  expandable?: boolean;
+  /** Reserve a trailing-action slot outside the row's card (e.g. delete). */
+  trailing?: boolean;
+};
+
+export type UseListGridReturn = {
+  /** Spread onto the outer row element to apply the grid template. */
+  rowProps: { className: string; style: CSSProperties };
+};
+
+/**
+ * Row layout aspect. Generates the CSS grid template that keeps drag handle, title,
+ * inline actions, expand caret, and trailing icon co-aligned on the same line —
+ * independent of whether the row body is expanded.
+ *
+ * Width tracks are `var(--dx-rail-item)` for icon-button slots and `1fr` for the
+ * title, so every icon-shaped slot is the same width as `IconBlock` / `IconButton iconOnly`
+ * and the line aligns without per-pixel adjustments.
+ */
+export const useListGrid = ({
+  actionSlots = 0,
+  expandable = false,
+  trailing = false,
+}: UseListGridOptions = {}): UseListGridReturn => {
+  // Grid columns: [handle] [title=1fr] [action × N] [expand?] [trailing?]
+  // `items-start` keeps trailing/handle anchored to the row top so they don't shift
+  // when the title-row card grows vertically (e.g. on expand).
+  const gridTemplateColumns = useMemo(() => {
+    const tracks = ['var(--dx-rail-item)', '1fr'];
+    for (let index = 0; index < actionSlots; index++) {
+      tracks.push('var(--dx-rail-item)');
+    }
+    if (expandable) {
+      tracks.push('var(--dx-rail-item)');
+    }
+    if (trailing) {
+      tracks.push('var(--dx-rail-item)');
+    }
+    return tracks.join(' ');
+  }, [actionSlots, expandable, trailing]);
+
+  return {
+    rowProps: {
+      className: 'grid items-start gap-1',
+      style: { gridTemplateColumns },
+    },
+  };
+};

package/src/aspects/useListNavigation.test.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { renderHook } from '@testing-library/react';
+import { describe, test } from 'vitest';
+
+import { useListNavigation } from './useListNavigation';
+
+describe('useListNavigation', () => {
+  test('list mode emits role=list / listitem with vertical orientation', ({ expect }) => {
+    const { result } = renderHook(() => useListNavigation({ mode: 'list' }));
+    expect(result.current.containerProps.role).toBe('list');
+    expect(result.current.containerProps['aria-orientation']).toBe('vertical');
+    expect(result.current.itemProps().role).toBe('listitem');
+    expect(result.current.itemProps().tabIndex).toBe(-1);
+  });
+
+  test('listbox mode emits role=listbox / option with focusable items', ({ expect }) => {
+    const { result } = renderHook(() => useListNavigation({ mode: 'listbox' }));
+    expect(result.current.containerProps.role).toBe('listbox');
+    expect(result.current.itemProps().role).toBe('option');
+    expect(result.current.itemProps().tabIndex).toBe(0);
+  });
+
+  test('grid mode emits role=grid / row and omits aria-orientation', ({ expect }) => {
+    const { result } = renderHook(() => useListNavigation({ mode: 'grid' }));
+    expect(result.current.containerProps.role).toBe('grid');
+    expect(result.current.containerProps['aria-orientation']).toBeUndefined();
+    expect(result.current.itemProps().role).toBe('row');
+  });
+
+  test('disabled item carries aria-disabled', ({ expect }) => {
+    const { result } = renderHook(() => useListNavigation({ mode: 'listbox' }));
+    expect(result.current.itemProps({ disabled: true })['aria-disabled']).toBe(true);
+    expect(result.current.itemProps()['aria-disabled']).toBeUndefined();
+  });
+
+  test('emits Tabster data attributes on the container', ({ expect }) => {
+    const { result } = renderHook(() => useListNavigation({ mode: 'listbox' }));
+    const tabsterKeys = Object.keys(result.current.containerProps).filter((key) => key.startsWith('data-tabster'));
+    expect(tabsterKeys.length).toBeGreaterThan(0);
+  });
+});

package/src/aspects/useListNavigation.ts

@@ -0,0 +1,160 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type TabsterDOMAttribute, useArrowNavigationGroup } from '@fluentui/react-tabster';
+import { type FocusEvent, useCallback, useMemo } from 'react';
+
+export type ListNavigationMode = 'list' | 'listbox' | 'grid';
+
+export type UseListNavigationOptions = {
+  /**
+   * Determines the bundled ARIA role + keyboard wiring.
+   *
+   * - `list` — `role='list'` items are `role='listitem'`. Arrow keys move focus among
+   *   interactive descendants of the row (handles, buttons). No selection semantics.
+   * - `listbox` — `role='listbox'` items are `role='option'`. Arrow keys move focus
+   *   between options; `memorizeCurrent` keeps the last-focused option when re-entering.
+   * - `grid` — `role='grid'` items are `role='row'`. Two-axis arrow navigation.
+   */
+  mode: ListNavigationMode;
+  /**
+   * Override default axis. `list` and `listbox` default to `'vertical'`; `grid`
+   * defaults to `'grid'` (two-axis). Set explicitly when a horizontal list is needed.
+   */
+  axis?: 'vertical' | 'horizontal' | 'grid' | 'grid-linear' | 'both';
+  /**
+   * Remember the last-focused item when re-entering the group. Defaults to `true`.
+   * Only meaningful for `listbox` mode.
+   */
+  memorizeCurrent?: boolean;
+};
+
+type ContainerRole = 'list' | 'listbox' | 'grid';
+type ItemRole = 'listitem' | 'option' | 'row';
+
+export type UseListNavigationReturn = {
+  /**
+   * Spread onto the container element to apply role + ARIA + Tabster attributes.
+   * Also wires a focus-on-entry handler that redirects to the selected or first
+   * focusable item — Tabster doesn't cover initial focus, only traversal.
+   *
+   * The shape is intentionally open — Tabster's `useArrowNavigationGroup` returns
+   * `TabsterDOMAttribute` (one or more `data-tabster*` attributes that may be undefined
+   * when the runtime is disabled), and the precise key set isn't part of Tabster's
+   * stable contract.
+   */
+  containerProps: TabsterDOMAttribute & {
+    role: ContainerRole;
+    'aria-orientation'?: 'vertical' | 'horizontal';
+    onFocus: (event: FocusEvent<HTMLElement>) => void;
+  };
+  /**
+   * Apply to each item. Returns role, tabIndex, and aria-disabled. Disabled options remain
+   * focusable so screen readers can announce them, per WAI-ARIA listbox guidance.
+   */
+  itemProps: (opts?: { disabled?: boolean }) => {
+    role: ItemRole;
+    tabIndex: number;
+    'aria-disabled'?: true;
+  };
+};
+
+const containerRoleByMode: Record<ListNavigationMode, ContainerRole> = {
+  list: 'list',
+  listbox: 'listbox',
+  grid: 'grid',
+};
+
+const itemRoleByMode: Record<ListNavigationMode, ItemRole> = {
+  list: 'listitem',
+  listbox: 'option',
+  grid: 'row',
+};
+
+const defaultAxisByMode: Record<ListNavigationMode, 'vertical' | 'horizontal' | 'grid'> = {
+  list: 'vertical',
+  listbox: 'vertical',
+  grid: 'grid',
+};
+
+/**
+ * Find the focus-on-entry target inside a listbox container: the currently-selected
+ * option, or the first non-disabled option. Used to give arrow-key navigation a
+ * meaningful starting point when focus first lands on the listbox itself.
+ */
+const findListboxEntryTarget = (container: HTMLElement): HTMLElement | null => {
+  return (
+    container.querySelector<HTMLElement>('[role="option"][aria-selected="true"]:not([aria-disabled="true"])') ??
+    container.querySelector<HTMLElement>('[role="option"]:not([aria-disabled="true"])')
+  );
+};
+
+/**
+ * Keyboard navigation + ARIA role aspect for list-shaped surfaces. Wraps Tabster's
+ * `useArrowNavigationGroup` with a `mode` that selects the appropriate role bundle
+ * and adds a focus-on-entry redirect (Tabster handles traversal once focus is on a
+ * child; first-entry is the consumer's responsibility).
+ *
+ * Canonical for all list-shaped surfaces (List, OrderedList, RowList, Tree,
+ * Combobox.List, Mosaic.Stack). Non-list focus zones — e.g. Composer's multi-pane
+ * chrome — should keep their own Tabster wiring (Focus.Group).
+ */
+export const useListNavigation = ({
+  mode,
+  axis,
+  memorizeCurrent = true,
+}: UseListNavigationOptions): UseListNavigationReturn => {
+  const tabsterAttrs = useArrowNavigationGroup({
+    axis: axis ?? defaultAxisByMode[mode],
+    memorizeCurrent,
+  });
+
+  const handleFocus = useCallback(
+    (event: FocusEvent<HTMLElement>) => {
+      if (event.target !== event.currentTarget) {
+        // Focus is already on a descendant; Tabster handles traversal from here.
+        return;
+      }
+      if (mode !== 'listbox') {
+        return;
+      }
+      // First-time entry on the listbox itself: redirect focus into a meaningful child
+      // so arrow keys have an immediate starting point.
+      const target = findListboxEntryTarget(event.currentTarget);
+      target?.focus();
+    },
+    [mode],
+  );
+
+  // `aria-orientation` only accepts 'vertical' or 'horizontal'. Tabster's `axis` permits
+  // grid-shaped values too ('grid', 'grid-linear', 'both'); collapse those (and the grid mode
+  // itself) so we never leak an invalid ARIA value into the DOM.
+  const orientation: 'vertical' | 'horizontal' | undefined =
+    mode === 'grid' ? undefined : axis === 'horizontal' ? 'horizontal' : 'vertical';
+
+  const containerProps = useMemo(
+    () => ({
+      role: containerRoleByMode[mode],
+      ...(orientation && { 'aria-orientation': orientation }),
+      ...tabsterAttrs,
+      onFocus: handleFocus,
+    }),
+    [mode, orientation, tabsterAttrs, handleFocus],
+  );
+
+  // Listbox items need tabIndex=0 so Tabster can focus them; list/grid items inherit
+  // their tabIndex from their interactive descendants (button-shaped handles, links).
+  const itemRole = itemRoleByMode[mode];
+  const itemTabIndex = mode === 'listbox' ? 0 : -1;
+  const itemProps = useCallback(
+    ({ disabled }: { disabled?: boolean } = {}) => ({
+      role: itemRole,
+      tabIndex: itemTabIndex,
+      ...(disabled && { 'aria-disabled': true as const }),
+    }),
+    [itemRole, itemTabIndex],
+  );
+
+  return { containerProps, itemProps };
+};