@constructive-io/sheets 0.14.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 (60) hide show
  1. package/README.md +231 -157
  2. package/dist/advanced.cjs +7192 -3840
  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-BYAYBXVB.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-MOFFS5WQ.js +128 -0
  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-YJZFHL2D.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-C2-ocDS7.d.cts → grid-cell-types-YNIVK4hN.d.cts} +71 -18
  25. package/dist/{grid-cell-types-C2-ocDS7.d.ts → grid-cell-types-YNIVK4hN.d.ts} +71 -18
  26. package/dist/index.cjs +22733 -12052
  27. package/dist/index.cjs.map +1 -1
  28. package/dist/index.d.cts +1432 -266
  29. package/dist/index.d.ts +1432 -266
  30. package/dist/index.js +12688 -6097
  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 +1170 -589
  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 +778 -147
  39. package/dist/testing.js.map +1 -1
  40. package/package.json +4 -5
  41. package/dist/chunk-4EZ6A23C.js +0 -44
  42. package/dist/chunk-4EZ6A23C.js.map +0 -1
  43. package/dist/chunk-6Y7CZ5VS.js +0 -168
  44. package/dist/chunk-6Y7CZ5VS.js.map +0 -1
  45. package/dist/chunk-BGL6EBTE.js +0 -446
  46. package/dist/chunk-BGL6EBTE.js.map +0 -1
  47. package/dist/chunk-ER3FIDK7.js +0 -4383
  48. package/dist/chunk-ER3FIDK7.js.map +0 -1
  49. package/dist/chunk-GZM2CSTR.js +0 -279
  50. package/dist/chunk-GZM2CSTR.js.map +0 -1
  51. package/dist/chunk-X7DHTSOX.js +0 -21
  52. package/dist/chunk-X7DHTSOX.js.map +0 -1
  53. package/dist/chunk-YJZFHL2D.js.map +0 -1
  54. package/dist/date-editor-G26WKILO.js +0 -358
  55. package/dist/date-editor-G26WKILO.js.map +0 -1
  56. package/dist/map-picker-ZUGGOIZS.js +0 -290
  57. package/dist/map-picker-ZUGGOIZS.js.map +0 -1
  58. package/dist/sheets-context-CHUVJCff.d.ts +0 -245
  59. package/dist/sheets-context-C_MkTxXm.d.cts +0 -245
  60. /package/dist/{chunk-BYAYBXVB.js.map → chunk-J7KK4UWI.js.map} +0 -0
@@ -1,5 +1,5 @@
1
+ import { RelationModel, TableModel, RowIdentityValue, TableWriteCapability, MetaTable, RowKey, ColumnModel } from '@constructive-io/data';
1
2
  import { ComponentType } from 'react';
2
- import { MetaQuery, RowIdentityValue, TableWriteCapability, MetaTable } from '@constructive-io/data';
3
3
 
