@tjakoen/grain 0.1.16 → 0.1.18

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.
@@ -35,3 +35,33 @@ describe("createCatalog inject seams", () => {
35
35
  expect(html).not.toContain("undefined");
36
36
  });
37
37
  });
38
+
39
+ // A component that owns the window (a deck at position: fixed) rendered live inside a panel
40
+ // covers the whole catalog page — the failure that motivated the `flat` fence tag.
41
+ describe("flat panels render source only", () => {
42
+ let dir: string;
43
+
44
+ beforeAll(async () => {
45
+ dir = await mkdtemp(join(tmpdir(), "batch-catalog-flat-"));
46
+ await mkdir(join(dir, "organisms", "deck"), { recursive: true });
47
+ await writeFile(join(dir, "organisms", "deck", "deck.md"),
48
+ "# Deck\n\n## Markup\n\n```html flat\n<div class=\"deck-live-marker\"></div>\n```\n\n" +
49
+ "## Live\n\n```html\n<div class=\"other-live-marker\"></div>\n```\n");
50
+ });
51
+ afterAll(() => rm(dir, { recursive: true, force: true }));
52
+
53
+ test("a ```html flat fence keeps its markup out of the live panel", async () => {
54
+ const html = await (createCatalog(dir)).html();
55
+ // the flat panel: no live node, but the copyable source survives escaped
56
+ expect(html).not.toContain(`<div class="deck-live-marker">`);
57
+ expect(html).toContain("&lt;div class=&quot;deck-live-marker&quot;&gt;");
58
+ expect(html).toContain("panel__flat");
59
+ // an untagged fence in the same doc still renders live
60
+ expect(html).toContain(`<div class="other-live-marker">`);
61
+ });
62
+
63
+ test("each component entry carries a data-surface address", async () => {
64
+ const html = await (createCatalog(dir)).html();
65
+ expect(html).toContain(`data-surface="catalog:deck"`);
66
+ });
67
+ });
@@ -10,7 +10,7 @@
10
10
  import { readdirSync, readFileSync } from "fs";
11
11
  import { join } from "path";
12
12
 
13
- interface Panel { label: string; code: string; }
13
+ interface Panel { label: string; code: string; flat?: boolean; }
14
14
  interface Group { label: string; panels: Panel[]; }
15
15
  interface Doc { name: string; slug: string; intro: string; groups: Group[]; }
16
16
  interface Component { layer: string; slug: string; name: string; human: Doc; ai: Doc | null; }
@@ -34,6 +34,10 @@ const LAYER_ORDER = ["atoms", "molecules", "organisms"];
34
34
  const rank = (layer: string) => { const i = LAYER_ORDER.indexOf(layer); return i < 0 ? 99 : i; };
35
35
 
36
36
  // minimal markdown: # title, ## group, ### panel, ```html fences, plain prose.
