@pebble-software/bonsai 0.1.2 → 0.2.0

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)).
 
@@ -261,6 +262,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 +421,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).
@@ -543,6 +568,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,