react-smart-copy 1.8.1 → 1.10.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/dist/core.d.cts CHANGED
@@ -3,8 +3,9 @@
3
3
  type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
4
4
  /**
5
5
  * What a paste may contain, in any order: a shorthand, an exact MIME type
6
- * (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
7
- * `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
6
+ * (`'image/png'`), a web custom format (`'web application/vnd.acme+json'`) or a
7
+ * wildcard (`'image/*'`, `'*\/*'`). `image/svg+xml` (scriptable XML), web custom
8
+ * formats and `+json` types are only accepted when listed exactly.
8
9
  */
9
10
  type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
10
11
  interface PasteLimits {
@@ -211,8 +212,19 @@ export interface JsonPayload {
211
212
  readonly pretty?: boolean | number;
212
213
  }
213
214
  export interface MultiPayloadItem {
215
+ /**
216
+ * The MIME type, or a web custom format (`web application/vnd.acme+json`).
217
+ * Web custom formats are only written by the async Clipboard API; copy and drag
218
+ * events skip them.
219
+ */
214
220
  readonly mimeType: string;
215
221
  readonly data: string | Blob;
222
+ /**
223
+ * Skip this item, instead of failing the copy, when the browser cannot write its type.
224
+ * An optional item is only written when `ClipboardItem.supports()` confirms the type.
225
+ * At least one item must be written.
226
+ */
227
+ readonly optional?: boolean;
216
228
  }
217
229
  export interface MultiPayload {
218
230
  readonly kind: 'multi';
@@ -247,9 +259,18 @@ export declare function serializeJson(payload: JsonPayload): string;
247
259
  export declare const SVG_MIME_TYPE = "image/svg+xml";
248
260
  /** Lower-cased `type/subtype` without parameters, or `null` if it is not a valid MIME type. */
249
261
  export declare function normalizeMimeType(value: string): string | null;
262
+ /** Prefix of the async Clipboard API's web custom formats (`web application/vnd.acme+json`). */
263
+ export declare const WEB_CUSTOM_FORMAT_PREFIX = "web ";
264
+ /** Whether a clipboard type is a web custom format (`web type/subtype`). */
265
+ export declare function isWebCustomFormat(type: string): boolean;
266
+ /**
267
+ * Like {@link normalizeMimeType}, but also accepts web custom formats
268
+ * (`web type/subtype`), returned as `web ` + the normalised MIME type.
269
+ */
270
+ export declare function normalizeClipboardType(value: string): string | null;
250
271
  /**
251
272
  * Does `mimeType` (already normalised) match `pattern` (`type/subtype`, `type/*` or `*\/*`)?
252
- * Wildcards never match `image/svg+xml`: accepting SVG must be explicit.
273
+ * Wildcards never match `image/svg+xml`, web custom formats or `+json` types: those must be listed exactly.
253
274
  */
254
275
  export declare function matchesMimePattern(mimeType: string, pattern: string): boolean;
255
276
  /** Types whose clipboard data is text and is therefore surfaced as a `string`. */
@@ -468,12 +489,16 @@ export interface CopySelection {
468
489
  /** Whether a `cut` would remove the selection (form field or contenteditable). */
469
490
  readonly editable: boolean;
470
491
  }
471
- /** A multi payload whose items are all strings; the only kind `setData` accepts. */
492
+ /**
493
+ * A multi payload whose items are all strings; the only kind `setData` accepts.
494
+ * Web custom formats (`web …`) are skipped: only the async Clipboard API writes them.
495
+ */
472
496
  export interface SyncMultiPayload {
473
497
  readonly kind: 'multi';
474
498
  readonly items: readonly {
475
499
  readonly mimeType: string;
476
500
  readonly data: string;
501
+ readonly optional?: boolean;
477
502
  }[];
478
503
  }
479
504
  /** Payloads writable synchronously during a copy event. Images need the async clipboard. */
@@ -574,8 +599,11 @@ export declare function registerCopyInterceptor(root: Element, options: CopyInte
574
599
  export type DragEffectAllowed = 'copy' | 'move' | 'link' | 'copyMove' | 'copyLink' | 'linkMove' | 'all' | 'none' | 'uninitialized';
575
600
  /** What is put into `DataTransfer` when a drag starts. */
576
601
  export interface DragCopyItem {
602
+ /** Web custom formats (`web …`) are skipped: only the async Clipboard API writes them. */
577
603
  readonly mimeType: string;
578
604
  readonly data: string;
605
+ /** Accepted for parity with `MultiPayloadItem`; every non-web item can be written to a drag. */
606
+ readonly optional?: boolean;
579
607
  }
580
608
  /**
581
609
  * A multi-format drag payload — strings only (DataTransfer only accepts strings).
package/dist/core.d.ts CHANGED
@@ -3,8 +3,9 @@
3
3
  type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
4
4
  /**
5
5
  * What a paste may contain, in any order: a shorthand, an exact MIME type
6
- * (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
7
- * `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
6
+ * (`'image/png'`), a web custom format (`'web application/vnd.acme+json'`) or a
7
+ * wildcard (`'image/*'`, `'*\/*'`). `image/svg+xml` (scriptable XML), web custom
8
+ * formats and `+json` types are only accepted when listed exactly.
8
9
  */
9
10
  type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
10
11
  interface PasteLimits {
@@ -211,8 +212,19 @@ export interface JsonPayload {
211
212
  readonly pretty?: boolean | number;
212
213
  }
213
214
  export interface MultiPayloadItem {
215
+ /**
216
+ * The MIME type, or a web custom format (`web application/vnd.acme+json`).
217
+ * Web custom formats are only written by the async Clipboard API; copy and drag
218
+ * events skip them.
219
+ */
214
220
  readonly mimeType: string;
215
221
  readonly data: string | Blob;
222
+ /**
223
+ * Skip this item, instead of failing the copy, when the browser cannot write its type.
224
+ * An optional item is only written when `ClipboardItem.supports()` confirms the type.
225
+ * At least one item must be written.
226
+ */
227
+ readonly optional?: boolean;
216
228
  }
217
229
  export interface MultiPayload {
218
230
  readonly kind: 'multi';
@@ -247,9 +259,18 @@ export declare function serializeJson(payload: JsonPayload): string;
247
259
  export declare const SVG_MIME_TYPE = "image/svg+xml";
248
260
  /** Lower-cased `type/subtype` without parameters, or `null` if it is not a valid MIME type. */
249
261
  export declare function normalizeMimeType(value: string): string | null;
262
+ /** Prefix of the async Clipboard API's web custom formats (`web application/vnd.acme+json`). */
263
+ export declare const WEB_CUSTOM_FORMAT_PREFIX = "web ";
264
+ /** Whether a clipboard type is a web custom format (`web type/subtype`). */
265
+ export declare function isWebCustomFormat(type: string): boolean;
266
+ /**
267
+ * Like {@link normalizeMimeType}, but also accepts web custom formats
268
+ * (`web type/subtype`), returned as `web ` + the normalised MIME type.
269
+ */
270
+ export declare function normalizeClipboardType(value: string): string | null;
250
271
  /**
251
272
  * Does `mimeType` (already normalised) match `pattern` (`type/subtype`, `type/*` or `*\/*`)?
252
- * Wildcards never match `image/svg+xml`: accepting SVG must be explicit.
273
+ * Wildcards never match `image/svg+xml`, web custom formats or `+json` types: those must be listed exactly.
253
274
  */
254
275
  export declare function matchesMimePattern(mimeType: string, pattern: string): boolean;
255
276
  /** Types whose clipboard data is text and is therefore surfaced as a `string`. */
@@ -468,12 +489,16 @@ export interface CopySelection {
468
489
  /** Whether a `cut` would remove the selection (form field or contenteditable). */
469
490
  readonly editable: boolean;
470
491
  }
471
- /** A multi payload whose items are all strings; the only kind `setData` accepts. */
492
+ /**
493
+ * A multi payload whose items are all strings; the only kind `setData` accepts.
494
+ * Web custom formats (`web …`) are skipped: only the async Clipboard API writes them.
495
+ */
472
496
  export interface SyncMultiPayload {
473
497
  readonly kind: 'multi';
474
498
  readonly items: readonly {
475
499
  readonly mimeType: string;
476
500
  readonly data: string;
501
+ readonly optional?: boolean;
477
502
  }[];
478
503
  }
479
504
  /** Payloads writable synchronously during a copy event. Images need the async clipboard. */
@@ -574,8 +599,11 @@ export declare function registerCopyInterceptor(root: Element, options: CopyInte
574
599
  export type DragEffectAllowed = 'copy' | 'move' | 'link' | 'copyMove' | 'copyLink' | 'linkMove' | 'all' | 'none' | 'uninitialized';
575
600
  /** What is put into `DataTransfer` when a drag starts. */
576
601
  export interface DragCopyItem {
602
+ /** Web custom formats (`web …`) are skipped: only the async Clipboard API writes them. */
577
603
  readonly mimeType: string;
578
604
  readonly data: string;
605
+ /** Accepted for parity with `MultiPayloadItem`; every non-web item can be written to a drag. */
606
+ readonly optional?: boolean;
579
607
  }
580
608
  /**
581
609
  * A multi-format drag payload — strings only (DataTransfer only accepts strings).
package/dist/core.js CHANGED
@@ -196,19 +196,43 @@ function normalizeMimeType(value) {
196
196
  const base = (separator === -1 ? value : value.slice(0, separator)).trim().toLowerCase();
197
197
  return MIME_SHAPE.test(base) ? base : null;
198
198
  }
199
+ /** Prefix of the async Clipboard API's web custom formats (`web application/vnd.acme+json`). */
200
+ const WEB_CUSTOM_FORMAT_PREFIX = "web ";
201
+ /** Whether a clipboard type is a web custom format (`web type/subtype`). */
202
+ function isWebCustomFormat(type) {
203
+ return type.slice(0, 4).toLowerCase() === WEB_CUSTOM_FORMAT_PREFIX;
204
+ }
205
+ /**
206
+ * Like {@link normalizeMimeType}, but also accepts web custom formats
207
+ * (`web type/subtype`), returned as `web ` + the normalised MIME type.
208
+ */
209
+ function normalizeClipboardType(value) {
210
+ if (!isWebCustomFormat(value)) return normalizeMimeType(value);
211
+ const inner = normalizeMimeType(value.slice(4));
212
+ return inner === null ? null : WEB_CUSTOM_FORMAT_PREFIX + inner;
213
+ }
214
+ /**
215
+ * Types a wildcard never matches, so accepting them must be explicit:
216
+ * `image/svg+xml` (scriptable XML), web custom formats and structured `+json` types
217
+ * (application-specific data that only the app that defined them should read).
218
+ */
219
+ function requiresExactMatch(mimeType) {
220
+ return mimeType === "image/svg+xml" || isWebCustomFormat(mimeType) || mimeType.endsWith("+json");
221
+ }
199
222
  /**
200
223
  * Does `mimeType` (already normalised) match `pattern` (`type/subtype`, `type/*` or `*\/*`)?
201
- * Wildcards never match `image/svg+xml`: accepting SVG must be explicit.
224
+ * Wildcards never match `image/svg+xml`, web custom formats or `+json` types: those must be listed exactly.
202
225
  */
203
226
  function matchesMimePattern(mimeType, pattern) {
204
227
  if (pattern === mimeType) return true;
205
- if (mimeType === "image/svg+xml") return false;
228
+ if (requiresExactMatch(mimeType)) return false;
206
229
  if (pattern === "*/*") return true;
207
230
  return pattern.endsWith("/*") && mimeType.startsWith(pattern.slice(0, -1));
208
231
  }
209
232
  /** Types whose clipboard data is text and is therefore surfaced as a `string`. */
210
233
  function isTextualMimeType(mimeType) {
211
- return mimeType.startsWith("text/") || mimeType === "image/svg+xml" || mimeType === "application/json" || mimeType === "application/xml";
234
+ const type = isWebCustomFormat(mimeType) ? mimeType.slice(4) : mimeType;
235
+ return type.startsWith("text/") || type === "image/svg+xml" || type === "application/json" || type === "application/xml" || type.endsWith("+json");
212
236
  }
213
237
  const SNIFF_BYTES = 16;
214
238
  function startsWith(bytes, signature, offset = 0) {
@@ -324,10 +348,14 @@ async function writeToClipboard(payload, env, degradeHtmlToText, context) {
324
348
  const rich = getRichClipboard(env, clipboard);
325
349
  if (!rich) throw fail("unsupported-format", "Multi-format copy requires ClipboardItem and navigator.clipboard.write().");
326
350
  const record = Object.create(null);
327
- for (const { mimeType, data } of payload.items) {
351
+ let written = 0;
352
+ for (const { mimeType, data, optional } of payload.items) {
353
+ if (optional === true && !(typeof rich.Item.supports === "function" && rich.Item.supports(mimeType))) continue;
328
354
  if (!isTypeSupported(rich.Item, mimeType)) throw fail("unsupported-format", `This browser cannot write "${mimeType}" to the clipboard.`);
329
355
  record[mimeType] = typeof data === "string" ? new Blob([data], { type: mimeType }) : data;
356
+ written += 1;
330
357
  }
358
+ if (written === 0) throw fail("unsupported-format", "This browser can write none of the payload types.");
331
359
  return rich.write([new rich.Item(record)]);
332
360
  }
333
361
  }
@@ -404,6 +432,17 @@ function createOperations() {
404
432
  };
405
433
  }
406
434
  //#endregion
435
+ //#region src/core/source-error.ts
436
+ /**
437
+ * The error for a user-supplied source (copy source, drag source, copy transform)
438
+ * that threw. A thrown `CopyFailure` keeps its classification, so a helper such as
439
+ * `tablePayload()` can report `too-large` instead of a generic `invalid-payload`.
440
+ * Internal: not part of the public API.
441
+ */
442
+ function sourceError(cause, message) {
443
+ return isCopyFailure(cause) ? cause.copyError : createCopyError("invalid-payload", message, cause);
444
+ }
445
+ //#endregion
407
446
  //#region src/core/copy-machine.ts
408
447
  const DEFAULT_RESET_AFTER_MS = 2e3;
409
448
  const IDLE_STATE = /* @__PURE__ */ Object.freeze({ status: "idle" });
@@ -506,7 +545,7 @@ function createCopyMachine(options = {}) {
506
545
  }
507
546
  payload = normalizePayload(resolved);
508
547
  } catch (cause) {
509
- const error = createCopyError("invalid-payload", "The copy source function threw.", cause);
548
+ const error = sourceError(cause, "The copy source function threw.");
510
549
  settleError(error, null, retryCount);
511
550
  return Promise.resolve({
512
551
  status: "error",
@@ -746,7 +785,8 @@ function prepare(decision) {
746
785
  if (typeof data !== "string") return unsupported$1(`Multi item "${mimeType}" must be a string during a copy event.`);
747
786
  entries.push([mimeType, data]);
748
787
  }
749
- return ok(entries);
788
+ const writable = entries.filter(([mimeType]) => !isWebCustomFormat(mimeType));
789
+ return writable.length > 0 ? ok(writable) : unsupported$1("Web custom formats need the async Clipboard API (useCopy).");
750
790
  }
751
791
  default: return unsupported$1(`"${String(fields["kind"])}" payloads cannot be written during a copy event; use useCopy() for images.`);
752
792
  }
@@ -796,7 +836,7 @@ function interceptCopyEvent(event, options) {
796
836
  try {
797
837
  decision = options.transform(selection);
798
838
  } catch (cause) {
799
- return fail(createCopyError("invalid-payload", "The copy transform threw.", cause));
839
+ return fail(sourceError(cause, "The copy transform threw."));
800
840
  }
801
841
  if (decision === null || decision === void 0) return {
802
842
  status: "passed",
@@ -982,7 +1022,8 @@ function prepareDragDecision(decision) {
982
1022
  data
983
1023
  });
984
1024
  }
985
- return ok(out);
1025
+ const writable = out.filter((item) => !isWebCustomFormat(item.mimeType));
1026
+ return writable.length > 0 ? ok(writable) : unsupported("Web custom formats need the async Clipboard API (useCopy).");
986
1027
  }
987
1028
  default: return unsupported(`"${String(fields["kind"])}" payloads cannot be used for drag-copy; use useCopy() for images.`);
988
1029
  }
@@ -1003,7 +1044,7 @@ function applyDragCopy(event, options) {
1003
1044
  } catch (cause) {
1004
1045
  return {
1005
1046
  status: "failed",
1006
- error: createCopyError("invalid-payload", "The drag source threw.", cause)
1047
+ error: sourceError(cause, "The drag source threw.")
1007
1048
  };
1008
1049
  }
1009
1050
  if (decision === null || decision === void 0) return {
@@ -1132,7 +1173,7 @@ function resolvePattern(entry) {
1132
1173
  const type = entry.slice(0, -2).toLowerCase();
1133
1174
  return TYPE_TOKEN.test(type) ? `${type}/*` : null;
1134
1175
  }
1135
- return normalizeMimeType(entry);
1176
+ return normalizeClipboardType(entry);
1136
1177
  }
1137
1178
  function resolveLimit(value, fallback, name) {
1138
1179
  if (value === void 0) return fallback;
@@ -1208,7 +1249,7 @@ function canAcceptDrag(data, options) {
1208
1249
  });
1209
1250
  return Array.from(items).some(({ kind, type: raw }) => {
1210
1251
  const file = kind === "file";
1211
- const type = normalizeMimeType(raw);
1252
+ const type = normalizeClipboardType(raw);
1212
1253
  if (type === null) return file;
1213
1254
  return (file || isTextualMimeType(type)) && isAccepted(type, options);
1214
1255
  });
@@ -1221,7 +1262,7 @@ function snapshotDataTransfer(data, options) {
1221
1262
  const entries = [];
1222
1263
  const seen = /* @__PURE__ */ new Set();
1223
1264
  for (const raw of Array.from(data.types)) {
1224
- const type = normalizeMimeType(raw);
1265
+ const type = normalizeClipboardType(raw);
1225
1266
  if (type === null || seen.has(type) || !isTextualMimeType(type) || !isAccepted(type, options)) continue;
1226
1267
  seen.add(type);
1227
1268
  const text = data.getData(raw);
@@ -1250,7 +1291,7 @@ async function collectClipboardItems(items, options, signal) {
1250
1291
  const entries = [];
1251
1292
  const seen = /* @__PURE__ */ new Set();
1252
1293
  for (const item of items) for (const raw of item.types) {
1253
- const type = normalizeMimeType(raw);
1294
+ const type = normalizeClipboardType(raw);
1254
1295
  if (type === null || seen.has(type) || !isAccepted(type, options)) continue;
1255
1296
  seen.add(type);
1256
1297
  let blob;
@@ -1569,6 +1610,6 @@ function createPasteMachine(options = {}) {
1569
1610
  };
1570
1611
  }
1571
1612
  //#endregion
1572
- export { CopyFailure, DEFAULT_INTERCEPTED_EVENTS, DEFAULT_MAX_RETRIES, DEFAULT_PASTE_ACCEPT, DEFAULT_PASTE_MAX_BYTES, DEFAULT_PASTE_MAX_ITEMS, DEFAULT_RESET_AFTER_MS, IDLE_STATE, IMAGE_MIME_TYPE, PASTE_IDLE_STATE, SVG_MIME_TYPE, applyDragCopy, canAcceptDrag, canRetryPasteState, canRetryState, copyFailure, createBrowserClipboardAdapter, createBrowserPasteAdapter, createCopyCoordinator, createCopyError, createCopyMachine, createPasteMachine, describeCopyError, describePasteError, interceptCopyEvent, isBlob, isCopyFailure, isRetryableError, isTextualMimeType, matchesMimePattern, normalizeMimeType, normalizePayload, readCopySelection, registerCopyInterceptor, registerDragCopy, resolveMaxRetries, resolvePasteReadOptions, serializeJson, sniffImageBytes, sniffImageType, toCopyError, validatePayload };
1613
+ export { CopyFailure, DEFAULT_INTERCEPTED_EVENTS, DEFAULT_MAX_RETRIES, DEFAULT_PASTE_ACCEPT, DEFAULT_PASTE_MAX_BYTES, DEFAULT_PASTE_MAX_ITEMS, DEFAULT_RESET_AFTER_MS, IDLE_STATE, IMAGE_MIME_TYPE, PASTE_IDLE_STATE, SVG_MIME_TYPE, WEB_CUSTOM_FORMAT_PREFIX, applyDragCopy, canAcceptDrag, canRetryPasteState, canRetryState, copyFailure, createBrowserClipboardAdapter, createBrowserPasteAdapter, createCopyCoordinator, createCopyError, createCopyMachine, createPasteMachine, describeCopyError, describePasteError, interceptCopyEvent, isBlob, isCopyFailure, isRetryableError, isTextualMimeType, isWebCustomFormat, matchesMimePattern, normalizeClipboardType, normalizeMimeType, normalizePayload, readCopySelection, registerCopyInterceptor, registerDragCopy, resolveMaxRetries, resolvePasteReadOptions, serializeJson, sniffImageBytes, sniffImageType, toCopyError, validatePayload };
1573
1614
 
1574
1615
  //# sourceMappingURL=core.js.map