An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file SideNavItem.tsx
* @input Uses React, ReactNode, StyleX, Icon, IconType, useMenuHover
* @output Exports SideNavItem component and SideNavItemProps
* @position Core implementation; used inside SideNav children
*
* Navigation item with icon, selected state, row-level actions, and nesting.
* Collapsed icon-only controls use a meaningful consumer `aria-label` when
* provided and fall back to `label` when it is missing or blank. Their label
* tooltip binds to the interactive control through a callback ref, so hover,
* keyboard focus, and `aria-describedby` follow the control from the first
* collapsed render. A disabled control takes no pointer, so its row listens
* for the tooltip instead, while the control keeps focus and the description.
*
* Collapsed items with children open their submenu flyout through
* `useMenuHover`, the shared hover-intent hook (same one `SideNavHeading` and
* `TopNavMenu` use). Hover is a progressive enhancement over the popover's
* click behavior and is inert on coarse pointers.
*
* Nested rows span the full width of the nav list, like top-level rows, so
* their hover and selected fill lines up with the rows above them. The
* nesting indent sits inside the row as extra inline-start padding, one step
* per level, tracked through a private depth context.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/SideNav/SideNav.doc.mjs
* - /packages/core/src/SideNav/SideNav.test.tsx
* - /packages/core/src/SideNav/index.ts
* - /apps/storybook/stories/SideNav.stories.tsx
* - /packages/cli/assets/templates/blocks/components/SideNav/ (showcase blocks)
*/
import {
use,
useCallback,
useId,
useMemo,
useState,
type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
spacingVars,
sizeVars,
fontWeightVars,
typeScaleVars,
durationVars,
easeVars,
radiusVars,
} from '../theme/tokens.stylex';
import {Icon, renderIconSlot, type IconType} from '../Icon';
import {useLinkComponent} from '../Link/useLinkComponent';
import type {LinkComponentType} from '../Link/types';
import {usePopover} from '../Popover/usePopover';
import {useMenuHover} from '../hooks/useMenuHover';
import {mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import {useTooltip} from '../Tooltip';
import {navItemStyles, type NavItemSize} from '../NavItem/navItemStyles.stylex';
import {SizeProvider} from '../SizeContext/SizeContext';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';
import {
useSideNavCollapse,
SideNavCollapseContext,
} from './SideNavCollapseContext';
import {useSideNavRenderMode} from './SideNavRenderContext';
import {useCloseMobileDrawerOnActivate} from '../AppShell/useCloseMobileDrawerOnActivate';
import {themeProps} from '../utils/themeProps';
import {
disabledInteractionProps,
withholdCallerHandlers,
} from '../utils/disabledInteraction';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {SideNavFocusTargetsContext} from './SideNavFocusTargetsContext';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/SideNav/SideNavItem.generated';
import {isRenderable} from '../utils/isRenderable';
import {createSharedContext} from '../utils/sharedContext';
registerEnglishFallback(english);
// =============================================================================
// Styles
// =============================================================================
const styles = stylex.create({
root: {
display: 'flex',
flexDirection: 'column',
width: '100%',
},
// A collapsed rail row holds only its icon, so it keeps a fixed square.
itemCollapsed: {
justifyContent: 'center',
width: sizeVars['--size-element-md'],
height: sizeVars['--size-element-md'],
paddingInline: 0,
},
itemCollapsedSm: {
width: sizeVars['--size-element-sm'],
height: sizeVars['--size-element-sm'],
},
itemCollapsedLg: {
width: sizeVars['--size-element-lg'],
height: sizeVars['--size-element-lg'],
},
label: {
flex: 1,
minWidth: 0,
overflow: 'hidden',
textOverflow: 'ellipsis',
whiteSpace: 'nowrap',
},
endContent: {
flexShrink: 0,
display: 'flex',
alignItems: 'center',
},
// Row-level secondary controls (actions slot) — siblings of the primary
// element at the trailing edge of the row. pointerEvents opts back in when
// a disabled row's navItemStyles.disabled sets pointer-events: none on the
// wrapper: the slot is passthrough, so each control owns its own disabled
// state (keyboard focus already reaches it either way).
actions: {
flexShrink: 0,
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-1'],
pointerEvents: 'auto',
},
// The group clips its rows only for the 0fr collapse animation. Nested rows
// sit flush with the group, so a permanent clip would cut off their focus
// ring, which paints outside the row. The expanded group therefore stops
// clipping once it has finished opening: `overflow` is discrete, so it rides
// the same transition with `allow-discrete` and a delay equal to the open
// duration, holding `hidden` until the rows' height has settled. Collapsing
// flips back to `hidden` at once (no delay on the collapsed state), so
// nothing spills while the group closes.
//
// Reduced fallback: a browser without `transition-behavior: allow-discrete`
// (the tier below current Baseline) cannot delay the switch, so the group
// stops clipping as soon as it starts opening and the opening rows briefly
// overlap the row below. The group still opens and the ring still shows.
childrenCollapsible: {
display: 'grid',
gridTemplateRows: '1fr',
overflow: 'visible',
transitionProperty: 'grid-template-rows, overflow',
transitionBehavior: 'allow-discrete',
transitionDuration: {
default: `${durationVars['--duration-medium']}, 0s`,
'@media (prefers-reduced-motion: reduce)': '0s, 0s',
},
transitionDelay: {
default: `0s, ${durationVars['--duration-medium']}`,
'@media (prefers-reduced-motion: reduce)': '0s, 0s',
},
transitionTimingFunction: easeVars['--ease-standard'],
},
childrenCollapsed: {
gridTemplateRows: '0fr',
overflow: 'hidden',
transitionDelay: '0s, 0s',
},
// No inline padding: nested rows fill the full width of the nav list, and
// each row carries its own indent (`indentStyles` below). `minHeight: 0`
// lets the 0fr track shrink this item to nothing; the group clips it.
childrenInner: {
minHeight: 0,
},
expandChevron: {
display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
width: spacingVars['--spacing-6'],
height: spacingVars['--spacing-6'],
// Icon's `lg` would also set font-size: 1.5rem, and the registry chevron
// is a 1em SVG — that would blow the glyph up from the 14px it inherits
// from the row to the full 24px box. The 24px box is the touch/alignment
// target, not the glyph size, so keep the glyph on the inherited size.
fontSize: 'inherit',
transitionProperty: 'transform',
transitionDuration: {
default: durationVars['--duration-fast'],
'@media (prefers-reduced-motion: reduce)': '0s',
},
transitionTimingFunction: easeVars['--ease-standard'],
flexShrink: 0,
},
// Inside a whole-row toggle the chevron takes its 1em glyph's height, so
// the row's height comes from its label, not from the chevron's box.
expandChevronInRow: {
height: 'auto',
},
expandChevronExpanded: {
transform: 'rotate(180deg)',
},
// Standalone toggle button for the chevron when collapsible + href.
// Boxed like a `size="sm"` icon Button so it and whatever sits in
// `actions` paint one size of hover pill; without a box of its own it
// shrank to the 24px chevron beside a 28px menu button.
// SYNC: matches ROW_CONTROL_SIZE below.
expandToggle: {
width: sizeVars['--size-element-sm'],
height: sizeVars['--size-element-sm'],
display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
flexShrink: 0,
padding: 0,
margin: 0,
borderWidth: 0,
borderStyle: 'none',
backgroundColor: 'transparent',
color: 'inherit',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
borderRadius: radiusVars['--radius-element'],
},
// Primary action element inside the split-action row (link or button).
// Flex:1 so it fills remaining space, giving a wide click target.
// `alignSelf: stretch` makes it fill the row's height too — without it the
// element collapses to its line box (20px), under the 24px WCAG 2.5.8
// target-size floor even though the row it sits in is 32px tall.
// Resets both link and button appearance so it blends into the row.
splitAction: {
display: 'flex',
alignItems: 'center',
alignSelf: 'stretch',
gap: spacingVars['--spacing-2'],
flex: 1,
minWidth: 0,
color: 'inherit',
textDecoration: 'none',
padding: 0,
margin: 0,
borderWidth: 0,
borderStyle: 'none',
backgroundColor: 'transparent',
fontFamily: 'inherit',
fontSize: 'inherit',
fontWeight: 'inherit',
lineHeight: 'inherit',
textAlign: 'start',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
},
// No border and no background: `usePopover` paints the panel this renders
// into. Drawing a second surface here put square corners inside its rounded
// ones. The radius matches so a theme retargeting `--radius-container`
// keeps the two in step.
popoverSurface: {
borderRadius: radiusVars['--radius-container'],
paddingBlock: spacingVars['--spacing-1'],
paddingInline: spacingVars['--spacing-1'],
minWidth: 180,
},
// The gap from the rail belongs on the positioned layer, where
// `DropdownMenu` keeps it. On the content div it insets the content instead,
// leaving the panel flush against the rail.
popoverGap: {
marginInlineStart: spacingVars['--spacing-1'],
marginInlineEnd: spacingVars['--spacing-1'],
},
popoverHeader: {
paddingInline: spacingVars['--spacing-2'],
paddingBlock: spacingVars['--spacing-1'],
fontSize: typeScaleVars['--text-supporting-size'],
fontWeight: fontWeightVars['--font-weight-semibold'],
color: colorVars['--color-text-secondary'],
lineHeight: typeScaleVars['--text-supporting-leading'],
},
});
// Nesting indent, drawn inside the row: one `--spacing-6` step per nesting
// level. The row itself stays full width, so its hover and selected fill
// matches a top-level row's.
// - `sm` / `md` — the ordinary row, where the row element is the link or
// button: its own inline-start padding plus the steps.
// SYNC: the base padding matches navItemStyles.sm / .md / .lg.
// - `primary` — the row-wrapper path: the wrapper keeps its base padding and
// the steps go on the primary link or button, so the whole indent is part
// of the click target rather than dead space that still shows feedback.
const indentStyles = stylex.create({
sm: (depth: number) => ({
paddingInlineStart: `calc(${spacingVars['--spacing-1']} + ${depth} * ${spacingVars['--spacing-6']})`,
}),
md: (depth: number) => ({
paddingInlineStart: `calc(${spacingVars['--spacing-2']} + ${depth} * ${spacingVars['--spacing-6']})`,
}),
primary: (depth: number) => ({
paddingInlineStart: `calc(${depth} * ${spacingVars['--spacing-6']})`,
}),
});
/**
* How many SideNavItems deep the current item sits: 0 at the top level,
* 1 inside one parent, and so on. A collapsed rail's flyout resets it to 0,
* since the flyout lists a parent's children as its own top level.
*/
const SideNavItemDepthContext = createSharedContext(
'SideNavItemDepthContext',
1,
0,
);
SideNavItemDepthContext.displayName = 'SideNavItemDepthContext';
/**
* Cascaded to the `actions` slot through `SizeContext` so a consumer's row
* controls come out the same height as the built-in expand/collapse toggle,
* the way `SideNav` already cascades one size to its footer icons. An
* explicit `size` on a supplied control still wins.
*
* SYNC: `styles.expandToggle` carries the matching box.
*/
const ROW_CONTROL_SIZE = 'sm';
// Non-collapsed state for popover children — ensures nested items render expanded
const EXPANDED_COLLAPSE_STATE = {
isCollapsed: false,
toggle: () => {},
isCollapsible: false,
};
// =============================================================================
// NavItemElement — resolves link vs button based on props
// =============================================================================
interface NavItemElementProps {
href?: string;
as?: LinkComponentType;
isDisabled?: boolean;
onClick?: (e: React.MouseEvent) => void;
ref?: React.Ref<HTMLElement>;
children: ReactNode;
[key: string]: unknown;
}
/**
* Renders `<a>` (via LinkComponent) when `href` is set, otherwise `<button>`.
* Centralizes the link-vs-button decision used across all SideNavItem paths.
* A disabled item is a `<button>` that keeps its tab stop and exposes
* `aria-disabled`, but is inert (spec:AST-085 FR1, FR2).
*/
function NavItemElement({
href,
as,
isDisabled,
onClick,
ref,
children,
...rest
}: NavItemElementProps) {
const LinkComponent = useLinkComponent(as);
if (href && !isDisabled) {
return (
<LinkComponent
ref={ref as React.Ref<HTMLAnchorElement>}
href={href}
onClick={onClick}
{...rest}>
{children}
</LinkComponent>
);
}
return (
<button
ref={ref as React.Ref<HTMLButtonElement>}
type="button"
onClick={onClick}
// A disabled item keeps its tab stop, so the browser still sends it events.
// It runs no caller handler except `onFocus` and `onBlur`.
{...withholdCallerHandlers(rest, !!isDisabled)}
{...(isDisabled
? {
'aria-disabled': true,
...disabledInteractionProps<HTMLButtonElement>(),
}
: null)}>
{children}
</button>
);
}
/** Joins the non-empty ids into one `aria-describedby` value. */
function joinIds(...ids: (string | null | undefined)[]): string | undefined {
const joined = ids.filter(Boolean).join(' ');
return joined === '' ? undefined : joined;
}
// =============================================================================
// Types
// =============================================================================
export interface SideNavItemProps extends BaseProps<HTMLElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLElement>;
/**
* Custom component to render instead of `<a>` for link items.
* Overrides the provider-level default set by LinkProvider.
* Only applies when `href` is provided. Must accept href, className, style, and children props.
*/
as?: LinkComponentType;
/**
* Item label.
*/
label: string;
/**
* Icon (outline variant).
*/
icon?: ReactNode | IconType;
/**
* Icon when selected (filled variant).
*/
selectedIcon?: ReactNode | IconType;
/**
* Current page indicator.
* @default false
*/
isSelected?: boolean;
/**
* Whether the item is disabled.
* @default false
*/
isDisabled?: boolean;
/**
* Navigation URL.
*/
href?: string;
/**
* Click handler.
*/
onClick?: (e: React.MouseEvent) => void;
/**
* Passive right-side content only (badges, counts). Interactive
* controls (icon buttons, menus) go in `actions`. `endContent`
* renders inside the primary link or button.
*/
endContent?: ReactNode;
/**
* Row-level secondary controls (icon buttons, menus) rendered as siblings
* of the primary element at the trailing edge of the row — after the
* expand/collapse toggle, and before any nested children in DOM and focus
* order. Content is passthrough: each control owns its accessible name,
* keyboard behavior, and disabled state. Hidden while the SideNav rail is
* collapsed.
*
* Controls inherit the row's control size through `SizeContext`, so an
* unsized icon button comes out the same box as the built-in
* expand/collapse toggle. An explicit `size` still wins.
*/
actions?: ReactNode;
/**
* Sub-items for nesting. Nested items span the full width of the nav
* list, like top-level items; their content is indented one step per
* nesting level.
*/
children?: ReactNode;
/**
* Enables collapse behavior for items with children.
* When true, clicking the item toggles visibility of sub-items.
*
* - `true` — collapsible with defaults (starts expanded)
* - Object — controlled/configured:
* - `defaultIsCollapsed` — start collapsed (default: false)
* - `isCollapsed` + `onCollapsedChange` — controlled mode
*
* @default false
*/
collapsible?:
| boolean
| {
defaultIsCollapsed?: boolean;
isCollapsed?: boolean;
onCollapsedChange?: (isCollapsed: boolean) => void;
};
/**
* Size variant for the nav item.
* @default 'md'
*/
size?: NavItemSize;
}
// =============================================================================
// Component
// =============================================================================
/**
* Navigation item for SideNav.
*
* Supports icons, selected state, nesting, and end content like badges or
* counts. Interactive row-level controls (menus, icon buttons) go in
* `actions`, which renders them as siblings of the primary element — never
* nested inside it — before any nested children in DOM and focus order.
*
* @example
* ```
* <SideNavItem
* label="Dashboard"
* icon={HomeIcon}
* selectedIcon={HomeIconSolid}
* isSelected
* href="/dashboard"
* />
* <SideNavItem label="Settings" icon={CogIcon}>
* <SideNavItem label="General" href="/settings/general" />
* <SideNavItem label="Security" href="/settings/security" />
* </SideNavItem>
* <SideNavItem
* label="Projects"
* href="/projects"
* collapsible
* actions={<MoreMenu label="Project actions" items={items} />}>
* <SideNavItem label="Alpha" href="/projects/alpha" />
* </SideNavItem>
* ```
*/
export function SideNavItem({
as,
label,
icon,
selectedIcon,
isSelected = false,
isDisabled = false,
href,
onClick,
endContent,
actions,
children,
collapsible: itemCollapsible,
size = 'md',
'data-testid': testId,
ref,
xstyle,
...rest
}: SideNavItemProps) {
// The row (or, collapsed, the trigger/link/button) is the pressable; the
// expand toggle inside it is its own.
const pressable = usePressFeedback();
const t = useComponentTranslator();
const {isCollapsed} = useSideNavCollapse();
const renderMode = useSideNavRenderMode();
const isInDrawer = renderMode === 'drawer' || renderMode === 'drawer-content';
const closeDrawerAfter = useCloseMobileDrawerOnActivate(isInDrawer);
const id = useId();
const hasChildren = !!children;
const depth = use(SideNavItemDepthContext);
// Popover for collapsed items with children
const popover = usePopover({
hasLightDismiss: true,
hasAutoFocus: true,
hasCloseButton: false,
dialogLabel: t('@astryx.sideNavItem.submenuLabel', {label}),
});
const mergedTriggerRef = useMergedRefs(ref, popover.triggerRef);
// Label tooltip for a collapsed leaf. It binds through a callback ref and
// its id renders as an `aria-describedby` prop, so both follow the element
// they describe across re-renders. The hook outlives the collapsed branch,
// so it is held shut whenever the item is not a collapsed leaf: a tooltip
// open when the rail expands must not come back on the next collapse.
const isRailLeaf = isCollapsed && !hasChildren;
const railTooltip = useTooltip({
placement: 'end',
// A disabled leaf's row is the trigger (see the collapsed path). It is not
// focusable itself, so `auto` would never hear the focus that bubbles up
// from its control.
focusTrigger: 'always',
isEnabled: isRailLeaf,
isOpen: isRailLeaf ? undefined : false,
});
const railLeafRef = useMergedRefs(ref, railTooltip.ref);
// The row's root registers with its SideNav, so a collapse that removes the
// focused row can hand focus to the toggle or the nearest row still in the
// rail (`component:SideNav` AR3).
const focusTargets = use(SideNavFocusTargetsContext);
// The collapsed rail renders a top-level row with an icon (FR2).
const isKeptInRail = !!icon && depth === 0;
const rowRef = useCallback(
(element: HTMLDivElement | null) =>
element == null || focusTargets == null
? undefined
: focusTargets.registerRow(element, isKeptInRail),
[focusTargets, isKeptInRail],
);
const rowTooltipRef = useMergedRefs(rowRef, railTooltip.ref);
// Collapse state for items with children
const itemCollapsibleConfig = useMemo(
() => (typeof itemCollapsible === 'object' ? itemCollapsible : {}),
[itemCollapsible],
);
const isItemCollapsible = hasChildren && itemCollapsible !== false;
const itemControlledCollapsed = itemCollapsibleConfig.isCollapsed;
const isItemControlled = itemControlledCollapsed !== undefined;
const [uncontrolledCollapsed, setUncontrolledCollapsed] = useState(
itemCollapsibleConfig.defaultIsCollapsed ?? false,
);
const isItemCollapsed = isItemControlled
? itemControlledCollapsed
: uncontrolledCollapsed;
const toggleItemCollapse = useCallback(() => {
const next = !isItemCollapsed;
if (!isItemControlled) {
setUncontrolledCollapsed(next);
}
itemCollapsibleConfig.onCollapsedChange?.(next);
}, [isItemCollapsed, isItemControlled, itemCollapsibleConfig]);
const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
// When collapsible + a primary action (href or onClick), the action and
// toggle are independent: clicking the label navigates/fires onClick,
// clicking the chevron expands/collapses children.
const hasPrimaryAction = !!href || !!onClick;
const hasIndependentToggle =
isItemCollapsible && hasPrimaryAction && !isCollapsed;
const hasActions = !!actions;
const handleClick = (e: React.MouseEvent) => {
if (isDisabled) {
e.preventDefault();
return;
}
if (isItemCollapsible && !hasIndependentToggle && !isCollapsed) {
e.preventDefault();
toggleItemCollapse();
return;
}
closeDrawerAfter(onClick)?.(e);
};
const handleToggleClick = (e: React.MouseEvent) => {
e.preventDefault();
e.stopPropagation();
toggleItemCollapse();
};
// Pointer half only. The hook's `onKeyDown`/`menuRef` drive a `useListFocus`
// over `[role="menuitem"]`, and this flyout is a focus-trapped dialog of
// links — wiring them would swallow arrow keys rather than navigate with
// them. Keyboard stays with `usePopover`'s trap, as in DropdownMenuSubMenu.
const {triggerProps: hoverTriggerProps, contentProps: hoverContentProps} =
useMenuHover({
show: popover.show,
hide: popover.hide,
isOpen: popover.isOpen,
isEnabled: isCollapsed && hasChildren,
// Standard popover toggling: the flyout opens beside the rail, not over
// the icon, so the click after a hover-open is a deliberate dismissal
// rather than the #3121 confirmation the nav menus need.
clickGuardMs: 0,
ownsFocus: false,
});
// In collapsed mode: hide items without icons
if (isCollapsed && !icon) {
return null;
}
// =========================================================================
// Collapsed mode — icon-only items, popover for items with children
// =========================================================================
if (isCollapsed) {
const collapsedIcon =
displayIcon &&
renderIconSlot(displayIcon, {
size: 'sm',
// `inherit` so a selected row's icon follows the row to HighlightText
// under forced colors. Identical to `primary` otherwise: both token
// families are emitted from one expression.
color: isSelected ? 'inherit' : isDisabled ? 'disabled' : 'secondary',
});
// Shared collapsed item styles — used by trigger, link, and button.
// All three render a focusable element, so each draws the shared ring.
const collapsedItemStyles = {
...mergeProps(
themeProps('side-nav-item', {
size,
selected: isSelected ? 'selected' : null,
disabled: isDisabled ? 'disabled' : null,
}),
focusOutlineProps.focusVisible(
navItemStyles.item,
interactionOverlayStyles.backgroundColor,
navItemStyles[size],
styles.itemCollapsed,
size === 'sm' && styles.itemCollapsedSm,
size === 'lg' && styles.itemCollapsedLg,
isSelected && navItemStyles.selected,
isDisabled && navItemStyles.disabled,
),
// Spread after `rest`, so keep the caller's class beside these.
rest.className,
),
...pressable,
};
const collapsedAccessibleLabel =
rest['aria-label'] != null && rest['aria-label'].trim() !== ''
? rest['aria-label']
: label;
// Items with children: popover trigger + popover
if (hasChildren) {
return (
<div ref={rowRef} {...stylex.props(styles.root, xstyle)}>
<button
ref={mergedTriggerRef}
type="button"
{...rest}
{...hoverTriggerProps}
aria-label={collapsedAccessibleLabel}
data-testid={testId}
{...popover.triggerProps}
{...collapsedItemStyles}>
{collapsedIcon}
</button>
{popover.render(
<div
{...stylex.props(styles.popoverSurface)}
onMouseEnter={hoverContentProps.onMouseEnter}
onMouseLeave={hoverContentProps.onMouseLeave}
onClick={() => popover.hide()}>
<div {...stylex.props(styles.popoverHeader)}>{label}</div>
<SideNavCollapseContext value={EXPANDED_COLLAPSE_STATE}>
<SideNavItemDepthContext value={0}>
{children}
</SideNavItemDepthContext>
</SideNavCollapseContext>
</div>,
{placement: 'end', alignment: 'start', xstyle: styles.popoverGap},
)}
</div>
);
}
// Items without children: icon-only link or button, its label in a
// tooltip. The control is the trigger, so the element that takes focus is
// the one described. A disabled control takes no pointer
// (`navItemStyles.disabled`), so its row listens for the tooltip instead;
// the control still takes focus (focusin reaches the row) and stays the
// element described (spec:AST-085 FR5).
const isRowTrigger = isDisabled;
const collapsedAriaProps = {
'aria-current': isSelected ? ('page' as const) : undefined,
'aria-describedby': joinIds(
rest['aria-describedby'],
railTooltip.describedBy,
),
'aria-disabled': isDisabled || undefined,
'aria-label': collapsedAccessibleLabel,
'data-testid': testId,
};
const collapsedElement = (
<NavItemElement
ref={isRowTrigger ? ref : railLeafRef}
href={href}
as={as}
isDisabled={isDisabled}
onClick={handleClick}
{...rest}
{...collapsedAriaProps}
{...collapsedItemStyles}>
{collapsedIcon}
</NavItemElement>
);
return (
<div
ref={isRowTrigger ? rowTooltipRef : rowRef}
{...stylex.props(styles.root, xstyle)}>
{collapsedElement}
{railTooltip.renderTooltip(label)}
</div>
);
}
const itemContent = (
<>
{displayIcon &&
renderIconSlot(displayIcon, {
size: 'sm',
// `inherit` — see the collapsed path above.
color: isSelected ? 'inherit' : isDisabled ? 'disabled' : 'secondary',
})}
{!isCollapsed && <span {...stylex.props(styles.label)}>{label}</span>}
{!isCollapsed && isRenderable(endContent) && (
<span {...stylex.props(styles.endContent)}>{endContent}</span>
)}
{!isCollapsed && isItemCollapsible && !hasIndependentToggle && (
<Icon
icon="chevronDown"
size="lg"
color="inherit"
xstyle={[
styles.expandChevron,
styles.expandChevronInRow,
!isItemCollapsed && styles.expandChevronExpanded,
]}
/>
)}
</>
);
const itemThemeProps = themeProps('side-nav-item', {
size,
selected: isSelected ? 'selected' : null,
disabled: isDisabled ? 'disabled' : null,
});
const itemStyleArgs = [
navItemStyles.item,
interactionOverlayStyles.backgroundColor,
navItemStyles[size],
isSelected && navItemStyles.selected,
isDisabled && navItemStyles.disabled,
] as const;
const rowIndent =
depth > 0 && indentStyles[size === 'sm' ? 'sm' : 'md'](depth);
const primaryIndent = depth > 0 && indentStyles.primary(depth);
// The indent is a runtime value, so it reaches the element as an inline
// style. These props are spread after `rest`, so fold the caller's `style`
// back in (caller wins) rather than letting the indent replace it, and the
// caller's `className` beside the row's own classes.
const callerStyle = {className: rest.className, style: rest.style};
// Three shapes of the same row appearance:
// - `rowProps` — split-action path (toggle, no actions): presentational
// <div>; the ring belongs on each child tab stop.
// - `focusableRowProps` — ordinary row: the row element is the control.
// - `actionsRowProps` — same pill, but the ring is drawn for the primary
// only. The wrapper is not a tab stop, so `:focus-visible` on it would
// never match, and matching any descendant instead would light the whole
// row around the chevron's or an action's own ring.
const rowProps = {
...mergeProps(itemThemeProps, stylex.props(...itemStyleArgs)),
...pressable,
};
const focusableRowProps = {
...mergeProps(
itemThemeProps,
mergeProps(
focusOutlineProps.focusVisible(...itemStyleArgs, rowIndent),
callerStyle,
),
),
...pressable,
};
const actionsRowProps = {
...mergeProps(
itemThemeProps,
focusOutlineProps.focusWithinFirstChild(...itemStyleArgs),
),
...pressable,
};
// Row-wrapper path: primary element + row controls as siblings.
//
// Used when the row carries more than one control: an independent
// expand/collapse toggle (collapsible + href/onClick), consumer-supplied
// actions, or both. A <div> is the styled flex row; the primary link or
// button, the chevron toggle, and the actions slot render as siblings so
// no interactive element nests inside another, and every row-level
// control precedes the nested children group in DOM and focus order.
const hasRowWrapper = hasIndependentToggle || hasActions;
let itemElement;
if (hasRowWrapper) {
// aria-expanded/-controls stay on the primary element only when the
// whole row is the collapse toggle (no independent chevron button).
const rowPrimaryAriaProps = hasIndependentToggle
? {'aria-current': isSelected ? ('page' as const) : undefined}
: {
'aria-current': isSelected ? ('page' as const) : undefined,
'aria-disabled': isDisabled || undefined,
'aria-expanded': isItemCollapsible ? !isItemCollapsed : undefined,
'aria-controls': isItemCollapsible ? `${id}-children` : undefined,
};
itemElement = (
<div data-testid={testId} {...(hasActions ? actionsRowProps : rowProps)}>
<NavItemElement
ref={ref}
href={href}
as={as}
isDisabled={isDisabled}
onClick={handleClick}
{...rest}
{...rowPrimaryAriaProps}
{...mergeProps(
hasActions
? // The wrapper rings for this element; suppressing here is what
// keeps the UA's own ring from painting inside that one.
focusOutlineProps.suppressed(styles.splitAction, primaryIndent)
: focusOutlineProps.focusVisible(
styles.splitAction,
primaryIndent,
),
callerStyle,
)}>
{itemContent}
</NavItemElement>
{hasIndependentToggle && (
<button
type="button"
onClick={handleToggleClick}
aria-label={
isItemCollapsed
? t('@astryx.sideNavItem.expand', {label})
: t('@astryx.sideNavItem.collapse', {label})
}
aria-expanded={!isItemCollapsed}
aria-controls={`${id}-children`}
{...pressable}
{...focusOutlineProps.focusVisible(
styles.expandToggle,
interactionOverlayStyles.backgroundColor,
)}>
<Icon
icon="chevronDown"
size="lg"
color="inherit"
xstyle={[
styles.expandChevron,
!isItemCollapsed && styles.expandChevronExpanded,
]}
/>
</button>
)}
{hasActions && (
<span {...stylex.props(styles.actions)}>
<SizeProvider value={ROW_CONTROL_SIZE}>{actions}</SizeProvider>
</span>
)}
</div>
);
} else {
const ariaProps = {
'aria-current': isSelected ? ('page' as const) : undefined,
'aria-disabled': isDisabled || undefined,
'aria-expanded': isItemCollapsible ? !isItemCollapsed : undefined,
'aria-controls': isItemCollapsible ? `${id}-children` : undefined,
'data-testid': testId,
};
itemElement = (
<NavItemElement
ref={ref}
href={href}
as={as}
isDisabled={isDisabled}
onClick={handleClick}
{...rest}
{...ariaProps}
{...focusableRowProps}>
{itemContent}
</NavItemElement>
);
}
const item = (
<div ref={rowRef} {...stylex.props(styles.root, xstyle)}>
{itemElement}
{hasChildren && !isCollapsed && (
<div
id={`${id}-children`}
role="group"
aria-labelledby={`${id}-label`}
aria-hidden={isItemCollapsed}
inert={isItemCollapsed ? true : undefined}
{...stylex.props(
styles.childrenCollapsible,
isItemCollapsed && styles.childrenCollapsed,
)}>
<div {...stylex.props(styles.childrenInner)}>
<span id={`${id}-label`} hidden>
{label}
</span>
<SideNavItemDepthContext value={depth + 1}>
{children}
</SideNavItemDepthContext>
</div>
</div>
)}
</div>
);
return item;
}
SideNavItem.displayName = 'SideNavItem';