react-smart-copy 1.17.2 → 1.18.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.
Files changed (146) hide show
  1. package/README.md +9 -3
  2. package/dist/capture.cjs +30 -153
  3. package/dist/capture.cjs.map +1 -1
  4. package/dist/capture.d.cts +2 -25
  5. package/dist/capture.d.ts +2 -25
  6. package/dist/capture.js +5 -128
  7. package/dist/capture.js.map +1 -1
  8. package/dist/chunks/clipboard-adapter-Cfz-rzw3.cjs +102 -0
  9. package/dist/chunks/clipboard-adapter-Cfz-rzw3.cjs.map +1 -0
  10. package/dist/chunks/clipboard-adapter-CtH4VELE.d.cts +43 -0
  11. package/dist/chunks/clipboard-adapter-DEXkXxwV.js +97 -0
  12. package/dist/chunks/clipboard-adapter-DEXkXxwV.js.map +1 -0
  13. package/dist/chunks/clipboard-adapter-Ds0irroN.d.ts +43 -0
  14. package/dist/chunks/contrast-C6CVklEI.cjs +842 -0
  15. package/dist/chunks/contrast-C6CVklEI.cjs.map +1 -0
  16. package/dist/chunks/contrast-DpK2JIVu.js +789 -0
  17. package/dist/chunks/contrast-DpK2JIVu.js.map +1 -0
  18. package/dist/chunks/copy-interceptor-C6NABy1l.d.ts +141 -0
  19. package/dist/chunks/copy-interceptor-CZWzGOkL.d.cts +141 -0
  20. package/dist/chunks/core-Cp2HSpaz.js +1035 -0
  21. package/dist/chunks/core-Cp2HSpaz.js.map +1 -0
  22. package/dist/chunks/core-DYf_Lhbe.cjs +1142 -0
  23. package/dist/chunks/core-DYf_Lhbe.cjs.map +1 -0
  24. package/dist/chunks/deadline-C29AlS_Q.js +46 -0
  25. package/dist/chunks/deadline-C29AlS_Q.js.map +1 -0
  26. package/dist/chunks/deadline-DkiB8ZHE.cjs +51 -0
  27. package/dist/chunks/deadline-DkiB8ZHE.cjs.map +1 -0
  28. package/dist/chunks/errors-9h8sdFFX.js +120 -0
  29. package/dist/chunks/errors-9h8sdFFX.js.map +1 -0
  30. package/dist/chunks/errors-BwOF6T_M.cjs +167 -0
  31. package/dist/chunks/errors-BwOF6T_M.cjs.map +1 -0
  32. package/dist/chunks/index-mr7sSAgP.d.ts +426 -0
  33. package/dist/chunks/index-vz0iW5V2.d.cts +426 -0
  34. package/dist/chunks/mime--LB7kdqG.cjs +153 -0
  35. package/dist/chunks/mime--LB7kdqG.cjs.map +1 -0
  36. package/dist/chunks/mime-aa-HA2dm.js +100 -0
  37. package/dist/chunks/mime-aa-HA2dm.js.map +1 -0
  38. package/dist/chunks/paste-adapter--SPL4PRE.d.cts +35 -0
  39. package/dist/chunks/paste-adapter-uahXnTYk.d.ts +35 -0
  40. package/dist/chunks/paste-reader-Bo01IMC_.cjs +289 -0
  41. package/dist/chunks/paste-reader-Bo01IMC_.cjs.map +1 -0
  42. package/dist/chunks/paste-reader-D9i7yMXF.js +224 -0
  43. package/dist/chunks/paste-reader-D9i7yMXF.js.map +1 -0
  44. package/dist/chunks/paste-reader-DcXnRWQr.d.cts +96 -0
  45. package/dist/chunks/paste-reader-DcXnRWQr.d.ts +96 -0
  46. package/dist/chunks/payload-CUymxwim.cjs +100 -0
  47. package/dist/chunks/payload-CUymxwim.cjs.map +1 -0
  48. package/dist/chunks/payload-CcwKJ_bU.d.cts +162 -0
  49. package/dist/chunks/payload-Cl_8hCI5.d.ts +162 -0
  50. package/dist/chunks/payload-DGw-JOo7.js +71 -0
  51. package/dist/chunks/payload-DGw-JOo7.js.map +1 -0
  52. package/dist/chunks/payload-DI5AorDz.js +103 -0
  53. package/dist/chunks/payload-DI5AorDz.js.map +1 -0
  54. package/dist/chunks/payload-J6GjHuh3.cjs +132 -0
  55. package/dist/chunks/payload-J6GjHuh3.cjs.map +1 -0
  56. package/dist/chunks/share-Bop47Znn.js +208 -0
  57. package/dist/chunks/share-Bop47Znn.js.map +1 -0
  58. package/dist/chunks/share-C0esXvRK.d.cts +115 -0
  59. package/dist/chunks/share-ayDz974N.cjs +231 -0
  60. package/dist/chunks/share-ayDz974N.cjs.map +1 -0
  61. package/dist/chunks/share-e7FenIr2.d.ts +115 -0
  62. package/dist/chunks/text-field-Ba8W3v4R.cjs +77 -0
  63. package/dist/chunks/text-field-Ba8W3v4R.cjs.map +1 -0
  64. package/dist/chunks/text-field-C0SGmvvR.d.cts +18 -0
  65. package/dist/chunks/text-field-C0SGmvvR.d.ts +18 -0
  66. package/dist/chunks/text-field-DUvrMMaK.js +66 -0
  67. package/dist/chunks/text-field-DUvrMMaK.js.map +1 -0
  68. package/dist/chunks/url-BcMYVCXQ.js +135 -0
  69. package/dist/chunks/url-BcMYVCXQ.js.map +1 -0
  70. package/dist/chunks/url-D4PGsRm8.cjs +164 -0
  71. package/dist/chunks/url-D4PGsRm8.cjs.map +1 -0
  72. package/dist/chunks/url-DWdElCT3.d.cts +43 -0
  73. package/dist/chunks/url-DWdElCT3.d.ts +43 -0
  74. package/dist/code.cjs +20 -112
  75. package/dist/code.cjs.map +1 -1
  76. package/dist/code.d.cts +4 -28
  77. package/dist/code.d.ts +4 -28
  78. package/dist/code.js +3 -95
  79. package/dist/code.js.map +1 -1
  80. package/dist/color.cjs +21 -893
  81. package/dist/color.cjs.map +1 -1
  82. package/dist/color.d.cts +4 -28
  83. package/dist/color.d.ts +4 -28
  84. package/dist/color.js +4 -876
  85. package/dist/color.js.map +1 -1
  86. package/dist/core.cjs +52 -1659
  87. package/dist/core.d.cts +8 -878
  88. package/dist/core.d.ts +8 -878
  89. package/dist/core.js +7 -1614
  90. package/dist/image.cjs +23 -94
  91. package/dist/image.cjs.map +1 -1
  92. package/dist/image.d.cts +1 -0
  93. package/dist/image.d.ts +1 -0
  94. package/dist/image.js +3 -74
  95. package/dist/image.js.map +1 -1
  96. package/dist/index.cjs +74 -2072
  97. package/dist/index.cjs.map +1 -1
  98. package/dist/index.d.cts +8 -978
  99. package/dist/index.d.ts +8 -978
  100. package/dist/index.js +7 -2005
  101. package/dist/index.js.map +1 -1
  102. package/dist/link.cjs +24 -338
  103. package/dist/link.cjs.map +1 -1
  104. package/dist/link.d.cts +5 -83
  105. package/dist/link.d.ts +5 -83
  106. package/dist/link.js +5 -319
  107. package/dist/link.js.map +1 -1
  108. package/dist/markdown.cjs +8 -97
  109. package/dist/markdown.cjs.map +1 -1
  110. package/dist/markdown.d.cts +3 -16
  111. package/dist/markdown.d.ts +3 -16
  112. package/dist/markdown.js +3 -92
  113. package/dist/markdown.js.map +1 -1
  114. package/dist/rich.cjs +26 -934
  115. package/dist/rich.cjs.map +1 -1
  116. package/dist/rich.d.cts +4 -90
  117. package/dist/rich.d.ts +4 -90
  118. package/dist/rich.js +4 -912
  119. package/dist/rich.js.map +1 -1
  120. package/dist/share.cjs +5 -640
  121. package/dist/share.d.cts +3 -248
  122. package/dist/share.d.ts +3 -248
  123. package/dist/share.js +1 -637
  124. package/dist/structured.cjs +13 -95
  125. package/dist/structured.cjs.map +1 -1
  126. package/dist/structured.d.cts +2 -11
  127. package/dist/structured.d.ts +2 -11
  128. package/dist/structured.js +4 -86
  129. package/dist/structured.js.map +1 -1
  130. package/dist/table.cjs +11 -39
  131. package/dist/table.cjs.map +1 -1
  132. package/dist/table.d.cts +2 -12
  133. package/dist/table.d.ts +2 -12
  134. package/dist/table.js +2 -30
  135. package/dist/table.js.map +1 -1
  136. package/dist/testing.cjs +10 -43
  137. package/dist/testing.cjs.map +1 -1
  138. package/dist/testing.d.cts +6 -181
  139. package/dist/testing.d.ts +6 -181
  140. package/dist/testing.js +3 -36
  141. package/dist/testing.js.map +1 -1
  142. package/package.json +20 -2
  143. package/dist/core.cjs.map +0 -1
  144. package/dist/core.js.map +0 -1
  145. package/dist/share.cjs.map +0 -1
  146. package/dist/share.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -1,881 +1,12 @@
