@tjakoen/grain 0.1.29 → 0.1.31
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/components/molecules/chat-message/chat-message.md +23 -0
- package/components/organisms/date-rail/date-rail.css +67 -0
- package/components/organisms/date-rail/date-rail.md +58 -0
- package/components/tokens.test.ts +13 -0
- package/package.json +1 -1
- package/scripts/ai-dispatch.js +10 -1
- package/scripts/ai-dispatch.test.ts +8 -0
- package/styles/variables.css +5 -0
|
@@ -50,3 +50,26 @@ buttons render clean, because clicking them is the **human's** move, not AI-auth
|
|
|
50
50
|
|
|
51
51
|
Every verb here must exist in `ai/contract.ts` and walk the usual alignment row — an action button
|
|
52
52
|
in the chat is a door client like any other, so a new verb needs its reasoner branch + tests.
|
|
53
|
+
|
|
54
|
+
## Consent notice (the desk asks before it stores anything)
|
|
55
|
+
|
|
56
|
+
A consent question is not an AI offer, so it carries no `data-action`: the app owns the policy and
|
|
57
|
+
the endpoint. It is still an AI message (`data-role="ai"`, grain), because the desk asks it, and its
|
|
58
|
+
buttons stay clean because choosing is the human's move. Use the actions row with
|
|
59
|
+
`data-consent="allow|deny"`, name what is stored and for how long, and make the decline real.
|
|
60
|
+
|
|
61
|
+
```html
|
|
62
|
+
<div class="chat-message" data-role="ai" data-grade="grain" data-consent-notice>
|
|
63
|
+
<span class="chat-message__who">GRAIN</span>
|
|
64
|
+
<span class="chat-message__body">May the desk remember this conversation on this device with a cookie? It stores a session id for 30 days. Not now loses only the remembering.</span>
|
|
65
|
+
<div class="chat-message__actions">
|
|
66
|
+
<button class="btn" data-variant="soft" data-consent="allow" type="button">Remember this chat</button>
|
|
67
|
+
<button class="btn" data-variant="outline" data-consent="deny" type="button">Not now</button>
|
|
68
|
+
</div>
|
|
69
|
+
</div>
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The app sets the server-issued id on `data-desk-session` (see `scripts/ai-dispatch.js`) or as
|
|
73
|
+
`window.__DESK_SESSION__` before the dispatcher runs, handles the two buttons, sets the cookie only
|
|
74
|
+
on allow, and dismisses the notice after either choice. A static site with no consent endpoint
|
|
75
|
+
simply never renders the notice.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/* organisms/date-rail: a left-hand rail of dates for a note that tells a dated story.
|
|
2
|
+
Each .date-rail__section pairs a date with a stretch of prose. The date is position: sticky
|
|
3
|
+
inside its own section, so it holds at the top while the reader is in that section and is
|
|
4
|
+
carried off by the section's end, which is exactly when the next date arrives. No scroll JS:
|
|
5
|
+
the handover is the browser's containing-block rule, nothing more.
|
|
6
|
+
No transitions or animation, so there is nothing for prefers-reduced-motion to switch off.
|
|
7
|
+
Tokens only, no shadows: the rail is one hairline in --color-line. */
|
|
8
|
+
.date-rail {
|
|
9
|
+
--date-rail-width: 7.5rem;
|
|
10
|
+
--date-rail-top: var(--space-6);
|
|
11
|
+
position: relative;
|
|
12
|
+
}
|
|
13
|
+
/* The hairline runs the full height of the rail, behind every section, so the bar reads as one
|
|
14
|
+
continuous line rather than a stack of segments. */
|
|
15
|
+
.date-rail::before {
|
|
16
|
+
content: "";
|
|
17
|
+
position: absolute;
|
|
18
|
+
inset-block: 0;
|
|
19
|
+
inset-inline-start: calc(var(--date-rail-width) - 1px);
|
|
20
|
+
border-inline-start: 1px solid var(--color-line);
|
|
21
|
+
}
|
|
22
|
+
.date-rail__section {
|
|
23
|
+
display: grid;
|
|
24
|
+
grid-template-columns: var(--date-rail-width) minmax(0, 1fr);
|
|
25
|
+
column-gap: var(--space-6);
|
|
26
|
+
}
|
|
27
|
+
.date-rail__date {
|
|
28
|
+
position: sticky;
|
|
29
|
+
top: var(--date-rail-top);
|
|
30
|
+
align-self: start;
|
|
31
|
+
margin: 0;
|
|
32
|
+
padding-block: var(--space-2);
|
|
33
|
+
padding-inline-end: var(--space-4);
|
|
34
|
+
text-align: end;
|
|
35
|
+
font-size: var(--text-sm);
|
|
36
|
+
font-weight: var(--font-weight-semibold);
|
|
37
|
+
color: var(--color-fg);
|
|
38
|
+
font-variant-numeric: tabular-nums;
|
|
39
|
+
background: var(--color-bg);
|
|
40
|
+
}
|
|
41
|
+
.date-rail__body { min-width: 0; }
|
|
42
|
+
.date-rail__body > h2:first-child { margin-top: var(--space-2); }
|
|
43
|
+
.date-rail__body > p, .date-rail__body > ul, .date-rail__body > ol, .date-rail__body > blockquote {
|
|
44
|
+
line-height: var(--leading-relaxed);
|
|
45
|
+
}
|
|
46
|
+
.date-rail__section + .date-rail__section { padding-top: var(--space-6); }
|
|
47
|
+
/* A note on the rail needs the rail's width on top of its reading measure. */
|
|
48
|
+
.note[data-layout="timeline"] { max-width: calc(72ch + var(--date-rail-width, 7.5rem)); }
|
|
49
|
+
|
|
50
|
+
/* Phone width: the rail folds away and each date becomes a small label above its heading. */
|
|
51
|
+
@media (max-width: 768px) {
|
|
52
|
+
.date-rail::before { content: none; }
|
|
53
|
+
.date-rail__section { display: block; }
|
|
54
|
+
.date-rail__date {
|
|
55
|
+
position: static;
|
|
56
|
+
padding: 0;
|
|
57
|
+
text-align: start;
|
|
58
|
+
font-size: var(--text-xs);
|
|
59
|
+
text-transform: uppercase;
|
|
60
|
+
letter-spacing: 0.08em;
|
|
61
|
+
color: var(--color-muted);
|
|
62
|
+
background: none;
|
|
63
|
+
}
|
|
64
|
+
.date-rail__date:empty { display: none; }
|
|
65
|
+
.date-rail__body > h2:first-child { margin-top: var(--space-1); }
|
|
66
|
+
.note[data-layout="timeline"] { max-width: 72ch; }
|
|
67
|
+
}
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Date rail
|
|
2
|
+
|
|
3
|
+
A left-hand rail of dates for a note that tells a dated story. On desktop a hairline runs down the left of the article and each section's date sits beside it. The date of the section you are reading stays pinned near the top of the screen while you scroll through that section, then the section's end carries it away and the next date takes its place. On phone width (768px and under) the rail folds away and each date becomes a small label above its heading, with no horizontal scroll.
|
|
4
|
+
|
|
5
|
+
The handover is plain CSS. Each date is `position: sticky` inside its own section, so the section's bottom edge is what releases it. There is no scroll listener and no animation, which is also why there is nothing to switch off under reduced motion. It reads only palette tokens and draws no shadow, so it follows light and dark with the theme.
|
|
6
|
+
|
|
7
|
+
**Parent context:** sticky needs a scrolling ancestor with no `overflow: hidden` between it and the rail. A normal page scroll is that ancestor. Inside a bounded box (like the demo below) the box itself must scroll. Tune where the date pins with `--date-rail-top` and the rail's width with `--date-rail-width` on `.date-rail`. CSS-only (no `.html`).
|
|
8
|
+
|
|
9
|
+
## Authoring it from MILL
|
|
10
|
+
|
|
11
|
+
Opt a note in with `layout: timeline` in its frontmatter, then open each H2 with its date and a spaced middle dot, as in `## Aug 18 · Then it had to keep score`. The marker is plain Markdown, so the file still reads sensibly anywhere else, where the date simply shows as part of the heading.
|
|
12
|
+
|
|
13
|
+
```html flat
|
|
14
|
+
---
|
|
15
|
+
title: The reviewer that learned to be wrong
|
|
16
|
+
layout: timeline
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
An opening paragraph stays above the rail.
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
MILL's default layout then wraps every H2 and the prose under it in a rail section, adds `data-layout="timeline"` to the note, and slugs each heading from its text without the date, so an anchor does not move when a date is corrected. An H2 without a marker still gets a section, with an empty rail slot. A consumer with its own layout can call `dateRailBody(body)` from `@tjakoen/mill` to get the same markup.
|
|
23
|
+
|
|
24
|
+
## Example
|
|
25
|
+
|
|
26
|
+
```html
|
|
27
|
+
<div style="height:22rem;overflow:auto;border:1px solid var(--color-line);padding:var(--space-4)">
|
|
28
|
+
<article class="note" data-layout="timeline">
|
|
29
|
+
<p>An opening paragraph stays above the rail and reads at full width.</p>
|
|
30
|
+
<div class="date-rail">
|
|
31
|
+
<section class="date-rail__section">
|
|
32
|
+
<p class="date-rail__date"><time>Aug 18</time></p>
|
|
33
|
+
<div class="date-rail__body">
|
|
34
|
+
<h2 id="then-it-had-to-keep-score">Then it had to keep score</h2>
|
|
35
|
+
<p>The first version only commented. It had no way to know whether a comment had landed, so it could not tell a good finding from noise.</p>
|
|
36
|
+
<p>Keeping score meant writing down every finding and what the author did with it.</p>
|
|
37
|
+
<p>Scroll on and the date beside this section stays pinned until the section ends.</p>
|
|
38
|
+
</div>
|
|
39
|
+
</section>
|
|
40
|
+
<section class="date-rail__section">
|
|
41
|
+
<p class="date-rail__date"><time>Sep 17</time></p>
|
|
42
|
+
<div class="date-rail__body">
|
|
43
|
+
<h2 id="the-talk-was-the-old-version">The talk was the old version</h2>
|
|
44
|
+
<p>By the time it was presented, the thing on the slides had already been replaced.</p>
|
|
45
|
+
<p>The next date takes over as this section reaches the top.</p>
|
|
46
|
+
</div>
|
|
47
|
+
</section>
|
|
48
|
+
<section class="date-rail__section">
|
|
49
|
+
<p class="date-rail__date"><time>Nov 2</time></p>
|
|
50
|
+
<div class="date-rail__body">
|
|
51
|
+
<h2 id="where-it-stands">Where it stands</h2>
|
|
52
|
+
<p>A short closing section, so the last handover is visible too.</p>
|
|
53
|
+
</div>
|
|
54
|
+
</section>
|
|
55
|
+
</div>
|
|
56
|
+
</article>
|
|
57
|
+
</div>
|
|
58
|
+
```
|
|
@@ -20,6 +20,19 @@ function cssFiles(dir: string, out: string[] = []): string[] {
|
|
|
20
20
|
const HEX = /#[0-9a-fA-F]{3,8}\b/g;
|
|
21
21
|
const FUNC = /\b(rgb|rgba|hsl|hsla)\(/;
|
|
22
22
|
|
|
23
|
+
test("the dense type steps sit below the caption step, in order", () => {
|
|
24
|
+
const css = readFileSync(join(import.meta.dir, "../styles/variables.css"), "utf8");
|
|
25
|
+
const rem = (name: string) => {
|
|
26
|
+
const m = css.match(new RegExp(`--${name}:\\s*([\\d.]+)rem`));
|
|
27
|
+
return m ? Number(m[1]) : Number.NaN;
|
|
28
|
+
};
|
|
29
|
+
expect(rem("text-3xs")).toBe(0.625);
|
|
30
|
+
expect(rem("text-2xs")).toBe(0.6875);
|
|
31
|
+
expect(rem("text-xs")).toBe(0.8125);
|
|
32
|
+
expect(rem("text-3xs")).toBeLessThan(rem("text-2xs"));
|
|
33
|
+
expect(rem("text-2xs")).toBeLessThan(rem("text-xs"));
|
|
34
|
+
});
|
|
35
|
+
|
|
23
36
|
test("no component stylesheet hardcodes a color (tokens only, ever)", () => {
|
|
24
37
|
const offenders: string[] = [];
|
|
25
38
|
for (const f of cssFiles(import.meta.dir)) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tjakoen/grain",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.31",
|
|
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/scripts/ai-dispatch.js
CHANGED
|
@@ -17,8 +17,17 @@ import { createSpotlight } from "/scripts/ai-spotlight.js";
|
|
|
17
17
|
(() => {
|
|
18
18
|
"use strict";
|
|
19
19
|
|
|
20
|
-
// A stable session id for this tab; the server pushes results back on it.
|
|
20
|
+
// A stable session id for this tab; the server pushes results back on it. A server that issues
|
|
21
|
+
// and validates ids can hand one in (a data attribute or a global, set before this script runs);
|
|
22
|
+
// the per-tab UUID stays the fallback for a fully static site, so a page with no server still
|
|
23
|
+
// works. The id is validated here too, because it ends up in a query string: 128 safe characters
|
|
24
|
+
// or it is ignored and the UUID is used.
|
|
25
|
+
const provided =
|
|
26
|
+
(document.documentElement.dataset.deskSession || "") ||
|
|
27
|
+
(document.body.dataset.deskSession || "") ||
|
|
28
|
+
(typeof window.__DESK_SESSION__ === "string" ? window.__DESK_SESSION__ : "");
|
|
21
29
|
const session =
|
|
30
|
+
(provided.length > 0 && provided.length <= 128 && /^[A-Za-z0-9_-]+$/.test(provided) && provided) ||
|
|
22
31
|
(crypto && crypto.randomUUID && crypto.randomUUID()) ||
|
|
23
32
|
"s-" + Math.random().toString(36).slice(2) + performance.now();
|
|
24
33
|
|
|
@@ -20,6 +20,14 @@ test("ai-dispatch.js registers a case for every RenderOpKind contract.ts declare
|
|
|
20
20
|
for (const kind of kinds) expect(dispatch).toContain(`case "${kind}":`);
|
|
21
21
|
});
|
|
22
22
|
|
|
23
|
+
test("the client takes a server-issued session id before falling back to the per-tab UUID", async () => {
|
|
24
|
+
const dispatch = await read("./ai-dispatch.js");
|
|
25
|
+
expect(dispatch).toContain("dataset.deskSession");
|
|
26
|
+
expect(dispatch).toContain("__DESK_SESSION__");
|
|
27
|
+
expect(dispatch.indexOf("dataset.deskSession")).toBeLessThan(dispatch.indexOf("crypto.randomUUID"));
|
|
28
|
+
expect(dispatch).toContain("provided.length <= 128");
|
|
29
|
+
});
|
|
30
|
+
|
|
23
31
|
test("SAFE_NAV_HREF in ai-dispatch.js matches contract.ts's isSafeNavigateHref regex verbatim", async () => {
|
|
24
32
|
const [dispatch, contract] = await Promise.all([read("./ai-dispatch.js"), read("../ai/contract.ts")]);
|
|
25
33
|
const dispatchRe = dispatch.match(/const SAFE_NAV_HREF = (\/.*\/);/)?.[1];
|
package/styles/variables.css
CHANGED
|
@@ -82,6 +82,11 @@
|
|
|
82
82
|
--font-weight-bold: 700; /* reserved for rare extra punch */
|
|
83
83
|
|
|
84
84
|
/* type scale (mobile-first, rem @ 16px) — fluid display via clamp */
|
|
85
|
+
/* Dense instrument steps, below the caption. Only for packed panels and meters, never body copy,
|
|
86
|
+
and only where the foreground clears 4.5:1 at that size; a hint that cannot be read is not a
|
|
87
|
+
hint. The Nest panel is the surface these were added for (2026-11-08). */
|
|
88
|
+
--text-3xs: 0.625rem; /* 10px dense instrument: meter hints, micro-labels */
|
|
89
|
+
--text-2xs: 0.6875rem; /* 11px dense instrument: panel labels, captions */
|
|
85
90
|
--text-xs: 0.8125rem; /* 13px caption */
|
|
86
91
|
--text-sm: 0.875rem; /* 14px label / eyebrow */
|
|
87
92
|
--text-base: 0.9375rem; /* 15px body */
|