@tjakoen/grain 0.1.31 → 0.1.33

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.
@@ -29,7 +29,7 @@
29
29
  /* On a phone the small button's dense min-height:0 lands ~30px - below the touch
30
30
  target floor (DESIGN-SYSTEM §7). Restore a comfortable tap size at the narrow
31
31
  breakpoint without fattening the dense desktop rows. */
32
- @media (max-width: 768px) { .btn[data-size="sm"] { min-height: 2.5rem; } }
32
+ @media (max-width: 640px) { .btn[data-size="sm"] { min-height: 2.5rem; } }
33
33
 
34
34
  /* ---- variants (attribute). Monochrome: the difference is fill, not hue ---- */
35
35
  .btn[data-variant="soft"] { background: var(--paper-2); }
@@ -112,7 +112,7 @@
112
112
  /* ---- CONTAINER (2026-07-14 responsive-polish fix): the two layout breakpoints below used to be
113
113
  `@media`, which reads the actual BROWSER viewport — so the viewport-toggle's cosmetic max-width
114
114
  clamp on `.app-shell` (see the bottom of this file) never made them fire; a squeezed real window
115
- between 768-1100px also just squeezed the fixed rail/aside tracks instead of collapsing (the
115
+ between 640-1100px also just squeezed the fixed rail/aside tracks instead of collapsing (the
116
116
  `minmax(0,1fr)` main column went to zero, not the layout).
117
117
 
118
118
  Fix: `.app-shell` cannot query an `@container` condition on ITSELF (the CSS containment spec:
@@ -136,7 +136,7 @@ body:has(.app-shell) { container-type: inline-size; container-name: shell-frame;
136
136
 
137
137
  /* ---- mobile: single column; the rail becomes an off-canvas drawer. The aside (assistant)
138
138
  becomes a bottom sheet (sidebar-panel.css, which loads after this file and wins the tie). ---- */
