@astryxdesign/core 0.5.2-canary.1e29ea2 → 0.5.2-canary.1f005bf

package/src/CheckboxList/CheckboxList.spec.md

@@ -0,0 +1,214 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:CheckboxList
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/CheckboxList/CheckboxList.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# CheckboxList component contract
+
+## Intent
+
+CheckboxList presents a labeled group of checkbox options. This draft records
+its current consumer anatomy and the theming ownership of parts rendered by
+CheckboxList, List, CheckboxInput, Field, FieldStatus, and Spinner. It changes no
+runtime behavior 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 checkbox-group composition and its existing `checkbox-list` target.
+- Collection state shared with CheckboxListItem.
+
+**Does not own / non-goals**
+
+- List and option-row presentation — owned by `component:List`; its
+  `list-item` target reaches only the row root.
+- Standard option-label and option-description wrappers — rendered as separate,
+  untargeted spans by Item rather than Text; rich label content and end content
+  remain caller-owned.
+- The checkbox indicator — owned by `component:CheckboxInput`.
+- Group-label and validation-message presentation — owned by `component:Field`
+  and `component:FieldStatus`.
+- Loading-indicator presentation — owned by `component:Spinner`.
+- New targets for untargeted descriptions or caller-provided item content.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, collection and standalone
+item modes, and usage remain documented in `CheckboxList.doc.mjs` and
+`CheckboxListItem.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                    | Basis                                   | Draft review state                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places CheckboxListItem children inside a List and a group named by the group label.                                                | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | The CheckboxList root carries the current `checkbox-list` target.                                                                                      | Current source and public docs          | Verified current behavior; no target change        |
+| FR3 | The option-row root and checkbox indicator continue to be rendered by List and CheckboxInput rather than reimplemented.                                | Current source                          | Verified composition boundary                      |
+| FR5 | Item renders option label and description as separate untargeted children; end content remains caller-provided inside its own untargeted slot wrapper. | Current source and focused tests        | Verified child ownership; no target change         |
+| FR4 | A pending item renders Spinner inside that item's checkbox; a status message renders through detached FieldStatus.                                     | Current source, docs, and focused tests | Verified conditional composition                   |
+
+### Allowed variation
+
+- Option labels, descriptions, and end content may vary with caller-provided
+  CheckboxListItem content without becoming new CheckboxList targets.
+- Density, dividers, checked state, and disabled state remain capabilities of
+  their current owning components rather than separate anatomy parts.
+
+### Representative states
+
+| State                     | Required invariant                                              | Allowed variation                  |
+| ------------------------- | --------------------------------------------------------------- | ---------------------------------- |
+| Default collection        | Named group, options list, rows, and checkbox indicators render | Option content and selected values |
+| Item pending              | Only the pending checkbox includes a Spinner                    | Which option is pending            |
+| Group status with message | Detached FieldStatus follows the group                          | Error, warning, or success status  |
+
+### Transformation and precedence order
+
+- No new state, event, layout, or styling precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend CheckboxList's existing group naming,
+checkbox semantics, focus order, busy state, or description/status association.
+
+## Design relationships
+
+| Anatomy or state   | Design requirement                                                           | Representation authority        | Hierarchy role | Component contract |
+| ------------------ | ---------------------------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |
+| Group              | Contains the current checkbox-group composition.                             | Current source and public docs  | Supporting     | FR1, FR2           |
+| Options and rows   | Present the List-owned list and row root plus Item-rendered child structure. | Current source                  | Supporting     | FR1, FR3           |
+| Checkbox           | Presents each option's current selection indicator.                          | Current CheckboxInput source    | Prominent      | FR3                |
+| Spinner and status | Present the current conditional feedback components.                         | Current shared-component source | Supporting     | FR4                |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Group": {"target": "checkbox-list"},
+  "Group label": {
+    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
+  },
+  "Description": {
+    "none": {
+      "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
+    }
+  },
+  "Options list": {
+    "delegatesTo": {"owner": "component:List", "target": "list"}
+  },
+  "Option row": {
+    "delegatesTo": {"owner": "component:List", "target": "list-item"}
+  },
+  "Checkbox": {
+    "delegatesTo": {
+      "owner": "component:CheckboxInput",
+      "target": "checkbox-indicator"
+    }
+  },
+  "Option label": {
+    "none": {
+      "reason": "unsettled: Item rather than Text renders the stable Option label in a separate untargeted span; future exposure still needs an owner decision"
+    }
+  },
+  "Option description": {
+    "none": {
+      "reason": "unsettled: Item rather than Text renders the stable Option description in a separate untargeted span; future exposure still needs an owner decision"
+    }
+  },
+  "End content": {
+    "none": {
+      "reason": "intentional: End content is caller-provided content outside CheckboxList's public theming ownership"
+    }
+  },
+  "Spinner": {
+    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
+  },
+  "Status message": {
+    "delegatesTo": {
+      "owner": "component:FieldStatus",
+      "target": "field-status"
+    }
+  }
+}
+```
+
+`Description` remains stable consumer anatomy, but no current public target
+reaches it. Item, not Text, renders option labels and descriptions in separate
+untargeted spans, so neither delegates to Text nor inherits the row-root
+`list-item` target; future exposure remains unsettled. Rich label content and end
+content are caller-provided, and end content intentionally stays outside
+CheckboxList's public theming ownership.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, factual
+  `none` dispositions, and composition-preserving target ownership.
+- List, CheckboxInput, Field, FieldStatus, and Spinner retain their existing
+  public target contracts when composed by CheckboxList.
+
+## Verification map
+
+| Contract            | Verification                                                                                         | Representative states                                        | Mutation or failure expectation                                                                                                 | Audit section                |
+| ------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1, FR3, FR5       | `CheckboxList.test.tsx` structure, content, and interaction suites plus `Item.tsx` source inspection | Collection mode; string/rich label; description; end content | Removing the group, row, checkbox, or separate content children breaks existing DOM and interaction assertions.                 | `audit:CheckboxList/anatomy` |
+| FR4                 | `CheckboxList.test.tsx` loading and status suites                                                    | Pending item and detached status                             | Removing composed feedback breaks existing spinner, busy-state, or message assertions.                                          | `audit:CheckboxList/anatomy` |
+| Local target source | `themingTargets.test.ts`                                                                             | `checkbox-list`                                              | Source/docs target drift fails the repository target guard.                                                                     | `audit:CheckboxList/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                        | Canonical anatomy and current local target                   | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:CheckboxList/theming` |
+
+The focused CheckboxList suite does not pin the exact delegated target classes
+or the local `checkbox-list` class in rendered DOM. The source/metadata target
+guard independently verifies that each owner's emitted targets remain
+documented. No current repository check resolves `delegatesTo` owner/target
+pairs; the pairs in this draft were verified manually, so semantic delegation
+drift remains a validation gap.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, or shared-component contracts. It links to their owners.

