react-smart-copy 1.13.2 → 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,6 +30,7 @@ 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
@@ -52,6 +53,7 @@ This package only promises what browsers actually support.
52
53
  | Rich text as Markdown | ✅ paste | `react-smart-copy/markdown`: CommonMark + GFM from Docs, Word, web pages and mail; plain-text pastes stay untouched |
53
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 |
54
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:` |
55
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 |
56
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 |
57
59
  | Files (PDF, DOCX, ZIP) | ❌ | Not writable to the system clipboard by any browser API |
@@ -306,10 +308,12 @@ in every browser that supports HTML5 drag-and-drop.
306
308
 
307
309
  ```tsx
308
310
  import { useDragCopy } from "react-smart-copy";
311
+ import { linkPayload } from "react-smart-copy/link";
309
312
 
310
313
  function DraggableCard({ title, url }: { title: string; url: string }) {
311
314
  const { ref, status } = useDragCopy({
312
- 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" }),
313
317
  effectAllowed: "copy",
314
318
  });
315
319
  return (
@@ -840,6 +844,92 @@ const { blob, removed } = await stripMetadata(file); // bit-for-bit the same pic
840
844
  their orientation, and Chromium doesn't turn WebP. `removed` is read back from the
841
845
  output, not assumed, because some browsers' encoders add their own colour profile.
842
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
+
843
933
  ## Only one "Copied" at a time
844
934
 
845
935
  Wrap a table or list in `<CopyGroup>`. A new successful copy returns the previously copied
@@ -1290,7 +1380,8 @@ embedded webviews. Where a capability is missing you get a typed error, never a
1290
1380
  - ~~**1.10** `react-smart-copy/structured` — typed, versioned, validated application data on the clipboard~~ shipped
1291
1381
  - ~~**1.11** `react-smart-copy/markdown` — paste rich content as Markdown, with undo intact~~ shipped
1292
1382
  - ~~**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
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
1294
1385
 
1295
1386
  Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/#releases).
1296
1387