react-smart-copy 1.19.0 → 1.20.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
@@ -32,6 +32,7 @@ ID PLT-29018 [Copy]
32
32
  - **`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} />`
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
+ - **`react-smart-copy/files`**: take pasted and dropped files and whole folders safely. Types come from each file's content, so a program named `invoice.pdf.exe` or a web page named `report.pdf` is turned away with a reason, names are made safe for every operating system, and limits cap count, size and depth
35
36
  - **`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
37
  - **`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. And the other way: paste from Docs, Word and mail into a rich-text editor (TipTap, Lexical, `contenteditable`) as clean, semantic HTML
37
38
  - **`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
@@ -686,7 +687,7 @@ documents with a CommonMark parser and compare the result character by character
686
687
  - images default to their alt text (`images: "alt"`), so rendering the Markdown loads no tracking pixels. `"keep"` writes `![alt](url)` for `https:`/`http:` images, `"drop"` removes them
687
688
  - `maxLength` (16 MiB), `maxNodes` (200,000) and `maxDepth` (200) bound the work; content left out sets `truncated: true`, and merged-cell expansion is capped
688
689
 
689
- | Option | Default | |
690
+ | Option | Default | Notes |
690
691
  | ------ | ------- | - |
691
692
  | `images` | `"alt"` | `"alt"`, `"keep"` or `"drop"` |
692
693
  | `links` | `"keep"` | `"text"` keeps only the link text |
@@ -764,7 +765,7 @@ Pasted code is never cut: past `maxLength` (2,000,000 characters) `pasteToCode`
764
765
  `too-large` error, and `pasteAsCode` leaves the paste to the browser. HTML is parsed
765
766
  inertly and only its text is used.
766
767
 
767
- | Option | Default | |
768
+ | Option | Default | Notes |
768
769
  | ------ | ------- | - |
769
770
  | `prompt` | `"auto"` copy, `false` paste | a style (`"shell"`, `"powershell"`, `"cmd"`, `"python"`, `"ipython"`, `"node"`), `{ command, continuation }` regexes, or `false` |
770
771
  | `diff` | `false` | `"after"` or `"before"` |
@@ -838,7 +839,7 @@ const info = await readImageInfo(file);
838
839
  const { blob, removed } = await stripMetadata(file); // bit-for-bit the same picture
839
840
  ```
840
841
 
841
- | Option (`prepareImage`) | Default | |
842
+ | Option (`prepareImage`) | Default | Notes |
842
843
  | ----------------------- | ------- | - |
843
844
  | `maxWidth` / `maxHeight` | none | only ever makes images smaller |
844
845
  | `maxPixels` | 16,777,216 | Safari's canvas limit |
@@ -856,6 +857,96 @@ const { blob, removed } = await stripMetadata(file); // bit-for-bit the same pic
856
857
  their orientation, and Chromium doesn't turn WebP. `removed` is read back from the
857
858
  output, not assumed, because some browsers' encoders add their own colour profile.
858
859
 
