@kronor/dtv 9.3.0 → 9.4.1

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.
Files changed (38) hide show
  1. package/README.md +8 -2
  2. package/dist/cli/commands/definitions.js +76 -0
  3. package/dist/cli/config/loadConfig.js +69 -5
  4. package/dist/cli/definitions/discover.js +130 -0
  5. package/dist/cli/definitions/generate.js +261 -0
  6. package/dist/cli/definitions/loadProject.js +107 -0
  7. package/dist/cli/definitions/project.js +122 -0
  8. package/dist/cli/definitions/resolve.js +53 -0
  9. package/dist/cli/definitions/run.js +223 -0
  10. package/dist/cli/definitions/types.js +8 -0
  11. package/dist/cli/definitions/wire.js +111 -0
  12. package/dist/cli/dtv.js +2 -0
  13. package/dist/cli/typegen/runTypegen.js +4 -3
  14. package/dist/index.es.js +14103 -13451
  15. package/dist/types/components/UserPreferencesPanel.d.ts +2 -1
  16. package/dist/types/dsl/index.d.ts +1 -0
  17. package/dist/types/dsl/migrations.d.ts +114 -0
  18. package/dist/types/framework/decoder.d.ts +61 -0
  19. package/dist/types/framework/filter-form-state.d.ts +18 -2
  20. package/dist/types/framework/filter-sharing.d.ts +21 -9
  21. package/dist/types/framework/runtime.d.ts +2 -0
  22. package/dist/types/framework/saved-filters.d.ts +10 -14
  23. package/dist/types/framework/state/app-state.d.ts +8 -0
  24. package/dist/types/framework/useUserDataManager.d.ts +3 -0
  25. package/dist/types/framework/user-data-errors.d.ts +8 -0
  26. package/dist/types/framework/user-data-manager.d.ts +6 -1
  27. package/dist/types/framework/user-data-undecoded.d.ts +86 -0
  28. package/dist/types/framework/user-data.d.ts +120 -33
  29. package/dist/types/framework/user-data.migrations.d.ts +9 -8
  30. package/dist/types/framework/view-migrations.d.ts +112 -0
  31. package/dist/types/framework/view-parser.d.ts +2 -1
  32. package/dist/types/framework/view-projection.d.ts +52 -0
  33. package/dist/types/framework/view.d.ts +7 -0
  34. package/dist/types/lib/index.d.ts +4 -0
  35. package/dist/types/typegen/index.d.ts +26 -4
  36. package/docs/typegen.md +12 -0
  37. package/docs/view-migrations.md +183 -0
  38. package/package.json +1 -1
@@ -13,6 +13,7 @@ interface UserPreferencesPanelProps {
13
13
  columnDefinitions: ColumnDefinition[];
14
14
  onSetHiddenColumns: (viewId: ViewId, hiddenColumns: string[]) => Promise<ViewData>;
15
15
  onSetSyncFilterStateToUserData: (viewId: ViewId, enabled: boolean) => Promise<ViewData>;
16
+ onSetSyncOrderingToUserData: (viewId: ViewId, enabled: boolean) => Promise<ViewData>;
16
17
  }
17
- export default function UserPreferencesPanel({ visible, preferences, onChangePreferences, currentView, viewData, columnDefinitions, onSetHiddenColumns, onSetSyncFilterStateToUserData }: UserPreferencesPanelProps): import("react/jsx-runtime").JSX.Element | null;
18
+ export default function UserPreferencesPanel({ visible, preferences, onChangePreferences, currentView, viewData, columnDefinitions, onSetHiddenColumns, onSetSyncFilterStateToUserData, onSetSyncOrderingToUserData }: UserPreferencesPanelProps): import("react/jsx-runtime").JSX.Element | null;
18
19
  export {};
@@ -11,3 +11,4 @@ export type { DslTypeError } from './typeErrors';
11
11
  export * from './hasura';
12
12
  export * from './queryForRow';
13
13
  export * from './view';
