@itwin/core-backend 5.2.0-dev.8 → 5.2.1

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

@@ -4,9 +4,9 @@
 *--------------------------------------------------------------------------------------------*/
 import { expect } from "chai";
 import { Angle, Point3d, Range2d, Range3d, YawPitchRollAngles } from "@itwin/core-geometry";
-import { FractionRun, SubCategoryAppearance, TextAnnotation, TextBlock, TextRun, TextStyleSettings } from "@itwin/core-common";
+import { FieldRun, FractionRun, SubCategoryAppearance, TextAnnotation, TextBlock, TextRun, TextStyleSettings } from "@itwin/core-common";
 import { StandaloneDb } from "../../IModelDb";
-import { AnnotationTextStyle, TextAnnotation2d, TextAnnotation3d } from "../../annotations/TextAnnotationElement";
+import { AnnotationTextStyle, parseTextAnnotationData, TEXT_ANNOTATION_JSON_VERSION, TEXT_STYLE_SETTINGS_JSON_VERSION, TextAnnotation2d, TextAnnotation3d } from "../../annotations/TextAnnotationElement";
 import { IModelTestUtils } from "../IModelTestUtils";
 import { Subject } from "../../Element";
 import { Guid, Id64 } from "@itwin/core-bentley";
@@ -15,7 +15,11 @@ import { DrawingCategory, SpatialCategory } from "../../Category";
 import { DisplayStyle2d, DisplayStyle3d } from "../../DisplayStyle";
 import { CategorySelector, DrawingViewDefinition, ModelSelector, SpatialViewDefinition } from "../../ViewDefinition";
 import { FontFile } from "../../FontFile";
