doccraft 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# doccraft
+
+A visual template editor for React. Build HTML templates with `{{variables}}`, loops, and conditionals in a Google Docs-like editor. Output clean HTML for Jinja, Handlebars, Mustache, or any template engine.
+
+Built on [TipTap](https://tiptap.dev) and [ProseMirror](https://prosemirror.net).
+
+## Install
+
+```bash
+npm install doccraft
+```
+
+Peer dependencies: `react` and `react-dom` (v18 or v19).
+
+## Usage
+
+```tsx
+import { useRef } from 'react'
+import { DocCraft, type DocCraftRef, forBlock, ifBlock } from 'doccraft'
+
+function TemplateEditor() {
+  const ref = useRef<DocCraftRef>(null)
+
+  return (
+    <DocCraft
+      ref={ref}
+      variables={[
+        { key: 'name', label: 'Name' },
+        { key: 'email', label: 'Email' },
+      ]}
+      blocks={[forBlock, ifBlock]}
+      onChange={(html) => saveTemplate(html)}
+    />
+  )
+}
+```
+
+> Styles are auto-imported. No separate CSS import needed.
+
+## What It Does
+
+Users design documents visually. The editor outputs HTML with template syntax:
+
+```
+Visual editor          ->    HTML output
+-----------------            ---------------------
+[name chip]            ->    {{name}}
+[For: item in items]   ->    <div data-block-for="item in items">
+  [item.name chip]     ->      {{item.name}}
+[End for]              ->    </div>
+```
+
+Feed the HTML to Jinja, Handlebars, or any template engine, then generate PDFs.
+
+## API Reference
+
+See the [full documentation](../../README.md) for complete API reference including:
+
+- All props (canvas, toolbar, theme, extensions, actions, header/footer)
+- Ref methods (getHTML, getPdfHTML, getPreviewHTML, setContent, etc.)
+- Canvas presets (A4, email, custom)
+- Toolbar presets (full, minimal, document)
+- Custom block plugins
+- Import/export utilities
+- PDF generation examples
+
+### Quick Reference
+
+| Export | Description |
+|--------|-------------|
+| `DocCraft` | Main editor component |
+| `DocCraftRef` | Ref type for programmatic control |
+| `DocCraftProps` | Props type |
+| `forBlock` | For-loop block plugin |
+| `ifBlock` | If-condition block plugin |
+| `readonlyBlock` | Read-only block plugin |
+| `importDocx(file)` | Import .docx files |
+| `importPdf(file)` | Import .pdf files |
+| `exportToPdfHtml(html, opts)` | Generate PDF-ready HTML |
+| `exportToPreviewHtml(html, opts)` | Generate visual preview HTML |
+
+## License
+
+MIT

package/dist/blocks/base-styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared structural styles for all editor blocks.
+ * Injected once when any block is registered.
+ * Individual block colors/themes come from each block's own styles.
+ */
+export declare const BLOCK_BASE_STYLES = "\n.s-block {\n  position: relative;\n  margin: 0.75em 0;\n  border-radius: 6px;\n  border: 1.5px solid transparent;\n  transition: border-color 0.15s;\n}\n.s-block--selected {\n  border-color: currentColor;\n}\n.s-block__header {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  padding: 4px 10px;\n  border-radius: 5px 5px 0 0;\n  font-size: 11px;\n  font-weight: 500;\n  user-select: none;\n  gap: 6px;\n}\n.s-block__header-left {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  min-width: 0;\n  flex: 1;\n}\n.s-block__footer {\n  padding: 3px 10px;\n  border-radius: 0 0 5px 5px;\n  font-size: 10px;\n  font-weight: 500;\n  user-select: none;\n  opacity: 0.7;\n}\n.s-block__body {\n  padding: 8px 12px;\n  min-height: 2em;\n}\n.s-block__expr {\n  cursor: default;\n  white-space: nowrap;\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n.s-block__expr strong {\n  font-weight: 700;\n  font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, monospace;\n}\n.s-block__expr-edit {\n  display: inline-flex;\n  align-items: center;\n  gap: 4px;\n}\n.s-block__expr-kw {\n  opacity: 0.7;\n}\n.s-block__expr-input {\n  background: rgba(255,255,255,0.3);\n  border: 1px solid rgba(255,255,255,0.5);\n  border-radius: 3px;\n  padding: 0 4px;\n  font-size: 11px;\n  font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, monospace;\n  font-weight: 700;\n  color: inherit;\n  outline: none;\n  min-width: 3ch;\n}\n.s-block__expr-input:focus {\n  border-color: rgba(255,255,255,0.8);\n  background: rgba(255,255,255,0.4);\n}\n.s-block__delete {\n  opacity: 0;\n  transition: opacity 0.15s;\n  flex-shrink: 0;\n  background: none;\n  border: none;\n  color: inherit;\n  cursor: pointer;\n  padding: 2px;\n  border-radius: 3px;\n  display: flex;\n  align-items: center;\n}\n.s-block__delete:hover {\n  background: rgba(0,0,0,0.1);\n}\n.s-block:hover .s-block__delete,\n.s-block--selected .s-block__delete {\n  opacity: 1;\n}\n";

package/dist/blocks/for-block/extension.d.ts

@@ -0,0 +1,16 @@
+import { Node } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        forBlock: {
+            insertForBlock: (options: {
+                iterVar: string;
+                listVar: string;
+            }) => ReturnType;
+        };
+    }
+}
+export interface ForBlockOptions {
+    /** Available variables the user can pick as the list source */
+    variables: import('../../types').TemplateVariable[];
+}
+export declare const ForBlockExtension: Node<ForBlockOptions, any>;

