@itwin/core-quantity 5.9.0-dev.9 → 5.9.1

package/lib/esm/Formatter/FormatterSpec.js

@@ -5,6 +5,8 @@
 /** @packageDocumentation
  * @module Quantity
  */
+import { Logger } from "@itwin/core-bentley";
+import { QuantityLoggerCategory } from "../QuantityLoggerCategory";
 import { FormatType } from "./FormatEnums";
 import { Formatter } from "./Formatter";
 // cSpell:ignore ZERONORMALIZED, nosign, onlynegative, signalways, negativeparentheses
@@ -60,6 +62,9 @@ export class FormatterSpec {
         const [denominatorUnit, denominatorLabel] = units[1];
         // Compute ratio scale: how many numerator units per denominator unit (e.g., IN:FT = 12)
         const denominatorToNumerator = await unitsProvider.getConversion(denominatorUnit, numeratorUnit);
+        if (denominatorToNumerator.error) {
+            Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from "${denominatorUnit.name}" to "${numeratorUnit.name}" could not be resolved.`);
+        }
         const displayRatioScale = denominatorToNumerator.factor;
         // Avoid double-scaling: if persistence unit already encodes the display ratio, use factor 1.
         // Check by name heuristic (e.g., IN_PER_FT with ratioUnits [IN, FT] → no scaling needed)
@@ -119,6 +124,9 @@ export class FormatterSpec {
                 let unitConversion;
                 if (convertFromUnit) {
                     unitConversion = await unitsProvider.getConversion(convertFromUnit, unit[0]);
+                    if (unitConversion.error) {
+                        Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from "${convertFromUnit.name}" to "${unit[0].name}" could not be resolved.`);
+                    }
                 }
                 else {
                     unitConversion = { factor: 1.0, offset: 0.0 };
@@ -151,6 +159,9 @@ export class FormatterSpec {
         if (format.azimuthBaseUnit !== undefined) {
             if (inputUnit !== undefined) {
                 azimuthBaseConversion = await unitsProvider.getConversion(format.azimuthBaseUnit, inputUnit);
+                if (azimuthBaseConversion.error) {
+                    Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from "${format.azimuthBaseUnit.name}" to "${inputUnit.name}" could not be resolved.`);
+                }
             }
             else {
                 azimuthBaseConversion = { factor: 1.0, offset: 0.0 };
@@ -160,6 +171,9 @@ export class FormatterSpec {
         if (format.revolutionUnit !== undefined) {
             if (inputUnit !== undefined) {
                 revolutionConversion = await unitsProvider.getConversion(format.revolutionUnit, inputUnit);
+                if (revolutionConversion.error) {
+                    Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from "${format.revolutionUnit.name}" to "${inputUnit.name}" could not be resolved.`);
+                }
             }
             else {
                 revolutionConversion = { factor: 1.0, offset: 0.0 };

package/lib/esm/Formatter/FormatterSpec.js.map

@@ -1 +1 @@
-{"version":3,"file":"FormatterSpec.js","sourceRoot":"","sources":["../../../src/Formatter/FormatterSpec.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,sFAAsF;AACtF,6JAA6J;AAE7J;;;GAGG;AACH,MAAM,OAAO,aAAa;IACd,KAAK,CAAS;IACd,YAAY,GAAyB,EAAE,CAAC,CAAE,mBAAmB;IAC7D,OAAO,CAAS;IAChB,gBAAgB,CAAY;IAC5B,sBAAsB,CAAuB,CAAC,iDAAiD;IAC/F,qBAAqB,CAAuB,CAAC,+CAA+C;IAEtG;;;;;;;OAOG;IACH,YAAY,IAAY,EAAE,MAAc,EAAE,WAAkC,EAAE,eAA2B,EAAE,qBAA2C,EAAE,oBAA0C;QAChM,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAChC,eAAe,GAAG,KAAK,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,gBAAgB,GAAG,eAAe,CAAC;QACxC,IAAI,WAAW;YACb,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;QAClC,IAAI,CAAC,sBAAsB,GAAG,qBAAqB,CAAC;QACpD,IAAI,CAAC,qBAAqB,GAAG,oBAAoB,CAAC;IACpD,CAAC;IAED,IAAW,IAAI,KAAa,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAChD,uHAAuH;IACvH,IAAW,eAAe,KAA2B,OAAO,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IAChF,IAAW,MAAM,KAAa,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IACpD,IAAW,eAAe,KAAgB,OAAO,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACzE,IAAW,qBAAqB,KAAsC,OAAO,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC;IAC3G,IAAW,oBAAoB,KAAsC,OAAO,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC;IAEzG,8FAA8F;IACtF,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,KAAqD,EAAE,aAA4B,EAAE,eAA0B;QAC1J,MAAM,WAAW,GAAyB,EAAE,CAAC;QAE7C,MAAM,CAAC,aAAa,EAAE,cAAc,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACjD,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAErD,wFAAwF;QACxF,MAAM,sBAAsB,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC;QACjG,MAAM,iBAAiB,GAAG,sBAAsB,CAAC,MAAM,CAAC;QAExD,6FAA6F;QAC7F,yFAAyF;QACzF,MAAM,eAAe,GAAG,eAAe,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAC3D,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;QACxE,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;QAC1E,iFAAiF;QACjF,MAAM,iBAAiB,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACxD,MAAM,0BAA0B,GAAG,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9G,MAAM,gBAAgB,GAAG,0BAA0B,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC;QAE9E,yDAAyD;QACzD,MAAM,mBAAmB,GAAuB;YAC9C,IAAI,EAAE,GAAG,aAAa,CAAC,IAAI,QAAQ,eAAe,CAAC,IAAI,EAAE;YACzD,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,aAAa,CAAC,MAAM;YAC5B,UAAU,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,EAAE;SACtD,CAAC;QACF,WAAW,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAEtC,kCAAkC;QAClC,MAAM,aAAa,GAAuB;YACxC,IAAI,EAAE,aAAa,CAAC,IAAI;YACxB,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK;YACpE,MAAM,EAAE,aAAa,CAAC,MAAM;YAC5B,UAAU,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;SACzC,CAAC;QACF,WAAW,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAEhC,oCAAoC;QACpC,MAAM,eAAe,GAAuB;YAC1C,IAAI,EAAE,eAAe,CAAC,IAAI;YAC1B,KAAK,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK;YAC1E,MAAM,EAAE,eAAe,CAAC,MAAM;YAC9B,UAAU,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;SACzC,CAAC;QACF,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAElC,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,mHAAmH;IAC5G,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAc,EAAE,aAA4B,EAAE,SAAqB;QACxG,MAAM,WAAW,GAAyB,EAAE,CAAC;QAC7C,IAAI,eAAe,GAAG,SAAS,CAAC;QAChC,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAChC,eAAe,GAAG,KAAK,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;QAED,4DAA4D;QAC5D,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClF,OAAO,aAAa,CAAC,uBAAuB,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,eAAe,CAAC,CAAC;QAC7F,CAAC;QAED,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,IAAI,eAAe,GAAG,SAAS,CAAC;YAChC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBAChC,IAAI,cAAmC,CAAC;gBACxC,IAAI,eAAe,EAAE,CAAC;oBACpB,cAAc,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC/E,CAAC;qBAAM,CAAC;oBACN,cAAc,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;gBAChD,CAAC;gBACD,MAAM,SAAS,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;gBAC5E,MAAM,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAuB,CAAC;gBAElI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACvB,eAAe,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,0GAA0G;YAC1G,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,IAAI,GAAuB,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC;gBACtJ,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,MAAc,EAAE,aAA4B,EAAE,SAAqB;QAC1G,MAAM,WAAW,GAAyB,MAAM,aAAa,CAAC,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;QACnH,IAAI,qBAAsD,CAAC;QAC3D,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;YACzC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,qBAAqB,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;YAC/F,CAAC;iBAAM,CAAC;gBACN,qBAAqB,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;YACvD,CAAC;QACH,CAAC;QACD,IAAI,oBAAqD,CAAC;QAC1D,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YACxC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,oBAAoB,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;YAC7F,CAAC;iBAAM,CAAC;gBACN,oBAAoB,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;YACtD,CAAC;QACH,CAAC;QAED,OAAO,IAAI,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,qBAAqB,EAAE,oBAAoB,CAAC,CAAC;IAC9G,CAAC;IAED,+BAA+B;IACxB,eAAe,CAAC,SAAiB;QACtC,OAAO,SAAS,CAAC,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACnD,CAAC;CACF","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Quantity\n */\n\nimport { UnitConversionProps, UnitConversionSpec, UnitProps, UnitsProvider } from \"../Interfaces\";\nimport { Format } from \"./Format\";\nimport { FormatType } from \"./FormatEnums\";\nimport { Formatter } from \"./Formatter\";\n\n// cSpell:ignore ZERONORMALIZED, nosign, onlynegative, signalways, negativeparentheses\n// cSpell:ignore trailzeroes, keepsinglezero, zeroempty, keepdecimalpoint, applyrounding, fractiondash, showunitlabel, prependunitlabel, exponentonlynegative\n\n/** A class that contains both formatting information and the conversion factors necessary to convert from an input unit to the units specified in the format.\n * Once created the FormatterSpec will be able to format quantity values with synchronous calls.\n * @beta\n */\nexport class FormatterSpec {\n  protected _name: string;\n  protected _conversions: UnitConversionSpec[] = [];  // max four entries\n  protected _format: Format;\n  protected _persistenceUnit: UnitProps;\n  protected _azimuthBaseConversion?: UnitConversionProps; // converts azimuth base unit to persistence unit\n  protected _revolutionConversion?: UnitConversionProps; // converts revolution unit to persistence unit\n\n  /** Constructor\n   *  @param name     The name of a format specification.\n   *  @param format   Defines the output format for the quantity value.\n   *  @param conversions An array of conversion factors necessary to convert from an input unit to the units specified in the format.\n   *  @param persistenceUnit The unit the magnitude value is input.\n   *  @param azimuthBaseConversion The conversion used to interpret azimuth base values.\n   *  @param revolutionConversion The conversion used to determine a revolution value (used for bearing and azimuth).\n   */\n  constructor(name: string, format: Format, conversions?: UnitConversionSpec[], persistenceUnit?: UnitProps, azimuthBaseConversion?: UnitConversionProps, revolutionConversion?: UnitConversionProps) {\n    if (!persistenceUnit) {\n      if (format.units) {\n        const [props] = format.units[0];\n        persistenceUnit = props;\n      } else {\n        throw new Error(\"Formatter Spec needs persistence unit to be specified\");\n      }\n    }\n\n    this._name = name;\n    this._format = format;\n    this._persistenceUnit = persistenceUnit;\n    if (conversions)\n      this._conversions = conversions;\n    this._azimuthBaseConversion = azimuthBaseConversion;\n    this._revolutionConversion = revolutionConversion;\n  }\n\n  public get name(): string { return this._name; }\n  /** Returns an array of UnitConversionSpecs, one for each unit that is to be shown in the formatted quantity string. */\n  public get unitConversions(): UnitConversionSpec[] { return this._conversions; }\n  public get format(): Format { return this._format; }\n  public get persistenceUnit(): UnitProps { return this._persistenceUnit; }\n  public get azimuthBaseConversion(): UnitConversionProps | undefined { return this._azimuthBaseConversion; }\n  public get revolutionConversion(): UnitConversionProps | undefined { return this._revolutionConversion; }\n\n  /** Build conversion specs for ratio format with 2 composite units (numerator/denominator). */\n  private static async getRatioUnitConversions(units: ReadonlyArray<[UnitProps, string | undefined]>, unitsProvider: UnitsProvider, persistenceUnit: UnitProps): Promise<UnitConversionSpec[]> {\n    const conversions: UnitConversionSpec[] = [];\n\n    const [numeratorUnit, numeratorLabel] = units[0];\n    const [denominatorUnit, denominatorLabel] = units[1];\n\n    // Compute ratio scale: how many numerator units per denominator unit (e.g., IN:FT = 12)\n    const denominatorToNumerator = await unitsProvider.getConversion(denominatorUnit, numeratorUnit);\n    const displayRatioScale = denominatorToNumerator.factor;\n\n    // Avoid double-scaling: if persistence unit already encodes the display ratio, use factor 1.\n    // Check by name heuristic (e.g., IN_PER_FT with ratioUnits [IN, FT] → no scaling needed)\n    const persistenceName = persistenceUnit.name.toUpperCase();\n    const numName = numeratorUnit.name.toUpperCase().split(\".\").pop() ?? \"\";\n    const denName = denominatorUnit.name.toUpperCase().split(\".\").pop() ?? \"\";\n    // Split by word boundaries (underscores, dots) and check for exact token matches\n    const persistenceTokens = persistenceName.split(/[._]/);\n    const isPersistenceMatchingRatio = persistenceTokens.includes(numName) && persistenceTokens.includes(denName);\n    const ratioScaleFactor = isPersistenceMatchingRatio ? 1.0 : displayRatioScale;\n\n    // First conversion spec: effective ratio unit conversion\n    const ratioConversionSpec: UnitConversionSpec = {\n      name: `${numeratorUnit.name}_per_${denominatorUnit.name}`,\n      label: \"\",\n      system: numeratorUnit.system,\n      conversion: { factor: ratioScaleFactor, offset: 0.0 },\n    };\n    conversions.push(ratioConversionSpec);\n\n    // Numerator unit for label lookup\n    const numeratorSpec: UnitConversionSpec = {\n      name: numeratorUnit.name,\n      label: numeratorLabel?.length ? numeratorLabel : numeratorUnit.label,\n      system: numeratorUnit.system,\n      conversion: { factor: 1.0, offset: 0.0 },\n    };\n    conversions.push(numeratorSpec);\n\n    // Denominator unit for label lookup\n    const denominatorSpec: UnitConversionSpec = {\n      name: denominatorUnit.name,\n      label: denominatorLabel?.length ? denominatorLabel : denominatorUnit.label,\n      system: denominatorUnit.system,\n      conversion: { factor: 1.0, offset: 0.0 },\n    };\n    conversions.push(denominatorSpec);\n\n    return conversions;\n  }\n\n  /** Get an array of UnitConversionSpecs, one for each unit that is to be shown in the formatted quantity string. */\n  public static async getUnitConversions(format: Format, unitsProvider: UnitsProvider, inputUnit?: UnitProps): Promise<UnitConversionSpec[]> {\n    const conversions: UnitConversionSpec[] = [];\n    let persistenceUnit = inputUnit;\n    if (!persistenceUnit) {\n      if (format.units) {\n        const [props] = format.units[0];\n        persistenceUnit = props;\n      } else {\n        throw new Error(\"Formatter Spec needs persistence unit to be specified\");\n      }\n    }\n\n    // Handle 2-unit composite for ratio formats (scale factors)\n    if (format.type === FormatType.Ratio && format.units && format.units.length === 2) {\n      return FormatterSpec.getRatioUnitConversions(format.units, unitsProvider, persistenceUnit);\n    }\n\n    if (format.units) {\n      let convertFromUnit = inputUnit;\n      for (const unit of format.units) {\n        let unitConversion: UnitConversionProps;\n        if (convertFromUnit) {\n          unitConversion = await unitsProvider.getConversion(convertFromUnit, unit[0]);\n        } else {\n          unitConversion = { factor: 1.0, offset: 0.0 };\n        }\n        const unitLabel = (unit[1] && unit[1].length > 0) ? unit[1] : unit[0].label;\n        const spec = ({ name: unit[0].name, label: unitLabel, conversion: unitConversion, system: unit[0].system }) as UnitConversionSpec;\n\n        conversions.push(spec);\n        convertFromUnit = unit[0];\n      }\n    } else {\n      // if format is only numeric and a input unit is defined set spec to use the input unit as the format unit\n      if (inputUnit) {\n        const spec: UnitConversionSpec = { name: inputUnit.name, label: inputUnit.label, system: inputUnit.system, conversion: { factor: 1.0, offset: 0.0 } };\n        conversions.push(spec);\n      }\n    }\n\n    return conversions;\n  }\n\n  /** Static async method to create a FormatSpec given the format and unit of the quantity that will be passed to the Formatter. The input unit will\n   * be used to generate conversion information for each unit specified in the Format. This method is async due to the fact that the units provider must make\n   * async calls to lookup unit definitions.\n   *  @param name     The name of a format specification.\n   *  @param unitsProvider The units provider is used to look up unit definitions and provide conversion information for converting between units.\n   *  @param inputUnit The unit the value to be formatted. This unit is often referred to as persistence unit.\n   */\n  public static async create(name: string, format: Format, unitsProvider: UnitsProvider, inputUnit?: UnitProps): Promise<FormatterSpec> {\n    const conversions: UnitConversionSpec[] = await FormatterSpec.getUnitConversions(format, unitsProvider, inputUnit);\n    let azimuthBaseConversion: UnitConversionProps | undefined;\n    if (format.azimuthBaseUnit !== undefined) {\n      if (inputUnit !== undefined) {\n        azimuthBaseConversion = await unitsProvider.getConversion(format.azimuthBaseUnit, inputUnit);\n      } else {\n        azimuthBaseConversion = { factor: 1.0, offset: 0.0 };\n      }\n    }\n    let revolutionConversion: UnitConversionProps | undefined;\n    if (format.revolutionUnit !== undefined) {\n      if (inputUnit !== undefined) {\n        revolutionConversion = await unitsProvider.getConversion(format.revolutionUnit, inputUnit);\n      } else {\n        revolutionConversion = { factor: 1.0, offset: 0.0 };\n      }\n    }\n\n    return new FormatterSpec(name, format, conversions, inputUnit, azimuthBaseConversion, revolutionConversion);\n  }\n\n  /** Format a quantity value. */\n  public applyFormatting(magnitude: number): string {\n    return Formatter.formatQuantity(magnitude, this);\n  }\n}\n"]}
+{"version":3,"file":"FormatterSpec.js","sourceRoot":"","sources":["../../../src/Formatter/FormatterSpec.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Quantity\n */\n\nimport { Logger } from \"@itwin/core-bentley\";\nimport { UnitConversionProps, UnitConversionSpec, UnitProps, UnitsProvider } from \"../Interfaces\";\nimport { QuantityLoggerCategory } from \"../QuantityLoggerCategory\";\nimport { Format } from \"./Format\";\nimport { FormatType } from \"./FormatEnums\";\nimport { Formatter } from \"./Formatter\";\n\n// cSpell:ignore ZERONORMALIZED, nosign, onlynegative, signalways, negativeparentheses\n// cSpell:ignore trailzeroes, keepsinglezero, zeroempty, keepdecimalpoint, applyrounding, fractiondash, showunitlabel, prependunitlabel, exponentonlynegative\n\n/** A class that contains both formatting information and the conversion factors necessary to convert from an input unit to the units specified in the format.\n * Once created the FormatterSpec will be able to format quantity values with synchronous calls.\n * @beta\n */\nexport class FormatterSpec {\n  protected _name: string;\n  protected _conversions: UnitConversionSpec[] = [];  // max four entries\n  protected _format: Format;\n  protected _persistenceUnit: UnitProps;\n  protected _azimuthBaseConversion?: UnitConversionProps; // converts azimuth base unit to persistence unit\n  protected _revolutionConversion?: UnitConversionProps; // converts revolution unit to persistence unit\n\n  /** Constructor\n   *  @param name     The name of a format specification.\n   *  @param format   Defines the output format for the quantity value.\n   *  @param conversions An array of conversion factors necessary to convert from an input unit to the units specified in the format.\n   *  @param persistenceUnit The unit the magnitude value is input.\n   *  @param azimuthBaseConversion The conversion used to interpret azimuth base values.\n   *  @param revolutionConversion The conversion used to determine a revolution value (used for bearing and azimuth).\n   */\n  constructor(name: string, format: Format, conversions?: UnitConversionSpec[], persistenceUnit?: UnitProps, azimuthBaseConversion?: UnitConversionProps, revolutionConversion?: UnitConversionProps) {\n    if (!persistenceUnit) {\n      if (format.units) {\n        const [props] = format.units[0];\n        persistenceUnit = props;\n      } else {\n        throw new Error(\"Formatter Spec needs persistence unit to be specified\");\n      }\n    }\n\n    this._name = name;\n    this._format = format;\n    this._persistenceUnit = persistenceUnit;\n    if (conversions)\n      this._conversions = conversions;\n    this._azimuthBaseConversion = azimuthBaseConversion;\n    this._revolutionConversion = revolutionConversion;\n  }\n\n  public get name(): string { return this._name; }\n  /** Returns an array of UnitConversionSpecs, one for each unit that is to be shown in the formatted quantity string. */\n  public get unitConversions(): UnitConversionSpec[] { return this._conversions; }\n  public get format(): Format { return this._format; }\n  public get persistenceUnit(): UnitProps { return this._persistenceUnit; }\n  public get azimuthBaseConversion(): UnitConversionProps | undefined { return this._azimuthBaseConversion; }\n  public get revolutionConversion(): UnitConversionProps | undefined { return this._revolutionConversion; }\n\n  /** Build conversion specs for ratio format with 2 composite units (numerator/denominator). */\n  private static async getRatioUnitConversions(units: ReadonlyArray<[UnitProps, string | undefined]>, unitsProvider: UnitsProvider, persistenceUnit: UnitProps): Promise<UnitConversionSpec[]> {\n    const conversions: UnitConversionSpec[] = [];\n\n    const [numeratorUnit, numeratorLabel] = units[0];\n    const [denominatorUnit, denominatorLabel] = units[1];\n\n    // Compute ratio scale: how many numerator units per denominator unit (e.g., IN:FT = 12)\n    const denominatorToNumerator = await unitsProvider.getConversion(denominatorUnit, numeratorUnit);\n    if (denominatorToNumerator.error) {\n      Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from \"${denominatorUnit.name}\" to \"${numeratorUnit.name}\" could not be resolved.`);\n    }\n    const displayRatioScale = denominatorToNumerator.factor;\n\n    // Avoid double-scaling: if persistence unit already encodes the display ratio, use factor 1.\n    // Check by name heuristic (e.g., IN_PER_FT with ratioUnits [IN, FT] → no scaling needed)\n    const persistenceName = persistenceUnit.name.toUpperCase();\n    const numName = numeratorUnit.name.toUpperCase().split(\".\").pop() ?? \"\";\n    const denName = denominatorUnit.name.toUpperCase().split(\".\").pop() ?? \"\";\n    // Split by word boundaries (underscores, dots) and check for exact token matches\n    const persistenceTokens = persistenceName.split(/[._]/);\n    const isPersistenceMatchingRatio = persistenceTokens.includes(numName) && persistenceTokens.includes(denName);\n    const ratioScaleFactor = isPersistenceMatchingRatio ? 1.0 : displayRatioScale;\n\n    // First conversion spec: effective ratio unit conversion\n    const ratioConversionSpec: UnitConversionSpec = {\n      name: `${numeratorUnit.name}_per_${denominatorUnit.name}`,\n      label: \"\",\n      system: numeratorUnit.system,\n      conversion: { factor: ratioScaleFactor, offset: 0.0 },\n    };\n    conversions.push(ratioConversionSpec);\n\n    // Numerator unit for label lookup\n    const numeratorSpec: UnitConversionSpec = {\n      name: numeratorUnit.name,\n      label: numeratorLabel?.length ? numeratorLabel : numeratorUnit.label,\n      system: numeratorUnit.system,\n      conversion: { factor: 1.0, offset: 0.0 },\n    };\n    conversions.push(numeratorSpec);\n\n    // Denominator unit for label lookup\n    const denominatorSpec: UnitConversionSpec = {\n      name: denominatorUnit.name,\n      label: denominatorLabel?.length ? denominatorLabel : denominatorUnit.label,\n      system: denominatorUnit.system,\n      conversion: { factor: 1.0, offset: 0.0 },\n    };\n    conversions.push(denominatorSpec);\n\n    return conversions;\n  }\n\n  /** Get an array of UnitConversionSpecs, one for each unit that is to be shown in the formatted quantity string. */\n  public static async getUnitConversions(format: Format, unitsProvider: UnitsProvider, inputUnit?: UnitProps): Promise<UnitConversionSpec[]> {\n    const conversions: UnitConversionSpec[] = [];\n    let persistenceUnit = inputUnit;\n    if (!persistenceUnit) {\n      if (format.units) {\n        const [props] = format.units[0];\n        persistenceUnit = props;\n      } else {\n        throw new Error(\"Formatter Spec needs persistence unit to be specified\");\n      }\n    }\n\n    // Handle 2-unit composite for ratio formats (scale factors)\n    if (format.type === FormatType.Ratio && format.units && format.units.length === 2) {\n      return FormatterSpec.getRatioUnitConversions(format.units, unitsProvider, persistenceUnit);\n    }\n\n    if (format.units) {\n      let convertFromUnit = inputUnit;\n      for (const unit of format.units) {\n        let unitConversion: UnitConversionProps;\n        if (convertFromUnit) {\n          unitConversion = await unitsProvider.getConversion(convertFromUnit, unit[0]);\n          if (unitConversion.error) {\n            Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from \"${convertFromUnit.name}\" to \"${unit[0].name}\" could not be resolved.`);\n          }\n        } else {\n          unitConversion = { factor: 1.0, offset: 0.0 };\n        }\n        const unitLabel = (unit[1] && unit[1].length > 0) ? unit[1] : unit[0].label;\n        const spec = ({ name: unit[0].name, label: unitLabel, conversion: unitConversion, system: unit[0].system }) as UnitConversionSpec;\n\n        conversions.push(spec);\n        convertFromUnit = unit[0];\n      }\n    } else {\n      // if format is only numeric and a input unit is defined set spec to use the input unit as the format unit\n      if (inputUnit) {\n        const spec: UnitConversionSpec = { name: inputUnit.name, label: inputUnit.label, system: inputUnit.system, conversion: { factor: 1.0, offset: 0.0 } };\n        conversions.push(spec);\n      }\n    }\n\n    return conversions;\n  }\n\n  /** Static async method to create a FormatSpec given the format and unit of the quantity that will be passed to the Formatter. The input unit will\n   * be used to generate conversion information for each unit specified in the Format. This method is async due to the fact that the units provider must make\n   * async calls to lookup unit definitions.\n   *  @param name     The name of a format specification.\n   *  @param unitsProvider The units provider is used to look up unit definitions and provide conversion information for converting between units.\n   *  @param inputUnit The unit the value to be formatted. This unit is often referred to as persistence unit.\n   */\n  public static async create(name: string, format: Format, unitsProvider: UnitsProvider, inputUnit?: UnitProps): Promise<FormatterSpec> {\n    const conversions: UnitConversionSpec[] = await FormatterSpec.getUnitConversions(format, unitsProvider, inputUnit);\n    let azimuthBaseConversion: UnitConversionProps | undefined;\n    if (format.azimuthBaseUnit !== undefined) {\n      if (inputUnit !== undefined) {\n        azimuthBaseConversion = await unitsProvider.getConversion(format.azimuthBaseUnit, inputUnit);\n        if (azimuthBaseConversion.error) {\n          Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from \"${format.azimuthBaseUnit.name}\" to \"${inputUnit.name}\" could not be resolved.`);\n        }\n      } else {\n        azimuthBaseConversion = { factor: 1.0, offset: 0.0 };\n      }\n    }\n    let revolutionConversion: UnitConversionProps | undefined;\n    if (format.revolutionUnit !== undefined) {\n      if (inputUnit !== undefined) {\n        revolutionConversion = await unitsProvider.getConversion(format.revolutionUnit, inputUnit);\n        if (revolutionConversion.error) {\n          Logger.logWarning(QuantityLoggerCategory.Formatting, `Unit conversion from \"${format.revolutionUnit.name}\" to \"${inputUnit.name}\" could not be resolved.`);\n        }\n      } else {\n        revolutionConversion = { factor: 1.0, offset: 0.0 };\n      }\n    }\n\n    return new FormatterSpec(name, format, conversions, inputUnit, azimuthBaseConversion, revolutionConversion);\n  }\n\n  /** Format a quantity value. */\n  public applyFormatting(magnitude: number): string {\n    return Formatter.formatQuantity(magnitude, this);\n  }\n}\n"]}

package/lib/esm/Formatter/FormattingReadyCollector.d.ts

@@ -0,0 +1,16 @@
+/** @module Quantity */
+/** Collects async work from formatting providers during the pre-ready phase.
+ * Providers call [[addPendingWork]] to register promises that the formatter
+ * will await before signaling [[QuantityFormatter.onFormattingReady]].
+ * @beta
+ */
+export declare class FormattingReadyCollector {
+    private _promises;
+    /** Register async work that must complete before the formatter signals ready.
+     * Call this from an `onBeforeFormattingReady` listener.
+     */
+    addPendingWork(work: Promise<void>): void;
+    /** @internal Await all registered work with a timeout. Logs warnings for rejections and timeouts. */
+    awaitAll(timeoutMs?: number): Promise<void>;
+}
+//# sourceMappingURL=FormattingReadyCollector.d.ts.map

package/lib/esm/Formatter/FormattingReadyCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormattingReadyCollector.d.ts","sourceRoot":"","sources":["../../../src/Formatter/FormattingReadyCollector.ts"],"names":[],"mappings":"AAIA,uBAAuB;AAKvB;;;;GAIG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,SAAS,CAAuB;IAExC;;OAEG;IACI,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAIhD,qGAAqG;IACxF,QAAQ,CAAC,SAAS,GAAE,MAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAmBjE"}

package/lib/esm/Formatter/FormattingReadyCollector.js

@@ -0,0 +1,40 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @module Quantity */
+import { Logger } from "@itwin/core-bentley";
+import { QuantityLoggerCategory } from "../QuantityLoggerCategory";
+/** Collects async work from formatting providers during the pre-ready phase.
+ * Providers call [[addPendingWork]] to register promises that the formatter
+ * will await before signaling [[QuantityFormatter.onFormattingReady]].
+ * @beta
+ */
+export class FormattingReadyCollector {
+    _promises = [];
+    /** Register async work that must complete before the formatter signals ready.
+     * Call this from an `onBeforeFormattingReady` listener.
+     */
+    addPendingWork(work) {
+        this._promises.push(work);
+    }
+    /** @internal Await all registered work with a timeout. Logs warnings for rejections and timeouts. */
+    async awaitAll(timeoutMs = 20_000) {
+        if (this._promises.length === 0)
+            return;
+        const timeout = new Promise((resolve) => setTimeout(() => resolve("timeout"), timeoutMs));
+        const work = Promise.allSettled(this._promises).then((results) => {
+            for (const result of results) {
+                if (result.status === "rejected") {
+                    Logger.logWarning(QuantityLoggerCategory.Formatting, "FormattingReadyCollector: a provider's async work rejected", () => ({ reason: result.reason }));
+                }
+            }
+            return "done";
+        });
+        const outcome = await Promise.race([work, timeout]);
+        if (outcome === "timeout") {
+            Logger.logWarning(QuantityLoggerCategory.Formatting, `FormattingReadyCollector: timed out after ${timeoutMs}ms waiting for ${this._promises.length} provider(s). Proceeding with ready signal.`);
+        }
+    }
+}
+//# sourceMappingURL=FormattingReadyCollector.js.map

package/lib/esm/Formatter/FormattingReadyCollector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormattingReadyCollector.js","sourceRoot":"","sources":["../../../src/Formatter/FormattingReadyCollector.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F,uBAAuB;AAEvB,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,OAAO,wBAAwB;IAC3B,SAAS,GAAoB,EAAE,CAAC;IAExC;;OAEG;IACI,cAAc,CAAC,IAAmB;QACvC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,qGAAqG;IAC9F,KAAK,CAAC,QAAQ,CAAC,YAAoB,MAAM;QAC9C,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YAC7B,OAAO;QAET,MAAM,OAAO,GAAG,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;QACrG,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;YAC/D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;oBACjC,MAAM,CAAC,UAAU,CAAC,sBAAsB,CAAC,UAAU,EAAE,4DAA4D,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;gBACxJ,CAAC;YACH,CAAC;YACD,OAAO,MAAe,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QACpD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,CAAC,UAAU,CAAC,sBAAsB,CAAC,UAAU,EAAE,6CAA6C,SAAS,kBAAkB,IAAI,CAAC,SAAS,CAAC,MAAM,6CAA6C,CAAC,CAAC;QACnM,CAAC;IACH,CAAC;CACF","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @module Quantity */\n\nimport { Logger } from \"@itwin/core-bentley\";\nimport { QuantityLoggerCategory } from \"../QuantityLoggerCategory\";\n\n/** Collects async work from formatting providers during the pre-ready phase.\n * Providers call [[addPendingWork]] to register promises that the formatter\n * will await before signaling [[QuantityFormatter.onFormattingReady]].\n * @beta\n */\nexport class FormattingReadyCollector {\n  private _promises: Promise<void>[] = [];\n\n  /** Register async work that must complete before the formatter signals ready.\n   * Call this from an `onBeforeFormattingReady` listener.\n   */\n  public addPendingWork(work: Promise<void>): void {\n    this._promises.push(work);\n  }\n\n  /** @internal Await all registered work with a timeout. Logs warnings for rejections and timeouts. */\n  public async awaitAll(timeoutMs: number = 20_000): Promise<void> {\n    if (this._promises.length === 0)\n      return;\n\n    const timeout = new Promise<\"timeout\">((resolve) => setTimeout(() => resolve(\"timeout\"), timeoutMs));\n    const work = Promise.allSettled(this._promises).then((results) => {\n      for (const result of results) {\n        if (result.status === \"rejected\") {\n          Logger.logWarning(QuantityLoggerCategory.Formatting, \"FormattingReadyCollector: a provider's async work rejected\", () => ({ reason: result.reason }));\n        }\n      }\n      return \"done\" as const;\n    });\n\n    const outcome = await Promise.race([work, timeout]);\n    if (outcome === \"timeout\") {\n      Logger.logWarning(QuantityLoggerCategory.Formatting, `FormattingReadyCollector: timed out after ${timeoutMs}ms waiting for ${this._promises.length} provider(s). Proceeding with ready signal.`);\n    }\n  }\n}\n"]}

package/lib/esm/Formatter/Interfaces.d.ts

@@ -1,9 +1,11 @@
 /** @packageDocumentation
  * @module Quantity
  */
-import { BeEvent } from "@itwin/core-bentley";
-import { UnitProps } from "../Interfaces";
+import { BeEvent, BeUnorderedUiEvent } from "@itwin/core-bentley";
+import { UnitProps, UnitSystemKey } from "../Interfaces";
 import { DecimalPrecision, FormatTraits, FormatType, FractionalPrecision } from "./FormatEnums";
+import type { FormatterSpec } from "./FormatterSpec";
+import type { ParserSpec } from "../ParserSpec";
 /** Defines a unit specification with a name and optional label override.
  * Used in composite formats and ratio unit specifications.
  * @beta
@@ -150,6 +152,13 @@ export interface FormatsChangedArgs {
      * If array, the array items list the names of formats that were changed or removed.
      */
     formatsChanged: "all" | string[];
+    /** If set, indicates that the format set implies a particular unit system. The consumer
+     * (e.g., QuantityFormatter) will synchronize the active unit system to match.
+     * If `undefined`, the format change does not imply a unit system switch — the active
+     * unit system remains unchanged.
+     * @beta
+     */
+    impliedUnitSystem?: UnitSystemKey;
 }
 /** This interface is implemented by a class that would provide formats for use in formatting quantities.
  * @beta
@@ -158,7 +167,7 @@ export interface FormatsProvider {
     /**
      * @param name The full name of the Format or KindOfQuantity.
      */
