Skip to content

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.patch
new file mode 100644
index 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.tsx
new file mode 100644
index 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.json
index 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.mjs
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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';