tutuca 0.9.86 → 0.9.87

package/dist/tutuca-storybook.js

@@ -34,20 +34,36 @@ var Storybook = component({
         return this;
       }
       return this.setSectionId(sectionId).setExampleId(exampleId).setFocusExample(example.value);
+    },
+    setSelectedSectionFilter(value) {
+      if (this.sections.size === 0)
+        return this;
+      const i = this.selectedSectionIndex;
+      const sections = this.sections.map((s, idx) => idx === i ? s.setFilter(value ?? "") : s);
+      return this.setSections(sections);
+    },
+    toUrlState(overrides = {}) {
+      const section = this.sections.get(this.selectedSectionIndex);
+      return {
+        section: section?.id ?? "",
+        example: this.exampleId ?? "",
+        sectionFilter: this.filter ?? "",
+        exampleFilter: section?.filter ?? "",
+        ...overrides
+      };
     }
   },
   input: {
     onApplyFilter(value, ctx) {
-      ctx.request("persistState", [{ key: "sectionFilter", value }]);
+      ctx.request("persistState", [this.toUrlState({ sectionFilter: value }), this, false]);
       return this.setFilter(value);
     },
     onClearFilter(ctx) {
-      ctx.request("persistState", [{ key: "sectionFilter", value: "" }]);
+      ctx.request("persistState", [this.toUrlState({ sectionFilter: "" }), this, false]);
       return this.resetFilter();
     },
     onFocusClose(ctx) {
-      ctx.request("persistState", [{ key: "sectionId", value: "" }]);
-      ctx.request("persistState", [{ key: "exampleId", value: "" }]);
+      ctx.request("persistState", [this.toUrlState({ example: "" }), this, true]);
       return this.setSectionId(null).setExampleId(null).setFocusExample(null);
     }
   },
