@astryxdesign/core 0.5.2-canary.457de8d → 0.5.2-canary.53353aa

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.5.2-canary.457de8d",
+  "version": "0.5.2-canary.53353aa",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -661,7 +661,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.5.2-canary.457de8d",
+    "@astryxdesign/cli": "0.5.2-canary.53353aa",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",

package/src/FieldStatus/FieldStatus.doc.mjs

@@ -1,5 +1,24 @@
 // 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',
@@ -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/theme/themingTargets.test.ts

@@ -3,8 +3,10 @@
 /* eslint-disable @typescript-eslint/no-require-imports */
 /**
  * @file Guards `theming.targets` against the real `themeProps()` call sites (#3741).
- * @input Component sources (*.tsx/*.ts) and their `{Name}.doc.mjs` files.
- * @output Vitest failures naming each undocumented class / visual prop.
+ * @input Core/Lab component sources (*.tsx/*.ts), their `{Name}.doc.mjs`
+ *   files, and the Lab promotion-candidate manifest.
+ * @output Vitest failures naming each undocumented class / visual prop on the
+ *   stable Core surface or a capability-participating Lab component.
  * @position Sibling of derivedVarRegistry.test.ts, which already validates the
  *   OTHER fields of the same `theming` block (`vars`, `derived`). `targets` was
  *   the one field with no machine check, so it drifted — twice (#3652, #3680).
@@ -22,6 +24,11 @@
  * `visualProps` or `states`. Docs may list MORE than the source passes —
  * components forward props they don't themselves reflect (Timestamp passes
  * `{format}` but documents `type`/`color`/`format`), and that is intentional.
+ *
+ * Lab is capability-based: a component participates when it already declares
+ * `theming.targets` or enters the existing promotion-candidate manifest. Other
+ * Lab components remain free to iterate with runtime hooks that are not yet a
+ * documented public theming promise.
  */
 
 import {describe, it, expect} from 'vitest';
@@ -30,7 +37,23 @@ import {join, relative} from 'node:path';
 import ts from 'typescript';
 import {stableClassName} from '../naming';
 
-const SRC_DIR = join(__dirname, '..');
+const CORE_SRC_DIR = join(__dirname, '..');
+const LAB_SRC_DIR = join(__dirname, '../../../lab/src');
+const LAB_PROMOTION_MANIFEST = join(
+  __dirname,
+  '../../../../internal/lab-readiness/manifest.mjs',
+);
+
+interface LabPromotionCandidate {
+  sourceDir: string;
+}
+
+const {CANDIDATES: labPromotionCandidates} = require(
+  LAB_PROMOTION_MANIFEST,
+) as {CANDIDATES: LabPromotionCandidate[]};
+const LAB_PROMOTION_DIRS = new Set(
+  labPromotionCandidates.map(candidate => candidate.sourceDir),
+);
 
 // ---------------------------------------------------------------------------
 // Source scanning: find themeProps() call sites via the TypeScript AST
