Move to GridList

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

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

@@ -1,186 +0,0 @@
-'use client';
-
-import {
-  ListBox,
-  ListBoxItem,
-} from '../../../../../packages/ui/src/components/ListBox/ListBox';
-import { MenuItem } from '../../../../../packages/ui/src/components/Menu/Menu';
-import {
-  TagGroup,
-  Tag,
-} from '../../../../../packages/ui/src/components/TagGroup/TagGroup';
-import { useState } from 'react';
-import type { Selection } from 'react-aria-components';
-import {
-  RiJavascriptLine,
-  RiReactjsLine,
-  RiShipLine,
-  RiTerminalLine,
-  RiCodeLine,
-  RiDeleteBinLine,
-  RiEdit2Line,
-  RiShareBoxLine,
-} from '@remixicon/react';
-
-const itemTags: Record<string, string[]> = {
-  react: ['frontend', 'ui'],
-  typescript: ['typed', 'js'],
-  javascript: ['web'],
-  rust: ['systems', 'fast'],
-  go: ['backend'],
-};
-
-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: <RiShipLine />,
-  go: <RiTerminalLine />,
-};
-
-export const Default = () => (
-  <ListBox aria-label="Programming languages" style={{ width: 380 }}>
-    {items.map(item => (
-      <ListBoxItem
-        key={item.id}
-        id={item.id}
-        icon={itemIcons[item.id]}
-        menuItems={
-          <>
-            <MenuItem iconStart={<RiEdit2Line />}>Edit</MenuItem>
-            <MenuItem iconStart={<RiShareBoxLine />}>Share</MenuItem>
-            <MenuItem iconStart={<RiDeleteBinLine />} color="danger">
-              Delete
-            </MenuItem>
-          </>
-        }
-        customActions={
-          <TagGroup aria-label={`Tags for ${item.label}`}>
-            {itemTags[item.id].map(tag => (
-              <Tag key={tag}>{tag}</Tag>
-            ))}
-          </TagGroup>
-        }
-      >
-        {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/snippets.ts

@@ -1,75 +0,0 @@
-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/app/components/list/components.tsx

@@ -0,0 +1,159 @@
+'use client';
+
+import {
+  List,
+  ListRow,
+} from '../../../../../packages/ui/src/components/List/List';
+import { MenuItem } from '../../../../../packages/ui/src/components/Menu/Menu';
+import {
+  TagGroup,
+  Tag,
+} from '../../../../../packages/ui/src/components/TagGroup/TagGroup';
+import { useState } from 'react';
+import type { Selection } from 'react-aria-components';
+import {
+  RiJavascriptLine,
+  RiReactjsLine,
+  RiShipLine,
+  RiTerminalLine,
+  RiCodeLine,
+  RiDeleteBinLine,
+  RiEdit2Line,
+  RiShareBoxLine,
+} from '@remixicon/react';
+
+const items = [
+  {
+    id: 'react',
+    label: 'React',
+    description: 'A JavaScript library for building user interfaces',
+    icon: <RiReactjsLine />,
+    tags: ['frontend', 'ui'],
+  },
+  {
+    id: 'typescript',
+    label: 'TypeScript',
+    description: 'Typed superset of JavaScript',
+    icon: <RiCodeLine />,
+    tags: ['typed', 'js'],
+  },
+  {
+    id: 'javascript',
+    label: 'JavaScript',
+    description: 'The language of the web',
+    icon: <RiJavascriptLine />,
+    tags: ['web'],
+  },
+  {
+    id: 'rust',
+    label: 'Rust',
+    description: 'Systems programming with memory safety',
+    icon: <RiShipLine />,
+    tags: ['systems', 'fast'],
+  },
+  {
+    id: 'go',
+    label: 'Go',
+    description: 'Simple, fast, and reliable',
+    icon: <RiTerminalLine />,
+    tags: ['backend'],
+  },
+];
+
+const menuItems = (
+  <>
+    <MenuItem iconStart={<RiEdit2Line />}>Edit</MenuItem>
+    <MenuItem iconStart={<RiShareBoxLine />}>Share</MenuItem>
+    <MenuItem iconStart={<RiDeleteBinLine />} color="danger">
+      Delete
+    </MenuItem>
+  </>
+);
+
+export const Default = () => (
+  <List aria-label="Programming languages" style={{ width: 380 }} items={items}>
+    {item => (
+      <ListRow
+        id={item.id}
+        icon={item.icon}
+        menuItems={menuItems}
+        customActions={
+          <TagGroup aria-label={`Tags for ${item.label}`}>
+            {item.tags.map(tag => (
+              <Tag key={tag}>{tag}</Tag>
+            ))}
+          </TagGroup>
+        }
+      >
+        {item.label}
+      </ListRow>
+    )}
+  </List>
+);
+
+export const WithIcons = () => (
+  <List aria-label="Programming languages" style={{ width: 280 }} items={items}>
+    {item => (
+      <ListRow id={item.id} icon={item.icon}>
+        {item.label}
+      </ListRow>
+    )}
+  </List>
+);
+
+export const WithDescription = () => (
+  <List aria-label="Programming languages" style={{ width: 340 }} items={items}>
+    {item => (
+      <ListRow id={item.id} icon={item.icon} description={item.description}>
+        {item.label}
+      </ListRow>
+    )}
+  </List>
+);
+
+export const SelectionModeSingle = () => {
+  const [selected, setSelected] = useState<Selection>(new Set(['react']));
+
+  return (
+    <List
+      aria-label="Programming languages"
+      style={{ width: 280 }}
+      items={items}
+      selectionMode="single"
+      selectedKeys={selected}
+      onSelectionChange={setSelected}
+    >
+      {item => <ListRow id={item.id}>{item.label}</ListRow>}
+    </List>
+  );
+};
+
+export const SelectionModeMultiple = () => {
+  const [selected, setSelected] = useState<Selection>(
+    new Set(['react', 'typescript']),
+  );
+
+  return (
+    <List
+      aria-label="Programming languages"
+      style={{ width: 280 }}
+      items={items}
+      selectionMode="multiple"
+      selectedKeys={selected}
+      onSelectionChange={setSelected}
+    >
+      {item => <ListRow id={item.id}>{item.label}</ListRow>}
+    </List>
+  );
+};
+
+export const Disabled = () => (
+  <List
+    aria-label="Programming languages"
+    style={{ width: 280 }}
+    items={items}
+    disabledKeys={['typescript', 'rust']}
+  >
+    {item => <ListRow id={item.id}>{item.label}</ListRow>}
+  </List>
+);

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

@@ -10,7 +10,7 @@ import {
   SelectionModeMultiple,
   Disabled,
 } from './components';
-import { listBoxPropDefs, listBoxItemPropDefs } from './props-definition';
+import { listPropDefs, listRowPropDefs } from './props-definition';
 import {
   usage,
   preview,
@@ -23,18 +23,18 @@ import {
 import { PageTitle } from '@/components/PageTitle';
 import { Theming } from '@/components/Theming';
 import {
-  ListBoxDefinition,
-  ListBoxItemDefinition,
+  ListDefinition,
+  ListRowDefinition,
 } from '../../../utils/definitions';
 import { ChangelogComponent } from '@/components/ChangelogComponent';
 
 export const reactAriaUrls = {
-  listBox: 'https://react-aria.adobe.com/ListBox',
+  gridList: 'https://react-aria.adobe.com/GridList',
 };
 
 <PageTitle
-  title="ListBox"
-  description="A list of options that allows users to select one or more items."
+  title="List"
+  description="A list of interactive rows with support for keyboard navigation, single or multiple selection, and row actions."
 />
 
 <Snippet align="center" py={4} preview={<Default />} code={preview} />
@@ -45,21 +45,21 @@ export const reactAriaUrls = {
 
 ## API reference
 
-### ListBox
+### List
 
-Container for a list of selectable options.
+Container for a list of interactive rows.
 
-<PropsTable data={listBoxPropDefs} />
+<PropsTable data={listPropDefs} />
 
-<ReactAriaLink component="ListBox" href={reactAriaUrls.listBox} />
+<ReactAriaLink component="GridList" href={reactAriaUrls.gridList} />
 
-### ListBoxItem
+### ListRow
 
-Individual item within a ListBox.
+Individual row within a List.
 
-<PropsTable data={listBoxItemPropDefs} />
+<PropsTable data={listRowPropDefs} />
 
-<ReactAriaLink component="ListBoxItem" href={reactAriaUrls.listBox} />
+<ReactAriaLink component="GridListItem" href={reactAriaUrls.gridList} />
 
 ## Examples
 
@@ -101,6 +101,6 @@ Individual item within a ListBox.
 
 <Snippet align="center" py={4} open preview={<Disabled />} code={disabled} />
 
-<Theming definition={ListBoxDefinition} />
+<Theming definition={ListDefinition} />
 
-<ChangelogComponent component="list-box" />
+<ChangelogComponent component="list" />

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

@@ -4,7 +4,7 @@ import {
   type PropDef,
 } from '@/utils/propDefs';
 
-export const listBoxPropDefs: Record<string, PropDef> = {
+export const listPropDefs: Record<string, PropDef> = {
   items: {
     type: 'enum',
     values: ['Iterable<T>'],
@@ -12,7 +12,7 @@ export const listBoxPropDefs: Record<string, PropDef> = {
   },
   renderEmptyState: {
     type: 'enum',
-    values: ['() => ReactNode'],
+    values: ['(props: GridListRenderProps) => ReactNode'],
     description: 'Content to display when the collection is empty.',
   },
   selectionMode: {
@@ -44,10 +44,10 @@ export const listBoxPropDefs: Record<string, PropDef> = {
   ...classNamePropDefs,
 };
 
-export const listBoxItemPropDefs: Record<string, PropDef> = {
+export const listRowPropDefs: Record<string, PropDef> = {
   id: {
     type: 'string',
-    description: 'Unique identifier for the item.',
+    description: 'Unique identifier for the row.',
   },
   textValue: {
     type: 'string',
@@ -57,7 +57,7 @@ export const listBoxItemPropDefs: Record<string, PropDef> = {
   icon: {
     type: 'enum',
     values: ['ReactNode'],
-    description: 'Icon displayed before the item label.',
+    description: 'Icon displayed before the row label.',
   },
   description: {
     type: 'string',
@@ -65,17 +65,19 @@ export const listBoxItemPropDefs: Record<string, PropDef> = {
   },
   isDisabled: {
     type: 'boolean',
-    description: 'Whether the item is disabled.',
+    description: 'Whether the row is disabled.',
   },
   menuItems: {
     type: 'enum',
-    values: ['Iterable<MenuItemConfig>'],
-    description: 'Menu items displayed for this list box item.',
+    values: ['ReactNode'],
+    description:
+      'Menu items rendered inside an automatically managed dropdown. Pass MenuItem nodes.',
   },
   customActions: {
     type: 'enum',
     values: ['ReactNode'],
-    description: 'Custom action elements displayed alongside the item.',
+    description:
+      'Custom action elements displayed on the right side of the row, e.g. tags.',
   },
   ...childrenPropDefs,
   ...classNamePropDefs,

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

@@ -0,0 +1,72 @@
+export const usage = `import { List, ListRow } from '@backstage/ui';
+
+<List aria-label="Programming languages" items={items}>
+  {item => <ListRow id={item.id}>{item.label}</ListRow>}
+</List>`;
+
+export const preview = `<List aria-label="Programming languages" items={items}>
+  {item => (
+    <ListRow
+      id={item.id}
+      icon={item.icon}
+      menuItems={menuItems}
+      customActions={
+        <TagGroup aria-label={\`Tags for \${item.label}\`}>
+          {item.tags.map(tag => (
+            <Tag key={tag}>{tag}</Tag>
+          ))}
+        </TagGroup>
+      }
+    >
+      {item.label}
+    </ListRow>
+  )}
+</List>`;
+
+export const withIcons = `<List aria-label="Programming languages" items={items}>
+  {item => (
+    <ListRow id={item.id} icon={item.icon}>
+      {item.label}
+    </ListRow>
+  )}
+</List>`;
+
+export const withDescription = `<List aria-label="Programming languages" items={items}>
+  {item => (
+    <ListRow id={item.id} icon={item.icon} description={item.description}>
+      {item.label}
+    </ListRow>
+  )}
+</List>`;
+
+export const selectionModeSingle = `const [selected, setSelected] = useState(new Set(['react']));
+
+<List
+  aria-label="Programming languages"
+  items={items}
+  selectionMode="single"
+  selectedKeys={selected}
+  onSelectionChange={setSelected}
+>
+  {item => <ListRow id={item.id}>{item.label}</ListRow>}
+</List>`;
+
+export const selectionModeMultiple = `const [selected, setSelected] = useState(new Set(['react', 'typescript']));
+
+<List
+  aria-label="Programming languages"
+  items={items}
+  selectionMode="multiple"
+  selectedKeys={selected}
+  onSelectionChange={setSelected}
+>
+  {item => <ListRow id={item.id}>{item.label}</ListRow>}
+</List>`;
+
+export const disabled = `<List
+  aria-label="Programming languages"
+  items={items}
+  disabledKeys={['typescript', 'rust']}
+>
+  {item => <ListRow id={item.id}>{item.label}</ListRow>}
+</List>`;

docs-ui/src/utils/data.ts

@@ -70,8 +70,8 @@ export const components: Page[] = [
     slug: 'link',
   },
   {
-    title: 'ListBox',
-    slug: 'list-box',
+    title: 'List',
+    slug: 'list',
   },
   {
     title: 'Menu',