@itwin/saved-views-react 1.0.0 → 1.1.1

package/lib/applySavedView.d.ts

@@ -1,6 +1,6 @@
 import { ViewChangeOptions, ViewPose, ViewState, type IModelConnection, type Viewport } from "@itwin/core-frontend";
 import type { SavedViewData } from "./SavedView.js";
-import { type ApplyVisibilitySettings } from "./createViewState.js";
+import { ShowStrategy, type ApplyVisibilitySettings } from "./createViewState.js";
 import { type DefaultExtensionHandlersApplyOverrides } from "./translation/SavedViewsExtensionHandlers.js";
 export interface ApplySavedViewSettings {
     /**
@@ -49,6 +49,11 @@ export interface ApplySavedViewSettings {
      * @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") {
@@ -78,8 +78,16 @@ async function applyViewStateProps(viewStateProps, iModel, viewport, savedViewDa
     const viewState = await createViewStateFromProps(viewStateProps, iModel, savedViewData.viewData, {
         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/createViewState.d.ts

@@ -1,6 +1,7 @@
 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.
@@ -20,7 +21,7 @@ export interface ApplyVisibilitySettings {
  *   * `"hide"` – Hide (ie do not show) the elements in this list
  *   * `"ignore"` – Preserve current elements that are shown in viewport
  */
-type ShowStrategy = "show" | "hide" | "ignore";
+export type ShowStrategy = "show" | "hide" | "ignore";
 export interface ViewStateCreateSettings {
     /**
      * Normally {@link createViewState} function invokes and awaits {@linkcode ViewState.load}
@@ -53,6 +54,11 @@ export interface ViewStateCreateSettings {
      * @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
@@ -94,4 +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>;
-export {};
+/**
+ * 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

@@ -26,7 +26,10 @@ export async function createViewStateProps(iModel, viewData) {
 }
 async function applyViewStateOptions(viewState, iModel, viewData, settings = {}) {
     await applyModelSettings(iModel, viewState, viewData, settings.models);
-    await applyCategorySettings(iModel, viewState, viewData, settings.categories);
+    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();
     }
@@ -351,15 +354,14 @@ async function applyModelSettings(iModel, viewState, viewData, settings) {
     }
 }
 /**
- * Apply the category settings to the view state.
- * This function modifies the category selector of the view state based on the provided settings.
+ * 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 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.
+ * @returns A list of categories that should be added or dropped (ie visible or hidden).
  */
-async function applyCategorySettings(iModel, viewState, viewData, settings) {
+export async function sortCategories(iModel, viewData, settings) {
     const addCategories = [];
     const dropCategories = [];
     if (settings?.enabled === "show") {
@@ -386,10 +388,23 @@ async function applyCategorySettings(iModel, viewState, viewData, settings) {
             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;
     }
-    // Update model selector
+    // Update category selector
     const categorySelector = viewState.categorySelector.clone();
     categorySelector.addCategories(addCategories);
     categorySelector.dropCategories(dropCategories);

package/lib/translation/displayStyleExtractor.js

@@ -1,4 +1,4 @@
-import { applyExtraction, extractArray, extractArrayConditionally, extractBoolean, extractColor, extractColorLegacy, extractConditionally, extractLinePixels, extractNumber, extractNumberOrBool, extractObject, extractPlainTypedMap, extractRGB, extractSimpleArray, extractString, extractStringOrArray, extractStringOrNumber, extractStringOrNumberArray, isAnyColorFormat, simpleTypeOf, } from "./extractionUtilities.js";
+import { applyExtraction, extractArray, extractArrayConditionally, extractArrayElementsConditionally, extractBoolean, extractColor, extractColorLegacy, extractConditionally, extractLinePixels, extractNumber, extractNumberOrBool, extractObject, extractPlainTypedMap, extractRGB, extractSimpleArray, extractString, extractStringOrArray, extractStringOrNumber, extractStringOrNumberArray, isAnyColorFormat, simpleTypeOf, } from "./extractionUtilities.js";
 const viewFlagMappings = [
     extractNumber("renderMode"),
     extractBoolean("noConstructions", "noConstruct"),
@@ -411,7 +411,7 @@ const displayStylesLegacyMapping = [
     extractNumber("timePoint"),
     extractArray(displayStyleSubCategoryLegacyMappings, "subCategoryOvr", "subCategoryOverrides"),
     extractObject(backgroundMapMappings, "backgroundMap"),
-    extractArray(contextRealityModelsLegacyMappings, "contextRealityModels"),
+    extractArrayElementsConditionally((value) => value && !value.invisible, contextRealityModelsLegacyMappings, "contextRealityModels"),
     extractStringOrArray("excludedElements"),
     extractObject(mapImageryLegacyMapping, "mapImagery"),
     extractArray(displayStyleModelAppearanceLegacyMappings, "modelOvr", "modelOverrides"),

package/lib/translation/extractionUtilities.d.ts

@@ -185,6 +185,16 @@ export declare const extractConditionally: (params: ConditionalExtractParams[],
  * @param extractionFunc
  */
 export declare const extractArray: (extractionFunc: ExtractionFunc<void, void>[], from: string, to?: string) => (input: any, output: any) => void;
+/**
+ * Creates an extraction function that will extract each value of an array if it meets the given condition
+ * by using a single extraction function on each of the array values
+ * @param condition Function that checks if the value should be extracted
+ * @param extractionFunc Array of extraction functions to apply to each value in the array that meets the condition
+ * @param from Accessor string where the array is in the input object
+ * @param to Accessor string to store it in the output object
+ * @returns Function that extracts an array of values conditionally
+ */
+export declare const extractArrayElementsConditionally: (condition: (value: any) => boolean, extractionFunc: ExtractionFunc<void, void>[], from: string, to?: string) => (input: any, output: any) => void;
 /**
  * Creates an extraction function that will extract the values inside a 2D array from the given accessor
  * @param extractionFunc Extraction functions to apply to each entry in the array

package/lib/translation/extractionUtilities.js

@@ -439,6 +439,34 @@ export const extractArray = (extractionFunc, from, to) => {
         }
     };
 };
+/**
+ * Creates an extraction function that will extract each value of an array if it meets the given condition
+ * by using a single extraction function on each of the array values
+ * @param condition Function that checks if the value should be extracted
+ * @param extractionFunc Array of extraction functions to apply to each value in the array that meets the condition
+ * @param from Accessor string where the array is in the input object
+ * @param to Accessor string to store it in the output object
+ * @returns Function that extracts an array of values conditionally
+ */
+export const extractArrayElementsConditionally = (
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+condition, extractionFunc, from, to) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (input, output) => {
+        const adjustedTo = to ?? from;
+        if (input[from] !== undefined && Array.isArray(input[from])) {
+            output[adjustedTo] = [];
+            let outputIndex = 0;
+            input[from].forEach((_, index) => {
+                if (condition(input[from][index])) {
+                    output[adjustedTo].push({});
+                    extractionFunc.forEach((func) => func(input[from][index], output[adjustedTo][outputIndex]));
+                    outputIndex++;
+                }
+            });
+        }
+    };
+};
 /**
  * Creates an extraction function that will extract the values inside a 2D array from the given accessor
  * @param extractionFunc Extraction functions to apply to each entry in the array

package/package.json

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