@dxos/react-list 0.8.4-main.dedc0f3 → 0.8.4-main.dfabb4ec29

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@dxos/react-list",
-  "version": "0.8.4-main.dedc0f3",
+  "version": "0.8.4-main.dfabb4ec29",
   "description": "List primitive components for React.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -17,34 +21,29 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@preact-signals/safe-react": "^0.9.0",
     "@radix-ui/react-collapsible": "1.1.3",
     "@radix-ui/react-context": "1.1.1",
     "@radix-ui/react-primitive": "2.0.2",
     "@radix-ui/react-slot": "1.1.2",
     "@radix-ui/react-use-controllable-state": "1.1.0",
-    "lodash.omit": "^4.5.0",
-    "@dxos/react-hooks": "0.8.4-main.dedc0f3"
+    "@dxos/react-hooks": "0.8.4-main.dfabb4ec29"
   },
   "devDependencies": {
     "@radix-ui/react-checkbox": "1.1.4",
-    "@types/lodash.omit": "^4.5.7",
-    "@types/react": "~18.2.0",
-    "@types/react-dom": "~18.2.0",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0"
+    "@storybook/react-vite": "^10.3.6",
+    "@types/react": "~19.2.7",
+    "@types/react-dom": "~19.2.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3"
   },
   "peerDependencies": {
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0"
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3"
   },
   "publishConfig": {
     "access": "public"

package/src/List.stories.tsx

@@ -0,0 +1,149 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Stories for the elemental `@dxos/react-list` primitive — ARIA + structure
+// only. These show the default-styling-free behavior of `List` / `ListItem`
+// in isolation. For the styled, ARIA-correct, keyboard-navigable layer most
+// app code reaches for, see `@dxos/react-ui-list`'s `RowList` story.
+
+import { type Decorator, type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+
+import { List } from './List';
+import { ListItem, ListItemCollapsibleContent, ListItemHeading, ListItemOpenTrigger } from './ListItem';
+
+type Item = { id: string; label: string };
+
+const items: Item[] = Array.from({ length: 5 }, (_, i) => ({
+  id: `item-${i}`,
+  label: `Item ${i + 1}`,
+}));
+
+//
+// Static unordered list — no selection.
+//
+
+const StaticStory = () => (
+  <List variant='unordered' className='dx-container border border-separator p-2'>
+    {items.map((item) => (
+      <ListItem key={item.id} className='py-1'>
+        <ListItemHeading>{item.label}</ListItemHeading>
+      </ListItem>
+    ))}
+  </List>
+);
+
+//
+// Single-select listbox. Pairs `aria-selected` (set by the primitive when
+// `selectable={true}`) with the canonical `dx-selected` / `dx-hover`
+// utilities to demonstrate the ARIA ↔ dx-* grammar in its rawest form.
+//
+
+const SingleSelectStory = () => {
+  const [selected, setSelected] = useState<string>(items[0].id);
+  return (
+    <List
+      variant='unordered'
+      selectable
+      aria-label='Single-select example'
+      className='dx-container border border-separator'
+    >
+      {items.map((item) => (
+        <ListItem
+          key={item.id}
+          selected={item.id === selected}
+          onClick={() => setSelected(item.id)}
+          className='dx-hover dx-selected px-3 py-2 cursor-pointer outline-none'
+        >
+          <ListItemHeading>{item.label}</ListItemHeading>
+        </ListItem>
+      ))}
+    </List>
+  );
+};
+
+//
+// Multi-select listbox. `multiSelectable` adds `aria-multiselectable="true"`
+// on the listbox itself; selection state is per-item.
+//
+
+const MultiSelectStory = () => {
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set([items[1].id]));
+  const toggle = (id: string) => {
+    setSelectedIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      return next;
+    });
+  };
+  return (
+    <List
+      variant='unordered'
+      selectable
+      multiSelectable
+      aria-label='Multi-select example'
+      className='dx-container border border-separator'
+    >
+      {items.map((item) => (
+        <ListItem
+          key={item.id}
+          selected={selectedIds.has(item.id)}
+          onClick={() => toggle(item.id)}
+          className='dx-hover dx-selected px-3 py-2 cursor-pointer outline-none'
+        >
+          <ListItemHeading>{item.label}</ListItemHeading>
+        </ListItem>
+      ))}
+    </List>
+  );
+};
+
+//
+// Collapsible item — opens / closes a Radix `Collapsible`-backed body.
+// Useful for accordion-style headings without reaching for the full
+// `react-ui-list` `Accordion` component.
+//
+
+const CollapsibleStory = () => (
+  <List variant='unordered' className='dx-container border border-separator divide-y divide-separator'>
+    {items.slice(0, 3).map((item) => (
+      <ListItem key={item.id} collapsible defaultOpen={item.id === items[0].id}>
+        <ListItemOpenTrigger asChild>
+          <ListItemHeading className='cursor-pointer px-3 py-2 select-none'>{item.label}</ListItemHeading>
+        </ListItemOpenTrigger>
+        <ListItemCollapsibleContent>
+          <div className='px-3 pb-2 text-description text-sm'>Details for {item.label}.</div>
+        </ListItemCollapsibleContent>
+      </ListItem>
+    ))}
+  </List>
+);
+
+// Inline column decorator — `react-list` deliberately doesn't depend on
+// `@dxos/react-ui` (a `withTheme/withLayout` import would create a cycle
+// since `react-ui` already depends on this primitive). Storybook's global
+// `withThemeByClassName` already applies the theme class at the root.
+const withColumn: Decorator = (Story) => (
+  <div className='flex flex-col gap-4 p-4 h-full max-w-md'>
+    <Story />
+  </div>
+);
+
+const meta = {
+  title: 'ui/react-list/List',
+  decorators: [withColumn],
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Static: Story = { render: StaticStory };
+export const SingleSelect: Story = { render: SingleSelectStory };
+export const MultiSelect: Story = { render: MultiSelectStory };
+export const Collapsible: Story = { render: CollapsibleStory };

package/src/List.tsx

@@ -2,12 +2,36 @@
 // Copyright 2023 DXOS.org
 //
 
+// Elemental list / listbox primitive.
+//
+// This is the ARIA-only foundation of the DXOS list stack. It renders a
+// semantically-correct `<ol>` / `<ul>` (or, when `selectable={true}`, a
+// `role="listbox"` element with `role="option"` children carrying
+// `aria-selected`). It applies no styling, no keyboard navigation, and
+// no `dx-*` utility classes — those are layered above in
+// `@dxos/react-ui-list`.
+//
+// Layering:
+//   - `@dxos/react-list`      — this package; ARIA + structure only.
+//   - `@dxos/react-ui-list`   — adds `dx-*` styling, keyboard nav, and
+//                               opinionated `RowList`/`CardList` containers.
+//   - `@dxos/react-ui-mosaic` — virtualized / draggable / card-board
+//                               layouts; composes the above where useful.
+//
+// Most app code should reach for `@dxos/react-ui-list`. Use this primitive
+// directly only when building a *new* selectable surface that needs full
+// control over styling and keyboard handling (e.g. a custom Combobox).
+//
+// See:
+//   - `packages/ui/ui-theme/src/css/components/selected.md` for the
+//     `aria-selected` ↔ `dx-selected` pairing rules.
+//   - `packages/ui/react-ui-list/AUDIT.md` for why this layering exists.
+//   - https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role
+
 import { type Scope, createContextScope } from '@radix-ui/react-context';
 import { Primitive } from '@radix-ui/react-primitive';
 import React, { type ComponentPropsWithRef, forwardRef } from 'react';
 
-// TODO(thure): A lot of the accessible affordances for this kind of thing need to be implemented per https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role
-
 const LIST_NAME = 'List';
 
 type ListScopedProps<P> = P & { __listScope?: Scope };
@@ -17,7 +41,19 @@ type ListVariant = 'ordered' | 'unordered';
 type ListItemSizes = 'one' | 'many';
 
 type ListProps = ComponentPropsWithRef<typeof Primitive.ol> & {
+  /**
+   * If true, render as `role="listbox"` and let `ListItem` children become
+   * `role="option"` + `aria-selected`. If false (default) the list is a
+   * plain `<ol>` / `<ul>` with no selection semantics — pick this for
+   * static lists.
+   */
   selectable?: boolean;
+  /**
+   * If true, the listbox advertises multi-select via
+   * `aria-multiselectable="true"`. Defaults to false (single-select).
+   * Has no effect unless `selectable` is also true.
+   */
+  multiSelectable?: boolean;
   variant?: ListVariant;
   itemSizes?: ListItemSizes;
 };
@@ -33,10 +69,28 @@ type ListContextValue = {
 const [ListProvider, useListContext] = createListContext<ListContextValue>(LIST_NAME);
 
 const List = forwardRef<HTMLOListElement, ListProps>((props: ListScopedProps<ListProps>, forwardedRef) => {
-  const { __listScope, variant = 'ordered', selectable = false, itemSizes, children, ...rootProps } = props;
+  const {
+    __listScope,
+    variant = 'ordered',
+    selectable = false,
+    multiSelectable = false,
+    itemSizes,
+    children,
+    ...rootProps
+  } = props;
   const ListRoot = variant === 'ordered' ? Primitive.ol : Primitive.ul;
   return (
-    <ListRoot {...(selectable && { role: 'listbox', 'aria-multiselectable': true })} {...rootProps} ref={forwardedRef}>
+    <ListRoot
+      // `aria-multiselectable` is only meaningful on `role="listbox"`,
+      // and even there is omitted in the single-select default to keep
+      // assistive tech announcements concise.
+      {...(selectable && {
+        role: 'listbox',
+        ...(multiSelectable && { 'aria-multiselectable': true as const }),
+      })}
+      {...rootProps}
+      ref={forwardedRef}
+    >
       <ListProvider
         {...{
           scope: __listScope,

package/src/ListItem.tsx

@@ -13,7 +13,7 @@ import React, {
   type ComponentProps,
   type ComponentPropsWithoutRef,
   type Dispatch,
-  type ElementRef,
+  type ComponentRef,
   type ForwardRefExoticComponent,
   type RefAttributes,
   type SetStateAction,
@@ -44,7 +44,7 @@ type ListItemProps = Omit<ListItemData, 'id'> & { collapsible?: boolean } & RefA
     defaultSelected?: CheckboxProps['defaultChecked'];
   };
 
-type ListItemElement = ElementRef<'li'>;
+type ListItemElement = ComponentRef<'li'>;
 
 const [createListItemContext, createListItemScope] = createContextScope(LIST_ITEM_NAME, []);
 
@@ -65,11 +65,11 @@ type ListItemHeadingProps = ListItemScopedProps<Omit<ComponentPropsWithoutRef<'p
 const ListItemHeading = forwardRef<HTMLDivElement, ListItemHeadingProps>(
   ({ children, asChild, __listItemScope, ...props }, forwardedRef) => {
     const { headingId } = useListItemContext(LIST_ITEM_NAME, __listItemScope);
-    const Root = asChild ? Slot : Primitive.div;
+    const Comp = asChild ? Slot : Primitive.div;
     return (
-      <Root {...props} id={headingId} ref={forwardedRef}>
+      <Comp {...props} id={headingId} ref={forwardedRef}>
         {children}
-      </Root>
+      </Comp>
     );
   },
 );