@itwin/core-frontend 5.9.0-dev.9 → 5.9.0

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

@@ -5,11 +5,11 @@
 /** @packageDocumentation
  * @module QuantityFormatting
  */
-import { BeEvent, BentleyError, BeUiEvent, Logger } from "@itwin/core-bentley";
-import { Format, FormatterSpec, ParseError, ParserSpec, } from "@itwin/core-quantity";
+import { BeEvent, BentleyError, BeUiEvent, BeUnorderedUiEvent, Logger } from "@itwin/core-bentley";
+import { BasicUnitsProvider, Format, FormatSpecHandle, FormatterSpec, FormattingReadyCollector, ParseError, ParserSpec, } from "@itwin/core-quantity";
 import { FrontendLoggerCategory } from "../common/FrontendLoggerCategory";
 import { IModelApp } from "../IModelApp";
-import { BasicUnitsProvider, getDefaultAlternateUnitLabels } from "./BasicUnitsProvider";
+import { getDefaultAlternateUnitLabels } from "./AlternateUnitLabels";
 // cSpell:ignore FORMATPROPS FORMATKEY ussurvey uscustomary USCUSTOM
 /**
  * Defines standard format types for tools that need to display measurements to user.
@@ -162,7 +162,7 @@ export class QuantityTypeFormatsProvider {
         ["CivilUnits.LENGTH", QuantityType.LengthEngineering],
         ["AecUnits.LENGTH", QuantityType.LengthEngineering]
     ]);
-    async getFormat(name) {
+    async getFormat(name, _system) {
         const quantityType = this._kindOfQuantityMap.get(name);
         if (!quantityType)
             return undefined;
@@ -177,36 +177,34 @@ export class QuantityTypeFormatsProvider {
 export class FormatsProviderManager {
     _formatsProvider;
     onFormatsChanged = new BeEvent();
+    _removeProviderListener;
     constructor(_formatsProvider) {
         this._formatsProvider = _formatsProvider;
-        this._formatsProvider.onFormatsChanged.addListener((args) => {
+        this._removeProviderListener = this._formatsProvider.onFormatsChanged.addListener((args) => {
             this.onFormatsChanged.raiseEvent(args);
         });
     }
-    async getFormat(name) {
-        return this._formatsProvider.getFormat(name);
+    async getFormat(name, system) {
+        return this._formatsProvider.getFormat(name, system);
     }
     get formatsProvider() { return this; }
     set formatsProvider(formatsProvider) {
+        this._removeProviderListener?.();
         this._formatsProvider = formatsProvider;
-        this._formatsProvider.onFormatsChanged.addListener((args) => {
+        this._removeProviderListener = 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]], and provide methods
- * to generate both a [[FormatterSpec]] and a [[ParserSpec]]. There are built-in quantity types that are
+/** The QuantityFormatter class provides methods for formatting and parsing quantities. There are a set of standard quantity types
  * 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.
  *
  * @public
  */
 export class QuantityFormatter {
+    static _allUnitSystems = ["metric", "imperial", "usCustomary", "usSurvey"];
     _unitsProvider = new BasicUnitsProvider();
     _alternateUnitLabelsRegistry = new AlternateUnitLabelsRegistry(getDefaultAlternateUnitLabels());
     /** Registry containing available quantity type definitions. */
@@ -217,9 +215,9 @@ export class QuantityFormatter {
     _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 */
+    /** Map of FormatSpecs for all available QuantityTypes, keyed by quantity type */
     _activeFormatSpecsByType = new Map();
-    /** Map of ParserSpecs for all available QuantityTypes and the active Unit System */
+    /** Map of ParserSpecs for all available QuantityTypes, keyed by quantity type */
     _activeParserSpecsByType = new Map();
     /** Map of FormatSpecs that have been overriden from the default. */
     _overrideFormatPropsByUnitSystem = new Map();
@@ -241,6 +239,45 @@ 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();
+    /** Fired after every reload path completes (initialization, unit system change, provider change, reinitialize).
+     * This is the terminal "ready" signal — it fires once the QuantityFormatter has fully rebuilt its caches and is
+     * ready to format/parse values. Subscribe to this event to know when formatting specs are available.
+     *
+     * Uses `BeUnorderedUiEvent` (Set-backed) so listeners can safely add/remove themselves during emit —
+     * this is critical for `FormatSpecHandle` instances that subscribe/dispose at volume.
+     * @beta
+     */
+    onFormattingReady = new BeUnorderedUiEvent();
+    /** Event for formatting providers to register async work before the formatter signals ready.
+     * Fires synchronously after each reload completes. Providers should call
+     * `collector.addPendingWork(promise)` to register work. The formatter awaits all
+     * registered work (with a 20-second default timeout) before emitting [[onFormattingReady]].
+     *
+     * Use this for **providers** that need async loading. Use [[onFormattingReady]] for
+     * **consumers** that read specs.
+     * @beta
+     */
+    onBeforeFormattingReady = new BeEvent();
+    /** Whether the QuantityFormatter has completed at least one successful reload and is ready to format/parse.
+     * @beta
+     */
+    get isReady() { return this._isReady; }
+    /** A promise that resolves after the first successful initialization. This is one-shot — it resolves once
+     * and stays resolved forever. For subsequent reloads, subscribe to [[onFormattingReady]].
+     *
+     * This promise never rejects. If the first initialization attempt fails, it stays pending until a
+     * subsequent reload succeeds (e.g., triggered by `setUnitsProvider` or a format change). There is no
+     * finite retry limit, so rejection would prematurely close the door on recovery.
+     * @beta
+     */
+    get whenInitialized() { return this._initializedPromise; }
+    _isReady = false;
+    _hasEverBeenReady = false;
+    _initializedPromise;
+    _resolveInitialized;
+    _reloadInFlight = false;
+    _pendingReload;
+    _deferredSystemChangedEmit;
     _removeFormatsProviderListener;
     /**
      * constructor
@@ -248,6 +285,9 @@ export class QuantityFormatter {
      * set it to a specific unit system pass a UnitSystemKey.
      */
     constructor(showMetricOrUnitSystem) {
+        this._initializedPromise = new Promise((resolve) => {
+            this._resolveInitialized = resolve;
+        });
         if (undefined !== showMetricOrUnitSystem) {
             if (typeof showMetricOrUnitSystem === "boolean")
                 this._activeUnitSystem = showMetricOrUnitSystem ? "metric" : "imperial";
@@ -261,6 +301,116 @@ export class QuantityFormatter {
             this._removeFormatsProviderListener = undefined;
         }
     }
+    /** Schedule an async reload. If no reload is in flight, runs immediately. If a reload is
+     * already in flight, stores the intent as pending (latest-wins: only the last scheduled reload
+     * is kept). `finalizeReload()` fires only when the queue is fully drained.
+     *
+     * **Await semantics:** When a reload is already in flight, the returned promise resolves
+     * immediately *without* the requested reload having run. Callers that need to know when
+     * the reload has actually completed should listen for `onFormattingReady` instead.
+     *
+     * Reload intents:
+     * - `"full"` — rebuild entire registry + re-register provider listener (onInitialized, setUnitsProvider)
+     * - `"formatsChanged"` — patch registry from provider + load maps (formatsChanged listener)
+     * - `"activeSystem"` — reload format/parsing maps for current unit system (setActiveUnitSystem, reinitializeFormatAndParsingsMaps)
+     * @internal
+     */
+    async scheduleReload(intent) {
+        if (this._reloadInFlight) {
+            // A reload is already running — queue this one (latest-wins)
+            this._pendingReload = intent;
+            return;
+        }
+        this._reloadInFlight = true;
+        this._isReady = false;
+        this._deferredSystemChangedEmit = undefined; // Clear stale deferred from prior cycle
+        try {
+            await this._executeReload(intent);
+        }
+        catch (err) {
+            Logger.logError(`${FrontendLoggerCategory.Package}.QuantityFormatter`, BentleyError.getErrorMessage(err));
+            this._reloadInFlight = false;
+            // If there's a pending reload, still try to run it
+            if (this._pendingReload) {
+                const next = this._pendingReload;
+                this._pendingReload = undefined;
+                return this.scheduleReload(next);
+            }
+            // Restore prior ready state so stale-but-usable specs remain accessible
+            if (this._hasEverBeenReady) {
+                Logger.logWarning(`${FrontendLoggerCategory.Package}.QuantityFormatter`, "Reload failed — restoring previous ready state. Cached specs may be stale.");
+                this._isReady = true;
+            }
+            return;
+        }
+        // Current reload succeeded — check if another was queued
+        if (this._pendingReload) {
+            const next = this._pendingReload;
+            this._pendingReload = undefined;
+            this._reloadInFlight = false;
+            return this.scheduleReload(next);
+        }
+        // Queue is drained — finalize
+        await this.finalizeReload();
+        // A new reload may have been queued during the async finalizeReload window
+        if (this._pendingReload) {
+            const next = this._pendingReload;
+            this._pendingReload = undefined;
+            this._reloadInFlight = false;
+            return this.scheduleReload(next);
+        }
+        this._reloadInFlight = false;
+    }
+    /** Execute the reload work for a given intent. All reload logic is centralized here.
+     * @internal
+     */
+    async _executeReload(intent) {
+        switch (intent.scope) {
+            case "full":
+                await this._reloadCore();
+                break;
+            case "formatsChanged": {
+                const { args } = intent;
+                await this._rebuildRegistryFromProvider(args);
+                if (args.impliedUnitSystem && args.impliedUnitSystem !== this._activeUnitSystem) {
+                    this._activeUnitSystem = args.impliedUnitSystem;
+                }
+                await this.loadFormatAndParsingMapsForSystem(this._activeUnitSystem);
+                if (args.impliedUnitSystem) {
+                    this._deferredSystemChangedEmit = { system: this._activeUnitSystem };
+                }
+                break;
+            }
+            case "activeSystem":
+                await this.loadFormatAndParsingMapsForSystem(this._activeUnitSystem);
+                if (intent.emitSystemChanged) {
+                    this._deferredSystemChangedEmit = { system: this._activeUnitSystem };
+                }
+                break;
+        }
+    }
+    /** Called when the reload queue is fully drained after a successful reload.
+     * Sets `isReady` to true, resolves `whenInitialized` (one-shot), and emits ready events.
+     * @internal
+     */
+    async finalizeReload() {
+        // Phase 1: Let providers register async work
+        const collector = new FormattingReadyCollector();
+        this.onBeforeFormattingReady.raiseEvent(collector);
+        await collector.awaitAll();
+        // Phase 2: Signal ready to consumers
+        this._isReady = true;
+        this._hasEverBeenReady = true;
+        this._resolveInitialized();
+        this.onFormattingReady.emit();
+        // Phase 3: Emit deferred unit-system-changed if the winning reload set one.
+        // This fires after isReady === true so listeners can safely use the formatter.
+        if (this._deferredSystemChangedEmit) {
+            const args = this._deferredSystemChangedEmit;
+            this._deferredSystemChangedEmit = undefined;
+            this.onActiveFormattingUnitSystemChanged.emit(args);
+        }
+    }
     getOverrideFormatPropsByQuantityType(quantityTypeKey, unitSystem) {
         const requestedUnitSystem = unitSystem ?? this.activeUnitSystem;
         const overrideMap = this._overrideFormatPropsByUnitSystem.get(requestedUnitSystem);
@@ -387,6 +537,12 @@ export class QuantityFormatter {
      * @internal
      */
     async onInitialized() {
+        await this.scheduleReload({ scope: "full" });
+    }
+    /** Core reload logic — does all async I/O and cache rebuilding without events or state management.
+     * @internal
+     */
+    async _reloadCore() {
         // Remove any existing listener before re-registering to avoid duplicates when called via setUnitsProvider.
         if (this._removeFormatsProviderListener) {
             this._removeFormatsProviderListener();
@@ -395,46 +551,61 @@ export class QuantityFormatter {
         await this.initializeQuantityTypesRegistry();
         const initialKoQs = [["DefaultToolsUnits.LENGTH", "Units.M"], ["DefaultToolsUnits.ANGLE", "Units.RAD"], ["DefaultToolsUnits.AREA", "Units.SQ_M"], ["DefaultToolsUnits.VOLUME", "Units.CUB_M"], ["DefaultToolsUnits.LENGTH_COORDINATE", "Units.M"], ["CivilUnits.STATION", "Units.M"], ["CivilUnits.LENGTH", "Units.M"], ["AecUnits.LENGTH", "Units.M"]];
         for (const entry of initialKoQs) {
-            try {
-                await this.addFormattingSpecsToRegistry(entry[0], entry[1]);
+            for (const system of QuantityFormatter._allUnitSystems) {
+                try {
+                    await this.addFormattingSpecsToRegistry({ name: entry[0], persistenceUnitName: entry[1], system });
+                }
+                catch (err) {
+                    Logger.logWarning(`${FrontendLoggerCategory.Package}.QuantityFormatter`, err.toString());
+                }
+            }
+        }
+        // Register formatsProvider listener that triggers a queued reload when formats change
+        this._removeFormatsProviderListener = IModelApp.formatsProvider.onFormatsChanged.addListener((args) => {
+            void this.scheduleReload({ scope: "formatsChanged", args });
+        });
+        // initialize default format and parsing specs
+        await this.loadFormatAndParsingMapsForSystem();
+    }
+    /** Rebuild the formatting specs registry from the current formatsProvider based on changed args.
+     * @internal
+     */
+    async _rebuildRegistryFromProvider(args) {
+        if (args.formatsChanged === "all") {
+            for (const [name, unitMap] of this._formatSpecsRegistry.entries()) {
+                await this._rebuildRegistryForName(name, unitMap);
             }
-            catch (err) {
-                Logger.logWarning(`${FrontendLoggerCategory.Package}.QuantityFormatter`, err.toString());
+        }
+        else {
+            for (const name of args.formatsChanged) {
+                const unitMap = this._formatSpecsRegistry.get(name);
+                if (unitMap) {
+                    await this._rebuildRegistryForName(name, unitMap);
+                }
             }
         }
-        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.
-                    }
+    }
+    /** Rebuild all system entries for a single KoQ name in the registry. */
+    async _rebuildRegistryForName(name, unitMap) {
+        let anySystemHadFormat = false;
+        for (const system of QuantityFormatter._allUnitSystems) {
+            const formatProps = await IModelApp.formatsProvider.getFormat(name, system);
+            if (formatProps) {
+                anySystemHadFormat = true;
+                for (const [persistenceUnitName] of unitMap.entries()) {
+                    await this.addFormattingSpecsToRegistry({ name, persistenceUnitName, formatProps, system });
                 }
             }
             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);
-                        }
-                    }
+                // Remove stale entries for this system
+                for (const [, systemMap] of unitMap.entries()) {
+                    systemMap.delete(system);
                 }
             }
-        });
-        // initialize default format and parsing specs
-        await this.loadFormatAndParsingMapsForSystem();
+        }
+        if (!anySystemHadFormat) {
+            this._formatSpecsRegistry.delete(name);
+        }
     }
     /** Return a map that serves as a registry of all standard and custom quantity types. */
     get quantityTypesRegistry() {
@@ -469,7 +640,7 @@ export class QuantityFormatter {
         this._unitsProvider = unitsProvider;
         try {
             // force all cached data to be reinitialized
-            await IModelApp.quantityFormatter.onInitialized();
+            await this.scheduleReload({ scope: "full" });
         }
         catch (err) {
             Logger.logWarning(`${FrontendLoggerCategory.Package}.quantityFormatter`, BentleyError.getErrorMessage(err), BentleyError.getErrorMetadata(err));
@@ -487,6 +658,7 @@ export class QuantityFormatter {
      * `IModelApp.toolAdmin.restartPrimitiveTool()` to allow the tool to reinitialize itself.
      */
     async resetToUseInternalUnitsProvider() {
+        // Coupled to createUnitsProvider() returning BasicUnitsProvider directly when no primary is set.
         if (this._unitsProvider instanceof BasicUnitsProvider)
             return;
         await this.setUnitsProvider(new BasicUnitsProvider());
@@ -516,8 +688,7 @@ export class QuantityFormatter {
             this._overrideFormatPropsByUnitSystem = overrideFormatPropsByUnitSystem;
         }
         unitSystemKey && (this._activeUnitSystem = unitSystemKey);
-        await this.loadFormatAndParsingMapsForSystem(this._activeUnitSystem);
-        fireUnitSystemChanged && this.onActiveFormattingUnitSystemChanged.emit({ system: this._activeUnitSystem });
+        await this.scheduleReload({ scope: "activeSystem", emitSystemChanged: fireUnitSystemChanged });
         IModelApp.toolAdmin && startDefaultTool && await IModelApp.toolAdmin.startDefaultTool();
     }
     /** Set the Active unit system to one of the supported types. This will asynchronously load the formatter and parser specs for the activated system. */
@@ -530,11 +701,9 @@ export class QuantityFormatter {
         if (this._activeUnitSystem === systemType)
             return;
         this._activeUnitSystem = systemType;
-        await this.loadFormatAndParsingMapsForSystem(systemType);
+        await this.scheduleReload({ scope: "activeSystem", emitSystemChanged: true });
         // allow settings provider to store the change
         await this._unitFormattingSettingsProvider?.storeUnitSystemSetting({ system: systemType });
-        // fire current event
-        this.onActiveFormattingUnitSystemChanged.emit({ system: systemType });
         if (IModelApp.toolAdmin && restartActiveTool)
             return IModelApp.toolAdmin.startDefaultTool();
     }
@@ -780,7 +949,10 @@ export class QuantityFormatter {
     }
     /** 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);
+        const result = await this._unitsProvider.getConversion(fromUnit, toUnit);
+        if (result.error)
+            Logger.logWarning(`${FrontendLoggerCategory.Package}.quantityFormatter`, `Unit conversion from "${fromUnit.name}" to "${toUnit.name}" could not be resolved.`);
+        return result;
     }
     /**
      * Creates a [[FormatterSpec]] for a given persistence unit name and format properties, using the [[UnitsProvider]] to resolve the persistence unit.
@@ -806,21 +978,50 @@ export class QuantityFormatter {
     }
     /**
      * @beta
-     * Returns a [[FormattingSpecEntry]] for a given name, typically a KindOfQuantity full name.
+     * Returns a map of [[FormattingSpecEntry]] keyed by persistence unit for a given name, typically a KindOfQuantity full name.
      */
     getSpecsByName(name) {
-        return this._formatSpecsRegistry.get(name);
+        const unitMap = this._formatSpecsRegistry.get(name);
+        if (!unitMap)
+            return undefined;
+        // Return active-system projection
+        const result = new Map();
+        for (const [persistenceUnit, systemMap] of unitMap) {
+            const entry = systemMap.get(this._activeUnitSystem);
+            if (entry)
+                result.set(persistenceUnit, entry);
+        }
+        return result.size > 0 ? result : undefined;
+    }
+    /**
+     * Returns a [[FormattingSpecEntry]] for a given name and persistence unit.
+     * @beta
+     */
+    getSpecsByNameAndUnit(args) {
+        const effectiveSystem = args.system ?? this._activeUnitSystem;
+        return this._formatSpecsRegistry.get(args.name)?.get(args.persistenceUnitName)?.get(effectiveSystem);
+    }
+    /** Create a cacheable handle to formatting specs for a specific KoQ and persistence unit.
+     * The handle auto-refreshes when the QuantityFormatter reloads. Call `dispose()` when done.
+     *
+     * @param koqName - The KindOfQuantity name (e.g., "DefaultToolsUnits.LENGTH")
+     * @param persistenceUnit - The persistence unit name (e.g., "Units.M")
+     * @returns A FormatSpecHandle that auto-updates on reload
+     * @beta
+     */
+    getFormatSpecHandle(koqName, persistenceUnit, system) {
+        return new FormatSpecHandle({ provider: this, name: koqName, persistenceUnitName: persistenceUnit, system });
     }
     /**
    * 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) {
+    async addFormattingSpecsToRegistry(args) {
+        const { name, persistenceUnitName } = args;
+        const effectiveSystem = args.system ?? this._activeUnitSystem;
+        let formatProps = args.formatProps;
         if (!formatProps) {
-            formatProps = await IModelApp.formatsProvider.getFormat(name);
+            formatProps = await IModelApp.formatsProvider.getFormat(name, effectiveSystem);
         }
         if (formatProps) {
             const formatterSpec = await this.createFormatterSpec({
@@ -833,7 +1034,12 @@ export class QuantityFormatter {
                 formatProps,
                 formatName: name,
             });
-            this._formatSpecsRegistry.set(name, { formatterSpec, parserSpec });
+            if (!this._formatSpecsRegistry.has(name))
+                this._formatSpecsRegistry.set(name, new Map());
+            const unitMap = this._formatSpecsRegistry.get(name);
+            if (!unitMap.has(persistenceUnitName))
+                unitMap.set(persistenceUnitName, new Map());
+            unitMap.get(persistenceUnitName).set(effectiveSystem, { formatterSpec, parserSpec });
         }
         else {
             throw new Error(`Unable to find format properties for ${name} with persistence unit ${persistenceUnitName}`);