@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.
Files changed (43) 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/figure/figure.css +8 -0
  35. package/components/molecules/figure/figure.md +12 -0
  36. package/components/molecules/form-grid/form-grid.css +42 -0
  37. package/components/molecules/form-grid/form-grid.md +64 -0
  38. package/components/molecules/readiness/readiness.css +51 -0
  39. package/components/molecules/readiness/readiness.md +91 -0
  40. package/package.json +1 -1
  41. package/scripts/ai-dispatch.js +74 -4
  42. package/scripts/ai-dispatch.test.ts +68 -0
  43. package/styles/variables.css +6 -2
@@ -56,6 +56,22 @@ import { createSpotlight } from "/scripts/ai-spotlight.js";
56
56
  // eslint-disable-next-line no-control-regex
57
57
  const FIELD_VALUE_BAD_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f]/;
58
58
  const SAFE_FIELD_VALUE = (v) => typeof v === "string" && v.length <= FIELD_VALUE_CAP && !FIELD_VALUE_BAD_CHARS.test(v);
59
+
60
+ // ---- tick: a check.set state's guard — mirrors ai/contract.ts's isCheckedState EXACTLY ---------
61
+ // Same self-contained copy as the two above, drift-guarded by ai-dispatch.test.ts.
62
+ const CHECKED_STATE = (v) => typeof v === "boolean";
63
+ // WHICH elements a tick may touch, and this is the load-bearing half of the op. `"checked" in el`
64
+ // would be the obvious guard and it is the wrong one: EVERY input carries a `checked` property, so
65
+ // a tick aimed at a text field would pass it, assign a property the control does not render, and
66
+ // report a success nobody can see — the same class of silent lie that kept `field.set` away from
67
+ // tick boxes in the first place. The type is what actually decides whether a box can be ticked.
68
+ const TICKABLE_TYPES = new Set(["checkbox", "radio"]);
69
+ // ---- span: block.span's closed word list — mirrors ai/contract.ts's BLOCK_SPANS EXACTLY --------
70
+ // Same self-contained copy as the guards above, and the same reason: this file ships to the
71
+ // browser with no imports, so the contract's closed set has to be re-stated here and kept honest
72
+ // by the drift-guard test rather than by anyone remembering. A fourth word reaching a stylesheet
73
+ // that has no rule for it would lay the block out at some default width and report success.
74
+ const BLOCK_SPANS = new Set(["full", "half", "third"]);
59
75
  // A `navigate` op tears the page down — irreversible, so give any in-flight settle (the
60
76
  // spotlight's glide off, a caret's last frame) a beat to read before that happens, instead of a
61
77
  // bare synchronous location.assign mid-render. Named per CLAUDE.md lesson #9 (a magic number
@@ -324,6 +340,57 @@ import { createSpotlight } from "/scripts/ai-spotlight.js";
324
340
  el.dispatchEvent(new Event("input", { bubbles: true })); // page validation/counters stay honest
325
341
  }
326
342
  return;
343
+ case "tick": // AI sets a tick box's state; it PERSISTS for human review (never a submit)
344
+ // No focus steal, no submit, no form access — el.checked and nothing else. A radio may only
345
+ // be TICKED: clearing one leaves its group with nothing selected, which is a state no click
346
+ // can reach, so the AI must not be able to put a form there either. Refused out loud, on the
347
+ // navigate precedent, because a silent refusal is indistinguishable from a broken op.
348
+ if (el && TICKABLE_TYPES.has(el.type) && CHECKED_STATE(op.checked)) {
349
+ if (el.type === "radio" && op.checked === false) {
350
+ console.error("[ai-dispatch] refused to clear a radio — no click can reach that state", op.target);
351
+ return;
352
+ }
353
+ el.checked = op.checked;
354
+ el.setAttribute("data-grade", "grain"); // AI ink until the human touches it (trusted-input settle below)
355
+ // BOTH events, because a real tick fires both and a page listening for either stays honest:
356
+ // `change` is the one a form listens to for a tick box, `input` is the one the settle
357
+ // listener below reads (and the one `fill` already dispatches).
358
+ el.dispatchEvent(new Event("input", { bubbles: true }));
359
+ el.dispatchEvent(new Event("change", { bubbles: true }));
360
+ }
361
+ return;
362
+ // The two BLOCK ops. Both mutate the addressed element and nothing else, and both fire a
363
+ // bubbling `change` so the page that owns the composition can derive its state back off the
364
+ // DOM. That handshake is the whole reason these are ops rather than a back channel into the
365
+ // page's module: the dispatcher stays the single writer, and the page stays the single source
366
+ // of truth about what it holds. Without the event a block op would look exactly like it
367
+ // worked and reappear on the next repaint, which is the failure `tick` was invented to close
368
+ // one control over.
369
+ case "span": // AI sets one block's width word (block.span)
370
+ if (el && BLOCK_SPANS.has(op.span)) {
371
+ el.setAttribute("data-span", op.span);
372
+ el.setAttribute("data-grade", "grain"); // AI ink, same treatment a fill or a tick gets
373
+ el.dispatchEvent(new Event("change", { bubbles: true }));
374
+ } else if (el) {
375
+ console.error("[ai-dispatch] refused a span outside the closed three", op.span, op.target);
376
+ }
377
+ return;
378
+ case "move": // AI shifts one block one place (block.move)
379
+ // Clamped rather than wrapped, matching moveBlock's own rule and the arrows a human presses:
380
+ // the first block's "up" is a no-op, not a jump to the bottom. Refused out loud when the
381
+ // direction is not one of the two, on the navigate precedent.
382
+ if (el && (op.direction === "up" || op.direction === "down")) {
383
+ const sib = op.direction === "up" ? el.previousElementSibling : el.nextElementSibling;
384
+ if (sib) {
385
+ if (op.direction === "up") el.parentNode.insertBefore(el, sib);
386
+ else el.parentNode.insertBefore(sib, el);
387
+ el.setAttribute("data-grade", "grain");
388
+ el.dispatchEvent(new Event("change", { bubbles: true }));
389
+ }
390
+ } else if (el) {
391
+ console.error("[ai-dispatch] refused a move that is neither up nor down", op.direction, op.target);
392
+ }
393
+ return;
327
394
  case "log": // one entry into the interaction TIMELINE (§5g)
