@kronor/dtv 11.0.0 → 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.
@@ -95,6 +95,13 @@ export type DTVAPI = {
95
95
  collapseAll: () => void;
96
96
  expandAll: () => void;
97
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;
98
105
  };
99
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;
100
107
  export default App;
@@ -1,18 +1,9 @@
1
- import { ActionDefinition, ActionUserDataAPI, type ShownRows } from '../framework/actions';
2
- import { View } from '../framework/view';
3
- import type { ShowToastFn } from '../framework/toast';
4
- import { FilterState } from '../framework/state';
1
+ import type { ActionDefinition } from '../framework/actions';
5
2
  export interface ActionButtonsProps {
6
3
  actions: ActionDefinition[];
7
- selectedView: View;
8
- filterState: FilterState;
9
- selectedRows: readonly unknown[];
10
- setFilterState: (next: FilterState) => void;
11
- refetch: () => void;
12
- applyFilters: () => void;
13
- showToast: ShowToastFn;
14
- shownRows: ShownRows | null;
15
- 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;
16
7
  }
17
- export declare function ActionButtons({ actions, selectedView, filterState, selectedRows, setFilterState, refetch, applyFilters, showToast, shownRows, userData }: ActionButtonsProps): import("react/jsx-runtime").JSX.Element;
8
+ export declare function ActionButtons({ actions, isRunning, onClick }: ActionButtonsProps): import("react/jsx-runtime").JSX.Element;
18
9
  export default ActionButtons;
@@ -83,8 +83,11 @@ export interface ActionAPI {
83
83
  }
84
84
  export interface ActionDefinition {
85
85
  label: string;
86
- /** Names the action in analytics events. Defaults to the label, which may change with wording. */
87
- 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;
88
91
  onClick: (api: ActionAPI) => void | Promise<void>;
89
92
  icon?: string;
90
93
  /** Optional PrimeReact Button badge value. */
@@ -203,7 +203,7 @@ export type DTVAnalyticsEventPayload =
203
203
  readonly error?: DTVAnalyticsUserDataError;
204
204
  }) | (DTVAnalyticsSpan & {
205
205
  readonly type: 'action';
206
- /** The action's `id`, or its label. */
206
+ /** The action's `id`. */
207
207
  readonly action: string;
208
208
  readonly selectedRows: number;
209
209
  readonly outcome: 'succeeded' | 'failed';
@@ -1,4 +1,4 @@
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';
@@ -40,6 +40,10 @@ export interface AppState {
40
40
  readonly showPopout: boolean;
41
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. */
@@ -58,6 +62,10 @@ export interface AppStateEnv {
58
62
  readonly snapshotDiff: (viewId: ViewId) => SnapshotDiff | null;
59
63
  /** What a view's rows are read with now; `null` for a view the table does not have. */
60
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;
61
69
  }
62
70
  /** What applies filters by a message. The table opening with filters is told by the state. */
63
71
  export type ApplyTrigger = Extract<FiltersAppliedTrigger, 'submit' | 'reset' | 'pillRemoved' | 'savedFilter' | 'api'>;
@@ -145,6 +153,19 @@ export type Msg =
145
153
  readonly tag: 'rowsSelected';
146
154
  readonly rows: readonly unknown[];
147
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
+ }
148
169
  /** A component or the user data reported an analytics event, of the selected view. */
149
170
  | {
150
171
  readonly tag: 'reported';
@@ -172,6 +193,16 @@ export type Command = {
172
193
  | {
173
194
  readonly tag: 'notifyRowSelectionCleared';
174
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
+ }
175
206
  /** Report `event` as an analytics event of `viewId`. */
176
207
  | {
177
208
  readonly tag: 'track';
@@ -25,6 +25,10 @@ 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
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';
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
 
@@ -761,7 +762,7 @@ per record share a definition and its migrations.
761
762
  - The preferences other than hidden columns: syncing filters or sorting to user data, syncing
762
763
  filters to the URL, closing the filter panel on apply.
763
764
  - The table's API: `DTVAPI.rowSelection`, `rowExpansion` (its `fetchData` is a `fetch` with
764
- `reason: 'refresh'`).
765
+ `reason: 'refresh'`, and its `runAction` an `action`).
765
766
  - The sorting, rows per page and filters a view opens with are not changes: they are on the
766
767
  `fetch` and the `filtersApplied` it names.
767
768
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kronor/dtv",
3
- "version": "11.0.0",
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",