-    getFormat(name: string): Promise<FormatDefinition | undefined>;
+    getFormat(name: string, system?: UnitSystemKey): Promise<FormatDefinition | undefined>;
     /**
      * Fired when formats are added, removed, or changed.
      * If all formats are changed, a single string "all" is emitted. Else, an array of changed format names is emitted.
@@ -179,4 +188,43 @@ export interface MutableFormatsProvider extends FormatsProvider {
      */
     removeFormat(name: string): Promise<void>;
 }
+/** Entries returned when looking up specs from the format registry.
+ * @beta
+ */
+export interface FormattingSpecEntry {
+    formatterSpec: FormatterSpec;
+    parserSpec: ParserSpec;
+}
+/** Arguments for looking up a formatting spec entry.
+ * @beta
+ */
+export interface FormattingSpecArgs {
+    /** The KoQ name to look up. */
+    name: string;
+    /** The persistence unit name (e.g., `"Units.M"`). */
+    persistenceUnitName: string;
+    /** Optional unit system override. When omitted, the active system is used. */
+    system?: UnitSystemKey;
+}
+/** Arguments for registering a formatting spec entry.
+ * @beta
+ */
+export interface AddFormattingSpecArgs extends FormattingSpecArgs {
+    /** Format properties to use. When omitted, the provider resolves them from the KoQ schema. */
+    formatProps?: FormatProps;
+}
+/** Minimal contract required by [[FormatSpecHandle]] to look up specs and subscribe to reloads.
+ * Implemented by [[QuantityFormatter]] in `@itwin/core-frontend`.
+ * @beta
+ */
+export interface FormattingSpecProvider {
+    /** Look up a formatting spec entry by KoQ name and persistence unit. */
+    getSpecsByNameAndUnit(args: FormattingSpecArgs): FormattingSpecEntry | undefined;
+    /** Format a numeric value using the given formatter spec. */
+    formatQuantity(magnitude: number, formatSpec: FormatterSpec): string;
+    /** Event raised after the provider has finished reloading its caches.
+     * Uses Set-backed event for safe concurrent add/remove during emit.
+     */
+    readonly onFormattingReady: BeUnorderedUiEvent<void>;
+}
 //# sourceMappingURL=Interfaces.d.ts.map

