@astryxdesign/core 0.7.5 → 0.7.6-canary.5cd7a15

package/src/DropdownMenu/lazyMenuBottomSheet.test.ts

@@ -0,0 +1,53 @@
+// 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 no 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('drops a failed preload without 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');
+      preloadMenuBottomSheetActionList();
+      await vi.waitFor(() => expect(attempts).toBe(1));
+      // 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([]);
+
+      preloadMenuBottomSheetActionList();
+      await vi.waitFor(() => expect(attempts).toBe(2));
+      const loaded = await import('./MenuBottomSheetActionList');
+      expect(typeof loaded.MenuBottomSheetActionList).toBe('function');
+    } 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; 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,28 @@ 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. */
+/**
+ * Starts loading the action list; a sheet menu calls it at rest. A preload
+ * that fails is dropped, never an unhandled rejection: the first open asks the
+ * module loader again.
+ */
 export function preloadMenuBottomSheetActionList(): void {
-  void loadActionList();
+  loadActionList().catch(() => {});
 }
 
 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.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';

package/src/FileInput/FileInput.test.tsx

@@ -20,6 +20,7 @@ import {
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {FileInput} from './FileInput';
+import {FormLayout} from '../FormLayout';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {InternationalizationProvider} from '../i18n';
 import {Theme} from '../theme/Theme';
@@ -204,6 +205,26 @@ describe('FileInput', () => {
     expect(trigger).not.toHaveAttribute('aria-required');
   });
 
+  it('conveys required state under FormLayout defaultOptionality="required" unless isOptional (FormLayout FR5)', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <FileInput label="Resume" value={null} onChange={() => {}} />
+        <FileInput
+          label="Cover letter"
+          isOptional
+          value={null}
+          onChange={() => {}}
+        />
+      </FormLayout>,
+    );
+    expect(
+      screen.getByRole('button', {name: 'Resume'}),
+    ).toHaveAccessibleDescription(/Required/);
+    expect(
+      screen.getByRole('button', {name: /Cover letter/}),
+    ).not.toHaveAccessibleDescription(/Required/);
+  });
+
   it('combines required with the description in the accessible description', () => {
     render(
       <FileInput

package/src/FileInput/FileInput.tsx

@@ -68,6 +68,7 @@ import {useTranslator} from '../i18n';
 import type {TranslatorFn} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 function formatFileSize(bytes: number, t: TranslatorFn): string {
   if (bytes < 1024) {
     return t('@astryx.fileInput.fileSize.bytes', {size: bytes});
@@ -544,7 +545,9 @@ export function FileInput({
   // at a visually hidden "Required" span — mirroring the Field label's visible
   // indicator (where isOptional takes precedence) and the pattern Slider uses
   // for its thumbs.
-  const conveysRequired = isRequired && !isOptional;
+  // A surrounding FormLayout's defaultOptionality="required" makes an unmarked
+  // field required too (FormLayout FR5).
+  const conveysRequired = useResolvedRequired({isRequired, isOptional});
 
   const ariaDescribedBy =
     [

package/src/FormLayout/FormLayout.spec.md

@@ -63,12 +63,11 @@ This table is a review projection; the body below is authoritative.
 
 ## Current-state impact
 
-- **Required state lost for four controls (FR5, AR2).** Under
+- **Required state lost for two controls (FR5, AR2).** Under
   `defaultOptionality="required"` the visible "Required" marker is hidden,
-  but Typeahead and Tokenizer set no `aria-required`, and FileInput and
-  Slider build their required description from `isRequired` alone. Screen
-  reader users hear those fields as not required, while sighted users see
-  the form-wide convention.
+  but Typeahead and Tokenizer set no `aria-required`. Screen reader users
+  hear those fields as not required, while sighted users see the form-wide
+  convention.
 
 ## Ownership boundary
 
@@ -101,7 +100,7 @@ This table is a review projection; the body below is authoritative.
 | FR2 | `horizontal` places every direct child in one `1fr` grid column in the document's logical inline order, with a `--spacing-4` gap and no component-owned wrap rule.                                                                                                                                                                                                                                                                                                                                                                                          | Released source, tests, and stories                             |
 | FR3 | `horizontal-labels` is a two-column grid (`auto 1fr`) with a `--spacing-3` row gap and `--spacing-4` column gap, items aligned to the start, so Field labels sit on the inline-start side of their controls; at a viewport width of 480px or below it becomes one flex column with a `--spacing-4` gap. OQ1 holds whether the collapsed label and control need a tighter pair gap.                                                                                                                                                                          | Released source, Field composition, and tests                   |
 | FR4 | FormLayout provides its direction and `defaultOptionality` to descendants in the same layer; a nested FormLayout replaces both for its own descendants, and content in a layer opened inside a FormLayout starts without them (`spec:AST-038` FR7, FR8).                                                                                                                                                                                                                                                                                                    | Context source and tests                                        |
-| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose the resolved `aria-required`, while native `required` stays tied to an explicit field `isRequired`. Unset keeps each field's own indicators. Implementation gap: under `defaultOptionality="required"`, Typeahead and Tokenizer set no `aria-required`, and FileInput and Slider describe required state from `isRequired` alone, so those fields are announced as not required while the marker is hidden (Current-state impact). | Tests; `family:input-fields` ownership                          |
+| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose the resolved `aria-required`, while native `required` stays tied to an explicit field `isRequired`. Unset keeps each field's own indicators. Implementation gap: under `defaultOptionality="required"`, Typeahead and Tokenizer set no `aria-required`, so those fields are announced as not required while the marker is hidden (Current-state impact). | Tests; `family:input-fields` ownership                          |
 | FR6 | The root is a `div`. `ref`, DOM, data, ARIA, and event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the `form-layout` target.                                                                                                                                                                                                                                                                                                                                                           | `architecture:public-component-api/INV5–INV8`; source and tests |
 
 ### Allowed variation
@@ -135,7 +134,7 @@ This table is a review projection; the body below is authoritative.
 ## Accessibility contract
 
 - **AR1 — Layout remains nonsemantic.** FormLayout renders a `<div>` and does not imply `<form>`, group, label, or submission semantics; callers provide those when their composition needs them.
-- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology. Implementation gap: Typeahead, Tokenizer, FileInput, and Slider do not (FR5).
+- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology. Implementation gap: Typeahead and Tokenizer do not (FR5).
 - **AR3 — Logical order is preserved.** Every direction retains DOM order and logical inline flow; FormLayout does not create a separate keyboard order.
 
 ## Design relationships
@@ -191,7 +190,7 @@ The root target reflects the closed `direction` axis. It owns the outer arrangem
 | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
 | FR1–FR3        | `FormLayout.test.tsx` direction snapshots; `FormLayout.stories.tsx` play checks; stable visual baseline `core-formlayout--vertical` | Vertical, horizontal, horizontal-labels wide and narrow                  | A changed style class set fails the snapshots; a narrow horizontal-labels control narrower than the layout, or a wide label not before its control, fails the play checks; a changed vertical layout comes back changed for review. The story play guard also runs the AuditMatrix play right-to-left at 320px and the default width, where mirrored horizontal columns are asserted. Gap: no right-to-left check asserts that a horizontal-labels label sits on the inline-start side of its control. | `audit:FormLayout/behavior`      |
 | FR4, ORD1      | `FormLayout.test.tsx` context and nesting tests; `Layer/layerScopedContext.test.tsx`                                                | Default, explicit, nested; content in a fixed Layer and an inline Dialog | A lost default or value, lost shadowing by an inner layout's explicit values, or content inside a layer that still reads the outer `defaultOptionality` fails. Gap: no test covers an inner layout with unset props (which supplies its own defaults) or `direction` across a layer boundary.                                                                                                                                                                                                          | `audit:FormLayout/behavior`      |
-| FR5, ORD3, AR2 | `FormLayout.test.tsx` optionality and `aria-required` tests                                                                         | Required, optional, unset defaults; explicit exceptions                  | A redundant marker, a missing `aria-required`, or a native `required` from the default fails. Gap: no test covers Typeahead, Tokenizer, FileInput, or Slider under a `required` default, which do not expose it.                                                                                                                                                                                                                                                                                       | `audit:FormLayout/accessibility` |
+| FR5, ORD3, AR2 | `FormLayout.test.tsx` optionality and `aria-required` tests                                                                         | Required, optional, unset defaults; explicit exceptions                  | A redundant marker, a missing `aria-required`, or a native `required` from the default fails. FileInput and Slider tests cover a `required` default. Gap: no test covers Typeahead or Tokenizer under a `required` default, which do not expose it.                                                                                                                                                                                                                                                                                       | `audit:FormLayout/accessibility` |
 | FR6, ORD2      | `FormLayout.test.tsx` ref, passthrough, and owned-metadata tests; `themingTargets.test.ts`                                          | Ref, attributes, colliding `data-direction`                              | A ref on a non-`div`, a dropped `id` or `role`, or a replaced `data-direction` fails. Gap: no test covers event props or the styling-input merge order.                                                                                                                                                                                                                                                                                                                                                | `audit:FormLayout/api`           |
 | AR1, AR3       | `FormLayout.test.tsx` div and passthrough tests; `FormLayout.stories.tsx` play checks                                               | Plain root; caller `role`                                                | A non-`div` root or a dropped caller `role` fails. Horizontal columns that do not mirror right-to-left fail the AuditMatrix play under the story play guard. Gap: no check fails if FormLayout adds a role of its own.                                                                                                                                                                                                                                                                                 | `audit:FormLayout/accessibility` |
 | PR1            | Source review                                                                                                                       | Every direction                                                          | Gap: no automated check covers context identity or added resources.                                                                                                                                                                                                                                                                                                                                                                                                                                    | `audit:FormLayout/behavior`      |

package/src/Heading/Heading.tsx

@@ -45,7 +45,7 @@ import {
 import {useTruncation} from '../Text/useTruncation';
 import {resolveStyleColor} from '../Text/Text';
 import type {LayerPlacement} from '../Layer';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';

package/src/Icon/Icon.tsx

@@ -38,7 +38,7 @@ import {useThemeName} from '../theme/useTheme';
 import {resolveIcon} from './globalIconRegistry';
 import type {IconName, NamespacedIconName} from './globalIconRegistry';
 import type {IconVariant} from './index';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 import {useIconSize} from './IconDefaultSizeContext';
 import {iconSizeStyles, type IconSize} from './IconSize.stylex';

package/src/Indicator/CheckIndicator.spec.md

@@ -1,20 +1,19 @@
 ---
 schema_version: 3
-template_version: 6
+template_version: 7
 kind: component
 id: component:CheckIndicator
-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, theming, accessibility, visual]
 verified_by:
   [
     packages/core/src/Indicator/Indicator.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
-    apps/storybook/stories/Indicator.stories.tsx,
   ]
 modules: []
 families: []
@@ -33,17 +32,17 @@ system_specs: []
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                   |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `CheckIndicator` is exported from `@astryxdesign/core/Indicator`; `state` is required, `size` defaults to `md`, `isDisabled` defaults to `false`, and `children` may replace the built-in mark.                                                            |
-| Behavior                | The component draws a decorative check glyph only when checked. Shallow-renderable `children` replace that glyph in either state; unchecked without replacement content renders no element.                                                                |
-| End-user impact         | People receive one selection cue from the owning control without a duplicate accessible object or an empty placeholder beside unselected rows.                                                                                                             |
-| Builder impact          | Builders may replace the named `check` indicator or compose host-owned classes and styling without taking over the owning control's semantics.                                                                                                             |
-| Compatibility/readiness | The released component and default state behavior remain unchanged. The checked glyph path currently drops the declared `ref`; this draft records that current-authority gap without choosing a new DOM or ref contract.                                   |
-| Review checks           | Reject lost `aria-hidden`, a mark in the unchecked default, a missing checked mark, dropped supported DOM/styling passthrough, changed replacement precedence, a new component-owned theme target, or any claim that the checked-path ref gap is resolved. |
-| Governing rules         | `architecture:public-component-api/INV1,INV5,INV6,INV8,INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`.                                                                         |
+| Area                    | Contract                                                                                                                                                                                                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `CheckIndicator` is exported from `@astryxdesign/core/Indicator`; `state` is required, `size` defaults to `md`, `isDisabled` defaults to `false`, and `children` may replace the built-in mark.                                                                    |
+| Behavior                | The component draws a decorative check glyph only when checked. Shallow-renderable `children` replace that glyph in either state; unchecked without replacement content renders no element.                                                                        |
+| End-user impact         | People receive one selection cue from the owning control without a duplicate accessible object or an empty placeholder beside unselected rows.                                                                                                                     |
+| Builder impact          | Builders may replace the named `check` indicator or compose host-owned classes and styling without taking over the owning control's semantics.                                                                                                                     |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The checked glyph path drops the declared `ref`; listed under Current-state impact, with the fix open (OQ1).                                                                                             |
+| Review checks           | Reject lost `aria-hidden`, a mark in the unchecked default, a missing checked mark, dropped supported DOM/styling passthrough, changed replacement precedence, a new component-owned theme target, or a checked path that still drops the ref once OQ1 is decided. |
+| Governing rules         | `architecture:public-component-api/INV1,INV5,INV6,INV8,INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`.                                                                                 |
 
-This table is a review projection; the body below is authoritative only after owner approval.
+This table is a review projection; the body below is authoritative.
 
 ## Intent
 
@@ -52,7 +51,8 @@ Render the replaceable, decorative checkmark used by a host to show that one opt
 ## Compatibility and migration
 
 - Released default preserved: yes
-- Compatibility class: observational only; no runtime or public-type change
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
 - Controlled/uncontrolled behavior: not applicable; `state` is supplied by the owner
 - Migration decision: none; the public component and `check` registry name remain unchanged
 
@@ -68,29 +68,29 @@ Consumer migration instructions belong in consumer docs and release notes.
 **Does not own / non-goals**
 
 - Selection role, accessible name, state, focus, keyboard, activation, or busy semantics — owned by the composing control.
-- Persistent checkbox or radio chrome — owned by `component:CheckboxIndicator` or `component:RadioIndicator`.
+- Persistent checkbox or radio chrome — owned by `component:CheckboxIndicator` or `component:Indicator`.
 - Row placement and logical-edge layout — owned by the host component.
 - The behavior or accessibility of consumer-supplied replacement content.
 
 ## Public concepts
 
-| Concept             | Closed values or states     | Meaning                                                                                                                                                                     | Availability by variant/orientation/state             | Default            | Owner                      | Stability                                  | Invalid-value behavior                             |
-| ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------ | -------------------------- | ------------------------------------------ | -------------------------------------------------- |
-| state               | `unchecked`, `checked`      | Selects whether the built-in check glyph is absent or present.                                                                                                              | Every render path.                                    | required           | `component:CheckIndicator` | stable                                     | rejected by the public type                        |
-| size                | `sm`, `md`                  | Selects the shared indicator size; both current values use the `sm` Icon glyph.                                                                                             | Checked and replacement-content roots.                | `md`               | `component:CheckIndicator` | stable                                     | rejected by the public type                        |
-| disabled appearance | enabled, disabled           | Mirrors the owning control's disabled color without creating semantics.                                                                                                     | Checked and replacement-content roots.                | enabled            | `component:CheckIndicator` | stable                                     | boolean only                                       |
-| replacement content | shallow renderable or empty | Replaces the built-in mark in either state when `isRenderable(children)` returns true. React elements and containers take this branch even when descendants render nothing. | Every state; replacement content creates a span root. | built-in mark path | `component:CheckIndicator` | observed; empty-container policy unsettled | unsupported values follow React rendering behavior |
+| Concept             | Closed values or states     | Meaning                                                                                                                                                                     | Availability by variant/orientation/state             | Default            | Owner                      | Stability                                 | Invalid-value behavior                             |
+| ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------ | -------------------------- | ----------------------------------------- | -------------------------------------------------- |
+| state               | `unchecked`, `checked`      | Selects whether the built-in check glyph is absent or present.                                                                                                              | Every render path.                                    | required           | `component:CheckIndicator` | stable                                    | rejected by the public type                        |
+| size                | `sm`, `md`                  | Selects the shared indicator size; both current values use the `sm` Icon glyph.                                                                                             | Checked and replacement-content roots.                | `md`               | `component:CheckIndicator` | stable                                    | rejected by the public type                        |
+| disabled appearance | enabled, disabled           | Mirrors the owning control's disabled color without creating semantics.                                                                                                     | Checked and replacement-content roots.                | enabled            | `component:CheckIndicator` | stable                                    | boolean only                                       |
+| replacement content | shallow renderable or empty | Replaces the built-in mark in either state when `isRenderable(children)` returns true. React elements and containers take this branch even when descendants render nothing. | Every state; replacement content creates a span root. | built-in mark path | `component:CheckIndicator` | stable; empty-container policy open (OQ2) | unsupported values follow React rendering behavior |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                              | Basis                                                                     | Draft review state |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------ |
-| FR1 | The component MUST render one decorative check glyph when `state="checked"` and no replacement content is present, and MUST set its own `aria-hidden="true"` after caller passthrough.                                                                                                                                                                           | shipped source; `architecture:public-component-api/INV5`                  | verify             |
-| FR2 | The default component MUST render no element when `state="unchecked"` and no replacement content is present.                                                                                                                                                                                                                                                     | shipped source, docs, tests, and stories                                  | verify             |
-| FR3 | The current implementation uses shallow `isRenderable(children)` replacement precedence in both states: nullish values, booleans, and the empty string keep the built-in state behavior; React elements and containers replace it even when descendants render nothing. This draft does not settle whether empty-container behavior should remain public policy. | shipped source and regression tests                                       | verify             |
-| FR4 | Every rendered root MUST preserve supported DOM props, `className`, `style`, and `xstyle` while keeping component-owned accessibility precedence. Under `architecture:public-component-api/INV8`, the declared ref also MUST reach the promised root; the replacement-content span does, but the checked Icon path currently drops it.                           | `architecture:public-component-api/INV5,INV6,INV8`; shipped source review | human decision     |
-| FR5 | The built-in checked mark MUST remain an Icon-owned painter on the same element as host-supplied classes; CheckIndicator MUST NOT add a wrapper or a distinct public target without an approved contract change.                                                                                                                                                 | shipped source; `architecture:component-theming-surface/INV3–INV5`        | verify             |
-| FR6 | Disabled color and replacement-content color MUST continue to use semantic tokens rather than raw color values.                                                                                                                                                                                                                                                  | shipped source; current token and theming architecture                    | verify             |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                    | Basis                                                              |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| FR1 | The component MUST render one decorative check glyph when `state="checked"` and no replacement content is present, and MUST set its own `aria-hidden="true"` after caller passthrough.                                                                                                                                                                       | shipped source; `architecture:public-component-api/INV5`           |
+| FR2 | The default component MUST render no element when `state="unchecked"` and no replacement content is present.                                                                                                                                                                                                                                                 | shipped source, docs, tests, and stories                           |
+| FR3 | Replacement uses shallow `isRenderable(children)` precedence in both states: nullish values, booleans, and the empty string keep the built-in state behavior; React elements and containers replace it even when descendants render nothing (OQ2).                                                                                                           | shipped source and regression tests                                |
+| FR4 | Every rendered root MUST preserve supported DOM props, `className`, `style`, and `xstyle` while keeping component-owned accessibility precedence, and the declared ref MUST reach the rendered root (`architecture:public-component-api/INV8`). Implementation gap: the replacement-content span receives the ref, but the checked Icon path drops it (OQ1). | `architecture:public-component-api/INV5,INV6,INV8`; current source |
+| FR5 | The built-in checked mark MUST remain an Icon-owned painter on the same element as host-supplied classes; CheckIndicator MUST NOT add a wrapper or a distinct public target without an approved contract change.                                                                                                                                             | shipped source; `architecture:component-theming-surface/INV3–INV5` |
+| FR6 | Disabled color and replacement-content color MUST continue to use semantic tokens rather than raw color values.                                                                                                                                                                                                                                              | shipped source; current token and theming architecture             |
 
 ### Allowed variation
 
@@ -126,7 +126,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | Chrome           | CheckIndicator intentionally owns no persistent chrome. | observed shipped representation         | not applicable       | FR2, FR5           |
 | State mark       | Checked state renders the shared decorative check Icon. | Icon-owned current theming architecture | supporting state cue | FR1, FR5–FR6       |
 
-The shared `Indicator.doc.mjs` owns anatomy and targets for CheckboxIndicator, CheckIndicator, and RadioIndicator together. This component draft does not add an `anatomy-theming:v1` block while that shared consumer record remains the canonical cross-component inventory; the block is optional during migration. CheckIndicator owns no persistent chrome and delegates its built-in checked mark to Icon.
+The shared `Indicator.doc.mjs` lists anatomy and targets for CheckboxIndicator, CheckIndicator, and RadioIndicator together, so this record carries no anatomy-theming map. CheckIndicator owns no persistent chrome and delegates its built-in checked mark to Icon.
 
 ## Family and system relationships
 
@@ -136,23 +136,28 @@ The shared `Indicator.doc.mjs` owns anatomy and targets for CheckboxIndicator, C
 
 ## Verification map
 
-| Contract    | Verification                                                | Representative states                                                                   | Mutation or failure expectation                                                                                             | Audit section                   |
-| ----------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1–FR3     | `Indicator.test.tsx` state and replacement-content cases    | checked, unchecked, empty scalar, visible child, numeric 0                              | Removing the glyph, adding unchecked chrome, or choosing the wrong children branch fails DOM assertions.                    | `audit:CheckIndicator/behavior` |
-| FR1, AR1    | `Indicator.test.tsx` decorative-contract cases              | glyph and replacement roots; hostile `aria-hidden` input                                | Removing or reordering owned `aria-hidden` exposes duplicate semantics.                                                     | `audit:CheckIndicator/a11y`     |
-| FR4         | `Indicator.test.tsx`, strict lint, and source review        | neutral DOM props on both roots; replacement-root class; checked-path style composition | Passthrough stops reaching a rendered root or the checked Icon stops receiving composed `className`, `style`, and `xstyle`. | `audit:CheckIndicator/api`      |
-| FR4 ref gap | source review                                               | checked Icon root and replacement-content span                                          | The declared ref remains `null` on the checked path while reaching the replacement span.                                    | `audit:CheckIndicator/api`      |
-| FR5–FR6     | source review, Icon target guards, and rendered evidence    | checked, disabled, replacement content; light/dark                                      | A wrapper separates the host target from the painter or semantic color stops reaching the mark.                             | `audit:CheckIndicator/theming`  |
-| All         | `Indicator.stories.tsx`, component-scoped axe and RTL audit | all states, sizes, disabled, replacement content                                        | A required rendered state is unreachable or gains an accessibility/RTL failure.                                             | `audit:CheckIndicator/testing`  |
+| Contract      | Verification                                                                                           | Representative states                                       | Mutation or failure expectation                                                                                                                                                                                                                                                                                               | Audit section                        |
+| ------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| FR1, FR2, FR3 | `Indicator.test.tsx` CheckIndicator state and replacement cases; falsy-children cases                  | Checked, unchecked, empty scalar, visible child, `0`        | Removing the glyph, adding unchecked chrome, or choosing the wrong children branch fails.                                                                                                                                                                                                                                     | `audit:CheckIndicator/behavior`      |
+| FR1, AR1      | `Indicator.test.tsx` decorative-contract cases                                                         | Glyph and replacement roots; a caller `aria-hidden={false}` | A root that a caller can expose fails. Evidence gap: no test asserts that replacement content is not the only state expression (AR2).                                                                                                                                                                                         | `audit:CheckIndicator/accessibility` |
+| FR4           | `Indicator.test.tsx` "forwards caller props and styling on both render paths"                          | Both render paths                                           | A caller DOM prop that stops reaching either root, or a `className` that stops reaching the replacement span, fails. Evidence gap: no test asserts `className`, `style`, or `xstyle` on the checked-glyph path, `style` or `xstyle` on the replacement span, or the ref on either path (the checked-path ref is the FR4 gap). | `audit:CheckIndicator/api`           |
+| FR5, FR6      | `themingTargets.test.ts`                                                                               | Checked glyph                                               | A rendered class absent from the documented targets fails. Evidence gap: no test asserts that no wrapper separates host classes from the Icon painter, or that disabled and replacement colors use semantic tokens.                                                                                                           | `audit:CheckIndicator/theming`       |
+| ORD1, PR1     | Covered by the FR1–FR4 rows. Evidence gap: no test asserts the absence of state, effects, or listeners | —                                                           | —                                                                                                                                                                                                                                                                                                                             | `audit:CheckIndicator/behavior`      |
+
+## Current-state impact
+
+- **Checked-path ref (FR4).** The declared ref is `null` when CheckIndicator
+  draws its checked glyph, against `architecture:public-component-api` INV8; the
+  fix is OQ1.
 
 ## Decision log
 
-None. This draft records only verified shipped behavior.
+No component-local decision.
 
 ## Open questions
 
 - **OQ1 — Should CheckIndicator preserve its declared `HTMLSpanElement` ref by owning a stable span root in the checked path, or should the public ref contract change to match the Icon-owned painter?** (`human-api`) The current checked path returns `null`; either correction changes a released DOM or ref contract.
-- **OQ2 — Should empty React containers continue to suppress the built-in state mark?** (`human-api`) This observational draft records the current shallow branch without approving it as future policy.
+- **OQ2 — Should empty React containers continue to suppress the built-in state mark?** (`human-api`) FR3 records that they do today.
 
 ## Content boundary
 

package/src/Indicator/CheckIndicator.tsx

@@ -34,7 +34,8 @@ import * as stylex from '@stylexjs/stylex';
 import type {SVGProps} from 'react';
 import {Icon} from '../Icon/Icon';
 import {colorVars} from '../theme/tokens.stylex';
-import {isRenderable, mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
 import type {IndicatorProps} from './types';
 
 /** The check glyph matches the control sizes the indicator families share. */