tutuca 0.9.79 → 0.9.80

package/README.md

@@ -168,7 +168,7 @@ npx tutuca install-skill --dot-agents
 npx tutuca install-skill --force
 ```
 
-The skill content is generated from `docs/llm/`, so the same reference
+The skill content is generated from `docs/skill/`, so the same reference
 runs locally (`tutuca lint <module>` + `tutuca render <module> --title …`)
 and inside Claude.
 

package/package.json

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

package/skill/tutuca/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: tutuca
-description: Use when authoring or reviewing tutuca modules — `component({...})` definitions, `html\`...\`` views, `@`-directives, `input` / `bubble` / `receive` / `response` / `alter` handlers, macros, or `getTests` exports — or when running the `tutuca` CLI (`lint` / `test` / `render` / `docs`). Covers the post-edit `tutuca <module> lint` → `test` → `render --title "<example>"` verification recipe.
+description: Use when authoring or reviewing tutuca modules — `component({...})` definitions, `html`...`` views, `@`-directives, `input` / `bubble` / `receive` / `response` / `alter` handlers, macros, or `getTests` exports — or when running the `tutuca` CLI (`lint` / `test` / `render` / `docs`). Covers the post-edit `tutuca <module> lint` → `test` → `render --title "<example>"` verification recipe.
 ---
 
-<!-- This file is generated by scripts/build-skill.js from docs/llm/. Do not edit. -->
+<!-- Source of truth: docs/skill/. The skill/tutuca/ copy is generated by scripts/build-skill.js — edit docs/skill/, not skill/. -->
 
 # Tutuca
 
@@ -27,12 +27,13 @@ When authoring tutuca code, also load these if available:
 
 | Task                                                                                           | File                            |
 | ---------------------------------------------------------------------------------------------- | ------------------------------- |
-| Authoring `component({...})`, `html\`...\`` views, macros, fields, events, lists, styles | [core.md](./core.md)           |
+| Authoring `component({...})`, `html`...`` views, macros, fields, events, lists, styles | [core.md](./core.md)           |
 | CLI commands, flags, exit codes, full linter rule list                                         | [cli.md](./cli.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)   |
 | 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) |
 
 Read `core.md` first. Reach for the others only when the task touches
 them — each is referenced inline from `core.md` so you'll be pointed

package/skill/tutuca/core.md

@@ -19,7 +19,9 @@ the `tutuca` CLI.
 > [testing.md](./testing.md). Runtime semantics — path steps, the
 > transaction lifecycle, dyn-var teleporting, and async key pinning
 > (`livePath`): see [semantics.md](./semantics.md). Read those only when
-> the task touches them.
+> the task touches them. Task-oriented "how do I do X" recipes (iteration,
+> filtering, slicing, conditional content, conditional attributes, dynamic
+> vars, composition, events, …): see [patterns/README.md](./patterns/README.md).
 
 ## Verifying changes
 
@@ -987,3 +989,6 @@ export function getTests({ describe, test, expect }) { /*...*/ }      // optiona
   convention for tests.
 - [cli.md](./cli.md) — commands, flags, exit codes, and the full linter rule
   list.
