react-smart-copy 1.13.2 → 1.14.1
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 +104 -3
- package/dist/link.cjs +651 -0
- package/dist/link.cjs.map +1 -0
- package/dist/link.d.cts +259 -0
- package/dist/link.d.ts +259 -0
- package/dist/link.js +637 -0
- package/dist/link.js.map +1 -0
- package/dist/markdown.cjs +17 -1
- package/dist/markdown.cjs.map +1 -1
- package/dist/markdown.js +17 -1
- package/dist/markdown.js.map +1 -1
- package/package.json +35 -4
package/dist/link.d.ts
ADDED
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
//#region src/core/payload.d.ts
|
|
2
|
+
interface HtmlPayload {
|
|
3
|
+
readonly kind: 'html';
|
|
4
|
+
readonly html: string;
|
|
5
|
+
/** Required plain-text fallback for targets that don't understand HTML. */
|
|
6
|
+
readonly text: string;
|
|
7
|
+
}
|
|
8
|
+
interface MultiPayloadItem {
|
|
9
|
+
/**
|
|
10
|
+
* The MIME type, or a web custom format (`web application/vnd.acme+json`).
|
|
11
|
+
* Web custom formats are only written by the async Clipboard API; copy and drag
|
|
12
|
+
* events skip them.
|
|
13
|
+
*/
|
|
14
|
+
readonly mimeType: string;
|
|
15
|
+
readonly data: string | Blob;
|
|
16
|
+
/**
|
|
17
|
+
* Skip this item, instead of failing the copy, when the browser cannot write its type.
|
|
18
|
+
* An optional item is only written when `ClipboardItem.supports()` confirms the type.
|
|
19
|
+
* At least one item must be written.
|
|
20
|
+
*/
|
|
21
|
+
readonly optional?: boolean;
|
|
22
|
+
}
|
|
23
|
+
interface MultiPayload {
|
|
24
|
+
readonly kind: 'multi';
|
|
25
|
+
readonly items: readonly MultiPayloadItem[];
|
|
26
|
+
}
|
|
27
|
+
//#endregion
|
|
28
|
+
//#region src/link/url.d.ts
|
|
29
|
+
/** Schemes a copied or pasted link may use by default. Never `javascript:`, `data:`, `vbscript:` or `file:`. */
|
|
30
|
+
export declare const DEFAULT_LINK_PROTOCOLS: readonly string[];
|
|
31
|
+
/**
|
|
32
|
+
* Query parameters that only track where a click came from: the defaults of
|
|
33
|
+
* {@link cleanLinkUrl}. `utm_` matches every parameter starting with it.
|
|
34
|
+
*/
|
|
35
|
+
export declare const TRACKING_PARAMETERS: readonly string[];
|
|
36
|
+
interface CleanLinkOptions {
|
|
37
|
+
/**
|
|
38
|
+
* Parameters to remove: exact names, names ending in `_` (a prefix, like
|
|
39
|
+
* `utm_`), or regular expressions tested against the name. Default {@link TRACKING_PARAMETERS}.
|
|
40
|
+
*/
|
|
41
|
+
readonly params?: readonly (string | RegExp)[];
|
|
42
|
+
/** Parameters never removed, even when `params` matches them. */
|
|
43
|
+
readonly keep?: readonly string[];
|
|
44
|
+
}
|
|
45
|
+
interface LinkUrlOptions {
|
|
46
|
+
/** Resolves relative links. Default: the page's address in a browser; required elsewhere for relative links. */
|
|
47
|
+
readonly base?: string | URL;
|
|
48
|
+
/** Allowed schemes, with the colon. Default {@link DEFAULT_LINK_PROTOCOLS}. */
|
|
49
|
+
readonly protocols?: readonly string[];
|
|
50
|
+
/** Remove tracking parameters: `true` for {@link TRACKING_PARAMETERS}, or your own list. Default `false`. */
|
|
51
|
+
readonly clean?: boolean | CleanLinkOptions;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The link as an absolute, safe URL string, or a typed `invalid-payload` error:
|
|
55
|
+
* relative links are resolved, the scheme must be allowed, user names and
|
|
56
|
+
* passwords are always removed, and tracking parameters optionally.
|
|
57
|
+
*/
|
|
58
|
+
export declare function resolveLinkUrl(input: string | URL, options?: LinkUrlOptions): string;
|
|
59
|
+
/**
|
|
60
|
+
* Removes tracking parameters (`utm_*`, `fbclid`, `gclid`, ...) from a link, keeping
|
|
61
|
+
* everything else, including the fragment. Also validates it like every link here.
|
|
62
|
+
*
|
|
63
|
+
* @example
|
|
64
|
+
* cleanLinkUrl('https://shop.example/p/42?utm_source=news&color=red'); // 'https://shop.example/p/42?color=red'
|
|
65
|
+
*/
|
|
66
|
+
export declare function cleanLinkUrl(url: string | URL, options?: CleanLinkOptions & Omit<LinkUrlOptions, 'clean'>): string;
|
|
67
|
+
//#endregion
|
|
68
|
+
//#region src/link/payload.d.ts
|
|
69
|
+
/** A link with an optional title. */
|
|
70
|
+
interface Link {
|
|
71
|
+
readonly url: string | URL;
|
|
72
|
+
/** What the link says when pasted into a document or chat. Default: the URL. */
|
|
73
|
+
readonly title?: string;
|
|
74
|
+
}
|
|
75
|
+
/** A link: a URL, a `{ url, title }` object, or an `<a>` element (its `href` and text). */
|
|
76
|
+
type LinkSource = string | URL | Link | HTMLAnchorElement;
|
|
77
|
+
/** A validated link: an absolute, safe URL and a clean title. */
|
|
78
|
+
interface ResolvedLink {
|
|
79
|
+
readonly url: string;
|
|
80
|
+
/** Never empty: the URL when there is no title. */
|
|
81
|
+
readonly title: string;
|
|
82
|
+
/** Whether `title` came from the input (`false`: it is the URL). */
|
|
83
|
+
readonly titled: boolean;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* What the plain-text flavour holds (editors, terminals and address bars paste it):
|
|
87
|
+
* `'url'` (the default), `'title'`, `'title-and-url'` (the title, then the URL on
|
|
88
|
+
* the next line) or `'markdown'` (`[Title](URL)`).
|
|
89
|
+
*/
|
|
90
|
+
type LinkTextFormat = 'url' | 'title' | 'title-and-url' | 'markdown';
|
|
91
|
+
interface LinkPayloadOptions extends LinkUrlOptions {
|
|
92
|
+
/** Default `'url'`. */
|
|
93
|
+
readonly text?: LinkTextFormat;
|
|
94
|
+
/** Longest title kept, in characters; longer ones end in an ellipsis. Default {@link DEFAULT_LINK_TITLE_LENGTH}. */
|
|
95
|
+
readonly maxTitleLength?: number;
|
|
96
|
+
}
|
|
97
|
+
interface LinkDragPayloadOptions extends LinkPayloadOptions {
|
|
98
|
+
/**
|
|
99
|
+
* `'drag'`: a multi-format payload that also carries `text/uri-list` and
|
|
100
|
+
* Firefox's `text/x-moz-url`, for `useDragCopy` and `useCopyInterceptor` (a link
|
|
101
|
+
* dropped on the tab bar opens). Clipboard writes skip those two where the
|
|
102
|
+
* browser can't write them.
|
|
103
|
+
*/
|
|
104
|
+
readonly target: 'drag';
|
|
105
|
+
}
|
|
106
|
+
export declare const DEFAULT_LINK_TITLE_LENGTH = 300;
|
|
107
|
+
/**
|
|
108
|
+
* Validates a link and its title: see {@link resolveLinkUrl} for the URL rules.
|
|
109
|
+
* An `<a>` element gives its `href` and its text (or `title` attribute).
|
|
110
|
+
*/
|
|
111
|
+
export declare function resolveLink(source: LinkSource, options?: LinkPayloadOptions): ResolvedLink;
|
|
112
|
+
/** `[title](url)`, safe in every CommonMark renderer: brackets and backslashes escaped, parentheses and spaces encoded. */
|
|
113
|
+
export declare function markdownLink(link: ResolvedLink): string;
|
|
114
|
+
/**
|
|
115
|
+
* A copy payload for a link: an HTML anchor, so Slack, Google Docs, Notion,
|
|
116
|
+
* Teams, Word and mail paste a titled link, and plain text (the URL by default)
|
|
117
|
+
* for editors and address bars. The URL is validated (allowed schemes only,
|
|
118
|
+
* credentials removed, optionally cleaned of tracking) and the title is cleaned
|
|
119
|
+
* of hidden characters; both are escaped.
|
|
120
|
+
*
|
|
121
|
+
* @example
|
|
122
|
+
* copy(() => linkPayload({ url: location.href, title: document.title }, { clean: true }));
|
|
123
|
+
* useDragCopy({ payload: () => linkPayload(anchor, { target: 'drag' }) });
|
|
124
|
+
*/
|
|
125
|
+
export declare function linkPayload(source: LinkSource, options: LinkDragPayloadOptions): MultiPayload;
|
|
126
|
+
export declare function linkPayload(source: LinkSource, options?: LinkPayloadOptions): HtmlPayload;
|
|
127
|
+
//#endregion
|
|
128
|
+
//#region src/link/fragment.d.ts
|
|
129
|
+
/**
|
|
130
|
+
* A passage to link to: `start` alone, or `start` to `end` for a longer one.
|
|
131
|
+
* `prefix` and `suffix` are the words around it, used to tell apart passages
|
|
132
|
+
* that appear more than once. Each term must lie within one block of the page
|
|
133
|
+
* (a paragraph, a list item, a heading).
|
|
134
|
+
*/
|
|
135
|
+
interface TextFragment {
|
|
136
|
+
readonly start: string;
|
|
137
|
+
readonly end?: string;
|
|
138
|
+
readonly prefix?: string;
|
|
139
|
+
readonly suffix?: string;
|
|
140
|
+
}
|
|
141
|
+
interface TextFragmentOptions extends LinkUrlOptions {
|
|
142
|
+
/** Passages longer than this many words link by their first and last words (`start,end`). Default 10. */
|
|
143
|
+
readonly maxWords?: number;
|
|
144
|
+
/** Words kept at each end of a long passage, and of prefix and suffix context. Default 4. */
|
|
145
|
+
readonly contextWords?: number;
|
|
146
|
+
/** Where to look for repeats of the passage, to decide whether context is needed. Default `document.body`. */
|
|
147
|
+
readonly root?: Node;
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* A link that scrolls to, and highlights, a passage of the page: the
|
|
151
|
+
* [text fragment](https://wicg.github.io/scroll-to-text-fragment/) syntax
|
|
152
|
+
* (`#:~:text=`), supported by Chromium, Safari and Firefox. Browsers without it
|
|
153
|
+
* open the page at its normal position (or its existing `#section`).
|
|
154
|
+
*
|
|
155
|
+
* The passage is a string, a {@link TextFragment}, or a DOM `Range` (the user's
|
|
156
|
+
* selection): long passages link by their first and last words, and the words
|
|
157
|
+
* around a passage are added when it appears more than once on the page.
|
|
158
|
+
*
|
|
159
|
+
* @example
|
|
160
|
+
* textFragmentUrl(location.href, window.getSelection()!.getRangeAt(0));
|
|
161
|
+
* textFragmentUrl('https://example.com/docs#install', 'npm install react-smart-copy');
|
|
162
|
+
*/
|
|
163
|
+
export declare function textFragmentUrl(url: string | URL, passage: string | TextFragment | Range, options?: TextFragmentOptions): string;
|
|
164
|
+
/** Whether this browser scrolls to text fragments (`document.fragmentDirective`). */
|
|
165
|
+
export declare function supportsTextFragments(): boolean;
|
|
166
|
+
//#endregion
|
|
167
|
+
//#region src/link/paste.d.ts
|
|
168
|
+
/** What was pasted or dropped: a `PasteResult` from `usePaste`, a `DataTransfer`-like source, or the flavours themselves. */
|
|
169
|
+
interface LinkPasteSource {
|
|
170
|
+
readonly text?: string | null;
|
|
171
|
+
readonly html?: string | null;
|
|
172
|
+
/** `text/uri-list`. */
|
|
173
|
+
readonly uriList?: string | null;
|
|
174
|
+
/** A `PasteResult`'s entries: a `text/uri-list` entry is read from here. */
|
|
175
|
+
readonly items?: readonly {
|
|
176
|
+
readonly type: string;
|
|
177
|
+
readonly data: string | Blob;
|
|
178
|
+
}[];
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* The link the clipboard (or a drop) holds, or `null`: from `text/uri-list`,
|
|
182
|
+
* from HTML that is exactly one link (keeping its title), or from text that is
|
|
183
|
+
* exactly one URL. Every URL is validated: allowed schemes only (never
|
|
184
|
+
* `javascript:`), credentials removed. Never throws for clipboard content.
|
|
185
|
+
*
|
|
186
|
+
* @example
|
|
187
|
+
* usePaste({ accept: ['text', 'html', 'text/uri-list'], onPaste: (result) => {
|
|
188
|
+
* const link = readLink(result);
|
|
189
|
+
* if (link) addBookmark(link.url, link.title);
|
|
190
|
+
* } });
|
|
191
|
+
*/
|
|
192
|
+
export declare function readLink(source: LinkPasteSource, options?: LinkUrlOptions): ResolvedLink | null;
|
|
193
|
+
/** Structural paste event: a DOM `ClipboardEvent` and React's `onPaste` event both fit. */
|
|
194
|
+
interface LinkPasteEvent {
|
|
195
|
+
readonly clipboardData: {
|
|
196
|
+
getData(format: string): string;
|
|
197
|
+
} | null;
|
|
198
|
+
readonly currentTarget: EventTarget | null;
|
|
199
|
+
readonly target: EventTarget | null;
|
|
200
|
+
readonly defaultPrevented: boolean;
|
|
201
|
+
preventDefault(): void;
|
|
202
|
+
}
|
|
203
|
+
interface PasteAsLinkOptions extends LinkUrlOptions {
|
|
204
|
+
/**
|
|
205
|
+
* What replaces the selection. Default: a Markdown link, `[selection](url)`.
|
|
206
|
+
* Receives the selected text and the pasted link.
|
|
207
|
+
*/
|
|
208
|
+
readonly format?: (selection: string, link: ResolvedLink) => string;
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* A paste handler for text fields: pasting a link over selected text turns the
|
|
212
|
+
* selection into a link (`[selected text](url)` by default), as GitHub, Slack
|
|
213
|
+
* and Notion do. Everything else is left to the browser: pasting with nothing
|
|
214
|
+
* selected, pasting over a URL, or pasting something that is not one link. The
|
|
215
|
+
* browser's undo still works. Returns whether it handled the paste.
|
|
216
|
+
*
|
|
217
|
+
* @example
|
|
218
|
+
* <textarea onPaste={pasteAsLink} />
|
|
219
|
+
*/
|
|
220
|
+
export declare function pasteAsLink(event: LinkPasteEvent, options?: PasteAsLinkOptions): boolean;
|
|
221
|
+
/** A link to the current selection, as returned by {@link selectionLink}. */
|
|
222
|
+
interface SelectionLink extends ResolvedLink {
|
|
223
|
+
/** The selected text, as one line. */
|
|
224
|
+
readonly quote: string;
|
|
225
|
+
}
|
|
226
|
+
interface SelectionLinkOptions extends TextFragmentOptions {
|
|
227
|
+
/** The page to link to. Default: `location.href`. */
|
|
228
|
+
readonly url?: string | URL;
|
|
229
|
+
/** Default: `document.title`. */
|
|
230
|
+
readonly title?: string;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* A link to the passage the user has selected (a text fragment link), with the
|
|
234
|
+
* page title and the quote, or `null` when nothing is selected. Pass it to
|
|
235
|
+
* `linkPayload` to copy it.
|
|
236
|
+
*
|
|
237
|
+
* @example
|
|
238
|
+
* const link = selectionLink();
|
|
239
|
+
* if (link) copy(() => linkPayload(link));
|
|
240
|
+
*/
|
|
241
|
+
export declare function selectionLink(options?: SelectionLinkOptions): SelectionLink | null;
|
|
242
|
+
//#endregion
|
|
243
|
+
//#region src/core/text-field.d.ts
|
|
244
|
+
/**
|
|
245
|
+
* Text-field helpers shared by the paste handlers of the opt-in entry points.
|
|
246
|
+
* Internal: not part of `react-smart-copy/core`'s public API.
|
|
247
|
+
*/
|
|
248
|
+
/** Text fields `setRangeText` and `execCommand('insertText')` both support. */
|
|
249
|
+
type TextField = HTMLTextAreaElement | HTMLInputElement;
|
|
250
|
+
/**
|
|
251
|
+
* Inserts text at the cursor of a `<textarea>` or text `<input>`, replacing the
|
|
252
|
+
* selection, as typing or pasting would: the browser's undo (Ctrl/⌘+Z) still
|
|
253
|
+
* works, `input` events fire (so React and other frameworks see the change),
|
|
254
|
+
* and `maxlength` is respected. Returns `false` for disabled or read-only fields.
|
|
255
|
+
*/
|
|
256
|
+
export declare function insertText(field: TextField, text: string): boolean;
|
|
257
|
+
//#endregion
|
|
258
|
+
export type { CleanLinkOptions, Link, LinkDragPayloadOptions, LinkPasteEvent, LinkPasteSource, LinkPayloadOptions, LinkSource, LinkTextFormat, LinkUrlOptions, PasteAsLinkOptions, ResolvedLink, SelectionLink, SelectionLinkOptions, TextFragment, TextFragmentOptions };
|
|
259
|
+
//# sourceMappingURL=link.d.ts.map
|