react-smart-copy 1.13.2 → 1.14.1

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
@@ -3,6 +3,8 @@
3
3
  [![npm](https://img.shields.io/npm/v/react-smart-copy)](https://www.npmjs.com/package/react-smart-copy)
4
4
  [![npm downloads](https://img.shields.io/npm/dm/react-smart-copy)](https://www.npmjs.com/package/react-smart-copy)
5
5
  [![CI](https://github.com/suprabhat02/react-smart-copy/actions/workflows/ci.yml/badge.svg)](https://github.com/suprabhat02/react-smart-copy/actions/workflows/ci.yml)
6
+ [![CodeQL](https://github.com/suprabhat02/react-smart-copy/actions/workflows/codeql.yml/badge.svg)](https://github.com/suprabhat02/react-smart-copy/actions/workflows/codeql.yml)
7
+ [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/suprabhat02/react-smart-copy/badge)](https://scorecard.dev/viewer/?uri=github.com/suprabhat02/react-smart-copy)
6
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
7
9
  [![React 18+](https://img.shields.io/badge/React-18%2B-61dafb)](https://react.dev)
8
10
  [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)
@@ -30,6 +32,7 @@ ID PLT-29018 [Copy]
30
32
  - **`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
33
  - **`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
32
34
  - **`react-smart-copy/image`**: get pasted photos and screenshots ready to upload. It removes GPS location, camera data and hidden thumbnails without touching a pixel, and fits size and byte limits, re-encoding only when it has to
35
+ - **`react-smart-copy/link`**: "Copy link" buttons that paste as a titled link in Slack, Docs and Notion and as the URL in editors, links that scroll to a highlighted passage, tracking parameters removed, and pasting a URL over selected text to make a link
33
36
  - **`react-smart-copy/capture`**: copy an `<svg>` or any piece of your UI as a PNG
34
37
  - Every failure is a typed, classified error. Nothing silently no-ops
35
38
  - Unstyled. Works with Tailwind, CSS modules, CSS-in-JS, shadcn, MUI, Ant Design
@@ -52,6 +55,7 @@ This package only promises what browsers actually support.
52
55
  | Rich text as Markdown | ✅ paste | `react-smart-copy/markdown`: CommonMark + GFM from Docs, Word, web pages and mail; plain-text pastes stay untouched |
53
56
  | Code (blocks, sessions, diffs) | ✅ | `react-smart-copy/code`: plain text plus monospaced, highlighted HTML; commands without prompts or output; Trojan Source checks on paste |
54
57
  | Pasted images, made safe | ✅ paste | `react-smart-copy/image`: removes location and camera metadata losslessly; resizes and compresses under a byte budget |
58
+ | Links (titled, to a passage) | ✅ | `react-smart-copy/link`: a titled `<a>` plus the URL; `text/uri-list` when dragged; text fragment links; never `javascript:` |
55
59
  | SVG (icons, charts, logos) | ✅ as PNG | `svgToPngBlob()` from `react-smart-copy/capture` rasterises natively, no dependency. Raw SVG is not a clipboard image format |
56
60
  | 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 |
57
61
  | Files (PDF, DOCX, ZIP) | ❌ | Not writable to the system clipboard by any browser API |
@@ -306,10 +310,12 @@ in every browser that supports HTML5 drag-and-drop.
306
310
 
307
311
  ```tsx
308
312
  import { useDragCopy } from "react-smart-copy";
313
+ import { linkPayload } from "react-smart-copy/link";
309
314
 
310
315
  function DraggableCard({ title, url }: { title: string; url: string }) {
311
316
  const { ref, status } = useDragCopy({
312
- source: () => ({ kind: "html", html: `<a href="${url}">${title}</a>`, text: title }),
317
+ // Escaped, scheme-checked, and with text/uri-list so it drops into the address bar too.
318
+ source: () => linkPayload({ url, title }, { target: "drag" }),
313
319
  effectAllowed: "copy",
314
320
  });
315
321
  return (
@@ -840,6 +846,92 @@ const { blob, removed } = await stripMetadata(file); // bit-for-bit the same pic
840
846
  their orientation, and Chromium doesn't turn WebP. `removed` is read back from the
841
847
  output, not assumed, because some browsers' encoders add their own colour profile.
842
848
 
849
+ ## Copy links
850
+
851
+ `react-smart-copy/link` is for "Copy link" and "Share" buttons, and for fields people
852
+ paste links into. No dependencies, about 4 kB (`linkPayload` alone is about 1.8 kB).
853
+
854
+ ```tsx
855
+ import { useCopy } from "react-smart-copy";
856
+ import { linkPayload } from "react-smart-copy/link";
857
+
858
+ const { copy, status } = useCopy();
859
+ <button onClick={() => copy(() => linkPayload({ url: issue.url, title: issue.title }, { clean: true }))}>Copy link</button>
860
+ ```
861
+
862
+ **It pastes as the right thing everywhere.** The clipboard gets a titled link (`<a href>`)
863
+ and the URL. Slack, Google Docs, Notion, Teams, Word and mail paste the title as a link;
864
+ editors, terminals and the address bar paste the URL. `text: "markdown"` makes the plain
865
+ text `[title](url)` for Markdown fields, `"title-and-url"` puts both on two lines. Dragged
866
+ with `useDragCopy` (`{ target: "drag" }`), it also carries `text/uri-list` and Firefox's
867
+ `text/x-moz-url`, so it drops into tabs, bookmarks and other apps as a link.
868
+
869
+ **Safe by default.** Every URL is resolved to an absolute one and checked: only `https:`,
870
+ `http:`, `mailto:` and `tel:` are allowed (`protocols` changes that), so `javascript:` and
871
+ `data:` links are never copied or pasted. User names and passwords in a URL are always
872
+ removed. International domains are written in punycode, so a lookalike domain shows as
873
+ one. Titles are cleaned of hidden and reordering characters and capped at 300 characters
874
+ (`maxTitleLength`), and all HTML is escaped. Invalid input is a typed `invalid-payload` error.
875
+
876
+ **Tracking parameters removed.** `clean: true` (or `cleanLinkUrl(url)`) removes `utm_*`,
877
+ `fbclid`, `gclid`, `msclkid` and other click trackers, and keeps every other parameter and
878
+ the `#section`. `clean: { params, keep }` sets your own list.
879
+
880
+ ```ts
881
+ import { cleanLinkUrl, linkPayload, resolveLink } from "react-smart-copy/link";
882
+
883
+ cleanLinkUrl("https://shop.example/p/42?utm_source=news&color=red#reviews");
884
+ // "https://shop.example/p/42?color=red#reviews"
885
+
886
+ linkPayload(anchorElement); // an <a>: its resolved href and its text
887
+ ```
888
+
889
+ **Links to a passage.** `textFragmentUrl` makes a link that scrolls to a passage and
890
+ highlights it (`#:~:text=`), in Chrome, Edge, Safari and Firefox. Other browsers open the
891
+ page as usual. `selectionLink()` links to what the reader has selected, with the page title
892
+ and the quote, ready for `linkPayload`. Passing a function to `copy` turns an invalid link into an
893
+ `invalid-payload` error state rather than an exception:
894
+
895
+ ```tsx
896
+ import { linkPayload, selectionLink, textFragmentUrl } from "react-smart-copy/link";
897
+
898
+ <button onClick={() => { const link = selectionLink(); if (link) void copy(() => linkPayload(link)); }}>Copy link to selection</button>
899
+
900
+ textFragmentUrl("https://example.com/docs#install", "npm install react-smart-copy");
901
+ // "https://example.com/docs#install:~:text=npm%20install%20react%2Dsmart%2Dcopy"
902
+ ```
903
+
904
+ Long passages link by their first and last words, each taken from within one paragraph,
905
+ as the syntax requires. When the passage appears more than once on the page, the words
906
+ around it are added so the link finds the right one.
907
+
908
+ **Pasting links.** `pasteAsLink` turns selected text into a link when a URL is pasted over
909
+ it, as GitHub, Slack and Notion do. It writes `[selection](url)` by default (`format`
910
+ changes that) and keeps the browser's undo. Every other paste is left alone.
911
+ `readLink(result)` reads the one link a paste or drop holds, with its title, from
912
+ `text/uri-list`, a single `<a>` or a single URL, or returns `null`.
913
+
914
+ ```tsx
915
+ import { pasteAsLink, readLink } from "react-smart-copy/link";
916
+
917
+ <textarea onPaste={pasteAsLink} />
918
+
919
+ usePaste({ accept: ["text", "html", "text/uri-list"], onPaste: (result) => {
920
+ const link = readLink(result);
921
+ if (link) addBookmark(link.url, link.title);
922
+ } });
923
+ ```
924
+
925
+ | Option | Default | |
926
+ | ------ | ------- | - |
927
+ | `text` | `"url"` | plain text: `"url"`, `"title"`, `"title-and-url"` or `"markdown"` |
928
+ | `target` | clipboard | `"drag"` adds `text/uri-list` and `text/x-moz-url` |
929
+ | `clean` | `false` | `true`, or `{ params, keep }` |
930
+ | `protocols` | `https:`, `http:`, `mailto:`, `tel:` | allowed schemes |
931
+ | `base` | the page's address | resolves relative links; needed on the server |
932
+ | `maxTitleLength` | 300 | |
933
+ | `maxWords` / `contextWords` | 10 / 4 | text fragments |
934
+
843
935
  ## Only one "Copied" at a time
844
936
 
845
937
  Wrap a table or list in `<CopyGroup>`. A new successful copy returns the previously copied
@@ -1290,7 +1382,8 @@ embedded webviews. Where a capability is missing you get a typed error, never a
1290
1382
  - ~~**1.10** `react-smart-copy/structured` — typed, versioned, validated application data on the clipboard~~ shipped
1291
1383
  - ~~**1.11** `react-smart-copy/markdown` — paste rich content as Markdown, with undo intact~~ shipped
1292
1384
  - ~~**1.12** `react-smart-copy/code` — copy code blocks and sessions cleanly, paste code safely, detect Trojan Source and homoglyphs~~ shipped
1293
- - **1.13** `react-smart-copy/image` — pasted images without location or camera metadata, fitted to size and byte limits
1385
+ - ~~**1.13** `react-smart-copy/image` — pasted images without location or camera metadata, fitted to size and byte limits~~ shipped
1386
+ - **1.14** `react-smart-copy/link` — links that paste well everywhere, links to a passage, tracking parameters removed, paste a URL over text to make a link
1294
1387
 
1295
1388
  Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/#releases).
1296
1389
 
@@ -1307,11 +1400,19 @@ npm run site:build && npm run test:e2e # end-to-end tests in Chromium, Firefox
1307
1400
  Releases are automated: merging the "chore: release" PR publishes to npm through
1308
1401
  trusted publishing with provenance. No long-lived npm token is stored in the repo.
1309
1402
 
1403
+ ## Security
1404
+
1405
+ Clipboard content is untrusted input, and this package treats it that way: pasted HTML
1406
+ is parsed inertly, URLs are scheme-checked, hidden characters are reported, and image
1407
+ metadata is verified as removed. Report vulnerabilities privately as described in
1408
+ [SECURITY.md](./SECURITY.md). Releases carry npm provenance (`npm audit signatures`
1409
+ verifies them), and CodeQL and the OpenSSF Scorecard run on every change.
1410
+
1310
1411
  ## Support
1311
1412
 
1312
1413
  If react-smart-copy saves you time, [star it on GitHub](https://github.com/suprabhat02/react-smart-copy):
1313
1414
  it helps other React developers find it. Bugs and ideas are welcome in
1314
- [issues](https://github.com/suprabhat02/react-smart-copy/issues).
1415
+ [issues](https://github.com/suprabhat02/react-smart-copy/issues); see [CONTRIBUTING.md](./CONTRIBUTING.md).
1315
1416
 
1316
1417
  ## Author
1317
1418