@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

package/dist/Outline/Outline.js

@@ -4,7 +4,7 @@
 
 /**
  * @file Outline.tsx
- * @input Uses React, StyleX, Astryx link provider integration, Outline hooks/types
+ * @input Uses React, StyleX, Astryx link provider integration, Outline hooks/types, useListFocus
  * @output Exports Outline component and OutlineProps type
  * @position Core implementation; consumed by index.ts
  *
@@ -12,6 +12,9 @@
  * - Sliding indicator track (vertical divider + animated active bar)
  * - Density variant (default/compact)
  * - Scroll-spy active state when uncontrolled
+ * - Roving-tabindex keyboard navigation (Arrow/Home/End, Enter/Space activate)
+ * - onNavigateStart / onNavigateEnd callbacks around the smooth scroll
+ * - Scroll scoping (offset, scrollContainerRef, hasScrollOnClick)
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Outline/Outline.doc.mjs
@@ -24,6 +27,8 @@ import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, durationVars, easeVars, radiusVars, spacingVars, typeScaleVars, fontWeightVars } from "../theme/tokens.stylex.js";
 import { useLinkComponent } from "../Link/useLinkComponent.js";
+import { useListFocus } from "../hooks/useListFocus.js";
+import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
 import { mergeProps, mergeRefs } from "../utils/index.js";
 import { useScrollSpy } from "./useScrollSpy.js";
 import { themeProps } from "../utils/themeProps.js";
@@ -135,8 +140,15 @@ function getIndentStyle(level) {
  * track that animates to the active item.
  *
  * When `activeId` is omitted, it tracks scroll position and marks the last
- * heading whose top has passed its activation line (its scroll-margin-top)
- * active — defaulting to the first item at the top and the last at the bottom.
+ * heading whose top has passed its activation line — which is exactly where
+ * navigating to that heading lands it: `offset` (a fixed header overlaying the
+ * scroll root) plus the heading's own `scroll-margin-top`. It defaults to the
+ * first item at the top and the last at the bottom.
+ *
+ * Keyboard: the list is a single tab stop (roving tabindex), seated on the
+ * active heading. Arrow keys move between headings, Home/End jump to the ends,
+ * and Enter/Space activate — so a long table of contents costs one Tab press,
+ * not one per heading.
  *
  * @example
  * ```
@@ -148,6 +160,20 @@ function getIndentStyle(level) {
  *   ]}
  * />
  * ```
+ *
+ * Scoped to a custom scroll container, under a fixed header:
+ *
+ * @example
+ * ```
+ * const scrollContainerRef = useRef<HTMLDivElement>(null);
+ * <div ref={scrollContainerRef} style={{overflowY: 'auto'}}>...</div>
+ * <Outline
+ *   items={items}
+ *   scrollContainerRef={scrollContainerRef}
+ *   offset={64}
+ *   onNavigateEnd={id => flashHeading(id)}
+ * />
+ * ```
  */
 export function Outline({
   items,
@@ -155,6 +181,11 @@ export function Outline({
   onActiveIdChange,
   label: labelFromProps,
   density = 'default',
+  onNavigateStart,
+  onNavigateEnd,
+  offset = 0,
+  scrollContainerRef,
+  hasScrollOnClick = true,
   xstyle,
   className,
   style,
@@ -166,42 +197,109 @@ export function Outline({
   const label = labelFromProps ?? t('@astryx.outline.label');
   const rootRef = useRef(null);
   const LinkComponent = useLinkComponent();
-  const isControlled = activeId !== undefined;
   const {
     activeId: resolvedActiveId,
-    setActiveId,
-    lockActiveId
+    scrollTo
   } = useScrollSpy({
     activeId,
     items,
     onActiveIdChange,
-    rootRef
+    rootRef,
+    offset,
+    scrollContainerRef,
+    hasScrollOnClick,
+    onNavigateStart,
+    onNavigateEnd
+  });
+
+  // Roving tabindex over the links: the whole outline is one tab stop, and
+  // arrows move between headings. The hook owns `tabindex` on the items.
+  const {
+    listRef,
+    handleKeyDown: handleListKeyDown,
+    handleFocus
+  } = useListFocus({
+    itemSelector: 'a[href]',
+    orientation: 'vertical',
+    hasRovingTabIndex: true
+  });
+
+  // Seat the tab stop on the *active* heading. WAI-ARIA puts the single tab
+  // stop on the current item, so tabbing into a table of contents while
+  // reading section 7 lands on section 7 — not back at section 1, which is
+  // where useListFocus would otherwise leave it (it promotes the first item on
+  // mount and then keeps whichever item already holds the stop).
+  //
+  // Only while focus is outside the list: once the reader has arrowed to an
+  // item, the stop is theirs and scroll-spy must not yank it away. Sets
+  // `tabindex` only — it never steals focus. Registered after useListFocus so
+  // it runs after the hook's own layout effect and wins; on later commits the
+  // hook then finds this item already holding the stop and keeps it.
+  useIsomorphicLayoutEffect(() => {
+    const list = listRef.current;
+    if (list == null || list.contains(document.activeElement)) {
+      return;
+    }
+    const links = Array.from(list.querySelectorAll('a[href]'));
+    const active = links.find(link => link.getAttribute('aria-current') === 'true');
+    if (active == null) {
+      return;
+    }
+    for (const link of links) {
+      const tabIndex = link === active ? '0' : '-1';
+      if (link.getAttribute('tabindex') !== tabIndex) {
+        link.setAttribute('tabindex', tabIndex);
+      }
+    }
   });
+
+  /**
+   * The single navigation path, shared by click and keyboard activation:
+   * push the hash, then hand off to the scroll-spy's `scrollTo`, which fires
+   * the navigate callbacks and moves the indicator when the scroll settles.
+   */
+  const navigate = id => {
+    if (scrollTo(id)) {
+      window.history.pushState(null, '', `#${id}`);
+    }
+  };
+
+  /** Whether an event carries a modifier chord we must leave to the browser. */
+  const hasModifier = event => event.metaKey || event.altKey || event.ctrlKey || event.shiftKey;
   const handleClick = id => event => {
-    const target = document.getElementById(id);
+    // Let the browser handle modified clicks (open in new tab, etc.) without
+    // touching the active state.
+    if (event.defaultPrevented || hasModifier(event)) {
+      return;
+    }
 
-    // Let the browser handle modified clicks (open in new tab, etc.) and
-    // missing targets without touching the active state.
-    if (target == null || event.defaultPrevented || event.metaKey || event.altKey || event.ctrlKey || event.shiftKey) {
+    // With no target in the DOM — lazily-rendered or virtualized content —
+    // there is nothing to scroll to and nothing to make active. Leave the
+    // anchor to the browser's native fragment navigation (which still
+    // updates the URL) rather than swallowing the click into a dead link.
+    if (document.getElementById(id) == null) {
       return;
     }
-    event.preventDefault();
-    window.history.pushState(null, '', `#${id}`);
 
-    // Move the indicator to the clicked item in a single step. Controlled
-    // consumers own the active state (notify only); uncontrolled mode pins
-    // the active id and suppresses scroll-spy until the next manual scroll,
-    // so the click is honored — even for short/last sections — and the
-    // indicator doesn't chase the smooth scroll through other sections.
-    if (isControlled) {
-      setActiveId(id);
-    } else {
-      lockActiveId(id);
+    // Suppress the anchor's default jump: we own the scroll (or, with
+    // `hasScrollOnClick={false}`, deliberately leave it to the consumer).
+    event.preventDefault();
+    navigate(id);
+  };
+  const handleKeyDown = id => event => {
+    // Enter is a link's native activation and already produces a click.
+    // Space is not, so wire it up here to match the button-like affordance.
+    if (event.key !== ' ' && event.key !== 'Spacebar') {
+      return;
     }
-    target.scrollIntoView({
-      behavior: 'smooth',
-      block: 'start'
-    });
+    if (event.defaultPrevented || hasModifier(event)) {
+      return;
+    }
+
+    // preventDefault does double duty: it stops the page from scrolling, and
+    // it tells useScrollSpy this Space is an activation, not a manual scroll.
+    event.preventDefault();
+    navigate(id);
   };
   return /*#__PURE__*/_jsxs("nav", {
     ...props,
@@ -215,7 +313,10 @@ export function Outline({
       ...{
         className: "x78zum5 xdt5ytf x1lsbc85 x1ghz6dp x1717udv xe8uvvx x98rzlu xeuugli"
       },
+      ref: listRef,
       role: "list",
+      onKeyDown: handleListKeyDown,
+      onFocus: handleFocus,
       children: items.map(item => {
         const isActive = item.id === resolvedActiveId;
         return /*#__PURE__*/_jsx("li", {
@@ -227,6 +328,7 @@ export function Outline({
             href: `#${item.id}`,
             "aria-current": isActive ? 'true' : undefined,
             onClick: handleClick(item.id),
+            onKeyDown: handleKeyDown(item.id),
             ...mergeProps(themeProps('outline-item', {
               active: isActive ? 'active' : null,
               level: item.level

package/dist/Outline/useScrollSpy.d.ts

@@ -4,20 +4,40 @@ interface UseScrollSpyOptions {
     items: OutlineItem[];
     onActiveIdChange?: (id: string) => void;
     rootRef: React.RefObject<HTMLElement | null>;
+    /**
+     * Height in px of a fixed header overlaying the top of the scroll root.
+     * Shifts both the activation line and the scroll landing by the same amount,
+     * on top of each heading's own `scroll-margin-top`.
+     */
+    offset?: number;
+    /** Scroll container to track, instead of the nearest scrollable ancestor. */
+    scrollContainerRef?: React.RefObject<HTMLElement | null>;
+    /** Whether {@link UseScrollSpyResult.scrollTo} performs the smooth scroll. */
+    hasScrollOnClick?: boolean;
+    /** Called when a navigation begins, before the scroll starts. */
+    onNavigateStart?: (id: string) => void;
+    /** Called once per navigation, when the scroll settles or is interrupted. */
+    onNavigateEnd?: (id: string) => void;
 }
 interface UseScrollSpyResult {
     activeId: string | undefined;
     /** Set the active id (notifies onActiveIdChange). For controlled consumers. */
     setActiveId: (id: string) => void;
     /**
-     * Handle a click on the outline item with id `id`. Delays moving the
-     * indicator: scroll-spy is suppressed during the programmatic smooth scroll
-     * so the indicator doesn't chase it, then the indicator moves once to the
-     * clicked item when the scroll settles. If the user scrolls manually mid-way,
-     * scroll-position tracking resumes immediately instead.
+     * Navigate to the item with id `id` — the single path shared by click and
+     * keyboard activation.
+     *
+     * Fires `onNavigateStart(id)`, scrolls (unless `hasScrollOnClick` is false),
+     * and fires `onNavigateEnd(id)` exactly once when the scroll settles or the
+     * user interrupts it. While uncontrolled, scroll-spy is suppressed for the
+     * duration so the indicator doesn't chase the scroll through intervening
+     * sections; it lands on the target once the scroll settles, or resumes
+     * position tracking if the user scrolls away mid-flight.
+     *
+     * Returns false (and does nothing) when no element with `id` exists.
      */
-    lockActiveId: (id: string) => void;
+    scrollTo: (id: string) => boolean;
 }
-export declare function useScrollSpy({ activeId, items, onActiveIdChange, rootRef, }: UseScrollSpyOptions): UseScrollSpyResult;
+export declare function useScrollSpy({ activeId, items, onActiveIdChange, rootRef, offset, scrollContainerRef, hasScrollOnClick, onNavigateStart, onNavigateEnd, }: UseScrollSpyOptions): UseScrollSpyResult;
 export {};
 //# sourceMappingURL=useScrollSpy.d.ts.map

package/dist/Outline/useScrollSpy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useScrollSpy.d.ts","sourceRoot":"","sources":["../../src/Outline/useScrollSpy.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAuFzC,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC9C;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,+EAA+E;IAC/E,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,KAAK,EACL,gBAAgB,EAChB,OAAO,GACR,EAAE,mBAAmB,GAAG,kBAAkB,CA2I1C"}
+{"version":3,"file":"useScrollSpy.d.ts","sourceRoot":"","sources":["../../src/Outline/useScrollSpy.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAsJzC,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC7C;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACzD,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iEAAiE;IACjE,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,6EAA6E;IAC7E,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,+EAA+E;IAC/E,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC;AAED,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,KAAK,EACL,gBAAgB,EAChB,OAAO,EACP,MAAU,EACV,kBAAkB,EAClB,gBAAuB,EACvB,eAAe,EACf,aAAa,GACd,EAAE,mBAAmB,GAAG,kBAAkB,CAoN1C"}

package/dist/Outline/useScrollSpy.js

@@ -10,15 +10,38 @@
  *
  * Drives the active outline item from scroll position. On each scroll
  * (rAF-throttled) it reads live heading positions and marks the last heading
- * whose top has passed its activation line (its own scroll-margin-top, i.e.
- * where it lands when navigated to). This is stable — it never compares stale
- * cached positions — so the indicator moves monotonically instead of jumping.
- * Defaults to the first item at the top and the last item at the bottom so
- * short final sections still activate.
+ * whose top has passed its activation line. This is stable — it never compares
+ * stale cached positions — so the indicator moves monotonically instead of
+ * jumping. Defaults to the first item at the top and the last item at the
+ * bottom so short final sections still activate.
+ *
+ * The activation line and the scroll landing are the same number, computed once
+ * in `getRestingTop`: scroll-root top + `offset` (a fixed header overlaying the
+ * root) + the heading's own `scroll-margin-top`. A heading therefore activates
+ * exactly where navigating to it puts it. `offset` and `scroll-margin-top`
+ * compose — the header, then the breathing room below it — they do not
+ * duplicate each other.
+ *
+ * It also owns the single navigation path (`scrollTo`), shared by click and
+ * keyboard activation: it announces the jump, suppresses scroll-spy for the
+ * duration of the programmatic scroll (so the indicator doesn't chase it), and
+ * resolves when the scroll settles — via `scrollend` where supported, or a
+ * timeout fallback where it is not.
+ *
+ * The scroll root is the `scrollContainerRef` element when provided, otherwise
+ * the nearest scrollable ancestor of the outline, otherwise the viewport.
  *
  * SYNC: When modified, update /packages/core/src/Outline/Outline.tsx
  */
 import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * How long to wait for a programmatic smooth scroll to settle when the
+ * `scrollend` event never arrives — either because the browser does not
+ * support it (Safari at time of writing) or because the target was already in
+ * position, so no scroll happened at all and no events were emitted.
+ */
+const SCROLL_SETTLE_TIMEOUT_MS = 1200;
+
 /** Keys that scroll the viewport — used to detect a manual scroll intent. */
 const SCROLL_KEYS = new Set(['ArrowUp', 'ArrowDown', 'PageUp', 'PageDown', 'Home', 'End', ' ', 'Spacebar']);
 function getScrollableAncestor(element) {
@@ -35,20 +58,69 @@ function getScrollableAncestor(element) {
   return null;
 }
 
+/** The element's own `scroll-margin-top` in px (0 when unset). */
+function getScrollMarginTop(element) {
+  return Number.parseFloat(window.getComputedStyle(element).scrollMarginTop) || 0;
+}
+
+/** The top of the scroll root in viewport coordinates (0 for the viewport). */
+function getRootTop(scrollRoot) {
+  return scrollRoot != null ? scrollRoot.getBoundingClientRect().top : 0;
+}
+
+/**
+ * Where a heading comes to rest, in viewport coordinates: below the fixed
+ * header (`offset`) and below its own `scroll-margin-top` breathing room.
+ *
+ * This is the single source of truth shared by the activation line and the
+ * scroll landing — the two must agree, or a heading activates somewhere other
+ * than where navigating to it puts it.
+ */
+function getRestingTop(target, scrollRoot, offset) {
+  return getRootTop(scrollRoot) + offset + getScrollMarginTop(target);
+}
+
+/**
+ * Bring `target` to rest at the top of the scroll root, below any fixed header.
+ *
+ * With no `offset`, this is the CSS-native path: `scrollIntoView` already
+ * honors the heading's `scroll-margin-top`, and it walks *every* scrollable
+ * ancestor, so the browser does it better than we can.
+ *
+ * An `offset` describes a fixed header overlaying the top of the scroll root —
+ * which the browser cannot know about, so `scrollIntoView` would park the
+ * heading underneath it, hidden. Compute the landing explicitly instead, from
+ * the same {@link getRestingTop} the activation line uses.
+ */
+function scrollToTarget(target, scrollRoot, scrollTarget, offset) {
+  if (offset === 0) {
+    target.scrollIntoView({
+      behavior: 'smooth',
+      block: 'start'
+    });
+    return;
+  }
+  const delta = target.getBoundingClientRect().top - getRestingTop(target, scrollRoot, offset);
+  scrollTarget.scrollBy({
+    top: delta,
+    behavior: 'smooth'
+  });
+}
+
 /**
  * Resolve the active heading id from current scroll position.
  *
- * A heading is "passed" once its top reaches its activation line — the scroll
- * root's top plus the heading's own scroll-margin-top. The active heading is
- * the last passed one (headings are in document order). When none have passed
- * (scrolled above the first), the first item is active; at the bottom, the
- * last item is active.
+ * A heading is "passed" once its top reaches its activation line — exactly
+ * where navigating to it would land it ({@link getRestingTop}): the scroll
+ * root's top, plus `offset` (a fixed header overlaying the scroll root), plus
+ * the heading's own scroll-margin-top. The active heading is the last passed
+ * one (headings are in document order). When none have passed (scrolled above
+ * the first), the first item is active; at the bottom, the last item is active.
  */
-function resolveActiveId(items, scrollRoot) {
+function resolveActiveId(items, scrollRoot, offset) {
   if (items.length === 0) {
     return undefined;
   }
-  const rootTop = scrollRoot != null ? scrollRoot.getBoundingClientRect().top : 0;
   const atBottom = scrollRoot != null ? scrollRoot.scrollTop + scrollRoot.clientHeight >= scrollRoot.scrollHeight - 2 : window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2;
   if (atBottom) {
     return items[items.length - 1].id;
@@ -59,9 +131,10 @@ function resolveActiveId(items, scrollRoot) {
     if (element == null) {
       continue;
     }
+
+    // 1px of tolerance absorbs sub-pixel rounding after a scroll lands.
     const top = element.getBoundingClientRect().top;
-    const marginTop = Number.parseFloat(window.getComputedStyle(element).scrollMarginTop) || 0;
-    if (top <= rootTop + marginTop + 1) {
+    if (top <= getRestingTop(element, scrollRoot, offset) + 1) {
       activeId = item.id;
     } else {
       break;
@@ -73,17 +146,23 @@ export function useScrollSpy({
   activeId,
   items,
   onActiveIdChange,
-  rootRef
+  rootRef,
+  offset = 0,
+  scrollContainerRef,
+  hasScrollOnClick = true,
+  onNavigateStart,
+  onNavigateEnd
 }) {
   const isControlled = activeId !== undefined;
   const [uncontrolledActiveId, setUncontrolledActiveId] = useState(items[0]?.id);
   const activeIdRef = useRef(activeId);
-  // While true, scroll-spy ignores scroll updates because a click is driving a
-  // programmatic scroll. Released when that scroll settles or the user scrolls.
+  // While true, scroll-spy ignores scroll updates because a navigation is
+  // driving a programmatic scroll. Released when it settles or the user scrolls.
   const suppressRef = useRef(false);
-  const releaseSuppressionRef = useRef(null);
-  // Latest scroll-position resolver, so the click handler can resume tracking
-  // when the user scrolls during a programmatic scroll.
+  // The navigation currently in flight, if any.
+  const navigationRef = useRef(null);
+  // Latest scroll-position resolver, so a navigation can resume tracking when
+  // the user scrolls during the programmatic scroll.
   const syncRef = useRef(null);
   // Keep latest items/callback in refs so the scroll listener effect doesn't
   // re-subscribe on every render (items is a fresh array each render).
@@ -93,11 +172,20 @@ export function useScrollSpy({
   onActiveIdChangeRef.current = onActiveIdChange;
   const itemIds = items.map(item => item.id).join('\n');
   activeIdRef.current = isControlled ? activeId : uncontrolledActiveId;
+
+  /**
+   * The element whose scroll position drives the outline: the explicit
+   * container when scoped, else the nearest scrollable ancestor, else null
+   * (meaning the viewport).
+   */
+  const getScrollRoot = useCallback(() => {
+    return scrollContainerRef?.current ?? getScrollableAncestor(rootRef.current);
+  }, [rootRef, scrollContainerRef]);
   useEffect(() => {
     if (isControlled || typeof window === 'undefined') {
       return;
     }
-    const scrollRoot = getScrollableAncestor(rootRef.current);
+    const scrollRoot = getScrollRoot();
     const scrollTarget = scrollRoot ?? window;
     let frame = 0;
     const update = () => {
@@ -105,7 +193,7 @@ export function useScrollSpy({
       if (suppressRef.current) {
         return;
       }
-      const nextActiveId = resolveActiveId(itemsRef.current, scrollRoot);
+      const nextActiveId = resolveActiveId(itemsRef.current, scrollRoot, offset);
       if (nextActiveId != null && nextActiveId !== activeIdRef.current) {
         activeIdRef.current = nextActiveId;
         setUncontrolledActiveId(nextActiveId);
@@ -133,12 +221,12 @@ export function useScrollSpy({
         cancelAnimationFrame(frame);
       }
     };
-  }, [isControlled, itemIds, rootRef]);
+  }, [isControlled, itemIds, offset, getScrollRoot]);
 
-  // Tear down any pending suppression listeners when the Outline unmounts.
+  // Tear down any in-flight navigation's listeners when the Outline unmounts.
   useEffect(() => {
     return () => {
-      releaseSuppressionRef.current?.();
+      navigationRef.current?.teardown();
     };
   }, []);
   const setActiveId = nextActiveId => {
@@ -147,68 +235,112 @@ export function useScrollSpy({
     }
     onActiveIdChange?.(nextActiveId);
   };
-  const lockActiveId = useCallback(clickedId => {
-    if (typeof window === 'undefined') {
-      setUncontrolledActiveId(clickedId);
-      activeIdRef.current = clickedId;
-      onActiveIdChangeRef.current?.(clickedId);
-      return;
+
+  // Defined in render (not memoized) so it always closes over the current props
+  // — it only ever runs from an event handler, never during render.
+  const scrollTo = id => {
+    const target = typeof document !== 'undefined' ? document.getElementById(id) : null;
+    if (target == null) {
+      return false;
     }
 
-    // Freeze the indicator during the programmatic smooth scroll instead of
-    // moving it immediately — it lands on the clicked item once the scroll
-    // settles, so it doesn't chase the scroll through intervening sections.
-    suppressRef.current = true;
-    // Replace any in-flight handlers from a previous click.
-    releaseSuppressionRef.current?.();
+    // A second navigation replaces the first: end the old one (balancing its
+    // onNavigateStart) without resuming tracking, since we are about to
+    // suppress it again anyway.
+    navigationRef.current?.supersede();
+    onNavigateStart?.(id);
+    if (isControlled) {
+      // The consumer owns the active state — notify only.
+      setActiveId(id);
+    } else {
+      // Freeze the indicator during the programmatic scroll instead of moving
+      // it immediately: it lands on the target once the scroll settles, so it
+      // doesn't chase the scroll through intervening sections.
+      suppressRef.current = true;
+    }
+    const scrollRoot = getScrollRoot();
+    const scrollTarget = scrollRoot ?? window;
     let settleTimer = 0;
+    let isSettled = false;
     const cleanup = () => {
-      window.removeEventListener('scrollend', onSettle);
-      window.removeEventListener('wheel', onManual);
-      window.removeEventListener('touchmove', onManual);
+      scrollTarget.removeEventListener('scrollend', onSettle);
+      scrollTarget.removeEventListener('wheel', onManual);
+      scrollTarget.removeEventListener('touchmove', onManual);
       window.removeEventListener('keydown', onKeyDown);
       if (settleTimer !== 0) {
         clearTimeout(settleTimer);
         settleTimer = 0;
       }
-      releaseSuppressionRef.current = null;
-    };
-    // Programmatic scroll finished: move the indicator to the clicked item.
-    const onSettle = () => {
-      cleanup();
-      suppressRef.current = false;
-      setUncontrolledActiveId(clickedId);
-      activeIdRef.current = clickedId;
-      onActiveIdChangeRef.current?.(clickedId);
+      navigationRef.current = null;
     };
-    // User scrolled mid-flight: hand control back to scroll-position tracking.
-    const onManual = () => {
+
+    /**
+     * End the navigation exactly once. `didArrive` is false when the user took
+     * over with a manual scroll mid-flight. `onNavigateEnd` fires either way,
+     * so every `onNavigateStart` is balanced and a consumer's "navigating"
+     * state can never leak.
+     */
+    const finish = (didArrive, shouldResume = true) => {
+      if (isSettled) {
+        return;
+      }
+      isSettled = true;
       cleanup();
-      suppressRef.current = false;
-      syncRef.current?.();
+      if (!isControlled) {
+        suppressRef.current = false;
+        if (didArrive) {
+          setUncontrolledActiveId(id);
+          activeIdRef.current = id;
+          onActiveIdChangeRef.current?.(id);
+        } else if (shouldResume) {
+          // Hand control back to scroll-position tracking.
+          syncRef.current?.();
+        }
+      }
+      onNavigateEnd?.(id);
     };
+    const onSettle = () => finish(true);
+    const onManual = () => finish(false);
     const onKeyDown = event => {
-      if (SCROLL_KEYS.has(event.key)) {
-        onManual();
+      // A key the outline itself consumed (arrow roving focus, Space
+      // activation) is prevented, so the browser will not scroll — it is not a
+      // manual scroll intent and must not cancel the navigation it just began.
+      if (!event.defaultPrevented && SCROLL_KEYS.has(event.key)) {
+        finish(false);
       }
     };
-    window.addEventListener('scrollend', onSettle, {
-      once: true
-    });
-    window.addEventListener('wheel', onManual, {
-      passive: true
-    });
-    window.addEventListener('touchmove', onManual, {
-      passive: true
-    });
-    window.addEventListener('keydown', onKeyDown);
-    // Fallback when scrollend is unsupported or no scroll is needed.
-    settleTimer = window.setTimeout(onSettle, 1200);
-    releaseSuppressionRef.current = cleanup;
-  }, []);
+    if (hasScrollOnClick) {
+      // Arm settle detection *before* scrolling so an instant jump (a target
+      // already in position, or prefers-reduced-motion collapsing the smooth
+      // scroll) cannot land before anyone is listening.
+      scrollTarget.addEventListener('scrollend', onSettle, {
+        once: true
+      });
+      scrollTarget.addEventListener('wheel', onManual, {
+        passive: true
+      });
+      scrollTarget.addEventListener('touchmove', onManual, {
+        passive: true
+      });
+      window.addEventListener('keydown', onKeyDown);
+      settleTimer = window.setTimeout(onSettle, SCROLL_SETTLE_TIMEOUT_MS);
+      navigationRef.current = {
+        supersede: () => finish(false, false),
+        teardown: cleanup
+      };
+      scrollToTarget(target, scrollRoot, scrollTarget, offset);
+    } else {
+      // The consumer owns scrolling — there is no scroll to wait for, so the
+      // navigation is already at rest. Resolving immediately (instead of
+      // waiting on the settle timeout) keeps onNavigateEnd usable for arrival
+      // effects even when hasScrollOnClick is false.
+      finish(true);
+    }
+    return true;
+  };
   return {
     activeId: isControlled ? activeId : uncontrolledActiveId,
     setActiveId,
-    lockActiveId
+    scrollTo
   };
 }