@hussmartinez/pdf-sdk 0.2.0 → 0.4.0
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.
- package/README.md +36 -7
- package/dist/assets/processing/processing.worker.js +1 -1
- package/dist/index.d.ts +359 -53
- package/dist/index.js +233 -1
- package/dist/index.js.map +1 -0
- package/dist/lazy/{processing-worker-DU8GEYFs.js → processing-worker-DIP9ck2l.js} +2 -2
- package/dist/lazy/{processing-worker-DU8GEYFs.js.map → processing-worker-DIP9ck2l.js.map} +1 -1
- package/dist/react.d.ts +198 -172
- package/dist/react.js +487 -78
- package/dist/react.js.map +1 -1
- package/dist/shared/{en-BYB_GHqG.js → en-DKR-ngAZ.js} +391 -217
- package/dist/shared/en-DKR-ngAZ.js.map +1 -0
- package/dist/styles.css +19 -0
- package/formats/hm-pdf-command/v1.schema.json +162 -0
- package/formats/hm-pdf-plan/v1.schema.json +259 -0
- package/package.json +18 -10
- package/dist/shared/en-BYB_GHqG.js.map +0 -1
package/dist/index.d.ts
CHANGED
|
@@ -130,6 +130,60 @@ export declare function linkDestination(url: string): string | undefined;
|
|
|
130
130
|
*/
|
|
131
131
|
export declare const PDF_MAX_CANVAS_PIXELS = 16777216;
|
|
132
132
|
|
|
133
|
+
/**
|
|
134
|
+
* The most Unicode code points in a form field's name.
|
|
135
|
+
*
|
|
136
|
+
* @public
|
|
137
|
+
*/
|
|
138
|
+
export declare const PDF_MAX_FIELD_NAME_LENGTH = 1000;
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* The most Unicode code points in a page key, a source id or an annotation
|
|
142
|
+
* id. Lengths count code points, not UTF-16 units (sdk-core ADR 0045).
|
|
143
|
+
*
|
|
144
|
+
* @public
|
|
145
|
+
*/
|
|
146
|
+
export declare const PDF_MAX_ID_LENGTH = 128;
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* The most points in one pen or highlighter stroke.
|
|
150
|
+
*
|
|
151
|
+
* @public
|
|
152
|
+
*/
|
|
153
|
+
export declare const PDF_MAX_STROKE_POINTS = 10000;
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* The most Unicode code points in a text note, or a form field's text value.
|
|
157
|
+
*
|
|
158
|
+
* @public
|
|
159
|
+
*/
|
|
160
|
+
export declare const PDF_MAX_TEXT_LENGTH = 10000;
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* The name of the plan's portable format (sdk-core ADR 0045).
|
|
164
|
+
*
|
|
165
|
+
* @public
|
|
166
|
+
*/
|
|
167
|
+
export declare const PDF_PLAN_FORMAT = "hm-pdf-plan";
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* The version of {@link PDF_PLAN_FORMAT} this release writes, and the latest
|
|
171
|
+
* it reads.
|
|
172
|
+
*
|
|
173
|
+
* @public
|
|
174
|
+
*/
|
|
175
|
+
export declare const PDF_PLAN_VERSION = 1;
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* The grid positions and sizes on a page are kept on: millionths of the
|
|
179
|
+
* page (sdk-core ADR 0045, docs/adr/0003). Every position, size, stroke
|
|
180
|
+
* width and text size the session stores is a whole number of millionths,
|
|
181
|
+
* so a document saved in any language reproduces it exactly.
|
|
182
|
+
*
|
|
183
|
+
* @public
|
|
184
|
+
*/
|
|
185
|
+
export declare const PDF_POSITION_GRID = 1000000;
|
|
186
|
+
|
|
133
187
|
/**
|
|
134
188
|
* Adds an annotation to a page.
|
|
135
189
|
*
|
|
@@ -144,6 +198,19 @@ export declare interface PdfAddAnnotationCommand {
|
|
|
144
198
|
readonly index?: number;
|
|
145
199
|
}
|
|
146
200
|
|
|
201
|
+
/**
|
|
202
|
+
* `pdf.addAnnotation` as `hm-pdf-command` writes it, with the annotation's
|
|
203
|
+
* positions and sizes in whole millionths of the page.
|
|
204
|
+
*
|
|
205
|
+
* @public
|
|
206
|
+
*/
|
|
207
|
+
export declare interface PdfAddAnnotationCommandDocument {
|
|
208
|
+
readonly type: "pdf.addAnnotation";
|
|
209
|
+
readonly page: string;
|
|
210
|
+
readonly annotation: PdfAnnotationDocument;
|
|
211
|
+
readonly index?: number;
|
|
212
|
+
}
|
|
213
|
+
|
|
147
214
|
/**
|
|
148
215
|
* Anything the editor draws on top of a page until it's flattened on export
|
|
149
216
|
* (ADR 0003). Annotations are plain data, so they can be stored in commands
|
|
@@ -153,6 +220,29 @@ export declare interface PdfAddAnnotationCommand {
|
|
|
153
220
|
*/
|
|
154
221
|
export declare type PdfAnnotation = PdfStrokeAnnotation | PdfTextAnnotation | PdfImageAnnotation;
|
|
155
222
|
|
|
223
|
+
/**
|
|
224
|
+
* An annotation in a plan document. Version 1 has no signatures: their image
|
|
225
|
+
* needs an asset, whose design comes with the signature tool (docs/adr/0003).
|
|
226
|
+
*
|
|
227
|
+
* @public
|
|
228
|
+
*/
|
|
229
|
+
export declare type PdfAnnotationDocument = PdfStrokeAnnotationDocument | PdfTextAnnotationDocument;
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* A content-addressed reference to binary data, such as a source's file
|
|
233
|
+
* (sdk-core ADR 0045). Documents never inline bytes.
|
|
234
|
+
*
|
|
235
|
+
* @public
|
|
236
|
+
*/
|
|
237
|
+
export declare interface PdfAssetReference {
|
|
238
|
+
/** `sha256:` and the lowercase hex SHA-256 of the bytes. */
|
|
239
|
+
readonly asset: string;
|
|
240
|
+
/** The bytes' media type, such as `application/pdf`, in lowercase. */
|
|
241
|
+
readonly mediaType: string;
|
|
242
|
+
/** The size of the bytes. */
|
|
243
|
+
readonly size: number;
|
|
244
|
+
}
|
|
245
|
+
|
|
156
246
|
/**
|
|
157
247
|
* Everything needed to build an output document from the page plan, in one
|
|
158
248
|
* call to the processor (ADR 0003): the sources, the pages in order, and the
|
|
@@ -252,7 +342,7 @@ export declare interface PdfCallOptions {
|
|
|
252
342
|
}
|
|
253
343
|
|
|
254
344
|
/**
|
|
255
|
-
* A colour as `#rrggbb
|
|
345
|
+
* A colour as `#rrggbb`, in lowercase.
|
|
256
346
|
*
|
|
257
347
|
* @public
|
|
258
348
|
*/
|
|
@@ -267,6 +357,56 @@ export declare type PdfColor = `#${string}`;
|
|
|
267
357
|
*/
|
|
268
358
|
export declare type PdfCommand = PdfRotatePagesCommand | PdfDeletePagesCommand | PdfRestorePagesCommand | PdfMovePagesCommand | PdfReorderPagesCommand | PdfInsertPagesCommand | PdfSetFieldValueCommand | PdfAddAnnotationCommand | PdfRemoveAnnotationCommand;
|
|
269
359
|
|
|
360
|
+
/**
|
|
361
|
+
* A user-level command as portable JSON: `hm-pdf-command` version 1, which
|
|
362
|
+
* `formats/hm-pdf-command/v1.schema.json` describes. Every command but
|
|
363
|
+
* `pdf.restorePages`, an inverse that carries whole pages; only
|
|
364
|
+
* `pdf.addAnnotation` differs from the command in memory.
|
|
365
|
+
*
|
|
366
|
+
* @public
|
|
367
|
+
*/
|
|
368
|
+
export declare type PdfCommandDocument = Exclude<PdfCommand, PdfRestorePagesCommand | PdfAddAnnotationCommand> | PdfAddAnnotationCommandDocument;
|
|
369
|
+
|
|
370
|
+
/**
|
|
371
|
+
* Why a command was refused, as a stable token: `details.reason` on the
|
|
372
|
+
* `INVALID_COMMAND` error (sdk-core ADR 0045).
|
|
373
|
+
*
|
|
374
|
+
* - `malformed-command`: not shaped as a command of its type, such as a
|
|
375
|
+
* missing field, a field of the wrong type, an unknown field, an empty
|
|
376
|
+
* list of pages, or an id that's empty or over `PDF_MAX_ID_LENGTH` code
|
|
377
|
+
* points.
|
|
378
|
+
* - `unknown-command`: a `type` the session doesn't know.
|
|
379
|
+
* - `unknown-page`: a page key the plan doesn't have.
|
|
380
|
+
* - `duplicate-page`: a page named twice in one command.
|
|
381
|
+
* - `last-page`: deleting every page; a document keeps at least one.
|
|
382
|
+
* - `invalid-position`: a position outside the plan, or outside a page's
|
|
383
|
+
* annotations.
|
|
384
|
+
* - `invalid-rotation`: an angle that isn't a multiple of 90 degrees from
|
|
385
|
+
* -360 to 360, or a page rotation other than 0, 90, 180 or 270.
|
|
386
|
+
* - `invalid-order`: a new order that doesn't list every page exactly once.
|
|
387
|
+
* - `invalid-keys`: an insert without one key per page.
|
|
388
|
+
* - `duplicate-key`: a new page key the plan already has, or one given twice.
|
|
389
|
+
* - `unknown-source`: a source the session doesn't hold.
|
|
390
|
+
* - `page-out-of-range`: a page index its source doesn't have.
|
|
391
|
+
* - `field-name-too-long`: a form field's name over
|
|
392
|
+
* `PDF_MAX_FIELD_NAME_LENGTH` code points.
|
|
393
|
+
* - `text-too-long`: a text note, or a field's text value, over
|
|
394
|
+
* `PDF_MAX_TEXT_LENGTH` code points.
|
|
395
|
+
* - `unknown-annotation`: an annotation id the page doesn't have.
|
|
396
|
+
* - `duplicate-annotation`: an annotation id the page already has.
|
|
397
|
+
* - `unsupported-annotation`: an annotation type the session doesn't edit,
|
|
398
|
+
* such as `signature`, whose image the portable format can't carry yet.
|
|
399
|
+
* - `outside-page`: a position outside the page, 0 to 1 on each axis.
|
|
400
|
+
* - `invalid-size`: a stroke width or text size that isn't more than 0 and
|
|
401
|
+
* at most 1, after snapping to `PDF_POSITION_GRID`.
|
|
402
|
+
* - `too-many-points`: a stroke with no points, or over
|
|
403
|
+
* `PDF_MAX_STROKE_POINTS`.
|
|
404
|
+
* - `invalid-color`: a colour that isn't `#rrggbb` in lowercase.
|
|
405
|
+
*
|
|
406
|
+
* @public
|
|
407
|
+
*/
|
|
408
|
+
export declare type PdfCommandRejection = "malformed-command" | "unknown-command" | "unknown-page" | "duplicate-page" | "last-page" | "invalid-position" | "invalid-rotation" | "invalid-order" | "invalid-keys" | "duplicate-key" | "unknown-source" | "page-out-of-range" | "field-name-too-long" | "text-too-long" | "unknown-annotation" | "duplicate-annotation" | "unsupported-annotation" | "outside-page" | "invalid-size" | "too-many-points" | "invalid-color";
|
|
409
|
+
|
|
270
410
|
/**
|
|
271
411
|
* How to compress the output. Compression is lossless unless `images` is set.
|
|
272
412
|
*
|
|
@@ -330,6 +470,37 @@ export declare interface PdfDocumentHandle {
|
|
|
330
470
|
destroy(): Promise<void>;
|
|
331
471
|
}
|
|
332
472
|
|
|
473
|
+
/**
|
|
474
|
+
* A point in a plan document: whole millionths of the page, from 0 to
|
|
475
|
+
* {@link PDF_POSITION_GRID}.
|
|
476
|
+
*
|
|
477
|
+
* @public
|
|
478
|
+
*/
|
|
479
|
+
export declare interface PdfDocumentPoint {
|
|
480
|
+
readonly x: number;
|
|
481
|
+
readonly y: number;
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
/**
|
|
485
|
+
* Why a plan document was refused, as a stable token: `details.reason` on
|
|
486
|
+
* the error (sdk-core ADR 0045).
|
|
487
|
+
*
|
|
488
|
+
* - With `UNSUPPORTED_FORMAT`: `unknown-format`, a document of another
|
|
489
|
+
* format, and `unknown-format-version`, a later version than this release
|
|
490
|
+
* reads.
|
|
491
|
+
* - With `INVALID_DOCUMENT`: `malformed-document`, a document that isn't
|
|
492
|
+
* shaped as the schema says; `unknown-source`, a page or form values for a
|
|
493
|
+
* source the document doesn't list; `page-out-of-range`, a page index its
|
|
494
|
+
* source doesn't have; `duplicate-key`, two pages with one key;
|
|
495
|
+
* `duplicate-annotation`, two annotations with one id on a page; and, as
|
|
496
|
+
* for commands, `invalid-rotation`, `outside-page`, `invalid-size`,
|
|
497
|
+
* `too-many-points`, `invalid-color`, `unsupported-annotation`,
|
|
498
|
+
* `field-name-too-long` and `text-too-long`.
|
|
499
|
+
*
|
|
500
|
+
* @public
|
|
501
|
+
*/
|
|
502
|
+
export declare type PdfDocumentRejection = "unknown-format" | "unknown-format-version" | "malformed-document" | "unknown-source" | "page-out-of-range" | "duplicate-key" | "duplicate-annotation" | "invalid-rotation" | "outside-page" | "invalid-size" | "too-many-points" | "invalid-color" | "unsupported-annotation" | "field-name-too-long" | "text-too-long";
|
|
503
|
+
|
|
333
504
|
/**
|
|
334
505
|
* How to encrypt the output. Encryption is always AES-256.
|
|
335
506
|
*
|
|
@@ -406,13 +577,21 @@ export declare class PdfError extends SdkError<PdfErrorCode> {
|
|
|
406
577
|
* - `IMAGE_TOO_LARGE`: an image exceeds the `maxImagePixels` limit. It's
|
|
407
578
|
* reported as a warning, because the image is skipped rather than the
|
|
408
579
|
* document failing (ADR 0004).
|
|
580
|
+
* - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as
|
|
581
|
+
* one naming a page the plan doesn't have. `details.reason` says why, as
|
|
582
|
+
* a stable token (`PdfCommandRejection`, sdk-core ADR 0045).
|
|
583
|
+
* - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
|
|
584
|
+
* valid in its format. `details.reason` says why (`PdfDocumentRejection`).
|
|
585
|
+
* - `UNSUPPORTED_FORMAT`: a plan document of another format, or of a later
|
|
586
|
+
* version than this release reads, with `details.reason`
|
|
587
|
+
* `unknown-format` or `unknown-format-version`.
|
|
409
588
|
*
|
|
410
589
|
* Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
|
|
411
590
|
* value and the `unit`.
|
|
412
591
|
*
|
|
413
592
|
* @public
|
|
414
593
|
*/
|
|
415
|
-
export declare type PdfErrorCode = SdkCoreErrorCode | "INVALID_PDF" | "PASSWORD_REQUIRED" | "PROCESSING_FAILED" | "TOO_MANY_PAGES" | "SESSION_TOO_LARGE" | "IMAGE_TOO_LARGE";
|
|
594
|
+
export declare type PdfErrorCode = SdkCoreErrorCode | "INVALID_PDF" | "PASSWORD_REQUIRED" | "PROCESSING_FAILED" | "TOO_MANY_PAGES" | "SESSION_TOO_LARGE" | "IMAGE_TOO_LARGE" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "UNSUPPORTED_FORMAT";
|
|
416
595
|
|
|
417
596
|
/**
|
|
418
597
|
* Options for {@link PdfSession.export}.
|
|
@@ -481,6 +660,10 @@ export declare interface PdfFormField {
|
|
|
481
660
|
/**
|
|
482
661
|
* A drawn signature, or another image, placed on the page.
|
|
483
662
|
*
|
|
663
|
+
* The session refuses it for now, with `INVALID_COMMAND` and
|
|
664
|
+
* `unsupported-annotation`: the portable format can't carry its image yet
|
|
665
|
+
* (docs/adr/0003). The editor's signature tool will bring it back.
|
|
666
|
+
*
|
|
484
667
|
* @public
|
|
485
668
|
*/
|
|
486
669
|
export declare interface PdfImageAnnotation {
|
|
@@ -513,7 +696,7 @@ export declare interface PdfImageCompression {
|
|
|
513
696
|
*
|
|
514
697
|
* @public
|
|
515
698
|
*/
|
|
516
|
-
export declare interface PdfInsertOptions extends
|
|
699
|
+
export declare interface PdfInsertOptions extends PdfOpenOptions {
|
|
517
700
|
/** The position of the first inserted page. Defaults to the end. */
|
|
518
701
|
readonly at?: number;
|
|
519
702
|
/** Zero-based indexes of the pages to insert. Defaults to every page. */
|
|
@@ -672,10 +855,14 @@ export declare interface PdfLink {
|
|
|
672
855
|
export declare type PdfMessageCatalogue = typeof pdfMessages;
|
|
673
856
|
|
|
674
857
|
/**
|
|
675
|
-
* The PDF SDK's English message catalogue
|
|
676
|
-
* every {@link PdfErrorCode} and every
|
|
677
|
-
* `createMessages` from `@hussmartinez/sdk-core`,
|
|
678
|
-
* overrides.
|
|
858
|
+
* The PDF SDK's English message catalogue for the server-safe entry:
|
|
859
|
+
* sdk-core's messages, and text for every {@link PdfErrorCode} and every
|
|
860
|
+
* limit's warning. Pass it to `createMessages` from `@hussmartinez/sdk-core`,
|
|
861
|
+
* with the host's locale and overrides.
|
|
862
|
+
*
|
|
863
|
+
* It holds no interface text: the editor's, the viewer's and the
|
|
864
|
+
* thumbnails' text is in `pdfEditorMessages`, from the React entry
|
|
865
|
+
* (docs/adr/0010).
|
|
679
866
|
*
|
|
680
867
|
* Error text is looked up by code, with the error's `details` as
|
|
681
868
|
* parameters, and never taken from `error.message` (ADR 0019).
|
|
@@ -696,6 +883,9 @@ export declare const pdfMessages: {
|
|
|
696
883
|
readonly "errors.TOO_MANY_PAGES": "This document has {actual, number} pages, which is over the {maximum, number}-page limit.";
|
|
697
884
|
readonly "errors.SESSION_TOO_LARGE": "The open documents would use {actual, fileSize}, which is over the {maximum, fileSize} limit. Close a document, or clear the undo history, and try again.";
|
|
698
885
|
readonly "errors.IMAGE_TOO_LARGE": "Some images are too large to show. They're kept unchanged in the document.";
|
|
886
|
+
readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
|
|
887
|
+
readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't a PDF project.";
|
|
888
|
+
readonly "errors.UNSUPPORTED_FORMAT": "This project was saved by a newer version, or by another app. Update the app, and try again.";
|
|
699
889
|
readonly "warnings.maxPages": {
|
|
700
890
|
readonly $plural: "actual";
|
|
701
891
|
} & {
|
|
@@ -704,46 +894,6 @@ export declare const pdfMessages: {
|
|
|
704
894
|
};
|
|
705
895
|
readonly "warnings.maxSessionSize": "The open documents use {actual, fileSize}. Clearing the undo history frees memory.";
|
|
706
896
|
readonly "warnings.maxImagePixels": "Some images are very large and may be slow to show.";
|
|
707
|
-
readonly "viewer.label": "Document";
|
|
708
|
-
readonly "viewer.empty": "No document is open.";
|
|
709
|
-
readonly "viewer.page": "Page {page} of {count}";
|
|
710
|
-
readonly "viewer.webLink": "Link to {destination}, opens in a new tab";
|
|
711
|
-
readonly "viewer.emailLink": "Email {destination}";
|
|
712
|
-
readonly "thumbnails.label": "Pages";
|
|
713
|
-
readonly "thumbnails.page": "Page {page} of {count}";
|
|
714
|
-
readonly "thumbnails.number": "{page}";
|
|
715
|
-
readonly "editor.label": "PDF editor";
|
|
716
|
-
readonly "editor.start.title": "Open a PDF to get started";
|
|
717
|
-
readonly "editor.start.retryTitle": "Try another PDF";
|
|
718
|
-
readonly "editor.start.choose": "Choose a PDF";
|
|
719
|
-
readonly "editor.start.retry": "Choose another PDF";
|
|
720
|
-
readonly "editor.start.hint": "Or drop one here. Your file stays on this device and is never uploaded.";
|
|
721
|
-
readonly "editor.opening": "Opening the PDF…";
|
|
722
|
-
readonly "editor.opened": {
|
|
723
|
-
readonly $plural: "count";
|
|
724
|
-
} & {
|
|
725
|
-
readonly one: "Opened a PDF with {count} page.";
|
|
726
|
-
readonly other: "Opened a PDF with {count} pages.";
|
|
727
|
-
};
|
|
728
|
-
readonly "editor.closed": "The PDF was closed.";
|
|
729
|
-
readonly "editor.undone": "Undone.";
|
|
730
|
-
readonly "editor.redone": "Redone.";
|
|
731
|
-
readonly "editor.rotated": {
|
|
732
|
-
readonly $plural: "count";
|
|
733
|
-
} & {
|
|
734
|
-
readonly one: "Rotated {count} page.";
|
|
735
|
-
readonly other: "Rotated {count} pages.";
|
|
736
|
-
};
|
|
737
|
-
readonly "toolbar.label": "PDF tools";
|
|
738
|
-
readonly "toolbar.groups.file": "File";
|
|
739
|
-
readonly "toolbar.groups.history": "History";
|
|
740
|
-
readonly "toolbar.groups.pages": "Pages";
|
|
741
|
-
readonly "toolbar.groups.other": "More tools";
|
|
742
|
-
readonly "tools.open": "Open a PDF";
|
|
743
|
-
readonly "tools.undo": "Undo";
|
|
744
|
-
readonly "tools.redo": "Redo";
|
|
745
|
-
readonly "tools.rotate-left": "Rotate left";
|
|
746
|
-
readonly "tools.rotate-right": "Rotate right";
|
|
747
897
|
readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
|
|
748
898
|
readonly "errors.ABORTED": "The operation was cancelled.";
|
|
749
899
|
readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
|
|
@@ -804,6 +954,19 @@ export declare interface PdfMovePagesCommand {
|
|
|
804
954
|
readonly to: number;
|
|
805
955
|
}
|
|
806
956
|
|
|
957
|
+
/**
|
|
958
|
+
* Options for {@link PdfSession.open}.
|
|
959
|
+
*
|
|
960
|
+
* @public
|
|
961
|
+
*/
|
|
962
|
+
export declare interface PdfOpenOptions extends PdfCallOptions {
|
|
963
|
+
/**
|
|
964
|
+
* The file's name, for bytes or a `Blob` that isn't a `File`. It wins over
|
|
965
|
+
* `File.name`, and is cleaned before it's kept (docs/adr/0009).
|
|
966
|
+
*/
|
|
967
|
+
readonly name?: string;
|
|
968
|
+
}
|
|
969
|
+
|
|
807
970
|
/**
|
|
808
971
|
* Facts about one page of a source document.
|
|
809
972
|
*
|
|
@@ -831,6 +994,47 @@ export declare interface PdfPlan {
|
|
|
831
994
|
readonly formValues: Readonly<Record<string, Readonly<Record<string, PdfFieldValue>>>>;
|
|
832
995
|
}
|
|
833
996
|
|
|
997
|
+
/**
|
|
998
|
+
* The plan as portable JSON: `hm-pdf-plan` version 1, which
|
|
999
|
+
* `formats/hm-pdf-plan/v1.schema.json` describes
|
|
1000
|
+
* (docs/formats/hm-pdf-plan.md). Positions and sizes are whole millionths of
|
|
1001
|
+
* the page, and pages name their sources by ids the document lists.
|
|
1002
|
+
*
|
|
1003
|
+
* @public
|
|
1004
|
+
*/
|
|
1005
|
+
export declare interface PdfPlanDocument {
|
|
1006
|
+
readonly format: typeof PDF_PLAN_FORMAT;
|
|
1007
|
+
readonly version: typeof PDF_PLAN_VERSION;
|
|
1008
|
+
readonly sources: Readonly<Record<string, PdfPlanDocumentSource>>;
|
|
1009
|
+
readonly pages: readonly PdfPlanDocumentPage[];
|
|
1010
|
+
readonly formValues: Readonly<Record<string, Readonly<Record<string, PdfFieldValue>>>>;
|
|
1011
|
+
}
|
|
1012
|
+
|
|
1013
|
+
/**
|
|
1014
|
+
* A page in a plan document.
|
|
1015
|
+
*
|
|
1016
|
+
* @public
|
|
1017
|
+
*/
|
|
1018
|
+
export declare interface PdfPlanDocumentPage {
|
|
1019
|
+
readonly key: string;
|
|
1020
|
+
readonly source: string;
|
|
1021
|
+
readonly pageIndex: number;
|
|
1022
|
+
readonly rotation: PdfRotation;
|
|
1023
|
+
readonly annotations: readonly PdfAnnotationDocument[];
|
|
1024
|
+
}
|
|
1025
|
+
|
|
1026
|
+
/**
|
|
1027
|
+
* A source, as a plan document records it: its page count, which the pages
|
|
1028
|
+
* that use it must fit, and, once documents travel with their files, its
|
|
1029
|
+
* content.
|
|
1030
|
+
*
|
|
1031
|
+
* @public
|
|
1032
|
+
*/
|
|
1033
|
+
export declare interface PdfPlanDocumentSource {
|
|
1034
|
+
readonly pageCount: number;
|
|
1035
|
+
readonly asset?: PdfAssetReference;
|
|
1036
|
+
}
|
|
1037
|
+
|
|
834
1038
|
/**
|
|
835
1039
|
* One page of the page plan (docs/adr/0003): a page of a source document,
|
|
836
1040
|
* with a rotation added to its own, and the annotations drawn on it. The key
|
|
@@ -986,7 +1190,10 @@ export declare interface PdfRotatePagesCommand {
|
|
|
986
1190
|
readonly type: "pdf.rotatePages";
|
|
987
1191
|
/** The keys of the pages to rotate. */
|
|
988
1192
|
readonly pages: readonly string[];
|
|
989
|
-
/**
|
|
1193
|
+
/**
|
|
1194
|
+
* Degrees, clockwise, in multiples of 90 from -360 to 360. Negative turns
|
|
1195
|
+
* anticlockwise.
|
|
1196
|
+
*/
|
|
990
1197
|
readonly angle: number;
|
|
991
1198
|
}
|
|
992
1199
|
|
|
@@ -1016,7 +1223,7 @@ export declare interface PdfSession {
|
|
|
1016
1223
|
* Rejects with a `PdfError`, which the snapshot also holds; the current
|
|
1017
1224
|
* document, if any, stays open.
|
|
1018
1225
|
*/
|
|
1019
|
-
open(file: Blob | PdfBytes, options?:
|
|
1226
|
+
open(file: Blob | PdfBytes, options?: PdfOpenOptions): Promise<void>;
|
|
1020
1227
|
/**
|
|
1021
1228
|
* Inserts the pages of another document, as one undoable step. If the
|
|
1022
1229
|
* documents held would then exceed `maxSessionSize`, the session first
|
|
@@ -1027,9 +1234,11 @@ export declare interface PdfSession {
|
|
|
1027
1234
|
*/
|
|
1028
1235
|
insert(file: Blob | PdfBytes, options?: PdfInsertOptions): Promise<void>;
|
|
1029
1236
|
/**
|
|
1030
|
-
* Runs one command, or several as one undoable step. Throws `
|
|
1031
|
-
*
|
|
1032
|
-
* nothing then.
|
|
1237
|
+
* Runs one command, or several as one undoable step. Throws `PdfError`
|
|
1238
|
+
* with `INVALID_COMMAND` for a command that doesn't fit the plan, with a
|
|
1239
|
+
* `PdfCommandRejection` as `details.reason`, and changes nothing then.
|
|
1240
|
+
* Positions and sizes are snapped to millionths of the page
|
|
1241
|
+
* (`PDF_POSITION_GRID`).
|
|
1033
1242
|
*/
|
|
1034
1243
|
execute(commands: PdfCommand | readonly PdfCommand[]): void;
|
|
1035
1244
|
undo(): void;
|
|
@@ -1147,7 +1356,9 @@ export declare interface PdfSessionSnapshot {
|
|
|
1147
1356
|
readonly historyTrimmed: boolean;
|
|
1148
1357
|
/**
|
|
1149
1358
|
* The keys of the selected pages, in plan order. Tools act on them, such as
|
|
1150
|
-
* rotating the selection. View state: not
|
|
1359
|
+
* rotating the selection. View state: not part of the plan and never in
|
|
1360
|
+
* events, but undo and redo bring back the selection and current page
|
|
1361
|
+
* that went with each step (docs/adr/0008).
|
|
1151
1362
|
*/
|
|
1152
1363
|
readonly selection: readonly string[];
|
|
1153
1364
|
/** The key of the page the user is looking at, if a document is open. */
|
|
@@ -1200,6 +1411,13 @@ export declare interface PdfSourceInfo {
|
|
|
1200
1411
|
readonly pageCount: number;
|
|
1201
1412
|
/** The size of its bytes. */
|
|
1202
1413
|
readonly byteLength: number;
|
|
1414
|
+
/**
|
|
1415
|
+
* The file's name, from `File.name` or the `name` option, cleaned as
|
|
1416
|
+
* docs/adr/0009 describes: one path segment, without control or
|
|
1417
|
+
* bidirectional formatting characters, at most 128 code points. Absent
|
|
1418
|
+
* when there was none. Show it only as text; it never reaches `onEvent`.
|
|
1419
|
+
*/
|
|
1420
|
+
readonly name?: string;
|
|
1203
1421
|
}
|
|
1204
1422
|
|
|
1205
1423
|
/**
|
|
@@ -1217,6 +1435,20 @@ export declare interface PdfStrokeAnnotation {
|
|
|
1217
1435
|
readonly width: number;
|
|
1218
1436
|
}
|
|
1219
1437
|
|
|
1438
|
+
/**
|
|
1439
|
+
* A pen or highlighter stroke in a plan document. Its points and width are
|
|
1440
|
+
* whole millionths of the page.
|
|
1441
|
+
*
|
|
1442
|
+
* @public
|
|
1443
|
+
*/
|
|
1444
|
+
export declare interface PdfStrokeAnnotationDocument {
|
|
1445
|
+
readonly id: string;
|
|
1446
|
+
readonly type: "pen" | "highlight";
|
|
1447
|
+
readonly points: readonly PdfDocumentPoint[];
|
|
1448
|
+
readonly color: PdfColor;
|
|
1449
|
+
readonly width: number;
|
|
1450
|
+
}
|
|
1451
|
+
|
|
1220
1452
|
/**
|
|
1221
1453
|
* A text note placed on the page.
|
|
1222
1454
|
*
|
|
@@ -1234,6 +1466,21 @@ export declare interface PdfTextAnnotation {
|
|
|
1234
1466
|
readonly color: PdfColor;
|
|
1235
1467
|
}
|
|
1236
1468
|
|
|
1469
|
+
/**
|
|
1470
|
+
* A text note in a plan document. Its position and size are whole
|
|
1471
|
+
* millionths of the page.
|
|
1472
|
+
*
|
|
1473
|
+
* @public
|
|
1474
|
+
*/
|
|
1475
|
+
export declare interface PdfTextAnnotationDocument {
|
|
1476
|
+
readonly id: string;
|
|
1477
|
+
readonly type: "text";
|
|
1478
|
+
readonly at: PdfDocumentPoint;
|
|
1479
|
+
readonly text: string;
|
|
1480
|
+
readonly size: number;
|
|
1481
|
+
readonly color: PdfColor;
|
|
1482
|
+
}
|
|
1483
|
+
|
|
1237
1484
|
/**
|
|
1238
1485
|
* The text of one page, in reading order as the document stores it.
|
|
1239
1486
|
*
|
|
@@ -1287,6 +1534,40 @@ export declare interface PdfWarning {
|
|
|
1287
1534
|
readonly actual: number;
|
|
1288
1535
|
}
|
|
1289
1536
|
|
|
1537
|
+
/**
|
|
1538
|
+
* Reads a command in its portable form, `hm-pdf-command` version 1, such as
|
|
1539
|
+
* one parsed from JSON, into the command the session executes: an
|
|
1540
|
+
* annotation's millionths become fractions of the page. The session's
|
|
1541
|
+
* reducer checks everything else when the command runs.
|
|
1542
|
+
*
|
|
1543
|
+
* @param value - The parsed JSON.
|
|
1544
|
+
* @throws `PdfError` with `INVALID_COMMAND` and `malformed-command` for a
|
|
1545
|
+
* position or size that isn't whole millionths, and `unknown-command` for
|
|
1546
|
+
* `pdf.restorePages`, which isn't part of the format.
|
|
1547
|
+
* @public
|
|
1548
|
+
*/
|
|
1549
|
+
export declare function readPdfCommandDocument(value: unknown): PdfCommand;
|
|
1550
|
+
|
|
1551
|
+
/**
|
|
1552
|
+
* Reads a plan document, such as one parsed from JSON, checking it as
|
|
1553
|
+
* {@link PdfPlanDocument}'s schema does and more: every page's source must
|
|
1554
|
+
* be one the document lists, with the page's index, and page keys and each
|
|
1555
|
+
* page's annotation ids must be unique. Unknown fields are refused, never
|
|
1556
|
+
* dropped.
|
|
1557
|
+
*
|
|
1558
|
+
* @param value - The parsed JSON.
|
|
1559
|
+
* @returns The plan, with positions as fractions of the page, and its
|
|
1560
|
+
* sources by id.
|
|
1561
|
+
* @throws `PdfError` with `UNSUPPORTED_FORMAT` for another format or a later
|
|
1562
|
+
* version, and `INVALID_DOCUMENT` for anything else that's wrong, with a
|
|
1563
|
+
* {@link PdfDocumentRejection} as `details.reason`.
|
|
1564
|
+
* @public
|
|
1565
|
+
*/
|
|
1566
|
+
export declare function readPdfPlanDocument(value: unknown): {
|
|
1567
|
+
readonly plan: PdfPlan;
|
|
1568
|
+
readonly sources: Readonly<Record<string, PdfPlanDocumentSource>>;
|
|
1569
|
+
};
|
|
1570
|
+
|
|
1290
1571
|
/**
|
|
1291
1572
|
* The URL, normalised, if it's an absolute `http`, `https` or `mailto` URL
|
|
1292
1573
|
* without credentials (ADR 0012), and otherwise undefined. Every engine
|
|
@@ -1301,4 +1582,29 @@ export declare interface PdfWarning {
|
|
|
1301
1582
|
*/
|
|
1302
1583
|
export declare function safeLinkUrl(url: string): string | undefined;
|
|
1303
1584
|
|
|
1585
|
+
/**
|
|
1586
|
+
* Writes a command in its portable form, `hm-pdf-command` version 1, with an
|
|
1587
|
+
* annotation's positions and sizes in whole millionths of the page.
|
|
1588
|
+
*
|
|
1589
|
+
* @param command - A command the session applied, so its values are on the
|
|
1590
|
+
* grid.
|
|
1591
|
+
* @throws `TypeError` for `pdf.restorePages`, which isn't part of the
|
|
1592
|
+
* format, and for a signature annotation, which version 1 can't hold.
|
|
1593
|
+
* @public
|
|
1594
|
+
*/
|
|
1595
|
+
export declare function toPdfCommandDocument(command: PdfCommand): PdfCommandDocument;
|
|
1596
|
+
|
|
1597
|
+
/**
|
|
1598
|
+
* Writes a plan as a {@link PdfPlanDocument}, plain JSON-ready data, with
|
|
1599
|
+
* positions and sizes in whole millionths of the page.
|
|
1600
|
+
*
|
|
1601
|
+
* @param plan - The plan, such as a session snapshot's.
|
|
1602
|
+
* @param sources - The sources by id, with at least every one the plan's
|
|
1603
|
+
* pages and form values use. They're written as given.
|
|
1604
|
+
* @throws `TypeError` if a source the plan uses is missing from `sources`,
|
|
1605
|
+
* or the plan has a signature annotation, which version 1 can't hold.
|
|
1606
|
+
* @public
|
|
1607
|
+
*/
|
|
1608
|
+
export declare function toPdfPlanDocument(plan: PdfPlan, sources: Readonly<Record<string, PdfPlanDocumentSource>>): PdfPlanDocument;
|
|
1609
|
+
|
|
1304
1610
|
export { }
|