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

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.doc.mjs

@@ -1,5 +1,74 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Dialog',
+    required: true,
+    description: 'Modal surface that contains the command palette.',
+  },
+  {
+    name: 'Input',
+    required: true,
+    description:
+      'Search region containing the query field and its supporting visuals.',
+  },
+  {
+    name: 'Search glyph',
+    required: true,
+    description: 'Search symbol rendered by Icon in the default Input.',
+  },
+  {
+    name: 'Query field',
+    required: true,
+    description: 'Native text field used to enter a search query.',
+  },
+  {
+    name: 'Loading spinner',
+    required: false,
+    description:
+      'Spinner shown in the default Input while a search is pending.',
+  },
+  {
+    name: 'List',
+    required: true,
+    description:
+      'Scrollable listbox containing the current results or Empty state.',
+  },
+  {
+    name: 'Item',
+    required: false,
+    description: 'Selectable command result rendered inside the List.',
+  },
+  {
+    name: 'Group',
+    required: false,
+    description: 'Optional collection of Items that share a heading.',
+  },
+  {
+    name: 'Group heading',
+    required: false,
+    description: 'Visible heading rendered for a Group.',
+  },
+  {
+    name: 'Empty',
+    required: false,
+    description: 'Message shown when the current result set is empty.',
+  },
+  {
+    name: 'Footer',
+    required: false,
+    description:
+      'Footer region for default keyboard guidance or caller-provided content.',
+  },
+  {
+    name: 'Keyboard shortcut',
+    required: false,
+    description:
+      'Painted key badges rendered by Kbd in the default Footer guidance.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docs = {
   name: 'CommandPalette',
@@ -152,6 +221,7 @@ export const docs = {
     ],
   },
   usage: {
+    anatomy,
     description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
     bestPractices: [
       { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
@@ -165,6 +235,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
+    anatomy,
     description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
     bestPractices: [
       { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
@@ -180,6 +251,7 @@ export const docsDense = {
   description:
     'searchSource-driven command palette dialog; filtering, keyboard nav, grouping, selection; same SearchSource interface as Typeahead',
   usage: {
+    anatomy,
     description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
     bestPractices: [
       { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },

package/src/CommandPalette/CommandPalette.spec.md

@@ -0,0 +1,223 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:CommandPalette
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [behavior, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/CommandPalette/CommandPalette.test.tsx,
+    packages/core/src/CommandPalette/CommandPaletteInput.test.tsx,
+    packages/core/src/CommandPalette/CommandPaletteList.test.tsx,
+    packages/core/src/CommandPalette/CommandPaletteItem.test.tsx,
+    packages/core/src/CommandPalette/CommandPaletteGroup.test.tsx,
+    packages/core/src/CommandPalette/CommandPaletteFooter.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# CommandPalette component contract
+
+## Intent
+
+CommandPalette presents searchable commands inside a Dialog. This draft records
+its current aggregate consumer anatomy, target ownership, and delegated stable
+parts 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, aliases, 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**
+
+- Search orchestration and the current Input, List, Item, Group, Group heading,
+  Empty, and Footer parts and targets.
+- The native Query field rendered inside the default Input.
+
+**Does not own / non-goals**
+
+- Dialog's surface, Icon's glyph, Spinner's loading indicator, or Kbd's shortcut
+  badges — owned by their respective components.
+- Caller-provided replacement Input, Footer, item content, or trailing input
+  content — owned by the product callsite.
+- A `command-palette` root target — no such current target exists, and this
+  factual backfill does not invent one.
+- Shared layer hosting, positioning, or lifecycle rules beyond the current
+  records linked below.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, slots, and usage remain
+documented in `CommandPalette.doc.mjs` and its subcomponent docs.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                 | Basis                             | Draft review state                                                        |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------- |
+| FR1 | The current default render places Input and Footer around a List inside a delegated Dialog; the List contains Items, optional Groups and Group headings, or Empty according to the current results. | Current source, docs, and tests   | Verified current behavior; no new behavior decided                        |
+| FR2 | Input, List, Item, Group, Group heading, Empty, and Footer carry the seven current `command-palette-*` targets documented below; no `command-palette` root target exists.                           | Current source and target docs    | Verified current inventory; focused placement coverage is partial         |
+| FR3 | The default Input delegates its Search glyph to Icon and pending Loading spinner to Spinner; the default Footer delegates keyboard shortcuts to Kbd; the containing surface delegates to Dialog.    | Current source and component docs | Verified current composition; no ownership change                         |
+| FR4 | Query field is a distinct native text field inside Input and currently has no separate public target. The `command-palette-input` target is on the surrounding search region, not the native field. | Current source and target docs    | Verified current reachability; long-term theming intent remains unsettled |
+
+### Allowed variation
+
+- **AV1 — Results.** Item count, grouping, selected content, and empty state may
+  vary without changing the aggregate anatomy.
+- **AV2 — Slots.** Caller-provided Input and Footer content may replace the
+  defaults without becoming CommandPalette-owned subparts.
+- **AV3 — Delegated rendering.** Dialog, Icon, Spinner, and Kbd may change their
+  internal element shape while preserving their own public contracts.
+
+### Representative states
+
+| State                  | Required invariant                                      | Allowed variation                               |
+| ---------------------- | ------------------------------------------------------- | ----------------------------------------------- |
+| Ungrouped results      | List contains Item instances.                           | Item count and caller-rendered content.         |
+| Grouped results        | List contains Group, Group heading, and Item instances. | Group names, count, ordering, and item content. |
+| Empty bootstrap/search | List contains Empty instead of Items.                   | Caller-provided empty content.                  |
+| Pending search         | Default Input may contain Loading spinner.              | Spinner is absent when no search is pending.    |
+| Default slots          | Input and Footer render their documented defaults.      | Footer shortcut text and translated labels.     |
+| Caller-replaced slots  | The slot content replaces the corresponding default.    | Replacement structure remains caller-owned.     |
+
+### Transformation and precedence order
+
+- No new search, selection, 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 CommandPalette's current Dialog, combobox,
+listbox, option, announcement, or keyboard behavior.
+
+## Design relationships
+
+| Anatomy or state  | Design requirement                                                      | Representation authority       | Hierarchy role | Component contract |
+| ----------------- | ----------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Dialog            | Presents the containing modal surface.                                  | `component:Dialog`             | Supporting     | FR1, FR3           |
+| Input             | Paints the search region around the query field and supporting visuals. | Current source and public docs | Prominent      | FR1, FR2, FR4      |
+| Search glyph      | Presents the search symbol in the default Input.                        | `component:Icon`               | Supporting     | FR3                |
+| Query field       | Accepts the native text query inside Input.                             | Current source and public docs | Prominent      | FR1, FR4           |
+| Loading spinner   | Indicates a pending search in the default Input.                        | `component:Spinner`            | Supporting     | FR3                |
+| List              | Presents the current result collection or Empty state.                  | Current source and public docs | Supporting     | FR1, FR2           |
+| Item              | Presents one selectable command result.                                 | Current source and public docs | Prominent      | FR1, FR2           |
+| Group             | Arranges related Items together.                                        | Current source and public docs | Supporting     | FR1, FR2           |
+| Group heading     | Labels one Group visually.                                              | Current source and public docs | Supporting     | FR1, FR2           |
+| Empty             | Presents the no-results or no-query message.                            | Current source and public docs | Prominent      | FR1, FR2           |
+| Footer            | Presents default guidance or caller-provided footer content.            | Current source and public docs | Supporting     | FR1, FR2           |
+| Keyboard shortcut | Presents one shortcut as painted key badges in the default Footer.      | `component:Kbd`                | Supporting     | FR3                |
+
+The native Query field is separate from the Input region that carries
+`command-palette-input`. Its current lack of a direct target is observed
+reachability, not a decision that it must remain unthemeable.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Dialog": {
+    "delegatesTo": {"owner": "component:Dialog", "target": "dialog"}
+  },
+  "Input": {"target": "command-palette-input"},
+  "Search glyph": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Query field": {
+    "none": {
+      "reason": "unsettled: No current public target is applied directly to the native query field; future exposure still needs an owner decision"
+    }
+  },
+  "Loading spinner": {
+    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
+  },
+  "List": {"target": "command-palette-list"},
+  "Item": {"target": "command-palette-item"},
+  "Group": {"target": "command-palette-group"},
+  "Group heading": {"target": "command-palette-group-heading"},
+  "Empty": {"target": "command-palette-empty"},
+  "Footer": {"target": "command-palette-footer"},
+  "Keyboard shortcut": {
+    "delegatesTo": {"owner": "component:Kbd", "target": "kbd"}
+  }
+}
+```
+
+The seven local targets are current public seams. The delegated parts retain
+their existing component owners. The Query field `none` disposition records a
+current audit gap and does not authorize a new target.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+  mapping, delegation, and factual `none` dispositions.
+- `architecture:public-component-api` owns the stable props and composition
+  surface; this documentation adds no API.
+- `architecture:interaction-modality` owns shared keyboard and pointer modality;
+  this draft does not redefine focus ownership or input behavior.
+- `family:overlay-dismissal` identifies CommandPalette as a current member and
+  records its component-local Escape handling as an adoption gap.
+- No layer-runtime record is linked because no current record with that scope is
+  present in this checkout.
+
+## Verification map
+
+| Contract            | Verification                                                                    | Representative states                                  | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section                  |
+| ------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1                 | CommandPalette root and subcomponent render suites plus source inspection       | Default, grouped, empty, pending, and replaced slots   | Removing the asserted Dialog, Query field, List, Item, Group, Group heading, Empty, or Footer content fails existing role, content, or slot assertions; Search glyph, Loading spinner, and Keyboard shortcut presence remain source-inspected only. | `audit:CommandPalette/anatomy` |
+| FR2                 | Source inspection, `themingTargets.test.ts`, and `CommandPaletteGroup.test.tsx` | Seven local targets; Group and Group heading placement | Removing a current target fails the global inventory; moving Group or Group heading fails focused class assertions.                                                                                                                                 | `audit:CommandPalette/theming` |
+| FR3                 | Source inspection plus Dialog, Icon, Spinner, and Kbd public target metadata    | Default surface, Input visuals, and Footer shortcuts   | Existing focused tests do not assert the composed Icon, Spinner, or Kbd instances; changing delegated ownership requires this map and the delegated component metadata to change.                                                                   | `audit:CommandPalette/theming` |
+| FR4                 | `CommandPaletteInput.test.tsx` and source inspection                            | Native query field with idle and pending Input         | Removing the field fails combobox tests; adding a field target requires an explicit map update.                                                                                                                                                     | `audit:CommandPalette/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                   | Canonical anatomy and seven current local targets      | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                               | `audit:CommandPalette/theming` |
+
+Focused target-placement assertions currently cover Group and Group heading.
+Input, List, Item, Empty, and Footer placement rely on source inspection plus the
+global target inventory. Existing tests assert default Footer text and pending
+announcements, but do not assert that Icon, Spinner, or Kbd renders.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+layer, API, or theming decision.
+
+## Open questions
+
+- **OQ1 — Should Query field gain a stable public theming target?** (`human-api`)
+  Its current lack of direct reachability is an audit gap, not settled intent.
+- **OQ2 — Should focused tests pin the default Search glyph, pending Loading
+  spinner, and default Footer Keyboard shortcuts?** (`checkable`) Their presence
+  is currently source-inspected rather than asserted.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, shared layer or
+modality rules, current audit results, or implementation steps. It links to
+their owners.

package/src/ComplexSelector/ComplexSelector.doc.mjs

@@ -9,13 +9,53 @@
  * 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 = {
   name: 'ComplexSelector',
   displayName: 'Complex Selector',
   group: 'Selector',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: [
     'selector',
     'picker',
@@ -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: [
@@ -214,10 +255,11 @@ export const docsDense = {
   name: 'ComplexSelector',
   displayName: 'Complex Selector',
   group: 'Selector',
-  category: 'Data Input',
+  category: 'Form Controls',
   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: [