react-smart-copy 1.10.0 → 1.11.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/README.md CHANGED
@@ -27,6 +27,7 @@ ID PLT-29018 [Copy]
27
27
  - **`useCopyInterceptor`**: control what Ctrl/⌘+C copies from your page — attribution, redaction, Excel-ready tables, no-copy zones
28
28
  - **`react-smart-copy/table`**: copy rows that paste into Excel and Google Sheets as cells, and read pasted ranges back as typed records. Works with AG Grid, TanStack Table and any `<table>`
29
29
  - **`react-smart-copy/structured`**: copy your own objects and paste them back as the same typed, validated objects in another tab or app, the way design tools do. Versioned, with migrations, and works with Zod, Valibot or ArkType
30
+ - **`react-smart-copy/markdown`**: paste from Google Docs, Word, Notion or any web page into a Markdown field and get clean Markdown, with undo intact: `<textarea onPaste={pasteAsMarkdown} />`
30
31
  - **`react-smart-copy/capture`**: copy an `<svg>` or any piece of your UI as a PNG
31
32
  - Every failure is a typed, classified error. Nothing silently no-ops
32
33
  - Unstyled. Works with Tailwind, CSS modules, CSS-in-JS, shadcn, MUI, Ant Design
@@ -45,6 +46,7 @@ This package only promises what browsers actually support.
45
46
  | Tables (Excel, Sheets, Docs) | ✅ | `react-smart-copy/table`: an HTML table plus tab-separated text in one entry. Pasting reads both back |
46
47
  | Several formats at once | ✅ | `kind: 'multi'`; each MIME type is checked with `ClipboardItem.supports()` first |
47
48
  | Your app's own data (typed) | ✅ | `react-smart-copy/structured`: a web custom format, a custom type and an HTML envelope, so every browser and paste path gets one |
49
+ | Rich text as Markdown | ✅ paste | `react-smart-copy/markdown`: CommonMark + GFM from Docs, Word, web pages and mail; plain-text pastes stay untouched |
48
50
  | SVG (icons, charts, logos) | ✅ as PNG | `svgToPngBlob()` from `react-smart-copy/capture` rasterises natively, no dependency. Raw SVG is not a clipboard image format |
49
51
  | A section of your UI as an image | ✅ bring a rasteriser | Browsers have no "screenshot this element" API. `captureElement()` wraps one you choose (e.g. `modern-screenshot`) with limits and checks |
50
52
  | Files (PDF, DOCX, ZIP) | ❌ | Not writable to the system clipboard by any browser API |
@@ -606,6 +608,73 @@ the data is never trusted, only checked.
606
608
  instead of turning silently into `null` or `{}`. Dates become ISO strings, so read them back with a
607
609
  coercing schema (`z.coerce.date()`), or convert in `encode`.
608
610
 
