react-smart-copy 1.13.2 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/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