Add FormatSetFormatsProvider to ecschema-metadata (#8438)

Author: hl662

common/api/core-quantity.api.md

@@ -306,7 +306,6 @@ export interface FormatsChangedArgs {
 export interface FormatsProvider {
     // (undocumented)
     getFormat(name: string): Promise<FormatDefinition | undefined>;
-    // (undocumented)
     onFormatsChanged: BeEvent<(args: FormatsChangedArgs) => void>;
 }
 
@@ -415,9 +414,7 @@ export const isCustomFormatProps: (item: FormatProps) => item is CustomFormatPro
 
 // @beta
 export interface MutableFormatsProvider extends FormatsProvider {
-    // (undocumented)
     addFormat(name: string, format: FormatDefinition): Promise<void>;
-    // (undocumented)
     removeFormat(name: string): Promise<void>;
 }
 

common/api/ecschema-metadata.api.md

@@ -14,6 +14,7 @@ import { FormatsProvider } from '@itwin/core-quantity';
 import { FormatTraits } from '@itwin/core-quantity';
 import { FormatType } from '@itwin/core-quantity';
 import { FractionalPrecision } from '@itwin/core-quantity';
+import { MutableFormatsProvider } from '@itwin/core-quantity';
 import { ScientificType } from '@itwin/core-quantity';
 import { ShowSignOption } from '@itwin/core-quantity';
 import { UnitConversionProps } from '@itwin/core-quantity';
@@ -808,6 +809,20 @@ export interface FormatSet {
     name: string;
 }
 
+// @beta
+export class FormatSetFormatsProvider implements MutableFormatsProvider {
+    constructor(props: {
+        formatSet: FormatSet;
+        fallbackProvider?: FormatsProvider;
+    });
+    addFormat(name: string, format: FormatDefinition): Promise<void>;
+    clearFallbackProvider(): void;
+    getFormat(input: string): Promise<FormatDefinition | undefined>;
+    // (undocumented)
+    onFormatsChanged: BeEvent<(args: FormatsChangedArgs) => void>;
+    removeFormat(name: string): Promise<void>;
+}
+
 // @internal (undocumented)
 export function getFormatProps(format: Format | OverrideFormat): FormatProps;
 

common/api/summary/ecschema-metadata.exports.csv

@@ -89,6 +89,7 @@ preview;interface;EnumeratorProps
 public;class;Format
 preview;class;Format
 beta;interface;FormatSet
+beta;class;FormatSetFormatsProvider
 internal;function;getFormatProps
 public;interface;HasMixins
 preview;interface;HasMixins

common/changes/@itwin/core-quantity/nam-format-set-provider_2025-08-19-16-29.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-quantity",
+      "comment": "Add documentation to public methods",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-quantity"
+}

common/changes/@itwin/ecschema-metadata/nam-format-set-provider_2025-08-18-20-19.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/ecschema-metadata",
+      "comment": "Add FormatSetFormatsProvider",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/ecschema-metadata"
+}

core/ecschema-metadata/src/Formatting/FormatSetFormatsProvider.ts

