@hussmartinez/pdf-sdk 0.1.0 → 0.3.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-CxoVSxEZ.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-Dy5JQHXJ.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
@@ -11,12 +11,16 @@
11
11
 
12
12
  import { FilePolicyOverrides } from '@hussmartinez/sdk-core';
13
13
  import { ForwardRefExoticComponent } from 'react';
14
+ import { IconComponent } from '@hussmartinez/ui/react';
14
15
  import { MessageOverrides } from '@hussmartinez/sdk-core';
15
16
  import type { Messages } from '@hussmartinez/sdk-core';
16
17
  import { ReactNode } from 'react';
17
18
  import { RefAttributes } from 'react';
18
19
  import { SdkCoreErrorCode } from '@hussmartinez/sdk-core';
19
20
  import { SdkError } from '@hussmartinez/sdk-core';
21
+ import type { ShortcutRegistry } from '@hussmartinez/sdk-core';
22
+ import type { Tool } from '@hussmartinez/sdk-core';
23
+ import type { ToolRegistry } from '@hussmartinez/sdk-core';
20
24
 
21
25
  /**
22
26
  * Adds an annotation to a page.
@@ -140,7 +144,7 @@ declare interface PdfCallOptions {
140
144
  }
141
145
 
142
146
  /**
143
- * A colour as `#rrggbb`.
147
+ * A colour as `#rrggbb`, in lowercase.
144
148
  *
145
149
  * @public
146
150
  */
