@genesislcap/foundation-workspace 15.78.2 → 15.79.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.
@@ -3,7 +3,6 @@ import type { ColumnApi } from '@ag-grid-community/core';
3
3
  import { Connect } from '@genesislcap/foundation-comms';
4
4
  import type { Container } from '@genesislcap/web-core';
5
5
  import { FoundationElement } from '@genesislcap/web-core';
6
- import type { FoundationLayout } from '@genesislcap/foundation-layout';
7
6
  import type { GridApi } from '@ag-grid-community/core';
8
7
  import { InterfaceSymbol } from '@microsoft/fast-foundation';
9
8
  import { KVStorage } from '@genesislcap/foundation-comms';
@@ -11,23 +10,80 @@ import { Modal } from '@genesislcap/foundation-ui';
11
10
  import type { SerialisedLayout } from '@genesislcap/foundation-layout';
12
11
 
13
12
  /**
13
+ * Default filter registry implementation.
14
+ *
15
+ * @remarks
16
+ * Keeps a store of every filter's last known value by key, so a workspace covers filters that
17
+ * aren't currently mounted (e.g. on another route):
18
+ * - `unregisterFilter` stores the filter's last value; `registerFilter` applies any stored value.
19
+ * - `applyFiltersValues` (workspace load) replaces the store with the loaded values and applies
20
+ * them to mounted filters; unmounted ones pick theirs up when they register.
21
+ * - `getAllFiltersValues` (workspace save) returns the store with mounted filters' live values on
22
+ * top, so a filter the user never visited keeps its loaded value rather than being dropped.
14
23
  * @alpha
15
24
  */
16
25
  export declare class DefaultFilterRegistry implements FilterRegistry {
17
26
  private filters;
27
+ private stored;
18
28
  registerFilter(filterKey: string, getFilterValue: () => SavedFilterValue | null, setFilterValue: (value: string) => void): void;
19
29
  unregisterFilter(filterKey: string): void;
20
30
  getAllFiltersValues(): SavedFilterValue[];
21
31
  applyFiltersValues(filtersValues: SavedFilterValue[]): void;
32
+ private readValue;
22
33
  }
23
34
 
24
35
  /**
36
+ * Default grid registry implementation.
37
+ *
38
+ * @remarks
39
+ * Keeps a store of every grid's last known column state and filter model by key, so a workspace
40
+ * covers grids that aren't currently mounted (e.g. on another route):
41
+ * - `unregisterGrid` stores the grid's last state; `registerGrid` applies any stored state.
42
+ * - `applyAllGridsSettings` (workspace load) replaces the store with the loaded settings and
43
+ * applies them to mounted grids; unmounted ones pick theirs up when they register.
44
+ * - `getAllGridsSettings` (workspace save) returns the store with mounted grids' live state on
45
+ * top, so a grid the user never visited keeps its loaded state rather than being dropped.
46
+ *
47
+ * Filters race with the grid's own start-up. grid-pro restores its persisted filter model
48
+ * (`persist-filter-model-key`) asynchronously, up to three times — at grid ready, once
49
+ * datasource-driven columns exist, and on the datasource's `filtersRestored` — and a restore with
50
+ * nothing stored applies `{}`, clearing every filter. A filter for a column that doesn't exist yet
51
+ * is dropped. So when the registry applies a filter model it:
52
+ * 1. writes it into the grid's own filter persistence first (`filterPersistence`), so grid-pro's
53
+ * later restores, including a datasource re-init long after start-up, return the workspace's
54
+ * model rather than an older one;
55
+ * 2. arms a guard that re-applies it if a programmatic filter change (e.g. a restore that read
56
+ * storage before step 1 landed, as KV storage can) replaces it, and when the grid's columns
57
+ * change (so filters on columns that arrive late apply). The guard ends as soon as the user
58
+ * changes a filter, once the grid has been quiet for `filterSettleMs` after its last start-up
59
+ * event, and in any case after `filterGuardMaxMs`, so it never fights app code for long. It
60
+ * re-applies at most `maxFilterReapplies` times per arming, so it cannot loop.
61
+ *
62
+ * The guard can't tell grid-pro's restores from the app's own programmatic filter changes (both
63
+ * are `source: 'api'`), so an app that calls `setFilterModel` or clears filters while the guard
64
+ * runs has that change reverted. Since `{}` is saved for unfiltered grids, every grid with a
65
+ * stored entry is guarded when it registers.
66
+ *
67
+ * A saved entry without `filterModel` (a workspace saved before filters were captured) leaves the
68
+ * grid's filters alone.
25
69
  * @alpha
26
70
  */