package/dist/blocks/for-block/index.d.ts

@@ -0,0 +1,2 @@
+import type { EditorBlockPlugin } from '../types';
+export declare const forBlock: EditorBlockPlugin;

package/dist/blocks/for-block/styles.d.ts

@@ -0,0 +1,2 @@
+export declare const FOR_BLOCK_STYLES = "\n.s-block--for { color: #1d4ed8; }\n.s-block--for__header { background: #dbeafe; color: #1e40af; }\n.s-block--for__footer { background: #dbeafe; color: #1e40af; }\n.s-block--for .s-block__body {\n  background: #f0f7ff;\n  border-left: 2px solid #93c5fd;\n  border-right: 2px solid #93c5fd;\n}\n\n/* Variable picker */\n.s-block__var-picker-wrap {\n  position: relative;\n  display: inline-flex;\n}\n.s-block__var-picker-btn {\n  display: inline-flex;\n  align-items: center;\n  gap: 2px;\n  background: rgba(255,255,255,0.3);\n  border: 1px solid rgba(255,255,255,0.5);\n  border-radius: 3px;\n  padding: 0 6px 0 4px;\n  font-size: 11px;\n  font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, monospace;\n  font-weight: 700;\n  color: inherit;\n  cursor: pointer;\n  min-width: 3ch;\n  line-height: 1.6;\n}\n.s-block__var-picker-btn:hover {\n  background: rgba(255,255,255,0.5);\n}\n.s-block__var-picker-dropdown {\n  position: absolute;\n  top: 100%;\n  left: 0;\n  margin-top: 4px;\n  background: white;\n  border: 1px solid #d1d5db;\n  border-radius: 6px;\n  box-shadow: 0 4px 12px rgba(0,0,0,0.15);\n  min-width: 160px;\n  max-height: 200px;\n  overflow-y: auto;\n  z-index: 50;\n  padding: 4px;\n}\n.s-block__var-picker-item {\n  display: block;\n  width: 100%;\n  text-align: left;\n  padding: 4px 8px;\n  font-size: 12px;\n  font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, monospace;\n  color: #374151;\n  background: none;\n  border: none;\n  border-radius: 4px;\n  cursor: pointer;\n}\n.s-block__var-picker-item:hover {\n  background: #dbeafe;\n  color: #1e40af;\n}\n.s-block__var-picker-item.active {\n  background: #bfdbfe;\n  color: #1e40af;\n  font-weight: 600;\n}\n.s-block__var-picker-empty {\n  padding: 8px;\n  font-size: 11px;\n  color: #9ca3af;\n  text-align: center;\n}\n.s-block__var-picker-divider {\n  height: 1px;\n  background: #e5e7eb;\n  margin: 4px 0;\n}\n.s-block__var-picker-custom {\n  padding: 4px;\n}\n.s-block__var-picker-custom .s-block__expr-input {\n  background: #f9fafb;\n  border-color: #d1d5db;\n  color: #374151;\n  width: 100%;\n  padding: 2px 6px;\n}\n\n/* Done button */\n.s-block__expr-done {\n  background: rgba(255,255,255,0.4);\n  border: 1px solid rgba(255,255,255,0.6);\n  border-radius: 3px;\n  padding: 0 8px;\n  font-size: 10px;\n  color: inherit;\n  cursor: pointer;\n  margin-left: 4px;\n  line-height: 1.6;\n}\n.s-block__expr-done:hover {\n  background: rgba(255,255,255,0.6);\n}\n";
+export declare const FOR_BLOCK_EXPORT_STYLES = "\ndiv[data-block-for] {\n  border-left: 3px solid #93c5fd;\n  padding-left: 12px;\n  margin: 0.5em 0;\n}\n";

