@astryxdesign/core 0.7.1 → 0.7.2-canary.01eab6a

package/src/Selector/hooks.ts

@@ -6,8 +6,12 @@
  * @file hooks.ts
  * @input Uses untransformed DOM layout geometry from the Selector's outer
  *   anchor, listbox, and selected option
- * @output Hooks for Selector
- * @position Internal hooks; used by Selector.tsx
+ * @output Hooks for Selector: useSelectedItemOffset, and useCombobox (public,
+ *   exported from the Selector entry point; also used by CommandPalette)
+ * @position Selector hooks; used by Selector.tsx and CommandPalette
+ *
+ * SYNC: When useCombobox's options or return change, update:
+ * - /packages/core/src/Selector/useCombobox.doc.mjs
  */
 
 import {useCallback, useState} from 'react';

package/src/Selector/useCombobox.doc.mjs

@@ -0,0 +1,237 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useCombobox',
+  displayName: 'useCombobox',
+  group: 'Selector',
+  keywords: [
+    'combobox',
+    'listbox',
+    'select',
+    'dropdown',
+    'highlight',
+    'active option',
+    'aria-activedescendant',
+    'keyboard',
+    'arrow keys',
+    'headless',
+    'apg',
+    'accessibility',
+    'a11y',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseComboboxOptions',
+      description: 'Configuration object.',
+      required: true,
+    },
+    {
+      name: 'options.selectableItems',
+      type: 'SelectorOptionData[]',
+      description:
+        'The options in the same order as they render. Options with `disabled` cannot be picked and are skipped while moving through the open list; ArrowDown or ArrowUp that opens the list still lands on the first or last option.',
+      required: true,
+    },
+    {
+      name: 'options.isOpen',
+      type: 'boolean',
+      description: 'Whether the list is shown. The caller owns this state.',
+      required: true,
+    },
+    {
+      name: 'options.onOpen',
+      type: '() => unknown',
+      description:
+        'Called to show the list. Return `false` to refuse; the hook then leaves the highlight alone.',
+      required: true,
+    },
+    {
+      name: 'options.onClose',
+      type: '() => void',
+      description:
+        'Called when the hook hides the list; the hook resets the highlight first. When the caller closes the list itself (an outside press, say), it should also call `setHighlightedIndex(-1)`.',
+      required: true,
+    },
+    {
+      name: 'options.listboxId',
+      type: 'string',
+      description:
+        "The listbox element's id. Option ids are derived from it through `getItemId`.",
+      required: true,
+    },
+    {
+      name: 'options.value',
+      type: 'string',
+      description:
+        'The selected value. Without search, opening by a press, Enter or Space highlights it, or the first option when nothing is selected; ArrowDown and ArrowUp open on the first and last option.',
+    },
+    {
+      name: 'options.onSelect',
+      type: '(value: string) => void',
+      description:
+        'Called with the picked value. Picking also closes the list.',
+    },
+    {
+      name: 'options.onClear',
+      type: '() => void',
+      description:
+        'Clears the value. When provided, Delete or Backspace on the closed control clears it, so clearing is not pointer-only. Ignored while the list is open or with `hasSearch`.',
+    },
+    {
+      name: 'options.hasSearch',
+      type: 'boolean',
+      description:
+        'Whether the list has its own search field. Space then types instead of picking, opening by a press or Enter does not pre-highlight (ArrowDown and ArrowUp still open on the first and last option), and printable keys on the closed control go to `onSearchSeed`.',
+      default: 'false',
+    },
+    {
+      name: 'options.onSearchSeed',
+      type: '(char: string) => void',
+      description:
+        'With `hasSearch`, receives each printable character except Space typed while the control has focus, opening the list first when it is closed, so type-to-find needs no separate open step.',
+    },
+    {
+      name: 'options.isDisabled',
+      type: 'boolean',
+      description: 'Whether the control ignores clicks and keys.',
+      default: 'false',
+    },
+  ],
+  returns: [
+    {
+      name: 'highlightedIndex',
+      type: 'number',
+      description:
+        'Index of the active option, or -1 when none is active. With `hasSearch`, opening by a press or Enter does not set one, so it stays -1 after the hook itself closes the list; ArrowDown and ArrowUp still open on the first or last option. Render it as the active option and name it in `aria-activedescendant` only while it points at a rendered option.',
+    },
+    {
+      name: 'setHighlightedIndex',
+      type: '(index: number) => void',
+      description:
+        'Sets the active option, for example from a filter that changes the options.',
+    },
+    {
+      name: 'getItemId',
+      type: '(index: number) => string',
+      description:
+        "The id to render on the option at `index`. Set the control's `aria-activedescendant` to `isOpen && highlightedIndex >= 0 && highlightedIndex < selectableItems.length ? getItemId(highlightedIndex) : undefined`, so it never names an option that does not exist, including in an empty list.",
+    },
+    {
+      name: 'onTriggerClick',
+      type: '() => void',
+      description: 'Toggles the list from a press on the control.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: React.KeyboardEvent) => void',
+      description:
+        'Key handler for the control that keeps focus. ArrowDown and ArrowUp open the list or move the active option; Enter (and Space without search) picks it or opens the list; Escape and Tab close it; Home, End, PageUp and PageDown jump to the first or last option. An editable control that keeps Home and End for the caret does not pass them to this handler, as CommandPalette does.',
+    },
+    {
+      name: 'onItemSelect',
+      type: '(item: SelectorOptionData) => void',
+      description: 'Picks an option from a press on it, then closes the list.',
+    },
+    {
+      name: 'onItemMouseEnter',
+      type: '(item: SelectorOptionData, index: number) => void',
+      description:
+        'Makes the hovered option active without scrolling the list or moving focus.',
+    },
+  ],
+  usage: {
+    description:
+      'Tracks the active option of a single-select combobox and handles its keys, while DOM focus stays on the control. It powers Selector and CommandPalette; use it to build a combobox those components do not cover. It renders nothing and sets no attributes: the caller renders the control, the listbox and the options, and wires `role`, `aria-expanded`, `aria-controls` and `aria-activedescendant` from what it returns.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Render each option with `id={getItemId(index)}` and set the control's `aria-activedescendant` only while `isOpen` and `highlightedIndex` points at a rendered option, as CommandPalette does.",
+      },
+      {
+        guidance: true,
+        description:
+          "For type-to-select without a search field, run useTypeahead's handler first and fall through to this `onKeyDown` when it returns false, as Selector does.",
+      },
+      {
+        guidance: true,
+        description:
+          'Announce the number of results through useAnnounce when the options change for a new query.',
+      },
+      {
+        guidance: false,
+        description:
+          'Move DOM focus onto the options; the active option is announced through `aria-activedescendant` while focus stays on the control.',
+      },
+    ],
+  },
+  relatedComponents: ['Selector', 'CommandPalette'],
+  relatedHooks: ['useMultiCombobox', 'useTypeahead', 'useAnnounce'],
+  importPath: '@astryxdesign/core/Selector',
+  category: 'focus',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Single-select combobox state + keys; focus stays on control. Powers Selector / CommandPalette. Renders nothing, sets no attrs: caller renders control / listbox / options and wires role, aria-expanded, aria-controls, aria-activedescendant.',
+  paramDescriptions: {
+    options: 'config.',
+    'options.selectableItems':
+      'options in render order; disabled ones not pickable, skipped while moving in open list (ArrowDown/Up opening still lands first / last).',
+    'options.isOpen': 'list shown; caller owns state.',
+    'options.onOpen':
+      'show list; return false to refuse (highlight untouched).',
+    'options.onClose':
+      'hook hides list; resets highlight first. caller closing itself (outside press): also setHighlightedIndex(-1).',
+    'options.listboxId': 'listbox id; option ids derive from it (getItemId).',
+    'options.value':
+      'selected value; w/o search, press / Enter / Space opening highlights it (else first); ArrowDown/Up open on first / last.',
+    'options.onSelect': 'called w/ picked value; picking closes.',
+    'options.onClear':
+      'clears value; Delete / Backspace on closed control. ignored when open or hasSearch.',
+    'options.hasSearch':
+      'list has own search field: Space types, press / Enter opening does not pre-highlight (ArrowDown/Up still first / last), printable keys on closed control -> onSearchSeed.',
+    'options.onSearchSeed':
+      'w/ hasSearch, each printable char except Space typed while control focused (opens first if closed).',
+    'options.isDisabled': 'ignore clicks + keys.',
+  },
+  returnDescriptions: {
+    highlightedIndex:
+      'active option index, -1 = none. hasSearch: press / Enter opening sets none (stays -1 after hook closes); ArrowDown/Up still first / last. name in aria-activedescendant only when it points at a rendered option.',
+    setHighlightedIndex: 'set active option (e.g. after filtering).',
+    getItemId:
+      'id for option at index; aria-activedescendant = isOpen && highlightedIndex >= 0 && highlightedIndex < selectableItems.length ? getItemId(highlightedIndex) : undefined (empty list safe).',
+    onTriggerClick: 'toggle list from a press on control.',
+    onKeyDown:
+      'control keydown: ArrowDown/Up open or move; Enter (Space w/o search) picks or opens; Escape / Tab close; Home / End / PageUp / PageDown jump. editable control keeping Home / End for caret: do not pass them.',
+    onItemSelect: 'pick from a press, then close.',
+    onItemMouseEnter: 'hover makes option active; no scroll, no focus move.',
+  },
+  usage: {
+    description:
+      'Headless single-select combobox: active option + keys, focus stays on control. Caller renders + wires ARIA.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Option id = getItemId(index); aria-activedescendant only while open and highlightedIndex points at a rendered option.',
+      },
+      {
+        guidance: true,
+        description:
+          'Type-to-select w/o search: run useTypeahead first, fall through when it returns false.',
+      },
+      {
+        guidance: true,
+        description: 'Announce result count via useAnnounce on new query.',
+      },
+      {
+        guidance: false,
+        description: 'Move DOM focus onto options; use aria-activedescendant.',
+      },
+    ],
+  },
+};

