feat: enhance exportTemplate functionality with configurable options

.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

@@ -16,7 +16,7 @@
 type Editor = NonNullable<SuperDoc["activeEditor"]>;
 
 const getTemplateFieldsFromEditor = (editor: Editor): Types.TemplateField[] => {
   const structuredContentHelpers = (editor.helpers as any)
     ?.structuredContentCommands;
 
   if (!structuredContentHelpers?.getStructuredContentTags) {
@@ -26,7 +26,7 @@
   const tags =
     structuredContentHelpers.getStructuredContentTags(editor.state) || [];
 
   return tags.map((entry: any) => {
     const node = entry?.node ?? entry;
     const attrs = node?.attrs ?? {};
 
@@ -163,7 +163,7 @@
 
   const trigger = menu.trigger || "{{"; // Default trigger
 
   const availableFields = fieldsRef.current.available || [];
 
   const computeFilteredFields = useCallback(
     (query: string) => {
@@ -391,7 +391,7 @@
             const editor = instance.activeEditor;
 
             // Setup trigger detection
             editor.on("update", ({ editor: e }: any) => {
               const { state } = e;
               const { from } = state.selection;
 
@@ -503,7 +503,7 @@
 
       superdocRef.current = null;
     };
   }, [
     document?.source,
     document?.mode,
     trigger,
@@ -588,12 +588,17 @@
   }, [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

@@ -5,7 +5,7 @@
   label: string;
   category?: string;
   defaultValue?: string;
   metadata?: Record<string, any>;
 }
 
 export interface TemplateField {
@@ -73,9 +73,27 @@
   responsiveToContainer?: boolean;
   excludeItems?: string[];
   texts?: Record<string, string>;
   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 @@
   nextField: () => void;
   previousField: () => void;
   getFields: () => TemplateField[];
-  exportTemplate: (options?: { fileName?: string }) => Promise<void>;
+  exportTemplate: (config?: ExportConfig) => Promise<void | Blob>;
 }