1
1
 
2
+ import { A as resolveMaxRetries, C as describeCopyError, D as toCopyError, E as isRetryableError, O as DEFAULT_MAX_RETRIES, S as createCopyError, T as isCopyFailure, _ as ClipboardOperation, a as CopySource, b as CopyFailure, c as ImagePayload, d as MultiPayloadItem, f as TextPayload, g as validatePayload, h as serializeJson, i as CopyPayloadKind, k as OperationContext, l as JsonPayload, m as normalizePayload, n as CopyInput, o as HtmlPayload, p as isBlob, r as CopyPayload, s as IMAGE_MIME_TYPE, t as BlobSource, u as MultiPayload, v as CopyError, w as describePasteError, x as copyFailure, y as CopyErrorType } from "./chunks/payload-Cl_8hCI5.js";
3
+ import { _ as resolvePasteReadOptions, a as DataTransferItemLike, c as PasteAcceptShorthand, d as PasteReadOptions, f as PasteReadResult, g as canAcceptDrag, h as ResolvedPasteReadOptions, i as DEFAULT_PASTE_MAX_ITEMS, l as PasteItem, m as PasteSource, n as DEFAULT_PASTE_ACCEPT, o as DataTransferLike, p as PasteResult, r as DEFAULT_PASTE_MAX_BYTES, s as PasteAccept, t as ClipboardItemLike, u as PasteLimits } from "./chunks/paste-reader-DcXnRWQr.js";
4
+ import { $ as SVG_MIME_TYPE, A as RegisterDragCopyResult, B as CopyState, C as DragCopyPayload, D as DragEffectAllowed, E as DragCopyStatus, F as CopyIgnoredReason, G as IDLE_STATE, H as CopyingState, I as CopyMachine, J as createCopyMachine, K as IdleState, L as CopyMachineOptions, M as registerDragCopy, N as CopiedState, O as DragMultiPayload, P as CopyCancelReason, Q as RasterImageMimeType, R as CopyMachineOptionsSource, S as DragCopyPassReason, T as DragCopyState, U as DEFAULT_RESET_AFTER_MS, V as CopyStatus, W as ErrorState, X as CopyCoordinatorMember, Y as CopyCoordinator, Z as createCopyCoordinator, _ as createPasteMachine, a as PasteEventLike, at as normalizeMimeType, b as DragCopyOptions, c as PasteMachine, d as PasteOutcome, et as WEB_CUSTOM_FORMAT_PREFIX, f as PasteReadState, g as canRetryPasteState, h as PasteStatus, i as PasteErrorState, it as normalizeClipboardType, j as applyDragCopy, k as DragStartEventLike, l as PasteMachineOptions, m as PasteState, n as PasteCancelReason, nt as isWebCustomFormat, o as PasteIdleState, ot as sniffImageBytes, p as PasteReadingState, q as canRetryState, r as PasteDropEventLike, rt as matchesMimePattern, s as PasteIgnoredReason, st as sniffImageType, t as PASTE_IDLE_STATE, tt as isTextualMimeType, u as PasteMachineOptionsSource, v as DragCopyDecision, w as DragCopySource, x as DragCopyOutcome, y as DragCopyItem, z as CopyOutcome } from "./chunks/index-mr7sSAgP.js";
5
+ import { a as ClipboardItemData, i as ClipboardItemConstructorLike, n as ClipboardAdapter, o as ClipboardLike, r as ClipboardEnvironment, s as createBrowserClipboardAdapter, t as BrowserClipboardAdapterOptions } from "./chunks/clipboard-adapter-Ds0irroN.js";
6
+ import { _ as registerCopyInterceptor, a as CopyInterceptOptions, c as CopyInterceptTransform, d as DEFAULT_INTERCEPTED_EVENTS, f as InterceptedCopyKind, g as readCopySelection, h as interceptCopyEvent, i as CopyInterceptFailureMode, l as CopyInterceptorOptions, m as SyncMultiPayload, n as CopyEventLike, o as CopyInterceptOutcome, p as SyncCopyPayload, r as CopyInterceptDecision, s as CopyInterceptPassReason, t as ClipboardDataLike, u as CopySelection } from "./chunks/copy-interceptor-C6NABy1l.js";
7
+ import { a as createBrowserPasteAdapter, i as PasteEnvironment, n as PasteAdapter, r as PasteClipboardLike, t as BrowserPasteAdapterOptions } from "./chunks/paste-adapter-uahXnTYk.js";
8
+ import { a as ShareMethod, c as ShareOutcome, i as ShareEnvironment, n as ResolvedShare, o as ShareMode, r as ShareContent, s as ShareOptions, t as CopyReason } from "./chunks/share-e7FenIr2.js";
2
9
  import { ButtonHTMLAttributes, CSSProperties, ClipboardEventHandler, DragEventHandler, FocusEventHandler, HTMLAttributes, PointerEventHandler, ReactNode, RefCallback } from "react";
