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

package/src/Tooltip/Tooltip.spec.md

@@ -0,0 +1,141 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Tooltip
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [packages/core/src/Tooltip/Tooltip.test.tsx, scripts/check-knowledge.mjs]
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:layer-runtime,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Tooltip component contract
+
+## Intent
+
+Tooltip renders supplied tooltip content on an owned overlay surface associated
+with a caller-owned trigger. This draft records current consumer anatomy and
+theming ownership without deciding layer behavior, positioning, or new visual
+parts.
+
+## 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 rendered tooltip surface and content inside that surface.
+
+**Does not own / non-goals**
+
+- The trigger element — supplied by the caller or referenced externally and
+  outside Tooltip's owned anatomy.
+- An arrow element — the current implementation renders none.
+- Layer lifecycle, light dismissal, and anchor-positioning policy — outside this
+  factual anatomy backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Tooltip.doc.mjs` and `useTooltip.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                  | Basis                           | Draft review state                                 |
+| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current rendered tooltip contains one owned surface with the supplied tooltip content inside it. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | The surface carries the current `tooltip` target; its content has no separate target.                | Current source and public docs  | Verified current behavior; no target change        |
+
+### Allowed variation
+
+- Supplied content may vary without adding a Tooltip-owned child target.
+
+### Representative states
+
+- The owned anatomy is unchanged across wrapped-trigger and external-anchor
+  modes; the trigger remains outside it.
+
+### Transformation and precedence order
+
+- No new ordering or positioning rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Tooltip's existing accessibility behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                  | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | --------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Tooltip surface  | Presents the current painted overlay surface.       | Current source and public docs | Supporting     | FR1, FR2           |
+| Tooltip text     | Presents supplied content within the owned surface. | Current source and public docs | Prominent      | FR1, FR2           |
+
+The trigger is caller-owned and outside this anatomy. The current implementation
+has no arrow element.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Tooltip surface": {"target": "tooltip"},
+  "Tooltip text": {"inherits": "tooltip"}
+}
+```
+
+## Family and system relationships
+
+This draft references the current shared owners without restating their rules:
+`architecture:component-theming-surface`, `family:overlay-dismissal`,
+`architecture:interaction-modality`, `architecture:layer-runtime`, and
+`architecture:public-component-api`.
+
+## Verification map
+
+| Contract            | Verification                          | Representative states                 | Mutation or failure expectation                                                  | Audit section           |
+| ------------------- | ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------- | ----------------------- |
+| FR1                 | `Tooltip.test.tsx` role/content suite | Rendered surface and supplied content | Removing the surface or content fails existing tooltip role and text assertions. | `audit:Tooltip/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`         | Canonical anatomy and current target  | Missing, extra, prefixed, or stale mappings fail repository validation.          | `audit:Tooltip/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or layer-system decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, layer-system rules,
+implementation steps, or system rules. It links to their owners.

package/src/TreeList/TreeList.doc.mjs

