@itwin/core-frontend 5.0.0-dev.112 → 5.0.0-dev.113

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

@@ -5,7 +5,7 @@
 /** @packageDocumentation
  * @module QuantityFormatting
  */
-import { BentleyError, BeUiEvent, Logger } from "@itwin/core-bentley";
+import { BeEvent, BentleyError, BeUiEvent, Logger } from "@itwin/core-bentley";
 import { Format, FormatterSpec, ParseError, ParserSpec, } from "@itwin/core-quantity";
 import { FrontendLoggerCategory } from "../common/FrontendLoggerCategory";
 import { IModelApp } from "../IModelApp";
@@ -135,12 +135,66 @@ class StandardQuantityTypeDefinition {
         return ParserSpec.create(format, unitsProvider, this.persistenceUnit, alternateUnitLabelsProvider);
     }
 }
+/**
+ * A default formatsProvider, that provides a limited set of [[FormatDefinition]], associated to a few [[KindOfQuantity]].
+ * Maps each KindOfQuantity to a [[QuantityType]].
+ * When retrieving a valid [[KindOfQuantity]], returns the [[FormatProps]] for the associated [[QuantityType]].
+ * @internal
+ */
+export class QuantityTypeFormatsProvider {
+    onFormatsChanged = new BeEvent();
+    constructor() {
+        IModelApp.quantityFormatter.onActiveFormattingUnitSystemChanged.addListener(() => {
+            this.onFormatsChanged.raiseEvent({ formatsChanged: "all" });
+        });
+    }
+    _kindOfQuantityMap = new Map([
+        ["AecUnits.LENGTH", QuantityType.Length],
+        ["AecUnits.ANGLE", QuantityType.Angle],
+        ["AecUnits.AREA", QuantityType.Area],
+        ["AecUnits.VOLUME", QuantityType.Volume],
+        ["RoadRailUnits.STATION", QuantityType.Stationing],
+        ["RoadRailUnits.LENGTH", QuantityType.LengthSurvey],
+    ]);
+    async getFormat(name) {
+        const quantityType = this._kindOfQuantityMap.get(name);
+        if (!quantityType)
+            return undefined;
+        return IModelApp.quantityFormatter.getFormatPropsByQuantityType(quantityType);
+    }
+}
+/**
+ * An implementation of the [[FormatsProvider]] interface that forwards calls to getFormats to the underlying FormatsProvider.
+ * Also fires the onFormatsChanged event when the underlying FormatsProvider fires its own onFormatsChanged event.
+ * @internal
+ */
+export class FormatsProviderManager {
+    _formatsProvider;
+    onFormatsChanged = new BeEvent();
+    constructor(_formatsProvider) {
+        this._formatsProvider = _formatsProvider;
+        this._formatsProvider.onFormatsChanged.addListener((args) => {
+            this.onFormatsChanged.raiseEvent(args);
+        });
+    }
+    async getFormat(name) {
+        return this._formatsProvider.getFormat(name);
+    }
+    get formatsProvider() { return this; }
+    set formatsProvider(formatsProvider) {
+        this._formatsProvider = formatsProvider;
+        this._formatsProvider.onFormatsChanged.addListener((args) => {
+            this.onFormatsChanged.raiseEvent(args);
+        });
+        this.onFormatsChanged.raiseEvent({ formatsChanged: "all" });
+    }
+}
 /** Class that supports formatting quantity values into strings and parsing strings into quantity values. This class also maintains
  * the "active" unit system and caches FormatterSpecs and ParserSpecs for the "active" unit system to allow synchronous access to
  * parsing and formatting values. The support unit systems are defined by [[UnitSystemKey]] and is kept in synch with the unit systems
  * provided by the Presentation Manager on the backend. The QuantityFormatter contains a registry of quantity type definitions. These definitions implement
- * the [[QuantityTypeDefinition]] interface, which among other things, provide default [FormatProps]$(core-quantity), and provide methods
- * to generate both a [FormatterSpec]$(core-quantity) and a [ParserSpec]$(core-quantity). There are built-in quantity types that are
+ * the [[QuantityTypeDefinition]] interface, which among other things, provide default [[FormatProps]], and provide methods
+ * to generate both a [[FormatterSpec]] and a [[ParserSpec]]. There are built-in quantity types that are
  * 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.
  *
@@ -151,6 +205,10 @@ export class QuantityFormatter {
     _alternateUnitLabelsRegistry = new AlternateUnitLabelsRegistry(getDefaultAlternateUnitLabels());
     /** Registry containing available quantity type definitions. */
     _quantityTypeRegistry = new Map();
+    /** Registry containing available FormatterSpec and ParserSpec, mapped by keys.
+     * @beta
+     */
+    _formatSpecsRegistry = new Map();
     /** Active UnitSystem key - must be one of "imperial", "metric", "usCustomary", or "usSurvey". */
     _activeUnitSystem = "imperial";
     /** Map of FormatSpecs for all available QuantityTypes and the active Unit System */
