feat(template-builder): wire lockMode through field insertion paths (#2721)

* feat(template-builder): wire lockMode through field insertion paths

SuperDoc core already enforces SDT lock modes (SD-1616), but Template
Builder never passed lockMode to the editor commands. This adds:

- LockMode type and lockMode prop on FieldDefinition / TemplateField
- defaultLockMode prop on SuperDocTemplateBuilderProps
- lockMode threading through insertFieldInternal, handleSelectExisting,
  and handleMenuSelect
- lockMode read-back in getTemplateFieldsFromEditor

Closes SD-1866

* fix(template-builder): include lockMode in field equality check

areTemplateFieldsEqual omitted lockMode, so lock-only changes were
silently dropped by discoverFields. Also tightens the lockMode spread
guard from truthiness to nullish check for consistency with the ??
resolution above.

* docs(template-builder): add lockMode and defaultLockMode

Documents field locking in configuration guide and API reference.

* feat(template-builder): add lock mode selector to field creation form

Adds a dropdown to the default FieldMenu create form so users can
set a lock mode when creating new fields. Options: No lock, Unlocked,
Container locked, Content locked, Fully locked.

* fix(template-builder): respect lock mode in delete and show lock badge

- deleteField no longer force-removes locked fields from state when
  the editor command is rejected by the lock plugin
- FieldList sidebar shows a lock icon for fields with active lock modes

* refactor(template-builder): simplify lock UI to a checkbox

- Revert lock guard in deleteField — template authors can always
  delete fields regardless of lock mode
- Replace 5-option lock dropdown with a simple "Locked" checkbox
  that maps to contentLocked
- Full LockMode type still available for programmatic use

* docs(template-builder): simplify lock mode documentation

Focus on contentLocked as the default, remove the 4-mode table,
clarify that locking only affects end users not template authors.

Author: caio-pizzol

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

@@ -75,6 +75,10 @@ None - the component works with zero configuration.
   - `object` — full toolbar configuration (see ToolbarConfig)
 </ParamField>
 
+<ParamField path="defaultLockMode" type="'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked'">
+  Lock mode for all inserted fields. Per-field `lockMode` overrides this. See [lock modes](/extensions/structured-content#lock-modes).
+</ParamField>
+
 <ParamField path="cspNonce" type="string">
   Content Security Policy nonce for dynamically injected styles
 </ParamField>
@@ -174,6 +178,7 @@ interface FieldDefinition {
   mode?: "inline" | "block";       // Insertion mode (default: "inline")
   group?: string;                  // Group ID for linked fields
   fieldType?: string;              // Field type, e.g. "owner" or "signer" (default: "owner")
+  lockMode?: LockMode;             // Lock mode for this field (overrides defaultLockMode)
 }
 ```
 
@@ -190,6 +195,7 @@ interface TemplateField {
   mode?: "inline" | "block"; // Rendering mode
   group?: string;            // Group ID for linked fields
   fieldType?: string;        // Field type, e.g. "owner" or "signer"
+  lockMode?: LockMode;       // Current lock mode of this field
 }
 ```
 
@@ -426,6 +432,7 @@ import type {
   SuperDocTemplateBuilderHandle,
   FieldDefinition,
   TemplateField,
+  LockMode,
   TriggerEvent,
   ExportEvent,
   ExportConfig,

apps/docs/solutions/template-builder/configuration.mdx

@@ -110,6 +110,26 @@ Allow users to create new fields while building templates:
 
 When enabled, the field menu shows a "Create New Field" option with inputs for name, mode (inline/block), and field type (owner/signer).
 
+### Field locking
+
+Make fields read-only so end users can't edit their content:
+
+```tsx
+<SuperDocTemplateBuilder
+  defaultLockMode="contentLocked"
+  fields={{
+    available: [
+      { id: "1", label: "Customer Name" },
+      { id: "2", label: "Notes", lockMode: "unlocked" }, // this one stays editable
+    ],
+  }}
+/>
+```
+
+Per-field `lockMode` overrides `defaultLockMode`. The default field creation form includes a "Locked" checkbox that sets `contentLocked`.
+
+Template authors can always delete and manage fields regardless of lock mode — locking only affects end users interacting with the document. For advanced use cases, see [lock modes](/extensions/structured-content#lock-modes).
+
 ### Linked fields
 
 When a user selects an existing field from the "Existing Fields" section in the menu, a linked copy is inserted. Both instances share a group ID and stay in sync.

packages/template-builder/src/defaults/FieldList.tsx

@@ -124,6 +124,21 @@ const FieldItem: FC<{
               {field.fieldType}
             </span>
           )}
+          {field.lockMode && field.lockMode !== 'unlocked' && (
+            <span
+              style={{
+                fontSize: '9px',
+                padding: '2px 5px',
+                borderRadius: '3px',
+                background: '#fef2f2',
+                color: '#991b1b',
+                fontWeight: '500',
+              }}
+              title={field.lockMode}
+            >
+              🔒
+            </span>
+          )}
         </div>
       </div>
     </div>

packages/template-builder/src/defaults/FieldMenu.tsx

@@ -20,6 +20,7 @@ export const FieldMenu: React.FC<FieldMenuProps> = ({
   const [newFieldName, setNewFieldName] = useState('');
   const [fieldMode, setFieldMode] = useState<'inline' | 'block'>('inline');
   const [fieldType, setFieldType] = useState<string>('owner');
+  const [fieldLocked, setFieldLocked] = useState(false);
   const [existingExpanded, setExistingExpanded] = useState(true);
   const [availableExpanded, setAvailableExpanded] = useState(true);
 
@@ -29,6 +30,7 @@ export const FieldMenu: React.FC<FieldMenuProps> = ({
       setNewFieldName('');
       setFieldMode('inline');
       setFieldType('owner');
+      setFieldLocked(false);
     }
   }, [isVisible]);
 
@@ -69,6 +71,7 @@ export const FieldMenu: React.FC<FieldMenuProps> = ({
       label: trimmedName,
       mode: fieldMode,
       fieldType: fieldType,
+      ...(fieldLocked && { lockMode: 'contentLocked' as const }),
     };
 
     try {
@@ -83,6 +86,7 @@ export const FieldMenu: React.FC<FieldMenuProps> = ({
       setNewFieldName('');
       setFieldMode('inline');
       setFieldType('owner');
+      setFieldLocked(false);
     }
   };
 
@@ -131,6 +135,7 @@ export const FieldMenu: React.FC<FieldMenuProps> = ({
                 setIsCreating(false);
                 setNewFieldName('');
                 setFieldMode('inline');
+                setFieldLocked(false);
               }
             }}
             autoFocus
@@ -227,6 +232,19 @@ export const FieldMenu: React.FC<FieldMenuProps> = ({
               Signer
             </label>
           </div>
+          <div
+            style={{
+              marginTop: '8px',
+              display: 'flex',
+              gap: '12px',
+              fontSize: '13px',
+            }}
+          >
+            <label style={{ display: 'flex', alignItems: 'center', gap: '4px', cursor: 'pointer' }}>
+              <input type='checkbox' checked={fieldLocked} onChange={(e) => setFieldLocked(e.target.checked)} />
+              Locked
+            </label>
+          </div>
           <div
             style={{
               marginTop: '8px',
@@ -254,6 +272,7 @@ export const FieldMenu: React.FC<FieldMenuProps> = ({
                 setNewFieldName('');
                 setFieldMode('inline');
                 setFieldType('owner');
+                setFieldLocked(false);
               }}
               style={{
                 padding: '4px 12px',

packages/template-builder/src/index.tsx

@@ -39,6 +39,7 @@ const getTemplateFieldsFromEditor = (editor: Editor): Types.TemplateField[] => {
       mode,
       group: structuredContentHelpers.getGroup?.(attrs.tag) ?? undefined,
       fieldType: parsedTag?.fieldType ?? 'owner',
+      lockMode: attrs.lockMode ?? undefined,
     } as Types.TemplateField;
   });
 };
@@ -51,6 +52,7 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
       menu = {},
       list = {},
       toolbar,
+      defaultLockMode,
       cspNonce,
       telemetry,
       licenseKey,
@@ -139,22 +141,18 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
               })
             : undefined;
 
+        const lockMode = field.lockMode ?? defaultLockMode;
+
+        const attrs: Record<string, unknown> = {
+          alias: field.alias,
+          tag: tagData,
+          ...(lockMode != null && { lockMode }),
+        };
+
         const success = (
           mode === 'inline'
-            ? editor.commands.insertStructuredContentInline?.({
-                attrs: {
-                  alias: field.alias,
-                  tag: tagData,
-                },
-                text: field.defaultValue || field.alias,
-              })
-            : editor.commands.insertStructuredContentBlock?.({
-                attrs: {
-                  alias: field.alias,
-                  tag: tagData,
-                },
-                text: field.defaultValue || field.alias,
-              })
+            ? editor.commands.insertStructuredContentInline?.({ attrs, text: field.defaultValue || field.alias })
+            : editor.commands.insertStructuredContentBlock?.({ attrs, text: field.defaultValue || field.alias })
         ) as boolean | undefined;
 
         if (success) {
@@ -174,7 +172,7 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
 
         return success ?? false;
       },
-      [onFieldInsert, onFieldsChange, templateFields],
+      [onFieldInsert, onFieldsChange, templateFields, defaultLockMode],
     );
 
     const updateField = useCallback(
@@ -485,6 +483,7 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
               metadata: createdField.metadata,
               defaultValue: createdField.defaultValue,
               fieldType: createdField.fieldType,
+              lockMode: createdField.lockMode,
             });
             setMenuVisible(false);
             return;
@@ -496,6 +495,7 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
           metadata: field.metadata,
           defaultValue: field.defaultValue,
           fieldType: field.fieldType,
+          lockMode: field.lockMode,
         });
         setMenuVisible(false);
       },
@@ -526,23 +526,18 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
         });
 
         const mode = field.mode || 'inline';
