@itwin/core-backend 5.3.0-dev.2 → 5.3.0-dev.4

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

@@ -6,7 +6,7 @@ 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 { StandaloneDb } from "../../IModelDb";
-import { AnnotationTextStyle, TextAnnotation2d, TextAnnotation3d } from "../../annotations/TextAnnotationElement";
+import { AnnotationTextStyle, 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";
@@ -30,13 +30,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 +82,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 +128,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 +188,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();
@@ -168,7 +220,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 +230,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 +291,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 +341,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 +366,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 +379,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 +389,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();
@@ -358,7 +410,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 +423,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 +433,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 +464,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 +483,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 +520,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 +582,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 +637,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 +650,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 +665,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 +688,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);