feat: add gallery state storage

iobuhov · leonardomendix · commit f8a90f1994f7 · 2025-07-14T13:09:21.000+02:00
diff --git a/packages/pluggableWidgets/gallery-web/src/Gallery.xml b/packages/pluggableWidgets/gallery-web/src/Gallery.xml
@@ -122,6 +122,37 @@
                 </property>
             </propertyGroup>
         </propertyGroup>
+        <propertyGroup caption="Personalization">
+            <propertyGroup caption="Configuration">
+                <property key="stateStorageType" type="enumeration" defaultValue="attribute">
+                    <caption>Store configuration in</caption>
+                    <description>When Browser local storage is selected, the configuration is scoped to a browser profile. This configuration is not tied to a Mendix user.</description>
+                    <enumerationValues>
+                        <enumerationValue key="attribute">Attribute</enumerationValue>
+                        <enumerationValue key="localStorage">Browser local storage</enumerationValue>
+                    </enumerationValues>
+                </property>
+                <property key="stateStorageAttr" type="attribute" required="false" onChange="onConfigurationChange">
+                    <caption>Attribute</caption>
+                    <description>Attribute containing the personalized configuration of the capabilities. This configuration is automatically stored and loaded. The attribute requires Unlimited String.</description>
+                    <attributeTypes>
+                        <attributeType name="String" />
+                    </attributeTypes>
+                </property>
+                <property key="storeFilters" type="boolean" defaultValue="true">
+                    <caption>Store filters</caption>
+                    <description />
+                </property>
+                <property key="storeSort" type="boolean" defaultValue="true">
+                    <caption>Store sort</caption>
+                    <description />
+                </property>
+                <property key="onConfigurationChange" type="action" required="false">
+                    <caption>On change</caption>
+                    <description />
+                </property>
+            </propertyGroup>
+        </propertyGroup>
         <propertyGroup caption="Accessibility">
             <propertyGroup caption="Aria labels">
                 <property key="filterSectionTitle" type="textTemplate" required="false">
diff --git a/packages/pluggableWidgets/gallery-web/src/stores/AttributeStorage.ts b/packages/pluggableWidgets/gallery-web/src/stores/AttributeStorage.ts
@@ -0,0 +1,51 @@
+import { PlainJs } from "@mendix/filter-commons/typings/settings";
+import { DerivedPropsGate } from "@mendix/widget-plugin-mobx-kit/props-gate";
+import { ReactiveController, ReactiveControllerHost } from "@mendix/widget-plugin-mobx-kit/reactive-controller";
+import { EditableValue } from "mendix";
+import { computed, makeObservable } from "mobx";
+import { ObservableStorage } from "src/typings/storage";
+
+type Gate = DerivedPropsGate<{
+    stateStorageAttr: EditableValue<string>;
+}>;
+
+export class AttributeStorage implements ObservableStorage, ReactiveController {
+    private readonly _gate: Gate;
+
+    constructor(host: ReactiveControllerHost, gate: Gate) {
+        host.addController(this);
+
+        this._gate = gate;
+        makeObservable<this, "_attribute">(this, {
+            _attribute: computed,
+            data: computed.struct
+        });
+    }
+
+    setup(): () => void {
+        return () => {};
+    }
+
+    private get _attribute(): EditableValue<string> {
+        return this._gate.props.stateStorageAttr;
+    }
+
+    get data(): PlainJs {
+        const jsonString = this._attribute.value;
+        if (!jsonString) {
+            return null;
+        }
+        try {
+            return JSON.parse(jsonString) as PlainJs;
+        } catch {
+            console.warn("Invalid JSON configuration in the attribute. Resetting configuration.");
+            this._attribute.setValue("");
+            return null;
+        }
+    }
+
+    setData(data: PlainJs): void {
+        data = data === "" ? null : data;
+        this._attribute.setValue(JSON.stringify(data, null, 2));
+    }
+}
diff --git a/packages/pluggableWidgets/gallery-web/src/stores/BrowserStorage.ts b/packages/pluggableWidgets/gallery-web/src/stores/BrowserStorage.ts
@@ -0,0 +1,18 @@
+import { PlainJs } from "@mendix/filter-commons/typings/settings";
+import { ObservableStorage } from "src/typings/storage";
+
+export class BrowserStorage implements ObservableStorage {
+    constructor(private readonly _storageKey: string) {}
+
+    get data(): PlainJs {
+        try {
+            return JSON.parse(localStorage.getItem(this._storageKey) ?? "null");
+        } catch {
+            return null;
+        }
+    }
+
+    setData(data: PlainJs): void {
+        localStorage.setItem(this._storageKey, JSON.stringify(data));
+    }
+}
diff --git a/packages/pluggableWidgets/gallery-web/src/stores/GalleryPersistentStateController.ts b/packages/pluggableWidgets/gallery-web/src/stores/GalleryPersistentStateController.ts
@@ -1,25 +1,22 @@
-import { Json, Serializable } from "@mendix/filter-commons/typings/settings";
+import { PlainJs, Serializable } from "@mendix/filter-commons/typings/settings";
 import { disposeBatch } from "@mendix/widget-plugin-mobx-kit/disposeBatch";
 import { ReactiveControllerHost } from "@mendix/widget-plugin-mobx-kit/reactive-controller";
 import { action, comparer, computed, makeObservable, reaction } from "mobx";
