@tjakoen/grain 0.1.17 → 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.
package/catalog/catalog.test.ts
CHANGED
|
@@ -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("<div class="deck-live-marker">");
|
|
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
|
+
});
|
package/catalog/catalog.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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",
|