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

package/src/Skeleton/Skeleton.doc.mjs

@@ -1,5 +1,14 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Placeholder',
+    required: true,
+    description: 'Painted shape that stands in for content while it loads.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -49,6 +58,7 @@ export const docs = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'An animated shimmer placeholder that previews the shape of content while it loads. Use it to build loading screens that match the layout of the real content. For content with unknown dimensions, use Spinner instead.',
     bestPractices: [
@@ -98,6 +108,7 @@ export const docsZh = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'An animated shimmer placeholder that previews the shape of content while it loads. Use it to build loading screens that match the layout of the real content. For content with unknown dimensions, use Spinner instead.',
     bestPractices: [
@@ -113,6 +124,7 @@ export const docsZh = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
+    anatomy,
     description:
       'An animated shimmer placeholder that previews the shape of content while it loads. Use it to build loading screens that match the layout of the real content. For content with unknown dimensions, use Spinner instead.',
     bestPractices: [

package/src/Skeleton/Skeleton.spec.md

@@ -0,0 +1,126 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Skeleton
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [packages/core/src/Skeleton/Skeleton.test.tsx, scripts/check-knowledge.mjs]
+families: []
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: []
+---
+
+# Skeleton component contract
+
+## Intent
+
+Skeleton renders a placeholder shape while surrounding content loads. This draft
+records the component's current consumer anatomy and theming ownership without
+changing its runtime contract.
+
+## 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 rendered placeholder shape and its existing `skeleton` theming target.
+
+**Does not own / non-goals**
+
+- The surrounding content's loading state, layout, or replacement timing — owned
+  by the product callsite.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Skeleton.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                 | Basis                           | Draft review state                                 |
+| --- | ----------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current render contains one painted placeholder carrying the `skeleton` target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+
+### Allowed variation
+
+- This documentation does not constrain behavior beyond the factual anatomy and
+  target relationship recorded here.
+
+### Representative states
+
+- The anatomy and target relationship is the same for the documented size,
+  radius, and animation inputs.
+
+### Transformation and precedence order
+
+- No new ordering rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Skeleton's existing accessibility behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                         | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------ | ------------------------------ | -------------- | ------------------ |
+| Placeholder      | Represents the current painted loading UI. | Current source and public docs | Supporting     | FR1                |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Placeholder": {"target": "skeleton"}
+}
+```
+
+## Family and system relationships
+
+This draft references the current shared owners without restating their rules:
+`architecture:component-theming-surface` and
+`architecture:public-component-api`.
+
+## Verification map
+
+| Contract            | Verification                     | Representative states                | Mutation or failure expectation                                         | Audit section            |
+| ------------------- | -------------------------------- | ------------------------------------ | ----------------------------------------------------------------------- | ------------------------ |
+| FR1                 | `Skeleton.test.tsx` render suite | A rendered placeholder               | Removing the placeholder fails the existing render assertion.           | `audit:Skeleton/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`    | Canonical anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Skeleton/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, or system rules. It links to their owners.

package/src/Slider/Slider.doc.mjs

@@ -1,12 +1,86 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Label',
+    required: true,
+    description:
+      'Text identifying the numeric setting controlled by the slider.',
+  },
+  {
+    name: 'Description',
+    required: false,
+    description: 'Helper text between the label and the slider control.',
+  },
+  {
+    name: 'Slider',
+    required: true,
+    description:
+      'Control row containing the track, thumb or thumbs, and optional text value.',
+  },
+  {
+    name: 'Track',
+    required: true,
+    description: 'Background rail representing the available numeric range.',
+  },
+  {
+    name: 'Filled range',
+    required: true,
+    description:
+      'Accent segment from the minimum to a single value, or between two range values.',
+  },
+  {
+    name: 'Tick mark',
+    required: false,
+    description: 'Position marker supplied through the marks collection.',
+  },
+  {
+    name: 'Mark label',
+    required: false,
+    description: 'Optional text displayed beside a tick mark.',
+  },
+  {
+    name: 'Thumb',
+    required: true,
+    description:
+      'Draggable value indicator; range mode renders a minimum and maximum thumb.',
+  },
+  {
+    name: 'Value display',
+    required: false,
+    description:
+      'Formatted current value shown beside the slider when valueDisplay is text.',
+  },
+  {
+    name: 'Value tooltip',
+    required: false,
+    description:
+      'Formatted current value shown in a tooltip when valueDisplay is tooltip.',
+  },
+  {
+    name: 'Status message',
+    required: false,
+    description: 'Error, warning, or success message below the slider.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Slider',
   displayName: 'Slider',
-  category: 'Data Input',
-  keywords: ["slider","range","slidebar","trackbar","scrubber","knob","thumb","rangeslider"],
+  category: 'Form Controls',
+  keywords: [
+    'slider',
+    'range',
+    'slidebar',
+    'trackbar',
+    'scrubber',
+    'knob',
+    'thumb',
+    'rangeslider',
+  ],
   playground: {
     defaults: {
       label: 'Volume',
@@ -156,20 +230,49 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-slider', visualProps: ['orientation'], states: ['disabled']},
+      {
+        className: 'astryx-slider',
+        visualProps: ['orientation'],
+        states: ['disabled'],
+      },
       {className: 'astryx-slider-track', visualProps: ['orientation']},
-      {className: 'astryx-slider-thumb', visualProps: ['orientation'], states: ['disabled']},
+      {
+        className: 'astryx-slider-thumb',
+        visualProps: ['orientation'],
+        states: ['disabled'],
+      },
     ],
   },
   usage: {
+    anatomy,
     description:
       'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
     bestPractices: [
-      {guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
-      {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
-      {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
-      {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
-      {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
+      {
+        guidance: true,
+        description:
+          'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.',
+      },
+      {
+        guidance: true,
+        description:
+          'Format values with meaningful units like "$50" or "75%" instead of raw numbers.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for precise numeric entry; pair with a text input or use NumberInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };
@@ -229,8 +332,7 @@ export const docsZh = {
     {
       name: 'formatValue',
       type: '(value: number) => string',
-      description:
-        '自定义值格式化函数，用于显示和 `aria-valuetext`。',
+      description: '自定义值格式化函数，用于显示和 `aria-valuetext`。',
     },
     {
       name: 'valueDisplay',
@@ -246,8 +348,7 @@ export const docsZh = {
     {
       name: 'minStepsBetweenThumbs',
       type: 'number',
-      description:
-        '范围模式下滑块之间的最小步数；防止滑块重叠。',
+      description: '范围模式下滑块之间的最小步数；防止滑块重叠。',
       default: '0',
     },
     {
@@ -259,7 +360,8 @@ export const docsZh = {
     {
       name: 'htmlName',
       type: 'string',
-      description: '用于表单提交的 HTML name 属性。渲染携带当前值的隐藏输入（范围模式下为两个条目）。',
+      description:
+        '用于表单提交的 HTML name 属性。渲染携带当前值的隐藏输入（范围模式下为两个条目）。',
     },
     {
       name: 'disabledMessage',
@@ -293,8 +395,7 @@ export const docsZh = {
     {
       name: 'status',
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
-      description:
-        '验证反馈的状态指示器对象（`{ type, message }`）。',
+      description: '验证反馈的状态指示器对象（`{ type, message }`）。',
     },
     {
       name: 'labelTooltip',
@@ -310,20 +411,49 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-slider', visualProps: ['orientation'], states: ['disabled']},
+      {
+        className: 'astryx-slider',
+        visualProps: ['orientation'],
+        states: ['disabled'],
+      },
       {className: 'astryx-slider-track', visualProps: ['orientation']},
-      {className: 'astryx-slider-thumb', visualProps: ['orientation'], states: ['disabled']},
+      {
+        className: 'astryx-slider-thumb',
+        visualProps: ['orientation'],
+        states: ['disabled'],
+      },
     ],
   },
   usage: {
+    anatomy,
     description:
       'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
     bestPractices: [
-      {guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
-      {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
-      {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
-      {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
-      {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
+      {
+        guidance: true,
+        description:
+          'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.',
+      },
+      {
+        guidance: true,
+        description:
+          'Format values with meaningful units like "$50" or "75%" instead of raw numbers.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for precise numeric entry; pair with a text input or use NumberInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };
@@ -331,19 +461,41 @@ export const docsZh = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
+    anatomy,
     description:
       'A draggable control for selecting a numeric value or range within defined bounds. Supports single value and range selection, tick marks, custom value formatting, and vertical orientation. Use it when users need to explore a continuous range, such as volume, price, or percentage.',
     bestPractices: [
-      {guidance: true, description: 'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.'},
-      {guidance: true, description: 'Format values with meaningful units like "$50" or "75%" instead of raw numbers.'},
-      {guidance: false, description: 'Use for precise numeric entry; pair with a text input or use NumberInput instead.'},
-      {guidance: false, description: 'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.'},
-      {guidance: false, description: 'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.'},
+      {
+        guidance: true,
+        description:
+          'Always provide a label, even if visually hidden, so the slider is accessible to screen readers.',
+      },
+      {
+        guidance: true,
+        description:
+          'Format values with meaningful units like "$50" or "75%" instead of raw numbers.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for precise numeric entry; pair with a text input or use NumberInput instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Set a step size so large that only a few positions are possible; use SegmentedControl or radio buttons instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled slider in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   propDescriptions: {
     label: 'Label text (always rendered for a11y).',
-    value: 'Current value; number for single thumb, [number, number] for range.',
+    value:
+      'Current value; number for single thumb, [number, number] for range.',
     onChange: 'Fired on value change during drag.',
     onChangeEnd: 'Fired when drag ends.',
     min: 'Minimum value.',
@@ -353,9 +505,11 @@ export const docsDense = {
     formatValue: 'Custom value formatting fn for display + aria-valuetext.',
     valueDisplay: 'How current value is displayed.',
     marks: 'Tick marks at specified positions w/ optional labels.',
-    minStepsBetweenThumbs: 'Min steps between thumbs in range mode; prevents overlap.',
+    minStepsBetweenThumbs:
+      'Min steps between thumbs in range mode; prevents overlap.',
     isDisabled: 'Whether slider is disabled.',
-    htmlName: 'HTML name attr; hidden inputs carry the value (two in range mode).',
+    htmlName:
+      'HTML name attr; hidden inputs carry the value (two in range mode).',
     isOptional: 'Whether field is optional.',
     isRequired: 'Whether field is required.',
     isLabelHidden: 'Visually hide label.',
@@ -364,4 +518,4 @@ export const docsDense = {
     labelTooltip: 'Tooltip text for info icon next to label.',
     xstyle: 'StyleX layout styles; must be stylex.create() value.',
   },
-};
+};