139
- @container shell-frame (max-width: 768px) {
139
+ @container shell-frame (max-width: 640px) {
140
140
  .app-shell {
141
141
  grid-template-columns: minmax(0, 1fr);
142
142
  /* the last row only reserves room for the bottom sheet's peeking head (sidebar-panel.css),
@@ -35,13 +35,13 @@ test("app-shell.css establishes the shell-frame container on <body>, not on .app
35
35
  test("app-shell.css's own layout breakpoints are @container, not @media (the self-query trap)", () => {
36
36
  expect(appShellCss).not.toMatch(MEDIA_LAYOUT_BP);
37
37
  expect(appShellCss).toMatch(/@container shell-frame \(max-width: 1100px\)/);
38
- expect(appShellCss).toMatch(/@container shell-frame \(max-width: 768px\)/);
38
+ expect(appShellCss).toMatch(/@container shell-frame \(max-width: 640px\)/);
39
39
  });
40
40
 
41
41
  test("sidebar-panel + status-bar mobile rules follow the shell's container, not a stale @media", () => {
42
42
  for (const [name, css] of [["sidebar-panel.css", sidebarPanelCss], ["status-bar.css", statusBarCss]] as const) {
43
43
  expect(css, `${name} still has a real-viewport-only layout @media`).not.toMatch(MEDIA_LAYOUT_BP);
44
- expect(css, `${name} lost its @container shell-frame mobile rule`).toMatch(/@container shell-frame \(max-width: 768px\)/);
44
+ expect(css, `${name} lost its @container shell-frame mobile rule`).toMatch(/@container shell-frame \(max-width: 640px\)/);
45
45
  }
46
46
  });
47
47
 
@@ -58,7 +58,7 @@ test("app-window.css keeps exactly the documented self-query exception, converts
58
58
  const mediaBody = afterMedia.slice(0, afterMedia.indexOf("}") + 1);
59
59
  expect(mediaBody).toMatch(/\.app-window-backdrop\s*\{\s*padding:\s*0/);
60
60
  expect(mediaBody).not.toMatch(/\.app-shell\.app-window|\.window-bar/);
61
- expect(appWindowCss).toMatch(/@container shell-frame \(max-width: 768px\)\s*\{[^}]*\.app-shell\.app-window/);
61
+ expect(appWindowCss).toMatch(/@container shell-frame \(max-width: 640px\)\s*\{[^}]*\.app-shell\.app-window/);
62
62
  expect(appWindowCss).toMatch(/\.window-bar\s*\{\s*display:\s*none/);
63
63
  });
64
64
 
@@ -72,3 +72,22 @@ test("the viewport-toggle clamps body[data-viewport], not .app-shell[data-viewpo
72
72
  test("reduced-motion queries stay real @media (they read a user preference, not a size)", () => {
73
73
  expect(appShellCss).toMatch(/@media \(prefers-reduced-motion: reduce\)/);
74
74
  });
75
+
76
+ // One named breakpoint set (variables.css: --bp-phone, --bp-narrow). Every shell-frame container
77
+ // query and every width media query in GRAIN's components and scripts must use one of those two
78
+ // values, so a component can never disagree with the shell about which layout it is in.
79
+ test("every shell breakpoint in GRAIN is one of the named set", () => {
80
+ const vars = read("styles/variables.css");
81
+ const named = new Set([...vars.matchAll(/--bp-(?:phone|narrow):\s*(\d+px);/g)].map((m) => m[1]));
82
+ expect([...named].sort()).toEqual(["1100px", "640px"]);
83
+ const { readdirSync } = require("node:fs") as typeof import("node:fs");
84
+ const walk = (dir: string): string[] => readdirSync(join(root, dir), { withFileTypes: true }).flatMap((e) =>
85
+ e.isDirectory() ? walk(join(dir, e.name)) : /\.(css|js)$/.test(e.name) ? [join(dir, e.name)] : []);
86
+ const offenders: string[] = [];
87
+ for (const file of [...walk("components"), ...walk("scripts")]) {
88
+ const src = read(file);
89
+ for (const m of src.matchAll(/(?:@container shell-frame\s*|@media\s*|matchMedia\(["'`])\((?:max|min)-width:\s*(\d+px)\)/g))
90
+ if (!named.has(m[1])) offenders.push(`${file}: ${m[0]}`);
91
+ }
92
+ expect(offenders).toEqual([]);
93
+ });
@@ -102,10 +102,10 @@
102
102
  a demo-only feature. `.app-shell.app-window` and `.window-bar`, though, are DESCENDANTS of body,
103
103
  not body itself, so they're free to follow the container — converted, so the toggle's preview at
104
104
  least drops the frame border/shadow/title-bar even though the backdrop margin lingers. ---- */
105
- @media (max-width: 768px) {
105
+ @media (max-width: 640px) {
106
106
  .app-window-backdrop { padding: 0; }
107
107
  }
108
- @container shell-frame (max-width: 768px) {
108
+ @container shell-frame (max-width: 640px) {
109
109
  .app-shell.app-window { border: 0; border-radius: 0; box-shadow: none; }
110
110
  .window-bar { display: none; }
111
111
  }
@@ -1,67 +1,76 @@
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. */
1
+ /* organisms/date-rail: dates for a note that tells a dated story.
2
+ Two states, both CSS only, with no scroll JS and no animation (so nothing for
3
+ prefers-reduced-motion to switch off). Tokens only, no shadows.
4
+
5
+ Folded (the default): each date is a small label above its heading with a hairline under it.
6
+ It is sticky at the top of the column inside its own section, so it stays on screen while the
7
+ section does and the next section's label pushes it off.
8
+
9
+ In the margin: when the page's main column is wide enough, each date hangs in the left margin
10
+ beside its section, sticky, with a hairline between the dates and the prose. The note keeps its
11
+ normal reading measure, because the rail borrows the margin instead of a column.
12
+
13
+ Which state applies is decided by the width of the page's main column, not the viewport: a note
14
+ in a narrow pane on a wide screen has no margin to spare. A page opts in by naming that column
15
+ as a size container called "page". Without one the rail stays folded, which always fits. */
8
16
  .date-rail {
9
- --date-rail-width: 7.5rem;
17
+ --date-rail-width: 5rem;
18
+ --date-rail-gap: var(--space-5);
10
19
  --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
20
  }
21
+ .date-rail__section { position: relative; }
27
22
  .date-rail__date {
28
23
  position: sticky;
29
- top: var(--date-rail-top);
30
- align-self: start;
31
- margin: 0;
24
+ top: 0;
25
+ z-index: 1;
26
+ margin: 0 0 var(--space-2);
32
27
  padding-block: var(--space-2);
33
- padding-inline-end: var(--space-4);
34
- text-align: end;
35
- font-size: var(--text-sm);
28
+ border-bottom: 1px solid var(--color-line);
29
+ font-size: var(--text-xs);
36
30
  font-weight: var(--font-weight-semibold);
37
- color: var(--color-fg);
38
31
  font-variant-numeric: tabular-nums;
32
+ text-transform: uppercase;
33
+ letter-spacing: 0.08em;
34
+ color: var(--color-muted);
39
35
  background: var(--color-bg);
40
36
  }
37
+ .date-rail__date:empty { display: none; }
41
38
  .date-rail__body { min-width: 0; }
42
- .date-rail__body > h2:first-child { margin-top: var(--space-2); }
39
+ .date-rail__body > h2:first-child { margin-top: var(--space-1); }
43
40
  .date-rail__body > p, .date-rail__body > ul, .date-rail__body > ol, .date-rail__body > blockquote {
44
41
  line-height: var(--leading-relaxed);
45
42
  }
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)); }
43
+ .date-rail__section + .date-rail__section { padding-top: var(--space-4); }
49
44
 
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;
45
+ @container page (min-width: 54rem) {
46
+ /* The hairline sits halfway between the dates and the prose. */
47
+ .date-rail__section::before {
48
+ content: "";
49
+ position: absolute;
50
+ inset-block: 0;
51
+ inset-inline-start: calc(-0.5 * var(--date-rail-gap));
52
+ border-inline-start: 1px solid var(--color-line);
53
+ }
54
+ /* A zero-height float, pulled out into the margin, still sticks within its section. */
55
+ .date-rail__date,
56
+ .date-rail__date:empty {
57
+ display: block;
58
+ position: sticky;
59
+ top: var(--date-rail-top);
60
+ float: inline-start;
61
+ width: var(--date-rail-width);
62
+ height: 0;
63
+ margin: 0;
64
+ margin-inline-start: calc(-1 * (var(--date-rail-width) + var(--date-rail-gap)));
56
65
  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);
66
+ overflow: visible;
67
+ border-bottom: 0;
62
68
  background: none;
69
+ text-align: end;
70
+ text-transform: none;
71
+ letter-spacing: 0;
72
+ line-height: 1.3;
73
+ color: var(--color-fg);
63
74
  }
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; }
75
+ .date-rail__date time { display: block; padding-top: var(--space-3); }
67
76
  }
