react-smart-copy 1.13.1 → 1.14.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
@@ -30,10 +30,12 @@ ID PLT-29018 [Copy]
30
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
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
32
32
  - **`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
33
+ - **`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
34
  - **`react-smart-copy/capture`**: copy an `<svg>` or any piece of your UI as a PNG
34
35
  - Every failure is a typed, classified error. Nothing silently no-ops
35
36
  - Unstyled. Works with Tailwind, CSS modules, CSS-in-JS, shadcn, MUI, Ant Design
36
37
  - SSR / Next.js App Router safe, React 18 and 19, StrictMode-proof
38
+ - Tested in real browser engines on every change: Chromium, Firefox and WebKit (Safari's engine)
37
39
 
38
40
  ## What it can and cannot copy
39
41
 
@@ -51,6 +53,7 @@ This package only promises what browsers actually support.
51
53
  | Rich text as Markdown | ✅ paste | `react-smart-copy/markdown`: CommonMark + GFM from Docs, Word, web pages and mail; plain-text pastes stay untouched |
52
54
  | Code (blocks, sessions, diffs) | ✅ | `react-smart-copy/code`: plain text plus monospaced, highlighted HTML; commands without prompts or output; Trojan Source checks on paste |
53
55
  | Pasted images, made safe | ✅ paste | `react-smart-copy/image`: removes location and camera metadata losslessly; resizes and compresses under a byte budget |
56
+ | 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:` |
54
57
  | SVG (icons, charts, logos) | ✅ as PNG | `svgToPngBlob()` from `react-smart-copy/capture` rasterises natively, no dependency. Raw SVG is not a clipboard image format |
55
58
  | 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 |
56
59
  | Files (PDF, DOCX, ZIP) | ❌ | Not writable to the system clipboard by any browser API |
@@ -305,10 +308,12 @@ in every browser that supports HTML5 drag-and-drop.
305
308
 
306
309
  ```tsx
307
310
  import { useDragCopy } from "react-smart-copy";
311
+ import { linkPayload } from "react-smart-copy/link";
308
312
 
309
313
  function DraggableCard({ title, url }: { title: string; url: string }) {
310
314
  const { ref, status } = useDragCopy({
311
- source: () => ({ kind: "html", html: `<a href="${url}">${title}</a>`, text: title }),
315
+ // Escaped, scheme-checked, and with text/uri-list so it drops into the address bar too.
316
+ source: () => linkPayload({ url, title }, { target: "drag" }),
312
317
  effectAllowed: "copy",
313
318
  });
314
319
  return (
@@ -839,6 +844,92 @@ const { blob, removed } = await stripMetadata(file); // bit-for-bit the same pic
839
844
  their orientation, and Chromium doesn't turn WebP. `removed` is read back from the
840
845
  output, not assumed, because some browsers' encoders add their own colour profile.
841
846
 
847
+ ## Copy links
848
+
849
+ `react-smart-copy/link` is for "Copy link" and "Share" buttons, and for fields people
850
+ paste links into. No dependencies, about 4 kB (`linkPayload` alone is about 1.8 kB).
851
+
852
+ ```tsx
853
+ import { useCopy } from "react-smart-copy";
854
+ import { linkPayload } from "react-smart-copy/link";
855
+
856
+ const { copy, status } = useCopy();
857
+ <button onClick={() => copy(() => linkPayload({ url: issue.url, title: issue.title }, { clean: true }))}>Copy link</button>
858
+ ```
859
+
860
+ **It pastes as the right thing everywhere.** The clipboard gets a titled link (`<a href>`)
861
+ and the URL. Slack, Google Docs, Notion, Teams, Word and mail paste the title as a link;
862
+ editors, terminals and the address bar paste the URL. `text: "markdown"` makes the plain
863
+ text `[title](url)` for Markdown fields, `"title-and-url"` puts both on two lines. Dragged
864
+ with `useDragCopy` (`{ target: "drag" }`), it also carries `text/uri-list` and Firefox's
865
+ `text/x-moz-url`, so it drops into tabs, bookmarks and other apps as a link.
866
+
867
+ **Safe by default.** Every URL is resolved to an absolute one and checked: only `https:`,
868
+ `http:`, `mailto:` and `tel:` are allowed (`protocols` changes that), so `javascript:` and
869
+ `data:` links are never copied or pasted. User names and passwords in a URL are always
870
+ removed. International domains are written in punycode, so a lookalike domain shows as
871
+ one. Titles are cleaned of hidden and reordering characters and capped at 300 characters
872
+ (`maxTitleLength`), and all HTML is escaped. Invalid input is a typed `invalid-payload` error.
873
+
874
+ **Tracking parameters removed.** `clean: true` (or `cleanLinkUrl(url)`) removes `utm_*`,
875
+ `fbclid`, `gclid`, `msclkid` and other click trackers, and keeps every other parameter and
876
+ the `#section`. `clean: { params, keep }` sets your own list.
877
+
878
+ ```ts
879
+ import { cleanLinkUrl, linkPayload, resolveLink } from "react-smart-copy/link";
880
+
881
+ cleanLinkUrl("https://shop.example/p/42?utm_source=news&color=red#reviews");
882
+ // "https://shop.example/p/42?color=red#reviews"
883
+
884
+ linkPayload(anchorElement); // an <a>: its resolved href and its text
885
+ ```
886
+
887
+ **Links to a passage.** `textFragmentUrl` makes a link that scrolls to a passage and
888
+ highlights it (`#:~:text=`), in Chrome, Edge, Safari and Firefox. Other browsers open the
889
+ page as usual. `selectionLink()` links to what the reader has selected, with the page title
890
+ and the quote, ready for `linkPayload`. Passing a function to `copy` turns an invalid link into an
891
+ `invalid-payload` error state rather than an exception:
892
+
893
+ ```tsx
894
+ import { linkPayload, selectionLink, textFragmentUrl } from "react-smart-copy/link";
895
+
896
+ <button onClick={() => { const link = selectionLink(); if (link) void copy(() => linkPayload(link)); }}>Copy link to selection</button>
897
+
898
+ textFragmentUrl("https://example.com/docs#install", "npm install react-smart-copy");
899
+ // "https://example.com/docs#install:~:text=npm%20install%20react%2Dsmart%2Dcopy"
900
+ ```
901
+
902
+ Long passages link by their first and last words, each taken from within one paragraph,
903
+ as the syntax requires. When the passage appears more than once on the page, the words
904
+ around it are added so the link finds the right one.
905
+
906
+ **Pasting links.** `pasteAsLink` turns selected text into a link when a URL is pasted over
907
+ it, as GitHub, Slack and Notion do. It writes `[selection](url)` by default (`format`
908
+ changes that) and keeps the browser's undo. Every other paste is left alone.
909
+ `readLink(result)` reads the one link a paste or drop holds, with its title, from
910
+ `text/uri-list`, a single `<a>` or a single URL, or returns `null`.
911
+
912
+ ```tsx
913
+ import { pasteAsLink, readLink } from "react-smart-copy/link";
914
+
915
+ <textarea onPaste={pasteAsLink} />
916
+
917
+ usePaste({ accept: ["text", "html", "text/uri-list"], onPaste: (result) => {
918
+ const link = readLink(result);
919
+ if (link) addBookmark(link.url, link.title);
920
+ } });
921
+ ```
922
+
923
+ | Option | Default | |
924
+ | ------ | ------- | - |
925
+ | `text` | `"url"` | plain text: `"url"`, `"title"`, `"title-and-url"` or `"markdown"` |
926
+ | `target` | clipboard | `"drag"` adds `text/uri-list` and `text/x-moz-url` |
927
+ | `clean` | `false` | `true`, or `{ params, keep }` |
928
+ | `protocols` | `https:`, `http:`, `mailto:`, `tel:` | allowed schemes |
929
+ | `base` | the page's address | resolves relative links; needed on the server |
930
+ | `maxTitleLength` | 300 | |
931
+ | `maxWords` / `contextWords` | 10 / 4 | text fragments |
932
+
842
933
  ## Only one "Copied" at a time
843
934
 
844
935
  Wrap a table or list in `<CopyGroup>`. A new successful copy returns the previously copied
@@ -1289,7 +1380,8 @@ embedded webviews. Where a capability is missing you get a typed error, never a
1289
1380
  - ~~**1.10** `react-smart-copy/structured` — typed, versioned, validated application data on the clipboard~~ shipped
1290
1381
  - ~~**1.11** `react-smart-copy/markdown` — paste rich content as Markdown, with undo intact~~ shipped
1291
1382
  - ~~**1.12** `react-smart-copy/code` — copy code blocks and sessions cleanly, paste code safely, detect Trojan Source and homoglyphs~~ shipped
1292
- - **1.13** `react-smart-copy/image` — pasted images without location or camera metadata, fitted to size and byte limits
1383
+ - ~~**1.13** `react-smart-copy/image` — pasted images without location or camera metadata, fitted to size and byte limits~~ shipped
1384
+ - **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
1293
1385
 
1294
1386
  Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/#releases).
1295
1387
 
@@ -1300,6 +1392,7 @@ npm install
1300
1392
  npm run verify # lint, types, tests at 100% coverage, build, publint + attw, consumer types, size budgets
1301
1393
  npm run changeset # describe your change for the changelog
1302
1394
  npm run site:preview # docs site at http://localhost:3000
1395
+ npm run site:build && npm run test:e2e # end-to-end tests in Chromium, Firefox and WebKit
1303
1396
  ```
1304
1397
 
1305
1398
  Releases are automated: merging the "chore: release" PR publishes to npm through