@openworkbook/pdf 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,304 @@
1
+ import { Range, PageSetupPatch, PageBreaks, LinkPolicy, Workbook, WorkbookData, Worksheet, PageSetup } from '@openworkbook/core';
2
+
3
+ /**
4
+ * Fonts of one PDF: which face draws which character, how wide every piece of text is, and the PDF font objects
5
+ * written at the end (standard Type 1 fonts with WinAnsi encoding, or embedded Type0 / CID fonts with subsetting
6
+ * and a ToUnicode CMap). Measurement and drawing use the same metrics, so wrapping and "####" decisions made while
7
+ * painting match what the PDF shows.
8
+ */
9
+
10
+ type FontBytes = Uint8Array | ArrayBuffer;
11
+ /** The faces of one font family. Missing bold / italic faces are synthesised (stroked / slanted) from `normal`. */
12
+ interface FontFaces {
13
+ normal?: FontBytes;
14
+ bold?: FontBytes;
15
+ italic?: FontBytes;
16
+ boldItalic?: FontBytes;
17
+ /** Member of a .ttc collection to use (default 0), for every face of the family. */
18
+ index?: number;
19
+ }
20
+ /** A font family: its faces, or the bytes of a single (regular) face. */
21
+ type FontSource = FontBytes | FontFaces;
22
+ /**
23
+ * Register a font family for every later PDF export (in addition to the `fonts` option of `exportPdf`). Cells whose
24
+ * font family matches (case-insensitively) are drawn with it, embedded and subset. Pass null to remove it.
25
+ */
26
+ declare function registerPdfFont(family: string, source: FontSource | null): void;
27
+ /** Families registered with `registerPdfFont`. */
28
+ declare function registeredPdfFonts(): string[];
29
+ type StdFamily = 'Helvetica' | 'Times' | 'Courier';
30
+ /** The standard family a font family is drawn with when no font file was supplied. */
31
+ declare function standardFamilyFor(family: string): StdFamily;
32
+
33
+ /** Source of random bytes; the default is `globalThis.crypto.getRandomValues` (Node.js 18: `node:crypto`'s webcrypto). */
34
+ type RandomBytes = (length: number) => Uint8Array;
35
+ /**
36
+ * What a user who opened the file with the user password may do (the owner password always gives every right).
37
+ * Every flag defaults to allowed. Viewers are trusted to honour these flags: they are advisory, not enforced by the
38
+ * encryption.
39
+ */
40
+ interface PdfPermissions {
41
+ /** 'none', 'low' (degraded, e.g. a low-resolution bitmap) or 'high' (default; faithful printing). `true` = 'high', `false` = 'none'. */
42
+ printing?: 'none' | 'low' | 'high' | boolean;
43
+ /** Change the document other than by annotating, filling forms or assembling (P bit 4). */
44
+ modifying?: boolean;
45
+ /** Copy or otherwise extract text and graphics (P bit 5). */
46
+ copying?: boolean;
47
+ /** Add or modify annotations and, with `fillingForms`, fill form fields (P bit 6). */
48
+ annotating?: boolean;
49
+ /** Fill in form fields even when `annotating` is false (P bit 9). */
50
+ fillingForms?: boolean;
51
+ /** Extract text and graphics for accessibility (P bit 10). PDF 2.0 deprecates this restriction: readers ignore the bit. */
52
+ contentAccessibility?: boolean;
53
+ /** Insert, rotate or delete pages, create bookmarks and thumbnails (P bit 11). */
54
+ documentAssembly?: boolean;
55
+ /** @deprecated Use `printing`. */
56
+ print?: boolean;
57
+ /** @deprecated Use `printing: 'low'` (with `print`). */
58
+ printHighQuality?: boolean;
59
+ /** @deprecated Use `modifying`. */
60
+ modify?: boolean;
61
+ /** @deprecated Use `copying`. */
62
+ copy?: boolean;
63
+ /** @deprecated Use `annotating`. */
64
+ annotate?: boolean;
65
+ /** @deprecated Use `fillingForms`. */
66
+ fillForms?: boolean;
67
+ /** @deprecated Use `contentAccessibility`. */
68
+ extract?: boolean;
69
+ /** @deprecated Use `documentAssembly`. */
70
+ assemble?: boolean;
71
+ }
72
+
73
+ /** Anything `exportPdf` accepts as a workbook: a `Workbook`, a `Sheets` SDK object, or workbook JSON. */
74
+ type PdfSource = Workbook | {
75
+ workbook: Workbook;
76
+ } | WorkbookData;
77
+ interface PdfWarning {
78
+ /** Stable identifier of the kind of problem (`font-substituted`, `missing-glyphs`, `image-unsupported`, ...). */
79
+ code: string;
80
+ message: string;
81
+ /** Sheet the warning is about, when it is about one. */
82
+ sheet?: string;
83
+ }
84
+ interface PdfExportOptions {
85
+ /** Which sheets: names or indexes, 'active' (default) or 'all' (every visible sheet). */
86
+ sheets?: Array<string | number> | 'active' | 'all';
87
+ /** Print only this range (A1 text such as "A1:F40", or a Range) of each exported sheet, instead of its print area. */
88
+ range?: Range | string;
89
+ /** Page setup changes for this export: one patch for every sheet, or patches by sheet name. Applied over each sheet's own page setup. */
90
+ pageSetup?: PageSetupPatch | Record<string, PageSetupPatch>;
91
+ /** Manual page breaks to use instead of the sheets' own (`sheet.pageBreaks`): one set for every sheet, or sets by sheet name. */
92
+ pageBreaks?: PageBreaks | Record<string, PageBreaks>;
93
+ /** Font files by family name (`{ Calibri: { normal, bold, italic, boldItalic } }` or the bytes of one face). Embedded and subset. */
94
+ fonts?: Record<string, FontSource>;
95
+ /** A family of `fonts` used for text whose own font was not supplied (instead of a standard PDF font). */
96
+ defaultFont?: string;
97
+ /** Families of `fonts` tried in order for characters the text's own font cannot draw (Arabic, CJK, symbols ...). */
98
+ fallbackFonts?: string[];
99
+ /** Document properties. Title, author, subject and keywords default to the workbook's `documentProperties.core` (title, creator, subject, keywords). */
100
+ title?: string;
101
+ author?: string;
102
+ subject?: string;
103
+ keywords?: string | string[];
104
+ creator?: string;
105
+ /** One bookmark per sheet (default true when more than one sheet is exported). */
106
+ bookmarks?: boolean;
107
+ /** Draw floating objects (charts, pictures, shapes, ...) and sparklines. Default true (a sheet's draft quality still leaves them out). */
108
+ includeObjects?: boolean;
109
+ /** Comments and notes: 'none' (default), 'asDisplayed' (notes shown on the sheet are drawn as callouts) or 'atEnd' (listed after each sheet). */
110
+ includeComments?: 'none' | 'asDisplayed' | 'atEnd';
111
+ /** Rows without an explicit height grow to fit wrapped text and large fonts, measured with the PDF fonts (as the grid does). Default true. */
112
+ autoFitRows?: boolean;
113
+ /** What `&F` prints (default: the title, else "Book1"); `&Z` prints `filePath`. */
114
+ fileName?: string;
115
+ filePath?: string;
116
+ /** The moment `&D` / `&T` print (default: now). */
117
+ date?: Date;
118
+ /** Picture bytes for sources that are not data: URLs (http(s) URLs, blob: URLs). `exportPdfAsync` fills this by downloading them. */
119
+ images?: Record<string, Uint8Array>;
120
+ /**
121
+ * Encrypt the file with AES-256 (PDF 2.0 security handler, revision 6): the password needed to open it. `''` (with
122
+ * `ownerPassword` or `permissions`) encrypts a file that opens without a password but with restricted rights.
123
+ */
124
+ password?: string;
125
+ /** Password with full rights. Default: a random one nobody knows (so `permissions` cannot be lifted). */
126
+ ownerPassword?: string;
127
+ /** What a user who opened the file with `password` may do (default: everything). Advisory: viewers enforce it. */
128
+ permissions?: PdfPermissions;
129
+ /** The encryption algorithm; only 'aes256' (the default) is accepted. */
130
+ encryption?: 'aes256';
131
+ /** Source of random bytes (IVs, salts, file key, document ID). Default `globalThis.crypto.getRandomValues`; set it for reproducible files in tests. */
132
+ randomBytes?: RandomBytes;
133
+ /** Compress content streams (default true). */
134
+ compress?: boolean;
135
+ /** Called once with every warning (also returned by `exportPdfDetailed`). */
136
+ onWarnings?: (warnings: PdfWarning[]) => void;
137
+ /**
138
+ * Which cell and object links become clickable `/URI` link annotations (see core's `checkLinkUrl`). Default: http,
139
+ * https, mailto and tel; in-workbook references (`#Sheet2!A1`, `#Name`) become jumps inside the PDF. A refused link
140
+ * (`javascript:`, `data:`, `file:`, `//host`, an unlisted scheme...) is printed as text without an annotation.
141
+ */
142
+ linkPolicy?: LinkPolicy;
143
+ /** Shorthand for `linkPolicy.allowedSchemes` (wins over it). */
144
+ allowedLinkSchemes?: string[];
145
+ /**
146
+ * [tagged pdf] Write a tagged (accessible) PDF: a structure tree with one Sect per sheet, one Table per print area
147
+ * (one TR per sheet row, TH / TD cells, continued across pages; repeated print titles are artifacts), Figures with
148
+ * the alternative text of the floating objects (a chart's title as its Caption), Links, artifacts for gridlines,
149
+ * borders, fills, headings, headers and footers. Default true. The file also claims PDF/UA-1 when every font is
150
+ * embedded.
151
+ */
152
+ tagged?: boolean;
153
+ /**
154
+ * [tagged pdf] Give every chart an accessible data table: a Table (series names and categories as TH, values as
155
+ * TD) after the chart's Figure in the structure tree, written as invisible text over the chart (it is extracted by
156
+ * copy / paste and text tools). Default false. Ignored when `tagged` is false.
157
+ */
158
+ chartDataTables?: boolean;
159
+ /** [tagged pdf] Natural language of the document (`/Lang`, BCP 47 such as 'fr-FR'). Default: the workbook's language property, else its culture, else 'en-US'. */
160
+ lang?: string;
161
+ }
162
+ /** One page of the PDF. */
163
+ interface PdfPageInfo {
164
+ sheet: string;
165
+ /** What `&P` printed on it. */
166
+ pageNumber: number;
167
+ /** The cells on the page (absent on comment pages). */
168
+ area?: Range;
169
+ titleRows?: [number, number];
170
+ titleCols?: [number, number];
171
+ scale: number;
172
+ /** Paper size in points. */
173
+ width: number;
174
+ height: number;
175
+ /** 'cells' or 'comments' (the list printed with `includeComments: 'atEnd'`). */
176
+ kind: 'cells' | 'comments';
177
+ /** Link annotations on the page. */
178
+ links: number;
179
+ }
180
+ interface PdfExportResult {
181
+ bytes: Uint8Array;
182
+ pages: PdfPageInfo[];
183
+ warnings: PdfWarning[];
184
+ /** [tagged pdf] Whether the file is tagged, and whether it claims PDF/UA-1 (tagged, every font embedded, no missing glyph). */
185
+ tagged: boolean;
186
+ pdfUA: boolean;
187
+ }
188
+ /** The page setup a sheet is exported with. */
189
+ declare function pdfPageSetup(sheet: Worksheet, options?: Pick<PdfExportOptions, 'pageSetup' | 'range'>): PageSetup;
190
+ /** The manual page breaks a sheet is exported with: `options.pageBreaks` (one set, or the set of the sheet's name), else the sheet's own. */
191
+ declare function pdfPageBreaks(sheet: Worksheet, options?: Pick<PdfExportOptions, 'pageBreaks'>): PageBreaks;
192
+ /** Export synchronously. Pictures that are not data: URLs must be supplied in `options.images` (or use `exportPdfAsync`). */
193
+ declare function exportPdf(source: PdfSource, options?: PdfExportOptions): Uint8Array;
194
+ /** Like `exportPdf`, also returning the pages and the warnings (what could not be rendered exactly). */
195
+ declare function exportPdfDetailed(source: PdfSource, options?: PdfExportOptions): PdfExportResult;
196
+
197
+ /**
198
+ * Convenience helpers for PDF files in browsers, Node.js and Next.js route handlers (mirroring `@openworkbook/xlsx`):
199
+ *
200
+ * ```ts
201
+ * return pdfResponse(book, 'report.pdf'); // Next.js route handler / any Web-standard server
202
+ * downloadPdf(book, 'report.pdf', { sheets: 'all' }); // browser
203
+ * await writePdf('out/report.pdf', book); // Node.js
204
+ * const bytes = await exportPdfAsync(book, { fonts: { Calibri: '/fonts/calibri.ttf' } }); // fonts / pictures by URL
205
+ * ```
206
+ */
207
+
208
+ declare const PDF_MIME = "application/pdf";
209
+ /** The PDF as a Blob (browsers, and Node 18+). */
210
+ declare function pdfBlob(source: PdfSource | Uint8Array, options?: PdfExportOptions): Blob;
211
+ /**
212
+ * A fetch `Response` with the PDF — return it from a Next.js route handler or any Web-standard server. `source` is
213
+ * a workbook (exported with `options`) or PDF bytes. Downloads as an attachment unless `init.headers` sets its own
214
+ * Content-Disposition (e.g. `inline` to show it in the browser's viewer).
215
+ */
216
+ declare function pdfResponse(source: PdfSource | Uint8Array, filename?: string, init?: ResponseInit, options?: PdfExportOptions): Response;
217
+ /** Trigger a download in the browser. */
218
+ declare function downloadPdf(source: PdfSource | Uint8Array, filename?: string, options?: PdfExportOptions): void;
219
+ /** Node.js: export and write the PDF to a file. Resolves with the export result (pages, warnings). */
220
+ declare function writePdf(path: string, source: PdfSource, options?: PdfExportOptions | AsyncPdfExportOptions): Promise<PdfExportResult>;
221
+ /** A font face given by URL / file path (loaded by the async export). */
222
+ type FontLocation = string | URL;
223
+ /** `fonts` of the async export: bytes, URLs or (Node.js) file paths. */
224
+ type AsyncFontSource = FontSource | FontLocation | {
225
+ normal?: FontBytes | FontLocation;
226
+ bold?: FontBytes | FontLocation;
227
+ italic?: FontBytes | FontLocation;
228
+ boldItalic?: FontBytes | FontLocation;
229
+ index?: number;
230
+ };
231
+ type AsyncPdfExportOptions = Omit<PdfExportOptions, 'fonts'> & {
232
+ fonts?: Record<string, AsyncFontSource>;
233
+ };
234
+ /**
235
+ * Asynchronous export: fonts may be given as URLs / file paths, pictures at http(s) / blob: URLs are downloaded,
236
+ * and in a browser GIF / WebP / BMP pictures are converted to PNG through a canvas. Otherwise as `exportPdf`.
237
+ */
238
+ declare function exportPdfDetailedAsync(source: PdfSource, options?: AsyncPdfExportOptions): Promise<PdfExportResult>;
239
+ /** `exportPdfDetailedAsync(...).bytes`. */
240
+ declare function exportPdfAsync(source: PdfSource, options?: AsyncPdfExportOptions): Promise<Uint8Array>;
241
+
242
+ /**
243
+ * `layoutPdf`: the pages a PDF export would have, each with a `draw(ctx)` that paints it on a browser canvas through
244
+ * the same page painter that writes the file (see screen.ts). For previews: the page count and every page come
245
+ * from the code path of `exportPdf`, so the preview shows what the file will contain.
246
+ *
247
+ * ```ts
248
+ * const { pages } = layoutPdf(book, { sheets: 'all' });
249
+ * pages[0].draw(canvas.getContext('2d')!, { scale: devicePixelRatio });
250
+ * ```
251
+ */
252
+
253
+ /** Options of `layoutPdf`: those of `exportPdf` (the file options such as `password` or `compress` are ignored). */
254
+ type PdfLayoutOptions = PdfExportOptions;
255
+ interface PdfDrawOptions {
256
+ /** Device pixels per page px (CSS pixel at 96 dpi), e.g. `zoom * devicePixelRatio`. Default 1. */
257
+ scale?: number;
258
+ /** Fill the paper white first (default true). */
259
+ background?: boolean;
260
+ /** A JPEG picture finished decoding after the page was drawn: draw it again to show it. */
261
+ onImageReady?: () => void;
262
+ }
263
+ /** One page of the PDF, ready to be drawn. */
264
+ interface PdfLayoutPage {
265
+ /** Zero-based position in the document. */
266
+ index: number;
267
+ sheet: string;
268
+ /** What `&P` prints on it (0 on comment pages). */
269
+ pageNumber: number;
270
+ /** 'cells' or 'comments' (the list printed with `includeComments: 'atEnd'`). */
271
+ kind: 'cells' | 'comments';
272
+ /** The cells on the page (absent on comment pages). */
273
+ area?: Range;
274
+ titleRows?: [number, number];
275
+ titleCols?: [number, number];
276
+ scale: number;
277
+ /** Paper size in points (as in the PDF). */
278
+ width: number;
279
+ height: number;
280
+ /** Paper size in CSS pixels (96 dpi): the user space of `draw`. */
281
+ widthPx: number;
282
+ heightPx: number;
283
+ /** Paint the page on a 2D canvas context, from its current transform, `scale` device pixels per page px. */
284
+ draw(ctx: CanvasRenderingContext2D, options?: PdfDrawOptions): void;
285
+ }
286
+ interface PdfLayout {
287
+ pages: PdfLayoutPage[];
288
+ pageCount: number;
289
+ /** Planning warnings (fonts substituted, pictures that cannot be embedded, ...); drawing a page may find more. */
290
+ warnings: PdfWarning[];
291
+ }
292
+ /**
293
+ * Lay out a PDF export without writing it: the pages `exportPdf(source, options)` would produce, in order, with the
294
+ * same pagination (print areas, page breaks, scaling, titles, automatic row heights measured with the PDF fonts,
295
+ * comment pages) and a `draw(ctx)` per page that paints it on a canvas with the same painters. Pages are drawn on
296
+ * demand, so laying out a long export is cheap and a preview can draw only the visible pages.
297
+ */
298
+ declare function layoutPdf(source: PdfSource, options?: PdfLayoutOptions): PdfLayout;
299
+ /** `layoutPdf` with the asynchronous export's options: fonts by URL / file path, pictures at http(s) / blob: URLs downloaded. */
300
+ declare function layoutPdfAsync(source: PdfSource, options?: AsyncPdfExportOptions): Promise<PdfLayout>;
301
+ /** Draw page `pageIndex` of the PDF export of `source` on a canvas (lays the whole export out first: keep `layoutPdf`'s result to draw several pages). */
302
+ declare function renderPdfPage(ctx: CanvasRenderingContext2D, source: PdfSource, pageIndex: number, options?: PdfLayoutOptions & PdfDrawOptions): PdfLayoutPage | undefined;
303
+
304
+ export { type AsyncFontSource, type AsyncPdfExportOptions, type FontBytes, type FontFaces, type FontLocation, type FontSource, PDF_MIME, type PdfDrawOptions, type PdfExportOptions, type PdfExportResult, type PdfLayout, type PdfLayoutOptions, type PdfLayoutPage, type PdfPageInfo, type PdfPermissions, type PdfSource, type PdfWarning, type RandomBytes, type StdFamily, downloadPdf, exportPdf, exportPdfAsync, exportPdfDetailed, exportPdfDetailedAsync, layoutPdf, layoutPdfAsync, pdfBlob, pdfPageBreaks, pdfPageSetup, pdfResponse, registerPdfFont, registeredPdfFonts, renderPdfPage, standardFamilyFor, writePdf };
@@ -0,0 +1,304 @@
1
+ import { Range, PageSetupPatch, PageBreaks, LinkPolicy, Workbook, WorkbookData, Worksheet, PageSetup } from '@openworkbook/core';
2
+
3
+ /**
4
+ * Fonts of one PDF: which face draws which character, how wide every piece of text is, and the PDF font objects
5
+ * written at the end (standard Type 1 fonts with WinAnsi encoding, or embedded Type0 / CID fonts with subsetting
6
+ * and a ToUnicode CMap). Measurement and drawing use the same metrics, so wrapping and "####" decisions made while
7
+ * painting match what the PDF shows.
8
+ */
9
+
10
+ type FontBytes = Uint8Array | ArrayBuffer;
11
+ /** The faces of one font family. Missing bold / italic faces are synthesised (stroked / slanted) from `normal`. */
12
+ interface FontFaces {
13
+ normal?: FontBytes;
14
+ bold?: FontBytes;
15
+ italic?: FontBytes;
16
+ boldItalic?: FontBytes;
17
+ /** Member of a .ttc collection to use (default 0), for every face of the family. */
18
+ index?: number;
19
+ }
20
+ /** A font family: its faces, or the bytes of a single (regular) face. */
21
+ type FontSource = FontBytes | FontFaces;
22
+ /**
23
+ * Register a font family for every later PDF export (in addition to the `fonts` option of `exportPdf`). Cells whose
24
+ * font family matches (case-insensitively) are drawn with it, embedded and subset. Pass null to remove it.
25
+ */
26
+ declare function registerPdfFont(family: string, source: FontSource | null): void;
27
+ /** Families registered with `registerPdfFont`. */
28
+ declare function registeredPdfFonts(): string[];
29
+ type StdFamily = 'Helvetica' | 'Times' | 'Courier';
30
+ /** The standard family a font family is drawn with when no font file was supplied. */
31
+ declare function standardFamilyFor(family: string): StdFamily;
32
+
33
+ /** Source of random bytes; the default is `globalThis.crypto.getRandomValues` (Node.js 18: `node:crypto`'s webcrypto). */
34
+ type RandomBytes = (length: number) => Uint8Array;
35
+ /**
36
+ * What a user who opened the file with the user password may do (the owner password always gives every right).
37
+ * Every flag defaults to allowed. Viewers are trusted to honour these flags: they are advisory, not enforced by the
38
+ * encryption.
39
+ */
40
+ interface PdfPermissions {
41
+ /** 'none', 'low' (degraded, e.g. a low-resolution bitmap) or 'high' (default; faithful printing). `true` = 'high', `false` = 'none'. */
42
+ printing?: 'none' | 'low' | 'high' | boolean;
43
+ /** Change the document other than by annotating, filling forms or assembling (P bit 4). */
44
+ modifying?: boolean;
45
+ /** Copy or otherwise extract text and graphics (P bit 5). */
46
+ copying?: boolean;
47
+ /** Add or modify annotations and, with `fillingForms`, fill form fields (P bit 6). */
48
+ annotating?: boolean;
49
+ /** Fill in form fields even when `annotating` is false (P bit 9). */
50
+ fillingForms?: boolean;
51
+ /** Extract text and graphics for accessibility (P bit 10). PDF 2.0 deprecates this restriction: readers ignore the bit. */
52
+ contentAccessibility?: boolean;
53
+ /** Insert, rotate or delete pages, create bookmarks and thumbnails (P bit 11). */
54
+ documentAssembly?: boolean;
55
+ /** @deprecated Use `printing`. */
56
+ print?: boolean;
57
+ /** @deprecated Use `printing: 'low'` (with `print`). */
58
+ printHighQuality?: boolean;
59
+ /** @deprecated Use `modifying`. */
60
+ modify?: boolean;
61
+ /** @deprecated Use `copying`. */
62
+ copy?: boolean;
63
+ /** @deprecated Use `annotating`. */
64
+ annotate?: boolean;
65
+ /** @deprecated Use `fillingForms`. */
66
+ fillForms?: boolean;
67
+ /** @deprecated Use `contentAccessibility`. */
68
+ extract?: boolean;
69
+ /** @deprecated Use `documentAssembly`. */
70
+ assemble?: boolean;
71
+ }
72
+
73
+ /** Anything `exportPdf` accepts as a workbook: a `Workbook`, a `Sheets` SDK object, or workbook JSON. */
74
+ type PdfSource = Workbook | {
75
+ workbook: Workbook;
76
+ } | WorkbookData;
77
+ interface PdfWarning {
78
+ /** Stable identifier of the kind of problem (`font-substituted`, `missing-glyphs`, `image-unsupported`, ...). */
79
+ code: string;
80
+ message: string;
81
+ /** Sheet the warning is about, when it is about one. */
82
+ sheet?: string;
83
+ }
84
+ interface PdfExportOptions {
85
+ /** Which sheets: names or indexes, 'active' (default) or 'all' (every visible sheet). */
86
+ sheets?: Array<string | number> | 'active' | 'all';
87
+ /** Print only this range (A1 text such as "A1:F40", or a Range) of each exported sheet, instead of its print area. */
88
+ range?: Range | string;
89
+ /** Page setup changes for this export: one patch for every sheet, or patches by sheet name. Applied over each sheet's own page setup. */
90
+ pageSetup?: PageSetupPatch | Record<string, PageSetupPatch>;
91
+ /** Manual page breaks to use instead of the sheets' own (`sheet.pageBreaks`): one set for every sheet, or sets by sheet name. */
92
+ pageBreaks?: PageBreaks | Record<string, PageBreaks>;
93
+ /** Font files by family name (`{ Calibri: { normal, bold, italic, boldItalic } }` or the bytes of one face). Embedded and subset. */
94
+ fonts?: Record<string, FontSource>;
95
+ /** A family of `fonts` used for text whose own font was not supplied (instead of a standard PDF font). */
96
+ defaultFont?: string;
97
+ /** Families of `fonts` tried in order for characters the text's own font cannot draw (Arabic, CJK, symbols ...). */
98
+ fallbackFonts?: string[];
99
+ /** Document properties. Title, author, subject and keywords default to the workbook's `documentProperties.core` (title, creator, subject, keywords). */
100
+ title?: string;
101
+ author?: string;
102
+ subject?: string;
103
+ keywords?: string | string[];
104
+ creator?: string;
105
+ /** One bookmark per sheet (default true when more than one sheet is exported). */
106
+ bookmarks?: boolean;
107
+ /** Draw floating objects (charts, pictures, shapes, ...) and sparklines. Default true (a sheet's draft quality still leaves them out). */
108
+ includeObjects?: boolean;
109
+ /** Comments and notes: 'none' (default), 'asDisplayed' (notes shown on the sheet are drawn as callouts) or 'atEnd' (listed after each sheet). */
110
+ includeComments?: 'none' | 'asDisplayed' | 'atEnd';
111
+ /** Rows without an explicit height grow to fit wrapped text and large fonts, measured with the PDF fonts (as the grid does). Default true. */
112
+ autoFitRows?: boolean;
113
+ /** What `&F` prints (default: the title, else "Book1"); `&Z` prints `filePath`. */
114
+ fileName?: string;
115
+ filePath?: string;
116
+ /** The moment `&D` / `&T` print (default: now). */
117
+ date?: Date;
118
+ /** Picture bytes for sources that are not data: URLs (http(s) URLs, blob: URLs). `exportPdfAsync` fills this by downloading them. */
119
+ images?: Record<string, Uint8Array>;
120
+ /**
121
+ * Encrypt the file with AES-256 (PDF 2.0 security handler, revision 6): the password needed to open it. `''` (with
122
+ * `ownerPassword` or `permissions`) encrypts a file that opens without a password but with restricted rights.
123
+ */
124
+ password?: string;
125
+ /** Password with full rights. Default: a random one nobody knows (so `permissions` cannot be lifted). */
126
+ ownerPassword?: string;
127
+ /** What a user who opened the file with `password` may do (default: everything). Advisory: viewers enforce it. */
128
+ permissions?: PdfPermissions;
129
+ /** The encryption algorithm; only 'aes256' (the default) is accepted. */
130
+ encryption?: 'aes256';
131
+ /** Source of random bytes (IVs, salts, file key, document ID). Default `globalThis.crypto.getRandomValues`; set it for reproducible files in tests. */
132
+ randomBytes?: RandomBytes;
133
+ /** Compress content streams (default true). */
134
+ compress?: boolean;
135
+ /** Called once with every warning (also returned by `exportPdfDetailed`). */
136
+ onWarnings?: (warnings: PdfWarning[]) => void;
137
+ /**
138
+ * Which cell and object links become clickable `/URI` link annotations (see core's `checkLinkUrl`). Default: http,
139
+ * https, mailto and tel; in-workbook references (`#Sheet2!A1`, `#Name`) become jumps inside the PDF. A refused link
140
+ * (`javascript:`, `data:`, `file:`, `//host`, an unlisted scheme...) is printed as text without an annotation.
141
+ */
142
+ linkPolicy?: LinkPolicy;
143
+ /** Shorthand for `linkPolicy.allowedSchemes` (wins over it). */
144
+ allowedLinkSchemes?: string[];
145
+ /**
146
+ * [tagged pdf] Write a tagged (accessible) PDF: a structure tree with one Sect per sheet, one Table per print area
147
+ * (one TR per sheet row, TH / TD cells, continued across pages; repeated print titles are artifacts), Figures with
148
+ * the alternative text of the floating objects (a chart's title as its Caption), Links, artifacts for gridlines,
149
+ * borders, fills, headings, headers and footers. Default true. The file also claims PDF/UA-1 when every font is
150
+ * embedded.
151
+ */
152
+ tagged?: boolean;
153
+ /**
154
+ * [tagged pdf] Give every chart an accessible data table: a Table (series names and categories as TH, values as
155
+ * TD) after the chart's Figure in the structure tree, written as invisible text over the chart (it is extracted by
156
+ * copy / paste and text tools). Default false. Ignored when `tagged` is false.
157
+ */
158
+ chartDataTables?: boolean;
159
+ /** [tagged pdf] Natural language of the document (`/Lang`, BCP 47 such as 'fr-FR'). Default: the workbook's language property, else its culture, else 'en-US'. */
160
+ lang?: string;
161
+ }
162
+ /** One page of the PDF. */
163
+ interface PdfPageInfo {
164
+ sheet: string;
165
+ /** What `&P` printed on it. */
166
+ pageNumber: number;
167
+ /** The cells on the page (absent on comment pages). */
168
+ area?: Range;
169
+ titleRows?: [number, number];
170
+ titleCols?: [number, number];
171
+ scale: number;
172
+ /** Paper size in points. */
173
+ width: number;
174
+ height: number;
175
+ /** 'cells' or 'comments' (the list printed with `includeComments: 'atEnd'`). */
176
+ kind: 'cells' | 'comments';
177
+ /** Link annotations on the page. */
178
+ links: number;
179
+ }
180
+ interface PdfExportResult {
181
+ bytes: Uint8Array;
182
+ pages: PdfPageInfo[];
183
+ warnings: PdfWarning[];
184
+ /** [tagged pdf] Whether the file is tagged, and whether it claims PDF/UA-1 (tagged, every font embedded, no missing glyph). */
185
+ tagged: boolean;
186
+ pdfUA: boolean;
187
+ }
188
+ /** The page setup a sheet is exported with. */
189
+ declare function pdfPageSetup(sheet: Worksheet, options?: Pick<PdfExportOptions, 'pageSetup' | 'range'>): PageSetup;
190
+ /** The manual page breaks a sheet is exported with: `options.pageBreaks` (one set, or the set of the sheet's name), else the sheet's own. */
191
+ declare function pdfPageBreaks(sheet: Worksheet, options?: Pick<PdfExportOptions, 'pageBreaks'>): PageBreaks;
192
+ /** Export synchronously. Pictures that are not data: URLs must be supplied in `options.images` (or use `exportPdfAsync`). */
193
+ declare function exportPdf(source: PdfSource, options?: PdfExportOptions): Uint8Array;
194
+ /** Like `exportPdf`, also returning the pages and the warnings (what could not be rendered exactly). */
195
+ declare function exportPdfDetailed(source: PdfSource, options?: PdfExportOptions): PdfExportResult;
196
+
197
+ /**
198
+ * Convenience helpers for PDF files in browsers, Node.js and Next.js route handlers (mirroring `@openworkbook/xlsx`):
199
+ *
200
+ * ```ts
201
+ * return pdfResponse(book, 'report.pdf'); // Next.js route handler / any Web-standard server
202
+ * downloadPdf(book, 'report.pdf', { sheets: 'all' }); // browser
203
+ * await writePdf('out/report.pdf', book); // Node.js
204
+ * const bytes = await exportPdfAsync(book, { fonts: { Calibri: '/fonts/calibri.ttf' } }); // fonts / pictures by URL
205
+ * ```
206
+ */
207
+
208
+ declare const PDF_MIME = "application/pdf";
209
+ /** The PDF as a Blob (browsers, and Node 18+). */
210
+ declare function pdfBlob(source: PdfSource | Uint8Array, options?: PdfExportOptions): Blob;
211
+ /**
212
+ * A fetch `Response` with the PDF — return it from a Next.js route handler or any Web-standard server. `source` is
213
+ * a workbook (exported with `options`) or PDF bytes. Downloads as an attachment unless `init.headers` sets its own
214
+ * Content-Disposition (e.g. `inline` to show it in the browser's viewer).
215
+ */
216
+ declare function pdfResponse(source: PdfSource | Uint8Array, filename?: string, init?: ResponseInit, options?: PdfExportOptions): Response;
217
+ /** Trigger a download in the browser. */
218
+ declare function downloadPdf(source: PdfSource | Uint8Array, filename?: string, options?: PdfExportOptions): void;
219
+ /** Node.js: export and write the PDF to a file. Resolves with the export result (pages, warnings). */
220
+ declare function writePdf(path: string, source: PdfSource, options?: PdfExportOptions | AsyncPdfExportOptions): Promise<PdfExportResult>;
221
+ /** A font face given by URL / file path (loaded by the async export). */
222
+ type FontLocation = string | URL;
223
+ /** `fonts` of the async export: bytes, URLs or (Node.js) file paths. */
224
+ type AsyncFontSource = FontSource | FontLocation | {
225
+ normal?: FontBytes | FontLocation;
226
+ bold?: FontBytes | FontLocation;
227
+ italic?: FontBytes | FontLocation;
228
+ boldItalic?: FontBytes | FontLocation;
229
+ index?: number;
230
+ };
231
+ type AsyncPdfExportOptions = Omit<PdfExportOptions, 'fonts'> & {
232
+ fonts?: Record<string, AsyncFontSource>;
233
+ };
234
+ /**
235
+ * Asynchronous export: fonts may be given as URLs / file paths, pictures at http(s) / blob: URLs are downloaded,
236
+ * and in a browser GIF / WebP / BMP pictures are converted to PNG through a canvas. Otherwise as `exportPdf`.
237
+ */
238
+ declare function exportPdfDetailedAsync(source: PdfSource, options?: AsyncPdfExportOptions): Promise<PdfExportResult>;
239
+ /** `exportPdfDetailedAsync(...).bytes`. */
240
+ declare function exportPdfAsync(source: PdfSource, options?: AsyncPdfExportOptions): Promise<Uint8Array>;
241
+
242
+ /**
243
+ * `layoutPdf`: the pages a PDF export would have, each with a `draw(ctx)` that paints it on a browser canvas through
244
+ * the same page painter that writes the file (see screen.ts). For previews: the page count and every page come
245
+ * from the code path of `exportPdf`, so the preview shows what the file will contain.
246
+ *
247
+ * ```ts
248
+ * const { pages } = layoutPdf(book, { sheets: 'all' });
249
+ * pages[0].draw(canvas.getContext('2d')!, { scale: devicePixelRatio });
250
+ * ```
251
+ */
252
+
253
+ /** Options of `layoutPdf`: those of `exportPdf` (the file options such as `password` or `compress` are ignored). */
254
+ type PdfLayoutOptions = PdfExportOptions;
255
+ interface PdfDrawOptions {
256
+ /** Device pixels per page px (CSS pixel at 96 dpi), e.g. `zoom * devicePixelRatio`. Default 1. */
257
+ scale?: number;
258
+ /** Fill the paper white first (default true). */
259
+ background?: boolean;
260
+ /** A JPEG picture finished decoding after the page was drawn: draw it again to show it. */
261
+ onImageReady?: () => void;
262
+ }
263
+ /** One page of the PDF, ready to be drawn. */
264
+ interface PdfLayoutPage {
265
+ /** Zero-based position in the document. */
266
+ index: number;
267
+ sheet: string;
268
+ /** What `&P` prints on it (0 on comment pages). */
269
+ pageNumber: number;
270
+ /** 'cells' or 'comments' (the list printed with `includeComments: 'atEnd'`). */
271
+ kind: 'cells' | 'comments';
272
+ /** The cells on the page (absent on comment pages). */
273
+ area?: Range;
274
+ titleRows?: [number, number];
275
+ titleCols?: [number, number];
276
+ scale: number;
277
+ /** Paper size in points (as in the PDF). */
278
+ width: number;
279
+ height: number;
280
+ /** Paper size in CSS pixels (96 dpi): the user space of `draw`. */
281
+ widthPx: number;
282
+ heightPx: number;
283
+ /** Paint the page on a 2D canvas context, from its current transform, `scale` device pixels per page px. */
284
+ draw(ctx: CanvasRenderingContext2D, options?: PdfDrawOptions): void;
285
+ }
286
+ interface PdfLayout {
287
+ pages: PdfLayoutPage[];
288
+ pageCount: number;
289
+ /** Planning warnings (fonts substituted, pictures that cannot be embedded, ...); drawing a page may find more. */
290
+ warnings: PdfWarning[];
291
+ }
292
+ /**
293
+ * Lay out a PDF export without writing it: the pages `exportPdf(source, options)` would produce, in order, with the
294
+ * same pagination (print areas, page breaks, scaling, titles, automatic row heights measured with the PDF fonts,
295
+ * comment pages) and a `draw(ctx)` per page that paints it on a canvas with the same painters. Pages are drawn on
296
+ * demand, so laying out a long export is cheap and a preview can draw only the visible pages.
297
+ */
298
+ declare function layoutPdf(source: PdfSource, options?: PdfLayoutOptions): PdfLayout;
299
+ /** `layoutPdf` with the asynchronous export's options: fonts by URL / file path, pictures at http(s) / blob: URLs downloaded. */
300
+ declare function layoutPdfAsync(source: PdfSource, options?: AsyncPdfExportOptions): Promise<PdfLayout>;
301
+ /** Draw page `pageIndex` of the PDF export of `source` on a canvas (lays the whole export out first: keep `layoutPdf`'s result to draw several pages). */
302
+ declare function renderPdfPage(ctx: CanvasRenderingContext2D, source: PdfSource, pageIndex: number, options?: PdfLayoutOptions & PdfDrawOptions): PdfLayoutPage | undefined;
303
+
304
+ export { type AsyncFontSource, type AsyncPdfExportOptions, type FontBytes, type FontFaces, type FontLocation, type FontSource, PDF_MIME, type PdfDrawOptions, type PdfExportOptions, type PdfExportResult, type PdfLayout, type PdfLayoutOptions, type PdfLayoutPage, type PdfPageInfo, type PdfPermissions, type PdfSource, type PdfWarning, type RandomBytes, type StdFamily, downloadPdf, exportPdf, exportPdfAsync, exportPdfDetailed, exportPdfDetailedAsync, layoutPdf, layoutPdfAsync, pdfBlob, pdfPageBreaks, pdfPageSetup, pdfResponse, registerPdfFont, registeredPdfFonts, renderPdfPage, standardFamilyFor, writePdf };