diff --git a/.gitignore b/.gitignore index c09dd7e..7050ee9 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,4 @@ examples/**/yarn.lock # Dev dev/** +CLAUDE.md diff --git a/README.md b/README.md index d0a184b..88f0281 100644 --- a/README.md +++ b/README.md @@ -206,25 +206,77 @@ function TemplateEditor() { ## Export Template -Get the complete template data for saving: +The `exportTemplate` method supports two modes of operation via the `ExportConfig` interface: + +### 1. Download Mode (Default) + +Automatically downloads the template as a file in the browser: + +```jsx +const handleDownload = async () => { + // Download with default filename "document.docx" + await ref.current?.exportTemplate(); + + // Or with custom filename + await ref.current?.exportTemplate({ + fileName: 'invoice-template.docx' + }); +}; +``` + +### 2. Blob Mode (for Database/API) + +Get the template as a Blob for saving to your database or API: ```jsx const handleSave = async () => { - await ref.current?.exportTemplate({ fileName: 'invoice.docx' }); + // Get the blob without triggering download + const blob = await ref.current?.exportTemplate({ + fileName: 'invoice-template.docx', + triggerDownload: false + }); + + if (blob) { + // Send to your API/database + const formData = new FormData(); + formData.append('template', blob, 'invoice-template.docx'); + + await fetch('/api/templates', { + method: 'POST', + body: formData + }); + } }; ``` +### ExportConfig Interface + +```typescript +interface ExportConfig { + fileName?: string; // Default: "document" + triggerDownload?: boolean; // Default: true +} + +// Method signature +exportTemplate(config?: ExportConfig): Promise +``` + +**Return value:** +- `Promise` when `triggerDownload: true` (download happens automatically) +- `Promise` when `triggerDownload: false` (returns the docx data) + ## TypeScript Full TypeScript support included: ```typescript import SuperDocTemplateBuilder from '@superdoc-dev/template-builder'; -import type { +import type { TemplateField, FieldDefinition, TriggerEvent, - SuperDocTemplateBuilderHandle + ExportConfig, + SuperDocTemplateBuilderHandle } from '@superdoc-dev/template-builder'; const ref = useRef(null); diff --git a/src/index.tsx b/src/index.tsx index 2e56540..762ed3d 100644 --- a/src/index.tsx +++ b/src/index.tsx @@ -588,12 +588,17 @@ const SuperDocTemplateBuilder = forwardRef< }, [templateFields, selectedFieldId, selectField]); const exportTemplate = useCallback( - async (options?: { fileName?: string }): Promise => { + async (config?: Types.ExportConfig): Promise => { + const { fileName = "document", triggerDownload = true } = config || {}; + try { - await superdocRef.current?.export({ + const result = await superdocRef.current?.export({ exportType: ["docx"], - exportedName: options?.fileName ? options?.fileName : "document", + exportedName: fileName, + triggerDownload, }); + + return result; } catch (error) { console.error("Failed to export DOCX", error); throw error; diff --git a/src/types.ts b/src/types.ts index 0450008..0cd135f 100644 --- a/src/types.ts +++ b/src/types.ts @@ -76,6 +76,24 @@ export interface ToolbarConfig { icons?: Record; } +/** + * Configuration options for exporting templates + */ +export interface ExportConfig { + /** + * The name of the exported file (without extension) + * @default "document" + */ + fileName?: string; + /** + * Whether to trigger an automatic download in the browser + * - true: Automatically downloads the file + * - false: Returns the Blob data for manual handling (e.g., saving to database) + * @default true + */ + triggerDownload?: boolean; +} + export interface SuperDocTemplateBuilderProps { document?: DocumentConfig; fields?: FieldsConfig; @@ -115,5 +133,5 @@ export interface SuperDocTemplateBuilderHandle { nextField: () => void; previousField: () => void; getFields: () => TemplateField[]; - exportTemplate: (options?: { fileName?: string }) => Promise; + exportTemplate: (config?: ExportConfig) => Promise; }