@itwin/saved-views-react 0.1.0

package/lib/api/utilities/translation/extractionUtilities.js

@@ -0,0 +1,515 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+import { ColorDef } from "@itwin/core-common";
+/**
+ * Returns a function that does a simple typeof check on a value
+ * @param typeOfString String to compare against
+ * @returns
+ */
+export const simpleTypeOf = (typeOfString) => {
+    return (value) => typeof value === typeOfString;
+};
+/**
+ * Type check for colors in format {r: number, g: number, b:number}
+ * @param value
+ * @returns
+ */
+const isRgbColorProps = (value) => {
+    return (typeof value === "object" &&
+        value !== null &&
+        "r" in value &&
+        typeof value.r === "number" &&
+        "g" in value &&
+        typeof value.g === "number" &&
+        "b" in value &&
+        typeof value.b === "number");
+};
+/**
+ * Type check for colors in our schema format {red: number, green: number, blue: number}
+ * @param value
+ * @returns
+ */
+const isSchemaRgbColor = (value) => {
+    return (typeof value === "object" &&
+        value !== null &&
+        "red" in value &&
+        typeof value.red === "number" &&
+        "green" in value &&
+        typeof value.green === "number" &&
+        "blue" in value &&
+        typeof value.blue === "number");
+};
+/**
+ * Returns true if the value is a ColorDef, which is simply a number
+ * @param value
+ * @returns
+ */
+const isColorDef = (value) => {
+    return ColorDef.isValidColor(value);
+};
+/**
+ * Returns true if the given value is in any of the color formats that we accept to transform
+ * @param value
+ * @returns
+ */
+export const isAnyColorFormat = (value) => isColorDef(value) ||
+    isRgbColorProps(value) ||
+    isSchemaRgbColor(value);
+// data format is broken into bits for storage of color
+// data format is 0xTTBBGGRR
+// where TT is the transparency bits
+// BB GG RR are the color bits (BB =blue GG= green RR= red)
+// something that if fully one color would be FF or 1111 1111
+const mapColorsToBitShiftedEquivalent = (color) => {
+    const colorCodeRed = color.red; //0x 00 00 00 RR   Binary  0000 0000 0000 0000 0000 0000 RRRR RRRR
+    const colorCodeGreen = color.green << 8; //0x 00 00 GG 00 Binary  0000 0000 0000 0000 GGGG GGGG 0000 0000
+    const colorCodeBlue = color.blue << 16; //0x 00 BB 00 00 Binary  0000 0000 BBBB BBBB 0000 0000 0000 0000
+    const colorCodeTransparency = (color.transparency ?? 0) << 24; //0x TT 00 00 00 Binary  TTTT TTTT 0000 0000 0000 0000 0000 0000
+    return {
+        red: colorCodeRed,
+        green: colorCodeGreen,
+        blue: colorCodeBlue,
+        transparency: colorCodeTransparency,
+    };
+};
+/**
+ * Transforms new color value object into color format  0xTTBBGGRR  value new schema ({red: number,green: number,blue:number, alpha?: number ,transparency})
+ * @param value
+ * @returns color value that is  0xTTBBGGRR
+ */
+const transformSchemaColor = (value) => {
+    const color = {
+        red: value.red,
+        green: value.green,
+        blue: value.blue,
+        transparency: value.alpha ? 255 - value.alpha : 0,
+    };
+    const colorsBitShifted = mapColorsToBitShiftedEquivalent(color);
+    // mix colors codes together using bit shifted or operator
+    const combineBitsForFinalColorCode = (colorsBitShifted) => {
+        return (colorsBitShifted.red |
+            colorsBitShifted.green |
+            colorsBitShifted.blue |
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            color.transparency);
+    };
+    return combineBitsForFinalColorCode(colorsBitShifted);
+};
+const createRGB = (value) => {
+    return {
+        r: value.red,
+        g: value.green,
+        b: value.blue,
+    };
+};
+/**
+ * Transforms a vanilla value into our format {red: number,green: number,blue:number, alpha?: number}
+ * @param value
+ * @returns
+ */
+const transformSchemaColorLegacy = (value) => {
+    const color = {
+        red: value.red,
+        green: value.green,
+        blue: value.blue,
+    };
+    if (value.alpha) {
+        color.alpha = value.alpha;
+    }
+    return color;
+};
+/**
+ * Transform RgbColorProps {r,g,b} to our schema {red,green,blue}
+ * @param value
+ * @returns
+ */
+const transformRgbColorPropsLegacy = (value) => {
+    const color = {
+        red: value.r,
+        green: value.g,
+        blue: value.b,
+    };
+    if (value?.a !== undefined) {
+        color.alpha = value?.a;
+    }
+    return color;
+};
+/**
+ * Transform ColorDef 0xTTBBGGRR to our schema {red,green,blue,alpha if existent}
+ * @param value
+ */
+const transformColorDefLegacy = (value) => {
+    const color = {
+        red: value & 0xff,
+        green: (value & 0xff00) >> 8,
+        blue: (value & 0xff0000) >> 16,
+    };
+    // Extract alpha from transparency
+    if ((value & 0xff000000) !== 0) {
+        color.alpha = 255 - ((value & 0xff000000) >> 24);
+    }
+    return color;
+};
+/**
+ * Transforms any of the three types of colors into our schema color format {red: number, green: number, blue: number}
+ * Legacy to new schema
+ * @param value
+ * @returns
+ */
+export const transformColorLegacy = (value) => {
+    // No need to extract if already follows schema convention
+    if (isSchemaRgbColor(value)) {
+        return transformSchemaColorLegacy(value);
+    }
+    // Extract RgbColorProps format
+    if (isRgbColorProps(value)) {
+        return transformRgbColorPropsLegacy(value);
+    }
+    // Extract 0xTTBBGGRR format
+    if (isColorDef(value)) {
+        return transformColorDefLegacy(value);
+    }
+    return undefined;
+};
+/**
+ * Transforms any of the two types of colors into our schema color format 0xttbbggrr
+ * @param value
+ * @returns
+ */
+export const transformColor = (value) => {
+    // Transform New Schema Into Legacy Schema( Color Def)
+    if (isSchemaRgbColor(value)) {
+        return transformSchemaColor(value);
+    }
+    // Extract 0xTTBBGGRR format we want this format
+    if (isColorDef(value)) {
+        return value;
+    }
+    return undefined;
+};
+/**
+ * Transforms any of the three types of colors into our schema color format {r: number, g: number, b: number}
+ * @param value
+ * @returns
+ */
+export const transformRGB = (value) => {
+    // Extract RgbColorProps format
+    if (isSchemaRgbColor(value)) {
+        return createRGB(value);
+    }
+    //is already the proper format
+    if (isRgbColorProps(value)) {
+        return value;
+    }
+    return undefined;
+};
+/**
+ * Creates a function that extracts a value from input to output
+ * @param from Accessor from where to retrieve the value
+ * @param to Accessor to add to the output object to store the value
+ * @param typeCheck Type checker for validation of the value
+ * @param transform Transform function of the value to be put in the output
+ * @returns Function that does the extraction
+ */
+export const createExtractionFunc = (from, to, typeCheck, transform) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (input, output) => {
+        if (input[from] !== undefined && (!typeCheck || typeCheck(input[from]))) {
+            output[to] = transform ? transform(input[from]) : input[from];
+        }
+    };
+};
+/**
+ * Creates a extraction function that will extract a number from the given accessor 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 extractNumber = (from, to) => {
+    return createExtractionFunc(from, to ?? from, simpleTypeOf("number"));
+};
+/**
+ * Creates a extraction function that will extract a boolean from the given accessor 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 boolean value and type checks it
+ */
+export const extractBoolean = (from, to) => {
+    return createExtractionFunc(from, to ?? from, simpleTypeOf("boolean"));
+};
+/**
+ * Creates a extraction function that will extract a boolean or a number with the same accessor name
+ * @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 boolean or number value and type checks it
+ */
+export const extractNumberOrBool = (from, to) => {
+    return createExtractionFunc(from, to ?? from, (value) => typeof value === "number" || typeof value === "boolean");
+};
+/**
+ * Creates a extraction function that will extract a string from the given accessor 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 string value and type checks it
+ */
+export const extractString = (from, to) => {
+    return createExtractionFunc(from, to ?? from, simpleTypeOf("string"));
+};
+/**
+ * Creates a extraction function that will extract a string or number from them given accessor
+ * @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 string or number value and type checks it
+ */
+export const extractStringOrNumber = (from, to) => {
+    return createExtractionFunc(from, to ?? from, (value) => typeof value === "number" || typeof value === "string");
+};
+/**
+ * Creates a extraction function that will extract a string or an array of strings into the given
+ * accessor
+ * @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 string or string array value and type checks it
+ */
+export const extractStringOrArray = (from, to) => {
+    return createExtractionFunc(from, to ?? from, (value) => typeof value === "string" ||
+        (Array.isArray(value) &&
+            value.every((inner) => typeof inner === "string")));
+};
+/**
+ * Creates a extraction function that will extract an array of type: (string | number)[]
+ * @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 string | number array value and type checks it
+ */
+export const extractStringOrNumberArray = (from, to) => {
+    return createExtractionFunc(from, to ?? from, (value) => Array.isArray(value) &&
+        value.every((val) => typeof val === "number" || typeof val === "string"));
+};
+/**
+ * Creates a extraction function that will extract an array in which all the elements are type checked with the
+ * given function
+ * @param typeCheck Function to check each value of the array
+ * @param from Accessor string where the array is in the input object
+ * @param to Accessor string to store it in the output object
+ * @returns
+ */
+export const extractSimpleArray = (typeCheck, from, to) => {
+    return createExtractionFunc(from, to ?? from, (value) => Array.isArray(value) && value.every((val) => typeCheck(val)));
+};
+/**
+ * Creates a extraction function that will extract a color from the given accessor and put it
+ * in the given accessor if provided. Colors will be transformed from either of the following representations:
+ * 1. Number in format: 0xTTBBGGRR
+ * 2. JSON Object in format: {r: number, g: number, b: number}
+ * 3. JSON Object in format: {red: number, green: number, blue: number}
+ *
+ * The resulting transformed color will be in format: {red: number, green: number, blue: number}
+ *
+ * @param from Accessor that will be used on input to access value
+ * @param to Accessor that will be used to store the value in the output object
+ * @returns Function that extracts a color value and type checks it
+ */
+export const extractColor = (from, to) => {
+    return createExtractionFunc(from, to ?? from, isAnyColorFormat, transformColor);
+};
+/**
+ * Creates a extraction function that will extract a color from the given accessor and put it
+ * in the given accessor if provided. Colors will be transformed from either of the following representations:
+ * 1. Number in format: 0xTTBBGGRR
+ * 2. JSON Object in format: {r: number, g: number, b: number}
+ * 3. JSON Object in format: {red: number, green: number, blue: number}
+ *
+ * The resulting transformed color will be in format: {red: number, green: number, blue: number}
+ *
+ * @param from Accessor that will be used on input to access value
+ * @param to Accessor that will be used to store the value in the output object
+ * @returns Function that extracts a color value and type checks it
+ */
+export const extractColorLegacy = (from, to) => {
+    return createExtractionFunc(from, to ?? from, isAnyColorFormat, transformColorLegacy);
+};
+/**
+ * Creates a extraction function that will extract a color from RBG format
+ *
+ * @param from Accessor that will be used on input to access value
+ * @param to Accessor that will be used to store the value in the output object
+ * @returns Function that extracts a color value and type checks it
+ */
+export const extractRGB = (from, to) => {
+    return createExtractionFunc(from, to ?? from, isAnyColorFormat, transformRGB);
+};
+/**
+ * Creates a extraction function that will extract an array of mappings from an object with the given accessor
+ * @param extractionFuncs Array of extraction functions
+ * @param from Accessor that will be used on input to access value
+ * @param to Accessor that will be used to store the value in the output object
+ * @returns Function that extracts an object
+ */
+export const extractObject = (extractionFuncs, from, to) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (input, output) => {
+        const adjustedTo = to ?? from;
+        if (input[from] !== undefined) {
+            output[adjustedTo] = {};
+            extractionFuncs.forEach((func) => func(input[from], output[adjustedTo]));
+        }
+    };
+};
+/**
+ * Returns true if the value matches the discriminator
+ * @param value Value to check
+ * @param discriminator String to check for an accessor or function that determines whether or not a value is proper
+ */
+const objectMatchesDiscriminator = (
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+value, discriminator) => {
+    if (typeof discriminator === "string") {
+        return value[discriminator] !== undefined;
+    }
+    return discriminator(value);
+};
+/**
+ * Creates an extraction function that will extract different values based on a discriminator string
+ * This is to allow extracting types like 'ClassA | ClassB'
+ * @param params
+ * @param from
+ * @param to
+ * @returns
+ */
+export const extractConditionally = (params, from, to) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (input, output) => {
+        const adjustedTo = to ?? from;
+        if (input[from] !== undefined) {
+            for (const param of params) {
+                // Check that the discriminator prop exist
+                if (objectMatchesDiscriminator(input[from], param.discriminator)) {
+                    // If so, then apply the necessary extraction functions
+                    output[adjustedTo] = {};
+                    if (Array.isArray(param.mappings)) {
+                        // Apply each extraction func to the inner object
+                        param.mappings.forEach((func) => func(input[from], output[adjustedTo]));
+                    }
+                    else {
+                        // Apply the extraction func to the object directly
+                        param.mappings(from, to ?? from)(input, output);
+                    }
+                }
+            }
+        }
+    };
+};
+/**
+ * Creates a extraction function that will extract values of an array by using a single extraction function
+ * on each of the array values
+ * @param extractionFunc
+ */
+export const extractArray = (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] = [];
+            input[from].forEach((_, index) => {
+                output[adjustedTo].push({});
+                extractionFunc.forEach((func) => func(input[from][index], output[adjustedTo][index]));
+            });
+        }
+    };
+};
+/**
+ * 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
+ * @param from Accessor string for the 2D array in the input object
+ * @param to Accessor string for the 2D array in the output object
+ */
+export const extractArray2d = (extractionFunc, from, to) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (input, output) => {
+        if (Array.isArray(input[from]) &&
+            input[from].every((inner) => Array.isArray(inner))) {
+            const adjustedTo = to ?? from;
+            output[adjustedTo] = [];
+            for (let i = 0; i < input[from].length; ++i) {
+                output[adjustedTo].push([]);
+                for (let j = 0; j < input[from][i].length; ++j) {
+                    output[adjustedTo][i].push({});
+                    extractionFunc.forEach((func) => func(input[from][i][j], output[adjustedTo][i][j]));
+                }
+            }
+        }
+    };
+};
+/**
+ * Creates a extraction function that will extract values of an array by using different extraction functions
+ * based on a discriminator for each array value. This is to extract arrays of types like (ClassA | ClassB)[]
+ * @param extractionFunc
+ */
+export const extractArrayConditionally = (params, 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] = [];
+            input[from].forEach((_, index) => {
+                output[adjustedTo].push({});
+                for (const param of params) {
+                    // Check that the discriminator matches with the object
+                    if (objectMatchesDiscriminator(input[from][index], param.discriminator)) {
+                        // If so, then apply the necessary extraction functions
+                        if (Array.isArray(param.mappings)) {
+                            param.mappings.forEach((func) => func(input[from][index], output[adjustedTo][index]));
+                        }
+                        else {
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            param.mappings(index, index)(input[from], output[adjustedTo]);
+                        }
+                    }
+                }
+            });
+        }
+    };
+};
+/**
+ * Creates an extraction function that will extract a plain typed map
+ * @param extractionFuncs Extraction functions for the values
+ * @param isValidKey Checker for the validity of the key
+ * @param from Accessor where the plain typed map exists
+ * @param to Accessor to store the plain typed map to
+ * @returns
+ */
+export const extractPlainTypedMap = (extractionFuncs, isValidKey, from, to) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (input, output) => {
+        if (input[from] !== undefined) {
+            const adjustedTo = to ?? from;
+            output[adjustedTo] = {};
+            for (const prop in input[from]) {
+                if (isValidKey(prop)) {
+                    output[adjustedTo][prop] = {};
+                    extractionFuncs.forEach((func) => func(input[from][prop], output[adjustedTo][prop]));
+                }
+            }
+        }
+    };
+};
+/**
+ * Applies an array of extraction functions to extract the data from the input object
+ * into the output object
+ * @param input Object to extract data from
+ * @param output Object to map the data to
+ * @param extractionFuncs Array of extraction functions
+ */
+export const applyExtraction = (
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+input, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+output, extractionFuncs) => {
+    extractionFuncs.forEach((func) => func(input, output));
+};

