tutuca 0.9.68 → 0.9.69

package/package.json

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

package/skill/tutuca/core.md

@@ -7,6 +7,9 @@ orchestration. Read this file when authoring or reviewing
 `component({...})` definitions, `view: html\`...\`` templates, macros, or
 the `tutuca` CLI.
 
+> Orchestration channels — `bubble`, `send`/`receive`, async
+> `request`/`response`, the `$unknown` fallback, and request-handler
+> registration: see [request-response.md](./request-response.md).
 > 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,
@@ -173,8 +176,8 @@ to the value the handler should run against. The same `Path` is reused
 verbatim for `ctx.send`, `ctx.bubble`, and `ctx.request` /
 response: because it's positional rather than a captured reference, an
 async response still lands at the right slot even after intervening
-transactions have rebuilt the root. See *Bubble Events*, *Send /
-Receive*, *Async Requests* for the dispatch APIs.
+transactions have rebuilt the root. See
+[request-response.md](./request-response.md) for the dispatch APIs.
 
 **Why `alter` is its own table.** Alter handlers are pure, evaluated
 on every render, and produce binds (no state change). `input` /
@@ -727,114 +730,53 @@ a same-shape handler block:
 
 Every handler is called as `handler(...args, ctx)` and returns a
 (possibly updated) instance of `this`; the framework swaps the
-returned value into the dispatch path. The four sections below cover
-each channel in turn.
+returned value into the dispatch path. The three event-driven channels
+beyond `input` — `bubble`, `send`/`receive`, async `request`/`response`
+— plus the shared `$unknown` fallback and request-handler registration
+are documented in [request-response.md](./request-response.md); the
+brief anchors below cover the essentials.
 
 `alter` is a fifth handler block, but unlike the four above it isn't
 event-triggered — the renderer invokes alter handlers to produce
 binds, not to update state. See *Mental model* and *Scope Enrichment*.
 
