cerfaparse 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 calibrae
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.fr.md

@@ -0,0 +1,159 @@
+[English](README.md) | [Français](README.fr.md)
+
+# cerfaparse
+
+Convertit les formulaires CERFA PDF non interactifs en PDF remplissables (AcroForm) avec des définitions de champs en JSON.
+
+## Fonctionnalités
+
+1. Extrait les cases caractères et les cases à cocher depuis la géométrie du PDF (via SVG)
+2. Extrait les libellés depuis la couche texte du PDF
+3. Associe les libellés aux groupes de champs pour générer des noms de champs pertinents
+4. Injecte des champs AcroForm (champs texte à cases + cases à cocher) dans le PDF
+5. Produit un fichier `.fields.json` avec toutes les définitions de champs (nom, type, libellé, position, maxLength)
+
+## Prérequis
+
+- Node.js >= 20
+- Outils CLI [Poppler](https://poppler.freedesktop.org/) (`pdftocairo`, `pdftotext`, `pdfinfo`)
+
+```bash
+# macOS
+brew install poppler
+
+# Debian/Ubuntu
+sudo apt-get install poppler-utils
+```
+
+## Installation
+
+```bash
+npm install cerfaparse
+```
+
+## Utilisation en ligne de commande
+
+```bash
+npx cerfaparse convert <input.pdf> [-o <output.pdf>]
+```
+
+Exemple :
+
+```bash
+npx cerfaparse convert docs/pdf-cerfa_cs8_bleu-recto-verso-140x202mm.pdf -o /tmp/cs8-fillable.pdf
+```
+
+Cela produit :
+- `/tmp/cs8-fillable.pdf` — le PDF original avec les champs AcroForm superposés
+- `/tmp/cs8-fillable.fields.json` — les définitions de champs en JSON
+
+## Format de sortie JSON (compatible ngx-formly)
+
+Le JSON de sortie utilise des définitions de champs compatibles [ngx-formly](https://formly.dev/) (`key`, `type`, `props`) avec les métadonnées spatiales intégrées dans `props` :
+
+```json
+{
+  "pages": [
+    {
+      "pageNumber": 1,
+      "fields": [
+        {
+          "key": "p1_nom",
+          "type": "input",
+          "props": {
+            "label": "Nom :",
+            "maxLength": 9,
+            "page": 1,
+            "pdfRect": { "x": 50.4, "y": 505.6, "width": 104.1, "height": 10.9 }
+          }
+        },
+        {
+          "key": "p1_oui",
+          "type": "checkbox",
+          "props": {
+            "label": "Oui",
+            "page": 1,
+            "pdfRect": { "x": 288.1, "y": 472.3, "width": 8.0, "height": 8.0 }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Types de champs
+
+| Type | Description | Props |
+|------|-------------|-------|
+| `input` | Champ texte — rendu libre dans formly, une case par caractère (peigne) dans le PDF lorsque `maxLength` est défini | `maxLength`, `label`, `page`, `pdfRect` |
+| `checkbox` | Case à cocher | `label`, `page`, `pdfRect` |
+
+## Utilisation en tant que bibliothèque (Node.js)
+
+```typescript
+import { convert } from 'cerfaparse';
+
+const { pdfOut, jsonOut, fields } = await convert('input.pdf', 'output.pdf');
+```
+
+Ou utilisez les fonctions individuellement :
+
+```typescript
+import { extractBoxes } from 'cerfaparse';
+import { extractSvg } from 'cerfaparse';
+```
+
+## Utilisation avec Angular / ngx-formly
+
+Le JSON de sortie est directement compatible avec [ngx-formly](https://formly.dev/). Exécutez `convert` au moment du build, puis utilisez les champs JSON tels quels :
+
+```typescript
+// Charger le JSON généré
+import fieldDefs from './assets/cerfa-cs8.fields.json';
+
+// Les champs sont déjà compatibles formly — il suffit de les aplatir
+const formlyFields = fieldDefs.pages.flatMap(page => page.fields);
+// Chaque champ contient : { key, type, props: { label, maxLength?, page, pdfRect } }
+```
+
+Les champs utilisent les types formly standard (`input`, `checkbox`). La prop `maxLength` limite la longueur de saisie dans le formulaire ; lors du remplissage du PDF, `maxLength` déclenche le rendu en peigne (un caractère par case).
+
+Pour remplir le PDF côté client avec [pdf-lib](https://pdf-lib.js.org/) (fonctionne dans le navigateur) :
+
+```typescript
+import { PDFDocument } from 'pdf-lib';
+
+const pdfBytes = await fetch('/assets/cerfa-cs8-fillable.pdf').then(r => r.arrayBuffer());
+const pdfDoc = await PDFDocument.load(pdfBytes);
+const form = pdfDoc.getForm();
+
+for (const [key, value] of Object.entries(formValues)) {
+  const field = fieldDefs.pages.flatMap(p => p.fields).find(f => f.key === key);
+  if (!field) continue;
+  if (field.type === 'input') {
+    form.getTextField(key).setText(String(value));
+  } else {
+    const cb = form.getCheckBox(key);
+    value ? cb.check() : cb.uncheck();
+  }
+}
+
+const filledBytes = await pdfDoc.save();
+// Déclencher le téléchargement ou l'affichage
+```
+
+## Tests
+
+```bash
+npx vitest run
+```
+
+## Fonctionnement
+
+1. **pdftocairo** convertit chaque page du PDF en SVG
+2. Les éléments SVG `<path>` avec un remplissage blanc sont classés comme cases caractères (contour blanc, épaisseur ~1) ou cases à cocher (contour foncé, épaisseur ~0.5)
+3. Les matrices de transformation affine SVG (y compris les transformations des ancêtres `<g>`/`<use>`) sont composées pour convertir les coordonnées SVG en coordonnées PDF (origine en bas à gauche, Y vers le haut)
+4. Les cases sont regroupées en lignes par proximité Y, puis découpées en champs par écarts X
+5. **pdftotext** fournit le texte des libellés et leurs positions via la sortie bbox, associés aux groupes de champs par proximité spatiale
+6. **pdf-lib** injecte les champs AcroForm avec des fonds transparents aux coordonnées PDF calculées

package/README.md

@@ -0,0 +1,159 @@
+[English](README.md) | [Français](README.fr.md)
+
+# cerfaparse
+
+Convert flat (non-interactive) French CERFA PDF forms into fillable AcroForm PDFs with JSON field definitions.
+
+## What it does
+
+1. Extracts character cells and checkboxes from the PDF geometry (via SVG)
+2. Extracts labels from the PDF text layer
+3. Maps labels to field groups to generate meaningful field names
+4. Injects AcroForm fields (combed text fields + checkboxes) into the PDF
+5. Outputs a `.fields.json` with all field definitions (name, type, label, position, maxLength)
+
+## Prerequisites
+
+- Node.js >= 20
+- [Poppler](https://poppler.freedesktop.org/) CLI tools (`pdftocairo`, `pdftotext`, `pdfinfo`)
+
+```bash
+# macOS
+brew install poppler
+
+# Debian/Ubuntu
+sudo apt-get install poppler-utils
+```
+
+## Install
+
+```bash
+npm install cerfaparse
+```
+
+## CLI Usage
+
+```bash
+npx cerfaparse convert <input.pdf> [-o <output.pdf>]
+```
+
+Example:
+
+```bash
+npx cerfaparse convert docs/pdf-cerfa_cs8_bleu-recto-verso-140x202mm.pdf -o /tmp/cs8-fillable.pdf
+```
+
+This produces:
+- `/tmp/cs8-fillable.pdf` — the original PDF with overlay AcroForm fields
+- `/tmp/cs8-fillable.fields.json` — JSON field definitions
+
+## JSON Output Format (ngx-formly compatible)
+
+The output JSON uses [ngx-formly](https://formly.dev/)-compatible field definitions (`key`, `type`, `props`) with spatial metadata embedded in `props`:
+
+```json
+{
+  "pages": [
+    {
+      "pageNumber": 1,
+      "fields": [
+        {
+          "key": "p1_nom",
+          "type": "input",
+          "props": {
+            "label": "Nom :",
+            "maxLength": 9,
+            "page": 1,
+            "pdfRect": { "x": 50.4, "y": 505.6, "width": 104.1, "height": 10.9 }
+          }
+        },
+        {
+          "key": "p1_oui",
+          "type": "checkbox",
+          "props": {
+            "label": "Oui",
+            "page": 1,
+            "pdfRect": { "x": 288.1, "y": 472.3, "width": 8.0, "height": 8.0 }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Field types
+
+| Type | Description | Props |
+|------|-------------|-------|
+| `input` | Text input — rendered as free-form in formly, mapped to one-char-per-box (combed) in PDF when `maxLength` is set | `maxLength`, `label`, `page`, `pdfRect` |
+| `checkbox` | Checkbox | `label`, `page`, `pdfRect` |
+
+## Library Usage (Node.js)
+
+```typescript
+import { convert } from 'cerfaparse';
+
+const { pdfOut, jsonOut, fields } = await convert('input.pdf', 'output.pdf');
+```
+
+Or use individual functions:
+
+```typescript
+import { extractBoxes } from 'cerfaparse';
+import { extractSvg } from 'cerfaparse';
+```
+
+## Using with Angular / ngx-formly
+
+The JSON output is directly compatible with [ngx-formly](https://formly.dev/). Run `convert` at build time, then use the JSON fields as-is:
+
+```typescript
+// Load the generated JSON
+import fieldDefs from './assets/cerfa-cs8.fields.json';
+
+// Fields are already formly-compatible — just flatten across pages
+const formlyFields = fieldDefs.pages.flatMap(page => page.fields);
+// Each field has: { key, type, props: { label, maxLength?, page, pdfRect } }
+```
+
+Fields use standard formly types (`input`, `checkbox`). The `maxLength` prop constrains input length in the form; when filling the PDF, `maxLength` triggers combed rendering (one character per cell).
+
+To fill the PDF client-side with [pdf-lib](https://pdf-lib.js.org/) (works in the browser):
+
+```typescript
+import { PDFDocument } from 'pdf-lib';
+
+const pdfBytes = await fetch('/assets/cerfa-cs8-fillable.pdf').then(r => r.arrayBuffer());
+const pdfDoc = await PDFDocument.load(pdfBytes);
+const form = pdfDoc.getForm();
+
+for (const [key, value] of Object.entries(formValues)) {
+  const field = fieldDefs.pages.flatMap(p => p.fields).find(f => f.key === key);
+  if (!field) continue;
+  if (field.type === 'input') {
+    form.getTextField(key).setText(String(value));
+  } else {
+    const cb = form.getCheckBox(key);
+    value ? cb.check() : cb.uncheck();
+  }
+}
+
+const filledBytes = await pdfDoc.save();
+// Trigger download or display
+```
+
+## Tests
+
+```bash
+npx vitest run
+```
+
+## How it works
+
+1. **pdftocairo** converts each PDF page to SVG
+2. SVG `<path>` elements with white fill are classified as character cells (white stroke, stroke-width ~1) or checkboxes (dark stroke, stroke-width ~0.5)
+3. SVG affine transform matrices (including ancestor `<g>`/`<use>` transforms) are composed to convert from SVG content coordinates to PDF coordinates (bottom-left origin, Y-up)
+4. Boxes are grouped into rows by Y-proximity, then split into fields by X-gaps
+5. **pdftotext** bbox output provides label text and positions, matched to field groups by spatial proximity
+6. **pdf-lib** injects AcroForm fields with transparent backgrounds at the computed PDF coordinates

package/dist/cli.d.ts

@@ -0,0 +1,27 @@
+/** Formly-compatible field types */
+type FieldType = 'input' | 'checkbox';
+interface PdfRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Formly-compatible field definition with spatial metadata */
+interface Field {
+    key: string;
+    type: FieldType;
+    props: {
+        label: string;
+        maxLength?: number;
+        page: number;
+        pdfRect: PdfRect;
+    };
+}
+
+declare function convert(inputPath: string, outputPath?: string): Promise<{
+    pdfOut: string;
+    jsonOut: string;
+    fields: Field[];
+}>;
+
+export { convert };