@tjakoen/grain 0.1.21 → 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.
Files changed (38) hide show
  1. package/ai/contract.test.ts +88 -1
  2. package/ai/contract.ts +96 -3
  3. package/ai/interaction-layer.test.ts +58 -0
  4. package/ai/manifest-dom.test.ts +59 -5
  5. package/ai/manifest-dom.ts +42 -11
  6. package/ai/reasoner-kit.test.ts +11 -1
  7. package/ai/reasoner-kit.ts +40 -2
  8. package/ai/reasoner.test.ts +55 -0
  9. package/ai/reasoner.ts +75 -2
  10. package/ai/vocab-reference.ts +3 -0
  11. package/catalog/catalog.ts +56 -14
  12. package/components/atoms/b-check/b-check.html +27 -0
  13. package/components/atoms/b-check/b-check.md +67 -0
  14. package/components/atoms/b-checkbox/b-checkbox.css +61 -0
  15. package/components/atoms/b-checkbox/b-checkbox.html +17 -0
  16. package/components/atoms/b-checkbox/b-checkbox.md +83 -0
  17. package/components/atoms/b-choice/b-choice.html +16 -0
  18. package/components/atoms/b-choice/b-choice.md +35 -0
  19. package/components/atoms/b-field/b-field.html +17 -0
  20. package/components/atoms/b-field/b-field.md +43 -0
  21. package/components/atoms/b-input/b-input.css +20 -0
  22. package/components/atoms/b-input/b-input.html +7 -2
  23. package/components/atoms/b-input/b-input.md +27 -1
  24. package/components/atoms/b-memo/b-memo.html +21 -0
  25. package/components/atoms/b-memo/b-memo.md +34 -0
  26. package/components/atoms/b-option/b-option.html +5 -0
  27. package/components/atoms/b-option/b-option.md +13 -0
  28. package/components/atoms/b-radio/b-radio.html +17 -0
  29. package/components/atoms/b-radio/b-radio.md +57 -0
  30. package/components/atoms/b-textarea/b-textarea.css +48 -0
  31. package/components/atoms/b-textarea/b-textarea.html +15 -0
  32. package/components/atoms/b-textarea/b-textarea.md +70 -0
  33. package/components/form-from-data.test.ts +314 -0
  34. package/components/molecules/form-grid/form-grid.css +42 -0
  35. package/components/molecules/form-grid/form-grid.md +64 -0
  36. package/package.json +1 -1
  37. package/scripts/ai-dispatch.js +74 -4
  38. package/scripts/ai-dispatch.test.ts +68 -0
package/ai/reasoner.ts CHANGED
@@ -7,10 +7,16 @@
7
7
  // PLUMBING, never faked judgment (MVP §"Build Order").
8
8
 
9
9
  import type { Intent, Decision, Surface, RenderOp } from "./contract.ts";
10
- import { ACTIONS, PUSH_SURFACES, surfaceId, isSafeNavigateHref, isSafeFieldValue, FIELD_VALUE_CAP } from "./contract.ts";
10
+ import {
11
+ ACTIONS, BLOCK_SPANS, MOVE_DIRECTIONS, PUSH_SURFACES, surfaceId, isBlockSpan, isCheckedState,
12
+ isMoveDirection, isSafeFieldValue, isSafeNavigateHref, FIELD_VALUE_CAP,
13
+ } from "./contract.ts";
11
14
  // The reusable reasoner primitives — the stub DOGFOODS them so the exported kit (what a consumer's
12
15
  // real model composes with) and the shipped chat markup can never drift apart.
13
- import { esc, chatBubble, narrationLine, navigateOp, noteAppendOp, noteReplaceOp, fillOp } from "./reasoner-kit.ts";
16
+ import {
17
+ esc, chatBubble, narrationLine, navigateOp, noteAppendOp, noteReplaceOp, fillOp, tickOp,
18
+ removeBlockOp, spanOp, moveOp,
19
+ } from "./reasoner-kit.ts";
14
20
 
15
21
  // The scoped capabilities the reasoner is allowed to use — its tool surface. The
16
22
  // real reasoner reaches storage through least-privilege tools exactly like this.
@@ -158,6 +164,73 @@ export function makeStubReasoner(opts: StubOptions = {}): Reasoner {
158
164
  ops: [fillOp(intent.surface, value)] };
159
165
  }
160
166
 
