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

package/src/Table/types.ts

@@ -261,6 +261,20 @@ export interface HeaderCellRenderProps {
   overlay?: ReactNode;
   /** Content rendered below the header label row (e.g. inline filter controls). */
   below?: ReactNode;
+  /**
+   * Index of this column within the final, ordered list of rendered columns
+   * (after column injection/reordering by other plugins). Populated by
+   * BaseTable. Optional for backward compatibility with hand-constructed
+   * renders in tests.
+   */
+  columnIndex?: number;
+  /**
+   * The full, final ordered list of columns being rendered (after column
+   * injection/reordering by other plugins). Populated by BaseTable so plugins
+   * can reason about column position — e.g. cumulative sticky offsets. Optional
+   * for backward compatibility.
+   */
+  columns?: ReadonlyArray<TableColumn<Record<string, unknown>>>;
 }
 
 /** Props passed through the plugin pipeline for each body `<tr>` */
@@ -276,6 +290,49 @@ export interface BodyRowRenderProps {
 export interface BodyCellRenderProps {
   htmlProps: TdHTMLAttributes<HTMLTableCellElement>;
   styles: StyleXStyles[];
+  /**
+   * Index of this cell's column within the final ordered column list.
+   * Mirrors the `columnIndex` passed to `transformHeaderCell`. Populated by
+   * BaseTable. Optional for backward compatibility with hand-constructed
+   * renders in tests.
+   */
+  columnIndex?: number;
+  /**
+   * The full, final ordered list of columns being rendered. Populated by
+   * BaseTable so plugins can reason about column position — e.g. cumulative
+   * sticky offsets. Optional for backward compatibility.
+   */
+  columns?: ReadonlyArray<TableColumn<Record<string, unknown>>>;
+}
+
+/**
+ * Props passed through the plugin pipeline for the scroll-wrapper region — the
+ * `<div>` wrapping the `<table>` element (the horizontal scroll container, see
+ * the `scrollWrapper` prop on `BaseTableProps`). Lets plugins attach a `ref` to
+ * the scrollable element (e.g. for scroll-aware sticky-column shadows or
+ * virtualization) and inject chrome before/after the table.
+ *
+ * Named after `scrollWrapper` (not "layout") to avoid ambiguity: it transforms
+ * the wrapper element, not the internal header/body/footer layout of `<table>`.
+ *
+ * Runs after `transformTable`/cell transforms but inside `transformTableContext`,
+ * so plugin chrome added here stays within any context providers but wraps the
+ * scroll area.
+ */
+export interface ScrollWrapperRenderProps {
+  /**
+   * HTML attributes applied to the scroll container `<div>`, including an
+   * optional `ref`. Plugins compose refs by reading the existing `ref` and
+   * merging their own (see `useTableStickyColumns`).
+   */
+  htmlProps: HTMLAttributes<HTMLDivElement> & {
+    ref?: Ref<HTMLDivElement>;
+  };
+  styles: StyleXStyles[];
+  /** Content rendered before the `<table>`, inside the scroll container. */
+  beforeTable?: ReactNode;
+  /** Content rendered after the `<table>`, inside the scroll container. */
+  afterTable?: ReactNode;
 }
 
 // =============================================================================
@@ -294,7 +351,8 @@ export interface BodyCellRenderProps {
  * 4. `transformHeaderCell` — transform each `<th>` props
  * 5. `transformBodyRow` — transform each body `<tr>` props
  * 6. `transformBodyCell` — transform each body `<td>` props
- * 7. `transformTableContext` — wrap the table output in context providers
+ * 7. `transformScrollWrapper` — transform the scroll-container wrapper around the table
+ * 8. `transformTableContext` — wrap the table output in context providers
  */
 export interface TablePlugin<
   T extends Record<string, unknown> = Record<string, unknown>,
@@ -309,10 +367,17 @@ export interface TablePlugin<
   transformTable?: (props: TableRenderProps) => TableRenderProps;
   /** Transform the header `<tr>` props */
   transformHeaderRow?: (props: HeaderRowRenderProps) => HeaderRowRenderProps;
-  /** Transform each `<th>` props */
+  /**
+   * Transform each `<th>` props.
+   *
+   * `columnIndex` and the full `columns` list are provided for plugins that
+   * need to reason about column position (e.g. cumulative sticky offsets).
+   */
   transformHeaderCell?: (
     props: HeaderCellRenderProps,
     column: TableColumn<T>,
+    columnIndex: number,
+    columns: ReadonlyArray<TableColumn<T>>,
   ) => HeaderCellRenderProps;
   /** Transform each body `<tr>` props */
   transformBodyRow?: (
@@ -320,12 +385,28 @@ export interface TablePlugin<
     item: T,
     index: number,
   ) => BodyRowRenderProps;
-  /** Transform each body `<td>` props */
+  /**
+   * Transform each body `<td>` props.
+   *
+   * `columnIndex` and the full `columns` list are provided for plugins that
+   * need to reason about column position (e.g. cumulative sticky offsets).
+   */
   transformBodyCell?: (
     props: BodyCellRenderProps,
     column: TableColumn<T>,
     item: T,
+    columnIndex: number,
+    columns: ReadonlyArray<TableColumn<T>>,
   ) => BodyCellRenderProps;
+  /**
+   * Transform the scroll-wrapper region — the `<div>` wrapping the `<table>`
+   * (see the `scrollWrapper` prop). Use to attach a `ref` to the scrollable
+   * element (scroll-aware shadows, virtualization) or to inject chrome
+   * before/after the table.
+   */
+  transformScrollWrapper?: (
+    props: ScrollWrapperRenderProps,
+  ) => ScrollWrapperRenderProps;
   /** Wrap the table output in context providers */
   transformTableContext?: (children: ReactNode) => ReactNode;
 }
@@ -390,8 +471,19 @@ export interface BaseTableProps<
    * plugin `transformTableContext` layer. Used by `Table` to add a
    * horizontal scroll container so plugin chrome (pagination, toolbars)
    * stays outside the scrollable area.
+   *
+   * Receives `htmlProps` (including an optional `ref`) and `styles` produced
+   * by the plugin `transformScrollWrapper` pipeline, plus `beforeTable`/`afterTable`
+   * chrome. The wrapper must spread `htmlProps` (and apply `styles`) onto its
+   * scroll-container element so plugins can attach refs / scroll listeners.
    */
-  scrollWrapper?: ComponentType<{children: ReactNode}>;
+  scrollWrapper?: ComponentType<{
+    children: ReactNode;
+    htmlProps?: HTMLAttributes<HTMLDivElement> & {ref?: Ref<HTMLDivElement>};
+    styles?: StyleXStyles[];
+    beforeTable?: ReactNode;
+    afterTable?: ReactNode;
+  }>;
   /**
    * How default-rendered body cell text behaves when it exceeds column width.
    *

package/src/Table/useBaseTablePlugins.ts

@@ -87,6 +87,7 @@ const VALID_TRANSFORM_KEYS = new Set([
   'transformHeaderCell',
   'transformBodyRow',
   'transformBodyCell',
+  'transformScrollWrapper',
   'transformTableContext',
 ]);
 

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);
+  });
 });
 
 // =============================================================================

package/src/ToggleButton/ToggleButton.tsx

@@ -20,7 +20,14 @@
  * - /packages/cli/templates/blocks/components/ToggleButton/ (showcase blocks)
  */
 
-import React, {useCallback, type ReactNode} from 'react';
+import React, {
+  useCallback,
+  useEffect,
+  useOptimistic,
+  useState,
+  useTransition,
+  type ReactNode,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, fontWeightVars} from '../theme/tokens.stylex';
 
@@ -29,6 +36,37 @@ import {useToggleButtonGroup} from './ToggleButtonGroup';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
+// =============================================================================
+// Constants & helpers
+// =============================================================================
+
+/**
+ * The spinner only appears once the action has been pending for this long.
+ * A fast action shows the optimistic pressed state immediately with no spinner
+ * flash, and rapid re-clicks can interrupt the in-flight action before the
+ * button locks behind the spinner.
+ */
+const PENDING_SPINNER_DELAY_MS = 150;
+
+/**
+ * Returns `true` only once `active` has stayed `true` for `delayMs`.
+ * Used to debounce the loading spinner so the optimistic state shows first.
+ */
+function useDelayed(active: boolean, delayMs: number): boolean {
+  const [delayed, setDelayed] = useState(false);
+  useEffect(() => {
+    if (!active) {
+      return undefined;
+    }
+    const timer = setTimeout(() => setDelayed(true), delayMs);
+    return () => {
+      clearTimeout(timer);
+      setDelayed(false);
+    };
+  }, [active, delayMs]);
+  return active && delayed;
+}
+
 // =============================================================================
 // Styles
 // =============================================================================
@@ -91,8 +129,15 @@ export interface ToggleButtonProps extends BaseProps<HTMLButtonElement> {
   onPressedChange?: (isPressed: boolean) => void;
 
   /**
-   * Async action handler for API-backed toggles.
-   * The button shows a loading spinner while the promise is pending.
+   * Action handler for API- or navigation-backed toggles, run inside a
+   * transition. The button shows a loading spinner while the action is
+   * pending — whether it returns a promise or synchronously triggers a
+   * suspending update (e.g. a router navigation that suspends on data).
+   *
+   * Because it runs in a transition, the toggle is *interruptible*: clicking
+   * again while an action is pending starts a new transition with the next
+   * optimistic state, so the action reflects the latest intent rather than
+   * being dropped.
    *
    * @example
    * ```
@@ -106,7 +151,7 @@ export interface ToggleButtonProps extends BaseProps<HTMLButtonElement> {
    * />
    * ```
    */
-  pressedChangeAction?: (isPressed: boolean) => Promise<void>;
+  pressedChangeAction?: (isPressed: boolean) => void | Promise<void>;
 
   /**
    * The size of the toggle button.
@@ -218,46 +263,64 @@ export function ToggleButton({
   style,
   ...props
 }: ToggleButtonProps): ReactNode {
-  // Read group context if inside a group
   const group = useToggleButtonGroup();
 
-  // Resolve state from group or props
-  const isPressed =
+  const committedPressed =
     group && value != null
       ? group.selectedValues.has(value)
       : (isPressedProp ?? false);
   const size = sizeProp ?? group?.size ?? 'md';
   const isDisabled = group?.isDisabled ?? isDisabledProp;
 
+  // Track the pressed state optimistically. While an action is pending, the
+  // button reflects the intended (optimistic) state immediately, and a click
+  // mid-flight derives its next state from this value — so rapid toggles read
+  // true -> false -> true rather than stalling on the last committed value.
+  const [optimisticPressed, setOptimisticPressed] =
+    useOptimistic(committedPressed);
+  const isPressed = optimisticPressed;
+
   const resolvedIcon = isPressed && pressedIcon ? pressedIcon : icon;
 
+  // Run the toggle inside a transition. The action is interruptible: clicking
+  // again while it is pending starts a fresh transition with the next
+  // optimistic state instead of being dropped, so there is no re-entry guard.
+  // Both onPressedChange and pressedChangeAction run inside the transition,
+  // which means a synchronous-but-suspending handler (e.g. a router navigation
+  // that suspends on data) also drives the pending state — not just promises.
+  const [isPending, startTransition] = useTransition();
+  // Debounce the spinner so a fast action shows the optimistic state without a
+  // spinner flash, and rapid re-clicks can interrupt before the button locks.
+  const showSpinner = useDelayed(isPending, PENDING_SPINNER_DELAY_MS);
+  const isLoadingState = isLoading || showSpinner;
+
   const handleClick = useCallback(() => {
-    if (isDisabled || isLoading) {
+    if (isDisabled) {
       return;
     }
 
     if (group && value != null) {
-      // Delegate to group context
+      // Group mode delegates selection to the group; no async-action path.
       group.toggle(value);
-    } else if (onPressedChangeProp) {
-      // Standalone toggle
-      const newState = !isPressed;
-      onPressedChangeProp(newState);
-      if (pressedChangeAction) {
-        void pressedChangeAction(newState);
-      }
+      return;
     }
+
+    const newState = !optimisticPressed;
+    startTransition(async () => {
+      setOptimisticPressed(newState);
+      onPressedChangeProp?.(newState);
+      await pressedChangeAction?.(newState);
+    });
   }, [
     isDisabled,
-    isLoading,
     group,
     value,
+    optimisticPressed,
     onPressedChangeProp,
     pressedChangeAction,
-    isPressed,
+    setOptimisticPressed,
   ]);
 
-  // Label with font weight shift and width reservation
   // isIconOnly prop is the source of truth for icon-only rendering.
   const labelContent =
     children != null ? (
@@ -289,7 +352,7 @@ export function ToggleButton({
       variant="ghost"
       size={size}
       isDisabled={isDisabled}
-      isLoading={isLoading}
+      isLoading={isLoadingState}
       isIconOnly={isIconOnly}
       aria-pressed={isPressed}
       icon={resolvedIcon}

package/src/Toolbar/Toolbar.doc.mjs

@@ -58,7 +58,7 @@ export const docs = {
           name: 'gap',
           type: 'SpacingStep',
           description: 'Gap between items within each slot.',
-          default: '2',
+          default: '1',
         },
         {
           name: 'orientation',

package/src/hooks/useEntryAnimation.doc.mjs

@@ -23,7 +23,7 @@ export const docs = {
   ],
   usage: {
     description:
-      'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint; elements rendered on page load are not animated. Uses XDS motion tokens (duration, easing) for consistent animation timing. Requires "use client"; does not support SSR.',
+      'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint; elements rendered on page load are not animated. Uses Astryx motion tokens (duration, easing) for consistent animation timing. Requires "use client"; does not support SSR.',
     bestPractices: [
       { guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, or expanding sections.' },
       { guidance: true, description: 'Spread the returned style into stylex.props() alongside other styles.' },
@@ -39,7 +39,7 @@ export const docs = {
 /** @type {import('../docs-types').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses XDS motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
+    'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
   paramDescriptions: {
     preset: 'animation preset applied on mount.',
   },
@@ -48,7 +48,7 @@ export const docsDense = {
   },
   usage: {
     description:
-      'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses XDS motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
+      'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
     bestPractices: [
       { guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, expanding sections.' },
       { guidance: true, description: 'Spread returned style into stylex.props() alongside other styles.' },

package/src/hooks/useMediaQuery.doc.mjs

@@ -24,7 +24,7 @@ export const docs = {
     description: 'SSR-safe media query hook that subscribes to window.matchMedia changes. Returns whether the given media query matches. Always returns false on first render for SSR compatibility.',
     bestPractices: [
       { guidance: true, description: 'Use for responsive layout switching based on viewport width, color scheme, or motion preferences.' },
-      { guidance: true, description: 'Prefer XDS responsive tokens and component props over manual breakpoint logic when possible.' },
+      { guidance: true, description: 'Prefer Astryx responsive tokens and component props over manual breakpoint logic when possible.' },
       { guidance: false, description: 'Use for server-rendered content that must match on first paint; the hook always returns false initially.' },
     ],
   },
@@ -47,7 +47,7 @@ export const docsDense = {
     description: 'SSR-safe media query hook subscribing to window.matchMedia changes. Returns whether given media query matches. Always returns false on first render for SSR compatibility.',
     bestPractices: [
       { guidance: true, description: 'Use for responsive layout switching based on viewport width, color scheme, or motion preferences.' },
-      { guidance: true, description: 'Prefer XDS responsive tokens + component props over manual breakpoint logic when possible.' },
+      { guidance: true, description: 'Prefer Astryx responsive tokens + component props over manual breakpoint logic when possible.' },
       { guidance: false, description: 'Use for server-rendered content that must match on first paint; hook always returns false initially.' },
     ],
   },

package/src/hooks/useStreamingText.doc.mjs

@@ -41,7 +41,7 @@ export const docs = {
   ],
   usage: {
     description:
-      'Smooths bursty streamed text into a steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word and syntax boundaries to avoid slicing mid-markdown or mid-word, preventing visual glitches with markdown renderers. Animation timing derives from XDS motion tokens via useTheme when available, with sensible fallbacks outside a theme provider. Snaps to full text when isStreaming becomes false.',
+      'Smooths bursty streamed text into a steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word and syntax boundaries to avoid slicing mid-markdown or mid-word, preventing visual glitches with markdown renderers. Animation timing derives from Astryx motion tokens via useTheme when available, with sensible fallbacks outside a theme provider. Snaps to full text when isStreaming becomes false.',
     bestPractices: [
       { guidance: true, description: 'Pass the accumulated text (not individual chunks) as targetText; the hook handles incremental reveal internally.' },
       { guidance: true, description: 'Set isStreaming to false when the stream completes to snap to the final text.' },
@@ -58,7 +58,7 @@ export const docs = {
 /** @type {import('../docs-types').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from XDS motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',
+    'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from Astryx motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',
   paramDescriptions: {
     targetText: 'full target text to reveal. As new chunks arrive, update this value w/ accumulated text.',
     isStreaming: 'whether text currently being streamed. When false, hook returns full targetText immediately.',
@@ -70,7 +70,7 @@ export const docsDense = {
   },
   usage: {
     description:
-      'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from XDS motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',
+      'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from Astryx motion tokens via useTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',
     bestPractices: [
       { guidance: true, description: 'Pass accumulated text (not individual chunks) as targetText; hook handles incremental reveal internally.' },
       { guidance: true, description: 'Set isStreaming to false when stream completes to snap to final text.' },

package/src/theme/Theme.doc.mjs

@@ -39,7 +39,7 @@ export const docs = {
   },
   usage: {
     description:
-      'Wraps a subtree with a specific XDS theme. For static production themes, use `npx astryx theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.\n\n`defineTheme` accepts a `tokens` object whose keys are CSS custom property names (always prefixed with `--`). Common token names include `--color-accent`, `--color-background-surface`, `--color-background-body`, `--color-text-primary`, `--color-text-secondary`, `--radius-container`, `--spacing-1` through `--spacing-6`. Values can be a string (same for light/dark) or a `[light, dark]` tuple.\n\nExample:\n```ts\nimport {defineTheme} from \'@astryxdesign/core/theme\';\nconst myTheme = defineTheme({\n  name: \'ocean\',\n  tokens: {\n    \'--color-accent\': [\'#0077B6\', \'#48CAE4\'],\n    \'--color-background-surface\': [\'#F0F8FF\', \'#0A1628\'],\n    \'--color-text-primary\': [\'#0A1317\', \'#FFFFFF\'],\n    \'--radius-container\': \'16px\',\n  },\n});\n```',
+      'Wraps a subtree with a specific Astryx theme. For static production themes, use `npx astryx theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.\n\n`defineTheme` accepts a `tokens` object whose keys are CSS custom property names (always prefixed with `--`). Common token names include `--color-accent`, `--color-background-surface`, `--color-background-body`, `--color-text-primary`, `--color-text-secondary`, `--radius-container`, `--spacing-1` through `--spacing-6`. Values can be a string (same for light/dark) or a `[light, dark]` tuple.\n\nExample:\n```ts\nimport {defineTheme} from \'@astryxdesign/core/theme\';\nconst myTheme = defineTheme({\n  name: \'ocean\',\n  tokens: {\n    \'--color-accent\': [\'#0077B6\', \'#48CAE4\'],\n    \'--color-background-surface\': [\'#F0F8FF\', \'#0A1628\'],\n    \'--color-text-primary\': [\'#0A1317\', \'#FFFFFF\'],\n    \'--radius-container\': \'16px\',\n  },\n});\n```',
     bestPractices: [
       {
         guidance: true,
@@ -90,7 +90,7 @@ export const docs = {
 export const docsDense = {
   usage: {
     description:
-      'Wraps subtree w/ specific XDS theme. For static production themes, use `npx astryx theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping. Token names always start with `--` (e.g. `--color-accent`, `--color-background-surface`).',
+      'Wraps subtree w/ specific Astryx theme. For static production themes, use `npx astryx theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping. Token names always start with `--` (e.g. `--color-accent`, `--color-background-surface`).',
     bestPractices: [
       {
         guidance: true,

package/src/theme/Theme.tsx

@@ -123,7 +123,7 @@ function useThemeStyleInjection(theme: DefinedTheme): void {
     if (!warnedThemes.has(theme.name)) {
       warnedThemes.add(theme.name);
       console.warn(
-        `[XDS] Theme "${theme.name}" is using runtime style injection. ` +
+        `[Astryx] Theme "${theme.name}" is using runtime style injection. ` +
           `For better performance, use the pre-built theme:\n\n` +
           `  import {${theme.name}Theme} from '@astryxdesign/theme-${theme.name}/built';\n` +
           `  import '@astryxdesign/theme-${theme.name}/theme.css';\n\n` +

package/src/theme/defineTheme.ts

@@ -361,7 +361,7 @@ export interface DefinedTheme {
 // =============================================================================
 
 /** All Astryx token defaults as a flat map. Useful for resolving full token sets. */
-export const xdsTokenDefaults: Record<string, string> = {
+export const tokenDefaults: Record<string, string> = {
   ...colorDefaults,
   ...spacingDefaults,
   ...sizeDefaults,

package/src/theme/index.ts

@@ -28,7 +28,7 @@ export {
   type ThemeCSSOutput,
   type ThemeRulesSplit,
   isDefinedTheme,
-  xdsTokenDefaults,
+  tokenDefaults,
 } from './defineTheme';
 export type {
   DefineThemeInput,

package/src/theme/syntax/defineSyntaxTheme.ts

@@ -134,7 +134,7 @@ export function defineSyntaxTheme(input: SyntaxThemeInput): SyntaxThemeDefinitio
   const missing = ALL_SYNTAX_KEYS.filter(key => !(key in input.tokens));
   if (missing.length > 0) {
     console.warn(
-      '[XDS] defineSyntaxTheme("' + input.name + '"): missing tokens: ' +
+      '[Astryx] defineSyntaxTheme("' + input.name + '"): missing tokens: ' +
         missing.join(', ') + '. All 14 syntax tokens are required.',
     );
   }