@bambamboole/pdf-ua-template-builder 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Christlieb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @bambamboole/pdf-ua-template-builder
+
+An embeddable React template builder for the
+[pdf-ua-api](https://github.com/bambamboole/pdf-ua-api) PDF/UA renderer.
+
+- Hybrid block cards that expand inline for editing
+- Page-format aware canvas (A3/A4/A5/A6/Letter/Legal/Tabloid + orientation)
+- Repeated footer area and page-number controls
+- Animated drag-and-drop with full keyboard accessibility (powered by dnd-kit)
+- Lightweight neutral UI built around CSS custom properties
+
+## Install
+
+```bash
+npm install @bambamboole/pdf-ua-template-builder
+```
+
+React 18 or 19 is required as a peer dependency:
+
+```bash
+npm install react react-dom
+```
+
+## Usage
+
+```tsx
+import { TemplateBuilder, createInvoiceExample } from "@bambamboole/pdf-ua-template-builder";
+import "@bambamboole/pdf-ua-template-builder/style.css";
+
+const example = createInvoiceExample();
+
+export default function App() {
+  return (
+    <TemplateBuilder
+      apiUrl="http://localhost:8080"
+      initialTemplate={example.template}
+      initialData={example.data}
+      onChange={(template, data) => console.log("changed", template, data)}
+      onRendered={(pdf) => console.log("rendered pdf blob", pdf)}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop              | Type                                                                | Description                                                                  |
+| ----------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `apiUrl`          | `string`                                                            | Base URL of a running `pdf-ua-api`. Defaults to `""` (relative URL / proxy). |
+| `initialTemplate` | `Template`                                                          | Template loaded on first render.                                             |
+| `initialData`     | `Record<string, unknown>`                                           | Runtime data keyed by block id (table rows, dynamic key-value overrides).   |
+| `onChange`        | `(template: Template, data: Record<string, unknown>) => void`       | Fires on every edit.                                                         |
+| `onRendered`     | `(pdf: Blob) => void`                                               | Fires after a successful render.                                             |
+| `className`      | `string`                                                            | Class appended to the root element.                                          |
+
+## Backend
+
+The component talks to a `pdf-ua-api` instance via:
+
+- `GET {apiUrl}/schema` — for block metadata used by the palette and forms.
+- `POST {apiUrl}/render/template` — to render the current template + data into a PDF blob.
+
+See the [pdf-ua-api](https://github.com/bambamboole/pdf-ua-api) repository for
+installation and configuration. The component does **not** render PDFs in the
+browser — the backend owns the PDF/UA-accurate rendering pipeline.
+
+## Helpers
+
+The package also exports framework-agnostic utilities:
+
+```ts
+import {
+  pageSizeForFormat,   // [widthMm, heightMm] for a PageFormat + Orientation
+  mmToPx,              // mm → CSS px at 96 DPI
+  createEditorModel,   // ingest a Template into an editor model
+  serializeTemplate,   // emit a Template from an editor model
+  getPageSize, setPageSize,
+  getFooterRepeat, setFooterRepeat,
+  getPageNumbers, setPageNumbers,
+} from "@bambamboole/pdf-ua-template-builder";
+```
+
+## Local development
+
+```bash
+npm install
+npm run dev          # runs the playground app on http://localhost:5174
+npm run build        # produces the npm package in dist/
+npm run build:app    # produces the playground build
+npm run test         # vitest
+npm run typecheck    # tsc --noEmit
+npm run lint         # oxlint
+```
+
+`npm run dev` proxies `/schema` and `/render/*` to a local `pdf-ua-api`
+(default: `http://localhost:8080`, override with `PDF_UA_API_PROXY_URL`).
+
+## License
+
+MIT

package/dist/api/pdfUaApi.d.ts

@@ -0,0 +1,10 @@
+import { RenderOptions, Template, TemplateData, TemplateSchemaResponse } from '../types/template';
+interface RenderTemplateRequest {
+    template: Template;
+    data?: TemplateData;
+    options?: RenderOptions;
+}
+export declare function resolveDefaultApiUrl(configuredApiUrl?: string): string;
+export declare function fetchTemplateSchema(baseUrl: string): Promise<TemplateSchemaResponse>;
+export declare function renderTemplatePdf(baseUrl: string, request: RenderTemplateRequest): Promise<Blob>;
+export {};

package/dist/builder/TemplateBuilder.d.ts

@@ -0,0 +1,29 @@
+import { UniqueIdentifier } from '@dnd-kit/core';
+import { Template } from '../types/generated/template';
+import { TemplateData } from '../types/template';
+import { EditorArea, EditorModel } from './state/editorModel';
+export interface TemplateBuilderProps {
+    /** Base URL of a running pdf-ua-api instance. Defaults to "" (relative URLs / proxy). */
+    apiUrl?: string;
+    /** Template loaded into the editor on first render. */
+    initialTemplate?: Template;
+    /** Runtime data keyed by block id (table rows, dynamic key-value overrides). */
+    initialData?: TemplateData;
+    /** Fires whenever the user edits the template or its runtime data. */
+    onChange?: (template: Template, data: TemplateData) => void;
+    /** Fires after a successful render with the produced PDF blob. */
+    onRendered?: (pdf: Blob) => void;
+    /** Optional className appended to the root element. */
+    className?: string;
+}
+interface DragData {
+    source?: string;
+    type?: string;
+    rowUid?: string;
+    blockUid?: string;
+    area?: EditorArea;
+}
+export declare function TemplateBuilder({ apiUrl: initialApiUrlProp, initialTemplate, initialData, onChange, onRendered, className, }?: TemplateBuilderProps): import("react/jsx-runtime").JSX.Element;
+export declare function getRowIndex(model: EditorModel, overId: UniqueIdentifier | undefined, overData: DragData): number | null;
+export declare function createNextBlockId(model: EditorModel, blockType: string): string;
+export {};

