@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

package/src/Timestamp/Timestamp.doc.mjs

@@ -89,18 +89,18 @@ export const docs = {
   },
   usage: {
     description:
-      'Timestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled \u2014 picking relative for recency, absolute for precision, or auto to let the component decide.',
+      'Timestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled; picking relative for recency, absolute for precision, or auto to let the component decide.',
     bestPractices: [
-      {guidance: true, description: 'Use the auto format in feeds and lists so recent items show \u201c2 hours ago\u201d and older items show the full date automatically.'},
-      {guidance: true, description: 'Keep formatting consistent within the same list or table \u2014 mixing relative and absolute timestamps in the same column confuses scanning.'},
+      {guidance: true, description: 'Use the auto format in feeds and lists so recent items show "2 hours ago" and older items show the full date automatically.'},
+      {guidance: true, description: 'Keep formatting consistent within the same list or table; mixing relative and absolute timestamps in the same column confuses scanning.'},
       {guidance: true, description: 'Enable isTimezoneShown when the audience spans multiple time zones, like a global team calendar or audit log.'},
       {guidance: true, description: 'Use isLive for active dashboards or real-time feeds so the relative time stays accurate without a page refresh.'},
-      {guidance: false, description: 'Don\u2019t display raw Unix timestamps or ISO strings to users \u2014 always pass them through Timestamp to get a human-readable format.'},
-      {guidance: false, description: 'Avoid system_date or system_time formats in user-facing UI \u2014 they are meant for developer tools, logs, and machine-readable contexts.'},
-      {guidance: false, description: 'Don\u2019t disable the tooltip on relative timestamps \u2014 users expect to hover for the full date when they see \u201c3 hours ago\u201d.'},
+      {guidance: false, description: 'Don\'t display raw Unix timestamps or ISO strings to users; always pass them through Timestamp to get a human-readable format.'},
+      {guidance: false, description: 'Avoid system_date or system_time formats in user-facing UI; they are meant for developer tools, logs, and machine-readable contexts.'},
+      {guidance: false, description: 'Don\'t disable the tooltip on relative timestamps; users expect to hover for the full date when they see "3 hours ago".'},
     ],
     anatomy: [
-      {name: 'Formatted text', required: true, description: 'The rendered date, time, or relative label like \u201c2 hours ago\u201d or \u201cMar 21, 2025\u201d.'},
+      {name: 'Formatted text', required: true, description: 'The rendered date, time, or relative label like "2 hours ago" or "Mar 21, 2025".'},
       {name: 'Tooltip', required: false, description: 'A hover card showing the full absolute date and time when the display is relative.'},
     ],
   },
@@ -122,18 +122,18 @@ export const docsZh = {
   },
   usage: {
     description:
-      'Timestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled \u2014 picking relative for recency, absolute for precision, or auto to let the component decide.',
+      'Timestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled; picking relative for recency, absolute for precision, or auto to let the component decide.',
     bestPractices: [
-      {guidance: true, description: 'Use the auto format in feeds and lists so recent items show \u201c2 hours ago\u201d and older items show the full date automatically.'},
-      {guidance: true, description: 'Keep formatting consistent within the same list or table \u2014 mixing relative and absolute timestamps in the same column confuses scanning.'},
+      {guidance: true, description: 'Use the auto format in feeds and lists so recent items show "2 hours ago" and older items show the full date automatically.'},
+      {guidance: true, description: 'Keep formatting consistent within the same list or table; mixing relative and absolute timestamps in the same column confuses scanning.'},
       {guidance: true, description: 'Enable isTimezoneShown when the audience spans multiple time zones, like a global team calendar or audit log.'},
       {guidance: true, description: 'Use isLive for active dashboards or real-time feeds so the relative time stays accurate without a page refresh.'},
-      {guidance: false, description: 'Don\u2019t display raw Unix timestamps or ISO strings to users \u2014 always pass them through Timestamp to get a human-readable format.'},
-      {guidance: false, description: 'Avoid system_date or system_time formats in user-facing UI \u2014 they are meant for developer tools, logs, and machine-readable contexts.'},
-      {guidance: false, description: 'Don\u2019t disable the tooltip on relative timestamps \u2014 users expect to hover for the full date when they see \u201c3 hours ago\u201d.'},
+      {guidance: false, description: 'Don\'t display raw Unix timestamps or ISO strings to users; always pass them through Timestamp to get a human-readable format.'},
+      {guidance: false, description: 'Avoid system_date or system_time formats in user-facing UI; they are meant for developer tools, logs, and machine-readable contexts.'},
+      {guidance: false, description: 'Don\'t disable the tooltip on relative timestamps; users expect to hover for the full date when they see "3 hours ago".'},
     ],
     anatomy: [
-      {name: 'Formatted text', required: true, description: 'The rendered date, time, or relative label like \u201c2 hours ago\u201d or \u201cMar 21, 2025\u201d.'},
+      {name: 'Formatted text', required: true, description: 'The rendered date, time, or relative label like "2 hours ago" or "Mar 21, 2025".'},
       {name: 'Tooltip', required: false, description: 'A hover card showing the full absolute date and time when the display is relative.'},
     ],
   },
