@constructive-io/sheets 0.13.1 → 0.15.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.
Files changed (61) hide show
  1. package/README.md +231 -148
  2. package/dist/advanced.cjs +7220 -4030
  3. package/dist/advanced.cjs.map +1 -1
  4. package/dist/advanced.d.cts +2 -2
  5. package/dist/advanced.d.ts +2 -2
  6. package/dist/advanced.js +5 -5
  7. package/dist/auth.cjs.map +1 -1
  8. package/dist/auth.js +3 -3
  9. package/dist/chunk-CJ4PRA64.js +312 -0
  10. package/dist/chunk-CJ4PRA64.js.map +1 -0
  11. package/dist/chunk-II3MSNRO.js +18 -0
  12. package/dist/chunk-II3MSNRO.js.map +1 -0
  13. package/dist/{chunk-MXVNIKES.js → chunk-J7KK4UWI.js} +6 -6
  14. package/dist/chunk-MBSHDF55.js +839 -0
  15. package/dist/chunk-MBSHDF55.js.map +1 -0
  16. package/dist/{chunk-ZKANUG3F.js → chunk-MOFFS5WQ.js} +20 -15
  17. package/dist/chunk-MOFFS5WQ.js.map +1 -0
  18. package/dist/chunk-VCBY2AMT.js +8920 -0
  19. package/dist/chunk-VCBY2AMT.js.map +1 -0
  20. package/dist/{chunk-H5HR5HUJ.js → chunk-ZOQDSOMO.js} +50 -312
  21. package/dist/chunk-ZOQDSOMO.js.map +1 -0
  22. package/dist/date-editor-ORCB43ZM.js +346 -0
  23. package/dist/date-editor-ORCB43ZM.js.map +1 -0
  24. package/dist/grid-cell-types-YNIVK4hN.d.cts +346 -0
  25. package/dist/grid-cell-types-YNIVK4hN.d.ts +346 -0
  26. package/dist/index.cjs +22910 -12084
  27. package/dist/index.cjs.map +1 -1
  28. package/dist/index.d.cts +1497 -337
  29. package/dist/index.d.ts +1497 -337
  30. package/dist/index.js +12833 -6142
  31. package/dist/index.js.map +1 -1
  32. package/dist/sheets-context-Bb7ZoNBg.d.cts +436 -0
  33. package/dist/sheets-context-CPuf31LS.d.ts +436 -0
  34. package/dist/testing.cjs +1253 -638
  35. package/dist/testing.cjs.map +1 -1
  36. package/dist/testing.d.cts +80 -11
  37. package/dist/testing.d.ts +80 -11
  38. package/dist/testing.js +791 -148
  39. package/dist/testing.js.map +1 -1
  40. package/package.json +5 -5
  41. package/dist/chunk-4EZ6A23C.js +0 -44
  42. package/dist/chunk-4EZ6A23C.js.map +0 -1
  43. package/dist/chunk-5QPNOKMA.js +0 -4397
  44. package/dist/chunk-5QPNOKMA.js.map +0 -1
  45. package/dist/chunk-AYMXT3ME.js +0 -540
  46. package/dist/chunk-AYMXT3ME.js.map +0 -1
  47. package/dist/chunk-H5HR5HUJ.js.map +0 -1
  48. package/dist/chunk-PZL2BCWF.js +0 -168
  49. package/dist/chunk-PZL2BCWF.js.map +0 -1
  50. package/dist/chunk-X7DHTSOX.js +0 -21
  51. package/dist/chunk-X7DHTSOX.js.map +0 -1
  52. package/dist/chunk-ZKANUG3F.js.map +0 -1
  53. package/dist/date-editor-ZFNDKYBD.js +0 -358
  54. package/dist/date-editor-ZFNDKYBD.js.map +0 -1
  55. package/dist/grid-cell-types-Pbe2m2tE.d.cts +0 -253
  56. package/dist/grid-cell-types-Pbe2m2tE.d.ts +0 -253
  57. package/dist/map-picker-ZUGGOIZS.js +0 -290
  58. package/dist/map-picker-ZUGGOIZS.js.map +0 -1
  59. package/dist/sheets-context-CY1RmDKL.d.cts +0 -244
  60. package/dist/sheets-context-Cu3Ec_ca.d.ts +0 -244
  61. /package/dist/{chunk-MXVNIKES.js.map → chunk-J7KK4UWI.js.map} +0 -0
