feat(core): Add focus management primitives for 2nd-gen architecture

[caseyisonit]

Description

Implements the core focus management infrastructure for 2nd-gen Spectrum Web Components, as defined in the Focus Management Proposal. This PR delivers the foundational primitives that all component migrations will build on.

Core Utilities

• get-active-element.ts — Shadow DOM-aware activeElement traversal that follows shadowRoot.activeElement chains to find the deepest focused element
• focusable-selectors.ts — Standard HTML focusableSelector and tabbableSelector strings (removes 1st-gen [focusable] attribute workaround in favor of native delegatesFocus)
• hasVisibleFocusInTree() cleanup — Refactored from ~30 lines to 3 in spectrum-element.ts, removing dead ancestor-chain traversal code and legacy .focus-visible polyfill fallback. Now delegates to the new getActiveElement() utility.

Controller

• FocusgroupNavigationController — Implements the roving tabindex pattern from the WAI-ARIA APG and directional navigation aligned with the proposed focusgroup HTML attribute (Open UI), with a polyfill until browsers ship native support.

  Key capabilities:

  • Keeps exactly one item in the tab order (tabindex="0") per composite widget
  • Supports horizontal, vertical, both, and grid direction modes
  • Optional wrap, last-focused memory, skip-disabled, and pageStep (Page Up/Down navigation)
  • Grid mode uses bounding-rect layout for row/column navigation with Ctrl+Home/Ctrl+End support
  • Printable character typeahead via focusFirstItemByTextPrefix()
  • Dispatches a bubbling, composed swc-focusgroup-navigation-active-change custom event on active item changes
  • Flat single-file architecture (no base class inheritance from 1st-gen)
  • Listener scope defaults to host.renderRoot for shadow DOM encapsulation

  Supersedes the 1st-gen FocusGroupController + RovingTabindexController split with a single, consolidated controller.

Mixin

• DisabledMixin — Standalone mixin extracted from 1st-gen Focusable base class. Adds a reactive disabled property with aria-disabled, tabindex management, and blur-on-disable. Uses aria-disabled on the host so elements remain discoverable by assistive technology.

Documentation & Testing

• Contributor guide (CONTRIBUTOR-DOCS/01_contributor-guides/13_focus-management.md) — Comprehensive focus management guide for contributors
• Controller composition style guide — Updated 14_controller-composition.md with focus controller patterns
• Storybook stories — Interactive demos for all FocusgroupNavigationController modes (horizontal, vertical, both, grid, wrap, memory, skipDisabled, pageStep, typeahead)
• Unit tests — Test suite for FocusgroupNavigationController
• Controller documentation — focus-group-navigation-controller.md with API reference
• Storybook config — Added storybook configuration for 2nd-gen controller stories

File Structure

2nd-gen/packages/core/
├── controllers/
│   ├── focus-group-navigation-controller.ts              NEW (re-export entry)
│   ├── focus-group-navigation-controller/
│   │   ├── src/focus-group-navigation-controller.ts      NEW (implementation)
│   │   ├── stories/focus-group-navigation-controller.stories.ts  NEW
│   │   ├── test/focus-group-navigation-controller.test.ts        NEW
│   │   └── focus-group-navigation-controller.md          NEW
│   └── index.ts                                          UPDATED
├── mixins/
│   ├── disabled-mixin.ts                                 NEW
│   └── index.ts                                          UPDATED
├── utils/
│   ├── get-active-element.ts                             NEW
│   ├── focusable-selectors.ts                            NEW
│   └── index.ts                                          UPDATED
├── element/
│   └── spectrum-element.ts                               UPDATED (hasVisibleFocusInTree cleanup)
├── overview.mdx                                          UPDATED
└── package.json                                          UPDATED

CONTRIBUTOR-DOCS/
├── 01_contributor-guides/13_focus-management.md           NEW
└── 02_style-guide/02_typescript/14_controller-composition.md  UPDATED

Motivation and Context

The 1st-gen focus architecture uses a deep inheritance chain (Focusable base class) that forces all-or-nothing inheritance, carries dead polyfill code, and uses a fragile flag system. The 2nd-gen strategy replaces this with composable, opt-in primitives: native delegatesFocus: true, FocusgroupNavigationController, and DisabledMixin.

Centralizing composite widget keyboard navigation on a single controller aligned with the focusgroup proposal reduces duplicated roving-tabindex logic across components, improves consistency, and shrinks maintenance surface while preserving WAI-ARIA APG accessibility expectations.

Related Issues

• fixes SWC-1676

Manual Testing

Run Storybook from 2nd-gen/packages/swc.

1. Horizontal Toolbar

