An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): MoreMenu records its shipped contract as current (#8533)
Cindy Zhangc98456e21f32
diff --git a/packages/core/src/MoreMenu/MoreMenu.spec.md b/packages/core/src/MoreMenu/MoreMenu.spec.mdindex dbfbc7d2b7..9947098871 100644--- a/packages/core/src/MoreMenu/MoreMenu.spec.md+++ b/packages/core/src/MoreMenu/MoreMenu.spec.md@@ -1,18 +1,21 @@---schema_version: 3-template_version: 3+template_version: 7kind: componentid: component:MoreMenu-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-26owners: [cixzhang]review_triggers: [theming]verified_by:[packages/core/src/MoreMenu/MoreMenu.test.tsx,+ packages/core/src/DropdownMenu/__tests__/MenuButton.a11y.test.tsx,+ packages/core/src/DropdownMenu/__tests__/MenuButton.a11y.chromium.spec.ts,+ apps/storybook/stories/MoreMenu.stories.tsx,packages/core/src/DropdownMenu/DropdownMenu.test.tsx,packages/core/src/Button/Button.test.tsx,packages/core/src/Icon/Icon.test.tsx,@@ -30,28 +33,54 @@ architecture:architecture:layer-runtime,]contributing: []-system_specs: []+system_specs: [spec:AST-020]---# MoreMenu component contract+## Contract at a glance++| Area | Contract |+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `MoreMenu` with `items`, `label` (default "More options"), `variant` (`ghost`), `size` (surrounding size context, else `md`), `icon`, `isDisabled`, `placement`, `alignment`, `presentation`, `isMenuOpen`, and `onOpenChange`; target `more-menu`. |+| Behavior | An icon-only overflow Button with a tooltip that opens a DropdownMenu of `items`; MoreMenu forwards open state, placement, alignment, and presentation to DropdownMenu and adds no menu runtime of its own. |+| End-user impact | Users find secondary actions behind one named "More options" button; keyboard users open it as an APG menu button. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps (see Current-state impact). |+| Review checks | Reject moving `more-menu` onto the trigger, a parallel menu runtime, or a trigger that loses its name, `aria-haspopup`, `aria-expanded`, or `aria-controls`. |+| Governing rules | `spec:AST-020` (pattern bindings); `architecture:component-theming-surface`; `architecture:layer-runtime`; `family:overlay-dismissal`. |++This table is a review projection; the body below is authoritative.+## IntentMoreMenu provides a visible icon-only overflow trigger and delegates its action-presentation to DropdownMenu. This draft records current consumer anatomy and-theming ownership without changing runtime behavior, styling, targets, or public-API.+presentation to DropdownMenu. It owns the trigger's defaults, the `more-menu`+target on the composed panel, and what it forwards to DropdownMenu. Consumer+usage lives in `MoreMenu.doc.mjs`.## Compatibility and migration- Released default preserved: `yes`-- Compatibility class: additive documentation only; runtime, DOM, styling,+- Compatibility class: records shipped behavior; runtime, DOM, styling,targets, and public API remain unchanged-- Controlled/uncontrolled behavior: unchanged+- Controlled/uncontrolled behavior: `isMenuOpen` and `onOpenChange` pass to+ DropdownMenu unchanged- Migration decision: noneConsumer migration instructions belong in consumer docs and release notes.+## Current-state impact++- **The bottom-sheet trigger drops the ref.** With `presentation="bottom-sheet"`,+ or `presentation="adaptive"` on a compact touch screen, DropdownMenu replaces the `ref` MoreMenu passes to the trigger, so a caller's+ ref stays empty. `architecture:public-component-api` INV8 has the ref reach+ the element the contract promises.+- **The arrow-key opening rows are advisory.** The shared menu-button binding+ runs AR1's ArrowDown and ArrowUp opening rows as advisory, so a keyboard open+ that misses the first or last row does not fail either binding lane.+ `spec:AST-020` FR9 makes an adopted expectation required.+## Ownership boundary**Owns**@@ -66,28 +95,28 @@ Consumer migration instructions belong in consumer docs and release notes.- Default semantic trigger artwork resolution — delegated to the Icon registry;the current artwork renders directly inside Button and does not carry Icon's`icon` target. Arbitrary caller-rendered trigger content remains caller-owned.-- Menu-panel lifecycle and presentation switching — delegated to- `component:DropdownMenu`.+- Menu-panel lifecycle and presentation switching — owned by DropdownMenu and+ uncontracted here.- Anchored action rows, sections, dividers, selectable indicators, and nested- flyouts — delegated to `component:DropdownMenu`.+ flyouts — owned by DropdownMenu and uncontracted here.- BottomSheet action rows and lists — delegated through DropdownMenu to`component:List`; the touch frame remains owned by `component:BottomSheet`.- Shared layer lifecycle or dismissal policy.## Public concepts-No new public concept is introduced. Consumer props and usage remain documented-in `MoreMenu.doc.mjs`; its action data and presentation values remain those of-DropdownMenu.+No component-local concept. Action data and presentation values are+DropdownMenu's; consumer props are documented in `MoreMenu.doc.mjs`.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------- |-| FR1 | Every current render contains one icon-only Trigger button and one DropdownMenu-owned Menu surface. Anchored presentation uses Pointer action rows; BottomSheet presentation uses Touch action rows. The default trigger icon resolves through the Icon registry, while a caller may replace it with arbitrary React content. | Current source, docs, and tests | Verified current behavior; no new behavior decided |-| FR2 | The current `more-menu` target is applied to the composed DropdownMenu panel as an additional class. It is not applied to the Trigger button. | Current source, docs, and tests | Verified current target placement; no target change |-| FR3 | Button owns the Trigger button and the Icon registry owns default semantic trigger artwork resolution. DropdownMenu owns Pointer action rows; List owns Touch action rows rendered through DropdownMenu's BottomSheet path. | Current source and owner docs | Verified current delegation; no ownership change |-| FR4 | MoreMenu forwards the current open state, placement, alignment, and pointer/touch presentation policy to DropdownMenu without adding a parallel menu runtime. | Current source and tests | Verified composition; no behavior change |+| ID | Invariant | Basis |+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |+| FR1 | Every render contains one icon-only Trigger button. The anchored presentation also renders one DropdownMenu-owned Menu surface; the bottom-sheet presentation renders its Menu surface only while the sheet is open. Anchored presentation uses Pointer action rows; BottomSheet presentation uses Touch action rows. The default trigger icon is the active registry's `moreHorizontal` artwork; `icon` replaces it with any React content. | Current source, docs, and tests |+| FR2 | The `more-menu` target is applied to the composed DropdownMenu panel as an additional class, before any caller `className`. It is not applied to the Trigger button. | Current source, docs, and tests |+| FR3 | Button owns the Trigger button and the Icon registry owns default semantic trigger artwork resolution. DropdownMenu owns Pointer action rows; List owns Touch action rows rendered through DropdownMenu's BottomSheet path. | Current source and owner docs |+| FR4 | MoreMenu forwards open state, placement, alignment, presentation, `xstyle`, `style`, and `data-testid` to DropdownMenu without adding a parallel menu runtime, and shows no chevron. Its default position matches DropdownMenu's. | Current source and tests |+| FR5 | The trigger is named by `label` (else the translated `@astryx.moreMenu.label`, "More options"), shows that name as its tooltip, uses `variant` (default `ghost`) and `size` (default from the surrounding size context, else `md`), forwards `ref` to the trigger in the anchored presentation, and honors `isDisabled`: a disabled trigger opens from no key or press. | Current source and tests |### Allowed variation@@ -112,28 +141,25 @@ DropdownMenu.### Transformation and precedence order-- No new icon-resolution, presentation-resolution, open-state, positioning, or- styling precedence rule is introduced.+- **ORD1 — Trigger icon.** `icon`, then the registry's `moreHorizontal`.+- **ORD2 — Size.** `size`, then the surrounding size context, then `md`.### Performance and resources-- No new loading, listener, measurement, or render constraint is introduced.+- No resource rule; MoreMenu adds no listener or measurement of its own.## Accessibility contract-This draft does not change or extend MoreMenu's existing accessible label,-tooltip, icon-only Button semantics, focus behavior, keyboard operation, or-dismissal behavior.--- **AR1 — The anchored trigger is a Menu Button through DropdownMenu.** In the- anchored pointer presentation MoreMenu's icon-only trigger adopts the APG- Menu Button pattern's required parts as `component:DropdownMenu/AR4` records- them — `button` role, its accessible label as the name,- `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`, Enter or Space- opening with focus on the first enabled row — and the same named exception- for ArrowDown and ArrowUp opening. MoreMenu adds nothing of its own to that- contract. In the bottom-sheet presentation the trigger opens a dialog and says- `aria-haspopup="dialog"`, outside this pattern.+- **AR1 — The anchored trigger is a Menu Button.** In the anchored pointer+ presentation MoreMenu's icon-only trigger meets the APG Menu Button pattern's+ required parts: `button` role, its label as the name, `aria-haspopup="menu"`,+ `aria-expanded`, `aria-controls`, and Enter or Space opening with focus on the+ first enabled row. ArrowDown opening on the first and ArrowUp on the last+ enabled row go beyond the pattern's required set and are a named exception+ (`spec:AST-020` FR15), kept because they ship. A pointer open focuses the menu container, and the first+ ArrowDown then moves to the first row. In the bottom-sheet presentation the+ trigger opens a dialog and says `aria-haspopup="dialog"`, outside this+ pattern.## Design relationships@@ -143,7 +169,7 @@ dismissal behavior.| Icon-resolved trigger icon | Draws semantic three-dot artwork from the active Icon registry. | Icon registry | Supporting | FR1, FR3 || Caller-rendered trigger content | Presents arbitrary caller content supplied through the icon override. | Caller-supplied content | Context-dependent | FR1, FR3 || Menu surface | Adds MoreMenu's target to the composed DropdownMenu panel, not the trigger. | Current source and public docs | Prominent | FR1, FR2 |-| Pointer action row | Presents an action or nested flyout trigger in the anchored presentation. | `component:DropdownMenu` | Prominent | FR1, FR3, FR4 |+| Pointer action row | Presents an action or nested flyout trigger in the anchored presentation. | DropdownMenu | Prominent | FR1, FR3, FR4 || Touch action row | Presents an action or drill-in entry through ListItem in the touch presentation. | `component:List` | Prominent | FR1, FR3, FR4 |The Menu surface is the DropdownMenu panel itself. It carries both@@ -193,8 +219,7 @@ presentation.resolution. MoreMenu's default artwork uses that registry but currentlybypasses Icon's painted `icon` target.- `architecture:interaction-modality` owns the shared pointer, touch, keyboard,- and adaptive-presentation boundaries inherited through DropdownMenu; this- draft changes none of them.+ and adaptive-presentation boundaries inherited through DropdownMenu.- `architecture:layer-runtime` owns the current DropdownMenu Popover host, nativelight-dismiss reconciliation, and BottomSheet host distinction. MoreMenu addsno parallel layer runtime.@@ -205,26 +230,36 @@ presentation.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |-| FR1, FR4 | `MoreMenu.test.tsx` render, pointer, bottom-sheet, placement, and controlled suites | Default, custom icon, pointer, touch | Replacing the composition or changing forwarded behavior fails existing render/interaction tests. | `audit:MoreMenu/anatomy` |-| FR2 | MoreMenu target test, source inspection, and theming target inventories | Closed trigger and composed menu panel | Moving `more-menu` onto the trigger or removing it from the panel fails target evidence. | `audit:MoreMenu/theming` |-| FR3 | MoreMenu, DropdownMenu, Button, Icon, and List source/owner tests | Trigger, icon branches, pointer rows, touch rows | A composed part loses its owner target or is documented as a new MoreMenu-owned descendant. | `audit:MoreMenu/theming` |-| AR1 | `MoreMenu.test.tsx` "renders trigger button with default aria-label" and "has aria-haspopup and aria-expanded attributes"; keyboard opening verified through DropdownMenu's AR4 tests; MoreMenu-bound Menu Button accessibility contract (`internal/a11y-spec`) pending | Default and custom-icon triggers; closed/open; Enter, Space, ArrowDown, ArrowUp | The trigger loses its label, `aria-haspopup="menu"`, `aria-expanded` or `aria-controls`, or a keyboard open does not land on the first (ArrowUp: last) enabled row | `audit:MoreMenu/accessibility` |-| Layer relationships | `MoreMenu.test.tsx`, `DropdownMenu.test.tsx`, and current layer/dismissal records | Light dismiss, Escape, pointer, touch | Documentation gives MoreMenu a parallel runtime or misstates the current dismissal owner. | `audit:MoreMenu/behavior` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:MoreMenu/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |+| FR1, FR4 | `MoreMenu.test.tsx` render, pointer, bottom-sheet, and placement suites | Default, custom icon, pointer, touch | Replacing the composition or changing forwarded behavior fails existing render/interaction tests. | `audit:MoreMenu/anatomy` |+| FR2 | MoreMenu target test, source inspection, and theming target inventories | Closed trigger and composed menu panel | Moving `more-menu` onto the trigger or removing it from the panel fails target evidence. | `audit:MoreMenu/theming` |+| FR3 | MoreMenu, DropdownMenu, Button, Icon, and List source/owner tests | Trigger, icon branches, pointer rows, touch rows | A composed part loses its owner target or is documented as a new MoreMenu-owned descendant. | `audit:MoreMenu/theming` |+| FR5 | `MoreMenu.test.tsx` label, custom-label, ref, disabled-keys, and closed-while-disabled tests | Default and custom label; disabled | A lost name, or a disabled trigger that opens, fails. | `audit:MoreMenu/behavior` |+| AR1 | `MoreMenu.test.tsx` label, popup, and pointer-focus tests; the menu-button pattern binding `MenuButton.a11y.test.tsx` and `MenuButton.a11y.chromium.spec.ts`, which render MoreMenu states; `DropdownMenu.test.tsx` ArrowDown and ArrowUp trigger-key tests on the shared Button trigger path | Default and custom-icon triggers; closed/open; Enter, Space, ArrowDown, ArrowUp | The trigger loses its label, `aria-haspopup="menu"`, `aria-expanded` or `aria-controls`, or an Enter or Space open does not land on the first enabled row | `audit:MoreMenu/accessibility` |+| Layer relationships | `MoreMenu.test.tsx`, `DropdownMenu.test.tsx`, and current layer/dismissal records | Light dismiss, Escape, pointer, touch | Documentation gives MoreMenu a parallel runtime or misstates the current dismissal owner. | `audit:MoreMenu/behavior` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:MoreMenu/theming` |++Read from source, with no focused test yet:++- FR1: the registry's `moreHorizontal` as the default trigger icon.+- FR2: `more-menu` coming before a caller `className`, and its absence from the+ Trigger button.+- FR4: forwarding `isMenuOpen`, `onOpenChange`, `xstyle`, and `style`, and the+ absence of a chevron.+- FR5: the tooltip, the `ghost` default, the size from the surrounding size+ context, the `md` default, and the ref reaching the trigger button.+- AR1: `aria-haspopup="dialog"` in the bottom-sheet presentation.## Decision log-None. This draft records current facts and introduces no component-local design,-API, theming, modality, or layer-system decision.+No component-local decision is recorded.## Open questions- **OQ1 — Should the default trigger artwork render through Icon's publictarget?** (`human-api`) The current registry lookup preserves semantic artwork- replacement but leaves the painted glyph outside the `icon` target; this- draft does not change that reachability.+ replacement but leaves the painted glyph outside the `icon` target.## Content boundary