@kronor/dtv 9.1.0 → 9.2.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.
@@ -10,7 +10,7 @@ interface AIAssistantFormProps {
10
10
  /** AI provider: the built-in Gemini integration or a custom request function. */
11
11
  aiIntegration: AIIntegration;
12
12
  toast: RefObject<Toast | null>;
13
- setShowFilterForm: (value: boolean | ((prev: boolean) => boolean)) => void;
13
+ setShowFilterForm: (shown: boolean) => void;
14
14
  /** Optional hook to modify the AI prompt template before it is sent to the AI provider. */
15
15
  modifyAiFilterPrompt?: ModifyAiFilterPromptFn;
16
16
  }
@@ -7,7 +7,7 @@ export interface ActionButtonsProps {
7
7
  actions: ActionDefinition[];
8
8
  selectedView: View;
9
9
  filterState: FilterState;
10
- selectedRows: unknown[];
10
+ selectedRows: readonly unknown[];
11
11
  setFilterState: (next: FilterState) => void;
12
12
  refetch: () => void;
13
13
  applyFilters: () => void;
@@ -52,14 +52,19 @@ type ThroughList<List extends string> = {
52
52
  };
53
53
  /** null when the key can be missing: the cell reads a missing field as null. */
54
54
  type MissingAsNull<Row, Key extends keyof Row> = undefined extends Row[Key] ? null : Partial<Pick<Row, Key>> extends Pick<Row, Key> ? null : never;
55
+ /**
56
+ * Whether a path can continue past a value: into an object (or `any`, a
57
+ * json/jsonb column), not into a scalar, whose keys (`length`) are no fields.
58
+ */
59
+ type CanStepInto<Value> = IsAny<Value> extends true ? true : [Value] extends [Date | ((...args: never[]) => unknown)] ? false : [Value] extends [object] ? true : false;
55
60
  /**
56
61
  * The value a cell gets at a dotted path: the field's own type, plus null when
57
62
  * it or an object on the way can be null or missing (`undefined` never reaches
58
63
  * the cell, see `readPath` in ./columns). `never` when the path is not on the
59
- * row; `ThroughList` when it steps into a list; `unknown` on a row with an
60
- * index signature.
64
+ * row or steps into a scalar; `ThroughList` when it steps into a list;
65
+ * `unknown` on a row with an index signature.
61
66
  */
62
- export type ColumnFieldValue<Row, Path extends string, Prefix extends string = ''> = string extends keyof Row ? unknown : Path extends `${infer Head}.${infer Tail}` ? Head extends keyof Row ? NonNullable<Row[Head]> extends readonly unknown[] ? ThroughList<`${Prefix}${Head}`> : ColumnFieldValue<NonNullable<Row[Head]>, Tail, `${Prefix}${Head}.`> extends infer Inner ? [Inner] extends [never] ? never : Inner extends ThroughList<string> ? Inner : Inner | (null extends Row[Head] ? null : never) | MissingAsNull<Row, Head> : never : never : Path extends keyof Row ? Exclude<Row[Path], undefined> | MissingAsNull<Row, Path> : never;
67
+ export type ColumnFieldValue<Row, Path extends string, Prefix extends string = ''> = string extends keyof Row ? unknown : Path extends `${infer Head}.${infer Tail}` ? Head extends keyof Row ? NonNullable<Row[Head]> extends readonly unknown[] ? ThroughList<`${Prefix}${Head}`> : CanStepInto<NonNullable<Row[Head]>> extends false ? never : ColumnFieldValue<NonNullable<Row[Head]>, Tail, `${Prefix}${Head}.`> extends infer Inner ? [Inner] extends [never] ? never : Inner extends ThroughList<string> ? Inner : Inner | (null extends Row[Head] ? null : never) | MissingAsNull<Row, Head> : never : never : Path extends keyof Row ? Exclude<Row[Path], undefined> | MissingAsNull<Row, Path> : never;
63
68
  type Nullish = null | undefined;
64
69
  type FieldErrors<Row, Field extends string, Value> = string extends Field ? `the field must be a literal path; a helper takes it as 'Field & ValidateColumnFieldType<Row, Field, Value>'` : string extends keyof Row ? never : ColumnFieldValue<Row, Field> extends infer Held ? Opaque<Held> extends true ? never : [Held] extends [never] ? `field '${Field}' is not on the row` : [Held] extends [ThroughList<infer List>] ? `field '${Field}' goes through the list '${List}'; select the list instead` : [Held] extends [Value] ? never : [Exclude<Held, Nullish>] extends [Value] ? `field '${Field}' can be null, and this column does not render null` : `field '${Field}' holds ${DescribeType<Exclude<Held, Nullish>>}, and this column renders ${DescribeType<Exclude<Value, Nullish>>}` : never;
65
70
  /**
@@ -18,9 +18,9 @@ export interface ActionAPI {
18
18
  /** Current selected rows (simplified/flattened), empty when none selected or selection disabled. */
19
19
  selectedRows: unknown[];
20
20
  /**
21
- * Replace the *draft* filter state (resets pagination). This is what the
22
- * filter form edits; it does not affect the query until applied. Follow it
23
- * with `applyFilters` to make the new value take effect.
21
+ * Replace the *draft* filter state. This is what the filter form edits; it
22
+ * does not affect the query, nor the page the user is on, until applied.
23
+ * Follow it with `applyFilters` to make the new value take effect.
24
24
  */
25
25
  setFilterState: (next: FilterState) => void;
26
26
  /**
@@ -0,0 +1,125 @@
1
+ import type { FetchDataResult } from '../data';
2
+ import { type DataOrdering } from '../data-ordering';
3
+ import { type FilterDisplayState } from '../filter-display-state';
4
+ import type { FilterGroups } from '../filters';
5
+ import type { ViewId } from '../view';
6
+ import { type FilterState } from './filter-state';
7
+ import { type RequestId, type TableState } from './table';
8
+ /** What user data holds for the selected view. */
9
+ export interface ViewUserData {
10
+ /** The initial load has completed. Until then, the remote copy may bring a persisted state. */
11
+ readonly ready: boolean;
12
+ readonly syncFilterState: boolean;
13
+ readonly persistedFilterState: FilterState | null;
14
+ readonly rowsPerPage: number | null;
15
+ }
16
+ /** A panel shown below the menu bar; one at a time. */
17
+ export type Panel = 'filters' | 'savedFilters' | 'preferences';
18
+ export interface AppState {
19
+ readonly selectedViewId: ViewId;
20
+ readonly table: TableState;
21
+ /** The draft filter state: the one being edited. Applying it starts a request; editing it does not. */
22
+ readonly filterState: FilterState;
23
+ /** The search through the selected view's filters, and which of their groups are expanded. */
24
+ readonly searchQuery: string;
25
+ readonly filterDisplayState: FilterDisplayState;
26
+ /** The user data of the selected view; `null` until it arrives. */
27
+ readonly userData: ViewUserData | null;
28
+ /** The ordering each view's next query starts with. Remembered across view switches. */
29
+ readonly orderingByViewId: Readonly<Record<ViewId, DataOrdering | null>>;
30
+ /** The rows per page the next query starts with. Kept across view switches. */
31
+ readonly rowsPerPage: number;
32
+ readonly lastRequestId: RequestId;
33
+ readonly activePanel: Panel | null;
34
+ readonly showAIAssistant: boolean;
35
+ readonly showPopout: boolean;
36
+ /** The rows the user selected, flattened; empty when row selection is off. */
37
+ readonly selectedRows: readonly unknown[];
38
+ }
39
+ /** What `updateAppState` reads but does not own. */
40
+ export interface AppStateEnv {
41
+ readonly filterGroups: (viewId: ViewId) => FilterGroups;
42
+ /** The rows per page a user may pick; empty allows any. */
43
+ readonly rowsPerPageOptions: readonly number[];
44
+ }
45
+ export type Msg =
46
+ /** User data of `viewId` changed: written here, by another tab, or loaded. */
47
+ {
48
+ readonly tag: 'userDataChanged';
49
+ readonly viewId: ViewId;
50
+ readonly userData: ViewUserData;
51
+ } | {
52
+ readonly tag: 'viewSelected';
53
+ readonly viewId: ViewId;
54
+ } | {
55
+ readonly tag: 'draftChanged';
56
+ readonly filters: FilterState;
57
+ }
58
+ /** Apply the draft as it is when this message is handled. */
59
+ | {
60
+ readonly tag: 'draftApplied';
61
+ }
62
+ /** Apply `filters`, leaving the draft as it is. */
63
+ | {
64
+ readonly tag: 'filtersApplied';
65
+ readonly filters: FilterState;
66
+ } | {
67
+ readonly tag: 'searchQueryChanged';
68
+ readonly searchQuery: string;
69
+ } | {
70
+ readonly tag: 'filterGroupExpandedChanged';
71
+ readonly groupName: string;
72
+ readonly expanded: boolean;
73
+ } | {
74
+ readonly tag: 'orderingChanged';
75
+ readonly ordering: DataOrdering | null;
76
+ } | {
77
+ readonly tag: 'rowsPerPageChanged';
78
+ readonly rowsPerPage: number;
79
+ } | {
80
+ readonly tag: 'nextPageRequested';
81
+ } | {
82
+ readonly tag: 'previousPageRequested';
83
+ }
84
+ /** Refetch the current page, e.g. after a mutation elsewhere. Hydrating, the view fetches once it settles. */
85
+ | {
86
+ readonly tag: 'refreshRequested';
87
+ } | {
88
+ readonly tag: 'rowsArrived';
89
+ readonly requestId: RequestId;
90
+ readonly rows: FetchDataResult;
91
+ }
92
+ /** Show `panel`, or hide it when it is the one shown. */
93
+ | {
94
+ readonly tag: 'panelToggled';
95
+ readonly panel: Panel;
96
+ } | {
97
+ readonly tag: 'filterPanelShown';
98
+ readonly shown: boolean;
99
+ } | {
100
+ readonly tag: 'aiAssistantToggled';
101
+ } | {
102
+ readonly tag: 'popoutShown';
103
+ readonly shown: boolean;
104
+ } | {
105
+ readonly tag: 'rowsSelected';
106
+ readonly rows: readonly unknown[];
107
+ };
108
+ export type Command = {
109
+ readonly tag: 'persistFilterState';
110
+ readonly viewId: ViewId;
111
+ readonly filters: FilterState;
112
+ } | {
113
+ readonly tag: 'persistRowsPerPage';
114
+ readonly viewId: ViewId;
115
+ readonly rowsPerPage: number;
116
+ };
117
+ export interface AppStateInit {
118
+ readonly viewId: ViewId;
119
+ readonly rowsPerPage: number;
120
+ /** A filter state the page was opened with, e.g. a shared link. It wins over a persisted one. */
121
+ readonly initialFilterState?: FilterState;
122
+ }
123
+ /** A table that waits for the user data of its view: it starts with a `userDataChanged`. */
124
+ export declare function initAppState(env: AppStateEnv, init: AppStateInit): AppState;
125
+ export declare function updateAppState(env: AppStateEnv, state: AppState, msg: Msg): [AppState, Command[]];
@@ -0,0 +1,12 @@
1
+ import { FilterFormState } from "../filter-form-state";
2
+ import { FilterGroups, FilterId, FilterExpr } from "../filters";
3
+ export type FilterState = Map<FilterId, FilterFormState>;
4
+ export declare enum FormStateInitMode {
5
+ WithInitialValues = "withInitialValues",
6
+ Empty = "empty"
7
+ }
8
+ export declare function buildInitialFormState(expr: FilterExpr, mode?: FormStateInitMode): FilterFormState;
9
+ export declare function getFilterStateById(state: FilterState, id: FilterId): FilterFormState;
10
+ export declare function setFilterStateById(state: FilterState, id: FilterId, newFilterState: FilterFormState): FilterState;
11
+ export declare function filterStatesEqual(left: FilterState, right: FilterState): boolean;
12
+ export declare function createDefaultFilterState(filterGroups: FilterGroups, mode?: FormStateInitMode): FilterState;
@@ -0,0 +1,4 @@
1
+ export * from './filter-state';
2
+ export { appliedFilterState, currentPageQuery, currentQuery, hasNextPage, hasPreviousPage, isLoading, nextPageCursor, noRows, paginationState, pendingRequest, receiveRows, shownPage, type Cursor, type DataRequest, type Page, type PaginationState, type Query, type RequestId, type TableState } from './table';
3
+ export * from './app-state';
4
+ export * from './use-app-state';
@@ -0,0 +1,93 @@
1
+ import type { FetchDataResult, PaginationCursor } from '../data';
2
+ import type { DataOrdering } from '../data-ordering';
3
+ import type { ViewId } from '../view';
4
+ import type { FilterState } from './filter-state';
5
+ declare const requestIdBrand: unique symbol;
6
+ /** Identifies a request. Minted by this module alone, so rows can only answer one it started. */
7
+ export type RequestId = number & {
8
+ readonly [requestIdBrand]: true;
9
+ };
10
+ /** The row a following page starts after. */
11
+ export type Cursor = NonNullable<PaginationCursor>;
12
+ /** Everything the rows of a request depend on. */
13
+ export interface Query {
14
+ readonly viewId: ViewId;
15
+ readonly filters: FilterState;
16
+ readonly ordering: DataOrdering | null;
17
+ readonly rowsPerPage: number;
18
+ /** Where each page after the first starts. Its length is the page index. */
19
+ readonly cursors: readonly Cursor[];
20
+ }
21
+ /** A request for the rows of `query`. */
22
+ export interface DataRequest {
23
+ readonly id: RequestId;
24
+ readonly query: Query;
25
+ }
26
+ /** Rows and the query they answer. */
27
+ export interface Page {
28
+ readonly query: Query;
29
+ readonly rows: FetchDataResult;
30
+ }
31
+ export type TableState =
32
+ /**
33
+ * The filter state to start from is not known yet: the view's user data has not arrived,
34
+ * or a persisted state may still come with the initial load. `initialFilterState`, from a
35
+ * shared link say, wins over a persisted one once the user data is there.
36
+ */
37
+ {
38
+ readonly tag: 'hydrating';
39
+ readonly initialFilterState: FilterState | null;
40
+ }
41
+ /** Waiting for `request`. `shown` stays on screen, under the loading overlay, meanwhile. */
42
+ | {
43
+ readonly tag: 'loading';
44
+ readonly request: DataRequest;
45
+ readonly shown: Page | null;
46
+ }
47
+ /**
48
+ * Moving to another page of the rows on screen. Until it arrives the user is still on
49
+ * `shown`: refreshing, or going back, is relative to it.
50
+ */
51
+ | {
52
+ readonly tag: 'paging';
53
+ readonly request: DataRequest;
54
+ readonly shown: Page;
55
+ } | {
56
+ readonly tag: 'loaded';
57
+ readonly page: Page;
58
+ };
59
+ /** Pagination as actions see it (see `ActionAPI.getPaginationState`). */
60
+ export interface PaginationState {
61
+ page: number;
62
+ cursors: PaginationCursor[];
63
+ rowsPerPage: number;
64
+ }
65
+ /** No rows: what a table shows before any arrive, or when a request fails. */
66
+ export declare const noRows: FetchDataResult;
67
+ /** The id before the first request. Not exported from the state module: only it mints ids. */
68
+ export declare const noRequestId: RequestId;
69
+ /** The id of the request after the one `last` identifies. */
70
+ export declare function nextRequestId(last: RequestId): RequestId;
71
+ /** Rows arrived for `requestId`: the table shows them if it waits on that request. */
72
+ export declare function receiveRows(table: TableState, requestId: RequestId, rows: FetchDataResult): TableState;
73
+ /** The request to run. Running another one, or none, means the previous one is superseded. */
74
+ export declare function pendingRequest(table: TableState): DataRequest | null;
75
+ /** The rows on screen and the query they answer. */
76
+ export declare function shownPage(table: TableState): Page | null;
77
+ /** The query the table last asked for, answered or not. */
78
+ export declare function currentQuery(table: TableState): Query | null;
79
+ /**
80
+ * The query of the page the user is on: the one being loaded, unless that is only a move to
81
+ * another page of the rows on screen.
82
+ */
83
+ export declare function currentPageQuery(table: TableState): Query | null;
84
+ /** The filters of the query the table last asked for; `null` while hydrating. */
85
+ export declare function appliedFilterState(table: TableState): FilterState | null;
86
+ export declare function isLoading(table: TableState): boolean;
87
+ export declare function hasNextPage(table: TableState): boolean;
88
+ export declare function hasPreviousPage(table: TableState): boolean;
89
+ /** The pagination of the rows on screen; `rowsPerPage` while there are none. */
90
+ export declare function paginationState(table: TableState, rowsPerPage: number): PaginationState;
91
+ /** A full page may have one after it, starting after its last row. */
92
+ export declare function nextPageCursor(page: Page): Cursor | null;
93
+ export {};
@@ -0,0 +1,15 @@
1
+ import type { FetchDataResult } from '../data';
2
+ import { type AppState, type AppStateEnv, type AppStateInit, type Command, type Msg } from './app-state';
3
+ import { type Query } from './table';
4
+ /** How the effects of the app state are carried out. */
5
+ export interface AppStateEffects {
6
+ /** Fetches the rows `query` asks for. Rejects with an AbortError once `signal` aborts. */
7
+ readonly fetchRows: (query: Query, signal: AbortSignal) => Promise<FetchDataResult>;
8
+ readonly runCommand: (command: Command) => void;
9
+ }
10
+ /**
11
+ * Holds the state of a table and runs the effects it asks for. The pending request is
12
+ * fetched, and aborted once another one supersedes it or none is wanted any more, unmounting
13
+ * included. Commands run once each, in order.
14
+ */
15
+ export declare function useAppState(env: AppStateEnv, init: AppStateInit, effects: AppStateEffects): [AppState, (msg: Msg) => void];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kronor/dtv",
3
- "version": "9.1.0",
3
+ "version": "9.2.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",
@@ -58,7 +58,7 @@
58
58
  "react-dom": "^19.0.0"
59
59
  },
