@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e4f8e4e

package/src/BottomSheet/BottomSheet.test.tsx

@@ -2319,6 +2319,35 @@ describe('BottomSheet', () => {
 
       expect(document.activeElement).toBe(opener);
     });
+
+    it('prefers an explicit final focus target', () => {
+      const finalFocusRef = createRef<HTMLButtonElement>();
+      function ExplicitFocusHarness() {
+        const [isOpen, setIsOpen] = useState(true);
+        return (
+          <>
+            <button ref={finalFocusRef} type="button">
+              Adaptive trigger
+            </button>
+            <BottomSheet
+              isOpen={isOpen}
+              onOpenChange={setIsOpen}
+              finalFocusRef={finalFocusRef}
+              label="Filters">
+              <button type="button" onClick={() => setIsOpen(false)}>
+                Done
+              </button>
+            </BottomSheet>
+          </>
+        );
+      }
+
+      render(<ExplicitFocusHarness />);
+      fireEvent.click(screen.getByRole('button', {name: 'Done'}));
+      finishSheetExit();
+
+      expect(document.activeElement).toBe(finalFocusRef.current);
+    });
   });
 
   describe('initial focus', () => {

package/src/BottomSheet/BottomSheet.tsx

@@ -32,6 +32,7 @@ import {
   useLayoutEffect,
   useRef,
   useState,
+  type RefObject,
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -162,6 +163,8 @@ interface StandaloneBottomSheetProps extends BottomSheetSharedProps {
   isOpen: boolean;
   onOpenChange: (isOpen: boolean) => void;
   hasScrim?: boolean;
+  /** Element that receives focus after the sheet closes. */
+  finalFocusRef?: RefObject<HTMLElement | null>;
   sheetId?: never;
 }
 
@@ -221,6 +224,7 @@ function StandaloneBottomSheet({
   height = 'capped',
   snapPoints,
   hasScrim = true,
+  finalFocusRef,
   purpose = 'info',
   xstyle,
   ...props
@@ -298,10 +302,10 @@ function StandaloneBottomSheet({
         dialog.close();
       }
       setIsPresented(false);
-      triggerRef.current?.focus();
+      (finalFocusRef?.current ?? triggerRef.current)?.focus();
       triggerRef.current = null;
     },
-    [isOpen],
+    [finalFocusRef, isOpen],
   );
 
   useScrollLock(shouldPresent && hasScrim);
@@ -385,8 +389,7 @@ function StandaloneBottomSheet({
           {children}
         </BottomSheetPanel>
       </div>
-      {/* A modal sheet's ::backdrop already answers Safari's edge sampler. */}
-      {hasScrim ? null : <BottomSheetEdgeTint />}
+      <BottomSheetEdgeTint />
     </dialog>
   );
 }

package/src/BottomSheet/BottomSheetEdgeTint.test.tsx

@@ -101,15 +101,13 @@ describe('BottomSheetEdgeTint', () => {
     expect(tints()).toHaveLength(1);
   });
 
-  // A modal sheet's ::backdrop is a case WebKit's sampler handles on its own,
-  // so a second sampling target there would only fight it.
-  it('leaves a modal sheet to its ::backdrop', () => {
+  it('gives a modal sheet the same surface-coloured edge tint', () => {
     render(
       <BottomSheet isOpen onOpenChange={() => {}} label="Place details">
         Content
       </BottomSheet>,
     );
-    expect(tints()).toHaveLength(0);
+    expect(tints()).toHaveLength(1);
   });
 
   it('renders the tint inside the dialog, so it unmounts with the sheet', () => {
@@ -148,7 +146,7 @@ describe('BottomSheetEdgeTint', () => {
     expect(tints()).toHaveLength(1);
   });
 
-  it('leaves a modal switcher flow to its ::backdrop', () => {
+  it('gives a modal switcher flow exactly one tint', () => {
     render(
       <BottomSheetSwitcher activeSheet="comment" onActiveSheetChange={() => {}}>
         <BottomSheet sheetId="comment" label="Add a comment">
@@ -156,7 +154,7 @@ describe('BottomSheetEdgeTint', () => {
         </BottomSheet>
       </BottomSheetSwitcher>,
     );
-    expect(tints()).toHaveLength(0);
+    expect(tints()).toHaveLength(1);
   });
 
   it('keeps the tint out of the accessibility tree and out of hit testing', async () => {

package/src/BottomSheet/BottomSheetEdgeTint.tsx

@@ -6,7 +6,7 @@
  * @file BottomSheetEdgeTint.tsx
  * @input Uses StyleX and core color tokens
  * @output Exports BottomSheetEdgeTint, an internal decorative element
- * @position Private helper rendered inside a non-modal BottomSheet dialog
+ * @position Private helper rendered inside every BottomSheet dialog
  *
  * iOS 26 Safari dropped `<meta name="theme-color">` and instead derives the
  * colour it paints behind its translucent toolbars by sampling the page: it
@@ -14,13 +14,10 @@
  * `fixed`/`sticky` ancestor, and extends that element's declared
  * `background-color` into the browser chrome.
  *
- * A modal sheet is served by that heuristic already — WebKit has a dedicated
- * branch for a dialog's `::backdrop`. A non-modal sheet is not: the nearest
- * fixed ancestor of the panel is the sheet's own full-viewport `<dialog>`,
- * which is transparent and viewport-sized, and WebKit answers a viewport-sized
- * candidate by *keeping the colour it already had* — the host page's. The page
- * then shows through behind the address bar while the sheet covers the screen
- * above it.
+ * WebKit may otherwise extend either the dialog backdrop or the host page into
+ * the browser chrome. Which one wins varies with dialog mode and the page's
+ * own fixed or sticky edge content, so relying on the backdrop makes otherwise
+ * identical BottomSheets produce different toolbar colours.
  *
  * This element gives the heuristic something unambiguous to sample: fixed,
  * full width, flush with the bottom edge, taller than WebKit's 10px minimum
@@ -68,8 +65,8 @@ const styles = stylex.create({
 });
 
 /**
- * Colours the iOS Safari toolbar strip below a non-modal sheet. Renders
- * nothing visible; see the file header for why it exists.
+ * Colours the iOS Safari toolbar strip below a sheet. Renders nothing visible;
+ * see the file header for why it exists.
  */
 export function BottomSheetEdgeTint() {
   return (

package/src/BottomSheet/BottomSheetSwitcher.tsx

@@ -632,8 +632,7 @@ export function BottomSheetSwitcher({
           ? {role: 'alertdialog'}
           : undefined)}>
         {children}
-        {/* A modal flow's ::backdrop already answers Safari's edge sampler. */}
-        {hasScrim ? null : <BottomSheetEdgeTint />}
+        <BottomSheetEdgeTint />
       </dialog>
     </BottomSheetSwitcherContext>
   );

package/src/Button/Button.doc.mjs

@@ -23,6 +23,62 @@ export const docs = {
       {guidance: false, description: 'Use the destructive variant without a confirmation step for irreversible actions like deleting data.'},
       {guidance: false, description: 'Use a button for navigation. If it only takes the user to another page, use a link instead. Buttons are for actions like saving, deleting, or submitting.'},
     ],
+    accessibility: [
+      {
+        name: 'Text label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Button text must have at least 4.5:1 contrast with the button background in every state. For Hover and Pointer down, measure the final background after the overlay is applied.',
+      },
+      {
+        name: 'Essential icon or spinner arc',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Icon only', 'Loading'],
+        description:
+          'An icon used instead of text must have at least 3:1 contrast with the button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+      },
+      {
+        name: 'Badge text',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Badge text inside a button must have at least 4.5:1 contrast with the Badge background. Check all 14 built-in Badge colors in Rest, Hover, and Pointer down on page and surface backgrounds. This covers 336 pairs per mode. Check custom end content separately.',
+      },
+      {
+        name: 'Visible control boundary',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if needed',
+        states: ['Rest'],
+        description:
+          'The button edge needs 3:1 contrast only when users need it to see the control. A text-only button can rely on its label.',
+      },
+      {
+        name: 'Keyboard focus indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Focus visible'],
+        description:
+          'The focus outline needs at least 3:1 contrast with the area around the button. Check every style. Destructive buttons use a red outline.',
+      },
+      {
+        name: 'Disabled appearance',
+        category: 'Color contrast',
+        criterion: '1.4.3 and 1.4.11 exceptions',
+        requirement: 'Not required',
+        states: ['Disabled'],
+        description:
+          'Disabled controls do not need to meet these contrast ratios.',
+      },
+    ],
     anatomy: [
       {name: 'Icon', required: false, description: 'A leading icon that reinforces the label, like a trash icon on a Delete button.'},
       {name: 'Label', required: true, description: 'The visible text describing the action. Also used as the accessible name.'},

package/src/Button/Button.test.tsx

@@ -70,6 +70,16 @@ describe('Button', () => {
     const button = screen.getByRole('button');
     // Button should be disabled when loading
     expect(button).toBeDisabled();
+    expect(button.className).toContain('styles.inactive');
+    expect(button.className).not.toContain('styles.disabled');
+  });
+
+  it('keeps the dimmed treatment for explicitly disabled buttons', () => {
+    render(<Button label="Submit" isDisabled />);
+    const button = screen.getByRole('button');
+    expect(button).toBeDisabled();
+    expect(button.className).toContain('styles.inactive');
+    expect(button.className).toContain('styles.disabled');
   });
 
   it('sets aria-busy synchronously while clickAction is pending', async () => {

package/src/Button/Button.tsx

@@ -99,18 +99,20 @@ const styles = stylex.create({
   pressable: {
     transform: {
       default: 'scale(1)',
-      ':active': 'scale(0.98)',
+      ':active:where(:not(:disabled,[aria-disabled="true"]))': 'scale(0.98)',
     },
   },
-  disabled: {
+  inactive: {
     cursor: 'default',
-    opacity: 0.5,
     backgroundImage: 'none',
     transform: {
       default: 'none',
       ':active': 'none',
     },
   },
+  disabled: {
+    opacity: 0.5,
+  },
   ariaDisabled: {
     // The variants' hover treatment already steps aside for
     // `[aria-disabled]`; `:active` still matches a press on an aria-disabled
@@ -270,7 +272,8 @@ export interface ButtonProps extends BaseProps<HTMLButtonElement> {
    */
   isDisabled?: boolean;
   /**
-   * Whether the button is in a loading state.
+   * Whether the button is in a loading state. Loading prevents interaction
+   * without dimming the spinner; explicit disabled states remain dimmed.
    * @default false
    */
   isLoading?: boolean;
@@ -573,6 +576,10 @@ export function Button({
   // 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;
   // isIconOnly prop is the source of truth for icon-only rendering.
   // When false (default), label is always rendered as visible text.
 
@@ -639,7 +646,8 @@ export function Button({
     sizeStyles[size],
     isIconOnly && styles.iconOnly,
     interactionOverlayStyles.backgroundImage,
-    buttonDisabled && styles.disabled,
+    buttonDisabled && styles.inactive,
+    visuallyDisabled && styles.disabled,
     useAriaDisabled && styles.ariaDisabled,
     renderAsLink && styles.link,
     !buttonGroup && styles.pressable,

package/src/ButtonGroup/ButtonGroup.doc.mjs

@@ -39,6 +39,53 @@ export const docs = {
   usage: {
     description:
       'ButtonGroup joins related actions into a single connected control. Use it when multiple buttons represent related choices or operations that belong together visually, like copy/cut/paste, or undo/redo.',
+    accessibility: [
+      {
+        name: 'Text label',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Text in each button must have at least 4.5:1 contrast with its background in every state. For Hover and Pointer down, measure the final background after the overlay is applied.',
+      },
+      {
+        name: 'Essential icon or spinner arc',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Icon only', 'Loading'],
+        description:
+          'An icon used instead of text must have at least 3:1 contrast with the button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+      },
+      {
+        name: 'Visible control boundary',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1 if needed',
+        states: ['Rest'],
+        description:
+          'Some groups need a divider or edge to show each button. That divider or edge must have at least 3:1 contrast.',
+      },
+      {
+        name: 'Keyboard focus indicator',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Focus visible'],
+        description:
+          'The focus outline must have at least 3:1 contrast with the area around it.',
+      },
+      {
+        name: 'Disabled appearance',
+        category: 'Color contrast',
+        criterion: '1.4.3 and 1.4.11 exceptions',
+        requirement: 'Not required',
+        states: ['Disabled'],
+        description:
+          'Disabled controls do not need to meet these contrast ratios.',
+      },
+    ],
     bestPractices: [
       {guidance: true, description: 'Group buttons that perform related actions on the same object, like copy, cut, paste on selected text.'},
       {guidance: true, description: 'Use the same variant for all buttons in a group so they look like a single connected unit.'},

package/src/Carousel/Carousel.test.tsx

@@ -850,4 +850,87 @@ describe('Carousel', () => {
       expect(scroller).not.toHaveAttribute('data-padding');
     });
   });
+
+  describe('edge fade', () => {
+    function getScroller() {
+      const region = screen.getByRole('region');
+      return region.firstElementChild as HTMLElement;
+    }
+
+    function makeOverflowing(el: HTMLElement, scrollLeft: number) {
+      Object.defineProperty(el, 'scrollWidth', {
+        value: 500,
+        configurable: true,
+      });
+      Object.defineProperty(el, 'clientWidth', {
+        value: 200,
+        configurable: true,
+      });
+      Object.defineProperty(el, 'scrollLeft', {
+        value: scrollLeft,
+        writable: true,
+        configurable: true,
+      });
+      fireEvent.scroll(el);
+    }
+
+    function injectedCss(): string {
+      let out = '';
+      for (const sheet of Array.from(document.styleSheets)) {
+        try {
+          for (const rule of Array.from(sheet.cssRules)) {
+            out += rule.cssText + '\n';
+          }
+        } catch {
+          // Ignore cross-origin sheets.
+        }
+      }
+      return out;
+    }
+
+    it('fades the physical left edge when only the start overflows (LTR)', () => {
+      render(
+        <Carousel aria-label="Fade">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const scroller = getScroller();
+      makeOverflowing(scroller, 300);
+      expect(getComputedStyle(scroller).maskImage).toContain(
+        'linear-gradient(to right',
+      );
+    });
+
+    it('fades the physical right edge when only the end overflows (LTR)', () => {
+      render(
+        <Carousel aria-label="Fade">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const scroller = getScroller();
+      makeOverflowing(scroller, 0);
+      expect(getComputedStyle(scroller).maskImage).toContain(
+        'linear-gradient(to left',
+      );
+    });
+
+    it('mirrors both single-edge fade gradients under RTL', () => {
+      render(
+        <Carousel aria-label="Fade">
+          <div>Item 1</div>
+          <div>Item 2</div>
+        </Carousel>,
+      );
+      const css = injectedCss();
+      expect(css).toMatch(
+        /:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*mask-image:\s*linear-gradient\(to left/,
+      );
+      expect(css).toMatch(
+        /:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*mask-image:\s*linear-gradient\(to right/,
+      );
+    });
+  });
+
 });

package/src/Carousel/Carousel.tsx

@@ -178,10 +178,16 @@ const styles = stylex.create({
     maskImage: 'none',
   },
   fadeStart: {
-    maskImage: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    maskImage: {
+      default: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+      ':is([dir="rtl"] *)': `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    },
   },
   fadeEnd: {
-    maskImage: `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    maskImage: {
+      default: `linear-gradient(to left, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+      ':is([dir="rtl"] *)': `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']})`,
+    },
   },
   fadeBoth: {
     maskImage: `linear-gradient(to right, transparent 0%, rgba(0,0,0,0.3) 2px, black ${spacingVars['--spacing-1']}, black calc(100% - ${spacingVars['--spacing-1']}), rgba(0,0,0,0.3) calc(100% - 2px), transparent 100%)`,

package/src/Chat/ChatToolCalls.test.tsx

@@ -46,6 +46,50 @@ describe('ChatToolCalls', () => {
     expect(screen.queryByText('1.2s')).not.toBeInTheDocument();
   });
 
+  it.each([
+    ['pending', 'Pending'],
+    ['running', 'Running'],
+    ['complete', 'Complete'],
+    ['error', 'Failed'],
+  ] as const)(
+    'names the %s status for assistive technology',
+    (status, label) => {
+      render(<ChatToolCalls calls={[{name: 'bash', status}]} />);
+      expect(screen.getByText(label)).toBeInTheDocument();
+    },
+  );
+
+  it('includes the status in an expandable row accessible name', () => {
+    render(
+      <ChatToolCalls
+        calls={[
+          {
+            name: 'readFile',
+            status: 'running',
+            resultDetail: <div>file contents</div>,
+          },
+        ]}
+      />,
+    );
+    expect(
+      screen.getByRole('button', {name: /Running.*readFile/}),
+    ).toBeInTheDocument();
+  });
+
+  it('includes the latest status in a collapsed group accessible name', () => {
+    render(
+      <ChatToolCalls
+        calls={[
+          {name: 'searchCode', status: 'complete'},
+          {name: 'editFile', status: 'running'},
+        ]}
+      />,
+    );
+    expect(
+      screen.getByRole('button', {name: /Running.*editFile/}),
+    ).toBeInTheDocument();
+  });
+
   it('defaults to collapsed', () => {
     render(
       <ChatToolCalls

package/src/Chat/ChatToolCalls.tsx

@@ -365,6 +365,26 @@ const STATUS_STYLES: Record<
   error: styles.colorError,
 };
 
+function getStatusAnnouncement(
+  t: ReturnType<typeof useTranslator>,
+  status: ChatToolCallStatus,
+  errorMessage?: string,
+): string {
+  if (status === 'error' && errorMessage != null) {
+    return t('@astryx.chatToolCalls.error', {message: errorMessage});
+  }
+  switch (status) {
+    case 'pending':
+      return t('@astryx.chatToolCalls.status.pending');
+    case 'running':
+      return t('@astryx.chatToolCalls.status.running');
+    case 'complete':
+      return t('@astryx.chatToolCalls.status.complete');
+    case 'error':
+      return t('@astryx.chatToolCalls.status.error');
+  }
+}
+
 function getToolCallKey(call: ChatToolCallItem): string {
   return getKey(call.key, () =>
     [
@@ -390,6 +410,11 @@ function CallRow({call}: {call: ChatToolCallItem}) {
   const hasDetail = call.resultDetail != null;
   const [isDetailOpen, setIsDetailOpen] = useState(false);
   const detailId = useId();
+  const statusAnnouncement = getStatusAnnouncement(
+    t,
+    status,
+    call.errorMessage,
+  );
 
   const toggleDetail = hasDetail
     ? () => setIsDetailOpen(prev => !prev)
@@ -417,9 +442,9 @@ function CallRow({call}: {call: ChatToolCallItem}) {
         title={status === 'error' ? call.errorMessage : undefined}
         {...stylex.props(styles.statusIcon, STATUS_STYLES[status])}>
         {status === 'running' ? (
-          <Spinner size="sm" shade="subtle" />
+          <Spinner size="sm" shade="subtle" aria-hidden="true" />
         ) : status === 'pending' ? (
-          <Spinner size="sm" shade="subtle" />
+          <Spinner size="sm" shade="subtle" aria-hidden="true" />
         ) : (
           <>
             <span {...stylex.props(styles.statusIconCircle)} />
@@ -432,17 +457,7 @@ function CallRow({call}: {call: ChatToolCallItem}) {
             </span>
           </>
         )}
-        {status === 'error' && call.errorMessage != null && (
-          // The title attribute above is hover-only; expose the error detail
-          // as real text so it reaches screen readers, keyboard, and touch
-          // users. Rendering it inside the row also folds it into the
-          // accessible name of expandable (role="button") rows.
-          <VisuallyHidden>
-            {t('@astryx.chatToolCalls.error', {
-              message: call.errorMessage ?? '',
-            })}
-          </VisuallyHidden>
-        )}
+        <VisuallyHidden>{statusAnnouncement}</VisuallyHidden>
       </span>
       <span {...stylex.props(styles.callName)}>{call.name}</span>
       {call.node != null && (
@@ -581,6 +596,11 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
   // Multiple calls: latest call at surface with chevron to expand all
   const latestCall = calls[calls.length - 1];
   const latestStatus = latestCall.status ?? 'complete';
+  const latestStatusAnnouncement = getStatusAnnouncement(
+    t,
+    latestStatus,
+    latestCall.errorMessage,
+  );
 
   return (
     <div
@@ -620,9 +640,9 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
             <span
               {...stylex.props(styles.statusIcon, STATUS_STYLES[latestStatus])}>
               {latestStatus === 'running' ? (
-                <Spinner size="sm" shade="subtle" />
+                <Spinner size="sm" shade="subtle" aria-hidden="true" />
               ) : latestStatus === 'pending' ? (
-                <Spinner size="sm" shade="subtle" />
+                <Spinner size="sm" shade="subtle" aria-hidden="true" />
               ) : (
                 <>
                   <span {...stylex.props(styles.statusIconCircle)} />
@@ -635,6 +655,7 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
                   </span>
                 </>
               )}
+              <VisuallyHidden>{latestStatusAnnouncement}</VisuallyHidden>
             </span>
             <span {...stylex.props(styles.callName)}>{latestCall.name}</span>
             {latestCall.target != null && (