package/src/SideNav/SideNav.test.tsx

@@ -828,6 +828,169 @@ describe('SideNavItem', () => {
     expect(screen.getByText('Security')).toBeInTheDocument();
   });
 
+  it('keeps nested rows full width and indents their content inside the row', () => {
+    render(
+      <SideNavItem label="Settings">
+        <SideNavItem label="General" href="/settings/general">
+          <SideNavItem label="Advanced" href="/settings/general/advanced" />
+        </SideNavItem>
+      </SideNavItem>,
+    );
+
+    // The children group adds no inset of its own, so a nested row's hover
+    // and selected fill spans the nav list like a top-level row's.
+    const groups = screen.getAllByRole('group', {hidden: true});
+    for (const group of groups) {
+      expect(declaredOn(group, 'padding-inline-start')).toEqual([]);
+      expect(
+        declaredOn(group.firstElementChild!, 'padding-inline-start'),
+      ).toEqual([]);
+    }
+
+    // The indent lives inside each row instead, one step per nesting level.
+    // An ordinary row is the link itself: its own padding plus the steps.
+    const top = screen.getByRole('button', {name: 'Settings'});
+    const general = screen.getByRole('link', {name: 'General'});
+    const advanced = screen.getByRole('link', {name: 'Advanced'});
+    expect(indentOf(top)).toBeNull();
+    expect(indentOf(advanced)).toBe(
+      'calc(var(--spacing-2) + 2 * var(--spacing-6))',
+    );
+
+    // A split row (own href plus children) keeps the wrapper's base padding
+    // and puts the steps on the link, so the whole indent is clickable
+    // instead of dead space that still shows hover and press feedback.
+    expect(indentOf(general.parentElement!)).toBeNull();
+    expect(indentOf(general)).toBe('calc(1 * var(--spacing-6))');
+  });
+
+  it('clips the children group only while it is collapsed', async () => {
+    // Nested rows sit flush with the group, so a permanent clip would cut off
+    // their focus ring. The group clips for the collapse animation only.
+    const user = userEvent.setup();
+    render(
+      <SideNavItem label="Settings" collapsible>
+        <SideNavItem label="General" href="/settings/general" />
+      </SideNavItem>,
+    );
+    const group = () => screen.getByRole('group', {hidden: true});
+    expect(declaredOn(group(), 'overflow')).toEqual(['visible']);
+    expect(declaredOn(group().firstElementChild!, 'overflow')).toEqual([]);
+
+    await user.click(screen.getByRole('button', {name: 'Settings'}));
+    expect(declaredOn(group(), 'overflow')).toEqual(['hidden']);
+  });
+
+  it('puts the indent on the primary link of a nested actions row', () => {
+    render(
+      <SideNavItem label="Projects">
+        <SideNavItem
+          label="Alpha"
+          href="/projects/alpha"
+          actions={
+            <button type="button" aria-label="Alpha actions">
+              More
+            </button>
+          }
+        />
+      </SideNavItem>,
+    );
+    const alpha = screen.getByRole('link', {name: 'Alpha'});
+    expect(indentOf(alpha.parentElement!)).toBeNull();
+    expect(indentOf(alpha)).toBe('calc(1 * var(--spacing-6))');
+  });
+
+  it("composes a caller's style with the indent on a nested row", () => {
+    render(
+      <SideNavItem label="Settings">
+        <SideNavItem
+          label="General"
+          href="/settings/general"
+          style={{color: 'rebeccapurple'}}
+        />
+        <SideNavItem
+          label="Security"
+          href="/settings/security"
+          style={{color: 'rebeccapurple'}}>
+          <SideNavItem label="Keys" href="/settings/security/keys" />
+        </SideNavItem>
+      </SideNavItem>,
+    );
+    // Ordinary row: the link is the row.
+    const general = screen.getByRole('link', {name: 'General'});
+    expect(general.style.color).toBe('rebeccapurple');
+    expect(indentOf(general)).toBe(
+      'calc(var(--spacing-2) + 1 * var(--spacing-6))',
+    );
+    // Split row: the caller's style still lands on the primary link.
+    const security = screen.getByRole('link', {name: 'Security'});
+    expect(security.style.color).toBe('rebeccapurple');
+    expect(indentOf(security)).toBe('calc(1 * var(--spacing-6))');
+  });
+
+  it("lets a caller's inline-start padding replace the indent", () => {
+    // The caller's `style` composes after the indent: a caller-set
+    // inline-start padding is an inline declaration, so it wins over the
+    // indent's class rule on the element that carries the indent, on both
+    // the ordinary and the split row path.
+    render(
+      <SideNavItem label="Settings">
+        <SideNavItem
+          label="General"
+          href="/settings/general"
+          style={{paddingInlineStart: '20px'}}
+        />
+        <SideNavItem
+          label="Security"
+          href="/settings/security"
+          style={{paddingInlineStart: '20px'}}>
+          <SideNavItem label="Keys" href="/settings/security/keys" />
+        </SideNavItem>
+      </SideNavItem>,
+    );
+    const general = screen.getByRole('link', {name: 'General'});
+    expect(general.style.paddingInlineStart).toBe('20px');
+    const security = screen.getByRole('link', {name: 'Security'});
+    expect(security.style.paddingInlineStart).toBe('20px');
+    // A row whose caller sets no padding keeps its indent.
+    expect(indentOf(screen.getByRole('link', {name: 'Keys'}))).toBe(
+      'calc(var(--spacing-2) + 2 * var(--spacing-6))',
+    );
+  });
+
+  it('indents a small nested row from the small row padding', () => {
+    render(
+      <SideNavItem label="Settings">
+        <SideNavItem label="General" href="/settings/general" size="sm" />
+      </SideNavItem>,
+    );
+    expect(indentOf(screen.getByRole('link', {name: 'General'}))).toBe(
+      'calc(var(--spacing-1) + 1 * var(--spacing-6))',
+    );
+  });
+
+  it('does not indent the first level of a collapsed rail flyout', async () => {
+    const user = userEvent.setup();
+    renderCollapsed(
+      <SideNavItem label="Settings" icon={StubIcon}>
+        <SideNavItem label="General" href="/settings/general">
+          <SideNavItem label="Advanced" href="/settings/general/advanced" />
+        </SideNavItem>
+      </SideNavItem>,
+    );
+    await user.click(screen.getByRole('button', {name: 'Settings'}));
+
+    // jsdom leaves the native popover `display: none`, hence `hidden: true`.
+    // The flyout lists the parent's children as its own top level.
+    const general = screen.getByRole('link', {name: 'General', hidden: true});
+    const advanced = screen.getByRole('link', {name: 'Advanced', hidden: true});
+    expect(indentOf(general)).toBeNull();
+    expect(indentOf(general.parentElement!)).toBeNull();
+    expect(indentOf(advanced)).toBe(
+      'calc(var(--spacing-2) + 1 * var(--spacing-6))',
+    );
+  });
+
   it('passes data-testid', () => {
     render(<SideNavItem label="Dashboard" data-testid="nav-item" />);
     expect(screen.getByTestId('nav-item')).toBeInTheDocument();
@@ -2457,6 +2620,22 @@ function declaredOn(el: Element, prop: string): string[] {
     .filter(value => value != null);
 }
 
+/**
+ * The nesting indent a row carries, or null for none. The indent is a
+ * runtime StyleX value, so it rides the row's inline style as a custom
+ * property; read the value rather than the generated property name.
+ */
+function indentOf(el: HTMLElement): string | null {
+  const {style} = el;
+  for (let i = 0; i < style.length; i++) {
+    const value = style.getPropertyValue(style[i]).trim();
+    if (value.includes('var(--spacing-6)')) {
+      return value;
+    }
+  }
+  return null;
+}
+
 /**
  * The selectors that actually paint the shared ring on `el`, read out of the
  * live stylesheet with StyleX's `:not(#\#)` specificity padding stripped so

package/src/SideNav/SideNavItem.doc.mjs

@@ -90,7 +90,7 @@ export const docs = {
     {
       name: 'children',
       type: 'ReactNode',
-      description: 'Sub-items for nesting.',
+      description: '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.',
       slotElements: [
         {
           __element: 'SideNavItem',
@@ -213,7 +213,7 @@ export const docsDense = {
       'Passive right-side content only (badges, counts). Interactive controls go in actions.',
     actions:
       'Row-level secondary controls (icon buttons, menus) rendered as siblings of the primary element, after the expand/collapse toggle and before nested children in DOM/focus order. Inherit the row control size via SizeContext (explicit size wins). Hidden when rail collapsed. Passive content goes in endContent; interactive content goes here.',
-    children: 'Sub-items for nesting.',
+    children: 'Sub-items for nesting. Nested rows stay full width; content indents one step per level.',
     collapsible: 'Enables collapse for items w/ children. true=uncontrolled, object=controlled mode.',
     size: "Row size variant: 'sm' | 'md' | 'lg'.",
   },

package/src/SideNav/SideNavItem.tsx

@@ -17,6 +17,11 @@
  * `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
@@ -26,6 +31,8 @@
  */
 
 import {
+  createContext,
+  use,
   useCallback,
   useId,
   useMemo,
@@ -108,26 +115,45 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-1'],
     pointerEvents: 'auto',
   },
-  children: {
-    paddingInlineStart: spacingVars['--spacing-6'],
-  },
+  // 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',
-    transitionProperty: 'grid-template-rows',
+    overflow: 'visible',
+    transitionProperty: 'grid-template-rows, overflow',
+    transitionBehavior: 'allow-discrete',
     transitionDuration: {
-      default: durationVars['--duration-medium'],
-      '@media (prefers-reduced-motion: reduce)': '0s',
+      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: {
-    overflow: 'hidden',
     minHeight: 0,
-    paddingInlineStart: spacingVars['--spacing-6'],
   },
   expandChevron: {
     display: 'inline-flex',
@@ -232,6 +258,35 @@ const styles = stylex.create({
   },
 });
 
+// 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 = createContext(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,
@@ -363,7 +418,9 @@ export interface SideNavItemProps extends BaseProps<HTMLElement> {
    */
   actions?: ReactNode;
   /**
-   * Sub-items for nesting.
+   * 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;
   /**
@@ -455,6 +512,7 @@ export function SideNavItem({
   const id = useId();
   const hasChildren = !!children;
   const itemRef = useRef<HTMLDivElement>(null);
+  const depth = use(SideNavItemDepthContext);
 
   // Popover for collapsed items with children
   const popover = usePopover({
@@ -608,7 +666,9 @@ export function SideNavItem({
               onClick={() => popover.hide()}>
               <div {...stylex.props(styles.popoverHeader)}>{label}</div>
               <SideNavCollapseContext value={EXPANDED_COLLAPSE_STATE}>
-                {children}
+                <SideNavItemDepthContext value={0}>
+                  {children}
+                </SideNavItemDepthContext>
               </SideNavCollapseContext>
             </div>,
             {placement: 'end', alignment: 'start', xstyle: styles.popoverGap},
@@ -686,6 +746,14 @@ export function SideNavItem({
     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.
+  const callerStyle = {style: rest.style};
 
   // Three shapes of the same row appearance:
   // - `rowProps` — split-action path (toggle, no actions): presentational
@@ -702,7 +770,10 @@ export function SideNavItem({
   const focusableRowProps = {
     ...mergeProps(
       itemThemeProps,
-      focusOutlineProps.focusVisible(...itemStyleArgs),
+      mergeProps(
+        focusOutlineProps.focusVisible(...itemStyleArgs, rowIndent),
+        callerStyle,
+      ),
     ),
     ...pressable,
   };
@@ -748,11 +819,17 @@ export function SideNavItem({
           onClick={handleClick}
           {...rest}
           {...rowPrimaryAriaProps}
-          {...(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)
-            : focusOutlineProps.focusVisible(styles.splitAction))}>
+          {...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 && (
@@ -831,7 +908,9 @@ export function SideNavItem({
             <span id={`${id}-label`} hidden>
               {label}
             </span>
-            {children}
+            <SideNavItemDepthContext value={depth + 1}>
+              {children}
+            </SideNavItemDepthContext>
           </div>
         </div>
       )}