package/lib/esm/Formatter/Interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Interfaces.d.ts","sourceRoot":"","sources":["../../../src/Formatter/Interfaces.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Interfaces.d.ts","sourceRoot":"","sources":["../../../src/Formatter/Interfaces.ts"],"names":[],"mappings":"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"}

package/lib/esm/Formatter/Interfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"Interfaces.js","sourceRoot":"","sources":["../../../src/Formatter/Interfaces.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAsHH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,IAAiB,EAA6B,EAAE;IAClF,OAAQ,IAA0B,CAAC,MAAM,KAAK,SAAS,CAAC;AAC1D,CAAC,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Quantity\n */\n\nimport { BeEvent } from \"@itwin/core-bentley\";\nimport { UnitProps } from \"../Interfaces\";\nimport { DecimalPrecision, FormatTraits, FormatType, FractionalPrecision } from \"./FormatEnums\";\n\n/** Defines a unit specification with a name and optional label override.\n * Used in composite formats and ratio unit specifications.\n * @beta\n */\nexport interface FormatUnitSpec {\n  /** The name of the unit (e.g., \"Units.FT\", \"Units.IN\") */\n  readonly name: string;\n  /** Optional custom label that overrides the unit's default label (e.g., '\"' for inches, \"'\" for feet) */\n  readonly label?: string;\n}\n\n/** A resolved [[FormatUnitSpec]] with the unit name replaced with the resolved UnitProps.\n * @beta\n */\nexport interface ResolvedFormatUnitSpec {\n  /** The resolved unit */\n  readonly unit: UnitProps;\n  /** Optional custom label that overrides the unit's default label */\n  readonly label?: string;\n}\n\n/** Defines the units that make up a composite format and their display properties.\n * A composite format allows displaying a single quantity value across multiple units,\n * such as displaying length as \"5 feet 6 inches\" or angle as \"45° 30' 15\"\".\n * @beta\n */\nexport interface FormatCompositeProps {\n  /** Separator character between unit values when formatting composite strings. Must be empty or a single character. */\n  readonly spacer?: string;\n  /** Whether to include unit segments with zero magnitude in the formatted output. */\n  readonly includeZero?: boolean;\n  /** Array of units this format is comprised of. Each unit specifies the unit name and\n   * an optional custom label that will override the unit's default label when displaying values. */\n  readonly units: FormatUnitSpec[];\n}\n\n/** This interface defines the persistence format for describing the formatting of quantity values.\n * @beta\n */\nexport interface FormatProps {\n  /** The format type. See [[FormatType]] */\n  readonly type: string;\n\n  /** The precision for the format. Must be an integer. See [[DecimalPrecision]] and [[FractionalPrecision]] */\n  readonly precision?: number;\n\n  /** Value is rounded to a multiple of this factor if nonzero and the `applyRounding` trait is set, defaults to 0 */\n  readonly roundFactor?: number;\n\n  /** Minimum width of the formatted output including digits and separators. Must be a positive integer (≥ 0). */\n  readonly minWidth?: number;\n\n  /** How and when positive and negative signs are displayed. See [[ShowSignOption]] */\n  readonly showSignOption?: string;\n\n  /** Array of format traits controlling display behavior. See [[FormatTraits]] */\n  readonly formatTraits?: string | string[];\n\n  /** Character separating integer from fractional part. Must be empty or a single character. */\n  readonly decimalSeparator?: string;\n\n  /** Character separating thousands in the integer part. Must be empty or a single character. */\n  readonly thousandSeparator?: string;\n\n  /** Character separating the magnitude from the unit label. Must be empty or a single character. */\n  readonly uomSeparator?: string;\n\n  /** Required when type is Scientific. See [[ScientificType]] */\n  readonly scientificType?: string;\n\n  /** Required when type is Ratio. See [[RatioType]]*/\n  readonly ratioType?: string;\n  /** The separator character for ratio formatting. Defaults to ':' if not specified. */\n  readonly ratioSeparator?: string;\n   /** The format type for the numbers within a ratio. Defaults to \"Decimal\". */\n  readonly ratioFormatType?: string;\n\n  /** Required when type is Station. Number of decimal places for calculating station offset magnitude. Must be a positive integer > 0. */\n  readonly stationOffsetSize?: number;\n\n  /** Character separating station and offset portions of a Station formatted value. Must be empty or a single character. */\n  readonly stationSeparator?: string;\n\n  /** Optional base factor for station formatting. A positive integer, defaults to 1. */\n  readonly stationBaseFactor?: number;\n\n  /** The base value for azimuth, specified from east counter-clockwise. */\n  readonly azimuthBase?: number;\n\n  /** The name of the unit for the azimuth base value. Required if azimuthBase is set. */\n  readonly azimuthBaseUnit?: string;\n\n  /** If set to true, azimuth values are returned counter-clockwise from the base. */\n  readonly azimuthCounterClockwise?: boolean;\n\n  /** The name of the unit that represents a revolution/perigon. Required for bearing or azimuth types. */\n  readonly revolutionUnit?: string;\n\n  /** Enables calculating mathematic operations during parsing; only addition and subtraction are supported. */\n  readonly allowMathematicOperations?: boolean;\n\n  /** Composite format specification for multi-unit display. */\n  readonly composite?: FormatCompositeProps;\n}\n\n/** This interface is used when supporting Custom Formatters that need more than the standard set of properties.\n * @beta\n */\nexport interface CustomFormatProps extends FormatProps {\n  readonly custom: any;\n}\n\n/** CustomFormatProps type guard.\n * @beta\n */\nexport const isCustomFormatProps = (item: FormatProps): item is CustomFormatProps => {\n  return (item as CustomFormatProps).custom !== undefined;\n};\n\n/** A [[FormatCompositeProps]] with unit names replaced with JSON representations of those units.\n * @beta\n */\nexport type ResolvedFormatCompositeProps = Omit<FormatCompositeProps, \"units\"> & {\n  readonly units: ResolvedFormatUnitSpec[];\n};\n\n/** A [[FormatProps]] with all the references to units replaced with JSON representations of those units.\n * @beta\n */\nexport type ResolvedFormatProps = Omit<FormatDefinition, \"azimuthBaseUnit\" | \"revolutionUnit\" | \"composite\"> & {\n  readonly azimuthBaseUnit?: UnitProps;\n  readonly revolutionUnit?: UnitProps;\n  readonly composite?: ResolvedFormatCompositeProps;\n  readonly custom?: any;\n};\n\n/** CloneFormat defines unit and label specification if primary unit is to be set during clone.\n * @beta\n */\nexport interface CloneUnit {\n  unit?: UnitProps;\n  label?: string;\n}\n\n/** CloneOptions that define modifications that can be made during the cloning of a Format.\n * @beta\n */\nexport interface CloneOptions {\n  /** allows composite formats to be converted to only show primary unit */\n  showOnlyPrimaryUnit?: boolean;\n  /** allow format traits to be set */\n  traits?: FormatTraits;\n  /** allows new FormatType to be specified */\n  type?: FormatType;\n  /** allows precision to be set, this will throw if value is not valid for FormatType */\n  precision?: DecimalPrecision | FractionalPrecision;\n  /** allows primary unit and label to be specified */\n  primaryUnit?: CloneUnit;\n}\n\n/** An extension of FormatProps to help identify formats.\n * @beta\n */\nexport interface FormatDefinition extends FormatProps {\n  readonly name?: string;\n  readonly label?: string;\n  readonly description?: string;\n}\n\n/** Argument for [[FormatsProvider.onFormatsChanged]]\n * @beta\n */\nexport interface FormatsChangedArgs {\n  /**\n   * If `all` - all formats within the `FormatsProvider` have changed.\n   * If array, the array items list the names of formats that were changed or removed.\n   */\n  formatsChanged: \"all\" | string[];\n}\n\n/** This interface is implemented by a class that would provide formats for use in formatting quantities.\n * @beta\n */\nexport interface FormatsProvider {\n  /**\n   * @param name The full name of the Format or KindOfQuantity.\n   */\n  getFormat(name: string): Promise<FormatDefinition | undefined>;\n\n  /**\n   * Fired when formats are added, removed, or changed.\n   * If all formats are changed, a single string \"all\" is emitted. Else, an array of changed format names is emitted.\n   */\n  onFormatsChanged: BeEvent<(args: FormatsChangedArgs) => void>;\n}\n\n/** This interface is implemented by a class that would provide and allow creating formats for use in formatting quantities.\n * @beta\n */\nexport interface MutableFormatsProvider extends FormatsProvider {\n  /**\n   * Adds a new format or updates an existing format associated with the specified name.\n   */\n  addFormat(name: string, format: FormatDefinition): Promise<void>;\n  /**\n   * Removes the format associated with the specified name.\n   * @param name The name of the format to remove.\n   */\n  removeFormat(name: string): Promise<void>;\n}\n"]}
+{"version":3,"file":"Interfaces.js","sourceRoot":"","sources":["../../../src/Formatter/Interfaces.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAwHH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,IAAiB,EAA6B,EAAE;IAClF,OAAQ,IAA0B,CAAC,MAAM,KAAK,SAAS,CAAC;AAC1D,CAAC,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Quantity\n */\n\nimport { BeEvent, BeUnorderedUiEvent } from \"@itwin/core-bentley\";\nimport { UnitProps, UnitSystemKey } from \"../Interfaces\";\nimport { DecimalPrecision, FormatTraits, FormatType, FractionalPrecision } from \"./FormatEnums\";\nimport type { FormatterSpec } from \"./FormatterSpec\";\nimport type { ParserSpec } from \"../ParserSpec\";\n\n/** Defines a unit specification with a name and optional label override.\n * Used in composite formats and ratio unit specifications.\n * @beta\n */\nexport interface FormatUnitSpec {\n  /** The name of the unit (e.g., \"Units.FT\", \"Units.IN\") */\n  readonly name: string;\n  /** Optional custom label that overrides the unit's default label (e.g., '\"' for inches, \"'\" for feet) */\n  readonly label?: string;\n}\n\n/** A resolved [[FormatUnitSpec]] with the unit name replaced with the resolved UnitProps.\n * @beta\n */\nexport interface ResolvedFormatUnitSpec {\n  /** The resolved unit */\n  readonly unit: UnitProps;\n  /** Optional custom label that overrides the unit's default label */\n  readonly label?: string;\n}\n\n/** Defines the units that make up a composite format and their display properties.\n * A composite format allows displaying a single quantity value across multiple units,\n * such as displaying length as \"5 feet 6 inches\" or angle as \"45° 30' 15\"\".\n * @beta\n */\nexport interface FormatCompositeProps {\n  /** Separator character between unit values when formatting composite strings. Must be empty or a single character. */\n  readonly spacer?: string;\n  /** Whether to include unit segments with zero magnitude in the formatted output. */\n  readonly includeZero?: boolean;\n  /** Array of units this format is comprised of. Each unit specifies the unit name and\n   * an optional custom label that will override the unit's default label when displaying values. */\n  readonly units: FormatUnitSpec[];\n}\n\n/** This interface defines the persistence format for describing the formatting of quantity values.\n * @beta\n */\nexport interface FormatProps {\n  /** The format type. See [[FormatType]] */\n  readonly type: string;\n\n  /** The precision for the format. Must be an integer. See [[DecimalPrecision]] and [[FractionalPrecision]] */\n  readonly precision?: number;\n\n  /** Value is rounded to a multiple of this factor if nonzero and the `applyRounding` trait is set, defaults to 0 */\n  readonly roundFactor?: number;\n\n  /** Minimum width of the formatted output including digits and separators. Must be a positive integer (≥ 0). */\n  readonly minWidth?: number;\n\n  /** How and when positive and negative signs are displayed. See [[ShowSignOption]] */\n  readonly showSignOption?: string;\n\n  /** Array of format traits controlling display behavior. See [[FormatTraits]] */\n  readonly formatTraits?: string | string[];\n\n  /** Character separating integer from fractional part. Must be empty or a single character. */\n  readonly decimalSeparator?: string;\n\n  /** Character separating thousands in the integer part. Must be empty or a single character. */\n  readonly thousandSeparator?: string;\n\n  /** Character separating the magnitude from the unit label. Must be empty or a single character. */\n  readonly uomSeparator?: string;\n\n  /** Required when type is Scientific. See [[ScientificType]] */\n  readonly scientificType?: string;\n\n  /** Required when type is Ratio. See [[RatioType]]*/\n  readonly ratioType?: string;\n  /** The separator character for ratio formatting. Defaults to ':' if not specified. */\n  readonly ratioSeparator?: string;\n   /** The format type for the numbers within a ratio. Defaults to \"Decimal\". */\n  readonly ratioFormatType?: string;\n\n  /** Required when type is Station. Number of decimal places for calculating station offset magnitude. Must be a positive integer > 0. */\n  readonly stationOffsetSize?: number;\n\n  /** Character separating station and offset portions of a Station formatted value. Must be empty or a single character. */\n  readonly stationSeparator?: string;\n\n  /** Optional base factor for station formatting. A positive integer, defaults to 1. */\n  readonly stationBaseFactor?: number;\n\n  /** The base value for azimuth, specified from east counter-clockwise. */\n  readonly azimuthBase?: number;\n\n  /** The name of the unit for the azimuth base value. Required if azimuthBase is set. */\n  readonly azimuthBaseUnit?: string;\n\n  /** If set to true, azimuth values are returned counter-clockwise from the base. */\n  readonly azimuthCounterClockwise?: boolean;\n\n  /** The name of the unit that represents a revolution/perigon. Required for bearing or azimuth types. */\n  readonly revolutionUnit?: string;\n\n  /** Enables calculating mathematic operations during parsing; only addition and subtraction are supported. */\n  readonly allowMathematicOperations?: boolean;\n\n  /** Composite format specification for multi-unit display. */\n  readonly composite?: FormatCompositeProps;\n}\n\n/** This interface is used when supporting Custom Formatters that need more than the standard set of properties.\n * @beta\n */\nexport interface CustomFormatProps extends FormatProps {\n  readonly custom: any;\n}\n\n/** CustomFormatProps type guard.\n * @beta\n */\nexport const isCustomFormatProps = (item: FormatProps): item is CustomFormatProps => {\n  return (item as CustomFormatProps).custom !== undefined;\n};\n\n/** A [[FormatCompositeProps]] with unit names replaced with JSON representations of those units.\n * @beta\n */\nexport type ResolvedFormatCompositeProps = Omit<FormatCompositeProps, \"units\"> & {\n  readonly units: ResolvedFormatUnitSpec[];\n};\n\n/** A [[FormatProps]] with all the references to units replaced with JSON representations of those units.\n * @beta\n */\nexport type ResolvedFormatProps = Omit<FormatDefinition, \"azimuthBaseUnit\" | \"revolutionUnit\" | \"composite\"> & {\n  readonly azimuthBaseUnit?: UnitProps;\n  readonly revolutionUnit?: UnitProps;\n  readonly composite?: ResolvedFormatCompositeProps;\n  readonly custom?: any;\n};\n\n/** CloneFormat defines unit and label specification if primary unit is to be set during clone.\n * @beta\n */\nexport interface CloneUnit {\n  unit?: UnitProps;\n  label?: string;\n}\n\n/** CloneOptions that define modifications that can be made during the cloning of a Format.\n * @beta\n */\nexport interface CloneOptions {\n  /** allows composite formats to be converted to only show primary unit */\n  showOnlyPrimaryUnit?: boolean;\n  /** allow format traits to be set */\n  traits?: FormatTraits;\n  /** allows new FormatType to be specified */\n  type?: FormatType;\n  /** allows precision to be set, this will throw if value is not valid for FormatType */\n  precision?: DecimalPrecision | FractionalPrecision;\n  /** allows primary unit and label to be specified */\n  primaryUnit?: CloneUnit;\n}\n\n/** An extension of FormatProps to help identify formats.\n * @beta\n */\nexport interface FormatDefinition extends FormatProps {\n  readonly name?: string;\n  readonly label?: string;\n  readonly description?: string;\n}\n\n/** Argument for [[FormatsProvider.onFormatsChanged]]\n * @beta\n */\nexport interface FormatsChangedArgs {\n  /**\n   * If `all` - all formats within the `FormatsProvider` have changed.\n   * If array, the array items list the names of formats that were changed or removed.\n   */\n  formatsChanged: \"all\" | string[];\n  /** If set, indicates that the format set implies a particular unit system. The consumer\n   * (e.g., QuantityFormatter) will synchronize the active unit system to match.\n   * If `undefined`, the format change does not imply a unit system switch — the active\n   * unit system remains unchanged.\n   * @beta\n   */\n  impliedUnitSystem?: UnitSystemKey;\n}\n\n/** This interface is implemented by a class that would provide formats for use in formatting quantities.\n * @beta\n */\nexport interface FormatsProvider {\n  /**\n   * @param name The full name of the Format or KindOfQuantity.\n   */\n  getFormat(name: string, system?: UnitSystemKey): Promise<FormatDefinition | undefined>;\n\n  /**\n   * Fired when formats are added, removed, or changed.\n   * If all formats are changed, a single string \"all\" is emitted. Else, an array of changed format names is emitted.\n   */\n  onFormatsChanged: BeEvent<(args: FormatsChangedArgs) => void>;\n}\n\n/** This interface is implemented by a class that would provide and allow creating formats for use in formatting quantities.\n * @beta\n */\nexport interface MutableFormatsProvider extends FormatsProvider {\n  /**\n   * Adds a new format or updates an existing format associated with the specified name.\n   */\n  addFormat(name: string, format: FormatDefinition): Promise<void>;\n  /**\n   * Removes the format associated with the specified name.\n   * @param name The name of the format to remove.\n   */\n  removeFormat(name: string): Promise<void>;\n}\n\n/** Entries returned when looking up specs from the format registry.\n * @beta\n */\nexport interface FormattingSpecEntry {\n  formatterSpec: FormatterSpec;\n  parserSpec: ParserSpec;\n}\n\n/** Arguments for looking up a formatting spec entry.\n * @beta\n */\nexport interface FormattingSpecArgs {\n  /** The KoQ name to look up. */\n  name: string;\n  /** The persistence unit name (e.g., `\"Units.M\"`). */\n  persistenceUnitName: string;\n  /** Optional unit system override. When omitted, the active system is used. */\n  system?: UnitSystemKey;\n}\n\n/** Arguments for registering a formatting spec entry.\n * @beta\n */\nexport interface AddFormattingSpecArgs extends FormattingSpecArgs {\n  /** Format properties to use. When omitted, the provider resolves them from the KoQ schema. */\n  formatProps?: FormatProps;\n}\n\n/** Minimal contract required by [[FormatSpecHandle]] to look up specs and subscribe to reloads.\n * Implemented by [[QuantityFormatter]] in `@itwin/core-frontend`.\n * @beta\n */\nexport interface FormattingSpecProvider {\n  /** Look up a formatting spec entry by KoQ name and persistence unit. */\n  getSpecsByNameAndUnit(args: FormattingSpecArgs): FormattingSpecEntry | undefined;\n  /** Format a numeric value using the given formatter spec. */\n  formatQuantity(magnitude: number, formatSpec: FormatterSpec): string;\n  /** Event raised after the provider has finished reloading its caches.\n   * Uses Set-backed event for safe concurrent add/remove during emit.\n   */\n  readonly onFormattingReady: BeUnorderedUiEvent<void>;\n}\n\n"]}

