@tjakoen/grain 0.1.23 โ 0.1.25
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/ai/model-reasoner.test.ts +56 -0
- package/ai/model-reasoner.ts +19 -2
- package/ai/model.test.ts +8 -0
- package/ai/model.ts +16 -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/components/organisms/app-shell/app-shell.css +18 -2
- package/package.json +1 -1
- package/styles/global.css +1 -1
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
|
---
|
|
@@ -150,3 +150,59 @@ test("direct verb (control click, no message) โ executed without consulting th
|
|
|
150
150
|
expect(called).toBe(false); // the human already decided โ no model turn
|
|
151
151
|
expect(archived).toEqual(["ITM-1"]);
|
|
152
152
|
});
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
test("unsupported registered actions reject instead of reporting success", async () => {
|
|
156
|
+
const field = { id: "name", kind: "field" as const, accepts: ["field.set" as const] };
|
|
157
|
+
const r = makeModelReasoner({ model: model(""), manifest: () => buildManifest("loop", [field], { surfaces: ["name"], readable: [] }) });
|
|
158
|
+
const { tools, ops } = recordingTools();
|
|
159
|
+
const d = await r.decide(intent({ action: "field.set", surface: "name", payload: { value: "Ada" } }), tools);
|
|
160
|
+
expect(d.ok).toBe(false);
|
|
161
|
+
expect(ops).toEqual([]);
|
|
162
|
+
});
|
|
163
|
+
|
|
164
|
+
test("cancellation while the model completes prevents the structural mutation", async () => {
|
|
165
|
+
let cancelled = false;
|
|
166
|
+
const r = makeModelReasoner({ model: { complete: async () => { cancelled = true; return '{"action":"item.archive","target":"item:ITM-1"}'; } }, manifest });
|
|
167
|
+
const { tools, archived } = recordingTools();
|
|
168
|
+
tools.cancelled = () => cancelled;
|
|
169
|
+
const d = await r.decide(intent({ payload: { text: "archive it" } }), tools);
|
|
170
|
+
expect(d.ok).toBe(false);
|
|
171
|
+
expect(archived).toEqual([]);
|
|
172
|
+
});
|
|
173
|
+
|
|
174
|
+
test("an already cancelled direct intent emits nothing and makes no mutation", async () => {
|
|
175
|
+
const r = makeModelReasoner({ model: model(""), manifest });
|
|
176
|
+
const { tools, ops, archived } = recordingTools();
|
|
177
|
+
tools.cancelled = () => true;
|
|
178
|
+
expect((await r.decide(intent({ action: "item.archive", surface: "item:ITM-1" }), tools)).ok).toBe(false);
|
|
179
|
+
expect(ops).toEqual([]);
|
|
180
|
+
expect(archived).toEqual([]);
|
|
181
|
+
});
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
test("cancellation during reply delay prevents later tokens and navigation", async () => {
|
|
185
|
+
const nav = { id: "screen", kind: "screen", accepts: ["navigate" as const] };
|
|
186
|
+
const r = makeModelReasoner({ model: model('{"action":"navigate","target":"screen","payload":{"href":"/notes"},"reply":"Going"}'),
|
|
187
|
+
thinkMs: 1, manifest: () => buildManifest("loop", [nav], { surfaces: ["screen"], readable: [] }) });
|
|
188
|
+
let cancelled = false;
|
|
189
|
+
const { tools, ops } = recordingTools();
|
|
190
|
+
tools.cancelled = () => cancelled;
|
|
191
|
+
tools.delay = async () => { cancelled = true; };
|
|
192
|
+
expect((await r.decide(intent({ payload: { text: "go" } }), tools)).ok).toBe(false);
|
|
193
|
+
expect(ops.some(op => op.op === "navigate" || (op.op === "type" && op.commit === "pending") )).toBe(false);
|
|
194
|
+
});
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
test("the generic prompt omits unsupported handlers and rejects a proposed unsupported move visibly", async () => {
|
|
198
|
+
const field = { id: "name", kind: "field", accepts: ["field.set" as const] };
|
|
199
|
+
let prompt = "";
|
|
200
|
+
const r = makeModelReasoner({ model: { complete: async text => { prompt = text; return '{"action":"field.set","target":"name","payload":{"value":"Ada"}}'; } },
|
|
201
|
+
manifest: () => buildManifest("loop", [...targets, field], { surfaces: ["name"], readable: [] }) });
|
|
202
|
+
const { tools } = recordingTools();
|
|
203
|
+
const result = await r.decide(intent({ payload: { text: "fill my name" } }), tools);
|
|
204
|
+
expect(prompt).not.toContain("field.set");
|
|
205
|
+
expect(result.ok).toBe(false);
|
|
206
|
+
expect(result.ops).toHaveLength(1);
|
|
207
|
+
expect(result.ops[0]).toMatchObject({ op: "replace" });
|
|
208
|
+
});
|
package/ai/model-reasoner.ts
CHANGED
|
@@ -52,6 +52,7 @@ export function makeModelReasoner(opts: ModelReasonerOptions): Reasoner {
|
|
|
52
52
|
for (const ch of text) {
|
|
53
53
|
if (tools.cancelled()) break;
|
|
54
54
|
if (thinkMs > 0) await tools.delay(TYPE_MS);
|
|
55
|
+
if (tools.cancelled()) break;
|
|
55
56
|
tools.emit(typeToken(surface, ch));
|
|
56
57
|
}
|
|
57
58
|
tools.emit(settleOp(surface));
|
|
@@ -61,6 +62,11 @@ export function makeModelReasoner(opts: ModelReasonerOptions): Reasoner {
|
|
|
61
62
|
* human-facing reply into `replyTarget` (a chat bubble body, or the reflection line). `navigate` is
|
|
62
63
|
* emitted LAST โ it's terminal for the page, so the reply is seen first. */
|
|
63
64
|
async function execute(move: ValidatedMove, tools: ReasonTools, replyTarget: string | null): Promise<Decision> {
|
|
65
|
+
if (tools.cancelled()) return { ok: false, reason: "cancelled", ops: [] };
|
|
66
|
+
const unsupported = (): Decision => ({ ok: false,
|
|
67
|
+
reason: `unsupported action ${move.action} in the generic model reasoner`,
|
|
68
|
+
ops: replyTarget ? [replaceBodyOp(replyTarget, "I cannot perform that action here.", "committed")] : [],
|
|
69
|
+
});
|
|
64
70
|
const structural: RenderOp[] = [];
|
|
65
71
|
let terminal: RenderOp | null = null;
|
|
66
72
|
|
|
@@ -75,14 +81,20 @@ export function makeModelReasoner(opts: ModelReasonerOptions): Reasoner {
|
|
|
75
81
|
break;
|
|
76
82
|
}
|
|
77
83
|
// action null (reply-only) or a reply-shaped verb: the effect IS the reply, streamed below.
|
|
78
|
-
|
|
84
|
+
case null: break;
|
|
85
|
+
case "demo.run": case "say.stream": case "say.set":
|
|
86
|
+
if (replyTarget && move.reply) break;
|
|
87
|
+
return unsupported();
|
|
88
|
+
default: return unsupported();
|
|
79
89
|
}
|
|
80
90
|
|
|
91
|
+
if (tools.cancelled()) return { ok: false, reason: "cancelled", ops: [] };
|
|
81
92
|
for (const op of structural) tools.emit(op);
|
|
82
93
|
if (replyTarget) {
|
|
83
94
|
if (move.reply) await stream(replyTarget, move.reply, tools);
|
|
84
95
|
else tools.emit(settleOp(replyTarget)); // never leave an opened bubble blank
|
|
85
96
|
}
|
|
97
|
+
if (tools.cancelled()) return { ok: false, reason: "cancelled", ops: [] };
|
|
86
98
|
if (terminal) tools.emit(terminal);
|
|
87
99
|
|
|
88
100
|
return { ok: true, ops: [], reply: move.reply }; // ops all emitted inline (streaming pattern)
|
|
@@ -90,7 +102,10 @@ export function makeModelReasoner(opts: ModelReasonerOptions): Reasoner {
|
|
|
90
102
|
|
|
91
103
|
/** The agentic entry: a human message โ the model picks + we execute one move. */
|
|
92
104
|
async function decideFromMessage(intent: Intent, tools: ReasonTools, message: string): Promise<Decision> {
|
|
93
|
-
const
|
|
105
|
+
const live = manifest();
|
|
106
|
+
const supported = new Set(["note.append", "note.replace", "navigate", "item.archive", "say.set", "say.stream", "demo.run"]);
|
|
107
|
+
const m = { ...live, actions: live.actions.filter(action => supported.has(action.name)),
|
|
108
|
+
targets: live.targets.map(target => ({ id: target.id, kind: target.kind, accepts: target.accepts.filter(action => supported.has(action)) })) };
|
|
94
109
|
|
|
95
110
|
// chat.send shows the human's message, then opens an AI bubble to stream the reply into. say.set
|
|
96
111
|
// writes straight back into the reflection surface it targeted (no chat bubble).
|
|
@@ -117,6 +132,7 @@ export function makeModelReasoner(opts: ModelReasonerOptions): Reasoner {
|
|
|
117
132
|
try { raw = await model.complete(buildReasonerPrompt(manifestToText(m), message)); }
|
|
118
133
|
catch (e) { return fail("The model didn't respond โ try again.", `model.complete threw: ${String(e)}`); }
|
|
119
134
|
|
|
135
|
+
if (tools.cancelled()) return { ok: false, reason: "cancelled", ops: [] };
|
|
120
136
|
const parsed = parseModelMove(raw);
|
|
121
137
|
if (!parsed.ok) return fail("I couldn't read that decision.", parsed.reason);
|
|
122
138
|
const valid = validateMove(parsed.move, m);
|
|
@@ -127,6 +143,7 @@ export function makeModelReasoner(opts: ModelReasonerOptions): Reasoner {
|
|
|
127
143
|
|
|
128
144
|
return {
|
|
129
145
|
async decide(intent: Intent, tools: ReasonTools): Promise<Decision> {
|
|
146
|
+
if (tools.cancelled()) return { ok: false, reason: "cancelled", ops: [] };
|
|
130
147
|
const message = String(intent.payload?.text ?? "").trim();
|
|
131
148
|
|
|
132
149
|
if ((intent.action === "chat.send" || intent.action === "say.set") && message)
|
package/ai/model.test.ts
CHANGED
|
@@ -146,3 +146,11 @@ test("pipeline: fake model โ parse โ validate yields a safe move", async ()
|
|
|
146
146
|
const valid = validateMove(parsed.move, manifest);
|
|
147
147
|
expect(valid).toEqual({ ok: true, move: { action: "note.append", target: "notepad", payload: { text: "remember the milk" }, reply: undefined } });
|
|
148
148
|
});
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
test("malformed model property types are rejected before validation executes them", () => {
|
|
152
|
+
for (const value of [{ reply: 42 }, { action: [] }, { target: false }, { payload: [] }, { payload: "bad" }]) {
|
|
153
|
+
expect(parseModelMove(JSON.stringify(value)).ok).toBe(false);
|
|
154
|
+
expect(validateMove(value as never, manifest).ok).toBe(false);
|
|
155
|
+
}
|
|
156
|
+
});
|
package/ai/model.ts
CHANGED
|
@@ -99,6 +99,8 @@ export function parseModelMove(raw: string): { ok: true; move: ModelMove } | { o
|
|
|
99
99
|
catch { return { ok: false, reason: "model returned malformed JSON" }; }
|
|
100
100
|
if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
|
|
101
101
|
return { ok: false, reason: "model output is not a JSON object" };
|
|
102
|
+
const shape = modelMoveShape(parsed);
|
|
103
|
+
if (shape) return { ok: false, reason: shape };
|
|
102
104
|
return { ok: true, move: parsed as ModelMove };
|
|
103
105
|
}
|
|
104
106
|
|
|
@@ -124,6 +126,18 @@ function extractJsonObject(raw: string): string | null {
|
|
|
124
126
|
return null;
|
|
125
127
|
}
|
|
126
128
|
|
|
129
|
+
function modelMoveShape(value: unknown): string | null {
|
|
130
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) return "model move must be an object";
|
|
131
|
+
const move = value as Record<string, unknown>;
|
|
132
|
+
for (const key of ["action", "target", "reply"] as const) {
|
|
133
|
+
if (move[key] !== undefined && !(key === "action" && move[key] === null) && typeof move[key] !== "string")
|
|
134
|
+
return `model ${key} must be a string${key === "action" ? " or null" : ""}`;
|
|
135
|
+
}
|
|
136
|
+
if (move.payload !== undefined && (!move.payload || typeof move.payload !== "object" || Array.isArray(move.payload)))
|
|
137
|
+
return "model payload must be an object";
|
|
138
|
+
return null;
|
|
139
|
+
}
|
|
140
|
+
|
|
127
141
|
// โโ validating the move against the contract + the live manifest โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
128
142
|
/** Turn an UNTRUSTED ModelMove into a ValidatedMove or an informative rejection. This is the safety
|
|
129
143
|
* boundary: the model can PROPOSE anything, but only moves that are legal in the vocabulary AND
|
|
@@ -140,6 +154,8 @@ export function validateMove(
|
|
|
140
154
|
move: ModelMove,
|
|
141
155
|
manifest: Manifest,
|
|
142
156
|
): { ok: true; move: ValidatedMove } | { ok: false; reason: string } {
|
|
157
|
+
const shape = modelMoveShape(move);
|
|
158
|
+
if (shape) return { ok: false, reason: shape };
|
|
143
159
|
const action = move.action ?? null;
|
|
144
160
|
|
|
145
161
|
// reply-only: the model chose to talk, not act.
|
|
@@ -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
|
+
});
|
|
@@ -139,10 +139,14 @@ body:has(.app-shell) { container-type: inline-size; container-name: shell-frame;
|
|
|
139
139
|
@container shell-frame (max-width: 768px) {
|
|
140
140
|
.app-shell {
|
|
141
141
|
grid-template-columns: minmax(0, 1fr);
|
|
142
|
-
|
|
143
|
-
|
|
142
|
+
/* the last row only reserves room for the bottom sheet's peeking head (sidebar-panel.css),
|
|
143
|
+
so the sheet never covers the end of <main>. The console strip and status bar are
|
|
144
|
+
dropped here: on a phone they stacked 75px of chrome under the sheet for no new reading. */
|
|
145
|
+
grid-template-areas: "window" "topbar" "main" "sheet";
|
|
146
|
+
grid-template-rows: auto auto minmax(0, 1fr) 2.75rem;
|
|
144
147
|
}
|
|
145
148
|
.app-shell__aside { display: none; }
|
|
149
|
+
.app-shell > .app-shell__console, .app-shell > .app-shell__status { display: none; } /* two classes: status-bar.css sorts later */
|
|
146
150
|
.app-shell[data-rail-collapsed="true"] { --shell-rail: 15rem; } /* collapse-width is desktop-only */
|
|
147
151
|
/* two classes ON PURPOSE: a composed rail (e.g. side-rail) may carry its own `position:
|
|
148
152
|
relative` (the icon gutter), and the CSS bundle sorts side-rail AFTER app-shell โ at equal
|
|
@@ -191,3 +195,15 @@ body[data-viewport="mobile"] { --shell-viewport-w: 24.4rem; }
|
|
|
191
195
|
.app-shell__console { view-transition-name: shell-console; }
|
|
192
196
|
.app-shell__window { view-transition-name: shell-window; }
|
|
193
197
|
.app-shell__status { view-transition-name: shell-status; }
|
|
198
|
+
/* the chrome SNAPS to its new state rather than morphing. The browser's default for a named
|
|
199
|
+
element is to tween its box and cross-fade its two snapshots, so a tab strip that lost a tab,
|
|
200
|
+
or a window that gained the aside, slid visibly on every navigation. Only <main> fades. */
|
|
201
|
+
::view-transition-group(shell-rail), ::view-transition-group(shell-topbar),
|
|
202
|
+
::view-transition-group(shell-aside), ::view-transition-group(shell-console),
|
|
203
|
+
::view-transition-group(shell-window), ::view-transition-group(shell-status),
|
|
204
|
+
::view-transition-new(shell-rail), ::view-transition-new(shell-topbar),
|
|
205
|
+
::view-transition-new(shell-aside), ::view-transition-new(shell-console),
|
|
206
|
+
::view-transition-new(shell-window), ::view-transition-new(shell-status) { animation: none; }
|
|
207
|
+
::view-transition-old(shell-rail), ::view-transition-old(shell-topbar),
|
|
208
|
+
::view-transition-old(shell-aside), ::view-transition-old(shell-console),
|
|
209
|
+
::view-transition-old(shell-window), ::view-transition-old(shell-status) { display: none; }
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tjakoen/grain",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.25",
|
|
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/global.css
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
would break the spell (DESIGN-SYSTEM ยง6). */
|
|
7
7
|
@view-transition { navigation: auto; }
|
|
8
8
|
@media (prefers-reduced-motion: reduce) { @view-transition { navigation: none; } }
|
|
9
|
-
::view-transition-old(root), ::view-transition-new(root) { animation-duration: 0.
|
|
9
|
+
::view-transition-old(root), ::view-transition-new(root) { animation-duration: 0.15s; }
|
|
10
10
|
|
|
11
11
|
* { box-sizing: border-box; }
|
|
12
12
|
|