chore: promote main to stable

Author: github-actions[bot]

.github/workflows/release-package.yml

@@ -52,14 +52,22 @@ jobs:
         run: |
           pnpm dlx semantic-release
 
-      - name: Sync stable back to main
+      - name: Create sync PR to main
         if: github.ref == 'refs/heads/stable'
         env:
           GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
+          GH_TOKEN: ${{ steps.generate_token.outputs.token }}
         run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git fetch origin main stable
-          git checkout main
-          git merge origin/stable -m "chore: sync stable release to main"
-          git push origin main
+          pr_number=$(gh pr list --base main --head stable --state open --json number --jq '.[0].number')
+          if [ -z "$pr_number" ]; then
+            git fetch origin main
+            if git diff --quiet origin/main...HEAD; then
+              echo "Main is already up to date with stable; skipping PR."
+              exit 0
+            fi
+            pr_number=$(gh pr create --base main --head stable --title "chore: sync stable release to main" --body "Automated PR to merge the latest stable changes back into main." --json number --jq '.number')
+            echo "Created PR #$pr_number to sync stable into main."
+          else
+            echo "PR #$pr_number already open to sync stable into main."
+          fi
+          gh pr merge "$pr_number" --merge --auto || echo "Auto-merge setup skipped (conditions not met)."

.gitignore

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

README.md

