tutuca 0.9.52 → 0.9.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.52",
+  "version": "0.9.53",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",

package/skill/tutuca/SKILL.md

@@ -40,7 +40,9 @@ done:
 | Authoring `component({...})`, `html\`...\`` views, macros, fields, events, lists, styles | [core.md](./core.md)           |
 | CLI commands, flags, exit codes, full linter rule list                                         | [cli.md](./cli.md)             |
 | Drag & drop, dynamic bindings (`*x`), pseudo-`x`, custom seq types, Tailwind/MargaUI | [advanced.md](./advanced.md)   |
+| Authoring tests — `getTests` shape, calling methods/input/receive/bubble/response/alter handlers, designing handlers for testability | [testing.md](./testing.md) |
 
-Read `core.md` first. Reach for `cli.md` or `advanced.md` only when the
-task touches them — both files are referenced inline from `core.md` so
-you'll be pointed there when relevant.
+Read `core.md` first. Reach for `cli.md`, `advanced.md`, or
+`testing.md` only when the task touches them — all three are
+referenced inline from `core.md` so you'll be pointed there when
+relevant.

package/skill/tutuca/core.md

@@ -10,8 +10,11 @@ the `tutuca` CLI.
 > Advanced topics (drag & drop, dynamic bindings `*x`, pseudo-`x` for
 > `<select>`/`<table>`/`<tr>`, custom seq types, Tailwind/MargaUI
 > compilation): see [advanced.md](./advanced.md). CLI commands, flags,
-> exit codes, and full linter rule list: see [cli.md](./cli.md). Read
-> those only when the task touches them.
+> exit codes, and full linter rule list: see [cli.md](./cli.md).
+> Authoring tests — `getTests` shape, calling methods/input/receive/
+> bubble/response/alter handlers, designing for testability: see
+> [testing.md](./testing.md). Read those only when the task touches
+> them.
 
 ## Verifying changes
 
@@ -37,8 +40,10 @@ edit done:
         tutuca <module-path> test --grep "inc()"    # one path
 
    Exits `4` on any failure. Skip this step when the change is purely
-   templates/styling — `render` already covers that. Full reference,
-   including a worked `getTests()` export, in [cli.md](./cli.md).
+   templates/styling — `render` already covers that. Authoring patterns
+   (handler calling convention, designing handlers for testability,
+   worked `getTests` export) in [testing.md](./testing.md); CLI flags
+   and exit codes in [cli.md](./cli.md).
 
 3. **Render the example(s) that exercise the feature you changed** —
    confirms the component actually mounts in a headless DOM with the new

package/skill/tutuca/testing.md

