@astryxdesign/charts 0.6.2-canary.413fa55 → 0.6.2-canary.5dcd8dd
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/dist/ChartSwatch.js +3 -3
- package/package.json +3 -3
- package/src/ChartSwatch.doc.mjs +104 -2
- package/src/ChartSwatch.spec.md +189 -0
- package/src/ChartSwatch.tsx +3 -3
package/dist/ChartSwatch.js
CHANGED
|
@@ -2,10 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* @file ChartSwatch.tsx
|
|
5
|
+
* @input Caller-owned CSS color and optional square or line shape
|
|
5
6
|
* @output Color swatch primitive for legends, tooltips, and standalone use
|
|
6
|
-
* @position Composable primitive — used by ChartLegend
|
|
7
|
-
*
|
|
8
|
-
* is needed.
|
|
7
|
+
* @position Composable primitive — used by ChartLegend and ChartTooltip, or
|
|
8
|
+
* independently anywhere a series indicator is needed.
|
|
9
9
|
*
|
|
10
10
|
* @example
|
|
11
11
|
* ```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astryxdesign/charts",
|
|
3
|
-
"version": "0.6.2-canary.
|
|
3
|
+
"version": "0.6.2-canary.5dcd8dd",
|
|
4
4
|
"description": "Astryx charts — a config-model data visualization library (d3-based). Published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
|
|
5
5
|
"author": "Meta Open Source",
|
|
6
6
|
"license": "MIT",
|
|
@@ -47,7 +47,7 @@
|
|
|
47
47
|
},
|
|
48
48
|
"peerDependencies": {
|
|
49
49
|
"@stylexjs/stylex": ">=0.10.0",
|
|
50
|
-
"@astryxdesign/core": "0.6.2-canary.
|
|
50
|
+
"@astryxdesign/core": "0.6.2-canary.5dcd8dd",
|
|
51
51
|
"react": ">=19.0.0",
|
|
52
52
|
"react-dom": ">=19.0.0"
|
|
53
53
|
},
|
|
@@ -57,7 +57,7 @@
|
|
|
57
57
|
"d3-shape": "^3.2.0"
|
|
58
58
|
},
|
|
59
59
|
"devDependencies": {
|
|
60
|
-
"@astryxdesign/cli": "0.6.2-canary.
|
|
60
|
+
"@astryxdesign/cli": "0.6.2-canary.5dcd8dd",
|
|
61
61
|
"@babel/cli": "^7.29.7",
|
|
62
62
|
"@babel/core": "^7.29.7",
|
|
63
63
|
"@babel/preset-react": "^7.29.7",
|
package/src/ChartSwatch.doc.mjs
CHANGED
|
@@ -8,10 +8,112 @@ export const docs = {
|
|
|
8
8
|
group: 'Charts',
|
|
9
9
|
category: 'Data Visualization',
|
|
10
10
|
isHiddenFromOverview: true,
|
|
11
|
+
keywords: [
|
|
12
|
+
'chart',
|
|
13
|
+
'swatch',
|
|
14
|
+
'series',
|
|
15
|
+
'legend',
|
|
16
|
+
'tooltip',
|
|
17
|
+
'data visualization',
|
|
18
|
+
],
|
|
11
19
|
|
|
12
20
|
usage: {
|
|
13
|
-
description:
|
|
21
|
+
description:
|
|
22
|
+
'ChartSwatch renders the small decorative mark that pairs a chart series color with its visible label. Use a square for bar series and a short line for other series, including line, dot, and area marks.',
|
|
23
|
+
bestPractices: [
|
|
24
|
+
{
|
|
25
|
+
guidance: true,
|
|
26
|
+
description:
|
|
27
|
+
'Place every swatch next to visible text that names the corresponding series. ChartSwatch is decorative and stays hidden from assistive technology.',
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
guidance: true,
|
|
31
|
+
description:
|
|
32
|
+
'Use the square variant for bar series and the line variant for other mark types so legends and tooltips echo the plotted marks consistently.',
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
guidance: false,
|
|
36
|
+
description:
|
|
37
|
+
'Use ChartSwatch as the accessible name or data alternative for a series. Its surrounding legend, tooltip, or chart must provide that information.',
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
guidance: false,
|
|
41
|
+
description:
|
|
42
|
+
'Rely on arbitrary colors alone when multiple same-shaped series must be matched across a chart. Verify the complete chart and its labels together.',
|
|
43
|
+
},
|
|
44
|
+
],
|
|
45
|
+
accessibility: [
|
|
46
|
+
{
|
|
47
|
+
name: 'Decorative mark',
|
|
48
|
+
category: 'Semantics',
|
|
49
|
+
criterion: '1.1.1 Non-text Content',
|
|
50
|
+
requirement: 'Built in',
|
|
51
|
+
states: ['All'],
|
|
52
|
+
description:
|
|
53
|
+
'The swatch is hidden from assistive technology. Pair it with visible series text that supplies the accessible meaning.',
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
name: 'Series distinction',
|
|
57
|
+
category: 'Color contrast',
|
|
58
|
+
criterion: '1.4.1 Use of Color; 1.4.11 Non-text Contrast',
|
|
59
|
+
requirement: 'Consumer verification required',
|
|
60
|
+
states: ['All'],
|
|
61
|
+
description:
|
|
62
|
+
'Choose colors and, when necessary, additional labels or mark distinctions that remain understandable on the rendered chart surface.',
|
|
63
|
+
},
|
|
64
|
+
],
|
|
65
|
+
anatomy: [
|
|
66
|
+
{
|
|
67
|
+
name: 'Series swatch',
|
|
68
|
+
required: true,
|
|
69
|
+
description:
|
|
70
|
+
'Decorative square or short line painted with a caller-owned series color.',
|
|
71
|
+
},
|
|
72
|
+
],
|
|
14
73
|
},
|
|
15
74
|
|
|
16
|
-
|
|
75
|
+
playground: {
|
|
76
|
+
defaults: {
|
|
77
|
+
color: '#3b82f6',
|
|
78
|
+
variant: 'square',
|
|
79
|
+
},
|
|
80
|
+
},
|
|
81
|
+
|
|
82
|
+
props: [
|
|
83
|
+
{
|
|
84
|
+
name: 'color',
|
|
85
|
+
type: 'string',
|
|
86
|
+
description:
|
|
87
|
+
'CSS color used to paint the swatch. The caller owns palette selection and contrast on the rendered surface.',
|
|
88
|
+
required: true,
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
name: 'variant',
|
|
92
|
+
type: "'square' | 'line'",
|
|
93
|
+
description:
|
|
94
|
+
'Mark shape: use square for bar series and line for other series types.',
|
|
95
|
+
default: "'square'",
|
|
96
|
+
},
|
|
97
|
+
],
|
|
98
|
+
|
|
99
|
+
examples: [
|
|
100
|
+
{
|
|
101
|
+
label: 'Bar series swatch',
|
|
102
|
+
code: `import {ChartSwatch} from '@astryxdesign/charts';
|
|
103
|
+
|
|
104
|
+
<ChartSwatch color="#3b82f6" variant="square" />;`,
|
|
105
|
+
},
|
|
106
|
+
{
|
|
107
|
+
label: 'Series-driven swatch',
|
|
108
|
+
code: `import {
|
|
109
|
+
ChartSwatch,
|
|
110
|
+
swatchVariantForType,
|
|
111
|
+
} from '@astryxdesign/charts';
|
|
112
|
+
|
|
113
|
+
<ChartSwatch
|
|
114
|
+
color={series.color}
|
|
115
|
+
variant={swatchVariantForType(series.type)}
|
|
116
|
+
/>;`,
|
|
117
|
+
},
|
|
118
|
+
],
|
|
17
119
|
};
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
---
|
|
2
|
+
schema_version: 3
|
|
3
|
+
template_version: 5
|
|
4
|
+
kind: component
|
|
5
|
+
id: component:ChartSwatch
|
|
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, layout, theming, accessibility]
|
|
13
|
+
verified_by:
|
|
14
|
+
[
|
|
15
|
+
packages/charts/src/ChartSwatch.test.tsx,
|
|
16
|
+
apps/storybook/stories/charts/Swatch.stories.tsx,
|
|
17
|
+
]
|
|
18
|
+
modules: []
|
|
19
|
+
families: []
|
|
20
|
+
design_specs: []
|
|
21
|
+
architecture:
|
|
22
|
+
[
|
|
23
|
+
architecture:component-test-sufficiency,
|
|
24
|
+
architecture:component-theming-surface,
|
|
25
|
+
architecture:knowledge-contracts,
|
|
26
|
+
]
|
|
27
|
+
contributing: []
|
|
28
|
+
system_specs: [spec:AST-002, spec:AST-029]
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
# ChartSwatch component contract
|
|
32
|
+
|
|
33
|
+
## Contract at a glance
|
|
34
|
+
|
|
35
|
+
| Area | Contract |
|
|
36
|
+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
37
|
+
| Public contract | No API shape or default changes. This draft records the current caller-owned color, square/line shape, and exported series-type mapping utility. |
|
|
38
|
+
| Behavior | Omitted `variant` renders a square; explicit `line` renders a short stroke; `swatchVariantForType` maps `bar` to square and every other or omitted type to line. |
|
|
39
|
+
| End-user impact | Chart readers keep the same decorative mark-shaped color keys next to visible series labels; this audit changes no rendered behavior. |
|
|
40
|
+
| Builder impact | Existing callsites remain valid and gain consumer documentation for the shipped props, defaults, composition, and accessibility boundary. |
|
|
41
|
+
| Compatibility/readiness | The package remains canary-only. This observational draft is non-authoritative; the public utility name and future theming reachability remain unresolved owner choices. |
|
|
42
|
+
| Review checks | Reject a changed default or type mapping, lost decorative semantics, geometry drift presented as policy, or a claim that color alone always identifies a series. |
|
|
43
|
+
| Governing rules | `spec:AST-029/FR3–FR7`, `architecture:component-test-sufficiency/INV1–INV11`, `architecture:component-theming-surface/INV1–INV11`, and `spec:AST-002/FR17`. |
|
|
44
|
+
|
|
45
|
+
This table is a review projection; the body below is authoritative.
|
|
46
|
+
|
|
47
|
+
## Intent
|
|
48
|
+
|
|
49
|
+
ChartSwatch paints a compact decorative key that visually connects a series label
|
|
50
|
+
to a chart mark. It owns the square and line shapes and the current mapping from a
|
|
51
|
+
series type to those shapes. A legend, tooltip, chart, or product callsite owns the
|
|
52
|
+
visible series name and the surrounding relationship.
|
|
53
|
+
|
|
54
|
+
## Compatibility and migration
|
|
55
|
+
|
|
56
|
+
- Released default preserved: yes at the canary surface; the package has no stable release.
|
|
57
|
+
- Compatibility class: no public API, default, or rendered-behavior change.
|
|
58
|
+
- Controlled/uncontrolled behavior: not applicable.
|
|
59
|
+
- Migration decision: none; this draft does not authorize a public utility rename or removal.
|
|
60
|
+
|
|
61
|
+
Consumer migration instructions belong in consumer docs and release notes.
|
|
62
|
+
|
|
63
|
+
## Ownership boundary
|
|
64
|
+
|
|
65
|
+
**Owns**
|
|
66
|
+
|
|
67
|
+
- Painting one caller-owned color as a compact square or line.
|
|
68
|
+
- Keeping the swatch decorative to assistive technology.
|
|
69
|
+
- Mapping a `bar` series type to square and every other or omitted type to line.
|
|
70
|
+
|
|
71
|
+
**Does not own / non-goals**
|
|
72
|
+
|
|
73
|
+
- Selecting, validating, or adapting a chart palette — owned by the chart and product callsite.
|
|
74
|
+
- Naming a series or supplying an accessible chart alternative — owned by the surrounding legend, tooltip, Chart, or product callsite.
|
|
75
|
+
- Establishing that color alone distinguishes series across the plotted chart and its chrome.
|
|
76
|
+
- Interaction, selection, filtering, visibility, or tooltip behavior.
|
|
77
|
+
|
|
78
|
+
## Public concepts
|
|
79
|
+
|
|
80
|
+
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|
|
81
|
+
| ---------------- | -------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------- | -------- | ----------------------- | ------------ | -------------------------------------------------------------- |
|
|
82
|
+
| Series color | caller-owned CSS color string | Paints the decorative mark. | Every ChartSwatch | required | product callsite | experimental | Invalid CSS color syntax may leave the swatch without a paint. |
|
|
83
|
+
| Swatch shape | `square`, `line` | Visually echoes a bar or non-bar chart mark. | Every ChartSwatch | `square` | `component:ChartSwatch` | experimental | Closed by the exported TypeScript union. |
|
|
84
|
+
| Series-type map | `bar`; every other string; omitted | Converts a series type to the component's two supported shapes. | Exported utility | line | `component:ChartSwatch` | experimental | Unknown and omitted types use the line shape. |
|
|
85
|
+
| AT participation | decorative, hidden from assistive technology | Leaves the surrounding visible text responsible for meaning. | Every ChartSwatch | built in | `component:ChartSwatch` | experimental | Not configurable. |
|
|
86
|
+
|
|
87
|
+
## Behavioral and layout contract
|
|
88
|
+
|
|
89
|
+
Draft requirements identify their basis so observed code is not mistaken for an
|
|
90
|
+
intentional decision.
|
|
91
|
+
|
|
92
|
+
| ID | Candidate invariant | Basis | Draft review state |
|
|
93
|
+
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------ |
|
|
94
|
+
| FR1 | ChartSwatch MUST render one decorative element and MUST use `square` when `variant` is omitted. | implementation, focused tests, and browser sensors | verify |
|
|
95
|
+
| FR2 | Square MUST currently render as an 8 by 8 mark with 2 radius and 1 inline margin; line MUST currently render as a 10 by 3 mark with 1.5 radius. | implementation and receipted browser matrix | verify |
|
|
96
|
+
| FR3 | The rendered paint MUST follow the caller-supplied `color` without choosing or adapting a palette. | implementation, focused tests, and browser sensors | verify |
|
|
97
|
+
| FR4 | The swatch MUST remain hidden from assistive technology; surrounding content MUST provide the visible and accessible series meaning. | implementation, focused tests, focused axe, and browsers | verify |
|
|
98
|
+
| FR5 | `swatchVariantForType` MUST return `square` only for `bar` and MUST return `line` for every other string and for `undefined`. | implementation and focused tests | verify |
|
|
99
|
+
| FR6 | Light, dark, narrow, and coarse-pointer media MUST NOT change the component-owned shape contract or introduce horizontal viewport overflow. | receipted browser matrix | verify |
|
|
100
|
+
|
|
101
|
+
### Allowed variation
|
|
102
|
+
|
|
103
|
+
- **AV1 — Series paint.** Any valid caller-owned CSS color may paint either shape.
|
|
104
|
+
- **AV2 — Surrounding layout.** A legend, tooltip, or custom callsite may position the swatch anywhere that preserves its association with a visible series label.
|
|
105
|
+
|
|
106
|
+
### Representative states
|
|
107
|
+
|
|
108
|
+
| State | Required invariant | Allowed variation |
|
|
109
|
+
| ----------------------- | ---------------------------------------------------- | --------------------------------------------------------- |
|
|
110
|
+
| Omitted / square | Square geometry and decorative semantics remain. | Caller color and surrounding placement may vary. |
|
|
111
|
+
| Line | Line geometry and decorative semantics remain. | Caller color and surrounding placement may vary. |
|
|
112
|
+
| `bar` mapping | Utility returns `square`. | Source series definition may carry other fields. |
|
|
113
|
+
| Non-bar / omitted map | Utility returns `line`. | Unknown and future non-bar type strings use the fallback. |
|
|
114
|
+
| Light / dark | Shape and supplied paint remain unchanged. | Surrounding surface follows its active theme. |
|
|
115
|
+
| Narrow / coarse pointer | No component-owned overflow or interaction is added. | Surrounding layout may wrap or reposition the swatch. |
|
|
116
|
+
|
|
117
|
+
### Transformation and precedence order
|
|
118
|
+
|
|
119
|
+
- **ORD1 — Render.** Apply the default variant when omitted → select square or line geometry → paint with caller color → hide the resulting element from assistive technology.
|
|
120
|
+
- **ORD2 — Series mapping.** Compare the series type with `bar` → return square for the exact match → return line otherwise.
|
|
121
|
+
|
|
122
|
+
### Performance and resources
|
|
123
|
+
|
|
124
|
+
- **PR1 — No persistent resources.** Rendering, rerendering, and unmounting ChartSwatch MUST NOT create or retain a listener, observer, timer, request, subscription, or other persistent browser resource, and MUST require no consumer cleanup.
|
|
125
|
+
|
|
126
|
+
## Accessibility contract
|
|
127
|
+
|
|
128
|
+
- **AR1 — Decorative mark.** ChartSwatch stays hidden from assistive technology because its surrounding visible series label supplies the meaning.
|
|
129
|
+
- **AR2 — Meaningful context.** A standalone callsite pairs the swatch with visible text; the swatch does not replace a Chart accessible name, equivalent data view, or summary.
|
|
130
|
+
- **AR3 — Series distinction.** Evidence for whether same-shaped series need an additional association cue must cover the composed chart and its labels, not the isolated decorative swatch.
|
|
131
|
+
|
|
132
|
+
## Design relationships
|
|
133
|
+
|
|
134
|
+
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|
|
135
|
+
| ---------------- | ---------------------------------------------------------- | --------------------------------------------- | -------------- | ------------------ |
|
|
136
|
+
| Series swatch | Echo the chart mark while remaining decorative to AT. | unsettled; no current design record is linked | supporting | FR1–FR6, AR1–AR3 |
|
|
137
|
+
| Square shape | Represent the current bar-series mapping. | observed implementation | supporting | FR1–FR2, FR5 |
|
|
138
|
+
| Line shape | Represent the current non-bar and fallback series mapping. | observed implementation | supporting | FR2, FR5 |
|
|
139
|
+
|
|
140
|
+
### Theming anatomy
|
|
141
|
+
|
|
142
|
+
<!-- anatomy-theming:v1 -->
|
|
143
|
+
|
|
144
|
+
```json
|
|
145
|
+
{
|
|
146
|
+
"Series swatch": {
|
|
147
|
+
"none": {
|
|
148
|
+
"reason": "unsettled: caller-owned color and fixed component geometry currently paint the swatch without a public theme target; this draft does not decide future reachability."
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
ChartSwatch is the visible painter but exposes no current public theme target.
|
|
155
|
+
Whether themes should gain a stable target remains an owner decision.
|
|
156
|
+
|
|
157
|
+
## Family and system relationships
|
|
158
|
+
|
|
159
|
+
- No current family or design record governs ChartSwatch.
|
|
160
|
+
- `architecture:component-test-sufficiency` owns rational public-state partitions, observable assertions, and audit evidence quality.
|
|
161
|
+
- `architecture:component-theming-surface` owns anatomy-to-target disposition; this draft records current absence without deciding future themeability.
|
|
162
|
+
- `architecture:knowledge-contracts` keeps consumer syntax in `ChartSwatch.doc.mjs` and observed behavior in this draft component record.
|
|
163
|
+
- `spec:AST-002/FR17` owns the unresolved public utility naming question.
|
|
164
|
+
- `spec:AST-029` owns this observational backfill, closed evidence receipt, safe remediation, and fail-closed eligibility report.
|
|
165
|
+
|
|
166
|
+
## Verification map
|
|
167
|
+
|
|
168
|
+
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|
|
169
|
+
| -------- | ------------------------------------------------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------- |
|
|
170
|
+
| FR1–FR3 | `ChartSwatch.test.tsx`; receipted browser matrix | omitted, square, line, six colors, light, dark | Default, geometry, or caller paint changes without visible evidence. | `audit:ChartSwatch/behavior-design` |
|
|
171
|
+
| FR4 | focused DOM assertion; focused axe; browser sensors | square, line, light, dark | The swatch enters the accessibility tree or surrounding meaning is assigned to the mark. | `audit:ChartSwatch/accessibility` |
|
|
172
|
+
| FR5 | `ChartSwatch.test.tsx` | bar, line, dot, area, unknown, omitted | A bar loses its square or another type gains one. | `audit:ChartSwatch/public-utility-behavior` |
|
|
173
|
+
| FR6 | receipted Storybook browser matrix | 1280 px, 320 px, coarse pointer, light, dark | Shape changes, overflow appears, or the component gains a media-dependent behavior. | `audit:ChartSwatch/responsive-rendered-design` |
|
|
174
|
+
| AR1–AR3 | focused axe; ChartLegend and ChartTooltip composition review | standalone and composed use | Decorative semantics are lost or isolated evidence is used to decide chart association. | `audit:ChartSwatch/accessibility-composition` |
|
|
175
|
+
|
|
176
|
+
## Decision log
|
|
177
|
+
|
|
178
|
+
None. This draft records observed behavior and evidence gaps only.
|
|
179
|
+
|
|
180
|
+
## Open questions
|
|
181
|
+
|
|
182
|
+
- **OQ1 — Public utility name.** Should the series-type mapping remain public and, if so, what verb-led name and compatibility path satisfy `spec:AST-002/FR17`? (`human-api`)
|
|
183
|
+
- **OQ2 — Swatch theming reachability.** Should ChartSwatch expose a public theme target, or should its paint and geometry remain caller/component owned? (`human-api`)
|
|
184
|
+
- **OQ3 — Composed series association.** Does a composed chart with multiple same-shaped series need an additional association cue, and which layer owns it? (`human-design`)
|
|
185
|
+
|
|
186
|
+
## Content boundary
|
|
187
|
+
|
|
188
|
+
This file does not duplicate consumer prop tables/examples, current audit results,
|
|
189
|
+
implementation steps, or shared system rules. It links to their owners.
|
package/src/ChartSwatch.tsx
CHANGED
|
@@ -2,10 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* @file ChartSwatch.tsx
|
|
5
|
+
* @input Caller-owned CSS color and optional square or line shape
|
|
5
6
|
* @output Color swatch primitive for legends, tooltips, and standalone use
|
|
6
|
-
* @position Composable primitive — used by ChartLegend
|
|
7
|
-
*
|
|
8
|
-
* is needed.
|
|
7
|
+
* @position Composable primitive — used by ChartLegend and ChartTooltip, or
|
|
8
|
+
* independently anywhere a series indicator is needed.
|
|
9
9
|
*
|
|
10
10
|
* @example
|
|
11
11
|
* ```
|