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.
Files changed (154) hide show
  1. package/README.md +86 -5
  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/inert-html-D75NyVvT.js +34 -0
  35. package/dist/chunks/inert-html-D75NyVvT.js.map +1 -0
  36. package/dist/chunks/inert-html-DyxjWDok.cjs +39 -0
  37. package/dist/chunks/inert-html-DyxjWDok.cjs.map +1 -0
  38. package/dist/chunks/mime--LB7kdqG.cjs +153 -0
  39. package/dist/chunks/mime--LB7kdqG.cjs.map +1 -0
  40. package/dist/chunks/mime-aa-HA2dm.js +100 -0
  41. package/dist/chunks/mime-aa-HA2dm.js.map +1 -0
  42. package/dist/chunks/paste-adapter--SPL4PRE.d.cts +35 -0
  43. package/dist/chunks/paste-adapter-uahXnTYk.d.ts +35 -0
  44. package/dist/chunks/paste-reader-Bo01IMC_.cjs +289 -0
  45. package/dist/chunks/paste-reader-Bo01IMC_.cjs.map +1 -0
  46. package/dist/chunks/paste-reader-D9i7yMXF.js +224 -0
  47. package/dist/chunks/paste-reader-D9i7yMXF.js.map +1 -0
  48. package/dist/chunks/paste-reader-DcXnRWQr.d.cts +96 -0
  49. package/dist/chunks/paste-reader-DcXnRWQr.d.ts +96 -0
  50. package/dist/chunks/payload-CUymxwim.cjs +100 -0
  51. package/dist/chunks/payload-CUymxwim.cjs.map +1 -0
  52. package/dist/chunks/payload-CcwKJ_bU.d.cts +162 -0
  53. package/dist/chunks/payload-Cl_8hCI5.d.ts +162 -0
  54. package/dist/chunks/payload-DGw-JOo7.js +71 -0
  55. package/dist/chunks/payload-DGw-JOo7.js.map +1 -0
  56. package/dist/chunks/payload-DI5AorDz.js +103 -0
  57. package/dist/chunks/payload-DI5AorDz.js.map +1 -0
  58. package/dist/chunks/payload-J6GjHuh3.cjs +132 -0
  59. package/dist/chunks/payload-J6GjHuh3.cjs.map +1 -0
  60. package/dist/chunks/share-Bop47Znn.js +208 -0
  61. package/dist/chunks/share-Bop47Znn.js.map +1 -0
  62. package/dist/chunks/share-C0esXvRK.d.cts +115 -0
  63. package/dist/chunks/share-ayDz974N.cjs +231 -0
  64. package/dist/chunks/share-ayDz974N.cjs.map +1 -0
  65. package/dist/chunks/share-e7FenIr2.d.ts +115 -0
  66. package/dist/chunks/text-field-Ba8W3v4R.cjs +77 -0
  67. package/dist/chunks/text-field-Ba8W3v4R.cjs.map +1 -0
  68. package/dist/chunks/text-field-C0SGmvvR.d.cts +18 -0
  69. package/dist/chunks/text-field-C0SGmvvR.d.ts +18 -0
  70. package/dist/chunks/text-field-DUvrMMaK.js +66 -0
  71. package/dist/chunks/text-field-DUvrMMaK.js.map +1 -0
  72. package/dist/chunks/url-B9jdFGQy.cjs +86 -0
  73. package/dist/chunks/url-B9jdFGQy.cjs.map +1 -0
  74. package/dist/chunks/url-BcMYVCXQ.js +135 -0
  75. package/dist/chunks/url-BcMYVCXQ.js.map +1 -0
  76. package/dist/chunks/url-D4PGsRm8.cjs +164 -0
  77. package/dist/chunks/url-D4PGsRm8.cjs.map +1 -0
  78. package/dist/chunks/url-DWdElCT3.d.cts +43 -0
  79. package/dist/chunks/url-DWdElCT3.d.ts +43 -0
  80. package/dist/chunks/url-vJaFPbNL.js +57 -0
  81. package/dist/chunks/url-vJaFPbNL.js.map +1 -0
  82. package/dist/code.cjs +22 -113
  83. package/dist/code.cjs.map +1 -1
  84. package/dist/code.d.cts +4 -28
  85. package/dist/code.d.ts +4 -28
  86. package/dist/code.js +5 -96
  87. package/dist/code.js.map +1 -1
  88. package/dist/color.cjs +21 -893
  89. package/dist/color.cjs.map +1 -1
  90. package/dist/color.d.cts +4 -28
  91. package/dist/color.d.ts +4 -28
  92. package/dist/color.js +4 -876
  93. package/dist/color.js.map +1 -1
  94. package/dist/core.cjs +52 -1659
  95. package/dist/core.d.cts +8 -878
  96. package/dist/core.d.ts +8 -878
  97. package/dist/core.js +7 -1614
  98. package/dist/image.cjs +23 -94
  99. package/dist/image.cjs.map +1 -1
  100. package/dist/image.d.cts +1 -0
  101. package/dist/image.d.ts +1 -0
  102. package/dist/image.js +3 -74
  103. package/dist/image.js.map +1 -1
  104. package/dist/index.cjs +74 -2072
  105. package/dist/index.cjs.map +1 -1
  106. package/dist/index.d.cts +8 -978
  107. package/dist/index.d.ts +8 -978
  108. package/dist/index.js +7 -2005
  109. package/dist/index.js.map +1 -1
  110. package/dist/link.cjs +26 -339
  111. package/dist/link.cjs.map +1 -1
  112. package/dist/link.d.cts +5 -83
  113. package/dist/link.d.ts +5 -83
  114. package/dist/link.js +7 -320
  115. package/dist/link.js.map +1 -1
  116. package/dist/markdown.cjs +19 -159
  117. package/dist/markdown.cjs.map +1 -1
  118. package/dist/markdown.d.cts +3 -16
  119. package/dist/markdown.d.ts +3 -16
  120. package/dist/markdown.js +6 -146
  121. package/dist/markdown.js.map +1 -1
  122. package/dist/rich.cjs +1123 -940
  123. package/dist/rich.cjs.map +1 -1
  124. package/dist/rich.d.cts +101 -91
  125. package/dist/rich.d.ts +101 -91
  126. package/dist/rich.js +1099 -919
  127. package/dist/rich.js.map +1 -1
  128. package/dist/share.cjs +5 -640
  129. package/dist/share.d.cts +3 -248
  130. package/dist/share.d.ts +3 -248
  131. package/dist/share.js +1 -637
  132. package/dist/structured.cjs +13 -95
  133. package/dist/structured.cjs.map +1 -1
  134. package/dist/structured.d.cts +2 -11
  135. package/dist/structured.d.ts +2 -11
  136. package/dist/structured.js +4 -86
  137. package/dist/structured.js.map +1 -1
  138. package/dist/table.cjs +13 -40
  139. package/dist/table.cjs.map +1 -1
  140. package/dist/table.d.cts +2 -12
  141. package/dist/table.d.ts +2 -12
  142. package/dist/table.js +4 -31
  143. package/dist/table.js.map +1 -1
  144. package/dist/testing.cjs +10 -43
  145. package/dist/testing.cjs.map +1 -1
  146. package/dist/testing.d.cts +6 -181
  147. package/dist/testing.d.ts +6 -181
  148. package/dist/testing.js +3 -36
  149. package/dist/testing.js.map +1 -1
  150. package/package.json +37 -5
  151. package/dist/core.cjs.map +0 -1
  152. package/dist/core.js.map +0 -1
  153. package/dist/share.cjs.map +0 -1
  154. package/dist/share.js.map +0 -1
