tutuca 0.9.97 → 0.9.99

package/skill/tutuca/semantics.md

@@ -83,9 +83,10 @@ return curLeaf !== newLeaf ? txnPath.setValue(curRoot, newLeaf) : curRoot;
 ```
 
 The root swap is atomic and identity-cheap: unchanged subtrees keep their
-references, so re-render is incremental. Cross-transaction ordering and
-fan-out completion are tracked by `Task` (a transaction's `task` resolves
-once its dependency tasks do).
+references, so re-render is incremental. Per-dispatch completion is tracked
+by `Completion` (counter-based): `whenSettled()` resolves once a
+transaction's own work finishes, `whenSubtreeSettled()` once the subtree it
+spawned (requests, follow-on sends) settles too.
 
 ## Dispatch channels, semantically
 

package/skill/tutuca/storybook.md

@@ -27,7 +27,7 @@ same file is a valid target for `tutuca lint` / `test` / `render` too.
 
 | Export | Returns | Used for |
 | ------ | ------- | -------- |
-| `getComponents()` | `[Comp, ...]` | stories — return **every** component the module defines, children and helpers included |
+| `getComponents()` | `[Comp, ...]` | stories — return **every** component the module defines, children and helpers included. Components dedup by identity, so re-listing a leaf that another module also lists is safe (a composition module can re-list every leaf it uses). |
 | `getExamples()` | one section, or an array of sections | the catalog cards |
 | `getTests({ describe, test, expect })` | tests | the pre-serve test run (optional) |
 | `getMacros()` | `{ name: macro }` | macros referenced in views (optional) |
@@ -37,7 +37,12 @@ same file is a valid target for `tutuca lint` / `test` / `render` too.
 ## Authoring stories (`getExamples`)
 
 Return one section, or an array of sections to group examples under multiple
-headings. A section is `{ title, description?, items: [...] }`:
+headings. A section is `{ title, description?, items: [...] }`. An array of one
+section behaves exactly like returning that section directly — both go through
+the same `Section.fromData`, which **throws** on a malformed section (missing
+`title`, not an object) rather than rendering a placeholder title. (If you saw
+broken titles from a one-element array in an older build, that predates array
+support — it has shipped since well before 0.9.88.)
 
 ```js
 import { component, html } from "tutuca";

package/skill/tutuca/testing.md

@@ -114,10 +114,21 @@ export function getTests({ describe, test, expect, drive }) {
 - `drive(value, phase, opts?)` builds a transactor over `value`, dispatches the
   phase's actions at the root, awaits the whole cascade (including async
   requests), and returns the **settled** instance.
