@pixldocs/canvas-renderer 0.3.3

package/README.md

@@ -0,0 +1,148 @@
+# @pixldocs/canvas-renderer
+
+React component + imperative API for rendering Pixldocs templates client-side. No server needed.
+
+## Installation
+
+```bash
+npm install @pixldocs/canvas-renderer fabric react react-dom
+```
+
+## Quick Start — React Component
+
+### Mode 1: Pre-resolved config
+
+```tsx
+import { PixldocsPreview } from '@pixldocs/canvas-renderer';
+
+function App() {
+  return (
+    <PixldocsPreview
+      config={templateConfig}
+      pageIndex={0}
+      imageProxyUrl="https://your-project.supabase.co/functions/v1/image-proxy"
+      onReady={() => console.log('Rendered!')}
+    />
+  );
+}
+```
+
+### Mode 2: Auto-resolve from database (recommended)
+
+Pass the same data you'd send to the server API — the component fetches
+the template, resolves repeatable sections, applies themes, and renders.
+
+```tsx
+import { PixldocsPreview } from '@pixldocs/canvas-renderer';
+
+function App() {
+  const sectionState = {
+    section_abc123: { full_name: 'John Doe', photo: 'https://...' },
+    section_def456: [
+      { label: 'Date of Birth', value: '1995-08-15' },
+      { label: 'Religion', value: 'Hindu' },
+    ],
+  };
+
+  return (
+    <PixldocsPreview
+      templateId="dc3fbb17-b671-47cb-a4cf-643a10251fb2"
+      formSchemaId="b04cd362-a0ef-438d-a7a3-0e8560a709ce"
+      sectionState={sectionState}
+      supabaseUrl="https://xxx.supabase.co"
+      supabaseAnonKey="eyJ..."
+      onReady={() => console.log('Rendered!')}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `TemplateConfig` | — | Pre-resolved template config (Mode 1) |
+| `templateId` | `string` | — | Template UUID (Mode 2) |
+| `formSchemaId` | `string` | — | Form schema UUID (Mode 2) |
+| `sectionState` | `SectionFormState` | — | V2 section state data (Mode 2) |
+| `themeId` | `string` | `'default'` | Theme variant ID (Mode 2) |
+| `supabaseUrl` | `string` | — | Supabase URL (Mode 2) |
+| `supabaseAnonKey` | `string` | — | Supabase anon key (Mode 2) |
+| `pageIndex` | `number` | `0` | Page index to render |
+| `zoom` | `number` | auto-fit | Zoom/scale factor |
+| `absoluteZoom` | `boolean` | `false` | Use zoom as-is without auto-fit |
+| `imageProxyUrl` | `string` | — | CORS proxy URL for external images |
+| `className` | `string` | — | CSS class for outer container |
+| `onReady` | `() => void` | — | Called when rendering completes |
+| `onError` | `(error: Error) => void` | — | Called on error |
+
+## Imperative API
+
+### Render from V2 sectionState (primary use case)
+
+Same payload format as the Pixldocs server API (`/render-from-form`):
+
+```ts
+import { PixldocsRenderer } from '@pixldocs/canvas-renderer';
+
+const renderer = new PixldocsRenderer({
+  supabaseUrl: 'https://xxx.supabase.co',
+  supabaseAnonKey: 'eyJ...',
+});
+
+const results = await renderer.renderFromForm({
+  templateId: 'dc3fbb17-b671-47cb-a4cf-643a10251fb2',
+  formSchemaId: 'b04cd362-a0ef-438d-a7a3-0e8560a709ce',
+  sectionState: {
+    section_abc: { full_name: 'John' },
+    section_def: [{ label: 'DOB', value: '1995-08-15' }],
+  },
+  themeId: 'default',
+});
+
+// results is an array of { dataUrl, width, height } for each page
+for (const page of results) {
+  console.log(page.dataUrl); // data:image/png;base64,...
+}
+```
+
+### Render a pre-resolved config
+
+```ts
+const { dataUrl } = await renderer.render(templateConfig);
+const allPages = await renderer.renderAllPages(templateConfig);
+```
+
+### Render by template ID (simple flat data)
+
+```ts
+const result = await renderer.renderById('template-uuid', { name: 'John' });
+```
+
+## Data Resolution Utilities
+
+```ts
+import { resolveFromForm, resolveTemplateData } from '@pixldocs/canvas-renderer';
+
+// V2: resolve from sectionState (same as server API)
+const { config } = await resolveFromForm({
+  templateId: 'uuid',
+  formSchemaId: 'uuid',
+  sectionState: { ... },
+  supabaseUrl: '...', supabaseAnonKey: '...',
+});
+
+// Legacy: resolve with flat formData
+const { config } = await resolveTemplateData({
+  templateId: 'uuid',
+  formData: { name: 'Jane' },
+  supabaseUrl: '...', supabaseAnonKey: '...',
+});
+```
+
+## Peer Dependencies
+
+- `fabric` ^6.0.0
+- `react` ^18.0.0 || ^19.0.0
+- `react-dom` ^18.0.0 || ^19.0.0