@pebble-software/bonsai 0.1.2 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/%40pebble-software%2Fbonsai)](https://www.npmjs.com/package/@pebble-software/bonsai)
 [![status: preview](https://img.shields.io/badge/status-preview-orange)](https://github.com/PebbleSoftwareInc/pebble-bonsai)
-[![react](https://img.shields.io/badge/react-18%20%7C%2019-61dafb)](https://react.dev)
+[![react](https://img.shields.io/badge/react-19.2%2B-61dafb)](https://react.dev)
 
 > ⚠️ **Active development / preview** — this package is pre-1.0 and evolving quickly. APIs, the configuration schema, and the component set may change between releases without a deprecation cycle. Pin an exact version and read release notes before upgrading. Feedback and issues are very welcome!
 
@@ -22,6 +22,7 @@ Bonsai is the rendering engine behind [Pebble Bonsai](https://github.com/PebbleS
 - [Expression language](#expression-language)
 - [Structural nodes: each & if](#structural-nodes-each--if)
 - [Controlled inputs & state](#controlled-inputs--state)
+- [Click actions](#click-actions)
 - [Component reference](#component-reference)
 - [Styling](#styling)
 - [Extending Bonsai](#extending-bonsai)
@@ -67,7 +68,7 @@ npm and pnpm don't auto-install optional peers — if you import the root entry
 
 Requirements:
 
-- `react` and `react-dom` 18 or 19
+- `react` and `react-dom` 19.2 or newer
 - A bundler that understands ES modules (Vite, Next.js, Rspack, etc.) — the package is ESM-only.
 - Tailwind CSS v4 in your build, for the styles — `index.css` ships as Tailwind source (see [Styling](#styling)).
 
@@ -245,6 +246,7 @@ Submission only happens when the instance renders a `<form>` (see below) and the
 - `as: "div"` renders the whole instance as a `<div>` instead of a `<form>` (and no submit handler is attached). Use it when embedding an instance inside a host `<form>`, or when rendering sibling/nested instances, where nested `<form>` elements would be invalid HTML.
 - The two combine predictably: `render: "pdf"` always wins and produces a `<div>`; otherwise `as` decides.
 - Components read the mode with `useBonsaiRenderMode()`. The built-in `signature` uses it: under `render: "pdf"` it shows the captured image (or an empty signature line) instead of the interactive pad.
+- Templates restyle their PDF output with the `pdf:` variant: `pdf:hidden`, `pdf:text-sm`, `pdf:break-before-page`. It matches only inside a `render: "pdf"` tree and sorts after the responsive and `print:` variants, so `pdf:text-sm` wins over `md:text-xl` (an A4 page, 794px wide, is past the `md` breakpoint). It ships in `theme.css` and in the bundled stylesheet.
 
 Each mounted instance owns its own store — there's no shared module-level state and no global `updateData`; `useUpdateData()` is the only way to reach a given instance's data, and only from within its subtree.
 
@@ -261,6 +263,7 @@ The template format is defined by the Zod schema in [`library/schemas/src/bonsai
 **The renderer does not validate templates; it renders whatever it is given.** The schema is a discriminated union on `type` with a per-component `args` contract, and the Pebble Bonsai platform validates every template against it before rendering. At render time:
 
 - An unknown `type` (one not in the active registry) follows the registry's `fallback`: a plain `<div>` by default (all built-in registries), a component of your choosing, or — with `fallback: "error"` — an error, which the node's error guard logs and renders as nothing.
+- A few `args` never reach the component, whatever the template says: raw-HTML props (`dangerouslySetInnerHTML`, `srcDoc`) and overrides of where a form submits (`formAction`, `formMethod`, `formTarget`, `formEncType`). URL props (`href`, `src`, `action`, `xlinkHref`) keep only `http(s):`, `mailto:`, `tel:`, `data:image/` and relative URLs, bound values included; anything else is dropped, and an `image` without a usable `src` renders nothing. This is a floor, not a replacement for validation: pages that render untrusted templates should also send a Content Security Policy without `'unsafe-inline'` scripts.
 - A node that throws while rendering is logged with `console.error` and rendered as nothing; the rest of the tree still renders.
 - The exported `Config` type is `any`, so TypeScript won't catch template mistakes either.
 
@@ -419,6 +422,29 @@ Allowlisted methods: `map`, `filter`, `some`, `every`, `find`. Anything else —
 - The store's `data` is deep-copied from the `data` prop *for plain objects and arrays* — an instance never mutates the object you passed in, and two instances seeded from the same plain-object `data` still get fully independent state. **Non-plain values nested inside `data` (class instances, `Map`/`Set`, functions, `Date`, `File`, etc.) are passed through by reference, not cloned.** If `data` nests something like `{ profile: new SomeClass() }`, that nested value is shared between every instance seeded from it, and writes through it are visible to the caller. Keep non-plain values out of `data` if you need per-instance isolation.
 - **Reactivity model**: every leaf reads the store itself (via `valtio`'s `useSnapshot`) and evaluates its own bindings against that snapshot — the read *is* the subscription. A node with no bindings at all (a plain layout `div`) is detected and skipped from this entirely, so it never re-renders due to an unrelated store write. This is what keeps a keystroke in one field from re-rendering the rest of the form.
 
+## Click actions
+
+Any component can take an `onClick` arg: a list of store writes applied in order when it's clicked. Templates carry data, never code: each action names a store path (`set`) and the value to write there (`to`).
+
+```json
+{
+  "type": "button",
+  "args": {
+    "type": "button",
+    "className": "{{pizzaChoice == 'pizza1' ? 'bg-accent-orange' : 'bg-background'}}",
+    "onClick": [{ "set": "pizzaChoice", "to": "pizza1" }]
+  },
+  "children": ["Classic Margherita"]
+}
+```
+
+- `set` is a plain path using the same grammar as bindings (`"order.size"`, `"items[0].done"`), not a `{{binding}}`. Missing objects along the path are created.
+- `to` is required. It's either a literal (`"pizza1"`, `true`, `null` to clear, an object) or a `{{...}}` expression such as `"{{!open}}"` or `"{{step + 1}}"`. Every `to` in one click is evaluated against the state from before the click, so `[{ "set": "step", "to": "{{step + 1}}" }, { "set": "previous", "to": "{{step}}" }]` records the old step. Object values are copied into the store, so later edits never change the template.
+- Inside an `each`, a path that starts with the row alias (`"row.selected"`) writes to that row's real store path, just like a two-way binding. Rows of a computed `items` expression have no store path, so clicks there write nothing.
+- Use a `button` with `"type": "button"` for anything that looks clickable. It gets keyboard and focus support for free, and inside the form wrapper a button without a type submits the form.
+- Handlers only exist after client hydration. The server render emits the same markup with or without `onClick`.
+- In a registry, a component that lists `capabilities` must include `"events"` to receive click actions (see [Bring your own registry](#bring-your-own-registry)). All built-in components include it.
+
 ## Component reference
 
 The full list of built-in component types is the `COMPONENT` enum in [`library/constants/src/components.ts`](https://github.com/PebbleSoftwareInc/pebble-bonsai/blob/main/library/constants/src/components.ts); allowed `args` for each are in the [schema](#configuration-schema).
@@ -459,7 +485,7 @@ Bonsai is styled with **Tailwind CSS v4**. Components emit plain Tailwind utilit
 - **Compile it with your own Tailwind v4 build.** `index.css` ships as uncompiled Tailwind source: it opens with `@import "tailwindcss"` and carries the full theme (an OKLCH color palette with swappable accent colors, typography, shadows) and base styles. Its `@source "./"` points Tailwind at Bonsai's compiled `dist/`, so every class the built-in components use is generated. `tailwindcss` and `tw-animate-css` are optional peers for this reason. None of the JavaScript entry points import it; it is the only side effect the package declares (`"sideEffects": ["**/*.css"]`), so bundlers can tree-shake everything else.
 - **It styles the whole page, not just Bonsai.** The stylesheet includes Tailwind's Preflight reset plus base rules for `body` (font, background, text color) and `h1`–`h6` (heading font). On a page that has its own design system, load it deliberately — for example, only on the routes that render Bonsai.
 - **Fonts load from Pebble's CDN.** Sora, Fredoka, and Great Vibes (used by the signature control) are declared with `@font-face` pointing at `https://brand.pebble.software/fonts/`. If you use a Content Security Policy, allow that origin in `font-src`, or override `--font-body`, `--font-heading`, and `--font-signature` with fonts you host.
-- **Scoping**: every rendered tree is wrapped in a `.bonsai-root` element carrying a `data-mode` attribute (`web` / `pdf` / `preview`), so hosts can scope their own overrides per render mode.
+- **Scoping**: every rendered tree is wrapped in a `.bonsai-root` element carrying a `data-mode` attribute (`web` / `pdf` / `preview`), so hosts can scope their own overrides per render mode; templates use the `pdf:` variant for the same thing (see [Wrapper element and render mode](#wrapper-element-and-render-mode)).
 - **Accent colors**: set `data-theme` on any ancestor (`<body data-theme="indigo">`) to switch the accent palette. Available values: `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald` (default), `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`.
 - **Theming**: the theme is token-driven — redefine the CSS variables (e.g. `--color-main`, `--font-heading`) after the stylesheet to restyle every component at once, or target `.bonsai-root` descendants for finer overrides.
 - **Utilities in your templates**: a `className` utility that no built-in component uses (say, `grid-cols-5`) is only generated if your build also scans the templates that use it — add their location with `@source`. Inside the Pebble Bonsai platform, CSS is compiled per template so this never comes up.
@@ -543,6 +569,8 @@ const acmeRegistry = defineBonsaiRegistry({
 export const { Bonsai } = createBonsaiRenderer({ registry: acmeRegistry });
 ```
 
+`capabilities` is optional; leaving it out means unrestricted. When present, `validateTemplate` rejects anything the list doesn't allow: children without `"children"`, a render mode without `"ssr"`/`"pdf"`, and [click actions](#click-actions) without `"events"`. The renderer also skips `onClick` on a component without `"events"`. In the example above, `rating` can't take `onClick`; add `"events"` to allow it.
+
 A `registry` prop on an individual `<Bonsai>` replaces the renderer's registry for that instance only. `extendRegistry(base, preset)` layers a preset-shaped `{ components, controlledInputs }` over any registry — `createBonsaiRenderer` uses it for its `components`/`controlledInputs` options.
 
 ### Contributing a built-in component

package/dist/ast.js

@@ -1,4 +1,4 @@
-import { a as r, c as i, e as p, i as o, p as x } from "./chunks/index-DzpRdatr.js";
+import { a as r, c as i, e as p, i as o, p as x } from "./chunks/index-CD5pykpk.js";
 import "jsep";
 export {
   r as clearExpressionCache,