@astryxdesign/core 0.7.1 → 0.7.2-canary.374b53a

package/src/Selector/useCombobox.doc.mjs

@@ -0,0 +1,237 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useCombobox',
+  displayName: 'useCombobox',
+  group: 'Selector',
+  keywords: [
+    'combobox',
+    'listbox',
+    'select',
+    'dropdown',
+    'highlight',
+    'active option',
+    'aria-activedescendant',
+    'keyboard',
+    'arrow keys',
+    'headless',
+    'apg',
+    'accessibility',
+    'a11y',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseComboboxOptions',
+      description: 'Configuration object.',
+      required: true,
+    },
+    {
+      name: 'options.selectableItems',
+      type: 'SelectorOptionData[]',
+      description:
+        'The options in the same order as they render. Options with `disabled` cannot be picked and are skipped while moving through the open list; ArrowDown or ArrowUp that opens the list still lands on the first or last option.',
+      required: true,
+    },
+    {
+      name: 'options.isOpen',
+      type: 'boolean',
+      description: 'Whether the list is shown. The caller owns this state.',
+      required: true,
+    },
+    {
+      name: 'options.onOpen',
+      type: '() => unknown',
+      description:
+        'Called to show the list. Return `false` to refuse; the hook then leaves the highlight alone.',
+      required: true,
+    },
+    {
+      name: 'options.onClose',
+      type: '() => void',
+      description:
+        'Called when the hook hides the list; the hook resets the highlight first. When the caller closes the list itself (an outside press, say), it should also call `setHighlightedIndex(-1)`.',
+      required: true,
+    },
+    {
+      name: 'options.listboxId',
+      type: 'string',
+      description:
+        "The listbox element's id. Option ids are derived from it through `getItemId`.",
+      required: true,
+    },
+    {
+      name: 'options.value',
+      type: 'string',
+      description:
+        'The selected value. Without search, opening by a press, Enter or Space highlights it, or the first option when nothing is selected; ArrowDown and ArrowUp open on the first and last option.',
+    },
+    {
+      name: 'options.onSelect',
+      type: '(value: string) => void',
+      description:
+        'Called with the picked value. Picking also closes the list.',
+    },
+    {
+      name: 'options.onClear',
+      type: '() => void',
+      description:
+        'Clears the value. When provided, Delete or Backspace on the closed control clears it, so clearing is not pointer-only. Ignored while the list is open or with `hasSearch`.',
+    },
+    {
+      name: 'options.hasSearch',
+      type: 'boolean',
+      description:
+        'Whether the list has its own search field. Space then types instead of picking, opening by a press or Enter does not pre-highlight (ArrowDown and ArrowUp still open on the first and last option), and printable keys on the closed control go to `onSearchSeed`.',
+      default: 'false',
+    },
+    {
+      name: 'options.onSearchSeed',
+      type: '(char: string) => void',
+      description:
+        'With `hasSearch`, receives each printable character except Space typed while the control has focus, opening the list first when it is closed, so type-to-find needs no separate open step.',
+    },
+    {
+      name: 'options.isDisabled',
+      type: 'boolean',
+      description: 'Whether the control ignores clicks and keys.',
+      default: 'false',
+    },
+  ],
+  returns: [
+    {
+      name: 'highlightedIndex',
+      type: 'number',
+      description:
+        'Index of the active option, or -1 when none is active. With `hasSearch`, opening by a press or Enter does not set one, so it stays -1 after the hook itself closes the list; ArrowDown and ArrowUp still open on the first or last option. Render it as the active option and name it in `aria-activedescendant` only while it points at a rendered option.',
+    },
+    {
+      name: 'setHighlightedIndex',
+      type: '(index: number) => void',
+      description:
+        'Sets the active option, for example from a filter that changes the options.',
+    },
+    {
+      name: 'getItemId',
+      type: '(index: number) => string',
+      description:
+        "The id to render on the option at `index`. Set the control's `aria-activedescendant` to `isOpen && highlightedIndex >= 0 && highlightedIndex < selectableItems.length ? getItemId(highlightedIndex) : undefined`, so it never names an option that does not exist, including in an empty list.",
+    },
+    {
+      name: 'onTriggerClick',
+      type: '() => void',
+      description: 'Toggles the list from a press on the control.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: React.KeyboardEvent) => void',
+      description:
+        'Key handler for the control that keeps focus. ArrowDown and ArrowUp open the list or move the active option; Enter (and Space without search) picks it or opens the list; Escape and Tab close it; Home, End, PageUp and PageDown jump to the first or last option. An editable control that keeps Home and End for the caret does not pass them to this handler, as CommandPalette does.',
+    },
+    {
+      name: 'onItemSelect',
+      type: '(item: SelectorOptionData) => void',
+      description: 'Picks an option from a press on it, then closes the list.',
+    },
+    {
+      name: 'onItemMouseEnter',
+      type: '(item: SelectorOptionData, index: number) => void',
+      description:
+        'Makes the hovered option active without scrolling the list or moving focus.',
+    },
+  ],
+  usage: {
+    description:
+      'Tracks the active option of a single-select combobox and handles its keys, while DOM focus stays on the control. It powers Selector and CommandPalette; use it to build a combobox those components do not cover. It renders nothing and sets no attributes: the caller renders the control, the listbox and the options, and wires `role`, `aria-expanded`, `aria-controls` and `aria-activedescendant` from what it returns.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Render each option with `id={getItemId(index)}` and set the control's `aria-activedescendant` only while `isOpen` and `highlightedIndex` points at a rendered option, as CommandPalette does.",
+      },
+      {
+        guidance: true,
+        description:
+          "For type-to-select without a search field, run useTypeahead's handler first and fall through to this `onKeyDown` when it returns false, as Selector does.",
+      },
+      {
+        guidance: true,
+        description:
+          'Announce the number of results through useAnnounce when the options change for a new query.',
+      },
+      {
+        guidance: false,
+        description:
+          'Move DOM focus onto the options; the active option is announced through `aria-activedescendant` while focus stays on the control.',
+      },
+    ],
+  },
+  relatedComponents: ['Selector', 'CommandPalette'],
+  relatedHooks: ['useMultiCombobox', 'useTypeahead', 'useAnnounce'],
+  importPath: '@astryxdesign/core/Selector',
+  category: 'focus',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Single-select combobox state + keys; focus stays on control. Powers Selector / CommandPalette. Renders nothing, sets no attrs: caller renders control / listbox / options and wires role, aria-expanded, aria-controls, aria-activedescendant.',
+  paramDescriptions: {
+    options: 'config.',
+    'options.selectableItems':
+      'options in render order; disabled ones not pickable, skipped while moving in open list (ArrowDown/Up opening still lands first / last).',
+    'options.isOpen': 'list shown; caller owns state.',
+    'options.onOpen':
+      'show list; return false to refuse (highlight untouched).',
+    'options.onClose':
+      'hook hides list; resets highlight first. caller closing itself (outside press): also setHighlightedIndex(-1).',
+    'options.listboxId': 'listbox id; option ids derive from it (getItemId).',
+    'options.value':
+      'selected value; w/o search, press / Enter / Space opening highlights it (else first); ArrowDown/Up open on first / last.',
+    'options.onSelect': 'called w/ picked value; picking closes.',
+    'options.onClear':
+      'clears value; Delete / Backspace on closed control. ignored when open or hasSearch.',
+    'options.hasSearch':
+      'list has own search field: Space types, press / Enter opening does not pre-highlight (ArrowDown/Up still first / last), printable keys on closed control -> onSearchSeed.',
+    'options.onSearchSeed':
+      'w/ hasSearch, each printable char except Space typed while control focused (opens first if closed).',
+    'options.isDisabled': 'ignore clicks + keys.',
+  },
+  returnDescriptions: {
+    highlightedIndex:
+      'active option index, -1 = none. hasSearch: press / Enter opening sets none (stays -1 after hook closes); ArrowDown/Up still first / last. name in aria-activedescendant only when it points at a rendered option.',
+    setHighlightedIndex: 'set active option (e.g. after filtering).',
+    getItemId:
+      'id for option at index; aria-activedescendant = isOpen && highlightedIndex >= 0 && highlightedIndex < selectableItems.length ? getItemId(highlightedIndex) : undefined (empty list safe).',
+    onTriggerClick: 'toggle list from a press on control.',
+    onKeyDown:
+      'control keydown: ArrowDown/Up open or move; Enter (Space w/o search) picks or opens; Escape / Tab close; Home / End / PageUp / PageDown jump. editable control keeping Home / End for caret: do not pass them.',
+    onItemSelect: 'pick from a press, then close.',
+    onItemMouseEnter: 'hover makes option active; no scroll, no focus move.',
+  },
+  usage: {
+    description:
+      'Headless single-select combobox: active option + keys, focus stays on control. Caller renders + wires ARIA.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Option id = getItemId(index); aria-activedescendant only while open and highlightedIndex points at a rendered option.',
+      },
+      {
+        guidance: true,
+        description:
+          'Type-to-select w/o search: run useTypeahead first, fall through when it returns false.',
+      },
+      {
+        guidance: true,
+        description: 'Announce result count via useAnnounce on new query.',
+      },
+      {
+        guidance: false,
+        description: 'Move DOM focus onto options; use aria-activedescendant.',
+      },
+    ],
+  },
+};

