react-smart-copy 1.10.0 → 1.12.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 +154 -2
- package/dist/code.cjs +1129 -0
- package/dist/code.cjs.map +1 -0
- package/dist/code.d.cts +292 -0
- package/dist/code.d.ts +292 -0
- package/dist/code.js +1117 -0
- package/dist/code.js.map +1 -0
- package/dist/markdown.cjs +1407 -0
- package/dist/markdown.cjs.map +1 -0
- package/dist/markdown.d.cts +150 -0
- package/dist/markdown.d.ts +150 -0
- package/dist/markdown.js +1397 -0
- package/dist/markdown.js.map +1 -0
- package/package.json +73 -4
package/README.md
CHANGED
|
@@ -27,6 +27,8 @@ 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} />`
|
|
31
|
+
- **`react-smart-copy/code`**: copy code blocks the way developers expect (a terminal session copies as its commands, gutters and prompts stay behind, colours survive in Docs and Slack), paste code cleaned and indented, and catch Trojan Source, invisible identifiers and lookalike letters
|
|
30
32
|
- **`react-smart-copy/capture`**: copy an `<svg>` or any piece of your UI as a PNG
|
|
31
33
|
- Every failure is a typed, classified error. Nothing silently no-ops
|
|
32
34
|
- Unstyled. Works with Tailwind, CSS modules, CSS-in-JS, shadcn, MUI, Ant Design
|
|
@@ -45,6 +47,8 @@ This package only promises what browsers actually support.
|
|
|
45
47
|
| Tables (Excel, Sheets, Docs) | ✅ | `react-smart-copy/table`: an HTML table plus tab-separated text in one entry. Pasting reads both back |
|
|
46
48
|
| Several formats at once | ✅ | `kind: 'multi'`; each MIME type is checked with `ClipboardItem.supports()` first |
|
|
47
49
|
| 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 |
|
|
50
|
+
| Rich text as Markdown | ✅ paste | `react-smart-copy/markdown`: CommonMark + GFM from Docs, Word, web pages and mail; plain-text pastes stay untouched |
|
|
51
|
+
| Code (blocks, sessions, diffs) | ✅ | `react-smart-copy/code`: plain text plus monospaced, highlighted HTML; commands without prompts or output; Trojan Source checks on paste |
|
|
48
52
|
| 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
53
|
| 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
54
|
| Files (PDF, DOCX, ZIP) | ❌ | Not writable to the system clipboard by any browser API |
|
|
@@ -606,6 +610,152 @@ the data is never trusted, only checked.
|
|
|
606
610
|
instead of turning silently into `null` or `{}`. Dates become ISO strings, so read them back with a
|
|
607
611
|
coercing schema (`z.coerce.date()`), or convert in `encode`.
|
|
608
612
|
|
|
613
|
+
## Paste as Markdown
|
|
614
|
+
|
|
615
|
+
`react-smart-copy/markdown` turns what people paste into comment boxes, editors and CMS
|
|
616
|
+
fields into clean Markdown: headings, bold and italic, links, lists (nested and task
|
|
617
|
+
lists), tables, code blocks and quotes, from Google Docs, Word, Notion, GitHub, web pages
|
|
618
|
+
and mail. No dependencies, about 7.3 kB.
|
|
619
|
+
|
|
620
|
+
```tsx
|
|
621
|
+
import { pasteAsMarkdown } from "react-smart-copy/markdown";
|
|
622
|
+
|
|
623
|
+
<textarea value={body} onChange={(event) => setBody(event.target.value)} onPaste={pasteAsMarkdown} />
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
That one handler:
|
|
627
|
+
|
|
628
|
+
- converts rich pastes (the HTML flavour) and inserts the Markdown at the cursor, replacing the selection
|
|
629
|
+
- keeps the browser's **undo** (Ctrl/⌘+Z undoes the paste), fires `input` so React state follows, respects `maxlength`
|
|
630
|
+
- 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
|
|
631
|
+
- in a single-line `<input>`, joins the result into one line
|
|
632
|
+
|
|
633
|
+
Pass options with `onPaste={(event) => pasteAsMarkdown(event, { images: "keep" })}`.
|
|
634
|
+
For other flows, the pieces are separate:
|
|
635
|
+
|
|
636
|
+
```ts
|
|
637
|
+
import { escapeMarkdown, htmlToMarkdown, insertText, pasteToMarkdown } from "react-smart-copy/markdown";
|
|
638
|
+
|
|
639
|
+
// With usePaste or PasteField: Markdown for a paste result (plain text stays as it is).
|
|
640
|
+
const pasted = pasteToMarkdown(result); // { markdown, source: "html" | "text", truncated } | null
|
|
641
|
+
if (pasted) insertText(textarea, pasted.markdown);
|
|
642
|
+
|
|
643
|
+
// Copy a rendered article as Markdown (a DOM node is converted in place, not re-parsed).
|
|
644
|
+
copy(() => htmlToMarkdown(articleRef.current).markdown);
|
|
645
|
+
|
|
646
|
+
// Any text, rendered literally by any Markdown renderer.
|
|
647
|
+
escapeMarkdown("1. *Not* a list <b>"); // "1\\. \\*Not\\* a list \\<b>"
|
|
648
|
+
```
|
|
649
|
+
|
|
650
|
+
**What real clipboards look like, handled.** Google Docs sets bold and italic with CSS on
|
|
651
|
+
spans, wraps everything in a non-bold `<b>`, nests lists as siblings and wraps links in
|
|
652
|
+
`google.com/url?q=` redirects. Word writes lists as `mso-list` paragraphs with hidden
|
|
653
|
+
markers. Mail clients use `<div>` per line and layout tables. Spreadsheets and Docs tables
|
|
654
|
+
become GFM tables, merged cells included.
|
|
655
|
+
|
|
656
|
+
**Correct by construction.** Every delimiter the converter writes is checked with
|
|
657
|
+
CommonMark's own pairing algorithm before it is kept, so text always renders as the same
|
|
658
|
+
text: where CommonMark can't express a style (`x**[y]**z`), the style is dropped, never the
|
|
659
|
+
text, and asterisks never leak into the output. Property tests render thousands of random
|
|
660
|
+
documents with a CommonMark parser and compare the result character by character.
|
|
661
|
+
|
|
662
|
+
**Security.** Pasted HTML is untrusted, so:
|
|
663
|
+
|
|
664
|
+
- it is parsed in an inert document: scripts never run and nothing is fetched, not even images
|
|
665
|
+
- the output never contains raw HTML: any `<` in the text is escaped
|
|
666
|
+
- links keep only `http:`, `https:` and `mailto:` (`linkProtocols`); `javascript:`, `data:` and relative links keep only their text
|
|
667
|
+
- images default to their alt text (`images: "alt"`), so rendering the Markdown loads no tracking pixels. `"keep"` writes `` for `https:`/`http:` images, `"drop"` removes them
|
|
668
|
+
- `maxLength` (16 MiB), `maxNodes` (200,000) and `maxDepth` (200) bound the work; content left out sets `truncated: true`, and merged-cell expansion is capped
|
|
669
|
+
|
|
670
|
+
| Option | Default | |
|
|
671
|
+
| ------ | ------- | - |
|
|
672
|
+
| `images` | `"alt"` | `"alt"`, `"keep"` or `"drop"` |
|
|
673
|
+
| `links` | `"keep"` | `"text"` keeps only the link text |
|
|
674
|
+
| `linkProtocols` / `imageProtocols` | `http(s)`, `mailto` / `https`, `http` | allowed URL schemes |
|
|
675
|
+
| `baseUrl` | none | resolves relative links and images |
|
|
676
|
+
| `bullet` | `"-"` | `"*"` or `"+"` |
|
|
677
|
+
| `hardBreak` | `"backslash"` | `"spaces"` for two trailing spaces |
|
|
678
|
+
| `codeAsText` (paste) | `true` | `false` turns code-only pastes into fenced code blocks |
|
|
679
|
+
|
|
680
|
+
## Copy and paste code
|
|
681
|
+
|
|
682
|
+
`react-smart-copy/code` is for the copy button on every code block and for fields people
|
|
683
|
+
paste code into. It also catches code that reads differently from how it runs. No
|
|
684
|
+
dependencies, about 7.4 kB (`inspectCode` alone is about 2.5 kB).
|
|
685
|
+
|
|
686
|
+
```tsx
|
|
687
|
+
import { useCopy } from "react-smart-copy";
|
|
688
|
+
import { codePayload } from "react-smart-copy/code";
|
|
689
|
+
|
|
690
|
+
const { copy, status } = useCopy();
|
|
691
|
+
<pre ref={preRef}>…</pre>
|
|
692
|
+
<button onClick={() => copy(() => codePayload(preRef.current!, { language: "tsx" }))}>Copy</button>
|
|
693
|
+
```
|
|
694
|
+
|
|
695
|
+
What gets copied is the code the reader means to run:
|
|
696
|
+
|
|
697
|
+
- **A terminal or REPL session copies as its commands.** `$ npm test` followed by its output copies as `npm test`. Prompts from `bash`/`zsh` (`$`, `user@host:~$`, `(venv) $`), PowerShell, `cmd`, Python, IPython and Node are recognised. Continued commands stay whole: a trailing `\`, a heredoc or an open quote. `prompt: "auto"` (the default) only acts when the first line starts with a prompt
|
|
698
|
+
- **A highlighted block copies without its chrome.** Line-number gutters (Prism, highlight.js, Rouge, react-syntax-highlighter and others), `user-select: none` and `aria-hidden` parts, hidden parts, buttons and anything with `data-copy-ignore` are left out. `ignore` takes a CSS selector for more
|
|
699
|
+
- **It pastes well everywhere.** Plain text for editors and terminals, plus monospaced HTML with the block's syntax colours for Google Docs, Word, Slack, Teams and mail. Both flavours always hold the same code
|
|
700
|
+
- **Diffs, line numbers, indentation.** `diff: "after"` (or `"before"`) copies one side of a unified diff. `lineNumbers: true` removes typed line numbers when they count up on every line. Shared indentation, trailing whitespace and blank edges are removed, and line endings are normalised (`lineEnding: "crlf"` for Windows)
|
|
701
|
+
|
|
702
|
+
For a code field, `pasteAsCode` is a ready paste handler:
|
|
703
|
+
|
|
704
|
+
```tsx
|
|
705
|
+
import { pasteAsCode } from "react-smart-copy/code";
|
|
706
|
+
|
|
707
|
+
<textarea onPaste={pasteAsCode} />
|
|
708
|
+
<textarea onPaste={(event) => pasteAsCode(event, { onPaste: (r) => !r.danger || confirm("Paste anyway?") })} />
|
|
709
|
+
```
|
|
710
|
+
|
|
711
|
+
It fixes what chat apps and word processors do to code (curly quotes, `—` for `--`,
|
|
712
|
+
no-break spaces, zero-width characters) and dedents the paste. Each line after the first is
|
|
713
|
+
indented to the cursor line, as code editors do. The paste is one step on the browser's
|
|
714
|
+
undo stack. `onPaste` sees every finding first and can cancel. For CodeMirror, Monaco or
|
|
715
|
+
`usePaste`, `pasteToCode(result)` returns the same `{ code, findings, fixed, remaining, danger }`.
|
|
716
|
+
|
|
717
|
+
**Security: code that runs differently from how it reads.** `inspectCode` reports, with
|
|
718
|
+
line, column and a label such as `U+202E RIGHT-TO-LEFT OVERRIDE`:
|
|
719
|
+
|
|
720
|
+
| Kind | Severity | What it catches |
|
|
721
|
+
| ---- | -------- | --------------- |
|
|
722
|
+
| `bidi-control` | danger | Trojan Source ([CVE-2021-42574](https://trojansource.codes/)): overrides and isolates that reorder how code is shown. Implicit marks are a warning |
|
|
723
|
+
| `invisible` | danger / warning | Hangul fillers that make invisible identifiers, and tag characters that hide ASCII (including hidden instructions in prompts) are danger. Zero-width spaces, joiners outside words and emoji, and runs of variation selectors that smuggle data are warnings |
|
|
724
|
+
| `mixed-script` | danger / warning | A Cyrillic or Greek letter inside a Latin word (`аdmin` with a Cyrillic `а`). A Latin lookalike is danger; another letter is a warning |
|
|
725
|
+
| `control` | warning | Control characters other than tab, line feed, carriage return and form feed, and Unicode line separators |
|
|
726
|
+
| `unusual-space` | warning | No-break, em, ideographic and similar spaces |
|
|
727
|
+
| `confusable-punctuation` | warning | Curly quotes, dashes, `…`, the Greek question mark that looks like `;`, full-width punctuation outside CJK text |
|
|
728
|
+
|
|
729
|
+
Joiners inside Arabic, Persian or Indic words and emoji, a single emoji variation
|
|
730
|
+
selector, and full-width punctuation in CJK comments are left alone. `cleanCode` applies
|
|
731
|
+
the safe replacement of every finding. It runs until nothing fixable is left, because
|
|
732
|
+
removing a zero-width space can expose a mixed word. It never guesses a letter that has no
|
|
733
|
+
Latin lookalike; those stay in `remaining`. Copying doesn't clean by default
|
|
734
|
+
(`clean: true` turns it on). Pasting does (`clean: false` turns it off).
|
|
735
|
+
|
|
736
|
+
```ts
|
|
737
|
+
import { cleanCode, inspectCode, normalizeCode } from "react-smart-copy/code";
|
|
738
|
+
|
|
739
|
+
inspectCode(source).danger; // true for Trojan Source, lookalikes, invisible identifiers
|
|
740
|
+
cleanCode("const s = “hi”;").code; // 'const s = "hi";'
|
|
741
|
+
normalizeCode("$ npm i\nadded 1 package"); // "npm i" (also works on the server)
|
|
742
|
+
```
|
|
743
|
+
|
|
744
|
+
Pasted code is never cut: past `maxLength` (2,000,000 characters) `pasteToCode` throws a
|
|
745
|
+
`too-large` error, and `pasteAsCode` leaves the paste to the browser. HTML is parsed
|
|
746
|
+
inertly and only its text is used.
|
|
747
|
+
|
|
748
|
+
| Option | Default | |
|
|
749
|
+
| ------ | ------- | - |
|
|
750
|
+
| `prompt` | `"auto"` copy, `false` paste | a style (`"shell"`, `"powershell"`, `"cmd"`, `"python"`, `"ipython"`, `"node"`), `{ command, continuation }` regexes, or `false` |
|
|
751
|
+
| `diff` | `false` | `"after"` or `"before"` |
|
|
752
|
+
| `lineNumbers` | `false` | remove typed line numbers that count up |
|
|
753
|
+
| `dedent` / `trimTrailingWhitespace` / `trimBlankLines` | `true` | |
|
|
754
|
+
| `lineEnding` / `finalNewline` | `"lf"` / `false` | |
|
|
755
|
+
| `clean` | `false` copy, `true` paste | `true`, `false` or a list of kinds |
|
|
756
|
+
| `html` / `language` (copy) | `true` / none | add the HTML flavour; `class="language-…"` on `<code>` |
|
|
757
|
+
| `indentToCursor` / `onPaste` (`pasteAsCode`) | `true` / none | |
|
|
758
|
+
|
|
609
759
|
## Only one "Copied" at a time
|
|
610
760
|
|
|
611
761
|
Wrap a table or list in `<CopyGroup>`. A new successful copy returns the previously copied
|
|
@@ -1053,7 +1203,9 @@ embedded webviews. Where a capability is missing you get a typed error, never a
|
|
|
1053
1203
|
- ~~**1.7** `useCopyInterceptor` / `registerCopyInterceptor` — attribution, redaction and no-copy zones for native Ctrl/⌘+C~~ shipped
|
|
1054
1204
|
- ~~**1.8** `useDragCopy` / `registerDragCopy` — populate `DataTransfer` on drag-start; no Clipboard API needed~~ shipped
|
|
1055
1205
|
- ~~**1.9** `react-smart-copy/table` — Excel- and Sheets-ready copy and paste, AG Grid and TanStack Table adapters, typed record import~~ shipped
|
|
1056
|
-
-
|
|
1206
|
+
- ~~**1.10** `react-smart-copy/structured` — typed, versioned, validated application data on the clipboard~~ shipped
|
|
1207
|
+
- ~~**1.11** `react-smart-copy/markdown` — paste rich content as Markdown, with undo intact~~ shipped
|
|
1208
|
+
- **1.12** `react-smart-copy/code` — copy code blocks and sessions cleanly, paste code safely, detect Trojan Source and homoglyphs
|
|
1057
1209
|
|
|
1058
1210
|
Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/#releases).
|
|
1059
1211
|
|
|
@@ -1061,7 +1213,7 @@ Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://supr
|
|
|
1061
1213
|
|
|
1062
1214
|
```bash
|
|
1063
1215
|
npm install
|
|
1064
|
-
npm run verify # lint, types,
|
|
1216
|
+
npm run verify # lint, types, 1,100+ tests at 100% coverage, build, publint + attw, size budgets
|
|
1065
1217
|
npm run changeset # describe your change for the changelog
|
|
1066
1218
|
npm run site:preview # docs site at http://localhost:3000
|
|
1067
1219
|
```
|