328
395
  if (el && typeof op.html === "string") {
329
396
  el.insertAdjacentHTML("beforeend", op.html);
@@ -545,10 +612,13 @@ import { createSpotlight } from "/scripts/ai-spotlight.js";
545
612
  if (ev.key === "Escape" && isActing()) { ev.preventDefault(); interrupt(); }
546
613
  });
547
614
 
548
- // A `fill`ed field wears data-grade="grain" (AI ink) until the human TOUCHES it: the first
549
- // TRUSTED input event settles it clean (the human edited — the ink is theirs now). Synthetic
550
- // events (including fill's own bubbling `input` above) are not a human touch, so they never
551
- // settle it. Delegated once — grain's grade-as-signal reaching a form control (DESIGN-SYSTEM §3).
615
+ // A `fill`ed field — or a `tick`ed box — wears data-grade="grain" (AI ink) until the human
616
+ // TOUCHES it: the first TRUSTED input event settles it clean (the human edited — the ink is
617
+ // theirs now). Synthetic events (including fill's and tick's own bubbling `input` above) are not
618
+ // a human touch, so they never settle it. A tick box needs no special case here: clicking one
619
+ // fires a trusted `input` like any other control, and `"value" in el` holds for it (a tick box
620
+ // has a value — it is just not the state, which is the whole reason `tick` exists).
621
+ // Delegated once — grain's grade-as-signal reaching a form control (DESIGN-SYSTEM §3).
552
622
  document.addEventListener("input", (ev) => {
553
623
  if (!ev.isTrusted) return;
554
624
  const el = ev.target;
@@ -70,6 +70,38 @@ test("fill sets .value + a grain grade and dispatches a bubbling input event; a
70
70
  expect(dispatch).toMatch(/isTrusted\)\s*return/); // …synthetic events never do
71
71
  });
72
72
 