167
+ // --- check.set: set a registered tick box's state (plans/check-set-op.md). field.set's
168
+ // sibling, and the reason it is a sibling rather than the same verb: a tick box's state
169
+ // is `checked`, and its `value` is what the form submits. The payload is a real boolean
170
+ // or nothing — a truthy string is refused rather than coerced, because "false" would tick
171
+ // the box the reasoner asked to clear, silently, which is the failure this verb exists to
172
+ // close. The door already brackets an ai-sourced intent with spotlight ops + timeline
173
+ // entries; nothing extra needed here. ---
174
+ if (intent.action === "check.set") {
175
+ const checked = intent.payload.checked;
176
+ if (!isCheckedState(checked)) {
177
+ return {
178
+ ok: false,
179
+ reason: `check.set checked rejected: must be a boolean, got ${typeof checked}`,
180
+ ops: [{ target: intent.surface, op: "flash", message: "Couldn't set that tick box.",
181
+ provenance: "system", commit: "committed" }],
182
+ };
183
+ }
184
+ const name = surfaceId(intent.surface) || intent.surface;
185
+ narrate("ticks", `${checked ? "ticking" : "clearing"} ${name} — yours to review and send`);
186
+ return { ok: true, reply: `${checked ? "Ticked" : "Cleared"} it — review and send when ready.`,
187
+ ops: [tickOp(intent.surface, checked)] };
188
+ }
189
+
190
+ // --- the three block verbs: operate ONE block of a composed page (plans/block-verbs.md).
191
+ // Deterministic and model-free, exactly like check.set: the payload is a closed word list,
192
+ // so there is nothing here for a reasoner to be clever about. The rejection echoes the
193
+ // legal words rather than saying "invalid", because the model this is aimed at is small
194
+ // and a rejection it can act on is the difference between a retry and a dead end
195
+ // (AI-INTERFACE §0, informative rejections).
196
+ //
197
+ // What none of them do is touch the page's own state directly. Each returns an op the
198
+ // dispatcher applies to the addressed cell, and the page derives its composition back off
199
+ // the DOM — because a reasoner that reached into a module's variables would be the
200
+ // privileged AI-to-DOM back channel this whole architecture exists to refuse. ---
201
+ if (intent.action === "block.remove") {
202
+ narrate("edits", `removing ${surfaceId(intent.surface) || intent.surface} from the page`);
203
+ return { ok: true, reply: "Dropped that block.", ops: [removeBlockOp(intent.surface)] };
204
+ }
205
+
206
+ if (intent.action === "block.span") {
207
+ const span = intent.payload.span;
208
+ if (!isBlockSpan(span)) {
209
+ return {
210
+ ok: false,
211
+ reason: `block.span rejected: span must be one of ${BLOCK_SPANS.join(", ")}, got ${JSON.stringify(span)}`,
212
+ ops: [{ target: intent.surface, op: "flash", message: `A block is full, half or third wide.`,
213
+ provenance: "system", commit: "committed" }],
214
+ };
215
+ }
216
+ narrate("edits", `setting ${surfaceId(intent.surface) || intent.surface} to ${span} width`);
217
+ return { ok: true, reply: `Set it to ${span} width.`, ops: [spanOp(intent.surface, span)] };
218
+ }
219
+
220
+ if (intent.action === "block.move") {
221
+ const direction = intent.payload.direction;
222
+ if (!isMoveDirection(direction)) {
223
+ return {
224
+ ok: false,
225
+ reason: `block.move rejected: direction must be one of ${MOVE_DIRECTIONS.join(", ")}, got ${JSON.stringify(direction)}`,
226
+ ops: [{ target: intent.surface, op: "flash", message: "A block moves up or down.",
227
+ provenance: "system", commit: "committed" }],
228
+ };
229
+ }
230
+ narrate("edits", `moving ${surfaceId(intent.surface) || intent.surface} ${direction}`);
231
+ return { ok: true, reply: `Moved it ${direction}.`, ops: [moveOp(intent.surface, direction)] };
232
+ }
233
+
161
234
  // --- chat.send: the assistant conversation. Your message settles CLEAN (human), then
162
235
  // the AI's reply STREAMS into a fresh bubble that stays GRAIN (AI). Same door,
163
236
  // same ops — no chat-specific machinery. User text is escaped at the writer. ---
@@ -29,6 +29,9 @@ export const RENDER_OP_KINDS: readonly { kind: string; means: string }[] = [
29
29
  { kind: "navigate", means: "change the browser's location (href) — same-origin, root-relative only" },
30
30
  { kind: "choices", means: "the AI asks the human to pick — a chat bubble with a row of choice buttons (each a chat.send)" },
31
31
  { kind: "fill", means: "prefill a registered form field's value — persists for human review (the AI never submits)" },
32
+ { kind: "tick", means: "set a registered tick box's checked state — persists for human review (a radio may only be ticked, never cleared)" },
33
+ { kind: "span", means: "set one block's width word on a composed page — full, half or third, and there is no fourth" },
34
+ { kind: "move", means: "shift one block one place on a composed page — up or down, clamped at the ends rather than wrapped" },
32
35
  ];
33
36
 
34
37
  // The one door's HTTP surface (AI-INTERFACE.md) — guarded by vocab-reference.test.ts
@@ -11,8 +11,13 @@ import { readdirSync, readFileSync } from "node:fs";
11
11
  import { join } from "node:path";
12
12
 
13
13
  interface Panel { label: string; code: string; flat?: boolean; }
14
- interface Group { label: string; panels: Panel[]; }
15
- interface Doc { name: string; slug: string; intro: string; groups: Group[]; }
14
+ // `prose` is the paragraphs written under a `## ` heading. They used to be dropped on the floor
15
+ // while the heading was still emitted, so a section explaining a caller rule rendered as a heading
16
+ // with nothing beneath it — worse than losing the text, because it reads as broken rather than
17
+ // absent. Both intro and group prose are PARAGRAPHS rather than one joined string: joining them was
18
+ // what turned four paragraphs of a component doc into a single wall.
19
+ interface Group { label: string; prose: string[]; panels: Panel[]; }
20
+ interface Doc { name: string; slug: string; intro: string[]; groups: Group[]; }
16
21
  interface Component { layer: string; slug: string; name: string; human: Doc; ai: Doc | null; }