package/lib/esm/Interfaces.d.ts

@@ -66,6 +66,13 @@ export interface UnitConversionProps {
     offset: number;
     /** If set, inverts the unit value (1/x) before or after conversion. */
     inversion?: UnitConversionInvert;
+    /**
+     * If `true`, the conversion could not be resolved (e.g. unknown unit, incompatible phenomena).
+     * When `error` is `true`, `factor` MUST be `1.0` and `offset` MUST be `0.0` (identity).
+     * Callers must check this flag before applying the conversion — applying an identity conversion
+     * silently produces wrong output.
+     */
+    error?: boolean;
 }
 /** Interface that defines potential parse units that may be found in user's string input of a quantity value.
  * @beta
@@ -90,10 +97,33 @@ export interface UnitsProvider {
     findUnit(unitLabel: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps>;
     getUnitsByFamily(phenomenon: string): Promise<UnitProps[]>;
     findUnitByName(unitName: string): Promise<UnitProps>;
+    /**
+     * Compute the conversion factors from `fromUnit` to `toUnit`.
+     * On failure (unknown unit, incompatible phenomena), implementations MUST return
+     * `{ factor: 1.0, offset: 0.0, error: true }`. Throwing is also permitted;
+     * composite providers treat a throw as equivalent to `error: true`.
+     * Callers MUST check `result.error` before applying the conversion.
+     */
     getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversionProps>;
 }
 /**
- * Used to uniquely identify a unit system.
+ * Identifies a user-facing unit system preference group.
+ *
+ * A `UnitSystemKey` does **not** map one-to-one to an EC `UnitSystem` element. Instead, each key
+ * represents a *preference group* that matches against one or more EC `UnitSystem` names in
+ * priority order when resolving formats from a `KindOfQuantity`:
+ *
+ * | Key            | EC UnitSystems matched (highest priority first)         |
+ * | -------------- | ------------------------------------------------------- |
+ * | `"metric"`     | SI / METRIC, INTERNATIONAL, FINANCE                     |
+ * | `"imperial"`   | IMPERIAL, USCUSTOM, INTERNATIONAL, FINANCE               |
+ * | `"usCustomary"`| USCUSTOM, INTERNATIONAL, FINANCE                         |
+ * | `"usSurvey"`   | USSURVEY, USCUSTOM, INTERNATIONAL, FINANCE               |
+ *
+ * EC `UnitSystem` elements not listed above (e.g. CGS, MARITIME, INDUSTRIAL) are not covered by
+ * any preference group and will only appear if a `KindOfQuantity` explicitly references them.
+ *
+ * @see [SchemaFormatsProvider]($ecschema-metadata) for how preference groups resolve formats.
  * @beta
  */
 export type UnitSystemKey = "metric" | "imperial" | "usCustomary" | "usSurvey";

