Skip to content

Commit 9069558

Browse files
bendersejbendersej
authored
feat: introduce DETECT_FIELDS for automatic detection of flattened fields (#27)
## Background `CREATE_FIELD` required callers to manually specify each field's type, position, dimensions, and page - making programmatic field creation tedious and error-prone. `DETECT_FIELDS` replaces this by automatically detecting flattened form fields in a document. ## Changes - Replace `createField` with `detectFields()` in the React embed component (`EmbedActions`, `useEmbed`, `EmbedPDF`) - Remove `CreateFieldOptions` discriminated union types and `CreateFieldResult` - Replace `CREATE_FIELD` with `DETECT_FIELDS` in iframe documentation - Simplify Playwright automation example: accept document URL/path inline, load local files via `LOAD_DOCUMENT` data URL, log detected field count - Remove config file indirection, zod dependency, and schema from automation example - Update all tests and type assertions - Update README docs across react, documentation, and root ## Notes Breaking change in theory but practically no usage for `createField` - safe to release as major.
1 parent bc37f1c commit 9069558

File tree

14 files changed

+107
-862
lines changed

14 files changed

+107
-862
lines changed

‎.changeset/replace-create-field-with-detect-fields.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
"@simplepdf/react-embed-pdf": major
3+
---
4+
5+
Replaces `createField` with `detectFields` for automatic form field detection. This is a breaking change: the `createField` action and `CreateFieldOptions` type have been removed.
6+
7+
If you are not using `actions.createField(...)` or `sendEvent("CREATE_FIELD", ...)`, you can safely update to this new major version.
8+
9+
```ts
10+
// Before (removed)
11+
await actions.createField({ type: "TEXT", page: 1, x: 100, y: 700, width: 200, height: 30 });
12+
13+
// After
14+
await actions.detectFields();
15+
```

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ SimplePDF Embed uses a **fully client-side architecture** for PDF processing:
189189

190190
| Limitation | Description | Workaround |
191191
| --------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- |
192-
| **No server-side PDF generation** | Cannot generate PDFs from templates server-side | Use client-side field creation via `createField()` |
192+
| **No server-side PDF generation** | Cannot generate PDFs from templates server-side | Use client-side field detection via `detectFields()` |
193193
| **No bulk processing** | Cannot process multiple PDFs in batch | Process sequentially or use dedicated server-side library |
194194
| **No programmatic PDF retrieval** | Cannot get modified PDF as Blob/Base64 in JS | Use webhooks + server storage for programmatic access |
195195
| **No persistent storage** | PDFs don't persist without user action | Use `companyIdentifier` for server-side submission storage |
@@ -285,7 +285,7 @@ Currently, page manipulation (add/remove/re-arrange/rotate) is only available th
285285
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
286286
| `goTo` | Navigate to a specific page |
287287
| `selectTool` | Select a tool (`TEXT`, `BOXED_TEXT`, `CHECKBOX`, `PICTURE`, `SIGNATURE`) or `null` for cursor |
288-
| `createField` | Create a field at a specified position |
288+
| `detectFields` | Automatically detect form fields in the document |
289289
| `removeFields` | Remove fields by ID, by page, or all fields |
290290
| `getDocumentContent` | Extract text content from the document |
291291
| `submit` | Submit the document (with optional device download) |

‎documentation/IFRAME.md‎

Lines changed: 5 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -185,16 +185,8 @@ await sendEvent("GO_TO", { page: 3 });
185185
// Select a tool
186186
await sendEvent("SELECT_TOOL", { tool: "TEXT" }); // or "CHECKBOX", "SIGNATURE", "PICTURE", "BOXED_TEXT", null
187187

188-
// Create a field
189-
await sendEvent("CREATE_FIELD", {
190-
type: "TEXT",
191-
page: 1,
192-
x: 100,
193-
y: 700,
194-
width: 200,
195-
height: 30,
196-
value: "Hello World",
197-
});
188+
// Detect fields in the document
189+
await sendEvent("DETECT_FIELDS", {});
198190

199191
// Remove all fields (or specific ones)
200192
await sendEvent("REMOVE_FIELDS", {}); // Remove all
@@ -290,34 +282,11 @@ Select a drawing tool or return to cursor mode.
290282
| ------ | ---------------- | -------- | ---------------------------------------------------------------------------------------- |
291283
| `tool` | `string \| null` | Yes | `"TEXT"`, `"BOXED_TEXT"`, `"CHECKBOX"`, `"SIGNATURE"`, `"PICTURE"`, or `null` for cursor |
292284

293-
#### CREATE_FIELD
294-
295-
Create a new field on the document.
285+
#### DETECT_FIELDS
296286

297-
| Field | Type | Required | Description |
298-
| -------- | -------- | -------- | --------------------------------------------------------------------- |
299-
| `type` | `string` | Yes | `"TEXT"`, `"BOXED_TEXT"`, `"CHECKBOX"`, `"SIGNATURE"`, or `"PICTURE"` |
300-
| `page` | `number` | Yes | Page number (1-indexed) |
301-
| `x` | `number` | Yes | X coordinate (PDF points from left) |
302-
| `y` | `number` | Yes | Y coordinate (PDF points from bottom) |
303-
| `width` | `number` | Yes | Field width in PDF points |
304-
| `height` | `number` | Yes | Field height in PDF points |
305-
| `value` | `string` | No | Initial value (see value formats below) |
287+
Automatically detect form fields in the document.
306288

307-
**Value formats by field type:**
308-
309-
- `TEXT` / `BOXED_TEXT`: Plain text content
310-
- `CHECKBOX`: `"checked"` or `"unchecked"`
311-
- `PICTURE`: Data URL (base64)
312-
- `SIGNATURE`: Data URL (base64 image) or plain text (generates a typed signature)
313-
314-
**Response data:**
315-
316-
```json
317-
{
318-
"field_id": "f_kj8n2hd9x3m1p"
319-
}
320-
```
289+
_No data fields required._
321290

322291
#### REMOVE_FIELDS
323292

‎examples/with-playwright-automation/README.md‎

Lines changed: 12 additions & 224 deletions
Original file line numberDiff line numberDiff line change
@@ -1,244 +1,33 @@
11
# SimplePDF Editor Automation
22

3-
Playwright-based CLI tool for programmatically creating and positioning fields in PDF documents using the SimplePDF editor.
4-
5-
## Features
6-
7-
- Create TEXT, BOXED_TEXT, CHECKBOX, SIGNATURE, and PICTURE fields
8-
- Position fields using PDF standard coordinates (bottom-left origin)
9-
- Pre-fill field values including typed signatures
10-
- Browser opens for visual inspection after field creation
3+
Playwright-based CLI tool for automatically detecting form fields in PDF documents using the SimplePDF editor.
114

125
## Quick Start
136

147
```bash
158
npm install
16-
npx tsx src/index.ts example.config.json
9+
npx tsx src/index.ts https://example.com/form.pdf
1710
```
1811

1912
## Usage
2013

2114
```bash
22-
npx tsx src/index.ts <config.json> [options]
15+
npx tsx src/index.ts <document> [options]
16+
17+
Arguments:
18+
document URL or local file path to a PDF
2319

2420
Options:
2521
--company-identifier Your SimplePDF company identifier (default: embed)
2622
--help Show help
2723
```
2824

29-
### Using Your Company Identifier
25+
### Examples
3026

3127
```bash
32-
npx tsx src/index.ts config.json --company-identifier mycompany
33-
```
34-
35-
This connects to `https://mycompany.simplepdf.com`.
36-
37-
## Configuration
38-
39-
Create a JSON configuration file:
40-
41-
```json
42-
{
43-
"document": "https://example.com/document.pdf",
44-
"fields": [...]
45-
}
46-
```
47-
48-
### Document Source
49-
50-
| Format | Example |
51-
|--------|---------|
52-
| URL | `"https://example.com/doc.pdf"` |
53-
| Local file | `"./documents/form.pdf"` |
54-
55-
## Field Types
56-
57-
### TEXT
58-
59-
Single-line text input.
60-
61-
```json
62-
{
63-
"type": "TEXT",
64-
"x": 100,
65-
"y": 700,
66-
"width": 200,
67-
"height": 20,
68-
"page": 1,
69-
"value": "John Doe"
70-
}
71-
```
72-
73-
### BOXED_TEXT
74-
75-
Multi-line text with border.
76-
77-
```json
78-
{
79-
"type": "BOXED_TEXT",
80-
"x": 100,
81-
"y": 600,
82-
"width": 300,
83-
"height": 100,
84-
"page": 1,
85-
"value": "Additional notes here..."
86-
}
87-
```
88-
89-
### CHECKBOX
90-
91-
Checkable box. Must be square (equal width/height).
92-
93-
```json
94-
{
95-
"type": "CHECKBOX",
96-
"x": 100,
97-
"y": 550,
98-
"width": 12,
99-
"height": 12,
100-
"page": 1,
101-
"value": true
102-
}
103-
```
104-
105-
### SIGNATURE
106-
107-
Signature field with multiple value formats.
108-
109-
```json
110-
{
111-
"type": "SIGNATURE",
112-
"x": 100,
113-
"y": 450,
114-
"width": 200,
115-
"height": 60,
116-
"page": 1,
117-
"value": "John Doe"
118-
}
119-
```
120-
121-
**Value formats:**
122-
123-
| Format | Example | Result |
124-
|--------|---------|--------|
125-
| Plain text | `"John Doe"` | Typed signature (cursive font) |
126-
| URL | `"https://example.com/sig.png"` | Drawn signature from image |
127-
| Data URL | `"data:image/png;base64,..."` | Drawn signature from base64 |
128-
| Local file | `"./signatures/john.png"` | Drawn signature from file |
129-
130-
### PICTURE
131-
132-
Image field.
133-
134-
```json
135-
{
136-
"type": "PICTURE",
137-
"x": 100,
138-
"y": 300,
139-
"width": 150,
140-
"height": 150,
141-
"page": 1,
142-
"value": "https://example.com/photo.jpg"
143-
}
144-
```
145-
146-
**Value formats:** URL, data URL, or local file path.
147-
148-
## Coordinate System
149-
150-
Uses PDF standard coordinates:
151-
152-
```
153-
┌─────────────────────────────┐
154-
│ │ ↑
155-
│ │ │
156-
│ PDF Page │ │ Y increases
157-
│ │ │
158-
│ │ │
159-
└─────────────────────────────┘
160-
(0,0) ───────────────────────→
161-
X increases
162-
```
163-
164-
- **Origin**: Bottom-left corner of page
165-
- **Units**: Points (1/72 inch)
166-
- **Y-axis**: Increases upward
167-
168-
## Examples
169-
170-
### Basic Form Fill
171-
172-
```json
173-
{
174-
"document": "https://cdn.simplepdf.com/simple-pdf/assets/sample.pdf",
175-
"fields": [
176-
{
177-
"type": "TEXT",
178-
"x": 72,
179-
"y": 700,
180-
"width": 200,
181-
"height": 14,
182-
"page": 1,
183-
"value": "John"
184-
},
185-
{
186-
"type": "TEXT",
187-
"x": 320,
188-
"y": 700,
189-
"width": 200,
190-
"height": 14,
191-
"page": 1,
192-
"value": "Doe"
193-
},
194-
{
195-
"type": "SIGNATURE",
196-
"x": 72,
197-
"y": 100,
198-
"width": 200,
199-
"height": 60,
200-
"page": 1,
201-
"value": "John Doe"
202-
}
203-
]
204-
}
205-
```
206-
207-
### Multi-Page Document
208-
209-
```json
210-
{
211-
"document": "./documents/multi-page.pdf",
212-
"fields": [
213-
{
214-
"type": "TEXT",
215-
"x": 72,
216-
"y": 700,
217-
"width": 200,
218-
"height": 14,
219-
"page": 1,
220-
"value": "Page 1 content"
221-
},
222-
{
223-
"type": "TEXT",
224-
"x": 72,
225-
"y": 700,
226-
"width": 200,
227-
"height": 14,
228-
"page": 2,
229-
"value": "Page 2 content"
230-
},
231-
{
232-
"type": "SIGNATURE",
233-
"x": 72,
234-
"y": 100,
235-
"width": 200,
236-
"height": 60,
237-
"page": 3,
238-
"value": "Final Signature"
239-
}
240-
]
241-
}
28+
npx tsx src/index.ts https://example.com/form.pdf
29+
npx tsx src/index.ts ./documents/form.pdf
30+
npx tsx src/index.ts https://example.com/form.pdf --company-identifier mycompany
24231
```
24332

24433
## How It Works
@@ -247,9 +36,8 @@ The tool uses the SimplePDF editor's iframe postMessage API:
24736

24837
1. Embeds the editor in an iframe
24938
2. Waits for `DOCUMENT_LOADED` event
250-
3. Sends `REMOVE_FIELDS` to remove existing fields
251-
4. Sends `CREATE_FIELD` for each configured field
252-
5. Leaves browser open for inspection
39+
3. Sends `DETECT_FIELDS` to automatically detect form fields
40+
4. Leaves browser open for inspection
25341

25442
## Requirements
25543

0 commit comments

Comments
 (0)