react-smart-copy 1.8.0 → 1.9.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.
@@ -0,0 +1,380 @@
1
+ //#region src/core/payload.d.ts
2
+ interface TextPayload {
3
+ readonly kind: 'text';
4
+ readonly value: string;
5
+ }
6
+ interface HtmlPayload {
7
+ readonly kind: 'html';
8
+ readonly html: string;
9
+ /** Required plain-text fallback for targets that don't understand HTML. */
10
+ readonly text: string;
11
+ }
12
+ //#endregion
13
+ //#region src/table/serialize.d.ts
14
+ /**
15
+ * What a table cell may hold. Numbers, bigints, booleans and dates stay typed
16
+ * all the way to the spreadsheet; strings are kept as text.
17
+ */
18
+ type TableCell = string | number | bigint | boolean | Date | null | undefined;
19
+ /** One row of cells, left to right. */
20
+ type TableRow = readonly TableCell[];
21
+ /**
22
+ * A table as plain data: optional header labels and rows of cells.
23
+ * Every helper in this module produces or consumes this shape, so the output of
24
+ * `fromRows`, `fromAgGrid`, `fromTanStackTable` and `parseTable` can all be
25
+ * copied with {@link tablePayload}.
26
+ */
27
+ interface TableData {
28
+ readonly headers?: readonly string[] | null | undefined;
29
+ readonly rows: readonly TableRow[];
30
+ }
31
+ /** Where a cell sits, passed to `formatCell`. Indexes are zero-based; `row` is -1 for the header row. */
32
+ interface CellFormatContext {
33
+ readonly row: number;
34
+ readonly column: number;
35
+ readonly header: string | undefined;
36
+ }
37
+ interface TableFormatOptions {
38
+ /** Include the header row when the data has headers. Default `true`. */
39
+ readonly headers?: boolean;
40
+ /**
41
+ * Neutralise text cells that a spreadsheet would run as a formula: those starting
42
+ * with `=`, `+`, `-`, `@`, a tab or a line break (and their full-width forms), as
43
+ * listed by OWASP's CSV Injection guidance. They get a leading `'`, which
44
+ * spreadsheets treat as "this is text". Typed numbers are never touched, so
45
+ * `-5` as a number stays a number. Default `true`; turn off only for trusted data.
46
+ */
47
+ readonly formulaGuard?: boolean;
48
+ /**
49
+ * Mark string cells as text in the HTML flavour (`mso-number-format:"\@"`), so
50
+ * Excel keeps `00123`, `1/2` or `1E5` exactly as written instead of converting them.
51
+ * Typed numbers, booleans and dates are left for the spreadsheet to recognise.
52
+ * Default `true`.
53
+ */
54
+ readonly preserveText?: boolean;
55
+ /**
56
+ * Custom text for a cell. Return `undefined` to use the default. The result is
57
+ * still escaped, and guarded when the original value was text.
58
+ * Defaults: `null`/`undefined` → empty, `Date` → ISO 8601 (invalid dates → empty),
59
+ * everything else → `String(value)`.
60
+ */
61
+ readonly formatCell?: (value: TableCell, context: CellFormatContext) => string | undefined;
62
+ /** Upper bound on cells (header included), checked before any work. Default 1,000,000. */
63
+ readonly maxCells?: number;
64
+ }
65
+ interface TablePayloadOptions extends TableFormatOptions {
66
+ /**
67
+ * `'html'` (default): an HTML table plus a tab-separated plain-text fallback, which
68
+ * degrades to the plain text where rich copy is unavailable.
69
+ * `'text'`: tab-separated text only.
70
+ */
71
+ readonly format?: 'html' | 'text';
72
+ }
73
+ export declare const DEFAULT_TABLE_MAX_CELLS = 1000000;
74
+ /**
75
+ * Tab-separated text, the format Excel, Google Sheets, Numbers and LibreOffice paste
76
+ * straight into cells. Cells containing tabs, line breaks or quotes are quoted the
77
+ * way Excel quotes them. Throws a `CopyFailure` (`invalid-payload` or `too-large`).
78
+ */
79
+ export declare function tableToTsv(data: TableData, options?: TableFormatOptions): string;
80
+ /** An HTML `<table>`: what rich editors (Docs, Word, Notion, mail) and spreadsheets read first. */
81
+ export declare function tableToHtml(data: TableData, options?: TableFormatOptions): string;
82
+ /**
83
+ * A copy payload for a table, ready for `copy()`, `useCopyInterceptor` or `useDragCopy`.
84
+ *
85
+ * ```ts
86
+ * copy(() => tablePayload(fromRows(invoices, columns)));
87
+ * ```
88
+ *
89
+ * The default `html` format carries the HTML table and the tab-separated text in one
90
+ * clipboard entry. Throws a `CopyFailure` for bad input; inside a `copy()` source that
91
+ * becomes the copy's classified error.
92
+ */
93
+ export declare function tablePayload(data: TableData, options: TablePayloadOptions & {
94
+ readonly format: 'text';
95
+ }): TextPayload;
96
+ export declare function tablePayload(data: TableData, options?: TablePayloadOptions & {
97
+ readonly format?: 'html';
98
+ }): HtmlPayload;
99
+ export declare function tablePayload(data: TableData, options?: TablePayloadOptions): HtmlPayload | TextPayload;
100
+ /** Keys of `Row` whose values are valid cells. */
101
+ type CellKey<Row> = { [K in keyof Row]-?: Row[K] extends TableCell ? K : never; }[keyof Row] & string;
102
+ /** One output column for {@link fromRows}: a header and how to read the cell. */
103
+ interface TableColumn<Row> {
104
+ readonly header: string;
105
+ /** A property of the row, or a function returning the cell. */
106
+ readonly value: CellKey<Row> | ((row: Row, index: number) => TableCell);
107
+ }
108
+ /**
109
+ * Turns your own row objects into {@link TableData}, choosing and ordering columns.
110
+ *
111
+ * ```ts
112
+ * fromRows(users, [
113
+ * { header: 'Name', value: 'name' },
114
+ * { header: 'Joined', value: (user) => user.joinedAt },
115
+ * ]);
116
+ * ```
117
+ */
118
+ export declare function fromRows<Row>(rows: readonly Row[], columns: readonly TableColumn<Row>[]): TableData;
119
+ //#endregion
120
+ //#region src/table/parse.d.ts
121
+ /** A table read from pasted or dropped content. Every cell is a string. */
122
+ interface ParsedTable extends TableData {
123
+ /** The header row, when one was detected or requested; otherwise `null`. */
124
+ readonly headers: readonly string[] | null;
125
+ /** Data rows, all padded to `columnCount`. */
126
+ readonly rows: readonly (readonly string[])[];
127
+ readonly columnCount: number;
128
+ /** Which clipboard flavour the table came from. */
129
+ readonly source: 'html' | 'text';
130
+ /** `true` when rows or columns were dropped to stay within the limits. Never silent. */
131
+ readonly truncated: boolean;
132
+ }
133
+ interface ParseTableOptions {
134
+ /**
135
+ * `'auto'` (default): an HTML table's first row is the header when it sits in
136
+ * `<thead>` or is made of `<th>` cells; plain text has no header.
137
+ * `true`: the first row is always the header. `false`: never.
138
+ */
139
+ readonly headers?: 'auto' | boolean;
140
+ /** Which flavour to read when both are present. Default `'html'`, which keeps merged cells and line breaks exact. */
141
+ readonly prefer?: 'html' | 'text';
142
+ /** Column separator for plain text. Default tab, what spreadsheets put on the clipboard. */
143
+ readonly delimiter?: string;
144
+ /** Merged cells: `'empty'` (default) fills the covered cells with `''`, as spreadsheets do; `'repeat'` copies the value. */
145
+ readonly spans?: 'empty' | 'repeat';
146
+ /** Trim spaces around plain-text cells. HTML cells are always normalised. Default `false`. */
147
+ readonly trim?: boolean;
148
+ /** Most rows kept (header included). Default 100,000. Extra rows set `truncated`. */
149
+ readonly maxRows?: number;
150
+ /** Most columns kept. Default 16,384, Excel's own limit. Extra columns set `truncated`. */
151
+ readonly maxColumns?: number;
152
+ /** Most cells kept. Default 1,000,000. */
153
+ readonly maxCells?: number;
154
+ /** Longest input read, in characters. Default 32 MiB. Longer input fails with `too-large`. */
155
+ readonly maxLength?: number;
156
+ }
157
+ /** Plain text, or anything with `html` and `text`, such as a `PasteResult`. */
158
+ type TableSource = string | {
159
+ readonly html?: string | null | undefined;
160
+ readonly text?: string | null | undefined;
161
+ };
162
+ export declare const DEFAULT_PARSE_MAX_ROWS = 100000;
163
+ export declare const DEFAULT_PARSE_MAX_COLUMNS = 16384;
164
+ export declare const DEFAULT_PARSE_MAX_CELLS = 1000000;
165
+ export declare const DEFAULT_PARSE_MAX_LENGTH: number;
166
+ /**
167
+ * Reads tab-separated (or `delimiter`-separated) text into a table.
168
+ * Returns `null` when there is no non-empty cell.
169
+ */
170
+ export declare function parseDelimited(text: string, options?: ParseTableOptions): ParsedTable | null;
171
+ /**
172
+ * Reads the first non-empty `<table>` from an HTML string (such as Excel, Google Sheets,
173
+ * Word or a web page put on the clipboard) or from an element, which may be the table or
174
+ * contain it. Merged cells, `<br>` line breaks and hidden rows and cells are handled.
175
+ * Returns `null` without a table, without content, or on a server without `DOMParser`.
176
+ */
177
+ export declare function parseHtmlTable(input: string | Element, options?: ParseTableOptions): ParsedTable | null;
178
+ /**
179
+ * Reads a table from pasted content: a `PasteResult` (or any `{ html, text }`), or plain
180
+ * text. The HTML flavour is preferred when it holds a table; otherwise the text is split
181
+ * on tabs. Returns `null` when neither holds any cell content.
182
+ *
183
+ * ```ts
184
+ * usePaste({ accept: ['html', 'text'], onPaste: (result) => setRows(parseTable(result)?.rows ?? []) });
185
+ * ```
186
+ *
187
+ * Throws a `CopyFailure`: `too-large` past `maxLength`, `invalid-payload` for bad options.
188
+ */
189
+ export declare function parseTable(source: TableSource, options?: ParseTableOptions): ParsedTable | null;
190
+ /**
191
+ * Reads a rendered `<table>` (or the first table inside `element`) as {@link TableData},
192
+ * ready for `tablePayload`. Works with any library that renders real table markup.
193
+ * Throws `invalid-payload` when there is no table with content.
194
+ */
195
+ export declare function fromTableElement(element: Element, options?: ParseTableOptions): ParsedTable;
196
+ //#endregion
197
+ //#region src/table/records.d.ts
198
+ /** How to read one field of a record from a pasted table. */
199
+ interface RecordField<Value = string> {
200
+ /**
201
+ * Header text that identifies the column; several for aliases. Matched ignoring case,
202
+ * surrounding and repeated spaces, and full-width characters. Defaults to the key.
203
+ */
204
+ readonly header?: string | readonly string[];
205
+ /** Turns the cell text into a value. Default: the text itself. A throw is reported in `errors`. */
206
+ readonly parse?: (text: string, context: RecordParseContext) => Value;
207
+ /** Report the column in `missing` when the table doesn't have it. Default `false`. */
208
+ readonly required?: boolean;
209
+ }
210
+ interface RecordParseContext {
211
+ /** Zero-based data row (the header row is not counted). */
212
+ readonly row: number;
213
+ readonly key: string;
214
+ }
215
+ /** Field definitions by record key. */
216
+ type RecordSchema = Readonly<Record<string, RecordField<unknown>>>;
217
+ /** The record a schema produces. A value is `undefined` when its column is missing or its `parse` threw. */
218
+ type RecordOf<Schema extends RecordSchema> = { -readonly [Key in keyof Schema]: (Schema[Key] extends {
219
+ readonly parse: (...args: never[]) => infer Value;
220
+ } ? Value : string) | undefined; };
221
+ interface RecordError<Key extends string = string> {
222
+ readonly row: number;
223
+ readonly key: Key;
224
+ readonly text: string;
225
+ readonly cause: unknown;
226
+ }
227
+ interface RecordsResult<Schema extends RecordSchema> {
228
+ readonly records: RecordOf<Schema>[];
229
+ /** Required fields whose column was not found. */
230
+ readonly missing: (keyof Schema & string)[];
231
+ /** Cells whose `parse` threw. */
232
+ readonly errors: RecordError<keyof Schema & string>[];
233
+ /** `true` when nothing is missing and nothing failed to parse. */
234
+ readonly ok: boolean;
235
+ }
236
+ interface ToRecordsOptions {
237
+ /**
238
+ * `'header'`: find columns by header text. `'position'`: the schema's key order is the
239
+ * column order. `'auto'` (default): by header when the table has one, else by position.
240
+ */
241
+ readonly match?: 'auto' | 'header' | 'position';
242
+ /** Skip rows whose cells are all empty. Default `true`. */
243
+ readonly skipEmptyRows?: boolean;
244
+ }
245
+ /** Any table of strings, such as the result of `parseTable`. */
246
+ interface StringTable {
247
+ readonly headers?: readonly string[] | null | undefined;
248
+ readonly rows: readonly (readonly string[])[];
249
+ }
250
+ /**
251
+ * Maps a pasted table onto typed records, for importing rows from Excel or Google Sheets.
252
+ *
253
+ * ```ts
254
+ * const { records, missing, errors } = toRecords(parseTable(result)!, {
255
+ * email: { header: ['Email', 'E-mail'], required: true },
256
+ * seats: { header: 'Seats', parse: (text) => Number.parseInt(text, 10) },
257
+ * });
258
+ * // records: { email: string | undefined; seats: number | undefined }[]
259
+ * ```
260
+ */
261
+ export declare function toRecords<const Schema extends RecordSchema>(table: StringTable, schema: Schema, options?: ToRecordsOptions): RecordsResult<Schema>;
262
+ //#endregion
263
+ //#region src/table/cell-value.d.ts
264
+ /**
265
+ * Turns whatever a grid holds into a cell: primitives and dates as they are, arrays as
266
+ * a comma-separated list, other objects as JSON. Never throws, so one odd value can't
267
+ * break a copy of thousands of rows.
268
+ */
269
+ export declare function toCellValue(value: unknown): TableCell;
270
+ //#endregion
271
+ //#region src/table/ag-grid.d.ts
272
+ interface AgGridColumnLike {
273
+ getColId(): string;
274
+ }
275
+ interface AgGridRowNodeLike {
276
+ /** Position among displayed rows; `null` when filtered out or inside a collapsed group. */
277
+ readonly rowIndex: number | null;
278
+ readonly group?: boolean | undefined;
279
+ }
280
+ interface AgGridApiLike<Node extends AgGridRowNodeLike, Column extends AgGridColumnLike> {
281
+ getAllDisplayedColumns(): Column[];
282
+ getDisplayNameForColumn(column: Column, location: 'csv'): string;
283
+ getSelectedNodes(): Node[];
284
+ getDisplayedRowCount(): number;
285
+ getDisplayedRowAtIndex(index: number): Node | undefined;
286
+ forEachNodeAfterFilterAndSort(callback: (node: Node, index: number) => void): void;
287
+ forEachNode(callback: (node: Node, index: number) => void): void;
288
+ /** v31.3+. */
289
+ getCellValue?(params: {
290
+ rowNode: Node;
291
+ colKey: Column | string;
292
+ useFormatter?: boolean;
293
+ }): unknown;
294
+ /** v31–v32; removed in v33. */
295
+ getValue?(colKey: Column | string, rowNode: Node): unknown;
296
+ }
297
+ interface FromAgGridOptions<Node extends AgGridRowNodeLike, Column extends AgGridColumnLike> {
298
+ /**
299
+ * Which rows, in on-screen order:
300
+ * - `'displayed'` (default): every row the grid displays after filtering, sorting and
301
+ * grouping, across all pages.
302
+ * - `'selected'`: selected rows that are currently displayed.
303
+ * - `'filtered'`: rows passing the filter, in sort order, including those inside
304
+ * collapsed groups.
305
+ * - `'all'`: every row, in the order of your data.
306
+ * - an array of row nodes, taken as given.
307
+ */
308
+ readonly rows?: 'displayed' | 'selected' | 'filtered' | 'all' | readonly Node[];
309
+ /** Column ids to copy, in this order. Default: the displayed columns, minus the selection and row-number columns. */
310
+ readonly columns?: readonly string[];
311
+ /**
312
+ * - `'auto'` (default): numbers, bigints and booleans raw, so spreadsheets can calculate
313
+ * with them; everything else as the grid's `valueFormatter` shows it.
314
+ * - `'raw'`: the underlying values. `'formatted'`: exactly what the grid shows.
315
+ */
316
+ readonly values?: 'auto' | 'raw' | 'formatted';
317
+ /** Include group rows (Enterprise row grouping). Default `false`: only rows with data. */
318
+ readonly includeGroupRows?: boolean;
319
+ /** Header text for a column. Default: the grid's own name for exports. */
320
+ readonly header?: (column: Column) => string;
321
+ }
322
+ /**
323
+ * Reads rows from an AG Grid (v31+, Community or Enterprise) as table data.
324
+ *
325
+ * ```ts
326
+ * copy(() => tablePayload(fromAgGrid(gridRef.current!.api, { rows: 'selected' })));
327
+ * ```
328
+ *
329
+ * Gives Community grids Excel-ready copy, which AG Grid only ships in Enterprise.
330
+ */
331
+ export declare function fromAgGrid<Node extends AgGridRowNodeLike, Column extends AgGridColumnLike>(api: AgGridApiLike<Node, Column>, options?: FromAgGridOptions<Node, Column>): TableData;
332
+ //#endregion
333
+ //#region src/table/tanstack.d.ts
334
+ interface TanStackColumnLike {
335
+ readonly id: string;
336
+ readonly columnDef: {
337
+ readonly header?: unknown;
338
+ };
339
+ /** Absent on display columns (checkboxes, actions), which hold no data. */
340
+ readonly accessorFn?: unknown;
341
+ }
342
+ interface TanStackRowLike {
343
+ getValue(columnId: string): unknown;
344
+ /** Present when the row selection feature is enabled. */
345
+ getIsSelected?: () => boolean;
346
+ }
347
+ interface TanStackTableLike<Row extends TanStackRowLike, Column extends TanStackColumnLike> {
348
+ getRowModel(): {
349
+ readonly rows: readonly Row[];
350
+ };
351
+ getAllLeafColumns(): readonly Column[];
352
+ /** Present when the column visibility feature is enabled (always in v8). */
353
+ getVisibleLeafColumns?: () => readonly Column[];
354
+ }
355
+ interface FromTanStackTableOptions<Row extends TanStackRowLike, Column extends TanStackColumnLike> {
356
+ /**
357
+ * - `'visible'` (default): the rows the table renders now (`getRowModel()`): filtered,
358
+ * sorted, grouped and paginated.
359
+ * - `'selected'`: those of them that are selected.
360
+ * - an array of rows, such as `table.getPrePaginationRowModel().rows` for every page.
361
+ */
362
+ readonly rows?: 'visible' | 'selected' | readonly Row[];
363
+ /** Column ids to copy, in this order. Default: visible leaf columns that hold data. */
364
+ readonly columns?: readonly string[];
365
+ /** Header text for a column. Default: `columnDef.header` when it is a string, else the column id. */
366
+ readonly header?: (column: Column) => string;
367
+ /** The cell for a row and column. Default: `row.getValue(column.id)`. */
368
+ readonly value?: (row: Row, column: Column) => TableCell;
369
+ }
370
+ /**
371
+ * Reads rows from a TanStack Table instance (v8 or v9) as table data.
372
+ *
373
+ * ```ts
374
+ * copy(() => tablePayload(fromTanStackTable(table, { rows: 'selected' })));
375
+ * ```
376
+ */
377
+ export declare function fromTanStackTable<Row extends TanStackRowLike, Column extends TanStackColumnLike>(table: TanStackTableLike<Row, Column>, options?: FromTanStackTableOptions<Row, Column>): TableData;
378
+ //#endregion
379
+ export type { AgGridApiLike, AgGridColumnLike, AgGridRowNodeLike, CellFormatContext, CellKey, FromAgGridOptions, FromTanStackTableOptions, ParseTableOptions, ParsedTable, RecordError, RecordField, RecordOf, RecordParseContext, RecordSchema, RecordsResult, StringTable, TableCell, TableColumn, TableData, TableFormatOptions, TablePayloadOptions, TableRow, TableSource, TanStackColumnLike, TanStackRowLike, TanStackTableLike, ToRecordsOptions };
380
+ //# sourceMappingURL=table.d.ts.map