Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

XDSTreeList (#609)

Andrey Goder118ad3585571
diff --git a/apps/storybook/stories/TreeList.stories.tsx b/apps/storybook/stories/TreeList.stories.tsx
new file mode 100644
index 0000000000..d40b7290e4
--- /dev/null
+++ b/apps/storybook/stories/TreeList.stories.tsx
@@ -0,0 +1,313 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {XDSTreeList} from '@xds/core/TreeList';
+import type {XDSTreeListItemData} from '@xds/core/TreeList';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSBadge} from '@xds/core/Badge';
+import {
+ FolderIcon,
+ DocumentIcon,
+ Cog6ToothIcon,
+ ChevronRightIcon,
+} from '@heroicons/react/24/outline';
+
+const meta: Meta<typeof XDSTreeList> = {
+ title: 'Core/XDSTreeList',
+ component: XDSTreeList,
+ tags: ['autodocs'],
+ argTypes: {
+ density: {
+ control: 'select',
+ options: ['compact', 'balanced', 'spacious'],
+ description: 'Spacing density for tree list items',
+ },
+ branchAlignment: {
+ control: 'select',
+ options: ['center', 'top'],
+ description: 'Where branch lines connect to items',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSTreeList>;
+
+const fileTreeItems: XDSTreeListItemData[] = [
+ {
+ id: 'src',
+ label: 'src',
+ isExpanded: true,
+ children: [
+ {
+ id: 'components',
+ label: 'components',
+ children: [
+ {id: 'button', label: 'Button.tsx'},
+ {id: 'card', label: 'Card.tsx'},
+ {id: 'list', label: 'List.tsx'},
+ ],
+ },
+ {id: 'app', label: 'App.tsx'},
+ {id: 'index', label: 'index.tsx'},
+ ],
+ },
+ {
+ id: 'public',
+ label: 'public',
+ children: [
+ {id: 'favicon', label: 'favicon.ico'},
+ {id: 'index-html', label: 'index.html'},
+ ],
+ },
+ {id: 'pkg', label: 'package.json'},
+ {id: 'readme', label: 'README.md'},
+];
+
+export const Basic: Story = {
+ args: {
+ items: fileTreeItems,
+ },
+};
+
+export const FullyExpanded: Story = {
+ args: {
+ items: [
+ {
+ id: 'src',
+ label: 'src',
+ isExpanded: true,
+ children: [
+ {
+ id: 'components',
+ label: 'components',
+ isExpanded: true,
+ children: [
+ {id: 'button', label: 'Button.tsx'},
+ {id: 'card', label: 'Card.tsx'},
+ {id: 'list', label: 'List.tsx'},
+ ],
+ },
+ {id: 'app', label: 'App.tsx'},
+ {id: 'index', label: 'index.tsx'},
+ ],
+ },
+ {
+ id: 'public',
+ label: 'public',
+ isExpanded: true,
+ children: [
+ {id: 'favicon', label: 'favicon.ico'},
+ {id: 'index-html', label: 'index.html'},
+ ],
+ },
+ {id: 'pkg', label: 'package.json'},
+ {id: 'readme', label: 'README.md'},
+ ],
+ },
+};
+
+export const WithIcons: Story = {
+ args: {
+ items: [
+ {
+ id: 'src',
+ label: 'src',
+ isExpanded: true,
+ startContent: <XDSIcon icon={FolderIcon} />,
+ children: [
+ {
+ id: 'app',
+ label: 'App.tsx',
+ startContent: <XDSIcon icon={DocumentIcon} />,
+ },
+ {
+ id: 'index',
+ label: 'index.tsx',
+ startContent: <XDSIcon icon={DocumentIcon} />,
+ },
+ ],
+ },
+ {
+ id: 'pkg',
+ label: 'package.json',
+ startContent: <XDSIcon icon={DocumentIcon} />,
+ },
+ ],
+ },
+};
+
+export const WithHeader: Story = {
+ args: {
+ items: fileTreeItems,
+ header: <strong>Project Files</strong>,
+ },
+};
+
+export const Compact: Story = {
+ args: {
+ items: [
+ {
+ id: 'src',
+ label: 'src',
+ isExpanded: true,
+ children: [
+ {
+ id: 'components',
+ label: 'components',
+ isExpanded: true,
+ children: [
+ {id: 'button', label: 'Button.tsx'},
+ {id: 'card', label: 'Card.tsx'},
+ {id: 'list', label: 'List.tsx'},
+ ],
+ },
+ {id: 'app', label: 'App.tsx'},
+ {id: 'index', label: 'index.tsx'},
+ ],
+ },
+ {
+ id: 'public',
+ label: 'public',
+ children: [
+ {id: 'favicon', label: 'favicon.ico'},
+ {id: 'index-html', label: 'index.html'},
+ ],
+ },
+ {id: 'pkg', label: 'package.json'},
+ {id: 'readme', label: 'README.md'},
+ ],
+ density: 'compact',
+ },
+};
+
+export const Spacious: Story = {
+ args: {
+ items: fileTreeItems,
+ density: 'spacious',
+ },
+};
+
+export const TopAligned: Story = {
+ args: {
+ items: [
+ {
+ id: 'src',
+ label: 'src',
+ isExpanded: true,
+ children: [
+ {
+ id: 'components',
+ label: 'components',
+ isExpanded: true,
+ children: [
+ {id: 'button', label: 'Button.tsx'},
+ {id: 'card', label: 'Card.tsx'},
+ {id: 'list', label: 'List.tsx'},
+ ],
+ },
+ {id: 'app', label: 'App.tsx'},
+ {id: 'index', label: 'index.tsx'},
+ ],
+ },
+ {
+ id: 'public',
+ label: 'public',
+ children: [
+ {id: 'favicon', label: 'favicon.ico'},
+ {id: 'index-html', label: 'index.html'},
+ ],
+ },
+ {id: 'pkg', label: 'package.json'},
+ {id: 'readme', label: 'README.md'},
+ ],
+ branchAlignment: 'top',
+ },
+};
+
+export const Interactive: Story = {
+ args: {
+ items: [
+ {
+ id: 'settings',
+ label: 'Settings',
+ isExpanded: true,
+ startContent: <XDSIcon icon={Cog6ToothIcon} />,
+ children: [
+ {
+ id: 'general',
+ label: 'General',
+ onClick: () => alert('General settings'),
+ },
+ {
+ id: 'advanced',
+ label: 'Advanced',
+ onClick: () => alert('Advanced settings'),
+ },
+ ],
+ },
+ {
+ id: 'docs',
+ label: 'Documentation',
+ href: '#',
+ endContent: <XDSIcon icon={ChevronRightIcon} />,
+ },
+ ],
+ },
+};
+
+export const WithEndContent: Story = {
+ args: {
+ items: [
+ {
+ id: 'inbox',
+ label: 'Inbox',
+ isExpanded: true,
+ endContent: <XDSBadge label="3" />,
+ children: [
+ {id: 'unread', label: 'Unread', endContent: <XDSBadge label="3" />},
+ {id: 'starred', label: 'Starred'},
+ ],
+ },
+ {id: 'sent', label: 'Sent'},
+ {id: 'drafts', label: 'Drafts', endContent: <XDSBadge label="1" />},
+ ],
+ },
+};
+
+export const DisabledItems: Story = {
+ args: {
+ items: [
+ {
+ id: 'active',
+ label: 'Active Section',
+ isExpanded: true,
+ children: [
+ {id: 'item1', label: 'Available Item', onClick: () => {}},
+ {
+ id: 'item2',
+ label: 'Disabled Item',
+ onClick: () => {},
+ isDisabled: true,
+ },
+ ],
+ },
+ {id: 'disabled-parent', label: 'Disabled Parent', isDisabled: true},
+ ],
+ },
+};
+
+export const SelectedItems: Story = {
+ args: {
+ items: [
+ {
+ id: 'nav',
+ label: 'Navigation',
+ isExpanded: true,
+ children: [
+ {id: 'home', label: 'Home', onClick: () => {}},
+ {id: 'about', label: 'About', onClick: () => {}, isSelected: true},
+ {id: 'contact', label: 'Contact', onClick: () => {}},
+ ],
+ },
+ ],
+ },
+};
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
new file mode 100644
index 0000000000..e60082bb41
--- /dev/null
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -0,0 +1,125 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TreeList',
+ description:
+ 'Data-driven tree list component for rendering hierarchical data with expand/collapse, branch lines, and interactive items. Uses a flat items array with recursive children — no composition, no cloneElement.',
+ features: [
+ 'Data-driven API — items array with recursive children',
+ 'Internal expansion state — seed via isExpanded on each item',
+ 'Branch connector lines with center/top alignment',
+ 'Density variants: compact, balanced, spacious',
+ 'Interactive items via invisible button or anchor pattern',
+ 'Start and end content slots (icon, avatar, badge)',
+ 'Optional header associated via aria-labelledby',
+ 'No context for positional data — computed at render time',
+ ],
+ examples: [
+ {
+ label: 'Basic tree',
+ code: `<XDSTreeList
+ items={[
+ { id: 'src', label: 'src', isExpanded: true, children: [
+ { id: 'app', label: 'App.tsx' },
+ { id: 'index', label: 'index.tsx' },
+ ]},
+ { id: 'pkg', label: 'package.json' },
+ ]}
+/>`,
+ },
+ {
+ label: 'With icons and header',
+ code: `<XDSTreeList
+ header={<strong>Project Files</strong>}
+ density="compact"
+ items={[
+ { id: 'src', label: 'src', isExpanded: true, startContent: <FolderIcon />, children: [
+ { id: 'app', label: 'App.tsx', startContent: <FileIcon /> },
+ ]},
+ ]}
+/>`,
+ },
+ {
+ label: 'Interactive items',
+ code: `<XDSTreeList
+ items={[
+ { id: 'settings', label: 'Settings', onClick: () => navigate('/settings') },
+ { id: 'docs', label: 'Docs', href: '/docs', target: '_blank' },
+ ]}
+/>`,
+ },
+ ],
+ accessibility: [
+ 'Semantic <ul role="tree"> with <li role="treeitem"> elements',
+ '<ul role="group"> for nested children',
+ 'aria-expanded on items with children',
+ 'aria-labelledby links the header element to the tree',
+ 'aria-selected on selected items',
+ 'aria-disabled on disabled items',
+ 'Chevron toggle button with aria-label="Toggle children"',
+ 'Interactive items are keyboard-focusable via Tab',
+ ],
+ theming: {
+ targets: [
+ {className: 'xds-tree-list', visualProps: ['density', 'branchAlignment']},
+ ],
+ },
+ notes: [
+ 'Data-driven pattern: Unlike XDSList which uses children composition, XDSTreeList accepts an items array. This avoids cloneElement and enables the component to compute positional data (nestedLevel, isLast, ancestorsIsLast) at render time.',
+ 'Expansion control: Expansion state is managed internally. Seed initial state by setting isExpanded: true on individual items in the data.',
+ 'Performance: React reconciliation via key={id} means expanding a node only causes DOM updates in that subtree. Siblings with stable keys and same props are skipped by React.',
+ ],
+ components: [
+ {
+ name: 'XDSTreeList',
+ description:
+ 'Tree list container. Accepts items data and rendering configuration. Expansion state is managed internally.',
+ examples: [
+ {
+ label: 'Basic tree',
+ code: `<XDSTreeList
+ items={[
+ { id: 'src', label: 'src', isExpanded: true, children: [
+ { id: 'app', label: 'App.tsx' },
+ ]},
+ { id: 'pkg', label: 'package.json' },
+ ]}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'items',
+ type: 'XDSTreeListItemData[]',
+ description:
+ 'Recursive tree item data. Each item has id, label, optional children array, and optional isExpanded boolean for initial state.',
+ required: true,
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Spacing density for items.',
+ default: "'balanced'",
+ },
+ {
+ name: 'branchAlignment',
+ type: "'center' | 'top'",
+ description: 'Where branch lines connect to items.',
+ default: "'center'",
+ },
+ {
+ name: 'header',
+ type: 'ReactNode',
+ description:
+ 'Header content, associated with the tree via aria-labelledby.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/TreeList/XDSTreeList.test.tsx b/packages/core/src/TreeList/XDSTreeList.test.tsx
new file mode 100644
index 0000000000..61c7ab558f
--- /dev/null
+++ b/packages/core/src/TreeList/XDSTreeList.test.tsx
@@ -0,0 +1,327 @@
+/**
+ * @file XDSTreeList.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSTreeList
+ * @output Unit tests for XDSTreeList component
+ * @position Testing; validates XDSTreeList.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 {XDSTreeList} from './XDSTreeList';
+import type {XDSTreeListItemData} from './XDSTreeListTypes';
+
+const simpleItems: XDSTreeListItemData[] = [
+ {id: 'a', label: 'Item A'},
+ {id: 'b', label: 'Item B'},
+];
+
+const nestedItems: XDSTreeListItemData[] = [
+ {
+ id: 'parent',
+ label: 'Parent',
+ children: [
+ {id: 'child-1', label: 'Child 1'},
+ {id: 'child-2', label: 'Child 2'},
+ ],
+ },
+ {id: 'sibling', label: 'Sibling'},
+];
+
+const nestedItemsExpanded: XDSTreeListItemData[] = [
+ {
+ id: 'parent',
+ label: 'Parent',
+ isExpanded: true,
+ children: [
+ {id: 'child-1', label: 'Child 1'},
+ {id: 'child-2', label: 'Child 2'},
+ ],
+ },
+ {id: 'sibling', label: 'Sibling'},
+];
+
+const deepItems: XDSTreeListItemData[] = [
+ {
+ id: 'root',
+ label: 'Root',
+ isExpanded: true,
+ children: [
+ {
+ id: 'mid',
+ label: 'Mid',
+ isExpanded: true,
+ children: [{id: 'leaf', label: 'Leaf'}],
+ },
+ ],
+ },
+];
+
+describe('XDSTreeList', () => {
+ // ===========================================================================
+ // Basic rendering
+ // ===========================================================================
+
+ it('renders items', () => {
+ render(<XDSTreeList items={simpleItems} />);
+ expect(screen.getByText('Item A')).toBeInTheDocument();
+ expect(screen.getByText('Item B')).toBeInTheDocument();
+ });
+
+ it('renders with data-testid', () => {
+ render(<XDSTreeList items={simpleItems} data-testid="tree" />);
+ expect(screen.getByTestId('tree')).toBeInTheDocument();
+ });
+
+ it('renders description text', () => {
+ const items: XDSTreeListItemData[] = [
+ {id: 'a', label: 'Label', description: 'Description text'},
+ ];
+ render(<XDSTreeList items={items} />);
+ expect(screen.getByText('Description text')).toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Semantic HTML
+ // ===========================================================================
+
+ it('renders a tree role on the list', () => {
+ render(<XDSTreeList items={simpleItems} />);
+ expect(screen.getByRole('tree')).toBeInTheDocument();
+ });
+
+ it('renders treeitem role on items', () => {
+ render(<XDSTreeList items={simpleItems} />);
+ const treeitems = screen.getAllByRole('treeitem');
+ expect(treeitems).toHaveLength(2);
+ });
+
+ it('renders items as <li> elements', () => {
+ const {container} = render(<XDSTreeList items={simpleItems} />);
+ const items = container.querySelectorAll('li');
+ expect(items).toHaveLength(2);
+ });
+
+ // ===========================================================================
+ // Header with aria-labelledby
+ // ===========================================================================
+
+ it('renders header and associates via aria-labelledby', () => {
+ render(<XDSTreeList items={simpleItems} header={<span>File Tree</span>} />);
+ expect(screen.getByText('File Tree')).toBeInTheDocument();
+ const tree = screen.getByRole('tree');
+ const headerId = tree.getAttribute('aria-labelledby');
+ expect(headerId).toBeTruthy();
+ const headerEl = document.getElementById(headerId!);
+ expect(headerEl?.textContent).toBe('File Tree');
+ });
+
+ it('does not render aria-labelledby when no header', () => {
+ render(<XDSTreeList items={simpleItems} />);
+ const tree = screen.getByRole('tree');
+ expect(tree).not.toHaveAttribute('aria-labelledby');
+ });
+
+ // ===========================================================================
+ // Expansion (internal state)
+ // ===========================================================================
+
+ it('does not render children by default', () => {
+ render(<XDSTreeList items={nestedItems} />);
+ expect(screen.getByText('Parent')).toBeInTheDocument();
+ expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
+ });
+
+ it('renders children when item has isExpanded: true', () => {
+ render(<XDSTreeList items={nestedItemsExpanded} />);
+ expect(screen.getByText('Child 1')).toBeInTheDocument();
+ expect(screen.getByText('Child 2')).toBeInTheDocument();
+ });
+
+ it('sets aria-expanded on items with children', () => {
+ render(<XDSTreeList items={nestedItemsExpanded} />);
+ const parent = screen.getByText('Parent').closest('li');
+ expect(parent).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('sets aria-expanded=false on collapsed items with children', () => {
+ render(<XDSTreeList items={nestedItems} />);
+ const parent = screen.getByText('Parent').closest('li');
+ expect(parent).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('does not set aria-expanded on leaf items', () => {
+ render(<XDSTreeList items={simpleItems} />);
+ const item = screen.getByText('Item A').closest('li');
+ expect(item).not.toHaveAttribute('aria-expanded');
+ });
+
+ it('renders group role for nested children', () => {
+ render(<XDSTreeList items={nestedItemsExpanded} />);
+ const groups = document.querySelectorAll('[role="group"]');
+ expect(groups.length).toBeGreaterThanOrEqual(1);
+ });
+
+ it('expands a collapsed item when clicked', async () => {
+ const user = userEvent.setup();
+ render(<XDSTreeList items={nestedItems} />);
+ expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
+ await user.click(screen.getByText('Parent'));
+ expect(screen.getByText('Child 1')).toBeInTheDocument();
+ });
+
+ it('collapses an expanded item when clicked', async () => {
+ const user = userEvent.setup();
+ render(<XDSTreeList items={nestedItemsExpanded} />);
+ expect(screen.getByText('Child 1')).toBeInTheDocument();
+ await user.click(screen.getByText('Parent'));
+ expect(screen.queryByText('Child 1')).not.toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Deep nesting
+ // ===========================================================================
+
+ it('renders deeply nested items when all expanded', () => {
+ render(<XDSTreeList items={deepItems} />);
+ expect(screen.getByText('Root')).toBeInTheDocument();
+ expect(screen.getByText('Mid')).toBeInTheDocument();
+ expect(screen.getByText('Leaf')).toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Interactive items
+ // ===========================================================================
+
+ it('renders an invisible button when onClick is provided', () => {
+ const items: XDSTreeListItemData[] = [
+ {id: 'a', label: 'Clickable', onClick: () => {}},
+ ];
+ const {container} = render(<XDSTreeList items={items} />);
+ 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();
+ const items: XDSTreeListItemData[] = [
+ {id: 'a', label: 'Clickable', onClick},
+ ];
+ render(<XDSTreeList items={items} />);
+ await user.click(screen.getByRole('button'));
+ expect(onClick).toHaveBeenCalledTimes(1);
+ });
+
+ it('renders an invisible anchor when href is provided', () => {
+ const items: XDSTreeListItemData[] = [
+ {id: 'a', label: 'Link', href: '/docs'},
+ ];
+ const {container} = render(<XDSTreeList items={items} />);
+ const anchor = container.querySelector('a');
+ expect(anchor).toBeInTheDocument();
+ expect(anchor).toHaveAttribute('href', '/docs');
+ });
+
+ it('does not render button or anchor for static items', () => {
+ const {container} = render(<XDSTreeList items={simpleItems} />);
+ expect(container.querySelector('button')).not.toBeInTheDocument();
+ expect(container.querySelector('a')).not.toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Disabled state
+ // ===========================================================================
+
+ it('applies aria-disabled when isDisabled', () => {
+ const items: XDSTreeListItemData[] = [
+ {id: 'a', label: 'Disabled', isDisabled: true},
+ ];
+ render(<XDSTreeList items={items} />);
+ const li = screen.getByText('Disabled').closest('li');
+ expect(li).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ // ===========================================================================
+ // Selected state
+ // ===========================================================================
+
+ it('applies aria-selected when isSelected', () => {
+ const items: XDSTreeListItemData[] = [
+ {id: 'a', label: 'Selected', isSelected: true},
+ ];
+ render(<XDSTreeList items={items} />);
+ const li = screen.getByText('Selected').closest('li');
+ expect(li).toHaveAttribute('aria-selected', 'true');
+ });
+
+ it('does not apply aria-selected when not selected', () => {
+ render(<XDSTreeList items={simpleItems} />);
+ const li = screen.getByText('Item A').closest('li');
+ expect(li).not.toHaveAttribute('aria-selected');
+ });
+
+ // ===========================================================================
+ // startContent and endContent
+ // ===========================================================================
+
+ it('renders startContent', () => {
+ const items: XDSTreeListItemData[] = [
+ {
+ id: 'a',
+ label: 'With Icon',
+ startContent: <span data-testid="icon">★</span>,
+ },
+ ];
+ render(<XDSTreeList items={items} />);
+ expect(screen.getByTestId('icon')).toBeInTheDocument();
+ });
+
+ it('renders endContent', () => {
+ const items: XDSTreeListItemData[] = [
+ {
+ id: 'a',
+ label: 'With Badge',
+ endContent: <span data-testid="badge">3</span>,
+ },
+ ];
+ render(<XDSTreeList items={items} />);
+ expect(screen.getByTestId('badge')).toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Density
+ // ===========================================================================
+
+ it('renders with compact density', () => {
+ render(<XDSTreeList items={simpleItems} density="compact" />);
+ expect(screen.getByRole('tree')).toBeInTheDocument();
+ });
+
+ it('renders with spacious density', () => {
+ render(<XDSTreeList items={simpleItems} density="spacious" />);
+ expect(screen.getByRole('tree')).toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // Branch alignment
+ // ===========================================================================
+
+ it('renders with top branch alignment', () => {
+ render(<XDSTreeList items={nestedItemsExpanded} branchAlignment="top" />);
+ expect(screen.getByText('Child 1')).toBeInTheDocument();
+ });
+
+ // ===========================================================================
+ // xds class name
+ // ===========================================================================
+
+ it('applies xds-tree-list class name', () => {
+ render(<XDSTreeList items={simpleItems} data-testid="tree" />);
+ const root = screen.getByTestId('tree');
+ expect(root.className).toContain('xds-tree-list');
+ });
+});
diff --git a/packages/core/src/TreeList/XDSTreeList.tsx b/packages/core/src/TreeList/XDSTreeList.tsx
new file mode 100644
index 0000000000..9fccdccd2c
--- /dev/null
+++ b/packages/core/src/TreeList/XDSTreeList.tsx
@@ -0,0 +1,258 @@
+/**
+ * @file XDSTreeList.tsx
+ * @input Uses React, StyleX, theme tokens, XDSTreeListItem, XDSTreeListTypes
+ * @output Exports XDSTreeList component, XDSTreeListProps type
+ * @position Core implementation; consumed by index.ts
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/TreeList/TreeList.doc.mjs
+ * - /packages/core/src/TreeList/index.ts
+ * - /apps/storybook/stories/TreeList.stories.tsx
+ */
+
+'use client';
+
+import {useId, useState, useCallback, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {spacingVars} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
+import {XDSTreeListItem} from './XDSTreeListItem';
+import type {
+ XDSTreeListItemData,
+ XDSTreeListDensity,
+ XDSTreeListBranchAlignment,
+} from './XDSTreeListTypes';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export {
+ type XDSTreeListDensity,
+ type XDSTreeListBranchAlignment,
+} from './XDSTreeListTypes';
+
+export interface XDSTreeListProps {
+ /** Ref forwarded to the root element */
+ ref?: React.Ref<HTMLDivElement>;
+
+ /**
+ * Tree items as a recursive data structure.
+ * Each item can have nested `children` arrays.
+ */
+ items: XDSTreeListItemData[];
+
+ /**
+ * Spacing density for tree list items.
+ * - 'compact': Tighter spacing for dense UIs
+ * - 'balanced': Standard spacing
+ * - 'spacious': Extra spacing for readability
+ * @default 'balanced'
+ */
+ density?: XDSTreeListDensity;
+
+ /**
+ * Controls where tree branch lines connect to items.
+ * - 'center': Lines terminate at vertical center of items
+ * - 'top': Lines terminate at the top of items
+ * @default 'center'
+ */
+ branchAlignment?: XDSTreeListBranchAlignment;
+
+ /**
+ * Header content rendered above the tree list.
+ * Semantically associated via aria-labelledby.
+ */
+ header?: ReactNode;
+
+ /**
+ * StyleX styles created via `stylex.create()`. Merged with the component's
+ * base styles inside a single `stylex.props()` call for optimal deduplication.
+ */
+ xstyle?: StyleXStyles;
+
+ /**
+ * CSS class name(s) appended to the root element.
+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
+ */
+ className?: string;
+
+ /**
+ * Inline styles to apply to the root element. Spread after StyleX
+ * inline styles, so these values take priority.
+ */
+ style?: React.CSSProperties;
+
+ /**
+ * Test ID for testing frameworks.
+ */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ root: {
+ position: 'relative',
+ },
+ list: {
+ margin: 0,
+ padding: 0,
+ listStyleType: 'none',
+ },
+ header: {
+ marginBottom: spacingVars['--spacing-2'],
+ },
+});
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Recursively collect IDs of items marked as `isExpanded`. */
+function collectExpandedKeys(items: XDSTreeListItemData[]): string[] {
+ const keys: string[] = [];
+ for (const item of items) {
+ if (item.isExpanded && item.children != null && item.children.length > 0) {
+ keys.push(item.id);
+ }
+ if (item.children != null) {
+ keys.push(...collectExpandedKeys(item.children));
+ }
+ }
+ return keys;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * A data-driven tree list component for rendering hierarchical data.
+ *
+ * Accepts an `items` array of recursive config objects. Expansion state is
+ * managed internally — seed initial state by setting `isExpanded: true` on
+ * individual items in the data.
+ * Positional data (nestedLevel, isLast, ancestorsIsLast) is computed during
+ * rendering — no context, no cloneElement, no force-update mechanism.
+ *
+ * @example
+ * ```
+ * <XDSTreeList
+ * items={[
+ * { id: 'src', label: 'src', isExpanded: true, children: [
+ * { id: 'app', label: 'App.tsx' },
+ * { id: 'index', label: 'index.tsx' },
+ * ]},
+ * { id: 'pkg', label: 'package.json' },
+ * ]}
+ * />
+ * ```
+ */
+export function XDSTreeList({
+ items,
+ density = 'balanced',
+ branchAlignment = 'center',
+ header,
+ xstyle,
+ className,
+ style,
+ 'data-testid': testId,
+ ref,
+}: XDSTreeListProps) {
+ const headerId = useId();
+ const [expandedKeys, setExpandedKeys] = useState(
+ () => new Set(collectExpandedKeys(items)),
+ );
+
+ const handleToggle = useCallback((id: string) => {
+ setExpandedKeys(prev => {
+ const next = new Set(prev);
+ if (next.has(id)) {
+ next.delete(id);
+ } else {
+ next.add(id);
+ }
+ return next;
+ });
+ }, []);
+
+ function renderItems(
+ items: XDSTreeListItemData[],
+ nestedLevel: number,
+ ancestorsIsLast: ReadonlyArray<boolean>,
+ ): ReactNode {
+ return items.map((item, index) => {
+ const isLast = index === items.length - 1;
+ const isExpanded = expandedKeys.has(item.id);
+ const hasChildren = item.children != null && item.children.length > 0;
+
+ const ancestorsIsLastForChildren = hasChildren
+ ? [...ancestorsIsLast, isLast]
+ : ancestorsIsLast;
+
+ const renderedChildren =
+ isExpanded && hasChildren
+ ? renderItems(
+ item.children!,
+ nestedLevel + 1,
+ ancestorsIsLastForChildren,
+ )
+ : undefined;
+
+ return (
+ <XDSTreeListItem
+ key={item.id}
+ id={item.id}
+ label={item.label}
+ description={item.description}
+ startContent={item.startContent}
+ endContent={item.endContent}
+ hasChildren={hasChildren}
+ onClick={item.onClick}
+ href={item.href}
+ target={item.target}
+ isDisabled={item.isDisabled}
+ isSelected={item.isSelected}
+ nestedLevel={nestedLevel}
+ isLast={isLast}
+ ancestorsIsLast={ancestorsIsLast}
+ isExpanded={isExpanded}
+ onToggle={handleToggle}
+ density={density}
+ branchAlignment={branchAlignment}
+ renderedChildren={renderedChildren}
+ />
+ );
+ });
+ }
+
+ return (
+ <div
+ ref={ref}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('tree-list', {density, branchAlignment}),
+ stylex.props(styles.root, xstyle),
+ className,
+ style,
+ )}>
+ {header != null && (
+ <div id={headerId} {...stylex.props(styles.header)}>
+ {header}
+ </div>
+ )}
+ <ul
+ role="tree"
+ aria-labelledby={header != null ? headerId : undefined}
+ {...stylex.props(styles.list)}>
+ {renderItems(items, 0, [])}
+ </ul>
+ </div>
+ );
+}
+
+XDSTreeList.displayName = 'XDSTreeList';
diff --git a/packages/core/src/TreeList/XDSTreeListBranches.tsx b/packages/core/src/TreeList/XDSTreeListBranches.tsx
new file mode 100644
index 0000000000..f53855b268
--- /dev/null
+++ b/packages/core/src/TreeList/XDSTreeListBranches.tsx
@@ -0,0 +1,168 @@
+/**
+ * @file XDSTreeListBranches.tsx
+ * @input Uses React, StyleX, theme tokens
+ * @output Exports XDSTreeListBranches component (internal)
+ * @position Presentational component for tree connector lines; consumed by XDSTreeListItem.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/TreeList/XDSTreeListItem.tsx
+ */
+
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import type {
+ XDSTreeListBranchAlignment,
+ XDSTreeListDensity,
+} from './XDSTreeListTypes';
+
+const LINE_WIDTH = 2;
+
+// Content row heights per density (paddingBlock * 2 + line-height).
+// These must stay in sync with densityStyles in XDSTreeListItem.tsx.
+const LABEL_ROW_HEIGHT_COMPACT = 28;
+const LABEL_ROW_HEIGHT_BALANCED = 36;
+const LABEL_ROW_HEIGHT_SPACIOUS = 48;
+
+const styles = stylex.create({
+ container: {
+ height: '100%',
+ position: 'absolute',
+ width: 20,
+ },
+ verticalLine: {
+ borderRadius: 1,
+ left: 0,
+ margin: 'auto',
+ position: 'absolute',
+ right: 0,
+ width: LINE_WIDTH,
+ backgroundColor: colorVars['--color-divider-emphasized'],
+ },
+ verticalFull: {
+ height: 'calc(100% + 1px)',
+ },
+ horizontalLine: {
+ borderRadius: 1,
+ height: LINE_WIDTH,
+ left: '50%',
+ position: 'absolute',
+ width: '50%',
+ backgroundColor: colorVars['--color-divider-emphasized'],
+ },
+ horizontalLineFull: {
+ width: '100%',
+ },
+});
+
+// Vertical line from top to chevron center of content row (L-connector for last child)
+const verticalToCenter = stylex.create({
+ compact: {height: LABEL_ROW_HEIGHT_COMPACT / 2 - 2 + LINE_WIDTH},
+ balanced: {height: LABEL_ROW_HEIGHT_BALANCED / 2 - 2 + LINE_WIDTH},
+ spacious: {height: LABEL_ROW_HEIGHT_SPACIOUS / 2 - 2 + LINE_WIDTH},
+});
+
+// Horizontal line positioned to align with chevron center
+const horizontalAtCenter = stylex.create({
+ compact: {top: LABEL_ROW_HEIGHT_COMPACT / 2 - 2},
+ balanced: {top: LABEL_ROW_HEIGHT_BALANCED / 2 - 2},
+ spacious: {top: LABEL_ROW_HEIGHT_SPACIOUS / 2 - 2},
+});
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface XDSTreeListBranchesProps {
+ ancestorsIsLast: ReadonlyArray<boolean>;
+ branchAlignment: XDSTreeListBranchAlignment;
+ density: XDSTreeListDensity;
+ hasChildren: boolean;
+ isLast: boolean;
+ levelIndent: number;
+ marginLeft: number;
+ nestedLevel: number;
+}
+
+interface BranchItemProps {
+ density: XDSTreeListDensity;
+ hasChildren?: boolean;
+ leftPosition: number;
+ type: 'parentToParentSibling' | 'parentToChildAndSibling' | 'parentToChild';
+}
+
+// =============================================================================
+// Components
+// =============================================================================
+
+function TreeListBranchItem({
+ density,
+ hasChildren,
+ leftPosition,
+ type,
+}: BranchItemProps) {
+ return (
+ <div {...stylex.props(styles.container)} style={{left: leftPosition}}>
+ <div
+ {...stylex.props(
+ styles.verticalLine,
+ type === 'parentToParentSibling' || type === 'parentToChildAndSibling'
+ ? styles.verticalFull
+ : verticalToCenter[density],
+ )}
+ />
+ {(type === 'parentToChildAndSibling' || type === 'parentToChild') && (
+ <div
+ {...stylex.props(
+ styles.horizontalLine,
+ hasChildren === false && styles.horizontalLineFull,
+ horizontalAtCenter[density],
+ )}
+ />
+ )}
+ </div>
+ );
+}
+
+/**
+ * Renders lines showing parent-child relationships in the tree.
+ *
+ * Line types:
+ * 1. Pass-through vertical lines for non-last ancestors
+ * 2. Parent-to-child connector (L-shaped for last child, T-shaped otherwise)
+ */
+export function XDSTreeListBranches({
+ ancestorsIsLast,
+ branchAlignment: _branchAlignment,
+ density,
+ hasChildren,
+ isLast,
+ levelIndent,
+ marginLeft,
+ nestedLevel,
+}: XDSTreeListBranchesProps) {
+ return (
+ <>
+ {ancestorsIsLast.map(
+ (ancestorIsLast, level) =>
+ !ancestorIsLast && (
+ <TreeListBranchItem
+ key={level}
+ density={density}
+ leftPosition={marginLeft + level * levelIndent}
+ type="parentToParentSibling"
+ />
+ ),
+ )}
+ {nestedLevel > 0 && (
+ <TreeListBranchItem
+ density={density}
+ hasChildren={hasChildren}
+ leftPosition={marginLeft + (nestedLevel - 1) * levelIndent}
+ type={isLast ? 'parentToChild' : 'parentToChildAndSibling'}
+ />
+ )}
+ </>
+ );
+}
diff --git a/packages/core/src/TreeList/XDSTreeListItem.tsx b/packages/core/src/TreeList/XDSTreeListItem.tsx
new file mode 100644
index 0000000000..d8b5aef67b
--- /dev/null
+++ b/packages/core/src/TreeList/XDSTreeListItem.tsx
@@ -0,0 +1,440 @@
+/**
+ * @file XDSTreeListItem.tsx
+ * @input Uses React, StyleX, theme tokens, XDSTreeListBranches
+ * @output Exports XDSTreeListItem component (internal, not publicly exported)
+ * @position Internal implementation; consumed by XDSTreeList.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/TreeList/TreeList.doc.mjs
+ * - /packages/core/src/TreeList/XDSTreeList.tsx
+ */
+
+'use client';
+
+import {useId, useMemo, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+ colorVars,
+ radiusVars,
+ spacingVars,
+ textSizeVars,
+ lineHeightVars,
+ transitionVars,
+} from '../theme/tokens.stylex';
+import {getIcon} from '../Icon/globalIconRegistry';
+import {XDSTreeListBranches} from './XDSTreeListBranches';
+import type {
+ XDSTreeListBranchAlignment,
+ XDSTreeListDensity,
+} from './XDSTreeListTypes';
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const INDENT = 20;
+const CHEVRON_SIZE = 16;
+const CHEVRON_MARGIN = 8;
+const BRANCH_MARGIN_LEFT = 9;
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ wrapper: {
+ listStyleType: 'none',
+ margin: 0,
+ padding: 0,
+ position: 'relative',
+ width: '100%',
+ },
+ childGroup: {
+ margin: 0,
+ padding: 0,
+ listStyleType: 'none',
+ },
+ treeBranches: {
+ paddingInlineStart: BRANCH_MARGIN_LEFT,
+ },
+ contentWrapper: {
+ borderRadius: radiusVars['--radius-content'],
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ outline: 'none',
+ overflow: 'hidden',
+ position: 'relative',
+ boxSizing: 'border-box',
+ textAlign: 'start',
+ },
+ interactive: {
+ cursor: 'pointer',
+ transitionProperty: 'background-image',
+ transitionDuration: transitionVars['--transition-fast'],
+ backgroundImage: {
+ default: null,
+ ':hover': {
+ '@media (hover: 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',
+ },
+ chevronContainer: {
+ flexShrink: 0,
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: CHEVRON_SIZE,
+ height: CHEVRON_SIZE,
+ fontSize: CHEVRON_SIZE,
+ cursor: 'pointer',
+ border: 'none',
+ background: 'none',
+ padding: 0,
+ color: colorVars['--color-icon-secondary'],
+ borderRadius: radiusVars['--radius-content'],
+ },
+ chevronButton: {
+ all: 'unset',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: CHEVRON_SIZE,
+ height: CHEVRON_SIZE,
+ fontSize: CHEVRON_SIZE,
+ cursor: 'pointer',
+ color: colorVars['--color-icon-secondary'],
+ borderRadius: radiusVars['--radius-content'],
+ },
+ chevronSvg: {
+ display: 'flex',
+ transitionProperty: 'transform',
+ transitionDuration: transitionVars['--transition-fast'],
+ },
+ chevronExpanded: {
+ transform: 'rotate(90deg)',
+ },
+ chevronCollapsed: {
+ transform: 'rotate(0deg)',
+ },
+});
+
+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'],
+ },
+});
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface XDSTreeListItemInternalProps {
+ id: string;
+ label: React.ReactNode;
+ description?: string;
+ startContent?: React.ReactNode;
+ endContent?: React.ReactNode;
+ onClick?: (e: React.MouseEvent) => void;
+ href?: string;
+ target?: string;
+ isDisabled?: boolean;
+ isSelected?: boolean;
+ hasChildren: boolean;
+ nestedLevel: number;
+ isLast: boolean;
+ ancestorsIsLast: ReadonlyArray<boolean>;
+ isExpanded: boolean;
+ onToggle?: (id: string) => void;
+ density: XDSTreeListDensity;
+ branchAlignment: XDSTreeListBranchAlignment;
+ /** Pre-rendered children subtree (rendered by the parent recursion) */
+ renderedChildren?: ReactNode;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export function XDSTreeListItem({
+ id,
+ label,
+ description,
+ startContent,
+ endContent,
+ onClick,
+ href,
+ target,
+ isDisabled = false,
+ isSelected = false,
+ hasChildren,
+ nestedLevel,
+ isLast,
+ ancestorsIsLast,
+ isExpanded,
+ onToggle,
+ density,
+ branchAlignment,
+ renderedChildren,
+}: XDSTreeListItemInternalProps) {
+ const labelId = useId();
+ const descriptionId = useId();
+ const isInteractive = onClick != null || href != null;
+
+ const handleToggle = useMemo(
+ () =>
+ hasChildren && onToggle != null
+ ? (e: React.MouseEvent) => {
+ e.stopPropagation();
+ onToggle(id);
+ }
+ : undefined,
+ [hasChildren, onToggle, id],
+ );
+
+ const handleClick = useMemo(() => {
+ if (onClick != null || (hasChildren && onToggle != null)) {
+ return (e: React.MouseEvent) => {
+ if (isDisabled) return;
+ const el = e.target as HTMLElement;
+ if (el.closest('button, a, input, select, textarea')) return;
+ if (onClick != null) {
+ onClick(e);
+ } else if (hasChildren && onToggle != null) {
+ onToggle(id);
+ }
+ };
+ }
+ return undefined;
+ }, [onClick, hasChildren, onToggle, id, isDisabled]);
+
+ const computedMarginLeft = hasChildren
+ ? nestedLevel * INDENT
+ : nestedLevel * INDENT +
+ CHEVRON_SIZE +
+ (startContent != null ? 0 : CHEVRON_MARGIN);
+
+ const labelAndDescription = (
+ <>
+ <span id={labelId} {...stylex.props(styles.label)}>
+ {label}
+ </span>
+ {description != null && (
+ <span
+ id={descriptionId}
+ {...stylex.props(styles.description, descriptionSizeStyles[density])}>
+ {description}
+ </span>
+ )}
+ </>
+ );
+
+ const chevronIcon = (
+ <span
+ {...stylex.props(
+ styles.chevronSvg,
+ isExpanded ? styles.chevronExpanded : styles.chevronCollapsed,
+ )}>
+ {getIcon('chevronRight')}
+ </span>
+ );
+
+ const chevron = hasChildren ? (
+ handleClick != null && onClick != null ? (
+ // Separate toggle button when item has its own onClick
+ <button
+ type="button"
+ aria-expanded={isExpanded}
+ aria-label="Toggle children"
+ onClick={handleToggle}
+ {...stylex.props(styles.chevronButton)}>
+ {chevronIcon}
+ </button>
+ ) : (
+ // Non-interactive chevron when clicking the row toggles
+ <span {...stylex.props(styles.chevronContainer)}>{chevronIcon}</span>
+ )
+ ) : null;
+
+ const innerContent = (
+ <>
+ {chevron}
+ {startContent != null && (
+ <span {...stylex.props(styles.startContent)}>{startContent}</span>
+ )}
+ {href != null ? (
+ <a
+ href={href}
+ target={target}
+ aria-disabled={isDisabled || undefined}
+ aria-labelledby={labelId}
+ aria-describedby={description != null ? descriptionId : undefined}
+ tabIndex={isDisabled ? -1 : undefined}
+ {...stylex.props(styles.invisibleAnchor)}>
+ {labelAndDescription}
+ </a>
+ ) : onClick != null ? (
+ <button
+ type="button"
+ onClick={onClick}
+ disabled={isDisabled}
+ aria-labelledby={labelId}
+ aria-describedby={description != null ? descriptionId : undefined}
+ {...stylex.props(styles.invisibleButton)}>
+ {labelAndDescription}
+ </button>
+ ) : (
+ <span {...stylex.props(styles.content)}>{labelAndDescription}</span>
+ )}
+ {endContent != null && (
+ <span {...stylex.props(styles.endContent)}>{endContent}</span>
+ )}
+ </>
+ );
+
+ return (
+ <li
+ role="treeitem"
+ aria-expanded={hasChildren ? isExpanded : undefined}
+ aria-selected={isSelected || undefined}
+ aria-disabled={isDisabled || undefined}
+ {...stylex.props(styles.wrapper)}>
+ <div {...stylex.props(styles.treeBranches)}>
+ <XDSTreeListBranches
+ ancestorsIsLast={ancestorsIsLast}
+ branchAlignment={branchAlignment}
+ density={density}
+ hasChildren={hasChildren}
+ isLast={isLast}
+ levelIndent={INDENT}
+ marginLeft={BRANCH_MARGIN_LEFT}
+ nestedLevel={nestedLevel}
+ />
+ </div>
+ <div
+ {...stylex.props(
+ styles.contentWrapper,
+ densityStyles[density],
+ (isInteractive || (hasChildren && onClick == null)) &&
+ styles.interactive,
+ (isInteractive || (hasChildren && onClick == null)) &&
+ styles.focusWithinOutline,
+ isDisabled && styles.disabled,
+ isSelected && styles.selected,
+ )}
+ style={{marginLeft: computedMarginLeft}}
+ onClick={handleClick}>
+ {innerContent}
+ </div>
+ {isExpanded && renderedChildren != null && (
+ <ul role="group" {...stylex.props(styles.childGroup)}>
+ {renderedChildren}
+ </ul>
+ )}
+ </li>
+ );
+}
+
+XDSTreeListItem.displayName = 'XDSTreeListItem';
diff --git a/packages/core/src/TreeList/XDSTreeListTypes.ts b/packages/core/src/TreeList/XDSTreeListTypes.ts
new file mode 100644
index 0000000000..3c97a196e0
--- /dev/null
+++ b/packages/core/src/TreeList/XDSTreeListTypes.ts
@@ -0,0 +1,57 @@
+/**
+ * @file XDSTreeListTypes.ts
+ * @input Uses React types
+ * @output Exports XDSTreeListItemData, XDSTreeListDensity types
+ * @position Type definitions; consumed by XDSTreeList.tsx, XDSTreeListItem.tsx, index.ts
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/TreeList/TreeList.doc.mjs
+ * - /packages/core/src/TreeList/index.ts
+ */
+
+import type {ReactNode} from 'react';
+
+/** Spacing density for tree list items. */
+export type XDSTreeListDensity = 'compact' | 'balanced' | 'spacious';
+
+/** Branch alignment mode for tree connector lines. */
+export type XDSTreeListBranchAlignment = 'center' | 'top';
+
+/** Recursive item configuration for XDSTreeList. */
+export interface XDSTreeListItemData {
+ /** Unique identifier for the item. Used as React key and for expansion tracking. */
+ id: string;
+
+ /** Primary text label for the item. */
+ label: ReactNode;
+
+ /** Secondary description text below the label. */
+ description?: string;
+
+ /** Content rendered before the label (icon, avatar, checkbox). */
+ startContent?: ReactNode;
+
+ /** Content rendered after the label (badge, action button). */
+ endContent?: ReactNode;
+
+ /** Nested child items. When present, the item renders an expand/collapse toggle. */
+ children?: XDSTreeListItemData[];
+
+ /** Click handler for the item. */
+ onClick?: (e: React.MouseEvent) => void;
+
+ /** URL for link items. Renders an invisible anchor element. */
+ href?: string;
+
+ /** Link target (e.g., '_blank'). Only used with href. */
+ target?: string;
+
+ /** Whether the item is disabled. */
+ isDisabled?: boolean;
+
+ /** Whether the item is currently selected. */
+ isSelected?: boolean;
+
+ /** Whether the item is initially expanded. Only meaningful for items with children. */
+ isExpanded?: boolean;
+}
diff --git a/packages/core/src/TreeList/index.ts b/packages/core/src/TreeList/index.ts
new file mode 100644
index 0000000000..6b7c3ab7ab
--- /dev/null
+++ b/packages/core/src/TreeList/index.ts
@@ -0,0 +1,16 @@
+/**
+ * @file index.ts
+ * @input Imports from XDSTreeList.tsx and XDSTreeListTypes.ts
+ * @output Exports XDSTreeList component and its types
+ * @position Package entry point for TreeList
+ *
+ * SYNC: When modified, update /packages/core/src/TreeList/TreeList.doc.mjs
+ */
+
+export {XDSTreeList} from './XDSTreeList';
+export type {
+ XDSTreeListProps,
+ XDSTreeListDensity,
+ XDSTreeListBranchAlignment,
+} from './XDSTreeList';
+export type {XDSTreeListItemData} from './XDSTreeListTypes';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index f8aed59295..ef0ddbdc23 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -49,6 +49,7 @@ export * from './Token';
export * from './Typeahead';
export * from './Tokenizer';
export * from './PowerSearch';
+export * from './TreeList';
// Keyboard shortcut display
export * from './Kbd';