feat(ui): add ListBox and ListBoxItem components

Adds standalone `ListBox` and `ListBoxItem` components to `@backstage/ui`,
built on top of React Aria's ListBox primitives. Items support icons,
descriptions, and single or multiple selection modes.

Includes Storybook stories and docs-ui documentation page.

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
Made-with: Cursor

docs-ui/src/app/components/list-box/components.tsx

@@ -0,0 +1,150 @@
+'use client';
+
+import {
+  ListBox,
+  ListBoxItem,
+} from '../../../../../packages/ui/src/components/ListBox/ListBox';
+import { useState } from 'react';
+import type { Selection } from 'react-aria-components';
+import {
+  RiJavascriptLine,
+  RiReactjsLine,
+  RiRustLine,
+  RiTerminalLine,
+  RiCodeLine,
+} from '@remixicon/react';
+
+const items = [
+  { id: 'react', label: 'React' },
+  { id: 'typescript', label: 'TypeScript' },
+  { id: 'javascript', label: 'JavaScript' },
+  { id: 'rust', label: 'Rust' },
+  { id: 'go', label: 'Go' },
+];
+
+const itemsWithDescription = [
+  {
+    id: 'react',
+    label: 'React',
+    description: 'A JavaScript library for building user interfaces',
+  },
+  {
+    id: 'typescript',
+    label: 'TypeScript',
+    description: 'Typed superset of JavaScript',
+  },
+  {
+    id: 'javascript',
+    label: 'JavaScript',
+    description: 'The language of the web',
+  },
+  {
+    id: 'rust',
+    label: 'Rust',
+    description: 'Systems programming with memory safety',
+  },
+  {
+    id: 'go',
+    label: 'Go',
+    description: 'Simple, fast, and reliable',
+  },
+];
+
+const itemIcons: Record<string, React.ReactNode> = {
+  react: <RiReactjsLine />,
+  typescript: <RiCodeLine />,
+  javascript: <RiJavascriptLine />,
+  rust: <RiRustLine />,
+  go: <RiTerminalLine />,
+};
+
+export const Default = () => (
+  <ListBox aria-label="Programming languages" style={{ width: 280 }}>
+    {items.map(item => (
+      <ListBoxItem key={item.id} id={item.id}>
+        {item.label}
+      </ListBoxItem>
+    ))}
+  </ListBox>
+);
+
+export const WithIcons = () => (
+  <ListBox aria-label="Programming languages" style={{ width: 280 }}>
+    {items.map(item => (
+      <ListBoxItem key={item.id} id={item.id} icon={itemIcons[item.id]}>
+        {item.label}
+      </ListBoxItem>
+    ))}
+  </ListBox>
+);
+
+export const WithDescription = () => (
+  <ListBox aria-label="Programming languages" style={{ width: 340 }}>
+    {itemsWithDescription.map(item => (
+      <ListBoxItem
+        key={item.id}
+        id={item.id}
+        icon={itemIcons[item.id]}
+        description={item.description}
+      >
+        {item.label}
+      </ListBoxItem>
+    ))}
+  </ListBox>
+);
+
+export const SelectionModeSingle = () => {
+  const [selected, setSelected] = useState<Selection>(new Set(['react']));
+
+  return (
+    <ListBox
+      aria-label="Programming languages"
+      style={{ width: 280 }}
+      selectionMode="single"
+      selectedKeys={selected}
+      onSelectionChange={setSelected}
+    >
+      {items.map(item => (
+        <ListBoxItem key={item.id} id={item.id}>
+          {item.label}
+        </ListBoxItem>
+      ))}
+    </ListBox>
+  );
+};
+
+export const SelectionModeMultiple = () => {
+  const [selected, setSelected] = useState<Selection>(
+    new Set(['react', 'typescript']),
+  );
+
+  return (
+    <ListBox
+      aria-label="Programming languages"
+      style={{ width: 280 }}
+      selectionMode="multiple"
+      selectedKeys={selected}
+      onSelectionChange={setSelected}
+    >
+      {items.map(item => (
+        <ListBoxItem key={item.id} id={item.id}>
+          {item.label}
+        </ListBoxItem>
+      ))}
+    </ListBox>
+  );
+};
+
+export const Disabled = () => (
+  <ListBox
+    aria-label="Programming languages"
+    style={{ width: 280 }}
+    disabledKeys={['typescript', 'rust']}
+  >
+    {items.map(item => (
+      <ListBoxItem key={item.id} id={item.id}>
+        {item.label}
+      </ListBoxItem>
+    ))}
+  </ListBox>
+);

