chore: update documentation and improve types

Author: bendersej

react/README.md

@@ -122,31 +122,74 @@ import { EmbedPDF } from '@simplepdf/react-embed-pdf';
 
 ### Programmatic Control
 
-_Requires a SimplePDF account_
+_Some actions require a SimplePDF account_
 
 Use `const { embedRef, actions } = useEmbed();` to programmatically control the embed editor:
 
-- `actions.submit`: Submit the document (specify or not whether to download a copy of the document on the device of the user)
-- `actions.selectTool`: Select a tool to use
+| Action                                           | Description                                                                                                         |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `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.getDocumentContent({ extractionMode })` | Extract document content (`extractionMode: 'auto'` or `'ocr'`)                                                      |
+| `actions.submit({ downloadCopyOnDevice })`       | Submit the document                                                                                                 |
 
-```jsx
-import { EmbedPDF, useEmbed } from "@simplepdf/react-embed-pdf";
-
-const { embedRef, actions } = useEmbed();
+All actions return a `Promise` with a result object: `{ success: true, data: ... }` or `{ success: false, error: { code, message } }`.
 
-return (
-   <>
-      <button onClick={() => await actions.submit({ downloadCopyOnDevice: false })}>Submit</button>
-      <button onClick={() => await actions.selectTool('TEXT')}>Select Text Tool</button>
+```jsx
+import { EmbedPDF, useEmbed } from '@simplepdf/react-embed-pdf';
+
+const Editor = () => {
+  const { embedRef, actions } = useEmbed();
+
+  const handleSubmit = async () => {
+    const result = await actions.submit({ downloadCopyOnDevice: false });
+    if (result.success) {
+      console.log('Submitted!');
+    }
+  };
+
+  const handleExtract = async () => {
+    const result = await actions.getDocumentContent({ extractionMode: 'auto' });
+    if (result.success) {
+      console.log('Document name:', result.data.name);
+      console.log('Pages:', result.data.pages);
+    }
+  };
+
+  const handleCreateTextField = async () => {
+    const result = await actions.createField({
+      type: 'TEXT',
+      page: 1,
+      x: 100,
+      y: 200,
+      width: 150,
+      height: 30,
+      value: 'Hello World',
+    });
+    if (result.success) {
+      console.log('Created field:', result.data.field_id);
+    }
+  };
+
+  return (
+    <>
+      <button onClick={handleSubmit}>Submit</button>
+      <button onClick={handleExtract}>Extract Content</button>
+      <button onClick={handleCreateTextField}>Add Text Field</button>
+      <button onClick={() => actions.selectTool('TEXT')}>Select Text Tool</button>
+      <button onClick={() => actions.goTo({ page: 2 })}>Go to Page 2</button>
       <EmbedPDF
-         companyIdentifier="yourcompany"
-         ref={embedRef}
-         mode="inline"
-         style={{ width: 900, height: 800 }}
-         documentURL="https://cdn.simplepdf.com/simple-pdf/assets/sample.pdf"
+        companyIdentifier="yourcompany"
+        ref={embedRef}
+        mode="inline"
+        style={{ width: 900, height: 800 }}
+        documentURL="https://cdn.simplepdf.com/simple-pdf/assets/sample.pdf"
       />
-   </>
-);
+    </>
+  );
+};
 ```
 
 ### <a id="available-props"></a>Available props
@@ -160,19 +203,19 @@ return (
   </tr>
   <tr>
     <td>ref</td>
-    <td>EmbedRefHandlers</td>
+    <td>EmbedActions</td>
     <td>No</td>
-    <td>Used for programmatic control of the editor</td>
+    <td>Used for programmatic control of the editor (see Programmatic Control section)</td>
   </tr>
   <tr>
     <td>mode</td>
     <td>"inline" | "modal"</td>
     <td>No (defaults to "modal")</td>
     <td>Inline the editor or display it inside a modal</td>
   </tr>
-    <tr>
+  <tr>
     <td>locale</td>
-    <td>"en" | "de" | "es" | "fr" | "it" | "pt"</td>
+    <td>"en" | "de" | "es" | "fr" | "it" | "nl" | "pt"</td>
     <td>No (defaults to "en")</td>
     <td>Language to display the editor in (ISO locale)</td>
   </tr>
@@ -188,6 +231,12 @@ return (
     <td>No</td>
     <td><a href="https://simplepdf.com/embed">Allows collecting customers submissions</a></td>
   </tr>
+  <tr>
+    <td>baseDomain</td>
+    <td>string</td>
+    <td>No</td>
+    <td>Override the base domain for self-hosted deployments (e.g., "yourdomain.com"). Contact sales@simplepdf.com for enterprise self-hosting</td>
+  </tr>
   <tr>
     <td>context</td>
     <td>Record&lt;string, unknown&gt;</td>
@@ -225,12 +274,12 @@ return (
 1. Link the widget
 
 ```sh
