@astryxdesign/core 0.7.1 → 0.7.2-canary.020e1fe

package/src/Button/Button.tsx

@@ -594,26 +594,37 @@ export function Button({
   // the consumer is deliberately showing it.
   const delaySpinner = isPending || isInterruptible;
   const groupDisabled = buttonGroup?.isDisabled ?? false;
-  // 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);
-  // A loading button remains non-interactive, but its spinner communicates an
-  // active state and must retain contrast. Only explicitly disabled controls
-  // receive the visually dimmed treatment.
-  const visuallyDisabled = isDisabled || groupDisabled;
+  const isTrueDisabled = isDisabled || groupDisabled;
+  // Busy-only: the button can't fire again purely because an action is in
+  // flight, not because it's genuinely isDisabled/group-disabled. Per the API
+  // Conventions "Disabled vs Busy" rule, busy is visual-only (aria-busy +
+  // spinner) and must never take focusability away — the click-handler ref
+  // guard (actionInFlightRef) is what actually makes a fire-once action fire
+  // once, so the native disabled attribute adds nothing but a focus loss
+  // here. When interruptible, the loading state drives the spinner and
+  // aria-busy but not disabled at all, so clicks keep landing and can
+  // interrupt the in-flight action.
+  const isBusyOnlyDisabled =
+    !isTrueDisabled && isLoadingState && !isInterruptible;
+  const buttonDisabled = isTrueDisabled || isBusyOnlyDisabled;
   // isIconOnly prop is the source of truth for icon-only rendering.
   // When false (default), label is always rendered as visible text.
 
   const LinkComponent = useLinkComponent(as);
 
-  // Render as link when href is provided and button is not disabled.
-  // Disabled links are an accessibility anti-pattern — fall back to <button>.
-  const renderAsLink = href != null && !buttonDisabled;
+  // Render as link when href is provided and the button is not TRULY
+  // disabled. Disabled links are an accessibility anti-pattern, so a
+  // genuinely isDisabled/group-disabled button falls back to <button>.
+  // Busy-only does NOT fall back: swapping <a> for a disabled <button>
+  // mid-action would drop focus the same way the native attribute does
+  // (credit @AKnassa, #4879), which is exactly the bug this PR fixes.
+  const renderAsLink = href != null && !isTrueDisabled;
 
-  // Use aria-disabled when tooltip is present so the button remains focusable
-  // for keyboard users to reach the tooltip. Otherwise use native disabled.
-  const useAriaDisabled = tooltip != null && buttonDisabled;
+  // Use aria-disabled (button stays focusable) when busy-only, or when a
+  // tooltip is present so keyboard users can still reach it. A genuinely
+  // isDisabled/group-disabled button (not busy) keeps native disabled.
+  const useAriaDisabled =
+    buttonDisabled && (isBusyOnlyDisabled || tooltip != null);
 
   // Attach tooltip behavior via the hook rather than wrapping the button in a
   // <Tooltip> element. The hook adds hover/focus triggers to the button itself,
@@ -630,6 +641,16 @@ export function Button({
     // a re-click while pending starts a fresh action that interrupts the prior.
     if (buttonDisabled || (actionInFlightRef.current && !isInterruptible)) {
       e.preventDefault();
+      // A native `disabled` element never dispatches a click at all, so it
+      // never reaches a wrapping element's own handler either. An
+      // aria-disabled button (busy-only, or with a tooltip) is still a real,
+      // interactive element the DOM keeps dispatching clicks on —
+      // preventDefault alone only cancels the button's OWN default action
+      // (form submit, link navigation), not propagation. Without this, an
+      // unavailable Button inside a clickable row/card/backdrop still
+      // triggers that ancestor's action, which the previously native-disabled
+      // control never did.
+      e.stopPropagation();
       return;
     }
     props.onClick?.(e);
@@ -669,7 +690,7 @@ export function Button({
     isIconOnly && styles.iconOnly,
     interactionOverlayStyles.backgroundImage,
     buttonDisabled && styles.inactive,
-    visuallyDisabled && styles.disabled,
+    isTrueDisabled && styles.disabled,
     useAriaDisabled && styles.ariaDisabled,
     renderAsLink && styles.link,
     !buttonGroup && styles.pressable,
@@ -797,7 +818,9 @@ export function Button({
         {...describedByProp}
         {...edgeCompAttr}
         aria-busy={isLoadingState || undefined}
-        onClick={handleClick}>
+        aria-disabled={useAriaDisabled || undefined}
+        onClick={handleClick}
+        {...(handleKeyDown ? {onKeyDown: handleKeyDown} : null)}>
         {buttonContent}
       </LinkComponent>
     );

package/src/Button/__tests__/Button.a11y.known-failures.ts

@@ -22,65 +22,4 @@
 
 import type {KnownFailure} from '@astryxdesign/a11y-spec';
 
-export const BUTTON_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
-  // ---- Button and IconButton go natively disabled while busy --------------
-  // One defect, one record per component.
-  // They are written out rather than generated, because a record has to name
-  // exactly one thing that is broken — a loop would make it easy to widen this
-  // later without anyone noticing.
-  {
-    expectation: 'button.focus.reachable-and-escapable',
-    binding: 'Button',
-    state: 'button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      '10 presses of Tab from the start of the document never reached the button, so a keyboard user cannot get to this action',
-    standardsReference:
-      'WCAG 2.2 2.1.1 Keyboard and 2.1.2 No Keyboard Trap (Level A)',
-    userImpact:
-      'A keyboard user who activates Save and waits is dropped to the top of the document the moment the action starts, and the button leaves the tab sequence entirely — so they cannot get back to it, to see that it is busy or to interrupt it. The next Tab restarts from the beginning of the page.',
-    reason:
-      'Button sets the native disabled attribute while a clickAction is pending. A natively disabled element is neither focusable nor a tab stop. Separate implementation work will turn this record into an unexpected pass.',
-  },
-  {
-    expectation: 'button.focus.reachable-and-escapable',
-    binding: 'IconButton',
-    state: 'icon-button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      '10 presses of Tab from the start of the document never reached the button, so a keyboard user cannot get to this action',
-    standardsReference:
-      'WCAG 2.2 2.1.1 Keyboard and 2.1.2 No Keyboard Trap (Level A)',
-    userImpact:
-      'The same drop from an icon button, where it is worse: an icon button is usually one of several in a row, so the user loses their place among them.',
-    reason:
-      'IconButton is a thin wrapper over Button and inherits the behaviour exactly.',
-  },
-
-  {
-    expectation: 'button.unavailable.inert',
-    binding: 'Button',
-    state: 'button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'this state is declared focusable so its reason stays reachable, but it cannot take focus — so a keyboard user can neither read why it is unavailable nor reach it to confirm it refuses to act',
-    standardsReference:
-      'Current Astryx family:buttons FR3 and WAI-ARIA APG Button unavailable-state requirement; supports WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
-    userImpact:
-      'The third face of the same defect: because the busy button cannot take focus, there is no way to confirm from the keyboard that it declines a second press — the user can neither reach it nor see why it is unavailable.',
-    reason:
-      'Same native disabled attribute. Recorded separately because a record names exactly one outcome, and a fix that restored focus without keeping the button inert would satisfy one of these and not the other.',
-  },
-  {
-    expectation: 'button.unavailable.inert',
-    binding: 'IconButton',
-    state: 'icon-button-loading',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'this state is declared focusable so its reason stays reachable, but it cannot take focus — so a keyboard user can neither read why it is unavailable nor reach it to confirm it refuses to act',
-    standardsReference:
-      'Current Astryx family:buttons FR3 and WAI-ARIA APG Button unavailable-state requirement; supports WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
-    userImpact: 'The same, from an icon button.',
-    reason: 'Inherited from Button, as above.',
-  },
-];
+export const BUTTON_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];

package/src/Button/__tests__/Button.a11y.states.ts

@@ -177,16 +177,9 @@ export const BUTTON_BINDING_STATES = [
     binding: 'Button',
     summary:
       'a button waiting on the action it started: the action is unavailable, and it is meant to stay focusable so the user can see that and interrupt it',
-    // `focusable: true` is the declaration, and the component does not deliver
-    // it — see the known-failure records. Declaring what the component does
-    // instead would make the expectations that catch it not-applicable, which
-    // is how a contract quietly stops noticing a defect.
     facts: facts({operable: false, unavailable: true}),
     visibleLabel: null,
     storyId: 'a11y-button-pattern--button-loading',
-    declaredNotDelivered: [
-      {fact: 'focusable', owned: 'button.focus.reachable-and-escapable'},
-    ],
   },
 
   // ---- IconButton ---------------------------------------------------------
@@ -214,9 +207,6 @@ export const BUTTON_BINDING_STATES = [
     facts: facts({operable: false, unavailable: true}),
     visibleLabel: null,
     storyId: 'a11y-button-pattern--icon-button-loading',
-    declaredNotDelivered: [
-      {fact: 'focusable', owned: 'button.focus.reachable-and-escapable'},
-    ],
   },
 
   // ---- ClickableCard ------------------------------------------------------

package/src/Card/Card.doc.mjs

@@ -83,7 +83,7 @@ export const docs = {
       code: `
 import {Card} from '@astryxdesign/core/Card';
 import {Grid} from '@astryxdesign/core/Grid';
-import {VStack} from '@astryxdesign/core/Layout';
+import {VStack} from '@astryxdesign/core/VStack';
 import {Heading} from '@astryxdesign/core/Heading';
 import {Text} from '@astryxdesign/core/Text';
 

package/src/Chat/__tests__/ChatMessageMetadata.a11y.chromium.spec.ts

@@ -395,7 +395,9 @@ test('captures narrow touch reflow in both modes', async ({browser}) => {
   try {
     const page = await context.newPage();
     const scenario = CASES.find(item => item.name === 'narrow-overflow');
-    if (!scenario) {throw new Error('Narrow metadata fixture is missing');}
+    if (!scenario) {
+      throw new Error('Narrow metadata fixture is missing');
+    }
     const failures: string[] = [];
     for (const mode of ['light', 'dark'] as const) {
       failures.push(

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -209,6 +209,40 @@ describe('CheckboxInput', () => {
     );
   });
 
+  it('preserves a caller-provided id on the input and its label', () => {
+    render(
+      <CheckboxInput
+        id="accept-terms"
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox).toHaveAttribute('id', 'accept-terms');
+    expect(screen.getByText('Accept terms').closest('label')).toHaveAttribute(
+      'for',
+      'accept-terms',
+    );
+    expect(screen.getByLabelText('Accept terms')).toBe(checkbox);
+  });
+
+  it('generates an id the label resolves when the caller passes an empty id', () => {
+    render(
+      <CheckboxInput
+        id=""
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox.id).not.toBe('');
+    expect(screen.getByLabelText('Accept terms')).toBe(checkbox);
+  });
+
   it('forwards arbitrary data-* attributes to the input', () => {
     render(
       <CheckboxInput

package/src/CheckboxInput/CheckboxInput.tsx

@@ -311,6 +311,7 @@ const dynamicWidthStyles = stylex.create({
  * ```
  */
 export function CheckboxInput({
+  id: idProp,
   label,
   isLabelHidden = false,
   description,
@@ -340,7 +341,8 @@ export function CheckboxInput({
   // The row is the pressable: the overlay's pressed arm reads the row's
   // scope marker, the way the indicator's hover tint does.
   const pressable = usePressFeedback();
-  const id = useId();
+  const generatedId = useId();
+  const id = idProp || generatedId;
   const descriptionID = useId();
   const statusMessageID = useId();
   // Announce the effective required state (form default included) while the

package/src/CheckboxList/CheckboxList.test.tsx

@@ -59,6 +59,28 @@ beforeEach(() => {
 });
 
 describe('CheckboxList', () => {
+  it('forwards CheckboxListItem align to its Item row unchanged', () => {
+    render(
+      <CheckboxList label="Toppings" value={[]} onChange={() => {}}>
+        <CheckboxListItem label="Cheese" value="cheese" data-testid="cheese" />
+        <CheckboxListItem
+          label="Olives"
+          value="olives"
+          align="first-line"
+          data-testid="olives"
+        />
+      </CheckboxList>,
+    );
+    expect(screen.getByTestId('cheese')).toHaveAttribute(
+      'data-align',
+      'center',
+    );
+    expect(screen.getByTestId('olives')).toHaveAttribute(
+      'data-align',
+      'first-line',
+    );
+  });
+
   it('renders with label', () => {
     render(
       <CheckboxList label="Preferences" value={[]} onChange={() => {}}>

package/src/CheckboxList/CheckboxListItem.doc.mjs

@@ -55,6 +55,13 @@ export const docs = {
         },
       ],
     },
+    {
+      name: 'align',
+      type: "'center' | 'start' | 'first-line'",
+      description:
+        'Vertical alignment of the start and end content against the label, passed through to Item unchanged. `first-line` keeps a small mark (a checkbox) level with the first line of a wrapped label. See Item.align.',
+      default: "'center'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -130,6 +137,13 @@ export const docsZh = {
       type: 'ReactNode',
       description: '在标签区域后渲染的内容。',
     },
+    {
+      name: 'align',
+      type: "'center' | 'start' | 'first-line'",
+      description:
+        '起始和结束内容相对于标签的垂直对齐方式，原样传递给 Item。`first-line` 让小标记（复选框）与换行标签的第一行保持水平。参见 Item.align。',
+      default: "'center'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -165,6 +179,8 @@ export const docsDense = {
   description:
     'Individual checkbox item w/ label, description, end content slot. Collection mode inside CheckboxList with value; standalone inside List or CheckboxList without value.',
   propDescriptions: {
+    align:
+      "Start/end content alignment, passed to Item: 'center' (default), 'start', or 'first-line' (centered on the label's first line).",
     label:
       'Primary label. String or ReactNode; nested controls keep their behavior. A ReactNode names the checkbox from its visible text.',
     'aria-label':

package/src/CheckboxList/CheckboxListItem.tsx

@@ -29,6 +29,7 @@ import {ListContext} from '../List/ListContext';
 import {CheckboxListContext} from './CheckboxListContext';
 import {useTranslator} from '../i18n';
 import {ItemDescriptionContext} from '../Item/ItemDescriptionContext';
+import type {ItemAlign} from '../Item';
 
 // =============================================================================
 // Styles
@@ -45,6 +46,13 @@ const styles = stylex.create({
 // =============================================================================
 
 export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {
+  /**
+   * Vertical alignment of the start and end content against the label,
+   * forwarded to Item. Use `first-line` to keep the checkbox level with the
+   * first line of a wrapped label.
+   * @default 'center'
+   */
+  align?: ItemAlign;
   /**
    * Primary text label for the item.
    *
@@ -192,6 +200,7 @@ export function CheckboxListItem({
   className,
   style,
   onClick: onClickProp,
+  align,
   ...restProps
 }: CheckboxListItemProps) {
   const t = useTranslator();
@@ -297,6 +306,7 @@ export function CheckboxListItem({
       label={namesFromVisibleLabel ? <span id={labelID}>{label}</span> : label}
       description={description}
       endContent={endContent}
+      align={align}
       isDisabled={effectiveDisabled}
       // Delegate row clicks to the checkbox instead of wiring onClick (which
       // would add an invisible row button = a second tab stop). The checkbox

package/src/Code/Code.doc.mjs

@@ -4,6 +4,7 @@
 export const docs = {
   name: 'Code',
   displayName: 'Code',
+  keywords: ['inlinecode', 'monospace'],
   group: 'Code',
   category: 'Content',
   description:

package/src/CommandPalette/CommandPalette.doc.mjs

@@ -87,6 +87,8 @@ export const docs = {
     'modal',
     'dialog',
     'navigation',
+    'commandmenu',
+    'cmdk',
   ],
   description:
     'Root component. Manages open state, search, keyboard navigation, and composition slots.',

package/src/CommandPalette/CommandPaletteInput.test.tsx

@@ -8,12 +8,19 @@
  */
 
 import {createRef} from 'react';
-import {describe, it, expect, vi} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen, fireEvent, act} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
 import {CommandPaletteInput} from './CommandPaletteInput';
 import {CommandPaletteContext} from './CommandPaletteContext';
 import {Dialog} from '../Dialog';
 import type {CommandPaletteContextValue} from './CommandPaletteContext';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {__resetInteractionModalityForTest} from '../utils/interactionModality';
+
+beforeEach(() => {
+  __resetInteractionModalityForTest();
+});
 
 function makeContext(
   overrides: Partial<CommandPaletteContextValue> = {},
@@ -279,6 +286,45 @@ describe('CommandPaletteInput', () => {
     },
   );
 
+  it('draws the shared ring only when keyboard navigation acquired focus', () => {
+    render(<CommandPaletteInput hasAutoFocus={false} />);
+    const input = screen.getByRole('searchbox');
+    const ringClasses = stylex
+      .props(focusOutlineStyles.focusVisible)
+      .className!.split(' ');
+    const isRinged = () =>
+      ringClasses.every(className => input.classList.contains(className));
+
+    fireEvent.pointerDown(input);
+    fireEvent.focus(input);
+    expect(isRinged()).toBe(false);
+
+    fireEvent.blur(input);
+    fireEvent.keyDown(input, {key: 'Tab'});
+    fireEvent.focus(input);
+    expect(isRinged()).toBe(true);
+  });
+
+  it('preserves caller focus and blur handlers while tracking modality', () => {
+    const onFocus = vi.fn();
+    const onBlur = vi.fn();
+    render(
+      <CommandPaletteInput
+        hasAutoFocus={false}
+        onFocus={onFocus}
+        onBlur={onBlur}
+      />,
+    );
+    const input = screen.getByRole('searchbox');
+
+    fireEvent.keyDown(input, {key: 'Tab'});
+    fireEvent.focus(input);
+    fireEvent.blur(input);
+
+    expect(onFocus).toHaveBeenCalledTimes(1);
+    expect(onBlur).toHaveBeenCalledTimes(1);
+  });
+
   it('does not schedule focus when hasAutoFocus is false', async () => {
     const focusSpy = vi.spyOn(HTMLElement.prototype, 'focus');
     render(<CommandPaletteInput hasAutoFocus={false} />);
@@ -481,8 +527,11 @@ describe('CommandPaletteInput popup context', () => {
       </CommandPaletteContext>,
     );
 
-    await vi.waitFor(() => {
-      expect(screen.getByRole('combobox')).toHaveFocus();
+    await act(async () => {
+      await new Promise<void>(resolve =>
+        requestAnimationFrame(() => resolve()),
+      );
     });
+    expect(screen.getByRole('combobox')).toHaveFocus();
   });
 });

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -13,7 +13,7 @@
  * - /packages/cli/assets/templates/blocks/components/CommandPalette/ (showcase blocks)
  */
 
-import {useCallback, useEffect, useRef, type ReactNode} from 'react';
+import {useCallback, useEffect, useRef, useState, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -28,6 +28,11 @@ import {useCommandPaletteContext} from './CommandPaletteContext';
 import {useDialogContext} from '../Dialog/DialogContext';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {
+  getInteractionModality,
+  useInteractionModalityTracking,
+} from '../utils/interactionModality';
 import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
@@ -71,7 +76,6 @@ const styles = stylex.create({
     minWidth: 0,
     borderWidth: 0,
     borderStyle: 'none',
-    outline: 'none',
     backgroundColor: 'transparent',
     color: colorVars['--color-text-primary'],
     fontFamily: typographyVars['--font-family-body'],
@@ -169,6 +173,8 @@ export function CommandPaletteInput({
   endContent,
   onChange,
   onKeyDown,
+  onFocus,
+  onBlur,
   ref,
   xstyle,
   className,
@@ -184,6 +190,26 @@ export function CommandPaletteInput({
   const hasListbox = ctx ? ctx.selectableItems.length > 0 : true;
   const dialogContext = useDialogContext();
   const inputRef = useRef<HTMLInputElement>(null);
+  const [isKeyboardFocus, setIsKeyboardFocus] = useState(false);
+
+  // Text-entry controls match :focus-visible after pointer focus in Chromium.
+  // Keep the shared selector, but narrow its ring to focus acquired through
+  // keyboard navigation so a click or pointer-opened palette stays unringed.
+  useInteractionModalityTracking();
+  const handleFocus = useCallback(
+    (event: React.FocusEvent<HTMLInputElement>) => {
+      setIsKeyboardFocus(getInteractionModality() === 'keyboard');
+      onFocus?.(event);
+    },
+    [onFocus],
+  );
+  const handleBlur = useCallback(
+    (event: React.FocusEvent<HTMLInputElement>) => {
+      setIsKeyboardFocus(false);
+      onBlur?.(event);
+    },
+    [onBlur],
+  );
 
   // Use context values as fallback
   const value = controlledValue ?? ctx?.search;
@@ -259,7 +285,9 @@ export function CommandPaletteInput({
       <input
         {...props}
         ref={useMergedRefs(ref, inputRef)}
-        {...stylex.props(styles.input)}
+        {...(isKeyboardFocus
+          ? focusOutlineProps.focusVisible(styles.input)
+          : focusOutlineProps.suppressed(styles.input))}
         type="text"
         role={ctx ? 'combobox' : standaloneRole}
         aria-expanded={
@@ -300,6 +328,8 @@ export function CommandPaletteInput({
           onChange?.(e);
         }}
         onKeyDown={handleKeyDown}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
       />
       {(ctx?.isBusy || hasEndContent) && (
         <span {...stylex.props(styles.end)}>