@astryxdesign/core 0.1.2 → 0.1.3

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

@@ -4,9 +4,9 @@
 
 /**
  * @file Typeahead.tsx
- * @input Uses React, BaseTypeahead, Field, Token
+ * @input Uses React, BaseTypeahead, Field, Token, InputGroupContext
  * @output Exports Typeahead styled typeahead component
- * @position Styled wrapper; composes BaseTypeahead with Field
+ * @position Styled wrapper; composes BaseTypeahead with Field or InputGroup
  *
  * Owns the input wrapper (border, padding, status styles), selected value
  * token with spacing compensation, and edit mode behavior. Delegates
@@ -38,9 +38,13 @@ import {
   inputStatusFocusWithinStyles,
 } from '../Field';
 import {Token} from '../Token';
+import {useTooltip} from '../Tooltip';
 import {renderIconSlot, type IconType} from '../Icon';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {spacingVars, sizeVars} from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {groupStyles} from '../InputGroup/groupStyles';
+import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {getInputARIA, mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import type {SearchableItem, SearchSource} from './types';
@@ -101,6 +105,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 +236,7 @@ export function Typeahead<T extends SearchableItem>({
   maxMenuItems,
   emptySearchResultsText,
   isDisabled = false,
+  disabledMessage,
   hasClear = true,
   hasAutoFocus,
   size: sizeProp,
@@ -223,13 +251,30 @@ export function Typeahead<T extends SearchableItem>({
 }: TypeaheadProps<T>) {
   const size = useSize(sizeProp, 'md');
   const inputId = useId();
+  const inputLabelId = useId();
   const descriptionId = useId();
   const statusMessageId = useId();
+  const inputGroup = useInputGroup();
 
   const wrapperRef = useRef<HTMLDivElement>(null);
   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);
@@ -335,43 +380,26 @@ export function Typeahead<T extends SearchableItem>({
     }
   }, [isDisabled, showToken, handleEnterEditMode]);
 
-  const ariaDescribedBy =
+  const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
+    inputLabelId,
     [
       description ? descriptionId : null,
       status?.message ? statusMessageId : null,
-    ]
-      .filter(Boolean)
-      .join(' ') || undefined;
+      showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+    ],
+    inputGroup,
+  );
 
   const sizeStyle = wrapperSizeStyles[size];
 
-  return (
-    <Field
-      ref={ref}
-      label={label}
-      isLabelHidden={isLabelHidden}
-      description={description}
-      inputID={inputId}
-      descriptionID={description ? descriptionId : undefined}
-      isOptional={isOptional}
-      isRequired={isRequired}
-      isDisabled={isDisabled}
-      status={
-        status
-          ? {
-              type: status.type,
-              message: status.message,
-              messageID: status.message ? statusMessageId : undefined,
-            }
-          : undefined
-      }
-      labelTooltip={labelTooltip}
-      width={width}
-      xstyle={xstyle}
-      className={className}
-      style={style}>
+  const typeaheadContent = (
+    <>
       <div
-        ref={wrapperRef}
+        ref={mergeRefs(
+          wrapperRef,
+          disabledMessageTooltip.ref,
+          inputGroup ? ref : undefined,
+        )}
         data-testid={testId}
         onClick={handleWrapperClick}
         onBlur={handleBlur}
@@ -385,10 +413,17 @@ export function Typeahead<T extends SearchableItem>({
             status && inputStatusHoverShadowStyles[status.type],
             status && inputStatusFocusWithinStyles[status.type],
             isDisabled && inputWrapperStyles.disabled,
+            inputGroup && groupStyles.inGroup,
+            inputGroup && xstyle,
           ),
+          inputGroup ? className : undefined,
+          inputGroup ? style : undefined,
         )}>
         {startIcon &&
           renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+        {inputGroup && (
+          <VisuallyHidden id={inputLabelId}>{label}</VisuallyHidden>
+        )}
         {showToken && (
           <Token
             ref={tokenRef}
@@ -411,8 +446,10 @@ export function Typeahead<T extends SearchableItem>({
           emptySearchResultsText={emptySearchResultsText}
           isDisabled={isDisabled}
           hasAutoFocus={hasAutoFocus}
+          isFocusableDisabled={showsDisabledMessage}
           inputId={inputId}
           ariaDescribedBy={ariaDescribedBy}
+          ariaLabelledBy={ariaLabelledBy}
           onChangeQuery={onChangeQuery}
           onOpenChange={onOpenChange}
           debounceMs={debounceMs}
@@ -432,6 +469,41 @@ export function Typeahead<T extends SearchableItem>({
           />
         )}
       </div>
+      {showsDisabledMessage &&
+        disabledMessageTooltip.renderTooltip(disabledMessage)}
+    </>
+  );
+
+  if (inputGroup) {
+    return typeaheadContent;
+  }
+
+  return (
+    <Field
+      ref={ref}
+      label={label}
+      isLabelHidden={isLabelHidden}
+      description={description}
+      inputID={inputId}
+      descriptionID={description ? descriptionId : undefined}
+      isOptional={isOptional}
+      isRequired={isRequired}
+      isDisabled={isDisabled}
+      status={
+        status
+          ? {
+              type: status.type,
+              message: status.message,
+              messageID: status.message ? statusMessageId : undefined,
+            }
+          : undefined
+      }
+      labelTooltip={labelTooltip}
+      width={width}
+      xstyle={xstyle}
+      className={className}
+      style={style}>
+      {typeaheadContent}
     </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',
+  },
+};