• Open the "Focus group navigation controller / Horizontal Toolbar" story
• Tab into the toolbar — only one button receives focus (roving tabindex)
• ArrowRight / ArrowLeft move focus between Bold, Italic, Underline, Strikethrough
• Focus wraps from Strikethrough → Bold and vice versa
• Home jumps to Bold, End jumps to Strikethrough
• Tab away and back — the last-focused button is remembered

2. Both Axes Linear

• Open "Both Axes Linear" story
• ArrowRight and ArrowDown both advance forward through items
• ArrowLeft and ArrowUp both go backward
• Wrapping is enabled in both directions

3. Vertical Menu

• Open "Vertical Menu" story
• ArrowDown / ArrowUp move through Copy, Paste, Cut (unavailable), Select all
• "Cut (unavailable)" has aria-disabled="true" but is still focusable (skipDisabled: false)
• Clicking or pressing Enter/Space on "Cut (unavailable)" does nothing
• Page Down / Page Up skip 2 items at a time (pageStep: 2)

4. Skip Disabled Menu

• Open "Skip Disabled Menu" story
• ArrowDown skips "Save" (native disabled) and "Close" (aria-disabled="true")
• Only New, Open, Print, Help are reachable via arrow keys
• Wrap is enabled — Help → New and New → Help

5. Grid (3×3)

• Open "Grid" story
• ArrowRight / ArrowLeft move within a row
• ArrowDown / ArrowUp move between rows (same column)
• Home / End jump to first/last cell in row-major order
• Ctrl+Home / Ctrl+End jump to cell 1 / cell 9
• Page Down / Page Up move 2 rows at a time (pageStep: 2)
• No wrapping — arrows stop at edges

6. Programmatic Focus

• Open "Programmatic Focus" story
• Click "Focus item C programmatically" — focus moves to Item C in the toolbar
• Arrow keys work from the programmatically focused item

7. Text Prefix (Typeahead)

• Open "Text Prefix Focus" story
• Click 'Focus match for "Pas"' — focus jumps to Paste in the menu
• Click 'Focus match for "cu"' — focus jumps to Cut (case-insensitive)

8. General Checks

• :focus-visible outline appears on keyboard navigation (not on click)
• tabindex="0" is on exactly one item in each group, all others are tabindex="-1"
• Test in RTL (dir="rtl") — ArrowRight should go backward in horizontal mode

[changeset-bot]

⚠️ No Changeset found

Latest commit: e2f6a9f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview Links

• Documentation Site (first-gen)
• Storybook (first-gen)
• Storybook (second-gen)

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6129

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

[Rajdeepc]

I have two blocking concerns before technical review:

1. No consuming component validates composition. DisabledMixin, delegatesFocus, and FocusgroupNavigationController are designed to work together, but no 2nd-gen component uses them yet. Before merging infrastructure, I need to see at least one component (e.g., a simple toolbar or action-button) that exercises all three primitives together to prove they compose correctly.

2. DisabledMixin is not a replacement for Focusable. The 1st-gen Focusable class provides focus(), blur(), click() overrides, autofocus, focusElement delegation, selfManageFocusElement, and manipulating Tabindex. DisabledMixin only handles aria-disabled, tabindex save/restore, and blur-on-disable. The migration cost for components moving from Focusable is significant and the documentation does not surface this adequately.

Additional concerns for discussion:

FocusgroupNavigationController is missing APIs that 1st-gen composite widgets depend on: elementEnterAction (Tabs, Accordion), stopKeyEventPropagation (nested composites), manage/unmanage (Menu search mode), focusOnItem, reset. If these are intentionally deferred, please document what's deferred vs. what's deliberately dropped.

Holding off on line-by-line technical review until the above are addressed.

[nikkimk]

This is deliberately lightweight, as we can decide which features should be added to this controller, to a new controller, or to the component itself as components demonstrate need.

Note that many components that use focus group involve a11y changes and will be set to DelegatesFocus: true so that some of the old may not need what they used to from the old controller.

[nikkimk]

I have two blocking concerns before technical review:

1. No consuming component validates composition. DisabledMixin, delegatesFocus, and FocusgroupNavigationController are designed to work together, but no 2nd-gen component uses them yet. Before merging infrastructure, I need to see at least one component (e.g., a simple toolbar or action-button) that exercises all three primitives together to prove they compose correctly.
2. DisabledMixin is not a replacement for Focusable. The 1st-gen Focusable class provides focus(), blur(), click() overrides, autofocus, focusElement delegation, selfManageFocusElement, and manipulating Tabindex. DisabledMixin only handles aria-disabled, tabindex save/restore, and blur-on-disable. The migration cost for components moving from Focusable is significant and the documentation does not surface this adequately.

Additional concerns for discussion:

