@dxos/react-ui-list 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/components/RowList/RowList.tsx

@@ -0,0 +1,353 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// `RowList` — Radix-style compound listbox / single-select picker.
+//
+// Compound shape (matches Radix Select / Toolbar / Tabs):
+//
+//   <RowList.Root selectedId={…} onSelectChange={…}>
+//     <RowList.Viewport thin padding>
+//       <RowList.Content aria-label='Tools'>
+//         <Row id='a'>…</Row>
+//         <Row id='b'>…</Row>
+//       </RowList.Content>
+//     </RowList.Viewport>
+//   </RowList.Root>
+//
+//   - `Root`     — headless context provider (no DOM). Owns the
+//                  single-select `selectedId` model.
+//   - `Viewport` — `ScrollArea.Root` + `ScrollArea.Viewport`. Always
+//                  scrolls. Forwards ScrollArea knobs (`thin`, `padding`,
+//                  `centered`).
+//   - `Content`  — the `<ul role="listbox">` holding the items. Carries
+//                  the tabster arrow-nav group and the `aria-label`.
+//   - `Row`      — `<li role="option">` with `aria-selected` on the
+//                  selected row, paired with `dx-selected` styling. See
+//                  `ui-theme/src/css/components/selected.md`.
+//
+// Single visual variant. Card-style rendering, denser/wider rows,
+// dividers, etc. are styling concerns layered on via `classNames` —
+// not separate components.
+//
+// Selection model:
+//
+//   This layer ships single-select (`selectedId: string | undefined`).
+//   Selection follows focus, so arrow keys + click both update it. This
+//   matches the codebase's existing `useSelected(_, 'single')` convention
+//   from `@dxos/react-ui-attention`.
+//
+//   Multi-select (`selectedIds: ReadonlySet<string>` + per-row checkbox
+//   affordance) is a future expansion point. When it lands it'll likely
+//   plumb through `react-ui-attention`'s `SelectionManager` for
+//   cross-context state sharing — but RowList itself can stay
+//   provider-agnostic, with consumers wiring it as they need.
+//
+// Composability:
+//
+//   `Viewport`, `Content`, and `Row` are all `composable()` from
+//   `@dxos/ui-theme` — they merge `classNames` + parent-Slot
+//   `className` via `composableProps()` and accept any standard HTML
+//   attributes. None expose `asChild`: Viewport can't (two nested
+//   elements, no coherent slot target), and Content / Row would need
+//   to abandon the `@dxos/react-list` primitive's context to honor it
+//   — not worth the complexity for this layer. If a consumer needs a
+//   `<button>`-as-row or a `<div>`-as-listbox, drop down to
+//   `@dxos/react-list` directly.
+//
+// Keyboard:
+//
+//   `useArrowNavigationGroup({ axis: 'vertical', memorizeCurrent: true })`
+//   from `@fluentui/react-tabster` is applied to `Content`. Tabster
+//   auto-initializes (`useTabster` lazy-creates the runtime) so no
+//   provider setup is required at the app/storybook level. ArrowUp /
+//   ArrowDown move focus among options.
+//
+//   When focus first lands on the `<ul>` itself (e.g. user tabs in),
+//   `Content` redirects focus into the selected option (or the first
+//   one) so arrow keys have an immediate starting point.
+//
+// What this layer deliberately does NOT do:
+//
+//   - Virtualization or drag-and-drop. Reach for `@dxos/react-ui-mosaic`.
+//   - Multi-select (see "Selection model" above; future expansion).
+
+import { useArrowNavigationGroup } from '@fluentui/react-tabster';
+import { createContextScope } from '@radix-ui/react-context';
+import { useControllableState } from '@radix-ui/react-use-controllable-state';
+import React, { type FocusEvent, type ForwardedRef, type MouseEvent, type PropsWithChildren, useCallback } from 'react';
+
+import { List, ListItem } from '@dxos/react-list';
+import { ScrollArea, type ScrollAreaRootProps } from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/ui-theme';
+
+const ROW_LIST_NAME = 'RowList';
+const ROW_LIST_ROOT_NAME = 'RowList.Root';
+const ROW_LIST_VIEWPORT_NAME = 'RowList.Viewport';
+const ROW_LIST_CONTENT_NAME = 'RowList.Content';
+const ROW_NAME = 'List.Row';
+
+//
+// Context — Radix-scoped so future composition (a tree of nested
+// RowLists, or a parent like a Combobox embedding RowList) can read
+// the right scope.
+//
+
+type RowListContextValue = {
+  /** The currently-selected option id. */
+  selectedId?: string;
+  /** Set the selected option (called from click, arrow nav, focus). */
+  setSelected: (id: string) => void;
+};
+
+const [createRowListContext, createRowListScope] = createContextScope(ROW_LIST_NAME, []);
+const [RowListProvider, useRowListContext] = createRowListContext<RowListContextValue>(ROW_LIST_NAME);
+
+//
+// Root — headless context provider. Renders no DOM.
+//
+
+type RootProps = PropsWithChildren<{
+  /** Currently-selected option id (controlled). */
+  selectedId?: string;
+  /** Initial selected option for uncontrolled mode. */
+  defaultSelectedId?: string;
+  /**
+   * Called when the user picks a different option (click, arrow keys,
+   * focus). Receives the option's `id` prop.
+   */
+  onSelectChange?: (id: string) => void;
+}>;
+
+const Root = ({ selectedId, defaultSelectedId, onSelectChange, children }: RootProps) => {
+  // `useControllableState`'s `onChange` is typed `(state: string | undefined) => void`,
+  // but our public `onSelectChange` is `(id: string) => void` (an `id` is always
+  // a string when emitted). Wrap to satisfy the type without leaking
+  // `undefined` to callers.
+  const [resolved, setResolved] = useControllableState<string | undefined>({
+    prop: selectedId,
+    defaultProp: defaultSelectedId,
+    onChange: (next) => {
+      if (next !== undefined) {
+        onSelectChange?.(next);
+      }
+    },
+  });
+
+  const setSelected = useCallback((id: string) => setResolved(id), [setResolved]);
+
+  return (
+    <RowListProvider scope={undefined} selectedId={resolved} setSelected={setSelected}>
+      {children}
+    </RowListProvider>
+  );
+};
+
+Root.displayName = ROW_LIST_ROOT_NAME;
+
+//
+// Viewport — ScrollArea wrapper. Always scrolls; forwards ScrollArea knobs.
+//
+
+// Subset of ScrollArea.Root props that make sense on a list viewport.
+// `orientation` is fixed to 'vertical' — for other knobs (autoHide,
+// snap, …) build your own ScrollArea wrapper and skip Viewport.
+//
+// `Viewport` is `composable()` rather than `slottable()` because there
+// is no coherent `asChild` semantic for a wrapper that always renders
+// two nested elements (`ScrollArea.Root` containing `ScrollArea.Viewport`).
+type ViewportProps = Pick<ScrollAreaRootProps, 'thin' | 'padding' | 'centered'>;
+
+const Viewport = composable<HTMLDivElement, ViewportProps>((props, forwardedRef) => {
+  const { thin, padding, centered, children, ...rest } = props as PropsWithChildren<
+    ViewportProps & Record<string, unknown>
+  >;
+  const composed = composableProps<HTMLDivElement>(rest, { classNames: 'dx-container' });
+  return (
+    <ScrollArea.Root
+      orientation='vertical'
+      thin={thin}
+      padding={padding}
+      centered={centered}
+      {...composed}
+      ref={forwardedRef}
+    >
+      <ScrollArea.Viewport>{children}</ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+});
+
+Viewport.displayName = ROW_LIST_VIEWPORT_NAME;
+
+//
+// Content — the listbox `<ul>` (tabster arrow group + aria-label).
+//
+
+type ContentProps = {
+  /**
+   * Accessible label for the listbox. Strongly recommended; assistive
+   * tech announces this when focus enters the list.
+   */
+  'aria-label'?: string;
+};
+
+// Find the first non-disabled `role='option'` descendant in DOM order.
+// Used as the focus-on-entry target so we don't land on a disabled row.
+const firstEnabledOption = (ul: HTMLElement | null): HTMLLIElement | null => {
+  if (!ul) {
+    return null;
+  }
+  return ul.querySelector<HTMLLIElement>('[role="option"]:not([aria-disabled="true"])');
+};
+
+const Content = composable<HTMLUListElement, ContentProps>((props, forwardedRef) => {
+  // Touch the context so Content fails loudly if used outside Root.
+  useRowListContext(ROW_LIST_CONTENT_NAME, undefined);
+
+  // Tabster arrow-key navigation. `useTabster` auto-initializes the
+  // runtime on first call, so no app/storybook-level setup is required.
+  // The data attributes returned here go onto the focusable container —
+  // the `<ul>` rendered by the primitive `<List>`.
+  const arrowGroup = useArrowNavigationGroup({ axis: 'vertical', memorizeCurrent: true });
+
+  const { children, ...rest } = props as PropsWithChildren<ContentProps & Record<string, unknown>>;
+
+  // When focus first enters the `<ul>` itself (e.g. user tabs in),
+  // redirect into the selected option (or the first enabled one) so
+  // arrow keys have an immediate starting point. Tabster doesn't do
+  // this — it manages traversal once focus is already on a child.
+  const handleFocus = useCallback((event: FocusEvent<HTMLUListElement>) => {
+    if (event.target !== event.currentTarget) {
+      return;
+    }
+    const ul = event.currentTarget;
+    const selected = ul.querySelector<HTMLLIElement>(
+      '[role="option"][aria-selected="true"]:not([aria-disabled="true"])',
+    );
+    const target = selected ?? firstEnabledOption(ul);
+    target?.focus();
+  }, []);
+
+  // Render via the primitive `<List>` so descendant `<ListItem>`s
+  // satisfy their Radix context-scope check. We don't pass `selectable`
+  // — we set `role='listbox'` and `aria-selected` ourselves in `Row`,
+  // so the primitive's listbox-mode plumbing isn't needed.
+  const composed = composableProps<HTMLUListElement>(rest, { classNames: 'flex flex-col' });
+  return (
+    <List
+      variant='unordered'
+      {...composed}
+      {...arrowGroup}
+      role='listbox'
+      onFocus={handleFocus}
+      ref={forwardedRef as unknown as ForwardedRef<HTMLOListElement>}
+    >
+      {children}
+    </List>
+  );
+});
+
+Content.displayName = ROW_LIST_CONTENT_NAME;
+
+//
+// Row — option item.
+//
+
+type RowProps = PropsWithChildren<{
+  /** Stable identifier; matched against the parent's `selectedId`. */
+  id: string;
+  /** Disable the row — focusable but doesn't update selection, dimmed. */
+  disabled?: boolean;
+  /** Optional click handler in addition to selection. */
+  onClick?: (event: MouseEvent<HTMLLIElement>) => void;
+  /** Optional focus handler in addition to selection-follows-focus. */
+  onFocus?: (event: FocusEvent<HTMLLIElement>) => void;
+}>;
+
+// `dx-selected` pairs with `aria-selected="true"` (set per-option below);
+// see `ui-theme/src/css/components/selected.md`.
+const ROW_BASE = 'dx-hover dx-selected px-3 py-2 cursor-pointer outline-none border-b border-separator last:border-b-0';
+
+const Row = composable<HTMLLIElement, RowProps>((props, forwardedRef) => {
+  const { id, disabled, onClick, onFocus, children, ...rest } = props as RowProps & Record<string, unknown>;
+  const { selectedId, setSelected } = useRowListContext(ROW_NAME, undefined);
+  const isSelected = selectedId === id;
+
+  const handleClick = useCallback(
+    (event: MouseEvent<HTMLLIElement>) => {
+      if (disabled) {
+        return;
+      }
+      setSelected(id);
+      onClick?.(event);
+    },
+    [disabled, id, setSelected, onClick],
+  );
+
+  // Selection-follows-focus: arrow nav (and any focus path) updates
+  // `selectedId` so the model stays in sync with what the user is
+  // looking at. Disabled rows are still focusable for screen-reader
+  // announcement but don't update the selection model.
+  const handleFocus = useCallback(
+    (event: FocusEvent<HTMLLIElement>) => {
+      if (!disabled && selectedId !== id) {
+        setSelected(id);
+      }
+      onFocus?.(event);
+    },
+    [disabled, selectedId, id, setSelected, onFocus],
+  );
+
+  const composed = composableProps<HTMLLIElement>(rest, {
+    classNames: [ROW_BASE, disabled && 'opacity-50 cursor-not-allowed'],
+  });
+
+  // Per WAI-ARIA APG listbox guidance, disabled options remain
+  // keyboard-navigable for SR announcement; the selection model is not
+  // updated for disabled rows (see `handleFocus` / `handleClick` above).
+  return (
+    <ListItem
+      {...composed}
+      role='option'
+      tabIndex={0}
+      aria-selected={isSelected}
+      aria-disabled={disabled || undefined}
+      onClick={handleClick}
+      onFocus={handleFocus}
+      ref={forwardedRef}
+    >
+      {children}
+    </ListItem>
+  );
+});
+
+Row.displayName = ROW_NAME;
+
+/**
+ * Read selection state for a single id, from inside any descendant of
+ * `<RowList.Root>`. Returns `true` when the row is currently selected.
+ * Lets composing components (e.g. `Listbox.OptionIndicator`) react to
+ * selection without re-rendering on unrelated changes.
+ */
+const useRowListSelection = (id: string): boolean => {
+  const { selectedId } = useRowListContext('useRowListSelection', undefined);
+  return selectedId === id;
+};
+
+//
+// Public namespace.
+//
+
+const RowList = {
+  Root,
+  Viewport,
+  Content,
+};
+
+export { RowList, Row, createRowListScope, useRowListSelection };
+export type {
+  RootProps as RowListRootProps,
+  ViewportProps as RowListViewportProps,
+  ContentProps as RowListContentProps,
+  RowProps,
+};

package/src/components/RowList/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { RowList, Row, createRowListScope, useRowListSelection } from './RowList';
+export type { RowListRootProps, RowListViewportProps, RowListContentProps, RowProps } from './RowList';

package/src/components/Tree/Tree.stories.tsx

@@ -2,30 +2,157 @@
 // Copyright 2024 DXOS.org
 //
 
-import { monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
 import { type Instruction, extractInstruction } from '@atlaskit/pragmatic-drag-and-drop-hitbox/tree-item';
+import { monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+import { Atom, RegistryContext } from '@effect-atom/atom-react';
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useEffect } from 'react';
+import React, { useCallback, useContext, useEffect, useMemo, useRef } from 'react';
 
-import { type Live, live } from '@dxos/live-object';
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 import { Icon } from '@dxos/react-ui';
 import { withTheme } from '@dxos/react-ui/testing';
+import { withRegistry } from '@dxos/storybook-utils';
 
 import { Path } from '../../util';
-
 import { type TestItem, createTree, updateState } from './testing';
-import { Tree, type TreeProps } from './Tree';
+import { Tree } from './Tree';
+import { type TreeModel } from './TreeContext';
 import { type TreeData } from './TreeItem';
 
-faker.seed(1234);
+random.seed(1234);
+
+const tree = createTree() as TestItem;
+
+const DefaultStory = ({ draggable }: { draggable?: boolean }) => {
+  const registry = useContext(RegistryContext);
+  const stateAtomsRef = useRef(new Map<string, Atom.Writable<{ open: boolean; current: boolean }>>());
+
+  const getOrCreateStateAtom = useCallback((pathKey: string) => {
+    let atom = stateAtomsRef.current.get(pathKey);
+    if (!atom) {
+      atom = Atom.make({ open: false, current: false }).pipe(Atom.keepAlive);
+      stateAtomsRef.current.set(pathKey, atom);
+    }
+    return atom;
+  }, []);
+
+  // Build a lookup map of all items by ID.
+  const itemMap = useMemo(() => {
+    const map = new Map<string, TestItem>();
+    const walk = (item: TestItem) => {
+      map.set(item.id, item);
+      item.items?.forEach(walk);
+    };
+    walk(tree);
+    return map;
+  }, []);
+
+  // Build a child IDs map keyed by parent ID.
+  const childIdsMap = useMemo(() => {
+    const map = new Map<string, string[]>();
+    const walk = (item: TestItem) => {
+      if (item.items) {
+        map.set(
+          item.id,
+          item.items.map((child) => child.id),
+        );
+        item.items.forEach(walk);
+      }
+    };
+    // Root children.
+    map.set(
+      tree.id,
+      (tree.items ?? []).map((child) => child.id),
+    );
+    walk(tree);
+    return map;
+  }, []);
+
+  const childIdsFamily = useMemo(
+    () => Atom.family((id: string) => Atom.make(() => childIdsMap.get(id) ?? []).pipe(Atom.keepAlive)),
+    [childIdsMap],
+  );
+
+  const itemFamily = useMemo(
+    () => Atom.family((id: string) => Atom.make(() => itemMap.get(id)).pipe(Atom.keepAlive)),
+    [itemMap],
+  );
+
+  const itemPropsFamily = useMemo(
+    () =>
+      Atom.family((pathKey: string) => {
+        const id = pathKey.split('~').pop()!;
+        return Atom.make(() => {
+          const parent = itemMap.get(id);
+          if (!parent) {
+            return { id, label: id };
+          }
+          return {
+            id: parent.id,
+            label: parent.name,
+            icon: parent.icon,
+            ...((parent.items?.length ?? 0) > 0 && {
+              parentOf: parent.items!.map(({ id }) => id),
+            }),
+          };
+        }).pipe(Atom.keepAlive);
+      }),
+    [itemMap],
+  );
+
+  const itemOpenFamily = useMemo(
+    () =>
+      Atom.family((pathKey: string) => {
+        const stateAtom = getOrCreateStateAtom(pathKey);
+        return Atom.make((get) => get(stateAtom).open).pipe(Atom.keepAlive);
+      }),
+    [getOrCreateStateAtom],
+  );
+
+  const itemCurrentFamily = useMemo(
+    () =>
+      Atom.family((pathKey: string) => {
+        const stateAtom = getOrCreateStateAtom(pathKey);
+        return Atom.make((get) => get(stateAtom).current).pipe(Atom.keepAlive);
+      }),
+    [getOrCreateStateAtom],
+  );
+
+  const model: TreeModel<TestItem> = useMemo(
+    () => ({
+      childIds: (parentId?: string) => childIdsFamily(parentId ?? tree.id),
+      item: (id: string) => itemFamily(id),
+      itemProps: (path: string[]) => itemPropsFamily(path.join('~')),
+      itemOpen: (path: string[]) => itemOpenFamily(Path.create(...path)),
+      itemCurrent: (path: string[]) => itemCurrentFamily(Path.create(...path)),
+    }),
+    [childIdsFamily, itemFamily, itemPropsFamily, itemOpenFamily, itemCurrentFamily],
+  );
+
+  const handleOpenChange = useCallback(
+    ({ path: pathProp, open }: { path: string[]; open: boolean }) => {
+      const path = Path.create(...pathProp);
+      const atom = getOrCreateStateAtom(path);
+      const prev = registry.get(atom);
+      registry.set(atom, { ...prev, open });
+    },
+    [getOrCreateStateAtom, registry],
+  );
+
+  const handleSelect = useCallback(
+    ({ path: pathProp, current }: { path: string[]; current: boolean }) => {
+      const path = Path.create(...pathProp);
+      const atom = getOrCreateStateAtom(path);
+      const prev = registry.get(atom);
+      registry.set(atom, { ...prev, current });
+    },
+    [getOrCreateStateAtom, registry],
+  );
 
-const DefaultStory = (props: TreeProps) => {
   useEffect(() => {
     return monitorForElements({
       canMonitor: ({ source }) => typeof source.data.id === 'string' && Array.isArray(source.data.path),
       onDrop: ({ location, source }) => {
-        // Didn't drop on anything.
         if (!location.current.dropTargets.length) {
           return;
         }
@@ -44,72 +171,34 @@ const DefaultStory = (props: TreeProps) => {
     });
   }, []);
 
-  return <Tree {...props} />;
+  return (
+    <Tree
+      model={model}
+      id={tree.id}
+      rootId={tree.id}
+      draggable={draggable}
+      renderColumns={() => (
+        <div className='flex items-center'>
+          <Icon icon='ph--placeholder--regular' />
+        </div>
+      )}
+      onOpenChange={handleOpenChange}
+      onSelect={handleSelect}
+    />
+  );
 };
 
-const tree = live<TestItem>(createTree());
-const state = new Map<string, Live<{ open: boolean; current: boolean }>>();
-
 const meta = {
   title: 'ui/react-ui-list/Tree',
 
-  decorators: [withTheme],
+  decorators: [withTheme(), withRegistry],
   component: Tree,
   render: DefaultStory,
-  args: {
-    id: tree.id,
-    useItems: (parent?: TestItem) => {
-      return parent?.items ?? tree.items;
-    },
-    getProps: (parent: TestItem) => ({
-      id: parent.id,
-      label: parent.name,
-      icon: parent.icon,
-      ...((parent.items?.length ?? 0) > 0 && {
-        parentOf: parent.items!.map(({ id }) => id),
-      }),
-    }),
-    isOpen: (_path: string[]) => {
-      const path = Path.create(..._path);
-      const object = state.get(path) ?? live({ open: false, current: false });
-      if (!state.has(path)) {
-        state.set(path, object);
-      }
-
-      return object.open;
-    },
-    isCurrent: (_path: string[]) => {
-      const path = Path.create(..._path);
-      const object = state.get(path) ?? live({ open: false, current: false });
-      if (!state.has(path)) {
-        state.set(path, object);
-      }
-
-      return object.current;
-    },
-    renderColumns: () => {
-      return (
-        <div className='flex items-center'>
-          <Icon icon='ph--placeholder--regular' size={5} />
-        </div>
-      );
-    },
-    onOpenChange: ({ path: _path, open }) => {
-      const path = Path.create(..._path);
-      const object = state.get(path);
-      object!.open = open;
-    },
-    onSelect: ({ path: _path, current }) => {
-      const path = Path.create(..._path);
-      const object = state.get(path);
-      object!.current = current;
-    },
-  },
 } satisfies Meta<typeof Tree<TestItem>>;
 
 export default meta;
 
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof DefaultStory>;
 
 export const Default: Story = {};