react-smart-copy 1.14.0 → 1.15.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
@@ -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)
@@ -31,6 +33,7 @@ ID PLT-29018 [Copy]
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
33
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
36
+ - **`react-smart-copy/share`**: one "Share" button that opens the share sheet on phones and copies a titled link on desktop, with honest states: a closed share sheet is never an error
34
37
  - **`react-smart-copy/capture`**: copy an `<svg>` or any piece of your UI as a PNG
35
38
  - Every failure is a typed, classified error. Nothing silently no-ops
36
39
  - Unstyled. Works with Tailwind, CSS modules, CSS-in-JS, shadcn, MUI, Ant Design
@@ -54,6 +57,7 @@ This package only promises what browsers actually support.
54
57
  | Code (blocks, sessions, diffs) | ✅ | `react-smart-copy/code`: plain text plus monospaced, highlighted HTML; commands without prompts or output; Trojan Source checks on paste |
55
58
  | Pasted images, made safe | ✅ paste | `react-smart-copy/image`: removes location and camera metadata losslessly; resizes and compresses under a byte budget |
56
59
  | 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:` |
60
+ | Share sheet (Web Share API) | ✅ with copy fallback | `react-smart-copy/share`: the share sheet on phones and tablets, a titled link copied elsewhere; files where the share sheet takes them |
57
61
  | SVG (icons, charts, logos) | ✅ as PNG | `svgToPngBlob()` from `react-smart-copy/capture` rasterises natively, no dependency. Raw SVG is not a clipboard image format |
58
62
  | 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 |
59
63
  | Files (PDF, DOCX, ZIP) | ❌ | Not writable to the system clipboard by any browser API |
@@ -930,6 +934,67 @@ usePaste({ accept: ["text", "html", "text/uri-list"], onPaste: (result) => {
930
934
  | `maxTitleLength` | 300 | |
931
935
  | `maxWords` / `contextWords` | 10 / 4 | text fragments |
932
936
 
937
+ ## Share, or copy the link
938
+
939
+ `react-smart-copy/share` is one button that does the right thing on every device: the
940
+ share sheet on phones and tablets, where people expect it, and a copied titled link on
941
+ desktop. `useShare` comes from `react-smart-copy`; without React, use
942
+ `shareOrCopy` from `react-smart-copy/share` (about 4.4 kB).
943
+
944
+ ```tsx
945
+ import { useShare } from "react-smart-copy";
946
+
947
+ function ShareButton({ url, title }: { url: string; title: string }) {
948
+ const { share, status, method } = useShare({ clean: true });
949
+ return (
950
+ <button type="button" onClick={() => void share({ url, title })}>
951
+ {status === "copied" ? "Link copied" : status === "shared" ? "Shared" : method === "native" ? "Share…" : "Copy link"}
952
+ </button>
953
+ );
954
+ }
955
+ ```
956
+
957
+ **Honest outcomes.** `share()` never rejects. It resolves to `shared`, `copied` (with a
958
+ `reason`: `preferred`, `unsupported` or `fallback`), `cancelled` or `error`. Closing the
959
+ share sheet is `cancelled`, and the status goes back to `idle`: it is not an error, and it
960
+ never triggers a surprise copy. When the share sheet fails for another reason (an iframe
961
+ without the `web-share` permission, content it rejects), the link is copied instead.
962
+ `fallback: false` reports the error instead. `describeShareError(error, method)` gives a
963
+ sentence for each.
964
+
965
+ **Labelled correctly.** `method` says what the button will do, `"native"` or `"copy"`, so
966
+ the label can say "Share…" or "Copy link". It is `"copy"` during server rendering and
967
+ hydration, so there is no mismatch. Then it follows the device, including a tablet that
968
+ gets a keyboard and a mouse.
969
+
970
+ | `mode` | What happens |
971
+ | ------ | ------------ |
972
+ | `"auto"` (default) | the share sheet on touch-first devices (`(hover: none) and (pointer: coarse)`), copy elsewhere |
973
+ | `"native"` | the share sheet wherever the browser has one (also desktop Safari, and Edge and Chrome on Windows and macOS) |
974
+ | `"copy"` | always copy |
975
+
976
+ **What is shared.** `url`, `title`, `text` and `files`. The URL is checked like every link
977
+ in `react-smart-copy/link`: only safe schemes, with credentials removed, and tracking
978
+ parameters removed with `clean: true`. The title is cleaned of hidden characters. Files go
979
+ only to a share sheet that accepts them (`navigator.canShare`); otherwise the link is
980
+ copied. The copy is a titled link (`linkPayload`), or the text when there is no URL.
981
+ `copy` sets your own.
982
+
983
+ Without React, `shareOrCopy(content, options)` resolves to the same outcomes, and
984
+ `shareMethod(options)` says how it would share:
985
+
986
+ ```ts
987
+ import { shareOrCopy } from "react-smart-copy/share";
988
+
989
+ button.addEventListener("click", async () => {
990
+ const outcome = await shareOrCopy({ url: location.href, title: document.title });
991
+ if (outcome.status === "copied") toast("Link copied");
992
+ });
993
+ ```
994
+
995
+ Call `share()` directly in the click handler. The share sheet needs the click's user
996
+ activation, so don't `await` anything before it.
997
+
933
998
  ## Only one "Copied" at a time
934
999
 
935
1000
  Wrap a table or list in `<CopyGroup>`. A new successful copy returns the previously copied
@@ -1381,7 +1446,8 @@ embedded webviews. Where a capability is missing you get a typed error, never a
1381
1446
  - ~~**1.11** `react-smart-copy/markdown` — paste rich content as Markdown, with undo intact~~ shipped
1382
1447
  - ~~**1.12** `react-smart-copy/code` — copy code blocks and sessions cleanly, paste code safely, detect Trojan Source and homoglyphs~~ shipped
1383
1448
  - ~~**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
1449
+ - ~~**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~~ shipped
1450
+ - **1.15** `react-smart-copy/share` — the share sheet on phones, a copied titled link everywhere else, with honest outcomes
1385
1451
 
1386
1452
  Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/#releases).
1387
1453
 
@@ -1398,11 +1464,19 @@ npm run site:build && npm run test:e2e # end-to-end tests in Chromium, Firefox
1398
1464
  Releases are automated: merging the "chore: release" PR publishes to npm through
1399
1465
  trusted publishing with provenance. No long-lived npm token is stored in the repo.
1400
1466
 
1467
+ ## Security
1468
+
1469
+ Clipboard content is untrusted input, and this package treats it that way: pasted HTML
1470
+ is parsed inertly, URLs are scheme-checked, hidden characters are reported, and image
1471
+ metadata is verified as removed. Report vulnerabilities privately as described in
1472
+ [SECURITY.md](./SECURITY.md). Releases carry npm provenance (`npm audit signatures`
1473
+ verifies them), and CodeQL and the OpenSSF Scorecard run on every change.
1474
+
1401
1475
  ## Support
1402
1476
 
1403
1477
  If react-smart-copy saves you time, [star it on GitHub](https://github.com/suprabhat02/react-smart-copy):
1404
1478
  it helps other React developers find it. Bugs and ideas are welcome in
1405
- [issues](https://github.com/suprabhat02/react-smart-copy/issues).
1479
+ [issues](https://github.com/suprabhat02/react-smart-copy/issues); see [CONTRIBUTING.md](./CONTRIBUTING.md).
1406
1480
 
1407
1481
  ## Author
1408
1482