@signiphi/pdf-compose 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -0,0 +1,258 @@
+# @signiphi/pdf-compose
+
+Markdown-based document composer with interactive form field placeholders and real-time PDF preview. Built for the signiphi signing pipeline.
+
+Write documents in a rich text editor, embed signable form fields (signature, date, text, checkbox, etc.) and template variables, then export production-ready PDFs with interactive AcroForm fields.
+
+## Install
+
+```bash
+npm install @signiphi/pdf-compose
+# or
+pnpm add @signiphi/pdf-compose
+```
+
+## Quick Start
+
+```tsx
+import { DocumentGenerator } from '@signiphi/pdf-compose';
+import '@signiphi/pdf-compose/styles';
+
+function App() {
+  return (
+    <DocumentGenerator
+      placeholder="Start writing your document..."
+      onExport={(result) => {
+        // result.pdfBlob  — Blob with interactive form fields
+        // result.fields   — Array of field positions for signing
+        const url = URL.createObjectURL(result.pdfBlob);
+        window.open(url);
+      }}
+    />
+  );
+}
+```
+
+## Features
+
+- **Rich text editor** — TipTap-based with markdown toolbar (headings, bold, italic, underline, lists, alignment)
+- **Form field placeholders** — Insert signature, text, date, checkbox, initials, radio, dropdown, and text label fields inline
+- **Template variables** — Define reusable variables (company name, salary, etc.) that get replaced at generation time
+- **Real-time PDF preview** — See the rendered PDF alongside the editor with field overlays
+- **PDF generation** — Export PDFs with embedded interactive AcroForm fields via pdf-lib
+- **Bulk generation** — Fill variables from JSON or CSV and generate multiple PDFs as a ZIP
+- **Theming** — Light, dark, and auto modes with customizable primary color
+- **Markdown I/O** — Import/export documents as markdown with field token syntax
+
+## Props
+
+```tsx
+interface DocumentGeneratorProps {
+  /** Pre-fill the editor with markdown content */
+  initialMarkdown?: string;
+  /** Pre-fill with TipTap JSON content (takes precedence over initialMarkdown) */
+  initialContent?: JSONContent;
+  /** Fires on content changes (debounced 150ms) */
+  onChange?: (data: { markdown: string; fields: DocumentGeneratorField[]; variables: DocumentGeneratorVariable[] }) => void;
+  /** Fires when the user exports from the Editor tab */
+  onExport?: (result: DocumentGeneratorExportResult) => void;
+  /** Fires when the user generates a PDF from the Generate tab */
+  onGeneratePdf?: (blob: Blob, fileName: string) => void;
+  /** Disable editing */
+  readOnly?: boolean;
+  /** Custom CSS class */
+  className?: string;
+  /** Primary theme color (hex) */
+  themeColor?: string;
+  /** Theme mode — 'light' | 'dark' | 'auto' (default: 'auto') */
+  themeMode?: ThemeMode;
+  /** Full custom color palette */
+  themeConfig?: ThemeConfig;
+  /** Show the PDF preview panel (default: true) */
+  showPreview?: boolean;
+  /** Show the editor toolbar (default: true) */
+  showToolbar?: boolean;
+  /** Show the Generate tab (default: true) */
+  showGenerateTab?: boolean;
+  /** Editor placeholder text */
+  placeholder?: string;
+  /** Custom text for the export button */
+  exportButtonText?: string;
+  /** Pre-fill bulk generation data */
+  initialBulkData?: Record<string, string>[];
+}
+```
+
+## Field Token Syntax
+
+Fields and variables are embedded as inline tokens in the markdown content:
+
+### Form Fields
+
+```
+{{field|type:signature|name:sig_1|label:Employee Signature|required:true}}
+```
+
+| Attribute      | Description                                   |
+| -------------- | --------------------------------------------- |
+| `type`         | `text`, `signature`, `initials`, `date`, `checkbox`, `radio`, `dropdown`, `text_label` |
+| `name`         | Field identifier in the PDF                   |
+| `label`        | User-facing label                             |
+| `required`     | `true` or `false`                             |
+| `placeholder`  | Hint text for text fields                     |
+| `options`      | Comma-separated values (radio/dropdown)       |
+| `defaultValue` | Pre-filled value                              |
+| `multiline`    | `true` for multiline text fields              |
+| `maxLength`    | Character limit                               |
+| `fontSize`     | Font size in points                           |
+
+### Template Variables
+
+```
+{{var|name:company_name|label:Company Name|default:Acme Corp}}
+```
+
+| Attribute | Description           |
+| --------- | --------------------- |
+| `name`    | Variable identifier   |
+| `label`   | Display label         |
+| `default` | Default value         |
+
+Variables are replaced with actual values at PDF generation time. In bulk mode, each row of data produces a separate PDF.
+
+## Advanced Usage
+
+### Using the Hook Directly
+
+For custom layouts, use `useDocumentGenerator` to drive your own UI:
+
+```tsx
+import { useDocumentGenerator, EditorPanel, PreviewPanel } from '@signiphi/pdf-compose';
+import '@signiphi/pdf-compose/styles';
+
+function CustomComposer() {
+  const generator = useDocumentGenerator({ initialMarkdown: '# My Doc' });
+
+  return (
+    <div style={{ display: 'flex', gap: 16 }}>
+      <EditorPanel {...generator} />
+      <PreviewPanel pages={generator.pdfPages} fields={generator.positionedFields} />
+    </div>
+  );
+}
+```
+
+### Export Result
+
+The `onExport` callback receives:
+
+```tsx
+interface DocumentGeneratorExportResult {
+  pdfBlob: Blob;           // PDF with embedded interactive form fields
+  fields: FormFieldForExport[]; // Field metadata with page positions
+}
+
+interface FormFieldForExport {
+  name: string;
+  type: FormFieldType;
+  label?: string;
+  required: boolean;
+  page: number;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+```
+
+### Pre-filled Markdown Example
+
+```tsx
+const markdown = `# Employment Agreement
+
+**Company:** {{var|name:company|label:Company Name|default:Acme Corp}}
+
+**Employee:** {{field|type:text|name:employee_name|required:true|placeholder:Full name}}
+
+**Start Date:** {{field|type:date|name:start_date|required:true}}
+
+## Signature
+
+{{field|type:signature|name:employee_sig|label:Employee Signature|required:true}}
+`;
+
+<DocumentGenerator
+  initialMarkdown={markdown}
+  onExport={handleExport}
+  themeColor="#4F46E5"
+/>
+```
+
+## Styling
+
+Import the stylesheet — required for the component to render correctly:
+
+```tsx
+import '@signiphi/pdf-compose/styles';
+```
+
+All styles are scoped under `.signiphi-pdf-compose` so they won't conflict with your application's CSS. CSS custom properties use the `--xpc-*` namespace.
+
+### Theming
+
+```tsx
+// Simple — just a color
+<DocumentGenerator themeColor="#4F46E5" themeMode="dark" />
+
+// Full custom palette
+<DocumentGenerator themeConfig={{
+  primary: '#4F46E5',
+  primaryForeground: '#ffffff',
+  background: '#1a1a2e',
+  foreground: '#e0e0e0',
+  border: '#333355',
+  // ...
+}} />
+```
+
+## Exports
+
+```tsx
+// Components
+export { DocumentGenerator } from '@signiphi/pdf-compose';
+export { EditorPanel } from '@signiphi/pdf-compose';
+export { PreviewPanel } from '@signiphi/pdf-compose';
+
+// Hooks
+export { useDocumentGenerator } from '@signiphi/pdf-compose';
+
+// Theme
+export { ThemeProvider, useTheme } from '@signiphi/pdf-compose';
+
+// Types
+export type {
+  DocumentGeneratorProps,
+  DocumentGeneratorField,
+  DocumentGeneratorVariable,
+  VariableValues,
+  GeneratedDocument,
+  DocumentGeneratorExportResult,
+  FormFieldForExport,
+  ThemeMode,
+  ThemeConfig,
+  PdfPage,
+} from '@signiphi/pdf-compose';
+
+export { FormFieldType } from '@signiphi/pdf-compose';
+```
+
+## Peer Dependencies
+
+- `react` >= 18
+- `react-dom` >= 18
+- `@radix-ui/react-dialog`, `@radix-ui/react-label`, `@radix-ui/react-popover`, `@radix-ui/react-select`, `@radix-ui/react-tooltip`
+- `lucide-react`
+
+## License
+
+See repository for license information.