4
4
  interface FieldMetadata$1 {
5
5
  name: string;
@@ -18,10 +18,23 @@ interface CellTypeResolution {
18
18
  activationBehavior: 'single-click' | 'double-click';
19
19
  isReadonly: boolean;
20
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
+ */
21
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
+ */
22
35
  declare function isImageField(fieldMeta?: FieldMetadata$1, fieldName?: string): boolean;
23
36
 
24
- type CellType = 'text' | 'textarea' | 'email' | 'url' | 'phone' | 'citext' | 'bpchar' | 'number' | 'integer' | 'smallint' | 'decimal' | 'currency' | 'percentage' | 'date' | 'datetime' | 'time' | 'timestamptz' | 'interval' | 'boolean' | 'toggle' | 'bit' | 'json' | 'jsonb' | 'array' | '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' | 'relation' | 'unknown';
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';
25
38
  type CellCategory = 'text' | 'numeric' | 'date' | 'boolean' | 'structured' | 'geometric' | 'network' | 'media' | 'special' | 'other';
26
39
  type CellValue = string | number | boolean | Date | null | undefined | Array<any> | Record<string, any>;
27
40
  interface FieldMetadata {
@@ -153,6 +166,8 @@ interface SheetsCellStyleHint {
153
166
  faded?: boolean;
154
167
  /** This draft cell has a field-level validation error (draftMeta.errors[colKey]). */
155
168
  error?: boolean;
169
+ /** The server could not send this value: the cell shows a muted notice instead. */
170
+ unreadable?: boolean;
156
171
  [extra: string]: unknown;
157
172
  }
158
173
  /**
@@ -175,35 +190,49 @@ interface SheetsCell {
175
190
  };
176
191
  }
177
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
+
178
202
  /** Result of submitting a draft row */
179
203
  interface DraftSubmitResult {
180
204
  /** The created row with its metadata-defined primary-key fields. */
181
205
  createdRow: Record<string, unknown> | null;
206
+ /** Required fields the draft still lacks, when Save was refused before sending. */
207
+ missing?: readonly DraftFieldGap[];
182
208
  }
183
209
 
184
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
+ */
185
216
  interface RelationInfo {
186
217
  kind: RelationKind;
218
+ /** GraphQL type name of the related table. */
187
219
  relatedTable?: string;
220
+ /** Fields that label a related record (the related table's display rule). */
188
221
  displayCandidates: string[];
222
+ /** The relation field on the row. */
189
223
  relationField?: string;
224
+ /** belongsTo only: the local key field this entry stands for (on the relation entry, the first one). */
190
225
  foreignKeyField?: string;
191
- junctionTable?: string;
192
- junctionLeftKeyField?: string;
193
- junctionRightKeyField?: string;
194
- displayName?: string;
226
+ /** The relation model behind this entry. */
227
+ relation?: RelationModel;
195
228
  }
196
- interface RelationInfoSlice {
197
- relationInfoCache: Record<string, Record<string, RelationInfo>>;
198
- relationInfoMapCache: Record<string, Map<string, RelationInfo>>;
199
- setRelationInfoForTable: (tableName: string, info: Record<string, RelationInfo>) => void;
200
- getRelationInfoForTable: (tableName: string) => Record<string, RelationInfo> | undefined;
201
- getRelationInfoMapForTable: (tableName: string) => Map<string, RelationInfo> | undefined;
202
- rebuildRelationInfo: (tableName: string, meta: MetaQuery | undefined) => void;
203
- ensureRelationInfo: (tableName: string, meta: MetaQuery | undefined) => Record<string, RelationInfo>;
204
- clearRelationInfoCache: () => void;
205
- }
206
- declare function buildRelationInfoFromMeta(tableName: string, meta: MetaQuery | undefined): Record<string, RelationInfo> | null;
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>;
207
236
 
208
237
  /** A row locator accepted by Sheets CRUD operations. */
209
238
  type SheetsRowIdentifier = string | number | Readonly<Record<string, RowIdentityValue>>;
@@ -231,6 +260,12 @@ declare function resolveSheetsIdentifier(table: MetaTable, identifier: SheetsRow
231
260
  declare function sheetsIdentifierToWhere(table: MetaTable, identifier: SheetsRowIdentifier): Record<string, {
232
261
  equalTo: RowIdentityValue;
233
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;
234
269
  /** Use scalar IDs as cache keys for compatibility; use serialized identities otherwise. */
235
270
  declare function sheetsIdentifierCacheKey(table: MetaTable, identifier: SheetsRowIdentifier): string | number | null;
236
271
  /** Stable TanStack/selection/editor key with an index fallback only for non-writable rows. */
@@ -244,10 +279,20 @@ interface EditorProps {
244
279
  colKey: string;
245
280
  rowId: string;
246
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;
247
284
  rowIndex: number;
248
285
  tableName?: string;
249
286
  fieldMeta?: FieldMetadata$1;
250
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;
251
296
  /**
252
297
  * Type-to-edit seed: when the overlay was opened by typing a printable char on the
253
298
  * active cell, this carries that char. Value editors (text/number) initialize their
@@ -284,10 +329,18 @@ interface CellCreationMetadata {
284
329
  fieldName: string;
285
330
  fieldMeta?: FieldMetadata$1;
286
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;
287
340
  relationOptions?: RelationCellOptions;
288
341
  canEdit: boolean;
289
342
  isReadonly: boolean;
290
343
  activationBehavior: 'single-click' | 'double-click';
291
344
  }
292
345
 
293
- 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 RelationInfoSlice as d, type SheetsRowIdentifier as e, type CellRegistryEntry as f, type CellRenderer as g, type CellPlugin as h, type ColumnSchema as i, type CellValue as j, type FieldMetadata as k, type RelationKind as l, type RowData as m, type SheetsRowIdentityResolution as n, buildRelationInfoFromMeta as o, canRunSheetsMutation as p, getSheetsWriteCapability as q, isImageField as r, resolveCellType as s, resolveSheetsIdentifier as t, resolveSheetsRowIdentity as u, sheetsIdentifierCacheKey as v, sheetsIdentifierToWhere as w, sheetsRowKey as x };
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 };