@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e03511b

package/src/MoreMenu/MoreMenu.spec.md

@@ -0,0 +1,221 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:MoreMenu
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/MoreMenu/MoreMenu.test.tsx,
+    packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
+    packages/core/src/Button/Button.test.tsx,
+    packages/core/src/Icon/Icon.test.tsx,
+    packages/core/src/List/List.test.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:icon-resolution-and-component-slots,
+    architecture:interaction-modality,
+    architecture:layer-runtime,
+  ]
+contributing: []
+system_specs: []
+---
+
+# MoreMenu component contract
+
+## Intent
+
+MoreMenu 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.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The overflow-menu composition and its visible icon-only trigger defaults.
+- The Menu surface's current `more-menu` target, which is a second class on the
+  composed DropdownMenu panel.
+
+**Does not own / non-goals**
+
+- Trigger-button presentation — delegated to `component:Button`.
+- 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`.
+- Anchored action rows, sections, dividers, selectable indicators, and nested
+  flyouts — delegated to `component:DropdownMenu`.
+- 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.
+
+## 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            |
+
+### Allowed variation
+
+- **AV1 — Trigger icon.** The default semantic three-dot icon may be replaced by
+  an icon component or arbitrary React content without moving the MoreMenu target
+  onto the trigger.
+- **AV2 — Presentation.** DropdownMenu may resolve the current anchored or
+  BottomSheet presentation while MoreMenu keeps the same trigger and Menu-surface
+  ownership.
+- **AV3 — Interior.** Action rows, sections, dividers, icons, selectable
+  indicators, and nested actions may vary according to DropdownMenu's current
+  data contract.
+
+### Representative states
+
+| State                  | Required invariant                                                                        | Allowed variation                                    |
+| ---------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| Default overflow menu  | Trigger button uses the default Icon-resolved glyph and Menu surface carries `more-menu`. | Button size, variant, placement, and alignment vary. |
+| Arbitrary icon content | Trigger button remains Button-owned while caller content bypasses Icon ownership.         | Caller owns the rendered content.                    |
+| Pointer presentation   | DropdownMenu owns the anchored Menu interior and Pointer action rows.                     | Rows, sections, dividers, and nested flyouts vary.   |
+| Touch presentation     | DropdownMenu owns the BottomSheet-backed Menu interior; List owns Touch action rows.      | Touch rows and drill-in depth vary.                  |
+
+### Transformation and precedence order
+
+- No new icon-resolution, presentation-resolution, open-state, positioning, or
+  styling precedence rule is introduced.
+
+### Performance and resources
+
+- No new loading, listener, measurement, or render constraint is introduced.
+
+## 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.
+
+## Design relationships
+
+| Anatomy or state                | Design requirement                                                               | Representation authority       | Hierarchy role    | Component contract |
+| ------------------------------- | -------------------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Trigger button                  | Provides the visible and discoverable entry point for secondary actions.         | `component:Button`             | Supporting        | FR1, FR3           |
+| 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      |
+| 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
+`astryx-more-menu` and DropdownMenu's own panel target; the local class is not a
+wrapper and does not retarget the trigger. DropdownMenu remains the owner of the
+presentation runtime and anchored interior. Its touch path delegates action rows
+to List rather than extending the pointer-row target into the BottomSheet
+presentation.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Trigger button": {
+    "delegatesTo": {"owner": "component:Button", "target": "button"}
+  },
+  "Icon-resolved trigger icon": {
+    "none": {
+      "reason": "unsettled: The current useIcon artwork renders directly inside Button; whether it should carry Icon's icon target needs an owner decision."
+    }
+  },
+  "Caller-rendered trigger content": {
+    "none": {
+      "reason": "intentional: Arbitrary React icon content is caller-owned and receives no MoreMenu target."
+    }
+  },
+  "Menu surface": {"target": "more-menu"},
+  "Pointer action row": {
+    "delegatesTo": {
+      "owner": "component:DropdownMenu",
+      "target": "dropdown-menu-item"
+    }
+  },
+  "Touch action row": {
+    "delegatesTo": {"owner": "component:List", "target": "list-item"}
+  }
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, the local
+  Menu-surface target, and composition delegation rules.
+- `architecture:icon-resolution-and-component-slots` owns active-theme icon
+  resolution. MoreMenu's default artwork uses that registry but currently
+  bypasses 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.
+- `architecture:layer-runtime` owns the current DropdownMenu Popover host, native
+  light-dismiss reconciliation, and BottomSheet host distinction. MoreMenu adds
+  no parallel layer runtime.
+- `family:overlay-dismissal` owns shared Escape and platform-close ordering and
+  records MoreMenu as a shared owner through its composed DropdownMenu root;
+  BottomSheet presentation retains BottomSheet's recorded local-only adoption
+  gap.
+
+## 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`  |
+| 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`  |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, theming, modality, or layer-system decision.
+
+## Open questions
+
+- **OQ1 — Should the default trigger artwork render through Icon's public
+  target?** (`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.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, DropdownMenu item examples,
+icon-resolution rules, implementation steps, or shared modality, layer,
+dismissal, and theming rules. It links to their owners.

