tutuca 0.9.94 → 0.9.96

package/package.json

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

package/skill/tutuca/core.md

@@ -586,6 +586,15 @@ The content of `value` depends on the event source:
 For numeric inputs, prefer `valueAsInt` / `valueAsFloat` to skip the
 string parse.
 
+Ask for the most granular arg the handler actually uses — `value` /
+`valueAsInt` / `key`, not the raw `event` — when the specific value is
+all you need. A handler that takes `event` forces every test and
+storybook story to fabricate a DOM-event-shaped object
+(`{ target: { value: … } }`); one that takes `value` is called with a
+plain literal. (Genuine exceptions exist — e.g. a file input needs
+`event` to reach `event.target.files`.) See
+[testing.md](./testing.md) *Designing handlers so tests stay simple*.
+
 ### Event Modifiers
 
 `@on.<event>+<mod>+<mod>=...`

package/skill/tutuca/patterns/coordinate-components.md

@@ -24,3 +24,8 @@ selections); **send/receive** to address one known component
 `scope.registerRequestHandlers({...})`, and `response` gets `(res, err)`. `ctx`
 is always the trailing arg. `receive.init` is a convention, not a lifecycle
 hook — dispatch it with `app.sendAtRoot("init")`.
+
+Carry the most granular payload across the channel, not whole objects you
+won't use — `ctx.bubble("itemSelected", [item.label])` over passing the entire
+component. The handler then receives plain values that are easy to reproduce in
+tests and storybook stories.

package/skill/tutuca/patterns/handle-events.md

@@ -25,3 +25,10 @@ names — `value`, `valueAsInt`/`valueAsFloat`, `event`, `key`, `isAlt`,
 `event.target.value` (or `.checked` for a checkbox, or `event.detail` for a
 `CustomEvent`). Bind events declaratively with `@on.` rather than reaching for
 the node and `addEventListener` — an outside listener bypasses the transactor.
+
+Pass the most granular arg the handler needs — `value`/`valueAsInt`/`key`, not
+the raw `event` — when the specific value is all the handler uses. The args
+become plain literals, so the same call is trivial to reproduce in tests and
+storybook stories (no need to stub a `{ target: { value: … } }` event). Reach
+for `event` only when you truly need it (e.g. a file input reading
+`event.target.files`).

package/skill/tutuca/semantics.md

@@ -56,8 +56,9 @@ The reconstructed path is transformed two ways depending on use:
 
 The DOM is the only thing that survives between render and click, so the
 renderer leaves breadcrumbs: `data-cid` / `data-nid` / `data-eid` on
-elements, and `§…§` comment "metas" adjacent to component boundaries and
-iteration entries. On an event, `Path.fromNodeAndEventName` walks from the
+elements, and `§…§` comment "metas" adjacent to component boundaries,
+iteration entries, and scope boundaries (`@scope` / `@enrich-with`, so
+their custom binds can be replayed). On an event, `Path.fromNodeAndEventName` walks from the
 target up to the root, reads the breadcrumbs, and rebuilds the path. Along
 the way it resolves the handler: normally on the **leaf** component, but
 for bubbling events (and explicit `bubble`) it can resolve on an

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

@@ -47,6 +47,23 @@ class BindStep extends Step {
   }
 }
 
+class ScopeBindStep extends BindStep {
+  constructor(val, binds = {}) {
+    super(binds);
+    this.val = val;
+  }
+  enterFrame(stack, _prev, next) {
+    const dyn = this.val.evalAsHandler(stack)?.call(stack.it) ?? {};
+    return stack.enter(next, { ...this.binds, ...dyn }, false);
+  }
+  withIndex(i) {
+    return new ScopeBindStep(this.val, { ...this.binds, key: i });
+  }
+  withKey(key) {
+    return new ScopeBindStep(this.val, { ...this.binds, key });
+  }
+}
+
 class FieldStep extends Step {
   constructor(field) {
     super();
@@ -108,9 +125,9 @@ class SeqAccessStep extends Step {
 }
 
 class EachBindStep extends Step {
-  constructor(seqVal, key) {
+  constructor(iterInfo, key) {
     super();
-    this.seqVal = seqVal;
+    this.iterInfo = iterInfo;
     this.key = key;
   }
   lookup(v, _dval) {
@@ -120,8 +137,7 @@ class EachBindStep extends Step {
     return v;
   }
   enterFrame(stack, _prev, next) {
-    const item = this.seqVal.eval(stack)?.get(this.key, null);
-    return stack.enter(next, { key: this.key, value: item }, false);
+    return stack.enter(next, this.iterInfo.enrichBinds(stack, this.key), false);
   }
   toAbstractPathStep() {
     return null;
@@ -1776,6 +1792,9 @@ class Renderer {
   _renderMetadata(info) {
     return new VComment(`§${JSON.stringify(info)}§`);
   }
+  renderScopeMeta(nid, dom) {
+    return new VFragment([this._renderMetadata({ $: "Scope", nid }), dom]);
+  }
 }
 var getSeqInfo = (seq) => isIndexed(seq) ? imIndexedIter : isKeyed(seq) ? imKeyedIter : seq?.[SEQ_INFO] ?? unkIter;
 var normalizeRange = (start, end, size) => {
@@ -2296,10 +2315,11 @@ class SlotNode extends WrapperNode {
 class ScopeNode extends WrapperNode {
   render(stack, rx) {
     const binds = this.val.evalAsHandler(stack)?.call(stack.it) ?? {};
-    return this.node.render(stack.enter(stack.it, binds, false), rx);
+    const dom = this.node.render(stack.enter(stack.it, binds, false), rx);
+    return rx.renderScopeMeta(this.nodeId, dom);
   }
   toPathStep(_ctx) {
-    return new BindStep({});
+    return new ScopeBindStep(this.val);
   }
   wrapNode(node) {
     this.node = node;
@@ -2317,7 +2337,7 @@ class EachNode extends WrapperNode {
     return rx.renderEachWhen(stack, this.iterInfo, this.node, this.nodeId);
   }
   toPathStep(ctx) {
-    return ctx.hasKey ? new EachBindStep(this.val, ctx.key) : null;
+    return ctx.hasKey ? new EachBindStep(this.iterInfo, ctx.key) : null;
   }
   static register = true;
 }
@@ -2336,6 +2356,16 @@ class IterInfo {
     const enricher = this.enrichWithVal?.evalAsHandler(stack) ?? null;
     return { seq, filter, loopWith, enricher };
   }
+  enrichBinds(stack, key) {
+    const { seq, 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);
+      enricher.call(stack.it, binds, key, value, iterData);
+    }
+    return binds;
+  }
 }
 function xOp(consumed = [], { wrappable = false, wrapper = null } = {}) {
   return { consumed: new Set(consumed), wrappable, wrapper };