@astryxdesign/core 0.5.2-canary.212c4fd → 0.5.2-canary.457de8d
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astryxdesign/core",
|
|
3
|
-
"version": "0.5.2-canary.
|
|
3
|
+
"version": "0.5.2-canary.457de8d",
|
|
4
4
|
"displayName": "Astryx Core",
|
|
5
5
|
"description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
|
|
6
6
|
"author": "Meta Open Source",
|
|
@@ -661,7 +661,7 @@
|
|
|
661
661
|
"react-dom": ">=19.0.0"
|
|
662
662
|
},
|
|
663
663
|
"devDependencies": {
|
|
664
|
-
"@astryxdesign/cli": "0.5.2-canary.
|
|
664
|
+
"@astryxdesign/cli": "0.5.2-canary.457de8d",
|
|
665
665
|
"@babel/cli": "^8.0.4",
|
|
666
666
|
"@babel/core": "^7.29.7",
|
|
667
667
|
"@babel/preset-react": "^8.0.1",
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
---
|
|
2
|
+
schema_version: 1
|
|
3
|
+
template_version: 1
|
|
4
|
+
kind: component
|
|
5
|
+
id: component:ProgressBar
|
|
6
|
+
authority: draft
|
|
7
|
+
archive_reason: null
|
|
8
|
+
superseded_by: null
|
|
9
|
+
approved_by: null
|
|
10
|
+
approved_at: null
|
|
11
|
+
owners: [cixzhang]
|
|
12
|
+
review_triggers: [public-api, behavior, theming, accessibility]
|
|
13
|
+
verified_by: [packages/core/src/ProgressBar/ProgressBar.test.tsx]
|
|
14
|
+
families: []
|
|
15
|
+
design_specs: []
|
|
16
|
+
architecture:
|
|
17
|
+
[
|
|
18
|
+
architecture:public-component-api,
|
|
19
|
+
architecture:component-theming-surface,
|
|
20
|
+
architecture:theme-authoring-contract,
|
|
21
|
+
architecture:theme-tokens,
|
|
22
|
+
]
|
|
23
|
+
contributing: []
|
|
24
|
+
system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2]
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
# ProgressBar component contract
|
|
28
|
+
|
|
29
|
+
## Intent
|
|
30
|
+
|
|
31
|
+
ProgressBar communicates the progress of an operation. A determinate bar must be
|
|
32
|
+
a sufficient standalone visual: people must be able to distinguish completed
|
|
33
|
+
from remaining progress without depending on visible text rendered elsewhere.
|
|
34
|
+
External text may supplement the bar, but it is not a prerequisite for the bar
|
|
35
|
+
to be correct.
|
|
36
|
+
|
|
37
|
+
This draft is intentionally limited to that visual-completeness requirement and
|
|
38
|
+
the resulting public-API boundary. It does not choose a visual treatment.
|
|
39
|
+
|
|
40
|
+
## Compatibility and migration
|
|
41
|
+
|
|
42
|
+
- Released default preserved: `yes`; this draft changes no runtime behavior.
|
|
43
|
+
- Compatibility class: documentation-only draft; no public API is added, removed,
|
|
44
|
+
or changed.
|
|
45
|
+
- Controlled/uncontrolled behavior: unchanged.
|
|
46
|
+
- Migration decision: `component:ProgressBar/DEC-1`.
|
|
47
|
+
|
|
48
|
+
Consumer migration instructions belong in consumer docs and release notes.
|
|
49
|
+
|
|
50
|
+
## Ownership boundary
|
|
51
|
+
|
|
52
|
+
**Owns**
|
|
53
|
+
|
|
54
|
+
- A sufficient standalone visual distinction between completed and remaining
|
|
55
|
+
progress for every determinate presentation the component provides.
|
|
56
|
+
- Internal resolution of that visual treatment when the caller supplies ordinary
|
|
57
|
+
progress state.
|
|
58
|
+
|
|
59
|
+
**Does not own / non-goals**
|
|
60
|
+
|
|
61
|
+
- External visible labels, values, or descriptions — owned by the product
|
|
62
|
+
callsite and supplementary to the bar.
|
|
63
|
+
- The exact standalone contrast treatment — still a human design decision.
|
|
64
|
+
- Theme token definitions — owned by `architecture:theme-tokens`.
|
|
65
|
+
- Public API that makes visual correctness depend on caller-declared external
|
|
66
|
+
content — governed by `architecture:public-component-api` and `spec:AST-002`.
|
|
67
|
+
|
|
68
|
+
## Public concepts
|
|
69
|
+
|
|
70
|
+
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|
|
71
|
+
| ------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------- | ------------------------------- | ----------------------- | ------------------ | ------------------------------ |
|
|
72
|
+
| Progress mode | `determinate`, `indeterminate` | Whether completed progress is known | All variants | Determinate | `component:ProgressBar` | Stable current API | Existing prop handling applies |
|
|
73
|
+
| Built-in value text | Shown or hidden | Optional visible text supplement generated by ProgressBar | Determinate only | Hidden | `component:ProgressBar` | Stable current API | Ignored when indeterminate |
|
|
74
|
+
| Visual treatment | One sufficient standalone treatment; exact form unresolved | How the graphic distinguishes completed from remaining progress | Determinate progress | Sufficient standalone treatment | `component:ProgressBar` | Draft decision | No incomplete public mode |
|
|
75
|
+
|
|
76
|
+
The current public props remain documented in `ProgressBar.doc.mjs`. This draft
|
|
77
|
+
does not turn nearby external content into a ProgressBar concept.
|
|
78
|
+
|
|
79
|
+
## Behavioral and layout contract
|
|
80
|
+
|
|
81
|
+
Draft requirements identify their basis so observed code is not mistaken for an
|
|
82
|
+
intentional decision.
|
|
83
|
+
|
|
84
|
+
| ID | Candidate invariant | Basis | Draft review state |
|
|
85
|
+
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ---------------------- |
|
|
86
|
+
| 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 |
|
|
87
|
+
| FR2 | External visible text MAY supplement the bar but MUST NOT be required for the bar's visual correctness. | `component:ProgressBar/DEC-1` | Settled |
|
|
88
|
+
| 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 |
|
|
89
|
+
| FR4 | Supplementary text or graphics MUST NOT substitute for a sufficient distinction between completed and remaining progress. | `component:ProgressBar/DEC-1` | Settled |
|
|
90
|
+
| 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 |
|
|
91
|
+
|
|
92
|
+
### Observed current behavior
|
|
93
|
+
|
|
94
|
+
These observations describe `main`; they are not design approval from this
|
|
95
|
+
draft:
|
|
96
|
+
|
|
97
|
+
- Determinate progress renders a semantic-color fill over a muted track.
|
|
98
|
+
- `hasValueLabel` optionally renders formatted value text in the component.
|
|
99
|
+
- Callers may compose other visible text outside the component.
|
|
100
|
+
- The current public theming surface exposes root, fill, track, and mark targets;
|
|
101
|
+
variant state is reflected on the root, fill, and mark targets.
|
|
102
|
+
- Current unit tests cover value semantics, labels, variants, determinate and
|
|
103
|
+
indeterminate modes, disabled rendering, marks, and public target names. They
|
|
104
|
+
do not establish a sufficient standalone completed-versus-remaining visual
|
|
105
|
+
across shipped themes.
|
|
106
|
+
|
|
107
|
+
### Allowed variation
|
|
108
|
+
|
|
109
|
+
- **AV1 — Exact visual treatment.** Shape, token choice, and other rendering
|
|
110
|
+
details may vary if every resulting presentation satisfies FR1.
|
|
111
|
+
- **AV2 — Themes.** Themes may express their visual language through the current
|
|
112
|
+
theming system while preserving the standalone distinction.
|
|
113
|
+
|
|
114
|
+
### Representative states
|
|
115
|
+
|
|
116
|
+
| State | Required invariant | Allowed variation |
|
|
117
|
+
| -------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
118
|
+
| Determinate, partial progress | Completed and remaining progress are distinguishable from the graphic alone | Exact visual treatment and semantic variant |
|
|
119
|
+
| Determinate with built-in value text | The graphic still satisfies FR1; value text supplements it | Value formatting |
|
|
120
|
+
| Determinate with external visible text | The graphic still satisfies FR1 without relying on that text | Callsite composition |
|
|
121
|
+
| Indeterminate | Communicates ongoing activity without claiming a completed amount | Existing animation and theme variation; completed-versus-remaining distinction does not apply |
|
|
122
|
+
|
|
123
|
+
### Transformation and precedence order
|
|
124
|
+
|
|
125
|
+
- **ORD1 — Progress state before presentation.** Resolve determinate or
|
|
126
|
+
indeterminate behavior from component state, then render a treatment valid for
|
|
127
|
+
that mode. External content does not weaken the determinate visual requirement.
|
|
128
|
+
|
|
129
|
+
### Performance and resources
|
|
130
|
+
|
|
131
|
+
- **PR1 — No external-content inspection.** ProgressBar MUST NOT add DOM
|
|
132
|
+
observation, measurement, or relationship discovery to decide whether nearby
|
|
133
|
+
visible text makes a weaker bar acceptable.
|
|
134
|
+
|
|
135
|
+
## Accessibility contract
|
|
136
|
+
|
|
137
|
+
- **AR1 — Standalone non-text distinction.** A determinate bar MUST satisfy the
|
|
138
|
+
applicable non-text contrast requirement without relying on external visible
|
|
139
|
+
text.
|
|
140
|
+
- **AR2 — Programmatic semantics remain present.** The current required
|
|
141
|
+
accessible name and determinate value semantics remain independent of the
|
|
142
|
+
visible treatment.
|
|
143
|
+
- **AR3 — Supplementary text is not inferred.** ProgressBar MUST NOT claim that
|
|
144
|
+
external text is present, visible, equivalent, or correctly associated when it
|
|
145
|
+
cannot encode or verify those facts.
|
|
146
|
+
|
|
147
|
+
## Design relationships
|
|
148
|
+
|
|
149
|
+
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|
|
150
|
+
| ------------------------------------ | ------------------------------------------- | ------------------------ | -------------- | ------------------ |
|
|
151
|
+
| Determinate fill and remaining track | Sufficient standalone distinction | Unsettled | Prominent | FR1, AR1 |
|
|
152
|
+
| Built-in or external visible value | Supplements rather than enables correctness | Prescribed | Supporting | FR2, AR3 |
|
|
153
|
+
|
|
154
|
+
The component implements design requirements without copying their rationale.
|
|
155
|
+
The standalone visual remains a human design decision; this contract does not
|
|
156
|
+
invent its form.
|
|
157
|
+
|
|
158
|
+
## Family and system relationships
|
|
159
|
+
|
|
160
|
+
- `architecture:public-component-api` and `spec:AST-002/DEC-1` govern whether a
|
|
161
|
+
caller-owned distinction justifies a public prop.
|
|
162
|
+
- `architecture:component-theming-surface` governs which stable visible parts and
|
|
163
|
+
states become public theme capabilities.
|
|
164
|
+
- `architecture:theme-authoring-contract` governs how themes override those
|
|
165
|
+
component capabilities without creating a second component contract.
|
|
166
|
+
- `architecture:theme-tokens` governs the semantic token vocabulary used by the
|
|
167
|
+
eventual treatment.
|
|
168
|
+
|
|
169
|
+
## Verification map
|
|
170
|
+
|
|
171
|
+
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|
|
172
|
+
| ------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------- |
|
|
173
|
+
| 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 |
|
|
174
|
+
| 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 |
|
|
175
|
+
| AR2 | `ProgressBar.test.tsx` | Determinate, indeterminate, hidden label, custom value text | Accessible name or value semantics disappear when visuals change | Future ProgressBar accessibility audit |
|
|
176
|
+
| 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 |
|
|
177
|
+
|
|
178
|
+
## Decision log
|
|
179
|
+
|
|
180
|
+
### DEC-1 — ProgressBar owns a sufficient standalone visual
|
|
181
|
+
|
|
182
|
+
**Reference:** `component:ProgressBar/DEC-1`
|
|
183
|
+
**Decider:** `cixzhang`, `2026-08-30`
|
|
184
|
+
|
|
185
|
+
ProgressBar must provide a sufficient standalone visual. Visible text inside or
|
|
186
|
+
outside the component may improve understanding, but the bar remains responsible
|
|
187
|
+
for communicating completed versus remaining progress without it.
|
|
188
|
+
|
|
189
|
+
Public API must not make that correctness depend on external content the
|
|
190
|
+
component cannot carry, associate, or verify. Solve the component behavior first.
|
|
191
|
+
Consider new API only when a stable caller-owned distinction still remains after
|
|
192
|
+
the base behavior is correct.
|
|
193
|
+
|
|
194
|
+
Rejected: weakening the bar based on a caller claim about nearby content. That
|
|
195
|
+
would move component correctness into an external condition the component cannot
|
|
196
|
+
verify.
|
|
197
|
+
|
|
198
|
+
## Open questions
|
|
199
|
+
|
|
200
|
+
- **OQ1 — What exact visual treatment gives every determinate presentation a
|
|
201
|
+
sufficient standalone completed-versus-remaining distinction across supported
|
|
202
|
+
variants, themes, and color modes?** (`human-design`)
|
|
203
|
+
|
|
204
|
+
## Content boundary
|
|
205
|
+
|
|
206
|
+
This file does not duplicate consumer prop tables or examples, current audit
|
|
207
|
+
results, implementation steps, exact visual values, or system theming rules. It
|
|
208
|
+
links to their owners.
|