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

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