@@ -59,16 +75,38 @@ var Storybook = component({
   bubble: {
     sectionSelected(section, ctx) {
       ctx.stopPropagation();
-      ctx.request("persistState", [{ key: "section", value: section.id }]);
+      ctx.request("persistState", [
+        this.toUrlState({ section: section.id, exampleFilter: section.filter }),
+        this,
+        true
+      ]);
       return this.selectSectionAtIndex(this.sections.indexOf(section));
     },
     exampleFocusRequested(example, ctx) {
       ctx.stopPropagation();
       const section = this.sections.get(this.selectedSectionIndex);
       const sectionId = section?.id ?? null;
-      ctx.request("persistState", [{ key: "sectionId", value: sectionId }]);
-      ctx.request("persistState", [{ key: "exampleId", value: example.id }]);
+      ctx.request("persistState", [this.toUrlState({ example: example.id }), this, true]);
       return this.setSectionId(sectionId).setExampleId(example.id).setFocusExample(example.value);
+    },
+    exampleFilterChanged(value, ctx) {
+      ctx.stopPropagation();
+      ctx.request("persistState", [this.toUrlState({ exampleFilter: value }), this, false]);
+      return this;
+    }
+  },
+  receive: {
+    init(ctx) {
+      ctx.request("loadState", []);
+      return this;
+    }
+  },
+  response: {
+    loadState(state, err) {
+      if (err || !state)
+        return this;
+      const next = this.selectSectionWithId(state.section).setFilter(state.sectionFilter ?? "").setSelectedSectionFilter(state.exampleFilter ?? "");
+      return state.example ? next.focusExampleByIds(state.section, state.example) : next.setSectionId(null).setExampleId(null).setFocusExample(null);
     }
   },
   view: html`<div>
@@ -115,10 +153,13 @@ var Section = component({
     selected: false
   },
   statics: {
-    fromData({ id, title = "???", description = "", items = [] }) {
-      id ??= slugify(title);
+    fromData(raw) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw) || raw.title == null) {
+        throw new Error(`Section.fromData: expected a section object { title, items }, got ${JSON.stringify(raw)}. ` + `getExamples() must return a section object or an array of section objects.`);
+      }
+      const { id, title, description = "", items = [] } = raw;
       return this.make({
-        id,
+        id: id ?? slugify(title),
         title,
         description,
         items: items.map((v) => Example.Class.fromData(v))
@@ -132,11 +173,11 @@ var Section = component({
   },
   input: {
     onApplyFilter(value, ctx) {
-      ctx.request("persistState", [{ key: "exampleFilter", value }]);
+      ctx.bubble("exampleFilterChanged", [value]);
       return this.setFilter(value);
     },
     onClearFilter(ctx) {
-      ctx.request("persistState", [{ key: "exampleFilter", value: "" }]);
+      ctx.bubble("exampleFilterChanged", [""]);
       return this.resetFilter();
     },
     onListItemClick(ctx) {
@@ -235,7 +276,12 @@ function slugify(str) {
   return String(str).normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function buildStorybook(modules) {
-  const sections = modules.map((m) => Section.Class.fromData(m.getExamples())).sort((a, b) => a.title.localeCompare(b.title));
+  const sections = modules.flatMap((m) => {
+    const raw = m.getExamples?.();
+    if (raw == null)
+      return [];
+    return Array.isArray(raw) ? raw : [raw];
+  }).map((s) => Section.Class.fromData(s)).sort((a, b) => a.title.localeCompare(b.title));
   const components = new Set([Storybook, Section, Example]);
   const macros = {};
   const requestHandlers = {};
@@ -255,18 +301,46 @@ function buildStorybook(modules) {
     requestHandlers
   };
 }
-async function mountStorybook(selector, modules, { compileCss, root } = {}) {
+async function mountStorybook(selector, modules, { compileCss, root, persistUrl = true } = {}) {
   const app = tutuca(selector);
   const built = buildStorybook(modules);
   app.state.set(root ?? built.root);
   const scope = app.registerComponents(built.components);
   scope.registerMacros(built.macros);
   scope.registerRequestHandlers(built.requestHandlers);
+  if (persistUrl) {
+    scope.registerRequestHandlers({ persistState, loadState });
+  }
   if (compileCss) {
     injectCss("tutuca-storybook", await compileCss(app));
   }
   app.start();
+  if (persistUrl) {
+    app.sendAtRoot("init", []);
+    window.addEventListener("popstate", () => app.sendAtRoot("init", []));
+  }
   return app;
+  function persistState(state, instance, push) {
+    if (instance !== app.state.val)
+      return;
+    const url = new URL(window.location.href);
+    for (const [k, v] of Object.entries(state)) {
+      if (v === "" || v == null)
+        url.searchParams.delete(k);
+      else
+        url.searchParams.set(k, String(v));
+    }
+    window.history[push ? "pushState" : "replaceState"](null, "", url);
+  }
+  function loadState() {
+    const p = new URLSearchParams(window.location.search);
+    return {
+      section: p.get("section"),
+      example: p.get("example"),
+      sectionFilter: p.get("sectionFilter") ?? "",
+      exampleFilter: p.get("exampleFilter") ?? ""
+    };
+  }
 }
 function getComponents() {
   return [Storybook, Section, Example];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.86",
+  "version": "0.9.87",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -39,6 +39,7 @@
     "lint-fix": "bunx @biomejs/biome lint --write",
     "fix": "bunx @biomejs/biome check --write",
     "tutuca": "bun tools/tutuca.js",
+    "storybook:examples": "bun scripts/storybook-examples.js",
     "stresstest": "bun scripts/stresstest.js",
     "smoke-test": "bun tools/tutuca.js lint ./test/todo.js && bun tools/tutuca.js render ./test/todo.js && bun tools/tutuca.js test ./test/todo.js && bun tools/tutuca.js lint ./test/json.js && bun tools/tutuca.js render ./test/json.js"
   },

package/skill/tutuca/component-design.md

@@ -28,6 +28,13 @@ Walk these top-down whenever you add or reshape a component:
 
 ## Communication decision ladder
 
+This ladder is about *acting across* a component boundary — reaching up,
+messaging a target, doing async work, or mutating state someone else owns. It is
+**not** about merely *reading* a child's state: an ancestor already holds its
+children as immutable fields and can read them directly in any handler or method
+(`this.items.get(i).done`) — no channel needed. See [core.md](./core.md) "The
+value tree".
+
 Reach for the *narrowest* channel that does the job, and only move further down
 the ladder when the one above can't express it:
 
@@ -72,6 +79,16 @@ A compact worked version of the first four (`method`, `bubble`, `send`/`receive`
   between** (the React "prop drilling" reflex) — let a child render the field it
   needs from its owner. → [patterns/share-state-across-the-tree.md](./patterns/share-state-across-the-tree.md)
 
+- **Do read a child's state directly when an ancestor needs it for an aggregate
+  decision.** A parent holds its children as immutable fields, so a handler or
+  method can read `this.items.get(i).done` straight off — children don't have to
+  `bubble` their state up just to be *read*. **Don't reach for a channel to read
+  downward**; `bubble` / `send` are for reaching *up*, messaging a target, or
+  mutating — not for inspecting state you already own. (And don't reach in to
+  mutate a child around the model — that still goes through the owner returning a
+  new self or `ctx.send`.) → [core.md](./core.md) "The value tree" and
+  [request-response.md](./request-response.md) "When to bubble"
+
 - **Do reach for `provide` / `lookup` (`*name`) last** — only when a deep
   descendant needs a value owned far away and nothing in between should know about
   it. Dynamic bindings couple a consumer to a producer that may not be in scope.

package/skill/tutuca/core.md

@@ -169,6 +169,23 @@ keys its cache on `===` identity, so unchanged subtrees skip work.
 Every value carries a hidden tag back to its component class, so the
 runtime never needs `instanceof` — it asks the value what it is.
 
+Because children are just immutable Records held in fields, **handlers
+and methods are ordinary JS with full read access to nested child
+state** — `this.child.count`, `this.items.get(i).done`,
+`this.byKey.get(k).label`. Reading *down* the tree is direct and needs
+no channel: an ancestor that owns a list already holds every child's
+state and can read it for an aggregate decision. The single-level
+`.field` restriction (no `.foo.bar`) is a **view-template** rule, not a
+JS one — it's why a derivation like `userName() { return this.user.name; }`
+is written as a method (see *Methods as Predicates & Computed Values*).
+Reading is free; **mutating** a child still flows through the model —
+the owner returns a new self (`setInItemsAt`, …) or messages the child
+with `ctx.send`. Don't reach in to mutate around the handler discipline,
+and prefer letting a child own and render its own state — reach down to
+read only when the ancestor genuinely needs it. See
+[component-design.md](./component-design.md) and "When to bubble" in
+[request-response.md](./request-response.md).
+
 **Stack: frames vs scopes.** As the renderer walks the AST it pushes
 `BindFrame`s. A *frame* is a barrier: name lookups (`@x`) stop at it,
 so a child component view sees a clean namespace. A *scope* is

package/skill/tutuca/request-response.md

@@ -56,7 +56,11 @@ 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.
+with no consumer — and don't bubble merely so an ancestor can *read* a
+child's state: the ancestor already holds the child as a field and can
+read it directly in its own handler (`this.items.get(i).done`). Bubble
+when the ancestor must **act on** or **record** the event, not to learn
+state it already owns.
 
 ## Send / Receive