-## Bubble Events
-
-```js
-input:  { onClick(ctx) { ctx.bubble("treeItemSelected", [this]); return this; } },
-bubble: {
-  treeItemSelected(selected, ctx) {  // ctx.stopPropagation() to halt
-    return this.insertInLogAt(0, `selected ${selected.label}`);
-  },
-}
-```
-
-`ctx.bubble("name", args)` emits an event that walks the dispatch path
-back toward the root. Each ancestor whose component defines
-`bubble.<name>(...args, ctx)` runs it (others are skipped silently);
-bubbling stops at the root or when a handler calls
-`ctx.stopPropagation()`. Ancestors see the event *after* descendants
-have transacted, so bubble handlers are the place for aggregate state
-(logs, selections, totals).
-
-When to bubble: handle the event locally if the current component owns
-the state needed to respond. Bubble when the action belongs to an
-ancestor (a list item's "remove" must reach the list that owns the
-items), or when an ancestor may want to react to or record something
-that happened (selection, logging, analytics). Don't bubble events
-with no consumer.
-
-## Send / Receive
-
-`ctx.send(name, args)` delivers a message to a specific target
-component (addressed by path; on its own `ctx.send` targets `this`).
-The target's `receive.<name>(...args, ctx)` handler runs. There is
-**no built-in lifecycle** — `receive.init` is just a convention; the
-host must dispatch it (typically after `app.start()`) for it to run.
-
-```js
-receive: { init(ctx) { ctx.request("loadData"); return this.setIsLoading(true); } }
-```
-
-Dispatch from anywhere:
-
-```js
-app.sendAtRoot("init");                            // host code, top-level
-ctx.at.field("personalSite").send("init");                 // child by field name
-ctx.at.index("items", 3).send("init");                     // list element at index 3
-ctx.at.key("byKey", "k1").send("init");                    // map entry by key
-ctx.at.field("a").field("b").index("xs", 0).send("ping");  // chain freely
-ctx.send("name");                                          // self
-ctx.bubble("name", [arg]);                                 // bubble up
-```
-
-`ctx.at` returns a `PathBuilder` with `.field(name)`, `.index(name, i)`,
-and `.key(name, k)`. Each call appends a step to the path before
-`.send(...)` / `.bubble(...)` fires; the handler runs inside the child
-instance with `this` bound to it. Paths are positional, not references —
-see *Mental model* for why this matters across async boundaries.
-
-When to send: bubble emits an *event* that any ancestor with a
-matching handler can observe; send delivers a *message* to one
-specific target (or to self). Reach for `ctx.at.…send("name")` when
-one component needs to address another by path — e.g. a form telling
-its email field to focus after a failed submit
-(`ctx.at.field("email").send("focus")`), or a list telling item 3 to
-enter edit mode (`ctx.at.index("items", 3).send("startEditing")`).
-Reach for `ctx.send("name")` on self to reuse a handler from multiple
-call sites without duplicating its body — e.g. a "Reload" button and
-`receive.init` both calling `ctx.send("loadData")`. Don't `send` to
-self when a direct method call on the same component would do.
-
-## Async Requests
-
-`ctx.request("name", args)` triggers a host-registered async handler
-and routes the result back to the issuing component's
-`response.<name>(res, err, ctx)`. Use it for fetch / timer / IndexedDB
-work that should land back in component state.
-
-```js
-export function getRequestHandlers() {
-  return {
-    async loadData() {
-      const r = await fetch("https://example.com/data.json");
-      return await r.json();
-    },
-  };
-}
-
-// register at the same scope where you registerComponents
-const scope = app.registerComponents([Comp]);
-scope.registerRequestHandlers(getRequestHandlers());
-```
-
-In a component:
-
-```js
-receive:  { init(ctx) { ctx.request("loadData"); return this.setIsLoading(true); } },
-response: { loadData(res, err, ctx) { return this.setIsLoading(false).setItems(res); } },
-// override response handler names per-call:
-// ctx.request("loadData", [], { onOkName: "loadDataOk", onErrorName: "loadDataErr" });
-```
-
-The `ctx` arg is the last argument of every `response` / `bubble` /
-`receive` handler.
+## Orchestration channels (bubble / send-receive / request-response)
+
+Beyond local `input` handlers, three channels move state between
+components. Full mechanics — when-to-use guidance, the `ctx.at`
+`PathBuilder`, error handling, per-call handler-name overrides, the
+`$unknown` fallback, and request-handler registration — are in
+[request-response.md](./request-response.md). The essentials:
+
+- **`bubble`** — `ctx.bubble("name", args)` walks the dispatch path
+  toward the root; each ancestor with `bubble.<name>(...args, ctx)`
+  runs (after descendants transact); `ctx.stopPropagation()` halts it.
+  Use for aggregate state owned by an ancestor (logs, selections).
+
+  ```js
+  input:  { onClick(ctx) { ctx.bubble("itemSelected", [this]); return this; } },
+  bubble: { itemSelected(item, ctx) { return this.insertInLogAt(0, item.label); } },
+  ```
+
+- **`send` / `receive`** — `ctx.send("name", args)` delivers a message
+  to one target (self by default, or `ctx.at.field("x").send(...)` /
+  `.index(name, i)` / `.key(name, k)` for another); the target's
+  `receive.<name>(...args, ctx)` runs. `receive.init` is a convention,
+  not a lifecycle hook — dispatch it via `app.sendAtRoot("init")`.
+
+- **`request` / `response`** — `ctx.request("name", args)` runs a
+  host-registered async handler (registered with
+  `scope.registerRequestHandlers({...})`) and routes the result to
+  `response.<name>(res, err, ctx)` — `res` set on success, `err` on
+  failure. Use for fetch / timer / IndexedDB work.
+
+  ```js
+  receive:  { init(ctx) { ctx.request("loadData"); return this.setIsLoading(true); } },
+  response: { loadData(res, err, ctx) { return this.setIsLoading(false).setItems(res); } },
+  ```
+
+`ctx` is always the last argument of every `bubble` / `receive` /
+`response` handler.
 
 ## Macros
 

package/skill/tutuca/testing.md

