tutuca 0.9.66 → 0.9.67

package/skill/SKILL.md

@@ -1,46 +0,0 @@
----
-name: tutuca
-description: Authoring or reviewing tutuca components, html`` views, macros, or running the `tutuca` CLI. Covers field types, @-directives, bubble/receive/response handlers, and the post-edit `tutuca <module> lint` + `tutuca <module> render --title …` verification recipe.
----
-
-# Tutuca
-
-Tutuca is an immutable-state SPA framework: components have typed
-`fields`, auto-generated mutators (`setX`, `pushInX`, …), HTML-template
-`view`s with `@`-prefixed directives, and `bubble` / `receive` /
-`response` handlers for orchestration.
-
-## Verifying changes
-
-After editing a tutuca module, run two checks before declaring the edit
-done:
-
-1. **Lint** — catches undefined fields/handlers/macros/events. Exits
-   `2` on any error-level finding.
-
-   ```sh
-   tutuca <module-path> lint
-   ```
-
-2. **Render the example that exercises the feature you changed** —
-   confirms the component mounts in a headless DOM with the new
-   behavior. Exits `3` on render crash.
-
-   ```sh
-   tutuca <module-path> render --title "<example title>"
-   ```
-
-   If no example covers the feature, add one to `getExamples()` first —
-   that's how the feature becomes verifiable.
-
-## Routing
-
-| Task                                                                                           | File                            |
-| ---------------------------------------------------------------------------------------------- | ------------------------------- |
-| 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)             |
-| Drag & drop, dynamic bindings (`*x`), pseudo-`x`, custom seq types, Tailwind/MargaUI | [advanced.md](./advanced.md)   |
-
-Read `core.md` first. Reach for `cli.md` or `advanced.md` only when the
-task touches them — both files are referenced inline from `core.md` so
-you'll be pointed there when relevant.

package/skill/advanced.md

@@ -1,146 +0,0 @@
-# Tutuca — Advanced Topics
-
-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.
-
-## Drag and Drop
-
-```html
-<div
-  @each=".items"
-  draggable="true"
-  data-dragtype="my-item"
-  data-droptarget="my-item"
-  @on.drop="onDrop @key dragInfo event"
-></div>
-```
-
-```js
-input: {
-  onDrop(targetKey, dragInfo, e) {
-    const sourceKey = dragInfo.lookupBind("key");   // any bind from source render
-    return this.setItems(this.items.moveKeyBeforeKey(sourceKey, targetKey));
-  },
-}
-```
-
-Tutuca auto-manages two attrs during a drag — style them with CSS:
-
-```css
-[data-dragging="1"] {
-  opacity: 0.5;
-}
-[data-draggingover="my-item"] {
-  outline: 1px dashed;
-}
-```
-
-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. Define on the producer; alias on consumers; resolve as `*name`.
-
-```js
-const Theme = component({
-  name: "Theme",
-  fields: { color: "blue" },
-  dynamic: { color: ".color" },
-  on: {
-    stackEnter() {
-      return ["color"];
-    },
-  },
-});
-const Child = component({
-  dynamic: { color: { for: "Theme.color", default: "'gray'" } },
-  view: html`<p :style="color: {*color}"></p>`,
-});
-```
-
-`on.stackEnter()` is required only on the **producer** (the component
-declaring `dynamic: { name: ".field" }` to expose a value). It returns
-the list of dynamic-binding names this component pushes onto the stack
-when entering its render. Consumers (which only alias via
-`{ for: "Producer.name", default: ... }`) don't need it.
-
-## Pseudo-`x` (`@x`)
-
-Tutuca's special operations (`render`, `render-it`, `render-each`, `text`,
-`show`, `hide`, `slot`) live on the `<x>` tag. That works almost
-everywhere, but the browser's HTML parser refuses to keep `<x>` (or any
-unknown tag) as a child of certain elements: `<select>` only allows
-`<option>` / `<optgroup>`, `<table>` only allows `<thead>` / `<tbody>` /
-`<tr>`, `<tr>` only allows `<th>` / `<td>`, etc. Drop `<x render-each>`
-inside one of those and the parser silently strips it.
-
-The escape hatch: prefix the **first** attribute on a *legal* tag with
-`@x`. Tutuca treats that tag as if it were `<x>` and reads the next
-attribute as the special op.
-
-```html
-<!-- ❌ <x> stripped by the HTML parser inside <select> -->
-<select>
-  <x render-each=".items" as="option"></x>
-</select>
-
-<!-- ✅ pseudo-x: <option @x render-each=".items" as="option"> -->
-<select>
-  <option @x render-each=".items" as="option"></option>
-</select>
-```
-
-Notes:
-
-- `@x` must be the **first** attribute; the special op (`render-each`,
-  `render`, `text`, `show`, ...) is the second.
-- The host tag (here `<option>`) is otherwise ignored — only the special
-  op runs. Tutuca produces the rendered children directly.
-- Same trick works inside `<tr>`, `<table>`, `<colgroup>`, `<dl>`,
-  `<details>`, or anywhere else the parser would discard `<x>`.
-
-## Registering a custom seq type
-
-To make `@each` recognize your own collection class, install a
-`SEQ_INFO` walker on its prototype:
-
-```js
-import { SEQ_INFO } from "tutuca";
-
-class MyClass {
-  // ...
-}
-MyClass.prototype[SEQ_INFO] = (seq, visit) => {
-  for (const [k, v] of seq.entries()) visit(k, v, "data-sk");
-};
-```
-
-`SEQ_INFO` is `Symbol.for("tutuca.seqInfo")`, so the same identity
-is shared across module graphs (source vs. bundled tutuca). The
-renderer reads `seq[SEQ_INFO]` directly (no `.constructor` lookup),
-which is why the walker goes on the prototype, not as a static.
-
-The third arg to `visit` is the data attribute used for stable-key
-diffing (typically `"data-sk"` for "sequence key").
-
-## Tailwind / MargaUI Class Compilation (extra build)
-
-```js
-import { compileClassesToStyleText, injectCss, tutuca } from "tutuca/extra";
-import { compile } from "https://esm.sh/margaui";
-
-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()`.