860
+ ## Pasted and dropped files: safe by content
861
+
862
+ `react-smart-copy/files` takes the files people paste or drop, whole folders included, and
863
+ decides for each one whether it is safe and wanted. The type comes from the file's content,
864
+ never from its name or the type the browser claims. So an HTML page named `invoice.pdf`, a
865
+ program named `invoice.pdf.exe`, or a name that hides its real extension behind a
866
+ right-to-left character is turned away, with a reason you can show. No dependencies, about
867
+ 6.9 kB (about 2.3 kB for `safeFileName` alone). It works the same on a server.
868
+
869
+ ```tsx
870
+ import { acceptFiles } from "react-smart-copy/files";
871
+
872
+ <div
873
+ onDragOver={(event) => event.preventDefault()}
874
+ onDrop={(event) => {
875
+ event.preventDefault();
876
+ // Call it in the handler, before any await: the browser empties the drop when the event ends.
877
+ void acceptFiles(event, { accept: ".pdf,image/*", maxFileBytes: 20_000_000, digest: true }).then(({ accepted, rejected }) => {
878
+ for (const file of accepted) upload(file.upload, file.path); // safe name, real type
879
+ for (const file of rejected) toast(file.message); // "invoice.pdf.exe is a program or script, which can't be added."
880
+ });
881
+ }}
882
+ />
883
+ ```
884
+
885
+ It takes a drop or paste event (DOM or React), its `DataTransfer`, the `FileList` of an
886
+ `<input type="file">`, or any list of files. With `usePaste` and `PasteField`, pass the
887
+ result's `files`.
888
+
889
+ **Known by content.** The first 8 KB of each file is read, and more than 50 formats are
890
+ recognised by their signatures: PDF; images (JPEG, PNG, GIF, WebP, AVIF, HEIC, TIFF, BMP,
891
+ ICO, PSD, SVG); audio and video; Office and OpenDocument files, told apart inside their
892
+ ZIP; archives; fonts; SQLite; HTML, XML, JSON and other text; and programs (Windows, Linux
893
+ and macOS executables, WebAssembly, Java and Android archives, shortcuts and scripts). Each
894
+ accepted file's `type` is the detected one, never the claimed one: `upload` is the same
895
+ bytes as a `File` with that type and the safe name.
896
+
897
+ **Risky files are rejected by default.** Each file is checked for these risks, and by
898
+ default any of them rejects it. Pass `block` to choose which ones do.
899
+
900
+ | Risk | What it catches |
901
+ | --- | --- |
902
+ | `executable` | Programs and scripts, by content or by a name the system runs (`.exe`, `.bat`, `.ps1`, `.js`, `.jar`, `.iso`, `.lnk`, ...) |
903
+ | `active-content` | HTML and SVG, and XML with XHTML or scripts: they run script when opened from your site |
904
+ | `macros` | Office files that can hold macros (`.docm`, `.xlsm`, or a `vbaProject.bin` inside) |
905
+ | `type-mismatch` | The content is not what the extension says: `report.pdf` holding HTML |
906
+ | `double-extension` | `invoice.pdf.exe`, or `invoice.pdf .exe` |
907
+ | `hidden-characters` | Bidirectional controls and invisible characters in the name: `photo\u202Egpj.exe` shows as `photoexe.jpg` |
908
+ | `empty` | No bytes: often a folder dropped where folders aren't read |
909
+
910
+ **Folders, within limits.** Dropped folders are walked depth-first, and each file's
911
+ `path` keeps where it was (`photos/2024/a.jpg`). `maxFiles` (100), `maxFileBytes`
912
+ (100 MiB), `maxTotalBytes` (1 GiB) and `maxDepth` (8) bound the walk, so a dropped home
913
+ folder can't hang the page. With `digest: true`, each file's SHA-256 is computed and a
914
+ repeated file is rejected as a `duplicate`.
915
+
916
+ **Names safe everywhere.** `safeFileName` keeps only the last path segment (no `../`),
917
+ removes hidden and control characters, replaces the characters Windows, macOS and Linux
918
+ reject, prefixes Windows device names (`CON`, `NUL`, `COM1`), and fits the name to 255
919
+ UTF-8 bytes, keeping its extension.
920
+
921
+ ```ts
922
+ import { inspectFile, safeFileName } from "react-smart-copy/files";
923
+
924
+ // In the browser or on a server (Node 18+), for a file you already have.
925
+ const inspection = await inspectFile(file);
926
+ // { name: "invoice.pdf", safeName: "invoice.pdf", extension: "pdf", type: "text/html",
927
+ // detected: { mime: "text/html", family: "text", ... }, mismatch: true,
928
+ // risks: ["active-content", "type-mismatch"], ... }
929
+
930
+ safeFileName("../../uploads/CON.txt"); // "_CON.txt"
931
+ ```
932
+
933
+ | Option (`acceptFiles`) | Default | Notes |
934
+ | --- | --- | --- |
935
+ | `accept` | any | as in `<input accept>`: `".pdf,image/*"`, judged by content |
936
+ | `block` | every risk | `[]` accepts risky files; their `inspection.risks` still say |
937
+ | `maxFiles` | 100 | the walk stops at the next file, and `truncated` is `true` |
938
+ | `maxFileBytes` / `maxTotalBytes` | 100 MiB / 1 GiB | |
939
+ | `folders` / `maxDepth` | `true` / 8 | |
940
+ | `digest` | `false` | SHA-256 for each file, and `duplicate` rejections; needs Web Crypto (a secure page, or Node.js 20+) |
941
+ | `names` | | `maxBytes`, `replacement` and `fallback` for `safeFileName` |
942
+ | `signal` | none | aborts with an `aborted` CopyFailure |
943
+
944
+ Each rejection has a `reason` (`blocked`, `not-accepted`, `too-large`, `total-too-large`,
945
+ `too-many`, `too-deep`, `unreadable` or `duplicate`), the file's `risks`, and a `message`
946
+ that names the file by its safe name. Checking files in the browser is for the people
947
+ using your app: check them again on your server, where `inspectFile` works the same, and
948
+ serve uploads with `Content-Disposition: attachment` and `X-Content-Type-Options: nosniff`.
949
+
859
950
  ## Copy links
