react-smart-copy 1.2.0 → 1.3.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 +35 -3
- package/dist/core.cjs +47 -8
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.cts +48 -3
- package/dist/core.d.ts +48 -3
- package/dist/core.js +47 -8
- package/dist/core.js.map +1 -1
- package/dist/index.cjs +47 -8
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +48 -3
- package/dist/index.d.ts +48 -3
- package/dist/index.js +47 -8
- package/dist/index.js.map +1 -1
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -268,14 +268,29 @@ keeps working. Events with accepted content are `preventDefault()`-ed (opt out w
|
|
|
268
268
|
`preventDefault: false`).
|
|
269
269
|
|
|
270
270
|
**Result.** `result.text`, `result.html`, `result.images` (verified raster images),
|
|
271
|
-
`result.files` (files copied in the OS file manager),
|
|
271
|
+
`result.files` (files copied in the OS file manager), `result.imageFiles` (the files that are
|
|
272
|
+
verified images, with their names kept, ready for `FormData`), and `result.items` with everything.
|
|
273
|
+
|
|
274
|
+
```ts
|
|
275
|
+
onPaste: ({ imageFiles }) => {
|
|
276
|
+
const form = new FormData();
|
|
277
|
+
for (const file of imageFiles) form.append("attachments", file, file.name);
|
|
278
|
+
void fetch("/api/attachments", { method: "POST", body: form });
|
|
279
|
+
};
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
A screenshot read with the paste button arrives as an unnamed `Blob` in `images` only; files
|
|
283
|
+
pasted from the OS file manager arrive in `files`, and the verified ones also in `imageFiles`.
|
|
284
|
+
Custom adapters resolve without `imageFiles` (`PasteReadResult`); the machine derives it.
|
|
272
285
|
|
|
273
286
|
**Security.** Everything pasted is untrusted input, and the defaults are strict:
|
|
274
287
|
|
|
275
288
|
- `accept` defaults to `['text']`. Ask for `'html'`, `'image'`, exact types like `'application/pdf'`, or `'image/*'` explicitly
|
|
276
289
|
- Images are verified from their bytes (PNG, JPEG, GIF, WebP, AVIF, BMP); a "PNG" that isn't one is dropped
|
|
277
290
|
- SVG is never matched by a wildcard, it must be listed exactly as `'image/svg+xml'` (it is scriptable XML)
|
|
278
|
-
- `maxBytes` (default 32 MiB) and `maxItems` (default 32) are enforced before anything is decoded
|
|
291
|
+
- `maxBytes` (default 32 MiB) and `maxItems` (default 32) are enforced before anything is decoded.
|
|
292
|
+
`maxBytes` counts UTF-8 bytes on every path, so `'日本'` costs 6 bytes whether it arrives
|
|
293
|
+
from a paste event, `readText()` or `read()`
|
|
279
294
|
- **Never render `result.html` without a sanitiser** such as DOMPurify
|
|
280
295
|
|
|
281
296
|
States: `idle` → `reading` → `read` | `error`. `paste()` is ignored while reading; a keyboard
|
|
@@ -349,6 +364,8 @@ useCopy({
|
|
|
349
364
|
maxRetries: 3,
|
|
350
365
|
onCopy: (payload) => {}, // inline functions are fine; the latest one is always used
|
|
351
366
|
onError: (error, payload) => {},
|
|
367
|
+
onReset: () => {}, // reset() left a non-idle state (not the automatic reset)
|
|
368
|
+
onCancel: (reason) => {}, // "reset" | "disconnect": a copy in flight was cancelled
|
|
352
369
|
adapter: myAdapter, // swap the clipboard backend (tests, Electron, native bridges)
|
|
353
370
|
coordinator: null, // opt out of the surrounding <CopyGroup>
|
|
354
371
|
});
|
|
@@ -370,6 +387,21 @@ the promise you awaited resolves `{ status: "ignored", reason: "cancelled" }` ra
|
|
|
370
387
|
error, and `onError` is not called, so you never toast a failure for work the user walked away
|
|
371
388
|
from. Adapters and sources written before 1.2 keep working: the argument is optional.
|
|
372
389
|
|
|
390
|
+
To observe cancellations (for analytics, or to clean up your own work), pass `onCancel`. It
|
|
391
|
+
receives why the operation stopped: `"reset"`, `"disconnect"` (the component unmounted) or, for
|
|
392
|
+
paste only, `"superseded"` (a paste event replaced a Clipboard API read). It fires once per
|
|
393
|
+
cancelled operation and never for one the library has already settled, so React Strict Mode's
|
|
394
|
+
extra mount/unmount does not trigger it. (If the clipboard resolves in the same tick as the
|
|
395
|
+
cancellation, the awaited promise may still report the result; state is not updated.) When
|
|
396
|
+
`reset()` cancels work, `onCancel("reset")` runs first, then `onReset()`.
|
|
397
|
+
|
|
398
|
+
```ts
|
|
399
|
+
usePaste({
|
|
400
|
+
onCancel: (reason) => analytics.track("paste_cancelled", { reason }),
|
|
401
|
+
onReset: () => setDraft(""),
|
|
402
|
+
});
|
|
403
|
+
```
|
|
404
|
+
|
|
373
405
|
## CopyField API
|
|
374
406
|
|
|
375
407
|
| Part | Renders | Notes |
|
|
@@ -515,7 +547,7 @@ embedded webviews. Where a capability is missing you get a typed error, never a
|
|
|
515
547
|
- ~~**1.0** Frozen API, SSR / security / accessibility audit~~ shipped
|
|
516
548
|
- ~~**1.1** `PasteField`~~ shipped
|
|
517
549
|
- ~~**1.2** Paste `retry()`, cancellation with `AbortSignal`, `PasteField.Preview`~~ shipped
|
|
518
|
-
- **
|
|
550
|
+
- ~~**1.3** `onReset` / `onCancel` callbacks, UTF-8 `maxBytes` on every paste path, `PasteResult.imageFiles`~~ shipped
|
|
519
551
|
|
|
520
552
|
Full history: [CHANGELOG.md](./CHANGELOG.md) or the [Releases page](https://suprabhat02.github.io/react-smart-copy/#releases).
|
|
521
553
|
|
package/dist/core.cjs
CHANGED
|
@@ -377,8 +377,10 @@ function invoke(fn, ...args) {
|
|
|
377
377
|
function createOperations() {
|
|
378
378
|
let controller;
|
|
379
379
|
const abort = () => {
|
|
380
|
-
controller
|
|
380
|
+
if (!controller) return false;
|
|
381
|
+
controller.abort();
|
|
381
382
|
controller = void 0;
|
|
383
|
+
return true;
|
|
382
384
|
};
|
|
383
385
|
return {
|
|
384
386
|
start: () => {
|
|
@@ -566,17 +568,21 @@ function createCopyMachine(options = {}) {
|
|
|
566
568
|
};
|
|
567
569
|
const reset = () => {
|
|
568
570
|
++generation;
|
|
569
|
-
operations.abort();
|
|
571
|
+
const cancelled = operations.abort();
|
|
570
572
|
clearResetTimer();
|
|
573
|
+
const wasIdle = state.status === "idle";
|
|
571
574
|
setState(IDLE_STATE);
|
|
575
|
+
if (cancelled) invoke(read().onCancel, "reset");
|
|
576
|
+
if (!wasIdle) invoke(read().onReset);
|
|
572
577
|
};
|
|
573
578
|
const connect = () => {
|
|
574
579
|
if (state.status === "copied") scheduleReset(state);
|
|
575
580
|
return () => {
|
|
576
581
|
++generation;
|
|
577
|
-
operations.abort();
|
|
582
|
+
const cancelled = operations.abort();
|
|
578
583
|
clearResetTimer();
|
|
579
584
|
if (state.status === "copying") setState(IDLE_STATE);
|
|
585
|
+
if (cancelled) invoke(read().onCancel, "disconnect");
|
|
580
586
|
};
|
|
581
587
|
};
|
|
582
588
|
return {
|
|
@@ -595,6 +601,14 @@ function createCopyMachine(options = {}) {
|
|
|
595
601
|
}
|
|
596
602
|
//#endregion
|
|
597
603
|
//#region src/core/paste-reader.ts
|
|
604
|
+
/** Adds the derived fields to an adapter's result. Any `imageFiles` it carried is recomputed. */
|
|
605
|
+
function completePasteResult(result) {
|
|
606
|
+
const images = new Set(result.images);
|
|
607
|
+
return {
|
|
608
|
+
...result,
|
|
609
|
+
imageFiles: result.files.filter((file) => images.has(file))
|
|
610
|
+
};
|
|
611
|
+
}
|
|
598
612
|
const DEFAULT_PASTE_ACCEPT = /* @__PURE__ */ Object.freeze(["text"]);
|
|
599
613
|
const DEFAULT_PASTE_MAX_BYTES = 33554432;
|
|
600
614
|
const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
@@ -650,7 +664,25 @@ function createBudget(options) {
|
|
|
650
664
|
if (bytes > options.maxBytes) throw copyFailure("too-large", `The paste exceeds the ${String(options.maxBytes)}-byte limit.`);
|
|
651
665
|
} };
|
|
652
666
|
}
|
|
653
|
-
|
|
667
|
+
/**
|
|
668
|
+
* UTF-8 byte length of a string, without allocating an encoded copy.
|
|
669
|
+
* Lone surrogates count 3 bytes, as `TextEncoder` / `Blob` encode them as U+FFFD.
|
|
670
|
+
*/
|
|
671
|
+
function utf8ByteLength(text) {
|
|
672
|
+
let bytes = 0;
|
|
673
|
+
for (let i = 0; i < text.length; i += 1) {
|
|
674
|
+
const unit = text.charCodeAt(i);
|
|
675
|
+
if (unit < 128) bytes += 1;
|
|
676
|
+
else if (unit < 2048) bytes += 2;
|
|
677
|
+
else if (unit >= 55296 && unit <= 56319 && i + 1 < text.length && (text.charCodeAt(i + 1) & 64512) === 56320) {
|
|
678
|
+
bytes += 4;
|
|
679
|
+
i += 1;
|
|
680
|
+
} else bytes += 3;
|
|
681
|
+
}
|
|
682
|
+
return bytes;
|
|
683
|
+
}
|
|
684
|
+
/** Strings are measured as UTF-8, the same unit `Blob.size` reports for clipboard items. */
|
|
685
|
+
const sizeOf = (data) => typeof data === "string" ? utf8ByteLength(data) : data.size;
|
|
654
686
|
/** Throws `too-large` when the entries break `maxItems` / `maxBytes`. */
|
|
655
687
|
function enforcePasteLimits(entries, options) {
|
|
656
688
|
const budget = createBudget(options);
|
|
@@ -894,15 +926,17 @@ function createPasteMachine(options = {}) {
|
|
|
894
926
|
const run = (produce, source, retryCount) => {
|
|
895
927
|
clearResetTimer();
|
|
896
928
|
const current = ++generation;
|
|
929
|
+
const superseded = operations.abort();
|
|
897
930
|
const context = operations.start();
|
|
898
931
|
setState(PASTE_READING_STATE);
|
|
932
|
+
if (superseded) invoke(read().onCancel, "superseded");
|
|
899
933
|
let pending;
|
|
900
934
|
try {
|
|
901
935
|
pending = produce(context);
|
|
902
936
|
} catch (cause) {
|
|
903
937
|
pending = Promise.reject(cause);
|
|
904
938
|
}
|
|
905
|
-
return pending.then((result) => {
|
|
939
|
+
return pending.then(completePasteResult).then((result) => {
|
|
906
940
|
operations.end(context);
|
|
907
941
|
if (current === generation) {
|
|
908
942
|
const readState = {
|
|
@@ -954,9 +988,10 @@ function createPasteMachine(options = {}) {
|
|
|
954
988
|
} catch (cause) {
|
|
955
989
|
const error = toCopyError(cause, "read");
|
|
956
990
|
++generation;
|
|
957
|
-
operations.abort();
|
|
991
|
+
const superseded = operations.abort();
|
|
958
992
|
clearResetTimer();
|
|
959
993
|
settleError(error, "event", 0);
|
|
994
|
+
if (superseded) invoke(current.onCancel, "superseded");
|
|
960
995
|
return Promise.resolve({
|
|
961
996
|
status: "error",
|
|
962
997
|
error
|
|
@@ -972,17 +1007,21 @@ function createPasteMachine(options = {}) {
|
|
|
972
1007
|
};
|
|
973
1008
|
const reset = () => {
|
|
974
1009
|
++generation;
|
|
975
|
-
operations.abort();
|
|
1010
|
+
const cancelled = operations.abort();
|
|
976
1011
|
clearResetTimer();
|
|
1012
|
+
const wasIdle = state.status === "idle";
|
|
977
1013
|
setState(PASTE_IDLE_STATE);
|
|
1014
|
+
if (cancelled) invoke(read().onCancel, "reset");
|
|
1015
|
+
if (!wasIdle) invoke(read().onReset);
|
|
978
1016
|
};
|
|
979
1017
|
const connect = () => {
|
|
980
1018
|
if (state.status === "read") scheduleReset(state);
|
|
981
1019
|
return () => {
|
|
982
1020
|
++generation;
|
|
983
|
-
operations.abort();
|
|
1021
|
+
const cancelled = operations.abort();
|
|
984
1022
|
clearResetTimer();
|
|
985
1023
|
if (state.status === "reading") setState(PASTE_IDLE_STATE);
|
|
1024
|
+
if (cancelled) invoke(read().onCancel, "disconnect");
|
|
986
1025
|
};
|
|
987
1026
|
};
|
|
988
1027
|
return {
|