feat(react-headless-components-preview): add Nav component and stories by dmytrokirpa · Pull Request #36213 · microsoft/fluentui

dmytrokirpa · 2026-05-16T14:23:35Z

Stack

This PR is part of a 3-PR stack. Review and merge bottom-up:

test(react-nav): add hook-level regression tests for react-nav components #36212 — test(react-nav): hook-level regression tests (base: master) — merge first
feat(react-nav): add useNavBase_unstable hook #35812 — feat(react-nav): expose base hooks (base: test(react-nav): add hook-level regression tests for react-nav components #36212) — depends on test(react-nav): add hook-level regression tests for react-nav components #36212
👉 feat(react-headless-components-preview): add Nav component and stories #36213 — feat(react-headless-components-preview): add Nav component (base: feat(react-nav): add useNavBase_unstable hook #35812) — merge last; depends on feat(react-nav): add useNavBase_unstable hook #35812

Summary

Add a headless Nav component to react-headless-components-preview built on top of the newly exposed useNavBase_unstable hooks from @fluentui/react-nav. Includes API report and Storybook stories.

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

github-actions · 2026-05-16T14:31:20Z

Pull request demo site: URL

…ents Add hook-level tests covering useNavBase_unstable, useAppItemBase_unstable, useAppItemStaticBase_unstable, useNavCategoryItemBase_unstable, useNavItemBase_unstable, useNavSubItemBase_unstable, and useNavSubItemGroupBase_unstable to lock in current behavior before refactor. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Add useNavBase_unstable, useAppItemBase_unstable, useAppItemStaticBase_unstable, useNavCategoryItemBase_unstable, useNavItemBase_unstable, useNavSubItemBase_unstable, and useNavSubItemGroupBase_unstable, exposing the behavior layer of react-nav without styling. Also exports the related Base prop, slot, and state types. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

…emBase_unstable Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Add a headless Nav component to react-headless-components-preview built on top of the newly exposed useNavBase_unstable hooks from @fluentui/react-nav. Includes API report and Storybook stories. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

…tions and slot usage Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

…Nav stories Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

github-actions · 2026-05-19T18:42:50Z

📊 Bundle size report

Package & Exports	Baseline (minified/GZIP)	PR	Change
`react-headless-components-preview` react-headless-components-preview: entire library	`150.303 kB` `43.181 kB`	`158.206 kB` `45.02 kB`	`7.903 kB` `1.839 kB`

_{🤖 This report was generated against 82fb42454f40721a0923ed12604ed4f6120ff28f}

Hotell

left some comments
tried to run copilot for additional review check - doesn't do anything 🥹
this PR is huge. it would be great to provide some additional context on which parts are copy paste and which are not and why are they necessary

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR introduces a new headless Nav component (and related subcomponents) in @fluentui/react-headless-components-preview, built on top of @fluentui/react-nav base hooks, along with Storybook examples, API report updates, and packaging/export wiring.

Changes:

Added Nav, NavDrawer, and supporting subcomponents (items, categories, sub-item groups, divider, section header) to the headless preview library.
Added Storybook stories and styling to demonstrate default, controlled, categorized, and drawer-based navigation.
Updated package exports, API report, bundle-size fixture, and change file to publish the new entrypoint.

Reviewed changes