611
+ ## Paste as Markdown
612
+
613
+ `react-smart-copy/markdown` turns what people paste into comment boxes, editors and CMS
614
+ fields into clean Markdown: headings, bold and italic, links, lists (nested and task
615
+ lists), tables, code blocks and quotes, from Google Docs, Word, Notion, GitHub, web pages
616
+ and mail. No dependencies, about 7.3 kB.
617
+
618
+ ```tsx
619
+ import { pasteAsMarkdown } from "react-smart-copy/markdown";
620
+
621
+ <textarea value={body} onChange={(event) => setBody(event.target.value)} onPaste={pasteAsMarkdown} />
622
+ ```
623
+
624
+ That one handler:
625
+
626
+ - converts rich pastes (the HTML flavour) and inserts the Markdown at the cursor, replacing the selection
627
+ - keeps the browser's **undo** (Ctrl/⌘+Z undoes the paste), fires `input` so React state follows, respects `maxlength`
628
+ - leaves **plain-text pastes alone**, because plain text pasted into a Markdown field is usually Markdown already, and leaves code from editors (VS Code, JetBrains) as plain code
629
+ - in a single-line `<input>`, joins the result into one line
630
+
631
+ Pass options with `onPaste={(event) => pasteAsMarkdown(event, { images: "keep" })}`.
632
+ For other flows, the pieces are separate:
633
+
634
+ ```ts
635
+ import { escapeMarkdown, htmlToMarkdown, insertText, pasteToMarkdown } from "react-smart-copy/markdown";
636
+
637
+ // With usePaste or PasteField: Markdown for a paste result (plain text stays as it is).
638
+ const pasted = pasteToMarkdown(result); // { markdown, source: "html" | "text", truncated } | null
639
+ if (pasted) insertText(textarea, pasted.markdown);
640
+
641
+ // Copy a rendered article as Markdown (a DOM node is converted in place, not re-parsed).
642
+ copy(() => htmlToMarkdown(articleRef.current).markdown);
643
+
644
+ // Any text, rendered literally by any Markdown renderer.
645
+ escapeMarkdown("1. *Not* a list <b>"); // "1\\. \\*Not\\* a list \\<b>"
646
+ ```
647
+
648
+ **What real clipboards look like, handled.** Google Docs sets bold and italic with CSS on
649
+ spans, wraps everything in a non-bold `<b>`, nests lists as siblings and wraps links in
650
+ `google.com/url?q=` redirects. Word writes lists as `mso-list` paragraphs with hidden
651
+ markers. Mail clients use `<div>` per line and layout tables. Spreadsheets and Docs tables
652
+ become GFM tables, merged cells included.
653
+
654
+ **Correct by construction.** Every delimiter the converter writes is checked with
655
+ CommonMark's own pairing algorithm before it is kept, so text always renders as the same
656
+ text: where CommonMark can't express a style (`x**[y]**z`), the style is dropped, never the
657
+ text, and asterisks never leak into the output. Property tests render thousands of random
658
+ documents with a CommonMark parser and compare the result character by character.
659
+
660
+ **Security.** Pasted HTML is untrusted, so:
661
+
662
+ - it is parsed in an inert document: scripts never run and nothing is fetched, not even images
663
+ - the output never contains raw HTML: any `<` in the text is escaped
664
+ - links keep only `http:`, `https:` and `mailto:` (`linkProtocols`); `javascript:`, `data:` and relative links keep only their text
665
+ - images default to their alt text (`images: "alt"`), so rendering the Markdown loads no tracking pixels. `"keep"` writes `![alt](url)` for `https:`/`http:` images, `"drop"` removes them
666
+ - `maxLength` (16 MiB), `maxNodes` (200,000) and `maxDepth` (200) bound the work; content left out sets `truncated: true`, and merged-cell expansion is capped
667
+
668
+ | Option | Default | |
669
+ | ------ | ------- | - |
670
+ | `images` | `"alt"` | `"alt"`, `"keep"` or `"drop"` |
671
+ | `links` | `"keep"` | `"text"` keeps only the link text |
672
+ | `linkProtocols` / `imageProtocols` | `http(s)`, `mailto` / `https`, `http` | allowed URL schemes |
673
+ | `baseUrl` | none | resolves relative links and images |
674
+ | `bullet` | `"-"` | `"*"` or `"+"` |
675
+ | `hardBreak` | `"backslash"` | `"spaces"` for two trailing spaces |
676
+ | `codeAsText` (paste) | `true` | `false` turns code-only pastes into fenced code blocks |
677
+
609
678
  ## Only one "Copied" at a time
610
679
 
611
680
  Wrap a table or list in `<CopyGroup>`. A new successful copy returns the previously copied
@@ -1053,7 +1122,8 @@ embedded webviews. Where a capability is missing you get a typed error, never a
1053
1122
  - ~~**1.7** `useCopyInterceptor` / `registerCopyInterceptor` — attribution, redaction and no-copy zones for native Ctrl/⌘+C~~ shipped
1054
1123
  - ~~**1.8** `useDragCopy` / `registerDragCopy` — populate `DataTransfer` on drag-start; no Clipboard API needed~~ shipped
1055
1124
  - ~~**1.9** `react-smart-copy/table` — Excel- and Sheets-ready copy and paste, AG Grid and TanStack Table adapters, typed record import~~ shipped
1056
- - **1.10** `react-smart-copy/structured` — typed, versioned, validated application data on the clipboard
1125
+ - ~~**1.10** `react-smart-copy/structured` — typed, versioned, validated application data on the clipboard~~ shipped
1126
+ - **1.11** `react-smart-copy/markdown` — paste rich content as Markdown, with undo intact
1057
1127
 
1058
1128
  Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/#releases).
1059
1129
 
@@ -1061,7 +1131,7 @@ Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://supr
1061
1131
 
1062
1132
  ```bash
1063
1133
  npm install
1064
- npm run verify # lint, types, 988 tests at 100% coverage, build, publint + attw, size budgets
1134
+ npm run verify # lint, types, 1,100+ tests at 100% coverage, build, publint + attw, size budgets
1065
1135
  npm run changeset # describe your change for the changelog
1066
1136
  npm run site:preview # docs site at http://localhost:3000
1067
1137
  ```