-yarn link
-yarn start
+npm link
+npm start
 ```
 
 2. Use it in the target application
 
 ```sh
-yarn link @simplepdf/react-embed-pdf
+npm link @simplepdf/react-embed-pdf
 ```

react/src/hook.test.ts

@@ -284,7 +284,7 @@ describe('useEmbed', () => {
 
     it('getDocumentContent returns error when embedRef not attached', async () => {
       const { result } = renderHook(() => useEmbed());
-      const actionResult = await result.current.actions.getDocumentContent({});
+      const actionResult = await result.current.actions.getDocumentContent({ extractionMode: 'auto' });
       expect(actionResult).toEqual(expectedError);
     });
 
@@ -365,9 +365,9 @@ describe('useEmbed', () => {
       const { ref, spies } = createMockEmbedRef();
       (result.current.embedRef as React.MutableRefObject<EmbedActions>).current = ref;
 
-      const actionResult = await result.current.actions.getDocumentContent({});
+      const actionResult = await result.current.actions.getDocumentContent({ extractionMode: 'auto' });
 
-      expect(spies.getDocumentContent).toHaveBeenCalledWith({});
+      expect(spies.getDocumentContent).toHaveBeenCalledWith({ extractionMode: 'auto' });
       expect(actionResult).toEqual({ success: true });
     });
 

react/src/hook.tsx

@@ -55,7 +55,7 @@ export type EmbedActions = {
 
   clearFields: (options?: { fieldIds?: string[]; page?: number }) => Promise<ActionResult<ClearFieldsResult>>;
 
-  getDocumentContent: (options?: { extractionMode?: ExtractionMode }) => Promise<ActionResult<DocumentContentResult>>;
+  getDocumentContent: (options: { extractionMode: ExtractionMode }) => Promise<ActionResult<DocumentContentResult>>;
 
   submit: (options: { downloadCopyOnDevice: boolean }) => Promise<ActionResult>;
 };
@@ -175,7 +175,7 @@ export const useEmbed = (): { embedRef: React.RefObject<EmbedActions | null>; ac
   );
 
   const handleGetDocumentContent = React.useCallback(
-    createAction<[{ extractionMode?: ExtractionMode }?], DocumentContentResult>(async (ref, options) => {
+    createAction<[{ extractionMode: ExtractionMode }], DocumentContentResult>(async (ref, options) => {
       return ref.getDocumentContent(options);
     }),
     [],

react/src/index.test.tsx

@@ -508,7 +508,7 @@ describe('EmbedPDF', () => {
           throw new Error('Expected ref to be available');
         }
 
-        const resultPromise = ref.current.getDocumentContent({});
+        const resultPromise = ref.current.getDocumentContent({ extractionMode: 'auto' });
 
         await waitFor(() => {
           expect(mockContentWindow.postMessage).toHaveBeenCalled();

react/src/index.tsx

@@ -207,7 +207,7 @@ export const EmbedPDF = React.forwardRef<EmbedActions, Props>((props, ref) => {
     await ensureEditorReady();
     return sendEvent(iframeRef.current, {
       type: 'GET_DOCUMENT_CONTENT',
-      data: { extraction_mode: options?.extractionMode },
+      data: { extraction_mode: options.extractionMode },
     });
   }, []);