37
+ // A fence tagged ```html flat renders as SOURCE ONLY, with no live panel. That escape hatch
38
+ // exists for markup a catalog panel cannot honestly host: a component that sizes itself from
39
+ // the viewport, or one that goes position: fixed, takes over the whole catalog page rather than
40
+ // demonstrating itself inside its box. Default stays live — flat is the exception a doc asks for.
37
41
  function parseDoc(md: string): Doc {
38
42
  const lines = md.split("\n");
39
43
  const doc: Doc = { name: "Untitled", slug: "untitled", intro: "", groups: [] };
@@ -48,12 +52,13 @@ function parseDoc(md: string): Doc {
48
52
  if (line.startsWith("## ")) { group = { label: line.slice(3).trim(), panels: [] }; doc.groups.push(group); pendingLabel = ""; i++; continue; }
49
53
  if (line.startsWith("### ")) { pendingLabel = line.slice(4).trim(); i++; continue; }
50
54
  if (line.startsWith("```html")) {
55
+ const flat = /\bflat\b/.test(line.slice(7));
51
56
  const body: string[] = [];
52
57
  i++;
53
58
  while (i < lines.length && !lines[i].startsWith("```")) { body.push(lines[i]); i++; }
54
59
  i++; // skip closing fence
55
60
  if (!group) { group = { label: "", panels: [] }; doc.groups.push(group); }
56
- group.panels.push({ label: pendingLabel, code: body.join("\n").trim() });
61
+ group.panels.push({ label: pendingLabel, code: body.join("\n").trim(), flat });
57
62
  continue;
58
63
  }
59
64
  if (!group && line.trim()) intro.push(line.trim());
@@ -130,9 +135,9 @@ export function createCatalog(componentsDir: string | string[], pages?: () => st
130
135
 
131
136
  function renderPanel(p: Panel): string {
132
137
  // live = author-controlled design-system markup (not user data) → inject raw
133
- return `<figure class="panel">
138
+ return `<figure class="panel"${p.flat ? " data-flat" : ""}>
134
139
  ${p.label ? `<figcaption class="panel__label">${esc(p.label)}</figcaption>` : ""}
135
- <div class="panel__live">${liveSafe(p.code)}</div>
140
+ ${p.flat ? `<p class="panel__flat">Source only — this one owns the whole window, so a panel cannot host it. Open a real one.</p>` : `<div class="panel__live">${liveSafe(p.code)}</div>`}
136
141
  <div class="panel__src">
137
142
  <button class="panel__copy" type="button">Copy</button>
138
143
  <pre><code>${esc(p.code)}</code></pre>
@@ -151,7 +156,9 @@ export function createCatalog(componentsDir: string | string[], pages?: () => st
151
156
 
152
157
  function renderDoc(c: Component): string {
153
158
  const ai = c.ai ?? c.human; // no .ai.md → AI view re-uses the human panels, grain-flipped
154
- return `<section class="cat-doc" id="${c.slug}" data-grade="smooth" data-layer="${c.layer}">
159
+ // data-surface addresses the entry so a tour, a lamp or the reasoner can point AT one
160
+ // component rather than at "the catalog". The id stays for plain anchor links.
161
+ return `<section class="cat-doc" id="${c.slug}" data-surface="catalog:${esc(c.slug)}" data-grade="smooth" data-layer="${c.layer}">
155
162
  <header class="cat-doc__head">
156
163
  <div class="cat-doc__title">
157
164
  <p class="cat-doc__eyebrow">${esc(cap(c.layer))}</p>
@@ -278,6 +285,8 @@ function page(pageNav: string, navGroups: string, main: string, inject: CatalogI
278
285
  text-transform: uppercase; letter-spacing: 0.04em; color: var(--color-muted);
279
286
  padding: var(--space-2) var(--space-3); border-bottom: 1px solid var(--color-line); }
280
287
  .panel__live { padding: var(--space-6); display: flex; align-items: center; justify-content: center; background: var(--color-bg); }
288
+ .panel__flat { margin: 0; padding: var(--space-4) var(--space-6); background: var(--color-bg);
289
+ font-size: var(--text-xs); color: var(--color-muted); text-align: center; }
281
290
  .panel__src { position: relative; border-top: 1px solid var(--color-line); }
282
291
  .panel__src pre { margin: 0; padding: var(--space-3); overflow-x: auto;
283
292
  font-size: var(--text-xs); line-height: var(--leading-normal); background: var(--ink); color: var(--paper); }
@@ -12,7 +12,7 @@ per-page wiring.
12
12
 
13
13
  ## Markup
14
14
 
15
- ```html
15
+ ```html flat
16
16
  <div class="presentation" data-present data-deck data-hash data-minutes="20" data-channel="my-talk">
17
17
 
18
18
  <div class="presentation__bar">
@@ -52,7 +52,9 @@ presenter window.
52
52
 
53
53
  The catalog renders this example flat rather than live, and that is the honest thing to do: a deck
54
54
  sizes itself from its own box with `container-type: size` and lays its slides out absolutely, so
55
- one dropped into a catalog panel collapses to nothing. Read the code, or open a real deck.
55
+ one dropped into a catalog panel collapses to nothing, and `data-present` puts it `position: fixed`
56
+ over the whole catalog page. That is what the `flat` tag on the fence above asks for. Read the
57
+ code, or open a real deck.
56
58
 
57
59
  **Opt in with `data-deck`.** Without the script the markup still renders whichever slide carries
58
60
  `data-current`, which is what a static export and a print run get.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tjakoen/grain",
3
- "version": "0.1.16",
3
+ "version": "0.1.18",
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",
@@ -203,6 +203,13 @@
203
203
  case "p": window.open(`${location.pathname}?presenter=1`, "grain-presenter", "width=1100,height=760"); break;
204
204
  case "f": togglePresent(); break;
205
205
  case "d": {
206
+ // Hand this to grain's theme control when the page has one, so the key and the button
207
+ // agree and the choice persists like every other scheme switch on the site. Flipping the
208
+ // attribute here as well would look identical on screen and quietly forget the choice.
209
+ const ctl = document.querySelector("[data-toggle-scheme]");
210
+ if (ctl) { ctl.click(); break; }
211
+ // standalone deck, no theme island on the page: flip it ourselves and accept that it
212
+ // lasts as long as the tab does.
206
213
  const root = document.documentElement;
207
214
  const dark = root.dataset.colorScheme
208
215
  ? root.dataset.colorScheme === "dark"
@@ -57,6 +57,16 @@ test("the presenter window is the same page, synced, and never shown to the room
57
57
  expect(js).toMatch(/postMessage\(\{ type: "key"/);
58
58
  });
59
59
 
60
+ test("the D key defers to grain's theme control, so it persists like the button", () => {
61
+ // flipping data-color-scheme here as well looks identical and forgets the choice the moment
62
+ // you leave the deck, which is how the key and the button came to disagree
63
+ const block = js.slice(js.indexOf('case "d"'), js.indexOf('case "."'));
64
+ expect(block).toMatch(/querySelector\("\[data-toggle-scheme\]"\)/);
65
+ expect(block).toMatch(/ctl\.click\(\)/);
66
+ // the standalone fallback stays, for a deck on a page with no theme island
67
+ expect(block).toMatch(/root\.dataset\.colorScheme = dark \? "light" : "dark"/);
68
+ });
69
+
60
70
  test("typing in a field never moves the deck", () => {
61
71
  expect(js).toMatch(/INPUT\|TEXTAREA\|SELECT/);
62
72
  expect(js).toMatch(/isContentEditable/);