860
951
 
861
952
  `react-smart-copy/link` is for "Copy link" and "Share" buttons, and for fields people
@@ -932,7 +1023,7 @@ usePaste({ accept: ["text", "html", "text/uri-list"], onPaste: (result) => {
932
1023
  } });
933
1024
  ```
934
1025
 
935
- | Option | Default | |
1026
+ | Option | Default | Notes |
936
1027
  | ------ | ------- | - |
937
1028
  | `text` | `"url"` | plain text: `"url"`, `"title"`, `"title-and-url"` or `"markdown"` |
938
1029
  | `target` | clipboard | `"drag"` adds `text/uri-list` and `text/x-moz-url` |
@@ -1000,7 +1091,7 @@ The output is property-tested against hostile HTML. [DOMPurify](https://github.c
1000
1091
  finds nothing to remove from it, and running the output through again changes nothing.
1001
1092
  In Chromium, Firefox and WebKit, the computed styles are checked end to end.
1002
1093
 
1003
- | Option | Default | |
1094
+ | Option | Default | Notes |
1004
1095
  | --- | --- | --- |
1005
1096
  | `colors` | `"readable"` | `"keep"`, `"none"` |
1006
1097
  | `background` | `"#ffffff"` | where it is pasted, for readability |
@@ -1136,7 +1227,7 @@ contrastLevel(contrastRatio("#767676", "#fff")); // "AA" (4.54)
1136
1227
  parseColor("hsl(1turn 100% 50% / 50%)"); // { r: 1, g: 0, b: 0, alpha: 0.5 }
1137
1228
  ```
1138
1229
 
1139
- | Option (`formatColor`, `colorPayload`) | Default | |
1230
+ | Option (`formatColor`, `colorPayload`) | Default | Notes |
1140
1231
  | --- | --- | --- |
1141
1232
  | `format` | `"hex"` | `colorPayload` only |
1142
1233
  | `gamut` | `"map"` | `"clip"` |
@@ -1673,8 +1764,9 @@ embedded webviews. Where a capability is missing you get a typed error, never a
1673
1764
  - ~~**1.17** `react-smart-copy/rich` — styled content that pastes as it looks in mail, Docs, Word and Slack, for buttons and Ctrl/⌘+C~~ shipped
1674
1765
  - ~~**1.18** One shared copy of the core across entry points: smaller bundles when you use several modules, and one `CopyFailure` class~~ shipped
1675
1766
  - ~~**1.19** `react-smart-copy/rich`, paste side: paste from Word, Google Docs and web pages into rich-text editors as clean, safe HTML~~ shipped
1767
+ - ~~**1.20** `react-smart-copy/files` — take pasted and dropped files and folders safely: types from content, risky files rejected, safe names, limits~~ shipped
1676
1768
 
1677
- Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/#releases).
1769
+ Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/project/releases/).
1678
1770
 
1679
1771
  ## Development
1680
1772
 
@@ -1682,8 +1774,9 @@ Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://supr
1682
1774
  npm install
1683
1775
  npm run verify # lint, types, tests at 100% coverage, build, publint + attw, consumer types, size budgets
1684
1776
  npm run changeset # describe your change for the changelog
1685
- npm run site:preview # docs site at http://localhost:3000
1686
- npm run site:build && npm run test:e2e # end-to-end tests in Chromium, Firefox and WebKit
1777
+ npm run docs:install # once: the docs site has its own lockfile, in docs/
1778
+ npm run docs:dev # the docs, with live demos, at http://localhost:4321/react-smart-copy/
1779
+ npm run docs:build && npm run test:e2e # end-to-end tests in Chromium, Firefox and WebKit
1687
1780
  ```
1688
1781
 
1689
1782
  Releases are automated: merging the "chore: release" PR publishes to npm through