@pebble-software/bonsai 0.0.4 → 0.0.5

package/README.md

@@ -1,7 +1,15 @@
 # @pebble-software/bonsai
 
+[![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)
+
+> ⚠️ **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!
+
 The React runtime that turns a validated Bonsai configuration into a fully interactive, styled experience. It's built for UI that has to be delivered remotely (email, SMS, embedded experiences) but rendered locally with real React components, consistent styling, and predictable data flow.
 
+Bonsai is the rendering engine behind [Pebble Bonsai](https://github.com/PebbleSoftwareInc/pebble-bonsai), an open-source form and signature service — but the renderer is useful anywhere you need to ship UI as data: define a screen as a JSON template, bind it to your data with `{{ }}` expressions, and let one component render it on the server (SSR, PDF) or in the browser (fully interactive).
+
 ## Table of contents
 
 - [Features](#features)
@@ -20,26 +28,31 @@ The React runtime that turns a validated Bonsai configuration into a fully inter
 
 ## Features
 
-- **Schema-driven UI** — every screen is a Zod-validated `Config` tree from `@bonsai/schemas`, so the renderer only ever processes known-safe structures.
-- **Universal rendering** — one component (`Bonsai`) picks server (SSR) or client (interactive) rendering automatically based on environment.
+- **Schema-driven UI** — every screen is a Zod-validated `Config` tree, so the renderer only ever processes known-safe structures.
+- **Universal rendering** — one component (`Bonsai`) picks server (SSR) or client (interactive) rendering automatically based on environment, with `web`, `pdf`, and `preview` render modes.
 - **Composable components** — schema component identifiers map to real React implementations via a `componentMap`, so the same schema can target different component sets.
 - **Isolated per-instance state** — each mounted `Bonsai` tree owns its own `valtio` store, scoped via React context. Nothing about which data renders lives in shared or module-level state.
 - **Fine-grained reactivity** — every leaf node reads the store itself and evaluates only its own bindings, so editing one field re-renders just that field and whatever depends on it.
 - **Structural nodes** — `each` and `if` handle looping and conditional rendering directly in the schema, with two-way binding preserved inside loops.
 - **Sandboxed expression language** — `{{ }}` bindings are evaluated by a small, fixed-surface formula language, never executable JavaScript.
-- **Tailwind CSS v4** theme with a `bonsai:` prefix to avoid collisions with a host app's own styles.
+- **Tailwind CSS v4 design system** — a themeable token set (colors, typography, spacing, shadows) drives every component, and templates can layer on any Tailwind utility via `className`.
 
 ## Installation
 
 ```bash
+npm install @pebble-software/bonsai
+# or
 pnpm add @pebble-software/bonsai
+# or
+yarn add @pebble-software/bonsai
 ```
 
-Peer expectations:
+Peer dependencies:
 
-- React 18 or newer
+- `react` and `react-dom` 18 or 19
 - A bundler that understands ES modules (Vite, Next, Rspack, etc.)
-- Tailwind CSS support if you intend to merge or override Bonsai styles
+
+> **Preview note:** while the package is pre-1.0, pin an exact version (`npm install @pebble-software/bonsai --save-exact`) — minor releases may contain breaking changes.
 
 ### Working in this monorepo
 
@@ -48,7 +61,7 @@ pnpm install
 pnpm --filter @pebble-software/bonsai run build
 ```
 
-The build script compiles the shared workspaces (`@bonsai/constants`, `@bonsai/schemas`) before bundling this package with Vite.
+The shared workspaces (`@bonsai/constants`, `@bonsai/schemas`) are aliased to their sources and bundled directly into `dist/` by Vite, so downstream consumers only ever install this one package.
 
 ## Quick start
 
@@ -57,7 +70,7 @@ import { Bonsai, type Config } from "@pebble-software/bonsai";
 
 const template: Config = {
   type: "card",
-  args: { className: "bonsai:p-6 bonsai:flex bonsai:flex-col bonsai:gap-4" },
+  args: { className: "p-6 flex flex-col gap-4" },
   children: [
     {
       type: "label",
@@ -98,7 +111,7 @@ export function Example() {
 | `useUpdateData()` | hook | Returns an `updateData(path, value)` function bound to the nearest `Bonsai` instance's store. Must be called from a component mounted inside it. |
 | `componentMap` | object | Maps schema component identifiers to React implementations. |
 | `controlledInputMap` | object | Defines how specific component types behave as controlled inputs (value prop, change handler, value extractor). |
-| `Config` | type | Runtime type describing a Bonsai node, re-exported from `@bonsai/schemas`. |
+| `Config` | type | Runtime type describing a Bonsai node. |
 | `SignatureProps` | type | Props contract for the built-in signature capture component. |
 
 `Bonsai` accepts:
@@ -114,11 +127,14 @@ interface BonsaiProps {
 }
 ```
 
+- `render: "web"` (default) mounts the tree inside a `<form>` whose submit handler POSTs the captured data to `captureUrl`. `"preview"` renders the same form UI flagged with `data-mode="preview"` for host styling. `"pdf"` renders a plain `<div>` wrapper with no form — the layout used for print/PDF output.
+- `status` other than `"pending"` disables capture: the submit handler no-ops instead of POSTing.
+
 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.
 
 ## Configuration schema
 
-The schema is defined in `@bonsai/schemas/src/bonsai.schema.ts` and exported as `Config`.
+The schema is defined in [`library/schemas/src/bonsai.schema.ts`](https://github.com/PebbleSoftwareInc/pebble-bonsai/blob/main/library/schemas/src/bonsai.schema.ts) and exported as `Config`.
 
 - **Node shape**: each node is either a string literal (rendered directly, and itself eligible for `{{ }}` bindings) or an object with:
   - `type`: a value from `COMPONENT` (see [Component reference](#component-reference)), including the structural `each` and `if` types (see [Structural nodes](#structural-nodes-each--if)).
@@ -135,18 +151,21 @@ Example node:
   "args": {
     "id": "terms",
     "checked": "{{agreements.terms}}",
-    "className": "bonsai:mt-4"
+    "className": "mt-4"
   },
   "children": ["I agree to the terms"]
 }
 ```
 
+Complete example templates live in the repo's [`examples/`](https://github.com/PebbleSoftwareInc/pebble-bonsai/tree/main/examples) directory, including a kitchen-sink template that exercises every component type.
+
 ## Dynamic data binding
 
 - Use `{{ }}` to declare bindings. A binding must span the *entire* string value — `"{{a}}"` is evaluated, `"{{a}} of {{b}}"` is not (put each placeholder in its own child/string instead). Whitespace inside `{{ }}` is trimmed automatically.
 - Paths support dot notation (`user.email`) and array indexing (`addresses[0].street`).
 - Missing keys resolve to `undefined`; use the `default(value, fallback)` helper for a fallback inline, or handle defaults in host data.
 - Any `args` prop or string child can contain a binding.
+- Besides your own `data`, the instance's top-level state fields — `status`, `expiry`, and `submitting` — are readable from bindings too (e.g. an `if` on `{{submitting}}`).
 - Inside an `each` row, an identifier resolves against the loop alias first (e.g. `applicant.name`), then falls back to the surrounding data for anything the alias doesn't shadow (e.g. `orgName` from outside the loop) — see [Structural nodes](#structural-nodes-each--if).
 - On the client, evaluating a node's bindings is also what subscribes that node to the store — see [Controlled inputs & state](#controlled-inputs--state).
 
@@ -263,7 +282,7 @@ Allowlisted methods: `map`, `filter`, `some`, `every`, `find`. Anything else —
 
 ## Component reference
 
-The full, authoritative list of component types is the `COMPONENT` enum in `@bonsai/constants` (`library/constants/src/components.ts`) — `componentMap` (`src/lib/ui/registry.ts`) has an entry for every value in it.
+The full, authoritative list of component types is the `COMPONENT` enum in `@bonsai/constants` ([`library/constants/src/components.ts`](https://github.com/PebbleSoftwareInc/pebble-bonsai/blob/main/library/constants/src/components.ts)) — `componentMap` (`src/lib/ui/registry.ts`) has an entry for every value in it.
 
 | Category | Schema types |
 | --- | --- |
@@ -280,10 +299,12 @@ Controlled inputs (registered in `controlledInputMap` — `input`, `otp`, `check
 
 ## Styling
 
-- Tailwind CSS v4 is bundled with a `bonsai:` prefix to avoid class collisions. Host applications can safely include their own Tailwind build.
-- `src/index.css` registers all theme tokens (colors, spacing, shadows, fonts) and safelists commonly generated utility classes.
-- Custom fonts (e.g. for signatures) are declared locally and loaded via `@font-face`.
-- To override styling, supply a `className` through the schema or wrap Bonsai components in host containers.
+Bonsai is styled with **Tailwind CSS v4**. Components emit plain Tailwind utility classes, and templates can pass any additional utilities through `className` on any node.
+
+- The design system lives in [`src/index.css`](https://github.com/PebbleSoftwareInc/pebble-bonsai/blob/main/apps/bonsai/src/index.css): an `@theme` token set (an OKLCH color palette with swappable accent colors, typography, shadows) plus base and utility layers, custom fonts (Sora, Fredoka, and Great Vibes for signatures) loaded via `@font-face`, and style overrides for the embedded map (MapLibre) and chart (Recharts) widgets.
+- 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.
+- **Getting the stylesheet**: inside the Pebble Bonsai platform, CSS is compiled per-template at form-creation time — only the classes a template actually uses are emitted. When consuming this package standalone, compile the styles with your own Tailwind v4 build: import the Bonsai theme and add the package (and your template sources) as content via `@source` so the utilities your templates reference are generated. A prebuilt, ready-to-import stylesheet export is planned while the packaging story stabilizes during the preview period.
+- **Theming**: the theme is token-driven — redefine the CSS variables (e.g. `--color-main`, `--font-heading`) after the theme to restyle every component at once, or target `.bonsai-root` descendants for finer overrides.
 
 ## Extending Bonsai
 
@@ -295,14 +316,17 @@ Controlled inputs (registered in `controlledInputMap` — `input`, `otp`, `check
 2. **Custom data handling**:
    - Use `useUpdateData()` from a component mounted inside a `Bonsai` instance's subtree for simple mutations.
 3. **Alternate styling**:
-   - Tailwind tokens can be overridden by redefining CSS variables before mounting Bonsai.
+   - Redefine the theme's CSS variables before mounting Bonsai — see [Styling](#styling).
 
 ## Development
 
+Issues and pull requests are welcome at [PebbleSoftwareInc/pebble-bonsai](https://github.com/PebbleSoftwareInc/pebble-bonsai). This package lives at `apps/bonsai` in the monorepo.
+
 ```bash
-pnpm lint   # Static analysis using ESLint
-pnpm test   # Run the test suite (vitest)
-pnpm build  # Builds dependencies then bundles dist/ via Vite
+pnpm lint        # Static analysis using ESLint
+pnpm test        # Run the test suite (vitest)
+pnpm type-check  # TypeScript without emit
+pnpm build       # Bundles dist/ (ESM + type declarations) via Vite
 ```
 
-`dist/` contains the ESM bundle and TypeScript declarations consumed by downstream applications.
+`dist/` contains the ESM bundle and TypeScript declarations consumed by downstream applications. The shared `@bonsai/constants` and `@bonsai/schemas` workspaces are bundled in, so the published package has no workspace dependencies.

package/dist/index.d.ts

@@ -1,5 +1,9 @@
+import { ComponentType } from 'react';
 import { JSX } from 'react';
 import { z } from 'zod';
+import { ZodType } from 'zod';
+
+export declare function assertNoFailingDrift(issues: DriftIssue[]): void;
 
 export declare function Bonsai(props: BonsaiProps): JSX.Element;
 
@@ -10,8 +14,22 @@ declare interface BonsaiProps {
     data?: any;
     status?: "pending" | "captured" | "completed" | "error" | "revoked";
     render?: "web" | "pdf" | "preview";
+    registry?: BonsaiRegistry;
+}
+
+export declare interface BonsaiRegistry {
+    id: string;
+    version: string;
+    namespace?: string;
+    manifestHash?: string;
+    components: Record<string, ComponentDefinition>;
+    fallback?: RegistryFallback;
 }
 
+export declare function checkArtifactDrift(input: DriftCheckInput): DriftIssue[];
+
+export declare function clearManifestCache(): void;
+
 declare enum COMPONENT {
     A = "a",
     P = "p",
@@ -72,11 +90,34 @@ declare enum COMPONENT {
     IF = "if",
 }
 
+export declare type ComponentCapability = "children" | "bindings" | "events" | "formField" | "ssr" | "pdf";
+
+export declare interface ComponentDefinition {
+    component: ComponentType<any> | string;
+    propsSchema?: ZodType<any>;
+    capabilities?: ComponentCapability[];
+    controlled?: ControlledFieldSpec | Record<string, ControlledFieldSpec>;
+    assets?: {
+        css?: string[];
+        fonts?: string[];
+    };
+}
+
 export declare const componentMap: Record<COMPONENT[number], any>;
 
-export declare const Config = Node;
+export declare function composePropsSchema(baseSchema: z.ZodType<unknown> | undefined, tenantSchema: z.ZodType<unknown> | undefined): z.ZodType<unknown> | undefined;
+
+export declare function computeManifestHash(raw: string): Promise<string>;
+
+export declare const Config = pebbleTemplateSchema.Node;
+
+export declare type Config = z.infer<typeof pebbleTemplateSchema.Node>;
 
-export declare type Config = z.infer<typeof Node_2>;
+export declare interface ControlledFieldSpec {
+    valueProp: string;
+    changeProp: string;
+    extract: (eventOrValue: unknown) => unknown;
+}
 
 declare interface ControlledInput {
     valueProp: string;
@@ -86,7 +127,175 @@ declare interface ControlledInput {
 
 export declare const controlledInputMap: Record<COMPONENT[number], Record<string, ControlledInput> | ControlledInput>;
 
-declare const Node_2: z.ZodType<any> = z.lazy(() => z.union([z.string(), ComponentNode]));
+export declare function defineBonsaiRegistry(registry: BonsaiRegistry): BonsaiRegistry;
+
+export declare function defineComponent(def: ComponentDefinition): ComponentDefinition;
+
+export declare interface DriftCheckInput {
+    artifactRegistries: RegistrySource[];
+    configRegistries: RegistrySource[];
+    artifactBaseUiVersion: string;
+    installedBaseUiVersion: string;
+}
+
+export declare interface DriftIssue {
+    check: "stale-artifact" | "baseui-drift";
+    level: "warn" | "fail";
+    message: string;
+}
+
+export declare const EXTRACTOR_ALLOWLIST: Record<string, (eventOrValue: unknown) => unknown>;
+
+/**
+ * Compiles the JSON Schema subset a manifest's `propsSchema` is allowed to use into a
+ * Zod validator (REGISTRY_SPIKE.md, "Registry manifests": "JSON Schema on the wire;
+ * compiled to a Zod validator at load"). Deliberately a subset, not a general JSON
+ * Schema implementation — enough to express prop narrowing (type, enum, required,
+ * string/number bounds), which is the only thing a Case A manifest is allowed to do
+ * to a prop schema in the first place.
+ */
+export declare type JsonSchema = Record<string, unknown>;
+
+export declare function jsonSchemaToZod(schema: JsonSchema): z.ZodType<unknown>;
+
+export declare interface LoadManifestOptions extends ResolveManifestOptions {
+    allowedOrigins?: string[];
+    fetchImpl?: typeof fetch;
+}
+
+export declare function loadRegistryManifest(source: RegistryManifest | string, options: LoadManifestOptions): Promise<BonsaiRegistry>;
+
+export declare type ManifestComponent = z.infer<typeof ManifestComponentSchema>;
+
+declare const ManifestComponentSchema: z.ZodObject<{
+    name: z.ZodString;
+    canonicalName: z.ZodOptional<z.ZodString>;
+    entry: z.ZodString;
+    propsSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        children: "children";
+        pdf: "pdf";
+        bindings: "bindings";
+        events: "events";
+        formField: "formField";
+        ssr: "ssr";
+    }>>>;
+    controlled: z.ZodOptional<z.ZodObject<{
+        valueProp: z.ZodString;
+        changeProp: z.ZodString;
+        extract: z.ZodString;
+    }, z.core.$strict>>;
+    css: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+
+export declare class ManifestLoadError extends Error {
+    constructor(message: string);
+}
+
+export declare function mergeGeneratedWithOverrides(generated: ObjectPropsSchema | undefined, overrides: Partial<ObjectPropsSchema> | undefined): ObjectPropsSchema;
+
+export declare interface ObjectPropsSchema {
+    type?: "object";
+    properties: Record<string, JsonSchema>;
+    required?: string[];
+}
+
+export declare const pebbleRegistry: BonsaiRegistry;
+
+declare const pebbleTemplateSchema = createTemplateSchema(PEBBLE_COMPONENT_SCHEMAS);
+
+export declare type PinResolution = {
+    action: "render";
+    reason: "no-pin";
+} | {
+    action: "render";
+    reason: "match";
+} | {
+    action: "render";
+    reason: "version-skew";
+    warning: string;
+} | {
+    action: "fail";
+    reason: "id-mismatch";
+    error: string;
+};
+
+declare type RegistryFallback = "error" | "div" | ComponentType<any>;
+
+export declare interface RegistryIdentity {
+    id: string;
+    version: string;
+    manifestHash?: string;
+}
+
+export declare type RegistryManifest = z.infer<typeof RegistryManifestSchema>;
+
+export declare const RegistryManifestSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    namespace: z.ZodOptional<z.ZodString>;
+    version: z.ZodString;
+    engine: z.ZodObject<{
+        name: z.ZodLiteral<"bonsai">;
+        api: z.ZodString;
+    }, z.core.$strict>;
+    components: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        canonicalName: z.ZodOptional<z.ZodString>;
+        entry: z.ZodString;
+        propsSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            children: "children";
+            pdf: "pdf";
+            bindings: "bindings";
+            events: "events";
+            formField: "formField";
+            ssr: "ssr";
+        }>>>;
+        controlled: z.ZodOptional<z.ZodObject<{
+            valueProp: z.ZodString;
+            changeProp: z.ZodString;
+            extract: z.ZodString;
+        }, z.core.$strict>>;
+        css: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    integrity: z.ZodOptional<z.ZodObject<{
+        algorithm: z.ZodLiteral<"sha256">;
+        manifestHash: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+export declare interface RegistrySource {
+    url: string;
+    registryHash: string;
+}
+
+export declare interface RegistryValidationError {
+    path: string;
+    message: string;
+    componentType?: string;
+}
+
+export declare interface RegistryValidationResult {
+    valid: boolean;
+    errors: RegistryValidationError[];
+    warnings: string[];
+}
+
+export declare function resolveManifest(manifest: RegistryManifest, options: ResolveManifestOptions): BonsaiRegistry;
+
+export declare interface ResolveManifestOptions {
+    base: BonsaiRegistry;
+    engineApi?: string;
+    maxComponents?: number;
+    maxManifestBytes?: number;
+    rawManifestSize?: number;
+    manifestHash?: string;
+}
+
+export declare function resolveRegistryPin(pin: RegistryIdentity | undefined, registry: Pick<BonsaiRegistry, "id" | "version"> & {
+    manifestHash?: string;
+}): PinResolution;
 
 export declare type SignatureProps = {
     value?: string | null;
@@ -97,4 +306,11 @@ export declare type SignatureProps = {
 
 export declare function useUpdateData(): (path: string, value: any) => void;
 
+export declare function validateTemplate(template: Config, registry: BonsaiRegistry, options?: ValidateTemplateOptions): RegistryValidationResult;
+
+export declare interface ValidateTemplateOptions {
+    mode?: "web" | "pdf";
+    pin?: RegistryIdentity;
+}
+
 export { }