@astryxdesign/core 0.1.0 → 0.1.1-canary.129bf0e

package/src/Outline/Outline.tsx

@@ -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'});
     };
 

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/Pagination/Pagination.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, within} from '@testing-library/react';
+import {render, screen, within, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Pagination, generatePageRange} from './Pagination';
 
@@ -346,6 +346,140 @@ describe('Pagination', () => {
     });
   });
 
+  // ---------------------------------------------------------------------------
+  // changeAction (interruptible, optimistic)
+  // ---------------------------------------------------------------------------
+
+  describe('changeAction', () => {
+    it('fires onChange then changeAction with the new page', async () => {
+      const user = userEvent.setup();
+      const order: string[] = [];
+      const onChange = vi.fn(() => order.push('onChange'));
+      const changeAction = vi.fn(() => {
+        order.push('changeAction');
+      });
+      render(
+        <Pagination
+          page={1}
+          onChange={onChange}
+          changeAction={changeAction}
+          totalPages={5}
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      expect(onChange).toHaveBeenCalledWith(2);
+      expect(changeAction).toHaveBeenCalledWith(2);
+      expect(order).toEqual(['onChange', 'changeAction']);
+    });
+
+    it('shows the optimistic page while changeAction is pending', async () => {
+      const user = userEvent.setup();
+      let resolveAction: (() => void) | undefined;
+      const changeAction = vi.fn(
+        async () =>
+          new Promise<void>(resolve => {
+            resolveAction = resolve;
+          }),
+      );
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          changeAction={changeAction}
+          totalPages={5}
+          variant="compact"
+        />,
+      );
+
+      // The committed `page` prop stays at 1, but the indicator optimistically
+      // reflects the page being navigated to.
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      expect(changeAction).toHaveBeenCalledWith(2);
+      expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();
+
+      await act(async () => {
+        resolveAction?.();
+        await Promise.resolve();
+      });
+    });
+
+    it('interrupts an in-flight action on rapid next clicks', async () => {
+      // Each click derives its target from the optimistic page, so clicking
+      // next twice before the action settles advances 1 -> 2 -> 3 instead of
+      // being dropped by a re-entry guard.
+      const resolvers: (() => void)[] = [];
+      const changeAction = vi.fn(
+        async () =>
+          new Promise<void>(resolve => {
+            resolvers.push(resolve);
+          }),
+      );
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          changeAction={changeAction}
+          totalPages={5}
+          variant="compact"
+        />,
+      );
+
+      const next = screen.getByRole('button', {name: 'Go to next page'});
+      await act(async () => {
+        fireEvent.click(next);
+      });
+      expect(screen.getByText('Page 2 of 5')).toBeInTheDocument();
+      await act(async () => {
+        fireEvent.click(next);
+      });
+      expect(screen.getByText('Page 3 of 5')).toBeInTheDocument();
+
+      expect(changeAction).toHaveBeenCalledTimes(2);
+      expect(changeAction).toHaveBeenNthCalledWith(1, 2);
+      expect(changeAction).toHaveBeenNthCalledWith(2, 3);
+
+      await act(async () => {
+        resolvers.forEach(resolve => resolve());
+        await Promise.resolve();
+      });
+    });
+
+    it('supports a synchronous changeAction', async () => {
+      const user = userEvent.setup();
+      const changeAction = vi.fn((_page: number) => {});
+      const onChange = vi.fn();
+      render(
+        <Pagination
+          page={2}
+          onChange={onChange}
+          changeAction={changeAction}
+          totalPages={5}
+        />,
+      );
+      await user.click(
+        screen.getByRole('button', {name: 'Go to previous page'}),
+      );
+      expect(onChange).toHaveBeenCalledWith(1);
+      expect(changeAction).toHaveBeenCalledWith(1);
+    });
+
+    it('does not fire changeAction when disabled', async () => {
+      const user = userEvent.setup();
+      const changeAction = vi.fn();
+      render(
+        <Pagination
+          page={1}
+          onChange={() => {}}
+          changeAction={changeAction}
+          totalPages={5}
+          isDisabled
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Go to next page'}));
+      expect(changeAction).not.toHaveBeenCalled();
+    });
+  });
+
   // ---------------------------------------------------------------------------
   // Boundary states
   // ---------------------------------------------------------------------------
@@ -459,12 +593,7 @@ describe('Pagination', () => {
   describe('disabled state', () => {
     it('disables all page buttons when isDisabled', () => {
       render(
-        <Pagination
-          page={3}
-          onChange={() => {}}
-          totalPages={5}
-          isDisabled
-        />,
+        <Pagination page={3} onChange={() => {}} totalPages={5} isDisabled />,
       );
       expect(
         screen.getByRole('button', {name: 'Go to previous page'}),
@@ -480,12 +609,7 @@ describe('Pagination', () => {
       const user = userEvent.setup();
       const onChange = vi.fn();
       render(
-        <Pagination
-          page={3}
-          onChange={onChange}
-          totalPages={5}
-          isDisabled
-        />,
+        <Pagination page={3} onChange={onChange} totalPages={5} isDisabled />,
       );
       // Disabled buttons can't be clicked
       await user.click(screen.getByRole('button', {name: 'Go to page 1'}));