react-smart-copy 1.15.0 → 1.17.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/rich.d.ts ADDED
@@ -0,0 +1,212 @@
1
+ //#region src/link/url.d.ts
2
+ interface CleanLinkOptions {
3
+ /**
4
+ * Parameters to remove: exact names, names ending in `_` (a prefix, like
5
+ * `utm_`), or regular expressions tested against the name. Default {@link TRACKING_PARAMETERS}.
6
+ */
7
+ readonly params?: readonly (string | RegExp)[];
8
+ /** Parameters never removed, even when `params` matches them. */
9
+ readonly keep?: readonly string[];
10
+ }
11
+ interface LinkUrlOptions {
12
+ /** Resolves relative links. Default: the page's address in a browser; required elsewhere for relative links. */
13
+ readonly base?: string | URL;
14
+ /** Allowed schemes, with the colon. Default {@link DEFAULT_LINK_PROTOCOLS}. */
15
+ readonly protocols?: readonly string[];
16
+ /** Remove tracking parameters: `true` for {@link TRACKING_PARAMETERS}, or your own list. Default `false`. */
17
+ readonly clean?: boolean | CleanLinkOptions;
18
+ }
19
+ //#endregion
20
+ //#region src/rich/style.d.ts
21
+ /** Where styles come from: `getComputedStyle` for a live element, the `style` attribute otherwise. */
22
+ interface StyleSource {
23
+ getPropertyValue(name: string): string;
24
+ }
25
+ /**
26
+ * How colours are copied:
27
+ * - `readable` (default): every colour, made opaque, except text that would be hard to
28
+ * read where it lands (contrast under 3:1 on its background, or on white), such as
29
+ * light text from a dark theme
30
+ * - `keep`: every colour, made opaque
31
+ * - `none`: no colours: the destination's own text colour and background
32
+ */
33
+ type RichColors = 'readable' | 'keep' | 'none';
34
+ //#endregion
35
+ //#region src/rich/walk.d.ts
36
+ interface RichOptions extends Pick<LinkUrlOptions, 'protocols'> {
37
+ /** Resolves relative links and images. Default: the source document's address. */
38
+ readonly base?: string | URL;
39
+ /** Default `"readable"`. See {@link RichColors}. */
40
+ readonly colors?: RichColors;
41
+ /**
42
+ * Images: `"keep"` (default) with absolute `https:` and `http:` addresses and their
43
+ * displayed size; `"alt"` writes their alt text instead; `"drop"` leaves them out.
44
+ */
45
+ readonly images?: 'keep' | 'alt' | 'drop';
46
+ /** Also keep `data:` images (PNG, JPEG, GIF, WebP, up to 2 MB each). Many mail clients block them. Default `false`. */
47
+ readonly dataImages?: boolean;
48
+ /**
49
+ * Where styles come from: `"computed"` (default for elements and selections on the
50
+ * page: what the reader sees), `"inline"` (only `style` attributes: the default for
51
+ * HTML strings and detached nodes), or `"none"`.
52
+ */
53
+ readonly styles?: 'computed' | 'inline' | 'none';
54
+ /** More elements to leave out, as a CSS selector. `[data-copy-ignore]`, `[hidden]` and `[aria-hidden="true"]` always are. */
55
+ readonly ignore?: string;
56
+ /** The background the content is pasted on, for readability checks. Default `"#ffffff"`. */
57
+ readonly background?: string;
58
+ /** Most elements written; the rest is left out and `truncated` is set. Default 10,000. */
59
+ readonly maxElements?: number;
60
+ /** Most characters of HTML written, roughly. Default 1,000,000. */
61
+ readonly maxLength?: number;
62
+ /** The plain-text version. Default: readable text with lists, tables and line breaks. Pass `htmlToMarkdown` for Markdown. */
63
+ readonly text?: (root: HTMLElement) => string;
64
+ /** Reads an element's computed style. Default `getComputedStyle`; set it for DOMs that lack one. */
65
+ readonly computedStyle?: (element: Element) => StyleSource | null;
66
+ }
67
+ /**
68
+ * Why something was left out: `unsafe-element` (scripts, embeds, forms, SVG, media),
69
+ * `hidden`, `ignored`, `unsafe-link`, `unsafe-image`, `image` (by the `images` option),
70
+ * `unreadable-color` (by `colors: "readable"`), or `misplaced` (content a table can't
71
+ * hold where it is, which every HTML parser would move out of the table).
72
+ */
73
+ type RichRemovalReason = 'unsafe-element' | 'hidden' | 'ignored' | 'unsafe-link' | 'unsafe-image' | 'image' | 'unreadable-color' | 'misplaced';
74
+ interface RichRemoval {
75
+ readonly reason: RichRemovalReason;
76
+ /** The element name, or the URL scheme for links and images. */
77
+ readonly name: string;
78
+ readonly count: number;
79
+ }
80
+ interface RichResult {
81
+ /** Portable HTML: allowlisted elements and attributes, inline styles, absolute URLs. */
82
+ readonly html: string;
83
+ /** The same content as plain text. */
84
+ readonly text: string;
85
+ /** What was left out, and why: for logs and audits. */
86
+ readonly removed: readonly RichRemoval[];
87
+ /** The content went past `maxElements` or `maxLength` and was cut there. */
88
+ readonly truncated: boolean;
89
+ }
90
+ /** What can be copied: an element, a selection range, a fragment, or HTML text. */
91
+ type RichSource = Element | DocumentFragment | Range | string;
92
+ /**
93
+ * Converts content into portable rich text: the HTML that mail clients, Google Docs,
94
+ * Word, Notion and Slack paste as it looks, plus a plain-text version.
95
+ *
96
+ * - Only safe, widely supported elements and attributes are kept: never scripts,
97
+ * event handlers, embeds, forms or tracking pixels from `data:` or `blob:` URLs.
98
+ * - Styles are inline, from what the reader sees (computed styles) for content on
99
+ * the page. Classes, stylesheets and CSS variables can't travel; their result can.
100
+ * - Every colour becomes an opaque hex value, which every mail client understands
101
+ * (not `oklch()` or `rgb(r g b / 50%)`). Text that would be unreadable on a white
102
+ * page, such as light text from a dark theme, keeps the destination's colour.
103
+ * - Links and images get absolute, scheme-checked URLs; images get their displayed size.
104
+ *
105
+ * Never inserts anything into the page: the output is built in a separate, inert document.
106
+ *
107
+ * @example
108
+ * const { html, text, removed } = prepareRich(articleRef.current);
109
+ */
110
+ export declare function prepareRich(source: RichSource, options?: RichOptions): RichResult;
111
+ //#endregion
112
+ //#region src/core/payload.d.ts
113
+ interface TextPayload {
114
+ readonly kind: 'text';
115
+ readonly value: string;
116
+ }
117
+ interface HtmlPayload {
118
+ readonly kind: 'html';
119
+ readonly html: string;
120
+ /** Required plain-text fallback for targets that don't understand HTML. */
121
+ readonly text: string;
122
+ }
123
+ interface JsonPayload {
124
+ readonly kind: 'json';
125
+ readonly value: unknown;
126
+ /** `true` = 2-space indent, a number = that indent, falsy = compact. */
127
+ readonly pretty?: boolean | number;
128
+ }
129
+ //#endregion
130
+ //#region src/core/copy-interceptor.d.ts
131
+ /**
132
+ * Native copy interception: rewrite, redact or block what lands on the
133
+ * clipboard when the user copies (Ctrl/Cmd+C, context menu) or cuts inside a
134
+ * scope.
135
+ *
136
+ * Writes go through `event.clipboardData` synchronously, so no permission
137
+ * prompt, no secure-context requirement, and it works in every browser. The
138
+ * price is that only strings can be written, which the types enforce.
139
+ *
140
+ * Not a security boundary: users can still screenshot, use dev tools or
141
+ * disable script. Treat redaction as a guard against accidents.
142
+ */
143
+ type InterceptedCopyKind = 'copy' | 'cut';
144
+ /** What the user selected when they copied. */
145
+ interface CopySelection {
146
+ readonly kind: InterceptedCopyKind;
147
+ /** What the browser would put on the clipboard as `text/plain`. */
148
+ readonly text: string;
149
+ /** Serialised HTML of the selection; `null` inside text inputs. */
150
+ readonly html: string | null;
151
+ /** A detached clone of the selected nodes, safe to mutate; `null` inside text inputs. */
152
+ readonly fragment: DocumentFragment | null;
153
+ /** The `<input>`/`<textarea>` the selection lives in, if any. */
154
+ readonly field: HTMLInputElement | HTMLTextAreaElement | null;
155
+ /** Whether a `cut` would remove the selection (form field or contenteditable). */
156
+ readonly editable: boolean;
157
+ }
158
+ /**
159
+ * A multi payload whose items are all strings; the only kind `setData` accepts.
160
+ * Web custom formats (`web …`) are skipped: only the async Clipboard API writes them.
161
+ */
162
+ interface SyncMultiPayload {
163
+ readonly kind: 'multi';
164
+ readonly items: readonly {
165
+ readonly mimeType: string;
166
+ readonly data: string;
167
+ readonly optional?: boolean;
168
+ }[];
169
+ }
170
+ /** Payloads writable synchronously during a copy event. Images need the async clipboard. */
171
+ type SyncCopyPayload = TextPayload | HtmlPayload | JsonPayload | SyncMultiPayload;
172
+ /**
173
+ * What a transform returns:
174
+ * - a string or payload: write that instead of the selection
175
+ * - `false`: block the copy (nothing reaches the clipboard; a cut deletes nothing)
176
+ * - `null` / `undefined`: leave the browser's default copy untouched
177
+ *
178
+ * Must be synchronous: the clipboard closes when the event handler returns.
179
+ */
180
+ type CopyInterceptDecision = string | SyncCopyPayload | false | null | undefined;
181
+ type CopyInterceptTransform = (selection: CopySelection) => CopyInterceptDecision;
182
+ //#endregion
183
+ //#region src/rich/payload.d.ts
184
+ /**
185
+ * Content to copy as portable rich text: the sanitized HTML, and its plain text for
186
+ * editors and plain fields. A typed `invalid-payload` error when nothing is left to copy.
187
+ *
188
+ * @example
189
+ * const { copy } = useCopy();
190
+ * <button onClick={() => copy(() => richPayload(noteRef.current))}>Copy note</button>
191
+ */
192
+ export declare function richPayload(source: RichSource, options?: RichOptions): HtmlPayload;
193
+ /**
194
+ * A copy interceptor transform that makes Ctrl/Cmd+C (and cut) of a selection in your
195
+ * page portable: what the reader selected, with the styles they see, sanitized. The
196
+ * plain text stays the browser's own. Selections in text fields are left alone.
197
+ *
198
+ * @example
199
+ * useCopyInterceptor(articleRef, { transform: richTransform() });
200
+ */
201
+ export declare function richTransform(options?: RichOptions): CopyInterceptTransform;
202
+ //#endregion
203
+ //#region src/rich/text.d.ts
204
+ /**
205
+ * Readable plain text for sanitized rich content: blocks on their own lines, list
206
+ * items with bullets or numbers (indented when nested), table cells separated by tabs,
207
+ * images by their alt text, and preformatted text as it is.
208
+ */
209
+ export declare function plainText(root: HTMLElement): string;
210
+ //#endregion
211
+ export type { RichColors, RichOptions, RichRemoval, RichRemovalReason, RichResult, RichSource, StyleSource };
212
+ //# sourceMappingURL=rich.d.ts.map