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/index.d.cts
CHANGED
|
@@ -69,15 +69,34 @@ export declare function describeCopyError(error: CopyError): string;
|
|
|
69
69
|
/** Default English, user-facing sentence for a paste error. Replace for i18n. */
|
|
70
70
|
export declare function describePasteError(error: CopyError): string;
|
|
71
71
|
//#endregion
|
|
72
|
+
//#region src/core/machine-shared.d.ts
|
|
73
|
+
/**
|
|
74
|
+
* Internals shared by the copy and paste state machines. Kept in one module so
|
|
75
|
+
* apps that use both don't ship two copies.
|
|
76
|
+
*/
|
|
77
|
+
export declare const DEFAULT_MAX_RETRIES = 3;
|
|
78
|
+
/**
|
|
79
|
+
* Passed to adapters and lazy sources as their last argument. `signal` aborts
|
|
80
|
+
* when the operation is superseded, `reset()`, or its host unmounts, so
|
|
81
|
+
* expensive work (rasterising, decoding) can stop early.
|
|
82
|
+
*/
|
|
83
|
+
interface OperationContext {
|
|
84
|
+
readonly signal: AbortSignal;
|
|
85
|
+
}
|
|
86
|
+
export declare function resolveMaxRetries(value: number | undefined): number;
|
|
87
|
+
//#endregion
|
|
72
88
|
//#region src/core/payload.d.ts
|
|
73
89
|
/** The only image MIME type with reliable cross-browser clipboard write support. */
|
|
74
90
|
export declare const IMAGE_MIME_TYPE = "image/png";
|
|
75
91
|
/**
|
|
76
92
|
* An image as a Blob, a promise of one, or a function producing one.
|
|
77
93
|
* Prefer the function form: it is invoked synchronously inside the user
|
|
78
|
-
* gesture, which Safari requires for async image generation.
|
|
94
|
+
* gesture, which Safari requires for async image generation. The browser
|
|
95
|
+
* adapter always passes an `OperationContext`: stop work once
|
|
96
|
+
* `context.signal` aborts (reset, superseded, unmount). Optional in the type
|
|
97
|
+
* so adapters that call sources themselves keep compiling.
|
|
79
98
|
*/
|
|
80
|
-
export type BlobSource = Blob | PromiseLike<Blob> | (() => Blob | PromiseLike<Blob>);
|
|
99
|
+
export type BlobSource = Blob | PromiseLike<Blob> | ((context?: OperationContext) => Blob | PromiseLike<Blob>);
|
|
81
100
|
export interface TextPayload {
|
|
82
101
|
readonly kind: 'text';
|
|
83
102
|
readonly value: string;
|
|
@@ -173,10 +192,11 @@ export interface ClipboardEnvironment {
|
|
|
173
192
|
*
|
|
174
193
|
* Contract: start the platform write synchronously (before any `await`) so the
|
|
175
194
|
* browser still sees the user gesture, and reject with a `CopyFailure` when you
|
|
176
|
-
* can classify the error.
|
|
195
|
+
* can classify the error. `context.signal` aborts when the copy is reset or its
|
|
196
|
+
* host unmounts; honour it to stop expensive work early.
|
|
177
197
|
*/
|
|
178
198
|
export interface ClipboardAdapter {
|
|
179
|
-
write(payload: CopyPayload): Promise<void>;
|
|
199
|
+
write(payload: CopyPayload, context?: OperationContext): Promise<void>;
|
|
180
200
|
}
|
|
181
201
|
export interface BrowserClipboardAdapterOptions {
|
|
182
202
|
/** Defaults to `window`, read lazily at copy time (SSR-safe). */
|
|
@@ -214,7 +234,6 @@ export declare function createCopyCoordinator(): CopyCoordinator;
|
|
|
214
234
|
//#endregion
|
|
215
235
|
//#region src/core/copy-machine.d.ts
|
|
216
236
|
export declare const DEFAULT_RESET_AFTER_MS = 2000;
|
|
217
|
-
export declare const DEFAULT_MAX_RETRIES = 3;
|
|
218
237
|
export interface IdleState {
|
|
219
238
|
readonly status: 'idle';
|
|
220
239
|
}
|
|
@@ -238,7 +257,16 @@ export interface ErrorState {
|
|
|
238
257
|
}
|
|
239
258
|
export type CopyState = IdleState | CopyingState | CopiedState | ErrorState;
|
|
240
259
|
export type CopyStatus = CopyState['status'];
|
|
241
|
-
|
|
260
|
+
/**
|
|
261
|
+
* `cancelled`: the copy was reset or its host unmounted before it finished,
|
|
262
|
+
* so its work was aborted. Nothing to report to the user.
|
|
263
|
+
*/
|
|
264
|
+
export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
265
|
+
/**
|
|
266
|
+
* Why an in-flight copy was cancelled: `reset` (`reset()` was called) or
|
|
267
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted).
|
|
268
|
+
*/
|
|
269
|
+
export type CopyCancelReason = 'reset' | 'disconnect';
|
|
242
270
|
/** What `copy()`/`retry()` resolve to. They never reject. */
|
|
243
271
|
export type CopyOutcome = {
|
|
244
272
|
readonly status: 'copied';
|
|
@@ -267,6 +295,18 @@ export interface CopyMachineOptions {
|
|
|
267
295
|
readonly coordinator?: CopyCoordinator | null;
|
|
268
296
|
readonly onCopy?: (payload: CopyPayload) => void;
|
|
269
297
|
readonly onError?: (error: CopyError, payload: CopyPayload | null) => void;
|
|
298
|
+
/**
|
|
299
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
300
|
+
* called for the automatic return after `resetAfterMs`, for a `<CopyGroup>`
|
|
301
|
+
* handing "Copied" to another member, or when already `idle`.
|
|
302
|
+
*/
|
|
303
|
+
readonly onReset?: () => void;
|
|
304
|
+
/**
|
|
305
|
+
* A copy in flight was cancelled before it settled: its `signal` aborted
|
|
306
|
+
* and its result will not reach state or `onCopy` / `onError`. Fires
|
|
307
|
+
* before `onReset` when `reset()` cancels a copy.
|
|
308
|
+
*/
|
|
309
|
+
readonly onCancel?: (reason: CopyCancelReason) => void;
|
|
270
310
|
/** Clock injection for tests and deterministic environments. */
|
|
271
311
|
readonly now?: () => number;
|
|
272
312
|
}
|
|
@@ -277,16 +317,17 @@ export interface CopyMachine {
|
|
|
277
317
|
readonly subscribe: (listener: () => void) => () => void;
|
|
278
318
|
readonly copy: (source: CopySource) => Promise<CopyOutcome>;
|
|
279
319
|
readonly retry: () => Promise<CopyOutcome>;
|
|
320
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
280
321
|
readonly reset: () => void;
|
|
281
322
|
/**
|
|
282
323
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
283
|
-
* cleanup clears timers, drops in-flight results
|
|
324
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
325
|
+
* unsticks `copying`.
|
|
284
326
|
* Safe to call repeatedly (React StrictMode).
|
|
285
327
|
*/
|
|
286
328
|
readonly connect: () => () => void;
|
|
287
329
|
}
|
|
288
330
|
export declare const IDLE_STATE: IdleState;
|
|
289
|
-
export declare function resolveMaxRetries(value: number | undefined): number;
|
|
290
331
|
/** Pure helper: can `retry()` do anything from this state? */
|
|
291
332
|
export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
|
|
292
333
|
/** Framework-agnostic copy state machine. */
|
|
@@ -302,7 +343,11 @@ type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
|
302
343
|
*/
|
|
303
344
|
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
304
345
|
interface PasteLimits {
|
|
305
|
-
/**
|
|
346
|
+
/**
|
|
347
|
+
* Total size cap across all accepted items, in UTF-8 bytes. Strings are measured as
|
|
348
|
+
* they would be encoded, matching `Blob.size`, so every paste path counts the same way.
|
|
349
|
+
* Default 32 MiB.
|
|
350
|
+
*/
|
|
306
351
|
readonly maxBytes?: number;
|
|
307
352
|
/** Max number of accepted items (types + files). Default 32. */
|
|
308
353
|
readonly maxItems?: number;
|
|
@@ -341,7 +386,14 @@ interface PasteResult {
|
|
|
341
386
|
readonly images: readonly Blob[];
|
|
342
387
|
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
343
388
|
readonly files: readonly File[];
|
|
389
|
+
/**
|
|
390
|
+
* The entries of `files` that are also in `images`: verified image files, keeping their
|
|
391
|
+
* names, ready for `FormData`. Derived by the paste machine, so it is always consistent.
|
|
392
|
+
*/
|
|
393
|
+
readonly imageFiles: readonly File[];
|
|
344
394
|
}
|
|
395
|
+
/** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
|
|
396
|
+
type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
|
|
345
397
|
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
346
398
|
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
347
399
|
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
@@ -376,9 +428,11 @@ interface PasteEnvironment {
|
|
|
376
428
|
*
|
|
377
429
|
* Contract: call the platform API synchronously (before any `await`) so the
|
|
378
430
|
* browser still sees the user gesture, and reject with a `CopyFailure`.
|
|
431
|
+
* `context.signal` aborts when the read is superseded, reset, or its host
|
|
432
|
+
* unmounts; honour it to stop decoding early.
|
|
379
433
|
*/
|
|
380
434
|
interface PasteAdapter {
|
|
381
|
-
read(options: ResolvedPasteReadOptions): Promise<
|
|
435
|
+
read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteReadResult>;
|
|
382
436
|
}
|
|
383
437
|
interface BrowserPasteAdapterOptions {
|
|
384
438
|
/** Defaults to `window`, read lazily at paste time (SSR-safe). */
|
|
@@ -403,11 +457,25 @@ export interface PasteReadState {
|
|
|
403
457
|
export interface PasteErrorState {
|
|
404
458
|
readonly status: 'error';
|
|
405
459
|
readonly error: CopyError;
|
|
460
|
+
/** Where the failed read came from. Only `'clipboard'` reads can be retried. */
|
|
461
|
+
readonly source: PasteSource;
|
|
462
|
+
/** `retry()` calls made since the last fresh `paste()`. */
|
|
463
|
+
readonly retryCount: number;
|
|
406
464
|
}
|
|
407
465
|
export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
|
|
408
466
|
export type PasteStatus = PasteState['status'];
|
|
409
|
-
|
|
410
|
-
|
|
467
|
+
/**
|
|
468
|
+
* `cancelled`: the read was superseded, reset, or its host unmounted before it
|
|
469
|
+
* finished, so its work was aborted. Nothing to report to the user.
|
|
470
|
+
*/
|
|
471
|
+
export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
472
|
+
/**
|
|
473
|
+
* Why an in-flight read was cancelled: `reset` (`reset()` was called),
|
|
474
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted) or
|
|
475
|
+
* `superseded` (a paste event arrived while a clipboard read was pending).
|
|
476
|
+
*/
|
|
477
|
+
export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
|
|
478
|
+
/** What `paste()` / `pasteEvent()` / `retry()` resolve to. They never reject. */
|
|
411
479
|
export type PasteOutcome = {
|
|
412
480
|
readonly status: 'read';
|
|
413
481
|
readonly result: PasteResult;
|
|
@@ -433,8 +501,24 @@ export interface PasteMachineOptions extends PasteReadOptions {
|
|
|
433
501
|
* accepted content, so the browser doesn't also insert it. Default `true`.
|
|
434
502
|
*/
|
|
435
503
|
readonly preventDefault?: boolean;
|
|
504
|
+
/**
|
|
505
|
+
* Max `retry()` calls after a failed clipboard read. Default 3. `0`
|
|
506
|
+
* disables retry; `Infinity` allows unlimited retries.
|
|
507
|
+
*/
|
|
508
|
+
readonly maxRetries?: number;
|
|
436
509
|
readonly onPaste?: (result: PasteResult) => void;
|
|
437
510
|
readonly onError?: (error: CopyError) => void;
|
|
511
|
+
/**
|
|
512
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
513
|
+
* called for the automatic return after `resetAfterMs`, or when already `idle`.
|
|
514
|
+
*/
|
|
515
|
+
readonly onReset?: () => void;
|
|
516
|
+
/**
|
|
517
|
+
* A read in flight was cancelled before it settled: its `signal` aborted
|
|
518
|
+
* and its result will not reach state or `onPaste` / `onError`. Fires
|
|
519
|
+
* before `onReset` when `reset()` cancels a read.
|
|
520
|
+
*/
|
|
521
|
+
readonly onCancel?: (reason: PasteCancelReason) => void;
|
|
438
522
|
/** Clock injection for tests and deterministic environments. */
|
|
439
523
|
readonly now?: () => number;
|
|
440
524
|
}
|
|
@@ -454,16 +538,25 @@ export interface PasteMachine {
|
|
|
454
538
|
* accepted content are ignored and left untouched for the browser.
|
|
455
539
|
*/
|
|
456
540
|
readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
|
|
457
|
-
/**
|
|
541
|
+
/**
|
|
542
|
+
* Re-reads the clipboard after a retryable failure (e.g. permission denied,
|
|
543
|
+
* page not focused), up to `maxRetries`. Call it from a user gesture.
|
|
544
|
+
* Paste-event failures can't be retried: their data is gone after dispatch.
|
|
545
|
+
*/
|
|
546
|
+
readonly retry: () => Promise<PasteOutcome>;
|
|
547
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
458
548
|
readonly reset: () => void;
|
|
459
549
|
/**
|
|
460
550
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
461
|
-
* cleanup clears timers, drops in-flight results
|
|
551
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
552
|
+
* unsticks `reading`.
|
|
462
553
|
* Safe to call repeatedly (React StrictMode).
|
|
463
554
|
*/
|
|
464
555
|
readonly connect: () => () => void;
|
|
465
556
|
}
|
|
466
557
|
export declare const PASTE_IDLE_STATE: PasteIdleState;
|
|
558
|
+
/** Pure helper: can `retry()` do anything from this state? */
|
|
559
|
+
export declare function canRetryPasteState(state: PasteState, maxRetries?: number): boolean;
|
|
467
560
|
/** Framework-agnostic paste state machine. */
|
|
468
561
|
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
469
562
|
//#endregion
|
|
@@ -480,7 +573,7 @@ interface UseCopyResult {
|
|
|
480
573
|
readonly copy: CopyMachine['copy'];
|
|
481
574
|
/** Stable identity. Re-attempts the last failed payload, up to `maxRetries`. */
|
|
482
575
|
readonly retry: CopyMachine['retry'];
|
|
483
|
-
/** Stable identity. Back to `idle`, discarding any in-flight
|
|
576
|
+
/** Stable identity. Back to `idle`, discarding and aborting any in-flight copy. */
|
|
484
577
|
readonly reset: CopyMachine['reset'];
|
|
485
578
|
}
|
|
486
579
|
/**
|
|
@@ -657,11 +750,15 @@ interface UsePasteResult<T extends Element = HTMLElement> {
|
|
|
657
750
|
/** The latest result while `status === 'read'`, otherwise `null`. */
|
|
658
751
|
readonly result: PasteResult | null;
|
|
659
752
|
readonly error: CopyError | null;
|
|
753
|
+
/** Whether `retry()` can do anything right now. */
|
|
754
|
+
readonly canRetry: boolean;
|
|
660
755
|
/** Stable identity. Reads the clipboard from a user gesture. Never rejects. */
|
|
661
756
|
readonly paste: PasteMachine['paste'];
|
|
662
757
|
/** Stable identity. Handles a paste event you received yourself. Never rejects. */
|
|
663
758
|
readonly pasteEvent: PasteMachine['pasteEvent'];
|
|
664
|
-
/** Stable identity.
|
|
759
|
+
/** Stable identity. Re-reads the clipboard after a retryable failure, up to `maxRetries`. */
|
|
760
|
+
readonly retry: PasteMachine['retry'];
|
|
761
|
+
/** Stable identity. Back to `idle`, discarding and aborting any in-flight read. */
|
|
665
762
|
readonly reset: PasteMachine['reset'];
|
|
666
763
|
/** Spread onto an element (drop zone, textarea, editor) to accept Ctrl/⌘+V there. */
|
|
667
764
|
readonly targetProps: PasteTargetProps<T>;
|
|
@@ -773,11 +870,31 @@ interface PasteFieldTriggerRenderProps {
|
|
|
773
870
|
readonly displayStatus: PasteStatus;
|
|
774
871
|
readonly state: PasteState;
|
|
775
872
|
readonly revealed: boolean;
|
|
873
|
+
/** Whether `retry()` could help after the current error. */
|
|
874
|
+
readonly canRetry: boolean;
|
|
776
875
|
}
|
|
777
876
|
interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> {
|
|
778
877
|
/** Static content, or a render function receiving the live state. */
|
|
779
878
|
readonly children?: ReactNode | ((props: PasteFieldTriggerRenderProps) => ReactNode);
|
|
780
879
|
}
|
|
880
|
+
interface PasteFieldPreviewRenderProps {
|
|
881
|
+
readonly result: PasteResult;
|
|
882
|
+
/**
|
|
883
|
+
* Object URLs for `result.images`, in order, revoked automatically. Empty on
|
|
884
|
+
* the server and for the first render after a paste, until they are created.
|
|
885
|
+
*/
|
|
886
|
+
readonly imageUrls: readonly string[];
|
|
887
|
+
}
|
|
888
|
+
interface PasteFieldPreviewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
|
|
889
|
+
/** Custom rendering of the latest result. Replaces the default text / image / file preview. */
|
|
890
|
+
readonly children?: (props: PasteFieldPreviewRenderProps) => ReactNode;
|
|
891
|
+
/** Shown while there is no pasted result (idle, reading, error). */
|
|
892
|
+
readonly placeholder?: ReactNode;
|
|
893
|
+
/** Pasted text longer than this is cut and ends with "…". Default 2000. */
|
|
894
|
+
readonly maxTextLength?: number;
|
|
895
|
+
/** Alt text for each pasted image. Default "Pasted image 1 of 2". */
|
|
896
|
+
readonly imageAlt?: (index: number, total: number) => string;
|
|
897
|
+
}
|
|
781
898
|
/**
|
|
782
899
|
* Headless compound component for a labelled, paste-ready field.
|
|
783
900
|
*
|
|
@@ -792,6 +909,7 @@ interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
|
|
|
792
909
|
* <PasteField.Label />
|
|
793
910
|
* <PasteField.Zone />
|
|
794
911
|
* <PasteField.Trigger />
|
|
912
|
+
* <PasteField.Preview placeholder="Nothing pasted yet" />
|
|
795
913
|
* </PasteField.Root>
|
|
796
914
|
* ```
|
|
797
915
|
*/
|
|
@@ -801,7 +919,8 @@ export declare const PasteField: {
|
|
|
801
919
|
readonly Status: import("react").ForwardRefExoticComponent<PasteFieldStatusProps & import("react").RefAttributes<HTMLSpanElement>>;
|
|
802
920
|
readonly Zone: import("react").ForwardRefExoticComponent<PasteFieldZoneProps & import("react").RefAttributes<HTMLDivElement>>;
|
|
803
921
|
readonly Trigger: import("react").ForwardRefExoticComponent<PasteFieldTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
|
|
922
|
+
readonly Preview: import("react").ForwardRefExoticComponent<PasteFieldPreviewProps & import("react").RefAttributes<HTMLDivElement>>;
|
|
804
923
|
};
|
|
805
924
|
//#endregion
|
|
806
|
-
export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, DataTransferLike, LiveRegionProps, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteFieldContextValue, PasteFieldLabelProps, PasteFieldMessages, PasteFieldRootProps, PasteFieldStatusProps, PasteFieldTriggerProps, PasteFieldTriggerRenderProps, PasteFieldZoneProps, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, RevealReason, RevealTargetProps, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult };
|
|
925
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, DataTransferLike, LiveRegionProps, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteFieldContextValue, PasteFieldLabelProps, PasteFieldMessages, PasteFieldPreviewProps, PasteFieldPreviewRenderProps, PasteFieldRootProps, PasteFieldStatusProps, PasteFieldTriggerProps, PasteFieldTriggerRenderProps, PasteFieldZoneProps, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, RevealReason, RevealTargetProps, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult };
|
|
807
926
|
//# sourceMappingURL=index.d.cts.map
|
package/dist/index.d.ts
CHANGED
|
@@ -69,15 +69,34 @@ export declare function describeCopyError(error: CopyError): string;
|
|
|
69
69
|
/** Default English, user-facing sentence for a paste error. Replace for i18n. */
|
|
70
70
|
export declare function describePasteError(error: CopyError): string;
|
|
71
71
|
//#endregion
|
|
72
|
+
//#region src/core/machine-shared.d.ts
|
|
73
|
+
/**
|
|
74
|
+
* Internals shared by the copy and paste state machines. Kept in one module so
|
|
75
|
+
* apps that use both don't ship two copies.
|
|
76
|
+
*/
|
|
77
|
+
export declare const DEFAULT_MAX_RETRIES = 3;
|
|
78
|
+
/**
|
|
79
|
+
* Passed to adapters and lazy sources as their last argument. `signal` aborts
|
|
80
|
+
* when the operation is superseded, `reset()`, or its host unmounts, so
|
|
81
|
+
* expensive work (rasterising, decoding) can stop early.
|
|
82
|
+
*/
|
|
83
|
+
interface OperationContext {
|
|
84
|
+
readonly signal: AbortSignal;
|
|
85
|
+
}
|
|
86
|
+
export declare function resolveMaxRetries(value: number | undefined): number;
|
|
87
|
+
//#endregion
|
|
72
88
|
//#region src/core/payload.d.ts
|
|
73
89
|
/** The only image MIME type with reliable cross-browser clipboard write support. */
|
|
74
90
|
export declare const IMAGE_MIME_TYPE = "image/png";
|
|
75
91
|
/**
|
|
76
92
|
* An image as a Blob, a promise of one, or a function producing one.
|
|
77
93
|
* Prefer the function form: it is invoked synchronously inside the user
|
|
78
|
-
* gesture, which Safari requires for async image generation.
|
|
94
|
+
* gesture, which Safari requires for async image generation. The browser
|
|
95
|
+
* adapter always passes an `OperationContext`: stop work once
|
|
96
|
+
* `context.signal` aborts (reset, superseded, unmount). Optional in the type
|
|
97
|
+
* so adapters that call sources themselves keep compiling.
|
|
79
98
|
*/
|
|
80
|
-
export type BlobSource = Blob | PromiseLike<Blob> | (() => Blob | PromiseLike<Blob>);
|
|
99
|
+
export type BlobSource = Blob | PromiseLike<Blob> | ((context?: OperationContext) => Blob | PromiseLike<Blob>);
|
|
81
100
|
export interface TextPayload {
|
|
82
101
|
readonly kind: 'text';
|
|
83
102
|
readonly value: string;
|
|
@@ -173,10 +192,11 @@ export interface ClipboardEnvironment {
|
|
|
173
192
|
*
|
|
174
193
|
* Contract: start the platform write synchronously (before any `await`) so the
|
|
175
194
|
* browser still sees the user gesture, and reject with a `CopyFailure` when you
|
|
176
|
-
* can classify the error.
|
|
195
|
+
* can classify the error. `context.signal` aborts when the copy is reset or its
|
|
196
|
+
* host unmounts; honour it to stop expensive work early.
|
|
177
197
|
*/
|
|
178
198
|
export interface ClipboardAdapter {
|
|
179
|
-
write(payload: CopyPayload): Promise<void>;
|
|
199
|
+
write(payload: CopyPayload, context?: OperationContext): Promise<void>;
|
|
180
200
|
}
|
|
181
201
|
export interface BrowserClipboardAdapterOptions {
|
|
182
202
|
/** Defaults to `window`, read lazily at copy time (SSR-safe). */
|
|
@@ -214,7 +234,6 @@ export declare function createCopyCoordinator(): CopyCoordinator;
|
|
|
214
234
|
//#endregion
|
|
215
235
|
//#region src/core/copy-machine.d.ts
|
|
216
236
|
export declare const DEFAULT_RESET_AFTER_MS = 2000;
|
|
217
|
-
export declare const DEFAULT_MAX_RETRIES = 3;
|
|
218
237
|
export interface IdleState {
|
|
219
238
|
readonly status: 'idle';
|
|
220
239
|
}
|
|
@@ -238,7 +257,16 @@ export interface ErrorState {
|
|
|
238
257
|
}
|
|
239
258
|
export type CopyState = IdleState | CopyingState | CopiedState | ErrorState;
|
|
240
259
|
export type CopyStatus = CopyState['status'];
|
|
241
|
-
|
|
260
|
+
/**
|
|
261
|
+
* `cancelled`: the copy was reset or its host unmounted before it finished,
|
|
262
|
+
* so its work was aborted. Nothing to report to the user.
|
|
263
|
+
*/
|
|
264
|
+
export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
265
|
+
/**
|
|
266
|
+
* Why an in-flight copy was cancelled: `reset` (`reset()` was called) or
|
|
267
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted).
|
|
268
|
+
*/
|
|
269
|
+
export type CopyCancelReason = 'reset' | 'disconnect';
|
|
242
270
|
/** What `copy()`/`retry()` resolve to. They never reject. */
|
|
243
271
|
export type CopyOutcome = {
|
|
244
272
|
readonly status: 'copied';
|
|
@@ -267,6 +295,18 @@ export interface CopyMachineOptions {
|
|
|
267
295
|
readonly coordinator?: CopyCoordinator | null;
|
|
268
296
|
readonly onCopy?: (payload: CopyPayload) => void;
|
|
269
297
|
readonly onError?: (error: CopyError, payload: CopyPayload | null) => void;
|
|
298
|
+
/**
|
|
299
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
300
|
+
* called for the automatic return after `resetAfterMs`, for a `<CopyGroup>`
|
|
301
|
+
* handing "Copied" to another member, or when already `idle`.
|
|
302
|
+
*/
|
|
303
|
+
readonly onReset?: () => void;
|
|
304
|
+
/**
|
|
305
|
+
* A copy in flight was cancelled before it settled: its `signal` aborted
|
|
306
|
+
* and its result will not reach state or `onCopy` / `onError`. Fires
|
|
307
|
+
* before `onReset` when `reset()` cancels a copy.
|
|
308
|
+
*/
|
|
309
|
+
readonly onCancel?: (reason: CopyCancelReason) => void;
|
|
270
310
|
/** Clock injection for tests and deterministic environments. */
|
|
271
311
|
readonly now?: () => number;
|
|
272
312
|
}
|
|
@@ -277,16 +317,17 @@ export interface CopyMachine {
|
|
|
277
317
|
readonly subscribe: (listener: () => void) => () => void;
|
|
278
318
|
readonly copy: (source: CopySource) => Promise<CopyOutcome>;
|
|
279
319
|
readonly retry: () => Promise<CopyOutcome>;
|
|
320
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
280
321
|
readonly reset: () => void;
|
|
281
322
|
/**
|
|
282
323
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
283
|
-
* cleanup clears timers, drops in-flight results
|
|
324
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
325
|
+
* unsticks `copying`.
|
|
284
326
|
* Safe to call repeatedly (React StrictMode).
|
|
285
327
|
*/
|
|
286
328
|
readonly connect: () => () => void;
|
|
287
329
|
}
|
|
288
330
|
export declare const IDLE_STATE: IdleState;
|
|
289
|
-
export declare function resolveMaxRetries(value: number | undefined): number;
|
|
290
331
|
/** Pure helper: can `retry()` do anything from this state? */
|
|
291
332
|
export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
|
|
292
333
|
/** Framework-agnostic copy state machine. */
|
|
@@ -302,7 +343,11 @@ type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
|
302
343
|
*/
|
|
303
344
|
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
304
345
|
interface PasteLimits {
|
|
305
|
-
/**
|
|
346
|
+
/**
|
|
347
|
+
* Total size cap across all accepted items, in UTF-8 bytes. Strings are measured as
|
|
348
|
+
* they would be encoded, matching `Blob.size`, so every paste path counts the same way.
|
|
349
|
+
* Default 32 MiB.
|
|
350
|
+
*/
|
|
306
351
|
readonly maxBytes?: number;
|
|
307
352
|
/** Max number of accepted items (types + files). Default 32. */
|
|
308
353
|
readonly maxItems?: number;
|
|
@@ -341,7 +386,14 @@ interface PasteResult {
|
|
|
341
386
|
readonly images: readonly Blob[];
|
|
342
387
|
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
343
388
|
readonly files: readonly File[];
|
|
389
|
+
/**
|
|
390
|
+
* The entries of `files` that are also in `images`: verified image files, keeping their
|
|
391
|
+
* names, ready for `FormData`. Derived by the paste machine, so it is always consistent.
|
|
392
|
+
*/
|
|
393
|
+
readonly imageFiles: readonly File[];
|
|
344
394
|
}
|
|
395
|
+
/** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
|
|
396
|
+
type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
|
|
345
397
|
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
346
398
|
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
347
399
|
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
@@ -376,9 +428,11 @@ interface PasteEnvironment {
|
|
|
376
428
|
*
|
|
377
429
|
* Contract: call the platform API synchronously (before any `await`) so the
|
|
378
430
|
* browser still sees the user gesture, and reject with a `CopyFailure`.
|
|
431
|
+
* `context.signal` aborts when the read is superseded, reset, or its host
|
|
432
|
+
* unmounts; honour it to stop decoding early.
|
|
379
433
|
*/
|
|
380
434
|
interface PasteAdapter {
|
|
381
|
-
read(options: ResolvedPasteReadOptions): Promise<
|
|
435
|
+
read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteReadResult>;
|
|
382
436
|
}
|
|
383
437
|
interface BrowserPasteAdapterOptions {
|
|
384
438
|
/** Defaults to `window`, read lazily at paste time (SSR-safe). */
|
|
@@ -403,11 +457,25 @@ export interface PasteReadState {
|
|
|
403
457
|
export interface PasteErrorState {
|
|
404
458
|
readonly status: 'error';
|
|
405
459
|
readonly error: CopyError;
|
|
460
|
+
/** Where the failed read came from. Only `'clipboard'` reads can be retried. */
|
|
461
|
+
readonly source: PasteSource;
|
|
462
|
+
/** `retry()` calls made since the last fresh `paste()`. */
|
|
463
|
+
readonly retryCount: number;
|
|
406
464
|
}
|
|
407
465
|
export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
|
|
408
466
|
export type PasteStatus = PasteState['status'];
|
|
409
|
-
|
|
410
|
-
|
|
467
|
+
/**
|
|
468
|
+
* `cancelled`: the read was superseded, reset, or its host unmounted before it
|
|
469
|
+
* finished, so its work was aborted. Nothing to report to the user.
|
|
470
|
+
*/
|
|
471
|
+
export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
472
|
+
/**
|
|
473
|
+
* Why an in-flight read was cancelled: `reset` (`reset()` was called),
|
|
474
|
+
* `disconnect` (its host disconnected, e.g. the React component unmounted) or
|
|
475
|
+
* `superseded` (a paste event arrived while a clipboard read was pending).
|
|
476
|
+
*/
|
|
477
|
+
export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
|
|
478
|
+
/** What `paste()` / `pasteEvent()` / `retry()` resolve to. They never reject. */
|
|
411
479
|
export type PasteOutcome = {
|
|
412
480
|
readonly status: 'read';
|
|
413
481
|
readonly result: PasteResult;
|
|
@@ -433,8 +501,24 @@ export interface PasteMachineOptions extends PasteReadOptions {
|
|
|
433
501
|
* accepted content, so the browser doesn't also insert it. Default `true`.
|
|
434
502
|
*/
|
|
435
503
|
readonly preventDefault?: boolean;
|
|
504
|
+
/**
|
|
505
|
+
* Max `retry()` calls after a failed clipboard read. Default 3. `0`
|
|
506
|
+
* disables retry; `Infinity` allows unlimited retries.
|
|
507
|
+
*/
|
|
508
|
+
readonly maxRetries?: number;
|
|
436
509
|
readonly onPaste?: (result: PasteResult) => void;
|
|
437
510
|
readonly onError?: (error: CopyError) => void;
|
|
511
|
+
/**
|
|
512
|
+
* `reset()` moved the machine back to `idle` from any other state. Not
|
|
513
|
+
* called for the automatic return after `resetAfterMs`, or when already `idle`.
|
|
514
|
+
*/
|
|
515
|
+
readonly onReset?: () => void;
|
|
516
|
+
/**
|
|
517
|
+
* A read in flight was cancelled before it settled: its `signal` aborted
|
|
518
|
+
* and its result will not reach state or `onPaste` / `onError`. Fires
|
|
519
|
+
* before `onReset` when `reset()` cancels a read.
|
|
520
|
+
*/
|
|
521
|
+
readonly onCancel?: (reason: PasteCancelReason) => void;
|
|
438
522
|
/** Clock injection for tests and deterministic environments. */
|
|
439
523
|
readonly now?: () => number;
|
|
440
524
|
}
|
|
@@ -454,16 +538,25 @@ export interface PasteMachine {
|
|
|
454
538
|
* accepted content are ignored and left untouched for the browser.
|
|
455
539
|
*/
|
|
456
540
|
readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
|
|
457
|
-
/**
|
|
541
|
+
/**
|
|
542
|
+
* Re-reads the clipboard after a retryable failure (e.g. permission denied,
|
|
543
|
+
* page not focused), up to `maxRetries`. Call it from a user gesture.
|
|
544
|
+
* Paste-event failures can't be retried: their data is gone after dispatch.
|
|
545
|
+
*/
|
|
546
|
+
readonly retry: () => Promise<PasteOutcome>;
|
|
547
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
458
548
|
readonly reset: () => void;
|
|
459
549
|
/**
|
|
460
550
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
461
|
-
* cleanup clears timers, drops in-flight results
|
|
551
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
552
|
+
* unsticks `reading`.
|
|
462
553
|
* Safe to call repeatedly (React StrictMode).
|
|
463
554
|
*/
|
|
464
555
|
readonly connect: () => () => void;
|
|
465
556
|
}
|
|
466
557
|
export declare const PASTE_IDLE_STATE: PasteIdleState;
|
|
558
|
+
/** Pure helper: can `retry()` do anything from this state? */
|
|
559
|
+
export declare function canRetryPasteState(state: PasteState, maxRetries?: number): boolean;
|
|
467
560
|
/** Framework-agnostic paste state machine. */
|
|
468
561
|
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
469
562
|
//#endregion
|
|
@@ -480,7 +573,7 @@ interface UseCopyResult {
|
|
|
480
573
|
readonly copy: CopyMachine['copy'];
|
|
481
574
|
/** Stable identity. Re-attempts the last failed payload, up to `maxRetries`. */
|
|
482
575
|
readonly retry: CopyMachine['retry'];
|
|
483
|
-
/** Stable identity. Back to `idle`, discarding any in-flight
|
|
576
|
+
/** Stable identity. Back to `idle`, discarding and aborting any in-flight copy. */
|
|
484
577
|
readonly reset: CopyMachine['reset'];
|
|
485
578
|
}
|
|
486
579
|
/**
|
|
@@ -657,11 +750,15 @@ interface UsePasteResult<T extends Element = HTMLElement> {
|
|
|
657
750
|
/** The latest result while `status === 'read'`, otherwise `null`. */
|
|
658
751
|
readonly result: PasteResult | null;
|
|
659
752
|
readonly error: CopyError | null;
|
|
753
|
+
/** Whether `retry()` can do anything right now. */
|
|
754
|
+
readonly canRetry: boolean;
|
|
660
755
|
/** Stable identity. Reads the clipboard from a user gesture. Never rejects. */
|
|
661
756
|
readonly paste: PasteMachine['paste'];
|
|
662
757
|
/** Stable identity. Handles a paste event you received yourself. Never rejects. */
|
|
663
758
|
readonly pasteEvent: PasteMachine['pasteEvent'];
|
|
664
|
-
/** Stable identity.
|
|
759
|
+
/** Stable identity. Re-reads the clipboard after a retryable failure, up to `maxRetries`. */
|
|
760
|
+
readonly retry: PasteMachine['retry'];
|
|
761
|
+
/** Stable identity. Back to `idle`, discarding and aborting any in-flight read. */
|
|
665
762
|
readonly reset: PasteMachine['reset'];
|
|
666
763
|
/** Spread onto an element (drop zone, textarea, editor) to accept Ctrl/⌘+V there. */
|
|
667
764
|
readonly targetProps: PasteTargetProps<T>;
|
|
@@ -773,11 +870,31 @@ interface PasteFieldTriggerRenderProps {
|
|
|
773
870
|
readonly displayStatus: PasteStatus;
|
|
774
871
|
readonly state: PasteState;
|
|
775
872
|
readonly revealed: boolean;
|
|
873
|
+
/** Whether `retry()` could help after the current error. */
|
|
874
|
+
readonly canRetry: boolean;
|
|
776
875
|
}
|
|
777
876
|
interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> {
|
|
778
877
|
/** Static content, or a render function receiving the live state. */
|
|
779
878
|
readonly children?: ReactNode | ((props: PasteFieldTriggerRenderProps) => ReactNode);
|
|
780
879
|
}
|
|
880
|
+
interface PasteFieldPreviewRenderProps {
|
|
881
|
+
readonly result: PasteResult;
|
|
882
|
+
/**
|
|
883
|
+
* Object URLs for `result.images`, in order, revoked automatically. Empty on
|
|
884
|
+
* the server and for the first render after a paste, until they are created.
|
|
885
|
+
*/
|
|
886
|
+
readonly imageUrls: readonly string[];
|
|
887
|
+
}
|
|
888
|
+
interface PasteFieldPreviewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
|
|
889
|
+
/** Custom rendering of the latest result. Replaces the default text / image / file preview. */
|
|
890
|
+
readonly children?: (props: PasteFieldPreviewRenderProps) => ReactNode;
|
|
891
|
+
/** Shown while there is no pasted result (idle, reading, error). */
|
|
892
|
+
readonly placeholder?: ReactNode;
|
|
893
|
+
/** Pasted text longer than this is cut and ends with "…". Default 2000. */
|
|
894
|
+
readonly maxTextLength?: number;
|
|
895
|
+
/** Alt text for each pasted image. Default "Pasted image 1 of 2". */
|
|
896
|
+
readonly imageAlt?: (index: number, total: number) => string;
|
|
897
|
+
}
|
|
781
898
|
/**
|
|
782
899
|
* Headless compound component for a labelled, paste-ready field.
|
|
783
900
|
*
|
|
@@ -792,6 +909,7 @@ interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
|
|
|
792
909
|
* <PasteField.Label />
|
|
793
910
|
* <PasteField.Zone />
|
|
794
911
|
* <PasteField.Trigger />
|
|
912
|
+
* <PasteField.Preview placeholder="Nothing pasted yet" />
|
|
795
913
|
* </PasteField.Root>
|
|
796
914
|
* ```
|
|
797
915
|
*/
|
|
@@ -801,7 +919,8 @@ export declare const PasteField: {
|
|
|
801
919
|
readonly Status: import("react").ForwardRefExoticComponent<PasteFieldStatusProps & import("react").RefAttributes<HTMLSpanElement>>;
|
|
802
920
|
readonly Zone: import("react").ForwardRefExoticComponent<PasteFieldZoneProps & import("react").RefAttributes<HTMLDivElement>>;
|
|
803
921
|
readonly Trigger: import("react").ForwardRefExoticComponent<PasteFieldTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
|
|
922
|
+
readonly Preview: import("react").ForwardRefExoticComponent<PasteFieldPreviewProps & import("react").RefAttributes<HTMLDivElement>>;
|
|
804
923
|
};
|
|
805
924
|
//#endregion
|
|
806
|
-
export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, DataTransferLike, LiveRegionProps, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteFieldContextValue, PasteFieldLabelProps, PasteFieldMessages, PasteFieldRootProps, PasteFieldStatusProps, PasteFieldTriggerProps, PasteFieldTriggerRenderProps, PasteFieldZoneProps, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, RevealReason, RevealTargetProps, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult };
|
|
925
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, DataTransferLike, LiveRegionProps, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteFieldContextValue, PasteFieldLabelProps, PasteFieldMessages, PasteFieldPreviewProps, PasteFieldPreviewRenderProps, PasteFieldRootProps, PasteFieldStatusProps, PasteFieldTriggerProps, PasteFieldTriggerRenderProps, PasteFieldZoneProps, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, RevealReason, RevealTargetProps, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult };
|
|
807
926
|
//# sourceMappingURL=index.d.ts.map
|