@kronor/dtv 10.1.1 → 12.0.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.
@@ -32,6 +32,9 @@ export interface AppProps<V extends View = View> {
32
32
  /**
33
33
  * Optional already-parsed views.
34
34
  * When provided, `viewsJson` is ignored and no JSON parsing occurs.
35
+ * When the selected view's source, function arguments, `staticConditions` or
36
+ * `staticOrdering` change, its first page is asked for again and the row selection is
37
+ * cleared; filters, ordering and rows per page stay.
35
38
  */
36
39
  views?: V[];
37
40
  /** JSON string containing array of view definitions (required if `views` is not provided). */
@@ -92,6 +95,13 @@ export type DTVAPI = {
92
95
  collapseAll: () => void;
93
96
  expandAll: () => void;
94
97
  };
98
+ /**
99
+ * Runs the action of `actions` with this `id` as a click on its button would: the button
100
+ * shows it running, a run while it is running or disabled does nothing, and it reports the
101
+ * same analytics and failure toast. For a host that starts an action from a control of its
102
+ * own, e.g. with the toolbar hidden. Does nothing, with a warning, for an id no action has.
103
+ */
104
+ runAction: (id: string) => void;
95
105
  };
96
106
  declare function App<V extends View = View>({ graphqlHost, requestHeaders, aiIntegration, showViewsMenu, showViewTitle, showCsvExportButton, showPopoutButton, views: viewsFromProps, viewsJson, externalRuntime, isOverlay, onCloseOverlay, syncFilterStateToUrl, rowSelection, actions, rowClassFunction, rowsPerPageOptions, userData, analytics, modifyAiFilterPrompt, apiRef }: AppProps<V>): import("react/jsx-runtime").JSX.Element;
97
107
  export default App;
@@ -1,21 +1,9 @@
1
- import { ActionDefinition, ActionUserDataAPI } from '../framework/actions';
2
- import { View } from '../framework/view';
3
- import type { ShowToastFn } from '../framework/toast';
4
- import { FilterState, PaginationState } from '../framework/state';
5
- import type { DataOrdering } from '../framework/data-ordering';
1
+ import type { ActionDefinition } from '../framework/actions';
6
2
  export interface ActionButtonsProps {
7
3
  actions: ActionDefinition[];
8
- selectedView: View;
9
- filterState: FilterState;
10
- selectedRows: readonly unknown[];
11
- setFilterState: (next: FilterState) => void;
12
- refetch: () => void;
13
- applyFilters: () => void;
14
- showToast: ShowToastFn;
15
- paginationState: PaginationState;
16
- rowsPerPage: number;
17
- ordering: DataOrdering | null;
18
- userData: ActionUserDataAPI;
4
+ /** Whether the action with this id is running: its button shows it, and cannot be clicked. */
5
+ isRunning: (id: string) => boolean;
6
+ onClick: (id: string) => void;
19
7
  }
20
- export declare function ActionButtons({ actions, selectedView, filterState, selectedRows, setFilterState, refetch, applyFilters, showToast, paginationState, rowsPerPage, ordering, userData }: ActionButtonsProps): import("react/jsx-runtime").JSX.Element;
8
+ export declare function ActionButtons({ actions, isRunning, onClick }: ActionButtonsProps): import("react/jsx-runtime").JSX.Element;
21
9
  export default ActionButtons;
@@ -5,7 +5,6 @@ import { NoRowsComponent, RowExpansionDefinition, type SimplifiedRow } from '../
5
5
  import { FilterState } from '../framework/state';
6
6
  import { type FlattenedDataRow } from '../framework/data';
7
7
  import type { DataOrdering } from '../framework/data-ordering';