package/src/MoreMenu/MoreMenu.test.tsx

@@ -17,6 +17,30 @@ import {DropdownMenu} from '../DropdownMenu/DropdownMenu';
 
 // Mock showPopover and hidePopover methods since they're not implemented in jsdom
 beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
   HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
     this.setAttribute('popover-open', '');
     const event = new Event('toggle', {bubbles: false});
@@ -85,6 +109,29 @@ describe('MoreMenu', () => {
     expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
   });
 
+  it('keeps the trigger visually pressed while the menu is open', async () => {
+    const user = userEvent.setup();
+    render(<MoreMenu items={defaultItems} />);
+
+    const trigger = screen.getByRole('button', {name: 'More options'});
+    expect(trigger.className).not.toContain('DropdownMenu__styles.triggerOpen');
+
+    await user.click(trigger);
+
+    expect(trigger.className).toContain('DropdownMenu__styles.triggerOpen');
+  });
+
+  it('forwards BottomSheet presentation to DropdownMenu', async () => {
+    const user = userEvent.setup();
+    render(<MoreMenu items={defaultItems} presentation="bottom-sheet" />);
+
+    await user.click(screen.getByRole('button', {name: 'More options'}));
+    await waitFor(() =>
+      expect(HTMLDialogElement.prototype.showModal).toHaveBeenCalledOnce(),
+    );
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+  });
+
   it('calls onClick when item is clicked', async () => {
     const handleEdit = vi.fn();
     const items = [

package/src/MoreMenu/MoreMenu.tsx

@@ -22,7 +22,10 @@ import type {ReactNode} from 'react';
 import {useIcon} from '../Icon';
 import {DropdownMenu} from '../DropdownMenu/DropdownMenu';
 import {useSize} from '../SizeContext/SizeContext';
-import type {DropdownMenuOption} from '../DropdownMenu';
+import type {
+  DropdownMenuOption,
+  DropdownMenuPresentation,
+} from '../DropdownMenu';
 import type {LayerAlignment, LayerPlacement} from '../Layer';
 import type {ButtonVariant, ButtonSize} from '../Button';
 import type {BaseProps} from '../BaseProps';
@@ -87,6 +90,13 @@ export interface MoreMenuProps extends Pick<
    */
   alignment?: LayerAlignment;
 
+  /**
+   * Menu presentation policy. `adaptive` uses a BottomSheet on compact
+   * coarse-pointer viewports and an anchored popover elsewhere.
+   * @default 'popover'
+   */
+  presentation?: DropdownMenuPresentation;
+
   /**
    * Controlled open state for the menu.
    */
@@ -125,6 +135,7 @@ export function MoreMenu({
   isDisabled = false,
   placement,
   alignment,
+  presentation,
   isMenuOpen,
   onOpenChange,
   xstyle,
@@ -151,6 +162,7 @@ export function MoreMenu({
       onOpenChange={onOpenChange}
       placement={placement}
       alignment={alignment}
+      presentation={presentation}
       button={{
         label,
         icon: icon ?? moreIcon,

package/src/MultiSelector/MultiSelector.doc.mjs

@@ -1,5 +1,116 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Field',
+    required: false,
+    description:
+      'Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.',
+  },
+  {
+    name: 'Trigger',
+    required: true,
+    description:
+      'Painted control that displays the current selection or placeholder and opens the selection surface.',
+  },
+  {
+    name: 'Icon-rendered start icon',
+    required: false,
+    description:
+      'Optional leading semantic icon or icon component rendered through Icon.',
+  },
+  {
+    name: 'Caller-rendered start content',
+    required: false,
+    description:
+      'Optional arbitrary React content rendered directly at the start of the trigger.',
+  },
+  {
+    name: 'Trigger clear button',
+    required: false,
+    description:
+      'Shared clear action that removes every selected value when hasClear is enabled.',
+  },
+  {
+    name: 'Status icon',
+    required: false,
+    description:
+      'Status glyph shown in place of the disclosure indicator for attached or tooltip status.',
+  },
+  {
+    name: 'Indicator icon',
+    required: false,
+    description:
+      'Trailing chevron shown when status presentation does not replace it; reflects collapsed or expanded state.',
+  },
+  {
+    name: 'Search row',
+    required: false,
+    description:
+      'Panel header with a borderless search input and optional clear action.',
+  },
+  {
+    name: 'Search icon',
+    required: false,
+    description:
+      'Leading magnifier rendered through Icon inside the search row.',
+  },
+  {
+    name: 'Search clear button',
+    required: false,
+    description:
+      'Shared clear action shown in the search row while a query is present.',
+  },
+  {
+    name: 'Option row',
+    required: false,
+    description:
+      'Selectable row for an option or the optional select-all choice.',
+  },
+  {
+    name: 'Option checkbox indicator',
+    required: false,
+    description:
+      'CheckboxInput indicator that presents each row’s selected, unselected, or indeterminate state.',
+  },
+  {
+    name: 'Option divider',
+    required: false,
+    description:
+      'Divider supplied in the public options data to separate adjacent option groups.',
+  },
+  {
+    name: 'Section heading',
+    required: false,
+    description: 'Visible heading for a labeled group of option rows.',
+  },
+  {
+    name: 'Empty state',
+    required: false,
+    description:
+      'Message shown when the shared panel content has no options or no search matches.',
+  },
+  {
+    name: 'Pointer popup',
+    required: false,
+    description:
+      'Anchored painted surface that hosts the shared panel content for popover presentation.',
+  },
+  {
+    name: 'Touch sheet heading',
+    required: false,
+    description:
+      'Heading above the shared panel content in bottom-sheet presentation.',
+  },
+  {
+    name: 'Touch sheet',
+    required: false,
+    description:
+      'BottomSheet surface that hosts the same panel content for bottom-sheet presentation.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -224,6 +335,13 @@ export const docs = {
             'Which edge of the option row carries the checkbox. end pushes it to the far edge of the row, including on the select-all row.',
           default: "'start'",
         },
+        {
+          name: 'presentation',
+          type: "'popover' | 'bottom-sheet' | 'adaptive'",
+          description:
+            'How the option list is presented. adaptive uses a bottom sheet on compact touch screens and an anchored popover otherwise.',
+          default: "'popover'",
+        },
         {
           name: 'width',
           type: 'SizeValue',
@@ -257,6 +375,7 @@ export const docs = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.',
     bestPractices: [
@@ -290,6 +409,11 @@ export const docs = {
         description:
           'Use variant="ghost" when a multi-selector sits in a toolbar with ghost buttons. If validation status is needed there, prefer statusVariant="tooltip" so the toolbar height stays compact.',
       },
+      {
+        guidance: true,
+        description:
+          'Use presentation="adaptive" when the multi-selector should become a bottom sheet on compact touch screens.',
+      },
       {
         guidance: false,
         description: 'Use for single-value selection; use Selector instead.',
@@ -349,6 +473,8 @@ export const docsZh = {
           '状态消息的放置方式：attached 直接叠加在输入框下方；detached 作为独立元素浮于下方并留有间距。',
         renderOption:
           '每个可选选项的自定义渲染函数。不会用于分隔线、分组或全选行。',
+        presentation:
+          '选项列表的呈现方式：锚定弹出框、底部抽屉，或根据紧凑触控屏自适应。',
         xstyle: '布局自定义的 StyleX 样式，必须是 stylex.create() 值。',
       },
     },
@@ -487,6 +613,8 @@ export const docsDense = {
           'status message placement; ghost detaches attached by default; use tooltip for compact toolbars.',
         renderOption:
           'custom render fn per selectable option; not dividers/sections/select-all',
+        presentation:
+          'popover, bottom-sheet, or compact-touch adaptive presentation',
         xstyle: 'StyleX layout styles; stylex.create() only',
       },
     },