+- [patterns/README.md](./patterns/README.md) — task-oriented recipes ("how do I
+  iterate / filter / paginate / show-hide / build tabs / share state / …"),
+  each linking back here and to a runnable example.

package/skill/tutuca/patterns/README.md

@@ -0,0 +1,42 @@
+# Tutuca Patterns
+
+Task-oriented recipes: "how do I do X" with a minimal working snippet and the
+one pitfall worth knowing. Each recipe is self-contained and brief; for the
+full directive *semantics* behind a pattern, see [core.md](../core.md) and its
+spokes.
+
+New to Tutuca? Read [core.md](../core.md) first, then reach here for a specific
+task.
+
+## Iteration & lists
+
+- [Iterate a list](iterate-a-list.md) — render one element per item with `@each` / `render-each`.
+- [Filter a list](filter-a-list.md) — keep only matching items with `@when`.
+- [Enrich each item](enrich-each-item.md) — expose derived per-item values as `@`-bindings.
+- [Paginate a list](paginate-a-list.md) — slice the iteration with `@loop-with` `start`/`end`.
+
+## Conditional content & attributes
+
+- [Show or hide content](show-or-hide-content.md) — `@show` / `@hide` and the boolean predicates.
+- [Switch between views](switch-between-views.md) — pick a component's own view with `as=` or `@push-view`.
+- [Conditional attribute value](conditional-attribute-value.md) — set a class/title by condition with `@if` / `@then` / `@else`.
+- [Tabbed interface](tabbed-interface.md) — a `currentView` field + predicates to show the panel and highlight the active tab.
+
+## Context & dynamic variables
+
+- [Share state without prop-drilling](share-state-without-prop-drilling.md) — `provide` / `lookup` and reading `*name`.
+- [Edit through a dynamic target](edit-through-a-dynamic-target.md) — render `*name` and teleport edits back to the owner.
+
+## Composition
+
+- [Render a child component](render-a-child-component.md) — `<x render=".field">` and multiple views.
+- [Reuse markup with macros](reuse-markup-with-macros.md) — `macro(...)` with parameters and slots.
+
+## Data & events
+
+- [Bind text and attributes](bind-text-and-attributes.md) — `@text`, `:attr`, `$'…'` templates, scope enrichment.
+- [Handle events](handle-events.md) — `@on.<event>`, handler args, modifiers, custom events.
+
+## Component communication
+
+- [Coordinate components](coordinate-components.md) — `bubble`, `send`/`receive`, async `request`/`response`.

package/skill/tutuca/patterns/bind-text-and-attributes.md

@@ -0,0 +1,30 @@
+# Bind text and attributes
+
+**Problem:** display a field as text, bind it to an attribute, or compose a
+string from several values.
+
+```html
+<!-- text -->
+<span @text=".str"></span>      <!-- into a host element -->
+<x text="$getStrUpper"></x>     <!-- $ calls a method; no wrapping element -->
+
+<!-- attributes: plain = static, :attr = dynamic -->
+<input :value=".str" @on.input="$setStr value" />
+<a :href=".url" :title="$'Hi {.name}'">link</a>   <!-- $'…' string template -->
+<button :class="$'btn btn-{.kind}'">x</button>
+
+<!-- derive values for a subtree without putting them on the component -->
+<div @enrich-with="enrichScope">Len: <x text="@len"></x></div>
+```
+
+```js
+methods: { getStrUpper() { return this.str.toUpperCase(); } },
+alter:   { enrichScope() { return { len: this.text.length }; } },  // keys → @len, …
+```
+
+Value slots take `.field`, `$method`, or `@binding` — never a path
+(`.user.name` fails). Multi-word strings **must** be quoted (`'flex gap-3'`) or
+written as a `$'…'` template (`$'btn {.kind}'`); a bare unquoted string returns
+`null`. Boolean HTML attributes (`disabled`, `checked`, …) are auto-recognized
+— pass a boolean field. Scope `@enrich-with` (no `@each` on the element) is the
+path-free way to expose derived values to a subtree.

package/skill/tutuca/patterns/conditional-attribute-value.md

@@ -0,0 +1,29 @@
+# Conditional attribute value
+
+**Problem:** set an attribute (class, title, …) to one value or another
+depending on a condition.
+
+```html
+<button
+  @if.class=".isActive"
+  @then="'btn btn-success'"
+  @else="'btn btn-ghost'"
+  @on.click="$toggleIsActive"
+>
+  toggle
+</button>
+```
+
+`@if.<attr>` takes the condition (a `.field`, a `$method`, or a predicate like
+`equals? .tab 'x'`); `@then`/`@else` are the two values. String literals need
+quotes (`'btn ok'`); a `$'…'` template works too. **Multiple `@if` on one
+element:** every `@then`/`@else` after the first must name its attr
+(`@then.title`, `@else.title`) — HTML forbids duplicate attribute names, so an
+unnamed second `@then` is dropped silently.
+
+```html
+<button
+  @if.class=".isActive" @then="'on'" @else="'off'"
+  @if.title=".isActive" @then.title="'On'" @else.title="'Off'"
+></button>
+```

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

@@ -0,0 +1,26 @@
+# Coordinate components
+
+**Problem:** move state between components — notify an ancestor, message a
+specific component, or run async work and fold in the result.
+
+```js
+// bubble — walk toward the root; the first ancestor with the handler runs
+input:  { onItemClick(ctx) { ctx.bubble("itemSelected", [this]); return this; } },
+bubble: { itemSelected(item, ctx) { return this.insertInLogAt(0, item.label); } },
+
+// send / receive — deliver to one target (self, or ctx.at.<step> for another)
+methods: { submit(ctx) { ctx.at.field("status").send("flash", [this.draft]); return this; } },
+receive: { flash(message, ctx) { return this.setMessage(message); } },
+
+// request / response — async host work, result routed back
+receive:  { init(ctx) { ctx.request("loadData"); return this.setIsLoading(true); } },
+response: { loadData(res, err, ctx) { return this.setIsLoading(false).setItems(res); } },
+```
+
+Pick by direction: **bubble** for aggregate state an ancestor owns (logs,
+selections); **send/receive** to address one known component
+(`ctx.at.field("x")` / `.index(name, i)` / `.key(name, k)`, default self);
+**request/response** for fetch/timer/IndexedDB — register the async fn with
+`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")`.

package/skill/tutuca/patterns/edit-through-a-dynamic-target.md

@@ -0,0 +1,27 @@
+# Edit through a dynamic target
+
+**Problem:** render a value owned by a distant ancestor *and* let edits made in
+the child land back on the owner — without forwarding events up by hand.
+
+```js
+// producer exposes a field (or a seq-access) as a dynamic
+const Workspace = component({
+  name: "Workspace",
+  fields: { sheet: null },
+  provide: { active: ".sheet" },                       // or ".items[.selectedKey]"
+});
+
+// a distant consumer renders it as a target
+const Toolbar = component({
+  name: "Toolbar",
+  lookup: { active: { for: "Workspace.active", default: ".missing" } },
+  view: html`<x render="*active" as="edit"></x>`,
+});
+```
+
+Because `*active` resolves to a real **path** (not a copied value), the event
+fired inside the rendered child is *teleported*: the mutation skips the
+intermediate components and lands on `Workspace.sheet`, so the owner and any
+other view of the same value update in lock-step. A `provide` can even point at
+a seq-access (`.items[.selectedKey]`) to expose "the selected item". This is
+the **edit** counterpart of the share-state-without-prop-drilling recipe.

package/skill/tutuca/patterns/enrich-each-item.md

@@ -0,0 +1,25 @@
+# Enrich each item
+
+**Problem:** show a value derived from each item (a count, a formatted label)
+without storing it on the data.
+
+```html
+<li @each=".items" @enrich-with="enrichItem">
+  <x text="@value"></x> (<x text="@count"></x> characters)
+</li>
+```
+
+```js
+alter: {
+  enrichItem(binds, _key, item) {
+    binds.count = item.length;   // becomes @count in the template
+  },
+}
+```
+
+`@enrich-with` receives a **mutable** `binds` object (seeded with `{ key,
+value }`); every key you set becomes an `@`-prefixed binding for that item's
+subtree. The return value is ignored. Combine freely with `@when` and
+`@loop-with` on the same element. Without an `@each` on the same element,
+`@enrich-with` enriches the whole scope instead (see the bind-text-and-attributes
+recipe).

package/skill/tutuca/patterns/filter-a-list.md

@@ -0,0 +1,23 @@
+# Filter a list
+
+**Problem:** render only the items that match a condition.
+
+```html
+<li @each=".items" @when="filterItem">
+  <span @text="@key"></span>: <x text="@value"></x>
+</li>
+<!-- on <x render-each> the prefix drops: when="filterItem" -->
+```
+
+```js
+alter: {
+  filterItem(_key, item) {
+    return item.toLowerCase().includes(this.query.toLowerCase());
+  },
+}
+```
+
+`@when` names an `alter` handler called per item as `(key, value, iterData)`;
+return `false` to skip. It filters *after* any `@loop-with` slice, so a page
+can yield fewer than its window. Filtering reads other fields off `this`
+directly (`this.query`) — there are no paths in the template.

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

@@ -0,0 +1,27 @@
+# Handle events
+
+**Problem:** respond to a DOM event and update state.
+
+```html
+<button @on.click="$inc">+</button>      <!-- $ calls a method -->
+<button @on.click="dec">-</button>        <!-- bare name = input handler -->
+
+<!-- pass args by name; ctx is auto-appended last -->
+<input @on.input="$setStr value" />
+<input @on.input="$setN valueAsInt" />
+<button @on.click="$addItem JsonSelector">+</button>
+
+<!-- modifiers: keydown +send (Enter) / +cancel (Esc), and +ctrl/+cmd/+alt -->
+<input @on.keydown+send="$submit value" @on.keydown+cancel="$reset" />
+
+<!-- custom elements: any CustomEvent reaches @on.<name>, detail is `value` -->
+<emoji-picker @on.emoji-click="onPick value"></emoji-picker>
+```
+
+Handlers return a (new) instance of `this`. The first slot is a handler name
+(`$method`, or a bare name in `input`/`alter`); later slots are built-in arg
+names — `value`, `valueAsInt`/`valueAsFloat`, `event`, `key`, `isAlt`,
+`isShift`, `isCtrl`/`isCmd`, `dragInfo`, … `value` resolves to
+`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.

package/skill/tutuca/patterns/iterate-a-list.md

@@ -0,0 +1,18 @@
+# Iterate a list
+
+**Problem:** render one element per item in a list/map field.
+
+```html
+<!-- a host element per item: @key and @value are bound in the loop -->
+<li @each=".items"><span @text="@key"></span>: <x text="@value"></x></li>
+
+<!-- a child component per item -->
+<x render-each=".items"></x>
+<div @each=".items"><x render-it></x></div>
+```
+
+`@each` accepts a `.field` or a `*dynamic` (not a `$method` — a method result
+has no addressable path for event dispatch). `@key`/`@value` are auto-bound on
+host-element loops; under `render-each` / `render-it` each item is rendered as
+its own component (no `@value`). Use `render-each` for lists of components,
+`@each` for plain values.

package/skill/tutuca/patterns/paginate-a-list.md

@@ -0,0 +1,27 @@
+# Paginate a list
+
+**Problem:** show one page at a time without iterating or rendering the
+off-page items.
+
+```html
+<li @each=".items" @loop-with="paginate">
+  <span class="badge" @text="@key"></span> <x text="@value"></x>
+</li>
+```
+
+```js
+fields: { items: [], page: 0, pageSize: 5 },
+alter: {
+  paginate(seq) {           // runs once per render, before iteration
+    const start = this.page * this.pageSize;
+    return { iterData: { total: seq.size }, start, end: start + this.pageSize };
+  },
+}
+```
+
+`@loop-with` returns `{ iterData?, start?, end? }`, all optional. `start`/`end`
+slice with `Array.prototype.slice` semantics (`end` exclusive, negatives count
+from the end). Slicing is positional but **preserves each item's original
+key** — `@key` is the index in the full list, so events and two-way binding
+keep their identity across pages. `iterData` is the shared per-loop value
+handed to `@when` / `@enrich-with`.

package/skill/tutuca/patterns/render-a-child-component.md

@@ -0,0 +1,20 @@
+# Render a child component
+
+**Problem:** a component holds another component in a field and wants to render
+it (reaching into nested data is not allowed — `@text=".child.name"` fails).
+
+```js
+fields: { greeting: Greeting.make({ name: "world" }) },
+```
+
+```html
+<x render=".greeting"></x>           <!-- default ("main") view -->
+<x render=".greeting" as="edit"></x> <!-- a named view -->
+```
+
+The child draws its own view from its own fields, so inside `Greeting`'s view
+`@text=".name"` reads the child's `name`. This is the idiomatic way to display
+nested structure: make the nested thing a component and render it, rather than
+trying to path into it. For a list of children use `render-each` (see the
+iterate-a-list recipe); to flip which view renders, see the switch-between-views
+recipe.

package/skill/tutuca/patterns/reuse-markup-with-macros.md

@@ -0,0 +1,35 @@
+# Reuse markup with macros
+
+**Problem:** the same markup fragment repeats across a view and you want one
+definition — but it has no state of its own.
+
+```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>`,
+);
+
+const card = macro(
+  { title: "'Card'" },
+  html`<div class="card"><h2 @text="^title"></h2><x:slot></x:slot></div>`,
+);
+
+export function getMacros() { return { badge, card }; }
+```
+
+```html
+<x:badge></x:badge>                  <!-- defaults -->
+<x:badge label="Sale"></x:badge>     <!-- static string (no quotes needed) -->
+<x:badge :label=".status"></x:badge> <!-- bind a field -->
+<x:card title="Hi"><p>body</p></x:card>  <!-- children fill <x:slot> -->
+```
+
+A macro is pure template expansion — no fields, no handlers. Parameters are
+read as `^name`; calls inside the body (`$method`, `.field`) resolve against
+the *host* component. `<x:slot>` (or `<x:slot name="…">` for named slots)
+receives the caller's children. Register with `scope.registerMacros(...)`;
+registry keys are lowercased (`<x:Card>` → `card`). For repeated markup that
+*does* need state, use a child component instead (see the render-a-child-component
+recipe).

package/skill/tutuca/patterns/share-state-without-prop-drilling.md

@@ -0,0 +1,30 @@
+# Share state without prop-drilling
+
+**Problem:** a deep descendant needs a value owned by a distant ancestor, and
+you don't want to thread it through every component in between.
+
+```js
+// producer — exposes one of its fields under a name
+const Producer = component({
+  name: "EntryEditorAndSelector",
+  fields: { items: [] },
+  provide: { entries: ".items" },
+});
+
+// consumer — forwards to the producer's binding by "Component.name"
+const Consumer = component({
+  name: "Selector",
+  lookup: { entries: { for: "EntryEditorAndSelector.entries", default: ".items" } },
+});
+```
+
+```html
+<!-- read the dynamic with the * prefix — iterate or render it -->
+<option @each="*entries" :value="@value" @text="@label"></option>
+```
+
+`provide` publishes a field under a name; a descendant's `lookup` resolves
+`*name` to the nearest matching producer, falling back to `default` when none
+is in scope. `*name` works wherever a `.field` does for iteration/rendering.
+This is the **read** side; to edit the producer's value through the dynamic,
+see the edit-through-a-dynamic-target recipe.

package/skill/tutuca/patterns/show-or-hide-content.md

@@ -0,0 +1,22 @@
+# Show or hide content
+
+**Problem:** render an element only when a condition holds.
+
+```html
+<div @show=".isOpen">Details</div>
+<p @hide=".isOpen">(hidden when open)</p>
+
+<!-- boolean predicates for one-field checks -->
+<p @show="empty? .items">No results</p>
+<p @show="truthy? .query">Searching…</p>
+<div @show="equals? .view 'detail'">detail view</div>
+
+<!-- on an <x> render op: wraps the produced node, no extra DOM element -->
+<x text=".count" show=".isOpen"></x>
+```
+
+The closed set of predicates is `empty?`, `truthy?`, `falsy?`, `null?`,
+`equals?` (binary). For a condition spanning multiple fields, use a no-arg
+method instead (`@show="$canSubmit"`). `@show`/`@hide` toggle visibility on a
+host element; the wrapper form (`show=` / `hide=` on `<x>`) conditionally
+emits the node with no surrounding element.

package/skill/tutuca/patterns/switch-between-views.md

@@ -0,0 +1,26 @@
+# Switch between views
+
+**Problem:** render the *same* component in a different view (e.g. a read-only
+"main" vs an "edit" form).
+
+```js
+component({
+  view:  html`<p @text=".title"></p>`,                  // "main"
+  views: { edit: html`<input :value=".title" @on.input="$setTitle value" />` },
+});
+```
+
+```html
+<!-- as= picks the view for one <x render> element only -->
+<x render=".value"></x>
+<x render=".value" as="edit"></x>
+
+<!-- @push-view forces a view on every component rendered under the host -->
+<div @push-view=".view"><x render-each=".items"></x></div>
+```
+
+`as="edit"` applies to the direct component only and falls back to `main` if
+the view is absent. `@push-view` pushes a view name onto the render stack so
+every descendant picks the first matching view (else `main`) — use it to flip a
+whole subtree (e.g. a list) into edit mode at once. To toggle *sibling panels*
+by a field instead, see the tabbed-interface recipe.

package/skill/tutuca/patterns/tabbed-interface.md

@@ -0,0 +1,38 @@
+# Tabbed interface
+
+**Problem:** build tabs — a single `currentView` field decides which panel
+shows, and the active tab button is highlighted.
+
+```html
+<div role="tablist" class="tabs">
+  <button
+    role="tab"
+    @if.class="equals? .currentView 'overview'"
+    @then="'tab tab-active'"
+    @else="'tab'"
+    @on.click="$setCurrentView 'overview'"
+  >Overview</button>
+  <button
+    role="tab"
+    @if.class="equals? .currentView 'pricing'"
+    @then="'tab tab-active'"
+    @else="'tab'"
+    @on.click="$setCurrentView 'pricing'"
+  >Pricing</button>
+</div>
+
+<div @show="equals? .currentView 'overview'">…overview…</div>
+<div @show="equals? .currentView 'pricing'">…pricing…</div>
+```
+
+```js
+fields: { currentView: "overview" },   // $setCurrentView is auto-generated
+```
+
+One string field is the whole state machine. `equals? .currentView 'overview'`
+drives both the panel's `@show` and the active-tab class via `@if.class` /
+`@then` / `@else`. Tab clicks call the auto-generated setter with a
+string-literal arg (`@on.click="$setCurrentView 'pricing'"`). This toggles
+**sibling panels** by predicate; to swap a *component's own* rendered view
+instead, see the switch-between-views recipe. The field name is yours to pick
+(`tab`, `currentView`, …).