react-smart-copy 1.15.0 → 1.17.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
@@ -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/rich`**: copy styled content so it pastes as it looks in Gmail, Outlook, Apple Mail, Google Docs, Word, Notion and Slack: sanitized HTML with inline styles, email-safe colours and absolute links, plus readable plain text. Works for buttons and for Ctrl/⌘+C
37
+ - **`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
36
38
  - **`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
37
39
  - **`react-smart-copy/capture`**: copy an `<svg>` or any piece of your UI as a PNG
38
40
  - Every failure is a typed, classified error. Nothing silently no-ops
@@ -57,6 +59,8 @@ This package only promises what browsers actually support.
57
59
  | Code (blocks, sessions, diffs) | ✅ | `react-smart-copy/code`: plain text plus monospaced, highlighted HTML; commands without prompts or output; Trojan Source checks on paste |
58
60
  | Pasted images, made safe | ✅ paste | `react-smart-copy/image`: removes location and camera metadata losslessly; resizes and compresses under a byte budget |
59
61
  | 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:` |
62
+ | Styled content, portable | ✅ | `react-smart-copy/rich`: sanitized HTML with inline styles and email-safe colours, plus plain text; for buttons and Ctrl/⌘+C |
63
+ | 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 |
60
64
  | 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 |
61
65
  | SVG (icons, charts, logos) | ✅ as PNG | `svgToPngBlob()` from `react-smart-copy/capture` rasterises natively, no dependency. Raw SVG is not a clipboard image format |
62
66
  | 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 |
