tutuca 0.11.2 → 0.12.0

package/skill/tutuca/iteration.md

@@ -0,0 +1,207 @@
+# Tutuca — List Iteration & Enrichment
+
+Read this file when a view iterates a sequence (`@each`,
+`render-each`), filters (`@when`), enriches items or scopes
+(`@enrich-with`), or paginates (`@loop-with`).
+
+## List Iteration
+
+`@each` accepts: `.field`, `*dynamic`.
+
+```html
+<!-- iterate plain values -->
+<li @each=".items"><span @text="@key"></span>: <x text="@value"></x></li>
+
+<!-- filter -->
+<li @each=".items" @when="filterItem">...</li>
+
+<!-- per-item enrichment via the enrich handler (binds.X => @X in template) -->
+<li @each=".items" @enrich-with="enrichItem">
+  <x text="@count"></x>
+</li>
+
+<!-- shared per-loop data + slicing (computed once before iteration) -->
+<li @each=".items" @loop-with="getIterData" @when="filterItem">...</li>
+
+<!-- render a list of components -->
+<x render-each=".items"></x>
+<x render-each=".items" as="edit"></x>                          <!-- specific view -->
+<x render-each=".items" @when="filterItem"></x>                 <!-- with filter -->
+<x render-each=".items" @loop-with="getIterData" @when="filterItem"></x>
+<x render-each=".items" @show=".isOpen"></x>                    <!-- wrap in show -->
+```
+
+Directives carry the `@` prefix everywhere — on `<li @each>` / `<div @each>`
+host-element loops and on `<x render-each>` alike. Only `as=` is bare, because
+it is an argument to the op rather than a directive. Both forms share the
+handler-name resolution rules below.
+
+`@enrich-with` is **not** supported on `<x render-each>`: the op renders
+each item as a component in its own frame and drops child content, so
+nothing is left to read the `@X` binds an enricher would set. Reach for a
+host-element `@each` loop when you need enrichment.
+
+```js
+alter: {
+  filterItem(_key, item, iterData) { return item.includes(iterData.q); },
+  enrichItem(binds, _key, item, iterData) { binds.count = item.length; },
+  // `@loop-with` is `(seq, ctx)` and returns { iterData?, start?, end?, keys? }.
+  getIterData(seq, ctx) {
+    const start = this.page * this.pageSize;
+    return { iterData: { q: this.query.toLowerCase() }, start, end: start + this.pageSize };
+  },
+}
+```
+
+### `@loop-with` return shape — `iterData` + slicing
+
+A `@loop-with` handler returns an object with up to four optional keys:
+
+- **`iterData`** — the shared per-loop value handed to `@when` /
+  `@enrich-with`. Defaults to `{ seq }` when omitted. Inside the loop a
+  binding may read one **binding member** directly (`@value.title`) — if
+  an enrich handler only copies members of the loop value, the linter
+  hints to drop it and read the members instead.
+- **`start`, `end`** — a positional slice of the iteration, with
+  `Array.prototype.slice` semantics: `end` is exclusive, negatives count
+  from the end (`end: -3` drops the last 3), `undefined` means the
+  natural bound. Use this to **paginate** — skip a prefix and/or suffix
+  without iterating or rendering it.
+- **`keys`** — an explicit, ordered array of **original keys** to visit,
+  for **filter-then-paginate**. The handler filters/sorts/slices the full
+  sequence itself and returns the current page's slice of original keys;
+  the renderer visits exactly those (`seq.get(key)`), in order. Takes
+  precedence over `start`/`end` when both are present.
+
+Slicing is positional but **preserves each item's original key**: a List
+sliced to `start: 2` still binds `@key` to `2, 3, …`, so events, drag,
+and two-way binding keep their identity. With `start`/`end`, `@when` then
+filters *within* the window, so a page may yield fewer than `end - start`
+items — to filter *before* paging (so the page count reflects the filtered
+total), return `keys` instead. `keys` are original keys, so identity is
+preserved there too: editing or deleting a row on page 2 of a filtered view
+hits the right item. A `keys` return is **authoritative** — the renderer
+visits exactly those keys and does **not** re-apply `@when` (the handler has
+already decided what renders).
+
+### `@loop-with` handler context — `(seq, ctx)`
+
+The handler's second argument is `ctx = { lookup, filter }` (an object so it
+can grow):
+
+- **`ctx.lookup(name)`** — reads a scope `@`-binding, e.g. one published by an
+  ancestor scope `@enrich-with`. Lets the handler **reuse a value the enrich
+  already computed** instead of recomputing it.
+- **`ctx.filter(key, value, iterData)`** — wraps the declared `@when` predicate
+  (always callable; a no-op that returns `true` when there is no `@when`). Lets
+  the handler apply the *declared* filter while building its `keys` slice,
+  rather than re-implementing the match test.
+
+### Lifecycle of `@each`
+
+For each render of an element with `@each=".items"`:
+
+1. **Resolve sequence** — evaluate `.items`. Native Arrays and Maps, plus any
+   class declaring a `SEQ_INFO` walker, are recognized.
+2. **`@loop-with`** (once per render) — `getIterData.call(this, seq, ctx)`
+   is called with the full sequence and the `{ lookup, filter }` context;
+   its `iterData` becomes the shared per-loop value and its `start`/`end`
+   slice the iteration. Skipped if no `@loop-with`; then `iterData` is
+   `{ seq }` and the whole sequence is iterated. If it returns `keys`,
+   those exact keys are visited in order (filter-then-paginate) and
+   `start`/`end` are ignored.
+3. For each `(key, value)` pair in the sliced sequence (or each `key` in
+   `keys`):
+   1. **`@when`** — `filterItem.call(this, key, value, iterData)`; if it
+      returns `false`, the item is skipped. **Not applied** when the
+      handler returned `keys` (those are authoritative).
+   2. **`@enrich-with`** — `enrichItem.call(this, binds, key, value, iterData)`.
+      `binds` is a **mutable object** seeded with `{ key, value }`;
+      mutating it (`binds.count = ...`) creates `@`-prefixed bindings
+      available in the templated children. The return value is ignored.
+   3. **Render** the element with the new bindings on the stack.
+
+Auto-bound names inside the loop are always `@key` and `@value` (or
+whatever you wrote into `binds`).
+
+### Handler resolution
+
+`@when` / `@enrich-with` / `@loop-with` resolve like event handler names:
+bare `filterItem` → `alter.filterItem` (idiomatic); `$filterItem` →
+method on `this` (works, not idiomatic — `alter` keeps iteration helpers
+grouped).
+
+## Scope Enrichment
+
+Without an `@each` on the same element, `@enrich-with` becomes a scope
+enricher: it takes no `binds` arg, and its **return value** is the
+bindings object whose keys become `@`-prefixed bindings for descendants.
+
+```js
+alter: { enrichScope() { return { len: this.text.length }; } }
+```
+
+```html
+<div @enrich-with="enrichScope">Length: <x text="@len"></x></div>
+```
+
+## Filter-then-paginate strategies
+
+The recipe form is in
+[patterns/filter-and-paginate.md](./patterns/filter-and-paginate.md).
+There are three ways to wire it, trading simplicity for scans-per-render
+(all return `keys`, so all keep identity):
+
+**1. Naive — two independent scans.** The loop scans + slices the whole
+list itself; a separate `@enrich-with` scans again for the pager labels.
+Simplest, nothing shared:
+
+```js
+naiveTablePage(seq, { filter }) {            // builds the WHOLE matching list…
+  const all = [];
+  for (let i = 0; i < seq.size; i++) if (filter(i, seq.get(i))) all.push(i);
+  const start = clamp(this.page, all.length, this.pageSize).currentPage * this.pageSize;
+  return { keys: all.slice(start, start + this.pageSize) };   // …just to slice it
+},
+```
+
+**2. Shared — one count + one partial collect** (the recipe's default).
+A scope `@enrich-with` on an ancestor does **one** counting scan and
+publishes the clamped page + pager labels (which the page controls,
+sitting outside the loop, read as `@`-bindings); the `@loop-with` handler
+reads the clamped page via `ctx.lookup`, reuses the predicate via
+`ctx.filter`, and collects only the current page's keys — early-exiting
+once the page is full.
+
+**3. Coupled — one scan.** The enrich does *everything*, including the
+page keys, and stashes them in a binding only the loop reads. Fastest,
+but the two handlers are welded together — name them so it shows:
+
+```js
+enrichBuildsKeysForTheLoopBelow() {          // the only scan: count + labels + keys
+  const all = []; /* …collect matching indices… */
+  const { pageCount, currentPage } = clamp(this.page, all.length, this.pageSize);
+  const start = currentPage * this.pageSize;
+  return { __keys__: all.slice(start, start + this.pageSize), /* …labels… */ };
+},
+loopJustForwardsTheEnrichsKeys(_seq, { lookup }) {  // useless without the enrich
+  return { keys: lookup("__keys__") };
+},
+```
+
+Test any strategy with `collectIterBindings(Comp, instance, seq, opts)`,
+which drives a loop exactly like the renderer — map `when` → `@when`,
+`loopWith` → `@loop-with`, `scopeEnrich` → the ancestor scope
+`@enrich-with` the loop reads via `ctx.lookup`. Mechanics and the
+dev-build caveat in [testing.md](./testing.md).
+
+## See also
+
+- [patterns/iterate-a-list.md](./patterns/iterate-a-list.md),
+  [patterns/filter-a-list.md](./patterns/filter-a-list.md),
+  [patterns/paginate-a-list.md](./patterns/paginate-a-list.md),
+  [patterns/enrich-each-item.md](./patterns/enrich-each-item.md) — minimal
+  recipes for each half.
+- [core.md](./core.md) — the component primer, notation, and the
+  frame/scope stack model these directives build on.
+- [advanced.md](./advanced.md) — custom seq types (`SEQ_INFO`).

package/skill/tutuca/macros.md

@@ -0,0 +1,86 @@
+# Tutuca — Macros
+
+Macros are pure template expansion — no state, no methods. Calls inside
+a macro resolve against the *host* component. Read this file when
+authoring `macro({...}, html)` definitions, `<x:name>` calls, or slots.
+
+```js
+import { macro, html } from "tutuca";
+
+const badge = macro(
+  { label: "'New'", kind: "'info'" },     // defaults are *expressions*
+  html`<span :class="$'badge badge-{^kind}'" @text="^label"></span>`,
+);
+
+export function getMacros() {
+  return { badge };
+}
+```
+
+```html
+<x:badge></x:badge>                       <!-- defaults -->
+<x:badge label="Sale"></x:badge>          <!-- static string (no quotes needed) -->
+<x:badge :label="'Sale'"></x:badge>       <!-- dynamic literal -->
+<x:badge :label=".status"></x:badge>      <!-- field reference -->
+```
+
+Inside the macro body, `^param` reads a parameter. Static attributes
+(`label="Sale"`) pass the raw string; dynamic attributes (`:label=…`)
+take the same value forms as any binding — see *Quoting & String
+Literals* in [core.md](./core.md) for the literal-vs-template rules.
+
+Register macros at the same scope as components:
+
+```js
+const scope = app.registerComponents([Comp]);
+scope.registerMacros(getMacros());
+```
+
+Registry keys are lowercased on insert because the HTML parser already
+lowercases `<x:Tag>` to `<x:tag>`. `{ Card }` and `{ card }` both register
+under `card`; registering two *different* macros under the same lowercased
+name warns via `console.assert`.
+
+## Slots
+
+```js
+const card = macro(
+  { title: "'Card'" },
+  html`<div class="card">
+    <h2 @text="^title"></h2>
+    <x:slot></x:slot>
+  </div>`,
+);
+```
+
+```html
+<x:card title="Hi"><p>body</p></x:card>   <!-- default slot -->
+```
+
+## Named Slots
+
+```js
+const panel = macro(
+  {},
+  html`<div>
+    <header><x:slot name="actions"></x:slot></header>
+    <main><x:slot></x:slot></main>                      <!-- default == name="_" -->
+    <footer><x:slot name="footer"></x:slot></footer>
+  </div>`,
+);
+```
+
+```html
+<x:panel>
+  <x slot="actions"><button @on.click="inc">+</button></x>
+  <p>default slot content</p>
+  <x slot="footer">© 2026</x>
+</x:panel>
+```
+
+## See also
+
+- [patterns/reuse-markup-with-macros.md](./patterns/reuse-markup-with-macros.md) —
+  the minimal recipe form of the badge example.
+- [core.md](./core.md) — notation, quoting rules, and the component
+  primer the macro body plugs into.

package/skill/tutuca/margaui.md

@@ -0,0 +1,175 @@
+# 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, [styles.md](./styles.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.
+
+## Dark mode and the other palettes
+
+A margaui theme is a block of CSS custom properties (`--color-*`, `--radius-*`,
+…) under a `[data-theme="<name>"]` selector, and every class it compiles reads
+those through `var(--color-*)`. So switching theme is **one attribute flip on
+`<html>`** — the compiled stylesheet never changes:
+
+```js
+document.documentElement.dataset.theme = "dark";
+```
+
+Two things to know, both of which bite if you assume otherwise:
+
+- **Dark mode never turns itself on.** `dark.css` is keyed on
+  `[data-theme="dark"]` alone — there is no `prefers-color-scheme` fallback and
+  no `.dark` class. Link `theme.css` and do nothing else and the page is light
+  forever, on every machine. Following the OS is your job:
+
+  ```js
+  const dark = matchMedia("(prefers-color-scheme: dark)");
+  document.documentElement.dataset.theme = dark.matches ? "dark" : "light";
+  ```
+
+- **`theme.css` is only light + dark.** It is literally
+  `@import"./light.css";@import"./dark.css";`. margaui ships ~33 more palettes
+  (dracula, nord, cyberpunk, …) as sibling files, each linked separately and
+  each cheap:
+
+  ```html
+  <link rel="stylesheet" href="https://marianoguerra.github.io/margaui/themes/dracula.css" />
+  ```
+
+  Link it **after** `theme.css`: `light.css` claims plain `:root` as well as
+  `[data-theme=light]`, which ties on specificity with `[data-theme=dracula]`,
+  so a palette only wins by coming later in the cascade.
+
+`tutuca storybook` does all of this for you — see the Themes section of
+[storybook.md](./storybook.md).
+
+## 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: assembled class names are invisible to the scanner
+
+The scanner only reads **constant** class literals out of parsed templates. It
+cannot see a class name that is assembled rather than written out verbatim, so
+the margaui CSS for that class is never emitted and it renders unstyled. Two
+cases:
+
+- **Interpolated templates** — `:class="$'bg-{.color}'"` contributes only the
+  constant prefix `bg-`, never `bg-red` / `bg-blue`. Same for any `${…}` segment.
+- **Classes built in a method** — anything a method returns (e.g. a `headerClass()`
+  that builds `` `progress-${this.color}` ``) is never scanned at all; the walker
+  only reads view templates, not JS bodies.
+
+(Literal `@then` / `@else` strings on `@if.class` — e.g.
+`@if.class=".active" @then="'btn-success'" @else="'btn-ghost'"` — **are** now
+collected, so those don't need the workaround.)
+
+Workaround: add a hidden "decoy"/palette view on the component that lists every
+possible assembled class as a real literal, so the walker picks them up:
+
+```js
+// enumerate color × utility so each full class name appears verbatim
+_margauiClasses: html`<p class="bg-red bg-blue progress-red progress-blue"></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.) The cost is that the palette and the methods can drift apart with no
+check catching it; keep them adjacent and update both together.
+
+## See also
+
+- [styles.md](./styles.md) — 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.