@@ -229,6 +233,13 @@ declare interface PdfDocumentHandle {
229
233
  * closing are announced, and focus moves to the document once it opens, or
230
234
  * to the button to try again if it couldn't.
231
235
  *
236
+ * Its toolbar is built from {@link pdfTools}: choose them with `tools` and
237
+ * arrange them with `toolbar`. Each tool's shortcut works while focus is in
238
+ * the editor, and undoing, redoing and rotating are announced.
239
+ *
240
+ * Load `@hussmartinez/ui/styles.css` once, before the SDK's stylesheet: the
241
+ * toolbar's focus rings and target sizes are in it (sdk-core ADR 0036).
242
+ *
232
243
  * Give the editor a bounded height, such as a grid row or a fixed height:
233
244
  * its viewer and thumbnails scroll within it.
234
245
  *
@@ -279,6 +290,140 @@ export declare interface PdfEditorHandle {
279
290
  close(): Promise<void>;
280
291
  }
281
292
 
293
+ /**
294
+ * The type of {@link pdfEditorMessages}, for typing the editor's `messages`
295
+ * overrides with `MessageOverrides<PdfEditorMessageCatalogue>`.
296
+ *
297
+ * @public
298
+ */
299
+ export declare type PdfEditorMessageCatalogue = typeof pdfEditorMessages;
300
+
301
+ /**
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.
307
+ *
308
+ * It's defined in the React entry, so the headless `.` entry and its
309
+ * `pdfMessages` don't carry ui's text.
310
+ *
311
+ * @public
312
+ */
313
+ 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 "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
330
+ readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't a PDF project.";
331
+ readonly "errors.UNSUPPORTED_FORMAT": "This project was saved by a newer version, or by another app. Update the app, and try again.";
332
+ readonly "warnings.maxPages": {
333
+ readonly $plural: "actual";
334
+ } & {
335
+ readonly one: "This document has {actual} page. Large documents may be slow.";
336
+ readonly other: "This document has {actual} pages. Large documents may be slow.";
337
+ };
338
+ readonly "warnings.maxSessionSize": "The open documents use {actual, fileSize}. Clearing the undo history frees memory.";
339
+ readonly "warnings.maxImagePixels": "Some images are very large and may be slow to show.";
340
+ readonly "viewer.label": "Document";
341
+ readonly "viewer.empty": "No document is open.";
342
+ readonly "viewer.page": "Page {page} of {count}";
343
+ readonly "viewer.webLink": "Link to {destination}, opens in a new tab";
344
+ readonly "viewer.emailLink": "Email {destination}";
345
+ readonly "thumbnails.label": "Pages";
346
+ readonly "thumbnails.page": "Page {page} of {count}";
347
+ readonly "thumbnails.number": "{page}";
348
+ readonly "editor.label": "PDF editor";
349
+ readonly "editor.start.title": "Open a PDF to get started";
350
+ readonly "editor.start.retryTitle": "Try another PDF";
351
+ readonly "editor.start.choose": "Choose a PDF";
352
+ readonly "editor.start.retry": "Choose another PDF";
353
+ readonly "editor.start.hint": "Or drop one here. Your file stays on this device and is never uploaded.";
354
+ readonly "editor.opening": "Opening the PDF…";
355
+ readonly "editor.opened": {
356
+ readonly $plural: "count";
357
+ } & {
358
+ readonly one: "Opened a PDF with {count} page.";
359
+ readonly other: "Opened a PDF with {count} pages.";
360
+ };
361
+ readonly "editor.closed": "The PDF was closed.";
362
+ readonly "editor.undone": "Undone.";
363
+ readonly "editor.redone": "Redone.";
364
+ readonly "editor.rotated": {
365
+ readonly $plural: "count";
366
+ } & {
367
+ readonly one: "Rotated {count} page.";
368
+ readonly other: "Rotated {count} pages.";
369
+ };
370
+ readonly "toolbar.label": "PDF tools";
371
+ readonly "toolbar.groups.file": "File";
372
+ readonly "toolbar.groups.history": "History";
373
+ readonly "toolbar.groups.pages": "Pages";
374
+ readonly "toolbar.groups.other": "More tools";
375
+ readonly "tools.open": "Open a PDF";
376
+ readonly "tools.undo": "Undo";
377
+ readonly "tools.redo": "Redo";
378
+ readonly "tools.rotate-left": "Rotate left";
379
+ readonly "tools.rotate-right": "Rotate right";
380
+ readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
381
+ readonly "errors.ABORTED": "The operation was cancelled.";
382
+ readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
383
+ readonly "errors.WORKER_START_FAILED": "The file processor couldn't start. Reload the page and try again.";
384
+ readonly "errors.WORKER_PROTOCOL_MISMATCH": "The file processor is out of date. Reload the page to update it.";
385
+ readonly "errors.WORKER_CRASHED": "The file processor stopped unexpectedly. Please try again.";
386
+ readonly "errors.WORKER_TERMINATED": "The operation was stopped before it finished. Please try again.";
387
+ readonly "errors.WORKER_METHOD_NOT_FOUND": "This operation isn't available. Reload the page and try again.";
388
+ readonly "errors.WORKER_DATA_NOT_CLONEABLE": "Something went wrong while processing the file. Please try again.";
389
+ readonly "errors.UNSUPPORTED_ENVIRONMENT": "This browser doesn't support a feature this tool needs. Update your browser, or try another one.";
390
+ readonly "errors.FILE_TOO_LARGE": "This file is {actual, fileSize}, which is over the {maximum, fileSize} limit.";
391
+ readonly "errors.TOO_MANY_FILES": {
392
+ readonly $plural: "maximum";
393
+ } & {
394
+ readonly one: "You can add {maximum} file at a time.";
395
+ readonly other: "You can add up to {maximum} files at a time.";
396
+ };
397
+ readonly "errors.DECODED_SIZE_TOO_LARGE": "This file expands to more than {maximum, fileSize} when opened, which is over the limit.";
398
+ readonly "errors.PROCESSING_TIME_EXCEEDED": "Processing this file took too long and was stopped.";
399
+ readonly "warnings.maxFileSize": "This file is {actual, fileSize}. Large files may be slow to process.";
400
+ readonly "warnings.maxFiles": "Adding {actual} files at once may be slow.";
401
+ readonly "warnings.maxDecodedSize": "This file is very large once opened and may be slow to process.";
402
+ readonly "warnings.maxProcessingTime": "This is taking longer than usual.";
403
+ readonly "keys.control": "Ctrl";
404
+ readonly "keys.alt": "Alt";
405
+ readonly "keys.shift": "Shift";
406
+ readonly "keys.meta": "Meta";
407
+ readonly "keys.apple.control": "\u2303";
408
+ readonly "keys.apple.alt": "\u2325";
409
+ readonly "keys.apple.shift": "\u21E7";
410
+ readonly "keys.apple.meta": "\u2318";
411
+ readonly "keys.space": "Space";
412
+ readonly "keys.enter": "Enter";
413
+ readonly "keys.escape": "Esc";
414
+ readonly "keys.tab": "Tab";
415
+ readonly "keys.delete": "Delete";
416
+ readonly "keys.backspace": "Backspace";
417
+ readonly "keys.arrowUp": "\u2191";
418
+ readonly "keys.arrowDown": "\u2193";
419
+ readonly "keys.arrowLeft": "\u2190";
420
+ readonly "keys.arrowRight": "\u2192";
421
+ readonly "keys.home": "Home";
422
+ readonly "keys.end": "End";
423
+ readonly "keys.pageUp": "Page Up";
424
+ readonly "keys.pageDown": "Page Down";
425
+ };
426
+
282
427
  /**
283
428
  * The parts of `PdfEditor` that take extra classes through `classNames`.
284
429
  *
@@ -293,7 +438,12 @@ export declare type PdfEditorPart = "root" | "header" | "toolbar" | "body" | "si
293
438
  *
294
439
  * @public
295
440
  */
