Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
36.5 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file SideNav.tsx
 * @input Uses React, HTMLAttributes, ReactNode, StyleX
 * @output Exports SideNav component and SideNavProps
 * @position Core implementation; consumed by index.ts, tested by SideNav.test.tsx
 *
 * Sidebar navigation container with five zones: header + topContent (sticky together),
 * children (scrollable), footer, and footerIcons (sticky bottom).
 *
 * Supports optional resize via a drag handle at the inline-end edge. The
 * resizable wrapper clips handle overflow while keeping its focus ring inside.
 *
 * 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,
  useImperativeHandle,
  useLayoutEffect,
  useMemo,
  useRef,
  type ReactNode,
} from 'react';
import type {BaseProps} from '../BaseProps';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {focusVars, spacingVars} from '../theme/tokens.stylex';
import {mergeProps} from '../utils';
import {
  SideNavCollapseContext,
  type SideNavCollapseState,
  type SideNavCollapsibleConfig,
  type SideNavImperativeCollapseHandle,
} from './SideNavCollapseContext';
import {SideNavCollapseButton} from './SideNavCollapseButton';
import {useSideNavRenderMode} from './SideNavRenderContext';
import {MobileNav} from '../MobileNav/MobileNav';
import {
  isResizableRegion,
  useResizable,
  type ResizableConfig,
  type ResizableRegion,
} from '../Resizable/useResizable';
import {ResizeHandle} from '../Resizable/ResizeHandle';
import {themeProps} from '../utils/themeProps';
import {SizeProvider} from '../SizeContext/SizeContext';
import {useDevWarning} from '../hooks/useDevWarning';

import {useMergedRefs} from '../hooks/useMergedRefs';
import {LayoutChangeSnapshot} from '../motion/LayoutChangeSnapshot';
import {getFocusableElements} from '../hooks/useFocusTrap';
import {useFocusLeavingChange} from '../utils/useFocusLeavingChange';
import {readAccessibleName} from '../utils/accessibleName';
import {
  moveFocusLeftBehind,
  noteFocusWithin,
  type FocusWithin,
} from '../utils/focusReturn';
import {useInteractionModalityTracking} from '../utils/interactionModality';
import {
  SideNavFocusTargetsContext,
  type SideNavFocusTargets,
} from './SideNavFocusTargetsContext';
import {
  createRailLayout,
  playRail,
  snapshotRail,
  SideNavShellContext,
  type RailMotion,
  type RailSnapshot,
} from './railMotion';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/SideNav/SideNav.generated';
import {isRenderable} from '../utils/isRenderable';

registerEnglishFallback(english);
// =============================================================================
// Constants
// =============================================================================

/** Width below which dragging collapses the sidebar (when collapsible). */
const COLLAPSE_THRESHOLD = 160;

// =============================================================================
// Collapse config
// =============================================================================

interface ResolvedCollapseConfig {
  isCollapsible: boolean;
  defaultIsCollapsed: boolean;
  isCollapsed: boolean | undefined;
  onCollapsedChange: ((isCollapsed: boolean) => void) | undefined;
  /** Dev-warning text when both props address the same state, else null. */
  conflict: string | null;
}

/**
 * `collapsible` and `resizable` can each carry collapse state, so they are
 * normalized here into one config with one owner — two independently
 * initialized copies of the same boolean is what rendered an expanded nav at
 * width 0 in #4790. `resizable` is the superset, so its keys win.
 */
function resolveCollapseConfig(
  collapsible: boolean | SideNavCollapsibleConfig,
  resizable: boolean | ResizableConfig,
): ResolvedCollapseConfig {
  const fromCollapsible = typeof collapsible === 'object' ? collapsible : {};
  const fromResizable = typeof resizable === 'object' ? resizable : {};

  const resizableCarriesCollapse =
    fromResizable.defaultIsCollapsed !== undefined ||
    fromResizable.isCollapsed !== undefined ||
    fromResizable.onCollapseChange !== undefined;

  return {
    isCollapsible: !!collapsible || resizableCarriesCollapse,
    defaultIsCollapsed:
      (resizableCarriesCollapse
        ? fromResizable.defaultIsCollapsed
        : fromCollapsible.defaultIsCollapsed) ?? false,
    isCollapsed: resizableCarriesCollapse
      ? fromResizable.isCollapsed
      : fromCollapsible.isCollapsed,
    onCollapsedChange: resizableCarriesCollapse
      ? fromResizable.onCollapseChange
      : fromCollapsible.onCollapsedChange,
    conflict: describeCollapseConflict(fromCollapsible, fromResizable),
  };
}

