react-smart-copy 1.18.0 → 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/dist/rich.d.cts CHANGED
@@ -122,5 +122,101 @@ export declare function richTransform(options?: RichOptions): CopyInterceptTrans
122
122
  */
123
123
  export declare function plainText(root: HTMLElement): string;
124
124
  //#endregion
125
- 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 };
126
222
  //# sourceMappingURL=rich.d.cts.map
package/dist/rich.d.ts CHANGED
@@ -122,5 +122,101 @@ export declare function richTransform(options?: RichOptions): CopyInterceptTrans
122
122
  */
123
123
  export declare function plainText(root: HTMLElement): string;
124
124
  //#endregion
125
- 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 };
126
222
  //# sourceMappingURL=rich.d.ts.map