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

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';

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 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 /> };