Copilot reviewed 80 out of 80 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/react-components/react-headless-components-preview/stories/src/Nav/nav.module.css	Adds styles used by Nav-related Storybook examples
packages/react-components/react-headless-components-preview/stories/src/Nav/index.stories.tsx	Registers Nav stories and docs description for Storybook
packages/react-components/react-headless-components-preview/stories/src/Nav/NavWithCategories.stories.tsx	Adds a hierarchical Nav example with categories/sub-items
packages/react-components/react-headless-components-preview/stories/src/Nav/NavDrawerControlled.stories.tsx	Adds a fully controlled NavDrawer example (selection + open categories)
packages/react-components/react-headless-components-preview/stories/src/Nav/NavDrawerBasic.stories.tsx	Adds a basic NavDrawer example with inline/overlay toggle
packages/react-components/react-headless-components-preview/stories/src/Nav/NavDescription.md	Adds component docs blurb for Nav story
packages/react-components/react-headless-components-preview/stories/src/Nav/NavDefault.stories.tsx	Adds a simple flat Nav example
packages/react-components/react-headless-components-preview/stories/src/Nav/NavControlled.stories.tsx	Adds a controlled selection example for Nav
packages/react-components/react-headless-components-preview/library/src/nav.ts	Adds public exports/types for the new `./nav` entrypoint
packages/react-components/react-headless-components-preview/library/src/components/Nav/useNavContextValues.ts	Builds Nav context values for providers/consumers
packages/react-components/react-headless-components-preview/library/src/components/Nav/useNav.ts	Adds headless Nav hook built on `useNavBase_unstable`
packages/react-components/react-headless-components-preview/library/src/components/Nav/renderNav.tsx	Re-exports react-nav renderer with local typing
packages/react-components/react-headless-components-preview/library/src/components/Nav/navContext.ts	Re-exports Nav context/provider from `@fluentui/react-nav`
packages/react-components/react-headless-components-preview/library/src/components/Nav/navCategoryItemContext.ts	Re-exports NavCategoryItem context/provider wiring
packages/react-components/react-headless-components-preview/library/src/components/Nav/navCategoryContext.ts	Re-exports NavCategory context and defines value type
packages/react-components/react-headless-components-preview/library/src/components/Nav/index.ts	Barrels all Nav subcomponent exports under components/Nav
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSubItemGroup/useNavSubItemGroup.ts	Adds headless conditional sub-item group state based on open category
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSubItemGroup/renderNavSubItemGroup.tsx	Renders sub-item group only when the category is open
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSubItemGroup/index.ts	Barrels NavSubItemGroup exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSubItemGroup/NavSubItemGroup.types.ts	Defines NavSubItemGroup slots/props/state
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSubItemGroup/NavSubItemGroup.tsx	Implements NavSubItemGroup component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSubItem/useNavSubItem.ts	Re-exports base sub-item hook
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSubItem/renderNavSubItem.tsx	Re-exports base sub-item renderer with local typing
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSubItem/index.ts	Barrels NavSubItem exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSubItem/NavSubItem.types.ts	Defines NavSubItem types via `@fluentui/react-nav`
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSubItem/NavSubItem.tsx	Implements NavSubItem component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSectionHeader/useNavSectionHeader.ts	Adds headless section header state hook
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSectionHeader/renderNavSectionHeader.tsx	Renders section header slot
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSectionHeader/index.ts	Barrels NavSectionHeader exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSectionHeader/NavSectionHeader.types.ts	Defines NavSectionHeader slots/props/state
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSectionHeader/NavSectionHeader.tsx	Implements NavSectionHeader component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavItem/useNavItem.ts	Re-exports base item hook
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavItem/renderNavItem.tsx	Re-exports base item renderer with local typing
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavItem/index.ts	Barrels NavItem exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavItem/NavItem.types.ts	Defines NavItem types via `@fluentui/react-nav`
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavItem/NavItem.tsx	Implements NavItem component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerHeader/useNavDrawerHeader.ts	Adapts DrawerHeader hook for NavDrawerHeader
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerHeader/renderNavDrawerHeader.ts	Re-exports DrawerHeader renderer
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerHeader/index.ts	Barrels NavDrawerHeader exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerHeader/NavDrawerHeader.types.ts	Re-exports DrawerHeader types as NavDrawerHeader types
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerHeader/NavDrawerHeader.tsx	Implements NavDrawerHeader component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerFooter/useNavDrawerFooter.ts	Adapts DrawerFooter hook for NavDrawerFooter
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerFooter/renderNavDrawerFooter.ts	Re-exports DrawerFooter renderer
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerFooter/index.ts	Barrels NavDrawerFooter exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerFooter/NavDrawerFooter.types.ts	Re-exports DrawerFooter types as NavDrawerFooter types
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerFooter/NavDrawerFooter.tsx	Implements NavDrawerFooter component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerBody/useNavDrawerBody.ts	Adapts DrawerBody hook and adds navigation focus props
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerBody/renderNavDrawerBody.ts	Re-exports DrawerBody renderer
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerBody/index.ts	Barrels NavDrawerBody exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerBody/NavDrawerBody.types.ts	Defines NavDrawerBody state extension for focusgroup
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawerBody/NavDrawerBody.tsx	Implements NavDrawerBody component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawer/useNavDrawer.ts	Combines Nav state with Drawer as the root slot
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawer/renderNavDrawer.tsx	Wraps Drawer rendering inside a NavProvider
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawer/index.ts	Barrels NavDrawer exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawer/NavDrawer.types.ts	Defines NavDrawer slots/props/state
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDrawer/NavDrawer.tsx	Implements NavDrawer component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDivider/useNavDivider.ts	Adapts Divider hook for NavDivider
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDivider/renderNavDivider.tsx	Re-exports Divider renderer
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDivider/index.ts	Barrels NavDivider exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDivider/NavDivider.types.ts	Defines NavDivider props/state based on Divider
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavDivider/NavDivider.tsx	Implements NavDivider component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategoryItem/useNavCategoryItemContextValues.ts	Adds context-values hook for NavCategoryItem
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategoryItem/useNavCategoryItem.ts	Implements headless NavCategoryItem behavior and aria
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategoryItem/renderNavCategoryItem.tsx	Renders NavCategoryItem with provider and icon slots
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategoryItem/index.ts	Barrels NavCategoryItem exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategoryItem/NavCategoryItem.types.ts	Defines NavCategoryItem slots/props/state/context types
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategoryItem/NavCategoryItem.tsx	Implements NavCategoryItem component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategory/useNavCategoryContextValues.ts	Re-exports category context values hook
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategory/useNavCategory.ts	Re-exports category hook
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategory/renderNavCategory.tsx	Re-exports category renderer
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategory/index.ts	Barrels NavCategory exports
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategory/NavCategory.types.ts	Re-exports category types
packages/react-components/react-headless-components-preview/library/src/components/Nav/NavCategory/NavCategory.tsx	Implements NavCategory component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/Nav.types.ts	Defines Nav state type extension (focusgroup) and re-exports props
packages/react-components/react-headless-components-preview/library/src/components/Nav/Nav.tsx	Implements Nav component wrapper
packages/react-components/react-headless-components-preview/library/src/components/Nav/Nav.test.tsx	Adds component conformance + behavior tests for Nav
packages/react-components/react-headless-components-preview/library/package.json	Adds dependency and exports map for `./nav` entrypoint
packages/react-components/react-headless-components-preview/library/etc/nav.api.md	Adds API Extractor report for new nav entrypoint
packages/react-components/react-headless-components-preview/library/bundle-size/AllComponents.fixture.js	Includes `nav` entrypoint in bundle-size fixture
change/@fluentui-react-headless-components-preview-00b1aba3-b65a-45fc-b760-cb450c3901da.json	Adds change file for release notes/version bump

