@constructive-io/sheets 0.4.1 → 0.6.1

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 (50) hide show
  1. package/README.md +19 -24
  2. package/dist/advanced.cjs +250 -405
  3. package/dist/advanced.cjs.map +1 -1
  4. package/dist/advanced.d.cts +9 -10
  5. package/dist/advanced.d.ts +9 -10
  6. package/dist/advanced.js +3 -3
  7. package/dist/auth.cjs +10 -10
  8. package/dist/auth.cjs.map +1 -1
  9. package/dist/auth.d.cts +5 -4
  10. package/dist/auth.d.ts +5 -4
  11. package/dist/auth.js +3 -3
  12. package/dist/{chunk-GLVZSPV2.js → chunk-4EZ6A23C.js} +4 -3
  13. package/dist/chunk-4EZ6A23C.js.map +1 -0
  14. package/dist/{chunk-3BNOZQIJ.js → chunk-KKAWMVEG.js} +11 -11
  15. package/dist/chunk-KKAWMVEG.js.map +1 -0
  16. package/dist/{chunk-FG2LRZP5.js → chunk-KOZAW264.js} +4 -3
  17. package/dist/chunk-KOZAW264.js.map +1 -0
  18. package/dist/{chunk-BWJVRYJT.js → chunk-KVPVEXWB.js} +40 -17
  19. package/dist/chunk-KVPVEXWB.js.map +1 -0
  20. package/dist/{chunk-BWKB52JB.js → chunk-LR64FLWO.js} +231 -379
  21. package/dist/chunk-LR64FLWO.js.map +1 -0
  22. package/dist/{chunk-SDKHWE7G.js → chunk-ZETPUEXH.js} +27 -2
  23. package/dist/chunk-ZETPUEXH.js.map +1 -0
  24. package/dist/{date-editor-CXKKGNL6.js → date-editor-QT47WY5T.js} +5 -3
  25. package/dist/date-editor-QT47WY5T.js.map +1 -0
  26. package/dist/{editor-props-M6Dh0P9f.d.ts → grid-cell-types-C3ARj148.d.cts} +70 -62
  27. package/dist/{editor-props-M6Dh0P9f.d.cts → grid-cell-types-C3ARj148.d.ts} +70 -62
  28. package/dist/index.cjs +564 -493
  29. package/dist/index.cjs.map +1 -1
  30. package/dist/index.d.cts +86 -35
  31. package/dist/index.d.ts +86 -35
  32. package/dist/index.js +264 -72
  33. package/dist/index.js.map +1 -1
  34. package/dist/{sheets-context-9u9r7Bs0.d.ts → sheets-context-B03WDhZ9.d.cts} +13 -6
  35. package/dist/{sheets-context-BjGIHocT.d.cts → sheets-context-DmVCOgiX.d.ts} +13 -6
  36. package/dist/styles.css +6 -0
  37. package/dist/testing.cjs +99 -33
  38. package/dist/testing.cjs.map +1 -1
  39. package/dist/testing.d.cts +11 -7
  40. package/dist/testing.d.ts +11 -7
  41. package/dist/testing.js +34 -8
  42. package/dist/testing.js.map +1 -1
  43. package/package.json +15 -16
  44. package/dist/chunk-3BNOZQIJ.js.map +0 -1
  45. package/dist/chunk-BWJVRYJT.js.map +0 -1
  46. package/dist/chunk-BWKB52JB.js.map +0 -1
  47. package/dist/chunk-FG2LRZP5.js.map +0 -1
  48. package/dist/chunk-GLVZSPV2.js.map +0 -1
  49. package/dist/chunk-SDKHWE7G.js.map +0 -1
  50. package/dist/date-editor-CXKKGNL6.js.map +0 -1
package/dist/index.d.cts CHANGED
@@ -1,14 +1,14 @@
1
- import * as react_jsx_runtime from 'react/jsx-runtime';
2
- import { b as SheetsConfig, S as SheetsExecuteFn, C as CellProps, c as CellTypeDefinition, d as CellTypeMatchInput, e as SheetsCellRenderContext, f as SheetsScopeKey, a as SheetsUploadFn, g as SheetsBackendAdapter } from './sheets-context-BjGIHocT.cjs';
3
- export { n as AdapterListQuery, o as AdapterListResult, p as AdapterPageInfo, A as AdapterTableContext, s as CellColumnDescriptor, r as CellTypePlugin, j as SheetsAuthEmbedded, k as SheetsAuthStandalone, h as SheetsContext, i as SheetsContextValue, t as SheetsLogger, l as createSheetsExecute, m as createSheetsUpload, q as defineCellType, u as useSheetsContext } from './sheets-context-BjGIHocT.cjs';
1
+ import * as react from 'react';
2
+ import react__default, { Component, ReactNode, ErrorInfo } from 'react';
3
+ import { b as SheetsConfig, S as SheetsExecuteFn, C as CellProps, c as CellTypeDefinition, d as SheetsCellRenderContext, e as CellTypeMatchInput, f as SheetsScopeKey, a as SheetsUploadFn, g as SheetsBackendAdapter } from './sheets-context-B03WDhZ9.cjs';
4
+ export { A as AdapterListQuery, h as AdapterListResult, i as AdapterPageInfo, j as AdapterTableContext, k as CellColumnDescriptor, l as CellTypePlugin, m as SheetsAuthEmbedded, n as SheetsAuthStandalone, o as SheetsContext, p as SheetsContextValue, q as SheetsLogger, r as createSheetsExecute, s as createSheetsUpload, t as defineCellType, u as useSheetsContext } from './sheets-context-B03WDhZ9.cjs';
4
5
  import { StoreApi } from 'zustand';
5
- import { R as RelationInfo, d as RelationInfoSlice, E as EditorProps, F as FieldMetadata, S as SheetsCell, e as CellRegistryEntry, b as CellType, f as CellRenderer, g as CellPlugin, h as ColumnSchema } from './editor-props-M6Dh0P9f.cjs';
6
- export { B as BaseCellProps, c as CellCategory, l as CellValue, m as FieldMetadata, i as RelationKind, n as RowData, a as SheetsCellKind, T as TableSchema, j as buildRelationInfoFromMeta, k as isImageField, r as resolveCellType } from './editor-props-M6Dh0P9f.cjs';
7
- import React__default, { Component, ReactNode, ErrorInfo } from 'react';
6
+ import { R as RelationInfo, d as RelationInfoSlice, E as EditorProps, F as FieldMetadata, S as SheetsCell, e as CellRegistryEntry, b as CellType, f as CellRenderer, g as CellPlugin, h as ColumnSchema } from './grid-cell-types-C3ARj148.cjs';
7
+ export { B as BaseCellProps, c as CellCategory, i as CellValue, j as FieldMetadata, k as RelationKind, l as RowData, a as SheetsCellKind, T as TableSchema, m as buildRelationInfoFromMeta, n as isImageField, r as resolveCellType } from './grid-cell-types-C3ARj148.cjs';
8
+ import { RowIdentityValue, TableWriteCapability, MetaTable as MetaTable$1, FieldSelection, MutationOptions, PageInfo, MetaQuery, QueryOptions, Filter } from '@constructive-io/data';
9
+ export { DataError } from '@constructive-io/data';
8
10
  import * as _tanstack_react_query from '@tanstack/react-query';
9
11
  import { UseQueryResult } from '@tanstack/react-query';
10
- import { FieldSelection, MutationOptions, PageInfo, MetaQuery, QueryOptions, Filter } from '@constructive-io/data';
11
- export { DataError } from '@constructive-io/data';
12
12
  import { z } from 'zod';