17
22
 
18
23
  const slugify = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
@@ -27,7 +32,14 @@ const inline = (s: string) => esc(s)
27
32
  .replace(/`([^`]+)`/g, "<code>$1</code>")
28
33
  .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
29
34
  .replace(/\*([^*\n]+)\*/g, "<em>$1</em>")
30
- .replace(/\[([^\]]+)\]\((https?:\/\/[^)]+|\/[^)]*|#[^)]*)\)/g, '<a href="$2">$1</a>');
35
+ .replace(/\[([^\]]+)\]\((https?:\/\/[^)]+|\/[^)]*|#[^)]*)\)/g, '<a href="$2">$1</a>')
36
+ // A link the rule above did NOT take is a RELATIVE one, and the commonest by far is a sibling
37
+ // doc: [Radio](../b-radio/b-radio.md). It cannot become an anchor, because a .md path on disk is
38
+ // not a route this site serves and doc-links.test.ts exists to stop docs inventing routes. But
39
+ // leaving it whole printed the raw markdown mid-sentence in every doc that referenced a sibling.
40
+ // Keep the text, drop the target: the reader gets a name, and the file keeps a link that works
41
+ // wherever the markdown is read directly.
42
+ .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1");
31
43
 
32
44
  // atomic-design layers render in this order; unknown dirs fall to the end.
33
45
  const LAYER_ORDER = ["atoms", "molecules", "organisms"];
@@ -40,16 +52,27 @@ const rank = (layer: string) => { const i = LAYER_ORDER.indexOf(layer); return i
40
52
  // demonstrating itself inside its box. Default stays live — flat is the exception a doc asks for.
41
53
  function parseDoc(md: string): Doc {
42
54
  const lines = md.split("\n");
43
- const doc: Doc = { name: "Untitled", slug: "untitled", intro: "", groups: [] };
55
+ const doc: Doc = { name: "Untitled", slug: "untitled", intro: [], groups: [] };
44
56
  let group: Group | null = null;
45
57
  let pendingLabel = "";
46
58
  const intro: string[] = [];
47
59
  let i = 0;
48
60
 
61
+ /** Collect prose into the open group, or into the intro when none is open. A BLANK line ends the
62
+ * paragraph; consecutive non-blank lines are one paragraph re-joined, because these files are
63
+ * hard-wrapped and a wrap is not a paragraph break. */
64
+ const pushProse = (line: string) => {
65
+ const into = group ? group.prose : intro;
66
+ const text = line.trim();
67
+ if (!text) { if (into.length && into[into.length - 1] !== "") into.push(""); return; }
68
+ if (!into.length || into[into.length - 1] === "") into.push(text);
69
+ else into[into.length - 1] += ` ${text}`;
70
+ };
71
+
49
72
  while (i < lines.length) {
50
73
  const line = lines[i];
51
74
  if (line.startsWith("# ")) { doc.name = line.slice(2).trim(); doc.slug = slugify(doc.name); i++; continue; }
52
- if (line.startsWith("## ")) { group = { label: line.slice(3).trim(), panels: [] }; doc.groups.push(group); pendingLabel = ""; i++; continue; }
75
+ if (line.startsWith("## ")) { group = { label: line.slice(3).trim(), prose: [], panels: [] }; doc.groups.push(group); pendingLabel = ""; i++; continue; }
53
76
  if (line.startsWith("### ")) { pendingLabel = line.slice(4).trim(); i++; continue; }
54
77
  if (line.startsWith("```html")) {
55
78
  const flat = /\bflat\b/.test(line.slice(7));
@@ -57,14 +80,24 @@ function parseDoc(md: string): Doc {
57
80
  i++;
58
81
  while (i < lines.length && !lines[i].startsWith("```")) { body.push(lines[i]); i++; }
59
82
  i++; // skip closing fence
60
- if (!group) { group = { label: "", panels: [] }; doc.groups.push(group); }
83
+ if (!group) { group = { label: "", prose: [], panels: [] }; doc.groups.push(group); }
61
84
  group.panels.push({ label: pendingLabel, code: body.join("\n").trim(), flat });
62
85
  continue;
63
86
  }
64
- if (!group && line.trim()) intro.push(line.trim());
87
+ // Any OTHER fence (```json, a bare ```) is skipped whole rather than read as prose. Falling
88
+ // through used to sweep a spec block's braces into the surrounding paragraph, which is how raw
89
+ // JSON ended up mid-sentence in two shipped intros.
90
+ if (line.startsWith("```")) {
91
+ i++;
92
+ while (i < lines.length && !lines[i].startsWith("```")) i++;
93
+ i++;
94
+ continue;
95
+ }
96
+ pushProse(line);
65
97
  i++;
66
98
  }