package/dist/builder/blocks/BlockPalette.d.ts

@@ -0,0 +1,5 @@
+export interface BlockPaletteProps {
+    blockTypes: string[];
+    onAdd?: (type: string) => void;
+}
+export declare function BlockPalette({ blockTypes, onAdd }: BlockPaletteProps): import("react/jsx-runtime").JSX.Element;

package/dist/builder/blocks/blockChrome.d.ts

@@ -0,0 +1,7 @@
+import { Block } from '../../types/generated/template';
+export interface BlockChrome {
+    chip: string;
+    label: string;
+}
+export declare function getBlockChrome(type: string): BlockChrome;
+export declare function getBlockSummary(block: Block): string;

package/dist/builder/canvas/BlockCardPreview.d.ts

@@ -0,0 +1,6 @@
+export interface BlockCardPreviewProps {
+    type: string;
+    summary?: string;
+    prefix?: string;
+}
+export declare function BlockCardPreview({ type, summary, prefix }: BlockCardPreviewProps): import("react/jsx-runtime").JSX.Element;

package/dist/builder/canvas/BuilderCanvas.d.ts

@@ -0,0 +1,17 @@
+import { Block, Orientation, PageFormat } from '../../types/generated/template';
+import { TemplateSchemaResponse } from '../../types/template';
+import { EditorModel, PageNumbersValue } from '../state/editorModel';
+export interface BuilderCanvasProps {
+    schema: TemplateSchemaResponse;
+    model: EditorModel;
+    format: PageFormat;
+    orientation: Orientation;
+    footerRepeat: boolean;
+    pageNumbers: PageNumbersValue;
+    onChangeBlock: (blockUid: string, block: Block) => void;
+    onRemoveBlock: (blockUid: string) => void;
+    onSetRowWidths: (rowUid: string, widths: string[]) => void;
+    onToggleFooterRepeat: (repeat: boolean) => void;
+    onChangePageNumbers: (value: PageNumbersValue) => void;
+}
+export declare function BuilderCanvas({ schema, model, format, orientation, footerRepeat, pageNumbers, onChangeBlock, onRemoveBlock, onSetRowWidths, onToggleFooterRepeat, onChangePageNumbers, }: BuilderCanvasProps): import("react/jsx-runtime").JSX.Element;

package/dist/builder/canvas/ColumnResizer.d.ts

@@ -0,0 +1,9 @@
+import { RefObject } from 'react';
+export interface ColumnResizerProps {
+    widths: readonly string[] | null;
+    count: number;
+    leftIndex: number;
+    containerRef: RefObject<HTMLElement | null>;
+    onResize: (widths: string[]) => void;
+}
+export declare function ColumnResizer({ widths, count, leftIndex, containerRef, onResize, }: ColumnResizerProps): import("react/jsx-runtime").JSX.Element;

package/dist/builder/canvas/PageSheet.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react';
+import { Orientation, PageFormat } from '../../types/generated/template';
+export interface PageSheetProps {
+    format: PageFormat;
+    orientation: Orientation;
+    children: ReactNode;
+}
+export declare function PageSheet({ format, orientation, children }: PageSheetProps): import("react/jsx-runtime").JSX.Element;

