@quillmark/quillify 0.0.0-stage → 0.3.1

package/dist/types.js

@@ -0,0 +1,42 @@
+/** AcroForm field type codes as pdf.js reports them. */
+export const WIDGET_KINDS = ['Tx', 'Btn', 'Ch', 'Sig'];
+export const SNAKE_CASE = /^[a-z][a-z0-9_]*$/;
+/** The largest file `sanitize` opens. It bounds the compressed input. */
+export const MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * The most a file may come to once qpdf has it: the file qpdf writes together
+ * with what its Flate streams decode to and what its images declare, and
+ * qpdf's own memory. Of 1,423 published files the largest comes to
+ * 48,477,587 bytes (AF 4101), and qpdf's memory is 17,235,968 bytes after
+ * each. Their largest image is 6,026 by 4,523 pixels at a bit each, 3,410,342
+ * bytes (AF 1520), and the one that declares the most bytes is 2,322 by 2,916
+ * at three bytes each, 20,312,856 (AF 4101).
+ */
+export const MAX_INFLATED_BYTES = 64 * 1024 * 1024;
+/** The most pages and fields a form has and is taken. The engine takes at most 1,000 fields in a block. */
+export const MAX_PAGES = 25;
+export const MAX_WIDGETS = 1000;
+/** The limits a consumer prints before a read. A refusal's own `limit` is the one to print after it: `too_large` carries `MAX_INFLATED_BYTES` for the decoded bound. */
+export const limits = Object.freeze({
+    bytes: MAX_BYTES,
+    pages: MAX_PAGES,
+    fields: MAX_WIDGETS
+});
+/**
+ * The longest side a page has and is taken, in points, and the farthest its
+ * box reaches from the origin: the PDF specification's limit for a side (ISO
+ * 32000-1, Annex C). Of 2,127 published pages the longest is 3,456 (AFMC 1656).
+ */
+export const MAX_SIDE = 14_400;
+/**
+ * The most pixels the pictures of a dynamic form come to, each use counted.
+ * At four bytes a pixel that is 32 MB on a canvas, and as much in the
+ * background when the pictures are noise with an alpha channel. Of the 65 Air
+ * Force forms with a picture the largest comes to 6,958,512 (AF 4035).
+ */
+export const MAX_PICTURE_PIXELS = 8_000_000;
+/**
+ * How long `sanitize` works on a file before it refuses it. Of 59 published
+ * forms the slowest takes 2.7 s (SF 2809).
+ */
+export const MAX_SECONDS = 60;

package/dist/xfa-layer.d.ts

@@ -0,0 +1,40 @@
+import type { PDFPageProxy } from 'pdfjs-dist';
+/** One page after the browser has solved its layout. */
+export interface XfaPage {
+    layer: HTMLElement;
+    /** The page box in client coordinates. Every harvested rect is read against it. */
+    origin: DOMRect;
+    /** Page size in points. pdf.js normalizes XFA to points and emits CSS px, so 1px is 1pt. */
+    width: number;
+    height: number;
+}
+/**
+ * Somewhere out of sight to lay XFA pages out: a frame, whose document takes no
+ * rule from the host page and gives it none. `display: none` is not an option:
+ * it zeroes every rect, and it does that silently. The frame is hidden, out of
+ * the flow and of no size instead, so the host page shows, lays out and
+ * scrolls as it did, and the form inside is laid out all the same. A host page
+ * can still take the frame's boxes away, and `lay` throws when one has. It can
+ * take the frame out before it has loaded, and `ready` then rejects. And it
+ * can zoom the frame, which the frame undoes, or `lay` throws.
+ *
+ * The frame runs no script, and its policy lets its document load only an
+ * image from `blob:`, which is how pdf.js hands it a form's images, or from
+ * `data:`. A face of the form is not the document's to load: pdf.js makes it
+ * in the host page's realm, from the file's bytes, a `local()` name or a face
+ * the package ships.
+ */
+export declare class XfaStage {
+    #private;
+    /** The frame's document, once the stylesheet `XfaLayer.render` counts on applies in it. */
+    readonly ready: Promise<Document>;
+    constructor();
+    /**
+     * Lay one page out. Each page gets its own relative wrapper: `.xfaLayer` is
+     * absolutely positioned, so sibling layers would stack at the initial
+     * containing block and every page after the first would measure against the
+     * wrong origin.
+     */
+    lay(page: PDFPageProxy): Promise<XfaPage>;
+    close(): void;
+}

package/dist/xfa-layer.js