@@ -144,15 +144,15 @@ export const docsDense = {
   description: 'formatted timestamp with relative/absolute/auto modes, live updates, timezone display',
   usage: {
     description:
-      'Timestamp formats a date or time into readable text. Use for creation dates, update times, or schedules \u2014 relative for recency, absolute for precision, auto to switch automatically.',
+      'Timestamp formats a date or time into readable text. Use for creation dates, update times, or schedules; relative for recency, absolute for precision, auto to switch automatically.',
     bestPractices: [
-      {guidance: true, description: 'Auto format in feeds and lists \u2014 recent shows relative, older shows date_time.'},
+      {guidance: true, description: 'Auto format in feeds and lists; recent shows relative, older shows date_time.'},
       {guidance: true, description: 'Consistent formatting within the same list or table column.'},
       {guidance: true, description: 'isTimezoneShown for multi-timezone audiences.'},
       {guidance: true, description: 'isLive for dashboards so relative time stays current.'},
-      {guidance: false, description: 'Don\u2019t show raw Unix timestamps or ISO strings \u2014 always use Timestamp.'},
-      {guidance: false, description: 'Avoid system_* formats in user-facing UI \u2014 those are for dev tools and logs.'},
-      {guidance: false, description: 'Don\u2019t disable tooltip on relative timestamps \u2014 users expect the full date on hover.'},
+      {guidance: false, description: 'Don\'t show raw Unix timestamps or ISO strings; always use Timestamp.'},
+      {guidance: false, description: 'Avoid system_* formats in user-facing UI; those are for dev tools and logs.'},
+      {guidance: false, description: 'Don\'t disable tooltip on relative timestamps; users expect the full date on hover.'},
     ],
   },
   propDescriptions: {

package/src/Toast/Toast.tsx

@@ -167,6 +167,20 @@ export function Toast({
     };
   }, [autoHideDuration, startTimer]);
 
+  // Pause the auto-hide timer while the window is not focused, so a toast
+  // doesn't silently expire while the user is in another window or tab.
+  useEffect(() => {
+    if (!isAutoHide) {
+      return;
+    }
+    window.addEventListener('blur', pauseTimer);
+    window.addEventListener('focus', resumeTimer);
+    return () => {
+      window.removeEventListener('blur', pauseTimer);
+      window.removeEventListener('focus', resumeTimer);
+    };
+  }, [isAutoHide, pauseTimer, resumeTimer]);
+
   const handleDismiss = useCallback(() => {
     onDismiss('manual');
   }, [onDismiss]);

package/src/Toast/ToastViewport.test.tsx

@@ -0,0 +1,214 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ToastViewport.test.tsx
+ * @input Uses vitest, @testing-library/react, ToastViewport + useToast
+ * @output Unit tests for toast keyboard reach and focus management
+ * @position Testing; validates ToastViewport.tsx + Toast.tsx focus behavior
+ *
+ * SYNC: When ToastViewport.tsx or Toast.tsx focus handling changes, update these tests
+ */
+
+import {describe, it, expect, vi, beforeAll} from 'vitest';
+import {render, screen, fireEvent, act} from '@testing-library/react';
+import React from 'react';
+import {ToastViewport} from './ToastViewport';
+import {useToast} from './useToast';
+import type {ToastOptions} from './types';
+
+// Popover API is not implemented in jsdom.
+beforeAll(() => {
+  if (typeof HTMLElement.prototype.showPopover === 'undefined') {
+    HTMLElement.prototype.showPopover = vi.fn();
+    HTMLElement.prototype.hidePopover = vi.fn();
+  }
+});
+
+// Module-level constant default props (avoids unstable-default-props lint).
+const EMPTY_OPTIONS: ToastOptions = {body: 'placeholder'};
+
+function ShowToastButton({
+  options = EMPTY_OPTIONS,
+  triggerLabel = 'Trigger',
+}: {
+  options?: ToastOptions;
+  triggerLabel?: string;
+}) {
+  const toast = useToast();
+  return (
+    <button type="button" onClick={() => toast(options)}>
+      {triggerLabel}
+    </button>
+  );
+}
+
+const INFO_A: ToastOptions = {body: 'Toast A'};
+const INFO_B: ToastOptions = {body: 'Toast B'};
+const AUTO_TOAST: ToastOptions = {body: 'Auto toast', autoHideDuration: 3000};
+
+function renderViewport(children: React.ReactNode) {
+  return render(<ToastViewport isTopLayer={false}>{children}</ToastViewport>);
+}
+
+// Fire the transition-end that ToastViewport listens for to unmount an
+// exiting toast (jsdom does not run CSS transitions).
+function completeExit(toastId: string) {
+  const node = document.querySelector<HTMLElement>(
+    `[data-toast-id="${toastId}"]`,
+  );
+  if (node) {
+    fireEvent.transitionEnd(node, {propertyName: 'grid-template-rows'});
+  }
+}
+
+describe('ToastViewport keyboard reach + focus', () => {
+  it('F6 moves focus into the newest toast', () => {
+    renderViewport(
+      <ShowToastButton options={INFO_A} triggerLabel="Trigger A" />,
+    );
+    const trigger = screen.getByText('Trigger A');
+    trigger.focus();
+    act(() => {
+      fireEvent.click(trigger);
+    });
+
+    expect(screen.getByText('Toast A')).toBeInTheDocument();
+    expect(document.activeElement).toBe(trigger);
+
+    act(() => {
+      fireEvent.keyDown(document, {key: 'F6'});
+    });
+
+    // Focus lands on the dismiss button of the newest toast.
+    const dismiss = screen.getByRole('button', {name: 'Dismiss notification'});
+    expect(document.activeElement).toBe(dismiss);
+  });
+
+  it('dismissing a focused toast moves focus to a remaining toast, not body', () => {
+    renderViewport(
+      <>
+        <ShowToastButton options={INFO_A} triggerLabel="Trigger A" />
+        <ShowToastButton options={INFO_B} triggerLabel="Trigger B" />
+      </>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Trigger A'));
+    });
+    act(() => {
+      fireEvent.click(screen.getByText('Trigger B'));
+    });
+
+    const dismissButtons = screen.getAllByRole('button', {
+      name: 'Dismiss notification',
+    });
+    expect(dismissButtons).toHaveLength(2);
+
+    // Focus the first toast's dismiss button, then dismiss it.
+    const firstToast = document.querySelectorAll('[data-toast-id]')[0];
+    const firstToastId = firstToast.getAttribute('data-toast-id')!;
+    const firstDismiss = firstToast.querySelector<HTMLElement>(
+      'button[aria-label="Dismiss notification"]',
+    )!;
+    firstDismiss.focus();
+    expect(document.activeElement).toBe(firstDismiss);
+
+    act(() => {
+      fireEvent.click(firstDismiss);
+    });
+    act(() => {
+      completeExit(firstToastId);
+    });
+
+    // Focus must NOT drop to <body>; it moves to the remaining toast.
+    expect(document.activeElement).not.toBe(document.body);
+    expect(document.activeElement?.getAttribute('aria-label')).toBe(
+      'Dismiss notification',
+    );
+  });
+
+  it('dismissing the last focused toast restores the previously-focused element', () => {
+    renderViewport(
+      <ShowToastButton options={INFO_A} triggerLabel="Trigger A" />,
+    );
+    const trigger = screen.getByText('Trigger A');
+    trigger.focus();
+    act(() => {
+      fireEvent.click(trigger);
+    });
+
+    // F6 into the toast, remembering the trigger as the prior focus.
+    act(() => {
+      fireEvent.keyDown(document, {key: 'F6'});
+    });
+    const dismiss = screen.getByRole('button', {name: 'Dismiss notification'});
+    expect(document.activeElement).toBe(dismiss);
+
+    const toastId = document
+      .querySelector('[data-toast-id]')!
+      .getAttribute('data-toast-id')!;
+
+    act(() => {
+      fireEvent.click(dismiss);
+    });
+    act(() => {
+      completeExit(toastId);
+    });
+
+    // No toasts left — focus returns to the element focused before F6.
+    expect(document.activeElement).toBe(trigger);
+  });
+});
+
+describe('Toast blur timer pause', () => {
+  it('pauses the auto-hide timer while the window is blurred', () => {
+    vi.useFakeTimers();
+    try {
+      renderViewport(
+        <ShowToastButton options={AUTO_TOAST} triggerLabel="Trigger Auto" />,
+      );
+      act(() => {
+        fireEvent.click(screen.getByText('Trigger Auto'));
+      });
+      expect(screen.getByText('Auto toast')).toBeInTheDocument();
+
+      // Window loses focus — timer should pause.
+      act(() => {
+        window.dispatchEvent(new Event('blur'));
+      });
+      act(() => {
+        vi.advanceTimersByTime(5000);
+      });
+      // Still present because the timer was paused while blurred.
+      expect(screen.getByText('Auto toast')).toBeInTheDocument();
+
+      // Window regains focus — timer resumes and the toast dismisses.
+      act(() => {
+        window.dispatchEvent(new Event('focus'));
+      });
+      act(() => {
+        vi.advanceTimersByTime(5000);
+      });
+      const toastId = document
+        .querySelector('[data-toast-id]')
+        ?.getAttribute('data-toast-id');
+      if (toastId) {
+        act(() => {
+          completeExit(toastId);
+        });
+      }
+      expect(screen.queryByText('Auto toast')).not.toBeInTheDocument();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe('ToastViewport region ARIA', () => {
+  it('exposes the notifications region without a prohibited aria-modal', () => {
+    renderViewport(<ShowToastButton />);
+    const region = screen.getByRole('region', {name: 'Notifications'});
+    // aria-modal is only valid on role="dialog"/"alertdialog"; a region must
+    // not declare it (axe: aria-allowed-attr).
+    expect(region).not.toHaveAttribute('aria-modal');
+  });
+});

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,48 @@ 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 +170,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 +221,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 +283,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 +297,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 +352,7 @@ export function ToastViewport({
         ref={viewportRef}
         role="region"
         aria-label="Notifications"
+        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/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',
@@ -172,7 +178,7 @@ export const docs = {
       name: 'xstyle',
       type: 'StyleXStyles',
       description:
-        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value \u2014 not an inline style object like style={{}}.',
+        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value; not an inline style object like style={{}}.',
     },
   ],
   theming: {
@@ -184,13 +190,14 @@ export const docs = {
     description:
       'Tokenizer is a multi-select input that lets users search, select, and manage multiple items displayed as removable chips. Use it when users need to build a set of selections from a searchable data source, like adding team members, applying tags, or choosing filters.',
     bestPractices: [
-      {guidance: true, description: 'Write a placeholder that tells users what they can search for \u2014 "Search people\u2026" or "Add tags\u2026" \u2014 so the input is not a blank mystery.'},
+      {guidance: true, description: 'Write a placeholder that tells users what they can search for, such as "Search people..." or "Add tags...", so the input is not a blank mystery.'},
       {guidance: true, description: 'Set maxEntries when the number of selections should be bounded, like limiting a review to 5 approvers.'},
       {guidance: true, description: 'Use hasCreate for free-form tagging where users need to enter values that do not exist in the search source.'},
       {guidance: true, description: 'Show validation status with the status prop so users know immediately when a selection is missing or invalid.'},
-      {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: 'Don\'t use Tokenizer for single-item selection; 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; use the default token style for visual consistency across the set.'},
+      {guidance: false, description: 'Don\'t hide the label; 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',
@@ -361,7 +374,7 @@ export const docsZh = {
       name: 'xstyle',
       type: 'StyleXStyles',
       description:
-        '\u7528\u4e8e\u5e03\u5c40\u81ea\u5b9a\u4e49\u7684 StyleX \u6837\u5f0f\uff08\u5916\u8fb9\u8ddd\u3001\u5b9a\u4f4d\u3001\u5c3a\u5bf8\uff09\u3002\u5fc5\u987b\u662f stylex.create() \u7684\u503c \u2014 \u4e0d\u80fd\u662f\u5185\u8054\u6837\u5f0f\u5bf9\u8c61\u5982 style={{}}\u3002',
+        '\u7528\u4e8e\u5e03\u5c40\u81ea\u5b9a\u4e49\u7684 StyleX \u6837\u5f0f\uff08\u5916\u8fb9\u8ddd\u3001\u5b9a\u4f4d\u3001\u5c3a\u5bf8\uff09\u3002\u5fc5\u987b\u662f stylex.create() \u7684\u503c; \u4e0d\u80fd\u662f\u5185\u8054\u6837\u5f0f\u5bf9\u8c61\u5982 style={{}}\u3002',
     },
   ],
   theming: {
@@ -373,13 +386,14 @@ export const docsZh = {
     description:
       'Tokenizer is a multi-select input that lets users search, select, and manage multiple items displayed as removable chips. Use it when users need to build a set of selections from a searchable data source, like adding team members, applying tags, or choosing filters.',
     bestPractices: [
-      {guidance: true, description: 'Write a placeholder that tells users what they can search for \u2014 "Search people\u2026" or "Add tags\u2026" \u2014 so the input is not a blank mystery.'},
+      {guidance: true, description: 'Write a placeholder that tells users what they can search for, such as "Search people..." or "Add tags...", so the input is not a blank mystery.'},
       {guidance: true, description: 'Set maxEntries when the number of selections should be bounded, like limiting a review to 5 approvers.'},
       {guidance: true, description: 'Use hasCreate for free-form tagging where users need to enter values that do not exist in the search source.'},
       {guidance: true, description: 'Show validation status with the status prop so users know immediately when a selection is missing or invalid.'},
-      {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: 'Don\'t use Tokenizer for single-item selection; 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; use the default token style for visual consistency across the set.'},
+      {guidance: false, description: 'Don\'t hide the label; 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.'},
@@ -399,13 +413,14 @@ export const docsDense = {
     description:
       'Multi-select input for searching and selecting multiple items as removable chips. Use for team members, tags, filters, or any set built from a searchable source.',
     bestPractices: [
-      {guidance: true, description: 'Placeholder that communicates what to search \u2014 "Search people\u2026" not blank.'},
+      {guidance: true, description: 'Placeholder that communicates what to search, such as "Search people..." rather than blank.'},
       {guidance: true, description: 'maxEntries when selections are bounded (e.g. 5 approvers max).'},
       {guidance: true, description: 'hasCreate for free-form tagging with values not in the source.'},
       {guidance: true, description: 'status prop for immediate validation feedback.'},
-      {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: 'Don\'t use for single-item selection; use Typeahead instead.'},
+      {guidance: false, description: 'Avoid custom token colors; default style for consistency.'},
+      {guidance: false, description: 'Don\'t 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: {