@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.
- package/README.md +231 -157
- package/dist/advanced.cjs +7192 -3840
- package/dist/advanced.cjs.map +1 -1
- package/dist/advanced.d.cts +2 -2
- package/dist/advanced.d.ts +2 -2
- package/dist/advanced.js +5 -5
- package/dist/auth.cjs.map +1 -1
- package/dist/auth.js +3 -3
- package/dist/chunk-CJ4PRA64.js +312 -0
- package/dist/chunk-CJ4PRA64.js.map +1 -0
- package/dist/chunk-II3MSNRO.js +18 -0
- package/dist/chunk-II3MSNRO.js.map +1 -0
- package/dist/{chunk-BYAYBXVB.js → chunk-J7KK4UWI.js} +6 -6
- package/dist/chunk-MBSHDF55.js +839 -0
- package/dist/chunk-MBSHDF55.js.map +1 -0
- package/dist/chunk-MOFFS5WQ.js +128 -0
- package/dist/chunk-MOFFS5WQ.js.map +1 -0
- package/dist/chunk-VCBY2AMT.js +8920 -0
- package/dist/chunk-VCBY2AMT.js.map +1 -0
- package/dist/{chunk-YJZFHL2D.js → chunk-ZOQDSOMO.js} +50 -312
- package/dist/chunk-ZOQDSOMO.js.map +1 -0
- package/dist/date-editor-ORCB43ZM.js +346 -0
- package/dist/date-editor-ORCB43ZM.js.map +1 -0
- package/dist/{grid-cell-types-C2-ocDS7.d.cts → grid-cell-types-YNIVK4hN.d.cts} +71 -18
- package/dist/{grid-cell-types-C2-ocDS7.d.ts → grid-cell-types-YNIVK4hN.d.ts} +71 -18
- package/dist/index.cjs +22733 -12052
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1432 -266
- package/dist/index.d.ts +1432 -266
- package/dist/index.js +12688 -6097
- package/dist/index.js.map +1 -1
- package/dist/sheets-context-Bb7ZoNBg.d.cts +436 -0
- package/dist/sheets-context-CPuf31LS.d.ts +436 -0
- package/dist/testing.cjs +1170 -589
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +80 -11
- package/dist/testing.d.ts +80 -11
- package/dist/testing.js +778 -147
- package/dist/testing.js.map +1 -1
- package/package.json +4 -5
- package/dist/chunk-4EZ6A23C.js +0 -44
- package/dist/chunk-4EZ6A23C.js.map +0 -1
- package/dist/chunk-6Y7CZ5VS.js +0 -168
- package/dist/chunk-6Y7CZ5VS.js.map +0 -1
- package/dist/chunk-BGL6EBTE.js +0 -446
- package/dist/chunk-BGL6EBTE.js.map +0 -1
- package/dist/chunk-ER3FIDK7.js +0 -4383
- package/dist/chunk-ER3FIDK7.js.map +0 -1
- package/dist/chunk-GZM2CSTR.js +0 -279
- package/dist/chunk-GZM2CSTR.js.map +0 -1
- package/dist/chunk-X7DHTSOX.js +0 -21
- package/dist/chunk-X7DHTSOX.js.map +0 -1
- package/dist/chunk-YJZFHL2D.js.map +0 -1
- package/dist/date-editor-G26WKILO.js +0 -358
- package/dist/date-editor-G26WKILO.js.map +0 -1
- package/dist/map-picker-ZUGGOIZS.js +0 -290
- package/dist/map-picker-ZUGGOIZS.js.map +0 -1
- package/dist/sheets-context-CHUVJCff.d.ts +0 -245
- package/dist/sheets-context-C_MkTxXm.d.cts +0 -245
- /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
|
-
|
|
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
|
-
-
|
|
20
|
-
|
|
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
|
|
55
|
+
## Install
|
|
23
56
|
|
|
24
|
-
|
|
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
|
-
|
|
40
|
-
plus the headless `@constructive-io/data` runtime
|
|
41
|
-
|
|
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
|
-
|
|
77
|
+
From npm (built package):
|
|
44
78
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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
|
-
|
|
85
|
+
```css
|
|
86
|
+
/* globals.css (npm) */
|
|
87
|
+
@import "@constructive-io/ui/globals.css";
|
|
88
|
+
@import "@constructive-io/sheets/styles.css";
|
|
89
|
+
```
|
|
54
90
|
|
|
55
|
-
|
|
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
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
102
|
+
See [Embedding](./docs/EMBEDDING.md) for the full setup.
|
|
103
|
+
|
|
104
|
+
## Quick start
|
|
102
105
|
|
|
103
106
|
```tsx
|
|
104
|
-
|
|
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
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
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
|
-
|
|
164
|
-
|
|
165
|
-
|
|
|
166
|
-
|
|
167
|
-
| `endpoint` |
|
|
168
|
-
| `auth` |
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
172
|
-
| `fieldTypeOverrides` |
|
|
173
|
-
| `
|
|
174
|
-
| `storage` | `{ endpoint
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
|
193
|
-
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
196
|
-
| `
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
|
201
|
-
|
|
202
|
-
| `useSheetsTable(
|
|
203
|
-
| `useSheetsInfiniteTable
|
|
204
|
-
| `
|
|
205
|
-
| `
|
|
206
|
-
| `
|
|
207
|
-
|
|
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
|
|
212
|
-
- [Host
|
|
213
|
-
- [
|
|
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
|
|