67
- doc.intro = intro.join(" ");
99
+ doc.intro = intro.filter(Boolean);
100
+ for (const g of doc.groups) g.prose = g.prose.filter(Boolean);
68
101
  return doc;
69
102
  }
70
103
 
@@ -145,12 +178,15 @@ export function createCatalog(componentsDir: string | string[], pages?: () => st
145
178
  </figure>`;
146
179
  }
147
180
 
181
+ const paras = (cls: string, ps: string[]) => ps.map((p) => `<p class="${cls}">${inline(p)}</p>`).join("");
182
+
148
183
  const renderGroups = (groups: Group[]) => groups.map(g => `
149
184
  ${g.label ? `<h3 class="cat-group">${esc(g.label)}</h3>` : ""}
150
- <div class="panel-grid">${g.panels.map(renderPanel).join("")}</div>`).join("");
185
+ ${paras("cat-note", g.prose)}
186
+ ${g.panels.length ? `<div class="panel-grid">${g.panels.map(renderPanel).join("")}</div>` : ""}`).join("");
151
187
 
152
188
  const renderView = (doc: Doc, view: "smooth" | "grain") => `<div class="cat-doc__view" data-view="${view}">
153
- ${doc.intro ? `<p class="cat-intro">${inline(doc.intro)}</p>` : ""}
189
+ ${paras("cat-intro", doc.intro)}
154
190
  ${renderGroups(doc.groups)}
155
191
  </div>`;
156
192
 
