@astryxdesign/core 0.1.7-canary.eb8e07b → 0.1.7-canary.fb9c68c

package/README.md

@@ -2,7 +2,14 @@
 
 Core UI components, theme system, and utilities for the Astryx design system. For project setup, see [Quick Start](#quick-start) below.
 
-> **Building with an AI agent?** Run **`npx astryx init`** first. It installs the Astryx CLI's component index into your `AGENTS.md`/`CLAUDE.md` so your agent discovers components, templates, and design tokens instead of guessing. Without it, agents can't see the CLI — see [XDS CLI](#xds-cli).
+> **Building with an AI agent?** Add the CLI, then run `init`:
+>
+> ```bash
+> npm install -D @astryxdesign/cli   # or: pnpm add -D / yarn add -D / bun add -d
+> npx astryx init                    # resolves to the CLI you just installed
+> ```
+>
+> `init` writes the Astryx component index into your `AGENTS.md`/`CLAUDE.md` so your agent discovers components, templates, and design tokens instead of guessing. Need a single command without installing? Use the scoped package directly — `npx @astryxdesign/cli <cmd>` (or `pnpm dlx`/`bunx @astryxdesign/cli`). Bare `npx astryx` only works once `@astryxdesign/cli` is a dependency; before that npm resolves it to an unrelated package. See [XDS CLI](#xds-cli).
 
 ## Component Docs
 
@@ -25,9 +32,9 @@ global navigation.
 Requires `@astryxdesign/cli` (`npm install -D @astryxdesign/cli`):
 
 ```bash
-npx astryx template --list              # browse all page and block templates
-npx astryx template dashboard           # emit full page source
-npx astryx template settings --skeleton # layout skeleton with spatial annotations
+astryx template --list              # browse all page and block templates
+astryx template dashboard           # emit full page source
+astryx template settings --skeleton # layout skeleton with spatial annotations
 ```
 
 ## Astryx CLI
@@ -35,19 +42,21 @@ npx astryx template settings --skeleton # layout skeleton with spatial annotatio
 The CLI (`@astryxdesign/cli`) provides additional tooling:
 
 ```bash
-npx astryx --help                       # full listing of all commands
-npx astryx component Button             # full docs + related block templates
-npx astryx docs                         # reference docs (principles, tokens, theming, styling)
-npx astryx docs theme                   # theming guide (Theme, defineTheme, light/dark)
-npx astryx docs tokens                  # spacing, color, radius, typography token reference
-npx astryx init                         # initialize Astryx in your project
-npx astryx theme build                  # build theme CSS for production
-npx astryx swizzle Button               # eject component source for customization
-npx astryx upgrade --apply              # run codemods to migrate between versions
-npx astryx discover                     # discover external Astryx packages
-npx astryx gap-report                   # report a missing capability
+astryx --help                       # full listing of all commands
+astryx component Button             # full docs + related block templates
+astryx docs                         # reference docs (principles, tokens, theming, styling)
+astryx docs theme                   # theming guide (Theme, defineTheme, light/dark)
+astryx docs tokens                  # spacing, color, radius, typography token reference
+astryx init                         # initialize Astryx in your project
+astryx theme build                  # build theme CSS for production
+astryx swizzle Button               # eject component source for customization
+astryx upgrade --apply              # run codemods to migrate between versions
+astryx discover                     # discover external Astryx packages
+astryx gap-report                   # report a missing capability
 ```
 
+> Prefix these with your runner: `npx astryx …` / `pnpm exec astryx …` once the CLI is installed, or `npx @astryxdesign/cli …` to run without installing.
+
 ## Related Packages
 
 | Package                                                                                               | Description                                                   |

package/dist/Collapsible/Collapsible.d.ts

@@ -45,6 +45,16 @@ export interface CollapsibleProps extends BaseProps {
      * Controlled open state. When provided, the component is fully controlled.
      */
     isOpen?: boolean;
+    /**
+     * Whether the collapsible is disabled. A disabled item can't be toggled —
+     * its trigger is non-interactive and dimmed. Following the system-wide
+     * disabled convention, the trigger uses `aria-disabled` (not the native
+     * `disabled` attribute) and drops out of the tab order, staying perceivable
+     * to assistive tech. The content stays in whatever open state it was;
+     * disabling doesn't collapse an already-open item.
+     * @default false
+     */
+    isDisabled?: boolean;
     /**
      * Callback when the open state changes.
      */
@@ -96,7 +106,7 @@ export interface CollapsibleProps extends BaseProps {
  * </CollapsibleGroup>
  * ```
  */
-export declare function Collapsible({ trigger, children, defaultIsOpen, isOpen: controlledIsOpen, onOpenChange, value, ref, xstyle, className, style, ...props }: CollapsibleProps): import("react").JSX.Element;
+export declare function Collapsible({ trigger, children, defaultIsOpen, isOpen: controlledIsOpen, isDisabled, onOpenChange, value, ref, xstyle, className, style, ...props }: CollapsibleProps): import("react").JSX.Element;
 export declare namespace Collapsible {
     var displayName: string;
 }

package/dist/Collapsible/Collapsible.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Collapsible.d.ts","sourceRoot":"","sources":["../../src/Collapsible/Collapsible.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAa,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAgBjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAkG5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,QAAQ,EACR,aAAa,EACb,MAAM,EAAE,gBAAgB,EACxB,YAAY,EACZ,KAAK,EACL,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,gBAAgB,+BAqElB;yBAjFe,WAAW"}
+{"version":3,"file":"Collapsible.d.ts","sourceRoot":"","sources":["../../src/Collapsible/Collapsible.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAa,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAiBjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAkH5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,QAAQ,EACR,aAAa,EACb,MAAM,EAAE,gBAAgB,EACxB,UAAkB,EAClB,YAAY,EACZ,KAAK,EACL,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,gBAAgB,+BA6FlB;yBA1Ge,WAAW"}

package/dist/Collapsible/Collapsible.js

@@ -58,12 +58,22 @@ const styles = {
     kInvED: "x1wfwxd8 x7s97pk",
     $$css: true
   },
+  triggerDisabled: {
+    kkrTdU: "x1h6gzvc",
+    kSiTet: "xbyyjgo",
+    $$css: true
+  },
   contentHidden: {
     k1xSpc: "x1s85apg",
     $$css: true
   },
   content: {
     kLKAdn: "xfsso4q",
+    kMv6JI: "x9ynric",
+    kGuDYH: "xjm74w1",
+    k63SB2: "xxovm9e",
+    kLWn49: "xw6l6zx",
+    kMwMTN: "x1tgivj0",
     $$css: true
   },
   divided: {
@@ -155,6 +165,7 @@ export function Collapsible({
   children,
   defaultIsOpen,
   isOpen: controlledIsOpen,
+  isDisabled = false,
   onOpenChange,
   value,
   ref,
@@ -178,6 +189,17 @@ export function Collapsible({
     isCollapsible: collapsibleConfig,
     value
   });
+
+  // Activation is blocked by this guard rather than the native `disabled`
+  // attribute, so the trigger keeps `aria-disabled` semantics and stays
+  // discoverable. A native `disabled` button would silently swallow events
+  // (e.g. a wrapping tooltip's hover) — the system-wide disabled convention.
+  const handleToggle = () => {
+    if (isDisabled) {
+      return;
+    }
+    toggle();
+  };
   const presentation = use(CollapsibleGroupPresentationContext);
   const isDivided = presentation?.hasDividers ?? false;
   const density = presentation?.density ?? null;
@@ -194,10 +216,18 @@ export function Collapsible({
     ...props,
     children: [/*#__PURE__*/_jsxs("button", {
       type: "button",
-      onClick: toggle,
+      onClick: handleToggle,
+      "aria-disabled": isDisabled || undefined,
       "aria-expanded": isOpen,
-      "aria-controls": contentId,
-      ...stylex.props(styles.trigger, density != null && triggerDensity[density]),
+      "aria-controls": contentId
+      // A disabled trigger drops out of the tab order so it isn't a silently
+      // dead tab stop; activation stays blocked by the handleToggle guard,
+      // and aria-disabled keeps the state perceivable to assistive tech —
+      // the system-wide disabled convention (never native `disabled`, which
+      // would swallow events like a wrapping tooltip's hover).
+      ,
+      tabIndex: isDisabled ? -1 : undefined,
+      ...stylex.props(styles.trigger, density != null && triggerDensity[density], isDisabled && styles.triggerDisabled),
       children: [/*#__PURE__*/_jsx("span", {
         ...{
           className: "x1b2iylo xwgcxoh"
@@ -216,7 +246,9 @@ export function Collapsible({
       })]
     }), /*#__PURE__*/_jsx("div", {
       id: contentId,
-      ...stylex.props(styles.content, density != null && contentDensity[density], !isOpen && styles.contentHidden),
+      ...mergeProps(themeProps('collapsible-content', {
+        density: density ?? undefined
+      }), stylex.props(styles.content, density != null && contentDensity[density], !isOpen && styles.contentHidden)),
       children: presentation != null ? /*#__PURE__*/_jsx(CollapsibleGroupPresentationContext, {
         value: null,
         children: children

package/dist/Outline/Outline.d.ts

@@ -19,6 +19,50 @@ export interface OutlineProps extends BaseProps<HTMLElement> {
      * @default 'default'
      */
     density?: 'default' | 'compact';
+    /**
+     * Called when navigation to an item begins, before the scroll starts.
+     * Receives the item `id`. Pair with `onNavigateEnd` to drive an arrival
+     * effect (flash, ring, pulse) on the target heading.
+     */
+    onNavigateStart?: (id: string) => void;
+    /**
+     * Called once when navigation to an item resolves — when the smooth scroll
+     * settles, or immediately-ish when reduced motion turns it into a jump.
+     *
+     * Fires exactly once for every `onNavigateStart`, including when the user
+     * interrupts the scroll by scrolling manually, so a "navigating" state can
+     * never leak. It does not fire if the Outline unmounts mid-scroll.
+     */
+    onNavigateEnd?: (id: string) => void;
+    /**
+     * 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, so a heading activates exactly where navigating to it puts it —
+     * below the header rather than hidden underneath it.
+     *
+     * It composes with each heading's own `scroll-margin-top` (the header, then
+     * the breathing room below it) rather than replacing it. When nothing
+     * overlays the content, leave this at 0 and let `scroll-margin-top` do the
+     * work — the browser already honors it.
+     *
+     * @default 0
+     */
+    offset?: number;
+    /**
+     * Scroll container to track, instead of auto-detecting the nearest scrollable
+     * ancestor. Use this when the content scrolls inside a split pane, modal, or
+     * dashboard panel rather than the viewport.
+     */
+    scrollContainerRef?: React.RefObject<HTMLElement | null>;
+    /**
+     * Whether activating an item smooth-scrolls to it. Set to false to own the
+     * scrolling yourself (virtualized content, a router) — the Outline still
+     * updates the active item, the hash, and the navigate callbacks, but performs
+     * no scroll and suppresses the anchor's default jump.
+     * @default true
+     */
+    hasScrollOnClick?: boolean;
     /** Test ID for testing frameworks. */
     'data-testid'?: string;
 }
@@ -30,8 +74,15 @@ export interface OutlineProps extends BaseProps<HTMLElement> {
  * 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
  * ```
@@ -43,8 +94,23 @@ export interface OutlineProps extends BaseProps<HTMLElement> {
  *   ]}
  * />
  * ```
+ *
+ * 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 declare function Outline({ items, activeId, onActiveIdChange, label: labelFromProps, density, xstyle, className, style, ref, 'data-testid': testId, ...props }: OutlineProps): import("react").JSX.Element;
+export declare function Outline({ items, activeId, onActiveIdChange, label: labelFromProps, density, onNavigateStart, onNavigateEnd, offset, scrollContainerRef, hasScrollOnClick, xstyle, className, style, ref, 'data-testid': testId, ...props }: OutlineProps): import("react").JSX.Element;
 export declare namespace Outline {
     var displayName: string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"Outline.d.ts","sourceRoot":"","sources":["../../src/Outline/Outline.tsx"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAIzC,YAAY,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAEzC,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC1D,6CAA6C;IAC7C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B,+CAA+C;IAC/C,KAAK,EAAE,WAAW,EAAE,CAAC;IAErB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAEhC,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAgJD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,QAAQ,EACR,gBAAgB,EAChB,KAAK,EAAE,cAAc,EACrB,OAAmB,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,YAAY,+BA2Gd;yBAvHe,OAAO"}
+{"version":3,"file":"Outline.d.ts","sourceRoot":"","sources":["../../src/Outline/Outline.tsx"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAIzC,YAAY,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAEzC,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC1D,6CAA6C;IAC7C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B,+CAA+C;IAC/C,KAAK,EAAE,WAAW,EAAE,CAAC;IAErB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAEhC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAEvC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAErC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEzD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAgJD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,QAAQ,EACR,gBAAgB,EAChB,KAAK,EAAE,cAAc,EACrB,OAAmB,EACnB,eAAe,EACf,aAAa,EACb,MAAU,EACV,kBAAkB,EAClB,gBAAuB,EACvB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,YAAY,+BAiLd;yBAlMe,OAAO"}

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,21 @@ 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 +182,11 @@ export function Outline({
   onActiveIdChange,
   label: labelFromProps,
   density = 'default',
+  onNavigateStart,
+  onNavigateEnd,
+  offset = 0,
+  scrollContainerRef,
+  hasScrollOnClick = true,
   xstyle,
   className,
   style,
@@ -166,42 +198,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 +314,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 +329,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"}