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

package/README.md

@@ -2,14 +2,7 @@
 
 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?** 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).
+> **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).
 
 ## Component Docs
 
@@ -32,9 +25,9 @@ global navigation.
 Requires `@astryxdesign/cli` (`npm install -D @astryxdesign/cli`):
 
 ```bash
-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
+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 CLI
@@ -42,21 +35,19 @@ astryx template settings --skeleton # layout skeleton with spatial annotations
 The CLI (`@astryxdesign/cli`) provides additional tooling:
 
 ```bash
-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
+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
 ```
 
-> 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,16 +45,6 @@ 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.
      */
@@ -106,7 +96,7 @@ export interface CollapsibleProps extends BaseProps {
  * </CollapsibleGroup>
  * ```
  */
-export declare function Collapsible({ trigger, children, defaultIsOpen, isOpen: controlledIsOpen, isDisabled, onOpenChange, value, ref, xstyle, className, style, ...props }: CollapsibleProps): import("react").JSX.Element;
+export declare function Collapsible({ trigger, children, defaultIsOpen, isOpen: controlledIsOpen, 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;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"}
+{"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"}

package/dist/Collapsible/Collapsible.js

@@ -58,22 +58,12 @@ 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: {
@@ -165,7 +155,6 @@ export function Collapsible({
   children,
   defaultIsOpen,
   isOpen: controlledIsOpen,
-  isDisabled = false,
   onOpenChange,
   value,
   ref,
@@ -189,17 +178,6 @@ 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;
@@ -216,18 +194,10 @@ export function Collapsible({
     ...props,
     children: [/*#__PURE__*/_jsxs("button", {
       type: "button",
-      onClick: handleToggle,
-      "aria-disabled": isDisabled || undefined,
+      onClick: toggle,
       "aria-expanded": isOpen,
-      "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),
+      "aria-controls": contentId,
+      ...stylex.props(styles.trigger, density != null && triggerDensity[density]),
       children: [/*#__PURE__*/_jsx("span", {
         ...{
           className: "x1b2iylo xwgcxoh"
@@ -246,9 +216,7 @@ export function Collapsible({
       })]
     }), /*#__PURE__*/_jsx("div", {
       id: contentId,
-      ...mergeProps(themeProps('collapsible-content', {
-        density: density ?? undefined
-      }), stylex.props(styles.content, density != null && contentDensity[density], !isOpen && styles.contentHidden)),
+      ...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,50 +19,6 @@ 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;
 }
@@ -74,15 +30,8 @@ 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 — 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.
+ * 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.
  *
  * @example
  * ```
@@ -94,23 +43,8 @@ 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, onNavigateStart, onNavigateEnd, offset, scrollContainerRef, hasScrollOnClick, xstyle, className, style, ref, 'data-testid': testId, ...props }: OutlineProps): import("react").JSX.Element;
+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 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":"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"}
+{"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"}

package/dist/Outline/Outline.js

@@ -4,7 +4,7 @@
 
 /**
  * @file Outline.tsx
- * @input Uses React, StyleX, Astryx link provider integration, Outline hooks/types, useListFocus
+ * @input Uses React, StyleX, Astryx link provider integration, Outline hooks/types
  * @output Exports Outline component and OutlineProps type
  * @position Core implementation; consumed by index.ts
  *
@@ -12,9 +12,6 @@
  * - 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
@@ -27,8 +24,6 @@ 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";
@@ -140,15 +135,8 @@ 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 — 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.
+ * 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.
  *
  * @example
  * ```
@@ -160,21 +148,6 @@ 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,
@@ -182,11 +155,6 @@ export function Outline({
   onActiveIdChange,
   label: labelFromProps,
   density = 'default',
-  onNavigateStart,
-  onNavigateEnd,
-  offset = 0,
-  scrollContainerRef,
-  hasScrollOnClick = true,
   xstyle,
   className,
   style,
@@ -198,109 +166,42 @@ export function Outline({
   const label = labelFromProps ?? t('@astryx.outline.label');
   const rootRef = useRef(null);
   const LinkComponent = useLinkComponent();
+  const isControlled = activeId !== undefined;
   const {
     activeId: resolvedActiveId,
-    scrollTo
+    setActiveId,
+    lockActiveId
   } = useScrollSpy({
     activeId,
     items,
     onActiveIdChange,
-    rootRef,
-    offset,
-    scrollContainerRef,
-    hasScrollOnClick,
-    onNavigateStart,
-    onNavigateEnd
+    rootRef
   });
-
-  // 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 => {
-    // Let the browser handle modified clicks (open in new tab, etc.) without
-    // touching the active state.
-    if (event.defaultPrevented || hasModifier(event)) {
-      return;
-    }
+    const target = document.getElementById(id);
 
-    // 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) {
+    // 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) {
       return;
     }
-
-    // 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;
-    }
-    if (event.defaultPrevented || hasModifier(event)) {
-      return;
-    }
+    window.history.pushState(null, '', `#${id}`);
 
-    // 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);
+    // 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);
+    }
+    target.scrollIntoView({
+      behavior: 'smooth',
+      block: 'start'
+    });
   };
   return /*#__PURE__*/_jsxs("nav", {
     ...props,
@@ -314,10 +215,7 @@ 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", {
@@ -329,7 +227,6 @@ 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,40 +4,20 @@ 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;
     /**
-     * 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.
+     * 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.
      */
-    scrollTo: (id: string) => boolean;
+    lockActiveId: (id: string) => void;
 }
-export declare function useScrollSpy({ activeId, items, onActiveIdChange, rootRef, offset, scrollContainerRef, hasScrollOnClick, onNavigateStart, onNavigateEnd, }: UseScrollSpyOptions): UseScrollSpyResult;
+export declare function useScrollSpy({ activeId, items, onActiveIdChange, rootRef, }: 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":"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"}
+{"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"}