package/lib/api/utilities/translation/urlConverter.d.ts

@@ -0,0 +1,7 @@
+import type { ViewData } from "@itwin/saved-views-client";
+/**
+ * Convert url that potentially contains subtituted characters ('++and++' or '++dot++') to use restricated characters ('&' or '.')
+ * @param extensionData
+ */
+export declare const urlToLegacyUrl: (restrictedUrl: string) => string;
+export declare const convertAllLegacyUrlsToUrls: (savedViewData: ViewData, convert: (url: string) => string) => void;

package/lib/api/utilities/translation/urlConverter.js

@@ -0,0 +1,42 @@
+/**
+ * Convert url that potentially contains subtituted characters ('++and++' or '++dot++') to use restricated characters ('&' or '.')
+ * @param extensionData
+ */
+export const urlToLegacyUrl = (restrictedUrl) => {
+    const unrestrictedUrl = restrictedUrl
+        .replaceAll("++and++", "&")
+        .replaceAll("++dot++", ".");
+    return unrestrictedUrl;
+};
+export const convertAllLegacyUrlsToUrls = (savedViewData, convert) => {
+    const displayStyle = savedViewData?.itwin3dView.displayStyle ??
+        savedViewData?.itwinDrawingView.displayStyle ??
+        savedViewData?.itwinSheetView.displayStyle;
+    if (displayStyle === undefined) {
+        return;
+    }
+    // Convert legacy urls to restricted urls
+    const baseUrl = displayStyle.mapImagery?.backgroundBase
+        ?.url;
+    if (displayStyle.mapImagery && baseUrl) {
+        displayStyle.mapImagery.backgroundBase.url =
+            convert(baseUrl);
+    }
+    for (const layer of (displayStyle.mapImagery?.overlayLayers ??
+        [])) {
+        if (layer.url) {
+            layer.url = convert(layer.url);
+        }
+    }
+    for (const layer of (displayStyle.mapImagery?.backgroundLayers ??
+        [])) {
+        if (layer.url) {
+            layer.url = convert(layer.url);
+        }
+    }
+    for (const model of displayStyle.contextRealityModels ?? []) {
+        if (model.tilesetUrl) {
+            model.tilesetUrl = convert(model.tilesetUrl);
+        }
+    }
+};

