feat: enhance exportTemplate functionality with configurable options (#17)

This commit updates the exportTemplate method to support a new ExportConfig interface, allowing users to specify a custom filename and control whether the download is triggered automatically or if the template is returned as a Blob for manual handling. Additionally, the README has been updated to reflect these changes, providing clear examples for both download and Blob modes.

Author: caio-pizzol

.gitignore

@@ -25,3 +25,4 @@ examples/**/yarn.lock
 
 # Dev
 dev/**
+CLAUDE.md

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<void | Blob>
+```
+
+**Return value:**
+- `Promise<void>` when `triggerDownload: true` (download happens automatically)
+- `Promise<Blob>` 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<SuperDocTemplateBuilderHandle>(null);

src/index.tsx

@@ -588,12 +588,17 @@ const SuperDocTemplateBuilder = forwardRef<
   }, [templateFields, selectedFieldId, selectField]);
 
   const exportTemplate = useCallback(
-    async (options?: { fileName?: string }): Promise<void> => {
+    async (config?: Types.ExportConfig): Promise<void | Blob> => {
+      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;

src/types.ts

@@ -76,6 +76,24 @@ export interface ToolbarConfig {
   icons?: Record<string, any>;
 }
 
+/**
+ * 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<void>;
+  exportTemplate: (config?: ExportConfig) => Promise<void | Blob>;
 }