@astryxdesign/core 0.1.0 → 0.1.1

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

package/src/theme/tokens.ts

@@ -16,7 +16,7 @@
  */
 
 import {
-  xdsTokenDefaults,
+  tokenDefaults,
   type DefinedTheme,
   type TokenName,
   type TokenValue,
@@ -60,7 +60,7 @@ export function tokenVar(name: TokenName | (string & {})): string {
 
 /** Flat map of every known Astryx token name to its `var(--token-name)` reference. */
 export const tokenVars: Record<TokenName, string> = Object.fromEntries(
-  Object.keys(xdsTokenDefaults).map(name => [name, tokenVar(name)]),
+  Object.keys(tokenDefaults).map(name => [name, tokenVar(name)]),
 ) as Record<TokenName, string>;
 
 /**
@@ -147,7 +147,7 @@ function resolveXDSTokenValue(
 /**
  * Resolve all Astryx token values for a theme and effective color mode.
  *
- * The result starts with `xdsTokenDefaults`, applies `theme.tokens`, then
+ * The result starts with `tokenDefaults`, applies `theme.tokens`, then
  * reapplies `theme.__inputTokens` when available so explicit tuple overrides
  * retain their original light/dark sides instead of relying on CSS parsing.
  * This mirrors the token resolution used by `useTheme()` but does not need
@@ -162,7 +162,7 @@ export function resolveThemeTokens(
   const {mode} = options;
   const resolved: Record<string, string> = {};
 
-  for (const [key, value] of Object.entries(xdsTokenDefaults)) {
+  for (const [key, value] of Object.entries(tokenDefaults)) {
     resolved[key] = resolveXDSTokenValue(value, mode);
   }
 

package/src/theme/useTheme.ts

@@ -63,7 +63,7 @@ export interface UseThemeReturn {
    * For tokens with [light, dark] tuples, returns the value matching
    * the current mode. For single-value tokens, returns the value as-is.
    *
-   * Falls back to xdsTokenDefaults if the token isn't overridden by the theme.
+   * Falls back to tokenDefaults if the token isn't overridden by the theme.
    *
    * @example
    * ```
@@ -75,7 +75,7 @@ export interface UseThemeReturn {
   /**
    * All tokens resolved for the current color mode.
    *
-   * Merges xdsTokenDefaults with the theme's overrides, resolving
+   * Merges tokenDefaults with the theme's overrides, resolving
    * light-dark() values based on the effective color mode.
    *
    * Memoized — stable reference unless theme or mode changes.

package/src/utils/dateParser.test.ts

@@ -320,5 +320,31 @@ describe('parseDateInput', () => {
     it('rejects mixed separators', () => {
       expect(parseDateInput('1/25.2026')).toBeNull();
     });
+
+    it('treats a single typed digit as incomplete, not a date', () => {
+      // A user starting to type a month (e.g. "0" or "1" for January) should
+      // not produce a date. Native Date parsing would otherwise coerce these
+      // into arbitrary dates (and a year of 0 in some engines).
+      expect(parseDateInput('0')).toBeNull();
+      expect(parseDateInput('1')).toBeNull();
+    });
+
+    it('treats bare numeric input as incomplete, not a date', () => {
+      expect(parseDateInput('00')).toBeNull();
+      expect(parseDateInput('01')).toBeNull();
+      expect(parseDateInput('12')).toBeNull();
+      expect(parseDateInput('2026')).toBeNull();
+    });
+
+    it('never returns an out-of-range date for partial input', () => {
+      // Regression: partial input must never yield a date with year < 1,
+      // which would throw when later re-parsed and crash the page.
+      for (const input of ['0', '1', '01', '00', '9', '99']) {
+        const result = parseDateInput(input);
+        if (result !== null) {
+          expect(result.year).toBeGreaterThanOrEqual(1);
+        }
+      }
+    });
   });
 });

package/src/utils/dateParser.ts

@@ -124,10 +124,24 @@ export function parseDateInput(input: string): PlainDate | null {
     return parseNumericDate(+first, +second, currentYear);
   }
 
-  // 6. Fall back to native Date parsing for other formats
+  // 6. Fall back to native Date parsing for other formats.
+  //
+  // Skip bare numeric input (e.g. "0", "1", "01", "2026"). These are
+  // in-progress values a user is still typing, not complete dates. Native
+  // `Date` parsing coerces them into arbitrary dates ("0" -> year 2000 in V8,
+  // year 0 in some engines), which is both surprising and — when the year
+  // resolves to 0 — produces an out-of-range date that throws downstream.
+  // Treat them as not-yet-a-valid-date instead.
+  if (/^\d+$/.test(trimmed)) {
+    return null;
+  }
+
   const parsed = new Date(trimmed);
   if (!isNaN(parsed.getTime())) {
-    return plainDateFromDate(parsed);
+    const fromDate = plainDateFromDate(parsed);
+    // Validate the result so we never return an out-of-range date (e.g. a
+    // year of 0), which would throw when later re-parsed.
+    return tryCreatePlainDate(fromDate.year, fromDate.month, fromDate.day);
   }
 
   return null;

package/dist/DropdownMenu/renderXDSDropdownItems.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"renderXDSDropdownItems.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/renderXDSDropdownItems.tsx"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAUrC,OAAO,KAAK,EAEV,kBAAkB,EAEnB,MAAM,gBAAgB,CAAC;AAyBxB;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EAAE,GAC1B,SAAS,CA8CX"}