14
+ export * from './migrations';
@@ -0,0 +1,114 @@
1
+ import type { Json } from '../framework/decoder';
2
+ import { DROP, RESET, type MigrationOp, type ViewMigration, type ViewMigrationChain } from '../framework/view-migrations';
3
+ import type { ViewProjection } from '../framework/view-projection';
4
+ import type { DslTypeError } from './typeErrors';
5
+ export { DROP, RESET } from '../framework/view-migrations';
6
+ export type { ViewMigration, ViewMigrationChain } from '../framework/view-migrations';
7
+ export type { ViewProjection } from '../framework/view-projection';
8
+ type FilterIdOf<P extends ViewProjection> = Extract<keyof P['filters'], string>;
9
+ type ColumnIdOf<P extends ViewProjection> = Extract<keyof P['columns'], string>;
10
+ type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
11
+ type Assignable<A, B> = [A] extends [B] ? true : false;
12
+ type Check<Ok extends boolean, Message extends string> = Ok extends true ? unknown : DslTypeError<Message>;
13
+ type OperatorsOfControl<C> = C extends {
14
+ type: 'customOperator';
15
+ operators: readonly (infer O)[];
16
+ } ? O : never;
17
+ /** The custom operators a filter's controls offer. */
18
+ export type OperatorsOf<F> = F extends {
19
+ kind: 'leaf';
20
+ control: infer C;
21
+ } ? OperatorsOfControl<C> : F extends {
22
+ kind: 'and' | 'or';
23
+ children: readonly (infer Child)[];
24
+ } ? OperatorsOf<Child> : F extends {
25
+ kind: 'not';
26
+ child: infer Child;
27
+ } ? OperatorsOf<Child> : never;
28
+ type LeafValueFor<C> = C extends {
29
+ type: 'customOperator';
30
+ operators: readonly (infer O)[];
31
+ } ? {
32
+ operator: O;
33
+ value: {
34
+ type: 'empty';
35
+ } | {
36
+ type: 'value';
37
+ value: Json;
38
+ };
39
+ } : Json;
40
+ /** A stored leaf value of a filter with the control `C`. */
41
+ export type UndecodedFilterValueFor<C> = {
42
+ type: 'empty';
43
+ } | {
44
+ type: 'value';
45
+ value: LeafValueFor<C>;
46
+ } | {
47
+ type: 'legacy';
48
+ raw: Json;
49
+ };
50
+ /** A filter's stored state, for the filter's snapshot `F`. */
51
+ export type UndecodedFilterFormStateFor<F> = F extends {
52
+ kind: 'leaf';
53
+ control: infer C;
54
+ } ? {
55
+ type: 'leaf';
56
+ value: UndecodedFilterValueFor<C>;
57
+ } : F extends {
58
+ kind: infer K extends 'and' | 'or';
59
+ children: infer Children extends readonly unknown[];
60
+ } ? {
61
+ type: K;
62
+ children: {
63
+ -readonly [I in keyof Children]: UndecodedFilterFormStateFor<Children[I]>;
64
+ };
65
+ } : F extends {
66
+ kind: 'not';
67
+ child: infer Child;
68
+ } ? {
69
+ type: 'not';
70
+ child: UndecodedFilterFormStateFor<Child>;
71
+ } : never;
72
+ type StateOf<P extends ViewProjection, Id extends keyof P['filters']> = UndecodedFilterFormStateFor<P['filters'][Id]>;
73
+ /** The operations of a migration from the snapshot `From` to the snapshot `To`. */
74
+ export interface MigrationBuilder<From extends ViewProjection, To extends ViewProjection> {
75
+ /** The filter got another id; it is otherwise the same. */
76
+ renameFilter<A extends FilterIdOf<From>, B extends FilterIdOf<To>>(from: A, to: B & Check<Same<From['filters'][A], To['filters'][B]>, `renameFilter: "${A}" and "${B}" differ; use custom()`>): MigrationOp;
77
+ /** The filter changed, but every state stored for it still fits and means the same. */
78
+ keep<Id extends FilterIdOf<From> & FilterIdOf<To>>(id: Id & Check<Assignable<StateOf<From, Id>, StateOf<To, Id>>, `keep: state stored for "${Id}" does not fit it any more; use custom() or reset()`>, why: {
79
+ because: string;
80
+ }): MigrationOp;
81
+ /** Drop what is stored for the filter; it starts over from its initial value. Users are told. */
82
+ reset<Id extends FilterIdOf<From>>(id: Id): MigrationOp;
83
+ /** The filter was removed. */
84
+ drop<Id extends Exclude<FilterIdOf<From>, FilterIdOf<To>>>(id: Id): MigrationOp;
85
+ /**
86
+ * Rewrite the stored values of the filter's leaves, e.g. for renamed enum values. A list
87
+ * (a multiselect's value) is mapped element by element. Return `DROP` to remove a value.
88
+ * Dropdown items are not part of snapshots, so this is checked by nothing but you:
89
+ * `dtv definitions snapshot --manual` makes a revision for it.
90
+ */
91
+ mapValues<Id extends FilterIdOf<From> & FilterIdOf<To>>(id: Id, map: (value: Json) => Json | typeof DROP): MigrationOp;
92
+ /** Map each custom operator the filter no longer offers to one it does, or to `null` to clear it. */
93
+ mapOperators<Id extends FilterIdOf<From> & FilterIdOf<To>>(id: Id, map: {
94
+ [O in Exclude<OperatorsOf<From['filters'][Id]>, OperatorsOf<To['filters'][Id]>>]: OperatorsOf<To['filters'][Id]> | null;
95
+ }): MigrationOp;
96
+ /** Turn what is stored for `from` into a state of `to`, or `RESET`. */
97
+ custom<A extends FilterIdOf<From>, B extends FilterIdOf<To>>(from: A, to: B, migrate: (state: StateOf<From, A>) => StateOf<To, B> | typeof RESET): MigrationOp;
98
+ renameColumn<A extends ColumnIdOf<From>, B extends ColumnIdOf<To>>(from: A, to: B): MigrationOp;
99
+ dropColumn<Id extends Exclude<ColumnIdOf<From>, ColumnIdOf<To>>>(id: Id): MigrationOp;
100
+ /** The column sorts by another field. */
101
+ resetSort<Id extends ColumnIdOf<From> & ColumnIdOf<To>>(id: Id): MigrationOp;
102
+ /**
103
+ * A decision left open about `subject` (a filter, a column, …). Does not type-check, on
104
+ * purpose: replace it with one of the operations above.
105
+ */
106
+ todo<const Message extends string>(subject: string, message: Message): DslTypeError<`todo: ${Message}`>;
107
+ }
108
+ /** The migration of stored user data from the snapshot `from` to the snapshot `to`. */
109
+ export declare function defineMigration<const From extends ViewProjection, const To extends ViewProjection>(from: From, to: To, ops: (m: MigrationBuilder<From, To>) => readonly MigrationOp[]): ViewMigration;
110
+ /**
111
+ * A view definition's migrations, from its first snapshot on. Pass the result as the
112
+ * view's `migrations`. Throws when the migrations do not follow on from each other.
113
+ */
114
+ export declare function defineViewMigrations(baseline: ViewProjection, migrations?: readonly ViewMigration[]): ViewMigrationChain;
@@ -0,0 +1,61 @@
1
+ import { Result } from './result';
2
+ /**
3
+ * Decoders for data read back from storage: `unknown` in, a typed value out.
4
+ *
5
+ * The decoded values are JSON, so there are no encoders: writing a decoded value back is
6
+ * `JSON.stringify`. Objects keep the fields their decoder does not know, so data this
7
+ * version of dtv only reads and writes back loses nothing.
8
+ *
9
+ * Some decoders are lenient: they fall back or drop an invalid part instead of failing the
10
+ * whole input. What they worked around is collected in the context's `issues`.
11
+ */
12
+ export type Json = null | boolean | number | string | Json[] | {
13
+ [key: string]: Json;
14
+ };
15
+ export type DecodeIssue = {
16
+ path: string;
17
+ message: string;
18
+ };
19
+ /** Where a decoder is in the input, and the problems decoders worked around so far. */
20
+ export type DecodeContext = {
21
+ path: string;
22
+ issues: DecodeIssue[];
23
+ };
24
+ export type Decoder<T> = (input: unknown, context: DecodeContext) => Result<DecodeIssue, T>;
25
+ export type Infer<D> = D extends Decoder<infer T> ? T : never;
26
+ export declare function isRecord(value: unknown): value is Record<string, unknown>;
27
+ /** Decodes `input`, reporting paths from `$`. */
28
+ export declare function decode<T>(decoder: Decoder<T>, input: unknown): {
29
+ result: Result<DecodeIssue, T>;
30
+ issues: DecodeIssue[];
31
+ };
32
+ export declare const string: Decoder<string>;
33
+ export declare const number: Decoder<number>;
34
+ export declare const boolean: Decoder<boolean>;
35
+ /** Any value, taken to be JSON: what is decoded was read from JSON. */
36
+ export declare const json: Decoder<Json>;
37
+ export declare function nullable<T>(decoder: Decoder<T>): Decoder<T | null>;
38
+ /** An absent field decodes to `fallback()`; an invalid one too, as an issue. */
39
+ export declare function withDefault<T>(decoder: Decoder<T>, fallback: () => T): Decoder<T>;
40
+ /** `decoder`'s values that pass `guard`; others fail as not `expected`. */
41
+ export declare function refine<A, B extends A>(decoder: Decoder<A>, guard: (value: A) => value is B, expected: string): Decoder<B>;
42
+ export declare function map<A, B>(decoder: Decoder<A>, f: (value: A) => B): Decoder<B>;
43
+ /** For recursive decoders. */
44
+ export declare function lazy<T>(decoder: () => Decoder<T>): Decoder<T>;
45
+ export declare function array<T>(item: Decoder<T>): Decoder<T[]>;
46
+ /** An array whose invalid items are dropped, as issues. */
47
+ export declare function arrayDroppingInvalid<T>(item: Decoder<T>): Decoder<T[]>;
48
+ /** A record whose invalid entries are dropped, as issues. */
49
+ export declare function recordDroppingInvalid<T>(entry: Decoder<T>): Decoder<Record<string, T>>;
50
+ type Fields = Record<string, Decoder<unknown>>;
51
+ type Decoded<F extends Fields> = {
52
+ [K in keyof F]: Infer<F[K]>;
53
+ };
54
+ /**
55
+ * An object with the given fields. An absent field is decoded from `undefined`, so
56
+ * `withDefault` can fill it in. Fields not listed are kept as they are.
57
+ */
58
+ export declare function object<F extends Fields>(fields: F): Decoder<Decoded<F>>;
59
+ /** One of several object shapes, told apart by the string field `tag`. */
60
+ export declare function taggedUnion<T>(tag: string, variants: Record<string, Decoder<T>>): Decoder<T>;
61
+ export {};
@@ -1,6 +1,7 @@
1
- import { FilterField, FilterControl, FilterExpr, FilterGroups } from './filters';
1
+ import { FilterField, FilterControl, FilterExpr, FilterGroups, FilterId } from './filters';
2
2
  import { FilterState, FormStateInitMode } from './state';