package/dist/blocks/for-block/view.d.ts

@@ -0,0 +1,2 @@
+import { type NodeViewProps } from '@tiptap/react';
+export declare function ForBlockView({ node, updateAttributes, deleteNode, selected, extension, editor }: NodeViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/blocks/if-block/extension.d.ts

@@ -0,0 +1,11 @@
+import { Node } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        ifBlock: {
+            insertIfBlock: (options: {
+                condition: string;
+            }) => ReturnType;
+        };
+    }
+}
+export declare const IfBlockExtension: Node<any, any>;

package/dist/blocks/if-block/index.d.ts

@@ -0,0 +1,2 @@
+import type { EditorBlockPlugin } from '../types';
+export declare const ifBlock: EditorBlockPlugin;

package/dist/blocks/if-block/styles.d.ts

@@ -0,0 +1,2 @@
+export declare const IF_BLOCK_STYLES = "\n.s-block--if { color: #b45309; }\n.s-block--if__header { background: #fef3c7; color: #92400e; }\n.s-block--if__footer { background: #fef3c7; color: #92400e; }\n.s-block--if .s-block__body {\n  background: #fffbeb;\n  border-left: 2px solid #fcd34d;\n  border-right: 2px solid #fcd34d;\n}\n";
+export declare const IF_BLOCK_EXPORT_STYLES = "\ndiv[data-block-if] {\n  border-left: 3px solid #fcd34d;\n  padding-left: 12px;\n  margin: 0.5em 0;\n}\n";

package/dist/blocks/if-block/view.d.ts

@@ -0,0 +1,2 @@
+import { type NodeViewProps } from '@tiptap/react';
+export declare function IfBlockView({ node, updateAttributes, deleteNode, selected, editor }: NodeViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/blocks/index.d.ts

@@ -0,0 +1,5 @@
+export type { EditorBlockPlugin } from './types';
+export { BLOCK_BASE_STYLES } from './base-styles';
+export { forBlock } from './for-block';
+export { ifBlock } from './if-block';
+export { readonlyBlock } from './readonly-block';

package/dist/blocks/readonly-block/extension.d.ts

@@ -0,0 +1,12 @@
+import { Node } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        readonlyBlock: {
+            insertReadOnlyBlock: (options: {
+                content: string;
+                label?: string;
+            }) => ReturnType;
+        };
+    }
+}
+export declare const ReadOnlyBlockExtension: Node<any, any>;

package/dist/blocks/readonly-block/index.d.ts

@@ -0,0 +1,2 @@
+import type { EditorBlockPlugin } from '../types';
+export declare const readonlyBlock: EditorBlockPlugin;

package/dist/blocks/readonly-block/styles.d.ts

@@ -0,0 +1,2 @@
+export declare const READONLY_BLOCK_STYLES = "\n.s-block--readonly { color: #4b5563; }\n.s-block--readonly__header { background: #e5e7eb; color: #374151; }\n.s-block--readonly__body {\n  background: #f9fafb;\n  border-left: 2px solid #d1d5db;\n  border-right: 2px solid #d1d5db;\n  border-bottom: 2px solid #d1d5db;\n  border-radius: 0 0 5px 5px;\n  color: #6b7280;\n  cursor: default;\n}\n";
+export declare const READONLY_BLOCK_EXPORT_STYLES = "\ndiv[data-block-readonly] {\n  background: #f9fafb;\n  border: 1px solid #e5e7eb;\n  border-radius: 4px;\n  padding: 8px 12px;\n  margin: 0.5em 0;\n  color: #6b7280;\n}\n";

