tutuca 0.9.90 → 0.9.92

package/package.json

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

package/skill/tutuca/SKILL.md

@@ -21,7 +21,8 @@ When authoring tutuca code, also load these if available:
   values.
 - **margaui** — the Tailwind v4 / daisyUI-compatible class library.
   Reach for it when the project uses MargaUI / Tailwind class lists in
-  `class=` / `:class=`.
+  `class=` / `:class=`. See [margaui.md](./margaui.md) to set it up in a
+  project and wire it into tutuca.
 
 ## Routing
 
@@ -30,8 +31,10 @@ When authoring tutuca code, also load these if available:
 | Authoring `component({...})`, `html`...`` views, macros, fields, events, lists, styles | [core.md](./core.md)           |
 | Designing components — responsibilities, state ownership, channel choice, do's & don'ts | [component-design.md](./component-design.md) |
 | CLI commands, flags, exit codes, full linter rule list                                         | [cli.md](./cli.md)             |
+| Authoring `*.dev.js` story modules, `getExamples()` sections, per-example request mocking, running `tutuca storybook` | [storybook.md](./storybook.md) |
 | `bubble` / `send`-`receive` / async `request`-`response` channels, `$unknown`, request-handler registration | [request-response.md](./request-response.md) |
-| Drag & drop, dynamic bindings (`*x`), pseudo-`x`, custom seq types, Tailwind/MargaUI | [advanced.md](./advanced.md)   |
+| Drag & drop, dynamic bindings (`*x`), pseudo-`x`, custom seq types | [advanced.md](./advanced.md)   |
+| Setting up MargaUI styling — install (CDN / npm / vendoring), theme CSS, and the `compileClassesToStyleText` wiring | [margaui.md](./margaui.md)     |
 | Runtime semantics — path steps, transaction lifecycle, dyn-var teleporting, async key pinning (`livePath`) | [semantics.md](./semantics.md) |
 | Authoring tests — `getTests` shape, calling methods/input/receive/bubble/response/alter handlers, designing handlers for testability | [testing.md](./testing.md) |
 | Task-oriented recipes — iteration, filtering, conditional content, conditional attributes, dynamic vars, composition, events | [patterns/README.md](./patterns/README.md) |

package/skill/tutuca/advanced.md

@@ -2,9 +2,9 @@
 
 Reach this file only when the task touches drag & drop, context-style
 "dynamic bindings", pseudo-`x` (the `<x>`-stripping workaround inside
-`<select>`/`<table>`/`<tr>`), registering a custom seq type, or
-compiling Tailwind / MargaUI classes. For everything else, `core.md`
-is the right place.
+`<select>`/`<table>`/`<tr>`), or registering a custom seq type. For
+compiling Tailwind / MargaUI classes see [margaui.md](./margaui.md); for
+everything else, `core.md` is the right place.
 
 ## Drag and Drop
 
@@ -190,37 +190,6 @@ whose entries resolve `@key` in event handlers.
 
 ## Tailwind / MargaUI Class Compilation (extra build)
 
-```js
-import { compileClassesToStyleText, injectCss, tutuca } from "tutuca/extra";
-import { compile } from "https://cdn.jsdelivr.net/npm/margaui/+esm";
-
-const app = tutuca("#app");
-app.registerComponents([Comp]);
-const css = await compileClassesToStyleText(app, compile);
-injectCss("myapp", css);
-app.start();
-```
-
-`compileClassesToStyleText` walks every registered component's templates,
-collects the `class=` and `:class=` literals, hands them to a `compile`
-function (any margaui-compatible signature), and returns CSS text. Pair
-with `injectCss(scopeName, css)` to install the result before `start()`.
-
-If a margaui skill is available, load it alongside this one when
-authoring class lists — it lists the available components and their
-canonical class strings, which is what the `compile` step expects.
-
-**Pitfall: `@if.class` payloads are invisible to the scanner.** Classes
-inside `@then` / `@else` (e.g. `@if.class=".active" @then="'btn-success'"
-@else="'btn-ghost'"`) are not literals in `class=` / `:class=`, so
-`compileClassesToStyleText` skips them and the margaui CSS for those
-classes is never emitted — the conditional class renders unstyled.
-Workaround: add a hidden "decoy" view on the component that lists every
-conditional class as a real literal, so the walker picks them up:
-
-```js
-_margauiClasses: html`<p class="btn-success btn-ghost on off"></p>`,
-```
-
-The view does not need to be rendered anywhere — registration is enough
-for the template walker to find it.
+Moved to [margaui.md](./margaui.md) — installing margaui (CDN / npm /
+vendoring), the theme CSS, the `compileClassesToStyleText` + `injectCss`
+wiring, and the `@if.class` decoy-view pitfall.

