@veztraa/report-designer 0.2.8 → 0.2.10

package/README.md

@@ -2,7 +2,7 @@
 
 **[Documentation & Live Demo →](https://report-forge.veztraa.com)**
 
-Embeddable React PDF report designer component for ReportForge. Drop `<ReportDesigner />` into any React app and give your users a full visual report builder — drag-and-drop canvas, live PDF preview, undo/redo, dark mode, and more.
+Embeddable React drag-and-drop PDF report designer — a visual report builder you can drop into any React app. Give your users a Figma-like canvas for data-driven PDFs: drag-and-drop elements, live preview, undo/redo, dark mode, and `{{field}}` data bindings.
 
 Styles auto-inject on mount — no CSS import required.
 
@@ -12,7 +12,7 @@ Styles auto-inject on mount — no CSS import required.
 npm install @veztraa/report-designer
 ```
 
-## Usage
+## Quick start
 
 ```tsx
 import { ReportDesigner } from "@veztraa/report-designer";
@@ -21,20 +21,17 @@ import { ReportDesigner } from "@veztraa/report-designer";
 export default function App() {
   return (
     <div style={{ height: "100vh" }}>
-      <ReportDesigner
-        theme="light"
-        onTemplateChange={(template) => console.log(template)}
-      />
+      <ReportDesigner />
     </div>
   );
 }
 ```
 
-> The designer fills its parent container — set a `height` on the parent (e.g. `100vh` or a fixed px value).
+> The designer fills its parent — give the parent a `height` (e.g. `100vh` or a fixed px value).
 
-## Controlled Template
+## Load and save templates
 
-Load an existing template and receive updates whenever the user makes a change:
+Pass an existing template via `report` (the designer reloads whenever it changes), and capture the user's work via `toolbar.onSave`, which receives the current template when they click **Save**:
 
 ```tsx
 import { ReportDesigner } from "@veztraa/report-designer";
@@ -42,7 +39,7 @@ import type { Template } from "@veztraa/report-core";
 
 export default function ReportEditor({ saved }: { saved: Template }) {
   const handleSave = async (template: Template) => {
-    await fetch("/api/templates/save", {
+    await fetch("/api/templates", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(template),
@@ -52,9 +49,11 @@ export default function ReportEditor({ saved }: { saved: Template }) {
   return (
     <div style={{ height: "100vh" }}>
       <ReportDesigner
-        initialTemplate={saved}
+        report={saved}
+        data={{ company: { name: "Acme Corp" }, items: [] }}
         theme="light"
-        onTemplateChange={handleSave}
+        accentColor="#6c63ff"
+        toolbar={{ onSave: handleSave }}
       />
     </div>
   );
@@ -63,44 +62,78 @@ export default function ReportEditor({ saved }: { saved: Template }) {
 
 ## Props
 
+Every prop is optional — `<ReportDesigner />` is fully functional with none.
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `initialTemplate` | `Template` | blank A4 | Pre-load an existing template into the designer |
-| `theme` | `"light" \| "dark"` | `"light"` | Color scheme — flips all CSS custom properties |
-| `onTemplateChange` | `(t: Template) => void` | — | Called on every element add / move / resize / property change |
+| `report` | `Template` | blank A4 | Template JSON to load. Reloads the designer whenever it changes. |
+| `data` | `string \| object` | `"{}"` | Preview data for `{{field}}` bindings — JSON string or plain object. |
+| `onDataChange` | `(data: string) => void` | — | Fires when the user edits preview data inside the designer. |
+| `theme` | `"light" \| "dark"` | `"light"` | Controlled color theme. Sync with your app's theme toggle. |
+| `onThemeChange` | `(t: "light" \| "dark") => void` | — | Fires when the user toggles the theme inside the designer. |
+| `accentColor` | `string` | `"#6c63ff"` | Primary accent (6-digit hex). All buttons, rings, and indicators derive from it. |
+| `defaultZoom` | `number` | `1` | Initial canvas zoom (0.25–2.0). Applied once on mount. |
+| `toolbar` | `ToolbarConfig` | show all | Hide built-in actions, override Save / Load, or add custom buttons. |
+| `elements` | `ElementsConfig` | all types | Whitelist or blacklist which element types appear in the palette. |
+| `style` | `CSSProperties` | — | Inline styles for the root container. |
+| `className` | `string` | — | Extra class names for the root container. |
+
+### ToolbarConfig
+
+Passed as the `toolbar` prop. Every boolean defaults to `true` (visible).
+
+| Field | Type | Description |
+|---|---|---|
+| `hidden` | `boolean` | Hide the entire toolbar. |
+| `load` / `save` | `boolean` | Show the Load / Save buttons. |
+| `history` | `boolean` | Show Undo / Redo. |
+| `duplicate` / `delete` | `boolean` | Show Duplicate / Delete. |
+| `sections` | `boolean` | Show the Header / Body / Footer switcher. |
+| `preview` | `boolean` | Show the Preview PDF button. |
+| `theme` / `zoom` | `boolean` | Show the theme toggle / zoom controls. |
+| `onSave` | `(t: Template) => void` | Override Save — receives the current template instead of downloading JSON. |
+| `onLoad` | `() => void` | Override Load — the default opens a JSON file picker. |
+| `actions` | `ToolbarAction[]` | Custom buttons injected before the Preview button. |
+
+### ElementsConfig
+
+Passed as the `elements` prop. Use `include` (whitelist) **or** `exclude` (blacklist), not both.
+
+| Field | Type | Description |
+|---|---|---|
+| `hidden` | `boolean` | Hide the Elements palette entirely. |
+| `include` | `ElementType[]` | Only these types appear, in this order. |
+| `exclude` | `ElementType[]` | Hide these types (ignored when `include` is set). |
+
+`ElementType` is one of: `text`, `richtext`, `table`, `container`, `image`, `chart`, `barcode`, `qrcode`, `rectangle`, `line`, `pagebreak`.
 
 ## Features
 
-- Drag-and-drop canvas (div-based, no Fabric.js)
-- Snap-to-grid with alignment guides
-- Resize handles on all 8 corners/edges
-- 50-step undo/redo
-- Live PDF preview panel (debounced 400ms)
-- Dark / light theme
-- Header, body, footer sections
-- Layers panel with lock/hide/reorder
+- **Drag-and-drop canvas** — snap-to-grid with alignment guides, 8-handle resize, arrow-key nudge
+- **Live PDF preview rendered off the main thread** (Web Worker) — debounced 400ms with an adaptive loading UI, so even large multi-hundred-page reports never freeze the tab
+- **Repeating containers** (data-bound bands) with **automatic pagination** — tables, rich text, and bands flow across pages, keeping items together where they fit
+- **50-step undo / redo**
+- **Light / dark theme** and a fully customizable accent color
+- Header, body, and footer sections
+- Layers panel with lock / hide / reorder
 - Data panel for `{{field}}` preview bindings
+- **JSON-first** — the designer is a visual editor for a plain `Template` object; load with `report`, save with `toolbar.onSave`
 
-## Keyboard Shortcuts
+## Keyboard shortcuts
 
 | Shortcut | Action |
 |---|---|
 | `Del` / `Backspace` | Delete selected element |
-| `Ctrl+Z` | Undo |
-| `Ctrl+Y` | Redo |
-| `Ctrl+D` | Duplicate selected element |
+| `Ctrl/Cmd + Z` | Undo |
+| `Ctrl/Cmd + Y` (or `Ctrl/Cmd + Shift + Z`) | Redo |
+| `Ctrl/Cmd + D` | Duplicate selected element |
 | Arrow keys | Nudge 1px |
-| `Shift+Arrows` | Nudge 10px |
-| `Ctrl+Scroll` | Zoom in / out |
-| `Space+Drag` | Pan canvas |
-
-## Template Format
-
-See [`@veztraa/report-core`](https://www.npmjs.com/package/@veztraa/report-core) for the full template schema and expression syntax.
+| `Shift + Arrows` | Nudge 10px |
+| `Esc` | Close the PDF preview |
 
-## Keywords
+## Template format
 
-`pdf` `pdf-designer` `report-designer` `react` `react-component` `drag-and-drop` `pdf-editor` `report-builder` `embeddable` `canvas` `undo-redo` `dark-mode` `live-preview` `reportforge`
+See [`@veztraa/report-core`](https://www.npmjs.com/package/@veztraa/report-core) for the full template schema, element types, and expression syntax. Generate PDFs from a template on the server or in the browser with [`@veztraa/report-renderer`](https://www.npmjs.com/package/@veztraa/report-renderer).
 
 ## License