@@ -160,9 +216,9 @@ return (
| ref |
- EmbedRefHandlers |
+ EmbedActions |
No |
- Used for programmatic control of the editor |
+ Used for programmatic control of the editor (see Programmatic Control section) |
| mode |
@@ -170,9 +226,9 @@ return (
No (defaults to "modal") |
Inline the editor or display it inside a modal |
-
+
| locale |
- "en" | "de" | "es" | "fr" | "it" | "pt" |
+ "en" | "de" | "es" | "fr" | "it" | "nl" | "pt" |
No (defaults to "en") |
Language to display the editor in (ISO locale) |
@@ -188,6 +244,12 @@ return (
No |
Allows collecting customers submissions |
+
+ | baseDomain |
+ string |
+ No |
+ Override the base domain for self-hosted deployments (e.g., "yourdomain.com"). Contact sales@simplepdf.com for enterprise self-hosting |
+
| context |
Record<string, unknown> |
@@ -225,12 +287,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
```
diff --git a/react/package.json b/react/package.json
index 9e32d01..41bce3e 100644
--- a/react/package.json
+++ b/react/package.json
@@ -13,12 +13,19 @@
"author": "bendersej",
"license": "MIT",
"private": false,
+ "engines": {
+ "node": ">=18"
+ },
"scripts": {
+ "pretest": "tsc --noEmit -p tsconfig.test.json",
+ "test": "vitest run",
+ "test:watch": "vitest",
+ "test:coverage": "vitest run --coverage",
"test:types": "tsc --noEmit",
"test:format": "npm run prettier -- --check",
"prettier": "prettier .",
"format": "npm run prettier -- --write",
- "prepublishOnly": "rimraf dist && yarn build",
+ "prepublishOnly": "rimraf dist && npm run build",
"build": "rollup -c",
"start": "rollup -c -w"
},
@@ -28,9 +35,15 @@
},
"devDependencies": {
"@rollup/plugin-terser": "^0.4.4",
+ "@testing-library/dom": "10.4.1",
+ "@testing-library/jest-dom": "^6.9.1",
+ "@testing-library/react": "16.3.1",
+ "@testing-library/user-event": "^14.6.1",
"@types/react": "*",
"@types/react-dom": "*",
+ "@vitest/coverage-v8": "4.0.17",
"autoprefixer": "^10.4.18",
+ "jsdom": "26.1.0",
"postcss": "^8.4.35",
"prettier": "^3.4.2",
"react": "^18.2.0",
@@ -40,7 +53,8 @@
"rollup-plugin-scss": "^4.0.0",
"rollup-plugin-typescript2": "^0.36.0",
"sass": "^1.71.1",
- "typescript": "^5.7.3"
+ "typescript": "^5.9.3",
+ "vitest": "4.0.17"
},
"files": ["dist"],
"keywords": ["react", "typescript", "npm", "pdf"]
diff --git a/react/rollup.config.js b/react/rollup.config.js
index 6088509..ffa5666 100644
--- a/react/rollup.config.js
+++ b/react/rollup.config.js
@@ -3,8 +3,10 @@ import postcss from 'postcss';
import autoprefixer from 'autoprefixer';
import typescript from 'rollup-plugin-typescript2';
import terser from '@rollup/plugin-terser';
+import { createRequire } from 'module';
-import pkg from './package.json' assert { type: 'json' };
+const require = createRequire(import.meta.url);
+const pkg = require('./package.json');
export default {
input: 'src/index.tsx',
diff --git a/react/src/hook.test.ts b/react/src/hook.test.ts
new file mode 100644
index 0000000..8aac7df
--- /dev/null
+++ b/react/src/hook.test.ts
@@ -0,0 +1,551 @@
+import { describe, it, expect, vi, beforeEach, afterEach, expectTypeOf } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { sendEvent, useEmbed, EmbedActions } from './hook';
+
+type MessageEventHandler = (event: MessageEvent) => void;
+
+interface MockContentWindow {
+ postMessage: ReturnType;
+}
+
+interface MockIframe {
+ contentWindow: MockContentWindow;
+}
+
+const createMockIframe = (): { iframe: MockIframe; postMessageSpy: ReturnType } => {
+ const postMessageSpy = vi.fn();
+ return {
+ iframe: { contentWindow: { postMessage: postMessageSpy } },
+ postMessageSpy,
+ };
+};
+
+const extractRequestId = (postMessageSpy: ReturnType): string => {
+ const rawMessage = postMessageSpy.mock.calls[0]?.[0];
+ if (typeof rawMessage !== 'string') {
+ throw new Error('Expected postMessage to be called with a string');
+ }
+ const parsed = JSON.parse(rawMessage);
+ return parsed.request_id;
+};
+
+const createMessageEvent = ({
+ source,
+ data,
+}: {
+ source: MockContentWindow | Record;
+ data: string;
+}): MessageEvent => ({ source, data }) as unknown as MessageEvent;
+
+describe('sendEvent', () => {
+ let removeEventListenerSpy: ReturnType;
+ let messageHandler: MessageEventHandler | null = null;
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+
+ vi.spyOn(window, 'addEventListener').mockImplementation((type, handler) => {
+ if (type === 'message') {
+ messageHandler = handler as MessageEventHandler;
+ }
+ });
+
+ removeEventListenerSpy = vi.spyOn(window, 'removeEventListener').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+ messageHandler = null;
+ });
+
+ it('resolves with result when matching REQUEST_RESULT received', async () => {
+ const { iframe } = createMockIframe();
+
+ const resultPromise = sendEvent(iframe as unknown as HTMLIFrameElement, { type: 'SUBMIT', data: {} });
+
+ const requestId = extractRequestId(iframe.contentWindow.postMessage);
+
+ messageHandler?.(
+ createMessageEvent({
+ source: iframe.contentWindow,
+ data: JSON.stringify({
+ type: 'REQUEST_RESULT',
+ data: { request_id: requestId, result: { success: true } },
+ }),
+ }),
+ );
+
+ const result = await resultPromise;
+ expect(result).toEqual({ success: true });
+ });
+
+ it('ignores messages from different source', async () => {
+ const { iframe } = createMockIframe();
+
+ const resultPromise = sendEvent(iframe as unknown as HTMLIFrameElement, { type: 'SUBMIT', data: {} });
+
+ const requestId = extractRequestId(iframe.contentWindow.postMessage);
+
+ messageHandler?.(
+ createMessageEvent({
+ source: { postMessage: vi.fn() },
+ data: JSON.stringify({
+ type: 'REQUEST_RESULT',
+ data: { request_id: requestId, result: { success: true } },
+ }),
+ }),
+ );
+
+ vi.advanceTimersByTime(30000);
+ const result = await resultPromise;
+ expect(result).toEqual({
+ success: false,
+ error: { code: 'unexpected:request_timed_out', message: 'The request timed out: try again' },
+ });
+ });
+
+ it('ignores messages with different request_id', async () => {
+ const { iframe } = createMockIframe();
+
+ const resultPromise = sendEvent(iframe as unknown as HTMLIFrameElement, { type: 'SUBMIT', data: {} });
+
+ messageHandler?.(
+ createMessageEvent({
+ source: iframe.contentWindow,
+ data: JSON.stringify({
+ type: 'REQUEST_RESULT',
+ data: { request_id: 'wrong_id', result: { success: true } },
+ }),
+ }),
+ );
+
+ vi.advanceTimersByTime(30000);
+ const result = await resultPromise;
+ expect(result).toEqual({
+ success: false,
+ error: { code: 'unexpected:request_timed_out', message: 'The request timed out: try again' },
+ });
+ });
+
+ it('ignores non-REQUEST_RESULT messages', async () => {
+ const { iframe } = createMockIframe();
+
+ const resultPromise = sendEvent(iframe as unknown as HTMLIFrameElement, { type: 'SUBMIT', data: {} });
+
+ messageHandler?.(
+ createMessageEvent({
+ source: iframe.contentWindow,
+ data: JSON.stringify({ type: 'EDITOR_READY', data: {} }),
+ }),
+ );
+
+ vi.advanceTimersByTime(30000);
+ const result = await resultPromise;
+ expect(result).toEqual({
+ success: false,
+ error: { code: 'unexpected:request_timed_out', message: 'The request timed out: try again' },
+ });
+ });
+
+ it('times out after 30 seconds with error result', async () => {
+ const { iframe } = createMockIframe();
+
+ const resultPromise = sendEvent(iframe as unknown as HTMLIFrameElement, { type: 'SUBMIT', data: {} });
+
+ vi.advanceTimersByTime(30000);
+
+ const result = await resultPromise;
+ expect(result).toEqual({
+ success: false,
+ error: { code: 'unexpected:request_timed_out', message: 'The request timed out: try again' },
+ });
+ });
+
+ it('removes event listener after successful response', async () => {
+ const { iframe } = createMockIframe();
+
+ const resultPromise = sendEvent(iframe as unknown as HTMLIFrameElement, { type: 'SUBMIT', data: {} });
+
+ const requestId = extractRequestId(iframe.contentWindow.postMessage);
+
+ messageHandler?.(
+ createMessageEvent({
+ source: iframe.contentWindow,
+ data: JSON.stringify({
+ type: 'REQUEST_RESULT',
+ data: { request_id: requestId, result: { success: true } },
+ }),
+ }),
+ );
+
+ await resultPromise;
+ expect(removeEventListenerSpy).toHaveBeenCalledWith('message', expect.any(Function));
+ });
+
+ it('removes event listener after timeout', async () => {
+ const { iframe } = createMockIframe();
+
+ const resultPromise = sendEvent(iframe as unknown as HTMLIFrameElement, { type: 'SUBMIT', data: {} });
+
+ vi.advanceTimersByTime(30000);
+
+ await resultPromise;
+ expect(removeEventListenerSpy).toHaveBeenCalledWith('message', expect.any(Function));
+ });
+
+ it('handles invalid JSON in message gracefully', async () => {
+ const { iframe } = createMockIframe();
+
+ const resultPromise = sendEvent(iframe as unknown as HTMLIFrameElement, { type: 'SUBMIT', data: {} });
+
+ messageHandler?.(
+ createMessageEvent({
+ source: iframe.contentWindow,
+ data: 'not valid json',
+ }),
+ );
+
+ vi.advanceTimersByTime(30000);
+ const result = await resultPromise;
+ expect(result).toEqual({
+ success: false,
+ error: { code: 'unexpected:request_timed_out', message: 'The request timed out: try again' },
+ });
+ });
+});
+
+describe('useEmbed', () => {
+ const expectedError = {
+ success: false,
+ error: {
+ code: 'bad_request:embed_ref_not_available',
+ message: 'embedRef is not available: make sure to pass embedRef to the component',
+ },
+ };
+
+ describe('initial state', () => {
+ it('returns embedRef and actions object', () => {
+ const { result } = renderHook(() => useEmbed());
+
+ expect(result.current.embedRef).toBeDefined();
+ expect(result.current.embedRef.current).toBeNull();
+ expect(result.current.actions).toBeDefined();
+ });
+ });
+
+ describe('actions without ref attached', () => {
+ it('goTo returns error when embedRef not attached', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const actionResult = await result.current.actions.goTo({ page: 1 });
+ expect(actionResult).toEqual(expectedError);
+ });
+
+ it('selectTool returns error when embedRef not attached', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const actionResult = await result.current.actions.selectTool('TEXT');
+ expect(actionResult).toEqual(expectedError);
+ });
+
+ it('createField returns error when embedRef not attached', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const actionResult = await result.current.actions.createField({
+ type: 'TEXT',
+ page: 1,
+ x: 0,
+ y: 0,
+ width: 100,
+ height: 20,
+ });
+ expect(actionResult).toEqual(expectedError);
+ });
+
+ it('clearFields returns error when embedRef not attached', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const actionResult = await result.current.actions.clearFields({});
+ expect(actionResult).toEqual(expectedError);
+ });
+
+ it('getDocumentContent returns error when embedRef not attached', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const actionResult = await result.current.actions.getDocumentContent({ extractionMode: 'auto' });
+ expect(actionResult).toEqual(expectedError);
+ });
+
+ it('submit returns error when embedRef not attached', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const actionResult = await result.current.actions.submit({ downloadCopyOnDevice: false });
+ expect(actionResult).toEqual(expectedError);
+ });
+ });
+
+ describe('actions with ref attached', () => {
+ const createMockEmbedRef = (): {
+ ref: EmbedActions;
+ spies: Record>;
+ } => {
+ const spies = {
+ goTo: vi.fn().mockResolvedValue({ success: true }),
+ selectTool: vi.fn().mockResolvedValue({ success: true }),
+ createField: vi.fn().mockResolvedValue({ success: true }),
+ clearFields: vi.fn().mockResolvedValue({ success: true }),
+ getDocumentContent: vi.fn().mockResolvedValue({ success: true }),
+ submit: vi.fn().mockResolvedValue({ success: true }),
+ };
+
+ return {
+ ref: spies,
+ spies,
+ };
+ };
+
+ it('goTo delegates to ref.goTo', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const { ref, spies } = createMockEmbedRef();
+ (result.current.embedRef as React.MutableRefObject).current = ref;
+
+ const actionResult = await result.current.actions.goTo({ page: 1 });
+
+ expect(spies.goTo).toHaveBeenCalledWith({ page: 1 });
+ expect(actionResult).toEqual({ success: true });
+ });
+
+ it('selectTool delegates to ref.selectTool', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const { ref, spies } = createMockEmbedRef();
+ (result.current.embedRef as React.MutableRefObject).current = ref;
+
+ const actionResult = await result.current.actions.selectTool('TEXT');
+
+ expect(spies.selectTool).toHaveBeenCalledWith('TEXT');
+ expect(actionResult).toEqual({ success: true });
+ });
+
+ it('createField delegates to ref.createField', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const { ref, spies } = createMockEmbedRef();
+ (result.current.embedRef as React.MutableRefObject).current = ref;
+
+ const fieldOptions = { type: 'TEXT' as const, page: 1, x: 0, y: 0, width: 100, height: 20 };
+ const actionResult = await result.current.actions.createField(fieldOptions);
+
+ expect(spies.createField).toHaveBeenCalledWith(fieldOptions);
+ expect(actionResult).toEqual({ success: true });
+ });
+
+ it('clearFields delegates to ref.clearFields', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const { ref, spies } = createMockEmbedRef();
+ (result.current.embedRef as React.MutableRefObject).current = ref;
+
+ const actionResult = await result.current.actions.clearFields({});
+
+ expect(spies.clearFields).toHaveBeenCalledWith({});
+ expect(actionResult).toEqual({ success: true });
+ });
+
+ it('getDocumentContent delegates to ref.getDocumentContent', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const { ref, spies } = createMockEmbedRef();
+ (result.current.embedRef as React.MutableRefObject).current = ref;
+
+ const actionResult = await result.current.actions.getDocumentContent({ extractionMode: 'auto' });
+
+ expect(spies.getDocumentContent).toHaveBeenCalledWith({ extractionMode: 'auto' });
+ expect(actionResult).toEqual({ success: true });
+ });
+
+ it('submit delegates to ref.submit', async () => {
+ const { result } = renderHook(() => useEmbed());
+ const { ref, spies } = createMockEmbedRef();
+ (result.current.embedRef as React.MutableRefObject).current = ref;
+
+ const actionResult = await result.current.actions.submit({ downloadCopyOnDevice: false });
+
+ expect(spies.submit).toHaveBeenCalledWith({ downloadCopyOnDevice: false });
+ expect(actionResult).toEqual({ success: true });
+ });
+ });
+
+ it('maintains stable action references across renders', () => {
+ const { result, rerender } = renderHook(() => useEmbed());
+
+ const initialActions = result.current.actions;
+ rerender();
+
+ expect(result.current.actions.goTo).toBe(initialActions.goTo);
+ expect(result.current.actions.submit).toBe(initialActions.submit);
+ });
+});
+
+describe('Type assertions', () => {
+ // These types are intentionally inlined to act as a "frozen" contract.
+ // If the actual types change, these tests will fail at compile time.
+
+ type ExpectedToolType = 'TEXT' | 'BOXED_TEXT' | 'CHECKBOX' | 'PICTURE' | 'SIGNATURE';
+
+ type ExpectedBaseFieldOptions = {
+ page: number;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ };
+
+ type ExpectedTextFieldOptions = ExpectedBaseFieldOptions & {
+ type: 'TEXT' | 'BOXED_TEXT';
+ value?: string;
+ };
+
+ type ExpectedCheckboxFieldOptions = ExpectedBaseFieldOptions & {
+ type: 'CHECKBOX';
+ value?: 'checked' | 'unchecked';
+ };
+
+ type ExpectedPictureFieldOptions = ExpectedBaseFieldOptions & {
+ type: 'PICTURE';
+ value?: string;
+ };
+
+ type ExpectedSignatureFieldOptions = ExpectedBaseFieldOptions & {
+ type: 'SIGNATURE';
+ value?: string;
+ };
+
+ type ExpectedCreateFieldOptions =
+ | ExpectedTextFieldOptions
+ | ExpectedCheckboxFieldOptions
+ | ExpectedPictureFieldOptions
+ | ExpectedSignatureFieldOptions;
+
+ type ExpectedErrorResult = {
+ success: false;
+ error: { code: string; message: string };
+ };
+
+ type ExpectedSuccessResult = TData extends undefined
+ ? { success: true }
+ : { success: true; data: TData };
+
+ type ExpectedActionResult = ExpectedSuccessResult | ExpectedErrorResult;
+
+ describe('EmbedActions', () => {
+ it('goTo accepts { page: number } and returns ActionResult', () => {
+ expectTypeOf().parameter(0).toEqualTypeOf<{ page: number }>();
+ expectTypeOf().returns.resolves.toExtend();
+ });
+
+ it('selectTool accepts ToolType | null and returns ActionResult', () => {
+ expectTypeOf().parameter(0).toEqualTypeOf();
+ expectTypeOf().returns.resolves.toExtend();
+ });
+
+ it('createField accepts CreateFieldOptions and returns ActionResult with field_id', () => {
+ expectTypeOf().parameter(0).toEqualTypeOf();
+ expectTypeOf().returns.resolves.toExtend<
+ ExpectedActionResult<{ field_id: string }>
+ >();
+ });
+
+ it('clearFields accepts optional { fieldIds?, page? } and returns ActionResult with cleared_count', () => {
+ expectTypeOf()
+ .parameter(0)
+ .toEqualTypeOf<{ fieldIds?: string[]; page?: number } | undefined>();
+ expectTypeOf().returns.resolves.toExtend<
+ ExpectedActionResult<{ cleared_count: number }>
+ >();
+ });
+
+ it('getDocumentContent requires { extractionMode } and returns ActionResult with document content', () => {
+ expectTypeOf().parameter(0).toEqualTypeOf<{
+ extractionMode: 'auto' | 'ocr';
+ }>();
+ expectTypeOf().returns.resolves.toExtend<
+ ExpectedActionResult<{ name: string; pages: { page: number; content: string }[] }>
+ >();
+ });
+
+ it('submit requires { downloadCopyOnDevice } and returns ActionResult', () => {
+ expectTypeOf().parameter(0).toEqualTypeOf<{ downloadCopyOnDevice: boolean }>();
+ expectTypeOf().returns.resolves.toExtend();
+ });
+ });
+
+ describe('createField discriminated union', () => {
+ it('TEXT field options are accepted', () => {
+ const textField = {
+ type: 'TEXT' as const,
+ page: 1,
+ x: 0,
+ y: 0,
+ width: 100,
+ height: 20,
+ value: 'hello',
+ };
+ expectTypeOf(textField).toExtend();
+ });
+
+ it('BOXED_TEXT field options are accepted', () => {
+ const boxedTextField = {
+ type: 'BOXED_TEXT' as const,
+ page: 1,
+ x: 0,
+ y: 0,
+ width: 100,
+ height: 20,
+ value: 'hello',
+ };
+ expectTypeOf(boxedTextField).toExtend();
+ });
+
+ it('CHECKBOX field accepts only checked/unchecked values', () => {
+ const checkedField = {
+ type: 'CHECKBOX' as const,
+ page: 1,
+ x: 0,
+ y: 0,
+ width: 20,
+ height: 20,
+ value: 'checked' as const,
+ };
+ expectTypeOf(checkedField).toExtend();
+
+ const uncheckedField = {
+ type: 'CHECKBOX' as const,
+ page: 1,
+ x: 0,
+ y: 0,
+ width: 20,
+ height: 20,
+ value: 'unchecked' as const,
+ };
+ expectTypeOf(uncheckedField).toExtend();
+ });
+
+ it('PICTURE field options are accepted', () => {
+ const pictureField = {
+ type: 'PICTURE' as const,
+ page: 1,
+ x: 0,
+ y: 0,
+ width: 100,
+ height: 100,
+ value: 'data:image/png;base64,...',
+ };
+ expectTypeOf(pictureField).toExtend();
+ });
+
+ it('SIGNATURE field options are accepted', () => {
+ const signatureField = {
+ type: 'SIGNATURE' as const,
+ page: 1,
+ x: 0,
+ y: 0,
+ width: 150,
+ height: 50,
+ value: 'John Doe',
+ };
+ expectTypeOf(signatureField).toExtend();
+ });
+ });
+});
diff --git a/react/src/hook.tsx b/react/src/hook.tsx
index 00cf7c8..2a70b0d 100644
--- a/react/src/hook.tsx
+++ b/react/src/hook.tsx
@@ -1,16 +1,83 @@
import * as React from 'react';
+import { generateRandomID } from './utils';
-const DEFAULT_REQUEST_TIMEOUT_IN_MS = 5000;
+const DEFAULT_REQUEST_TIMEOUT_IN_MS = 30000;
-const generateRandomID = () => {
- return Math.random().toString(36).substring(2, 15);
+type ExtractionMode = 'auto' | 'ocr';
+
+type ToolType = 'TEXT' | 'BOXED_TEXT' | 'CHECKBOX' | 'PICTURE' | 'SIGNATURE';
+
+type BaseFieldOptions = {
+ page: number;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+};
+
+type TextFieldOptions = BaseFieldOptions & {
+ type: 'TEXT' | 'BOXED_TEXT';
+ value?: string;
+};
+
+type CheckboxFieldOptions = BaseFieldOptions & {
+ type: 'CHECKBOX';
+ value?: 'checked' | 'unchecked';
+};
+
+type PictureFieldOptions = BaseFieldOptions & {
+ type: 'PICTURE';
+ value?: string; // Data URL (base64)
+};
+
+type SignatureFieldOptions = BaseFieldOptions & {
+ type: 'SIGNATURE';
+ value?: string; // Data URL (base64) or plain text (generates typed signature)
+};
+
+export type CreateFieldOptions = TextFieldOptions | CheckboxFieldOptions | PictureFieldOptions | SignatureFieldOptions;
+
+type ErrorCodePrefix = 'bad_request' | 'unexpected' | 'forbidden';
+
+type ErrorResult = {
+ success: false;
+ error: { code: `${ErrorCodePrefix}:${string}`; message: string };
+};
+
+type SuccessResult = TData extends undefined ? { success: true } : { success: true; data: TData };
+
+type ActionResult = SuccessResult | ErrorResult;
+
+type DocumentContentPage = {
+ page: number;
+ content: string;
+};
+
+type DocumentContentResult = {
+ name: string;
+ pages: DocumentContentPage[];
+};
+
+type ClearFieldsResult = {
+ cleared_count: number;
+};
+
+type CreateFieldResult = {
+ field_id: string;
};
export type EmbedActions = {
- submit: (options: { downloadCopyOnDevice: boolean }) => Promise;
- selectTool: (
- toolType: 'TEXT' | 'BOXED_TEXT' | 'CHECKBOX' | 'PICTURE' | 'SIGNATURE' | null,
- ) => Promise;
+ goTo: (options: { page: number }) => Promise;
+
+ selectTool: (toolType: ToolType | null) => Promise;
+
+ createField: (options: CreateFieldOptions) => Promise>;
+
+ clearFields: (options?: { fieldIds?: string[]; page?: number }) => Promise>;
+
+ getDocumentContent: (options: { extractionMode: ExtractionMode }) => Promise>;
+
+ submit: (options: { downloadCopyOnDevice: boolean }) => Promise;
};
export type EventPayload = {
@@ -18,130 +85,135 @@ export type EventPayload = {
data: unknown;
};
-export function sendEvent(iframe: HTMLIFrameElement, payload: EventPayload) {
+type RequestResultEvent = {
+ type: 'REQUEST_RESULT';
+ data: {
+ request_id: string;
+ result: ActionResult;
+ };
+};
+
+export const sendEvent = (
+ iframe: HTMLIFrameElement,
+ payload: EventPayload,
+): Promise> => {
const requestId = generateRandomID();
- return new Promise((resolve) => {
- try {
- const handleMessage = (event: MessageEvent) => {
- const parsedEvent: Result = (() => {
- try {
- const parsedEvent = JSON.parse(event.data);
-
- if (parsedEvent.type !== 'REQUEST_RESULT') {
- return {
- data: {
- request_id: null,
- },
- };
- }
-
- return parsedEvent;
- } catch (e) {
+ return new Promise>((resolve) => {
+ const handleMessage = (event: MessageEvent) => {
+ const parsedEvent: RequestResultEvent | null = (() => {
+ try {
+ const parsed = JSON.parse(event.data);
+ if (parsed.type !== 'REQUEST_RESULT') {
return null;
}
- })();
- const isTargetIframe = event.source === iframe.contentWindow;
- const isMatchingResponse = parsedEvent.data.request_id === requestId;
-
- if (isTargetIframe && isMatchingResponse) {
- resolve(parsedEvent.data.result);
- window.removeEventListener('message', handleMessage);
+ return parsed;
+ } catch {
+ return null;
}
- };
+ })();
- window.addEventListener('message', handleMessage);
+ if (parsedEvent === null) {
+ return;
+ }
- iframe.contentWindow?.postMessage(JSON.stringify({ ...payload, request_id: requestId }), '*');
+ const isTargetIframe = event.source === iframe.contentWindow;
+ const isMatchingResponse = parsedEvent.data.request_id === requestId;
- const timeoutId = setTimeout(() => {
- resolve({
- success: false,
- error: {
- code: 'unexpected:request_timed_out',
- message: 'The request timed out: try again',
- },
- } satisfies Result['data']['result']);
+ if (isTargetIframe && isMatchingResponse) {
+ resolve(parsedEvent.data.result);
window.removeEventListener('message', handleMessage);
- }, DEFAULT_REQUEST_TIMEOUT_IN_MS);
+ clearTimeout(timeoutId);
+ }
+ };
- const cleanup = () => clearTimeout(timeoutId);
- window.addEventListener('message', cleanup);
- } catch (e) {
- const error = e as Error;
+ window.addEventListener('message', handleMessage);
+
+ iframe.contentWindow?.postMessage(JSON.stringify({ ...payload, request_id: requestId }), '*');
+
+ const timeoutId = setTimeout(() => {
resolve({
success: false,
error: {
- code: 'unexpected:failed_processing_request',
- message: `The following error happened: ${error.name}:${error.message}`,
+ code: 'unexpected:request_timed_out',
+ message: 'The request timed out: try again',
},
});
- }
+ window.removeEventListener('message', handleMessage);
+ }, DEFAULT_REQUEST_TIMEOUT_IN_MS);
});
-}
-
-type ErrorCodePrefix = 'bad_request' | 'unexpected';
-
-type Result = {
- type: 'REQUEST_RESULT';
- data: {
- request_id: string;
- result:
- | { success: true }
- | {
- success: false;
- error: { code: `${ErrorCodePrefix}:${string}`; message: string };
- };
- };
};
-export const useEmbed = (): { embedRef: React.RefObject; actions: EmbedActions } => {
- const embedRef = React.useRef(null);
+export const useEmbed = (): { embedRef: React.RefObject; actions: EmbedActions } => {
+ const embedRef = React.useRef(null);
- const handleSubmit: EmbedRefHandlers['submit'] = React.useCallback(
- async ({ downloadCopyOnDevice }): Promise => {
+ const createAction = (
+ actionFn: (ref: EmbedActions, ...args: TArgs) => Promise>,
+ ): ((...args: TArgs) => Promise>) => {
+ return async (...args: TArgs): Promise> => {
if (embedRef.current === null) {
- return Promise.resolve({
- success: false as const,
+ return {
+ success: false,
error: {
- code: 'bad_request:embed_ref_not_available' as const,
+ code: 'bad_request:embed_ref_not_available',
message: 'embedRef is not available: make sure to pass embedRef to the component',
},
- });
+ };
}
+ return actionFn(embedRef.current, ...args);
+ };
+ };
+
+ const handleGoTo = React.useCallback(
+ createAction<[{ page: number }]>(async (ref, options) => {
+ return ref.goTo(options);
+ }),
+ [],
+ );
- const result = await embedRef.current.submit({ downloadCopyOnDevice });
+ const handleSelectTool = React.useCallback(
+ createAction<[ToolType | null]>(async (ref, toolType) => {
+ return ref.selectTool(toolType);
+ }),
+ [],
+ );
- return result;
- },
+ const handleCreateField = React.useCallback(
+ createAction<[CreateFieldOptions], CreateFieldResult>(async (ref, options) => {
+ return ref.createField(options);
+ }),
[],
);
- const handleSelectTool: EmbedRefHandlers['selectTool'] = React.useCallback(
- async (toolType): Promise => {
- if (embedRef.current === null) {
- return Promise.resolve({
- success: false as const,
- error: {
- code: 'bad_request:embed_ref_not_available' as const,
- message: 'embedRef is not available: make sure to pass embedRef to the component',
- },
- });
- }
+ const handleClearFields = React.useCallback(
+ createAction<[{ fieldIds?: string[]; page?: number }?], ClearFieldsResult>(async (ref, options) => {
+ return ref.clearFields(options);
+ }),
+ [],
+ );
- const result = await embedRef.current.selectTool(toolType);
+ const handleGetDocumentContent = React.useCallback(
+ createAction<[{ extractionMode: ExtractionMode }], DocumentContentResult>(async (ref, options) => {
+ return ref.getDocumentContent(options);
+ }),
+ [],
+ );
- return result;
- },
+ const handleSubmit = React.useCallback(
+ createAction<[{ downloadCopyOnDevice: boolean }]>(async (ref, options) => {
+ return ref.submit(options);
+ }),
[],
);
return {
embedRef,
actions: {
- submit: handleSubmit,
+ goTo: handleGoTo,
selectTool: handleSelectTool,
+ createField: handleCreateField,
+ clearFields: handleClearFields,
+ getDocumentContent: handleGetDocumentContent,
+ submit: handleSubmit,
},
};
};
-
-export type EmbedRefHandlers = EmbedActions;
diff --git a/react/src/index.test.tsx b/react/src/index.test.tsx
new file mode 100644
index 0000000..5732a40
--- /dev/null
+++ b/react/src/index.test.tsx
@@ -0,0 +1,829 @@
+///
+
+import * as React from 'react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, waitFor, act } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { EmbedPDF } from './index';
+import type { EmbedActions } from './hook';
+
+vi.mock('./styles.scss', () => ({}));
+
+/**
+ * These tests focus on user-facing behavior:
+ * - What users see (iframe, modal, styling)
+ * - How users interact (clicking triggers, calling ref methods)
+ * - What users receive (events via callbacks)
+ *
+ * Tests intentionally avoid implementation details like:
+ * - Internal postMessage protocol format
+ * - Internal state machine transitions
+ * - Internal timing workarounds
+ */
+
+type MessageEventHandler = (event: MessageEvent) => void;
+
+const createMessageEvent = ({
+ origin,
+ source,
+ data,
+}: {
+ origin: string;
+ source: Window | null;
+ data: string;
+}): MessageEvent => ({ origin, source, data }) as MessageEvent;
+
+const getIframe = (): HTMLIFrameElement => {
+ const iframe = screen.getByTitle('SimplePDF');
+ return iframe as HTMLIFrameElement;
+};
+
+const getIframeSrcUrl = (): URL => {
+ const iframe = getIframe();
+ const src = iframe.getAttribute('src');
+ if (src === null) {
+ throw new Error('Expected iframe to have src attribute');
+ }
+ return new URL(src);
+};
+
+class MockFileReader {
+ result: string | null = 'data:application/pdf;base64,dGVzdA==';
+ onload: ((e: ProgressEvent) => void) | null = null;
+ onerror: ((e: ProgressEvent) => void) | null = null;
+
+ readAsDataURL(): void {
+ queueMicrotask(() => {
+ this.onload?.({} as ProgressEvent);
+ });
+ }
+}
+
+class MockFileReaderWithError {
+ result: string | null = null;
+ onload: ((e: ProgressEvent) => void) | null = null;
+ onerror: ((e: ProgressEvent) => void) | null = null;
+
+ readAsDataURL(): void {
+ queueMicrotask(() => {
+ this.onerror?.({} as ProgressEvent);
+ });
+ }
+}
+
+describe('EmbedPDF', () => {
+ let messageHandler: MessageEventHandler | null = null;
+
+ beforeEach(() => {
+ vi.spyOn(window, 'addEventListener').mockImplementation((type, handler) => {
+ if (type === 'message') {
+ messageHandler = handler as MessageEventHandler;
+ }
+ });
+ vi.spyOn(window, 'removeEventListener').mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ messageHandler = null;
+ });
+
+ describe('inline mode', () => {
+ it('renders an iframe with title', () => {
+ render();
+
+ expect(screen.getByTitle('SimplePDF')).toBeInTheDocument();
+ });
+
+ it('applies className prop to iframe', () => {
+ render();
+
+ expect(screen.getByTitle('SimplePDF')).toHaveClass('custom-class');
+ });
+
+ it('applies style prop to iframe with border: 0', () => {
+ render();
+
+ const iframe = screen.getByTitle('SimplePDF');
+ expect(iframe).toHaveStyle({ width: '100%', height: '500px', border: '0px' });
+ });
+
+ it.each([
+ { baseDomain: undefined, companyIdentifier: undefined, expectedOrigin: 'https://react-editor.simplepdf.com' },
+ { baseDomain: 'custom.com', companyIdentifier: 'myco', expectedOrigin: 'https://myco.custom.com' },
+ { baseDomain: 'simplepdf.nil:3000', companyIdentifier: 'e2e', expectedOrigin: 'http://e2e.simplepdf.nil:3000' },
+ ])(
+ 'sets iframe src with correct domain ($expectedOrigin)',
+ async ({ baseDomain, companyIdentifier, expectedOrigin }) => {
+ render();
+
+ await waitFor(() => {
+ const url = getIframeSrcUrl();
+ expect(url.origin).toBe(expectedOrigin);
+ expect(url.pathname).toBe('/en/editor');
+ });
+ },
+ );
+
+ it.each([
+ { locale: undefined, expectedPath: '/en/editor' },
+ { locale: 'fr' as const, expectedPath: '/fr/editor' },
+ { locale: 'de' as const, expectedPath: '/de/editor' },
+ ])('sets correct locale in URL path ($expectedPath)', async ({ locale, expectedPath }) => {
+ render();
+
+ await waitFor(() => {
+ const url = getIframeSrcUrl();
+ expect(url.pathname).toBe(expectedPath);
+ });
+ });
+
+ it('adds loadingPlaceholder param when documentURL provided', async () => {
+ render();
+
+ await waitFor(() => {
+ const url = getIframeSrcUrl();
+ expect(url.searchParams.get('loadingPlaceholder')).toBe('true');
+ });
+ });
+
+ it('adds context param when context provided', async () => {
+ render();
+
+ await waitFor(() => {
+ const url = getIframeSrcUrl();
+ const encodedContext = url.searchParams.get('context');
+ if (encodedContext === null) {
+ throw new Error('Expected context param to be present');
+ }
+ const decodedContext = JSON.parse(atob(decodeURIComponent(encodedContext)));
+ expect(decodedContext).toEqual({ key: 'value' });
+ });
+ });
+
+ it('sets up message event listener on mount', () => {
+ render();
+
+ expect(window.addEventListener).toHaveBeenCalledWith('message', expect.any(Function), false);
+ });
+
+ it('removes message event listener on unmount', () => {
+ const { unmount } = render();
+
+ unmount();
+
+ expect(window.removeEventListener).toHaveBeenCalledWith('message', expect.any(Function));
+ });
+ });
+
+ describe('modal mode', () => {
+ it('renders children trigger element', () => {
+ render(
+
+
+ ,
+ );
+
+ expect(screen.getByRole('button', { name: 'Open PDF Editor' })).toBeInTheDocument();
+ });
+
+ it('does not render modal initially', () => {
+ render(
+
+
+ ,
+ );
+
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ });
+
+ it('opens modal when trigger clicked', async () => {
+ const user = userEvent.setup();
+ render(
+
+
+ ,
+ );
+
+ await user.click(screen.getByRole('button', { name: 'Open PDF Editor' }));
+
+ expect(screen.getByRole('dialog')).toBeInTheDocument();
+ });
+
+ it('renders modal with aria-modal attribute', async () => {
+ const user = userEvent.setup();
+ render(
+
+
+ ,
+ );
+
+ await user.click(screen.getByRole('button', { name: 'Open PDF Editor' }));
+
+ expect(screen.getByRole('dialog')).toHaveAttribute('aria-modal', 'true');
+ });
+
+ it('renders close button with aria-label', async () => {
+ const user = userEvent.setup();
+ render(
+
+
+ ,
+ );
+
+ await user.click(screen.getByRole('button', { name: 'Open PDF Editor' }));
+
+ expect(screen.getByRole('button', { name: 'Close PDF editor modal' })).toBeInTheDocument();
+ });
+
+ it('closes modal when close button clicked', async () => {
+ const user = userEvent.setup();
+ render(
+
+
+ ,
+ );
+
+ await user.click(screen.getByRole('button', { name: 'Open PDF Editor' }));
+ expect(screen.getByRole('dialog')).toBeInTheDocument();
+
+ await user.click(screen.getByRole('button', { name: 'Close PDF editor modal' }));
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ });
+
+ it('renders iframe inside modal', async () => {
+ const user = userEvent.setup();
+ render(
+
+
+ ,
+ );
+
+ await user.click(screen.getByRole('button', { name: 'Open PDF Editor' }));
+
+ expect(screen.getByTitle('SimplePDF')).toBeInTheDocument();
+ });
+
+ it('sets iframe src with editor URL when modal opens', async () => {
+ const user = userEvent.setup();
+ render(
+
+
+ ,
+ );
+
+ await user.click(screen.getByRole('button', { name: 'Open PDF Editor' }));
+
+ const url = getIframeSrcUrl();
+ expect(url.origin).toBe('https://testco.simplepdf.com');
+ expect(url.pathname).toBe('/en/editor');
+ });
+
+ it('extracts href from anchor child for document loading', async () => {
+ const user = userEvent.setup();
+ render(
+
+ Edit PDF
+ ,
+ );
+
+ await user.click(screen.getByRole('link', { name: 'Edit PDF' }));
+
+ const url = getIframeSrcUrl();
+ expect(url.searchParams.get('loadingPlaceholder')).toBe('true');
+ });
+
+ it('renders null for non-element children', () => {
+ render({'plain text'});
+
+ expect(screen.queryByText('plain text')).not.toBeInTheDocument();
+ });
+ });
+
+ describe('ref handlers', () => {
+ it('exposes action methods via ref', async () => {
+ const ref = React.createRef();
+
+ render();
+
+ await waitFor(() => {
+ expect(ref.current).not.toBeNull();
+ });
+
+ 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?.getDocumentContent).toBe('function');
+ expect(typeof ref.current?.submit).toBe('function');
+ });
+
+ describe('action methods before modal opens (iframe not available)', () => {
+ it.each([
+ { action: 'goTo' as const, args: { page: 1 } },
+ { action: 'selectTool' as const, args: 'TEXT' as const },
+ {
+ 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: 'getDocumentContent' as const, args: {} },
+ { action: 'submit' as const, args: { downloadCopyOnDevice: false } },
+ ])('$action returns error when iframe not available (modal not opened)', async ({ action, args }) => {
+ const ref = React.createRef();
+
+ render(
+
+
+ ,
+ );
+
+ await waitFor(() => {
+ expect(ref.current).not.toBeNull();
+ });
+
+ if (ref.current === null) {
+ throw new Error('Expected ref to be available');
+ }
+
+ const result = await (ref.current[action] as (arg: never) => Promise)(args as never);
+
+ expect(result).toEqual({
+ success: false,
+ error: {
+ code: 'unexpected:iframe_not_available',
+ message: 'Iframe not available',
+ },
+ });
+ });
+ });
+
+ describe('action methods when editor is ready (inline mode)', () => {
+ interface MockContentWindow {
+ postMessage: ReturnType;
+ }
+
+ const setupMockContentWindow = (iframe: HTMLIFrameElement): MockContentWindow => {
+ const mockContentWindow: MockContentWindow = {
+ postMessage: vi.fn(),
+ };
+ Object.defineProperty(iframe, 'contentWindow', {
+ value: mockContentWindow,
+ writable: true,
+ });
+ return mockContentWindow;
+ };
+
+ const simulateEditorReady = async (
+ iframe: HTMLIFrameElement,
+ mockContentWindow: MockContentWindow,
+ ): Promise => {
+ await act(async () => {
+ messageHandler?.(
+ createMessageEvent({
+ origin: 'https://react-editor.simplepdf.com',
+ source: mockContentWindow as unknown as Window,
+ data: JSON.stringify({ type: 'EDITOR_READY', data: {} }),
+ }),
+ );
+ });
+
+ await act(async () => {
+ messageHandler?.(
+ createMessageEvent({
+ origin: 'https://react-editor.simplepdf.com',
+ source: mockContentWindow as unknown as Window,
+ data: JSON.stringify({ type: 'DOCUMENT_LOADED', data: { document_id: 'doc123' } }),
+ }),
+ );
+ });
+
+ // Allow editor ready promise to resolve
+ await act(async () => {
+ await new Promise((resolve) => setTimeout(resolve, 250));
+ });
+ };
+
+ const extractRequestId = (mockContentWindow: MockContentWindow): string => {
+ const calls = mockContentWindow.postMessage.mock.calls;
+ const lastCall = calls[calls.length - 1];
+ if (!lastCall || typeof lastCall[0] !== 'string') {
+ throw new Error('Expected postMessage to be called with a string');
+ }
+ const parsed = JSON.parse(lastCall[0]);
+ return parsed.request_id;
+ };
+
+ const simulateActionResponse = async ({
+ mockContentWindow,
+ result,
+ }: {
+ mockContentWindow: MockContentWindow;
+ result: { success: true } | { success: true; data: unknown };
+ }): Promise => {
+ const requestId = extractRequestId(mockContentWindow);
+
+ await act(async () => {
+ messageHandler?.(
+ createMessageEvent({
+ origin: 'https://react-editor.simplepdf.com',
+ source: mockContentWindow as unknown as Window,
+ data: JSON.stringify({
+ type: 'REQUEST_RESULT',
+ data: { request_id: requestId, result },
+ }),
+ }),
+ );
+ });
+ };
+
+ it('goTo resolves with success when iframe responds', async () => {
+ const ref = React.createRef();
+
+ render();
+
+ const iframe = getIframe();
+ const mockContentWindow = setupMockContentWindow(iframe);
+
+ await simulateEditorReady(iframe, mockContentWindow);
+
+ if (ref.current === null) {
+ throw new Error('Expected ref to be available');
+ }
+
+ const resultPromise = ref.current.goTo({ page: 2 });
+
+ await waitFor(() => {
+ expect(mockContentWindow.postMessage).toHaveBeenCalled();
+ });
+
+ await simulateActionResponse({
+ mockContentWindow,
+ result: { success: true },
+ });
+
+ const result = await resultPromise;
+ expect(result).toEqual({ success: true });
+ });
+
+ it('submit resolves with success when iframe responds', async () => {
+ const ref = React.createRef();
+
+ render();
+
+ const iframe = getIframe();
+ const mockContentWindow = setupMockContentWindow(iframe);
+
+ await simulateEditorReady(iframe, mockContentWindow);
+
+ if (ref.current === null) {
+ throw new Error('Expected ref to be available');
+ }
+
+ const resultPromise = ref.current.submit({ downloadCopyOnDevice: false });
+
+ await waitFor(() => {
+ expect(mockContentWindow.postMessage).toHaveBeenCalled();
+ });
+
+ await simulateActionResponse({
+ mockContentWindow,
+ result: { success: true },
+ });
+
+ const result = await resultPromise;
+ expect(result).toEqual({ success: true });
+ });
+
+ it('getDocumentContent resolves with data when iframe responds', async () => {
+ const ref = React.createRef();
+
+ render();
+
+ const iframe = getIframe();
+ const mockContentWindow = setupMockContentWindow(iframe);
+
+ await simulateEditorReady(iframe, mockContentWindow);
+
+ if (ref.current === null) {
+ throw new Error('Expected ref to be available');
+ }
+
+ const resultPromise = ref.current.getDocumentContent({ extractionMode: 'auto' });
+
+ await waitFor(() => {
+ expect(mockContentWindow.postMessage).toHaveBeenCalled();
+ });
+
+ await simulateActionResponse({
+ mockContentWindow,
+ result: {
+ success: true,
+ data: {
+ name: 'document.pdf',
+ pages: [{ page: 1, content: 'Hello world' }],
+ },
+ },
+ });
+
+ const result = await resultPromise;
+ expect(result).toEqual({
+ success: true,
+ data: {
+ name: 'document.pdf',
+ pages: [{ page: 1, content: 'Hello world' }],
+ },
+ });
+ });
+ });
+ });
+
+ describe('event handling', () => {
+ it('calls onEmbedEvent when EDITOR_READY received', async () => {
+ const onEmbedEvent = vi.fn();
+
+ render();
+
+ const iframe = getIframe();
+
+ await act(async () => {
+ messageHandler?.(
+ createMessageEvent({
+ origin: 'https://react-editor.simplepdf.com',
+ source: iframe.contentWindow,
+ data: JSON.stringify({ type: 'EDITOR_READY', data: {} }),
+ }),
+ );
+ });
+
+ expect(onEmbedEvent).toHaveBeenCalledWith({ type: 'EDITOR_READY', data: {} });
+ });
+
+ it.each([
+ { type: 'DOCUMENT_LOADED', data: { document_id: 'doc123' } },
+ { type: 'PAGE_FOCUSED', data: { previous_page: 1, current_page: 2, total_pages: 5 } },
+ { type: 'SUBMISSION_SENT', data: { document_id: 'doc123', submission_id: 'sub456' } },
+ ])('calls onEmbedEvent for $type', async ({ type, data }) => {
+ const onEmbedEvent = vi.fn();
+
+ render();
+
+ const iframe = getIframe();
+
+ await act(async () => {
+ messageHandler?.(
+ createMessageEvent({
+ origin: 'https://react-editor.simplepdf.com',
+ source: iframe.contentWindow,
+ data: JSON.stringify({ type, data }),
+ }),
+ );
+ });
+
+ expect(onEmbedEvent).toHaveBeenCalledWith({ type, data });
+ });
+
+ it('ignores events from different origins', async () => {
+ const onEmbedEvent = vi.fn();
+
+ render();
+
+ await act(async () => {
+ messageHandler?.(
+ createMessageEvent({
+ origin: 'https://malicious.com',
+ source: null,
+ data: JSON.stringify({ type: 'EDITOR_READY', data: {} }),
+ }),
+ );
+ });
+
+ expect(onEmbedEvent).not.toHaveBeenCalled();
+ });
+
+ it('ignores events from untrusted iframe source', async () => {
+ const onEmbedEvent = vi.fn();
+
+ render();
+
+ await act(async () => {
+ messageHandler?.(
+ createMessageEvent({
+ origin: 'https://react-editor.simplepdf.com',
+ source: {} as Window,
+ data: JSON.stringify({ type: 'EDITOR_READY', data: {} }),
+ }),
+ );
+ });
+
+ expect(onEmbedEvent).not.toHaveBeenCalled();
+ });
+
+ it('handles invalid JSON in message gracefully', async () => {
+ const onEmbedEvent = vi.fn();
+ const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ render();
+
+ const iframe = getIframe();
+
+ await act(async () => {
+ messageHandler?.(
+ createMessageEvent({
+ origin: 'https://react-editor.simplepdf.com',
+ source: iframe.contentWindow,
+ data: 'not valid json',
+ }),
+ );
+ });
+
+ expect(onEmbedEvent).not.toHaveBeenCalled();
+ expect(consoleErrorSpy).toHaveBeenCalledWith('Failed to parse iFrame event payload');
+ });
+
+ it('handles error when onEmbedEvent throws', async () => {
+ const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+ const onEmbedEvent = vi.fn().mockRejectedValue(new Error('Handler error'));
+
+ render();
+
+ const iframe = getIframe();
+
+ await act(async () => {
+ messageHandler?.(
+ createMessageEvent({
+ origin: 'https://react-editor.simplepdf.com',
+ source: iframe.contentWindow,
+ data: JSON.stringify({ type: 'EDITOR_READY', data: {} }),
+ }),
+ );
+ });
+
+ expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('onEmbedEvent failed to execute'));
+ });
+ });
+
+ describe('document loading', () => {
+ let originalFetch: typeof globalThis.fetch;
+ let originalFileReader: typeof globalThis.FileReader;
+
+ beforeEach(() => {
+ originalFetch = globalThis.fetch;
+ originalFileReader = globalThis.FileReader;
+ });
+
+ afterEach(() => {
+ globalThis.fetch = originalFetch;
+ globalThis.FileReader = originalFileReader;
+ });
+
+ it('calls fetch with documentURL when provided', async () => {
+ const fetchMock = vi.fn().mockImplementation(
+ () =>
+ new Promise(() => {
+ // Never resolve to prevent state updates
+ }),
+ );
+ globalThis.fetch = fetchMock;
+
+ render();
+
+ await waitFor(() => {
+ expect(fetchMock).toHaveBeenCalledWith('https://example.com/document.pdf', {
+ method: 'GET',
+ credentials: 'same-origin',
+ });
+ });
+ });
+
+ it('adds open param to URL when CORS fallback is triggered', async () => {
+ globalThis.fetch = vi.fn().mockRejectedValue(new Error('CORS error'));
+
+ render();
+
+ await waitFor(() => {
+ const url = getIframeSrcUrl();
+ expect(url.searchParams.get('open')).toBe('https://example.com/doc.pdf');
+ });
+ });
+
+ it('falls back to CORS proxy when fetch returns non-ok response', async () => {
+ globalThis.fetch = vi.fn().mockResolvedValue({ ok: false, status: 403 });
+
+ render();
+
+ await waitFor(() => {
+ const url = getIframeSrcUrl();
+ expect(url.searchParams.get('open')).toBe('https://example.com/forbidden.pdf');
+ });
+ });
+
+ it('loads document via fetch and FileReader when CORS allows', async () => {
+ const mockBlob = new Blob(['pdf content'], { type: 'application/pdf' });
+ globalThis.fetch = vi.fn().mockResolvedValue({
+ ok: true,
+ blob: () => Promise.resolve(mockBlob),
+ });
+
+ globalThis.FileReader = MockFileReader as unknown as typeof FileReader;
+
+ render();
+
+ await waitFor(() => {
+ expect(globalThis.fetch).toHaveBeenCalledWith('https://example.com/doc.pdf', {
+ method: 'GET',
+ credentials: 'same-origin',
+ });
+ });
+ });
+
+ it('falls back to CORS proxy when FileReader fails', async () => {
+ const mockBlob = new Blob(['pdf content'], { type: 'application/pdf' });
+ globalThis.fetch = vi.fn().mockResolvedValue({
+ ok: true,
+ blob: () => Promise.resolve(mockBlob),
+ });
+
+ globalThis.FileReader = MockFileReaderWithError as unknown as typeof FileReader;
+
+ render();
+
+ await waitFor(() => {
+ const url = getIframeSrcUrl();
+ expect(url.searchParams.get('open')).toBe('https://example.com/doc.pdf');
+ });
+ });
+
+ it('handles unmount during fetch without errors', async () => {
+ let resolveFetch: (value: Response) => void;
+ globalThis.fetch = vi.fn().mockReturnValue(
+ new Promise((resolve) => {
+ resolveFetch = resolve;
+ }),
+ );
+ const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const { unmount } = render();
+
+ await waitFor(() => {
+ expect(globalThis.fetch).toHaveBeenCalled();
+ });
+
+ unmount();
+
+ await act(async () => {
+ resolveFetch!({
+ ok: true,
+ blob: () => Promise.resolve(new Blob(['pdf'], { type: 'application/pdf' })),
+ } as Response);
+ });
+
+ expect(consoleErrorSpy).not.toHaveBeenCalledWith(
+ expect.stringContaining("Can't perform a React state update on an unmounted component"),
+ );
+ });
+ });
+
+ describe('context changes', () => {
+ it('re-encodes context when it changes', () => {
+ const decodeContext = (url: URL): unknown => {
+ const encoded = url.searchParams.get('context');
+ if (encoded === null) {
+ throw new Error('Expected context param to be present');
+ }
+ return JSON.parse(atob(decodeURIComponent(encoded)));
+ };
+
+ const { rerender } = render();
+
+ const initialUrl = getIframeSrcUrl();
+ expect(decodeContext(initialUrl)).toEqual({ v: 1 });
+
+ rerender();
+
+ const newUrl = getIframeSrcUrl();
+ expect(decodeContext(newUrl)).toEqual({ v: 2 });
+ });
+ });
+
+ describe('unknown event types', () => {
+ it('ignores unknown event types', async () => {
+ const onEmbedEvent = vi.fn();
+
+ render();
+
+ const iframe = getIframe();
+
+ await act(async () => {
+ messageHandler?.(
+ createMessageEvent({
+ origin: 'https://react-editor.simplepdf.com',
+ source: iframe.contentWindow,
+ data: JSON.stringify({ type: 'UNKNOWN_EVENT', data: {} }),
+ }),
+ );
+ });
+
+ expect(onEmbedEvent).not.toHaveBeenCalled();
+ });
+ });
+});
diff --git a/react/src/index.tsx b/react/src/index.tsx
index 21adb5f..e14ddb5 100644
--- a/react/src/index.tsx
+++ b/react/src/index.tsx
@@ -1,14 +1,17 @@
import * as React from 'react';
import { createPortal } from 'react-dom';
-import { sendEvent, EmbedRefHandlers, useEmbed } from './hook';
+import { sendEvent, EmbedActions, useEmbed } from './hook';
+import { buildEditorDomain, encodeContext, buildEditorURL, extractDocumentName, type Locale } from './utils';
import './styles.scss';
export { useEmbed };
export type EmbedEvent =
+ | { type: 'EDITOR_READY'; data: Record }
| { type: 'DOCUMENT_LOADED'; data: { document_id: string } }
- | { type: 'SUBMISSION_SENT'; data: { submission_id: string } };
+ | { type: 'PAGE_FOCUSED'; data: { previous_page: number | null; current_page: number; total_pages: number } }
+ | { type: 'SUBMISSION_SENT'; data: { document_id: string; submission_id: string } };
type Props = InlineProps | ModalProps;
@@ -16,7 +19,12 @@ interface CommonProps {
companyIdentifier?: string;
context?: Record;
onEmbedEvent?: (event: EmbedEvent) => Promise | void;
- locale?: 'en' | 'de' | 'es' | 'fr' | 'it' | 'pt';
+ locale?: Locale;
+ /**
+ * Override the base domain for self-hosted deployments (e.g., "yourdomain.com").
+ * Interested in enterprise self-hosting? Contact sales@simplepdf.com
+ */
+ baseDomain?: string;
}
interface InlineProps extends CommonProps {
@@ -41,34 +49,11 @@ const CloseIcon: React.FC = () => (
);
-const loadDocument = async ({
- iframeRef,
- documentDataURL,
- documentName,
- editorDomain,
-}: {
- iframeRef: React.RefObject;
- documentDataURL: string;
- documentName: string;
- editorDomain: string;
-}) => {
- const editorDomainURL = new URL(editorDomain);
- iframeRef.current?.contentWindow?.postMessage(
- JSON.stringify({
- type: 'LOAD_DOCUMENT',
- data: { data_url: documentDataURL, name: documentName },
- }),
- editorDomainURL.origin,
- );
-};
-
-const DEFAULT_LOCALE = 'en';
-
const isInlineComponent = (props: Props): props is InlineProps => (props as InlineProps).mode === 'inline';
const InlineComponent = React.forwardRef>(
({ className, style }, iframeRef) => {
- return ;
+ return ;
},
);
@@ -89,7 +74,7 @@ const ModalComponent = React.forwardRef
{shouldDisplayModal &&
createPortal(
-
+