An open source design system that's fully customizable and agent ready
TypeScript
feat(ButtonGroup): add XDSButtonGroup component (#210) (#2202)
Andrey Goder061a16da7f10
diff --git a/apps/storybook/stories/ButtonGroup.stories.tsx b/apps/storybook/stories/ButtonGroup.stories.tsxnew file mode 100644index 0000000000..5c974bb748--- /dev/null+++ b/apps/storybook/stories/ButtonGroup.stories.tsx@@ -0,0 +1,161 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import type {Meta, StoryObj} from '@storybook/react';+import {XDSButtonGroup} from '@xds/core/ButtonGroup';+import {XDSButton} from '@xds/core/Button';+import {XDSIconButton} from '@xds/core/IconButton';+import {XDSIcon} from '@xds/core/Icon';+import {+ ClipboardDocumentIcon,+ ScissorsIcon,+ ClipboardIcon,+ ArrowUturnLeftIcon,+ ArrowUturnRightIcon,+ BoldIcon,+ ItalicIcon,+ UnderlineIcon,+ ChevronDownIcon,+} from '@heroicons/react/24/outline';++const meta: Meta<typeof XDSButtonGroup> = {+ title: 'Core/Buttons/ButtonGroup',+ component: XDSButtonGroup,+ tags: ['autodocs'],+ argTypes: {+ orientation: {control: 'select', options: ['horizontal', 'vertical']},+ size: {control: 'select', options: ['sm', 'md', 'lg']},+ },+};++export default meta;+type Story = StoryObj<typeof XDSButtonGroup>;++const iconSize = {width: 16, height: 16} as const;++/** Basic horizontal button group with text buttons. */+export const Horizontal: Story = {+ render: () => (+ <XDSButtonGroup label="Clipboard actions">+ <XDSButton+ label="Copy"+ icon={<ClipboardDocumentIcon style={iconSize} />}+ />+ <XDSButton label="Cut" icon={<ScissorsIcon style={iconSize} />} />+ <XDSButton label="Paste" icon={<ClipboardIcon style={iconSize} />} />+ </XDSButtonGroup>+ ),+};++/** Vertical button group. */+export const Vertical: Story = {+ render: () => (+ <XDSButtonGroup label="Actions" orientation="vertical">+ <XDSButton label="Copy" />+ <XDSButton label="Cut" />+ <XDSButton label="Paste" />+ </XDSButtonGroup>+ ),+};++/** Icon-only button group for compact toolbars. */+export const IconOnly: Story = {+ render: () => (+ <XDSButtonGroup label="Text formatting">+ <XDSIconButton+ label="Bold"+ icon={<XDSIcon icon={BoldIcon} size="sm" />}+ />+ <XDSIconButton+ label="Italic"+ icon={<XDSIcon icon={ItalicIcon} size="sm" />}+ />+ <XDSIconButton+ label="Underline"+ icon={<XDSIcon icon={UnderlineIcon} size="sm" />}+ />+ </XDSButtonGroup>+ ),+};++/** Undo/redo pair with ghost variant. */+export const GhostPair: Story = {+ render: () => (+ <XDSButtonGroup label="History">+ <XDSButton+ label="Undo"+ variant="ghost"+ icon={<ArrowUturnLeftIcon style={iconSize} />}+ isIconOnly+ />+ <XDSButton+ label="Redo"+ variant="ghost"+ icon={<ArrowUturnRightIcon style={iconSize} />}+ isIconOnly+ />+ </XDSButtonGroup>+ ),+};++/** All three sizes side by side. */+export const Sizes: Story = {+ render: () => (+ <div style={{display: 'flex', gap: 16, alignItems: 'center'}}>+ <XDSButtonGroup label="Small actions" size="sm">+ <XDSButton label="Copy" />+ <XDSButton label="Paste" />+ </XDSButtonGroup>+ <XDSButtonGroup label="Medium actions" size="md">+ <XDSButton label="Copy" />+ <XDSButton label="Paste" />+ </XDSButtonGroup>+ <XDSButtonGroup label="Large actions" size="lg">+ <XDSButton label="Copy" />+ <XDSButton label="Paste" />+ </XDSButtonGroup>+ </div>+ ),+};++/** Primary variant button group. */+export const PrimaryVariant: Story = {+ render: () => (+ <XDSButtonGroup label="Save options">+ <XDSButton label="Save" variant="primary" />+ <XDSButton+ label="Save options"+ variant="primary"+ icon={<ChevronDownIcon style={iconSize} />}+ isIconOnly+ />+ </XDSButtonGroup>+ ),+};++/** Two-button group (common split button pattern). */+export const SplitButton: Story = {+ render: () => (+ <XDSButtonGroup label="Merge options">+ <XDSButton label="Merge pull request" variant="primary" />+ <XDSButton+ label="More merge options"+ variant="primary"+ icon={<ChevronDownIcon style={iconSize} />}+ isIconOnly+ />+ </XDSButtonGroup>+ ),+};++/** Mixed button and icon button children. */+export const Mixed: Story = {+ render: () => (+ <XDSButtonGroup label="Edit actions">+ <XDSButton label="Edit" />+ <XDSIconButton+ label="More options"+ icon={<ChevronDownIcon style={iconSize} />}+ />+ </XDSButtonGroup>+ ),+};diff --git a/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.doc.mjs b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.doc.mjsnew file mode 100644index 0000000000..4989840e7b--- /dev/null+++ b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.doc.mjs@@ -0,0 +1,12 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'ButtonGroup',+ name: 'ButtonGroup',+ isReady: true,+ aspectRatio: 16 / 9,+ isShowcase: true,+ componentsUsed: ['Button', 'ButtonGroup', 'Icon', 'IconButton', 'Layout'],+};diff --git a/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.tsx b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.tsxnew file mode 100644index 0000000000..b0ff54dc09--- /dev/null+++ b/packages/cli/templates/blocks/components/ButtonGroup/ButtonGroupShowcase.tsx@@ -0,0 +1,38 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {XDSButtonGroup} from '@xds/core/ButtonGroup';+import {XDSButton} from '@xds/core/Button';+import {XDSIconButton} from '@xds/core/IconButton';+import {XDSStack} from '@xds/core/Layout';+import {XDSIcon} from '@xds/core/Icon';+import {+ ClipboardDocumentIcon,+ ScissorsIcon,+ ClipboardIcon,+ ChevronDownIcon,+} from '@heroicons/react/24/outline';++export default function ButtonGroupShowcase() {+ return (+ <XDSStack direction="horizontal" gap={6} vAlign="center">+ <XDSButtonGroup label="Clipboard actions">+ <XDSButton+ label="Copy"+ icon={<XDSIcon icon={ClipboardDocumentIcon} />}+ />+ <XDSButton label="Cut" icon={<XDSIcon icon={ScissorsIcon} />} />+ <XDSButton label="Paste" icon={<XDSIcon icon={ClipboardIcon} />} />+ </XDSButtonGroup>+ <XDSButtonGroup label="Save options">+ <XDSButton label="Save" variant="primary" />+ <XDSIconButton+ label="Save options"+ variant="primary"+ icon={<XDSIcon icon={ChevronDownIcon} />}+ />+ </XDSButtonGroup>+ </XDSStack>+ );+}diff --git a/packages/core/package.json b/packages/core/package.jsonindex 1577e41fc5..4ef970919d 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -121,6 +121,12 @@"import": "./dist/Button/index.mjs","require": "./dist/Button/index.js"},+ "./ButtonGroup": {+ "source": "./src/ButtonGroup/index.ts",+ "types": "./dist/ButtonGroup/index.d.ts",+ "import": "./dist/ButtonGroup/index.mjs",+ "require": "./dist/ButtonGroup/index.js"+ },"./Calendar": {"source": "./src/Calendar/index.ts","types": "./dist/Calendar/index.d.ts",diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsxindex 4e1d262d10..0a43cb19c1 100644--- a/packages/core/src/Button/XDSButton.tsx+++ b/packages/core/src/Button/XDSButton.tsx@@ -26,6 +26,7 @@ import {sizeVars,spacingVars,radiusVars,+ borderVars,durationVars,easeVars,fontWeightVars,@@ -36,6 +37,7 @@ import {XDSSpinner} from '../Spinner';import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';import {useXDSSize} from '../SizeContext/XDSSizeContext';+import {useXDSButtonGroup} from '../ButtonGroup/XDSButtonGroupContext';import {xdsClassName, mergeProps} from '../utils';import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';import type {XDSLinkComponentType} from '../Link/types';@@ -392,6 +394,69 @@ const loadingStyles = stylex.create({},});+const groupStyles = stylex.create({+ horizontal: {+ borderStartStartRadius: {+ default: 0,+ ':first-child': radiusVars['--radius-element'],+ },+ borderEndStartRadius: {+ default: 0,+ ':first-child': radiusVars['--radius-element'],+ },+ borderStartEndRadius: {+ default: 0,+ ':last-child': radiusVars['--radius-element'],+ },+ borderEndEndRadius: {+ default: 0,+ ':last-child': radiusVars['--radius-element'],+ },+ borderInlineStartWidth: {+ default: borderVars['--border-width'],+ ':first-child': 0,+ },+ borderInlineStartStyle: {+ default: 'solid' as const,+ ':first-child': 'none' as const,+ },+ borderInlineStartColor: colorVars['--color-border'],+ },+ vertical: {+ borderStartStartRadius: {+ default: 0,+ ':first-child': radiusVars['--radius-element'],+ },+ borderStartEndRadius: {+ default: 0,+ ':first-child': radiusVars['--radius-element'],+ },+ borderEndStartRadius: {+ default: 0,+ ':last-child': radiusVars['--radius-element'],+ },+ borderEndEndRadius: {+ default: 0,+ ':last-child': radiusVars['--radius-element'],+ },+ borderBlockStartWidth: {+ default: borderVars['--border-width'],+ ':first-child': 0,+ },+ borderBlockStartStyle: {+ default: 'solid' as const,+ ':first-child': 'none' as const,+ },+ borderBlockStartColor: colorVars['--color-border'],+ },+ onSolidHorizontal: {+ borderInlineStartColor: colorVars['--color-on-accent'],+ },+ onSolidVertical: {+ borderBlockStartColor: colorVars['--color-on-accent'],+ },+});+/*** A versatile button component with multiple variants.*@@ -441,11 +506,13 @@ export function XDSButton({...props}: XDSButtonProps): ReactNode {const size = useXDSSize(sizeProp, 'md');+ const buttonGroup = useXDSButtonGroup();const [isPending, startTransition] = useTransition();const actionInFlightRef = useRef(false);const isLoadingState = isLoading || isPending;- const buttonDisabled = isDisabled || isLoadingState;+ const groupDisabled = buttonGroup?.isDisabled ?? false;+ const buttonDisabled = isDisabled || groupDisabled || isLoadingState;const useLightSpinner = variant === 'primary' || variant === 'destructive';// isIconOnly prop is the source of truth for icon-only rendering.// When false (default), label is always rendered as visible text.@@ -505,6 +572,15 @@ export function XDSButton({useAriaDisabled && styles.ariaDisabled,isLoadingState && loadingStyles.loading,renderAsLink && styles.link,+ buttonGroup &&+ (buttonGroup.orientation === 'horizontal'+ ? groupStyles.horizontal+ : groupStyles.vertical),+ buttonGroup &&+ (variant === 'primary' || variant === 'destructive') &&+ (buttonGroup.orientation === 'horizontal'+ ? groupStyles.onSolidHorizontal+ : groupStyles.onSolidVertical),xstyle,);diff --git a/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjsnew file mode 100644index 0000000000..1f038d77b3--- /dev/null+++ b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs@@ -0,0 +1,119 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'ButtonGroup',+ group: 'Button',+ keywords: ["button-group","connected","split","toolbar","actions","grouped","buttons"],+ playground: {+ defaults: {+ label: 'Actions',+ },+ },+ theming: {+ targets: [+ {className: 'xds-button-group'},+ ],+ },+ components: [+ {+ name: 'XDSButtonGroup',+ description: 'Groups multiple buttons together with connected styling — shared borders, proper border-radius handling (only on outer edges), and horizontal or vertical orientation.',+ props: [+ {name: 'children', type: 'ReactNode', description: 'XDSButton or XDSIconButton children.', required: true, slotElements: [{__element: 'XDSButton', props: {label: 'Action'}}]},+ {name: 'label', type: 'string', description: 'Accessible label for the group (aria-label).', required: true},+ {name: 'orientation', type: "'horizontal' | 'vertical'", description: 'Layout direction of the button group.', default: "'horizontal'"},+ {name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Default size for buttons in the group. Individual buttons can override.', default: "'md'"},+ {name: 'isDisabled', type: 'boolean', description: 'Whether all buttons in the group are disabled.', default: 'false'},+ {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},+ {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization. Must be a stylex.create() value.'},+ {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},+ ],+ },+ ],+ usage: {+ description:+ 'ButtonGroup joins related actions into a single connected control. Use it when multiple buttons represent related choices or operations that belong together visually — like copy/cut/paste, or undo/redo.',+ bestPractices: [+ {guidance: true, description: 'Group buttons that perform related actions on the same object — like copy, cut, paste on selected text.'},+ {guidance: true, description: 'Use the same variant for all buttons in a group so they look like a single connected unit.'},+ {guidance: true, description: 'Keep groups small (2–4 buttons). For more actions, use a Toolbar or DropdownMenu instead.'},+ {guidance: false, description: "Don't mix wildly different actions — a Save button next to a Delete button in the same group is confusing."},+ {guidance: false, description: "Don't use ButtonGroup for navigation — use SegmentedControl or TabList for switching between views."},+ {guidance: false, description: "Don't nest ButtonGroups. If you need multiple groups, place them side by side with a gap."},+ ],+ anatomy: [+ {name: 'Button', required: true, description: 'One or more XDSButton or XDSIconButton children that form the connected group.'},+ {name: 'Divider', required: false, description: 'A thin border between buttons, rendered automatically by the group.'},+ ],+ },+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsZh = {+ components: [+ {+ name: 'XDSButtonGroup',+ description: '将多个按钮组合在一起,带有连接样式 — 共享边框、正确的圆角处理(仅外边缘),以及水平或垂直方向。',+ propDescriptions: {+ children: 'XDSButton 或 XDSIconButton 子元素。',+ label: '按钮组的无障碍标签 (aria-label)。',+ orientation: '按钮组的布局方向。',+ size: '组内按钮的默认尺寸。单个按钮可覆盖。',+ isDisabled: '组内所有按钮是否禁用。',+ ref: '转发到根元素的引用。',+ xstyle: 'StyleX 样式,用于布局自定义。必须是 stylex.create() 的值。',+ 'data-testid': '自动化测试的选择器。',+ },+ },+ ],+ usage: {+ description:+ 'ButtonGroup 将相关操作连接成一个控件。当多个按钮表示对同一对象的相关操作时使用 — 如复制/剪切/粘贴,或撤销/重做。',+ bestPractices: [+ {guidance: true, description: '将对同一对象执行相关操作的按钮分组 — 如对选中文本的复制、剪切、粘贴。'},+ {guidance: true, description: '组内所有按钮使用相同的变体,使其看起来像一个连接的整体。'},+ {guidance: true, description: '保持组较小(2-4 个按钮)。更多操作请使用工具栏或下拉菜单。'},+ {guidance: false, description: '不要混合差异很大的操作 — 将保存按钮和删除按钮放在同一组中会令人困惑。'},+ {guidance: false, description: '不要使用 ButtonGroup 进行导航 — 使用 SegmentedControl 或 TabList 切换视图。'},+ {guidance: false, description: '不要嵌套 ButtonGroup。如需多个组,请并排放置并留有间隔。'},+ ],+ anatomy: [+ {name: '按钮', required: true, description: '一个或多个 XDSButton 或 XDSIconButton 子元素,形成连接的组。'},+ {name: '分隔线', required: false, description: '按钮之间的细边框,由组自动渲染。'},+ ],+ },+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsDense = {+ description: 'connected button group w/ shared borders, outer-only radius, horizontal/vertical',+ usage: {+ description:+ 'ButtonGroup joins related actions into a single connected control. Use for related operations on the same object.',+ bestPractices: [+ {guidance: true, description: 'Group related actions on the same object — copy/cut/paste, undo/redo.'},+ {guidance: true, description: 'Same variant for all buttons to look like one unit.'},+ {guidance: true, description: 'Keep groups small (2–4 buttons). Use Toolbar or DropdownMenu for more.'},+ {guidance: false, description: "Don't mix unrelated actions in one group."},+ {guidance: false, description: "Don't use for navigation — use SegmentedControl or TabList."},+ {guidance: false, description: "Don't nest ButtonGroups."},+ ],+ },+ components: [+ {+ name: 'XDSButtonGroup',+ description: 'connected button group w/ shared borders, outer-only radius',+ propDescriptions: {+ children: 'XDSButton or XDSIconButton children',+ label: 'a11y label (aria-label)',+ orientation: 'layout direction',+ size: 'default btn size; individual btns override',+ isDisabled: 'all btns disabled',+ xstyle: 'StyleX layout styles; must be stylex.create() value',+ 'data-testid': 'test selector',+ },+ },+ ],+};diff --git a/packages/core/src/ButtonGroup/XDSButtonGroup.test.tsx b/packages/core/src/ButtonGroup/XDSButtonGroup.test.tsxnew file mode 100644index 0000000000..b1cb40f3c7--- /dev/null+++ b/packages/core/src/ButtonGroup/XDSButtonGroup.test.tsx@@ -0,0 +1,188 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file XDSButtonGroup.test.tsx+ * @input Uses vitest, @testing-library/react, ButtonGroup and Button components+ * @output Unit tests for XDSButtonGroup+ * @position Testing; validates ButtonGroup component implementation+ *+ * SYNC: When ButtonGroup component changes, update tests to match new behavior+ */++import {createRef} from 'react';+import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import {XDSButtonGroup} from './XDSButtonGroup';+import {XDSButton} from '../Button';+import {XDSIconButton} from '../IconButton';++describe('XDSButtonGroup', () => {+ it('renders a group with aria-label', () => {+ render(+ <XDSButtonGroup label="Actions">+ <XDSButton label="Copy" />+ <XDSButton label="Cut" />+ <XDSButton label="Paste" />+ </XDSButtonGroup>,+ );++ const group = screen.getByRole('group');+ expect(group).toBeInTheDocument();+ expect(group).toHaveAttribute('aria-label', 'Actions');+ });++ it('renders all child buttons', () => {+ render(+ <XDSButtonGroup label="Actions">+ <XDSButton label="Copy" />+ <XDSButton label="Cut" />+ <XDSButton label="Paste" />+ </XDSButtonGroup>,+ );++ expect(screen.getByRole('button', {name: 'Copy'})).toBeInTheDocument();+ expect(screen.getByRole('button', {name: 'Cut'})).toBeInTheDocument();+ expect(screen.getByRole('button', {name: 'Paste'})).toBeInTheDocument();+ });++ it('works with XDSIconButton children', () => {+ render(+ <XDSButtonGroup label="Text formatting">+ <XDSIconButton+ label="Bold"+ icon={<span data-testid="bold-icon">B</span>}+ />+ <XDSIconButton+ label="Italic"+ icon={<span data-testid="italic-icon">I</span>}+ />+ </XDSButtonGroup>,+ );++ expect(screen.getByRole('button', {name: 'Bold'})).toBeInTheDocument();+ expect(screen.getByRole('button', {name: 'Italic'})).toBeInTheDocument();+ });++ it('applies data-testid', () => {+ render(+ <XDSButtonGroup label="Actions" data-testid="my-group">+ <XDSButton label="Copy" />+ </XDSButtonGroup>,+ );++ expect(screen.getByTestId('my-group')).toBeInTheDocument();+ });++ it('forwards ref to the root element', () => {+ const ref = createRef<HTMLDivElement>();+ render(+ <XDSButtonGroup label="Actions" ref={ref}>+ <XDSButton label="Copy" />+ </XDSButtonGroup>,+ );++ expect(ref.current).toBeInstanceOf(HTMLDivElement);+ expect(ref.current).toBe(screen.getByRole('group'));+ });++ it('sets aria-orientation', () => {+ const {rerender} = render(+ <XDSButtonGroup label="Actions">+ <XDSButton label="Copy" />+ </XDSButtonGroup>,+ );++ expect(screen.getByRole('group')).toHaveAttribute(+ 'aria-orientation',+ 'horizontal',+ );++ rerender(+ <XDSButtonGroup label="Actions" orientation="vertical">+ <XDSButton label="Copy" />+ </XDSButtonGroup>,+ );++ expect(screen.getByRole('group')).toHaveAttribute(+ 'aria-orientation',+ 'vertical',+ );+ });++ it('renders with vertical orientation', () => {+ render(+ <XDSButtonGroup label="Actions" orientation="vertical">+ <XDSButton label="Copy" />+ <XDSButton label="Cut" />+ </XDSButtonGroup>,+ );++ const group = screen.getByRole('group');+ expect(group).toBeInTheDocument();+ expect(screen.getByRole('button', {name: 'Copy'})).toBeInTheDocument();+ expect(screen.getByRole('button', {name: 'Cut'})).toBeInTheDocument();+ });++ it('renders with different sizes', () => {+ const {rerender} = render(+ <XDSButtonGroup label="Actions" size="sm">+ <XDSButton label="Copy" />+ </XDSButtonGroup>,+ );+ expect(screen.getByRole('button', {name: 'Copy'})).toBeInTheDocument();++ rerender(+ <XDSButtonGroup label="Actions" size="lg">+ <XDSButton label="Copy" />+ </XDSButtonGroup>,+ );+ expect(screen.getByRole('button', {name: 'Copy'})).toBeInTheDocument();+ });++ it('disables all buttons when isDisabled is true', () => {+ render(+ <XDSButtonGroup label="Actions" isDisabled>+ <XDSButton label="Copy" />+ <XDSButton label="Cut" />+ </XDSButtonGroup>,+ );++ expect(screen.getByRole('group')).toHaveAttribute('aria-disabled', 'true');+ expect(screen.getByRole('button', {name: 'Copy'})).toBeDisabled();+ expect(screen.getByRole('button', {name: 'Cut'})).toBeDisabled();+ });++ it('does not set aria-disabled when not disabled', () => {+ render(+ <XDSButtonGroup label="Actions">+ <XDSButton label="Copy" />+ </XDSButtonGroup>,+ );++ expect(screen.getByRole('group')).not.toHaveAttribute('aria-disabled');+ });++ it('renders a single button without errors', () => {+ render(+ <XDSButtonGroup label="Actions">+ <XDSButton label="Copy" />+ </XDSButtonGroup>,+ );++ expect(screen.getByRole('button', {name: 'Copy'})).toBeInTheDocument();+ });++ it('renders mixed Button and IconButton children', () => {+ render(+ <XDSButtonGroup label="Edit actions">+ <XDSButton label="Edit" />+ <XDSIconButton label="More options" icon={<span>▼</span>} />+ </XDSButtonGroup>,+ );++ expect(screen.getByRole('button', {name: 'Edit'})).toBeInTheDocument();+ expect(+ screen.getByRole('button', {name: 'More options'}),+ ).toBeInTheDocument();+ });+});diff --git a/packages/core/src/ButtonGroup/XDSButtonGroup.tsx b/packages/core/src/ButtonGroup/XDSButtonGroup.tsxnew file mode 100644index 0000000000..bec618dbb7--- /dev/null+++ b/packages/core/src/ButtonGroup/XDSButtonGroup.tsx@@ -0,0 +1,171 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file XDSButtonGroup.tsx+ * @input Uses React, StyleX, XDSButton/XDSIconButton children+ * @output Exports XDSButtonGroup component, context, and types+ * @position Groups buttons with connected styling; consumed by index.ts+ *+ * Children (XDSButton, XDSIconButton) consume the ButtonGroup context to+ * apply position-aware styles using CSS :first-child / :last-child+ * pseudo-classes — no cloneElement or wrapper divs needed.+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/ButtonGroup/ButtonGroup.doc.mjs (props table, features)+ * - /packages/core/src/ButtonGroup/XDSButtonGroup.test.tsx (tests)+ * - /packages/core/src/ButtonGroup/index.ts (exports if types change)+ * - /apps/storybook/stories/ButtonGroup.stories.tsx (storybook stories)+ * - /packages/cli/templates/blocks/components/ButtonGroup/ (showcase blocks)+ */++import {useMemo, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {XDSButtonSize} from '../Button';+import {XDSSizeProvider, useXDSSize} from '../SizeContext/XDSSizeContext';+import {useListFocus} from '../hooks/useListFocus';+import {xdsClassName, mergeProps} from '../utils';+import type {XDSBaseProps} from '../XDSBaseProps';+import {XDSButtonGroupContext} from './XDSButtonGroupContext';+import type {XDSButtonGroupOrientation} from './XDSButtonGroupContext';++// =============================================================================+// Props+// =============================================================================++export interface XDSButtonGroupProps extends XDSBaseProps<HTMLDivElement> {+ /** Ref forwarded to the root element. */+ ref?: React.Ref<HTMLDivElement>;++ /**+ * XDSButton or XDSIconButton children.+ */+ children: ReactNode;++ /**+ * Accessible label for the group (used as aria-label).+ */+ label: string;++ /**+ * Orientation of the button group.+ * @default 'horizontal'+ */+ orientation?: XDSButtonGroupOrientation;++ /**+ * Default size for buttons in the group.+ * Individual buttons can override this with their own `size` prop.+ * @default 'md'+ */+ size?: XDSButtonSize;++ /**+ * Whether all buttons in the group are disabled.+ * @default false+ */+ isDisabled?: boolean;++ /**+ * Test ID for testing frameworks.+ */+ 'data-testid'?: string;+}++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ group: {+ display: 'inline-flex',+ alignItems: 'stretch',+ },+ vertical: {+ flexDirection: 'column',+ },+});++// =============================================================================+// Component+// =============================================================================++/**+ * Groups buttons with connected styling — shared borders, proper border-radius+ * handling (only on outer edges), and horizontal or vertical orientation.+ *+ * Children automatically detect the group via context and apply position-aware+ * styles using CSS :first-child / :last-child pseudo-classes.+ *+ * @example+ * ```+ * <XDSButtonGroup label="Actions">+ * <XDSButton label="Copy" />+ * <XDSButton label="Cut" />+ * <XDSButton label="Paste" />+ * </XDSButtonGroup>+ * ```+ */+export function XDSButtonGroup({+ children,+ label,+ orientation = 'horizontal',+ size: sizeProp,+ isDisabled = false,+ xstyle,+ className,+ style,+ ref,+ 'data-testid': testId,+ ...props+}: XDSButtonGroupProps): ReactNode {+ const size = useXDSSize(sizeProp, 'md');++ const {listRef, handleKeyDown} = useListFocus({+ itemSelector: 'button, [tabindex="0"]',+ orientation,+ });++ const contextValue = useMemo(+ () => ({orientation, isDisabled}),+ [orientation, isDisabled],+ );++ return (+ <XDSButtonGroupContext.Provider value={contextValue}>+ <XDSSizeProvider value={size}>+ <div+ ref={(node: HTMLDivElement | null) => {+ (listRef as React.MutableRefObject<HTMLElement | null>).current =+ node;+ if (typeof ref === 'function') ref(node);+ else if (ref)+ (ref as React.MutableRefObject<HTMLDivElement | null>).current =+ node;+ }}+ role="group"+ aria-label={label}+ onKeyDown={handleKeyDown}+ aria-orientation={orientation}+ aria-disabled={isDisabled || undefined}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('button-group', {size}),+ stylex.props(+ styles.group,+ orientation === 'vertical' && styles.vertical,+ xstyle,+ ),+ className,+ style,+ )}+ {...props}>+ {children}+ </div>+ </XDSSizeProvider>+ </XDSButtonGroupContext.Provider>+ );+}++XDSButtonGroup.displayName = 'XDSButtonGroup';diff --git a/packages/core/src/ButtonGroup/XDSButtonGroupContext.ts b/packages/core/src/ButtonGroup/XDSButtonGroupContext.tsnew file mode 100644index 0000000000..2ee8aab029--- /dev/null+++ b/packages/core/src/ButtonGroup/XDSButtonGroupContext.ts@@ -0,0 +1,30 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file XDSButtonGroupContext.ts+ * @input None (pure context definition)+ * @output Exports ButtonGroup context and useXDSButtonGroup hook+ * @position Shared context; consumed by XDSButton for group-aware styling+ */++import {createContext, useContext} from 'react';++export type XDSButtonGroupOrientation = 'horizontal' | 'vertical';++export interface XDSButtonGroupContextValue {+ orientation: XDSButtonGroupOrientation;+ isDisabled: boolean;+}++export const XDSButtonGroupContext =+ createContext<XDSButtonGroupContextValue | null>(null);++/**+ * Hook for XDSButton to detect when it's inside a ButtonGroup.+ * Returns null when used outside a group.+ */+export function useXDSButtonGroup(): XDSButtonGroupContextValue | null {+ return useContext(XDSButtonGroupContext);+}diff --git a/packages/core/src/ButtonGroup/index.ts b/packages/core/src/ButtonGroup/index.tsnew file mode 100644index 0000000000..bc40a596b7--- /dev/null+++ b/packages/core/src/ButtonGroup/index.ts@@ -0,0 +1,16 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file index.ts+ * @input Imports from XDSButtonGroup.tsx and XDSButtonGroupContext.ts+ * @output Exports XDSButtonGroup, context hook, and types+ * @position Component entry point; re-exported by /packages/core/src/index.ts+ */++export {XDSButtonGroup} from './XDSButtonGroup';+export type {XDSButtonGroupProps} from './XDSButtonGroup';++export {useXDSButtonGroup} from './XDSButtonGroupContext';+export type {XDSButtonGroupOrientation} from './XDSButtonGroupContext';diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 25f287421e..8e03e29c90 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -23,6 +23,7 @@ export * from './Banner';export * from './Blockquote';export * from './Breadcrumbs';export * from './Button';+export * from './ButtonGroup';export * from './IconButton';export * from './Card';export * from './ClickableCard';