13
13
  export { SheetsAuthGate, SheetsAuthGateProps, useSheetsForgotPassword, useSheetsLogin, useSheetsRegister, useSheetsResetPassword } from './auth.cjs';
14
14
  import 'graphql';
@@ -17,7 +17,7 @@ interface SheetsProviderProps {
17
17
  config: SheetsConfig;
18
18
  children: React.ReactNode;
19
19
  }
20
- declare function SheetsProvider({ config, children }: SheetsProviderProps): react_jsx_runtime.JSX.Element;
20
+ declare function SheetsProvider({ config, children }: SheetsProviderProps): react.JSX.Element;
21
21
 
22
22
  /**
23
23
  * Presigned-URL upload helpers for the sheets cell-upload seam.
@@ -121,7 +121,8 @@ interface SheetsAuthState {
121
121
  isAuthenticated: boolean;
122
122
  accessToken: string | null;
123
123
  expiresAt: string | null;
124
- setAuthenticated: (token: string, expiresAt: string) => void;
124
+ identityKey: string | null;
125
+ setAuthenticated: (token: string, expiresAt: string, identityKey?: string | null) => void;
125
126
  setUnauthenticated: () => void;
126
127
  }
127
128
  type SheetsStoreState = DraftRowsSlice & RelationInfoSlice & SheetsAuthState;
@@ -321,6 +322,39 @@ declare function extendRangeToCell(sel: SheetsSelection, col: number, row: numbe
321
322
  */
322
323
  declare function moveActive(sel: SheetsSelection, dCol: number, dRow: number, colCount: number, rowCount: number): SheetsSelection;
323
324
 
325
+ /** A row locator accepted by Sheets CRUD operations. */
326
+ type SheetsRowIdentifier = string | number | Readonly<Record<string, RowIdentityValue>>;
327
+ type SheetsMutationOperation = 'create' | 'update' | 'delete';
328
+ type SheetsRowIdentityResolution = Readonly<{
329
+ status: 'identified';
330
+ /** Backwards-compatible scalar for an ordinary `id` PK; otherwise the PK object. */
331
+ identifier: SheetsRowIdentifier;
332
+ /** GraphQL primary-key input, including renamed and composite keys. */
333
+ primaryKey: Readonly<Record<string, RowIdentityValue>>;
334
+ /** Stable, schema-qualified key used by caches, selection, and editors. */
335
+ key: string;
336
+ }> | Readonly<{
337
+ status: 'unavailable';
338
+ reason: 'no-primary-key' | 'invalid-row';
339
+ }>;
340
+ /**
341
+ * Resolve one server row from `_meta`. The familiar scalar `id` contract is kept
342
+ * for existing adapters, while renamed and composite keys use the full PK input.
343
+ */
344
+ declare function resolveSheetsRowIdentity(table: MetaTable$1, row: Readonly<Record<string, unknown>>): SheetsRowIdentityResolution;
345
+ /** Resolve a public CRUD identifier through the same `_meta` identity contract. */
346
+ declare function resolveSheetsIdentifier(table: MetaTable$1, identifier: SheetsRowIdentifier): SheetsRowIdentityResolution;
347
+ /** Build the PostGraphile connection filter used by `findOne`. */
348
+ declare function sheetsIdentifierToWhere(table: MetaTable$1, identifier: SheetsRowIdentifier): Record<string, {
349
+ equalTo: RowIdentityValue;
350
+ }> | null;
351
+ /** Use scalar IDs as cache keys for compatibility; use serialized identities otherwise. */
352
+ declare function sheetsIdentifierCacheKey(table: MetaTable$1, identifier: SheetsRowIdentifier): string | number | null;
353
+ /** Stable TanStack/selection/editor key with an index fallback only for non-writable rows. */
354
+ declare function sheetsRowKey(table: MetaTable$1, row: Readonly<Record<string, unknown>>, index: number): string;
355
+ declare function getSheetsWriteCapability(table: MetaTable$1 | null): TableWriteCapability | null;
356
+ declare function canRunSheetsMutation(capability: TableWriteCapability | null, operation: SheetsMutationOperation): boolean;
357
+
324
358
  /** A single cell write request. */
