react-smart-copy 1.17.1 → 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 +22 -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 -109
  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 +4 -93
  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 -91
  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 +5 -73
  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/share.d.cts CHANGED
@@ -1,248 +1,3 @@
1
- //#region src/core/machine-shared.d.ts
2
- /**
3
- * Passed to adapters and lazy sources as their last argument. `signal` aborts
4
- * when the operation is superseded, `reset()`, or its host unmounts, so
5
- * expensive work (rasterising, decoding) can stop early.
6
- */
7
- interface OperationContext {
8
- readonly signal: AbortSignal;
9
- }
10
- //#endregion
11
- //#region src/core/errors.d.ts
12
- /**
13
- * Every way a clipboard operation can fail, as a closed union.
14
- *
15
- * `CopyError.message` is developer-facing (logs, telemetry). For user-facing
16
- * text use {@link describeCopyError} / {@link describePasteError}, or map
17
- * `type` through your own i18n layer.
18
- */
19
- type CopyErrorType =
20
- /** No Clipboard API (old browser, server, locked-down webview). Not retryable. */
21
- 'unsupported' |
22
- /** Page is not served over HTTPS/localhost. Not retryable. */
23
- 'insecure-context' |
24
- /** Browser or user blocked the operation. Also what Safari reports for a missing user gesture. */
25
- 'permission-denied' |
26
- /** The document lost focus mid-operation (Chromium). Retrying after refocus usually works. */
27
- 'not-focused' |
28
- /** Empty or malformed payload, or a lazy source that threw. Caught before touching the clipboard. */
29
- 'invalid-payload' |
30
- /** The browser cannot handle this MIME type (e.g. non-PNG image, HTML without ClipboardItem). */
31
- 'unsupported-format' |
32
- /** A lazy image source (or capture) threw, rejected or did not produce a Blob. */
33
- 'blob-generation-failed' |
34
- /** `retry()` was called after `maxRetries` was reached. Terminal. */
35
- 'max-retries-exceeded' |
36
- /** Paste: the clipboard held nothing matching `accept`. */
37
- 'no-content' |
38
- /** Content exceeded a configured safety limit (bytes, items or pixels). Not retryable. */
39
- 'too-large' |
40
- /** An operation did not settle within its deadline. Retryable. */
41
- 'timeout' |
42
- /** The caller aborted the operation through an `AbortSignal`. Not retryable. */
43
- 'aborted' |
44
- /** Anything the platform threw that we could not classify. */
45
- 'unknown';
46
- interface CopyError {
47
- readonly type: CopyErrorType;
48
- readonly message: string;
49
- readonly cause?: unknown;
50
- }
51
- //#endregion
52
- //#region src/core/payload.d.ts
53
- /**
54
- * An image as a Blob, a promise of one, or a function producing one.
55
- * Prefer the function form: it is invoked synchronously inside the user
56
- * gesture, which Safari requires for async image generation. The browser
57
- * adapter always passes an `OperationContext`: stop work once
58
- * `context.signal` aborts (reset, superseded, unmount). Optional in the type
59
- * so adapters that call sources themselves keep compiling.
60
- */
61
- type BlobSource = Blob | PromiseLike<Blob> | ((context?: OperationContext) => Blob | PromiseLike<Blob>);
62
- interface TextPayload {
63
- readonly kind: 'text';
64
- readonly value: string;
65
- }
66
- interface HtmlPayload {
67
- readonly kind: 'html';
68
- readonly html: string;
69
- /** Required plain-text fallback for targets that don't understand HTML. */
70
- readonly text: string;
71
- }
72
- interface ImagePayload {
73
- readonly kind: 'image';
74
- readonly blob: BlobSource;
75
- }
76
- interface JsonPayload {
77
- readonly kind: 'json';
78
- readonly value: unknown;
79
- /** `true` = 2-space indent, a number = that indent, falsy = compact. */
80
- readonly pretty?: boolean | number;
81
- }
82
- interface MultiPayloadItem {
83
- /**
84
- * The MIME type, or a web custom format (`web application/vnd.acme+json`).
85
- * Web custom formats are only written by the async Clipboard API; copy and drag
86
- * events skip them.
87
- */
88
- readonly mimeType: string;
89
- readonly data: string | Blob;
90
- /**
91
- * Skip this item, instead of failing the copy, when the browser cannot write its type.
92
- * An optional item is only written when `ClipboardItem.supports()` confirms the type.
93
- * At least one item must be written.
94
- */
95
- readonly optional?: boolean;
96
- }
97
- interface MultiPayload {
98
- readonly kind: 'multi';
99
- readonly items: readonly MultiPayloadItem[];
100
- }
101
- type CopyPayload = TextPayload | HtmlPayload | ImagePayload | JsonPayload | MultiPayload;
102
- /** A payload, or a bare string as shorthand for `{ kind: 'text' }`. */
103
- type CopyInput = string | CopyPayload;
104
- //#endregion
105
- //#region src/core/clipboard-adapter.d.ts
106
- /**
107
- * The only thing the state machine needs. Implement it to target Electron,
108
- * a native bridge, a test double, or anything else.
109
- *
110
- * Contract: start the platform write synchronously (before any `await`) so the
111
- * browser still sees the user gesture, and reject with a `CopyFailure` when you
112
- * can classify the error. `context.signal` aborts when the copy is reset or its
113
- * host unmounts; honour it to stop expensive work early.
114
- */
115
- interface ClipboardAdapter {
116
- write(payload: CopyPayload, context?: OperationContext): Promise<void>;
117
- }
118
- //#endregion
119
- //#region src/link/url.d.ts
120
- interface CleanLinkOptions {
121
- /**
122
- * Parameters to remove: exact names, names ending in `_` (a prefix, like
123
- * `utm_`), or regular expressions tested against the name. Default {@link TRACKING_PARAMETERS}.
124
- */
125
- readonly params?: readonly (string | RegExp)[];
126
- /** Parameters never removed, even when `params` matches them. */
127
- readonly keep?: readonly string[];
128
- }
129
- interface LinkUrlOptions {
130
- /** Resolves relative links. Default: the page's address in a browser; required elsewhere for relative links. */
131
- readonly base?: string | URL;
132
- /** Allowed schemes, with the colon. Default {@link DEFAULT_LINK_PROTOCOLS}. */
133
- readonly protocols?: readonly string[];
134
- /** Remove tracking parameters: `true` for {@link TRACKING_PARAMETERS}, or your own list. Default `false`. */
135
- readonly clean?: boolean | CleanLinkOptions;
136
- }
137
- //#endregion
138
- //#region src/share/share.d.ts
139
- /** What to share: a link, a message, files, or any mix of them. */
140
- interface ShareContent {
141
- /** Validated like every link in this package: allowed schemes only, credentials removed. */
142
- readonly url?: string | URL;
143
- readonly title?: string;
144
- /** A message to share alongside (or instead of) the link. */
145
- readonly text?: string;
146
- /** Files for the share sheet, where the browser can share them (`navigator.canShare({ files })`). Never copied. */
147
- readonly files?: readonly File[];
148
- }
149
- /** The content after validation: what the share sheet or the clipboard receives. */
150
- interface ResolvedShare {
151
- readonly url: string | null;
152
- /** Cleaned of hidden characters; `null` when there is none. */
153
- readonly title: string | null;
154
- readonly text: string | null;
155
- readonly files: readonly File[];
156
- }
157
- /**
158
- * How to share:
159
- * - `auto` (default): the share sheet on phones and tablets, where people expect it; copy elsewhere.
160
- * - `native`: the share sheet wherever the browser has one (also desktop Safari, Edge and Chrome on Windows and macOS).
161
- * - `copy`: always copy.
162
- */
163
- type ShareMode = 'auto' | 'native' | 'copy';
164
- type ShareMethod = 'native' | 'copy';
165
- /** Structural view of what sharing needs from the browser; `window` by default. */
166
- interface ShareEnvironment {
167
- readonly navigator?: {
168
- readonly share?: (data: ShareData) => Promise<void>;
169
- readonly canShare?: (data: ShareData) => boolean;
170
- };
171
- readonly matchMedia?: (query: string) => {
172
- readonly matches: boolean;
173
- };
174
- }
175
- interface ShareOptions extends LinkUrlOptions {
176
- /** Default `"auto"`. */
177
- readonly mode?: ShareMode;
178
- /** When the share sheet fails for a reason other than the user closing it, copy instead. Default `true`. */
179
- readonly fallback?: boolean;
180
- /**
181
- * What to copy. Default: a titled link (`linkPayload`) when there is a URL,
182
- * otherwise the text. Return a string or any copy payload.
183
- */
184
- readonly copy?: (content: ResolvedShare) => CopyInput;
185
- /** Default: the browser Clipboard API, as `useCopy` uses. */
186
- readonly adapter?: ClipboardAdapter;
187
- /** Default: `window`. For tests, webviews and other hosts. */
188
- readonly environment?: ShareEnvironment;
189
- /** Aborting it stops a copy in progress; the share sheet itself can only be closed by the user. */
190
- readonly signal?: AbortSignal;
191
- }
192
- /**
193
- * Why the content was copied rather than shared: `preferred` (the mode chose
194
- * copy, as on desktop in `auto`), `unsupported` (no share sheet, or it can't
195
- * take this content) or `fallback` (the share sheet failed).
196
- */
197
- type CopyReason = 'preferred' | 'unsupported' | 'fallback';
198
- /** What `shareOrCopy` resolves to. It never rejects. */
199
- type ShareOutcome = {
200
- readonly status: 'shared';
201
- readonly method: 'native';
202
- readonly content: ResolvedShare;
203
- } | {
204
- readonly status: 'copied';
205
- readonly method: 'copy';
206
- readonly reason: CopyReason;
207
- readonly payload: CopyPayload;
208
- readonly content: ResolvedShare;
209
- } |
210
- /** The user closed the share sheet. Nothing to report. */
211
- {
212
- readonly status: 'cancelled';
213
- readonly method: 'native';
214
- } | {
215
- readonly status: 'error';
216
- readonly method: ShareMethod;
217
- readonly error: CopyError;
218
- };
219
- /**
220
- * How {@link shareOrCopy} would share right now: `"native"` (the share sheet) or
221
- * `"copy"`. Use it to label the button ("Share…" or "Copy link"). Pass the
222
- * content when it has files, since not every share sheet takes them.
223
- */
224
- export declare function shareMethod(options?: Pick<ShareOptions, 'mode' | 'environment'>, content?: ShareContent): ShareMethod;
225
- /**
226
- * Shares through the device's share sheet where people expect one, and copies a
227
- * titled link everywhere else. Call it directly in a click handler: the share
228
- * sheet needs the user's gesture.
229
- *
230
- * It never rejects. It resolves to `shared`, `copied` (with why), `cancelled`
231
- * (the user closed the share sheet: nothing to report) or `error` with a typed
232
- * {@link CopyError}.
233
- *
234
- * @example
235
- * button.addEventListener('click', async () => {
236
- * const outcome = await shareOrCopy({ url: location.href, title: document.title });
237
- * if (outcome.status === 'copied') toast('Link copied');
238
- * });
239
- */
240
- export declare function shareOrCopy(content: ShareContent, options?: ShareOptions): Promise<ShareOutcome>;
241
- /**
242
- * Default English, user-facing sentence for a failed share: a share sheet
243
- * failure is described as sharing, a failed copy as copying. Replace for i18n.
244
- */
245
- export declare function describeShareError(error: CopyError, method: ShareMethod): string;
246
- //#endregion
247
- export type { CopyReason, ResolvedShare, ShareContent, ShareEnvironment, ShareMethod, ShareMode, ShareOptions, ShareOutcome };
248
- //# sourceMappingURL=share.d.cts.map
1
+
2
+ import { a as ShareMethod, c as ShareOutcome, d as shareOrCopy, i as ShareEnvironment, l as describeShareError, n as ResolvedShare, o as ShareMode, r as ShareContent, s as ShareOptions, t as CopyReason, u as shareMethod } from "./chunks/share-C0esXvRK.cjs";
3
+ export { type CopyReason, type ResolvedShare, type ShareContent, type ShareEnvironment, type ShareMethod, type ShareMode, type ShareOptions, type ShareOutcome, describeShareError, shareMethod, shareOrCopy };
package/dist/share.d.ts CHANGED
@@ -1,248 +1,3 @@
1
- //#region src/core/machine-shared.d.ts
2
- /**
3
- * Passed to adapters and lazy sources as their last argument. `signal` aborts
4
- * when the operation is superseded, `reset()`, or its host unmounts, so
5
- * expensive work (rasterising, decoding) can stop early.
6
- */
7
- interface OperationContext {
8
- readonly signal: AbortSignal;
9
- }
10
- //#endregion
11
- //#region src/core/errors.d.ts
12
- /**
13
- * Every way a clipboard operation can fail, as a closed union.
14
- *
15
- * `CopyError.message` is developer-facing (logs, telemetry). For user-facing
16
- * text use {@link describeCopyError} / {@link describePasteError}, or map
17
- * `type` through your own i18n layer.
18
- */
19
- type CopyErrorType =
20
- /** No Clipboard API (old browser, server, locked-down webview). Not retryable. */
21
- 'unsupported' |
22
- /** Page is not served over HTTPS/localhost. Not retryable. */
23
- 'insecure-context' |
24
- /** Browser or user blocked the operation. Also what Safari reports for a missing user gesture. */
25
- 'permission-denied' |
26
- /** The document lost focus mid-operation (Chromium). Retrying after refocus usually works. */
27
- 'not-focused' |
28
- /** Empty or malformed payload, or a lazy source that threw. Caught before touching the clipboard. */
29
- 'invalid-payload' |
30
- /** The browser cannot handle this MIME type (e.g. non-PNG image, HTML without ClipboardItem). */
31
- 'unsupported-format' |
32
- /** A lazy image source (or capture) threw, rejected or did not produce a Blob. */
33
- 'blob-generation-failed' |
34
- /** `retry()` was called after `maxRetries` was reached. Terminal. */
35
- 'max-retries-exceeded' |
36
- /** Paste: the clipboard held nothing matching `accept`. */
37
- 'no-content' |
38
- /** Content exceeded a configured safety limit (bytes, items or pixels). Not retryable. */
39
- 'too-large' |
40
- /** An operation did not settle within its deadline. Retryable. */
41
- 'timeout' |
42
- /** The caller aborted the operation through an `AbortSignal`. Not retryable. */
43
- 'aborted' |
44
- /** Anything the platform threw that we could not classify. */
45
- 'unknown';
46
- interface CopyError {
47
- readonly type: CopyErrorType;
48
- readonly message: string;
49
- readonly cause?: unknown;
50
- }
51
- //#endregion
52
- //#region src/core/payload.d.ts
53
- /**
54
- * An image as a Blob, a promise of one, or a function producing one.
55
- * Prefer the function form: it is invoked synchronously inside the user
56
- * gesture, which Safari requires for async image generation. The browser
57
- * adapter always passes an `OperationContext`: stop work once
58
- * `context.signal` aborts (reset, superseded, unmount). Optional in the type
59
- * so adapters that call sources themselves keep compiling.
60
- */
61
- type BlobSource = Blob | PromiseLike<Blob> | ((context?: OperationContext) => Blob | PromiseLike<Blob>);
62
- interface TextPayload {
63
- readonly kind: 'text';
64
- readonly value: string;
65
- }
66
- interface HtmlPayload {
67
- readonly kind: 'html';
68
- readonly html: string;
69
- /** Required plain-text fallback for targets that don't understand HTML. */
70
- readonly text: string;
71
- }
72
- interface ImagePayload {
73
- readonly kind: 'image';
74
- readonly blob: BlobSource;
75
- }
76
- interface JsonPayload {
77
- readonly kind: 'json';
78
- readonly value: unknown;
79
- /** `true` = 2-space indent, a number = that indent, falsy = compact. */
80
- readonly pretty?: boolean | number;
81
- }
82
- interface MultiPayloadItem {
83
- /**
84
- * The MIME type, or a web custom format (`web application/vnd.acme+json`).
85
- * Web custom formats are only written by the async Clipboard API; copy and drag
86
- * events skip them.
87
- */
88
- readonly mimeType: string;
89
- readonly data: string | Blob;
90
- /**
91
- * Skip this item, instead of failing the copy, when the browser cannot write its type.
92
- * An optional item is only written when `ClipboardItem.supports()` confirms the type.
93
- * At least one item must be written.
94
- */
95
- readonly optional?: boolean;
96
- }
97
- interface MultiPayload {
98
- readonly kind: 'multi';
99
- readonly items: readonly MultiPayloadItem[];
100
- }
101
- type CopyPayload = TextPayload | HtmlPayload | ImagePayload | JsonPayload | MultiPayload;
102
- /** A payload, or a bare string as shorthand for `{ kind: 'text' }`. */
103
- type CopyInput = string | CopyPayload;
104
- //#endregion
105
- //#region src/core/clipboard-adapter.d.ts
106
- /**
107
- * The only thing the state machine needs. Implement it to target Electron,
108
- * a native bridge, a test double, or anything else.
109
- *
110
- * Contract: start the platform write synchronously (before any `await`) so the
111
- * browser still sees the user gesture, and reject with a `CopyFailure` when you
112
- * can classify the error. `context.signal` aborts when the copy is reset or its
113
- * host unmounts; honour it to stop expensive work early.
114
- */
115
- interface ClipboardAdapter {
116
- write(payload: CopyPayload, context?: OperationContext): Promise<void>;
117
- }
118
- //#endregion
119
- //#region src/link/url.d.ts
120
- interface CleanLinkOptions {
121
- /**
122
- * Parameters to remove: exact names, names ending in `_` (a prefix, like
123
- * `utm_`), or regular expressions tested against the name. Default {@link TRACKING_PARAMETERS}.
124
- */
125
- readonly params?: readonly (string | RegExp)[];
126
- /** Parameters never removed, even when `params` matches them. */
127
- readonly keep?: readonly string[];
128
- }
129
- interface LinkUrlOptions {
130
- /** Resolves relative links. Default: the page's address in a browser; required elsewhere for relative links. */
131
- readonly base?: string | URL;
132
- /** Allowed schemes, with the colon. Default {@link DEFAULT_LINK_PROTOCOLS}. */
133
- readonly protocols?: readonly string[];
134
- /** Remove tracking parameters: `true` for {@link TRACKING_PARAMETERS}, or your own list. Default `false`. */
135
- readonly clean?: boolean | CleanLinkOptions;
136
- }
137
- //#endregion
138
- //#region src/share/share.d.ts
139
- /** What to share: a link, a message, files, or any mix of them. */
140
- interface ShareContent {
141
- /** Validated like every link in this package: allowed schemes only, credentials removed. */
142
- readonly url?: string | URL;
143
- readonly title?: string;
144
- /** A message to share alongside (or instead of) the link. */
145
- readonly text?: string;
146
- /** Files for the share sheet, where the browser can share them (`navigator.canShare({ files })`). Never copied. */
147
- readonly files?: readonly File[];
148
- }
149
- /** The content after validation: what the share sheet or the clipboard receives. */
150
- interface ResolvedShare {
151
- readonly url: string | null;
152
- /** Cleaned of hidden characters; `null` when there is none. */
153
- readonly title: string | null;
154
- readonly text: string | null;
155
- readonly files: readonly File[];
156
- }
157
- /**
158
- * How to share:
159
- * - `auto` (default): the share sheet on phones and tablets, where people expect it; copy elsewhere.
160
- * - `native`: the share sheet wherever the browser has one (also desktop Safari, Edge and Chrome on Windows and macOS).
161
- * - `copy`: always copy.
162
- */
163
- type ShareMode = 'auto' | 'native' | 'copy';
164
- type ShareMethod = 'native' | 'copy';
165
- /** Structural view of what sharing needs from the browser; `window` by default. */
166
- interface ShareEnvironment {
167
- readonly navigator?: {
168
- readonly share?: (data: ShareData) => Promise<void>;
169
- readonly canShare?: (data: ShareData) => boolean;
170
- };
171
- readonly matchMedia?: (query: string) => {
172
- readonly matches: boolean;
173
- };
174
- }
175
- interface ShareOptions extends LinkUrlOptions {
176
- /** Default `"auto"`. */
177
- readonly mode?: ShareMode;
178
- /** When the share sheet fails for a reason other than the user closing it, copy instead. Default `true`. */
179
- readonly fallback?: boolean;
180
- /**
181
- * What to copy. Default: a titled link (`linkPayload`) when there is a URL,
182
- * otherwise the text. Return a string or any copy payload.
183
- */
184
- readonly copy?: (content: ResolvedShare) => CopyInput;
185
- /** Default: the browser Clipboard API, as `useCopy` uses. */
186
- readonly adapter?: ClipboardAdapter;
187
- /** Default: `window`. For tests, webviews and other hosts. */
188
- readonly environment?: ShareEnvironment;
189
- /** Aborting it stops a copy in progress; the share sheet itself can only be closed by the user. */
190
- readonly signal?: AbortSignal;
191
- }
192
- /**
193
- * Why the content was copied rather than shared: `preferred` (the mode chose
194
- * copy, as on desktop in `auto`), `unsupported` (no share sheet, or it can't
195
- * take this content) or `fallback` (the share sheet failed).
196
- */
197
- type CopyReason = 'preferred' | 'unsupported' | 'fallback';
198
- /** What `shareOrCopy` resolves to. It never rejects. */
199
- type ShareOutcome = {
200
- readonly status: 'shared';
201
- readonly method: 'native';
202
- readonly content: ResolvedShare;
203
- } | {
204
- readonly status: 'copied';
205
- readonly method: 'copy';
206
- readonly reason: CopyReason;
207
- readonly payload: CopyPayload;
208
- readonly content: ResolvedShare;
209
- } |
210
- /** The user closed the share sheet. Nothing to report. */
211
- {
212
- readonly status: 'cancelled';
213
- readonly method: 'native';
214
- } | {
215
- readonly status: 'error';
216
- readonly method: ShareMethod;
217
- readonly error: CopyError;
218
- };
219
- /**
220
- * How {@link shareOrCopy} would share right now: `"native"` (the share sheet) or
221
- * `"copy"`. Use it to label the button ("Share…" or "Copy link"). Pass the
222
- * content when it has files, since not every share sheet takes them.
223
- */
224
- export declare function shareMethod(options?: Pick<ShareOptions, 'mode' | 'environment'>, content?: ShareContent): ShareMethod;
225
- /**
226
- * Shares through the device's share sheet where people expect one, and copies a
227
- * titled link everywhere else. Call it directly in a click handler: the share
228
- * sheet needs the user's gesture.
229
- *
230
- * It never rejects. It resolves to `shared`, `copied` (with why), `cancelled`
231
- * (the user closed the share sheet: nothing to report) or `error` with a typed
232
- * {@link CopyError}.
233
- *
234
- * @example
235
- * button.addEventListener('click', async () => {
236
- * const outcome = await shareOrCopy({ url: location.href, title: document.title });
237
- * if (outcome.status === 'copied') toast('Link copied');
238
- * });
239
- */
240
- export declare function shareOrCopy(content: ShareContent, options?: ShareOptions): Promise<ShareOutcome>;
241
- /**
242
- * Default English, user-facing sentence for a failed share: a share sheet
243
- * failure is described as sharing, a failed copy as copying. Replace for i18n.
244
- */
245
- export declare function describeShareError(error: CopyError, method: ShareMethod): string;
246
- //#endregion
247
- export type { CopyReason, ResolvedShare, ShareContent, ShareEnvironment, ShareMethod, ShareMode, ShareOptions, ShareOutcome };
248
- //# sourceMappingURL=share.d.ts.map
1
+
2
+ import { a as ShareMethod, c as ShareOutcome, d as shareOrCopy, i as ShareEnvironment, l as describeShareError, n as ResolvedShare, o as ShareMode, r as ShareContent, s as ShareOptions, t as CopyReason, u as shareMethod } from "./chunks/share-e7FenIr2.js";
3
+ export { type CopyReason, type ResolvedShare, type ShareContent, type ShareEnvironment, type ShareMethod, type ShareMode, type ShareOptions, type ShareOutcome, describeShareError, shareMethod, shareOrCopy };