docs-ui/src/app/components/list-box/page.mdx

@@ -0,0 +1,85 @@
+import { PropsTable } from '@/components/PropsTable';
+import { Snippet } from '@/components/Snippet';
+import { CodeBlock } from '@/components/CodeBlock';
+import { ReactAriaLink } from '@/components/ReactAriaLink';
+import {
+  Default,
+  WithIcons,
+  WithDescription,
+  SelectionModeSingle,
+  SelectionModeMultiple,
+  Disabled,
+} from './components';
+import { listBoxPropDefs, listBoxItemPropDefs } from './props-definition';
+import {
+  usage,
+  preview,
+  withIcons,
+  withDescription,
+  selectionModeSingle,
+  selectionModeMultiple,
+  disabled,
+} from './snippets';
+import { PageTitle } from '@/components/PageTitle';
+import { Theming } from '@/components/Theming';
+import { ListBoxDefinition, ListBoxItemDefinition } from '../../../utils/definitions';
+import { ChangelogComponent } from '@/components/ChangelogComponent';
+
+export const reactAriaUrls = {
+  listBox: 'https://react-aria.adobe.com/ListBox',
+};
+
+<PageTitle
+  title="ListBox"
+  description="A list of options that allows users to select one or more items."
+/>
+
+<Snippet align="center" py={4} preview={<Default />} code={preview} />
+
+## Usage
+
+<CodeBlock code={usage} />
+
+## API reference
+
+### ListBox
+
+Container for a list of selectable options.
+
+<PropsTable data={listBoxPropDefs} />
+
+<ReactAriaLink component="ListBox" href={reactAriaUrls.listBox} />
+
+### ListBoxItem
+
+Individual item within a ListBox.
+
+<PropsTable data={listBoxItemPropDefs} />
+
+<ReactAriaLink component="ListBoxItem" href={reactAriaUrls.listBox} />
+
+## Examples
+
+### With icons
+
+<Snippet align="center" py={4} open preview={<WithIcons />} code={withIcons} />
+
+### With description
+
+<Snippet align="center" py={4} open preview={<WithDescription />} code={withDescription} />
+
+### Single selection
+
+<Snippet align="center" py={4} open preview={<SelectionModeSingle />} code={selectionModeSingle} />
+
+### Multiple selection
+
+<Snippet align="center" py={4} open preview={<SelectionModeMultiple />} code={selectionModeMultiple} />
+
+### Disabled items
+
+<Snippet align="center" py={4} open preview={<Disabled />} code={disabled} />
+
+<Theming definition={ListBoxDefinition} />
+
+<ChangelogComponent component="list-box" />

docs-ui/src/app/components/list-box/props-definition.tsx

@@ -0,0 +1,72 @@
+import {
+  classNamePropDefs,
+  childrenPropDefs,
+  type PropDef,
+} from '@/utils/propDefs';
+
+export const listBoxPropDefs: Record<string, PropDef> = {
+  items: {
+    type: 'enum',
+    values: ['Iterable<T>'],
+    description: 'Item objects in the collection.',
+  },
+  renderEmptyState: {
+    type: 'enum',
+    values: ['() => ReactNode'],
+    description: 'Content to display when the collection is empty.',
+  },
+  selectionMode: {
+    type: 'enum',
+    values: ['none', 'single', 'multiple'],
+    description: 'The type of selection allowed.',
+  },
+  selectedKeys: {
+    type: 'enum',
+    values: ['all', 'Iterable<Key>'],
+    description: 'The currently selected keys (controlled).',
+  },
+  defaultSelectedKeys: {
+    type: 'enum',
+    values: ['all', 'Iterable<Key>'],
+    description: 'The initial selected keys (uncontrolled).',
+  },
+  disabledKeys: {
+    type: 'enum',
+    values: ['Iterable<Key>'],
+    description: 'Keys of items that should be disabled.',
+  },
+  onSelectionChange: {
+    type: 'enum',
+    values: ['(keys: Selection) => void'],
+    description: 'Handler called when the selection changes.',
+  },
+  ...childrenPropDefs,
+  ...classNamePropDefs,
+};
+
+export const listBoxItemPropDefs: Record<string, PropDef> = {
+  id: {
+    type: 'string',
+    description: 'Unique identifier for the item.',
+  },
+  textValue: {
+    type: 'string',
+    description:
+      'Text value for accessibility. Derived from children if string.',
+  },
+  icon: {
+    type: 'enum',
+    values: ['ReactNode'],
+    description: 'Icon displayed before the item label.',
+  },
+  description: {
+    type: 'string',
+    description: 'Secondary description text displayed below the label.',
+  },
+  isDisabled: {
+    type: 'boolean',
+    description: 'Whether the item is disabled.',
+  },
+  ...childrenPropDefs,
+  ...classNamePropDefs,
+};

