react-smart-copy 0.1.0 → 0.2.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 +136 -23
- package/dist/capture.cjs +498 -0
- package/dist/capture.cjs.map +1 -0
- package/dist/capture.d.cts +142 -0
- package/dist/capture.d.ts +142 -0
- package/dist/capture.js +485 -0
- package/dist/capture.js.map +1 -0
- package/dist/core.cjs +559 -22
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.cts +257 -9
- package/dist/core.d.ts +257 -9
- package/dist/core.js +544 -23
- package/dist/core.js.map +1 -1
- package/dist/index.cjs +645 -29
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +312 -11
- package/dist/index.d.ts +312 -11
- package/dist/index.js +627 -30
- package/dist/index.js.map +1 -1
- package/package.json +39 -10
package/dist/core.d.ts
CHANGED
|
@@ -1,29 +1,40 @@
|
|
|
1
1
|
//#region src/core/errors.d.ts
|
|
2
2
|
/**
|
|
3
|
-
* Every way a
|
|
3
|
+
* Every way a clipboard operation can fail, as a closed union.
|
|
4
4
|
*
|
|
5
5
|
* `CopyError.message` is developer-facing (logs, telemetry). For user-facing
|
|
6
|
-
* text use {@link describeCopyError}
|
|
6
|
+
* text use {@link describeCopyError} / {@link describePasteError}, or map
|
|
7
|
+
* `type` through your own i18n layer.
|
|
7
8
|
*/
|
|
8
9
|
export type CopyErrorType =
|
|
9
10
|
/** No Clipboard API (old browser, server, locked-down webview). Not retryable. */
|
|
10
11
|
'unsupported' |
|
|
11
12
|
/** Page is not served over HTTPS/localhost. Not retryable. */
|
|
12
13
|
'insecure-context' |
|
|
13
|
-
/** Browser or user blocked the
|
|
14
|
+
/** Browser or user blocked the operation. Also what Safari reports for a missing user gesture. */
|
|
14
15
|
'permission-denied' |
|
|
15
|
-
/** The document lost focus mid-
|
|
16
|
+
/** The document lost focus mid-operation (Chromium). Retrying after refocus usually works. */
|
|
16
17
|
'not-focused' |
|
|
17
18
|
/** Empty or malformed payload, or a lazy source that threw. Caught before touching the clipboard. */
|
|
18
19
|
'invalid-payload' |
|
|
19
|
-
/** The browser cannot
|
|
20
|
+
/** The browser cannot handle this MIME type (e.g. non-PNG image, HTML without ClipboardItem). */
|
|
20
21
|
'unsupported-format' |
|
|
21
|
-
/** A lazy image source threw, rejected or did not produce a Blob. */
|
|
22
|
+
/** A lazy image source (or capture) threw, rejected or did not produce a Blob. */
|
|
22
23
|
'blob-generation-failed' |
|
|
23
24
|
/** `retry()` was called after `maxRetries` was reached. Terminal. */
|
|
24
25
|
'max-retries-exceeded' |
|
|
26
|
+
/** Paste: the clipboard held nothing matching `accept`. */
|
|
27
|
+
'no-content' |
|
|
28
|
+
/** Content exceeded a configured safety limit (bytes, items or pixels). Not retryable. */
|
|
29
|
+
'too-large' |
|
|
30
|
+
/** An operation did not settle within its deadline. Retryable. */
|
|
31
|
+
'timeout' |
|
|
32
|
+
/** The caller aborted the operation through an `AbortSignal`. Not retryable. */
|
|
33
|
+
'aborted' |
|
|
25
34
|
/** Anything the platform threw that we could not classify. */
|
|
26
35
|
'unknown';
|
|
36
|
+
/** Which clipboard direction failed; only changes developer-facing messages. */
|
|
37
|
+
export type ClipboardOperation = 'write' | 'read';
|
|
27
38
|
export interface CopyError {
|
|
28
39
|
readonly type: CopyErrorType;
|
|
29
40
|
readonly message: string;
|
|
@@ -44,10 +55,17 @@ export declare class CopyFailure extends Error {
|
|
|
44
55
|
constructor(copyError: CopyError);
|
|
45
56
|
}
|
|
46
57
|
export declare function isCopyFailure(value: unknown): value is CopyFailure;
|
|
47
|
-
/**
|
|
48
|
-
export declare function
|
|
49
|
-
/**
|
|
58
|
+
/** Shorthand for throwing a classified failure. */
|
|
59
|
+
export declare function copyFailure(type: CopyErrorType, message: string, cause?: unknown): CopyFailure;
|
|
60
|
+
/**
|
|
61
|
+
* Classifies anything thrown by the platform or an adapter into a {@link CopyError}.
|
|
62
|
+
* `operation` only tailors the developer-facing message.
|
|
63
|
+
*/
|
|
64
|
+
export declare function toCopyError(cause: unknown, operation?: ClipboardOperation): CopyError;
|
|
65
|
+
/** Default English, user-facing sentence for a copy error. Replace for i18n. */
|
|
50
66
|
export declare function describeCopyError(error: CopyError): string;
|
|
67
|
+
/** Default English, user-facing sentence for a paste error. Replace for i18n. */
|
|
68
|
+
export declare function describePasteError(error: CopyError): string;
|
|
51
69
|
//#endregion
|
|
52
70
|
//#region src/core/payload.d.ts
|
|
53
71
|
/** The only image MIME type with reliable cross-browser clipboard write support. */
|
|
@@ -105,6 +123,30 @@ export declare function validatePayload(payload: unknown): CopyError | null;
|
|
|
105
123
|
/** Serialises a JSON payload, throwing a classified failure instead of a raw TypeError. */
|
|
106
124
|
export declare function serializeJson(payload: JsonPayload): string;
|
|
107
125
|
//#endregion
|
|
126
|
+
//#region src/core/mime.d.ts
|
|
127
|
+
/**
|
|
128
|
+
* MIME helpers shared by paste and capture. Everything that comes from the
|
|
129
|
+
* clipboard is untrusted input, so types are normalised and validated before
|
|
130
|
+
* they are compared, and image types are confirmed from the bytes themselves.
|
|
131
|
+
*/
|
|
132
|
+
/** SVG is XML that can carry scripts; it is never matched by a wildcard. */
|
|
133
|
+
export declare const SVG_MIME_TYPE = "image/svg+xml";
|
|
134
|
+
/** Lower-cased `type/subtype` without parameters, or `null` if it is not a valid MIME type. */
|
|
135
|
+
export declare function normalizeMimeType(value: string): string | null;
|
|
136
|
+
/**
|
|
137
|
+
* Does `mimeType` (already normalised) match `pattern` (`type/subtype`, `type/*` or `*\/*`)?
|
|
138
|
+
* Wildcards never match `image/svg+xml`: accepting SVG must be explicit.
|
|
139
|
+
*/
|
|
140
|
+
export declare function matchesMimePattern(mimeType: string, pattern: string): boolean;
|
|
141
|
+
/** Types whose clipboard data is text and is therefore surfaced as a `string`. */
|
|
142
|
+
export declare function isTextualMimeType(mimeType: string): boolean;
|
|
143
|
+
/** Raster image formats recognised from their leading bytes. */
|
|
144
|
+
export type RasterImageMimeType = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'image/bmp' | 'image/avif';
|
|
145
|
+
/** Identifies a raster image from its magic bytes, ignoring whatever type the Blob claims. */
|
|
146
|
+
export declare function sniffImageBytes(bytes: Uint8Array): RasterImageMimeType | null;
|
|
147
|
+
/** Reads only the first bytes of a Blob, so sniffing a 20 MB screenshot stays cheap. */
|
|
148
|
+
export declare function sniffImageType(blob: Blob): Promise<RasterImageMimeType | null>;
|
|
149
|
+
//#endregion
|
|
108
150
|
//#region src/core/clipboard-adapter.d.ts
|
|
109
151
|
/** Minimal structural view of `navigator.clipboard`, so fakes and polyfills fit. */
|
|
110
152
|
export interface ClipboardLike {
|
|
@@ -143,6 +185,31 @@ export interface BrowserClipboardAdapterOptions {
|
|
|
143
185
|
/** The default adapter: async Clipboard API with feature detection and honest errors. */
|
|
144
186
|
export declare function createBrowserClipboardAdapter(options?: BrowserClipboardAdapterOptions): ClipboardAdapter;
|
|
145
187
|
//#endregion
|
|
188
|
+
//#region src/core/copy-coordinator.d.ts
|
|
189
|
+
/**
|
|
190
|
+
* A copy machine as seen by a coordinator. `release()` returns it from
|
|
191
|
+
* `copied` to `idle`; it is a no-op in any other state.
|
|
192
|
+
*/
|
|
193
|
+
export interface CopyCoordinatorMember {
|
|
194
|
+
readonly release: () => void;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Makes a set of copy machines behave like one clipboard: when a member
|
|
198
|
+
* succeeds, the member that previously showed "Copied" goes back to idle,
|
|
199
|
+
* because the clipboard no longer holds its value.
|
|
200
|
+
*
|
|
201
|
+
* Failed copies never release anyone (the clipboard still holds the previous value).
|
|
202
|
+
*/
|
|
203
|
+
export interface CopyCoordinator {
|
|
204
|
+
/** A member just reached `copied`. Releases the previous one. */
|
|
205
|
+
readonly activate: (member: CopyCoordinatorMember) => void;
|
|
206
|
+
/** A member left `copied` on its own (auto-reset, reset, unmount). */
|
|
207
|
+
readonly deactivate: (member: CopyCoordinatorMember) => void;
|
|
208
|
+
/** The member currently showing `copied`, if any. */
|
|
209
|
+
readonly getActive: () => CopyCoordinatorMember | null;
|
|
210
|
+
}
|
|
211
|
+
export declare function createCopyCoordinator(): CopyCoordinator;
|
|
212
|
+
//#endregion
|
|
146
213
|
//#region src/core/copy-machine.d.ts
|
|
147
214
|
export declare const DEFAULT_RESET_AFTER_MS = 2000;
|
|
148
215
|
export declare const DEFAULT_MAX_RETRIES = 3;
|
|
@@ -188,6 +255,11 @@ export interface CopyMachineOptions {
|
|
|
188
255
|
readonly resetAfterMs?: number | false;
|
|
189
256
|
/** Max `retry()` calls after the first failure. Default 3. */
|
|
190
257
|
readonly maxRetries?: number;
|
|
258
|
+
/**
|
|
259
|
+
* Share "Copied" with other machines: only one member of a coordinator
|
|
260
|
+
* shows `copied` at a time. `null` explicitly opts out (e.g. of a React `<CopyGroup>`).
|
|
261
|
+
*/
|
|
262
|
+
readonly coordinator?: CopyCoordinator | null;
|
|
191
263
|
readonly onCopy?: (payload: CopyPayload) => void;
|
|
192
264
|
readonly onError?: (error: CopyError, payload: CopyPayload | null) => void;
|
|
193
265
|
/** Clock injection for tests and deterministic environments. */
|
|
@@ -215,4 +287,180 @@ export declare function canRetryState(state: CopyState, maxRetries?: number): bo
|
|
|
215
287
|
/** Framework-agnostic copy state machine. */
|
|
216
288
|
export declare function createCopyMachine(options?: CopyMachineOptionsSource): CopyMachine;
|
|
217
289
|
//#endregion
|
|
290
|
+
//#region src/core/paste-reader.d.ts
|
|
291
|
+
/** Friendly names for the common cases. */
|
|
292
|
+
type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
293
|
+
/**
|
|
294
|
+
* What a paste may contain, in any order: a shorthand, an exact MIME type
|
|
295
|
+
* (`'image/png'`) or a wildcard (`'image/*'`, `'*\/*'`).
|
|
296
|
+
* `image/svg+xml` is only accepted when listed exactly (it is scriptable XML).
|
|
297
|
+
*/
|
|
298
|
+
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
299
|
+
interface PasteLimits {
|
|
300
|
+
/** Total size cap across all accepted items. Strings count UTF-16 code units. Default 32 MiB. */
|
|
301
|
+
readonly maxBytes?: number;
|
|
302
|
+
/** Max number of accepted items (types + files). Default 32. */
|
|
303
|
+
readonly maxItems?: number;
|
|
304
|
+
}
|
|
305
|
+
interface PasteReadOptions extends PasteLimits {
|
|
306
|
+
/** Default `['text']` (plain text only): the safest choice. */
|
|
307
|
+
readonly accept?: readonly PasteAccept[];
|
|
308
|
+
}
|
|
309
|
+
/** Validated, normalised options that adapters receive. */
|
|
310
|
+
interface ResolvedPasteReadOptions {
|
|
311
|
+
/** Normalised patterns: `type/subtype`, `type/*` or `*\/*`. */
|
|
312
|
+
readonly accept: readonly string[];
|
|
313
|
+
readonly maxBytes: number;
|
|
314
|
+
readonly maxItems: number;
|
|
315
|
+
}
|
|
316
|
+
/** Where the content came from. */
|
|
317
|
+
type PasteSource = 'clipboard' | 'event';
|
|
318
|
+
/** One accepted clipboard entry. Textual types are decoded to `string`, everything else stays a `Blob`. */
|
|
319
|
+
interface PasteItem {
|
|
320
|
+
readonly type: string;
|
|
321
|
+
readonly data: string | Blob;
|
|
322
|
+
}
|
|
323
|
+
/**
|
|
324
|
+
* Everything the paste produced. Treat all of it as untrusted user input:
|
|
325
|
+
* in particular never inject `html` into the DOM without sanitising it.
|
|
326
|
+
*/
|
|
327
|
+
interface PasteResult {
|
|
328
|
+
readonly source: PasteSource;
|
|
329
|
+
/** Every accepted entry, in clipboard order. */
|
|
330
|
+
readonly items: readonly PasteItem[];
|
|
331
|
+
/** `text/plain`, when accepted and present. */
|
|
332
|
+
readonly text: string | null;
|
|
333
|
+
/** `text/html`, when accepted and present. UNTRUSTED markup: sanitise before rendering. */
|
|
334
|
+
readonly html: string | null;
|
|
335
|
+
/** Raster images, verified from their bytes (PNG, JPEG, GIF, WebP, AVIF, BMP), typed accordingly. */
|
|
336
|
+
readonly images: readonly Blob[];
|
|
337
|
+
/** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
|
|
338
|
+
readonly files: readonly File[];
|
|
339
|
+
}
|
|
340
|
+
export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
|
|
341
|
+
export declare const DEFAULT_PASTE_MAX_BYTES: number;
|
|
342
|
+
export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
|
|
343
|
+
/** Validates and normalises paste options. Throws a classified `invalid-payload` failure. */
|
|
344
|
+
export declare function resolvePasteReadOptions(options?: PasteReadOptions): ResolvedPasteReadOptions;
|
|
345
|
+
/** Structural view of `DataTransfer` (paste events). */
|
|
346
|
+
interface DataTransferLike {
|
|
347
|
+
readonly types: ArrayLike<string>;
|
|
348
|
+
getData(format: string): string;
|
|
349
|
+
readonly files?: ArrayLike<File> | null;
|
|
350
|
+
}
|
|
351
|
+
/** Structural view of a `ClipboardItem` as returned by `navigator.clipboard.read()`. */
|
|
352
|
+
interface ClipboardItemLike {
|
|
353
|
+
readonly types: readonly string[];
|
|
354
|
+
getType(type: string): Promise<Blob>;
|
|
355
|
+
}
|
|
356
|
+
//#endregion
|
|
357
|
+
//#region src/core/paste-adapter.d.ts
|
|
358
|
+
/** Minimal structural view of `navigator.clipboard` for reading. */
|
|
359
|
+
interface PasteClipboardLike {
|
|
360
|
+
read?(): Promise<readonly ClipboardItemLike[]>;
|
|
361
|
+
readText?(): Promise<string>;
|
|
362
|
+
}
|
|
363
|
+
interface PasteEnvironment {
|
|
364
|
+
readonly isSecureContext?: boolean;
|
|
365
|
+
readonly navigator?: {
|
|
366
|
+
readonly clipboard?: PasteClipboardLike | undefined;
|
|
367
|
+
} | undefined;
|
|
368
|
+
}
|
|
369
|
+
/**
|
|
370
|
+
* Reads the system clipboard. Implement it for Electron, a native bridge or tests.
|
|
371
|
+
*
|
|
372
|
+
* Contract: call the platform API synchronously (before any `await`) so the
|
|
373
|
+
* browser still sees the user gesture, and reject with a `CopyFailure`.
|
|
374
|
+
*/
|
|
375
|
+
interface PasteAdapter {
|
|
376
|
+
read(options: ResolvedPasteReadOptions): Promise<PasteResult>;
|
|
377
|
+
}
|
|
378
|
+
interface BrowserPasteAdapterOptions {
|
|
379
|
+
/** Defaults to `window`, read lazily at paste time (SSR-safe). */
|
|
380
|
+
readonly getEnvironment?: () => PasteEnvironment | undefined;
|
|
381
|
+
}
|
|
382
|
+
/** The default paste adapter: async Clipboard API with feature detection and honest errors. */
|
|
383
|
+
export declare function createBrowserPasteAdapter(options?: BrowserPasteAdapterOptions): PasteAdapter;
|
|
384
|
+
//#endregion
|
|
385
|
+
//#region src/core/paste-machine.d.ts
|
|
386
|
+
export interface PasteIdleState {
|
|
387
|
+
readonly status: 'idle';
|
|
388
|
+
}
|
|
389
|
+
export interface PasteReadingState {
|
|
390
|
+
readonly status: 'reading';
|
|
391
|
+
}
|
|
392
|
+
export interface PasteReadState {
|
|
393
|
+
readonly status: 'read';
|
|
394
|
+
readonly result: PasteResult;
|
|
395
|
+
/** Epoch ms when the read resolved. */
|
|
396
|
+
readonly at: number;
|
|
397
|
+
}
|
|
398
|
+
export interface PasteErrorState {
|
|
399
|
+
readonly status: 'error';
|
|
400
|
+
readonly error: CopyError;
|
|
401
|
+
}
|
|
402
|
+
export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
|
|
403
|
+
export type PasteStatus = PasteState['status'];
|
|
404
|
+
export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content';
|
|
405
|
+
/** What `paste()` / `pasteEvent()` resolve to. They never reject. */
|
|
406
|
+
export type PasteOutcome = {
|
|
407
|
+
readonly status: 'read';
|
|
408
|
+
readonly result: PasteResult;
|
|
409
|
+
} | {
|
|
410
|
+
readonly status: 'error';
|
|
411
|
+
readonly error: CopyError;
|
|
412
|
+
} | {
|
|
413
|
+
readonly status: 'ignored';
|
|
414
|
+
readonly reason: PasteIgnoredReason;
|
|
415
|
+
};
|
|
416
|
+
/** Structural view of a DOM / React `paste` event. */
|
|
417
|
+
export interface PasteEventLike {
|
|
418
|
+
readonly clipboardData: DataTransferLike | null | undefined;
|
|
419
|
+
preventDefault(): void;
|
|
420
|
+
}
|
|
421
|
+
export interface PasteMachineOptions extends PasteReadOptions {
|
|
422
|
+
/** Defaults to the browser Clipboard API adapter. */
|
|
423
|
+
readonly adapter?: PasteAdapter;
|
|
424
|
+
/** Return from `read` to `idle` after this many ms. `false` / `Infinity` / omitted = keep the result. */
|
|
425
|
+
readonly resetAfterMs?: number | false;
|
|
426
|
+
/**
|
|
427
|
+
* Paste events only: call `event.preventDefault()` when the event carried
|
|
428
|
+
* accepted content, so the browser doesn't also insert it. Default `true`.
|
|
429
|
+
*/
|
|
430
|
+
readonly preventDefault?: boolean;
|
|
431
|
+
readonly onPaste?: (result: PasteResult) => void;
|
|
432
|
+
readonly onError?: (error: CopyError) => void;
|
|
433
|
+
/** Clock injection for tests and deterministic environments. */
|
|
434
|
+
readonly now?: () => number;
|
|
435
|
+
}
|
|
436
|
+
/** Options object, or a getter so hosts (like React) can supply the latest options. */
|
|
437
|
+
export type PasteMachineOptionsSource = PasteMachineOptions | (() => PasteMachineOptions);
|
|
438
|
+
export interface PasteMachine {
|
|
439
|
+
readonly getSnapshot: () => PasteState;
|
|
440
|
+
readonly subscribe: (listener: () => void) => () => void;
|
|
441
|
+
/**
|
|
442
|
+
* Reads the system clipboard via the adapter. Call it from a user gesture
|
|
443
|
+
* (click, keypress). May show a permission prompt. Ignored while `reading`.
|
|
444
|
+
*/
|
|
445
|
+
readonly paste: () => Promise<PasteOutcome>;
|
|
446
|
+
/**
|
|
447
|
+
* Handles a `paste` event (Ctrl/⌘+V). No permission prompt: the data is
|
|
448
|
+
* already in the event. Supersedes any read in flight. Events without
|
|
449
|
+
* accepted content are ignored and left untouched for the browser.
|
|
450
|
+
*/
|
|
451
|
+
readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
|
|
452
|
+
/** Back to `idle`, discarding any in-flight result. */
|
|
453
|
+
readonly reset: () => void;
|
|
454
|
+
/**
|
|
455
|
+
* Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
|
|
456
|
+
* cleanup clears timers, drops in-flight results and unsticks `reading`.
|
|
457
|
+
* Safe to call repeatedly (React StrictMode).
|
|
458
|
+
*/
|
|
459
|
+
readonly connect: () => () => void;
|
|
460
|
+
}
|
|
461
|
+
export declare const PASTE_IDLE_STATE: PasteIdleState;
|
|
462
|
+
/** Framework-agnostic paste state machine. */
|
|
463
|
+
export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
|
|
464
|
+
//#endregion
|
|
465
|
+
export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, ResolvedPasteReadOptions };
|
|
218
466
|
//# sourceMappingURL=core.d.ts.map
|