60
60
  "dependencies": {
61
- "@kronor/hasura-graphql": "^0.1.2",
61
+ "@kronor/hasura-graphql": "^0.1.4",
62
62
  "commander": "^14.0.0",
63
63
  "fast-glob": "^3.3.3",
64
64
  "graphql": "^16.14.2",
@@ -1,60 +0,0 @@
1
- import { FilterFormState } from "./filter-form-state";
2
- import { FilterGroups, FilterId, FilterExpr } from "./filters";
3
- import { View, ViewId } from "./view";
4
- import { FetchDataResult } from "./data";
5
- import type { PaginationCursor } from "./data";
6
- import { FilterDisplayState } from "./filter-display-state";
7
- import type { DataOrdering } from "./data-ordering";
8
- export type FilterState = Map<FilterId, FilterFormState>;
9
- export declare enum FormStateInitMode {
10
- WithInitialValues = "withInitialValues",
11
- Empty = "empty"
12
- }
13
- export declare function buildInitialFormState(expr: FilterExpr, mode?: FormStateInitMode): FilterFormState;
14
- export declare function getFilterStateById(state: FilterState, id: FilterId): FilterFormState;
15
- export declare function setFilterStateById(state: FilterState, id: FilterId, newFilterState: FilterFormState): FilterState;
16
- export declare function filterStatesEqual(left: FilterState, right: FilterState): boolean;
17
- export interface AppState {
18
- selectedViewId: ViewId;
19
- views: View[];
20
- filterGroups: FilterGroups;
21
- searchQuery: string;
22
- filterDisplayState: FilterDisplayState;
23
- data: FetchDataResult;
24
- filterState: FilterState;
25
- appliedFilterState: FilterState;
26
- pagination: PaginationState;
27
- orderingByViewId: Record<ViewId, DataOrdering | null>;
28
- }
29
- export interface PaginationState {
30
- page: number;
31
- cursors: PaginationCursor[];
32
- rowsPerPage: number;
33
- }
34
- export declare function createDefaultFilterState(filterGroups: FilterGroups, mode?: FormStateInitMode): FilterState;
35
- export declare function createDefaultAppState(views: View[], rowsPerPageOptions: number[]): AppState;
36
- declare function setSelectedViewId(state: AppState, newId: ViewId): AppState;
37
- declare function setDataRows(state: AppState, newRows: FetchDataResult, pagination?: PaginationState): AppState;
38
- declare function setFilterGroups(state: AppState, newFilterGroups: FilterGroups): AppState;
39
- declare function setSearchQuery(state: AppState, searchQuery: string): AppState;
40
- declare function setFilterGroupExpanded(state: AppState, groupName: string, expanded: boolean): AppState;
41
- declare function setFilterState(state: AppState, newFilterState: FilterState): AppState;
42
- declare function setAppliedFilterState(state: AppState, newAppliedFilterState: FilterState): AppState;
43
- declare function commitFilterState(state: AppState): AppState;
44
- declare function setRowsPerPage(state: AppState, newRowsPerPage: number): AppState;
45
- declare function setOrdering(state: AppState, viewId: ViewId, ordering: DataOrdering | null): AppState;
46
- export declare const useAppState: (views: View[], rowsPerPageOptions: number[], initialFilterStateOverride?: FilterState) => {
47
- state: AppState;
48
- selectedView: View;
49
- setSelectedViewId: (id: ViewId) => void;
50
- setDataRows: (rows: FetchDataResult, pagination?: PaginationState) => void;
51
- setFilterGroups: (groups: FilterGroups) => void;
52
- setFilterState: (filterState: FilterState) => void;
53
- setAppliedFilterState: (filterState: FilterState) => void;
54
- commitFilterState: () => void;
55
- setSearchQuery: (searchQuery: string) => void;
56
- setFilterGroupExpanded: (groupName: string, expanded: boolean) => void;
57
- setRowsPerPage: (value: number) => void;
58
- setOrdering: (viewId: ViewId, ordering: DataOrdering | null) => void;
59
- };
60
- export { setSelectedViewId, setDataRows, setFilterGroups, setFilterState, setAppliedFilterState, commitFilterState, setSearchQuery, setFilterGroupExpanded, setRowsPerPage, setOrdering };