NavList: Support linked sub-nav parents

[mattobee]

Closes github/primer#6408

This lets a NavList parent navigate somewhere while a separate chevron expands its nested links. Existing sub-nav parents stay as toggle buttons unless subNavToggleLabel is set.

We could arguably construct the label instead of relying on the consumer to pass a sensible value, but I'm not sure if that's too restrictive.

I also think we should reconsider the styling of this and other trailing actions. Current hover effect highlights the entire row, including the trailing action, which wrongly implies that a click on the label will also activate the trailing action.

Changelog

New

• Add subNavToggleLabel to opt into a linked parent with an independent sub-nav toggle.

Changed

• N/A

Removed

• N/A

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Open the With Linked Sub Nav Parent story. The Overview link and chevron should work independently, and the expanded links should appear below them at the full width of the list.

• npx vitest run packages/react/src/NavList/NavList.test.tsx
• npm run type-check

[changeset-bot]

🦋 Changeset detected

Latest commit: 2945d6d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Minor

Not sure what this means? Click here to learn what changesets are.

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

[github-actions]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

[Copilot]

Copilot review overview

🟡 Changes recommended

There are two confirmed interaction/behavior bugs in the new linked-parent path (toggle click propagation and false-positive dev warnings with tooltips) that should be fixed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review tier: Lite
Findings: 1

New issues introduced by this change (1)

Severity	Finding
	packages/​react/​src/​NavList/​NavList.tsx — The dev-only warning for subNavToggleLabel can false-positive when tooltipText is set, because…

What changed in this PR

Adds an opt-in API for NavList.Item with a SubNav to behave as a navigational link while providing a separate, accessible toggle control to expand/collapse the nested list.

Changes:

• Introduces subNavToggleLabel to render sub-nav parents as links with an independent chevron toggle.
• Updates internal ItemWithSubNav rendering to support the split link/toggle interaction, including updated styling and visibility behavior.
• Adds Storybook coverage, docs metadata, unit tests, and a changeset for the new minor feature.

File	Description
packages/​react/​src/​NavList/​NavList.tsx	Implements linked sub-nav parents via subNavToggleLabel, adds toggle control and context updates.
packages/​react/​src/​NavList/​NavList.test.tsx	Adds tests for the linked-parent behavior and warning cases.
packages/​react/​src/​NavList/​NavList.module.css	Adds grid-based layout rules for link + separate toggle and full-width sub-nav positioning.
packages/​react/​src/​NavList/​NavList.features.stories.tsx	Adds “With Linked Sub Nav Parent” story for manual verification.
packages/​react/​src/​NavList/​NavList.docs.json	Documents the new prop and references the new story.
.changeset/​lazy-linked-subnav.md	Declares a minor release for the new NavList capability.

Suppressed comments (1)

packages/react/src/NavList/NavList.tsx:358

• In the linked-parent variant, NavList.Item props (including onClick) are spread onto the underlying ActionList.Item
• via ActionList.LinkItem. Clicking the trailing toggle button will bubble to that
• and can inadvertently trigger the link's onClick/navigation logic. Stop propagation (and prevent default) in the toggle handler so the chevron click is isolated to expanding/collapsing.

            onClick={toggleSubNav}

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[llastflowers]

Should a linked sub-nav parent with aria-current="page" have the normal active NavList styling? The code sets it as active, but it doesn’t appear selected when I test it in Storybook.

For example, in the Default NavList story, Item 1 has aria-current="page":

If I apply that to the new With Linked Sub Nav Parent story, the styling is not applied.

[llastflowers]

Since subNavToggleLabel changes a sub-nav parent into a link, should we make it a requirement to add a navigation destination (href) when this prop is set? Currently it's optional here, so it can be omitted, which would result in the parent label rendering as a non-focusable anchor while only the chevron remains interactive.

[llastflowers]

Also, please run integration tests when ready! 🙏