package/lib/api/utilities/translation/viewExtractorSavedViewToLegacySavedView.d.ts

@@ -0,0 +1,35 @@
+import { SheetViewState, type DrawingViewState, type SpatialViewState } from "@itwin/core-frontend";
+import type { SavedViewWithDataRepresentation } from "@itwin/saved-views-client";
+import type { LegacySavedView, LegacySavedView2d } from "../SavedViewTypes.js";
+/**
+ * Extracts id from href
+ * @param href
+ */
+export declare const extractIdFromHref: (href: string) => string | undefined;
+/**
+ * Transform a ViewDataITwinDrawing into a legacy SavedView if possible
+ * @param savedViewRsp
+ * @param iModelViewData
+ * @returns SavedView2d
+ */
+export declare function savedViewItwinDrawingToLegacyDrawingView(savedViewRsp: SavedViewWithDataRepresentation, seedDrawingViewState: DrawingViewState): LegacySavedView2d;
+/**
+ * Transform a ViewDataITwinSheet into a legacy SavedView if possible
+ * @param savedViewRsp
+ * @param seedSheetViewState
+ * @returns SavedView2d
+ */
+export declare function savedViewItwinSheetToLegacySheetSavedView(savedViewRsp: SavedViewWithDataRepresentation, seedSheetViewState: SheetViewState): LegacySavedView2d;
+/**
+ * Transform a ViewDataItwin3d into a legacy SavedView if possible
+ * @param savedViewRsp
+ * @param seedSpatialViewState
+ * @returns SavedView
+ */
+export declare function savedViewITwin3dToLegacy3dSavedView(savedViewRsp: SavedViewWithDataRepresentation, seedSpatialViewState: SpatialViewState): LegacySavedView;
+/**
+ * removes null and undefined from legacy view model selectors props models
+ * @param savedView
+ * @returns SavedViewWithData
+ */
+export declare const cleanLegacyViewModelSelectorPropsModels: (savedView: SavedViewWithDataRepresentation) => SavedViewWithDataRepresentation;