@@ -1,5 +1,60 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Tree list',
+    required: true,
+    description: 'Container that presents the hierarchical tree.',
+  },
+  {
+    name: 'Header',
+    required: false,
+    description: 'Caller-provided content that visibly names the tree.',
+  },
+  {
+    name: 'Item',
+    required: true,
+    description: 'Painted row for one node in the hierarchy.',
+  },
+  {
+    name: 'Chevron',
+    required: false,
+    description:
+      'Expand and collapse control rendered for an Item with children.',
+  },
+  {
+    name: 'Chevron glyph',
+    required: false,
+    description: 'Directional symbol rendered by Icon inside a Chevron.',
+  },
+  {
+    name: 'Item label',
+    required: true,
+    description: 'Primary content that identifies an Item.',
+  },
+  {
+    name: 'Item description',
+    required: false,
+    description: 'Secondary text rendered below an Item label.',
+  },
+  {
+    name: 'Start content',
+    required: false,
+    description: 'Caller-provided content rendered before an Item label.',
+  },
+  {
+    name: 'End content',
+    required: false,
+    description: 'Caller-provided content rendered after an Item label.',
+  },
+  {
+    name: 'Guide',
+    required: false,
+    description: 'Connector line that shows parent-child relationships.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -79,6 +134,7 @@ export const docs = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
     bestPractices: [
@@ -158,6 +214,7 @@ export const docsZh = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
     bestPractices: [
@@ -175,6 +232,7 @@ export const docsDense = {
   description:
     'Data-driven tree list for hierarchical data w/ expand/collapse, branch lines, interactive items. Flat items array w/ recursive children, no composition, no cloneElement.',
   usage: {
+    anatomy,
     description:
       'An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.',
     bestPractices: [

package/src/TreeList/TreeList.spec.md

@@ -0,0 +1,220 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:TreeList
+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/TreeList/TreeList.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# TreeList component contract
+
+## Intent
+
+TreeList presents hierarchical data as expandable tree rows. This draft records
+its current consumer anatomy, target ownership, delegated Icon glyph, and
+unreached 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**
+
+- The Tree list, Item, Chevron, Item label, and Guide parts and their five current
+  targets.
+- The stable Item description rendered below an Item label.
+- Hierarchical placement, indentation, expansion, selection, and tree semantics.
+
+**Does not own / non-goals**
+
+- The Chevron glyph artwork and Icon target — owned by `component:Icon`.
+- Header, Start content, and End content supplied through consumer slots — owned
+  by the product callsite.
+- New targets for Item description or caller-provided slots — unresolved by this
+  factual backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer data, props, slots, and usage
+remain documented in `TreeList.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                          | Basis                             | Draft review state                                                        |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------- |
+| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs. | Current source, docs, and tests   | Verified current behavior; no new behavior decided                        |
+| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below.                                                                                                | Current source and target docs    | Verified current inventory; focused placement coverage is partial         |
+| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target.                                                                      | Current source and component docs | Verified current ownership; no target change                              |
+| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content.  | Current source and target docs    | Verified current reachability; long-term theming intent remains unsettled |
+
+### Allowed variation
+
+- **AV1 — Hierarchy.** Item count, depth, expansion, selection, density, and guide
+  visibility may vary without changing the anatomy ownership recorded here.
+- **AV2 — Consumer content.** Header, Start content, End content, Item label
+  values, and descriptions may vary without making caller-owned slot content a
+  TreeList target.
+- **AV3 — Delegated glyph.** Icon may change the Chevron glyph's internal element
+  shape while preserving its own public contract.
+
+### Representative states
+
+| State                    | Required invariant                                    | Allowed variation                             |
+| ------------------------ | ----------------------------------------------------- | --------------------------------------------- |
+| Empty tree               | Tree list remains; no Item instances render.          | Optional Header content.                      |
+| Flat items               | Each Item contains an Item label.                     | Description and consumer slots may be absent. |
+| Expandable item          | Item may contain Chevron and delegated Chevron glyph. | Expanded or collapsed state.                  |
+| Nested `lineGuides` tree | Guide instances show parent-child relationships.      | Count and position follow hierarchy.          |
+| `noGuides` tree          | Guide instances are absent; indentation remains.      | All other anatomy remains unchanged.          |
+| Described item           | Item description renders below Item label.            | Caller-provided description text.             |
+
+### Transformation and precedence order
+
+- No new hierarchy, focus, expansion, 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 TreeList's current tree, treeitem, group,
+roving-focus, expansion, selection, disabled, or activation behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                   | Representation authority       | Hierarchy role    | Component contract |
+| ---------------- | -------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Tree list        | Groups the hierarchical tree and owns its density and guide variant. | Current source and public docs | Supporting        | FR1, FR2           |
+| Header           | Visibly names the tree with caller-provided content.                 | Caller-supplied content        | Prominent         | FR1, FR3           |
+| Item             | Paints one row and reflects density, selection, and disabled state.  | Current source and public docs | Prominent         | FR1, FR2           |
+| Chevron          | Provides the expand and collapse control for an Item with children.  | Current source and public docs | Supporting        | FR1, FR2           |
+| Chevron glyph    | Presents the current directional symbol inside Chevron.              | `component:Icon`               | Supporting        | FR1, FR3           |
+| Item label       | Presents the primary content that identifies an Item.                | Current source and public docs | Prominent         | FR1, FR2           |
+| Item description | Presents stable secondary text below Item label.                     | Current source and public docs | Supporting        | FR1, FR4           |
+| Start content    | Presents caller-provided content before Item label.                  | Caller-supplied content        | Context-dependent | FR1, FR3           |
+| End content      | Presents caller-provided content after Item label.                   | Caller-supplied content        | Context-dependent | FR1, FR3           |
+| Guide            | Paints a connector between related hierarchy levels.                 | Current source and public docs | Supporting        | FR1, FR2           |
+
+Item description is stable TreeList-rendered anatomy, not consumer-owned slot
+structure. Its current lack of a target is observed reachability, not a decision
+that it must remain unthemeable. Header, Start content, and End content remain
+caller-owned even though TreeList positions their slot wrappers.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Tree list": {"target": "tree-list"},
+  "Header": {
+    "none": {
+      "reason": "intentional: Header is caller-provided content outside TreeList's public theming ownership"
+    }
+  },
+  "Item": {"target": "tree-list-item"},
+  "Chevron": {"target": "tree-list-chevron"},
+  "Chevron glyph": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Item label": {"target": "tree-list-item-label"},
+  "Item description": {
+    "none": {
+      "reason": "unsettled: No current public target reaches the stable Item description; future exposure still needs an owner decision"
+    }
+  },
+  "Start content": {
+    "none": {
+      "reason": "intentional: Start content is caller-provided content outside TreeList's public theming ownership"
+    }
+  },
+  "End content": {
+    "none": {
+      "reason": "intentional: End content is caller-provided content outside TreeList's public theming ownership"
+    }
+  },
+  "Guide": {"target": "tree-list-guide"}
+}
+```
+
+The five local targets are current public seams. The Chevron glyph retains Icon
+ownership. Consumer-slot `none` dispositions are ownership boundaries; Item
+description's `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 data, props, and slot
+  surface; this documentation adds no API.
+- `architecture:interaction-modality` owns shared keyboard and pointer modality;
+  TreeList continues to own its existing tree focus and activation behavior.
+- TreeList has no current family contract, and no unresolved family or runtime
+  record identifier is included.
+
+## Verification map
+
+| Contract            | Verification                                                                                    | Representative states                              | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section            |
+| ------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1                 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection | Flat, nested, described, headed, and slotted items | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy` |
+| FR2                 | `TreeList.test.tsx` and `themingTargets.test.ts`                                                | Five local targets and their documented states     | Removing or moving any current local target fails focused class assertions or the global inventory.                                                                                                                                                 | `audit:TreeList/theming` |
+| FR3                 | Source inspection plus Icon public target metadata                                              | Expandable rows and caller-provided slots          | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change.                                                                                      | `audit:TreeList/theming` |
+| FR4                 | `TreeList.test.tsx` description rendering test and source inspection                            | Item with description                              | Removing description fails content coverage; adding a target requires an explicit map update.                                                                                                                                                       | `audit:TreeList/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                   | Canonical anatomy and five current local targets   | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                               | `audit:TreeList/theming` |
+
+Focused target-placement assertions cover all five local targets: Tree list,
+Item, Chevron, Item label, and Guide. Existing tests do not assert the Icon
+instance that renders Chevron glyph.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, behavior, or theming decision.
+
+## Open questions
+
+- **OQ1 — Should Item description gain a stable public theming target?**
+  (`human-api`) Its current lack of reachability is an audit gap, not settled
+  intent.
+- **OQ2 — Should a focused test pin the delegated Chevron glyph's Icon
+  instance?** (`checkable`) Its presence is currently source-inspected rather
+  than asserted.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, shared modality
+rules, current audit results, or implementation steps. It links to their owners.

package/src/Typeahead/Typeahead.doc.mjs

@@ -1,5 +1,85 @@
 // 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: 'Input surface',
+    required: true,
+    description:
+      'Painted control surface containing the editable input or the selected token.',
+  },
+  {
+    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 input surface.',
+  },
+  {
+    name: 'Selected token',
+    required: false,
+    description:
+      'Token that presents the selected item while the control is not in edit mode.',
+  },
+  {
+    name: 'Clear button',
+    required: false,
+    description:
+      'Shared clear action that removes the selected item when hasClear is enabled.',
+  },
+  {
+    name: 'Dropdown',
+    required: false,
+    description:
+      'Anchored listbox surface containing the current search results.',
+  },
+  {
+    name: 'Empty state',
+    required: false,
+    description: 'Message shown after a completed search returns no results.',
+  },
+  {
+    name: 'Result row',
+    required: false,
+    description:
+      'Stable option wrapper that owns highlight, selection, pointer, and keyboard behavior.',
+  },
+  {
+    name: 'Default item content',
+    required: false,
+    description:
+      'Standard TypeaheadItem label and supporting content rendered inside a result row when renderItem and item.element are absent.',
+  },
+  {
+    name: 'Caller-rendered item content',
+    required: false,
+    description:
+      'Caller-owned result content supplied through renderItem or item.element inside the stable result row.',
+  },
+  {
+    name: 'Result group heading',
+    required: false,
+    description: 'Visible heading for a labeled group of result rows.',
+  },
+  {
+    name: 'Selected result state',
+    required: false,
+    description:
+      'Selected styling and trailing check presented on the current result row.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -86,7 +166,8 @@ export const docs = {
     {
       name: 'minQueryLength',
       type: 'number',
-      description: 'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',
+      description:
+        'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',
       default: '1',
     },
     {
@@ -199,6 +280,7 @@ export const docs = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',
     bestPractices: [