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

package/src/NavMenu/NavHeadingMenu.spec.md

@@ -0,0 +1,205 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:NavHeadingMenu
+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/NavMenu/NavHeadingMenu.test.tsx,
+    packages/core/src/Icon/Icon.test.tsx,
+    packages/core/src/Text/Text.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:icon-resolution-and-component-slots,
+    architecture:layer-runtime,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# NavHeadingMenu component contract
+
+## Intent
+
+NavHeadingMenu presents selectable actions inside a SideNavHeading or
+TopNavHeading popover. This draft records the current consumer anatomy and
+theming ownership without changing rendering, keyboard behavior, layer
+lifecycle, 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 Menu container, menu semantics, keyboard movement, typeahead, and current
+  `nav-heading-menu` target.
+- Each Item's action/link row, selection handling, size treatment, and current
+  `nav-heading-menu-item` target.
+- The content layout that contains either the text-rendered or caller-rendered
+  label path and the optional description.
+
+**Does not own / non-goals**
+
+- Icon artwork and the `icon` target — delegated to `component:Icon` for values
+  rendered through Icon.
+- String label and description typography and their `text` target — delegated to
+  `component:Text`.
+- Non-string label content — owned by the caller.
+- The SideNavHeading or TopNavHeading trigger, popup surface, positioning,
+  dismissal lifecycle, or close-state ownership.
+- New NavHeadingMenu targets for either label path or Item description, or any
+  runtime, API, target, or DOM change.
+
+## Public concepts
+
+No new public concept is introduced. The canonical `NavMenu.doc.mjs` continues
+to document NavHeadingMenu and NavHeadingMenuItem together.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                  | Basis                           | Draft review state                                      |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------- |
+| FR1 | NavHeadingMenu renders one Menu carrying `role="menu"` and the current `nav-heading-menu` target.                                                                                                    | Current source, docs, and tests | Verified current behavior; no new behavior decided      |
+| FR2 | NavHeadingMenuItem renders one Item carrying `role="menuitem"` and the current `nav-heading-menu-item` target as a link when `href` is supplied and a div otherwise.                                 | Current source, docs, and tests | Verified current behavior; no target change             |
+| FR3 | An optional Icon-rendered icon delegates to Icon's `icon` target. String labels and all descriptions render through Text's `text` target; non-string labels render directly as caller-owned content. | Current source and target docs  | Verified current ownership; focused evidence is partial |
+| FR4 | The parent nav heading supplies the close callback and owns its popup runtime; NavHeadingMenu consumes that callback for Escape and successful Item selection.                                       | Current source and tests        | Verified current relationship; no layer change          |
+
+### Allowed variation
+
+- Items may render as links or callback actions and may be enabled or disabled
+  without changing anatomy ownership.
+- Icon may be absent. A label may take the string path rendered through Text or
+  the non-string path rendered directly as caller-owned content. Item
+  description may be absent and, when present, renders through Text.
+- Menu size and minimum width may vary without creating separate anatomy parts
+  or targets.
+
+### Representative states
+
+| State             | Required invariant                                                | Allowed variation                                         |
+| ----------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
+| Link Item         | Item is an anchor with menuitem semantics and its current target. | Destination, text, description, and icon may vary.        |
+| Action Item       | Item is a div with menuitem semantics and its current target.     | Selection callback may vary.                              |
+| Disabled Item     | Item remains present and reflects disabled semantics.             | It is skipped by keyboard navigation and typeahead.       |
+| String-label Item | Text-rendered item label delegates to Text's current target.      | Label value, destination, description, and icon may vary. |
+| Custom-label Item | Caller-rendered item label remains caller-owned.                  | Caller controls the non-string label content.             |
+| Described Item    | Item description delegates to Text's current target.              | Description content may vary or be absent.                |
+
+### Transformation and precedence order
+
+- No new focus, typeahead, activation, close, size, 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 the current menu/menuitem roles, disabled
+state, arrow/Home/End/Escape movement, typeahead, keyboard activation, or caller
+labeling behavior.
+
+## Design relationships
+
+| Anatomy or state           | Design requirement                                                        | Representation authority       | Hierarchy role    | Component contract |
+| -------------------------- | ------------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Menu                       | Groups nav-heading actions with menu semantics and keyboard navigation.   | Current source and public docs | Prominent         | FR1, FR4           |
+| Item                       | Presents one selectable action or navigation destination.                 | Current source and public docs | Prominent         | FR2                |
+| Icon                       | Presents optional Icon-owned artwork before the label.                    | `component:Icon`               | Supporting        | FR3                |
+| Text-rendered item label   | Presents a string label through Text's body treatment.                    | `component:Text`               | Prominent         | FR2, FR3           |
+| Caller-rendered item label | Presents a non-string label directly through caller-owned content.        | Caller-supplied content        | Context-dependent | FR2, FR3           |
+| Item description           | Presents optional supporting content through Text's supporting treatment. | `component:Text`               | Supporting        | FR2, FR3           |
+
+The menu is popup content, not the popup host. SideNavHeading or TopNavHeading
+owns the layer lifecycle and supplies the close callback through context.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Menu": {"target": "nav-heading-menu"},
+  "Item": {"target": "nav-heading-menu-item"},
+  "Icon": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Text-rendered item label": {
+    "delegatesTo": {"owner": "component:Text", "target": "text"}
+  },
+  "Caller-rendered item label": {
+    "none": {
+      "reason": "intentional: Non-string label content is rendered directly and remains caller-owned"
+    }
+  },
+  "Item description": {
+    "delegatesTo": {"owner": "component:Text", "target": "text"}
+  }
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, local
+  target mapping, component delegation, and factual `none` dispositions.
+- `architecture:icon-resolution-and-component-slots` owns Icon slot resolution;
+  this draft records the current Icon delegation without changing slot behavior.
+- `architecture:layer-runtime` owns the shared popup host lifecycle used by the
+  parent nav heading. NavHeadingMenu owns only its menu behavior and consumes the
+  heading-provided close callback.
+- `architecture:public-component-api` owns the stable props and subcomponent
+  surface; this documentation adds no API.
+- NavHeadingMenu has no current family contract.
+
+## Verification map
+
+| Contract            | Verification                                                            | Representative states                                            | Mutation or failure expectation                                                                                                                                                                        | Audit section                   |
+| ------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
+| FR1, FR2            | `NavHeadingMenu.test.tsx` role, render, link, and disabled suites       | Menu with link, action, and disabled Items                       | Removing menu/item semantics, content, or current rendering branches fails existing role, tag, attribute, and text checks.                                                                             | `audit:NavHeadingMenu/anatomy`  |
+| FR3                 | NavHeadingMenuItem source inspection plus Icon and Text target metadata | Icon, string label, caller-rendered label, and description paths | Source proves Icon-slot delegation, conditional label rendering, and Text-wrapped description; focused tests assert string and description content but not target placement or custom-label ownership. | `audit:NavHeadingMenu/theming`  |
+| FR4                 | `NavHeadingMenu.test.tsx` context and keyboard suites                   | Selection, Escape, arrows, Home/End, typeahead                   | Breaking close callback consumption or keyboard behavior fails focused interaction assertions.                                                                                                         | `audit:NavHeadingMenu/behavior` |
+| Target inventory    | Source inspection and `themingTargets.test.ts`                          | Menu, Item, and delegated Icon targets                           | Runtime and documented target metadata drift fails target validation.                                                                                                                                  | `audit:NavHeadingMenu/theming`  |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                           | Canonical anatomy and both current local targets                 | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                                                                                | `audit:NavHeadingMenu/theming`  |
+
+Existing tests prove menu/item roles, string-label and description content,
+interaction, and the heading-provided close callback. The conditional non-string
+label path, Icon target placement, Text target placement, and both local target
+placements remain source-inspected rather than pinned by focused assertions.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+behavior, accessibility, layer, or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, keyboard or layer
+algorithms, implementation steps, or system rules. It links to their owners.

