@itwin/core-backend 5.2.0-dev.7 → 5.2.0

package/lib/esm/test/annotations/Fields.test.js

@@ -7,14 +7,20 @@ import { Code, FieldRun, SubCategoryAppearance, TextAnnotation, TextBlock, TextR
 import { StandaloneDb } from "../../IModelDb";
 import { IModelTestUtils } from "../IModelTestUtils";
 import { createUpdateContext, updateField, updateFields } from "../../internal/annotations/fields";
-import { DbResult, Id64 } from "@itwin/core-bentley";
+import { DbResult, Id64, ProcessDetector } from "@itwin/core-bentley";
 import { SpatialCategory } from "../../Category";
 import { Point3d, YawPitchRollAngles } from "@itwin/core-geometry";
 import { Schema, Schemas } from "../../Schema";
 import { ClassRegistry } from "../../ClassRegistry";
 import { PhysicalElement } from "../../Element";
 import { ElementOwnsUniqueAspect, ElementUniqueAspect, FontFile, TextAnnotation3d } from "../../core-backend";
-import { ElementDrivesTextAnnotation } from "../../annotations/ElementDrivesTextAnnotation";
+import { ElementDrivesTextAnnotation, TextAnnotationUsesTextStyleByDefault } from "../../annotations/ElementDrivesTextAnnotation";
+function isIntlSupported() {
+    // Node in the mobile add-on does not include Intl, so this test fails. Right now, mobile
+    // users are not expected to do any editing, but long term we will attempt to find a better
+    // solution.
+    return !ProcessDetector.isMobileAppBackend;
+}
 describe("updateField", () => {
     const mockElementId = "0x1";
     const mockPath = {
@@ -31,7 +37,7 @@ describe("updateField", () => {
                 propertyPath.accessors?.[0] === 0 &&
                 propertyPath.accessors?.[1] === "nestedProperty" &&
                 propertyValue !== undefined) {
-                return { value: propertyValue, metadata: {} };
+                return { value: propertyValue, type: "string" };
             }
             return undefined;
         },
@@ -97,36 +103,43 @@ describe("updateField", () => {
         expect(fieldRun.cachedContent).to.equal(FieldRun.invalidContentIndicator);
     });
 });
-const fieldsSchemaXml = `
-<?xml version="1.0" encoding="UTF-8"?>
-<ECSchema schemaName="Fields" alias="ts" version="01.00.00" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.2">
-  <ECSchemaReference name="BisCore" version="01.00.04" alias="bis"/>
-
-  <ECStructClass typeName="InnerStruct" modifier="None">
-    <ECProperty propertyName="bool" typeName="boolean"/>
-    <ECArrayProperty propertyName="doubles" typeName="double" minOccurs="0" maxOccurs="unbounded"/>
-  </ECStructClass>
-
-  <ECStructClass typeName="OuterStruct" modifier="None">
-    <ECStructProperty propertyName="innerStruct" typeName="InnerStruct"/>
-    <ECStructArrayProperty propertyName="innerStructs" typeName="InnerStruct" minOccurs="0" maxOccurs="unbounded"/>
-  </ECStructClass>
-
-  <ECEntityClass typeName="TestElement" modifier="None">
-    <BaseClass>bis:PhysicalElement</BaseClass>
-    <ECProperty propertyName="intProp" typeName="int"/>
-    <ECProperty propertyName="point" typeName="point3d"/>
-    <ECProperty propertyName="maybeNull" typeName="int"/>
-    <ECArrayProperty propertyName="strings" typeName="string" minOccurs="0" maxOccurs="unbounded"/>
-    <ECStructProperty propertyName="outerStruct" typeName="OuterStruct"/>
-    <ECStructArrayProperty propertyName="outerStructs" typeName="OuterStruct" minOccurs="0" maxOccurs="unbounded"/>
-  </ECEntityClass>
-
-  <ECEntityClass typeName="TestAspect" modifier="None">
-    <BaseClass>bis:ElementUniqueAspect</BaseClass>
-    <ECProperty propertyName="aspectProp" typeName="int"/>
-  </ECEntityClass>
-</ECSchema>
+const fieldsSchemaXml = `
+<?xml version="1.0" encoding="UTF-8"?>
+<ECSchema schemaName="Fields" alias="ts" version="01.00.00" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.2">
+  <ECSchemaReference name="BisCore" version="01.00.04" alias="bis"/>
+
+  <ECEnumeration typeName="IntEnum" backingTypeName="int">
+    <ECEnumerator name="one" displayLabel="One" value="1" />
+    <ECEnumerator name="two" displayLabel="Two" value="2"/>
+  </ECEnumeration>
+
+  <ECStructClass typeName="InnerStruct" modifier="None">
+    <ECProperty propertyName="bool" typeName="boolean"/>
+    <ECArrayProperty propertyName="doubles" typeName="double" minOccurs="0" maxOccurs="unbounded"/>
+  </ECStructClass>
+
+  <ECStructClass typeName="OuterStruct" modifier="None">
+    <ECStructProperty propertyName="innerStruct" typeName="InnerStruct"/>
+    <ECStructArrayProperty propertyName="innerStructs" typeName="InnerStruct" minOccurs="0" maxOccurs="unbounded"/>
+  </ECStructClass>
+
+  <ECEntityClass typeName="TestElement" modifier="None">
+    <BaseClass>bis:PhysicalElement</BaseClass>
+    <ECProperty propertyName="intProp" typeName="int"/>
+    <ECProperty propertyName="point" typeName="point3d"/>
+    <ECProperty propertyName="maybeNull" typeName="int"/>
+    <ECProperty propertyName="datetime" typeName="dateTime"/>
+    <ECArrayProperty propertyName="strings" typeName="string" minOccurs="0" maxOccurs="unbounded"/>
+    <ECStructProperty propertyName="outerStruct" typeName="OuterStruct"/>
+    <ECStructArrayProperty propertyName="outerStructs" typeName="OuterStruct" minOccurs="0" maxOccurs="unbounded"/>
+    <ECProperty propertyName="intEnum" typeName="IntEnum"/>
+  </ECEntityClass>
+
+  <ECEntityClass typeName="TestAspect" modifier="None">
+    <BaseClass>bis:ElementUniqueAspect</BaseClass>
+    <ECProperty propertyName="aspectProp" typeName="int"/>
+  </ECEntityClass>
+</ECSchema>
 `;
 class TestElement extends PhysicalElement {
     static get className() { return "TestElement"; }
@@ -174,6 +187,8 @@ describe("Field evaluation", () => {
             intProp: 100,
             point: { x: 1, y: 2, z: 3 },
             strings: ["a", "b", `"name": "c"`],
+            datetime: new Date("2025-08-28T13:45:30.123Z"),
+            intEnum: 1,
             outerStruct: {
                 innerStruct: { bool: false, doubles: [1, 2, 3] },
                 innerStructs: [{ bool: true, doubles: [] }, { bool: false, doubles: [5, 4, 3, 2, 1] }],
@@ -189,6 +204,7 @@ describe("Field evaluation", () => {
             jsonProperties: {
                 stringProp: "abc",
                 ints: [10, 11, 12, 13],
+                bool: true,
                 zoo: {
                     address: {
                         zipcode: 12345,
@@ -210,22 +226,27 @@ describe("Field evaluation", () => {
         imodel.saveChanges();
         return id;
     }
+    function evaluateField(propertyPath, propertyHost, deletedDependency = false) {
+        if (typeof propertyHost === "string") {
+            propertyHost = { schemaName: "Fields", className: "TestElement", elementId: propertyHost };
+        }
+        const field = FieldRun.create({
+            propertyPath,
+            propertyHost,
+        });
+        const context = createUpdateContext(propertyHost.elementId, imodel, deletedDependency);
+        return context.getProperty(field);
+    }
     describe("getProperty", () => {
         function expectValue(expected, propertyPath, propertyHost, deletedDependency = false) {
-            if (typeof propertyHost === "string") {
-                propertyHost = { schemaName: "Fields", className: "TestElement", elementId: propertyHost };
-            }
-            const field = FieldRun.create({
-                propertyPath,
-                propertyHost,
-            });
-            const context = createUpdateContext(propertyHost.elementId, imodel, deletedDependency);
-            const actual = context.getProperty(field);
-            expect(actual?.value).to.deep.equal(expected);
+            expect(evaluateField(propertyPath, propertyHost, deletedDependency)?.value).to.deep.equal(expected);
         }
         it("returns a primitive property value", () => {
             expectValue(100, { propertyName: "intProp" }, sourceElementId);
         });
+        it("returns an integer enum property value", () => {
+            expectValue(1, { propertyName: "intEnum" }, sourceElementId);
+        });
         it("treats points as primitive values", () => {
             expectValue({ x: 1, y: 2, z: 3 }, { propertyName: "point" }, sourceElementId);
             expectValue(undefined, { propertyName: "point", accessors: ["x"] }, sourceElementId);
@@ -284,28 +305,62 @@ describe("Field evaluation", () => {
             expectValue(false, { propertyName: "outerStructs", accessors: [0, "innerStructs", -1, "bool"] }, sourceElementId);
             expectValue(5, { propertyName: "outerStructs", accessors: [0, "innerStructs", 0, "doubles", 0] }, sourceElementId);
         });
-        it("returns arbitrarily-nested JSON properties", () => {
-            expectValue("abc", { propertyName: "jsonProperties", jsonAccessors: ["stringProp"] }, sourceElementId);
-            expectValue(10, { propertyName: "jsonProperties", jsonAccessors: ["ints", 0] }, sourceElementId);
-            expectValue(13, { propertyName: "jsonProperties", jsonAccessors: ["ints", 3] }, sourceElementId);
-            expectValue(13, { propertyName: "jsonProperties", jsonAccessors: ["ints", -1] }, sourceElementId);
-            expectValue(11, { propertyName: "jsonProperties", jsonAccessors: ["ints", -3] }, sourceElementId);
-            expectValue(12345, { propertyName: "jsonProperties", jsonAccessors: ["zoo", "address", "zipcode"] }, sourceElementId);
-            expectValue("scree!", { propertyName: "jsonProperties", jsonAccessors: ["zoo", "birds", 1, "sound"] }, sourceElementId);
-        });
-        it("returns undefined if JSON accessors applied to non-JSON property", () => {
-            expectValue(undefined, { propertyName: "int", jsonAccessors: ["whatever"] }, sourceElementId);
-            expectValue(undefined, { propertyName: "strings", accessors: [2, "name"] }, sourceElementId);
-            expectValue(undefined, { propertyName: "outerStruct", accessors: ["innerStruct"], jsonAccessors: ["bool"] }, sourceElementId);
-        });
         it("returns the value of a property of an aspect", () => {
             expect(imodel.elements.getAspects(sourceElementId, "Fields:TestAspect").length).to.equal(1);
             expectValue(999, { propertyName: "aspectProp" }, { elementId: sourceElementId, schemaName: "Fields", className: "TestAspect" });
         });
+        it("should fail to evaluate if prop type does not match", () => {
+            const fieldRun = FieldRun.create({
+                propertyHost: { elementId: sourceElementId, schemaName: "Fields", className: "TestElement" },
+                propertyPath: { propertyName: "string", accessors: [0] },
+                cachedContent: "oldValue",
+                formatOptions: {
+                    case: "upper",
+                    prefix: "Value: ",
+                    suffix: "!"
+                }
+            });
+            const context = createUpdateContext(sourceElementId, imodel, false);
+            const updated = updateField(fieldRun, context);
+            expect(updated).to.be.true;
+            expect(fieldRun.cachedContent).to.equal(FieldRun.invalidContentIndicator);
+        });
+        function getPropertyType(propertyHost, propertyPath) {
+            if (typeof propertyPath === "string") {
+                propertyPath = { propertyName: propertyPath };
+            }
+            return evaluateField(propertyPath, propertyHost)?.type;
+        }
+        it("deduces type for primitive properties", () => {
+            const propertyHost = { elementId: sourceElementId, schemaName: "Fields", className: "TestElement" };
+            expect(getPropertyType(propertyHost, "intProp")).to.equal("string");
+            expect(getPropertyType(propertyHost, "point")).to.equal("coordinate");
+            expect(getPropertyType(propertyHost, { propertyName: "strings", accessors: [0] })).to.equal("string");
+            expect(getPropertyType(propertyHost, "intEnum")).to.equal("int-enum");
+            expect(getPropertyType(propertyHost, { propertyName: "outerStruct", accessors: ["innerStruct", "doubles", 0] })).to.equal("quantity");
+            expect(getPropertyType(propertyHost, { propertyName: "outerStruct", accessors: ["innerStruct", "bool"] })).to.equal("boolean");
+            propertyHost.schemaName = "BisCore";
+            propertyHost.className = "GeometricElement3d";
+            expect(getPropertyType(propertyHost, "LastMod")).to.equal("datetime");
+            expect(getPropertyType(propertyHost, "FederationGuid")).to.equal("string");
+        });
+        it("returns undefined for non-primitive properties", () => {
+            const propertyHost = { elementId: sourceElementId, schemaName: "Fields", className: "TestElement" };
+            expect(getPropertyType(propertyHost, "outerStruct")).to.equal(undefined);
+            expect(getPropertyType(propertyHost, "outerStructs")).to.equal(undefined);
+        });
+        it("returns undefined for invalid property paths", () => {
+            const propertyHost = { elementId: sourceElementId, schemaName: "Fields", className: "TestElement" };
+            expect(getPropertyType(propertyHost, "unknownPropertyName")).to.be.undefined;
+        });
+        it("should return undefined for unsupported primitive types", () => {
+            const host = { elementId: sourceElementId, schemaName: "BisCore", className: "GeometricElement3d" };
+            expect(getPropertyType(host, "GeometryStream")).to.be.undefined;
+        });
     });
     describe("updateFields", () => {
         it("recomputes cached content", () => {
-            const textBlock = TextBlock.create({ styleId: "0x123" });
+            const textBlock = TextBlock.create();
             const fieldRun = FieldRun.create({
                 propertyHost: { elementId: sourceElementId, schemaName: "Fields", className: "TestElement" },
                 propertyPath: { propertyName: "intProp" },
@@ -318,7 +373,7 @@ describe("Field evaluation", () => {
             expect(fieldRun.cachedContent).to.equal("100"); // `intProp` value from the test element
         });
         it("does not update a field if recomputed content matches cached content", () => {
-            const textBlock = TextBlock.create({ styleId: "0x123" });
+            const textBlock = TextBlock.create();
             const fieldRun = FieldRun.create({
                 propertyHost: { elementId: sourceElementId, schemaName: "Fields", className: "TestElement" },
                 propertyPath: { propertyName: "intProp" },
@@ -331,7 +386,7 @@ describe("Field evaluation", () => {
             expect(fieldRun.cachedContent).to.equal("100");
         });
         it("returns the number of fields updated", () => {
-            const textBlock = TextBlock.create({ styleId: "0x123" });
+            const textBlock = TextBlock.create();
             const fieldRun1 = FieldRun.create({
                 propertyHost: { elementId: sourceElementId, schemaName: "Fields", className: "TestElement" },
                 propertyPath: { propertyName: "intProp" },
@@ -361,6 +416,7 @@ describe("Field evaluation", () => {
                 angles: YawPitchRollAngles.createDegrees(0, 0, 0).toJSON(),
             },
             classFullName: TextAnnotation3d.classFullName,
+            defaultTextStyle: new TextAnnotationUsesTextStyleByDefault("0x123").toJSON(),
         }, imodel);
         if (textBlock) {
             const annotation = TextAnnotation.fromJSON({ textBlock: textBlock.toJSON() });
@@ -395,21 +451,21 @@ describe("Field evaluation", () => {
             expect(relationship.sourceId).to.equal(sourceElementId);
             expect(relationship.targetId).to.equal(targetId);
         });
-        function createField(propertyHost, cachedContent, propertyName = "intProp", accessors, jsonAccessors) {
+        function createField(propertyHost, cachedContent, propertyName = "intProp", accessors) {
             if (typeof propertyHost === "string") {
                 propertyHost = { schemaName: "Fields", className: "TestElement", elementId: propertyHost };
             }
             return FieldRun.create({
-                styleOverrides: { fontName: "Karla" },
+                styleOverrides: { font: { name: "Karla" } },
                 propertyHost,
                 cachedContent,
-                propertyPath: { propertyName, accessors, jsonAccessors },
+                propertyPath: { propertyName, accessors },
             });
         }
         describe("updateFieldDependencies", () => {
             it("creates exactly one relationship for each unique source element on insert and update", () => {
                 const source1 = insertTestElement();
-                const block = TextBlock.create({ styleId: "0x123" });
+                const block = TextBlock.create();
                 block.appendRun(createField(source1, "1"));
                 const targetId = insertAnnotationElement(block);
                 imodel.saveChanges();
@@ -437,7 +493,7 @@ describe("Field evaluation", () => {
             it("deletes stale relationships", () => {
                 const sourceA = insertTestElement();
                 const sourceB = insertTestElement();
-                const block = TextBlock.create({ styleId: "0x123" });
+                const block = TextBlock.create();
                 block.appendRun(createField(sourceA, "A"));
                 block.appendRun(createField(sourceB, "B"));
                 const targetId = insertAnnotationElement(block);
@@ -447,14 +503,16 @@ describe("Field evaluation", () => {
                 expect(imodel.relationships.tryGetInstance(ElementDrivesTextAnnotation.classFullName, { targetId, sourceId: sourceB })).not.to.be.undefined;
                 const target = imodel.elements.getElement(targetId);
                 const anno = target.getAnnotation();
-                anno.textBlock.paragraphs[0].runs.shift();
+                // Remove the sourceA FieldRun from the first paragraph.
+                const p1 = anno.textBlock.children[0];
+                p1.children.shift();
                 target.setAnnotation(anno);
                 target.update();
                 imodel.saveChanges();
                 expectNumRelationships(1, targetId);
                 expect(imodel.relationships.tryGetInstance(ElementDrivesTextAnnotation.classFullName, { targetId, sourceId: sourceA })).to.be.undefined;
                 expect(imodel.relationships.tryGetInstance(ElementDrivesTextAnnotation.classFullName, { targetId, sourceId: sourceB })).not.to.be.undefined;
-                anno.textBlock.paragraphs.length = 0;
+                anno.textBlock.children.length = 0;
                 anno.textBlock.appendRun(createField(sourceA, "A2"));
                 target.setAnnotation(anno);
                 target.update();
@@ -462,9 +520,9 @@ describe("Field evaluation", () => {
                 expectNumRelationships(1, targetId);
                 expect(imodel.relationships.tryGetInstance(ElementDrivesTextAnnotation.classFullName, { targetId, sourceId: sourceA })).not.to.be.undefined;
                 expect(imodel.relationships.tryGetInstance(ElementDrivesTextAnnotation.classFullName, { targetId, sourceId: sourceB })).to.be.undefined;
-                anno.textBlock.paragraphs.length = 0;
+                anno.textBlock.children.length = 0;
                 anno.textBlock.appendRun(TextRun.create({
-                    styleOverrides: { fontName: "Karla" },
+                    styleOverrides: { font: { name: "Karla" } },
                     content: "not a field",
                 }));
                 target.setAnnotation(anno);
@@ -476,7 +534,7 @@ describe("Field evaluation", () => {
             });
             it("ignores invalid source element Ids", () => {
                 const source = insertTestElement();
-                const block = TextBlock.create({ styleId: "0x123" });
+                const block = TextBlock.create();
                 block.appendRun(createField(Id64.invalid, "invalid"));
                 block.appendRun(createField("0xbaadf00d", "non-existent"));
                 block.appendRun(createField(source, "valid"));
@@ -491,9 +549,19 @@ describe("Field evaluation", () => {
             const actual = anno.textBlock.stringify();
             expect(actual).to.equal(expected);
         }
+        it("evaluates cachedContent when annotation element is inserted", () => {
+            const sourceId = insertTestElement();
+            const block = TextBlock.create();
+            block.appendRun(createField(sourceId, "initial cached content"));
+            expect(block.stringify()).to.equal("initial cached content");
+            const targetId = insertAnnotationElement(block);
+            imodel.saveChanges();
+            const target = imodel.elements.getElement(targetId);
+            expect(target.getAnnotation().textBlock.stringify()).to.equal("100");
+        });
         it("updates fields when source element is modified or deleted", () => {
             const sourceId = insertTestElement();
-            const block = TextBlock.create({ styleId: "0x123" });
+            const block = TextBlock.create();
             block.appendRun(createField(sourceId, "old value"));
             ;
             const targetId = insertAnnotationElement(block);
@@ -516,7 +584,7 @@ describe("Field evaluation", () => {
         });
         it("updates fields when source element aspect is modified, deleted, or recreated", () => {
             const sourceId = insertTestElement();
-            const block = TextBlock.create({ styleId: "0x123" });
+            const block = TextBlock.create();
             block.appendRun(createField({ elementId: sourceId, schemaName: "Fields", className: "TestAspect" }, "", "aspectProp"));
             const targetId = insertAnnotationElement(block);
             imodel.saveChanges();
@@ -544,7 +612,7 @@ describe("Field evaluation", () => {
         it("updates only fields for specific modified element", () => {
             const sourceA = insertTestElement();
             const sourceB = insertTestElement();
-            const block = TextBlock.create({ styleId: "0x123" });
+            const block = TextBlock.create();
             block.appendRun(createField(sourceA, "A"));
             block.appendRun(createField(sourceB, "B"));
             const targetId = insertAnnotationElement(block);
@@ -558,18 +626,67 @@ describe("Field evaluation", () => {
         });
         it("supports complex property paths", () => {
             const sourceId = insertTestElement();
-            const block = TextBlock.create({ styleId: "0x123" });
+            const block = TextBlock.create();
             block.appendRun(createField(sourceId, "", "outerStruct", ["innerStructs", 1, "doubles", -2]));
-            block.appendRun(createField(sourceId, "", "jsonProperties", undefined, ["zoo", "birds", 0, "name"]));
             const targetId = insertAnnotationElement(block);
             imodel.saveChanges();
-            expectText("2duck", targetId);
+            expectText("2", targetId);
             const source = imodel.elements.getElement(sourceId);
             source.outerStruct.innerStructs[1].doubles[3] = 12.5;
-            source.jsonProperties.zoo.birds[0].name = "parrot";
             source.update();
             imodel.saveChanges();
-            expectText("12.5parrot", targetId);
+            expectText("12.5", targetId);
+        });
+    });
+    describe("Format Validation", () => {
+        it("validates formatting options for string property type", () => {
+            // Create a FieldRun with string property type and some format options
+            const fieldRun = FieldRun.create({
+                propertyHost: { elementId: sourceElementId, schemaName: "Fields", className: "TestElement" },
+                propertyPath: { propertyName: "strings", accessors: [0] },
+                cachedContent: "oldValue",
+                formatOptions: {
+                    case: "upper",
+                    prefix: "Value: ",
+                    suffix: "!"
+                }
+            });
+            // Context returns a string value for the property
+            const context = {
+                hostElementId: sourceElementId,
+                getProperty: () => { return { value: "abc", type: "string" }; },
+            };
+            // Update the field and check the result
+            const updated = updateField(fieldRun, context);
+            // The formatted value should be uppercased and have prefix/suffix applied
+            expect(updated).to.be.true;
+            expect(fieldRun.cachedContent).to.equal("Value: ABC!");
+        });
+        it("validates formatting options for datetime objects", function () {
+            if (!isIntlSupported()) {
+                this.skip();
+            }
+            const propertyHost = { elementId: sourceElementId, schemaName: "Fields", className: "TestElement" };
+            const fieldRun = FieldRun.create({
+                propertyHost,
+                propertyPath: { propertyName: "datetime" },
+                cachedContent: "oldval",
+                formatOptions: {
+                    dateTime: {
+                        formatOptions: {
+                            month: "short",
+                            day: "2-digit",
+                            year: "numeric",
+                            timeZone: "UTC"
+                        },
+                        locale: "en-US",
+                    },
+                },
+            });
+            const context = createUpdateContext(sourceElementId, imodel, false);
+            const updated = updateField(fieldRun, context);
+            expect(updated).to.be.true;
+            expect(fieldRun.cachedContent).to.equal("Aug 28, 2025");
         });
     });
 });