@@ -934,6 +938,139 @@ usePaste({ accept: ["text", "html", "text/uri-list"], onPaste: (result) => {
934
938
  | `maxTitleLength` | 300 | |
935
939
  | `maxWords` / `contextWords` | 10 / 4 | text fragments |
936
940
 
941
+ ## Copy styled content: paste it as it looks
942
+
943
+ Copy a card, a note, a report or a table from your app and paste it into Gmail, Outlook
944
+ or Google Docs, and it usually comes out wrong. The classes and stylesheets it depended on
945
+ don't travel. Modern CSS colours like Tailwind's `oklch()` mean nothing to mail clients.
946
+ Light text from a dark theme turns invisible on a white page. Relative links and images
947
+ break. And the browser's own copy fills the paste with layout CSS and page chrome.
948
+ `react-smart-copy/rich` copies what the reader sees, in HTML that every destination keeps.
949
+
950
+ ```tsx
951
+ import { useCopy, useCopyInterceptor } from "react-smart-copy";
952
+ import { richPayload, richTransform } from "react-smart-copy/rich";
953
+
954
+ const { copy } = useCopy();
955
+ <button onClick={() => copy(() => richPayload(cardRef.current))}>Copy for email</button>
956
+
957
+ // Ctrl/⌘+C of any selection inside the article is portable too:
958
+ useCopyInterceptor(articleRef, { transform: richTransform() });
959
+ ```
960
+
961
+ **What it writes:**
962
+
963
+ - **Only what's safe and widely supported.** Text, headings, lists, tables, links, images,
964
+ quotes and code. Scripts, event handlers, embeds, SVG, media, forms and controls are left
965
+ out. So are hidden content and anything marked `data-copy-ignore` or `aria-hidden`. Every
966
+ attribute is checked against an allowlist.
967
+ - **Styles inline, from what the reader sees.** For content on the page, the computed
968
+ styles are read: colours, fonts, sizes, weight, alignment, borders, padding, list markers.
969
+ They are written only where they change, so the HTML stays small. Layout CSS (`flex`,
970
+ `grid`, `position`) is never copied, because no destination keeps it.
971
+ - **Colours every mail client understands.** Every colour, from `oklch()`, `color()`,
972
+ `rgb(… / 50%)` or a CSS variable, becomes an opaque hex value drawn over its background.
973
+ With `colors: "readable"` (the default), text that would fall under 3:1 contrast where
974
+ it lands, like light text from a dark theme, takes the destination's own colour.
975
+ `"keep"` copies every colour, and `"none"` copies none.
976
+ - **Absolute, safe URLs.** Links resolve against the page and keep only `https:`,
977
+ `http:`, `mailto:` and `tel:` (`protocols` changes this). Images keep `https:` and `http:`
978
+ sources with their displayed size as attributes, which Outlook needs. `data:` images
979
+ need `dataImages: true`, because many mail clients block them. `images: "alt"` writes
980
+ their alt text instead, and `images: "drop"` leaves them out.
981
+ - **Structure that survives the paste.** Rows sit in table bodies. A block inside a
982
+ paragraph is written inline. Nothing is left where an HTML parser would move it.
983
+ - **Readable plain text** for editors and plain fields: lists with bullets or numbers,
984
+ table cells separated by tabs, line breaks kept. `text: (root) => htmlToMarkdown(root).markdown`
985
+ gives Markdown instead.
986
+
987
+ `prepareRich(source, options)` returns `{ html, text, removed, truncated }`. `removed`
988
+ lists what was left out and why (`unsafe-element`, `unsafe-link`, `unreadable-color`,
989
+ `hidden`, …), for logs and audits. The source can be an element, a selection `Range`, a
990
+ fragment or HTML text. HTML text is parsed inertly, and only its `style` attributes are
991
+ read. The output is built in a separate, inert document, so nothing is inserted into your
992
+ page and no image loads while it is prepared. `maxElements` (10,000) and `maxLength`
993
+ (about 1 MB) bound the work.
994
+
995
+ The output is property-tested against hostile HTML. [DOMPurify](https://github.com/cure53/DOMPurify)
996
+ finds nothing to remove from it, and running the output through again changes nothing.
997
+ In Chromium, Firefox and WebKit, the computed styles are checked end to end.
998
+
999
+ | Option | Default | |
1000
+ | --- | --- | --- |
1001
+ | `colors` | `"readable"` | `"keep"`, `"none"` |
1002
+ | `background` | `"#ffffff"` | where it is pasted, for readability |
1003
+ | `images` / `dataImages` | `"keep"` / `false` | `"alt"`, `"drop"` |
1004
+ | `styles` | `"computed"` on the page, `"inline"` otherwise | `"none"` |
1005
+ | `ignore` | none | a CSS selector to leave out |
1006
+ | `base` / `protocols` | the page / `https:`, `http:`, `mailto:`, `tel:` | links |
1007
+ | `maxElements` / `maxLength` | 10,000 / 1,000,000 | then `truncated` |
1008
+ | `text` | readable plain text | your own, such as Markdown |
1009
+
1010
+ ## Copy and paste colours
1011
+
1012
+ `react-smart-copy/color` is for design-system docs, colour pickers, theme editors and
1013
+ design tools. It reads and writes every CSS Color 4 notation, without dependencies.
1014
+ About 6.5 kB in total; `parseColor` with `formatColor` is about 5.3 kB.
1015
+
1016
+ ```tsx
1017
+ import { useCopy } from "react-smart-copy";
1018
+ import { colorPayload, pasteAsColor } from "react-smart-copy/color";
1019
+
1020
+ const { copy } = useCopy();
1021
+ <button onClick={() => copy(() => colorPayload(token.value, { format: "oklch" }))}>Copy</button>
1022
+ // Text: "oklch(62.31% 0.18801 259.81)". Docs, Notion, Slack and mail also get a swatch.
1023
+
1024
+ <input value={hex} onChange={…} onPaste={(event) => pasteAsColor(event, { format: "hex" })} />
1025
+ // Pasting "rgb(59 130 246)" or "background: #3b82f6;" inserts "#3b82f6".
1026
+ ```
1027
+
1028
+ **Every format, both ways.** `parseColor` reads hex (3, 4, 6 and 8 digits), the 148 named
1029
+ colours and `transparent`, `rgb()` and `hsl()` (both syntaxes), `hwb()`, `lab()`, `lch()`,
1030
+ `oklab()`, `oklch()`, and `color()` in `srgb`, `srgb-linear`, `display-p3`, `xyz`, `xyz-d65`
1031
+ and `xyz-d50`, with every angle unit, percentages and `none`. It returns `null` for
1032
+ anything else and never throws. `formatColor(color, format)` writes `hex`, `rgb`, `hsl`,
1033
+ `hwb`, `oklch`, `oklab`, `lab`, `lch` or `p3`. Its default precision brings every 8-bit
1034
+ colour back exactly; this was checked on 836,056 colours.
1035
+
1036
+ **Wide gamut done right.** A Display P3 or OKLCH colour outside sRGB stays exact until a
1037
+ format needs it in sRGB. Then it is gamut-mapped as CSS Color 4 specifies: lightness and
1038
+ hue are kept and chroma is reduced, so a vivid P3 red becomes the closest sRGB red, not an
1039
+ orange. `gamut: "clip"` clips each channel instead, as most browsers draw. `inGamut` and
1040
+ `toGamut` are exported.
1041
+
1042
+ **Pasting.** `readColor(text)` reads the one colour in pasted text. That includes a
1043
+ declaration copied from a stylesheet or developer tools: `color: #3b82f6;`,
1044
+ `--brand: oklch(…) !important;`. `bareHex: true` also reads `3b82f6`; it is off by default,
1045
+ because words like "decade" are hex. `pasteAsColor` is a paste handler for colour fields
1046
+ that keeps the browser's undo.
1047
+
1048
+ **Contrast.** `contrastRatio(text, background)` is the WCAG 2 ratio. Translucent colours
1049
+ are drawn the way a browser draws them, and the ratio is never rounded, so 4.499 fails.
1050
+ `contrastLevel(ratio, { large })` gives `AAA`, `AA` or `fail`.
1051
+
1052
+ ```ts
1053
+ import { contrastLevel, contrastRatio, formatColor, parseColor } from "react-smart-copy/color";
1054
+
1055
+ formatColor("color(display-p3 1 0 0)", "hex"); // "#ff0b0c": mapped, not clipped
1056
+ formatColor("#3b82f6", "hsl", { legacy: true }); // "hsl(217.22, 91.22%, 59.8%)"
1057
+ contrastLevel(contrastRatio("#767676", "#fff")); // "AA" (4.54)
1058
+ parseColor("hsl(1turn 100% 50% / 50%)"); // { r: 1, g: 0, b: 0, alpha: 0.5 }
1059
+ ```
1060
+
1061
+ | Option (`formatColor`, `colorPayload`) | Default | |
1062
+ | --- | --- | --- |
1063
+ | `format` | `"hex"` | `colorPayload` only |
1064
+ | `gamut` | `"map"` | `"clip"` |
1065
+ | `legacy` | `false` | comma syntax for `rgb` and `hsl` |
1066
+ | `uppercase` | `false` | hex digits |
1067
+ | `precision` | per format | decimal places |
1068
+ | `swatch` | `true` | `colorPayload` only |
1069
+
1070
+ Accuracy is property-tested against [culori](https://culorijs.org) for every notation and
1071
+ format. In Chromium, Firefox and WebKit, colours are also checked against the browser's
1072
+ own CSS parser.
1073
+
937
1074
  ## Share, or copy the link
938
1075
 
939
1076
  `react-smart-copy/share` is one button that does the right thing on every device: the
@@ -1447,7 +1584,9 @@ embedded webviews. Where a capability is missing you get a typed error, never a
1447
1584
  - ~~**1.12** `react-smart-copy/code` — copy code blocks and sessions cleanly, paste code safely, detect Trojan Source and homoglyphs~~ shipped
1448
1585
  - ~~**1.13** `react-smart-copy/image` — pasted images without location or camera metadata, fitted to size and byte limits~~ shipped
1449
1586
  - ~~**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
1587
+ - ~~**1.15** `react-smart-copy/share` — the share sheet on phones, a copied titled link everywhere else, with honest outcomes~~ shipped
1588
+ - ~~**1.16** `react-smart-copy/color` — copy and paste colours in every CSS format, CSS gamut mapping, WCAG contrast~~ shipped
1589
+ - **1.17** `react-smart-copy/rich` — styled content that pastes as it looks in mail, Docs, Word and Slack, for buttons and Ctrl/⌘+C
1451
1590
 
1452
1591
  Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/#releases).
1453
1592