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

package/src/Outline/Outline.test.tsx

@@ -37,7 +37,13 @@ describe('parseOutlineFromMarkdown', () => {
       parseOutlineFromMarkdown(
         '## **Install** `@astryxdesign/core`\n\n```\n# Not a heading\n```',
       ),
-    ).toEqual([{id: 'install-astryxdesign-core', label: 'Install @astryxdesign/core', level: 2}]);
+    ).toEqual([
+      {
+        id: 'install-astryxdesign-core',
+        label: 'Install @astryxdesign/core',
+        level: 2,
+      },
+    ]);
   });
 
   it('deduplicates generated ids', () => {
@@ -87,7 +93,7 @@ describe('Outline', () => {
     ).not.toHaveAttribute('aria-current');
   });
 
-  it('smooth-scrolls and reports active id on click', async () => {
+  it('smooth-scrolls and defers the indicator until the scroll settles when uncontrolled', async () => {
     const user = userEvent.setup();
     const target = document.createElement('h2');
     target.id = 'install';
@@ -101,6 +107,47 @@ describe('Outline', () => {
       behavior: 'smooth',
       block: 'start',
     });
+    // Uncontrolled: the indicator is deferred during the programmatic scroll,
+    // so it has not moved to the clicked item yet.
+    expect(
+      screen.getByRole('link', {name: 'Installation'}),
+    ).not.toHaveAttribute('aria-current', 'true');
+
+    // When the scroll settles, the indicator lands on the clicked item.
+    act(() => {
+      window.dispatchEvent(new Event('scrollend'));
+    });
+    expect(onActiveIdChange).toHaveBeenCalledWith('install');
+    expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
+      'aria-current',
+      'true',
+    );
+
+    document.body.removeChild(target);
+  });
+
+  it('reports active id on click when controlled', async () => {
+    const user = userEvent.setup();
+    const target = document.createElement('h2');
+    target.id = 'install';
+    document.body.appendChild(target);
+    const onActiveIdChange = vi.fn();
+
+    render(
+      <Outline
+        items={items}
+        activeId="intro"
+        onActiveIdChange={onActiveIdChange}
+      />,
+    );
+    await user.click(screen.getByRole('link', {name: 'Installation'}));
+
+    expect(target.scrollIntoView).toHaveBeenCalledWith({
+      behavior: 'smooth',
+      block: 'start',
+    });
+    // Controlled: there is no built-in scroll-spy, so the consumer owns the
+    // active state and must be notified on click.
     expect(onActiveIdChange).toHaveBeenCalledWith('install');
 
     document.body.removeChild(target);
@@ -122,11 +169,7 @@ describe('Outline', () => {
 
   it('renders with density="compact"', () => {
     render(
-      <Outline
-        items={items}
-        density="compact"
-        data-testid="outline-compact"
-      />,
+      <Outline items={items} density="compact" data-testid="outline-compact" />,
     );
     expect(screen.getByTestId('outline-compact').className).toContain(
       'compact',
@@ -201,50 +244,45 @@ describe('Outline', () => {
     ).not.toHaveAttribute('aria-current');
   });
 
-  it('updates uncontrolled active id from IntersectionObserver', () => {
-    let observerCallback: IntersectionObserverCallback | undefined;
-
-    class MockIntersectionObserver {
-      observe = vi.fn();
-      disconnect = vi.fn();
-
-      constructor(callback: IntersectionObserverCallback) {
-        observerCallback = callback;
-      }
-    }
-
-    vi.stubGlobal('IntersectionObserver', MockIntersectionObserver);
-
+  it('updates uncontrolled active id from scroll position', () => {
     const intro = document.createElement('h2');
     intro.id = 'intro';
+    const install = document.createElement('h3');
+    install.id = 'install';
     const api = document.createElement('h3');
     api.id = 'api';
-    document.body.append(intro, api);
+    document.body.append(intro, install, api);
 
-    const onActiveIdChange = vi.fn();
-    render(<Outline items={items} onActiveIdChange={onActiveIdChange} />);
+    // Not at the bottom of the page.
+    Object.defineProperty(document.documentElement, 'scrollHeight', {
+      value: 4000,
+      configurable: true,
+    });
 
-    const entry: IntersectionObserverEntry = {
-      target: api,
-      isIntersecting: true,
-      boundingClientRect: {top: 12} as DOMRectReadOnly,
-      intersectionRatio: 1,
-      intersectionRect: {} as DOMRectReadOnly,
-      rootBounds: null,
-      time: 0,
-    };
+    // intro + install have scrolled above the activation line (top <= 0);
+    // api is still below it, so install is the last passed heading.
+    vi.spyOn(intro, 'getBoundingClientRect').mockReturnValue({
+      top: -200,
+    } as DOMRect);
+    vi.spyOn(install, 'getBoundingClientRect').mockReturnValue({
+      top: -10,
+    } as DOMRect);
+    vi.spyOn(api, 'getBoundingClientRect').mockReturnValue({
+      top: 400,
+    } as DOMRect);
 
-    act(() => {
-      observerCallback?.([entry], {} as IntersectionObserver);
-    });
+    const onActiveIdChange = vi.fn();
+    // The hook resolves the active id from scroll position on mount.
+    render(<Outline items={items} onActiveIdChange={onActiveIdChange} />);
 
-    expect(screen.getByRole('link', {name: 'API'})).toHaveAttribute(
+    expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
       'aria-current',
       'true',
     );
-    expect(onActiveIdChange).toHaveBeenCalledWith('api');
+    expect(onActiveIdChange).toHaveBeenCalledWith('install');
 
     document.body.removeChild(intro);
+    document.body.removeChild(install);
     document.body.removeChild(api);
   });
 });

package/src/Outline/Outline.tsx

@@ -36,7 +36,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useScrollSpy} from './useScrollSpy';
 import type {OutlineItem} from './types';
-import {xdsThemeProps} from '../utils/xdsThemeProps';
+import {themeProps} from '../utils/themeProps';
 
 export type {OutlineItem} from './types';
 
@@ -217,8 +217,9 @@ function getIndentStyle(level: number) {
  * 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
  * ```
@@ -246,7 +247,12 @@ export function Outline({
 }: OutlineProps) {
   const rootRef = useRef<HTMLElement | null>(null);
   const LinkComponent = useLinkComponent();
-  const [resolvedActiveId, setActiveId] = useScrollSpy({
+  const isControlled = activeId !== undefined;
+  const {
+    activeId: resolvedActiveId,
+    setActiveId,
+    lockActiveId,
+  } = useScrollSpy({
     activeId,
     items,
     onActiveIdChange,
@@ -256,8 +262,9 @@ export function Outline({
   const handleClick =
     (id: string) => (event: React.MouseEvent<HTMLElement>) => {
       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 ||
@@ -271,6 +278,18 @@ export function Outline({
 
       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'});
     };
 
@@ -281,7 +300,7 @@ export function Outline({
       aria-label={label}
       data-testid={testId}
       {...mergeProps(
-        xdsThemeProps('outline', {density}),
+        themeProps('outline', {density}),
         stylex.props(styles.root, xstyle),
         className,
         style,
@@ -297,7 +316,7 @@ export function Outline({
                 aria-current={isActive ? 'true' : undefined}
                 onClick={handleClick(item.id)}
                 {...mergeProps(
-                  xdsThemeProps('outline-item', {
+                  themeProps('outline-item', {
                     active: isActive ? 'active' : null,
                     level: item.level,
                   }),
@@ -323,7 +342,7 @@ export function Outline({
       </div>
       <span
         {...mergeProps(
-          xdsThemeProps('outline-indicator'),
+          themeProps('outline-indicator'),
           stylex.props(styles.indicator),
         )}
         aria-hidden="true"

package/src/Outline/useScrollSpy.ts

@@ -4,17 +4,39 @@
 
 /**
  * @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';
 import type {OutlineItem} from './types';
 
-function getScrollableAncestor(element: HTMLElement | null): Element | null {
+/** 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: HTMLElement | null,
+): HTMLElement | null {
   let current = element?.parentElement ?? null;
 
   while (current != null) {
@@ -36,6 +58,55 @@ function getScrollableAncestor(element: HTMLElement | null): Element | null {
   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: OutlineItem[],
+  scrollRoot: HTMLElement | null,
+): string | undefined {
+  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;
+}
+
 interface UseScrollSpyOptions {
   activeId?: string;
   items: OutlineItem[];
@@ -43,93 +114,95 @@ interface UseScrollSpyOptions {
   rootRef: React.RefObject<HTMLElement | null>;
 }
 
+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 function useScrollSpy({
   activeId,
   items,
   onActiveIdChange,
   rootRef,
-}: UseScrollSpyOptions): [string | undefined, (id: string) => void] {
+}: UseScrollSpyOptions): UseScrollSpyResult {
   const isControlled = activeId !== undefined;
   const [uncontrolledActiveId, setUncontrolledActiveId] = useState<
     string | undefined
   >(items[0]?.id);
-  const visibleHeadingIdsRef = useRef<Set<string>>(new Set());
-  const headingTopRef = useRef<Map<string, number>>(new Map());
   const activeIdRef = useRef<string | undefined>(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<(() => void) | null>(null);
+  // Latest scroll-position resolver, so the click handler can resume tracking
+  // when the user scrolls during a programmatic scroll.
+  const syncRef = useRef<(() => void) | null>(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') {
+    if (isControlled || typeof window === 'undefined') {
       return;
     }
 
-    const headingElements = items
-      .map(item => document.getElementById(item.id))
-      .filter((element): element is HTMLElement => element != null);
+    const scrollRoot = getScrollableAncestor(rootRef.current);
+    const scrollTarget: HTMLElement | Window = scrollRoot ?? window;
 
-    if (headingElements.length === 0) {
-      return;
-    }
-
-    const visibleHeadingIds = visibleHeadingIdsRef.current;
-    const headingTop = headingTopRef.current;
-
-    const setNextActiveId = (nextActiveId: string) => {
-      if (activeIdRef.current === nextActiveId) {
+    let frame = 0;
+    const update = () => {
+      frame = 0;
+      if (suppressRef.current) {
         return;
       }
-      activeIdRef.current = nextActiveId;
-      setUncontrolledActiveId(nextActiveId);
-      onActiveIdChange?.(nextActiveId);
+      const nextActiveId = resolveActiveId(itemsRef.current, scrollRoot);
+      if (nextActiveId != null && nextActiveId !== activeIdRef.current) {
+        activeIdRef.current = nextActiveId;
+        setUncontrolledActiveId(nextActiveId);
+        onActiveIdChangeRef.current?.(nextActiveId);
+      }
     };
-
-    const chooseActiveHeading = () => {
-      let nextActiveId: string | undefined;
-      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;
-        }
+    const onScroll = () => {
+      if (frame === 0) {
+        frame = requestAnimationFrame(update);
       }
+    };
+
+    syncRef.current = update;
+    update();
+    scrollTarget.addEventListener('scroll', onScroll, {passive: true});
+    window.addEventListener('resize', onScroll, {passive: true});
 
-      if (nextActiveId != null) {
-        setNextActiveId(nextActiveId);
+    return () => {
+      syncRef.current = null;
+      scrollTarget.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', onScroll);
+      if (frame !== 0) {
+        cancelAnimationFrame(frame);
       }
     };
+  }, [isControlled, itemIds, rootRef]);
 
-    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);
-          }
-        }
-        chooseActiveHeading();
-      },
-      {
-        root: getScrollableAncestor(rootRef.current),
-        threshold: 0,
-      },
-    );
-
-    for (const headingElement of headingElements) {
-      observer.observe(headingElement);
-    }
-
+  // Tear down any pending suppression listeners when the Outline unmounts.
+  useEffect(() => {
     return () => {
-      observer.disconnect();
-      visibleHeadingIds.clear();
-      headingTop.clear();
+      releaseSuppressionRef.current?.();
     };
-  }, [isControlled, itemIds, items, onActiveIdChange, rootRef]);
+  }, []);
 
   const setActiveId = (nextActiveId: string) => {
     if (!isControlled) {
@@ -138,5 +211,65 @@ export function useScrollSpy({
     onActiveIdChange?.(nextActiveId);
   };
 
-  return [isControlled ? activeId : uncontrolledActiveId, setActiveId];
+  const lockActiveId = useCallback((clickedId: string) => {
+    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: KeyboardEvent) => {
+      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/src/OverflowList/OverflowList.tsx

@@ -24,7 +24,7 @@ import * as stylex from '@stylexjs/stylex';
 import {mergeProps, mergeRefs} from '../utils';
 import {useOverflow} from '../hooks/useOverflow';
 import {spacingVars} from '../theme/tokens.stylex';
-import {xdsThemeProps} from '../utils/xdsThemeProps';
+import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
   container: {
@@ -246,7 +246,7 @@ export function OverflowList({
       <div
         ref={mergeRefs(ref, containerRef)}
         {...mergeProps(
-          xdsThemeProps('overflow-list'),
+          themeProps('overflow-list'),
           stylex.props(
             styles.container,
             gapStyles[gap],

package/src/Overlay/Overlay.tsx

@@ -21,7 +21,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {useOverlay} from './useOverlay';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {overlayScope, overlayContainerStyles} from './overlay.markers.stylex';
-import {xdsThemeProps} from '../utils/xdsThemeProps';
+import {themeProps} from '../utils/themeProps';
 import type {BaseProps} from '../BaseProps';
 import type {
   OverlayScrimMode,
@@ -115,7 +115,7 @@ export function Overlay({
     <div
       ref={mergeRefs(ref, overlay.containerRef)}
       {...mergeProps(
-        xdsThemeProps('overlay'),
+        themeProps('overlay'),
         stylex.props(overlayScope, overlayContainerStyles.root, xstyle),
         className,
         style,

package/src/Overlay/OverlayScrim.tsx

@@ -23,7 +23,7 @@ import {
 import {MediaTheme} from '../theme/MediaTheme';
 import {mergeProps} from '../utils';
 import {overlayScope} from './overlay.markers.stylex';
-import {xdsThemeProps} from '../utils/xdsThemeProps';
+import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
 // Types (re-exported from index.ts for consumers)
@@ -276,7 +276,7 @@ export function OverlayScrim({
   return (
     <div
       {...mergeProps(
-        xdsThemeProps('overlay-scrim', {position}),
+        themeProps('overlay-scrim', {position}),
         stylex.props(
           styles.base,
           positionMap[position],

package/src/Pagination/Pagination.tsx

@@ -36,7 +36,7 @@ import {Selector} from '../Selector';
 import {Text} from '../Text';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
-import {xdsThemeProps} from '../utils/xdsThemeProps';
+import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
 // Types
@@ -507,7 +507,7 @@ export function Pagination({
                 onClick={() => handlePageChange(i + 1)}
                 disabled={isDisabled}
                 {...mergeProps(
-                  xdsThemeProps('pagination-dot', {
+                  themeProps('pagination-dot', {
                     active: i + 1 === page ? 'active' : null,
                     size,
                   }),
@@ -536,7 +536,7 @@ export function Pagination({
       aria-label={label}
       data-testid={testId}
       {...mergeProps(
-        xdsThemeProps('pagination', {variant, size}),
+        themeProps('pagination', {variant, size}),
         stylex.props(styles.root, xstyle),
         className,
         style,