27
71
  export declare class DefaultGridRegistry implements GridRegistry {
72
+ /** Quiet period after the last start-up event before the filter guard ends. */
73
+ filterSettleMs: number;
74
+ /** Longest the filter guard runs after it is armed, however often it is re-armed. */
75
+ filterGuardMaxMs: number;
76
+ /** Most re-applies the filter guard makes per arming. */
77
+ maxFilterReapplies: number;
28
78
  private grids;
29
- private cachedSettings;
30
- registerGrid(gridKey: string, gridApi: unknown, columnApi: unknown): void;
79
+ private stored;
80
+ private listeners;
81
+ private guards;
82
+ /** Registrations whose first data has rendered or whose filters the user has changed. */
83
+ private settled;
84
+ registerGrid(gridKey: string, gridApi: unknown, columnApi: unknown, filterPersistence?: GridFilterPersistence): void;
85
+ /** Applies the stored settings for a grid, unless it already has exactly that state. */
86
+ private applyStoredSettings;
31
87
  getGrid(gridKey: string): GridRegistration | null;
32
88
  unregisterGrid(gridKey: string): void;
33
89
  getAllGridsSettings(): SavedGridSettings[];
@@ -35,20 +91,81 @@ export declare class DefaultGridRegistry implements GridRegistry {
35
91
  applyColumns?: boolean;
36
92
  applyFilters?: boolean;
37
93
  }): Promise<boolean>;
38
- applyAllGridsSettings(gridsSettings: SavedGridSettings[], maxRetries?: number): Promise<void>;
94
+ applyAllGridsSettings(gridsSettings: SavedGridSettings[]): Promise<void>;
95
+ /**
96
+ * Writes a filter model into the grid's own persistence, then onto the grid, and records what
97
+ * the grid reports back so the guard can tell a later replacement from AG Grid's normalisation.
98
+ */
99
+ private applyFilterModel;
100
+ private reapplyStoredFilter;
101
+ /**
102
+ * Whether the grid's filter model moved away from what the registry last applied — a stale
103
+ * restore or other programmatic change, rather than AG Grid normalising the applied model (which
104
+ * reads back the same each time).
105
+ */
106
+ private filterWasReplaced;
107
+ private armFilterGuard;
108
+ /** Restarts the settle timer: the grid just did something that can precede a stale restore. */
109
+ private touchFilterGuard;
110
+ private guardActive;
111
+ private endFilterGuard;
112
+ private addListener;
113
+ private removeListener;
114
+ /**
115
+ * Stores a grid's live state over its stored entry, except what the grid can't report yet:
116
+ * - nothing, once its API is destroyed (grid-pro destroys the outgoing grid before the new one
117
+ * re-registers, and a destroyed v36 API returns `undefined` rather than throwing);
118
+ * - the stored column state and filter model while the grid has no columns: before datasource
119
+ * columns exist, and after a datasource restart clears them (AG Grid then drops every filter,
120
+ * before grid-pro rebuilds the grid). With nothing stored, the filter model is left out, so the
121
+ * next registration leaves grid-pro to restore its own persisted filters;
122
+ * - the stored filter model until the first data renders or the user filters, since before that
123
+ * the grid may not have applied it yet (its columns or grid-pro's restore still pending).
124
+ */
125
+ private storeSnapshot;
126
+ /** Removes a registration's grid listeners and stops its filter guard. */
127
+ private detach;
128
+ /** Whether the grid already has exactly these settings, so re-applying them is a no-op. */
129
+ private hasSettings;
130
+ private readFilterModel;
39
131
  private getGridSettings;
40
132
  }
41
133
 
