@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Typeahead/Typeahead.tsx

@@ -19,6 +19,7 @@
  */
 
 import React, {
+  use,
   useCallback,
   useId,
   useRef,
@@ -27,6 +28,7 @@ import React, {
   type ReactNode,
   type RefObject,
 } from 'react';
+import {flushSync} from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import {
   BusyIndicatorLaneProvider,
@@ -52,8 +54,9 @@ import {renderIconSlot, type IconType} from '../Icon';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {Spinner} from '../Spinner';
 import {spacingVars, sizeVars} from '../theme/tokens.stylex';
-import {groupStyles} from '../InputGroup/groupStyles';
+import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
 import {
   composeEventHandlers,
   getInputARIA,
@@ -395,7 +398,7 @@ export function Typeahead<T extends SearchableItem>({
   maxMenuItems,
   minQueryLength,
   emptySearchText,
-  isDisabled = false,
+  isDisabled: isDisabledProp = false,
   disabledMessage,
   hasClear = true,
   hasAutoFocus,
@@ -428,6 +431,8 @@ export function Typeahead<T extends SearchableItem>({
   const descriptionId = useId();
   const statusMessageId = useId();
   const inputGroup = useInputGroup();
+  const inputGroupState = use(InputGroupInternalContext);
+  const isDisabled = isDisabledProp || inputGroupState.isDisabled;
 
   const wrapperRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
@@ -462,7 +467,14 @@ export function Typeahead<T extends SearchableItem>({
   // Show token when value is selected and not in edit mode
   const showToken = value != null && !isEditing;
 
-  // Enter edit mode: remove token visually, populate input with value label
+  // Enter edit mode: remove token visually, populate input with value label.
+  //
+  // Everything happens inside the tap or click that asked for it, never a
+  // frame later: iOS raises the software keyboard only for a focus made while
+  // the browser is still dispatching the person's own tap (or when the
+  // keyboard is already up). Deferred to an animation frame, the focus landed
+  // with no keyboard, so a tap on the selected value showed a caret and
+  // nothing to type with until a second tap.
   const handleEnterEditMode = useCallback(() => {
     if (isDisabled || !value) {
       return;
@@ -471,21 +483,26 @@ export function Typeahead<T extends SearchableItem>({
     setIsEditing(true);
     // The base will receive onChangeQuery with the value's label
     onChangeQuery?.(value.label);
-    requestAnimationFrame(() => {
-      const input = inputRef.current;
-      if (input) {
-        // Set the input value directly since the base manages its own query state
-        // We trigger a synthetic change to sync the base's internal state
-        const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
-          window.HTMLInputElement.prototype,
-          'value',
-        )?.set;
+    const input = inputRef.current;
+    if (input) {
+      // Set the input value directly since the base manages its own query
+      // state, and trigger a synthetic change to sync the base's internal
+      // state. flushSync commits that query before the focus, so the base's
+      // focus handler sees the label rather than an empty query: an empty one
+      // would open the hasEntriesOnFocus bootstrap entries, and Enter would
+      // commit the first of them instead of the edited value.
+      const nativeInputValueSetter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype,
+        'value',
+      )?.set;
+      // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the base must hold the label as its query before the in-tap focus
+      flushSync(() => {
         nativeInputValueSetter?.call(input, value.label);
         input.dispatchEvent(new Event('input', {bubbles: true}));
-        input.focus();
-        input.setSelectionRange(0, input.value.length);
-      }
-    });
+      });
+      input.focus();
+      input.setSelectionRange(0, input.value.length);
+    }
   }, [isDisabled, value, onChangeQuery]);
 
   // Handle blur: restore token if editing and no selection was made
@@ -608,6 +625,7 @@ export function Typeahead<T extends SearchableItem>({
             onKeyDown?.(event);
           }
         }}
+        {...(inputGroup ? inputGroupItemProps : undefined)}
         {...mergeProps(
           themeProps('typeahead', {size, status: status?.type}),
           stylex.props(

package/src/VisuallyHidden/VisuallyHidden.spec.md

@@ -0,0 +1,170 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:VisuallyHidden
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-27
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility]
+verified_by:
+  [
+    .github/visual-baseline/manifest.json,
+    packages/core/src/VisuallyHidden/VisuallyHidden.test.tsx,
+    apps/storybook/stories/VisuallyHidden.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture: [architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-009, spec:AST-071]
+---
+
+# VisuallyHidden component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | A wrapper with required `children` and an optional `as` element; accessibility and data props pass through. It accepts no `className` or `style` and ignores `xstyle` today (FR3 gap, OQ1). |
+| Behavior                | Content is clipped from sight by a fixed style block no caller input can displace, and stays in the accessibility tree unless the caller passes `hidden`, `inert`, or `aria-hidden`.        |
+| End-user impact         | Screen-reader users hear names and announcements that sighted users do not need to see.                                                                                                     |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact; OQ1 is open.                                        |
+| Review checks           | Reject a `display: none` or `visibility: hidden` hide, a caller input that displaces the clip, or dropped `aria-*` passthrough.                                                             |
+| Governing rules         | `architecture:public-component-api/INV5,INV6,INV8`; `spec:AST-071` FR2.                                                                                                                     |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+VisuallyHidden exposes content to assistive technology while keeping it out of
+sight: names for icon-only controls, live announcement regions, and
+supplementary screen-reader context. It owns the hiding technique and the
+guarantee that the hidden node cannot be styled visible.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, or
+  DOM output changes. `xstyle` is accepted by the type and ignored;
+  `className` and `style` are not accepted; the styling surface is the FR3 gap (OQ1)
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Styling inputs not accepted (FR3).** VisuallyHidden drops `className` and
+  `style` and ignores `xstyle`, so callers cannot style the element, where
+  `architecture:public-component-api` INV6 and `spec:AST-071` FR2 have root
+  styling inputs compose. The consumer docs plan to remove `xstyle`; OQ1
+  decides whether the component conforms or INV6's owner records it as an
+  exception.
+
+## Ownership boundary
+
+**Owns**
+
+- The rendered element and its fixed clip style block.
+- Passing accessibility, identity, data, and event props through.
+
+**Does not own / non-goals**
+
+- What the hidden content says and whether it is a live region — owned by the
+  caller, through `children`, `as`, and ARIA props.
+- Shared status announcements — owned by `spec:AST-086` and its shared channel.
+- Theming — VisuallyHidden has no theming target.
+
+## Public concepts
+
+| Concept | Closed values or states                                                                            | Meaning                                | Availability by variant/orientation/state | Default | Owner                      | Stability | Invalid-value behavior                                                                                          |
+| ------- | -------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------- | ------- | -------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- |
+| Element | An intrinsic element, or a component that forwards `className` and `ref` to the element it renders | The rendered element, inline or block. | Always                                    | `span`  | `component:VisuallyHidden` | Stable    | A component that does not forward `className` and `ref` renders its content unclipped, and the ref stays unset. |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | VisuallyHidden renders `children` in the element named by `as` (default `span`). Its own hiding keeps the content in the accessibility tree; a caller's `hidden`, `inert`, or `aria-hidden` passes through and removes it, by the caller's choice.                                                                                                                                                                                                                                                                                                                                          | Current source and tests |
+| FR2 | When `as` is an intrinsic element or forwards `className` to the element it renders, that element is absolutely positioned at the inline-start and block-start of its containing block, 1px by 1px with a −1px margin, no padding or border, clipped to an empty rectangle with hidden overflow, unwrapped, and ignores pointer events and selection.                                                                                                                                                                                                                                       | Current source and tests |
+| FR3 | `ref` reaches the element (for a component `as`, when it forwards `ref`), and supported `aria-*`, `role`, `id`, `data-*`, and event props reach it. The clip styles apply after every caller input, so nothing displaces the clip. Root styling inputs compose on the element (`architecture:public-component-api` INV6, `spec:AST-071` FR2). Implementation gap: `className` and `style` are not accepted and `xstyle` is ignored; the consumer docs plan to remove `xstyle`, and OQ1 decides whether VisuallyHidden conforms or becomes a recorded INV6 exception (Current-state impact). | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Element choice.** Callers choose an inline or block element, such as
+  a `div` for block content or a live region.
+
+### Representative states
+
+| State             | Required invariant                                                      | Allowed variation |
+| ----------------- | ----------------------------------------------------------------------- | ----------------- |
+| Icon-only label   | Hidden `span` gives the control its accessible name.                    | Text.             |
+| Live region       | Block element with caller `aria-live` stays hidden and announced.       | Politeness.       |
+| Styling attempted | The clip still wins; caller styling has no effect today (FR3 gap, OQ1). | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Props.** Caller props → fixed clip styles, so the clip wins.
+
+### Performance and resources
+
+- **PR1 — Static render.** VisuallyHidden holds no state and uses no hooks.
+
+## Accessibility contract
+
+- **AR1 — Perceivable to assistive technology.** Hiding uses clipping, never
+  `display: none`, `visibility: hidden`, or `aria-hidden`, so the content is
+  read and can name or describe other elements.
+- **AR2 — Live regions and hiding by caller choice.** VisuallyHidden adds no
+  role or live region of its own; a caller's `role`, `aria-live`, `hidden`,
+  `inert`, and `aria-hidden` pass through.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                  | Representation authority | Hierarchy role | Component contract |
+| ---------------- | --------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Hidden content   | Present to assistive technology, absent from sight. | Current source and docs  | Supporting     | FR1–FR3, AR1, AR2  |
+
+Theming: VisuallyHidden has no theming target, by design; a visible style on a
+hidden node would defeat its purpose.
+
+## Family and system relationships
+
+- `architecture:public-component-api` owns passthrough, ref, and styling-input
+  rules; FR3 applies INV5, INV6, and INV8 and records the INV6 gap.
+
+## Verification map
+
+| Contract | Verification                                                                                     | Representative states                                                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Audit section                   |
+| -------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1, AR1 | `VisuallyHidden.test.tsx` render and icon-label tests                                            | Default, `as`, icon-only control                                                        | Content leaving the accessibility tree or a lost accessible name fails. Gap: no test covers a caller `hidden`, `inert`, or `aria-hidden` passing through.                                                                                                                                                                                                                                                                                                                                                                                             | `audit:VisuallyHidden/a11y`     |
+| FR2      | `VisuallyHidden.test.tsx` clip-style test; stable visual baseline `core-visuallyhidden--default` | Default                                                                                 | A `hidden` attribute fails the unit test; content that becomes visible comes back changed in the visual baseline. Gap: no unit test asserts a clip declaration, although the test environment exposes them.                                                                                                                                                                                                                                                                                                                                           | `audit:VisuallyHidden/behavior` |
+| FR3, AR2 | `VisuallyHidden.test.tsx` `as`, ref, passthrough, and styling tests                              | `as` with `aria-live`; ref; `id`, `role`, `data-testid`; `className`, `style`, `xstyle` | A lost `aria-live`, a missed ref, or a dropped `id` or `role` fails. The styling tests pin today's dropped `className`, `style`, and `xstyle` attribute, which pins the recorded FR3 gap, not the contract. Gap: no test asserts that VisuallyHidden adds no role or live region of its own; the ref test still passes when a wrapper receives the ref; no test asserts other `aria-*` or event props; no test checks that the clip wins over caller styles; and no test covers a component `as` that does or does not forward `className` and `ref`. | `audit:VisuallyHidden/behavior` |
+| PR1      | Source review                                                                                    | Every state                                                                             | Gap: no automated check fails if VisuallyHidden adds state or a hook.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `audit:VisuallyHidden/behavior` |
+| AR1      | Accessibility-tree evidence (`spec:AST-009` FR3)                                                 | Icon-only label; live region                                                            | Gap: no accessibility-tree check proves the hidden content stays in the tree; the unit tests query the DOM.                                                                                                                                                                                                                                                                                                                                                                                                                                           | `audit:VisuallyHidden/a11y`     |
+
+## Decision log
+
+None recorded. The record describes shipped behavior; OQ1 is open.
+
+## Open questions
+
+- **OQ1 — Should VisuallyHidden accept root styling inputs?** (`human-api`)
+  `architecture:public-component-api` INV6 has root styling inputs compose
+  unless a family decision names an exception, and the consumer docs plan to
+  remove `xstyle`; until an owner decides, the styling-free surface is the FR3
+  gap. If styling-free is a deliberate exception, INV6's owner
+  records it (with a `spec:AST-071` known-gap entry) and FR3 links it, and
+  callers keep no way to style the element. If composition is the direction,
+  FR3 stays as written and a conforming implementation closes the gap.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/__tests__/BusyOwnerAnnouncement.test.tsx

@@ -344,7 +344,9 @@ describe.each(OWNERS)(
       const dialog = document.querySelector('dialog') as HTMLDialogElement;
       rerender(<dialog open>{renderOwner(true)}</dialog>);
       await nextFrame();
-      const region = dialog.querySelector('[data-astryx-modal-busy-region]');
+      const region = dialog.querySelector(
+        '[data-astryx-modal-live-region="polite"]',
+      );
       expect(region).not.toBeNull();
       expect(region).toHaveAttribute('role', 'status');
       expect(region).toHaveAttribute('aria-live', 'polite');
@@ -370,7 +372,7 @@ describe.each(OWNERS)(
       await nextFrame();
       const dialog = document.querySelector('dialog') as HTMLDialogElement;
       expect(
-        dialog.querySelector('[data-astryx-modal-busy-region]'),
+        dialog.querySelector('[data-astryx-modal-live-region="polite"]'),
       ).toHaveTextContent('Loading');
       expect(busyAnnouncements()).toEqual([]);
     });
@@ -436,7 +438,7 @@ describe.each(SEARCH_OWNERS)(
       await nextFrame();
       const dialog = document.querySelector('dialog') as HTMLDialogElement;
       expect(
-        dialog.querySelector('[data-astryx-modal-busy-region]'),
+        dialog.querySelector('[data-astryx-modal-live-region="polite"]'),
       ).toHaveTextContent('Loading');
       expect(busyAnnouncements()).toEqual([]);
       vi.restoreAllMocks();
@@ -472,6 +474,65 @@ const SHEET_OWNERS: ReadonlyArray<
   ],
 ];
 
+/** A source whose searches settle in a frame callback that runs before the
+ * busy start's frame, as a fast or cached search can. */
+function frameSettledSource(): SearchSource<SearchableItem> {
+  return {
+    search: async () =>
+      new Promise<SearchableItem[]>(resolve =>
+        requestAnimationFrame(() => resolve([{id: 'alex', label: 'Alex'}])),
+      ),
+    bootstrap: () => [],
+  };
+}
+
+describe.each([
+  ...SEARCH_OWNERS.filter(([name]) => name !== 'Tokenizer'),
+  [
+    'CommandPalette',
+    (source: SearchSource<SearchableItem>) => (
+      <CommandPalette
+        isOpen
+        isInline
+        onOpenChange={() => {}}
+        searchSource={source}
+      />
+    ),
+  ] as const,
+])(
+  '%s search that settles before its busy start is announced (spec:AST-086 FR8)',
+  (_name, renderOwner) => {
+    // Browsers run microtasks after each frame callback, while jsdom runs a
+    // frame's callbacks back to back. One task per callback lets a search that
+    // settles in one callback announce its outcome before the next one runs.
+    const jsdomRequestFrame = window.requestAnimationFrame;
+    const jsdomCancelFrame = window.cancelAnimationFrame;
+    beforeEach(() => {
+      window.requestAnimationFrame = callback =>
+        window.setTimeout(() => callback(performance.now()), 16);
+      window.cancelAnimationFrame = frame => window.clearTimeout(frame);
+    });
+    afterEach(() => {
+      window.requestAnimationFrame = jsdomRequestFrame;
+      window.cancelAnimationFrame = jsdomCancelFrame;
+    });
+
+    it('announces the outcome and never the overtaken busy start', async () => {
+      render(renderOwner(frameSettledSource()));
+      await nextFrame();
+      announce.mockClear();
+      act(() => {
+        fireEvent.change(screen.getByRole('combobox'), {target: {value: 'Al'}});
+      });
+      await nextFrame();
+      await nextFrame();
+      await nextFrame();
+      expect(announce).toHaveBeenCalledWith('1 result');
+      expect(busyAnnouncements()).toEqual([]);
+    });
+  },
+);
+
 describe.each(SHEET_OWNERS)(
   '%s busy start from inside its open sheet (spec:AST-086 Platform support)',
   (_name, renderOwner, openSheet) => {
@@ -511,7 +572,7 @@ describe.each(SHEET_OWNERS)(
       await nextFrame();
       await nextFrame();
       expect(
-        sheet!.querySelector('[data-astryx-modal-busy-region]'),
+        sheet!.querySelector('[data-astryx-modal-live-region="polite"]'),
       ).toHaveTextContent('Loading');
       expect(busyAnnouncements()).toEqual([]);
     });
@@ -742,7 +803,7 @@ describe('CommandPalette busy start inside its modal (spec:AST-086 FR8, FR3)', (
     return (
       document
         .querySelector('dialog[open]')
-        ?.querySelector('[data-astryx-modal-busy-region]') ?? null
+        ?.querySelector('[data-astryx-modal-live-region="polite"]') ?? null
     );
   }