@dxos/react-ui-list 0.8.4-main.c85a9c8dae → 0.8.4-main.cb12b3f963

package/src/components/List/ListItem.tsx

@@ -2,21 +2,22 @@
 // Copyright 2024 DXOS.org
 //
 
-import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
-import { draggable, dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
-import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
 import {
   type Edge,
   attachClosestEdge,
   extractClosestEdge,
 } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge';
+import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
+import { draggable, dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
 import { createContext } from '@radix-ui/react-context';
+import { Slot } from '@radix-ui/react-slot';
 import React, {
   type ComponentProps,
   type HTMLAttributes,
-  type MutableRefObject,
   type PropsWithChildren,
   type ReactNode,
+  RefObject,
   useEffect,
   useRef,
   useState,
@@ -46,22 +47,22 @@ export type ItemDragState =
       container: HTMLElement;
     }
   | {
-      type: 'w-dragging';
+      type: 'is-dragging';
     }
   | {
-      type: 'w-dragging-over';
+      type: 'is-dragging-over';
       closestEdge: Edge | null;
     };
 
 export const idle: ItemDragState = { type: 'idle' };
 
 const stateStyles: { [Key in ItemDragState['type']]?: HTMLAttributes<HTMLDivElement>['className'] } = {
-  'w-dragging': 'opacity-50',
+  'is-dragging': 'opacity-50',
 };
 
 type ListItemContext<T extends ListItemRecord> = {
   item: T;
-  dragHandleRef: MutableRefObject<HTMLElement | null>;
+  dragHandleRef: RefObject<HTMLButtonElement | null>;
 };
 
 /**
@@ -80,6 +81,8 @@ export type ListItemProps<T extends ListItemRecord> = ThemedClassName<
   PropsWithChildren<
     {
       item: T;
+      asChild?: boolean;
+      selected?: boolean;
     } & HTMLAttributes<HTMLDivElement>
   >
 >;
@@ -87,14 +90,22 @@ export type ListItemProps<T extends ListItemRecord> = ThemedClassName<
 /**
  * Draggable list item.
  */
-export const ListItem = <T extends ListItemRecord>({ children, classNames, item, ...props }: ListItemProps<T>) => {
+export const ListItem = <T extends ListItemRecord>({
+  children,
+  classNames,
+  item,
+  asChild,
+  selected,
+  ...props
+}: ListItemProps<T>) => {
+  const Comp = asChild ? Slot : 'div';
   const { isItem, readonly, dragPreview, setState: setRootState } = useListContext(LIST_ITEM_NAME);
-  const ref = useRef<HTMLDivElement | null>(null);
-  const dragHandleRef = useRef<HTMLElement | null>(null);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const dragHandleRef = useRef<HTMLButtonElement | null>(null);
   const [state, setState] = useState<ItemDragState>(idle);
 
   useEffect(() => {
-    const element = ref.current;
+    const element = rootRef.current;
     invariant(element);
     return combine(
       //
@@ -124,8 +135,8 @@ export const ListItem = <T extends ListItemRecord>({ children, classNames, item,
             }
           : undefined,
         onDragStart: () => {
-          setState({ type: 'w-dragging' });
-          setRootState({ type: 'w-dragging', item });
+          setState({ type: 'is-dragging' });
+          setRootState({ type: 'is-dragging', item });
         },
         onDrop: () => {
           setState(idle);
@@ -147,7 +158,7 @@ export const ListItem = <T extends ListItemRecord>({ children, classNames, item,
         getIsSticky: () => true,
         onDragEnter: ({ self }) => {
           const closestEdge = extractClosestEdge(self.data);
-          setState({ type: 'w-dragging-over', closestEdge });
+          setState({ type: 'is-dragging-over', closestEdge });
         },
         onDragLeave: () => {
           setState(idle);
@@ -155,10 +166,10 @@ export const ListItem = <T extends ListItemRecord>({ children, classNames, item,
         onDrag: ({ self }) => {
           const closestEdge = extractClosestEdge(self.data);
           setState((current) => {
-            if (current.type === 'w-dragging-over' && current.closestEdge === closestEdge) {
+            if (current.type === 'is-dragging-over' && current.closestEdge === closestEdge) {
               return current;
             }
-            return { type: 'w-dragging-over', closestEdge };
+            return { type: 'is-dragging-over', closestEdge };
           });
         },
         onDrop: () => {
@@ -170,12 +181,18 @@ export const ListItem = <T extends ListItemRecord>({ children, classNames, item,
 
   return (
     <ListItemProvider item={item} dragHandleRef={dragHandleRef}>
-      <div ref={ref} role='listitem' className={mx('flex relative', classNames, stateStyles[state.type])} {...props}>
+      <Comp
+        {...props}
+        role='listitem'
+        aria-selected={selected}
+        className={mx('relative p-1 dx-selected dx-hover', classNames, stateStyles[state.type])}
+        ref={rootRef}
+      >
         {children}
-        {state.type === 'w-dragging-over' && state.closestEdge && (
-          <NaturalListItem.DropIndicator edge={state.closestEdge} />
-        )}
-      </div>
+      </Comp>
+      {state.type === 'is-dragging-over' && state.closestEdge && (
+        <NaturalListItem.DropIndicator edge={state.closestEdge} />
+      )}
     </ListItemProvider>
   );
 };
@@ -184,47 +201,48 @@ export const ListItem = <T extends ListItemRecord>({ children, classNames, item,
 // List item components
 //
 
-export const ListItemDeleteButton = ({
+export const ListItemIconButton = ({
   autoHide = true,
+  iconOnly = true,
+  variant = 'ghost',
   classNames,
   disabled,
-  icon = 'ph--x--regular',
-  label,
   ...props
-}: Partial<Pick<IconButtonProps, 'icon'>> &
-  Omit<IconButtonProps, 'icon' | 'label'> & { autoHide?: boolean; label?: string }) => {
-  const { state } = useListContext('DELETE_BUTTON');
+}: IconButtonProps & { autoHide?: boolean }) => {
+  const { state } = useListContext('ITEM_BUTTON');
   const isDisabled = state.type !== 'idle' || disabled;
-  const { t } = useTranslation(osTranslations);
   return (
     <IconButton
-      iconOnly
-      variant='ghost'
       {...props}
-      icon={icon}
       disabled={isDisabled}
-      label={label ?? t('delete label')}
+      iconOnly={iconOnly}
+      variant={variant}
       classNames={[classNames, autoHide && disabled && 'hidden']}
     />
   );
 };
 
-export const ListItemButton = ({
+// TODO(burdon): Generalize to action button.
+export const ListItemDeleteButton = ({
   autoHide = true,
-  iconOnly = true,
-  variant = 'ghost',
   classNames,
   disabled,
+  icon = 'ph--x--regular',
+  label,
   ...props
-}: IconButtonProps & { autoHide?: boolean }) => {
-  const { state } = useListContext('ITEM_BUTTON');
+}: Partial<Pick<IconButtonProps, 'icon'>> &
+  Omit<IconButtonProps, 'icon' | 'label'> & { autoHide?: boolean; label?: string }) => {
+  const { state } = useListContext('DELETE_BUTTON');
   const isDisabled = state.type !== 'idle' || disabled;
+  const { t } = useTranslation(osTranslations);
   return (
     <IconButton
       {...props}
+      variant='ghost'
       disabled={isDisabled}
-      iconOnly={iconOnly}
-      variant={variant}
+      icon={icon}
+      iconOnly
+      label={label ?? t('delete.label')}
       classNames={[classNames, autoHide && disabled && 'hidden']}
     />
   );
@@ -235,12 +253,12 @@ export const ListItemDragHandle = ({ disabled }: Pick<IconButtonProps, 'disabled
   const { t } = useTranslation(osTranslations);
   return (
     <IconButton
-      iconOnly
       variant='ghost'
-      label={t('drag handle label')}
-      ref={dragHandleRef as any}
-      icon='ph--dots-six-vertical--regular'
       disabled={disabled}
+      icon='ph--dots-six-vertical--regular'
+      iconOnly
+      label={t('drag-handle.label')}
+      ref={dragHandleRef}
     />
   );
 };
@@ -255,7 +273,9 @@ export const ListItemDragPreview = <T extends ListItemRecord>({
 };
 
 export const ListItemWrapper = ({ classNames, children }: ThemedClassName<PropsWithChildren>) => (
-  <div className={mx('flex w-full gap-2', classNames)}>{children}</div>
+  <div role='none' className={mx('flex w-full gap-2', classNames)}>
+    {children}
+  </div>
 );
 
 export const ListItemTitle = ({
@@ -263,7 +283,7 @@ export const ListItemTitle = ({
   children,
   ...props
 }: ThemedClassName<PropsWithChildren<ComponentProps<'div'>>>) => (
-  <div className={mx('flex grow items-center truncate', classNames)} {...props}>
+  <div role='none' className={mx('flex grow items-center truncate', classNames)} {...props}>
     {children}
   </div>
 );

package/src/components/List/ListRoot.tsx

@@ -2,9 +2,9 @@
 // Copyright 2024 DXOS.org
 //
 
-import { monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
 import { 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 { monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
 import { createContext } from '@radix-ui/react-context';
 import React, { type ReactNode, useCallback, useEffect, useState } from 'react';
 

package/src/components/List/testing.ts

@@ -5,7 +5,7 @@
 import * as Schema from 'effect/Schema';
 
 import { Obj } from '@dxos/echo';
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 
 export const TestItemSchema = Schema.Struct({
   id: Obj.ID,
@@ -21,10 +21,10 @@ export const TestList = Schema.Struct({
 export type TestList = Schema.Schema.Type<typeof TestList>;
 
 export const createList = (n = 10): TestList => ({
-  items: faker.helpers.multiple(
+  items: random.helpers.multiple(
     () => ({
-      id: faker.string.uuid(),
-      name: faker.commerce.productName(),
+      id: random.string.uuid(),
+      name: random.commerce.productName(),
     }),
     { count: n },
   ),

package/src/components/Listbox/Listbox.stories.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+
+import { random } from '@dxos/random';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { Listbox } from './Listbox';
+
+random.seed(1234);
+
+type StoryItem = { value: string; label: string };
+
+const options: StoryItem[] = random.helpers.multiple(
+  () => ({ value: random.string.uuid(), label: random.commerce.productName() }) satisfies StoryItem,
+  { count: 16 },
+);
+
+const DefaultStory = () => {
+  const [selectedValue, setSelectedValue] = useState<string>();
+
+  return (
+    <Listbox.Root value={selectedValue} onValueChange={setSelectedValue}>
+      {options.map((option) => (
+        <Listbox.Option key={option.value} value={option.value}>
+          <Listbox.OptionLabel>{option.label}</Listbox.OptionLabel>
+          <Listbox.OptionIndicator />
+        </Listbox.Option>
+      ))}
+    </Listbox.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-list/Listbox',
+  component: Listbox.Root,
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'p-2' })],
+} satisfies Meta<typeof Listbox.Root>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

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],
+  },
+};