3
- //#region src/core/paste-reader.d.ts
4
- /** Friendly names for the common cases. */
5
- type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
6
- /**
7
- * What a paste may contain, in any order: a shorthand, an exact MIME type
8
- * (`'image/png'`), a web custom format (`'web application/vnd.acme+json'`) or a
9
- * wildcard (`'image/*'`, `'*\/*'`). `image/svg+xml` (scriptable XML), web custom
10
- * formats and `+json` types are only accepted when listed exactly.
11
- */
12
- type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
13
- interface PasteLimits {
14
- /**
15
- * Total size cap across all accepted items, in UTF-8 bytes. Strings are measured as
16
- * they would be encoded, matching `Blob.size`, so every paste path counts the same way.
17
- * Default 32 MiB.
18
- */
19
- readonly maxBytes?: number;
20
- /** Max number of accepted items (types + files). Default 32. */
21
- readonly maxItems?: number;
22
- }
23
- interface PasteReadOptions extends PasteLimits {
24
- /** Default `['text']` (plain text only): the safest choice. */
25
- readonly accept?: readonly PasteAccept[];
26
- }
27
- /** Validated, normalised options that adapters receive. */
28
- interface ResolvedPasteReadOptions {
29
- /** Normalised patterns: `type/subtype`, `type/*` or `*\/*`. */
30
- readonly accept: readonly string[];
31
- readonly maxBytes: number;
32
- readonly maxItems: number;
33
- }
34
- /** Where the content came from: a Clipboard API read, a `paste` event, or a drag-and-drop `drop` event. */
35
- type PasteSource = 'clipboard' | 'event' | 'drop';
36
- /** One accepted clipboard entry. Textual types are decoded to `string`, everything else stays a `Blob`. */
37
- interface PasteItem {
38
- readonly type: string;
39
- readonly data: string | Blob;
40
- }
41
- /**
42
- * Everything the paste produced. Treat all of it as untrusted user input:
43
- * in particular never inject `html` into the DOM without sanitising it.
44
- */
45
- interface PasteResult {
46
- readonly source: PasteSource;
47
- /** Every accepted entry, in clipboard order. */
48
- readonly items: readonly PasteItem[];
49
- /** `text/plain`, when accepted and present. */
50
- readonly text: string | null;
51
- /** `text/html`, when accepted and present. UNTRUSTED markup: sanitise before rendering. */
52
- readonly html: string | null;
53
- /** Raster images, verified from their bytes (PNG, JPEG, GIF, WebP, AVIF, BMP), typed accordingly. */
54
- readonly images: readonly Blob[];
55
- /** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
56
- readonly files: readonly File[];
57
- /**
58
- * The entries of `files` that are also in `images`: verified image files, keeping their
59
- * names, ready for `FormData`. Derived by the paste machine, so it is always consistent.
60
- */
61
- readonly imageFiles: readonly File[];
62
- }
63
- /** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
64
- type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
65
- export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
66
- export declare const DEFAULT_PASTE_MAX_BYTES: number;
67
- export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
68
- /** Validates and normalises paste options. Throws a classified `invalid-payload` failure. */
69
- export declare function resolvePasteReadOptions(options?: PasteReadOptions): ResolvedPasteReadOptions;
70
- /** Structural view of a `DataTransferItem`: only what is readable while dragging. */
71
- interface DataTransferItemLike {
72
- /** `'string'` or `'file'`. */
73
- readonly kind: string;
74
- readonly type: string;
75
- }
76
- /** Structural view of `DataTransfer` (paste and drop events). */
77
- export interface DataTransferLike {
78
- readonly types: ArrayLike<string>;
79
- getData(format: string): string;
80
- readonly files?: ArrayLike<File> | null;
81
- readonly items?: ArrayLike<DataTransferItemLike> | null;
82
- }
83
- /**
84
- * Whether a drag in progress could drop anything `accept`s. Uses only what
85
- * browsers expose before the drop (item kinds and types, never the data).
86
- * A file whose type is not known yet (some browsers hide it while dragging)
87
- * counts as a maybe: the drop itself is checked against `accept`.
88
- */
89
- export declare function canAcceptDrag(data: DataTransferLike, options: ResolvedPasteReadOptions): boolean;
90
- /** Structural view of a `ClipboardItem` as returned by `navigator.clipboard.read()`. */
91
- interface ClipboardItemLike {
92
- readonly types: readonly string[];
93
- getType(type: string): Promise<Blob>;
94
- }
95
- //#endregion
96
- //#region src/core/errors.d.ts
97
- /**
98
- * Every way a clipboard operation can fail, as a closed union.
99
- *
100
- * `CopyError.message` is developer-facing (logs, telemetry). For user-facing
101
- * text use {@link describeCopyError} / {@link describePasteError}, or map
102
- * `type` through your own i18n layer.
103
- */
104
- export type CopyErrorType =
105
- /** No Clipboard API (old browser, server, locked-down webview). Not retryable. */
106
- 'unsupported' |
107
- /** Page is not served over HTTPS/localhost. Not retryable. */
108
- 'insecure-context' |
109
- /** Browser or user blocked the operation. Also what Safari reports for a missing user gesture. */
110
- 'permission-denied' |
111
- /** The document lost focus mid-operation (Chromium). Retrying after refocus usually works. */
112
- 'not-focused' |
113
- /** Empty or malformed payload, or a lazy source that threw. Caught before touching the clipboard. */
114
- 'invalid-payload' |
115
- /** The browser cannot handle this MIME type (e.g. non-PNG image, HTML without ClipboardItem). */
116
- 'unsupported-format' |
117
- /** A lazy image source (or capture) threw, rejected or did not produce a Blob. */
118
- 'blob-generation-failed' |
119
- /** `retry()` was called after `maxRetries` was reached. Terminal. */
120
- 'max-retries-exceeded' |
121
- /** Paste: the clipboard held nothing matching `accept`. */
122
- 'no-content' |
123
- /** Content exceeded a configured safety limit (bytes, items or pixels). Not retryable. */
124
- 'too-large' |
125
- /** An operation did not settle within its deadline. Retryable. */
126
- 'timeout' |
127
- /** The caller aborted the operation through an `AbortSignal`. Not retryable. */
128
- 'aborted' |
129
- /** Anything the platform threw that we could not classify. */
130
- 'unknown';
131
- /** Which clipboard direction failed; only changes developer-facing messages. */
132
- export type ClipboardOperation = 'write' | 'read';
133
- export interface CopyError {
134
- readonly type: CopyErrorType;
135
- readonly message: string;
136
- readonly cause?: unknown;
137
- }
138
- export declare function createCopyError(type: CopyErrorType, message: string, cause?: unknown): CopyError;
139
- /** Whether retrying the same payload could plausibly succeed. */
140
- export declare function isRetryableError(error: CopyError): boolean;
141
- /**
142
- * Branded (not `instanceof`) so failures stay recognisable even when the core
143
- * is bundled twice, e.g. `react-smart-copy` and `react-smart-copy/core` together.
144
- */
145
- declare const COPY_FAILURE_BRAND: unique symbol;
146
- /** Error thrown by adapters to carry a fully classified {@link CopyError}. */
147
- export declare class CopyFailure extends Error {
148
- readonly copyError: CopyError;
149
- readonly [COPY_FAILURE_BRAND] = true;
150
- constructor(copyError: CopyError);
151
- }
152
- export declare function isCopyFailure(value: unknown): value is CopyFailure;
153
- /** Shorthand for throwing a classified failure. */
154
- export declare function copyFailure(type: CopyErrorType, message: string, cause?: unknown): CopyFailure;
155
- /**
156
- * Classifies anything thrown by the platform or an adapter into a {@link CopyError}.
157
- * `operation` only tailors the developer-facing message.
158
- */
159
- export declare function toCopyError(cause: unknown, operation?: ClipboardOperation): CopyError;
160
- /** Default English, user-facing sentence for a copy error. Replace for i18n. */
161
- export declare function describeCopyError(error: CopyError): string;
162
- /**
163
- * Default English, user-facing sentence for a paste error. Pass the error
164
- * state's `source` to word drag-and-drop failures as drops. Replace for i18n.
165
- */
166
- export declare function describePasteError(error: CopyError, source?: PasteSource): string;
167
- //#endregion
168
- //#region src/core/machine-shared.d.ts
169
- /**
170
- * Internals shared by the copy and paste state machines. Kept in one module so
171
- * apps that use both don't ship two copies.
172
- */
173
- export declare const DEFAULT_MAX_RETRIES = 3;
174
- /**
175
- * Passed to adapters and lazy sources as their last argument. `signal` aborts
176
- * when the operation is superseded, `reset()`, or its host unmounts, so
177
- * expensive work (rasterising, decoding) can stop early.
178
- */
179
- interface OperationContext {
180
- readonly signal: AbortSignal;
181
- }
182
- export declare function resolveMaxRetries(value: number | undefined): number;
183
- //#endregion
184
- //#region src/core/payload.d.ts
185
- /** The only image MIME type with reliable cross-browser clipboard write support. */
186
- export declare const IMAGE_MIME_TYPE = "image/png";
187
- /**
188
- * An image as a Blob, a promise of one, or a function producing one.
189
- * Prefer the function form: it is invoked synchronously inside the user
190
- * gesture, which Safari requires for async image generation. The browser
191
- * adapter always passes an `OperationContext`: stop work once
192
- * `context.signal` aborts (reset, superseded, unmount). Optional in the type
193
- * so adapters that call sources themselves keep compiling.
194
- */
195
- export type BlobSource = Blob | PromiseLike<Blob> | ((context?: OperationContext) => Blob | PromiseLike<Blob>);
196
- export interface TextPayload {
197
- readonly kind: 'text';
198
- readonly value: string;
199
- }
200
- export interface HtmlPayload {
201
- readonly kind: 'html';
202
- readonly html: string;
203
- /** Required plain-text fallback for targets that don't understand HTML. */
204
- readonly text: string;
205
- }
206
- export interface ImagePayload {
207
- readonly kind: 'image';
208
- readonly blob: BlobSource;
209
- }
210
- export interface JsonPayload {
211
- readonly kind: 'json';
212
- readonly value: unknown;
213
- /** `true` = 2-space indent, a number = that indent, falsy = compact. */
214
- readonly pretty?: boolean | number;
215
- }
216
- export interface MultiPayloadItem {
217
- /**
218
- * The MIME type, or a web custom format (`web application/vnd.acme+json`).
219
- * Web custom formats are only written by the async Clipboard API; copy and drag
220
- * events skip them.
221
- */
222
- readonly mimeType: string;
223
- readonly data: string | Blob;
224
- /**
225
- * Skip this item, instead of failing the copy, when the browser cannot write its type.
226
- * An optional item is only written when `ClipboardItem.supports()` confirms the type.
227
- * At least one item must be written.
228
- */
229
- readonly optional?: boolean;
230
- }
231
- export interface MultiPayload {
232
- readonly kind: 'multi';
233
- readonly items: readonly MultiPayloadItem[];
234
- }
235
- export type CopyPayload = TextPayload | HtmlPayload | ImagePayload | JsonPayload | MultiPayload;
236
- export type CopyPayloadKind = CopyPayload['kind'];
237
- /** A payload, or a bare string as shorthand for `{ kind: 'text' }`. */
238
- export type CopyInput = string | CopyPayload;
239
- /**
240
- * What `copy()` accepts. The function form is resolved synchronously at copy
241
- * time, so it always reads the latest value without re-rendering.
242
- */
243
- export type CopySource = CopyInput | (() => CopyInput);
244
- export declare function normalizePayload(input: CopyInput): CopyPayload;
245
- export declare function isBlob(value: unknown): value is Blob;
246
- /**
247
- * Structural validation. Typed callers can't produce most of these states,
248
- * but plain-JS callers and runtime data can, so the check is always on.
249
- */
250
- export declare function validatePayload(payload: unknown): CopyError | null;
251
- /** Serialises a JSON payload, throwing a classified failure instead of a raw TypeError. */
252
- export declare function serializeJson(payload: JsonPayload): string;
253
- //#endregion
254
- //#region src/core/mime.d.ts
255
- /**
256
- * MIME helpers shared by paste and capture. Everything that comes from the
257
- * clipboard is untrusted input, so types are normalised and validated before
258
- * they are compared, and image types are confirmed from the bytes themselves.
259
- */
260
- /** SVG is XML that can carry scripts; it is never matched by a wildcard. */
261
- export declare const SVG_MIME_TYPE = "image/svg+xml";
262
- /** Lower-cased `type/subtype` without parameters, or `null` if it is not a valid MIME type. */
263
- export declare function normalizeMimeType(value: string): string | null;
264
- /** Prefix of the async Clipboard API's web custom formats (`web application/vnd.acme+json`). */
265
- export declare const WEB_CUSTOM_FORMAT_PREFIX = "web ";
266
- /** Whether a clipboard type is a web custom format (`web type/subtype`). */
267
- export declare function isWebCustomFormat(type: string): boolean;
268
- /**
269
- * Like {@link normalizeMimeType}, but also accepts web custom formats
270
- * (`web type/subtype`), returned as `web ` + the normalised MIME type.
271
- */
272
- export declare function normalizeClipboardType(value: string): string | null;
273
- /**
274
- * Does `mimeType` (already normalised) match `pattern` (`type/subtype`, `type/*` or `*\/*`)?
275
- * Wildcards never match `image/svg+xml`, web custom formats or `+json` types: those must be listed exactly.
276
- */
277
- export declare function matchesMimePattern(mimeType: string, pattern: string): boolean;
278
- /** Types whose clipboard data is text and is therefore surfaced as a `string`. */
279
- export declare function isTextualMimeType(mimeType: string): boolean;
280
- /** Raster image formats recognised from their leading bytes. */
281
- export type RasterImageMimeType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'image/bmp' | 'image/avif';
282
- /** Identifies a raster image from its magic bytes, ignoring whatever type the Blob claims. */
283
- export declare function sniffImageBytes(bytes: Uint8Array): RasterImageMimeType | null;
284
- /** Reads only the first bytes of a Blob, so sniffing a 20 MB screenshot stays cheap. */
285
- export declare function sniffImageType(blob: Blob): Promise<RasterImageMimeType | null>;
286
- //#endregion
287
- //#region src/core/clipboard-adapter.d.ts
288
- /** Minimal structural view of `navigator.clipboard`, so fakes and polyfills fit. */
289
- export interface ClipboardLike {
290
- writeText?(text: string): Promise<void>;
291
- write?(items: readonly unknown[]): Promise<void>;
292
- }
293
- export type ClipboardItemData = Blob | PromiseLike<Blob>;
294
- export interface ClipboardItemConstructorLike {
295
- new (items: Record<string, ClipboardItemData>): unknown;
296
- supports?(type: string): boolean;
297
- }
298
- export interface ClipboardEnvironment {
299
- readonly isSecureContext?: boolean;
300
- readonly navigator?: {
301
- readonly clipboard?: ClipboardLike | undefined;
302
- } | undefined;
303
- readonly ClipboardItem?: ClipboardItemConstructorLike | undefined;
304
- }
305
- /**
306
- * The only thing the state machine needs. Implement it to target Electron,
307
- * a native bridge, a test double, or anything else.
308
- *
309
- * Contract: start the platform write synchronously (before any `await`) so the
310
- * browser still sees the user gesture, and reject with a `CopyFailure` when you
311
- * can classify the error. `context.signal` aborts when the copy is reset or its
312
- * host unmounts; honour it to stop expensive work early.
313
- */
314
- export interface ClipboardAdapter {
315
- write(payload: CopyPayload, context?: OperationContext): Promise<void>;
316
- }
317
- export interface BrowserClipboardAdapterOptions {
318
- /** Defaults to `window`, read lazily at copy time (SSR-safe). */
319
- readonly getEnvironment?: () => ClipboardEnvironment | undefined;
320
- /** When rich HTML copy is unavailable, fall back to its plain text. Default `true`. */
321
- readonly degradeHtmlToText?: boolean;
322
- }
323
- /** The default adapter: async Clipboard API with feature detection and honest errors. */
324
- export declare function createBrowserClipboardAdapter(options?: BrowserClipboardAdapterOptions): ClipboardAdapter;
325
- //#endregion
326
- //#region src/core/copy-coordinator.d.ts
327
- /**
328
- * A copy machine as seen by a coordinator. `release()` returns it from
329
- * `copied` to `idle`; it is a no-op in any other state.
330
- */
331
- export interface CopyCoordinatorMember {
332
- readonly release: () => void;
333
- }
334
- /**
335
- * Makes a set of copy machines behave like one clipboard: when a member
336
- * succeeds, the member that previously showed "Copied" goes back to idle,
337
- * because the clipboard no longer holds its value.
338
- *
339
- * Failed copies never release anyone (the clipboard still holds the previous value).
340
- */
341
- export interface CopyCoordinator {
342
- /** A member just reached `copied`. Releases the previous one. */
343
- readonly activate: (member: CopyCoordinatorMember) => void;
344
- /** A member left `copied` on its own (auto-reset, reset, unmount). */
345
- readonly deactivate: (member: CopyCoordinatorMember) => void;
346
- /** The member currently showing `copied`, if any. */
347
- readonly getActive: () => CopyCoordinatorMember | null;
348
- }
349
- export declare function createCopyCoordinator(): CopyCoordinator;
350
- //#endregion
351
- //#region src/core/copy-machine.d.ts
352
- export declare const DEFAULT_RESET_AFTER_MS = 2000;
353
- export interface IdleState {
354
- readonly status: 'idle';
355
- }
356
- export interface CopyingState {
357
- readonly status: 'copying';
358
- readonly payload: CopyPayload;
359
- readonly retryCount: number;
360
- }
361
- export interface CopiedState {
362
- readonly status: 'copied';
363
- readonly payload: CopyPayload;
364
- /** Epoch ms when the write resolved. */
365
- readonly at: number;
366
- }
367
- export interface ErrorState {
368
- readonly status: 'error';
369
- /** `null` when the input itself could not be resolved. */
370
- readonly payload: CopyPayload | null;
371
- readonly error: CopyError;
372
- readonly retryCount: number;
373
- }
374
- export type CopyState = IdleState | CopyingState | CopiedState | ErrorState;
375
- export type CopyStatus = CopyState['status'];
376
- /**
377
- * `cancelled`: the copy was reset or its host unmounted before it finished,
378
- * so its work was aborted. Nothing to report to the user.
379
- */
380
- export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
381
- /**
382
- * Why an in-flight copy was cancelled: `reset` (`reset()` was called) or
383
- * `disconnect` (its host disconnected, e.g. the React component unmounted).
384
- */
385
- export type CopyCancelReason = 'reset' | 'disconnect';
386
- /** What `copy()`/`retry()` resolve to. They never reject. */
387
- export type CopyOutcome = {
388
- readonly status: 'copied';
389
- readonly payload: CopyPayload;
390
- } | {
391
- readonly status: 'error';
392
- readonly error: CopyError;
393
- } | {
394
- readonly status: 'ignored';
395
- readonly reason: CopyIgnoredReason;
396
- };
397
- export interface CopyMachineOptions {
398
- /** Defaults to the browser Clipboard API adapter. */
399
- readonly adapter?: ClipboardAdapter;
400
- /** Time in `copied` before returning to `idle`. `false`/`Infinity` disables. Default 2000. */
401
- readonly resetAfterMs?: number | false;
402
- /**
403
- * Max `retry()` calls after the first failure. Default 3. `0` disables
404
- * retry; `Infinity` allows unlimited retries.
405
- */
406
- readonly maxRetries?: number;
407
- /**
408
- * Share "Copied" with other machines: only one member of a coordinator
409
- * shows `copied` at a time. `null` explicitly opts out (e.g. of a React `<CopyGroup>`).
410
- */
411
- readonly coordinator?: CopyCoordinator | null;
412
- readonly onCopy?: (payload: CopyPayload) => void;
413
- readonly onError?: (error: CopyError, payload: CopyPayload | null) => void;
414
- /**
415
- * `reset()` moved the machine back to `idle` from any other state. Not
416
- * called for the automatic return after `resetAfterMs`, for a `<CopyGroup>`
417
- * handing "Copied" to another member, or when already `idle`.
418
- */
419
- readonly onReset?: () => void;
420
- /**
421
- * A copy in flight was cancelled before it settled: its `signal` aborted
422
- * and its result will not reach state or `onCopy` / `onError`. Fires
423
- * before `onReset` when `reset()` cancels a copy.
424
- */
425
- readonly onCancel?: (reason: CopyCancelReason) => void;
426
- /** Clock injection for tests and deterministic environments. */
427
- readonly now?: () => number;
428
- }
429
- /** Options object, or a getter so hosts (like React) can supply the latest options. */
430
- export type CopyMachineOptionsSource = CopyMachineOptions | (() => CopyMachineOptions);
431
- export interface CopyMachine {
432
- readonly getSnapshot: () => CopyState;
433
- readonly subscribe: (listener: () => void) => () => void;
434
- readonly copy: (source: CopySource) => Promise<CopyOutcome>;
435
- readonly retry: () => Promise<CopyOutcome>;
436
- /** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
437
- readonly reset: () => void;
438
- /**
439
- * Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
440
- * cleanup clears timers, drops in-flight results, aborts in-flight work and
441
- * unsticks `copying`.
442
- * Safe to call repeatedly (React StrictMode).
443
- */
444
- readonly connect: () => () => void;
445
- }
446
- export declare const IDLE_STATE: IdleState;
447
- /** Pure helper: can `retry()` do anything from this state? */
448
- export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
449
- /** Framework-agnostic copy state machine. */
450
- export declare function createCopyMachine(options?: CopyMachineOptionsSource): CopyMachine;
451
- //#endregion
452
- //#region src/core/copy-interceptor.d.ts
453
- /**
454
- * Native copy interception: rewrite, redact or block what lands on the
455
- * clipboard when the user copies (Ctrl/Cmd+C, context menu) or cuts inside a
456
- * scope.
457
- *
458
- * Writes go through `event.clipboardData` synchronously, so no permission
459
- * prompt, no secure-context requirement, and it works in every browser. The
460
- * price is that only strings can be written, which the types enforce.
461
- *
462
- * Not a security boundary: users can still screenshot, use dev tools or
463
- * disable script. Treat redaction as a guard against accidents.
464
- */
465
- export type InterceptedCopyKind = 'copy' | 'cut';
466
- export declare const DEFAULT_INTERCEPTED_EVENTS: readonly InterceptedCopyKind[];
467
- /** The writable slice of `DataTransfer` during a `copy`/`cut` event. */
468
- export interface ClipboardDataLike {
469
- setData(format: string, data: string): void;
470
- clearData?(format?: string): void;
471
- }
472
- /** Structural `ClipboardEvent`: DOM and React clipboard events both satisfy it. */
473
- export interface CopyEventLike {
474
- readonly type: string;
475
- readonly target: EventTarget | null;
476
- readonly clipboardData: ClipboardDataLike | null;
477
- readonly defaultPrevented: boolean;
478
- preventDefault(): void;
479
- }
480
- /** What the user selected when they copied. */
481
- export interface CopySelection {
482
- readonly kind: InterceptedCopyKind;
483
- /** What the browser would put on the clipboard as `text/plain`. */
484
- readonly text: string;
485
- /** Serialised HTML of the selection; `null` inside text inputs. */
486
- readonly html: string | null;
487
- /** A detached clone of the selected nodes, safe to mutate; `null` inside text inputs. */
488
- readonly fragment: DocumentFragment | null;
489
- /** The `<input>`/`<textarea>` the selection lives in, if any. */
490
- readonly field: HTMLInputElement | HTMLTextAreaElement | null;
491
- /** Whether a `cut` would remove the selection (form field or contenteditable). */
492
- readonly editable: boolean;
493
- }
494
- /**
495
- * A multi payload whose items are all strings; the only kind `setData` accepts.
496
- * Web custom formats (`web …`) are skipped: only the async Clipboard API writes them.
497
- */
498
- export interface SyncMultiPayload {
499
- readonly kind: 'multi';
500
- readonly items: readonly {
501
- readonly mimeType: string;
502
- readonly data: string;
503
- readonly optional?: boolean;
504
- }[];
505
- }
506
- /** Payloads writable synchronously during a copy event. Images need the async clipboard. */
507
- export type SyncCopyPayload = TextPayload | HtmlPayload | JsonPayload | SyncMultiPayload;
508
- /**
509
- * What a transform returns:
510
- * - a string or payload: write that instead of the selection
511
- * - `false`: block the copy (nothing reaches the clipboard; a cut deletes nothing)
512
- * - `null` / `undefined`: leave the browser's default copy untouched
513
- *
514
- * Must be synchronous: the clipboard closes when the event handler returns.
515
- */
516
- export type CopyInterceptDecision = string | SyncCopyPayload | false | null | undefined;
517
- export type CopyInterceptTransform = (selection: CopySelection) => CopyInterceptDecision;
518
- /**
519
- * When the transform throws or returns something unwritable:
520
- * - `'block'` (default): nothing is copied. Safe for redaction.
521
- * - `'native'`: the browser's default copy proceeds unmodified.
522
- */
523
- export type CopyInterceptFailureMode = 'block' | 'native';
524
- export interface CopyInterceptOptions {
525
- readonly transform: CopyInterceptTransform;
526
- readonly failureMode?: CopyInterceptFailureMode;
527
- }
528
- export type CopyInterceptPassReason =
529
- /** Not a `copy`/`cut` event. */
530
- 'unsupported-event' |
531
- /** Another handler already called `preventDefault()`. */
532
- 'already-handled' |
533
- /** Nothing readable was selected. */
534
- 'no-selection' |
535
- /** The transform returned `null`/`undefined`. */
536
- 'declined';
537
- export type CopyInterceptOutcome = {
538
- readonly status: 'passed';
539
- readonly reason: CopyInterceptPassReason;
540
- readonly selection: CopySelection | null;
541
- } | {
542
- readonly status: 'written';
543
- readonly selection: CopySelection;
544
- readonly payload: SyncCopyPayload;
545
- /** For an editable `cut`: whether the selection was removed. Always `false` for `copy`. */
546
- readonly deleted: boolean;
547
- } | {
548
- readonly status: 'blocked';
549
- readonly selection: CopySelection;
550
- } | {
551
- readonly status: 'failed';
552
- readonly selection: CopySelection;
553
- readonly error: CopyError;
554
- /** What actually happened to the copy. */
555
- readonly fallback: CopyInterceptFailureMode;
556
- };
557
- /** Reads the selection behind a copy event, or `null` if nothing readable is selected. */
558
- export declare function readCopySelection(event: CopyEventLike): CopySelection | null;
559
- /**
560
- * Applies a transform to one `copy`/`cut` event. Use directly from an
561
- * `onCopy` handler, or let {@link registerCopyInterceptor} scope it.
562
- */
563
- export declare function interceptCopyEvent(event: CopyEventLike, options: CopyInterceptOptions): CopyInterceptOutcome;
564
- export interface CopyInterceptorOptions extends CopyInterceptOptions {
565
- /**
566
- * When one selection touches several scopes, exactly one handles it: the
567
- * highest `priority`, then the innermost, then the first in the document.
568
- * The winner sees the *whole* selection. Give redaction scopes a higher
569
- * priority so text copied across them is always masked. Default `0`.
570
- */
571
- readonly priority?: number;
572
- /** Which events to intercept. Default: both `copy` and `cut`. */
573
- readonly events?: readonly InterceptedCopyKind[];
574
- /** Every outcome for selections inside this scope, including `passed`. */
575
- readonly onIntercept?: (outcome: CopyInterceptOutcome) => void;
576
- /** Called when the transform failed; the outcome's `fallback` says what happened to the copy. */
577
- readonly onError?: (error: CopyError) => void;
578
- }
579
- /**
580
- * Intercepts native copies and cuts whose selection touches `root`. Returns
581
- * an unsubscribe function. Pass a getter to always read the latest options.
582
- *
583
- * One listener per document serves every scope, so overlapping scopes
584
- * resolve deterministically (see `priority`) regardless of registration order.
585
- * Handlers that call `preventDefault()` first (e.g. a React `onCopy`) win.
586
- */
587
- export declare function registerCopyInterceptor(root: Element, options: CopyInterceptorOptions | (() => CopyInterceptorOptions)): () => void;
588
- //#endregion
589
- //#region src/core/drag-copy.d.ts
590
- /**
591
- * The `effectAllowed` a drag operation advertises. Controls which cursor the
592
- * browser shows and which `dropEffect` the drop target may request.
593
- *
594
- * - `'copy'` (default): dragging produces a copy of the data.
595
- * - `'move'`: dragging removes the source after a drop (the app must do this).
596
- * - `'link'`: dragging creates a link/reference.
597
- * - `'copyMove'` / `'copyLink'` / `'linkMove'` / `'all'`: combinations.
598
- * - `'none'`: the drag is not droppable anywhere.
599
- * - `'uninitialized'`: browser default (same as `'all'` in most cases).
600
- */
601
- export type DragEffectAllowed = 'copy' | 'move' | 'link' | 'copyMove' | 'copyLink' | 'linkMove' | 'all' | 'none' | 'uninitialized';
602
- /** What is put into `DataTransfer` when a drag starts. */
603
- export interface DragCopyItem {
604
- /** Web custom formats (`web …`) are skipped: only the async Clipboard API writes them. */
605
- readonly mimeType: string;
606
- readonly data: string;
607
- /** Accepted for parity with `MultiPayloadItem`; every non-web item can be written to a drag. */
608
- readonly optional?: boolean;
609
- }
610
- /**
611
- * A multi-format drag payload — strings only (DataTransfer only accepts strings).
612
- * Mirrors `SyncCopyPayload` from copy-interceptor but scoped to drag.
613
- */
614
- export type DragCopyPayload = TextPayload | HtmlPayload | JsonPayload | DragMultiPayload;
615
- export interface DragMultiPayload {
616
- readonly kind: 'multi';
617
- readonly items: readonly DragCopyItem[];
618
- }
619
- /**
620
- * What the source getter returns:
621
- * - a string: written as `text/plain`.
622
- * - a `DragCopyPayload`: written according to its `kind`.
623
- * - `false`: cancels the drag (`preventDefault()` on `dragstart`).
624
- * - `null` / `undefined`: leaves the browser's default drag data untouched.
625
- */
626
- export type DragCopyDecision = string | DragCopyPayload | false | null | undefined;
627
- /** Called once when the user begins dragging the element. Must be synchronous. */
628
- export type DragCopySource = (event: DragStartEventLike) => DragCopyDecision;
629
- /** Structural `DragEvent`: DOM and React drag events both satisfy it. */
630
- export interface DragStartEventLike {
631
- readonly type: string;
632
- readonly dataTransfer: DataTransferLike$1 | null;
633
- readonly defaultPrevented: boolean;
634
- preventDefault(): void;
635
- }
636
- /** The writable face of `DataTransfer`. */
637
- interface DataTransferLike$1 {
638
- effectAllowed: string;
639
- setData(format: string, data: string): void;
640
- clearData?(format?: string): void;
641
- }
642
- export type DragCopyStatus =
643
- /** No drag has started yet, or it was cancelled / never had source data. */
644
- 'idle' |
645
- /** The element is being dragged and data is on the DataTransfer. */
646
- 'dragging' |
647
- /** The drag ended (dropped or abandoned). */
648
- 'done';
649
- export type DragCopyPassReason =
650
- /** Source returned `null`/`undefined`. */
651
- 'declined' |
652
- /** `DataTransfer` is not present on this event. */
653
- 'no-transfer' |
654
- /** Source returned `false`. */
655
- 'cancelled';
656
- export type DragCopyOutcome = {
657
- readonly status: 'written';
658
- readonly payload: DragCopyPayload;
659
- } | {
660
- readonly status: 'passed';
661
- readonly reason: DragCopyPassReason;
662
- } | {
663
- readonly status: 'failed';
664
- readonly error: CopyError;
665
- };
666
- export interface DragCopyState {
667
- readonly status: DragCopyStatus;
668
- /** The last `dragstart` outcome; `null` before the first drag. */
669
- readonly outcome: DragCopyOutcome | null;
670
- }
671
- export interface DragCopyOptions {
672
- /**
673
- * Returns the data to put in the drag. Called synchronously on `dragstart`.
674
- * Return a string (shorthand for `{ kind: 'text' }`), a payload object,
675
- * `false` to cancel the drag, or `null`/`undefined` to pass through.
676
- */
677
- readonly source: DragCopySource;
678
- /**
679
- * `effectAllowed` advertised on the drag. Default `'copy'`.
680
- * Setting `'move'` signals to drop targets that the source will be removed.
681
- */
682
- readonly effectAllowed?: DragEffectAllowed;
683
- /**
684
- * Called each time a drag starts or ends, with the latest outcome and status.
685
- * Stable across re-renders when written as a class method or via `useRef`.
686
- */
687
- readonly onDrag?: (state: DragCopyState) => void;
688
- /** Called when preparing the drag payload fails. */
689
- readonly onError?: (error: CopyError) => void;
690
- }
691
- /**
692
- * Populates a `dragstart` event's `DataTransfer` with the given payload.
693
- * Use this from a raw `dragstart` handler or a React `onDragStart` prop.
694
- * Returns the outcome so you can inspect what happened.
695
- */
696
- export declare function applyDragCopy(event: DragStartEventLike, options: DragCopyOptions): DragCopyOutcome;
697
- export interface RegisterDragCopyResult {
698
- /** Unsubscribes all listeners. Idempotent. */
699
- readonly unsubscribe: () => void;
700
- }
701
- /**
702
- * Attaches `dragstart` and `dragend` listeners to `element`, calling
703
- * `applyDragCopy` on every drag start. Returns an object with an
704
- * `unsubscribe` function.
705
- *
706
- * Pass an options getter so the latest options are always used without
707
- * re-registering — safe to pass an inline object from a React render.
708
- *
709
- * ```ts
710
- * const { unsubscribe } = registerDragCopy(el, () => ({
711
- * source: () => `${title}\n${url}`,
712
- * }));
713
- * ```
714
- */
715
- export declare function registerDragCopy(element: HTMLElement, options: DragCopyOptions | (() => DragCopyOptions)): RegisterDragCopyResult;
716
- //#endregion
717
- //#region src/core/paste-adapter.d.ts
718
- /** Minimal structural view of `navigator.clipboard` for reading. */
719
- interface PasteClipboardLike {
720
- read?(): Promise<readonly ClipboardItemLike[]>;
721
- readText?(): Promise<string>;
722
- }
723
- interface PasteEnvironment {
724
- readonly isSecureContext?: boolean;
725
- readonly navigator?: {
726
- readonly clipboard?: PasteClipboardLike | undefined;
727
- } | undefined;
728
- }
729
- /**
730
- * Reads the system clipboard. Implement it for Electron, a native bridge or tests.
731
- *
732
- * Contract: call the platform API synchronously (before any `await`) so the
733
- * browser still sees the user gesture, and reject with a `CopyFailure`.
734
- * `context.signal` aborts when the read is superseded, reset, or its host
735
- * unmounts; honour it to stop decoding early.
736
- */
737
- interface PasteAdapter {
738
- read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteReadResult>;
739
- }
740
- interface BrowserPasteAdapterOptions {
741
- /** Defaults to `window`, read lazily at paste time (SSR-safe). */
742
- readonly getEnvironment?: () => PasteEnvironment | undefined;
743
- }
744
- /** The default paste adapter: async Clipboard API with feature detection and honest errors. */
745
- export declare function createBrowserPasteAdapter(options?: BrowserPasteAdapterOptions): PasteAdapter;
746
- //#endregion
747
- //#region src/core/paste-machine.d.ts
748
- export interface PasteIdleState {
749
- readonly status: 'idle';
750
- }
751
- export interface PasteReadingState {
752
- readonly status: 'reading';
753
- }
754
- export interface PasteReadState {
755
- readonly status: 'read';
756
- readonly result: PasteResult;
757
- /** Epoch ms when the read resolved. */
758
- readonly at: number;
759
- }
760
- export interface PasteErrorState {
761
- readonly status: 'error';
762
- readonly error: CopyError;
763
- /** Where the failed read came from. Only `'clipboard'` reads can be retried. */
764
- readonly source: PasteSource;
765
- /** `retry()` calls made since the last fresh `paste()`. */
766
- readonly retryCount: number;
767
- }
768
- export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
769
- export type PasteStatus = PasteState['status'];
770
- /**
771
- * `cancelled`: the read was superseded, reset, or its host unmounted before it
772
- * finished, so its work was aborted. Nothing to report to the user.
773
- */
774
- export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
775
- /**
776
- * Why an in-flight read was cancelled: `reset` (`reset()` was called),
777
- * `disconnect` (its host disconnected, e.g. the React component unmounted) or
778
- * `superseded` (a paste or drop event arrived while a read was pending).
779
- */
780
- export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
781
- /** What `paste()` / `pasteEvent()` / `dropEvent()` / `retry()` resolve to. They never reject. */
782
- export type PasteOutcome = {
783
- readonly status: 'read';
784
- readonly result: PasteResult;
785
- } | {
786
- readonly status: 'error';
787
- readonly error: CopyError;
788
- } | {
789
- readonly status: 'ignored';
790
- readonly reason: PasteIgnoredReason;
791
- };
792
- /** Structural view of a DOM / React `paste` event. */
793
- export interface PasteEventLike {
794
- readonly clipboardData: DataTransferLike | null | undefined;
795
- preventDefault(): void;
796
- }
797
- /** Structural view of a DOM / React `drop` event. */
798
- export interface PasteDropEventLike {
799
- readonly dataTransfer: DataTransferLike | null | undefined;
800
- preventDefault(): void;
801
- }
802
- export interface PasteMachineOptions extends PasteReadOptions {
803
- /** Defaults to the browser Clipboard API adapter. */
804
- readonly adapter?: PasteAdapter;
805
- /** Return from `read` to `idle` after this many ms. `false` / `Infinity` / omitted = keep the result. */
806
- readonly resetAfterMs?: number | false;
807
- /**
808
- * Paste events: call `event.preventDefault()` when the event carried accepted
809
- * content, so the browser doesn't also insert it. Drop events: always call it,
810
- * so the browser doesn't open the dropped file. Default `true`.
811
- */
812
- readonly preventDefault?: boolean;
813
- /**
814
- * Max `retry()` calls after a failed clipboard read. Default 3. `0`
815
- * disables retry; `Infinity` allows unlimited retries.
816
- */
817
- readonly maxRetries?: number;
818
- readonly onPaste?: (result: PasteResult) => void;
819
- readonly onError?: (error: CopyError) => void;
820
- /**
821
- * `reset()` moved the machine back to `idle` from any other state. Not
822
- * called for the automatic return after `resetAfterMs`, or when already `idle`.
823
- */
824
- readonly onReset?: () => void;
825
- /**
826
- * A read in flight was cancelled before it settled: its `signal` aborted
827
- * and its result will not reach state or `onPaste` / `onError`. Fires
828
- * before `onReset` when `reset()` cancels a read.
829
- */
830
- readonly onCancel?: (reason: PasteCancelReason) => void;
831
- /** Clock injection for tests and deterministic environments. */
832
- readonly now?: () => number;
833
- }
834
- /** Options object, or a getter so hosts (like React) can supply the latest options. */
835
- export type PasteMachineOptionsSource = PasteMachineOptions | (() => PasteMachineOptions);
836
- export interface PasteMachine {
837
- readonly getSnapshot: () => PasteState;
838
- readonly subscribe: (listener: () => void) => () => void;
839
- /**
840
- * Reads the system clipboard via the adapter. Call it from a user gesture
841
- * (click, keypress). May show a permission prompt. Ignored while `reading`.
842
- */
843
- readonly paste: () => Promise<PasteOutcome>;
844
- /**
845
- * Handles a `paste` event (Ctrl/⌘+V). No permission prompt: the data is
846
- * already in the event. Supersedes any read in flight. Events without
847
- * accepted content are ignored and left untouched for the browser.
848
- */
849
- readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
850
- /**
851
- * Handles a drag-and-drop `drop` event exactly like a paste event: same
852
- * `accept`, limits and image checks, `result.source === 'drop'`. Always calls
853
- * `event.preventDefault()` (unless `preventDefault: false`), so a rejected
854
- * file is not opened by the browser in place of the page.
855
- */
856
- readonly dropEvent: (event: PasteDropEventLike) => Promise<PasteOutcome>;
857
- /**
858
- * Re-reads the clipboard after a retryable failure (e.g. permission denied,
859
- * page not focused), up to `maxRetries`. Call it from a user gesture.
860
- * Paste-event failures can't be retried: their data is gone after dispatch.
861
- */
862
- readonly retry: () => Promise<PasteOutcome>;
863
- /** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
864
- readonly reset: () => void;
865
- /**
866
- * Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
867
- * cleanup clears timers, drops in-flight results, aborts in-flight work and
868
- * unsticks `reading`.
869
- * Safe to call repeatedly (React StrictMode).
870
- */
871
- readonly connect: () => () => void;
872
- }
873
- export declare const PASTE_IDLE_STATE: PasteIdleState;
874
- /** Pure helper: can `retry()` do anything from this state? */
875
- export declare function canRetryPasteState(state: PasteState, maxRetries?: number): boolean;
876
- /** Framework-agnostic paste state machine. */
877
- export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
878
- //#endregion
879
10
  //#region src/react/useCopy.d.ts