3
3
  import * as FilterValue from './filterValue';
4
+ import { type UndecodedFilterState } from './user-data-undecoded';
4
5
  export type FilterFormState = {
5
6
  type: 'leaf';
6
7
  value: FilterValue.FilterValue;
@@ -67,14 +68,29 @@ export declare function makeFilterFormStateSerializable(node: FilterFormState):
67
68
  * For customOperator controls we look at the nested `value` field inside { operator, value }.
68
69
  */
69
70
  export declare function isFilterEmpty(state: FilterFormState, schemaExpr: FilterExpr): boolean;
71
+ /**
72
+ * The filter state as stored: dates as ISO strings, and empty filters left out.
73
+ * Requires schema so emptiness can be evaluated correctly.
74
+ */
75
+ export declare function encodeFilterState(state: FilterState, filterGroups: FilterGroups): UndecodedFilterState;
70
76
  /**
71
77
  * Serialize a FilterState Map to a JSON object for persistence/sharing.
72
78
  * Requires schema so emptiness can be evaluated correctly.
73
79
  */
74
80
  export declare function serializeFilterFormStateMap(state: FilterState, filterGroups: FilterGroups): Record<string, any>;
81
+ export type FilterStateDecoding = {
82
+ state: FilterState;
83
+ /** Filters whose stored state no longer fit the schema and were reset. */
84
+ resetFilterIds: FilterId[];
85
+ };
86
+ /**
87
+ * Decodes stored filter state against the schema. Every filter of the schema gets a
88
+ * state; stored state for filters the schema no longer has is dropped.
89
+ */
90
+ export declare function decodeFilterState(stored: UndecodedFilterState, filterGroups: FilterGroups, missingFilterMode?: FormStateInitMode): FilterStateDecoding;
75
91
  /**
76
92
  * Parse serialized filter state (object keyed by filter id) back into a FilterState Map,
77
93
  * converting date string values to Date objects by consulting the filter schema.
78
94
  */
79
- export declare function parseFilterFormState(serializedState: any, filterGroups: FilterGroups, missingFilterMode?: FormStateInitMode): FilterState;
95
+ export declare function parseFilterFormState(serializedState: unknown, filterGroups: FilterGroups, missingFilterMode?: FormStateInitMode): FilterState;
80
96
  export {};
@@ -1,16 +1,28 @@
1
- import type { FilterGroups } from './filters';
2
1
  import { FilterState } from './state';
2
+ import { type UndecodedFilterState } from './user-data-undecoded';
3
+ import type { View, ViewId } from './view';
3
4
  /**
4
- * Encode filter state to a base64 URL-safe string
5
+ * A filter state shared in a URL, with the view it is for and the revision of that view's
6
+ * definition it was written for. Links from before views were named in them carry only
7
+ * the state: `view` is `null` then.
5
8
  */
6
- export declare function encodeFilterState(filterState: FilterState, filterGroups: FilterGroups): string;
9
+ export type SharedFilterState = {
10
+ view: ViewId | null;
11
+ definitionRevision: number;
12
+ state: UndecodedFilterState;
13
+ };
7
14
  /**
8
- * Decode filter state from a base64 URL-safe string
15
+ * Encode a view's filter state to a base64 URL-safe string
9
16
  */
10
- export declare function decodeFilterState(encodedState: string): unknown;
11
- export declare function createShareableUrl(filterState: FilterState, filterGroups: FilterGroups): string;
12
- export declare function createShareableUrlForSchema(filterState: FilterState, filterGroups: FilterGroups): string;
13
- export declare function setFilterInUrl(filterState: FilterState, filterGroups: FilterGroups): void;
17
+ /** What sharing needs of a view. */
18
+ export type SharedView = Pick<View, 'id' | 'filterGroups' | 'migrations'>;
19
+ export declare function encodeSharedFilterState(view: SharedView, filterState: FilterState): string;
20
+ /**
21
+ * Decode a filter state from a base64 URL-safe string. Throws when it is not one.
22
+ */
23
+ export declare function decodeSharedFilterState(encodedState: string): SharedFilterState;
24
+ export declare function createShareableUrl(view: SharedView, filterState: FilterState): string;
25
+ export declare function setFilterInUrl(view: SharedView, filterState: FilterState): void;
14
26
  /**
15
27
  * Copy URL to clipboard
16
28
  */
@@ -18,7 +30,7 @@ export declare function copyToClipboard(text: string): Promise<void>;
18
30
  /**
19
31
  * Get filter state from URL parameters
20
32
  */
21
- export declare function getFilterFromUrl(): unknown | null;
33
+ export declare function getFilterFromUrl(): SharedFilterState | null;
22
34
  /**
23
35
  * Remove filter parameter from URL without page reload
24
36
  */
@@ -2,6 +2,7 @@ import React from "react";
2
2
  import { CellRenderer, TableColumnDefinitionFooter } from "./column-definition";
3
3
  import { NoRowsComponent, RowExpansionRuntimeEntry } from "./view";
4
4
  import { QueryTransformContext, TransformResult, SuggestionFetcher } from "./filters";
5
+ import type { ViewMigrationChain } from "./view-migrations";
5
6
  export type Runtime = {
6
7
  cellRenderers: Record<string, CellRenderer>;
7
8
  queryTransforms: Record<string, {
@@ -13,4 +14,5 @@ export type Runtime = {
13
14
  customFilterComponents: Record<string, React.ComponentType<any>>;
14
15
  initialValues: Record<string, any>;
15
16
  suggestionFetchers: Record<string, SuggestionFetcher>;
17
+ viewMigrations?: Record<string, ViewMigrationChain>;
16
18
  };
@@ -1,20 +1,10 @@
1
- import { FilterGroups } from './filters';
1
+ import { FilterGroups, FilterId } from './filters';
2
2
  import { FilterState } from './state';
3
+ import type { UndecodedSavedFilter } from './user-data-undecoded';
3
4
  /**
4
5
  * Format revisions for saved filters
5
6
  */
6
7
  export declare const CURRENT_FORMAT_REVISION = "2025-09-19T00:00:00.000Z";
7
- /**
8
- * Raw saved filter data as stored in localStorage - using unknown for type safety
9
- */
10
- export interface SavedFilterJson {
11
- id: string;
12
- name: string;
13
- view: string;
14
- state: unknown;
15
- createdAt: string | Date;
16
- formatRevision: string;
17
- }
18
8
  /**
19
9
  * Parsed saved filter with properly typed state
20
10
  */
@@ -28,5 +18,11 @@ export interface SavedFilter {
28
18
  }
29
19
  export type SavedFilterId = SavedFilter['id'];
30
20
  export declare const SAVED_FILTERS_KEY = "dtvSavedFilters";
31
- export declare function fromSavedFilterJson(rawFilter: SavedFilterJson, filterGroups: FilterGroups): SavedFilter;
32
- export declare function toSavedFilterJson(savedFilter: SavedFilter, filterGroups: FilterGroups): SavedFilterJson;
21
+ export type SavedFilterDecoding = {
22
+ savedFilter: SavedFilter;
23
+ /** Filters whose stored state no longer fit the schema and were reset. */
24
+ resetFilterIds: FilterId[];
25
+ };
26
+ /** Decodes a saved filter of the view `viewId` against the view's filter schema. */
27
+ export declare function decodeSavedFilter(stored: UndecodedSavedFilter, viewId: string, filterGroups: FilterGroups): SavedFilterDecoding;
28
+ export declare function encodeSavedFilter(savedFilter: SavedFilter, filterGroups: FilterGroups): UndecodedSavedFilter;
@@ -12,6 +12,8 @@ export interface ViewUserData {
12
12
  readonly syncFilterState: boolean;
13
13
  readonly persistedFilterState: FilterState | null;
14
14
  readonly rowsPerPage: number | null;
15
+ readonly syncOrdering: boolean;
16
+ readonly ordering: DataOrdering | null;
15
17
  }
16
18
  /** A panel shown below the menu bar; one at a time. */
17
19
  export type Panel = 'filters' | 'savedFilters' | 'preferences';
@@ -41,6 +43,8 @@ export interface AppStateEnv {
41
43
  readonly filterGroups: (viewId: ViewId) => FilterGroups;
42
44
  /** The rows per page a user may pick; empty allows any. */
43
45
  readonly rowsPerPageOptions: readonly number[];
46
+ /** The fields a view's rows can be ordered by. */
47
+ readonly orderableFields: (viewId: ViewId) => readonly string[];
44
48
  }
45
49
  export type Msg =
46
50
  /** User data of `viewId` changed: written here, by another tab, or loaded. */
@@ -113,6 +117,10 @@ export type Command = {
113
117
  readonly tag: 'persistRowsPerPage';
114
118
  readonly viewId: ViewId;
115
119
  readonly rowsPerPage: number;
120
+ } | {
121
+ readonly tag: 'persistOrdering';
122
+ readonly viewId: ViewId;
123
+ readonly ordering: DataOrdering | null;
116
124
  };
117
125
  export interface AppStateInit {
118
126
  readonly viewId: ViewId;
@@ -1,6 +1,7 @@
1
1
  import type { FilterGroups } from './filters';
2
2
  import type { SavedFilter, SavedFilterId } from './saved-filters';
3
3
  import type { FilterState } from './state';
4
+ import type { DataOrdering } from './data-ordering';
4
5
  import type { UserPreferences } from './user-data';
5
6
  import { type UserDataManagerOptions } from './user-data-manager';
6
7
  import type { ViewId } from './view';
@@ -13,6 +14,8 @@ export declare function useUserDataManager(filterGroupsByViewId: Record<ViewId,
13
14
  setRowsPerPage: (viewId: ViewId, rowsPerPage: number) => Promise<import("./user-data").ViewData>;
14
15
  setColumnOrder: (viewId: ViewId, order: string[] | null) => Promise<import("./user-data").ViewData>;
15
16
  setHiddenColumns: (viewId: ViewId, hidden: string[]) => Promise<import("./user-data").ViewData>;
17
+ setSyncOrderingToUserData: (viewId: ViewId, enabled: boolean) => Promise<import("./user-data").ViewData>;
18
+ setOrdering: (viewId: ViewId, ordering: DataOrdering | null) => Promise<import("./user-data").ViewData>;
16
19
  setSyncFilterStateToUserData: (viewId: ViewId, enabled: boolean) => Promise<import("./user-data").ViewData>;
17
20
  setPersistedFilterState: (viewId: ViewId, filterState: FilterState | null) => Promise<import("./user-data").ViewData>;
18
21
  createFilter: (filter: Omit<SavedFilter, "id" | "createdAt" | "formatRevision">) => Promise<void>;
@@ -1,5 +1,8 @@
1
+ import type { FilterId } from './filters';
1
2
  import type { ShowToastOptions } from './toast';
3
+ import type { ViewResets } from './user-data';
2
4
  import type { UserDataStorageError } from './user-data-storage';
5
+ import type { ViewId } from './view';
3
6
  export declare const errorMessage: (err: unknown) => string;
4
7
  export declare function userDataStorageErrorToMessage(error: UserDataStorageError): string;
5
8
  export type UserDataManagerError = {
@@ -18,4 +21,9 @@ export type UserDataManagerError = {
18
21
  export declare function externalSaveFailed(message: string, cause?: unknown): UserDataManagerError;
19
22
  export declare function externalLoadFailed(message: string, cause?: unknown): UserDataManagerError;
20
23
  export declare function localStorageFailed(error: UserDataStorageError): UserDataManagerError;
24
+ /**
25
+ * Tells the user which filters were reset because their view's definition changed since
26
+ * they were stored. `filterLabel` names a filter of a view.
27
+ */
28
+ export declare function viewResetsToToast(resets: ViewResets[], filterLabel: (viewId: ViewId, filterId: FilterId) => string): ShowToastOptions;
21
29
  export declare function userDataManagerErrorToToast(err: UserDataManagerError): ShowToastOptions;
@@ -1,7 +1,8 @@
1
1
  import { FilterGroups } from './filters';
2
2
  import { SavedFilter, SavedFilterId } from './saved-filters';
3
3
  import type { FilterState } from './state';
4
- import { UserDataJson, UserPreferences, ViewData } from './user-data';
4
+ import type { DataOrdering } from './data-ordering';
5
+ import { UserDataJson, UserPreferences, ViewData, type ViewMigrationContext } from './user-data';
5
6
  import { ViewId } from './view';
6
7
  import type { ShowToastFn } from './toast';
7
8
  import { Result } from './result';
@@ -24,6 +25,8 @@ export interface UserDataManager {
24
25
  setColumnOrder(viewId: ViewId, order: string[] | null): Promise<ViewData>;
25
26
  setHiddenColumns(viewId: ViewId, hidden: string[] | null): Promise<ViewData>;
26
27
  setRowsPerPage(viewId: ViewId, rowsPerPage: number): Promise<ViewData>;
28
+ setSyncOrderingToUserData(viewId: ViewId, enabled: boolean): Promise<ViewData>;
29
+ setOrdering(viewId: ViewId, ordering: DataOrdering | null): Promise<ViewData>;
27
30
  setSyncFilterStateToUserData(viewId: ViewId, enabled: boolean): Promise<ViewData>;
28
31
  setPersistedFilterState(viewId: ViewId, filterState: FilterState | null): Promise<ViewData>;
29
32
  getSavedFilters(viewId: ViewId): SavedFilter[];
@@ -49,5 +52,7 @@ export type UserDataManagerOptions = {
49
52
  save?: UserDataSaveCallback;
50
53
  /** Toast function forwarded to load/save callbacks */
51
54
  showToast: ShowToastFn;
55
+ /** The migrations of views that have them, see `viewMigrationContext`. */
56
+ migrationsByViewId?: Record<ViewId, ViewMigrationContext>;
52
57
  };
53
58
  export declare function createUserDataManager(filterGroupsByViewId: Record<ViewId, FilterGroups>, options: UserDataManagerOptions): UserDataManager;
@@ -0,0 +1,86 @@
1
+ import type { DataOrdering } from './data-ordering';
2
+ import * as D from './decoder';
3
+ import type { Json } from './decoder';
4
+ import type { ViewId } from './view';
5
+ /**
6
+ * A leaf's value. `legacy` is a leaf written before filter values were stored as
7
+ * `empty | value` (2026-03-26): which `FilterValue` it stands for depends on the filter's
8
+ * control, so it is resolved when the view is decoded.
9
+ */
10
+ export type UndecodedFilterValue = {
11
+ type: 'empty';
12
+ } | {
13
+ type: 'value';
14
+ value: Json;
15
+ } | {
16
+ type: 'legacy';
17
+ raw: Json;
18
+ };
19
+ export type UndecodedFilterFormState = {
20
+ type: 'leaf';
21
+ value: UndecodedFilterValue;
22
+ } | {
23
+ type: 'and' | 'or';
24
+ children: UndecodedFilterFormState[];
25
+ } | {
26
+ type: 'not';
27
+ child: UndecodedFilterFormState;
28
+ };
29
+ /** Filter states by filter id. Filters left empty are not stored. */
30
+ export type UndecodedFilterState = Record<string, UndecodedFilterFormState>;
31
+ export type UndecodedSavedFilter = {
32
+ id: string;
33
+ name: string;
34
+ view: string;
35
+ createdAt: string;
36
+ formatRevision: string;
37
+ state: UndecodedFilterState;
38
+ };
39
+ export type UndecodedViewData = {
40
+ columnOrder: string[] | null;
41
+ hiddenColumns: string[];
42
+ rowsPerPage: number | null;
43
+ syncOrderingToUserData: boolean;
44
+ /** The ordering the user sorted by: a field the view orders by, not a column id. */
45
+ ordering: DataOrdering | null;
46
+ syncFilterStateToUserData: boolean;
47
+ persistedFilterState: UndecodedFilterState | null;
48
+ savedFilters: UndecodedSavedFilter[];
49
+ /** The revision of the view definition the data was written for. */
50
+ definitionRevision: number;
51
+ };
52
+ export type UserPreferences = {
53
+ /**
54
+ * When set, overrides the App option `syncFilterStateToUrl`.
55
+ * - `true`: always sync filter state to URL
56
+ * - `false`: never sync filter state to URL
57
+ * - `null`: use the App option
58
+ */
59
+ syncFilterStateToUrlOverride: boolean | null;
60
+ /**
61
+ * When enabled, closes the filters panel after applying the current filter state.
62
+ */
63
+ closeFilterPanelOnApply: boolean;
64
+ };
65
+ export type UserDataWithUndecodedViews = {
66
+ preferences: UserPreferences;
67
+ views: Record<ViewId, UndecodedViewData>;
68
+ /** Monotonic per-writer revision number, incremented on each persisted change. */
69
+ revision: number;
70
+ formatRevision: string;
71
+ };
72
+ /** The definition revision of data written before views had revisions, and of views without migrations. */
73
+ export declare const BASELINE_DEFINITION_REVISION = 1;
74
+ export declare const defaultUserPreferences: UserPreferences;
75
+ export declare function defaultUndecodedViewData(): UndecodedViewData;
76
+ export declare const undecodedFilterValue: D.Decoder<UndecodedFilterValue>;
77
+ export declare const undecodedFilterFormState: D.Decoder<UndecodedFilterFormState>;
78
+ /** A filter whose state cannot be read is dropped, as if it was never stored. */
79
+ export declare const undecodedFilterState: D.Decoder<UndecodedFilterState>;
80
+ export declare const undecodedSavedFilter: D.Decoder<UndecodedSavedFilter>;
81
+ export declare const dataOrdering: D.Decoder<DataOrdering>;
82
+ /** Lenient field by field: an invalid field falls back to its default. */
83
+ export declare const undecodedViewData: D.Decoder<UndecodedViewData>;
84
+ /** Lenient: an invalid preference falls back to its default. */
85
+ export declare const userPreferences: D.Decoder<UserPreferences>;
86
+ export declare const userDataWithUndecodedViews: D.Decoder<UserDataWithUndecodedViews>;