@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 +21 -0
- package/README.md +134 -2
- package/dist/index.d.ts +494 -0
- package/dist/index.js +3162 -0
- package/dist/index.js.map +1 -0
- package/dist/standalone.css +2 -0
- package/dist/styles.css +12 -0
- package/package.json +119 -3
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
|
-
#
|
|
1
|
+
# @marktiderman/genesis-data
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
package/dist/index.d.ts
ADDED
|
@@ -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 };
|