/** * The form layer and the form service against a real kernel and the real engine (the forms are * the engine's): a text box fills in on blur and a checkbox on a click, a field without a border * gets the settings' edge, a press on a field stays out of the page below and still reaches the * field's PDF "mouse down" action, a click on a read-only "button" runs its action, with the * render plugin each field's picture shows the state it's in, and the service's `valueOf()` and * `controlOf()` follow one field both ways. */ import { readFile } from 'node:fs/promises'; import { dirname, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; import { Component, inject, signal } from '@angular/core'; import { TestBed, type ComponentFixture } from '@angular/core/testing'; import { ReactiveFormsModule } from '@angular/forms'; import { afterEach, describe, expect, it, vi } from 'vitest'; import { annotationKey, type Engine, type PageRef } from '@embedpdf/core'; import { pageTransform } from '@embedpdf/core-geometry'; import { createLocalEngine } from '@embedpdf/engine'; import { actionsPlugin, ActionsToken, type ActionExecutedEvent } from '@embedpdf/plugin-actions'; import { annotationPlugin } from '@embedpdf/plugin-annotation'; import type { AnnotationRef } from '@embedpdf/plugin-annotation/contract'; import { FormToken as FormHostToken } from '@embedpdf/plugin-form/contract/host'; import { RenderToken as RenderHostToken } from '@embedpdf/plugin-render/contract/host'; import { createPageContext, EPDF_PAGE, EpdfKernelHost, type EmbedPdfFeature, } from '@embedpdf/angular/runtime'; import { withInteraction } from '@embedpdf/angular/interaction'; import { withRender } from '@embedpdf/angular/render'; import { EpdfForm, EpdfFormLayer, FormToken, toFieldRef, withForm } from '@embedpdf/angular/form'; import { EpdfSignature, withSignature } from '@embedpdf/angular/signature'; import { kernelOf, mount, viewerHost } from './fixtures'; const here = dirname(fileURLToPath(import.meta.url)); const fixtures = resolve(here, '../../../engine/main/test/fixtures'); const wasm = resolve(here, '../../../engine/runtime/npm/wasm32/lib/embedpdf.wasm'); /** The real engine. happy-dom's browser-shaped globals would steer the wasm toward fetch(): hand it over. */ async function realEngine(): Promise { const wasmBinary = new Uint8Array(await readFile(wasm)); return createLocalEngine({ runtime: { prefer: 'wasm', wasmBinary } }); } const LETTER = { width: 612, height: 792 }; /** The page, at scale 1 from the top-left corner of the screen, once the test names it. */ const shownPage = signal<{ documentId: string; ref: PageRef } | null>(null); @Component({ selector: 'test-form-page', imports: [EpdfFormLayer], providers: [ { provide: EPDF_PAGE, useFactory: () => createPageContext({ documentId: () => shownPage()!.documentId, ref: () => shownPage()!.ref, view: () => 'test-view', pageIndex: signal(0), frame: signal({ top: 0, right: 0, bottom: 0, left: 0 }), transform: signal( pageTransform({ pageSize: LETTER, rotation: 0, scale: 1, baseScale: 1, dpr: 1 }), ), getRect: () => new DOMRect(0, 0, LETTER.width, LETTER.height), }), }, ], template: `
`, }) class FormPage { presses = 0; } @Component({ selector: 'test-form-shell', imports: [FormPage], template: ` @if (page()) { } `, }) class FormShell { protected readonly page = shownPage; } /** A viewer on the real engine with `file` open as `id`, and its form read. */ async function openForm( file: string, id: string, features: EmbedPdfFeature[] = [withInteraction(), withForm()], ) { const bytes = new Uint8Array(await readFile(resolve(fixtures, file))); const fixture = await mount( viewerHost({ template: '', imports: [FormShell], // The viewer's own engine: destroyed after the kernel, when the test's module goes. config: { engine: realEngine, initialDocuments: [{ source: { kind: 'bytes', id, bytes } }] }, features, }), ); await vi.waitFor(() => expect(kernelOf(fixture).tryCapability(FormToken)).toBeTruthy(), { timeout: 20_000, }); const form = kernelOf(fixture).capability(FormToken); await form.refresh(); return { fixture, form }; } /** Show the page with the form layer on it, and wait for its controls. */ async function showPage(fixture: ComponentFixture, documentId: string, ref: PageRef) { shownPage.set({ documentId, ref }); await fixture.whenStable(); } const element = (fixture: ComponentFixture) => fixture.nativeElement as HTMLElement; afterEach(() => { shownPage.set(null); TestBed.resetTestingModule(); vi.restoreAllMocks(); }); describe(' over fields made from code', () => { it( 'fills in a text box and a checkbox, and draws the edge of a field without a border', { timeout: 45_000 }, async () => { const { fixture, form } = await openForm('hello_world.pdf', 'blank', [ withInteraction(), withForm({ fields: { border: '#ea580c' } }), ]); const page = kernelOf(fixture).documents.getPage(0, 'blank')!.ref; await form.create({ kind: 'text', name: 'name', widgets: [{ page, rect: { x: 72, y: 100, width: 160, height: 20 }, color: '#94a3b8' }], }); await form.create({ kind: 'checkbox', name: 'agree', widgets: [{ page, rect: { x: 72, y: 140, width: 14, height: 14 } }], }); await showPage(fixture, 'blank', page); const input = await vi.waitFor(() => { const found = element(fixture).querySelector('input[aria-label="name"]'); expect(found).not.toBeNull(); return found!; }); input.dispatchEvent(new FocusEvent('focus')); input.value = 'Ada Lovelace'; input.dispatchEvent(new Event('input', { bubbles: true })); input.dispatchEvent(new FocusEvent('blur')); await vi.waitFor(() => expect(form.getValue(toFieldRef('name'))).toEqual({ value: 'Ada Lovelace' }), ); const checkbox = element(fixture).querySelector( '[role="checkbox"][aria-label="agree"]', )!; // A click activates the widget once its write is answered: waited for, so it runs before the page goes. const activated = vi.spyOn(kernelOf(fixture).capability(FormHostToken), 'activateWidget'); checkbox.click(); await vi.waitFor(() => expect(form.getValue(toFieldRef('agree'))).toEqual({ checked: true })); await vi.waitFor(() => expect(activated).toHaveBeenCalled()); // Each control's box sits over its widget, and always takes the pointer. expect(checkbox.style.position).toBe('absolute'); expect(checkbox.style.pointerEvents).toBe('auto'); expect(checkbox.style.left).toBe('72px'); expect(checkbox.style.top).toBe('140px'); // The checkbox has no border of its own: the layer draws its edge in the setting's color. expect(checkbox.style.boxShadow).toContain('#ea580c'); // The text box has its own border: no edge. expect(input.parentElement!.style.boxShadow).toBe(''); // A press on a field stops at its box, before the page below sees it, and still reaches the // field's PDF actions as "mouse down" (the box's native listener sends it). const host = kernelOf(fixture).capability(FormHostToken); const events: string[] = []; vi.spyOn(host, 'notifyWidgetEvent').mockImplementation((_field, _widget, event) => { events.push(event); }); input.parentElement!.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true })); // Exactly once: the box's widget events send it, and the listener that stops the press // doesn't send it again. expect(events.filter((event) => event === 'mouseDown')).toHaveLength(1); const shell = fixture.debugElement.query( (node) => node.componentInstance instanceof FormPage, ); expect((shell.componentInstance as FormPage).presses).toBe(0); }, ); }); /** * A field turned a quarter (`/MK /R`): its control sits in the field's frame, turned with it * about its middle, so what's typed reads the way the field does. An unturned field's control * is placed as it always was. */ describe(' over a turned field', () => { it( 'places the control in the field’s frame and turns it with the field', { timeout: 45_000 }, async () => { const { fixture, form } = await openForm('hello_world.pdf', 'blank'); const page = kernelOf(fixture).documents.getPage(0, 'blank')!.ref; // Its frame is 160 × 20; turned 270° it stands 20 wide and 160 tall. await form.create({ kind: 'text', name: 'side', widgets: [{ page, box: { x: 72, y: 300, width: 160, height: 20 }, rotation: 270 }], }); await form.create({ kind: 'text', name: 'flat', widgets: [{ page, rect: { x: 72, y: 100, width: 160, height: 20 } }], }); await showPage(fixture, 'blank', page); const side = await vi.waitFor(() => { const found = element(fixture).querySelector('input[aria-label="side"]'); expect(found).not.toBeNull(); return found!; }); const box = side.parentElement!; expect(box.style.left).toBe('72px'); expect(box.style.top).toBe('300px'); expect(box.style.width).toBe('160px'); expect(box.style.height).toBe('20px'); expect(box.style.transform).toBe('rotate(270deg)'); // The item says where it stands: the frame turned about its middle. const item = form.listWidgets(page).find((each) => each.label === 'side')!; expect(item.rotation).toBe(270); expect(item.rect).toEqual({ x: 142, y: 230, width: 20, height: 160 }); const flat = element(fixture).querySelector('input[aria-label="flat"]')!; expect(flat.parentElement!.style.transform).toBe(''); expect(flat.parentElement!.style.left).toBe('72px'); // Typing into the turned field fills it in, and it keeps its turn. side.dispatchEvent(new FocusEvent('focus')); side.value = 'Up the page'; side.dispatchEvent(new Event('input', { bubbles: true })); side.dispatchEvent(new FocusEvent('blur')); await vi.waitFor(() => expect(form.getValue(toFieldRef('side'))).toEqual({ value: 'Up the page' }), ); expect(form.listWidgets(page).find((each) => each.label === 'side')!.rotation).toBe(270); }, ); }); /** * With the render plugin, the layer paints each field as the engine draws it: one picture per * widget, the one of the state it shows. The engine encodes pictures with a 2D canvas, which * happy-dom doesn't have, so the render plugin's pictures are stand-ins here: a URL naming widget * and state. */ describe(' field pictures', () => { it( 'paints each field, and a checkbox its new state once it changes', { timeout: 45_000 }, async () => { const { fixture, form } = await openForm('hello_world.pdf', 'blank', [ withInteraction(), withRender(), withForm(), ]); const page = kernelOf(fixture).documents.getPage(0, 'blank')!.ref; await form.create({ kind: 'text', name: 'name', widgets: [{ page, rect: { x: 72, y: 100, width: 160, height: 20 } }], }); await form.create({ kind: 'checkbox', name: 'agree', widgets: [{ page, rect: { x: 72, y: 140, width: 14, height: 14 } }], }); const [text, check] = kernelOf(fixture).capability(FormHostToken).listShownWidgets(page); const checkBox = { x: 72, y: 140, width: 14, height: 14 }; const picture = (widget: AnnotationRef, state: string | null, rect: typeof checkBox) => ({ ref: widget, mode: 'normal' as const, state, rect, image: { objectUrl: () => ({ abortWith: async () => ({ url: `blob:${annotationKey(widget)}:${state}`, revoke: () => {}, }), }), }, }); const drawn = [ picture(text!.ref, null, { x: 72, y: 100, width: 160, height: 20 }), picture(check!.ref, 'Off', checkBox), picture(check!.ref, 'Yes', checkBox), ]; // The render plugin's door, as it answers: the asked widgets' pictures, each at its version. const fetches = vi.spyOn(kernelOf(fixture).capability(RenderHostToken), 'renderAppearances'); fetches.mockImplementation( async (_page, { items }) => drawn.map((each) => ({ ...each, version: items.find((item) => annotationKey(item.ref) === annotationKey(each.ref))?.version ?? 0, })) as never, ); await showPage(fixture, 'blank', page); const images = () => [...element(fixture).querySelectorAll('epdf-field-pictures img')]; const pictures = () => images().map((image) => image.getAttribute('src')); await vi.waitFor(async () => { await fixture.whenStable(); expect(pictures()).toHaveLength(2); }); const checkKey = annotationKey(check!.ref); expect(pictures()).toEqual([`blob:${annotationKey(text!.ref)}:null`, `blob:${checkKey}:Off`]); // Placed at its widget's box, in page pixels. expect((images()[1] as HTMLElement).style.top).toBe('140px'); // A click activates the widget once its write is answered: waited for, so it runs before the page goes. const activated = vi.spyOn(kernelOf(fixture).capability(FormHostToken), 'activateWidget'); // A checkbox switches to the picture it holds: nothing is fetched. const asked = fetches.mock.calls.length; element(fixture).querySelector('[role="checkbox"][aria-label="agree"]')!.click(); await vi.waitFor(() => expect(form.getValue(toFieldRef('agree'))).toEqual({ checked: true })); await vi.waitFor(async () => { await fixture.whenStable(); expect(pictures()[1]).toBe(`blob:${checkKey}:Yes`); }); await vi.waitFor(() => expect(activated).toHaveBeenCalled()); expect(fetches.mock.calls.length).toBe(asked); // A move takes the picture along: it is drawn where the widget is now, not where the // engine drew it, and nothing is fetched. await form.updateWidget(check!.ref, { rect: { x: 300, y: 400, width: 14, height: 14 } }); const moved = () => (images()[1] as HTMLElement).style; await vi.waitFor(async () => { await fixture.whenStable(); expect(moved().top).toBe('400px'); }); expect(moved().left).toBe('300px'); expect(pictures()[1]).toBe(`blob:${checkKey}:Yes`); expect(fetches.mock.calls.length).toBe(asked); // A fill shows at once: the painter draws the new value while the page's newer pictures // load (here they never do). The check box keeps its picture: it didn't change. fetches.mockReturnValue(new Promise(() => {}) as never); await form.setValue(toFieldRef('name'), { value: 'Ada' }); const painted = () => [...element(fixture).querySelectorAll('epdf-field-pictures svg text')] .map((text) => text.textContent) .join(' '); await vi.waitFor(async () => { await fixture.whenStable(); expect(painted()).toBe('Ada'); }); expect(pictures()).toEqual([`blob:${checkKey}:Yes`]); }, ); }); describe(' choices', () => { it( 'fills in a dropdown and a list, each showing the field’s selection', { timeout: 45_000 }, async () => { const { fixture, form } = await openForm('hello_world.pdf', 'blank'); const page = kernelOf(fixture).documents.getPage(0, 'blank')!.ref; const options = ['NL', 'BE', 'DE'].map((value) => ({ label: value, value })); await form.create({ kind: 'combobox', name: 'country', options, widgets: [{ page, rect: { x: 72, y: 100, width: 160, height: 20 } }], }); await form.create({ kind: 'listbox', name: 'languages', options, widgets: [{ page, rect: { x: 72, y: 140, width: 160, height: 60 } }], }); await form.setValue(toFieldRef('country'), { value: 'BE' }); await showPage(fixture, 'blank', page); const [dropdown, list] = await vi.waitFor(() => { const found = element(fixture).querySelectorAll('select'); expect(found).toHaveLength(2); return [...found]; }); // The dropdown is see-through over the field's picture, and shows the field's choice. expect(dropdown!.value).toBe('BE'); expect(dropdown!.style.opacity).toBe('0'); // The list is visible, and draws its own edge: its box has none. expect(list!.style.opacity).toBe(''); expect(list!.parentElement!.style.boxShadow).toBe(''); dropdown!.value = 'DE'; dropdown!.dispatchEvent(new Event('change')); await vi.waitFor(() => expect(form.getValue(toFieldRef('country'))).toEqual({ value: 'DE' })); // The dropdown is made again for the new selection, and shows it. await vi.waitFor(async () => { await fixture.whenStable(); expect(element(fixture).querySelector('select')!.value).toBe('DE'); }); list!.value = 'NL'; list!.dispatchEvent(new Event('change')); await vi.waitFor(() => expect(form.getValue(toFieldRef('languages'))).toEqual({ selectedValues: ['NL'] }), ); await fixture.whenStable(); // The same list, never made again: its scroll position is the user's. expect(element(fixture).querySelectorAll('select')[1]).toBe(list); expect(list!.value).toBe('NL'); }, ); }); describe(' signature fields', () => { it( 'makes an empty one "sign here": a click makes it the target', { timeout: 45_000 }, async () => { const { fixture, form } = await openForm('hello_world.pdf', 'blank', [ withInteraction(), withForm(), withSignature(), ]); const page = kernelOf(fixture).documents.getPage(0, 'blank')!.ref; await form.create({ kind: 'signature', name: 'approval', widgets: [{ page, rect: { x: 72, y: 100, width: 160, height: 48 } }], }); await showPage(fixture, 'blank', page); const signature = fixture.debugElement.injector.get(EpdfSignature); const button = await vi.waitFor(() => { const found = element(fixture).querySelector( 'button[aria-label="approval"]', ); expect(found).not.toBeNull(); return found!; }); expect(button.hasAttribute('data-signed')).toBe(false); expect(button.parentElement!.style.cursor).toBe('pointer'); // A click makes the field the target the next mark goes to. button.click(); expect(signature.target()).toEqual(form.get(toFieldRef('approval'))!.ref); }, ); }); /** * The regression net for the "fake button": a read-only text field with a widget action, which * Acrobat runs on a click. Through the real DOM: a click on its box, and the actions plugin's * own event stream as proof that its Hide action ran. */ describe('widget activation through the DOM (the fake-button pattern)', () => { it( 'clicking a read-only text widget with an action runs the action', { timeout: 45_000 }, async () => { const { fixture, form } = await openForm('action_buttons_form.pdf', 'buttons', [ withInteraction(), // Scripting off: Hide is native. { plugins: [actionsPlugin({ openSequence: 'off' }), annotationPlugin()] }, withForm(), ]); const fake = form.getSnapshot()?.fields.find((field) => field.name === 'fakeButton'); expect(fake?.readOnly).toBe(true); const dispatched: ActionExecutedEvent[] = []; kernelOf(fixture) .capability(ActionsToken) .onExecuted((event) => dispatched.push(event)); await showPage(fixture, 'buttons', fake!.widgets[0]!.page!); // The fake button is a text control with a disabled editor; its box runs the action. const input = await vi.waitFor(() => { const found = element(fixture).querySelector('[aria-label="fakeButton"]'); expect(found).not.toBeNull(); return found!; }); expect(input.disabled).toBe(true); input.parentElement!.click(); await vi.waitFor(() => { const hide = dispatched.find((event) => event.tree.root?.type === 'hide'); expect(hide).toBeTruthy(); expect(hide!.result.nodes).toEqual([ expect.objectContaining({ type: 'hide', status: 'executed' }), ]); expect(hide!.source).toMatchObject({ kind: 'widget' }); }); }, ); }); /** A component of the app's own: one field's value, and an input bound to another field. */ @Component({ selector: 'test-billing', imports: [ReactiveFormsModule], template: ``, }) class Billing { private readonly form = inject(EpdfForm); readonly total = this.form.valueOf(toFieldRef('total')); readonly name = this.form.controlOf(toFieldRef('name')); } describe('EpdfForm', () => { it('has no fields, and no value, without a document', async () => { const fixture = await mount( viewerHost({ template: '', features: [withInteraction(), withForm()] }), ); const form = fixture.debugElement.injector.get(EpdfForm); expect(form.fields()).toEqual([]); expect(form.status()).toBe('idle'); expect(form.valueOf(toFieldRef('total'))()).toBeNull(); // An async method rejects without a document, so `.catch()` sees the refusal. await expect(form.setValue(toFieldRef('total'), { value: '1' })).rejects.toMatchObject({ code: 'not-ready', }); }); it( 'follows one field with valueOf(), and fills one in with controlOf()', { timeout: 45_000 }, async () => { const bytes = new Uint8Array(await readFile(resolve(fixtures, 'hello_world.pdf'))); const fixture = await mount( viewerHost({ template: '', imports: [Billing], config: { engine: realEngine, initialDocuments: [{ source: { kind: 'bytes', id: 'blank', bytes } }], }, features: [withInteraction(), withForm()], }), ); await vi.waitFor(() => expect(kernelOf(fixture).tryCapability(FormToken)).toBeTruthy(), { timeout: 20_000, }); const viewer = fixture.debugElement.injector.get(EpdfKernelHost); const form = kernelOf(fixture).capability(FormToken); await form.refresh(); const billing = fixture.debugElement.query( (node) => node.componentInstance instanceof Billing, ).componentInstance as Billing; const input = element(fixture).querySelector('input.name')!; // No such field yet: nothing to fill in. await fixture.whenStable(); expect(billing.name.disabled).toBe(true); expect(billing.total()).toBeNull(); const page = viewer.kernel()!.documents.getPage(0, 'blank')!.ref; const at = (y: number) => ({ page, rect: { x: 72, y, width: 160, height: 20 } }); await form.create({ kind: 'text', name: 'name', widgets: [at(100)] }); await form.create({ kind: 'text', name: 'total', widgets: [at(140)] }); await form.setValue(toFieldRef('total'), { value: '120.00' }); await form.setValue(toFieldRef('name'), { value: 'Ada' }); await fixture.whenStable(); expect(billing.total()).toEqual({ value: '120.00' }); // The control holds the field's value, in the input too, and can fill it in now. expect(billing.name.value).toBe('Ada'); expect(billing.name.enabled).toBe(true); expect(input.value).toBe('Ada'); // Typing in the input fills in the field. input.value = 'Grace'; input.dispatchEvent(new Event('input')); await vi.waitFor(() => expect(form.getValue(toFieldRef('name'))).toEqual({ value: 'Grace' })); // A change of the field, whoever made it, reaches the control and the input. await form.setValue(toFieldRef('name'), { value: 'Ada Lovelace' }); await fixture.whenStable(); expect(billing.name.value).toBe('Ada Lovelace'); expect(input.value).toBe('Ada Lovelace'); // A read-only field can't be filled in: the control is disabled. await form.update(toFieldRef('name'), { readOnly: true }); await fixture.whenStable(); expect(billing.name.disabled).toBe(true); expect(input.disabled).toBe(true); }, ); });