Merge pull request #33358 from backstage/charlesdedreuille/bacui-42-code-listboxlistrow-component

feat(ui): add List and ListRow components

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

@@ -0,0 +1,103 @@
+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 { listPropDefs, listRowPropDefs } from './props-definition';
+import {
+  usage,
+  preview,
+  withIcons,
+  withDescription,
+  selectionModeSingle,
+  selectionModeMultiple,
+  disabled,
+} from './snippets';
+import { PageTitle } from '@/components/PageTitle';
+import { Theming } from '@/components/Theming';
+import { ListDefinition, ListRowDefinition } from '../../../utils/definitions';
+import { ChangelogComponent } from '@/components/ChangelogComponent';
+
+export const reactAriaUrls = {
+  gridList: 'https://react-aria.adobe.com/GridList',
+};
+
+<PageTitle
+  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} />
+
+## Usage
+
+<CodeBlock code={usage} />
+
+## API reference
+
+### List
+
+Container for a list of interactive rows.
+
+<PropsTable data={listPropDefs} />
+
+<ReactAriaLink component="GridList" href={reactAriaUrls.gridList} />
+
+### ListRow
+
+Individual row within a List.
+
+<PropsTable data={listRowPropDefs} />
+
+<ReactAriaLink component="GridListItem" href={reactAriaUrls.gridList} />
+
+## 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={ListDefinition} />
+
+<ChangelogComponent component="list" />

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

@@ -0,0 +1,84 @@
+import {
+  classNamePropDefs,
+  childrenPropDefs,
+  type PropDef,
+} from '@/utils/propDefs';
+
+export const listPropDefs: Record<string, PropDef> = {
+  items: {
+    type: 'enum',
+    values: ['Iterable<T>'],
+    description: 'Item objects in the collection.',
+  },
+  renderEmptyState: {
+    type: 'enum',
+    values: ['(props: GridListRenderProps) => 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 listRowPropDefs: Record<string, PropDef> = {
+  id: {
+    type: 'string',
+    description: 'Unique identifier for the row.',
+  },
+  textValue: {
+    type: 'string',
+    description:
+      'Text value for accessibility. Derived from children if string.',
+  },
+  icon: {
+    type: 'enum',
+    values: ['ReactNode'],
+    description: 'Icon displayed before the row label.',
+  },
+  description: {
+    type: 'string',
+    description: 'Secondary description text displayed below the label.',
+  },
+  isDisabled: {
+    type: 'boolean',
+    description: 'Whether the row is disabled.',
+  },
+  menuItems: {
+    type: 'enum',
+    values: ['ReactNode'],
+    description:
+      'Menu items rendered inside an automatically managed dropdown. Pass MenuItem nodes.',
+  },
+  customActions: {
+    type: 'enum',
+    values: ['ReactNode'],
+    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

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

docs-ui/src/utils/types.ts

@@ -19,6 +19,8 @@ export type Component =
   | 'heading'
   | 'icon'
   | 'link'
+  | 'list'
+  | 'list-row'
   | 'menu'
   | 'password-field'
   | 'radio-group'