296
- export declare interface PdfEditorProps extends Omit<PdfSessionProviderProps, "children"> {
441
+ export declare interface PdfEditorProps extends Omit<PdfSessionProviderProps, "children" | "messages"> {
442
+ /**
443
+ * Text overrides, typed against the editor's English catalogue, which
444
+ * includes ui's text for the ui components it renders (sdk-core ADR 0046).
445
+ */
446
+ readonly messages?: MessageOverrides<PdfEditorMessageCatalogue>;
297
447
  /**
298
448
  * A document to open. The editor opens it on mount, and again whenever a
299
449
  * different file or buffer is passed; `null` closes the document. Files
@@ -302,6 +452,21 @@ export declare interface PdfEditorProps extends Omit<PdfSessionProviderProps, "c
302
452
  readonly file?: Blob | PdfBytes | null;
303
453
  /** Called after the document opens, changes or closes. */
304
454
  readonly onChange?: (change: PdfEditorChange) => void;
455
+ /**
456
+ * Which tools are present, by id, in order, such as
457
+ * `["pdf.undo", "pdf.redo"]`. All of {@link pdfTools} by default. Their
458
+ * shortcuts work only while they're present.
459
+ */
460
+ readonly tools?: readonly string[];
461
+ /**
462
+ * The toolbar's groups, as tool ids, such as
463
+ * `[["pdf.undo", "pdf.redo"], ["pdf.rotate-left", "pdf.rotate-right"]]`.
464
+ * Defaults to the present tools in their usual groups; `[]` hides the
465
+ * toolbar, keeping the shortcuts. An unknown id throws.
466
+ */
467
+ readonly toolbar?: readonly (readonly string[])[];
468
+ /** Icon components by name, over the SDK's own from ui. */
469
+ readonly icons?: Readonly<Record<string, IconComponent>>;
305
470
  /** Extra classes on the root. */
306
471
  readonly className?: string;
307
472
  /** Extra classes on each part. */
@@ -386,13 +551,21 @@ declare class PdfError extends SdkError<PdfErrorCode> {
386
551
  * - `IMAGE_TOO_LARGE`: an image exceeds the `maxImagePixels` limit. It's
387
552
  * reported as a warning, because the image is skipped rather than the
388
553
  * document failing (ADR 0004).
554
+ * - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as
555
+ * one naming a page the plan doesn't have. `details.reason` says why, as
556
+ * a stable token (`PdfCommandRejection`, sdk-core ADR 0045).
557
+ * - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
558
+ * valid in its format. `details.reason` says why (`PdfDocumentRejection`).
559
+ * - `UNSUPPORTED_FORMAT`: a plan document of another format, or of a later
560
+ * version than this release reads, with `details.reason`
561
+ * `unknown-format` or `unknown-format-version`.
389
562
  *
390
563
  * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
391
564
  * value and the `unit`.
392
565
  *
393
566
  * @public
394
567
  */
395
- declare type PdfErrorCode = SdkCoreErrorCode | "INVALID_PDF" | "PASSWORD_REQUIRED" | "PROCESSING_FAILED" | "TOO_MANY_PAGES" | "SESSION_TOO_LARGE" | "IMAGE_TOO_LARGE";
568
+ 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";
396
569
 
397
570
  /**
398
571
  * Options for {@link PdfSession.export}.
@@ -451,9 +624,21 @@ declare interface PdfFormField {
451
624
  readonly readOnly: boolean;
452
625
  }
453
626
 
627
+ /**
628
+ * The components of the icons the editor's tools name, from ui's set
629
+ * (sdk-core ADR 0030). A host's `icons` prop overrides any of them.
630
+ *
631
+ * @public
632
+ */
633
+ export declare const pdfIcons: Readonly<Record<string, IconComponent>>;
634
+
454
635
  /**
455
636
  * A drawn signature, or another image, placed on the page.
456
637
  *
638
+ * The session refuses it for now, with `INVALID_COMMAND` and
639
+ * `unsupported-annotation`: the portable format can't carry its image yet
640
+ * (docs/adr/0003). The editor's signature tool will bring it back.
641
+ *
457
642
  * @public
458
643
  */
459
644
  declare interface PdfImageAnnotation {
@@ -631,6 +816,9 @@ declare const pdfMessages: {
631
816
  readonly "errors.TOO_MANY_PAGES": "This document has {actual, number} pages, which is over the {maximum, number}-page limit.";
632
817
  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.";
633
818
  readonly "errors.IMAGE_TOO_LARGE": "Some images are too large to show. They're kept unchanged in the document.";
819
+ readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
820
+ readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't a PDF project.";
821
+ readonly "errors.UNSUPPORTED_FORMAT": "This project was saved by a newer version, or by another app. Update the app, and try again.";
634
822
  readonly "warnings.maxPages": {
635
823
  readonly $plural: "actual";
636
824
  } & {
@@ -661,6 +849,24 @@ declare const pdfMessages: {
661
849
  readonly other: "Opened a PDF with {count} pages.";
662
850
  };
663
851
  readonly "editor.closed": "The PDF was closed.";
852
+ readonly "editor.undone": "Undone.";
853
+ readonly "editor.redone": "Redone.";
854
+ readonly "editor.rotated": {
855
+ readonly $plural: "count";
856
+ } & {
857
+ readonly one: "Rotated {count} page.";
858
+ readonly other: "Rotated {count} pages.";
859
+ };
860
+ readonly "toolbar.label": "PDF tools";
861
+ readonly "toolbar.groups.file": "File";
862
+ readonly "toolbar.groups.history": "History";
863
+ readonly "toolbar.groups.pages": "Pages";
864
+ readonly "toolbar.groups.other": "More tools";
865
+ readonly "tools.open": "Open a PDF";
866
+ readonly "tools.undo": "Undo";
867
+ readonly "tools.redo": "Redo";
868
+ readonly "tools.rotate-left": "Rotate left";
869
+ readonly "tools.rotate-right": "Rotate right";
664
870
  readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
665
871
  readonly "errors.ABORTED": "The operation was cancelled.";
666
872
  readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
@@ -886,7 +1092,10 @@ declare interface PdfRotatePagesCommand {
886
1092
  readonly type: "pdf.rotatePages";
887
1093
  /** The keys of the pages to rotate. */
888
1094
  readonly pages: readonly string[];
889
- /** Degrees, clockwise, in multiples of 90. Negative turns anticlockwise. */
1095
+ /**
1096
+ * Degrees, clockwise, in multiples of 90 from -360 to 360. Negative turns
1097
+ * anticlockwise.
1098
+ */
890
1099
  readonly angle: number;
891
1100
  }
892
1101
 
@@ -927,9 +1136,11 @@ declare interface PdfSession {
927
1136
  */
928
1137
  insert(file: Blob | PdfBytes, options?: PdfInsertOptions): Promise<void>;
929
1138
  /**
930
- * Runs one command, or several as one undoable step. Throws `TypeError`
931
- * or `RangeError` for a command that doesn't fit the plan, and changes
932
- * nothing then.
1139
+ * Runs one command, or several as one undoable step. Throws `PdfError`
1140
+ * with `INVALID_COMMAND` for a command that doesn't fit the plan, with a
1141
+ * `PdfCommandRejection` as `details.reason`, and changes nothing then.
1142
+ * Positions and sizes are snapped to millionths of the page
1143
+ * (`PDF_POSITION_GRID`).
933
1144
  */
934
1145
  execute(commands: PdfCommand | readonly PdfCommand[]): void;
935
1146
  undo(): void;
@@ -1232,6 +1443,73 @@ export declare interface PdfThumbnailsProps {
1232
1443
  readonly concurrency?: number;
1233
1444
  }
1234
1445
 
1446
+ /**
1447
+ * One of the editor's tools (sdk-core ADR 0009 and ADR 0030): headless, so
1448
+ * the React editor and the custom element share it.
1449
+ *
1450
+ * @public
1451
+ */
1452
+ export declare type PdfTool = Tool<PdfToolState, PdfToolContext, undefined>;
1453
+
1454
+ /**
1455
+ * The editor's toolbar: ui's `Toolbar`, one labelled group per toolbar group
1456
+ * of the registry and one button per tool, disabled when the tool can't
1457
+ * run, with the tool's shortcuts as `aria-keyshortcuts`. Arrow keys move
1458
+ * between the buttons, as ui's toolbar does, so it's one tab stop.
1459
+ *
1460
+ * @public
1461
+ */
1462
+ export declare function PdfToolbar(props: PdfToolbarProps): ReactNode;
1463
+
1464
+ /**
1465
+ * Props for {@link PdfToolbar}.
1466
+ *
1467
+ * @public
1468
+ */
1469
+ export declare interface PdfToolbarProps {
1470
+ /** The editor's tools, from `createToolRegistry`. */
1471
+ readonly registry: ToolRegistry<PdfTool>;
1472
+ /** The editor's shortcuts, for each button's `aria-keyshortcuts`. */
1473
+ readonly shortcuts?: ShortcutRegistry;
1474
+ /** What the tools run against. */
1475
+ readonly context: PdfToolContext;
1476
+ /** Icon components by name. */
1477
+ readonly icons: Readonly<Record<string, IconComponent>>;
1478
+ /** Runs a tool. Defaults to running it against `context`. */
1479
+ readonly onRun?: (tool: PdfTool) => void;
1480
+ /** Extra classes on the root. */
1481
+ readonly className?: string;
1482
+ }
1483
+
1484
+ /**
1485
+ * What a tool runs against.
1486
+ *
1487
+ * @public
1488
+ */
1489
+ export declare interface PdfToolContext {
1490
+ /** The session the tool edits. */
1491
+ readonly session: PdfSession;
1492
+ /** Asks the user for a PDF and opens it, as the open tool does. */
1493
+ readonly chooseFile: () => void;
1494
+ }
1495
+
1496
+ /**
1497
+ * Every tool the editor knows, in their default order (sdk-core ADR 0030).
1498
+ *
1499
+ * @public
1500
+ */
1501
+ export declare const pdfTools: readonly PdfTool[];
1502
+
1503
+ /**
1504
+ * What a tool reads to decide whether it's available, enabled or active.
1505
+ *
1506
+ * @public
1507
+ */
1508
+ export declare interface PdfToolState {
1509
+ /** The session's current snapshot. */
1510
+ readonly snapshot: PdfSessionSnapshot;
1511
+ }
1512
+
1235
1513
  /**
1236
1514
  * Options for calls that take PDF bytes.
1237
1515
  *