8
- export type RowSelectionResetFn = () => void;
9
8
  export type RowExpansionApi = {
10
9
  reset: () => void;
11
10
  collapseAll: () => void;
@@ -29,16 +28,15 @@ type TableProps<Row> = {
29
28
  filterState: FilterState;
30
29
  applyFilters: () => void;
31
30
  ref?: React.Ref<DataTable<any>>;
32
- rowSelection?: {
33
- rowSelectionType: 'none' | 'multiple';
34
- onRowSelectionChange?: (rows: Row[]) => void;
35
- };
36
- /** Optional callback invoked when row selection reset becomes available/unavailable. */
37
- onRowSelectionResetChange?: (resetFn: RowSelectionResetFn | null) => void;
31
+ /** 'none' disables selection UI. 'multiple' enables checkbox multi-select. */
32
+ rowSelectionType: 'none' | 'multiple';
33
+ /** The rows selected, as this table handed them to `onSelectedRowsChange`. */
34
+ selectedRows: readonly unknown[];
35
+ onSelectedRowsChange?: (rows: FlattenedDataRow[]) => void;
38
36
  onRowExpansionApiChange?: (api: RowExpansionApi | null) => void;
39
37
  rowClassFunction?: (row: Row) => Record<string, boolean>;
40
38
  ordering?: DataOrdering | null;
41
39
  onOrderingChange?: (ordering: DataOrdering | null) => void;
42
40
  };
43
- declare function Table<Row extends object = SimplifiedRow>({ viewId, columns, hiddenColumnIds, paginationKey, data, rawRows, rowExpansion, loadLazyRowExpansionData, noRowsComponent, setFilterState, filterState, applyFilters, ref, rowSelection, rowClassFunction, onRowSelectionResetChange, onRowExpansionApiChange, ordering, onOrderingChange }: TableProps<Row>): import("react/jsx-runtime").JSX.Element;
41
+ declare function Table<Row extends object = SimplifiedRow>({ viewId, columns, hiddenColumnIds, paginationKey, data, rawRows, rowExpansion, loadLazyRowExpansionData, noRowsComponent, setFilterState, filterState, applyFilters, ref, rowSelectionType: selectionType, selectedRows, onSelectedRowsChange, rowClassFunction, onRowExpansionApiChange, ordering, onOrderingChange }: TableProps<Row>): import("react/jsx-runtime").JSX.Element;
44
42
  export default Table;
@@ -3,8 +3,7 @@ import type { FilterState } from './state';
3
3
  import type { DataOrdering } from './data-ordering';
4
4
  import { generateGraphQLQueryAST, renderGraphQLQuery } from './graphql';
5
5
  import { generateColumnAliasedGraphQLQueryAST } from './graphql/query';
6
- import { buildGraphQLQueryVariables } from './data';
7
- import type { PaginationState } from './state';
6
+ import { buildGraphQLQueryVariables, type PaginationCursor } from './data';
8
7
  import type { ShowToastFn } from './toast';
9
8
  import type { UserPreferences, ViewData } from './user-data';
10
9
  import type { CSSProperties } from 'react';
@@ -12,6 +11,33 @@ export interface ActionUserDataAPI {
12
11
  preferences: UserPreferences;
13
12
  viewData: ViewData;
14
13
  }
14
+ /**
15
+ * The rows on screen, and the query they answer. A request for exactly these rows is built from
16
+ * it alone: `buildGraphQLQueryVariables(view, filterState, rowsPerPage, cursors.at(-1) ?? null,
17
+ * ordering)` for the variables, and `getViewStaticArgs(view)` for the document's arguments.
18
+ */
19
+ export interface ShownRows {
20
+ /**
21
+ * The view as these rows were read: with the source, function arguments, static conditions
22
+ * and static ordering they were asked for with, which the host may have changed since.
23
+ */
24
+ view: View;
25
+ /** The filters these rows were asked for with: the applied ones, not the draft `ActionAPI.filterState`. */
26
+ filterState: FilterState;
27
+ /**
28
+ * The ordering the user picked by sorting a column, or `null` when they have not sorted
29
+ * anything. `field` is the GraphQL field path the column sorts by — dotted for nested
30
+ * columns, e.g. `customer.profile.status` — not the column id. The view's `staticOrdering`
31
+ * trails it as a tie-breaker, and stands alone when this is `null`.
32
+ */
33
+ ordering: DataOrdering | null;
34
+ rowsPerPage: number;
35
+ /**
36
+ * Where each page up to this one starts: the last one is this page's cursor, and the length
37
+ * is its page index, 0 for the first page.
38
+ */
39
+ cursors: NonNullable<PaginationCursor>[];
40
+ }
15
41
  export interface ActionAPI {
16
42
  view: View;
17
43
  filterState: FilterState;
@@ -38,20 +64,8 @@ export interface ActionAPI {
38
64
  */
39
65
  applyFilters: () => void;
40
66
  showToast: ShowToastFn;
41
- /** Current rows-per-page setting for pagination. */
42
- rowsPerPage: number;
43
- /**
44
- * The ordering the table is currently showing: the ordering the user picked by
45
- * sorting a column, or `null` when they have not sorted anything. `field` is the
46
- * GraphQL field path the column sorts by — dotted for nested columns, e.g.
47
- * `customer.profile.status` — not the column id.
48
- *
49
- * Pass it to `buildGraphQLQueryVariables` as its `ordering` argument to build
50
- * variables that order and paginate exactly like the table on screen. The view's
51
- * `staticOrdering` is applied either way — it trails this ordering as a
52
- * tie-breaker, and stands alone when this is `null`.
53
- */
54
- ordering: DataOrdering | null;
67
+ /** The rows on screen and the query they answer; `null` until rows were shown. */
68
+ shownRows: ShownRows | null;
55
69
  /** Build a GraphQLQueryAST for an arbitrary rootField (usually the current view root field). */
56
70
  generateGraphQLQueryAST: typeof generateGraphQLQueryAST;
57
71
  /**
@@ -64,15 +78,16 @@ export interface ActionAPI {
64
78
  renderGraphQLQuery: typeof renderGraphQLQuery;
65
79
  /** Build GraphQL variables (conditions, paginationCondition, orderBy, rowLimit) for the current view. */
66
80
  buildGraphQLQueryVariables: typeof buildGraphQLQueryVariables;
67
- /** Access current pagination state (page number and cursor history). */
68
- getPaginationState: () => PaginationState;
69
81
  /** Access persisted user data for the current view. */
70
82
  userData: ActionUserDataAPI;
71
83
  }
72
84
  export interface ActionDefinition {
73
85
  label: string;
74
- /** Names the action in analytics events. Defaults to the label, which may change with wording. */
75
- id?: string;
86
+ /**
87
+ * Identifies the action among the table's actions: `DTVAPI.runAction` finds it by it, and
88
+ * analytics events name it. Unlike the label, it does not change with wording.
89
+ */
90
+ id: string;
76
91
  onClick: (api: ActionAPI) => void | Promise<void>;
77
92
  icon?: string;
78
93
  /** Optional PrimeReact Button badge value. */
@@ -69,7 +69,9 @@ export type FetchReason =
69
69
  /** The host asked for fresh rows, e.g. after a mutation. */
70
70
  | 'refresh'
71
71
  /** The rows per page or ordering changed in the user's data, e.g. in another tab. */
72
- | 'userData';
72
+ | 'userData'
73
+ /** The host changed what the view's rows are read with, e.g. its static conditions. */
74
+ | 'viewQuery';
73
75
  /** A panel below the menu bar, or the popout. */
74
76
  export type DTVAnalyticsPanel = 'filters' | 'savedFilters' | 'preferences' | 'aiAssistant' | 'popout';
75
77
  /** Filters whose stored state was dropped while the user's data was read. */
@@ -201,7 +203,7 @@ export type DTVAnalyticsEventPayload =
201
203
  readonly error?: DTVAnalyticsUserDataError;
202
204
  }) | (DTVAnalyticsSpan & {
203
205
  readonly type: 'action';
204
- /** The action's `id`, or its label. */
206
+ /** The action's `id`. */
205
207
  readonly action: string;
206
208
  readonly selectedRows: number;
207
209
  readonly outcome: 'succeeded' | 'failed';
@@ -1,11 +1,11 @@
1
- import type { DTVAnalyticsEventPayload, FiltersAppliedTrigger, ReportedEvent } from '../analytics';
1
+ import type { DTVAnalyticsError, DTVAnalyticsEventPayload, DTVAnalyticsSpan, FiltersAppliedTrigger, ReportedEvent } from '../analytics';
2
2
  import type { ViewDefinition } from '../analytics-emitter';
3
3
  import type { FetchDataResult } from '../data';
4
4
  import { type DataOrdering } from '../data-ordering';
5
5
  import { type FilterDisplayState } from '../filter-display-state';
6
6
  import type { FilterGroups } from '../filters';
7
7
  import { type SnapshotDiff } from '../view-migrations';
8
- import type { ViewId } from '../view';
8
+ import type { ViewId, ViewQuery } from '../view';
9
9
  import { type FilterState } from './filter-state';
10
10
  import { type RequestId, type TableState } from './table';
11
11
  /** What user data holds for the selected view. */
@@ -38,8 +38,12 @@ export interface AppState {
38
38
  readonly activePanel: Panel | null;
39
39
  readonly showAIAssistant: boolean;
40
40
  readonly showPopout: boolean;
41
- /** The rows the user selected, flattened; empty when row selection is off. */
41
+ /** The rows the user selected, as the table hands them out; empty when row selection is off. */
42
42
  readonly selectedRows: readonly unknown[];
43
+ /** The toolbar actions running, by id, with how many rows were selected when each started. */
44
+ readonly runningActions: ReadonlyMap<string, {
45
+ readonly selectedRows: number;
46
+ }>;
43
47
  /** The AI filter assistant filled the draft since filters were last applied. */
44
48
  readonly aiAssistedDraft: boolean;
45
49
  /** Where the filter state the table opened with came from, until the view settles. */
@@ -56,6 +60,12 @@ export interface AppStateEnv {
56
60
  readonly definition: (viewId: ViewId) => ViewDefinition;
57
61
  /** How a view's filters differ from its latest definition snapshot; `null` without migrations. */
58
62
  readonly snapshotDiff: (viewId: ViewId) => SnapshotDiff | null;
63
+ /** What a view's rows are read with now; `null` for a view the table does not have. */
64
+ readonly viewQuery: (viewId: ViewId) => ViewQuery | null;
65
+ /** The toolbar action with this id; `null` for an id no action has. */
66
+ readonly action: (id: string) => {
67
+ readonly disabled: boolean;
68
+ } | null;
59
69
  }
60
70
  /** What applies filters by a message. The table opening with filters is told by the state. */
61
71
  export type ApplyTrigger = Extract<FiltersAppliedTrigger, 'submit' | 'reset' | 'pillRemoved' | 'savedFilter' | 'api'>;
@@ -115,6 +125,13 @@ export type Msg =
115
125
  /** Refetch the current page, e.g. after a mutation elsewhere. Hydrating, the view fetches once it settles. */
116
126
  | {
117
127
  readonly tag: 'refreshRequested';
128
+ }
129
+ /**
130
+ * The environment changed: the host may have changed what the selected view's rows are read
131
+ * with. Hydrating, the view fetches with it once it settles.
132
+ */
133
+ | {
134
+ readonly tag: 'envChanged';
118
135
  } | {
119
136
  readonly tag: 'rowsArrived';
120
137
  readonly requestId: RequestId;
@@ -136,6 +153,19 @@ export type Msg =
136
153
  readonly tag: 'rowsSelected';
137
154
  readonly rows: readonly unknown[];
138
155
  }
156
+ /** Run the toolbar action with this id: its button was clicked, or the host asked (`DTVAPI.runAction`). */
157
+ | {
158
+ readonly tag: 'actionRequested';
159
+ readonly id: string;
160
+ }
161
+ /** The run of an action ended: its promise settled, or it threw. */
162
+ | {
163
+ readonly tag: 'actionEnded';
164
+ readonly id: string;
165
+ readonly span: DTVAnalyticsSpan;
166
+ readonly outcome: 'succeeded' | 'failed';
167
+ readonly error?: DTVAnalyticsError;
168
+ }
139
169
  /** A component or the user data reported an analytics event, of the selected view. */
140
170
  | {
141
171
  readonly tag: 'reported';
@@ -159,6 +189,20 @@ export type Command = {
159
189
  readonly viewId: ViewId;
160
190
  readonly ordering: DataOrdering | null;
161
191
  }
192
+ /** Tell the host that no row is selected any more: the table cleared the selection itself. */
193
+ | {
194
+ readonly tag: 'notifyRowSelectionCleared';
195
+ }
196
+ /** Call the `onClick` of the action with this id, and send `actionEnded` once it ends. */
197
+ | {
198
+ readonly tag: 'runAction';
199
+ readonly id: string;
200
+ }
201
+ /** Warn the host that it asked to run an action no action has the id of. */
202
+ | {
203
+ readonly tag: 'warnUnknownAction';
204
+ readonly id: string;
205
+ }
162
206
  /** Report `event` as an analytics event of `viewId`. */
163
207
  | {
164
208
  readonly tag: 'track';
@@ -1,7 +1,7 @@
1
1
  import type { FetchReason } from '../analytics';
2
2
  import type { FetchDataResult, PaginationCursor } from '../data';
3
3
  import type { DataOrdering } from '../data-ordering';
4
- import type { ViewId } from '../view';
4
+ import type { ViewId, ViewQuery } from '../view';
5
5
  import type { FilterState } from './filter-state';
6
6
  declare const requestIdBrand: unique symbol;
7
7
  /** Identifies a request. Minted by this module alone, so rows can only answer one it started. */
@@ -13,6 +13,8 @@ export type Cursor = NonNullable<PaginationCursor>;
13
13
  /** Everything the rows of a request depend on. */
14
14
  export interface Query {
15
15
  readonly viewId: ViewId;
16
+ /** What the host had the view read with; `null` for a view the table does not have. */
17
+ readonly viewQuery: ViewQuery | null;
16
18
  readonly filters: FilterState;
17
19
  readonly ordering: DataOrdering | null;
18
20
  readonly rowsPerPage: number;
@@ -59,7 +61,7 @@ export type TableState =
59
61
  readonly tag: 'loaded';
60
62
  readonly page: Page;
61
63
  };
62
- /** Pagination as actions see it (see `ActionAPI.getPaginationState`). */
64
+ /** Pagination of the rows on screen, as the pager shows it. */
63
65
  export interface PaginationState {
64
66
  page: number;
65
67
  cursors: PaginationCursor[];
@@ -134,6 +134,19 @@ type KnownFields<Data> = string extends keyof Data ? Record<string, unknown> : D
134
134
  export type SimplifiedRow<V extends View = View> = V extends View<infer Columns> ? Simplify<UnionToIntersection<ColumnRowData<Columns[number]>>> : never;
135
135
  export declare function getViewRootFieldName(view: View): string;
136
136
  export declare function getViewStaticArgs(view: View): Record<string, unknown> | undefined;
137
+ /**
138
+ * What a view's rows are read with besides what the user picks: its source with the function
139
+ * arguments, its static conditions and its static ordering. The host may change them, e.g. to
140
+ * scope the view to another record.
141
+ */
142
+ export type ViewQuery = Pick<View, 'source' | 'staticConditions' | 'staticOrdering'>;
143
+ export declare function getViewQuery(view: View): ViewQuery;
144
+ /**
145
+ * `view` as it reads its rows with `viewQuery`, the view query a request was made with, which
146
+ * the host may have changed since. The view itself while they are the same, so what is cached
147
+ * for it is used.
148
+ */
149
+ export declare function viewWithQuery(view: View, viewQuery: ViewQuery | null): View;
137
150
  export declare function getAllFilters(filterGroups: FilterGroups): FilterSchema[];
138
151
  export type { ColumnDefinitionJson, ViewJson } from './view-parser';
139
152
  export { parseColumnDefinitionJson, parseViewJson } from './view-parser';
@@ -25,8 +25,12 @@ export { CellRenderer } from '../dsl/cellRenderer';
25
25
  export { FilterTransform } from '../dsl/filterTransform';
26
26
  export { rowType } from '../dsl/columns';
27
27
  export type { UserDataJson } from '../framework/user-data';
28
+ export { decodeUserData } from '../framework/user-data';
29
+ export { CURRENT_USERDATA_FORMAT_REVISION } from '../framework/user-data.migrations';
30
+ export type { UserDataDecodeError, UserDataDecoding } from '../framework/user-data';
31
+ export type { UndecodedViewData, UndecodedSavedFilter, UserDataWithUndecodedViews } from '../framework/user-data-undecoded';
28
32
  export type { UserDataLoadAPI, UserDataSaveAPI, UserDataLoadCallback, UserDataSaveCallback } from '../framework/user-data-manager';
29
- export type { ActionDefinition, ActionAPI, ActionUserDataAPI } from '../framework/actions';
33
+ export type { ActionDefinition, ActionAPI, ActionUserDataAPI, ShownRows } from '../framework/actions';
30
34
  export type { DTVAnalytics, DTVAnalyticsEvent, DTVAnalyticsEventBase, DTVAnalyticsEventPayload, DTVAnalyticsEventType, DTVAnalyticsSpan, DTVAnalyticsError, DTVAnalyticsPanel, DTVAnalyticsResets, DTVAnalyticsRetainedView, DTVAnalyticsUserDataError, FiltersAppliedTrigger, FetchReason } from '../framework/analytics';
31
35
  export type { FetchErrorInfo, FetchErrorKind } from '../framework/fetch-error';
32
36
  export type { HasuraFilterObject, HasuraOperator, HasuraOperatorFor, HasuraComparable, HasuraFilterExpression, GraphQLVariable, HasuraOrderBy, GraphQLSelectionSetItem, GraphQLSelectionSet, GraphQLQueryAST, } from '../framework/graphql';
package/docs/analytics.md CHANGED
@@ -414,12 +414,13 @@ When the stored data is in a format this version cannot read, the table reports
414
414
 
415
415
  #### `action`
416
416
 
417
- An action button's `onClick` ended: its promise settled, or it threw.
417
+ An action's `onClick` ended: its promise settled, or it threw. It was started by a click on its
418
+ button, or by `DTVAPI.runAction`.
418
419
 
419
420
  | Field | Type | |
420
421
  |---|---|---|
421
- | `action` | string | The action's `id`, or its label when it has none. Give actions an `id`: labels change with wording. |
422
- | `selectedRows` | number | The rows selected when it was clicked. |
422
+ | `action` | string | The action's `id`. |
423
+ | `selectedRows` | number | The rows selected when it started. |
423
424
  | `outcome` | `'succeeded'` \| `'failed'` | `failed`: it threw or rejected. |
424
425
  | `error` | [`DTVAnalyticsError`](#dtvanalyticserror), *optional* | When `failed`: what it threw. |
425
426
 
@@ -556,6 +557,7 @@ failed lookup is reported, so one broken fetcher can report once per keystroke.
556
557
  | `nextPage`, `previousPage` | The user paged. |
557
558
  | `refresh` | The app asked for fresh rows (`DTVAPI.fetchData`, an action's `refetch`), e.g. after a mutation. |
558
559
  | `userData` | The rows per page or the sorting changed in the user's data, e.g. in another tab. |
560
+ | `viewQuery` | The app changed what the view's rows are read with: its source, function arguments, `staticConditions` or `staticOrdering`, e.g. on a page that shows another record. The first page is requested. |
559
561
 
560
562
  ### `DTVAnalyticsPanel`
561
563
 
@@ -760,7 +762,7 @@ per record share a definition and its migrations.
760
762
  - The preferences other than hidden columns: syncing filters or sorting to user data, syncing
761
763
  filters to the URL, closing the filter panel on apply.
762
764
  - The table's API: `DTVAPI.rowSelection`, `rowExpansion` (its `fetchData` is a `fetch` with
763
- `reason: 'refresh'`).
765
+ `reason: 'refresh'`, and its `runAction` an `action`).
764
766
  - The sorting, rows per page and filters a view opens with are not changes: they are on the
765
767
  `fetch` and the `filtersApplied` it names.
766
768
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kronor/dtv",
3
- "version": "10.1.1",
3
+ "version": "12.0.0",
4
4
  "description": "Schema-driven, declarative table views with advanced filtering, data fetching and AI-assisted filter generation.",
5
5
  "repository": {
6
6
  "type": "git",