@itwin/core-backend 5.3.0-dev.1 → 5.3.0-dev.12

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";
@@ -19,6 +19,7 @@ import { computeTextRangeAsStringLength, MockBuilder } from "../AnnotationTestUt
 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: {
@@ -30,13 +31,12 @@ function mockIModel() {
     return iModel;
 }
 function createAnnotation(textBlock) {
-    const styleOverrides = { fontName: "Karla" };
+    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 }));
-        block.margins = { left: 0, right: 1, top: 2, bottom: 3 };
     }
     const annotation = TextAnnotation.fromJSON({ textBlock: block.toJSON() });
     annotation.anchor = { vertical: "middle", horizontal: "right" };
@@ -83,8 +83,13 @@ 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 = {
@@ -124,13 +129,56 @@ describe("TextAnnotation element", () => {
             ...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().toJSON() }),
+                textAnnotationData: JSON.stringify({
+                    version: TEXT_ANNOTATION_JSON_VERSION,
+                    data: {
+                        textBlock: TextBlock.create().toJSON()
+                    }
+                }),
                 defaultTextStyle: new TextAnnotationUsesTextStyleByDefault("0x42").toJSON()
             });
             const anno = elem.getAnnotation();
@@ -141,7 +189,12 @@ describe("TextAnnotation element", () => {
         });
         it("produces a new object each time it is called", () => {
             const elem = makeElement({
-                textAnnotationData: JSON.stringify({ textBlock: TextBlock.create().toJSON() })
+                textAnnotationData: JSON.stringify({
+                    version: TEXT_ANNOTATION_JSON_VERSION,
+                    data: {
+                        textBlock: TextBlock.create().toJSON()
+                    }
+                }),
             });
             const anno1 = elem.getAnnotation();
             const anno2 = elem.getAnnotation();
@@ -160,6 +213,58 @@ 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 createElement3dArgs;
@@ -168,7 +273,7 @@ describe("TextAnnotation element", () => {
             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;
@@ -178,7 +283,7 @@ describe("TextAnnotation element", () => {
         after(() => imodel.close());
         it("creating element does not automatically compute the geometry", () => {
             const annotation = createAnnotation();
-            const args = { ...createElement3dArgs, 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;
@@ -239,7 +344,7 @@ describe("TextAnnotation element", () => {
         });
         it("creating element does not automatically compute the geometry", () => {
             const annotation = createAnnotation();
-            const args = { ...createElement2dArgs, 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;
@@ -289,8 +394,8 @@ describe("TextAnnotation element", () => {
             imodel = await createIModel("DefaultTextStyle");
             const jobSubjectId = createJobSubjectElement(imodel, "Job").insert();
             const definitionModel = DefinitionModel.insert(imodel, jobSubjectId, "Definition");
-            const styleId = createAnnotationTextStyle(imodel, definitionModel, "test", { fontName: "Totally Real Font", lineHeight: 0.25, isItalic: true }).insert();
-            const differentStyleId = createAnnotationTextStyle(imodel, definitionModel, "alt", { fontName: "Karla", lineHeight: 0.5, isBold: true }).insert();
+            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;
@@ -314,7 +419,7 @@ describe("TextAnnotation element", () => {
             });
             it("preserves defaultTextStyle after round trip", () => {
                 const annotation = createAnnotation();
-                const args = { ...createElement2dArgs, textAnnotationData: annotation.toJSON(), defaultTextStyleId: seedStyleId };
+                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);
@@ -327,7 +432,7 @@ describe("TextAnnotation element", () => {
             });
             it("produces different geometry when defaultTextStyle changes", () => {
                 const annotation = createAnnotation();
-                const args = { ...createElement2dArgs, textAnnotationData: annotation.toJSON() };
+                const args = { ...createElement2dArgs, textAnnotationProps: annotation.toJSON() };
                 const el0 = createElement2d(imodel, args);
                 el0.defaultTextStyle = new TextAnnotationUsesTextStyleByDefault(seedStyleId);
                 const geom1 = el0.toJSON().elementGeometryBuilderParams;
@@ -337,7 +442,7 @@ describe("TextAnnotation element", () => {
             });
             it("allows defaultTextStyle to be undefined", () => {
                 const annotation = createAnnotation();
-                const args = { ...createElement2dArgs, textAnnotationData: annotation.toJSON() };
+                const args = { ...createElement2dArgs, textAnnotationProps: annotation.toJSON() };
                 const el0 = createElement2d(imodel, args);
                 el0.defaultTextStyle = undefined;
                 const elId = el0.insert();
@@ -347,6 +452,178 @@ describe("TextAnnotation element", () => {
                 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;
@@ -358,7 +635,7 @@ describe("TextAnnotation element", () => {
             });
             it("preserves defaultTextStyle after round trip", () => {
                 const annotation = createAnnotation();
-                const args = { ...createElement3dArgs, textAnnotationData: annotation.toJSON(), defaultTextStyleId: seedStyleId };
+                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);
@@ -371,7 +648,7 @@ describe("TextAnnotation element", () => {
             });
             it("produces different geometry when defaultTextStyle changes", () => {
                 const annotation = createAnnotation();
-                const args = { ...createElement3dArgs, textAnnotationData: annotation.toJSON() };
+                const args = { ...createElement3dArgs, textAnnotationProps: annotation.toJSON() };
                 const el0 = createElement3d(imodel, args);
                 el0.defaultTextStyle = new TextAnnotationUsesTextStyleByDefault(seedStyleId);
                 const geom1 = el0.toJSON().elementGeometryBuilderParams;
@@ -381,7 +658,7 @@ describe("TextAnnotation element", () => {
             });
             it("allows defaultTextStyle to be undefined", () => {
                 const annotation = createAnnotation();
-                const args = { ...createElement3dArgs, textAnnotationData: annotation.toJSON() };
+                const args = { ...createElement3dArgs, textAnnotationProps: annotation.toJSON() };
                 const el0 = createElement3d(imodel, args);
                 el0.defaultTextStyle = undefined;
                 const elId = el0.insert();
@@ -412,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();
@@ -431,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();
@@ -468,12 +745,56 @@ 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;
@@ -486,8 +807,8 @@ describe("appendTextAnnotationGeometry", () => {
         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();
-        const differentStyleId = createAnnotationTextStyle(imodel, definitionModel, "alt", { fontName: "Karla", lineHeight: 0.5, isBold: true }).insert();
+        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;
@@ -541,7 +862,7 @@ describe("appendTextAnnotationGeometry", () => {
         const block = TextBlock.create();
         const annotation = TextAnnotation.fromJSON({ textBlock: block.toJSON() });
         const styleId = createAnnotationTextStyle(imodel, seedDefinitionModelId, "empty anno style", {
-            fontName: "Totally Real Font",
+            font: { name: "Totally Real Font" },
             frame: {
                 shape: "rectangle",
             }
@@ -554,7 +875,7 @@ describe("appendTextAnnotationGeometry", () => {
     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: { fontName: "Totally Real Font" } }));
+        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);
@@ -569,12 +890,12 @@ describe("appendTextAnnotationGeometry", () => {
     });
     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 } }));
-        block.margins = { left: 0, right: 1, top: 2, bottom: 3 };
         const annotation = createAnnotation(block);
         const builder = runAppendTextAnnotationGeometry(annotation, seedStyleId);
         expect(builder.textStrings.length).to.equal(2);
@@ -592,7 +913,6 @@ describe("appendTextAnnotationGeometry", () => {
     it("uses TextStyleSettings.defaults when no default style is provided", () => {
         const block = TextBlock.create();
         block.appendRun(TextRun.create({ content: "Run, Barry," }));
-        block.margins = { left: 0, right: 1, top: 2, bottom: 3 };
         const annotation = createAnnotation(block);
         const builder = runAppendTextAnnotationGeometry(annotation, "");
         expect(builder.textStrings.length).to.equal(1);