@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -179,11 +179,16 @@ export function BreadcrumbItem({
   className,
   style,
   'data-testid': testId,
+  ...rest
 }: BreadcrumbItemProps) {
   const ctx = use(BreadcrumbContext);
   const LinkComponent = useLinkComponent(as);
   const isSupporting = ctx.variant === 'supporting';
   const liRef = useRef<HTMLLIElement>(null);
+  // Points at the element we render to hold the item's content (the
+  // link/button/span in the auto-candidate path). Auto-current detection sets
+  // aria-current on this instead of guessing the <li>'s last child.
+  const contentRef = useRef<HTMLElement>(null);
 
   const isCurrent = isCurrentProp === true;
   const isAutoCandidate = isCurrentProp == null;
@@ -191,6 +196,10 @@ export function BreadcrumbItem({
   // Auto-detect: if no sibling has aria-current="page" and this is the last
   // non-separator item, set aria-current on our content element.
   // Runs as useEffect (not layout) — only sets an aria attribute, no visual change.
+  // Placed on the item's content element (the link/button/span after the
+  // separator), matching where the explicit `isCurrent` path sets it, so
+  // aria-current lands on the actual interactive element — including when the
+  // last item is a link — rather than on the outer <li> (navigation-11).
   useEffect(() => {
     if (!isAutoCandidate) {
       return;
@@ -211,12 +220,16 @@ export function BreadcrumbItem({
     const hasExplicit = ol.querySelector('[aria-current="page"]');
 
     if (isLast && !hasExplicit) {
-      li.setAttribute('aria-current', 'page');
+      // We control the element that holds the content (see the auto-candidate
+      // render path below), so set aria-current on that ref rather than
+      // assuming a positional last child. Fall back to the <li> only if the
+      // ref is somehow unresolved.
+      const target = contentRef.current ?? li;
+      target.setAttribute('aria-current', 'page');
+      return () => {
+        target.removeAttribute('aria-current');
+      };
     }
-
-    return () => {
-      li.removeAttribute('aria-current');
-    };
   });
 
   const content = (
@@ -240,7 +253,8 @@ export function BreadcrumbItem({
           className,
           style,
         )}
-        data-testid={testId}>
+        data-testid={testId}
+        {...rest}>
         <span aria-hidden="true" {...stylex.props(itemStyles.separator)}>
           {ctx.separator}
         </span>
@@ -274,12 +288,14 @@ export function BreadcrumbItem({
         className,
         style,
       )}
-      data-testid={testId}>
+      data-testid={testId}
+      {...rest}>
       <span aria-hidden="true" {...stylex.props(itemStyles.separator)}>
         {ctx.separator}
       </span>
       {href != null ? (
         <LinkComponent
+          ref={contentRef}
           href={href}
           onClick={onClick}
           {...stylex.props(
@@ -290,6 +306,7 @@ export function BreadcrumbItem({
         </LinkComponent>
       ) : onClick != null ? (
         <button
+          ref={contentRef as React.RefObject<HTMLButtonElement | null>}
           type="button"
           onClick={onClick}
           {...stylex.props(
@@ -301,6 +318,7 @@ export function BreadcrumbItem({
         </button>
       ) : (
         <span
+          ref={contentRef}
           {...stylex.props(
             itemStyles.contentWrapper,
             itemStyles.current,

package/src/Breadcrumbs/Breadcrumbs.test.tsx

@@ -180,12 +180,31 @@ describe('BreadcrumbItem', () => {
         <BreadcrumbItem>Last Item</BreadcrumbItem>
       </Breadcrumbs>,
     );
-    // aria-current is set via useEffect, so we need to wait for it
-    const lastLi = screen.getByText('Last Item').closest('li')!;
+    // aria-current is set via useEffect on the content element (matching the
+    // explicit isCurrent path), not the outer <li>.
+    const lastContent = screen.getByText('Last Item');
     await waitFor(() => {
-      expect(lastLi).toHaveAttribute('aria-current', 'page');
+      expect(lastContent).toHaveAttribute('aria-current', 'page');
     });
-    expect(screen.getByText('Last Item').tagName).toBe('SPAN');
+    expect(lastContent.tagName).toBe('SPAN');
+    // The <li> wrapper must NOT carry aria-current.
+    expect(lastContent.closest('li')).not.toHaveAttribute('aria-current');
+  });
+
+  it('auto-detects aria-current on the anchor when the last item is a link', async () => {
+    render(
+      <Breadcrumbs>
+        <BreadcrumbItem href="/">Home</BreadcrumbItem>
+        <BreadcrumbItem href="/projects/current">Current</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    const lastLink = screen.getByText('Current');
+    await waitFor(() => {
+      expect(lastLink).toHaveAttribute('aria-current', 'page');
+    });
+    // aria-current is on the anchor itself, not the <li>.
+    expect(lastLink.tagName).toBe('A');
+    expect(lastLink.closest('li')).not.toHaveAttribute('aria-current');
   });
 
   it('does not auto-detect when isCurrent is explicitly set', async () => {
@@ -270,11 +289,12 @@ describe('BreadcrumbItem', () => {
         <BreadcrumbItem>Only Item</BreadcrumbItem>
       </Breadcrumbs>,
     );
-    const li = screen.getByText('Only Item').closest('li')!;
+    const content = screen.getByText('Only Item');
     await waitFor(() => {
-      expect(li).toHaveAttribute('aria-current', 'page');
+      expect(content).toHaveAttribute('aria-current', 'page');
     });
-    expect(screen.getByText('Only Item').tagName).toBe('SPAN');
+    expect(content.tagName).toBe('SPAN');
+    expect(content.closest('li')).not.toHaveAttribute('aria-current');
   });
 
   it('auto-detects last child as current with supporting variant', async () => {
@@ -284,11 +304,12 @@ describe('BreadcrumbItem', () => {
         <BreadcrumbItem>Last</BreadcrumbItem>
       </Breadcrumbs>,
     );
-    const li = screen.getByText('Last').closest('li')!;
+    const content = screen.getByText('Last');
     await waitFor(() => {
-      expect(li).toHaveAttribute('aria-current', 'page');
+      expect(content).toHaveAttribute('aria-current', 'page');
     });
-    expect(screen.getByText('Last').tagName).toBe('SPAN');
+    expect(content.tagName).toBe('SPAN');
+    expect(content.closest('li')).not.toHaveAttribute('aria-current');
   });
 
   it('renders custom component for non-current items when as is provided', () => {

package/src/Button/Button.doc.mjs

@@ -78,6 +78,12 @@ export const docs = {
       description: 'Shows a loading spinner and disables interaction. Announces "Loading" via a live region.',
       default: 'false',
     },
+    {
+      name: 'isInterruptible',
+      type: 'boolean',
+      description: 'Keep the button clickable while a clickAction is pending: the spinner and aria-busy still show, but the button is not disabled and the action is not deduped, so a re-click lands and interrupts the in-flight action with a fresh one.',
+      default: 'false',
+    },
     {
       name: 'isDisabled',
       type: 'boolean',

package/src/Button/Button.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Button} from './Button';
 import {Badge} from '../Badge/Badge';
@@ -71,6 +71,32 @@ describe('Button', () => {
     expect(button).toBeDisabled();
   });
 
+  it('sets aria-busy synchronously while clickAction is pending', async () => {
+    // The spinner reveal is visually delayed (CSS animation-delay), but the
+    // loading DOM state — aria-busy and disabled — must not be delayed.
+    const user = userEvent.setup();
+    let resolveAction: (() => void) | undefined;
+    const clickAction = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          resolveAction = resolve;
+        }),
+    );
+    render(<Button label="Save" clickAction={clickAction} />);
+    const button = screen.getByRole('button');
+
+    await user.click(button);
+    expect(button).toHaveAttribute('aria-busy', 'true');
+    expect(button).toBeDisabled();
+
+    await act(async () => {
+      resolveAction?.();
+      await Promise.resolve();
+    });
+    expect(button).not.toHaveAttribute('aria-busy', 'true');
+    expect(button).not.toBeDisabled();
+  });
+
   it('renders the loading spinner with the inherit shade for every variant (#2717)', () => {
     // The spinner must follow the button's resolved foreground color rather
     // than a hardcoded white, so it keeps contrast on themed variants like the
@@ -228,11 +254,7 @@ describe('Button', () => {
       order.push('clickAction');
     });
     render(
-      <Button
-        label="Test"
-        onClick={handleClick}
-        clickAction={handleAction}
-      />,
+      <Button label="Test" onClick={handleClick} clickAction={handleAction} />,
     );
 
     await user.click(screen.getByRole('button'));
@@ -246,11 +268,7 @@ describe('Button', () => {
     const handleClick = vi.fn((e: React.MouseEvent) => e.preventDefault());
     const handleAction = vi.fn();
     render(
-      <Button
-        label="Test"
-        onClick={handleClick}
-        clickAction={handleAction}
-      />,
+      <Button label="Test" onClick={handleClick} clickAction={handleAction} />,
     );
 
     await user.click(screen.getByRole('button'));
@@ -258,6 +276,82 @@ describe('Button', () => {
     expect(handleAction).not.toHaveBeenCalled();
   });
 
+  it('fires clickAction once on a fast double-click (no double-submit)', async () => {
+    let resolveAction: (() => void) | undefined;
+    const handleAction = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          resolveAction = resolve;
+        }),
+    );
+    render(<Button label="Pay" clickAction={handleAction} />);
+
+    const button = screen.getByRole('button');
+    await act(async () => {
+      fireEvent.click(button);
+      fireEvent.click(button);
+    });
+    expect(handleAction).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      resolveAction?.();
+      await Promise.resolve();
+    });
+  });
+
+  it('stays clickable (not disabled) while a clickAction is pending when isInterruptible', async () => {
+    const user = userEvent.setup();
+    let resolveAction: (() => void) | undefined;
+    const clickAction = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          resolveAction = resolve;
+        }),
+    );
+    render(<Button label="Toggle" isInterruptible clickAction={clickAction} />);
+    const button = screen.getByRole('button');
+
+    await user.click(button);
+    // Loading is announced via aria-busy, but the button is not disabled so it
+    // can be re-clicked to interrupt the in-flight action.
+    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('re-fires clickAction on re-click while pending when isInterruptible (no dedupe)', async () => {
+    // Unlike the fire-once default, an interruptible action is not deduped: a
+    // re-click while pending starts a fresh action that interrupts the prior.
+    const resolvers: (() => void)[] = [];
+    const clickAction = vi.fn(
+      async () =>
+        new Promise<void>(resolve => {
+          resolvers.push(resolve);
+        }),
+    );
+    render(<Button label="Toggle" isInterruptible clickAction={clickAction} />);
+
+    const button = screen.getByRole('button');
+    await act(async () => {
+      fireEvent.click(button);
+    });
+    await act(async () => {
+      fireEvent.click(button);
+    });
+    expect(clickAction).toHaveBeenCalledTimes(2);
+
+    await act(async () => {
+      resolvers.forEach(resolve => resolve());
+      await Promise.resolve();
+    });
+  });
+
   // type/name/value/form props
   it('defaults type to button', () => {
     render(<Button label="Test" />);

package/src/Button/Button.tsx

@@ -15,7 +15,7 @@
  * - /apps/storybook/stories/Button.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/Button/ (showcase blocks)
  *
- * Last synced props: label, variant, size, isDisabled, isLoading, clickAction, icon, isIconOnly, children, tooltip, endContent, href, as, target, rel
+ * Last synced props: label, variant, size, isDisabled, isLoading, isInterruptible, clickAction, icon, isIconOnly, children, tooltip, endContent, href, as, target, rel
  */
 
 import {useRef, useTransition, type ReactNode} from 'react';
@@ -34,6 +34,7 @@ import {
 } from '../theme/tokens.stylex';
 import {Tooltip} from '../Tooltip/Tooltip';
 import {Spinner} from '../Spinner';
+import {VisuallyHidden} from '../VisuallyHidden';
 
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {useSize} from '../SizeContext/SizeContext';
@@ -124,17 +125,6 @@ const styles = stylex.create({
     textOverflow: 'ellipsis',
     minWidth: 0,
   },
-  visuallyHidden: {
-    position: 'absolute',
-    width: '1px',
-    height: '1px',
-    padding: 0,
-    margin: '-1px',
-    overflow: 'hidden',
-    clip: 'rect(0, 0, 0, 0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
   link: {
     textDecoration: 'none',
   },
@@ -320,6 +310,16 @@ export interface ButtonProps extends BaseProps<HTMLButtonElement> {
    * @default false
    */
   isLoading?: boolean;
+  /**
+   * Keep the button interactive while a `clickAction` is pending. The loading
+   * state still renders the spinner and `aria-busy`, but the button is not
+   * disabled and the in-flight action is not deduped — so a re-click lands and
+   * interrupts the previous action with a fresh one. Use for interruptible
+   * actions (e.g. a toggle whose action can be re-triggered before the previous
+   * one settles), not fire-once actions (submit/save/pay).
+   * @default false
+   */
+  isInterruptible?: boolean;
   /**
    * Click handler. For async actions that should show a loading state,
    * use `clickAction` instead.
@@ -380,6 +380,22 @@ export interface ButtonProps extends BaseProps<HTMLButtonElement> {
   rel?: string;
 }
 
+const spinnerReveal = stylex.keyframes({
+  from: {opacity: 0},
+  to: {opacity: 1},
+});
+
+const contentHide = stylex.keyframes({
+  from: {color: 'inherit'},
+  to: {color: 'transparent'},
+});
+
+// Hold the loading swap for a short delay so a fast action (e.g. clickAction)
+// that settles within the delay never flashes a spinner. The spinner fade-in
+// and the content hide share the same delay so the button never shows an empty
+// frame in between. Reduced motion is instant.
+const SPINNER_DELAY = durationVars['--duration-medium-min'];
+
 const loadingStyles = stylex.create({
   // Hide the button's own content while the spinner overlay is shown. Applied
   // to the content wrapper (not the button) so the button keeps its variant
@@ -387,6 +403,17 @@ const loadingStyles = stylex.create({
   hiddenContent: {
     color: 'transparent',
   },
+  // Delayed variant: keep content visible, then hide it in lockstep with the
+  // spinner reveal once the delay elapses.
+  hiddenContentDelayed: {
+    animationName: contentHide,
+    animationDuration: '1ms',
+    animationFillMode: 'forwards',
+    animationDelay: {
+      default: SPINNER_DELAY,
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+  },
   spinnerOverlay: {
     position: 'absolute',
     top: 0,
@@ -396,6 +423,15 @@ const loadingStyles = stylex.create({
     display: 'grid',
     placeItems: 'center',
   },
+  spinnerDelayed: {
+    animationName: spinnerReveal,
+    animationDuration: durationVars['--duration-fast'],
+    animationFillMode: 'backwards',
+    animationDelay: {
+      default: SPINNER_DELAY,
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+  },
 });
 
 const groupStyles = stylex.create({
@@ -493,6 +529,7 @@ export function Button({
   type = 'button',
   isDisabled = false,
   isLoading = false,
+  isInterruptible = false,
   clickAction,
   icon,
   isIconOnly = false,
@@ -513,10 +550,23 @@ export function Button({
   const buttonGroup = useButtonGroup();
 
   const [isPending, startTransition] = useTransition();
+  // clickAction is normally fire-once (submit/save/pay), so a same-tick
+  // double-click must dedupe — which neither isPending nor useOptimistic do.
+  // Hence the ref guard. Interruptible callers (e.g. ToggleButton) opt out so a
+  // re-click can land and interrupt the in-flight action with a fresh one.
   const actionInFlightRef = useRef(false);
   const isLoadingState = isLoading || isPending;
+  // Delay the spinner reveal for action-driven loading (clickAction's own
+  // transition) so a fast action that settles within the delay does not flash
+  // a spinner. Interruptible loading is delayed too, so rapid re-clicks settle
+  // before any spinner shows. Explicit isLoading-only stays immediate, since
+  // the consumer is deliberately showing it.
+  const delaySpinner = isPending || isInterruptible;
   const groupDisabled = buttonGroup?.isDisabled ?? false;
-  const buttonDisabled = isDisabled || groupDisabled || isLoadingState;
+  // When interruptible, the loading state drives the spinner and aria-busy but
+  // not disabled, so clicks keep landing and can interrupt the in-flight action.
+  const buttonDisabled =
+    isDisabled || groupDisabled || (isLoadingState && !isInterruptible);
   // isIconOnly prop is the source of truth for icon-only rendering.
   // When false (default), label is always rendered as visible text.
 
@@ -531,7 +581,9 @@ export function Button({
   const useAriaDisabled = tooltip != null && buttonDisabled;
 
   const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
-    if (buttonDisabled || actionInFlightRef.current) {
+    // The ref guard dedupes fire-once actions. Interruptible callers skip it so
+    // a re-click while pending starts a fresh action that interrupts the prior.
+    if (buttonDisabled || (actionInFlightRef.current && !isInterruptible)) {
       e.preventDefault();
       return;
     }
@@ -598,7 +650,10 @@ export function Button({
     <>
       {isLoadingState && (
         <span
-          {...stylex.props(loadingStyles.spinnerOverlay)}
+          {...stylex.props(
+            loadingStyles.spinnerOverlay,
+            delaySpinner && loadingStyles.spinnerDelayed,
+          )}
           aria-hidden="true">
           <Spinner size="sm" shade="inherit" />
         </span>
@@ -606,7 +661,10 @@ export function Button({
       <span
         {...stylex.props(
           styles.contentWrapper,
-          isLoadingState && loadingStyles.hiddenContent,
+          isLoadingState &&
+            (delaySpinner
+              ? loadingStyles.hiddenContentDelayed
+              : loadingStyles.hiddenContent),
         )}
         aria-hidden={isLoadingState || undefined}>
         {icon && (
@@ -622,12 +680,9 @@ export function Button({
         )}
       </span>
       {/* Live region for loading state announcements */}
-      <span
-        {...stylex.props(styles.visuallyHidden)}
-        role="status"
-        aria-live="polite">
+      <VisuallyHidden role="status" aria-live="polite">
         {isLoadingState ? 'Loading' : ''}
-      </span>
+      </VisuallyHidden>
     </>
   );
 

package/src/Calendar/Calendar.doc.mjs

@@ -103,8 +103,8 @@ export const docs = {
     },
     {
       name: 'weekStartsOn',
-      type: '0 | 1 | 2 | 3 | 4 | 5 | 6',
-      description: 'First day of week (0=Sunday).',
+      type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
+      description: 'First day of week. Accepts a number (0=Sunday) or a three-letter day name (e.g. "mon").',
       default: '0',
     },
   ],
@@ -147,7 +147,7 @@ export const docsZh = {
     {name: 'hasOutsideDays', type: 'boolean', description: '显示相邻月份的日期。', default: 'true'},
     {name: 'hasWeekNumbers', type: 'boolean', description: '显示 ISO 周数。', default: 'false'},
     {name: 'hasVariableRowCount', type: 'boolean', description: '可变行数与固定 6 行网格。', default: 'false'},
-    {name: 'weekStartsOn', type: '0 | 1 | 2 | 3 | 4 | 5 | 6', description: '每周起始日（0=周日）。', default: '0'},
+    {name: 'weekStartsOn', type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'", description: '每周起始日。可为数字（0=周日）或三字母星期缩写（如 "mon"）。', default: '0'},
   ],
   theming: {
     targets: [
@@ -200,6 +200,6 @@ export const docsDense = {
     hasOutsideDays: 'show days from adjacent months',
     hasWeekNumbers: 'show ISO week numbers',
     hasVariableRowCount: 'variable vs fixed 6-row grid',
-    weekStartsOn: 'first day of week (0=Sunday)',
+    weekStartsOn: 'first day of week (0=Sunday, or name e.g. "mon")',
   },
 };