@tjakoen/grain 0.1.20 → 0.1.22
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/ai/contract.test.ts +88 -1
- package/ai/contract.ts +96 -3
- package/ai/interaction-layer.test.ts +58 -0
- package/ai/manifest-dom.test.ts +59 -5
- package/ai/manifest-dom.ts +42 -11
- package/ai/reasoner-kit.test.ts +11 -1
- package/ai/reasoner-kit.ts +40 -2
- package/ai/reasoner.test.ts +55 -0
- package/ai/reasoner.ts +75 -2
- package/ai/vocab-reference.ts +3 -0
- package/assets/doc-sample.pdf +34 -0
- package/catalog/catalog.ts +56 -14
- package/components/atoms/b-check/b-check.html +27 -0
- package/components/atoms/b-check/b-check.md +67 -0
- package/components/atoms/b-checkbox/b-checkbox.css +61 -0
- package/components/atoms/b-checkbox/b-checkbox.html +17 -0
- package/components/atoms/b-checkbox/b-checkbox.md +83 -0
- package/components/atoms/b-choice/b-choice.html +16 -0
- package/components/atoms/b-choice/b-choice.md +35 -0
- package/components/atoms/b-field/b-field.html +17 -0
- package/components/atoms/b-field/b-field.md +43 -0
- package/components/atoms/b-input/b-input.css +20 -0
- package/components/atoms/b-input/b-input.html +7 -2
- package/components/atoms/b-input/b-input.md +27 -1
- package/components/atoms/b-memo/b-memo.html +21 -0
- package/components/atoms/b-memo/b-memo.md +34 -0
- package/components/atoms/b-option/b-option.html +5 -0
- package/components/atoms/b-option/b-option.md +13 -0
- package/components/atoms/b-radio/b-radio.html +17 -0
- package/components/atoms/b-radio/b-radio.md +57 -0
- package/components/atoms/b-textarea/b-textarea.css +48 -0
- package/components/atoms/b-textarea/b-textarea.html +15 -0
- package/components/atoms/b-textarea/b-textarea.md +70 -0
- package/components/doc-links.test.ts +1 -0
- package/components/form-from-data.test.ts +314 -0
- package/components/molecules/attachment/attachment.css +71 -0
- package/components/molecules/attachment/attachment.md +40 -0
- package/components/molecules/doc-frame/doc-frame.css +52 -0
- package/components/molecules/doc-frame/doc-frame.md +51 -0
- package/components/molecules/form-grid/form-grid.css +42 -0
- package/components/molecules/form-grid/form-grid.md +64 -0
- package/package.json +1 -1
- package/scripts/ai-dispatch.js +74 -4
- package/scripts/ai-dispatch.test.ts +68 -0
- package/styles/vars-defined.test.ts +1 -0
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
// grain/components/form-from-data.test.ts — conformance for the data-first form atoms.
|
|
2
|
+
//
|
|
3
|
+
// b-field / b-choice / b-option / b-memo are the DATA-driven siblings of b-input / b-select /
|
|
4
|
+
// b-textarea: same control, same CSS frame, bindings instead of config props. Two mistakes would
|
|
5
|
+
// quietly break that deal, and both are the kind grain's CLAUDE.md says to design out rather than
|
|
6
|
+
// patch on the instance:
|
|
7
|
+
//
|
|
8
|
+
// 1. Shipping a stylesheet here. The whole reason these atoms exist without one is that the frame
|
|
9
|
+
// is b-input.css and the controls are b-select.css and b-textarea.css, so the sizes, the inline
|
|
10
|
+
// variant and the AI treatment cannot drift from the component they mirror. A second stylesheet describing the same control is how two components
|
|
11
|
+
// become two designs.
|
|
12
|
+
// 2. Mixing config props and data bindings for the SAME key. `prop-*` resolves in PASS 0 from a
|
|
13
|
+
// LITERAL attribute on the tag, so it is identical for every item of an `each` — exactly what a
|
|
14
|
+
// per-field label must not be. Put both on one element and the config wins on some keys and the
|
|
15
|
+
// binding blanks others. That collision is why this is a sibling atom and not a retrofit of
|
|
16
|
+
// b-input, and it is worth a test because the two markers look interchangeable in a template.
|
|
17
|
+
//
|
|
18
|
+
// The rendering itself is not tested here: grain imports nothing from the substrate, so it has no
|
|
19
|
+
// renderer to call. That proof lives with the consumer that owns createRenderer.
|
|
20
|
+
import { test, expect } from "bun:test";
|
|
21
|
+
import { readdirSync, readFileSync } from "node:fs";
|
|
22
|
+
import { join } from "node:path";
|
|
23
|
+
|
|
24
|
+
const ATOMS = join(import.meta.dir, "atoms");
|
|
25
|
+
const DATA_FIRST = ["b-field", "b-choice", "b-option", "b-memo", "b-check"];
|
|
26
|
+
const read = (name: string) => readFileSync(join(ATOMS, name, `${name}.html`), "utf8");
|
|
27
|
+
/** The templates that wrap a control in the .field frame and therefore own the message slots. */
|
|
28
|
+
const FRAMED = ["b-input", "b-textarea", "b-checkbox", "b-radio", "b-field", "b-choice", "b-memo", "b-check"];
|
|
29
|
+
|
|
30
|
+
// The per-item content keys. Each must arrive as a binding, never as a config prop.
|
|
31
|
+
const CONTENT_KEYS = ["label", "name", "type", "placeholder", "value", "required", "selected"];
|
|
32
|
+
|
|
33
|
+
/** The whole opening tag carrying `class="<cls>"`, attributes included, however many lines it is
|
|
34
|
+
* wrapped across. The assertions below are about WHICH ELEMENT an attribute sits on, and a
|
|
35
|
+
* line-by-line search answers that question only while the template happens to fit on one line. */
|
|
36
|
+
const openTag = (html: string, cls: string): string =>
|
|
37
|
+
html.match(new RegExp(`<[a-zA-Z][a-zA-Z0-9]*[^>]*class="${cls}"[^>]*>`))?.[0] ?? "";
|
|
38
|
+
|
|
39
|
+
test("the data-first form atoms ship no CSS (the frame is b-input.css)", () => {
|
|
40
|
+
const withCss = DATA_FIRST.filter((n) => readdirSync(join(ATOMS, n)).some((f) => f.endsWith(".css")));
|
|
41
|
+
expect(withCss).toEqual([]);
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
test("every class they use is already declared by the components they mirror", () => {
|
|
45
|
+
const frame = readFileSync(join(ATOMS, "b-input", "b-input.css"), "utf8")
|
|
46
|
+
+ readFileSync(join(ATOMS, "b-select", "b-select.css"), "utf8")
|
|
47
|
+
+ readFileSync(join(ATOMS, "b-textarea", "b-textarea.css"), "utf8")
|
|
48
|
+
+ readFileSync(join(ATOMS, "b-checkbox", "b-checkbox.css"), "utf8");
|
|
49
|
+
const unknown: string[] = [];
|
|
50
|
+
for (const name of DATA_FIRST) {
|
|
51
|
+
for (const m of read(name).matchAll(/\bclass="([^"]+)"/g)) {
|
|
52
|
+
for (const cls of m[1].split(/\s+/).filter(Boolean)) {
|
|
53
|
+
if (!frame.includes(`.${cls}`)) unknown.push(`${name}: .${cls}`);
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
expect(unknown).toEqual([]);
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
test("content comes from data, never from a config prop", () => {
|
|
61
|
+
const offenders: string[] = [];
|
|
62
|
+
for (const name of DATA_FIRST) {
|
|
63
|
+
const html = read(name);
|
|
64
|
+
for (const key of CONTENT_KEYS) {
|
|
65
|
+
if (new RegExp(`prop-(attr-[\\w-]+|text)="${key}"`).test(html)) offenders.push(`${name}: ${key}`);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
expect(offenders).toEqual([]);
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
test("b-field binds every key the field spec carries", () => {
|
|
72
|
+
const html = read("b-field");
|
|
73
|
+
for (const attr of ["name", "type", "value", "placeholder", "required"]) {
|
|
74
|
+
expect(html).toContain(`data-bind-${attr}="${attr}"`);
|
|
75
|
+
}
|
|
76
|
+
expect(html).toContain(`data-field="label"`);
|
|
77
|
+
// The surface binding is the reason a generated form is AI-operable at all: it lands as
|
|
78
|
+
// data-surface="field:…" per item, which is what field.set resolves against.
|
|
79
|
+
expect(html).toContain(`data-bind-data-surface="surface"`);
|
|
80
|
+
// WHERE it lands is the whole of it, and asserting only that the binding exists is what let this
|
|
81
|
+
// ship wrong. field.set resolves the address and then writes el.value, so the address has to be on
|
|
82
|
+
// the input. On the label it points at something with nothing to write into and the write is
|
|
83
|
+
// dropped in silence. Assert the binding sits on the input itself, and the label carries none.
|
|
84
|
+
expect(openTag(html, "field__input")).toContain(`data-bind-data-surface="surface"`);
|
|
85
|
+
expect(openTag(html, "field")).not.toContain(`data-bind-data-surface`);
|
|
86
|
+
// Presentation IS form-wide, so these two stay config props on purpose.
|
|
87
|
+
expect(html).toContain(`prop-attr-data-size="size"`);
|
|
88
|
+
expect(html).toContain(`prop-attr-data-variant="variant"`);
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
test("b-choice nests b-option over the item's own options array", () => {
|
|
92
|
+
expect(read("b-choice")).toContain(`<b-option each="options">`);
|
|
93
|
+
expect(read("b-option")).toContain(`data-bind-value="value"`);
|
|
94
|
+
});
|
|
95
|
+
|
|
96
|
+
test("b-choice addresses the select, matching b-field's control-not-label rule", () => {
|
|
97
|
+
const html = read("b-choice");
|
|
98
|
+
expect(openTag(html, "field__select")).toContain(`data-bind-data-surface="surface"`);
|
|
99
|
+
expect(openTag(html, "field")).not.toContain(`data-bind-data-surface`);
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
test("b-memo addresses the textarea, matching the same control-not-label rule", () => {
|
|
103
|
+
const html = read("b-memo");
|
|
104
|
+
expect(openTag(html, "field__textarea")).toContain(`data-bind-data-surface="surface"`);
|
|
105
|
+
expect(openTag(html, "field")).not.toContain(`data-bind-data-surface`);
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
// The one way b-memo cannot copy b-field, and it is invisible in a diff: a textarea has no `value`
|
|
109
|
+
// ATTRIBUTE. Its value is its content. `data-bind-value="value"` would render value="…" onto a
|
|
110
|
+
// textarea, the browser would ignore it, and the box would come up empty with nothing warning —
|
|
111
|
+
// exactly the shape of failure the label addressing had. So the value arrives through data-field
|
|
112
|
+
// (setInnerContent) and the attribute binding must never appear here.
|
|
113
|
+
test("b-memo binds its value as CONTENT, never as a value attribute", () => {
|
|
114
|
+
const html = read("b-memo");
|
|
115
|
+
// The markup only: this atom's own comment names the marker it must not use, and a scan that
|
|
116
|
+
// cannot tell a rule from its explanation would fail on a template that is entirely correct.
|
|
117
|
+
expect(html.replace(/<!--[\s\S]*?-->/g, "")).not.toContain(`data-bind-value`);
|
|
118
|
+
expect(openTag(html, "field__textarea")).toContain(`data-field="value"`);
|
|
119
|
+
for (const attr of ["name", "placeholder", "required"]) {
|
|
120
|
+
expect(html).toContain(`data-bind-${attr}="${attr}"`);
|
|
121
|
+
}
|
|
122
|
+
expect(html).toContain(`data-field="label"`);
|
|
123
|
+
});
|
|
124
|
+
|
|
125
|
+
// Height is presentation, so it is form-wide config like size and variant, not a per-item data key.
|
|
126
|
+
// Binding it per item would be the first crack in the split the whole family rests on.
|
|
127
|
+
test("b-memo takes its height as form-wide config, not as per-item data", () => {
|
|
128
|
+
const html = read("b-memo");
|
|
129
|
+
expect(html).toContain(`prop-attr-rows="rows"`);
|
|
130
|
+
expect(html).not.toContain(`data-bind-rows`);
|
|
131
|
+
expect(html).toContain(`prop-attr-data-size="size"`);
|
|
132
|
+
expect(html).toContain(`prop-attr-data-variant="variant"`);
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
// b-textarea is the authoring-time sibling that OWNS the control's stylesheet, the way b-select owns
|
|
136
|
+
// .field__select for b-choice. If it ever stopped declaring the class, b-memo would render an
|
|
137
|
+
// unstyled box and the test above would still pass, so the ownership is asserted here rather than
|
|
138
|
+
// assumed.
|
|
139
|
+
test("b-textarea declares the control class its data-first sibling reuses", () => {
|
|
140
|
+
const css = readFileSync(join(ATOMS, "b-textarea", "b-textarea.css"), "utf8");
|
|
141
|
+
expect(css).toContain(`.field__textarea`);
|
|
142
|
+
expect(readdirSync(join(ATOMS, "b-textarea")).filter((f) => f.endsWith(".css"))).toEqual(["b-textarea.css"]);
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
// ---- the tick box, and the renderer behaviour that decided its shape -------------------------
|
|
146
|
+
//
|
|
147
|
+
// The obvious design is ONE authoring-time atom with a `type` prop. Measured on 2026-08-13 through
|
|
148
|
+
// createRenderer: PASS 0 APPENDS a prop's attribute rather than replacing a literal one already in
|
|
149
|
+
// the template, so `<b-checkbox type="radio">` renders `type="checkbox" type="radio"` and the browser
|
|
150
|
+
// honors the first. A radio that is silently a checkbox is exactly the class of failure this family
|
|
151
|
+
// has now hit three times, so the type is a literal and there are two templates.
|
|
152
|
+
test("b-checkbox and b-radio each state their own type, with no prop that could shadow it", () => {
|
|
153
|
+
for (const [name, type] of [["b-checkbox", "checkbox"], ["b-radio", "radio"]] as const) {
|
|
154
|
+
const html = read(name).replace(/<!--[\s\S]*?-->/g, "");
|
|
155
|
+
expect(openTag(html, "field__box")).toContain(`type="${type}"`);
|
|
156
|
+
// A prop-attr-type alongside the literal would render both and change nothing. Ban it outright.
|
|
157
|
+
expect(html).not.toContain(`prop-attr-type`);
|
|
158
|
+
}
|
|
159
|
+
});
|
|
160
|
+
|
|
161
|
+
test("b-checkbox declares the control class b-radio and b-check both reuse", () => {
|
|
162
|
+
const css = readFileSync(join(ATOMS, "b-checkbox", "b-checkbox.css"), "utf8");
|
|
163
|
+
expect(css).toContain(`.field__box`);
|
|
164
|
+
expect(readdirSync(join(ATOMS, "b-checkbox")).filter((f) => f.endsWith(".css"))).toEqual(["b-checkbox.css"]);
|
|
165
|
+
// b-radio is authoring-time but adds no rule of its own; if it ever grows one, the two controls
|
|
166
|
+
// have started drifting and this is where that shows up.
|
|
167
|
+
expect(readdirSync(join(ATOMS, "b-radio")).filter((f) => f.endsWith(".css"))).toEqual([]);
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
// The data-first side can do in one atom what the authoring side needs two for, because a BINDING
|
|
171
|
+
// replaces where a config prop appends. That inversion is the whole reason b-check exists once.
|
|
172
|
+
test("b-check takes its type from data, with no literal to shadow the binding", () => {
|
|
173
|
+
const html = read("b-check").replace(/<!--[\s\S]*?-->/g, "");
|
|
174
|
+
expect(html).toContain(`data-bind-type="type"`);
|
|
175
|
+
expect(openTag(html, "field__box")).not.toContain(`type="checkbox"`);
|
|
176
|
+
expect(openTag(html, "field__box")).not.toContain(`type="radio"`);
|
|
177
|
+
// The name is per-item data on purpose: a radio GROUP is made by every item sharing one name, and
|
|
178
|
+
// a form-wide config prop would have forced that on every group the page renders.
|
|
179
|
+
expect(html).toContain(`data-bind-name="name"`);
|
|
180
|
+
expect(html).toContain(`data-bind-checked="checked"`);
|
|
181
|
+
});
|
|
182
|
+
|
|
183
|
+
// This atom shipped 2026-08-13 with NO surface, because the vocabulary had no verb that could tick a
|
|
184
|
+
// box and an address would have advertised a write that lands, reports success and moves nothing.
|
|
185
|
+
// The verb exists now (check.set, contract.ts), so the address does too — and the assertion that
|
|
186
|
+
// replaces the old absence is the one that keeps the address honest: it has to be a `check` address,
|
|
187
|
+
// because a `field` one would advertise field.set, which writes el.value, and a tick box's value is
|
|
188
|
+
// what the form SUBMITS rather than whether it is ticked. The atom cannot pin its own prefix (the
|
|
189
|
+
// value comes from the spec at render time), so what is pinned here is the binding's PLACE: on the
|
|
190
|
+
// input, never on the wrapper, the same rule b-field and b-choice are held to.
|
|
191
|
+
test("b-check addresses the input, matching b-field's control-not-label rule", () => {
|
|
192
|
+
const html = read("b-check");
|
|
193
|
+
expect(openTag(html, "field__box")).toContain(`data-bind-data-surface="surface"`);
|
|
194
|
+
expect(openTag(html, "field")).not.toContain(`data-bind-data-surface`);
|
|
195
|
+
});
|
|
196
|
+
|
|
197
|
+
// ---- the two message slots, and the required marker ------------------------------------------
|
|
198
|
+
//
|
|
199
|
+
// Both slots ship in every framed template, which is only safe because they collapse when empty.
|
|
200
|
+
// Measured the same day: a prop-text whose prop is NOT supplied leaves the template's own text in
|
|
201
|
+
// place, so a slot carrying a fallback would print that fallback on every field nobody wrote a hint
|
|
202
|
+
// for. The fallback has to be empty, and that is invisible in a diff unless something asserts it.
|
|
203
|
+
test("every framed control carries a hint and an error slot", () => {
|
|
204
|
+
const missing: string[] = [];
|
|
205
|
+
for (const name of FRAMED) {
|
|
206
|
+
const html = read(name);
|
|
207
|
+
for (const slot of ["hint", "error"]) {
|
|
208
|
+
if (!html.includes(`class="field__${slot}"`)) missing.push(`${name}: .field__${slot}`);
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
expect(missing).toEqual([]);
|
|
212
|
+
});
|
|
213
|
+
|
|
214
|
+
test("a message slot's fallback content is empty, or it prints on every field that has no message", () => {
|
|
215
|
+
const offenders: string[] = [];
|
|
216
|
+
for (const name of FRAMED) {
|
|
217
|
+
for (const m of read(name).matchAll(/<span class="field__(hint|error)"[^>]*>([\s\S]*?)<\/span>/g)) {
|
|
218
|
+
if (m[2]!.trim() !== "") offenders.push(`${name}: .field__${m[1]} fallback is ${JSON.stringify(m[2])}`);
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
expect(offenders).toEqual([]);
|
|
222
|
+
});
|
|
223
|
+
|
|
224
|
+
test("the frame declares both slots, hides them when empty, and marks a required label itself", () => {
|
|
225
|
+
const css = readFileSync(join(ATOMS, "b-input", "b-input.css"), "utf8");
|
|
226
|
+
expect(css).toContain(`.field__hint`);
|
|
227
|
+
expect(css).toContain(`.field__error`);
|
|
228
|
+
// The collapse is what makes an unconditional slot safe; without it every field grows a gap.
|
|
229
|
+
expect(css).toMatch(/\.field__hint:empty[^{]*\{[^}]*display:\s*none/);
|
|
230
|
+
// The marker reads the attribute the browser already enforces, so it cannot drift from it and no
|
|
231
|
+
// author can forget it. A marker carried in markup instead would be a second source of truth.
|
|
232
|
+
expect(css).toMatch(/\.field:has\(:required\)\s+\.field__label::after/);
|
|
233
|
+
// An error is weight against the hint's fade, never a hue of its own (DESIGN-SYSTEM §2).
|
|
234
|
+
expect(css).not.toMatch(/\.field__error[^{]*\{[^}]*color:\s*(red|#)/);
|
|
235
|
+
});
|
|
236
|
+
|
|
237
|
+
// ---- what the catalog does with a doc, which was not what the file looked like ------------------
|
|
238
|
+
//
|
|
239
|
+
// Measured against the RENDERED page on 2026-08-13, not read off the source. Three silent faults,
|
|
240
|
+
// and the first two are now fixed in catalog.ts rather than worked around here:
|
|
241
|
+
//
|
|
242
|
+
// 1. Every prose line before the first heading was joined into ONE paragraph, so four paragraphs
|
|
243
|
+
// of rationale arrived as one wall. The parser keeps paragraphs now.
|
|
244
|
+
// 2. Prose under a heading was DROPPED while the heading was still emitted, so a section
|
|
245
|
+
// explaining a caller rule rendered as a heading with nothing beneath it — worse than losing
|
|
246
|
+
// the text, because it reads as broken rather than absent. Groups carry their prose now.
|
|
247
|
+
// 3. A fence that is not html fell through to the prose collector when it sat before the first
|
|
248
|
+
// heading, which is how raw JSON braces ended up mid-sentence in two shipped intros. Any
|
|
249
|
+
// non-html fence is skipped whole now.
|
|
250
|
+
//
|
|
251
|
+
// What no parser can fix is a single paragraph that is simply too long, so that is what is asserted,
|
|
252
|
+
// across EVERY component doc rather than just this family.
|
|
253
|
+
// Two of the three are now designed out rather than asserted: the parser renders a group's prose and
|
|
254
|
+
// skips a non-html fence whole, so a prose-only section is legitimate and a spec block can no longer
|
|
255
|
+
// leak. What is left is the part no parser can fix, which is how long a single paragraph is.
|
|
256
|
+
function allDocs(dir = import.meta.dir, out: string[] = []): string[] {
|
|
257
|
+
for (const e of readdirSync(dir, { withFileTypes: true })) {
|
|
258
|
+
const full = join(dir, e.name);
|
|
259
|
+
if (e.isDirectory()) allDocs(full, out);
|
|
260
|
+
else if (e.name.endsWith(".md")) out.push(full);
|
|
261
|
+
}
|
|
262
|
+
return out;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/** Every paragraph the catalog will print, fences and headings removed, hard wraps rejoined. */
|
|
266
|
+
const paragraphs = (md: string): string[] =>
|
|
267
|
+
md.replace(/```[\s\S]*?```/g, "").split(/\n\s*\n/)
|
|
268
|
+
.map((p) => p.split("\n").filter((l) => !l.startsWith("#")).join(" ").replace(/\s+/g, " ").trim())
|
|
269
|
+
.filter(Boolean);
|
|
270
|
+
|
|
271
|
+
// Three docs predate the rule and are not this change's to rewrite: they belong to components
|
|
272
|
+
// nobody asked about, and shortening someone else's prose is a separate judgment call. Named rather
|
|
273
|
+
// than excluded silently, and this list is a debt to shrink. It must never grow.
|
|
274
|
+
const LONG_PARAGRAPH_LEGACY = new Set(["console.md", "app-shell.md", "app-window.md"]);
|
|
275
|
+
|
|
276
|
+
test("no component doc has a paragraph long enough to read as a wall", () => {
|
|
277
|
+
// Median across the catalog is under 400 characters and only a handful clear 700, so 800 is a
|
|
278
|
+
// ceiling on the genuinely unreadable rather than a house style. The docs that prompted this ran
|
|
279
|
+
// to 2100 as a single joined block.
|
|
280
|
+
const offenders: string[] = [];
|
|
281
|
+
for (const file of allDocs()) {
|
|
282
|
+
const name = file.split("/").pop()!;
|
|
283
|
+
if (LONG_PARAGRAPH_LEGACY.has(name)) continue;
|
|
284
|
+
const longest = Math.max(0, ...paragraphs(readFileSync(file, "utf8")).map((p) => p.length));
|
|
285
|
+
if (longest > 800) offenders.push(`${name}: ${longest} characters in one paragraph`);
|
|
286
|
+
}
|
|
287
|
+
expect(offenders).toEqual([]);
|
|
288
|
+
});
|
|
289
|
+
|
|
290
|
+
test("no section heading is truly empty: it has prose, a panel, or it should not exist", () => {
|
|
291
|
+
const offenders: string[] = [];
|
|
292
|
+
for (const file of allDocs()) {
|
|
293
|
+
for (const part of readFileSync(file, "utf8").split(/^## /m).slice(1)) {
|
|
294
|
+
const label = part.split("\n")[0]!.trim();
|
|
295
|
+
const body = part.slice(label.length);
|
|
296
|
+
if (!body.includes("```html") && !paragraphs(body).length) {
|
|
297
|
+
offenders.push(`${file.split("/").pop()}: "${label}"`);
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
expect(offenders).toEqual([]);
|
|
302
|
+
});
|
|
303
|
+
|
|
304
|
+
// ---- the layout ------------------------------------------------------------------------------
|
|
305
|
+
test("form-grid is CSS only, and its auto-fit floor cannot overflow a narrow viewport", () => {
|
|
306
|
+
const dir = join(import.meta.dir, "molecules", "form-grid");
|
|
307
|
+
expect(readdirSync(dir).sort()).toEqual(["form-grid.css", "form-grid.md"]);
|
|
308
|
+
const css = readFileSync(join(dir, "form-grid.css"), "utf8");
|
|
309
|
+
// The classic auto-fit bug: a bare minmax floor wider than the screen scrolls the page sideways,
|
|
310
|
+
// and it only ever shows up on a real device. min(floor, 100%) is the fix, so pin it.
|
|
311
|
+
expect(css).toMatch(/minmax\(min\(var\(--form-grid-min\), 100%\), 1fr\)/);
|
|
312
|
+
// A message box spans without being asked; that rule is the reason this component earns its place.
|
|
313
|
+
expect(css).toMatch(/\.form-grid > \.field:has\(\.field__textarea\)/);
|
|
314
|
+
});
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/* molecules/attachment — a document hanging off a page: a deck, a paper, a slide set. CSS-only
|
|
2
|
+
(CONVENTIONS §4), composed by hand, nothing data-binds it.
|
|
3
|
+
|
|
4
|
+
The shape is deliberately quiet and horizontal. An attachment is not the page's content, it is
|
|
5
|
+
the thing the page is about, offered on the way in — so it announces itself in one row near the
|
|
6
|
+
top and then gets out of the way. That is the whole reason it is not a media-card: a poster-sized
|
|
7
|
+
tile at the top of a note reads as the subject rather than the appendix.
|
|
8
|
+
|
|
9
|
+
The whole row is the link. Composed as an <a> with <span> children, so every child that must sit
|
|
10
|
+
on its own line declares display, because a <span> inside an <a> does not get one for free. Owns
|
|
11
|
+
no outer margin: where an attachment sits is the consumer's layout decision. */
|
|
12
|
+
.attachment {
|
|
13
|
+
display: flex;
|
|
14
|
+
flex-wrap: wrap;
|
|
15
|
+
align-items: center;
|
|
16
|
+
gap: var(--space-4);
|
|
17
|
+
padding: var(--space-3) var(--space-4);
|
|
18
|
+
border: 1px solid var(--color-line);
|
|
19
|
+
border-radius: var(--radius-md);
|
|
20
|
+
text-decoration: none;
|
|
21
|
+
color: var(--color-fg);
|
|
22
|
+
transition: background-color 0.15s, border-color 0.15s;
|
|
23
|
+
}
|
|
24
|
+
.attachment:hover { background: var(--paper-2); border-color: var(--ink); }
|
|
25
|
+
|
|
26
|
+
/* the kind chip: PDF, DECK, SLIDES. Monospace and small, so it reads as a file type rather than
|
|
27
|
+
a heading, and fixed-width enough that a row of attachments lines up down the left. */
|
|
28
|
+
.attachment__kind {
|
|
29
|
+
flex: none;
|
|
30
|
+
min-width: 3.5rem;
|
|
31
|
+
padding: var(--space-1) var(--space-2);
|
|
32
|
+
border: 1px solid var(--color-line);
|
|
33
|
+
border-radius: var(--radius-sm);
|
|
34
|
+
font-family: var(--font-mono);
|
|
35
|
+
font-size: var(--text-xs);
|
|
36
|
+
text-transform: uppercase;
|
|
37
|
+
letter-spacing: .04em;
|
|
38
|
+
text-align: center;
|
|
39
|
+
color: var(--color-muted);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
.attachment__body { flex: 1 1 12rem; min-width: 10rem; }
|
|
43
|
+
.attachment__title { display: block; font-size: var(--text-base); overflow-wrap: anywhere; }
|
|
44
|
+
.attachment__meta {
|
|
45
|
+
display: block;
|
|
46
|
+
margin-top: var(--space-1);
|
|
47
|
+
font-size: var(--text-xs);
|
|
48
|
+
color: var(--color-muted);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/* the affordance on the right: says what the click does. Hidden on narrow screens, where the row
|
|
52
|
+
is obviously tappable and the words cost more than they carry.
|
|
53
|
+
|
|
54
|
+
The row WRAPS rather than squeezing (flex-wrap above, and a 12rem basis on the body). Without
|
|
55
|
+
that, a narrow container — the component catalog's preview column is the one that caught it —
|
|
56
|
+
crushes the title to one word per line while the chip and this label sit comfortably beside it.
|
|
57
|
+
A viewport media query cannot fix that: the viewport is wide, the box is not. */
|
|
58
|
+
.attachment__action {
|
|
59
|
+
flex: none;
|
|
60
|
+
font-size: var(--text-sm);
|
|
61
|
+
color: var(--color-muted);
|
|
62
|
+
}
|
|
63
|
+
.attachment:hover .attachment__action { color: var(--color-fg); }
|
|
64
|
+
@media (max-width: 32rem) {
|
|
65
|
+
.attachment__action { display: none; }
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/* ---- AI / in-transit: an attachment the AI is still producing wears the dashed terminal edge,
|
|
69
|
+
the same vocabulary card, badge and field use. */
|
|
70
|
+
.attachment[data-commit="pending"],
|
|
71
|
+
[data-grade="grain"] .attachment { border-style: dashed; border-color: var(--ink); }
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Attachment
|
|
2
|
+
|
|
3
|
+
A document hanging off a page: a deck, a paper, a slide set. One quiet horizontal row, near the top,
|
|
4
|
+
saying what is attached and what opening it costs. Composed by hand, so nothing data-binds it.
|
|
5
|
+
|
|
6
|
+
It is deliberately **not** a `media-card`. A poster-sized tile at the top of a note reads as the
|
|
7
|
+
subject of the page; an attachment is the thing the page is *about*, offered on the way in. It
|
|
8
|
+
announces itself in one row and gets out of the way.
|
|
9
|
+
|
|
10
|
+
The whole row is the link. Children are `<span>`s inside an `<a>`, so anything that must sit on its
|
|
11
|
+
own line declares `display` (a `<span>` in an `<a>` does not get one for free). The component owns no
|
|
12
|
+
outer margin: where it sits is the consumer's layout decision.
|
|
13
|
+
|
|
14
|
+
## Attachment
|
|
15
|
+
```html
|
|
16
|
+
<a class="attachment" href="#gallery">
|
|
17
|
+
<span class="attachment__kind">PDF</span>
|
|
18
|
+
<span class="attachment__body">
|
|
19
|
+
<span class="attachment__title">Beyond Limits, the ideation workshop</span>
|
|
20
|
+
<span class="attachment__meta">32 slides · 2.5 MB · opens in a tab here</span>
|
|
21
|
+
</span>
|
|
22
|
+
<span class="attachment__action">Open →</span>
|
|
23
|
+
</a>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## A talk that lives on the site
|
|
27
|
+
```html
|
|
28
|
+
<a class="attachment" href="/notes/ten-times-zero">
|
|
29
|
+
<span class="attachment__kind">Talk</span>
|
|
30
|
+
<span class="attachment__body">
|
|
31
|
+
<span class="attachment__title">Ten times zero</span>
|
|
32
|
+
<span class="attachment__meta">28 slides · runs in the browser</span>
|
|
33
|
+
</span>
|
|
34
|
+
<span class="attachment__action">Open →</span>
|
|
35
|
+
</a>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
**Write the meta line as a cost, not a boast.** Page count, size, and where it opens are the three
|
|
39
|
+
things someone weighs before clicking. `--space` and type come from the tokens; the only per-use knob
|
|
40
|
+
is the kind chip's text.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/* molecules/doc-frame — a document rendered INSIDE the page instead of replacing it. CSS-only
|
|
2
|
+
(CONVENTIONS §4), composed by hand, nothing data-binds it.
|
|
3
|
+
|
|
4
|
+
Why it exists: a link straight to a PDF hands the tab to the browser's viewer and the site is
|
|
5
|
+
gone, chrome and all. Pointed at a route that composes this, the document becomes an ordinary
|
|
6
|
+
page, which means it becomes an ordinary open tab (scripts/tabs.js projects visited paths), which
|
|
7
|
+
means the reader can close it and still be where they were.
|
|
8
|
+
|
|
9
|
+
<object> and not <iframe>: same element, better failure. A browser that cannot render the type
|
|
10
|
+
inline renders the element's CHILDREN instead, so the fallback is markup rather than a script
|
|
11
|
+
sniffing for support. Same origin only — this is for documents the site itself serves, and it is
|
|
12
|
+
emphatically not a hole for third-party embeds.
|
|
13
|
+
|
|
14
|
+
The escape hatch below the frame is NOT redundant with that fallback, and this is the part worth
|
|
15
|
+
remembering: iOS Safari neither renders a multi-page PDF inline nor triggers the fallback. It
|
|
16
|
+
draws page one in a dead box and stops. So the direct link is always visible, for everybody.
|
|
17
|
+
|
|
18
|
+
Height is a knob (--doc-frame-height) because a slide deck and a two-column paper want different
|
|
19
|
+
boxes; the default is most of the viewport, floored so a short window still shows a page. */
|
|
20
|
+
.doc-frame { margin: 0; }
|
|
21
|
+
|
|
22
|
+
.doc-frame__object {
|
|
23
|
+
display: block;
|
|
24
|
+
width: 100%;
|
|
25
|
+
height: var(--doc-frame-height, max(28rem, 78vh));
|
|
26
|
+
border: 1px solid var(--color-line);
|
|
27
|
+
border-radius: var(--radius-md);
|
|
28
|
+
background: var(--paper-2);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/* the <object>'s own children: shown only when the browser refuses the document inline */
|
|
32
|
+
.doc-frame__fallback {
|
|
33
|
+
margin: 0;
|
|
34
|
+
padding: var(--space-6);
|
|
35
|
+
color: var(--color-muted);
|
|
36
|
+
font-size: var(--text-sm);
|
|
37
|
+
line-height: var(--leading-relaxed);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/* always visible, under the frame: the plain link out, plus whatever the consumer puts beside it */
|
|
41
|
+
.doc-frame__escape {
|
|
42
|
+
display: flex;
|
|
43
|
+
flex-wrap: wrap;
|
|
44
|
+
align-items: baseline;
|
|
45
|
+
gap: var(--space-3);
|
|
46
|
+
margin-top: var(--space-3);
|
|
47
|
+
font-size: var(--text-sm);
|
|
48
|
+
color: var(--color-muted);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
.doc-frame[data-commit="pending"] .doc-frame__object,
|
|
52
|
+
[data-grade="grain"] .doc-frame__object { border-style: dashed; border-color: var(--ink); }
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Doc frame
|
|
2
|
+
|
|
3
|
+
A document rendered **inside** the page instead of replacing it. Point a route at one and a PDF
|
|
4
|
+
becomes an ordinary page, which makes it an ordinary open tab (`scripts/tabs.js` projects visited
|
|
5
|
+
paths), which means the reader can close it and still be where they were. A bare link to a `.pdf`
|
|
6
|
+
hands the tab to the browser's viewer and the site is gone, chrome and all.
|
|
7
|
+
|
|
8
|
+
Composed by hand, so nothing data-binds it. **Same-origin documents only.** This is for files the
|
|
9
|
+
site itself serves; it is not a hole for third-party embeds.
|
|
10
|
+
|
|
11
|
+
`<object>` rather than `<iframe>` for one reason: a browser that cannot render the type inline
|
|
12
|
+
renders the element's **children** instead, so the fallback is markup and not a script sniffing for
|
|
13
|
+
support.
|
|
14
|
+
|
|
15
|
+
## Doc frame
|
|
16
|
+
```html
|
|
17
|
+
<figure class="doc-frame">
|
|
18
|
+
<object class="doc-frame__object" data="/assets/doc-sample.pdf" type="application/pdf"
|
|
19
|
+
aria-label="Sample document, rendered in the page">
|
|
20
|
+
<p class="doc-frame__fallback">
|
|
21
|
+
This browser will not display the document inline. Open it directly instead.
|
|
22
|
+
</p>
|
|
23
|
+
</object>
|
|
24
|
+
<figcaption class="doc-frame__escape">
|
|
25
|
+
<a href="/assets/doc-sample.pdf">Open the file directly</a>
|
|
26
|
+
<span>1 page · 753 bytes</span>
|
|
27
|
+
</figcaption>
|
|
28
|
+
</figure>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## The escape hatch is not optional
|
|
32
|
+
|
|
33
|
+
The `<figcaption>` link is **not** redundant with the `<object>` fallback, and this is the part worth
|
|
34
|
+
remembering when a future change makes it look like clutter: **iOS Safari neither renders a
|
|
35
|
+
multi-page PDF inline nor triggers the fallback.** It draws page one in a dead box and stops. Nothing
|
|
36
|
+
in the markup can detect that, so the direct link stays visible for everybody rather than being
|
|
37
|
+
hidden behind a fallback that never fires.
|
|
38
|
+
|
|
39
|
+
## Height
|
|
40
|
+
|
|
41
|
+
`--doc-frame-height` (default `max(28rem, 78vh)`) sets the box, because a slide deck and a
|
|
42
|
+
two-column paper want different ones. Set it on the `.doc-frame`.
|
|
43
|
+
|
|
44
|
+
```html
|
|
45
|
+
<figure class="doc-frame" style="--doc-frame-height: 32rem;">
|
|
46
|
+
<object class="doc-frame__object" data="/assets/doc-sample.pdf" type="application/pdf"
|
|
47
|
+
aria-label="Sample document in a shorter frame">
|
|
48
|
+
<p class="doc-frame__fallback">This browser will not display the document inline.</p>
|
|
49
|
+
</object>
|
|
50
|
+
</figure>
|
|
51
|
+
```
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/* molecules/form-grid — the layout the field family never had. A .field is flex: 1 inside a column,
|
|
2
|
+
which is a rule about how one field behaves and says nothing about how several sit together, so
|
|
3
|
+
every form so far has laid itself out by hand. One class per element (BEM, component-scoped);
|
|
4
|
+
variants are attributes, same pattern as the rest.
|
|
5
|
+
|
|
6
|
+
CSS only, no .html: there is nothing to render, only a rule about children. It wraps controls —
|
|
7
|
+
b-input, b-field, b-choice, b-memo, b-checkbox and their siblings — and it requires nothing of its
|
|
8
|
+
own parent. */
|
|
9
|
+
.form-grid {
|
|
10
|
+
/* The narrowest a field may be before the grid drops a column. A local custom property rather than
|
|
11
|
+
a bare number, so a page with unusually long labels can raise it without forking this file. */
|
|
12
|
+
--form-grid-min: 16rem;
|
|
13
|
+
display: grid;
|
|
14
|
+
/* min() is what keeps auto-fit honest below the track size: without it a 16rem floor on a 320px
|
|
15
|
+
phone overflows the viewport horizontally, which is the classic auto-fit bug and it only ever
|
|
16
|
+
shows up on a real device. */
|
|
17
|
+
grid-template-columns: repeat(auto-fit, minmax(min(var(--form-grid-min), 100%), 1fr));
|
|
18
|
+
gap: var(--space-4);
|
|
19
|
+
/* Fields differ in height once one of them carries a hint or an error, and a stretched row would
|
|
20
|
+
pull every control's border down to match the tallest. */
|
|
21
|
+
align-items: start;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/* A control that wants the full width says so, and one kind of control never has to: a message box
|
|
25
|
+
is a paragraph, and a paragraph in a half-width column is the layout mistake this rule exists to
|
|
26
|
+
make unmakeable. Keyed off the control being present, so it holds for the hand-authored textarea
|
|
27
|
+
and the generated one alike. */
|
|
28
|
+
.form-grid > [data-span="full"],
|
|
29
|
+
.form-grid > .field:has(.field__textarea) { grid-column: 1 / -1; }
|
|
30
|
+
|
|
31
|
+
/* ---- columns (attribute). auto-fit is the default and fits the most cases; a fixed count is for a
|
|
32
|
+
form whose shape is a design decision rather than a consequence of width. minmax(0, 1fr) rather
|
|
33
|
+
than a bare 1fr, so a long placeholder cannot push a track wider than its share. */
|
|
34
|
+
.form-grid[data-columns="1"] { grid-template-columns: 1fr; }
|
|
35
|
+
.form-grid[data-columns="2"] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
|
|
36
|
+
.form-grid[data-columns="3"] { grid-template-columns: repeat(3, minmax(0, 1fr)); }
|
|
37
|
+
|
|
38
|
+
/* A fixed column count is a desktop decision. On a narrow screen it collapses, because two columns
|
|
39
|
+
of form fields on a phone is not a smaller version of the design, it is a different and worse one. */
|
|
40
|
+
@media (max-width: 40rem) {
|
|
41
|
+
.form-grid[data-columns] { grid-template-columns: 1fr; }
|
|
42
|
+
}
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Form grid
|
|
2
|
+
|
|
3
|
+
The layout the field family never had. A field is told to grow inside a column, which says nothing
|
|
4
|
+
about how several sit together, so every form so far laid itself out by hand. CSS only, so there is
|
|
5
|
+
no tag: put the class on whatever holds the controls, hand-authored or generated, and it asks nothing
|
|
6
|
+
of its own parent.
|
|
7
|
+
|
|
8
|
+
Columns are found rather than declared by default, flowing into as many tracks as fit down to a
|
|
9
|
+
minimum width a page can raise. A fixed count is an attribute, and it collapses to one column on a
|
|
10
|
+
narrow screen. Two rules make one mistake unmakeable: a message box takes the full width without
|
|
11
|
+
being asked, and fields align to the top so one carrying a hint cannot drag its neighbours down.
|
|
12
|
+
|
|
13
|
+
**One limit.** That collapse keys off the viewport rather than the container, so a fixed count inside
|
|
14
|
+
a narrow panel keeps its columns and the fields get cramped. The found columns have no such problem,
|
|
15
|
+
because their floor is a width rather than a count. Prefer them wherever the container can be much
|
|
16
|
+
narrower than the window.
|
|
17
|
+
|
|
18
|
+
## Found columns (the default)
|
|
19
|
+
|
|
20
|
+
```html
|
|
21
|
+
<div class="form-grid">
|
|
22
|
+
<label class="field">
|
|
23
|
+
<span class="field__label">Name</span>
|
|
24
|
+
<input class="field__input" name="name" placeholder="Jane">
|
|
25
|
+
</label>
|
|
26
|
+
<label class="field">
|
|
27
|
+
<span class="field__label">Email</span>
|
|
28
|
+
<input class="field__input" type="email" name="email" placeholder="jane@example.com" required>
|
|
29
|
+
</label>
|
|
30
|
+
<label class="field">
|
|
31
|
+
<span class="field__label">Company</span>
|
|
32
|
+
<input class="field__input" name="company">
|
|
33
|
+
<span class="field__hint">Optional.</span>
|
|
34
|
+
</label>
|
|
35
|
+
<label class="field">
|
|
36
|
+
<span class="field__label">Message</span>
|
|
37
|
+
<textarea class="field__textarea" name="message" rows="3"></textarea>
|
|
38
|
+
</label>
|
|
39
|
+
</div>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Two columns, and a full-width row
|
|
43
|
+
|
|
44
|
+
```html
|
|
45
|
+
<div class="form-grid" data-columns="2">
|
|
46
|
+
<label class="field">
|
|
47
|
+
<span class="field__label">First name</span>
|
|
48
|
+
<input class="field__input" name="first">
|
|
49
|
+
</label>
|
|
50
|
+
<label class="field">
|
|
51
|
+
<span class="field__label">Last name</span>
|
|
52
|
+
<input class="field__input" name="last">
|
|
53
|
+
</label>
|
|
54
|
+
<label class="field" data-span="full">
|
|
55
|
+
<span class="field__label">Where should the reply go</span>
|
|
56
|
+
<input class="field__input" type="email" name="reply" required>
|
|
57
|
+
<span class="field__hint">Spanning the whole row because it was asked to.</span>
|
|
58
|
+
</label>
|
|
59
|
+
<label class="field">
|
|
60
|
+
<input type="checkbox" class="field__box" name="terms" value="yes" required>
|
|
61
|
+
<span class="field__label">I agree to be contacted</span>
|
|
62
|
+
</label>
|
|
63
|
+
</div>
|
|
64
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tjakoen/grain",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.22",
|
|
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",
|