@itwin/core-quantity 5.9.0-dev.8 → 5.10.0-dev.1

package/lib/cjs/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/cjs/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/cjs/Formatter/FormattingReadyCollector.js

@@ -0,0 +1,44 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @module Quantity */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormattingReadyCollector = void 0;
+const core_bentley_1 = require("@itwin/core-bentley");
+const QuantityLoggerCategory_1 = require("../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
+ */
+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") {
+                    core_bentley_1.Logger.logWarning(QuantityLoggerCategory_1.QuantityLoggerCategory.Formatting, "FormattingReadyCollector: a provider's async work rejected", () => ({ reason: result.reason }));
+                }
+            }
+            return "done";
+        });
+        const outcome = await Promise.race([work, timeout]);
+        if (outcome === "timeout") {
+            core_bentley_1.Logger.logWarning(QuantityLoggerCategory_1.QuantityLoggerCategory.Formatting, `FormattingReadyCollector: timed out after ${timeoutMs}ms waiting for ${this._promises.length} provider(s). Proceeding with ready signal.`);
+        }
+    }
+}
+exports.FormattingReadyCollector = FormattingReadyCollector;
+//# sourceMappingURL=FormattingReadyCollector.js.map

package/lib/cjs/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,sDAA6C;AAC7C,sEAAmE;AAEnE;;;;GAIG;AACH,MAAa,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,qBAAM,CAAC,UAAU,CAAC,+CAAsB,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,qBAAM,CAAC,UAAU,CAAC,+CAAsB,CAAC,UAAU,EAAE,6CAA6C,SAAS,kBAAkB,IAAI,CAAC,SAAS,CAAC,MAAM,6CAA6C,CAAC,CAAC;QACnM,CAAC;IACH,CAAC;CACF;AA9BD,4DA8BC","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @module Quantity */\r\n\r\nimport { Logger } from \"@itwin/core-bentley\";\r\nimport { QuantityLoggerCategory } from \"../QuantityLoggerCategory\";\r\n\r\n/** Collects async work from formatting providers during the pre-ready phase.\r\n * Providers call [[addPendingWork]] to register promises that the formatter\r\n * will await before signaling [[QuantityFormatter.onFormattingReady]].\r\n * @beta\r\n */\r\nexport class FormattingReadyCollector {\r\n  private _promises: Promise<void>[] = [];\r\n\r\n  /** Register async work that must complete before the formatter signals ready.\r\n   * Call this from an `onBeforeFormattingReady` listener.\r\n   */\r\n  public addPendingWork(work: Promise<void>): void {\r\n    this._promises.push(work);\r\n  }\r\n\r\n  /** @internal Await all registered work with a timeout. Logs warnings for rejections and timeouts. */\r\n  public async awaitAll(timeoutMs: number = 20_000): Promise<void> {\r\n    if (this._promises.length === 0)\r\n      return;\r\n\r\n    const timeout = new Promise<\"timeout\">((resolve) => setTimeout(() => resolve(\"timeout\"), timeoutMs));\r\n    const work = Promise.allSettled(this._promises).then((results) => {\r\n      for (const result of results) {\r\n        if (result.status === \"rejected\") {\r\n          Logger.logWarning(QuantityLoggerCategory.Formatting, \"FormattingReadyCollector: a provider's async work rejected\", () => ({ reason: result.reason }));\r\n        }\r\n      }\r\n      return \"done\" as const;\r\n    });\r\n\r\n    const outcome = await Promise.race([work, timeout]);\r\n    if (outcome === \"timeout\") {\r\n      Logger.logWarning(QuantityLoggerCategory.Formatting, `FormattingReadyCollector: timed out after ${timeoutMs}ms waiting for ${this._promises.length} provider(s). Proceeding with ready signal.`);\r\n    }\r\n  }\r\n}\r\n"]}

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

package/lib/cjs/Interfaces.d.ts

