Skip to content

RFC: focusgroup navigation#6144

Draft
nikkimk wants to merge 30 commits intomainfrom
nikkimk/rti-demo
Draft

RFC: focusgroup navigation#6144
nikkimk wants to merge 30 commits intomainfrom
nikkimk/rti-demo

Conversation

@nikkimk
Copy link
Copy Markdown
Contributor

@nikkimk nikkimk commented Apr 6, 2026

Description

  • Prefer native focusgroup when 'focusgroup' in HTMLElement.prototype (or agreed feature-detection) is true
  • Provide a polyfill that mirrors the proposed semantics closely enough for SWC components to use one API
  • Added doc block comments analyzing which part of the controller may become deprecated with focusgroup
  • Support horizontal (inline-axis) and vertical (block-axis) linear composites
  • Support grid navigation via polyfill (and document how it composes with native focusgroup when both exist)
  • Integrate with Shadow DOM (focusgroup applies across shadow boundaries per explainer; polyfill must define behavior for shadow trees and slotted content)
  • Preserve accessibility: correct roles/names/states remain author responsibility; polyfill must not fight inferred or explicit ARIA
  • Added Page Up/Down and Home End navigation
  • Added printable character navigation

Motivation and context

Propose a next-generation approach for composite widget keyboard navigation (roving tabindex and related focus management) across Spectrum Web Components. The goal is to align with the emerging focusgroup HTML attribute as a declarative, platform-native solution where possible, and to ship a small, well-tested polyfill where browsers do not yet implement it.

Primary reference: Request for developer feedback: focusgroup (Chromium / Open UI; behavior tokens, inline / block / wrap / nomemory, focusgroupstart, role inference, shadow DOM behavior, feature detection).

Today, many components duplicate roving-tabindex logic (accordion, toolbar, tabs, menus, listbox-like lists, segmented controls, etc.). Centralizing on focusgroup plus a polyfill should reduce bugs, improve consistency, and shrink maintenance surface—while preserving accessibility expectations from the WAI-ARIA APG.

Grid-oriented navigation (two-dimensional roving across rows and columns, home/end, page up/down where applicable) is not fully specified as a single focusgroup behavior token in the current public proposal. This ticket should therefore treat grid as an explicit extension in the polyfill (and/or layered pattern using nested focusgroups + documented rules), mapped to the APG grid pattern—not assumed to be “free” from the native attribute alone until the standard catches up.

Related issue(s)

  • fixes 1676

Screenshots (if appropriate)


Author's checklist

  • I have read the CONTRIBUTING and PULL_REQUESTS documents.
  • I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
  • I have added automated tests to cover my changes.
  • I have included a well-written changeset if my change needs to be published.
  • I have included updated documentation if my change required it.

Reviewer's checklist

  • Includes a Github Issue with appropriate flag or Jira ticket number without a link
  • Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
  • Automated tests cover all use cases and follow best practices for writing
  • Validated on all supported browsers
  • All VRTs are approved before the author can update Golden Hash

Manual review test cases

  • Descriptive Test Statement
    1. Go here
    2. Use a keyboard to navigate the examples
    3. Make sure keyboard navigation works as described
    4. Review the documentation. Is the controller easy to understand? Do you think you'd be able to implement this easily in a component?

Device review

  • Did it pass in Desktop?
  • Did it pass in (emulated) Mobile?
  • Did it pass in (emulated) iPad?

caseyisonit and others added 29 commits April 1, 2026 15:42
Phase 1 of focus management migration (FOCUS-MANAGEMENT-PROPOSAL.md §5).

- Add get-active-element.ts: shadow DOM-aware activeElement traversal
- Add focusable-selectors.ts: standard HTML focusable/tabbable selectors
  (removes 1st-gen [focusable] attribute workaround)
- Refactor hasVisibleFocusInTree() to use getActiveElement(), removing
  dead ancestor-chain code and legacy .focus-visible polyfill fallback
- Export new utilities from utils/index.ts
Phase 2 of focus management migration (FOCUS-MANAGEMENT-PROPOSAL.md §5).

Consolidates 1st-gen FocusGroupController + RovingTabindexController into
a single, self-contained reactive controller. Key changes from 1st-gen:

- Flat single-file architecture (no base class inheritance)
- MutationObserver uses attributeFilter for disabled/aria-disabled only
- Listener scope defaults to host.renderRoot for shadow DOM encapsulation
- Removes redundant click handler (focusin covers click-to-focus)
- Removes virtualization offset (deferred until needed)
- Simplified tabindex management (direct tabIndex set, no requestUpdate)
Phase 3 of focus management migration (FOCUS-MANAGEMENT-PROPOSAL.md §5).

Extracts disabled state handling from 1st-gen Focusable base class into
a standalone, composable mixin. Uses aria-disabled on the host for screen
reader discoverability rather than the native disabled attribute. Manages
tabindex removal/restoration and blurs active element on disable.
@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Apr 6, 2026

⚠️ No Changeset found

Latest commit: 8c7c97b

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

@nikkimk nikkimk changed the title Nikkimk/rti demo RFC: focusgroup navigation Apr 6, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 6, 2026

📚 Branch Preview Links

🔍 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:

Deployed to Azure Blob Storage: pr-6144

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants