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

package/src/aspects/useListSelection.test.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { act, renderHook } from '@testing-library/react';
+import { type FocusEvent } from 'react';
+import { describe, test, vi } from 'vitest';
+
+import { useListSelection } from './useListSelection';
+
+// Minimal synthetic focus event exposing only the fields the selection-follows-focus handler reads.
+// Constructing a partial event for a unit test is a genuine type boundary (React synthesizes the rest).
+const focusEvent = (
+  fields: Pick<FocusEvent<HTMLElement>, 'currentTarget' | 'relatedTarget'>,
+): FocusEvent<HTMLElement> => fields as FocusEvent<HTMLElement>;
+
+describe('useListSelection', () => {
+  describe('single mode', () => {
+    test('click selects the row', ({ expect }) => {
+      const onValueChange = vi.fn();
+      const { result } = renderHook(() => useListSelection({ mode: 'single', onValueChange }));
+      act(() => result.current.bind('a').rowProps.onClick({} as any));
+      expect(onValueChange).toHaveBeenLastCalledWith('a');
+    });
+
+    test('focus selects the row when selection-follows-focus is enabled (default)', ({ expect }) => {
+      const onValueChange = vi.fn();
+      const { result } = renderHook(() => useListSelection({ mode: 'single', onValueChange }));
+      act(() => result.current.bind('a').rowProps.onFocus?.({} as any));
+      expect(onValueChange).toHaveBeenLastCalledWith('a');
+    });
+
+    test('focus entering the list from outside does not change selection', ({ expect }) => {
+      const onValueChange = vi.fn();
+      // A listbox with one option, and an unrelated element outside it.
+      const container = document.createElement('div');
+      container.setAttribute('role', 'listbox');
+      const optionA = document.createElement('div');
+      const outside = document.createElement('div');
+      container.append(optionA);
+      document.body.append(container, outside);
+
+      const { result } = renderHook(() => useListSelection({ mode: 'single', value: 'b', onValueChange }));
+
+      // Entry focus (e.g. a popover auto-focusing on open): relatedTarget is outside the list.
+      act(() =>
+        result.current.bind('a').rowProps.onFocus?.(focusEvent({ currentTarget: optionA, relatedTarget: outside })),
+      );
+      expect(onValueChange).not.toHaveBeenCalled();
+
+      // Navigation within the list: relatedTarget is inside the list, so selection follows focus.
+      act(() =>
+        result.current.bind('a').rowProps.onFocus?.(focusEvent({ currentTarget: optionA, relatedTarget: container })),
+      );
+      expect(onValueChange).toHaveBeenLastCalledWith('a');
+
+      container.remove();
+      outside.remove();
+    });
+
+    test('disabled rows do not update selection on click', ({ expect }) => {
+      const onValueChange = vi.fn();
+      const { result } = renderHook(() => useListSelection({ mode: 'single', onValueChange }));
+      act(() => result.current.bind('a', { disabled: true }).rowProps.onClick({} as any));
+      expect(onValueChange).not.toHaveBeenCalled();
+    });
+
+    test('aria-selected mirrors controlled value', ({ expect }) => {
+      const { result, rerender } = renderHook(({ value }) => useListSelection({ mode: 'single', value }), {
+        initialProps: { value: 'a' as string | undefined },
+      });
+      expect(result.current.bind('a').rowProps['aria-selected']).toBe(true);
+      expect(result.current.bind('b').rowProps['aria-selected']).toBe(false);
+      rerender({ value: 'b' });
+      expect(result.current.bind('a').rowProps['aria-selected']).toBe(false);
+      expect(result.current.bind('b').rowProps['aria-selected']).toBe(true);
+    });
+  });
+
+  describe('multi mode', () => {
+    test('click toggles row in/out of selection set', ({ expect }) => {
+      const onValueChange = vi.fn();
+      const { result } = renderHook(() => useListSelection({ mode: 'multi', onValueChange }));
+      act(() => result.current.bind('a').rowProps.onClick({} as any));
+      const firstCall = onValueChange.mock.calls[0]?.[0] as Set<string>;
+      expect(firstCall.has('a')).toBe(true);
+    });
+
+    test('does not follow focus by default', ({ expect }) => {
+      const { result } = renderHook(() => useListSelection({ mode: 'multi' }));
+      expect(result.current.bind('a').rowProps.onFocus).toBeUndefined();
+    });
+
+    test('follows focus when explicitly enabled', ({ expect }) => {
+      const onValueChange = vi.fn();
+      const { result } = renderHook(() => useListSelection({ mode: 'multi', followsFocus: true, onValueChange }));
+      act(() => result.current.bind('a').rowProps.onFocus?.({} as any));
+      expect(onValueChange).toHaveBeenCalled();
+    });
+  });
+});

