@itwin/saved-views-react 0.1.0

package/lib/useSavedViews.js

@@ -0,0 +1,514 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState, } from "react";
+/**
+ * Pulls Saved View data from a store and provides means to update and synchronize the data back to it. Interaction with
+ * the store is performed via {@linkcode SavedViewsClient} interface which could communicate, for instance, with
+ * [iTwin Saved Views API](https://developer.bentley.com/apis/savedviews/overview/) using `ITwinSavedViewsClient`.
+ *
+ * Note on the current implementation limitations. While the result of the first update action is reflected immediately,
+ * subsequent actions are put in a queue and executed serially. This may cause the UI to feel sluggish when user makes
+ * changes to Saved Views faster than the Saved Views store can be updated.
+ */
+export function useSavedViews(args) {
+    const onUpdateInProgress = useEvent(args.onUpdateInProgress ?? (() => { }));
+    const onUpdateComplete = useEvent(args.onUpdateComplete ?? (() => { }));
+    // eslint-disable-next-line no-console
+    const onUpdateError = useEvent(args.onUpdateError ?? ((error) => console.error(error)));
+    const [state, setState] = useState();
+    const providerRef = useRef({
+        mostRecentState: state,
+        actionQueue: [],
+        abortController: new AbortController(),
+    });
+    providerRef.current.mostRecentState = state;
+    const [provider, setProvider] = useState();
+    useEffect(() => {
+        const observer = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (!entry.isIntersecting) {
+                    continue;
+                }
+                const savedViewId = entry.target.dataset.savedViewId;
+                if (savedViewId) {
+                    void (async () => {
+                        let thumbnailUrl;
+                        try {
+                            thumbnailUrl = await args.client.getThumbnailUrl({ savedViewId, signal });
+                        }
+                        catch {
+                            thumbnailUrl = undefined;
+                        }
+                        if (signal.aborted) {
+                            return;
+                        }
+                        setState((prev) => {
+                            if (!prev) {
+                                return prev;
+                            }
+                            const newState = { ...prev };
+                            newState.savedViews = new Map(prev.savedViews);
+                            const prevSavedView = prev.savedViews.get(savedViewId);
+                            if (!prevSavedView) {
+                                return prev;
+                            }
+                            const newSavedView = { ...prevSavedView };
+                            newSavedView.thumbnail = thumbnailUrl;
+                            newState.savedViews.set(savedViewId, newSavedView);
+                            return newState;
+                        });
+                    })();
+                }
+            }
+        });
+        const abortController = new AbortController();
+        const signal = abortController.signal;
+        providerRef.current.abortController = abortController;
+        providerRef.current.actionQueue = [];
+        void (async () => {
+            try {
+                const result = await args.client.getSavedViewInfo({
+                    iTwinId: args.iTwinId,
+                    iModelId: args.iModelId,
+                    signal: signal,
+                });
+                if (signal.aborted) {
+                    return;
+                }
+                setState({
+                    savedViews: new Map(result.savedViews.map((savedView) => {
+                        if (savedView.thumbnail === undefined) {
+                            savedView.thumbnail = _jsx(ThumbnailPlaceholder, { savedViewId: savedView.id, observer: observer });
+                        }
+                        return [savedView.id, savedView];
+                    })),
+                    groups: new Map(result.groups.map((group) => [group.id, group])),
+                    tags: new Map(result.tags.map((tag) => [tag.id, tag])),
+                    thumbnails: new Map(),
+                });
+                setProvider(createSavedViewActions(args.iTwinId, args.iModelId, args.client, setState, providerRef, onUpdateInProgress, onUpdateComplete, onUpdateError));
+            }
+            catch (error) {
+                if (error.name !== "AbortError") {
+                    throw error;
+                }
+            }
+        })();
+        return () => {
+            abortController.abort();
+            observer.disconnect();
+        };
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [args.client, args.iModelId, args.iTwinId]);
+    if (state === undefined || provider === undefined) {
+        return undefined;
+    }
+    return {
+        savedViews: state.savedViews,
+        groups: state.groups,
+        tags: state.tags,
+        actions: provider,
+    };
+}
+// Loosely based on useEvent proposal https://github.com/reactjs/rfcs/blob/useevent/text/0000-useevent.md
+function useEvent(handleEvent) {
+    const handleEventRef = useRef(handleEvent);
+    handleEventRef.current = handleEvent;
+    return useCallback((...args) => handleEventRef.current(...args), []);
+}
+function createSavedViewActions(iTwinId, iModelId, client, setState, ref, onUpdateInProgress, onUpdateComplete, onUpdateError) {
+    const signal = ref.current.abortController.signal;
+    return {
+        createSavedView: actionWrapper(async (savedViewName, savedViewData) => {
+            const savedView = await client.createSavedView({
+                iTwinId: iTwinId,
+                iModelId: iModelId,
+                savedView: {
+                    displayName: savedViewName,
+                },
+                savedViewData,
+                signal,
+            });
+            updateSavedViews((savedViews) => savedViews.set(savedView.id, savedView));
+        }),
+        renameSavedView: actionWrapper(async (savedViewId, newName) => {
+            let prevName;
+            updateSavedView(savedViewId, (savedView) => {
+                prevName = savedView.displayName;
+                savedView.displayName = newName;
+            });
+            try {
+                const savedView = await client.updateSavedView({
+                    savedView: { id: savedViewId, displayName: newName },
+                    signal,
+                });
+                updateSavedView(savedViewId, () => savedView);
+            }
+            catch (error) {
+                if (prevName !== undefined) {
+                    const restoredDisplayName = prevName;
+                    updateSavedView(savedViewId, (savedView) => {
+                        savedView.displayName = restoredDisplayName;
+                    });
+                }
+                throw error;
+            }
+        }),
+        shareSavedView: actionWrapper(async (savedViewId, share) => {
+            const savedView = ref.current.mostRecentState.savedViews.get(savedViewId);
+            if (!savedView || savedView.shared === share) {
+                return;
+            }
+            updateSavedView(savedViewId, (savedView) => {
+                savedView.shared = share;
+            });
+            try {
+                const savedView = await client.updateSavedView({ savedView: { id: savedViewId, shared: share }, signal });
+                updateSavedView(savedView.id, () => savedView);
+            }
+            catch (error) {
+                updateSavedView(savedViewId, (savedView) => {
+                    savedView.shared = !share;
+                });
+                throw error;
+            }
+        }),
+        deleteSavedView: actionWrapper(async (savedViewId) => {
+            let prevSavedView;
+            updateSavedViews((savedViews) => {
+                prevSavedView = savedViews.get(savedViewId);
+                savedViews.delete(savedViewId);
+            });
+            try {
+                await client.deleteSavedView({ savedViewId, signal });
+            }
+            catch {
+                if (prevSavedView !== undefined) {
+                    const restoredSavedView = prevSavedView;
+                    updateSavedViews((savedViews) => {
+                        // The deleted view will return at the last position in the enumeration
+                        savedViews.set(savedViewId, restoredSavedView);
+                    });
+                }
+            }
+        }),
+        createGroup: actionWrapper(async (groupName) => {
+            const group = await client.createGroup({
+                iTwinId: iTwinId,
+                iModelId: iModelId,
+                group: { displayName: groupName },
+                signal,
+            });
+            updateGroups((groups) => groups.set(group.id, group));
+        }),
+        renameGroup: actionWrapper(async (groupId, newName) => {
+            let prevName;
+            updateGroup(groupId, (group) => {
+                prevName = group.displayName;
+                group.displayName = newName;
+            });
+            try {
+                const group = await client.updateGroup({ group: { id: groupId, displayName: newName }, signal });
+                updateGroup(group.id, () => group);
+            }
+            catch (error) {
+                if (prevName !== undefined) {
+                    const restoredDisplayName = prevName;
+                    updateGroup(groupId, (group) => {
+                        group.displayName = restoredDisplayName;
+                    });
+                }
+                throw error;
+            }
+        }),
+        shareGroup: actionWrapper(async (groupId, share) => {
+            const group = ref.current.mostRecentState.groups.get(groupId);
+            if (!group || group.shared === share) {
+                return;
+            }
+            updateGroup(groupId, (group) => {
+                group.shared = share;
+            });
+            try {
+                const group = await client.updateGroup({ group: { id: groupId, shared: share }, signal });
+                updateGroup(group.id, () => group);
+            }
+            catch (error) {
+                updateGroup(groupId, (group) => {
+                    group.shared = !share;
+                });
+                throw error;
+            }
+        }),
+        moveToGroup: actionWrapper(async (savedViewId, groupId) => {
+            let prevGroupId;
+            updateSavedView(savedViewId, (savedView) => {
+                prevGroupId = savedView.groupId;
+                savedView.groupId = groupId;
+            });
+            try {
+                const savedView = await client.updateSavedView({ savedView: { id: savedViewId, groupId }, signal });
+                updateSavedView(savedView.id, () => savedView);
+            }
+            catch (error) {
+                const restoredGroupId = prevGroupId;
+                updateSavedView(savedViewId, (savedView) => {
+                    savedView.groupId = restoredGroupId;
+                });
+                throw error;
+            }
+        }),
+        moveToNewGroup: actionWrapper(async (savedViewId, groupName) => {
+            const group = await client.createGroup({
+                iTwinId: iTwinId,
+                iModelId: iModelId,
+                group: { displayName: groupName },
+                signal,
+            });
+            if (signal.aborted) {
+                return;
+            }
+            updateGroups((groups) => groups.set(group.id, group));
+            let prevGroupId;
+            updateSavedView(savedViewId, (savedView) => {
+                prevGroupId = savedView.groupId;
+                savedView.groupId = group.id;
+            });
+            try {
+                const savedView = await client.updateSavedView({ savedView: { id: savedViewId, groupId: group.id }, signal });
+                updateSavedView(savedView.id, () => savedView);
+            }
+            catch (error) {
+                updateSavedView(savedViewId, (savedView) => {
+                    savedView.groupId = prevGroupId;
+                });
+                throw error;
+            }
+        }),
+        deleteGroup: actionWrapper(async (groupId) => {
+            let prevGroup;
+            updateGroups((groups) => {
+                prevGroup = groups.get(groupId);
+                groups.delete(groupId);
+            });
+            try {
+                await client.deleteGroup({ groupId, signal });
+            }
+            catch (error) {
+                if (prevGroup) {
+                    const restoredGroup = prevGroup;
+                    updateGroups((groups) => {
+                        // The deleted group will return at the last position in the enumeration
+                        groups.set(groupId, restoredGroup);
+                    });
+                }
+                throw error;
+            }
+        }),
+        addTag: actionWrapper(async (savedViewId, tagId) => {
+            let savedView = ref.current.mostRecentState.savedViews.get(savedViewId);
+            if (!savedView) {
+                return;
+            }
+            const tagIds = savedView.tagIds?.slice() ?? [];
+            tagIds.push(tagId);
+            tagIds.sort((a, b) => {
+                const aDisplayName = ref.current.mostRecentState.tags.get(a)?.displayName;
+                const bDisplayName = ref.current.mostRecentState.tags.get(b)?.displayName;
+                return aDisplayName?.toLowerCase().localeCompare(bDisplayName?.toLowerCase() ?? "") ?? -1;
+            });
+            let prevTagIds;
+            updateSavedView(savedViewId, (savedView) => {
+                prevTagIds = savedView.tagIds;
+                savedView.tagIds = tagIds;
+            });
+            try {
+                savedView = await client.updateSavedView({ savedView: { id: savedViewId, tagIds }, signal });
+                updateSavedView(savedView.id, () => savedView);
+            }
+            catch (error) {
+                updateSavedView(savedViewId, (savedView) => {
+                    savedView.tagIds = prevTagIds;
+                });
+                throw error;
+            }
+        }),
+        addNewTag: actionWrapper(async (savedViewId, tagName) => {
+            let savedView = ref.current.mostRecentState.savedViews.get(savedViewId);
+            if (!savedView) {
+                return;
+            }
+            const tag = await client.createTag({
+                iTwinId: iTwinId,
+                iModelId: iModelId,
+                displayName: tagName,
+                signal,
+            });
+            updateTags((tags) => {
+                tags.set(tag.id, tag);
+            });
+            const tagIds = savedView.tagIds?.slice() ?? [];
+            tagIds.push(tag.id);
+            tagIds.sort((a, b) => {
+                const aDisplayName = ref.current.mostRecentState.tags.get(a)?.displayName;
+                const bDisplayName = ref.current.mostRecentState.tags.get(b)?.displayName;
+                return aDisplayName?.toLowerCase().localeCompare(bDisplayName?.toLowerCase() ?? "") ?? -1;
+            });
+            let prevTagIds;
+            updateSavedView(savedViewId, (savedView) => {
+                prevTagIds = savedView.tagIds;
+                savedView.tagIds = tagIds;
+            });
+            try {
+                savedView = await client.updateSavedView({ savedView: { id: savedViewId, tagIds }, signal });
+                updateSavedView(savedView.id, () => savedView);
+            }
+            catch (error) {
+                updateSavedView(savedViewId, (savedView) => {
+                    savedView.tagIds = prevTagIds;
+                });
+                throw error;
+            }
+        }),
+        removeTag: actionWrapper(async (savedViewId, tagId) => {
+            let savedView = ref.current.mostRecentState.savedViews.get(savedViewId);
+            if (!savedView) {
+                return;
+            }
+            const tagIds = (savedView.tagIds ?? []).filter((id) => id !== tagId);
+            if (tagIds.length === (savedView.tagIds?.length ?? 0)) {
+                return;
+            }
+            let prevTagIds;
+            updateSavedView(savedViewId, (savedView) => {
+                prevTagIds = savedView.tagIds;
+                savedView.tagIds = tagIds;
+            });
+            try {
+                savedView = await client.updateSavedView({ savedView: { id: savedViewId, tagIds }, signal });
+                updateSavedView(savedView.id, () => savedView);
+            }
+            catch (error) {
+                updateSavedView(savedViewId, (savedView) => {
+                    savedView.tagIds = prevTagIds;
+                });
+                throw error;
+            }
+        }),
+    };
+    /** Serializes action execution and notifies when action processing begins and ends. Silences cancellation errors. */
+    function actionWrapper(callback) {
+        return async (...args) => {
+            ref.current.actionQueue.push(async () => {
+                if (signal.aborted) {
+                    return;
+                }
+                try {
+                    await callback(...args);
+                }
+                catch (error) {
+                    if (error && typeof error === "object" && "name" in error && error.name === "AbortError") {
+                        // It's a cancellation error
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            });
+            // If there are no other queued actions, start executing the queue
+            if (ref.current.actionQueue.length === 1) {
+                onUpdateInProgress();
+                // By the time the first action completes, other actions may have been queued
+                while (ref.current.actionQueue.length > 0) {
+                    try {
+                        await ref.current.actionQueue[0]();
+                    }
+                    catch (error) {
+                        onUpdateError(error);
+                    }
+                    finally {
+                        ref.current.actionQueue.shift();
+                    }
+                }
+                onUpdateComplete();
+            }
+        };
+    }
+    function updateSavedViews(callback) {
+        if (signal.aborted) {
+            return;
+        }
+        setState((prev) => {
+            const store = { ...prev };
+            store.savedViews = new Map(prev.savedViews);
+            callback(store.savedViews);
+            return store;
+        });
+    }
+    function updateSavedView(savedViewId, callback) {
+        if (signal.aborted) {
+            return;
+        }
+        setState((prev) => {
+            const store = { ...prev };
+            store.savedViews = new Map(prev.savedViews);
+            const prevSavedView = store.savedViews.get(savedViewId);
+            if (!prevSavedView) {
+                return prev;
+            }
+            const savedView = { ...prevSavedView };
+            store.savedViews.set(savedViewId, callback(savedView) ?? savedView);
+            return store;
+        });
+    }
+    function updateGroups(callback) {
+        if (signal.aborted) {
+            return;
+        }
+        setState((prev) => {
+            const store = { ...prev };
+            store.groups = new Map(prev.groups);
+            callback(store.groups);
+            return store;
+        });
+    }
+    function updateGroup(groupId, callback) {
+        if (signal.aborted) {
+            return;
+        }
+        setState((prev) => {
+            const store = { ...prev };
+            store.groups = new Map(prev.groups);
+            const prevGroup = store.groups.get(groupId);
+            if (!prevGroup) {
+                return prev;
+            }
+            const group = { ...prevGroup };
+            store.groups.set(groupId, callback(group) ?? group);
+            return store;
+        });
+    }
+    function updateTags(callback) {
+        if (signal.aborted) {
+            return;
+        }
+        setState((prev) => {
+            const store = { ...prev };
+            store.tags = new Map(prev.tags);
+            callback(store.tags);
+            return store;
+        });
+    }
+}
+function ThumbnailPlaceholder(props) {
+    const divRef = useRef(null);
+    useEffect(() => {
+        const div = divRef.current;
+        if (!div) {
+            return;
+        }
+        props.observer.observe(div);
+        return () => props.observer.unobserve(div);
+    }, [props.observer]);
+    return _jsx("div", { ref: divRef, "data-saved-view-id": props.savedViewId });
+}

package/lib/utils.d.ts

@@ -0,0 +1 @@
+export declare function trimInputString(string: string): string;

package/lib/utils.js

@@ -0,0 +1,7 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+export function trimInputString(string) {
+    return string.replace(/\s+/g, " ");
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@itwin/saved-views-react",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iTwin/saved-views.git",
+    "directory": "packages/saved-views-react"
+  },
+  "homepage": "https://github.com/iTwin/saved-views",
+  "author": {
+    "name": "Bentley Systems, Inc.",
+    "url": "https://www.bentley.com"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./experimental": {
+      "types": "./lib/experimental.d.ts",
+      "default": "./lib/experimental.js"
+    }
+  },
+  "files": [
+    "./lib",
+    "./public"
+  ],
+  "devDependencies": {
+    "@itwin/core-bentley": "^4.0.6",
+    "@itwin/core-common": "^4.0.6",
+    "@itwin/core-frontend": "^4.0.6",
+    "@itwin/core-geometry": "^4.0.6",
+    "@testing-library/react": "^12.1.5",
+    "@types/react": "^17.0.39",
+    "@types/recursive-readdir": "^2.2.2",
+    "@vitejs/plugin-react-swc": "^3.5.0",
+    "@vitest/coverage-v8": "^1.0.4",
+    "cpx2": "^5.0.0",
+    "happy-dom": "^10.5.2",
+    "npm-run-all": "^4.1.5",
+    "postcss-cli": "^10.1.0",
+    "postcss-modules": "^6.0.0",
+    "react": "^17.0.0",
+    "react-dom": "^17.0.0",
+    "recursive-readdir": "^2.2.3",
+    "typescript": "^5.1.6",
+    "vite": "^5.0.12",
+    "vitest": "^1.0.4"
+  },
+  "peerDependencies": {
+    "@itwin/core-common": "^4.0.6",
+    "@itwin/core-frontend": "^4.0.6",
+    "react": "^17.0.0 || ^18.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0"
+  },
+  "dependencies": {
+    "@itwin/itwinui-icons-react": "^2.4.0",
+    "@itwin/itwinui-react": "^3.0.11",
+    "fuse.js": "^6.6.2",
+    "@itwin/saved-views-client": "0.1.0"
+  },
+  "scripts": {
+    "build": "run-p build:*",
+    "build:transpile": "run-s build:transpile:*",
+    "build:transpile:client": "cd ../saved-views-client && npm run build",
+    "build:transpile:react": "tsc --project ./tsconfig.build.json",
+    "build:css": "postcss src/**/*.css --base ./src --dir ./lib",
+    "test": "vitest run --passWithNoTests",
+    "test:cover": "vitest run --coverage --passWithNoTests",
+    "test:watch": "vitest watch",
+    "typecheck": "tsc --noEmit"
+  }
+}