@@ -93,7 +93,23 @@ export interface UnitsProvider {
     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/cjs/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;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;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC"}

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

package/lib/cjs/QuantityLoggerCategory.d.ts

@@ -0,0 +1,14 @@
+/** @packageDocumentation
+ * @module Logging
+ */
+/** Logger categories used by the `@itwin/core-quantity` package.
+ * @see [Logger]($bentley)
+ * @beta
+ */
+export declare enum QuantityLoggerCategory {
+    /** The root category for the core-quantity package. */
+    Package = "core-quantity",
+    /** Logger category for quantity formatting operations. */
+    Formatting = "core-quantity.Formatting"
+}
+//# sourceMappingURL=QuantityLoggerCategory.d.ts.map

package/lib/cjs/QuantityLoggerCategory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuantityLoggerCategory.d.ts","sourceRoot":"","sources":["../../src/QuantityLoggerCategory.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;;GAGG;AACH,oBAAY,sBAAsB;IAChC,uDAAuD;IACvD,OAAO,kBAAkB;IACzB,0DAA0D;IAC1D,UAAU,6BAA6B;CACxC"}

package/lib/cjs/QuantityLoggerCategory.js

@@ -0,0 +1,22 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Logging
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuantityLoggerCategory = void 0;
+/** Logger categories used by the `@itwin/core-quantity` package.
+ * @see [Logger]($bentley)
+ * @beta
+ */
+var QuantityLoggerCategory;
+(function (QuantityLoggerCategory) {
+    /** The root category for the core-quantity package. */
+    QuantityLoggerCategory["Package"] = "core-quantity";
+    /** Logger category for quantity formatting operations. */
+    QuantityLoggerCategory["Formatting"] = "core-quantity.Formatting";
+})(QuantityLoggerCategory || (exports.QuantityLoggerCategory = QuantityLoggerCategory = {}));
+//# sourceMappingURL=QuantityLoggerCategory.js.map

package/lib/cjs/QuantityLoggerCategory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuantityLoggerCategory.js","sourceRoot":"","sources":["../../src/QuantityLoggerCategory.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAEH;;;GAGG;AACH,IAAY,sBAKX;AALD,WAAY,sBAAsB;IAChC,uDAAuD;IACvD,mDAAyB,CAAA;IACzB,0DAA0D;IAC1D,iEAAuC,CAAA;AACzC,CAAC,EALW,sBAAsB,sCAAtB,sBAAsB,QAKjC","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Logging\r\n */\r\n\r\n/** Logger categories used by the `@itwin/core-quantity` package.\r\n * @see [Logger]($bentley)\r\n * @beta\r\n */\r\nexport enum QuantityLoggerCategory {\r\n  /** The root category for the core-quantity package. */\r\n  Package = \"core-quantity\",\r\n  /** Logger category for quantity formatting operations. */\r\n  Formatting = \"core-quantity.Formatting\",\r\n}\r\n"]}

package/lib/cjs/core-quantity.d.ts

@@ -1,5 +1,6 @@
 export * from "./Constants";
 export * from "./Exception";
+export * from "./FormatSpecHandle";
 export * from "./Interfaces";
 export * from "./Parser";
 export * from "./ParserSpec";
@@ -9,7 +10,9 @@ export * from "./Formatter/Format";
 export * from "./Formatter/FormatterSpec";
 export * from "./Formatter/FormatEnums";
 export * from "./Formatter/Formatter";
+export * from "./Formatter/FormattingReadyCollector";
 export * from "./Formatter/Interfaces";
+export * from "./QuantityLoggerCategory";
 /** @docs-package-description
  * The core-quantity package always runs in a web browser. It contains classes, interfaces, and definitions for formatting and parsing quantity values.
  */
@@ -17,4 +20,8 @@ export * from "./Formatter/Interfaces";
  * @docs-group-description Quantity
  * Classes, Interfaces, and definitions used to format and parse quantity values.
  */
+/**
+ * @docs-group-description Logging
+ * Logger categories used by this package.
+ */
 //# sourceMappingURL=core-quantity.d.ts.map

