diff --git a/packages/react/src/ActionBar/ActionBar.test.tsx b/packages/react/src/ActionBar/ActionBar.test.tsx
index 98fd2d4b777..f5537efde2e 100644
--- a/packages/react/src/ActionBar/ActionBar.test.tsx
+++ b/packages/react/src/ActionBar/ActionBar.test.tsx
@@ -82,6 +82,72 @@ describe('ActionBar', () => {
})
})
+describe('ActionBar.Button', () => {
+ afterEach(() => {
+ vi.clearAllMocks()
+ })
+
+ it('renders a text button with its children as the accessible name', () => {
+ render(
+
+ Save
+ ,
+ )
+
+ expect(screen.getByRole('button', {name: 'Save'})).toBeInTheDocument()
+ })
+
+ it('should trigger non-disabled button', () => {
+ const onClick = vi.fn()
+ render(
+
+ Save
+ ,
+ )
+
+ screen.getByRole('button', {name: 'Save'}).click()
+
+ expect(onClick).toHaveBeenCalled()
+ })
+
+ it('should not trigger disabled button', () => {
+ const onClick = vi.fn()
+ render(
+
+
+ Save
+
+ ,
+ )
+
+ screen.getByRole('button', {name: 'Save'}).click()
+
+ expect(onClick).not.toHaveBeenCalled()
+ })
+
+ it('should not trigger disabled button with spacebar or enter', async () => {
+ const user = userEvent.setup()
+ const onClick = vi.fn()
+ render(
+
+
+ Save
+
+ ,
+ )
+
+ const button = screen.getByRole('button', {name: 'Save'})
+
+ act(() => {
+ button.focus()
+ })
+
+ await user.keyboard('{Enter}')
+
+ expect(onClick).not.toHaveBeenCalled()
+ })
+})
+
describe('ActionBar Registry System', () => {
it('should preserve order with deep nesting', () => {
render(
@@ -442,6 +508,17 @@ describe('ActionBar data-component attributes', () => {
expect(iconButton).toBeInTheDocument()
})
+ it('renders ActionBar.Button with a text label', () => {
+ render(
+
+ Save
+ ,
+ )
+
+ const button = screen.getByRole('button', {name: 'Save'})
+ expect(button).toBeInTheDocument()
+ })
+
it('renders ActionBar.VerticalDivider with data-component attribute', () => {
const {container} = render(
diff --git a/packages/react/src/ActionBar/ActionBar.tsx b/packages/react/src/ActionBar/ActionBar.tsx
index 8fd85484606..037922e3aed 100644
--- a/packages/react/src/ActionBar/ActionBar.tsx
+++ b/packages/react/src/ActionBar/ActionBar.tsx
@@ -1,23 +1,25 @@
import {type RefObject, type MouseEventHandler, useContext} from 'react'
-import React, {useState, useCallback, useRef, forwardRef, useMemo, useSyncExternalStore} from 'react'
+import React, {useState, useCallback, useRef, forwardRef, useMemo} from 'react'
import {KebabHorizontalIcon} from '@primer/octicons-react'
import {ActionList, type ActionListItemProps} from '../ActionList'
-import type {IconButtonProps} from '../Button'
-import {IconButton} from '../Button'
+import type {ButtonProps, IconButtonProps} from '../Button'
+import {Button, IconButton} from '../Button'
import {ActionMenu} from '../ActionMenu'
import {useFocusZone, FocusKeys} from '../hooks/useFocusZone'
import styles from './ActionBar.module.css'
import {clsx} from 'clsx'
import {useMergedRefs} from '../hooks'
import {createDescendantRegistry} from '../utils/descendant-registry'
+import {OverflowObserverProvider} from '../internal/components/OverflowObserverProvider'
+import {useIsClipped} from '../internal/hooks/useOverflowObserver'
type ChildProps =
| {
type: 'action'
- label: string
+ label: React.ReactNode
disabled: boolean
- icon: ActionBarIconButtonProps['icon']
+ icon?: ActionBarIconButtonProps['icon']
onClick: MouseEventHandler
}
| {type: 'divider' | 'group'}
@@ -84,6 +86,8 @@ export type ActionBarProps = {
export type ActionBarIconButtonProps = {disabled?: boolean} & IconButtonProps
+export type ActionBarButtonProps = {disabled?: boolean} & ButtonProps
+
export type ActionBarMenuItemProps =
| ({
/**
@@ -236,7 +240,11 @@ export const ActionBar: React.FC> = ({
{/* An empty first element allows the real first item to wrap to the next line and get clipped. */}
- {children}
+
+
+ {children}
+
+
@@ -260,15 +268,17 @@ export const ActionBar: React.FC> = ({
const {onClick, icon: Icon, label, disabled} = menuItem
return (
{
typeof onClick === 'function' && onClick(event as React.MouseEvent)
}}
disabled={disabled}
>
-
-
-
+ {Icon ? (
+
+
+
+ ) : null}
{label}
)
@@ -310,33 +320,9 @@ function useActionBarItem(ref: React.RefObject, registryProp
const isGroupOverflowing = useContext(ActionBarGroupContext)?.isOverflowing
const isInGroup = isGroupOverflowing !== undefined
- const subscribeIntersectionObserver = useCallback(
- (onChange: () => void) => {
- // There's no need to register observers on items inside of a group
- // since the entire group overflows at once
- if (isInGroup) return () => {}
-
- // Technically 1 should work as the threshold, but in some scenarios that
- // doesn't seem to trigger correctly - probably because the browser still
- // thinks a tiny bit of the button is not visible, since the container
- // height is exactly the button height. So 75% should be more reliable.
- const observer = new IntersectionObserver(() => onChange(), {threshold: 0.75})
-
- if (ref.current) observer.observe(ref.current)
- return () => observer.disconnect()
- },
- [ref, isInGroup],
- )
-
- const isItemOverflowing = useSyncExternalStore(
- subscribeIntersectionObserver,
- // Note: the IntersectionObserver is just being used as a trigger to re-check
- // `offsetTop > 0`; this is fast and simpler than checking visibility from
- // the observed entry. When an item wraps, it will move to the next row which
- // increases its `offsetTop`
- () => (ref.current ? ref.current.offsetTop > 0 : false),
- () => false,
- )
+ // There's no need to observe items inside of a group since the entire group overflows at once, so `disabled` skips
+ // subscription for grouped items and always reports `false` for the child item itself.
+ const isItemOverflowing = useIsClipped(ref, {disabled: isInGroup})
const isOverflowing = isGroupOverflowing || isItemOverflowing
@@ -390,6 +376,51 @@ export const ActionBarIconButton = forwardRef(
},
)
+export const ActionBarButton = forwardRef(({disabled, onClick, ...props}: ActionBarButtonProps, forwardedRef) => {
+ const ref = useRef(null)
+ const mergedRef = useMergedRefs(forwardedRef, ref)
+
+ const {size} = React.useContext(ActionBarContext)
+
+ const {children, leadingVisual} = props
+
+ const {dataOverflowingAttr} = useActionBarItem(
+ ref,
+ useMemo(
+ (): ChildProps => ({
+ type: 'action',
+ label: children,
+ // Only forward the leading visual to the overflow menu when it is a component
+ // that can be rendered as an icon (e.g. an octicon), matching ActionBar.IconButton.
+ icon: typeof leadingVisual === 'function' ? (leadingVisual as ActionBarIconButtonProps['icon']) : undefined,
+ disabled: !!disabled,
+ onClick: onClick as MouseEventHandler,
+ }),
+ [children, leadingVisual, disabled, onClick],
+ ),
+ )
+
+ const clickHandler = useCallback(
+ (event: React.MouseEvent) => {
+ if (disabled) return
+ onClick?.(event)
+ },
+ [disabled, onClick],
+ )
+
+ return (
+
+ )
+})
+
const ActionBarGroupContext = React.createContext<{
isOverflowing: boolean
} | null>(null)
diff --git a/packages/react/src/ActionBar/index.ts b/packages/react/src/ActionBar/index.ts
index 9a7e78b503b..ef72a7a1e1d 100644
--- a/packages/react/src/ActionBar/index.ts
+++ b/packages/react/src/ActionBar/index.ts
@@ -1,8 +1,16 @@
-import {ActionBar as Bar, ActionBarIconButton, VerticalDivider, ActionBarGroup, ActionBarMenu} from './ActionBar'
-export type {ActionBarProps, ActionBarMenuProps, ActionBarMenuItemProps} from './ActionBar'
+import {
+ ActionBar as Bar,
+ ActionBarIconButton,
+ ActionBarButton,
+ VerticalDivider,
+ ActionBarGroup,
+ ActionBarMenu,
+} from './ActionBar'
+export type {ActionBarProps, ActionBarButtonProps, ActionBarMenuProps, ActionBarMenuItemProps} from './ActionBar'
const ActionBar = Object.assign(Bar, {
IconButton: ActionBarIconButton,
+ Button: ActionBarButton,
Divider: VerticalDivider,
Group: ActionBarGroup,
Menu: ActionBarMenu,
diff --git a/packages/react/src/ActionList/ActionList.module.css b/packages/react/src/ActionList/ActionList.module.css
index 6195a4a1bb8..aa7d807f673 100644
--- a/packages/react/src/ActionList/ActionList.module.css
+++ b/packages/react/src/ActionList/ActionList.module.css
@@ -557,9 +557,17 @@
display: none;
}
- /* show active indicator on parent collapse if child is active */
- /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
- &:has(~ .SubGroup [data-active='true']) {
+ /*
+ * Show the active indicator on a collapsed parent when one of its subnav
+ * items is active. NavList sets `active` (→ the parent
's `data-active`)
+ * to exactly `!isOpen && containsCurrentItem`, which is the same condition as
+ * `:has(~ .SubGroup [data-active='true'])`. Keying off the ancestor's
+ * `data-active` avoids Safari's `:has()` invalidation cost, which is
+ * especially high here because the old anchor (`[data-active]`) toggles on
+ * every navigation and combined a general-sibling with a descendant match.
+ * The ancestor prefix keeps the original selector specificity (0,4,0).
+ */
+ .ActionListItem[data-active='true'] & {
background: var(--control-transparent-bgColor-selected);
& .ItemLabel {
@@ -655,13 +663,6 @@ default block */
word-break: normal;
}
- /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
- &:has([data-truncate='true']) {
- & .ItemLabel {
- flex: 1 0 auto;
- }
- }
-
& .Description {
/* stylelint-disable-next-line primer/typography */
line-height: 16px;
diff --git a/packages/react/src/ActionList/Heading.test.tsx b/packages/react/src/ActionList/Heading.test.tsx
index 2e32f776988..2bd6b5f72c5 100644
--- a/packages/react/src/ActionList/Heading.test.tsx
+++ b/packages/react/src/ActionList/Heading.test.tsx
@@ -5,6 +5,7 @@ import {ActionList} from '.'
import {ActionMenu} from '../ActionMenu'
import {implementsClassName, withExpectedConsoleError} from '../utils/testing'
import classes from './Heading.module.css'
+import visuallyHiddenClasses from '../_VisuallyHidden.module.css'
describe('ActionList.Heading', () => {
implementsClassName(
@@ -29,6 +30,41 @@ describe('ActionList.Heading', () => {
expect(heading).toHaveTextContent('Heading')
})
+ it('should not wrap the heading in a span', async () => {
+ const {getByRole} = HTMLRender(
+
+ Heading
+ ,
+ )
+ const heading = getByRole('heading', {level: 1})
+ expect(heading.parentElement?.tagName).not.toBe('SPAN')
+ expect(heading).toHaveClass(classes.ActionListHeader)
+ })
+
+ it('should apply the visually-hidden class to the heading when visuallyHidden is set', async () => {
+ const {getByRole} = HTMLRender(
+
+
+ Heading
+
+ ,
+ )
+ const heading = getByRole('heading', {level: 1})
+ expect(heading).toHaveClass(visuallyHiddenClasses.InternalVisuallyHidden)
+ expect(heading).toHaveClass(classes.ActionListHeader)
+ })
+
+ it('should not apply the visually-hidden class to the heading by default', async () => {
+ const {getByRole} = HTMLRender(
+
+ Heading
+ ,
+ )
+ const heading = getByRole('heading', {level: 1})
+ expect(heading).not.toHaveClass(visuallyHiddenClasses.InternalVisuallyHidden)
+ expect(heading).toHaveClass(classes.ActionListHeader)
+ })
+
it('should label the action list with the heading id', async () => {
const {container, getByRole} = HTMLRender(
diff --git a/packages/react/src/ActionList/Heading.tsx b/packages/react/src/ActionList/Heading.tsx
index 3ffcd843468..b8dd90e305d 100644
--- a/packages/react/src/ActionList/Heading.tsx
+++ b/packages/react/src/ActionList/Heading.tsx
@@ -3,11 +3,11 @@ import {useMergedRefs} from '../hooks'
import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
import {default as HeadingComponent} from '../Heading'
import {ListContext} from './shared'
-import VisuallyHidden from '../_VisuallyHidden'
import {ActionListContainerContext} from './ActionListContainerContext'
import {invariant} from '../utils/invariant'
import {clsx} from 'clsx'
import classes from './Heading.module.css'
+import visuallyHiddenClasses from '../_VisuallyHidden.module.css'
type HeadingLevels = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
type HeadingVariants = 'large' | 'medium' | 'small'
@@ -33,21 +33,23 @@ export const Heading = forwardRef(({as, size, children, visuallyHidden = false,
)
return (
-
-
- {children}
-
-
+
+ {children}
+
)
}) as PolymorphicForwardRefComponent
diff --git a/packages/react/src/Breadcrumbs/Breadcrumbs.module.css b/packages/react/src/Breadcrumbs/Breadcrumbs.module.css
index bd1691f28f0..17cf5ee538a 100644
--- a/packages/react/src/Breadcrumbs/Breadcrumbs.module.css
+++ b/packages/react/src/Breadcrumbs/Breadcrumbs.module.css
@@ -117,8 +117,9 @@
list-style: none;
/* allow menu items to wrap line */
- /* stylelint-disable-next-line selector-pseudo-class-disallowed-list -- scoped to CSS Module, audited (github/github-ui#17224) */
- &:has(.MenuOverlay) {
+ /* The overflow-menu item is marked in React (`data-overflow-menu`) instead of using
+ `:has(.MenuOverlay)`, avoiding Safari's `:has()` invalidation cost. */
+ &[data-overflow-menu] {
white-space: normal;
}
diff --git a/packages/react/src/Breadcrumbs/Breadcrumbs.tsx b/packages/react/src/Breadcrumbs/Breadcrumbs.tsx
index f348609e88b..00f3f266787 100644
--- a/packages/react/src/Breadcrumbs/Breadcrumbs.tsx
+++ b/packages/react/src/Breadcrumbs/Breadcrumbs.tsx
@@ -313,7 +313,7 @@ function Breadcrumbs({className, children, style, overflow = 'wrap', variant = '
// In 'menu-with-root' mode the root stays visible, so drop it from the menu.
const effectiveMenuItems = effectiveHideRoot ? menuItems : menuItems.slice(1)
const menuElement = (
-
+
export function FeatureFlags({children, flags}: FeatureFlagsProps) {
diff --git a/packages/react/src/NavList/NavList.dev.stories.tsx b/packages/react/src/NavList/NavList.dev.stories.tsx
index d4316028b7f..ea8017b59ea 100644
--- a/packages/react/src/NavList/NavList.dev.stories.tsx
+++ b/packages/react/src/NavList/NavList.dev.stories.tsx
@@ -1,4 +1,5 @@
import type {Meta} from '@storybook/react-vite'
+import {within, userEvent} from 'storybook/test'
import {PageLayout} from '../PageLayout'
import {NavList} from './NavList'
import {ArrowRightIcon, ArrowLeftIcon, BookIcon, FileDirectoryIcon} from '@primer/octicons-react'
@@ -69,3 +70,38 @@ export const WithGroupTitleAndHeading = () => (
)
+
+/**
+ * A collapsed parent item whose sub-nav contains the current item shows an
+ * active indicator. NavList auto-expands sub-navs that contain the current
+ * item, so the play function collapses it to surface the collapsed-parent
+ * active styling for visual regression coverage. This exercises the CSS that
+ * replaced `:has(~ .SubGroup [data-active])` with the parent's `data-active`.
+ */
+export const CollapsedSubNavWithCurrentItem = () => (
+
+
+
+ Item 1
+
+ Item with current sub-item
+
+
+ Current sub-item
+
+ Other sub-item
+
+
+ Item 3
+
+
+
+
+)
+
+CollapsedSubNavWithCurrentItem.storyName = 'Collapsed SubNav With Current Item'
+CollapsedSubNavWithCurrentItem.play = async ({canvasElement}: {canvasElement: HTMLElement}) => {
+ const canvas = within(canvasElement)
+ const parentButton = await canvas.findByRole('button', {name: /Item with current sub-item/i})
+ await userEvent.click(parentButton)
+}
diff --git a/packages/react/src/NavList/NavList.docs.json b/packages/react/src/NavList/NavList.docs.json
index f44605ffe60..6ea9ab1e73f 100644
--- a/packages/react/src/NavList/NavList.docs.json
+++ b/packages/react/src/NavList/NavList.docs.json
@@ -48,6 +48,46 @@
}
],
"subcomponents": [
+ {
+ "name": "NavList.Heading",
+ "props": [
+ {
+ "name": "as",
+ "type": "'h2' | 'h3'",
+ "defaultValue": "\"h2\"",
+ "required": false,
+ "description": "Semantic heading level for the NavList. Also sets the default level for child group headings, which render one level deeper (h3 under an h2, h4 under an h3). Constrained to h2/h3 so the hierarchy stays shallow."
+ },
+ {
+ "name": "visuallyHidden",
+ "type": "boolean",
+ "defaultValue": "false",
+ "required": false,
+ "description": "Visually hide the heading while keeping it available to assistive technology and as the accessible name for the `nav` landmark."
+ },
+ {
+ "name": "children",
+ "type": "ReactNode",
+ "required": true,
+ "description": "The text rendered as the NavList's heading."
+ },
+ {
+ "name": "id",
+ "type": "string",
+ "description": "Custom id for the heading element. When set, it is used as the `aria-labelledby` target that names the `nav` landmark; otherwise a generated id is used."
+ },
+ {
+ "name": "className",
+ "type": "string",
+ "description": "Custom CSS class name."
+ },
+ {
+ "name": "style",
+ "type": "React.CSSProperties",
+ "description": "Custom CSS styles."
+ }
+ ]
+ },
{
"name": "NavList.Item",
"props": [
@@ -194,10 +234,9 @@
},
{
"name": "as",
- "description": "Heading level for the group heading. Sets the semantic heading tag.",
+ "description": "Heading level for the group heading. Sets the semantic heading tag. Defaults to one level below a `NavList.Heading` (h3 under an h2, h4 under an h3), or `h3` when there is no `NavList.Heading`.",
"required": false,
- "type": "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'",
- "defaultValue": "\"h3\""
+ "type": "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'"
}
]
},
diff --git a/packages/react/src/NavList/NavList.features.stories.tsx b/packages/react/src/NavList/NavList.features.stories.tsx
index e575ffe71f6..fb3983f64c0 100644
--- a/packages/react/src/NavList/NavList.features.stories.tsx
+++ b/packages/react/src/NavList/NavList.features.stories.tsx
@@ -646,4 +646,48 @@ export const WithItemGap: StoryFn = () => (
WithItemGap.storyName = 'With gap between items (behind feature flag)'
+export const WithHeading: StoryFn = () => (
+
+
+
+ Settings
+
+
+ Profile
+
+ Appearance
+
+
+ Password and authentication
+ Sessions
+
+
+
+
+
+)
+
+export const WithVisuallyHiddenHeading: StoryFn = () => (
+
+
+
+ Settings
+
+
+ Profile
+
+ Appearance
+
+
+ Password and authentication
+ Sessions
+
+
+
+
+
+)
+
+WithVisuallyHiddenHeading.storyName = 'With Heading (hidden)'
+
export default meta
diff --git a/packages/react/src/NavList/NavList.module.css b/packages/react/src/NavList/NavList.module.css
index 9908361e112..93dbb6674eb 100644
--- a/packages/react/src/NavList/NavList.module.css
+++ b/packages/react/src/NavList/NavList.module.css
@@ -1,3 +1,9 @@
+.Heading {
+ margin-block-end: var(--base-size-8);
+ /* stylelint-disable-next-line primer/spacing */
+ margin-inline-start: calc(var(--control-medium-paddingInline-condensed) + var(--base-size-8));
+}
+
.GroupHeading > a {
color: var(--fgColor-default);
text-decoration: inherit;
diff --git a/packages/react/src/NavList/NavList.test.tsx b/packages/react/src/NavList/NavList.test.tsx
index b70f1314d4b..cedde128ac5 100644
--- a/packages/react/src/NavList/NavList.test.tsx
+++ b/packages/react/src/NavList/NavList.test.tsx
@@ -619,4 +619,137 @@ describe('NavList.ShowMoreItem with pages', () => {
expect(getComputedStyle(subGroup as HTMLElement).marginBlockStart).toBe('0px')
})
})
+
+ describe('NavList.Heading', () => {
+ it('renders an h2 heading by default', () => {
+ const {getByRole} = render(
+
+ Settings
+ Item 1
+ ,
+ )
+
+ expect(getByRole('heading', {level: 2, name: 'Settings'})).toBeInTheDocument()
+ })
+
+ it('respects an explicit heading level via the `as` prop', () => {
+ const {getByRole} = render(
+
+ Settings
+ Item 1
+ ,
+ )
+
+ expect(getByRole('heading', {level: 3, name: 'Settings'})).toBeInTheDocument()
+ })
+
+ it('labels the nav landmark with the heading', () => {
+ const {getByRole} = render(
+
+ Settings
+ Item 1
+ ,
+ )
+
+ const nav = getByRole('navigation', {name: 'Settings'})
+ const heading = getByRole('heading', {name: 'Settings'})
+ expect(nav).toHaveAttribute('aria-labelledby', heading.id)
+ })
+
+ it('does not override a consumer-supplied aria-label', () => {
+ const {getByRole} = render(
+
+ Settings
+ Item 1
+ ,
+ )
+
+ const nav = getByRole('navigation', {name: 'Custom label'})
+ expect(nav).not.toHaveAttribute('aria-labelledby')
+ })
+
+ it('defaults group headings to one level below the NavList.Heading', () => {
+ const {getByRole} = render(
+
+ Settings
+
+ Profile
+
+ ,
+ )
+
+ expect(getByRole('heading', {level: 2, name: 'Settings'})).toBeInTheDocument()
+ expect(getByRole('heading', {level: 3, name: 'Account'})).toBeInTheDocument()
+ })
+
+ it('derives group headings to h4 when the NavList.Heading is an h3', () => {
+ const {getByRole} = render(
+
+ Settings
+
+ Profile
+
+ ,
+ )
+
+ expect(getByRole('heading', {level: 3, name: 'Settings'})).toBeInTheDocument()
+ expect(getByRole('heading', {level: 4, name: 'Account'})).toBeInTheDocument()
+ })
+
+ it('keeps the h3 group heading default when there is no NavList.Heading', () => {
+ const {getByRole} = render(
+
+
+ Profile
+
+ ,
+ )
+
+ expect(getByRole('heading', {level: 3, name: 'Account'})).toBeInTheDocument()
+ })
+
+ it('lets group headings override their computed level with `as`', () => {
+ const {getByRole} = render(
+
+ Settings
+
+ Account
+ Profile
+
+ ,
+ )
+
+ expect(getByRole('heading', {level: 4, name: 'Account'})).toBeInTheDocument()
+ })
+
+ it('keeps a visually hidden heading in the accessibility tree', () => {
+ const {getByRole} = render(
+
+ Settings
+ Item 1
+ ,
+ )
+
+ const heading = getByRole('heading', {level: 2, name: 'Settings'})
+ expect(heading).toBeInTheDocument()
+ expect(getByRole('navigation', {name: 'Settings'})).toBeInTheDocument()
+ // The visually-hidden styles are applied to the heading itself, not a wrapping element.
+ expect(heading.parentElement?.tagName).not.toBe('SPAN')
+ })
+
+ it('forwards standard HTML attributes to the heading element', () => {
+ const {getByRole} = render(
+
+
+ Settings
+
+ Item 1
+ ,
+ )
+
+ const heading = getByRole('heading', {level: 2, name: 'Settings'})
+ expect(heading).toHaveAttribute('data-testid', 'nav-heading')
+ expect(heading).toHaveAttribute('title', 'Section navigation')
+ })
+ })
})
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index 6af6985976b..3deb4662531 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -19,6 +19,31 @@ import navListClasses from './NavList.module.css'
import {flushSync} from 'react-dom'
import {useSlots} from '../hooks/useSlots'
import {fixedForwardRef, type PolymorphicProps} from '../utils/modern-polymorphic'
+import HeadingComponent from '../Heading'
+import visuallyHiddenClasses from '../_VisuallyHidden.module.css'
+import type {FCWithSlotMarker} from '../utils/types/Slots'
+
+type HeadingLevels = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+
+// NavList establishes a shallow hierarchy: the NavList itself is named by a
+// heading (h2 or h3) and its groups render one level deeper (h3 or h4). We don't
+// expose an h1 (that's the page title) and we don't go deeper than h4.
+type NavListHeadingLevels = 'h2' | 'h3'
+
+// Publishes the resolved numeric level of a NavList.Heading (e.g. 2 for an h2) so
+// NavList.Group/NavList.GroupHeading can default to one level deeper. `null` when
+// there is no NavList.Heading, in which case groups keep their historical h3 default.
+const NavListHeadingLevelContext = React.createContext(null)
+
+function headingTagToLevel(as: NavListHeadingLevels): number {
+ return Number.parseInt(as.slice(1), 10)
+}
+
+function levelToHeadingTag(level: number): HeadingLevels {
+ // Clamp to h4 so group headings never go deeper than the supported hierarchy.
+ const clamped = Math.min(Math.max(level, 1), 4)
+ return `h${clamped}` as HeadingLevels
+}
// ----------------------------------------------------------------------------
// NavList
@@ -27,21 +52,77 @@ export type NavListProps = {
children: React.ReactNode
} & React.ComponentProps<'nav'>
-const Root = React.forwardRef(({children, ...props}, ref) => {
+const Root = React.forwardRef(
+ ({children, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ...props}, ref) => {
+ const [slots, childrenWithoutHeading] = useSlots(children, {
+ heading: Heading,
+ })
+
+ const fallbackHeadingId = useId()
+ const heading = slots.heading
+ const headingId = heading ? (heading.props.id ?? fallbackHeadingId) : undefined
+ const headingLevel = heading ? headingTagToLevel(heading.props.as ?? 'h2') : null
+
+ // Don't override a consumer-supplied accessible name; otherwise label the
+ //