@@ -0,0 +1,61 @@
+import { BeEvent } from "@itwin/core-bentley";
+import { FormatDefinition, FormatsChangedArgs, FormatsProvider, MutableFormatsProvider } from "@itwin/core-quantity";
+import { FormatSet } from "../Deserialization/JsonProps";
+import { SchemaItem } from "../Metadata/SchemaItem";
+
+/**
+ * A mutable format provider that manages format definitions within a format set.
+ * When formats are added or removed, the underlying format set is automatically updated.
+ * @beta
+ */
+export class FormatSetFormatsProvider implements MutableFormatsProvider {
+  public onFormatsChanged: BeEvent<(args: FormatsChangedArgs) => void> = new BeEvent<(args: FormatsChangedArgs) => void>();
+
+  private _formatSet: FormatSet;
+  private _fallbackProvider?: FormatsProvider;
+
+  public constructor(props: {formatSet: FormatSet, fallbackProvider?: FormatsProvider}) {
+    this._formatSet = props.formatSet;
+    this._fallbackProvider = props.fallbackProvider;
+  }
+
+  /**
+   * Adds a format definition to the format set or updates an existing one.
+   * @param name The name of the format to add or update
+   * @param format The format definition to add or update
+   */
+  public async addFormat(name: string, format: FormatDefinition): Promise<void> {
+    this._formatSet.formats[name] = format;
+    this.onFormatsChanged.raiseEvent({ formatsChanged: [name] });
+  }
+
+  /**
+   * Clears the fallback provider, if one is set.
+   */
+  public clearFallbackProvider(): void {
+    this._fallbackProvider = undefined;
+  }
+
+  /**
+   * Retrieves a format definition by its name from the format set. If not found, it checks the fallback provider to find the format, else returns undefined.
+   */
+  public async getFormat(input: string): Promise<FormatDefinition | undefined> {
+    // Normalizes any schemaItem names coming from node addon 'schemaName:schemaItemName' -> 'schemaName.schemaItemName'
+    const [schemaName, itemName] = SchemaItem.parseFullName(input);
+
+    const name = (schemaName === "") ? itemName : `${schemaName}.${itemName}`;
+    const format = this._formatSet.formats[name];
+    if (format) return format;
+    if (this._fallbackProvider) return this._fallbackProvider.getFormat(name);
+    return undefined;
+  }
+
+  /**
+   * Removes a format definition from the format set.
+   * @param name The name of the format to remove
+   */
+  public async removeFormat(name: string): Promise<void> {
+    delete this._formatSet.formats[name];
+    this.onFormatsChanged.raiseEvent({ formatsChanged: [name] });
+  }
+}

core/ecschema-metadata/src/SchemaFormatsProvider.ts renamed to core/ecschema-metadata/src/Formatting/SchemaFormatsProvider.ts

@@ -6,19 +6,19 @@
  * @module Metadata
  */
 
-import { ISchemaLocater, SchemaContext } from "./Context";
-import { SchemaItemKey, SchemaKey } from "./SchemaKey";
-import { SchemaItem } from "./Metadata/SchemaItem";
-import { Format } from "./Metadata/Format";
-import { SchemaItemFormatProps } from "./Deserialization/JsonProps";
+import { ISchemaLocater, SchemaContext } from "../Context";
+import { SchemaItemKey, SchemaKey } from "../SchemaKey";
+import { SchemaItem } from "../Metadata/SchemaItem";
+import { Format } from "../Metadata/Format";
+import { SchemaItemFormatProps } from "../Deserialization/JsonProps";
 import { BeEvent, Logger } from "@itwin/core-bentley";
-import { KindOfQuantity } from "./Metadata/KindOfQuantity";
-import { getFormatProps } from "./Metadata/OverrideFormat";
+import { KindOfQuantity } from "../Metadata/KindOfQuantity";
+import { getFormatProps } from "../Metadata/OverrideFormat";
 import { FormatDefinition, FormatProps, FormatsChangedArgs, FormatsProvider, UnitSystemKey } from "@itwin/core-quantity";
-import { Unit } from "./Metadata/Unit";
-import { InvertedUnit } from "./Metadata/InvertedUnit";
-import { Schema } from "./Metadata/Schema";
-import { UnitSystem } from "./Metadata/UnitSystem";
+import { Unit } from "../Metadata/Unit";
+import { InvertedUnit } from "../Metadata/InvertedUnit";
+import { Schema } from "../Metadata/Schema";
+import { UnitSystem } from "../Metadata/UnitSystem";
 const loggerCategory = "SchemaFormatsProvider";
 /**
  * Provides default formats and kind of quantities from a given SchemaContext or SchemaLocater.

core/ecschema-metadata/src/ecschema-metadata.ts

@@ -45,7 +45,8 @@ export * from "./UnitConversion/UnitConverter";
 export * from "./UnitProvider/SchemaUnitProvider";
 export * from "./Validation/SchemaWalker";
 export * from "./SchemaPartVisitorDelegate";
-export * from "./SchemaFormatsProvider";
+export * from "./Formatting/SchemaFormatsProvider";
+export * from "./Formatting/FormatSetFormatsProvider";
 export * from "./IncrementalLoading/ECSqlSchemaLocater";
 export * from "./IncrementalLoading/IncrementalSchemaLocater";
 export { CustomAttribute, CustomAttributeContainerProps} from "./Metadata/CustomAttribute";