@@ -0,0 +1,346 @@
1
+ import { RelationModel, TableModel, RowIdentityValue, TableWriteCapability, MetaTable, RowKey, ColumnModel } from '@constructive-io/data';
2
+ import { ComponentType } from 'react';
3
+
4
+ interface FieldMetadata$1 {
5
+ name: string;
6
+ type?: {
7
+ gqlType: string;
8
+ pgType?: string | null;
9
+ pgAlias?: string | null;
10
+ isArray?: boolean;
11
+ subtype?: string | null;
12
+ };
13
+ }
14
+ interface CellTypeResolution {
15
+ cellType: string;
16
+ canEdit: boolean;
17
+ canActivate: boolean;
18
+ activationBehavior: 'single-click' | 'double-click';
19
+ isReadonly: boolean;
20
+ }
21
+ /**
22
+ * Resolve a cell type from raw `_meta` field metadata.
23
+ *
24
+ * @deprecated The grid routes table-model columns with `cellTypeForColumn` and takes
25
+ * read-only state from the model's write flags. This resolver never marks a field
26
+ * read-only by its name; it only says whether the cell type itself is editable.
27
+ */
28
+ declare function resolveCellType(fieldName: string, fieldMeta?: FieldMetadata$1): CellTypeResolution;
29
+ /**
30
+ * Whether raw field metadata describes an image column. Decided by the type only
31
+ * (a registered matcher or the image type), never by the field's name.
32
+ *
33
+ * @deprecated Read `ColumnModel.value.file?.kind === 'image'` from the table model.
34
+ */
35
+ declare function isImageField(fieldMeta?: FieldMetadata$1, fieldName?: string): boolean;
36
+
37
+ type CellType = 'text' | 'textarea' | 'email' | 'url' | 'phone' | 'citext' | 'bpchar' | 'number' | 'integer' | 'smallint' | 'bigint' | 'decimal' | 'currency' | 'percentage' | 'select' | 'multi-select' | 'date' | 'datetime' | 'time' | 'timestamptz' | 'interval' | 'boolean' | 'toggle' | 'bit' | 'bitstring' | 'json' | 'jsonb' | 'array' | 'range' | 'composite' | 'point' | 'text-array' | 'uuid-array' | 'number-array' | 'integer-array' | 'date-array' | 'geometry' | 'geometry-point' | 'geometry-collection' | 'inet' | 'image' | 'file' | 'video' | 'audio' | 'upload' | 'attachment' | 'uuid' | 'color' | 'rating' | 'tags' | 'tsvector' | 'origin' | 'path' | 'binary' | 'vector' | 'relation' | 'unknown';
38
+ type CellCategory = 'text' | 'numeric' | 'date' | 'boolean' | 'structured' | 'geometric' | 'network' | 'media' | 'special' | 'other';
39
+ type CellValue = string | number | boolean | Date | null | undefined | Array<any> | Record<string, any>;
40
+ interface FieldMetadata {
41
+ name: string;
42
+ gqlType: string;
43
+ isArray: boolean;
44
+ modifier?: string | number | null;
45
+ pgAlias?: string | null;
46
+ pgType?: string | null;
47
+ subtype?: string | null;
48
+ typmod?: number | null;
49
+ encoding?: {
50
+ kind: string;
51
+ elementType?: string | null;
52
+ dimensions?: number | null;
53
+ geometrySubtype?: string | null;
54
+ srid?: number | null;
55
+ dotPath?: boolean | null;
56
+ } | null;
57
+ }
58
+ interface ColumnSchema {
59
+ id: string;
60
+ name: string;
61
+ type: CellType;
62
+ nullable: boolean;
63
+ metadata?: {
64
+ label?: string;
65
+ description?: string;
66
+ hidden?: boolean;
67
+ readonly?: boolean;
68
+ sortable?: boolean;
69
+ filterable?: boolean;
70
+ isArray?: boolean;
71
+ placeholder?: string;
72
+ maxLength?: number;
73
+ minLength?: number;
74
+ pattern?: string;
75
+ rows?: number;
76
+ required?: boolean;
77
+ };
78
+ }
79
+ interface TableSchema {
80
+ id: string;
81
+ name: string;
82
+ columns: ColumnSchema[];
83
+ metadata?: {
84
+ label?: string;
85
+ description?: string;
86
+ primaryKey?: string[];
87
+ indexes?: Array<{
88
+ columns: string[];
89
+ unique?: boolean;
90
+ }>;
91
+ };
92
+ }
93
+ interface RowData {
94
+ id: string;
95
+ [columnId: string]: CellValue;
96
+ }
97
+
98
+ /**
99
+ * @deprecated since 0.2.0 — use CellTypeDefinition (defineCellType). This React-component model was never rendered by the canvas grid.
100
+ */
101
+ interface BaseCellProps {
102
+ value: CellValue;
103
+ column: ColumnSchema;
104
+ rowId: string;
105
+ isEditing?: boolean;
106
+ onChange?: (value: CellValue) => void;
107
+ onStartEdit?: () => void;
108
+ onSave?: () => void;
109
+ onCancel?: () => void;
110
+ className?: string;
111
+ disabled?: boolean;
112
+ }
113
+ /**
114
+ * @deprecated since 0.2.0 — use CellTypeDefinition (defineCellType). This React-component model was never rendered by the canvas grid.
115
+ */
116
+ type CellRenderer = ComponentType<BaseCellProps>;
117
+ /**
118
+ * @deprecated since 0.2.0 — use CellTypeDefinition (defineCellType). This React-component model was never rendered by the canvas grid.
119
+ */
120
+ interface CellRegistryEntry {
121
+ type: CellType;
122
+ component: CellRenderer;
123
+ editComponent?: CellRenderer;
124
+ validator?: (value: CellValue) => boolean;
125
+ formatter?: (value: CellValue) => string;
126
+ parser?: (input: string) => CellValue;
127
+ defaultValue?: () => CellValue;
128
+ match?: (metadata: {
129
+ gqlType: string;
130
+ isArray: boolean;
131
+ pgAlias?: string | null;
132
+ pgType?: string | null;
133
+ subtype?: string | null;
134
+ fieldName?: string;
135
+ value?: any;
136
+ }) => boolean;
137
+ metadata?: {
138
+ name: string;
139
+ description: string;
140
+ category: CellCategory;
141
+ supportsInlineEdit?: boolean;
142
+ supportsSort?: boolean;
143
+ supportsFilter?: boolean;
144
+ width?: number;
145
+ };
146
+ }
147
+ /**
148
+ * @deprecated since 0.2.0 — use CellTypeDefinition (defineCellType). This React-component model was never rendered by the canvas grid.
149
+ */
150
+ interface CellPlugin {
151
+ name: string;
152
+ version: string;
153
+ cells: CellRegistryEntry[];
154
+ install?: () => void;
155
+ uninstall?: () => void;
156
+ }
157
+
158
+ /**
159
+ * Neutral render kinds. `loading` and `draft-action` originate from grid-internal
160
+ * state, not the `CellType` system.
161
+ */
162
+ type SheetsCellKind = 'text' | 'number' | 'boolean' | 'badges' | 'uri' | 'image' | 'geometry' | 'relation' | 'loading' | 'draft-action' | 'custom';
163
+ /** Per-cell visual hint, open-ish so later phases can enrich it. */
164
+ interface SheetsCellStyleHint {
165
+ draft?: boolean;
166
+ faded?: boolean;
167
+ /** This draft cell has a field-level validation error (draftMeta.errors[colKey]). */
168
+ error?: boolean;
169
+ /** The server could not send this value: the cell shows a muted notice instead. */
170
+ unreadable?: boolean;
171
+ [extra: string]: unknown;
172
+ }
173
+ /**
174
+ * The factory output + render payload. A SINGLE interface with a `kind` field
175
+ * (not a per-kind discriminated union): text/number/boolean share this payload
176
+ * and do not diverge yet.
177
+ *
178
+ * TODO(phases 2+): enrich `meta` per kind (badges/uri/image/geometry/relation)
179
+ * once their factories and views are ported.
180
+ */
181
+ interface SheetsCell {
182
+ kind: SheetsCellKind;
183
+ data: unknown;
184
+ displayData: string;
185
+ readonly: boolean;
186
+ styleHint?: SheetsCellStyleHint;
187
+ meta?: {
188
+ cellType?: CellType;
189
+ [extra: string]: unknown;
190
+ };
191
+ }
192
+
193
+ interface DraftFieldGap {
194
+ /** The model field without a value. */
195
+ field: string;
196
+ /** The grid column that fills it: the field itself, or the link column of the relation it keys. */
197
+ columnKey: string;
198
+ /** The column's label, as its header shows it. */
199
+ label: string;
200
+ }
201
+
202
+ /** Result of submitting a draft row */
203
+ interface DraftSubmitResult {
204
+ /** The created row with its metadata-defined primary-key fields. */
205
+ createdRow: Record<string, unknown> | null;
206
+ /** Required fields the draft still lacks, when Save was refused before sending. */
207
+ missing?: readonly DraftFieldGap[];
208
+ }
209
+
210
+ type RelationKind = 'belongsTo' | 'hasOne' | 'hasMany' | 'manyToMany';
211
+ /**
212
+ * Per-column relation facts for cell routing, draft rows and draft submission.
213
+ * Built from the table model by {@link relationInfoFromModel}; `relation` is the
214
+ * model's relation itself and is the source of truth for keys and labels.
215
+ */
216
+ interface RelationInfo {
217
+ kind: RelationKind;
218
+ /** GraphQL type name of the related table. */
219
+ relatedTable?: string;
220
+ /** Fields that label a related record (the related table's display rule). */
221
+ displayCandidates: string[];
222
+ /** The relation field on the row. */
223
+ relationField?: string;
224
+ /** belongsTo only: the local key field this entry stands for (on the relation entry, the first one). */
225
+ foreignKeyField?: string;
226
+ /** The relation model behind this entry. */
227
+ relation?: RelationModel;
228
+ }
229
+ /**
230
+ * Relation entries per column key, from the table model: one entry per relation
231
+ * column the grid shows, plus one per local key field of a shown belongsTo (so a
232
+ * draft submission sends those fields and skips the relation field). Derived, not
233
+ * cached: a new model (after a `_meta` refetch) gives new entries.
234
+ */
235
+ declare function relationInfoFromModel(model: TableModel | null | undefined): Map<string, RelationInfo>;
236
+
237
+ /** A row locator accepted by Sheets CRUD operations. */
238
+ type SheetsRowIdentifier = string | number | Readonly<Record<string, RowIdentityValue>>;
239
+ type SheetsMutationOperation = 'create' | 'update' | 'delete';
240
+ type SheetsRowIdentityResolution = Readonly<{
241
+ status: 'identified';
242
+ /** Backwards-compatible scalar for an ordinary `id` PK; otherwise the PK object. */
243
+ identifier: SheetsRowIdentifier;
244
+ /** GraphQL primary-key input, including renamed and composite keys. */
245
+ primaryKey: Readonly<Record<string, RowIdentityValue>>;
246
+ /** Stable, schema-qualified key used by caches, selection, and editors. */
247
+ key: string;
248
+ }> | Readonly<{
249
+ status: 'unavailable';
250
+ reason: 'no-primary-key' | 'invalid-row';
251
+ }>;
252
+ /**
253
+ * Resolve one server row from `_meta`. The familiar scalar `id` contract is kept
254
+ * for existing adapters, while renamed and composite keys use the full PK input.
255
+ */
256
+ declare function resolveSheetsRowIdentity(table: MetaTable, row: Readonly<Record<string, unknown>>): SheetsRowIdentityResolution;
257
+ /** Resolve a public CRUD identifier through the same `_meta` identity contract. */
258
+ declare function resolveSheetsIdentifier(table: MetaTable, identifier: SheetsRowIdentifier): SheetsRowIdentityResolution;
259
+ /** Build the PostGraphile connection filter used by `findOne`. */
260
+ declare function sheetsIdentifierToWhere(table: MetaTable, identifier: SheetsRowIdentifier): Record<string, {
261
+ equalTo: RowIdentityValue;
262
+ }> | null;
263
+ /**
264
+ * The primary-key values a model document needs. A scalar identifier is the
265
+ * value of a one-field key, whatever that field is called; an object must
266
+ * carry every key field.
267
+ */
268
+ declare function sheetsIdentifierToRowKey(model: TableModel, identifier: SheetsRowIdentifier): RowKey;
269
+ /** Use scalar IDs as cache keys for compatibility; use serialized identities otherwise. */
270
+ declare function sheetsIdentifierCacheKey(table: MetaTable, identifier: SheetsRowIdentifier): string | number | null;
271
+ /** Stable TanStack/selection/editor key with an index fallback only for non-writable rows. */
272
+ declare function sheetsRowKey(table: MetaTable, row: Readonly<Record<string, unknown>>, index: number): string;
273
+ declare function getSheetsWriteCapability(table: MetaTable | null): TableWriteCapability | null;
274
+ declare function canRunSheetsMutation(capability: TableWriteCapability | null, operation: SheetsMutationOperation): boolean;
275
+
276
+ interface EditorProps {
277
+ value: unknown;
278
+ cell: SheetsCell;
279
+ colKey: string;
280
+ rowId: string;
281
+ rowIdentifier?: SheetsRowIdentifier | null;
282
+ /** The row being edited (server or draft), or null. Relation editors read the row's own key values from it. */
283
+ row?: Readonly<Record<string, unknown>> | null;
284
+ rowIndex: number;
285
+ tableName?: string;
286
+ fieldMeta?: FieldMetadata$1;
287
+ relationInfo?: RelationInfo;
288
+ /** The table-model column behind this cell, or null when the cell is not a column. */
289
+ column?: ColumnModel | null;
290
+ /** The table-model relation behind this cell, or null when the cell is not a relation. */
291
+ relation?: RelationModel | null;
292
+ /** The table model of the grid, or null while it loads. */
293
+ table?: TableModel | null;
294
+ /** Why the cell cannot be written, from the table model; null when it can. */
295
+ readOnlyReason?: string | null;
296
+ /**
297
+ * Type-to-edit seed: when the overlay was opened by typing a printable char on the
298
+ * active cell, this carries that char. Value editors (text/number) initialize their
299
+ * input to it in OVERWRITE mode (replacing the cell value); other editors ignore it.
300
+ */
301
+ initialText?: string;
302
+ /** Commit a value down the glide value-commit path (onCellEdited -> editCell). */
303
+ onCommit: (next: unknown) => void;
304
+ /**
305
+ * Self-committing editors (relation/image): commit a MULTI-field patch after an
306
+ * out-of-band server mutation, routed through the existing optimistic-update path
307
+ * (handleEditorSaveComplete). Value editors use {@link onCommit} instead.
308
+ */
309
+ onCommitPatch?: (patch: Record<string, unknown>) => void;
310
+ /** Dismiss the overlay with no write. */
311
+ onCancel: () => void;
312
+ /** Self-committing editors: submit a client-side draft row and return its creation result. */
313
+ onSubmitDraftRow?: (draftRowId: string) => Promise<DraftSubmitResult>;
314
+ /** Self-committing editors: invalidate cached data after an out-of-band mutation. */
315
+ onInvalidateData?: () => void;
316
+ /** Geometry pre-computed by the OverlayManager (reused `computeOverlayGeometry`). */
317
+ overlay: {
318
+ maxHeight: number;
319
+ flipped: boolean;
320
+ };
321
+ }
322
+
323
+ interface RelationCellOptions {
324
+ relationChipLimit?: number;
325
+ relationLabelMaxLength?: number;
326
+ }
327
+ interface CellCreationMetadata {
328
+ cellType: string;
329
+ fieldName: string;
330
+ fieldMeta?: FieldMetadata$1;
331
+ relationInfo?: RelationInfo;
332
+ /** The table-model column behind this cell, or null when the cell is not a column (a relation, a draft action). */
333
+ column?: ColumnModel | null;
334
+ /** The table-model relation behind this cell, or null when the cell is not a relation. */
335
+ relation?: RelationModel | null;
336
+ /** The table model of the grid, or null while it loads. */
337
+ table?: TableModel | null;
338
+ /** Every record a list relation links to when the relation reports a total, else null ("+N more"). */
339
+ relationTotalCount?: number | null;
340
+ relationOptions?: RelationCellOptions;
341
+ canEdit: boolean;
342
+ isReadonly: boolean;
343
+ activationBehavior: 'single-click' | 'double-click';
344
+ }
345
+
346
+ export { type BaseCellProps as B, type CellCreationMetadata as C, type DraftSubmitResult as D, type EditorProps as E, type FieldMetadata$1 as F, type RelationInfo as R, type SheetsCell as S, type TableSchema as T, type SheetsCellKind as a, type CellType as b, type CellCategory as c, type SheetsRowIdentifier as d, type CellRegistryEntry as e, type CellRenderer as f, type CellPlugin as g, type ColumnSchema as h, type CellValue as i, type FieldMetadata as j, type RelationKind as k, type RowData as l, type SheetsRowIdentityResolution as m, canRunSheetsMutation as n, getSheetsWriteCapability as o, isImageField as p, resolveCellType as q, relationInfoFromModel as r, resolveSheetsIdentifier as s, resolveSheetsRowIdentity as t, sheetsIdentifierCacheKey as u, sheetsIdentifierToRowKey as v, sheetsIdentifierToWhere as w, sheetsRowKey as x };
@@ -0,0 +1,346 @@
1
+ import { RelationModel, TableModel, RowIdentityValue, TableWriteCapability, MetaTable, RowKey, ColumnModel } from '@constructive-io/data';
2
+ import { ComponentType } from 'react';
3
+
4
+ interface FieldMetadata$1 {
5
+ name: string;
6
+ type?: {
7
+ gqlType: string;
8
+ pgType?: string | null;
9
+ pgAlias?: string | null;
10
+ isArray?: boolean;
11
+ subtype?: string | null;
12
+ };
13
+ }
14
+ interface CellTypeResolution {
15
+ cellType: string;
16
+ canEdit: boolean;
17
+ canActivate: boolean;
18
+ activationBehavior: 'single-click' | 'double-click';
19
+ isReadonly: boolean;
20
+ }
21
+ /**
22
+ * Resolve a cell type from raw `_meta` field metadata.
23
+ *
24
+ * @deprecated The grid routes table-model columns with `cellTypeForColumn` and takes
25
+ * read-only state from the model's write flags. This resolver never marks a field
26
+ * read-only by its name; it only says whether the cell type itself is editable.
27
+ */
28
+ declare function resolveCellType(fieldName: string, fieldMeta?: FieldMetadata$1): CellTypeResolution;
29
+ /**
30
+ * Whether raw field metadata describes an image column. Decided by the type only
31
+ * (a registered matcher or the image type), never by the field's name.
32
+ *
33
+ * @deprecated Read `ColumnModel.value.file?.kind === 'image'` from the table model.
34
+ */
35
+ declare function isImageField(fieldMeta?: FieldMetadata$1, fieldName?: string): boolean;
36
+
37
+ type CellType = 'text' | 'textarea' | 'email' | 'url' | 'phone' | 'citext' | 'bpchar' | 'number' | 'integer' | 'smallint' | 'bigint' | 'decimal' | 'currency' | 'percentage' | 'select' | 'multi-select' | 'date' | 'datetime' | 'time' | 'timestamptz' | 'interval' | 'boolean' | 'toggle' | 'bit' | 'bitstring' | 'json' | 'jsonb' | 'array' | 'range' | 'composite' | 'point' | 'text-array' | 'uuid-array' | 'number-array' | 'integer-array' | 'date-array' | 'geometry' | 'geometry-point' | 'geometry-collection' | 'inet' | 'image' | 'file' | 'video' | 'audio' | 'upload' | 'attachment' | 'uuid' | 'color' | 'rating' | 'tags' | 'tsvector' | 'origin' | 'path' | 'binary' | 'vector' | 'relation' | 'unknown';
38
+ type CellCategory = 'text' | 'numeric' | 'date' | 'boolean' | 'structured' | 'geometric' | 'network' | 'media' | 'special' | 'other';
39
+ type CellValue = string | number | boolean | Date | null | undefined | Array<any> | Record<string, any>;
40
+ interface FieldMetadata {
41
+ name: string;
42
+ gqlType: string;
43
+ isArray: boolean;
44
+ modifier?: string | number | null;
45
+ pgAlias?: string | null;
46
+ pgType?: string | null;
47
+ subtype?: string | null;
48
+ typmod?: number | null;
49
+ encoding?: {
50
+ kind: string;
51
+ elementType?: string | null;
52
+ dimensions?: number | null;
53
+ geometrySubtype?: string | null;
54
+ srid?: number | null;
55
+ dotPath?: boolean | null;
56
+ } | null;
57
+ }
58
+ interface ColumnSchema {
59
+ id: string;
60
+ name: string;
61
+ type: CellType;
62
+ nullable: boolean;
63
+ metadata?: {
64
+ label?: string;
65
+ description?: string;
66
+ hidden?: boolean;
67
+ readonly?: boolean;
68
+ sortable?: boolean;
69
+ filterable?: boolean;
70
+ isArray?: boolean;
71
+ placeholder?: string;
72
+ maxLength?: number;
73
+ minLength?: number;
74
+ pattern?: string;
75
+ rows?: number;
76
+ required?: boolean;
77
+ };
78
+ }
79
+ interface TableSchema {
80
+ id: string;
81
+ name: string;
82
+ columns: ColumnSchema[];
83
+ metadata?: {
84
+ label?: string;
85
+ description?: string;
86
+ primaryKey?: string[];
87
+ indexes?: Array<{
88
+ columns: string[];
89
+ unique?: boolean;
90
+ }>;
91
+ };
92
+ }
93
+ interface RowData {
94
+ id: string;
95
+ [columnId: string]: CellValue;
96
+ }
97
+
98
+ /**
99
+ * @deprecated since 0.2.0 — use CellTypeDefinition (defineCellType). This React-component model was never rendered by the canvas grid.
100
+ */
101
+ interface BaseCellProps {
102
+ value: CellValue;
103
+ column: ColumnSchema;
104
+ rowId: string;
105
+ isEditing?: boolean;
106
+ onChange?: (value: CellValue) => void;
107
+ onStartEdit?: () => void;
108
+ onSave?: () => void;
109
+ onCancel?: () => void;
110
+ className?: string;
111
+ disabled?: boolean;
112
+ }
113
+ /**
114
+ * @deprecated since 0.2.0 — use CellTypeDefinition (defineCellType). This React-component model was never rendered by the canvas grid.
115
+ */
116
+ type CellRenderer = ComponentType<BaseCellProps>;
117
+ /**
118
+ * @deprecated since 0.2.0 — use CellTypeDefinition (defineCellType). This React-component model was never rendered by the canvas grid.
119
+ */
120
+ interface CellRegistryEntry {
121
+ type: CellType;
122
+ component: CellRenderer;
123
+ editComponent?: CellRenderer;
124
+ validator?: (value: CellValue) => boolean;
125
+ formatter?: (value: CellValue) => string;
126
+ parser?: (input: string) => CellValue;
127
+ defaultValue?: () => CellValue;
128
+ match?: (metadata: {
129
+ gqlType: string;
130
+ isArray: boolean;
131
+ pgAlias?: string | null;
132
+ pgType?: string | null;
133
+ subtype?: string | null;
134
+ fieldName?: string;
135
+ value?: any;
136
+ }) => boolean;
137
+ metadata?: {
138
+ name: string;
139
+ description: string;
140
+ category: CellCategory;
141
+ supportsInlineEdit?: boolean;
142
+ supportsSort?: boolean;
143
+ supportsFilter?: boolean;
144
+ width?: number;
145
+ };
146
+ }
147
+ /**
148
+ * @deprecated since 0.2.0 — use CellTypeDefinition (defineCellType). This React-component model was never rendered by the canvas grid.
149
+ */
150
+ interface CellPlugin {
151
+ name: string;
152
+ version: string;
153
+ cells: CellRegistryEntry[];
154
+ install?: () => void;
155
+ uninstall?: () => void;
156
+ }
157
+
158
+ /**
159
+ * Neutral render kinds. `loading` and `draft-action` originate from grid-internal
160
+ * state, not the `CellType` system.
161
+ */
162
+ type SheetsCellKind = 'text' | 'number' | 'boolean' | 'badges' | 'uri' | 'image' | 'geometry' | 'relation' | 'loading' | 'draft-action' | 'custom';
163
+ /** Per-cell visual hint, open-ish so later phases can enrich it. */
164
+ interface SheetsCellStyleHint {
165
+ draft?: boolean;
166
+ faded?: boolean;
167
+ /** This draft cell has a field-level validation error (draftMeta.errors[colKey]). */
168
+ error?: boolean;
169
+ /** The server could not send this value: the cell shows a muted notice instead. */
170
+ unreadable?: boolean;
171
+ [extra: string]: unknown;
172
+ }
173
+ /**
174
+ * The factory output + render payload. A SINGLE interface with a `kind` field
175
+ * (not a per-kind discriminated union): text/number/boolean share this payload
176
+ * and do not diverge yet.
177
+ *
178
+ * TODO(phases 2+): enrich `meta` per kind (badges/uri/image/geometry/relation)
179
+ * once their factories and views are ported.
180
+ */
181
+ interface SheetsCell {
182
+ kind: SheetsCellKind;
183
+ data: unknown;
184
+ displayData: string;
185
+ readonly: boolean;
186
+ styleHint?: SheetsCellStyleHint;
187
+ meta?: {
188
+ cellType?: CellType;
189
+ [extra: string]: unknown;
190
+ };
191
+ }
192
+
193
+ interface DraftFieldGap {
194
+ /** The model field without a value. */
195
+ field: string;
196
+ /** The grid column that fills it: the field itself, or the link column of the relation it keys. */
197
+ columnKey: string;
198
+ /** The column's label, as its header shows it. */
199
+ label: string;
200
+ }
201
+
202
+ /** Result of submitting a draft row */
203
+ interface DraftSubmitResult {
204
+ /** The created row with its metadata-defined primary-key fields. */
205
+ createdRow: Record<string, unknown> | null;
206
+ /** Required fields the draft still lacks, when Save was refused before sending. */
207
+ missing?: readonly DraftFieldGap[];
208
+ }
209
+
210
+ type RelationKind = 'belongsTo' | 'hasOne' | 'hasMany' | 'manyToMany';
211
+ /**
212
+ * Per-column relation facts for cell routing, draft rows and draft submission.
213
+ * Built from the table model by {@link relationInfoFromModel}; `relation` is the
214
+ * model's relation itself and is the source of truth for keys and labels.
215
+ */
216
+ interface RelationInfo {
217
+ kind: RelationKind;
218
+ /** GraphQL type name of the related table. */
219
+ relatedTable?: string;
220
+ /** Fields that label a related record (the related table's display rule). */
221
+ displayCandidates: string[];
222
+ /** The relation field on the row. */
223
+ relationField?: string;
224
+ /** belongsTo only: the local key field this entry stands for (on the relation entry, the first one). */
225
+ foreignKeyField?: string;
226
+ /** The relation model behind this entry. */
227
+ relation?: RelationModel;
228
+ }
229
+ /**
230
+ * Relation entries per column key, from the table model: one entry per relation
231
+ * column the grid shows, plus one per local key field of a shown belongsTo (so a
232
+ * draft submission sends those fields and skips the relation field). Derived, not
233
+ * cached: a new model (after a `_meta` refetch) gives new entries.
234
+ */
235
+ declare function relationInfoFromModel(model: TableModel | null | undefined): Map<string, RelationInfo>;
236
+
237
+ /** A row locator accepted by Sheets CRUD operations. */
238
+ type SheetsRowIdentifier = string | number | Readonly<Record<string, RowIdentityValue>>;
239
+ type SheetsMutationOperation = 'create' | 'update' | 'delete';
240
+ type SheetsRowIdentityResolution = Readonly<{
241
+ status: 'identified';
242
+ /** Backwards-compatible scalar for an ordinary `id` PK; otherwise the PK object. */
243
+ identifier: SheetsRowIdentifier;
244
+ /** GraphQL primary-key input, including renamed and composite keys. */
245
+ primaryKey: Readonly<Record<string, RowIdentityValue>>;
246
+ /** Stable, schema-qualified key used by caches, selection, and editors. */
247
+ key: string;
248
+ }> | Readonly<{
249
+ status: 'unavailable';
250
+ reason: 'no-primary-key' | 'invalid-row';
251
+ }>;
252
+ /**
253
+ * Resolve one server row from `_meta`. The familiar scalar `id` contract is kept
254
+ * for existing adapters, while renamed and composite keys use the full PK input.
255
+ */
256
+ declare function resolveSheetsRowIdentity(table: MetaTable, row: Readonly<Record<string, unknown>>): SheetsRowIdentityResolution;
257
+ /** Resolve a public CRUD identifier through the same `_meta` identity contract. */
258
+ declare function resolveSheetsIdentifier(table: MetaTable, identifier: SheetsRowIdentifier): SheetsRowIdentityResolution;
259
+ /** Build the PostGraphile connection filter used by `findOne`. */
260
+ declare function sheetsIdentifierToWhere(table: MetaTable, identifier: SheetsRowIdentifier): Record<string, {
261
+ equalTo: RowIdentityValue;
262
+ }> | null;
263
+ /**
264
+ * The primary-key values a model document needs. A scalar identifier is the
265
+ * value of a one-field key, whatever that field is called; an object must
266
+ * carry every key field.
267
+ */
268
+ declare function sheetsIdentifierToRowKey(model: TableModel, identifier: SheetsRowIdentifier): RowKey;
269
+ /** Use scalar IDs as cache keys for compatibility; use serialized identities otherwise. */
270
+ declare function sheetsIdentifierCacheKey(table: MetaTable, identifier: SheetsRowIdentifier): string | number | null;
271
+ /** Stable TanStack/selection/editor key with an index fallback only for non-writable rows. */
272
+ declare function sheetsRowKey(table: MetaTable, row: Readonly<Record<string, unknown>>, index: number): string;
273
+ declare function getSheetsWriteCapability(table: MetaTable | null): TableWriteCapability | null;
274
+ declare function canRunSheetsMutation(capability: TableWriteCapability | null, operation: SheetsMutationOperation): boolean;
275
+
276
+ interface EditorProps {
277
+ value: unknown;
278
+ cell: SheetsCell;
279
+ colKey: string;
280
+ rowId: string;
281
+ rowIdentifier?: SheetsRowIdentifier | null;
282
+ /** The row being edited (server or draft), or null. Relation editors read the row's own key values from it. */
283
+ row?: Readonly<Record<string, unknown>> | null;
284
+ rowIndex: number;
285
+ tableName?: string;
286
+ fieldMeta?: FieldMetadata$1;
287
+ relationInfo?: RelationInfo;
288
+ /** The table-model column behind this cell, or null when the cell is not a column. */
289
+ column?: ColumnModel | null;
290
+ /** The table-model relation behind this cell, or null when the cell is not a relation. */
291
+ relation?: RelationModel | null;
292
+ /** The table model of the grid, or null while it loads. */
293
+ table?: TableModel | null;
294
+ /** Why the cell cannot be written, from the table model; null when it can. */
295
+ readOnlyReason?: string | null;
296
+ /**
297
+ * Type-to-edit seed: when the overlay was opened by typing a printable char on the
298
+ * active cell, this carries that char. Value editors (text/number) initialize their
299
+ * input to it in OVERWRITE mode (replacing the cell value); other editors ignore it.
300
+ */
301
+ initialText?: string;
302
+ /** Commit a value down the glide value-commit path (onCellEdited -> editCell). */
303
+ onCommit: (next: unknown) => void;
304
+ /**
305
+ * Self-committing editors (relation/image): commit a MULTI-field patch after an
306
+ * out-of-band server mutation, routed through the existing optimistic-update path
307
+ * (handleEditorSaveComplete). Value editors use {@link onCommit} instead.
308
+ */
309
+ onCommitPatch?: (patch: Record<string, unknown>) => void;
310
+ /** Dismiss the overlay with no write. */
311
+ onCancel: () => void;
312
+ /** Self-committing editors: submit a client-side draft row and return its creation result. */
313
+ onSubmitDraftRow?: (draftRowId: string) => Promise<DraftSubmitResult>;
314
+ /** Self-committing editors: invalidate cached data after an out-of-band mutation. */
315
+ onInvalidateData?: () => void;
316
+ /** Geometry pre-computed by the OverlayManager (reused `computeOverlayGeometry`). */
317
+ overlay: {
318
+ maxHeight: number;
319
+ flipped: boolean;
320
+ };
321
+ }
322
+
323
+ interface RelationCellOptions {
324
+ relationChipLimit?: number;
325
+ relationLabelMaxLength?: number;
326
+ }
327
+ interface CellCreationMetadata {
328
+ cellType: string;
329
+ fieldName: string;
330
+ fieldMeta?: FieldMetadata$1;
331
+ relationInfo?: RelationInfo;
332
+ /** The table-model column behind this cell, or null when the cell is not a column (a relation, a draft action). */
333
+ column?: ColumnModel | null;
334
+ /** The table-model relation behind this cell, or null when the cell is not a relation. */
335
+ relation?: RelationModel | null;
336
+ /** The table model of the grid, or null while it loads. */
337
+ table?: TableModel | null;
338
+ /** Every record a list relation links to when the relation reports a total, else null ("+N more"). */
339
+ relationTotalCount?: number | null;
340
+ relationOptions?: RelationCellOptions;
341
+ canEdit: boolean;
342
+ isReadonly: boolean;
343
+ activationBehavior: 'single-click' | 'double-click';
344
+ }
345
+
346
+ export { type BaseCellProps as B, type CellCreationMetadata as C, type DraftSubmitResult as D, type EditorProps as E, type FieldMetadata$1 as F, type RelationInfo as R, type SheetsCell as S, type TableSchema as T, type SheetsCellKind as a, type CellType as b, type CellCategory as c, type SheetsRowIdentifier as d, type CellRegistryEntry as e, type CellRenderer as f, type CellPlugin as g, type ColumnSchema as h, type CellValue as i, type FieldMetadata as j, type RelationKind as k, type RowData as l, type SheetsRowIdentityResolution as m, canRunSheetsMutation as n, getSheetsWriteCapability as o, isImageField as p, resolveCellType as q, relationInfoFromModel as r, resolveSheetsIdentifier as s, resolveSheetsRowIdentity as t, sheetsIdentifierCacheKey as u, sheetsIdentifierToRowKey as v, sheetsIdentifierToWhere as w, sheetsRowKey as x };