@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

package/src/ToggleButton/ToggleButton.tsx

@@ -9,7 +9,7 @@
  * @position Thin wrapper over Button; adds controlled toggle pattern
  *
  * ToggleButton wraps Button with `isPressed` and adds:
- * - `onPressedChange` controlled toggle callback
+ * - `onPressedChange` from internal `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
@@ -116,10 +116,12 @@ export interface ToggleButtonProps extends BaseProps<HTMLButtonElement> {
   ) => void;
 
   /**
-   * Action handler for API- or navigation-backed toggles, run inside a
-   * transition by Button. 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).
+   * Action handler for API- or navigation-backed toggles, run through Button's
+   * clickAction transition after onPressedChange unless that callback prevents
+   * default. It also runs without a callback. Omit it for callback-only toggles
+   * that need no Action transition. The button shows a loading spinner while
+   * the action is pending, including synchronous actions that suspend.
+   * Ignored when a value identifies this button as a ToggleButtonGroup member.
    *
    * @example
    * ```
@@ -154,7 +156,8 @@ export interface ToggleButtonProps extends BaseProps<HTMLButtonElement> {
 
   /**
    * Whether the button is disabled.
-   * When used inside ToggleButtonGroup, the group's isDisabled overrides this.
+   * When used inside ToggleButtonGroup, a disabled group disables this button
+   * too, but an enabled group does not re-enable a button that disables itself.
    * @default false
    */
   isDisabled?: boolean;
@@ -263,54 +266,44 @@ export function ToggleButton({
       ? group.selectedValues.has(value)
       : (isPressedProp ?? false);
   const size = sizeProp ?? group?.size ?? 'md';
-  const isDisabled = group?.isDisabled ?? isDisabledProp;
+  // Either source disabling this button is enough. `??` could not express that:
+  // the group always supplies a boolean (its own prop defaults to false), so the
+  // fallback never ran and an enabled group handed a member that had disabled
+  // itself its availability back. A group still disables everything it contains
+  // — that is the half `??` got right — but it cannot re-enable a member
+  // (family:buttons FR3).
+  const isDisabled = (group?.isDisabled ?? false) || isDisabledProp;
 
-  // Track the pressed state optimistically so the button reflects the intended
-  // state immediately while an async action is pending. The optimistic update
-  // is applied inside Button's clickAction transition (below), satisfying
-  // React's "useOptimistic must run in a transition" rule.
   const [optimisticPressed, setOptimisticPressed] =
     useOptimistic(committedPressed);
   const isPressed = optimisticPressed;
-
-  // Next state derives from the *optimistic* value, not the committed one, so a
-  // re-click while an action is pending reads the in-flight intent and toggles
-  // (true -> false -> true) rather than recomputing from the stale committed
-  // state. handleClick and clickAction share this so the callback and the
-  // optimistic update always agree within a single click.
+  // Both paths use the same in-flight intent, so re-clicks reverse a pending
+  // toggle rather than deriving from the stale controlled value.
   const nextPressed = !isPressed;
-
   const resolvedIcon = isPressed && pressedIcon ? pressedIcon : icon;
 
-  // Synchronous part of the toggle. Button calls onClick before clickAction and
-  // skips clickAction when the event is defaultPrevented, so calling
-  // preventDefault() inside onPressedChange opts out of pressedChangeAction.
   const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
     if (isDisabled) {
       return;
     }
     if (group && value != null) {
-      // Group mode delegates selection to the group; no async-action path.
       group.toggle(value);
       event.preventDefault();
       return;
     }
+
     onPressedChangeProp?.(nextPressed, event);
   };
 
-  // Async part of the toggle, run inside Button's transition (so the optimistic
-  // update is valid and Button's isPending drives the pending spinner). Skipped
-  // automatically by Button when handleClick called preventDefault, and never
-  // wired in group mode (where there is no async action). Button is rendered
-  // interruptible, so it stays clickable while pending and a re-click starts a
-  // fresh transition that interrupts the previous one.
+  // Button runs onClick first and skips clickAction when the callback prevents
+  // default. Its transition owns both the optimistic update and pending UI.
   const clickAction =
-    group && value != null
-      ? undefined
-      : async () => {
+    pressedChangeAction && !(group && value != null)
+      ? async () => {
           setOptimisticPressed(nextPressed);
-          await pressedChangeAction?.(nextPressed);
-        };
+          await pressedChangeAction(nextPressed);
+        }
+      : undefined;
 
   // isIconOnly prop is the source of truth for icon-only rendering.
   const labelContent =

package/src/ToggleButton/ToggleButtonGroup.doc.mjs

@@ -11,7 +11,7 @@ export const docs = {
     {
       name: 'children',
       type: 'ReactNode',
-      description: 'ToggleButton children.',
+      description: 'ToggleButton children. Give each member a value; the group owns its pressed state and ignores its isPressed, onPressedChange, and pressedChangeAction props. Member activation calls the group’s onChange without starting a member Action transition.',
       required: true,
       slotElements: [
         {
@@ -83,7 +83,7 @@ export const docsZh = {
   displayName: 'Toggle Button Group',
   description: '将切换按钮分组，支持单选或多选行为。通过 type 判别联合类型实现类型安全。',
   propDescriptions: {
-    children: 'ToggleButton 子元素。',
+    children: 'ToggleButton 子元素；每个成员都需要 value。分组控制按下状态，并忽略成员的 isPressed、onPressedChange 和 pressedChangeAction。激活成员只调用分组的 onChange，不启动成员的 Action 过渡。',
     label: '分组的无障碍标签 (aria-label)。',
     type: '选择模式。single 允许单个激活，multiple 允许多个。',
     value: '当前选中的值。类型取决于选择模式。',
@@ -101,7 +101,7 @@ export const docsDense = {
   displayName: 'Toggle Button Group',
   description: 'groups toggle btns for exclusive/multi-select; discriminated union on type',
   propDescriptions: {
-    children: 'ToggleButton children',
+    children: 'ToggleButton children; each member needs a value. Group owns pressed state; member isPressed/onPressedChange/pressedChangeAction are ignored. Selection uses group onChange, with no member Action transition.',
     label: 'a11y label (aria-label)',
     type: 'selection mode: single or multiple',
     value: 'selected value(s); type depends on mode',

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

@@ -0,0 +1,209 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ToggleButton.a11y.chromium.spec.ts
+ * @input Uses @playwright/test, the a11y-spec static Storybook server, and the
+ *   checked-in ToggleButtonDisabledA11y stories
+ * @output Real-browser evidence for `docs/families/buttons.md` FR3 — disabled
+ *   means non-operable — across the two ways a ToggleButton becomes disabled,
+ *   plus the enabled control that catches a fix which disables too much.
+ * @position The half of FR3 that jsdom cannot honestly reach. A disabled toggle
+ *   kept focusable by a tooltip carries `aria-disabled` instead of the native
+ *   `disabled` attribute, so whether a real mouse press is refused is an engine
+ *   fact — jsdom's synthetic click does not settle it
+ *   (`docs/specs/AST-013/spec.md`: a browser claim is made in a browser).
+ *
+ * Each state drives a checked-in story rather than a page this file builds, so
+ * the reproduction path for any failure is a URL a person can open
+ * (`docs/specs/AST-009/spec.md` FR30). Each story counts its own activations,
+ * which is what `activationsOn` reads — a toggle that refuses a press leaves no
+ * trace on itself.
+ *
+ * Presses go through `page.mouse` at the control's own centre rather than
+ * `locator.click()`. Playwright's actionability wait would refuse to press a
+ * natively disabled control at all, which would prove nothing about what the
+ * engine does with a press that really lands.
+ *
+ * SYNC: Fixtures live in
+ *   /apps/storybook/stories/ToggleButtonDisabledA11y.stories.tsx.
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const STORY_BASE = 'a11y-togglebutton-disabled-state';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+/** Load a story and wait for the control the assertions press. */
+async function mountStory(page: Page, storyId: string): Promise<void> {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=${STORY_BASE}--${storyId}&viewMode=story`,
+    {waitUntil: 'load'},
+  );
+  await holdMotionStill(page);
+  await page
+    .locator('#storybook-root')
+    .getByRole('button')
+    .first()
+    .waitFor({state: 'attached'});
+}
+
+/**
+ * How many times this story's own handler has run.
+ *
+ * The story publishes the count as an attribute, so this reads a fact the story
+ * renders rather than instrumenting the page from the test — a person opening
+ * the story sees the same number the spec does.
+ */
+async function activationsOn(page: Page): Promise<number> {
+  const raw = await page
+    .locator('[data-a11y-activations]')
+    .first()
+    .getAttribute('data-a11y-activations');
+  return Number(raw ?? '0');
+}
+
+/**
+ * A real mouse press at the control's own centre, landing whether or not
+ * Playwright would consider the control actionable. This is the press the
+ * expectations are about: a user aiming at a control that looks unavailable.
+ */
+async function pressWithMouse(page: Page, name: string): Promise<void> {
+  const control = page
+    .locator('#storybook-root')
+    .getByRole('button', {name, includeHidden: true})
+    .first();
+  const box = await control.boundingBox();
+  if (box == null) {
+    throw new Error(
+      `"${name}" has no layout box, so no mouse press could land on it`,
+    );
+  }
+  await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
+}
+
+/**
+ * Whether the engine reports this control as unavailable, by either of the two
+ * spellings FR3 permits: the native attribute, or focusable `aria-disabled`.
+ */
+async function isUnavailable(page: Page, name: string): Promise<boolean> {
+  return page
+    .locator('#storybook-root')
+    .getByRole('button', {name, includeHidden: true})
+    .first()
+    .evaluate(
+      element =>
+        (element as HTMLButtonElement).disabled ||
+        element.getAttribute('aria-disabled') === 'true',
+    );
+}
+
+test('a member that disables itself stays disabled inside an enabled group', async ({
+  page,
+}) => {
+  await mountStory(page, 'group-enabled-member-disabled');
+
+  expect(
+    await isUnavailable(page, 'List'),
+    'the member sets isDisabled, so it must be exposed as unavailable even though the group disables nothing',
+  ).toBe(true);
+
+  await pressWithMouse(page, 'List');
+  expect(
+    await activationsOn(page),
+    'a disabled member must not invoke the group selection callback (family:buttons FR3)',
+  ).toBe(0);
+});
+
+test('an enabled member of the same group still toggles', async ({page}) => {
+  await mountStory(page, 'group-enabled-member-disabled');
+
+  expect(await isUnavailable(page, 'Grid')).toBe(false);
+
+  await pressWithMouse(page, 'Grid');
+  expect(
+    await activationsOn(page),
+    'the sibling says nothing about its own availability and the group disables nothing, so it must still select',
+  ).toBe(1);
+});
+
+test('a group disabled state still disables a member that says nothing', async ({
+  page,
+}) => {
+  await mountStory(page, 'group-disabled-member-silent');
+
+  expect(await isUnavailable(page, 'List')).toBe(true);
+
+  await pressWithMouse(page, 'List');
+  expect(
+    await activationsOn(page),
+    'a group disabled state overrides member availability (family:buttons FR3)',
+  ).toBe(0);
+});
+
+test('a disabled toggle kept focusable by its tooltip refuses a mouse press', async ({
+  page,
+}) => {
+  await mountStory(page, 'disabled-with-tooltip');
+
+  const control = page.locator('#storybook-root').getByRole('button').first();
+
+  // The tooltip is why this control is focusable rather than natively disabled,
+  // so the press has to be made the way a user reaches it: hover first, let the
+  // tip come up, then press. Pressing cold would skip the hover state the
+  // tooltip's own pointer listeners run in.
+  await control.hover();
+  await expect(page.getByRole('tooltip')).toBeVisible();
+
+  expect(
+    await control.evaluate(element => element.getAttribute('aria-disabled')),
+    'a tooltip keeps the reason reachable by making the control focusable rather than natively disabled',
+  ).toBe('true');
+  expect(await control.getAttribute('aria-pressed')).toBe('false');
+
+  await pressWithMouse(page, 'Bold');
+
+  expect(
+    await activationsOn(page),
+    'focusable is not operable: a disabled toggle must not invoke onPressedChange from a mouse press (family:buttons FR3)',
+  ).toBe(0);
+  expect(
+    await control.getAttribute('aria-pressed'),
+    'the pressed state must not flip',
+  ).toBe('false');
+});
+
+test('an enabled toggle with the same tooltip still toggles on a mouse press', async ({
+  page,
+}) => {
+  await mountStory(page, 'enabled-with-tooltip');
+
+  const control = page.locator('#storybook-root').getByRole('button').first();
+  await control.hover();
+  await expect(page.getByRole('tooltip')).toBeVisible();
+  expect(await control.getAttribute('aria-pressed')).toBe('false');
+
+  await pressWithMouse(page, 'Bold');
+
+  expect(
+    await activationsOn(page),
+    'the enabled path must be untouched by the disabled-state fix',
+  ).toBe(1);
+  expect(await control.getAttribute('aria-pressed')).toBe('true');
+});

package/src/Token/Token.doc.mjs

@@ -55,7 +55,7 @@ export const docs = {
       name: 'href',
       type: 'string',
       description:
-        'Link URL. When provided, the token renders as an <a> element.',
+        'Link URL. When provided, the token renders as an <a> element. The destination follows the shared navigation rule described on the Link `href` prop.',
     },
     {
       name: 'description',
@@ -241,7 +241,7 @@ export const docsDense = {
     isDisabled: 'Reduces opacity, blocks interactions.',
     onRemove: 'Fired on remove button click. Renders X button when provided.',
     onClick: 'Click handler. Renders <span> w/ invisible <button> inside for a11y.',
-    href: 'Link URL. Renders as <a> element.',
+    href: 'Link URL. Renders as <a> element. Follows the shared navigation rule (see Link href).',
     description: 'A11y description via aria-description on root.',
     endContent: 'Content after label, before remove button.',
     isLabelHidden: 'Visually hides label w/ screen-reader-only clip; stays accessible.',