FocusgroupNavigationController is missing APIs that 1st-gen composite widgets depend on: elementEnterAction (Tabs, Accordion), stopKeyEventPropagation (nested composites), manage/unmanage (Menu search mode), focusOnItem, reset. If these are intentionally deferred, please document what's deferred vs. what's deliberately dropped.

Holding off on line-by-line technical review until the above are addressed.

@Rajdeepc see my comments FocusgroupNavigationController here: #6129 (comment)

[caseyisonit]

No consuming component validates composition. DisabledMixin, delegatesFocus, and FocusgroupNavigationController are designed to work together, but no 2nd-gen component uses them yet. Before merging infrastructure, I need to see at least one component (e.g., a simple toolbar or action-button) that exercises all three primitives together to prove they compose correctly.

DisabledMixin is not a replacement for Focusable. The 1st-gen Focusable class provides focus(), blur(), click() overrides, autofocus, focusElement delegation, selfManageFocusElement, and manipulating Tabindex. DisabledMixin only handles aria-disabled, tabindex save/restore, and blur-on-disable. The migration cost for components moving from Focusable is significant and the documentation does not surface this adequately.

• delegatesFocus is an implementation detail and strategy approach and not something to be validated until a component comes over that would follow that guidance.
• DisabledMixin is NOT a replacement of Focusable. it simply isolates an a11y property that should be opt in and not included in every instance of focus. Its removing the coupling and making it more flexible for usage.
• Please reference the Slack canvas as all the information about 1st-gen considerations are included and called out, this is a PR that supports the RFC proposal that has been documented and shared out. we cant't link internaly docs to PR.
• The documentation included is comprehensive of reasoning and refactor guidance, please review the whole PR (ive added even more details to be extra clear)

[caseyisonit]

@Rajdeepc I have migrated the updated RFC to the PR in project planning so the slack canvas is now out of date and i will clean that up in my tomorrow.

I’m still a bit curious about isn’t testing delegatesFocus in isolation, but how all three primitives behave together in a real component scenario. Right now, the Storybook demos are great for exercising the controller on its own, but we don’t yet have an example that combines DisabledMixin + delegatesFocus: true + FocusgroupNavigationController on the same element the way a migrated component would. Even a small proof-of-concept (like a simple action-group or toolbar prototype) will be helpful in validating that there aren’t any subtle interaction issues between tabindex management, roving tabindex, and browser focus delegation.

I think to honor the scope of this RFC proposal, this work would be a follow up in the next sprint, im thinking Tabs since it would need all three. To incorporate an entire component migration with this is out of scope and we should approach this agilely and iterate as we migrate more components. Accepting this with the agnostic component setups in the documentation covers the testing concern to be accepted in to main. This will also unblock several other components that didnt need all the complexity of 1st-gen now that we have separated the concerns.
TLDR We will migrate Tabs in the next round of components once this is merged in

I have addressed the three other concerns in the documentation and RFC so those should now be covered! Let me know if i missed anything else. :)

[caseyisonit]

All of the storybook docs changes were to allow the controller docs to work correctly. this will be re-evaluated in the docs IA epic for scalability but can be accepted with little to no risk.

[Rajdeepc]

I think to honor the scope of this RFC proposal, this work would be a follow up in the next sprint, im thinking Tabs since it would need all three. To incorporate an entire component migration with this is out of scope and we should approach this agilely and iterate as we migrate more components. Accepting this with the agnostic component setups in the documentation covers the testing concern to be accepted in to main. This will also unblock several other components that didnt need all the complexity of 1st-gen now that we have separated the concerns. TLDR We will migrate Tabs in the next round of components once this is merged in

I have addressed the three other concerns in the documentation and RFC so those should now be covered! Let me know if i missed anything else. :)

Fair point. I think you have addressed the documentation gaps and would really appreciate the Tabs follow-up being tracked as a ticket so it doesn't slip between sprints.

[Rajdeepc]

Nice effort. I have few suggestions in some areas where we can improve the cyclometric complexity as well as how we reduce DOM burnouts. I did an initial pass and please find my feedback. Open to discuss if you need any guidance or you feel it can be done in an alternate way.
Blocking for me would be

1. I see a conflict in DisabledMixin + FocusGroupNavigationController tabindex. Would love to see a new test and potentially a coordination mechanism.
2. Please add a test for memory behaviour and RTL behaviour, dynamic item addition/removal, onActiveItemChange callback, setOptions(), for inert attribute handling, disconnection/reconnection
3. Add a migration path for elementEnterAction. We are now using onActiveItemChange

[miwha-adobe]

Suggestion (non-blocking): This is a pretty large comment for the class. I wonder if it warrants a readme or some sort of supporting doc, instead of just JSDoc.

[caseyisonit]

ill be looking in to the docs pattern for controllers and other types of content in the docs IA epic and will note this concern, i am in agreement, its not great.

