docs(controllers): add FocusGroupController and RovingTabindexController to 2nd-gen

[Rajdeepc]

Description

• Adds standalone FocusGroupController and RovingTabindexController to @spectrum-web-components/core/controllers for 2nd-gen consumption
• Controllers are fully decoupled from 1st-gen — each generation owns its own independent copy (no cross-generation imports)
• Removes the hostDelegatesFocus config option from the 2nd-gen controllers since all 2nd-gen hosts use delegatesFocus: true; the delegation-aware behavior is now always applied
• Adds comprehensive JSDoc to every class, method, property, config option, and type — including APG pattern references, usage examples, and a mapping table to the proposed focusgroup HTML attribute
• Adds a new Controllers section in Storybook with documentation for both controllers (overview, configuration, public API, examples for toolbar/tablist/menu/grid/radio group patterns)
• Registers both controllers in the package exports (package.json exports + typesVersions) and barrel index

What changed

File	Change
controllers/FocusGroup.ts	New — standalone FocusGroupController with JSDoc, hostDelegatesFocus removed
controllers/RovingTabindex.ts	New — standalone RovingTabindexController with JSDoc, simplified manageTabindexes()
controllers/index.ts	Added barrel exports for both controllers and config types
package.json	Added exports and typesVersions entries for direct imports
.storybook/controllers/overview.mdx	New — controllers overview, installation, focusgroup attribute mapping
.storybook/controllers/focus-group-controller.mdx	New — full API docs, config options, grid mode, APG patterns
.storybook/controllers/roving-tabindex-controller.mdx	New — tabindex management, examples for tablist/menu/radio/nested groups
.storybook/main.ts	Added controllers directory as a Storybook story source
.storybook/preview.ts	Added Controllers to sidebar sort order

What did NOT change

• 1st-gen source is untouched — controllers in 1st-gen/tools/reactive-controllers retain their own standalone implementations
• Zero behavioral changes — all navigation logic is identical to the 1st-gen source (minus hostDelegatesFocus which is hardcoded as always-on)
• No components are migrated to use the new location in this PR (that's follow-up work)

Motivation and context

These controllers are the foundation for keyboard navigation in every composite widget (toolbar, tablist, menu, listbox, radio group, grid). Moving them to 2nd-gen with thorough documentation:

• Makes them available to 2nd-gen components without cross-generation imports
• Documents the API surface, behavioral semantics, and APG alignment in-code so future contributors don't have to reverse-engineer intent
• Provides Storybook documentation for both consumers and team members
• Establishes a clear mapping to the emerging focusgroup HTML attribute so migration is straightforward when native support stabilizes

Related issue(s)

• fixes SWC-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
  • Verify @spectrum-web-components/core/controllers exports resolve correctly after build
  • Verify no regressions in existing 1st-gen components (1st-gen source is untouched)
  • IDE: confirm JSDoc renders in autocomplete/hover for all public APIs

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0cbad1a

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-6118

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.

[nikkimk]

Can we do this with our copy/strategy so that 1st-gen and 2nd-gen are decoupled. Also can we remove hostDelegatesFocus and assume that every 2nd-gen hosts that use this will delegate focus?

[nikkimk]

Meant to hit request changes

Can we do this with our copy/strategy so that 1st-gen and 2nd-gen are decoupled. Also can we remove hostDelegatesFocus and assume that every 2nd-gen hosts that use this will delegate focus?

Also can we create some next gen docs on how to implement this? We need this not just for consumers but for our own team members as well. Perhaps a controllers section in the storybook?

[caseyisonit]

@Rajdeepc can we consider closing/pausing on this PR in favor of the team focus management RFC?

[caseyisonit]

Closing in favor of the focus management RFC PR #6129