tutuca 0.9.80 → 0.9.82

package/package.json

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

package/skill/tutuca/SKILL.md

@@ -28,6 +28,7 @@ When authoring tutuca code, also load these if available:
 | Task                                                                                           | File                            |
 | ---------------------------------------------------------------------------------------------- | ------------------------------- |
 | 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)             |
 | `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)   |

package/skill/tutuca/advanced.md

@@ -42,9 +42,16 @@ Touch is wired up too (drag fires after a small move threshold).
 
 ## Dynamic Bindings
 
-For passing values "context-style" through nested components without prop
-drilling. **`provide`** on the producer; **`lookup`** on consumers;
-resolve as `*name`.
+For passing values "context-style" to a deep descendant without threading
+them through every component in between. **`provide`** on the producer;
+**`lookup`** on consumers; resolve as `*name`.
+
+> **Best practice:** keep state local to the component and reach for
+> `provide` / `lookup` only when it is genuinely the only solution. Dynamic
+> bindings couple a consumer to a producer that may not be in scope — prefer
+> keeping components as self-contained as possible: let a child render the
+> field it needs from its owner, and lift state only as far up the tree as it
+> actually needs to live.
 
 ```js
 const Theme = component({

package/skill/tutuca/component-design.md

@@ -0,0 +1,151 @@
+# Tutuca Cheatsheet — Component Design
+
+How to *shape* a feature into one or more tutuca components — responsibilities,
+where state lives, which channel to reach for — before you reach for syntax. The
+mechanics live elsewhere: component skeleton, fields, directives, and the
+post-edit verification recipe in [core.md](./core.md); the orchestration channels
+in [request-response.md](./request-response.md); dynamic bindings (`provide` /
+`lookup` / `*x`) in [advanced.md](./advanced.md); task recipes in
+[patterns/README.md](./patterns/README.md). This file is a router with judgment
+attached — every rule points at its canonical home rather than restating it.
+Read it when deciding how to split a feature into components, where a piece of
+state should live, how two components should talk, or when reviewing a component
+for design smells.
+
+## Decide in this order
+
+Walk these top-down whenever you add or reshape a component:
+
+1. **What single responsibility is this?** If the answer has an "and" in it, split
+   it into separate components.
+2. **Who owns each piece of state?** The component that reads and mutates a value
+   owns it. Put the field there; let others render or message it.
+3. **How do these components talk?** Pick the narrowest channel that reaches the
+   owner — see the ladder below.
+4. **Where does the outside world cross the boundary?** Outbound I/O goes through
+   `ctx.request` / `response`; inbound external events go through
+   `app.sendAtRoot` to the root. Keep the logic inside tutuca on both sides.
+
+## Communication decision ladder
+
+Reach for the *narrowest* channel that does the job, and only move further down
+the ladder when the one above can't express it:
+
+- **The component owns the state needed to respond** → call a plain **`method`** on
+  itself (stays self-contained). See [core.md](./core.md) Methods.
+- **An ancestor owns aggregate state** (a log, a selection, a total) → **`ctx.bubble`**
+  up toward the root; the first ancestor with a matching handler runs. See
+  [request-response.md](./request-response.md) "When to bubble".
+- **You need to reach one known component** → **`ctx.send` / `receive`**, addressing a
+  specific path with `ctx.at` (defaults to self). See
+  [request-response.md](./request-response.md) "When to send".
+- **The work is async or host-side** (fetch, timer, IndexedDB, an SDK) →
+  **`ctx.request` / `response`**, which goes out to the host and routes the result
+  back into component state. See [request-response.md](./request-response.md).
+- **An external event pushes *into* the app** (WebSocket, `postMessage`, …) →
+  **`app.sendAtRoot`**, which lands the inbound event on the root. See
+  [request-response.md](./request-response.md) "Integrating with the outside world".
+- **A deep descendant needs a value owned far away** and nothing in between should
+  know about it → **`provide` / `lookup` (`*name`)** across the tree — the last
+  resort. See [advanced.md](./advanced.md).
+
+A compact worked version of the first four (`method`, `bubble`, `send`/`receive`,
+`request`/`response`) lives in
+[patterns/coordinate-components.md](./patterns/coordinate-components.md).
+
+## Do's & Don'ts
+
+- **Do create single-purpose components. Don't pack multiple responsibilities
+  into one.** A component that draws its own view from its own fields is the unit
+  of reuse and the unit of testing. → [patterns/render-a-child-component.md](./patterns/render-a-child-component.md)
+
+- **Don't add a `kind` / `type` field and branch the view on it. Do make one
+  component per kind and render it with `<x render=".item">`.** Conditional-on-kind
+  views grow into tangled `@if` chains; a component per kind keeps each view flat
+  and each concern isolated. This is also why pathing into nested data is barred —
+  model the nested thing as a component instead. → [core.md](./core.md) "Common
+  pitfalls" (Paths are not allowed in values) and
+  [patterns/render-a-child-component.md](./patterns/render-a-child-component.md)
+
+- **Do keep state in the component that owns and uses it, and lift it only as far
+  up the tree as it needs to live. Don't thread a value through every component in
+  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 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.
+  → [advanced.md](./advanced.md)
+
+- **Do pick the channel by direction (the ladder above). Don't `bubble` an event
+  no ancestor consumes, and don't `send` to self when a plain method call would
+  do.** `bubble` emits an *event* any ancestor can observe; `send` delivers a
+  *message* to one target. → [request-response.md](./request-response.md) "When to
+  bubble" / "When to send"
+
+- **Do keep logic inside the tutuca app when integrating with the outside world.**
+  Route outbound work through `ctx.request` / `response` and inbound external
+  events through `app.sendAtRoot` to the root (which forwards deeper with `ctx.at`),
+  so handlers stay the single owner of state changes. **Don't mutate `app.state`
+  directly or `addEventListener` outside the model** — state changed that way
+  bypasses the immutable `return this.set…()` discipline and is invisible to the
+  component that owns it. → [request-response.md](./request-response.md)
+  "Integrating with the outside world" (and its ⚠️ note)
+
+- **Do handle every DOM event with tutuca's built-in `@on.` handlers — including
+  custom events fired by web components.** `@on.click`, `@on.input`,
+  `@on.<custom-event>` (the event `detail` surfaces as `value`) keep the event
+  inside the model, so it flows through a handler and returns a new `this`. **Don't
+  reach in from the outside with `addEventListener`** — a listener attached out of
+  band mutates state the owning component can't see and bypasses the transactor.
+  → [core.md](./core.md) "Event Handling" and "Web Components & Custom Events"
+
+- **Do use inline predicates and auto-generated mutators. Don't hand-write
+  `is*Selected()` / `select*()` boilerplate.** A single field plus
+  `equals? .activeSection 'todo'` / `empty?` and the generated `$setActiveSection`
+  / `toggleX` often *is* the whole state machine. → [core.md](./core.md) "Methods
+  as Predicates & Computed Values" and "Field Types & Auto-generated API"
+
+- **Do remember a rendered child gets a clean namespace.** Parent `@` bindings
+  (`@each`, `@enrich-with`) don't cross a `<x render>` boundary — pass a value
+  across it with `*name`, not by assuming the binding leaks in. → [advanced.md](./advanced.md)
+
+- **Do add a decoy view when a margaui class is assembled at runtime.** The margaui
+  compiler only scans `class=` / `:class=` *literals*, so classes that appear only
+  in `@if.class` `@then`/`@else` payloads or are composed dynamically in an
+  `@enrich-with` / `:class` handler emit no CSS and render unstyled. Add a hidden,
+  never-rendered view (e.g. `_margauiClasses: html\`<p class="btn-success btn-ghost
+  …"></p>\``) listing each such class as a real literal so the scanner picks it up.
+  → [advanced.md](./advanced.md) "Pitfall: `@if.class` payloads are invisible to
+  the scanner", and the worked decoy view in `personal-site.js`.
+
+- **Do close the loop after every change** with `tutuca <module> lint` → `test` →
+  `render`. → [core.md](./core.md) "Verifying changes"
+
+## Smells & refactors
+
+- **`is*Selected()` + `select*()` methods → predicate + generated setter.**
+  Replace `@on.click="selectTodo"` / `@show="$isTodoSelected"` with
+  `@on.click="$setActiveSection 'todo'"` / `@show="equals? .activeSection 'todo'"`,
+  derive the current value from one field. (See `composability.js`, commit `808574e`.)
+- **A view that `@if`-branches on a `kind` field → one component per kind**, each
+  rendered with `<x render>`.
+- **A value passed down through three components that don't use it → move the
+  state up to the nearest common owner** and let the leaf render it directly; only
+  if nothing in between should know it, use `provide` / `lookup`.
+- **Host code poking `app.state` or attaching a listener → an `app.sendAtRoot`
+  handler on the root**, with the mutation expressed as `return this.set…()`.
+
+## See also
+
+- [core.md](./core.md) — component skeleton, fields, directives, predicates, the
+  verification recipe, and the "Common pitfalls" list.
+- [request-response.md](./request-response.md) — the channels in depth
+  (`bubble`, `send`/`receive`, `request`/`response`, `sendAtRoot`) and integrating
+  with the outside world.
+- [advanced.md](./advanced.md) — `provide` / `lookup` / `*name` and the
+  clean-namespace boundary.
+- [patterns/coordinate-components.md](./patterns/coordinate-components.md),
+  [patterns/share-state-across-the-tree.md](./patterns/share-state-across-the-tree.md),
+  [patterns/render-a-child-component.md](./patterns/render-a-child-component.md) —
+  runnable recipes for the rules above.

package/skill/tutuca/core.md

@@ -22,6 +22,9 @@ the `tutuca` CLI.
 > 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).
+> Design judgment — shaping a feature into components, where state lives, which
+> channel to reach for, and a do's & don'ts list: see
+> [component-design.md](./component-design.md).
 
 ## Verifying changes
 
@@ -976,6 +979,9 @@ export function getTests({ describe, test, expect }) { /*...*/ }      // optiona
 
 ## See also
 
+- [component-design.md](./component-design.md) — design judgment for shaping a
+  feature into components: responsibilities, where state lives, which channel to
+  reach for, and a curated do's & don'ts list.
 - [request-response.md](./request-response.md) — `bubble` / `send`-`receive` /
   `request`-`response` channels, the `ctx.at` `PathBuilder`, `$unknown`, and
   request-handler registration.

package/skill/tutuca/patterns/README.md

@@ -24,7 +24,7 @@ task.
 
 ## Context & dynamic variables
 
-- [Share state without prop-drilling](share-state-without-prop-drilling.md) — `provide` / `lookup` and reading `*name`.
+- [Share state across the tree](share-state-across-the-tree.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

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

@@ -24,4 +24,4 @@ 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.
+the **edit** counterpart of the share-state-across-the-tree recipe.

package/skill/tutuca/patterns/{share-state-without-prop-drilling.md → share-state-across-the-tree.md}

@@ -1,8 +1,16 @@
-# Share state without prop-drilling
+# Share state across the tree
 
 **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.
 
+> **Reach for this last.** Keep state local to the component and use
+> `provide` / `lookup` only when it is genuinely the only solution — a value
+> owned far away that a deep descendant needs and nothing in between should
+> know about. Dynamic bindings couple a consumer to a producer that may not be
+> in scope, so keep components as self-contained as possible: let a child
+> render the field it needs from its owner, and lift state only as far up the
+> tree as it needs to live.
+
 ```js
 // producer — exposes one of its fields under a name
 const Producer = component({