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

package/src/Switch/Switch.spec.md

@@ -0,0 +1,174 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Switch
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/Switch/Switch.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Switch component contract
+
+## Intent
+
+Switch presents a labeled boolean control whose change takes effect immediately.
+This draft records current consumer anatomy and theming ownership 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, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged; Switch remains controlled
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The switch field, track, thumb, and label presentations represented by the
+  existing `switch-field`, `switch`, `switch-thumb`, and `switch-label` targets.
+
+**Does not own / non-goals**
+
+- Description styling through a dedicated public target; none currently exists.
+- Validation-message presentation — owned by `component:FieldStatus`.
+- Loading-indicator presentation — owned by `component:Spinner`.
+- Tooltip surfaces used for shared label and disabled-reason behavior.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, states, and usage remain
+documented in `Switch.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                    | Basis                                   | Draft review state                                 |
+| --- | ------------------------------------------------------------------------------------------------------ | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places a thumb inside the switch track and arranges that control with its label.    | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | The field, track, thumb, and label carry their existing local targets.                                 | Current source, public docs, and tests  | Verified current behavior; no target change        |
+| FR3 | A busy switch renders Spinner inside the thumb; a status message renders through detached FieldStatus. | Current source, docs, and focused tests | Verified conditional composition                   |
+
+### Allowed variation
+
+- Label position and spacing, size, checked state, and disabled state remain
+  current target capabilities rather than separate anatomy parts.
+- A description may be absent without changing the remaining anatomy.
+
+### Representative states
+
+| State               | Required invariant                                      | Allowed variation                      |
+| ------------------- | ------------------------------------------------------- | -------------------------------------- |
+| Off or on           | Track, thumb, and label render within the switch field. | Checked state, size, label placement   |
+| Busy                | Spinner renders inside the thumb.                       | Controlled or optimistic checked value |
+| Status with message | Detached FieldStatus follows the switch row.            | Error, warning, or success status      |
+
+### Transformation and precedence order
+
+- No new state, event, layout, or styling precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Switch's existing accessible name, switch
+role, checked state, busy state, description/status association, or disabled
+behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                       | Representation authority        | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |
+| Field            | Arranges the switch control with its label and feedback. | Current source and public docs  | Supporting     | FR1, FR2           |
+| Track and thumb  | Present the current on/off control.                      | Current source and public docs  | Prominent      | FR1, FR2           |
+| Label            | Identifies the controlled setting.                       | Current source and public docs  | Prominent      | FR1, FR2           |
+| Spinner/status   | Present conditional progress and validation feedback.    | Current shared-component source | Supporting     | FR3                |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Field": {"target": "switch-field"},
+  "Track": {"target": "switch"},
+  "Thumb": {"target": "switch-thumb"},
+  "Label": {"target": "switch-label"},
+  "Description": {
+    "none": {
+      "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
+    }
+  },
+  "Spinner": {
+    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
+  },
+  "Status message": {
+    "delegatesTo": {
+      "owner": "component:FieldStatus",
+      "target": "field-status"
+    }
+  }
+}
+```
+
+`Description` remains stable consumer anatomy, but no current public target
+reaches it. The map classifies future exposure as unsettled rather than silently
+making the absence intentional.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, factual
+  `none` dispositions, and composition-preserving target ownership.
+- FieldStatus and Spinner retain their existing public target contracts when
+  composed by Switch.
+
+## Verification map
+
+| Contract            | Verification                                                      | Representative states                      | Mutation or failure expectation                                                                                                 | Audit section          |
+| ------------------- | ----------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR1                 | `Switch.test.tsx` structure and interaction suites                | On/off, size, label position, hidden label | Removing or reordering stable parts breaks existing role, label, or DOM assertions.                                             | `audit:Switch/anatomy` |
+| FR2                 | `Switch.test.tsx` label-target suite and `themingTargets.test.ts` | Current local targets                      | Removing the label target fails focused coverage; source/docs drift fails the target guard.                                     | `audit:Switch/theming` |
+| FR3                 | `Switch.test.tsx` loading and status suites                       | Busy and detached status                   | Removing composed feedback breaks existing spinner, busy-state, or message assertions.                                          | `audit:Switch/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                     | Canonical anatomy and all current targets  | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:Switch/theming` |
+
+The focused Switch suite pins `switch-label`, but does not separately assert the
+exact `switch-field`, `switch`, or `switch-thumb` class placement. The
+source/metadata target guard covers those local declarations. No current
+repository check resolves `delegatesTo` owner/target pairs; the pairs in this
+draft were verified manually, so semantic delegation drift remains a validation
+gap.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, or shared-component contracts. It links to their owners.

package/src/Text/Text.doc.mjs

