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

package/src/components/Picker/Picker.tsx

@@ -0,0 +1,439 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// `Picker` — generic listbox-with-input compound (the WAI-ARIA combobox
+// keyboard pattern, sans the search-domain bits).
+//
+// Owns:
+//   - The virtual-highlight selection model (`selectedValue` updated by
+//     arrow keys; items don't receive browser focus, the input retains it).
+//   - An item registry (`registerItem` / `unregisterItem`) used by the
+//     input's keyboard handler to walk DOM-order siblings.
+//   - Auto-select-first-when-items-change behaviour.
+//   - `triggerSelect` so Enter from the input fires the highlighted
+//     item's `onSelect`.
+//
+// Does NOT own:
+//   - Query / search state (`query`, `onSearch`, `debounceMs`) — that
+//     lives in `@dxos/react-ui-search`'s `SearchList`, which composes
+//     `Picker` + adds the search-themed wrapper.
+//   - Filtering / ranking — same, see `useSearchListResults`.
+//   - The `<ul role='listbox'>` wrapper. Caller provides one (today's
+//     `SearchList.Viewport` / future `Combobox.Content` puts the role
+//     on the scroll surface).
+//   - Translations.
+//
+// Compound shape (matches Radix Select / Combobox patterns):
+//
+//   <Picker.Root>
+//     <Picker.Input value={query} onValueChange={setQuery} />
+//     <YourScrollWrapper role='listbox'>
+//       {items.map(item => (
+//         <Picker.Item key={item.id} value={item.id} onSelect={…}>
+//           {item.label}
+//         </Picker.Item>
+//       ))}
+//     </YourScrollWrapper>
+//   </Picker.Root>
+//
+// Why two contexts (Item / Input) — performance: items don't re-render
+// when the input value changes; the input doesn't re-render when an
+// item registers / unregisters.
+
+import { Slot } from '@radix-ui/react-slot';
+import React, {
+  type ChangeEvent,
+  type ComponentPropsWithRef,
+  type KeyboardEvent,
+  type MouseEvent as ReactMouseEvent,
+  type PropsWithChildren,
+  type ReactNode,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import { type Density, type Elevation, Input, type ThemedClassName, useThemeContext } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import {
+  PickerInputContextProvider,
+  PickerItemContextProvider,
+  usePickerInputContext,
+  usePickerItemContext,
+} from './context';
+
+//
+// Internal types.
+//
+
+type ItemData = {
+  element: HTMLElement;
+  disabled?: boolean;
+  onSelect?: () => void;
+};
+
+//
+// Root — context provider; renders no DOM.
+//
+
+type PickerRootProps = PropsWithChildren<{}>;
+
+const PickerRoot = ({ children }: PickerRootProps) => {
+  const [selectedValue, setSelectedValue] = useState<string | undefined>(undefined);
+
+  // Item registry: value → { element, onSelect, disabled }.
+  const itemsRef = useRef<Map<string, ItemData>>(new Map());
+
+  // Bumped on every (un)register so the auto-select-first effect can fire.
+  const [itemVersion, setItemVersion] = useState(0);
+
+  // Auto-select first non-disabled item when the registry changes and the
+  // current selection is no longer valid (gone or disabled).
+  useEffect(() => {
+    const current = selectedValue !== undefined ? itemsRef.current.get(selectedValue) : undefined;
+    const isValid = current !== undefined && !current.disabled;
+    if (!isValid && itemsRef.current.size > 0) {
+      const entries = Array.from(itemsRef.current.entries()).filter(([, data]) => !data.disabled);
+      if (entries.length > 0) {
+        entries.sort(([, a], [, b]) => {
+          const position = a.element.compareDocumentPosition(b.element);
+          if (position & Node.DOCUMENT_POSITION_FOLLOWING) {
+            return -1;
+          }
+          if (position & Node.DOCUMENT_POSITION_PRECEDING) {
+            return 1;
+          }
+          return 0;
+        });
+        const firstValue = entries[0]?.[0];
+        if (firstValue !== undefined && firstValue !== selectedValue) {
+          setSelectedValue(firstValue);
+        }
+      } else if (selectedValue !== undefined) {
+        setSelectedValue(undefined);
+      }
+    }
+  }, [itemVersion, selectedValue]);
+
+  const registerItem = useCallback(
+    (value: string, element: HTMLElement | null, onSelect: (() => void) | undefined, disabled?: boolean) => {
+      if (element) {
+        itemsRef.current.set(value, { element, onSelect, disabled });
+        setItemVersion((v) => v + 1);
+      }
+    },
+    [],
+  );
+
+  const unregisterItem = useCallback((value: string) => {
+    itemsRef.current.delete(value);
+    setItemVersion((v) => v + 1);
+  }, []);
+
+  // DOM-order traversal of registered items (excludes disabled).
+  const getItemValues = useCallback(() => {
+    return Array.from(itemsRef.current.entries())
+      .filter(([, data]) => !data.disabled)
+      .sort(([, a], [, b]) => {
+        const position = a.element.compareDocumentPosition(b.element);
+        return position & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : position & Node.DOCUMENT_POSITION_PRECEDING ? 1 : 0;
+      })
+      .map(([value]) => value);
+  }, []);
+
+  const triggerSelect = useCallback(() => {
+    if (selectedValue !== undefined) {
+      const item = itemsRef.current.get(selectedValue);
+      item?.onSelect?.();
+    }
+  }, [selectedValue]);
+
+  // Stable: items subscribe to this. Excludes the volatile bits (input
+  // helpers) that change with every keystroke.
+  const itemContextValue = useMemo(
+    () => ({
+      selectedValue,
+      onSelectedValueChange: setSelectedValue,
+      registerItem,
+      unregisterItem,
+    }),
+    [selectedValue, registerItem, unregisterItem],
+  );
+
+  // Volatile: input subscribes to this. Includes the keyboard helpers.
+  const inputContextValue = useMemo(
+    () => ({
+      selectedValue,
+      onSelectedValueChange: setSelectedValue,
+      getItemValues,
+      triggerSelect,
+    }),
+    [selectedValue, getItemValues, triggerSelect],
+  );
+
+  return (
+    <PickerInputContextProvider {...inputContextValue}>
+      <PickerItemContextProvider {...itemContextValue}>{children}</PickerItemContextProvider>
+    </PickerInputContextProvider>
+  );
+};
+
+PickerRoot.displayName = 'Picker.Root';
+
+//
+// Input — text input with virtual-highlight keyboard handling.
+//
+
+type InputVariant = 'default' | 'subdued';
+
+type PickerInputProps = ThemedClassName<
+  Omit<ComponentPropsWithRef<'input'>, 'value'> & {
+    /** Controlled input value. Caller owns this — e.g. binds to query state. */
+    value?: string;
+    /** Called on every keystroke with the new input string. */
+    onValueChange?: (value: string) => void;
+    density?: Density;
+    elevation?: Elevation;
+    variant?: InputVariant;
+  }
+>;
+
+const PickerInput = forwardRef<HTMLInputElement, PickerInputProps>(
+  ({ value, onValueChange, onChange, onKeyDown, autoFocus, ...props }, forwardedRef) => {
+    const { hasIosKeyboard } = useThemeContext();
+    const { selectedValue, onSelectedValueChange, getItemValues, triggerSelect } =
+      usePickerInputContext('Picker.Input');
+
+    const handleChange = useCallback(
+      (event: ChangeEvent<HTMLInputElement>) => {
+        onValueChange?.(event.target.value);
+        onChange?.(event);
+      },
+      [onValueChange, onChange],
+    );
+
+    const handleKeyDown = useCallback(
+      (event: KeyboardEvent<HTMLInputElement>) => {
+        onKeyDown?.(event);
+        if (event.defaultPrevented) {
+          return;
+        }
+        const values = getItemValues();
+        if (values.length === 0) {
+          if (event.key === 'Escape') {
+            onValueChange?.('');
+          }
+          return;
+        }
+
+        const currentIndex = selectedValue !== undefined ? values.indexOf(selectedValue) : -1;
+
+        switch (event.key) {
+          case 'ArrowDown': {
+            event.preventDefault();
+            const nextIndex = currentIndex === -1 ? 0 : Math.min(currentIndex + 1, values.length - 1);
+            const nextValue = values[nextIndex];
+            if (nextValue !== undefined) {
+              onSelectedValueChange(nextValue);
+            }
+            break;
+          }
+          case 'ArrowUp': {
+            event.preventDefault();
+            const prevIndex = currentIndex === -1 ? values.length - 1 : Math.max(currentIndex - 1, 0);
+            const prevValue = values[prevIndex];
+            if (prevValue !== undefined) {
+              onSelectedValueChange(prevValue);
+            }
+            break;
+          }
+          case 'Enter': {
+            if (selectedValue !== undefined) {
+              event.preventDefault();
+              triggerSelect();
+            }
+            break;
+          }
+          case 'Home': {
+            event.preventDefault();
+            const firstValue = values[0];
+            if (firstValue !== undefined) {
+              onSelectedValueChange(firstValue);
+            }
+            break;
+          }
+          case 'End': {
+            event.preventDefault();
+            const lastValue = values[values.length - 1];
+            if (lastValue !== undefined) {
+              onSelectedValueChange(lastValue);
+            }
+            break;
+          }
+          case 'Escape': {
+            event.preventDefault();
+            if (selectedValue !== undefined) {
+              onSelectedValueChange(undefined);
+            } else {
+              onValueChange?.('');
+            }
+            break;
+          }
+        }
+      },
+      [selectedValue, onSelectedValueChange, getItemValues, triggerSelect, onValueChange, onKeyDown],
+    );
+
+    // Spread `value` only when defined: a caller that wants a
+    // controlled input passes `value` + `onValueChange`; a caller that
+    // just wants the keyboard pattern (Default story) passes neither
+    // and gets an uncontrolled input that accepts keystrokes normally.
+    // Without this guard `value={value ?? ''}` would force-control the
+    // input, swallowing every keystroke when no `onValueChange` is
+    // wired (input visually accepts characters then re-renders empty).
+    return (
+      <Input.Root>
+        <Input.TextInput
+          {...props}
+          autoFocus={autoFocus && !hasIosKeyboard}
+          {...(value !== undefined && { value })}
+          onChange={handleChange}
+          onKeyDown={handleKeyDown}
+          ref={forwardedRef}
+        />
+      </Input.Root>
+    );
+  },
+);
+
+PickerInput.displayName = 'Picker.Input';
+
+//
+// Item — option that registers in the parent's registry.
+//
+
+type PickerItemProps = ThemedClassName<{
+  /** Unique identifier; used by the registry and DOM-order traversal. */
+  value: string;
+  /** Callback when the item is committed (click, or Enter while highlighted). */
+  onSelect?: () => void;
+  /** Disable the item — registry-visible but not focusable, not navigable, not clickable. */
+  disabled?: boolean;
+  asChild?: boolean;
+  children?: ReactNode;
+}>;
+
+const PickerItem = forwardRef<HTMLDivElement, PickerItemProps>(
+  ({ classNames, value, onSelect, disabled, asChild, children, ...props }, forwardedRef) => {
+    const { selectedValue, onSelectedValueChange, registerItem, unregisterItem } = usePickerItemContext('Picker.Item');
+    const internalRef = useRef<HTMLDivElement>(null);
+
+    const isSelected = selectedValue === value && !disabled;
+
+    // Register on mount, unregister on unmount.
+    useEffect(() => {
+      const element = internalRef.current;
+      if (element) {
+        registerItem(value, element, onSelect, disabled);
+      }
+      return () => unregisterItem(value);
+    }, [value, onSelect, disabled, registerItem, unregisterItem]);
+
+    // Smooth-scroll the selected option into view.
+    useEffect(() => {
+      if (isSelected && internalRef.current) {
+        internalRef.current.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+      }
+    }, [isSelected]);
+
+    const handleClick = useCallback(() => {
+      if (disabled) {
+        return;
+      }
+      // Move the virtual highlight to the clicked item so subsequent
+      // arrow keys continue from here, then fire the caller's select.
+      onSelectedValueChange(value);
+      onSelect?.();
+    }, [disabled, value, onSelectedValueChange, onSelect]);
+
+    // Prevent the mousedown from moving focus off `Picker.Input` —
+    // browsers focus an element with any `tabIndex` (including `-1`) on
+    // click, which would steal focus from the input and break the
+    // input's arrow-key handler. Cancelling on `mousedown` keeps focus
+    // on the input while still letting the subsequent `click` fire.
+    const handleMouseDown = useCallback((event: ReactMouseEvent<HTMLElement>) => {
+      event.preventDefault();
+    }, []);
+
+    const Comp: any = asChild ? Slot : 'div';
+
+    // Default styling: pair `aria-selected` with `dx-selected` and add
+    // `dx-hover` for the standard hover affordance. Same grammar `Row`
+    // uses (see `ui-theme/src/css/components/selected.md`). Horizontal
+    // padding follows `--gutter` so item text aligns with sibling
+    // `Column.Center` content (input, status row); falls back to
+    // `0.75rem` (≈ `px-3`) when not nested under `Column.Root`. Vertical
+    // padding and the pointer cursor are baked in so callsites don't
+    // have to repeat them; callers can still append / override via
+    // `classNames`. `dx-selected` only fires when `aria-selected="true"`,
+    // which we set below from the virtual highlight — so unfocused
+    // items render plain.
+    return (
+      <Comp
+        {...props}
+        ref={(node: HTMLDivElement | null) => {
+          internalRef.current = node;
+          if (typeof forwardedRef === 'function') {
+            forwardedRef(node);
+          } else if (forwardedRef) {
+            forwardedRef.current = node;
+          }
+        }}
+        role='option'
+        aria-selected={isSelected}
+        aria-disabled={disabled}
+        data-selected={isSelected}
+        data-disabled={disabled}
+        data-value={value}
+        // tabIndex={-1} — combobox pattern keeps browser focus on the
+        // input; the selected option is highlighted via `aria-selected`,
+        // not via DOM focus. Differs from `Row` (listbox pattern,
+        // tabIndex={0}). See header comment.
+        tabIndex={-1}
+        className={mx(
+          'dx-hover dx-selected px-[var(--gutter,0.75rem)] py-1 cursor-pointer select-none',
+          disabled && 'opacity-50 cursor-not-allowed',
+          classNames,
+        )}
+        onMouseDown={handleMouseDown}
+        onClick={handleClick}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+PickerItem.displayName = 'Picker.Item';
+
+//
+// Public namespace.
+//
+
+export const Picker = {
+  Root: PickerRoot,
+  Input: PickerInput,
+  Item: PickerItem,
+};
+
+export type { PickerRootProps, PickerInputProps, PickerItemProps };
+
+// Re-export context hooks for higher layers (SearchList) that need to
+// compose: `useSearchListInputContext` etc. previously read these
+// values; they now route through Picker.
+export { usePickerInputContext, usePickerItemContext } from './context';

package/src/components/Picker/context.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Two contexts (Item / Input) instead of one — performance optimization
+// from the original SearchList: items don't subscribe to query / input
+// state, so typing in the input doesn't re-render every option.
+
+import { createContext } from '@radix-ui/react-context';
+
+/** Stable: items subscribe to selection, registry. Doesn't change on query. */
+export type PickerItemContextValue = {
+  /** Currently highlighted item value (virtual; not browser focus). */
+  selectedValue: string | undefined;
+  /** Update the highlighted value (e.g. arrow keys, hover). */
+  onSelectedValueChange: (value: string | undefined) => void;
+  /** Register an item for keyboard nav + DOM-order traversal. */
+  registerItem: (
+    value: string,
+    element: HTMLElement | null,
+    onSelect: (() => void) | undefined,
+    disabled?: boolean,
+  ) => void;
+  /** Unregister an item. */
+  unregisterItem: (value: string) => void;
+};
+
+/** Volatile: input subscribes to selection + the input keyboard helpers. */
+export type PickerInputContextValue = {
+  /** Currently highlighted item value. */
+  selectedValue: string | undefined;
+  /** Update the highlighted value. */
+  onSelectedValueChange: (value: string | undefined) => void;
+  /** Get registered item values in DOM order (excludes disabled). */
+  getItemValues: () => string[];
+  /** Trigger the highlighted item's `onSelect`. */
+  triggerSelect: () => void;
+};
+
+export const [PickerItemContextProvider, usePickerItemContext] = createContext<PickerItemContextValue>('PickerItem');
+
+export const [PickerInputContextProvider, usePickerInputContext] =
+  createContext<PickerInputContextValue>('PickerInput');

package/src/components/Picker/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { Picker, usePickerInputContext, usePickerItemContext } from './Picker';
+export type { PickerRootProps, PickerInputProps, PickerItemProps } from './Picker';

package/src/components/RowList/RowList.stories.tsx

@@ -0,0 +1,163 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+
+import { random } from '@dxos/random';
+import { Input, Panel, Toolbar } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { Row, RowList } from './RowList';
+
+random.seed(1);
+
+type TestItem = { id: string; name: string; description: string };
+
+const allItems: TestItem[] = Array.from({ length: 24 }, (_, i) => ({
+  id: `item-${i}`,
+  name: random.commerce.productName(),
+  description: random.lorem.sentences(2),
+}));
+
+//
+// Single configurable story for the basic-listbox variants
+// (Default / Thin / WithDisabled). MasterDetail and WithToolbar
+// diverge structurally and keep their own render functions per
+// AUDIT.md §11.
+//
+
+type StoryArgs = {
+  /** Items to render. Defaults to the full 24-item catalog. */
+  items?: TestItem[];
+  /** Forwards to `RowList.Viewport thin`. */
+  thin?: boolean;
+  /** Forwards to `RowList.Viewport padding`. */
+  padding?: boolean;
+  /** Index into `items` that should render disabled. */
+  disabledIndex?: number;
+  /** Render the description line under each row's name. */
+  showDescription?: boolean;
+};
+
+const DefaultStory = ({
+  items = allItems,
+  thin = false,
+  padding = false,
+  disabledIndex,
+  showDescription = true,
+}: StoryArgs = {}) => {
+  const [selected, setSelected] = useState<string | undefined>(items[0]?.id);
+  return (
+    <RowList.Root selectedId={selected} onSelectChange={setSelected}>
+      <RowList.Viewport thin={thin} padding={padding}>
+        <RowList.Content aria-label='Items'>
+          {items.map((item, i) => {
+            const disabled = i === disabledIndex;
+            return (
+              <Row key={item.id} id={item.id} disabled={disabled}>
+                <div className='font-medium'>
+                  {item.name}
+                  {disabled && ' (disabled)'}
+                </div>
+                {showDescription && <div className='text-sm text-description line-clamp-1'>{item.description}</div>}
+              </Row>
+            );
+          })}
+        </RowList.Content>
+      </RowList.Viewport>
+    </RowList.Root>
+  );
+};
+
+//
+// Master/detail — list is one pane of a layout.
+//
+
+const MasterDetailStory = () => {
+  const [selected, setSelected] = useState<string | undefined>(allItems[0].id);
+  const detail = allItems.find(({ id }) => id === selected);
+  return (
+    <div role='none' className='dx-container grid grid-cols-[20rem_1fr] divide-x divide-separator'>
+      <RowList.Root selectedId={selected} onSelectChange={setSelected}>
+        <RowList.Viewport>
+          <RowList.Content aria-label='Items'>
+            {allItems.map((item) => (
+              <Row key={item.id} id={item.id}>
+                <div className='font-medium'>{item.name}</div>
+              </Row>
+            ))}
+          </RowList.Content>
+        </RowList.Viewport>
+      </RowList.Root>
+      <div role='region' aria-label='Detail' className='dx-container p-4 overflow-auto'>
+        {detail && (
+          <>
+            <h2 className='text-lg font-semibold'>{detail.name}</h2>
+            <p className='text-description mt-2'>{detail.description}</p>
+          </>
+        )}
+      </div>
+    </div>
+  );
+};
+
+//
+// Toolbar + viewport siblings — Root is headless, so layout is the
+// caller's responsibility. `Panel` is the canonical chrome wrapper.
+//
+
+const WithToolbarStory = () => {
+  const [selected, setSelected] = useState<string | undefined>(allItems[0].id);
+  const [filter, setFilter] = useState('');
+  const filtered = allItems.filter((item) => item.name.toLowerCase().includes(filter.toLowerCase()));
+  return (
+    <RowList.Root selectedId={selected} onSelectChange={setSelected}>
+      <Panel.Root>
+        <Panel.Toolbar asChild>
+          <Toolbar.Root>
+            <Input.Root>
+              <Input.Label srOnly>Filter items</Input.Label>
+              <Input.TextInput
+                placeholder='Filter…'
+                value={filter}
+                onChange={(event) => setFilter(event.target.value)}
+              />
+            </Input.Root>
+          </Toolbar.Root>
+        </Panel.Toolbar>
+        <Panel.Content asChild>
+          <RowList.Viewport>
+            <RowList.Content aria-label='Items'>
+              {filtered.map((item) => (
+                <Row key={item.id} id={item.id}>
+                  {item.name}
+                </Row>
+              ))}
+            </RowList.Content>
+          </RowList.Viewport>
+        </Panel.Content>
+      </Panel.Root>
+    </RowList.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-list/RowList',
+  render: (args) => <DefaultStory {...args} />,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<StoryArgs>;
+
+export default meta;
+
+type Story = StoryObj<StoryArgs>;
+
+export const Default: Story = {};
+export const Thin: Story = { args: { thin: true, padding: true, showDescription: false } };
+export const WithDisabled: Story = { args: { items: allItems.slice(0, 6), disabledIndex: 2 } };
+export const MasterDetail: Story = { render: () => <MasterDetailStory /> };
+export const WithToolbar: Story = { render: () => <WithToolbarStory /> };