package/dist/blocks/readonly-block/view.d.ts

@@ -0,0 +1,2 @@
+import { type NodeViewProps } from '@tiptap/react';
+export declare function ReadOnlyBlockView({ node, deleteNode, selected, editor }: NodeViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/blocks/types.d.ts

@@ -0,0 +1,47 @@
+import type { Node } from '@tiptap/core';
+import type { ComponentType } from 'react';
+/**
+ * Runtime context passed to block plugins during registration.
+ * Contains editor-level state the block may need.
+ */
+export interface BlockContext {
+    /** Available template variables in the editor */
+    variables: import('../types').TemplateVariable[];
+}
+/**
+ * Interface every editor block plugin must implement.
+ *
+ * A block is a self-contained plugin that provides:
+ * - A TipTap Node extension (schema, commands, parsing)
+ * - Its own CSS styles (injected at mount, cleaned up on unmount)
+ * - Metadata for the toolbar (name, icon, description)
+ * - An insert handler for the toolbar to call
+ *
+ * Blocks own their entire lifecycle — the editor core knows nothing
+ * about block internals. It just registers the extension and shows
+ * the block in the toolbar.
+ */
+export interface EditorBlockPlugin {
+    /** Unique block name — must match the TipTap extension name */
+    name: string;
+    /** Display label for the toolbar */
+    label: string;
+    /** Lucide icon component for the toolbar */
+    icon: ComponentType<{
+        className?: string;
+    }>;
+    /** Short description shown in toolbar tooltip */
+    description?: string;
+    /**
+     * The TipTap Node extension.
+     * Can be a static extension or a factory that receives runtime context
+     * (e.g., current variables list) and returns a configured extension.
+     */
+    extension: Node | ((ctx: BlockContext) => Node);
+    /** CSS styles for this block — injected into <head> when the block is registered */
+    styles: string;
+    /** CSS styles for PDF/preview export — included in exported HTML */
+    exportStyles?: string;
+    /** Called when the user clicks the block in the toolbar. Should call editor commands to insert. */
+    insert: (editor: import('@tiptap/react').Editor) => void;
+}

package/dist/canvas/HeaderFooterField.d.ts

@@ -0,0 +1,11 @@
+import { type Editor } from '@tiptap/react';
+interface HeaderFooterFieldProps {
+    content: string;
+    onChange: (html: string) => void;
+    placeholder: string;
+    isEditing: boolean;
+    onStartEdit: () => void;
+    editorRef?: React.MutableRefObject<Editor | null>;
+}
+export declare function HeaderFooterField({ content, onChange, placeholder, isEditing, onStartEdit, editorRef, }: HeaderFooterFieldProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/canvas/PageCanvas.d.ts

@@ -0,0 +1,16 @@
+import { type Editor } from '@tiptap/react';
+import type { ResolvedCanvas } from './canvas-config';
+import type { ThemeConfig } from '../types';
+interface PageCanvasProps {
+    editor: Editor;
+    canvas: ResolvedCanvas;
+    header?: string;
+    footer?: string;
+    onHeaderChange?: (value: string) => void;
+    onFooterChange?: (value: string) => void;
+    onActiveHfEditor?: (editor: Editor | null) => void;
+    readOnly?: boolean;
+    theme?: ThemeConfig;
+}
+export declare function PageCanvas({ editor, canvas, header, footer, onHeaderChange, onFooterChange, onActiveHfEditor, readOnly, theme }: PageCanvasProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/canvas/canvas-config.d.ts

@@ -0,0 +1,25 @@
+import type { CanvasConfig } from '../types';
+export declare const CANVAS_PRESETS: Record<string, CanvasConfig>;
+export interface ResolvedCanvas {
+    width: string;
+    height: string | undefined;
+    padding: {
+        top: string;
+        right: string;
+        bottom: string;
+        left: string;
+    };
+    paginate: boolean;
+    pageGap: number;
+    widthPx: number;
+    heightPx: number | undefined;
+    paddingPx: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    contentHeightPx: number | undefined;
+}
+export declare function resolveCanvas(canvas: string | CanvasConfig | undefined): ResolvedCanvas;
+export declare function cssToPixels(value: string): number;

package/dist/core/DocCraft.d.ts

@@ -0,0 +1,54 @@
+import { type EditorActionsConfig } from '../toolbar/EditorActions';
+import type { EditorBlockPlugin } from '../blocks/types';
+import type { CanvasConfig, ToolbarConfig, TemplateVariable, ExtensionsConfig, ThemeConfig } from '../types';
+import '../editor.css';
+export interface DocCraftRef {
+    getHTML: () => string;
+    getPdfHTML: (options?: {
+        title?: string;
+    }) => string;
+    getPreviewHTML: (options?: {
+        title?: string;
+    }) => string;
+    getJSON: () => Record<string, unknown>;
+    setContent: (html: string) => void;
+    getVariables: () => TemplateVariable[];
+    getHeader: () => string;
+    getFooter: () => string;
+    setHeader: (text: string) => void;
+    setFooter: (text: string) => void;
+    setReadOnly: (readOnly: boolean) => void;
+    isReadOnly: () => boolean;
+    focus: () => void;
+    clear: () => void;
+}
+export interface DocCraftProps {
+    content?: string;
+    placeholder?: string;
+    onChange?: (html: string) => void;
+    className?: string;
+    variables?: TemplateVariable[] | false;
+    blocks?: EditorBlockPlugin[];
+    header?: string;
+    footer?: string;
+    /**
+     * Read-only mode. Disables content editing but keeps the document visible.
+     * Toolbar remains visible (unless showToolbar={false}) so the user can
+     * click the Edit/Preview toggle to switch modes.
+     * Can be toggled programmatically via ref.setReadOnly().
+     */
+    readOnly?: boolean;
+    /**
+     * Whether to show the toolbar. Defaults to true.
+     * Set to false to completely hide the toolbar — the user cannot
+     * switch between edit/preview modes (true read-only display).
+     */
+    showToolbar?: boolean;
+    actions?: boolean | EditorActionsConfig;
+    toolbarActions?: React.ReactNode;
+    canvas?: 'a4' | 'email' | CanvasConfig;
+    toolbar?: 'full' | 'minimal' | 'document' | ToolbarConfig;
+    extensions?: ExtensionsConfig;
+    theme?: ThemeConfig;
+}
+export declare const DocCraft: import("react").ForwardRefExoticComponent<DocCraftProps & import("react").RefAttributes<DocCraftRef>>;

package/dist/core/page-flow-plugin.d.ts

@@ -0,0 +1,22 @@
+import { Extension } from '@tiptap/core';
+interface PageFlowOptions {
+    contentHeight: number;
+    paddingTop: number;
+    paddingBottom: number;
+    pageGap: number;
+    enabled: boolean;
+}
+/**
+ * Page Flow Extension
+ *
+ * Injects CSS margin-top rules via a <style> tag to push content that
+ * crosses page boundaries to the next page's content area.
+ *
+ * Uses nth-child selectors. To avoid layout thrashing:
+ * - Debounces at 100ms (not every keystroke)
+ * - Only recomputes when content structure changes
+ * - Clears rules, reads clean positions, re-applies in one rAF
+ *   (single reflow instead of clear-measure-apply cycle)
+ */
+export declare const PageFlowExtension: Extension<PageFlowOptions, any>;
+export {};

package/dist/core/use-editor.d.ts

@@ -0,0 +1,14 @@
+import type { EditorBlockPlugin } from '../blocks/types';
+import type { ResolvedCanvas } from '../canvas/canvas-config';
+import type { TemplateVariable as TemplateVariableType, ExtensionsConfig } from '../types';
+interface UseEditorOptions {
+    content?: string;
+    placeholder?: string;
+    variables?: TemplateVariableType[] | false;
+    blocks?: EditorBlockPlugin[];
+    canvas?: ResolvedCanvas;
+    extensions?: ExtensionsConfig;
+    onUpdate?: (html: string) => void;
+}
+export declare function useEditor(options?: UseEditorOptions): import("@tiptap/core").Editor;
+export {};