Comments suppressed due to low confidence (4)

packages/react-components/react-headless-components-preview/library/src/components/Nav/NavSectionHeader/useNavSectionHeader.ts:1

The ref and JSDoc specify HTMLDivElement, but the slot renders an h3. This is a type mismatch that can lead to incorrect ref typing for consumers. Update the ref type (and the doc) to a heading-compatible type (e.g., React.Ref<HTMLHeadingElement>/HTMLElement) and consider aligning the default slot type in NavSectionHeaderSlots (currently defaulting to h2) with the actual rendered default element.
packages/react-components/react-headless-components-preview/stories/src/Nav/NavDrawerControlled.stories.tsx:1
This controlled-story toggle handler sets openCategories multiple times per event (line 57-59 and again in the branches) and uses openCategories from the render closure, which can lead to stale updates and inconsistent open state. Use a single setOpenCategories(prev => ...) functional update and remove the extra initial setOpenCategories(...) to ensure deterministic behavior.
packages/react-components/react-headless-components-preview/stories/src/Nav/NavDrawerBasic.stories.tsx:1
These icon-only buttons rely on title for labeling. For accessibility, provide an explicit accessible name (e.g., aria-label) and set type=\"button\" to avoid unintended form submission behavior if used inside a <form> in the docs environment.
packages/react-components/react-headless-components-preview/stories/src/Nav/NavDrawerBasic.stories.tsx:1
These icon-only buttons rely on title for labeling. For accessibility, provide an explicit accessible name (e.g., aria-label) and set type=\"button\" to avoid unintended form submission behavior if used inside a <form> in the docs environment.

