feat(template-builder): reactive mode changes and refresh method (SD-2406) (#2726)

* feat(template-builder): reactive mode changes and refresh method

- Remove document.mode from init effect deps so mode changes don't
  destroy and recreate the editor (no more scroll jump / content flash)
- Add separate useEffect that calls setDocumentMode() imperatively,
  following the same pattern as the React wrapper
- Add refresh() method to the imperative handle for re-discovering
  fields after async data delivery
- Document refresh() in API reference

Closes SD-2406

* fix(template-builder): queue mode changes during init

If document.mode changes while SuperDoc is still loading, the change
is queued and applied once handleReady fires. Follows the same
pendingModeRef pattern as the React wrapper.

* fix(template-builder): address review findings for mode change logic

- Remove redundant prevModeRef — useEffect dep array handles this
- Clear pendingModeRef in init cleanup to prevent stale mode on re-init
- Clear pendingModeRef when applying mode directly
- Extract applyDocumentMode helper to centralize the as-any cast

Author: caio-pizzol

apps/docs/solutions/template-builder/api-reference.mdx

@@ -361,6 +361,14 @@ const fields = builderRef.current?.getFields();
 // Returns: TemplateField[]
 ```
 
+### refresh()
+
+Re-discover fields from the editor and trigger `onFieldsChange`. Use this when field data arrives asynchronously or after external changes to the document:
+
+```typescript
+builderRef.current?.refresh();
+```
+
 ### exportTemplate()
 
 Export the template as a .docx file:

packages/template-builder/src/index.tsx

@@ -15,6 +15,10 @@ export { FieldMenu, FieldList };
 
 type Editor = NonNullable<SuperDoc['activeEditor']>;
 
+const applyDocumentMode = (instance: SuperDoc, mode: string) => {
+  (instance as any).setDocumentMode(mode);
+};
+
 const getTemplateFieldsFromEditor = (editor: Editor): Types.TemplateField[] => {
   const structuredContentHelpers = (editor.helpers as any)?.structuredContentCommands;
 
@@ -443,6 +447,12 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
             discoverFields(editor);
           }
 
+          // Apply any mode change that arrived during init
+          if (pendingModeRef.current && instance) {
+            applyDocumentMode(instance, pendingModeRef.current);
+            pendingModeRef.current = null;
+          }
+
           onReady?.();
         };
 
@@ -475,10 +485,10 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
         }
 
         superdocRef.current = null;
+        pendingModeRef.current = null;
       };
     }, [
       document?.source,
-      document?.mode,
       trigger,
       discoverFields,
       onReady,
@@ -489,6 +499,18 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
       licenseKey,
     ]);
 
+    // Apply document mode changes without recreating the editor
+    const pendingModeRef = useRef<string | null>(null);
+    useEffect(() => {
+      const mode = document?.mode || 'editing';
+      if (superdocRef.current) {
+        applyDocumentMode(superdocRef.current, mode);
+        pendingModeRef.current = null;
+      } else {
+        pendingModeRef.current = mode;
+      }
+    }, [document?.mode]);
+
     const handleMenuSelect = useCallback(
       async (field: Types.FieldDefinition) => {
         if (triggerCleanupRef.current) {
@@ -638,6 +660,11 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
       nextField,
       previousField,
       getFields: () => templateFields,
+      refresh: () => {
+        if (superdocRef.current?.activeEditor) {
+          discoverFields(superdocRef.current.activeEditor);
+        }
+      },
       exportTemplate,
       getSuperDoc: () => superdocRef.current,
     }));

packages/template-builder/src/types.ts

@@ -161,6 +161,8 @@ export interface SuperDocTemplateBuilderHandle {
   nextField: () => void;
   previousField: () => void;
   getFields: () => TemplateField[];
+  /** Re-discover fields from the editor and notify via onFieldsChange */
+  refresh: () => void;
   exportTemplate: (config?: ExportConfig) => Promise<void | Blob>;
   /**
    * Returns the SuperDoc instance.