@tjakoen/grain 0.1.22 โ 0.1.24
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/PLAN.md +4 -0
- package/README.md +2 -1
- package/components/molecules/figure/figure.css +8 -0
- package/components/molecules/figure/figure.md +12 -0
- package/components/molecules/readiness/readiness.css +51 -0
- package/components/molecules/readiness/readiness.md +91 -0
- package/components/molecules/trend-chart/trend-chart.css +61 -0
- package/components/molecules/trend-chart/trend-chart.md +109 -0
- package/components/molecules/trend-chart/trend-chart.test.ts +74 -0
- package/package.json +1 -1
- package/styles/variables.css +6 -2
package/PLAN.md
CHANGED
|
@@ -56,3 +56,7 @@ Component work does not belong in the numbered list above, which tracks the AI-i
|
|
|
56
56
|
are the one pair that does **not** invert in the dark block, on purpose: a scrim darkens
|
|
57
57
|
somebody else's photograph so a label survives on top of it, and a photograph does not invert
|
|
58
58
|
with the palette.
|
|
59
|
+
3. **Trend chart.** `molecules/trend-chart`, a neutral time-series display with an optional comparison
|
|
60
|
+
range and an equivalent values table. The caller owns values, units, scale, period labels and any
|
|
61
|
+
interpretation; the component encodes no target or judgment. Static SVG and semantic tokens keep
|
|
62
|
+
it readable in narrow layouts, light and dark themes, and reduced-motion settings.
|
package/README.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# ๐พ GRAIN: usage
|
|
2
2
|
|
|
3
3
|
[](https://tjakoen.github.io/notes/ten-times-zero)
|
|
4
|
+
[](https://www.npmjs.com/package/@tjakoen/grain)
|
|
4
5
|
[](LICENSE)
|
|
5
6
|
|
|
6
7
|
GRAIN is the **AI-interaction design system**: a UI where every surface is addressable
|
|
@@ -188,7 +189,7 @@ data-attributes, no composition-root wiring and no AI layer required:
|
|
|
188
189
|
`presentation:slide`.
|
|
189
190
|
- **`scripts/drawer.js`** + the `drawer` organism: the modal side panel. `[data-drawer-open="id"]`
|
|
190
191
|
opens, `[data-drawer-close]` (the scrim carries it) closes, and the script owns the modal
|
|
191
|
-
obligations
|
|
192
|
+
obligations: focus into the panel, Tab trapped, the rest of the page `inert`, focus returned to
|
|
192
193
|
the opener. Open/closed is the plain `hidden` attribute, so a server can ship it either way.
|
|
193
194
|
|
|
194
195
|
---
|
|
@@ -10,6 +10,14 @@
|
|
|
10
10
|
line-height: var(--leading-normal);
|
|
11
11
|
}
|
|
12
12
|
|
|
13
|
+
/* diagram variant: an inline SVG rather than an <img>. MILL emits this for a rendered
|
|
14
|
+
mermaid fence. The SVG carries token references, so it re-colors with the theme; the only
|
|
15
|
+
job here is fitting it to the column and letting a wide flowchart scroll rather than
|
|
16
|
+
shrink to unreadable. No caption: a diagram fence has no caption source, and the prose
|
|
17
|
+
convention (an italic line under the figure) stays. */
|
|
18
|
+
.figure[data-variant="diagram"] { max-width: 100%; overflow-x: auto; }
|
|
19
|
+
.figure[data-variant="diagram"] svg { display: block; max-width: 100%; height: auto; }
|
|
20
|
+
|
|
13
21
|
/* clipped-photo variant: a hard editorial clip instead of a straight rectangle */
|
|
14
22
|
.figure[data-variant="clipped"] img { border: 0; clip-path: polygon(0 0, 100% 0, 100% 94%, 96% 100%, 0 100%); }
|
|
15
23
|
|
|
@@ -18,3 +18,15 @@ composed by hand, so nothing data-binds it. Images never overflow the column.
|
|
|
18
18
|
<img src="/assets/figure-sample.svg" alt="The same image, clipped">
|
|
19
19
|
</figure>
|
|
20
20
|
```
|
|
21
|
+
|
|
22
|
+
## Diagram
|
|
23
|
+
Holds an inline SVG instead of an image. MILL emits this for a rendered mermaid fence, with the
|
|
24
|
+
SVG's colors written as token references so the diagram follows both theme axes without being
|
|
25
|
+
re-rendered. A diagram wider than the column scrolls rather than shrinking to unreadable.
|
|
26
|
+
|
|
27
|
+
```html
|
|
28
|
+
<figure class="figure" data-variant="diagram">
|
|
29
|
+
<svg viewBox="0 0 120 40"><rect x="1" y="1" width="118" height="38"
|
|
30
|
+
fill="var(--color-surface)" stroke="var(--color-line)"></rect></svg>
|
|
31
|
+
</figure>
|
|
32
|
+
```
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/* molecules/readiness โ a verdict over its evidence: whether a set of boundary conditions
|
|
2
|
+
holds, the one line saying why, and what is still in the way. The generic shape behind
|
|
3
|
+
"ready to deploy", "ready to release", "ready to hand off". CSS-only (CONVENTIONS ยง4):
|
|
4
|
+
composed by hand, nothing data-binds it.
|
|
5
|
+
|
|
6
|
+
Parent context: none required. It fills its container and carries no width of its own โ
|
|
7
|
+
drop it inside a `.card` for a bordered tile, or leave it bare in a panel.
|
|
8
|
+
|
|
9
|
+
Composition: the evidence rows are a `status-list`, NOT a shape this component invents.
|
|
10
|
+
A readiness block that grows its own row markup is the thing to avoid โ the marks, the
|
|
11
|
+
in-flight lifecycle and the per-row `data-surface` hook all already live there.
|
|
12
|
+
|
|
13
|
+
This is a READOUT, not an ask. It reports state and stops. A closed-set question with
|
|
14
|
+
options and an escape belongs on CRUMB's decision ask, and having two surfaces put the
|
|
15
|
+
same question to someone is the failure DECISIONS names outright. */
|
|
16
|
+
|
|
17
|
+
.readiness { display: flex; flex-direction: column; gap: var(--space-2); }
|
|
18
|
+
|
|
19
|
+
/* The verdict sits at display scale on purpose: grade texture only reads at >= --text-2xl
|
|
20
|
+
(CLAUDE.md lesson 4), and a verdict is exactly the line an AI might compose โ so put
|
|
21
|
+
`data-grade="grain"` here and the provenance is legible instead of theoretical. */
|
|
22
|
+
.readiness__verdict {
|
|
23
|
+
font-size: var(--text-2xl);
|
|
24
|
+
line-height: var(--leading-tight);
|
|
25
|
+
color: var(--color-fg);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
.readiness__why {
|
|
29
|
+
font-size: var(--text-sm);
|
|
30
|
+
line-height: var(--leading-normal);
|
|
31
|
+
color: var(--color-muted);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/* State reads as ink level and edge weight, never hue โ the same rule stat-tile follows.
|
|
35
|
+
`blocked` earns a solid-ink edge because it is the one meant to stop you; `waiting`
|
|
36
|
+
recedes; `ready` and the default are identical, since a healthy verdict needs no
|
|
37
|
+
shouting. */
|
|
38
|
+
.readiness[data-state="blocked"] {
|
|
39
|
+
border-left: 2px solid var(--color-fg);
|
|
40
|
+
padding-left: var(--space-3);
|
|
41
|
+
}
|
|
42
|
+
.readiness[data-state="waiting"] .readiness__verdict { color: var(--color-muted); }
|
|
43
|
+
|
|
44
|
+
/* In transit โ the detector has not finished deciding. The shared idiom keyed off
|
|
45
|
+
`data-commit="pending"` and an ancestor `[data-grade="grain"]`, expressed here as a
|
|
46
|
+
dashed leading edge, never a bespoke "loading" state. */
|
|
47
|
+
.readiness[data-commit="pending"],
|
|
48
|
+
[data-grade="grain"] .readiness[data-commit="pending"] {
|
|
49
|
+
border-left: 2px dashed var(--color-fg);
|
|
50
|
+
padding-left: var(--space-3);
|
|
51
|
+
}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Readiness
|
|
2
|
+
|
|
3
|
+
A verdict over its evidence: whether a set of boundary conditions holds, one line saying why,
|
|
4
|
+
and what is still in the way. The generic shape behind "ready to deploy", "ready to release",
|
|
5
|
+
"ready to hand off" โ a run that has finished checking and now has to tell someone.
|
|
6
|
+
|
|
7
|
+
It is a **readout, not an ask.** It reports and stops. A closed-set question with options and an
|
|
8
|
+
escape hatch belongs on CRUMB's decision ask; two surfaces putting the same question to the same
|
|
9
|
+
person is a failure mode rather than thoroughness.
|
|
10
|
+
|
|
11
|
+
Composition note: no parent context is required โ it fills its container and carries no width of
|
|
12
|
+
its own, so it sits inside a `card` or bare in a panel. The evidence rows are a **`status-list`**,
|
|
13
|
+
not markup this component invents: the marks, the in-flight lifecycle and the per-row
|
|
14
|
+
`data-surface` hook already live there. Counts alongside the verdict are `stat` tiles, laid out by
|
|
15
|
+
the parent.
|
|
16
|
+
|
|
17
|
+
State is an attribute (`data-state`), and reads as ink level and edge weight, never hue.
|
|
18
|
+
|
|
19
|
+
## Ready
|
|
20
|
+
```html
|
|
21
|
+
<div class="readiness" data-state="ready">
|
|
22
|
+
<span class="readiness__verdict">Ready to hand off</span>
|
|
23
|
+
<span class="readiness__why">Gates green, plan synced, nothing in flight.</span>
|
|
24
|
+
<ul class="status-list">
|
|
25
|
+
<li class="status-list__item">
|
|
26
|
+
<span class="status-list__mark">โ</span>
|
|
27
|
+
<span class="status-list__title">gates green</span>
|
|
28
|
+
<span class="status-list__meta">check ยท test</span>
|
|
29
|
+
</li>
|
|
30
|
+
<li class="status-list__item">
|
|
31
|
+
<span class="status-list__mark">โ</span>
|
|
32
|
+
<span class="status-list__title">plan synced</span>
|
|
33
|
+
<span class="status-list__meta">PLAN.md</span>
|
|
34
|
+
</li>
|
|
35
|
+
</ul>
|
|
36
|
+
</div>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Blocked
|
|
40
|
+
The one state meant to stop you, so it takes a solid-ink edge. What blocks goes in the rows; the
|
|
41
|
+
verdict says only that something does.
|
|
42
|
+
```html
|
|
43
|
+
<div class="readiness" data-state="blocked">
|
|
44
|
+
<span class="readiness__verdict">Not yet</span>
|
|
45
|
+
<span class="readiness__why">Two conditions still hold it open.</span>
|
|
46
|
+
<ul class="status-list">
|
|
47
|
+
<li class="status-list__item">
|
|
48
|
+
<span class="status-list__mark">โ</span>
|
|
49
|
+
<span class="status-list__title">tests failing</span>
|
|
50
|
+
<span class="status-list__meta">3 of 663</span>
|
|
51
|
+
</li>
|
|
52
|
+
<li class="status-list__item" data-state="waiting">
|
|
53
|
+
<span class="status-list__mark">ยท</span>
|
|
54
|
+
<span class="status-list__title">plan not synced</span>
|
|
55
|
+
<span class="status-list__meta">PLAN.md</span>
|
|
56
|
+
</li>
|
|
57
|
+
</ul>
|
|
58
|
+
</div>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Waiting
|
|
62
|
+
Nothing has been checked yet, so the verdict recedes rather than claiming a result.
|
|
63
|
+
```html
|
|
64
|
+
<div class="readiness" data-state="waiting">
|
|
65
|
+
<span class="readiness__verdict">Not checked</span>
|
|
66
|
+
<span class="readiness__why">No gate has run this session.</span>
|
|
67
|
+
</div>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## With counts
|
|
71
|
+
Tiles are laid out by the parent, never by a wrapper inside the component.
|
|
72
|
+
```html
|
|
73
|
+
<div class="readiness" data-state="blocked">
|
|
74
|
+
<span class="readiness__verdict">Not yet</span>
|
|
75
|
+
<span class="readiness__why">Work is uncommitted.</span>
|
|
76
|
+
<div style="display:flex;gap:var(--space-3)">
|
|
77
|
+
<div class="stat" data-tone="bad"><span class="stat__value">12</span><span class="stat__label">uncommitted</span></div>
|
|
78
|
+
<div class="stat" data-tone="muted"><span class="stat__value">1</span><span class="stat__label">unpushed</span></div>
|
|
79
|
+
</div>
|
|
80
|
+
</div>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## In transit (the detector is still deciding)
|
|
84
|
+
The shared in-flight idiom, not a bespoke loading state. The verdict sits at display scale
|
|
85
|
+
precisely so that an AI-composed line reads as grain rather than claiming to be checked fact.
|
|
86
|
+
```html
|
|
87
|
+
<div class="readiness" data-commit="pending">
|
|
88
|
+
<span class="readiness__verdict" data-grade="grain">Checkingโฆ</span>
|
|
89
|
+
<span class="readiness__why">Reading the gate log.</span>
|
|
90
|
+
</div>
|
|
91
|
+
```
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/* molecules/trend-chart โ a neutral time-series display. Callers own the meaning and scale. */
|
|
2
|
+
.trend-chart {
|
|
3
|
+
display: grid;
|
|
4
|
+
gap: var(--space-3);
|
|
5
|
+
min-inline-size: 0;
|
|
6
|
+
margin: 0;
|
|
7
|
+
padding: var(--space-4);
|
|
8
|
+
border: var(--border);
|
|
9
|
+
border-radius: var(--radius-md);
|
|
10
|
+
color: var(--color-fg);
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
.trend-chart__head {
|
|
14
|
+
display: flex;
|
|
15
|
+
flex-wrap: wrap;
|
|
16
|
+
align-items: baseline;
|
|
17
|
+
justify-content: space-between;
|
|
18
|
+
gap: var(--space-2) var(--space-4);
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
.trend-chart__title { margin: 0; font-size: var(--text-base); font-weight: var(--font-weight-semibold); }
|
|
22
|
+
.trend-chart__unit,
|
|
23
|
+
.trend-chart__legend,
|
|
24
|
+
.trend-chart__caption {
|
|
25
|
+
margin: 0;
|
|
26
|
+
color: var(--color-muted);
|
|
27
|
+
font-size: var(--text-sm);
|
|
28
|
+
line-height: var(--leading-normal);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
.trend-chart__plot { min-inline-size: 0; }
|
|
32
|
+
.trend-chart__svg { display: block; inline-size: 100%; block-size: auto; overflow: visible; }
|
|
33
|
+
.trend-chart__grid { stroke: var(--color-line); stroke-width: 1; }
|
|
34
|
+
.trend-chart__axis-label { fill: var(--color-muted); font: var(--text-xs) var(--font-mono); }
|
|
35
|
+
.trend-chart__series { fill: none; stroke: var(--color-fg); stroke-width: 2.5; stroke-linecap: round; stroke-linejoin: round; }
|
|
36
|
+
.trend-chart__point { fill: var(--color-bg); stroke: var(--color-fg); stroke-width: 2; }
|
|
37
|
+
.trend-chart__range { fill: var(--color-muted); fill-opacity: .18; stroke: none; }
|
|
38
|
+
.trend-chart__range-edge { fill: none; stroke: var(--color-muted); stroke-width: 1.25; stroke-dasharray: 4 4; }
|
|
39
|
+
|
|
40
|
+
.trend-chart__table-wrap { max-inline-size: 100%; overflow-x: auto; }
|
|
41
|
+
.trend-chart__table {
|
|
42
|
+
inline-size: 100%;
|
|
43
|
+
border-collapse: collapse;
|
|
44
|
+
font-size: var(--text-sm);
|
|
45
|
+
font-variant-numeric: tabular-nums;
|
|
46
|
+
}
|
|
47
|
+
.trend-chart__table caption { padding-block-end: var(--space-2); text-align: start; }
|
|
48
|
+
.trend-chart__table th,
|
|
49
|
+
.trend-chart__table td { padding: var(--space-2); border-block-start: 1px solid var(--color-line); text-align: start; }
|
|
50
|
+
.trend-chart__table thead th { color: var(--color-muted); font-size: var(--text-xs); font-weight: var(--font-weight-semibold); }
|
|
51
|
+
.trend-chart__table tbody th { font-weight: var(--font-weight-regular); }
|
|
52
|
+
.trend-chart__table td { white-space: nowrap; }
|
|
53
|
+
|
|
54
|
+
/* A pending value uses GRAIN's shared in-transit edge, never a chart-specific state. */
|
|
55
|
+
.trend-chart[data-commit="pending"],
|
|
56
|
+
[data-grade="grain"] .trend-chart { border-style: dashed; border-color: var(--color-fg); }
|
|
57
|
+
|
|
58
|
+
/* The chart is static by design. Keep the reduced-motion contract explicit if future styling adds motion. */
|
|
59
|
+
@media (prefers-reduced-motion: reduce) {
|
|
60
|
+
.trend-chart, .trend-chart * { scroll-behavior: auto; }
|
|
61
|
+
}
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Trend chart
|
|
2
|
+
|
|
3
|
+
A neutral display for a measure observed across ordered periods or ordered categories. The caller
|
|
4
|
+
supplies the title, x-axis labels, units, series values and optional comparison range; the component
|
|
5
|
+
assigns no meaning to direction, size, or distance from the range. It does not imply a target or
|
|
6
|
+
evaluate a person.
|
|
7
|
+
|
|
8
|
+
Labels may be time windows or categories such as ordered size buckets; GRAIN treats them as opaque
|
|
9
|
+
labels and does not infer what their order means. The caller must state a unit in the heading and the
|
|
10
|
+
table caption.
|
|
11
|
+
|
|
12
|
+
CSS-only. The SVG is the visual plot, and the accompanying data table is its equivalent text
|
|
13
|
+
alternative. Keep both synchronized when values change. The caller calculates coordinates and
|
|
14
|
+
chooses a consistent scale for each chart. Use the same explicit unit for the primary series and the
|
|
15
|
+
comparison range. The range band is optional; omit its area and table column when no comparison is
|
|
16
|
+
available. A missing observation should be shown as unavailable in the table and as a break in the
|
|
17
|
+
SVG path, not as zero.
|
|
18
|
+
|
|
19
|
+
The plot uses semantic tokens and neutral line treatments so it follows light and dark themes without
|
|
20
|
+
encoding a judgment. It has no animation, so it does not require motion to understand the data.
|
|
21
|
+
|
|
22
|
+
## Ordered series with comparison range
|
|
23
|
+
|
|
24
|
+
All values and labels below are invented examples. Coordinates use a 400 by 180 viewBox; x positions
|
|
25
|
+
must align with the ordered labels in the table. These labels could identify time windows or size
|
|
26
|
+
categories. The four horizontal rules are caller-chosen scale guides, not thresholds.
|
|
27
|
+
|
|
28
|
+
```html
|
|
29
|
+
<figure class="trend-chart">
|
|
30
|
+
<figcaption class="trend-chart__head">
|
|
31
|
+
<span>
|
|
32
|
+
<span class="trend-chart__title">Sample measure</span><br>
|
|
33
|
+
<span class="trend-chart__unit">Hours</span>
|
|
34
|
+
</span>
|
|
35
|
+
<span class="trend-chart__legend">Series A ยท shaded band: comparison range</span>
|
|
36
|
+
</figcaption>
|
|
37
|
+
<div class="trend-chart__plot">
|
|
38
|
+
<svg class="trend-chart__svg" viewBox="0 0 400 180" role="img"
|
|
39
|
+
aria-label="Sample measure in hours across four ordered labels, with a comparison range">
|
|
40
|
+
<line class="trend-chart__grid" x1="48" y1="20" x2="390" y2="20"></line>
|
|
41
|
+
<line class="trend-chart__grid" x1="48" y1="58" x2="390" y2="58"></line>
|
|
42
|
+
<line class="trend-chart__grid" x1="48" y1="96" x2="390" y2="96"></line>
|
|
43
|
+
<line class="trend-chart__grid" x1="48" y1="134" x2="390" y2="134"></line>
|
|
44
|
+
<text class="trend-chart__axis-label" x="42" y="24" text-anchor="end">16</text>
|
|
45
|
+
<text class="trend-chart__axis-label" x="42" y="62" text-anchor="end">12</text>
|
|
46
|
+
<text class="trend-chart__axis-label" x="42" y="100" text-anchor="end">8</text>
|
|
47
|
+
<text class="trend-chart__axis-label" x="42" y="138" text-anchor="end">4</text>
|
|
48
|
+
<text class="trend-chart__axis-label" x="70" y="158" text-anchor="middle">A</text>
|
|
49
|
+
<text class="trend-chart__axis-label" x="176" y="158" text-anchor="middle">B</text>
|
|
50
|
+
<text class="trend-chart__axis-label" x="282" y="158" text-anchor="middle">C</text>
|
|
51
|
+
<text class="trend-chart__axis-label" x="388" y="158" text-anchor="middle">D</text>
|
|
52
|
+
<polygon class="trend-chart__range" points="70,86.5 176,77 282,96 388,67.5 388,115 282,124.5 176,115 70,124.5"></polygon>
|
|
53
|
+
<polyline class="trend-chart__range-edge" points="70,86.5 176,77 282,96 388,67.5"></polyline>
|
|
54
|
+
<polyline class="trend-chart__range-edge" points="70,124.5 176,115 282,124.5 388,115"></polyline>
|
|
55
|
+
<polyline class="trend-chart__series" points="70,105.5 176,96 282,115 388,86.5"></polyline>
|
|
56
|
+
<circle class="trend-chart__point" cx="70" cy="105.5" r="4"></circle>
|
|
57
|
+
<circle class="trend-chart__point" cx="176" cy="96" r="4"></circle>
|
|
58
|
+
<circle class="trend-chart__point" cx="282" cy="115" r="4"></circle>
|
|
59
|
+
<circle class="trend-chart__point" cx="388" cy="86.5" r="4"></circle>
|
|
60
|
+
</svg>
|
|
61
|
+
</div>
|
|
62
|
+
<div class="trend-chart__table-wrap">
|
|
63
|
+
<table class="trend-chart__table">
|
|
64
|
+
<caption class="trend-chart__caption">Values in hours</caption>
|
|
65
|
+
<thead><tr><th scope="col">Label</th><th scope="col">Series A</th><th scope="col">Comparison range</th></tr></thead>
|
|
66
|
+
<tbody>
|
|
67
|
+
<tr><th scope="row">Group A</th><td>7</td><td>5โ9</td></tr>
|
|
68
|
+
<tr><th scope="row">Group B</th><td>8</td><td>6โ10</td></tr>
|
|
69
|
+
<tr><th scope="row">Group C</th><td>6</td><td>5โ8</td></tr>
|
|
70
|
+
<tr><th scope="row">Group D</th><td>9</td><td>6โ11</td></tr>
|
|
71
|
+
</tbody>
|
|
72
|
+
</table>
|
|
73
|
+
</div>
|
|
74
|
+
</figure>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Without a comparison
|
|
78
|
+
|
|
79
|
+
Remove the range polygon, both range-edge polylines, the range phrase in the visible legend, and the
|
|
80
|
+
comparison column. Keep the label/value table: the chart is not the only way to read the series.
|
|
81
|
+
|
|
82
|
+
## Caller contract
|
|
83
|
+
|
|
84
|
+
- Use one `.trend-chart` root and the child class names shown above. No script or GRAIN binding is
|
|
85
|
+
required.
|
|
86
|
+
|
|
87
|
+
- The SVG viewBox, scale guides, series coordinates and range coordinates are caller-owned. Map all
|
|
88
|
+
series onto the same y scale, and align each x coordinate with its ordered label row.
|
|
89
|
+
|
|
90
|
+
- Supply either chronological period labels or ordered category labels. The component treats labels
|
|
91
|
+
as opaque strings; state the measure and its unit in the heading and table caption. Label any
|
|
92
|
+
comparison in the legend and table header.
|
|
93
|
+
|
|
94
|
+
- Use the same y scale and unit for the series and comparison range. The component draws no target
|
|
95
|
+
line and assigns no favorable or unfavorable meaning to any value or direction.
|
|
96
|
+
|
|
97
|
+
- Preserve each value in the table at the same precision as the plotted point. Do not fill missing
|
|
98
|
+
values with zero or visually connect across a missing period.
|
|
99
|
+
|
|
100
|
+
- The component does not color, rank, score, or explain the series. Callers may add interpretation
|
|
101
|
+
outside it, with evidence and context appropriate to their product.
|
|
102
|
+
|
|
103
|
+
## In transit
|
|
104
|
+
|
|
105
|
+
The standard GRAIN pending treatment applies to the root:
|
|
106
|
+
|
|
107
|
+
```html
|
|
108
|
+
<figure class="trend-chart" data-commit="pending">โฆ</figure>
|
|
109
|
+
```
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { test, expect } from "bun:test";
|
|
2
|
+
import { readFileSync } from "node:fs";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
|
|
5
|
+
const here = import.meta.dir;
|
|
6
|
+
const css = readFileSync(join(here, "trend-chart.css"), "utf8");
|
|
7
|
+
const md = readFileSync(join(here, "trend-chart.md"), "utf8");
|
|
8
|
+
const example = md.match(/```html\s*([\s\S]*?)```/)?.[1] ?? "";
|
|
9
|
+
|
|
10
|
+
function pointPairs(points: string): Array<[number, number]> {
|
|
11
|
+
return Array.from(points.matchAll(/([\d.]+),([\d.]+)/g), (match) => [Number(match[1]), Number(match[2])]);
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
test("the component gives a chart an equivalent tabular text alternative", () => {
|
|
15
|
+
expect(md).toMatch(/<svg[^>]+role="img"/);
|
|
16
|
+
expect(md).toMatch(/<table class="trend-chart__table">/);
|
|
17
|
+
expect(md).toMatch(/<th scope="col">Label<\/th>/);
|
|
18
|
+
expect(md).toMatch(/<th scope="row">Group A<\/th>/);
|
|
19
|
+
expect(md).toMatch(/class="trend-chart__axis-label" x="70" y="158"/);
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
test("the data contract requires a visible unit and an optional comparison range", () => {
|
|
23
|
+
expect(md).toMatch(/state a unit/i);
|
|
24
|
+
expect(md).toMatch(/optional comparison range/i);
|
|
25
|
+
expect(md).toMatch(/Without a comparison/);
|
|
26
|
+
expect(md).toMatch(/same y scale/i);
|
|
27
|
+
expect(md).toMatch(/ordered category labels/i);
|
|
28
|
+
expect(md).toMatch(/opaque strings/i);
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
test("the documented SVG points and range map exactly to the accessible table and labels", () => {
|
|
32
|
+
const rows = Array.from(example.matchAll(/<tr><th scope="row">Group ([A-D])<\/th><td>(\d+)<\/td><td>(\d+)โ(\d+)<\/td><\/tr>/g),
|
|
33
|
+
(match) => ({ label: match[1]!, value: Number(match[2]), low: Number(match[3]), high: Number(match[4]) }));
|
|
34
|
+
const labels = Array.from(example.matchAll(/<text class="trend-chart__axis-label" x="(\d+)" y="158" text-anchor="middle">([A-D])<\/text>/g),
|
|
35
|
+
(match) => ({ label: match[2]!, x: Number(match[1]) }));
|
|
36
|
+
const series = pointPairs(example.match(/<polyline class="trend-chart__series" points="([^"]+)"/)?.[1] ?? "");
|
|
37
|
+
const rangeEdges = Array.from(example.matchAll(/<polyline class="trend-chart__range-edge" points="([^"]+)"/g),
|
|
38
|
+
(match) => pointPairs(match[1]!));
|
|
39
|
+
const band = pointPairs(example.match(/<polygon class="trend-chart__range" points="([^"]+)"/)?.[1] ?? "");
|
|
40
|
+
const circles = Array.from(example.matchAll(/<circle class="trend-chart__point" cx="([\d.]+)" cy="([\d.]+)"/g),
|
|
41
|
+
(match) => [Number(match[1]), Number(match[2])] as [number, number]);
|
|
42
|
+
const y = (value: number) => 20 + (16 - value) * 9.5;
|
|
43
|
+
const xs = labels.map(({ x }) => x);
|
|
44
|
+
const upper = rows.map(({ high }, index) => [xs[index]!, y(high)] as [number, number]);
|
|
45
|
+
const lower = rows.map(({ low }, index) => [xs[index]!, y(low)] as [number, number]);
|
|
46
|
+
const expectedSeries = rows.map(({ value }, index) => [xs[index]!, y(value)] as [number, number]);
|
|
47
|
+
|
|
48
|
+
expect(rows).toHaveLength(4);
|
|
49
|
+
expect(labels.map(({ label }) => label)).toEqual(rows.map(({ label }) => label));
|
|
50
|
+
expect(series).toEqual(expectedSeries);
|
|
51
|
+
expect(circles).toEqual(expectedSeries);
|
|
52
|
+
expect(rangeEdges).toEqual([upper, lower]);
|
|
53
|
+
expect(band).toEqual([...upper, ...lower.toReversed()]);
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
test("chart ink and range use semantic tokens rather than a judgment color", () => {
|
|
57
|
+
expect(css).toMatch(/\.trend-chart__series\s*\{[^}]*stroke:\s*var\(--color-fg\)/);
|
|
58
|
+
expect(css).toMatch(/\.trend-chart__range\s*\{[^}]*fill:\s*var\(--color-muted\)/);
|
|
59
|
+
expect(css).toMatch(/\.trend-chart__grid\s*\{[^}]*stroke:\s*var\(--color-line\)/);
|
|
60
|
+
expect(md).toMatch(/assigns no meaning\s+to direction/i);
|
|
61
|
+
expect(md).toMatch(/does not imply a target or\s+evaluate a person/i);
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
test("the component is static and keeps the reduced-motion contract explicit", () => {
|
|
65
|
+
expect(css).toMatch(/@media\s*\(prefers-reduced-motion:\s*reduce\)/);
|
|
66
|
+
expect(md).toMatch(/It has no animation/i);
|
|
67
|
+
expect(css).not.toMatch(/\banimation\s*:/);
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
test("the shared GRAIN in-transit treatment applies to the component root", () => {
|
|
71
|
+
expect(css).toMatch(/\.trend-chart\[data-commit="pending"\]/);
|
|
72
|
+
expect(css).toMatch(/\[data-grade="grain"\] \.trend-chart/);
|
|
73
|
+
expect(md).toMatch(/class="trend-chart" data-commit="pending"/);
|
|
74
|
+
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tjakoen/grain",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.24",
|
|
4
4
|
"description": "GRAIN โ an AI-interaction design system where every surface is operable by both a human and an AI through one shared vocabulary.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
package/styles/variables.css
CHANGED
|
@@ -42,8 +42,12 @@
|
|
|
42
42
|
--paper-2: #E8E6DF; /* subtle hover surface */
|
|
43
43
|
--panel: #E8E6DF; /* grouped "sheet" โ a hair brighter than the page */
|
|
44
44
|
--ink: #1C1B17; /* primary text, filled dots, rules */
|
|
45
|
-
|
|
46
|
-
|
|
45
|
+
/* The two quiet tiers, and the line between them is a contract, not a shade. MUTED carries text
|
|
46
|
+
a reader is meant to read, so it clears WCAG AA (4.5:1) on --paper; it was #6E6C64 and measured
|
|
47
|
+
3.98:1, which is why it moved. FAINT is decoration: fading insights, empty and future dots. It
|
|
48
|
+
does NOT clear AA and is not meant to, so nothing a reader needs may be painted with it. */
|
|
49
|
+
--ink-muted: #65635B; /* secondary text, section labels. 4.55:1 on --paper */
|
|
50
|
+
--ink-faint: #ABA89F; /* fading insights, empty/future dots. DECORATIVE ONLY */
|
|
47
51
|
--hairline: #1C1B17; /* solid rules (under headlines) */
|
|
48
52
|
--line-soft: rgba(28, 27, 23, .14); /* translucent border for quiet grouping */
|
|
49
53
|
|