@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.
@@ -1 +1 @@
1
- {"version":3,"file":"processing-worker-DU8GEYFs.js","names":["ProcessingWorker"],"sources":["../../src/adapters/qpdf/processing-worker.ts"],"sourcesContent":["import ProcessingWorker from \"../../workers/processing.worker.ts?worker&inline\";\n\n/** Starts the inlined processing worker, from its own lazy chunk. */\nexport function createInlineWorker(): Worker {\n return new ProcessingWorker({ name: \"hm-pdf-processing\" });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAGA,SAAgB,qBAA6B;CAC3C,OAAO,IAAIA,cAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC3D"}
1
+ {"version":3,"file":"processing-worker-DIP9ck2l.js","names":["ProcessingWorker"],"sources":["../../src/adapters/qpdf/processing-worker.ts"],"sourcesContent":["import ProcessingWorker from \"../../workers/processing.worker.ts?worker&inline\";\n\n/** Starts the inlined processing worker, from its own lazy chunk. */\nexport function createInlineWorker(): Worker {\n return new ProcessingWorker({ name: \"hm-pdf-processing\" });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAGA,SAAgB,qBAA6B;CAC3C,OAAO,IAAIA,cAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC3D"}
package/dist/react.d.ts CHANGED
@@ -144,7 +144,7 @@ declare interface PdfCallOptions {
144
144
  }
145
145
 
146
146
  /**
147
- * A colour as `#rrggbb`.
147
+ * A colour as `#rrggbb`, in lowercase.
148
148
  *
149
149
  * @public
150
150
  */
@@ -222,6 +222,18 @@ declare interface PdfDocumentHandle {
222
222
  destroy(): Promise<void>;
223
223
  }
224
224
 
225
+ /**
226
+ * What {@link PdfEditorProps.downloadName} is given to name a download.
227
+ *
228
+ * @public
229
+ */
230
+ export declare interface PdfDownloadNameInfo {
231
+ /** The opened file's name, cleaned (docs/adr/0009), if it had one. */
232
+ readonly sourceName?: string;
233
+ /** The page count of the document being saved. */
234
+ readonly pageCount: number;
235
+ }
236
+
225
237
  /**
226
238
  * The complete editor: a document's pages beside it as thumbnails, with
227
239
  * designed states for no document, opening and a failed open (ADR 0014).
@@ -268,6 +280,11 @@ export declare interface PdfEditorChange {
268
280
  readonly reason: "open" | "edit" | "close";
269
281
  /** The document's page count after the change; 0 once it's closed. */
270
282
  readonly pageCount: number;
283
+ /**
284
+ * On `open`, the opened file's name, cleaned (docs/adr/0009), if it had
285
+ * one: from `File.name` or the `name` option. Show it only as text.
286
+ */
287
+ readonly fileName?: string;
271
288
  }
272
289
 
273
290
  /**
@@ -278,8 +295,11 @@ export declare interface PdfEditorChange {
278
295
  export declare interface PdfEditorHandle {
279
296
  /** The editor's session, for commands and state beyond the handle's. */
280
297
  readonly session: PdfSession;
281
- /** Opens a document, replacing the current one once it has opened. */
282
- open(file: Blob | PdfBytes): Promise<void>;
298
+ /**
299
+ * Opens a document, replacing the current one once it has opened. Pass
300
+ * `name` with bytes or a plain `Blob`; a `File` gives its own.
301
+ */
302
+ open(file: Blob | PdfBytes, options?: PdfOpenOptions): Promise<void>;
283
303
  /** Builds the document as it is now. The result is a new buffer the caller owns. */
284
304
  export(options?: PdfExportOptions): Promise<Uint8Array>;
285
305
  /** Undoes the last edit, if there is one. */
@@ -299,41 +319,22 @@ export declare interface PdfEditorHandle {
299
319
  export declare type PdfEditorMessageCatalogue = typeof pdfEditorMessages;
300
320
 
301
321
  /**
302
- * The editor's English message catalogue: the SDK's own, which includes
303
- * sdk-core's, and `@hussmartinez/ui`'s, for the ui components the editor
304
- * renders (sdk-core ADR 0046). The editor builds one `Messages` object from
305
- * it, with the host's locale and overrides, and gives the same object to
306
- * its own components and to ui's.
322
+ * The English message catalogue of the SDK's components: `pdfMessages`,
323
+ * with sdk-core's text, errors and warnings; `@hussmartinez/ui`'s, for the
324
+ * ui components the editor renders (sdk-core ADR 0046); and the text of the
325
+ * editor, its toolbar and tools, the viewer and the thumbnails.
307
326
  *
308
- * It's defined in the React entry, so the headless `.` entry and its
309
- * `pdfMessages` don't carry ui's text.
327
+ * `PdfEditor` and `PdfSessionProvider` each build one `Messages` object from
328
+ * it, with the host's locale and overrides, and the editor gives the same
329
+ * object to its own components and to ui's. Override any of its keys through
330
+ * their `messages` prop, typed with `PdfEditorMessageCatalogue`.
331
+ *
332
+ * It's defined in the React entry, so the server-safe `.` entry and its
333
+ * `pdfMessages` carry no interface text (docs/adr/0010).
310
334
  *
311
335
  * @public
312
336
  */
313
337
  export declare const pdfEditorMessages: {
314
- readonly "dialog.close": "Close";
315
- readonly "fileDropZone.choose": "Choose a file";
316
- readonly "fileDropZone.chooseMultiple": "Choose files";
317
- readonly "fileDropZone.hint": "or drop it here";
318
- readonly "fileDropZone.hintMultiple": "or drop them here";
319
- readonly "progress.label": "Progress";
320
- readonly "spinner.label": "Loading";
321
- readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
322
- readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
323
- readonly "errors.INVALID_PDF": "This file isn't a PDF, or it's too damaged to open.";
324
- readonly "errors.PASSWORD_REQUIRED": "This PDF is protected with a password.";
325
- readonly "errors.PROCESSING_FAILED": "Something went wrong while processing this PDF. Please try again.";
326
- readonly "errors.TOO_MANY_PAGES": "This document has {actual, number} pages, which is over the {maximum, number}-page limit.";
327
- 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.";
328
- readonly "errors.IMAGE_TOO_LARGE": "Some images are too large to show. They're kept unchanged in the document.";
329
- readonly "warnings.maxPages": {
330
- readonly $plural: "actual";
331
- } & {
332
- readonly one: "This document has {actual} page. Large documents may be slow.";
333
- readonly other: "This document has {actual} pages. Large documents may be slow.";
334
- };
335
- readonly "warnings.maxSessionSize": "The open documents use {actual, fileSize}. Clearing the undo history frees memory.";
336
- readonly "warnings.maxImagePixels": "Some images are very large and may be slow to show.";
337
338
  readonly "viewer.label": "Document";
338
339
  readonly "viewer.empty": "No document is open.";
339
340
  readonly "viewer.page": "Page {page} of {count}";
@@ -364,16 +365,72 @@ export declare const pdfEditorMessages: {
364
365
  readonly one: "Rotated {count} page.";
365
366
  readonly other: "Rotated {count} pages.";
366
367
  };
368
+ readonly "editor.deleted": {
369
+ readonly $plural: "count";
370
+ } & {
371
+ readonly one: "Deleted {count} page.";
372
+ readonly other: "Deleted {count} pages.";
373
+ };
374
+ readonly "editor.moved": {
375
+ readonly $plural: "count";
376
+ } & {
377
+ readonly one: "Moved {count} page to position {position}.";
378
+ readonly other: "Moved {count} pages to position {position}.";
379
+ };
380
+ readonly "editor.inserted": {
381
+ readonly $plural: "count";
382
+ } & {
383
+ readonly one: "Inserted {count} page after page {page}.";
384
+ readonly other: "Inserted {count} pages after page {page}.";
385
+ };
386
+ readonly "editor.historyTrimmed": "To make room for the inserted document, your earliest edits can no longer be undone.";
387
+ readonly "editor.saving": "Preparing the PDF…";
388
+ readonly "editor.cancelSave": "Cancel";
389
+ readonly "editor.saved": "Saved {name}.";
390
+ readonly "editor.ready": "The PDF is ready.";
391
+ readonly "editor.saveFailed": "The PDF couldn't be saved. Please try again.";
367
392
  readonly "toolbar.label": "PDF tools";
368
393
  readonly "toolbar.groups.file": "File";
369
394
  readonly "toolbar.groups.history": "History";
370
395
  readonly "toolbar.groups.pages": "Pages";
396
+ readonly "toolbar.groups.save": "Save";
371
397
  readonly "toolbar.groups.other": "More tools";
372
398
  readonly "tools.open": "Open a PDF";
373
399
  readonly "tools.undo": "Undo";
374
400
  readonly "tools.redo": "Redo";
375
401
  readonly "tools.rotate-left": "Rotate left";
376
402
  readonly "tools.rotate-right": "Rotate right";
403
+ readonly "tools.delete-pages": "Delete pages";
404
+ readonly "tools.download": "Download";
405
+ readonly "tools.insert-pages": "Insert pages";
406
+ readonly "tools.move-earlier": "Move earlier";
407
+ readonly "tools.move-later": "Move later";
408
+ readonly "dialog.close": "Close";
409
+ readonly "fileDropZone.choose": "Choose a file";
410
+ readonly "fileDropZone.chooseMultiple": "Choose files";
411
+ readonly "fileDropZone.hint": "or drop it here";
412
+ readonly "fileDropZone.hintMultiple": "or drop them here";
413
+ readonly "progress.label": "Progress";
414
+ readonly "spinner.label": "Loading";
415
+ readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
416
+ readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
417
+ readonly "errors.INVALID_PDF": "This file isn't a PDF, or it's too damaged to open.";
418
+ readonly "errors.PASSWORD_REQUIRED": "This PDF is protected with a password.";
419
+ readonly "errors.PROCESSING_FAILED": "Something went wrong while processing this PDF. Please try again.";
420
+ readonly "errors.TOO_MANY_PAGES": "This document has {actual, number} pages, which is over the {maximum, number}-page limit.";
421
+ 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.";
422
+ readonly "errors.IMAGE_TOO_LARGE": "Some images are too large to show. They're kept unchanged in the document.";
423
+ readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
424
+ readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't a PDF project.";
425
+ readonly "errors.UNSUPPORTED_FORMAT": "This project was saved by a newer version, or by another app. Update the app, and try again.";
426
+ readonly "warnings.maxPages": {
427
+ readonly $plural: "actual";
428
+ } & {
429
+ readonly one: "This document has {actual} page. Large documents may be slow.";
430
+ readonly other: "This document has {actual} pages. Large documents may be slow.";
431
+ };
432
+ readonly "warnings.maxSessionSize": "The open documents use {actual, fileSize}. Clearing the undo history frees memory.";
433
+ readonly "warnings.maxImagePixels": "Some images are very large and may be slow to show.";
377
434
  readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
378
435
  readonly "errors.ABORTED": "The operation was cancelled.";
379
436
  readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
@@ -449,6 +506,19 @@ export declare interface PdfEditorProps extends Omit<PdfSessionProviderProps, "c
449
506
  readonly file?: Blob | PdfBytes | null;
450
507
  /** Called after the document opens, changes or closes. */
451
508
  readonly onChange?: (change: PdfEditorChange) => void;
509
+ /**
510
+ * Receives the document the download tool built, instead of the browser
511
+ * downloading it, such as to store it in the host's own storage. The
512
+ * bytes are a new buffer the host owns. If it throws or rejects, the
513
+ * editor says the PDF couldn't be saved; its error is the host's to log.
514
+ */
515
+ readonly onExport?: (bytes: Uint8Array, info: PdfExportInfo) => void | Promise<void>;
516
+ /**
517
+ * Names the download tool's file. The result is cleaned as a file name
518
+ * and given a `.pdf` extension; the opened file's name by default, or
519
+ * `"document.pdf"` (docs/adr/0009).
520
+ */
521
+ readonly downloadName?: (info: PdfDownloadNameInfo) => string;
452
522
  /**
453
523
  * Which tools are present, by id, in order, such as
454
524
  * `["pdf.undo", "pdf.redo"]`. All of {@link pdfTools} by default. Their
@@ -548,13 +618,36 @@ declare class PdfError extends SdkError<PdfErrorCode> {
548
618
  * - `IMAGE_TOO_LARGE`: an image exceeds the `maxImagePixels` limit. It's
549
619
  * reported as a warning, because the image is skipped rather than the
550
620
  * document failing (ADR 0004).
621
+ * - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as
622
+ * one naming a page the plan doesn't have. `details.reason` says why, as
623
+ * a stable token (`PdfCommandRejection`, sdk-core ADR 0045).
624
+ * - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
625
+ * valid in its format. `details.reason` says why (`PdfDocumentRejection`).
626
+ * - `UNSUPPORTED_FORMAT`: a plan document of another format, or of a later
627
+ * version than this release reads, with `details.reason`
628
+ * `unknown-format` or `unknown-format-version`.
551
629
  *
552
630
  * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
553
631
  * value and the `unit`.
554
632
  *
555
633
  * @public
556
634
  */
557
- declare type PdfErrorCode = SdkCoreErrorCode | "INVALID_PDF" | "PASSWORD_REQUIRED" | "PROCESSING_FAILED" | "TOO_MANY_PAGES" | "SESSION_TOO_LARGE" | "IMAGE_TOO_LARGE";
635
+ 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";
636
+
637
+ /**
638
+ * What {@link PdfEditorProps.onExport} is given with the saved document.
639
+ *
640
+ * @public
641
+ */
642
+ export declare interface PdfExportInfo {
643
+ /**
644
+ * The name the browser download would have had: cleaned, ending in
645
+ * `.pdf`, and `"document.pdf"` when there's none.
646
+ */
647
+ readonly fileName: string;
648
+ /** The saved document's page count. */
649
+ readonly pageCount: number;
650
+ }
558
651
 
559
652
  /**
560
653
  * Options for {@link PdfSession.export}.
@@ -624,6 +717,10 @@ export declare const pdfIcons: Readonly<Record<string, IconComponent>>;
624
717
  /**
625
718
  * A drawn signature, or another image, placed on the page.
626
719
  *
720
+ * The session refuses it for now, with `INVALID_COMMAND` and
721
+ * `unsupported-annotation`: the portable format can't carry its image yet
722
+ * (docs/adr/0003). The editor's signature tool will bring it back.
723
+ *
627
724
  * @public
628
725
  */
629
726
  declare interface PdfImageAnnotation {
@@ -656,7 +753,7 @@ declare interface PdfImageCompression {
656
753
  *
657
754
  * @public
658
755
  */
659
- declare interface PdfInsertOptions extends PdfCallOptions {
756
+ declare interface PdfInsertOptions extends PdfOpenOptions {
660
757
  /** The position of the first inserted page. Defaults to the end. */
661
758
  readonly at?: number;
662
759
  /** Zero-based indexes of the pages to insert. Defaults to every page. */
@@ -768,134 +865,6 @@ declare interface PdfLink {
768
865
  readonly url: string;
769
866
  }
770
867
 
771
- /**
772
- * The type of {@link pdfMessages}, for typing a host's overrides with
773
- * `MessageOverrides<PdfMessageCatalogue>`.
774
- *
775
- * @public
776
- */
777
- declare type PdfMessageCatalogue = typeof pdfMessages;
778
-
779
- /**
780
- * The PDF SDK's English message catalogue: sdk-core's messages, and text for
781
- * every {@link PdfErrorCode} and every limit's warning. Pass it to
782
- * `createMessages` from `@hussmartinez/sdk-core`, with the host's locale and
783
- * overrides.
784
- *
785
- * Error text is looked up by code, with the error's `details` as
786
- * parameters, and never taken from `error.message` (ADR 0019).
787
- *
788
- * @example
789
- * ```ts
790
- * const messages = createMessages(pdfMessages, { locale: "en", overrides: props.messages });
791
- * messages.error(error); // "This document has 6,200 pages, which is over the 5,000-page limit."
792
- * messages.t("warnings.maxPages", { actual: 1_200 });
793
- * ```
794
- *
795
- * @public
796
- */
797
- declare const pdfMessages: {
798
- readonly "errors.INVALID_PDF": "This file isn't a PDF, or it's too damaged to open.";
799
- readonly "errors.PASSWORD_REQUIRED": "This PDF is protected with a password.";
800
- readonly "errors.PROCESSING_FAILED": "Something went wrong while processing this PDF. Please try again.";
801
- readonly "errors.TOO_MANY_PAGES": "This document has {actual, number} pages, which is over the {maximum, number}-page limit.";
802
- 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.";
803
- readonly "errors.IMAGE_TOO_LARGE": "Some images are too large to show. They're kept unchanged in the document.";
804
- readonly "warnings.maxPages": {
805
- readonly $plural: "actual";
806
- } & {
807
- readonly one: "This document has {actual} page. Large documents may be slow.";
808
- readonly other: "This document has {actual} pages. Large documents may be slow.";
809
- };
810
- readonly "warnings.maxSessionSize": "The open documents use {actual, fileSize}. Clearing the undo history frees memory.";
811
- readonly "warnings.maxImagePixels": "Some images are very large and may be slow to show.";
812
- readonly "viewer.label": "Document";
813
- readonly "viewer.empty": "No document is open.";
814
- readonly "viewer.page": "Page {page} of {count}";
815
- readonly "viewer.webLink": "Link to {destination}, opens in a new tab";
816
- readonly "viewer.emailLink": "Email {destination}";
817
- readonly "thumbnails.label": "Pages";
818
- readonly "thumbnails.page": "Page {page} of {count}";
819
- readonly "thumbnails.number": "{page}";
820
- readonly "editor.label": "PDF editor";
821
- readonly "editor.start.title": "Open a PDF to get started";
822
- readonly "editor.start.retryTitle": "Try another PDF";
823
- readonly "editor.start.choose": "Choose a PDF";
824
- readonly "editor.start.retry": "Choose another PDF";
825
- readonly "editor.start.hint": "Or drop one here. Your file stays on this device and is never uploaded.";
826
- readonly "editor.opening": "Opening the PDF…";
827
- readonly "editor.opened": {
828
- readonly $plural: "count";
829
- } & {
830
- readonly one: "Opened a PDF with {count} page.";
831
- readonly other: "Opened a PDF with {count} pages.";
832
- };
833
- readonly "editor.closed": "The PDF was closed.";
834
- readonly "editor.undone": "Undone.";
835
- readonly "editor.redone": "Redone.";
836
- readonly "editor.rotated": {
837
- readonly $plural: "count";
838
- } & {
839
- readonly one: "Rotated {count} page.";
840
- readonly other: "Rotated {count} pages.";
841
- };
842
- readonly "toolbar.label": "PDF tools";
843
- readonly "toolbar.groups.file": "File";
844
- readonly "toolbar.groups.history": "History";
845
- readonly "toolbar.groups.pages": "Pages";
846
- readonly "toolbar.groups.other": "More tools";
847
- readonly "tools.open": "Open a PDF";
848
- readonly "tools.undo": "Undo";
849
- readonly "tools.redo": "Redo";
850
- readonly "tools.rotate-left": "Rotate left";
851
- readonly "tools.rotate-right": "Rotate right";
852
- readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
853
- readonly "errors.ABORTED": "The operation was cancelled.";
854
- readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
855
- readonly "errors.WORKER_START_FAILED": "The file processor couldn't start. Reload the page and try again.";
856
- readonly "errors.WORKER_PROTOCOL_MISMATCH": "The file processor is out of date. Reload the page to update it.";
857
- readonly "errors.WORKER_CRASHED": "The file processor stopped unexpectedly. Please try again.";
858
- readonly "errors.WORKER_TERMINATED": "The operation was stopped before it finished. Please try again.";
859
- readonly "errors.WORKER_METHOD_NOT_FOUND": "This operation isn't available. Reload the page and try again.";
860
- readonly "errors.WORKER_DATA_NOT_CLONEABLE": "Something went wrong while processing the file. Please try again.";
861
- readonly "errors.UNSUPPORTED_ENVIRONMENT": "This browser doesn't support a feature this tool needs. Update your browser, or try another one.";
862
- readonly "errors.FILE_TOO_LARGE": "This file is {actual, fileSize}, which is over the {maximum, fileSize} limit.";
863
- readonly "errors.TOO_MANY_FILES": {
864
- readonly $plural: "maximum";
865
- } & {
866
- readonly one: "You can add {maximum} file at a time.";
867
- readonly other: "You can add up to {maximum} files at a time.";
868
- };
869
- readonly "errors.DECODED_SIZE_TOO_LARGE": "This file expands to more than {maximum, fileSize} when opened, which is over the limit.";
870
- readonly "errors.PROCESSING_TIME_EXCEEDED": "Processing this file took too long and was stopped.";
871
- readonly "warnings.maxFileSize": "This file is {actual, fileSize}. Large files may be slow to process.";
872
- readonly "warnings.maxFiles": "Adding {actual} files at once may be slow.";
873
- readonly "warnings.maxDecodedSize": "This file is very large once opened and may be slow to process.";
874
- readonly "warnings.maxProcessingTime": "This is taking longer than usual.";
875
- readonly "keys.control": "Ctrl";
876
- readonly "keys.alt": "Alt";
877
- readonly "keys.shift": "Shift";
878
- readonly "keys.meta": "Meta";
879
- readonly "keys.apple.control": "\u2303";
880
- readonly "keys.apple.alt": "\u2325";
881
- readonly "keys.apple.shift": "\u21E7";
882
- readonly "keys.apple.meta": "\u2318";
883
- readonly "keys.space": "Space";
884
- readonly "keys.enter": "Enter";
885
- readonly "keys.escape": "Esc";
886
- readonly "keys.tab": "Tab";
887
- readonly "keys.delete": "Delete";
888
- readonly "keys.backspace": "Backspace";
889
- readonly "keys.arrowUp": "\u2191";
890
- readonly "keys.arrowDown": "\u2193";
891
- readonly "keys.arrowLeft": "\u2190";
892
- readonly "keys.arrowRight": "\u2192";
893
- readonly "keys.home": "Home";
894
- readonly "keys.end": "End";
895
- readonly "keys.pageUp": "Page Up";
896
- readonly "keys.pageDown": "Page Down";
897
- };
898
-
899
868
  /**
900
869
  * Moves pages, keeping their relative order, so that the first of them ends
901
870
  * up at position `to` of the resulting plan.
@@ -909,6 +878,19 @@ declare interface PdfMovePagesCommand {
909
878
  readonly to: number;
910
879
  }
911
880
 
881
+ /**
882
+ * Options for {@link PdfSession.open}.
883
+ *
884
+ * @public
885
+ */
886
+ declare interface PdfOpenOptions extends PdfCallOptions {
887
+ /**
888
+ * The file's name, for bytes or a `Blob` that isn't a `File`. It wins over
889
+ * `File.name`, and is cleaned before it's kept (docs/adr/0009).
890
+ */
891
+ readonly name?: string;
892
+ }
893
+
912
894
  /**
913
895
  * Facts about one page of a source document.
914
896
  *
@@ -1074,7 +1056,10 @@ declare interface PdfRotatePagesCommand {
1074
1056
  readonly type: "pdf.rotatePages";
1075
1057
  /** The keys of the pages to rotate. */
1076
1058
  readonly pages: readonly string[];
1077
- /** Degrees, clockwise, in multiples of 90. Negative turns anticlockwise. */
1059
+ /**
1060
+ * Degrees, clockwise, in multiples of 90 from -360 to 360. Negative turns
1061
+ * anticlockwise.
1062
+ */
1078
1063
  readonly angle: number;
1079
1064
  }
1080
1065
 
@@ -1104,7 +1089,7 @@ declare interface PdfSession {
1104
1089
  * Rejects with a `PdfError`, which the snapshot also holds; the current
1105
1090
  * document, if any, stays open.
1106
1091
  */
1107
- open(file: Blob | PdfBytes, options?: PdfCallOptions): Promise<void>;
1092
+ open(file: Blob | PdfBytes, options?: PdfOpenOptions): Promise<void>;
1108
1093
  /**
1109
1094
  * Inserts the pages of another document, as one undoable step. If the
1110
1095
  * documents held would then exceed `maxSessionSize`, the session first
@@ -1115,9 +1100,11 @@ declare interface PdfSession {
1115
1100
  */
1116
1101
  insert(file: Blob | PdfBytes, options?: PdfInsertOptions): Promise<void>;
1117
1102
  /**
1118
- * Runs one command, or several as one undoable step. Throws `TypeError`
1119
- * or `RangeError` for a command that doesn't fit the plan, and changes
1120
- * nothing then.
1103
+ * Runs one command, or several as one undoable step. Throws `PdfError`
1104
+ * with `INVALID_COMMAND` for a command that doesn't fit the plan, with a
1105
+ * `PdfCommandRejection` as `details.reason`, and changes nothing then.
1106
+ * Positions and sizes are snapped to millionths of the page
1107
+ * (`PDF_POSITION_GRID`).
1121
1108
  */
1122
1109
  execute(commands: PdfCommand | readonly PdfCommand[]): void;
1123
1110
  undo(): void;
@@ -1225,7 +1212,7 @@ export declare interface PdfSessionProviderProps {
1225
1212
  /** Anonymous usage events from a session the provider creates. */
1226
1213
  readonly onEvent?: (event: PdfSessionEvent) => void;
1227
1214
  /** Text overrides, typed against the English catalogue (ADR 0019). */
1228
- readonly messages?: MessageOverrides<PdfMessageCatalogue>;
1215
+ readonly messages?: MessageOverrides<PdfEditorMessageCatalogue>;
1229
1216
  /** The locale for numbers, sizes and plurals. Defaults to `"en"`. */
1230
1217
  readonly locale?: string;
1231
1218
  /** The components that use the session, such as `PdfViewer`. */
@@ -1267,7 +1254,9 @@ declare interface PdfSessionSnapshot {
1267
1254
  readonly historyTrimmed: boolean;
1268
1255
  /**
1269
1256
  * The keys of the selected pages, in plan order. Tools act on them, such as
1270
- * rotating the selection. View state: not undoable, and never in events.
1257
+ * rotating the selection. View state: not part of the plan and never in
1258
+ * events, but undo and redo bring back the selection and current page
1259
+ * that went with each step (docs/adr/0008).
1271
1260
  */
1272
1261
  readonly selection: readonly string[];
1273
1262
  /** The key of the page the user is looking at, if a document is open. */
@@ -1320,6 +1309,13 @@ declare interface PdfSourceInfo {
1320
1309
  readonly pageCount: number;
1321
1310
  /** The size of its bytes. */
1322
1311
  readonly byteLength: number;
1312
+ /**
1313
+ * The file's name, from `File.name` or the `name` option, cleaned as
1314
+ * docs/adr/0009 describes: one path segment, without control or
1315
+ * bidirectional formatting characters, at most 128 code points. Absent
1316
+ * when there was none. Show it only as text; it never reaches `onEvent`.
1317
+ */
1318
+ readonly name?: string;
1323
1319
  }
1324
1320
 
1325
1321
  /**
@@ -1390,7 +1386,9 @@ declare interface PdfTextItem {
1390
1386
  * Keyboard: the arrow keys, Home and End move to a page, select it and show
1391
1387
  * it; with Shift they extend the selection; with Ctrl or ⌘ they move without
1392
1388
  * selecting, and Space then adds or removes the page. Ctrl or ⌘ + A selects
1393
- * every page, and Escape keeps only the focused one. With a pointer: click,
1389
+ * every page, and Escape keeps only the focused one. Delete and Backspace,
1390
+ * and Alt or Option with ↑ and ↓, run `onDelete` and `onMove` when given.
1391
+ * With a pointer: click,
1394
1392
  * Ctrl or ⌘ + click, and Shift + click.
1395
1393
  *
1396
1394
  * @public
@@ -1418,6 +1416,16 @@ export declare interface PdfThumbnailsProps {
1418
1416
  readonly unstyled?: boolean;
1419
1417
  /** How many thumbnails are drawn at once. Defaults to 2. */
1420
1418
  readonly concurrency?: number;
1419
+ /**
1420
+ * Runs when the user presses Delete or Backspace in the list, such as the
1421
+ * editor's delete tool. Without it, those keys do nothing here.
1422
+ */
1423
+ readonly onDelete?: () => void;
1424
+ /**
1425
+ * Runs when the user presses Alt+↑ or Alt+↓ (Option on macOS) in the list,
1426
+ * such as the editor's move tools. Without it, those keys do nothing here.
1427
+ */
1428
+ readonly onMove?: (direction: "earlier" | "later") => void;
1421
1429
  }
1422
1430
 
1423
1431
  /**
@@ -1452,6 +1460,10 @@ export declare interface PdfToolbarProps {
1452
1460
  readonly context: PdfToolContext;
1453
1461
  /** Icon components by name. */
1454
1462
  readonly icons: Readonly<Record<string, IconComponent>>;
1463
+ /** Whether the editor is saving, which tools read as `saving`. */
1464
+ readonly saving?: boolean;
1465
+ /** Whether the editor is inserting a document, which tools read as `inserting`. */
1466
+ readonly inserting?: boolean;
1455
1467
  /** Runs a tool. Defaults to running it against `context`. */
1456
1468
  readonly onRun?: (tool: PdfTool) => void;
1457
1469
  /** Extra classes on the root. */
@@ -1468,6 +1480,16 @@ export declare interface PdfToolContext {
1468
1480
  readonly session: PdfSession;
1469
1481
  /** Asks the user for a PDF and opens it, as the open tool does. */
1470
1482
  readonly chooseFile: () => void;
1483
+ /**
1484
+ * Builds the document and saves it, as the download tool does
1485
+ * (docs/adr/0009). Absent outside the editor.
1486
+ */
1487
+ readonly save?: () => void;
1488
+ /**
1489
+ * Asks the user for another PDF and inserts its pages after the current
1490
+ * page, as the insert tool does (docs/adr/0008). Absent outside the editor.
1491
+ */
1492
+ readonly chooseInsertFile?: () => void;
1471
1493
  }
1472
1494
 
1473
1495
  /**
@@ -1485,6 +1507,10 @@ export declare const pdfTools: readonly PdfTool[];
1485
1507
  export declare interface PdfToolState {
1486
1508
  /** The session's current snapshot. */
1487
1509
  readonly snapshot: PdfSessionSnapshot;
1510
+ /** Whether the editor is saving the document. Absent outside the editor. */
1511
+ readonly saving?: boolean;
1512
+ /** Whether the editor is inserting another document. Absent outside the editor. */
1513
+ readonly inserting?: boolean;
1488
1514
  }
1489
1515
 
1490
1516
  /**
@@ -1574,7 +1600,7 @@ export declare function usePdfDocument(): PdfSessionSnapshot;
1574
1600
  *
1575
1601
  * @public
1576
1602
  */
1577
- export declare function usePdfMessages(): Messages<PdfMessageCatalogue>;
1603
+ export declare function usePdfMessages(): Messages<PdfEditorMessageCatalogue>;
1578
1604
 
1579
1605
  /**
1580
1606
  * The session of the nearest `PdfSessionProvider`, to open documents, run