react-smart-copy 1.1.1 → 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/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
- export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable';
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';
@@ -277,16 +300,17 @@ export interface CopyMachine {
277
300
  readonly subscribe: (listener: () => void) => () => void;
278
301
  readonly copy: (source: CopySource) => Promise<CopyOutcome>;
279
302
  readonly retry: () => Promise<CopyOutcome>;
303
+ /** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
280
304
  readonly reset: () => void;
281
305
  /**
282
306
  * Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
283
- * cleanup clears timers, drops in-flight results and unsticks `copying`.
307
+ * cleanup clears timers, drops in-flight results, aborts in-flight work and
308
+ * unsticks `copying`.
284
309
  * Safe to call repeatedly (React StrictMode).
285
310
  */
286
311
  readonly connect: () => () => void;
287
312
  }
288
313
  export declare const IDLE_STATE: IdleState;
289
- export declare function resolveMaxRetries(value: number | undefined): number;
290
314
  /** Pure helper: can `retry()` do anything from this state? */
291
315
  export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
292
316
  /** Framework-agnostic copy state machine. */
@@ -376,9 +400,11 @@ interface PasteEnvironment {
376
400
  *
377
401
  * Contract: call the platform API synchronously (before any `await`) so the
378
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.
379
405
  */
380
406
  interface PasteAdapter {
381
- read(options: ResolvedPasteReadOptions): Promise<PasteResult>;
407
+ read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteResult>;
382
408
  }
383
409
  interface BrowserPasteAdapterOptions {
384
410
  /** Defaults to `window`, read lazily at paste time (SSR-safe). */
@@ -403,11 +429,19 @@ export interface PasteReadState {
403
429
  export interface PasteErrorState {
404
430
  readonly status: 'error';
405
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;
406
436
  }
407
437
  export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
408
438
  export type PasteStatus = PasteState['status'];
409
- export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content';
410
- /** What `paste()` / `pasteEvent()` resolve to. They never reject. */
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. */
411
445
  export type PasteOutcome = {
412
446
  readonly status: 'read';
413
447
  readonly result: PasteResult;
@@ -433,6 +467,11 @@ export interface PasteMachineOptions extends PasteReadOptions {
433
467
  * accepted content, so the browser doesn't also insert it. Default `true`.
434
468
  */
435
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;
436
475
  readonly onPaste?: (result: PasteResult) => void;
437
476
  readonly onError?: (error: CopyError) => void;
438
477
  /** Clock injection for tests and deterministic environments. */
@@ -454,16 +493,25 @@ export interface PasteMachine {
454
493
  * accepted content are ignored and left untouched for the browser.
455
494
  */
456
495
  readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
457
- /** Back to `idle`, discarding any in-flight result. */
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`. */
458
503
  readonly reset: () => void;
459
504
  /**
460
505
  * Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
461
- * cleanup clears timers, drops in-flight results and unsticks `reading`.
506
+ * cleanup clears timers, drops in-flight results, aborts in-flight work and
507
+ * unsticks `reading`.
462
508
  * Safe to call repeatedly (React StrictMode).
463
509
  */
464
510
  readonly connect: () => () => void;
465
511
  }
466
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;
467
515
  /** Framework-agnostic paste state machine. */
468
516
  export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
469
517
  //#endregion
@@ -480,7 +528,7 @@ interface UseCopyResult {
480
528
  readonly copy: CopyMachine['copy'];
481
529
  /** Stable identity. Re-attempts the last failed payload, up to `maxRetries`. */
482
530
  readonly retry: CopyMachine['retry'];
483
- /** Stable identity. Back to `idle`, discarding any in-flight result. */
531
+ /** Stable identity. Back to `idle`, discarding and aborting any in-flight copy. */
484
532
  readonly reset: CopyMachine['reset'];
485
533
  }
486
534
  /**
@@ -657,11 +705,15 @@ interface UsePasteResult<T extends Element = HTMLElement> {
657
705
  /** The latest result while `status === 'read'`, otherwise `null`. */
658
706
  readonly result: PasteResult | null;
659
707
  readonly error: CopyError | null;
708
+ /** Whether `retry()` can do anything right now. */
709
+ readonly canRetry: boolean;
660
710
  /** Stable identity. Reads the clipboard from a user gesture. Never rejects. */
661
711
  readonly paste: PasteMachine['paste'];
662
712
  /** Stable identity. Handles a paste event you received yourself. Never rejects. */
663
713
  readonly pasteEvent: PasteMachine['pasteEvent'];
664
- /** Stable identity. Back to `idle`, discarding any in-flight result. */
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. */
665
717
  readonly reset: PasteMachine['reset'];
666
718
  /** Spread onto an element (drop zone, textarea, editor) to accept Ctrl/⌘+V there. */
667
719
  readonly targetProps: PasteTargetProps<T>;
@@ -773,11 +825,31 @@ interface PasteFieldTriggerRenderProps {
773
825
  readonly displayStatus: PasteStatus;
774
826
  readonly state: PasteState;
775
827
  readonly revealed: boolean;
828
+ /** Whether `retry()` could help after the current error. */
829
+ readonly canRetry: boolean;
776
830
  }
777
831
  interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> {
778
832
  /** Static content, or a render function receiving the live state. */
779
833
  readonly children?: ReactNode | ((props: PasteFieldTriggerRenderProps) => ReactNode);
780
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
+ }
781
853
  /**
782
854
  * Headless compound component for a labelled, paste-ready field.
783
855
  *
@@ -792,6 +864,7 @@ interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
792
864
  * <PasteField.Label />
793
865
  * <PasteField.Zone />
794
866
  * <PasteField.Trigger />
867
+ * <PasteField.Preview placeholder="Nothing pasted yet" />
795
868
  * </PasteField.Root>
796
869
  * ```
797
870
  */
@@ -801,7 +874,8 @@ export declare const PasteField: {
801
874
  readonly Status: import("react").ForwardRefExoticComponent<PasteFieldStatusProps & import("react").RefAttributes<HTMLSpanElement>>;
802
875
  readonly Zone: import("react").ForwardRefExoticComponent<PasteFieldZoneProps & import("react").RefAttributes<HTMLDivElement>>;
803
876
  readonly Trigger: import("react").ForwardRefExoticComponent<PasteFieldTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
877
+ readonly Preview: import("react").ForwardRefExoticComponent<PasteFieldPreviewProps & import("react").RefAttributes<HTMLDivElement>>;
804
878
  };
805
879
  //#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 };
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 };
807
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
- export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable';
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';
@@ -277,16 +300,17 @@ export interface CopyMachine {
277
300
  readonly subscribe: (listener: () => void) => () => void;
278
301
  readonly copy: (source: CopySource) => Promise<CopyOutcome>;
279
302
  readonly retry: () => Promise<CopyOutcome>;
303
+ /** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
280
304
  readonly reset: () => void;
281
305
  /**
282
306
  * Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
283
- * cleanup clears timers, drops in-flight results and unsticks `copying`.
307
+ * cleanup clears timers, drops in-flight results, aborts in-flight work and
308
+ * unsticks `copying`.
284
309
  * Safe to call repeatedly (React StrictMode).
285
310
  */
286
311
  readonly connect: () => () => void;
287
312
  }
288
313
  export declare const IDLE_STATE: IdleState;
289
- export declare function resolveMaxRetries(value: number | undefined): number;
290
314
  /** Pure helper: can `retry()` do anything from this state? */
291
315
  export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
292
316
  /** Framework-agnostic copy state machine. */
@@ -376,9 +400,11 @@ interface PasteEnvironment {
376
400
  *
377
401
  * Contract: call the platform API synchronously (before any `await`) so the
378
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.
379
405
  */
380
406
  interface PasteAdapter {
381
- read(options: ResolvedPasteReadOptions): Promise<PasteResult>;
407
+ read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteResult>;
382
408
  }
383
409
  interface BrowserPasteAdapterOptions {
384
410
  /** Defaults to `window`, read lazily at paste time (SSR-safe). */
@@ -403,11 +429,19 @@ export interface PasteReadState {
403
429
  export interface PasteErrorState {
404
430
  readonly status: 'error';
405
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;
406
436
  }
407
437
  export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
408
438
  export type PasteStatus = PasteState['status'];
409
- export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content';
410
- /** What `paste()` / `pasteEvent()` resolve to. They never reject. */
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. */
411
445
  export type PasteOutcome = {
412
446
  readonly status: 'read';
413
447
  readonly result: PasteResult;
@@ -433,6 +467,11 @@ export interface PasteMachineOptions extends PasteReadOptions {
433
467
  * accepted content, so the browser doesn't also insert it. Default `true`.
434
468
  */
435
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;
436
475
  readonly onPaste?: (result: PasteResult) => void;
437
476
  readonly onError?: (error: CopyError) => void;
438
477
  /** Clock injection for tests and deterministic environments. */
@@ -454,16 +493,25 @@ export interface PasteMachine {
454
493
  * accepted content are ignored and left untouched for the browser.
455
494
  */
456
495
  readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
457
- /** Back to `idle`, discarding any in-flight result. */
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`. */
458
503
  readonly reset: () => void;
459
504
  /**
460
505
  * Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
461
- * cleanup clears timers, drops in-flight results and unsticks `reading`.
506
+ * cleanup clears timers, drops in-flight results, aborts in-flight work and
507
+ * unsticks `reading`.
462
508
  * Safe to call repeatedly (React StrictMode).
463
509
  */
464
510
  readonly connect: () => () => void;
465
511
  }
466
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;
467
515
  /** Framework-agnostic paste state machine. */
468
516
  export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
469
517
  //#endregion
@@ -480,7 +528,7 @@ interface UseCopyResult {
480
528
  readonly copy: CopyMachine['copy'];
481
529
  /** Stable identity. Re-attempts the last failed payload, up to `maxRetries`. */
482
530
  readonly retry: CopyMachine['retry'];
483
- /** Stable identity. Back to `idle`, discarding any in-flight result. */
531
+ /** Stable identity. Back to `idle`, discarding and aborting any in-flight copy. */
484
532
  readonly reset: CopyMachine['reset'];
485
533
  }
486
534
  /**
@@ -657,11 +705,15 @@ interface UsePasteResult<T extends Element = HTMLElement> {
657
705
  /** The latest result while `status === 'read'`, otherwise `null`. */
658
706
  readonly result: PasteResult | null;
659
707
  readonly error: CopyError | null;
708
+ /** Whether `retry()` can do anything right now. */
709
+ readonly canRetry: boolean;
660
710
  /** Stable identity. Reads the clipboard from a user gesture. Never rejects. */
661
711
  readonly paste: PasteMachine['paste'];
662
712
  /** Stable identity. Handles a paste event you received yourself. Never rejects. */
663
713
  readonly pasteEvent: PasteMachine['pasteEvent'];
664
- /** Stable identity. Back to `idle`, discarding any in-flight result. */
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. */
665
717
  readonly reset: PasteMachine['reset'];
666
718
  /** Spread onto an element (drop zone, textarea, editor) to accept Ctrl/⌘+V there. */
667
719
  readonly targetProps: PasteTargetProps<T>;
@@ -773,11 +825,31 @@ interface PasteFieldTriggerRenderProps {
773
825
  readonly displayStatus: PasteStatus;
774
826
  readonly state: PasteState;
775
827
  readonly revealed: boolean;
828
+ /** Whether `retry()` could help after the current error. */
829
+ readonly canRetry: boolean;
776
830
  }
777
831
  interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'type'> {
778
832
  /** Static content, or a render function receiving the live state. */
779
833
  readonly children?: ReactNode | ((props: PasteFieldTriggerRenderProps) => ReactNode);
780
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
+ }
781
853
  /**
782
854
  * Headless compound component for a labelled, paste-ready field.
783
855
  *
@@ -792,6 +864,7 @@ interface PasteFieldTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
792
864
  * <PasteField.Label />
793
865
  * <PasteField.Zone />
794
866
  * <PasteField.Trigger />
867
+ * <PasteField.Preview placeholder="Nothing pasted yet" />
795
868
  * </PasteField.Root>
796
869
  * ```
797
870
  */
@@ -801,7 +874,8 @@ export declare const PasteField: {
801
874
  readonly Status: import("react").ForwardRefExoticComponent<PasteFieldStatusProps & import("react").RefAttributes<HTMLSpanElement>>;
802
875
  readonly Zone: import("react").ForwardRefExoticComponent<PasteFieldZoneProps & import("react").RefAttributes<HTMLDivElement>>;
803
876
  readonly Trigger: import("react").ForwardRefExoticComponent<PasteFieldTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
877
+ readonly Preview: import("react").ForwardRefExoticComponent<PasteFieldPreviewProps & import("react").RefAttributes<HTMLDivElement>>;
804
878
  };
805
879
  //#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 };
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 };
807
881
  //# sourceMappingURL=index.d.ts.map