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/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
- /** Default English, user-facing sentence for a paste error. Replace for i18n. */
68
- export declare function describePasteError(error: CopyError): string;
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 clipboard read was pending).
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 only: call `event.preventDefault()` when the event carried
499
- * accepted content, so the browser doesn't also insert it. Default `true`.
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
- /** Default English, user-facing sentence for a paste error. Replace for i18n. */
68
- export declare function describePasteError(error: CopyError): string;
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 clipboard read was pending).
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 only: call `event.preventDefault()` when the event carried
499
- * accepted content, so the browser doesn't also insert it. Default `true`.
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
- /** Default English, user-facing sentence for a paste error. Replace for i18n. */
103
- function describePasteError(error) {
104
- return PASTE_DESCRIPTIONS[error.type];
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 clipboard holds nothing that matches `accept`.");
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
- const pasteEvent = (event) => {
981
- const data = event.clipboardData;
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, "event", 0);
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, "event", resolved);
1005
- }, "event", 0);
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