@kronor/dtv 9.4.3 → 9.5.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.
@@ -6,6 +6,7 @@ import { UserDataJson, UserPreferences, ViewData, type ViewMigrationContext } fr
6
6
  import { ViewId } from './view';
7
7
  import type { ShowToastFn } from './toast';
8
8
  import { Result } from './result';
9
+ import type { DTVAnalyticsEventPayload } from './analytics';
9
10
  import { USER_DATA_LOCALSTORAGE_KEY } from './user-data-storage';
10
11
  export { USER_DATA_LOCALSTORAGE_KEY };
11
12
  export interface UserDataManager {
@@ -14,6 +15,12 @@ export interface UserDataManager {
14
15
  * Useful for callers that need to await remote/user-provided hydration.
15
16
  */
16
17
  ready: Promise<void>;
18
+ /**
19
+ * Sends the manager's analytics events to `track`, the ones that waited first. Until it is
20
+ * called they wait: a component may create managers it then does not use (StrictMode does),
21
+ * and those load too.
22
+ */
23
+ reportTo(track: (event: UserDataAnalyticsEvent) => void): void;
17
24
  /**
18
25
  * Re-reads the user data another tab wrote to localStorage, so this tab works from
19
26
  * that revision and content. Meant for a `storage` event listener.
@@ -30,9 +37,9 @@ export interface UserDataManager {
30
37
  setSyncFilterStateToUserData(viewId: ViewId, enabled: boolean): Promise<ViewData>;
31
38
  setPersistedFilterState(viewId: ViewId, filterState: FilterState | null): Promise<ViewData>;
32
39
  getSavedFilters(viewId: ViewId): SavedFilter[];
33
- createFilter(filter: Omit<SavedFilter, 'id' | 'createdAt' | 'formatRevision'>): Promise<void>;
34
- updateFilter(viewId: ViewId, savedFilterId: SavedFilterId, updates: Partial<Pick<SavedFilter, 'name' | 'state'>>): Promise<void>;
35
- deleteFilter(viewId: ViewId, savedFilterId: SavedFilterId): Promise<void>;
40
+ createFilter(filter: Omit<SavedFilter, 'id' | 'createdAt' | 'formatRevision'>): Promise<SavedFilter>;
41
+ updateFilter(viewId: ViewId, savedFilterId: SavedFilterId, updates: Partial<Pick<SavedFilter, 'name' | 'state'>>): Promise<boolean>;
42
+ deleteFilter(viewId: ViewId, savedFilterId: SavedFilterId): Promise<boolean>;
36
43
  }
37
44
  export interface UserDataLoadAPI {
38
45
  showToast?: ShowToastFn;
@@ -55,4 +62,8 @@ export type UserDataManagerOptions = {
55
62
  /** The migrations of views that have them, see `viewMigrationContext`. */
56
63
  migrationsByViewId?: Record<ViewId, ViewMigrationContext>;
57
64
  };
65
+ /** The analytics events the user data manager reports. */
66
+ export type UserDataAnalyticsEvent = Extract<DTVAnalyticsEventPayload, {
67
+ readonly type: 'userDataLoad' | 'userDataSaveFailed' | 'userDataConflict' | 'userDataReadOnly';
68
+ }>;
58
69
  export declare function createUserDataManager(filterGroupsByViewId: Record<ViewId, FilterGroups>, options: UserDataManagerOptions): UserDataManager;
@@ -7,7 +7,7 @@ import { type DecodeIssue } from './decoder';
7
7
  import { Result } from './result';
8
8
  import { type UndecodedViewData, type UserDataWithUndecodedViews, type UserPreferences } from './user-data-undecoded';
9
9
  import { type UserDataJsonObject, type UserDataMigrationError } from './user-data.migrations';
10
- import { type ViewMigrationChain } from './view-migrations';
10
+ import { type SnapshotDiff, type ViewMigrationChain } from './view-migrations';
11
11
  import { type ViewProjection } from './view-projection';
12
12
  export { INITIAL_USERDATA_FORMAT_REVISION, REVISION_2026_01_05, REVISION_2026_01_29, REVISION_2026_03_26, REVISION_2026_05_06, REVISION_2026_10_25 } from './user-data.migrations';
13
13
  export { defaultUserPreferences, type UserPreferences } from './user-data-undecoded';
@@ -113,6 +113,8 @@ export type ViewMigrationContext = {
113
113
  chain: ViewMigrationChain;
114
114
  /** The projection of the live definition, to compare with the chain's latest snapshot. */
115
115
  live: ViewProjection;
116
+ /** How the view's filters differ from the latest snapshot; empty when it is up to date. */
117
+ snapshotDiff: SnapshotDiff;
116
118
  };
117
119
  /**
118
120
  * The migration context of a view with migrations. Logs an error when the view's filters
@@ -122,11 +124,19 @@ export type ViewMigrationContext = {
122
124
  * absent columns are harmless; `dtv definitions check` compares them.
123
125
  */
124
126
  export declare function viewMigrationContext(view: View): ViewMigrationContext | undefined;
127
+ /** A view of this app whose stored data was kept as stored instead of read. */
128
+ export type RetainedView = {
129
+ viewId: ViewId;
130
+ /** `newerRevision`: written for a revision of its definition this app does not know. */
131
+ reason: 'newerRevision' | 'decodeFailed';
132
+ };
125
133
  export type ViewsDecoding = {
126
134
  userData: UserData;
127
135
  resets: ViewResets[];
128
136
  /** Whether view-level migrations changed any view's data. */
129
137
  migrated: boolean;
138
+ /** Views of this app kept as stored. Views it does not define are kept without being listed. */
139
+ retained: RetainedView[];
130
140
  };
131
141
  /**
132
142
  * Decodes the views this app defines; the others are retained. Views with migrations are
@@ -99,6 +99,17 @@ export declare const noResets: () => MigrationResets;
99
99
  * Data at or past the latest revision is returned as it is.
100
100
  */
101
101
  export declare function migrateViewData(chain: ViewMigrationChain, data: UndecodedViewData): ViewDataMigration;
102
+ /** How a view's filters differ from its latest snapshot, when `dtv definitions snapshot` was not run for a change. */
103
+ export type SnapshotDiff = {
104
+ /** In both, with another definition: their stored state is reset. */
105
+ readonly changed: readonly FilterId[];
106
+ /** Only in the view; nothing was stored for them. */
107
+ readonly added: readonly FilterId[];
108
+ /** Only in the snapshot; their stored state is kept, as for any filter the view lacks. */
109
+ readonly removed: readonly FilterId[];
110
+ };
111
+ export declare function filtersChangedSinceSnapshot(latest: ViewProjection, live: ViewProjection): SnapshotDiff;
112
+ export declare function isSnapshotDiffEmpty(diff: SnapshotDiff): boolean;
102
113
  /**
103
114
  * Drops the stored state of filters whose definition differs from the chain's latest
104
115
  * snapshot: the definition changed and no migration was generated for it yet, so the
@@ -109,5 +120,11 @@ export declare function resetFiltersChangedSinceSnapshot(latest: ViewProjection,
109
120
  export declare function currentDefinitionRevision(chain: ViewMigrationChain | undefined): number;
110
121
  /** A single filter state (e.g. a shared one) taken from `revision` to the chain's latest. */
111
122
  export declare function migrateFilterState(chain: ViewMigrationChain, revision: number, state: UndecodedFilterState): UndecodedFilterState;
123
+ /**
124
+ * The id the filter `filterId` of `revision` has in the chain's latest revision, following
125
+ * renames; `null` when it was dropped since, or the latest revision has no such filter. A
126
+ * filter that was reset keeps its id: what was stored for it may have meant something else.
127
+ */
128
+ export declare function latestFilterId(chain: ViewMigrationChain, revision: number, filterId: FilterId): FilterId | null;
112
129
  /** The definition ids older snapshots had, latest first, other than the latest's. */
113
130
  export declare function previousDefinitions(chain: ViewMigrationChain): string[];
@@ -7,6 +7,8 @@ export { getViewRootFieldName, getViewStaticArgs } from '../framework/view';
7
7
  export type { ViewJson, ColumnDefinitionJson } from '../framework/view';
8
8
  export type { ViewProjection, FilterProjection, ColumnProjection, ControlProjection } from '../framework/view-projection';
9
9
  export type { ViewMigration, ViewMigrationChain } from '../framework/view-migrations';
10
+ export { currentDefinitionRevision, latestFilterId, migrateFilterState } from '../framework/view-migrations';
11
+ export type { UndecodedFilterState } from '../framework/user-data-undecoded';
10
12
  export { projectView, projectionsEqual } from '../framework/view-projection';
11
13
  export { checkMigration } from '../framework/view-migrations';
12
14
  export type { RowExpansionDefinition, RowExpansionRenderer, RowExpansionRendererProps, RowExpansionRuntimeEntry, } from '../framework/view';
@@ -25,6 +27,8 @@ export { rowType } from '../dsl/columns';
25
27
  export type { UserDataJson } from '../framework/user-data';
26
28
  export type { UserDataLoadAPI, UserDataSaveAPI, UserDataLoadCallback, UserDataSaveCallback } from '../framework/user-data-manager';
27
29
  export type { ActionDefinition, ActionAPI, ActionUserDataAPI } from '../framework/actions';
30
+ export type { DTVAnalytics, DTVAnalyticsEvent, DTVAnalyticsEventBase, DTVAnalyticsEventPayload, DTVAnalyticsEventType, DTVAnalyticsSpan, DTVAnalyticsError, DTVAnalyticsPanel, DTVAnalyticsResets, DTVAnalyticsRetainedView, DTVAnalyticsUserDataError, FiltersAppliedTrigger, FetchReason } from '../framework/analytics';
31
+ export type { FetchErrorInfo, FetchErrorKind } from '../framework/fetch-error';
28
32
  export type { HasuraFilterObject, HasuraOperator, HasuraOperatorFor, HasuraComparable, HasuraFilterExpression, GraphQLVariable, HasuraOrderBy, GraphQLSelectionSetItem, GraphQLSelectionSet, GraphQLQueryAST, } from '../framework/graphql';
29
33
  export type { DataOrdering } from '../framework/data-ordering';
30
34
  export type { OrderDirection } from '../framework/order-direction';