package/src/CommandPalette/CommandPalette.spec.md

@@ -1,6 +1,6 @@
 ---
 schema_version: 1
-template_version: 2
+template_version: 3
 kind: component
 id: component:CommandPalette
 authority: draft
@@ -153,7 +153,7 @@ reachability, not a decision that it must remain unthemeable.
   },
   "Query field": {
     "none": {
-      "reason": "No current public target is applied directly to the native query field"
+      "reason": "unsettled: No current public target is applied directly to the native query field; future exposure still needs an owner decision"
     }
   },
   "Loading spinner": {

package/src/ComplexSelector/ComplexSelector.doc.mjs

@@ -9,6 +9,46 @@
  * SYNC: When modified, update ComplexSelector.tsx, tests, and stories.
  */
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Field',
+    required: true,
+    description:
+      'Field shell that provides the label and optional supporting field content.',
+  },
+  {
+    name: 'Trigger',
+    required: true,
+    description:
+      'Control that displays the current value or placeholder and opens the popup.',
+  },
+  {
+    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: 'Indicator icon',
+    required: true,
+    description:
+      'Trailing chevron that rotates to reflect whether the popup is open.',
+  },
+  {
+    name: 'Popup',
+    required: true,
+    description:
+      'Mounted dialog surface that is painted and shown while open and hidden while closed.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -158,6 +198,7 @@ export const docs = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'Use ComplexSelector when a selection needs richer custom content than a Selector option row. It is intentionally one component: ComplexSelector owns the field, trigger, popover, focus restore, and changeAction flow, while the content render prop owns the selector-specific accessible structure.',
     bestPractices: [
@@ -218,6 +259,7 @@ export const docsDense = {
   description:
     'Input/ghost trigger + dialog-popover shell for rich custom selectors. Content gets value/onChange/close/state; content owns semantics. Use focus hooks and evaluate custom content against WCAG 2.2.',
   usage: {
+    anatomy,
     description:
       'Use when a selection needs richer custom content than a Selector row. One component: it owns field, trigger, popover, focus restore, and changeAction; the render prop owns the selector-specific accessible structure.',
     bestPractices: [

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

@@ -1,4 +1,50 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Trigger area',
+    required: true,
+    description:
+      'Caller-provided region that accepts right-click, keyboard context-menu, and long-press input.',
+  },
+  {
+    name: 'Pointer menu surface',
+    required: false,
+    description:
+      'Cursor-positioned menu panel used by the pointer presentation.',
+  },
+  {
+    name: 'Pointer action row',
+    required: false,
+    description:
+      'DropdownMenu-owned action, selectable option, or submenu row in the pointer presentation.',
+  },
+  {
+    name: 'Touch sheet frame',
+    required: false,
+    description:
+      'BottomSheet panel, content area, handle, and optional scrim that host touch actions.',
+  },
+  {
+    name: 'Touch menu surface',
+    required: false,
+    description:
+      'ContextMenu-owned content panel rendered inside the touch sheet frame.',
+  },
+  {
+    name: 'Touch action list',
+    required: false,
+    description: 'Spacious List that groups data-driven touch actions.',
+  },
+  {
+    name: 'Touch action row',
+    required: false,
+    description:
+      'ListItem button used for a data-driven action or drill-in entry in the touch presentation.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -80,6 +126,7 @@ export const docs = {
     {name: 'ContextMenuItem'},
   ],
   usage: {
+    anatomy,
     description: 'A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions without cluttering the UI with visible buttons.',
     bestPractices: [
       { guidance: true, description: 'Keep menu items concise and action-oriented; users expect quick access to contextual actions.' },
@@ -128,6 +175,7 @@ export const docsZh = {
 export const docsDense = {
   description: 'right-click context menu at cursor position',
   usage: {
+    anatomy,
     description: 'A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions.',
     bestPractices: [
       { guidance: true, description: 'Keep items concise and action-oriented.' },