@@ -1,10 +1,12 @@
1
1
  # Date rail
2
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.
3
+ Dates for a note that tells a dated story. When the page has room, each section's date hangs in the left margin beside it, with a hairline between the dates and the prose, and the date of the section you are reading stays pinned near the top while you scroll through it. The note keeps its normal reading measure: the rail borrows the margin, never a column of the text.
4
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.
5
+ Without room in the margin, on a phone or in a narrow pane, each date folds into a small uppercase label above its heading with a hairline under it. The label is sticky at the top of the column while its section is on screen, and the next section's label pushes it off. An empty label is hidden.
6
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`).
7
+ Both states are plain CSS. Each date is `position: sticky` inside its own section, so the section's end 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.
8
+
9
+ **Parent context:** the margin state is decided by the width of the page's main column, not the viewport, so a page opts in by naming that column as a size container called `page`, for example `.app-shell__main { container: page / inline-size; }`. The dates hang in the margin once that column is at least 54rem wide. A page with no `page` container always gets the folded labels, which fit anywhere. Sticky also needs a scrolling ancestor with no `overflow: hidden` between it and the rail. Tune the rail with `--date-rail-width` (5rem), `--date-rail-gap` (`--space-5`) and `--date-rail-top` on `.date-rail`. CSS-only (no `.html`).
8
10
 
9
11
  ## Authoring it from MILL
10
12
 
@@ -23,8 +25,10 @@ MILL's default layout then wraps every H2 and the prose under it in a rail secti
23
25
 
24
26
  ## Example
25
27
 
28
+ The box below names itself the page container, so it shows the margin state when the catalog is wide and folds when it is not.
29
+
26
30
  ```html
