react-smart-copy 1.14.1 → 1.16.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 +132 -1
- package/dist/color.cjs +927 -0
- package/dist/color.cjs.map +1 -0
- package/dist/color.d.cts +198 -0
- package/dist/color.d.ts +198 -0
- package/dist/color.js +916 -0
- package/dist/color.js.map +1 -0
- package/dist/index.cjs +523 -34
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +145 -1
- package/dist/index.d.ts +145 -1
- package/dist/index.js +523 -35
- package/dist/index.js.map +1 -1
- package/dist/link.cjs +2 -2
- package/dist/link.cjs.map +1 -1
- package/dist/link.js +2 -2
- package/dist/link.js.map +1 -1
- package/dist/markdown.cjs.map +1 -1
- package/dist/markdown.js.map +1 -1
- package/dist/share.cjs +641 -0
- package/dist/share.cjs.map +1 -0
- package/dist/share.d.cts +248 -0
- package/dist/share.d.ts +248 -0
- package/dist/share.js +638 -0
- package/dist/share.js.map +1 -0
- package/package.json +76 -4
package/README.md
CHANGED
|
@@ -33,6 +33,8 @@ ID PLT-29018 [Copy]
|
|
|
33
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
|
|
34
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
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/color`**: copy colours in any CSS format (hex to `oklch()` and Display P3) with a swatch for Docs and Slack, paste any format into a colour field, and check WCAG contrast. Wide-gamut colours are mapped the way CSS specifies, never clipped to a wrong hue
|
|
37
|
+
- **`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
|
|
36
38
|
- **`react-smart-copy/capture`**: copy an `<svg>` or any piece of your UI as a PNG
|
|
37
39
|
- Every failure is a typed, classified error. Nothing silently no-ops
|
|
38
40
|
- Unstyled. Works with Tailwind, CSS modules, CSS-in-JS, shadcn, MUI, Ant Design
|
|
@@ -56,6 +58,8 @@ This package only promises what browsers actually support.
|
|
|
56
58
|
| Code (blocks, sessions, diffs) | ✅ | `react-smart-copy/code`: plain text plus monospaced, highlighted HTML; commands without prompts or output; Trojan Source checks on paste |
|
|
57
59
|
| Pasted images, made safe | ✅ paste | `react-smart-copy/image`: removes location and camera metadata losslessly; resizes and compresses under a byte budget |
|
|
58
60
|
| 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:` |
|
|
61
|
+
| Colours (every CSS format) | ✅ | `react-smart-copy/color`: the value as text, plus a swatch for rich-text apps; any CSS colour read back on paste |
|
|
62
|
+
| 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 |
|
|
59
63
|
| SVG (icons, charts, logos) | ✅ as PNG | `svgToPngBlob()` from `react-smart-copy/capture` rasterises natively, no dependency. Raw SVG is not a clipboard image format |
|
|
60
64
|
| 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 |
|
|
61
65
|
| Files (PDF, DOCX, ZIP) | ❌ | Not writable to the system clipboard by any browser API |
|
|
@@ -932,6 +936,131 @@ usePaste({ accept: ["text", "html", "text/uri-list"], onPaste: (result) => {
|
|
|
932
936
|
| `maxTitleLength` | 300 | |
|
|
933
937
|
| `maxWords` / `contextWords` | 10 / 4 | text fragments |
|
|
934
938
|
|
|
939
|
+
## Copy and paste colours
|
|
940
|
+
|
|
941
|
+
`react-smart-copy/color` is for design-system docs, colour pickers, theme editors and
|
|
942
|
+
design tools. It reads and writes every CSS Color 4 notation, without dependencies.
|
|
943
|
+
About 6.5 kB in total; `parseColor` with `formatColor` is about 5.3 kB.
|
|
944
|
+
|
|
945
|
+
```tsx
|
|
946
|
+
import { useCopy } from "react-smart-copy";
|
|
947
|
+
import { colorPayload, pasteAsColor } from "react-smart-copy/color";
|
|
948
|
+
|
|
949
|
+
const { copy } = useCopy();
|
|
950
|
+
<button onClick={() => copy(() => colorPayload(token.value, { format: "oklch" }))}>Copy</button>
|
|
951
|
+
// Text: "oklch(62.31% 0.18801 259.81)". Docs, Notion, Slack and mail also get a swatch.
|
|
952
|
+
|
|
953
|
+
<input value={hex} onChange={…} onPaste={(event) => pasteAsColor(event, { format: "hex" })} />
|
|
954
|
+
// Pasting "rgb(59 130 246)" or "background: #3b82f6;" inserts "#3b82f6".
|
|
955
|
+
```
|
|
956
|
+
|
|
957
|
+
**Every format, both ways.** `parseColor` reads hex (3, 4, 6 and 8 digits), the 148 named
|
|
958
|
+
colours and `transparent`, `rgb()` and `hsl()` (both syntaxes), `hwb()`, `lab()`, `lch()`,
|
|
959
|
+
`oklab()`, `oklch()`, and `color()` in `srgb`, `srgb-linear`, `display-p3`, `xyz`, `xyz-d65`
|
|
960
|
+
and `xyz-d50`, with every angle unit, percentages and `none`. It returns `null` for
|
|
961
|
+
anything else and never throws. `formatColor(color, format)` writes `hex`, `rgb`, `hsl`,
|
|
962
|
+
`hwb`, `oklch`, `oklab`, `lab`, `lch` or `p3`. Its default precision brings every 8-bit
|
|
963
|
+
colour back exactly; this was checked on 836,056 colours.
|
|
964
|
+
|
|
965
|
+
**Wide gamut done right.** A Display P3 or OKLCH colour outside sRGB stays exact until a
|
|
966
|
+
format needs it in sRGB. Then it is gamut-mapped as CSS Color 4 specifies: lightness and
|
|
967
|
+
hue are kept and chroma is reduced, so a vivid P3 red becomes the closest sRGB red, not an
|
|
968
|
+
orange. `gamut: "clip"` clips each channel instead, as most browsers draw. `inGamut` and
|
|
969
|
+
`toGamut` are exported.
|
|
970
|
+
|
|
971
|
+
**Pasting.** `readColor(text)` reads the one colour in pasted text. That includes a
|
|
972
|
+
declaration copied from a stylesheet or developer tools: `color: #3b82f6;`,
|
|
973
|
+
`--brand: oklch(…) !important;`. `bareHex: true` also reads `3b82f6`; it is off by default,
|
|
974
|
+
because words like "decade" are hex. `pasteAsColor` is a paste handler for colour fields
|
|
975
|
+
that keeps the browser's undo.
|
|
976
|
+
|
|
977
|
+
**Contrast.** `contrastRatio(text, background)` is the WCAG 2 ratio. Translucent colours
|
|
978
|
+
are drawn the way a browser draws them, and the ratio is never rounded, so 4.499 fails.
|
|
979
|
+
`contrastLevel(ratio, { large })` gives `AAA`, `AA` or `fail`.
|
|
980
|
+
|
|
981
|
+
```ts
|
|
982
|
+
import { contrastLevel, contrastRatio, formatColor, parseColor } from "react-smart-copy/color";
|
|
983
|
+
|
|
984
|
+
formatColor("color(display-p3 1 0 0)", "hex"); // "#ff0b0c": mapped, not clipped
|
|
985
|
+
formatColor("#3b82f6", "hsl", { legacy: true }); // "hsl(217.22, 91.22%, 59.8%)"
|
|
986
|
+
contrastLevel(contrastRatio("#767676", "#fff")); // "AA" (4.54)
|
|
987
|
+
parseColor("hsl(1turn 100% 50% / 50%)"); // { r: 1, g: 0, b: 0, alpha: 0.5 }
|
|
988
|
+
```
|
|
989
|
+
|
|
990
|
+
| Option (`formatColor`, `colorPayload`) | Default | |
|
|
991
|
+
| --- | --- | --- |
|
|
992
|
+
| `format` | `"hex"` | `colorPayload` only |
|
|
993
|
+
| `gamut` | `"map"` | `"clip"` |
|
|
994
|
+
| `legacy` | `false` | comma syntax for `rgb` and `hsl` |
|
|
995
|
+
| `uppercase` | `false` | hex digits |
|
|
996
|
+
| `precision` | per format | decimal places |
|
|
997
|
+
| `swatch` | `true` | `colorPayload` only |
|
|
998
|
+
|
|
999
|
+
Accuracy is property-tested against [culori](https://culorijs.org) for every notation and
|
|
1000
|
+
format. In Chromium, Firefox and WebKit, colours are also checked against the browser's
|
|
1001
|
+
own CSS parser.
|
|
1002
|
+
|
|
1003
|
+
## Share, or copy the link
|
|
1004
|
+
|
|
1005
|
+
`react-smart-copy/share` is one button that does the right thing on every device: the
|
|
1006
|
+
share sheet on phones and tablets, where people expect it, and a copied titled link on
|
|
1007
|
+
desktop. `useShare` comes from `react-smart-copy`; without React, use
|
|
1008
|
+
`shareOrCopy` from `react-smart-copy/share` (about 4.4 kB).
|
|
1009
|
+
|
|
1010
|
+
```tsx
|
|
1011
|
+
import { useShare } from "react-smart-copy";
|
|
1012
|
+
|
|
1013
|
+
function ShareButton({ url, title }: { url: string; title: string }) {
|
|
1014
|
+
const { share, status, method } = useShare({ clean: true });
|
|
1015
|
+
return (
|
|
1016
|
+
<button type="button" onClick={() => void share({ url, title })}>
|
|
1017
|
+
{status === "copied" ? "Link copied" : status === "shared" ? "Shared" : method === "native" ? "Share…" : "Copy link"}
|
|
1018
|
+
</button>
|
|
1019
|
+
);
|
|
1020
|
+
}
|
|
1021
|
+
```
|
|
1022
|
+
|
|
1023
|
+
**Honest outcomes.** `share()` never rejects. It resolves to `shared`, `copied` (with a
|
|
1024
|
+
`reason`: `preferred`, `unsupported` or `fallback`), `cancelled` or `error`. Closing the
|
|
1025
|
+
share sheet is `cancelled`, and the status goes back to `idle`: it is not an error, and it
|
|
1026
|
+
never triggers a surprise copy. When the share sheet fails for another reason (an iframe
|
|
1027
|
+
without the `web-share` permission, content it rejects), the link is copied instead.
|
|
1028
|
+
`fallback: false` reports the error instead. `describeShareError(error, method)` gives a
|
|
1029
|
+
sentence for each.
|
|
1030
|
+
|
|
1031
|
+
**Labelled correctly.** `method` says what the button will do, `"native"` or `"copy"`, so
|
|
1032
|
+
the label can say "Share…" or "Copy link". It is `"copy"` during server rendering and
|
|
1033
|
+
hydration, so there is no mismatch. Then it follows the device, including a tablet that
|
|
1034
|
+
gets a keyboard and a mouse.
|
|
1035
|
+
|
|
1036
|
+
| `mode` | What happens |
|
|
1037
|
+
| ------ | ------------ |
|
|
1038
|
+
| `"auto"` (default) | the share sheet on touch-first devices (`(hover: none) and (pointer: coarse)`), copy elsewhere |
|
|
1039
|
+
| `"native"` | the share sheet wherever the browser has one (also desktop Safari, and Edge and Chrome on Windows and macOS) |
|
|
1040
|
+
| `"copy"` | always copy |
|
|
1041
|
+
|
|
1042
|
+
**What is shared.** `url`, `title`, `text` and `files`. The URL is checked like every link
|
|
1043
|
+
in `react-smart-copy/link`: only safe schemes, with credentials removed, and tracking
|
|
1044
|
+
parameters removed with `clean: true`. The title is cleaned of hidden characters. Files go
|
|
1045
|
+
only to a share sheet that accepts them (`navigator.canShare`); otherwise the link is
|
|
1046
|
+
copied. The copy is a titled link (`linkPayload`), or the text when there is no URL.
|
|
1047
|
+
`copy` sets your own.
|
|
1048
|
+
|
|
1049
|
+
Without React, `shareOrCopy(content, options)` resolves to the same outcomes, and
|
|
1050
|
+
`shareMethod(options)` says how it would share:
|
|
1051
|
+
|
|
1052
|
+
```ts
|
|
1053
|
+
import { shareOrCopy } from "react-smart-copy/share";
|
|
1054
|
+
|
|
1055
|
+
button.addEventListener("click", async () => {
|
|
1056
|
+
const outcome = await shareOrCopy({ url: location.href, title: document.title });
|
|
1057
|
+
if (outcome.status === "copied") toast("Link copied");
|
|
1058
|
+
});
|
|
1059
|
+
```
|
|
1060
|
+
|
|
1061
|
+
Call `share()` directly in the click handler. The share sheet needs the click's user
|
|
1062
|
+
activation, so don't `await` anything before it.
|
|
1063
|
+
|
|
935
1064
|
## Only one "Copied" at a time
|
|
936
1065
|
|
|
937
1066
|
Wrap a table or list in `<CopyGroup>`. A new successful copy returns the previously copied
|
|
@@ -1383,7 +1512,9 @@ embedded webviews. Where a capability is missing you get a typed error, never a
|
|
|
1383
1512
|
- ~~**1.11** `react-smart-copy/markdown` — paste rich content as Markdown, with undo intact~~ shipped
|
|
1384
1513
|
- ~~**1.12** `react-smart-copy/code` — copy code blocks and sessions cleanly, paste code safely, detect Trojan Source and homoglyphs~~ shipped
|
|
1385
1514
|
- ~~**1.13** `react-smart-copy/image` — pasted images without location or camera metadata, fitted to size and byte limits~~ shipped
|
|
1386
|
-
-
|
|
1515
|
+
- ~~**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
|
|
1516
|
+
- ~~**1.15** `react-smart-copy/share` — the share sheet on phones, a copied titled link everywhere else, with honest outcomes~~ shipped
|
|
1517
|
+
- **1.16** `react-smart-copy/color` — copy and paste colours in every CSS format, CSS gamut mapping, WCAG contrast
|
|
1387
1518
|
|
|
1388
1519
|
Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/#releases).
|
|
1389
1520
|
|