@itwin/core-frontend 3.1.0-dev.8 → 3.2.0-dev.3

package/lib/esm/quantity-formatting/QuantityFormatter.js

@@ -5,24 +5,35 @@
 /** @packageDocumentation
  * @module QuantityFormatting
  */
-import { BeUiEvent } from "@itwin/core-bentley";
+import { BeUiEvent, Logger } from "@itwin/core-bentley";
 import { Format, FormatterSpec, ParseError, ParserSpec, } from "@itwin/core-quantity";
+import { FrontendLoggerCategory } from "../FrontendLoggerCategory";
 import { IModelApp } from "../IModelApp";
 import { BasicUnitsProvider, getDefaultAlternateUnitLabels } from "./BasicUnitsProvider";
 // cSpell:ignore FORMATPROPS FORMATKEY ussurvey uscustomary USCUSTOM
-/** Defines standard format types for tools that need to display measurements to user. Kept only to provide compatibility for existing API.
- * @beta
+/**
+ * Defines standard format types for tools that need to display measurements to user.
+ * @public
  */
 export var QuantityType;
 (function (QuantityType) {
+    /** Length which is stored in meters. Typically formatted to display in meters or feet-inches based on active unit system. */
     QuantityType[QuantityType["Length"] = 1] = "Length";
+    /** Angular value which is stored in radians. Typically formatted to display degrees or Degrees-Minute-Seconds based on active unit system. */
     QuantityType[QuantityType["Angle"] = 2] = "Angle";
+    /** Area value store in meters squared. Typically formatted to display in meters squared or feet squared based on active unit system. */
     QuantityType[QuantityType["Area"] = 3] = "Area";
+    /** Volume value which is stored in meters cubed. Typically formatted to display in meters cubed or feet cubed based on active unit system. */
     QuantityType[QuantityType["Volume"] = 4] = "Volume";
+    /** LatLong is an angular value which is stored in radians. Typically formatted to display degrees or Degrees-Minute-Seconds based on active unit system. */
     QuantityType[QuantityType["LatLong"] = 5] = "LatLong";
+    /** Coordinate/Location value which is stored in meters. Typically formatted to display in meters or feet based on active unit system. */
     QuantityType[QuantityType["Coordinate"] = 6] = "Coordinate";
+    /** Stationing is a distance value stored in meters. Typically formatted to display `xxx+xx` or `xx+xxx` based on active unit system. */
     QuantityType[QuantityType["Stationing"] = 7] = "Stationing";
+    /** LengthSurvey is a distance value stored in meters. Typically formatted to display in meters or US Survey Feet based on active unit system.. */
     QuantityType[QuantityType["LengthSurvey"] = 8] = "LengthSurvey";
+    /** LengthEngineering is a distance value stored in meters. Typically formatted to display either meters or feet based on active unit system. */
     QuantityType[QuantityType["LengthEngineering"] = 9] = "LengthEngineering";
 })(QuantityType || (QuantityType = {}));
 /**
@@ -48,8 +59,10 @@ export class AlternateUnitLabelsRegistry {
         return undefined;
     }
 }
-/** Function to return a QuantityTypeKey given either a QuantityType or a string
- * @beta
+/**
+ * Function to return a QuantityTypeKey given either a QuantityType enum value or a string. This allows caching and
+ * retrieving standard and custom quantity types.
+ * @public
  */
 export function getQuantityTypeKey(type) {
     // For QuantityType enum values, build a string that shouldn't collide with anything a user may come up with
@@ -57,31 +70,13 @@ export function getQuantityTypeKey(type) {
         return `QuantityTypeEnumValue-${type.toString()}`;
     return type;
 }
-/** CheckboxFormatPropEditorSpec type guard.
- * @beta
- */
-export const isCheckboxFormatPropEditorSpec = (item) => {
-    return item.editorType === "checkbox";
-};
-/** TextInputFormatPropEditorSpec type guard.
- * @beta
- */
-export const isTextInputFormatPropEditorSpec = (item) => {
-    return item.editorType === "text";
-};
-/** TextSelectFormatPropEditorSpec type guard.
- * @beta
- */
-export const isTextSelectFormatPropEditorSpec = (item) => {
-    return item.editorType === "select";
-};
 /** CustomQuantityTypeDefinition type guard.
- * @beta
+ * @public
 */
 export function isCustomQuantityTypeDefinition(item) {
     return !!item.isCompatibleFormatProps;
 }
-/** private class to hold standard quantity definitions and implement QuantityTypeDefinition interface */
+/** private class to hold standard quantity definitions as defined by QuantityType enum and implement QuantityTypeDefinition interface */
 class StandardQuantityTypeDefinition {
     constructor(type, persistenceUnit, _labelKey, _descriptionKey) {
         this.type = type;
@@ -105,6 +100,7 @@ class StandardQuantityTypeDefinition {
         }
         return (_a = this._description) !== null && _a !== void 0 ? _a : this.label;
     }
+    /** Get a default format to show quantity in persistence unit with precision or 6 decimal places.  */
     getDefaultFormatPropsBySystem(requestedSystem) {
         // Fallback same as Format "DefaultRealU" in Formats ecschema
         const fallbackProps = {
@@ -143,7 +139,7 @@ class StandardQuantityTypeDefinition {
  * identified by the [[QuantityType]] enum. [[CustomQuantityTypeDefinition]] can be registered to extend the available quantity types available
  * by frontend tools. The QuantityFormatter also allows the default formats to be overriden.
  *
- * @beta
+ * @public
  */
 export class QuantityFormatter {
     /**
@@ -154,10 +150,15 @@ export class QuantityFormatter {
     constructor(showMetricOrUnitSystem) {
         this._unitsProvider = new BasicUnitsProvider();
         this._alternateUnitLabelsRegistry = new AlternateUnitLabelsRegistry(getDefaultAlternateUnitLabels());
+        /** Registry containing available quantity type definitions. */
         this._quantityTypeRegistry = new Map();
+        /** Active UnitSystem key - must be one of "imperial", "metric", "usCustomary", or "usSurvey". */
         this._activeUnitSystem = "imperial";
+        /** Map of FormatSpecs for all available QuantityTypes and the active Unit System */
         this._activeFormatSpecsByType = new Map();
+        /** Map of ParserSpecs for all available QuantityTypes and the active Unit System */
         this._activeParserSpecsByType = new Map();
+        /** Map of FormatSpecs that have been overriden from the default. */
         this._overrideFormatPropsByUnitSystem = new Map();
         /** Called after the active unit system is changed.
         * The system will report the UnitSystemKey/name of the the system that was activated.
@@ -189,6 +190,7 @@ export class QuantityFormatter {
             return undefined;
         return overrideMap.get(quantityTypeKey);
     }
+    /** Method used to register all QuantityTypes defined in QuantityType enum. */
     async initializeQuantityTypesRegistry() {
         // QuantityType.Length
         const lengthUnit = await this.findUnitByName("Units.M");
@@ -232,15 +234,13 @@ export class QuantityFormatter {
         // load cache for every registered QuantityType
         [...this.quantityTypesRegistry.keys()].forEach((key) => {
             const entry = this.quantityTypesRegistry.get(key);
-            formatPropsByType.set(entry, this.getFormatPropsByQuantityTypeEntyAndSystem(entry, systemKey));
+            formatPropsByType.set(entry, this.getFormatPropsByQuantityTypeEntryAndSystem(entry, systemKey));
         });
-        const formatPropPromises = new Array();
         for (const [entry, formatProps] of formatPropsByType) {
-            formatPropPromises.push(this.loadFormatAndParserSpec(entry, formatProps));
+            await this.loadFormatAndParserSpec(entry, formatProps);
         }
-        await Promise.all(formatPropPromises);
     }
-    getFormatPropsByQuantityTypeEntyAndSystem(quantityEntry, requestedSystem, ignoreOverrides) {
+    getFormatPropsByQuantityTypeEntryAndSystem(quantityEntry, requestedSystem, ignoreOverrides) {
         if (!ignoreOverrides) {
             const overrideProps = this.getOverrideFormatPropsByQuantityType(quantityEntry.key, requestedSystem);
             if (overrideProps)
@@ -313,9 +313,11 @@ export class QuantityFormatter {
         // initialize default format and parsing specs
         await this.loadFormatAndParsingMapsForSystem();
     }
+    /** Return a map that serves as a registry of all standard and custom quantity types. */
     get quantityTypesRegistry() {
         return this._quantityTypeRegistry;
     }
+    /** Return the class the contain map of all alternate labels for units. These alternate labels are used when parsing strings in quantity values. */
     get alternateUnitLabelsProvider() {
         return this._alternateUnitLabelsRegistry;
     }
@@ -328,13 +330,38 @@ export class QuantityFormatter {
         this._alternateUnitLabelsRegistry.addAlternateLabels(key, ...labels);
         this.onUnitsProviderChanged.emit();
     }
+    /** Get/Set the active UnitsProvider class. */
     get unitsProvider() {
         return this._unitsProvider;
     }
     set unitsProvider(unitsProvider) {
+        this.setUnitsProvider(unitsProvider); // eslint-disable-line @typescript-eslint/no-floating-promises
+    }
+    /** async method to set a units provider and reload caches */
+    async setUnitsProvider(unitsProvider) {
         this._unitsProvider = unitsProvider;
+        try {
+            // force all cached data to be reinitialized
+            await IModelApp.quantityFormatter.onInitialized();
+        }
+        catch (_) {
+            Logger.logWarning(`${FrontendLoggerCategory.Package}.quantityFormatter`, "An exception occurred initializing the iModelApp.quantityFormatter with the given UnitsProvider. Defaulting back to the internal units provider.");
+            // If there is a problem initializing with the given provider, default back to the internal provider
+            await IModelApp.quantityFormatter.resetToUseInternalUnitsProvider();
+            return;
+        }
+        // force default tool to start so any tool that may be using cached data will not be using bad data.
+        if (IModelApp.toolAdmin)
+            await IModelApp.toolAdmin.startDefaultTool();
         this.onUnitsProviderChanged.emit();
     }
+    /** Async call typically used after IModel is closed to reset UnitsProvider to default one that does not require an Units schema. */
+    async resetToUseInternalUnitsProvider() {
+        if (this._unitsProvider instanceof BasicUnitsProvider)
+            return;
+        await this.setUnitsProvider(new BasicUnitsProvider());
+    }
+    /** Async call to register a CustomQuantityType and load the FormatSpec and ParserSpec for the new type. */
     async registerQuantityType(entry, replace) {
         if (!replace && this._quantityTypeRegistry.has(entry.key))
             return false;
@@ -351,7 +378,7 @@ export class QuantityFormatter {
     }
     /** Reinitialize caches. Typically called by active UnitFormattingSettingsProvider.
      * startDefaultTool - set to true to start the Default to instead of leaving any active tool pointing to cached unit data that is no longer valid
-     * @beta
+     * @public
      */
     async reinitializeFormatAndParsingsMaps(overrideFormatPropsByUnitSystem, unitSystemKey, fireUnitSystemChanged, startDefaultTool) {
         this._overrideFormatPropsByUnitSystem.clear();
@@ -381,15 +408,17 @@ export class QuantityFormatter {
         if (IModelApp.toolAdmin && restartActiveTool)
             return IModelApp.toolAdmin.startDefaultTool();
     }
-    /** True if tool quantity values should be displayed in imperial units; false for metric. Changing this flag triggers an asynchronous request to refresh the cached formats. */
+    /** Retrieve the active [[UnitSystemKey]] which is used to determine what formats are to be used to display quantities */
     get activeUnitSystem() { return this._activeUnitSystem; }
+    /** Clear any formatting override for specified quantity type, but only for the "active" Unit System. */
     async clearOverrideFormats(type) {
         await this.clearOverrideFormatsByQuantityTypeKey(this.getQuantityTypeKey(type));
     }
+    /** Set formatting override for specified quantity type, but only for the "active" Unit System. */
     async setOverrideFormats(type, overrideEntry) {
         await this.setOverrideFormatsByQuantityTypeKey(this.getQuantityTypeKey(type), overrideEntry);
     }
-    // TODO: make more generic to support "named" systems.
+    /** Set Override Format for a quantity type, but only in the "active" Unit System. */
     async setOverrideFormat(type, overrideFormat) {
         const typeKey = this.getQuantityTypeKey(type);
         let overrideEntry = {};
@@ -403,6 +432,7 @@ export class QuantityFormatter {
             overrideEntry = { usSurvey: overrideFormat };
         await this.setOverrideFormatsByQuantityTypeKey(typeKey, overrideEntry);
     }
+    /** Clear formatting override for all quantity types, but only for the "active" Unit System. */
     async clearAllOverrideFormats() {
         if (0 === this._overrideFormatPropsByUnitSystem.size)
             return;
@@ -425,10 +455,11 @@ export class QuantityFormatter {
             }
         }
     }
-    /** Converts a QuantityTypeArg into a QuantityTypeKey/string value. */
+    /** Converts a QuantityTypeArg into a QuantityTypeKey/string value that can be used to lookup custom and standard quantity types. */
     getQuantityTypeKey(type) {
         return getQuantityTypeKey(type);
     }
+    /** Return [[QuantityTypeDefinition]] if type has been registered. Standard QuantityTypes are automatically registered. */
     getQuantityDefinition(type) {
         return this.quantityTypesRegistry.get(this.getQuantityTypeKey(type));
     }
@@ -438,13 +469,14 @@ export class QuantityFormatter {
     findFormatterSpecByQuantityType(type, _unused) {
         return this._activeFormatSpecsByType.get(this.getQuantityTypeKey(type));
     }
+    /** Asynchronous Call to get a FormatterSpec for a QuantityType. This formatter spec can be used to synchronously format quantities. */
     async generateFormatterSpecByType(type, formatProps) {
         const quantityTypeDefinition = this.quantityTypesRegistry.get(this.getQuantityTypeKey(type));
         if (quantityTypeDefinition)
             return quantityTypeDefinition.generateFormatterSpec(formatProps, this.unitsProvider);
         throw new Error(`Unable to generate FormatSpec for QuantityType ${type}`);
     }
-    /** Asynchronous Call to get a FormatterSpec of a QuantityType.
+    /** Asynchronous Call to get a FormatterSpec for a QuantityType and a Unit System. This formatter spec can be used to synchronously format quantities.
      * @param type        One of the built-in quantity types supported.
      * @param system      Requested unit system key. Note it is more efficient to use setActiveUnitSystem to set up formatters for all
      * quantity types of a unit system.
@@ -461,7 +493,7 @@ export class QuantityFormatter {
         const entry = this.quantityTypesRegistry.get(quantityKey);
         if (!entry)
             throw new Error(`Unable to find registered quantity type with key ${quantityKey}`);
-        return entry.generateFormatterSpec(this.getFormatPropsByQuantityTypeEntyAndSystem(entry, requestedSystem), this.unitsProvider);
+        return entry.generateFormatterSpec(this.getFormatPropsByQuantityTypeEntryAndSystem(entry, requestedSystem), this.unitsProvider);
     }
     /** Asynchronous Call to get a FormatterSpec for a QuantityType.
      * @param type        One of the built-in quantity types supported.
@@ -480,6 +512,7 @@ export class QuantityFormatter {
     findParserSpecByQuantityType(type) {
         return this._activeParserSpecsByType.get(this.getQuantityTypeKey(type));
     }
+    /** Asynchronous Call to get a ParserSpec for a QuantityType. If the UnitSystemKey is not specified the active Unit System is used. **/
     async getParserSpecByQuantityTypeAndSystem(type, system) {
         const quantityKey = this.getQuantityTypeKey(type);
         const requestedSystem = system !== null && system !== void 0 ? system : this.activeUnitSystem;
@@ -491,7 +524,7 @@ export class QuantityFormatter {
         const entry = this.quantityTypesRegistry.get(quantityKey);
         if (!entry)
             throw new Error(`Unable to find registered quantity type with key ${quantityKey}`);
-        return entry.generateParserSpec(this.getFormatPropsByQuantityTypeEntyAndSystem(entry, requestedSystem), this.unitsProvider);
+        return entry.generateParserSpec(this.getFormatPropsByQuantityTypeEntryAndSystem(entry, requestedSystem), this.unitsProvider);
     }
     /** Asynchronous Call to get a ParserSpec for a QuantityType.
      * @param type        One of the built-in quantity types supported.
@@ -525,7 +558,9 @@ export class QuantityFormatter {
             return parserSpec.parseToQuantityValue(inString);
         return { ok: false, error: ParseError.InvalidParserSpec };
     }
-    /** Get a UnitSystemKey from a string that may have been entered via a key-in. Support different variation of unit system names.
+    /**
+     * Get a UnitSystemKey from a string that may have been entered via a key-in. Supports different variation of
+     * unit system names that have been used in the past.
      */
     getUnitSystemFromString(inputSystem, fallback) {
         switch (inputSystem.toLowerCase()) {
@@ -550,6 +585,7 @@ export class QuantityFormatter {
         }
         return "imperial";
     }
+    /** Return true if the QuantityType is using an override format. */
     hasActiveOverride(type, checkOnlyActiveUnitSystem) {
         const quantityTypeKey = this.getQuantityTypeKey(type);
         if (checkOnlyActiveUnitSystem) {
@@ -564,22 +600,29 @@ export class QuantityFormatter {
         }
         return false;
     }
+    /** Get the cached FormatProps give a quantity type. If ignoreOverrides is false then if the format has been overridden
+     * the overridden format is returned, else the standard format is returned.
+     */
     getFormatPropsByQuantityType(quantityType, requestedSystem, ignoreOverrides) {
         const quantityEntry = this.quantityTypesRegistry.get(this.getQuantityTypeKey(quantityType));
         if (quantityEntry)
-            return this.getFormatPropsByQuantityTypeEntyAndSystem(quantityEntry, requestedSystem !== null && requestedSystem !== void 0 ? requestedSystem : this.activeUnitSystem, ignoreOverrides);
+            return this.getFormatPropsByQuantityTypeEntryAndSystem(quantityEntry, requestedSystem !== null && requestedSystem !== void 0 ? requestedSystem : this.activeUnitSystem, ignoreOverrides);
         return undefined;
     }
     // keep following to maintain existing API of implementing UnitsProvider
-    async findUnit(unitLabel, phenomenon, unitSystem) {
-        return this._unitsProvider.findUnit(unitLabel, phenomenon, unitSystem);
+    /** Find [UnitProp] for a specific unit label. */
+    async findUnit(unitLabel, schemaName, phenomenon, unitSystem) {
+        return this._unitsProvider.findUnit(unitLabel, schemaName, phenomenon, unitSystem);
     }
+    /** Returns all defined units for the specified Unit Family/Phenomenon. */
     async getUnitsByFamily(phenomenon) {
         return this._unitsProvider.getUnitsByFamily(phenomenon);
     }
+    /** Find [UnitProp] for a specific unit name. */
     async findUnitByName(unitName) {
         return this._unitsProvider.findUnitByName(unitName);
     }
+    /** Returns data needed to convert from one Unit to another in the same Unit Family/Phenomenon. */
     async getConversion(fromUnit, toUnit) {
         return this._unitsProvider.getConversion(fromUnit, toUnit);
     }