@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/DropdownMenu/lazyMenuBottomSheet.test.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file lazyMenuBottomSheet.test.ts
+ * @input lazyMenuBottomSheet's action-list preload, with the list's module
+ *   failing to load once
+ * @output A failed preload is the preload's result, with the loader's error,
+ *   never an unhandled rejection, and is not kept: the next load asks the
+ *   module loader again
+ * @position Unit test of ./lazyMenuBottomSheet; the hydration case is in
+ *   DropdownMenu.ssr.test.tsx
+ */
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+
+afterEach(() => {
+  vi.doUnmock('./MenuBottomSheetActionList');
+  vi.resetModules();
+});
+
+describe('preloadMenuBottomSheetActionList', () => {
+  it('reports a failed preload in its result, never as an unhandled rejection, and asks the module loader again on the next call', async () => {
+    vi.resetModules();
+    let attempts = 0;
+    vi.doMock('./MenuBottomSheetActionList', () => {
+      attempts += 1;
+      if (attempts === 1) {
+        throw new Error('the connection dropped');
+      }
+      return {MenuBottomSheetActionList: () => null};
+    });
+    const unhandled: unknown[] = [];
+    const onUnhandled = (reason: unknown) => unhandled.push(reason);
+    process.on('unhandledRejection', onUnhandled);
+    try {
+      const {preloadMenuBottomSheetActionList} =
+        await import('./lazyMenuBottomSheet');
+      const failed = await preloadMenuBottomSheetActionList();
+      expect(attempts).toBe(1);
+      // The failure is the preload's result, with the loader's error.
+      expect(failed.isLoaded).toBe(false);
+      expect(failed.isLoaded === false ? failed.error : null).toBeInstanceOf(
+        Error,
+      );
+      // An unhandled rejection is reported after the rejecting task's
+      // microtasks: give it two macrotasks.
+      await new Promise(resolve => setTimeout(resolve, 0));
+      await new Promise(resolve => setTimeout(resolve, 0));
+      expect(unhandled).toEqual([]);
+
+      // The failed load was not kept: the next call asks the loader again.
+      expect(await preloadMenuBottomSheetActionList()).toEqual({
+        isLoaded: true,
+      });
+      expect(attempts).toBe(2);
+    } finally {
+      process.off('unhandledRejection', onUnhandled);
+    }
+  });
+});

package/src/DropdownMenu/lazyMenuBottomSheet.ts

@@ -15,6 +15,11 @@
  * of pages whose dropdowns only open as anchored popovers. Each wrapper keeps
  * the wrapped component's props and renders nothing until its module loads.
  *
+ * The action list preloads at rest, and the preload's result says whether it
+ * loaded. A failed load is not kept, so the next preload or open asks the
+ * module loader again (a loader that retries then loads it; a browser does not
+ * fetch a native module again once its import failed).
+ *
  * Neither wrapper renders on the server or in the render that hydrates server
  * HTML (spec:AST-013 FR9): a lazy component that has not loaded yet would
  * leave server markup incomplete and abort hydration. The closed sheet has no
