react-smart-copy 1.2.0 → 1.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 +83 -16
- package/dist/capture.cjs.map +1 -1
- package/dist/capture.js.map +1 -1
- package/dist/core.cjs +94 -19
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.cts +149 -74
- package/dist/core.d.ts +149 -74
- package/dist/core.js +94 -20
- package/dist/core.js.map +1 -1
- package/dist/index.cjs +176 -27
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +181 -79
- package/dist/index.d.ts +181 -79
- package/dist/index.js +176 -28
- package/dist/index.js.map +1 -1
- package/package.json +7 -7
package/dist/core.d.cts
CHANGED
|
@@ -1,3 +1,95 @@
|
|
|
1
|
+
//#region src/core/paste-reader.d.ts
|
|
2
|
+
/** Friendly names for the common cases. */
|
|
3
|
+
type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
4
|
+
/**
|
|
5
|
+
* What a paste may contain, in any order: a shorthand, an exact MIME type
|
|
6
|
+
* (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
|
|
7
|
+
* `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
|
|
8
|
+
*/
|
|
9
|
+
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
10
|
+
interface PasteLimits {
|
|
11
|
+
/**
|
|
12
|
+
* Total size cap across all accepted items, in UTF-8 bytes. Strings are measured as
|
|
13
|
+
* they would be encoded, matching `Blob.size`, so every paste path counts the same way.
|
|
14
|
+
* Default 32 MiB.
|
|
15
|
+
*/
|
|
16
|
+
readonly maxBytes?: number;
|
|
17
|
+
/** Max number of accepted items (types + files). Default 32. */
|
|
18
|
+
readonly maxItems?: number;
|
|
19
|
+
}
|
|
20
|
+
interface PasteReadOptions extends PasteLimits {
|
|
21
|
+
/** Default `['text']` (plain text only): the safest choice. */
|
|
22
|
+
readonly accept?: readonly PasteAccept[];
|
|
23
|
+
}
|
|
24
|
+
/** Validated, normalised options that adapters receive. */
|
|
25
|
+
interface ResolvedPasteReadOptions {
|
|
26
|
+
/** Normalised patterns: `type/subtype`, `type/*` or `*\/*`. */
|
|
27
|
+
readonly accept: readonly string[];
|
|
28
|
+
readonly maxBytes: number;
|
|
29
|
+
readonly maxItems: number;
|
|
30
|
+
}
|
|
31
|
+
/** Where the content came from: a Clipboard API read, a `paste` event, or a drag-and-drop `drop` event. */
|
|
32
|
+
type PasteSource = 'clipboard' | 'event' | 'drop';
|
|
33
|
+
/** One accepted clipboard entry. Textual types are decoded to `string`, everything else stays a `Blob`. */
|
|
34
|
+
interface PasteItem {
|
|
35
|
+
readonly type: string;
|
|
36
|
+
readonly data: string | Blob;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Everything the paste produced. Treat all of it as untrusted user input:
|
|
40
|
+
* in particular never inject `html` into the DOM without sanitising it.
|
|
41
|
+
*/
|
|
42
|
+
interface PasteResult {
|
|
43
|
+
readonly source: PasteSource;
|
|
44
|
+
/** Every accepted entry, in clipboard order. */
|
|
45
|
+
readonly items: readonly PasteItem[];
|
|
46
|
+
/** `text/plain`, when accepted and present. */
|
|
47
|
+
readonly text: string | null;
|
|
48
|
+
/** `text/html`, when accepted and present. UNTRUSTED markup: sanitise before rendering. */
|
|
49
|
+
readonly html: string | null;
|
|
50
|
+
/** Raster images, verified from their bytes (PNG, JPEG, GIF, WebP, AVIF, BMP), typed accordingly. */
|
|
51
|
+
readonly images: readonly Blob[];
|
|
52
|
+
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
53
|
+
readonly files: readonly File[];
|
|
54
|
+
/**
|
|
55
|
+
* The entries of `files` that are also in `images`: verified image files, keeping their
|
|
56
|
+
* names, ready for `FormData`. Derived by the paste machine, so it is always consistent.
|
|
57
|
+
*/
|
|
58
|
+
readonly imageFiles: readonly File[];
|
|
59
|
+
}
|
|
60
|
+
/** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
|
|
61
|
+
type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
|
|
62
|
+
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
63
|
+
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
64
|
+
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
65
|
+
/** Validates and normalises paste options. Throws a classified `invalid-payload` failure. */
|
|
66
|
+
export declare function resolvePasteReadOptions(options?: PasteReadOptions): ResolvedPasteReadOptions;
|
|
67
|
+
/** Structural view of a `DataTransferItem`: only what is readable while dragging. */
|
|
68
|
+
interface DataTransferItemLike {
|
|
69
|
+
/** `'string'` or `'file'`. */
|
|
70
|
+
readonly kind: string;
|
|
71
|
+
readonly type: string;
|
|
72
|
+
}
|
|
73
|
+
/** Structural view of `DataTransfer` (paste and drop events). */
|
|
74
|
+
interface DataTransferLike {
|
|
75
|
+
readonly types: ArrayLike<string>;
|
|
76
|
+
getData(format: string): string;
|
|
77
|
+
readonly files?: ArrayLike<File> | null;
|
|
78
|
+
readonly items?: ArrayLike<DataTransferItemLike> | null;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Whether a drag in progress could drop anything `accept`s. Uses only what
|
|
82
|
+
* browsers expose before the drop (item kinds and types, never the data).
|
|
83
|
+
* A file whose type is not known yet (some browsers hide it while dragging)
|
|
84
|
+
* counts as a maybe: the drop itself is checked against `accept`.
|
|
85
|
+
*/
|
|
86
|
+
export declare function canAcceptDrag(data: DataTransferLike, options: ResolvedPasteReadOptions): boolean;
|
|
87
|
+
/** Structural view of a `ClipboardItem` as returned by `navigator.clipboard.read()`. */
|
|
88
|
+
interface ClipboardItemLike {
|
|
89
|
+
readonly types: readonly string[];
|
|
90
|
+
getType(type: string): Promise<Blob>;
|
|
91
|
+
}
|
|
92
|
+
//#endregion
|
|
1
93
|
//#region src/core/errors.d.ts
|
|
2
94
|
/**
|
|
3
95
|
* Every way a clipboard operation can fail, as a closed union.
|
|
@@ -64,8 +156,11 @@ export declare function copyFailure(type: CopyErrorType, message: string, cause?
|
|
|
64
156
|
export declare function toCopyError(cause: unknown, operation?: ClipboardOperation): CopyError;
|
|
65
157
|
/** Default English, user-facing sentence for a copy error. Replace for i18n. */
|
|
66
158
|
export declare function describeCopyError(error: CopyError): string;
|
|
67
|
-
/**
|
|
68
|
-
|
|
159
|
+
/**
|
|
160
|
+
* Default English, user-facing sentence for a paste error. Pass the error
|
|
161
|
+
* state's `source` to word drag-and-drop failures as drops. Replace for i18n.
|
|
162
|
+
*/
|
|
163
|
+
export declare function describePasteError(error: CopyError, source?: PasteSource): string;
|
|
69
164
|
//#endregion
|
|
70
165
|
//#region src/core/machine-shared.d.ts
|
|
71
166
|
/**
|
|
@@ -260,6 +355,11 @@ export type CopyStatus = CopyState['status'];
|
|
|
260
355
|
* so its work was aborted. Nothing to report to the user.
|
|
261
356
|
*/
|
|
262
357
|
export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
358
|
+
/**
|
|
359
|
+
* Why an in-flight copy was cancelled: `reset` (`reset()` was called) or
|
|
360
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted).
|
|
361
|
+
*/
|
|
362
|
+
export type CopyCancelReason = 'reset' | 'disconnect';
|
|
263
363
|
/** What `copy()`/`retry()` resolve to. They never reject. */
|
|
264
364
|
export type CopyOutcome = {
|
|
265
365
|
readonly status: 'copied';
|
|
@@ -288,6 +388,18 @@ export interface CopyMachineOptions {
|
|
|
288
388
|
readonly coordinator?: CopyCoordinator | null;
|
|
289
389
|
readonly onCopy?: (payload: CopyPayload) => void;
|
|
290
390
|
readonly onError?: (error: CopyError, payload: CopyPayload | null) => void;
|
|
391
|
+
/**
|
|
392
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
393
|
+
* called for the automatic return after `resetAfterMs`, for a `<CopyGroup>`
|
|
394
|
+
* handing "Copied" to another member, or when already `idle`.
|
|
395
|
+
*/
|
|
396
|
+
readonly onReset?: () => void;
|
|
397
|
+
/**
|
|
398
|
+
* A copy in flight was cancelled before it settled: its `signal` aborted
|
|
399
|
+
* and its result will not reach state or `onCopy` / `onError`. Fires
|
|
400
|
+
* before `onReset` when `reset()` cancels a copy.
|
|
401
|
+
*/
|
|
402
|
+
readonly onCancel?: (reason: CopyCancelReason) => void;
|
|
291
403
|
/** Clock injection for tests and deterministic environments. */
|
|
292
404
|
readonly now?: () => number;
|
|
293
405
|
}
|
|
@@ -314,73 +426,6 @@ export declare function canRetryState(state: CopyState, maxRetries?: number): bo
|
|
|
314
426
|
/** Framework-agnostic copy state machine. */
|
|
315
427
|
export declare function createCopyMachine(options?: CopyMachineOptionsSource): CopyMachine;
|
|
316
428
|
//#endregion
|
|
317
|
-
//#region src/core/paste-reader.d.ts
|
|
318
|
-
/** Friendly names for the common cases. */
|
|
319
|
-
type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
320
|
-
/**
|
|
321
|
-
* What a paste may contain, in any order: a shorthand, an exact MIME type
|
|
322
|
-
* (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
|
|
323
|
-
* `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
|
|
324
|
-
*/
|
|
325
|
-
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
326
|
-
interface PasteLimits {
|
|
327
|
-
/** Total size cap across all accepted items. Strings count UTF-16 code units. Default 32 MiB. */
|
|
328
|
-
readonly maxBytes?: number;
|
|
329
|
-
/** Max number of accepted items (types + files). Default 32. */
|
|
330
|
-
readonly maxItems?: number;
|
|
331
|
-
}
|
|
332
|
-
interface PasteReadOptions extends PasteLimits {
|
|
333
|
-
/** Default `['text']` (plain text only): the safest choice. */
|
|
334
|
-
readonly accept?: readonly PasteAccept[];
|
|
335
|
-
}
|
|
336
|
-
/** Validated, normalised options that adapters receive. */
|
|
337
|
-
interface ResolvedPasteReadOptions {
|
|
338
|
-
/** Normalised patterns: `type/subtype`, `type/*` or `*\/*`. */
|
|
339
|
-
readonly accept: readonly string[];
|
|
340
|
-
readonly maxBytes: number;
|
|
341
|
-
readonly maxItems: number;
|
|
342
|
-
}
|
|
343
|
-
/** Where the content came from. */
|
|
344
|
-
type PasteSource = 'clipboard' | 'event';
|
|
345
|
-
/** One accepted clipboard entry. Textual types are decoded to `string`, everything else stays a `Blob`. */
|
|
346
|
-
interface PasteItem {
|
|
347
|
-
readonly type: string;
|
|
348
|
-
readonly data: string | Blob;
|
|
349
|
-
}
|
|
350
|
-
/**
|
|
351
|
-
* Everything the paste produced. Treat all of it as untrusted user input:
|
|
352
|
-
* in particular never inject `html` into the DOM without sanitising it.
|
|
353
|
-
*/
|
|
354
|
-
interface PasteResult {
|
|
355
|
-
readonly source: PasteSource;
|
|
356
|
-
/** Every accepted entry, in clipboard order. */
|
|
357
|
-
readonly items: readonly PasteItem[];
|
|
358
|
-
/** `text/plain`, when accepted and present. */
|
|
359
|
-
readonly text: string | null;
|
|
360
|
-
/** `text/html`, when accepted and present. UNTRUSTED markup: sanitise before rendering. */
|
|
361
|
-
readonly html: string | null;
|
|
362
|
-
/** Raster images, verified from their bytes (PNG, JPEG, GIF, WebP, AVIF, BMP), typed accordingly. */
|
|
363
|
-
readonly images: readonly Blob[];
|
|
364
|
-
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
365
|
-
readonly files: readonly File[];
|
|
366
|
-
}
|
|
367
|
-
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
368
|
-
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
369
|
-
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
370
|
-
/** Validates and normalises paste options. Throws a classified `invalid-payload` failure. */
|
|
371
|
-
export declare function resolvePasteReadOptions(options?: PasteReadOptions): ResolvedPasteReadOptions;
|
|
372
|
-
/** Structural view of `DataTransfer` (paste events). */
|
|
373
|
-
interface DataTransferLike {
|
|
374
|
-
readonly types: ArrayLike<string>;
|
|
375
|
-
getData(format: string): string;
|
|
376
|
-
readonly files?: ArrayLike<File> | null;
|
|
377
|
-
}
|
|
378
|
-
/** Structural view of a `ClipboardItem` as returned by `navigator.clipboard.read()`. */
|
|
379
|
-
interface ClipboardItemLike {
|
|
380
|
-
readonly types: readonly string[];
|
|
381
|
-
getType(type: string): Promise<Blob>;
|
|
382
|
-
}
|
|
383
|
-
//#endregion
|
|
384
429
|
//#region src/core/paste-adapter.d.ts
|
|
385
430
|
/** Minimal structural view of `navigator.clipboard` for reading. */
|
|
386
431
|
interface PasteClipboardLike {
|
|
@@ -402,7 +447,7 @@ interface PasteEnvironment {
|
|
|
402
447
|
* unmounts; honour it to stop decoding early.
|
|
403
448
|
*/
|
|
404
449
|
interface PasteAdapter {
|
|
405
|
-
read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<
|
|
450
|
+
read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteReadResult>;
|
|
406
451
|
}
|
|
407
452
|
interface BrowserPasteAdapterOptions {
|
|
408
453
|
/** Defaults to `window`, read lazily at paste time (SSR-safe). */
|
|
@@ -439,7 +484,13 @@ export type PasteStatus = PasteState['status'];
|
|
|
439
484
|
* finished, so its work was aborted. Nothing to report to the user.
|
|
440
485
|
*/
|
|
441
486
|
export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
442
|
-
/**
|
|
487
|
+
/**
|
|
488
|
+
* Why an in-flight read was cancelled: `reset` (`reset()` was called),
|
|
489
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted) or
|
|
490
|
+
* `superseded` (a paste or drop event arrived while a read was pending).
|
|
491
|
+
*/
|
|
492
|
+
export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
|
|
493
|
+
/** What `paste()` / `pasteEvent()` / `dropEvent()` / `retry()` resolve to. They never reject. */
|
|
443
494
|
export type PasteOutcome = {
|
|
444
495
|
readonly status: 'read';
|
|
445
496
|
readonly result: PasteResult;
|
|
@@ -455,14 +506,20 @@ export interface PasteEventLike {
|
|
|
455
506
|
readonly clipboardData: DataTransferLike | null | undefined;
|
|
456
507
|
preventDefault(): void;
|
|
457
508
|
}
|
|
509
|
+
/** Structural view of a DOM / React `drop` event. */
|
|
510
|
+
export interface PasteDropEventLike {
|
|
511
|
+
readonly dataTransfer: DataTransferLike | null | undefined;
|
|
512
|
+
preventDefault(): void;
|
|
513
|
+
}
|
|
458
514
|
export interface PasteMachineOptions extends PasteReadOptions {
|
|
459
515
|
/** Defaults to the browser Clipboard API adapter. */
|
|
460
516
|
readonly adapter?: PasteAdapter;
|
|
461
517
|
/** Return from `read` to `idle` after this many ms. `false` / `Infinity` / omitted = keep the result. */
|
|
462
518
|
readonly resetAfterMs?: number | false;
|
|
463
519
|
/**
|
|
464
|
-
* Paste events
|
|
465
|
-
*
|
|
520
|
+
* Paste events: call `event.preventDefault()` when the event carried accepted
|
|
521
|
+
* content, so the browser doesn't also insert it. Drop events: always call it,
|
|
522
|
+
* so the browser doesn't open the dropped file. Default `true`.
|
|
466
523
|
*/
|
|
467
524
|
readonly preventDefault?: boolean;
|
|
468
525
|
/**
|
|
@@ -472,6 +529,17 @@ export interface PasteMachineOptions extends PasteReadOptions {
|
|
|
472
529
|
readonly maxRetries?: number;
|
|
473
530
|
readonly onPaste?: (result: PasteResult) => void;
|
|
474
531
|
readonly onError?: (error: CopyError) => void;
|
|
532
|
+
/**
|
|
533
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
534
|
+
* called for the automatic return after `resetAfterMs`, or when already `idle`.
|
|
535
|
+
*/
|
|
536
|
+
readonly onReset?: () => void;
|
|
537
|
+
/**
|
|
538
|
+
* A read in flight was cancelled before it settled: its `signal` aborted
|
|
539
|
+
* and its result will not reach state or `onPaste` / `onError`. Fires
|
|
540
|
+
* before `onReset` when `reset()` cancels a read.
|
|
541
|
+
*/
|
|
542
|
+
readonly onCancel?: (reason: PasteCancelReason) => void;
|
|
475
543
|
/** Clock injection for tests and deterministic environments. */
|
|
476
544
|
readonly now?: () => number;
|
|
477
545
|
}
|
|
@@ -491,6 +559,13 @@ export interface PasteMachine {
|
|
|
491
559
|
* accepted content are ignored and left untouched for the browser.
|
|
492
560
|
*/
|
|
493
561
|
readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
|
|
562
|
+
/**
|
|
563
|
+
* Handles a drag-and-drop `drop` event exactly like a paste event: same
|
|
564
|
+
* `accept`, limits and image checks, `result.source === 'drop'`. Always calls
|
|
565
|
+
* `event.preventDefault()` (unless `preventDefault: false`), so a rejected
|
|
566
|
+
* file is not opened by the browser in place of the page.
|
|
567
|
+
*/
|
|
568
|
+
readonly dropEvent: (event: PasteDropEventLike) => Promise<PasteOutcome>;
|
|
494
569
|
/**
|
|
495
570
|
* Re-reads the clipboard after a retryable failure (e.g. permission denied,
|
|
496
571
|
* page not focused), up to `maxRetries`. Call it from a user gesture.
|
|
@@ -513,5 +588,5 @@ export declare function canRetryPasteState(state: PasteState, maxRetries?: numbe
|
|
|
513
588
|
/** Framework-agnostic paste state machine. */
|
|
514
589
|
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
515
590
|
//#endregion
|
|
516
|
-
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
591
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
517
592
|
//# sourceMappingURL=core.d.cts.map
|
package/dist/core.d.ts
CHANGED
|
@@ -1,3 +1,95 @@
|
|
|
1
|
+
//#region src/core/paste-reader.d.ts
|
|
2
|
+
/** Friendly names for the common cases. */
|
|
3
|
+
type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
4
|
+
/**
|
|
5
|
+
* What a paste may contain, in any order: a shorthand, an exact MIME type
|
|
6
|
+
* (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
|
|
7
|
+
* `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
|
|
8
|
+
*/
|
|
9
|
+
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
10
|
+
interface PasteLimits {
|
|
11
|
+
/**
|
|
12
|
+
* Total size cap across all accepted items, in UTF-8 bytes. Strings are measured as
|
|
13
|
+
* they would be encoded, matching `Blob.size`, so every paste path counts the same way.
|
|
14
|
+
* Default 32 MiB.
|
|
15
|
+
*/
|
|
16
|
+
readonly maxBytes?: number;
|
|
17
|
+
/** Max number of accepted items (types + files). Default 32. */
|
|
18
|
+
readonly maxItems?: number;
|
|
19
|
+
}
|
|
20
|
+
interface PasteReadOptions extends PasteLimits {
|
|
21
|
+
/** Default `['text']` (plain text only): the safest choice. */
|
|
22
|
+
readonly accept?: readonly PasteAccept[];
|
|
23
|
+
}
|
|
24
|
+
/** Validated, normalised options that adapters receive. */
|
|
25
|
+
interface ResolvedPasteReadOptions {
|
|
26
|
+
/** Normalised patterns: `type/subtype`, `type/*` or `*\/*`. */
|
|
27
|
+
readonly accept: readonly string[];
|
|
28
|
+
readonly maxBytes: number;
|
|
29
|
+
readonly maxItems: number;
|
|
30
|
+
}
|
|
31
|
+
/** Where the content came from: a Clipboard API read, a `paste` event, or a drag-and-drop `drop` event. */
|
|
32
|
+
type PasteSource = 'clipboard' | 'event' | 'drop';
|
|
33
|
+
/** One accepted clipboard entry. Textual types are decoded to `string`, everything else stays a `Blob`. */
|
|
34
|
+
interface PasteItem {
|
|
35
|
+
readonly type: string;
|
|
36
|
+
readonly data: string | Blob;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Everything the paste produced. Treat all of it as untrusted user input:
|
|
40
|
+
* in particular never inject `html` into the DOM without sanitising it.
|
|
41
|
+
*/
|
|
42
|
+
interface PasteResult {
|
|
43
|
+
readonly source: PasteSource;
|
|
44
|
+
/** Every accepted entry, in clipboard order. */
|
|
45
|
+
readonly items: readonly PasteItem[];
|
|
46
|
+
/** `text/plain`, when accepted and present. */
|
|
47
|
+
readonly text: string | null;
|
|
48
|
+
/** `text/html`, when accepted and present. UNTRUSTED markup: sanitise before rendering. */
|
|
49
|
+
readonly html: string | null;
|
|
50
|
+
/** Raster images, verified from their bytes (PNG, JPEG, GIF, WebP, AVIF, BMP), typed accordingly. */
|
|
51
|
+
readonly images: readonly Blob[];
|
|
52
|
+
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
53
|
+
readonly files: readonly File[];
|
|
54
|
+
/**
|
|
55
|
+
* The entries of `files` that are also in `images`: verified image files, keeping their
|
|
56
|
+
* names, ready for `FormData`. Derived by the paste machine, so it is always consistent.
|
|
57
|
+
*/
|
|
58
|
+
readonly imageFiles: readonly File[];
|
|
59
|
+
}
|
|
60
|
+
/** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
|
|
61
|
+
type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
|
|
62
|
+
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
63
|
+
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
64
|
+
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
65
|
+
/** Validates and normalises paste options. Throws a classified `invalid-payload` failure. */
|
|
66
|
+
export declare function resolvePasteReadOptions(options?: PasteReadOptions): ResolvedPasteReadOptions;
|
|
67
|
+
/** Structural view of a `DataTransferItem`: only what is readable while dragging. */
|
|
68
|
+
interface DataTransferItemLike {
|
|
69
|
+
/** `'string'` or `'file'`. */
|
|
70
|
+
readonly kind: string;
|
|
71
|
+
readonly type: string;
|
|
72
|
+
}
|
|
73
|
+
/** Structural view of `DataTransfer` (paste and drop events). */
|
|
74
|
+
interface DataTransferLike {
|
|
75
|
+
readonly types: ArrayLike<string>;
|
|
76
|
+
getData(format: string): string;
|
|
77
|
+
readonly files?: ArrayLike<File> | null;
|
|
78
|
+
readonly items?: ArrayLike<DataTransferItemLike> | null;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Whether a drag in progress could drop anything `accept`s. Uses only what
|
|
82
|
+
* browsers expose before the drop (item kinds and types, never the data).
|
|
83
|
+
* A file whose type is not known yet (some browsers hide it while dragging)
|
|
84
|
+
* counts as a maybe: the drop itself is checked against `accept`.
|
|
85
|
+
*/
|
|
86
|
+
export declare function canAcceptDrag(data: DataTransferLike, options: ResolvedPasteReadOptions): boolean;
|
|
87
|
+
/** Structural view of a `ClipboardItem` as returned by `navigator.clipboard.read()`. */
|
|
88
|
+
interface ClipboardItemLike {
|
|
89
|
+
readonly types: readonly string[];
|
|
90
|
+
getType(type: string): Promise<Blob>;
|
|
91
|
+
}
|
|
92
|
+
//#endregion
|
|
1
93
|
//#region src/core/errors.d.ts
|
|
2
94
|
/**
|
|
3
95
|
* Every way a clipboard operation can fail, as a closed union.
|
|
@@ -64,8 +156,11 @@ export declare function copyFailure(type: CopyErrorType, message: string, cause?
|
|
|
64
156
|
export declare function toCopyError(cause: unknown, operation?: ClipboardOperation): CopyError;
|
|
65
157
|
/** Default English, user-facing sentence for a copy error. Replace for i18n. */
|
|
66
158
|
export declare function describeCopyError(error: CopyError): string;
|
|
67
|
-
/**
|
|
68
|
-
|
|
159
|
+
/**
|
|
160
|
+
* Default English, user-facing sentence for a paste error. Pass the error
|
|
161
|
+
* state's `source` to word drag-and-drop failures as drops. Replace for i18n.
|
|
162
|
+
*/
|
|
163
|
+
export declare function describePasteError(error: CopyError, source?: PasteSource): string;
|
|
69
164
|
//#endregion
|
|
70
165
|
//#region src/core/machine-shared.d.ts
|
|
71
166
|
/**
|
|
@@ -260,6 +355,11 @@ export type CopyStatus = CopyState['status'];
|
|
|
260
355
|
* so its work was aborted. Nothing to report to the user.
|
|
261
356
|
*/
|
|
262
357
|
export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
358
|
+
/**
|
|
359
|
+
* Why an in-flight copy was cancelled: `reset` (`reset()` was called) or
|
|
360
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted).
|
|
361
|
+
*/
|
|
362
|
+
export type CopyCancelReason = 'reset' | 'disconnect';
|
|
263
363
|
/** What `copy()`/`retry()` resolve to. They never reject. */
|
|
264
364
|
export type CopyOutcome = {
|
|
265
365
|
readonly status: 'copied';
|
|
@@ -288,6 +388,18 @@ export interface CopyMachineOptions {
|
|
|
288
388
|
readonly coordinator?: CopyCoordinator | null;
|
|
289
389
|
readonly onCopy?: (payload: CopyPayload) => void;
|
|
290
390
|
readonly onError?: (error: CopyError, payload: CopyPayload | null) => void;
|
|
391
|
+
/**
|
|
392
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
393
|
+
* called for the automatic return after `resetAfterMs`, for a `<CopyGroup>`
|
|
394
|
+
* handing "Copied" to another member, or when already `idle`.
|
|
395
|
+
*/
|
|
396
|
+
readonly onReset?: () => void;
|
|
397
|
+
/**
|
|
398
|
+
* A copy in flight was cancelled before it settled: its `signal` aborted
|
|
399
|
+
* and its result will not reach state or `onCopy` / `onError`. Fires
|
|
400
|
+
* before `onReset` when `reset()` cancels a copy.
|
|
401
|
+
*/
|
|
402
|
+
readonly onCancel?: (reason: CopyCancelReason) => void;
|
|
291
403
|
/** Clock injection for tests and deterministic environments. */
|
|
292
404
|
readonly now?: () => number;
|
|
293
405
|
}
|
|
@@ -314,73 +426,6 @@ export declare function canRetryState(state: CopyState, maxRetries?: number): bo
|
|
|
314
426
|
/** Framework-agnostic copy state machine. */
|
|
315
427
|
export declare function createCopyMachine(options?: CopyMachineOptionsSource): CopyMachine;
|
|
316
428
|
//#endregion
|
|
317
|
-
//#region src/core/paste-reader.d.ts
|
|
318
|
-
/** Friendly names for the common cases. */
|
|
319
|
-
type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
320
|
-
/**
|
|
321
|
-
* What a paste may contain, in any order: a shorthand, an exact MIME type
|
|
322
|
-
* (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
|
|
323
|
-
* `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
|
|
324
|
-
*/
|
|
325
|
-
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
326
|
-
interface PasteLimits {
|
|
327
|
-
/** Total size cap across all accepted items. Strings count UTF-16 code units. Default 32 MiB. */
|
|
328
|
-
readonly maxBytes?: number;
|
|
329
|
-
/** Max number of accepted items (types + files). Default 32. */
|
|
330
|
-
readonly maxItems?: number;
|
|
331
|
-
}
|
|
332
|
-
interface PasteReadOptions extends PasteLimits {
|
|
333
|
-
/** Default `['text']` (plain text only): the safest choice. */
|
|
334
|
-
readonly accept?: readonly PasteAccept[];
|
|
335
|
-
}
|
|
336
|
-
/** Validated, normalised options that adapters receive. */
|
|
337
|
-
interface ResolvedPasteReadOptions {
|
|
338
|
-
/** Normalised patterns: `type/subtype`, `type/*` or `*\/*`. */
|
|
339
|
-
readonly accept: readonly string[];
|
|
340
|
-
readonly maxBytes: number;
|
|
341
|
-
readonly maxItems: number;
|
|
342
|
-
}
|
|
343
|
-
/** Where the content came from. */
|
|
344
|
-
type PasteSource = 'clipboard' | 'event';
|
|
345
|
-
/** One accepted clipboard entry. Textual types are decoded to `string`, everything else stays a `Blob`. */
|
|
346
|
-
interface PasteItem {
|
|
347
|
-
readonly type: string;
|
|
348
|
-
readonly data: string | Blob;
|
|
349
|
-
}
|
|
350
|
-
/**
|
|
351
|
-
* Everything the paste produced. Treat all of it as untrusted user input:
|
|
352
|
-
* in particular never inject `html` into the DOM without sanitising it.
|
|
353
|
-
*/
|
|
354
|
-
interface PasteResult {
|
|
355
|
-
readonly source: PasteSource;
|
|
356
|
-
/** Every accepted entry, in clipboard order. */
|
|
357
|
-
readonly items: readonly PasteItem[];
|
|
358
|
-
/** `text/plain`, when accepted and present. */
|
|
359
|
-
readonly text: string | null;
|
|
360
|
-
/** `text/html`, when accepted and present. UNTRUSTED markup: sanitise before rendering. */
|
|
361
|
-
readonly html: string | null;
|
|
362
|
-
/** Raster images, verified from their bytes (PNG, JPEG, GIF, WebP, AVIF, BMP), typed accordingly. */
|
|
363
|
-
readonly images: readonly Blob[];
|
|
364
|
-
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
365
|
-
readonly files: readonly File[];
|
|
366
|
-
}
|
|
367
|
-
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
368
|
-
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
369
|
-
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
370
|
-
/** Validates and normalises paste options. Throws a classified `invalid-payload` failure. */
|
|
371
|
-
export declare function resolvePasteReadOptions(options?: PasteReadOptions): ResolvedPasteReadOptions;
|
|
372
|
-
/** Structural view of `DataTransfer` (paste events). */
|
|
373
|
-
interface DataTransferLike {
|
|
374
|
-
readonly types: ArrayLike<string>;
|
|
375
|
-
getData(format: string): string;
|
|
376
|
-
readonly files?: ArrayLike<File> | null;
|
|
377
|
-
}
|
|
378
|
-
/** Structural view of a `ClipboardItem` as returned by `navigator.clipboard.read()`. */
|
|
379
|
-
interface ClipboardItemLike {
|
|
380
|
-
readonly types: readonly string[];
|
|
381
|
-
getType(type: string): Promise<Blob>;
|
|
382
|
-
}
|
|
383
|
-
//#endregion
|
|
384
429
|
//#region src/core/paste-adapter.d.ts
|
|
385
430
|
/** Minimal structural view of `navigator.clipboard` for reading. */
|
|
386
431
|
interface PasteClipboardLike {
|
|
@@ -402,7 +447,7 @@ interface PasteEnvironment {
|
|
|
402
447
|
* unmounts; honour it to stop decoding early.
|
|
403
448
|
*/
|
|
404
449
|
interface PasteAdapter {
|
|
405
|
-
read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<
|
|
450
|
+
read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteReadResult>;
|
|
406
451
|
}
|
|
407
452
|
interface BrowserPasteAdapterOptions {
|
|
408
453
|
/** Defaults to `window`, read lazily at paste time (SSR-safe). */
|
|
@@ -439,7 +484,13 @@ export type PasteStatus = PasteState['status'];
|
|
|
439
484
|
* finished, so its work was aborted. Nothing to report to the user.
|
|
440
485
|
*/
|
|
441
486
|
export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
442
|
-
/**
|
|
487
|
+
/**
|
|
488
|
+
* Why an in-flight read was cancelled: `reset` (`reset()` was called),
|
|
489
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted) or
|
|
490
|
+
* `superseded` (a paste or drop event arrived while a read was pending).
|
|
491
|
+
*/
|
|
492
|
+
export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
|
|
493
|
+
/** What `paste()` / `pasteEvent()` / `dropEvent()` / `retry()` resolve to. They never reject. */
|
|
443
494
|
export type PasteOutcome = {
|
|
444
495
|
readonly status: 'read';
|
|
445
496
|
readonly result: PasteResult;
|
|
@@ -455,14 +506,20 @@ export interface PasteEventLike {
|
|
|
455
506
|
readonly clipboardData: DataTransferLike | null | undefined;
|
|
456
507
|
preventDefault(): void;
|
|
457
508
|
}
|
|
509
|
+
/** Structural view of a DOM / React `drop` event. */
|
|
510
|
+
export interface PasteDropEventLike {
|
|
511
|
+
readonly dataTransfer: DataTransferLike | null | undefined;
|
|
512
|
+
preventDefault(): void;
|
|
513
|
+
}
|
|
458
514
|
export interface PasteMachineOptions extends PasteReadOptions {
|
|
459
515
|
/** Defaults to the browser Clipboard API adapter. */
|
|
460
516
|
readonly adapter?: PasteAdapter;
|
|
461
517
|
/** Return from `read` to `idle` after this many ms. `false` / `Infinity` / omitted = keep the result. */
|
|
462
518
|
readonly resetAfterMs?: number | false;
|
|
463
519
|
/**
|
|
464
|
-
* Paste events
|
|
465
|
-
*
|
|
520
|
+
* Paste events: call `event.preventDefault()` when the event carried accepted
|
|
521
|
+
* content, so the browser doesn't also insert it. Drop events: always call it,
|
|
522
|
+
* so the browser doesn't open the dropped file. Default `true`.
|
|
466
523
|
*/
|
|
467
524
|
readonly preventDefault?: boolean;
|
|
468
525
|
/**
|
|
@@ -472,6 +529,17 @@ export interface PasteMachineOptions extends PasteReadOptions {
|
|
|
472
529
|
readonly maxRetries?: number;
|
|
473
530
|
readonly onPaste?: (result: PasteResult) => void;
|
|
474
531
|
readonly onError?: (error: CopyError) => void;
|
|
532
|
+
/**
|
|
533
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
534
|
+
* called for the automatic return after `resetAfterMs`, or when already `idle`.
|
|
535
|
+
*/
|
|
536
|
+
readonly onReset?: () => void;
|
|
537
|
+
/**
|
|
538
|
+
* A read in flight was cancelled before it settled: its `signal` aborted
|
|
539
|
+
* and its result will not reach state or `onPaste` / `onError`. Fires
|
|
540
|
+
* before `onReset` when `reset()` cancels a read.
|
|
541
|
+
*/
|
|
542
|
+
readonly onCancel?: (reason: PasteCancelReason) => void;
|
|
475
543
|
/** Clock injection for tests and deterministic environments. */
|
|
476
544
|
readonly now?: () => number;
|
|
477
545
|
}
|
|
@@ -491,6 +559,13 @@ export interface PasteMachine {
|
|
|
491
559
|
* accepted content are ignored and left untouched for the browser.
|
|
492
560
|
*/
|
|
493
561
|
readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
|
|
562
|
+
/**
|
|
563
|
+
* Handles a drag-and-drop `drop` event exactly like a paste event: same
|
|
564
|
+
* `accept`, limits and image checks, `result.source === 'drop'`. Always calls
|
|
565
|
+
* `event.preventDefault()` (unless `preventDefault: false`), so a rejected
|
|
566
|
+
* file is not opened by the browser in place of the page.
|
|
567
|
+
*/
|
|
568
|
+
readonly dropEvent: (event: PasteDropEventLike) => Promise<PasteOutcome>;
|
|
494
569
|
/**
|
|
495
570
|
* Re-reads the clipboard after a retryable failure (e.g. permission denied,
|
|
496
571
|
* page not focused), up to `maxRetries`. Call it from a user gesture.
|
|
@@ -513,5 +588,5 @@ export declare function canRetryPasteState(state: PasteState, maxRetries?: numbe
|
|
|
513
588
|
/** Framework-agnostic paste state machine. */
|
|
514
589
|
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
515
590
|
//#endregion
|
|
516
|
-
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
591
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
517
592
|
//# sourceMappingURL=core.d.ts.map
|