@kronor/dtv 10.1.0 → 11.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). */
@@ -1,8 +1,7 @@
1
- import { ActionDefinition, ActionUserDataAPI } from '../framework/actions';
1
+ import { ActionDefinition, ActionUserDataAPI, type ShownRows } from '../framework/actions';
2
2
  import { View } from '../framework/view';
3
3
  import type { ShowToastFn } from '../framework/toast';
4
- import { FilterState, PaginationState } from '../framework/state';
5
- import type { DataOrdering } from '../framework/data-ordering';
4
+ import { FilterState } from '../framework/state';
6
5
  export interface ActionButtonsProps {
7
6
  actions: ActionDefinition[];
8
7
  selectedView: View;
@@ -12,10 +11,8 @@ export interface ActionButtonsProps {
12
11
  refetch: () => void;
13
12
  applyFilters: () => void;
14
13
  showToast: ShowToastFn;
15
- paginationState: PaginationState;
16
- rowsPerPage: number;
17
- ordering: DataOrdering | null;
14
+ shownRows: ShownRows | null;
18
15
  userData: ActionUserDataAPI;
19
16
  }
20
- export declare function ActionButtons({ actions, selectedView, filterState, selectedRows, setFilterState, refetch, applyFilters, showToast, paginationState, rowsPerPage, ordering, userData }: ActionButtonsProps): import("react/jsx-runtime").JSX.Element;
17
+ export declare function ActionButtons({ actions, selectedView, filterState, selectedRows, setFilterState, refetch, applyFilters, showToast, shownRows, userData }: ActionButtonsProps): import("react/jsx-runtime").JSX.Element;
21
18
  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;
@@ -1,5 +1,5 @@
1
1
  import * as React from 'react';
2
- import type { FilterControl as FrameworkFilterControl, SuggestionFetcher, SuggestionItem } from '../framework/filters';
2
+ import type { CustomOperatorOption, FilterControl as FrameworkFilterControl, SuggestionFetcher, SuggestionItem } from '../framework/filters';
3
3
  import type * as FilterValue from '../framework/filterValue';
4
4
  import type { MutableTuple } from './filterTyping';
5
5
  export type { SuggestionFetcher, SuggestionItem };
@@ -33,10 +33,7 @@ export type DropdownControl<Items extends readonly ItemControlItem[]> = Omit<Con
33
33
  export type MultiselectControl<Items extends readonly ItemControlItem[]> = Omit<ControlOfType<'multiselect'>, 'items'> & {
34
34
  items: MutableTuple<Items>;
35
35
  };
36
- export type CustomOperatorControl<Operators extends readonly {
37
- label: string;
38
- value: string;
39
- }[], ValueControl extends FrameworkFilterControl> = Omit<ControlOfType<'customOperator'>, 'operators' | 'valueControl'> & {
36
+ export type CustomOperatorControl<Operators extends readonly CustomOperatorOption[], ValueControl extends FrameworkFilterControl> = Omit<ControlOfType<'customOperator'>, 'operators' | 'valueControl'> & {
40
37
  operators: MutableTuple<Operators>;
41
38
  valueControl: ValueControl;
42
39
  };
@@ -79,10 +76,7 @@ export declare const FilterControl: {
79
76
  filterable?: boolean;
80
77
  initialValue?: ControlValue<MultiselectControl<Items>>;
81
78
  }) => MultiselectControl<Items>;
82
- customOperator: <const Operators extends readonly {
83
- label: string;
84
- value: string;
85
- }[], const ValueControl extends FrameworkFilterControl>(options: {
79
+ customOperator: <const Operators extends readonly CustomOperatorOption[], const ValueControl extends FrameworkFilterControl>(options: {
86
80
  label?: string;
87
81
  operators: Operators;
88
82
  valueControl: ValueControl;
@@ -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,8 +78,6 @@ 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
  }
@@ -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. */
@@ -65,7 +65,8 @@ export declare function makeFilterFormStateSerializable(node: FilterFormState):
65
65
  /**
66
66
  * Schema-aware emptiness check for a FilterFormState tree.
67
67
  * A leaf is considered empty when its primitive value is '' | null | [] (if array).
68
- * For customOperator controls we look at the nested `value` field inside { operator, value }.
68
+ * For customOperator controls we look at the nested `value` field inside { operator, value },
69
+ * unless the operator takes no value (`is empty`): such a leaf is set.
69
70
  */
70
71
  export declare function isFilterEmpty(state: FilterFormState, schemaExpr: FilterExpr): boolean;
71
72
  /**
@@ -104,6 +104,17 @@ export type FilterValueFormatContext = {
104
104
  export type FilterTransform<Input = unknown, Row = any, Field extends FilterField = any> = {
105
105
  toQuery: (input: Input, context: QueryTransformContext<Row, Field>) => TransformResult;
106
106
  };
107
+ /**
108
+ * An operator of a `customOperator` control. `takesValue: false` marks one
109
+ * that filters without a value (`is empty`): the form hides the value control
110
+ * for it, and the filter counts as set although its value is empty. The
111
+ * filter's own transform builds its condition; `hasuraCustomOperator` does not.
112
+ */
113
+ export type CustomOperatorOption = {
114
+ label: string;
115
+ value: string;
116
+ takesValue?: boolean;
117
+ };
107
118
  export type FilterControl = {
108
119
  type: 'text';
109
120
  label?: string;
@@ -141,10 +152,7 @@ export type FilterControl = {
141
152
  } | {
142
153
  type: 'customOperator';
143
154
  label?: string;
144
- operators: {
145
- label: string;
146
- value: string;
147
- }[];
155
+ operators: CustomOperatorOption[];
148
156
  valueControl: FilterControl;
149
157
  initialValue?: any;
150
158
  } | {
@@ -262,6 +270,8 @@ export declare const SUPPORTED_OPERATORS: {
262
270
  label: string;
263
271
  value: string;
264
272
  }[];
273
+ export declare function customOperatorTakesValue(operators: readonly CustomOperatorOption[], operator: unknown): boolean;
274
+ export declare function defaultCustomOperator(operators: readonly CustomOperatorOption[]): string | undefined;
265
275
  export type SuggestionItem = {
266
276
  label: string;
267
277
  };
@@ -5,7 +5,7 @@ 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,7 +38,7 @@ 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
43
  /** The AI filter assistant filled the draft since filters were last applied. */
44
44
  readonly aiAssistedDraft: boolean;
@@ -56,6 +56,8 @@ export interface AppStateEnv {
56
56
  readonly definition: (viewId: ViewId) => ViewDefinition;
57
57
  /** How a view's filters differ from its latest definition snapshot; `null` without migrations. */
58
58
  readonly snapshotDiff: (viewId: ViewId) => SnapshotDiff | null;
59
+ /** What a view's rows are read with now; `null` for a view the table does not have. */
60
+ readonly viewQuery: (viewId: ViewId) => ViewQuery | null;
59
61
  }
60
62
  /** What applies filters by a message. The table opening with filters is told by the state. */
61
63
  export type ApplyTrigger = Extract<FiltersAppliedTrigger, 'submit' | 'reset' | 'pillRemoved' | 'savedFilter' | 'api'>;
@@ -115,6 +117,13 @@ export type Msg =
115
117
  /** Refetch the current page, e.g. after a mutation elsewhere. Hydrating, the view fetches once it settles. */
116
118
  | {
117
119
  readonly tag: 'refreshRequested';
120
+ }
121
+ /**
122
+ * The environment changed: the host may have changed what the selected view's rows are read
123
+ * with. Hydrating, the view fetches with it once it settles.
124
+ */
125
+ | {
126
+ readonly tag: 'envChanged';
118
127
  } | {
119
128
  readonly tag: 'rowsArrived';
120
129
  readonly requestId: RequestId;
@@ -159,6 +168,10 @@ export type Command = {
159
168
  readonly viewId: ViewId;
160
169
  readonly ordering: DataOrdering | null;
161
170
  }
171
+ /** Tell the host that no row is selected any more: the table cleared the selection itself. */
172
+ | {
173
+ readonly tag: 'notifyRowSelectionCleared';
174
+ }
162
175
  /** Report `event` as an analytics event of `viewId`. */
163
176
  | {
164
177
  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[];
@@ -50,6 +50,7 @@ export type FilterControlJson = {
50
50
  operators: {
51
51
  label: string;
52
52
  value: string;
53
+ takesValue?: boolean;
53
54
  }[];
54
55
  valueControl: FilterControlJson;
55
56
  initialValue?: any;
@@ -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';
@@ -16,7 +16,7 @@ export type { Runtime } from '../framework/runtime';
16
16
  export type { ColumnDefinition } from '../framework/column-definition';
17
17
  export type { FieldQuery } from '../framework/column-definition';
18
18
  export type { FilterState } from '../framework/state';
19
- export type { FilterSchema, FilterField, FilterValueFormatter, FilterValueFormatContext, QueryTransformContext, SuggestionFetcher, TransformConditionResult } from '../framework/filters';
19
+ export type { CustomOperatorOption, FilterSchema, FilterField, FilterValueFormatter, FilterValueFormatContext, QueryTransformContext, SuggestionFetcher, TransformConditionResult } from '../framework/filters';
20
20
  export { TransformResult } from '../framework/filters';
21
21
  export * as FilterValue from '../framework/filterValue';
22
22
  export { FilterExpr } from '../dsl/filterExpr';
@@ -26,7 +26,7 @@ export { FilterTransform } from '../dsl/filterTransform';
26
26
  export { rowType } from '../dsl/columns';
27
27
  export type { UserDataJson } from '../framework/user-data';
28
28
  export type { UserDataLoadAPI, UserDataSaveAPI, UserDataLoadCallback, UserDataSaveCallback } from '../framework/user-data-manager';
29
- export type { ActionDefinition, ActionAPI, ActionUserDataAPI } from '../framework/actions';
29
+ export type { ActionDefinition, ActionAPI, ActionUserDataAPI, ShownRows } from '../framework/actions';
30
30
  export type { DTVAnalytics, DTVAnalyticsEvent, DTVAnalyticsEventBase, DTVAnalyticsEventPayload, DTVAnalyticsEventType, DTVAnalyticsSpan, DTVAnalyticsError, DTVAnalyticsPanel, DTVAnalyticsResets, DTVAnalyticsRetainedView, DTVAnalyticsUserDataError, FiltersAppliedTrigger, FetchReason } from '../framework/analytics';
31
31
  export type { FetchErrorInfo, FetchErrorKind } from '../framework/fetch-error';
32
32
  export type { HasuraFilterObject, HasuraOperator, HasuraOperatorFor, HasuraComparable, HasuraFilterExpression, GraphQLVariable, HasuraOrderBy, GraphQLSelectionSetItem, GraphQLSelectionSet, GraphQLQueryAST, } from '../framework/graphql';
package/docs/analytics.md CHANGED
@@ -556,6 +556,7 @@ failed lookup is reported, so one broken fetcher can report once per keystroke.
556
556
  | `nextPage`, `previousPage` | The user paged. |
557
557
  | `refresh` | The app asked for fresh rows (`DTVAPI.fetchData`, an action's `refetch`), e.g. after a mutation. |
558
558
  | `userData` | The rows per page or the sorting changed in the user's data, e.g. in another tab. |
559
+ | `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
560
 
560
561
  ### `DTVAnalyticsPanel`
561
562
 
@@ -367,6 +367,23 @@ Annotate a hand-written one `ConditionOnlyTransform` — a transform typed
367
367
  `FilterTransform` may return either, which is not enough. A transform object
368
368
  with no `toQuery` at all is rejected too; it would do nothing at query time.
369
369
 
370
+ An operator marked `takesValue: false` filters without a value, as `is empty`
371
+ does. The form hides the value control while it is chosen, the filter counts as
372
+ set with an empty value, and the pill reads `Comment is empty`. A new filter
373
+ starts with the first operator that takes a value. The filter's own transform
374
+ gets `{ operator, value }` with an empty `value` and builds the condition;
375
+ `hasuraCustomOperator` has no condition for an empty value.
376
+
377
+ ```ts
378
+ FilterControl.customOperator({
379
+ operators: [
380
+ { label: 'contains', value: 'contains' },
381
+ { label: 'is empty', value: 'isEmpty', takesValue: false }
382
+ ],
383
+ valueControl: FilterControl.text()
384
+ });
385
+ ```
386
+
370
387
  ### Row-scoped builders
371
388
 
372
389
  `FilterExpr` accepts any field name and is checked when the expression reaches
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kronor/dtv",
3
- "version": "10.1.0",
3
+ "version": "11.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",