27
- <div style="height:22rem;overflow:auto;border:1px solid var(--color-line);padding:var(--space-4)">
31
+ <div style="container:page / inline-size;height:22rem;overflow:auto;border:1px solid var(--color-line);padding:var(--space-4) var(--space-4) var(--space-4) 7rem">
28
32
  <article class="note" data-layout="timeline">
29
33
  <p>An opening paragraph stays above the rail and reads at full width.</p>
30
34
  <div class="date-rail">
@@ -180,9 +180,10 @@
180
180
  position: absolute; right: calc(var(--u) * 11.7); bottom: calc(var(--u) * 2.4);
181
181
  display: flex; align-items: center; gap: calc(var(--u) * 0.8);
182
182
  }
183
+ /* WCAG 2.5.8: like the dots, a control never shrinks under a 24px target when the deck scales down. */
183
184
  .presentation__ctl {
184
185
  display: inline-flex; align-items: center; justify-content: center;
185
- min-width: calc(var(--u) * 3.4); height: calc(var(--u) * 3.4); padding: 0 calc(var(--u) * 1.1);
186
+ min-width: max(24px, calc(var(--u) * 3.4)); height: max(24px, calc(var(--u) * 3.4)); padding: 0 calc(var(--u) * 1.1);
186
187
  background: transparent; border: 1px solid var(--color-line); border-radius: var(--radius-sm);
187
188
  color: var(--color-muted); font: inherit; font-size: calc(var(--u) * 1.5); line-height: 1; cursor: pointer;
188
189
  transition: border-color 0.18s ease, color 0.18s ease, background 0.18s ease;
@@ -39,7 +39,7 @@
39
39
  here is not an interrupt (ai-dispatch ignores aside/console clicks). */
40
40
  .app-shell[data-acting="true"] .app-shell__aside { position: relative; z-index: var(--z-ai-surface, 9002); }
41
41
 
42
- /* mobile (<768px): the panel becomes a bottom SHEET. The shell drops the aside column, so re-show it
42
+ /* mobile (<640px): the panel becomes a bottom SHEET. The shell drops the aside column, so re-show it
43
43
  fixed to the bottom, collapsed to its header as a grab bar; tap the header to raise the full panel.
44
44
  `@container shell-frame`, not `@media` (app-shell.css establishes the container on `<body>` and
45
45
  converts its own layout breakpoints the same way — this one has to move in lockstep, or the
@@ -47,7 +47,7 @@
47
47
  override ever kicking in to replace it, since its old `@media` never fired off the toggle's
48
48
  clamp). Every selector here targets a descendant of body (`.app-shell__aside`, `.assistant__head`),
49
49
  never body itself, so the container-query self-query rule doesn't block this file. */
50
- @container shell-frame (max-width: 768px) {
50
+ @container shell-frame (max-width: 640px) {
51
51
  .app-shell__aside {
52
52
  display: flex; position: fixed; left: 0; right: 0; bottom: 0; z-index: var(--z-ai-surface, 9002);
53
53
  height: 85dvh; opacity: 1;
@@ -70,6 +70,6 @@
70
70
 
71
71
  /* WCAG 2.4.11 (focus not obscured): the collapsed sheet peeks over the page bottom on a narrow
72
72
  frame, so the page's scrollers keep a focused element clear of that strip. */
73
- @container shell-frame (max-width: 768px) {
73
+ @container shell-frame (max-width: 640px) {
74
74
  .app-shell__main { scroll-padding-bottom: 3.75rem; }
75
75
  }
@@ -27,7 +27,7 @@
27
27
  (app-shell.css establishes the container on `<body>`) so this fires off BOTH a real narrow
28
28
  window and the shell's viewport-toggle clamp, not just the real one — `.status-bar` is a
29
29
  descendant of body, never body itself, so it's legal to query here (see app-shell.css). */
30
- @container shell-frame (max-width: 768px) {
30
+ @container shell-frame (max-width: 640px) {
31
31
  .status-bar { gap: var(--space-4); }
32
32
  .status-bar [data-status-optional] { display: none; }
33
33
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tjakoen/grain",
3
- "version": "0.1.31",
3
+ "version": "0.1.33",
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",
@@ -79,7 +79,7 @@
79
79
  const modeTab = (m) => shell.querySelector(`.assistant__modes [data-shell-mode="${m}"]`);
80
80
  const setOpen = (v) => {
81
81
  modeTab(v ? "catalog" : "chat")?.click();
82
- if (v && matchMedia("(max-width: 768px)").matches) shell.setAttribute("data-aside-open", "");
82
+ if (v && matchMedia("(max-width: 640px)").matches) shell.setAttribute("data-aside-open", "");
83
83
  };
84
84
  // [data-peek] hooks: "open" forces open, "close" forces closed, "toggle" (default) flips.
85
85
  // preventDefault so a hook can be a real <a> (the Catalog tab is href="/grain" for no-JS nav /
package/scripts/cmdk.js CHANGED
@@ -112,7 +112,7 @@
112
112
  const MARGIN = 8;
113
113
  // Narrow viewport: a full-width sheet dropping from just under the field. A
114
114
  // compact trigger button must not squeeze the palette to its own width.
115
- if (vw <= 768) {
115
+ if (vw <= 640) {
116
116
  root.style.setProperty("--cmdk-top", `${r.bottom + 4}px`);
117
117
  root.style.setProperty("--cmdk-left", `${MARGIN}px`);
118
118
  root.style.setProperty("--cmdk-width", `${vw - MARGIN * 2}px`);
package/scripts/shell.js CHANGED
@@ -7,16 +7,16 @@
7
7
  const shell = document.querySelector(".app-shell");
8
8
  if (!shell) return;
9
9
 
10
- const mobile = window.matchMedia("(max-width: 768px)");
10
+ const mobile = window.matchMedia("(max-width: 640px)");
11
11
  // "Effective mobile" is a CONTAINER question, not a viewport one. The mobile drawer/sheet LAYOUT is
12
- // driven by `@container shell-frame (max-width: 768px)` on <body> (app-shell.css), which the
12
+ // driven by `@container shell-frame (max-width: 640px)` on <body> (app-shell.css), which the
13
13
  // viewport-toggle fires by clamping body's width — WITHOUT changing the real window, so
14
14
  // `mobile.matches` (a viewport media query) stays false and every behaviour gated on it silently
15
15
  // no-ops: the grab bar can't raise the sheet, the mode tabs can't reach the catalog, the rail
16
16
  // hamburger collapses instead of opening the drawer (owner report: "chat + catalog broken when the
17
17
  // viewport is toggled"). Gate on the SAME thing the CSS does — the shell-frame container's
18
18
  // inline-size (= body's width) — so JS and layout agree in both a real narrow window and the toggle.
19
- const isMobile = () => mobile.matches || document.body.getBoundingClientRect().width <= 768;
19
+ const isMobile = () => mobile.matches || document.body.getBoundingClientRect().width <= 640;
20
20
  const KEY = "grain.shell.rail-collapsed";
21
21
 
22
22
  const setCollapsed = (v) => {
@@ -115,6 +115,14 @@
115
115
  --border: 1px solid var(--hairline); /* buttons, hard edges you tap */
116
116
 
117
117
  --content-max: 768px;
118
+
119
+ /* The shell's layout breakpoints, the one named set. Below --bp-phone the shell is the phone
120
+ layout (one column, rail and assistant as drawers); up to --bp-narrow it keeps three columns
121
+ with a tighter assistant; above that it is the full desk. Container and media queries cannot
122
+ read a custom property, so each query writes the literal value, and app-shell.test.ts holds
123
+ every shell-frame query in GRAIN to exactly these two. Scripts read the tokens directly. */
124
+ --bp-phone: 640px;
125
+ --bp-narrow: 1100px;
118
126
  --page-pad: clamp(1.25rem, 5vw, 2.5rem);
119
127
 
120
128
  /* ---- Layer 2: semantic aliases (the only tokens components touch) -------