@tjakoen/grain 0.1.21 → 0.1.23
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/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/form-from-data.test.ts +314 -0
- package/components/molecules/figure/figure.css +8 -0
- package/components/molecules/figure/figure.md +12 -0
- package/components/molecules/form-grid/form-grid.css +42 -0
- package/components/molecules/form-grid/form-grid.md +64 -0
- package/components/molecules/readiness/readiness.css +51 -0
- package/components/molecules/readiness/readiness.md +91 -0
- package/package.json +1 -1
- package/scripts/ai-dispatch.js +74 -4
- package/scripts/ai-dispatch.test.ts +68 -0
- package/styles/variables.css +6 -2
|
@@ -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
|
+
});
|
|
@@ -10,6 +10,14 @@
|
|
|
10
10
|
line-height: var(--leading-normal);
|
|
11
11
|
}
|
|
12
12
|
|
|
13
|
+
/* diagram variant: an inline SVG rather than an <img>. MILL emits this for a rendered
|
|
14
|
+
mermaid fence. The SVG carries token references, so it re-colors with the theme; the only
|
|
15
|
+
job here is fitting it to the column and letting a wide flowchart scroll rather than
|
|
16
|
+
shrink to unreadable. No caption: a diagram fence has no caption source, and the prose
|
|
17
|
+
convention (an italic line under the figure) stays. */
|
|
18
|
+
.figure[data-variant="diagram"] { max-width: 100%; overflow-x: auto; }
|
|
19
|
+
.figure[data-variant="diagram"] svg { display: block; max-width: 100%; height: auto; }
|
|
20
|
+
|
|
13
21
|
/* clipped-photo variant: a hard editorial clip instead of a straight rectangle */
|
|
14
22
|
.figure[data-variant="clipped"] img { border: 0; clip-path: polygon(0 0, 100% 0, 100% 94%, 96% 100%, 0 100%); }
|
|
15
23
|
|
|
@@ -18,3 +18,15 @@ composed by hand, so nothing data-binds it. Images never overflow the column.
|
|
|
18
18
|
<img src="/assets/figure-sample.svg" alt="The same image, clipped">
|
|
19
19
|
</figure>
|
|
20
20
|
```
|
|
21
|
+
|
|
22
|
+
## Diagram
|
|
23
|
+
Holds an inline SVG instead of an image. MILL emits this for a rendered mermaid fence, with the
|
|
24
|
+
SVG's colors written as token references so the diagram follows both theme axes without being
|
|
25
|
+
re-rendered. A diagram wider than the column scrolls rather than shrinking to unreadable.
|
|
26
|
+
|
|
27
|
+
```html
|
|
28
|
+
<figure class="figure" data-variant="diagram">
|
|
29
|
+
<svg viewBox="0 0 120 40"><rect x="1" y="1" width="118" height="38"
|
|
30
|
+
fill="var(--color-surface)" stroke="var(--color-line)"></rect></svg>
|
|
31
|
+
</figure>
|
|
32
|
+
```
|
|
@@ -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
|
+
```
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/* molecules/readiness — a verdict over its evidence: whether a set of boundary conditions
|
|
2
|
+
holds, the one line saying why, and what is still in the way. The generic shape behind
|
|
3
|
+
"ready to deploy", "ready to release", "ready to hand off". CSS-only (CONVENTIONS §4):
|
|
4
|
+
composed by hand, nothing data-binds it.
|
|
5
|
+
|
|
6
|
+
Parent context: none required. It fills its container and carries no width of its own —
|
|
7
|
+
drop it inside a `.card` for a bordered tile, or leave it bare in a panel.
|
|
8
|
+
|
|
9
|
+
Composition: the evidence rows are a `status-list`, NOT a shape this component invents.
|
|
10
|
+
A readiness block that grows its own row markup is the thing to avoid — the marks, the
|
|
11
|
+
in-flight lifecycle and the per-row `data-surface` hook all already live there.
|
|
12
|
+
|
|
13
|
+
This is a READOUT, not an ask. It reports state and stops. A closed-set question with
|
|
14
|
+
options and an escape belongs on CRUMB's decision ask, and having two surfaces put the
|
|
15
|
+
same question to someone is the failure DECISIONS names outright. */
|
|
16
|
+
|
|
17
|
+
.readiness { display: flex; flex-direction: column; gap: var(--space-2); }
|
|
18
|
+
|
|
19
|
+
/* The verdict sits at display scale on purpose: grade texture only reads at >= --text-2xl
|
|
20
|
+
(CLAUDE.md lesson 4), and a verdict is exactly the line an AI might compose — so put
|
|
21
|
+
`data-grade="grain"` here and the provenance is legible instead of theoretical. */
|
|
22
|
+
.readiness__verdict {
|
|
23
|
+
font-size: var(--text-2xl);
|
|
24
|
+
line-height: var(--leading-tight);
|
|
25
|
+
color: var(--color-fg);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
.readiness__why {
|
|
29
|
+
font-size: var(--text-sm);
|
|
30
|
+
line-height: var(--leading-normal);
|
|
31
|
+
color: var(--color-muted);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/* State reads as ink level and edge weight, never hue — the same rule stat-tile follows.
|
|
35
|
+
`blocked` earns a solid-ink edge because it is the one meant to stop you; `waiting`
|
|
36
|
+
recedes; `ready` and the default are identical, since a healthy verdict needs no
|
|
37
|
+
shouting. */
|
|
38
|
+
.readiness[data-state="blocked"] {
|
|
39
|
+
border-left: 2px solid var(--color-fg);
|
|
40
|
+
padding-left: var(--space-3);
|
|
41
|
+
}
|
|
42
|
+
.readiness[data-state="waiting"] .readiness__verdict { color: var(--color-muted); }
|
|
43
|
+
|
|
44
|
+
/* In transit — the detector has not finished deciding. The shared idiom keyed off
|
|
45
|
+
`data-commit="pending"` and an ancestor `[data-grade="grain"]`, expressed here as a
|
|
46
|
+
dashed leading edge, never a bespoke "loading" state. */
|
|
47
|
+
.readiness[data-commit="pending"],
|
|
48
|
+
[data-grade="grain"] .readiness[data-commit="pending"] {
|
|
49
|
+
border-left: 2px dashed var(--color-fg);
|
|
50
|
+
padding-left: var(--space-3);
|
|
51
|
+
}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Readiness
|
|
2
|
+
|
|
3
|
+
A verdict over its evidence: whether a set of boundary conditions holds, one line saying why,
|
|
4
|
+
and what is still in the way. The generic shape behind "ready to deploy", "ready to release",
|
|
5
|
+
"ready to hand off" — a run that has finished checking and now has to tell someone.
|
|
6
|
+
|
|
7
|
+
It is a **readout, not an ask.** It reports and stops. A closed-set question with options and an
|
|
8
|
+
escape hatch belongs on CRUMB's decision ask; two surfaces putting the same question to the same
|
|
9
|
+
person is a failure mode rather than thoroughness.
|
|
10
|
+
|
|
11
|
+
Composition note: no parent context is required — it fills its container and carries no width of
|
|
12
|
+
its own, so it sits inside a `card` or bare in a panel. The evidence rows are a **`status-list`**,
|
|
13
|
+
not markup this component invents: the marks, the in-flight lifecycle and the per-row
|
|
14
|
+
`data-surface` hook already live there. Counts alongside the verdict are `stat` tiles, laid out by
|
|
15
|
+
the parent.
|
|
16
|
+
|
|
17
|
+
State is an attribute (`data-state`), and reads as ink level and edge weight, never hue.
|
|
18
|
+
|
|
19
|
+
## Ready
|
|
20
|
+
```html
|
|
21
|
+
<div class="readiness" data-state="ready">
|
|
22
|
+
<span class="readiness__verdict">Ready to hand off</span>
|
|
23
|
+
<span class="readiness__why">Gates green, plan synced, nothing in flight.</span>
|
|
24
|
+
<ul class="status-list">
|
|
25
|
+
<li class="status-list__item">
|
|
26
|
+
<span class="status-list__mark">✓</span>
|
|
27
|
+
<span class="status-list__title">gates green</span>
|
|
28
|
+
<span class="status-list__meta">check · test</span>
|
|
29
|
+
</li>
|
|
30
|
+
<li class="status-list__item">
|
|
31
|
+
<span class="status-list__mark">✓</span>
|
|
32
|
+
<span class="status-list__title">plan synced</span>
|
|
33
|
+
<span class="status-list__meta">PLAN.md</span>
|
|
34
|
+
</li>
|
|
35
|
+
</ul>
|
|
36
|
+
</div>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Blocked
|
|
40
|
+
The one state meant to stop you, so it takes a solid-ink edge. What blocks goes in the rows; the
|
|
41
|
+
verdict says only that something does.
|
|
42
|
+
```html
|
|
43
|
+
<div class="readiness" data-state="blocked">
|
|
44
|
+
<span class="readiness__verdict">Not yet</span>
|
|
45
|
+
<span class="readiness__why">Two conditions still hold it open.</span>
|
|
46
|
+
<ul class="status-list">
|
|
47
|
+
<li class="status-list__item">
|
|
48
|
+
<span class="status-list__mark">✕</span>
|
|
49
|
+
<span class="status-list__title">tests failing</span>
|
|
50
|
+
<span class="status-list__meta">3 of 663</span>
|
|
51
|
+
</li>
|
|
52
|
+
<li class="status-list__item" data-state="waiting">
|
|
53
|
+
<span class="status-list__mark">·</span>
|
|
54
|
+
<span class="status-list__title">plan not synced</span>
|
|
55
|
+
<span class="status-list__meta">PLAN.md</span>
|
|
56
|
+
</li>
|
|
57
|
+
</ul>
|
|
58
|
+
</div>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Waiting
|
|
62
|
+
Nothing has been checked yet, so the verdict recedes rather than claiming a result.
|
|
63
|
+
```html
|
|
64
|
+
<div class="readiness" data-state="waiting">
|
|
65
|
+
<span class="readiness__verdict">Not checked</span>
|
|
66
|
+
<span class="readiness__why">No gate has run this session.</span>
|
|
67
|
+
</div>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## With counts
|
|
71
|
+
Tiles are laid out by the parent, never by a wrapper inside the component.
|
|
72
|
+
```html
|
|
73
|
+
<div class="readiness" data-state="blocked">
|
|
74
|
+
<span class="readiness__verdict">Not yet</span>
|
|
75
|
+
<span class="readiness__why">Work is uncommitted.</span>
|
|
76
|
+
<div style="display:flex;gap:var(--space-3)">
|
|
77
|
+
<div class="stat" data-tone="bad"><span class="stat__value">12</span><span class="stat__label">uncommitted</span></div>
|
|
78
|
+
<div class="stat" data-tone="muted"><span class="stat__value">1</span><span class="stat__label">unpushed</span></div>
|
|
79
|
+
</div>
|
|
80
|
+
</div>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## In transit (the detector is still deciding)
|
|
84
|
+
The shared in-flight idiom, not a bespoke loading state. The verdict sits at display scale
|
|
85
|
+
precisely so that an AI-composed line reads as grain rather than claiming to be checked fact.
|
|
86
|
+
```html
|
|
87
|
+
<div class="readiness" data-commit="pending">
|
|
88
|
+
<span class="readiness__verdict" data-grade="grain">Checking…</span>
|
|
89
|
+
<span class="readiness__why">Reading the gate log.</span>
|
|
90
|
+
</div>
|
|
91
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tjakoen/grain",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.23",
|
|
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",
|