fix: rename CLEAR_FIELDS to REMOVE_FIELDS and clearFields to removeFields

Rename iframe event CLEAR_FIELDS to REMOVE_FIELDS and response field
cleared_count to removed_count. Rename React embed action clearFields
to removeFields. Update all docs, examples, and tests accordingly.

Author: bendersej

README.md

@@ -286,7 +286,7 @@ Currently, page manipulation (add/remove/re-arrange/rotate) is only available th
 | `goTo`                 | Navigate to a specific page                                                                                |
 | `selectTool`           | Select a tool (`TEXT`, `BOXED_TEXT`, `CHECKBOX`, `PICTURE`, `SIGNATURE`) or `null` for cursor              |
 | `createField`          | Create a field at a specified position                                                                     |
-| `clearFields`          | Clear fields by ID, by page, or all fields                                                                 |
+| `removeFields`         | Remove fields by ID, by page, or all fields                                                                |
 | `getDocumentContent`   | Extract text content from the document                                                                     |
 | `submit`               | Submit the document (with optional device download)                                                        |
 | `loadDocument` (Iframe)| Load a document programmatically (Iframe API only)                                                         |

documentation/IFRAME.md

@@ -196,12 +196,12 @@ await sendEvent("CREATE_FIELD", {
   value: "Hello World",
 });
 