@@ -53,7 +53,12 @@ template/styling tweaks; `tutuca render <module>` covers those.
   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.
+    - `response.<name>(res, err, ctx)` — async result + error. But a
+      handler reached via a request's `onOkName` / `onErrorName`
+      override takes a **single** payload arg, not `(res, err)`:
+      `Comp.response.loadDataOk.call(comp, res)` /
+      `Comp.response.loadDataErr.call(comp, err)`. See
+      [request-response.md](./request-response.md).
     - `alter.<name>(...)` — iteration handlers used by `@when`,
       `@loop-with`, `@enrich-with`. Each kind has its own signature; see
       *Testing iteration handlers* below.
@@ -266,5 +271,7 @@ export function getTests({ describe, test, expect }) {
 
 - [core.md](./core.md) — *Verifying changes*, *Event Handling*,
   *Component Skeleton*.
+- [request-response.md](./request-response.md) — handler signatures for
+  `bubble` / `receive` / `response`, override forms, `$unknown`.
 - [cli.md](./cli.md) — `test` flags, exit codes, output formats,
   `--grep` syntax.

package/skill/tutuca-source/tutuca.ext.js

@@ -1802,16 +1802,16 @@ function parseXOpVal(opName, value, px, parserFn) {
   return val;
 }
 function processXExtras(node, attrs, opName, startIdx, px) {
-  const consumed = X_OP_CONSUMED[opName];
-  const wrappable = X_OP_WRAPPABLE.has(opName);
+  const { consumed, wrappable } = X_OPS[opName];
   const wrappers = [];
   for (let i = startIdx;i < attrs.length; i++) {
     const a = attrs[i];
     const aName = a.name;
     if (consumed.has(aName))
       continue;
-    if (wrappable && X_ATTR_WRAPPERS[aName]) {
-      wrappers.push([X_ATTR_WRAPPERS[aName], vp.parseBool(a.value, px)]);
+    const wrapper = wrappable ? X_OPS[aName]?.wrapper : null;
+    if (wrapper) {
+      wrappers.push([wrapper, vp.parseBool(a.value, px)]);
       continue;
     }
     const issueInfo = { op: opName, name: aName, value: a.value };
@@ -1903,6 +1903,12 @@ class RenderViewId extends ANode {
   }
   setDataAttr(_key, _val) {}
 }
+function dynRenderStep(comp, name, key) {
+  const p = resolveDynProducer(comp, name);
+  if (!p)
+    return null;
+  return key === undefined ? new DynStep(p.producerCompId, p.producerSteps) : new DynEachStep(p.producerCompId, p.producerSteps, key);
+}
 
 class RenderNode extends RenderViewId {
   render(stack, rx) {
@@ -1910,10 +1916,8 @@ class RenderNode extends RenderViewId {
     return rx.renderIt(newStack, this, "", this.viewId);
   }
   toPathStep(ctx) {
-    if (this.val instanceof DynVal) {
-      const p = resolveDynProducer(ctx.comp, this.val.name);
-      return p ? new DynStep(p.producerCompId, p.producerSteps) : null;
-    }
+    if (this.val instanceof DynVal)
+      return dynRenderStep(ctx.comp, this.val.name);
     return super.toPathStep(ctx);
   }
 }
@@ -1929,10 +1933,8 @@ class RenderItNode extends RenderViewId {
       return null;
     const nextNode = next.resolveNode();
     if (nextNode instanceof EachNode && next.hasKey) {
-      if (nextNode.val instanceof DynVal) {
-        const p = resolveDynProducer(ctx.comp, nextNode.val.name);
-        return p ? new DynEachStep(p.producerCompId, p.producerSteps, next.key) : null;
-      }
+      if (nextNode.val instanceof DynVal)
+        return dynRenderStep(ctx.comp, nextNode.val.name, next.key);
       return new EachRenderItStep(nextNode.val.name, next.key);
     }
     return null;
@@ -1948,12 +1950,8 @@ class RenderEachNode extends RenderViewId {
     return rx.renderEach(stack, this.iterInfo, this, this.viewId);
   }
   toPathStep(ctx) {
-    if (this.val instanceof DynVal) {
-      if (!ctx.hasKey)
-        return null;
-      const p = resolveDynProducer(ctx.comp, this.val.name);
-      return p ? new DynEachStep(p.producerCompId, p.producerSteps, ctx.key) : null;
-    }
+    if (this.val instanceof DynVal)
+      return ctx.hasKey ? dynRenderStep(ctx.comp, this.val.name, ctx.key) : null;
     return super.toPathStep(ctx);
   }
   static parse(px, vp2, s, as, attrs) {
@@ -2083,17 +2081,18 @@ class IterInfo {
 }
 var filterAlwaysTrue = (_v, _k, _seq) => true;
 var nullLoopWith = (seq) => ({ iterData: { seq } });
-var X_OP_CONSUMED = {
-  slot: new Set,
-  text: new Set,
-  render: new Set(["as"]),
-  "render-it": new Set(["as"]),
-  "render-each": new Set(["as", "when", "loop-with"]),
-  show: new Set,
-  hide: new Set
+function xOp(consumed = [], { wrappable = false, wrapper = null } = {}) {
+  return { consumed: new Set(consumed), wrappable, wrapper };
+}
+var X_OPS = {
+  slot: xOp(),
+  text: xOp([], { wrappable: true }),
+  render: xOp(["as"], { wrappable: true }),
+  "render-it": xOp(["as"], { wrappable: true }),
+  "render-each": xOp(["as", "when", "loop-with"], { wrappable: true }),
+  show: xOp([], { wrapper: ShowNode }),
+  hide: xOp([], { wrapper: HideNode })
 };
-var X_OP_WRAPPABLE = new Set(["text", "render", "render-it", "render-each"]);
-var X_ATTR_WRAPPERS = { show: ShowNode, hide: HideNode };
 var WRAPPER_NODES = {
   slot: SlotNode,
   show: ShowNode,
@@ -2181,29 +2180,30 @@ var isBlockDomNode = (n) => {
   const node = n instanceof FragmentNode ? n.childs[0] : n;
   return node instanceof DomNode && HTML_BLOCK_TAGS.has(node.tagName);
 };
+var isEmptyText = (c) => c instanceof TextNode && c.val === "";
+function trimEdgeWhite(node) {
+  if (!node.isWhiteSpace?.())
+    return false;
+  node.condenseWhiteSpace();
+  return true;
+}
 function condenseChildsWhites(childs) {
   if (childs.length === 0)
     return childs;
-  let changed = false;
-  if (childs[0].isWhiteSpace?.()) {
-    childs[0].condenseWhiteSpace();
-    changed = true;
-  }
   const last = childs.length - 1;
-  if (last > 0 && childs[last].isWhiteSpace?.()) {
-    childs[last].condenseWhiteSpace();
-    changed = true;
-  }
+  let emptied = trimEdgeWhite(childs[0]);
+  if (last > 0 && trimEdgeWhite(childs[last]))
+    emptied = true;
   for (let i = 1;i < last; i++) {
     const cur = childs[i];
-    if (cur.isWhiteSpace?.() && cur.hasNewLine()) {
-      const bothBlock = isBlockDomNode(childs[i - 1]) && isBlockDomNode(childs[i + 1]);
-      cur.condenseWhiteSpace(bothBlock ? "" : " ");
-      if (bothBlock)
-        changed = true;
-    }
+    if (!(cur.isWhiteSpace?.() && cur.hasNewLine()))
+      continue;
+    const bothBlock = isBlockDomNode(childs[i - 1]) && isBlockDomNode(childs[i + 1]);
+    cur.condenseWhiteSpace(bothBlock ? "" : " ");
+    if (bothBlock)
+      emptied = true;
   }
-  return changed ? childs.filter((c) => !(c instanceof TextNode && c.val === "")) : childs;
+  return emptied ? childs.filter((c) => !isEmptyText(c)) : childs;
 }
 
 class View {