/**
 * Names the keys that address the same collapse state on both props, and
 * which one won. Silent for the common non-overlapping combinations —
 * `collapsible: true` alongside a resize config is not a conflict.
 */
function describeCollapseConflict(
  collapsible: SideNavCollapsibleConfig,
  resizable: ResizableConfig,
): string | null {
  const collapsibleKeys = [
    collapsible.defaultIsCollapsed !== undefined && 'defaultIsCollapsed',
    collapsible.isCollapsed !== undefined && 'isCollapsed',
    collapsible.onCollapsedChange !== undefined && 'onCollapsedChange',
  ].filter((key): key is string => key !== false);
  const resizableKeys = [
    resizable.defaultIsCollapsed !== undefined && 'defaultIsCollapsed',
    resizable.isCollapsed !== undefined && 'isCollapsed',
    resizable.onCollapseChange !== undefined && 'onCollapseChange',
  ].filter((key): key is string => key !== false);

  if (collapsibleKeys.length === 0 || resizableKeys.length === 0) {
    return null;
  }

  return (
    `${collapsibleKeys.map(key => `collapsible.${key}`).join(', ')} and ` +
    `${resizableKeys.map(key => `resizable.${key}`).join(', ')} address the ` +
    `same collapse state. resizable wins; the collapsible ` +
    `${collapsibleKeys.length === 1 ? 'value is' : 'values are'} ignored.`
  );
}

/**
 * The collapse config when `resizable` is useResizable's output. The region
 * owns the collapse state and decides whether the rail collapses. A
 * `collapsible` prop that sets state or disagrees is ignored and named in a
 * development warning.
 */