microsoft-github-policy-service Bot added the PR: API Modified label May 16, 2026

dmytrokirpa self-assigned this May 16, 2026

dmytrokirpa force-pushed the feat/react-nav-base-hooks branch from 3ff4cfc to f2ca767 Compare May 16, 2026 19:23

dmytrokirpa force-pushed the feat/react-headless-components-preview-nav branch from d6c1b76 to 7b28100 Compare May 16, 2026 19:23

dmytrokirpa and others added 2 commits May 16, 2026 21:55

dmytrokirpa force-pushed the feat/react-nav-base-hooks branch from f2ca767 to 00ced3c Compare May 16, 2026 19:56

dmytrokirpa force-pushed the feat/react-headless-components-preview-nav branch from 7b28100 to 71f5b4b Compare May 16, 2026 19:56

This was referenced May 17, 2026

test(react-nav): add hook-level regression tests for react-nav components #36212

Merged

feat(react-nav): add useNavBase_unstable hook #35812

Merged

dmytrokirpa and others added 3 commits May 17, 2026 11:26

fix(react-nav): add hyphen and description to @param tags on useNavIt…

fece79a

…emBase_unstable Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

refactor(react-headless-components-preview): clean up Nav render func…

1aad245

…tions and slot usage Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

dmytrokirpa force-pushed the feat/react-headless-components-preview-nav branch from ad26d12 to 1aad245 Compare May 17, 2026 09:26

fix(react-headless-components-preview): add explicit return types on …

ad07501

…Nav stories Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

dmytrokirpa marked this pull request as ready for review May 18, 2026 09:28

dmytrokirpa requested a review from a team as a code owner May 18, 2026 09:28

dmytrokirpa added Component: Nav Headless labels May 18, 2026

dmytrokirpa requested review from Hotell and mainframev May 18, 2026 09:30

mainframev reviewed May 19, 2026

View reviewed changes

Comment thread ...headless-components-preview/library/src/components/Nav/NavCategoryItem/useNavCategoryItem.ts Outdated

Comment thread ...act-headless-components-preview/library/src/components/Nav/NavDrawerBody/useNavDrawerBody.ts Outdated

Base automatically changed from feat/react-nav-base-hooks to master May 19, 2026 18:29

Merge branch 'master' into feat/react-headless-components-preview-nav

18cfccb

dmytrokirpa added 3 commits May 20, 2026 10:44

Merge branch 'master' into feat/react-headless-components-preview-nav

c0154fc

add focusgroup for arrow navigation

030ca5d

review comment

3b76627

dmytrokirpa requested a review from mainframev May 20, 2026 10:26

Hotell requested a review from Copilot May 20, 2026 13:20

Hotell approved these changes May 20, 2026

View reviewed changes

Copilot AI reviewed May 20, 2026

View reviewed changes

Copilot started reviewing on behalf of Hotell May 20, 2026 13:38 View session

dmytrokirpa added 4 commits May 20, 2026 18:55

Merge branch 'master' into feat/react-headless-components-preview-nav

d152272

address review comments

7bad28b

cleanup comment

843a1f7

Merge branch 'master' into feat/react-headless-components-preview-nav

f773498

dmytrokirpa enabled auto-merge (squash) May 21, 2026 10:05

dmytrokirpa merged commit b7214c3 into master May 21, 2026
14 checks passed

dmytrokirpa deleted the feat/react-headless-components-preview-nav branch May 23, 2026 10:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(react-headless-components-preview): add Nav component and stories#36213

feat(react-headless-components-preview): add Nav component and stories#36213
dmytrokirpa merged 14 commits into
masterfrom
feat/react-headless-components-preview-nav

dmytrokirpa commented May 16, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 16, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026 •

edited

Loading

Uh oh!

Hotell left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

dmytrokirpa commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Stack

Summary

Uh oh!

github-actions Bot commented May 16, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Bundle size report

Uh oh!

Hotell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dmytrokirpa commented May 16, 2026 •

edited

Loading

github-actions Bot commented May 19, 2026 •

edited

Loading