package/skill/cli.md

@@ -1,117 +0,0 @@
-# Tutuca CLI Reference
-
-The `tutuca` CLI inspects, documents, lints, and renders any module that
-follows the *Conventional Module Exports* shape (see `core.md`). Reach
-this file when you need command/flag/exit-code details, or when reading
-a lint code out of `lint` output. Otherwise the post-edit recipe in
-`core.md` (run `lint`, then `render --title "<your example>"`) is
-enough.
-
-## Install / invoke
-
-```sh
-# project local
-npm i --save-dev tutuca
-npx tutuca <module-path> <command> [name] [flags]
-
-# global
-npm i -g tutuca
-tutuca <module-path> <command> [name] [flags]
-
-# from a checkout of this repo
-bun tools/tutuca.js <module-path> <command> [name] [flags]
-```
-
-The module path comes **first**, the command second, an optional component
-name third. `tutuca help` prints the full reference; `tutuca help <command>`
-prints a one-liner. `tutuca` ↔ `tutuca -h` prints overview.
-
-## Commands
-
-| Command         | Purpose                                                                                                                |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `info`          | Summarize which `getX()` exports are present and counts                                                                |
-| `list`          | List components with their views and fields (name + type)                                                              |
-| `examples`      | Print `getExamples()` content (title, items, per section)                                                              |
-| `docs [name]`   | Generate API docs (methods, input handlers, fields with auto-generated accessors) — all or one                         |
-| `lint [name]`   | Run the linter; exits **2** on any error-level finding                                                                 |
-| `render [name]` | Render examples to HTML in a headless DOM. Filter by component name or `--title`/`--view`. Exits **3** on render crash |
-| `help [cmd]`    | Show usage; the only command that does **not** need a module path                                                      |
-
-## Global flags
-
-```
--f, --format <cli|md|json|html>  output format
-                                 defaults: info/list/examples/lint → cli
-                                           docs/render             → md
-                                 html only valid for render
-                                 json works for every command
--o, --output <file>              write to file instead of stdout
-    --pretty                     pretty-print HTML (md/html) via prettier;
-                                 JSON formatter uses indent 2
-    --module <path>              alternative to first-positional module path
--h, --help                       show help (overview, or for one command)
-```
-
-## Exit codes
-
-| Code | Meaning                                                  |
-| ---- | -------------------------------------------------------- |
-| `0`  | success                                                  |
-| `1`  | usage error (bad args, missing module, bad module shape) |
-| `2`  | lint findings at error level                             |
-| `3`  | render crash                                             |
-
-## Examples
-
-```sh
-tutuca ./src/components.js info                       # quick overview
-tutuca ./src/components.js list                       # components, views, fields
-tutuca ./src/components.js docs Button -f json        # one component, JSON
-tutuca ./src/components.js render -f html --pretty -o out/examples.html
-tutuca ./src/components.js render Button --title "Disabled state"
-
-# Post-edit verification: lint, then render the example for the feature
-# you just changed (add the example first if none covers it). Add
-# --pretty when you need to read the HTML to verify structure.
-tutuca ./src/components.js lint
-tutuca ./src/components.js render --title "Disabled state"
-tutuca ./src/components.js render --title "Disabled state" --pretty
-```
-
-## Linter Rules
-
-Codes emitted by `lint`. Source: `tools/core/lint-check.js`.
-
-### Field references
-
-- `FIELD_VAL_NOT_DEFINED` — `.field` not declared in `fields`.
-
-### Input-handler / method confusion
-
-- `INPUT_HANDLER_NOT_IMPLEMENTED` — bare handler name not in `input`.
-- `INPUT_HANDLER_NOT_REFERENCED` — `input` entry never used.
-- `INPUT_HANDLER_METHOD_NOT_IMPLEMENTED` — `.handler` not in `methods`.
-- `INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD` — bare name resolves to `methods` (use `.name`).
-- `INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER` — `.name` resolves to `input` (drop the dot).
-
-### Iteration helpers (`alter`)
-
-- `ALT_HANDLER_NOT_DEFINED` — `@when` / `@enrich-with` / `@loop-with` name not in `alter`.
-- `ALT_HANDLER_NOT_REFERENCED` — `alter` entry never used.
-
-### Templates / events
-
-- `RENDER_IT_OUTSIDE_OF_LOOP` — `<x render-it>` outside `@each` / `render-each`.
-- `UNKNOWN_EVENT_MODIFIER` — `+mod` not in the recognized modifier set.
-- `UNKNOWN_HANDLER_ARG_NAME` — handler arg name not a built-in / declared component.
-- `DUPLICATE_ATTR_DEFINITION` — same attr set by literal + `:attr` + `@if.attr` on one element.
-- `UNKNOWN_DIRECTIVE` — `@name` directive not recognized (typo or unsupported).
-- `UNKNOWN_X_OP` — first attribute on `<x>` (or pseudo-`@x`) is not a known op.
-- `UNKNOWN_X_ATTR` — extra attribute on `<x op>` not consumed by the op and not a known wrapper (`show`/`hide`).
-
-### Names registered with the app
-
-- `UNKNOWN_REQUEST_NAME` — `!name` not registered.
-- `UNKNOWN_COMPONENT_NAME` — component type not registered.
-- `UNKNOWN_MACRO_ARG` — macro attr not declared in defaults.