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

package/src/ToggleButton/ToggleButton.test.tsx

@@ -497,6 +497,78 @@ describe('ToggleButton', () => {
     expect(button).not.toHaveAttribute('aria-busy', 'true');
     await act(async () => {});
   });
+
+  // family:buttons FR5: a caller onClick on a standalone ToggleButton runs
+  // before onPressedChange and pressedChangeAction, never replaces the toggle
+  // request, and cancels it only by calling preventDefault() itself.
+  describe('with a caller onClick', () => {
+    it('runs the caller onClick first, then requests the next state and runs the Action', async () => {
+      const calls: string[] = [];
+      render(
+        <ToggleButton
+          label="Compact"
+          isPressed={false}
+          onClick={() => calls.push('onClick')}
+          onPressedChange={next => calls.push(`onPressedChange:${next}`)}
+          pressedChangeAction={next => {
+            calls.push(`pressedChangeAction:${next}`);
+          }}
+        />,
+      );
+
+      fireEvent.click(screen.getByRole('button', {name: 'Compact'}));
+      await act(async () => {});
+
+      expect(calls).toEqual([
+        'onClick',
+        'onPressedChange:true',
+        'pressedChangeAction:true',
+      ]);
+    });
+
+    it('requests no next state when the caller onClick calls preventDefault', async () => {
+      const onPressedChange = vi.fn();
+      const pressedChangeAction = vi.fn();
+      render(
+        <ToggleButton
+          label="Compact"
+          isPressed={false}
+          onClick={event => event.preventDefault()}
+          onPressedChange={onPressedChange}
+          pressedChangeAction={pressedChangeAction}
+        />,
+      );
+
+      const button = screen.getByRole('button', {name: 'Compact'});
+      fireEvent.click(button);
+      await act(async () => {});
+
+      expect(onPressedChange).not.toHaveBeenCalled();
+      expect(pressedChangeAction).not.toHaveBeenCalled();
+      expect(button).toHaveAttribute('aria-pressed', 'false');
+    });
+
+    it('still requests the next state when the click was already prevented before the caller onClick ran', () => {
+      const onPressedChange = vi.fn();
+      render(
+        <div onClickCapture={event => event.preventDefault()}>
+          <ToggleButton
+            label="Compact"
+            isPressed={false}
+            onClick={() => {}}
+            onPressedChange={onPressedChange}
+          />
+        </div>,
+      );
+
+      fireEvent.click(screen.getByRole('button', {name: 'Compact'}));
+
+      expect(onPressedChange).toHaveBeenCalledExactlyOnceWith(
+        true,
+        expect.anything(),
+      );
+    });
+  });
 });
 
 // =============================================================================
@@ -721,6 +793,29 @@ describe.each(['single', 'multiple'] as const)(
       expect(onPressedChange).not.toHaveBeenCalled();
       expect(pressedChangeAction).not.toHaveBeenCalled();
     });
+
+    // family:buttons FR11: a member's selection request comes from the group,
+    // and a caller onClick on the member must not replace it.
+    it('still asks the group to toggle a member that receives an onClick', async () => {
+      const onChange = vi.fn();
+      const onClick = vi.fn();
+      const groupProps =
+        type === 'single'
+          ? {type, value: null, onChange}
+          : {type, value: [], onChange};
+      render(
+        <ToggleButtonGroup {...groupProps} label="View">
+          <ToggleButton value="grid" label="Grid" onClick={onClick} />
+        </ToggleButtonGroup>,
+      );
+
+      await userEvent.setup().click(screen.getByRole('button', {name: 'Grid'}));
+
+      expect(onClick).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledExactlyOnceWith(
+        type === 'single' ? 'grid' : ['grid'],
+      );
+    });
   },
 );
 

package/src/ToggleButton/ToggleButton.tsx

@@ -9,7 +9,8 @@
  * @position Thin wrapper over Button; adds controlled toggle pattern
  *
  * ToggleButton wraps Button with `isPressed` and adds:
- * - `onPressedChange` from internal `onClick`; `pressedChangeAction` via Button
+ * - `onPressedChange` from internal `onClick`, after any caller `onClick`;
+ *   `pressedChangeAction` via Button
  * - `pressedIcon` for outline-to-filled icon swap
  * - Font weight shift on press with width reservation to prevent layout shift
  * - Group integration via ToggleButtonGroupContext
