@dxos/react-ui-list 0.8.4-main.ead640a → 0.8.4-main.f466a3d56e

package/src/components/Listbox/Listbox.tsx

@@ -0,0 +1,201 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+// `Listbox` — single-select listbox with optional check indicator.
+//
+// Internally composes `RowList` from this same package: `Listbox.Root`
+// is `RowList.Root` + `RowList.Content`, and `Listbox.Option` is `Row`.
+// The compound API (`Listbox.Root` / `.Option` / `.OptionLabel` /
+// `.OptionIndicator`) is preserved so existing call sites keep working.
+//
+// Why this shape (when `RowList` is right there): `Listbox` historically
+// rendered as a flat `<ul>` with no `ScrollArea` wrapper — it's used
+// inside dialogs / popovers / panels that own their own scroll. Skipping
+// `RowList.Viewport` keeps that behaviour. If a caller wants the styled
+// scroll surface, they wrap the listbox in `RowList.Viewport` themselves.
+
+import { type Scope, createContextScope } from '@radix-ui/react-context';
+import React, { type ComponentPropsWithRef, type ReactNode, forwardRef } from 'react';
+
+import { Icon, type IconProps, type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { Row, RowList, createRowListScope, useRowListSelection } from '../RowList';
+
+const commandItem = 'flex items-center overflow-hidden';
+
+const LISTBOX_NAME = 'Listbox';
+const LISTBOX_OPTION_NAME = 'ListboxOption';
+const LISTBOX_OPTION_LABEL_NAME = 'ListboxOptionLabel';
+const LISTBOX_OPTION_INDICATOR_NAME = 'ListboxOptionIndicator';
+
+//
+// Context — only used to thread `value` through to `OptionIndicator` so
+// it knows whether to show the checkmark. Selection state itself lives
+// in `RowList`'s context (we delegate to it via composition).
+//
+
+type ListboxScopedProps<P> = P & { __listboxScope?: Scope };
+type ListboxOptionScopedProps<P> = P & { __listboxOptionScope?: Scope };
+
+const [createListboxContext, createListboxScope] = createContextScope(LISTBOX_NAME, [createRowListScope]);
+const [createListboxOptionContext, createListboxOptionScope] = createContextScope(LISTBOX_OPTION_NAME, [
+  createListboxScope,
+]);
+
+type ListboxOptionContextValue = {
+  value: string;
+  isSelected: boolean;
+};
+
+const [ListboxOptionProvider, useListboxOptionContext] =
+  createListboxOptionContext<ListboxOptionContextValue>(LISTBOX_OPTION_NAME);
+
+//
+// Root — composes `RowList.Root` + `RowList.Content`.
+//
+// Maps the public `value` / `onValueChange` API to RowList's
+// `selectedId` / `onSelectChange` so existing consumers don't change.
+//
+
+type ListboxRootProps = ThemedClassName<ComponentPropsWithRef<'ul'>> & {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  /** Reserved — autoFocus on mount. RowList's focus-on-entry covers the typical case. */
+  autoFocus?: boolean;
+};
+
+const ListboxRoot = forwardRef<HTMLUListElement, ListboxRootProps>(
+  (props: ListboxScopedProps<ListboxRootProps>, forwardedRef) => {
+    const {
+      __listboxScope: _scope,
+      children,
+      classNames,
+      value,
+      defaultValue,
+      onValueChange,
+      autoFocus: _autoFocus,
+      ...rootProps
+    } = props;
+
+    return (
+      <RowList.Root selectedId={value} defaultSelectedId={defaultValue} onSelectChange={onValueChange}>
+        <RowList.Content {...rootProps} classNames={mx('w-full', classNames)} ref={forwardedRef}>
+          {children}
+        </RowList.Content>
+      </RowList.Root>
+    );
+  },
+);
+
+ListboxRoot.displayName = LISTBOX_NAME;
+
+//
+// Option — composes `Row`. Adds the listbox-specific styling and
+// publishes `{ value, isSelected }` so `OptionIndicator` can render a
+// checkmark.
+//
+
+type ListboxOptionProps = ThemedClassName<ComponentPropsWithRef<'li'>> & {
+  value: string;
+};
+
+const ListboxOption = forwardRef<HTMLLIElement, ListboxOptionProps>(
+  (props: ListboxScopedProps<ListboxOptionProps>, forwardedRef) => {
+    const { __listboxScope, children, classNames, value, ...rootProps } = props;
+
+    // Selection state is read inside `ListboxOptionProviderHost` via
+    // the public `useRowListSelection` hook and republished on the
+    // listbox-option scope so `OptionIndicator` can render its
+    // checkmark synchronously.
+    return (
+      <Row
+        id={value}
+        {...rootProps}
+        classNames={mx('dx-focus-ring rounded-xs', commandItem, classNames)}
+        ref={forwardedRef}
+      >
+        <ListboxOptionProviderHost value={value}>{children}</ListboxOptionProviderHost>
+      </Row>
+    );
+  },
+);
+
+ListboxOption.displayName = LISTBOX_OPTION_NAME;
+
+// Reads selection state from RowList's context (via `useRowListSelection`)
+// and publishes it on the listbox-option scope so `OptionIndicator` can
+// render its checkmark. Tiny adapter — keeps Listbox's public option API
+// intact while delegating the actual state to RowList.
+const ListboxOptionProviderHost = ({
+  value,
+  children,
+}: ListboxScopedProps<{ value: string; children?: ReactNode }>) => {
+  const isSelected = useRowListSelection(value);
+  return (
+    <ListboxOptionProvider scope={undefined} value={value} isSelected={isSelected}>
+      {children}
+    </ListboxOptionProvider>
+  );
+};
+
+//
+// OptionLabel
+//
+
+const ListboxOptionLabel = forwardRef<HTMLDivElement, ThemedClassName<ComponentPropsWithRef<'div'>>>(
+  ({ children, classNames, ...rootProps }, forwardedRef) => {
+    return (
+      <span {...rootProps} className={mx('grow truncate', classNames)} ref={forwardedRef}>
+        {children}
+      </span>
+    );
+  },
+);
+
+ListboxOptionLabel.displayName = LISTBOX_OPTION_LABEL_NAME;
+
+//
+// OptionIndicator — checkmark for the selected option.
+//
+// Reads `isSelected` from the option context. The visual indicator is
+// also covered by `dx-selected` on the row, so the checkmark is purely
+// confirmatory.
+//
+
+type ListboxOptionIndicatorProps = Omit<IconProps, 'icon'> & Partial<Pick<IconProps, 'icon'>>;
+
+const ListboxOptionIndicator = forwardRef<SVGSVGElement, ListboxOptionIndicatorProps>(
+  (props: ListboxOptionScopedProps<ListboxOptionIndicatorProps>, forwardedRef) => {
+    const { __listboxOptionScope, classNames, ...rootProps } = props;
+    const { isSelected } = useListboxOptionContext(LISTBOX_OPTION_INDICATOR_NAME, __listboxOptionScope);
+
+    return (
+      <Icon
+        icon='ph--check--regular'
+        {...rootProps}
+        classNames={mx(!isSelected && 'invisible', classNames)}
+        ref={forwardedRef}
+      />
+    );
+  },
+);
+
+ListboxOptionIndicator.displayName = LISTBOX_OPTION_INDICATOR_NAME;
+
+//
+// Listbox
+//
+
+export const Listbox = {
+  Root: ListboxRoot,
+  Option: ListboxOption,
+  OptionLabel: ListboxOptionLabel,
+  OptionIndicator: ListboxOptionIndicator,
+};
+
+export { createListboxScope };
+
+export type { ListboxRootProps, ListboxOptionProps, ListboxScopedProps };

package/src/components/Listbox/index.ts

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

package/src/components/Picker/Picker.stories.tsx

@@ -0,0 +1,131 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// `Picker` stories — exercises the generic listbox-with-input compound
+// in isolation. The compound is search-agnostic; the `Filtering` story
+// shows how a caller wires in-memory filtering on top, and the
+// `WithDisabled` story demonstrates the registry's skip-disabled
+// behaviour during keyboard nav.
+//
+// For a search-themed wrapper with debounced query / auto-select-first /
+// fuzzy filtering, see `SearchList` in `@dxos/react-ui-search`.
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo, useState } from 'react';
+
+import { random } from '@dxos/random';
+import { Column, ScrollArea } from '@dxos/react-ui';
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { Picker } from './Picker';
+
+random.seed(1234);
+
+type StoryItem = { value: string; label: string };
+
+const allItems: StoryItem[] = Array.from({ length: 24 }, (_, i) => ({
+  value: `item-${i}`,
+  label: random.commerce.productName(),
+})).sort((a, b) => a.label.localeCompare(b.label));
+
+//
+// Single configurable story. Each variant exported below sets a
+// different combination of props — keeps the per-variant code to one
+// line at the bottom of the file. See `AUDIT.md` §11 corrections for
+// the convention.
+//
+
+type StoryArgs = {
+  /** Items to render. Defaults to the full 24-item catalog. */
+  items?: StoryItem[];
+  /** When true, the input is controlled and filters the rendered set. */
+  controlled?: boolean;
+  /** Indices into `items` that should render disabled. */
+  disabledIndices?: number[];
+};
+
+const DefaultStory = ({ items = allItems, controlled = false, disabledIndices = [] }: StoryArgs = {}) => {
+  const [picked, setPicked] = useState<string | undefined>();
+  const [query, setQuery] = useState('');
+
+  const visible = useMemo(
+    () =>
+      controlled
+        ? items
+            .map((item, originalIndex) => ({ item, originalIndex }))
+            .filter(({ item }) => item.label.toLowerCase().includes(query.toLowerCase()))
+        : items.map((item, originalIndex) => ({ item, originalIndex })),
+    [controlled, items, query],
+  );
+
+  return (
+    <Column.Root gutter='sm' classNames='w-[24rem] border border-separator rounded-md py-form-gap'>
+      <Picker.Root>
+        <Column.Center>
+          <Picker.Input
+            autoFocus
+            placeholder={controlled ? 'Filter…' : '↑/↓ to navigate, Enter to pick'}
+            {...(controlled && { value: query, onValueChange: setQuery })}
+          />
+        </Column.Center>
+        <ScrollArea.Root classNames='max-h-[20rem] py-form-gap' thin>
+          <ScrollArea.Viewport>
+            <ul role='listbox' className='flex flex-col'>
+              {visible.map(({ item, originalIndex }) => {
+                const disabled = disabledIndices.includes(originalIndex);
+                return (
+                  <Picker.Item
+                    key={item.value}
+                    value={item.value}
+                    disabled={disabled}
+                    onSelect={() => setPicked(item.value)}
+                  >
+                    {item.label}
+                    {disabled && ' (disabled)'}
+                  </Picker.Item>
+                );
+              })}
+              {controlled && visible.length === 0 && (
+                <li role='status' className='px-2 py-1 text-description italic'>
+                  No matches
+                </li>
+              )}
+            </ul>
+          </ScrollArea.Viewport>
+        </ScrollArea.Root>
+      </Picker.Root>
+      <Column.Center classNames='text-sm text-description'>
+        Picked: <span className='font-mono'>{picked ?? '—'}</span>
+      </Column.Center>
+    </Column.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-list/Picker',
+  render: (args) => <DefaultStory {...args} />,
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<StoryArgs>;
+
+export default meta;
+
+type Story = StoryObj<StoryArgs>;
+
+export const Default: Story = {};
+
+export const Filtering: Story = {
+  args: {
+    controlled: true,
+  },
+};
+
+export const WithDisabled: Story = {
+  args: {
+    items: allItems.slice(0, 8),
+    disabledIndices: [2, 5],
+  },
+};

package/src/components/Picker/Picker.tsx

@@ -0,0 +1,368 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// `Picker` — generic listbox-with-input compound implementing the
+// WAI-ARIA combobox keyboard pattern. Search / filtering live one layer
+// up in `@dxos/react-ui-search`.
+//
+// The two contexts (Input / Item) are split so items don't re-render on
+// every keystroke and the input doesn't re-render on every (un)register.
+
+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';
+
+type ItemData = {
+  element: HTMLElement;
+  disabled?: boolean;
+  onSelect?: () => void;
+};
+
+//
+// Root
+//
+
+type PickerRootProps = PropsWithChildren<{}>;
+
+const PickerRoot = ({ children }: PickerRootProps) => {
+  const [selectedValue, setSelectedValue] = useState<string | undefined>(undefined);
+  const itemsRef = useRef<Map<string, ItemData>>(new Map());
+  // Bumped on every (un)register to retrigger auto-select.
+  const [itemVersion, setItemVersion] = useState(0);
+
+  // Auto-select first non-disabled item when the current selection is
+  // 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 list of enabled item values.
+  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 values items subscribe to.
+  const itemContextValue = useMemo(
+    () => ({
+      selectedValue,
+      onSelectedValueChange: setSelectedValue,
+      registerItem,
+      unregisterItem,
+    }),
+    [selectedValue, registerItem, unregisterItem],
+  );
+
+  // Volatile values the input subscribes to (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
+//
+
+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],
+    );
+
+    // Only force-control when `value` is provided; otherwise leave the
+    // input uncontrolled so it accepts keystrokes without `onValueChange`.
+    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
+//
+
+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;
+
+    useEffect(() => {
+      const element = internalRef.current;
+      if (element) {
+        registerItem(value, element, onSelect, disabled);
+      }
+      return () => unregisterItem(value);
+    }, [value, onSelect, disabled, registerItem, unregisterItem]);
+
+    useEffect(() => {
+      if (isSelected && internalRef.current) {
+        internalRef.current.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+      }
+    }, [isSelected]);
+
+    const handleClick = useCallback(() => {
+      if (disabled) {
+        return;
+      }
+      onSelectedValueChange(value);
+      onSelect?.();
+    }, [disabled, value, onSelectedValueChange, onSelect]);
+
+    // Keep focus on `Picker.Input`: any `tabIndex` (incl. `-1`) would
+    // steal focus on click and break the input's arrow-key handler.
+    const handleMouseDown = useCallback((event: ReactMouseEvent<HTMLElement>) => {
+      event.preventDefault();
+    }, []);
+
+    const Comp: any = asChild ? Slot : 'div';
+
+    // Padding follows `--gutter` to align with sibling `Column.Center`
+    // content; falls back to `0.75rem` when not nested under `Column.Root`.
+    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}
+        // Browser focus stays on the input; highlight is via `aria-selected`.
+        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';
+
+export const Picker = {
+  Root: PickerRoot,
+  Input: PickerInput,
+  Item: PickerItem,
+};
+
+export type { PickerRootProps, PickerInputProps, PickerItemProps };
+
+export { usePickerInputContext, usePickerItemContext } from './context';