An open source design system that's fully customizable and agent ready
TypeScript
feat(Toolbar): add XDSToolbar component #1006 (#1016)
Cindy Zhang70e5abebecca
diff --git a/.toolbar-patch.patch b/.toolbar-patch.patchnew file mode 100644index 0000000000..68be79fc50--- /dev/null+++ b/.toolbar-patch.patch@@ -0,0 +1,3 @@+fatal: ambiguous argument 'HEAD~1': unknown revision or path not in the working tree.+Use '--' to separate paths from revisions, like this:+'git <command> [<revision>...] -- [<file>...]'diff --git a/apps/storybook/stories/Toolbar.stories.tsx b/apps/storybook/stories/Toolbar.stories.tsxnew file mode 100644index 0000000000..755631136a--- /dev/null+++ b/apps/storybook/stories/Toolbar.stories.tsx@@ -0,0 +1,382 @@+import type {Meta, StoryObj} from '@storybook/react';+import {XDSToolbar} from '@xds/core/Toolbar';+import {XDSButton} from '@xds/core/Button';+import {XDSCard} from '@xds/core/Card';+import {XDSSection} from '@xds/core/Section';+import {XDSText} from '@xds/core/Text';+import {XDSTextInput} from '@xds/core/TextInput';+import {XDSBadge} from '@xds/core/Badge';+import {XDSTable} from '@xds/core/Table';+import {XDSLayout} from '@xds/core/Layout';+import {XDSLayoutHeader} from '@xds/core/Layout';+import {XDSLayoutContent} from '@xds/core/Layout';+import {XDSMoreMenu} from '@xds/core/MoreMenu';+import {XDSHeading} from '@xds/core/Text';+import {+ Cog6ToothIcon,+ FunnelIcon,+ MagnifyingGlassIcon,+ PlusIcon,+ ArrowDownTrayIcon,+ ArrowPathIcon,+ ArrowLeftIcon,+ TrashIcon,+ ArchiveBoxIcon,+} from '@heroicons/react/24/outline';++const meta: Meta<typeof XDSToolbar> = {+ title: 'Layout/XDSToolbar',+ component: XDSToolbar,+ tags: ['autodocs'],+ parameters: {+ layout: 'padded',+ },+ argTypes: {+ label: {control: 'text'},+ density: {control: 'radio', options: ['default', 'compact']},+ orientation: {control: 'radio', options: ['horizontal', 'vertical']},+ variant: {control: 'select', options: ['transparent', 'section', 'wash']},+ gap: {control: 'number'},+ },+};++export default meta;+type Story = StoryObj<typeof XDSToolbar>;++// ---------------------------------------------------------------------------+// Basic slot patterns+// ---------------------------------------------------------------------------++/** Two-slot layout: start + end content with space-between. */+export const Default: Story = {+ args: {+ label: 'Actions',+ startContent: (+ <>+ <XDSButton label="Cut" variant="ghost" />+ <XDSButton label="Copy" variant="ghost" />+ <XDSButton label="Paste" variant="ghost" />+ </>+ ),+ endContent: (+ <XDSButton+ label="Settings"+ variant="ghost"+ icon={<Cog6ToothIcon style={{width: 16, height: 16}} />}+ />+ ),+ },+};++/** Three-slot layout: CSS grid 1fr auto 1fr. Center content stays centered regardless of start/end width. */+export const ThreeSlot: Story = {+ render: () => (+ <XDSToolbar+ label="Document toolbar"+ startContent={+ <XDSButton+ label="Back"+ variant="ghost"+ icon={<ArrowLeftIcon style={{width: 16, height: 16}} />}+ />+ }+ centerContent={<XDSHeading level={4}>Q1 Planning Document</XDSHeading>}+ endContent={+ <>+ <XDSButton label="Discard" variant="secondary" />+ <XDSButton label="Save" />+ </>+ }+ />+ ),+};++export const StartOnly: Story = {+ args: {+ label: 'Bulk actions',+ startContent: (+ <>+ <XDSBadge label="3 selected" />+ <XDSButton label="Delete" variant="ghost" size="sm" />+ <XDSButton label="Archive" variant="ghost" size="sm" />+ </>+ ),+ },+};++export const EndOnly: Story = {+ args: {+ label: 'Page actions',+ endContent: (+ <>+ <XDSButton label="Cancel" variant="ghost" />+ <XDSButton label="Save" />+ </>+ ),+ },+};++export const Compact: Story = {+ args: {+ label: 'Compact toolbar',+ density: 'compact',+ startContent: (+ <>+ <XDSButton label="Cut" variant="ghost" size="sm" />+ <XDSButton label="Copy" variant="ghost" size="sm" />+ <XDSButton label="Paste" variant="ghost" size="sm" />+ </>+ ),+ endContent: (+ <XDSButton+ label="Settings"+ variant="ghost"+ size="sm"+ icon={<Cog6ToothIcon style={{width: 14, height: 14}} />}+ />+ ),+ },+};++export const WashVariant: Story = {+ args: {+ label: 'Highlighted toolbar',+ variant: 'wash',+ startContent: <XDSText>3 items selected</XDSText>,+ endContent: (+ <>+ <XDSButton label="Delete" variant="ghost" />+ <XDSButton label="Move" variant="ghost" />+ </>+ ),+ },+};++// ---------------------------------------------------------------------------+// Composition patterns — real-world layouts+// ---------------------------------------------------------------------------++/** Toolbar as a Card header. Full-bleed via XDSSection, compact density for card context. */+export const InsideCard: Story = {+ name: 'Composition: Card Header',+ render: () => (+ <XDSCard width={600}>+ <XDSToolbar+ label="User list actions"+ density="compact"+ dividers={['bottom']}+ startContent={<XDSHeading level={4}>Users</XDSHeading>}+ endContent={+ <>+ <XDSButton+ label="Filter"+ variant="ghost"+ size="sm"+ icon={<FunnelIcon style={{width: 16, height: 16}} />}+ />+ <XDSButton+ label="Add user"+ size="sm"+ icon={<PlusIcon style={{width: 16, height: 16}} />}+ />+ </>+ }+ />+ <XDSSection>+ <XDSText>Table rows go here...</XDSText>+ </XDSSection>+ </XDSCard>+ ),+};++/** Toolbar above a data table with search + filter buttons + view controls. */+export const TableToolbar: Story = {+ name: 'Composition: Table Toolbar',+ render: () => (+ <div style={{width: 700}}>+ <XDSToolbar+ label="Table filters"+ startContent={+ <>+ <XDSTextInput placeholder="Search..." size="sm" />+ <XDSButton label="Status" variant="outline" size="sm" />+ <XDSButton label="Priority" variant="outline" size="sm" />+ <XDSButton label="Assignee" variant="outline" size="sm" />+ </>+ }+ endContent={+ <XDSMoreMenu+ items={[+ {label: 'Compact view'},+ {label: 'Comfortable view'},+ {label: 'Export CSV'},+ ]}+ />+ }+ />+ <XDSTable+ columns={[+ {key: 'name', header: 'Name'},+ {key: 'status', header: 'Status'},+ {key: 'priority', header: 'Priority'},+ ]}+ data={[+ {name: 'Fix login bug', status: 'Open', priority: 'High'},+ {name: 'Update docs', status: 'In Progress', priority: 'Medium'},+ {name: 'Add tests', status: 'Open', priority: 'Low'},+ ]}+ />+ </div>+ ),+};++/** Page-level toolbar with breadcrumbs-like back nav, centered title, and actions. */+export const PageHeader: Story = {+ name: 'Composition: Page Header',+ render: () => (+ <XDSCard>+ <XDSToolbar+ label="Page navigation"+ dividers={['bottom']}+ startContent={+ <XDSButton+ label="Back to projects"+ variant="ghost"+ icon={<ArrowLeftIcon style={{width: 16, height: 16}} />}+ />+ }+ centerContent={<XDSHeading level={3}>Project Settings</XDSHeading>}+ endContent={+ <>+ <XDSButton label="Reset" variant="ghost" />+ <XDSButton label="Save changes" />+ </>+ }+ />+ <XDSSection>+ <XDSText>Settings form content...</XDSText>+ </XDSSection>+ </XDSCard>+ ),+};++/** Bulk selection toolbar with badge count + action buttons. Appears contextually when items are selected. */+export const BulkActions: Story = {+ name: 'Composition: Bulk Selection',+ render: () => (+ <XDSToolbar+ label="Bulk actions"+ variant="wash"+ startContent={+ <>+ <XDSBadge label="5 selected" />+ <XDSButton+ label="Delete"+ variant="ghost"+ size="sm"+ icon={<TrashIcon style={{width: 16, height: 16}} />}+ />+ <XDSButton+ label="Archive"+ variant="ghost"+ size="sm"+ icon={<ArchiveBoxIcon style={{width: 16, height: 16}} />}+ />+ </>+ }+ endContent={<XDSButton label="Deselect all" variant="ghost" size="sm" />}+ />+ ),+};++/** Stacked toolbars: primary actions above, secondary filters below. */+export const StackedToolbars: Story = {+ name: 'Composition: Stacked Toolbars',+ render: () => (+ <XDSCard width={700}>+ <XDSToolbar+ label="Primary actions"+ density="compact"+ dividers={['bottom']}+ startContent={<XDSHeading level={4}>Orders</XDSHeading>}+ endContent={+ <>+ <XDSButton+ label="Refresh"+ variant="ghost"+ size="sm"+ icon={<ArrowPathIcon style={{width: 16, height: 16}} />}+ />+ <XDSButton+ label="Export"+ variant="ghost"+ size="sm"+ icon={<ArrowDownTrayIcon style={{width: 16, height: 16}} />}+ />+ <XDSButton label="New order" size="sm" />+ </>+ }+ />+ <XDSToolbar+ label="Filters"+ density="compact"+ variant="wash"+ startContent={+ <>+ <XDSTextInput placeholder="Search orders..." size="sm" />+ <XDSButton label="Status" variant="outline" size="sm" />+ <XDSButton label="Date range" variant="outline" size="sm" />+ <XDSButton label="Customer" variant="outline" size="sm" />+ </>+ }+ endContent={+ <XDSButton label="Clear filters" variant="ghost" size="sm" />+ }+ />+ <XDSSection>+ <XDSText>Order table rows...</XDSText>+ </XDSSection>+ </XDSCard>+ ),+};++/** Inside a Layout header — toolbar inherits the layout's padding context. */+export const InsideLayout: Story = {+ name: 'Composition: Inside Layout',+ render: () => (+ <div style={{height: 300, border: '1px solid #e0e0e0', borderRadius: 8}}>+ <XDSLayout+ header={+ <XDSLayoutHeader hasDivider padding={0}>+ <XDSToolbar+ label="App toolbar"+ startContent={+ <>+ <XDSHeading level={4}>Dashboard</XDSHeading>+ <XDSBadge label="Beta" variant="info" />+ </>+ }+ endContent={+ <>+ <XDSButton label="Notifications" variant="ghost" size="sm" />+ <XDSMoreMenu+ items={[+ {label: 'Profile'},+ {label: 'Settings'},+ {label: 'Sign out'},+ ]}+ />+ </>+ }+ />+ </XDSLayoutHeader>+ }+ content={+ <XDSLayoutContent>+ <XDSText>Dashboard content...</XDSText>+ </XDSLayoutContent>+ }+ />+ </div>+ ),+};diff --git a/packages/core/package.json b/packages/core/package.jsonindex 6f7a1e5227..f7a40e5a7b 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -382,6 +382,12 @@"import": "./dist/Tokenizer/index.mjs","require": "./dist/Tokenizer/index.js"},+ "./Toolbar": {+ "source": "./src/Toolbar/index.ts",+ "types": "./dist/Toolbar/index.d.ts",+ "import": "./dist/Toolbar/index.mjs",+ "require": "./dist/Toolbar/index.js"+ },"./Tooltip": {"source": "./src/Tooltip/index.ts","types": "./dist/Tooltip/index.d.ts",diff --git a/packages/core/src/Toolbar/Toolbar.doc.mjs b/packages/core/src/Toolbar/Toolbar.doc.mjsnew file mode 100644index 0000000000..eb36e02058--- /dev/null+++ b/packages/core/src/Toolbar/Toolbar.doc.mjs@@ -0,0 +1,298 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Toolbar',+ description:+ 'General-purpose toolbar with start, center, and end content slots. Built on XDSSection with roving tabindex keyboard navigation.',+ features: [+ 'Slot-based layout — startContent, centerContent, and endContent for flexible organization',+ 'Three-column centering — centerContent switches to CSS grid (1fr auto 1fr) for true centering',+ 'Roving tabindex — arrow key navigation via useListFocus with orientation support',+ 'Density variants — default (40px) and compact (32px) minimum heights',+ 'Configurable gap — spacing scale gap between items within each slot',+ 'Built on XDSSection — inherits variant, theming, and nesting behavior',+ 'Composable overflow — use XDSOverflowList within slots for responsive collapsing',+ ],+ examples: [+ {+ label: 'Basic toolbar with start and end actions',+ code: `<XDSToolbar+ label="Text formatting"+ startContent={+ <>+ <XDSButton label="Bold" variant="ghost" icon={<BoldIcon />} />+ <XDSButton label="Italic" variant="ghost" icon={<ItalicIcon />} />+ <XDSButton label="Underline" variant="ghost" icon={<UnderlineIcon />} />+ </>+ }+ endContent={+ <XDSButton label="Settings" variant="ghost" icon={<Cog6ToothIcon />} />+ }+/>`,+ },+ {+ label: 'Three-slot layout with centered content',+ code: `<XDSToolbar+ label="Document actions"+ startContent={<XDSButton label="Back" variant="ghost" />}+ centerContent={<XDSText>Document Title</XDSText>}+ endContent={<XDSButton label="Save" variant="primary" />}+/>`,+ },+ {+ label: 'Card header pattern',+ code: `<XDSCard>+ <XDSToolbar+ label="Card actions"+ startContent={<XDSText weight="bold">Users</XDSText>}+ endContent={+ <>+ <XDSButton label="Filter" variant="ghost" icon={<FunnelIcon />} />+ <XDSButton label="Add" variant="primary" />+ </>+ }+ />+ <XDSSection>{/* card body */}</XDSSection>+</XDSCard>`,+ },+ {+ label: 'With XDSOverflowList for responsive collapsing',+ code: `<XDSToolbar+ label="Actions"+ startContent={+ <XDSOverflowList+ items={actions}+ renderItem={(action) => (+ <XDSButton key={action.id} label={action.label} variant="ghost" />+ )}+ renderOverflow={(items) => (+ <XDSDropdownMenu+ trigger={<XDSButton label="More" variant="ghost" />}+ items={items.map(a => ({label: a.label, onSelect: a.onSelect}))}+ />+ )}+ />+ }+/>`,+ },+ {+ label: 'Compact density',+ code: `<XDSToolbar+ label="Compact actions"+ density="compact"+ startContent={+ <>+ <XDSButton label="Cut" variant="ghost" size="sm" />+ <XDSButton label="Copy" variant="ghost" size="sm" />+ <XDSButton label="Paste" variant="ghost" size="sm" />+ </>+ }+/>`,+ },+ ],+ theming: {+ targets: [+ {className: 'xds-toolbar', states: ['density']},+ ],+ },+ accessibility: [+ 'Inner element renders role="toolbar" with aria-label from label prop',+ 'aria-orientation reflects the orientation prop (horizontal or vertical)',+ 'Roving tabindex via useListFocus — arrow keys move focus between focusable items (buttons, inputs, [tabindex="0"])',+ 'Home/End keys jump to first/last focusable item',+ 'Horizontal orientation: ArrowLeft/ArrowRight navigate; Vertical orientation: ArrowUp/ArrowDown navigate',+ ],+ keyboard:+ 'ArrowLeft/ArrowRight (horizontal) or ArrowUp/ArrowDown (vertical) to move between items; Home/End for first/last item',+ notes: [+ 'Built on XDSSection — variant prop controls background (default: transparent)',+ 'Two-slot layout (no centerContent): flex row with space-between',+ 'Three-slot layout (with centerContent): CSS grid 1fr auto 1fr for true centering',+ 'startContent only: fills width; endContent only: aligns to end',+ 'centerContent has min-width:0 and overflow:hidden for graceful truncation',+ 'No built-in overflow — compose with XDSOverflowList for responsive collapsing',+ 'Density controls minimum height — compact: 32px, default: 40px',+ 'Gap prop controls spacing between items within slots (default: --spacing-2 / 8px)',+ ],+ components: [+ {+ name: 'XDSToolbar',+ description:+ 'General-purpose toolbar container with three content slots and roving tabindex.',+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the toolbar, applied as aria-label.',+ required: true,+ },+ {+ name: 'startContent',+ type: 'ReactNode',+ description: 'Content aligned to the start (left in LTR).',+ },+ {+ name: 'centerContent',+ type: 'ReactNode',+ description:+ 'Centered content. Switches layout to CSS grid (1fr auto 1fr).',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description: 'Content aligned to the end (right in LTR).',+ },+ {+ name: 'density',+ type: "'compact' | 'default'",+ description: 'Toolbar density. Controls minimum height.',+ default: "'default'",+ },+ {+ name: 'gap',+ type: 'SpacingStep',+ description: 'Gap between items within each slot.',+ default: '2',+ },+ {+ name: 'orientation',+ type: "'horizontal' | 'vertical'",+ description:+ 'Orientation for keyboard navigation. Controls arrow key direction.',+ default: "'horizontal'",+ },+ {+ name: 'variant',+ type: 'XDSSectionVariant',+ description: 'Visual variant passed to XDSSection.',+ default: "'transparent'",+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSToolbar+ label="Actions"+ startContent={<XDSButton label="Save" variant="primary" />}+ endContent={<XDSButton label="Cancel" variant="ghost" />}+/>`,+ },+ {+ label: 'With centered content',+ code: `<XDSToolbar+ label="Editor"+ startContent={<XDSButton label="Back" variant="ghost" />}+ centerContent={<XDSText>Document.tsx</XDSText>}+ endContent={<XDSButton label="Publish" variant="primary" />}+/>`,+ },+ ],+ },+ ],+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsZh = {+ description:+ '通用工具栏,提供起始、居中和结束内容插槽。基于 XDSSection 构建,支持循环 Tab 键盘导航。',+ features: [+ '插槽式布局 — startContent、centerContent 和 endContent 灵活组织',+ '三列居中 — centerContent 切换为 CSS grid(1fr auto 1fr)实现真正居中',+ '循环 Tab — 通过 useListFocus 实现方向键导航',+ '密度变体 — default(40px)和 compact(32px)最小高度',+ '可配置间距 — 使用间距尺度设置插槽内项目间距',+ '基于 XDSSection — 继承变体、主题化和嵌套行为',+ '可组合溢出 — 在插槽中使用 XDSOverflowList 实现响应式折叠',+ ],+ accessibility: [+ '内部元素渲染 role="toolbar",从 label 属性设置 aria-label',+ 'aria-orientation 反映 orientation 属性(horizontal 或 vertical)',+ '通过 useListFocus 实现循环 Tab — 方向键在可聚焦项之间移动焦点',+ 'Home/End 键跳转到第一个/最后一个可聚焦项',+ '水平方向:ArrowLeft/ArrowRight 导航;垂直方向:ArrowUp/ArrowDown 导航',+ ],+ keyboard:+ 'ArrowLeft/ArrowRight(水平)或 ArrowUp/ArrowDown(垂直)移动项目;Home/End 跳转首/末项',+ notes: [+ '基于 XDSSection — variant 属性控制背景(默认:transparent)',+ '两插槽布局(无 centerContent):flex 行 + space-between',+ '三插槽布局(有 centerContent):CSS grid 1fr auto 1fr 实现真正居中',+ 'startContent 独占:填充宽度;endContent 独占:靠右对齐',+ 'centerContent 设置 min-width:0 和 overflow:hidden 以优雅截断',+ '无内置溢出 — 组合 XDSOverflowList 实现响应式折叠',+ '密度控制最小高度 — compact: 32px,default: 40px',+ 'gap 属性控制插槽内项目间距(默认:--spacing-2 / 8px)',+ ],+ components: [+ {+ name: 'XDSToolbar',+ description: '通用工具栏容器,提供三个内容插槽和循环 Tab。',+ propDescriptions: {+ label: '工具栏的无障碍标签,作为 aria-label 应用。',+ startContent: '起始内容(LTR 中靠左对齐)。',+ centerContent: '居中内容。切换为 CSS grid(1fr auto 1fr)。',+ endContent: '结束内容(LTR 中靠右对齐)。',+ density: '工具栏密度。控制最小高度。',+ gap: '插槽内项目间距。',+ orientation: '键盘导航方向。控制方向键方向。',+ variant: '传递给 XDSSection 的视觉变体。',+ xstyle: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',+ },+ },+ ],+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsDense = {+ description: 'General-purpose toolbar w/ start/center/end slots. Built on XDSSection w/ roving tabindex.',+ features: [+ 'Slot-based layout; startContent, centerContent, endContent',+ 'Three-column centering; centerContent switches to CSS grid (1fr auto 1fr)',+ 'Roving tabindex; arrow key nav via useListFocus w/ orientation',+ 'Density variants; default (40px) + compact (32px) min-height',+ 'Configurable gap; spacing scale gap between slot items',+ 'Built on XDSSection; inherits variant, theming, nesting',+ 'Composable overflow; use XDSOverflowList for responsive collapsing',+ ],+ accessibility: [+ 'role="toolbar" w/ aria-label from label prop.',+ 'aria-orientation reflects orientation prop.',+ 'Roving tabindex via useListFocus; arrows move focus between items.',+ 'Home/End jump to first/last item.',+ 'Horizontal: Left/Right; Vertical: Up/Down.',+ ],+ keyboard: 'Left/Right (horiz) or Up/Down (vert) between items; Home/End for first/last.',+ notes: [+ 'Built on XDSSection; variant controls bg (default: transparent).',+ 'Two-slot (no center): flex row w/ space-between.',+ 'Three-slot (w/ center): CSS grid 1fr auto 1fr.',+ 'startOnly fills width; endOnly aligns right.',+ 'centerContent: min-width:0 + overflow:hidden for truncation.',+ 'No built-in overflow; compose w/ XDSOverflowList.',+ 'Density: compact=32px, default=40px min-height.',+ 'Gap: spacing between slot items (default: --spacing-2/8px).',+ ],+ components: [+ {+ name: 'XDSToolbar',+ description: 'Toolbar container w/ 3 content slots + roving tabindex.',+ propDescriptions: {+ label: 'A11y label, aria-label on toolbar.',+ startContent: 'Start-aligned content.',+ centerContent: 'Centered content; switches to 3-col grid.',+ endContent: 'End-aligned content.',+ density: 'Toolbar density; controls min-height.',+ gap: 'Gap between slot items.',+ orientation: 'Keyboard nav direction.',+ variant: 'Visual variant for XDSSection.',+ xstyle: 'StyleX layout styles. Must be stylex.create() value.',+ },+ },+ ],+};diff --git a/packages/core/src/Toolbar/XDSToolbar.test.tsx b/packages/core/src/Toolbar/XDSToolbar.test.tsxnew file mode 100644index 0000000000..05fdeb9e5e--- /dev/null+++ b/packages/core/src/Toolbar/XDSToolbar.test.tsx@@ -0,0 +1,251 @@+/**+ * @file XDSToolbar.test.tsx+ * @input Uses vitest, @testing-library/react, XDSToolbar+ * @output Unit tests for XDSToolbar component+ * @position Testing; validates XDSToolbar implementation+ *+ * SYNC: When Toolbar component changes, update tests to match new behavior+ */++import {describe, it, expect, vi} from 'vitest';+import {render, screen} from '@testing-library/react';+import userEvent from '@testing-library/user-event';+import {XDSToolbar} from './XDSToolbar';++describe('XDSToolbar', () => {+ it('renders with toolbar role', () => {+ render(<XDSToolbar label="Actions" />);+ expect(screen.getByRole('toolbar')).toBeInTheDocument();+ });++ it('renders aria-label from label prop', () => {+ render(<XDSToolbar label="Formatting actions" />);+ expect(screen.getByRole('toolbar')).toHaveAttribute(+ 'aria-label',+ 'Formatting actions',+ );+ });++ it('renders startContent slot', () => {+ render(+ <XDSToolbar+ label="Actions"+ startContent={<span data-testid="start">Start</span>}+ />,+ );+ expect(screen.getByTestId('start')).toBeInTheDocument();+ });++ it('renders endContent slot', () => {+ render(+ <XDSToolbar+ label="Actions"+ endContent={<span data-testid="end">End</span>}+ />,+ );+ expect(screen.getByTestId('end')).toBeInTheDocument();+ });++ it('renders centerContent slot', () => {+ render(+ <XDSToolbar+ label="Actions"+ centerContent={<span data-testid="center">Center</span>}+ />,+ );+ expect(screen.getByTestId('center')).toBeInTheDocument();+ });++ it('renders all three slots together', () => {+ render(+ <XDSToolbar+ label="Actions"+ startContent={<span data-testid="start">Start</span>}+ centerContent={<span data-testid="center">Center</span>}+ endContent={<span data-testid="end">End</span>}+ />,+ );+ expect(screen.getByTestId('start')).toBeInTheDocument();+ expect(screen.getByTestId('center')).toBeInTheDocument();+ expect(screen.getByTestId('end')).toBeInTheDocument();++ // Three-slot layout produces 3 child divs+ const toolbar = screen.getByRole('toolbar');+ expect(toolbar.children).toHaveLength(3);+ });++ it('renders two-slot layout without centerContent', () => {+ render(+ <XDSToolbar+ label="Actions"+ startContent={<span data-testid="start">Start</span>}+ endContent={<span data-testid="end">End</span>}+ />,+ );+ expect(screen.getByTestId('start')).toBeInTheDocument();+ expect(screen.getByTestId('end')).toBeInTheDocument();++ // Two-slot layout produces 2 child divs+ const toolbar = screen.getByRole('toolbar');+ expect(toolbar.children).toHaveLength(2);+ });++ it('renders start-only layout', () => {+ render(+ <XDSToolbar+ label="Actions"+ startContent={<span data-testid="start">Start</span>}+ />,+ );+ expect(screen.getByTestId('start')).toBeInTheDocument();+ const toolbar = screen.getByRole('toolbar');+ expect(toolbar.children).toHaveLength(1);+ });++ it('renders end-only layout', () => {+ render(+ <XDSToolbar+ label="Actions"+ endContent={<span data-testid="end">End</span>}+ />,+ );+ expect(screen.getByTestId('end')).toBeInTheDocument();+ const toolbar = screen.getByRole('toolbar');+ expect(toolbar.children).toHaveLength(1);+ });++ it('sets aria-orientation to horizontal by default', () => {+ render(<XDSToolbar label="Actions" />);+ expect(screen.getByRole('toolbar')).toHaveAttribute(+ 'aria-orientation',+ 'horizontal',+ );+ });++ it('sets aria-orientation to vertical', () => {+ render(<XDSToolbar label="Actions" orientation="vertical" />);+ expect(screen.getByRole('toolbar')).toHaveAttribute(+ 'aria-orientation',+ 'vertical',+ );+ });++ it('applies density class', () => {+ render(<XDSToolbar label="Actions" density="compact" />);+ const toolbar = screen.getByRole('toolbar');+ expect(toolbar.className).toContain('compact');+ });++ it('applies default density class', () => {+ render(<XDSToolbar label="Actions" />);+ const toolbar = screen.getByRole('toolbar');+ expect(toolbar.className).toContain('default');+ });++ it('forwards ref to root element', () => {+ const ref = vi.fn();+ render(<XDSToolbar label="Actions" ref={ref} />);+ expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));+ });++ it('passes variant to XDSSection', () => {+ const {container} = render(<XDSToolbar label="Actions" variant="wash" />);+ // XDSSection renders with xds-section class containing the variant+ const sectionInner = container.querySelector('.xds-section');+ expect(sectionInner).toBeInTheDocument();+ expect(sectionInner?.className).toContain('wash');+ });++ it('defaults to transparent variant', () => {+ const {container} = render(<XDSToolbar label="Actions" />);+ const sectionInner = container.querySelector('.xds-section');+ expect(sectionInner).toBeInTheDocument();+ expect(sectionInner?.className).toContain('transparent');+ });++ it('navigates with ArrowRight/ArrowLeft in horizontal orientation', async () => {+ const user = userEvent.setup();+ render(+ <XDSToolbar+ label="Actions"+ startContent={+ <>+ <button>Cut</button>+ <button>Copy</button>+ <button>Paste</button>+ </>+ }+ />,+ );++ const buttons = screen.getAllByRole('button');+ buttons[0].focus();+ expect(document.activeElement).toBe(buttons[0]);++ await user.keyboard('{ArrowRight}');+ expect(document.activeElement).toBe(buttons[1]);++ await user.keyboard('{ArrowRight}');+ expect(document.activeElement).toBe(buttons[2]);++ await user.keyboard('{ArrowLeft}');+ expect(document.activeElement).toBe(buttons[1]);+ });++ it('navigates with ArrowDown/ArrowUp in vertical orientation', async () => {+ const user = userEvent.setup();+ render(+ <XDSToolbar+ label="Actions"+ orientation="vertical"+ startContent={+ <>+ <button>Cut</button>+ <button>Copy</button>+ <button>Paste</button>+ </>+ }+ />,+ );++ const buttons = screen.getAllByRole('button');+ buttons[0].focus();+ expect(document.activeElement).toBe(buttons[0]);++ await user.keyboard('{ArrowDown}');+ expect(document.activeElement).toBe(buttons[1]);++ await user.keyboard('{ArrowUp}');+ expect(document.activeElement).toBe(buttons[0]);+ });++ it('supports Home and End keys', async () => {+ const user = userEvent.setup();+ render(+ <XDSToolbar+ label="Actions"+ startContent={+ <>+ <button>Cut</button>+ <button>Copy</button>+ <button>Paste</button>+ </>+ }+ />,+ );++ const buttons = screen.getAllByRole('button');+ buttons[1].focus();++ await user.keyboard('{End}');+ expect(document.activeElement).toBe(buttons[2]);++ await user.keyboard('{Home}');+ expect(document.activeElement).toBe(buttons[0]);+ });++ it('spreads additional HTML attributes to toolbar element', () => {+ render(<XDSToolbar label="Actions" data-testid="my-toolbar" />);+ expect(screen.getByTestId('my-toolbar')).toBe(screen.getByRole('toolbar'));+ });+});diff --git a/packages/core/src/Toolbar/XDSToolbar.tsx b/packages/core/src/Toolbar/XDSToolbar.tsxnew file mode 100644index 0000000000..a564ba0377--- /dev/null+++ b/packages/core/src/Toolbar/XDSToolbar.tsx@@ -0,0 +1,281 @@+'use client';++/**+ * @file XDSToolbar.tsx+ * @input Uses XDSSection, useListFocus, StyleX, spacingVars+ * @output Exports XDSToolbar component and XDSToolbarProps+ * @position Core implementation; consumed by index.ts+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Toolbar/Toolbar.doc.mjs+ * - /packages/core/src/Toolbar/XDSToolbar.test.tsx+ * - /packages/core/src/Toolbar/index.ts+ * - /apps/storybook/stories/Toolbar.stories.tsx+ */++import {type ReactNode} from 'react';+import type {XDSBaseProps} from '../XDSBaseProps';+import type {XDSSectionVariant} from '../Section/XDSSection';+import type {SpacingStep} from '../utils/types';+import * as stylex from '@stylexjs/stylex';+import {spacingVars} from '../theme/tokens.stylex';+import {xdsClassName, mergeProps} from '../utils';+import {XDSSection} from '../Section/XDSSection';+import {useListFocus} from '../hooks/useListFocus';++/**+ * Map SpacingStep values to spacingVars keys.+ */+const spacingStepToVar: Record<SpacingStep, keyof typeof spacingVars> = {+ 0: '--spacing-0',+ 0.5: '--spacing-0-5',+ 1: '--spacing-1',+ 1.5: '--spacing-1-5',+ 2: '--spacing-2',+ 3: '--spacing-3',+ 4: '--spacing-4',+ 5: '--spacing-5',+ 6: '--spacing-6',+ 8: '--spacing-8',+ 10: '--spacing-10',+};++const styles = stylex.create({+ // Two-slot layout (no centerContent): flex row, space-between+ baseFlex: {+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'space-between',+ },+ // Three-slot layout (with centerContent): CSS grid 1fr auto 1fr+ baseGrid: {+ display: 'grid',+ gridTemplateColumns: '1fr auto 1fr',+ alignItems: 'center',+ },+ // Vertical orientation+ vertical: {+ flexDirection: 'column',+ alignItems: 'stretch',+ },+ // Compact density: tighter height+ compact: {+ minHeight: spacingVars['--spacing-8'],+ },+ defaultDensity: {+ minHeight: spacingVars['--spacing-10'],+ },+ // Slot containers+ // Start and end slots add horizontal padding (spacing-2 = 8px) so that+ // combined with the section's 8px padding, content aligns at 16px from edges.+ // This split enables future edge compensation: ghost buttons can negate+ // the slot padding while the section padding remains.+ startSlot: {+ display: 'flex',+ alignItems: 'center',+ paddingInlineStart: spacingVars['--spacing-2'],+ },+ centerSlot: {+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ minWidth: 0,+ overflow: 'hidden',+ },+ endSlot: {+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'flex-end',+ paddingInlineEnd: spacingVars['--spacing-2'],+ },+ // When only startContent is present, let it fill+ startOnly: {+ flex: '1 1 0%',+ },+ // When only endContent, push to end+ endOnly: {+ marginInlineStart: 'auto',+ },+});++// Dynamic styles for configurable gap+const dynamicStyles = stylex.create({+ gap: (gapValue: string) => ({+ gap: gapValue,+ }),+});++export interface XDSToolbarProps extends XDSBaseProps<HTMLDivElement> {+ /** Ref forwarded to the root XDSSection element */+ ref?: React.Ref<HTMLElement>;+ /**+ * Content aligned to the start (left in LTR).+ */+ startContent?: ReactNode;+ /**+ * Content centered between start and end.+ * When provided, switches layout to CSS grid (1fr auto 1fr).+ */+ centerContent?: ReactNode;+ /**+ * Content aligned to the end (right in LTR).+ */+ endContent?: ReactNode;+ /**+ * Accessible label for the toolbar.+ * Applied as aria-label on the inner toolbar element.+ */+ label: string;+ /**+ * Density of the toolbar.+ * - 'default': Standard height (40px min)+ * - 'compact': Reduced height (32px min)+ * @default 'default'+ */+ density?: 'compact' | 'default';+ /**+ * Gap between items within each slot, using the spacing scale.+ * @default 2+ */+ gap?: SpacingStep;+ /**+ * Orientation of the toolbar for keyboard navigation.+ * Controls which arrow keys navigate between items.+ * @default 'horizontal'+ */+ orientation?: 'horizontal' | 'vertical';+ /**+ * Visual variant passed through to XDSSection.+ * @default 'transparent'+ */+ variant?: XDSSectionVariant;+ /**+ * Internal padding using the spacing scale.+ * Passed through to XDSSection.+ * @default 2 (8px) — combined with 8px slot padding = 16px from edges+ */+ padding?: SpacingStep;+ /**+ * Which sides should have divider borders.+ * Passed through to XDSSection.+ * @example+ * ```tsx+ * dividers={['bottom']} // toolbar with a bottom border+ * ```+ */+ dividers?: Array<'top' | 'bottom' | 'start' | 'end'>;+}++/**+ * General-purpose toolbar with start, center, and end content slots.+ *+ * Built on XDSSection, provides flex/grid layout with roving tabindex+ * keyboard navigation via useListFocus.+ *+ * @example+ * ```+ * <XDSToolbar+ * label="Actions"+ * startContent={<XDSButton label="Cut" variant="ghost" />}+ * endContent={<XDSButton label="Settings" variant="ghost" />}+ * />+ * ```+ */+export function XDSToolbar({+ startContent,+ centerContent,+ endContent,+ label,+ density = 'default',+ gap = 2,+ orientation = 'horizontal',+ variant = 'transparent',+ padding,+ dividers,+ xstyle,+ className,+ style,+ ref,+ ...props+}: XDSToolbarProps) {+ const hasCenterContent = centerContent != null;+ const hasStartContent = startContent != null;+ const hasEndContent = endContent != null;++ const gapVar = spacingVars[spacingStepToVar[gap]] as string;++ const {listRef, handleKeyDown} = useListFocus({+ itemSelector: 'button, input, [tabindex="0"]',+ orientation,+ });++ return (+ <XDSSection+ ref={ref}+ variant={variant}+ padding={padding ?? 2}+ dividers={dividers}+ xstyle={xstyle}+ className={className}+ style={style}>+ <div+ ref={listRef as React.RefObject<HTMLDivElement>}+ role="toolbar"+ aria-label={label}+ aria-orientation={orientation}+ onKeyDown={handleKeyDown}+ {...mergeProps(+ xdsClassName('toolbar', {density}),+ stylex.props(+ hasCenterContent ? styles.baseGrid : styles.baseFlex,+ orientation === 'vertical' && styles.vertical,+ density === 'compact' ? styles.compact : styles.defaultDensity,+ dynamicStyles.gap(gapVar),+ ),+ )}+ {...props}>+ {hasCenterContent ? (+ // Three-slot grid layout+ <>+ <div {...stylex.props(styles.startSlot, dynamicStyles.gap(gapVar))}>+ {startContent}+ </div>+ <div+ {...stylex.props(styles.centerSlot, dynamicStyles.gap(gapVar))}>+ {centerContent}+ </div>+ <div {...stylex.props(styles.endSlot, dynamicStyles.gap(gapVar))}>+ {endContent}+ </div>+ </>+ ) : (+ // Two-slot flex layout+ <>+ {hasStartContent && (+ <div+ {...stylex.props(+ styles.startSlot,+ !hasEndContent && styles.startOnly,+ dynamicStyles.gap(gapVar),+ )}>+ {startContent}+ </div>+ )}+ {hasEndContent && (+ <div+ {...stylex.props(+ styles.endSlot,+ !hasStartContent && styles.endOnly,+ dynamicStyles.gap(gapVar),+ )}>+ {endContent}+ </div>+ )}+ </>+ )}+ </div>+ </XDSSection>+ );+}++XDSToolbar.displayName = 'XDSToolbar';diff --git a/packages/core/src/Toolbar/index.ts b/packages/core/src/Toolbar/index.tsnew file mode 100644index 0000000000..9f49e8ea6e--- /dev/null+++ b/packages/core/src/Toolbar/index.ts@@ -0,0 +1,13 @@+'use client';++/**+ * @file index.ts+ * @input Imports from Toolbar component files+ * @output Exports XDSToolbar and types+ * @position Entry point for Toolbar module+ *+ * SYNC: When modified, update /packages/core/src/Toolbar/Toolbar.doc.mjs+ */++export {XDSToolbar} from './XDSToolbar';+export type {XDSToolbarProps} from './XDSToolbar';diff --git a/packages/core/src/hooks/useListFocus.ts b/packages/core/src/hooks/useListFocus.tsindex 9b674c7ad6..e3e85fd47d 100644--- a/packages/core/src/hooks/useListFocus.ts+++ b/packages/core/src/hooks/useListFocus.ts@@ -4,13 +4,12 @@* @file useListFocus.ts* @input Uses React useCallback, useRef* @output Exports useListFocus hook for linear list keyboard navigation- * @position Core hook; used by XDSTabMenu for dropdown menu navigation+ * @position Core hook; used by XDSTabMenu for dropdown menu navigation, XDSToolbar for roving tabindex** SYNC: When modified, update:* - /packages/core/src/hooks/index.ts*/-import {useCallback, useRef} from 'react';/**@@ -33,6 +32,13 @@ export interface UseListFocusOptions {* Callback when Escape key is pressed.*/onEscape?: () => void;++ /**+ * Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight,+ * 'vertical' uses ArrowUp/ArrowDown.+ * @default 'vertical'+ */+ orientation?: 'horizontal' | 'vertical';}/**@@ -68,9 +74,9 @@ export interface UseListFocusReturn {/*** Hook for managing keyboard navigation within a linear list.*- * Implements WAI-ARIA menu/listbox pattern:- * - ArrowDown: Move to next item (wraps to first)- * - ArrowUp: Move to previous item (wraps to last)+ * Implements WAI-ARIA menu/listbox/toolbar pattern:+ * - ArrowDown/ArrowRight: Move to next item (wraps to first)+ * - ArrowUp/ArrowLeft: Move to previous item (wraps to last)* - Home: Move to first item* - End: Move to last item* - Escape: Custom callback (e.g., close menu)@@ -89,7 +95,12 @@ export interface UseListFocusReturn {export function useListFocus(options: UseListFocusOptions = {},): UseListFocusReturn {- const {itemSelector = '[role="menuitem"]', wrap = true, onEscape} = options;+ const {+ itemSelector = '[role="menuitem"]',+ wrap = true,+ onEscape,+ orientation = 'vertical',+ } = options;const listRef = useRef<HTMLElement>(null);@@ -152,8 +163,11 @@ export function useListFocus(const items = getItems();let handled = true;+ const nextKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';+ const prevKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';+switch (e.key) {- case 'ArrowDown': {+ case nextKey: {if (currentIndex === -1) {items[0]?.focus();} else if (currentIndex < items.length - 1) {@@ -163,7 +177,7 @@ export function useListFocus(}break;}- case 'ArrowUp': {+ case prevKey: {if (currentIndex === -1) {items[items.length - 1]?.focus();} else if (currentIndex > 0) {@@ -190,7 +204,15 @@ export function useListFocus(e.preventDefault();}},- [getCurrentIndex, getItems, wrap, focusFirst, focusLast, onEscape],+ [+ getCurrentIndex,+ getItems,+ wrap,+ orientation,+ focusFirst,+ focusLast,+ onEscape,+ ],);return {diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 67d277e260..b501013217 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -62,6 +62,7 @@ export * from './Kbd';export * from './Dialog';export * from './DropdownMenu';export * from './MoreMenu';+export * from './Toolbar';export * from './TopNav';export * from './SideNav';export * from './MobileNav';