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

package/src/DropdownMenu/DropdownMenu.tsx

@@ -67,6 +67,7 @@ import {
   type DropdownMenuSurfaceValue,
 } from './DropdownMenuContext';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useListFocus} from '../hooks/useListFocus';
 import {useMenuPress} from '../hooks/useMenuPress';
 import type {MenuPressPointerType} from '../hooks/menuPressGesture';
@@ -621,6 +622,11 @@ function DropdownMenuBottomSheet({
   const button = buttonFromProps ?? {label: t(DEFAULT_BUTTON_I18N_KEY)};
   const backLabel = t('@astryx.dropdownMenu.back');
   const buttonRef = useRef<HTMLElement>(null);
+  // The caller's `button.ref` rides along with the sheet's own trigger ref.
+  const triggerRef = useMergedRefs<HTMLButtonElement>(
+    buttonRef as React.Ref<HTMLButtonElement>,
+    button.ref,
+  );
   const triggerId = useId();
   const sheetId = useId();
   const actionListRef = useRef<HTMLDivElement>(null);
@@ -645,9 +651,10 @@ function DropdownMenuBottomSheet({
     }
   }
   // The closed sheet renders nothing, so load its rows at rest: the first
-  // open shows the actions at once.
+  // open shows the actions at once. The preload's result says whether they
+  // loaded; after a failure the first open loads them.
   useEffect(() => {
-    preloadMenuBottomSheetActionList();
+    void preloadMenuBottomSheetActionList();
   }, []);
   const currentSubmenu = submenuPath.at(-1);
   const currentItems = currentSubmenu?.items ?? items;
@@ -785,13 +792,15 @@ function DropdownMenuBottomSheet({
       {currentTitle}
     </Heading>
   );
+  // A stable ref: an inline one re-runs on every render (null, then the element).
+  const sheetTriggerRef = useCallback((el: HTMLElement | null) => {
+    buttonRef.current = el;
+  }, []);
   return (
     <>
       {renderTrigger != null ? (
         renderTrigger({
-          ref: el => {
-            buttonRef.current = el;
-          },
+          ref: sheetTriggerRef,
           id: triggerId,
           onClick: handleSheetTriggerClick,
           onClickCapture: () => {},
@@ -806,7 +815,7 @@ function DropdownMenuBottomSheet({
       ) : (
         <Button
           {...button}
-          ref={buttonRef as React.Ref<HTMLButtonElement>}
+          ref={triggerRef}
           xstyle={[
             isOpen && styles.triggerOpen,
             button.xstyle,
@@ -1584,11 +1593,35 @@ function DropdownMenuPopover({
       </>
     );
 
-  const triggerProps: DropdownMenuTriggerProps = {
-    ref: el => {
+  // Stable trigger refs. An inline ref is a new function every render, so React
+  // re-runs it on every commit (null, then the element), and each run moved the
+  // popover's anchor off the trigger and back: two inline-style writes on the
+  // trigger per render of the menu.
+  const popoverTriggerRef = popover.triggerRef;
+  const triggerRef = useCallback(
+    (el: HTMLElement | null) => {
       buttonRef.current = el;
-      popover.triggerRef(el);
+      popoverTriggerRef(el);
+    },
+    [popoverTriggerRef],
+  );
+  const consumerButtonRef = button.ref;
+  const buttonTriggerRef = useCallback(
+    (el: HTMLButtonElement | null) => {
+      triggerRef(el);
+      if (typeof consumerButtonRef === 'function') {
+        consumerButtonRef(el);
+      } else if (consumerButtonRef) {
+        /* eslint-disable react-compiler/react-compiler -- ref callback: forwarding consumer ref object */
+        consumerButtonRef.current = el;
+        /* eslint-enable react-compiler/react-compiler */
+      }
     },
+    [triggerRef, consumerButtonRef],
+  );
+
+  const triggerProps: DropdownMenuTriggerProps = {
+    ref: triggerRef,
     id: triggerId,
     onClick: handleButtonClick,
     onClickCapture: handleTriggerClickCapture,
@@ -1611,18 +1644,7 @@ function DropdownMenuPopover({
       ) : (
         <Button
           {...button}
-          ref={el => {
-            buttonRef.current = el;
-            popover.triggerRef(el);
-            const consumerRef = button.ref;
-            if (typeof consumerRef === 'function') {
-              consumerRef(el);
-            } else if (consumerRef) {
-              /* eslint-disable react-compiler/react-compiler -- ref callback: forwarding consumer ref object */
-              consumerRef.current = el;
-              /* eslint-enable react-compiler/react-compiler */
-            }
-          }}
+          ref={buttonTriggerRef}
           xstyle={[
             styles.triggerPressable,
             isOpen && styles.triggerOpen,

package/src/DropdownMenu/DropdownMenuCheckboxItem.spec.md

@@ -0,0 +1,192 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:DropdownMenuCheckboxItem
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-31
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming]
+verified_by:
+  [
+    packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx,
+    packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+  ]
+contributing: []
+system_specs: [spec:AST-020]
+---
+
+# DropdownMenuCheckboxItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                               |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | One pointer-menu row that toggles an independent boolean: `label`, `description`, `icon`, `endContent`, controlled `value` and `onChange`, `isDisabled`, `hasCloseOnSelect` (default `false`), root inputs, and a ref. |
+| Behavior                | The row is one `menuitemcheckbox` whose `aria-checked` is its `value`; an enabled activation reports `!value` and keeps the menu open unless asked to close; a disabled row is inert.                                  |
+| End-user impact         | People toggle options without the menu closing on each change, and screen-reader users hear one checkbox per row.                                                                                                      |
+| Builder impact          | Builders own the value; the row composes their click and pointer-move handlers with its own activation and hover focus.                                                                                                |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Enter keeping the menu open is listed under Current-state impact (OQ1).                                                                                      |
+| Review checks           | Reject a nested announced checkbox, a row that closes by default, a dropped caller handler, or an activation while disabled.                                                                                           |
+| Governing rules         | `spec:AST-020` FR15; `architecture:public-component-api` INV5–INV8; `architecture:interaction-modality`.                                                                                                               |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+DropdownMenuCheckboxItem renders one compound-mode row that toggles an
+independent boolean inside the pointer presentation of DropdownMenu.
+DropdownMenu owns focus movement, typeahead, keyboard click synthesis, and the
+close lifecycle.
+
+## Compatibility and migration
+
+- Released default preserved: yes (`hasCloseOnSelect=false`).
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change.
+- Controlled/uncontrolled behavior: controlled; `value` is caller-owned.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One `role="menuitemcheckbox"` root, its `aria-checked`, label, description,
+  icon, end content, disabled state, ref, supported host inputs, and styling
+  inputs.
+- Activation: reporting `!value`, the close policy, and composing the caller's
+  click and pointer-move handlers.
+- The decorative checkbox marker and the row's `dropdown-menu-item` target.
+
+**Does not own / non-goals**
+
+- Focus entry, roving focus, typeahead, and Enter/Space click synthesis — owned
+  by `component:DropdownMenu`.
+- Checkbox chrome — delegated to `component:Indicator`.
+- Whether disabled rows stay keyboard-discoverable — `component:DropdownMenu`
+  OQ1.
+
+## Public concepts
+
+| Concept       | Closed values or states | Meaning                                    | Availability      | Default     | Owner     | Stability | Invalid-value behavior        |
+| ------------- | ----------------------- | ------------------------------------------ | ----------------- | ----------- | --------- | --------- | ----------------------------- |
+| Checked state | `true`, `false`         | The boolean the row shows and toggles.     | Every row         | required    | caller    | stable    | Required by the public type.  |
+| Close policy  | close; remain open      | Whether an enabled toggle closes the menu. | Every enabled row | remain open | component | stable    | Omission keeps the menu open. |
+| Availability  | enabled; disabled       | Whether the row can activate.              | Every row         | enabled     | component | stable    | Disabled blocks activation.   |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Basis                                                                        |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| FR1 | The row renders one element with `role="menuitemcheckbox"` whose `aria-checked` equals `value`; the checkbox marker is decorative (`aria-hidden`), so the row is the only announced control.                                                                                                                                                                                                                                                                                             | `spec:AST-020` FR15; current source and tests                                |
+| FR2 | An enabled activation, by pointer or by the parent's synthesized Enter/Space click, calls `onChange(!value)`, then closes the menu when `hasCloseOnSelect` is set, then calls the caller's `onClick`; without `hasCloseOnSelect` the menu stays open. The APG Menu pattern's Enter closes the menu, and `spec:AST-020` FR15 requires this record to name any required part it does not adopt. Implementation gap: Enter keeps the menu open by default, and no exception is named (OQ1). | `spec:AST-020` FR15; `architecture:public-component-api` INV7; current tests |
+| FR3 | A disabled row exposes `aria-disabled="true"`, renders no `tabindex`, and on activation calls neither `onChange` nor the caller's activation handlers.                                                                                                                                                                                                                                                                                                                                   | Current source and tests                                                     |
+| FR4 | Ref, supported host attributes and handlers, `className`, `style`, and `xstyle` reach or compose on the row root; caller `onPointerMove` composes with the row's hover focus.                                                                                                                                                                                                                                                                                                            | `architecture:public-component-api` INV5–INV8; current tests                 |
+| FR5 | The marker is the shared checkbox Indicator, `sm` in a small menu; the row carries the `dropdown-menu-item` target with the menu size.                                                                                                                                                                                                                                                                                                                                                   | `architecture:component-theming-surface`; current source and tests           |
+| FR6 | The row adds no key handler or tab stop of its own: enabled rows are `tabindex="-1"` for the parent's roving focus, and the parent's arrow keys skip a disabled row (`component:DropdownMenu` FR17).                                                                                                                                                                                                                                                                                     | `architecture:interaction-modality`; parent tests                            |
+
+### Allowed variation
+
+- **AV1 — Content.** Label, description, icon, and end content are caller
+  content.
+- **AV2 — Theme paint.** Themes may restyle the row and marker targets.
+
+### Representative states
+
+| State           | Required invariant                     | Allowed variation      |
+| --------------- | -------------------------------------- | ---------------------- |
+| Unchecked       | `aria-checked="false"`; marker empty.  | Content.               |
+| Checked         | `aria-checked="true"`; marker checked. | Content.               |
+| Close on select | An enabled toggle closes the menu.     | —                      |
+| Disabled        | `aria-disabled="true"`; no activation. | Content stays visible. |
+
+### Transformation and precedence order
+
+- **ORD1 — Activation.** Disabled guard → `onChange(!value)` → close when
+  `hasCloseOnSelect` → caller `onClick`.
+
+### Performance and resources
+
+- **PR1 — Shared press listeners.** The row shares the press controller's
+  window and document listeners; it adds no per-row listener, observer, timer,
+  or request.
+
+## Accessibility contract
+
+- **AR1 — One checkbox control.** The row owns `menuitemcheckbox`, its
+  accessible name, checked state, focus, and activation; the marker is
+  decorative.
+- **AR2 — Disabled state.** A disabled row is inert.
+- **AR3 — Focus visibility.** Keyboard focus paints only the menu overlay
+  tint, about 1.1:1 against the menu surface in the default themes, with no
+  outline, and nothing under forced colors. The shared row treatment is
+  `component:DropdownMenuItem` OQ2.
+
+## Design relationships
+
+| Anatomy or state | Design requirement         | Representation authority | Hierarchy role | Component contract |
+| ---------------- | -------------------------- | ------------------------ | -------------- | ------------------ |
+| Row              | One full-width toggle row. | Current source           | Prominent      | FR1, FR5           |
+| Marker           | Shows the checked state.   | `component:Indicator`    | Supporting     | FR1, FR5           |
+
+The shared `DropdownMenu.doc.mjs` anatomy and `component:DropdownMenu` theming
+anatomy map the row and checkbox indicator, so this record carries no
+anatomy-theming map.
+
+## Family and system relationships
+
+- `component:DropdownMenu` owns the keyboard model and close lifecycle.
+- `component:Indicator` owns the checkbox chrome.
+- `architecture:public-component-api` owns root composition and handler order.
+
+## Verification map
+
+| Contract  | Verification                                                                                                                                                                                                                                                                                                                                                                        | Representative states                  | Mutation or failure expectation                                                                                                                       | Audit section                                  |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| FR1, AR1  | `DropdownMenuSelectable.test.tsx` "keeps the checkbox indicator decorative (row is the only announced control)"; "a ref reaches the menuitemcheckbox element"                                                                                                                                                                                                                       | Checked and unchecked                  | An announced marker or a row that is not `menuitemcheckbox` fails.                                                                                    | `audit:DropdownMenuCheckboxItem/semantics`     |
+| FR2, ORD1 | `DropdownMenuSelectable.test.tsx` "calls onChange with the toggled value on click", "composes the caller click handler with the checked-state change", "composes the caller click handler on keyboard activation", "closes after a successful toggle only when requested"; `DropdownMenu.test.tsx` "activates a focused menuitemradio with Enter and a menuitemcheckbox with Space" | Pointer and keyboard; close on and off | A wrong value, a dropped caller `onClick`, or a close without the opt-in fails. Evidence gap: no test asserts the `onChange`, close, `onClick` order. | `audit:DropdownMenuCheckboxItem/behavior`      |
+| FR3, AR2  | `DropdownMenuSelectable.test.tsx` "does not call consumer activation handlers when disabled" and "does not toggle when disabled"                                                                                                                                                                                                                                                    | Disabled                               | A toggle or caller handler while disabled fails. Evidence gap: no test asserts the absent `tabindex`.                                                 | `audit:DropdownMenuCheckboxItem/behavior`      |
+| FR4       | `DropdownMenuSelectable.test.tsx` "composes the caller pointer-move handler with menu hover focus" and "a ref reaches the menuitemcheckbox element"                                                                                                                                                                                                                                 | Ref; pointer move                      | A dropped ref or handler fails. Evidence gap: no test asserts host attributes, `className`, `style`, or `xstyle` on the row.                          | `audit:DropdownMenuCheckboxItem/api`           |
+| FR5       | `DropdownMenuSelectable.test.tsx` "maps a small menu to the small shared checkbox marker"                                                                                                                                                                                                                                                                                           | Small menu                             | A marker that ignores the menu size fails. Evidence gap: no test asserts the `dropdown-menu-item` target on this row.                                 | `audit:DropdownMenuCheckboxItem/theming`       |
+| FR6       | `DropdownMenu.test.tsx` "arrow navigation reaches consumer-rendered menuitemradio and menuitemcheckbox items" and "skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation"                                                                                                                                                                            | Enabled and disabled rows              | A row the arrows miss, or a disabled row they land on, fails.                                                                                         | `audit:DropdownMenuCheckboxItem/accessibility` |
+| AR3, PR1  | Evidence gap: no test asserts the focus paint or the listener bound                                                                                                                                                                                                                                                                                                                 | —                                      | —                                                                                                                                                     | `audit:DropdownMenuCheckboxItem/behavior`      |
+
+## Current-state impact
+
+- **Focus visibility (AR3).** Keyboard focus on a checkbox row shows only an
+  overlay tint about 1.1:1 against the menu surface, and no indicator in
+  forced-colors mode; the shared row treatment is `component:DropdownMenuItem`
+  OQ2.
+- **Enter keeps the menu open (FR2).** Enter on a checkbox row toggles it and
+  leaves the menu open by default, against the Menu pattern's Enter that
+  `spec:AST-020` FR15 adopts, with no named exception (OQ1).
+
+## Decision log
+
+No component-local decision.
+
+## Open questions
+
+- **OQ1 — Does a checkbox row keep the menu open on Enter as a named
+  exception to the Menu pattern, or close like other rows?** (`human-api`)
+  Keeping it open lets a person toggle several options in one visit; closing
+  matches the pattern's Enter and the other row types.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or parent contracts. It links to their owners.

package/src/DropdownMenu/DropdownMenuDivider.spec.md

@@ -3,11 +3,11 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:DropdownMenuDivider
-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, testing]
 verified_by:
@@ -16,7 +16,6 @@ verified_by:
     packages/core/src/ContextMenu/ContextMenu.test.tsx,
     packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
-    apps/storybook/stories/DropdownMenuDivider.stories.tsx,
     scripts/check-knowledge.mjs,
   ]
 modules: []
@@ -29,7 +28,7 @@ architecture:
     architecture:component-test-sufficiency,
   ]
 contributing: []
-system_specs: [spec:AST-020, spec:AST-029]
+system_specs: [spec:AST-020]
 ---
 
 # DropdownMenuDivider component contract
@@ -42,9 +41,9 @@ system_specs: [spec:AST-020, spec:AST-029]
 | Behavior                | One unlabelled horizontal separator divides pointer-menu rows and stays out of arrow-key order; data and compound pointer modes render the same component.                                                                         |
 | End-user impact         | Pointer-menu sections remain visually separated without adding a focus stop or changing row operation.                                                                                                                             |
 | Builder impact          | No new caller choice. Host attributes, handlers, and styling inputs continue to compose on the separator.                                                                                                                          |
-| Compatibility/readiness | Patch-compatible observational contract. Runtime behavior, exports, defaults, and target names remain unchanged; authority stays `draft` until exact-head owner approval.                                                          |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change.                                                                                                                                                                          |
 | Review checks           | Reject a focusable separator, changed role/orientation, pointer data/compound divergence, dropped root inputs, or a target moved off the visible separator.                                                                        |
-| Governing rules         | `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV6`; WCAG 2.2 SC 1.3.1 and 4.1.2 through `spec:AST-020/FR1`.                                                                    |
+| Governing rules         | `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV6`; `spec:AST-020`.                                                                                                            |
 
 This table is a review projection; the body below is authoritative.
 
@@ -63,7 +62,8 @@ Consumer syntax and examples belong in `DropdownMenuDivider.doc.mjs`.
 ## Compatibility and migration
 
 - Released default preserved: yes — one horizontal, unlabelled separator.
-- Compatibility class: observational patch; no behavior or public surface changes.
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change.
 - Controlled/uncontrolled behavior: not applicable.
 - Migration decision: none.
 
@@ -98,16 +98,13 @@ 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.
-
-| ID  | Candidate invariant                                                                                                                                                                | Basis                                                            | Draft review state |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------ |
-| FR1 | The component MUST render one unlabelled horizontal separator with pointer-menu-specific block spacing.                                                                            | Released source/docs and focused tests                           | verify             |
-| FR2 | The root MUST expose `role="separator"` and `aria-orientation="horizontal"`, remain outside menu-item collection and arrow-key order, and never become focusable.                  | WCAG 2.2 SC 1.3.1 and 4.1.2; focused tests                       | verify             |
-| FR3 | In pointer-menu presentation, `{type: "divider"}` in the data API and the compound divider component or alias MUST render the same component DOM, spacing, semantics, and targets. | Released docs/source; data/compound parity test                  | verify             |
-| FR4 | The visible root MUST carry both the delegated `divider` target and the menu-specific `dropdown-menu-divider` target; menu spacing applies before caller `xstyle`.                 | `architecture:component-theming-surface/INV3–INV6`; source/tests | verify             |
-| FR5 | Accepted ref, DOM/data/ARIA, class, style, events, and `xstyle` MUST reach or compose on the separator root without replacing component-owned role or orientation.                 | `architecture:public-component-api/INV5–INV8`                    | verify             |
+| ID  | Invariant                                                                                                                                                                     | Basis                                                              |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| FR1 | The component renders one unlabelled horizontal separator with pointer-menu-specific block spacing.                                                                           | Released source/docs and focused tests                             |
+| FR2 | The root exposes `role="separator"` and `aria-orientation="horizontal"`, stays outside menu-item collection and arrow-key order, and is never focusable.                      | `spec:AST-020`; current tests                                      |
+| FR3 | In pointer-menu presentation, `{type: "divider"}` in the data API and the compound divider component or alias render the same component DOM, spacing, semantics, and targets. | Released docs/source; data/compound parity test                    |
+| FR4 | The visible root carries both the delegated `divider` target and the menu-specific `dropdown-menu-divider` target; menu spacing applies before caller `xstyle`.               | `architecture:component-theming-surface`; current source and tests |
+| FR5 | Accepted ref, DOM/data/ARIA, class, style, events, and `xstyle` reach or compose on the separator root without replacing component-owned role or orientation.                 | `architecture:public-component-api` INV5–INV8; current tests       |
 
 ### Allowed variation
 
@@ -151,7 +148,7 @@ intentional decision.
 | ---------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------- | ------------------ |
 | Menu separator   | Visually separates adjacent menu row groups without competing with row content. | Current source and delegated Divider tokens; no component-local visual decision added | supporting     | FR1–FR4            |
 
-No component-local visual decision is settled by this draft.
+No component-local visual decision is recorded.
 
 ## Family and system relationships
 
@@ -164,22 +161,20 @@ No component-local visual decision is settled by this draft.
   props aliases; their pointer presentations retain the same component contract.
 - Touch and bottom-sheet data dividers bypass this component and delegate directly
   to Divider under the parent menu contract.
-- Divider provides the base separator implementation; its draft record is
-  observational context, not authority for this contract.
-- `spec:AST-029` keeps this observational draft separate from the audit receipt.
+- Divider provides the base separator implementation.
 
 ## Verification map
 
-| Contract         | Verification                                                                                            | Representative states                                         | Mutation or failure expectation                                                                                     | Audit section                           |
-| ---------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| FR1–FR3, AR1–AR2 | `DropdownMenu.test.tsx`; ContextMenu and Breadcrumbs alias tests; dedicated Storybook state; scoped axe | pointer data/compound, aliases, open menu, keyboard traversal | Pointer DOM modes drift, an alias disappears, the role/orientation changes, or the separator enters arrow-key order | `audit:DropdownMenuDivider/§1,§3,§4,§6` |
-| FR4              | Focused root-composition test; exact-head Neutral/Butter browser frames                                 | light/dark themes; menu and delegated targets                 | A target leaves the visible root or caller `xstyle` stops composing after menu spacing                              | `audit:DropdownMenuDivider/§2,§5`       |
-| FR5              | Focused root-composition test; lint and typecheck                                                       | ref, host attributes, class/style/xstyle/events               | An accepted input is dropped or owned semantics are overwritten                                                     | `audit:DropdownMenuDivider/§3`          |
-| PR1              | Source review                                                                                           | every state                                                   | A lifecycle mechanism appears without a resource contract                                                           | `audit:DropdownMenuDivider/§7`          |
+| Contract           | Verification                                                                                                                                                                                                                                                                                                                                                                                                     | Representative states                                     | Mutation or failure expectation                                                                                                                                                                                          | Audit section                         |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
+| FR1, FR2, AR1, AR2 | `DropdownMenu.test.tsx` divider and parity cases ("renders dividers between items", "renders an identical divider from either mode", "skips a compound divider in the arrow-key order", "forwards host attributes to a compound divider while keeping its role"); `ContextMenu.test.tsx` divider cases; `Breadcrumbs.test.tsx` "renders the separator and props types through the BreadcrumbMenuDivider aliases" | Data and compound pointer menus; aliases; arrow traversal | A missing separator, a changed role, a separator in the arrow-key order, or a lost alias fails. Evidence gap: no test asserts `aria-orientation` or the menu block spacing.                                              | `audit:DropdownMenuDivider/semantics` |
+| FR3                | `DropdownMenu.test.tsx` "renders an identical divider from either mode"                                                                                                                                                                                                                                                                                                                                          | Data and compound                                         | Different DOM between the modes fails.                                                                                                                                                                                   | `audit:DropdownMenuDivider/behavior`  |
+| FR4, FR5           | `DropdownMenu.test.tsx` "composes the complete public root surface on the separator" and the parity case's `dropdown-menu-divider` class assertion; `themingTargets.test.ts`                                                                                                                                                                                                                                     | Ref, class, style, xstyle, handler                        | A dropped ref, class, style, `xstyle`, or handler, or a missing `dropdown-menu-divider` target, fails. Evidence gap: no test asserts the delegated `divider` target or that menu spacing applies before caller `xstyle`. | `audit:DropdownMenuDivider/api`       |
+| PR1                | Evidence gap: no test asserts the absence of lifecycle resources                                                                                                                                                                                                                                                                                                                                                 | —                                                         | —                                                                                                                                                                                                                        | `audit:DropdownMenuDivider/behavior`  |
 
 ## Decision log
 
-None. This draft records current facts and introduces no product decision.
+No component-local decision.
 
 ## Open questions
 
@@ -188,5 +183,4 @@ None.
 ## Content boundary
 
 This file does not duplicate consumer prop tables/examples, current audit scores,
-screenshot matrices, implementation steps, or system rules. The audit pull request
-owns the closed run evidence required by `spec:AST-029/FR5`.
+screenshot matrices, implementation steps, or system rules. It links to their owners.

package/src/DropdownMenu/DropdownMenuGroup.spec.md

@@ -0,0 +1,145 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:DropdownMenuGroup
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-31
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility, theming]
+verified_by: [packages/core/src/DropdownMenu/DropdownMenu.test.tsx]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:public-component-api, architecture:component-theming-surface]
+contributing: []
+system_specs: [spec:AST-020]
+---
+
+# DropdownMenuGroup component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | A compound-mode group of rows with an optional `title`, `children`, root inputs, and a ref.                                                                                                |
+| Behavior                | Renders one `role="group"` named by its visible heading; the heading is plain text that roving focus and typeahead skip. An untitled group is an unnamed group unless the caller names it. |
+| End-user impact         | Screen-reader users hear a titled cluster of rows as one named group, as sighted users see it; arrow keys move across group boundaries as if the rows were flat.                           |
+| Builder impact          | Builders title compound rows with the same heading look as a data-mode section.                                                                                                            |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change.                                                                                                                                  |
+| Review checks           | Reject a heading that becomes a menu item or a focus stop, a titled group not named by its heading, or a lost section-heading target.                                                      |
+| Governing rules         | `component:DropdownMenu/DEC-6`; `architecture:public-component-api`; `architecture:component-theming-surface`.                                                                             |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+DropdownMenuGroup gives compound-mode menus the titled grouping that data-mode
+`{type: 'section'}` entries already have (`component:DropdownMenu/DEC-6`).
+
+## Compatibility and migration
+
+- Released default preserved: yes.
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One `role="group"` root, its name from the heading, and the heading itself
+  with the `dropdown-menu-section-heading` target.
+- Root composition of ref, host attributes, and handlers.
+
+**Does not own / non-goals**
+
+- Roving focus and typeahead — owned by `component:DropdownMenu`.
+- The rows inside — owned by each row component.
+- Focusable content inside the heading: arrow keys cannot reach it.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning                                 | Availability  | Default | Owner     | Stability | Invalid-value behavior                            |
+| ------- | ----------------------- | --------------------------------------- | ------------- | ------- | --------- | --------- | ------------------------------------------------- |
+| Title   | absent; any React node  | A visible heading that names the group. | Compound mode | absent  | component | stable    | Absent renders no heading and no name of its own. |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                    | Basis                                              |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| FR1 | With a `title`, the group is one `role="group"` whose `aria-labelledby` names its visible heading; the heading carries `dropdown-menu-section-heading`, is plain text rather than a menu item, and is skipped by roving focus and typeahead. | DEC-6 of `component:DropdownMenu`; current tests   |
+| FR2 | Without a `title`, the group is an unnamed `role="group"`, or takes the name a caller supplies.                                                                                                                                              | Current tests                                      |
+| FR3 | Arrow keys step across a group boundary as if the rows were flat; a focusable node inside the heading is not reachable by them.                                                                                                              | Current tests                                      |
+| FR4 | A ref and host attributes and handlers reach the group element while it keeps its role and heading name.                                                                                                                                     | `architecture:public-component-api`; current tests |
+
+### Allowed variation
+
+- **AV1 — Heading content.** The title may be any React node.
+
+### Representative states
+
+| State    | Required invariant               | Allowed variation |
+| -------- | -------------------------------- | ----------------- |
+| Titled   | Named by its heading.            | Title content.    |
+| Untitled | Unnamed, or named by the caller. | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Name.** Title heading → caller name → none.
+
+### Performance and resources
+
+- **PR1 — Render only.** The group owns no state, effect, listener, or
+  observer.
+
+## Accessibility contract
+
+- **AR1 — Named group.** A titled group is announced with its heading's text;
+  the heading is not a menu item.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                         | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Heading          | Labels a cluster of rows like a data-mode section heading. | `component:DropdownMenu` | Supporting     | FR1                |
+
+`component:DropdownMenu` maps the `dropdown-menu-section-heading` target in its
+theming anatomy, so this record carries no anatomy-theming map.
+
+## Family and system relationships
+
+- `component:DropdownMenu` owns the keyboard model and the section-heading
+  target mapping.
+- `architecture:public-component-api` owns root composition.
+
+## Verification map
+
+| Contract       | Verification                                                                                                                                                                                                                                               | Representative states                    | Mutation or failure expectation                                                                                       | Audit section                           |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| FR1, AR1, ORD1 | `DropdownMenu.test.tsx` DropdownMenuGroup cases ("renders a role=\"group\" named by its heading", "renders the heading with the data-mode theme class", "the heading is not a menuitem and roving focus skips it", "typeahead never lands on the heading") | Titled group                             | A group not named by its heading, a missing heading target, or a heading that takes focus or a typeahead match fails. | `audit:DropdownMenuGroup/semantics`     |
+| FR2            | `DropdownMenu.test.tsx` "an untitled group is an unnamed role=\"group\"" and "an untitled group takes a caller-supplied accessible name"                                                                                                                   | Untitled, with and without a caller name | A name invented for an untitled group, or a dropped caller name, fails.                                               | `audit:DropdownMenuGroup/semantics`     |
+| FR3            | `DropdownMenu.test.tsx` "arrow navigation steps across a group boundary as if the rows were flat" and "a focusable node in the heading is not reachable by the arrow keys"                                                                                 | Two groups; focusable heading content    | A stop at the boundary or a focusable heading node reached by arrows fails.                                           | `audit:DropdownMenuGroup/accessibility` |
+| FR4            | `DropdownMenu.test.tsx` "forwards a ref to the group element" and "forwards host attributes to the group while keeping its role and heading name"                                                                                                          | Ref; host attributes                     | A dropped ref or attribute, or a replaced role or name, fails.                                                        | `audit:DropdownMenuGroup/api`           |
+| PR1            | Evidence gap: no test asserts the absence of lifecycle resources                                                                                                                                                                                           | —                                        | —                                                                                                                     | `audit:DropdownMenuGroup/behavior`      |
+
+## Decision log
+
+No component-local decision; `component:DropdownMenu/DEC-6` decides the
+component.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or parent contracts. It links to their owners.

package/src/DropdownMenu/DropdownMenuGroup.tsx

@@ -35,6 +35,7 @@ import {
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {isRenderable} from '../utils/isRenderable';
 
 const styles = stylex.create({
   heading: {
@@ -98,7 +99,7 @@ export function DropdownMenuGroup({
   ...rest
 }: DropdownMenuGroupProps) {
   const headingId = useId();
-  const hasTitle = title != null && title !== '' && title !== false;
+  const hasTitle = isRenderable(title);
 
   return (
     <div