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/README.md +209 -4
- package/dist/capture.cjs.map +1 -1
- package/dist/capture.js.map +1 -1
- package/dist/core.cjs +57 -13
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.cts +32 -4
- package/dist/core.d.ts +32 -4
- package/dist/core.js +55 -14
- package/dist/core.js.map +1 -1
- package/dist/index.cjs +57 -13
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +32 -4
- package/dist/index.d.ts +32 -4
- package/dist/index.js +55 -14
- package/dist/index.js.map +1 -1
- package/dist/structured.cjs +552 -0
- package/dist/structured.cjs.map +1 -0
- package/dist/structured.d.cts +273 -0
- package/dist/structured.d.ts +273 -0
- package/dist/structured.js +545 -0
- package/dist/structured.js.map +1 -0
- package/dist/table.cjs +855 -0
- package/dist/table.cjs.map +1 -0
- package/dist/table.d.cts +380 -0
- package/dist/table.d.ts +380 -0
- package/dist/table.js +838 -0
- package/dist/table.js.map +1 -0
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +11 -0
- package/dist/testing.d.ts +11 -0
- package/dist/testing.js.map +1 -1
- package/package.json +83 -11
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
//#region src/structured/standard-schema.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* The Standard Schema v1 interface (https://standardschema.dev), inlined so the
|
|
4
|
+
* package has no runtime or type dependency. Zod (3.24+), Valibot (1.0+), ArkType
|
|
5
|
+
* (2.0+), Effect Schema and others implement it, so their schemas are accepted as is.
|
|
6
|
+
*/
|
|
7
|
+
interface StandardSchemaV1<Input = unknown, Output = Input> {
|
|
8
|
+
readonly '~standard': StandardSchemaProps<Input, Output>;
|
|
9
|
+
}
|
|
10
|
+
interface StandardSchemaProps<Input = unknown, Output = Input> {
|
|
11
|
+
readonly version: 1;
|
|
12
|
+
readonly vendor: string;
|
|
13
|
+
readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
|
|
14
|
+
readonly types?: StandardSchemaTypes<Input, Output> | undefined;
|
|
15
|
+
}
|
|
16
|
+
type StandardSchemaResult<Output> = StandardSchemaSuccess<Output> | StandardSchemaFailure;
|
|
17
|
+
interface StandardSchemaSuccess<Output> {
|
|
18
|
+
readonly value: Output;
|
|
19
|
+
readonly issues?: undefined;
|
|
20
|
+
}
|
|
21
|
+
interface StandardSchemaFailure {
|
|
22
|
+
readonly issues: readonly StandardSchemaIssue[];
|
|
23
|
+
}
|
|
24
|
+
interface StandardSchemaIssue {
|
|
25
|
+
readonly message: string;
|
|
26
|
+
readonly path?: readonly (PropertyKey | StandardSchemaPathSegment)[] | undefined;
|
|
27
|
+
}
|
|
28
|
+
interface StandardSchemaPathSegment {
|
|
29
|
+
readonly key: PropertyKey;
|
|
30
|
+
}
|
|
31
|
+
interface StandardSchemaTypes<Input = unknown, Output = Input> {
|
|
32
|
+
readonly input: Input;
|
|
33
|
+
readonly output: Output;
|
|
34
|
+
}
|
|
35
|
+
/** The type a Standard Schema produces. */
|
|
36
|
+
type InferSchemaOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
|
|
37
|
+
//#endregion
|
|
38
|
+
//#region src/structured/format.d.ts
|
|
39
|
+
/** A plain validator: return the typed value, or throw when `data` is not valid. */
|
|
40
|
+
type ClipValidator<Value> = (data: unknown) => Value;
|
|
41
|
+
/**
|
|
42
|
+
* Validates pasted data. A Standard Schema (Zod, Valibot, ArkType, Effect Schema, …)
|
|
43
|
+
* or a plain function that returns the value or throws.
|
|
44
|
+
*/
|
|
45
|
+
type ClipSchema<Value> = StandardSchemaV1<unknown, Value> | ClipValidator<Value>;
|
|
46
|
+
/**
|
|
47
|
+
* The value a schema produces. Standard Schemas are checked first: some (ArkType)
|
|
48
|
+
* are also callable, and their call signature returns errors instead of throwing.
|
|
49
|
+
*/
|
|
50
|
+
type ClipSchemaValue<Schema> = Schema extends StandardSchemaV1 ? InferSchemaOutput<Schema> : Schema extends ((data: unknown) => infer Value) ? Value : never;
|
|
51
|
+
/** Upgrades data written by version `n` to version `n + 1`. Receives untrusted data: check before use. */
|
|
52
|
+
type ClipMigration = (data: unknown) => unknown;
|
|
53
|
+
interface ClipFormatOptions<Value> {
|
|
54
|
+
/**
|
|
55
|
+
* A namespaced id: lower-case words separated by dots, e.g. `'acme.invoice-rows'`.
|
|
56
|
+
* It names the clipboard type (`application/vnd.acme.invoice-rows+json`), so keep it
|
|
57
|
+
* stable and specific to your app; two apps sharing an id can read each other's data.
|
|
58
|
+
*/
|
|
59
|
+
readonly id: string;
|
|
60
|
+
/** The data version this app writes. Positive integer, default `1`. Bump it when the shape changes. */
|
|
61
|
+
readonly version?: number;
|
|
62
|
+
/**
|
|
63
|
+
* Validates what is pasted, after migrations. The clipboard is untrusted input:
|
|
64
|
+
* anything (another app, another tab, a malicious page) can put this format on it.
|
|
65
|
+
*/
|
|
66
|
+
readonly schema: ClipSchema<Value>;
|
|
67
|
+
/**
|
|
68
|
+
* Migrations from older versions, keyed by the version they upgrade *from*:
|
|
69
|
+
* `{ 1: (v1) => v2 }`. A paste from a version with no migration path is reported
|
|
70
|
+
* as `unsupported-version`.
|
|
71
|
+
*/
|
|
72
|
+
readonly migrate?: Readonly<Record<number, ClipMigration>>;
|
|
73
|
+
/**
|
|
74
|
+
* Turns the value into JSON-ready data. Default: the value itself. The result must
|
|
75
|
+
* survive `JSON.stringify` unchanged (no Map, Set, functions, NaN or Infinity);
|
|
76
|
+
* Dates become ISO strings, so validate them back with a coercing schema.
|
|
77
|
+
*/
|
|
78
|
+
readonly encode?: (value: Value) => unknown;
|
|
79
|
+
/** Plain text for other apps (editors, chat, terminals). Default: the encoded data as indented JSON. */
|
|
80
|
+
readonly text?: (value: Value) => string;
|
|
81
|
+
/**
|
|
82
|
+
* Visible HTML for rich targets (Docs, Word, mail). Treat it like any HTML you
|
|
83
|
+
* generate: escape what you interpolate. Default: the plain text.
|
|
84
|
+
*/
|
|
85
|
+
readonly html?: (value: Value) => string;
|
|
86
|
+
/** Size cap of the serialised data, in UTF-8 bytes, enforced on copy and paste. Default 8 MiB. */
|
|
87
|
+
readonly maxBytes?: number;
|
|
88
|
+
/**
|
|
89
|
+
* Also embed the data, hidden, in the copied HTML: the carrier that works for every
|
|
90
|
+
* paste path in every browser (keyboard paste, drag-and-drop, Safari, Firefox).
|
|
91
|
+
* The embedded data travels wherever the HTML is pasted (a mail, a document), so
|
|
92
|
+
* copy only what the user may share. Default `true`.
|
|
93
|
+
*/
|
|
94
|
+
readonly embedInHtml?: boolean;
|
|
95
|
+
}
|
|
96
|
+
/** A validated, frozen clipboard format. Create one with {@link defineClipFormat} and share it. */
|
|
97
|
+
interface ClipFormat<Value> {
|
|
98
|
+
readonly id: string;
|
|
99
|
+
readonly version: number;
|
|
100
|
+
/** The clipboard type for copy and drag events, e.g. `application/vnd.acme.invoice-rows+json`. */
|
|
101
|
+
readonly mimeType: string;
|
|
102
|
+
/** The async Clipboard API's web custom format: `web ` + {@link mimeType}. */
|
|
103
|
+
readonly webMimeType: string;
|
|
104
|
+
readonly schema: ClipSchema<Value>;
|
|
105
|
+
readonly migrate: Readonly<Record<number, ClipMigration>>;
|
|
106
|
+
readonly encode: ((value: Value) => unknown) | undefined;
|
|
107
|
+
readonly text: ((value: Value) => string) | undefined;
|
|
108
|
+
readonly html: ((value: Value) => string) | undefined;
|
|
109
|
+
readonly maxBytes: number;
|
|
110
|
+
readonly embedInHtml: boolean;
|
|
111
|
+
}
|
|
112
|
+
/** The parts of a format that do not depend on its value type. */
|
|
113
|
+
type ClipFormatInfo = Pick<ClipFormat<unknown>, 'id' | 'version' | 'mimeType' | 'webMimeType' | 'maxBytes'>;
|
|
114
|
+
/** The value type of a format: `ClipValue<typeof InvoiceRows>`. */
|
|
115
|
+
type ClipValue<Format> = Format extends ClipFormat<infer Value> ? Value : never;
|
|
116
|
+
export declare const DEFAULT_CLIP_MAX_BYTES: number;
|
|
117
|
+
/**
|
|
118
|
+
* Defines a typed clipboard format: copy it with {@link clipPayload}, read it back
|
|
119
|
+
* with {@link readClip}. Define each format once, at module level, and share it
|
|
120
|
+
* between the copying and the pasting code.
|
|
121
|
+
*
|
|
122
|
+
* Throws an `invalid-payload` `CopyFailure` when the definition is invalid.
|
|
123
|
+
*
|
|
124
|
+
* @example
|
|
125
|
+
* const InvoiceRows = defineClipFormat({
|
|
126
|
+
* id: 'acme.invoice-rows',
|
|
127
|
+
* version: 2,
|
|
128
|
+
* schema: z.array(Invoice),
|
|
129
|
+
* migrate: { 1: (rows) => upgradeV1(rows) },
|
|
130
|
+
* text: (rows) => rows.map((row) => row.id).join('\n'),
|
|
131
|
+
* });
|
|
132
|
+
*/
|
|
133
|
+
export declare function defineClipFormat<Schema extends ClipSchema<unknown>>(options: Omit<ClipFormatOptions<ClipSchemaValue<Schema>>, 'schema'> & {
|
|
134
|
+
readonly schema: Schema;
|
|
135
|
+
}): ClipFormat<ClipSchemaValue<Schema>>;
|
|
136
|
+
//#endregion
|
|
137
|
+
//#region src/structured/envelope.d.ts
|
|
138
|
+
/** The HTML attribute holding `id;base64url(envelope)`. Exported for documentation and tests. */
|
|
139
|
+
export declare const CLIP_HTML_ATTRIBUTE = "data-rsc-clip";
|
|
140
|
+
//#endregion
|
|
141
|
+
//#region src/structured/write.d.ts
|
|
142
|
+
/** One clipboard entry of a {@link ClipPayload}. Strings only, so it also works in copy and drag events. */
|
|
143
|
+
interface ClipPayloadItem {
|
|
144
|
+
readonly mimeType: string;
|
|
145
|
+
readonly data: string;
|
|
146
|
+
readonly optional?: boolean;
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* A multi-format payload carrying a clip. Pass it to `copy()`, return it from a
|
|
150
|
+
* `useCopyInterceptor` transform or a `useDragCopy` source: each path writes the
|
|
151
|
+
* carriers it can.
|
|
152
|
+
*/
|
|
153
|
+
interface ClipPayload {
|
|
154
|
+
readonly kind: 'multi';
|
|
155
|
+
readonly items: readonly ClipPayloadItem[];
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* Builds the payload that puts `value` on the clipboard in `format`, through three carriers:
|
|
159
|
+
*
|
|
160
|
+
* 1. `web application/vnd.<id>+json`: the async Clipboard API's web custom format
|
|
161
|
+
* (Chromium). Read back by `navigator.clipboard.read()`, also across origins.
|
|
162
|
+
* 2. `application/vnd.<id>+json`: written by copy and drag events, read back by
|
|
163
|
+
* paste and drop events.
|
|
164
|
+
* 3. A hidden envelope in `text/html`, which every paste path in every browser keeps.
|
|
165
|
+
*
|
|
166
|
+
* Plus `text/plain` (and visible HTML) for every other app. Carriers a browser
|
|
167
|
+
* cannot write are skipped. {@link readClip} tries them in this order.
|
|
168
|
+
*
|
|
169
|
+
* Synchronous, so it can be built inside the user gesture. Throws a classified
|
|
170
|
+
* `CopyFailure`: `invalid-payload` when the data is not JSON-safe, `too-large`
|
|
171
|
+
* when it exceeds the format's `maxBytes`.
|
|
172
|
+
*/
|
|
173
|
+
export declare function clipPayload<Value>(format: ClipFormat<Value>, value: Value): ClipPayload;
|
|
174
|
+
//#endregion
|
|
175
|
+
//#region src/core/paste-reader.d.ts
|
|
176
|
+
/** Friendly names for the common cases. */
|
|
177
|
+
type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
|
|
178
|
+
/**
|
|
179
|
+
* What a paste may contain, in any order: a shorthand, an exact MIME type
|
|
180
|
+
* (`'image/png'`), a web custom format (`'web application/vnd.acme+json'`) or a
|
|
181
|
+
* wildcard (`'image/*'`, `'*\/*'`). `image/svg+xml` (scriptable XML), web custom
|
|
182
|
+
* formats and `+json` types are only accepted when listed exactly.
|
|
183
|
+
*/
|
|
184
|
+
type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
|
|
185
|
+
//#endregion
|
|
186
|
+
//#region src/structured/read.d.ts
|
|
187
|
+
/** Which carrier the clip was read from, most to least specific. */
|
|
188
|
+
type ClipCarrier = 'web' | 'custom' | 'html';
|
|
189
|
+
interface ClipIssue {
|
|
190
|
+
readonly message: string;
|
|
191
|
+
/** Where in the data the problem is; empty for the data as a whole. */
|
|
192
|
+
readonly path: readonly PropertyKey[];
|
|
193
|
+
}
|
|
194
|
+
interface ClipReadOk<Value> {
|
|
195
|
+
readonly status: 'ok';
|
|
196
|
+
/** The validated (and, if needed, migrated) value. */
|
|
197
|
+
readonly value: Value;
|
|
198
|
+
/** The version the data was written with; lower than the format's when it was migrated. */
|
|
199
|
+
readonly version: number;
|
|
200
|
+
readonly carrier: ClipCarrier;
|
|
201
|
+
}
|
|
202
|
+
/** The source holds no data in this format. */
|
|
203
|
+
interface ClipReadAbsent {
|
|
204
|
+
readonly status: 'absent';
|
|
205
|
+
}
|
|
206
|
+
/** Data in this format was found but is malformed, too large, failed a migration or failed the schema. */
|
|
207
|
+
interface ClipReadInvalid {
|
|
208
|
+
readonly status: 'invalid';
|
|
209
|
+
readonly carrier: ClipCarrier;
|
|
210
|
+
readonly issues: readonly ClipIssue[];
|
|
211
|
+
/** What a migration or validator threw, if anything. */
|
|
212
|
+
readonly cause?: unknown;
|
|
213
|
+
}
|
|
214
|
+
/** Written by a newer version of the app, or by an older one with no migration path. */
|
|
215
|
+
interface ClipReadUnsupportedVersion {
|
|
216
|
+
readonly status: 'unsupported-version';
|
|
217
|
+
readonly carrier: ClipCarrier;
|
|
218
|
+
readonly version: number;
|
|
219
|
+
}
|
|
220
|
+
type ClipReadResult<Value> = ClipReadOk<Value> | ClipReadAbsent | ClipReadInvalid | ClipReadUnsupportedVersion;
|
|
221
|
+
/** An entry of a paste result (`type`) or of a clip payload (`mimeType`). */
|
|
222
|
+
type ClipSourceItem = {
|
|
223
|
+
readonly type: string;
|
|
224
|
+
readonly data: string | Blob;
|
|
225
|
+
} | {
|
|
226
|
+
readonly mimeType: string;
|
|
227
|
+
readonly data: string | Blob;
|
|
228
|
+
};
|
|
229
|
+
/** The `DataTransfer` of a paste or drop event you handle yourself. */
|
|
230
|
+
interface ClipDataTransfer {
|
|
231
|
+
readonly types: ArrayLike<string>;
|
|
232
|
+
getData(format: string): string;
|
|
233
|
+
}
|
|
234
|
+
/**
|
|
235
|
+
* Where to read a clip from: a `PasteResult` (from `usePaste`, `PasteField` or a
|
|
236
|
+
* paste adapter), a {@link ClipPayload} (round-trips, tests, in-app duplication), or
|
|
237
|
+
* a raw `DataTransfer`.
|
|
238
|
+
*/
|
|
239
|
+
type ClipSource = {
|
|
240
|
+
readonly items: readonly ClipSourceItem[];
|
|
241
|
+
} | ClipDataTransfer;
|
|
242
|
+
/**
|
|
243
|
+
* Reads a clip of `format` from a paste, a drop or a clip payload: finds it in the
|
|
244
|
+
* first carrier that holds one, migrates it from older versions, and validates it.
|
|
245
|
+
* Never throws for clipboard content; every outcome is a {@link ClipReadResult}.
|
|
246
|
+
*
|
|
247
|
+
* Supports asynchronous schemas and `Blob` entries. When you need a result
|
|
248
|
+
* synchronously and your schema is synchronous, use {@link readClipSync}.
|
|
249
|
+
*
|
|
250
|
+
* @example
|
|
251
|
+
* onPaste: async (result) => {
|
|
252
|
+
* const clip = await readClip(result, InvoiceRows);
|
|
253
|
+
* if (clip.status === 'ok') addRows(clip.value);
|
|
254
|
+
* }
|
|
255
|
+
*/
|
|
256
|
+
export declare function readClip<Value>(source: ClipSource, format: ClipFormat<Value>): Promise<ClipReadResult<Value>>;
|
|
257
|
+
/**
|
|
258
|
+
* Synchronous {@link readClip}, e.g. to decide inside a paste or drop handler.
|
|
259
|
+
* `Blob` entries are skipped, and an asynchronous schema yields `invalid`.
|
|
260
|
+
*/
|
|
261
|
+
export declare function readClipSync<Value>(source: ClipSource, format: ClipFormat<Value>): ClipReadResult<Value>;
|
|
262
|
+
/**
|
|
263
|
+
* The `accept` list that lets a paste or drop carry these formats: each format's
|
|
264
|
+
* web custom format and clipboard type, plus HTML. Add `'text'` (or more) if you
|
|
265
|
+
* also handle other content.
|
|
266
|
+
*
|
|
267
|
+
* @example
|
|
268
|
+
* usePaste({ accept: [...clipAccept(InvoiceRows), 'text'], onPaste })
|
|
269
|
+
*/
|
|
270
|
+
export declare function clipAccept(...formats: readonly ClipFormatInfo[]): PasteAccept[];
|
|
271
|
+
//#endregion
|
|
272
|
+
export type { ClipCarrier, ClipDataTransfer, ClipFormat, ClipFormatInfo, ClipFormatOptions, ClipIssue, ClipMigration, ClipPayload, ClipPayloadItem, ClipReadAbsent, ClipReadInvalid, ClipReadOk, ClipReadResult, ClipReadUnsupportedVersion, ClipSchema, ClipSchemaValue, ClipSource, ClipSourceItem, ClipValidator, ClipValue, InferSchemaOutput, StandardSchemaFailure, StandardSchemaIssue, StandardSchemaPathSegment, StandardSchemaProps, StandardSchemaResult, StandardSchemaSuccess, StandardSchemaTypes, StandardSchemaV1 };
|
|
273
|
+
//# sourceMappingURL=structured.d.ts.map
|