package/skill/tutuca/cli.md

@@ -217,33 +217,11 @@ version-pinned CDN. All tutuca specifiers resolve to a single runtime, which
 component scope/identity requires. `--out` always pins the CDN so the static
 artifact is portable (host it from the project root so `/*.dev.js` paths resolve).
 
-### The `.dev.js` convention
+### Authoring `.dev.js` story modules
 
-A `*.dev.js` file is a **dev-only module**: it holds stories
-(`getComponents()` + `getExamples()`), tests (`getTests()`), and any other
-development-time helpers for nearby components, and is **never shipped to
-production or the UI**. The `.dev.js` suffix is the contract — your app imports
-its real components directly and never a `.dev.js`, and a production build glob
-can exclude `**/*.dev.js`. Because they follow the full module convention, the
-same files are valid targets for `tutuca test`/`lint`/`render` too.
-
-```js
-// counter.dev.js — lives next to counter.js
-import { component, html } from "tutuca";
-import { Counter } from "./counter.js";
-
-export function getComponents() {
-  return [Counter];
-}
-export function getExamples() {
-  return { title: "Counter", items: [{ title: "Basic", value: Counter.make({}) }] };
-}
-export function getTests({ describe, test, expect }) {
-  describe(Counter, () => {
-    test("starts at zero", () => expect(Counter.make({}).count).toBe(0));
-  });
-}
-```
+The `*.dev.js` convention (a dev-only module holding `getComponents()` +
+`getExamples()` + `getTests()`, never shipped), the example/section shape, and
+per-example request mocking are covered in [storybook.md](./storybook.md).
 
 ## Install skill assets
 

package/skill/tutuca/core.md

@@ -11,8 +11,9 @@ the `tutuca` CLI.
 > `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,
+> `<select>`/`<table>`/`<tr>`, custom seq types): see
+> [advanced.md](./advanced.md). Setting up Tailwind/MargaUI styling: see
+> [margaui.md](./margaui.md). CLI commands, flags,
 > exit codes, and full linter rule list: see [cli.md](./cli.md).
 > Authoring tests — `getTests` shape, calling methods/input/receive/
 > bubble/response/alter handlers, designing for testability: see
@@ -827,6 +828,9 @@ component({
 Tagged templates `html` and `css` are just `String.raw` (editor hinting
 only). Plain strings work too.
 
+For Tailwind / MargaUI utility classes (compiling `class=` literals into
+CSS via the extra build), see [margaui.md](./margaui.md).
+
 ## Triggers and Handlers
 
 Tutuca has four orchestration channels. Each one pairs a trigger with
@@ -1005,12 +1009,31 @@ export function getExamples()         {
   return {
     title: "...",
     description: "...",
-    items: [{ title, description, value, view }],         // value = Comp.make(...)
+    // value = Comp.make(...); requestHandlers (optional) mocks this example's requests
+    items: [{ title, description, value, view, requestHandlers }],
   };
 }
 export function getTests({ describe, test, expect }) { /*...*/ }      // optional — see cli.md
 ```
 
+An example item may carry an optional **`requestHandlers`** map — per-example
+mocks for the request handlers its component triggers, used by the storybook
+only. Each is a plain async function keyed by request name; it overrides the
+module's real `getRequestHandlers()` handler **for that example instance only**,
+so two examples of the same component can show different responses side by side.
+Return a fixture, `throw` to exercise the error path, or never resolve to hold a
+loading state:
+
+```js
+items: [
+  { title: "Loaded", value: Widget.make(),
+    requestHandlers: { async load() { return [{ id: 1, name: "Ada" }]; } } },
+  { title: "Error", value: Widget.make(),
+    requestHandlers: { async load() { throw new Error("boom"); } } },
+  { title: "Default", value: Widget.make() },   // no mock → real handler / 404
+]
+```
+
 Best practice: have `getComponents()` return **every** component the module
 defines — child and helper components included — and give each one at least
 one item in `getExamples()`. A component left out of `getComponents()` is
