[@types/html-to-pdfmake] window requires jsdom's DOMWindow, pins @types/pdfmake to 0.2, and types showHidden as showhidden #75834

Package: @types/html-to-pdfmake 2.4.5 (types/html-to-pdfmake on master @ 8442c3d, unchanged since 5734314). Library: html-to-pdfmake 2.5.36 (@ af6153b).

Four mismatches between the declarations and what the library does. All four show up with one call site, see the script below.

1. window must be a jsdom DOMWindow

The option is typed as import("jsdom").DOMWindow (index.d.ts L11). The library only stores the window (index.js L45) and constructs its DOMParser (L125); nothing else is read from it. Any other DOM implementation on the server (happy-dom, linkedom, ...) works at runtime but is rejected by the type, and every consumer gets @types/jsdom installed through the dependencies of this package.

2. @types/pdfmake is pinned to ^0.2.0

package.json L10 was changed from * to ^0.2.0 in #74337, when @types/pdfmake moved to 0.3. A project on pdfmake 0.3 with @types/pdfmake 0.3 therefore gets a second, nested @types/pdfmake 0.2.13, and the Content returned by htmlToPdfmake() is not assignable to the project's own Content. The package's own test file compiles unchanged against @types/pdfmake 0.3.3 (checked with its tsconfig plus esModuleInterop, TypeScript 5.9.3), so the pin looks unnecessary.

3. showhidden instead of showHidden

The declaration has showhidden (L24). The library reads options.showHidden (index.js L50), and has done so since the option was added in 2.4.10. So the typed spelling is silently ignored and the working spelling is a type error.

4. imagesByReference: true returns { content, images }

The return type is always Content (L48), but with imagesByReference the library returns { content, images } (index.js L1271-L1277). This one is already reported in discussion #66867; listed here because the fix below covers it too.

Also missing from the options, going by the library's JSDoc and source (not checked beyond reading): collapseMargins, removeTagClasses (L49-L51) and customTag (L696-L698).

Reproduction

package.json dependencies: html-to-pdfmake@2.5.36, @types/html-to-pdfmake@2.4.5, pdfmake@0.3.12, @types/pdfmake@0.3.3, happy-dom@21.0.4, typescript@5.9.3. tsconfig: strict, module/moduleResolution: nodenext, types: [].

import htmlToPdfmake = require("html-to-pdfmake");
import type { Content } from "pdfmake/interfaces";
import { Window } from "happy-dom";

const window = new Window();

// 1. Any window with a DOMParser works at runtime; the type asks for jsdom's DOMWindow.
const a = htmlToPdfmake("<p>Hello</p>", { window });

// 2. The result is typed against @types/pdfmake 0.2 and does not fit 0.3's Content.
const b: Content = htmlToPdfmake("<p>Hello</p>");

// 3. The option the library reads is `showHidden`; the type only knows `showhidden`.
htmlToPdfmake("<p>Hello</p>", { showHidden: true });

// 4. With imagesByReference the library returns { content, images }.
const { content, images } = htmlToPdfmake("<p>Hello</p>", { imagesByReference: true });

tsc -p .:

repro.ts(8,43): error TS2740: Type 'Window' is missing the following properties from type 'DOMWindow': Atomics, BigInt, BigInt64Array, BigUint64Array, and 64 more.
repro.ts(11,7): error TS2322: Type 'import("node_modules/@types/html-to-pdfmake/node_modules/@types/pdfmake/interfaces").Content' is not assignable to type 'import("node_modules/@types/pdfmake/interfaces").Content'.
  Type 'Content[]' is not assignable to type 'Content'.
repro.ts(14,33): error TS2561: Object literal may only specify known properties, but 'showHidden' does not exist in type 'Partial<{ window: DOMWindow; defaultStyles: StyleDictionary; removeExtraBlanks: boolean; showhidden: boolean; ignoreStyles: string[]; imagesByReference: boolean; fontSizes: [...]; replaceText: (text: string, nodes: HTMLElement[]) => string; tableAutoSize: boolean; }>'. Did you mean to write 'showhidden'?
repro.ts(17,9): error TS2339: Property 'content' does not exist on type 'Content'.
repro.ts(17,18): error TS2339: Property 'images' does not exist on type 'Content'.

The same calls at runtime (bun 1.4.4, happy-dom window):

happy-dom window:         ["a"]
showhidden: true (typed): ["shown"]
showHidden: true (read):  ["shown","hidden"]
imagesByReference: true: keys [ "content", "images" ] images ["https://example.com/a.png"]

(input for the showHidden lines: <p>shown</p><p style="display:none">hidden</p>)

Suggested fix

• window?: { DOMParser: new() => { parseFromString(string: string, type: "text/html"): unknown } }, and drop @types/jsdom from dependencies. jsdom's DOMWindow still fits this type.
• "@types/pdfmake": "^0.3.0" (or back to *).
• Rename showhidden to showHidden; add collapseMargins, removeTagClasses, customTag.
• An overload for imagesByReference: true returning { content: Content; images: Record<string, string | ImageDefinition> }.

With those changes applied to a local copy of index.d.ts, the script above compiles without errors, and so does a jsdom window (new JSDOM("").window). The package's test file then needs two updates, because it encodes points 3 and 4: it passes showhidden: true and assigns an imagesByReference: true result to Content.

I can open a PR with this if that is the preferred route.

Environment

• @types/html-to-pdfmake 2.4.5, html-to-pdfmake 2.5.36, @types/pdfmake 0.3.3, pdfmake 0.3.12, happy-dom 21.0.4
• TypeScript 5.9.3, bun 1.4.4 on Linux