@marktiderman/genesis-data 0.0.0-stage → 0.5.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mark Tiderman
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,135 @@
1
- # Temporary Holding Version
1
+ # @marktiderman/genesis-data
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Genesis Data**, the editor UI: a sidebar of the tables the signed-in user may see, and a
4
+ sheet of the selected one where a cell is edited in place. Every save is checked against the
5
+ version of the row it was read at and committed with its audit entry, and the outcome is on screen:
6
+ "Saved", with the audit entry, or "Not saved" and why.
7
+
8
+ Built on genesis-ui's `ResourcePage` and `DataTable` (DATA.md decision 21). Routing and URL
9
+ state come from your app through an adapter (decision 23), and sign-in fills a slot.
10
+
11
+ **Status: 0.3, Experimental.** P2 adds:
12
+ - the **sheet view**, with keyboard editing and copy and paste;
13
+ - multi-row pastes saved in one transaction;
14
+ - **undo** from the audit;
15
+ - **bulk** set and delete;
16
+ - **CSV import** with a dry run;
17
+ - code-configured **form sections and conditions** (`forms`).
18
+
19
+ From P1:
20
+ - the sheet grid, with in-place edits;
21
+ - a record pop-up with a schema-built form, related records, history and delete;
22
+ - adding rows, and relation pickers;
23
+ - a filter builder, multi-field sort and group-by;
24
+ - saved views and CSV export.
25
+
26
+ ## Embed it in any app
27
+
28
+ ```tsx
29
+ import { DataStudio } from "@marktiderman/genesis-data";
30
+ import { createSupabaseStudioProvider } from "@marktiderman/genesis-data-server/client";
31
+ import "@marktiderman/genesis-data/standalone.css";
32
+ import { supabase } from "@/integrations/supabase/client";
33
+
34
+ const provider = createSupabaseStudioProvider(supabase, { url: "/api/studio" });
35
+
36
+ export default function DataPage() {
37
+ return <DataStudio provider={provider} />;
38
+ }
39
+ ```
40
+
41
+ `npx @marktiderman/genesis-cli data init` writes this page and its server for you.
42
+
43
+ - **No router or session wiring.** Genesis Data keeps its state in the page's query string. The
44
+ Supabase provider tells it when the signed-in user changes.
45
+ - **`standalone.css`** is prebuilt: every class Genesis Data uses, for apps without Tailwind v4
46
+ (Tailwind 3, CSS modules, or none). It adds no global reset. A small reset applies only inside
47
+ Genesis Data and its pop-ups. The app's own shadcn-style theme variables (`--background`,
48
+ `--primary`, …) win over Genesis's defaults, so Genesis Data matches the app.
49
+ - An app already on Tailwind v4 imports `styles.css` instead (see below).
50
+
51
+ ## Use it
52
+
53
+ ```tsx
54
+ import { DataStudio, createSearchParamsRouter } from "@marktiderman/genesis-data";
55
+ import { createStudioProvider } from "@marktiderman/genesis-data-server/client";
56
+ import { useSearchParams } from "react-router";
57
+
58
+ export default function AdminData() {
59
+ const { session } = useSupabaseSession(); // your app's own sign-in
60
+ const [params, setParams] = useSearchParams();
61
+ const router = createSearchParamsRouter(params, (next, { replace }) => setParams(next, { replace }));
62
+ const provider = useMemo(
63
+ () => createStudioProvider({ url: "/api/studio", getAccessToken: () => session?.access_token ?? null }),
64
+ [session],
65
+ );
66
+ return <DataStudio provider={provider} router={router} sessionKey={session?.user.id} signIn={<SignInForm />} />;
67
+ }
68
+ ```
69
+
70
+ The server half — the handler at `/api/studio` — is
71
+ [`@marktiderman/genesis-data-server`](../data-server/README.md).
72
+
73
+ Tailwind v4 needs to see Genesis Data's classes:
74
+
75
+ ```css
76
+ @import "tailwindcss";
77
+ @import "@marktiderman/genesis-ui/styles.css";
78
+ @import "@marktiderman/genesis-data/styles.css";
79
+ ```
80
+
81
+ ## Props
82
+
83
+ | Prop | |
84
+ | --- | --- |
85
+ | `provider` | Any Genesis `DataProvider` with `describe` and `listResources` — usually `createStudioProvider`. |
86
+ | `router` | `{ location, navigate }`. `createSearchParamsRouter` adapts React Router or Next.js; `useHistoryRouter` works without a router; `useMemoryRouter` for tests. URL keys: `table`, `page`, `sort`, `q`, `filter`, `group`, `record`. |
87
+ | `signIn` | Rendered instead of Genesis Data while the provider reports nobody signed in. |
88
+ | `sessionKey` | The signed-in user's id. When it changes, everything loaded for the previous user is dropped. |
89
+ | `forms` | Per `schema.table`: `{ sections: [{ title, fields }], visibleWhen: { field: (values) => boolean } }`. |
90
+ | `title`, `perPage`, `className` | Presentation. |
91
+
92
+ ## What it does
93
+
94
+ - **Open a record** with the ⤢ button on any row. The pop-up has three tabs:
95
+ - **Details:** a form built from the schema, with validation for required fields, numbers,
96
+ dates, enums and JSON, and pickers for links. Read-only fields show why they can't change.
97
+ - **Related:** records this one links to and from.
98
+ - **History:** the record's audit trail.
99
+
100
+ The URL names the record (`?record=…`), so **Copy link** shares it. History entries
101
+ have an **Undo** button.
102
+ - **New row** opens a form of only the fields the user may set.
103
+ - **Filter, Sort, Group** run on the server and live in the URL. **Views** saves them, with
104
+ search and visible columns, per table.
105
+ - **Export CSV** pages through every matching row, up to 10 000. Cells a spreadsheet would run
106
+ as formulas are neutralised.
107
+ - **Sheet view** (Table | Sheet, `?view=sheet`): arrows, Tab and Shift+arrows move and select;
108
+ Enter, F2 or typing edits; Delete clears; Cmd/Ctrl+C and Cmd/Ctrl+V copy and paste with Sheets
109
+ and Excel. A paste across rows is **one transaction**: every row changes at the version you
110
+ see, or none does, and the failing cells are marked. **Cmd/Ctrl+Z** undoes your latest
111
+ change from its audit entry.
112
+ - **Select rows** to set a field on all of them, or delete them: all or none.
113
+ - **Import CSV:** map the file's columns, **Check rows** (a dry run against the database that
114
+ lists every row that won't import, and why), then **Import**, in one transaction.
115
+ - **Board view** (`?view=kanban&by=status`): one column per value of an enum or yes/no field,
116
+ 50 cards per column with **Load more**, the same filters, search and sort as the table. Drag a
117
+ card, or use its **Move to** menu from the keyboard: a move is a version-checked update.
118
+ - **Calendar view** (`?view=calendar&by=starts_on&month=2026-10`): a month of rows by a date or
119
+ timestamp field, one request per month, up to 200 rows. Timestamps show on the viewer's day.
120
+ - **Row actions** the server offers are buttons in the record pop-up, asking first when the
121
+ action has a `confirm` question. A **Comments** tab lists and adds comments.
122
+ - **Link cells** show the linked row's label (one query per linked table per page). Links are
123
+ edited in the record form, with a picker that searches on the server.
124
+
125
+ ## What it shows
126
+
127
+ - **Read-only tables** carry a lock in the sidebar and a banner with the server's reason (no version
128
+ trigger, editing not enabled, RLS off…).
129
+ - **Columns** are exactly the fields `describe()` returned for this user; a column they can't read
130
+ never renders. Only fields with `permissions.update` are editable; enum and boolean fields edit
131
+ as a select.
132
+ - **A conflict** keeps the editor open with the message, and the row then shows the other person's
133
+ value, so the next edit starts from it.
134
+ - **This session's edits** lists every save and refusal, with the audit id, actor, time and the
135
+ before → after of each changed field.
@@ -0,0 +1,494 @@
1
+ import * as react from 'react';
2
+ import { ReactNode } from 'react';
3
+ import { DataProvider, BulkResult, FilterParam, SortParam } from '@marktiderman/genesis-core/provider';
4
+ import { AuditEntry, ResourceSchema, FieldSchema, RowAction } from '@marktiderman/genesis-core/schema';
5
+ import { SavedViewItem } from '@marktiderman/genesis-ui/data';
6
+
7
+ /** Everything the studio keeps in the URL. */
8
+ interface StudioLocation {
9
+ /** `schema.table`, e.g. `public.clients`. */
10
+ resource?: string;
11
+ /** 1-based. */
12
+ page?: number;
13
+ /** `field:asc` or `field:desc`; several, comma-separated, sort by each in turn. */
14
+ sort?: string;
15
+ search?: string;
16
+ /** Filters, as a JSON array of `[field, operator, value?]`. */
17
+ filters?: string;
18
+ /** Group rows by this field. */
19
+ group?: string;
20
+ /** The open record's id (`encodeRecordKey`), for a copyable link to it. */
21
+ record?: string;
22
+ /** `sheet`, `kanban` or `calendar`; the table otherwise. */
23
+ view?: StudioView;
24
+ /** For `kanban` and `calendar`: the field that places each row. */
25
+ by?: string;
26
+ /** For `calendar`: the month shown, `YYYY-MM`. */
27
+ month?: string;
28
+ }
29
+ /** The views other than the table. */
30
+ type StudioView = "sheet" | "kanban" | "calendar";
31
+ interface StudioNavigateOptions {
32
+ /** Replace the current history entry instead of pushing one (e.g. while typing a search). */
33
+ replace?: boolean;
34
+ }
35
+ interface StudioRouter {
36
+ location: StudioLocation;
37
+ navigate(next: StudioLocation, options?: StudioNavigateOptions): void;
38
+ }
39
+ declare function locationFromSearchParams(params: URLSearchParams): StudioLocation;
40
+ /**
41
+ * The studio's location as query parameters, keeping every parameter in
42
+ * `base` that isn't the studio's own.
43
+ */
44
+ declare function searchParamsFromLocation(location: StudioLocation, base?: URLSearchParams): URLSearchParams;
45
+ /**
46
+ * An adapter over any router that exposes search params with a setter —
47
+ * React Router's `useSearchParams`, or Next.js's `useSearchParams` plus
48
+ * `router.replace`/`push`.
49
+ *
50
+ * @example React Router
51
+ * const [params, setParams] = useSearchParams();
52
+ * const router = createSearchParamsRouter(params, (next, { replace }) => setParams(next, { replace }));
53
+ */
54
+ declare function createSearchParamsRouter(params: URLSearchParams, setParams: (next: URLSearchParams, options: {
55
+ replace: boolean;
56
+ }) => void): StudioRouter;
57
+ /**
58
+ * For an app with no router: keeps the studio's state in the current page's
59
+ * query string through the History API.
60
+ */
61
+ declare function useHistoryRouter(): StudioRouter;
62
+ /** A router held in memory, for tests and embedded previews. */
63
+ declare function useMemoryRouter(initial?: StudioLocation): StudioRouter;
64
+
65
+ /** How one resource's record form is laid out. */
66
+ interface StudioFormConfig {
67
+ /** Fields grouped under headings, in order. Fields in no section follow, under "Other". */
68
+ sections?: {
69
+ title: string;
70
+ fields: string[];
71
+ }[];
72
+ /**
73
+ * Show a field only when this returns true for the form's current values,
74
+ * e.g. `{ cancel_reason: (v) => v.status === "cancelled" }`. A hidden field
75
+ * is left out of the save.
76
+ */
77
+ visibleWhen?: Record<string, (values: Record<string, unknown>) => boolean>;
78
+ }
79
+
80
+ /** One entry in the session's activity panel. */
81
+ interface StudioActivity {
82
+ id: string;
83
+ at: Date;
84
+ resource: string;
85
+ field: string;
86
+ /** The record's key, as shown to the user. */
87
+ record: string;
88
+ outcome: "saved" | "not_saved";
89
+ /** What was attempted. Default `update`. */
90
+ action?: "update" | "create" | "delete";
91
+ message: string;
92
+ /** Present when the edit committed with an audit entry from the `table` sink. */
93
+ audit?: AuditEntry;
94
+ /**
95
+ * A bulk write's audit entries, one per row. A single entry holds them all,
96
+ * so its Undo reaches every row however many there were.
97
+ */
98
+ audits?: AuditEntry[];
99
+ /** True once this change has been undone. */
100
+ undone?: boolean;
101
+ }
102
+ interface DataStudioProps {
103
+ /**
104
+ * Where the data comes from: the studio handler's client
105
+ * (`createStudioProvider` from `@marktiderman/genesis-data-server/client`)
106
+ * or any Genesis `DataProvider` that implements `describe` and
107
+ * `listResources`.
108
+ */
109
+ provider: DataProvider;
110
+ /**
111
+ * URL state, from the app's router (see `createSearchParamsRouter`).
112
+ * Default: the page's own query string, through the History API.
113
+ */
114
+ router?: StudioRouter;
115
+ /** Shown in place of the studio while nobody is signed in. */
116
+ signIn?: ReactNode;
117
+ /**
118
+ * Changes when the signed-in user does (their id, say). The studio drops
119
+ * everything it loaded for the previous user and asks again. Not needed
120
+ * with a provider that reports its session (`createSupabaseStudioProvider`).
121
+ */
122
+ sessionKey?: string | number | null;
123
+ /** Heading above the table list. Default "Data"; `null` for none (the app's own page header names it). */
124
+ title?: string | null;
125
+ /**
126
+ * `card` (default): the studio draws its own frame. `plain`: no frame, so
127
+ * it sits flush inside an app's layout, under its own header and nav,
128
+ * like any other page of the app.
129
+ */
130
+ variant?: "card" | "plain";
131
+ /** Rows per page. Default 50. */
132
+ perPage?: number;
133
+ /**
134
+ * Record-form layout per resource (`schema.table`): sections, and fields
135
+ * shown only when a condition holds. Code first; see `StudioFormConfig`.
136
+ */
137
+ forms?: Readonly<Record<string, StudioFormConfig>>;
138
+ className?: string;
139
+ }
140
+ /**
141
+ * Genesis Data: a sidebar of the tables this user may see, and a sheet of
142
+ * the selected one where a cell is edited in place. Every edit carries the
143
+ * version it was read at, so a stale edit is refused rather than saved over
144
+ * someone else's, and the outcome — saved with its audit entry, or not saved
145
+ * and why — is shown on screen.
146
+ *
147
+ * It renders inside its own `GenesisProvider`, so it works whether or not
148
+ * the app already has one.
149
+ *
150
+ * @stability Experimental
151
+ */
152
+ declare function DataStudio(props: DataStudioProps): react.JSX.Element;
153
+ /** A provider's report of who is signed in (see `createSupabaseStudioProvider`). */
154
+ interface StudioSessionSource {
155
+ subscribe(listener: (userId: string | null) => void): () => void;
156
+ }
157
+ interface ActivityPanelProps {
158
+ entries: StudioActivity[];
159
+ onUndo?: (entry: StudioActivity) => void;
160
+ }
161
+ /**
162
+ * The studio's activity panel: recent changes, with undo.
163
+ *
164
+ * @stability Beta
165
+ */
166
+ declare function ActivityPanel({ entries, onUndo }: ActivityPanelProps): react.JSX.Element;
167
+
168
+ interface BulkEditDialogProps {
169
+ schema: ResourceSchema;
170
+ count: number;
171
+ open: boolean;
172
+ onOpenChange: (open: boolean) => void;
173
+ /** Apply `data` to every selected row, in one transaction. */
174
+ onApply: (data: Record<string, unknown>) => Promise<BulkResult>;
175
+ }
176
+ /**
177
+ * Set one field on every selected row: all of them change, or none do.
178
+ *
179
+ * @stability Beta
180
+ */
181
+ declare function BulkEditDialog({ schema, count, open, onOpenChange, onApply }: BulkEditDialogProps): react.JSX.Element;
182
+
183
+ interface ImportDialogProps {
184
+ provider: DataProvider;
185
+ schema: ResourceSchema;
186
+ onImported: (count: number) => void;
187
+ }
188
+ /**
189
+ * CSV import (DATA.md P2): map the file's columns to fields, check
190
+ * every row against the database with a dry run, then add them all in one
191
+ * transaction. Nothing is coerced or dropped: a value that won't convert is
192
+ * listed, with the database's reason, before anything is kept.
193
+ *
194
+ * @stability Beta
195
+ */
196
+ declare function ImportDialog({ provider, schema, onImported }: ImportDialogProps): react.JSX.Element;
197
+
198
+ interface FilterBuilderProps {
199
+ fields: readonly FieldSchema[];
200
+ filters: FilterParam[];
201
+ onChange: (filters: FilterParam[]) => void;
202
+ }
203
+ /**
204
+ * Filters by field, with the operators that fit each field's type.
205
+ *
206
+ * @stability Beta
207
+ */
208
+ declare function FilterBuilder({ fields, filters, onChange, }: FilterBuilderProps): react.JSX.Element;
209
+ interface SortBuilderProps {
210
+ fields: readonly FieldSchema[];
211
+ sorts: SortParam[];
212
+ onChange: (sorts: SortParam[]) => void;
213
+ }
214
+ /**
215
+ * Sort by several fields, first one first.
216
+ *
217
+ * @stability Beta
218
+ */
219
+ declare function SortBuilder({ fields, sorts, onChange, }: SortBuilderProps): react.JSX.Element;
220
+ interface GroupPickerProps {
221
+ fields: readonly FieldSchema[];
222
+ group: string | undefined;
223
+ onChange: (group: string | undefined) => void;
224
+ }
225
+ /**
226
+ * Group rows by a field with few distinct values.
227
+ *
228
+ * @stability Beta
229
+ */
230
+ declare function GroupPicker({ fields, group, onChange, }: GroupPickerProps): react.JSX.Element;
231
+ interface ExportButtonProps {
232
+ onExport: () => void;
233
+ busy: boolean;
234
+ progress: number;
235
+ }
236
+ /**
237
+ * The studio toolbar's export button, with its progress.
238
+ *
239
+ * @stability Beta
240
+ */
241
+ declare function ExportButton({ onExport, busy, progress }: ExportButtonProps): react.JSX.Element;
242
+ interface NewRowButtonProps {
243
+ allowed: boolean;
244
+ reason?: string;
245
+ onClick: () => void;
246
+ }
247
+ /**
248
+ * The studio toolbar's new row button, disabled with a reason when not allowed.
249
+ *
250
+ * @stability Beta
251
+ */
252
+ declare function NewRowButton({ allowed, reason, onClick }: NewRowButtonProps): react.JSX.Element;
253
+ type ViewKind = "table" | "sheet" | "kanban" | "calendar";
254
+ interface ViewSwitchProps {
255
+ view: ViewKind;
256
+ onChange: (view: ViewKind) => void;
257
+ /** Views this table can show. A board and a calendar each need a fitting field. */
258
+ available?: Partial<Record<ViewKind, boolean>>;
259
+ }
260
+ /**
261
+ * Switch between the table, the spreadsheet grid, a board and a calendar.
262
+ *
263
+ * @stability Beta
264
+ */
265
+ declare function ViewSwitch({ view, onChange, available, }: ViewSwitchProps): react.JSX.Element;
266
+ interface ViewFieldPickerProps {
267
+ label: string;
268
+ fields: readonly FieldSchema[];
269
+ value: string;
270
+ onChange: (field: string) => void;
271
+ }
272
+ /**
273
+ * Which field lays out the board or the calendar.
274
+ *
275
+ * @stability Beta
276
+ */
277
+ declare function ViewFieldPicker({ label, fields, value, onChange, }: ViewFieldPickerProps): react.JSX.Element;
278
+ interface HideFieldsProps {
279
+ fields: readonly FieldSchema[];
280
+ hidden: ReadonlySet<string>;
281
+ onChange: (hidden: Set<string>) => void;
282
+ }
283
+ /**
284
+ * Which fields the grid shows.
285
+ *
286
+ * @stability Beta
287
+ */
288
+ declare function HideFields({ fields, hidden, onChange, }: HideFieldsProps): react.JSX.Element;
289
+ interface SearchBoxProps {
290
+ value: string;
291
+ onChange: (value: string) => void;
292
+ }
293
+ /**
294
+ * Search every text field, as you type.
295
+ *
296
+ * @stability Beta
297
+ */
298
+ declare function SearchBox({ value, onChange }: SearchBoxProps): react.JSX.Element;
299
+
300
+ type StudioViewKind = "grid" | "kanban" | "calendar";
301
+ interface ViewsPanelProps {
302
+ view: StudioViewKind;
303
+ available: Record<StudioViewKind, boolean>;
304
+ onChange: (view: StudioViewKind) => void;
305
+ saved: SavedViewItem[];
306
+ onLoad: (view: SavedViewItem) => void;
307
+ onDelete: (id: string) => void;
308
+ onSave: (name: string) => void;
309
+ }
310
+ /**
311
+ * The left column: how to look at this table, and the views you've saved.
312
+ *
313
+ * @stability Beta
314
+ */
315
+ declare function ViewsPanel({ view, available, onChange, saved, onLoad, onDelete, onSave, }: ViewsPanelProps): react.JSX.Element;
316
+ interface TableTabsProps {
317
+ resources: {
318
+ name: string;
319
+ label?: string;
320
+ access: {
321
+ update: boolean;
322
+ reason?: string;
323
+ };
324
+ }[];
325
+ selected?: string;
326
+ onSelect: (resource: string) => void;
327
+ /** `plain` draws underlined tabs on the page instead of a tinted band. */
328
+ variant?: "card" | "plain";
329
+ }
330
+ /**
331
+ * Table tabs across the top, as Airtable shows a base's tables.
332
+ *
333
+ * @stability Beta
334
+ */
335
+ declare function TableTabs({ resources, selected, onSelect, variant, }: TableTabsProps): react.JSX.Element;
336
+
337
+ type Row = Record<string, unknown>;
338
+ interface SheetViewProps {
339
+ provider: DataProvider;
340
+ schema: ResourceSchema;
341
+ rows: Row[];
342
+ keys: Map<Row, string>;
343
+ linkLabels: Map<string, Map<string, string>>;
344
+ /** Saved rows, to put back in the list. */
345
+ onSaved: (updates: {
346
+ old: Row;
347
+ next: Row;
348
+ audit?: AuditEntry;
349
+ }[]) => void;
350
+ onFailed: (message: string) => void;
351
+ onUndo: () => void;
352
+ onNotice: (message: string) => void;
353
+ /** Fields not shown. */
354
+ hidden?: ReadonlySet<string>;
355
+ /** Selected row ids, and how to change them. Without these, no checkboxes. */
356
+ selected?: ReadonlySet<string>;
357
+ onToggleSelect?: (id: string) => void;
358
+ onToggleAll?: () => void;
359
+ /** Open a row in the record pop-up. */
360
+ onOpenRecord?: (id: string) => void;
361
+ /** The number shown for the first row (pages after the first start later). */
362
+ firstRowNumber?: number;
363
+ /** Under the last row, e.g. "Add a record". */
364
+ footer?: ReactNode;
365
+ height?: number;
366
+ /** Accessible name; defaults to the table's label. */
367
+ label?: string;
368
+ }
369
+ /**
370
+ * The spreadsheet view of a table (DATA.md P2). A paste across rows
371
+ * is saved in ONE transaction through `updateMany`: every row changes, at
372
+ * the version it was read, or none does, and the failing cells are marked.
373
+ *
374
+ * @stability Beta
375
+ */
376
+ declare function SheetView({ provider, schema, rows, keys, linkLabels, onSaved, onFailed, onUndo, onNotice, hidden, selected, onToggleSelect, onToggleAll, onOpenRecord, firstRowNumber, footer, height, label, }: SheetViewProps): react.JSX.Element;
377
+
378
+ interface KanbanViewProps {
379
+ provider: DataProvider;
380
+ schema: ResourceSchema;
381
+ sessionKey: string | number | null;
382
+ /** The field whose value is each card's column. */
383
+ field: FieldSchema;
384
+ filters: FilterParam[];
385
+ sorts: SortParam[];
386
+ search: string;
387
+ onOpenRecord: (id: string) => void;
388
+ onMoved: (record: string, audit?: AuditEntry) => void;
389
+ onFailed: (record: string, message: string) => void;
390
+ onSignedOut: () => void;
391
+ }
392
+ /**
393
+ * A board of the table's rows, one column per value of `field`. Each column
394
+ * is paged on its own (50 cards, then "Load more"), with the same filters,
395
+ * search and sort as the table. Moving a card is a version-checked update of
396
+ * `field`, so a card someone else just changed is refused, not overwritten.
397
+ *
398
+ * @stability Beta
399
+ */
400
+ declare function KanbanView({ provider, schema, sessionKey, field, filters, sorts, search, onOpenRecord, onMoved, onFailed, onSignedOut, }: KanbanViewProps): react.JSX.Element;
401
+
402
+ interface CalendarViewProps {
403
+ provider: DataProvider;
404
+ schema: ResourceSchema;
405
+ sessionKey: string | number | null;
406
+ /** The date or timestamp field that places each row. */
407
+ field: FieldSchema;
408
+ /** `YYYY-MM`; this month when absent. */
409
+ month: string | undefined;
410
+ onMonthChange: (month: string) => void;
411
+ filters: FilterParam[];
412
+ sorts: SortParam[];
413
+ search: string;
414
+ onOpenRecord: (id: string) => void;
415
+ onSignedOut: () => void;
416
+ }
417
+ /**
418
+ * A month of the table's rows, placed by a date field and drawn by Genesis UI's EventCalendar.
419
+ * One request per month grid (a `gte`/`lt` range on the field covering the month's whole weeks,
420
+ * so the days shown from the months either side are filled too, with the table's filters, search
421
+ * and sort), up to 200 rows. A timestamp shows on the day it falls in the viewer's time zone.
422
+ *
423
+ * @stability Beta
424
+ */
425
+ declare function CalendarView({ provider, schema, sessionKey, field, month: monthProp, onMonthChange, filters, sorts, search, onOpenRecord, onSignedOut, }: CalendarViewProps): react.JSX.Element;
426
+
427
+ interface RecordPanelProps {
428
+ provider: DataProvider;
429
+ sessionKey: unknown;
430
+ schema: ResourceSchema;
431
+ /** The record's id (`encodeRecordKey`). */
432
+ id: string;
433
+ onClose: () => void;
434
+ /** Open another record (a related one), in its own table. */
435
+ onOpenRecord: (resource: string, id: string) => void;
436
+ onSaved: (row: Record<string, unknown>, audit?: AuditEntry) => void;
437
+ onDeleted: (audit?: AuditEntry) => void;
438
+ onFailed: (action: string, message: string) => void;
439
+ /** A change from the History tab was undone. */
440
+ onUndone?: (audit?: AuditEntry) => void;
441
+ /** Sections and conditional fields for the form. */
442
+ formConfig?: StudioFormConfig;
443
+ /** A row action ran; `row` is null when it removed the row. */
444
+ onActionRan?: (action: RowAction, row: Record<string, unknown> | null, audit?: AuditEntry) => void;
445
+ }
446
+ /**
447
+ * One record, in a side panel: its fields as a form, the records it links to
448
+ * and from, and its audit history. The URL names it, so the link copies.
449
+ *
450
+ * @stability Beta
451
+ */
452
+ declare function RecordPanel(props: RecordPanelProps): react.JSX.Element;
453
+
454
+ interface RelationPickerProps {
455
+ provider: DataProvider;
456
+ sessionKey: unknown;
457
+ field: FieldSchema;
458
+ /** The linked row's key, as text ("" for none). */
459
+ value: string;
460
+ onChange: (value: string) => void;
461
+ disabled?: boolean;
462
+ id?: string;
463
+ }
464
+ /**
465
+ * Pick a linked row by searching the target resource on the server, so it
466
+ * works for a table of any size; shows each row by its label field.
467
+ *
468
+ * @stability Beta
469
+ */
470
+ declare function RelationPicker({ provider, sessionKey, field, value, onChange, disabled, id }: RelationPickerProps): react.JSX.Element;
471
+
472
+ interface FieldIconProps {
473
+ field: FieldSchema;
474
+ isKey?: boolean;
475
+ }
476
+ /**
477
+ * An icon for the field's type, as Airtable shows in each column header.
478
+ *
479
+ * @stability Beta
480
+ */
481
+ declare function FieldIcon({ field, isKey }: FieldIconProps): react.JSX.Element;
482
+ interface PillProps {
483
+ value: string;
484
+ tint: string;
485
+ className?: string;
486
+ }
487
+ /**
488
+ * A value drawn as a tinted pill.
489
+ *
490
+ * @stability Beta
491
+ */
492
+ declare function Pill({ value, tint, className }: PillProps): react.JSX.Element;
493
+
494
+ export { ActivityPanel, type ActivityPanelProps, BulkEditDialog, type BulkEditDialogProps, CalendarView, type CalendarViewProps, DataStudio, type DataStudioProps, ExportButton, type ExportButtonProps, FieldIcon, type FieldIconProps, FilterBuilder, type FilterBuilderProps, GroupPicker, type GroupPickerProps, HideFields, type HideFieldsProps, ImportDialog, type ImportDialogProps, KanbanView, type KanbanViewProps, NewRowButton, type NewRowButtonProps, Pill, type PillProps, RecordPanel, type RecordPanelProps, RelationPicker, type RelationPickerProps, SearchBox, type SearchBoxProps, SheetView, type SheetViewProps, SortBuilder, type SortBuilderProps, type StudioActivity, type StudioLocation, type StudioNavigateOptions, type StudioRouter, type StudioSessionSource, type StudioView, TableTabs, type TableTabsProps, ViewFieldPicker, type ViewFieldPickerProps, type ViewKind, ViewSwitch, type ViewSwitchProps, ViewsPanel, type ViewsPanelProps, createSearchParamsRouter, locationFromSearchParams, searchParamsFromLocation, useHistoryRouter, useMemoryRouter };