@@ -0,0 +1,143 @@
+import css from '../assets/xfa-layer.js';
+import { Refused } from './refusal.js';
+/** `XfaLayer.render` reads these off a link service; XFA forms here carry no links. */
+const NO_LINKS = {
+    addLinkAttributes() { },
+    externalLinkTarget: 0,
+    externalLinkRel: '',
+    externalLinkEnabled: true,
+    getDestinationHash: () => '',
+    getAnchorUrl: () => ''
+};
+const SHELL = `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src blob: data:">`;
+/**
+ * Somewhere out of sight to lay XFA pages out: a frame, whose document takes no
+ * rule from the host page and gives it none. `display: none` is not an option:
+ * it zeroes every rect, and it does that silently. The frame is hidden, out of
+ * the flow and of no size instead, so the host page shows, lays out and
+ * scrolls as it did, and the form inside is laid out all the same. A host page
+ * can still take the frame's boxes away, and `lay` throws when one has. It can
+ * take the frame out before it has loaded, and `ready` then rejects. And it
+ * can zoom the frame, which the frame undoes, or `lay` throws.
+ *
+ * The frame runs no script, and its policy lets its document load only an
+ * image from `blob:`, which is how pdf.js hands it a form's images, or from
+ * `data:`. A face of the form is not the document's to load: pdf.js makes it
+ * in the host page's realm, from the file's bytes, a `local()` name or a face
+ * the package ships.
+ */
+export class XfaStage {
+    #frame = document.createElement('iframe');
+    /** The frame's document, once the stylesheet `XfaLayer.render` counts on applies in it. */
+    ready;
+    constructor() {
+        const frame = this.#frame;
+        frame.sandbox.add('allow-same-origin');
+        frame.style.cssText = 'position:fixed;width:0;height:0;border:0;visibility:hidden';
+        frame.srcdoc = SHELL;
+        this.ready = new Promise((loaded, removed) => {
+            // A frame that leaves the document before it has loaded never loads.
+            const left = () => {
+                if (document.contains(frame))
+                    return;
+                watch.disconnect();
+                removed(new Error('The host page removed the frame the form is laid out in before it had loaded.'));
+            };
+            const watch = new MutationObserver(left);
+            frame.onload = () => {
+                watch.disconnect();
+                loaded();
+            };
+            document.body.append(frame);
+            // A zoom on the frame or an ancestor scales the layout inside it. The
+            // frame's own zoom undoes its ancestors', where the browser tells it.
+            const zoom = document.body.currentCSSZoom;
+            if (zoom)
+                frame.style.zoom = String(1 / zoom);
+            watch.observe(document, { childList: true, subtree: true });
+            left();
+        }).then(() => {
+            const frameDocument = frame.contentDocument;
+            const view = frameDocument.defaultView;
+            const sheet = new view.CSSStyleSheet();
+            sheet.replaceSync(css);
+            // pdf.js's sheet gives a field out of focus a background from a data: URL,
+            // which nothing here reads and a host's policy may refuse, a logged error
+            // for each field.
+            sheet.insertRule(':root { --xfa-unfocused-field-background: none; }', sheet.cssRules.length);
+            frameDocument.adoptedStyleSheets = [sheet];
+            // A sheet that did not apply leaves every field at its content size,
+            // and the rects read off it are wrong with no error.
+            const probe = frameDocument.createElement('div');
+            probe.className = 'xfaLayer';
+            frameDocument.body.append(probe);
+            const applies = view.getComputedStyle(probe).position === 'absolute';
+            probe.remove();
+            if (!applies)
+                throw new Error('The XFA stylesheet did not apply to the stage.');
+            // pdf.js names a face with its family in quotes. Chromium keeps the quotes
+            // as part of the name, and no rule of the form then asks for that face.
+            const faces = frameDocument.fonts;
+            const add = faces.add.bind(faces);
+            faces.add = (face) => {
+                if (/^".*"$/.test(face.family))
+                    face.family = face.family.slice(1, -1);
+                return add(face);
+            };
+            return frameDocument;
+        });
+    }
+    /**
+     * Lay one page out. Each page gets its own relative wrapper: `.xfaLayer` is
+     * absolutely positioned, so sibling layers would stack at the initial
+     * containing block and every page after the first would measure against the
+     * wrong origin.
+     */
+    async lay(page) {
+        const pdfjs = await import('pdfjs-dist');
+        const xfa = await page.getXfa();
+        if (!xfa)
+            throw new Error(`XFA page ${page.pageNumber} laid out to nothing.`);
+        const viewport = pdfjs.XfaLayer.getPageViewport(xfa, { scale: 1, rotation: 0 });
+        // pdf.js lays out a page area whose medium has no size, and gives the page
+        // a side of nothing, a negative one, or no number at all.
+        if (!(viewport.width > 0 && viewport.height > 0))
+            throw new Refused({ code: 'layout', detail: 'a page has no size' });
+        const frameDocument = await this.ready;
+        const host = frameDocument.createElement('div');
+        // On Linux Chromium fits text to the pixel grid and rounds each advance to
+        // a whole pixel, unless the text asks for geometric precision.
+        host.style.cssText = `position:relative;overflow:hidden;background:#fff;text-rendering:geometricPrecision;width:${viewport.width}px;height:${viewport.height}px`;
+        const layer = frameDocument.createElement('div');
+        layer.className = 'xfaLayer';
+        host.append(layer);
+        frameDocument.body.append(host);
+        pdfjs.XfaLayer.render({
+            viewport: viewport.clone({ dontFlip: true }),
+            div: layer,
+            xfaHtml: xfa,
+            linkService: NO_LINKS,
+            intent: 'display'
+        });
+        await frameDocument.fonts.ready;
+        // A picture has a size once it has loaded, and one that fails to has none.
+        await Promise.all(Array.from(layer.querySelectorAll('img'), (img) => img.complete || new Promise((done) => (img.onload = img.onerror = done))));
+        // A frame the host page hid or took out gives the wrapper no box.
+        if (!host.getClientRects().length)
+            throw new Error('The host page hid or removed the frame the form is laid out in.');
+        // The frame's zoom times its ancestors' is a 32-bit float, and for some
+        // zooms no value brings it to 1. A rule marked `!important` beats the
+        // frame's own.
+        if ((this.#frame.currentCSSZoom ?? 1) !== 1)
+            throw new Error("The host page's zoom scales the frame the form is laid out in.");
+        return {
+            layer,
+            origin: host.getBoundingClientRect(),
+            width: viewport.width,
+            height: viewport.height
+        };
+    }
+    close() {
+        this.#frame.remove();
+    }
+}

package/dist/xfa-widgets.d.ts

@@ -0,0 +1,36 @@
+import type { XfaPage } from './xfa-layer.js';
+export type XfaKind = 'text' | 'multiline' | 'checkbox' | 'radio' | 'choice' | 'signature';
+export interface XfaWidget {
+    /**
+     * `p<page>.<SOM path>`, with `#n` where that repeats. It is the AcroForm field
+     * name of every control but a radio, whose field is its group's.
+     */
+    name: string;
+    kind: XfaKind;
+    page: number;
+    /** Points, top-left origin, page-relative: the rect `form.json` wants. */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** The exclusion group this radio belongs to, as a SOM path. */
+    group?: string;
+    /** This radio's own on-state, which is how the group tells its options apart. */
+    on?: string;
+    tooltip?: string;
+    options: string[];
+}
+/**
+ * Where the browser paints a check box or a radio button. pdf.js gives the
+ * control the width its template sets and the height of what is left of its
+ * row, and the browser paints the largest square centered in that box.
+ */
+export declare function square(box: DOMRect): Pick<DOMRect, 'left' | 'top' | 'width' | 'height'>;
+/**
+ * Every control on a laid-out page, named after what the form called it.
+ *
+ * What the form called it is its SOM path: the `xfaname` attributes from the
+ * layer root down to the control. Its `id` or `name` is read only when there
+ * is none.
+ */
+export declare function harvestWidgets(page: XfaPage, pageNumber: number): XfaWidget[];

package/dist/xfa-widgets.js

@@ -0,0 +1,131 @@
+import { Refused } from './refusal.js';
+/**
+ * Where the browser paints a check box or a radio button. pdf.js gives the
+ * control the width its template sets and the height of what is left of its
+ * row, and the browser paints the largest square centered in that box.
+ */
+export function square(box) {
+    const side = Math.min(box.width, box.height);
+    return {
+        left: box.left + (box.width - side) / 2,
+        top: box.top + (box.height - side) / 2,
+        width: side,
+        height: side
+    };
+}
+/**
+ * Every control on a laid-out page, named after what the form called it.
+ *
+ * What the form called it is its SOM path: the `xfaname` attributes from the
+ * layer root down to the control. Its `id` or `name` is read only when there
+ * is none.
+ */
+export function harvestWidgets(page, pageNumber) {
+    const { layer, origin } = page;
+    const view = layer.ownerDocument.defaultView;
+    const widgets = [];
+    const seen = new Map();
+    const places = new Set();
+    // No field of a quill prints a barcode of what was entered, or hides it.
+    for (const [selector, construct] of [
+        ['.xfaBarcode', 'barcode'],
+        ['.xfaPasswordEdit', 'password']
+    ])
+        if (layer.querySelector(selector))
+            throw new Refused({ code: 'unpaintable', page: pageNumber - 1, construct });
+    // A signature field is read after every control, so a control that shares its
+    // SOM path keeps the occurrence count it has without it.
+    for (const el of [
+        ...layer.querySelectorAll('input, select, textarea'),
+        ...layer.querySelectorAll('.xfaSignature')
+    ]) {
+        const style = view.getComputedStyle(el);
+        if (style.visibility === 'hidden' || style.display === 'none')
+            continue;
+        const box = el.getBoundingClientRect();
+        if (box.width <= 0 || box.height <= 0)
+            continue;
+        const type = el.getAttribute('type')?.toLowerCase();
+        const tag = el.tagName.toLowerCase();
+        const kind = tag === 'div'
+            ? 'signature'
+            : tag === 'select'
+                ? 'choice'
+                : tag === 'textarea'
+                    ? 'multiline'
+                    : type === 'checkbox'
+                        ? 'checkbox'
+                        : type === 'radio'
+                            ? 'radio'
+                            : 'text';
+        const rect = kind === 'checkbox' || kind === 'radio' ? square(box) : box;
+        const path = somPath(el, layer);
+        // A SOM path can recur: nine do on DAF 1288, six of them within a page, and
+        // every field on its second page starts `Page1.`. The page and an occurrence
+        // count make the AcroForm name unique without losing what the form called it.
+        const base = `p${pageNumber}.${path}`;
+        const x = +(rect.left - origin.left).toFixed(2);
+        const y = +(rect.top - origin.top).toFixed(2);
+        const w = +rect.width.toFixed(2);
+        const h = +rect.height.toFixed(2);
+        // pdf.js gives a control the place its layout comes to, on the page or not.
+        if (x >= page.width || y >= page.height || x + w <= 0 || y + h <= 0)
+            throw new Refused({ code: 'layout', detail: 'a field is off its page' });
+        const tooltip = tooltipOf(el);
+        const options = tag === 'select'
+            ? [...el.options]
+                .map((o) => o.textContent?.trim() ?? '')
+                .filter(Boolean)
+            : [];
+        // A template can hold a field twice at one place, the second drawn over the
+        // first. Controls that read the same in everything but their order are one field.
+        const place = JSON.stringify([base, kind, x, y, w, h, tooltip, options]);
+        if (places.has(place))
+            continue;
+        places.add(place);
+        const count = (seen.get(base) ?? 0) + 1;
+        seen.set(base, count);
+        const excl = kind === 'radio' ? exclusion(el, layer) : null;
+        widgets.push({
+            name: count === 1 ? base : `${base}#${count}`,
+            kind,
+            page: pageNumber - 1,
+            x,
+            y,
+            w,
+            h,
+            group: excl ? `p${pageNumber}.${somPath(excl, layer)}` : undefined,
+            // The leaf of the SOM path is what the form calls this option. It becomes
+            // the widget's on-state, which is the only thing telling one member of an
+            // exclusion group from another.
+            on: excl ? path.slice(path.lastIndexOf('.') + 1) : undefined,
+            tooltip,
+            options
+        });
+    }
+    return widgets;
+}
+/** `Page1.form1.page1.TypeRequest.type_of_request`, root-first. */
+function somPath(el, layer) {
+    const parts = [];
+    for (let node = el; node && node !== layer; node = node.parentElement) {
+        const name = node.getAttribute('xfaname');
+        if (name)
+            parts.unshift(name);
+    }
+    return parts.length ? parts.join('.') : el.id || el.getAttribute('name') || 'field';
+}
+function exclusion(el, layer) {
+    const found = el.closest('.xfaExclgroup[xfaname]');
+    return found && layer.contains(found) ? found : null;
+}
+/** The hover text a filler reads. */
+function tooltipOf(el) {
+    const field = el.closest('.xfaField');
+    const direct = el.getAttribute('aria-label') || el.getAttribute('title') || field?.getAttribute('title');
+    if (direct?.trim())
+        return direct.trim();
+    // pdf.js rewrites the caption's class for a check-button UI, which is every
+    // radio and every checkbox, so the one selector misses both.
+    return (field?.querySelector('.xfaCaption, .xfaCaptionForCheckButton')?.textContent?.trim() || undefined);
+}

package/dist/xfa.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A dynamic Adobe LiveCycle form as an ordinary static AcroForm, or the input
+ * unchanged when it is not one.
+ *
+ * In a dynamic form the fields exist only as XML inside `/AcroForm /XFA`:
+ * `/Fields` is empty, and the one page in the file is a placeholder, most often
+ * a "Please wait" notice. Converting one takes an XFA layout engine, and pdf.js
+ * has one. This runs it, reads the geometry the browser solved off the DOM, and
+ * writes both the printed page and the fields back out as a PDF the later
+ * stages already take.
+ *
+ * It is a normalization: bytes in, bytes out, and every later stage reads the
+ * result as it reads a static form.
+ */
+export declare function xfaToAcroForm(bytes: Uint8Array, signal?: AbortSignal): Promise<Uint8Array>;