An open source design system that's fully customizable and agent ready
TypeScript
feat: add XDSIconButton component (#1323)
Cindy Zhangf0583357fdee
diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.mdindex 26a6a1a44d..4e117ba46e 100644--- a/.claude/commands/create-component.md+++ b/.claude/commands/create-component.md@@ -23,7 +23,6 @@ Follow the full component lifecycle documented on the XDS wiki:- `XDS{ComponentName}.test.tsx` — unit tests- `{ComponentName}.doc.mjs` — typed docs (ComponentDoc)- `index.ts` — public exports- - `README.md` — directory README (see Tokenizer/README.md for the format)- Create `apps/storybook/stories/{ComponentName}.stories.tsx`- Wire up: add to `packages/core/src/index.ts`- Run `node scripts/sync-exports.js` to update package.json exportsdiff --git a/CLAUDE.md b/CLAUDE.mdindex 9c083fa9b3..594718c149 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -61,19 +61,12 @@ For component-specific documentation, see the `{Name}.doc.mjs` file in each comp## Documentation Standard-This project uses **Fractal Documentation** — a self-referential pattern where documentation exists at three levels:+Documentation lives in two places:-1. **Project Root** (`README.md`) — Project-wide architecture and directory overview-2. **Directory READMEs** — Each directory contains a `README.md` with file manifests-3. **File Headers** — Each source file has a structured JSDoc header with `@input`, `@output`, `@position`+1. **File Headers** — Each source file has a structured JSDoc header with `@input`, `@output`, `@position`+2. **Component Docs** — `{Name}.doc.mjs` files in each component directory (props, features, examples)-**Update Protocol**: When modifying code, update:--1. The file's header comment-2. The directory's README.md-3. Parent documentation if architecture changes--Look for `<!-- SYNC: ... -->` comments and `SYNC:` in file headers as reminders.+**Update Protocol**: When modifying code, update the file's header comment. Look for `SYNC:` comments as reminders.## Quick Referencediff --git a/apps/storybook/stories/IconButton.stories.tsx b/apps/storybook/stories/IconButton.stories.tsxnew file mode 100644index 0000000000..89e1c54b51--- /dev/null+++ b/apps/storybook/stories/IconButton.stories.tsx@@ -0,0 +1,127 @@+import type {Meta, StoryObj} from '@storybook/react';+import {XDSIconButton} from '@xds/core/IconButton';+import {+ Cog6ToothIcon,+ TrashIcon,+ PlusIcon,+ XMarkIcon,+ PencilIcon,+ HeartIcon,+ BellIcon,+} from '@heroicons/react/24/outline';++const meta: Meta<typeof XDSIconButton> = {+ title: 'Core/XDSIconButton',+ component: XDSIconButton,+ tags: ['autodocs'],+ argTypes: {+ label: {+ control: 'text',+ description: 'Accessible label (aria-label)',+ },+ variant: {+ control: 'select',+ options: ['primary', 'secondary', 'ghost', 'destructive'],+ description: 'Visual style variant',+ },+ size: {+ control: 'select',+ options: ['sm', 'md', 'lg'],+ description: 'Size variant',+ },+ isLoading: {+ control: 'boolean',+ description: 'Loading state',+ },+ isDisabled: {+ control: 'boolean',+ description: 'Disabled state',+ },+ },+};++export default meta;+type Story = StoryObj<typeof XDSIconButton>;++export const Default: Story = {+ args: {+ label: 'Settings',+ icon: <Cog6ToothIcon />,+ },+};++export const Ghost: Story = {+ args: {+ label: 'Settings',+ icon: <Cog6ToothIcon />,+ variant: 'ghost',+ },+};++export const Primary: Story = {+ args: {+ label: 'Add item',+ icon: <PlusIcon />,+ variant: 'primary',+ },+};++export const Destructive: Story = {+ args: {+ label: 'Delete',+ icon: <TrashIcon />,+ variant: 'destructive',+ },+};++export const Small: Story = {+ args: {+ label: 'Close',+ icon: <XMarkIcon />,+ variant: 'ghost',+ size: 'sm',+ },+};++export const Large: Story = {+ args: {+ label: 'Edit',+ icon: <PencilIcon />,+ size: 'lg',+ },+};++export const WithTooltip: Story = {+ args: {+ label: 'Notifications',+ icon: <BellIcon />,+ variant: 'ghost',+ tooltip: 'View notifications',+ },+};++export const Loading: Story = {+ args: {+ label: 'Saving',+ icon: <HeartIcon />,+ variant: 'primary',+ isLoading: true,+ },+};++export const Disabled: Story = {+ args: {+ label: 'Edit',+ icon: <PencilIcon />,+ isDisabled: true,+ },+};++export const EmojiIcon: Story = {+ args: {+ label: 'React with rocket',+ icon: <span>🚀</span>,+ variant: 'ghost',+ size: 'sm',+ },+};diff --git a/packages/core/package.json b/packages/core/package.jsonindex 993a32eef9..e1863c44ea 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -196,6 +196,12 @@"import": "./dist/Icon/index.mjs","require": "./dist/Icon/index.js"},+ "./IconButton": {+ "source": "./src/IconButton/index.ts",+ "types": "./dist/IconButton/index.d.ts",+ "import": "./dist/IconButton/index.mjs",+ "require": "./dist/IconButton/index.js"+ },"./Kbd": {"source": "./src/Kbd/index.ts","types": "./dist/Kbd/index.d.ts",diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjsnew file mode 100644index 0000000000..3d03848d44--- /dev/null+++ b/packages/core/src/IconButton/IconButton.doc.mjs@@ -0,0 +1,102 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'IconButton',+ description:+ 'An icon-only button. Thin wrapper around XDSButton with isIconOnly always true.',++ keywords: ['icon-button', 'icon', 'button', 'toolbar', 'action', 'compact'],+ features: [+ 'Composition wrapper — delegates all behavior to XDSButton with isIconOnly=true',+ 'Explicit component name — greppable, codemod-safe, import-level detection',+ 'Same variants, sizes, and states as XDSButton',+ 'label prop becomes aria-label for accessibility',+ 'icon prop is required (enforced by TypeScript)',+ ],++ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Accessible label. Used as aria-label (not rendered as visible text).',+ required: true,+ },+ {+ name: 'icon',+ type: 'ReactNode',+ description: 'Icon element rendered inside the button.',+ required: true,+ },+ {+ name: 'variant',+ type: "\'primary\' | \'secondary\' | \'ghost\' | \'destructive\'",+ description: 'Visual style variant.',+ default: "\'secondary\'",+ },+ {+ name: 'size',+ type: "\'sm\' | \'md\' | \'lg\'",+ description: 'Size variant.',+ default: "\'md\'",+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: 'Shows a loading spinner and disables interaction.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disables the button.',+ default: 'false',+ },+ {+ name: 'tooltip',+ type: 'string',+ description: 'Tooltip text shown on hover.',+ },+ {+ name: 'onClick',+ type: '(e: MouseEvent) => void',+ description: 'Standard click handler.',+ },+ {+ name: 'onClickAction',+ type: '(e: MouseEvent) => void | Promise<void>',+ description: 'Async click handler with automatic loading state.',+ },+ ],++ examples: [+ {+ label: 'Ghost icon button',+ code: '<XDSIconButton label="Settings" icon={<GearIcon />} variant="ghost" />',+ },+ {+ label: 'Destructive icon button',+ code: '<XDSIconButton label="Delete" icon={<TrashIcon />} variant="destructive" />',+ },+ {+ label: 'Small emoji icon button',+ code: '<XDSIconButton label="Emoji" icon={<span>🚀</span>} variant="ghost" size="sm" />',+ },+ {+ label: 'Primary icon button with tooltip',+ code: '<XDSIconButton label="Add item" icon={<PlusIcon />} variant="primary" tooltip="Add a new item" />',+ },+ ],++ notes: [+ 'Prefer XDSIconButton over <XDSButton isIconOnly> for explicit intent',+ 'The label prop is always used as aria-label — required for accessibility',+ 'children and endContent are not accepted (omitted from props type)',+ 'All other XDSButton props (variant, size, onClick, etc.) are forwarded',+ ],++ accessibility: [+ 'Uses aria-label from the label prop for screen reader accessibility',+ 'Same keyboard and screen reader behavior as XDSButton with isIconOnly',+ ],+};diff --git a/packages/core/src/IconButton/XDSIconButton.test.tsx b/packages/core/src/IconButton/XDSIconButton.test.tsxnew file mode 100644index 0000000000..3c1a622bc3--- /dev/null+++ b/packages/core/src/IconButton/XDSIconButton.test.tsx@@ -0,0 +1,106 @@+/**+ * @file XDSIconButton.test.tsx+ * @input Uses vitest, @testing-library/react, XDSIconButton component+ * @output Unit tests for XDSIconButton component behavior+ * @position Testing; validates XDSIconButton.tsx implementation+ *+ * SYNC: When XDSIconButton.tsx 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 {XDSIconButton} from './XDSIconButton';++describe('XDSIconButton', () => {+ it('renders as an icon-only button with aria-label', () => {+ render(+ <XDSIconButton+ label="Settings"+ icon={<span data-testid="icon">⚙</span>}+ />,+ );+ const button = screen.getByRole('button', {name: 'Settings'});+ expect(button).toHaveAttribute('aria-label', 'Settings');+ expect(screen.getByTestId('icon')).toBeInTheDocument();+ });++ it('does not render label as visible text', () => {+ render(+ <XDSIconButton+ label="Settings"+ icon={<span data-testid="icon">⚙</span>}+ />,+ );+ const button = screen.getByRole('button');+ // The label text should not appear as visible content+ const visibleText = button.textContent;+ expect(visibleText).not.toContain('Settings');+ });++ it('forwards variant prop', () => {+ render(+ <XDSIconButton+ label="Delete"+ icon={<span>🗑</span>}+ variant="destructive"+ />,+ );+ expect(screen.getByRole('button', {name: 'Delete'})).toBeInTheDocument();+ });++ it('forwards size prop', () => {+ render(<XDSIconButton label="Add" icon={<span>+</span>} size="sm" />);+ expect(screen.getByRole('button', {name: 'Add'})).toBeInTheDocument();+ });++ it('handles click events', async () => {+ const user = userEvent.setup();+ const handleClick = vi.fn();+ render(+ <XDSIconButton+ label="Close"+ icon={<span>✕</span>}+ onClick={handleClick}+ />,+ );++ await user.click(screen.getByRole('button'));+ expect(handleClick).toHaveBeenCalledTimes(1);+ });++ it('is disabled when isDisabled is true', async () => {+ const user = userEvent.setup();+ const handleClick = vi.fn();+ render(+ <XDSIconButton+ label="Close"+ icon={<span>✕</span>}+ isDisabled+ onClick={handleClick}+ />,+ );++ const button = screen.getByRole('button');+ expect(button).toBeDisabled();+ await user.click(button);+ expect(handleClick).not.toHaveBeenCalled();+ });++ it('shows loading state', () => {+ render(<XDSIconButton label="Save" icon={<span>💾</span>} isLoading />);+ const button = screen.getByRole('button');+ expect(button).toBeDisabled();+ });++ it('forwards ref correctly', () => {+ const ref = vi.fn();+ render(<XDSIconButton label="Action" icon={<span>⚡</span>} ref={ref} />);+ expect(ref).toHaveBeenCalled();+ expect(ref.mock.calls[0][0]).toBeInstanceOf(HTMLButtonElement);+ });++ it('has displayName set', () => {+ expect(XDSIconButton.displayName).toBe('XDSIconButton');+ });+});diff --git a/packages/core/src/IconButton/XDSIconButton.tsx b/packages/core/src/IconButton/XDSIconButton.tsxnew file mode 100644index 0000000000..abaa63df2e--- /dev/null+++ b/packages/core/src/IconButton/XDSIconButton.tsx@@ -0,0 +1,52 @@+'use client';++/**+ * @file XDSIconButton.tsx+ * @input Uses XDSButton, XDSButtonProps+ * @output Exports XDSIconButton component, XDSIconButtonProps type+ * @position Composition wrapper over XDSButton for icon-only buttons+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/IconButton/IconButton.doc.mjs (props table, features)+ * - /packages/core/src/IconButton/XDSIconButton.test.tsx (tests)+ * - /packages/core/src/IconButton/index.ts (exports if types change)+ * - /apps/storybook/stories/IconButton.stories.tsx (storybook stories)+ */++import type {ReactNode} from 'react';+import {XDSButton} from '../Button/XDSButton';+import type {XDSButtonProps} from '../Button/XDSButton';++/**+ * Props for XDSIconButton.+ *+ * Omits `isIconOnly` (always true), `children` and `endContent` (not applicable+ * for icon-only buttons). `icon` is required.+ */+export interface XDSIconButtonProps extends Omit<+ XDSButtonProps,+ 'isIconOnly' | 'children' | 'endContent'+> {+ /** Icon element rendered inside the button (required). */+ icon: ReactNode;+}++/**+ * An icon-only button — a thin wrapper around XDSButton with `isIconOnly`+ * always set to true.+ *+ * Use this instead of `<XDSButton isIconOnly>` for explicit, greppable,+ * and codemod-safe icon-only button usage.+ *+ * @example+ * ```+ * <XDSIconButton label="Settings" icon={<GearIcon />} variant="ghost" />+ * <XDSIconButton label="Delete" icon={<TrashIcon />} variant="destructive" />+ * <XDSIconButton label="Emoji" icon={<span>🚀</span>} variant="ghost" size="sm" />+ * ```+ */+export function XDSIconButton({icon, ...props}: XDSIconButtonProps): ReactNode {+ return <XDSButton {...props} icon={icon} isIconOnly />;+}++XDSIconButton.displayName = 'XDSIconButton';diff --git a/packages/core/src/IconButton/index.ts b/packages/core/src/IconButton/index.tsnew file mode 100644index 0000000000..a473369de1--- /dev/null+++ b/packages/core/src/IconButton/index.ts@@ -0,0 +1,13 @@+'use client';++/**+ * @file index.ts+ * @input Imports XDSIconButton component and types from XDSIconButton.tsx+ * @output Exports XDSIconButton, XDSIconButtonProps+ * @position Component entry point; re-exported by /packages/core/src/index.ts+ *+ * SYNC: When modified, update this header and /packages/core/src/IconButton/IconButton.doc.mjs+ */++export {XDSIconButton} from './XDSIconButton';+export type {XDSIconButtonProps} from './XDSIconButton';diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex c2814f5b54..df1aff7df4 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -20,6 +20,7 @@ export * from './Badge';export * from './Banner';export * from './Breadcrumbs';export * from './Button';+export * from './IconButton';export * from './Card';export * from './Carousel';export * from './Calendar';