+- `drive` **always originates at the root** — there is no `at:`/path option. To
+  exercise a handler on a nested child, call it directly with `.call(child, …)`.
 - `phase` is the same shape as an example's `on.init`
   (`{ send, bubble, request, input, do }`; see
   [storybook.md](./storybook.md#lifecycle-hooks-on)). `args` may be a function
   `(self) => [...]`.
+- A `bubble` action is a **no-op under `drive`**: bubbles travel child→parent, and
+  at the root there is no ancestor to receive it (the root's own `bubble` handler
+  is skipped too). To test a `bubble` handler, call it directly. (`drive` warns
+  when a phase contains a `bubble`.)
+- These are *action kinds*, not methods. `$`-prefixed **methods** (auto setters/
+  togglers, `$foo`) are not an action kind — `on`/`drive` can only reach state
+  through `input`/`receive`/`response` handlers. To put a component into a method-
+  driven state for a test, call the method directly or route it through an `input`
+  handler.
 - `request` actions resolve against the module's `getRequestHandlers()`.
 - `opts.onMessage(message, before, after)` observes every committed transaction —
   `message` is `{ kind, name, args, path }`, `before`/`after` are the root values
@@ -258,12 +269,9 @@ 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.
+The built-in named args are listed in [core.md](./core.md) *Event
+Handling*; `ctx` is auto-appended last. Reach for `event` only when no
+narrower arg fits.
 
 ## Worked example
 

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

@@ -1744,37 +1744,47 @@ class Renderer {
   renderEach(stack, iterInfo, node, viewName) {
     const { seq, filter, loopWith } = iterInfo.eval(stack);
     const r = [];
-    const { iterData, start, end } = unpackLoopResult(loopWith.call(stack.it, seq), seq);
-    getSeqInfo(seq)(seq, (key, value, attrName) => {
-      if (filter.call(stack.it, key, value, iterData)) {
-        const dom = this.renderIt(stack.enter(value, { key }, true), node, key, viewName);
-        this.pushEachEntry(r, node.nodeId, attrName, key, dom);
-      }
-    }, start, end);
+    const { iterData, start, end, keys } = unpackLoopResult(loopWith.call(stack.it, seq, makeLoopCtx(stack, filter)), seq);
+    const renderOne = (key, value, attrName) => {
+      const dom = this.renderIt(stack.enter(value, { key }, true), node, key, viewName);
+      this.pushEachEntry(r, node.nodeId, attrName, key, dom);
+    };
+    if (keys)
+      imKeysIter(seq, renderOne, keys);
+    else
+      getSeqInfo(seq)(seq, (key, value, attrName) => {
+        if (filter.call(stack.it, key, value, iterData))
+          renderOne(key, value, attrName);
+      }, start, end);
     return r;
   }
   renderEachWhen(stack, iterInfo, view, nid) {
     const { seq, filter, loopWith, enricher } = iterInfo.eval(stack);
     const r = [];
     const it = stack.it;
-    const { iterData, start, end } = unpackLoopResult(loopWith.call(it, seq), seq);
-    getSeqInfo(seq)(seq, (key, value, attrName) => {
-      if (filter.call(it, key, value, iterData)) {
-        const cachePath = enricher ? [view, it, value] : [view, value];
-        const binds = { key, value };
-        const cacheKey = `${nid}-${key}`;
-        if (enricher)
-          enricher.call(it, binds, key, value, iterData);
-        const cachedNode = this.cache.get(cachePath, cacheKey);
-        if (cachedNode)
-          this.pushEachEntry(r, nid, attrName, key, cachedNode);
-        else {
-          const dom = this.renderView(view, stack.enter(value, binds, false));
-          this.pushEachEntry(r, nid, attrName, key, dom);
-          this.cache.set(cachePath, cacheKey, dom);
-        }
+    const { iterData, start, end, keys } = unpackLoopResult(loopWith.call(it, seq, makeLoopCtx(stack, filter)), seq);
+    const renderOne = (key, value, attrName) => {
+      const cachePath = enricher ? [view, it, value] : [view, value];
+      const binds = { key, value };
+      const cacheKey = `${nid}-${key}`;
+      if (enricher)
+        enricher.call(it, binds, key, value, iterData);
+      const cachedNode = this.cache.get(cachePath, cacheKey);
+      if (cachedNode)
+        this.pushEachEntry(r, nid, attrName, key, cachedNode);
+      else {
+        const dom = this.renderView(view, stack.enter(value, binds, false));
+        this.pushEachEntry(r, nid, attrName, key, dom);
+        this.cache.set(cachePath, cacheKey, dom);
       }
-    }, start, end);
+    };
+    if (keys)
+      imKeysIter(seq, renderOne, keys);
+    else
+      getSeqInfo(seq)(seq, (key, value, attrName) => {
+        if (filter.call(it, key, value, iterData))
+          renderOne(key, value, attrName);
+      }, start, end);
     return r;
   }
   renderView(view, stack) {
@@ -1810,8 +1820,17 @@ var filterAlwaysTrue = (_v, _k, _seq) => true;
 var nullLoopWith = (seq) => ({ iterData: { seq } });
 var unpackLoopResult = (result, seq) => {
   const r = result ?? {};
-  return { iterData: r.iterData ?? { seq }, start: r.start, end: r.end };
+  return { iterData: r.iterData ?? { seq }, start: r.start, end: r.end, keys: r.keys };
+};
+var imKeysIter = (seq, visit, keys) => {
+  const attrName = isIndexed(seq) ? "si" : "sk";
+  for (const key of keys)
+    visit(key, seq.get(key), attrName);
 };
+var makeLoopCtx = (stack, filter) => ({
+  lookup: (name) => stack.lookupBind(name),
+  filter: (key, value, iterData) => filter.call(stack.it, key, value, iterData)
+});
 var imIndexedIter = (seq, visit, start, end) => {
   const [s, e] = normalizeRange(start, end, seq.size);
   for (let i = s;i < e; i++)
@@ -2359,11 +2378,11 @@ class IterInfo {
     return { seq, filter, loopWith, enricher };
   }
   enrichBinds(stack, key) {
-    const { seq, loopWith, enricher } = this.eval(stack);
+    const { seq, filter, loopWith, enricher } = this.eval(stack);
     const value = seq?.get ? seq.get(key, null) : null;
     const binds = { key, value };
     if (enricher) {
-      const { iterData } = unpackLoopResult(loopWith.call(stack.it, seq), seq);
+      const { iterData } = unpackLoopResult(loopWith.call(stack.it, seq, makeLoopCtx(stack, filter)), seq);
       enricher.call(stack.it, binds, key, value, iterData);
     }
     return binds;
@@ -3714,6 +3733,13 @@ function phaseOps(phase) {
 function resolveArgs(args, self) {
   return typeof args === "function" ? args(self) ?? [] : args ?? [];
 }
+function phaseHasBubble(phase) {
+  if (!phase)
+    return false;
+  if (phase.bubble?.length)
+    return true;
+  return (phase.do ?? []).some((op) => op.type === "bubble");
+}
 function dispatchPhase(dispatcher, targetPath, phase, self) {
   if (!phase)
     return;
@@ -4007,7 +4033,8 @@ class FieldSet extends Field {
 }
 function mkCompField(field, scope, args) {
   const Comp = scope?.lookupComponent(field.type) ?? null;
-  console.assert(!scope || Comp !== null, "component not found", { field });
+  if (Comp === null)
+    console.warn(scope ? `component field "${field.name}": component "${field.type}" not found in scope` : `component field "${field.name}": cannot resolve component "${field.type}" — built without a registered scope (use ${field.type}.make({}) as the default, or build via a registered component)`);
   return Comp?.make({ ...field.args, ...args }, { scope }) ?? null;
 }
 
@@ -4156,6 +4183,7 @@ export {
   removeIn,
   remove,
   phaseOps,
+  phaseHasBubble,
   mergeWith,
   mergeDeepWith,
   mergeDeep,