@rajdeep is contributing to this PR and addressing the blocking issues he had. We are dismissing this review status so that other team mates can review and approve now that he is a co-author!! Thanks for the support on this Rajdeep!!

[5t3ph]

In the Playground story, I would expect to be able to arrow through items linearly, regardless of disabled status. I'm not sure if it should still give focus to the disabled items, or just skip over them. But if you try arrow nav, you will currently get blocked due to the disabled "Underline". It looks like at some point tabindex="0" is trying to be set on the disabled button.

Edit: I now see the skipDisabled option, but maybe still worth some kind of change to the Playground, or maybe that should be default?

[5t3ph]

Suggestion: prevent tabindex="0" from being set on a disabled button and instead skip it since otherwise the other group items are modified to tabindex="-1" and the entire group becomes unnavigable via keyboard.

[miwha-adobe]

Question: When inspecting the dom, it shows me that strikethrough has aria-disabled, and disabled has the "disabled" attribute. I'm curious why strikethrough visually appears disabled when hovered over but only has the aria-attribute. Should it also have the disabled attribute, not just aria? It gets skipped when skipDisabled is true, but when set to false, only 'disabled' button is skipped.

[caseyisonit]

Question: When inspecting the dom, it shows me that strikethrough has aria-disabled, and disabled has the "disabled" attribute. I'm curious why strikethrough visually appears disabled when hovered over but only has the aria-attribute. Should it also have the disabled attribute, not just aria? It gets skipped when skipDisabled is true, but when set to false, only 'disabled' button is skipped.

@miwha-adobe great question, so theres some nuance around aria-disabled and disabled attritbutes. Based on this article @5t3ph shared about the accessibility implications and having the ability to opt in to certain disability states, this story should be exemplifying the difference between the two. Aria-disable allows for tabbing to exist and for screen readers to inform a user of an action that is avaialble but disabled for some reason i.e. form isn't filled out entirely so submit button is aria disabled, the user should still know the button exists but isnt active.

disabled attribute effectively makes it hidden and untabble/identifiable by screen readers and keyboard. I think Steph has highlighted an issue with the breaking of keyboard navigation and perhaps making skipDisabled the default so you can continue with keyboard and opt in to the block. e.g. walking a user through a stepper where steps need to be completed before you can reach the next step and dont want a user to skip it

Hope this helps, im still wrapping my brain around the nuance too but the article i think explains it much better than me! :D

https://kittygiraudel.com/2024/03/29/on-disabled-and-aria-disabled-attributes/

[nikkimk]

In the Playground story, I would expect to be able to arrow through items linearly, regardless of disabled status. I'm not sure if it should still give focus to the disabled items, or just skip over them. But if you try arrow nav, you will currently get blocked due to the disabled "Underline". It looks like at some point tabindex="0" is trying to be set on the disabled button.

Edit: I now see the skipDisabled option, but maybe still worth some kind of change to the Playground, or maybe that should be default?

From the APG

By default, disabled HTML input elements are removed from the tab sequence. In most contexts, the normal expectation is that disabled interactive elements are not focusable. However, there are some contexts where it is common for disabled elements to be focusable, especially inside of composite widgets. For example, as demonstrated in the menu and menubar pattern, disabled items are focusable when navigating through a menu with the arrow keys.

Since componenents using focus group / RTI nav are considered "composite widgets", I leaned toward making disabled items focusable as the default.

Or perhaps we should skip disabled but not skip aria-disabled and recommend that composite widgets use aria-disabled and the we wouldn't need the skipDisabled parameter?

[caseyisonit]

Or perhaps we should skip disabled but not skip aria-disabled and recommend that composite widgets use aria-disabled and the we wouldn't need the skipDisabled parameter?

I think this is the correct mental model we should adopt. disabled is always skipped and aria-disabled behaves the way its intended. does this have any effect on how we setup disabledMixin?

[Rajdeepc]

@5t3ph Great catch, Stephanie. This is a real accessibility issue — natively disabled elements can't receive focus regardless of their tabindex value, so if the controller assigns tabindex="0" to one and tabindex="-1" to everything else, the entire group becomes unreachable via the Tab key.

We should update applyRovingTabindex to detect natively disabled elements (via the disabled DOM property) and fall through to the next non-disabled eligible item for the roving tab stop. To be clear about the behavior:

• When skipDisabled: false (the default), disabled items remain in the arrow navigation order — this is intentional for aria-disabled patterns where the item should still be focusable and discoverable
• But only items that can actually receive browser focus are eligible to hold tabindex="0" (the tab entry point)

I have also added a dedicated test (DisabledButtonNeverTabStop) that natively disables the first button in a group and verifies the tabindex="0" tab stop moves to the next eligible item, preventing the keyboard trap.