@itwin/saved-views-react 0.9.8 → 1.1.0

package/lib/applySavedView.d.ts

@@ -1,5 +1,6 @@
 import { ViewChangeOptions, ViewPose, ViewState, type IModelConnection, type Viewport } from "@itwin/core-frontend";
 import type { SavedViewData } from "./SavedView.js";
+import { ShowStrategy, type ApplyVisibilitySettings } from "./createViewState.js";
 import { type DefaultExtensionHandlersApplyOverrides } from "./translation/SavedViewsExtensionHandlers.js";
 export interface ApplySavedViewSettings {
     /**
@@ -37,11 +38,22 @@ export interface ApplySavedViewSettings {
      */
     perModelCategoryVisibility?: ApplyStrategy | "clear" | undefined;
     /**
-     * How to handle visibility of models and categories that exist in iModel but
-     * are not captured in Saved View data.
-     * @default "hidden"
+     * How to handle the visibility of models that exist in iModel,
+     * including those not captured in Saved View data.
+     * @default '{ enabled: "ignore", disabled: "ignore", other: "ignore" }'
      */
-    modelAndCategoryVisibilityFallback?: "visible" | "hidden" | undefined;
+    models?: ApplyVisibilitySettings | undefined;
+    /**
+     * How to handle the visibility of categories that exist in iModel,
+     * including those not captured in Saved View data.
+     * @default '{ enabled: "ignore", disabled: "ignore", other: "ignore" }'
+     */
+    categories?: ApplyVisibilitySettings | undefined;
+    /**
+     * How to handle the visibility of subcategories that exist in iModel.
+     * @default "reset"
+     */
+    subcategories?: ShowStrategy | undefined;
     /**
      * Options forwarded to {@link Viewport.changeView}.
      * @default undefined

package/lib/applySavedView.js

@@ -5,7 +5,7 @@
 import { Camera, } from "@itwin/core-common";
 import { ViewPose, ViewPose2d, ViewPose3d, ViewState, } from "@itwin/core-frontend";
 import { YawPitchRollAngles } from "@itwin/core-geometry";
-import { createViewStateFromProps, createViewStateProps, } from "./createViewState.js";
+import { createViewStateFromProps, createViewStateProps, sortCategories, } from "./createViewState.js";
 import { extensionHandlers, } from "./translation/SavedViewsExtensionHandlers.js";
 async function createSeedViewStateProps(iModel, viewport, savedViewData, settings = {}) {
     if (settings.viewState !== "keep") {
@@ -61,15 +61,33 @@ function applyCameraOptions(seedViewStateProps, _iModel, viewport, savedViewData
     return seedViewStateProps;
 }
 async function applyViewStateProps(viewStateProps, iModel, viewport, savedViewData, settings) {
-    // We use "hidden" as the default value for modelAndCategoryVisibilityFallback
-    // because users expect modelSelector.enabled and categorySelector.enabled to
-    // act as exclusive whitelists when modelSelector.disabled or categorySelector.disabled
-    // arrays are empty, respectively.
-    const { modelAndCategoryVisibilityFallback = "hidden" } = settings;
+    // We use {enabled: "ignore", disabled: "ignore", other: "ignore"} as the default values
+    // for models and categories because users expect modelSelector.enabled and
+    // categorySelector.enabled to act as exclusive whitelists when modelSelector.disabled
+    // or categorySelector.disabled arrays are empty, respectively.
+    const models = {
+        enabled: settings.models?.enabled ?? "ignore",
+        disabled: settings.models?.disabled ?? "ignore",
+        other: settings.models?.other ?? "ignore",
+    };
+    const categories = {
+        enabled: settings.categories?.enabled ?? "ignore",
+        disabled: settings.categories?.disabled ?? "ignore",
+        other: settings.categories?.other ?? "ignore",
+    };
     const viewState = await createViewStateFromProps(viewStateProps, iModel, savedViewData.viewData, {
-        modelAndCategoryVisibilityFallback,
+        models,
+        categories,
+        subcategories: settings.subcategories ?? "ignore",
     });
     viewport.changeView(viewState, settings.viewChangeOptions);
+    if (settings.subcategories !== "ignore") {
+        // If subcategories are not ignored, we need to reset them here, 
+        // otherwise we might end up with subcategories not shown correctly
+        const { addCategories, dropCategories } = await sortCategories(iModel, savedViewData.viewData, categories);
+        viewport.changeCategoryDisplay(dropCategories, false);
+        viewport.changeCategoryDisplay(addCategories, true, settings.subcategories === "show");
+    }
 }
 /**
  * Updates {@linkcode viewport} state to match captured Saved View.

package/lib/captureSavedViewData.d.ts

@@ -35,8 +35,8 @@ interface CaptureSavedViewDataArgs {
  * }
  */
 export declare function captureSavedViewData(args: CaptureSavedViewDataArgs): Promise<SavedViewData>;
-export declare function queryMissingModels(iModel: IModelConnection, knownModels: Set<string>): Promise<string[]>;
+export declare function queryMissingModels(iModel: IModelConnection, knownModels?: Set<string>): Promise<string[]>;
 export declare function queryAllSpatiallyLocatedModels(iModel: IModelConnection): Promise<string[]>;
-export declare function queryMissingCategories(iModel: IModelConnection, knownCategories: Set<string>): Promise<Id64Array>;
+export declare function queryMissingCategories(iModel: IModelConnection, knownCategories?: Set<string>): Promise<Id64Array>;
 export declare function queryAllCategories(iModel: IModelConnection): Promise<string[]>;
 export {};

package/lib/captureSavedViewData.js

@@ -161,6 +161,9 @@ export async function queryMissingModels(iModel, knownModels) {
         return [];
     }
     const allModels = await queryAllSpatiallyLocatedModels(iModel);
+    if (!knownModels || knownModels.size === 0) {
+        return allModels;
+    }
     return allModels.filter((modelId) => !knownModels.has(modelId));
 }
 export async function queryAllSpatiallyLocatedModels(iModel) {
@@ -181,6 +184,9 @@ export async function queryMissingCategories(iModel, knownCategories) {
         return [];
     }
     const allCategories = await queryAllCategories(iModel);
+    if (!knownCategories || knownCategories.size === 0) {
+        return allCategories;
+    }
     return allCategories.filter((categoryId) => !knownCategories.has(categoryId));
 }
 export async function queryAllCategories(iModel) {

package/lib/createViewState.d.ts

@@ -1,6 +1,27 @@
 import { type ViewStateProps } from "@itwin/core-common";
 import { type IModelConnection, type ViewState } from "@itwin/core-frontend";
 import type { ViewData } from "./SavedView.js";
+import { Id64Array } from "@itwin/core-bentley";
+/**
+ * Settings for how to handle the visibility of elements (models or categories) in iModel.
+ *   * `enabled` – Enabled is the set of enabled elements (models or categories) that are stored in the saved view. Default is ignore.
+ *   * `disabled` – Disabled is the set of disabled elements (models or categories) that are stored in the saved view. Default is ignore.
+ *   * `other` – Other is the set of elements (models or categories) that are not stored in the saved view. Default is ignore.
+ *
+ * @default '{ enabled: "ignore", disabled: "ignore", other: "ignore" }'
+ */
+export interface ApplyVisibilitySettings {
+    enabled?: ShowStrategy | undefined;
+    disabled?: ShowStrategy | undefined;
+    other?: ShowStrategy | undefined;
+}
+/**
+ * Controls how models or categories are going to be altered.
+ *   * `"show"` – Show the elements in this list
+ *   * `"hide"` – Hide (ie do not show) the elements in this list
+ *   * `"ignore"` – Preserve current elements that are shown in viewport
+ */
+export type ShowStrategy = "show" | "hide" | "ignore";
 export interface ViewStateCreateSettings {
     /**
      * Normally {@link createViewState} function invokes and awaits {@linkcode ViewState.load}
@@ -14,11 +35,30 @@ export interface ViewStateCreateSettings {
      */
     skipViewStateLoad?: boolean | undefined;
     /**
-     * How to handle visibility of models and categories that exist in iModel but
-     * not captured in Saved View data.
-     * @default "hidden"
+     * How to handle the visibility of models that exist in iModel,
+     * including those not captured in Saved View data.
+     * Settings for how to handle the visibility of models in iModel.
+     *   * `enabled` – Enabled is the set of enabled models that are stored in the saved view. Default is ignore.
+     *   * `disabled` – Disabled is the set of disabled models that are stored in the saved view. Default is ignore.
+     *   * `other` – Other is the set of models that are not stored in the saved view. Default is ignore.
+     * @default '{ enabled: "ignore", disabled: "ignore", other: "ignore" }'
      */
-    modelAndCategoryVisibilityFallback?: "visible" | "hidden" | undefined;
+    models?: ApplyVisibilitySettings | undefined;
+    /**
+     * How to handle the visibility of categories that exist in iModel,
+     * including those not captured in Saved View data.
+     * Settings for how to handle the visibility of categories in iModel.
+     *   * `enabled` – Enabled is the set of enabled categories that are stored in the saved view. Default is ignore.
+     *   * `disabled` – Disabled is the set of disabled categories that are stored in the saved view. Default is ignore.
+     *   * `other` – Other is the set of categories that are not stored in the saved view. Default is ignore.
+     * @default '{ enabled: "ignore", disabled: "ignore", other: "ignore" }'
+     */
+    categories?: ApplyVisibilitySettings | undefined;
+    /**
+     * How to handle the visibility of subcategories that exist in iModel.
+     * @default "reset"
+     */
+    subcategories?: ShowStrategy | undefined;
 }
 /**
  * Creates {@link ViewStateProps} object out of Saved View data. It provides a lower-level
@@ -60,3 +100,15 @@ export declare function createViewStateFromProps(props: ViewStateProps, iModel:
  * await applySavedView(iModel, viewport, savedViewData);
  */
 export declare function createViewState(iModel: IModelConnection, viewData: ViewData, settings?: ViewStateCreateSettings): Promise<ViewState>;
+/**
+ * Determine, out of all categories in the iModel, which ones should be added or dropped
+ * (ie visible or hidden) based on the provided settings.
+ * @param iModel The current IModelConnection.
+ * @param viewData The view data containing the lists of enabled and disabled categories that will be applied.
+ * @param settings The settings for how to handle the visibility of enabled, disabled, and other category lists. Default is 'ignore' for all.
+ * @returns A list of categories that should be added or dropped (ie visible or hidden).
+ */
+export declare function sortCategories(iModel: IModelConnection, viewData: ViewData, settings?: ApplyVisibilitySettings): Promise<{
+    addCategories: Id64Array;
+    dropCategories: Id64Array;
+}>;

package/lib/createViewState.js

@@ -25,8 +25,10 @@ export async function createViewStateProps(iModel, viewData) {
     return viewStateProps;
 }
 async function applyViewStateOptions(viewState, iModel, viewData, settings = {}) {
-    if (settings.modelAndCategoryVisibilityFallback === "visible") {
-        await unhideNewModelsAndCategories(iModel, viewState, viewData);
+    await applyModelSettings(iModel, viewState, viewData, settings.models);
+    if (settings.subcategories === "ignore") {
+        // If subcategories are ignored, we apply category settings here instead of on the viewport.
+        await applyCategorySettings(iModel, viewState, viewData, settings.categories);
     }
     if (!settings.skipViewStateLoad) {
         await viewState.load();
@@ -300,27 +302,112 @@ async function getDefaultViewIdFromClassName(iModel, viewClassName) {
 function cloneCode({ spec, scope, value }) {
     return { spec, scope, value };
 }
-async function unhideNewModelsAndCategories(iModel, viewState, viewData) {
+/**
+ * Apply the model settings to the view state.
+ * This function modifies the model selector of the view state based on the provided settings.
+ * @param iModel The current IModelConnection.
+ * @param viewState The view state to modify.
+ * @param viewData The view data containing the lists of enabled and disabled models that will be applied.
+ * @param settings The settings for how to handle the visibility of enabled, disabled, and other model lists. Default is 'ignore' for all.
+ * @returns A promise that resolves when the model settings have been applied.
+ */
+async function applyModelSettings(iModel, viewState, viewData, settings) {
     if (viewData.type === "iTwin3d") {
         if (!viewState.isSpatialView()) {
             return;
         }
-        if (!viewData.categories?.disabled || !viewData.models?.disabled) {
+        const addModels = [];
+        const dropModels = [];
+        if (settings?.enabled === "show") {
+            addModels.push(...(viewData.models?.enabled ?? []));
+        }
+        else if (settings?.enabled === "hide") {
+            dropModels.push(...(viewData.models?.enabled ?? []));
+        }
+        if (settings?.disabled === "show") {
+            addModels.push(...(viewData.models?.disabled ?? []));
+        }
+        else if (settings?.disabled === "hide") {
+            dropModels.push(...(viewData.models?.disabled ?? []));
+        }
+        if (settings?.other !== "ignore") {
+            const otherModels = await queryMissingModels(iModel, new Set([
+                ...(viewData.models?.disabled ?? []),
+                ...(viewData.models?.enabled ?? []),
+            ]));
+            if (settings?.other === "show") {
+                addModels.push(...otherModels);
+            }
+            else if (settings?.other === "hide") {
+                dropModels.push(...otherModels);
+            }
+        }
+        if (addModels.length === 0 && dropModels.length === 0) {
             return;
         }
-        const [visibleCategories, visibleModels] = await Promise.all([
-            queryMissingCategories(iModel, new Set(viewData.categories.disabled)),
-            queryMissingModels(iModel, new Set(viewData.models.disabled)),
-        ]);
-        viewState.categorySelector.addCategories(visibleCategories);
+        // Update model selector
         const modelSelector = viewState.modelSelector.clone();
-        modelSelector.addModels(visibleModels);
+        modelSelector.addModels(addModels);
+        modelSelector.dropModels(dropModels);
         viewState.modelSelector = modelSelector;
         return;
     }
-    if (!viewData.categories?.disabled) {
+}
+/**
+ * Determine, out of all categories in the iModel, which ones should be added or dropped
+ * (ie visible or hidden) based on the provided settings.
+ * @param iModel The current IModelConnection.
+ * @param viewData The view data containing the lists of enabled and disabled categories that will be applied.
+ * @param settings The settings for how to handle the visibility of enabled, disabled, and other category lists. Default is 'ignore' for all.
+ * @returns A list of categories that should be added or dropped (ie visible or hidden).
+ */
+export async function sortCategories(iModel, viewData, settings) {
+    const addCategories = [];
+    const dropCategories = [];
+    if (settings?.enabled === "show") {
+        addCategories.push(...(viewData.categories?.enabled ?? []));
+    }
+    else if (settings?.enabled === "hide") {
+        dropCategories.push(...(viewData.categories?.enabled ?? []));
+    }
+    if (settings?.disabled === "show") {
+        addCategories.push(...(viewData.categories?.disabled ?? []));
+    }
+    else if (settings?.disabled === "hide") {
+        dropCategories.push(...(viewData.categories?.disabled ?? []));
+    }
+    if (settings?.other !== "ignore") {
+        const otherCategories = await queryMissingCategories(iModel, new Set([
+            ...(viewData.categories?.disabled ?? []),
+            ...(viewData.categories?.enabled ?? []),
+        ]));
+        if (settings?.other === "show") {
+            addCategories.push(...otherCategories);
+        }
+        else if (settings?.other === "hide") {
+            dropCategories.push(...otherCategories);
+        }
+    }
+    return { addCategories, dropCategories };
+}
+/**
+ * Apply the category settings to the view state.
+ * This function modifies the category selector of the view state based on the provided settings.
+ * @param iModel The current IModelConnection.
+ * @param viewState The view state to modify.
+ * @param viewData The view data containing the lists of enabled and disabled categories that will be applied.
+ * @param settings The settings for how to handle the visibility of enabled, disabled, and other category lists. Default is 'ignore' for all.
+ * @returns A promise that resolves when the category settings have been applied.
+ */
+async function applyCategorySettings(iModel, viewState, viewData, settings) {
+    const { addCategories, dropCategories } = await sortCategories(iModel, viewData, settings);
+    if (addCategories.length === 0 && dropCategories.length === 0) {
         return;
     }
-    const visibleCategories = await queryMissingCategories(iModel, new Set(viewData.categories.disabled));
-    viewState.categorySelector.addCategories(visibleCategories);
+    // Update category selector
+    const categorySelector = viewState.categorySelector.clone();
+    categorySelector.addCategories(addCategories);
+    categorySelector.dropCategories(dropCategories);
+    viewState.categorySelector = categorySelector;
+    return;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itwin/saved-views-react",
-  "version": "0.9.8",
+  "version": "1.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",