@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/SelectableCard/SelectableCard.tsx

@@ -44,6 +44,7 @@ import {mergeProps} from '../utils';
 import {Card} from '../Card/Card';
 import type {CardVariant} from '../Card/Card';
 import {useClickableContainer} from '../hooks/useClickableContainer';
+import {closestLayerRoot} from '../privateAttributes/layerRoot.stylex';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
@@ -323,6 +324,44 @@ export interface SelectableCardProps extends Omit<BaseProps, 'onChange'> {
 // Component
 // =============================================================================
 
+/**
+ * Call a caller's click handler during capture, before the layer's own
+ * handlers, without letting it change what those handlers see. Its
+ * stopPropagation() would keep the press from the control inside the layer,
+ * so it does nothing here. Its preventDefault() would mark the event handled
+ * for those controls (a Button skips its clickAction), so it is applied to
+ * the native event only after the press has bubbled to the document, where it
+ * still cancels the browser's default action.
+ */
+function callBeforeLayerHandlers(
+  handler: (event: MouseEvent<HTMLElement>) => void,
+  event: MouseEvent<HTMLElement>,
+): void {
+  const {stopPropagation, preventDefault} = event;
+  let isDefaultPreventedByCaller = false;
+  event.stopPropagation = () => {};
+  event.preventDefault = () => {
+    isDefaultPreventedByCaller = true;
+  };
+  try {
+    handler(event);
+  } finally {
+    event.stopPropagation = stopPropagation;
+    event.preventDefault = preventDefault;
+  }
+  if (isDefaultPreventedByCaller) {
+    const nativeEvent = event.nativeEvent;
+    const doc = event.currentTarget.ownerDocument;
+    const cancelDefault = (bubbled: Event) => {
+      doc.removeEventListener(nativeEvent.type, cancelDefault);
+      if (bubbled === nativeEvent) {
+        nativeEvent.preventDefault();
+      }
+    };
+    doc.addEventListener(nativeEvent.type, cancelDefault);
+  }
+}
+
 /**
  * A card that toggles between selected and unselected states.
  *
@@ -415,6 +454,24 @@ export function SelectableCard({
       }
     : onClick;
 
+  // Until the next minor, a click inside an open layer within the card still
+  // reaches the caller's onClick. The layer root stops that click before the
+  // bubble phase, so it is delivered here, during capture. It never toggles.
+  // Remove at the next minor, when that click stops reaching onClick.
+  const handleLayerClickCapture = onClickProp
+    ? (e: MouseEvent<HTMLElement>) => {
+        const target = e.target;
+        if (!(target instanceof Element)) {
+          return;
+        }
+        const layerRoot = closestLayerRoot(target);
+        if (layerRoot == null || layerRoot.contains(e.currentTarget)) {
+          return;
+        }
+        callBeforeLayerHandlers(onClickProp, e);
+      }
+    : undefined;
+
   const composedOnMouseUp = onMouseUpProp
     ? (e: MouseEvent<HTMLElement>) => {
         onMouseUp(e);
@@ -455,7 +512,15 @@ export function SelectableCard({
       }
       onClick={!isDisabled ? composedOnClick : undefined}
       onMouseUp={!isDisabled ? composedOnMouseUp : undefined}
-      {...props}>
+      {...props}
+      onClickCapture={
+        !isDisabled && handleLayerClickCapture
+          ? (e: MouseEvent<HTMLDivElement>) => {
+              handleLayerClickCapture(e);
+              props.onClickCapture?.(e);
+            }
+          : props.onClickCapture
+      }>
       <input
         ref={interactiveRef}
         type="checkbox"

package/src/Selector/Selector.tsx

@@ -10,7 +10,7 @@
  * @position Core implementation; consumed by index.ts
  *
  * SYNC: When modified, update:
- * - /packages/core/src/Selector/Selector.spec.md
+ * - /docs/specs/components/Selector/Selector.spec.md
  * - /packages/core/src/Selector/Selector.doc.mjs
  * - /packages/core/src/Selector/Selector.test.tsx
  * - /packages/core/src/Selector/index.ts
@@ -32,6 +32,7 @@ import React, {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
+import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
 import {useTooltip} from '../Tooltip';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {useIndicator} from '../Indicator';
@@ -42,7 +43,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputWrapperStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {Divider} from '../Divider';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
@@ -89,6 +89,7 @@ import {
 } from '../Field/fieldParts';
 import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
@@ -99,11 +100,18 @@ import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
 import {VisuallyHidden} from '../VisuallyHidden';
-import {useTranslator} from '../i18n';
 import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';
 import {SelectorBottomSheet} from './SelectorBottomSheet';
 import {useSelectorPresentation} from './useSelectorPresentation';
 import {selectorPresentationStyles} from './selectorPresentation.stylex';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/Selector/Selector.generated';
+
+registerEnglishFallback(english);
 
 const styles = stylex.create({
   // Trigger container — the enhanced click target wrapping the combobox button and clear button as siblings
@@ -295,21 +303,6 @@ const styles = stylex.create({
       '[data-astryx-press="on"]': 'scale(0.98)',
     },
   },
-  // A disabled input-variant trigger keeps its tab stop (`spec:AST-085` FR1),
-  // and the shared disabled wrapper style drops the field focus ring, so the
-  // trigger shows keyboard focus here instead (FR6). It keys on the trigger
-  // itself, a direct child, so a focused status button keeps its own outline.
-  triggerDisabledFocus: {
-    borderColor: {
-      default: colorVars['--color-border-emphasized'],
-      ':has(> [aria-disabled="true"]:focus-visible)':
-        colorVars['--color-accent'],
-    },
-    boxShadow: {
-      default: 'none',
-      ':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
-    },
-  },
   triggerGhostDisabled: {
     backgroundImage: 'none',
     transform: {
@@ -726,7 +719,7 @@ interface SelectorPropsBase<
    * - 'tooltip': message is exposed from the on-field status icon
    * @default 'attached' for input selectors; 'detached' for secondary/ghost selectors
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -946,7 +939,7 @@ function filterOptionsByQuery(
 export function Selector<T extends SelectorOptionType>(
   props: SelectorProps<T>,
 ) {
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const pressable = usePressFeedback();
   const {
     label,
@@ -1038,8 +1031,10 @@ export function Selector<T extends SelectorOptionType>(
   // shorter inner button makes every size's selected row land too low.
   const anchorRef = useRef<HTMLDivElement>(null);
   const triggerRef = useRef<HTMLElement>(null);
+  const triggerModality = useInteractionModalityTracking();
   const triggerButtonRef = useMergedRefs<HTMLButtonElement>(
     triggerRef as React.Ref<HTMLButtonElement>,
+    triggerModality.ref,
     ref,
   );
   const searchRef = useRef<HTMLInputElement>(null);
@@ -1181,6 +1176,7 @@ export function Selector<T extends SelectorOptionType>(
     onHide: handleLayerHide,
     onShow: handleLayerShow,
     triggerRef,
+    triggerModality,
     popoverOptions: {
       hasLightDismiss: true,
       hasCloseButton: false,
@@ -2004,7 +2000,7 @@ export function Selector<T extends SelectorOptionType>(
             variant === 'input' &&
               isDisabled &&
               !surface.isTriggerFocusRingSuppressed &&
-              styles.triggerDisabledFocus,
+              inputDisabledFocusStyles.ring,
             isEffectivelyReadOnly && styles.triggerReadOnly,
             variant !== 'input' && isDisabled && styles.triggerGhostDisabled,
             variant !== 'input' &&

package/src/Selector/useSelectorPresentation.ts

@@ -26,6 +26,7 @@ import {
   type AdaptivePresentation,
   type ResolvedAdaptivePresentation,
 } from '../hooks/useAdaptivePresentation';
+import type {InteractionModalityTracking} from '../utils/interactionModality';
 import {useFocusReturnVisibility} from '../hooks/useFocusReturnVisibility';
 
 interface UseSelectorPresentationOptions {
@@ -34,6 +35,11 @@ interface UseSelectorPresentationOptions {
   onShow: () => void;
   popoverOptions: Omit<UsePopoverOptions, 'onHide' | 'onShow'>;
   triggerRef: RefObject<HTMLElement | null>;
+  /**
+   * The component's one modality tracking, its `ref` attached to the trigger,
+   * so the returned trigger's ring follows the trigger's own document.
+   */
+  triggerModality: Pick<InteractionModalityTracking, 'readModality'>;
   /**
    * Return focus to the trigger on every close, even when a press already
    * moved focus to another element. A caller-rendered trigger needs this
@@ -62,6 +68,7 @@ export function useSelectorPresentation({
   onShow,
   popoverOptions,
   triggerRef,
+  triggerModality,
   isFocusReturnAlways = false,
 }: UseSelectorPresentationOptions): SelectorPresentationController {
   const resolvedPresentation = useAdaptivePresentation(presentation);
@@ -84,7 +91,7 @@ export function useSelectorPresentation({
     onFocusReturnTargetFocus,
     prepareFocusReturn,
     resetFocusReturn,
-  } = useFocusReturnVisibility();
+  } = useFocusReturnVisibility(triggerModality);
   onHideRef.current = onHide;
   onShowRef.current = onShow;
 

package/src/SideNav/SideNav.tsx

@@ -52,10 +52,22 @@ import {ResizeHandle} from '../Resizable/ResizeHandle';
 import {themeProps} from '../utils/themeProps';
 import {SizeProvider} from '../SizeContext/SizeContext';
 import {useDevWarning} from '../hooks/useDevWarning';
-import {useTranslator} from '../i18n';
 
 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,
@@ -64,6 +76,14 @@ import {
   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
 // =============================================================================
@@ -405,6 +425,19 @@ export interface SideNavProps extends BaseProps<HTMLElement> {
 // 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;
+}
+
 /**
  * Sidebar navigation container for application pages.
  *
@@ -439,7 +472,7 @@ export function SideNav({
   handleRef,
   ...props
 }: SideNavProps) {
-  const t = useTranslator();
+  const t = useComponentTranslator();
   // Parse collapsible prop
   const collapsibleConfig = typeof collapsible === 'object' ? collapsible : {};
   const hasCollapseButton = collapsibleConfig.hasButton ?? true;
@@ -462,7 +495,10 @@ export function SideNav({
   // nav needs an id; a consumer's own id wins.
   const generatedNavId = useId();
   const navId = props.id ?? generatedNavId;
-  const mergedNavRef = useMergedRefs(ref, navRef);
+  // 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();
+  const mergedNavRef = useMergedRefs(ref, navRef, modalityRef);
   const collapseStateRef = useRef<SideNavCollapseState>({
     isCollapsed: false,
     toggle: () => {},
@@ -492,7 +528,14 @@ export function SideNav({
   // it through AppShell's own handle (`component:AppShell` FR17); outside,
   // SideNav holds its own over its parent.
   const shell = use(SideNavShellContext);
-  const ownLayout = useMemo(() => createRailLayout(() => navRef.current), []);
+  // 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,
@@ -506,7 +549,7 @@ export function SideNav({
       running?.endContent();
       motionRef.current = null;
       railSnapshotRef.current = snapshotRail(
-        shell?.rail() ?? navRef.current,
+        shell?.rail() ?? ownRail(),
         shell?.animatedLayout ?? ownLayout,
         shown,
         wasCollapsed,
@@ -521,7 +564,7 @@ export function SideNav({
       }
       shell?.beforeRailChange();
     },
-    [shell, ownLayout],
+    [shell, ownLayout, ownRail],
   );
   useLayoutEffect(() => {
     const snapshot = railSnapshotRef.current;
@@ -534,13 +577,13 @@ export function SideNav({
     motionRef.current = {
       rail: playRail(
         snapshot,
-        shell?.rail() ?? navRef.current,
+        shell?.rail() ?? ownRail(),
         shell?.animatedLayout ?? ownLayout,
         shell?.column() ?? null,
       ),
       endContent,
     };
-  }, [collapsed, shell, ownLayout]);
+  }, [collapsed, shell, ownLayout, ownRail]);
   // An unmount mid-motion removes the copy at once.
   useLayoutEffect(
     () => () => {
@@ -550,6 +593,118 @@ export function SideNav({
     [],
   );
 
+  // 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;
 
@@ -616,7 +771,9 @@ export function SideNav({
   // =========================================================================
   // Drawer mode — render inside MobileNav with heading as header
   // =========================================================================
-  const hasDrawerFooter = !!(footer || footerIcons);
+  // 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 (
@@ -632,7 +789,7 @@ export function SideNav({
         {hasDrawerFooter && (
           <div {...stylex.props(styles.drawerFooter)}>
             {footer}
-            {footerIcons && (
+            {isRenderable(footerIcons) && (
               <div {...stylex.props(styles.drawerFooterIcons)}>
                 <SizeProvider value={FOOTER_ICON_SIZE}>
                   {footerIcons}
@@ -657,7 +814,7 @@ export function SideNav({
         {hasDrawerFooter && (
           <div {...stylex.props(styles.drawerFooter)}>
             {footer}
-            {footerIcons && (
+            {isRenderable(footerIcons) && (
               <div {...stylex.props(styles.drawerFooterIcons)}>
                 <SizeProvider value={FOOTER_ICON_SIZE}>
                   {footerIcons}
@@ -673,8 +830,8 @@ export function SideNav({
   // =========================================================================
   // Default mode — full sidebar
   // =========================================================================
-  const hasStickyTop = !!(header || topContent);
-  const hasStickyBottom = !!(footer || footerIcons);
+  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).
@@ -708,7 +865,7 @@ export function SideNav({
             collapsed && styles.stickyTopCollapsed,
           )}>
           {header}
-          {topContent && (
+          {isRenderable(topContent) && (
             <div {...stylex.props(styles.topContent)}>{topContent}</div>
           )}
         </div>
@@ -749,42 +906,82 @@ export function SideNav({
   // Overlay drag handle inside the nav when resizable.
   // Uses ResizeHandle in overlay mode so the handle sits inside
   // the panel's overflow: clip bounds.
-  const rail = showResizeHandle ? (
-    <div {...stylex.props(styles.resizableContainer)}>
+  // 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}
-      <ResizeHandle
-        data-testid="astryx-sidenav-resize-handle"
-        direction="horizontal"
-        position="overlay"
-        pillPlacement="end"
-        isAlwaysVisible={false}
-        xstyle={styles.resizableHandle}
-        resizable={resizableHook.props}
-        label={t('@astryx.sideNav.resizeSidebar')}
-        aria-controls={navId}
-      />
+      {showResizeHandle && (
+        <ResizeHandle
+          data-testid="astryx-sidenav-resize-handle"
+          direction="horizontal"
+          position="overlay"
+          pillPlacement="end"
+          isAlwaysVisible={false}
+          xstyle={styles.resizableHandle}
+          resizable={resizableHook.props}
+          label={t('@astryx.sideNav.resizeSidebar')}
+          aria-controls={navId}
+        />
+      )}
     </div>
   ) : (
     navElement
   );
-  // The snapshot stays mounted outside the resize wrapper, which comes and
-  // goes with the collapse it measures.
+  // The snapshot stays mounted outside the resize wrapper.
   const content = (
     <>
-      <LayoutChangeSnapshot value={collapsed} onBeforeChange={measureRail} />
+      <LayoutChangeSnapshot
+        value={collapsed}
+        onBeforeChange={beforeRailChange}
+      />
       {rail}
     </>
   );
 
   if (isCollapsible) {
     return (
-      <SideNavCollapseContext value={collapseContext}>
-        {content}
-      </SideNavCollapseContext>
+      <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';