@itwin/saved-views-react 0.5.0 → 0.7.0

package/lib/translation/displayStyleExtractor.js

@@ -1,4 +1,4 @@
-import { applyExtraction, extractArray, extractArrayConditionally, extractBoolean, extractColor, extractColorLegacy, extractConditionally, extractNumber, extractNumberOrBool, extractObject, extractPlainTypedMap, extractRGB, extractSimpleArray, extractString, extractStringOrArray, extractStringOrNumber, extractStringOrNumberArray, isAnyColorFormat, simpleTypeOf, } from "./extractionUtilities.js";
+import { applyExtraction, extractArray, extractArrayConditionally, 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"),
@@ -14,9 +14,18 @@ const viewFlagMappings = [
     extractBoolean("hiddenEdges", "hidEdges"),
     extractBoolean("shadows"),
     extractBoolean("clipVolume", "clipVol"),
+    extractBoolean("hiddenLineMaterialColors", "hlMatColors"),
     extractBoolean("monochrome"),
     extractBoolean("backgroundMap"),
     extractBoolean("ambientOcclusion"),
+    extractBoolean("acs"),
+    extractBoolean("thematicDisplay"),
+    extractBoolean("wiremesh"),
+    extractBoolean("forceSurfaceDiscard"),
+    extractBoolean("noWhiteOnWhiteReversal"),
+    extractBoolean("noSolarLight"),
+    extractBoolean("noSourceLights"),
+    extractBoolean("noCameraLights"),
 ];
 const viewFlagLegacyMappings = [
     extractNumber("renderMode"),
@@ -33,9 +42,18 @@ const viewFlagLegacyMappings = [
     extractBoolean("hidEdges", "hiddenEdges"),
     extractBoolean("shadows"),
     extractBoolean("clipVol", "clipVolume"),
+    extractBoolean("hlMatColors", "hiddenLineMaterialColors"),
     extractBoolean("monochrome"),
     extractBoolean("backgroundMap"),
     extractBoolean("ambientOcclusion"),
+    extractBoolean("acs"),
+    extractBoolean("thematicDisplay"),
+    extractBoolean("wiremesh"),
+    extractBoolean("forceSurfaceDiscard"),
+    extractBoolean("noWhiteOnWhiteReversal"),
+    extractBoolean("noSolarLight"),
+    extractBoolean("noSourceLights"),
+    extractBoolean("noCameraLights"),
 ];
 const planarClipMaskMappings = [
     extractNumber("mode"),
@@ -93,7 +111,7 @@ export const featureAppearanceMappings = [
     extractRGB("rgb"),
     extractNumber("weight"),
     extractNumber("transparency"),
-    extractNumber("linePixels"),
+    extractLinePixels("linePixels"),
     extractBoolean("ignoresMaterial"),
     extractBoolean("nonLocatable"),
     extractBoolean("emphasized"),
@@ -102,7 +120,7 @@ export const featureAppearanceLegacyMappings = [
     extractColorLegacy("rgb"),
     extractNumber("weight"),
     extractNumber("transparency"),
-    extractNumber("linePixels"),
+    extractLinePixels("linePixels"),
     extractBoolean("ignoresMaterial"),
     extractBoolean("nonLocatable"),
     extractBoolean("emphasized"),
@@ -284,6 +302,56 @@ const hiddenLineSettingsLegacyMappings = [
     extractObject(hiddenLineStyleLegacyMappings, "hidden"),
     extractNumber("transThreshold", "transparencyThreshold"),
 ];
+const keyColorPropsMappings = [
+    extractNumber("value"),
+    extractColor("color"),
+];
+const keyColorPropsLegacyMappings = [
+    extractNumber("value"),
+    extractColorLegacy("color"),
+];
+const thematicGradientSettingsPropsMappings = [
+    extractNumber("mode"),
+    extractNumber("stepCount"),
+    extractColor("marginColor"),
+    extractNumber("colorScheme"),
+    extractArray(keyColorPropsMappings, "customKeys"),
+    extractNumber("colorMix"),
+    extractNumber("transparencyMode"),
+];
+const thematicGradientSettingsPropsLegacyMappings = [
+    extractNumber("mode"),
+    extractNumber("stepCount"),
+    extractColorLegacy("marginColor"),
+    extractNumber("colorScheme"),
+    extractArray(keyColorPropsLegacyMappings, "customKeys"),
+    extractNumber("colorMix"),
+    extractNumber("transparencyMode"),
+];
+const thematicDisplaySensorPropsMappings = [
+    extractSimpleArray(simpleTypeOf("number"), "position"),
+    extractNumber("value"),
+];
+const thematicDisplaySensorSettingsPropsMappings = [
+    extractArray(thematicDisplaySensorPropsMappings, "sensors"),
+    extractNumber("distanceCutoff"),
+];
+const thematicDisplaySettingsMappings = [
+    extractNumber("displayMode"),
+    extractObject(thematicGradientSettingsPropsMappings, "gradientSettings"),
+    extractSimpleArray(simpleTypeOf("number"), "range"),
+    extractSimpleArray(simpleTypeOf("number"), "axis"),
+    extractSimpleArray(simpleTypeOf("number"), "sunDirection"),
+    extractObject(thematicDisplaySensorSettingsPropsMappings, "gradientSettings"),
+];
+const thematicDisplaySettingsLegacyMappings = [
+    extractNumber("displayMode"),
+    extractObject(thematicGradientSettingsPropsLegacyMappings, "gradientSettings"),
+    extractSimpleArray(simpleTypeOf("number"), "range"),
+    extractSimpleArray(simpleTypeOf("number"), "axis"),
+    extractSimpleArray(simpleTypeOf("number"), "sunDirection"),
+    extractObject(thematicDisplaySensorSettingsPropsMappings, "gradientSettings"),
+];
 const cutStyleMappings = [
     extractObject(viewFlagOverridesMapping, "viewflags"),
     extractObject(hiddenLineSettingsMappings, "hiddenLine"),
@@ -475,6 +543,8 @@ const displayStyle3dMapping = [
     extractObject(solarShadowMappings, "solarShadows"),
     extractObject(lightsMappings, "lights"),
     extractPlainTypedMap(planProjectionSettingsMappings, simpleTypeOf("string"), "planProjections"),
+    extractObject(thematicDisplaySettingsMappings, "thematic"),
+    extractObject(hiddenLineSettingsMappings, "hiddenLine", "hline"),
 ];
 const displayStyle3dLegacyMapping = [
     ...displayStylesLegacyMapping,
@@ -483,6 +553,8 @@ const displayStyle3dLegacyMapping = [
     extractObject(solarShadowLegacyMappings, "solarShadows"),
     extractObject(lightsLegacyMappings, "lights"),
     extractPlainTypedMap(planProjectionSettingsMappings, simpleTypeOf("string"), "planProjections"),
+    extractObject(thematicDisplaySettingsLegacyMappings, "thematic"),
+    extractObject(hiddenLineSettingsLegacyMappings, "hline", "hiddenLine"),
 ];
 /**
  * Extracts the display style from a legacy view displayStyle field
@@ -528,6 +600,11 @@ export const extractDisplayStyle3d = (data) => {
         styles = data.displayStyleProps.jsonProperties?.styles;
         applyExtraction(styles, output, displayStyle3dLegacyMapping);
     }
+    const range = output?.thematic?.range;
+    if (range && Array.isArray(range) && range.length === 0) {
+        // Range is optional, so delete it if it's empty
+        output.thematic.range = undefined;
+    }
     if (styles === undefined) {
         return undefined;
     }

package/lib/translation/extractionUtilities.d.ts

@@ -38,7 +38,7 @@ export declare const transformRGB: (value: unknown) => Rgba | undefined;
  * @param transform Transform function of the value to be put in the output
  * @returns Function that does the extraction
  */
-export declare const createExtractionFunc: (from: string, to: string, typeCheck?: ((value: unknown) => boolean) | undefined, transform?: ((value: unknown) => unknown) | undefined) => (input: any, output: any) => void;
+export declare const createExtractionFunc: (from: string, to: string, typeCheck?: (value: unknown) => boolean, transform?: (value: unknown) => unknown) => (input: any, output: any) => void;
 /** Type for a extraction function generator */
 export type ExtractionFunc<InputType, OutputType> = (input: InputType, output: OutputType) => OutputType;
 /** Type for a function that creates a extraction function */
@@ -51,6 +51,14 @@ export type ExtractionFuncCreator = (from: string, to: string) => ExtractionFunc
  * @returns Function that extracts a number value and type checks it
  */
 export declare const extractNumber: (from: string, to?: string) => ExtractionFunc<void, void>;
+/**
+ * Creates a extraction function that will extract a number from the given accessor, transform it into a LinePixels enum, and put it
+ * in the given accessor if provided
+ * @param from Accessor that will be used on input to access value
+ * @param to Accessor that will be used to stored the value in the output object
+ * @returns Function that extracts a number value and type checks it
+ */
+export declare const extractLinePixels: (from: string, to?: string) => ExtractionFunc<void, void>;
 /**
  * Creates a extraction function that will extract a boolean from the given accessor and put it
  * in the given accessor if provided

package/lib/translation/extractionUtilities.js

@@ -3,6 +3,7 @@
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/
 import { ColorDef } from "@itwin/core-common";
+import { LinePixels } from "@itwin/saved-views-client";
 /**
  * Returns a function that does a simple typeof check on a value
  * @param typeOfString String to compare against
@@ -231,6 +232,21 @@ export const createExtractionFunc = (from, to, typeCheck, transform) => {
 export const extractNumber = (from, to) => {
     return createExtractionFunc(from, to ?? from, simpleTypeOf("number"));
 };
+/**
+ * Creates a extraction function that will extract a number from the given accessor, transform it into a LinePixels enum, and put it
+ * in the given accessor if provided
+ * @param from Accessor that will be used on input to access value
+ * @param to Accessor that will be used to stored the value in the output object
+ * @returns Function that extracts a number value and type checks it
+ */
+export const extractLinePixels = (from, to) => {
+    return createExtractionFunc(from, to ?? from, simpleTypeOf("number"), (value) => {
+        if (typeof value !== "number" ||
+            !Object.keys(LinePixels).includes(value.toString()))
+            return LinePixels.Invalid;
+        return value;
+    });
+};
 /**
  * Creates a extraction function that will extract a boolean from the given accessor and put it
  * in the given accessor if provided

package/lib/useSavedViews.d.ts

@@ -1,53 +1,191 @@
-import type { ViewData } from "@itwin/saved-views-client";
-import type { SavedView, SavedViewGroup, SavedViewTag } from "./SavedView.js";
+import { type ReactNode, type SetStateAction } from "react";
+import type { SavedView, SavedViewData, SavedViewGroup, SavedViewTag, WriteableSavedViewProperties } from "./SavedView.js";
 import type { SavedViewsClient } from "./SavedViewsClient/SavedViewsClient.js";
-interface UseSavedViewsParams {
+import { type AllOrNone } from "./utils.js";
+type UseSavedViewsArgs = {
     /** iTwin identifier. */
     iTwinId: string;
     /** iModel identifier. */
     iModelId: string;
     /** Implements communication with Saved Views store. */
     client: SavedViewsClient;
+} & AllOrNone<ExternalState>;
+interface ExternalState {
     /**
-     * Invoked when any of {@linkcode SavedViewActions} is triggered. Does not get called again until either
-     * {@linkcode onUpdateComplete} or {@linkcode onUpdateError} is invoked.
+     * Current immutable value of Saved Views store. If provided, it is returned as
+     * {@linkcode UseSavedViewsResult.store}; otherwise an internal store is used.
+     *
+     * @example
+     * const [state, setState] = useState(useSavedViews.emptyState);
+     * const { store } = useSavedViews({ iTwinId, iModelId, client, state, setState });
+     * console.log(store === state); // true
      */
-    onUpdateInProgress?: (() => void) | undefined;
-    /** Invoked once after {@linkcode onUpdateInProgress} when the data is successfully synchronised with the store. */
-    onUpdateComplete?: (() => void) | undefined;
-    /** Invoked once after {@linkcode onUpdateInProgress} when data synchronisation with the store fails. */
-    onUpdateError?: ((error: unknown) => void) | undefined;
+    state: SavedViewsState;
+    /**
+     * Function which updates Saved Views store. It should behave the same as `setState` callback
+     * that is returned by `React.useState`.
+     *
+     * @remarks
+     * When hook arguments change, the state is not cleared automatically.
+     *
+     * @example
+     * const [state, setState] = useState(useSavedViews.emptyState);
+     * const savedViews = useSavedViews({ iTwinId, iModelId, client, state, setState });
+     */
+    setState: (action: SetStateAction<SavedViewsState>) => void;
 }
-interface UseSavedViewsResult {
+export interface SavedViewsState {
+    /** Maps `savedViewId` to {@link SavedView}. */
     savedViews: Map<string, SavedView>;
+    /** Maps `savedViewId` to {@link SavedViewData}. */
+    savedViewData: Map<string, SavedViewData>;
+    /** Maps `groupId` to {@link SavedViewGroup}. */
     groups: Map<string, SavedViewGroup>;
+    /** Maps `tagId` to {@link SavedViewTag}. */
     tags: Map<string, SavedViewTag>;
-    actions: SavedViewActions;
+    /** Maps `savedViewId` to {@link ReactNode} representing Saved View thumbnail. */
+    thumbnails: Map<string, ReactNode>;
 }
-export interface SavedViewActions {
-    submitSavedView: (savedView: string | Partial<SavedView> & Pick<SavedView, "displayName">, savedViewData: ViewData) => Promise<string>;
-    renameSavedView: (savedViewId: string, newName: string | undefined) => void;
-    shareSavedView: (savedViewId: string, share: boolean) => void;
-    deleteSavedView: (savedViewId: string) => void;
-    createGroup: (groupName: string) => void;
-    renameGroup: (groupId: string, newName: string) => void;
-    shareGroup: (groupId: string, share: boolean) => void;
-    moveToGroup: (savedViewId: string, groupId: string) => void;
-    moveToNewGroup: (savedViewId: string, groupName: string) => void;
-    deleteGroup: (groupId: string) => void;
-    addTag: (savedViewId: string, tagId: string) => void;
-    addNewTag: (savedViewId: string, tagName: string) => void;
-    removeTag: (savedViewId: string, tagId: string) => void;
-    uploadThumbnail: (savedViewId: string, imageDataUrl: string) => void;
+interface UseSavedViewsResult extends SavedViewsActions {
+    /**
+     * Immutable state which holds Saved Views data. If {@linkcode UseSavedViewsArgs.state} is not
+     * specified, an internal state is returned; otherwise its value is the same as the provided
+     * `state` argument.
+     */
+    store: SavedViewsState;
+    /**
+     * When invoked, {@link SavedViewsClient} is queried for all available Saved Views, Groups, and
+     * Tags. When the operation ends, all obtained entities are inserted into Saved Views store.
+     *
+     * @param callback Optional callback that is invoked when the operation ends. If an error occurs,
+     *                 the operation gets cancelled and the error object is passed as the argument.
+     * @returns Callback that cancels the operation.
+     *
+     * @example
+     * const { startLoadingData } = useSavedViews({ iTwinId, iModelId, client });
+     * const [isLoading, setIsLoading] = useState(true);
+     * useEffect(
+     *   () => {
+     *     return startLoadingData((error) => {
+     *       setIsLoading(false);
+     *       if (error) {
+     *         console.error(error);
+     *       }
+     *     });
+     *   },
+     *   [],
+     * );
+     */
+    startLoadingData: (callback?: (error?: unknown) => void) => () => void;
+}
+export interface SavedViewsActions {
+    /**
+     * Creates a new {@link SavedView} entity using {@link SavedViewsClient} and stores the result in
+     * Saved Views store.
+     * @returns Identifier of the newly created Saved View.
+     */
+    createSavedView: (savedView: WriteableSavedViewProperties, savedViewData: SavedViewData) => Promise<string>;
+    /**
+     * Retrieves {@link SavedViewData} associated with given {@linkcode savedViewId} from the Saved
+     * Views store if the data is present; otherwise it is queried from {@link SavedViewsClient} and the
+     * store is updated to include the new data.
+     */
+    lookupSavedViewData: (savedViewId: string) => Promise<SavedViewData>;
+    /**
+     * Uses {@link SavedViewsClient} to update {@link SavedView} entity. On success, updates
+     * {@link SavedView} in Saved Views store with provided values.
+     */
+    updateSavedView: (savedViewId: string, savedView: Partial<WriteableSavedViewProperties>, savedViewData?: SavedViewData | undefined) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to update {@link SavedView} entity associated with given {@linkcode savedViewId}.
+     * On success, updates {@link SavedView} in Saved Views store with provided name.
+     */
+    renameSavedView: (savedViewId: string, newName: string) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to mark {@link SavedView} entity as shared or unshared. On
+     * success, updates {@link SavedView} in Saved Views store with provided status.
+     */
+    shareSavedView: (savedViewId: string, shared: boolean) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to delete {@link SavedView} entity. On success, removes
+     * {@link SavedView} from Saved Views store.
+     */
+    deleteSavedView: (savedViewId: string) => Promise<void>;
+    /**
+     * Creates a new {@link SavedViewGroup} entity using {@link SavedViewsClient} and stores the
+     * result in Saved Views store.
+     * @returns Identifier of the newly created Saved View Group.
+     */
+    createGroup: (groupName: string) => Promise<string>;
+    /**
+     * Uses {@link SavedViewsClient} to update {@link SavedViewGroup} entity. On success, updates
+     * {@link SavedViewGroup} in Saved Views store with provided name.
+     */
+    renameGroup: (groupId: string, newName: string) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to mark {@link SavedViewGroup} entity as shared or unshared. On
+     * success, updates {@link SavedViewGroup} in Saved Views store with provided status.
+     */
+    shareGroup: (groupId: string, shared: boolean) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to move {@link SavedView} entity to the specified Saved View group.
+     */
+    moveToGroup: (savedViewId: string, groupId: string | undefined) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to delete {@link SavedViewGroup} entity. On success, removes
+     * {@link SavedViewGroup} from Saved Views store.
+     */
+    deleteGroup: (groupId: string) => Promise<void>;
+    /**
+     * Creates a new {@link SavedViewTag} entity using {@link SavedViewsClient} and stores the result
+     * in Saved Views store.
+     * @returns Identifier of the newly created Saved View Tag.
+     */
+    createTag: (tagName: string) => Promise<string>;
+    /** Uses {@link SavedViewsClient} to add {@link SavedViewTag} to {@link SavedView} entity. */
+    addTag: (savedViewId: string, tagId: string) => Promise<void>;
+    /** Uses {@link SavedViewsClient} to remove {@link SavedViewTag} from {@link SavedView} entity. */
+    removeTag: (savedViewId: string, tagId: string) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to delete {@link SavedViewTag} entity. On success, removes
+     * {@link SavedViewTag} from Saved Views store.
+     */
+    deleteTag: (tagId: string) => Promise<void>;
+    /** Uses {@link SavedViewsClient} to change thumbnail image for {@link SavedView} entity. */
+    uploadThumbnail: (savedViewId: string, imageDataUrl: string) => Promise<void>;
 }
 /**
- * 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`.
+ * Provides basic functionality to help get started with Saved Views.
+ *
+ * @remarks
+ * When hook arguments change, it does not automatically clear the {@linkcode UseSavedViewsResult.store}.
+ * If you want more control over the state, provide an external store via {@linkcode UseSavedViewsArgs.state}
+ * and {@linkcode UseSavedViewsArgs.setState} arguments.
+ *
+ * @example
+ * const { iTwinId, iModelId, client, viewport } = props;
+ * const savedViews = useSavedViews({ iTwinId, iModelId, client });
+ * const [isLoading, setIsLoading] = useState(true);
+ * useEffect(
+ *   () => {
+ *     return savedViews.startLoadingData(() => { setIsLoading(false); });
+ *   },
+ *   [],
+ * );
+ *
+ * if (isLoading) {
+ *   return <MyLoadingState />;
+ * }
+ *
+ * const handleOpenSavedView = async (savedViewId) => {
+ *   const savedViewData = await savedViews.lookupSavedViewData(savedViewId);
+ *   await applySavedView(iModel, viewport, savedViewData);
+ * };
  *
- * 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.
+ * return <MySavedViewsWidget savedViews={savedViews} onOpenSavedView={handleOpenSavedView} />;
  */
-export declare function useSavedViews(args: UseSavedViewsParams): UseSavedViewsResult | undefined;
+export declare const useSavedViews: ((args: UseSavedViewsArgs) => UseSavedViewsResult) & ((args: UseSavedViewsArgs) => UseSavedViewsResult) & {
+    /** Suggested initial state of custom Saved View stores. Immutable. */
+    emptyState: SavedViewsState;
+};
 export {};