-import { ObservableJsonStorage } from "src/typings/storage";
-
-interface PersistentState {
-    version: 1;
-    [key: string]: Json;
-}
+import { ObservableStorage } from "src/typings/storage";
 
 interface GalleryPersistentStateControllerSpec {
     filtersHost: Serializable;
     sortHost: Serializable;
-    storage: ObservableJsonStorage;
+    storage: ObservableStorage;
 }
 
 export class GalleryPersistentStateController {
-    private readonly _storage: ObservableJsonStorage;
+    private readonly _storage: ObservableStorage;
     private readonly _filtersHost: Serializable;
     private readonly _sortHost: Serializable;
 
+    readonly schemaVersion: number = 1;
+
     constructor(host: ReactiveControllerHost, spec: GalleryPersistentStateControllerSpec) {
         host.addController(this);
         this._storage = spec.storage;
@@ -65,23 +62,26 @@ export class GalleryPersistentStateController {
         return disposeAll;
     }
 
-    private get _persistentState(): PersistentState {
+    private get _persistentState(): PlainJs {
         return this.toJSON();
     }
 
-    private _validate(data: Json): data is PersistentState {
-        if (data == null || typeof data !== "object" || !("version" in data) || data.version !== 1) {
+    private _validate(data: PlainJs): data is { [key: string]: PlainJs } {
+        if (data == null || typeof data !== "object" || !("version" in data) || data.version !== this.schemaVersion) {
             return false;
         }
         return true;
     }
 
-    fromJSON(data: PersistentState): void {
+    fromJSON(data: PlainJs): void {
+        if (!this._validate(data)) {
+            return;
+        }
         this._filtersHost.fromJSON(data.filters);
         this._sortHost.fromJSON(data.sort);
     }
 
-    toJSON(): PersistentState {
+    toJSON(): PlainJs {
         return {
             version: 1,
             filters: this._filtersHost.toJSON(),
diff --git a/packages/pluggableWidgets/gallery-web/src/stores/GalleryStore.ts b/packages/pluggableWidgets/gallery-web/src/stores/GalleryStore.ts
@@ -8,12 +8,17 @@ import { DerivedPropsGate } from "@mendix/widget-plugin-mobx-kit/props-gate";
 import { generateUUID } from "@mendix/widget-plugin-platform/framework/generate-uuid";
 import { SortAPI } from "@mendix/widget-plugin-sorting/react/context";
 import { SortStoreHost } from "@mendix/widget-plugin-sorting/stores/SortStoreHost";
-import { ListValue } from "mendix";
-import { PaginationEnum } from "../../typings/GalleryProps";
+import { EditableValue, ListValue } from "mendix";
+import { AttributeStorage } from "src/stores/AttributeStorage";
+import { BrowserStorage } from "src/stores/BrowserStorage";
+import { GalleryPersistentStateController } from "src/stores/GalleryPersistentStateController";
+import { ObservableStorage } from "src/typings/storage";
+import { PaginationEnum, StateStorageTypeEnum } from "../../typings/GalleryProps";
 import { QueryParamsController } from "../controllers/QueryParamsController";
 
 interface DynamicProps {
     datasource: ListValue;
+    stateStorageAttr?: EditableValue<string>;
 }
 
 interface StaticProps {
@@ -22,6 +27,9 @@ interface StaticProps {
     showTotalCount: boolean;
     pageSize: number;
     name: string;
+    stateStorageType: StateStorageTypeEnum;
+    storeFilters: boolean;
+    storeSort: boolean;
 }
 
 export type GalleryPropsGate = DerivedPropsGate<DynamicProps>;
@@ -32,6 +40,9 @@ type GalleryStoreSpec = StaticProps & {
 
 export class GalleryStore extends BaseControllerHost {
     private readonly _query: DatasourceController;
+    private readonly _filtersHost: CustomFilterHost;
+    private readonly _sortHost: SortStoreHost;
+    private _storage: ObservableStorage | null = null;
 
     readonly id: string = `GalleryStore@${generateUUID()}`;
     readonly name: string;
@@ -54,26 +65,49 @@ export class GalleryStore extends BaseControllerHost {
             showTotalCount: spec.showTotalCount
         });
 
-        const filterObserver = new CustomFilterHost();
-        const sortObserver = new SortStoreHost();
+        this._filtersHost = new CustomFilterHost();
+        this._sortHost = new SortStoreHost();
 
-        const paramCtrl = new QueryParamsController(this, this._query, filterObserver, sortObserver);
+        const paramCtrl = new QueryParamsController(this, this._query, this._filtersHost, this._sortHost);
 
         this.filterAPI = createContextWithStub({
-            filterObserver,
+            filterObserver: this._filtersHost,
             parentChannelName: this.id,
             sharedInitFilter: paramCtrl.unzipFilter(spec.gate.props.datasource.filter)
         });
 
         this.sortAPI = {
             version: 1,
-            host: sortObserver,
+            host: this._sortHost,
             initSortOrder: spec.gate.props.datasource.sortOrder
         };
 
         new RefreshController(this, {
             delay: 0,
             query: this._query.derivedQuery
         });
+
+        this.initStateController(spec, spec.gate);
+    }
+
+    initStateController(props: StaticProps, gate: GalleryPropsGate): void {
+        if (props.stateStorageType === "localStorage") {
+            this._storage = new BrowserStorage(this.name);
+        } else if (gate.props.stateStorageAttr) {
+            this._storage = new AttributeStorage(
+                this,
+                gate as DerivedPropsGate<{ stateStorageAttr: EditableValue<string> }>
+            );
+        }
+
+        if (!this._storage) {
+            return;
+        }
+
+        new GalleryPersistentStateController(this, {
+            storage: this._storage,
+            filtersHost: this._filtersHost,
+            sortHost: this._sortHost
+        });
     }
 }
diff --git a/packages/pluggableWidgets/gallery-web/src/typings/storage.ts b/packages/pluggableWidgets/gallery-web/src/typings/storage.ts
@@ -1,6 +1,6 @@
-import { Json } from "@mendix/filter-commons/typings/settings";
+import { PlainJs } from "@mendix/filter-commons/typings/settings";
 
-export interface ObservableJsonStorage {
-    data: Json;
-    setData(data: Json): void;
+export interface ObservableStorage {
+    data: PlainJs;
+    setData(data: PlainJs): void;
 }
diff --git a/packages/pluggableWidgets/gallery-web/typings/GalleryProps.d.ts b/packages/pluggableWidgets/gallery-web/typings/GalleryProps.d.ts
@@ -4,7 +4,7 @@
  * @author Mendix Widgets Framework Team
  */
 import { ComponentType, CSSProperties, ReactNode } from "react";
-import { ActionValue, DynamicValue, ListValue, ListActionValue, ListExpressionValue, ListWidgetValue, SelectionSingleValue, SelectionMultiValue } from "mendix";
+import { ActionValue, DynamicValue, EditableValue, ListValue, ListActionValue, ListExpressionValue, ListWidgetValue, SelectionSingleValue, SelectionMultiValue } from "mendix";
 
 export type ItemSelectionModeEnum = "toggle" | "clear";
 
@@ -18,6 +18,8 @@ export type ShowEmptyPlaceholderEnum = "none" | "custom";
 
 export type OnClickTriggerEnum = "single" | "double";
 
+export type StateStorageTypeEnum = "attribute" | "localStorage";
+
 export interface GalleryContainerProps {
     name: string;
     class: string;
@@ -42,6 +44,10 @@ export interface GalleryContainerProps {
     onClickTrigger: OnClickTriggerEnum;
     onClick?: ListActionValue;
     onSelectionChange?: ActionValue;
+    stateStorageType: StateStorageTypeEnum;
+    stateStorageAttr?: EditableValue<string>;
+    storeFilters: boolean;
+    storeSort: boolean;
     filterSectionTitle?: DynamicValue<string>;
     emptyMessageTitle?: DynamicValue<string>;
     ariaLabelListBox?: DynamicValue<string>;
@@ -78,6 +84,11 @@ export interface GalleryPreviewProps {
     onClickTrigger: OnClickTriggerEnum;
     onClick: {} | null;
     onSelectionChange: {} | null;
+    stateStorageType: StateStorageTypeEnum;
+    stateStorageAttr: string;
+    storeFilters: boolean;
+    storeSort: boolean;
+    onConfigurationChange: {} | null;
     filterSectionTitle: string;
     emptyMessageTitle: string;
     ariaLabelListBox: string;
diff --git a/packages/shared/filter-commons/src/typings/settings.ts b/packages/shared/filter-commons/src/typings/settings.ts
@@ -8,9 +8,9 @@ export type FilterData = InputData | SelectData | null | undefined;
 
 export type FiltersSettingsMap<T> = Map<T, FilterData>;
 
-export type Json = string | number | boolean | null | Json[] | { [key: string]: Json };
+export type PlainJs = string | number | boolean | null | PlainJs[] | { [key: string]: PlainJs };
 
 export interface Serializable {
-    toJSON(): Json;
-    fromJSON(data: Json): void;
+    toJSON(): PlainJs;
+    fromJSON(data: PlainJs): void;
 }
diff --git a/packages/shared/widget-plugin-filtering/src/stores/generic/CustomFilterHost.ts b/packages/shared/widget-plugin-filtering/src/stores/generic/CustomFilterHost.ts
@@ -1,5 +1,5 @@
 import { tag } from "@mendix/filter-commons/condition-utils";
-import { FilterData, FiltersSettingsMap, Json, Serializable } from "@mendix/filter-commons/typings/settings";
+import { FilterData, FiltersSettingsMap, PlainJs, Serializable } from "@mendix/filter-commons/typings/settings";
 import { FilterCondition } from "mendix/filters";
 import { and } from "mendix/filters/builders";
 import { autorun, makeAutoObservable } from "mobx";
@@ -47,11 +47,11 @@ export class CustomFilterHost implements ObservableFilterHost, Serializable {
         }
     }
 
-    toJSON(): Json {
-        return [...this.settings.entries()] as Json[];
+    toJSON(): PlainJs {
+        return [...this.settings.entries()] as PlainJs;
     }
 
-    fromJSON(data: Json): void {
+    fromJSON(data: PlainJs): void {
         if (data == null || !Array.isArray(data)) {
             return;
         }
diff --git a/packages/shared/widget-plugin-sorting/src/__tests__/SortStoreHost.spec.ts b/packages/shared/widget-plugin-sorting/src/__tests__/SortStoreHost.spec.ts
@@ -12,7 +12,8 @@ describe("SortStoreHost", () => {
             sortOrder: [
                 [attrId("attr1"), "asc"],
                 [attrId("attr2"), "desc"]
-            ] as SortInstruction[]
+            ] as SortInstruction[],
+            setSortOrder: jest.fn()
         };
     });
 
@@ -58,7 +59,8 @@ describe("SortStoreHost", () => {
 
         it("should replace previously observed store", () => {
             const anotherMockStore: ObservableSortStore = {
-                sortOrder: [[attrId("attr3"), "asc"]] as SortInstruction[]
+                sortOrder: [[attrId("attr3"), "asc"]] as SortInstruction[],
+                setSortOrder: jest.fn()
             };
 
             sortStoreHost.observe(mockStore);
@@ -203,7 +205,8 @@ describe("SortStoreHost", () => {
 
         it("should handle store changes after observation", () => {
             const mutableStore = {
-                sortOrder: [[attrId("attr1"), "asc"]] as SortInstruction[]
+                sortOrder: [[attrId("attr1"), "asc"]] as SortInstruction[],
+                setSortOrder: jest.fn()
             };
 
             sortStoreHost.observe(mutableStore);
diff --git a/packages/shared/widget-plugin-sorting/src/controllers/SingleSortController.ts b/packages/shared/widget-plugin-sorting/src/controllers/SingleSortController.ts
diff --git a/packages/shared/widget-plugin-sorting/src/stores/SortOrderStore.ts b/packages/shared/widget-plugin-sorting/src/stores/SortOrderStore.ts
diff --git a/packages/shared/widget-plugin-sorting/src/stores/SortStoreHost.ts b/packages/shared/widget-plugin-sorting/src/stores/SortStoreHost.ts
diff --git a/packages/shared/widget-plugin-sorting/src/types/store.ts b/packages/shared/widget-plugin-sorting/src/types/store.ts

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`import { tag } from "@mendix/filter-commons/condition-utils";`
`2`		`-import { FilterData, FiltersSettingsMap, Json, Serializable } from "@mendix/filter-commons/typings/settings";`
	`2`	`+import { FilterData, FiltersSettingsMap, PlainJs, Serializable } from "@mendix/filter-commons/typings/settings";`
`3`	`3`	`import { FilterCondition } from "mendix/filters";`
`4`	`4`	`import { and } from "mendix/filters/builders";`
`5`	`5`	`import { autorun, makeAutoObservable } from "mobx";`
`@@ -47,11 +47,11 @@ export class CustomFilterHost implements ObservableFilterHost, Serializable {`
`47`	`47`	`}`
`48`	`48`	`}`
`49`	`49`
`50`		`- toJSON(): Json {`
`51`		`- return [...this.settings.entries()] as Json[];`
	`50`	`+ toJSON(): PlainJs {`
	`51`	`+ return [...this.settings.entries()] as PlainJs;`
`52`	`52`	`}`
`53`	`53`
`54`		`- fromJSON(data: Json): void {`
	`54`	`+ fromJSON(data: PlainJs): void {`
`55`	`55`	`if (data == null \|\| !Array.isArray(data)) {`
`56`	`56`	`return;`
`57`	`57`	`}`