tutuca 0.9.91 → 0.9.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.91",
+  "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
 
@@ -32,7 +33,8 @@ When authoring tutuca code, also load these if available:
 | 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/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
@@ -1056,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.