@@ -24,9 +24,9 @@ function TemplateEditor() {
 
       fields={{
         available: [
-          { id: 'customer_name', label: 'Customer Name', category: 'Contact' },
-          { id: 'invoice_date', label: 'Invoice Date', category: 'Invoice' },
-          { id: 'amount', label: 'Amount', category: 'Invoice' }
+          { id: '1324567890', label: 'Customer Name', category: 'Contact' },
+          { id: '1324567891', label: 'Invoice Date', category: 'Invoice' },
+          { id: '1324567892', label: 'Amount', category: 'Invoice' }
         ]
       }}
 
@@ -47,8 +47,8 @@ function TemplateEditor() {
 ```javascript
 {
   fields: [
-    { id: "field_123", alias: "Customer Name", tag: "contact" },
-    { id: "field_124", alias: "Invoice Date", tag: "invoice" }
+    { id: "1324567890", alias: "Customer Name", tag: "contact" },
+    { id: "1324567891", alias: "Invoice Date", tag: "invoice" }
   ],
   document: { /* ProseMirror document JSON */ }
 }
@@ -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);

demo/src/App.css

@@ -83,6 +83,12 @@ header {
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
 }
 
+.toolbar-right {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+}
+
 .toolbar-left {
     display: flex;
     align-items: center;
@@ -113,6 +119,38 @@ header {
     background: #0051d5;
 }
 
+.export-button:disabled,
+.import-button:disabled {
+    cursor: not-allowed;
+    opacity: 0.7;
+}
+
+.import-button {
+    padding: 0.5rem 1.25rem;
+    background: white;
+    color: #007aff;
+    border: 1px solid #b0d4ff;
+    border-radius: 8px;
+    font-weight: 600;
+    cursor: pointer;
+    transition: background 0.2s, color 0.2s, border-color 0.2s;
+}
+
+.import-button:hover {
+    background: #e8f2ff;
+    border-color: #007aff;
+}
+
+.toolbar-error {
+    margin-top: 0.75rem;
+    padding: 0.75rem 1rem;
+    background: #fef2f2;
+    color: #b91c1c;
+    border: 1px solid #fecaca;
+    border-radius: 8px;
+    font-size: 0.875rem;
+}
+
 /* Template Builder Container */
 .superdoc-template-builder {
     background: white;

demo/src/App.tsx

@@ -9,44 +9,38 @@ 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" },
-
-  // Company Information
-  { id: 'company_name', label: 'Company Name', category: 'Company' },
-  { id: 'company_address', label: 'Company Address', category: 'Company' },
-  { id: 'company_phone', label: 'Company Phone', category: 'Company' },
-  { id: 'company_email', label: 'Company Email', category: 'Company' },
-
-  // Invoice/Order
-  { id: 'invoice_number', label: 'Invoice Number', category: 'Invoice' },
-  { id: 'invoice_date', label: 'Invoice Date', category: 'Invoice' },
-  { id: 'due_date', label: 'Due Date', category: 'Invoice' },
-  { id: 'total_amount', label: 'Total Amount', category: 'Invoice' },
-  { id: 'tax_amount', label: 'Tax Amount', category: 'Invoice' },
-  { id: 'subtotal', label: 'Subtotal', category: 'Invoice' },
+  // Agreement
+  { id: '1242142770', label: 'Agreement Date', category: 'Agreement' },
+
+  // Parties
+  { id: '1242142771', label: 'User Name', category: 'Parties' },
+  { id: '1242142772', label: 'Company Name', category: 'Parties' },
+
+  // Scope
+  { id: '1242142773', label: 'Service Type', category: 'Scope' },
 
   // Legal
-  { id: 'effective_date', label: 'Effective Date', category: 'Legal' },
-  { id: 'termination_date', label: 'Termination Date', category: 'Legal' },
-  { id: 'jurisdiction', label: 'Jurisdiction', category: 'Legal' },
-  { id: 'governing_law', label: 'Governing Law', category: 'Legal' },
-
-  // Product/Service
-  { id: 'product_name', label: 'Product Name', category: 'Product' },
-  { id: 'product_description', label: 'Product Description', category: 'Product' },
-  { id: 'quantity', label: 'Quantity', category: 'Product' },
-  { id: 'unit_price', label: 'Unit Price', category: 'Product' },
+  { id: '1242142774', label: 'Agreement Jurisdiction', category: 'Legal' },
+
+  // Company Details
+  { id: '1242142775', label: 'Company Address', category: 'Company' },
+
+  // Signatures
+  { id: '1242142776', label: 'Signature', category: 'Signatures' },
 ];
 
 export function App() {
   const [fields, setFields] = useState<TemplateField[]>([]);
   const [events, setEvents] = useState<string[]>([]);
   const [isDownloading, setIsDownloading] = useState(false);
+  const [isImporting, setIsImporting] = useState(false);
+  const [importError, setImportError] = useState<string | null>(null);
+  const [documentSource, setDocumentSource] = useState<string | File>(
+    "https://storage.googleapis.com/public_static_hosting/public_demo_docs/new_service_agreement.docx",
+  );
   const builderRef = useRef<SuperDocTemplateBuilderHandle>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const importingRef = useRef(false);
 
   const log = useCallback((msg: string) => {
     const time = new Date().toLocaleTimeString();
@@ -63,7 +57,7 @@ export function App() {
     log(`✓ Inserted: ${field.alias}`);
   }, [log]);
 
-  const handleFieldDelete = useCallback((fieldId: string) => {
+  const handleFieldDelete = useCallback((fieldId: string | number) => {
     log(`✗ Deleted: ${fieldId}`);
   }, [log]);
 
@@ -75,6 +69,12 @@ export function App() {
 
   const handleReady = useCallback(() => {
     log('✓ Template builder ready');
+    if (importingRef.current) {
+      log('📄 Document imported');
+      importingRef.current = false;
+      setImportError(null);
+      setIsImporting(false);
+    }
   }, [log]);
 
   const handleTrigger = useCallback(() => {
@@ -114,9 +114,35 @@ export function App() {
   };
 
   const documentConfig = useMemo(() => ({
-    source: "https://storage.googleapis.com/public_static_hosting/public_demo_docs/service_agreement.docx",
+    source: documentSource,
     mode: 'editing' as const
-  }), []);
+  }), [documentSource]);
+
+  const handleImportButtonClick = useCallback(() => {
+    if (isImporting) return;
+    fileInputRef.current?.click();
+  }, [isImporting]);
+
+  const handleFileInputChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0];
+    event.target.value = "";
+
+    if (!file) return;
+
+    const extension = file.name.split('.').pop()?.toLowerCase();
+    if (extension !== 'docx') {
+      const message = 'Invalid file type. Please choose a .docx file.';
+      setImportError(message);
+      log('⚠️ ' + message);
+      return;
+    }
+
+    importingRef.current = true;
+    setImportError(null);
+    setIsImporting(true);
+    setDocumentSource(file);
+    log(`📥 Importing "${file.name}"`);
+  }, [log]);
 
   const fieldsConfig = useMemo(() => ({
     available: availableFields,
@@ -160,16 +186,36 @@ export function App() {
             <span className="hint">Tab/Shift+Tab to navigate</span>
           </div>
           <div className="toolbar-right">
+            <input
+              type="file"
+              accept=".docx"
+              ref={fileInputRef}
+              style={{ display: 'none' }}
+              onChange={handleFileInputChange}
+            />
+            <button
+              onClick={handleImportButtonClick}
+              className="import-button"
+              disabled={isImporting || isDownloading}
+            >
+              {isImporting ? 'Importing…' : 'Import File'}
+            </button>
             <button
               onClick={handleExportTemplate}
               className="export-button"
-              disabled={isDownloading}
+              disabled={isDownloading || isImporting}
             >
               {isDownloading ? "Exporting..." : "Export Template"}
             </button>
           </div>
         </div>
 
+        {importError && (
+          <div className="toolbar-error" role="alert">
+            {importError}
+          </div>
+        )}
+
         <SuperDocTemplateBuilder
           ref={builderRef}
           document={documentConfig}