325
359
  interface CellWrite {
326
360
  rowIndex: number;
@@ -610,7 +644,7 @@ interface DataGridProps<TRow extends SheetsRow = SheetsRow> {
610
644
  showSelection?: boolean;
611
645
  showPagination?: boolean;
612
646
  onRowSelect?: (selectedRows: TRow[]) => void;
613
- onCellEdit?: (id: string | number, field: string, value: unknown) => void;
647
+ onCellEdit?: (id: SheetsRowIdentifier, field: string, value: unknown) => void;
614
648
  relationChipLimit?: number;
615
649
  relationLabelMaxLength?: number;
616
650
  /**
@@ -670,8 +704,8 @@ interface DataGridProps<TRow extends SheetsRow = SheetsRow> {
670
704
  }
671
705
 
672
706
  declare const Sheets: <TRow extends SheetsRow = SheetsRow>(props: DataGridProps<TRow> & {
673
- ref?: React__default.Ref<SheetsHandle>;
674
- }) => React__default.ReactElement;
707
+ ref?: react__default.Ref<SheetsHandle>;
708
+ }) => react__default.ReactElement;
675
709
  type SheetsProps<TRow extends SheetsRow = SheetsRow> = DataGridProps<TRow>;
676
710
 
677
711
  type RelationMetadataSource = 'relation' | 'foreignKey';
@@ -764,11 +798,8 @@ declare function createCellTypeRegistry(cellTypes: CellTypeDefinition<any>[], bu
764
798
 
765
799
  /** Result of submitting a draft row */
766
800
  interface DraftSubmitResult {
767
- /** The created row with real database ID */
768
- createdRow: {
769
- id: string | number;
770
- [key: string]: unknown;
771
- } | null;
801
+ /** The created row with its metadata-defined primary-key fields. */
802
+ createdRow: Record<string, unknown> | null;
772
803
  }
773
804
 
774
805
  /** Resolved DOM cell payload: the neutral cell plus its (optional) view component. */
@@ -827,8 +858,10 @@ interface SheetsControlsProps {
827
858
  deleteSelected: () => void;
828
859
  onAddRow?: () => void;
829
860
  onExport?: () => void;
861
+ canDelete?: boolean;
862
+ readOnlyReason?: string | null;
830
863
  }
831
- declare function SheetsControls(props: SheetsControlsProps): react_jsx_runtime.JSX.Element;
864
+ declare function SheetsControls(props: SheetsControlsProps): react.JSX.Element;
832
865
 
833
866
  interface GridState {
834
867
  sorting: {
@@ -1027,6 +1060,13 @@ interface SheetsShellBindings {
1027
1060
  resizeColumn: ReturnType<typeof useGridState>['actions']['resizeColumn'];
1028
1061
  frozenCount: number;
1029
1062
  selectedRowCount: number;
1063
+ canCreate: boolean;
1064
+ canUpdate: boolean;
1065
+ canDelete: boolean;
1066
+ /** Human-readable reason shown when `_meta` proves the whole table is read-only. */
1067
+ readOnlyReason: string | null;
1068
+ /** Stable identity for selection, TanStack rows, and editor instances. */
1069
+ getRowId: (row: SheetsRow | null | undefined, index: number) => string;
1030
1070
  isSubmittingDrafts: boolean;
1031
1071
  submitDraftButtonDisabled: boolean;
1032
1072
  submitDraftLabel: string;
@@ -1080,7 +1120,7 @@ interface SheetsPaginationProps {
1080
1120
  totalPages: number;
1081
1121
  setPageIndex: React.Dispatch<React.SetStateAction<number>>;
1082
1122
  }
1083
- declare function SheetsPagination(props: SheetsPaginationProps): react_jsx_runtime.JSX.Element;
1123
+ declare function SheetsPagination(props: SheetsPaginationProps): react.JSX.Element;
1084
1124
 
1085
1125
  type TableWithCategory = {
1086
1126
  name: string;
@@ -1096,7 +1136,7 @@ interface TableSelectorProps {
1096
1136
  /** Optional callback when user clicks the "New table" button */
1097
1137
  onNewTable?: () => void;
1098
1138
  }
1099
- declare const SheetsTableSelector: React__default.NamedExoticComponent<TableSelectorProps>;
1139
+ declare const SheetsTableSelector: react__default.NamedExoticComponent<TableSelectorProps>;
1100
1140
 
1101
1141
  interface UseMetaOptions {
1102
1142
  enabled?: boolean;
@@ -1104,7 +1144,7 @@ interface UseMetaOptions {
1104
1144
  declare function useSheetsMeta(options?: UseMetaOptions): UseQueryResult<MetaQuery, Error>;
1105
1145
 
1106
1146
  type RowRecord$1 = Record<string, unknown>;
1107
- type DeleteIdentifier = string | number | Record<string, string | number>;
1147
+ type DeleteIdentifier = SheetsRowIdentifier;
1108
1148
  /**
1109
1149
  * Unified table hook options
1110
1150
  */
@@ -1124,11 +1164,11 @@ interface UseTableResult<TData extends RowRecord$1 = RowRecord$1> {
1124
1164
  totalCount: number;
1125
1165
  isLoading: boolean;
1126
1166
  error: Error | null;
1127
- findOne: (id: string | number) => Promise<TData | null>;
1167
+ findOne: (id: SheetsRowIdentifier) => Promise<TData | null>;
1128
1168
  create: (data: RowRecord$1) => Promise<{
1129
1169
  createdRow: TData | null;
1130
1170
  }>;
1131
- update: (id: string | number, patch: RowRecord$1) => Promise<{
1171
+ update: (id: SheetsRowIdentifier, patch: RowRecord$1) => Promise<{
1132
1172
  updatedRow: TData | null;
1133
1173
  }>;
1134
1174
  delete: (id: DeleteIdentifier) => Promise<{
@@ -1276,8 +1316,9 @@ declare const sheetsQueryKeys: {
1276
1316
  };
1277
1317
 
1278
1318
  /**
1279
- * Create the default PostGraphile-backed adapter. Stateless — safe to share as a
1280
- * module-level singleton.
1319
+ * Create the default PostGraphile-backed adapter. The metadata preflight makes
1320
+ * an outdated endpoint distinguishable from an ordinary transport failure,
1321
+ * while the WeakMap deduplicates that introspection for each executor/session.
1281
1322
  */
1282
1323
  declare function createPostGraphileAdapter(): SheetsBackendAdapter;
1283
1324
 
@@ -1361,6 +1402,10 @@ declare function mapToFrontendCellType(metadata: {
1361
1402
  pgAlias?: string | null;
1362
1403
  pgType?: string | null;
1363
1404
  subtype?: string | null;
1405
+ encoding?: {
1406
+ kind: string;
1407
+ geometrySubtype?: string | null;
1408
+ } | null;
1364
1409
  }): CellType;
1365
1410
  /**
1366
1411
  * Determines if a field represents structured data that should be rendered as JSON
@@ -1379,6 +1424,10 @@ declare function createColumnSchemaFromMeta(field: {
1379
1424
  pgType?: string | null;
1380
1425
  subtype?: string | null;
1381
1426
  typmod?: any;
1427
+ encoding?: {
1428
+ kind: string;
1429
+ geometrySubtype?: string | null;
1430
+ } | null;
1382
1431
  };
1383
1432
  }): ColumnSchema;
1384
1433
 
@@ -1475,6 +1524,7 @@ interface ScalarFieldSpec {
1475
1524
  pgAlias?: string | null;
1476
1525
  subtype?: string | null;
1477
1526
  typmod?: number | null;
1527
+ encoding?: MetaField['type']['encoding'];
1478
1528
  };
1479
1529
  constraints: ScalarConstraintHints;
1480
1530
  }
@@ -1501,7 +1551,7 @@ interface DynamicMutationResult<TData = unknown> {
1501
1551
  error: Error | null;
1502
1552
  }
1503
1553
  declare function useDynamicCreate(tableName: string): DynamicMutationResult;
1504
- declare function useDynamicUpdate(tableName: string, rowId: string | number): DynamicMutationResult;
1554
+ declare function useDynamicUpdate(tableName: string, rowId: SheetsRowIdentifier): DynamicMutationResult;
1505
1555
 
1506
1556
  declare function createMetadataHash(value: unknown): string;
1507
1557
 
@@ -1542,7 +1592,7 @@ interface FeedbackContextValue {
1542
1592
  interface FeedbackProviderProps {
1543
1593
  children: React.ReactNode;
1544
1594
  }
1545
- declare function FeedbackProvider({ children }: FeedbackProviderProps): react_jsx_runtime.JSX.Element;
1595
+ declare function FeedbackProvider({ children }: FeedbackProviderProps): react.JSX.Element;
1546
1596
  declare function useFeedback(): FeedbackContextValue;
1547
1597
  /**
1548
1598
  * Hook for accessing only operation feedback - useful for dock status bar
@@ -1563,14 +1613,14 @@ interface DockStatusBarProps {
1563
1613
  * - Success checkmark + message (auto-dismisses)
1564
1614
  * - Error/partial warning + message with optional retry
1565
1615
  */
1566
- declare function DockStatusBar({ className, onRetry }: DockStatusBarProps): react_jsx_runtime.JSX.Element | null;
1616
+ declare function DockStatusBar({ className, onRetry }: DockStatusBarProps): react.JSX.Element | null;
1567
1617
  /**
1568
1618
  * Compact variant for space-constrained layouts.
1569
1619
  * Shows only icon + abbreviated message.
1570
1620
  */
1571
1621
  declare function DockStatusBarCompact({ className }: {
1572
1622
  className?: string;
1573
- }): react_jsx_runtime.JSX.Element | null;
1623
+ }): react.JSX.Element | null;
1574
1624
 
1575
1625
  interface FloatingStatusProps {
1576
1626
  className?: string;
@@ -1579,7 +1629,7 @@ interface FloatingStatusProps {
1579
1629
  * Standalone floating status indicator for bulk operations.
1580
1630
  * Shows independently of row selection, positioned at bottom-center of grid.
1581
1631
  */
1582
- declare function FloatingStatus({ className }: FloatingStatusProps): react_jsx_runtime.JSX.Element;
1632
+ declare function FloatingStatus({ className }: FloatingStatusProps): react.JSX.Element;
1583
1633
 
1584
1634
  interface SheetsErrorBoundaryProps {
1585
1635
  children: ReactNode;
@@ -1612,19 +1662,20 @@ interface SheetsErrorStateProps {
1612
1662
  onRetry?: () => void;
1613
1663
  }
1614
1664
  /** Shown when the table data (or its metadata) fails to load. */
1615
- declare function SheetsErrorState({ error, onRetry }: SheetsErrorStateProps): react_jsx_runtime.JSX.Element;
1665
+ declare function SheetsErrorState({ error, onRetry }: SheetsErrorStateProps): react.JSX.Element;
1616
1666
  interface SheetsEmptyStateProps {
1617
1667
  tableName?: string;
1618
1668
  onAddRow?: () => void;
1669
+ readOnlyReason?: string | null;
1619
1670
  }
1620
1671
  /** Shown when the table loaded successfully but has no rows. */
1621
- declare function SheetsEmptyState({ tableName, onAddRow }: SheetsEmptyStateProps): react_jsx_runtime.JSX.Element;
1672
+ declare function SheetsEmptyState({ tableName, onAddRow, readOnlyReason }: SheetsEmptyStateProps): react.JSX.Element;
1622
1673
  /**
1623
1674
  * Shown during the initial data load. A STRUCTURAL skeleton of the grid (baseline-ui:
1624
1675
  * prefer skeletons over spinners) — mirrors the real grid's 40px header + 44px rows +
1625
1676
  * horizontal hairlines so the load→loaded swap doesn't jump. Pulse is motion-safe only.
1626
1677
  */
1627
- declare function SheetsLoadingState(): react_jsx_runtime.JSX.Element;
1678
+ declare function SheetsLoadingState(): react.JSX.Element;
1628
1679
 
1629
1680
  interface DataFilteringContextValue {
1630
1681
  filterTree: FilterGroup;
@@ -1684,4 +1735,4 @@ declare function useDataPagination({ initialPageSize, initialPageIndex, totalCou
1684
1735
  }) => any;
1685
1736
  };
1686
1737
 
1687
- export { BOOLEAN_TYPES, BUILTIN_EDITOR_TYPES, type Binding, CellPlugin, CellProps, CellRegistry, CellRegistryEntry, CellRenderer, type CellSlot, type CellSlots, CellType, type CellTypeBuiltins, CellTypeDefinition, CellTypeMatchInput, type CellTypeRegistry, ColumnSchema, type CommandResult, DATE_TIME_TYPES, type DataFilteringContextValue, type DataPaginationContextValue, type DispatchEvent, DockStatusBar, DockStatusBarCompact, type DraftMeta, type DraftRow, type DynamicFormSpec, ENHANCED_TYPES, EditorProps, type ExtractedRange, FeedbackProvider, type FieldTypeMap, type FilterCondition, type FilterGroup, type FilterNode, type FilterValue, FloatingStatus, GEOMETRY_TYPES, type GridCommand, type GridCommandContext, type Interceptor, MAX_FILTER_DEPTH, MEDIA_TYPES, type MetaField, type MetaTable, NON_EDITABLE_TYPES, NUMBER_TYPES, type OperationFeedback, RangeSet, type RelationColumnInfo, RelationInfo, type RowWithDraft, STRUCTURED_DATA_TYPES, type ScalarFieldSpec, type SelectionCurrent, type SelectionRect, Sheets, type SheetsAuthState, SheetsBackendAdapter, SheetsCell, SheetsCellRenderContext, SheetsConfig, SheetsControls, type SheetsControlsProps, type SheetsDraftBindings, SheetsEmptyState, SheetsErrorBoundary, SheetsErrorState, type SheetsEvent, SheetsExecuteFn, type SheetsHandle, SheetsLoadingState, SheetsPagination, type SheetsPaginationBindings, type SheetsPaginationProps, type SheetsProps, SheetsProvider, type SheetsRow, SheetsScopeKey, type SheetsSelection, type SheetsSelectionBindings, type SheetsSlots, type SheetsStoreState, SheetsTableSelector, type SheetsThemeInput, type SheetsThemeTokens, SheetsUploadFn, TYPED_ARRAY_TYPES, type TableSelectorProps, type TableWithCategory, type Trigger, type UploadProgress, type UploadResponse, type UseDataFilteringConfig, type UseDataPaginationConfig, type UseFieldUploadOptions, type UseInfiniteTableOptions, type UseInfiniteTableResult, type UseMetaOptions, type UseSheetsResult, type UseSheetsTableCursorOptions, type UseSheetsTableCursorResult, type UseTableOptions, type UseTableResult, VIEWER_ONLY_TYPES, buildScalarFormSpec, buildZodSchema, clear as clearSheetsSelection, computeDraftMetaSignature, countConditions, createCellTypeRegistry, createColumnSchemaFromMeta, createEmptyGroup, createMetadataHash, createPostGraphileAdapter, emptySheetsSelection, executeFieldUpload, extendRangeToCell, fillDownWrites, fillRightWrites, findTableFormSpec, getCellsInRange, getDraftMeta, isArrayCellType, isDraftRow, isSheetsScopeKey, isStructuredDataType, kbd, mapToFrontendCellType, moveActive, sheetsTableQueryKeys as queryKeys, resolveDownloadUrl, selectCell, selectRange, selectRow, sheetsQueryKeys, toTSV, toggleRow, tokensFromCssVars, useDataFiltering, useDataGridColumns, useDataPagination, useDynamicCreate, useDynamicUpdate, useFeedback, useOperationFeedback, useRelationColumns, useSheets, useSheetsAdapter, useSheetsFieldUpload, useSheetsImageUpload, useSheetsInfiniteTable, useSheetsMeta, useSheetsStore, useSheetsStoreApi, useSheetsTable, useSheetsTableCursor };
1738
+ export { BOOLEAN_TYPES, BUILTIN_EDITOR_TYPES, type Binding, CellPlugin, CellProps, CellRegistry, CellRegistryEntry, CellRenderer, type CellSlot, type CellSlots, CellType, type CellTypeBuiltins, CellTypeDefinition, CellTypeMatchInput, type CellTypeRegistry, ColumnSchema, type CommandResult, DATE_TIME_TYPES, type DataFilteringContextValue, type DataPaginationContextValue, type DispatchEvent, DockStatusBar, DockStatusBarCompact, type DraftMeta, type DraftRow, type DynamicFormSpec, ENHANCED_TYPES, EditorProps, type ExtractedRange, FeedbackProvider, type FieldTypeMap, type FilterCondition, type FilterGroup, type FilterNode, type FilterValue, FloatingStatus, GEOMETRY_TYPES, type GridCommand, type GridCommandContext, type Interceptor, MAX_FILTER_DEPTH, MEDIA_TYPES, type MetaField, type MetaTable, NON_EDITABLE_TYPES, NUMBER_TYPES, type OperationFeedback, RangeSet, type RelationColumnInfo, RelationInfo, type RowWithDraft, STRUCTURED_DATA_TYPES, type ScalarFieldSpec, type SelectionCurrent, type SelectionRect, Sheets, type SheetsAuthState, SheetsBackendAdapter, SheetsCell, SheetsCellRenderContext, SheetsConfig, SheetsControls, type SheetsControlsProps, type SheetsDraftBindings, SheetsEmptyState, SheetsErrorBoundary, SheetsErrorState, type SheetsEvent, SheetsExecuteFn, type SheetsHandle, SheetsLoadingState, SheetsPagination, type SheetsPaginationBindings, type SheetsPaginationProps, type SheetsProps, SheetsProvider, type SheetsRow, type SheetsRowIdentifier, type SheetsRowIdentityResolution, SheetsScopeKey, type SheetsSelection, type SheetsSelectionBindings, type SheetsSlots, type SheetsStoreState, SheetsTableSelector, type SheetsThemeInput, type SheetsThemeTokens, SheetsUploadFn, TYPED_ARRAY_TYPES, type TableSelectorProps, type TableWithCategory, type Trigger, type UploadProgress, type UploadResponse, type UseDataFilteringConfig, type UseDataPaginationConfig, type UseFieldUploadOptions, type UseInfiniteTableOptions, type UseInfiniteTableResult, type UseMetaOptions, type UseSheetsResult, type UseSheetsTableCursorOptions, type UseSheetsTableCursorResult, type UseTableOptions, type UseTableResult, VIEWER_ONLY_TYPES, buildScalarFormSpec, buildZodSchema, canRunSheetsMutation, clear as clearSheetsSelection, computeDraftMetaSignature, countConditions, createCellTypeRegistry, createColumnSchemaFromMeta, createEmptyGroup, createMetadataHash, createPostGraphileAdapter, emptySheetsSelection, executeFieldUpload, extendRangeToCell, fillDownWrites, fillRightWrites, findTableFormSpec, getCellsInRange, getDraftMeta, getSheetsWriteCapability, isArrayCellType, isDraftRow, isSheetsScopeKey, isStructuredDataType, kbd, mapToFrontendCellType, moveActive, sheetsTableQueryKeys as queryKeys, resolveDownloadUrl, resolveSheetsIdentifier, resolveSheetsRowIdentity, selectCell, selectRange, selectRow, sheetsIdentifierCacheKey, sheetsIdentifierToWhere, sheetsQueryKeys, sheetsRowKey, toTSV, toggleRow, tokensFromCssVars, useDataFiltering, useDataGridColumns, useDataPagination, useDynamicCreate, useDynamicUpdate, useFeedback, useOperationFeedback, useRelationColumns, useSheets, useSheetsAdapter, useSheetsFieldUpload, useSheetsImageUpload, useSheetsInfiniteTable, useSheetsMeta, useSheetsStore, useSheetsStoreApi, useSheetsTable, useSheetsTableCursor };
package/dist/index.d.ts CHANGED
@@ -1,14 +1,14 @@
1
- import * as react_jsx_runtime from 'react/jsx-runtime';
2
- import { b as SheetsConfig, S as SheetsExecuteFn, C as CellProps, c as CellTypeDefinition, d as CellTypeMatchInput, e as SheetsCellRenderContext, f as SheetsScopeKey, a as SheetsUploadFn, g as SheetsBackendAdapter } from './sheets-context-9u9r7Bs0.js';
3
- export { n as AdapterListQuery, o as AdapterListResult, p as AdapterPageInfo, A as AdapterTableContext, s as CellColumnDescriptor, r as CellTypePlugin, j as SheetsAuthEmbedded, k as SheetsAuthStandalone, h as SheetsContext, i as SheetsContextValue, t as SheetsLogger, l as createSheetsExecute, m as createSheetsUpload, q as defineCellType, u as useSheetsContext } from './sheets-context-9u9r7Bs0.js';
1
+ import * as react from 'react';
2
+ import react__default, { Component, ReactNode, ErrorInfo } from 'react';
3
+ import { b as SheetsConfig, S as SheetsExecuteFn, C as CellProps, c as CellTypeDefinition, d as SheetsCellRenderContext, e as CellTypeMatchInput, f as SheetsScopeKey, a as SheetsUploadFn, g as SheetsBackendAdapter } from './sheets-context-DmVCOgiX.js';
4
+ export { A as AdapterListQuery, h as AdapterListResult, i as AdapterPageInfo, j as AdapterTableContext, k as CellColumnDescriptor, l as CellTypePlugin, m as SheetsAuthEmbedded, n as SheetsAuthStandalone, o as SheetsContext, p as SheetsContextValue, q as SheetsLogger, r as createSheetsExecute, s as createSheetsUpload, t as defineCellType, u as useSheetsContext } from './sheets-context-DmVCOgiX.js';
4
5
  import { StoreApi } from 'zustand';
5
- import { R as RelationInfo, d as RelationInfoSlice, E as EditorProps, F as FieldMetadata, S as SheetsCell, e as CellRegistryEntry, b as CellType, f as CellRenderer, g as CellPlugin, h as ColumnSchema } from './editor-props-M6Dh0P9f.js';
6
- export { B as BaseCellProps, c as CellCategory, l as CellValue, m as FieldMetadata, i as RelationKind, n as RowData, a as SheetsCellKind, T as TableSchema, j as buildRelationInfoFromMeta, k as isImageField, r as resolveCellType } from './editor-props-M6Dh0P9f.js';
7
- import React__default, { Component, ReactNode, ErrorInfo } from 'react';
6
+ import { R as RelationInfo, d as RelationInfoSlice, E as EditorProps, F as FieldMetadata, S as SheetsCell, e as CellRegistryEntry, b as CellType, f as CellRenderer, g as CellPlugin, h as ColumnSchema } from './grid-cell-types-C3ARj148.js';
7
+ export { B as BaseCellProps, c as CellCategory, i as CellValue, j as FieldMetadata, k as RelationKind, l as RowData, a as SheetsCellKind, T as TableSchema, m as buildRelationInfoFromMeta, n as isImageField, r as resolveCellType } from './grid-cell-types-C3ARj148.js';
8
+ import { RowIdentityValue, TableWriteCapability, MetaTable as MetaTable$1, FieldSelection, MutationOptions, PageInfo, MetaQuery, QueryOptions, Filter } from '@constructive-io/data';
9
+ export { DataError } from '@constructive-io/data';
8
10
  import * as _tanstack_react_query from '@tanstack/react-query';
9
11
  import { UseQueryResult } from '@tanstack/react-query';
10
- import { FieldSelection, MutationOptions, PageInfo, MetaQuery, QueryOptions, Filter } from '@constructive-io/data';
11
- export { DataError } from '@constructive-io/data';
12
12
  import { z } from 'zod';
13
13
  export { SheetsAuthGate, SheetsAuthGateProps, useSheetsForgotPassword, useSheetsLogin, useSheetsRegister, useSheetsResetPassword } from './auth.js';
14
14
  import 'graphql';
@@ -17,7 +17,7 @@ interface SheetsProviderProps {
17
17
  config: SheetsConfig;
18
18
  children: React.ReactNode;
19
19
  }
20
- declare function SheetsProvider({ config, children }: SheetsProviderProps): react_jsx_runtime.JSX.Element;
20
+ declare function SheetsProvider({ config, children }: SheetsProviderProps): react.JSX.Element;
21
21
 
22
22
  /**
23
23
  * Presigned-URL upload helpers for the sheets cell-upload seam.
@@ -121,7 +121,8 @@ interface SheetsAuthState {
121
121
  isAuthenticated: boolean;
122
122
  accessToken: string | null;
123
123
  expiresAt: string | null;
124
- setAuthenticated: (token: string, expiresAt: string) => void;
124
+ identityKey: string | null;
125
+ setAuthenticated: (token: string, expiresAt: string, identityKey?: string | null) => void;
125
126
  setUnauthenticated: () => void;
126
127
  }
127
128
  type SheetsStoreState = DraftRowsSlice & RelationInfoSlice & SheetsAuthState;
@@ -321,6 +322,39 @@ declare function extendRangeToCell(sel: SheetsSelection, col: number, row: numbe
321
322
  */
322
323
  declare function moveActive(sel: SheetsSelection, dCol: number, dRow: number, colCount: number, rowCount: number): SheetsSelection;
323
324
 
325
+ /** A row locator accepted by Sheets CRUD operations. */
326
+ type SheetsRowIdentifier = string | number | Readonly<Record<string, RowIdentityValue>>;
327
+ type SheetsMutationOperation = 'create' | 'update' | 'delete';
328
+ type SheetsRowIdentityResolution = Readonly<{
329
+ status: 'identified';
330
+ /** Backwards-compatible scalar for an ordinary `id` PK; otherwise the PK object. */
331
+ identifier: SheetsRowIdentifier;
332
+ /** GraphQL primary-key input, including renamed and composite keys. */
333
+ primaryKey: Readonly<Record<string, RowIdentityValue>>;
334
+ /** Stable, schema-qualified key used by caches, selection, and editors. */
335
+ key: string;
336
+ }> | Readonly<{
337
+ status: 'unavailable';
338
+ reason: 'no-primary-key' | 'invalid-row';
339
+ }>;
340
+ /**
341
+ * Resolve one server row from `_meta`. The familiar scalar `id` contract is kept
342
+ * for existing adapters, while renamed and composite keys use the full PK input.
343
+ */
344
+ declare function resolveSheetsRowIdentity(table: MetaTable$1, row: Readonly<Record<string, unknown>>): SheetsRowIdentityResolution;
345
+ /** Resolve a public CRUD identifier through the same `_meta` identity contract. */
346
+ declare function resolveSheetsIdentifier(table: MetaTable$1, identifier: SheetsRowIdentifier): SheetsRowIdentityResolution;
347
+ /** Build the PostGraphile connection filter used by `findOne`. */
348
+ declare function sheetsIdentifierToWhere(table: MetaTable$1, identifier: SheetsRowIdentifier): Record<string, {
349
+ equalTo: RowIdentityValue;
350
+ }> | null;
351
+ /** Use scalar IDs as cache keys for compatibility; use serialized identities otherwise. */
352
+ declare function sheetsIdentifierCacheKey(table: MetaTable$1, identifier: SheetsRowIdentifier): string | number | null;
353
+ /** Stable TanStack/selection/editor key with an index fallback only for non-writable rows. */
354
+ declare function sheetsRowKey(table: MetaTable$1, row: Readonly<Record<string, unknown>>, index: number): string;
355
+ declare function getSheetsWriteCapability(table: MetaTable$1 | null): TableWriteCapability | null;
356
+ declare function canRunSheetsMutation(capability: TableWriteCapability | null, operation: SheetsMutationOperation): boolean;
357
+
324
358
  /** A single cell write request. */
325
359
  interface CellWrite {
326
360
  rowIndex: number;
@@ -610,7 +644,7 @@ interface DataGridProps<TRow extends SheetsRow = SheetsRow> {
610
644
  showSelection?: boolean;
611
645
  showPagination?: boolean;
612
646
  onRowSelect?: (selectedRows: TRow[]) => void;
613
- onCellEdit?: (id: string | number, field: string, value: unknown) => void;
647
+ onCellEdit?: (id: SheetsRowIdentifier, field: string, value: unknown) => void;
614
648
  relationChipLimit?: number;
615
649
  relationLabelMaxLength?: number;
616
650
  /**
@@ -670,8 +704,8 @@ interface DataGridProps<TRow extends SheetsRow = SheetsRow> {
670
704
  }
671
705
 
672
706
  declare const Sheets: <TRow extends SheetsRow = SheetsRow>(props: DataGridProps<TRow> & {
673
- ref?: React__default.Ref<SheetsHandle>;
674
- }) => React__default.ReactElement;
707
+ ref?: react__default.Ref<SheetsHandle>;
708
+ }) => react__default.ReactElement;
675
709
  type SheetsProps<TRow extends SheetsRow = SheetsRow> = DataGridProps<TRow>;
676
710
 
677
711
  type RelationMetadataSource = 'relation' | 'foreignKey';
@@ -764,11 +798,8 @@ declare function createCellTypeRegistry(cellTypes: CellTypeDefinition<any>[], bu
764
798
 
765
799
  /** Result of submitting a draft row */
766
800
  interface DraftSubmitResult {
767
- /** The created row with real database ID */
768
- createdRow: {
769
- id: string | number;
770
- [key: string]: unknown;
771
- } | null;
801
+ /** The created row with its metadata-defined primary-key fields. */
802
+ createdRow: Record<string, unknown> | null;
772
803
  }
773
804
 
774
805
  /** Resolved DOM cell payload: the neutral cell plus its (optional) view component. */
@@ -827,8 +858,10 @@ interface SheetsControlsProps {
827
858
  deleteSelected: () => void;
828
859
  onAddRow?: () => void;
829
860
  onExport?: () => void;
861
+ canDelete?: boolean;
862
+ readOnlyReason?: string | null;
830
863
  }
831
- declare function SheetsControls(props: SheetsControlsProps): react_jsx_runtime.JSX.Element;
864
+ declare function SheetsControls(props: SheetsControlsProps): react.JSX.Element;
832
865
 
833
866
  interface GridState {
834
867
  sorting: {
@@ -1027,6 +1060,13 @@ interface SheetsShellBindings {
1027
1060
  resizeColumn: ReturnType<typeof useGridState>['actions']['resizeColumn'];
1028
1061
  frozenCount: number;
1029
1062
  selectedRowCount: number;
1063
+ canCreate: boolean;
1064
+ canUpdate: boolean;
1065
+ canDelete: boolean;
1066
+ /** Human-readable reason shown when `_meta` proves the whole table is read-only. */
1067
+ readOnlyReason: string | null;
1068
+ /** Stable identity for selection, TanStack rows, and editor instances. */
1069
+ getRowId: (row: SheetsRow | null | undefined, index: number) => string;
1030
1070
  isSubmittingDrafts: boolean;
1031
1071
  submitDraftButtonDisabled: boolean;
1032
1072
  submitDraftLabel: string;
@@ -1080,7 +1120,7 @@ interface SheetsPaginationProps {
1080
1120
  totalPages: number;
1081
1121
  setPageIndex: React.Dispatch<React.SetStateAction<number>>;
1082
1122
  }
1083
- declare function SheetsPagination(props: SheetsPaginationProps): react_jsx_runtime.JSX.Element;
1123
+ declare function SheetsPagination(props: SheetsPaginationProps): react.JSX.Element;
1084
1124
 
1085
1125
  type TableWithCategory = {
1086
1126
  name: string;
@@ -1096,7 +1136,7 @@ interface TableSelectorProps {
1096
1136
  /** Optional callback when user clicks the "New table" button */
1097
1137
  onNewTable?: () => void;
1098
1138
  }
1099
- declare const SheetsTableSelector: React__default.NamedExoticComponent<TableSelectorProps>;
1139
+ declare const SheetsTableSelector: react__default.NamedExoticComponent<TableSelectorProps>;
1100
1140
 
1101
1141
  interface UseMetaOptions {
1102
1142
  enabled?: boolean;
@@ -1104,7 +1144,7 @@ interface UseMetaOptions {
1104
1144
  declare function useSheetsMeta(options?: UseMetaOptions): UseQueryResult<MetaQuery, Error>;
1105
1145
 
1106
1146
  type RowRecord$1 = Record<string, unknown>;
1107
- type DeleteIdentifier = string | number | Record<string, string | number>;
1147
+ type DeleteIdentifier = SheetsRowIdentifier;
1108
1148
  /**
1109
1149
  * Unified table hook options
1110
1150
  */
@@ -1124,11 +1164,11 @@ interface UseTableResult<TData extends RowRecord$1 = RowRecord$1> {
1124
1164
  totalCount: number;
1125
1165
  isLoading: boolean;
1126
1166
  error: Error | null;
1127
- findOne: (id: string | number) => Promise<TData | null>;
1167
+ findOne: (id: SheetsRowIdentifier) => Promise<TData | null>;
1128
1168
  create: (data: RowRecord$1) => Promise<{
1129
1169
  createdRow: TData | null;
1130
1170
  }>;
1131
- update: (id: string | number, patch: RowRecord$1) => Promise<{
1171
+ update: (id: SheetsRowIdentifier, patch: RowRecord$1) => Promise<{
1132
1172
  updatedRow: TData | null;
1133
1173
  }>;
1134
1174
  delete: (id: DeleteIdentifier) => Promise<{
@@ -1276,8 +1316,9 @@ declare const sheetsQueryKeys: {
1276
1316
  };
1277
1317
 
1278
1318
  /**
1279
- * Create the default PostGraphile-backed adapter. Stateless — safe to share as a
1280
- * module-level singleton.
1319
+ * Create the default PostGraphile-backed adapter. The metadata preflight makes
1320
+ * an outdated endpoint distinguishable from an ordinary transport failure,
1321
+ * while the WeakMap deduplicates that introspection for each executor/session.
1281
1322
  */
1282
1323
  declare function createPostGraphileAdapter(): SheetsBackendAdapter;
1283
1324
 
@@ -1361,6 +1402,10 @@ declare function mapToFrontendCellType(metadata: {
1361
1402
  pgAlias?: string | null;
1362
1403
  pgType?: string | null;
1363
1404
  subtype?: string | null;
1405
+ encoding?: {
1406
+ kind: string;
1407
+ geometrySubtype?: string | null;
1408
+ } | null;
1364
1409
  }): CellType;
1365
1410
  /**
1366
1411
  * Determines if a field represents structured data that should be rendered as JSON
@@ -1379,6 +1424,10 @@ declare function createColumnSchemaFromMeta(field: {
1379
1424
  pgType?: string | null;
1380
1425
  subtype?: string | null;
1381
1426
  typmod?: any;
1427
+ encoding?: {
1428
+ kind: string;
1429
+ geometrySubtype?: string | null;
1430
+ } | null;
1382
1431
  };
1383
1432
  }): ColumnSchema;
1384
1433
 
@@ -1475,6 +1524,7 @@ interface ScalarFieldSpec {
1475
1524
  pgAlias?: string | null;
1476
1525
  subtype?: string | null;
1477
1526
  typmod?: number | null;
1527
+ encoding?: MetaField['type']['encoding'];
1478
1528
  };
1479
1529
  constraints: ScalarConstraintHints;
1480
1530
  }
@@ -1501,7 +1551,7 @@ interface DynamicMutationResult<TData = unknown> {
1501
1551
  error: Error | null;
1502
1552
  }
1503
1553
  declare function useDynamicCreate(tableName: string): DynamicMutationResult;
1504
- declare function useDynamicUpdate(tableName: string, rowId: string | number): DynamicMutationResult;
1554
+ declare function useDynamicUpdate(tableName: string, rowId: SheetsRowIdentifier): DynamicMutationResult;
1505
1555
 
1506
1556
  declare function createMetadataHash(value: unknown): string;
1507
1557
 
@@ -1542,7 +1592,7 @@ interface FeedbackContextValue {
1542
1592
  interface FeedbackProviderProps {
1543
1593
  children: React.ReactNode;
1544
1594
  }
1545
- declare function FeedbackProvider({ children }: FeedbackProviderProps): react_jsx_runtime.JSX.Element;
1595
+ declare function FeedbackProvider({ children }: FeedbackProviderProps): react.JSX.Element;
1546
1596
  declare function useFeedback(): FeedbackContextValue;
1547
1597
  /**
1548
1598
  * Hook for accessing only operation feedback - useful for dock status bar
@@ -1563,14 +1613,14 @@ interface DockStatusBarProps {
1563
1613
  * - Success checkmark + message (auto-dismisses)
1564
1614
  * - Error/partial warning + message with optional retry
1565
1615
  */
1566
- declare function DockStatusBar({ className, onRetry }: DockStatusBarProps): react_jsx_runtime.JSX.Element | null;
1616
+ declare function DockStatusBar({ className, onRetry }: DockStatusBarProps): react.JSX.Element | null;
1567
1617
  /**
1568
1618
  * Compact variant for space-constrained layouts.
1569
1619
  * Shows only icon + abbreviated message.
1570
1620
  */
1571
1621
  declare function DockStatusBarCompact({ className }: {
1572
1622
  className?: string;
1573
- }): react_jsx_runtime.JSX.Element | null;
1623
+ }): react.JSX.Element | null;
1574
1624
 
1575
1625
  interface FloatingStatusProps {
1576
1626
  className?: string;
@@ -1579,7 +1629,7 @@ interface FloatingStatusProps {
1579
1629
  * Standalone floating status indicator for bulk operations.
1580
1630
  * Shows independently of row selection, positioned at bottom-center of grid.
1581
1631
  */
1582
- declare function FloatingStatus({ className }: FloatingStatusProps): react_jsx_runtime.JSX.Element;
1632
+ declare function FloatingStatus({ className }: FloatingStatusProps): react.JSX.Element;
1583
1633
 
1584
1634
  interface SheetsErrorBoundaryProps {
1585
1635
  children: ReactNode;
@@ -1612,19 +1662,20 @@ interface SheetsErrorStateProps {
1612
1662
  onRetry?: () => void;
1613
1663
  }
1614
1664
  /** Shown when the table data (or its metadata) fails to load. */
1615
- declare function SheetsErrorState({ error, onRetry }: SheetsErrorStateProps): react_jsx_runtime.JSX.Element;
1665
+ declare function SheetsErrorState({ error, onRetry }: SheetsErrorStateProps): react.JSX.Element;
1616
1666
  interface SheetsEmptyStateProps {
1617
1667
  tableName?: string;
1618
1668
  onAddRow?: () => void;
1669
+ readOnlyReason?: string | null;
1619
1670
  }
1620
1671
  /** Shown when the table loaded successfully but has no rows. */
1621
- declare function SheetsEmptyState({ tableName, onAddRow }: SheetsEmptyStateProps): react_jsx_runtime.JSX.Element;
1672
+ declare function SheetsEmptyState({ tableName, onAddRow, readOnlyReason }: SheetsEmptyStateProps): react.JSX.Element;
1622
1673
  /**
1623
1674
  * Shown during the initial data load. A STRUCTURAL skeleton of the grid (baseline-ui:
1624
1675
  * prefer skeletons over spinners) — mirrors the real grid's 40px header + 44px rows +
1625
1676
  * horizontal hairlines so the load→loaded swap doesn't jump. Pulse is motion-safe only.
1626
1677
  */
1627
- declare function SheetsLoadingState(): react_jsx_runtime.JSX.Element;
1678
+ declare function SheetsLoadingState(): react.JSX.Element;
1628
1679
 
1629
1680
  interface DataFilteringContextValue {
1630
1681
  filterTree: FilterGroup;
@@ -1684,4 +1735,4 @@ declare function useDataPagination({ initialPageSize, initialPageIndex, totalCou
1684
1735
  }) => any;
1685
1736
  };
1686
1737
 
1687
- export { BOOLEAN_TYPES, BUILTIN_EDITOR_TYPES, type Binding, CellPlugin, CellProps, CellRegistry, CellRegistryEntry, CellRenderer, type CellSlot, type CellSlots, CellType, type CellTypeBuiltins, CellTypeDefinition, CellTypeMatchInput, type CellTypeRegistry, ColumnSchema, type CommandResult, DATE_TIME_TYPES, type DataFilteringContextValue, type DataPaginationContextValue, type DispatchEvent, DockStatusBar, DockStatusBarCompact, type DraftMeta, type DraftRow, type DynamicFormSpec, ENHANCED_TYPES, EditorProps, type ExtractedRange, FeedbackProvider, type FieldTypeMap, type FilterCondition, type FilterGroup, type FilterNode, type FilterValue, FloatingStatus, GEOMETRY_TYPES, type GridCommand, type GridCommandContext, type Interceptor, MAX_FILTER_DEPTH, MEDIA_TYPES, type MetaField, type MetaTable, NON_EDITABLE_TYPES, NUMBER_TYPES, type OperationFeedback, RangeSet, type RelationColumnInfo, RelationInfo, type RowWithDraft, STRUCTURED_DATA_TYPES, type ScalarFieldSpec, type SelectionCurrent, type SelectionRect, Sheets, type SheetsAuthState, SheetsBackendAdapter, SheetsCell, SheetsCellRenderContext, SheetsConfig, SheetsControls, type SheetsControlsProps, type SheetsDraftBindings, SheetsEmptyState, SheetsErrorBoundary, SheetsErrorState, type SheetsEvent, SheetsExecuteFn, type SheetsHandle, SheetsLoadingState, SheetsPagination, type SheetsPaginationBindings, type SheetsPaginationProps, type SheetsProps, SheetsProvider, type SheetsRow, SheetsScopeKey, type SheetsSelection, type SheetsSelectionBindings, type SheetsSlots, type SheetsStoreState, SheetsTableSelector, type SheetsThemeInput, type SheetsThemeTokens, SheetsUploadFn, TYPED_ARRAY_TYPES, type TableSelectorProps, type TableWithCategory, type Trigger, type UploadProgress, type UploadResponse, type UseDataFilteringConfig, type UseDataPaginationConfig, type UseFieldUploadOptions, type UseInfiniteTableOptions, type UseInfiniteTableResult, type UseMetaOptions, type UseSheetsResult, type UseSheetsTableCursorOptions, type UseSheetsTableCursorResult, type UseTableOptions, type UseTableResult, VIEWER_ONLY_TYPES, buildScalarFormSpec, buildZodSchema, clear as clearSheetsSelection, computeDraftMetaSignature, countConditions, createCellTypeRegistry, createColumnSchemaFromMeta, createEmptyGroup, createMetadataHash, createPostGraphileAdapter, emptySheetsSelection, executeFieldUpload, extendRangeToCell, fillDownWrites, fillRightWrites, findTableFormSpec, getCellsInRange, getDraftMeta, isArrayCellType, isDraftRow, isSheetsScopeKey, isStructuredDataType, kbd, mapToFrontendCellType, moveActive, sheetsTableQueryKeys as queryKeys, resolveDownloadUrl, selectCell, selectRange, selectRow, sheetsQueryKeys, toTSV, toggleRow, tokensFromCssVars, useDataFiltering, useDataGridColumns, useDataPagination, useDynamicCreate, useDynamicUpdate, useFeedback, useOperationFeedback, useRelationColumns, useSheets, useSheetsAdapter, useSheetsFieldUpload, useSheetsImageUpload, useSheetsInfiniteTable, useSheetsMeta, useSheetsStore, useSheetsStoreApi, useSheetsTable, useSheetsTableCursor };
1738
+ export { BOOLEAN_TYPES, BUILTIN_EDITOR_TYPES, type Binding, CellPlugin, CellProps, CellRegistry, CellRegistryEntry, CellRenderer, type CellSlot, type CellSlots, CellType, type CellTypeBuiltins, CellTypeDefinition, CellTypeMatchInput, type CellTypeRegistry, ColumnSchema, type CommandResult, DATE_TIME_TYPES, type DataFilteringContextValue, type DataPaginationContextValue, type DispatchEvent, DockStatusBar, DockStatusBarCompact, type DraftMeta, type DraftRow, type DynamicFormSpec, ENHANCED_TYPES, EditorProps, type ExtractedRange, FeedbackProvider, type FieldTypeMap, type FilterCondition, type FilterGroup, type FilterNode, type FilterValue, FloatingStatus, GEOMETRY_TYPES, type GridCommand, type GridCommandContext, type Interceptor, MAX_FILTER_DEPTH, MEDIA_TYPES, type MetaField, type MetaTable, NON_EDITABLE_TYPES, NUMBER_TYPES, type OperationFeedback, RangeSet, type RelationColumnInfo, RelationInfo, type RowWithDraft, STRUCTURED_DATA_TYPES, type ScalarFieldSpec, type SelectionCurrent, type SelectionRect, Sheets, type SheetsAuthState, SheetsBackendAdapter, SheetsCell, SheetsCellRenderContext, SheetsConfig, SheetsControls, type SheetsControlsProps, type SheetsDraftBindings, SheetsEmptyState, SheetsErrorBoundary, SheetsErrorState, type SheetsEvent, SheetsExecuteFn, type SheetsHandle, SheetsLoadingState, SheetsPagination, type SheetsPaginationBindings, type SheetsPaginationProps, type SheetsProps, SheetsProvider, type SheetsRow, type SheetsRowIdentifier, type SheetsRowIdentityResolution, SheetsScopeKey, type SheetsSelection, type SheetsSelectionBindings, type SheetsSlots, type SheetsStoreState, SheetsTableSelector, type SheetsThemeInput, type SheetsThemeTokens, SheetsUploadFn, TYPED_ARRAY_TYPES, type TableSelectorProps, type TableWithCategory, type Trigger, type UploadProgress, type UploadResponse, type UseDataFilteringConfig, type UseDataPaginationConfig, type UseFieldUploadOptions, type UseInfiniteTableOptions, type UseInfiniteTableResult, type UseMetaOptions, type UseSheetsResult, type UseSheetsTableCursorOptions, type UseSheetsTableCursorResult, type UseTableOptions, type UseTableResult, VIEWER_ONLY_TYPES, buildScalarFormSpec, buildZodSchema, canRunSheetsMutation, clear as clearSheetsSelection, computeDraftMetaSignature, countConditions, createCellTypeRegistry, createColumnSchemaFromMeta, createEmptyGroup, createMetadataHash, createPostGraphileAdapter, emptySheetsSelection, executeFieldUpload, extendRangeToCell, fillDownWrites, fillRightWrites, findTableFormSpec, getCellsInRange, getDraftMeta, getSheetsWriteCapability, isArrayCellType, isDraftRow, isSheetsScopeKey, isStructuredDataType, kbd, mapToFrontendCellType, moveActive, sheetsTableQueryKeys as queryKeys, resolveDownloadUrl, resolveSheetsIdentifier, resolveSheetsRowIdentity, selectCell, selectRange, selectRow, sheetsIdentifierCacheKey, sheetsIdentifierToWhere, sheetsQueryKeys, sheetsRowKey, toTSV, toggleRow, tokensFromCssVars, useDataFiltering, useDataGridColumns, useDataPagination, useDynamicCreate, useDynamicUpdate, useFeedback, useOperationFeedback, useRelationColumns, useSheets, useSheetsAdapter, useSheetsFieldUpload, useSheetsImageUpload, useSheetsInfiniteTable, useSheetsMeta, useSheetsStore, useSheetsStoreApi, useSheetsTable, useSheetsTableCursor };