An open source design system that's fully customizable and agent ready
TypeScript
docs(core): record ProgressBar and Slider anatomy (#5760)
Cindy Zhang1d6d712bf6a1
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjsindex b27c45e3b8..b4e2902f0b 100644--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs@@ -1,12 +1,59 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Progress bar',+ required: true,+ description: 'Container arranging the label row and progress track.',+ },+ {+ name: 'Label',+ required: true,+ description:+ 'Text naming the operation, optionally hidden visually while remaining accessible.',+ },+ {+ name: 'Value text',+ required: false,+ description:+ 'Formatted determinate value shown beside the label when requested.',+ },+ {+ name: 'Track',+ required: true,+ description:+ 'Remaining-progress rail that carries the progressbar semantics.',+ },+ {+ name: 'Fill',+ required: true,+ description:+ 'Painted segment showing completed progress or indeterminate movement.',+ },+ {+ name: 'Mark',+ required: false,+ description: 'Labeled target tick positioned on a determinate track.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {name: 'ProgressBar',displayName: 'Progress Bar',category: 'Feedback & Status',- keywords: ["progressbar","progress","loader","loading","linear","determinate","indeterminate","meter"],+ keywords: [+ 'progressbar',+ 'progress',+ 'loader',+ 'loading',+ 'linear',+ 'determinate',+ 'indeterminate',+ 'meter',+ ],props: [{name: 'label',@@ -60,12 +107,13 @@ export const docs = {name: 'marks',type: 'ReadonlyArray<{value: number; label: string}>',description:- 'Fixed target marks drawn on the track at values in the same 0..max scale as value (e.g. a goal line). They stay visible whether progress is below or past them, and take their color from what they sit on: a mark inside the filled area uses the fill variant\'s on-color (on-accent, on-warning, on-error, and so on), a mark still out on the bare track uses the primary text color (the secondary one on a disabled bar, which dims everything it draws). Each mark requires a label: it is the mark\'s accessible name and the text revealed via a tooltip on hover/focus. Ignored when indeterminate.',+ "Fixed target marks drawn on the track at values in the same 0..max scale as value (e.g. a goal line). They stay visible whether progress is below or past them, and take their color from what they sit on: a mark inside the filled area uses the fill variant's on-color (on-accent, on-warning, on-error, and so on), a mark still out on the bare track uses the primary text color (the secondary one on a disabled bar, which dims everything it draws). Each mark requires a label: it is the mark's accessible name and the text revealed via a tooltip on hover/focus. Ignored when indeterminate.",},{name: 'isDisabled',type: 'boolean',- description: 'Visually disabled state: grays out the fill and text. Use for canceled or inactive operations.',+ description:+ 'Visually disabled state: grays out the fill and text. Use for canceled or inactive operations.',default: 'false',},{@@ -96,7 +144,10 @@ export const docs = {visualProps: ['variant'],deprecatedFor: 'progress-bar-fill',},- {className: 'astryx-progressbar-track', deprecatedFor: 'progress-bar-track'},+ {+ className: 'astryx-progressbar-track',+ deprecatedFor: 'progress-bar-track',+ },{className: 'astryx-progressbar-mark',visualProps: ['variant', 'placement'],@@ -104,24 +155,63 @@ export const docs = {},],vars: [- {name: '--_progressbar-mark-width', description: 'Target mark tick width', default: '2px', private: true},- {name: '--_progressbar-mark-height', description: 'Target mark tick height', default: '8px', private: true},+ {+ name: '--_progressbar-mark-width',+ description: 'Target mark tick width',+ default: '2px',+ private: true,+ },+ {+ name: '--_progressbar-mark-height',+ description: 'Target mark tick height',+ default: '8px',+ private: true,+ },],derived: [{property: 'width', vars: ['--_progressbar-mark-width'], replaces: true},- {property: 'height', vars: ['--_progressbar-mark-height'], replaces: true},+ {+ property: 'height',+ vars: ['--_progressbar-mark-height'],+ replaces: true,+ },],},usage: {+ anatomy,description:- 'A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can\'t be calculated. Supports semantic color variants, value labels, and custom formatting.',+ "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.",bestPractices: [- { guidance: true, description: "Use a determinate bar when the total amount of work is known, and indeterminate when it's not." },- { guidance: true, description: 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.' },- { guidance: true, description: "Always provide a label, even if hidden; screen readers need it to announce what's loading." },- { guidance: false, description: 'Place icons or labels inside the bar; compose them alongside it using layout components.' },- { guidance: false, description: "Use a progress bar for instant actions; it's meant for operations that take noticeable time." },- { guidance: false, description: 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.' },+ {+ guidance: true,+ description:+ "Use a determinate bar when the total amount of work is known, and indeterminate when it's not.",+ },+ {+ guidance: true,+ description:+ 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.',+ },+ {+ guidance: true,+ description:+ "Always provide a label, even if hidden; screen readers need it to announce what's loading.",+ },+ {+ guidance: false,+ description:+ 'Place icons or labels inside the bar; compose them alongside it using layout components.',+ },+ {+ guidance: false,+ description:+ "Use a progress bar for instant actions; it's meant for operations that take noticeable time.",+ },+ {+ guidance: false,+ description:+ 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.',+ },],},};@@ -164,8 +254,7 @@ export const docsZh = {{name: 'formatValueLabel',type: '(value: number, max: number) => string',- description:- '自定义值标签格式化器;默认为百分比字符串。',+ description: '自定义值标签格式化器;默认为百分比字符串。',},{name: 'variant',@@ -188,7 +277,8 @@ export const docsZh = {{name: 'isDisabled',type: 'boolean',- description: '视觉禁用状态——使填充条和文本变灰。用于已取消或不活跃的操作。',+ description:+ '视觉禁用状态——使填充条和文本变灰。用于已取消或不活跃的操作。',default: 'false',},{@@ -219,7 +309,10 @@ export const docsZh = {visualProps: ['variant'],deprecatedFor: 'progress-bar-fill',},- {className: 'astryx-progressbar-track', deprecatedFor: 'progress-bar-track'},+ {+ className: 'astryx-progressbar-track',+ deprecatedFor: 'progress-bar-track',+ },{className: 'astryx-progressbar-mark',visualProps: ['variant', 'placement'],@@ -227,24 +320,63 @@ export const docsZh = {},],vars: [- {name: '--_progressbar-mark-width', description: '目标标记刻度宽度', default: '2px', private: true},- {name: '--_progressbar-mark-height', description: '目标标记刻度高度', default: '8px', private: true},+ {+ name: '--_progressbar-mark-width',+ description: '目标标记刻度宽度',+ default: '2px',+ private: true,+ },+ {+ name: '--_progressbar-mark-height',+ description: '目标标记刻度高度',+ default: '8px',+ private: true,+ },],derived: [{property: 'width', vars: ['--_progressbar-mark-width'], replaces: true},- {property: 'height', vars: ['--_progressbar-mark-height'], replaces: true},+ {+ property: 'height',+ vars: ['--_progressbar-mark-height'],+ replaces: true,+ },],},usage: {+ anatomy,description:- 'A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can\'t be calculated. Supports semantic color variants, value labels, and custom formatting.',+ "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.",bestPractices: [- { guidance: true, description: "Use a determinate bar when the total amount of work is known, and indeterminate when it's not." },- { guidance: true, description: 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.' },- { guidance: true, description: "Always provide a label, even if hidden; screen readers need it to announce what's loading." },- { guidance: false, description: 'Place icons or labels inside the bar; compose them alongside it using layout components.' },- { guidance: false, description: "Use a progress bar for instant actions; it's meant for operations that take noticeable time." },- { guidance: false, description: 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.' },+ {+ guidance: true,+ description:+ "Use a determinate bar when the total amount of work is known, and indeterminate when it's not.",+ },+ {+ guidance: true,+ description:+ 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.',+ },+ {+ guidance: true,+ description:+ "Always provide a label, even if hidden; screen readers need it to announce what's loading.",+ },+ {+ guidance: false,+ description:+ 'Place icons or labels inside the bar; compose them alongside it using layout components.',+ },+ {+ guidance: false,+ description:+ "Use a progress bar for instant actions; it's meant for operations that take noticeable time.",+ },+ {+ guidance: false,+ description:+ 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.',+ },],},};@@ -254,15 +386,40 @@ export const docsDense = {description:'Progress bar for displaying determinate or indeterminate progress.',usage: {+ anatomy,description:- 'A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can\'t be calculated. Supports semantic color variants, value labels, and custom formatting.',+ "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.",bestPractices: [- { guidance: true, description: "Use a determinate bar when the total amount of work is known, and indeterminate when it's not." },- { guidance: true, description: 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.' },- { guidance: true, description: "Always provide a label, even if hidden; screen readers need it to announce what's loading." },- { guidance: false, description: 'Place icons or labels inside the bar; compose them alongside it using layout components.' },- { guidance: false, description: "Use a progress bar for instant actions; it's meant for operations that take noticeable time." },- { guidance: false, description: 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.' },+ {+ guidance: true,+ description:+ "Use a determinate bar when the total amount of work is known, and indeterminate when it's not.",+ },+ {+ guidance: true,+ description:+ 'Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.',+ },+ {+ guidance: true,+ description:+ "Always provide a label, even if hidden; screen readers need it to announce what's loading.",+ },+ {+ guidance: false,+ description:+ 'Place icons or labels inside the bar; compose them alongside it using layout components.',+ },+ {+ guidance: false,+ description:+ "Use a progress bar for instant actions; it's meant for operations that take noticeable time.",+ },+ {+ guidance: false,+ description:+ 'Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.',+ },],},propDescriptions: {@@ -271,11 +428,14 @@ export const docsDense = {max: 'Maximum value.',isLabelHidden: 'Visually hide label (remains accessible).',hasValueLabel: 'Show formatted value text (ignored when indeterminate).',- formatValueLabel: 'Custom value label formatter; defaults to percentage string.',+ formatValueLabel:+ 'Custom value label formatter; defaults to percentage string.',variant: 'Semantic color variant.',isIndeterminate: 'Animated loading indicator for unknown progress.',- marks: 'Fixed target marks ({value, label?}) drawn on the track in the 0..max scale; stay visible past the fill. Marks inside the fill take the variant on-color; marks on the bare track take the primary text color (secondary when disabled). A label reveals a tooltip on hover/focus. Ignored when indeterminate.',+ marks:+ 'Fixed target marks ({value, label?}) drawn on the track in the 0..max scale; stay visible past the fill. Marks inside the fill take the variant on-color; marks on the bare track take the primary text color (secondary when disabled). A label reveals a tooltip on hover/focus. Ignored when indeterminate.',isDisabled: 'Visually disabled: grays out fill and text.',- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',+ xstyle:+ 'StyleX styles for layout customization. Must be stylex.create() value.',},};diff --git a/packages/core/src/ProgressBar/ProgressBar.spec.md b/packages/core/src/ProgressBar/ProgressBar.spec.mdindex ffd0a959da..c6eeacc5b8 100644--- a/packages/core/src/ProgressBar/ProgressBar.spec.md+++ b/packages/core/src/ProgressBar/ProgressBar.spec.md@@ -1,6 +1,6 @@---schema_version: 1-template_version: 1+template_version: 3kind: componentid: component:ProgressBarauthority: draft@@ -10,7 +10,12 @@ approved_by: nullapproved_at: nullowners: [cixzhang]review_triggers: [public-api, behavior, theming, accessibility]-verified_by: [packages/core/src/ProgressBar/ProgressBar.test.tsx]+verified_by:+ [+ packages/core/src/ProgressBar/ProgressBar.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ scripts/check-knowledge.mjs,+ ]families: []design_specs: []architecture:@@ -34,14 +39,15 @@ from remaining progress without depending on visible text rendered elsewhere.External text may supplement the bar, but it is not a prerequisite for the barto be correct.-This draft is intentionally limited to that visual-completeness requirement and-the resulting public-API boundary. It does not choose a visual treatment.+This draft now also records the current consumer anatomy and exact theming+ownership. It still does not choose a visual treatment or change runtime+behavior.## Compatibility and migration- Released default preserved: `yes`; this draft changes no runtime behavior.-- Compatibility class: documentation-only draft; no public API is added, removed,- or changed.+- Compatibility class: additive documentation only; no public API, DOM, style,+ target, or alias is added, removed, or changed.- Controlled/uncontrolled behavior: unchanged.- Migration decision: `component:ProgressBar/DEC-1`.@@ -55,11 +61,16 @@ Consumer migration instructions belong in consumer docs and release notes.progress for every determinate presentation the component provides.- Internal resolution of that visual treatment when the caller supplies ordinaryprogress state.+- The current progress-bar container, track, fill, and mark parts represented by+ the `progress-bar`, `progress-bar-track`, `progress-bar-fill`, and+ `progress-bar-mark` targets.**Does not own / non-goals**- External visible labels, values, or descriptions — owned by the productcallsite and supplementary to the bar.+- A separate public target for the built-in label or value text; none currently+ exists.- The exact standalone contrast treatment — still a human design decision.- Theme token definitions — owned by `architecture:theme-tokens`.- Public API that makes visual correctness depend on caller-declared external@@ -81,13 +92,14 @@ does not turn nearby external content into a ProgressBar concept.Draft requirements identify their basis so observed code is not mistaken for anintentional decision.-| ID | Candidate invariant | Basis | Draft review state |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ---------------------- |-| FR1 | Every determinate presentation ProgressBar provides MUST be a sufficient standalone visual for distinguishing completed from remaining progress. | `component:ProgressBar/DEC-1`; existing non-text contrast standard | Settled |-| FR2 | External visible text MAY supplement the bar but MUST NOT be required for the bar's visual correctness. | `component:ProgressBar/DEC-1` | Settled |-| FR3 | ProgressBar MUST NOT make visual correctness depend on caller-declared external content that it cannot verify or associate. | `component:ProgressBar/DEC-1`; `spec:AST-002` | Settled |-| FR4 | Supplementary text or graphics MUST NOT substitute for a sufficient distinction between completed and remaining progress. | `component:ProgressBar/DEC-1` | Settled |-| FR5 | Public API MAY be considered only after the component has a correct base behavior and a stable caller-owned distinction still remains. | `component:ProgressBar/DEC-1`; `spec:AST-002` | Settled admission gate |+| ID | Candidate invariant | Basis | Draft review state |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------- |+| FR1 | Every determinate presentation ProgressBar provides MUST be a sufficient standalone visual for distinguishing completed from remaining progress. | `component:ProgressBar/DEC-1`; existing non-text contrast standard | Settled |+| FR2 | External visible text MAY supplement the bar but MUST NOT be required for the bar's visual correctness. | `component:ProgressBar/DEC-1` | Settled |+| FR3 | ProgressBar MUST NOT make visual correctness depend on caller-declared external content that it cannot verify or associate. | `component:ProgressBar/DEC-1`; `spec:AST-002` | Settled |+| FR4 | Supplementary text or graphics MUST NOT substitute for a sufficient distinction between completed and remaining progress. | `component:ProgressBar/DEC-1` | Settled |+| FR5 | Public API MAY be considered only after the component has a correct base behavior and a stable caller-owned distinction still remains. | `component:ProgressBar/DEC-1`; `spec:AST-002` | Settled admission gate |+| FR6 | The current container, track, fill, and mark carry their four current targets; label and value text carry no separate ProgressBar target. | Current source, public docs, and focused tests | Verified current behavior; no target change |### Observed current behavior@@ -97,8 +109,11 @@ draft:- Determinate progress renders a semantic-color fill over a muted track.- `hasValueLabel` optionally renders formatted value text in the component.- Callers may compose other visible text outside the component.-- The current public theming surface exposes root, fill, track, and mark targets;- variant state is reflected on the root, fill, and mark targets.+- `Progress bar`, `Track`, `Fill`, and `Mark` carry `progress-bar`,+ `progress-bar-track`, `progress-bar-fill`, and `progress-bar-mark`+ respectively. `Label` and `Value text` have no separate public target.+- Variant state is reflected on the progress-bar, fill, and mark targets;+ placement is also reflected on marks.- Current unit tests cover value semantics, labels, variants, determinate andindeterminate modes, disabled rendering, marks, and public target names. Theydo not establish a sufficient standalone completed-versus-remaining visual@@ -146,15 +161,45 @@ draft:## Design relationships-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |-| ------------------------------------ | ------------------------------------------- | ------------------------ | -------------- | ------------------ |-| Determinate fill and remaining track | Sufficient standalone distinction | Unsettled | Prominent | FR1, AR1 |-| Built-in or external visible value | Supplements rather than enables correctness | Prescribed | Supporting | FR2, AR3 |+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ------------------------------------ | ------------------------------------------------------- | ------------------------------------- | -------------- | ------------------ |+| Progress bar | Arranges the current label row and progress track. | Current source and public docs | Supporting | FR6 |+| Label and value text | Name the operation and optionally supplement its value. | Current source and public docs | Supporting | FR2, AR2, FR6 |+| Determinate fill and remaining track | Provide a sufficient standalone distinction. | Unsettled standalone visual treatment | Prominent | FR1, AR1 |+| Mark | Presents an optional labeled target on the track. | Current source and public docs | Supporting | FR6 |The component implements design requirements without copying their rationale.The standalone visual remains a human design decision; this contract does notinvent its form.+### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Progress bar": {"target": "progress-bar"},+ "Label": {+ "none": {+ "reason": "unsettled: No current public ProgressBar target reaches this part; future target ownership is undecided."+ }+ },+ "Value text": {+ "none": {+ "reason": "unsettled: No current public ProgressBar target reaches this part; future target ownership is undecided."+ }+ },+ "Track": {"target": "progress-bar-track"},+ "Fill": {"target": "progress-bar-fill"},+ "Mark": {"target": "progress-bar-mark"}+}+```++The `Label` and `Value text` gaps are current facts, not decisions that those+parts should remain untargeted. Deprecated `progressbar*` aliases are+compatibility metadata, not separate anatomy or current targets. This map does+not select a standalone visual treatment or resolve OQ1.+## Family and system relationships- `architecture:public-component-api` and `spec:AST-002/DEC-1` govern whether a@@ -165,15 +210,22 @@ invent its form.component capabilities without creating a second component contract.- `architecture:theme-tokens` governs the semantic token vocabulary used by theeventual treatment.+- ProgressBar and Slider both render a track, a filled segment, positioned+ indicators, and optional value presentation, while their current target+ coverage differs. That evidence requires a future joint family/audit pass; it+ does not declare a current family, require a new target, or authorize runtime+ behavior changes.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------- |-| FR1, AR1 | Real-browser visual and contrast evidence across shipped themes and color modes | Partial determinate progress for each semantic variant | A completed or remaining segment becomes indistinguishable without text | Future ProgressBar visual audit |-| FR2, FR3, AR3 | Public type and consumer-doc review | No value text, built-in value text, external composed text | A caller signal is credited with correctness the component cannot verify | Future ProgressBar API tests |-| AR2 | `ProgressBar.test.tsx` | Determinate, indeterminate, hidden label, custom value text | Accessible name or value semantics disappear when visuals change | Future ProgressBar accessibility audit |-| Theming | Theme-target metadata checks plus browser evidence | Shipped themes, light and dark modes | A theme override bypasses the standalone distinction | Future ProgressBar theming audit |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------- |+| FR1, AR1 | Real-browser visual and contrast evidence across shipped themes and color modes | Partial determinate progress for each semantic variant | A completed or remaining segment becomes indistinguishable without text | Future ProgressBar visual audit |+| FR2, FR3, AR3 | Public type and consumer-doc review | No value text, built-in value text, external composed text | A caller signal is credited with correctness the component cannot verify | Future ProgressBar API tests |+| AR2 | `ProgressBar.test.tsx` | Determinate, indeterminate, hidden label, custom value text | Accessible name or value semantics disappear when visuals change | Future ProgressBar accessibility audit |+| FR6 | `ProgressBar.test.tsx` and `themingTargets.test.ts` | Current and deprecated target classes | Source, metadata, or compatibility target placement drifts | `audit:ProgressBar/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and four current targets | Missing, extra, prefixed, stale, alias-backed, or unclaimed mappings fail | `audit:ProgressBar/theming` |+| Theming | Theme-target metadata checks plus browser evidence | Shipped themes, light and dark modes | A theme override bypasses the standalone distinction | Future ProgressBar theming audit |## Decision logdiff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjsindex 37f9be3eba..49349e2c5d 100644--- a/packages/core/src/Slider/Slider.doc.mjs+++ b/packages/core/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: 'Form Controls',- keywords: ["slider","range","slidebar","trackbar","scrubber","knob","thumb","rangeslider"],+ 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.',diff --git a/packages/core/src/Slider/Slider.spec.md b/packages/core/src/Slider/Slider.spec.mdnew file mode 100644index 0000000000..b91a3b7abb--- /dev/null+++ b/packages/core/src/Slider/Slider.spec.md@@ -0,0 +1,223 @@+---+schema_version: 1+template_version: 3+kind: component+id: component:Slider+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [theming]+verified_by:+ [+ packages/core/src/Slider/Slider.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ scripts/check-knowledge.mjs,+ ]+families: []+design_specs: []+architecture: [architecture:component-theming-surface]+contributing: []+system_specs: []+---++# Slider component contract++## Intent++Slider presents a labeled control for selecting one numeric value or a bounded+range. This draft records its 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; Slider remains controlled+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The current slider row, background track, filled range, tick marks and labels,+ thumbs, and adjacent text value presentation.+- The existing `slider`, `slider-track`, and `slider-thumb` public targets.++**Does not own / non-goals**++- Label and validation-message presentation — owned by `component:Field` and+ `component:FieldStatus`.+- Value-tooltip presentation — owned by `component:Tooltip`.+- New public targets for the filled range, tick marks, mark labels, description,+ or adjacent text value display.+- A decision that the current target asymmetry should be preserved or removed.++## Public concepts++No new public concept is introduced. Consumer props, modes, states, and usage+remain documented in `Slider.doc.mjs`.++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |+| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track. | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |+| FR2 | `Slider`, `Track`, and `Thumb` carry the existing `slider`, `slider-track`, and `slider-thumb` targets respectively. | Current source and public docs | Verified current behavior; no target change |+| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target. | Current source and public docs | Verified current asymmetry; not ratified as policy |+| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip. | Current source and focused tests | Verified composition boundary |++### Observed current target asymmetry++ProgressBar currently exposes targets for its fill and marks, while Slider+exposes targets for its root row, background track, and thumbs but not its+filled range, tick marks, mark labels, or adjacent text value display. This is+implementation evidence for a joint audit, not approval of either target shape.++### Allowed variation++- Orientation, single or range mode, disabled state, value-display mode, and the+ number or labels of supplied marks remain current capabilities rather than+ separate target names.+- A description, status message, mark label, text value, or value tooltip may be+ absent without changing the remaining anatomy.++### Representative states++| State | Required invariant | Allowed variation |+| ------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------- |+| Single value | One thumb and a filled range render over the track. | Orientation, value, disabled state, value display |+| Range value | Two thumbs bound the filled range. | Values and minimum step separation |+| With marks | Tick marks and optional mark labels align to the same range geometry. | Mark count, values, and label presence |+| With shared field output | Field or Tooltip renders the requested label, feedback, or value layer. | Description, status, disabled reason, tooltip mode |++### Transformation and precedence order++- No new value, snapping, geometry, interaction, 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 Slider's existing accessible name, value,+range-thumb naming, description/status association, keyboard behavior, disabled+behavior, or value-tooltip behavior.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ----------------------- | ------------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |+| Label and description | Identify and explain the numeric setting. | Current shared-component source | Supporting | FR4 |+| Slider and track | Arrange the current interactive range control and rail. | Current source and public docs | Prominent | FR1, FR2 |+| Filled range and thumbs | Show the selected value or interval over the available range. | Current source and public docs | Prominent | FR1, FR2, FR3 |+| Tick marks and labels | Show optional supplied positions and their text. | Current source and public docs | Supporting | FR1, FR3 |+| Value presentation | Shows the formatted value as text or a shared Tooltip. | Current source and public docs | Supporting | FR3, FR4 |+| Status message | Presents shared validation feedback below the slider. | Current shared-component source | Supporting | FR4 |++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Label": {+ "delegatesTo": {"owner": "component:Field", "target": "field-label"}+ },+ "Description": {+ "none": {+ "reason": "unsettled: No current public target reaches this part; future target ownership is undecided."+ }+ },+ "Slider": {"target": "slider"},+ "Track": {"target": "slider-track"},+ "Filled range": {+ "none": {+ "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."+ }+ },+ "Tick mark": {+ "none": {+ "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."+ }+ },+ "Mark label": {+ "none": {+ "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."+ }+ },+ "Thumb": {"target": "slider-thumb"},+ "Value display": {+ "none": {+ "reason": "unsettled: No current public Slider target reaches this part; future target ownership is undecided."+ }+ },+ "Value tooltip": {+ "delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}+ },+ "Status message": {+ "delegatesTo": {+ "owner": "component:FieldStatus",+ "target": "field-status"+ }+ }+}+```++`Filled range`, `Tick mark`, `Mark label`, and `Value display` remain stable+consumer anatomy, but no current Slider target reaches them. The map records+those gaps without making their absence intentional. `Value display` names the+adjacent text mode; the separately listed value tooltip retains Tooltip's target.++## Family and system relationships++- `architecture:component-theming-surface` owns anatomy qualification, factual+ `none` dispositions, and composition-preserving target ownership.+- Field, FieldStatus, and Tooltip retain their existing public target contracts+ when composed by Slider.+- Slider and ProgressBar both render a track, a filled segment, positioned+ indicators, and optional value presentation, while their current target+ coverage differs. That evidence requires a future joint family/audit pass; it+ does not declare a current family, require a new target, or authorize runtime+ behavior changes.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------- |+| FR1 | `Slider.test.tsx` structure, range, and marks suites | Single, range, horizontal, vertical, marks | Removing or misaligning stable parts breaks existing role, position, or mark assertions. | `audit:Slider/anatomy` |+| FR2 | `themingTargets.test.ts` | Root, track, and thumb target call sites | Source and public target metadata drift fails the target guard. | `audit:Slider/theming` |+| FR3 | Source and consumer-doc review | Filled range, marks, labels, adjacent text value | A missing target is inaccurately documented as present or intentionally permanent. | `audit:Slider/theming` |+| FR4 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only | Label, status, value tooltip, disabled reason | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage. | `audit:Slider/anatomy` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and three current local targets | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation. | `audit:Slider/theming` |++The focused Slider suite does not separately assert the exact `slider`,+`slider-track`, or `slider-thumb` class placement. The source/metadata target+guard covers those declarations. It also covers only the disabled-reason+Tooltip path, not the `valueDisplay="tooltip"` composition; that anatomy is+source-inspected and remains missing focused test coverage.++## Decision log++None. This draft records current facts and introduces no component-local design,+family, theming, or API decision.++## Open questions++- **OQ1 — After a joint ProgressBar and Slider family audit, should any shared+ painted parts have aligned target coverage?** (`human-api`)++This question records the audit need only. It does not presume that either+component should add, remove, or rename a target.++## Content boundary++This file does not duplicate consumer prop tables, examples, implementation+steps, audit outcomes, or shared-component contracts. It links to their owners.