package/lib/esm/Interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Interfaces.d.ts","sourceRoot":"","sources":["../../src/Interfaces.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sBAAsB,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,EAAE,GAAG,SAAS,CAAC;CACnE;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wHAAwH;IACxH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uGAAuG;IACvG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,UAAU,EAAE,mBAAmB,CAAC;IAChC,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,mGAAmG;IACnG,mBAAmB,wBAAwB;IAC3C,gGAAgG;IAChG,oBAAoB,yBAAyB;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,oBAAoB,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/G,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC3D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACrD,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACrF;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC"}
+{"version":3,"file":"Interfaces.d.ts","sourceRoot":"","sources":["../../src/Interfaces.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,sBAAsB,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,EAAE,GAAG,SAAS,CAAC;CACnE;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wHAAwH;IACxH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uGAAuG;IACvG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,UAAU,EAAE,mBAAmB,CAAC;IAChC,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,mGAAmG;IACnG,mBAAmB,wBAAwB;IAC3C,gGAAgG;IAChG,oBAAoB,yBAAyB;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/G,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC3D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACrD;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACrF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC"}

package/lib/esm/Interfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"Interfaces.js","sourceRoot":"","sources":["../../src/Interfaces.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAmDH;;GAEG;AACH,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B,mGAAmG;IACnG,mEAA2C,CAAA;IAC3C,gGAAgG;IAChG,qEAA6C,CAAA;AAC/C,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Quantity\n */\n\n/** This interface allows a provider to be specified that will define an array of alternate labels for a specific unit.\n * @beta\n */\nexport interface AlternateUnitLabelsProvider {\n  getAlternateUnitLabels: (unit: UnitProps) => string[] | undefined;\n}\n\n/** This interface provides basic information about a Unit that is return from a UnitProvider. This info\n * uniquely identifies a unit by its name.\n * @beta\n */\nexport interface UnitProps {\n  /** Unique name for unit. */\n  readonly name: string;\n  /** Default label for unit. */\n  readonly label: string;\n  /** Unique name of unit phenomenon. Example phenomenon names include 'Units.LENGTH', 'Units.AREA', and 'Units.VOLUME' */\n  readonly phenomenon: string;\n  /** This is set to true if the Unit is known by the UnitsProvider. */\n  readonly isValid: boolean;\n  /** Unique system name. Example \"Units.USCUSTOM\",\" Units.METRIC\", \"Units.USSURVEY\", \"Units.IMPERIAL\" */\n  readonly system: string;\n}\n\n/** This interface defines the required properties of a Quantity.\n * @beta\n */\nexport interface QuantityProps {\n  readonly magnitude: number;\n  readonly unit: UnitProps;\n  readonly isValid: boolean;\n}\n\n/** Interface that defines how to convert between a specific unit an another in synchronous formatting or parsing processing.\n * @beta\n */\nexport interface UnitConversionSpec {\n  /** Unit name that was used to locate the unit by the Unit Provider */\n  name: string;\n  /** The default label that is used to display unit */\n  label: string;\n  /** Unit system name, used to when finding preferred parse unit */\n  system: string;\n  /** the information necessary to convert the unit to a specific display unit */\n  conversion: UnitConversionProps;\n  /** Labels that may be used to represent the unit in a string that is to be parsed. */\n  parseLabels?: string[];\n}\n\n/** Indicates the way in which unit values are inverted during conversion\n * @beta\n */\nexport enum UnitConversionInvert {\n  /** Invert value before applying the other conversion steps (the from-unit is the inverted unit) */\n  InvertPreConversion = \"InvertPreConversion\",\n  /** Invert value after applying the other conversion steps (the to-unit is the inverted unit) */\n  InvertPostConversion = \"InvertPostConversion\"\n}\n\n/** This interface defines the properties required to convert a quantity value from one unit to another such as from meters to feet\n * or from Celsius to Fahrenheit.\n * @beta\n */\nexport interface UnitConversionProps {\n  /** The factor to multiply the input value by to convert to the output value. */\n  factor: number;\n  /** The offset to add to the input value to convert to the output value. */\n  offset: number;\n  /** If set, inverts the unit value (1/x) before or after conversion. */\n  inversion?: UnitConversionInvert;\n}\n\n/** Interface that defines potential parse units that may be found in user's string input of a quantity value.\n * @beta\n */\nexport interface PotentialParseUnit {\n  unitName: string;\n  altLabels?: string[];\n}\n\n/**\n * This interface defines extra properties to be associated with Units from Units Schema by name\n * @alpha\n */\nexport interface UnitExtraData {\n  readonly name: string;\n  readonly altDisplayLabels: string[];\n}\n\n/** This interface is implemented by the class that is responsible for locating units by name or label and providing conversion values between units.\n * The methods to be implemented are async allowing the UnitsProvider to query the backend when necessary to look up unit definition and conversion rules.\n * @beta\n */\nexport interface UnitsProvider {\n  findUnit(unitLabel: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps>;\n  getUnitsByFamily(phenomenon: string): Promise<UnitProps[]>;\n  findUnitByName(unitName: string): Promise<UnitProps>;\n  getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversionProps>;\n}\n\n/**\n * Used to uniquely identify a unit system.\n * @beta\n */\nexport type UnitSystemKey = \"metric\" | \"imperial\" | \"usCustomary\" | \"usSurvey\";\n"]}
+{"version":3,"file":"Interfaces.js","sourceRoot":"","sources":["../../src/Interfaces.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAmDH;;GAEG;AACH,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B,mGAAmG;IACnG,mEAA2C,CAAA;IAC3C,gGAAgG;IAChG,qEAA6C,CAAA;AAC/C,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Quantity\n */\n\n/** This interface allows a provider to be specified that will define an array of alternate labels for a specific unit.\n * @beta\n */\nexport interface AlternateUnitLabelsProvider {\n  getAlternateUnitLabels: (unit: UnitProps) => string[] | undefined;\n}\n\n/** This interface provides basic information about a Unit that is return from a UnitProvider. This info\n * uniquely identifies a unit by its name.\n * @beta\n */\nexport interface UnitProps {\n  /** Unique name for unit. */\n  readonly name: string;\n  /** Default label for unit. */\n  readonly label: string;\n  /** Unique name of unit phenomenon. Example phenomenon names include 'Units.LENGTH', 'Units.AREA', and 'Units.VOLUME' */\n  readonly phenomenon: string;\n  /** This is set to true if the Unit is known by the UnitsProvider. */\n  readonly isValid: boolean;\n  /** Unique system name. Example \"Units.USCUSTOM\",\" Units.METRIC\", \"Units.USSURVEY\", \"Units.IMPERIAL\" */\n  readonly system: string;\n}\n\n/** This interface defines the required properties of a Quantity.\n * @beta\n */\nexport interface QuantityProps {\n  readonly magnitude: number;\n  readonly unit: UnitProps;\n  readonly isValid: boolean;\n}\n\n/** Interface that defines how to convert between a specific unit an another in synchronous formatting or parsing processing.\n * @beta\n */\nexport interface UnitConversionSpec {\n  /** Unit name that was used to locate the unit by the Unit Provider */\n  name: string;\n  /** The default label that is used to display unit */\n  label: string;\n  /** Unit system name, used to when finding preferred parse unit */\n  system: string;\n  /** the information necessary to convert the unit to a specific display unit */\n  conversion: UnitConversionProps;\n  /** Labels that may be used to represent the unit in a string that is to be parsed. */\n  parseLabels?: string[];\n}\n\n/** Indicates the way in which unit values are inverted during conversion\n * @beta\n */\nexport enum UnitConversionInvert {\n  /** Invert value before applying the other conversion steps (the from-unit is the inverted unit) */\n  InvertPreConversion = \"InvertPreConversion\",\n  /** Invert value after applying the other conversion steps (the to-unit is the inverted unit) */\n  InvertPostConversion = \"InvertPostConversion\"\n}\n\n/** This interface defines the properties required to convert a quantity value from one unit to another such as from meters to feet\n * or from Celsius to Fahrenheit.\n * @beta\n */\nexport interface UnitConversionProps {\n  /** The factor to multiply the input value by to convert to the output value. */\n  factor: number;\n  /** The offset to add to the input value to convert to the output value. */\n  offset: number;\n  /** If set, inverts the unit value (1/x) before or after conversion. */\n  inversion?: UnitConversionInvert;\n  /**\n   * If `true`, the conversion could not be resolved (e.g. unknown unit, incompatible phenomena).\n   * When `error` is `true`, `factor` MUST be `1.0` and `offset` MUST be `0.0` (identity).\n   * Callers must check this flag before applying the conversion — applying an identity conversion\n   * silently produces wrong output.\n   */\n  error?: boolean;\n}\n\n/** Interface that defines potential parse units that may be found in user's string input of a quantity value.\n * @beta\n */\nexport interface PotentialParseUnit {\n  unitName: string;\n  altLabels?: string[];\n}\n\n/**\n * This interface defines extra properties to be associated with Units from Units Schema by name\n * @alpha\n */\nexport interface UnitExtraData {\n  readonly name: string;\n  readonly altDisplayLabels: string[];\n}\n\n/** This interface is implemented by the class that is responsible for locating units by name or label and providing conversion values between units.\n * The methods to be implemented are async allowing the UnitsProvider to query the backend when necessary to look up unit definition and conversion rules.\n * @beta\n */\nexport interface UnitsProvider {\n  findUnit(unitLabel: string, schemaName?: string, phenomenon?: string, unitSystem?: string): Promise<UnitProps>;\n  getUnitsByFamily(phenomenon: string): Promise<UnitProps[]>;\n  findUnitByName(unitName: string): Promise<UnitProps>;\n  /**\n   * Compute the conversion factors from `fromUnit` to `toUnit`.\n   * On failure (unknown unit, incompatible phenomena), implementations MUST return\n   * `{ factor: 1.0, offset: 0.0, error: true }`. Throwing is also permitted;\n   * composite providers treat a throw as equivalent to `error: true`.\n   * Callers MUST check `result.error` before applying the conversion.\n   */\n  getConversion(fromUnit: UnitProps, toUnit: UnitProps): Promise<UnitConversionProps>;\n}\n\n/**\n * Identifies a user-facing unit system preference group.\n *\n * A `UnitSystemKey` does **not** map one-to-one to an EC `UnitSystem` element. Instead, each key\n * represents a *preference group* that matches against one or more EC `UnitSystem` names in\n * priority order when resolving formats from a `KindOfQuantity`:\n *\n * | Key            | EC UnitSystems matched (highest priority first)         |\n * | -------------- | ------------------------------------------------------- |\n * | `\"metric\"`     | SI / METRIC, INTERNATIONAL, FINANCE                     |\n * | `\"imperial\"`   | IMPERIAL, USCUSTOM, INTERNATIONAL, FINANCE               |\n * | `\"usCustomary\"`| USCUSTOM, INTERNATIONAL, FINANCE                         |\n * | `\"usSurvey\"`   | USSURVEY, USCUSTOM, INTERNATIONAL, FINANCE               |\n *\n * EC `UnitSystem` elements not listed above (e.g. CGS, MARITIME, INDUSTRIAL) are not covered by\n * any preference group and will only appear if a `KindOfQuantity` explicitly references them.\n *\n * @see [SchemaFormatsProvider]($ecschema-metadata) for how preference groups resolve formats.\n * @beta\n */\nexport type UnitSystemKey = \"metric\" | \"imperial\" | \"usCustomary\" | \"usSurvey\";\n"]}