package/dist/builder/canvas/SortableBlock.d.ts

@@ -0,0 +1,14 @@
+import { CSSProperties } from 'react';
+import { EditorArea, EditorBlock } from '../state/editorModel';
+import { Block } from '../../types/generated/template';
+import { TemplateSchemaResponse } from '../../types/template';
+export interface SortableBlockProps {
+    rowUid: string;
+    area: EditorArea;
+    editorBlock: EditorBlock;
+    schema: TemplateSchemaResponse;
+    onChangeBlock: (blockUid: string, block: Block) => void;
+    onRemoveBlock: (blockUid: string) => void;
+    style?: CSSProperties;
+}
+export declare function SortableBlock({ rowUid, area, editorBlock, schema, onChangeBlock, onRemoveBlock, style: layoutStyle, }: SortableBlockProps): import("react/jsx-runtime").JSX.Element;

package/dist/builder/canvas/columns.d.ts

@@ -0,0 +1,4 @@
+export declare function parseWidths(widths: readonly (number | string)[] | null | undefined, count: number): number[];
+export declare function formatWidths(widths: readonly number[]): string[];
+export declare function gridTemplateForWidths(widths: readonly string[] | null | undefined, count: number): string | null;
+export declare function setBoundary(widths: readonly number[], leftIndex: number, leftPercent: number): number[];

package/dist/builder/forms/InlineBlockForm.d.ts

@@ -0,0 +1,9 @@
+import { Block } from '../../types/generated/template';
+import { JsonSchemaObject } from '../schema/schemaAdapter';
+export interface InlineBlockFormProps {
+    block: Block;
+    fieldSchema: JsonSchemaObject;
+    configSchema?: JsonSchemaObject;
+    onChange: (block: Block) => void;
+}
+export declare function InlineBlockForm({ block, fieldSchema, configSchema, onChange, }: InlineBlockFormProps): import("react/jsx-runtime").JSX.Element;

package/dist/builder/lib/displayScale.d.ts

@@ -0,0 +1 @@
+export declare function mmToPx(mm: number): number;

package/dist/builder/lib/pageSizes.d.ts

@@ -0,0 +1,3 @@
+import { Orientation, PageFormat } from '../../types/generated/template';
+export declare const PAGE_SIZES_MM: Record<PageFormat, [number, number]>;
+export declare function pageSizeForFormat(format: PageFormat | string | undefined, orientation?: Orientation | string | undefined): [number, number];

package/dist/builder/pdf/PdfPane.d.ts

@@ -0,0 +1,8 @@
+export interface PdfPaneProps {
+    pdfUrl: string | null;
+    error: string | null;
+    loading: boolean;
+    onRender?: () => void;
+    renderDisabled?: boolean;
+}
+export declare function PdfPane({ pdfUrl, error, loading, onRender, renderDisabled }: PdfPaneProps): import("react/jsx-runtime").JSX.Element;

package/dist/builder/schema/invoiceExample.d.ts

@@ -0,0 +1,8 @@
+import { Template } from '../../types/generated/template';
+export type TableRow = Record<string, string>;
+export type InvoiceData = Record<string, TableRow[]>;
+export interface InvoiceExample {
+    template: Template;
+    data: InvoiceData;
+}
+export declare function createInvoiceExample(): InvoiceExample;

package/dist/builder/schema/schemaAdapter.d.ts

@@ -0,0 +1,13 @@
+import { Block } from '../../types/generated/template';
+import { TemplateSchemaMetadata } from '../../types/template';
+export type JsonSchemaValue = string | number | boolean | null | JsonSchemaObject | JsonSchemaValue[];
+export interface JsonSchemaObject {
+    [key: string]: unknown;
+}
+export declare function getSchemaMetadata(schema: JsonSchemaObject): TemplateSchemaMetadata;
+export declare function resolveRef(schema: JsonSchemaObject, ref: string): JsonSchemaObject;
+export declare function getBlockTypes(schema: JsonSchemaObject): string[];
+export declare function getBlockDefinition(schema: JsonSchemaObject, blockType: string): JsonSchemaObject | undefined;
+export declare function getBlockFieldSchema(schema: JsonSchemaObject, blockType: string): JsonSchemaObject;
+export declare function getBlockConfigSchema(schema: JsonSchemaObject, blockType: string): JsonSchemaObject | undefined;
+export declare function createDefaultBlock(schema: JsonSchemaObject, blockType: string, id: string): Block;