function resolveRegionCollapseConfig(
  collapsible: boolean | SideNavCollapsibleConfig | undefined,
  region: ResizableRegion,
): ResolvedCollapseConfig {
  const fromCollapsible = typeof collapsible === 'object' ? collapsible : {};
  const ignoredKeys = [
    fromCollapsible.defaultIsCollapsed !== undefined && 'defaultIsCollapsed',
    fromCollapsible.isCollapsed !== undefined && 'isCollapsed',
    fromCollapsible.onCollapsedChange !== undefined && 'onCollapsedChange',
  ].filter((key): key is string => key !== false);
  // The region's own `collapsible` option decides whether the rail collapses.
  const isRegionCollapsible = region.props._collapsible ?? false;
  const conflicts: string[] = [];
  if (ignoredKeys.length > 0) {
    conflicts.push(
      `\`collapsible\` sets ${ignoredKeys.map(key => `\`${key}\``).join(', ')}, ` +
        'which the rail ignores: it follows the region.',
    );
  }
  if (
    collapsible !== undefined &&
    Boolean(collapsible) !== isRegionCollapsible
  ) {
    conflicts.push(
      isRegionCollapsible
        ? '`collapsible` is false, but the region is collapsible, so the rail still collapses.'
        : '`collapsible` turns collapse on, but the region is not collapsible, so the rail never collapses.',
    );
  }
  return {
    isCollapsible: isRegionCollapsible,
    defaultIsCollapsed: region.isCollapsed,
    isCollapsed: undefined,
    onCollapsedChange: undefined,
    conflict:
      conflicts.length === 0
        ? null
        : "`resizable` is useResizable's output, which owns the collapse " +
          `state and decides whether the rail collapses. ${conflicts.join(' ')}`,
  };
}

// =============================================================================
// Styles
// =============================================================================

const styles = stylex.create({
  root: {
    display: 'flex',
    flexDirection: 'column',
    height: '100%',
    width: 260,
    backgroundColor: 'inherit',
    boxSizing: 'border-box',
    overflow: 'hidden',
  },
  rootCollapsed: {
    width: spacingVars['--spacing-12'],
  },
  stickyTop: {
    display: 'flex',
    flexDirection: 'column',
    flexShrink: 0,
    position: 'sticky',
    top: 0,
    zIndex: 1,
    backgroundColor: 'inherit',
    paddingBlockStart: spacingVars['--spacing-2'],
    paddingBlockEnd: spacingVars['--spacing-2'],
    paddingInline: spacingVars['--spacing-2'],
    gap: spacingVars['--spacing-2'],
  },
  stickyTopCollapsed: {
    alignItems: 'center',
  },
  topContent: {},
  scrollable: {
    flex: 1,
    overflowY: 'auto',
    overflowX: 'hidden',
    paddingInline: spacingVars['--spacing-2'],
  },
  scrollableCollapsed: {
    display: 'flex',
    flexDirection: 'column' as const,
    alignItems: 'center',
  },
  scrollableNoTop: {
    paddingBlockStart: spacingVars['--spacing-2'],
  },
  scrollableWithTop: {
    paddingBlockStart: spacingVars['--spacing-1'],
  },
  scrollableNoBottom: {
    paddingBlockEnd: spacingVars['--spacing-2'],
  },
  scrollableWithBottom: {
    paddingBlockEnd: spacingVars['--spacing-1'],
  },
  stickyBottom: {
    display: 'flex',
    flexDirection: 'column',
    flexShrink: 0,
    marginTop: 'auto',
    position: 'sticky',
    bottom: 0,
    backgroundColor: 'inherit',
    gap: spacingVars['--spacing-2'],
    paddingInline: spacingVars['--spacing-2'],
    paddingBlockStart: spacingVars['--spacing-1'],
    paddingBlockEnd: spacingVars['--spacing-2'],
  },
  footerRow: {
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-1'],
  },
  footerRowCollapsed: {
    flexDirection: 'column-reverse',
  },
  footerIcons: {
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-1'],
  },
  footerIconsCollapsed: {
    flexDirection: 'column',
    alignItems: 'center',
  },
  stickyBottomCollapsed: {
    paddingBlockStart: 0,
    alignItems: 'center',
  },
  // Drawer footer — pushed to bottom of the scrollable content area
  drawerFooter: {
    display: 'flex',
    flexDirection: 'column',
    marginBlockStart: 'auto',
    gap: spacingVars['--spacing-2'],
    paddingBlockStart: spacingVars['--spacing-2'],
  },
  drawerFooterIcons: {
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-1'],
  },
  // Resizable container — wraps the nav and the drag handle
  resizableContainer: {
    position: 'relative',
    display: 'flex',
    flexShrink: 0,
    height: '100%',
    overflow: 'clip',
  },
  resizableHandle: {
    // Keep the shared ring inside the clipping boundary. The wrapper cannot
    // use overflow-clip-margin: that paint allowance also contributes the
    // overlay's half-pixel spill to AppShell's scrollable overflow.
    outlineOffset: {
      default: '0',
      ':focus-visible': `calc(0px - ${focusVars['--focus-outline-width']})`,
    },
  },
  // Topbar mode — horizontal layout for mobile top bar
  topbar: {
    display: 'flex',
    flexDirection: 'row',
    alignItems: 'center',
    justifyContent: 'space-between',
    height: 48,
    width: '100%',
    backgroundColor: 'inherit',
    boxSizing: 'border-box',
    overflow: 'hidden',
  },
  topbarIcons: {
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-1'],
    marginInlineStart: 'auto',
  },
});

/**
 * Cascaded to the icon rows through `SizeContext` so the built-in collapse
 * button and the consumer's `footerIcons` come out one height. An explicit
 * `size` on a child still wins.
 */
const FOOTER_ICON_SIZE = 'sm';

// =============================================================================
// Types
// =============================================================================

export interface SideNavProps extends BaseProps<HTMLElement> {
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLElement>;

  /**
   * Imperative collapse handle for SideNavCollapseButton instances rendered
   * outside this SideNav. This intentionally stays separate from `ref`, which
   * continues to expose the root HTMLElement.
   *
   * @deprecated Hand the same controlled `collapsible` config to SideNav and
   * to the outside button instead.
   */
  handleRef?: React.Ref<SideNavImperativeCollapseHandle>;

  /**
   * Header area — typically SideNavHeading. Sticky at top.
   */
  header?: ReactNode;
  /**
   * Content pinned below header (e.g., create button, top-level items). Sticky.
   */
  topContent?: ReactNode;
  /**
   * Navigation sections and items. Scrollable.
   */
  children: ReactNode;
  /**
   * Footer area above icon bar (e.g., promo cards).
   */
  footer?: ReactNode;
  /**
   * Footer icon bar (e.g., help, notifications, avatar).
   */
  footerIcons?: ReactNode;
  /**
   * StyleX styles created via `stylex.create()`. Merged with the component's
   * base styles inside a single `stylex.props()` call for optimal deduplication.
   *
   * @example
   * ```
   * const overrides = stylex.create({ root: { marginBottom: 8 } });
   * <Component xstyle={overrides.root} />
   * ```
   */
  xstyle?: StyleXStyles;
  /**
   * CSS class name(s) appended to the root element.
   * If you're using StyleX, prefer `xstyle` for optimal style deduplication.
   */
  className?: string;
  /**
   * Inline styles to apply to the root element. Spread after StyleX
   * inline styles, so these values take priority.
   */
  style?: React.CSSProperties;
  /**
   * Test ID for the root element.
   */
  'data-testid'?: string;

  /**
   * Enables a resize handle at the inline-end edge for resizing the sidebar.
   * Uses `useResizable` internally and renders `ResizeHandle` in
   * overlay mode. When collapsed, the handle is hidden.
   *
   * - `true` — resizable with defaults (260px initial, 180–480px range)
   * - Object — configured via `ResizableConfig`:
   *   - `defaultWidth` — initial width in pixels (default: 260)
   *   - `minWidth` — minimum width in pixels (default: 180)
   *   - `maxWidth` — maximum width in pixels (default: 480)
   *   - `autoSaveId` — localStorage key for persisting width and collapse state
   *   - `onWidthChange` — called when the width changes
   *   - `defaultIsCollapsed` / `isCollapsed` / `onCollapseChange` — collapse
   *     state, when `resizable` should own it rather than `collapsible`
   *
   * - `useResizable()`'s output — the caller's region owns the width and the
   *   collapse state. The rail follows its `isCollapsed`, the toggle calls
   *   its `collapse` and `expand`, and its `autoSaveId` saves the width.
   *   The region's own `collapsible` option also decides whether the rail
   *   collapses
   *
   * When both props carry collapse state, `resizable` wins and a dev warning
   * names the conflicting keys.
   *
   * @default false
   */
  resizable?: boolean | ResizableConfig | ResizableRegion;

  /**
   * Enables collapse behavior. The sidebar can be collapsed to a narrow
   * icon-only toolbar.
   *
   * - `true` — enables collapse with default toggle button and uncontrolled state
   * - Object — enables collapse with advanced configuration:
   *   - `defaultIsCollapsed` — start collapsed (uncontrolled)
   *   - `isCollapsed` + `onCollapsedChange` — controlled mode. Pass the same
   *     object to a `SideNavCollapseButton` rendered outside this SideNav
   *   - `hasButton` — render built-in collapse button (default: true)
   *   - `buttonLabel` — accessibility label for the collapse button
   *
   * @default false
   */
  collapsible?: boolean | SideNavCollapsibleConfig;
}

// =============================================================================
// Component
// =============================================================================

/** Where focus was before a collapse, as the move after it needs it. */
interface PendingRailFocus {
  focus: FocusWithin;
  /** Whether the rail keeps the row that held focus. */
  isRowKept: boolean;
  /** Kept rows before the row that held focus. */
  keptBefore: number;
  /** The name of the control outside the rows that held focus. */
  outside: {name: string} | null;
  /** Whether focus was on the collapse toggle. */
  wasOnToggle: boolean;
}

/** The timeline holds one time per frame, so two reads in one frame match. */
function frameTimeOf(doc: Document | undefined): number | null {
  const time = doc?.timeline?.currentTime;
  return time == null ? null : Number(time);
}

/**
 * Sidebar navigation container for application pages.
 *
 * Five vertical zones: sticky header + action area at top,
 * scrollable nav content in the middle, and sticky footer + icon bar at bottom.
 *
 * @example
 * ```
 * <SideNav
 *   header={<SideNavHeading heading="My App" headingHref="/" />}
 *   topContent={<Button label="Create new" variant="primary" />}>
 *   <SideNavSection heading="Main">
 *     <SideNavItem label="Dashboard" isSelected href="/dashboard" />
 *     <SideNavItem label="Projects" href="/projects" />
 *   </SideNavSection>
 * </SideNav>
 * ```
 */

export function SideNav({
  header,
  topContent,
  children,
  footer,
  footerIcons,
  collapsible: collapsibleProp,
  resizable = false,
  xstyle,
  className,
  style,
  'data-testid': testId,
  ref,
  handleRef,
  ...props
}: SideNavProps) {
  const t = useComponentTranslator();
  // Only a left-out `collapsible` becomes false, as before; `??` would also
  // turn null into false.
  const collapsible = collapsibleProp === undefined ? false : collapsibleProp;
  // Parse collapsible prop
  const collapsibleConfig = typeof collapsible === 'object' ? collapsible : {};
  const hasCollapseButton = collapsibleConfig.hasButton ?? true;

  // useResizable's output: the caller's region owns the width and collapse.
  const ownerRegion = isResizableRegion(resizable) ? resizable : null;
  // Resizable config
  const resizableConfig: ResizableConfig =
    typeof resizable === 'object' && !isResizableRegion(resizable)
      ? resizable
      : {};
  const isResizable = !!resizable;

  const collapseConfig =
    ownerRegion == null
      ? resolveCollapseConfig(
          collapsible,
          isResizableRegion(resizable) ? false : resizable,
        )
      : resolveRegionCollapseConfig(collapsibleProp, ownerRegion);
  const {isCollapsible, onCollapsedChange} = collapseConfig;

  useDevWarning(
    'SideNav',
    collapseConfig.conflict ?? '',
    collapseConfig.conflict != null,
  );

  const navRef = useRef<HTMLElement>(null);
  // The resize handle names the pane it resizes (APG window splitter), so the
  // nav needs an id; a consumer's own id wins.
  const generatedNavId = useId();
  const navId = props.id ?? generatedNavId;
  // The nav's own document's last input decides the moved focus's ring
  // (AR3), so a SideNav in a second document tracks input there.
  const {ref: modalityRef} = useInteractionModalityTracking();
  // The initial state never animates. A change before the rail's first paint
  // lands at once, unless the rail's own toggle made it. Until a frame runs
  // after the nav attaches, the document timeline reads the frame it read
  // then.
  const mountFrameRef = useRef<number | null>(null);
  const mountedNavRef = useRef<HTMLElement | null>(null);
  const isOwnToggleRef = useRef(false);
  const recordMountFrame = useCallback((nav: HTMLElement | null) => {
    // An inline ref re-attaches the same nav on each render. Only a new nav
    // starts a new initial state.
    if (nav != null && nav !== mountedNavRef.current) {
      mountedNavRef.current = nav;
      mountFrameRef.current = frameTimeOf(nav.ownerDocument);
    }
  }, []);
  const mergedNavRef = useMergedRefs(
    ref,
    navRef,
    modalityRef,
    recordMountFrame,
  );
  const collapseStateRef = useRef<SideNavCollapseState>({
    isCollapsed: false,
    toggle: () => {},
    isCollapsible,
  });

  // useResizable is the sole collapse owner in every SideNav mode. Keeping that
  // owner mounted when resize is toggled preserves the current collapse state.
  // Given the hook's output, the caller's region is the owner, and this one
  // stays idle.
  const resizableHook = useResizable({
    defaultSize: resizableConfig.defaultWidth ?? 260,
    minSize: resizableConfig.minWidth ?? 180,
    maxSize: resizableConfig.maxWidth ?? 480,
    collapsible: isCollapsible,
    collapsedSize: COLLAPSE_THRESHOLD,
    autoSaveId: resizableConfig.autoSaveId,
    defaultIsCollapsed: collapseConfig.defaultIsCollapsed,
    isCollapsed: collapseConfig.isCollapsed,
    onSizeChange: resizableConfig.onWidthChange,
    onCollapseChange: onCollapsedChange,
  });

  const region = ownerRegion ?? resizableHook;
  const collapsed = region.isCollapsed;

  // A collapse or expand plays the rail's motion, except an app's change
  // before the rail's first paint. It is measured in the commit before the
  // DOM changes and played after it, before paint. Inside AppShell the
  // content area moves with it through AppShell's own handle; outside,
  // SideNav holds its own over its parent.
  const shell = use(SideNavShellContext);
  // A resizable rail's wrapper holds the nav and the handle; outside AppShell
  // it is the rail the motion moves and lays its copy beside (FR6).
  const resizeWrapperRef = useRef<HTMLDivElement>(null);
  const ownRail = useCallback(
    () => resizeWrapperRef.current ?? navRef.current,
    [],
  );
  const ownLayout = useMemo(() => createRailLayout(ownRail), [ownRail]);
  const railSnapshotRef = useRef<RailSnapshot | null>(null);
  const motionRef = useRef<{rail: RailMotion; endContent: () => void} | null>(
    null,
  );
  const measureRail = useCallback(
    (wasCollapsed: boolean) => {
      // A change during a running motion starts from what the rail shows.
      const running = motionRef.current;
      const shown = running?.rail.shown() ?? null;
      running?.rail.end();
      running?.endContent();
      motionRef.current = null;
      const isOwnToggle = isOwnToggleRef.current;
      isOwnToggleRef.current = false;
      const frame = frameTimeOf(navRef.current?.ownerDocument);
      if (!isOwnToggle && (frame == null || frame === mountFrameRef.current)) {
        railSnapshotRef.current = null;
        shell?.landContent();
        return;
      }
      railSnapshotRef.current = snapshotRail(
        shell?.rail() ?? ownRail(),
        shell?.animatedLayout ?? ownLayout,
        shown,
        wasCollapsed,
      );
      // A collapse covers the old rail with its copy; when the rail cannot
      // be copied, the page lands at once with it, on one clock, a running
      // glide included.
      const snapshot = railSnapshotRef.current;
      if (snapshot != null && snapshot.swap == null && !wasCollapsed) {
        shell?.landContent();
        return;
      }
      shell?.beforeRailChange();
    },
    [shell, ownLayout, ownRail],
  );
  useLayoutEffect(() => {
    const snapshot = railSnapshotRef.current;
    railSnapshotRef.current = null;
    if (snapshot == null) {
      return;
    }
    // The content moves first: its glide starts before the rail rides it.
    const endContent = shell?.afterRailChange() ?? (() => {});
    motionRef.current = {
      rail: playRail(
        snapshot,
        shell?.rail() ?? ownRail(),
        shell?.animatedLayout ?? ownLayout,
        shell?.column() ?? null,
      ),
      endContent,
    };
  }, [collapsed, shell, ownLayout, ownRail]);
  // An unmount mid-motion removes the copy at once.
  useLayoutEffect(
    () => () => {
      motionRef.current?.rail.end();
      motionRef.current?.endContent();
    },
    [],
  );

  // Focus on something the collapsed rail does not render would fall to the
  // page when the rail collapses (`component:SideNav` AR3). On a row the rail
  // keeps (its link replaced, its expand toggle or row actions gone), focus
  // stays on that row's control; from a row the rail drops (no icon, or
  // nested), it moves to the rail's collapse toggle, or, with none, to the
  // nearest row the rail keeps. Rows and the toggle register through their
  // callback refs. Rows are matched across the commit by their place among
  // the rows the rail keeps, not by element, since a row's control can be
  // replaced by its collapsed form. Focus on a header or footer control that
  // the collapse replaces goes to the new control with the same accessible
  // name. From one the collapse removes or replaces under another name, or
  // the resize handle, focus goes to the toggle, or, with none, to the first
  // kept row.
  // Focus moves only if the collapse lost it.
  const rowsRef = useRef(new Map<HTMLElement, boolean>());
  const togglesRef = useRef(new Set<HTMLElement>());
  const focusTargets = useMemo<SideNavFocusTargets>(
    () => ({
      registerRow: (element, isKeptInRail) => {
        rowsRef.current.set(element, isKeptInRail);
        return () => {
          rowsRef.current.delete(element);
        };
      },
      registerToggle: element => {
        togglesRef.current.add(element);
        return () => {
          togglesRef.current.delete(element);
        };
      },
    }),
    [],
  );
  const noteRailFocus = useFocusLeavingChange(
    collapsed,
    (wasCollapsed: boolean): PendingRailFocus | null => {
      const nav = navRef.current;
      // The resize handle sits beside the nav, in the resize wrapper, and goes
      // with a collapse its Enter starts.
      const focus = wasCollapsed
        ? null
        : (noteFocusWithin(nav) ?? noteFocusWithin(resizeWrapperRef.current));
      if (focus == null || nav == null) {
        return null;
      }
      const rows = railRows(nav, rowsRef.current);
      // The innermost row holding focus, the last in document order: a nested
      // row's parent holds it too.
      let index = -1;
      rows.forEach((row, at) => {
        if (row.contains(focus.element)) {
          index = at;
        }
      });
      let outside = null;
      if (index < 0) {
        const controls = controlsOutsideRows(nav, rows);
        const at = controls.findIndex(control =>
          control.contains(focus.element),
        );
        outside = at < 0 ? null : {name: controlName(controls[at])};
      }
      return {
        focus,
        outside,
        wasOnToggle: [...togglesRef.current].some(toggle =>
          toggle.contains(focus.element),
        ),
        isRowKept: index >= 0 && rowsRef.current.get(rows[index]) === true,
        keptBefore: rows
          .slice(0, Math.max(index, 0))
          .filter(row => rowsRef.current.get(row) === true).length,
      };
    },
    (pending: PendingRailFocus, isCollapsed: boolean) => {
      const nav = navRef.current;
      if (!isCollapsed || nav == null) {
        return;
      }
      // Collapsed, every row the nav renders is one the rail keeps, in order.
      const kept = railRows(nav, rowsRef.current);
      const controlOf = (row: HTMLElement | undefined) =>
        row == null ? undefined : getFocusableElements(row)[0];
      const toggle = [...togglesRef.current].find(element =>
        nav.contains(element),
      );
      let sameOutside: HTMLElement | undefined;
      if (pending.wasOnToggle) {
        sameOutside = toggle;
      } else if (pending.outside != null) {
        const controls = controlsOutsideRows(nav, kept);
        sameOutside = controls.find(
          control => controlName(control) === pending.outside?.name,
        );
      }
      const target = pending.isRowKept
        ? controlOf(kept[pending.keptBefore])
        : (sameOutside ??
          toggle ??
          controlOf(kept[pending.keptBefore - 1]) ??
          controlOf(kept[pending.keptBefore]));
      moveFocusLeftBehind(pending.focus, target);
    },
  );
  const beforeRailChange = useCallback(
    (wasCollapsed: boolean) => {
      noteRailFocus(wasCollapsed);
      measureRail(wasCollapsed);
    },
    [noteRailFocus, measureRail],
  );

  const toggle = useCallback(() => {
    const next = !collapsed;
    isOwnToggleRef.current = true;

    // Deprecated `handleRef` path only: an out-of-tree button reads this
    // snapshot while rendering, which can happen before SideNav re-renders.
    collapseStateRef.current = {
      ...collapseStateRef.current,
      isCollapsed: next,
    };

    if (next) {
      region.collapse();
    } else {
      region.expand();
    }
  }, [collapsed, region]);

  const showResizeHandle = isResizable && !collapsed;

  collapseStateRef.current = {
    isCollapsed: collapsed,
    toggle,
    isCollapsible,
  };

  const collapseContext = {
    isCollapsed: collapsed,
    toggle,
    isCollapsible,
  };

  useImperativeHandle(
    handleRef,
    () => ({
      getCollapseState: () => collapseStateRef.current,
    }),
    [],
  );

  // Render mode — when inside AppShell mobile layout, render subsets
  const renderMode = useSideNavRenderMode();

  // =========================================================================
  // Topbar mode — heading + footerIcons in a horizontal bar
  // =========================================================================
  if (renderMode === 'topbar') {
    return (
      <div
        data-testid={testId}
        {...mergeProps(
          themeProps('side-nav', {mode: 'topbar'}),
          stylex.props(styles.topbar, xstyle),
          className,
          style,
        )}>
        {header}
        <div {...stylex.props(styles.topbarIcons)}>
          <SizeProvider value={FOOTER_ICON_SIZE}>{footerIcons}</SizeProvider>
        </div>
      </div>
    );
  }

  // =========================================================================
  // Drawer mode — render inside MobileNav with heading as header
  // =========================================================================
  // Slot presence follows `isRenderable` (`architecture:react-component-runtime`
  // INV16), so the footer area shows whenever a slot inside it renders.
  const hasDrawerFooter = isRenderable(footer) || isRenderable(footerIcons);

  if (renderMode === 'drawer') {
    return (
      <MobileNav
        header={header}
        data-testid={testId}
        xstyle={xstyle}
        className={className}
        style={style}
        {...props}>
        {topContent}
        {children}
        {hasDrawerFooter && (
          <div {...stylex.props(styles.drawerFooter)}>
            {footer}
            {isRenderable(footerIcons) && (
              <div {...stylex.props(styles.drawerFooterIcons)}>
                <SizeProvider value={FOOTER_ICON_SIZE}>
                  {footerIcons}
                </SizeProvider>
              </div>
            )}
          </div>
        )}
      </MobileNav>
    );
  }

  // =========================================================================
  // Drawer-content mode — render just items (no MobileNav wrapper)
  // Used when TopNav owns the drawer and SideNav items are nested inside
  // =========================================================================
  if (renderMode === 'drawer-content') {
    return (
      <>
        {topContent}
        {children}
        {hasDrawerFooter && (
          <div {...stylex.props(styles.drawerFooter)}>
            {footer}
            {isRenderable(footerIcons) && (
              <div {...stylex.props(styles.drawerFooterIcons)}>
                <SizeProvider value={FOOTER_ICON_SIZE}>
                  {footerIcons}
                </SizeProvider>
              </div>
            )}
          </div>
        )}
      </>
    );
  }

  // =========================================================================
  // Default mode — full sidebar
  // =========================================================================
  const hasStickyTop = isRenderable(header) || isRenderable(topContent);
  const hasStickyBottom = isRenderable(footer) || isRenderable(footerIcons);
  // The built-in collapse button only renders when collapse is enabled and it
  // hasn't been opted out via `collapsible.hasButton: false` (e.g. when the
  // consumer places a SideNavCollapseButton in the header instead).
  const showCollapseButton = isCollapsible && hasCollapseButton;

  // When resizable, override the nav width via inline style
  const resizableNavStyle: React.CSSProperties | undefined = isResizable
    ? {...(style ?? {}), width: collapsed ? undefined : region.size}
    : style;

  const navElement = (
    <nav
      ref={mergedNavRef}
      role="navigation"
      aria-label={t('@astryx.sideNav.label')}
      data-testid={testId}
      {...mergeProps(
        themeProps('side-nav'),
        stylex.props(styles.root, collapsed && styles.rootCollapsed, xstyle),
        className,
        resizableNavStyle,
      )}
      {...props}
      // After the spread: a wrapper forwarding `id={undefined}` must not erase
      // the id the resize handle's aria-controls points at.
      id={navId}>
      {hasStickyTop && (
        <div
          {...stylex.props(
            styles.stickyTop,
            collapsed && styles.stickyTopCollapsed,
          )}>
          {header}
          {isRenderable(topContent) && (
            <div {...stylex.props(styles.topContent)}>{topContent}</div>
          )}
        </div>
      )}
      <div
        {...stylex.props(
          styles.scrollable,
          collapsed && styles.scrollableCollapsed,
          hasStickyTop ? styles.scrollableWithTop : styles.scrollableNoTop,
          hasStickyBottom
            ? styles.scrollableWithBottom
            : styles.scrollableNoBottom,
        )}>
        {children}
      </div>
      {(hasStickyBottom || showCollapseButton) && (
        <div
          {...stylex.props(
            styles.stickyBottom,
            collapsed && styles.stickyBottomCollapsed,
          )}>
          {footer}
          {(showCollapseButton || isRenderable(footerIcons)) && (
            <div
              {...stylex.props(
                styles.footerRow,
                collapsed && styles.footerRowCollapsed,
              )}>
              <SizeProvider value={FOOTER_ICON_SIZE}>
                {showCollapseButton && <SideNavCollapseButton />}
                {footerIcons}
              </SizeProvider>
            </div>
          )}
        </div>
      )}
    </nav>
  );

  // Overlay drag handle inside the nav when resizable.
  // Uses ResizeHandle in overlay mode so the handle sits inside
  // the panel's overflow: clip bounds.
  // A resizable rail keeps its wrapper while collapsed, so collapsing or
  // expanding never changes the nav's parent: the nav and its items stay
  // mounted, and their state (an open nested group) and focus persist (FR6).
  // Only the handle comes and goes.
  const rail = isResizable ? (
    <div ref={resizeWrapperRef} {...stylex.props(styles.resizableContainer)}>
      {navElement}
      {showResizeHandle && (
        <ResizeHandle
          data-testid="astryx-sidenav-resize-handle"
          direction="horizontal"
          position="overlay"
          pillPlacement="end"
          isAlwaysVisible={false}
          xstyle={styles.resizableHandle}
          resizable={ownerRegion ?? resizableHook.props}
          label={t('@astryx.sideNav.resizeSidebar')}
          aria-controls={navId}
        />
      )}
    </div>
  ) : (
    navElement
  );
  // The snapshot stays mounted outside the resize wrapper.
  const content = (
    <>
      <LayoutChangeSnapshot
        value={collapsed}
        onBeforeChange={beforeRailChange}
      />
      {rail}
    </>
  );

  if (isCollapsible) {
    return (
      <SideNavFocusTargetsContext value={focusTargets}>
        <SideNavCollapseContext value={collapseContext}>
          {content}
        </SideNavCollapseContext>
      </SideNavFocusTargetsContext>
    );
  }

  return content;
}

/** The focusable controls in `nav` outside every row: header and footer. */
function controlsOutsideRows(
  nav: HTMLElement,
  rows: HTMLElement[],
): HTMLElement[] {
  return getFocusableElements(nav).filter(
    control => !rows.some(row => row.contains(control)),
  );
}

/** A control's accessible name, so a re-rendered control is found again. */
function controlName(control: HTMLElement): string {
  return readAccessibleName(control) ?? '';
}

/**
 * The registered rows inside `nav`, in document order, leaving out rows in a
 * collapsed item's flyout, which is a layer of its own.
 */
function railRows(
  nav: HTMLElement,
  rows: ReadonlyMap<HTMLElement, boolean>,
): HTMLElement[] {
  return [...rows.keys()]
    .filter(row => nav.contains(row) && row.closest('[popover]') == null)
    .sort((a, b) =>
      a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1,
    );
}

SideNav.displayName = 'SideNav';