docs-ui/src/app/components/list-box/snippets.ts

@@ -0,0 +1,75 @@
+export const usage = `import { ListBox, ListBoxItem } from '@backstage/ui';
+
+<ListBox aria-label="Programming languages">
+  <ListBoxItem id="react">React</ListBoxItem>
+  <ListBoxItem id="typescript">TypeScript</ListBoxItem>
+  <ListBoxItem id="javascript">JavaScript</ListBoxItem>
+</ListBox>`;
+
+export const preview = `<ListBox aria-label="Programming languages">
+  <ListBoxItem id="react">React</ListBoxItem>
+  <ListBoxItem id="typescript">TypeScript</ListBoxItem>
+  <ListBoxItem id="javascript">JavaScript</ListBoxItem>
+  <ListBoxItem id="rust">Rust</ListBoxItem>
+  <ListBoxItem id="go">Go</ListBoxItem>
+</ListBox>`;
+
+export const withIcons = `<ListBox aria-label="Programming languages">
+  <ListBoxItem id="react" icon={<RiReactjsLine />}>React</ListBoxItem>
+  <ListBoxItem id="typescript" icon={<RiCodeLine />}>TypeScript</ListBoxItem>
+  <ListBoxItem id="javascript" icon={<RiJavascriptLine />}>JavaScript</ListBoxItem>
+</ListBox>`;
+
+export const withDescription = `<ListBox aria-label="Programming languages">
+  <ListBoxItem
+    id="react"
+    icon={<RiReactjsLine />}
+    description="A JavaScript library for building user interfaces"
+  >
+    React
+  </ListBoxItem>
+  <ListBoxItem
+    id="typescript"
+    icon={<RiCodeLine />}
+    description="Typed superset of JavaScript"
+  >
+    TypeScript
+  </ListBoxItem>
+</ListBox>`;
+
+export const selectionModeSingle = `const [selected, setSelected] = useState(new Set(['react']));
+
+<ListBox
+  aria-label="Programming languages"
+  selectionMode="single"
+  selectedKeys={selected}
+  onSelectionChange={setSelected}
+>
+  <ListBoxItem id="react">React</ListBoxItem>
+  <ListBoxItem id="typescript">TypeScript</ListBoxItem>
+  <ListBoxItem id="javascript">JavaScript</ListBoxItem>
+</ListBox>`;
+
+export const selectionModeMultiple = `const [selected, setSelected] = useState(new Set(['react', 'typescript']));
+
+<ListBox
+  aria-label="Programming languages"
+  selectionMode="multiple"
+  selectedKeys={selected}
+  onSelectionChange={setSelected}
+>
+  <ListBoxItem id="react">React</ListBoxItem>
+  <ListBoxItem id="typescript">TypeScript</ListBoxItem>
+  <ListBoxItem id="javascript">JavaScript</ListBoxItem>
+</ListBox>`;
+
+export const disabled = `<ListBox
+  aria-label="Programming languages"
+  disabledKeys={['typescript', 'rust']}
+>
+  <ListBoxItem id="react">React</ListBoxItem>
+  <ListBoxItem id="typescript">TypeScript</ListBoxItem>
+  <ListBoxItem id="javascript">JavaScript</ListBoxItem>
+  <ListBoxItem id="rust">Rust</ListBoxItem>
+  <ListBoxItem id="go">Go</ListBoxItem>
+</ListBox>`;

docs-ui/src/utils/data.ts

@@ -69,6 +69,10 @@ export const components: Page[] = [
     title: 'Link',
     slug: 'link',
   },
+  {
+    title: 'ListBox',
+    slug: 'list-box',
+  },
   {
     title: 'Menu',
     slug: 'menu',