package/lib/cjs/core-quantity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-quantity.d.ts","sourceRoot":"","sources":["../../src/core-quantity.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AAEvB,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AAEvC;;GAEG;AAEH;;;GAGG"}
+{"version":3,"file":"core-quantity.d.ts","sourceRoot":"","sources":["../../src/core-quantity.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sCAAsC,CAAC;AACrD,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AAEzC;;GAEG;AAEH;;;GAGG;AACH;;;GAGG"}

package/lib/cjs/core-quantity.js

@@ -20,6 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 *--------------------------------------------------------------------------------------------*/
 __exportStar(require("./Constants"), exports);
 __exportStar(require("./Exception"), exports);
+__exportStar(require("./FormatSpecHandle"), exports);
 __exportStar(require("./Interfaces"), exports);
 __exportStar(require("./Parser"), exports);
 __exportStar(require("./ParserSpec"), exports);
@@ -29,7 +30,9 @@ __exportStar(require("./Formatter/Format"), exports);
 __exportStar(require("./Formatter/FormatterSpec"), exports);
 __exportStar(require("./Formatter/FormatEnums"), exports);
 __exportStar(require("./Formatter/Formatter"), exports);
+__exportStar(require("./Formatter/FormattingReadyCollector"), exports);
 __exportStar(require("./Formatter/Interfaces"), exports);
+__exportStar(require("./QuantityLoggerCategory"), exports);
 /** @docs-package-description
  * The core-quantity package always runs in a web browser. It contains classes, interfaces, and definitions for formatting and parsing quantity values.
  */
@@ -37,4 +40,8 @@ __exportStar(require("./Formatter/Interfaces"), exports);
  * @docs-group-description Quantity
  * Classes, Interfaces, and definitions used to format and parse quantity values.
  */
+/**
+ * @docs-group-description Logging
+ * Logger categories used by this package.
+ */
 //# sourceMappingURL=core-quantity.js.map

package/lib/cjs/core-quantity.js.map

@@ -1 +1 @@
-{"version":3,"file":"core-quantity.js","sourceRoot":"","sources":["../../src/core-quantity.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;+FAG+F;AAC/F,8CAA4B;AAC5B,8CAA4B;AAC5B,+CAA6B;AAC7B,2CAAyB;AACzB,+CAA6B;AAC7B,6CAA2B;AAC3B,yCAAuB;AAEvB,qDAAmC;AACnC,4DAA0C;AAC1C,0DAAwC;AACxC,wDAAsC;AACtC,yDAAuC;AAEvC;;GAEG;AAEH;;;GAGG","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\nexport * from \"./Constants\";\r\nexport * from \"./Exception\";\r\nexport * from \"./Interfaces\";\r\nexport * from \"./Parser\";\r\nexport * from \"./ParserSpec\";\r\nexport * from \"./Quantity\";\r\nexport * from \"./Unit\";\r\n\r\nexport * from \"./Formatter/Format\";\r\nexport * from \"./Formatter/FormatterSpec\";\r\nexport * from \"./Formatter/FormatEnums\";\r\nexport * from \"./Formatter/Formatter\";\r\nexport * from \"./Formatter/Interfaces\";\r\n\r\n/** @docs-package-description\r\n * The core-quantity package always runs in a web browser. It contains classes, interfaces, and definitions for formatting and parsing quantity values.\r\n */\r\n\r\n/**\r\n * @docs-group-description Quantity\r\n * Classes, Interfaces, and definitions used to format and parse quantity values.\r\n */\r\n"]}
+{"version":3,"file":"core-quantity.js","sourceRoot":"","sources":["../../src/core-quantity.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;+FAG+F;AAC/F,8CAA4B;AAC5B,8CAA4B;AAC5B,qDAAmC;AACnC,+CAA6B;AAC7B,2CAAyB;AACzB,+CAA6B;AAC7B,6CAA2B;AAC3B,yCAAuB;AACvB,qDAAmC;AACnC,4DAA0C;AAC1C,0DAAwC;AACxC,wDAAsC;AACtC,uEAAqD;AACrD,yDAAuC;AACvC,2DAAyC;AAEzC;;GAEG;AAEH;;;GAGG;AACH;;;GAGG","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\nexport * from \"./Constants\";\r\nexport * from \"./Exception\";\r\nexport * from \"./FormatSpecHandle\";\r\nexport * from \"./Interfaces\";\r\nexport * from \"./Parser\";\r\nexport * from \"./ParserSpec\";\r\nexport * from \"./Quantity\";\r\nexport * from \"./Unit\";\r\nexport * from \"./Formatter/Format\";\r\nexport * from \"./Formatter/FormatterSpec\";\r\nexport * from \"./Formatter/FormatEnums\";\r\nexport * from \"./Formatter/Formatter\";\r\nexport * from \"./Formatter/FormattingReadyCollector\";\r\nexport * from \"./Formatter/Interfaces\";\r\nexport * from \"./QuantityLoggerCategory\";\r\n\r\n/** @docs-package-description\r\n * The core-quantity package always runs in a web browser. It contains classes, interfaces, and definitions for formatting and parsing quantity values.\r\n */\r\n\r\n/**\r\n * @docs-group-description Quantity\r\n * Classes, Interfaces, and definitions used to format and parse quantity values.\r\n */\r\n/**\r\n * @docs-group-description Logging\r\n * Logger categories used by this package.\r\n */\r\n"]}

package/lib/esm/FormatSpecHandle.d.ts

@@ -0,0 +1,56 @@
+/** @packageDocumentation
+ * @module Quantity
+ */
+import type { FormatterSpec } from "./Formatter/FormatterSpec";
+import type { FormattingSpecArgs, FormattingSpecProvider } from "./Formatter/Interfaces";
+import type { ParserSpec } from "./ParserSpec";
+import type { UnitSystemKey } from "./Interfaces";
+/** Arguments for constructing a [[FormatSpecHandle]].
+ * @internal
+ */
+export interface FormatSpecHandleArgs extends FormattingSpecArgs {
+    /** The provider that supplies spec lookups and reload events. */
+    provider: FormattingSpecProvider;
+}
+/** A cacheable handle to formatting and parsing specs for a specific KoQ and persistence unit.
+ * Automatically refreshes when the QuantityFormatter reloads. Use [[QuantityFormatter.getFormatSpecHandle]]
+ * to create instances.
+ *
+ * When formatting is not yet ready, [[format]] returns a `value.toString()` fallback.
+ * Call [[dispose]] when the handle is no longer needed to unsubscribe from reload events.
+ *
+ * @beta
+ */
+export declare class FormatSpecHandle implements Disposable {
+    private _formatterSpec;
+    private _parserSpec;
+    private _removeListener;
+    private readonly _provider;
+    private readonly _koqName;
+    private readonly _persistenceUnit;
+    private readonly _system;
+    /** @internal */
+    constructor(args: FormatSpecHandleArgs);
+    /** The KoQ name this handle is keyed to. */
+    get koqName(): string;
+    /** The persistence unit this handle is keyed to. */
+    get persistenceUnit(): string;
+    /** The unit system this handle is pinned to, or `undefined` for the active system. */
+    get system(): UnitSystemKey | undefined;
+    /** The current FormatterSpec, or undefined if not yet loaded. */
+    get formatterSpec(): FormatterSpec | undefined;
+    /** The current ParserSpec, or undefined if not yet loaded. */
+    get parserSpec(): ParserSpec | undefined;
+    /** Format a quantity value using the current spec.
+     * If the formatter is not yet ready, returns `value.toString()` as a fallback.
+     * @param value - The numeric value to format.
+     * @returns The formatted string.
+     */
+    format(value: number): string;
+    /** Unsubscribe from reload events and clear cached specs.
+     * Idempotent and safe to call during a pending reload.
+     */
+    [Symbol.dispose](): void;
+    private _refresh;
+}
+//# sourceMappingURL=FormatSpecHandle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FormatSpecHandle.d.ts","sourceRoot":"","sources":["../../src/FormatSpecHandle.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAuB,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAC9G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,iEAAiE;IACjE,QAAQ,EAAE,sBAAsB,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,eAAe,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD,gBAAgB;gBACJ,IAAI,EAAE,oBAAoB;IAWtC,4CAA4C;IAC5C,IAAW,OAAO,IAAI,MAAM,CAA0B;IAEtD,oDAAoD;IACpD,IAAW,eAAe,IAAI,MAAM,CAAkC;IAEtE,sFAAsF;IACtF,IAAW,MAAM,IAAI,aAAa,GAAG,SAAS,CAAyB;IAEvE,iEAAiE;IACjE,IAAW,aAAa,IAAI,aAAa,GAAG,SAAS,CAAgC;IAErF,8DAA8D;IAC9D,IAAW,UAAU,IAAI,UAAU,GAAG,SAAS,CAA6B;IAE5E;;;;OAIG;IACI,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAMpC;;OAEG;IACI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAS/B,OAAO,CAAC,QAAQ;CAiBjB"}

package/lib/esm/FormatSpecHandle.js

@@ -0,0 +1,83 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** A cacheable handle to formatting and parsing specs for a specific KoQ and persistence unit.
+ * Automatically refreshes when the QuantityFormatter reloads. Use [[QuantityFormatter.getFormatSpecHandle]]
+ * to create instances.
+ *
+ * When formatting is not yet ready, [[format]] returns a `value.toString()` fallback.
+ * Call [[dispose]] when the handle is no longer needed to unsubscribe from reload events.
+ *
+ * @beta
+ */
+export class FormatSpecHandle {
+    _formatterSpec;
+    _parserSpec;
+    _removeListener;
+    _provider;
+    _koqName;
+    _persistenceUnit;
+    _system;
+    /** @internal */
+    constructor(args) {
+        this._provider = args.provider;
+        this._koqName = args.name;
+        this._persistenceUnit = args.persistenceUnitName;
+        this._system = args.system;
+        this._removeListener = args.provider.onFormattingReady.addListener(() => {
+            this._refresh();
+        });
+        this._refresh();
+    }
+    /** The KoQ name this handle is keyed to. */
+    get koqName() { return this._koqName; }
+    /** The persistence unit this handle is keyed to. */
+    get persistenceUnit() { return this._persistenceUnit; }
+    /** The unit system this handle is pinned to, or `undefined` for the active system. */
+    get system() { return this._system; }
+    /** The current FormatterSpec, or undefined if not yet loaded. */
+    get formatterSpec() { return this._formatterSpec; }
+    /** The current ParserSpec, or undefined if not yet loaded. */
+    get parserSpec() { return this._parserSpec; }
+    /** Format a quantity value using the current spec.
+     * If the formatter is not yet ready, returns `value.toString()` as a fallback.
+     * @param value - The numeric value to format.
+     * @returns The formatted string.
+     */
+    format(value) {
+        if (!this._formatterSpec)
+            return value.toString();
+        return this._provider.formatQuantity(value, this._formatterSpec);
+    }
+    /** Unsubscribe from reload events and clear cached specs.
+     * Idempotent and safe to call during a pending reload.
+     */
+    [Symbol.dispose]() {
+        if (this._removeListener) {
+            this._removeListener();
+            this._removeListener = undefined;
+        }
+        this._formatterSpec = undefined;
+        this._parserSpec = undefined;
+    }
+    _refresh() {
+        // Guard against mid-emission callbacks after dispose() — event may still fire during iteration.
+        if (!this._removeListener)
+            return;
+        const entry = this._provider.getSpecsByNameAndUnit({
+            name: this._koqName,
+            persistenceUnitName: this._persistenceUnit,
+            system: this._system,
+        });
+        if (entry) {
+            this._formatterSpec = entry.formatterSpec;
+            this._parserSpec = entry.parserSpec;
+        }
+        else {
+            this._formatterSpec = undefined;
+            this._parserSpec = undefined;
+        }
+    }
+}
+//# sourceMappingURL=FormatSpecHandle.js.map

package/lib/esm/FormatSpecHandle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormatSpecHandle.js","sourceRoot":"","sources":["../../src/FormatSpecHandle.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAmB/F;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IACnB,cAAc,CAA4B;IAC1C,WAAW,CAAyB;IACpC,eAAe,CAA2B;IACjC,SAAS,CAAyB;IAClC,QAAQ,CAAS;IACjB,gBAAgB,CAAS;IACzB,OAAO,CAA4B;IAEpD,gBAAgB;IAChB,YAAY,IAA0B;QACpC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;QAC1B,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,GAAG,EAAE;YACtE,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAED,4CAA4C;IAC5C,IAAW,OAAO,KAAa,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEtD,oDAAoD;IACpD,IAAW,eAAe,KAAa,OAAO,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAEtE,sFAAsF;IACtF,IAAW,MAAM,KAAgC,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAEvE,iEAAiE;IACjE,IAAW,aAAa,KAAgC,OAAO,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;IAErF,8DAA8D;IAC9D,IAAW,UAAU,KAA6B,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IAE5E;;;;OAIG;IACI,MAAM,CAAC,KAAa;QACzB,IAAI,CAAC,IAAI,CAAC,cAAc;YACtB,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IACnE,CAAC;IAED;;OAEG;IACI,CAAC,MAAM,CAAC,OAAO,CAAC;QACrB,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,IAAI,CAAC,eAAe,EAAE,CAAC;YACvB,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;QAChC,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;IAC/B,CAAC;IAEO,QAAQ;QACd,gGAAgG;QAChG,IAAI,CAAC,IAAI,CAAC,eAAe;YACvB,OAAO;QACT,MAAM,KAAK,GAAoC,IAAI,CAAC,SAAS,CAAC,qBAAqB,CAAC;YAClF,IAAI,EAAE,IAAI,CAAC,QAAQ;YACnB,mBAAmB,EAAE,IAAI,CAAC,gBAAgB;YAC1C,MAAM,EAAE,IAAI,CAAC,OAAO;SACrB,CAAC,CAAC;QACH,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC,aAAa,CAAC;YAC1C,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,UAAU,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;YAChC,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC/B,CAAC;IACH,CAAC;CACF","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n\r\n/** @packageDocumentation\r\n * @module Quantity\r\n */\r\n\r\nimport type { FormatterSpec } from \"./Formatter/FormatterSpec\";\r\nimport type { FormattingSpecArgs, FormattingSpecEntry, FormattingSpecProvider } from \"./Formatter/Interfaces\";\r\nimport type { ParserSpec } from \"./ParserSpec\";\r\nimport type { UnitSystemKey } from \"./Interfaces\";\r\n\r\n/** Arguments for constructing a [[FormatSpecHandle]].\r\n * @internal\r\n */\r\nexport interface FormatSpecHandleArgs extends FormattingSpecArgs {\r\n  /** The provider that supplies spec lookups and reload events. */\r\n  provider: FormattingSpecProvider;\r\n}\r\n\r\n/** A cacheable handle to formatting and parsing specs for a specific KoQ and persistence unit.\r\n * Automatically refreshes when the QuantityFormatter reloads. Use [[QuantityFormatter.getFormatSpecHandle]]\r\n * to create instances.\r\n *\r\n * When formatting is not yet ready, [[format]] returns a `value.toString()` fallback.\r\n * Call [[dispose]] when the handle is no longer needed to unsubscribe from reload events.\r\n *\r\n * @beta\r\n */\r\nexport class FormatSpecHandle implements Disposable {\r\n  private _formatterSpec: FormatterSpec | undefined;\r\n  private _parserSpec: ParserSpec | undefined;\r\n  private _removeListener: (() => void) | undefined;\r\n  private readonly _provider: FormattingSpecProvider;\r\n  private readonly _koqName: string;\r\n  private readonly _persistenceUnit: string;\r\n  private readonly _system: UnitSystemKey | undefined;\r\n\r\n  /** @internal */\r\n  constructor(args: FormatSpecHandleArgs) {\r\n    this._provider = args.provider;\r\n    this._koqName = args.name;\r\n    this._persistenceUnit = args.persistenceUnitName;\r\n    this._system = args.system;\r\n    this._removeListener = args.provider.onFormattingReady.addListener(() => {\r\n      this._refresh();\r\n    });\r\n    this._refresh();\r\n  }\r\n\r\n  /** The KoQ name this handle is keyed to. */\r\n  public get koqName(): string { return this._koqName; }\r\n\r\n  /** The persistence unit this handle is keyed to. */\r\n  public get persistenceUnit(): string { return this._persistenceUnit; }\r\n\r\n  /** The unit system this handle is pinned to, or `undefined` for the active system. */\r\n  public get system(): UnitSystemKey | undefined { return this._system; }\r\n\r\n  /** The current FormatterSpec, or undefined if not yet loaded. */\r\n  public get formatterSpec(): FormatterSpec | undefined { return this._formatterSpec; }\r\n\r\n  /** The current ParserSpec, or undefined if not yet loaded. */\r\n  public get parserSpec(): ParserSpec | undefined { return this._parserSpec; }\r\n\r\n  /** Format a quantity value using the current spec.\r\n   * If the formatter is not yet ready, returns `value.toString()` as a fallback.\r\n   * @param value - The numeric value to format.\r\n   * @returns The formatted string.\r\n   */\r\n  public format(value: number): string {\r\n    if (!this._formatterSpec)\r\n      return value.toString();\r\n    return this._provider.formatQuantity(value, this._formatterSpec);\r\n  }\r\n\r\n  /** Unsubscribe from reload events and clear cached specs.\r\n   * Idempotent and safe to call during a pending reload.\r\n   */\r\n  public [Symbol.dispose](): void {\r\n    if (this._removeListener) {\r\n      this._removeListener();\r\n      this._removeListener = undefined;\r\n    }\r\n    this._formatterSpec = undefined;\r\n    this._parserSpec = undefined;\r\n  }\r\n\r\n  private _refresh(): void {\r\n    // Guard against mid-emission callbacks after dispose() — event may still fire during iteration.\r\n    if (!this._removeListener)\r\n      return;\r\n    const entry: FormattingSpecEntry | undefined = this._provider.getSpecsByNameAndUnit({\r\n      name: this._koqName,\r\n      persistenceUnitName: this._persistenceUnit,\r\n      system: this._system,\r\n    });\r\n    if (entry) {\r\n      this._formatterSpec = entry.formatterSpec;\r\n      this._parserSpec = entry.parserSpec;\r\n    } else {\r\n      this._formatterSpec = undefined;\r\n      this._parserSpec = undefined;\r\n    }\r\n  }\r\n}\r\n"]}