react-smart-copy 1.17.2 → 1.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +86 -5
- package/dist/capture.cjs +30 -153
- package/dist/capture.cjs.map +1 -1
- package/dist/capture.d.cts +2 -25
- package/dist/capture.d.ts +2 -25
- package/dist/capture.js +5 -128
- package/dist/capture.js.map +1 -1
- package/dist/chunks/clipboard-adapter-Cfz-rzw3.cjs +102 -0
- package/dist/chunks/clipboard-adapter-Cfz-rzw3.cjs.map +1 -0
- package/dist/chunks/clipboard-adapter-CtH4VELE.d.cts +43 -0
- package/dist/chunks/clipboard-adapter-DEXkXxwV.js +97 -0
- package/dist/chunks/clipboard-adapter-DEXkXxwV.js.map +1 -0
- package/dist/chunks/clipboard-adapter-Ds0irroN.d.ts +43 -0
- package/dist/chunks/contrast-C6CVklEI.cjs +842 -0
- package/dist/chunks/contrast-C6CVklEI.cjs.map +1 -0
- package/dist/chunks/contrast-DpK2JIVu.js +789 -0
- package/dist/chunks/contrast-DpK2JIVu.js.map +1 -0
- package/dist/chunks/copy-interceptor-C6NABy1l.d.ts +141 -0
- package/dist/chunks/copy-interceptor-CZWzGOkL.d.cts +141 -0
- package/dist/chunks/core-Cp2HSpaz.js +1035 -0
- package/dist/chunks/core-Cp2HSpaz.js.map +1 -0
- package/dist/chunks/core-DYf_Lhbe.cjs +1142 -0
- package/dist/chunks/core-DYf_Lhbe.cjs.map +1 -0
- package/dist/chunks/deadline-C29AlS_Q.js +46 -0
- package/dist/chunks/deadline-C29AlS_Q.js.map +1 -0
- package/dist/chunks/deadline-DkiB8ZHE.cjs +51 -0
- package/dist/chunks/deadline-DkiB8ZHE.cjs.map +1 -0
- package/dist/chunks/errors-9h8sdFFX.js +120 -0
- package/dist/chunks/errors-9h8sdFFX.js.map +1 -0
- package/dist/chunks/errors-BwOF6T_M.cjs +167 -0
- package/dist/chunks/errors-BwOF6T_M.cjs.map +1 -0
- package/dist/chunks/index-mr7sSAgP.d.ts +426 -0
- package/dist/chunks/index-vz0iW5V2.d.cts +426 -0
- package/dist/chunks/inert-html-D75NyVvT.js +34 -0
- package/dist/chunks/inert-html-D75NyVvT.js.map +1 -0
- package/dist/chunks/inert-html-DyxjWDok.cjs +39 -0
- package/dist/chunks/inert-html-DyxjWDok.cjs.map +1 -0
- package/dist/chunks/mime--LB7kdqG.cjs +153 -0
- package/dist/chunks/mime--LB7kdqG.cjs.map +1 -0
- package/dist/chunks/mime-aa-HA2dm.js +100 -0
- package/dist/chunks/mime-aa-HA2dm.js.map +1 -0
- package/dist/chunks/paste-adapter--SPL4PRE.d.cts +35 -0
- package/dist/chunks/paste-adapter-uahXnTYk.d.ts +35 -0
- package/dist/chunks/paste-reader-Bo01IMC_.cjs +289 -0
- package/dist/chunks/paste-reader-Bo01IMC_.cjs.map +1 -0
- package/dist/chunks/paste-reader-D9i7yMXF.js +224 -0
- package/dist/chunks/paste-reader-D9i7yMXF.js.map +1 -0
- package/dist/chunks/paste-reader-DcXnRWQr.d.cts +96 -0
- package/dist/chunks/paste-reader-DcXnRWQr.d.ts +96 -0
- package/dist/chunks/payload-CUymxwim.cjs +100 -0
- package/dist/chunks/payload-CUymxwim.cjs.map +1 -0
- package/dist/chunks/payload-CcwKJ_bU.d.cts +162 -0
- package/dist/chunks/payload-Cl_8hCI5.d.ts +162 -0
- package/dist/chunks/payload-DGw-JOo7.js +71 -0
- package/dist/chunks/payload-DGw-JOo7.js.map +1 -0
- package/dist/chunks/payload-DI5AorDz.js +103 -0
- package/dist/chunks/payload-DI5AorDz.js.map +1 -0
- package/dist/chunks/payload-J6GjHuh3.cjs +132 -0
- package/dist/chunks/payload-J6GjHuh3.cjs.map +1 -0
- package/dist/chunks/share-Bop47Znn.js +208 -0
- package/dist/chunks/share-Bop47Znn.js.map +1 -0
- package/dist/chunks/share-C0esXvRK.d.cts +115 -0
- package/dist/chunks/share-ayDz974N.cjs +231 -0
- package/dist/chunks/share-ayDz974N.cjs.map +1 -0
- package/dist/chunks/share-e7FenIr2.d.ts +115 -0
- package/dist/chunks/text-field-Ba8W3v4R.cjs +77 -0
- package/dist/chunks/text-field-Ba8W3v4R.cjs.map +1 -0
- package/dist/chunks/text-field-C0SGmvvR.d.cts +18 -0
- package/dist/chunks/text-field-C0SGmvvR.d.ts +18 -0
- package/dist/chunks/text-field-DUvrMMaK.js +66 -0
- package/dist/chunks/text-field-DUvrMMaK.js.map +1 -0
- package/dist/chunks/url-B9jdFGQy.cjs +86 -0
- package/dist/chunks/url-B9jdFGQy.cjs.map +1 -0
- package/dist/chunks/url-BcMYVCXQ.js +135 -0
- package/dist/chunks/url-BcMYVCXQ.js.map +1 -0
- package/dist/chunks/url-D4PGsRm8.cjs +164 -0
- package/dist/chunks/url-D4PGsRm8.cjs.map +1 -0
- package/dist/chunks/url-DWdElCT3.d.cts +43 -0
- package/dist/chunks/url-DWdElCT3.d.ts +43 -0
- package/dist/chunks/url-vJaFPbNL.js +57 -0
- package/dist/chunks/url-vJaFPbNL.js.map +1 -0
- package/dist/code.cjs +22 -113
- package/dist/code.cjs.map +1 -1
- package/dist/code.d.cts +4 -28
- package/dist/code.d.ts +4 -28
- package/dist/code.js +5 -96
- package/dist/code.js.map +1 -1
- package/dist/color.cjs +21 -893
- package/dist/color.cjs.map +1 -1
- package/dist/color.d.cts +4 -28
- package/dist/color.d.ts +4 -28
- package/dist/color.js +4 -876
- package/dist/color.js.map +1 -1
- package/dist/core.cjs +52 -1659
- package/dist/core.d.cts +8 -878
- package/dist/core.d.ts +8 -878
- package/dist/core.js +7 -1614
- package/dist/image.cjs +23 -94
- package/dist/image.cjs.map +1 -1
- package/dist/image.d.cts +1 -0
- package/dist/image.d.ts +1 -0
- package/dist/image.js +3 -74
- package/dist/image.js.map +1 -1
- package/dist/index.cjs +74 -2072
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +8 -978
- package/dist/index.d.ts +8 -978
- package/dist/index.js +7 -2005
- package/dist/index.js.map +1 -1
- package/dist/link.cjs +26 -339
- package/dist/link.cjs.map +1 -1
- package/dist/link.d.cts +5 -83
- package/dist/link.d.ts +5 -83
- package/dist/link.js +7 -320
- package/dist/link.js.map +1 -1
- package/dist/markdown.cjs +19 -159
- package/dist/markdown.cjs.map +1 -1
- package/dist/markdown.d.cts +3 -16
- package/dist/markdown.d.ts +3 -16
- package/dist/markdown.js +6 -146
- package/dist/markdown.js.map +1 -1
- package/dist/rich.cjs +1123 -940
- package/dist/rich.cjs.map +1 -1
- package/dist/rich.d.cts +101 -91
- package/dist/rich.d.ts +101 -91
- package/dist/rich.js +1099 -919
- package/dist/rich.js.map +1 -1
- package/dist/share.cjs +5 -640
- package/dist/share.d.cts +3 -248
- package/dist/share.d.ts +3 -248
- package/dist/share.js +1 -637
- package/dist/structured.cjs +13 -95
- package/dist/structured.cjs.map +1 -1
- package/dist/structured.d.cts +2 -11
- package/dist/structured.d.ts +2 -11
- package/dist/structured.js +4 -86
- package/dist/structured.js.map +1 -1
- package/dist/table.cjs +13 -40
- package/dist/table.cjs.map +1 -1
- package/dist/table.d.cts +2 -12
- package/dist/table.d.ts +2 -12
- package/dist/table.js +4 -31
- package/dist/table.js.map +1 -1
- package/dist/testing.cjs +10 -43
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +6 -181
- package/dist/testing.d.ts +6 -181
- package/dist/testing.js +3 -36
- package/dist/testing.js.map +1 -1
- package/package.json +37 -5
- package/dist/core.cjs.map +0 -1
- package/dist/core.js.map +0 -1
- package/dist/share.cjs.map +0 -1
- package/dist/share.js.map +0 -1
package/dist/share.d.cts
CHANGED
|
@@ -1,248 +1,3 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
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
|
-
|
|
2
|
-
|
|
3
|
-
|
|
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 };
|