42
134
  /**
43
135
  * Default layout registry implementation.
136
+ *
137
+ * @remarks
138
+ * Keeps a store of every layout's last known config by key, so a workspace covers layouts that
139
+ * aren't currently mounted (e.g. on another route):
140
+ * - `unregisterLayout` stores the layout's last config; `registerLayout` loads any stored config
141
+ * once the layout has finished its first load (so its declared or autosaved layout doesn't
142
+ * overwrite it).
143
+ * - `applySavedLayouts` (workspace load) replaces the store with the loaded configs and loads them
144
+ * into mounted layouts; unmounted ones pick theirs up when they register.
145
+ * - `getLayoutsConfigs` (workspace save) returns the store with mounted layouts' live configs on
146
+ * top, so a layout the user never visited keeps its loaded config rather than being dropped.
44
147
  * @alpha
45
148
  */
46
149
  export declare class DefaultLayoutRegistry implements LayoutRegistry {
47
150
  private layouts;
48
- registerLayout(layoutKey: string, layout: FoundationLayout): void;
151
+ private stored;
152
+ /** Layouts with a stored-config load queued for their first load. */
153
+ private waiting;
154
+ registerLayout(layoutKey: string, layout: WorkspaceLayout): void;
49
155
  unregisterLayout(layoutKey: string): void;
50
156
  getLayoutsConfigs(): SavedLayout[];
51
157
  applySavedLayouts(savedLayouts: SavedLayout[]): Promise<void>;
158
+ /**
159
+ * A layout's config is only meaningful once it has finished its first load; before that it has
160
+ * no panes yet, and storing that would wipe the saved config.
161
+ */
162
+ private readLayout;
163
+ /**
164
+ * Loads a layout's stored config once it has finished its first load. The config is read at load
165
+ * time, so a workspace loaded while waiting wins, and a layout waiting already isn't queued twice;
166
+ * nothing loads into a layout that has since unregistered or been replaced under its key.
167
+ */
168
+ private loadStored;
52
169
  }
53
170
 
54
171
  /**
@@ -103,14 +220,24 @@ export declare interface FilterRegistry {
103
220
  export declare const FilterRegistry: InterfaceSymbol<FilterRegistry>;
104
221
 
105
222
  /**
106
- * Registers an AG Grid instance so workspace state can apply/load it.
223
+ * The part of a grid element that persists its own filter model, e.g. grid-pro's
224
+ * `setFilterModel` (backed by `persist-filter-model-key`, or an in-memory cache without one).
225
+ * @alpha
226
+ */
227
+ export declare interface GridFilterPersistence {
228
+ setFilterModel(filterModel: Record<string, unknown>): unknown;
229
+ }
230
+
231
+ /**
232
+ * Registers an AG Grid instance so workspace state can apply/load it. Registering applies the
233
+ * grid's stored column state (from the loaded workspace, or its last state this session) — see
234
+ * `DefaultGridRegistry`.
107
235
  * @alpha
108
236
  */
109
237
  export declare class GridRegister extends FoundationElement {
110
238
  gridKey: string;
111
239
  designSystemPrefix: string;
112
240
  gridRegistry: GridRegistry;
113
- workspaceState: WorkspaceState;
114
241
  /** `<prefix>-grid-pro` is the AG Grid v36 `GridPro` by default; `GridProLegacy` is the v29 grid. */
115
242
  private gridElement;
116
243
  private gridApi;
@@ -122,13 +249,6 @@ export declare class GridRegister extends FoundationElement {
122
249
  private readonly handleGridReady;
123
250
  private attachToGridApis;
124
251
  private detachFromGridApis;
125
- private loadWorkspaceSettings;
126
- /**
127
- * Column state comes from `gridApi` on AG Grid v36 and from `columnApi` on v29; mirrors the
128
- * fallback `GridRegistry` uses when saving.
129
- */
130
- private readColumnState;
131
- private loadWorkspaceColumnState;
132
252
  }
133
253
 
134
254
  /**
@@ -138,13 +258,15 @@ export declare interface GridRegistration {
138
258
  gridKey: string;
139
259
  gridApi: GridApi;
140
260
  columnApi: ColumnApi;
261
+ /** The grid element's own filter persistence, when the grid has one (grid-pro does). */
262
+ filterPersistence?: GridFilterPersistence;
141
263
  }
142
264
 
143
265
  /**
144
266
  * @alpha
145
267
  */