@@ -271,11 +307,17 @@ function page(pageNav: string, navGroups: string, main: string, inject: CatalogI
271
307
  the global [data-grade] rule would cascade, then re-apply grain to .panel__live. */
272
308
  .cat-doc[data-grade="grain"] { --type-font: var(--font-smooth); }
273
309
  .cat-doc__view[data-view="grain"] .panel__live { --type-font: var(--font-grain); }
274
- .cat-intro { color: var(--color-muted); margin: 0 0 var(--space-6); }
275
- .cat-intro code { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 0.88em;
310
+ /* Intro paragraphs sit close together and the LAST one opens the gap before the first group, so a
311
+ three-paragraph intro reads as three paragraphs rather than as one block with a hole after it. */
312
+ .cat-intro { color: var(--color-muted); margin: 0 0 var(--space-3); }
313
+ .cat-intro:last-of-type { margin-bottom: var(--space-6); }
314
+ /* Prose written under a section heading: the caller rules, the limits, the why. Same voice as the
315
+ intro, and measure-capped so it does not read as one column with the panels below it. */
316
+ .cat-note { color: var(--color-muted); margin: 0 0 var(--space-3); max-inline-size: 68ch; }
317
+ .cat-intro code, .cat-note code { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 0.88em;
276
318
  background: var(--paper-2); padding: 0 0.3em; border-radius: 2px; color: var(--ink); }
277
- .cat-intro strong { color: var(--ink); font-weight: var(--font-weight-semibold); }
278
- .cat-intro a { color: var(--ink); }
319
+ .cat-intro strong, .cat-note strong { color: var(--ink); font-weight: var(--font-weight-semibold); }
320
+ .cat-intro a, .cat-note a { color: var(--ink); }
279
321
  .cat-group { font-size: var(--text-sm); text-transform: uppercase; letter-spacing: 0.05em;
280
322
  color: var(--color-muted); margin: var(--space-6) 0 var(--space-3); }
281
323
  .panel-grid { display: grid; gap: var(--space-4); grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); }
@@ -0,0 +1,27 @@
1
+ <!-- atoms/b-check — a tick box built from DATA: the data-first sibling of b-checkbox and b-radio, the
2
+ way b-field is b-input's and b-memo is b-textarea's. One atom covers both controls because here
3
+ the type arrives as a BINDING rather than as a config prop, and a binding replaces rather than
4
+ appends: `<b-check each="options" name-shared-by-the-group>` renders a radio group when every
5
+ item carries type "radio", and independent tick boxes when they carry "checkbox".
6
+ Per-item DATA: label, name, type, value, checked ("checked", not ""), required, surface, hint, error.
7
+ Form-wide CONFIG props: size. No .css: the frame is b-input.css and the control is b-checkbox.css.
8
+ There is deliberately NO literal type here. A literal would win over the binding (PASS 0 appends,
9
+ the browser honors the first attribute), so the type has to come from the item and every item has
10
+ to carry it — a null one renders a text input, which is ugly rather than silent, and dev warns on
11
+ a key left out entirely.
12
+ The surface lands as check:… and NOT as field:…, which is the whole reason this atom can be
13
+ addressed at all. A field address would advertise field.set, and field.set writes el.value: a
14
+ tick box's value is what the form SUBMITS rather than whether it is ticked, so that write would
15
+ land, report success, change the form's meaning and leave the control looking untouched. The
16
+ check kind accepts check.set and nothing else, so the address promises only what it can keep.
17
+ The binding sits on the INPUT, never on the label, for the reason b-field records: an address on
18
+ the wrapper points at something with no state to set, and the write is dropped in silence. -->
19
+ <label class="field" prop-attr-data-size="size">
20
+ <input class="field__box" data-bind-type="type"
21
+ data-bind-name="name" data-bind-value="value"
22
+ data-bind-checked="checked" data-bind-required="required"
23
+ data-bind-data-surface="surface">
24
+ <span class="field__label" data-field="label">Label</span>
25
+ <span class="field__hint" data-field="hint"></span>
26
+ <span class="field__error" data-field="error"></span>
27
+ </label>
@@ -0,0 +1,67 @@
1
+ # Check (from data)
2
+
3
+ The data-first sibling of the [Checkbox](../b-checkbox/b-checkbox.md) and the
4
+ [Radio](../b-radio/b-radio.md), and the fourth member of the family
5
+ [Field](../b-field/b-field.md), [Choice](../b-choice/b-choice.md) and [Memo](../b-memo/b-memo.md)
6
+ started. Use it when the boxes arrive as data rather than as markup. One atom covers both controls
7
+ where the authoring side needs two, because here the type is a binding, and a binding replaces where
8
+ a config property appends. Items carry label, name, type, value, checked, required, surface, hint and
9
+ error, every key present and null where unset. A group of radios is simply every item sharing one
10
+ name.
11
+
12
+ **The address is a check address, never a field one.** This atom shipped without an address at all,
13
+ because a checkbox's value is what the form submits when it is ticked rather than whether it is
14
+ ticked, and the only verb the vocabulary had for a field wrote that value: it would have landed,
15
+ reported success, changed what the form means and left the control looking untouched. The verb that
16
+ can tick a box exists now, so the surface reads `check:digest` and the kind it names accepts that
17
+ verb and no other. Give an item a `field:` address and the tick box goes back to advertising the
18
+ write that lies, so the prefix is not a formatting detail.
19
+
20
+ ## What it renders
21
+
22
+ ```html
23
+ <label class="field">
24
+ <input type="checkbox" class="field__box" name="digest" value="yes" checked="checked"
25
+ data-surface="check:digest">
26
+ <span class="field__label">Send me the monthly digest</span>
27
+ </label>
28
+ ```
29
+
30
+ The spec behind one item. Both message slots take null when there is nothing to say:
31
+
32
+ ```json
33
+ { "label": "Send me the monthly digest", "name": "digest", "type": "checkbox", "value": "yes",
34
+ "checked": "checked", "required": null, "surface": "check:digest", "hint": null, "error": null }
35
+ ```
36
+
37
+ ## A radio group, from one array
38
+
39
+ ```html
40
+ <div>
41
+ <label class="field">
42
+ <input type="radio" class="field__box" name="reply" value="email" checked="checked">
43
+ <span class="field__label">Reply by email</span>
44
+ </label>
45
+ <label class="field">
46
+ <input type="radio" class="field__box" name="reply" value="call">
47
+ <span class="field__label">Reply by phone</span>
48
+ <span class="field__hint">Only if you leave a number.</span>
49
+ </label>
50
+ </div>
51
+ ```
52
+
53
+ Every item carries the same name, which is what makes the group exclusive:
54
+
55
+ ```json
56
+ { "options": [
57
+ { "label": "Reply by email", "name": "reply", "type": "radio", "value": "email",
58
+ "checked": "checked", "required": null, "surface": "check:reply-email", "hint": null, "error": null },
59
+ { "label": "Reply by phone", "name": "reply", "type": "radio", "value": "call",
60
+ "checked": null, "required": null, "surface": "check:reply-call", "hint": "Only if you leave a number.", "error": null }
61
+ ] }
62
+ ```
63
+
64
+ A radio takes its own address per item rather than one for the group, because a verb operates a
65
+ control and a group is not one. What the verb will not do is clear a radio: a group with nothing
66
+ selected is a state no click can reach, so the request is refused rather than granted, and the way
67
+ to move a group is to tick the option you want.
@@ -0,0 +1,61 @@
1
+ /* atoms/b-checkbox — the field family's tick box, and the stylesheet b-radio and b-check both reuse.
2
+ It adds .field__box to the frame b-input.css owns, exactly the way b-select adds .field__select and
3
+ b-textarea adds .field__textarea. One class per element (BEM, component-scoped).
4
+
5
+ No appearance reset. The platform's own checkbox and radio are accessible, they already draw the
6
+ difference between a square tick and a round dot, and a hand-drawn one would need a hardcoded color
7
+ to fill — which the tokens-only rule does not allow. `accent-color` is the whole styling budget
8
+ here, and it is a token.
9
+
10
+ Not to be confused with b-switch, which is a drawn track-and-thumb for a setting the user flips.
11
+ This is a checkbox in a form: something submitted, not something switched. */
12
+ .field__box {
13
+ flex: none; margin: 0;
14
+ inline-size: var(--text-lg); block-size: var(--text-lg);
15
+ accent-color: var(--color-accent);
16
+ cursor: pointer;
17
+ }
18
+
19
+ /* The row. A .field is a column — label above, control below — and that is right for every control
20
+ whose value shows inside it. A tick box has no inside, so its label sits beside it and reads as the
21
+ thing being agreed to. Keyed off the CONTROL being present rather than off a modifier class, so a
22
+ caller cannot compose the markup correctly and still get the column: the layout follows from what
23
+ is in the frame, which is the one thing that cannot be forgotten. */
24
+ .field:has(> .field__box) {
25
+ flex-direction: row; flex-wrap: wrap; align-items: center; gap: var(--space-2);
26
+ /* The tap target is the whole row, because the label wraps the input — which is also why the box
27
+ itself is allowed to stay small. The row is what has to clear the ≥44px floor
28
+ (DESIGN-SYSTEM §7); a 17px box and a 21px line of text would not, and a checkbox nobody can
29
+ reliably hit on a phone is the one control where that failure is invisible on a desktop. */
30
+ min-block-size: 2.75rem;
31
+ }
32
+ /* In a column the label captions a control that shows its own value, so it is muted. In a check row
33
+ the label IS the value — the sentence the tick agrees to — so it reads at full ink. Size is
34
+ unchanged, so a row of checks still lines up with the fields above it. */
35
+ .field:has(> .field__box) .field__label {
36
+ color: var(--ink);
37
+ /* Take the rest of the row, so a long sentence wraps INSIDE the label beside the box rather than
38
+ wrapping the label itself onto the line under it. A tick box whose text has fallen below it
39
+ reads as two controls, and the sentence a checkbox agrees to is usually long. */
40
+ flex: 1;
41
+ }
42
+ /* The message slots would otherwise land beside the box on the same row. Send them under it, across
43
+ the whole frame, where a hint about a checkbox actually reads. */
44
+ .field:has(> .field__box) .field__hint,
45
+ .field:has(> .field__box) .field__error { flex-basis: 100%; }
46
+
47
+ /* ---- sizes (attribute, on .field, same as b-input) ---- */
48
+ .field[data-size="sm"] .field__box { inline-size: var(--text-base); block-size: var(--text-base); }
49
+ .field[data-size="lg"] .field__box { inline-size: var(--text-xl); block-size: var(--text-xl); }
50
+
51
+ /* ---- AI / in-transit: the non-text grain, same language as the rest of the family
52
+ (AI-INTERFACE §5). A box has no border of its own to dash, so the dashed "terminal" edge arrives
53
+ as an outline instead of a border-style. The focus ring is declared AFTER this on purpose: both
54
+ rules write `outline` on the same element, and a keyboard user's ring must win over the ambient
55
+ AI treatment rather than depend on which selector happens to be more specific. */
56
+ .field[data-commit="pending"] .field__box,
57
+ [data-grade="grain"] .field__box { outline: 1px dashed var(--ink); outline-offset: 2px; }
58
+
59
+ /* focus ring; data-force parallel lets the catalog show the state statically (same pattern as
60
+ b-input) — never `autofocus`, which would steal focus + scroll the catalog on load. */
61
+ .field__box:focus-visible, .field__box[data-force~="focus"] { outline: 2px solid var(--color-accent); outline-offset: 2px; }
@@ -0,0 +1,17 @@
1
+ <!-- atoms/b-checkbox — a labelled tick box in the .field frame. Config props: label, name, value,
2
+ checked (bare boolean), required (bare boolean), hint, error, size. Usable self-closed.
3
+ This atom OWNS b-checkbox.css, which declares .field__box and the check row; b-radio and b-check
4
+ both reuse it, the same division b-textarea makes for b-memo.
5
+ The type is a LITERAL here and there is deliberately no `type` prop, because a prop cannot
6
+ override it: PASS 0 APPENDS the prop's attribute rather than replacing the literal, so a tag
7
+ asking for a radio renders type="checkbox" type="radio" and the browser honors the first one.
8
+ Measured on 2026-08-13. One control per atom is the only shape that cannot lie about which
9
+ control it is, so the radio is its own file. -->
10
+ <label class="field" prop-attr-data-size="size">
11
+ <input type="checkbox" class="field__box"
12
+ prop-attr-name="name" prop-attr-value="value"
13
+ prop-attr-checked="checked" prop-attr-required="required">
14
+ <span class="field__label" prop-text="label">Label</span>
15
+ <span class="field__hint" prop-text="hint"></span>
16
+ <span class="field__error" prop-text="error"></span>
17
+ </label>
@@ -0,0 +1,83 @@
1
+ # Checkbox
2
+
3
+ A tick box in the field frame: something a form submits, rather than something the user switches.
4
+ As a component: `<b-checkbox label="I agree" name="terms" value="yes" required />`, and the tag may
5
+ self-close. Its twin is the [Radio](../b-radio/b-radio.md) and its data-first sibling is
6
+ [Check](../b-check/b-check.md). Reach for the [Switch](../b-switch/b-switch.md) instead when the
7
+ thing being set takes effect the moment it moves, like delivered or held.
8
+
9
+ This atom owns the stylesheet the other two reuse, the division the
10
+ [Textarea](../b-textarea/b-textarea.md) already makes for the Memo. It adds one class for the control
11
+ and one rule for the row, because a tick box has no inside: the label sits beside it and reads at
12
+ full ink, as the sentence being agreed to. The native control is kept as the platform draws it, and
13
+ the tap target is the whole row rather than the box.
14
+
15
+ ## States
16
+
17
+ ### Default
18
+ ```html
19
+ <label class="field">
20
+ <input type="checkbox" class="field__box" name="terms" value="yes">
21
+ <span class="field__label">I have read how this site handles what you send</span>
22
+ </label>
23
+ ```
24
+
25
+ ### Checked
26
+ ```html
27
+ <label class="field">
28
+ <input type="checkbox" class="field__box" name="digest" value="yes" checked>
29
+ <span class="field__label">Send me the monthly digest</span>
30
+ </label>
31
+ ```
32
+
33
+ ### Required, with a hint
34
+ ```html
35
+ <label class="field">
36
+ <input type="checkbox" class="field__box" name="terms" value="yes" required>
37
+ <span class="field__label">I agree to be contacted about this enquiry</span>
38
+ <span class="field__hint">Nothing is stored: the form opens your own mail client.</span>
39
+ </label>
40
+ ```
41
+
42
+ ### With an error
43
+ ```html
44
+ <label class="field">
45
+ <input type="checkbox" class="field__box" name="terms" value="yes" required>
46
+ <span class="field__label">I agree to be contacted about this enquiry</span>
47
+ <span class="field__error">Tick this before sending.</span>
48
+ </label>
49
+ ```
50
+
51
+ ### Focus
52
+ ```html
53
+ <label class="field">
54
+ <input type="checkbox" class="field__box" name="terms" value="yes" data-force="focus">
55
+ <span class="field__label">I agree to be contacted about this enquiry</span>
56
+ </label>
57
+ ```
58
+
59
+ ### AI is acting
60
+ ```html
61
+ <label class="field" data-commit="pending">
62
+ <input type="checkbox" class="field__box" name="terms" value="yes">
63
+ <span class="field__label">A box the AI is working near, dashed like the rest of the family</span>
64
+ </label>
65
+ ```
66
+
67
+ ## Sizes
68
+
69
+ ### Small
70
+ ```html
71
+ <label class="field" data-size="sm">
72
+ <input type="checkbox" class="field__box" name="sm" value="yes" checked>
73
+ <span class="field__label">Small</span>
74
+ </label>
75
+ ```
76
+
77
+ ### Large
78
+ ```html
79
+ <label class="field" data-size="lg">
80
+ <input type="checkbox" class="field__box" name="lg" value="yes" checked>
81
+ <span class="field__label">Large</span>
82
+ </label>
83
+ ```
@@ -0,0 +1,16 @@
1
+ <!-- atoms/b-choice — the select sibling of b-field, also built from DATA. Options come from
2
+ the item's own `options` array through a nested each on b-option. Per-item DATA: label,
3
+ name, options, surface, hint, error. Form-wide CONFIG props: size, variant. No .css: the .field frame
4
+ and .field__select come from b-input.css and b-select.css.
5
+ The surface binds to the SELECT, matching b-field, so a generated choice is addressable
6
+ the same way every other control is. Read the note in b-choice.md before writing to one:
7
+ a select accepts a write that a text input would, and anything that is not one of its
8
+ option values empties it instead of failing. -->
9
+ <label class="field" prop-attr-data-size="size" prop-attr-data-variant="variant">
10
+ <span class="field__label" data-field="label">Label</span>
11
+ <select class="field__select" data-bind-data-surface="surface" data-bind-name="name">
12
+ <b-option each="options"></b-option>
13
+ </select>
14
+ <span class="field__hint" data-field="hint"></span>
15
+ <span class="field__error" data-field="error"></span>
16
+ </label>
@@ -0,0 +1,35 @@
1
+ # Choice (from data)
2
+
3
+ The select sibling of the [Field](../b-field/b-field.md), for when the options are data too. Its own
4
+ template nests an each over the item's options array, so one tag renders every choice in the form and
5
+ every option inside each one. That nesting is what earns it a component of its own: a select cannot
6
+ be built from a flat field spec without a second array.
7
+
8
+ The item shape is label, name, surface, hint, error and an options array of value, label and
9
+ selected. Like [Select](../b-select/b-select.md) it contributes no frame of its own, and the native
10
+ dropdown arrow is kept, so nothing here needs a color.
11
+
12
+ **One caller rule.** A select accepts a write that a text input would, and anything that is not one
13
+ of its option values does not fail: it sets the value to an empty string, so the control goes blank
14
+ and nothing is logged. Send option values, never labels. Measured against a real page on 2026-08-13.
15
+
16
+ ## What it renders
17
+
18
+ One item of the spec, and the markup it becomes:
19
+
20
+ ```json
21
+ { "surface": "field:contact-topic", "label": "About", "name": "topic",
22
+ "hint": null, "error": null,
23
+ "options": [ { "value": "grain", "label": "GRAIN", "selected": null },
24
+ { "value": "hiring", "label": "Hiring", "selected": "selected" } ] }
25
+ ```
26
+
27
+ ```html
28
+ <label class="field">
29
+ <span class="field__label">About</span>
30
+ <select class="field__select" data-surface="field:contact-topic" name="topic">
31
+ <option value="grain">GRAIN</option>
32
+ <option value="hiring" selected="selected">Hiring</option>
33
+ </select>
34
+ </label>
35
+ ```
@@ -0,0 +1,17 @@
1
+ <!-- atoms/b-field — a labelled text field built from DATA: the data-first sibling of b-input.
2
+ Use it with each= over a field spec (`<b-field each="fields">`); use b-input when the
3
+ field is known at authoring time. Per-item DATA: label, name, type, placeholder, value,
4
+ required ("required", not ""), surface, hint, error. Form-wide CONFIG props: size, variant — a literal
5
+ attribute on the tag reaches every item of the each. No .css: the frame is b-input.css.
6
+ The surface binds to the INPUT, not to the label around it: field.set resolves the address
7
+ and then writes el.value, so an address on a label points at something with nothing to
8
+ write into, and the write is dropped without a word. That is how this shipped on
9
+ 2026-08-13 and what the portfolio's first real form found. -->
10
+ <label class="field" prop-attr-data-size="size" prop-attr-data-variant="variant">
11
+ <span class="field__label" data-field="label">Label</span>
12
+ <input class="field__input" data-bind-data-surface="surface"
13
+ data-bind-name="name" data-bind-type="type" data-bind-value="value"
14
+ data-bind-placeholder="placeholder" data-bind-required="required">
15
+ <span class="field__hint" data-field="hint"></span>
16
+ <span class="field__error" data-field="error"></span>
17
+ </label>
@@ -0,0 +1,43 @@
1
+ # Field (from data)
2
+
3
+ The data-first sibling of the [Input](../b-input/b-input.md). Same control, same frame, different
4
+ author: reach for the Input when you know the field while typing the page, and for this when the
5
+ fields arrive as data and one tag should render all of them.
6
+
7
+ Two rules make it work and both are the renderer's. Config properties are form-wide, so a literal
8
+ size or variant on the tag reaches every item. Data is per item: label, name, type, placeholder,
9
+ value, required, hint and error. Every item carries every key, null where unset, because a key left
10
+ out warns in development and an explicit null stays quiet. An item may also carry a surface, which
11
+ lands on the input itself and makes the generated field addressable, and it sits on the control
12
+ rather than the label around it because a label has nothing to write into.
13
+
14
+ There is no CSS here. The frame, the sizes, the inline variant and the AI treatment all come from
15
+ b-input.css, which is the point: two components, one control, no drift.
16
+
17
+ ## What it renders
18
+
19
+ One item of the spec, and the markup it becomes:
20
+
21
+ ```json
22
+ { "surface": "field:contact-name", "label": "Name", "name": "name",
23
+ "type": "text", "placeholder": "Jane", "value": null, "required": "required",
24
+ "hint": null, "error": null }
25
+ ```
26
+
27
+ ```html
28
+ <label class="field">
29
+ <span class="field__label">Name</span>
30
+ <input class="field__input" data-surface="field:contact-name" name="name" type="text"
31
+ placeholder="Jane" required="required">
32
+ </label>
33
+ ```
34
+
35
+ ## Inline (form-wide config)
36
+
37
+ ```html
38
+ <label class="field" data-variant="inline">
39
+ <span class="field__label">Email</span>
40
+ <input class="field__input" data-surface="field:contact-email" name="email" type="email"
41
+ placeholder="jane@example.com">
42
+ </label>
43
+ ```
@@ -16,6 +16,26 @@
16
16
  /* invalid state — native, no JS. Monochrome: a heavier rule, not a red one. */
17
17
  .field__input:user-invalid { border-width: 2px; }
18
18
 
19
+ /* ---- the two message slots, declared HERE because they belong to the frame rather than to any one
20
+ control: an input, a select, a textarea and a checkbox all want somewhere to say a thing, and a
21
+ per-control copy of these rules is how one frame becomes four. Both hide when empty, which is what
22
+ makes them safe to put in every template: a slot with nothing in it must not open a gap in the
23
+ column, and an optional slot nobody fills is the common case, not the exception. */
24
+ .field__hint { font-size: var(--text-xs); color: var(--ink-faint); line-height: var(--leading-normal); }
25
+ /* An error is NOT a red one. Status is weight, not hue (DESIGN-SYSTEM §2): the message reads at full
26
+ ink against a hint's faint, and --color-danger is hueless by default so a flavor that DOES own a
27
+ hue can reach it without this file ever naming a color. */
28
+ .field__error { font-size: var(--text-xs); color: var(--color-danger); line-height: var(--leading-normal); }
29
+ .field__hint:empty, .field__error:empty { display: none; }
30
+
31
+ /* ---- the required marker. No markup carries it and no author can forget it: the frame reads the
32
+ `required` attribute the control already has to have anyway, so the marker cannot drift from the
33
+ constraint the browser actually enforces. Decorative by construction — the semantics are native,
34
+ and a screen reader announces the control as required with or without this glyph. */
35
+ .field:has(:required) .field__label::after {
36
+ content: "*"; margin-inline-start: var(--space-1); color: var(--color-accent);
37
+ }
38
+
19
39
  /* ---- variants (attribute) ---- */
20
40
  .field[data-variant="inline"] { flex-direction: row; align-items: center; gap: var(--space-3); }
21
41
  .field[data-variant="inline"] .field__label { flex: 0 0 auto; }