react-smart-copy 1.1.1 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +80 -12
- package/dist/capture.cjs +36 -2
- package/dist/capture.cjs.map +1 -1
- package/dist/capture.d.cts +18 -4
- package/dist/capture.d.ts +18 -4
- package/dist/capture.js +36 -2
- package/dist/capture.js.map +1 -1
- package/dist/core.cjs +176 -82
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.cts +108 -15
- package/dist/core.d.ts +108 -15
- package/dist/core.js +176 -83
- package/dist/core.js.map +1 -1
- package/dist/index.cjs +267 -106
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +136 -17
- package/dist/index.d.ts +136 -17
- package/dist/index.js +268 -108
- package/dist/index.js.map +1 -1
- package/package.json +8 -8
package/dist/core.d.cts
CHANGED
|
@@ -67,15 +67,34 @@ export declare function describeCopyError(error: CopyError): string;
|
|
|
67
67
|
/** Default English, user-facing sentence for a paste error. Replace for i18n. */
|
|
68
68
|
export declare function describePasteError(error: CopyError): string;
|
|
69
69
|
//#endregion
|
|
70
|
+
//#region src/core/machine-shared.d.ts
|
|
71
|
+
/**
|
|
72
|
+
* Internals shared by the copy and paste state machines. Kept in one module so
|
|
73
|
+
* apps that use both don't ship two copies.
|
|
74
|
+
*/
|
|
75
|
+
export declare const DEFAULT_MAX_RETRIES = 3;
|
|
76
|
+
/**
|
|
77
|
+
* Passed to adapters and lazy sources as their last argument. `signal` aborts
|
|
78
|
+
* when the operation is superseded, `reset()`, or its host unmounts, so
|
|
79
|
+
* expensive work (rasterising, decoding) can stop early.
|
|
80
|
+
*/
|
|
81
|
+
interface OperationContext {
|
|
82
|
+
readonly signal: AbortSignal;
|
|
83
|
+
}
|
|
84
|
+
export declare function resolveMaxRetries(value: number | undefined): number;
|
|
85
|
+
//#endregion
|
|
70
86
|
//#region src/core/payload.d.ts
|
|
71
87
|
/** The only image MIME type with reliable cross-browser clipboard write support. */
|
|
72
88
|
export declare const IMAGE_MIME_TYPE = "image/png";
|
|
73
89
|
/**
|
|
74
90
|
* An image as a Blob, a promise of one, or a function producing one.
|
|
75
91
|
* Prefer the function form: it is invoked synchronously inside the user
|
|
76
|
-
* gesture, which Safari requires for async image generation.
|
|
92
|
+
* gesture, which Safari requires for async image generation. The browser
|
|
93
|
+
* adapter always passes an `OperationContext`: stop work once
|
|
94
|
+
* `context.signal` aborts (reset, superseded, unmount). Optional in the type
|
|
95
|
+
* so adapters that call sources themselves keep compiling.
|
|
77
96
|
*/
|
|
78
|
-
export type BlobSource = Blob | PromiseLike<Blob> | (() => Blob | PromiseLike<Blob>);
|
|
97
|
+
export type BlobSource = Blob | PromiseLike<Blob> | ((context?: OperationContext) => Blob | PromiseLike<Blob>);
|
|
79
98
|
export interface TextPayload {
|
|
80
99
|
readonly kind: 'text';
|
|
81
100
|
readonly value: string;
|
|
@@ -171,10 +190,11 @@ export interface ClipboardEnvironment {
|
|
|
171
190
|
*
|
|
172
191
|
* Contract: start the platform write synchronously (before any `await`) so the
|
|
173
192
|
* browser still sees the user gesture, and reject with a `CopyFailure` when you
|
|
174
|
-
* can classify the error.
|
|
193
|
+
* can classify the error. `context.signal` aborts when the copy is reset or its
|
|
194
|
+
* host unmounts; honour it to stop expensive work early.
|
|
175
195
|
*/
|
|
176
196
|
export interface ClipboardAdapter {
|
|
177
|
-
write(payload: CopyPayload): Promise<void>;
|
|
197
|
+
write(payload: CopyPayload, context?: OperationContext): Promise<void>;
|
|
178
198
|
}
|
|
179
199
|
export interface BrowserClipboardAdapterOptions {
|
|
180
200
|
/** Defaults to `window`, read lazily at copy time (SSR-safe). */
|
|
@@ -212,7 +232,6 @@ export declare function createCopyCoordinator(): CopyCoordinator;
|
|
|
212
232
|
//#endregion
|
|
213
233
|
//#region src/core/copy-machine.d.ts
|
|
214
234
|
export declare const DEFAULT_RESET_AFTER_MS = 2000;
|
|
215
|
-
export declare const DEFAULT_MAX_RETRIES = 3;
|
|
216
235
|
export interface IdleState {
|
|
217
236
|
readonly status: 'idle';
|
|
218
237
|
}
|
|
@@ -236,7 +255,16 @@ export interface ErrorState {
|
|
|
236
255
|
}
|
|
237
256
|
export type CopyState = IdleState | CopyingState | CopiedState | ErrorState;
|
|
238
257
|
export type CopyStatus = CopyState['status'];
|
|
239
|
-
|
|
258
|
+
/**
|
|
259
|
+
* `cancelled`: the copy was reset or its host unmounted before it finished,
|
|
260
|
+
* so its work was aborted. Nothing to report to the user.
|
|
261
|
+
*/
|
|
262
|
+
export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
263
|
+
/**
|
|
264
|
+
* Why an in-flight copy was cancelled: `reset` (`reset()` was called) or
|
|
265
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted).
|
|
266
|
+
*/
|
|
267
|
+
export type CopyCancelReason = 'reset' | 'disconnect';
|
|
240
268
|
/** What `copy()`/`retry()` resolve to. They never reject. */
|
|
241
269
|
export type CopyOutcome = {
|
|
242
270
|
readonly status: 'copied';
|
|
@@ -265,6 +293,18 @@ export interface CopyMachineOptions {
|
|
|
265
293
|
readonly coordinator?: CopyCoordinator | null;
|
|
266
294
|
readonly onCopy?: (payload: CopyPayload) => void;
|
|
267
295
|
readonly onError?: (error: CopyError, payload: CopyPayload | null) => void;
|
|
296
|
+
/**
|
|
297
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
298
|
+
* called for the automatic return after `resetAfterMs`, for a `<CopyGroup>`
|
|
299
|
+
* handing "Copied" to another member, or when already `idle`.
|
|
300
|
+
*/
|
|
301
|
+
readonly onReset?: () => void;
|
|
302
|
+
/**
|
|
303
|
+
* A copy in flight was cancelled before it settled: its `signal` aborted
|
|
304
|
+
* and its result will not reach state or `onCopy` / `onError`. Fires
|
|
305
|
+
* before `onReset` when `reset()` cancels a copy.
|
|
306
|
+
*/
|
|
307
|
+
readonly onCancel?: (reason: CopyCancelReason) => void;
|
|
268
308
|
/** Clock injection for tests and deterministic environments. */
|
|
269
309
|
readonly now?: () => number;
|
|
270
310
|
}
|
|
@@ -275,16 +315,17 @@ export interface CopyMachine {
|
|
|
275
315
|
readonly subscribe: (listener: () => void) => () => void;
|
|
276
316
|
readonly copy: (source: CopySource) => Promise<CopyOutcome>;
|
|
277
317
|
readonly retry: () => Promise<CopyOutcome>;
|
|
318
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
278
319
|
readonly reset: () => void;
|
|
279
320
|
/**
|
|
280
321
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
281
|
-
* cleanup clears timers, drops in-flight results
|
|
322
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
323
|
+
* unsticks `copying`.
|
|
282
324
|
* Safe to call repeatedly (React StrictMode).
|
|
283
325
|
*/
|
|
284
326
|
readonly connect: () => () => void;
|
|
285
327
|
}
|
|
286
328
|
export declare const IDLE_STATE: IdleState;
|
|
287
|
-
export declare function resolveMaxRetries(value: number | undefined): number;
|
|
288
329
|
/** Pure helper: can `retry()` do anything from this state? */
|
|
289
330
|
export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
|
|
290
331
|
/** Framework-agnostic copy state machine. */
|
|
@@ -300,7 +341,11 @@ type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
|
300
341
|
*/
|
|
301
342
|
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
302
343
|
interface PasteLimits {
|
|
303
|
-
/**
|
|
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
|
+
*/
|
|
304
349
|
readonly maxBytes?: number;
|
|
305
350
|
/** Max number of accepted items (types + files). Default 32. */
|
|
306
351
|
readonly maxItems?: number;
|
|
@@ -339,7 +384,14 @@ interface PasteResult {
|
|
|
339
384
|
readonly images: readonly Blob[];
|
|
340
385
|
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
341
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[];
|
|
342
392
|
}
|
|
393
|
+
/** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
|
|
394
|
+
type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
|
|
343
395
|
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
344
396
|
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
345
397
|
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
@@ -374,9 +426,11 @@ interface PasteEnvironment {
|
|
|
374
426
|
*
|
|
375
427
|
* Contract: call the platform API synchronously (before any `await`) so the
|
|
376
428
|
* browser still sees the user gesture, and reject with a `CopyFailure`.
|
|
429
|
+
* `context.signal` aborts when the read is superseded, reset, or its host
|
|
430
|
+
* unmounts; honour it to stop decoding early.
|
|
377
431
|
*/
|
|
378
432
|
interface PasteAdapter {
|
|
379
|
-
read(options: ResolvedPasteReadOptions): Promise<
|
|
433
|
+
read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteReadResult>;
|
|
380
434
|
}
|
|
381
435
|
interface BrowserPasteAdapterOptions {
|
|
382
436
|
/** Defaults to `window`, read lazily at paste time (SSR-safe). */
|
|
@@ -401,11 +455,25 @@ export interface PasteReadState {
|
|
|
401
455
|
export interface PasteErrorState {
|
|
402
456
|
readonly status: 'error';
|
|
403
457
|
readonly error: CopyError;
|
|
458
|
+
/** Where the failed read came from. Only `'clipboard'` reads can be retried. */
|
|
459
|
+
readonly source: PasteSource;
|
|
460
|
+
/** `retry()` calls made since the last fresh `paste()`. */
|
|
461
|
+
readonly retryCount: number;
|
|
404
462
|
}
|
|
405
463
|
export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
|
|
406
464
|
export type PasteStatus = PasteState['status'];
|
|
407
|
-
|
|
408
|
-
|
|
465
|
+
/**
|
|
466
|
+
* `cancelled`: the read was superseded, reset, or its host unmounted before it
|
|
467
|
+
* finished, so its work was aborted. Nothing to report to the user.
|
|
468
|
+
*/
|
|
469
|
+
export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
470
|
+
/**
|
|
471
|
+
* Why an in-flight read was cancelled: `reset` (`reset()` was called),
|
|
472
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted) or
|
|
473
|
+
* `superseded` (a paste event arrived while a clipboard read was pending).
|
|
474
|
+
*/
|
|
475
|
+
export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
|
|
476
|
+
/** What `paste()` / `pasteEvent()` / `retry()` resolve to. They never reject. */
|
|
409
477
|
export type PasteOutcome = {
|
|
410
478
|
readonly status: 'read';
|
|
411
479
|
readonly result: PasteResult;
|
|
@@ -431,8 +499,24 @@ export interface PasteMachineOptions extends PasteReadOptions {
|
|
|
431
499
|
* accepted content, so the browser doesn't also insert it. Default `true`.
|
|
432
500
|
*/
|
|
433
501
|
readonly preventDefault?: boolean;
|
|
502
|
+
/**
|
|
503
|
+
* Max `retry()` calls after a failed clipboard read. Default 3. `0`
|
|
504
|
+
* disables retry; `Infinity` allows unlimited retries.
|
|
505
|
+
*/
|
|
506
|
+
readonly maxRetries?: number;
|
|
434
507
|
readonly onPaste?: (result: PasteResult) => void;
|
|
435
508
|
readonly onError?: (error: CopyError) => void;
|
|
509
|
+
/**
|
|
510
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
511
|
+
* called for the automatic return after `resetAfterMs`, or when already `idle`.
|
|
512
|
+
*/
|
|
513
|
+
readonly onReset?: () => void;
|
|
514
|
+
/**
|
|
515
|
+
* A read in flight was cancelled before it settled: its `signal` aborted
|
|
516
|
+
* and its result will not reach state or `onPaste` / `onError`. Fires
|
|
517
|
+
* before `onReset` when `reset()` cancels a read.
|
|
518
|
+
*/
|
|
519
|
+
readonly onCancel?: (reason: PasteCancelReason) => void;
|
|
436
520
|
/** Clock injection for tests and deterministic environments. */
|
|
437
521
|
readonly now?: () => number;
|
|
438
522
|
}
|
|
@@ -452,18 +536,27 @@ export interface PasteMachine {
|
|
|
452
536
|
* accepted content are ignored and left untouched for the browser.
|
|
453
537
|
*/
|
|
454
538
|
readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
|
|
455
|
-
/**
|
|
539
|
+
/**
|
|
540
|
+
* Re-reads the clipboard after a retryable failure (e.g. permission denied,
|
|
541
|
+
* page not focused), up to `maxRetries`. Call it from a user gesture.
|
|
542
|
+
* Paste-event failures can't be retried: their data is gone after dispatch.
|
|
543
|
+
*/
|
|
544
|
+
readonly retry: () => Promise<PasteOutcome>;
|
|
545
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
456
546
|
readonly reset: () => void;
|
|
457
547
|
/**
|
|
458
548
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
459
|
-
* cleanup clears timers, drops in-flight results
|
|
549
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
550
|
+
* unsticks `reading`.
|
|
460
551
|
* Safe to call repeatedly (React StrictMode).
|
|
461
552
|
*/
|
|
462
553
|
readonly connect: () => () => void;
|
|
463
554
|
}
|
|
464
555
|
export declare const PASTE_IDLE_STATE: PasteIdleState;
|
|
556
|
+
/** Pure helper: can `retry()` do anything from this state? */
|
|
557
|
+
export declare function canRetryPasteState(state: PasteState, maxRetries?: number): boolean;
|
|
465
558
|
/** Framework-agnostic paste state machine. */
|
|
466
559
|
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
467
560
|
//#endregion
|
|
468
|
-
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
561
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
469
562
|
//# sourceMappingURL=core.d.cts.map
|
package/dist/core.d.ts
CHANGED
|
@@ -67,15 +67,34 @@ export declare function describeCopyError(error: CopyError): string;
|
|
|
67
67
|
/** Default English, user-facing sentence for a paste error. Replace for i18n. */
|
|
68
68
|
export declare function describePasteError(error: CopyError): string;
|
|
69
69
|
//#endregion
|
|
70
|
+
//#region src/core/machine-shared.d.ts
|
|
71
|
+
/**
|
|
72
|
+
* Internals shared by the copy and paste state machines. Kept in one module so
|
|
73
|
+
* apps that use both don't ship two copies.
|
|
74
|
+
*/
|
|
75
|
+
export declare const DEFAULT_MAX_RETRIES = 3;
|
|
76
|
+
/**
|
|
77
|
+
* Passed to adapters and lazy sources as their last argument. `signal` aborts
|
|
78
|
+
* when the operation is superseded, `reset()`, or its host unmounts, so
|
|
79
|
+
* expensive work (rasterising, decoding) can stop early.
|
|
80
|
+
*/
|
|
81
|
+
interface OperationContext {
|
|
82
|
+
readonly signal: AbortSignal;
|
|
83
|
+
}
|
|
84
|
+
export declare function resolveMaxRetries(value: number | undefined): number;
|
|
85
|
+
//#endregion
|
|
70
86
|
//#region src/core/payload.d.ts
|
|
71
87
|
/** The only image MIME type with reliable cross-browser clipboard write support. */
|
|
72
88
|
export declare const IMAGE_MIME_TYPE = "image/png";
|
|
73
89
|
/**
|
|
74
90
|
* An image as a Blob, a promise of one, or a function producing one.
|
|
75
91
|
* Prefer the function form: it is invoked synchronously inside the user
|
|
76
|
-
* gesture, which Safari requires for async image generation.
|
|
92
|
+
* gesture, which Safari requires for async image generation. The browser
|
|
93
|
+
* adapter always passes an `OperationContext`: stop work once
|
|
94
|
+
* `context.signal` aborts (reset, superseded, unmount). Optional in the type
|
|
95
|
+
* so adapters that call sources themselves keep compiling.
|
|
77
96
|
*/
|
|
78
|
-
export type BlobSource = Blob | PromiseLike<Blob> | (() => Blob | PromiseLike<Blob>);
|
|
97
|
+
export type BlobSource = Blob | PromiseLike<Blob> | ((context?: OperationContext) => Blob | PromiseLike<Blob>);
|
|
79
98
|
export interface TextPayload {
|
|
80
99
|
readonly kind: 'text';
|
|
81
100
|
readonly value: string;
|
|
@@ -171,10 +190,11 @@ export interface ClipboardEnvironment {
|
|
|
171
190
|
*
|
|
172
191
|
* Contract: start the platform write synchronously (before any `await`) so the
|
|
173
192
|
* browser still sees the user gesture, and reject with a `CopyFailure` when you
|
|
174
|
-
* can classify the error.
|
|
193
|
+
* can classify the error. `context.signal` aborts when the copy is reset or its
|
|
194
|
+
* host unmounts; honour it to stop expensive work early.
|
|
175
195
|
*/
|
|
176
196
|
export interface ClipboardAdapter {
|
|
177
|
-
write(payload: CopyPayload): Promise<void>;
|
|
197
|
+
write(payload: CopyPayload, context?: OperationContext): Promise<void>;
|
|
178
198
|
}
|
|
179
199
|
export interface BrowserClipboardAdapterOptions {
|
|
180
200
|
/** Defaults to `window`, read lazily at copy time (SSR-safe). */
|
|
@@ -212,7 +232,6 @@ export declare function createCopyCoordinator(): CopyCoordinator;
|
|
|
212
232
|
//#endregion
|
|
213
233
|
//#region src/core/copy-machine.d.ts
|
|
214
234
|
export declare const DEFAULT_RESET_AFTER_MS = 2000;
|
|
215
|
-
export declare const DEFAULT_MAX_RETRIES = 3;
|
|
216
235
|
export interface IdleState {
|
|
217
236
|
readonly status: 'idle';
|
|
218
237
|
}
|
|
@@ -236,7 +255,16 @@ export interface ErrorState {
|
|
|
236
255
|
}
|
|
237
256
|
export type CopyState = IdleState | CopyingState | CopiedState | ErrorState;
|
|
238
257
|
export type CopyStatus = CopyState['status'];
|
|
239
|
-
|
|
258
|
+
/**
|
|
259
|
+
* `cancelled`: the copy was reset or its host unmounted before it finished,
|
|
260
|
+
* so its work was aborted. Nothing to report to the user.
|
|
261
|
+
*/
|
|
262
|
+
export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
263
|
+
/**
|
|
264
|
+
* Why an in-flight copy was cancelled: `reset` (`reset()` was called) or
|
|
265
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted).
|
|
266
|
+
*/
|
|
267
|
+
export type CopyCancelReason = 'reset' | 'disconnect';
|
|
240
268
|
/** What `copy()`/`retry()` resolve to. They never reject. */
|
|
241
269
|
export type CopyOutcome = {
|
|
242
270
|
readonly status: 'copied';
|
|
@@ -265,6 +293,18 @@ export interface CopyMachineOptions {
|
|
|
265
293
|
readonly coordinator?: CopyCoordinator | null;
|
|
266
294
|
readonly onCopy?: (payload: CopyPayload) => void;
|
|
267
295
|
readonly onError?: (error: CopyError, payload: CopyPayload | null) => void;
|
|
296
|
+
/**
|
|
297
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
298
|
+
* called for the automatic return after `resetAfterMs`, for a `<CopyGroup>`
|
|
299
|
+
* handing "Copied" to another member, or when already `idle`.
|
|
300
|
+
*/
|
|
301
|
+
readonly onReset?: () => void;
|
|
302
|
+
/**
|
|
303
|
+
* A copy in flight was cancelled before it settled: its `signal` aborted
|
|
304
|
+
* and its result will not reach state or `onCopy` / `onError`. Fires
|
|
305
|
+
* before `onReset` when `reset()` cancels a copy.
|
|
306
|
+
*/
|
|
307
|
+
readonly onCancel?: (reason: CopyCancelReason) => void;
|
|
268
308
|
/** Clock injection for tests and deterministic environments. */
|
|
269
309
|
readonly now?: () => number;
|
|
270
310
|
}
|
|
@@ -275,16 +315,17 @@ export interface CopyMachine {
|
|
|
275
315
|
readonly subscribe: (listener: () => void) => () => void;
|
|
276
316
|
readonly copy: (source: CopySource) => Promise<CopyOutcome>;
|
|
277
317
|
readonly retry: () => Promise<CopyOutcome>;
|
|
318
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
278
319
|
readonly reset: () => void;
|
|
279
320
|
/**
|
|
280
321
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
281
|
-
* cleanup clears timers, drops in-flight results
|
|
322
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
323
|
+
* unsticks `copying`.
|
|
282
324
|
* Safe to call repeatedly (React StrictMode).
|
|
283
325
|
*/
|
|
284
326
|
readonly connect: () => () => void;
|
|
285
327
|
}
|
|
286
328
|
export declare const IDLE_STATE: IdleState;
|
|
287
|
-
export declare function resolveMaxRetries(value: number | undefined): number;
|
|
288
329
|
/** Pure helper: can `retry()` do anything from this state? */
|
|
289
330
|
export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
|
|
290
331
|
/** Framework-agnostic copy state machine. */
|
|
@@ -300,7 +341,11 @@ type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
|
300
341
|
*/
|
|
301
342
|
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
302
343
|
interface PasteLimits {
|
|
303
|
-
/**
|
|
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
|
+
*/
|
|
304
349
|
readonly maxBytes?: number;
|
|
305
350
|
/** Max number of accepted items (types + files). Default 32. */
|
|
306
351
|
readonly maxItems?: number;
|
|
@@ -339,7 +384,14 @@ interface PasteResult {
|
|
|
339
384
|
readonly images: readonly Blob[];
|
|
340
385
|
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
341
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[];
|
|
342
392
|
}
|
|
393
|
+
/** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
|
|
394
|
+
type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
|
|
343
395
|
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
344
396
|
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
345
397
|
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
@@ -374,9 +426,11 @@ interface PasteEnvironment {
|
|
|
374
426
|
*
|
|
375
427
|
* Contract: call the platform API synchronously (before any `await`) so the
|
|
376
428
|
* browser still sees the user gesture, and reject with a `CopyFailure`.
|
|
429
|
+
* `context.signal` aborts when the read is superseded, reset, or its host
|
|
430
|
+
* unmounts; honour it to stop decoding early.
|
|
377
431
|
*/
|
|
378
432
|
interface PasteAdapter {
|
|
379
|
-
read(options: ResolvedPasteReadOptions): Promise<
|
|
433
|
+
read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteReadResult>;
|
|
380
434
|
}
|
|
381
435
|
interface BrowserPasteAdapterOptions {
|
|
382
436
|
/** Defaults to `window`, read lazily at paste time (SSR-safe). */
|
|
@@ -401,11 +455,25 @@ export interface PasteReadState {
|
|
|
401
455
|
export interface PasteErrorState {
|
|
402
456
|
readonly status: 'error';
|
|
403
457
|
readonly error: CopyError;
|
|
458
|
+
/** Where the failed read came from. Only `'clipboard'` reads can be retried. */
|
|
459
|
+
readonly source: PasteSource;
|
|
460
|
+
/** `retry()` calls made since the last fresh `paste()`. */
|
|
461
|
+
readonly retryCount: number;
|
|
404
462
|
}
|
|
405
463
|
export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
|
|
406
464
|
export type PasteStatus = PasteState['status'];
|
|
407
|
-
|
|
408
|
-
|
|
465
|
+
/**
|
|
466
|
+
* `cancelled`: the read was superseded, reset, or its host unmounted before it
|
|
467
|
+
* finished, so its work was aborted. Nothing to report to the user.
|
|
468
|
+
*/
|
|
469
|
+
export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
470
|
+
/**
|
|
471
|
+
* Why an in-flight read was cancelled: `reset` (`reset()` was called),
|
|
472
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted) or
|
|
473
|
+
* `superseded` (a paste event arrived while a clipboard read was pending).
|
|
474
|
+
*/
|
|
475
|
+
export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
|
|
476
|
+
/** What `paste()` / `pasteEvent()` / `retry()` resolve to. They never reject. */
|
|
409
477
|
export type PasteOutcome = {
|
|
410
478
|
readonly status: 'read';
|
|
411
479
|
readonly result: PasteResult;
|
|
@@ -431,8 +499,24 @@ export interface PasteMachineOptions extends PasteReadOptions {
|
|
|
431
499
|
* accepted content, so the browser doesn't also insert it. Default `true`.
|
|
432
500
|
*/
|
|
433
501
|
readonly preventDefault?: boolean;
|
|
502
|
+
/**
|
|
503
|
+
* Max `retry()` calls after a failed clipboard read. Default 3. `0`
|
|
504
|
+
* disables retry; `Infinity` allows unlimited retries.
|
|
505
|
+
*/
|
|
506
|
+
readonly maxRetries?: number;
|
|
434
507
|
readonly onPaste?: (result: PasteResult) => void;
|
|
435
508
|
readonly onError?: (error: CopyError) => void;
|
|
509
|
+
/**
|
|
510
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
511
|
+
* called for the automatic return after `resetAfterMs`, or when already `idle`.
|
|
512
|
+
*/
|
|
513
|
+
readonly onReset?: () => void;
|
|
514
|
+
/**
|
|
515
|
+
* A read in flight was cancelled before it settled: its `signal` aborted
|
|
516
|
+
* and its result will not reach state or `onPaste` / `onError`. Fires
|
|
517
|
+
* before `onReset` when `reset()` cancels a read.
|
|
518
|
+
*/
|
|
519
|
+
readonly onCancel?: (reason: PasteCancelReason) => void;
|
|
436
520
|
/** Clock injection for tests and deterministic environments. */
|
|
437
521
|
readonly now?: () => number;
|
|
438
522
|
}
|
|
@@ -452,18 +536,27 @@ export interface PasteMachine {
|
|
|
452
536
|
* accepted content are ignored and left untouched for the browser.
|
|
453
537
|
*/
|
|
454
538
|
readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
|
|
455
|
-
/**
|
|
539
|
+
/**
|
|
540
|
+
* Re-reads the clipboard after a retryable failure (e.g. permission denied,
|
|
541
|
+
* page not focused), up to `maxRetries`. Call it from a user gesture.
|
|
542
|
+
* Paste-event failures can't be retried: their data is gone after dispatch.
|
|
543
|
+
*/
|
|
544
|
+
readonly retry: () => Promise<PasteOutcome>;
|
|
545
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
456
546
|
readonly reset: () => void;
|
|
457
547
|
/**
|
|
458
548
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
459
|
-
* cleanup clears timers, drops in-flight results
|
|
549
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
550
|
+
* unsticks `reading`.
|
|
460
551
|
* Safe to call repeatedly (React StrictMode).
|
|
461
552
|
*/
|
|
462
553
|
readonly connect: () => () => void;
|
|
463
554
|
}
|
|
464
555
|
export declare const PASTE_IDLE_STATE: PasteIdleState;
|
|
556
|
+
/** Pure helper: can `retry()` do anything from this state? */
|
|
557
|
+
export declare function canRetryPasteState(state: PasteState, maxRetries?: number): boolean;
|
|
465
558
|
/** Framework-agnostic paste state machine. */
|
|
466
559
|
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
467
560
|
//#endregion
|
|
468
|
-
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
561
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
469
562
|
//# sourceMappingURL=core.d.ts.map
|