73
+ test("the tick state guard in ai-dispatch.js matches contract.ts's isCheckedState verbatim", async () => {
74
+ const [dispatch, contract] = await Promise.all([read("./ai-dispatch.js"), read("../ai/contract.ts")]);
75
+ expect(dispatch).toContain('const CHECKED_STATE = (v) => typeof v === "boolean";');
76
+ expect(contract).toContain('export const isCheckedState = (v: unknown): v is boolean => typeof v === "boolean";');
77
+ });
78
+
79
+ test("tick sets .checked on a checkbox or radio ONLY, grades it grain, and fires input + change", async () => {
80
+ // Source-text assertions, the same bar the fill case is held to above (the IIFE can't be
81
+ // imported — file header). The element guard is the one that matters: EVERY input carries a
82
+ // `checked` property, so `"checked" in el` would let a tick land on a text field, assign a
83
+ // property nothing renders, and report a success nobody can see.
84
+ const dispatch = await read("./ai-dispatch.js");
85
+ const tickCase = dispatch.match(/case "tick":([\s\S]*?)\n return;/)?.[1] ?? "";
86
+ expect(tickCase).toContain("TICKABLE_TYPES.has(el.type)"); // the type decides, not the property
87
+ expect(tickCase).not.toContain('"checked" in el'); // the guard that would silently lie
88
+ expect(tickCase).toContain("CHECKED_STATE(op.checked)"); // last-line-of-defense re-check
89
+ expect(tickCase).toContain("el.checked = op.checked"); // state, not value, not markup
90
+ expect(tickCase).toContain('el.setAttribute("data-grade", "grain")');
91
+ expect(tickCase).toContain('new Event("input", { bubbles: true })');
92
+ expect(tickCase).toContain('new Event("change", { bubbles: true })');
93
+ expect(dispatch).toContain('const TICKABLE_TYPES = new Set(["checkbox", "radio"]);');
94
+ });
95
+
96
+ test("tick refuses to CLEAR a radio, out loud — no click can reach an all-clear group", async () => {
97
+ const dispatch = await read("./ai-dispatch.js");
98
+ const tickCase = dispatch.match(/case "tick":([\s\S]*?)\n return;/)?.[1] ?? "";
99
+ expect(tickCase).toMatch(/el\.type === "radio" && op\.checked === false/);
100
+ expect(tickCase).toContain("console.error"); // refused audibly, like an unsafe navigate
101
+ // and the refusal returns BEFORE the assignment, rather than logging and carrying on
102
+ expect(tickCase.indexOf("console.error")).toBeLessThan(tickCase.indexOf("el.checked = op.checked"));
103
+ });
104
+
73
105
  test("a navigate op with an unsafe href is never assigned to location — asserted on the shared regex", async () => {
74
106
  const contract = await read("../ai/contract.ts");
75
107
  const src = contract.match(/const SAFE_NAV_HREF = (\/.*\/);/)?.[1];
@@ -83,3 +115,39 @@ test("a navigate op with an unsafe href is never assigned to location — assert
83
115
  expect(re.test("//evil.example")).toBe(false);
84
116
  expect(re.test("/\\evil.example")).toBe(false);
85
117
  });
118
+
119
+ // The block ops' own drift guard. ai-dispatch.js ships to the browser with no imports, so the
120
+ // contract's closed span list has to be re-stated there; this is what keeps the copy honest, the
121
+ // same way the FIELD_VALUE_CAP and CHECKED_STATE guards above do for their verbs.
122
+ test("the dispatcher's BLOCK_SPANS matches contract.ts's, word for word", async () => {
123
+ const dispatch = await Bun.file(new URL("./ai-dispatch.js", import.meta.url)).text();
124
+ const contract = await Bun.file(new URL("../ai/contract.ts", import.meta.url)).text();
125
+ const inDispatch = dispatch.match(/const BLOCK_SPANS = new Set\(\[([^\]]+)\]\)/)?.[1];
126
+ const inContract = contract.match(/export const BLOCK_SPANS = \[([^\]]+)\] as const/)?.[1];
127
+ expect(inDispatch).toBeTruthy();
128
+ expect(inContract).toBeTruthy();
129
+ const words = (s: string) => s.split(",").map((w) => w.trim().replace(/["']/g, "")).filter(Boolean);
130
+ expect(words(inDispatch!)).toEqual(words(inContract!));
131
+ });
132
+
133
+ // A block op that mutated the DOM and told nobody would look exactly like it worked and be undone
134
+ // by the next repaint, because the page holds the composition and the dispatcher holds the element.
135
+ // The bubbling `change` is the handshake, and it is the whole reason these are ops rather than a
136
+ // back channel into the page's own module.
137
+ test("both block ops fire a bubbling change so the page can derive its state back", async () => {
138
+ const dispatch = await Bun.file(new URL("./ai-dispatch.js", import.meta.url)).text();
139
+ for (const kind of ["span", "move"]) {
140
+ const body = dispatch.split(`case "${kind}":`)[1]?.split("return;")[0] ?? "";
141
+ expect(body, `${kind} must announce itself`).toContain('new Event("change", { bubbles: true })');
142
+ expect(body, `${kind} must wear AI ink`).toContain('setAttribute("data-grade", "grain")');
143
+ }
144
+ });
145
+
146
+ // Clamped, never wrapped: the first block's "up" is a no-op, matching the arrows a human presses.
147
+ test("move refuses to wrap: no sibling means no move", async () => {
148
+ const dispatch = await Bun.file(new URL("./ai-dispatch.js", import.meta.url)).text();
149
+ const body = dispatch.split('case "move":')[1]?.split("return;")[0] ?? "";
150
+ expect(body).toContain("previousElementSibling");
151
+ expect(body).toContain("nextElementSibling");
152
+ expect(body).toContain("if (sib)");
153
+ });
@@ -42,8 +42,12 @@
42
42
  --paper-2: #E8E6DF; /* subtle hover surface */
43
43
  --panel: #E8E6DF; /* grouped "sheet" — a hair brighter than the page */
44
44
  --ink: #1C1B17; /* primary text, filled dots, rules */
45
- --ink-muted: #6E6C64; /* secondary text, section labels */
46
- --ink-faint: #ABA89F; /* fading insights, empty/future dots */
45
+ /* The two quiet tiers, and the line between them is a contract, not a shade. MUTED carries text
46
+ a reader is meant to read, so it clears WCAG AA (4.5:1) on --paper; it was #6E6C64 and measured
47
+ 3.98:1, which is why it moved. FAINT is decoration: fading insights, empty and future dots. It
48
+ does NOT clear AA and is not meant to, so nothing a reader needs may be painted with it. */
49
+ --ink-muted: #65635B; /* secondary text, section labels. 4.55:1 on --paper */
50
+ --ink-faint: #ABA89F; /* fading insights, empty/future dots. DECORATIVE ONLY */
47
51
  --hairline: #1C1B17; /* solid rules (under headlines) */
48
52
  --line-soft: rgba(28, 27, 23, .14); /* translucent border for quiet grouping */
49
53