@@ -314,6 +337,7 @@ type DocBlock = {theming?: {targets?: DocTarget[]}};
 type ComponentDocModule = {docs?: DocBlock; docsZh?: DocBlock};
 
 interface ComponentInfo {
+  packageName: 'core' | 'lab';
   dir: string;
   sites: ThemeTargetSite[];
   /** The doc blocks that carry theming.targets, by the key they live under. */
@@ -328,7 +352,10 @@ interface ComponentInfo {
  * Reads the file as text rather than requiring it: this runs for directories
  * that have no doc of their own, so most candidates are misses.
  */
-function docFilesDocumenting(classNames: Set<string>): string[] {
+function docFilesDocumenting(
+  srcDir: string,
+  classNames: Set<string>,
+): string[] {
   const matches: string[] = [];
   const walk = (dir: string): void => {
     for (const entry of readdirSync(dir, {withFileTypes: true})) {
@@ -346,18 +373,22 @@ function docFilesDocumenting(classNames: Set<string>): string[] {
       }
     }
   };
-  walk(SRC_DIR);
+  walk(srcDir);
   return matches;
 }
 
-function discoverComponents(): ComponentInfo[] {
+function discoverComponents(
+  srcDir: string,
+  packageName: ComponentInfo['packageName'],
+  requiredDirs: ReadonlySet<string> = new Set(),
+): ComponentInfo[] {
   const results: ComponentInfo[] = [];
-  const dirs = readdirSync(SRC_DIR, {withFileTypes: true})
+  const dirs = readdirSync(srcDir, {withFileTypes: true})
     .filter(d => d.isDirectory())
     .map(d => d.name);
 
   for (const dir of dirs) {
-    const dirPath = join(SRC_DIR, dir);
+    const dirPath = join(srcDir, dir);
     const dirEntries = readdirSync(dirPath);
 
     const sourceFiles = dirEntries.filter(
@@ -389,10 +420,7 @@ function discoverComponents(): ComponentInfo[] {
     // doc file that CI never checks. (Same guard as derivedVarRegistry.test.ts.)
     const docFiles = dirEntries.includes(`${dir}.doc.mjs`)
       ? [join(dirPath, `${dir}.doc.mjs`)]
-      : docFilesDocumenting(new Set(sites.map(s => s.className)));
-    if (docFiles.length === 0) {
-      continue;
-    }
+      : docFilesDocumenting(srcDir, new Set(sites.map(s => s.className)));
 
     const docBlocks: ComponentInfo['docBlocks'] = [];
     for (const docFile of docFiles) {
@@ -404,18 +432,23 @@ function discoverComponents(): ComponentInfo[] {
       }
       for (const key of ['docs', 'docsZh'] as const) {
         const targets = mod[key]?.theming?.targets;
-        // Only blocks that already document a theming surface are held to it —
-        // a doc with no theming block at all is a separate (documentation) gap.
+        // A normal Core or Lab component enrolls by declaring a theming
+        // surface. Promotion candidates are also enrolled here so a missing
+        // block is a failure rather than a silently skipped readiness gap.
         if (targets != null) {
-          docBlocks.push({key, file: relative(SRC_DIR, docFile), targets});
+          docBlocks.push({key, file: relative(srcDir, docFile), targets});
         }
       }
     }
-    if (docBlocks.length === 0) {
+    const participates =
+      packageName === 'core'
+        ? docBlocks.length > 0
+        : requiredDirs.has(dir) || docBlocks.length > 0;
+    if (!participates) {
       continue;
     }
 
-    results.push({dir, sites, docBlocks});
+    results.push({packageName, dir, sites, docBlocks});
   }
   return results;
 }
@@ -425,24 +458,57 @@ function discoverComponents(): ComponentInfo[] {
 // ---------------------------------------------------------------------------
 
 describe('theming.targets matches the themeProps() call sites', () => {
-  const components = discoverComponents();
+  const components = [
+    ...discoverComponents(CORE_SRC_DIR, 'core'),
+    ...discoverComponents(LAB_SRC_DIR, 'lab', LAB_PROMOTION_DIRS),
+  ];
+
+  it('finds participating Core and Lab components', () => {
+    // A refactor that renames themeProps or drops the Lab package from this
+    // inventory must not silently disable either side of the guard.
+    expect(components.some(component => component.packageName === 'core')).toBe(
+      true,
+    );
+    expect(components.some(component => component.packageName === 'lab')).toBe(
+      true,
+    );
+  });
 
-  it('finds components to check', () => {
-    // A refactor that renames themeProps must not silently disable this file.
-    expect(components.length).toBeGreaterThan(0);
+  it('enrolls every Lab promotion candidate and explicit theming capability', () => {
+    const labDirs = new Set(
+      components
+        .filter(component => component.packageName === 'lab')
+        .map(component => component.dir),
+    );
+    expect([...LAB_PROMOTION_DIRS].filter(dir => !labDirs.has(dir))).toEqual(
+      [],
+    );
+    expect(LAB_PROMOTION_DIRS.has('CircularProgress')).toBe(false);
+    expect(labDirs.has('CircularProgress')).toBe(true);
+    expect(labDirs.has('Schedule')).toBe(false);
   });
 
-  for (const {dir, sites, docBlocks} of components) {
+  for (const {packageName, dir, sites, docBlocks} of components) {
+    const componentLabel = `${packageName}/${dir}`;
     const renderedClasses = [...new Set(sites.map(s => s.className))].sort();
 
+    it(`${componentLabel}: participating components declare theming metadata`, () => {
+      expect(
+        docBlocks,
+        `${componentLabel} participates in the public theming contract but has ` +
+          `no loadable .doc.mjs theming.targets. Lab components participate ` +
+          `when they declare theming.targets or enter the promotion manifest.`,
+      ).not.toHaveLength(0);
+    });
+
     for (const {key, file, targets} of docBlocks) {
       const documented = new Set(targets.map(t => t.className));
 
-      it(`${dir} (${file} ${key}): every rendered class is documented`, () => {
+      it(`${componentLabel} (${file} ${key}): every rendered class is documented`, () => {
         const undocumented = renderedClasses.filter(c => !documented.has(c));
         expect(
           undocumented,
-          `${dir} renders ${undocumented.length} astryx-* class(es) that ` +
+          `${componentLabel} renders ${undocumented.length} astryx-* class(es) that ` +
             `${file} ${key}.theming.targets does not document: ` +
             `${undocumented.join(', ')}. An undocumented class is an ` +
             `unthemeable element — theme authors and codegen read targets[] ` +
@@ -450,7 +516,7 @@ describe('theming.targets matches the themeProps() call sites', () => {
         ).toEqual([]);
       });
 
-      it(`${dir} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {
+      it(`${componentLabel} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {
         const missing: string[] = [];
         for (const site of sites) {
           const target = targets.find(t => t.className === site.className);