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 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), and `result.items` with everything.
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
- - **Next** Consistent `maxBytes` accounting across paste paths, `onReset` / `onRelease` telemetry callbacks
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?.abort();
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
- const sizeOf = (data) => typeof data === "string" ? data.length : data.size;
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 {