@astryxdesign/core 0.1.0 → 0.1.1-canary.080d887

package/src/Timestamp/Timestamp.test.tsx

@@ -33,10 +33,30 @@ describe('Timestamp', () => {
     expect(screen.getByText('2 hours ago')).toBeInTheDocument();
   });
 
-  it('renders "just now" for very recent times', () => {
+  it('renders "now" for very recent times', () => {
     const fiveSecondsAgo = Date.now() / 1000 - 5;
     render(<Timestamp value={fiveSecondsAgo} format="relative" />);
-    expect(screen.getByText('just now')).toBeInTheDocument();
+    expect(screen.getByText('now')).toBeInTheDocument();
+  });
+
+  it('renders "now" for the current instant (not a future phrase)', () => {
+    // A value equal to "right now". Because the internal `now` baseline is
+    // captured at render time, it can lag the value by a fraction of a second,
+    // producing a tiny negative delta that must not be treated as the future.
+    render(<Timestamp value={Date.now() / 1000} format="relative" />);
+    expect(screen.queryByText(/^in /)).not.toBeInTheDocument();
+    expect(screen.getByText('now')).toBeInTheDocument();
+  });
+
+  it('renders "now" for a value a hair in the future (clock skew)', () => {
+    // Real-world clock / captured-now skew can make a current-ish value land a
+    // fraction of a second in the future relative to the component's internal
+    // `now`. This must read as the present ("now"), never "in a few
+    // seconds". Regression test for the right-now -> future-phrase bug.
+    const aHairInTheFuture = Date.now() / 1000 + 0.6;
+    render(<Timestamp value={aHairInTheFuture} format="relative" />);
+    expect(screen.queryByText(/^in /)).not.toBeInTheDocument();
+    expect(screen.getByText('now')).toBeInTheDocument();
   });
 
   it('renders "yesterday" for times ~1 day ago', () => {
@@ -49,11 +69,7 @@ describe('Timestamp', () => {
 
   it('renders date format', () => {
     render(
-      <Timestamp
-        value="2026-02-19T17:00:00Z"
-        format="date"
-        data-testid="ts"
-      />,
+      <Timestamp value="2026-02-19T17:00:00Z" format="date" data-testid="ts" />,
     );
     const el = screen.getByTestId('ts');
     expect(el.textContent).toContain('2026');
@@ -77,11 +93,7 @@ describe('Timestamp', () => {
 
   it('renders time format', () => {
     render(
-      <Timestamp
-        value="2026-02-19T17:00:00Z"
-        format="time"
-        data-testid="ts"
-      />,
+      <Timestamp value="2026-02-19T17:00:00Z" format="time" data-testid="ts" />,
     );
     const el = screen.getByTestId('ts');
     // Should contain time but not year
@@ -197,7 +209,7 @@ describe('Timestamp', () => {
   it('live updates relative time', () => {
     const now = Date.now() / 1000;
     render(<Timestamp value={now - 5} format="relative" isLive />);
-    expect(screen.getByText('just now')).toBeInTheDocument();
+    expect(screen.getByText('now')).toBeInTheDocument();
 
     act(() => {
       vi.advanceTimersByTime(30_000);
@@ -210,11 +222,7 @@ describe('Timestamp', () => {
   it('forwards ref', () => {
     const ref = {current: null as HTMLTimeElement | null};
     render(
-      <Timestamp
-        ref={ref}
-        value="2026-03-25T10:00:00Z"
-        format="date_time"
-      />,
+      <Timestamp ref={ref} value="2026-03-25T10:00:00Z" format="date_time" />,
     );
     expect(ref.current).toBeInstanceOf(HTMLTimeElement);
   });
@@ -240,6 +248,24 @@ describe('Timestamp', () => {
     expect(screen.getByText('in 1 hour')).toBeInTheDocument();
   });
 
+  it('renders "now" for a value a few seconds in the future (clock skew)', () => {
+    // Beyond the sub-second render lag but still within the skew tolerance: a
+    // value ~20s ahead of our clock is almost always skew (the value's clock
+    // running fast), not a genuine future event, so it should read as the
+    // present rather than "in a few seconds".
+    const twentySecondsFromNow = Date.now() / 1000 + 20;
+    render(<Timestamp value={twentySecondsFromNow} format="relative" />);
+    expect(screen.queryByText(/^in /)).not.toBeInTheDocument();
+    expect(screen.getByText('now')).toBeInTheDocument();
+  });
+
+  it('renders a genuine near-future time beyond the skew tolerance', () => {
+    // Past the skew window — this is a real upcoming time, not clock drift.
+    const fortyFiveSecondsFromNow = Date.now() / 1000 + 45;
+    render(<Timestamp value={fortyFiveSecondsFromNow} format="relative" />);
+    expect(screen.getByText('in a few seconds')).toBeInTheDocument();
+  });
+
   // --- Long-ago relative ---
 
   it('renders months ago for dates older than 30 days', () => {

package/src/Timestamp/Timestamp.tsx

@@ -19,12 +19,7 @@
 import {useEffect, useRef, useState, lazy, Suspense} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Text} from '../Text';
-import type {
-  TextType,
-  TextSize,
-  TextColor,
-  TextWeight,
-} from '../theme/types';
+import type {TextType, TextSize, TextColor, TextWeight} from '../theme/types';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
@@ -54,7 +49,7 @@ export interface TimestampProps extends BaseProps<HTMLTimeElement> {
   value: string | number;
   /**
    * Display format.
-   * - `'relative'`: "2 hours ago", "yesterday", "just now"
+   * - `'relative'`: "2 hours ago", "yesterday", "now"
    * - `'auto'`: Relative for recent times, `date_time` for older
    * - `'date'`: "Mar 21, 2025"
    * - `'date_time'`: "Mar 21, 2025, 2:51 PM"
@@ -138,6 +133,18 @@ const YEAR = 365 * DAY;
 /** Default auto threshold: 7 days in seconds */
 const DEFAULT_AUTO_THRESHOLD = 7 * DAY;
 
+/**
+ * Tolerance (in seconds) for treating a *future* timestamp as the present.
+ * A value only a handful of seconds ahead of our reference clock is almost
+ * always clock skew — the displayed `now` lagging the real clock, or the value
+ * being produced on a slightly faster clock — not a genuine future event, so
+ * it reads as "now" rather than a confusing "in a few seconds". The future
+ * side gets a wider window than the past (which only needs to absorb the
+ * sub-second render-time lag) because future drift is far more likely to be
+ * skew than real.
+ */
+const FUTURE_SKEW_TOLERANCE = 30;
+
 function parseValue(value: string | number): Date {
   if (typeof value === 'number') {
     // Heuristic: if the number is less than 1e12, treat as seconds; otherwise ms.
@@ -150,9 +157,25 @@ function parseValue(value: string | number): Date {
 function getRelativeTimeString(date: Date, now: Date): string {
   const diffSeconds = Math.round((now.getTime() - date.getTime()) / 1000);
 
+  // Treat values at (or a hair before/after) the present as "now". The
+  // internal `now` reference is captured at render time, so it can lag the
+  // real clock; a value equal to "right now" can land a fraction of a second
+  // in the future and round to a small negative delta. Without this clamp,
+  // such values fall into the future branch and render "in a few seconds".
+  if (Math.abs(diffSeconds) < 10) {
+    return 'now';
+  }
+
   if (diffSeconds < 0) {
     // Future dates
     const absDiff = Math.abs(diffSeconds);
+    // A value only a few seconds ahead of our clock is almost always skew, not
+    // a genuine future event — render it as the present rather than a
+    // confusing "in a few seconds". Wider than the past window above on
+    // purpose (see FUTURE_SKEW_TOLERANCE).
+    if (absDiff <= FUTURE_SKEW_TOLERANCE) {
+      return 'now';
+    }
     if (absDiff < MINUTE) {
       return 'in a few seconds';
     }
@@ -176,9 +199,6 @@ function getRelativeTimeString(date: Date, now: Date): string {
     return `in ${years} ${years === 1 ? 'year' : 'years'}`;
   }
 
-  if (diffSeconds < 10) {
-    return 'just now';
-  }
   if (diffSeconds < MINUTE) {
     return `${diffSeconds} seconds ago`;
   }

package/src/ToggleButton/ToggleButton.doc.mjs

@@ -34,13 +34,13 @@ export const docs = {
     },
     {
       name: 'onPressedChange',
-      type: '(isPressed: boolean) => void',
-      description: 'Called when pressed state should change. Ignored when inside a group.',
+      type: '(isPressed: boolean, event: MouseEvent) => void',
+      description: 'Called when pressed state should change. Receives the next state and the click event; call event.preventDefault() to skip pressedChangeAction. Ignored when inside a group.',
     },
     {
       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 spinner while pending; the button stays interruptible by re-clicks.',
     },
     {
       name: 'size',

package/src/ToggleButton/ToggleButton.test.tsx

@@ -9,9 +9,9 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, act, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {useState} from 'react';
+import {useState, type MouseEvent} from 'react';
 import {ToggleButton} from './ToggleButton';
 import {ToggleButtonGroup} from './ToggleButtonGroup';
 
@@ -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');
   });
@@ -92,7 +88,7 @@ describe('ToggleButton', () => {
     );
 
     await user.click(screen.getByRole('button'));
-    expect(handleChange).toHaveBeenCalledWith(true);
+    expect(handleChange).toHaveBeenCalledWith(true, expect.anything());
   });
 
   it('calls onPressedChange with false when clicking pressed button', async () => {
@@ -107,7 +103,7 @@ describe('ToggleButton', () => {
     );
 
     await user.click(screen.getByRole('button'));
-    expect(handleChange).toHaveBeenCalledWith(false);
+    expect(handleChange).toHaveBeenCalledWith(false, expect.anything());
   });
 
   it('renders pressedIcon when pressed', () => {
@@ -196,6 +192,173 @@ describe('ToggleButton', () => {
     );
     expect(screen.getByTestId('bold-toggle')).toBeInTheDocument();
   });
+
+  it('shows the optimistic pressed state and stays interruptible while pending', 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 and the spinner shows via
+    // aria-busy, but the button is never disabled — it stays clickable so the
+    // action can be interrupted by another click.
+    expect(pressedChangeAction).toHaveBeenCalledWith(true);
+    expect(button).toHaveAttribute('aria-pressed', 'true');
+    expect(button).toHaveAttribute('aria-busy', 'true');
+    expect(button).not.toBeDisabled();
+
+    // Settle the action so the pending transition doesn't leak into later tests.
+    await act(async () => {
+      resolveAction?.();
+      await Promise.resolve();
+    });
+  });
+
+  it('clears the loading state once the action settles', 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);
+
+    expect(button).toHaveAttribute('aria-busy', 'true');
+    expect(button).not.toBeDisabled();
+
+    await act(async () => {
+      resolveAction?.();
+      await Promise.resolve();
+    });
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+    expect(button).not.toBeDisabled();
+  });
+
+  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. The button is
+    // never disabled while pending, so every click lands and interrupts.
+    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.anything());
+    expect(pressedChangeAction).toHaveBeenCalledWith(true);
+  });
+
+  it('skips pressedChangeAction when onPressedChange calls preventDefault', async () => {
+    const user = userEvent.setup();
+    const pressedChangeAction = vi.fn();
+    const onPressedChange = vi.fn(
+      (_next: boolean, event: MouseEvent<HTMLButtonElement>) => {
+        event.preventDefault();
+      },
+    );
+
+    render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        onPressedChange={onPressedChange}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Favorite'}));
+
+    expect(onPressedChange).toHaveBeenCalledWith(true, expect.anything());
+    expect(pressedChangeAction).not.toHaveBeenCalled();
+  });
 });
 
 // =============================================================================

package/src/ToggleButton/ToggleButton.tsx

@@ -20,7 +20,7 @@
  * - /packages/cli/templates/blocks/components/ToggleButton/ (showcase blocks)
  */
 
-import React, {useCallback, type ReactNode} from 'react';
+import React, {useOptimistic, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, fontWeightVars} from '../theme/tokens.stylex';
 
@@ -84,15 +84,23 @@ export interface ToggleButtonProps extends BaseProps<HTMLButtonElement> {
   isPressed?: boolean;
 
   /**
-   * Called when the pressed state should change.
+   * Called when the pressed state should change. Receives the next pressed
+   * state and the originating click event. Call `event.preventDefault()` to
+   * opt out of running `pressedChangeAction` (e.g. to handle the toggle
+   * entirely in this callback).
    * When used inside ToggleButtonGroup, this is handled by the group
    * and this prop is ignored.
    */
-  onPressedChange?: (isPressed: boolean) => void;
+  onPressedChange?: (
+    isPressed: boolean,
+    event: React.MouseEvent<HTMLButtonElement>,
+  ) => 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 by Button. 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).
    *
    * @example
    * ```
@@ -106,7 +114,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 +226,62 @@ 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 so the button reflects the intended
+  // state immediately while an async action is pending. The optimistic update
+  // is applied inside Button's clickAction transition (below), satisfying
+  // React's "useOptimistic must run in a transition" rule.
+  const [optimisticPressed, setOptimisticPressed] =
+    useOptimistic(committedPressed);
+  const isPressed = optimisticPressed;
+
+  // Next state derives from the *optimistic* value, not the committed one, so a
+  // re-click while an action is pending reads the in-flight intent and toggles
+  // (true -> false -> true) rather than recomputing from the stale committed
+  // state. handleClick and clickAction share this so the callback and the
+  // optimistic update always agree within a single click.
+  const nextPressed = !isPressed;
+
   const resolvedIcon = isPressed && pressedIcon ? pressedIcon : icon;
 
-  const handleClick = useCallback(() => {
-    if (isDisabled || isLoading) {
+  // Synchronous part of the toggle. Button calls onClick before clickAction and
+  // skips clickAction when the event is defaultPrevented, so calling
+  // preventDefault() inside onPressedChange opts out of pressedChangeAction.
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    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);
-      }
+      event.preventDefault();
+      return;
     }
-  }, [
-    isDisabled,
-    isLoading,
-    group,
-    value,
-    onPressedChangeProp,
-    pressedChangeAction,
-    isPressed,
-  ]);
-
-  // Label with font weight shift and width reservation
+    onPressedChangeProp?.(nextPressed, event);
+  };
+
+  // Async part of the toggle, run inside Button's transition (so the optimistic
+  // update is valid and Button's isPending drives the pending spinner). Skipped
+  // automatically by Button when handleClick called preventDefault, and never
+  // wired in group mode (where there is no async action). Button is rendered
+  // interruptible, so it stays clickable while pending and a re-click starts a
+  // fresh transition that interrupts the previous one.
+  const clickAction =
+    group && value != null
+      ? undefined
+      : async () => {
+          setOptimisticPressed(nextPressed);
+          await pressedChangeAction?.(nextPressed);
+        };
+
   // isIconOnly prop is the source of truth for icon-only rendering.
   const labelContent =
     children != null ? (
@@ -290,6 +314,7 @@ export function ToggleButton({
       size={size}
       isDisabled={isDisabled}
       isLoading={isLoading}
+      isInterruptible
       isIconOnly={isIconOnly}
       aria-pressed={isPressed}
       icon={resolvedIcon}
@@ -300,6 +325,7 @@ export function ToggleButton({
       xstyle={[isPressed ? pressedStyles.background : undefined, xstyle]}
       style={style}
       onClick={handleClick}
+      clickAction={clickAction}
       {...props}>
       {labelContent}
     </Button>

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.' },