package/dist/rich.d.cts CHANGED
@@ -1,22 +1,7 @@
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
1
+
2
+ import { o as HtmlPayload } from "./chunks/payload-CcwKJ_bU.cjs";
3
+ import { c as CopyInterceptTransform } from "./chunks/copy-interceptor-CZWzGOkL.cjs";
4
+ import { r as LinkUrlOptions } from "./chunks/url-DWdElCT3.cjs";
20
5
  //#region src/rich/style.d.ts
21
6
  /** Where styles come from: `getComputedStyle` for a live element, the `style` attribute otherwise. */
22
7
  interface StyleSource {
@@ -109,77 +94,6 @@ type RichSource = Element | DocumentFragment | Range | string;
109
94
  */
110
95
  export declare function prepareRich(source: RichSource, options?: RichOptions): RichResult;
111
96
  //#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
97
  //#region src/rich/payload.d.ts
184
98
  /**
185
99
  * Content to copy as portable rich text: the sanitized HTML, and its plain text for
@@ -208,5 +122,101 @@ export declare function richTransform(options?: RichOptions): CopyInterceptTrans
208
122
  */
209
123
  export declare function plainText(root: HTMLElement): string;
210
124
  //#endregion
211
- export type { RichColors, RichOptions, RichRemoval, RichRemovalReason, RichResult, RichSource, StyleSource };
125
+ //#region src/rich/paste.d.ts
126
+ /**
127
+ * What a destination can hold. A format left out of `formats` is written as the closest thing
128
+ * that is allowed, and its text is always kept:
129
+ *
130
+ * - `bold`, `italic`, `underline`, `strike`, `code`, `superscript`, `subscript`: the text, unformatted.
131
+ * - `link`: the link text. `image`: the image's alt text.
132
+ * - `heading`: a paragraph, in bold when `bold` is allowed.
133
+ * - `list`: a paragraph per item, after its marker (`\u2022`, `1.`).
134
+ * - `quote`: its paragraphs. `table`: a paragraph per cell, in reading order.
135
+ * - `codeBlock`: a paragraph per line, as inline code when `code` is allowed.
136
+ * - `rule`: nothing.
137
+ */
138
+ type RichPasteFormat = 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'superscript' | 'subscript' | 'link' | 'image' | 'heading' | 'list' | 'quote' | 'codeBlock' | 'table' | 'rule';
139
+ /** Every format, in the order the docs list them. */
140
+ export declare const RICH_PASTE_FORMATS: readonly RichPasteFormat[];
141
+ interface PasteToRichOptions extends Pick<RichOptions, 'protocols' | 'dataImages' | 'maxElements' | 'maxLength' | 'text'> {
142
+ /**
143
+ * What the destination can hold, such as an editor's schema or a comment box's toolbar.
144
+ * Default: every format. See {@link RichPasteFormat} for what happens to the rest.
145
+ */
146
+ readonly formats?: readonly RichPasteFormat[];
147
+ /**
148
+ * Resolves relative links and images, when you know where the content was copied from
149
+ * (your own site, say). Default: none, so relative links keep only their text: a pasted
150
+ * `/docs` would otherwise point into your site, not the one it came from.
151
+ */
152
+ readonly base?: string | URL;
153
+ /** Most nodes of the pasted HTML read; the rest is left out and `truncated` is set. Default 200,000. */
154
+ readonly maxNodes?: number;
155
+ }
156
+ /** Cleaned rich content: semantic HTML, its plain text, and what was left out. */
157
+ interface RichPaste extends RichResult {
158
+ /** `html` when cleaned from the rich flavour; `text` when built from plain text (paragraphs and line breaks). */
159
+ readonly source: 'html' | 'text';
160
+ }
161
+ /** The clipboard flavours: a `PasteResult` from `usePaste`, or anything with `html` / `text`. */
162
+ interface RichPasteSource {
163
+ readonly html?: string | null;
164
+ readonly text?: string | null;
165
+ }
166
+ /**
167
+ * Cleans what was pasted into semantic, safe HTML for a rich-text editor: the HTML Google Docs,
168
+ * Word, Outlook, Gmail, Notion and web pages put on the clipboard becomes paragraphs, headings,
169
+ * lists, quotes, code blocks, tables, links and images, with bold, italic, underline,
170
+ * strikethrough, code, superscript and subscript as tags (`<strong>`, `<em>`, ...).
171
+ *
172
+ * - Formatting set by CSS (`font-weight: 700`, `font-style: italic`) becomes tags, and every
173
+ * style, class and id is left out: pasted content takes the editor's look, not the source's.
174
+ * - Word's paragraph lists become real lists; Google Docs' wrappers, empty spacers and hidden
175
+ * markers go. Layout tables (mail) become their content.
176
+ * - The output is canonical (the same content always gives the same HTML) and goes through the
177
+ * same sanitizer as {@link prepareRich}: only allowlisted elements and attributes, links and
178
+ * images with absolute, scheme-checked URLs. `removed` says what was left out.
179
+ * - `formats` limits the output to what your editor holds, keeping all of the text.
180
+ *
181
+ * Plain text (no HTML on the clipboard) becomes paragraphs and line breaks. Returns `null` when
182
+ * there is nothing to paste. HTML needs `DOMParser` (any browser, or jsdom); without one, the
183
+ * plain text is used.
184
+ *
185
+ * @example
186
+ * // TipTap / ProseMirror
187
+ * editorProps: { transformPastedHTML: (html) => pasteToRich({ html })?.html ?? '' }
188
+ */
189
+ export declare function pasteToRich(source: RichPasteSource, options?: PasteToRichOptions): RichPaste | null;
190
+ /** Structural paste event: a DOM `ClipboardEvent` and React's `onPaste` event both fit. */
191
+ interface RichPasteEvent {
192
+ readonly clipboardData: {
193
+ getData(format: string): string;
194
+ } | null;
195
+ readonly currentTarget: EventTarget | null;
196
+ readonly target: EventTarget | null;
197
+ readonly defaultPrevented: boolean;
198
+ preventDefault(): void;
199
+ }
200
+ interface PasteAsRichOptions extends PasteToRichOptions {
201
+ /**
202
+ * Called with the cleaned content before it is inserted. Return `false` to insert it yourself
203
+ * (through your editor's API, say): the browser's paste is still prevented.
204
+ */
205
+ readonly onPaste?: (pasted: RichPaste) => boolean | undefined;
206
+ }
207
+ /**
208
+ * A paste handler for `contenteditable` elements: what is pasted from Google Docs, Word, mail or
209
+ * a web page goes in as clean, semantic HTML (see {@link pasteToRich}), with undo intact. Plain-text
210
+ * pastes are left to the browser. Returns whether it handled the paste.
211
+ *
212
+ * Rich-text editors (TipTap, ProseMirror, Lexical, Quill) have their own paste pipelines: use
213
+ * {@link pasteToRich} in their hook instead, so the editor keeps its document model.
214
+ *
215
+ * @example
216
+ * <div contentEditable onPaste={pasteAsRich} />
217
+ * <div contentEditable onPaste={(event) => pasteAsRich(event, { formats: ['bold', 'italic', 'link', 'list'] })} />
218
+ */
219
+ export declare function pasteAsRich(event: RichPasteEvent, options?: PasteAsRichOptions): boolean;
220
+ //#endregion
221
+ export type { PasteAsRichOptions, PasteToRichOptions, RichColors, RichOptions, RichPaste, RichPasteEvent, RichPasteFormat, RichPasteSource, RichRemoval, RichRemovalReason, RichResult, RichSource, StyleSource };
212
222
  //# sourceMappingURL=rich.d.cts.map
package/dist/rich.d.ts CHANGED
@@ -1,22 +1,7 @@
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
1
+
2
+ import { o as HtmlPayload } from "./chunks/payload-Cl_8hCI5.js";
3
+ import { c as CopyInterceptTransform } from "./chunks/copy-interceptor-C6NABy1l.js";
4
+ import { r as LinkUrlOptions } from "./chunks/url-DWdElCT3.js";
20
5
  //#region src/rich/style.d.ts
21
6
  /** Where styles come from: `getComputedStyle` for a live element, the `style` attribute otherwise. */
22
7
  interface StyleSource {
@@ -109,77 +94,6 @@ type RichSource = Element | DocumentFragment | Range | string;
109
94
  */
110
95
  export declare function prepareRich(source: RichSource, options?: RichOptions): RichResult;
111
96
  //#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
97
  //#region src/rich/payload.d.ts
184
98
  /**
185
99
  * Content to copy as portable rich text: the sanitized HTML, and its plain text for
@@ -208,5 +122,101 @@ export declare function richTransform(options?: RichOptions): CopyInterceptTrans
208
122
  */
209
123
  export declare function plainText(root: HTMLElement): string;
210
124
  //#endregion
211
- export type { RichColors, RichOptions, RichRemoval, RichRemovalReason, RichResult, RichSource, StyleSource };
125
+ //#region src/rich/paste.d.ts
126
+ /**
127
+ * What a destination can hold. A format left out of `formats` is written as the closest thing
128
+ * that is allowed, and its text is always kept:
129
+ *
130
+ * - `bold`, `italic`, `underline`, `strike`, `code`, `superscript`, `subscript`: the text, unformatted.
131
+ * - `link`: the link text. `image`: the image's alt text.
132
+ * - `heading`: a paragraph, in bold when `bold` is allowed.
133
+ * - `list`: a paragraph per item, after its marker (`\u2022`, `1.`).
134
+ * - `quote`: its paragraphs. `table`: a paragraph per cell, in reading order.
135
+ * - `codeBlock`: a paragraph per line, as inline code when `code` is allowed.
136
+ * - `rule`: nothing.
137
+ */
138
+ type RichPasteFormat = 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'superscript' | 'subscript' | 'link' | 'image' | 'heading' | 'list' | 'quote' | 'codeBlock' | 'table' | 'rule';
139
+ /** Every format, in the order the docs list them. */
140
+ export declare const RICH_PASTE_FORMATS: readonly RichPasteFormat[];
141
+ interface PasteToRichOptions extends Pick<RichOptions, 'protocols' | 'dataImages' | 'maxElements' | 'maxLength' | 'text'> {
142
+ /**
143
+ * What the destination can hold, such as an editor's schema or a comment box's toolbar.
144
+ * Default: every format. See {@link RichPasteFormat} for what happens to the rest.
145
+ */
146
+ readonly formats?: readonly RichPasteFormat[];
147
+ /**
148
+ * Resolves relative links and images, when you know where the content was copied from
149
+ * (your own site, say). Default: none, so relative links keep only their text: a pasted
150
+ * `/docs` would otherwise point into your site, not the one it came from.
151
+ */
152
+ readonly base?: string | URL;
153
+ /** Most nodes of the pasted HTML read; the rest is left out and `truncated` is set. Default 200,000. */
154
+ readonly maxNodes?: number;
155
+ }
156
+ /** Cleaned rich content: semantic HTML, its plain text, and what was left out. */
157
+ interface RichPaste extends RichResult {
158
+ /** `html` when cleaned from the rich flavour; `text` when built from plain text (paragraphs and line breaks). */
159
+ readonly source: 'html' | 'text';
160
+ }
161
+ /** The clipboard flavours: a `PasteResult` from `usePaste`, or anything with `html` / `text`. */
162
+ interface RichPasteSource {
163
+ readonly html?: string | null;
164
+ readonly text?: string | null;
165
+ }
166
+ /**
167
+ * Cleans what was pasted into semantic, safe HTML for a rich-text editor: the HTML Google Docs,
168
+ * Word, Outlook, Gmail, Notion and web pages put on the clipboard becomes paragraphs, headings,
169
+ * lists, quotes, code blocks, tables, links and images, with bold, italic, underline,
170
+ * strikethrough, code, superscript and subscript as tags (`<strong>`, `<em>`, ...).
171
+ *
172
+ * - Formatting set by CSS (`font-weight: 700`, `font-style: italic`) becomes tags, and every
173
+ * style, class and id is left out: pasted content takes the editor's look, not the source's.
174
+ * - Word's paragraph lists become real lists; Google Docs' wrappers, empty spacers and hidden
175
+ * markers go. Layout tables (mail) become their content.
176
+ * - The output is canonical (the same content always gives the same HTML) and goes through the
177
+ * same sanitizer as {@link prepareRich}: only allowlisted elements and attributes, links and
178
+ * images with absolute, scheme-checked URLs. `removed` says what was left out.
179
+ * - `formats` limits the output to what your editor holds, keeping all of the text.
180
+ *
181
+ * Plain text (no HTML on the clipboard) becomes paragraphs and line breaks. Returns `null` when
182
+ * there is nothing to paste. HTML needs `DOMParser` (any browser, or jsdom); without one, the
183
+ * plain text is used.
184
+ *
185
+ * @example
186
+ * // TipTap / ProseMirror
187
+ * editorProps: { transformPastedHTML: (html) => pasteToRich({ html })?.html ?? '' }
188
+ */
189
+ export declare function pasteToRich(source: RichPasteSource, options?: PasteToRichOptions): RichPaste | null;
190
+ /** Structural paste event: a DOM `ClipboardEvent` and React's `onPaste` event both fit. */
191
+ interface RichPasteEvent {
192
+ readonly clipboardData: {
193
+ getData(format: string): string;
194
+ } | null;
195
+ readonly currentTarget: EventTarget | null;
196
+ readonly target: EventTarget | null;
197
+ readonly defaultPrevented: boolean;
198
+ preventDefault(): void;
199
+ }
200
+ interface PasteAsRichOptions extends PasteToRichOptions {
201
+ /**
202
+ * Called with the cleaned content before it is inserted. Return `false` to insert it yourself
203
+ * (through your editor's API, say): the browser's paste is still prevented.
204
+ */
205
+ readonly onPaste?: (pasted: RichPaste) => boolean | undefined;
206
+ }
207
+ /**
208
+ * A paste handler for `contenteditable` elements: what is pasted from Google Docs, Word, mail or
209
+ * a web page goes in as clean, semantic HTML (see {@link pasteToRich}), with undo intact. Plain-text
210
+ * pastes are left to the browser. Returns whether it handled the paste.
211
+ *
212
+ * Rich-text editors (TipTap, ProseMirror, Lexical, Quill) have their own paste pipelines: use
213
+ * {@link pasteToRich} in their hook instead, so the editor keeps its document model.
214
+ *
215
+ * @example
216
+ * <div contentEditable onPaste={pasteAsRich} />
217
+ * <div contentEditable onPaste={(event) => pasteAsRich(event, { formats: ['bold', 'italic', 'link', 'list'] })} />
218
+ */
219
+ export declare function pasteAsRich(event: RichPasteEvent, options?: PasteAsRichOptions): boolean;
220
+ //#endregion
221
+ export type { PasteAsRichOptions, PasteToRichOptions, RichColors, RichOptions, RichPaste, RichPasteEvent, RichPasteFormat, RichPasteSource, RichRemoval, RichRemovalReason, RichResult, RichSource, StyleSource };
212
222
  //# sourceMappingURL=rich.d.ts.map