package/src/aspects/useListSelection.ts

@@ -0,0 +1,162 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type FocusEvent, type MouseEvent, useCallback, useEffect, useRef, useState } from 'react';
+
+export type ListSelectionMode = 'single' | 'multi';
+
+type SingleValue = string | undefined;
+type MultiValue = ReadonlySet<string>;
+
+type ValueFor<M extends ListSelectionMode> = M extends 'single' ? SingleValue : MultiValue;
+
+export type UseListSelectionOptions<M extends ListSelectionMode = ListSelectionMode> = {
+  mode: M;
+  /** Controlled selected id (single mode) or set of ids (multi mode). */
+  value?: ValueFor<M>;
+  defaultValue?: ValueFor<M>;
+  onValueChange?: (next: ValueFor<M>) => void;
+  /**
+   * Selection follows focus. Defaults to `true` for single-select (matches the WAI-ARIA
+   * listbox pattern) and `false` for multi-select (focus and toggle are separate gestures).
+   */
+  followsFocus?: boolean;
+};
+
+export type SelectionItemBinding = {
+  selected: boolean;
+  toggle: () => void;
+  /** Spread onto the row element to bind click + focus + ARIA. */
+  rowProps: {
+    'aria-selected': boolean;
+    onClick: (event: MouseEvent) => void;
+    onFocus?: (event: FocusEvent) => void;
+  };
+};
+
+export type UseListSelectionReturn = {
+  bind: (id: string, opts?: { disabled?: boolean }) => SelectionItemBinding;
+};
+
+const isMulti = (value: SingleValue | MultiValue): value is MultiValue => value instanceof Set;
+
+/**
+ * Selection aspect for list-shaped surfaces. Owns single- or multi-select state with
+ * controllable value semantics; emits `aria-selected` + click/focus handlers per row.
+ *
+ * `single` mode: at most one selected id, selection follows focus by default. Matches the
+ * existing `RowList` behaviour and the WAI-ARIA listbox single-select pattern.
+ *
+ * `multi` mode: tracks a `Set<string>`. Selection does NOT follow focus by default — multi
+ * select usually pairs with an explicit toggle affordance (checkbox or keyboard Space) rather
+ * than implicit focus-tracking.
+ */
+export const useListSelection: {
+  <M extends ListSelectionMode>(opts: UseListSelectionOptions<M>): UseListSelectionReturn;
+} = (opts) => {
+  const { mode, value, defaultValue, onValueChange, followsFocus } = opts;
+
+  // Latches whenever the consumer passes the `value` prop key (even as undefined). A controlled
+  // single-select consumer (`selectedId: string | undefined`) must be able to clear to undefined
+  // without the row falling back to stale internal state — Radix `useControllableState` (1.1.0)
+  // mishandles that case, so we mirror useListDisclosure's hand-rolled controller here.
+  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);
+
+  useEffect(() => {
+    if (isControlled) {
+      setInternalValue(value);
+    }
+  }, [isControlled, value]);
+
+  const resolvedValue = isControlled ? value : internalValue;
+  const setResolvedValue = useCallback(
+    (next: SingleValue | MultiValue) => {
+      if (!isControlled) {
+        setInternalValue(next);
+      }
+      onValueChange?.(next as ValueFor<typeof mode>);
+    },
+    [isControlled, onValueChange, mode],
+  );
+
+  const isSelected = useCallback(
+    (id: string) => {
+      if (mode === 'multi') {
+        return isMulti(resolvedValue) && resolvedValue.has(id);
+      }
+      return resolvedValue === id;
+    },
+    [mode, resolvedValue],
+  );
+
+  const setSelected = useCallback(
+    (id: string, selected: boolean) => {
+      if (mode === 'multi') {
+        const current = isMulti(resolvedValue) ? resolvedValue : new Set<string>();
+        const next = new Set(current);
+        if (selected) {
+          next.add(id);
+        } else {
+          next.delete(id);
+        }
+        setResolvedValue(next);
+      } else {
+        setResolvedValue(selected ? id : undefined);
+      }
+    },
+    [mode, resolvedValue, setResolvedValue],
+  );
+
+  const followFocusDefault = mode === 'single';
+  const trackFocus = followsFocus ?? followFocusDefault;
+
+  const bind = useCallback(
+    (id: string, { disabled }: { disabled?: boolean } = {}): SelectionItemBinding => {
+      const selected = isSelected(id);
+      return {
+        selected,
+        toggle: () => {
+          if (!disabled) {
+            setSelected(id, mode === 'multi' ? !selected : true);
+          }
+        },
+        rowProps: {
+          'aria-selected': selected,
+          onClick: () => {
+            if (disabled) {
+              return;
+            }
+            setSelected(id, mode === 'multi' ? !selected : true);
+          },
+          ...(trackFocus && {
+            onFocus: (event: FocusEvent) => {
+              if (disabled || selected) {
+                return;
+              }
+              // Selection follows focus only while navigating *between* options within the list.
+              // Focus entering the list from outside (e.g. a popover auto-focusing on open) must
+              // not change selection, or it would clobber the controlled value when entry focus
+              // lands on a non-selected option. Detect entry via `relatedTarget`: a synthetic event
+              // without DOM context (unit tests) falls through to the original follow-focus path.
+              const container = event.currentTarget?.closest?.('[role="listbox"],[role="list"],[role="grid"]');
+              if (container && !container.contains(event.relatedTarget)) {
+                return;
+              }
+              setSelected(id, true);
+            },
+          }),
+        },
+      };
+    },
+    [isSelected, mode, setSelected, trackFocus],
+  );
+
+  return { bind };
+};

