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

package/src/Toast/ToastViewport.tsx

@@ -2,17 +2,21 @@
 
 'use client';
 
-import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
 import {Toast} from './Toast';
 import {ToastContext, type ToastContextValue} from './ToastContext';
-import type {
-  ToastEntry,
-  ToastPosition,
-  ToastDismissReason,
-} from './types';
+import type {ToastEntry, ToastPosition, ToastDismissReason} from './types';
 
 const styles = stylex.create({
   viewport: {
@@ -108,6 +112,47 @@ export function ToastViewport({
   const toastsRef = useRef(toasts);
   toastsRef.current = toasts;
 
+  // Show the popover on mount so it enters the top layer.
+  const viewportRef = useRef<HTMLDivElement>(null);
+  // The element that was focused before the user jumped into the viewport
+  // (via F6). Used to restore focus once all toasts are dismissed so focus
+  // never falls to <body>.
+  const prevFocusRef = useRef<HTMLElement | null>(null);
+  // When a toast is dismissed while focus lives inside it, we need to move
+  // focus to a sensible neighbor after that toast unmounts. This holds the
+  // id of the toast whose removal should trigger a focus handoff.
+  const focusHandoffIdRef = useRef<string | null>(null);
+  // The next toast id that should receive focus once the dismissed toast has
+  // unmounted, or 'restore' to fall back to the previously-focused element.
+  const pendingFocusRef = useRef<string | 'restore' | null>(null);
+
+  // Collect a focusable control within a toast node, if any.
+  // Reuses the canonical INTERACTIVE_SELECTORS list (native controls plus
+  // role-based interactive elements) instead of a hand-rolled subset, then
+  // narrows to the first candidate that can actually receive focus —
+  // excluding elements opted out with `tabindex="-1"` and disabled controls.
+  const getFocusable = useCallback(
+    (container: HTMLElement | null): HTMLElement | null => {
+      if (!container) {
+        return null;
+      }
+      const candidates =
+        container.querySelectorAll<HTMLElement>(INTERACTIVE_SELECTORS);
+      for (const candidate of candidates) {
+        if (
+          candidate.getAttribute('tabindex') === '-1' ||
+          candidate.hasAttribute('disabled') ||
+          candidate.getAttribute('aria-disabled') === 'true'
+        ) {
+          continue;
+        }
+        return candidate;
+      }
+      return null;
+    },
+    [],
+  );
+
   const addToast = useCallback((entry: ToastEntry) => {
     setToasts(prev => {
       const {uniqueID, collisionBehavior = 'overwrite'} = entry.options;
@@ -124,21 +169,44 @@ export function ToastViewport({
     });
   }, []);
 
-  const removeToast = useCallback(
-    (id: string, reason: ToastDismissReason) => {
-      const entry = toastsRef.current.find(t => t.id === id);
-      if (entry) {
-        entry.options.onHide?.(reason);
+  const removeToast = useCallback((id: string, reason: ToastDismissReason) => {
+    const entry = toastsRef.current.find(t => t.id === id);
+    if (entry) {
+      entry.options.onHide?.(reason);
+    }
+    // If focus currently lives inside the toast being dismissed, remember
+    // that its removal must hand focus off to a neighbor (or the element
+    // focused before the user entered the viewport) rather than <body>.
+    const el = viewportRef.current;
+    const active = document.activeElement;
+    const dismissedNode =
+      el?.querySelector<HTMLElement>(`[data-toast-id="${id}"]`) ?? null;
+    if (
+      dismissedNode &&
+      active instanceof Node &&
+      dismissedNode.contains(active)
+    ) {
+      focusHandoffIdRef.current = id;
+      // Pick the neighbor to receive focus while the DOM is still intact:
+      // prefer the next toast, then the previous, else restore.
+      const remaining = toastsRef.current.filter(t => t.id !== id);
+      if (remaining.length > 0) {
+        const dismissedIndex = toastsRef.current.findIndex(t => t.id === id);
+        const next =
+          toastsRef.current[dismissedIndex + 1] ??
+          toastsRef.current[dismissedIndex - 1];
+        pendingFocusRef.current = next ? next.id : 'restore';
+      } else {
+        pendingFocusRef.current = 'restore';
       }
-      setExitingIds(prev => {
-        if (prev.has(id)) {
-          return prev;
-        }
-        return new Set(prev).add(id);
-      });
-    },
-    [],
-  );
+    }
+    setExitingIds(prev => {
+      if (prev.has(id)) {
+        return prev;
+      }
+      return new Set(prev).add(id);
+    });
+  }, []);
 
   const handleExited = useCallback((id: string) => {
     setExitingIds(prev => {
@@ -152,6 +220,43 @@ export function ToastViewport({
     setToasts(prev => prev.filter(t => t.id !== id));
   }, []);
 
+  // After a dismissed toast unmounts, hand focus off so it never falls to
+  // <body>. Runs in a layout effect once the toast list no longer contains
+  // the dismissed toast.
+  useLayoutEffect(() => {
+    const handoffId = focusHandoffIdRef.current;
+    const target = pendingFocusRef.current;
+    if (handoffId == null || target == null) {
+      return;
+    }
+    // Wait until the dismissed toast is actually gone from the list.
+    if (toasts.some(t => t.id === handoffId)) {
+      return;
+    }
+    focusHandoffIdRef.current = null;
+    pendingFocusRef.current = null;
+    const el = viewportRef.current;
+    if (target !== 'restore' && el) {
+      const nextNode = el.querySelector<HTMLElement>(
+        `[data-toast-id="${target}"]`,
+      );
+      const focusable = getFocusable(nextNode) ?? nextNode;
+      if (focusable) {
+        focusable.focus();
+        return;
+      }
+    }
+    // No remaining toast to receive focus — restore the previously-focused
+    // element if it's still connected, else fall back to the container.
+    const prev = prevFocusRef.current;
+    prevFocusRef.current = null;
+    if (prev && prev.isConnected) {
+      prev.focus();
+    } else if (el) {
+      el.focus();
+    }
+  }, [toasts, getFocusable]);
+
   const findByUniqueID = useCallback((uid: string) => {
     return toastsRef.current.find(t => t.options.uniqueID === uid);
   }, []);
@@ -177,7 +282,6 @@ export function ToastViewport({
   }
 
   // Show the popover on mount so it enters the top layer
-  const viewportRef = useRef<HTMLDivElement>(null);
   useEffect(() => {
     if (!isTopLayer) {
       return;
@@ -192,6 +296,45 @@ export function ToastViewport({
     }
   }, [isTopLayer]);
 
+  // F6 jumps focus into the toast viewport — the standard "go to
+  // notifications" affordance. Focus the first control in the newest toast,
+  // or the viewport container if none. Toasts are non-modal, so this only
+  // moves focus in; Shift+Tab / Escape let focus leave naturally.
+  const hasToasts = toasts.length > 0;
+  useEffect(() => {
+    if (!hasToasts) {
+      return;
+    }
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'F6') {
+        return;
+      }
+      const el = viewportRef.current;
+      if (!el) {
+        return;
+      }
+      // Already inside the viewport — nothing to do.
+      const active = document.activeElement;
+      if (active instanceof Node && el.contains(active)) {
+        return;
+      }
+      e.preventDefault();
+      // Remember where focus was so it can be restored on dismiss.
+      if (active instanceof HTMLElement) {
+        prevFocusRef.current = active;
+      }
+      // Newest toast is the last one rendered in the DOM.
+      const toastNodes = el.querySelectorAll<HTMLElement>('[data-toast-id]');
+      const newest = toastNodes[toastNodes.length - 1] ?? null;
+      const focusable = getFocusable(newest) ?? newest ?? el;
+      focusable.focus();
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [hasToasts, getFocusable]);
+
   const posStyle =
     position === 'topEnd'
       ? styles.topEnd
@@ -208,6 +351,8 @@ export function ToastViewport({
         ref={viewportRef}
         role="region"
         aria-label="Notifications"
+        aria-modal={false}
+        tabIndex={-1}
         // popover="manual" promotes to the top layer (above dialogs).
         // Omitted inside dialogs where the viewport is already in a top layer.
         popover={isTopLayer ? 'manual' : undefined}
@@ -223,6 +368,7 @@ export function ToastViewport({
           return (
             <div
               key={entry.id}
+              data-toast-id={entry.id}
               {...stylex.props(
                 styles.toastWrapper,
                 isExiting && styles.toastWrapperExiting,

package/src/ToggleButton/ToggleButton.doc.mjs

@@ -34,13 +34,13 @@ export const docs = {
     },
     {
       name: 'onPressedChange',
-      type: '(isPressed: boolean) => void',
-      description: 'Called when pressed state should change. Ignored when inside a group.',
+      type: '(isPressed: boolean, event: MouseEvent) => void',
+      description: 'Called when pressed state should change. Receives the next state and the click event; call event.preventDefault() to skip pressedChangeAction. Ignored when inside a group.',
     },
     {
       name: 'pressedChangeAction',
       type: '(isPressed: boolean) => void | Promise<void>',
-      description: 'Action handler for API- or navigation-backed toggles, run in a transition. Shows an optimistic pressed state immediately and a (debounced) spinner while pending; interruptible by re-clicks.',
+      description: 'Action handler for API- or navigation-backed toggles, run in a transition. Shows an optimistic pressed state immediately and a spinner while pending; the button stays interruptible by re-clicks.',
     },
     {
       name: 'size',
@@ -74,6 +74,12 @@ export const docs = {
         },
       ],
     },
+    {
+      name: 'isIconOnly',
+      type: 'boolean',
+      description: 'When true, renders as a square icon-only button with `label` as the aria-label and an automatic tooltip from the label.',
+      default: 'false',
+    },
     {
       name: 'pressedIcon',
       type: 'ReactNode',

package/src/ToggleButton/ToggleButton.test.tsx

@@ -9,9 +9,9 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
+import {render, screen, act, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {useState} from 'react';
+import {useState, type MouseEvent} from 'react';
 import {ToggleButton} from './ToggleButton';
 import {ToggleButtonGroup} from './ToggleButtonGroup';
 
@@ -88,7 +88,7 @@ describe('ToggleButton', () => {
     );
 
     await user.click(screen.getByRole('button'));
-    expect(handleChange).toHaveBeenCalledWith(true);
+    expect(handleChange).toHaveBeenCalledWith(true, expect.anything());
   });
 
   it('calls onPressedChange with false when clicking pressed button', async () => {
@@ -103,7 +103,7 @@ describe('ToggleButton', () => {
     );
 
     await user.click(screen.getByRole('button'));
-    expect(handleChange).toHaveBeenCalledWith(false);
+    expect(handleChange).toHaveBeenCalledWith(false, expect.anything());
   });
 
   it('renders pressedIcon when pressed', () => {
@@ -193,7 +193,7 @@ describe('ToggleButton', () => {
     expect(screen.getByTestId('bold-toggle')).toBeInTheDocument();
   });
 
-  it('shows the optimistic pressed state immediately, before any spinner', async () => {
+  it('shows the optimistic pressed state and stays interruptible while pending', async () => {
     const user = userEvent.setup();
     let resolveAction: (() => void) | undefined;
     const pressedChangeAction = vi.fn(
@@ -217,12 +217,13 @@ describe('ToggleButton', () => {
 
     await user.click(button);
 
-    // The optimistic state flips immediately. The spinner is debounced, so the
-    // button is not disabled or aria-busy yet — it stays interruptible.
+    // The optimistic state flips immediately and the spinner shows via
+    // aria-busy, but the button is never disabled — it stays clickable so the
+    // action can be interrupted by another click.
     expect(pressedChangeAction).toHaveBeenCalledWith(true);
     expect(button).toHaveAttribute('aria-pressed', 'true');
+    expect(button).toHaveAttribute('aria-busy', 'true');
     expect(button).not.toBeDisabled();
-    expect(button).not.toHaveAttribute('aria-busy', 'true');
 
     // Settle the action so the pending transition doesn't leak into later tests.
     await act(async () => {
@@ -231,7 +232,7 @@ describe('ToggleButton', () => {
     });
   });
 
-  it('shows a loading spinner once the action stays pending past the delay', async () => {
+  it('clears the loading state once the action settles', async () => {
     const user = userEvent.setup();
     let resolveAction: (() => void) | undefined;
     const pressedChangeAction = vi.fn(
@@ -253,18 +254,15 @@ describe('ToggleButton', () => {
     const button = screen.getByRole('button', {name: 'Favorite'});
     await user.click(button);
 
-    // The optimistic state shows immediately; the spinner is debounced and
-    // appears only after the action stays pending past the delay window.
-    expect(button).toHaveAttribute('aria-pressed', 'true');
-    await waitFor(() => expect(button).toBeDisabled());
     expect(button).toHaveAttribute('aria-busy', 'true');
+    expect(button).not.toBeDisabled();
 
     await act(async () => {
       resolveAction?.();
       await Promise.resolve();
     });
-    expect(button).not.toBeDisabled();
     expect(button).not.toHaveAttribute('aria-busy', 'true');
+    expect(button).not.toBeDisabled();
   });
 
   it('interrupts an in-flight action on re-click (true -> false -> true)', async () => {
@@ -290,9 +288,8 @@ describe('ToggleButton', () => {
     const button = screen.getByRole('button', {name: 'Favorite'});
 
     // Each click derives the next state from the optimistic (in-progress)
-    // value, so rapid clicks toggle rather than being dropped. fireEvent keeps
-    // the clicks within the spinner debounce window so the button stays
-    // interruptible.
+    // value, so rapid clicks toggle rather than being dropped. The button is
+    // never disabled while pending, so every click lands and interrupts.
     await act(async () => {
       fireEvent.click(button);
     });
@@ -335,9 +332,33 @@ describe('ToggleButton', () => {
     const button = screen.getByRole('button', {name: 'Favorite'});
     await user.click(button);
 
-    expect(onPressedChange).toHaveBeenCalledWith(true);
+    expect(onPressedChange).toHaveBeenCalledWith(true, expect.anything());
     expect(pressedChangeAction).toHaveBeenCalledWith(true);
   });
+
+  it('skips pressedChangeAction when onPressedChange calls preventDefault', async () => {
+    const user = userEvent.setup();
+    const pressedChangeAction = vi.fn();
+    const onPressedChange = vi.fn(
+      (_next: boolean, event: MouseEvent<HTMLButtonElement>) => {
+        event.preventDefault();
+      },
+    );
+
+    render(
+      <ToggleButton
+        label="Favorite"
+        isPressed={false}
+        onPressedChange={onPressedChange}
+        pressedChangeAction={pressedChangeAction}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: 'Favorite'}));
+
+    expect(onPressedChange).toHaveBeenCalledWith(true, expect.anything());
+    expect(pressedChangeAction).not.toHaveBeenCalled();
+  });
 });
 
 // =============================================================================

package/src/ToggleButton/ToggleButton.tsx

@@ -20,14 +20,7 @@
  * - /packages/cli/templates/blocks/components/ToggleButton/ (showcase blocks)
  */
 
-import React, {
-  useCallback,
-  useEffect,
-  useOptimistic,
-  useState,
-  useTransition,
-  type ReactNode,
-} from 'react';
+import React, {useOptimistic, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars, fontWeightVars} from '../theme/tokens.stylex';
 
@@ -36,37 +29,6 @@ import {useToggleButtonGroup} from './ToggleButtonGroup';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
-// =============================================================================
-// Constants & helpers
-// =============================================================================
-
-/**
- * The spinner only appears once the action has been pending for this long.
- * A fast action shows the optimistic pressed state immediately with no spinner
- * flash, and rapid re-clicks can interrupt the in-flight action before the
- * button locks behind the spinner.
- */
-const PENDING_SPINNER_DELAY_MS = 150;
-
-/**
- * Returns `true` only once `active` has stayed `true` for `delayMs`.
- * Used to debounce the loading spinner so the optimistic state shows first.
- */
-function useDelayed(active: boolean, delayMs: number): boolean {
-  const [delayed, setDelayed] = useState(false);
-  useEffect(() => {
-    if (!active) {
-      return undefined;
-    }
-    const timer = setTimeout(() => setDelayed(true), delayMs);
-    return () => {
-      clearTimeout(timer);
-      setDelayed(false);
-    };
-  }, [active, delayMs]);
-  return active && delayed;
-}
-
 // =============================================================================
 // Styles
 // =============================================================================
@@ -122,23 +84,24 @@ export interface ToggleButtonProps extends BaseProps<HTMLButtonElement> {
   isPressed?: boolean;
 
   /**
-   * Called when the pressed state should change.
+   * Called when the pressed state should change. Receives the next pressed
+   * state and the originating click event. Call `event.preventDefault()` to
+   * opt out of running `pressedChangeAction` (e.g. to handle the toggle
+   * entirely in this callback).
    * When used inside ToggleButtonGroup, this is handled by the group
    * and this prop is ignored.
    */
-  onPressedChange?: (isPressed: boolean) => void;
+  onPressedChange?: (
+    isPressed: boolean,
+    event: React.MouseEvent<HTMLButtonElement>,
+  ) => void;
 
   /**
    * Action handler for API- or navigation-backed toggles, run inside a
-   * transition. The button shows a loading spinner while the action is
-   * pending — whether it returns a promise or synchronously triggers 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).
    *
-   * Because it runs in a transition, the toggle is *interruptible*: clicking
-   * again while an action is pending starts a new transition with the next
-   * optimistic state, so the action reflects the latest intent rather than
-   * being dropped.
-   *
    * @example
    * ```
    * <ToggleButton
@@ -272,54 +235,52 @@ export function ToggleButton({
   const size = sizeProp ?? group?.size ?? 'md';
   const isDisabled = group?.isDisabled ?? isDisabledProp;
 
-  // Track the pressed state optimistically. While an action is pending, the
-  // button reflects the intended (optimistic) state immediately, and a click
-  // mid-flight derives its next state from this value — so rapid toggles read
-  // true -> false -> true rather than stalling on the last committed value.
+  // 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.
+  const nextPressed = !isPressed;
+
   const resolvedIcon = isPressed && pressedIcon ? pressedIcon : icon;
 
-  // Run the toggle inside a transition. The action is interruptible: clicking
-  // again while it is pending starts a fresh transition with the next
-  // optimistic state instead of being dropped, so there is no re-entry guard.
-  // Both onPressedChange and pressedChangeAction run inside the transition,
-  // which means a synchronous-but-suspending handler (e.g. a router navigation
-  // that suspends on data) also drives the pending state — not just promises.
-  const [isPending, startTransition] = useTransition();
-  // Debounce the spinner so a fast action shows the optimistic state without a
-  // spinner flash, and rapid re-clicks can interrupt before the button locks.
-  const showSpinner = useDelayed(isPending, PENDING_SPINNER_DELAY_MS);
-  const isLoadingState = isLoading || showSpinner;
-
-  const handleClick = useCallback(() => {
+  // 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;
     }
-
-    const newState = !optimisticPressed;
-    startTransition(async () => {
-      setOptimisticPressed(newState);
-      onPressedChangeProp?.(newState);
-      await pressedChangeAction?.(newState);
-    });
-  }, [
-    isDisabled,
-    group,
-    value,
-    optimisticPressed,
-    onPressedChangeProp,
-    pressedChangeAction,
-    setOptimisticPressed,
-  ]);
+    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.
+  const clickAction =
+    group && value != null
+      ? undefined
+      : async () => {
+          setOptimisticPressed(nextPressed);
+          await pressedChangeAction?.(nextPressed);
+        };
 
   // isIconOnly prop is the source of truth for icon-only rendering.
   const labelContent =
@@ -352,7 +313,8 @@ export function ToggleButton({
       variant="ghost"
       size={size}
       isDisabled={isDisabled}
-      isLoading={isLoadingState}
+      isLoading={isLoading}
+      isInterruptible
       isIconOnly={isIconOnly}
       aria-pressed={isPressed}
       icon={resolvedIcon}
@@ -363,6 +325,7 @@ export function ToggleButton({
       xstyle={[isPressed ? pressedStyles.background : undefined, xstyle]}
       style={style}
       onClick={handleClick}
+      clickAction={clickAction}
       {...props}>
       {labelContent}
     </Button>

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -70,6 +70,12 @@ export const docs = {
       description: 'Disables the input and all token interactions.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'status',
       type: 'InputStatus',
@@ -191,6 +197,7 @@ export const docs = {
       {guidance: false, description: 'Don\u2019t use Tokenizer for single-item selection \u2014 use Typeahead instead. Tokenizer is for building sets of two or more items.'},
       {guidance: false, description: 'Avoid applying custom colors to individual tokens inside a Tokenizer \u2014 use the default token style for visual consistency across the set.'},
       {guidance: false, description: 'Don\u2019t hide the label \u2014 every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.'},
+      {guidance: false, description: 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'The visible text above the input describing what the user is selecting. Also used as the accessible name.'},
@@ -270,6 +277,12 @@ export const docsZh = {
       description: '\u7981\u7528\u8f93\u5165\u6846\u548c\u6240\u6709\u6807\u8bb0\u4ea4\u4e92\u3002',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the tokenizer is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the input focusable via aria-disabled (input stays blocked). Use this instead of wrapping a disabled Tokenizer in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'status',
       type: 'InputStatus',
@@ -380,6 +393,7 @@ export const docsZh = {
       {guidance: false, description: 'Don\u2019t use Tokenizer for single-item selection \u2014 use Typeahead instead. Tokenizer is for building sets of two or more items.'},
       {guidance: false, description: 'Avoid applying custom colors to individual tokens inside a Tokenizer \u2014 use the default token style for visual consistency across the set.'},
       {guidance: false, description: 'Don\u2019t hide the label \u2014 every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.'},
+      {guidance: false, description: 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'The visible text above the input describing what the user is selecting. Also used as the accessible name.'},
@@ -406,6 +420,7 @@ export const docsDense = {
       {guidance: false, description: 'Don\u2019t use for single-item selection \u2014 use Typeahead instead.'},
       {guidance: false, description: 'Avoid custom token colors \u2014 default style for consistency.'},
       {guidance: false, description: 'Don\u2019t hide the label unless context makes purpose obvious.'},
+      {guidance: false, description: 'Wrap a disabled Tokenizer in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
     ],
   },
   propDescriptions: {