Skip to content

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

TypeScript

docs(ButtonGroup): drop the rule that arrows skip disabled members (#10203)

Cindy Zhangd88dff821854
diff --git a/.changeset/buttongroup-docs-no-skip-promise.md b/.changeset/buttongroup-docs-no-skip-promise.md
new file mode 100644
index 0000000000..66f704e3a4
--- /dev/null
+++ b/.changeset/buttongroup-docs-no-skip-promise.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] `ButtonGroup`'s docs no longer promise that arrow keys skip disabled members. Arrow keys still move between members, Home and End still jump to the ends, and the group is still one Tab stop.
+
+@cixzhang
diff --git a/docs/specs/components/ButtonGroup/ButtonGroup.spec.md b/docs/specs/components/ButtonGroup/ButtonGroup.spec.md
index cbec996548..343ec7b21c 100644
--- a/docs/specs/components/ButtonGroup/ButtonGroup.spec.md
+++ b/docs/specs/components/ButtonGroup/ButtonGroup.spec.md
@@ -38,10 +38,10 @@ system_specs: [spec:AST-038, spec:AST-085]
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public contract | None changes. ButtonGroup takes `label`, `orientation`, `size`, `elevation`, `isDisabled`, and Button or IconButton children. |
| Behavior | A labelled `role="group"` that joins its Button members into one connected surface, gives them a default size and its disabled state, owns one shared elevation, and is one Tab stop with arrow-key roving. |
-| End-user impact | Keyboard users reach the whole group with one Tab and move through it with arrows, which skip disabled members. A disabled group without tooltips has no Tab stop, so keyboard users cannot find it or hear that it is disabled. |
+| End-user impact | Keyboard users reach the whole group with one Tab and move through it with arrows. A disabled group without tooltips has no Tab stop, so keyboard users cannot find it or hear that it is disabled. |
| Builder impact | None. |
| Compatibility/readiness | No API or default change; its DOM change is listed below. Disabled members use native `disabled`, the Tab stop leaves disabled and busy-only members, and wrapped members lose connected geometry; all are listed under Current-state impact. |
-| Review checks | Reject a group without a name, gaps between members, rounded inner corners, a shadow on a member, more than one Tab stop, arrows that land on a disabled member, or arrows that steal keys from a member's open menu. |
+| Review checks | Reject a group without a name, gaps between members, rounded inner corners, a shadow on a member, more than one Tab stop, or arrows that steal keys from a member's open menu. |
| Governing rules | `family:buttons` FR3, FR8, FR10–FR12, AV5; `architecture:component-size-cascade` INV3–INV8; `spec:AST-085` FR1, FR7; `spec:AST-038` FR7, FR8. |
This table is a review projection; the body below is authoritative.
@@ -114,7 +114,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR6 | The group provides its resolved size to descendants up to the next layer boundary (`spec:AST-038` FR7, FR8): an explicit `size`, then the nearest outer provider, then `md`. A member's own `size` wins. | `architecture:component-size-cascade` INV3–INV8; current source; `spec:AST-038` FR7 |
| FR7 | While disabled, every Button member MUST be disabled under `component:Button` FR10: focusable with `aria-disabled`, inert, and never running its action, so the group keeps its Tab stop (`spec:AST-085` FR1, FR7). Implementation gap: members without a tooltip render native `disabled`, so a disabled group contributes no Tab stop. | `family:buttons` FR3; `spec:AST-085` FR7; current tests |
| FR8 | The group is one Tab stop. The stop starts on the first enabled member and moves with arrow navigation. A link member counts as a member. The stop MUST always sit on exactly one member, and a member that becomes busy or disabled MUST keep it (`component:Button` FR9, FR10; `spec:AST-085` FR1, FR7). Implementation gap: the group repairs the stop only after its own renders and when focus enters a member, and each repair keeps an enabled holder or gives the stop to the first enabled member. Between repairs the stop can sit on a member that has become busy-only, disabled, or unmounted, so the group can have a second stop or none; focus that arrives by pointer or by code does not take the stop, so the next Tab or Shift+Tab can stop inside the group; and a fully disabled group repairs nothing, so a group disabled from its first render gives each tooltip-bearing member its own stop and native-disabled members none. | `family:buttons` AV5; WAI-ARIA APG roving tabindex; current tests |
-| FR9 | Horizontal groups move with Left and Right in visual order, reversed under RTL; vertical groups move with Up and Down. Home and End jump to the first and last enabled member. Movement wraps at the ends and skips natively disabled and `aria-disabled` members, busy-only members (`component:Button` FR9) included; a member busy with an interruptible action stays in the order. | `family:buttons` AV5; current tests |
+| FR9 | Horizontal groups move with Left and Right in visual order, reversed under RTL; vertical groups move with Up and Down. Home and End jump to the first and last enabled member. Movement wraps at the ends. | `family:buttons` AV5; current tests |
| FR10 | Keys pressed inside a member's open layer (such as a DropdownMenu) belong to that layer, and the group keeps its Tab stop on its own members. A group inside a popover or other layer still handles its own arrow keys. The group's context does not reach Buttons rendered inside a member's layer (`spec:AST-038` FR7). | Current source and tests; `spec:AST-038` FR7 |
| FR11 | The root carries `astryx-button-group` and reflects `data-size`, `data-orientation`, and `data-elevation`. | `family:buttons` FR10; `architecture:component-theming-surface`; tests |
@@ -133,7 +133,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| Vertical | Column; Up and Down move focus; block-start dividers. | — |
| Elevated | Shadow on the group; members flat. | Tier. |
| Trailing DropdownMenu | The menu trigger keeps rounded trailing corners; arrows inside the open menu stay with it. | Menu content. |
-| One member disabled | Arrows skip it. Implementation gap: the Tab stop leaves it when the group repairs (FR8). | Tooltip present or not. |
+| One member disabled | Implementation gap: the Tab stop leaves it when the group repairs (FR8). | Tooltip present or not. |
| Group disabled | `aria-disabled` on the group; every member focusable and inert; one Tab stop. Implementation gap: native-disabled members give no Tab stop; disabled from the first render, tooltip-bearing members are one stop each (FR7, FR8). | — |
### Transformation and precedence order
@@ -193,7 +193,7 @@ carries no anatomy-theming map.
| FR11 (target, size) | Evidence gap: no test asserts `astryx-button-group` or `data-size` on the root | Each size | — | `audit:ButtonGroup/theming` |
| FR7, AR3 | `ButtonGroup.test.tsx` disabled cases | Group disabled | An operable member fails. Native-disabled and no-Tab-stop assertions match the FR7 gap. | `audit:ButtonGroup/accessibility` |
| FR8, AR2 | `ButtonGroup.test.tsx` roving-tabindex suite | Enter and leave; disabled member; unmount; becomes disabled; link | Two Tab stops or a lost stop fails. The suite asserts that a disabled member never holds the stop and that the stop is repaired away from it, matching the FR8 gap. Evidence gap: no test of a busy or self-unmounted holder, pointer focus, or a group disabled after mount. | `audit:ButtonGroup/accessibility` |
-| FR9, FR10, AR2 | `ButtonGroup.test.tsx` keyboard-navigation suite; `useListFocus.test.tsx` "useListFocus disabled-item skipping" for `aria-disabled` items and Home and End; `layerScopedContext.test.tsx` "ends group-owned disabled state while preserving explicit and inner-group state" for the layer boundary | Arrows, Home, End, vertical, RTL, open menu, group inside a popover | Wrong direction, no wrap, landing on a disabled member, stealing a menu's keys, or group state leaking into a member's layer fails. Evidence gap: no test skips a busy or tooltip-disabled Button member. | `audit:ButtonGroup/accessibility` |
+| FR9, FR10, AR2 | `ButtonGroup.test.tsx` keyboard-navigation suite; `useListFocus.test.tsx` "useListFocus disabled-item skipping" for Home and End, which reach enabled ends; `layerScopedContext.test.tsx` "ends group-owned disabled state while preserving explicit and inner-group state" for the layer boundary | Arrows, Home, End, vertical, RTL, open menu, group inside a popover | Wrong direction, no wrap, Home or End landing on a disabled member, stealing a menu's keys, or group state leaking into a member's layer fails. | `audit:ButtonGroup/accessibility` |
| FR2, FR3, FR4, FR6 | Evidence gap: no assertion of gap-free layout, divider paint, the absent press scale, non-Button children keeping their own paint, or member size inheritance beyond rendering | — | — | `audit:ButtonGroup/layout` |
| ORD2 | `ButtonGroup.test.tsx` elevation suite | Member with its own elevation | A member not reporting `none` fails. | `audit:ButtonGroup/theming` |
| ORD1, ORD3, PR1, AR4 | Evidence gap: no test asserts member size precedence, a member `isDisabled` inside an enabled group, when the Tab stop is repaired, or the member focus indicator | — | — | `audit:ButtonGroup/behavior` |
diff --git a/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
index 20cd9b1b3a..8979bda8ea 100644
--- a/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
+++ b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
@@ -94,7 +94,7 @@ export const docs = {
{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."},
{guidance: true, description: 'Name the group for what its buttons act on. The label is the group\'s accessible name and a screen reader reads it before each member.'},
- {guidance: true, description: 'Keep the group a single Tab stop. Arrow keys move between members along the orientation, Home/End jump to the ends, and disabled members are skipped. This is the WAI-ARIA APG roving tabindex technique: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex'},
+ {guidance: true, description: 'Keep the group a single Tab stop. Arrow keys move between members along the orientation, and Home/End jump to the ends. This is the WAI-ARIA APG roving tabindex technique: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex'},
{guidance: false, description: "Don't disable the group to show that an action is in flight. A disabled member drops focus, so a keyboard user loses their place; leave the group enabled and show progress on the button that started the work."},
],
anatomy: [
@@ -159,7 +159,7 @@ export const docsDense = {
{guidance: false, description: "Don't use for navigation. Use SegmentedControl or TabList."},
{guidance: false, description: "Don't nest ButtonGroups."},
{guidance: true, description: 'Label the group for what its buttons act on; it is the accessible name.'},
- {guidance: true, description: 'Single Tab stop; arrows move between members, Home/End to ends, disabled skipped (APG roving tabindex).'},
+ {guidance: true, description: 'Single Tab stop; arrows move between members, Home/End to ends (APG roving tabindex).'},
{guidance: true, description: 'Under the touch presentation a press tracks like a menu: slide across, the lifted button runs, a lift outside runs nothing. A mouse press acts as a native button\'s. Finger targets grow toward 44 px, up to half the gap to a neighbour; a menu trigger keeps its own opening.'},
{guidance: false, description: "Don't disable the group for an in-flight action; a disabled member drops focus."},
],
diff --git a/packages/core/src/ButtonGroup/ButtonGroup.test.tsx b/packages/core/src/ButtonGroup/ButtonGroup.test.tsx
index 535c5fd31d..b1a160c840 100644
--- a/packages/core/src/ButtonGroup/ButtonGroup.test.tsx
+++ b/packages/core/src/ButtonGroup/ButtonGroup.test.tsx
@@ -750,22 +750,6 @@ describe('ButtonGroup', () => {
expect(screen.getByRole('button', {name: 'Copy'})).toHaveFocus();
});
- it('skips a disabled member', async () => {
- const user = userEvent.setup();
- render(
- <ButtonGroup label="Actions">
- <Button label="Copy" />
- <Button label="Cut" isDisabled />
- <Button label="Paste" />
- </ButtonGroup>,
- );
-
- screen.getByRole('button', {name: 'Copy'}).focus();
-
- await user.keyboard('{ArrowRight}');
- expect(screen.getByRole('button', {name: 'Paste'})).toHaveFocus();
- });
-
it('leaves arrow keys to a member\u2019s open menu', async () => {
const user = userEvent.setup();
render(
diff --git a/packages/core/src/ButtonGroup/ButtonGroup.tsx b/packages/core/src/ButtonGroup/ButtonGroup.tsx
index 5df3d49e1c..a27fac9183 100644
--- a/packages/core/src/ButtonGroup/ButtonGroup.tsx
+++ b/packages/core/src/ButtonGroup/ButtonGroup.tsx
@@ -145,8 +145,8 @@ const elevationStyles = stylex.create({
* styles in pure CSS.
*
* The group is a single tab stop: arrow keys move between members along the
- * orientation, Home/End jump to the ends, focus wraps, and disabled members are
- * skipped (the APG roving tabindex technique, via `useListFocus`).
+ * orientation, Home/End jump to the ends, and focus wraps (the APG roving
+ * tabindex technique, via `useListFocus`).
*
* Members that render their own layer — a Button with a `tooltip`, or a
* DropdownMenu — compose correctly, including as the trailing member.