package/src/aspects/useReorder.ts

@@ -0,0 +1,370 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { autoScrollForElements } from '@atlaskit/pragmatic-drag-and-drop-auto-scroll/element';
+import {
+  type Edge,
+  attachClosestEdge,
+  extractClosestEdge,
+} from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge';
+import { getReorderDestinationIndex } from '@atlaskit/pragmatic-drag-and-drop-hitbox/util/get-reorder-destination-index';
+import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
+import {
+  type ElementDragPayload,
+  draggable,
+  dropTargetForElements,
+  monitorForElements,
+} from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
+import { type ReactNode, type RefCallback, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+/**
+ * Internal payload key. We attach this to every draggable's data so the root monitor can
+ * recognise drops that belong to its own list and ignore foreign payloads.
+ */
+const REORDER_LIST_KEY = '__dxosReorderListId';
+
+let reorderListIdCounter = 0;
+const allocateReorderListId = (): string => `reorder-${++reorderListIdCounter}`;
+
+export type ReorderAxis = 'vertical' | 'horizontal';
+
+export type ReorderItemState =
+  | { type: 'idle' }
+  | { type: 'preview'; container: HTMLElement }
+  | { type: 'dragging' }
+  | { type: 'dragging-over'; closestEdge: Edge | null };
+
+const IDLE: ReorderItemState = { type: 'idle' };
+
+export type UseReorderListOptions<T> = {
+  /** Authoritative item list. Read on each drop to compute the new index. */
+  items: readonly T[];
+  /** Stable identifier per item. The monitor uses this to find source/target indices. */
+  getId: (item: T) => string;
+  /** Called with `(fromIndex, toIndex)` when a drop completes inside this list. */
+  onMove: (fromIndex: number, toIndex: number) => void;
+  /** Drop axis. Defaults to `'vertical'`. */
+  axis?: ReorderAxis;
+  /** When true, drag handles report as disabled. Defaults to false. */
+  readonly?: boolean;
+  /** Forwarded to pragmatic-dnd's `getInitialData` on each draggable. */
+  getInitialData?: (item: T, index: number) => Record<string, unknown>;
+  /** Overrides the default `canDrop` (which matches payloads tagged with this list's id). */
+  canDrop?: (args: { source: ElementDragPayload }) => boolean;
+  /** Renderer for a custom native drag preview. */
+  getDragPreview?: (item: T) => ReactNode;
+};
+
+export type ReorderActive<T> = { id: string; item: T; container: HTMLElement } | null;
+
+/**
+ * Stable controller created by `useReorderList`. Item components consume it via
+ * `useReorderItem(controller, id)`. The controller is reference-stable across renders.
+ */
+export type ReorderListController<T> = {
+  /** Internal: list id; payload tagged with this is the only data the monitor accepts by default. */
+  listId: string;
+  /** Look up an item by id. Used by the item hook to bind pragmatic-dnd at register time. */
+  getItem: (id: string) => { item: T; index: number } | null;
+  /** Bind a row's pragmatic-dnd primitives. Idempotent; returns a cleanup function. */
+  bindItem: (
+    id: string,
+    refs: { row: HTMLElement; handle: HTMLElement },
+    onItemState: (state: ReorderItemState) => void,
+  ) => () => void;
+};
+
+export type UseReorderListReturn<T> = {
+  controller: ReorderListController<T>;
+  /** The currently-dragging item, or null. Used by global drag preview portals. */
+  active: ReorderActive<T>;
+  /** Same as `controller.listId`. Exposed for diagnostics. */
+  listId: string;
+};
+
+/**
+ * List-level reorder aspect. Spins up pragmatic-dnd's `monitorForElements` and produces a
+ * stable controller that per-row hooks consume. Item registration + the per-item draggable /
+ * drop-target wiring lives in `useReorderItem` so each row owns its own React state without
+ * re-rendering siblings on hover.
+ */
+export const useReorderList = <T>({
+  items,
+  getId,
+  onMove,
+  axis = 'vertical',
+  readonly = false,
+  getInitialData,
+  canDrop,
+  getDragPreview,
+}: UseReorderListOptions<T>): UseReorderListReturn<T> => {
+  const listIdRef = useRef<string | null>(null);
+  if (!listIdRef.current) {
+    listIdRef.current = allocateReorderListId();
+  }
+  const listId = listIdRef.current;
+
+  // Stable refs to mutable inputs so the controller and the monitor effect don't tear down
+  // on every render. The functions returned in `controller` read from these refs.
+  const itemsRef = useRef(items);
+  itemsRef.current = items;
+  const getIdRef = useRef(getId);
+  getIdRef.current = getId;
+  const onMoveRef = useRef(onMove);
+  onMoveRef.current = onMove;
+  const canDropRef = useRef(canDrop);
+  canDropRef.current = canDrop;
+  const getInitialDataRef = useRef(getInitialData);
+  getInitialDataRef.current = getInitialData;
+  const getDragPreviewRef = useRef(getDragPreview);
+  getDragPreviewRef.current = getDragPreview;
+  const readonlyRef = useRef(readonly);
+  readonlyRef.current = readonly;
+
+  const [active, setActive] = useState<ReorderActive<T>>(null);
+
+  const findIndex = useCallback((id: string): number => {
+    return itemsRef.current.findIndex((item) => getIdRef.current(item) === id);
+  }, []);
+
+  const findIndexFromPayload = useCallback(
+    (data: Record<string, unknown> | undefined): number => {
+      if (!data || data[REORDER_LIST_KEY] !== listId) {
+        return -1;
+      }
+      const id = data.id as string | undefined;
+      return id ? findIndex(id) : -1;
+    },
+    [listId, findIndex],
+  );
+
+  // The list-level monitor watches drops belonging to this list and computes the destination
+  // index using pragmatic-dnd's helper. Mounted once per list lifetime.
+  useEffect(() => {
+    return monitorForElements({
+      canMonitor: ({ source }) => {
+        if (canDropRef.current) {
+          return canDropRef.current({ source });
+        }
+        return source.data[REORDER_LIST_KEY] === listId;
+      },
+      onDrop: ({ location, source }) => {
+        const target = location.current.dropTargets[0];
+        if (!target) {
+          return;
+        }
+        const sourceIdx = findIndexFromPayload(source.data);
+        const targetIdx = findIndexFromPayload(target.data);
+        if (sourceIdx < 0 || targetIdx < 0) {
+          return;
+        }
+        const destinationIndex = getReorderDestinationIndex({
+          closestEdgeOfTarget: extractClosestEdge(target.data),
+          startIndex: sourceIdx,
+          indexOfTarget: targetIdx,
+          axis,
+        });
+        onMoveRef.current(sourceIdx, destinationIndex);
+      },
+    });
+  }, [listId, axis, findIndexFromPayload]);
+
+  // The controller is reference-stable. Item-level hooks call `bindItem` to register their
+  // DOM elements with pragmatic-dnd; `getItem` is the synchronous lookup used at bind time.
+  const controller = useMemo<ReorderListController<T>>(
+    () => ({
+      listId,
+      getItem: (id) => {
+        const index = findIndex(id);
+        if (index < 0) {
+          return null;
+        }
+        return { item: itemsRef.current[index], index };
+      },
+      bindItem: (id, refs, onItemState) => {
+        const lookup = () => {
+          const index = findIndex(id);
+          return { item: itemsRef.current[index], index };
+        };
+        const { item, index } = lookup();
+        if (!item && index < 0) {
+          return () => {};
+        }
+        const allowedEdges: Edge[] = axis === 'vertical' ? ['top', 'bottom'] : ['left', 'right'];
+        return combine(
+          draggable({
+            element: refs.row,
+            dragHandle: refs.handle,
+            canDrag: () => !readonlyRef.current,
+            getInitialData: () => {
+              const current = lookup();
+              return {
+                [REORDER_LIST_KEY]: listId,
+                id,
+                ...(getInitialDataRef.current?.(current.item, current.index) ?? {}),
+              };
+            },
+            onGenerateDragPreview: getDragPreviewRef.current
+              ? ({ nativeSetDragImage, source }) => {
+                  const rect = source.element.getBoundingClientRect();
+                  setCustomNativeDragPreview({
+                    nativeSetDragImage,
+                    getOffset: ({ container }) => ({ x: 20, y: container.getBoundingClientRect().height / 2 }),
+                    render: ({ container }) => {
+                      container.style.width = `${rect.width}px`;
+                      onItemState({ type: 'preview', container });
+                      const current = lookup();
+                      setActive({ id, item: current.item, container });
+                      return () => {
+                        onItemState(IDLE);
+                        setActive(null);
+                      };
+                    },
+                  });
+                }
+              : undefined,
+            onDragStart: () => {
+              onItemState({ type: 'dragging' });
+              const current = lookup();
+              setActive({ id, item: current.item, container: refs.row });
+            },
+            onDrop: () => {
+              onItemState(IDLE);
+              setActive(null);
+            },
+          }),
+          dropTargetForElements({
+            element: refs.row,
+            canDrop: ({ source }) => {
+              if (source.element === refs.row) {
+                return false;
+              }
+              if (canDropRef.current) {
+                return canDropRef.current({ source });
+              }
+              return source.data[REORDER_LIST_KEY] === listId;
+            },
+            getData: ({ input }) =>
+              attachClosestEdge({ [REORDER_LIST_KEY]: listId, id }, { element: refs.row, input, allowedEdges }),
+            getIsSticky: () => true,
+            onDragEnter: ({ self }) => {
+              onItemState({ type: 'dragging-over', closestEdge: extractClosestEdge(self.data) });
+            },
+            onDrag: ({ self }) => {
+              onItemState({ type: 'dragging-over', closestEdge: extractClosestEdge(self.data) });
+            },
+            onDragLeave: () => onItemState(IDLE),
+            onDrop: () => onItemState(IDLE),
+          }),
+        );
+      },
+    }),
+    [listId, axis, findIndex],
+  );
+
+  return { controller, active, listId };
+};
+
+export type ReorderItemBinding = {
+  rowRef: RefCallback<HTMLElement>;
+  handleRef: RefCallback<HTMLElement>;
+  state: ReorderItemState;
+  isDragging: boolean;
+  closestEdge: Edge | null;
+};
+
+/**
+ * Per-row reorder hook. Owns the row's local state and registers the row's DOM elements
+ * with the list controller once both `rowRef` and `handleRef` are attached. Unmounting (or
+ * detaching either ref) tears down the registration.
+ *
+ * Called inside the item component, not in the parent's render loop — this is what keeps
+ * us inside the rules of hooks.
+ */
+export const useReorderItem = <T>(controller: ReorderListController<T>, id: string): ReorderItemBinding => {
+  const [state, setState] = useState<ReorderItemState>(IDLE);
+
+  // Snapshot the attached DOM nodes between renders without disturbing the React tree. When
+  // both refs have resolved we register with the list controller; either detaching triggers
+  // cleanup so we never leak pragmatic-dnd bindings.
+  const rowElement = useRef<HTMLElement | null>(null);
+  const handleElement = useRef<HTMLElement | null>(null);
+  const cleanupRef = useRef<(() => void) | null>(null);
+
+  const tryRegister = useCallback(() => {
+    if (!rowElement.current || !handleElement.current) {
+      return;
+    }
+    cleanupRef.current?.();
+    cleanupRef.current = controller.bindItem(id, { row: rowElement.current, handle: handleElement.current }, setState);
+  }, [controller, id]);
+
+  const teardown = useCallback(() => {
+    cleanupRef.current?.();
+    cleanupRef.current = null;
+    setState(IDLE);
+  }, []);
+
+  // Re-register if the controller or id changes (e.g. items reorder identity-stable).
+  useEffect(() => {
+    tryRegister();
+    return teardown;
+  }, [tryRegister, teardown]);
+
+  const rowRef = useCallback<RefCallback<HTMLElement>>(
+    (node) => {
+      rowElement.current = node;
+      if (node) {
+        tryRegister();
+      } else {
+        teardown();
+      }
+    },
+    [tryRegister, teardown],
+  );
+
+  const handleRef = useCallback<RefCallback<HTMLElement>>(
+    (node) => {
+      handleElement.current = node;
+      if (node && rowElement.current) {
+        tryRegister();
+      } else if (!node) {
+        // Mirror rowRef: if either ref detaches, tear down pragmatic-dnd bindings so a
+        // re-attaching handle creates a fresh registration rather than racing the old one.
+        teardown();
+      }
+    },
+    [tryRegister, teardown],
+  );
+
+  return {
+    rowRef,
+    handleRef,
+    state,
+    isDragging: state.type === 'dragging',
+    closestEdge: state.type === 'dragging-over' ? state.closestEdge : null,
+  };
+};
+
+/**
+ * Wire pragmatic-dnd's auto-scroll on a scrollable container. While any pragmatic-dnd drag
+ * is in flight, hovering near the edges of the registered element scrolls the container
+ * automatically. Pair with `OrderedList.Viewport` (or any caller-owned ScrollArea) so long
+ * lists can be reordered without manually scrolling first.
+ *
+ * `autoScrollForElements` is global — it activates on every drag regardless of which list
+ * started it — so it's safe to register one element per scroll surface.
+ *
+ * Returns a callback ref so the registration fires as soon as the element attaches and the
+ * cleanup fires when it detaches; React doesn't re-run effects on mutable `ref.current`
+ * changes, so a plain `useEffect` on a `useRef` would miss late-mounting elements entirely.
+ */
+export const useReorderAutoScroll = (): RefCallback<HTMLElement> => {
+  const cleanupRef = useRef<(() => void) | null>(null);
+  return useCallback((node) => {
+    cleanupRef.current?.();
+    cleanupRef.current = node ? autoScrollForElements({ element: node }) : null;
+  }, []);
+};

package/src/components/Accordion/Accordion.stories.tsx

@@ -27,7 +27,7 @@ const DefaultStory = () => {
         <div className='flex flex-col w-full border-y border-separator divide-y divide-separator'>
           {items.map((item) => (
             <Accordion.Item key={item.id} item={item} classNames='border-x border-separator'>
-              <Accordion.ItemHeader>{item.name}</Accordion.ItemHeader>
+              <Accordion.ItemHeader icon='ph--circle--regular'>{item.name}</Accordion.ItemHeader>
               <Accordion.ItemBody>
                 <p>{item.text}</p>
               </Accordion.ItemBody>

package/src/components/Accordion/AccordionItem.tsx

@@ -9,7 +9,8 @@ import React, { type PropsWithChildren } from 'react';
 import { Icon, type ThemedClassName } from '@dxos/react-ui';
 import { mx } from '@dxos/ui-theme';
 
-import { type ListItemRecord } from '../List';
+// See `AccordionRoot.tsx` for the rationale on `ListItemRecord = any`.
+type ListItemRecord = any;
 import { useAccordionContext } from './AccordionRoot';
 
 const ACCORDION_ITEM_NAME = 'AccordionItem';
@@ -37,17 +38,21 @@ export const AccordionItem = <T extends ListItemRecord>({ children, classNames,
   );
 };
 
-export type AccordionItemHeaderProps = ThemedClassName<AccordionPrimitive.AccordionHeaderProps>;
+export type AccordionItemHeaderProps = ThemedClassName<AccordionPrimitive.AccordionHeaderProps & { icon?: string }>;
 
-export const AccordionItemHeader = ({ classNames, children, ...props }: AccordionItemHeaderProps) => {
+export const AccordionItemHeader = ({ classNames, children, icon, ...props }: AccordionItemHeaderProps) => {
   return (
     <AccordionPrimitive.Header {...props} className={mx(classNames)}>
-      <AccordionPrimitive.Trigger className='group flex items-center p-2 dx-focus-ring-inset w-full text-start'>
-        {children}
+      {/* `justify-between` pins the toggle caret to the trailing edge of the row regardless of
+          the header content's intrinsic width — so the affordance lives at a predictable
+          right-end position. The content wrapper grabs the remaining space. */}
+      <AccordionPrimitive.Trigger className='group flex items-center justify-between gap-2 p-2 dx-focus-ring-inset w-full text-start'>
+        {icon && <Icon icon={icon} size={4} />}
+        <span className='min-w-0 flex-1 truncate'>{children}</span>
         <Icon
           icon='ph--caret-right--regular'
           size={4}
-          classNames='transition-transform duration-200 group-data-[state=open]:rotate-90'
+          classNames='shrink-0 transition-transform duration-200 group-data-[state=open]:rotate-90'
         />
       </AccordionPrimitive.Trigger>
     </AccordionPrimitive.Header>