-// Clear all fields (or specific ones)
-await sendEvent("CLEAR_FIELDS", {}); // Clear all
-await sendEvent("CLEAR_FIELDS", { page: 1 }); // Clear page 1 only
-await sendEvent("CLEAR_FIELDS", {
+// Remove all fields (or specific ones)
+await sendEvent("REMOVE_FIELDS", {}); // Remove all
+await sendEvent("REMOVE_FIELDS", { page: 1 }); // Remove page 1 only
+await sendEvent("REMOVE_FIELDS", {
   field_ids: ["f_kj8n2hd9x3m1p", "f_q7v5c4b6a0wyz"],
-}); // Clear specific fields
+}); // Remove specific fields
 
 // Extract document content
 const content = await sendEvent("GET_DOCUMENT_CONTENT", {
@@ -319,20 +319,20 @@ Create a new field on the document.
 }
 ```
 
-#### CLEAR_FIELDS
+#### REMOVE_FIELDS
 
 Remove fields from the document.
 
 | Field       | Type       | Required | Description                                      |
 | ----------- | ---------- | -------- | ------------------------------------------------ |
-| `field_ids` | `string[]` | No       | Specific field IDs to remove (omit to clear all) |
-| `page`      | `number`   | No       | Only clear fields on this page                   |
+| `field_ids` | `string[]` | No       | Specific field IDs to remove (omit to remove all) |
+| `page`      | `number`   | No       | Only remove fields on this page                   |
 
 **Response data:**
 
 ```json
 {
-  "cleared_count": 5
+  "removed_count": 5
 }
 ```
 

examples/with-playwright-automation/README.md

@@ -247,7 +247,7 @@ The tool uses the SimplePDF editor's iframe postMessage API:
 
 1. Embeds the editor in an iframe
 2. Waits for `DOCUMENT_LOADED` event
-3. Sends `CLEAR_FIELDS` to remove existing fields
+3. Sends `REMOVE_FIELDS` to remove existing fields
 4. Sends `CREATE_FIELD` for each configured field
 5. Leaves browser open for inspection
 

examples/with-playwright-automation/src/automation.ts

@@ -6,7 +6,7 @@ import type { AutomationConfig } from './schema';
 type AutomationErrorCode =
   | 'document_load_failed'
   | 'field_creation_failed'
-  | 'clear_fields_failed';
+  | 'remove_fields_failed';
 
 type AutomationResult =
   | { success: true; data: null }
@@ -217,17 +217,17 @@ const runAutomation = async ({ config, baseUrl }: RunAutomationArgs): Promise<Au
     await waitForDocumentLoaded();
     console.log('Document loaded');
 
-    console.log('Clearing existing fields...');
-    const clearRequestId = await sendEvent({ type: 'CLEAR_FIELDS', data: {} });
-    const clearResult = await waitForEvent('REQUEST_RESULT', { requestId: clearRequestId });
+    console.log('Removing existing fields...');
+    const removeRequestId = await sendEvent({ type: 'REMOVE_FIELDS', data: {} });
+    const removeResult = await waitForEvent('REQUEST_RESULT', { requestId: removeRequestId });
 
-    if (!isRequestResultData(clearResult.event.data) || !clearResult.event.data.result.success) {
+    if (!isRequestResultData(removeResult.event.data) || !removeResult.event.data.result.success) {
       return {
         success: false,
-        error: { code: 'clear_fields_failed', message: 'Failed to clear existing fields' },
+        error: { code: 'remove_fields_failed', message: 'Failed to remove existing fields' },
       };
     }
-    console.log('Fields cleared');
+    console.log('Fields removed');
 
     console.log(`Creating ${config.fields.length} fields...`);
     for (let i = 0; i < config.fields.length; i++) {

react/CHANGELOG.md

@@ -4,4 +4,4 @@
 
 ### Minor Changes
 
-- cae5ce6: Adds new programmatic actions to the React embed component for advanced integrations: goTo, createField, clearFields, getDocumentContent
+- cae5ce6: Adds new programmatic actions to the React embed component for advanced integrations: goTo, createField, removeFields, getDocumentContent

react/README.md

@@ -131,7 +131,7 @@ Use `const { embedRef, actions } = useEmbed();` to programmatically control the
 | `actions.goTo({ page })`                         | Navigate to a specific page                                                                                         |
 | `actions.selectTool(toolType)`                   | Select a tool: `'TEXT'`, `'BOXED_TEXT'`, `'CHECKBOX'`, `'PICTURE'`, `'SIGNATURE'`, or `null` to deselect (`CURSOR`) |
 | `actions.createField(options)`                   | Create a field at specified position (see below)                                                                    |
-| `actions.clearFields(options?)`                  | Clear fields by `fieldIds` or `page`, or all fields if no options                                                   |
+| `actions.removeFields(options?)`                 | Remove fields by `fieldIds` or `page`, or all fields if no options                                                  |
 | `actions.getDocumentContent({ extractionMode })` | Extract document content (`extractionMode: 'auto'` or `'ocr'`)                                                      |
 | `actions.submit({ downloadCopyOnDevice })`       | Submit the document                                                                                                 |
 

react/src/hook.test.ts

@@ -260,9 +260,9 @@ describe('useEmbed', () => {
       expect(actionResult).toEqual(expectedError);
     });
 
-    it('clearFields returns error when embedRef not attached', async () => {
+    it('removeFields returns error when embedRef not attached', async () => {
       const { result } = renderHook(() => useEmbed());
-      const actionResult = await result.current.actions.clearFields({});
+      const actionResult = await result.current.actions.removeFields({});
       expect(actionResult).toEqual(expectedError);
     });
 
@@ -288,7 +288,7 @@ describe('useEmbed', () => {
         goTo: vi.fn().mockResolvedValue({ success: true }),
         selectTool: vi.fn().mockResolvedValue({ success: true }),
         createField: vi.fn().mockResolvedValue({ success: true }),
-        clearFields: vi.fn().mockResolvedValue({ success: true }),
+        removeFields: vi.fn().mockResolvedValue({ success: true }),
         getDocumentContent: vi.fn().mockResolvedValue({ success: true }),
         submit: vi.fn().mockResolvedValue({ success: true }),
       };
@@ -333,14 +333,14 @@ describe('useEmbed', () => {
       expect(actionResult).toEqual({ success: true });
     });
 
-    it('clearFields delegates to ref.clearFields', async () => {
+    it('removeFields delegates to ref.removeFields', async () => {
       const { result } = renderHook(() => useEmbed());
       const { ref, spies } = createMockEmbedRef();
       (result.current.embedRef as React.MutableRefObject<EmbedActions>).current = ref;
 
-      const actionResult = await result.current.actions.clearFields({});
+      const actionResult = await result.current.actions.removeFields({});
 
-      expect(spies.clearFields).toHaveBeenCalledWith({});
+      expect(spies.removeFields).toHaveBeenCalledWith({});
       expect(actionResult).toEqual({ success: true });
     });
 
@@ -447,12 +447,12 @@ describe('Type assertions', () => {
       >();
     });
 
-    it('clearFields accepts optional { fieldIds?, page? } and returns ActionResult with cleared_count', () => {
-      expectTypeOf<EmbedActions['clearFields']>()
+    it('removeFields accepts optional { fieldIds?, page? } and returns ActionResult with removed_count', () => {
+      expectTypeOf<EmbedActions['removeFields']>()
         .parameter(0)
         .toEqualTypeOf<{ fieldIds?: string[]; page?: number } | undefined>();
-      expectTypeOf<EmbedActions['clearFields']>().returns.resolves.toExtend<
-        ExpectedActionResult<{ cleared_count: number }>
+      expectTypeOf<EmbedActions['removeFields']>().returns.resolves.toExtend<
+        ExpectedActionResult<{ removed_count: number }>
       >();
     });
 

react/src/hook.tsx

@@ -58,8 +58,8 @@ type DocumentContentResult = {
   pages: DocumentContentPage[];
 };
 
-type ClearFieldsResult = {
-  cleared_count: number;
+type RemoveFieldsResult = {
+  removed_count: number;
 };
 
 type CreateFieldResult = {
@@ -73,7 +73,7 @@ export type EmbedActions = {
 
   createField: (options: CreateFieldOptions) => Promise<ActionResult<CreateFieldResult>>;
 
-  clearFields: (options?: { fieldIds?: string[]; page?: number }) => Promise<ActionResult<ClearFieldsResult>>;
+  removeFields: (options?: { fieldIds?: string[]; page?: number }) => Promise<ActionResult<RemoveFieldsResult>>;
 
   getDocumentContent: (options: { extractionMode: ExtractionMode }) => Promise<ActionResult<DocumentContentResult>>;
 
@@ -184,9 +184,9 @@ export const useEmbed = (): { embedRef: React.RefObject<EmbedActions | null>; ac
     [],
   );
 
-  const handleClearFields = React.useCallback(
-    createAction<[{ fieldIds?: string[]; page?: number }?], ClearFieldsResult>(async (ref, options) => {
-      return ref.clearFields(options);
+  const handleRemoveFields = React.useCallback(
+    createAction<[{ fieldIds?: string[]; page?: number }?], RemoveFieldsResult>(async (ref, options) => {
+      return ref.removeFields(options);
     }),
     [],
   );
@@ -211,7 +211,7 @@ export const useEmbed = (): { embedRef: React.RefObject<EmbedActions | null>; ac
       goTo: handleGoTo,
       selectTool: handleSelectTool,
       createField: handleCreateField,
-      clearFields: handleClearFields,
+      removeFields: handleRemoveFields,
       getDocumentContent: handleGetDocumentContent,
       submit: handleSubmit,
     },

react/src/index.test.tsx

@@ -312,7 +312,7 @@ describe('EmbedPDF', () => {
       expect(typeof ref.current?.goTo).toBe('function');
       expect(typeof ref.current?.selectTool).toBe('function');
       expect(typeof ref.current?.createField).toBe('function');
-      expect(typeof ref.current?.clearFields).toBe('function');
+      expect(typeof ref.current?.removeFields).toBe('function');
       expect(typeof ref.current?.getDocumentContent).toBe('function');
       expect(typeof ref.current?.submit).toBe('function');
     });
@@ -325,7 +325,7 @@ describe('EmbedPDF', () => {
           action: 'createField' as const,
           args: { type: 'TEXT' as const, page: 1, x: 0, y: 0, width: 100, height: 20 },
         },
-        { action: 'clearFields' as const, args: {} },
+        { action: 'removeFields' as const, args: {} },
         { action: 'getDocumentContent' as const, args: {} },
         { action: 'submit' as const, args: { downloadCopyOnDevice: false } },
       ])('$action returns error when iframe not available (modal not opened)', async ({ action, args }) => {

react/src/index.tsx

@@ -189,13 +189,13 @@ export const EmbedPDF = React.forwardRef<EmbedActions, Props>((props, ref) => {
     });
   }, []);
 
-  const clearFields: EmbedActions['clearFields'] = React.useCallback(async (options) => {
+  const removeFields: EmbedActions['removeFields'] = React.useCallback(async (options) => {
     if (!iframeRef.current) {
       return { success: false, error: { code: 'unexpected:iframe_not_available', message: 'Iframe not available' } };
     }
     await ensureEditorReady();
     return sendEvent(iframeRef.current, {
-      type: 'CLEAR_FIELDS',
+      type: 'REMOVE_FIELDS',
       data: { field_ids: options?.fieldIds, page: options?.page },
     });
   }, []);
@@ -227,7 +227,7 @@ export const EmbedPDF = React.forwardRef<EmbedActions, Props>((props, ref) => {
     goTo,
     selectTool,
     createField,
-    clearFields,
+    removeFields,
     getDocumentContent,
     submit,
   }));