@astryxdesign/core 0.5.1 → 0.5.2-canary.00477a5

package/src/ComplexSelector/ComplexSelector.spec.md

@@ -0,0 +1,189 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:ComplexSelector
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/ComplexSelector/ComplexSelector.test.tsx,
+    packages/core/src/Field/Field.test.tsx,
+    packages/core/src/Icon/Icon.test.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:layer-runtime]
+contributing: []
+system_specs: []
+---
+
+# ComplexSelector component contract
+
+## Intent
+
+ComplexSelector renders a field-owned shell, an owned trigger, and a dialog
+popup for caller-provided rich selection content. 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 trigger and its current `complex-selector` target.
+- The trailing indicator icon and its current
+  `complex-selector-indicator-icon` target.
+- The painted popup surface and its current `complex-selector-popup` target.
+
+**Does not own / non-goals**
+
+- Field-shell presentation — rendered by Field and themed through Field's
+  current `field` target.
+- General Icon presentation — rendered by Icon for semantic icon names and icon
+  component types and themed through Icon's current `icon` target.
+- Arbitrary ReactNode content supplied through `startIcon` — rendered directly
+  and owned by the product callsite.
+- The selector-specific structure supplied through `children` — owned by the
+  product callsite.
+- Shared layer lifecycle, positioning, and dismissal behavior.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `ComplexSelector.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                       | Basis                           | Draft review state                                 |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current render contains a Field, Trigger, Indicator icon, and mounted Popup; one optional start slot may contain either an Icon-rendered start icon or caller-rendered start content. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Trigger, Indicator icon, and Popup carry `complex-selector`, `complex-selector-indicator-icon`, and `complex-selector-popup`, respectively.                                               | Current source, docs, and tests | Verified current behavior; no target change        |
+| FR3 | Field delegates to Field's `field` target, and a semantic name or icon component in the start slot delegates to Icon's `icon` target.                                                     | Current source and owner tests  | Verified current behavior; no target change        |
+| FR4 | Arbitrary ReactNode start content renders directly and carries no ComplexSelector-owned target.                                                                                           | Current source                  | Verified current behavior; no target change        |
+
+### Allowed variation
+
+- Caller-provided popup content may vary without becoming a new
+  ComplexSelector-owned anatomy part or target.
+- The optional start slot has two factual branches: semantic names and icon
+  component types render through Icon, while arbitrary ReactNode content renders
+  directly under caller ownership.
+
+### Representative states
+
+- Input and ghost variants use the same six-part anatomy and current targets.
+- The start slot is absent when `startIcon` is omitted. When present, exactly
+  one of Icon-rendered start icon or Caller-rendered start content applies.
+- The Popup remains mounted in both states: it is hidden while closed and shown
+  while open. The Indicator icon remains present and reflects collapsed or
+  expanded state on its current target.
+
+### Transformation and precedence order
+
+- No new value, open-state, positioning, or style precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend ComplexSelector's existing field, trigger,
+dialog, focus, or keyboard behavior.
+
+## Design relationships
+
+| Anatomy or state              | Design requirement                                                               | Representation authority       | Hierarchy role    | Component contract |
+| ----------------------------- | -------------------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Field                         | Provides the field shell around the owned trigger.                               | Field component                | Supporting        | FR1, FR3           |
+| Trigger                       | Displays the current value or placeholder and opens the popup.                   | Current source and public docs | Prominent         | FR1, FR2           |
+| Icon-rendered start icon      | Optionally presents a semantic or component icon through Icon.                   | Icon component                 | Supporting        | FR1, FR3           |
+| Caller-rendered start content | Optionally presents arbitrary React content directly in the start slot.          | Caller-supplied content        | Context-dependent | FR1, FR4           |
+| Indicator icon                | Presents the trailing disclosure glyph and reflects collapsed or expanded state. | Current source and public docs | Supporting        | FR1, FR2           |
+| Popup                         | Keeps the dialog surface mounted, hidden while closed and painted while open.    | Current source and public docs | Prominent         | FR1, FR2           |
+
+The Field and Icon delegations preserve their existing owners. Arbitrary
+ReactNode start content remains caller-owned and receives no local target. The
+local Indicator icon target remains distinct because it carries the selector's
+expanded/collapsed state and rotation on the glyph itself. Caller-provided popup
+content remains outside the owned anatomy inventory.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Field": {"delegatesTo": {"owner": "component:Field", "target": "field"}},
+  "Trigger": {"target": "complex-selector"},
+  "Icon-rendered start icon": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Caller-rendered start content": {
+    "none": {
+      "reason": "intentional: Arbitrary ReactNode content is caller-owned and receives no ComplexSelector target."
+    }
+  },
+  "Indicator icon": {"target": "complex-selector-indicator-icon"},
+  "Popup": {"target": "complex-selector-popup"}
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, local
+  target mapping, and delegation rules.
+- `architecture:layer-runtime` owns the current `usePopover` host, positioning,
+  native light-dismiss, and visibility reconciliation used by the Popup.
+- `family:overlay-dismissal` owns shared Escape and platform-close ordering;
+  ComplexSelector participates through its composed Popover owner.
+- Field and Icon retain ownership of their delegated targets and presentation.
+
+## Verification map
+
+| Contract            | Verification                                                               | Representative states                            | Mutation or failure expectation                                                               | Audit section                   |
+| ------------------- | -------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1                 | `ComplexSelector.test.tsx` render, ghost-trigger, and popup suites         | Default closed, ghost start branches, open Popup | Removing a documented part fails existing role, content, or structure assertions.             | `audit:ComplexSelector/anatomy` |
+| FR2                 | Component target suites, source inspection, and theming target inventories | Closed/open Popup; expanded Indicator icon       | Removing or renaming a current local target fails component assertions or target inventories. | `audit:ComplexSelector/theming` |
+| FR3, FR4            | Icon owner tests and `renderIconSlot` source inspection                    | Semantic/component icon; arbitrary ReactNode     | A branch gains the wrong owner, loses its target, or receives an invented local target.       | `audit:ComplexSelector/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                              | Canonical anatomy and current local targets      | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.    | `audit:ComplexSelector/theming` |
+
+Current component tests directly assert the Trigger and Popup targets. Source
+inspection confirms that non-lazy `useLayer` keeps the Popup mounted while
+closed. The Indicator icon target is covered by source inspection and shared
+target inventories rather than a dedicated component assertion. `renderIconSlot`
+and Icon owner tests distinguish the Icon-rendered branch from arbitrary
+caller-owned ReactNode content.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, theming, or layer-system decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, caller-provided
+popup structure, implementation steps, or shared layer and theming rules. It
+links to their owners.

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -32,7 +32,7 @@ export const docs = {
     {
       name: 'items',
       type: 'ContextMenuOption[]',
-      description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?}` (variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
+      description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?, items?}` (nested `items` open a flyout in popover presentation and drill into a new view in bottom-sheet presentation; variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
       required: true,
     },
     {
@@ -63,6 +63,12 @@ export const docs = {
       type: '(isOpen: boolean) => void',
       description: 'Callback fired when the menu opens or closes.',
     },
+    {
+      name: 'presentation',
+      type: "'popover' | 'bottom-sheet' | 'adaptive'",
+      description: 'Presentation policy. `popover` opens at the pointer position, `bottom-sheet` always uses an action sheet, and `adaptive` uses the BottomSheet at 768px and below when the primary pointer is coarse.',
+      default: "'popover'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -78,7 +84,9 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Keep menu items concise and action-oriented; users expect quick access to contextual actions.' },
       { guidance: true, description: 'Use sections and dividers to group related actions when the menu has many items.' },
+      { guidance: true, description: 'Use `presentation="adaptive"` when right-click should remain cursor-positioned on desktop while long-press opens a reachable BottomSheet on compact touch devices.' },
       { guidance: true, description: 'Ensure all context menu actions are also accessible via other UI elements for keyboard-only users.' },
+      { guidance: true, description: 'Keep a visible MoreMenu or equivalent trigger for important mobile actions; long-press must not be the only route.' },
       { guidance: false, description: 'Use a ContextMenu as the only way to access important actions; not all users know to right-click.' },
       { guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },
     ],
@@ -107,7 +115,9 @@ export const docsZh = {
     bestPractices: [
       { guidance: true, description: '保持菜单项简洁和面向操作。' },
       { guidance: true, description: '有很多项时使用分组和分隔线。' },
+      { guidance: true, description: '在桌面端需要光标定位、紧凑触控设备上需要 BottomSheet 时，使用 `presentation="adaptive"`。' },
       { guidance: true, description: '确保所有上下文菜单操作也可通过其他 UI 元素访问。' },
+      { guidance: true, description: '重要的移动端操作还应提供可见的 MoreMenu 或同等入口，不要只依赖长按。' },
       { guidance: false, description: '将上下文菜单作为访问重要操作的唯一方式。' },
       { guidance: false, description: '在单个菜单中放置超过 10-12 个项而不分组。' },
     ],
@@ -122,7 +132,9 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Keep items concise and action-oriented.' },
       { guidance: true, description: 'Group related actions with sections and dividers.' },
+      { guidance: true, description: 'Use adaptive presentation for cursor popover on desktop and BottomSheet on compact touch.' },
       { guidance: true, description: 'Ensure actions are also accessible via other UI elements.' },
+      { guidance: true, description: 'Keep a visible mobile entry point for important actions.' },
       { guidance: false, description: 'Use as the only way to access important actions.' },
       { guidance: false, description: 'Place more than 10–12 items without grouping.' },
     ],

package/src/ContextMenu/ContextMenu.test.tsx

@@ -9,8 +9,9 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {readFileSync} from 'node:fs';
 import {ContextMenu} from './ContextMenu';
 import {
   ContextMenuItem,
@@ -23,6 +24,30 @@ import {DropdownMenuItem} from '../DropdownMenu/DropdownMenuItem';
 import {Divider} from '../Divider';
 
 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});
@@ -123,6 +148,100 @@ describe('ContextMenu', () => {
     expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
   });
 
+  it('opens the real menu content in a BottomSheet when requested', async () => {
+    render(
+      <ContextMenu
+        presentation="bottom-sheet"
+        label="Row actions"
+        items={[{label: 'Edit'}]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    await waitFor(() =>
+      expect(HTMLDialogElement.prototype.showModal).toHaveBeenCalledOnce(),
+    );
+    const dialog = screen.getByRole('dialog', {name: 'Row actions'});
+    const actionList = dialog.querySelector('[data-autofocus]');
+    expect(actionList).not.toBeNull();
+    await waitFor(() => expect(actionList).toHaveFocus());
+    expect(screen.getByRole('button', {name: 'Edit'})).not.toHaveFocus();
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+  });
+
+  it('drills into nested data items inside the BottomSheet', async () => {
+    const user = userEvent.setup();
+    const onMove = vi.fn();
+
+    render(
+      <ContextMenu
+        presentation="bottom-sheet"
+        label="Row actions"
+        items={[
+          {
+            label: 'Move to project',
+            items: [{label: 'Apollo launch', onClick: onMove}],
+          },
+        ]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    await user.click(screen.getByRole('button', {name: 'Move to project'}));
+
+    const submenuHeading = screen.getByRole('heading', {
+      name: 'Move to project',
+    });
+    expect(submenuHeading).toBeInTheDocument();
+    await waitFor(() => expect(submenuHeading).toHaveFocus());
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+
+    await user.click(screen.getByRole('button', {name: 'Apollo launch'}));
+    expect(onMove).toHaveBeenCalledOnce();
+    await waitFor(() =>
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument(),
+    );
+  });
+
+  it('keeps only the top content padding in a menu BottomSheet', () => {
+    const source = readFileSync(
+      'packages/core/src/DropdownMenu/MenuBottomSheet.tsx',
+      'utf8',
+    );
+
+    expect(source).toContain('paddingBlockStart={4}');
+    expect(source).toContain('paddingBlockEnd={0}');
+  });
+
+  it('uses the BottomSheet for adaptive presentation on compact touch', async () => {
+    vi.stubGlobal(
+      'matchMedia',
+      vi.fn().mockImplementation((query: string) => ({
+        matches: query === '(max-width: 768px) and (pointer: coarse)',
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      })),
+    );
+    render(
+      <ContextMenu presentation="adaptive" items={[{label: 'Edit'}]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    await waitFor(() =>
+      expect(HTMLDialogElement.prototype.showModal).toHaveBeenCalledOnce(),
+    );
+    expect(HTMLElement.prototype.showPopover).not.toHaveBeenCalled();
+  });
+
   it('closes on Escape even when opened without auto-focus', () => {
     render(
       <ContextMenu items={[{label: 'Item 1'}]}>
@@ -273,6 +392,17 @@ describe('ContextMenu', () => {
     }
   });
 
+  it('suppresses native text selection on the long-press trigger', () => {
+    const source = readFileSync(
+      'packages/core/src/ContextMenu/ContextMenu.tsx',
+      'utf8',
+    );
+
+    expect(source).toMatch(
+      /trigger:[\s\S]*?WebkitTouchCallout: 'none',[\s\S]*?WebkitUserSelect: 'none',[\s\S]*?userSelect: 'none'/,
+    );
+  });
+
   it('cancels the long-press when the finger moves past the threshold', () => {
     vi.useFakeTimers();
     try {