package/dist/builder/state/editorModel.d.ts

@@ -0,0 +1,36 @@
+import { Align, Block, CustomPageSize, Orientation, PageFormat, Template } from '../../types/generated/template';
+export type EditorArea = "body" | "footer";
+export type PageNumbersValue = "disabled" | Align;
+export interface ResolvedPageSize {
+    format: PageFormat;
+    orientation: Orientation;
+    custom: CustomPageSize | null;
+}
+export interface EditorBlock {
+    uid: string;
+    block: Block;
+}
+export interface EditorRow {
+    uid: string;
+    blocks: EditorBlock[];
+}
+export interface EditorModel {
+    template: Omit<Template, "rows">;
+    rows: EditorRow[];
+    footerRows: EditorRow[];
+}
+export declare function createEditorModel(template: Template): EditorModel;
+export declare function serializeTemplate(model: EditorModel): Template;
+export declare function addBlockToNewRow(model: EditorModel, block: Block, area?: EditorArea): EditorModel;
+export declare function addBlockToRow(model: EditorModel, rowUid: string, block: Block, index: number): EditorModel;
+export declare function removeBlock(model: EditorModel, blockUid: string): EditorModel;
+export declare function moveBlock(model: EditorModel, blockUid: string, rowUid: string | null, index: number, area?: EditorArea): EditorModel;
+export declare function moveRow(model: EditorModel, rowUid: string, index: number): EditorModel;
+export declare function updateBlock(model: EditorModel, blockUid: string, block: Block): EditorModel;
+export declare function getPageSize(model: EditorModel): ResolvedPageSize;
+export declare function setPageSize(model: EditorModel, format: PageFormat, orientation: Orientation): EditorModel;
+export declare function setRowWidths(model: EditorModel, rowUid: string, widths: string[]): EditorModel;
+export declare function getFooterRepeat(model: EditorModel): boolean;
+export declare function setFooterRepeat(model: EditorModel, repeat: boolean): EditorModel;
+export declare function getPageNumbers(model: EditorModel): PageNumbersValue;
+export declare function setPageNumbers(model: EditorModel, value: PageNumbersValue): EditorModel;

package/dist/builder/topbar/BuilderTopbar.d.ts

@@ -0,0 +1,17 @@
+import { Orientation, PageFormat } from '../../types/generated/template';
+export interface BuilderTopbarProps {
+    format: PageFormat;
+    orientation: Orientation;
+    onChangeFormat: (format: PageFormat) => void;
+    onChangeOrientation: (orientation: Orientation) => void;
+    apiUrl: string;
+    onApiUrlChange: (value: string) => void;
+    onLoadSchema: () => void;
+    schemaLoading: boolean;
+    onLoadExample: () => void;
+    exampleDisabled: boolean;
+    onRender: () => void;
+    renderDisabled: boolean;
+    rendering: boolean;
+}
+export declare function BuilderTopbar({ format, orientation, onChangeFormat, onChangeOrientation, apiUrl, onApiUrlChange, onLoadSchema, schemaLoading, onLoadExample, exampleDisabled, onRender, renderDisabled, rendering, }: BuilderTopbarProps): import("react/jsx-runtime").JSX.Element;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { TemplateBuilder } from './builder/TemplateBuilder';
+export type { TemplateBuilderProps } from './builder/TemplateBuilder';
+export { createInvoiceExample } from './builder/schema/invoiceExample';
+export type { InvoiceExample, InvoiceData, TableRow } from './builder/schema/invoiceExample';
+export { PAGE_SIZES_MM, pageSizeForFormat } from './builder/lib/pageSizes';
+export { mmToPx } from './builder/lib/displayScale';
+export { createEditorModel, serializeTemplate, getPageSize, setPageSize, getFooterRepeat, setFooterRepeat, getPageNumbers, setPageNumbers, } from './builder/state/editorModel';
+export type { EditorArea, EditorBlock, EditorModel, EditorRow, PageNumbersValue, ResolvedPageSize, } from './builder/state/editorModel';
+export { fetchTemplateSchema, renderTemplatePdf, resolveDefaultApiUrl } from './api/pdfUaApi';
+export type { TemplateData, TemplateSchemaResponse } from './types/template';
+export type { Align, Block, HeadingBlock, ImageBlock, KeyValueBlock, Orientation, PageConfig, PageFormat, PageSize, Row, SpacerBlock, TableBlock, Template, TextBlock, } from './types/generated/template';