react-smart-copy 1.3.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 +48 -13
- package/dist/capture.cjs.map +1 -1
- package/dist/capture.js.map +1 -1
- package/dist/core.cjs +47 -11
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.cts +115 -85
- package/dist/core.d.ts +115 -85
- package/dist/core.js +47 -12
- package/dist/core.js.map +1 -1
- package/dist/index.cjs +129 -19
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +147 -90
- package/dist/index.d.ts +147 -90
- package/dist/index.js +129 -20
- package/dist/index.js.map +1 -1
- package/package.json +4 -4
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
|
/**
|
|
@@ -331,84 +426,6 @@ export declare function canRetryState(state: CopyState, maxRetries?: number): bo
|
|
|
331
426
|
/** Framework-agnostic copy state machine. */
|
|
332
427
|
export declare function createCopyMachine(options?: CopyMachineOptionsSource): CopyMachine;
|
|
333
428
|
//#endregion
|
|
334
|
-
//#region src/core/paste-reader.d.ts
|
|
335
|
-
/** Friendly names for the common cases. */
|
|
336
|
-
type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
337
|
-
/**
|
|
338
|
-
* What a paste may contain, in any order: a shorthand, an exact MIME type
|
|
339
|
-
* (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
|
|
340
|
-
* `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
|
|
341
|
-
*/
|
|
342
|
-
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
343
|
-
interface PasteLimits {
|
|
344
|
-
/**
|
|
345
|
-
* Total size cap across all accepted items, in UTF-8 bytes. Strings are measured as
|
|
346
|
-
* they would be encoded, matching `Blob.size`, so every paste path counts the same way.
|
|
347
|
-
* Default 32 MiB.
|
|
348
|
-
*/
|
|
349
|
-
readonly maxBytes?: number;
|
|
350
|
-
/** Max number of accepted items (types + files). Default 32. */
|
|
351
|
-
readonly maxItems?: number;
|
|
352
|
-
}
|
|
353
|
-
interface PasteReadOptions extends PasteLimits {
|
|
354
|
-
/** Default `['text']` (plain text only): the safest choice. */
|
|
355
|
-
readonly accept?: readonly PasteAccept[];
|
|
356
|
-
}
|
|
357
|
-
/** Validated, normalised options that adapters receive. */
|
|
358
|
-
interface ResolvedPasteReadOptions {
|
|
359
|
-
/** Normalised patterns: `type/subtype`, `type/*` or `*\/*`. */
|
|
360
|
-
readonly accept: readonly string[];
|
|
361
|
-
readonly maxBytes: number;
|
|
362
|
-
readonly maxItems: number;
|
|
363
|
-
}
|
|
364
|
-
/** Where the content came from. */
|
|
365
|
-
type PasteSource = 'clipboard' | 'event';
|
|
366
|
-
/** One accepted clipboard entry. Textual types are decoded to `string`, everything else stays a `Blob`. */
|
|
367
|
-
interface PasteItem {
|
|
368
|
-
readonly type: string;
|
|
369
|
-
readonly data: string | Blob;
|
|
370
|
-
}
|
|
371
|
-
/**
|
|
372
|
-
* Everything the paste produced. Treat all of it as untrusted user input:
|
|
373
|
-
* in particular never inject `html` into the DOM without sanitising it.
|
|
374
|
-
*/
|
|
375
|
-
interface PasteResult {
|
|
376
|
-
readonly source: PasteSource;
|
|
377
|
-
/** Every accepted entry, in clipboard order. */
|
|
378
|
-
readonly items: readonly PasteItem[];
|
|
379
|
-
/** `text/plain`, when accepted and present. */
|
|
380
|
-
readonly text: string | null;
|
|
381
|
-
/** `text/html`, when accepted and present. UNTRUSTED markup: sanitise before rendering. */
|
|
382
|
-
readonly html: string | null;
|
|
383
|
-
/** Raster images, verified from their bytes (PNG, JPEG, GIF, WebP, AVIF, BMP), typed accordingly. */
|
|
384
|
-
readonly images: readonly Blob[];
|
|
385
|
-
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
386
|
-
readonly files: readonly File[];
|
|
387
|
-
/**
|
|
388
|
-
* The entries of `files` that are also in `images`: verified image files, keeping their
|
|
389
|
-
* names, ready for `FormData`. Derived by the paste machine, so it is always consistent.
|
|
390
|
-
*/
|
|
391
|
-
readonly imageFiles: readonly File[];
|
|
392
|
-
}
|
|
393
|
-
/** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
|
|
394
|
-
type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
|
|
395
|
-
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
396
|
-
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
397
|
-
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
398
|
-
/** Validates and normalises paste options. Throws a classified `invalid-payload` failure. */
|
|
399
|
-
export declare function resolvePasteReadOptions(options?: PasteReadOptions): ResolvedPasteReadOptions;
|
|
400
|
-
/** Structural view of `DataTransfer` (paste events). */
|
|
401
|
-
interface DataTransferLike {
|
|
402
|
-
readonly types: ArrayLike<string>;
|
|
403
|
-
getData(format: string): string;
|
|
404
|
-
readonly files?: ArrayLike<File> | null;
|
|
405
|
-
}
|
|
406
|
-
/** Structural view of a `ClipboardItem` as returned by `navigator.clipboard.read()`. */
|
|
407
|
-
interface ClipboardItemLike {
|
|
408
|
-
readonly types: readonly string[];
|
|
409
|
-
getType(type: string): Promise<Blob>;
|
|
410
|
-
}
|
|
411
|
-
//#endregion
|
|
412
429
|
//#region src/core/paste-adapter.d.ts
|
|
413
430
|
/** Minimal structural view of `navigator.clipboard` for reading. */
|
|
414
431
|
interface PasteClipboardLike {
|
|
@@ -470,10 +487,10 @@ export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-
|
|
|
470
487
|
/**
|
|
471
488
|
* Why an in-flight read was cancelled: `reset` (`reset()` was called),
|
|
472
489
|
* `disconnect` (its host disconnected, e.g. the React component unmounted) or
|
|
473
|
-
* `superseded` (a paste event arrived while a
|
|
490
|
+
* `superseded` (a paste or drop event arrived while a read was pending).
|
|
474
491
|
*/
|
|
475
492
|
export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
|
|
476
|
-
/** What `paste()` / `pasteEvent()` / `retry()` resolve to. They never reject. */
|
|
493
|
+
/** What `paste()` / `pasteEvent()` / `dropEvent()` / `retry()` resolve to. They never reject. */
|
|
477
494
|
export type PasteOutcome = {
|
|
478
495
|
readonly status: 'read';
|
|
479
496
|
readonly result: PasteResult;
|
|
@@ -489,14 +506,20 @@ export interface PasteEventLike {
|
|
|
489
506
|
readonly clipboardData: DataTransferLike | null | undefined;
|
|
490
507
|
preventDefault(): void;
|
|
491
508
|
}
|
|
509
|
+
/** Structural view of a DOM / React `drop` event. */
|
|
510
|
+
export interface PasteDropEventLike {
|
|
511
|
+
readonly dataTransfer: DataTransferLike | null | undefined;
|
|
512
|
+
preventDefault(): void;
|
|
513
|
+
}
|
|
492
514
|
export interface PasteMachineOptions extends PasteReadOptions {
|
|
493
515
|
/** Defaults to the browser Clipboard API adapter. */
|
|
494
516
|
readonly adapter?: PasteAdapter;
|
|
495
517
|
/** Return from `read` to `idle` after this many ms. `false` / `Infinity` / omitted = keep the result. */
|
|
496
518
|
readonly resetAfterMs?: number | false;
|
|
497
519
|
/**
|
|
498
|
-
* Paste events
|
|
499
|
-
*
|
|
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`.
|
|
500
523
|
*/
|
|
501
524
|
readonly preventDefault?: boolean;
|
|
502
525
|
/**
|
|
@@ -536,6 +559,13 @@ export interface PasteMachine {
|
|
|
536
559
|
* accepted content are ignored and left untouched for the browser.
|
|
537
560
|
*/
|
|
538
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>;
|
|
539
569
|
/**
|
|
540
570
|
* Re-reads the clipboard after a retryable failure (e.g. permission denied,
|
|
541
571
|
* page not focused), up to `maxRetries`. Call it from a user gesture.
|
|
@@ -558,5 +588,5 @@ export declare function canRetryPasteState(state: PasteState, maxRetries?: numbe
|
|
|
558
588
|
/** Framework-agnostic paste state machine. */
|
|
559
589
|
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
560
590
|
//#endregion
|
|
561
|
-
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
591
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
562
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
|
/**
|
|
@@ -331,84 +426,6 @@ export declare function canRetryState(state: CopyState, maxRetries?: number): bo
|
|
|
331
426
|
/** Framework-agnostic copy state machine. */
|
|
332
427
|
export declare function createCopyMachine(options?: CopyMachineOptionsSource): CopyMachine;
|
|
333
428
|
//#endregion
|
|
334
|
-
//#region src/core/paste-reader.d.ts
|
|
335
|
-
/** Friendly names for the common cases. */
|
|
336
|
-
type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
337
|
-
/**
|
|
338
|
-
* What a paste may contain, in any order: a shorthand, an exact MIME type
|
|
339
|
-
* (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
|
|
340
|
-
* `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
|
|
341
|
-
*/
|
|
342
|
-
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
343
|
-
interface PasteLimits {
|
|
344
|
-
/**
|
|
345
|
-
* Total size cap across all accepted items, in UTF-8 bytes. Strings are measured as
|
|
346
|
-
* they would be encoded, matching `Blob.size`, so every paste path counts the same way.
|
|
347
|
-
* Default 32 MiB.
|
|
348
|
-
*/
|
|
349
|
-
readonly maxBytes?: number;
|
|
350
|
-
/** Max number of accepted items (types + files). Default 32. */
|
|
351
|
-
readonly maxItems?: number;
|
|
352
|
-
}
|
|
353
|
-
interface PasteReadOptions extends PasteLimits {
|
|
354
|
-
/** Default `['text']` (plain text only): the safest choice. */
|
|
355
|
-
readonly accept?: readonly PasteAccept[];
|
|
356
|
-
}
|
|
357
|
-
/** Validated, normalised options that adapters receive. */
|
|
358
|
-
interface ResolvedPasteReadOptions {
|
|
359
|
-
/** Normalised patterns: `type/subtype`, `type/*` or `*\/*`. */
|
|
360
|
-
readonly accept: readonly string[];
|
|
361
|
-
readonly maxBytes: number;
|
|
362
|
-
readonly maxItems: number;
|
|
363
|
-
}
|
|
364
|
-
/** Where the content came from. */
|
|
365
|
-
type PasteSource = 'clipboard' | 'event';
|
|
366
|
-
/** One accepted clipboard entry. Textual types are decoded to `string`, everything else stays a `Blob`. */
|
|
367
|
-
interface PasteItem {
|
|
368
|
-
readonly type: string;
|
|
369
|
-
readonly data: string | Blob;
|
|
370
|
-
}
|
|
371
|
-
/**
|
|
372
|
-
* Everything the paste produced. Treat all of it as untrusted user input:
|
|
373
|
-
* in particular never inject `html` into the DOM without sanitising it.
|
|
374
|
-
*/
|
|
375
|
-
interface PasteResult {
|
|
376
|
-
readonly source: PasteSource;
|
|
377
|
-
/** Every accepted entry, in clipboard order. */
|
|
378
|
-
readonly items: readonly PasteItem[];
|
|
379
|
-
/** `text/plain`, when accepted and present. */
|
|
380
|
-
readonly text: string | null;
|
|
381
|
-
/** `text/html`, when accepted and present. UNTRUSTED markup: sanitise before rendering. */
|
|
382
|
-
readonly html: string | null;
|
|
383
|
-
/** Raster images, verified from their bytes (PNG, JPEG, GIF, WebP, AVIF, BMP), typed accordingly. */
|
|
384
|
-
readonly images: readonly Blob[];
|
|
385
|
-
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
386
|
-
readonly files: readonly File[];
|
|
387
|
-
/**
|
|
388
|
-
* The entries of `files` that are also in `images`: verified image files, keeping their
|
|
389
|
-
* names, ready for `FormData`. Derived by the paste machine, so it is always consistent.
|
|
390
|
-
*/
|
|
391
|
-
readonly imageFiles: readonly File[];
|
|
392
|
-
}
|
|
393
|
-
/** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
|
|
394
|
-
type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
|
|
395
|
-
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
396
|
-
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
397
|
-
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
398
|
-
/** Validates and normalises paste options. Throws a classified `invalid-payload` failure. */
|
|
399
|
-
export declare function resolvePasteReadOptions(options?: PasteReadOptions): ResolvedPasteReadOptions;
|
|
400
|
-
/** Structural view of `DataTransfer` (paste events). */
|
|
401
|
-
interface DataTransferLike {
|
|
402
|
-
readonly types: ArrayLike<string>;
|
|
403
|
-
getData(format: string): string;
|
|
404
|
-
readonly files?: ArrayLike<File> | null;
|
|
405
|
-
}
|
|
406
|
-
/** Structural view of a `ClipboardItem` as returned by `navigator.clipboard.read()`. */
|
|
407
|
-
interface ClipboardItemLike {
|
|
408
|
-
readonly types: readonly string[];
|
|
409
|
-
getType(type: string): Promise<Blob>;
|
|
410
|
-
}
|
|
411
|
-
//#endregion
|
|
412
429
|
//#region src/core/paste-adapter.d.ts
|
|
413
430
|
/** Minimal structural view of `navigator.clipboard` for reading. */
|
|
414
431
|
interface PasteClipboardLike {
|
|
@@ -470,10 +487,10 @@ export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-
|
|
|
470
487
|
/**
|
|
471
488
|
* Why an in-flight read was cancelled: `reset` (`reset()` was called),
|
|
472
489
|
* `disconnect` (its host disconnected, e.g. the React component unmounted) or
|
|
473
|
-
* `superseded` (a paste event arrived while a
|
|
490
|
+
* `superseded` (a paste or drop event arrived while a read was pending).
|
|
474
491
|
*/
|
|
475
492
|
export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
|
|
476
|
-
/** What `paste()` / `pasteEvent()` / `retry()` resolve to. They never reject. */
|
|
493
|
+
/** What `paste()` / `pasteEvent()` / `dropEvent()` / `retry()` resolve to. They never reject. */
|
|
477
494
|
export type PasteOutcome = {
|
|
478
495
|
readonly status: 'read';
|
|
479
496
|
readonly result: PasteResult;
|
|
@@ -489,14 +506,20 @@ export interface PasteEventLike {
|
|
|
489
506
|
readonly clipboardData: DataTransferLike | null | undefined;
|
|
490
507
|
preventDefault(): void;
|
|
491
508
|
}
|
|
509
|
+
/** Structural view of a DOM / React `drop` event. */
|
|
510
|
+
export interface PasteDropEventLike {
|
|
511
|
+
readonly dataTransfer: DataTransferLike | null | undefined;
|
|
512
|
+
preventDefault(): void;
|
|
513
|
+
}
|
|
492
514
|
export interface PasteMachineOptions extends PasteReadOptions {
|
|
493
515
|
/** Defaults to the browser Clipboard API adapter. */
|
|
494
516
|
readonly adapter?: PasteAdapter;
|
|
495
517
|
/** Return from `read` to `idle` after this many ms. `false` / `Infinity` / omitted = keep the result. */
|
|
496
518
|
readonly resetAfterMs?: number | false;
|
|
497
519
|
/**
|
|
498
|
-
* Paste events
|
|
499
|
-
*
|
|
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`.
|
|
500
523
|
*/
|
|
501
524
|
readonly preventDefault?: boolean;
|
|
502
525
|
/**
|
|
@@ -536,6 +559,13 @@ export interface PasteMachine {
|
|
|
536
559
|
* accepted content are ignored and left untouched for the browser.
|
|
537
560
|
*/
|
|
538
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>;
|
|
539
569
|
/**
|
|
540
570
|
* Re-reads the clipboard after a retryable failure (e.g. permission denied,
|
|
541
571
|
* page not focused), up to `maxRetries`. Call it from a user gesture.
|
|
@@ -558,5 +588,5 @@ export declare function canRetryPasteState(state: PasteState, maxRetries?: numbe
|
|
|
558
588
|
/** Framework-agnostic paste state machine. */
|
|
559
589
|
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
560
590
|
//#endregion
|
|
561
|
-
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
591
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
562
592
|
//# sourceMappingURL=core.d.ts.map
|
package/dist/core.js
CHANGED
|
@@ -99,9 +99,19 @@ const PASTE_DESCRIPTIONS = {
|
|
|
99
99
|
function describeCopyError(error) {
|
|
100
100
|
return COPY_DESCRIPTIONS[error.type];
|
|
101
101
|
}
|
|
102
|
-
/**
|
|
103
|
-
|
|
104
|
-
|
|
102
|
+
/** Drops can only fail in these ways; the rest of the paste wording would mention the clipboard. */
|
|
103
|
+
const DROP_DESCRIPTIONS = {
|
|
104
|
+
"invalid-payload": "The dropped content couldn't be read.",
|
|
105
|
+
"no-content": "Nothing that was dropped can be used here.",
|
|
106
|
+
"too-large": "The dropped content is too large.",
|
|
107
|
+
unknown: "Couldn't read the dropped content. Try again."
|
|
108
|
+
};
|
|
109
|
+
/**
|
|
110
|
+
* Default English, user-facing sentence for a paste error. Pass the error
|
|
111
|
+
* state's `source` to word drag-and-drop failures as drops. Replace for i18n.
|
|
112
|
+
*/
|
|
113
|
+
function describePasteError(error, source) {
|
|
114
|
+
return (source === "drop" ? DROP_DESCRIPTIONS[error.type] : void 0) ?? PASTE_DESCRIPTIONS[error.type];
|
|
105
115
|
}
|
|
106
116
|
//#endregion
|
|
107
117
|
//#region src/core/payload.ts
|
|
@@ -688,6 +698,27 @@ function enforcePasteLimits(entries, options) {
|
|
|
688
698
|
for (const entry of entries) budget.charge(sizeOf(entry.data));
|
|
689
699
|
}
|
|
690
700
|
/**
|
|
701
|
+
* Whether a drag in progress could drop anything `accept`s. Uses only what
|
|
702
|
+
* browsers expose before the drop (item kinds and types, never the data).
|
|
703
|
+
* A file whose type is not known yet (some browsers hide it while dragging)
|
|
704
|
+
* counts as a maybe: the drop itself is checked against `accept`.
|
|
705
|
+
*/
|
|
706
|
+
function canAcceptDrag(data, options) {
|
|
707
|
+
const items = data.items ?? Array.from(data.types, (type) => type === "Files" ? {
|
|
708
|
+
kind: "file",
|
|
709
|
+
type: ""
|
|
710
|
+
} : {
|
|
711
|
+
kind: "string",
|
|
712
|
+
type
|
|
713
|
+
});
|
|
714
|
+
return Array.from(items).some(({ kind, type: raw }) => {
|
|
715
|
+
const file = kind === "file";
|
|
716
|
+
const type = normalizeMimeType(raw);
|
|
717
|
+
if (type === null) return file;
|
|
718
|
+
return (file || isTextualMimeType(type)) && isAccepted(type, options);
|
|
719
|
+
});
|
|
720
|
+
}
|
|
721
|
+
/**
|
|
691
722
|
* Synchronously copies the accepted parts of a paste event's `DataTransfer`.
|
|
692
723
|
* It must run during the event: browsers empty the object afterwards.
|
|
693
724
|
*/
|
|
@@ -785,7 +816,7 @@ async function finalizePaste(entries, source, options) {
|
|
|
785
816
|
data
|
|
786
817
|
});
|
|
787
818
|
}
|
|
788
|
-
if (items.length === 0) throw copyFailure("no-content", "The
|
|
819
|
+
if (items.length === 0) throw copyFailure("no-content", "The content holds nothing that matches `accept`.");
|
|
789
820
|
return {
|
|
790
821
|
source,
|
|
791
822
|
items,
|
|
@@ -977,10 +1008,11 @@ function createPasteMachine(options = {}) {
|
|
|
977
1008
|
}
|
|
978
1009
|
return readClipboard(state.retryCount + 1);
|
|
979
1010
|
};
|
|
980
|
-
|
|
981
|
-
|
|
982
|
-
if (!data) return Promise.resolve(IGNORED_NO_CONTENT);
|
|
1011
|
+
/** Shared by paste and drop events: their `DataTransfer` has the same shape and lifetime. */
|
|
1012
|
+
const transfer = (data, event, source) => {
|
|
983
1013
|
const current = read();
|
|
1014
|
+
if (source === "drop" && current.preventDefault !== false) event.preventDefault();
|
|
1015
|
+
if (!data) return Promise.resolve(IGNORED_NO_CONTENT);
|
|
984
1016
|
let resolved;
|
|
985
1017
|
try {
|
|
986
1018
|
resolved = resolvePasteReadOptions(current);
|
|
@@ -989,7 +1021,7 @@ function createPasteMachine(options = {}) {
|
|
|
989
1021
|
++generation;
|
|
990
1022
|
const superseded = operations.abort();
|
|
991
1023
|
clearResetTimer();
|
|
992
|
-
settleError(error,
|
|
1024
|
+
settleError(error, source, 0);
|
|
993
1025
|
if (superseded) invoke(current.onCancel, "superseded");
|
|
994
1026
|
return Promise.resolve({
|
|
995
1027
|
status: "error",
|
|
@@ -998,12 +1030,14 @@ function createPasteMachine(options = {}) {
|
|
|
998
1030
|
}
|
|
999
1031
|
const entries = snapshotDataTransfer(data, resolved);
|
|
1000
1032
|
if (entries.length === 0) return Promise.resolve(IGNORED_NO_CONTENT);
|
|
1001
|
-
if (current.preventDefault !== false) event.preventDefault();
|
|
1033
|
+
if (source === "event" && current.preventDefault !== false) event.preventDefault();
|
|
1002
1034
|
return run(() => {
|
|
1003
1035
|
enforcePasteLimits(entries, resolved);
|
|
1004
|
-
return finalizePaste(entries,
|
|
1005
|
-
},
|
|
1036
|
+
return finalizePaste(entries, source, resolved);
|
|
1037
|
+
}, source, 0);
|
|
1006
1038
|
};
|
|
1039
|
+
const pasteEvent = (event) => transfer(event.clipboardData, event, "event");
|
|
1040
|
+
const dropEvent = (event) => transfer(event.dataTransfer, event, "drop");
|
|
1007
1041
|
const reset = () => {
|
|
1008
1042
|
++generation;
|
|
1009
1043
|
const cancelled = operations.abort();
|
|
@@ -1033,12 +1067,13 @@ function createPasteMachine(options = {}) {
|
|
|
1033
1067
|
},
|
|
1034
1068
|
paste,
|
|
1035
1069
|
pasteEvent,
|
|
1070
|
+
dropEvent,
|
|
1036
1071
|
retry,
|
|
1037
1072
|
reset,
|
|
1038
1073
|
connect
|
|
1039
1074
|
};
|
|
1040
1075
|
}
|
|
1041
1076
|
//#endregion
|
|
1042
|
-
export { CopyFailure, DEFAULT_MAX_RETRIES, DEFAULT_PASTE_ACCEPT, DEFAULT_PASTE_MAX_BYTES, DEFAULT_PASTE_MAX_ITEMS, DEFAULT_RESET_AFTER_MS, IDLE_STATE, IMAGE_MIME_TYPE, PASTE_IDLE_STATE, SVG_MIME_TYPE, canRetryPasteState, canRetryState, copyFailure, createBrowserClipboardAdapter, createBrowserPasteAdapter, createCopyCoordinator, createCopyError, createCopyMachine, createPasteMachine, describeCopyError, describePasteError, isBlob, isCopyFailure, isRetryableError, isTextualMimeType, matchesMimePattern, normalizeMimeType, normalizePayload, resolveMaxRetries, resolvePasteReadOptions, serializeJson, sniffImageBytes, sniffImageType, toCopyError, validatePayload };
|
|
1077
|
+
export { CopyFailure, DEFAULT_MAX_RETRIES, DEFAULT_PASTE_ACCEPT, DEFAULT_PASTE_MAX_BYTES, DEFAULT_PASTE_MAX_ITEMS, DEFAULT_RESET_AFTER_MS, IDLE_STATE, IMAGE_MIME_TYPE, PASTE_IDLE_STATE, SVG_MIME_TYPE, canAcceptDrag, canRetryPasteState, canRetryState, copyFailure, createBrowserClipboardAdapter, createBrowserPasteAdapter, createCopyCoordinator, createCopyError, createCopyMachine, createPasteMachine, describeCopyError, describePasteError, isBlob, isCopyFailure, isRetryableError, isTextualMimeType, matchesMimePattern, normalizeMimeType, normalizePayload, resolveMaxRetries, resolvePasteReadOptions, serializeJson, sniffImageBytes, sniffImageType, toCopyError, validatePayload };
|
|
1043
1078
|
|
|
1044
1079
|
//# sourceMappingURL=core.js.map
|