@@ -1037,8 +1060,9 @@ consumed by the shipped `tutuca/storybook` library (`mountStorybook`,
   `request`-`response` channels, the `ctx.at` `PathBuilder`, `$unknown`, and
   request-handler registration.
 - [advanced.md](./advanced.md) — dynamic bindings (`*x`), pseudo-`@x` for
-  `<select>` / `<table>` / `<tr>`, drag & drop, custom seq types, Tailwind /
-  MargaUI compilation.
+  `<select>` / `<table>` / `<tr>`, drag & drop, custom seq types.
+- [margaui.md](./margaui.md) — setting up MargaUI styling: install
+  (CDN / npm / vendoring), theme CSS, and `compileClassesToStyleText`.
 - [semantics.md](./semantics.md) — runtime semantics: path steps, the
   transaction lifecycle, dyn-var teleporting, and async key pinning
   (`livePath`).

package/skill/tutuca/margaui.md

@@ -0,0 +1,124 @@
+# Tutuca — MargaUI Styling
+
+Reach this file to add **MargaUI** (the Tailwind v4 / daisyUI-compatible
+class library) styling to a tutuca app: get margaui into the project,
+link its theme, and let tutuca's extra build compile the utility classes
+it finds in your views into CSS. If you only need scoped/global component
+CSS, the `## Styles` section in [core.md](./core.md) is enough.
+
+## Get margaui
+
+margaui ships two pieces: a `compile` function (class names → CSS text)
+and a `theme.css` stylesheet. Pick one of three ways to obtain them.
+
+### CDN (no install)
+
+Nothing to install — import from jsDelivr and link the theme. tutuca's
+extra build is on the CDN too:
+
+```html
+<link
+  rel="stylesheet"
+  href="https://marianoguerra.github.io/margaui/themes/theme.css"
+/>
+<script type="module">
+  import { compile } from "https://cdn.jsdelivr.net/npm/margaui/+esm";
+  import {
+    compileClassesToStyleText,
+    injectCss,
+    tutuca,
+  } from "https://cdn.jsdelivr.net/npm/tutuca/dist/tutuca-extra.js/+esm";
+  // …wire it up (see below)
+</script>
+```
+
+See `docs/examples/getting-started-margaui.html` for a complete runnable page.
+
+### npm
+
+Install both as dev dependencies and import via bare specifiers:
+
+```sh
+npm i --save-dev tutuca margaui
+```
+
+```js
+import { compileClassesToStyleText, injectCss, tutuca } from "tutuca/extra";
+import { compile } from "margaui";
+```
+
+Serve or copy the theme from `node_modules/margaui` into your build, or
+keep linking the GitHub Pages `theme.css` shown above.
+
+### Vendoring
+
+Copy a prebuilt `margaui.min.js` and a `theme.css` into the project and
+import from the local path — useful for offline builds or pinning an
+exact version (this repo vendors `docs/deps/margaui.min.js` for exactly
+that reason):
+
+```html
+<link rel="stylesheet" href="./vendor/theme.css" />
+<script type="module">
+  import { compile } from "./vendor/margaui.min.js";
+  // …
+</script>
+```
+
+Trade-off: no runtime network dependency and a frozen version, at the
+cost of updating the vendored files by hand.
+
+## Wire it into tutuca
+
+However you obtained `compile`, the integration is the same: register
+your components, compile the classes their views reference, inject the
+resulting CSS, then start.
+
+```js
+import { compileClassesToStyleText, injectCss, tutuca } from "tutuca/extra";
+import { compile } from "margaui"; // or the CDN / vendored path
+
+const app = tutuca("#app");
+app.registerComponents([Comp]);
+const css = await compileClassesToStyleText(app, compile);
+injectCss("myapp", css);
+app.start();
+```
+
+`compileClassesToStyleText` walks every registered component's templates,
+collects the `class=` and `:class=` literals, hands them to a `compile`
+function (any margaui-compatible signature), and returns CSS text. Pair
+with `injectCss(scopeName, css)` to install the result before `start()`.
+
+When authoring class lists, load the margaui skill alongside this one if
+available (`npx tutuca install-skill --margaui-skill`) — it lists the
+available components and their canonical class strings, which is what the
+`compile` step expects.
+
+## Pitfall: @if.class is invisible to the scanner
+
+Classes inside `@then` / `@else` (e.g.
+`@if.class=".active" @then="'btn-success'" @else="'btn-ghost'"`) are not
+literals in `class=` / `:class=`, so `compileClassesToStyleText` skips
+them and the margaui CSS for those classes is never emitted — the
+conditional class renders unstyled. Workaround: add a hidden "decoy" view
+on the component that lists every conditional class as a real literal, so
+the walker picks them up:
+
+```js
+_margauiClasses: html`<p class="btn-success btn-ghost on off"></p>`,
+```
+
+The view does not need to be rendered anywhere — registration is enough
+for the template walker to find it. (This is the same rule
+[component-design.md](./component-design.md) gives for runtime-assembled
+margaui classes.)
+
+## See also
+
+- [core.md](./core.md) — `## Styles` for scoped/global component CSS.
+- [advanced.md](./advanced.md) — dynamic bindings, drag & drop, custom
+  seq types, and other advanced view features.
+- [cli.md](./cli.md) — `tutuca storybook` wires margaui by default
+  (`--no-margaui` to skip); `install-skill --margaui-skill` installs the
+  margaui skill.

package/skill/tutuca/patterns/README.md

@@ -41,3 +41,7 @@ task.
 ## Component communication
 
 - [Coordinate components](coordinate-components.md) — `bubble`, `send`/`receive`, async `request`/`response`.
+
+## Stories & catalog
+
+- [Add a story for a component](add-a-story.md) — a `*.dev.js` with `getComponents()` + `getExamples()`, optional per-example request mocks.

package/skill/tutuca/patterns/add-a-story.md

@@ -0,0 +1,26 @@
+# Add a story for a component
+
+**Problem:** show a component (and its states) in the storybook.
+
+Create `foo.dev.js` next to `foo.js`:
+
+```js
+import { Foo } from "./foo.js";
+
+export function getComponents() {
+  return [Foo];
+}
+export function getExamples() {
+  return { title: "Foo", items: [
+    { title: "Empty", value: Foo.make({}) },
+    { title: "Loaded", value: Foo.make({ isLoading: true }),
+      requestHandlers: { async load() { return [{ id: 1 }]; } } },
+  ] };
+}
+```
+
+`value` must be a real `Foo.make(...)` instance, not a plain object. Add a
+`requestHandlers` map to an item to mock that example's requests
+(fixture / `throw` / never-resolve) — these are storybook-only. Run
+`tutuca storybook` to view, or `--dry-run --json` to smoke-test. See
+[storybook.md](../storybook.md).

package/skill/tutuca/storybook.md

@@ -0,0 +1,151 @@
+# Storybook
+
+Reach this file when authoring `*.dev.js` story modules or running
+`tutuca storybook` — defining `getExamples()` sections, mocking requests per
+example, or rendering a live component catalog. For the framework primer see
+[core.md](./core.md); for the full CLI flag/exit-code table see
+[cli.md](./cli.md); for the `getTests` shape see [testing.md](./testing.md).
+
+## Mental model
+
+`tutuca storybook [dir]` recursively discovers co-located `*.dev.js` modules,
+mounts them via the shipped `tutuca/storybook` library, and serves an ephemeral
+page — no config, no HTML to write. It is **batteries-included by default**:
+before serving it runs each module's `getTests()` in the terminal, the page
+wires margaui styling, and the browser runs `check(app)`. Each is individually
+disablable with a `--no-*` flag. All tutuca specifiers resolve to **one
+runtime** — component scope and identity require it.
+
+## The `.dev.js` module
+
+A `*.dev.js` file is a **dev-only module**: it holds stories, tests, and
+development-time helpers for nearby components, and is **never shipped to
+production or the UI**. The `.dev.js` suffix is the contract — your app imports
+its real components directly and never a `.dev.js`, and a production build glob
+can exclude `**/*.dev.js`. Because it follows the full module convention, the
+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 |
+| `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) |
+| `getRequestHandlers()` | `{ name: async fn }` | the module's **real** request handlers (optional) |
+| `getRoot()` | `Root.make({...})` | root state when examples need it (optional) |
+
+## Authoring stories (`getExamples`)
+
+Return one section, or an array of sections to group examples under multiple
+headings. A section is `{ title, description?, items: [...] }`:
+
+```js
+import { component, html } from "tutuca";
+import { Counter } from "./counter.js";
+
+export function getComponents() {
+  return [Counter];
+}
+export function getExamples() {
+  return {                                    // one section, or an array of these
+    title: "Counter",
+    description: "A button that counts clicks.", // optional
+    items: [
+      { title: "Basic", description: "starts at zero", value: Counter.make({ count: 0 }) },
+      { title: "Pre-filled", value: Counter.make({ count: 5 }) },
+    ],
+  };
+}
+```
+
+Item fields:
+
+- `title` — required.
+- `description?` — shown under the card title.
+- `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).
+
+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.
+
+## Mocking requests per example
+
+An item's optional `requestHandlers` map holds async functions keyed by request
+name that override the module's real `getRequestHandlers()` handler **for that
+one example instance only** — so two examples of the same component show
+different responses side by side. The three idioms:
+
+```js
+items: [
+  { title: "Loaded", value: Widget.make({ isLoading: true }),
+    requestHandlers: { async load() { return [{ id: 1, name: "Ada" }]; } } },   // fixture
+  { title: "Error", value: Widget.make({ isLoading: true }),
+    requestHandlers: { async load() { throw new Error("boom"); } } },           // error path
+  { title: "Loading", value: Widget.make({ isLoading: true }),
+    requestHandlers: { load() { return new Promise(() => {}); } } },            // never resolves
+  { title: "Default", value: Widget.make() },         // no mock → real handler / "Request not found"
+]
+```
+
+How it resolves: the storybook registers one meta-handler per request name. On
+dispatch it walks the issuing component's path leaf→root to find the nearest
+example carrying a mock for that name (**nearest example wins**), else falls
+back to the module's real handler, else surfaces `Request not found: <name>`.
+This is **storybook-only** — at runtime your real `getRequestHandlers()` apply.
+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.
+
+## Stories as tests (`getTests`)
+
+`getTests` runs through the same machinery as `tutuca test`; the storybook runs
+it in the terminal before serving (skip with `--no-tests`). `describe(Comp, fn)`
+auto-tags the suite by `Comp.name`:
+
+```js
+export function getTests({ describe, test, expect }) {
+  describe(Counter, () => {
+    test("starts at zero", () => expect(Counter.make({}).count).toBe(0));
+  });
+}
+```
+
+See [testing.md](./testing.md) for the full `getTests` shape and how to call
+methods / input / receive / bubble / response / alter handlers.
+
+## Running it
+
+```sh
+tutuca storybook                  # scan + serve the current directory
+tutuca storybook ./packages/ui    # scan + serve another directory
+tutuca storybook --dry-run        # prep + print what would be shown, don't serve (smoke test)
+tutuca storybook --dry-run --json # same, machine-readable for agents
+tutuca storybook --out ./_site    # write a static index.html + bootstrap instead of serving
+tutuca storybook --no-tests       # skip the pre-serve getTests() run
+```
+
+Runtime resolution (convention over configuration): a local
+`node_modules/tutuca` install if present, else the CLI's own `dist`, else the
+version-pinned CDN. `--out` always pins the CDN so the artifact is portable —
+host it from the project root so `/*.dev.js` paths resolve. See [cli.md](./cli.md)
+for the exhaustive flag list and exit codes.
+
+## Footguns
+
+- ⚠️ `value` must be a real instance (`Comp.make(...)`), not a plain object or
+  the class itself — examples need an addressable instance for event dispatch.
+- ⚠️ `requestHandlers` mocks are **storybook-only** and per-instance; don't rely
+  on them in `getTests` or production code.
+- ⚠️ Never import a `.dev.js` from app/production code — the suffix is the
+  ship / no-ship boundary.
+- ⚠️ An example whose component triggers a request with no real handler and no
+  per-example mock surfaces `Request not found: <name>`.
+- ⚠️ Keep one tutuca runtime — mixed specifiers or installs break scope identity.
+
+## Verify
+
+After editing a `*.dev.js`: `tutuca lint <module>.dev.js` →
+`tutuca test <module>.dev.js` → `tutuca storybook --dry-run --json <dir>`
+(smoke-test discovery, counts, and mocked names without serving), then
+`tutuca storybook <dir>` to view it live.