feat: update exportTemplate functionality to support async operations and improve user experience

Author: caio-pizzol

README.md

@@ -123,7 +123,7 @@ ref.current.previousField();  // Shift+Tab behavior
 
 // Get data
 const fields = ref.current.getFields();
-const template = ref.current.exportTemplate();
+const template = await ref.current.exportTemplate();
 ```
 
 ## Custom Components
@@ -201,15 +201,8 @@ function TemplateEditor() {
 Get the complete template data for saving:
 
 ```jsx
-const handleSave = () => {
-  const data = ref.current?.exportTemplate();
-  
-  // Save to backend
-  await api.saveTemplate({
-    name: 'Invoice Template',
-    fields: data.fields,
-    document: data.document
-  });
+const handleSave = async () => {
+  await ref.current?.exportTemplate({ fileName: 'invoice.docx' });
 };
 ```
 

demo/src/App.tsx

@@ -1,19 +1,19 @@
-import React, { useState, useRef, useCallback, useMemo } from 'react';
-import SuperDocTemplateBuilder from '@superdoc-dev/template-builder';
+import React, { useState, useRef, useCallback, useMemo } from "react";
+import SuperDocTemplateBuilder from "@superdoc-dev/template-builder";
 import type {
   SuperDocTemplateBuilderHandle,
   TemplateField,
-  FieldDefinition
-} from '@superdoc-dev/template-builder';
-import 'superdoc/dist/style.css';
-import './App.css';
+  FieldDefinition,
+} from "@superdoc-dev/template-builder";
+import "superdoc/dist/style.css";
+import "./App.css";
 
 const availableFields: FieldDefinition[] = [
   // Contact Information
-  { id: 'customer_name', label: 'Customer Name', category: 'Contact' },
-  { id: 'customer_email', label: 'Customer Email', category: 'Contact' },
-  { id: 'customer_phone', label: 'Customer Phone', category: 'Contact' },
-  { id: 'customer_address', label: 'Customer Address', category: 'Contact' },
+  { id: "customer_name", label: "Customer Name", category: "Contact" },
+  { id: "customer_email", label: "Customer Email", category: "Contact" },
+  { id: "customer_phone", label: "Customer Phone", category: "Contact" },
+  { id: "customer_address", label: "Customer Address", category: "Contact" },
 
   // Company Information
   { id: 'company_name', label: 'Company Name', category: 'Company' },
@@ -45,8 +45,7 @@ const availableFields: FieldDefinition[] = [
 export function App() {
   const [fields, setFields] = useState<TemplateField[]>([]);
   const [events, setEvents] = useState<string[]>([]);
-  const [showExport, setShowExport] = useState(false);
-  const [exportData, setExportData] = useState<any>(null);
+  const [isDownloading, setIsDownloading] = useState(false);
   const builderRef = useRef<SuperDocTemplateBuilderHandle>(null);
 
   const log = useCallback((msg: string) => {
@@ -82,11 +81,25 @@ export function App() {
     log('⌨ Trigger detected');
   }, [log]);
 
-  const handleExportTemplate = useCallback(() => {
-    const data = builderRef.current?.exportTemplate();
-    setExportData(data);
-    setShowExport(true);
-    log('📤 Template exported');
+  const handleExportTemplate = useCallback(async () => {
+    if (!builderRef.current) {
+      return;
+    }
+
+    try {
+      setIsDownloading(true);
+
+      await builderRef.current.exportTemplate({
+        fileName: "template.docx",
+      });
+
+      log("📤 Template exported");
+    } catch (error) {
+      log("⚠️ Export failed");
+      console.error("Failed to export template", error);
+    } finally {
+      setIsDownloading(false);
+    }
   }, [log]);
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
@@ -147,8 +160,12 @@ export function App() {
             <span className="hint">Tab/Shift+Tab to navigate</span>
           </div>
           <div className="toolbar-right">
-            <button onClick={handleExportTemplate} className="export-button">
-              Export Template
+            <button
+              onClick={handleExportTemplate}
+              className="export-button"
+              disabled={isDownloading}
+            >
+              {isDownloading ? "Exporting..." : "Export Template"}
             </button>
           </div>
         </div>
@@ -177,27 +194,6 @@ export function App() {
           </div>
         )}
 
-        {/* Export Modal */}
-        {showExport && (
-          <div className="modal-overlay" onClick={() => setShowExport(false)}>
-            <div className="modal" onClick={e => e.stopPropagation()}>
-              <h2>Exported Template</h2>
-              <div className="export-content">
-                <h3>Fields ({exportData?.fields?.length || 0})</h3>
-                <pre>{JSON.stringify(exportData?.fields || [], null, 2)}</pre>
-                {exportData?.document && (
-                  <>
-                    <h3>Document Structure</h3>
-                    <pre>{JSON.stringify(exportData.document, null, 2).substring(0, 500)}...</pre>
-                  </>
-                )}
-              </div>
-              <button onClick={() => setShowExport(false)} className="modal-close">
-                Close
-              </button>
-            </div>
-          </div>
-        )}
       </div>
     </div>
   );

src/__tests__/SuperDocTemplateBuilder.test.tsx

@@ -224,14 +224,11 @@ describe("SuperDocTemplateBuilder component", () => {
     await waitForBuilderReady();
     await waitFor(() => expect(ref.current).toBeTruthy());
 
-    const exportData = ref.current?.exportTemplate();
-
-    expect(exportData).toMatchObject({
-      fields: [
-        { id: "field1", alias: "Field 1", tag: "contact" },
-        { id: "field2", alias: "Field 2", tag: "invoice" },
-      ],
-      document: expect.any(Object),
+    await ref.current?.exportTemplate({ fileName: "export.docx" });
+
+    expect(superDocMock.mockExport).toHaveBeenCalledWith({
+      exportType: ["docx"],
+      exportedName: "export.docx",
     });
   });
 

src/index.tsx

@@ -66,25 +66,25 @@ const SuperDocTemplateBuilder = forwardRef<
       const success =
         mode === "inline"
           ? editor.commands.insertStructuredContentInline?.({
-            attrs: {
-              id: fieldId,
-              alias: field.alias,
-              tag: field.metadata
-                ? JSON.stringify(field.metadata)
-                : field.category,
-            },
-            text: field.defaultValue || field.alias,
-          })
+              attrs: {
+                id: fieldId,
+                alias: field.alias,
+                tag: field.metadata
+                  ? JSON.stringify(field.metadata)
+                  : field.category,
+              },
+              text: field.defaultValue || field.alias,
+            })
           : editor.commands.insertStructuredContentBlock?.({
-            attrs: {
-              id: fieldId,
-              alias: field.alias,
-              tag: field.metadata
-                ? JSON.stringify(field.metadata)
-                : field.category,
-            },
-            text: field.defaultValue || field.alias,
-          });
+              attrs: {
+                id: fieldId,
+                alias: field.alias,
+                tag: field.metadata
+                  ? JSON.stringify(field.metadata)
+                  : field.category,
+              },
+              text: field.defaultValue || field.alias,
+            });
 
       if (success) {
         const newField: Types.TemplateField = {
@@ -339,12 +339,31 @@ const SuperDocTemplateBuilder = forwardRef<
     selectField(templateFields[prevIndex].id);
   }, [templateFields, selectedFieldId, selectField]);
 
-  const exportTemplate = useCallback(() => {
-    return {
-      fields: templateFields,
-      document: superdocRef.current?.activeEditor?.exportDocx(),
-    };
-  }, [templateFields]);
+  const exportTemplate = useCallback(
+    async (options?: { fileName?: string }): Promise<void> => {
+      try {
+        const documentBlob = await superdocRef.current?.export({
+          exportType: ["docx"],
+          exportedName: options?.fileName || "document.docx",
+        });
+
+        if (!documentBlob) return;
+
+        const blobUrl = URL.createObjectURL(documentBlob as Blob);
+        const link = globalThis.document.createElement("a");
+        link.href = blobUrl;
+        link.download = options?.fileName || "document.docx";
+        globalThis.document.body.appendChild(link);
+        link.click();
+        globalThis.document.body.removeChild(link);
+        URL.revokeObjectURL(blobUrl);
+      } catch (error) {
+        console.error("Failed to export DOCX", error);
+        throw error;
+      }
+    },
+    [],
+  );
 
   // Imperative handle
   useImperativeHandle(ref, () => ({

src/test/setup.ts

@@ -7,6 +7,7 @@ const mockUpdateStructuredContentById = vi.fn();
 const mockDeleteStructuredContentById = vi.fn();
 const mockSelectStructuredContentById = vi.fn();
 const mockDestroy = vi.fn();
+const mockExportDocx = vi.fn(async () => new Blob());
 
 const mockEditor = {
   commands: {
@@ -37,6 +38,7 @@ const mockEditor = {
     dispatch: vi.fn(),
     coordsAtPos: vi.fn(() => ({ left: 0, top: 0 })),
   },
+  exportDocx: mockExportDocx,
   on: vi.fn(),
 };
 
@@ -48,6 +50,7 @@ const SuperDocMock = vi.fn((options: any = {}) => {
   return {
     destroy: mockDestroy,
     activeEditor: mockEditor,
+    exportDocx: mockExportDocx,
     on: vi.fn((event: string, handler: (data?: any) => void) => {
       if (event === "editorCreate") {
         queueMicrotask(() => handler({ editor: mockEditor }));
@@ -70,6 +73,7 @@ const SuperDocMock = vi.fn((options: any = {}) => {
 (SuperDocMock as any).mockSelectStructuredContentById =
   mockSelectStructuredContentById;
 (SuperDocMock as any).mockDestroy = mockDestroy;
+(SuperDocMock as any).mockExportDocx = mockExportDocx;
 
 vi.mock("superdoc", () => ({
   SuperDoc: SuperDocMock,

src/types.ts

@@ -28,7 +28,9 @@ export interface FieldMenuProps {
   allowCreate?: boolean;
   onSelect: (field: FieldDefinition) => void;
   onClose: () => void;
-  onCreateField?: (field: FieldDefinition) => void | Promise<FieldDefinition | void>;
+  onCreateField?: (
+    field: FieldDefinition,
+  ) => void | Promise<FieldDefinition | void>;
 }
 
 export interface FieldListProps {
@@ -73,7 +75,9 @@ export interface SuperDocTemplateBuilderProps {
   onFieldDelete?: (fieldId: string) => void;
   onFieldsChange?: (fields: TemplateField[]) => void;
   onFieldSelect?: (field: TemplateField | null) => void;
-  onFieldCreate?: (field: FieldDefinition) => void | Promise<FieldDefinition | void>;
+  onFieldCreate?: (
+    field: FieldDefinition,
+  ) => void | Promise<FieldDefinition | void>;
 
   // UI
   className?: string;
@@ -92,5 +96,5 @@ export interface SuperDocTemplateBuilderHandle {
   nextField: () => void;
   previousField: () => void;
   getFields: () => TemplateField[];
-  exportTemplate: () => { fields: TemplateField[]; document?: any };
+  exportTemplate: (options?: { fileName?: string }) => Promise<void>;
 }