146
268
  export declare interface GridRegistry {
147
- registerGrid(gridKey: string, gridApi: unknown, columnApi: unknown): void;
269
+ registerGrid(gridKey: string, gridApi: unknown, columnApi: unknown, filterPersistence?: GridFilterPersistence): void;
148
270
  getGrid(gridKey: string): GridRegistration | null;
149
271
  unregisterGrid(gridKey: string): void;
150
272
  getAllGridsSettings(): SavedGridSettings[];
@@ -212,7 +334,13 @@ export declare interface SavedFilterValue {
212
334
  */
213
335
  export declare interface SavedGridSettings {
214
336
  gridKey: string;
337
+ /** AG Grid column state; includes sort (`sort`/`sortIndex`) as well as order, width, visibility. */
215
338
  columnState: any[];
339
+ /**
340
+ * AG Grid filter model (`gridApi.getFilterModel()`); `{}` when no filters are set. Absent on
341
+ * workspaces saved before filters were captured, which then leave the grid's filters alone.
342
+ */
343
+ filterModel?: Record<string, unknown>;
216
344
  savedAt: string;
217
345
  }
218
346
 
@@ -271,6 +399,25 @@ export declare const workspaceComponents: {
271
399
  register(container?: Container, ...rest: any[]): void;
272
400
  };
273
401
 
402
+ /**
403
+ * What the layout registry needs from a registered layout. `rapid-layout` (`FoundationLayout`)
404
+ * satisfies it as-is; adapters make other layout libraries saveable, e.g.
405
+ * `useWorkspaceFlexLayout` in `@genesislcap/foundation-react-utils/workspace` for flexlayout-react.
406
+ * @alpha
407
+ */
408
+ export declare interface WorkspaceLayout {
409
+ /** Whether the layout has finished its first load; its config is only read after that. */
410
+ hasFirstLoaded: boolean;
411
+ /** Returns the layout's current config (serialisable JSON) for a workspace to save. */
412
+ getLayout(): SerialisedLayout;
413
+ /** Replaces the layout with a saved config. */
414
+ loadLayout(layout: SerialisedLayout, handleMissingItem?: 'placeholder' | 'error', disableCache?: boolean): void;
415
+ /** Used to wait for `first-loaded` when `hasFirstLoaded` is still false. */
416
+ addEventListener(type: string, listener: () => void, options?: {
417
+ once?: boolean;
418
+ }): void;
419
+ }
420
+
274
421
  /**
275
422
  * Workspace persistence UI (save/load + share/delete shared workspaces).
276
423
  * @alpha
@@ -306,6 +453,12 @@ export declare class WorkspaceManager extends FoundationElement {
306
453
  refreshSharedWorkspaces(): Promise<void>;
307
454
  private notifyError;
308
455
  saveWorkspace(): Promise<void>;
456
+ /**
457
+ * Seeds every registry's store with the workspace's entries (replacing whatever was stored,
458
+ * even when a list is empty) and applies them to what's mounted; unmounted grids, layouts and
459
+ * filters pick theirs up when they register. Grids and filters are seeded before layouts:
460
+ * loading a layout rebuilds its panes, and the grids/filters inside re-register straight away.
461
+ */
309
462
  private applyWorkspace;
310
463
  loadWorkspace(workspaceName: string): Promise<void>;
311
464
  private requestSharedWorkspace;
package/dist/react.cjs CHANGED
@@ -15,18 +15,18 @@ const WorkspaceManager = React.forwardRef(function WorkspaceManager(props, ref)
15
15
  return React.createElement(customElements.getName(WorkspaceManagerWC) ?? 'workspace-manager', { ...rest, ref }, children);
16
16
  });
17
17
 
18
- const GridRegister = React.forwardRef(function GridRegister(props, ref) {
18
+ const LayoutWrapper = React.forwardRef(function LayoutWrapper(props, ref) {
19
19
  const { children, ...rest } = props;
20
- return React.createElement(customElements.getName(GridRegisterWC) ?? 'grid-register', { ...rest, ref }, children);
20
+ return React.createElement(customElements.getName(LayoutWrapperWC) ?? 'layout-register', { ...rest, ref }, children);
21
21
  });
22
22
 
23
- const LayoutWrapper = React.forwardRef(function LayoutWrapper(props, ref) {
23
+ const GridRegister = React.forwardRef(function GridRegister(props, ref) {
24
24
  const { children, ...rest } = props;
25
- return React.createElement(customElements.getName(LayoutWrapperWC) ?? 'layout-register', { ...rest, ref }, children);
25
+ return React.createElement(customElements.getName(GridRegisterWC) ?? 'grid-register', { ...rest, ref }, children);
26
26
  });
27
27
 
28
28
  module.exports = {
29
29
  WorkspaceManager,
30
- GridRegister,
31
30
  LayoutWrapper,
31
+ GridRegister,
32
32
  };
package/dist/react.mjs CHANGED
@@ -13,12 +13,12 @@ export const WorkspaceManager = React.forwardRef(function WorkspaceManager(props
13
13
  return React.createElement(customElements.getName(WorkspaceManagerWC) ?? 'workspace-manager', { ...rest, ref }, children);
14
14
  });
15
15
 
16
- export const GridRegister = React.forwardRef(function GridRegister(props, ref) {
16
+ export const LayoutWrapper = React.forwardRef(function LayoutWrapper(props, ref) {
17
17
  const { children, ...rest } = props;
18
- return React.createElement(customElements.getName(GridRegisterWC) ?? 'grid-register', { ...rest, ref }, children);
18
+ return React.createElement(customElements.getName(LayoutWrapperWC) ?? 'layout-register', { ...rest, ref }, children);
19
19
  });
20
20
 
21
- export const LayoutWrapper = React.forwardRef(function LayoutWrapper(props, ref) {
21
+ export const GridRegister = React.forwardRef(function GridRegister(props, ref) {
22
22
  const { children, ...rest } = props;
23
- return React.createElement(customElements.getName(LayoutWrapperWC) ?? 'layout-register', { ...rest, ref }, children);
23
+ return React.createElement(customElements.getName(GridRegisterWC) ?? 'grid-register', { ...rest, ref }, children);
24
24
  });
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@genesislcap/foundation-workspace",
3
3
  "description": "Genesis Foundation Workspace Components and State",
4
- "version": "15.78.2",
4
+ "version": "15.79.0",
5
5
  "sideEffects": false,
6
6
  "license": "SEE LICENSE IN license.txt",
7
7
  "main": "dist/esm/index.js",
@@ -48,22 +48,22 @@
48
48
  }
49
49
  },
50
50
  "devDependencies": {
51
- "@genesislcap/foundation-testing": "15.78.2",
52
- "@genesislcap/genx": "15.78.2",
53
- "@genesislcap/ts-builder": "15.78.2",
54
- "@genesislcap/uvu-playwright-builder": "15.78.2",
55
- "@genesislcap/vite-builder": "15.78.2",
56
- "@genesislcap/webpack-builder": "15.78.2"
51
+ "@genesislcap/foundation-testing": "15.79.0",
52
+ "@genesislcap/genx": "15.79.0",
53
+ "@genesislcap/ts-builder": "15.79.0",
54
+ "@genesislcap/uvu-playwright-builder": "15.79.0",
55
+ "@genesislcap/vite-builder": "15.79.0",
56
+ "@genesislcap/webpack-builder": "15.79.0"
57
57
  },
58
58
  "dependencies": {
59
59
  "@ag-grid-community/core": "29.2.0",
60
- "@genesislcap/foundation-comms": "15.78.2",
61
- "@genesislcap/foundation-layout": "15.78.2",
62
- "@genesislcap/foundation-notifications": "15.78.2",
63
- "@genesislcap/foundation-ui": "15.78.2",
64
- "@genesislcap/foundation-utils": "15.78.2",
65
- "@genesislcap/grid-pro": "15.78.2",
66
- "@genesislcap/web-core": "15.78.2"
60
+ "@genesislcap/foundation-comms": "15.79.0",
61
+ "@genesislcap/foundation-layout": "15.79.0",
62
+ "@genesislcap/foundation-notifications": "15.79.0",
63
+ "@genesislcap/foundation-ui": "15.79.0",
64
+ "@genesislcap/foundation-utils": "15.79.0",
65
+ "@genesislcap/grid-pro": "15.79.0",
66
+ "@genesislcap/web-core": "15.79.0"
67
67
  },
68
68
  "repository": {
69
69
  "type": "git",