@tjakoen/grain 0.1.14 → 0.1.16

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,62 @@
1
+ // grain/components/doc-links.test.ts — a doc example must not invent a route.
2
+ //
3
+ // Why this exists. The catalog renders these examples as real markup, so a root-absolute href in a
4
+ // component doc becomes a real link on every consumer that mounts the catalog. Point one at a page
5
+ // that only exists in the example's imagination and you have handed every consumer a dead link,
6
+ // which their export walk will find long after the person who wrote the example has left.
7
+ //
8
+ // It happened: /clients/acme, /clients/borden and /tickets shipped in the admin-surface docs and
9
+ // broke the portfolio's Pages deploy the first time it consumed that version. The fix was to point
10
+ // fictional destinations at in-page anchors. This test is that fix, made mechanical.
11
+ //
12
+ // A doc may still link a route the REFERENCE CONSUMER really serves (the portfolio), and those are
13
+ // listed below, deliberately, one by one.
14
+ import { test, expect } from "bun:test";
15
+ import { readdirSync, readFileSync, statSync } from "node:fs";
16
+ import { join } from "node:path";
17
+
18
+ const here = new URL(".", import.meta.url).pathname;
19
+
20
+ // Two kinds of allowed reference, and the difference matters.
21
+ //
22
+ // Assets GRAIN itself ships, at the mount points a consumer wires up (/assets, /scripts). These
23
+ // resolve for anyone who mounted the package the way the README says to.
24
+ const SHIPPED_ASSETS = new Set([
25
+ "/assets/figure-sample.svg",
26
+ "/scripts/terminal.js",
27
+ ]);
28
+
29
+ // Routes the REFERENCE CONSUMER really serves. Adding one is a decision: it means every consumer
30
+ // mounting grain's catalog is expected to serve that path too, or accept a dead link on their site.
31
+ const REAL_ROUTES = new Set([
32
+ "/",
33
+ "/calendar",
34
+ "/grain",
35
+ "/notes",
36
+ "/notes/ten-times-zero",
37
+ "/notes/the-browser-grew-up",
38
+ "/notes/the-browser-grew-up.md",
39
+ ]);
40
+
41
+ function docs(dir: string, out: string[] = []): string[] {
42
+ for (const name of readdirSync(dir)) {
43
+ const full = join(dir, name);
44
+ if (statSync(full).isDirectory()) docs(full, out);
45
+ else if (name.endsWith(".md")) out.push(full);
46
+ }
47
+ return out;
48
+ }
49
+
50
+ test("no component doc links at a route that does not exist", () => {
51
+ const offenders: string[] = [];
52
+ for (const file of docs(here)) {
53
+ const md = readFileSync(file, "utf8");
54
+ for (const m of md.matchAll(/(?:href|src)="(\/[^"#][^"]*)"/g)) {
55
+ const ref = m[1];
56
+ if (ref.startsWith("//")) continue; // protocol-relative, not a route
57
+ if (SHIPPED_ASSETS.has(ref) || REAL_ROUTES.has(ref)) continue;
58
+ offenders.push(`${file.slice(here.length)}: ${ref}`);
59
+ }
60
+ }
61
+ expect(offenders).toEqual([]);
62
+ });
@@ -23,13 +23,13 @@ the rows; nothing breaks, but you don't get what the demo shows.
23
23
  <table class="data-table">
24
24
  <thead><tr><th>Name</th><th>Code</th><th>Owner</th></tr></thead>
25
25
  <tbody>
26
- <tr data-href="/clients/acme">
27
- <td><a href="/clients/acme">Acme Advisory</a><br><span class="data-table__sub">since 2021</span></td>
26
+ <tr data-href="#acme">
27
+ <td><a href="#acme">Acme Advisory</a><br><span class="data-table__sub">since 2021</span></td>
28
28
  <td>acme</td>
29
29
  <td><span class="data-table__sub">jane@acme.test</span></td>
30
30
  </tr>
31
- <tr data-href="/clients/borden">
32
- <td><a href="/clients/borden">Borden &amp; Co</a></td>
31
+ <tr data-href="#borden">
32
+ <td><a href="#borden">Borden &amp; Co</a></td>
33
33
  <td>borden</td>
34
34
  <td><span class="data-table__sub">ops@borden.test</span></td>
35
35
  </tr>
@@ -150,6 +150,11 @@
150
150
  position: absolute; left: calc(var(--u) * 11.7); right: calc(var(--u) * 11.7); top: calc(var(--u) * 3);
151
151
  display: flex; justify-content: space-between; align-items: baseline;
152
152
  gap: calc(var(--u) * 3); min-width: 0;
153
+ /* the bar is the FIRST child and a slide is inset:0, so without this the current slide paints
154
+ over the bar and eats its clicks. It still looked fine, because a slide is transparent: the
155
+ link was visible and dead. The dots and controls escape it only by sitting after the slides
156
+ in the DOM. */
157
+ z-index: 1;
153
158
  }
154
159
  .presentation__meta, .presentation__hint, .presentation__legend {
155
160
  margin: 0; font-size: calc(var(--u) * 1.4); color: var(--ink-faint);
@@ -37,6 +37,14 @@ test("fragments move opacity and transform only, never layout", () => {
37
37
  expect(frag![1]).not.toMatch(/display|height|margin|padding/);
38
38
  });
39
39
 
40
+ test("the bar stacks above the slides, or a link in it is visible and dead", () => {
41
+ // the bar is the first child and a slide is inset:0 with z-index auto, so the slide wins the
42
+ // paint order and swallows the clicks. It looks fine, because slides are transparent.
43
+ const bar = css.match(/\.presentation__bar\s*\{([^}]*)\}/);
44
+ expect(bar).not.toBeNull();
45
+ expect(bar![1]).toMatch(/z-index:\s*[1-9]/);
46
+ });
47
+
40
48
  test("speaker notes never render on the slide itself", () => {
41
49
  expect(css).toMatch(/\.presentation__slide \.slide-notes\s*\{\s*display:\s*none/);
42
50
  });
@@ -39,7 +39,7 @@ fails silently, so the promise here is only "an input that belongs in a topbar".
39
39
 
40
40
  ```html
41
41
  <header class="app-shell__topbar">
42
- <span class="topbar-crumbs"><a href="/tickets">Tickets</a> / <strong>Annual Review</strong></span>
42
+ <span class="topbar-crumbs"><a href="#tickets">Tickets</a> / <strong>Annual Review</strong></span>
43
43
  <div class="topbar-search"><input type="search" placeholder="Filter…" aria-label="Filter"></div>
44
44
  <div class="topbar-ctl">
45
45
  <button class="icon-btn" data-variant="ghost" data-toggle-scheme aria-label="Toggle light / dark">◐</button>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tjakoen/grain",
3
- "version": "0.1.14",
3
+ "version": "0.1.16",
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",