@kronor/dtv 9.4.2 → 9.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/README.md +6 -0
- package/dist/cli/definitions/loadProject.js +5 -1
- package/dist/index.es.js +19723 -19373
- package/dist/types/App.d.ts +7 -1
- package/dist/types/components/FilterForm.d.ts +2 -1
- package/dist/types/components/SavedFilterList.d.ts +1 -1
- package/dist/types/components/aiAssistant.d.ts +9 -2
- package/dist/types/framework/actions.d.ts +2 -0
- package/dist/types/framework/analytics-emitter.d.ts +42 -0
- package/dist/types/framework/analytics.d.ts +270 -0
- package/dist/types/framework/dtv-version.d.ts +2 -0
- package/dist/types/framework/fetch-error.d.ts +35 -0
- package/dist/types/framework/filter-sharing.d.ts +5 -1
- package/dist/types/framework/state/app-state.d.ts +59 -1
- package/dist/types/framework/state/table.d.ts +3 -0
- package/dist/types/framework/state/use-app-state.d.ts +18 -6
- package/dist/types/framework/useUserDataManager.d.ts +7 -5
- package/dist/types/framework/user-data-manager.d.ts +14 -3
- package/dist/types/framework/user-data.d.ts +11 -1
- package/dist/types/framework/view-migrations.d.ts +17 -0
- package/dist/types/lib/index.d.ts +4 -0
- package/docs/analytics.md +779 -0
- package/package.json +1 -1
package/dist/types/App.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { AIIntegration, ModifyAiFilterPromptFn } from './components/aiAssistant';
|
|
2
2
|
import { type RequestHeaders } from './framework/data';
|
|
3
|
+
import { type DTVAnalytics } from './framework/analytics';
|
|
3
4
|
import { View } from './framework/view';
|
|
4
5
|
import type { UserDataJson } from './framework/user-data';
|
|
5
6
|
import { Runtime } from './framework/runtime';
|
|
@@ -60,6 +61,11 @@ export interface AppProps {
|
|
|
60
61
|
* before it is sent to the AI provider.
|
|
61
62
|
*/
|
|
62
63
|
modifyAiFilterPrompt?: ModifyAiFilterPromptFn;
|
|
64
|
+
/**
|
|
65
|
+
* Optional analytics: receives an event for what users do in the table, how long its
|
|
66
|
+
* requests take, and what fails. See `DTVAnalyticsEvent`.
|
|
67
|
+
*/
|
|
68
|
+
analytics?: DTVAnalytics;
|
|
63
69
|
/** Optional user data integration hooks. */
|
|
64
70
|
userData?: {
|
|
65
71
|
/** Optional async loader invoked when the user-data manager is created. */
|
|
@@ -86,5 +92,5 @@ export type DTVAPI = {
|
|
|
86
92
|
expandAll: () => void;
|
|
87
93
|
};
|
|
88
94
|
};
|
|
89
|
-
declare function App({ graphqlHost, requestHeaders, aiIntegration, showViewsMenu, showViewTitle, showCsvExportButton, showPopoutButton, views: viewsFromProps, viewsJson, externalRuntime, isOverlay, onCloseOverlay, syncFilterStateToUrl, rowSelection, actions, rowClassFunction, rowsPerPageOptions, userData, modifyAiFilterPrompt, apiRef }: AppProps): import("react/jsx-runtime").JSX.Element;
|
|
95
|
+
declare function App({ graphqlHost, requestHeaders, aiIntegration, showViewsMenu, showViewTitle, showCsvExportButton, showPopoutButton, views: viewsFromProps, viewsJson, externalRuntime, isOverlay, onCloseOverlay, syncFilterStateToUrl, rowSelection, actions, rowClassFunction, rowsPerPageOptions, userData, analytics, modifyAiFilterPrompt, apiRef }: AppProps): import("react/jsx-runtime").JSX.Element;
|
|
90
96
|
export default App;
|
|
@@ -13,7 +13,8 @@ interface FilterFormProps {
|
|
|
13
13
|
savedFilters: SavedFilter[];
|
|
14
14
|
displayState: FilterDisplayState;
|
|
15
15
|
onFilterGroupExpandedChange: (groupName: string, expanded: boolean) => void;
|
|
16
|
-
|
|
16
|
+
/** The filters are to be applied: the form was submitted, or all filters were reset. */
|
|
17
|
+
onSubmit: (trigger: 'submit' | 'reset') => void;
|
|
17
18
|
graphqlClient: GraphQLClient;
|
|
18
19
|
}
|
|
19
20
|
declare function FilterForm({ filterGroups, filterState, setFilterState, onSaveFilter, onUpdateFilter, onShareFilter, savedFilters, displayState, onFilterGroupExpandedChange, onSubmit, graphqlClient }: FilterFormProps): import("react/jsx-runtime").JSX.Element;
|
|
@@ -5,7 +5,7 @@ interface SavedFilterListProps {
|
|
|
5
5
|
savedFilters: SavedFilter[];
|
|
6
6
|
onFilterDelete: (filterId: string) => void;
|
|
7
7
|
onFilterLoad: (filterState: FilterState) => void;
|
|
8
|
-
onFilterApply: (
|
|
8
|
+
onFilterApply: (filter: SavedFilter) => void;
|
|
9
9
|
onFilterShare: (filterState: FilterState) => void;
|
|
10
10
|
visible: boolean;
|
|
11
11
|
filterGroups: FilterGroups;
|
|
@@ -3,10 +3,17 @@ import type { FilterFormState } from '../framework/filter-form-state';
|
|
|
3
3
|
import { FilterState } from '../framework/state';
|
|
4
4
|
import type { RefObject } from 'react';
|
|
5
5
|
import type { Toast } from 'primereact/toast';
|
|
6
|
+
/** Whether the AI filled the filters; it tells the user itself when not. */
|
|
7
|
+
export type AIFilterResult = {
|
|
8
|
+
readonly filled: true;
|
|
9
|
+
} | {
|
|
10
|
+
readonly filled: false;
|
|
11
|
+
readonly error: unknown;
|
|
12
|
+
};
|
|
6
13
|
export interface AIApi {
|
|
7
14
|
sendPrompt(filterGroups: FilterGroups, userPrompt: string, setFormState: (state: FilterState) => void, aiIntegration: AIIntegration, toast?: RefObject<Toast | null>, options?: {
|
|
8
15
|
modifyAiFilterPrompt?: ModifyAiFilterPromptFn;
|
|
9
|
-
}): Promise<
|
|
16
|
+
}): Promise<AIFilterResult>;
|
|
10
17
|
}
|
|
11
18
|
export type ModifyAiFilterPromptFn = (promptTemplate: string, args: {
|
|
12
19
|
filterGroups: FilterGroups;
|
|
@@ -50,4 +57,4 @@ export declare function mergeFilterFormState(schema: FilterExpr, currentState: F
|
|
|
50
57
|
export declare const GeminiApi: AIApi;
|
|
51
58
|
export declare function generateFilterWithAI(filterGroups: FilterGroups, userPrompt: string, setFormState: (state: FilterState) => void, apiImpl: AIApi, aiIntegration: AIIntegration, toast?: RefObject<Toast | null>, options?: {
|
|
52
59
|
modifyAiFilterPrompt?: ModifyAiFilterPromptFn;
|
|
53
|
-
}): Promise<
|
|
60
|
+
}): Promise<AIFilterResult>;
|
|
@@ -67,6 +67,8 @@ export interface ActionAPI {
|
|
|
67
67
|
}
|
|
68
68
|
export interface ActionDefinition {
|
|
69
69
|
label: string;
|
|
70
|
+
/** Names the action in analytics events. Defaults to the label, which may change with wording. */
|
|
71
|
+
id?: string;
|
|
70
72
|
onClick: (api: ActionAPI) => void | Promise<void>;
|
|
71
73
|
icon?: string;
|
|
72
74
|
/** Optional PrimeReact Button badge value. */
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { DTVAnalyticsEvent, DTVAnalyticsEventPayload, DTVAnalyticsSpan, ReportedEvent } from './analytics';
|
|
2
|
+
import type { View, ViewId } from './view';
|
|
3
|
+
/** The definition a view's events are reported for. */
|
|
4
|
+
export type ViewDefinition = {
|
|
5
|
+
readonly definition: string;
|
|
6
|
+
readonly definitionRevision: number;
|
|
7
|
+
};
|
|
8
|
+
export declare function viewDefinition(view: Pick<View, 'id' | 'migrations'>): ViewDefinition;
|
|
9
|
+
/** Reports the events of one mounted table. */
|
|
10
|
+
export interface AnalyticsEmitter {
|
|
11
|
+
/** Reports `payload` as an event of `viewId`. */
|
|
12
|
+
emit(viewId: ViewId, payload: DTVAnalyticsEventPayload): void;
|
|
13
|
+
/** The `seq` of the last `filtersApplied` reported; `null` before the first. */
|
|
14
|
+
lastFiltersAppliedSeq(): number | null;
|
|
15
|
+
}
|
|
16
|
+
/** Identifies a mounted table in analytics events. */
|
|
17
|
+
export declare function newInstanceId(): string;
|
|
18
|
+
/**
|
|
19
|
+
* The page session: from when DTV is loaded until the page is, again. The tables of a page,
|
|
20
|
+
* however many and whenever they mount, are of one session.
|
|
21
|
+
*/
|
|
22
|
+
export type PageSession = {
|
|
23
|
+
readonly id: string;
|
|
24
|
+
/** `sessionStarted` was reported. */
|
|
25
|
+
started: boolean;
|
|
26
|
+
};
|
|
27
|
+
/** Starts another page session, as loading the page again would. For tests. */
|
|
28
|
+
export declare function startPageSession(): PageSession;
|
|
29
|
+
/**
|
|
30
|
+
* An emitter numbering events from 1. `onEvent` is read at each event, so the host's
|
|
31
|
+
* handler may change; while there is none, nothing is numbered or reported. What the
|
|
32
|
+
* handler throws is logged: reporting must never break the table. The first event of the
|
|
33
|
+
* page session, of whichever table reports one first, is preceded by `sessionStarted`.
|
|
34
|
+
*/
|
|
35
|
+
export declare function createAnalyticsEmitter(instanceId: string, onEvent: () => ((event: DTVAnalyticsEvent) => void) | undefined, definitionOf: (viewId: ViewId) => ViewDefinition, now?: () => number, session?: () => PageSession): AnalyticsEmitter;
|
|
36
|
+
/** Measures a span: call the result when it ends. */
|
|
37
|
+
export declare function startSpan(now?: () => number, clock?: () => number): () => DTVAnalyticsSpan;
|
|
38
|
+
/** Reports an event of the table's selected view (see `useAppState`). */
|
|
39
|
+
export type Track = (event: ReportedEvent) => void;
|
|
40
|
+
/** How components deep in a table report events. */
|
|
41
|
+
export declare const AnalyticsContext: import("react").Context<Track>;
|
|
42
|
+
export declare function useTrack(): Track;
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
import type { DataOrdering } from './data-ordering';
|
|
2
|
+
import type { FetchErrorInfo } from './fetch-error';
|
|
3
|
+
import type { FilterId } from './filters';
|
|
4
|
+
import type { UndecodedFilterState } from './user-data-undecoded';
|
|
5
|
+
import type { ViewId } from './view';
|
|
6
|
+
/** Where an event happened. */
|
|
7
|
+
export type DTVAnalyticsEventBase = {
|
|
8
|
+
/**
|
|
9
|
+
* Identifies the page session: from when DTV was loaded until the page is loaded again.
|
|
10
|
+
* Its tables, however many, share it; another tab has another one.
|
|
11
|
+
*/
|
|
12
|
+
readonly sessionId: string;
|
|
13
|
+
/** Identifies one mounted table. A popout of it is another one. */
|
|
14
|
+
readonly instanceId: string;
|
|
15
|
+
/** Numbers the instance's events from 1, without gaps, in the order they were reported. */
|
|
16
|
+
readonly seq: number;
|
|
17
|
+
/** When the event was reported, in milliseconds since the epoch. */
|
|
18
|
+
readonly at: number;
|
|
19
|
+
readonly viewId: ViewId;
|
|
20
|
+
/**
|
|
21
|
+
* The view's definition: the id its migrations are kept under. Views built per record
|
|
22
|
+
* (`asset-list-7`) share one. Without migrations, the view id.
|
|
23
|
+
*/
|
|
24
|
+
readonly definition: string;
|
|
25
|
+
/**
|
|
26
|
+
* The revision of the definition the table runs with. Filter states in events are
|
|
27
|
+
* written for it, and can be taken to a later revision with the view's migrations.
|
|
28
|
+
*/
|
|
29
|
+
readonly definitionRevision: number;
|
|
30
|
+
};
|
|
31
|
+
/** What a span adds: it is reported when it ends. */
|
|
32
|
+
export type DTVAnalyticsSpan = {
|
|
33
|
+
/** When it started, in milliseconds since the epoch. */
|
|
34
|
+
readonly startedAt: number;
|
|
35
|
+
readonly durationMs: number;
|
|
36
|
+
};
|
|
37
|
+
/** An error as events carry it. */
|
|
38
|
+
export type DTVAnalyticsError = {
|
|
39
|
+
readonly name: string;
|
|
40
|
+
readonly message: string;
|
|
41
|
+
};
|
|
42
|
+
/** What made a table apply filters. */
|
|
43
|
+
export type FiltersAppliedTrigger =
|
|
44
|
+
/** The filter form was submitted. */
|
|
45
|
+
'submit'
|
|
46
|
+
/** All filters were reset in the filter form. */
|
|
47
|
+
| 'reset'
|
|
48
|
+
/** An applied filter's pill was removed. */
|
|
49
|
+
| 'pillRemoved'
|
|
50
|
+
/** A saved filter was applied. */
|
|
51
|
+
| 'savedFilter'
|
|
52
|
+
/** Host code applied them: a cell renderer, row expansion, no-rows component or action. */
|
|
53
|
+
| 'api'
|
|
54
|
+
/** The table opened with a filter state from a shared link, or one made elsewhere (e.g. by the app). */
|
|
55
|
+
| 'link'
|
|
56
|
+
/**
|
|
57
|
+
* The table opened with the filter state it keeps in its URL (`syncFilterStateToUrl`): a
|
|
58
|
+
* reload, its popout, or that URL copied from the address bar.
|
|
59
|
+
*/
|
|
60
|
+
| 'url'
|
|
61
|
+
/** The table opened with the filter state persisted in the user's data. */
|
|
62
|
+
| 'restored'
|
|
63
|
+
/** The table opened with the view's initial filter values. */
|
|
64
|
+
| 'initial';
|
|
65
|
+
/** Why a table requested rows. */
|
|
66
|
+
export type FetchReason =
|
|
67
|
+
/** Filters were applied, the table opening included. */
|
|
68
|
+
'filters' | 'ordering' | 'rowsPerPage' | 'nextPage' | 'previousPage'
|
|
69
|
+
/** The host asked for fresh rows, e.g. after a mutation. */
|
|
70
|
+
| 'refresh'
|
|
71
|
+
/** The rows per page or ordering changed in the user's data, e.g. in another tab. */
|
|
72
|
+
| 'userData';
|
|
73
|
+
/** A panel below the menu bar, or the popout. */
|
|
74
|
+
export type DTVAnalyticsPanel = 'filters' | 'savedFilters' | 'preferences' | 'aiAssistant' | 'popout';
|
|
75
|
+
/** Filters whose stored state was dropped while the user's data was read. */
|
|
76
|
+
export type DTVAnalyticsResets = {
|
|
77
|
+
readonly viewId: ViewId;
|
|
78
|
+
readonly persistedFilterState: readonly FilterId[];
|
|
79
|
+
readonly savedFilters: ReadonlyArray<{
|
|
80
|
+
readonly name: string;
|
|
81
|
+
readonly filterIds: readonly FilterId[];
|
|
82
|
+
}>;
|
|
83
|
+
};
|
|
84
|
+
/** A view's stored data left as stored while the user's data was read. */
|
|
85
|
+
export type DTVAnalyticsRetainedView = {
|
|
86
|
+
readonly viewId: ViewId;
|
|
87
|
+
/** `newerRevision`: written for a revision of the definition this table does not know yet (an old tab, a rollback). */
|
|
88
|
+
readonly reason: 'newerRevision' | 'decodeFailed';
|
|
89
|
+
};
|
|
90
|
+
/** Why the user's data could not be read or written. */
|
|
91
|
+
export type DTVAnalyticsUserDataError = {
|
|
92
|
+
readonly kind: 'externalLoadFailed' | 'externalSaveFailed' | 'localStorageFailed';
|
|
93
|
+
readonly message: string;
|
|
94
|
+
};
|
|
95
|
+
export type DTVAnalyticsEventPayload =
|
|
96
|
+
/**
|
|
97
|
+
* The page session started: reported once per session, as the first event of the table that
|
|
98
|
+
* reports one first.
|
|
99
|
+
*/
|
|
100
|
+
{
|
|
101
|
+
readonly type: 'sessionStarted';
|
|
102
|
+
readonly dtvVersion: string;
|
|
103
|
+
}
|
|
104
|
+
/** The table mounted. */
|
|
105
|
+
| {
|
|
106
|
+
readonly type: 'viewMounted';
|
|
107
|
+
readonly popout: boolean;
|
|
108
|
+
}
|
|
109
|
+
/** The table unmounted. Spans still running end after it, as aborted. */
|
|
110
|
+
| {
|
|
111
|
+
readonly type: 'viewUnmounted';
|
|
112
|
+
}
|
|
113
|
+
/** The user switched views; `viewId` is the new one. */
|
|
114
|
+
| {
|
|
115
|
+
readonly type: 'viewSelected';
|
|
116
|
+
readonly previousViewId: ViewId;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Filters were applied, and rows are requested for them. `filters` is the state as user
|
|
120
|
+
* data stores it: empty filters left out. Every `fetch` names the apply its filters come
|
|
121
|
+
* from (`filtersSeq`).
|
|
122
|
+
*/
|
|
123
|
+
| {
|
|
124
|
+
readonly type: 'filtersApplied';
|
|
125
|
+
readonly trigger: FiltersAppliedTrigger;
|
|
126
|
+
readonly filters: UndecodedFilterState;
|
|
127
|
+
/** The saved filter applied, for `trigger: 'savedFilter'`. */
|
|
128
|
+
readonly savedFilter?: {
|
|
129
|
+
readonly id: string;
|
|
130
|
+
readonly name: string;
|
|
131
|
+
};
|
|
132
|
+
/** The AI filter assistant filled the draft since filters were last applied. */
|
|
133
|
+
readonly aiAssisted: boolean;
|
|
134
|
+
/** For `trigger: 'link'` and `'url'`: the revision of the definition the link was made for. */
|
|
135
|
+
readonly link?: {
|
|
136
|
+
readonly definitionRevision: number;
|
|
137
|
+
};
|
|
138
|
+
} | {
|
|
139
|
+
readonly type: 'orderingChanged';
|
|
140
|
+
readonly ordering: DataOrdering | null;
|
|
141
|
+
} | {
|
|
142
|
+
readonly type: 'rowsPerPageChanged';
|
|
143
|
+
readonly rowsPerPage: number;
|
|
144
|
+
} | {
|
|
145
|
+
readonly type: 'hiddenColumnsChanged';
|
|
146
|
+
readonly hiddenColumns: readonly string[];
|
|
147
|
+
} | {
|
|
148
|
+
readonly type: 'panelShown';
|
|
149
|
+
readonly panel: DTVAnalyticsPanel;
|
|
150
|
+
readonly shown: boolean;
|
|
151
|
+
}
|
|
152
|
+
/** The user searched the view's filters; reported once typing pauses. */
|
|
153
|
+
| {
|
|
154
|
+
readonly type: 'filterSearch';
|
|
155
|
+
readonly query: string;
|
|
156
|
+
} | {
|
|
157
|
+
readonly type: 'savedFilterSaved';
|
|
158
|
+
readonly savedFilterId: string;
|
|
159
|
+
readonly name: string;
|
|
160
|
+
readonly created: boolean;
|
|
161
|
+
readonly filters: UndecodedFilterState;
|
|
162
|
+
} | {
|
|
163
|
+
readonly type: 'savedFilterDeleted';
|
|
164
|
+
readonly savedFilterId: string;
|
|
165
|
+
} | {
|
|
166
|
+
readonly type: 'shareLinkCreated';
|
|
167
|
+
readonly from: 'filterForm' | 'savedFilter';
|
|
168
|
+
} | {
|
|
169
|
+
readonly type: 'rowExpansionToggled';
|
|
170
|
+
readonly expanded: boolean;
|
|
171
|
+
}
|
|
172
|
+
/** A request for rows ended. */
|
|
173
|
+
| (DTVAnalyticsSpan & {
|
|
174
|
+
readonly type: 'fetch';
|
|
175
|
+
readonly reason: FetchReason;
|
|
176
|
+
/** The page index: 0 for the first page. */
|
|
177
|
+
readonly page: number;
|
|
178
|
+
readonly rowsPerPage: number;
|
|
179
|
+
readonly ordering: DataOrdering | null;
|
|
180
|
+
/** The `seq` of the `filtersApplied` event the request's filters come from. */
|
|
181
|
+
readonly filtersSeq: number | null;
|
|
182
|
+
/** `aborted`: superseded by another request, or the table unmounted. */
|
|
183
|
+
readonly outcome: 'succeeded' | 'failed' | 'aborted';
|
|
184
|
+
readonly rowCount?: number;
|
|
185
|
+
/** A full page arrived, so there may be a next one. */
|
|
186
|
+
readonly hasMore?: boolean;
|
|
187
|
+
readonly error?: FetchErrorInfo;
|
|
188
|
+
})
|
|
189
|
+
/**
|
|
190
|
+
* The user's data was loaded and read, migrations to the views' current revisions
|
|
191
|
+
* included. `failed`: the host's loader failed, and the table goes on with the local copy.
|
|
192
|
+
*/
|
|
193
|
+
| (DTVAnalyticsSpan & {
|
|
194
|
+
readonly type: 'userDataLoad';
|
|
195
|
+
readonly outcome: 'succeeded' | 'failed';
|
|
196
|
+
readonly source: 'remote' | 'local';
|
|
197
|
+
/** Migrations changed what is stored. */
|
|
198
|
+
readonly migrated: boolean;
|
|
199
|
+
readonly resets: readonly DTVAnalyticsResets[];
|
|
200
|
+
readonly retainedViews: readonly DTVAnalyticsRetainedView[];
|
|
201
|
+
readonly error?: DTVAnalyticsUserDataError;
|
|
202
|
+
}) | (DTVAnalyticsSpan & {
|
|
203
|
+
readonly type: 'action';
|
|
204
|
+
/** The action's `id`, or its label. */
|
|
205
|
+
readonly action: string;
|
|
206
|
+
readonly selectedRows: number;
|
|
207
|
+
readonly outcome: 'succeeded' | 'failed';
|
|
208
|
+
readonly error?: DTVAnalyticsError;
|
|
209
|
+
})
|
|
210
|
+
/** The data of a lazily expanded row was loaded. */
|
|
211
|
+
| (DTVAnalyticsSpan & {
|
|
212
|
+
readonly type: 'rowExpansionLoad';
|
|
213
|
+
readonly outcome: 'succeeded' | 'failed';
|
|
214
|
+
readonly error?: DTVAnalyticsError;
|
|
215
|
+
})
|
|
216
|
+
/** The AI filter assistant was asked to fill the filters. */
|
|
217
|
+
| (DTVAnalyticsSpan & {
|
|
218
|
+
readonly type: 'aiFilter';
|
|
219
|
+
readonly prompt: string;
|
|
220
|
+
readonly outcome: 'succeeded' | 'failed';
|
|
221
|
+
readonly error?: DTVAnalyticsError;
|
|
222
|
+
})
|
|
223
|
+
/** Writing the user's data failed. The change is kept locally. */
|
|
224
|
+
| {
|
|
225
|
+
readonly type: 'userDataSaveFailed';
|
|
226
|
+
readonly error: DTVAnalyticsUserDataError;
|
|
227
|
+
}
|
|
228
|
+
/** The host rejected a write because another tab or device wrote first; it is applied on top of theirs. */
|
|
229
|
+
| {
|
|
230
|
+
readonly type: 'userDataConflict';
|
|
231
|
+
readonly resolved: boolean;
|
|
232
|
+
}
|
|
233
|
+
/** The stored user data is in a format this version cannot read: changes are not saved. */
|
|
234
|
+
| {
|
|
235
|
+
readonly type: 'userDataReadOnly';
|
|
236
|
+
readonly message: string;
|
|
237
|
+
}
|
|
238
|
+
/**
|
|
239
|
+
* The view's filters differ from its latest snapshot: `dtv definitions snapshot` was not
|
|
240
|
+
* run for a change. The stored state of the `changed` ones is reset.
|
|
241
|
+
*/
|
|
242
|
+
| {
|
|
243
|
+
readonly type: 'filtersChangedSinceSnapshot';
|
|
244
|
+
readonly changed: readonly FilterId[];
|
|
245
|
+
readonly added: readonly FilterId[];
|
|
246
|
+
readonly removed: readonly FilterId[];
|
|
247
|
+
}
|
|
248
|
+
/** A filter's suggestion fetcher failed. */
|
|
249
|
+
| {
|
|
250
|
+
readonly type: 'suggestionsFailed';
|
|
251
|
+
readonly error: DTVAnalyticsError;
|
|
252
|
+
};
|
|
253
|
+
/** An event a table reports. Narrow it by `type`. */
|
|
254
|
+
export type DTVAnalyticsEvent = DTVAnalyticsEventBase & DTVAnalyticsEventPayload;
|
|
255
|
+
export type DTVAnalyticsEventType = DTVAnalyticsEvent['type'];
|
|
256
|
+
export interface DTVAnalytics {
|
|
257
|
+
/**
|
|
258
|
+
* Receives each event, synchronously, as it happens. Keep it cheap: queue the event and
|
|
259
|
+
* send batches. What it throws is logged and otherwise ignored.
|
|
260
|
+
*/
|
|
261
|
+
onEvent: (event: DTVAnalyticsEvent) => void;
|
|
262
|
+
}
|
|
263
|
+
/**
|
|
264
|
+
* The events the table's components and its user data manager report; the state stamps them
|
|
265
|
+
* with the selected view. The others come from transitions and the interpreter.
|
|
266
|
+
*/
|
|
267
|
+
export type ReportedEvent = Extract<DTVAnalyticsEventPayload, {
|
|
268
|
+
readonly type: 'hiddenColumnsChanged' | 'savedFilterSaved' | 'savedFilterDeleted' | 'shareLinkCreated' | 'rowExpansionToggled' | 'action' | 'rowExpansionLoad' | 'aiFilter' | 'suggestionsFailed' | 'userDataLoad' | 'userDataSaveFailed' | 'userDataConflict' | 'userDataReadOnly';
|
|
269
|
+
}>;
|
|
270
|
+
export declare function analyticsError(error: unknown): DTVAnalyticsError;
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/** What kind of failure a `FetchError` is. */
|
|
2
|
+
export type FetchErrorKind =
|
|
3
|
+
/** The database cancelled the query, e.g. on its statement timeout, or a gateway timed out. */
|
|
4
|
+
'timeout'
|
|
5
|
+
/** HTTP 401 or 403, or the API rejected the token or the role. */
|
|
6
|
+
| 'unauthorized'
|
|
7
|
+
/** The response carried GraphQL errors, e.g. a field the role may not read. */
|
|
8
|
+
| 'graphql'
|
|
9
|
+
/** An HTTP status other than success, without GraphQL errors. */
|
|
10
|
+
| 'http'
|
|
11
|
+
/** No response arrived: offline, DNS, CORS, a dropped connection. */
|
|
12
|
+
| 'network'
|
|
13
|
+
/** A response without the view's root field. */
|
|
14
|
+
| 'unexpectedResponse'
|
|
15
|
+
/** Anything else, e.g. building the query's variables or flattening the rows threw. */
|
|
16
|
+
| 'internal';
|
|
17
|
+
export type FetchErrorInfo = {
|
|
18
|
+
readonly kind: FetchErrorKind;
|
|
19
|
+
readonly message: string;
|
|
20
|
+
/** The HTTP status, when a response arrived. */
|
|
21
|
+
readonly status?: number;
|
|
22
|
+
/** The `extensions.code` of each GraphQL error, e.g. `validation-failed` or `invalid-jwt` from Hasura. */
|
|
23
|
+
readonly codes?: readonly string[];
|
|
24
|
+
};
|
|
25
|
+
/** A failed request for a table's rows. Aborted requests reject with an AbortError instead. */
|
|
26
|
+
export declare class FetchError extends Error {
|
|
27
|
+
readonly info: FetchErrorInfo;
|
|
28
|
+
/** The error the failure was told from. */
|
|
29
|
+
readonly cause: unknown;
|
|
30
|
+
constructor(info: FetchErrorInfo, options?: {
|
|
31
|
+
cause?: unknown;
|
|
32
|
+
});
|
|
33
|
+
}
|
|
34
|
+
/** Tells what kind of failure an error the GraphQL client raised is. */
|
|
35
|
+
export declare function fetchErrorFromClientError(error: unknown): FetchError;
|
|
@@ -10,13 +10,17 @@ export type SharedFilterState = {
|
|
|
10
10
|
view: ViewId | null;
|
|
11
11
|
definitionRevision: number;
|
|
12
12
|
state: UndecodedFilterState;
|
|
13
|
+
/** Written by the table itself, keeping its URL in sync (`syncFilterStateToUrl`), not shared. */
|
|
14
|
+
synced: boolean;
|
|
13
15
|
};
|
|
14
16
|
/**
|
|
15
17
|
* Encode a view's filter state to a base64 URL-safe string
|
|
16
18
|
*/
|
|
17
19
|
/** What sharing needs of a view. */
|
|
18
20
|
export type SharedView = Pick<View, 'id' | 'filterGroups' | 'migrations'>;
|
|
19
|
-
export declare function encodeSharedFilterState(view: SharedView, filterState: FilterState
|
|
21
|
+
export declare function encodeSharedFilterState(view: SharedView, filterState: FilterState, options?: {
|
|
22
|
+
synced?: boolean;
|
|
23
|
+
}): string;
|
|
20
24
|
/**
|
|
21
25
|
* Decode a filter state from a base64 URL-safe string. Throws when it is not one.
|
|
22
26
|
*/
|
|
@@ -1,7 +1,10 @@
|
|
|
1
|
+
import type { DTVAnalyticsEventPayload, FiltersAppliedTrigger, ReportedEvent } from '../analytics';
|
|
2
|
+
import type { ViewDefinition } from '../analytics-emitter';
|
|
1
3
|
import type { FetchDataResult } from '../data';
|
|
2
4
|
import { type DataOrdering } from '../data-ordering';
|
|
3
5
|
import { type FilterDisplayState } from '../filter-display-state';
|
|
4
6
|
import type { FilterGroups } from '../filters';
|
|
7
|
+
import { type SnapshotDiff } from '../view-migrations';
|
|
5
8
|
import type { ViewId } from '../view';
|
|
6
9
|
import { type FilterState } from './filter-state';
|
|
7
10
|
import { type RequestId, type TableState } from './table';
|
|
@@ -37,6 +40,10 @@ export interface AppState {
|
|
|
37
40
|
readonly showPopout: boolean;
|
|
38
41
|
/** The rows the user selected, flattened; empty when row selection is off. */
|
|
39
42
|
readonly selectedRows: readonly unknown[];
|
|
43
|
+
/** The AI filter assistant filled the draft since filters were last applied. */
|
|
44
|
+
readonly aiAssistedDraft: boolean;
|
|
45
|
+
/** Where the filter state the table opened with came from, until the view settles. */
|
|
46
|
+
readonly initialFilterStateSource: AppStateInit['initialFilterStateSource'] | null;
|
|
40
47
|
}
|
|
41
48
|
/** What `updateAppState` reads but does not own. */
|
|
42
49
|
export interface AppStateEnv {
|
|
@@ -45,7 +52,18 @@ export interface AppStateEnv {
|
|
|
45
52
|
readonly rowsPerPageOptions: readonly number[];
|
|
46
53
|
/** The fields a view's rows can be ordered by. */
|
|
47
54
|
readonly orderableFields: (viewId: ViewId) => readonly string[];
|
|
55
|
+
/** The definition a view's analytics events are reported for. */
|
|
56
|
+
readonly definition: (viewId: ViewId) => ViewDefinition;
|
|
57
|
+
/** How a view's filters differ from its latest definition snapshot; `null` without migrations. */
|
|
58
|
+
readonly snapshotDiff: (viewId: ViewId) => SnapshotDiff | null;
|
|
48
59
|
}
|
|
60
|
+
/** What applies filters by a message. The table opening with filters is told by the state. */
|
|
61
|
+
export type ApplyTrigger = Extract<FiltersAppliedTrigger, 'submit' | 'reset' | 'pillRemoved' | 'savedFilter' | 'api'>;
|
|
62
|
+
/** A saved filter, as applying it is reported. */
|
|
63
|
+
export type SavedFilterRef = {
|
|
64
|
+
readonly id: string;
|
|
65
|
+
readonly name: string;
|
|
66
|
+
};
|
|
49
67
|
export type Msg =
|
|
50
68
|
/** User data of `viewId` changed: written here, by another tab, or loaded. */
|
|
51
69
|
{
|
|
@@ -55,18 +73,27 @@ export type Msg =
|
|
|
55
73
|
} | {
|
|
56
74
|
readonly tag: 'viewSelected';
|
|
57
75
|
readonly viewId: ViewId;
|
|
58
|
-
}
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* The draft changed: edited, unless `by` says it was filled by the AI filter assistant or
|
|
79
|
+
* replaced by a saved filter.
|
|
80
|
+
*/
|
|
81
|
+
| {
|
|
59
82
|
readonly tag: 'draftChanged';
|
|
60
83
|
readonly filters: FilterState;
|
|
84
|
+
readonly by?: 'aiAssistant' | 'savedFilter';
|
|
61
85
|
}
|
|
62
86
|
/** Apply the draft as it is when this message is handled. */
|
|
63
87
|
| {
|
|
64
88
|
readonly tag: 'draftApplied';
|
|
89
|
+
readonly trigger: Extract<ApplyTrigger, 'submit' | 'reset' | 'api'>;
|
|
65
90
|
}
|
|
66
91
|
/** Apply `filters`, leaving the draft as it is. */
|
|
67
92
|
| {
|
|
68
93
|
readonly tag: 'filtersApplied';
|
|
69
94
|
readonly filters: FilterState;
|
|
95
|
+
readonly trigger: ApplyTrigger;
|
|
96
|
+
readonly savedFilter?: SavedFilterRef;
|
|
70
97
|
} | {
|
|
71
98
|
readonly tag: 'searchQueryChanged';
|
|
72
99
|
readonly searchQuery: string;
|
|
@@ -108,6 +135,16 @@ export type Msg =
|
|
|
108
135
|
} | {
|
|
109
136
|
readonly tag: 'rowsSelected';
|
|
110
137
|
readonly rows: readonly unknown[];
|
|
138
|
+
}
|
|
139
|
+
/** A component or the user data reported an analytics event, of the selected view. */
|
|
140
|
+
| {
|
|
141
|
+
readonly tag: 'reported';
|
|
142
|
+
readonly event: ReportedEvent;
|
|
143
|
+
};
|
|
144
|
+
/** Reports the latest of the events of `key` once `ms` passed without another one. */
|
|
145
|
+
export type Debounce = {
|
|
146
|
+
readonly key: string;
|
|
147
|
+
readonly ms: number;
|
|
111
148
|
};
|
|
112
149
|
export type Command = {
|
|
113
150
|
readonly tag: 'persistFilterState';
|
|
@@ -121,13 +158,34 @@ export type Command = {
|
|
|
121
158
|
readonly tag: 'persistOrdering';
|
|
122
159
|
readonly viewId: ViewId;
|
|
123
160
|
readonly ordering: DataOrdering | null;
|
|
161
|
+
}
|
|
162
|
+
/** Report `event` as an analytics event of `viewId`. */
|
|
163
|
+
| {
|
|
164
|
+
readonly tag: 'track';
|
|
165
|
+
readonly viewId: ViewId;
|
|
166
|
+
readonly event: DTVAnalyticsEventPayload;
|
|
167
|
+
readonly debounce?: Debounce;
|
|
168
|
+
}
|
|
169
|
+
/** Drop the event of `key` waiting for a pause. */
|
|
170
|
+
| {
|
|
171
|
+
readonly tag: 'cancelTrack';
|
|
172
|
+
readonly key: string;
|
|
124
173
|
};
|
|
125
174
|
export interface AppStateInit {
|
|
126
175
|
readonly viewId: ViewId;
|
|
127
176
|
readonly rowsPerPage: number;
|
|
128
177
|
/** A filter state the page was opened with, e.g. a shared link. It wins over a persisted one. */
|
|
129
178
|
readonly initialFilterState?: FilterState;
|
|
179
|
+
/** Where `initialFilterState` came from, and the revision of the view's definition it was written for. */
|
|
180
|
+
readonly initialFilterStateSource?: {
|
|
181
|
+
readonly trigger: 'link' | 'url';
|
|
182
|
+
readonly definitionRevision: number;
|
|
183
|
+
};
|
|
184
|
+
/** The table is the popout of another one. */
|
|
185
|
+
readonly popout?: boolean;
|
|
130
186
|
}
|
|
131
187
|
/** A table that waits for the user data of its view: it starts with a `userDataChanged`. */
|
|
132
188
|
export declare function initAppState(env: AppStateEnv, init: AppStateInit): AppState;
|
|
189
|
+
/** What a table does as it mounts, before any message: it reports that it did. */
|
|
190
|
+
export declare function initialCommands(env: AppStateEnv, init: AppStateInit): Command[];
|
|
133
191
|
export declare function updateAppState(env: AppStateEnv, state: AppState, msg: Msg): [AppState, Command[]];
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { FetchReason } from '../analytics';
|
|
1
2
|
import type { FetchDataResult, PaginationCursor } from '../data';
|
|
2
3
|
import type { DataOrdering } from '../data-ordering';
|
|
3
4
|
import type { ViewId } from '../view';
|
|
@@ -22,6 +23,8 @@ export interface Query {
|
|
|
22
23
|
export interface DataRequest {
|
|
23
24
|
readonly id: RequestId;
|
|
24
25
|
readonly query: Query;
|
|
26
|
+
/** What made the table ask for the rows. Reported, not acted on. */
|
|
27
|
+
readonly reason: FetchReason;
|
|
25
28
|
}
|
|
26
29
|
/** Rows and the query they answer. */
|
|
27
30
|
export interface Page {
|
|
@@ -1,15 +1,27 @@
|
|
|
1
|
+
import type { DTVAnalyticsEvent, ReportedEvent } from '../analytics';
|
|
1
2
|
import type { FetchDataResult } from '../data';
|
|
2
3
|
import { type AppState, type AppStateEnv, type AppStateInit, type Command, type Msg } from './app-state';
|
|
3
|
-
import { type
|
|
4
|
+
import { type DataRequest } from './table';
|
|
5
|
+
/** A command the host carries out. Analytics events (`track`, `cancelTrack`) are the interpreter's. */
|
|
6
|
+
export type HostCommand = Exclude<Command, {
|
|
7
|
+
tag: 'track' | 'cancelTrack';
|
|
8
|
+
}>;
|
|
4
9
|
/** How the effects of the app state are carried out. */
|
|
5
10
|
export interface AppStateEffects {
|
|
6
|
-
/** Fetches the rows `
|
|
7
|
-
readonly fetchRows: (
|
|
8
|
-
readonly runCommand: (command:
|
|
11
|
+
/** Fetches the rows `request` asks for. Rejects with an AbortError once `signal` aborts. */
|
|
12
|
+
readonly fetchRows: (request: DataRequest, signal: AbortSignal) => Promise<FetchDataResult>;
|
|
13
|
+
readonly runCommand: (command: HostCommand) => void;
|
|
14
|
+
/** Receives the table's analytics events. */
|
|
15
|
+
readonly onEvent?: (event: DTVAnalyticsEvent) => void;
|
|
9
16
|
}
|
|
10
17
|
/**
|
|
11
18
|
* Holds the state of a table and runs the effects it asks for. The pending request is
|
|
12
19
|
* fetched, and aborted once another one supersedes it or none is wanted any more, unmounting
|
|
13
|
-
* included. Commands run once each, in order
|
|
20
|
+
* included. Commands run once each, in order, and before the request their transition
|
|
21
|
+
* started: the `filtersApplied` event a request's filters come from is reported before it.
|
|
22
|
+
*
|
|
23
|
+
* Returns `report` besides the state and `dispatch`: it reports an event of the selected
|
|
24
|
+
* view at any time. While the table is mounted it is a message like any other; before, the
|
|
25
|
+
* event waits for it to mount, and after, it is reported at once.
|
|
14
26
|
*/
|
|
15
|
-
export declare function useAppState(env: AppStateEnv, init: AppStateInit, effects: AppStateEffects): [AppState, (msg: Msg) => void];
|
|
27
|
+
export declare function useAppState(env: AppStateEnv, init: AppStateInit, effects: AppStateEffects): [AppState, (msg: Msg) => void, (event: ReportedEvent) => void];
|
|
@@ -3,9 +3,11 @@ import type { SavedFilter, SavedFilterId } from './saved-filters';
|
|
|
3
3
|
import type { FilterState } from './state';
|
|
4
4
|
import type { DataOrdering } from './data-ordering';
|
|
5
5
|
import type { UserPreferences } from './user-data';
|
|
6
|
-
import { type UserDataManagerOptions } from './user-data-manager';
|
|
6
|
+
import { type UserDataAnalyticsEvent, type UserDataManagerOptions } from './user-data-manager';
|
|
7
7
|
import type { ViewId } from './view';
|
|
8
|
-
export declare function useUserDataManager(filterGroupsByViewId: Record<ViewId, FilterGroups>, currentViewId: ViewId, options: UserDataManagerOptions
|
|
8
|
+
export declare function useUserDataManager(filterGroupsByViewId: Record<ViewId, FilterGroups>, currentViewId: ViewId, options: UserDataManagerOptions,
|
|
9
|
+
/** Receives the analytics events of the manager in use. */
|
|
10
|
+
track?: (event: UserDataAnalyticsEvent) => void): {
|
|
9
11
|
isReady: boolean;
|
|
10
12
|
preferences: UserPreferences;
|
|
11
13
|
viewData: import("./user-data").ViewData;
|
|
@@ -18,7 +20,7 @@ export declare function useUserDataManager(filterGroupsByViewId: Record<ViewId,
|
|
|
18
20
|
setOrdering: (viewId: ViewId, ordering: DataOrdering | null) => Promise<import("./user-data").ViewData>;
|
|
19
21
|
setSyncFilterStateToUserData: (viewId: ViewId, enabled: boolean) => Promise<import("./user-data").ViewData>;
|
|
20
22
|
setPersistedFilterState: (viewId: ViewId, filterState: FilterState | null) => Promise<import("./user-data").ViewData>;
|
|
21
|
-
createFilter: (filter: Omit<SavedFilter, "id" | "createdAt" | "formatRevision">) => Promise<
|
|
22
|
-
updateFilter: (viewId: ViewId, savedFilterId: SavedFilterId, updates: Partial<Pick<SavedFilter, "name" | "state">>) => Promise<
|
|
23
|
-
deleteFilter: (viewId: ViewId, savedFilterId: SavedFilterId) => Promise<
|
|
23
|
+
createFilter: (filter: Omit<SavedFilter, "id" | "createdAt" | "formatRevision">) => Promise<SavedFilter>;
|
|
24
|
+
updateFilter: (viewId: ViewId, savedFilterId: SavedFilterId, updates: Partial<Pick<SavedFilter, "name" | "state">>) => Promise<boolean>;
|
|
25
|
+
deleteFilter: (viewId: ViewId, savedFilterId: SavedFilterId) => Promise<boolean>;
|
|
24
26
|
};
|