@@ -0,0 +1,266 @@
+# Tutuca Cheatsheet — Testing
+
+How to author component tests in Tutuca: the `getTests` export shape,
+the calling conventions for methods and handler blocks (`input`,
+`receive`, `bubble`, `response`, `alter`), and the view-handler design
+rule that keeps tests free of fake DOM events. Run them with
+`tutuca <module-path> test` — flags and exit codes are in
+[cli.md](./cli.md). General authoring lives in
+[core.md](./core.md).
+
+## Setup
+
+A module opts into `tutuca test` by exporting `getTests`:
+
+```js
+export function getTests({ describe, test, expect }) {
+  describe(MyComp, () => {
+    test("does the thing", () => {
+      expect(MyComp.make().doTheThing().count).to.equal(1);
+    });
+  });
+}
+```
+
+- `expect` is chai.
+- `test` and `describe` are **Tutuca's own** subset of the common
+  Mocha/Bun-style API, injected by `tutuca test` — not Bun's built-ins.
+  Available calls: `describe(title, fn)`, `describe(Component, fn)`,
+  `describe(title, { component }, fn)`, and `test(title, fn)`. There is
+  no `before` / `after` / `beforeEach` / `it` / skip-flag — don't reach
+  for them.
+- `describe(Component, fn)` auto-tags the suite with `Component.name`,
+  so `tutuca <module> test Component` picks it up. Untagged `test(...)`
+  inside a tagged `describe` inherits the tag.
+
+Run with `tutuca <module-path> test [name] [--grep <pattern>] [--bail]`.
+Full flag/format/exit-code reference in [cli.md](./cli.md).
+
+## What to test
+
+Run tests when the change is observable from JS — methods, handlers,
+factories, coercion in `make({...})`. Skip them for pure
+template/styling tweaks; `tutuca <module> render` covers those.
+
+- **Methods** — call directly: `Comp.make({...}).method(args)`. Assert
+  on the *returned* instance (Tutuca state is immutable).
+- **Input handlers** — call via
+  `Comp.input.handlerName.call(comp, ...args)` (see *Calling input
+  handlers* below).
+- **All other handler kinds** (`receive`, `bubble`, `response`, `alter`,
+  and `on` if a component declares one) follow the **same shape**:
+  `Comp.<kind>.handlerName.call(comp, ...declaredArgs)`. Only the
+  arguments the handler receives differ:
+    - `receive.<name>(ctx)` — `ctx` carries `send` / `request` / `bubble`.
+    - `bubble.<name>(payload, ctx)` — `payload` is whatever the child sent.
+    - `response.<name>(res, err, ctx)` — async result + error.
+    - `alter.<name>(...)` — iteration handlers used by `@when`,
+      `@loop-with`, `@enrich-with`. Each kind has its own signature; see
+      *Testing iteration handlers* below.
+  Pass a plain stand-in for `ctx` (e.g. `{}`) when the handler doesn't
+  read from it; otherwise build the minimal shape it touches.
+- **Factories / coercion** — `Comp.make({...})` shape, defaults, and
+  any deep-coercion you wired up.
+
+## Calling input handlers
+
+Pattern:
+
+```js
+Comp.input.handlerName.call(comp, arg1, arg2, /* … */);
+```
+
+- Why `.call`: input handlers are plain functions stored on the
+  component descriptor. `this` must be bound explicitly to the instance.
+- `comp` is an instance — `Comp.make({...})`.
+- The args after `comp` are exactly what the template would have passed
+  (see next section). The auto-appended `ctx` is *not* required in
+  tests when the handler doesn't read from it; pass `{}` or a stub if
+  it does.
+- Returned value is the next instance.
+
+## Testing iteration handlers
+
+`alter` handlers run inside `@each` / `@when` / `@loop-with` /
+`@enrich-with` and have three distinct shapes:
+
+- `loopWith(seq)` — called once with the collection, returns an
+  `iterData` object. `this` is the parent component instance.
+- `when(key, value, iterData)` — called per element, returns truthy to
+  keep. `this` is the parent component instance.
+- `enrichWith(binds, key, value, iterData)` — called per kept element;
+  mutates `binds` (which already contains `key` and `value`). `this` is
+  the parent component instance.
+
+You can call each one directly with `.call(comp, ...)`, but in practice
+you want to test them as a pipeline: filter + loop-data + enrichment
+together produce a list of bindings the view sees. Use
+`collectIterBindings` from `tutuca/dev` for that:
+
+```js
+import { collectIterBindings } from "tutuca/dev";
+
+const c = MyComp.make({ items: [...] });
+const r = collectIterBindings(MyComp, c, c.items, {
+  loopWith: "loopHandlerName",   // optional
+  when: "whenHandlerName",       // optional
+  enrichWith: "enrichHandlerName", // optional
+});
+// r is Array<{ key, value, ...enrichments }> — one entry per kept item,
+// in iteration order.
+```
+
+- `seq` can be a plain JS Array, a JS `Map`, or any immutable.js indexed
+  or keyed seq.
+- Handler names refer to entries in `MyComp.alter`. An unknown name
+  throws — there's no silent fallback.
+- The `compInstance` is `this` for every handler. Pass
+  `MyComp.make({ field: ... })` so handlers that read `this.field` see
+  the value you want.
+
+Example:
+
+```js
+const Items = component({
+  name: "Items",
+  fields: { items: [], multiplier: 1 },
+  alter: {
+    loopMeta(seq) { return { len: seq.length, doubled: seq.length * 2 }; },
+    keepEven(k) { return k % 2 === 0; },
+    addLabel(binds, k, v, { len }) { binds.label = `${k}/${len}: ${v}`; },
+  },
+});
+
+test("filters and enriches", () => {
+  const c = Items.make({ items: [10, 20, 30, 40] });
+  const r = collectIterBindings(Items, c, c.items, {
+    loopWith: "loopMeta",
+    when: "keepEven",
+    enrichWith: "addLabel",
+  });
+  expect(r).to.deep.equal([
+    { key: 0, value: 10, label: "0/4: 10" },
+    { key: 2, value: 30, label: "2/4: 30" },
+  ]);
+});
+```
+
+Use this whenever the iteration logic is the subject under test —
+no DOM, no view, no Stack/Renderer needed. For end-to-end checks that
+the view actually wires these handlers correctly, use
+`tutuca <module> render` instead.
+
+## Designing handlers so tests stay simple
+
+Tutuca templates resolve handler args by name (see
+[core.md](./core.md) *Event Handling*). When you author a handler,
+**pick the most specific named args you need; don't take the raw
+event**. With named args, the test passes a literal; with `event`,
+the test must fabricate a DOM-event-shaped object.
+
+The dot-prefix in the template picks the handler block: a leading `.`
+means "method on `this`", no dot means an input handler. The same
+named-arg rule applies to both. Both forms below are correct
+placements — what matters is what argument the handler asks for.
+
+**Bad — method:**
+
+```html
+<input @on.input=".setName event" />
+```
+```js
+methods: { setName(event) { return this.setName(event.target.value); } }
+```
+
+**Good — method:**
+
+```html
+<input @on.input=".setName value" />
+```
+```js
+methods: { setName(value) { return this.setName(value); } }
+```
+
+**Bad — input handler:**
+
+```html
+<input @on.input="setCount event" />
+```
+```js
+input: { setCount(event) { return this.setCount(parseInt(event.target.value, 10)); } }
+```
+
+**Good — input handler:**
+
+```html
+<input @on.input="setCount valueAsInt" />
+```
+```js
+input: { setCount(n) { return this.setCount(n); } }
+```
+
+At test time, the "good" forms become trivial:
+
+```js
+expect(MyComp.make().setName("Ada").name).to.equal("Ada");
+expect(MyComp.input.setCount.call(MyComp.make(), 42).count).to.equal(42);
+```
+
+The "bad" forms force every test to construct
+`{ target: { value: "42" } }` (or a fuller stub when more fields are
+read), which is brittle and obscures intent.
+
+Built-in named args (full list in [core.md](./core.md) *Event
+Handling*): `value`, `valueAsInt`, `valueAsFloat`, `target`, `event`,
+`isAlt`, `isShift`, `isCtrl` / `isCmd`, `key`, `keyCode`, `isUpKey`,
+`isDownKey`, `isSend`, `isCancel`, `isTabKey`, `ctx`, `dragInfo`.
+`ctx` is auto-appended last. Reach for `event` only when no narrower
+arg fits.
+
+## Worked example
+
+A `getTests` export covering a method (`inc`), an input handler with no
+args (`dec`), and an input handler with a named arg (`setCount` taking
+`valueAsInt`):
+
+```js
+export function getTests({ describe, test, expect }) {
+  describe(Counter, () => {
+    describe("inc()", () => {                         // method
+      test("returns a Counter with count + 1", () => {
+        expect(Counter.make().inc().count).to.equal(1);
+      });
+      test("does not mutate the original instance", () => {
+        const c = Counter.make({ count: 7 });
+        c.inc();
+        expect(c.count).to.equal(7);
+      });
+    });
+
+    describe("dec()", () => {                         // input handler, no args
+      test("returns a Counter with count - 1", () => {
+        const next = Counter.input.dec.call(Counter.make());
+        expect(next.count).to.equal(-1);
+      });
+    });
+
+    describe("setCount()", () => {                    // input handler, valueAsInt
+      test("sets the count from a parsed int", () => {
+        const next = Counter.input.setCount.call(Counter.make(), 42);
+        expect(next.count).to.equal(42);
+      });
+    });
+
+    test("inc and dec round-trip", () => {            // untagged, inherits Counter
+      expect(Counter.input.dec.call(Counter.make().inc()).count).to.equal(0);
+    });
+  });
+}
+```
+
+## See also
+
+- [core.md](./core.md) — *Verifying changes*, *Event Handling*,
+  *Component Skeleton*.
+- [cli.md](./cli.md) — `test` flags, exit codes, output formats,
+  `--grep` syntax.