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

package/src/FieldStatus/FieldStatus.doc.mjs

@@ -1,11 +1,30 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Message box',
+    required: true,
+    description: 'Painted container for the validation feedback.',
+  },
+  {
+    name: 'Detached icon',
+    required: false,
+    description: 'Leading status glyph shown only by the detached variant.',
+  },
+  {
+    name: 'Message text',
+    required: true,
+    description: 'Text describing the validation status.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docs = {
   name: 'FieldStatus',
   displayName: 'Field Status',
   group: 'Field',
-  category: 'Data Input',
+  category: 'Form Controls',
   isHiddenFromOverview: true,
   description:
     'Status message component for form field validation feedback. Messages are announced to screen readers through persistent live regions (assertive for errors, polite otherwise), so conditional mounting is safe.',
@@ -61,6 +80,7 @@ export const docs = {
           'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.',
       },
     ],
+    anatomy,
   },
 };
 
@@ -86,6 +106,7 @@ export const docsDense = {
           'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.',
       },
     ],
+    anatomy,
   },
   propDescriptions: {
     type: 'error/warning/success status tone',

package/src/FieldStatus/FieldStatus.spec.md

@@ -0,0 +1,212 @@
+---
+schema_version: 1
+template_version: 1
+kind: component
+id: component:FieldStatus
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-30
+owners: [cixzhang, imdreamrunner]
+review_triggers: [public-api, behavior, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/FieldStatus/FieldStatus.test.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# FieldStatus component contract
+
+## Intent
+
+FieldStatus presents one validation message for a field or field-like control. It
+owns the visible message treatment and announcement behavior for attached and
+detached presentations; consumer usage remains documented in
+`FieldStatus.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling, and
+  public API remain unchanged
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: direct `FieldStatus variant="tooltip"` support is rejected.
+  `tooltip` remains a field-family sentinel that MUST be handled before rendering
+  FieldStatus. Narrowing the currently permissive type/runtime path requires a
+  separate compatibility-aware implementation change.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The attached and detached validation-message presentations.
+- Routing visible messages through the persistent announcement channels.
+- The detached presentation's redundant visual status glyph.
+
+**Does not own / non-goals**
+
+- Whether a caller renders a status message, or which control it describes —
+  owned by the composing field component or product callsite.
+- The bordered control's status treatment and on-field tooltip presentation —
+  owned by the composing field component.
+- General alerts and page-level notices — owned by the corresponding feedback
+  components.
+
+## Public concepts
+
+| Concept      | Closed values or states       | Meaning                                            | Availability by variant/orientation/state                                                                  | Default    | Owner                   | Stability | Invalid-value behavior                                                                                                          |
+| ------------ | ----------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------- | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Status type  | `error`, `warning`, `success` | Selects the message tone and announcement channel. | All rendered presentations.                                                                                | Required   | `component:FieldStatus` | Stable    | TypeScript rejects unsupported values.                                                                                          |
+| Presentation | `attached`, `detached`        | Selects the message presentation.                  | All direct FieldStatus usage. The field family's `tooltip` sentinel is handled before FieldStatus renders. | `attached` | `component:FieldStatus` | Stable.   | TypeScript rejects values absent from the extensible variant map; its current acceptance of `tooltip` is an implementation gap. |
+
+The field family's `tooltip` status presentation suppresses FieldStatus and
+surfaces the message from the control's on-field icon. `tooltip` is not a
+FieldStatus presentation. The public extensible variant map currently permits a
+direct `tooltip` value; that is an implementation gap, not supported behavior.
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                        | Basis                                               | Draft review state                                      |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------- |
+| FR1 | FieldStatus MUST render the provided message in one visible message box when mounted.                                                                      | Documented promise and current tests.               | Settled intent.                                         |
+| FR2 | The attached presentation MUST render the message without a leading glyph; the detached presentation MUST render its status glyph before the message text. | Documented promise, current DOM, and current tests. | Settled intent.                                         |
+| FR3 | Status type MUST select distinct error, warning, or success treatment and MUST be reflected on the message-box target.                                     | Current behavior and theming tests.                 | Settled intent.                                         |
+| FR4 | The detached glyph MUST reflect status type on its own target; the target MUST be absent from attached presentation.                                       | Current behavior and target tests.                  | Settled intent.                                         |
+| FR5 | The root MUST continue to forward its ref, ID, supported DOM props, and consumer styling escape hatches.                                                   | Current behavior and tests.                         | Current compatibility behavior; verify before changing. |
+| FR6 | Message and status-type updates MUST update the visible output without replacing the component contract.                                                   | Current behavior and tests.                         | Current compatibility behavior; verify before changing. |
+| FR7 | Direct FieldStatus usage MUST support only `attached` and `detached`; the Field family MUST consume its `tooltip` sentinel before rendering FieldStatus.   | Approved component boundary.                        | Settled intent; current type acceptance is a gap.       |
+
+### Allowed variation
+
+- **AV1 — Theme styling.** Theme and consumer overrides may change visual CSS
+  properties through the existing targets and styling escape hatches without
+  changing anatomy, ownership, or presentation behavior.
+- **AV2 — Message length.** The message may wrap; the detached glyph remains
+  aligned with the first text line.
+
+### Representative states
+
+| State            | Required invariant                                             | Allowed variation                                           |
+| ---------------- | -------------------------------------------------------------- | ----------------------------------------------------------- |
+| Attached error   | Message box and text render; no detached glyph renders.        | Theme-controlled visual properties on `field-status`.       |
+| Detached warning | Message box, leading warning glyph, then message text render.  | Theme-controlled visual properties on both current targets. |
+| Detached success | Message box, leading success glyph, then message text render.  | Message length and theme-controlled visual properties.      |
+| Empty message    | The root remains mounted and renders the provided empty value. | No announcement channel is created.                         |
+
+### Transformation and precedence order
+
+- **ORD1 — Presentation styling.** Resolve the default presentation, reflect
+  status and presentation through `themeProps`, apply component styles, then
+  merge `xstyle`, `className`, and inline `style` in their established order.
+- **ORD2 — Detached content.** Render the decorative status glyph before the
+  message text, using the same status-to-glyph mapping as field controls.
+
+### Performance and resources
+
+- **PR1 — Announcement work.** A message change schedules only the persistent
+  live-region announcement; FieldStatus owns no global event listeners,
+  observers, or measurements.
+
+## Accessibility contract
+
+- **AR1 — Announcement channel.** Errors MUST announce through the persistent
+  assertive region; warnings and successes MUST announce through the persistent
+  polite region, including on first mount and when message or type changes.
+- **AR2 — Visible description.** The rendered message box MUST remain available
+  to assistive technology for `aria-describedby` association and MUST NOT become
+  its own newly mounted live region.
+- **AR3 — Non-color cue.** Detached status MUST include a leading status glyph so
+  status is not conveyed only by color or position.
+- **AR4 — Redundant glyph.** The detached glyph MUST remain hidden from assistive
+  technology because the visible message already conveys and announces the
+  status.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                         | Representation authority                        | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------- | ----------------------------------------------- | -------------- | ------------------ |
+| Message box      | Carries the visible validation treatment.                  | Current behavior and approved component intent. | Supporting     | FR1, FR3           |
+| Detached icon    | Adds a non-color status cue only in detached presentation. | Current behavior and approved component intent. | Supporting     | FR2, FR4, AR3      |
+| Message text     | Communicates the validation result in words.               | Current behavior and approved component intent. | Prominent      | FR1, AR1, AR2      |
+
+Current behavior renders the detached icon before message text. The intended
+public theming ownership is the exact map below; it does not add a target or
+change either presentation.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Message box": {"target": "field-status"},
+  "Detached icon": {"target": "field-status-icon"},
+  "Message text": {"inherits": "field-status"}
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns the qualification and validation
+  rules for the two targets and inherited message text.
+- Field-like controls compose FieldStatus but continue to own control rendering,
+  status placement decisions, and association with the control.
+
+## Verification map
+
+| Contract            | Verification                                              | Representative states                             | Mutation or failure expectation                                                         | Audit section                     |
+| ------------------- | --------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1, FR2, AR3, AR4  | `FieldStatus.test.tsx` rendering and detached-icon suites | Attached and detached; all status types           | Removing or reordering presentation parts fails DOM and accessibility assertions.       | `audit:FieldStatus/anatomy`       |
+| FR3, FR4            | `FieldStatus.test.tsx` theme target suites                | Attached/detached; error/warning/success          | Removing a target or status reflection fails class/data-attribute assertions.           | `audit:FieldStatus/theming`       |
+| FR5, FR6            | `FieldStatus.test.tsx` forwarding and update suites       | Initial render and rerender                       | Breaking the released root or update behavior fails compatibility assertions.           | `audit:FieldStatus/behavior`      |
+| AR1, AR2            | `FieldStatus.test.tsx` announcement suites                | Mount, message update, type update, empty message | Reintroducing a local live region or misrouting severity fails announcement assertions. | `audit:FieldStatus/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                             | Consumer anatomy and current targets              | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.     | `audit:FieldStatus/theming`       |
+
+## Decision log
+
+### DEC-1 — Presentation-specific anatomy remains explicit
+
+**Reference:** `component:FieldStatus/DEC-1`
+**Decider:** cixzhang, 2026-08-30
+
+The detached icon is a separate anatomy part because only detached presentation
+renders it and it owns a target distinct from the message box. Message text
+inherits the message-box target rather than creating a redundant child target.
+
+Rejected: collapsing the glyph into a generic message row, which would hide its
+presentation condition and distinct theming owner.
+
+### DEC-2 — `tooltip` is not a FieldStatus presentation
+
+**Reference:** `component:FieldStatus/DEC-2`
+**Decider:** cixzhang, 2026-08-30
+
+Direct FieldStatus usage supports only `attached` and `detached`. The Field
+family may use `tooltip` as an internal presentation sentinel, but it MUST
+consume that value before rendering FieldStatus and surface the message through
+the control's on-field status treatment instead.
+
+Rejected: defining direct `FieldStatus variant="tooltip"` rendering semantics.
+That would expose a field-composition mechanism as a third FieldStatus
+presentation and preserve currently unintentional output.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop examples, current audit results,
+implementation steps, or family/system rules. It links to their owners.

package/src/FileInput/FileInput.doc.mjs

@@ -5,7 +5,7 @@
 export const docs = {
   name: 'FileInput',
   displayName: 'File Input',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: ["fileinput","file","upload","drag","drop","dropzone","attachment","browse"],
   props: [
     {

package/src/Grid/Grid.doc.mjs

@@ -1,5 +1,21 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Grid container',
+    required: true,
+    description:
+      'Two-dimensional layout container that arranges caller-supplied items in rows and columns.',
+  },
+  {
+    name: 'Spanning item',
+    required: false,
+    description:
+      "Optional GridSpan wrapper that changes one item's column or row participation.",
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -9,6 +25,7 @@ export const docs = {
   category: 'Layout',
   keywords: ["grid","columns","responsive","auto-fill","auto-fit","masonry","tiles","row","col","simplegrid","responsive grid","card grid"],
   usage: {
+    anatomy,
     description:
       'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',
     bestPractices: [
@@ -99,6 +116,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
+    anatomy,
     description:
       'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',
     bestPractices: [
@@ -116,6 +134,7 @@ export const docsZh = {
 export const docsDense = {
   description: 'CSS Grid-based layout w/ responsive column support.',
   usage: {
+    anatomy,
     description: 'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',
     bestPractices: [
       { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size: columns={{minWidth: 280}}.' },

package/src/Grid/Grid.spec.md

@@ -0,0 +1,161 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Grid
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [layout, theming]
+verified_by:
+  [
+    packages/core/src/Grid/Grid.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:layout-primitives]
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: []
+---
+
+# Grid component contract
+
+## Intent
+
+Grid arranges caller-supplied items in two-dimensional tracks. GridSpan
+optionally wraps one item to control its row or column participation. This draft
+records the current consumer anatomy and theming ownership without changing
+layout, 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: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The Grid container and its current `grid` theming target.
+- The optional GridSpan wrapper and its current `grid-span` theming target.
+- Grid track construction and GridSpan row/column participation.
+
+**Does not own / non-goals**
+
+- Content supplied to Grid or GridSpan — owned by the caller.
+- Structural page-region or surface semantics.
+- New responsive behavior, layout props, targets, or target placement.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in the canonical `Grid.doc.mjs` and the subordinate `GridSpan.doc.mjs`;
+`family:layout-primitives` owns the shared composition vocabulary.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                           | Basis                                   | Draft review state                                 |
+| --- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| FR1 | Grid renders one Grid container carrying the current `grid` target and arranges caller content using the current track model. | Current source, docs, tests, and family | Verified current behavior; no new behavior decided |
+| FR2 | GridSpan renders one optional Spanning item wrapper carrying the current `grid-span` target.                                  | Current source, docs, and tests         | Verified current behavior; no target change        |
+| FR3 | GridSpan's current `columns` and `rows` inputs affect only the wrapped item's participation in its parent grid.               | Current source, tests, and family       | Verified current behavior; no layout change        |
+
+### Allowed variation
+
+- Grid may use fixed or intrinsic responsive tracks without changing Grid
+  container ownership.
+- Caller content may render directly in Grid or inside optional GridSpan wrappers.
+- A Spanning item may span columns, rows, both, or neither while retaining the
+  same target.
+
+### Representative states
+
+| State          | Required invariant                                        | Allowed variation                                     |
+| -------------- | --------------------------------------------------------- | ----------------------------------------------------- |
+| Fixed Grid     | Grid container owns the current `grid` target.            | Positive fixed column count and spacing may vary.     |
+| Intrinsic Grid | The same container owns responsive track construction.    | Fill/fit mode, minimum width, and count cap may vary. |
+| Direct item    | Caller content participates without a Grid-owned wrapper. | Caller owns its element and styling.                  |
+| Spanning item  | GridSpan owns one wrapper and the `grid-span` target.     | Column and row span values may vary.                  |
+
+### Transformation and precedence order
+
+- No new track construction, gap, alignment, sizing, or span precedence rule is
+  introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not add semantic roles to Grid or GridSpan or change their
+current DOM forwarding and caller-owned content semantics.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                 | Representation authority                  | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------ | ----------------------------------------- | -------------- | ------------------ |
+| Grid container   | Presents the current two-dimensional layout container.             | Current source, docs, and family contract | Supporting     | FR1                |
+| Spanning item    | Optionally changes one item's row or column participation in Grid. | Current source, docs, and family contract | Supporting     | FR2, FR3           |
+
+Direct caller content is not an additional Grid-owned anatomy part.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Grid container": {"target": "grid"},
+  "Spanning item": {"target": "grid-span"}
+}
+```
+
+## Family and system relationships
+
+- `family:layout-primitives` owns the shared spacing, sizing, alignment, and item
+  participation vocabulary for Grid and GridSpan.
+- `architecture:component-theming-surface` owns anatomy qualification and the
+  two current local target mappings.
+- `architecture:public-component-api` owns the stable prop surface; this
+  documentation adds no API.
+
+## Verification map
+
+| Contract            | Verification                                                 | Representative states                        | Mutation or failure expectation                                                                                              | Audit section            |
+| ------------------- | ------------------------------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1                 | `Grid.test.tsx` track, sizing, alignment, and content suites | Fixed, default, fill, fit, capped, and sized | Changing current track output or removing the container/content fails exact style-variable, inline-style, or content checks. | `audit:Grid/anatomy`     |
+| FR2, FR3            | `Grid.test.tsx` GridSpan suites                              | Column, full-row, row, combined, and no span | Changing wrapper rendering or span values fails exact inline-style and content assertions.                                   | `audit:GridSpan/anatomy` |
+| Target inventory    | Source inspection and `themingTargets.test.ts`               | Grid and GridSpan targets                    | Runtime and documented target metadata drift fails target validation.                                                        | `audit:Grid/theming`     |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                | Canonical anatomy and both current targets   | Missing, extra, prefixed, or stale mappings fail repository validation.                                                      | `audit:Grid/theming`     |
+
+Grid tests pin track and span output, content rendering, and prop forwarding.
+They do not assert both target classes in focused component tests; target
+placement is source-inspected and the global inventory checks the runtime/docs
+relationship.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+layout, accessibility, or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, family layout
+rules, track algorithms, implementation steps, or system rules. It links to
+their owners.