@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
package/README.md CHANGED
@@ -12,17 +12,49 @@
12
12
  <a href="https://www.npmjs.com/package/@constructive-io/sheets"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/blocks?filename=packages%2Fsheets%2Fpackage.json"/></a>
13
13
  </p>
14
14
 
15
- Portable spreadsheet-like CRUD editor for Constructive/PostGraphile backends. The package provides a native DOM grid with filtering, pagination, cell editing, draft rows, relation handling, and standalone authentication.
15
+ A spreadsheet-style editor for the tables of a Constructive (PostGraphile) API.
16
+ Give it an endpoint and a session; it reads the table's model from `_meta` and
17
+ introspection, then loads, edits, creates and deletes rows itself, with
18
+ PostgreSQL privileges and row-level security deciding every read and write.
19
+
20
+ What the grid does:
21
+
22
+ - Every column kind the backend can create renders its exact value and edits with
23
+ a matching editor: exact big numbers and decimals, enum labels, three-state
24
+ booleans, ranges, records, geometry, JSON, lists. Anything the model cannot prove
25
+ is read-only and says why.
26
+ - Readable field labels (`dueOn` reads "Due on", with the raw name in the header's
27
+ title). A value too wide for its column ends with an ellipsis and keeps the full
28
+ value in its title.
29
+ - Linked records of every kind (belongs to, has one, has many, many to many), with
30
+ composite keys, and a picker that searches the related table. A double-click opens
31
+ the link editor; a click on a chip of the active cell opens that record.
32
+ - File columns (images, uploads, lists of uploads, attachment links) with
33
+ presigned uploads, previews and progress.
34
+ - Filters with the operators each column really has, linked-record filters,
35
+ multi-column sort, search, column order, hiding, freezing and row height, and saved
36
+ views (browser storage by default, or the host's).
37
+ - A record panel: one record with every field, its linked records and files,
38
+ previous and next, delete, and a form for a new record.
39
+ - CSV and TSV import with a column mapping, per-cell checks and an error report, and a
40
+ CSV export of the whole view.
41
+ - Keyboard navigation, range selection, copy and paste, fill, undo and redo, draft
42
+ rows, a context menu (also from Shift+F10 or the menu key). Escape closes the record
43
+ panel, then clears the range and the active cell; a press outside the grid clears
44
+ them too.
45
+ - Email and web-address cells link only from the active cell (a first click
46
+ selects), and only for http, https and mailto addresses.
16
47
 
17
48
  ## Requirements
18
49
 
19
- - **Backend**: Constructive server (`cnc server`) exposing the `2026-07` `_meta` contract
20
- - **Frontend**: React 18+, Tailwind CSS v4
50
+ - A Constructive API (`cnc server`) that serves `_meta` with the `2026-07` contract.
51
+ Newer optional `_meta` fields add detail
52
+ ([list](./docs/HOST_INTEGRATION.md#what-the-server-must-provide)).
53
+ - React 18 or later, Tailwind CSS v4.
21
54
 
22
- ## Install from the Constructive registry
55
+ ## Install
23
56
 
24
- Configure the `@constructive` registry in `components.json`, then copy the
25
- complete source-owned grid into your application:
57
+ From the Constructive registry (editable source in your app):
26
58
 
27
59
  ```json
28
60
  {
@@ -36,181 +68,223 @@ complete source-owned grid into your application:
36
68
  pnpm dlx shadcn@latest add @constructive/sheets
37
69
  ```
38
70
 
39
- The command installs editable Sheets source and local Constructive primitives,
40
- plus the headless `@constructive-io/data` runtime. It does not install the npm
41
- UI or Sheets packages.
71
+ This installs the Sheets source and the Constructive UI primitives it uses under
72
+ your aliases, plus the headless `@constructive-io/data` runtime and the editor
73
+ dependencies (`react-aria-components` and `@internationalized/date` for dates,
74
+ `leaflet` and `react-leaflet` for maps). For the map, import `leaflet/dist/leaflet.css`
75
+ once in the app; without Leaflet the geometry editor edits shapes as GeoJSON text.
42
76
 
43
- ### Editor dependencies
77
+ From npm (built package):
44
78
 
45
- | Package | For |
46
- |---------|-----|
47
- | `leaflet` + `react-leaflet` | Geometry/map editors |
48
- | `react-aria-components` + `@internationalized/date` | Date picker editors |
49
-
50
- The registry command installs these so every built-in editor typechecks out of
51
- the box, even when an application hides those field types.
79
+ ```bash
80
+ pnpm add @constructive-io/sheets @constructive-io/data @constructive-io/ui \
81
+ @tanstack/react-query @tanstack/react-form \
82
+ react-aria-components @internationalized/date leaflet react-leaflet
83
+ ```
52
84
 
53
- ## Quick Start
85
+ ```css
86
+ /* globals.css (npm) */
87
+ @import "@constructive-io/ui/globals.css";
88
+ @import "@constructive-io/sheets/styles.css";
89
+ ```
54
90
 
55
- ### Standalone mode (built-in login UI)
91
+ Mount the portal host for cell editors once, as the last child of `<body>`:
56
92
 
57
93
  ```tsx
58
- import {
59
- SheetsProvider, Sheets, SheetsTableSelector,
60
- SheetsAuthGate, useSheetsMeta,
61
- } from '@/components/ui/sheets';
62
- import { selectConsoleDataTables } from '@constructive-io/data';
63
-
64
- function SpreadsheetApp() {
65
- const [activeTable, setActiveTable] = useState('');
66
- const { data: meta, isLoading } = useSheetsMeta();
67
-
68
- const tables = useMemo(() => {
69
- const metaTables = meta?._meta?.tables;
70
- if (!metaTables?.length) return [];
71
- return selectConsoleDataTables(metaTables).map(({ name }) => ({ name }));
72
- }, [meta?._meta?.tables]);
94
+ import { PortalRoot } from '@constructive-io/ui/portal'; // registry: '@/components/ui/portal'
73
95
 
74
- return (
75
- <>
76
- <SheetsTableSelector
77
- tables={tables}
78
- activeTable={activeTable}
79
- onTableChange={setActiveTable}
80
- isLoading={isLoading}
81
- />
82
- {activeTable && <Sheets tableName={activeTable} />}
83
- </>
84
- );
85
- }
86
-
87
- function App() {
88
- return (
89
- <SheetsProvider config={{
90
- endpoint: 'http://localhost:3000/graphql',
91
- auth: { mode: 'standalone' },
92
- }}>
93
- <SheetsAuthGate>
94
- <SpreadsheetApp />
95
- </SheetsAuthGate>
96
- </SheetsProvider>
97
- );
98
- }
96
+ <body>
97
+ {children}
98
+ <PortalRoot />
99
+ </body>
99
100
  ```
100
101
 
101
- ### Embedded mode (bring your own auth)
102
+ See [Embedding](./docs/EMBEDDING.md) for the full setup.
103
+
104
+ ## Quick start
102
105
 
103
106
  ```tsx
104
- import { SheetsProvider, Sheets } from '@/components/ui/sheets';
107
+ 'use client';
108
+
109
+ import { useMemo } from 'react';
110
+ import { Sheets, SheetsProvider, type SheetsConfig } from '@constructive-io/sheets'; // registry: '@/components/ui/sheets'
111
+
112
+ export function TasksGrid({ endpoint, getToken, userId }: {
113
+ endpoint: string;
114
+ getToken: () => string | null;
115
+ userId: string;
116
+ }) {
117
+ const config = useMemo<SheetsConfig>(() => ({
118
+ endpoint,
119
+ auth: { mode: 'embedded', getToken, getIdentityKey: () => userId },
120
+ onAuthError: () => {
121
+ // HTTP 401, UNAUTHENTICATED or BAD_TOKEN_DEFINITION: clear the token, go to sign-in.
122
+ },
123
+ }), [endpoint, getToken, userId]);
105
124
 
106
- function MySpreadsheet() {
107
125
  return (
108
- <SheetsProvider config={{
109
- endpoint: 'http://localhost:3000/graphql',
110
- auth: {
111
- mode: 'embedded',
112
- getToken: () => localStorage.getItem('my-jwt-token'),
113
- // A stable user/session id isolates the React Query cache without
114
- // putting the bearer token into query keys or devtools.
115
- getIdentityKey: () => currentUser.id,
116
- },
117
- onAuthError: () => {
118
- // Handle 401 — clear tokens, redirect to login, etc.
119
- },
120
- }}>
121
- <Sheets tableName="users" />
126
+ <SheetsProvider config={config}>
127
+ <div className="h-[680px] min-h-0">
128
+ <Sheets tableName="Task" />
129
+ </div>
122
130
  </SheetsProvider>
123
131
  );
124
132
  }
125
133
  ```
126
134
 
127
- ## CSS Setup
128
-
129
- Sheets requires Tailwind CSS v4.
130
-
131
- ### 1. Install Tailwind v4
132
-
133
- ```bash
134
- npm install tailwindcss @tailwindcss/postcss
135
- ```
136
-
137
- ### 2. Import styles in your global CSS
138
-
139
- ```css
140
- /* globals.css */
141
- @import 'tailwindcss';
142
- ```
143
-
144
- The shadcn install adds the Constructive theme and places the component source
145
- under your configured aliases, so Tailwind scans it as application code.
146
-
147
- Overlay editors use the shared Constructive portal host. Mount it once as the last child of `<body>` in your root layout:
148
-
149
- ```tsx
150
- // app/layout.tsx
151
- import { PortalRoot } from '@/components/ui/portal';
152
-
153
- <body>
154
- {children}
155
- <PortalRoot />
156
- </body>
157
- ```
158
-
159
- `PortalRoot` renders the managed `#portal-root` layer used by date, relation, JSON, and other overlay editors. Editors fall back to `document.body` while the host is unavailable, but mounting the shared root keeps application overlays in one predictable stack.
135
+ `tableName` is the table's GraphQL type name in `_meta` (or its `TableModel.key`,
136
+ `schema.Name`, when two schemas share the name). `Sheets` fills its parent, so give
137
+ the parent a bounded height. For a built-in sign-in, use `auth: { mode: 'standalone' }`
138
+ with `authEndpoint` and wrap the grid in `SheetsAuthGate` from
139
+ `@constructive-io/sheets/auth`.
160
140
 
161
141
  ## Configuration
162
142
 
163
- The `SheetsConfig` object passed to `<SheetsProvider>`:
164
-
165
- | Prop | Type | Required | Description |
166
- |------|------|----------|-------------|
167
- | `endpoint` | `string` | Yes | PostGraphile GraphQL endpoint URL |
168
- | `auth` | `SheetsAuthEmbedded \| SheetsAuthStandalone` | Yes | Auth mode |
169
- | `auth.getIdentityKey` | `() => string \| null` | Embedded | Stable non-secret user/session cache identity; an opaque token-generation key is used when omitted |
170
- | `authEndpoint` | `string` | No | Separate auth GraphQL endpoint |
171
- | `databaseId` | `string` | No | Multi-tenant database scope |
172
- | `fieldTypeOverrides` | `Record<string, string>` | No | Override detected field types |
173
- | `execute` | `SheetsExecuteFn` | No | Custom GraphQL executor |
174
- | `storage` | `{ endpoint: string; execute?: SheetsExecuteFn }` | No | Storage endpoint for presigned uploads and previews |
175
- | `executeUpload` | `SheetsUploadFn` | No | Host uploader returning `{ file: SheetsFileValue; url?: string }`. Takes precedence over the storage uploader |
176
- | `upload` | `{ bucketKey?: string }` | No | Optional explicit bucket override. Sheets requests the tenant's public default when omitted |
177
- | `queryClient` | `QueryClient` | No | Bring-your-own TanStack Query client |
178
- | `onAuthError` | `() => void` | No | Callback on 401/UNAUTHENTICATED |
179
-
180
- Sheets writes media cell values through the data endpoint. Image and upload
181
- cells store the durable file projection, and attachment cells store its public
182
- URL as text. The optional top-level upload result URL can expire. Hosts with
183
- neither storage nor an injected uploader render media cells read-only. See
184
- [Host integration](docs/HOST_INTEGRATION.md#media-uploads) for the migration
185
- from the previous upload API.
186
-
187
- ## Components
188
-
189
- | Component | Description |
190
- |-----------|-------------|
191
- | `SheetsProvider` | Context provider — wrap your app once |
192
- | `Sheets` | Main data grid (table name required) |
193
- | `SheetsTableSelector` | Table picker sidebar |
194
- | `SheetsControls` | Filter/search bar (included in Sheets by default) |
195
- | `SheetsPagination` | Page navigation (included in Sheets by default) |
196
- | `SheetsAuthGate` | Login/register UI for standalone mode |
197
-
198
- ## Hooks
199
-
200
- | Hook | Description |
201
- |------|-------------|
202
- | `useSheetsTable(tableName, options)` | Full CRUD operations for a table |
203
- | `useSheetsInfiniteTable(tableName, options)` | Infinite scroll variant |
204
- | `useSheetsMeta()` | Schema introspection metadata |
205
- | `useSheetsStore(selector)` | Access sheets Zustand store |
206
- | `useDynamicCreate(tableName)` | Programmatic row creation |
207
- | `useDynamicUpdate(tableName)` | Programmatic row updates |
143
+ `SheetsConfig` (passed to `<SheetsProvider config>`; keep it referentially stable):
144
+
145
+ | Field | Required | What it does |
146
+ |---|---|---|
147
+ | `endpoint` | yes | The data GraphQL endpoint |
148
+ | `auth` | yes | `{ mode: 'embedded', getToken, getIdentityKey? }` or `{ mode: 'standalone' }` |
149
+ | `authEndpoint` | standalone | The auth GraphQL endpoint |
150
+ | `databaseId` | | The tenant database; part of every cache key |
151
+ | `displayFields` | | Label fields per table (`{ Task: ['title'] }`), for record titles and relation chips |
152
+ | `fieldTypeOverrides` | | Force a cell type: `{ 'Task.notes': 'textarea' }` |
153
+ | `locale` | | BCP-47 locale for dates and numbers (default `en-US`) |
154
+ | `storage` | | `{ endpoint, execute? }`: the storage endpoint for file columns |
155
+ | `upload` | | Bucket, owner, files table, per-column bindings, confirmation wait |
156
+ | `views` | | Where saved views are kept (default: browser local storage) |
157
+ | `map` | | The map's tiles and place search, or `'off'` for either (default: OpenStreetMap; [details](./docs/EMBEDDING.md#map-editor)) |
158
+ | `executeUpload` | | A host uploader; takes precedence over storage |
159
+ | `execute` | | A custom GraphQL executor |
160
+ | `adapter` | | A custom `SheetsBackendAdapter` |
161
+ | `queryClient` | | Reuse your TanStack Query client |
162
+ | `plugins` | | Provider-wide cell types |
163
+ | `onAuthError` | | Called on HTTP 401 or the code `UNAUTHENTICATED` or `BAD_TOKEN_DEFINITION`, before the error is thrown |
164
+ | `onError` | | Called when a grid, editor, mutation or upload error surfaces |
165
+ | `logger` | | Replace the console logger |
166
+
167
+ Details: [Host integration](./docs/HOST_INTEGRATION.md). `<Sheets>` props:
168
+ [Embedding](./docs/EMBEDDING.md#9-sheets-props).
169
+
170
+ ## Components and hooks
171
+
172
+ | Name | What it is |
173
+ |---|---|
174
+ | `SheetsProvider` | Context, executors, cache scope; wrap the grids once |
175
+ | `Sheets` | The grid for one table |
176
+ | `SheetsTableSelector` | A table list (`tables` as names or `{ name, label?, category?, system? }`, `activeTable`, `onTableChange(name)`); the search matches the name and the label. System tables (`system: true`) show in their own section only while "Show system tables" is on (off by default, remembered per browser; `useShowSystemTables()` shares the setting with a picker of your own) |
177
+ | `SheetsControls`, `SheetsPagination` | The toolbar and the pager (`Sheets` renders both) |
178
+ | `ImportRecordsControl`, `ExportViewControl` | The Import and Export view buttons, for a custom toolbar |
179
+ | `SheetsAuthGate` | Sign-in for standalone mode (`@constructive-io/sheets/auth`) |
180
+ | `useTableModel(nameOrKey)`, `useTableModels(refs)` | The table model |
181
+ | `useSheetsMeta()` | The `_meta` result |
182
+ | `useSheetsTable(name, options)` | Rows and create, update, delete for one table |
183
+ | `useSheetsInfiniteTable`, `useSheetsTableCursor` | The same with infinite or cursor paging |
184
+ | `useColumnStorage`, `useFileUploadState`, `useFileCellWriter` | File columns |
185
+ | `uploadToFilesTable` | Upload one file into a files table outside any cell ([details](./docs/HOST_INTEGRATION.md#upload-a-file-outside-a-cell)) |
186
+ | `useSheets(props)` | The bindings `Sheets` renders with, for a custom shell |
187
+
188
+ The full list is in [Features](./docs/FEATURES.md#17-public-api).
189
+
190
+ ## Upgrading
191
+
192
+ This release builds every document from the table model and drops the name
193
+ guessing of earlier releases. Removed and changed public exports, with their
194
+ replacements:
195
+
196
+ **Removed**
197
+
198
+ | Removed | Use instead |
199
+ |---|---|
200
+ | `buildRelationInfoFromMeta(tableName, meta)` | `relationInfoFromModel(model)` with `useTableModel(name).model` |
201
+ | `createEmptyGroup(conjunction?)` | `createFilterGroup(logic?, children?)` |
202
+ | `countConditions(tree)` | `filterConditionsOf(group).length` |
203
+ | types `FilterCondition`, `FilterGroup`, `FilterNode`, `FilterValue` | `SheetsFilterCondition`, `SheetsFilterGroup` (`kind` and `logic` instead of `type` and `conjunction`), `SheetsFilterNode`, `SheetsFilterValue` |
204
+ | type `FieldTypeMap` | none: operators come from `column.filter.operators` |
205
+ | `RelationInfo.junctionTable`, `junctionLeftKeyField`, `junctionRightKeyField`, `displayName` | `RelationInfo.relation` (the `RelationModel`: `junction.tableKey`, `junction.left`, `junction.right`) |
206
+ | relation cache fields of `SheetsStoreState` (`relationInfoCache`, `ensureRelationInfo`, `getRelationInfoForTable`, …) | derive with `relationInfoFromModel(model)` |
207
+ | `sheetsQueryKeys.typeFields`, `sheetsQueryKeys.enumValues` | none: the table model replaces them (`sheetsQueryKeys.tableModel`) |
208
+
209
+ **Changed**
210
+
211
+ | Export | Change |
212
+ |---|---|
213
+ | `SheetsBackendAdapter` | New required method `fetchTableModel(execute, meta, tableRef, options?)`. |
214
+ | `AdapterTableContext` | Now `{ model: TableModel; tableName: string }`; `table` and `allTables` are gone. |
215
+ | `AdapterListQuery` | `where`, `orderBy: { field, direction }[]` (any number of keys), `limit`, `offset`, `after`, `relations: 'all' \| 'none' \| string[]`, `columns`, `relationPageSize`, `includeTotalCount`, `signal`; `fieldSelection` and `relationFieldMap` are gone. An unsortable column throws instead of being dropped. |
216
+ | `SheetsExecuteFn` | Optional third argument `{ signal }`. |
217
+ | `buildFindOneDocument` (`@constructive-io/data`) | Returns `FindOneDocument`, whose `read(data, errors?)` keeps per-cell errors. |
218
+ | auth error detection, `isAuthenticationError` (`@constructive-io/data`) | Only HTTP 401, or the error code `UNAUTHENTICATED` or `BAD_TOKEN_DEFINITION` (on the error or any entry of its `errors`; the list is `AUTHENTICATION_ERROR_CODES`). The message text no longer counts, so a permission error that says "unauthorized" no longer signs the user out. |
219
+ | `sheetsQueryKeys` table keys | Built from `TableModel.key` segments (`[Name, schema]`); a key from a bare name is a prefix of every schema's entry, so invalidating by name still works. |
220
+ | `executeFieldUpload` | Now `executeFieldUpload({ table: TableModel, column, rowKey }, file \| null, { execute, adapter, send })`; it no longer takes a `MetaTable` and refuses list columns (write the list with `useFileCellWriter`). |
221
+ | `useSheetsFieldUpload`, `UseFieldUploadOptions` | Deprecated: a wrapper over `useFileUploadState` and `useFileCellWriter`, for single-file columns. |
222
+ | `UploadResponse` | Now `unknown`: a projection, a link, a list or null. |
223
+ | `SheetsConfig.upload` | Now `SheetsUploadConfig` (`bucketKey`, `isPublic`, `ownerId`, `filesType`, `columns`, `processing`); `{ bucketKey }` still works. |
224
+ | `SheetsConfig.map` | New and optional (`SheetsMapConfig`): the map's tiles and place search, each a host service or `'off'`. Leaving it out keeps OpenStreetMap tiles and its Nominatim search. |
225
+ | `SheetsControlsProps` | Now `view`, `columnKeys`, `savedViews`, `tools`, `newRecord` with the selection and row props; `onExport` now drives only the "Export selected" button. The row count moved out of the toolbar to the new `SheetsStatusBar`, pinned to the bottom of the table frame. |
226
+ | save feedback | One save status (`SaveStatus`, in the status bar) reports every write: cells, new rows, deletes, the link and file editors, record panel fields. The grid no longer renders `FloatingStatus` (still exported; it reads the same status) and no longer toasts "Image saved" or "Update failed". `startOperation` accepts overlapping writes and settles once; `useOptionalFeedback` and `trackWrite` / `noteWrite` report a write from outside the grid's hooks. Delete and create messages now read "Row deleted", "3 rows deleted", "Row created", "Row not created". |
227
+ | toolbar Export button | Replaced by "Export view" (every row of the current view) and "Export selected (N)" (only with a selection; aria-label "Export selected rows"). |
228
+ | `SheetsHandle.exportCsv`, `ExportViewControl` | Both take an optional `protectFormulas`; for `exportCsv` it overrides the grid's `csvExport.protectFormulas` for that call. |
229
+ | `SHEETS_VIEW_STATE_VERSION`, `SheetsViewState` | Version 2: the state requires `columns` (`SheetsColumnLayout`). `validateSheetsViewState` reads a stored version 1 value and returns version 2. |
230
+ | `GridCommandContext` (commands barrel) | `view` gains the column and saved-view members, and `record` (`GridRecordCommandTarget`) and `newRecord` (`GridNewRecordCommandTarget`) are new optional targets; a host that builds its own context must add the `view` members. |
231
+ | `useDataFiltering`, `UseDataFilteringConfig`, `DataFilteringContextValue` | Config `{ model, initialFilters?, relatedModel? }`; result `{ filters, setFilters, clearFilters, where, appliedCount, conditions, dropped }`. |
232
+ | `MAX_FILTER_DEPTH` | Same value, now from the view-state module. |
233
+ | `SheetsEvent.type` | Adds `'search:change'`. |
234
+ | `DataGridProps` (`Sheets` props) | Adds `filters` / `onFiltersChange`, `sort` / `onSortChange`, `search` / `onSearchChange`, `columns` / `onColumnsChange`, `onOpenTable` (`{ tableKey, tableName, filters, reason }`), `recordId` / `onRecordOpenChange`, `csvExport` (`{ protectFormulas }`, off by default), `readOnly` (`true` or a reason). |
235
+ | `SheetsHandle` | Adds `openRecord(recordId)`, `openNewRecord()`, `closeRecord()`. |
236
+ | `ModelFormField.cellType` | Now `string` (was `CellType`); `buildModelFormSpec` takes an optional `{ typeOverrides }`. |
237
+ | `CellTypeMatchInput` | Adds `kind`, `semantic`, `column`; `pgAlias` is deprecated. |
238
+ | `useDataGridColumns(tableName, rows)` | The `rows` argument is ignored; columns come from the model. |
239
+ | `mapToFrontendCellType`, `resolveCellType`, `isImageField`, `buildScalarFormSpec` | Deprecated; use `cellTypeForColumn(column)` (or `column.value.file`) and `buildModelFormSpec(model, mode)` with `buildModelFormSchema(spec)`. |
240
+ | `SheetsAuthGate` and the auth hooks from the root entry | Deprecated there; import them from `@constructive-io/sheets/auth`. |
241
+ | `TableWithCategory` (`SheetsTableSelector` items) | Adds an optional `label`, which the list shows; `name` stays the value `onTableChange` receives. The search matches both. |
242
+ | `TableWithCategory.system` | Marks a table a platform module made. Mark them with `isSystemTable(metaTable, tableRolesFromCatalog(platformTables))` from `@constructive-io/data`: the platform API's table `category` decides for the tables it lists (`APP` is the owner's); for the rest, and without it, storage and database-scope tables count. The list hides them until "Show system tables" is on. |
243
+ | `keymap` bindings | Several bindings may match one key: the grid tries them in order and runs the first whose command can run; before, only the first match was tried. |
244
+
245
+ **Behavior**
246
+
247
+ - A primary-key field of a saved row, a computed column (on servers that report
248
+ `isComputed`) and any column the update input does not accept are read-only with a
249
+ reason; read-only is no longer decided by the names `id`, `createdAt` or `updatedAt`.
250
+ - A draft row's create sends only the creatable columns the user set; required
251
+ fields come from the model, and a key without a default is sent when the user typed it.
252
+ - An attachment cell is a file chip (its link's last segment, the link in its title),
253
+ no longer raw URL text.
254
+ - A file cell and a relation cell open their editor even when read-only, to show the
255
+ value and the reason.
256
+ - Escape closes the record panel, then collapses a range to the active cell, then
257
+ clears the active cell. A press outside `<Sheets>` clears the active cell and the
258
+ range; Tab into the grid or a navigation key brings the cursor back.
259
+ - Email and web-address cells link only from the active cell and only for http,
260
+ https and mailto addresses; a first click selects the cell. The context menu
261
+ (also Shift+F10 or the menu key) has "Open link".
262
+ - The cell wrapper (`#sheets-cell-r-c`) is the `role="gridcell"` element with
263
+ `aria-selected`, `aria-colindex` and the read-only reason. Cell views, including
264
+ custom ones, should not declare the role again.
265
+ - Cell editors and the record panel open and close at once, with no animation, and
266
+ editors take keyboard focus when they open.
267
+ - `SheetsConfig.onError` now also receives every failed upload in a file cell (not a
268
+ cancel) with `source: 'upload'`. Sheets never deletes the file row an unfinished
269
+ upload left; the storage service expires it, and `unfinishedUploadOf(error)` names
270
+ it for a host with its own cleanup.
271
+ - `useSheetsFieldUpload`'s mutation has a key under `'sheets'`
272
+ (`sheetsMutationKeys`), like every other Sheets mutation.
273
+ - Dates and times display as `YYYY-MM-DD`, `HH:mm:ss` and `YYYY-MM-DD HH:mm:ss`, with
274
+ no `T` or offset and a fraction of a second only when it is not zero; a value with
275
+ a time zone is shown in the viewer's zone, with the exact text and the zone in its
276
+ title. Copy, export, paste and writes keep the exact stored text.
277
+ - When the shown columns are narrower than the grid, the columns the user has not
278
+ resized grow to fill it; checkbox and number columns grow only when no other
279
+ column can. The extra width is never saved: a view and
280
+ `onColumnsChange` carry only widths set by dragging a column edge.
208
281
 
209
282
  ## Documentation
210
283
 
211
- - [Embedding Guide](./docs/EMBEDDING.md) — full integration walkthrough
212
- - [Host Integration](./docs/HOST_INTEGRATION.md) — auth error handling, QueryClient sharing
213
- - [Overlay Editors](./docs/OVERLAY_EDITORS.md) — editor architecture and custom editors
284
+ - [Embedding](./docs/EMBEDDING.md): installation, styles, portal, first grid
285
+ - [Host integration](./docs/HOST_INTEGRATION.md): configuration, auth errors, executors, adapters, view state, uploads
286
+ - [Features](./docs/FEATURES.md): what the grid does, keys and commands
287
+ - [Cell editors](./docs/OVERLAY_EDITORS.md): how editors open, the editor contract, custom editors
214
288
 
215
289
  ## License
216
290