@astryxdesign/charts 0.6.2-canary.cdde227 → 0.6.2-canary.d4cc232
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/ChartLegend.doc.mjs +146 -0
- package/src/ChartLegend.spec.md +203 -0
- 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.d4cc232",
|
|
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.d4cc232",
|
|
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.d4cc232",
|
|
61
61
|
"@babel/cli": "^7.29.7",
|
|
62
62
|
"@babel/core": "^7.29.7",
|
|
63
63
|
"@babel/preset-react": "^7.29.7",
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
// Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
2
|
+
|
|
3
|
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
|
|
4
|
+
|
|
5
|
+
export const docs = {
|
|
6
|
+
name: 'ChartLegend',
|
|
7
|
+
displayName: 'Chart Legend',
|
|
8
|
+
group: 'Charts',
|
|
9
|
+
category: 'Data Visualization',
|
|
10
|
+
isHiddenFromOverview: true,
|
|
11
|
+
keywords: ['chart', 'legend', 'series', 'key', 'label', 'data visualization'],
|
|
12
|
+
|
|
13
|
+
usage: {
|
|
14
|
+
description:
|
|
15
|
+
'ChartLegend pairs series labels with decorative mark-shaped color swatches. Use Chart legend options for the generated legend, or render ChartLegend directly when the caller already owns the legend items.',
|
|
16
|
+
bestPractices: [
|
|
17
|
+
{
|
|
18
|
+
guidance: true,
|
|
19
|
+
description:
|
|
20
|
+
'Give every item a concise label that identifies the corresponding series without relying on its color name.',
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
guidance: true,
|
|
24
|
+
description:
|
|
25
|
+
'Use start or end for a vertical legend and top or bottom for a wrapping horizontal legend.',
|
|
26
|
+
},
|
|
27
|
+
{
|
|
28
|
+
guidance: false,
|
|
29
|
+
description:
|
|
30
|
+
'Use the legend as the chart’s only text alternative. Give the parent Chart an accessible name and preserve an equivalent data view or summary when the data requires one.',
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
guidance: false,
|
|
34
|
+
description:
|
|
35
|
+
'Assume arbitrary series colors will remain distinguishable in every theme. Verify the complete chart and legend together against the surfaces where they render.',
|
|
36
|
+
},
|
|
37
|
+
],
|
|
38
|
+
accessibility: [
|
|
39
|
+
{
|
|
40
|
+
name: 'Named list',
|
|
41
|
+
category: 'Semantics',
|
|
42
|
+
criterion: '1.3.1 Info and Relationships',
|
|
43
|
+
requirement: 'Built in',
|
|
44
|
+
states: ['Non-empty'],
|
|
45
|
+
description:
|
|
46
|
+
'Entries render as items in a localized Chart legend list. Each visible label supplies the series name while its swatch stays hidden from assistive technology.',
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
name: 'Chart alternative',
|
|
50
|
+
category: 'Content',
|
|
51
|
+
criterion: '1.1.1 Non-text Content',
|
|
52
|
+
requirement: 'Required on the parent Chart',
|
|
53
|
+
states: ['All'],
|
|
54
|
+
description:
|
|
55
|
+
'The legend supplements the parent Chart. It does not replace the Chart accessible name, data table, summary, or other equivalent alternative.',
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
name: 'Series distinction',
|
|
59
|
+
category: 'Color contrast',
|
|
60
|
+
criterion: '1.4.1 Use of Color; 1.4.11 Non-text Contrast',
|
|
61
|
+
requirement: 'Consumer verification required',
|
|
62
|
+
states: ['Non-empty'],
|
|
63
|
+
description:
|
|
64
|
+
'Caller-supplied series colors must remain distinguishable on the rendered surface. Do not depend on color alone when otherwise identical marks need to be matched across the chart and legend.',
|
|
65
|
+
},
|
|
66
|
+
],
|
|
67
|
+
anatomy: [
|
|
68
|
+
{
|
|
69
|
+
name: 'Legend list',
|
|
70
|
+
required: true,
|
|
71
|
+
description:
|
|
72
|
+
'Wrapping horizontal or stacked vertical list that groups the legend entries.',
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
name: 'Legend entry',
|
|
76
|
+
required: true,
|
|
77
|
+
description: 'One series label paired with its decorative swatch.',
|
|
78
|
+
},
|
|
79
|
+
{
|
|
80
|
+
name: 'Series swatch',
|
|
81
|
+
required: true,
|
|
82
|
+
description:
|
|
83
|
+
'Decorative square for bar marks or short line for other mark types, painted with the item color.',
|
|
84
|
+
},
|
|
85
|
+
{
|
|
86
|
+
name: 'Series label',
|
|
87
|
+
required: true,
|
|
88
|
+
description: 'Supporting text that names the series.',
|
|
89
|
+
},
|
|
90
|
+
],
|
|
91
|
+
},
|
|
92
|
+
|
|
93
|
+
props: [
|
|
94
|
+
{
|
|
95
|
+
name: 'items',
|
|
96
|
+
type: 'LegendItem[]',
|
|
97
|
+
description:
|
|
98
|
+
'Series entries to render. Each entry supplies a label, color, and optional mark type. An omitted or empty array renders nothing.',
|
|
99
|
+
default: '[]',
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
name: 'position',
|
|
103
|
+
type: "'top' | 'bottom' | 'start' | 'end'",
|
|
104
|
+
description:
|
|
105
|
+
'Logical placement used by Chart and the legend orientation: top and bottom are horizontal; start and end are vertical.',
|
|
106
|
+
default: "'bottom'",
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
name: 'alignment',
|
|
110
|
+
type: "'start' | 'center' | 'end'",
|
|
111
|
+
description:
|
|
112
|
+
'For top and bottom, distributes the row along its inline axis. For start and end, aligns each entry horizontally within the vertical list.',
|
|
113
|
+
default: "'start'",
|
|
114
|
+
},
|
|
115
|
+
],
|
|
116
|
+
|
|
117
|
+
examples: [
|
|
118
|
+
{
|
|
119
|
+
label: 'Generated chart legend',
|
|
120
|
+
code: `import {Chart, bar, line} from '@astryxdesign/charts';
|
|
121
|
+
|
|
122
|
+
<Chart
|
|
123
|
+
data={monthlyRevenue}
|
|
124
|
+
xKey="month"
|
|
125
|
+
series={[
|
|
126
|
+
bar('revenue', {label: 'Revenue'}),
|
|
127
|
+
line('forecast', {label: 'Forecast'}),
|
|
128
|
+
]}
|
|
129
|
+
legend={{position: 'top', alignment: 'start'}}
|
|
130
|
+
/>;`,
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
label: 'Standalone legend',
|
|
134
|
+
code: `import {ChartLegend} from '@astryxdesign/charts';
|
|
135
|
+
|
|
136
|
+
<ChartLegend
|
|
137
|
+
items={[
|
|
138
|
+
{label: 'Revenue', color: '#3b82f6', type: 'bar'},
|
|
139
|
+
{label: 'Forecast', color: '#f59e0b', type: 'line'},
|
|
140
|
+
]}
|
|
141
|
+
position="start"
|
|
142
|
+
alignment="center"
|
|
143
|
+
/>;`,
|
|
144
|
+
},
|
|
145
|
+
],
|
|
146
|
+
};
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
---
|
|
2
|
+
schema_version: 3
|
|
3
|
+
template_version: 5
|
|
4
|
+
kind: component
|
|
5
|
+
id: component:ChartLegend
|
|
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/ChartLegend.test.tsx,
|
|
16
|
+
apps/storybook/stories/charts/Legend.stories.tsx,
|
|
17
|
+
]
|
|
18
|
+
modules: []
|
|
19
|
+
families: []
|
|
20
|
+
design_specs: []
|
|
21
|
+
architecture:
|
|
22
|
+
[
|
|
23
|
+
architecture:component-test-sufficiency,
|
|
24
|
+
architecture:component-theming-surface,
|
|
25
|
+
]
|
|
26
|
+
contributing: []
|
|
27
|
+
system_specs: [spec:AST-002, spec:AST-029]
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
# ChartLegend component contract
|
|
31
|
+
|
|
32
|
+
## Contract at a glance
|
|
33
|
+
|
|
34
|
+
| Area | Contract |
|
|
35
|
+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
36
|
+
| Public contract | No API shape or default changes. This draft records the current item, logical placement, alignment, list-semantics, and empty-output surface. |
|
|
37
|
+
| Behavior | Non-empty items render in order as a named list; top/bottom use a wrapping row, start/end use a column, alignment remains logical, and omitted or empty items render nothing. |
|
|
38
|
+
| End-user impact | Chart readers receive visible series names paired with decorative mark-shaped color keys; this audit changes no rendered behavior. |
|
|
39
|
+
| Builder impact | Existing callsites remain valid and gain direct CLI documentation for the shipped props, defaults, composition, and accessibility boundary. |
|
|
40
|
+
| Compatibility/readiness | The package remains canary-only. This observational draft is non-authoritative; series distinction by arbitrary caller colors remains unresolved. |
|
|
41
|
+
| Review checks | Reject a changed public shape/default, lost list semantics or localization, reordered items, a wrong orientation, or a new claim that color alone is sufficient. |
|
|
42
|
+
| Governing rules | `spec:AST-029/FR3–FR7`, `architecture:component-test-sufficiency/INV1–INV11`, `architecture:component-theming-surface/INV1–INV6`, and `spec:AST-002`. |
|
|
43
|
+
|
|
44
|
+
This table is a review projection; the body below is authoritative.
|
|
45
|
+
|
|
46
|
+
## Intent
|
|
47
|
+
|
|
48
|
+
ChartLegend presents the visible key for a chart's series. It owns the ordered
|
|
49
|
+
legend list, entry layout, mark-shaped decorative swatches, series labels, and
|
|
50
|
+
the empty render. A parent Chart may derive its items and place the resulting
|
|
51
|
+
legend around the plot; callers may also render the component directly.
|
|
52
|
+
|
|
53
|
+
## Compatibility and migration
|
|
54
|
+
|
|
55
|
+
- Released default preserved: yes at the canary surface; the package has no stable release.
|
|
56
|
+
- Compatibility class: no public API, default, or rendered-behavior change.
|
|
57
|
+
- Controlled/uncontrolled behavior: not applicable.
|
|
58
|
+
- Migration decision: none; this draft does not authorize a public API change.
|
|
59
|
+
|
|
60
|
+
Consumer migration instructions belong in consumer docs and release notes.
|
|
61
|
+
|
|
62
|
+
## Ownership boundary
|
|
63
|
+
|
|
64
|
+
**Owns**
|
|
65
|
+
|
|
66
|
+
- Rendering non-empty legend items in caller order.
|
|
67
|
+
- Choosing horizontal or vertical layout from logical placement.
|
|
68
|
+
- Aligning the entry collection along the relevant logical axis.
|
|
69
|
+
- Pairing each visible series label with a decorative swatch shape and caller color.
|
|
70
|
+
- Localizing and exposing the legend list name.
|
|
71
|
+
|
|
72
|
+
**Does not own / non-goals**
|
|
73
|
+
|
|
74
|
+
- Series derivation, palette assignment, plot placement, or chart render order — owned by `component:Chart` and its series utilities.
|
|
75
|
+
- The chart's accessible name, data alternative, or product summary — owned by `component:Chart` and the product callsite.
|
|
76
|
+
- Custom legend interactions, selection, filtering, or visibility controls.
|
|
77
|
+
- A guarantee that arbitrary caller-supplied colors alone distinguish every series.
|
|
78
|
+
|
|
79
|
+
## Public concepts
|
|
80
|
+
|
|
81
|
+
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|
|
82
|
+
| ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------- | -------- | ----------------------- | ------------ | --------------------------------------------- |
|
|
83
|
+
| Legend items | ordered array or empty | Supplies each entry's label, color, and optional mark type. | Every ChartLegend | `[]` | `component:ChartLegend` | experimental | Omitted and empty arrays render nothing. |
|
|
84
|
+
| Logical position | `top`, `bottom`, `start`, `end` | Gives Chart placement intent and selects row or column orientation. | Non-empty | `bottom` | `component:ChartLegend` | experimental | Closed by the exported TypeScript union. |
|
|
85
|
+
| Alignment | `start`, `center`, `end` | Distributes a horizontal row inline or aligns entries horizontally inside a vertical list. | Non-empty | `start` | `component:ChartLegend` | experimental | Closed by the exported TypeScript union. |
|
|
86
|
+
| Swatch shape | square for `bar`; line for every other type | Visually echoes the item's mark category without adding AT content. | Each rendered item | line | `component:ChartSwatch` | experimental | Unknown and omitted types use the line shape. |
|
|
87
|
+
| List semantics | localized list with one item per entry | Groups the visible labels as one named legend. | Non-empty | built in | `component:ChartLegend` | experimental | Not applicable. |
|
|
88
|
+
|
|
89
|
+
## Behavioral and layout contract
|
|
90
|
+
|
|
91
|
+
Draft requirements identify their basis so observed code is not mistaken for an
|
|
92
|
+
intentional decision.
|
|
93
|
+
|
|
94
|
+
| ID | Candidate invariant | Basis | Draft review state |
|
|
95
|
+
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------ |
|
|
96
|
+
| FR1 | ChartLegend MUST render nothing when `items` is omitted or empty and MUST otherwise preserve item order and duplicate labels. | implementation and focused tests | verify |
|
|
97
|
+
| FR2 | Each rendered item MUST remain one visible label plus one assistive-technology-hidden ChartSwatch inside a list item. | implementation, focused tests, and browser accessibility run | verify |
|
|
98
|
+
| FR3 | The root MUST remain a localized named list with exactly one list item per supplied entry. | implementation, locale catalog, focused tests, and axe | verify |
|
|
99
|
+
| FR4 | `top` and `bottom` MUST use a wrapping horizontal row; `start` and `end` MUST use a vertical column. | implementation and receipted browser matrix | verify |
|
|
100
|
+
| FR5 | Alignment MUST remain logical: for `top` and `bottom`, it distributes the row along the inline axis; for `start` and `end`, it aligns entries horizontally within the vertical list, including under RTL. | implementation and receipted LTR/RTL browser evidence | verify |
|
|
101
|
+
| FR6 | Swatch shape MUST be square for `bar` and a short line for every other or omitted type; caller color supplies its paint. | ChartSwatch implementation and focused tests | verify |
|
|
102
|
+
| FR7 | Long labels MUST wrap without horizontal viewport overflow at 320 CSS pixels; no fixed-width truncation contract is currently exposed. | receipted browser evidence | verify |
|
|
103
|
+
|
|
104
|
+
### Allowed variation
|
|
105
|
+
|
|
106
|
+
- **AV1 — Available space.** Horizontal entries wrap to additional rows as the containing width narrows; vertical entry labels may wrap within the available inline size.
|
|
107
|
+
- **AV2 — Series paint.** Swatch color is caller-owned and may vary by chart palette and rendered surface, subject to the unresolved distinction requirement below.
|
|
108
|
+
|
|
109
|
+
### Representative states
|
|
110
|
+
|
|
111
|
+
| State | Required invariant | Allowed variation |
|
|
112
|
+
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
113
|
+
| Omitted / empty items | No legend DOM is rendered. | Surrounding Chart layout may omit its legend slot. |
|
|
114
|
+
| Bottom or top | Entries form a wrapping horizontal list. | Logical alignment and wrapping depend on available width. |
|
|
115
|
+
| Start or end | Entries form a vertical list. | Alignment changes each entry's horizontal position within the list. |
|
|
116
|
+
| Duplicate labels | Every supplied item remains present and ordered. | Internal React keys may disambiguate equal labels. |
|
|
117
|
+
| Long narrow labels | Labels wrap and the page remains free of horizontal overflow. | Entry and list height grow with content. |
|
|
118
|
+
| RTL | Logical start/end behavior follows the computed document direction. | Visual item order follows the flex and direction model. |
|
|
119
|
+
|
|
120
|
+
### Transformation and precedence order
|
|
121
|
+
|
|
122
|
+
- **ORD1 — Render.** Default omitted props → return nothing for zero items → derive orientation from logical position → map items in caller order → apply logical alignment to the list root.
|
|
123
|
+
- **ORD2 — Entry.** Map mark type to a swatch shape → paint the swatch with caller color → render the caller label as supporting text.
|
|
124
|
+
|
|
125
|
+
### Performance and resources
|
|
126
|
+
|
|
127
|
+
- **PR1 — Derived output.** ChartLegend remains render-derived. It owns no state, Effect, listener, observer, timer, request, or persistent resource.
|
|
128
|
+
|
|
129
|
+
## Accessibility contract
|
|
130
|
+
|
|
131
|
+
- **AR1 — Named structure.** A non-empty legend exposes one localized named list and one list item for every visible series label.
|
|
132
|
+
- **AR2 — Decorative swatches.** Series swatches stay hidden from assistive technology; the adjacent visible text supplies each entry name.
|
|
133
|
+
- **AR3 — Chart-level alternative.** The legend supplements rather than replaces the parent Chart's accessible name and equivalent data representation.
|
|
134
|
+
- **AR4 — Composed association evidence.** Standalone ChartLegend evidence does not establish how readers associate legend entries with rendered chart marks. Evaluate same-mark-shape series in a composed Chart or product callsite before deciding whether an additional visual cue is needed or which layer owns it.
|
|
135
|
+
|
|
136
|
+
## Design relationships
|
|
137
|
+
|
|
138
|
+
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|
|
139
|
+
| ---------------- | ----------------------------------------------------------------- | --------------------------------------------- | -------------- | ------------------ |
|
|
140
|
+
| Legend list | Group related series entries without adding an interactive state. | unsettled; no current design record is linked | supporting | FR1, FR3–FR5 |
|
|
141
|
+
| Legend entry | Keep each label associated with one series key. | unsettled; no current design record is linked | supporting | FR1–FR3 |
|
|
142
|
+
| Series swatch | Echo the chart mark while remaining decorative to AT. | unsettled; caller color is current behavior | supporting | FR2, FR6, AR2–AR4 |
|
|
143
|
+
| Series label | Name the series as readable supporting text. | delegated to Text | supporting | FR2, AR1–AR2 |
|
|
144
|
+
|
|
145
|
+
### Theming anatomy
|
|
146
|
+
|
|
147
|
+
<!-- anatomy-theming:v1 -->
|
|
148
|
+
|
|
149
|
+
```json
|
|
150
|
+
{
|
|
151
|
+
"Legend list": {
|
|
152
|
+
"delegatesTo": {"owner": "component:Stack", "target": "stack"}
|
|
153
|
+
},
|
|
154
|
+
"Legend entry": {
|
|
155
|
+
"delegatesTo": {"owner": "component:Stack", "target": "stack"}
|
|
156
|
+
},
|
|
157
|
+
"Series swatch": {
|
|
158
|
+
"none": {
|
|
159
|
+
"reason": "unsettled: ChartSwatch owns the visible painter but exposes no current public target; this draft does not decide future reachability."
|
|
160
|
+
}
|
|
161
|
+
},
|
|
162
|
+
"Series label": {
|
|
163
|
+
"delegatesTo": {"owner": "component:Text", "target": "text"}
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
ChartLegend delegates list and entry layout to Stack's existing target, and
|
|
169
|
+
series labels to Text. ChartSwatch is the visible swatch painter but does not
|
|
170
|
+
currently expose a public theme target. Whether that anatomy should become
|
|
171
|
+
reachable remains with the ChartSwatch and theming owners.
|
|
172
|
+
|
|
173
|
+
## Family and system relationships
|
|
174
|
+
|
|
175
|
+
- No current family or design record governs ChartLegend.
|
|
176
|
+
- `architecture:component-test-sufficiency` owns rational public-state partitions, observable assertions, and audit evidence quality.
|
|
177
|
+
- `architecture:component-theming-surface` owns anatomy-to-target disposition; composition from themed primitives does not enroll ChartLegend in public component theming.
|
|
178
|
+
- `spec:AST-002` owns public API admission and prevents this audit from adding or reinterpreting a public choice.
|
|
179
|
+
- `spec:AST-029` owns this observational backfill, closed evidence receipt, safe remediation, and fail-closed eligibility report.
|
|
180
|
+
|
|
181
|
+
## Verification map
|
|
182
|
+
|
|
183
|
+
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|
|
184
|
+
| ------------ | -------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
|
|
185
|
+
| FR1–FR3 | `ChartLegend.test.tsx`; focused axe run | omitted, empty, non-empty, localized, duplicate | Empty output leaves DOM, an entry disappears, or list semantics/name are lost. | `audit:ChartLegend/accessibility-behavior` |
|
|
186
|
+
| FR4–FR5, FR7 | receipted Storybook browser matrix; RTL geometry receipt | row, column, all alignments, 320px long text, RTL | Orientation, logical alignment, wrapping, or viewport containment changes. | `audit:ChartLegend/layout-responsive-rtl` |
|
|
187
|
+
| FR6 | `ChartLegend.test.tsx`; `ChartSwatch.test.tsx` | bar, line, omitted and unknown types | A bar loses its square, another type gains one, or swatch paint stops following color. | `audit:ChartLegend/behavior-design` |
|
|
188
|
+
| AR1–AR3 | role/name DOM assertions; focused axe run; Chart tests | standalone and Chart-composed legend | Labels leave the named list or the legend replaces the Chart alternative. | `audit:ChartLegend/accessibility` |
|
|
189
|
+
| AR4 | future composed Chart/callsite browser evidence | at least two same-mark-shape series and their rendered marks | Association evidence must cover the legend and plotted marks before recording a defect or assigning an owner. | `audit:ChartLegend/unscored-evidence-gap` |
|
|
190
|
+
|
|
191
|
+
## Decision log
|
|
192
|
+
|
|
193
|
+
None. This draft records observed behavior and evidence gaps only.
|
|
194
|
+
|
|
195
|
+
## Open questions
|
|
196
|
+
|
|
197
|
+
- **OQ1 — Composed series association.** In a composed Chart or product callsite, does evidence with two or more same-mark-shape series show that readers need an additional visual association cue? If so, which layer owns it: ChartLegend, the parent Chart/series definition, or the product callsite? (`human-design`)
|
|
198
|
+
- **OQ2 — Swatch theming reachability.** Should series swatches become a public ChartSwatch theme target, or should their paint remain caller-owned? (`human-api`)
|
|
199
|
+
|
|
200
|
+
## Content boundary
|
|
201
|
+
|
|
202
|
+
This file does not duplicate consumer prop tables/examples, current audit results,
|
|
203
|
+
implementation steps, or shared system rules. It links to their owners.
|
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
|
* ```
|