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

package/src/Typeahead/Typeahead.test.tsx

@@ -9,7 +9,15 @@
  * SYNC: When Typeahead components change, update tests to match
  */
 
-import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeAll,
+  afterAll,
+  beforeEach,
+} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Typeahead} from './Typeahead';
@@ -122,6 +130,47 @@ describe('BaseTypeahead', () => {
     });
   });
 
+  it('announces the result count to a live region (comboboxes-6)', async () => {
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'Ap'}});
+
+    await waitFor(() => {
+      const region = document.querySelector(
+        '[data-astryx-live-region="polite"]',
+      );
+      expect(region?.textContent).toMatch(/\d+ results?/);
+    });
+  });
+
+  it('announces "no results found" when the search is empty (comboboxes-6)', async () => {
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+        emptySearchResultsText="No results found"
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'zzzzz'}});
+
+    await waitFor(() => {
+      const region = document.querySelector(
+        '[data-astryx-live-region="polite"]',
+      );
+      expect(region).toHaveTextContent('No results found');
+    });
+  });
+
   it('disables input when isDisabled', () => {
     render(
       <BaseTypeahead
@@ -180,6 +229,90 @@ describe('BaseTypeahead', () => {
   });
 });
 
+describe('BaseTypeahead focus-out', () => {
+  it('closes the dropdown when focus leaves the input', async () => {
+    render(
+      <>
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />
+        <button type="button">Outside</button>
+      </>,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'App'}});
+
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    // Focus moves to an element outside the field/dropdown → menu closes.
+    const outside = screen.getByRole('button', {name: 'Outside'});
+    fireEvent.blur(input, {relatedTarget: outside});
+
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'false');
+    });
+  });
+
+  it('keeps the dropdown open when focus moves into the anchor wrapper', async () => {
+    const anchor = document.createElement('div');
+    document.body.appendChild(anchor);
+    const anchorRef = {current: anchor};
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        anchorRef={anchorRef}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    // The input lives inside the wrapper we hand to anchorRef.
+    anchor.appendChild(input.closest('div') ?? input);
+    fireEvent.change(input, {target: {value: 'App'}});
+
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    // A sibling control inside the field (e.g. a clear button) receives focus.
+    const sibling = document.createElement('button');
+    anchor.appendChild(sibling);
+    fireEvent.blur(input, {relatedTarget: sibling});
+
+    // Menu stays open because focus is still within the field.
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+    document.body.removeChild(anchor);
+  });
+
+  it('does not close when a dropdown option receives focus', async () => {
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'App'}});
+
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    const option = screen.getByRole('option', {hidden: true});
+    fireEvent.blur(input, {relatedTarget: option});
+
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+  });
+});
+
 describe('Typeahead', () => {
   it('renders with label', () => {
     render(
@@ -573,4 +706,201 @@ describe('BaseTypeahead paste behavior', () => {
       expect(screen.getByText('No results found')).toBeInTheDocument();
     });
   });
+
+  it('scrolls the highlighted option into view during arrow navigation', async () => {
+    const scrollIntoView = vi.fn();
+    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+      configurable: true,
+      value: scrollIntoView,
+    });
+    try {
+      const user = userEvent.setup();
+      render(
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />,
+      );
+
+      const input = screen.getByRole('combobox');
+      await user.click(input);
+      await user.paste('e'); // matches multiple fruits, opens listbox
+      await waitFor(() => {
+        expect(screen.getByRole('listbox', {hidden: true})).toBeInTheDocument();
+      });
+
+      scrollIntoView.mockClear();
+      await user.keyboard('{ArrowDown}');
+      await user.keyboard('{ArrowDown}');
+
+      expect(scrollIntoView).toHaveBeenCalledWith({block: 'nearest'});
+    } finally {
+      delete (HTMLElement.prototype as unknown as {scrollIntoView?: unknown})
+        .scrollIntoView;
+    }
+  });
+});
+
+describe('Typeahead disabledMessage', () => {
+  // jsdom does not implement the Popover API used by the tooltip, so mock
+  // showPopover/hidePopover to toggle a `popover-open` attribute the tests
+  // can assert on.
+  beforeEach(() => {
+    HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+      this.setAttribute('popover-open', '');
+    });
+    HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+      this.removeAttribute('popover-open');
+    });
+  });
+
+  // jsdom popover content is in the DOM but not "visible" in the
+  // accessibility tree; use hidden: true to find it.
+  const h = {hidden: true} as const;
+
+  it('shows the reason tooltip on hover when disabled with a reason', async () => {
+    render(
+      <Typeahead
+        label="Assignee"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        isDisabled
+        disabledMessage="You need the Editor role"
+      />,
+    );
+
+    const container = screen.getByRole('combobox').parentElement as HTMLElement;
+    const tooltip = screen.getByRole('tooltip', h);
+    expect(tooltip).toHaveTextContent('You need the Editor role');
+
+    fireEvent.mouseEnter(container);
+    await waitFor(() => {
+      expect(tooltip).toHaveAttribute('popover-open');
+    });
+
+    fireEvent.mouseLeave(container);
+    await waitFor(() => {
+      expect(tooltip).not.toHaveAttribute('popover-open');
+    });
+  });
+
+  it('shows the reason tooltip on keyboard focus', async () => {
+    const user = userEvent.setup();
+    render(
+      <Typeahead
+        label="Assignee"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        isDisabled
+        disabledMessage="You need the Editor role"
+      />,
+    );
+
+    const tooltip = screen.getByRole('tooltip', h);
+    await user.tab();
+    expect(screen.getByRole('combobox')).toHaveFocus();
+    await waitFor(() => {
+      expect(tooltip).toHaveAttribute('popover-open');
+    });
+  });
+
+  it('does not render a tooltip when not disabled', () => {
+    render(
+      <Typeahead
+        label="Assignee"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        disabledMessage="You need the Editor role"
+      />,
+    );
+    expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+  });
+
+  it('does not render a tooltip when disabled without a reason', () => {
+    render(
+      <Typeahead
+        label="Assignee"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        isDisabled
+      />,
+    );
+    expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
+  });
+
+  it('keeps the input focusable via aria-disabled when a reason is provided', () => {
+    render(
+      <Typeahead
+        label="Assignee"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        isDisabled
+        disabledMessage="You need the Editor role"
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    expect(input).not.toBeDisabled();
+    expect(input).toHaveAttribute('aria-disabled', 'true');
+    expect(input).toHaveAttribute('readonly');
+  });
+
+  it('links the reason tooltip from the input via aria-describedby', () => {
+    render(
+      <Typeahead
+        label="Assignee"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        isDisabled
+        disabledMessage="You need the Editor role"
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    const tooltip = screen.getByRole('tooltip', h);
+    expect(input.getAttribute('aria-describedby')).toContain(tooltip.id);
+  });
+
+  it('blocks typing and selection while focusable-disabled', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <Typeahead
+        label="Assignee"
+        searchSource={fruitSource}
+        value={null}
+        onChange={onChange}
+        isDisabled
+        disabledMessage="You need the Editor role"
+      />,
+    );
+
+    const input = screen.getByRole('combobox');
+    await user.click(input);
+    await user.type(input, 'App');
+    expect(input).toHaveValue('');
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('remains natively disabled when disabled without a reason', () => {
+    render(
+      <Typeahead
+        label="Assignee"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        isDisabled
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    expect(input).toBeDisabled();
+    expect(input).not.toHaveAttribute('aria-disabled');
+  });
 });

package/src/Typeahead/Typeahead.tsx

@@ -38,6 +38,7 @@ import {
   inputStatusFocusWithinStyles,
 } from '../Field';
 import {Token} from '../Token';
+import {useTooltip} from '../Tooltip';
 import {renderIconSlot, type IconType} from '../Icon';
 import {spacingVars, sizeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
@@ -101,6 +102,29 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<
   emptySearchResultsText?: string;
   /** Whether the input is disabled. @default false */
   isDisabled?: boolean;
+  /**
+   * Explains why the input is disabled. When set together with `isDisabled`,
+   * the input shows a tooltip with this text on hover and keyboard focus, and
+   * the field stays focusable (via `aria-disabled`) so the reason is
+   * discoverable by keyboard and assistive technology. Editing and selection
+   * stay blocked.
+   *
+   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
+   * controls don't emit the pointer events an external tooltip needs.
+   *
+   * @example
+   * ```
+   * <Typeahead
+   *   label="Assignee"
+   *   searchSource={userSource}
+   *   value={assignee}
+   *   onChange={setAssignee}
+   *   isDisabled
+   *   disabledMessage="You need the Editor role to change this"
+   * />
+   * ```
+   */
+  disabledMessage?: string;
   /** Show clear button. @default true */
   hasClear?: boolean;
   /** Auto-focus on mount. @default false */
@@ -209,6 +233,7 @@ export function Typeahead<T extends SearchableItem>({
   maxMenuItems,
   emptySearchResultsText,
   isDisabled = false,
+  disabledMessage,
   hasClear = true,
   hasAutoFocus,
   size: sizeProp,
@@ -230,6 +255,21 @@ export function Typeahead<T extends SearchableItem>({
   const inputRef = useRef<HTMLInputElement>(null);
   const tokenRef = useRef<HTMLElement>(null);
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the input wrapper (which already exists) and
+  // the input stays perceivable via aria-disabled + readOnly instead of the
+  // disabled attribute. Editing and selection stay blocked by the isDisabled
+  // guards (handleWrapperClick, handleEnterEditMode, and BaseTypeahead's own
+  // focus/change guards).
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The wrapper div is not naturally focusable; focusin bubbles up from the
+    // input, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage,
+  });
+
   // Edit mode: when the user clicks the token to edit the selected value
   const [isEditing, setIsEditing] = useState(false);
   const [editingValue, setEditingValue] = useState<T | null>(null);
@@ -339,6 +379,7 @@ export function Typeahead<T extends SearchableItem>({
     [
       description ? descriptionId : null,
       status?.message ? statusMessageId : null,
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
       .join(' ') || undefined;
@@ -371,7 +412,13 @@ export function Typeahead<T extends SearchableItem>({
       className={className}
       style={style}>
       <div
-        ref={wrapperRef}
+        ref={el => {
+          wrapperRef.current = el;
+          // Anchor + hover/focus listeners for the disabled-message tooltip.
+          // Handlers are gated internally by isEnabled, so attaching
+          // unconditionally is safe.
+          disabledMessageTooltip.ref(el);
+        }}
         data-testid={testId}
         onClick={handleWrapperClick}
         onBlur={handleBlur}
@@ -411,6 +458,7 @@ export function Typeahead<T extends SearchableItem>({
           emptySearchResultsText={emptySearchResultsText}
           isDisabled={isDisabled}
           hasAutoFocus={hasAutoFocus}
+          isFocusableDisabled={showsDisabledMessage}
           inputId={inputId}
           ariaDescribedBy={ariaDescribedBy}
           onChangeQuery={onChangeQuery}
@@ -432,6 +480,9 @@ export function Typeahead<T extends SearchableItem>({
           />
         )}
       </div>
+
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>
   );
 }

package/src/VisuallyHidden/VisuallyHidden.doc.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'VisuallyHidden',
+  displayName: 'VisuallyHidden',
+  category: 'Utility',
+  keywords: ["visually hidden","sr-only","screen reader","accessibility","a11y","aria-live","hidden label","assistive technology"],
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Content exposed to assistive technology while hidden from sight.',
+    },
+    {
+      name: 'as',
+      type: 'ElementType',
+      description: 'HTML tag to render as. Use a block element for live regions.',
+      default: "'span'",
+    },
+  ],
+  usage: {
+    description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context. Deliberately has no styling props; the whole point is to stay invisible.',
+    bestPractices: [
+      { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
+      { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
+      { guidance: false, description: 'Use it to hide content from everyone; it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+      { guidance: false, description: 'Put interactive controls inside it; the content is not visible and cannot receive pointer input.' },
+    ],
+  },
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+  name: 'VisuallyHidden',
+  displayName: 'VisuallyHidden',
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: '对辅助技术公开但对视觉隐藏的内容。',
+    },
+    {
+      name: 'as',
+      type: 'ElementType',
+      description: '要渲染的 HTML 标签。实时区域请使用块级元素。',
+      default: "'span'",
+    },
+  ],
+  usage: {
+    description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context.',
+    bestPractices: [
+      { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
+      { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
+      { guidance: false, description: 'Use it to hide content from everyone; it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+      { guidance: false, description: 'Put interactive controls inside it; the content is not visible and cannot receive pointer input.' },
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description: 'renders content in the a11y tree while hiding it visually (sr-only)',
+  usage: {
+    description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context.',
+    bestPractices: [
+      { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
+      { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
+      { guidance: false, description: 'Use it to hide content from everyone; it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+      { guidance: false, description: 'Put interactive controls inside it; the content is not visible and cannot receive pointer input.' },
+    ],
+  },
+  propDescriptions: {
+    children: 'content exposed to AT while visually hidden',
+    as: 'HTML tag to render as; block element for live regions',
+  },
+};

package/src/VisuallyHidden/VisuallyHidden.test.tsx

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file VisuallyHidden.test.tsx
+ * @input Uses vitest, @testing-library/react, VisuallyHidden component
+ * @output Unit tests for VisuallyHidden rendering + a11y behavior
+ * @position Testing; validates VisuallyHidden.tsx implementation
+ *
+ * SYNC: When VisuallyHidden.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {createRef} from 'react';
+import {VisuallyHidden} from './VisuallyHidden';
+
+describe('VisuallyHidden', () => {
+  it('renders its children in the accessibility tree', () => {
+    render(<VisuallyHidden>Delete incident</VisuallyHidden>);
+    // Present in the a11y tree (getByText finds it — it is not display:none).
+    expect(screen.getByText('Delete incident')).toBeInTheDocument();
+  });
+
+  it('renders a <span> by default', () => {
+    render(<VisuallyHidden>Label</VisuallyHidden>);
+    expect(screen.getByText('Label').tagName).toBe('SPAN');
+  });
+
+  it('renders a custom element via the `as` prop', () => {
+    render(
+      <VisuallyHidden as="div" aria-live="polite">
+        Moved task to Done
+      </VisuallyHidden>,
+    );
+    const el = screen.getByText('Moved task to Done');
+    expect(el.tagName).toBe('DIV');
+    expect(el).toHaveAttribute('aria-live', 'polite');
+  });
+
+  it('applies the clip styles that hide it visually', () => {
+    render(<VisuallyHidden>Hidden</VisuallyHidden>);
+    const el = screen.getByText('Hidden');
+    // jsdom does not apply the stylesheet, but the StyleX class is attached.
+    expect(el.getAttribute('class')).toBeTruthy();
+    // It must NOT be display:none / hidden — it stays in the a11y tree.
+    expect(el).not.toHaveAttribute('hidden');
+  });
+
+  it('forwards a ref to the rendered element', () => {
+    const ref = createRef<HTMLElement>();
+    render(<VisuallyHidden ref={ref}>Ref target</VisuallyHidden>);
+    expect(ref.current).toBeInstanceOf(HTMLElement);
+    expect(ref.current?.textContent).toBe('Ref target');
+  });
+
+  it('passes through arbitrary BaseProps (id, role, data-*)', () => {
+    render(
+      <VisuallyHidden id="announcer" role="status" data-testid="vh">
+        Status
+      </VisuallyHidden>,
+    );
+    const el = screen.getByTestId('vh');
+    expect(el).toHaveAttribute('id', 'announcer');
+    expect(el).toHaveAttribute('role', 'status');
+  });
+
+  it('gives an icon-only control an accessible name', () => {
+    render(
+      <button type="button">
+        <span aria-hidden="true">🗑️</span>
+        <VisuallyHidden>Delete</VisuallyHidden>
+      </button>,
+    );
+    expect(screen.getByRole('button', {name: 'Delete'})).toBeInTheDocument();
+  });
+});