react-smart-copy 1.1.0 → 1.2.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 +91 -6
- 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 +135 -80
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.cts +66 -15
- package/dist/core.d.ts +66 -15
- package/dist/core.js +135 -81
- package/dist/core.js.map +1 -1
- package/dist/index.cjs +267 -165
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +94 -17
- package/dist/index.d.ts +94 -17
- package/dist/index.js +268 -167
- package/dist/index.js.map +1 -1
- package/package.json +9 -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,11 @@ 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';
|
|
242
265
|
/** What `copy()`/`retry()` resolve to. They never reject. */
|
|
243
266
|
export type CopyOutcome = {
|
|
244
267
|
readonly status: 'copied';
|
|
@@ -255,7 +278,10 @@ export interface CopyMachineOptions {
|
|
|
255
278
|
readonly adapter?: ClipboardAdapter;
|
|
256
279
|
/** Time in `copied` before returning to `idle`. `false`/`Infinity` disables. Default 2000. */
|
|
257
280
|
readonly resetAfterMs?: number | false;
|
|
258
|
-
/**
|
|
281
|
+
/**
|
|
282
|
+
* Max `retry()` calls after the first failure. Default 3. `0` disables
|
|
283
|
+
* retry; `Infinity` allows unlimited retries.
|
|
284
|
+
*/
|
|
259
285
|
readonly maxRetries?: number;
|
|
260
286
|
/**
|
|
261
287
|
* Share "Copied" with other machines: only one member of a coordinator
|
|
@@ -274,16 +300,17 @@ export interface CopyMachine {
|
|
|
274
300
|
readonly subscribe: (listener: () => void) => () => void;
|
|
275
301
|
readonly copy: (source: CopySource) => Promise<CopyOutcome>;
|
|
276
302
|
readonly retry: () => Promise<CopyOutcome>;
|
|
303
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
277
304
|
readonly reset: () => void;
|
|
278
305
|
/**
|
|
279
306
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
280
|
-
* cleanup clears timers, drops in-flight results
|
|
307
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
308
|
+
* unsticks `copying`.
|
|
281
309
|
* Safe to call repeatedly (React StrictMode).
|
|
282
310
|
*/
|
|
283
311
|
readonly connect: () => () => void;
|
|
284
312
|
}
|
|
285
313
|
export declare const IDLE_STATE: IdleState;
|
|
286
|
-
export declare function resolveMaxRetries(value: number | undefined): number;
|
|
287
314
|
/** Pure helper: can `retry()` do anything from this state? */
|
|
288
315
|
export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
|
|
289
316
|
/** Framework-agnostic copy state machine. */
|
|
@@ -373,9 +400,11 @@ interface PasteEnvironment {
|
|
|
373
400
|
*
|
|
374
401
|
* Contract: call the platform API synchronously (before any `await`) so the
|
|
375
402
|
* browser still sees the user gesture, and reject with a `CopyFailure`.
|
|
403
|
+
* `context.signal` aborts when the read is superseded, reset, or its host
|
|
404
|
+
* unmounts; honour it to stop decoding early.
|
|
376
405
|
*/
|
|
377
406
|
interface PasteAdapter {
|
|
378
|
-
read(options: ResolvedPasteReadOptions): Promise<PasteResult>;
|
|
407
|
+
read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteResult>;
|
|
379
408
|
}
|
|
380
409
|
interface BrowserPasteAdapterOptions {
|
|
381
410
|
/** Defaults to `window`, read lazily at paste time (SSR-safe). */
|
|
@@ -400,11 +429,19 @@ export interface PasteReadState {
|
|
|
400
429
|
export interface PasteErrorState {
|
|
401
430
|
readonly status: 'error';
|
|
402
431
|
readonly error: CopyError;
|
|
432
|
+
/** Where the failed read came from. Only `'clipboard'` reads can be retried. */
|
|
433
|
+
readonly source: PasteSource;
|
|
434
|
+
/** `retry()` calls made since the last fresh `paste()`. */
|
|
435
|
+
readonly retryCount: number;
|
|
403
436
|
}
|
|
404
437
|
export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
|
|
405
438
|
export type PasteStatus = PasteState['status'];
|
|
406
|
-
|
|
407
|
-
|
|
439
|
+
/**
|
|
440
|
+
* `cancelled`: the read was superseded, reset, or its host unmounted before it
|
|
441
|
+
* finished, so its work was aborted. Nothing to report to the user.
|
|
442
|
+
*/
|
|
443
|
+
export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
444
|
+
/** What `paste()` / `pasteEvent()` / `retry()` resolve to. They never reject. */
|
|
408
445
|
export type PasteOutcome = {
|
|
409
446
|
readonly status: 'read';
|
|
410
447
|
readonly result: PasteResult;
|
|
@@ -430,6 +467,11 @@ export interface PasteMachineOptions extends PasteReadOptions {
|
|
|
430
467
|
* accepted content, so the browser doesn't also insert it. Default `true`.
|
|
431
468
|
*/
|
|
432
469
|
readonly preventDefault?: boolean;
|
|
470
|
+
/**
|
|
471
|
+
* Max `retry()` calls after a failed clipboard read. Default 3. `0`
|
|
472
|
+
* disables retry; `Infinity` allows unlimited retries.
|
|
473
|
+
*/
|
|
474
|
+
readonly maxRetries?: number;
|
|
433
475
|
readonly onPaste?: (result: PasteResult) => void;
|
|
434
476
|
readonly onError?: (error: CopyError) => void;
|
|
435
477
|
/** Clock injection for tests and deterministic environments. */
|
|
@@ -451,16 +493,25 @@ export interface PasteMachine {
|
|
|
451
493
|
* accepted content are ignored and left untouched for the browser.
|
|
452
494
|
*/
|
|
453
495
|
readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
|
|
454
|
-
/**
|
|
496
|
+
/**
|
|
497
|
+
* Re-reads the clipboard after a retryable failure (e.g. permission denied,
|
|
498
|
+
* page not focused), up to `maxRetries`. Call it from a user gesture.
|
|
499
|
+
* Paste-event failures can't be retried: their data is gone after dispatch.
|
|
500
|
+
*/
|
|
501
|
+
readonly retry: () => Promise<PasteOutcome>;
|
|
502
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
455
503
|
readonly reset: () => void;
|
|
456
504
|
/**
|
|
457
505
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
458
|
-
* cleanup clears timers, drops in-flight results
|
|
506
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
507
|
+
* unsticks `reading`.
|
|
459
508
|
* Safe to call repeatedly (React StrictMode).
|
|
460
509
|
*/
|
|
461
510
|
readonly connect: () => () => void;
|
|
462
511
|
}
|
|
463
512
|
export declare const PASTE_IDLE_STATE: PasteIdleState;
|
|
513
|
+
/** Pure helper: can `retry()` do anything from this state? */
|
|
514
|
+
export declare function canRetryPasteState(state: PasteState, maxRetries?: number): boolean;
|
|
464
515
|
/** Framework-agnostic paste state machine. */
|
|
465
516
|
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
466
517
|
//#endregion
|
|
@@ -477,7 +528,7 @@ interface UseCopyResult {
|
|
|
477
528
|
readonly copy: CopyMachine['copy'];
|
|
478
529
|
/** Stable identity. Re-attempts the last failed payload, up to `maxRetries`. */
|
|
479
530
|
readonly retry: CopyMachine['retry'];
|
|
480
|
-
/** Stable identity. Back to `idle`, discarding any in-flight
|
|
531
|
+
/** Stable identity. Back to `idle`, discarding and aborting any in-flight copy. */
|
|
481
532
|
readonly reset: CopyMachine['reset'];
|
|
482
533
|
}
|
|
483
534
|
/**
|
|
@@ -654,11 +705,15 @@ interface UsePasteResult<T extends Element = HTMLElement> {
|
|
|
654
705
|
/** The latest result while `status === 'read'`, otherwise `null`. */
|
|
655
706
|
readonly result: PasteResult | null;
|
|
656
707
|
readonly error: CopyError | null;
|
|
708
|
+
/** Whether `retry()` can do anything right now. */
|
|
709
|
+
readonly canRetry: boolean;
|
|
657
710
|
/** Stable identity. Reads the clipboard from a user gesture. Never rejects. */
|
|
658
711
|
readonly paste: PasteMachine['paste'];
|
|
659
712
|
/** Stable identity. Handles a paste event you received yourself. Never rejects. */
|
|
660
713
|
readonly pasteEvent: PasteMachine['pasteEvent'];
|
|
661
|
-
/** Stable identity.
|
|
714
|
+
/** Stable identity. Re-reads the clipboard after a retryable failure, up to `maxRetries`. */
|
|
715
|
+
readonly retry: PasteMachine['retry'];
|
|
716
|
+
/** Stable identity. Back to `idle`, discarding and aborting any in-flight read. */
|
|
662
717
|
readonly reset: PasteMachine['reset'];
|
|
663
718
|
/** Spread onto an element (drop zone, textarea, editor) to accept Ctrl/⌘+V there. */
|
|
664
719
|
readonly targetProps: PasteTargetProps<T>;
|
|
@@ -770,11 +825,31 @@ interface PasteFieldTriggerRenderProps {
|
|
|
770
825
|
readonly displayStatus: PasteStatus;
|
|
771
826
|
readonly state: PasteState;
|
|
772
827
|
readonly revealed: boolean;
|
|
828
|
+
/** Whether `retry()` could help after the current error. */
|
|
829
|
+
readonly canRetry: boolean;
|
|
773
830
|
}
|
|
774
831
|
interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> {
|
|
775
832
|
/** Static content, or a render function receiving the live state. */
|
|
776
833
|
readonly children?: ReactNode | ((props: PasteFieldTriggerRenderProps) => ReactNode);
|
|
777
834
|
}
|
|
835
|
+
interface PasteFieldPreviewRenderProps {
|
|
836
|
+
readonly result: PasteResult;
|
|
837
|
+
/**
|
|
838
|
+
* Object URLs for `result.images`, in order, revoked automatically. Empty on
|
|
839
|
+
* the server and for the first render after a paste, until they are created.
|
|
840
|
+
*/
|
|
841
|
+
readonly imageUrls: readonly string[];
|
|
842
|
+
}
|
|
843
|
+
interface PasteFieldPreviewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
|
|
844
|
+
/** Custom rendering of the latest result. Replaces the default text / image / file preview. */
|
|
845
|
+
readonly children?: (props: PasteFieldPreviewRenderProps) => ReactNode;
|
|
846
|
+
/** Shown while there is no pasted result (idle, reading, error). */
|
|
847
|
+
readonly placeholder?: ReactNode;
|
|
848
|
+
/** Pasted text longer than this is cut and ends with "…". Default 2000. */
|
|
849
|
+
readonly maxTextLength?: number;
|
|
850
|
+
/** Alt text for each pasted image. Default "Pasted image 1 of 2". */
|
|
851
|
+
readonly imageAlt?: (index: number, total: number) => string;
|
|
852
|
+
}
|
|
778
853
|
/**
|
|
779
854
|
* Headless compound component for a labelled, paste-ready field.
|
|
780
855
|
*
|
|
@@ -789,6 +864,7 @@ interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
|
|
|
789
864
|
* <PasteField.Label />
|
|
790
865
|
* <PasteField.Zone />
|
|
791
866
|
* <PasteField.Trigger />
|
|
867
|
+
* <PasteField.Preview placeholder="Nothing pasted yet" />
|
|
792
868
|
* </PasteField.Root>
|
|
793
869
|
* ```
|
|
794
870
|
*/
|
|
@@ -798,7 +874,8 @@ export declare const PasteField: {
|
|
|
798
874
|
readonly Status: import("react").ForwardRefExoticComponent<PasteFieldStatusProps & import("react").RefAttributes<HTMLSpanElement>>;
|
|
799
875
|
readonly Zone: import("react").ForwardRefExoticComponent<PasteFieldZoneProps & import("react").RefAttributes<HTMLDivElement>>;
|
|
800
876
|
readonly Trigger: import("react").ForwardRefExoticComponent<PasteFieldTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
|
|
877
|
+
readonly Preview: import("react").ForwardRefExoticComponent<PasteFieldPreviewProps & import("react").RefAttributes<HTMLDivElement>>;
|
|
801
878
|
};
|
|
802
879
|
//#endregion
|
|
803
|
-
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 };
|
|
880
|
+
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, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, RevealReason, RevealTargetProps, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult };
|
|
804
881
|
//# 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,11 @@ 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';
|
|
242
265
|
/** What `copy()`/`retry()` resolve to. They never reject. */
|
|
243
266
|
export type CopyOutcome = {
|
|
244
267
|
readonly status: 'copied';
|
|
@@ -255,7 +278,10 @@ export interface CopyMachineOptions {
|
|
|
255
278
|
readonly adapter?: ClipboardAdapter;
|
|
256
279
|
/** Time in `copied` before returning to `idle`. `false`/`Infinity` disables. Default 2000. */
|
|
257
280
|
readonly resetAfterMs?: number | false;
|
|
258
|
-
/**
|
|
281
|
+
/**
|
|
282
|
+
* Max `retry()` calls after the first failure. Default 3. `0` disables
|
|
283
|
+
* retry; `Infinity` allows unlimited retries.
|
|
284
|
+
*/
|
|
259
285
|
readonly maxRetries?: number;
|
|
260
286
|
/**
|
|
261
287
|
* Share "Copied" with other machines: only one member of a coordinator
|
|
@@ -274,16 +300,17 @@ export interface CopyMachine {
|
|
|
274
300
|
readonly subscribe: (listener: () => void) => () => void;
|
|
275
301
|
readonly copy: (source: CopySource) => Promise<CopyOutcome>;
|
|
276
302
|
readonly retry: () => Promise<CopyOutcome>;
|
|
303
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
277
304
|
readonly reset: () => void;
|
|
278
305
|
/**
|
|
279
306
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
280
|
-
* cleanup clears timers, drops in-flight results
|
|
307
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
308
|
+
* unsticks `copying`.
|
|
281
309
|
* Safe to call repeatedly (React StrictMode).
|
|
282
310
|
*/
|
|
283
311
|
readonly connect: () => () => void;
|
|
284
312
|
}
|
|
285
313
|
export declare const IDLE_STATE: IdleState;
|
|
286
|
-
export declare function resolveMaxRetries(value: number | undefined): number;
|
|
287
314
|
/** Pure helper: can `retry()` do anything from this state? */
|
|
288
315
|
export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
|
|
289
316
|
/** Framework-agnostic copy state machine. */
|
|
@@ -373,9 +400,11 @@ interface PasteEnvironment {
|
|
|
373
400
|
*
|
|
374
401
|
* Contract: call the platform API synchronously (before any `await`) so the
|
|
375
402
|
* browser still sees the user gesture, and reject with a `CopyFailure`.
|
|
403
|
+
* `context.signal` aborts when the read is superseded, reset, or its host
|
|
404
|
+
* unmounts; honour it to stop decoding early.
|
|
376
405
|
*/
|
|
377
406
|
interface PasteAdapter {
|
|
378
|
-
read(options: ResolvedPasteReadOptions): Promise<PasteResult>;
|
|
407
|
+
read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteResult>;
|
|
379
408
|
}
|
|
380
409
|
interface BrowserPasteAdapterOptions {
|
|
381
410
|
/** Defaults to `window`, read lazily at paste time (SSR-safe). */
|
|
@@ -400,11 +429,19 @@ export interface PasteReadState {
|
|
|
400
429
|
export interface PasteErrorState {
|
|
401
430
|
readonly status: 'error';
|
|
402
431
|
readonly error: CopyError;
|
|
432
|
+
/** Where the failed read came from. Only `'clipboard'` reads can be retried. */
|
|
433
|
+
readonly source: PasteSource;
|
|
434
|
+
/** `retry()` calls made since the last fresh `paste()`. */
|
|
435
|
+
readonly retryCount: number;
|
|
403
436
|
}
|
|
404
437
|
export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
|
|
405
438
|
export type PasteStatus = PasteState['status'];
|
|
406
|
-
|
|
407
|
-
|
|
439
|
+
/**
|
|
440
|
+
* `cancelled`: the read was superseded, reset, or its host unmounted before it
|
|
441
|
+
* finished, so its work was aborted. Nothing to report to the user.
|
|
442
|
+
*/
|
|
443
|
+
export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
|
|
444
|
+
/** What `paste()` / `pasteEvent()` / `retry()` resolve to. They never reject. */
|
|
408
445
|
export type PasteOutcome = {
|
|
409
446
|
readonly status: 'read';
|
|
410
447
|
readonly result: PasteResult;
|
|
@@ -430,6 +467,11 @@ export interface PasteMachineOptions extends PasteReadOptions {
|
|
|
430
467
|
* accepted content, so the browser doesn't also insert it. Default `true`.
|
|
431
468
|
*/
|
|
432
469
|
readonly preventDefault?: boolean;
|
|
470
|
+
/**
|
|
471
|
+
* Max `retry()` calls after a failed clipboard read. Default 3. `0`
|
|
472
|
+
* disables retry; `Infinity` allows unlimited retries.
|
|
473
|
+
*/
|
|
474
|
+
readonly maxRetries?: number;
|
|
433
475
|
readonly onPaste?: (result: PasteResult) => void;
|
|
434
476
|
readonly onError?: (error: CopyError) => void;
|
|
435
477
|
/** Clock injection for tests and deterministic environments. */
|
|
@@ -451,16 +493,25 @@ export interface PasteMachine {
|
|
|
451
493
|
* accepted content are ignored and left untouched for the browser.
|
|
452
494
|
*/
|
|
453
495
|
readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
|
|
454
|
-
/**
|
|
496
|
+
/**
|
|
497
|
+
* Re-reads the clipboard after a retryable failure (e.g. permission denied,
|
|
498
|
+
* page not focused), up to `maxRetries`. Call it from a user gesture.
|
|
499
|
+
* Paste-event failures can't be retried: their data is gone after dispatch.
|
|
500
|
+
*/
|
|
501
|
+
readonly retry: () => Promise<PasteOutcome>;
|
|
502
|
+
/** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
|
|
455
503
|
readonly reset: () => void;
|
|
456
504
|
/**
|
|
457
505
|
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
458
|
-
* cleanup clears timers, drops in-flight results
|
|
506
|
+
* cleanup clears timers, drops in-flight results, aborts in-flight work and
|
|
507
|
+
* unsticks `reading`.
|
|
459
508
|
* Safe to call repeatedly (React StrictMode).
|
|
460
509
|
*/
|
|
461
510
|
readonly connect: () => () => void;
|
|
462
511
|
}
|
|
463
512
|
export declare const PASTE_IDLE_STATE: PasteIdleState;
|
|
513
|
+
/** Pure helper: can `retry()` do anything from this state? */
|
|
514
|
+
export declare function canRetryPasteState(state: PasteState, maxRetries?: number): boolean;
|
|
464
515
|
/** Framework-agnostic paste state machine. */
|
|
465
516
|
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
466
517
|
//#endregion
|
|
@@ -477,7 +528,7 @@ interface UseCopyResult {
|
|
|
477
528
|
readonly copy: CopyMachine['copy'];
|
|
478
529
|
/** Stable identity. Re-attempts the last failed payload, up to `maxRetries`. */
|
|
479
530
|
readonly retry: CopyMachine['retry'];
|
|
480
|
-
/** Stable identity. Back to `idle`, discarding any in-flight
|
|
531
|
+
/** Stable identity. Back to `idle`, discarding and aborting any in-flight copy. */
|
|
481
532
|
readonly reset: CopyMachine['reset'];
|
|
482
533
|
}
|
|
483
534
|
/**
|
|
@@ -654,11 +705,15 @@ interface UsePasteResult<T extends Element = HTMLElement> {
|
|
|
654
705
|
/** The latest result while `status === 'read'`, otherwise `null`. */
|
|
655
706
|
readonly result: PasteResult | null;
|
|
656
707
|
readonly error: CopyError | null;
|
|
708
|
+
/** Whether `retry()` can do anything right now. */
|
|
709
|
+
readonly canRetry: boolean;
|
|
657
710
|
/** Stable identity. Reads the clipboard from a user gesture. Never rejects. */
|
|
658
711
|
readonly paste: PasteMachine['paste'];
|
|
659
712
|
/** Stable identity. Handles a paste event you received yourself. Never rejects. */
|
|
660
713
|
readonly pasteEvent: PasteMachine['pasteEvent'];
|
|
661
|
-
/** Stable identity.
|
|
714
|
+
/** Stable identity. Re-reads the clipboard after a retryable failure, up to `maxRetries`. */
|
|
715
|
+
readonly retry: PasteMachine['retry'];
|
|
716
|
+
/** Stable identity. Back to `idle`, discarding and aborting any in-flight read. */
|
|
662
717
|
readonly reset: PasteMachine['reset'];
|
|
663
718
|
/** Spread onto an element (drop zone, textarea, editor) to accept Ctrl/⌘+V there. */
|
|
664
719
|
readonly targetProps: PasteTargetProps<T>;
|
|
@@ -770,11 +825,31 @@ interface PasteFieldTriggerRenderProps {
|
|
|
770
825
|
readonly displayStatus: PasteStatus;
|
|
771
826
|
readonly state: PasteState;
|
|
772
827
|
readonly revealed: boolean;
|
|
828
|
+
/** Whether `retry()` could help after the current error. */
|
|
829
|
+
readonly canRetry: boolean;
|
|
773
830
|
}
|
|
774
831
|
interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> {
|
|
775
832
|
/** Static content, or a render function receiving the live state. */
|
|
776
833
|
readonly children?: ReactNode | ((props: PasteFieldTriggerRenderProps) => ReactNode);
|
|
777
834
|
}
|
|
835
|
+
interface PasteFieldPreviewRenderProps {
|
|
836
|
+
readonly result: PasteResult;
|
|
837
|
+
/**
|
|
838
|
+
* Object URLs for `result.images`, in order, revoked automatically. Empty on
|
|
839
|
+
* the server and for the first render after a paste, until they are created.
|
|
840
|
+
*/
|
|
841
|
+
readonly imageUrls: readonly string[];
|
|
842
|
+
}
|
|
843
|
+
interface PasteFieldPreviewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
|
|
844
|
+
/** Custom rendering of the latest result. Replaces the default text / image / file preview. */
|
|
845
|
+
readonly children?: (props: PasteFieldPreviewRenderProps) => ReactNode;
|
|
846
|
+
/** Shown while there is no pasted result (idle, reading, error). */
|
|
847
|
+
readonly placeholder?: ReactNode;
|
|
848
|
+
/** Pasted text longer than this is cut and ends with "…". Default 2000. */
|
|
849
|
+
readonly maxTextLength?: number;
|
|
850
|
+
/** Alt text for each pasted image. Default "Pasted image 1 of 2". */
|
|
851
|
+
readonly imageAlt?: (index: number, total: number) => string;
|
|
852
|
+
}
|
|
778
853
|
/**
|
|
779
854
|
* Headless compound component for a labelled, paste-ready field.
|
|
780
855
|
*
|
|
@@ -789,6 +864,7 @@ interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
|
|
|
789
864
|
* <PasteField.Label />
|
|
790
865
|
* <PasteField.Zone />
|
|
791
866
|
* <PasteField.Trigger />
|
|
867
|
+
* <PasteField.Preview placeholder="Nothing pasted yet" />
|
|
792
868
|
* </PasteField.Root>
|
|
793
869
|
* ```
|
|
794
870
|
*/
|
|
@@ -798,7 +874,8 @@ export declare const PasteField: {
|
|
|
798
874
|
readonly Status: import("react").ForwardRefExoticComponent<PasteFieldStatusProps & import("react").RefAttributes<HTMLSpanElement>>;
|
|
799
875
|
readonly Zone: import("react").ForwardRefExoticComponent<PasteFieldZoneProps & import("react").RefAttributes<HTMLDivElement>>;
|
|
800
876
|
readonly Trigger: import("react").ForwardRefExoticComponent<PasteFieldTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
|
|
877
|
+
readonly Preview: import("react").ForwardRefExoticComponent<PasteFieldPreviewProps & import("react").RefAttributes<HTMLDivElement>>;
|
|
801
878
|
};
|
|
802
879
|
//#endregion
|
|
803
|
-
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 };
|
|
880
|
+
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, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, RevealReason, RevealTargetProps, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult };
|
|
804
881
|
//# sourceMappingURL=index.d.ts.map
|