tutuca 0.9.93 → 0.9.95

package/skill/tutuca/storybook.md

@@ -65,6 +65,8 @@ Item fields:
 - `value` — required, the instance to render, usually `Comp.make({...})`.
 - `view?` — selects a pushed named view, rendered via `@push-view` in the card.
 - `requestHandlers?` — per-example request mocks (next section).
+- `on?` — lifecycle hooks; messages sent to `value` as sections are navigated
+  ([Lifecycle hooks](#lifecycle-hooks-on)).
 
 The storybook sorts sections by title and renders a sidebar with a filter, so
 one example item per meaningful state reads as a state matrix.
@@ -97,6 +99,50 @@ See [request-response.md](./request-response.md) for the handler contract (the
 `ctx` is the handler's final argument). `tutuca storybook --dry-run --json`
 lists each example's mocked names.
 
+## Lifecycle hooks (`on`)
+
+An item's optional `on` field declares messages dispatched to the example's
+component (`value`) as the user navigates sections — for examples that need to be
+"kicked" into a state (load data, open a panel, focus an input) rather than
+constructed in it. Three phases:
+
+- **`init`** — the first time a section is displayed, sent to each of its examples.
+- **`resume`** — each subsequent time that section is re-displayed.
+- **`suspend`** — when a section is navigated away from.
+
+```js
+items: [
+  { title: "Loaded", value: Grid.make({}),
+    on: {
+      init:    { request: [{ name: "load", args: [] }] },     // fetch on first show
+      resume:  { send:    [{ name: "refresh", args: [] }] },  // re-poll on return
+      suspend: { send:    [{ name: "pause", args: [] }] },    // stop work when hidden
+    } },
+]
+```
+
+Each phase holds **action buckets** — `send` (→ a `receive` handler), `bubble`,
+`request` (→ a `response` handler), `input` — each an array of
+`{ name, args?, opts? }`. `args` is a plain array, or a **function** `(self) =>
+[...]` called with the example's component instance:
+
+```js
+on: { init: { send: [{ name: "select", args: (self) => [self.firstId()] }] } }
+```
+
+For ordering **across** kinds, use `do` — an explicit sequence where each item
+carries its own `type`:
+
+```js
+on: { init: { do: [
+  { type: "send",    name: "reset", args: [] },
+  { type: "request", name: "load",  args: [] },   // runs after reset
+] } }
+```
+
+`request` actions honor the example's `requestHandlers` mocks. A phase message
+with no matching handler on the component is a silent no-op.
+
 ## Stories as tests (`getTests`)
 
 `getTests` runs through the same machinery as `tutuca test`; the storybook runs

package/skill/tutuca/testing.md

@@ -90,6 +90,39 @@ Comp.input.handlerName.call(comp, arg1, arg2, /* … */);
   it does.
 - Returned value is the next instance.
 
+## Driving a full cascade (`drive`)
+
+Direct `.call(comp, ...)` tests one handler in isolation. When you need a message
+to fan out through real dispatch — a `request` that resolves and feeds its
+`response`, a `send` that triggers more sends — `getTests` also injects an async
+`drive` helper (alongside `describe`, `test`, `expect`):
+
+```js
+export function getTests({ describe, test, expect, drive }) {
+  describe(Grid, () => {
+    test("init loads rows", async () => {
+      const settled = await drive(
+        Grid.make({ rows: [] }),
+        { request: [{ name: "load", args: [] }] }, // an `on`-phase config
+      );
+      expect(settled.rows.size).toBe(3);
+    });
+  });
+}
+```
+
+- `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.
+- `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) => [...]`.
+- `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
+  around its commit — handy for asserting the message/state trace.
+
 ## Testing iteration handlers
 
 `alter` handlers run inside `@each` / `@when` / `@loop-with` /

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

@@ -2920,36 +2920,81 @@ class Transactor {
     this.transactions = [];
     this.state = new State(rootValue);
     this.onTransactionPushed = () => {};
+    this._inflight = new Set;
   }
   pushTransaction(t) {
     this.transactions.push(t);
     this.onTransactionPushed(t);
   }
+  _link(child, parent) {
+    if (parent) {
+      const release = parent.completion.track();
+      child.completion.whenSubtreeSettled().then(release);
+    }
+    return child;
+  }
   pushSend(path, name, args = [], opts = {}, parent = null) {
-    this.pushTransaction(new SendEvent(path, this, name, args, parent, opts));
+    const t = new SendEvent(path, this, name, args, parent, opts);
+    this.pushTransaction(t);
+    return this._link(t, parent);
+  }
+  pushInput(path, name, args = [], opts = {}, parent = null) {
+    const t = new InputDispatchEvent(path, this, name, args, parent, opts);
+    this.pushTransaction(t);
+    return this._link(t, parent);
   }
   pushBubble(path, name, args = [], opts = {}, parent = null, targetPath = null) {
     const newOpts = opts.skipSelf ? { ...opts, skipSelf: false } : opts;
-    this.pushTransaction(new BubbleEvent(path, this, name, args, parent, newOpts, targetPath));
+    const t = new BubbleEvent(path, this, name, args, parent, newOpts, targetPath);
+    this.pushTransaction(t);
+    return this._link(t, parent);
+  }
+  pushRequest(path, name, args = [], opts = {}, parent = null) {
+    const release = parent ? parent.completion.track() : null;
+    const p = this._runRequest(path, name, args, opts, parent, release);
+    this._inflight.add(p);
+    p.finally(() => this._inflight.delete(p));
+    return p;
+  }
+  async settle(maxTurns = 1e4) {
+    while ((this.hasPendingTransactions || this._inflight.size) && maxTurns-- > 0) {
+      while (this.hasPendingTransactions)
+        this.transactNext();
+      if (this._inflight.size)
+        await Promise.allSettled([...this._inflight]);
+    }
   }
-  async pushRequest(path, name, args = [], opts = {}, parent = null) {
-    const curRoot = this.state.val;
-    const txnPath = path.toTransactionPath();
-    const curLeaf = txnPath.lookup(curRoot);
-    const handler = this.comps.getRequestFor(curLeaf, name) ?? mkReq404(name);
-    const reqCtx = new RequestContext(path, this, parent, curRoot);
-    const resHandlerName = opts?.onResName ?? name;
-    const resPath = opts?.livePath ? null : txnPath.pinKeys(curRoot);
-    const push = (specificName, baseName, singleArg, result, error) => {
-      const resArgs = specificName ? [singleArg] : [result, error];
-      const t = new ResponseEvent(path, this, specificName ?? baseName, resArgs, parent, resPath);
-      this.pushTransaction(t);
+  async _runRequest(path, name, args = [], opts = {}, parent = null, release = null) {
+    let released = false;
+    const transfer = (t) => {
+      if (release) {
+        released = true;
+        t.completion.whenSubtreeSettled().then(release);
+      }
     };
     try {
-      const result = await handler.fn.apply(null, [...args, reqCtx]);
-      push(opts?.onOkName, resHandlerName, result, result, null);
-    } catch (error) {
-      push(opts?.onErrorName, resHandlerName, error, null, error);
+      const curRoot = this.state.val;
+      const txnPath = path.toTransactionPath();
+      const curLeaf = txnPath.lookup(curRoot);
+      const handler = this.comps.getRequestFor(curLeaf, name) ?? mkReq404(name);
+      const reqCtx = new RequestContext(path, this, parent, curRoot);
+      const resHandlerName = opts?.onResName ?? name;
+      const resPath = opts?.livePath ? null : txnPath.pinKeys(curRoot);
+      const push = (specificName, baseName, singleArg, result, error) => {
+        const resArgs = specificName ? [singleArg] : [result, error];
+        const t = new ResponseEvent(path, this, specificName ?? baseName, resArgs, parent, resPath);
+        transfer(t);
+        this.pushTransaction(t);
+      };
+      try {
+        const result = await handler.fn.apply(null, [...args, reqCtx]);
+        push(opts?.onOkName, resHandlerName, result, result, null);
+      } catch (error) {
+        push(opts?.onErrorName, resHandlerName, error, null, error);
+      }
+    } finally {
+      if (release && !released)
+        release();
     }
   }
   get hasPendingTransactions() {
@@ -2960,13 +3005,18 @@ class Transactor {
       this.transact(this.transactions.shift());
   }
   transact(transaction) {
-    const curState = this.state.val;
-    const newState = transaction.run(curState, this.comps);
-    if (newState !== undefined) {
-      this.state.set(newState, { transaction });
-      transaction.afterTransaction();
-    } else
-      console.warn("undefined new state", { curState, transaction });
+    try {
+      const curState = this.state.val;
+      const newState = transaction.run(curState, this.comps);
+      if (newState !== undefined) {
+        this.state.set(newState, { transaction });
+        transaction.afterTransaction();
+      } else
+        console.warn("undefined new state", { curState, transaction });
+    } finally {
+      transaction._completion?.ensureSelfSettled();
+      transaction._completion?.releaseSelf();
+    }
   }
   transactInputNow(path, event, eventHandler, dragInfo) {
     this.transact(new InputEvent(path, event, eventHandler, this, dragInfo));
@@ -2987,18 +3037,17 @@ class Transaction {
     this.path = path;
     this.transactor = transactor;
     this.parentTransaction = parentTransaction;
-    this._task = null;
+    this._completion = null;
   }
-  get task() {
-    this._task ??= new Task;
-    return this._task;
+  get completion() {
+    this._completion ??= new Completion;
+    return this._completion;
   }
-  getCompletionPromise() {
-    return this.task.promise;
+  whenSettled() {
+    return this.completion.whenSettled();
   }
-  setParent(parentTransaction) {
-    this.parentTransaction = parentTransaction;
-    parentTransaction.task.addDep(this.task);
+  whenSubtreeSettled() {
+    return this.completion.whenSubtreeSettled();
   }
   run(rootValue, comps) {
     return this.updateRootValue(rootValue, comps);
@@ -3024,7 +3073,7 @@ class Transaction {
     const txnPath = this.getTransactionPath();
     const curLeaf = txnPath.lookup(curRoot);
     const newLeaf = this.callHandler(curRoot, curLeaf, comps);
-    this._task?.complete?.({ value: newLeaf, old: curLeaf });
+    this._completion?.markSelfSettled({ value: newLeaf, old: curLeaf });
     return curLeaf !== newLeaf ? txnPath.setValue(curRoot, newLeaf) : curRoot;
   }
   lookupName(_name) {
@@ -3161,29 +3210,69 @@ class BubbleEvent extends SendEvent {
   }
 }
 
-class Task {
+class InputDispatchEvent extends NameArgsTransaction {
+  handlerProp = "input";
+}
+
+class Completion {
   constructor() {
-    this.deps = [];
-    this.val = this.resolve = this.reject = null;
-    this.promise = new Promise((res, rej) => {
-      this.resolve = res;
-      this.reject = rej;
+    this.val = undefined;
+    this.selfSettled = false;
+    this.subtreeSettled = false;
+    this.pending = 1;
+    this._selfResolve = null;
+    this._selfPromise = null;
+    this._subtreeResolve = null;
+    this._subtreePromise = null;
+    this._selfReleased = false;
+  }
+  whenSettled() {
+    if (this.selfSettled)
+      return Promise.resolve(this.val);
+    this._selfPromise ??= new Promise((res) => {
+      this._selfResolve = res;
     });
-    this.isCompleted = false;
+    return this._selfPromise;
   }
-  addDep(task) {
-    console.assert(!this.isCompleted, "addDep for completed task", this, task);
-    this.deps.push(task);
-    task.promise.then((_) => this._check());
+  whenSubtreeSettled() {
+    if (this.subtreeSettled)
+      return Promise.resolve(this.val);
+    this._subtreePromise ??= new Promise((res) => {
+      this._subtreeResolve = res;
+    });
+    return this._subtreePromise;
   }
-  complete(val) {
+  markSelfSettled(val) {
+    if (this.selfSettled)
+      return;
+    this.selfSettled = true;
     this.val = val;
-    this._check();
+    this._selfResolve?.(val);
+  }
+  ensureSelfSettled() {
+    if (!this.selfSettled)
+      this.markSelfSettled(this.val);
   }
-  _check() {
-    if (this.deps.every((task) => task.isCompleted)) {
-      this.isCompleted = true;
-      this.resolve(this);
+  track() {
+    this.pending++;
+    let done = false;
+    return () => {
+      if (done)
+        return;
+      done = true;
+      this._release();
+    };
+  }
+  releaseSelf() {
+    if (this._selfReleased)
+      return;
+    this._selfReleased = true;
+    this._release();
+  }
+  _release() {
+    if (--this.pending === 0) {
+      this.subtreeSettled = true;
+      this._subtreeResolve?.(this.val);
     }
   }
 }
@@ -3222,6 +3311,9 @@ class Dispatcher {
   requestAtPath(path, name, args, opts) {
     return this.transactor.pushRequest(path, name, args, opts, this.parent);
   }
+  inputAtPath(path, name, args, opts) {
+    return this.transactor.pushInput(path, name, args, opts, this.parent);
+  }
   lookupTypeFor(name, inst) {
     return this.transactor.comps.getCompFor(inst).scope.lookupComponent(name);
   }
@@ -3576,6 +3668,45 @@ import {
   version
 } from "immutable";
 
+// src/on.js
+var OP_KINDS = ["send", "bubble", "request", "input"];
+function phaseOps(phase) {
+  const ops = [];
+  for (const type of OP_KINDS)
+    for (const a of phase[type] ?? [])
+      ops.push({ type, ...a });
+  for (const a of phase.do ?? [])
+    ops.push(a);
+  return ops;
+}
+function resolveArgs(args, self) {
+  return typeof args === "function" ? args(self) ?? [] : args ?? [];
+}
+function dispatchPhase(dispatcher, targetPath, phase, self) {
+  if (!phase)
+    return;
+  for (const op of phaseOps(phase)) {
+    const args = resolveArgs(op.args, self);
+    switch (op.type) {
+      case "send":
+        dispatcher.sendAtPath(targetPath, op.name, args, op.opts);
+        break;
+      case "bubble":
+        dispatcher.sendAtPath(targetPath, op.name, args, {
+          skipSelf: true,
+          bubbles: true,
+          ...op.opts
+        });
+        break;
+      case "request":
+        dispatcher.requestAtPath(targetPath, op.name, args, op.opts);
+        break;
+      case "input":
+        dispatcher.inputAtPath(targetPath, op.name, args, op.opts);
+        break;
+    }
+  }
+}
 // src/oo.js
 import { Map as IMap, Set as ISet, List, OrderedMap, Record } from "immutable";
 var BAD_VALUE = Symbol("BadValue");
@@ -3989,8 +4120,10 @@ export {
   test,
   setIn,
   set,
+  resolveArgs,
   removeIn,
   remove,
+  phaseOps,
   mergeWith,
   mergeDeepWith,
   mergeDeep,
@@ -4023,6 +4156,7 @@ export {
   getIn,
   get,
   fromJS,
+  dispatchPhase,
   css,
   component,
   collectIterBindings,