-import { computeTextRangeAsStringLength } from "../AnnotationTestUtils";
+import { computeTextRangeAsStringLength, MockBuilder } from "../AnnotationTestUtils";
+import { TextAnnotationUsesTextStyleByDefault } from "../../annotations/ElementDrivesTextAnnotation";
+import { layoutTextBlock, TextStyleResolver } from "../../annotations/TextBlockLayout";
+import { appendTextAnnotationGeometry } from "../../annotations/TextAnnotationGeometry";
+import { IModelElementCloneContext } from "../../IModelElementCloneContext";
 function mockIModel() {
     const iModel = {
         fonts: {
@@ -26,13 +30,14 @@ function mockIModel() {
     };
     return iModel;
 }
-function createAnnotation(styleId) {
-    const styleOverrides = { fontName: "Karla" };
-    const block = TextBlock.create({ styleId: styleId ?? "0x42", styleOverrides });
-    block.appendRun(TextRun.create({ content: "Run, Barry,", styleOverrides }));
-    block.appendRun(TextRun.create({ content: " RUN!!! ", styleOverrides }));
-    block.appendRun(FractionRun.create({ numerator: "Harrison", denominator: "Wells", styleOverrides }));
-    block.margins = { left: 0, right: 1, top: 2, bottom: 3 };
+function createAnnotation(textBlock) {
+    const styleOverrides = { font: { name: "Karla" }, margins: { left: 0, right: 1, top: 2, bottom: 3 } };
+    const block = textBlock ?? TextBlock.create({ styleOverrides });
+    if (!textBlock) {
+        block.appendRun(TextRun.create({ content: "Run, Barry,", styleOverrides }));
+        block.appendRun(TextRun.create({ content: " RUN!!! ", styleOverrides }));
+        block.appendRun(FractionRun.create({ numerator: "Harrison", denominator: "Wells", styleOverrides }));
+    }
     const annotation = TextAnnotation.fromJSON({ textBlock: block.toJSON() });
     annotation.anchor = { vertical: "middle", horizontal: "right" };
     annotation.orientation = YawPitchRollAngles.createDegrees(1, 0, -1);
@@ -78,9 +83,34 @@ const createIModel = async (name) => {
     });
     return iModel;
 };
-const createAnnotationTextStyle = (iModel, definitionModel, name, settings = TextStyleSettings.defaultProps) => {
-    return AnnotationTextStyle.create(iModel, definitionModel, name, settings, "description");
+const createAnnotationTextStyle = (iModel, definitionModelId, name, settings = TextStyleSettings.defaultProps) => {
+    return AnnotationTextStyle.create(iModel, {
+        definitionModelId,
+        name,
+        settings,
+        description: "description",
+    });
 };
+function createElement2d(imodel, createArgs) {
+    const placement = {
+        origin: { x: 0, y: 0 },
+        angle: Angle.createDegrees(0).toJSON(),
+    };
+    return TextAnnotation2d.create(imodel, {
+        ...createArgs,
+        placement,
+    });
+}
+function createElement3d(imodel, createArgs) {
+    const placement = {
+        origin: { x: 0, y: 0, z: 0 },
+        angles: YawPitchRollAngles.createDegrees(0, 0, 0).toJSON(),
+    };
+    return TextAnnotation3d.create(imodel, {
+        ...createArgs,
+        placement,
+    });
+}
 describe("TextAnnotation element", () => {
     function makeElement(props) {
         return TextAnnotation2d.fromJSON({
@@ -95,25 +125,76 @@ describe("TextAnnotation element", () => {
                 origin: { x: 0, y: 0 },
                 angle: 0,
             },
+            defaultTextStyle: new TextAnnotationUsesTextStyleByDefault("0x21").toJSON(),
             ...props,
         }, mockIModel());
     }
+    describe("versioning", () => {
+        it("throws if the JSON has no version", () => {
+            expect(() => makeElement({
+                textAnnotationData: JSON.stringify({
+                    data: {
+                        textBlock: TextBlock.create().toJSON()
+                    }
+                }),
+            })).to.throw("JSON version is missing or invalid.");
+        });
+        it("throws if the JSON has no data", () => {
+            expect(() => makeElement({
+                textAnnotationData: JSON.stringify({
+                    version: TEXT_ANNOTATION_JSON_VERSION,
+                }),
+            })).to.throw("JSON data is missing or invalid.");
+        });
+        it("throws if the JSON version is too new", () => {
+            expect(() => makeElement({
+                textAnnotationData: JSON.stringify({
+                    version: "999.999.999",
+                    data: {
+                        textBlock: TextBlock.create().toJSON()
+                    }
+                }),
+            })).to.throw(`JSON version 999.999.999 is newer than supported version ${TEXT_ANNOTATION_JSON_VERSION}. Application update required to understand data.`);
+        });
+        it("throws if the JSON version is old and cannot be migrated", () => {
+            expect(() => makeElement({
+                textAnnotationData: JSON.stringify({
+                    version: "0.0.1",
+                    data: {
+                        textBlock: TextBlock.create().toJSON()
+                    }
+                }),
+            })).to.throw(`Migration for textAnnotationData from version 0.0.1 to ${TEXT_ANNOTATION_JSON_VERSION} failed.`);
+        });
+    });
     describe("getAnnotation", () => {
         it("returns undefined if not provided", () => {
             expect(makeElement().getAnnotation()).to.be.undefined;
         });
         it("converts JSON string to class instance", () => {
             const elem = makeElement({
-                textAnnotationData: JSON.stringify({ textBlock: TextBlock.create({ styleId: "0x42" }).toJSON() })
+                textAnnotationData: JSON.stringify({
+                    version: TEXT_ANNOTATION_JSON_VERSION,
+                    data: {
+                        textBlock: TextBlock.create().toJSON()
+                    }
+                }),
+                defaultTextStyle: new TextAnnotationUsesTextStyleByDefault("0x42").toJSON()
             });
             const anno = elem.getAnnotation();
             expect(anno).not.to.be.undefined;
             expect(anno.textBlock.isEmpty).to.be.true;
-            expect(anno.textBlock.styleId).to.equal("0x42");
+            expect(elem.defaultTextStyle).not.to.be.undefined;
+            expect(elem.defaultTextStyle.id).to.equal("0x42");
         });
         it("produces a new object each time it is called", () => {
             const elem = makeElement({
-                textAnnotationData: JSON.stringify({ textBlock: TextBlock.create({ styleId: "0x42" }).toJSON() })
+                textAnnotationData: JSON.stringify({
+                    version: TEXT_ANNOTATION_JSON_VERSION,
+                    data: {
+                        textBlock: TextBlock.create().toJSON()
+                    }
+                }),
             });
             const anno1 = elem.getAnnotation();
             const anno2 = elem.getAnnotation();
@@ -124,7 +205,7 @@ describe("TextAnnotation element", () => {
     describe("setAnnotation", () => {
         it("updates properties", () => {
             const elem = makeElement();
-            const textBlock = TextBlock.create({ styleId: "0x42" });
+            const textBlock = TextBlock.create();
             textBlock.appendRun(TextRun.create({ content: "text" }));
             const annotation = TextAnnotation.fromJSON({ textBlock: textBlock.toJSON() });
             elem.setAnnotation(annotation);
@@ -132,35 +213,78 @@ describe("TextAnnotation element", () => {
             expect(elem.getAnnotation().toJSON()).not.to.equal(annotation.toJSON());
         });
     });
+    describe("getReferenceIds", () => {
+        function expectReferenceIds(expected, element) {
+            const actual = Array.from(element.getReferenceIds()).sort();
+            // reference Ids get a prefix indicating their type ('e' for 'element')
+            expected = expected.map((id) => `e${id}`);
+            // the superclasses provide some reference Ids (code spec, model, category)
+            const baseIds = ["e0x12", "e0x78", "m0x34"];
+            expected.push(...baseIds);
+            expected = expected.sort();
+            expect(actual).to.deep.equal(expected);
+        }
+        it("reports default text style and field hosts", () => {
+            // makeElement sets defaultTextStyle to "0x21"
+            const elem = makeElement();
+            expectReferenceIds(["0x21"], elem);
+            elem.defaultTextStyle = new TextAnnotationUsesTextStyleByDefault("0x123");
+            expectReferenceIds(["0x123"], elem);
+            const textBlock = TextBlock.create();
+            textBlock.appendRun(FieldRun.create({
+                propertyHost: { elementId: "0x456", schemaName: "BisCore", className: "GeometricElement3d" },
+                propertyPath: { propertyName: "CodeValue" },
+            }));
+            textBlock.appendRun(FieldRun.create({
+                propertyHost: { elementId: "0x789", schemaName: "BisCore", className: "GeometricElement3d" },
+                propertyPath: { propertyName: "LastMod" },
+            }));
+            elem.setAnnotation(TextAnnotation.create({ textBlock }));
+            expectReferenceIds(["0x123", "0x456", "0x789"], elem);
+            elem.defaultTextStyle = undefined;
+            expectReferenceIds(["0x456", "0x789"], elem);
+            elem.setAnnotation(TextAnnotation.create());
+            expectReferenceIds([], elem);
+        });
+        it("does not report invalid Ids", () => {
+            const elem = makeElement();
+            elem.defaultTextStyle = undefined;
+            expectReferenceIds([], elem);
+            elem.defaultTextStyle = new TextAnnotationUsesTextStyleByDefault("0");
+            expectReferenceIds([], elem);
+            const textBlock = TextBlock.create();
+            textBlock.appendRun(FieldRun.create({
+                propertyHost: { elementId: "0", schemaName: "BisCore", className: "GeometricElement3d" },
+                propertyPath: { propertyName: "CodeValue" },
+            }));
+            textBlock.appendRun(FieldRun.create({
+                propertyHost: { elementId: "0x123", schemaName: "BisCore", className: "GeometricElement3d" },
+                propertyPath: { propertyName: "LastMod" },
+            }));
+            elem.setAnnotation(TextAnnotation.create({ textBlock }));
+            expectReferenceIds(["0x123"], elem);
+        });
+    });
     describe("TextAnnotation3d Persistence", () => {
         let imodel;
-        let seedCategoryId;
-        let seedModelId;
-        let seedStyleId;
+        let createElement3dArgs;
         before(async () => {
             imodel = await createIModel("TextAnnotation3d");
             const jobSubjectId = createJobSubjectElement(imodel, "Job").insert();
             const definitionModel = DefinitionModel.insert(imodel, jobSubjectId, "Definition");
             const { category, model } = insertSpatialModel(imodel, jobSubjectId, definitionModel);
-            const styleId = createAnnotationTextStyle(imodel, definitionModel, "test", { fontName: "Totally Real Font", lineHeight: 0.25, isItalic: true }).insert();
+            const styleId = createAnnotationTextStyle(imodel, definitionModel, "test", { font: { name: "Totally Real Font" }, textHeight: 0.25, isItalic: true }).insert();
             expect(jobSubjectId).not.to.be.undefined;
             expect(category).not.to.be.undefined;
             expect(model).not.to.be.undefined;
             expect(styleId).not.to.be.undefined;
-            seedCategoryId = category;
-            seedModelId = model;
-            seedStyleId = styleId;
+            createElement3dArgs = { category, model };
         });
         after(() => imodel.close());
-        function createElement3d(createArgs) {
-            return TextAnnotation3d.create(imodel, seedCategoryId, seedModelId, {
-                origin: { x: 0, y: 0, z: 0 },
-                angles: YawPitchRollAngles.createDegrees(0, 0, 0).toJSON(),
-            }, createArgs?.textAnnotationData);
-        }
         it("creating element does not automatically compute the geometry", () => {
             const annotation = createAnnotation();
-            const el = createElement3d({ textAnnotationData: annotation.toJSON() });
+            const args = { ...createElement3dArgs, textAnnotationProps: annotation.toJSON() };
+            const el = createElement3d(imodel, args);
             expect(el.getAnnotation().equals(annotation)).to.be.true;
             expect(el.geom).to.be.undefined;
         });
@@ -175,7 +299,7 @@ describe("TextAnnotation element", () => {
         }
         describe("inserts 3d element and round-trips through JSON", async () => {
             async function test(annotation) {
-                const el0 = createElement3d();
+                const el0 = createElement3d(imodel, { ...createElement3dArgs });
                 if (annotation) {
                     el0.setAnnotation(annotation);
                 }
@@ -198,42 +322,30 @@ describe("TextAnnotation element", () => {
                 }
             }
             it("roundtrips an empty annotation", async () => { await test(); });
-            it("roundtrips an annotation with a style", async () => { await test(TextAnnotation.fromJSON({ textBlock: { styleId: seedStyleId } })); });
             it("roundtrips an annotation with a textBlock", async () => { await test(createAnnotation()); });
         });
     });
     describe("TextAnnotation2d Persistence", () => {
         let imodel;
-        let seedCategoryId;
-        let seedModelId;
-        let seedStyleId;
+        let createElement2dArgs;
         before(async () => {
             imodel = await createIModel("TextAnnotation2d");
             const jobSubjectId = createJobSubjectElement(imodel, "Job").insert();
             const definitionModel = DefinitionModel.insert(imodel, jobSubjectId, "Definition");
             const { category, model } = insertDrawingModel(imodel, jobSubjectId, definitionModel);
-            const styleId = createAnnotationTextStyle(imodel, definitionModel, "test", { fontName: "Totally Real Font", lineHeight: 0.25, isItalic: true }).insert();
             expect(jobSubjectId).not.to.be.undefined;
             expect(category).not.to.be.undefined;
             expect(model).not.to.be.undefined;
-            expect(styleId).not.to.be.undefined;
-            seedCategoryId = category;
-            seedModelId = model;
-            seedStyleId = styleId;
+            createElement2dArgs = { category, model };
         });
         after(() => {
             imodel.saveChanges("tests");
             imodel.close();
         });
-        function createElement2d(createArgs) {
-            return TextAnnotation2d.create(imodel, seedCategoryId, seedModelId, {
-                origin: { x: 0, y: 0 },
-                angle: Angle.createDegrees(0).toJSON(),
-            }, createArgs?.textAnnotationData);
-        }
         it("creating element does not automatically compute the geometry", () => {
             const annotation = createAnnotation();
-            const el = createElement2d({ textAnnotationData: annotation.toJSON() });
+            const args = { ...createElement2dArgs, textAnnotationProps: annotation.toJSON() };
+            const el = createElement2d(imodel, args);
             expect(el.getAnnotation().equals(annotation)).to.be.true;
             expect(el.geom).to.be.undefined;
         });
@@ -245,7 +357,7 @@ describe("TextAnnotation element", () => {
         }
         describe("inserts 2d element and round-trips through JSON", async () => {
             async function test(annotation) {
-                const el0 = createElement2d();
+                const el0 = createElement2d(imodel, createElement2dArgs);
                 if (annotation) {
                     el0.setAnnotation(annotation);
                 }
@@ -265,13 +377,299 @@ describe("TextAnnotation element", () => {
                     expect(anno).not.to.be.undefined;
                     expect(anno.equals(annotation)).to.be.true;
                     expect(el0.toJSON().elementGeometryBuilderParams).not.to.be.undefined;
+                    expect(el0.toJSON().elementGeometryBuilderParams).to.deep.equal(el1.toJSON().elementGeometryBuilderParams);
                 }
             }
             it("roundtrips an empty annotation", async () => { await test(); });
-            it("roundtrips an annotation with a style", async () => { await test(TextAnnotation.fromJSON({ textBlock: { styleId: seedStyleId } })); });
             it("roundtrips an annotation with a textBlock", async () => { await test(createAnnotation()); });
         });
     });
+    describe("defaultTextStyle", () => {
+        let imodel;
+        let seedSubjectId;
+        let seedDefinitionModelId;
+        let seedStyleId;
+        let seedStyleId2;
+        before(async () => {
+            imodel = await createIModel("DefaultTextStyle");
+            const jobSubjectId = createJobSubjectElement(imodel, "Job").insert();
+            const definitionModel = DefinitionModel.insert(imodel, jobSubjectId, "Definition");
+            const styleId = createAnnotationTextStyle(imodel, definitionModel, "test", { font: { name: "Totally Real Font" }, textHeight: 0.25, isItalic: true }).insert();
+            const differentStyleId = createAnnotationTextStyle(imodel, definitionModel, "alt", { font: { name: "Karla" }, textHeight: 0.5, isBold: true }).insert();
+            expect(jobSubjectId).not.to.be.undefined;
+            expect(definitionModel).not.to.be.undefined;
+            expect(styleId).not.to.be.undefined;
+            expect(differentStyleId).not.to.be.undefined;
+            seedSubjectId = jobSubjectId;
+            seedDefinitionModelId = definitionModel;
+            seedStyleId = styleId;
+            seedStyleId2 = differentStyleId;
+        });
+        after(() => {
+            imodel.saveChanges("tests");
+            imodel.close();
+        });
+        describe("TextAnnotation2d", () => {
+            let createElement2dArgs;
+            before(() => {
+                const { category, model } = insertDrawingModel(imodel, seedSubjectId, seedDefinitionModelId);
+                expect(category).not.to.be.undefined;
+                expect(model).not.to.be.undefined;
+                createElement2dArgs = { category, model };
+            });
+            it("preserves defaultTextStyle after round trip", () => {
+                const annotation = createAnnotation();
+                const args = { ...createElement2dArgs, textAnnotationProps: annotation.toJSON(), defaultTextStyleId: seedStyleId };
+                const el0 = createElement2d(imodel, args);
+                expect(el0.defaultTextStyle).not.to.be.undefined;
+                expect(el0.defaultTextStyle.id).to.equal(seedStyleId);
+                el0.insert();
+                const el1 = imodel.elements.getElement(el0.id);
+                expect(el1).not.to.be.undefined;
+                expect(el1.defaultTextStyle).not.to.be.undefined;
+                expect(el1.defaultTextStyle.id).to.equal(seedStyleId);
+                expect(el0.toJSON().elementGeometryBuilderParams).to.deep.equal(el1.toJSON().elementGeometryBuilderParams);
+            });
+            it("produces different geometry when defaultTextStyle changes", () => {
+                const annotation = createAnnotation();
+                const args = { ...createElement2dArgs, textAnnotationProps: annotation.toJSON() };
+                const el0 = createElement2d(imodel, args);
+                el0.defaultTextStyle = new TextAnnotationUsesTextStyleByDefault(seedStyleId);
+                const geom1 = el0.toJSON().elementGeometryBuilderParams;
+                el0.defaultTextStyle = new TextAnnotationUsesTextStyleByDefault(seedStyleId2);
+                const geom2 = el0.toJSON().elementGeometryBuilderParams;
+                expect(geom1).not.to.deep.equal(geom2);
+            });
+            it("allows defaultTextStyle to be undefined", () => {
+                const annotation = createAnnotation();
+                const args = { ...createElement2dArgs, textAnnotationProps: annotation.toJSON() };
+                const el0 = createElement2d(imodel, args);
+                el0.defaultTextStyle = undefined;
+                const elId = el0.insert();
+                expect(Id64.isValidId64(elId)).to.be.true;
+                const el1 = imodel.elements.getElement(elId);
+                expect(el1).not.to.be.undefined;
+                expect(el1 instanceof TextAnnotation2d).to.be.true;
+                expect(el1.defaultTextStyle).to.be.undefined;
+            });
+            describe("onCloned", () => {
+                function insertStyledElement(styleId, db) {
+                    const args = { ...createElement2dArgs, defaultTextStyleId: styleId };
+                    const elem = createElement2d(db, args);
+                    elem.insert();
+                    imodel.saveChanges();
+                    return elem;
+                }
+                describe("within a single iModel", () => {
+                    it("leaves property hosts intact", () => {
+                        const textBlock = TextBlock.create({
+                            children: [{
+                                    children: [{
+                                            type: "field",
+                                            propertyHost: {
+                                                elementId: "0x123",
+                                                schemaName: "Fields",
+                                                className: "TestElement",
+                                            },
+                                            propertyPath: { propertyName: "intProp" },
+                                        }, {
+                                            type: "field",
+                                            propertyHost: {
+                                                elementId: "0xabc",
+                                                schemaName: "BisCore",
+                                                className: "Element",
+                                            },
+                                            propertyPath: { propertyName: "CodeValue" },
+                                        }],
+                                }],
+                        });
+                        const annotation = TextAnnotation.create({ textBlock });
+                        const elem = createElement2d(imodel, { ...createElement2dArgs, textAnnotationProps: annotation.toJSON() });
+                        elem.insert();
+                        imodel.saveChanges();
+                        const context = new IModelElementCloneContext(imodel);
+                        context.remapElement("0x123", "0x456");
+                        context.remapElement("0xabc", "0xdef");
+                        context.remapElement(createElement2dArgs.model, createElement2dArgs.model);
+                        const props = context.cloneElement(elem);
+                        expect(props.textAnnotationData).not.to.be.undefined;
+                        const anno = TextAnnotation.fromJSON(parseTextAnnotationData(props.textAnnotationData)?.data);
+                        const para = anno.textBlock.children[0];
+                        expect(para.children[0].propertyHost.elementId).to.equal("0x123");
+                        expect(para.children[1].propertyHost.elementId).to.equal("0xabc");
+                    });
+                    it("leaves default text style intact", () => {
+                        function clone(styleId, expectedStyleId) {
+                            const elem = insertStyledElement(styleId, imodel);
+                            const context = new IModelElementCloneContext(imodel);
+                            context.remapElement(createElement2dArgs.model, createElement2dArgs.model);
+                            const props = context.cloneElement(elem);
+                            expect(props.defaultTextStyle?.id).to.equal(expectedStyleId);
+                            if (styleId) {
+                                // Even an explicit remapping is ignored when cloning within a single iModel
+                                // (per the examples set by most other elements, excluding RenderMaterial).
+                                context.remapElement(styleId, "0x99887");
+                                const props2 = context.cloneElement(elem);
+                                expect(props2.defaultTextStyle?.id).to.equal(expectedStyleId);
+                            }
+                        }
+                        clone(seedStyleId, seedStyleId);
+                        clone(undefined, undefined);
+                        clone("0x12345", "0x12345");
+                        clone(Id64.invalid, undefined);
+                    });
+                });
+                describe("between iModels", () => {
+                    let dstDb;
+                    let dstDefModel;
+                    let dstElemArgs;
+                    before(async () => {
+                        dstDb = await createIModel("CloneTarget");
+                        const jobSubjectId = createJobSubjectElement(dstDb, "Job").insert();
+                        dstDefModel = DefinitionModel.insert(dstDb, jobSubjectId, "Definition");
+                        const { category, model } = insertDrawingModel(dstDb, jobSubjectId, dstDefModel);
+                        expect(category).not.to.equal(createElement2dArgs.category);
+                        expect(model).not.to.equal(createElement2dArgs.model);
+                        dstElemArgs = { category, model };
+                    });
+                    after(() => dstDb.close());
+                    it("remaps property hosts", () => {
+                        const textBlock = TextBlock.create({
+                            children: [{
+                                    children: [{
+                                            type: "field",
+                                            propertyHost: {
+                                                elementId: "0x123",
+                                                schemaName: "Fields",
+                                                className: "TestElement",
+                                            },
+                                            propertyPath: { propertyName: "intProp" },
+                                        }, {
+                                            type: "field",
+                                            propertyHost: {
+                                                elementId: "0xabc",
+                                                schemaName: "BisCore",
+                                                className: "Element",
+                                            },
+                                            propertyPath: { propertyName: "CodeValue" },
+                                        }],
+                                }],
+                        });
+                        const annotation = TextAnnotation.create({ textBlock });
+                        const elem = createElement2d(imodel, { ...createElement2dArgs, textAnnotationProps: annotation.toJSON() });
+                        elem.insert();
+                        imodel.saveChanges();
+                        const context = new IModelElementCloneContext(imodel, dstDb);
+                        context.remapElement("0x123", "0x456");
+                        context.remapElement("0xabc", "0xdef");
+                        context.remapElement(createElement2dArgs.model, dstElemArgs.model);
+                        const props = context.cloneElement(elem);
+                        expect(props.textAnnotationData).not.to.be.undefined;
+                        const anno = TextAnnotation.fromJSON(parseTextAnnotationData(props.textAnnotationData)?.data);
+                        const para = anno.textBlock.children[0];
+                        expect(para.children[0].propertyHost.elementId).to.equal("0x456");
+                        expect(para.children[1].propertyHost.elementId).to.equal("0xdef");
+                    });
+                    it("sets default text style to undefined if source style does not exist", () => {
+                        const elem = insertStyledElement("0x12345", imodel);
+                        const context = new IModelElementCloneContext(imodel, dstDb);
+                        context.remapElement(createElement2dArgs.model, dstElemArgs.model);
+                        const props = context.cloneElement(elem);
+                        expect(props.defaultTextStyle).to.be.undefined;
+                    });
+                    it("remaps to an existing text style with the same code if present", () => {
+                        const dstStyleId = createAnnotationTextStyle(dstDb, dstDefModel, "test", { font: { name: "Karla" } }).insert();
+                        expect(dstStyleId).not.to.equal(seedStyleId);
+                        const srcElem = insertStyledElement(seedStyleId, imodel);
+                        const context = new IModelElementCloneContext(imodel, dstDb);
+                        context.remapElement(createElement2dArgs.model, dstElemArgs.model);
+                        const props = context.cloneElement(srcElem);
+                        expect(props.defaultTextStyle?.id).to.equal(dstStyleId);
+                    });
+                    it("throws an error if definition model is not remapped", () => {
+                        const srcElem = insertStyledElement(seedStyleId2, imodel);
+                        const context = new IModelElementCloneContext(imodel, dstDb);
+                        context.remapElement(createElement2dArgs.model, dstElemArgs.model);
+                        expect(() => context.cloneElement(srcElem)).to.throw("Invalid target model");
+                    });
+                    it("imports default text style if necessary", () => {
+                        const srcElem = insertStyledElement(seedStyleId2, imodel);
+                        const context = new IModelElementCloneContext(imodel, dstDb);
+                        context.remapElement(createElement2dArgs.model, dstElemArgs.model);
+                        context.remapElement(seedDefinitionModelId, dstDefModel);
+                        const props = context.cloneElement(srcElem);
+                        const dstStyleId = props.defaultTextStyle.id;
+                        expect(dstStyleId).not.to.be.undefined;
+                        expect(dstStyleId).not.to.equal(seedStyleId2);
+                        expect(dstDb.elements.tryGetElement(dstStyleId)).not.to.be.undefined;
+                    });
+                    it("remaps multiple occurrences of same style to same Id", () => {
+                        const srcStyleId = createAnnotationTextStyle(imodel, seedDefinitionModelId, "styyyle", { font: { name: "Karla" } }).insert();
+                        const srcElem1 = insertStyledElement(srcStyleId, imodel);
+                        const srcElem2 = insertStyledElement(srcStyleId, imodel);
+                        const srcElem3 = insertStyledElement(srcStyleId, imodel);
+                        const context = new IModelElementCloneContext(imodel, dstDb);
+                        context.remapElement(createElement2dArgs.model, dstElemArgs.model);
+                        context.remapElement(seedDefinitionModelId, dstDefModel);
+                        const props1 = context.cloneElement(srcElem1);
+                        const props2 = context.cloneElement(srcElem2);
+                        expect(props1.defaultTextStyle).not.to.be.undefined;
+                        expect(props1.defaultTextStyle?.id).not.to.equal(srcStyleId);
+                        expect(props2.defaultTextStyle?.id).to.equal(props1.defaultTextStyle?.id);
+                        const context2 = new IModelElementCloneContext(imodel, dstDb);
+                        context2.remapElement(createElement2dArgs.model, dstElemArgs.model);
+                        context2.remapElement(seedDefinitionModelId, dstDefModel);
+                        const props3 = context2.cloneElement(srcElem3);
+                        expect(props3.defaultTextStyle?.id).to.equal(props1.defaultTextStyle?.id);
+                    });
+                });
+            });
+        });
+        describe("TextAnnotation3d", () => {
+            let createElement3dArgs;
+            before(() => {
+                const { category, model } = insertSpatialModel(imodel, seedSubjectId, seedDefinitionModelId);
+                expect(category).not.to.be.undefined;
+                expect(model).not.to.be.undefined;
+                createElement3dArgs = { category, model };
+            });
+            it("preserves defaultTextStyle after round trip", () => {
+                const annotation = createAnnotation();
+                const args = { ...createElement3dArgs, textAnnotationProps: annotation.toJSON(), defaultTextStyleId: seedStyleId };
+                const el0 = createElement3d(imodel, args);
+                expect(el0.defaultTextStyle).not.to.be.undefined;
+                expect(el0.defaultTextStyle.id).to.equal(seedStyleId);
+                el0.insert();
+                const el1 = imodel.elements.getElement(el0.id);
+                expect(el1).not.to.be.undefined;
+                expect(el1.defaultTextStyle).not.to.be.undefined;
+                expect(el1.defaultTextStyle.id).to.equal(seedStyleId);
+                expect(el0.toJSON().elementGeometryBuilderParams).to.deep.equal(el1.toJSON().elementGeometryBuilderParams);
+            });
+            it("produces different geometry when defaultTextStyle changes", () => {
+                const annotation = createAnnotation();
+                const args = { ...createElement3dArgs, textAnnotationProps: annotation.toJSON() };
+                const el0 = createElement3d(imodel, args);
+                el0.defaultTextStyle = new TextAnnotationUsesTextStyleByDefault(seedStyleId);
+                const geom1 = el0.toJSON().elementGeometryBuilderParams;
+                el0.defaultTextStyle = new TextAnnotationUsesTextStyleByDefault(seedStyleId2);
+                const geom2 = el0.toJSON().elementGeometryBuilderParams;
+                expect(geom1).not.to.deep.equal(geom2);
+            });
+            it("allows defaultTextStyle to be undefined", () => {
+                const annotation = createAnnotation();
+                const args = { ...createElement3dArgs, textAnnotationProps: annotation.toJSON() };
+                const el0 = createElement3d(imodel, args);
+                el0.defaultTextStyle = undefined;
+                const elId = el0.insert();
+                expect(Id64.isValidId64(elId)).to.be.true;
+                const el1 = imodel.elements.getElement(elId);
+                expect(el1).not.to.be.undefined;
+                expect(el1 instanceof TextAnnotation3d).to.be.true;
+                expect(el1.defaultTextStyle).to.be.undefined;
+            });
+        });
+    });
 });
 describe("AnnotationTextStyle", () => {
     let imodel;
@@ -291,9 +689,9 @@ describe("AnnotationTextStyle", () => {
     });
     it("inserts a style and round-trips through JSON", async () => {
         const textStyle = TextStyleSettings.fromJSON({
-            fontName: "Totally Real Font",
+            font: { name: "Totally Real Font" },
             isUnderlined: true,
-            lineHeight: 0.5
+            textHeight: 0.5
         });
         const el0 = createAnnotationTextStyle(imodel, seedDefinitionModel, "round-trip", textStyle.toJSON());
         const elId = el0.insert();
@@ -310,27 +708,27 @@ describe("AnnotationTextStyle", () => {
         let annotationTextStyle = createAnnotationTextStyle(imodel, seedDefinitionModel, "default");
         expect(() => annotationTextStyle.insert()).to.throw();
         // font is required
-        annotationTextStyle = createAnnotationTextStyle(imodel, seedDefinitionModel, "no font", { fontName: "" });
+        annotationTextStyle = createAnnotationTextStyle(imodel, seedDefinitionModel, "no font", { font: { name: "" } });
         expect(() => annotationTextStyle.insert()).to.throw();
-        // lineHeight should be positive
-        annotationTextStyle = createAnnotationTextStyle(imodel, seedDefinitionModel, "invalid lineHeight", { fontName: "Totally Real Font", lineHeight: 0 });
+        // textHeight should be positive
+        annotationTextStyle = createAnnotationTextStyle(imodel, seedDefinitionModel, "invalid textHeight", { font: { name: "Totally Real Font" }, textHeight: 0 });
         expect(() => annotationTextStyle.insert()).to.throw();
         // stackedFractionScale should be positive
-        annotationTextStyle = createAnnotationTextStyle(imodel, seedDefinitionModel, "invalid stackedFractionScale", { fontName: "Totally Real Font", stackedFractionScale: 0 });
+        annotationTextStyle = createAnnotationTextStyle(imodel, seedDefinitionModel, "invalid stackedFractionScale", { font: { name: "Totally Real Font" }, stackedFractionScale: 0 });
         expect(() => annotationTextStyle.insert()).to.throw();
     });
     it("does not allow updating of elements to invalid styles", async () => {
-        const annotationTextStyle = createAnnotationTextStyle(imodel, seedDefinitionModel, "valid style", { fontName: "Totally Real Font" });
+        const annotationTextStyle = createAnnotationTextStyle(imodel, seedDefinitionModel, "valid style", { font: { name: "Totally Real Font" } });
         const elId = annotationTextStyle.insert();
         expect(Id64.isValidId64(elId)).to.be.true;
         const el1 = imodel.elements.getElement(elId);
         expect(el1).not.to.be.undefined;
         expect(el1 instanceof AnnotationTextStyle).to.be.true;
-        el1.settings = el1.settings.clone({ fontName: "" });
+        el1.settings = el1.settings.clone({ font: { name: "" } });
         expect(() => el1.update()).to.throw();
-        el1.settings = el1.settings.clone({ fontName: "Totally Real Font", lineHeight: 0 });
+        el1.settings = el1.settings.clone({ font: { name: "Totally Real Font" }, textHeight: 0 });
         expect(() => el1.update()).to.throw();
-        el1.settings = el1.settings.clone({ lineHeight: 2, stackedFractionScale: 0 });
+        el1.settings = el1.settings.clone({ textHeight: 2, stackedFractionScale: 0 });
         expect(() => el1.update()).to.throw();
         el1.settings = el1.settings.clone({ stackedFractionScale: 0.45 });
         el1.update();
@@ -347,11 +745,189 @@ describe("AnnotationTextStyle", () => {
         expect(el0.settings.toJSON()).to.deep.equal(TextStyleSettings.defaultProps);
     });
     it("can update style via cloning", async () => {
-        const el0 = createAnnotationTextStyle(imodel, seedDefinitionModel, "cloning", { fontName: "Totally Real Font" });
+        const el0 = createAnnotationTextStyle(imodel, seedDefinitionModel, "cloning", { font: { name: "Totally Real Font" } });
         const newStyle = el0.settings.clone({ isBold: true, lineSpacingFactor: 3 });
         expect(el0.settings.toJSON()).to.not.deep.equal(newStyle.toJSON());
         el0.settings = newStyle;
         expect(el0.settings.toJSON()).to.deep.equal(newStyle.toJSON());
     });
+    describe("versioning", () => {
+        function makeStyle(props) {
+            return AnnotationTextStyle.fromJSON({
+                model: "0x34",
+                code: {
+                    spec: "0x56",
+                    scope: "0x78",
+                    value: "style"
+                },
+                classFullName: AnnotationTextStyle.classFullName,
+                ...props,
+            }, mockIModel());
+        }
+        it("throws if the JSON has no version", () => {
+            expect(() => makeStyle({
+                settings: JSON.stringify({
+                    data: TextStyleSettings.defaultProps
+                }),
+            })).to.throw("JSON version is missing or invalid.");
+        });
+        it("throws if the JSON has no data", () => {
+            expect(() => makeStyle({
+                settings: JSON.stringify({
+                    version: TEXT_STYLE_SETTINGS_JSON_VERSION,
+                }),
+            })).to.throw("JSON data is missing or invalid.");
+        });
+        it("throws if the JSON version is too new", () => {
+            expect(() => makeStyle({
+                settings: JSON.stringify({
+                    version: "999.999.999",
+                    data: TextStyleSettings.defaultProps
+                }),
+            })).to.throw(`JSON version 999.999.999 is newer than supported version ${TEXT_STYLE_SETTINGS_JSON_VERSION}. Application update required to understand data.`);
+        });
+        it("throws if the JSON version is old and cannot be migrated", () => {
+            expect(() => makeStyle({
+                settings: JSON.stringify({
+                    version: "0.0.1",
+                    data: TextStyleSettings.defaultProps
+                }),
+            })).to.throw(`Migration for settings from version 0.0.1 to ${TEXT_STYLE_SETTINGS_JSON_VERSION} failed.`);
+        });
+    });
+});
+describe("appendTextAnnotationGeometry", () => {
+    let imodel;
+    let seedDefinitionModelId;
+    let seedCategoryId;
+    let seedStyleId;
+    let seedStyleId2;
+    before(async () => {
+        imodel = await createIModel("DefaultTextStyle");
+        const jobSubjectId = createJobSubjectElement(imodel, "Job").insert();
+        const definitionModel = DefinitionModel.insert(imodel, jobSubjectId, "Definition");
+        const { category, model } = insertDrawingModel(imodel, jobSubjectId, definitionModel);
+        const styleId = createAnnotationTextStyle(imodel, definitionModel, "test", { font: { name: "Totally Real Font" }, textHeight: 0.25, isItalic: true }).insert();
+        const differentStyleId = createAnnotationTextStyle(imodel, definitionModel, "alt", { font: { name: "Karla" }, textHeight: 0.5, isBold: true }).insert();
+        expect(jobSubjectId).not.to.be.undefined;
+        expect(definitionModel).not.to.be.undefined;
+        expect(category).not.to.be.undefined;
+        expect(model).not.to.be.undefined;
+        expect(styleId).not.to.be.undefined;
+        expect(differentStyleId).not.to.be.undefined;
+        seedDefinitionModelId = definitionModel;
+        seedCategoryId = category;
+        seedStyleId = styleId;
+        seedStyleId2 = differentStyleId;
+    });
+    function runAppendTextAnnotationGeometry(annotation, styleId, scaleFactor = 1) {
+        const builder = new MockBuilder();
+        const resolver = new TextStyleResolver({
+            textBlock: annotation.textBlock,
+            textStyleId: styleId,
+            iModel: imodel,
+        });
+        const layout = layoutTextBlock({
+            textBlock: annotation.textBlock,
+            iModel: imodel,
+            textStyleResolver: resolver,
+        });
+        const result = appendTextAnnotationGeometry({
+            annotationProps: annotation.toJSON(),
+            layout,
+            textStyleResolver: resolver,
+            scaleFactor,
+            builder,
+            categoryId: seedCategoryId,
+        });
+        expect(result).to.be.true;
+        return builder;
+    }
+    it("produces the same geometry when given the same inputs", () => {
+        const builder1 = runAppendTextAnnotationGeometry(createAnnotation(), seedStyleId);
+        const builder2 = runAppendTextAnnotationGeometry(createAnnotation(), seedStyleId);
+        expect(builder1.geometries).to.deep.equal(builder2.geometries);
+        expect(builder1.params).to.deep.equal(builder2.params);
+        expect(builder1.textStrings).to.deep.equal(builder2.textStrings);
+    });
+    it("produces no geometry when given an empty annotation", () => {
+        const block = TextBlock.create();
+        const annotation = TextAnnotation.fromJSON({ textBlock: block.toJSON() });
+        const builder = runAppendTextAnnotationGeometry(annotation, seedStyleId);
+        expect(builder.geometries).to.be.empty;
+        expect(builder.params).to.be.empty;
+        expect(builder.textStrings).to.be.empty;
+    });
+    it("produces geometry when given an empty annotation with frame styling", () => {
+        const block = TextBlock.create();
+        const annotation = TextAnnotation.fromJSON({ textBlock: block.toJSON() });
+        const styleId = createAnnotationTextStyle(imodel, seedDefinitionModelId, "empty anno style", {
+            font: { name: "Totally Real Font" },
+            frame: {
+                shape: "rectangle",
+            }
+        }).insert();
+        const builder = runAppendTextAnnotationGeometry(annotation, styleId);
+        expect(builder.geometries).not.to.be.empty;
+        expect(builder.params).not.to.be.empty;
+        expect(builder.textStrings).to.be.empty;
+    });
+    it("produces different geometry when given different text-content in annotations", () => {
+        const anno1 = createAnnotation();
+        const anno2 = createAnnotation();
+        anno2.textBlock.appendRun(TextRun.create({ content: "extra", styleOverrides: { font: { name: "Totally Real Font" } } }));
+        const builder1 = runAppendTextAnnotationGeometry(anno1, seedStyleId);
+        const builder2 = runAppendTextAnnotationGeometry(anno2, seedStyleId);
+        expect(builder1.geometries).to.not.deep.equal(builder2.geometries);
+        expect(builder1.params).to.deep.equal(builder2.params);
+        expect(builder1.textStrings).to.not.deep.equal(builder2.textStrings);
+    });
+    it("produces different geometry when given different default styles", () => {
+        const builder1 = runAppendTextAnnotationGeometry(createAnnotation(), seedStyleId);
+        const builder2 = runAppendTextAnnotationGeometry(createAnnotation(), seedStyleId2);
+        expect(builder1.geometries).to.not.deep.equal(builder2.geometries);
+        expect(builder1.textStrings).to.not.deep.equal(builder2.textStrings);
+    });
+    it("accounts for style overrides in the text", () => {
+        const block = TextBlock.create();
+        block.styleOverrides = { margins: { left: 0, right: 1, top: 2, bottom: 3 } };
+        block.appendParagraph();
+        block.children[0].styleOverrides = { isBold: true };
+        block.appendRun(TextRun.create({ content: "Run, Barry," }));
+        block.appendParagraph();
+        block.appendRun(TextRun.create({ content: " RUN!!! ", styleOverrides: { isItalic: false } }));
+        const annotation = createAnnotation(block);
+        const builder = runAppendTextAnnotationGeometry(annotation, seedStyleId);
+        expect(builder.textStrings.length).to.equal(2);
+        expect(builder.textStrings[0].text).to.equal("Run, Barry,");
+        // From override on paragraph
+        expect(builder.textStrings[0].bold).to.be.true;
+        // From default style
+        expect(builder.textStrings[0].italic).to.be.true;
+        expect(builder.textStrings[1].text).to.equal(" RUN!!! ");
+        // From default style
+        expect(builder.textStrings[1].bold).to.be.false;
+        // From override on run
+        expect(builder.textStrings[1].italic).to.be.false;
+    });
+    it("uses TextStyleSettings.defaults when no default style is provided", () => {
+        const block = TextBlock.create();
+        block.appendRun(TextRun.create({ content: "Run, Barry," }));
+        const annotation = createAnnotation(block);
+        const builder = runAppendTextAnnotationGeometry(annotation, "");
+        expect(builder.textStrings.length).to.equal(1);
+        expect(builder.textStrings[0].text).to.equal("Run, Barry,");
+        expect(builder.textStrings[0].font).to.equal(0); // Font ID 0 is the "missing" font in the default text style
+        expect(builder.textStrings[0].bold).to.equal(TextStyleSettings.defaultProps.isBold);
+        expect(builder.textStrings[0].italic).to.equal(TextStyleSettings.defaultProps.isItalic);
+        expect(builder.textStrings[0].underline).to.equal(TextStyleSettings.defaultProps.isUnderlined);
+    });
+    it("scales geometry correctly", () => {
+        const annotation = createAnnotation();
+        const builder1 = runAppendTextAnnotationGeometry(annotation, seedStyleId, 1);
+        const builder2 = runAppendTextAnnotationGeometry(annotation, seedStyleId, 2);
+        expect(builder1.textStrings[0].height * 2).to.equal(builder2.textStrings[0].height);
+        expect(builder1.textStrings[0].width * 2).to.equal(builder2.textStrings[0].width);
+    });
 });
 //# sourceMappingURL=TextAnnotation.test.js.map