package/src/Switch/Switch.test.tsx

@@ -834,6 +834,55 @@ describe('Switch', () => {
       expect(root).toHaveAttribute('id', 'switch-1');
       expect(root).toHaveAttribute('aria-label', 'Toggle notifications');
     });
+
+    it('composes a caller aria-describedby onto the switch control', () => {
+      const {container} = render(
+        <>
+          <p id="external-hint">Applies to every repository</p>
+          <Switch
+            label="Notifications"
+            description="Sends a daily digest"
+            value={false}
+            onChange={() => {}}
+            data-testid="my-switch"
+            aria-describedby="external-hint"
+          />
+        </>,
+      );
+      const control = screen.getByRole('switch');
+      const description = screen.getByText('Sends a daily digest');
+      expect(control.getAttribute('aria-describedby')?.split(' ')).toEqual([
+        'external-hint',
+        description.id,
+      ]);
+      expect(control).toHaveAccessibleDescription(
+        'Applies to every repository Sends a daily digest',
+      );
+      // The id reference lives on the control only, not on the field wrapper.
+      const root = container.querySelector('[data-testid="my-switch"]');
+      expect(root).not.toHaveAttribute('aria-describedby');
+    });
+
+    it('names the switch control from a caller aria-labelledby', () => {
+      const {container} = render(
+        <>
+          <span id="row-title">Release notes</span>
+          <Switch
+            label="Pin Release notes"
+            isLabelHidden
+            value={false}
+            onChange={() => {}}
+            data-testid="my-switch"
+            aria-labelledby="row-title"
+          />
+        </>,
+      );
+      const control = screen.getByRole('switch', {name: 'Release notes'});
+      expect(control).toHaveAttribute('aria-labelledby', 'row-title');
+      // The id reference lives on the control only, not on the field wrapper.
+      const root = container.querySelector('[data-testid="my-switch"]');
+      expect(root).not.toHaveAttribute('aria-labelledby');
+    });
   });
 
   describe('pressed state', () => {

package/src/Switch/Switch.tsx

@@ -566,6 +566,8 @@ export function Switch({
   className,
   style,
   ref,
+  'aria-describedby': ariaDescribedByProp,
+  'aria-labelledby': ariaLabelledByProp,
   ...rest
 }: SwitchProps) {
   const t = useTranslator();
@@ -610,7 +612,12 @@ export function Switch({
   // Only include descriptionID when the element actually renders.
   // FieldLabel renders the description (with descriptionID) even when the
   // label is visually hidden — it's sr-only, so keep it linked.
+  // A consumer's own `aria-describedby` describes the control, so it comes
+  // first here rather than landing on the field wrapper via `...rest`.
   const describedByParts: string[] = [];
+  if (ariaDescribedByProp) {
+    describedByParts.push(ariaDescribedByProp);
+  }
   if (description) {
     describedByParts.push(descriptionID);
   }
@@ -658,6 +665,10 @@ export function Switch({
         }}
         onFocus={onFocus}
         onBlur={onBlur}
+        // A caller's `aria-labelledby` names the control (a visible title
+        // elsewhere in the row, for example), so it reaches the input rather
+        // than the field wrapper via `...rest`.
+        aria-labelledby={ariaLabelledByProp}
         aria-describedby={ariaDescribedBy}
         aria-invalid={status?.type === 'error' ? true : undefined}
         aria-busy={isBusy || undefined}

package/src/Text/useTruncation.test.tsx

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useTruncation.test.tsx
+ * Tests for useTruncation
+ */
+
+import {render, screen, waitFor} from '@testing-library/react';
+import {afterEach, describe, it, expect, vi} from 'vitest';
+import {useTruncation} from './useTruncation';
+
+function Probe({text}: {text: string}) {
+  const truncation = useTruncation({maxLines: 1});
+  return (
+    <>
+      <span ref={truncation.ref}>{text}</span>
+      <output data-testid="full-text">{truncation.fullText}</output>
+    </>
+  );
+}
+
+// A status line at a fixed width never resizes when its message changes, so
+// the tooltip text must follow the content, not only the element's size.
+describe('useTruncation', () => {
+  it('re-measures when the text changes without a resize', async () => {
+    const {rerender} = render(<Probe text="planning the first step" />);
+    expect(screen.getByTestId('full-text')).toHaveTextContent(
+      'planning the first step',
+    );
+
+    rerender(<Probe text="writing the second step" />);
+
+    await waitFor(() =>
+      expect(screen.getByTestId('full-text')).toHaveTextContent(
+        'writing the second step',
+      ),
+    );
+  });
+
+  describe('content observation', () => {
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    it('shares one observer across every truncating instance', () => {
+      const NativeMutationObserver = globalThis.MutationObserver;
+      let created = 0;
+      vi.stubGlobal(
+        'MutationObserver',
+        class extends NativeMutationObserver {
+          constructor(callback: MutationCallback) {
+            super(callback);
+            created += 1;
+          }
+        },
+      );
+
+      render(
+        <>
+          {Array.from({length: 50}, (_, index) => (
+            <Probe key={index} text={`cell ${index}`} />
+          ))}
+        </>,
+      );
+
+      expect(created).toBe(1);
+    });
+  });
+});

package/src/Text/useTruncation.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useTruncation.ts
- * @input Uses React hooks, sharedResizeObserver
+ * @input Uses React hooks, sharedResizeObserver, sharedMutationObserver
  * @output Exports useTruncation hook for detecting text overflow
  * @position Hook; consumed by Text.tsx, Heading.tsx
  *
@@ -14,6 +14,7 @@
 
 import {useCallback, useRef, useState, type RefCallback} from 'react';
 import {observeResize} from '../utils/sharedResizeObserver';
+import {observeContent} from '../utils/sharedMutationObserver';
 
 export interface UseTruncationOptions {
   /**
@@ -43,10 +44,12 @@ export interface UseTruncationReturn {
 /**
  * Hook for detecting text overflow/truncation.
  *
- * Uses a shared ResizeObserver singleton (via observeResize)
- * for efficient detection when content or container changes. A single
- * ResizeObserver instance is shared across all mounted useTruncation hooks,
- * so even hundreds of table cells only create one observer.
+ * Uses a shared ResizeObserver singleton (via observeResize) for size
+ * changes and a shared MutationObserver singleton (via observeContent) for
+ * content changes, so even hundreds of table cells create one observer of
+ * each kind. Observing content matters because an element whose text changes
+ * without resizing (a fixed-width status line) must still be re-measured for
+ * the tooltip text and the truncated state to follow the current content.
  *
  * - Single-line: compares scrollWidth > offsetWidth
  * - Multi-line: uses Range.getBoundingClientRect() to measure actual content
@@ -71,6 +74,7 @@ export function useTruncation(
   const [fullText, setFullText] = useState('');
   const elementRef = useRef<HTMLElement | null>(null);
   const unobserveRef = useRef<(() => void) | null>(null);
+  const unobserveContentRef = useRef<(() => void) | null>(null);
 
   const checkTruncation = useCallback(
     (element: HTMLElement) => {
@@ -113,6 +117,8 @@ export function useTruncation(
       // by element leaves any other observer of the same node untouched.
       unobserveRef.current?.();
       unobserveRef.current = null;
+      unobserveContentRef.current?.();
+      unobserveContentRef.current = null;
 
       elementRef.current = element;
 
@@ -127,6 +133,11 @@ export function useTruncation(
         } else {
           checkTruncation(element);
         }
+        // New text in a box that keeps its size fires no resize, so the
+        // captured text and truncated state would otherwise stay stale.
+        unobserveContentRef.current = observeContent(element, () => {
+          checkTruncation(element);
+        });
       } else {
         setIsTruncated(false);
         setFullText('');

package/src/Tokenizer/Tokenizer.test.tsx

@@ -20,7 +20,7 @@ import {
   afterEach,
 } from 'vitest';
 import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
-import {createRef, Profiler} from 'react';
+import {createRef, Profiler, useState} from 'react';
 import userEvent from '@testing-library/user-event';
 import {Tokenizer} from './Tokenizer';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
@@ -1790,6 +1790,59 @@ describe('Tokenizer end-lane reserve', () => {
     expect(renderedTokens).toEqual([]);
   });
 
+  it('clears the busy spinner when a token is added while a bootstrap load is in flight', async () => {
+    let settle: (items: SearchableItem[]) => void = () => {};
+    const bootstrap = vi.fn(
+      async () =>
+        new Promise<SearchableItem[]>(resolve => {
+          settle = resolve;
+        }),
+    );
+    const source: SearchSource = {search: () => [], bootstrap};
+
+    function Harness() {
+      const [value, setValue] = useState<SearchableItem[]>([]);
+      return (
+        <>
+          <Tokenizer
+            label="Items"
+            searchSource={source}
+            value={value}
+            onChange={setValue}
+            hasEntriesOnFocus
+          />
+          <button type="button" onClick={() => setValue([users[0]])}>
+            Add Token
+          </button>
+        </>
+      );
+    }
+
+    render(<Harness />);
+    const input = screen.getByRole('combobox');
+
+    fireEvent.focus(input);
+    await waitFor(() => {
+      expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole('button', {name: 'Add Token'}));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByRole('status', {name: 'Loading'}),
+      ).not.toBeInTheDocument();
+    });
+
+    await act(async () => {
+      settle([]);
+      await Promise.resolve();
+    });
+    expect(
+      screen.queryByRole('status', {name: 'Loading'}),
+    ).not.toBeInTheDocument();
+  });
+
   it('shares one observer across every field on the page', () => {
     // Browsers batch per observer instance, so one observer per lane meant N
     // callback dispatches a frame for N fields.

package/src/Tooltip/useTooltip.test.tsx

@@ -147,6 +147,19 @@ describe('useTooltip — show delay', () => {
 
     expect(onShow).not.toHaveBeenCalled();
   });
+
+  it('drops a pending show when isEnabled turns false before the delay elapses', () => {
+    const onShow = vi.fn();
+    const {rerender} = render(<Harness onShow={onShow} />);
+
+    fireEvent.mouseEnter(trigger());
+    tick(100);
+    rerender(<Harness isEnabled={false} onShow={onShow} />);
+    tick(1000);
+
+    expect(onShow).not.toHaveBeenCalled();
+    expect(tooltipElement().matches(':popover-open')).toBe(false);
+  });
 });
 
 describe('useTooltip — touch suppression', () => {

package/src/Tooltip/useTooltip.tsx

@@ -352,6 +352,17 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     }, delay);
   }, [isEnabled, isOpen, clearTimeouts, showLayer, delay]);
 
+  // A show scheduled while the triggers were enabled must not outlive them:
+  // disabling also detaches the leave listener that would have cancelled it,
+  // so the timer would open a tooltip that nothing ever closes. Only the
+  // pending show is dropped; a pending hide still runs.
+  useEffect(() => {
+    if (!isEnabled && showTimeoutRef.current) {
+      clearTimeout(showTimeoutRef.current);
+      showTimeoutRef.current = null;
+    }
+  }, [isEnabled]);
+
   // Schedule hide with delay (suppressed when isOpen is true).
   // A small hover bridge (when hideDelay is 0) lets the pointer travel from the
   // trigger onto the tooltip surface without the tooltip vanishing — required

package/src/Typeahead/BaseTypeahead.tsx

@@ -624,6 +624,32 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
     sourceGenRef.current = ++searchGenRef.current;
   }
 
+  // The previous source is remembered in state, not a ref, so a render React
+  // discards cannot consume the comparison without its state updates.
+  const [sourceOfState, setSourceOfState] = useState(searchSource);
+  if (sourceOfState !== searchSource) {
+    setSourceOfState(searchSource);
+    if (isLoading) {
+      setIsLoading(false);
+      setHasSearched(false);
+    }
+    loadingRef.current = false;
+  }
+
+  // When the search source is replaced, any in-flight load from the previous
+  // source is abandoned (generation bumped above). Notify the wrapper's busy lane
+  // in an effect so external store listeners run safely after commit.
+  const isInitialMountRef = useRef(true);
+  useEffect(() => {
+    if (isInitialMountRef.current) {
+      isInitialMountRef.current = false;
+      return;
+    }
+    if (!loadingRef.current) {
+      onLoadingChangeRef.current?.(false);
+    }
+  }, [searchSource]);
+
   // Layer for dropdown
   const handleLayerShow = useCallback(() => {
     onOpenChange?.(true);