package/lib/esm/Parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Parser.d.ts","sourceRoot":"","sources":["../../src/Parser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Parser.d.ts","sourceRoot":"","sources":["../../src/Parser.ts"],"names":[],"mappings":"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"}

package/lib/esm/Parser.js

@@ -5,9 +5,11 @@
 /** @packageDocumentation
  * @module Quantity
  */
+import { Logger } from "@itwin/core-bentley";
 import { QuantityConstants } from "./Constants";
 import { QuantityError, QuantityStatus } from "./Exception";
 import { FormatTraits, FormatType } from "./Formatter/FormatEnums";
+import { QuantityLoggerCategory } from "./QuantityLoggerCategory";
 import { applyConversion, Quantity } from "./Quantity";
 /** Possible parser errors
  * @beta
@@ -388,6 +390,9 @@ export class Parser {
             else {
                 // Add new conversion to the list.
                 const conversion = await unitsProvider.getConversion(unitProps, outUnit);
+                if (conversion.error) {
+                    Logger.logWarning(QuantityLoggerCategory.Parsing, `Unit conversion from "${unitProps.name}" to "${outUnit.name}" could not be resolved.`);
+                }
                 if (conversion) {
                     spec = {
                         conversion,
@@ -408,7 +413,11 @@ export class Parser {
     static async createQuantityFromParseTokens(tokens, format, unitsProvider, altUnitLabelsProvider) {
         const unitConversionInfos = await this.getRequiredUnitsConversionsToParseTokens(tokens, format, unitsProvider, altUnitLabelsProvider);
         if (unitConversionInfos.outUnit) {
-            const value = Parser.getQuantityValueFromParseTokens(tokens, format, unitConversionInfos.specs, await unitsProvider.getConversion(unitConversionInfos.outUnit, unitConversionInfos.outUnit));
+            const outUnitConversion = await unitsProvider.getConversion(unitConversionInfos.outUnit, unitConversionInfos.outUnit);
+            if (outUnitConversion.error) {
+                Logger.logWarning(QuantityLoggerCategory.Parsing, `Unit conversion from "${unitConversionInfos.outUnit.name}" to "${unitConversionInfos.outUnit.name}" could not be resolved.`);
+            }
+            const value = Parser.getQuantityValueFromParseTokens(tokens, format, unitConversionInfos.specs, outUnitConversion);
             if (value.ok) {
                 return new Quantity(unitConversionInfos.outUnit, value.value);
             }
@@ -943,6 +952,9 @@ export class Parser {
         const familyUnits = await unitsProvider.getUnitsByFamily(outUnit.phenomenon);
         for (const unit of familyUnits) {
             const conversion = await unitsProvider.getConversion(unit, outUnit);
+            if (conversion.error) {
+                Logger.logWarning(QuantityLoggerCategory.Parsing, `Unit conversion from "${unit.name}" to "${outUnit.name}" could not be resolved.`);
+            }
             const parseLabels = [unit.label.toLocaleLowerCase()];
             const alternateLabels = altUnitLabelsProvider?.getAlternateUnitLabels(unit);
             // add any alternate labels that may be defined for the Unit
@@ -980,6 +992,9 @@ export class Parser {
                 continue;
             }
             const conversion = await unitsProvider.getConversion(unit, outUnit);
+            if (conversion.error) {
+                Logger.logWarning(QuantityLoggerCategory.Parsing, `Unit conversion from "${unit.name}" to "${outUnit.name}" could not be resolved.`);
+            }
             const parseLabels = [unit.label.toLocaleLowerCase()];
             const alternateLabels = altUnitLabelsProvider?.getAlternateUnitLabels(unit);
             // add any alternate labels that may be defined for the Unit