@tjakoen/grain 0.1.33 → 0.1.35

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.
@@ -0,0 +1,66 @@
1
+ # Dash panel
2
+
3
+ The surface one chart, table or ranked list sits on inside a dashboard. It has a title, an
4
+ optional action on the same line, and a state. A panel is never just a box: it is ready, loading,
5
+ empty, stale or failed, and it says which in a word a reader can act on.
6
+
7
+ Loading reuses the shared in-transit idiom, data-commit="pending", the same dashed edge a stat tile
8
+ or a button wears while the AI is writing it. Empty says what to do next rather than "No data".
9
+ Stale says when the numbers were last true. Failed says what to try.
10
+
11
+ ## States
12
+
13
+ ### Ready
14
+
15
+ ```html
16
+ <section class="dash-panel" data-surface="panel:signups">
17
+ <header class="dash-panel__head">
18
+ <h3 class="dash-panel__title">Signups</h3>
19
+ <a class="dash-panel__action" href="#signups">Open report</a>
20
+ </header>
21
+ <p class="dash-panel__note">312 this week</p>
22
+ </section>
23
+ ```
24
+
25
+ ### Loading
26
+
27
+ ```html
28
+ <section class="dash-panel" data-commit="pending" aria-busy="true" data-surface="panel:signups">
29
+ <header class="dash-panel__head"><h3 class="dash-panel__title">Signups</h3></header>
30
+ <p class="dash-panel__note">Loading this week</p>
31
+ </section>
32
+ ```
33
+
34
+ ### Empty
35
+
36
+ ```html
37
+ <section class="dash-panel" data-state="empty" data-surface="panel:refunds">
38
+ <header class="dash-panel__head"><h3 class="dash-panel__title">Refunds</h3></header>
39
+ <p class="dash-panel__note">None this period. Refunds appear here as soon as one is issued.</p>
40
+ </section>
41
+ ```
42
+
43
+ ### Stale
44
+
45
+ ```html
46
+ <section class="dash-panel" data-state="stale" data-surface="panel:traffic">
47
+ <header class="dash-panel__head"><h3 class="dash-panel__title">Traffic</h3></header>
48
+ <p class="dash-panel__note">Last updated 09:40, the feed has not answered since</p>
49
+ </section>
50
+ ```
51
+
52
+ ```controls
53
+ select data-state = - | empty | stale | error
54
+ toggle data-commit = pending
55
+ text .dash-panel__title = Signups
56
+ text .dash-panel__note = 312 this week
57
+ ```
58
+
59
+ ## Accessibility
60
+
61
+ A loading panel sets aria-busy so assistive technology waits for the content instead of reading a
62
+ half-drawn panel. The state is always written as text in the note, never carried by the border
63
+ alone; the border is a second cue for sighted readers, not the only one.
64
+
65
+ The action is a real link or button with a specific label ("Open report"), never "More" or an icon
66
+ on its own.
@@ -0,0 +1,19 @@
1
+ /* dashboards/dashboard — the page a dashboard sits on: a head that states the period and what the
2
+ numbers compare against, a KPI strip that ADDS columns as the screen widens (no narrow column
3
+ floating on a wide monitor), and a panel grid where a panel spans one, two or every column.
4
+ One column on a phone. Layout only: no colour of its own, so it follows both theme axes. */
5
+ .dash { display: grid; gap: var(--space-6); container-type: inline-size; min-inline-size: 0; }
6
+ .dash__head { display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between;
7
+ gap: var(--space-2) var(--space-4); padding-bottom: var(--space-3); border-bottom: var(--border); }
8
+ .dash__title { margin: 0; font-size: var(--text-xl); font-weight: var(--font-weight-semibold);
9
+ line-height: var(--leading-tight); color: var(--ink); }
10
+ .dash__period { margin: 0; font-size: var(--text-sm); color: var(--color-muted); }
11
+ .dash__kpis { display: grid; gap: var(--space-3);
12
+ grid-template-columns: repeat(auto-fit, minmax(min(100%, 11rem), 1fr)); }
13
+ .dash__grid { display: grid; gap: var(--space-4); grid-template-columns: repeat(var(--dash-cols, 1), minmax(0, 1fr)); }
14
+ .dash__grid > * { min-inline-size: 0; }
15
+ @container (min-width: 40rem) { .dash__grid { --dash-cols: 2; } }
16
+ @container (min-width: 72rem) { .dash__grid { --dash-cols: 3; } }
17
+ @container (min-width: 120rem) { .dash__grid { --dash-cols: 4; } }
18
+ .dash__grid > [data-span="2"] { grid-column: span min(2, var(--dash-cols, 1)); }
19
+ .dash__grid > [data-span="full"] { grid-column: 1 / -1; }
@@ -0,0 +1,70 @@
1
+ # Dashboard
2
+
3
+ The page a dashboard sits on. A head names the dashboard, the period and what every delta on the
4
+ page compares against, so a reader never has to guess the baseline. Below it, a strip of stat tiles
5
+ that adds columns as the screen grows, then a grid of panels that runs one column on a phone, two on
6
+ a tablet, three on a desktop and four on an ultrawide.
7
+
8
+ The layout queries its own width, not the viewport's, so a dashboard inside a sidebar or a catalog
9
+ panel lays itself out for the room it actually has. A panel spans two columns with data-span="2"
10
+ and the whole row with data-span="full".
11
+
12
+ Stat tiles, trend charts and data tables are the existing molecules; this layer composes them and
13
+ adds the dash panel, the delta, the bullet graph and the rank list. Every tile and panel carries a
14
+ data-surface slug so a tour, a lamp or the reasoner can point at one number rather than at the page.
15
+
16
+ ## Overview
17
+
18
+ ### A dashboard with a KPI strip and three panels
19
+
20
+ ```html
21
+ <div class="dash" data-surface="dashboard:sales">
22
+ <header class="dash__head">
23
+ <h2 class="dash__title">Sales</h2>
24
+ <p class="dash__period">1 to 14 November, compared with the two weeks before</p>
25
+ </header>
26
+ <div class="dash__kpis">
27
+ <div class="stat" data-surface="stat:revenue">
28
+ <span class="stat__value">€48.2k</span>
29
+ <span class="stat__label">Revenue</span>
30
+ <span class="delta" data-dir="up"><span class="delta__glyph" aria-hidden="true">▲</span> 12% <span class="delta__base">vs prior</span></span>
31
+ </div>
32
+ <div class="stat" data-surface="stat:orders">
33
+ <span class="stat__value">1,204</span>
34
+ <span class="stat__label">Orders</span>
35
+ <span class="delta" data-dir="down"><span class="delta__glyph" aria-hidden="true">▼</span> 3% <span class="delta__base">vs prior</span></span>
36
+ </div>
37
+ <div class="stat" data-surface="stat:refunds">
38
+ <span class="stat__value">0</span>
39
+ <span class="stat__label">Refunds</span>
40
+ <span class="delta" data-dir="flat" data-small-base><span class="delta__base">was 1</span></span>
41
+ </div>
42
+ </div>
43
+ <div class="dash__grid">
44
+ <section class="dash-panel" data-span="2" data-surface="panel:revenue-by-source">
45
+ <header class="dash-panel__head"><h3 class="dash-panel__title">Revenue by source</h3></header>
46
+ <ol class="rank-list">
47
+ <li class="rank-list__row" style="--share: 0.52"><span class="rank-list__name">Direct</span><span class="rank-list__value">€25.1k</span></li>
48
+ <li class="rank-list__row" style="--share: 0.31"><span class="rank-list__name">Search</span><span class="rank-list__value">€14.9k</span></li>
49
+ <li class="rank-list__row" style="--share: 0.17"><span class="rank-list__name">Referral</span><span class="rank-list__value">€8.2k</span></li>
50
+ </ol>
51
+ </section>
52
+ <section class="dash-panel" data-surface="panel:target">
53
+ <header class="dash-panel__head"><h3 class="dash-panel__title">Monthly target</h3></header>
54
+ <div class="bullet" role="img" aria-label="Revenue €48.2k of a €60k target" style="--value: 0.8; --target: 0.9; --poor: 0.5; --fair: 0.75">
55
+ <span class="bullet__bar"></span><span class="bullet__target"></span>
56
+ </div>
57
+ <p class="bullet__legend">€48.2k of €60k</p>
58
+ </section>
59
+ </div>
60
+ </div>
61
+ ```
62
+
63
+ ## Accessibility
64
+
65
+ The head is a real heading, and each panel title is the next level down, so a screen reader's
66
+ heading list reads as the dashboard's table of contents. The period line is plain text rather than
67
+ a tooltip, because it is the one sentence a reader must not miss.
68
+
69
+ Tiles read in source order, left to right and then down; the grid never reorders them visually, so
70
+ keyboard and reading order match what is on screen. The layout has no motion.
@@ -0,0 +1,44 @@
1
+ // grain/components/dashboards/dashboards.test.ts — holds the dashboards layer to its own rules
2
+ // (plans/dashboard-layer.md): every component ships a doc and a stylesheet, every doc has an
3
+ // Accessibility section and addresses its examples through data-surface, no stylesheet reaches for
4
+ // a raw colour or tracked capitals, and every class an example uses is one the layer defines.
5
+ import { test, expect } from "bun:test";
6
+ import { readdirSync, readFileSync, existsSync } from "node:fs";
7
+ import { join } from "node:path";
8
+
9
+ const root = import.meta.dir;
10
+ const names = readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
11
+ const md = (n: string) => readFileSync(join(root, n, `${n}.md`), "utf8");
12
+ const css = (n: string) => readFileSync(join(root, n, `${n}.css`), "utf8");
13
+
14
+ test("the layer holds the five components", () => {
15
+ expect(names.sort()).toEqual(["bullet-graph", "dash-panel", "dashboard", "delta", "rank-list"]);
16
+ for (const n of names) { expect(existsSync(join(root, n, `${n}.md`))).toBe(true); expect(existsSync(join(root, n, `${n}.css`))).toBe(true); }
17
+ });
18
+
19
+ test("every doc carries an Accessibility section and a data-surface address", () => {
20
+ for (const n of names) {
21
+ expect(md(n)).toMatch(/^## Accessibility$/m);
22
+ expect(md(n)).toContain("data-surface=");
23
+ }
24
+ });
25
+
26
+ test("no stylesheet hardcodes a colour or tracks its capitals", () => {
27
+ for (const n of names) {
28
+ const src = css(n);
29
+ expect(src).not.toMatch(/#[0-9a-fA-F]{3,8}\b|\b(rgb|hsl)a?\(/);
30
+ expect(src).not.toMatch(/text-transform:\s*uppercase|letter-spacing/);
31
+ }
32
+ });
33
+
34
+ test("every dashboard-layer class an example uses is defined in the layer", () => {
35
+ const defined = new Set(names.flatMap((n) => [...css(n).matchAll(/\.([a-z][a-z0-9_-]*)/g)].map((m) => m[1])));
36
+ const prefixes = ["dash", "dash-panel", "delta", "bullet", "rank-list"];
37
+ for (const n of names) for (const m of md(n).matchAll(/class="([^"]+)"/g))
38
+ for (const cls of m[1].split(/\s+/))
39
+ if (prefixes.some((p) => cls === p || cls.startsWith(`${p}__`))) expect(defined.has(cls)).toBe(true);
40
+ });
41
+
42
+ test("no example colours a delta by direction", () => {
43
+ expect(css("delta")).not.toMatch(/--color-(danger|success)/);
44
+ });
@@ -0,0 +1,9 @@
1
+ /* dashboards/delta — the change beside a number: a direction glyph, the change, a one-word
2
+ baseline. Monochrome: direction is the glyph and the words, never red or green, because whether
3
+ "up" is good depends on the measure and GRAIN assigns no meaning to direction. A delta on a
4
+ base too small for a percentage to be honest says "was 1" in a quiet tone instead. */
5
+ .delta { display: inline-flex; align-items: baseline; gap: var(--space-1); font-size: var(--text-xs);
6
+ font-weight: var(--font-weight-medium); color: var(--ink); font-variant-numeric: tabular-nums; }
7
+ .delta__glyph { font-size: 0.8em; }
8
+ .delta__base { font-weight: var(--font-weight-regular); color: var(--color-muted); }
9
+ .delta[data-dir="flat"], .delta[data-small-base] { color: var(--color-muted); }
@@ -0,0 +1,42 @@
1
+ # Delta
2
+
3
+ The change beside a number: a direction glyph, the size of the change, and a one-word baseline such
4
+ as "vs prior". The baseline sits on the tile and the full sentence, if one is needed, lives in the
5
+ dashboard head, so a tile never grows a paragraph under its number.
6
+
7
+ A delta never colours itself red or green. Whether up is good depends on the measure (revenue up is
8
+ good, churn up is not), and the component cannot know which, so direction is carried by the glyph
9
+ and the words. When the base is too small for a percentage to mean anything, write "was 1" with
10
+ data-small-base instead of a loud minus 100 percent.
11
+
12
+ ## Directions
13
+
14
+ ### Up
15
+
16
+ ```html
17
+ <span class="delta" data-dir="up" data-surface="delta:revenue"><span class="delta__glyph" aria-hidden="true">▲</span> 12% <span class="delta__base">vs prior</span></span>
18
+ ```
19
+
20
+ ### Down
21
+
22
+ ```html
23
+ <span class="delta" data-dir="down"><span class="delta__glyph" aria-hidden="true">▼</span> 3% <span class="delta__base">vs prior</span></span>
24
+ ```
25
+
26
+ ### Small base
27
+
28
+ ```html
29
+ <span class="delta" data-dir="flat" data-small-base><span class="delta__base">was 1</span></span>
30
+ ```
31
+
32
+ ```controls
33
+ select data-dir = up | down | flat
34
+ toggle data-small-base
35
+ ```
36
+
37
+ ## Accessibility
38
+
39
+ The glyph is hidden from assistive technology, so the delta must say its direction in words when
40
+ the number alone would be ambiguous: give the tile an accessible name such as "Orders, down 3
41
+ percent versus prior" when the visible text is only "3%". The words are what carry direction for a
42
+ colour-blind reader too, which is the reason the component has no colour to lose.
@@ -0,0 +1,10 @@
1
+ /* dashboards/rank-list — a ranked breakdown. Each row carries a slim share bar along its bottom
2
+ edge (width = --share, a fraction 0..1) instead of a tinted block behind the whole row, so the
3
+ names stay on plain paper and the bars compare by length. */
4
+ .rank-list { list-style: none; margin: 0; padding: 0; display: grid; gap: var(--space-2); }
5
+ .rank-list__row { --share: 0; position: relative; display: flex; justify-content: space-between; gap: var(--space-3);
6
+ padding-block: var(--space-1) var(--space-2); font-size: var(--text-sm); color: var(--ink); }
7
+ .rank-list__row::after { content: ""; position: absolute; inset-inline-start: 0; inset-block-end: 0;
8
+ block-size: 3px; inline-size: calc(var(--share, 0) * 100%); background: var(--ink-muted); border-radius: var(--radius-sm); }
9
+ .rank-list__name { min-inline-size: 0; overflow-wrap: anywhere; }
10
+ .rank-list__value { font-variant-numeric: tabular-nums; color: var(--ink); }
@@ -0,0 +1,27 @@
1
+ # Rank list
2
+
3
+ A ranked breakdown: sources by revenue, pages by views, courses by enrolment. Each row is a name and
4
+ a value, with a slim share bar along its bottom edge whose length is the row's share of the total.
5
+ The bar replaces a tinted block behind the whole row, which turns a list into a wall of colour and
6
+ makes the names harder to read than the numbers.
7
+
8
+ The caller sorts the rows and passes each share as --share, a fraction between 0 and 1.
9
+
10
+ ## Breakdown
11
+
12
+ ### Revenue by source
13
+
14
+ ```html
15
+ <ol class="rank-list" data-surface="rank:revenue-by-source">
16
+ <li class="rank-list__row" style="--share: 0.52"><span class="rank-list__name">Direct</span><span class="rank-list__value">€25.1k</span></li>
17
+ <li class="rank-list__row" style="--share: 0.31"><span class="rank-list__name">Search</span><span class="rank-list__value">€14.9k</span></li>
18
+ <li class="rank-list__row" style="--share: 0.17"><span class="rank-list__name">Referral</span><span class="rank-list__value">€8.2k</span></li>
19
+ </ol>
20
+ ```
21
+
22
+ ## Accessibility
23
+
24
+ The list is an ordered list, so a screen reader announces the rank and the count. The share bar is
25
+ decoration drawn by CSS and is never read; the value in each row is the text a reader hears, so
26
+ the value must carry its unit. Long names wrap instead of truncating, so nothing is hidden on a
27
+ phone.
@@ -32,3 +32,14 @@
32
32
  via the inherited --type-font. */
33
33
  .stat[data-commit="pending"],
34
34
  [data-grade="grain"] .stat { border-style: dashed; border-color: var(--ink); }
35
+
36
+ /* ---- a long text value (a plan id, a name) stays on one line and ends in an ellipsis rather
37
+ than wrapping the tile taller than its neighbours. Opt-in, because a number never needs it. */
38
+ .stat__value[data-fit="truncate"] { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
39
+
40
+ /* ---- a tile that is a link: a filter or a drill-down. It reads as the same tile; hover and focus
41
+ firm the border to full ink, and the selected tile (aria-current) adds an inset ink bar under
42
+ it. Weight and ink only, never hue. The focus ring stays the global one. */
43
+ a.stat { color: inherit; text-decoration: none; }
44
+ a.stat:hover { border-color: var(--ink); }
45
+ a.stat[aria-current]:not([aria-current="false"]) { border-color: var(--ink); box-shadow: inset 0 -3px 0 var(--ink); }
@@ -41,6 +41,26 @@ secondary/context count that recedes to faint; `ok` and the default read identic
41
41
  <div class="stat" data-tone="muted"><span class="stat__value">3</span><span class="stat__label">skipped</span></div>
42
42
  ```
43
43
 
44
+ ## A long text value
45
+ When the value is a word rather than a number (a plan id, a name), `data-fit="truncate"` keeps it
46
+ on one line and ends it in an ellipsis, so the tile stays the height of its neighbours. Put the
47
+ full text in a `title` so it can still be read.
48
+ ```html
49
+ <div class="stat">
50
+ <span class="stat__value" data-fit="truncate" title="pantry-session-control">pantry-session-control</span>
51
+ <span class="stat__label">busiest plan</span>
52
+ </div>
53
+ ```
54
+
55
+ ## As a link
56
+ A tile can be the link itself when it filters a view or opens the detail behind the number. Use a
57
+ real `<a>`, and mark the selected filter with `aria-current="page"`, which adds an ink bar under
58
+ the tile. The label should say where the link goes, as it does here.
59
+ ```html
60
+ <a class="stat" href="?view=doing" aria-current="page"><span class="stat__value">4</span><span class="stat__label">doing</span></a>
61
+ <a class="stat" href="?view=blocked"><span class="stat__value">1</span><span class="stat__label">blocked</span></a>
62
+ ```
63
+
44
64
  ## In transit (AI writing the number)
45
65
  ```html
46
66
  <div class="stat" data-commit="pending">
@@ -13,7 +13,7 @@ chrome — `tjakoen.github.io`'s `portfolio-frame`).
13
13
 
14
14
  **Parent context (implicit, self-installing).** `.app-shell` must be a direct-or-nested child of
15
15
  `<body>` — every real composition already is. `app-shell.css` sets `container-type: inline-size`
16
- on `body:has(.app-shell)` (named `shell-frame`) because the shell's own mobile/tablet layout
16
+ on `body:has(.app-shell)` (named `shell-frame`) because the shell's own layout
17
17
  breakpoints restyle `.app-shell`'s OWN grid properties, and an element can never `@container`-query
18
18
  a condition on itself — only a descendant can query an ancestor container. Using `body` (rather
19
19
  than a purpose-built wrapper) means the real narrow-viewport case works with zero JS; the
@@ -23,6 +23,14 @@ share this container for their own mobile rules. One documented gap: `app-window
23
23
  padding lives on `body` itself (`.app-window-backdrop`), so it can't follow suit — it stays a real
24
24
  `@media` and only responds to a genuinely narrow window, not the toggle preview.
25
25
 
26
+ **Breakpoints.** The shell has two, named as tokens in `styles/variables.css`. At `--bp-phone`
27
+ (640px) and under, it is the phone layout: one column, with the rail and the assistant as
28
+ drawers. Up to `--bp-narrow` (1100px) it keeps all three columns with a narrower assistant, so a
29
+ tablet gets the desk shell rather than the phone one. Above that it is the full desk. Container
30
+ and media queries cannot read a custom property, so each query writes the literal value, and
31
+ `app-shell.test.ts` fails if any `shell-frame` query in GRAIN uses a width other than these two.
32
+ Scripts such as `shell.js` read the same numbers. Every control in the shell is at least 24px.
33
+
26
34
  Two **optional full-width rows** bracket the workspace: `__window` (top — the `app-window`
27
35
  title bar) and `__status` (bottom — the `status-bar`). They're auto rows, so a shell that
28
36
  places nothing in them renders exactly as before; fill them to dress the shell as an editor
@@ -6,8 +6,7 @@
6
6
  .note { max-width: 72ch; }
7
7
  .note > p, .note > ul, .note > ol, .note > blockquote { line-height: var(--leading-relaxed); }
8
8
 
9
- .note__head .eyebrow { text-transform: uppercase; letter-spacing: 0.08em; font-size: var(--text-xs); }
10
- .note__head .masthead { font-size: var(--text-3xl); margin-bottom: var(--space-3); }
9
+ .note__head .masthead { font-size: var(--text-3xl); margin-bottom: var(--space-2); }
11
10
  .note__lede {
12
11
  color: var(--color-muted);
13
12
  font-size: var(--text-lg);
@@ -1,7 +1,7 @@
1
1
  # Note
2
2
 
3
3
  The editorial content article — the layout MILL's default GRAIN adapter emits for a
4
- rendered Markdown document (eyebrow meta → masthead → lede → tag badges → hairline rule →
4
+ rendered Markdown document (masthead → byline meta → lede → tag badges → hairline rule →
5
5
  prose). CSS-only: MILL composes the markup; nothing data-binds it. Human-authored content →
6
6
  always clean ink (`data-grade="smooth"`; only the AI grains).
7
7
 
@@ -9,8 +9,8 @@ always clean ink (`data-grade="smooth"`; only the AI grains).
9
9
  ```html
10
10
  <article class="note" data-grade="smooth">
11
11
  <header class="note__head">
12
- <p class="eyebrow">2026-07-03 · ~13 min</p>
13
12
  <h1 class="masthead">Ten Times Zero Is Still Zero</h1>
13
+ <p class="byline">2026-07-03 · ~13 min</p>
14
14
  <p class="note__lede">How I actually work with AI, and why it holds up.</p>
15
15
  <div class="note__tags"><span class="badge" data-status="active">ai</span> <span class="badge" data-status="active">workflow</span></div>
16
16
  <hr class="rule">
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tjakoen/grain",
3
- "version": "0.1.33",
3
+ "version": "0.1.35",
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",
@@ -32,12 +32,14 @@
32
32
  "components",
33
33
  "fonts",
34
34
  "scripts",
35
+ "!scripts/fixtures",
35
36
  "styles",
36
37
  "PLAN.md"
37
38
  ],
38
39
  "scripts": {
39
40
  "check": "tsc --noEmit",
40
- "test": "bun test"
41
+ "test": "bun test",
42
+ "lint:grain": "bun scripts/grain-lint.ts"
41
43
  },
42
44
  "devDependencies": {
43
45
  "bun-types": "^1.3.14",