react-smart-copy 1.9.0 → 1.11.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/index.d.cts CHANGED
@@ -5,8 +5,9 @@ import { ButtonHTMLAttributes, CSSProperties, ClipboardEventHandler, DragEventHa
5
5
  type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
6
6
  /**
7
7
  * What a paste may contain, in any order: a shorthand, an exact MIME type
8
- * (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
9
- * `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
8
+ * (`'image/png'`), a web custom format (`'web application/vnd.acme+json'`) or a
9
+ * wildcard (`'image/*'`, `'*\/*'`). `image/svg+xml` (scriptable XML), web custom
10
+ * formats and `+json` types are only accepted when listed exactly.
10
11
  */
11
12
  type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
12
13
  interface PasteLimits {
@@ -213,8 +214,19 @@ export interface JsonPayload {
213
214
  readonly pretty?: boolean | number;
214
215
  }
215
216
  export interface MultiPayloadItem {
217
+ /**
218
+ * The MIME type, or a web custom format (`web application/vnd.acme+json`).
219
+ * Web custom formats are only written by the async Clipboard API; copy and drag
220
+ * events skip them.
221
+ */
216
222
  readonly mimeType: string;
217
223
  readonly data: string | Blob;
224
+ /**
225
+ * Skip this item, instead of failing the copy, when the browser cannot write its type.
226
+ * An optional item is only written when `ClipboardItem.supports()` confirms the type.
227
+ * At least one item must be written.
228
+ */
229
+ readonly optional?: boolean;
218
230
  }
219
231
  export interface MultiPayload {
220
232
  readonly kind: 'multi';
@@ -249,9 +261,18 @@ export declare function serializeJson(payload: JsonPayload): string;
249
261
  export declare const SVG_MIME_TYPE = "image/svg+xml";
250
262
  /** Lower-cased `type/subtype` without parameters, or `null` if it is not a valid MIME type. */
251
263
  export declare function normalizeMimeType(value: string): string | null;
264
+ /** Prefix of the async Clipboard API's web custom formats (`web application/vnd.acme+json`). */
265
+ export declare const WEB_CUSTOM_FORMAT_PREFIX = "web ";
266
+ /** Whether a clipboard type is a web custom format (`web type/subtype`). */
267
+ export declare function isWebCustomFormat(type: string): boolean;
268
+ /**
269
+ * Like {@link normalizeMimeType}, but also accepts web custom formats
270
+ * (`web type/subtype`), returned as `web ` + the normalised MIME type.
271
+ */
272
+ export declare function normalizeClipboardType(value: string): string | null;
252
273
  /**
253
274
  * Does `mimeType` (already normalised) match `pattern` (`type/subtype`, `type/*` or `*\/*`)?
254
- * Wildcards never match `image/svg+xml`: accepting SVG must be explicit.
275
+ * Wildcards never match `image/svg+xml`, web custom formats or `+json` types: those must be listed exactly.
255
276
  */
256
277
  export declare function matchesMimePattern(mimeType: string, pattern: string): boolean;
257
278
  /** Types whose clipboard data is text and is therefore surfaced as a `string`. */
@@ -470,12 +491,16 @@ export interface CopySelection {
470
491
  /** Whether a `cut` would remove the selection (form field or contenteditable). */
471
492
  readonly editable: boolean;
472
493
  }
473
- /** A multi payload whose items are all strings; the only kind `setData` accepts. */
494
+ /**
495
+ * A multi payload whose items are all strings; the only kind `setData` accepts.
496
+ * Web custom formats (`web …`) are skipped: only the async Clipboard API writes them.
497
+ */
474
498
  export interface SyncMultiPayload {
475
499
  readonly kind: 'multi';
476
500
  readonly items: readonly {
477
501
  readonly mimeType: string;
478
502
  readonly data: string;
503
+ readonly optional?: boolean;
479
504
  }[];
480
505
  }
481
506
  /** Payloads writable synchronously during a copy event. Images need the async clipboard. */
@@ -576,8 +601,11 @@ export declare function registerCopyInterceptor(root: Element, options: CopyInte
576
601
  export type DragEffectAllowed = 'copy' | 'move' | 'link' | 'copyMove' | 'copyLink' | 'linkMove' | 'all' | 'none' | 'uninitialized';
577
602
  /** What is put into `DataTransfer` when a drag starts. */
578
603
  export interface DragCopyItem {
604
+ /** Web custom formats (`web …`) are skipped: only the async Clipboard API writes them. */
579
605
  readonly mimeType: string;
580
606
  readonly data: string;
607
+ /** Accepted for parity with `MultiPayloadItem`; every non-web item can be written to a drag. */
608
+ readonly optional?: boolean;
581
609
  }
582
610
  /**
583
611
  * A multi-format drag payload — strings only (DataTransfer only accepts strings).
package/dist/index.d.ts CHANGED
@@ -5,8 +5,9 @@ import { ButtonHTMLAttributes, CSSProperties, ClipboardEventHandler, DragEventHa
5
5
  type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
6
6
  /**
7
7
  * What a paste may contain, in any order: a shorthand, an exact MIME type
8
- * (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
9
- * `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
8
+ * (`'image/png'`), a web custom format (`'web application/vnd.acme+json'`) or a
9
+ * wildcard (`'image/*'`, `'*\/*'`). `image/svg+xml` (scriptable XML), web custom
10
+ * formats and `+json` types are only accepted when listed exactly.
10
11
  */
11
12
  type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
12
13
  interface PasteLimits {
@@ -213,8 +214,19 @@ export interface JsonPayload {
213
214
  readonly pretty?: boolean | number;
214
215
  }
215
216
  export interface MultiPayloadItem {
217
+ /**
218
+ * The MIME type, or a web custom format (`web application/vnd.acme+json`).
219
+ * Web custom formats are only written by the async Clipboard API; copy and drag
220
+ * events skip them.
221
+ */
216
222
  readonly mimeType: string;
217
223
  readonly data: string | Blob;
224
+ /**
225
+ * Skip this item, instead of failing the copy, when the browser cannot write its type.
226
+ * An optional item is only written when `ClipboardItem.supports()` confirms the type.
227
+ * At least one item must be written.
228
+ */
229
+ readonly optional?: boolean;
218
230
  }
219
231
  export interface MultiPayload {
220
232
  readonly kind: 'multi';
@@ -249,9 +261,18 @@ export declare function serializeJson(payload: JsonPayload): string;
249
261
  export declare const SVG_MIME_TYPE = "image/svg+xml";
250
262
  /** Lower-cased `type/subtype` without parameters, or `null` if it is not a valid MIME type. */
251
263
  export declare function normalizeMimeType(value: string): string | null;
264
+ /** Prefix of the async Clipboard API's web custom formats (`web application/vnd.acme+json`). */
265
+ export declare const WEB_CUSTOM_FORMAT_PREFIX = "web ";
266
+ /** Whether a clipboard type is a web custom format (`web type/subtype`). */
267
+ export declare function isWebCustomFormat(type: string): boolean;
268
+ /**
269
+ * Like {@link normalizeMimeType}, but also accepts web custom formats
270
+ * (`web type/subtype`), returned as `web ` + the normalised MIME type.
271
+ */
272
+ export declare function normalizeClipboardType(value: string): string | null;
252
273
  /**
253
274
  * Does `mimeType` (already normalised) match `pattern` (`type/subtype`, `type/*` or `*\/*`)?
254
- * Wildcards never match `image/svg+xml`: accepting SVG must be explicit.
275
+ * Wildcards never match `image/svg+xml`, web custom formats or `+json` types: those must be listed exactly.
255
276
  */
256
277
  export declare function matchesMimePattern(mimeType: string, pattern: string): boolean;
257
278
  /** Types whose clipboard data is text and is therefore surfaced as a `string`. */
@@ -470,12 +491,16 @@ export interface CopySelection {
470
491
  /** Whether a `cut` would remove the selection (form field or contenteditable). */
471
492
  readonly editable: boolean;
472
493
  }
473
- /** A multi payload whose items are all strings; the only kind `setData` accepts. */
494
+ /**
495
+ * A multi payload whose items are all strings; the only kind `setData` accepts.
496
+ * Web custom formats (`web …`) are skipped: only the async Clipboard API writes them.
497
+ */
474
498
  export interface SyncMultiPayload {
475
499
  readonly kind: 'multi';
476
500
  readonly items: readonly {
477
501
  readonly mimeType: string;
478
502
  readonly data: string;
503
+ readonly optional?: boolean;
479
504
  }[];
480
505
  }
481
506
  /** Payloads writable synchronously during a copy event. Images need the async clipboard. */
@@ -576,8 +601,11 @@ export declare function registerCopyInterceptor(root: Element, options: CopyInte
576
601
  export type DragEffectAllowed = 'copy' | 'move' | 'link' | 'copyMove' | 'copyLink' | 'linkMove' | 'all' | 'none' | 'uninitialized';
577
602
  /** What is put into `DataTransfer` when a drag starts. */
578
603
  export interface DragCopyItem {
604
+ /** Web custom formats (`web …`) are skipped: only the async Clipboard API writes them. */
579
605
  readonly mimeType: string;
580
606
  readonly data: string;
607
+ /** Accepted for parity with `MultiPayloadItem`; every non-web item can be written to a drag. */
608
+ readonly optional?: boolean;
581
609
  }
582
610
  /**
583
611
  * A multi-format drag payload — strings only (DataTransfer only accepts strings).
package/dist/index.js CHANGED
@@ -199,19 +199,43 @@ function normalizeMimeType(value) {
199
199
  const base = (separator === -1 ? value : value.slice(0, separator)).trim().toLowerCase();
200
200
  return MIME_SHAPE.test(base) ? base : null;
201
201
  }
202
+ /** Prefix of the async Clipboard API's web custom formats (`web application/vnd.acme+json`). */
203
+ const WEB_CUSTOM_FORMAT_PREFIX = "web ";
204
+ /** Whether a clipboard type is a web custom format (`web type/subtype`). */
205
+ function isWebCustomFormat(type) {
206
+ return type.slice(0, 4).toLowerCase() === WEB_CUSTOM_FORMAT_PREFIX;
207
+ }
208
+ /**
209
+ * Like {@link normalizeMimeType}, but also accepts web custom formats
210
+ * (`web type/subtype`), returned as `web ` + the normalised MIME type.
211
+ */
212
+ function normalizeClipboardType(value) {
213
+ if (!isWebCustomFormat(value)) return normalizeMimeType(value);
214
+ const inner = normalizeMimeType(value.slice(4));
215
+ return inner === null ? null : WEB_CUSTOM_FORMAT_PREFIX + inner;
216
+ }
217
+ /**
218
+ * Types a wildcard never matches, so accepting them must be explicit:
219
+ * `image/svg+xml` (scriptable XML), web custom formats and structured `+json` types
220
+ * (application-specific data that only the app that defined them should read).
221
+ */
222
+ function requiresExactMatch(mimeType) {
223
+ return mimeType === "image/svg+xml" || isWebCustomFormat(mimeType) || mimeType.endsWith("+json");
224
+ }
202
225
  /**
203
226
  * Does `mimeType` (already normalised) match `pattern` (`type/subtype`, `type/*` or `*\/*`)?
204
- * Wildcards never match `image/svg+xml`: accepting SVG must be explicit.
227
+ * Wildcards never match `image/svg+xml`, web custom formats or `+json` types: those must be listed exactly.
205
228
  */
206
229
  function matchesMimePattern(mimeType, pattern) {
207
230
  if (pattern === mimeType) return true;
208
- if (mimeType === "image/svg+xml") return false;
231
+ if (requiresExactMatch(mimeType)) return false;
209
232
  if (pattern === "*/*") return true;
210
233
  return pattern.endsWith("/*") && mimeType.startsWith(pattern.slice(0, -1));
211
234
  }
212
235
  /** Types whose clipboard data is text and is therefore surfaced as a `string`. */
213
236
  function isTextualMimeType(mimeType) {
214
- return mimeType.startsWith("text/") || mimeType === "image/svg+xml" || mimeType === "application/json" || mimeType === "application/xml";
237
+ const type = isWebCustomFormat(mimeType) ? mimeType.slice(4) : mimeType;
238
+ return type.startsWith("text/") || type === "image/svg+xml" || type === "application/json" || type === "application/xml" || type.endsWith("+json");
215
239
  }
216
240
  const SNIFF_BYTES = 16;
217
241
  function startsWith(bytes, signature, offset = 0) {
@@ -327,10 +351,14 @@ async function writeToClipboard(payload, env, degradeHtmlToText, context) {
327
351
  const rich = getRichClipboard(env, clipboard);
328
352
  if (!rich) throw fail("unsupported-format", "Multi-format copy requires ClipboardItem and navigator.clipboard.write().");
329
353
  const record = Object.create(null);
330
- for (const { mimeType, data } of payload.items) {
354
+ let written = 0;
355
+ for (const { mimeType, data, optional } of payload.items) {
356
+ if (optional === true && !(typeof rich.Item.supports === "function" && rich.Item.supports(mimeType))) continue;
331
357
  if (!isTypeSupported(rich.Item, mimeType)) throw fail("unsupported-format", `This browser cannot write "${mimeType}" to the clipboard.`);
332
358
  record[mimeType] = typeof data === "string" ? new Blob([data], { type: mimeType }) : data;
359
+ written += 1;
333
360
  }
361
+ if (written === 0) throw fail("unsupported-format", "This browser can write none of the payload types.");
334
362
  return rich.write([new rich.Item(record)]);
335
363
  }
336
364
  }
@@ -760,7 +788,8 @@ function prepare(decision) {
760
788
  if (typeof data !== "string") return unsupported$1(`Multi item "${mimeType}" must be a string during a copy event.`);
761
789
  entries.push([mimeType, data]);
762
790
  }
763
- return ok(entries);
791
+ const writable = entries.filter(([mimeType]) => !isWebCustomFormat(mimeType));
792
+ return writable.length > 0 ? ok(writable) : unsupported$1("Web custom formats need the async Clipboard API (useCopy).");
764
793
  }
765
794
  default: return unsupported$1(`"${String(fields["kind"])}" payloads cannot be written during a copy event; use useCopy() for images.`);
766
795
  }
@@ -996,7 +1025,8 @@ function prepareDragDecision(decision) {
996
1025
  data
997
1026
  });
998
1027
  }
999
- return ok(out);
1028
+ const writable = out.filter((item) => !isWebCustomFormat(item.mimeType));
1029
+ return writable.length > 0 ? ok(writable) : unsupported("Web custom formats need the async Clipboard API (useCopy).");
1000
1030
  }
1001
1031
  default: return unsupported(`"${String(fields["kind"])}" payloads cannot be used for drag-copy; use useCopy() for images.`);
1002
1032
  }
@@ -1146,7 +1176,7 @@ function resolvePattern(entry) {
1146
1176
  const type = entry.slice(0, -2).toLowerCase();
1147
1177
  return TYPE_TOKEN.test(type) ? `${type}/*` : null;
1148
1178
  }
1149
- return normalizeMimeType(entry);
1179
+ return normalizeClipboardType(entry);
1150
1180
  }
1151
1181
  function resolveLimit(value, fallback, name) {
1152
1182
  if (value === void 0) return fallback;
@@ -1222,7 +1252,7 @@ function canAcceptDrag(data, options) {
1222
1252
  });
1223
1253
  return Array.from(items).some(({ kind, type: raw }) => {
1224
1254
  const file = kind === "file";
1225
- const type = normalizeMimeType(raw);
1255
+ const type = normalizeClipboardType(raw);
1226
1256
  if (type === null) return file;
1227
1257
  return (file || isTextualMimeType(type)) && isAccepted(type, options);
1228
1258
  });
@@ -1235,7 +1265,7 @@ function snapshotDataTransfer(data, options) {
1235
1265
  const entries = [];
1236
1266
  const seen = /* @__PURE__ */ new Set();
1237
1267
  for (const raw of Array.from(data.types)) {
1238
- const type = normalizeMimeType(raw);
1268
+ const type = normalizeClipboardType(raw);
1239
1269
  if (type === null || seen.has(type) || !isTextualMimeType(type) || !isAccepted(type, options)) continue;
1240
1270
  seen.add(type);
1241
1271
  const text = data.getData(raw);
@@ -1264,7 +1294,7 @@ async function collectClipboardItems(items, options, signal) {
1264
1294
  const entries = [];
1265
1295
  const seen = /* @__PURE__ */ new Set();
1266
1296
  for (const item of items) for (const raw of item.types) {
1267
- const type = normalizeMimeType(raw);
1297
+ const type = normalizeClipboardType(raw);
1268
1298
  if (type === null || seen.has(type) || !isAccepted(type, options)) continue;
1269
1299
  seen.add(type);
1270
1300
  let blob;
@@ -2592,6 +2622,6 @@ function useDragCopy(options) {
2592
2622
  };
2593
2623
  }
2594
2624
  //#endregion
2595
- export { CopyFailure, CopyField, CopyGroup, DEFAULT_INTERCEPTED_EVENTS, DEFAULT_MAX_RETRIES, DEFAULT_MIN_PENDING_MS, DEFAULT_PASTE_ACCEPT, DEFAULT_PASTE_MAX_BYTES, DEFAULT_PASTE_MAX_ITEMS, DEFAULT_PASTE_MIN_PENDING_MS, DEFAULT_PASTE_PENDING_DELAY_MS, DEFAULT_PENDING_DELAY_MS, DEFAULT_RESET_AFTER_MS, IDLE_STATE, IMAGE_MIME_TYPE, LiveRegion, PASTE_IDLE_STATE, PasteField, SVG_MIME_TYPE, applyDragCopy, canAcceptDrag, canRetryPasteState, canRetryState, copyFailure, createBrowserClipboardAdapter, createBrowserPasteAdapter, createCopyCoordinator, createCopyError, createCopyMachine, createPasteMachine, defaultCopyFieldMessages, defaultPasteFieldMessages, describeCopyError, describePasteError, interceptCopyEvent, isBlob, isCopyFailure, isRetryableError, isTextualMimeType, matchesMimePattern, normalizeMimeType, normalizePayload, readCopySelection, registerCopyInterceptor, registerDragCopy, resolveMaxRetries, resolvePasteReadOptions, serializeJson, sniffImageBytes, sniffImageType, toCopyError, useCopy, useCopyField, useCopyGroup, useCopyInterceptor, useDisplayStatus, useDragCopy, usePaste, usePasteDisplayStatus, usePasteField, useRevealOnInteraction, validatePayload, visuallyHiddenStyle };
2625
+ export { CopyFailure, CopyField, CopyGroup, DEFAULT_INTERCEPTED_EVENTS, DEFAULT_MAX_RETRIES, DEFAULT_MIN_PENDING_MS, DEFAULT_PASTE_ACCEPT, DEFAULT_PASTE_MAX_BYTES, DEFAULT_PASTE_MAX_ITEMS, DEFAULT_PASTE_MIN_PENDING_MS, DEFAULT_PASTE_PENDING_DELAY_MS, DEFAULT_PENDING_DELAY_MS, DEFAULT_RESET_AFTER_MS, IDLE_STATE, IMAGE_MIME_TYPE, LiveRegion, PASTE_IDLE_STATE, PasteField, SVG_MIME_TYPE, WEB_CUSTOM_FORMAT_PREFIX, applyDragCopy, canAcceptDrag, canRetryPasteState, canRetryState, copyFailure, createBrowserClipboardAdapter, createBrowserPasteAdapter, createCopyCoordinator, createCopyError, createCopyMachine, createPasteMachine, defaultCopyFieldMessages, defaultPasteFieldMessages, describeCopyError, describePasteError, interceptCopyEvent, isBlob, isCopyFailure, isRetryableError, isTextualMimeType, isWebCustomFormat, matchesMimePattern, normalizeClipboardType, normalizeMimeType, normalizePayload, readCopySelection, registerCopyInterceptor, registerDragCopy, resolveMaxRetries, resolvePasteReadOptions, serializeJson, sniffImageBytes, sniffImageType, toCopyError, useCopy, useCopyField, useCopyGroup, useCopyInterceptor, useDisplayStatus, useDragCopy, usePaste, usePasteDisplayStatus, usePasteField, useRevealOnInteraction, validatePayload, visuallyHiddenStyle };
2596
2626
 
2597
2627
  //# sourceMappingURL=index.js.map