An open source design system that's fully customizable and agent ready
TypeScript
feat(List): add XDSList and XDSListItem components (#261)
Cindy Zhang4f3173b5c605
diff --git a/apps/storybook/stories/List.stories.tsx b/apps/storybook/stories/List.stories.tsxnew file mode 100644index 0000000000..0133aa25bd--- /dev/null+++ b/apps/storybook/stories/List.stories.tsx@@ -0,0 +1,219 @@+import type {Meta, StoryObj} from '@storybook/react';+import {XDSList, XDSListItem} from '@xds/core/List';+import {XDSAvatar} from '@xds/core/Avatar';+import {XDSBadge} from '@xds/core/Badge';+import {XDSIcon} from '@xds/core/Icon';+import {+ Cog6ToothIcon,+ BellIcon,+ ShieldCheckIcon,+ ChevronRightIcon,+ InboxIcon,+ PaperAirplaneIcon,+ DocumentIcon,+} from '@heroicons/react/24/outline';++const meta: Meta<typeof XDSList> = {+ title: 'Core/XDSList',+ component: XDSList,+ tags: ['autodocs'],+ argTypes: {+ density: {+ control: 'select',+ options: ['compact', 'balanced', 'spacious'],+ description: 'Spacing density for list items',+ },+ hasDividers: {+ control: 'boolean',+ description: 'Whether to show dividers between items',+ },+ listStyle: {+ control: 'select',+ options: ['none', 'disc', 'decimal', 'circle'],+ description: 'List marker style',+ },+ },+};++export default meta;+type Story = StoryObj<typeof XDSList>;++export const Basic: Story = {+ render: args => (+ <XDSList {...args}>+ <XDSListItem label="Notifications" description="Manage your alerts" />+ <XDSListItem label="Privacy" description="Control your data" />+ <XDSListItem label="Security" description="Password and 2FA" />+ </XDSList>+ ),+};++export const WithDividers: Story = {+ render: args => (+ <XDSList hasDividers header={<strong>Settings</strong>} {...args}>+ <XDSListItem+ label="Notifications"+ description="Manage your alerts"+ startContent={<XDSIcon icon={BellIcon} />}+ />+ <XDSListItem+ label="Privacy"+ description="Control your data"+ startContent={<XDSIcon icon={ShieldCheckIcon} />}+ />+ <XDSListItem+ label="General"+ description="App preferences"+ startContent={<XDSIcon icon={Cog6ToothIcon} />}+ />+ </XDSList>+ ),+};++export const Compact: Story = {+ render: args => (+ <XDSList density="compact" hasDividers {...args}>+ <XDSListItem+ label="Notifications"+ onClick={() => {}}+ endContent={<XDSBadge label="3" />}+ />+ <XDSListItem+ label="Messages"+ onClick={() => {}}+ endContent={<XDSBadge label="12" />}+ />+ <XDSListItem label="Settings" onClick={() => {}} />+ </XDSList>+ ),+};++export const Spacious: Story = {+ render: args => (+ <XDSList density="spacious" {...args}>+ <XDSListItem+ label="Getting Started"+ description="Learn the basics of our platform"+ />+ <XDSListItem+ label="Advanced Topics"+ description="Deep dive into advanced features"+ />+ <XDSListItem+ label="API Reference"+ description="Complete API documentation"+ />+ </XDSList>+ ),+};++export const Interactive: Story = {+ render: args => (+ <XDSList {...args}>+ <XDSListItem+ label="Inbox"+ isSelected+ onClick={() => {}}+ startContent={<XDSIcon icon={InboxIcon} />}+ endContent={<XDSIcon icon={ChevronRightIcon} />}+ />+ <XDSListItem+ label="Sent"+ onClick={() => {}}+ startContent={<XDSIcon icon={PaperAirplaneIcon} />}+ endContent={<XDSIcon icon={ChevronRightIcon} />}+ />+ <XDSListItem+ label="Drafts"+ onClick={() => {}}+ startContent={<XDSIcon icon={DocumentIcon} />}+ endContent={<XDSIcon icon={ChevronRightIcon} />}+ />+ </XDSList>+ ),+};++export const Links: Story = {+ render: args => (+ <XDSList {...args}>+ <XDSListItem label="Documentation" href="/docs" />+ <XDSListItem+ label="GitHub"+ href="https://github.com"+ target="_blank"+ description="View source code"+ />+ <XDSListItem+ label="Storybook"+ href="/storybook"+ description="Component playground"+ />+ </XDSList>+ ),+};++export const OrderedList: Story = {+ render: args => (+ <XDSList listStyle="decimal" {...args}>+ <XDSListItem+ label="Install the package"+ description="npm install @xds/core"+ />+ <XDSListItem+ label="Import components"+ description="import { XDSList } from '@xds/core'"+ />+ <XDSListItem+ label="Start building"+ description="Use components in your app"+ />+ </XDSList>+ ),+};++export const BulletedList: Story = {+ render: args => (+ <XDSList listStyle="disc" {...args}>+ <XDSListItem label="Accessible by default" />+ <XDSListItem label="Themeable with StyleX" />+ <XDSListItem label="Composable and extensible" />+ </XDSList>+ ),+};++export const DisabledItems: Story = {+ render: args => (+ <XDSList {...args}>+ <XDSListItem label="Available" onClick={() => {}} />+ <XDSListItem label="Unavailable" onClick={() => {}} isDisabled />+ <XDSListItem label="Also Available" onClick={() => {}} />+ </XDSList>+ ),+};++export const WithMedia: Story = {+ render: args => (+ <XDSList hasDividers {...args}>+ <XDSListItem+ label="Alex Johnson"+ description="Hey, are we still on for lunch tomorrow?"+ startContent={<XDSAvatar name="Alex Johnson" size="md" />}+ onClick={() => {}}+ endContent={<XDSBadge label="2" />}+ />+ <XDSListItem+ label="Sam Rivera"+ description="I pushed the latest changes to the repo"+ startContent={<XDSAvatar name="Sam Rivera" size="md" />}+ onClick={() => {}}+ />+ <XDSListItem+ label="Jordan Lee"+ description="Can you review the design spec when you get a chance?"+ startContent={<XDSAvatar name="Jordan Lee" size="md" />}+ onClick={() => {}}+ endContent={<XDSBadge label="5" />}+ />+ </XDSList>+ ),+};diff --git a/packages/core/src/List/README.md b/packages/core/src/List/README.mdnew file mode 100644index 0000000000..1f98173c46--- /dev/null+++ b/packages/core/src/List/README.md@@ -0,0 +1,110 @@+# XDSList++Vertical list component for rendering collections of items with consistent spacing, dividers, and marker styles. Uses a composition model: `XDSList` wraps `XDSListItem` sub-components.++## Files++<!-- SYNC: Update when files are added/removed -->++| File | Purpose |+| -------------------- | ------------------------------------ |+| `XDSList.tsx` | List container component |+| `XDSListItem.tsx` | List item component |+| `XDSListContext.tsx` | Internal context for density sharing |+| `XDSList.test.tsx` | Unit tests |+| `index.ts` | Public exports |+| `README.md` | This documentation |++## Usage++```tsx+import {XDSList, XDSListItem} from '@xds/core';++// Basic list+<XDSList>+ <XDSListItem label="Notifications" description="Manage your alerts" />+ <XDSListItem label="Privacy" description="Control your data" />+</XDSList>++// With dividers and header+<XDSList hasDividers header={<strong>Team Members</strong>}>+ <XDSListItem+ label="Alice Johnson"+ description="Engineering"+ startContent={<XDSIcon icon={UserIcon} />}+ />+ <XDSListItem+ label="Bob Smith"+ description="Design"+ startContent={<XDSIcon icon={UserIcon} />}+ />+</XDSList>++// Interactive items+<XDSList>+ <XDSListItem label="Settings" onClick={() => navigate('/settings')} />+ <XDSListItem label="Docs" href="/docs" target="_blank" />+</XDSList>++// Ordered list+<XDSList listStyle="decimal">+ <XDSListItem label="First step" />+ <XDSListItem label="Second step" />+</XDSList>+```++## XDSList Props++| Prop | Type | Default | Description |+| ------------- | ------------------------------------------- | ------------ | ------------------------------------------------ |+| `children` | `ReactNode` | — | List items (XDSListItem components) |+| `density` | `'compact' \| 'balanced' \| 'spacious'` | `'balanced'` | Spacing density for items |+| `hasDividers` | `boolean` | `false` | Show dividers between items |+| `header` | `ReactNode` | — | Header content, associated via `aria-labelledby` |+| `listStyle` | `'none' \| 'disc' \| 'decimal' \| 'circle'` | `'none'` | List marker style. `'decimal'` renders `<ol>` |+| `xstyle` | `StyleXStyles` | — | Style overrides |+| `data-testid` | `string` | — | Test ID |++## XDSListItem Props++| Prop | Type | Default | Description |+| -------------- | ------------------------- | ------- | ------------------------------------------------ |+| `label` | `string` | — | Primary text (required) |+| `description` | `string` | — | Secondary text below label |+| `startContent` | `ReactNode` | — | Content before label area (icon, avatar) |+| `endContent` | `ReactNode` | — | Content after label area (badge, chevron) |+| `onClick` | `(e: MouseEvent) => void` | — | Click handler (enables invisible button pattern) |+| `href` | `string` | — | Link URL (enables invisible anchor pattern) |+| `target` | `string` | — | Link target (only with `href`) |+| `isDisabled` | `boolean` | `false` | Disabled state |+| `isSelected` | `boolean` | `false` | Selected state (`aria-selected`) |+| `xstyle` | `StyleXStyles` | — | Style overrides |+| `data-testid` | `string` | — | Test ID |++## Interactive Pattern++When `onClick` is provided, XDSListItem uses the **invisible button pattern**:++```+┌─ li (container, :focus-within outline, click area) ──────────┐+│ [startContent] [button.invisible(label + desc)] [endContent] │+└──────────────────────────────────────────────────────────────────┘+```++- The `<li>` is the visual container with hover/press styles+- An invisible `<button>` wraps the label + description for accessibility+- `startContent` and `endContent` are siblings to the button (not inside it)+- Container click fires `onClick` unless the click originated from an interactive child+- `:focus-within` on the container shows the focus outline++When `href` is provided, the same pattern uses an invisible `<a>` instead.++## Accessibility++- Semantic `<ul>` / `<ol>` with `<li>` elements+- `role="list"` added when `listStyle='none'` (Safari fix)+- `aria-labelledby` links header to list+- `aria-selected` on selected items+- `aria-disabled` on disabled items+- Dividers are `aria-hidden="true"`+- Interactive items are keyboard-focusable via Tabdiff --git a/packages/core/src/List/XDSList.test.tsx b/packages/core/src/List/XDSList.test.tsxnew file mode 100644index 0000000000..d46ab152b0--- /dev/null+++ b/packages/core/src/List/XDSList.test.tsx@@ -0,0 +1,566 @@+/**+ * @file XDSList.test.tsx+ * @input Uses vitest, @testing-library/react, XDSList, XDSListItem+ * @output Unit tests for XDSList and XDSListItem components+ * @position Testing; validates XDSList.tsx and XDSListItem.tsx implementation+ *+ * SYNC: When modified, update this header+ */++import {describe, it, expect, vi} from 'vitest';+import {render, screen} from '@testing-library/react';+import userEvent from '@testing-library/user-event';+import {XDSList} from './XDSList';+import {XDSListItem} from './XDSListItem';++describe('XDSList', () => {+ // ===========================================================================+ // Basic rendering+ // ===========================================================================++ it('renders a list with items', () => {+ render(+ <XDSList>+ <XDSListItem label="Item 1" />+ <XDSListItem label="Item 2" />+ </XDSList>,+ );+ expect(screen.getByText('Item 1')).toBeInTheDocument();+ expect(screen.getByText('Item 2')).toBeInTheDocument();+ });++ it('renders label and description', () => {+ render(+ <XDSList>+ <XDSListItem label="Settings" description="Manage your preferences" />+ </XDSList>,+ );+ expect(screen.getByText('Settings')).toBeInTheDocument();+ expect(screen.getByText('Manage your preferences')).toBeInTheDocument();+ });++ it('supports data-testid on list', () => {+ render(+ <XDSList data-testid="my-list">+ <XDSListItem label="Item" />+ </XDSList>,+ );+ expect(screen.getByTestId('my-list')).toBeInTheDocument();+ });++ it('supports data-testid on list item', () => {+ render(+ <XDSList>+ <XDSListItem label="Item" data-testid="my-item" />+ </XDSList>,+ );+ expect(screen.getByTestId('my-item')).toBeInTheDocument();+ });++ // ===========================================================================+ // Semantic HTML+ // ===========================================================================++ it('renders as <ul> by default', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Item" />+ </XDSList>,+ );+ expect(container.querySelector('ul')).toBeInTheDocument();+ expect(container.querySelector('ol')).not.toBeInTheDocument();+ });++ it('renders as <ol> when listStyle is decimal', () => {+ const {container} = render(+ <XDSList listStyle="decimal">+ <XDSListItem label="First" />+ <XDSListItem label="Second" />+ </XDSList>,+ );+ expect(container.querySelector('ol')).toBeInTheDocument();+ expect(container.querySelector('ul')).not.toBeInTheDocument();+ });++ it('renders as <ul> when listStyle is disc', () => {+ const {container} = render(+ <XDSList listStyle="disc">+ <XDSListItem label="Item" />+ </XDSList>,+ );+ expect(container.querySelector('ul')).toBeInTheDocument();+ });++ it('renders as <ul> when listStyle is circle', () => {+ const {container} = render(+ <XDSList listStyle="circle">+ <XDSListItem label="Item" />+ </XDSList>,+ );+ expect(container.querySelector('ul')).toBeInTheDocument();+ });++ it('adds role="list" when listStyle is none (Safari fix)', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Item" />+ </XDSList>,+ );+ const ul = container.querySelector('ul');+ expect(ul).toHaveAttribute('role', 'list');+ });++ it('does not add role="list" when listStyle is disc', () => {+ const {container} = render(+ <XDSList listStyle="disc">+ <XDSListItem label="Item" />+ </XDSList>,+ );+ const ul = container.querySelector('ul');+ expect(ul).not.toHaveAttribute('role');+ });++ it('does not add role="list" when listStyle is decimal', () => {+ const {container} = render(+ <XDSList listStyle="decimal">+ <XDSListItem label="Item" />+ </XDSList>,+ );+ const ol = container.querySelector('ol');+ expect(ol).not.toHaveAttribute('role');+ });++ it('renders items as <li> elements', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Item 1" />+ <XDSListItem label="Item 2" />+ </XDSList>,+ );+ const items = container.querySelectorAll('li');+ expect(items).toHaveLength(2);+ });++ // ===========================================================================+ // Header with aria-labelledby+ // ===========================================================================++ it('renders header and associates via aria-labelledby', () => {+ const {container} = render(+ <XDSList header={<span>Team Members</span>}>+ <XDSListItem label="Alice" />+ </XDSList>,+ );+ expect(screen.getByText('Team Members')).toBeInTheDocument();+ const ul = container.querySelector('ul');+ const headerId = ul?.getAttribute('aria-labelledby');+ expect(headerId).toBeTruthy();+ const headerEl = document.getElementById(headerId!);+ expect(headerEl).toBeInTheDocument();+ expect(headerEl?.textContent).toBe('Team Members');+ });++ it('does not render aria-labelledby when no header', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Item" />+ </XDSList>,+ );+ const ul = container.querySelector('ul');+ expect(ul).not.toHaveAttribute('aria-labelledby');+ });++ // ===========================================================================+ // Density variants+ // ===========================================================================++ it('renders with compact density', () => {+ const {container} = render(+ <XDSList density="compact">+ <XDSListItem label="Item" />+ </XDSList>,+ );+ expect(container.querySelector('li')).toBeInTheDocument();+ });++ it('renders with balanced density (default)', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Item" />+ </XDSList>,+ );+ expect(container.querySelector('li')).toBeInTheDocument();+ });++ it('renders with spacious density', () => {+ const {container} = render(+ <XDSList density="spacious">+ <XDSListItem label="Item" />+ </XDSList>,+ );+ expect(container.querySelector('li')).toBeInTheDocument();+ });++ // ===========================================================================+ // Dividers+ // ===========================================================================++ it('renders dividers between items when hasDividers is true', () => {+ const {container} = render(+ <XDSList hasDividers>+ <XDSListItem label="Item 1" />+ <XDSListItem label="Item 2" />+ <XDSListItem label="Item 3" />+ </XDSList>,+ );+ const dividers = container.querySelectorAll('hr');+ expect(dividers).toHaveLength(2);+ });++ it('dividers have aria-hidden="true"', () => {+ const {container} = render(+ <XDSList hasDividers>+ <XDSListItem label="Item 1" />+ <XDSListItem label="Item 2" />+ </XDSList>,+ );+ const divider = container.querySelector('hr');+ expect(divider).toHaveAttribute('aria-hidden', 'true');+ });++ it('does not render dividers when hasDividers is false', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Item 1" />+ <XDSListItem label="Item 2" />+ </XDSList>,+ );+ const dividers = container.querySelectorAll('hr');+ expect(dividers).toHaveLength(0);+ });++ // ===========================================================================+ // Interactive items — onClick (invisible button pattern)+ // ===========================================================================++ it('renders an invisible button when onClick is provided', () => {+ const onClick = vi.fn();+ const {container} = render(+ <XDSList>+ <XDSListItem label="Clickable" onClick={onClick} />+ </XDSList>,+ );+ const button = container.querySelector('button');+ expect(button).toBeInTheDocument();+ expect(button?.textContent).toContain('Clickable');+ });++ it('fires onClick when invisible button is clicked', async () => {+ const user = userEvent.setup();+ const onClick = vi.fn();+ render(+ <XDSList>+ <XDSListItem label="Clickable" onClick={onClick} />+ </XDSList>,+ );+ await user.click(screen.getByRole('button'));+ expect(onClick).toHaveBeenCalledTimes(1);+ });++ it('fires onClick when container area is clicked', async () => {+ const user = userEvent.setup();+ const onClick = vi.fn();+ render(+ <XDSList>+ <XDSListItem+ label="Clickable"+ onClick={onClick}+ data-testid="item"+ startContent={<span data-testid="start">★</span>}+ />+ </XDSList>,+ );+ // Click on startContent (non-interactive, should propagate)+ await user.click(screen.getByTestId('start'));+ expect(onClick).toHaveBeenCalledTimes(1);+ });++ it('does not fire item onClick when endContent interactive element is clicked', async () => {+ const user = userEvent.setup();+ const itemClick = vi.fn();+ const buttonClick = vi.fn();+ render(+ <XDSList>+ <XDSListItem+ label="Item"+ onClick={itemClick}+ endContent={+ <button type="button" onClick={buttonClick}>+ Action+ </button>+ }+ />+ </XDSList>,+ );+ await user.click(screen.getByText('Action'));+ expect(buttonClick).toHaveBeenCalledTimes(1);+ expect(itemClick).not.toHaveBeenCalled();+ });++ it('invisible button is focusable via keyboard', async () => {+ const user = userEvent.setup();+ const onClick = vi.fn();+ render(+ <XDSList>+ <XDSListItem label="Focusable" onClick={onClick} />+ </XDSList>,+ );+ await user.tab();+ expect(screen.getByRole('button')).toHaveFocus();+ });++ it('invisible button can be activated via keyboard', async () => {+ const user = userEvent.setup();+ const onClick = vi.fn();+ render(+ <XDSList>+ <XDSListItem label="Pressable" onClick={onClick} />+ </XDSList>,+ );+ await user.tab();+ await user.keyboard('{Enter}');+ expect(onClick).toHaveBeenCalledTimes(1);+ });++ it('does not render nested buttons — only one invisible button', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Item" onClick={() => {}} />+ </XDSList>,+ );+ const buttons = container.querySelectorAll('li button');+ // Should be exactly 1 invisible button (no nesting)+ expect(buttons).toHaveLength(1);+ });++ // ===========================================================================+ // Interactive items — href (invisible anchor pattern)+ // ===========================================================================++ it('renders an invisible anchor when href is provided', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Link" href="/docs" />+ </XDSList>,+ );+ const anchor = container.querySelector('a');+ expect(anchor).toBeInTheDocument();+ expect(anchor).toHaveAttribute('href', '/docs');+ expect(anchor?.textContent).toContain('Link');+ });++ it('sets target on anchor when provided', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem+ label="External"+ href="https://example.com"+ target="_blank"+ />+ </XDSList>,+ );+ const anchor = container.querySelector('a');+ expect(anchor).toHaveAttribute('target', '_blank');+ });++ it('does not render button or anchor for static items', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Static" />+ </XDSList>,+ );+ expect(container.querySelector('button')).not.toBeInTheDocument();+ expect(container.querySelector('a')).not.toBeInTheDocument();+ });++ // ===========================================================================+ // Disabled state+ // ===========================================================================++ it('applies aria-disabled when isDisabled', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Disabled" isDisabled />+ </XDSList>,+ );+ const li = container.querySelector('li');+ expect(li).toHaveAttribute('aria-disabled', 'true');+ });++ it('disables the invisible button when isDisabled', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Disabled" onClick={() => {}} isDisabled />+ </XDSList>,+ );+ const button = container.querySelector('button');+ expect(button).toBeDisabled();+ });++ it('does not fire onClick when disabled item is clicked', async () => {+ const onClick = vi.fn();+ const {container} = render(+ <XDSList>+ <XDSListItem label="Disabled" onClick={onClick} isDisabled />+ </XDSList>,+ );+ // pointerEvents: none prevents click, but let's verify the handler guards+ const li = container.querySelector('li');+ // Manually dispatch click (bypassing pointer-events)+ li?.dispatchEvent(new MouseEvent('click', {bubbles: true}));+ expect(onClick).not.toHaveBeenCalled();+ });++ // ===========================================================================+ // Selected state+ // ===========================================================================++ it('applies aria-selected when isSelected', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Selected" isSelected onClick={() => {}} />+ </XDSList>,+ );+ const li = container.querySelector('li');+ expect(li).toHaveAttribute('aria-selected', 'true');+ });++ it('does not apply aria-selected when not selected', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem label="Not Selected" />+ </XDSList>,+ );+ const li = container.querySelector('li');+ expect(li).not.toHaveAttribute('aria-selected');+ });++ // ===========================================================================+ // startContent and endContent+ // ===========================================================================++ it('renders startContent before label', () => {+ render(+ <XDSList>+ <XDSListItem+ label="With Icon"+ startContent={<span data-testid="icon">★</span>}+ />+ </XDSList>,+ );+ expect(screen.getByTestId('icon')).toBeInTheDocument();+ });++ it('renders endContent after label', () => {+ render(+ <XDSList>+ <XDSListItem+ label="With Badge"+ endContent={<span data-testid="badge">3</span>}+ />+ </XDSList>,+ );+ expect(screen.getByTestId('badge')).toBeInTheDocument();+ });++ it('startContent and endContent are siblings to invisible button', () => {+ const {container} = render(+ <XDSList>+ <XDSListItem+ label="Item"+ onClick={() => {}}+ startContent={<span data-testid="start">★</span>}+ endContent={<span data-testid="end">→</span>}+ />+ </XDSList>,+ );+ const button = container.querySelector('button');+ const li = container.querySelector('li');+ // startContent and endContent should be children of li, not inside button+ expect(li?.querySelector('[data-testid="start"]')).toBeInTheDocument();+ expect(li?.querySelector('[data-testid="end"]')).toBeInTheDocument();+ expect(+ button?.querySelector('[data-testid="start"]'),+ ).not.toBeInTheDocument();+ expect(+ button?.querySelector('[data-testid="end"]'),+ ).not.toBeInTheDocument();+ });++ // ===========================================================================+ // Border radius+ // ===========================================================================++ it('applies content radius by default', () => {+ render(+ <XDSList>+ <XDSListItem label="Item" data-testid="item" isSelected />+ </XDSList>,+ );+ const item = screen.getByTestId('item');+ expect(item).toBeInTheDocument();+ });++ it('removes radius when hasDividers is true', () => {+ render(+ <XDSList hasDividers>+ <XDSListItem label="Item" data-testid="item" isSelected />+ </XDSList>,+ );+ const item = screen.getByTestId('item');+ expect(item).toBeInTheDocument();+ });++ // ===========================================================================+ // List markers+ // ===========================================================================++ it('renders list markers for disc style', () => {+ render(+ <XDSList listStyle="disc">+ <XDSListItem label="Bullet item" data-testid="item" />+ </XDSList>,+ );+ const item = screen.getByTestId('item');+ // When markers are shown, inner content is wrapped in a div+ const innerWrapper = item.querySelector('div');+ expect(innerWrapper).toBeInTheDocument();+ });++ it('does not wrap content when listStyle is none', () => {+ render(+ <XDSList listStyle="none">+ <XDSListItem label="Plain item" data-testid="item" />+ </XDSList>,+ );+ const item = screen.getByTestId('item');+ // No inner div wrapper when no markers+ const innerDiv = item.querySelector(':scope > div');+ expect(innerDiv).not.toBeInTheDocument();+ });++ // ===========================================================================+ // Description rendering+ // ===========================================================================++ it('does not render description when not provided', () => {+ render(+ <XDSList>+ <XDSListItem label="Label Only" />+ </XDSList>,+ );+ // Should have the label span only (plus possibly wrapper spans)+ expect(screen.getByText('Label Only')).toBeInTheDocument();+ expect(screen.queryByText('undefined')).not.toBeInTheDocument();+ });+});diff --git a/packages/core/src/List/XDSList.tsx b/packages/core/src/List/XDSList.tsxnew file mode 100644index 0000000000..4b969817cf--- /dev/null+++ b/packages/core/src/List/XDSList.tsx@@ -0,0 +1,206 @@+/**+ * @file XDSList.tsx+ * @input Uses React forwardRef, ReactNode, StyleXStyles, theme tokens, XDSListContext+ * @output Exports XDSList component, XDSListProps, XDSListDensity, XDSListStyle types+ * @position Core implementation; consumed by index.ts, tested by XDSList.test.tsx+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/List/README.md+ * - /packages/core/src/List/XDSList.test.tsx+ * - /packages/core/src/List/index.ts+ * - /apps/storybook/stories/List.stories.tsx+ */++import {forwardRef, useId, useMemo, Children, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {colorVars, spacingVars} from '../theme/tokens.stylex';+import {XDSListContext, type XDSListDensity} from './XDSListContext';++// =============================================================================+// Types+// =============================================================================++/** List marker style. */+export type XDSListStyle = 'none' | 'disc' | 'decimal' | 'circle';++export {type XDSListDensity} from './XDSListContext';++export interface XDSListProps {+ /**+ * List items. Should be XDSListItem components.+ */+ children: ReactNode;++ /**+ * Spacing density for list items.+ * - 'compact': Tighter spacing for dense UIs+ * - 'balanced': Standard spacing+ * - 'spacious': Extra spacing for readability+ * @default 'balanced'+ */+ density?: XDSListDensity;++ /**+ * Whether to show dividers between list items.+ * @default false+ */+ hasDividers?: boolean;++ /**+ * Header content rendered above the list.+ * Semantically associated via aria-labelledby.+ */+ header?: ReactNode;++ /**+ * List marker style.+ * When 'decimal', renders an `<ol>`. Otherwise renders a `<ul>`.+ * @default 'none'+ */+ listStyle?: XDSListStyle;++ /**+ * StyleX styles to apply to the list container.+ */+ xstyle?: StyleXStyles;++ /**+ * Test ID for testing frameworks.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ list: {+ margin: 0,+ paddingInlineStart: 0,+ },+ listWithMarkers: {+ paddingInlineStart: spacingVars['--spacing-6'],+ },+ header: {+ marginBottom: spacingVars['--spacing-2'],+ },+ divider: {+ height: '1px',+ border: 'none',+ margin: 0,+ backgroundColor: colorVars['--color-divider'],+ },+});++const listStyleTypes = stylex.create({+ none: {+ listStyleType: 'none',+ },+ disc: {+ listStyleType: 'disc',+ },+ decimal: {+ listStyleType: 'decimal',+ },+ circle: {+ listStyleType: 'circle',+ },+});++// =============================================================================+// Component+// =============================================================================++/**+ * A vertical list component for rendering collections of items.+ *+ * Renders semantic `<ul>` or `<ol>` elements with configurable density,+ * dividers, marker styles, and an optional header.+ *+ * @example+ * ```tsx+ * <XDSList>+ * <XDSListItem label="Notifications" description="Manage your alerts" />+ * <XDSListItem label="Privacy" description="Control your data" />+ * </XDSList>+ *+ * <XDSList listStyle="decimal" density="compact">+ * <XDSListItem label="First step" />+ * <XDSListItem label="Second step" />+ * </XDSList>+ * ```+ */+export const XDSList = forwardRef<+ HTMLUListElement | HTMLOListElement,+ XDSListProps+>(+ (+ {+ children,+ density = 'balanced',+ hasDividers = false,+ header,+ listStyle = 'none',+ xstyle,+ 'data-testid': testId,+ },+ ref,+ ) => {+ const headerId = useId();+ const isOrdered = listStyle === 'decimal';+ const hasMarkers = listStyle !== 'none';+ const Tag = isOrdered ? 'ol' : 'ul';++ const contextValue = useMemo(+ () => ({density, hasDividers, hasMarkers}),+ [density, hasDividers, hasMarkers],+ );++ // Interleave dividers between children when hasDividers is true+ let renderedChildren = children;+ if (hasDividers) {+ const childArray = Children.toArray(children);+ const withDividers: ReactNode[] = [];+ childArray.forEach((child, i) => {+ withDividers.push(child);+ if (i < childArray.length - 1) {+ withDividers.push(+ <hr+ key={`divider-${i}`}+ aria-hidden="true"+ {...stylex.props(styles.divider)}+ />,+ );+ }+ });+ renderedChildren = withDividers;+ }++ return (+ <XDSListContext.Provider value={contextValue}>+ {header != null && (+ <div id={headerId} {...stylex.props(styles.header)}>+ {header}+ </div>+ )}+ <Tag+ ref={ref as React.Ref<HTMLUListElement & HTMLOListElement>}+ data-testid={testId}+ aria-labelledby={header != null ? headerId : undefined}+ {...(listStyle === 'none' && !isOrdered ? {role: 'list'} : {})}+ {...stylex.props(+ styles.list,+ listStyleTypes[listStyle],+ hasMarkers && styles.listWithMarkers,+ xstyle,+ )}>+ {renderedChildren}+ </Tag>+ </XDSListContext.Provider>+ );+ },+);++XDSList.displayName = 'XDSList';diff --git a/packages/core/src/List/XDSListContext.tsx b/packages/core/src/List/XDSListContext.tsxnew file mode 100644index 0000000000..2f7eba1dee--- /dev/null+++ b/packages/core/src/List/XDSListContext.tsx@@ -0,0 +1,18 @@+/**+ * @file XDSListContext.tsx+ * @input Uses React createContext+ * @output Exports XDSListContext for sharing density between XDSList and XDSListItem+ * @position Internal context; consumed by XDSList.tsx and XDSListItem.tsx+ */++import {createContext} from 'react';++export type XDSListDensity = 'compact' | 'balanced' | 'spacious';++export interface XDSListContextValue {+ density: XDSListDensity;+ hasDividers: boolean;+ hasMarkers: boolean;+}++export const XDSListContext = createContext<XDSListContextValue | null>(null);diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsxnew file mode 100644index 0000000000..2582055818--- /dev/null+++ b/packages/core/src/List/XDSListItem.tsx@@ -0,0 +1,370 @@+/**+ * @file XDSListItem.tsx+ * @input Uses React forwardRef, ReactNode, StyleXStyles, theme tokens+ * @output Exports XDSListItem component, XDSListItemProps type+ * @position Core implementation; consumed by XDSList, index.ts, tested by XDSList.test.tsx+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/List/README.md+ * - /packages/core/src/List/XDSList.test.tsx+ * - /packages/core/src/List/index.ts+ * - /apps/storybook/stories/List.stories.tsx+ */++import {forwardRef, useContext, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {+ colorVars,+ radiusVars,+ spacingVars,+ textSizeVars,+ lineHeightVars,+ transitionVars,+} from '../theme/tokens.stylex';+import {XDSListContext} from './XDSListContext';++// =============================================================================+// Types+// =============================================================================++export interface XDSListItemProps {+ /**+ * Primary text label for the item.+ */+ label: string;++ /**+ * Secondary description text below the label.+ */+ description?: string;++ /**+ * Content rendered before the item (icon, avatar, checkbox).+ * Uses start/end naming for RTL support.+ */+ startContent?: ReactNode;++ /**+ * Content rendered after the item (badge, action button, chevron).+ */+ endContent?: ReactNode;++ /**+ * Click handler for interactive items.+ * Automatically enables hover/press styles when provided.+ */+ onClick?: (e: React.MouseEvent) => void;++ /**+ * URL for link items. Renders an invisible anchor element.+ * Automatically enables hover/press styles when provided.+ */+ href?: string;++ /**+ * Link target (e.g., '_blank'). Only used with href.+ */+ target?: string;++ /**+ * Whether the item is disabled.+ * @default false+ */+ isDisabled?: boolean;++ /**+ * Whether the item is currently selected.+ * @default false+ */+ isSelected?: boolean;++ /**+ * StyleX styles to apply to the list item.+ */+ xstyle?: StyleXStyles;++ /**+ * Test ID for testing frameworks.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ // Default layout: <li> is the flex container+ item: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-3'],+ position: 'relative',+ boxSizing: 'border-box',+ textAlign: 'start',+ },+ // When list has markers (disc/decimal/circle), <li> must be list-item+ // so the browser renders the ::marker. Flex layout moves to inner wrapper.+ itemWithMarker: {+ display: 'list-item',+ position: 'relative',+ boxSizing: 'border-box',+ textAlign: 'start',+ },+ // Inner flex wrapper used when markers are shown+ innerWrapper: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-3'],+ },+ withRadius: {+ borderRadius: radiusVars['--radius-content'],+ },+ noRadius: {+ borderRadius: 0,+ },+ interactive: {+ cursor: 'pointer',+ transitionProperty: 'background-image',+ transitionDuration: transitionVars['--transition-fast'],+ backgroundImage: {+ default: null,+ ':hover': `linear-gradient(${colorVars['--color-hover-overlay']}, ${colorVars['--color-hover-overlay']})`,+ ':active': `linear-gradient(${colorVars['--color-pressed-overlay']}, ${colorVars['--color-pressed-overlay']})`,+ },+ },+ focusWithinOutline: {+ outline: {+ default: 'none',+ ':focus-within': `2px solid ${colorVars['--color-focus-outline']}`,+ },+ outlineOffset: {+ default: '0',+ ':focus-within': '2px',+ },+ },+ disabled: {+ cursor: 'not-allowed',+ opacity: 0.5,+ pointerEvents: 'none' as const,+ },+ selected: {+ backgroundColor: colorVars['--color-accent-deemphasized'],+ },+ invisibleButton: {+ all: 'unset',+ cursor: 'inherit',+ font: 'inherit',+ color: 'inherit',+ display: 'flex',+ flexDirection: 'column',+ flex: 1,+ minWidth: 0,+ textAlign: 'start',+ },+ invisibleAnchor: {+ all: 'unset',+ cursor: 'inherit',+ font: 'inherit',+ color: 'inherit',+ display: 'flex',+ flexDirection: 'column',+ flex: 1,+ minWidth: 0,+ textAlign: 'start',+ textDecoration: 'none',+ },+ content: {+ display: 'flex',+ flexDirection: 'column',+ flex: 1,+ minWidth: 0,+ textAlign: 'start',+ },+ label: {+ color: colorVars['--color-text-primary'],+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ description: {+ color: colorVars['--color-text-secondary'],+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ startContent: {+ flexShrink: 0,+ display: 'flex',+ alignItems: 'center',+ },+ endContent: {+ flexShrink: 0,+ display: 'flex',+ alignItems: 'center',+ marginInlineStart: 'auto',+ },+});++const densityStyles = stylex.create({+ compact: {+ paddingBlock: spacingVars['--spacing-1'],+ paddingInline: spacingVars['--spacing-2'],+ fontSize: textSizeVars['--text-xsm'],+ lineHeight: lineHeightVars['--leading-snug'],+ },+ balanced: {+ paddingBlock: spacingVars['--spacing-2'],+ paddingInline: spacingVars['--spacing-3'],+ fontSize: textSizeVars['--text-sm'],+ lineHeight: lineHeightVars['--leading-snug'],+ },+ spacious: {+ paddingBlock: spacingVars['--spacing-3'],+ paddingInline: spacingVars['--spacing-4'],+ fontSize: textSizeVars['--text-base'],+ lineHeight: lineHeightVars['--leading-normal'],+ },+});++const descriptionSizeStyles = stylex.create({+ compact: {+ fontSize: textSizeVars['--text-2xs'],+ lineHeight: lineHeightVars['--leading-snug'],+ },+ balanced: {+ fontSize: textSizeVars['--text-xsm'],+ lineHeight: lineHeightVars['--leading-snug'],+ },+ spacious: {+ fontSize: textSizeVars['--text-sm'],+ lineHeight: lineHeightVars['--leading-normal'],+ },+});++// =============================================================================+// Component+// =============================================================================++/**+ * A list item component for use within XDSList.+ *+ * Renders structured content with label, description, start/end content areas.+ * When `onClick` is provided, uses the invisible button pattern for accessibility.+ * When `href` is provided, uses an invisible anchor pattern.+ *+ * @example+ * ```tsx+ * <XDSListItem label="Settings" description="Manage your preferences" />+ * <XDSListItem label="Profile" onClick={() => navigate('/profile')} />+ * <XDSListItem label="Docs" href="/docs" target="_blank" />+ * ```+ */+export const XDSListItem = forwardRef<HTMLLIElement, XDSListItemProps>(+ (+ {+ label,+ description,+ startContent,+ endContent,+ onClick,+ href,+ target,+ isDisabled = false,+ isSelected = false,+ xstyle,+ 'data-testid': testId,+ },+ ref,+ ) => {+ const ctx = useContext(XDSListContext);+ const density = ctx?.density ?? 'balanced';+ const hasDividers = ctx?.hasDividers ?? false;+ const hasMarkers = ctx?.hasMarkers ?? false;+ const isInteractive = onClick != null || href != null;++ const labelAndDescription = (+ <>+ <span {...stylex.props(styles.label)}>{label}</span>+ {description != null && (+ <span+ {...stylex.props(+ styles.description,+ descriptionSizeStyles[density],+ )}>+ {description}+ </span>+ )}+ </>+ );++ const handleContainerClick = (e: React.MouseEvent) => {+ if (isDisabled) return;+ const target = e.target as HTMLElement;+ // Don't fire onClick if click originated from an interactive child+ if (target.closest('button, a, input, select, textarea')) return;+ onClick?.(e);+ };++ const innerContent = (+ <>+ {startContent != null && (+ <span {...stylex.props(styles.startContent)}>{startContent}</span>+ )}++ {href != null ? (+ <a+ href={href}+ target={target}+ aria-disabled={isDisabled || undefined}+ tabIndex={isDisabled ? -1 : undefined}+ {...stylex.props(styles.invisibleAnchor)}>+ {labelAndDescription}+ </a>+ ) : onClick != null ? (+ <button+ type="button"+ onClick={onClick}+ disabled={isDisabled}+ {...stylex.props(styles.invisibleButton)}>+ {labelAndDescription}+ </button>+ ) : (+ <span {...stylex.props(styles.content)}>{labelAndDescription}</span>+ )}++ {endContent != null && (+ <span {...stylex.props(styles.endContent)}>{endContent}</span>+ )}+ </>+ );++ return (+ <li+ ref={ref}+ data-testid={testId}+ aria-selected={isSelected || undefined}+ aria-disabled={isDisabled || undefined}+ {...stylex.props(+ hasMarkers ? styles.itemWithMarker : styles.item,+ densityStyles[density],+ hasDividers ? styles.noRadius : styles.withRadius,+ isInteractive && styles.interactive,+ isInteractive && styles.focusWithinOutline,+ isDisabled && styles.disabled,+ isSelected && styles.selected,+ xstyle,+ )}+ onClick={isInteractive ? handleContainerClick : undefined}>+ {hasMarkers ? (+ <div {...stylex.props(styles.innerWrapper)}>{innerContent}</div>+ ) : (+ innerContent+ )}+ </li>+ );+ },+);++XDSListItem.displayName = 'XDSListItem';diff --git a/packages/core/src/List/index.ts b/packages/core/src/List/index.tsnew file mode 100644index 0000000000..1ebd48cd4d--- /dev/null+++ b/packages/core/src/List/index.ts@@ -0,0 +1,13 @@+/**+ * @file index.ts+ * @input Imports from XDSList.tsx and XDSListItem.tsx+ * @output Exports XDSList, XDSListItem components and their props/types+ * @position Package entry point for List+ *+ * SYNC: When modified, update /packages/core/src/List/README.md+ */++export {XDSList} from './XDSList';+export type {XDSListProps, XDSListStyle, XDSListDensity} from './XDSList';+export {XDSListItem} from './XDSListItem';+export type {XDSListItemProps} from './XDSListItem';diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex f6bd4bce2c..39d7ee5257 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -24,6 +24,7 @@ export * from './RadioList';export * from './Divider';export * from './EmptyState';export * from './Link';+export * from './List';export * from './Slider';export * from './Stack';export * from './Switch';