@astryxdesign/core 0.1.0 → 0.1.1

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/Resizable/Resizable.doc.mjs

@@ -27,7 +27,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Use useResizable() with existing XDS layout components. ' +
+          'Use useResizable() with existing Astryx layout components. ' +
           'Pass the returned props to the resizable prop on LayoutPanel or SideNav.',
       },
       {
@@ -195,7 +195,7 @@ export const docsDense = {
     description:
       'Hook-based resizable panel system. useResizable() manages size state; ResizeHandle provides interactive pill-grip separator. Pass resize props to existing layout components via their resizable prop.',
     bestPractices: [
-      {guidance: true, description: 'Use useResizable() w/ existing XDS layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.'},
+      {guidance: true, description: 'Use useResizable() w/ existing Astryx layout components. Pass returned props to resizable prop on LayoutPanel or SideNav.'},
       {guidance: true, description: 'Provide accessible label on each ResizeHandle when multiple handles exist (e.g. "Resize sidebar", "Resize terminal").'},
       {guidance: false, description: 'Wrap panels in extra container components for resize. Hook-first architecture avoids extra DOM; use it directly on existing components.'},
     ],

package/src/Resizable/useResizable.ts

@@ -107,10 +107,6 @@ export interface ResizableProps {
 const DEFAULT_MIN = 50;
 const DEFAULT_COLLAPSED_SIZE = 40;
 const STORAGE_PREFIX = 'astryx-resizable:';
-// Legacy key prefix read during the compat window so persisted panel sizes
-// survive the xds -> astryx rename. Read-only fallback; we always write the
-// new prefix. Removed at final cutover.
-const LEGACY_STORAGE_PREFIX = 'xds-resizable:';
 
 // =============================================================================
 // Helpers
@@ -147,9 +143,7 @@ function loadPersistedSize(key: string): number | null {
     return null;
   }
   try {
-    const raw =
-      localStorage.getItem(STORAGE_PREFIX + key) ??
-      localStorage.getItem(LEGACY_STORAGE_PREFIX + key);
+    const raw = localStorage.getItem(STORAGE_PREFIX + key);
     if (raw != null) {
       const parsed = JSON.parse(raw);
       if (typeof parsed === 'number') {

package/src/Selector/Selector.tsx

@@ -107,12 +107,11 @@ const styles = stylex.create({
     lineHeight: 'inherit',
     color: 'inherit',
     cursor: 'pointer',
-    outline: {
-      default: 'none',
-      ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: '0',
-    borderRadius: radiusVars['--radius-element'],
+    // The wrapper (inputWrapperStyles.base) renders the focus ring via
+    // :focus-within when this button is focused, matching TextInput/NumberInput.
+    // The button must not draw its own :focus-visible outline or the two stack
+    // into a doubled ring over the trigger.
+    outline: 'none',
   },
   triggerPlaceholder: {
     color: colorVars['--color-text-secondary'],

package/src/Table/Table.doc.mjs

@@ -104,7 +104,7 @@ export const docs = {
       'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
     bestPractices: [
       { guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
-      { guidance: true, description: 'Compose rich cell content with XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+      { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
       { guidance: true, description: 'Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum.' },
       { guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
@@ -128,7 +128,7 @@ export const docsZh = {
       'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
     bestPractices: [
       { guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
-      { guidance: true, description: 'Compose rich cell content with XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+      { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
       { guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
     ],
@@ -151,7 +151,7 @@ export const docsDense = {
       'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
     bestPractices: [
       { guidance: true, description: 'Use density and divider variants to match the information density and scanning needs of your data.' },
-      { guidance: true, description: 'Compose rich cell content with XDS components like Badge, StatusDot, and Avatar via renderCell.' },
+      { guidance: true, description: 'Compose rich cell content with Astryx components like Badge, StatusDot, and Avatar via renderCell.' },
       { guidance: true, description: 'Set explicit width on every column via proportional() or pixel(). proportional(1) = equal flex w/ 120px min preventing collapse on narrow viewports. Omitting width skips the minimum.' },
       { guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },

package/src/ToggleButton/ToggleButton.doc.mjs

@@ -39,8 +39,8 @@ export const docs = {
     },
     {
       name: 'pressedChangeAction',
-      type: '(isPressed: boolean) => Promise<void>',
-      description: 'Async action handler for API-backed toggles. Shows loading spinner while pending.',
+      type: '(isPressed: boolean) => void | Promise<void>',
+      description: 'Action handler for API- or navigation-backed toggles, run in a transition. Shows an optimistic pressed state immediately and a (debounced) spinner while pending; interruptible by re-clicks.',
     },
     {
       name: 'size',

package/src/ToggleButton/ToggleButton.test.tsx

@@ -9,7 +9,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {useState} from 'react';
 import {ToggleButton} from './ToggleButton';
@@ -71,11 +71,7 @@ describe('ToggleButton', () => {
 
   it('sets aria-pressed=true when pressed', () => {
     render(
-      <ToggleButton
-        label="Bold"
-        isPressed={true}
-        onPressedChange={() => {}}
-      />,
+      <ToggleButton label="Bold" isPressed={true} onPressedChange={() => {}} />,
     );
     expect(screen.getByRole('button')).toHaveAttribute('aria-pressed', 'true');
   });
@@ -196,6 +192,152 @@ describe('ToggleButton', () => {
     );
     expect(screen.getByTestId('bold-toggle')).toBeInTheDocument();
   });
+
+  it('shows the optimistic pressed state immediately, before any spinner', async () => {
+    const user = userEvent.setup();
+    let resolveAction: (() => void) | undefined;
+    const pressedChangeAction = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          resolveAction = resolve;
+        }),
+    );
+
+    render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        onPressedChange={() => {}}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+
+    const button = screen.getByRole('button', {name: 'Favorite'});
+    expect(button).toHaveAttribute('aria-pressed', 'false');
+
+    await user.click(button);
+
+    // The optimistic state flips immediately. The spinner is debounced, so the
+    // button is not disabled or aria-busy yet — it stays interruptible.
+    expect(pressedChangeAction).toHaveBeenCalledWith(true);
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+    expect(button).not.toBeDisabled();
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+
+    // Settle the action so the pending transition doesn't leak into later tests.
+    await act(async () => {
+      resolveAction?.();
+      await Promise.resolve();
+    });
+  });
+
+  it('shows a loading spinner once the action stays pending past the delay', async () => {
+    const user = userEvent.setup();
+    let resolveAction: (() => void) | undefined;
+    const pressedChangeAction = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          resolveAction = resolve;
+        }),
+    );
+
+    render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        onPressedChange={() => {}}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+
+    const button = screen.getByRole('button', {name: 'Favorite'});
+    await user.click(button);
+
+    // The optimistic state shows immediately; the spinner is debounced and
+    // appears only after the action stays pending past the delay window.
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+    await waitFor(() => expect(button).toBeDisabled());
+    expect(button).toHaveAttribute('aria-busy', 'true');
+
+    await act(async () => {
+      resolveAction?.();
+      await Promise.resolve();
+    });
+    expect(button).not.toBeDisabled();
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+  });
+
+  it('interrupts an in-flight action on re-click (true -> false -> true)', async () => {
+    // Each click interrupts the previous transition. The actions are resolved
+    // at the end so the pending transition doesn't leak into later tests.
+    const resolvers: (() => void)[] = [];
+    const pressedChangeAction = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          resolvers.push(resolve);
+        }),
+    );
+
+    render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        onPressedChange={() => {}}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+
+    const button = screen.getByRole('button', {name: 'Favorite'});
+
+    // Each click derives the next state from the optimistic (in-progress)
+    // value, so rapid clicks toggle rather than being dropped. fireEvent keeps
+    // the clicks within the spinner debounce window so the button stays
+    // interruptible.
+    await act(async () => {
+      fireEvent.click(button);
+    });
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+    await act(async () => {
+      fireEvent.click(button);
+    });
+    expect(button).toHaveAttribute('aria-pressed', 'false');
+    await act(async () => {
+      fireEvent.click(button);
+    });
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+
+    expect(pressedChangeAction).toHaveBeenCalledTimes(3);
+    expect(pressedChangeAction).toHaveBeenNthCalledWith(1, true);
+    expect(pressedChangeAction).toHaveBeenNthCalledWith(2, false);
+    expect(pressedChangeAction).toHaveBeenNthCalledWith(3, true);
+
+    await act(async () => {
+      resolvers.forEach(resolve => resolve());
+      await Promise.resolve();
+    });
+  });
+
+  it('supports a synchronous pressedChangeAction', async () => {
+    const user = userEvent.setup();
+    // A sync handler (e.g. a router navigation) with no returned promise.
+    const pressedChangeAction = vi.fn((_next: boolean) => {});
+    const onPressedChange = vi.fn();
+
+    render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        onPressedChange={onPressedChange}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+
+    const button = screen.getByRole('button', {name: 'Favorite'});
+    await user.click(button);
+
+    expect(onPressedChange).toHaveBeenCalledWith(true);
+    expect(pressedChangeAction).toHaveBeenCalledWith(true);
+  });
 });
 
 // =============================================================================