880
11
  type UseCopyOptions = CopyMachineOptions;
881
12
  interface UseCopyResult {
@@ -1334,107 +465,6 @@ interface UseDragCopyResult<T extends HTMLElement = HTMLElement> {
1334
465
  */
1335
466
  export declare function useDragCopy<T extends HTMLElement = HTMLElement>(options: UseDragCopyOptions): UseDragCopyResult<T>;
1336
467
  //#endregion
1337
- //#region src/link/url.d.ts
1338
- interface CleanLinkOptions {
1339
- /**
1340
- * Parameters to remove: exact names, names ending in `_` (a prefix, like
1341
- * `utm_`), or regular expressions tested against the name. Default {@link TRACKING_PARAMETERS}.
1342
- */
1343
- readonly params?: readonly (string | RegExp)[];
1344
- /** Parameters never removed, even when `params` matches them. */
1345
- readonly keep?: readonly string[];
1346
- }
1347
- interface LinkUrlOptions {
1348
- /** Resolves relative links. Default: the page's address in a browser; required elsewhere for relative links. */
1349
- readonly base?: string | URL;
1350
- /** Allowed schemes, with the colon. Default {@link DEFAULT_LINK_PROTOCOLS}. */
1351
- readonly protocols?: readonly string[];
1352
- /** Remove tracking parameters: `true` for {@link TRACKING_PARAMETERS}, or your own list. Default `false`. */
1353
- readonly clean?: boolean | CleanLinkOptions;
1354
- }
1355
- //#endregion
1356
- //#region src/share/share.d.ts
1357
- /** What to share: a link, a message, files, or any mix of them. */
1358
- interface ShareContent {
1359
- /** Validated like every link in this package: allowed schemes only, credentials removed. */
1360
- readonly url?: string | URL;
1361
- readonly title?: string;
1362
- /** A message to share alongside (or instead of) the link. */
1363
- readonly text?: string;
1364
- /** Files for the share sheet, where the browser can share them (`navigator.canShare({ files })`). Never copied. */
1365
- readonly files?: readonly File[];
1366
- }
1367
- /** The content after validation: what the share sheet or the clipboard receives. */
1368
- interface ResolvedShare {
1369
- readonly url: string | null;
1370
- /** Cleaned of hidden characters; `null` when there is none. */
1371
- readonly title: string | null;
1372
- readonly text: string | null;
1373
- readonly files: readonly File[];
1374
- }
1375
- /**
1376
- * How to share:
1377
- * - `auto` (default): the share sheet on phones and tablets, where people expect it; copy elsewhere.
1378
- * - `native`: the share sheet wherever the browser has one (also desktop Safari, Edge and Chrome on Windows and macOS).
1379
- * - `copy`: always copy.
1380
- */
1381
- type ShareMode = 'auto' | 'native' | 'copy';
1382
- type ShareMethod = 'native' | 'copy';
1383
- /** Structural view of what sharing needs from the browser; `window` by default. */
1384
- interface ShareEnvironment {
1385
- readonly navigator?: {
1386
- readonly share?: (data: ShareData) => Promise<void>;
1387
- readonly canShare?: (data: ShareData) => boolean;
1388
- };
1389
- readonly matchMedia?: (query: string) => {
1390
- readonly matches: boolean;
1391
- };
1392
- }
1393
- interface ShareOptions extends LinkUrlOptions {
1394
- /** Default `"auto"`. */
1395
- readonly mode?: ShareMode;
1396
- /** When the share sheet fails for a reason other than the user closing it, copy instead. Default `true`. */
1397
- readonly fallback?: boolean;
1398
- /**
1399
- * What to copy. Default: a titled link (`linkPayload`) when there is a URL,
1400
- * otherwise the text. Return a string or any copy payload.
1401
- */
1402
- readonly copy?: (content: ResolvedShare) => CopyInput;
1403
- /** Default: the browser Clipboard API, as `useCopy` uses. */
1404
- readonly adapter?: ClipboardAdapter;
1405
- /** Default: `window`. For tests, webviews and other hosts. */
1406
- readonly environment?: ShareEnvironment;
1407
- /** Aborting it stops a copy in progress; the share sheet itself can only be closed by the user. */
1408
- readonly signal?: AbortSignal;
1409
- }
1410
- /**
1411
- * Why the content was copied rather than shared: `preferred` (the mode chose
1412
- * copy, as on desktop in `auto`), `unsupported` (no share sheet, or it can't
1413
- * take this content) or `fallback` (the share sheet failed).
1414
- */
1415
- type CopyReason = 'preferred' | 'unsupported' | 'fallback';
1416
- /** What `shareOrCopy` resolves to. It never rejects. */
1417
- type ShareOutcome = {
1418
- readonly status: 'shared';
1419
- readonly method: 'native';
1420
- readonly content: ResolvedShare;
1421
- } | {
1422
- readonly status: 'copied';
1423
- readonly method: 'copy';
1424
- readonly reason: CopyReason;
1425
- readonly payload: CopyPayload;
1426
- readonly content: ResolvedShare;
1427
- } |
1428
- /** The user closed the share sheet. Nothing to report. */
1429
- {
1430
- readonly status: 'cancelled';
1431
- readonly method: 'native';
1432
- } | {
1433
- readonly status: 'error';
1434
- readonly method: ShareMethod;
1435
- readonly error: CopyError;
1436
- };
1437
- //#endregion
1438
468
  //#region src/react/useShare.d.ts
1439
469
  /** `sharing` lasts while the share sheet is open or the copy is being written. */
1440
470
  type ShareStatus = 'idle' | 'sharing' | 'shared' | 'copied' | 'error';
@@ -1478,5 +508,5 @@ interface UseShareResult {
1478
508
  */
1479
509
  export declare function useShare(options?: UseShareOptions): UseShareResult;
1480
510
  //#endregion
1481
- export type { BrowserPasteAdapterOptions, ClipboardItemLike, CopyFieldContextValue, CopyFieldLabelProps, CopyFieldMessages, CopyFieldRootProps, CopyFieldTriggerProps, CopyFieldTriggerRenderProps, CopyFieldValueProps, CopyGroupProps, CopyReason, DataTransferItemLike, LiveRegionProps, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteDropTargetProps, PasteEnvironment, PasteFieldContextValue, PasteFieldLabelProps, PasteFieldMessages, PasteFieldPreviewProps, PasteFieldPreviewRenderProps, PasteFieldRootProps, PasteFieldStatusProps, PasteFieldTriggerProps, PasteFieldTriggerRenderProps, PasteFieldZoneProps, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, PasteTargetProps, ResolvedPasteReadOptions, ResolvedShare, RevealReason, RevealTargetProps, ShareContent, ShareEnvironment, ShareMethod, ShareMode, ShareOptions, ShareOutcome, ShareStatus, UseCopyInterceptorOptions, UseCopyInterceptorResult, UseCopyOptions, UseCopyResult, UseDisplayStatusOptions, UseDragCopyOptions, UseDragCopyResult, UsePasteDisplayStatusOptions, UsePasteOptions, UsePasteResult, UseRevealOnInteractionOptions, UseRevealOnInteractionResult, UseShareOptions, UseShareOutcome, UseShareResult };
511
+ export { BlobSource, BrowserClipboardAdapterOptions, type BrowserPasteAdapterOptions, ClipboardAdapter, ClipboardDataLike, ClipboardEnvironment, ClipboardItemConstructorLike, ClipboardItemData, type ClipboardItemLike, ClipboardLike, ClipboardOperation, CopiedState, CopyCancelReason, CopyCoordinator, CopyCoordinatorMember, CopyError, CopyErrorType, CopyEventLike, CopyFailure, type CopyFieldContextValue, type CopyFieldLabelProps, type CopyFieldMessages, type CopyFieldRootProps, type CopyFieldTriggerProps, type CopyFieldTriggerRenderProps, type CopyFieldValueProps, type CopyGroupProps, CopyIgnoredReason, CopyInput, CopyInterceptDecision, CopyInterceptFailureMode, CopyInterceptOptions, CopyInterceptOutcome, CopyInterceptPassReason, CopyInterceptTransform, CopyInterceptorOptions, CopyMachine, CopyMachineOptions, CopyMachineOptionsSource, CopyOutcome, CopyPayload, CopyPayloadKind, type CopyReason, CopySelection, CopySource, CopyState, CopyStatus, CopyingState, DEFAULT_INTERCEPTED_EVENTS, DEFAULT_MAX_RETRIES, DEFAULT_PASTE_ACCEPT, DEFAULT_PASTE_MAX_BYTES, DEFAULT_PASTE_MAX_ITEMS, DEFAULT_RESET_AFTER_MS, type DataTransferItemLike, DataTransferLike, DragCopyDecision, DragCopyItem, DragCopyOptions, DragCopyOutcome, DragCopyPassReason, DragCopyPayload, DragCopySource, DragCopyState, DragCopyStatus, DragEffectAllowed, DragMultiPayload, DragStartEventLike, ErrorState, HtmlPayload, IDLE_STATE, IMAGE_MIME_TYPE, IdleState, ImagePayload, InterceptedCopyKind, JsonPayload, type LiveRegionProps, MultiPayload, MultiPayloadItem, type OperationContext, PASTE_IDLE_STATE, type PasteAccept, type PasteAcceptShorthand, type PasteAdapter, PasteCancelReason, type PasteClipboardLike, PasteDropEventLike, type PasteDropTargetProps, type PasteEnvironment, PasteErrorState, PasteEventLike, type PasteFieldContextValue, type PasteFieldLabelProps, type PasteFieldMessages, type PasteFieldPreviewProps, type PasteFieldPreviewRenderProps, type PasteFieldRootProps, type PasteFieldStatusProps, type PasteFieldTriggerProps, type PasteFieldTriggerRenderProps, type PasteFieldZoneProps, PasteIdleState, PasteIgnoredReason, type PasteItem, type PasteLimits, PasteMachine, PasteMachineOptions, PasteMachineOptionsSource, PasteOutcome, type PasteReadOptions, type PasteReadResult, PasteReadState, PasteReadingState, type PasteResult, type PasteSource, PasteState, PasteStatus, type PasteTargetProps, RasterImageMimeType, RegisterDragCopyResult, type ResolvedPasteReadOptions, type ResolvedShare, type RevealReason, type RevealTargetProps, SVG_MIME_TYPE, type ShareContent, type ShareEnvironment, type ShareMethod, type ShareMode, type ShareOptions, type ShareOutcome, type ShareStatus, SyncCopyPayload, SyncMultiPayload, TextPayload, type UseCopyInterceptorOptions, type UseCopyInterceptorResult, type UseCopyOptions, type UseCopyResult, type UseDisplayStatusOptions, type UseDragCopyOptions, type UseDragCopyResult, type UsePasteDisplayStatusOptions, type UsePasteOptions, type UsePasteResult, type UseRevealOnInteractionOptions, type UseRevealOnInteractionResult, type UseShareOptions, type UseShareOutcome, type UseShareResult, WEB_CUSTOM_FORMAT_PREFIX, applyDragCopy, canAcceptDrag, canRetryPasteState, canRetryState, copyFailure, createBrowserClipboardAdapter, createBrowserPasteAdapter, createCopyCoordinator, createCopyError, createCopyMachine, createPasteMachine, describeCopyError, describePasteError, interceptCopyEvent, isBlob, isCopyFailure, isRetryableError, isTextualMimeType, isWebCustomFormat, matchesMimePattern, normalizeClipboardType, normalizeMimeType, normalizePayload, readCopySelection, registerCopyInterceptor, registerDragCopy, resolveMaxRetries, resolvePasteReadOptions, serializeJson, sniffImageBytes, sniffImageType, toCopyError, validatePayload };
1482
512
  //# sourceMappingURL=index.d.ts.map