@@ -47,16 +52,40 @@ const LazyMenuBottomSheet = lazy(async () =>
 let actionListModule: typeof ActionListModule | null = null;
 let actionListLoad: Promise<typeof ActionListModule> | null = null;
 async function loadActionList(): Promise<typeof ActionListModule> {
-  actionListLoad ??= import('./MenuBottomSheetActionList').then(module => {
-    actionListModule = module;
-    return module;
-  });
+  actionListLoad ??= import('./MenuBottomSheetActionList').then(
+    module => {
+      actionListModule = module;
+      return module;
+    },
+    (error: unknown) => {
+      // A failed load (a dropped connection) is not kept: the next caller
+      // asks the module loader again.
+      actionListLoad = null;
+      throw error;
+    },
+  );
   return actionListLoad;
 }
 
-/** Starts loading the action list; a sheet menu calls it at rest. */
-export function preloadMenuBottomSheetActionList(): void {
-  void loadActionList();
+/** What a preload of the action list came to: loaded, or failed with the loader's error. */
+export type ActionListPreload =
+  | {readonly isLoaded: true}
+  | {readonly isLoaded: false; readonly error: unknown};
+
+/**
+ * Starts loading the action list; a sheet menu calls it at rest. Its result
+ * says whether the list loaded: a failure (a dropped connection) is that
+ * result, with the loader's error, and never a rejection. The failed load is
+ * not kept, so the first open asks the module loader again, and a load that
+ * fails there reaches the menu through lazy().
+ */
+export async function preloadMenuBottomSheetActionList(): Promise<ActionListPreload> {
+  try {
+    await loadActionList();
+    return {isLoaded: true};
+  } catch (error) {
+    return {isLoaded: false, error};
+  }
 }
 
 const LazyMenuBottomSheetActionList = lazy(async () =>

package/src/DropdownMenu/renderDropdownItems.tsx

@@ -68,6 +68,28 @@ function renderLeafItem(
   return <DropdownMenuItem key={getItemKey(item, index)} {...itemProps} />;
 }
 
+/**
+ * A data item that declares nested `items` becomes a submenu (data-mode
+ * parity with the compound DropdownMenuSubMenu API), at the top level and
+ * inside a section alike; otherwise it's a leaf. renderDropdownItems owns the
+ * recursion and hands the rendered children to DropdownMenuSubMenu, so
+ * DropdownMenuSubMenu never imports this module back (no import cycle).
+ */
+function renderItem(item: DropdownMenuItemData, index: number): ReactElement {
+  if (item.items && item.items.length > 0) {
+    return (
+      <DropdownMenuSubMenu
+        key={getItemKey(item, index)}
+        icon={item.icon}
+        label={item.label}
+        isDisabled={item.isDisabled}>
+        {renderDropdownItems(item.items)}
+      </DropdownMenuSubMenu>
+    );
+  }
+  return renderLeafItem(item, index);
+}
+
 /**
  * Converts data-driven items into DropdownMenuItem components,
  * so both modes share the same rendering and keyboard navigation path.
@@ -96,28 +118,11 @@ export function renderDropdownItems(items: DropdownMenuOption[]): ReactNode {
               {option.title}
             </div>
           )}
-          {option.items.map(renderLeafItem)}
+          {option.items.map(renderItem)}
         </div>,
       );
     } else if (!('type' in option)) {
-      // A plain item that declares nested `items` becomes a submenu (data-mode
-      // parity with the compound DropdownMenuSubMenu API); otherwise it's a
-      // leaf. renderDropdownItems owns the recursion and hands the rendered
-      // children to DropdownMenuSubMenu — so DropdownMenuSubMenu never imports
-      // this module back (no import cycle).
-      if (option.items && option.items.length > 0) {
-        elements.push(
-          <DropdownMenuSubMenu
-            key={getItemKey(option, i)}
-            icon={option.icon}
-            label={option.label}
-            isDisabled={option.isDisabled}>
-            {renderDropdownItems(option.items)}
-          </DropdownMenuSubMenu>,
-        );
-      } else {
-        elements.push(renderLeafItem(option, i));
-      }
+      elements.push(renderItem(option, i));
     }
   }
 

package/src/EmptyState/EmptyState.spec.md

@@ -3,16 +3,19 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:EmptyState
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, layout, theming, accessibility, testing]
 verified_by:
   [
     packages/core/src/EmptyState/EmptyState.test.tsx,
+    packages/core/src/EmptyState/EmptyState.announce.test.tsx,
+    .github/visual-baseline/manifest.json,
+    scripts/check-knowledge.mjs,
     packages/core/src/theme/themingTargets.test.ts,
     packages/core/src/docPropReferences.test.ts,
   ]
@@ -27,7 +30,7 @@ architecture:
   ]
 contributing: []
 system_specs:
-  [spec:AST-020/FR1, spec:AST-029/FR3, spec:AST-086/FR2, spec:AST-086/FR11]
+  [spec:AST-009, spec:AST-020/FR1, spec:AST-086/FR2, spec:AST-086/FR11]
 ---
 
 # EmptyState component contract
@@ -39,8 +42,8 @@ system_specs:
 | Public contract         | `EmptyState` renders a required title plus optional description, decorative icon, and caller-owned actions in one root without a live role; callers choose heading level and compact layout.     |
 | Behavior                | Null, undefined, boolean, and empty-string optional values create no slot wrapper. Rendered content follows icon, text, then actions order; compact layout reduces spacing and stacks actions.   |
 | End-user impact         | A person reaches a named empty-content message and any next action without blank gaps from shallow-empty optional values; the title fits the surrounding document outline.                       |
-| Builder impact          | Callers supply content and actions, select heading semantics, and may compose supported root props and styling. No additional setup is required.                                                 |
-| Compatibility/readiness | No live role on the root; an EmptyState that appears after load announces once (`spec:AST-086` FR2). Otherwise this draft observes shipped behavior and the scalar-slot remediation.             |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                     |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                                                                       |
 | Review checks           | Reject a missing heading, an informative icon hidden as decorative, a shallow-empty optional scalar that still changes layout, a dropped root prop/ref/style, or a theme target without anatomy. |
 | Governing rules         | `architecture:public-component-api` INV1 and INV5–INV9; `architecture:component-theming-surface` INV2–INV6; `architecture:component-test-sufficiency` INV1–INV7, INV10–INV11; WCAG 2.2.          |
 
@@ -53,10 +56,12 @@ context, optional decorative visual, and optional caller-owned next actions.
 
 ## Compatibility and migration
 
-- Released default preserved: no; EmptyState adds no live role to the root
-- Compatibility class: observational and additive documentation; runtime remediation removes wrappers for nullish, boolean, and empty-string optional values and removes the root's live role
+- Released default preserved: `yes` — heading level 3, default layout, no
+  live role on the root.
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  target, or styling output changes.
 - Controlled/uncontrolled behavior: not applicable
-- Migration decision: none; an EmptyState rendered with the page announces nothing, and one that appears later announces its message once through the shared polite channel, so apps need no change (`spec:AST-086` FR2)
+- Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -87,17 +92,14 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision. A `current` contract contains no unresolved rows.
-
-| ID  | Candidate invariant                                                                                                                                                                     | Basis                                                                                | Draft review state |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
-| FR1 | The component MUST render one root containing the icon, text group, and actions in that reading order when present. The component MUST NOT add a live role or `aria-live` to the root.  | Current implementation and consumer docs; `spec:AST-086` FR2; WCAG 2.2 SC 1.3.2      | verify             |
-| FR2 | The required title MUST render at the caller-selected heading level without changing the component's visual type role.                                                                  | Current implementation, tests, and consumer docs; WCAG 2.2 SC 1.3.1 and SC 2.4.6     | verify             |
-| FR3 | Null, undefined, boolean, and empty-string optional values MUST NOT create a wrapper, layout gap, or assistive-technology node; containers that are shallowly non-empty remain wrapped. | React's direct-child rendering semantics; established public optional-slot interface | verify             |
-| FR4 | The decorative icon wrapper MUST be absent when the slot is absent and hidden from assistive technology when rendered.                                                                  | Current implementation and tests; WCAG 2.2 SC 1.1.1                                  | verify             |
-| FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the root.                                                                             | `architecture:public-component-api` INV5–INV8                                        | verify             |
-| FR6 | Compact layout MUST reduce component spacing and stack the actions slot while preserving content order and root semantics.                                                              | Current implementation, tests, and consumer docs                                     | verify             |
+| ID  | Invariant                                                                                                                                                                               | Basis                                                                                |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| FR1 | The component MUST render one root containing the icon, text group, and actions in that reading order when present. The component MUST NOT add a live role or `aria-live` to the root.  | Current implementation and consumer docs; `spec:AST-086` FR2; WCAG 2.2 SC 1.3.2      |
+| FR2 | The required title MUST render at the caller-selected heading level without changing the component's visual type role.                                                                  | Current implementation, tests, and consumer docs; WCAG 2.2 SC 1.3.1 and SC 2.4.6     |
+| FR3 | Null, undefined, boolean, and empty-string optional values MUST NOT create a wrapper, layout gap, or assistive-technology node; containers that are shallowly non-empty remain wrapped. | React's direct-child rendering semantics; established public optional-slot interface |
+| FR4 | The decorative icon wrapper MUST be absent when the slot is absent and hidden from assistive technology when rendered.                                                                  | Current implementation and tests; WCAG 2.2 SC 1.1.1                                  |
+| FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the root.                                                                             | `architecture:public-component-api` INV5–INV8                                        |
+| FR6 | Compact layout MUST reduce component spacing and stack the actions slot while preserving content order and root semantics.                                                              | Current implementation, tests, and consumer docs                                     |
 
 ### Allowed variation
 
@@ -126,8 +128,9 @@ intentional decision. A `current` contract contains no unresolved rows.
 
 ### Performance and resources
 
-- **PR1 — Render-only surface.** EmptyState owns no retained state, listener,
-  observer, timer, or external resource.
+- **PR1 — No resources of its own.** EmptyState holds no state, listener,
+  observer, or timer of its own; the shared announcement wrapper around its
+  text owns the observation that announces it (`spec:AST-086`).
 
 ## Accessibility contract
 
@@ -176,16 +179,19 @@ No current family record owns EmptyState-specific behavior.
 
 ## Verification map
 
-| Contract       | Verification                                                        | Representative states                             | Mutation or failure expectation                                      | Audit section             |
-| -------------- | ------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------- | ------------------------- |
-| FR1–FR4, AR1–3 | focused DOM tests plus required exact-head accessibility evidence   | title only, all slots, absent/shallow-empty slots | order, heading, live role, or decorative treatment regresses         | `audit:EmptyState/a11y`   |
-| FR5, ORD1      | focused root composition tests plus shared API guards               | DOM/data/event/style inputs, ref, root target     | accepted input is dropped or component semantics/styles are replaced | `audit:EmptyState/api`    |
-| FR6            | compact target/DOM tests plus required exact-head rendered evidence | default and compact, wide and narrow              | compact state, spacing, or action direction no longer applies        | `audit:EmptyState/layout` |
-| PR1            | source review                                                       | every render path                                 | a retained resource appears without a named owner                    | `audit:EmptyState/code`   |
+| Contract            | Verification                                                                                                                           | Representative states                                                                                                                 | Mutation or failure expectation                                                                                                                                                                                                                                                                           | Audit section              |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, FR3, FR4, AR2  | `EmptyState.test.tsx` slot, order, decorative-icon, empty-slot, and live-role tests; stable visual baseline `core-emptystate--default` | Title only; all slots; absent and shallow-empty slots                                                                                 | A wrapper for an absent or shallow-empty slot, a changed slot order, an icon not hidden from assistive technology, or a live role on the root fails; a changed default layout comes back changed for review. Gap: no accessibility-tree check proves the hidden icon or the heading (`spec:AST-009` FR3). | `audit:EmptyState/a11y`    |
+| FR2, AR1            | `EmptyState.test.tsx` heading tests                                                                                                    | Default level 3; every level                                                                                                          | A title that is not the selected heading element fails. Gap: no check that the title keeps one type style at every heading level.                                                                                                                                                                         | `audit:EmptyState/a11y`    |
+| AR3                 | `EmptyState.announce.test.tsx`                                                                                                         | Render with the page; appear later; iframe; inside a live container; message change; server render and hydration; hidden and revealed | An announcement during load or hydration, a missing or repeated announcement when it appears or changes later, hidden text in the message, or an announcement inside a live container fails. Gap: no test asserts that focus stays where it was when EmptyState appears.                                  | `audit:EmptyState/a11y`    |
+| FR5, ORD1           | `EmptyState.test.tsx` ref, `data-testid`, and root-composition tests                                                                   | DOM, data, event, style inputs; caller role; ref                                                                                      | A dropped input, a replaced caller role, or a ref that is not a `div` fails. Gap: the ref test checks only that the ref is a `div`, not that it is the root. No test asserts that caller `xstyle` follows the component styles.                                                                           | `audit:EmptyState/api`     |
+| FR6                 | `EmptyState.test.tsx` compact and theming-target tests                                                                                 | Default and compact                                                                                                                   | A compact layout that is not reflected on the root, title, and description, or that changes slot order, fails. Gap: the reduced spacing and stacked actions have no automated check.                                                                                                                      | `audit:EmptyState/layout`  |
+| PR1                 | Source review                                                                                                                          | Every render path                                                                                                                     | Gap: no automated check fails if EmptyState adds state, a listener, or a timer of its own.                                                                                                                                                                                                                | `audit:EmptyState/code`    |
+| Theming anatomy map | `scripts/check-knowledge.mjs`; `themingTargets.test.ts`                                                                                | Consumer anatomy and current targets                                                                                                  | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                             | `audit:EmptyState/theming` |
 
 ## Decision log
 
-No component-local decision is approved in this draft.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 

package/src/EmptyState/EmptyState.tsx

@@ -24,7 +24,8 @@ import {
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {AnnounceRenderedText} from '../hooks/AnnounceRenderedText';
-import {isRenderable, mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({

package/src/Field/FieldLabel.tsx

@@ -19,7 +19,7 @@
 import {use, useMemo, useRef, type ReactNode, type RefObject} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 
 import {
   colorVars,
@@ -28,9 +28,10 @@ import {
   typographyVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {Icon, renderIconSlot, type IconType} from '../Icon';
-import {Tooltip} from '../Tooltip';
-import {useTranslator} from '../i18n';
+import {Icon, renderIconSlot} from '../Icon/Icon';
+import type {IconType} from '../Icon';
+import {Tooltip} from '../Tooltip/Tooltip';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';

package/src/Field/InputClearButton.tsx

@@ -18,9 +18,9 @@
 
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Button} from '../Button';
-import {Icon} from '../Icon';
-import {useTranslator} from '../i18n';
+import {Button} from '../Button/Button';
+import {Icon} from '../Icon/Icon';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({

package/src/Field/PanelSearchInput.tsx

@@ -42,9 +42,9 @@
 import {useCallback, useState, type Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
-import {Icon} from '../Icon';
+import {Icon} from '../Icon/Icon';
 import {InputClearButton} from './InputClearButton';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {
   getInteractionModality,
   useInteractionModalityTracking,

package/src/FieldStatus/FieldStatus.tsx

@@ -20,7 +20,7 @@
 import React from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {
   colorVars,
   radiusVars,
@@ -31,7 +31,7 @@ import {
 import type {InputStatusType} from '../Field/types';
 import {useEntryAnimation} from '../hooks/useEntryAnimation';
 import {themeProps} from '../utils/themeProps';
-import {Icon} from '../Icon';
+import {Icon} from '../Icon/Icon';
 import type {IconName} from '../Icon';
 import type {FieldStatusVariantMap} from './index';
 import {useFieldStatusAnnouncement} from './useFieldStatusAnnouncement';
@@ -63,6 +63,10 @@ const styles = stylex.create({
     fontFamily: typographyVars['--font-family-body'],
     fontSize: typeScaleVars['--text-supporting-size'],
     lineHeight: typeScaleVars['--text-supporting-leading'],
+    // A validation message often echoes the value that failed (an address, a
+    // URL). Let such an unbroken token wrap inside the field instead of
+    // painting past its edges (WCAG 2.2 SC 1.4.10 Reflow).
+    overflowWrap: 'anywhere',
   },
   attached: {
     marginTop: `calc(-1 * ${ATTACHED_OVERLAP})`,
@@ -118,6 +122,9 @@ const colorStyles = stylex.create({
 export type FieldStatusVariant = keyof FieldStatusVariantMap;
 
 export interface FieldStatusProps extends BaseProps<HTMLDivElement> {
+  /**
+   * Ref to the rendered message box.
+   */
   ref?: React.Ref<HTMLDivElement>;
   /**
    * The type of status to display.