@@ -258,6 +259,7 @@ export function ToggleButton({
   xstyle,
   className,
   style,
+  onClick: onClickProp,
   ...props
 }: ToggleButtonProps): ReactNode {
   const group = useToggleButtonGroup();
@@ -287,11 +289,20 @@ export function ToggleButton({
     if (isDisabled) {
       return;
     }
+    // A caller onClick (a trigger wrapper often supplies one) runs first and
+    // never replaces the toggle's own request (family:buttons FR5, FR11).
+    const wasPrevented = event.defaultPrevented;
+    onClickProp?.(event);
     if (group && value != null) {
       group.toggle(value);
       event.preventDefault();
       return;
     }
+    // A standalone toggle is cancelled only by the caller's own
+    // preventDefault(); Button then skips pressedChangeAction too.
+    if (!wasPrevented && event.defaultPrevented) {
+      return;
+    }
 
     onPressedChangeProp?.(nextPressed, event);
   };

package/src/ToggleButton/ToggleButtonGroup.doc.mjs

@@ -6,6 +6,10 @@ export const docs = {
   name: 'ToggleButtonGroup',
   subComponentOf: 'ToggleButton',
   displayName: 'Toggle Button Group',
+  keywords: [
+    'togglegroup',
+    'buttontogglegroup',
+  ],
   description: 'Groups toggle buttons for exclusive (single) or multi-select behavior. Uses discriminated union on type for type-safe value/onChange.',
   props: [
     {

package/src/Tokenizer/Tokenizer.test.tsx

@@ -20,7 +20,7 @@ import {
   afterEach,
 } from 'vitest';
 import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
-import {createRef, Profiler} from 'react';
+import {createRef, Profiler, useState} from 'react';
 import userEvent from '@testing-library/user-event';
 import {Tokenizer} from './Tokenizer';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
@@ -1790,6 +1790,59 @@ describe('Tokenizer end-lane reserve', () => {
     expect(renderedTokens).toEqual([]);
   });
 
+  it('clears the busy spinner when a token is added while a bootstrap load is in flight', async () => {
+    let settle: (items: SearchableItem[]) => void = () => {};
+    const bootstrap = vi.fn(
+      async () =>
+        new Promise<SearchableItem[]>(resolve => {
+          settle = resolve;
+        }),
+    );
+    const source: SearchSource = {search: () => [], bootstrap};
+
+    function Harness() {
+      const [value, setValue] = useState<SearchableItem[]>([]);
+      return (
+        <>
+          <Tokenizer
+            label="Items"
+            searchSource={source}
+            value={value}
+            onChange={setValue}
+            hasEntriesOnFocus
+          />
+          <button type="button" onClick={() => setValue([users[0]])}>
+            Add Token
+          </button>
+        </>
+      );
+    }
+
+    render(<Harness />);
+    const input = screen.getByRole('combobox');
+
+    fireEvent.focus(input);
+    await waitFor(() => {
+      expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole('button', {name: 'Add Token'}));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByRole('status', {name: 'Loading'}),
+      ).not.toBeInTheDocument();
+    });
+
+    await act(async () => {
+      settle([]);
+      await Promise.resolve();
+    });
+    expect(
+      screen.queryByRole('status', {name: 'Loading'}),
+    ).not.toBeInTheDocument();
+  });
+
   it('shares one observer across every field on the page', () => {
     // Browsers batch per observer instance, so one observer per lane meant N
     // callback dispatches a frame for N fields.

package/src/Toolbar/Toolbar.test.tsx

@@ -140,14 +140,6 @@ describe('Toolbar', () => {
     );
   });
 
-  it('sets aria-orientation to vertical', () => {
-    render(<Toolbar label="Actions" orientation="vertical" />);
-    expect(screen.getByRole('toolbar')).toHaveAttribute(
-      'aria-orientation',
-      'vertical',
-    );
-  });
-
   it('reflects the size', () => {
     render(<Toolbar label="Actions" size="sm" />);
     const toolbar = screen.getByRole('toolbar');

package/src/Toolbar/__tests__/Toolbar.a11y.chromium.spec.ts

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Toolbar.a11y.chromium.spec.ts
+ * @input Built toolbar stories and TOOLBAR_PATTERN in real Chromium
+ * @output Browser evidence for every toolbar expectation across Toolbar's representative states, and a paint check that each state's controls sit on the axis and in the direction it declares
+ * @position Chromium lane of the Toolbar binding
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  TOOLBAR_PATTERN,
+  blockingResults,
+  checkAccessibilitySpec,
+  formatFailures,
+  neverExercised,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {
+  TOOLBAR_BINDING_STATES,
+  type ToolbarBindingState,
+} from './Toolbar.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+  return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+async function mountState(
+  page: Page,
+  state: ToolbarBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const root = page.locator('#storybook-root');
+  const subject = root.getByRole('toolbar', {name: state.label, exact: true});
+  await expect(subject).toBeVisible();
+  const related: Record<string, Locator> = {
+    before: root.getByRole('button', {
+      name: 'Before the toolbar',
+      exact: true,
+    }),
+    after: root.getByRole('button', {name: 'After the toolbar', exact: true}),
+  };
+  for (const [relation, name] of Object.entries(state.controls)) {
+    related[relation] = subject.getByRole('button', {name, exact: true});
+  }
+  return {subject, related};
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: ToolbarBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TOOLBAR_PATTERN,
+    binding: 'Toolbar',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+  });
+}
+
+test('every toolbar expectation is exercised by a Toolbar state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of TOOLBAR_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+});
+
+/**
+ * The contract reads `orientation` and `direction` as facts the binding
+ * declares. This checks the painted page agrees: the second control sits
+ * below the first in a vertical state, and after it in reading order — to
+ * its right, or its left under right-to-left — in a horizontal one.
+ */
+for (const state of TOOLBAR_BINDING_STATES) {
+  test(`Toolbar [${state.id}] paints its controls on the declared axis and direction`, async ({
+    page,
+  }) => {
+    const {related} = await mountState(page, state);
+    const first = await related['first-control'].boundingBox();
+    const second = await related['second-control'].boundingBox();
+    if (first == null || second == null) {
+      throw new Error(`state "${state.id}" has an unpainted control`);
+    }
+    const firstMiddle = {
+      x: first.x + first.width / 2,
+      y: first.y + first.height / 2,
+    };
+    const secondMiddle = {
+      x: second.x + second.width / 2,
+      y: second.y + second.height / 2,
+    };
+    if (state.facts.orientation === 'vertical') {
+      expect(second.y, 'second control below the first').toBeGreaterThanOrEqual(
+        first.y + first.height,
+      );
+    } else {
+      expect(
+        Math.abs(secondMiddle.y - firstMiddle.y),
+        'controls share a row',
+      ).toBeLessThan(first.height / 2);
+      if (state.facts.direction === 'rtl') {
+        expect(secondMiddle.x, 'second control left of the first').toBeLessThan(
+          firstMiddle.x,
+        );
+      } else {
+        expect(
+          secondMiddle.x,
+          'second control right of the first',
+        ).toBeGreaterThan(firstMiddle.x);
+      }
+    }
+  });
+}
+
+for (const state of TOOLBAR_BINDING_STATES) {
+  test(`Toolbar [${state.id}] — ${state.summary}`, async ({page}) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(TOOLBAR_PATTERN, [result]);
+    // Required rows block (AST-020 FR9).
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

package/src/Toolbar/__tests__/Toolbar.a11y.renders.tsx

@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Toolbar.a11y.renders.tsx
+ * @input One toolbar binding state from Toolbar.a11y.states.ts
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook): a page button before the Toolbar, the Toolbar, and a page button after it
+ * @position Shared fixture for the Toolbar binding
+ */
+
+import type {ReactElement} from 'react';
+import {Button} from '../../Button/Button';
+import {VStack} from '../../VStack/VStack';
+import {Toolbar} from '../Toolbar';
+import type {ToolbarBindingState, ToolbarControl} from './Toolbar.a11y.states';
+
+/**
+ * One slot's controls. A slot lays its children out in a row, so a vertical
+ * toolbar's caller stacks them, as a product toolbar would, to arrange the
+ * controls on the axis the state declares.
+ */
+function controls(
+  list: ReadonlyArray<ToolbarControl>,
+  orientation: ToolbarBindingState['facts']['orientation'],
+): ReactElement | undefined {
+  if (list.length === 0) {
+    return undefined;
+  }
+  const buttons = list.map(control => (
+    <Button
+      key={control.label}
+      label={control.label}
+      variant="ghost"
+      isDisabled={control.isDisabled}
+    />
+  ));
+  return orientation === 'vertical' ? (
+    <VStack gap={1}>{buttons}</VStack>
+  ) : (
+    <>{buttons}</>
+  );
+}
+
+export function renderToolbarState(
+  state: Pick<
+    ToolbarBindingState,
+    'label' | 'startControls' | 'endControls' | 'facts'
+  >,
+): ReactElement {
+  return (
+    <div dir={state.facts.direction} style={{padding: 24, maxWidth: 640}}>
+      <button type="button">Before the toolbar</button>
+      <Toolbar
+        label={state.label}
+        orientation={state.facts.orientation}
+        startContent={controls(state.startControls, state.facts.orientation)}
+        endContent={controls(state.endControls, state.facts.orientation)}
+      />
+      <button type="button">After the toolbar</button>
+    </div>
+  );
+}

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

@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Toolbar.a11y.states.ts
+ * @input Toolbar's representative states and the facts TOOLBAR_PATTERN reads
+ * @output TOOLBAR_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test and the Chromium spec (Toolbar under spec:AST-020 FR15)
+ */
+
+import type {ToolbarStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface ToolbarControl {
+  readonly label: string;
+  readonly isDisabled?: boolean;
+}
+
+export interface ToolbarBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  /** The Toolbar `label`, which names the toolbar. */
+  readonly label: string;
+  /** Controls in the start slot, in order. */
+  readonly startControls: ReadonlyArray<ToolbarControl>;
+  /** Controls in the end slot, in order. */
+  readonly endControls: ReadonlyArray<ToolbarControl>;
+  /** Relation name → accessible name of the control it designates. */
+  readonly controls: Readonly<
+    Record<'first-control' | 'second-control' | 'last-control', string>
+  >;
+  readonly facts: ToolbarStateFacts;
+}
+
+const story = (id: string) => `a11y-toolbar--${id}`;
+
+const FORMATTING = [
+  {label: 'Bold'},
+  {label: 'Italic'},
+  {label: 'Underline'},
+] as const;
+
+const FORMATTING_CONTROLS = {
+  'first-control': 'Bold',
+  'second-control': 'Italic',
+  'last-control': 'Settings',
+} as const;
+
+const HORIZONTAL_LTR: ToolbarStateFacts = {
+  orientation: 'horizontal',
+  direction: 'ltr',
+  wraps: true,
+  homeEnd: true,
+};
+
+export const TOOLBAR_BINDING_STATES = [
+  {
+    id: 'horizontal',
+    summary:
+      'a named horizontal Toolbar with three formatting buttons in the start slot and Settings in the end slot',
+    storyId: story('horizontal'),
+    label: 'Text formatting',
+    startControls: FORMATTING,
+    endControls: [{label: 'Settings'}],
+    controls: FORMATTING_CONTROLS,
+    facts: HORIZONTAL_LTR,
+  },
+  {
+    id: 'horizontal-rtl',
+    summary:
+      'the same Toolbar inside a right-to-left container, where ArrowLeft moves to the next control',
+    storyId: story('horizontal-rtl'),
+    label: 'Text formatting',
+    startControls: FORMATTING,
+    endControls: [{label: 'Settings'}],
+    controls: FORMATTING_CONTROLS,
+    facts: {...HORIZONTAL_LTR, direction: 'rtl'},
+  },
+  {
+    id: 'vertical',
+    summary:
+      'a vertical Toolbar of drawing tools, moved through with ArrowDown and ArrowUp',
+    storyId: story('vertical'),
+    label: 'Drawing tools',
+    startControls: [{label: 'Select'}, {label: 'Pen'}, {label: 'Eraser'}],
+    endControls: [],
+    controls: {
+      'first-control': 'Select',
+      'second-control': 'Pen',
+      'last-control': 'Eraser',
+    },
+    facts: {...HORIZONTAL_LTR, orientation: 'vertical'},
+  },
+  {
+    id: 'first-control-disabled',
+    summary:
+      'a Toolbar whose first button is disabled, so Tab enters on the first enabled button and the arrows skip the disabled one',
+    storyId: story('first-control-disabled'),
+    label: 'Edit actions',
+    startControls: [
+      {label: 'Undo', isDisabled: true},
+      {label: 'Cut'},
+      {label: 'Copy'},
+    ],
+    endControls: [{label: 'Paste'}],
+    controls: {
+      'first-control': 'Cut',
+      'second-control': 'Copy',
+      'last-control': 'Paste',
+    },
+    facts: HORIZONTAL_LTR,
+  },
+] as const satisfies ReadonlyArray<ToolbarBindingState>;
+
+export const TOOLBAR_EXCLUSIONS = [
+  {
+    id: 'control-semantics',
+    owner:
+      'the button, toggle-button and menu-button patterns and their bindings',
+    reason:
+      'Each control placed in a Toolbar exposes its own role, name, state and activation through its own pattern; this binding renders plain Buttons only so the toolbar container and the movement between controls are what is checked.',
+  },
+  {
+    id: 'caret-guard-and-nested-popovers',
+    owner:
+      'Toolbar.test.tsx (caret-guard, nested popover and onKeyDown composition suites)',
+    reason:
+      'Leaving caret keys to a text field mid-line, leaving keys inside an open MoreMenu to that menu, and composing a caller onKeyDown are binding behaviour the APG leaves to the author, so no state here places a text field or popover in the toolbar.',
+  },
+  {
+    id: 'three-lane-layout',
+    owner:
+      'Toolbar.test.tsx (centerContent and three-slot layout tests) and the repository visual gate',
+    reason:
+      'Center content switches the row to a three-column grid, but the controls stay in DOM order inside the same toolbar element and the same roving tab stop walks them, so the role, name, Tab stop and arrow order this contract reads do not change; the grid itself is layout paint.',
+  },
+  {
+    id: 'outer-chrome',
+    owner: 'component:Section and the repository visual gate',
+    reason:
+      'Variant, dividers, block padding and edge compensation are Section and layout paint around the toolbar row; they change no role, name, Tab stop or arrow movement, so every state uses the default transparent chrome.',
+  },
+] as const;