@astryxdesign/core 0.0.15 → 0.1.0-canary.08d4cf4

package/dist/MetadataList/MetadataList.js

@@ -21,7 +21,7 @@ import "../theme/tokens.stylex.js";
 import { spacingVars, colorVars, typeScaleVars, fontWeightVars } from "../theme/tokens.stylex.js";
 import { MetadataListContext } from "./MetadataListContext.js";
 import { mergeProps } from "../utils/index.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 
 // =============================================================================
 // Types
@@ -164,7 +164,7 @@ export function MetadataList({
     children: /*#__PURE__*/_jsxs("div", {
       ref: ref,
       "data-testid": testId,
-      ...mergeProps(xdsThemeProps('metadata-list', {
+      ...mergeProps(themeProps('metadata-list', {
         columns: String(columns),
         orientation
       }), stylex.props(styles.root, xstyle), className, style),

package/dist/MetadataList/MetadataListItem.js

@@ -21,7 +21,7 @@ import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, typeScaleVars, fontWeightVars } from "../theme/tokens.stylex.js";
 import { MetadataListContext } from "./MetadataListContext.js";
 import { mergeProps } from "../utils/index.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 
 // =============================================================================
 // Types
@@ -99,7 +99,7 @@ export function MetadataListItem({
     return /*#__PURE__*/_jsxs("div", {
       ref: ref,
       "data-testid": testId,
-      ...mergeProps(xdsThemeProps('metadata-list-item'), stylex.props(styles.stackedWrapper, xstyle), className, style),
+      ...mergeProps(themeProps('metadata-list-item'), stylex.props(styles.stackedWrapper, xstyle), className, style),
       children: [/*#__PURE__*/_jsx("dt", {
         ...{
           className: "xv1l7n4 xjm74w1 xw6l6zx x1e4wzip x78zum5 x6s0dn4 x1txdalj x1ghz6dp x1717udv"
@@ -119,7 +119,7 @@ export function MetadataListItem({
     children: [/*#__PURE__*/_jsx("dt", {
       ref: ref,
       "data-testid": testId ? `${testId}-label` : undefined,
-      ...mergeProps(xdsThemeProps('metadata-list-item'), stylex.props(styles.label, xstyle), className, style),
+      ...mergeProps(themeProps('metadata-list-item'), stylex.props(styles.label, xstyle), className, style),
       children: labelContent
     }), /*#__PURE__*/_jsx("dd", {
       "data-testid": testId ? `${testId}-value` : undefined,

package/dist/MobileNav/MobileNav.js

@@ -34,7 +34,7 @@ import { Icon } from "../Icon/index.js";
 import { Heading } from "../Heading/Heading.js";
 import { useAppShellMobile } from "../AppShell/AppShellMobileContext.js";
 import { mergeProps, mergeRefs } from "../utils/index.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 
 // =============================================================================
 // Styles
@@ -259,7 +259,7 @@ export function MobileNav({
     "aria-label": label ?? (typeof header === 'string' ? header : 'Navigation'),
     onClick: handleDialogClick,
     onCancel: handleCancel,
-    ...mergeProps(xdsThemeProps('mobile-nav', {
+    ...mergeProps(themeProps('mobile-nav', {
       side: resolvedSide
     }), stylex.props(styles.dialog, isOpen && styles.open, styles.backdrop, isOpen && styles.backdropOpen, xstyle)),
     children: /*#__PURE__*/_jsxs("div", {

package/dist/MultiSelector/MultiSelector.js

@@ -28,7 +28,7 @@ import { isOptionData, isDivider, isSection, normalizeOption, getSelectableOptio
 import { useMultiCombobox } from "./hooks.js";
 import { mergeProps } from "../utils/index.js";
 import { useSize } from "../SizeContext/SizeContext.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 
 // Sentinel value for the select-all item in keyboard navigation
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -636,7 +636,7 @@ export function MultiSelector({
       },
       onClick: onTriggerClick,
       "data-testid": testId,
-      ...mergeProps(xdsThemeProps('multi-selector', {
+      ...mergeProps(themeProps('multi-selector', {
         size,
         status: status?.type ?? null
       }), stylex.props(inputWrapperStyles.base, styles.triggerContainer, sizeStyles[size], isDisabled && inputWrapperStyles.disabled, optimisticValue.length === 0 && styles.triggerPlaceholder, status && inputStatusBorderStyles[status.type], status && inputStatusHoverShadowStyles[status.type], xstyle), className, style),

package/dist/NavIcon/NavIcon.js

@@ -18,7 +18,7 @@ import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, sizeVars } from "../theme/tokens.stylex.js";
 import { mergeProps } from "../utils/index.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 
 /**
  * NavIcon styles
@@ -67,7 +67,7 @@ export function NavIcon({
 }) {
   return /*#__PURE__*/_jsx("span", {
     ref: ref,
-    ...mergeProps(xdsThemeProps('navicon'), stylex.props(styles.base, xstyle), className, style),
+    ...mergeProps(themeProps('navicon'), stylex.props(styles.base, xstyle), className, style),
     ...props,
     children: icon
   });

package/dist/NavMenu/NavHeadingMenu.js

@@ -17,7 +17,7 @@ import "../theme/tokens.stylex.js";
 import { spacingVars } from "../theme/tokens.stylex.js";
 import { mergeProps, mergeRefs } from "../utils/index.js";
 import { useListFocus } from "../hooks/useListFocus.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 import { NavHeadingMenuContext, useNavHeadingCloseContext } from "./NavMenuContext.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 const styles = {
@@ -98,7 +98,7 @@ export function NavHeadingMenu({
       role: "menu",
       onKeyDown: handleKeyDown,
       "data-testid": testId,
-      ...mergeProps(xdsThemeProps('nav-heading-menu', {
+      ...mergeProps(themeProps('nav-heading-menu', {
         size
       }), stylex.props(styles.root, sizeStyles[size], xstyle), className, inlineStyle),
       children: children

package/dist/NavMenu/NavHeadingMenuItem.js

@@ -20,7 +20,7 @@ import { colorVars, spacingVars, typographyVars, typeScaleVars, radiusVars } fro
 import { mergeProps } from "../utils/index.js";
 import { useNavHeadingMenuContext } from "./NavMenuContext.js";
 import { useLinkComponent } from "../Link/useLinkComponent.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const styles = {
   root: {
@@ -110,7 +110,7 @@ export function NavHeadingMenuItem({
     href: href,
     onClick: handleClick,
     "data-testid": testId,
-    ...mergeProps(xdsThemeProps('nav-heading-menu-item', {
+    ...mergeProps(themeProps('nav-heading-menu-item', {
       size
     }), stylex.props(styles.root, sizeStyles[size], isDisabled && styles.disabled, xstyle), className, style),
     children: [icon && renderIconSlot(icon, {

package/dist/NumberInput/NumberInput.js

@@ -49,7 +49,7 @@ import { groupStyles } from "../InputGroup/groupStyles.js";
 // Re-export shared types for convenience
 
 import { mergeProps, mergeRefs } from "../utils/index.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 
 /**
  * Without `hasClear`, onChange only receives valid numbers.
@@ -258,7 +258,7 @@ export function NumberInput({
     ref: containerRef,
     onClick: handleWrapperClick,
     onMouseUp: handleWrapperMouseUp,
-    ...mergeProps(xdsThemeProps('number-input', {
+    ...mergeProps(themeProps('number-input', {
       size,
       status: status?.type ?? null
     }), stylex.props(inputWrapperStyles.base, styles.wrapper, sizeStyles[size], isDisabled && inputWrapperStyles.disabled, status && inputStatusBorderStyles[status.type], status && inputStatusHoverShadowStyles[status.type], status && inputStatusFocusWithinStyles[status.type], inputGroup && groupStyles.inGroup, xstyle), className, style),

package/dist/Outline/Outline.d.ts

@@ -29,8 +29,9 @@ export interface OutlineProps extends BaseProps<HTMLElement> {
  * indentation based on each heading level. Features a sliding indicator
  * track that animates to the active item.
  *
- * When `activeId` is omitted, it observes heading elements by id and marks
- * the topmost visible heading active.
+ * 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.
  *
  * @example
  * ```

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;AAGzC,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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CAAC,EACtB,KAAK,EACL,QAAQ,EACR,gBAAgB,EAChB,KAA2B,EAC3B,OAAmB,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,YAAY,+BAuFd;yBAnGe,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;AAGzC,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,KAA2B,EAC3B,OAAmB,EACnB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,YAAY,+BAyGd;yBArHe,OAAO"}

package/dist/Outline/Outline.js

@@ -26,7 +26,7 @@ import { colorVars, durationVars, easeVars, radiusVars, spacingVars, typeScaleVa
 import { useLinkComponent } from "../Link/useLinkComponent.js";
 import { mergeProps, mergeRefs } from "../utils/index.js";
 import { useScrollSpy } from "./useScrollSpy.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // =============================================================================
 // Styles
@@ -133,8 +133,9 @@ function getIndentStyle(level) {
  * indentation based on each heading level. Features a sliding indicator
  * track that animates to the active item.
  *
- * When `activeId` is omitted, it observes heading elements by id and marks
- * the topmost visible heading active.
+ * 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.
  *
  * @example
  * ```
@@ -162,7 +163,12 @@ export function Outline({
 }) {
   const rootRef = useRef(null);
   const LinkComponent = useLinkComponent();
-  const [resolvedActiveId, setActiveId] = useScrollSpy({
+  const isControlled = activeId !== undefined;
+  const {
+    activeId: resolvedActiveId,
+    setActiveId,
+    lockActiveId
+  } = useScrollSpy({
     activeId,
     items,
     onActiveIdChange,
@@ -170,12 +176,25 @@ export function Outline({
   });
   const handleClick = id => event => {
     const target = document.getElementById(id);
-    setActiveId(id);
+
+    // 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;
     }
     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);
+    }
     target.scrollIntoView({
       behavior: 'smooth',
       block: 'start'
@@ -186,7 +205,7 @@ export function Outline({
     ref: mergeRefs(rootRef, ref),
     "aria-label": label,
     "data-testid": testId,
-    ...mergeProps(xdsThemeProps('outline', {
+    ...mergeProps(themeProps('outline', {
       density
     }), stylex.props(styles.root, xstyle), className, style),
     children: [/*#__PURE__*/_jsx("ul", {
@@ -205,7 +224,7 @@ export function Outline({
             href: `#${item.id}`,
             "aria-current": isActive ? 'true' : undefined,
             onClick: handleClick(item.id),
-            ...mergeProps(xdsThemeProps('outline-item', {
+            ...mergeProps(themeProps('outline-item', {
               active: isActive ? 'active' : null,
               level: item.level
             }), stylex.props(styles.link, densityStyles[density], getIndentStyle(item.level), isActive && styles.activeLink, isActive && styles.activeAnchor)),
@@ -229,7 +248,7 @@ export function Outline({
         }
       })
     }), /*#__PURE__*/_jsx("span", {
-      ...mergeProps(xdsThemeProps('outline-indicator'), {
+      ...mergeProps(themeProps('outline-indicator'), {
         className: "x10l6tqk x1o0tod xfo62xy xowkcby xjspbzw x47corl x1vjfegm x1tsffl5 x1ltwjim x1qjb5ga x1xuz8iz xkvfbh3 xlr8y92"
       }),
       "aria-hidden": "true"

package/dist/Outline/useScrollSpy.d.ts

@@ -5,6 +5,19 @@ interface UseScrollSpyOptions {
     onActiveIdChange?: (id: string) => void;
     rootRef: React.RefObject<HTMLElement | null>;
 }
-export declare function useScrollSpy({ activeId, items, onActiveIdChange, rootRef, }: UseScrollSpyOptions): [string | undefined, (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.
+     */
+    lockActiveId: (id: string) => void;
+}
+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":"AAcA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,SAAS,CAAC;AAwBzC,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,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,KAAK,EACL,gBAAgB,EAChB,OAAO,GACR,EAAE,mBAAmB,GAAG,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC,CA2FlE"}
+{"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"}

package/dist/Outline/useScrollSpy.js

@@ -4,13 +4,23 @@
 
 /**
  * @file useScrollSpy.ts
- * @input Uses React, IntersectionObserver, OutlineItem type
+ * @input Uses React, scroll position of heading elements, OutlineItem type
  * @output Exports internal useScrollSpy hook
  * @position Internal behavior hook; consumed by Outline.tsx
  *
+ * 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.
+ *
  * SYNC: When modified, update /packages/core/src/Outline/Outline.tsx
  */
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/** 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) {
   let current = element?.parentElement ?? null;
   while (current != null) {
@@ -24,6 +34,41 @@ function getScrollableAncestor(element) {
   }
   return null;
 }
+
+/**
+ * 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.
+ */
+function resolveActiveId(items, scrollRoot) {
+  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;
+  }
+  let activeId = items[0].id;
+  for (const item of items) {
+    const element = document.getElementById(item.id);
+    if (element == null) {
+      continue;
+    }
+    const top = element.getBoundingClientRect().top;
+    const marginTop = Number.parseFloat(window.getComputedStyle(element).scrollMarginTop) || 0;
+    if (top <= rootTop + marginTop + 1) {
+      activeId = item.id;
+    } else {
+      break;
+    }
+  }
+  return activeId;
+}
 export function useScrollSpy({
   activeId,
   items,
@@ -32,72 +77,138 @@ export function useScrollSpy({
 }) {
   const isControlled = activeId !== undefined;
   const [uncontrolledActiveId, setUncontrolledActiveId] = useState(items[0]?.id);
-  const visibleHeadingIdsRef = useRef(new Set());
-  const headingTopRef = useRef(new Map());
   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.
+  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.
+  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).
+  const itemsRef = useRef(items);
+  itemsRef.current = items;
+  const onActiveIdChangeRef = useRef(onActiveIdChange);
+  onActiveIdChangeRef.current = onActiveIdChange;
   const itemIds = items.map(item => item.id).join('\n');
   activeIdRef.current = isControlled ? activeId : uncontrolledActiveId;
   useEffect(() => {
-    if (isControlled || typeof IntersectionObserver === 'undefined') {
-      return;
-    }
-    const headingElements = items.map(item => document.getElementById(item.id)).filter(element => element != null);
-    if (headingElements.length === 0) {
+    if (isControlled || typeof window === 'undefined') {
       return;
     }
-    const visibleHeadingIds = visibleHeadingIdsRef.current;
-    const headingTop = headingTopRef.current;
-    const setNextActiveId = nextActiveId => {
-      if (activeIdRef.current === nextActiveId) {
+    const scrollRoot = getScrollableAncestor(rootRef.current);
+    const scrollTarget = scrollRoot ?? window;
+    let frame = 0;
+    const update = () => {
+      frame = 0;
+      if (suppressRef.current) {
         return;
       }
-      activeIdRef.current = nextActiveId;
-      setUncontrolledActiveId(nextActiveId);
-      onActiveIdChange?.(nextActiveId);
-    };
-    const chooseActiveHeading = () => {
-      let nextActiveId;
-      let nextTop = Number.POSITIVE_INFINITY;
-      for (const id of visibleHeadingIds) {
-        const top = headingTop.get(id) ?? Number.POSITIVE_INFINITY;
-        if (top < nextTop) {
-          nextTop = top;
-          nextActiveId = id;
-        }
-      }
-      if (nextActiveId != null) {
-        setNextActiveId(nextActiveId);
+      const nextActiveId = resolveActiveId(itemsRef.current, scrollRoot);
+      if (nextActiveId != null && nextActiveId !== activeIdRef.current) {
+        activeIdRef.current = nextActiveId;
+        setUncontrolledActiveId(nextActiveId);
+        onActiveIdChangeRef.current?.(nextActiveId);
       }
     };
-    const observer = new IntersectionObserver(entries => {
-      for (const entry of entries) {
-        const id = entry.target.id;
-        headingTop.set(id, entry.boundingClientRect.top);
-        if (entry.isIntersecting) {
-          visibleHeadingIds.add(id);
-        } else {
-          visibleHeadingIds.delete(id);
-        }
+    const onScroll = () => {
+      if (frame === 0) {
+        frame = requestAnimationFrame(update);
       }
-      chooseActiveHeading();
-    }, {
-      root: getScrollableAncestor(rootRef.current),
-      threshold: 0
+    };
+    syncRef.current = update;
+    update();
+    scrollTarget.addEventListener('scroll', onScroll, {
+      passive: true
+    });
+    window.addEventListener('resize', onScroll, {
+      passive: true
     });
-    for (const headingElement of headingElements) {
-      observer.observe(headingElement);
-    }
     return () => {
-      observer.disconnect();
-      visibleHeadingIds.clear();
-      headingTop.clear();
+      syncRef.current = null;
+      scrollTarget.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', onScroll);
+      if (frame !== 0) {
+        cancelAnimationFrame(frame);
+      }
+    };
+  }, [isControlled, itemIds, rootRef]);
+
+  // Tear down any pending suppression listeners when the Outline unmounts.
+  useEffect(() => {
+    return () => {
+      releaseSuppressionRef.current?.();
     };
-  }, [isControlled, itemIds, items, onActiveIdChange, rootRef]);
+  }, []);
   const setActiveId = nextActiveId => {
     if (!isControlled) {
       setUncontrolledActiveId(nextActiveId);
     }
     onActiveIdChange?.(nextActiveId);
   };
-  return [isControlled ? activeId : uncontrolledActiveId, setActiveId];
+  const lockActiveId = useCallback(clickedId => {
+    if (typeof window === 'undefined') {
+      setUncontrolledActiveId(clickedId);
+      activeIdRef.current = clickedId;
+      onActiveIdChangeRef.current?.(clickedId);
+      return;
+    }
+
+    // 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?.();
+    let settleTimer = 0;
+    const cleanup = () => {
+      window.removeEventListener('scrollend', onSettle);
+      window.removeEventListener('wheel', onManual);
+      window.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);
+    };
+    // User scrolled mid-flight: hand control back to scroll-position tracking.
+    const onManual = () => {
+      cleanup();
+      suppressRef.current = false;
+      syncRef.current?.();
+    };
+    const onKeyDown = event => {
+      if (SCROLL_KEYS.has(event.key)) {
+        onManual();
+      }
+    };
+    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;
+  }, []);
+  return {
+    activeId: isControlled ? activeId : uncontrolledActiveId,
+    setActiveId,
+    lockActiveId
+  };
 }

package/dist/OverflowList/OverflowList.js

@@ -22,7 +22,7 @@ import { mergeProps, mergeRefs } from "../utils/index.js";
 import { useOverflow } from "../hooks/useOverflow.js";
 import "../theme/tokens.stylex.js";
 import { spacingVars } from "../theme/tokens.stylex.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const styles = {
   container: {
@@ -192,7 +192,7 @@ export function OverflowList({
       })]
     }), /*#__PURE__*/_jsxs("div", {
       ref: mergeRefs(ref, containerRef),
-      ...mergeProps(xdsThemeProps('overflow-list'), stylex.props(styles.container, gapStyles[gap], observeParent && hasOverflow && styles.fillParent, xstyle), className, style),
+      ...mergeProps(themeProps('overflow-list'), stylex.props(styles.container, gapStyles[gap], observeParent && hasOverflow && styles.fillParent, xstyle), className, style),
       ...props,
       children: [collapseFrom === 'start' && hasOverflow && overflowRenderer?.(overflowItems), visibleItems.map(({
         child

package/dist/Overlay/Overlay.js

@@ -19,7 +19,7 @@ import { mergeProps, mergeRefs } from "../utils/index.js";
 import { useOverlay } from "./useOverlay.js";
 import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
 import { overlayScope, overlayContainerStyles } from "./overlay.markers.stylex.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 import { jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * Overlay — renders content on top of media with a scrim background
@@ -81,7 +81,7 @@ export function Overlay({
   }, []);
   return /*#__PURE__*/_jsxs("div", {
     ref: mergeRefs(ref, overlay.containerRef),
-    ...mergeProps(xdsThemeProps('overlay'), stylex.props(overlayScope, overlayContainerStyles.root, xstyle), className, style),
+    ...mergeProps(themeProps('overlay'), stylex.props(overlayScope, overlayContainerStyles.root, xstyle), className, style),
     onClick: overlay.containerProps.onClick,
     onMouseUp: overlay.containerProps.onMouseUp,
     children: [children, overlay.element]

package/dist/Overlay/OverlayScrim.js

@@ -18,7 +18,7 @@ import { MediaTheme } from "../theme/MediaTheme.js";
 import { mergeProps } from "../utils/index.js";
 import "./overlay.markers.stylex.js";
 import { overlayScope } from "./overlay.markers.stylex.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 
 // =============================================================================
 // Types (re-exported from index.ts for consumers)
@@ -220,7 +220,7 @@ export function OverlayScrim({
   }) : children;
   const visibility = isControlled ? getControlledVisibility(isOpen, position) : getShowOnVisibility(showOn, position);
   return /*#__PURE__*/_jsx("div", {
-    ...mergeProps(xdsThemeProps('overlay-scrim', {
+    ...mergeProps(themeProps('overlay-scrim', {
       position
     }), stylex.props(styles.base, positionMap[position], alignMap[align], scrim === 'dark' && styles.scrimDark, scrim === 'light' && styles.scrimLight, visibility.base, visibility.bottom, visibility.top)),
     inert: isControlled && !isOpen ? true : undefined,

package/dist/Pagination/Pagination.js

@@ -27,7 +27,7 @@ import { Icon } from "../Icon/index.js";
 import { Selector } from "../Selector/index.js";
 import { Text } from "../Text/index.js";
 import { mergeProps } from "../utils/index.js";
-import { xdsThemeProps } from "../utils/xdsThemeProps.js";
+import { themeProps } from "../utils/themeProps.js";
 
 // =============================================================================
 // Types
@@ -319,7 +319,7 @@ export function Pagination({
               "aria-current": i + 1 === page ? 'page' : undefined,
               onClick: () => handlePageChange(i + 1),
               disabled: isDisabled,
-              ...mergeProps(xdsThemeProps('pagination-dot', {
+              ...mergeProps(themeProps('pagination-dot', {
                 active: i + 1 === page ? 'active' : null,
                 size
               }), {
@@ -360,7 +360,7 @@ export function Pagination({
     ref: ref,
     "aria-label": label,
     "data-testid": testId,
-    ...mergeProps(xdsThemeProps('pagination', {
+    ...mergeProps(themeProps('pagination', {
       variant,
       size
     }), stylex.props(styles.root, xstyle), className, style),