@@ -1,12 +1,44 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Text',
+    required: true,
+    description:
+      'Polymorphic text element that renders the supplied content with themed typography.',
+  },
+  {
+    name: 'Heading',
+    required: false,
+    description:
+      'Referenced Heading member that renders the supplied content as a semantic h1–h6 element.',
+  },
+  {
+    name: 'Truncation tooltip',
+    required: false,
+    description:
+      'Tooltip-owned surface available only when Text or Heading is measured as truncated and truncation tooltips are enabled.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Text',
   displayName: 'Text',
   category: 'Content',
-  keywords: ["text","typography","label","paragraph","heading","caption","font","body","subtitle"],
+  keywords: [
+    'text',
+    'typography',
+    'label',
+    'paragraph',
+    'heading',
+    'caption',
+    'font',
+    'body',
+    'subtitle',
+  ],
   playground: {
     defaults: {
       children: 'The quick brown fox jumps over the lazy dog.',
@@ -19,12 +51,14 @@ export const docs = {
       {className: 'astryx-text', visualProps: ['type', 'size', 'color']},
     ],
   },
-  description: 'Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.',
+  description:
+    'Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.',
   props: [
     {
       name: 'type',
       type: "'body' | 'large' | 'label' | 'supporting' | 'code' | 'display-1' | 'display-2' | 'display-3' | 'inherit'",
-      description: "Semantic text type. Determines size, weight, and line-height from the theme. 'inherit' takes all three from the surrounding text instead. Themes may add custom types. Note: this prop is called `type`, not `variant`.",
+      description:
+        "Semantic text type. Determines size, weight, and line-height from the theme. 'inherit' takes all three from the surrounding text instead. Themes may add custom types. Note: this prop is called `type`, not `variant`.",
       default: "'body'",
     },
     {
@@ -36,12 +70,14 @@ export const docs = {
     {
       name: 'size',
       type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
-      description: 'Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone.',
+      description:
+        'Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone.',
     },
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
-      description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others. Themes may add custom colors.",
+      description:
+        "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others. Themes may add custom colors.",
     },
     {
       name: 'weight',
@@ -51,7 +87,8 @@ export const docs = {
     {
       name: 'display',
       type: "'inline' | 'block'",
-      description: "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",
+      description:
+        "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",
       default: "'inline'",
     },
     {
@@ -63,19 +100,22 @@ export const docs = {
     {
       name: 'maxLines',
       type: 'number',
-      description: 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',
+      description:
+        'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',
       default: '0',
     },
     {
       name: 'hasTruncateTooltip',
       type: "boolean | 'above' | 'below' | 'start' | 'end'",
-      description: "Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a placement string ('above' | 'below' | 'start' | 'end') sets a specific position.",
+      description:
+        "Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a placement string ('above' | 'below' | 'start' | 'end') sets a specific position.",
       default: 'true',
     },
     {
       name: 'wordBreak',
       type: "'break-word' | 'break-all'",
-      description: "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
+      description:
+        "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
     },
     {
       name: 'textWrap',
@@ -85,13 +125,15 @@ export const docs = {
     {
       name: 'justify',
       type: "'start' | 'center' | 'end'",
-      description: 'Text alignment (justification). Uses logical values (start/end) for i18n/RTL compatibility.',
+      description:
+        'Text alignment (justification). Uses logical values (start/end) for i18n/RTL compatibility.',
       default: "'start'",
     },
     {
       name: 'hasCapsize',
       type: 'boolean',
-      description: 'Enable optical alignment using text-box-trim. Forces block display.',
+      description:
+        'Enable optical alignment using text-box-trim. Forces block display.',
       default: 'false',
     },
     {
@@ -114,25 +156,61 @@ export const docs = {
     {
       name: 'xstyle',
       type: 'StyleXStyles',
-      description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
+      description:
+        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
     },
   ],
-  components: [
-    {name: 'Heading'},
-  ],
+  components: [{name: 'Heading'}],
   usage: {
+    anatomy,
     description:
       'Text renders styled body text and headings from the theme. Use Text with a semantic type for body copy, labels, and captions, and Heading for section titles that output the correct h1\u2013h6 element.',
     bestPractices: [
-      { guidance: true, description: 'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.' },
-      { guidance: true, description: 'Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.' },
-      { guidance: true, description: 'Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.' },
-      { guidance: true, description: 'Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.' },
-      { guidance: false, description: 'Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.' },
-      { guidance: false, description: 'Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.' },
-      { guidance: false, description: 'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.' },
-      { guidance: false, description: 'Pass a `variant` prop; Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.' },
-      { guidance: false, description: 'Use Text for headings; use Heading with a `level` prop (1\u20136) for section titles and headings.' },
+      {
+        guidance: true,
+        description:
+          'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.',
+      },
+      {
+        guidance: true,
+        description:
+          'Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.',
+      },
+      {
+        guidance: false,
+        description:
+          'Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.',
+      },
+      {
+        guidance: false,
+        description:
+          'Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.',
+      },
+      {
+        guidance: false,
+        description:
+          'Pass a `variant` prop; Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Text for headings; use Heading with a `level` prop (1\u20136) for section titles and headings.',
+      },
     ],
   },
 };
@@ -143,35 +221,104 @@ export const docsZh = {
     description:
       'Text renders styled body text and headings from the theme. Use Text with a semantic type for body copy, labels, and captions, and Heading for section titles that output the correct h1\u2013h6 element.',
     bestPractices: [
-      { guidance: true, description: 'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.' },
-      { guidance: true, description: 'Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.' },
-      { guidance: true, description: 'Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.' },
-      { guidance: true, description: 'Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.' },
-      { guidance: false, description: 'Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.' },
-      { guidance: false, description: 'Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.' },
-      { guidance: false, description: 'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.' },
-      { guidance: false, description: 'Pass a `variant` prop; Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.' },
-      { guidance: false, description: 'Use Text for headings; use Heading with a `level` prop (1\u20136) for section titles and headings.' },
+      {
+        guidance: true,
+        description:
+          'Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight; the theme handles the details.',
+      },
+      {
+        guidance: true,
+        description:
+          'Set accessibilityLevel on Heading when the visual level differs from the document outline so screen readers announce the correct hierarchy.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use maxLines with a number to truncate long content; a tooltip appears automatically on hover so no text is lost.',
+      },
+      {
+        guidance: true,
+        description:
+          'Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows.',
+      },
+      {
+        guidance: false,
+        description:
+          'Override size and weight when a semantic type already matches; extra overrides fight the theme and break when themes change.',
+      },
+      {
+        guidance: false,
+        description:
+          'Skip heading levels in the document outline; go h1 then h2 then h3, never h1 then h3.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use raw HTML tags like <p>, <h1>\u2013<h6>, or <span> for text; Text and Heading apply the correct theme tokens automatically.',
+      },
+      {
+        guidance: false,
+        description:
+          'Pass a `variant` prop; Text does not have a `variant` prop. Use `type` for semantic styling (body, label, large, supporting, code) or use Heading for headings.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Text for headings; use Heading with a `level` prop (1\u20136) for section titles and headings.',
+      },
     ],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'semantic body text + headings w/ theme-driven type scale, truncation, tabular numbers',
+  description:
+    'semantic body text + headings w/ theme-driven type scale, truncation, tabular numbers',
   usage: {
     description:
       'Text renders styled body text and headings. Text for body copy with semantic types, Heading for h1\u2013h6 with theme tokens.',
     bestPractices: [
-      { guidance: true, description: 'Semantic type (body, label, supporting, large, code) instead of manual size/weight.' },
-      { guidance: true, description: 'accessibilityLevel on Heading when visual level differs from document outline.' },
-      { guidance: true, description: 'maxLines for truncation; tooltip shows full text on hover.' },
-      { guidance: true, description: 'hasTabularNumbers for aligned numeric columns.' },
-      { guidance: false, description: 'Override size/weight when a semantic type already matches.' },
-      { guidance: false, description: 'Skip heading levels; sequential h1 \u2192 h2 \u2192 h3.' },
-      { guidance: false, description: 'Raw <p>/<h1>/<span>; use Text/Heading for theme tokens.' },
-      { guidance: false, description: '`variant` prop, which does not exist. Use `type` for text styling or Heading for headings.' },
-      { guidance: false, description: 'Text for headings: use Heading with level (1\u20136).' },
+      {
+        guidance: true,
+        description:
+          'Semantic type (body, label, supporting, large, code) instead of manual size/weight.',
+      },
+      {
+        guidance: true,
+        description:
+          'accessibilityLevel on Heading when visual level differs from document outline.',
+      },
+      {
+        guidance: true,
+        description:
+          'maxLines for truncation; tooltip shows full text on hover.',
+      },
+      {
+        guidance: true,
+        description: 'hasTabularNumbers for aligned numeric columns.',
+      },
+      {
+        guidance: false,
+        description:
+          'Override size/weight when a semantic type already matches.',
+      },
+      {
+        guidance: false,
+        description: 'Skip heading levels; sequential h1 \u2192 h2 \u2192 h3.',
+      },
+      {
+        guidance: false,
+        description: 'Raw <p>/<h1>/<span>; use Text/Heading for theme tokens.',
+      },
+      {
+        guidance: false,
+        description:
+          '`variant` prop, which does not exist. Use `type` for text styling or Heading for headings.',
+      },
+      {
+        guidance: false,
+        description: 'Text for headings: use Heading with level (1\u20136).',
+      },
     ],
   },
 };