+        const lockMode = field.lockMode ?? defaultLockMode;
+
+        const attrs: Record<string, unknown> = {
+          alias: field.alias,
+          tag: tagWithGroup,
+          ...(lockMode != null && { lockMode }),
+        };
 
         const success =
           mode === 'inline'
-            ? editor.commands.insertStructuredContentInline?.({
-                attrs: {
-                  alias: field.alias,
-                  tag: tagWithGroup,
-                },
-                text: field.alias,
-              })
-            : editor.commands.insertStructuredContentBlock?.({
-                attrs: {
-                  alias: field.alias,
-                  tag: tagWithGroup,
-                },
-                text: field.alias,
-              });
+            ? editor.commands.insertStructuredContentInline?.({ attrs, text: field.alias })
+            : editor.commands.insertStructuredContentBlock?.({ attrs, text: field.alias });
 
         if (success) {
           if (!field.group) {
@@ -556,7 +551,7 @@ const SuperDocTemplateBuilder = forwardRef<Types.SuperDocTemplateBuilderHandle,
           onFieldsChange?.(updatedFields);
         }
       },
-      [updateField, resetMenuFilter, onFieldsChange],
+      [updateField, resetMenuFilter, onFieldsChange, defaultLockMode],
     );
 
     const handleMenuClose = useCallback(() => {

packages/template-builder/src/tests/utils.test.ts

@@ -72,6 +72,18 @@ describe('areTemplateFieldsEqual', () => {
     const b: TemplateField[] = [{ id: '1', alias: 'Name', fieldType: 'signer' }];
     expect(areTemplateFieldsEqual(a, b)).toBe(false);
   });
+
+  it('returns false when lockMode differs', () => {
+    const a: TemplateField[] = [{ id: '1', alias: 'Name', lockMode: 'unlocked' }];
+    const b: TemplateField[] = [{ id: '1', alias: 'Name', lockMode: 'sdtContentLocked' }];
+    expect(areTemplateFieldsEqual(a, b)).toBe(false);
+  });
+
+  it('returns true when lockMode is the same', () => {
+    const a: TemplateField[] = [{ id: '1', alias: 'Name', lockMode: 'contentLocked' }];
+    const b: TemplateField[] = [{ id: '1', alias: 'Name', lockMode: 'contentLocked' }];
+    expect(areTemplateFieldsEqual(a, b)).toBe(true);
+  });
 });
 
 describe('resolveToolbar', () => {

packages/template-builder/src/types.ts

@@ -1,5 +1,7 @@
 import type { SuperDoc } from 'superdoc';
 
+export type LockMode = 'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked';
+
 /** Field definition for template builder */
 export interface FieldDefinition {
   id: string;
@@ -9,6 +11,7 @@ export interface FieldDefinition {
   mode?: 'inline' | 'block';
   group?: string;
   fieldType?: string;
+  lockMode?: LockMode;
 }
 
 /** Field instance in a template document */
@@ -20,6 +23,7 @@ export interface TemplateField {
   mode?: 'inline' | 'block';
   group?: string;
   fieldType?: string;
+  lockMode?: LockMode;
 }
 
 export interface TriggerEvent {
@@ -114,6 +118,9 @@ export interface SuperDocTemplateBuilderProps {
   list?: ListConfig;
   toolbar?: boolean | string | ToolbarConfig;
 
+  /** Lock mode applied to all inserted fields unless overridden per-field */
+  defaultLockMode?: LockMode;
+
   /** Content Security Policy nonce for dynamically injected styles */
   cspNonce?: string;
 

packages/template-builder/src/utils.ts

@@ -18,7 +18,8 @@ export const areTemplateFieldsEqual = (a: TemplateField[], b: TemplateField[]):
       left.position !== right.position ||
       left.mode !== right.mode ||
       left.group !== right.group ||
-      left.fieldType !== right.fieldType
+      left.fieldType !== right.fieldType ||
+      left.lockMode !== right.lockMode
     ) {
       return false;
     }