@@ -177,6 +235,7 @@ export class QuantityFormatter {
     onQuantityFormatsChanged = new BeUiEvent();
     /** Fired when the active UnitsProvider is updated. This will allow cached Formatter and Parser specs to be updated if necessary. */
     onUnitsProviderChanged = new BeUiEvent();
+    _removeFormatsProviderListener;
     /**
      * constructor
      * @param showMetricOrUnitSystem - Pass in `true` to show Metric formatted quantity values. Defaults to Imperial. To explicitly
@@ -190,6 +249,12 @@ export class QuantityFormatter {
                 this._activeUnitSystem = showMetricOrUnitSystem;
         }
     }
+    [Symbol.dispose]() {
+        if (this._removeFormatsProviderListener) {
+            this._removeFormatsProviderListener();
+            this._removeFormatsProviderListener = undefined;
+        }
+    }
     getOverrideFormatPropsByQuantityType(quantityTypeKey, unitSystem) {
         const requestedUnitSystem = unitSystem ?? this.activeUnitSystem;
         const overrideMap = this._overrideFormatPropsByUnitSystem.get(requestedUnitSystem);
@@ -315,6 +380,46 @@ export class QuantityFormatter {
      */
     async onInitialized() {
         await this.initializeQuantityTypesRegistry();
+        const initialKoQs = [["AecUnits.LENGTH", "Units.M"], ["AecUnits.ANGLE", "Units.RAD"], ["AecUnits.AREA", "Units.SQ_M"], ["AecUnits.VOLUME", "Units.CUB_M"], ["RoadRailUnits.STATION", "Units.M"], ["RoadRailUnits.LENGTH", "Units.M"]];
+        for (const entry of initialKoQs) {
+            try {
+                await this.addFormattingSpecsToRegistry(entry[0], entry[1]);
+            }
+            catch (err) {
+                Logger.logWarning(`${FrontendLoggerCategory.Package}.QuantityFormatter`, err.toString());
+            }
+        }
+        this._removeFormatsProviderListener = IModelApp.formatsProvider.onFormatsChanged.addListener(async (args) => {
+            if (args.formatsChanged === "all") {
+                for (const [name, entry] of this._formatSpecsRegistry.entries()) {
+                    const formatProps = await IModelApp.formatsProvider.getFormat(name);
+                    if (formatProps) {
+                        const persistenceUnitName = entry.formatterSpec.persistenceUnit.name;
+                        await this.addFormattingSpecsToRegistry(name, persistenceUnitName, formatProps);
+                    }
+                    else {
+                        this._formatSpecsRegistry.delete(name); // clear the specs if format was removed, or no longer exists.
+                    }
+                }
+            }
+            else {
+                for (const name of args.formatsChanged) {
+                    if (this._formatSpecsRegistry.has(name)) {
+                        const formatProps = await IModelApp.formatsProvider.getFormat(name);
+                        if (formatProps) {
+                            const existingEntry = this._formatSpecsRegistry.get(name);
+                            if (existingEntry) {
+                                const persistenceUnitName = existingEntry.formatterSpec.persistenceUnit.name;
+                                await this.addFormattingSpecsToRegistry(name, persistenceUnitName, formatProps);
+                            }
+                        }
+                        else {
+                            this._formatSpecsRegistry.delete(name);
+                        }
+                    }
+                }
+            }
+        });
         // initialize default format and parsing specs
         await this.loadFormatAndParsingMapsForSystem();
     }
@@ -544,26 +649,51 @@ export class QuantityFormatter {
             requestedSystem = isImperial ? "imperial" : "metric";
         return this.getParserSpecByQuantityTypeAndSystem(type, requestedSystem);
     }
-    /** Generates a formatted string for a quantity given its format spec.
-     * @param magnitude       The magnitude of the quantity.
-     * @param formatSpec      The format specification. See methods getFormatterSpecByQuantityType and findFormatterSpecByQuantityType.
-     * @return the formatted string.
-     */
-    formatQuantity(magnitude, formatSpec) {
-        /** Format a quantity value. Default FormatterSpec implementation uses Formatter.formatQuantity. */
-        if (formatSpec)
-            return formatSpec.applyFormatting(magnitude);
-        return magnitude.toString();
-    }
-    /** Parse input string into quantity given the ParserSpec
-     * @param inString       The magnitude of the quantity.
-     * @param parserSpec     The parse specification the defines the expected format of the string and the conversion to the output unit.
-     * @return QuantityParseResult object containing either the parsed value or an error value if unsuccessful.
-     */
-    parseToQuantityValue(inString, parserSpec) {
-        if (parserSpec)
-            return parserSpec.parseToQuantityValue(inString);
-        return { ok: false, error: ParseError.InvalidParserSpec };
+    // eslint-disable-next-line @typescript-eslint/promise-function-async
+    formatQuantity(args, spec) {
+        if (typeof args === "number") {
+            /** Format a quantity value. Default FormatterSpec implementation uses Formatter.formatQuantity. */
+            const magnitude = args;
+            if (spec)
+                return spec.applyFormatting(magnitude);
+            return magnitude.toString();
+        }
+        return this.formatQuantityAsync(args);
+    }
+    async formatQuantityAsync(args) {
+        const { value, valueUnitName, kindOfQuantityName } = args;
+        const formatProps = await IModelApp.formatsProvider.getFormat(kindOfQuantityName);
+        if (!formatProps)
+            return value.toString();
+        const formatSpec = await this.createFormatterSpec({
+            persistenceUnitName: valueUnitName,
+            formatProps,
+            formatName: kindOfQuantityName,
+        });
+        return formatSpec.applyFormatting(value);
+    }
+    // eslint-disable-next-line @typescript-eslint/promise-function-async
+    parseToQuantityValue(args, parserSpec) {
+        if (typeof args === "string") {
+            /** Parse a quantity value. Default ParserSpec implementation uses ParserSpec.parseToQuantityValue. */
+            const inString = args;
+            if (parserSpec)
+                return parserSpec.parseToQuantityValue(inString);
+            return { ok: false, error: ParseError.InvalidParserSpec };
+        }
+        return this.parseToQuantityValueAsync(args);
+    }
+    async parseToQuantityValueAsync(args) {
+        const { value, valueUnitName, kindOfQuantityName } = args;
+        const formatProps = await IModelApp.formatsProvider.getFormat(kindOfQuantityName);
+        if (!formatProps)
+            return { ok: false, error: ParseError.InvalidParserSpec };
+        const parserSpec = await this.createParserSpec({
+            persistenceUnitName: valueUnitName,
+            formatProps,
+            formatName: kindOfQuantityName,
+        });
+        return parserSpec.parseToQuantityValue(value);
     }
     /**
      * Get a UnitSystemKey from a string that may have been entered via a key-in. Supports different variation of
@@ -633,6 +763,63 @@ export class QuantityFormatter {
     async getConversion(fromUnit, toUnit) {
         return this._unitsProvider.getConversion(fromUnit, toUnit);
     }
+    /**
+     * Creates a [[FormatterSpec]] for a given persistence unit name and format properties, using the [[UnitsProvider]] to resolve the persistence unit.
+     * @beta
+     * @param props - A [[CreateFormattingSpecProps]] interface.
+     */
+    async createFormatterSpec(props) {
+        const { persistenceUnitName, formatProps, formatName } = props;
+        const persistenceUnitProps = await this._unitsProvider.findUnitByName(persistenceUnitName);
+        const format = await Format.createFromJSON(formatName ?? "temp", this._unitsProvider, formatProps);
+        return FormatterSpec.create(`${format.name}_format_spec`, format, this._unitsProvider, persistenceUnitProps);
+    }
+    /**
+     * Creates a [[ParserSpec]] for a given persistence unit name and format properties, using the [[UnitsProvider]] to resolve the persistence unit.
+     * @beta
+     * @param props - A [[CreateFormattingSpecProps]] object.
+     */
+    async createParserSpec(props) {
+        const { persistenceUnitName, formatProps, formatName } = props;
+        const persistenceUnitProps = await this._unitsProvider.findUnitByName(persistenceUnitName);
+        const format = await Format.createFromJSON(formatName ?? "temp", this._unitsProvider, formatProps);
+        return ParserSpec.create(format, this._unitsProvider, persistenceUnitProps);
+    }
+    /**
+     * @beta
+     * Returns a [[FormattingSpecEntry]] for a given name, typically a KindOfQuantity full name.
+     */
+    getSpecsByName(name) {
+        return this._formatSpecsRegistry.get(name);
+    }
+    /**
+   * Populates the registry with a new FormatterSpec and ParserSpec entry for the given format name.
+   * @beta
+   * @param name The key used to identify the formatter and parser spec
+   * @param persistenceUnitName The name of the persistence unit
+   * @param formatProps If not supplied, tries to retrieve the [[FormatProps]] from [[IModelApp.formatsProvider]]
+   */
+    async addFormattingSpecsToRegistry(name, persistenceUnitName, formatProps) {
+        if (!formatProps) {
+            formatProps = await IModelApp.formatsProvider.getFormat(name);
+        }
+        if (formatProps) {
+            const formatterSpec = await this.createFormatterSpec({
+                persistenceUnitName,
+                formatProps,
+                formatName: name,
+            });
+            const parserSpec = await this.createParserSpec({
+                persistenceUnitName,
+                formatProps,
+                formatName: name,
+            });
+            this._formatSpecsRegistry.set(name, { formatterSpec, parserSpec });
+        }
+        else {
+            throw new Error(`Unable to find format properties for ${name} with persistence unit ${persistenceUnitName}`);
+        }
+    }
 }
 // ========================================================================================================================================
 // Default Data