package/src/NavMenu/NavMenu.doc.mjs

@@ -1,5 +1,40 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Menu',
+    required: true,
+    description:
+      'Menu container for nav-heading actions, with menu semantics and keyboard navigation.',
+  },
+  {
+    name: 'Item',
+    required: true,
+    description: 'Selectable action or navigation link inside the Menu.',
+  },
+  {
+    name: 'Icon',
+    required: false,
+    description: 'Optional Icon-rendered artwork shown before an Item label.',
+  },
+  {
+    name: 'Text-rendered item label',
+    required: false,
+    description: 'String Item label rendered through Text.',
+  },
+  {
+    name: 'Caller-rendered item label',
+    required: false,
+    description: 'Non-string Item label content rendered directly by the caller.',
+  },
+  {
+    name: 'Item description',
+    required: false,
+    description: 'Optional supporting description rendered through Text.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -11,6 +46,7 @@ export const docs = {
   hidden: false,
   keywords: ['nav', 'menu', 'navigation', 'heading', 'menu-item', 'popover'],
   usage: {
+    anatomy,
     description:
       'Accessible menu container and items for nav heading popovers. ' +
       'NavHeadingMenu provides role="menu" with keyboard navigation; ' +
@@ -44,6 +80,7 @@ export const docs = {
 export const docsDense = {
   description: 'Accessible menu container + items for nav heading popovers. NavHeadingMenu = role="menu" w/ keyboard nav; NavHeadingMenuItem renders selectable items.',
   usage: {
+    anatomy,
     description:
       'Accessible menu container + items for nav heading popovers. NavHeadingMenu provides role="menu" w/ keyboard navigation; NavHeadingMenuItem renders individual selectable items. Pass as menu prop of SideNavHeading or TopNavHeading.',
   },

package/src/NumberInput/NumberInput.doc.mjs

@@ -5,7 +5,7 @@
 export const docs = {
   name: 'NumberInput',
   displayName: 'Number Input',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: [
     'numberinput',
     'numberfield',

package/src/Outline/Outline.doc.mjs

@@ -1,5 +1,37 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Outline',
+    required: true,
+    description:
+      'Navigation container for the same-page heading links and indicator.',
+  },
+  {
+    name: 'Heading link',
+    required: true,
+    description:
+      'Anchor for one heading, indented by level and marked when active.',
+  },
+  {
+    name: 'Label',
+    required: true,
+    description: 'Heading text displayed inside its heading link.',
+  },
+  {
+    name: 'Indicator track',
+    required: true,
+    description: 'Painted vertical rule behind the active indicator.',
+  },
+  {
+    name: 'Active indicator',
+    required: true,
+    description:
+      'Sliding bar positioned beside the currently active heading link.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -222,6 +254,7 @@ function FlashOnArrival() {
     },
   ],
   usage: {
+    anatomy,
     description:
       'A table-of-contents sidebar for documentation pages, help centers, wikis, and long settings pages. Use it for navigation within a single page, not for app routes. Features a sliding indicator track that animates to the active heading. The list is a single tab stop: arrow keys move between headings, Home/End jump to the ends, and Enter/Space activate.',
     bestPractices: [
@@ -323,6 +356,7 @@ export const docsZh = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'A table-of-contents sidebar for documentation pages, help centers, wikis, and long settings pages. Use it for navigation within a single page, not for app routes.',
     bestPractices: [
@@ -341,6 +375,7 @@ export const docsDense = {
   description:
     'Document outline/table-of-contents nav with sliding indicator track. Flat items array {id,label,level}; anchor links; density variant (default/compact); uncontrolled scroll-spy by scroll position (last heading past its resting line = offset + its own scroll-margin-top; first item at top, last at bottom); controlled with activeId; smooth-scroll on click that pins the active item until the next manual scroll. Single tab stop (roving tabindex): Arrow keys move, Home/End jump, Enter/Space activate. onNavigateStart/onNavigateEnd fire around the scroll. Scroll scoping via offset / scrollContainerRef / hasScrollOnClick.',
   usage: {
+    anatomy,
     description:
       'A table-of-contents sidebar for documentation pages, help centers, wikis, and long settings pages. Use it for navigation within a single page, not for app routes.',
     bestPractices: [

package/src/Outline/Outline.spec.md

@@ -0,0 +1,161 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Outline
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [packages/core/src/Outline/Outline.test.tsx, scripts/check-knowledge.mjs]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Outline component contract
+
+## Intent
+
+Outline presents same-page heading navigation with heading links, labels, a
+vertical indicator track, and a sliding active indicator. This draft records
+current consumer anatomy and theming reachability 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 outline navigation container and its current `outline` target.
+- The heading links and their current `outline-item` target.
+- The active indicator and its current `outline-indicator` target.
+- The label and indicator-track elements rendered inside that structure.
+
+**Does not own / non-goals**
+
+- The destination headings or their content — owned by the document or product
+  callsite.
+- Whether the Indicator track should gain a public target — unresolved by this
+  factual backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Outline.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                       | Basis                                                | Draft review state                                                                   |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| FR1 | The current render contains one Outline, one Heading link and Label per item, one Indicator track, and one Active indicator.              | Current source and docs; existing link/marker tests  | Verified by source; Label-wrapper and Indicator-track identity lack exact assertions |
+| FR2 | Outline, Heading link, and Active indicator carry `outline`, `outline-item`, and `outline-indicator`; Label inherits from `outline-item`. | Current source and target docs; current target tests | Current target facts verified; Label inheritance remains source-inspected            |
+| FR3 | Indicator track currently carries no public target.                                                                                       | Current source and target docs                       | Verified current behavior; theming intent unsettled                                  |
+
+### Allowed variation
+
+- Heading count, labels, levels, density, and active item may vary without
+  changing the five-part anatomy recorded here.
+
+### Representative states
+
+- Controlled and uncontrolled active state use the same anatomy and current
+  targets.
+- Default and compact density use the same anatomy and current targets.
+- An empty items array still renders Outline, Indicator track, and Active
+  indicator; it renders no Heading link or Label instances.
+
+### Transformation and precedence order
+
+- No new navigation, active-state, 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 Outline's existing navigation, link,
+current-item, or keyboard behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                  | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Outline          | Groups same-page heading navigation and the indicator presentation. | Current source and public docs | Supporting     | FR1, FR2           |
+| Heading link     | Navigates to one heading and carries level and active state.        | Current source and public docs | Prominent      | FR1, FR2           |
+| Label            | Presents heading text inside its Heading link.                      | Current source and public docs | Prominent      | FR1, FR2           |
+| Indicator track  | Paints the vertical rule behind the active marker.                  | Current source and public docs | Supporting     | FR1, FR3           |
+| Active indicator | Paints the marker aligned to the current Heading link.              | Current source and public docs | Supporting     | FR1, FR2           |
+
+The Label sits inside the `outline-item` target and receives the link's
+inherited text treatment. Its own StyleX rules only manage truncation. The
+Indicator track's target exposure remains unsettled; its current lack of a
+target does not decide that the part must remain unthemeable.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Outline": {"target": "outline"},
+  "Heading link": {"target": "outline-item"},
+  "Label": {"inherits": "outline-item"},
+  "Indicator track": {
+    "none": {
+      "reason": "unsettled: No current public target reaches this part"
+    }
+  },
+  "Active indicator": {"target": "outline-indicator"}
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+  mapping, inherited-part treatment, and explicit unsettled dispositions.
+
+## Verification map
+
+| Contract            | Verification                                             | Representative states                 | Mutation or failure expectation                                                                                                                                            | Audit section           |
+| ------------------- | -------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1                 | Source inspection plus existing link/indicator suites    | Populated and active outlines         | Heading links and the active indicator have regression assertions; Label-wrapper and Indicator-track identity remain source-inspected without exact regression assertions. | `audit:Outline/anatomy` |
+| FR2                 | `Outline.test.tsx` stable-target and active-state suites | Root, heading link, active indicator  | Removing or renaming a current target fails existing class assertions or target inventories.                                                                               | `audit:Outline/theming` |
+| FR3                 | Source inspection and current target inventories         | Indicator track                       | Adding or documenting a current track target without updating the map fails repository checks.                                                                             | `audit:Outline/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                            | Canonical anatomy and current targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                      | `audit:Outline/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or theming decision.
+
+## Open questions
+
+- **OQ1 — Should Indicator track gain a stable public theming target?**
+  (`human-api`) Target exposure is unsettled; the current lack of reachability
+  does not decide the answer.
+- **OQ2 — Add exact regression assertions for the Label wrapper and Indicator
+  track identity.** (`checkable`) Current evidence for those two parts is source
+  inspection rather than a uniquely identifying test assertion.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or system rules. It links to their owners.

package/src/OverflowList/OverflowList.doc.mjs

@@ -1,5 +1,26 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'List',
+    required: true,
+    description: 'Visible horizontal list container for the currently shown content.',
+  },
+  {
+    name: 'Items',
+    required: true,
+    description:
+      'Caller-supplied items selected for visible display by the current width and count limits.',
+  },
+  {
+    name: 'Overflow indicator',
+    required: false,
+    description:
+      'Optional caller-rendered indicator for items collapsed by width or count limits.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -106,6 +127,7 @@ export const docs = {
     targets: [{className: 'astryx-overflow-list'}],
   },
   usage: {
+    anatomy,
     description:
       'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
     bestPractices: [
@@ -209,6 +231,7 @@ export const docsZh = {
     },
   ],
   usage: {
+    anatomy,
     description:
       'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
     bestPractices: [
@@ -246,6 +269,7 @@ export const docsDense = {
   description:
     'horizontal list w/ overflow indicator: hides items beyond container width',
   usage: {
+    anatomy,
     description:
       'A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.',
     bestPractices: [