@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/DropdownMenu/DropdownMenuCheckboxItem.spec.md

@@ -1,192 +0,0 @@
----
-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

@@ -1,186 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:DropdownMenuDivider
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-owners: [cixzhang]
-review_triggers: [public-api, behavior, theming, accessibility, testing]
-verified_by:
-  [
-    packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
-    packages/core/src/ContextMenu/ContextMenu.test.tsx,
-    packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:component-test-sufficiency,
-  ]
-contributing: []
-system_specs: [spec:AST-020]
----
-
-# DropdownMenuDivider component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                           |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `DropdownMenuDivider` / `DropdownMenuDividerProps`, plus the `ContextMenuDivider` and `BreadcrumbMenuDivider` aliases and their props; `BaseProps<HTMLDivElement>` minus caller-owned `role` and `aria-orientation`; a root `ref`. |
-| 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 | 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`; `spec:AST-020`.                                                                                                            |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-DropdownMenuDivider provides the visual and programmatic boundary between groups
-of rows in pointer-menu presentations. It ships directly under the DropdownMenu
-name and through ContextMenu and Breadcrumbs aliases. It owns the separator
-semantics, menu spacing, root input composition, and the
-`dropdown-menu-divider` theme target. The surrounding DropdownMenu, ContextMenu,
-or BreadcrumbItem owns menu lifecycle and row navigation; Divider supplies the
-base rule geometry and paint.
-
-Consumer syntax and examples belong in `DropdownMenuDivider.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: yes — one horizontal, unlabelled separator.
-- 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 horizontal separator root and its public ref, DOM/data/ARIA, class, style,
-  event, and `xstyle` composition.
-- Menu-specific block-axis spacing.
-- The `dropdown-menu-divider` target on the same visible root.
-- Pointer-menu data/compound rendering parity for the divider row across
-  DropdownMenu, ContextMenu, and breadcrumb menus.
-
-**Does not own / non-goals**
-
-- Menu open state, focus entry, row activation, or arrow-key navigation — owned by
-  DropdownMenu, ContextMenu, BreadcrumbItem, and their shared hooks.
-- Touch and bottom-sheet data dividers — those presentations render Divider
-  directly and are owned by their parent menu surface.
-- Base separator rule geometry and token paint — delegated to Divider.
-- Caller-authored grouping meaning — owned by the product callsite.
-
-## Public concepts
-
-| Concept       | Closed values or states                       | Meaning                                                                        | Availability by variant/orientation/state | Default                | Owner                | Stability | Invalid-value behavior                                                          |
-| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- | ---------------------- | -------------------- | --------- | ------------------------------------------------------------------------------- |
-| Separator row | one horizontal unlabelled separator           | Divides adjacent pointer-menu row groups without becoming a row or focus stop. | Data and compound pointer-menu modes      | present where authored | component            | stable    | Role and orientation are excluded from caller props and remain component-owned. |
-| Root surface  | ref; DOM/data/ARIA; class/style/xstyle/events | Extends the separator root while preserving component semantics.               | Every separator row                       | omitted                | public component API | stable    | Accepted inputs compose; role and orientation remain authoritative.             |
-
-## Behavioral and layout contract
-
-| 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
-
-- **AV1 — Theme paint.** The delegated Divider and menu-specific targets may restyle
-  their owned surface without changing separator semantics or focus behavior.
-- **AV2 — Caller root inputs.** Supported host attributes, handlers, and styling
-  inputs may vary while the owned role and orientation remain fixed.
-
-### Representative states
-
-| State                     | Required invariant                                                   | Allowed variation                                             |
-| ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------- |
-| Pointer data-mode divider | One horizontal separator between data-driven rows.                   | Adjacent row content and active theme may vary.               |
-| Pointer compound divider  | DOM and behavior match the pointer data-mode divider.                | Host attributes and supported styling inputs may be supplied. |
-| Public aliases            | ContextMenuDivider and BreadcrumbMenuDivider render this component.  | The containing menu owns lifecycle and navigation.            |
-| Touch data divider        | Outside this component; the parent surface renders Divider directly. | Touch-menu layout follows the parent contract.                |
-| RTL                       | The horizontal, full-width rule remains direction-neutral.           | Surrounding text and menu alignment may mirror.               |
-| Narrow viewport           | The rule remains inside the menu without horizontal overflow.        | Menu width follows its owner.                                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Root composition.** Apply menu spacing, then caller `xstyle`; combine the
-  menu-specific target class with caller `className`; preserve caller `style` and
-  host props; keep role and orientation component-owned.
-
-### Performance and resources
-
-- **PR1 — No external lifecycle.** DropdownMenuDivider installs no listener,
-  observer, timer, request, state machine, or Effect.
-
-## Accessibility contract
-
-- **AR1 — Separator semantics.** The root exposes a horizontal separator and no
-  interactive role or tab stop.
-- **AR2 — Navigation exclusion.** Menu navigation collects menu-item roles only, so
-  ArrowDown and ArrowUp pass across the separator without focusing it.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                              | Representation authority                                                              | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------- | ------------------ |
-| 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 recorded.
-
-## Family and system relationships
-
-- `architecture:public-component-api` owns exports and root input composition.
-- `architecture:component-theming-surface` owns target placement and composed target
-  ownership.
-- `architecture:component-test-sufficiency` owns proportionate, observable evidence.
-- DropdownMenu exports the implementation directly. ContextMenu and Breadcrumbs
-  re-export it as `ContextMenuDivider` and `BreadcrumbMenuDivider`, with matching
-  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.
-
-## Verification map
-
-| 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
-
-No component-local decision.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit scores,
-screenshot matrices, implementation steps, or system rules. It links to their owners.

package/src/DropdownMenu/DropdownMenuGroup.spec.md

@@ -1,145 +0,0 @@
----
-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.