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

package/lib/esm/annotations/TextAnnotationElement.js

@@ -5,29 +5,65 @@
 /** @packageDocumentation
  * @module Elements
  */
-import { BisCodeSpec, Code, ElementGeometry, Placement2d, Placement3d, TextAnnotation, TextStyleSettings } from "@itwin/core-common";
-import { AnnotationElement2d, DefinitionElement, GraphicalElement3d } from "../Element";
-import { assert } from "@itwin/core-bentley";
+import { BisCodeSpec, Code, ElementGeometry, Placement2d, Placement3d, TextAnnotation, TextStyleSettings, traverseTextBlockComponent } from "@itwin/core-common";
+import { AnnotationElement2d, DefinitionElement, Drawing, GraphicalElement3d } from "../Element";
+import { assert, Id64 } from "@itwin/core-bentley";
 import { layoutTextBlock, TextStyleResolver } from "./TextBlockLayout";
 import { appendTextAnnotationGeometry } from "./TextAnnotationGeometry";
-import { ElementDrivesTextAnnotation } from "./ElementDrivesTextAnnotation";
-function parseTextAnnotationData(json) {
-    if (!json)
-        return undefined;
+import { ElementDrivesTextAnnotation, TextAnnotationUsesTextStyleByDefault } from "./ElementDrivesTextAnnotation";
+import * as semver from "semver";
+/** The version of the JSON stored in `TextAnnotation2d/3dProps.textAnnotationData` used by the code.
+ * Uses the same semantics as [ECVersion]($ecschema-metadata).
+ * @internal
+*/
+export const TEXT_ANNOTATION_JSON_VERSION = "1.0.0";
+function validateAndMigrateVersionedJSON(json, currentVersion, migrate) {
+    let parsed;
     try {
-        return JSON.parse(json);
+        parsed = JSON.parse(json);
     }
     catch {
         return undefined;
     }
+    const version = parsed.version;
+    if (typeof version !== "string" || !semver.valid(version))
+        throw new Error("JSON version is missing or invalid.");
+    if (typeof parsed.data !== "object" || parsed.data === null)
+        throw new Error("JSON data is missing or invalid.");
+    // Newer
+    if (semver.gt(version, currentVersion))
+        throw new Error(`JSON version ${parsed.version} is newer than supported version ${currentVersion}. Application update required to understand data.`);
+    // Older
+    if (semver.lt(version, currentVersion)) {
+        parsed.data = migrate(parsed);
+        parsed.version = currentVersion;
+    }
+    return parsed;
+}
+function migrateTextAnnotationData(oldData) {
+    if (oldData.version === TEXT_ANNOTATION_JSON_VERSION)
+        return oldData.data;
+    // Place migration logic here.
+    throw new Error(`Migration for textAnnotationData from version ${oldData.version} to ${TEXT_ANNOTATION_JSON_VERSION} failed.`);
+}
+/** Parses, validates, and potentially migrates the text annotation data from a JSON string.
+ * @internal
+ */
+export function parseTextAnnotationData(json) {
+    if (!json)
+        return undefined;
+    return validateAndMigrateVersionedJSON(json, TEXT_ANNOTATION_JSON_VERSION, migrateTextAnnotationData);
 }
-function getElementGeometryBuilderParams(iModel, modelId, _placementProps, stringifiedAnnotationProps, categoryId, _subCategory) {
-    const annotationProps = parseTextAnnotationData(stringifiedAnnotationProps);
+function getElementGeometryBuilderParams(iModel, modelId, categoryId, _placementProps, annotationProps, textStyleId, _subCategory) {
     const textBlock = TextAnnotation.fromJSON(annotationProps).textBlock;
-    const textStyleResolver = new TextStyleResolver({ textBlock, iModel, modelId });
+    const textStyleResolver = new TextStyleResolver({ textBlock, textStyleId: textStyleId ?? "", iModel });
     const layout = layoutTextBlock({ iModel, textBlock, textStyleResolver });
     const builder = new ElementGeometry.Builder();
-    appendTextAnnotationGeometry({ layout, textStyleResolver, annotationProps: annotationProps ?? {}, builder, categoryId });
+    let scaleFactor = 1;
+    const element = iModel.elements.getElement(modelId);
+    if (element instanceof Drawing)
+        scaleFactor = element.scaleFactor;
+    appendTextAnnotationGeometry({ layout, textStyleResolver, scaleFactor, annotationProps: annotationProps ?? {}, builder, categoryId });
     return { entryArray: builder.entries };
 }
 /** An element that displays textual content within a 2d model.
@@ -38,25 +74,32 @@ function getElementGeometryBuilderParams(iModel, modelId, _placementProps, strin
 export class TextAnnotation2d extends AnnotationElement2d /* implements ITextAnnotation */ {
     /** @internal */
     static get className() { return "TextAnnotation2d"; }
-    /** Optional string containing the data associated with the text annotation. */
-    _textAnnotationData;
+    /**
+     * The default [[AnnotationTextStyle]] used by the TextAnnotation2d.
+     * @beta
+     */
+    defaultTextStyle;
+    /** The data associated with the text annotation. */
+    _textAnnotationProps;
     /** Extract the textual content, if present.
      * @see [[setAnnotation]] to change it.
      */
     getAnnotation() {
-        const textAnnotationProps = parseTextAnnotationData(this._textAnnotationData);
-        return textAnnotationProps ? TextAnnotation.fromJSON(textAnnotationProps) : undefined;
+        return this._textAnnotationProps ? TextAnnotation.fromJSON(this._textAnnotationProps) : undefined;
     }
     /** Change the textual content of the `TextAnnotation2d`.
      * @see [[getAnnotation]] to extract the current annotation.
      * @param annotation The new annotation
      */
     setAnnotation(annotation) {
-        this._textAnnotationData = annotation ? JSON.stringify(annotation.toJSON()) : undefined;
+        this._textAnnotationProps = annotation.toJSON();
     }
     constructor(props, iModel) {
         super(props, iModel);
-        this._textAnnotationData = props.textAnnotationData;
+        if (props.defaultTextStyle) {
+            this.defaultTextStyle = new TextAnnotationUsesTextStyleByDefault(props.defaultTextStyle.id);
+        }
+        this._textAnnotationProps = parseTextAnnotationData(props.textAnnotationData)?.data;
     }
     /** Creates a new instance of `TextAnnotation2d` from its JSON representation. */
     static fromJSON(props, iModel) {
@@ -65,76 +108,96 @@ export class TextAnnotation2d extends AnnotationElement2d /* implements ITextAnn
     /**
      * Converts the current `TextAnnotation2d` instance to its JSON representation.
      * It also computes the `elementGeometryBuilderParams` property used to create the GeometryStream.
-  
      * @inheritdoc
      */
     toJSON() {
         const props = super.toJSON();
-        props.textAnnotationData = this._textAnnotationData;
-        if (this._textAnnotationData) {
-            props.elementGeometryBuilderParams = getElementGeometryBuilderParams(this.iModel, this.model, this.placement, this._textAnnotationData, this.category);
+        props.textAnnotationData = this._textAnnotationProps ? JSON.stringify({ version: TEXT_ANNOTATION_JSON_VERSION, data: this._textAnnotationProps }) : undefined;
+        if (this._textAnnotationProps) {
+            props.elementGeometryBuilderParams = getElementGeometryBuilderParams(this.iModel, this.model, this.category, this.placement, this._textAnnotationProps, this.defaultTextStyle ? this.defaultTextStyle.id : undefined);
         }
         return props;
     }
     /** Creates a new `TextAnnotation2d` instance with the specified properties.
      * @param iModelDb The iModel.
-     * @param category The category ID for the annotation.
-     * @param model The model ID where the annotation will be placed.
-     * @param placement The placement properties for the annotation.
-     * @param textAnnotationData Optional [[TextAnnotation]] JSON representation used to create the `TextAnnotation2d`. Essentially an empty element if not provided.
-     * @param code Optional code for the element.
+     * @param arg The arguments for creating the TextAnnotation2d.
+     * @beta
      */
-    static create(iModelDb, category, model, placement, textAnnotationData, code) {
-        const props = {
+    static create(iModelDb, arg) {
+        const elementProps = {
             classFullName: this.classFullName,
-            textAnnotationData: JSON.stringify(textAnnotationData),
-            placement,
-            model,
-            category,
-            code: code ?? Code.createEmpty(),
+            textAnnotationData: arg.textAnnotationProps ? JSON.stringify({ version: TEXT_ANNOTATION_JSON_VERSION, data: arg.textAnnotationProps }) : undefined,
+            defaultTextStyle: arg.defaultTextStyleId ? new TextAnnotationUsesTextStyleByDefault(arg.defaultTextStyleId).toJSON() : undefined,
+            placement: arg.placement,
+            model: arg.model,
+            category: arg.category,
+            code: arg.code ?? Code.createEmpty(),
         };
-        return new this(props, iModelDb);
+        return new this(elementProps, iModelDb);
     }
     /**
-     * Updates the geometry of the TextAnnotation2d on insert.
+     * Updates the geometry of the TextAnnotation2d on insert and validates version.
      * @inheritdoc
      * @beta
      */
     static onInsert(arg) {
         super.onInsert(arg);
-        this.updateGeometry(arg.iModel, arg.props);
+        this.validateVersionAndUpdateGeometry(arg);
     }
     /**
-     * Updates the geometry of the TextAnnotation2d on update.
+     * Updates the geometry of the TextAnnotation2d on update and validates version.
      * @inheritdoc
      * @beta
      */
     static onUpdate(arg) {
         super.onUpdate(arg);
-        this.updateGeometry(arg.iModel, arg.props);
+        this.validateVersionAndUpdateGeometry(arg);
     }
     /**
      * Populates the `elementGeometryBuilderParams` property in the [TextAnnotation2dProps]($common).
-     * It only does this if the `elementGeometryBuilderParams` is not already set and if there is actually a text annotation to produce geometry for.
+     * Only does this if the `elementGeometryBuilderParams` is not already set and if there is actually a text annotation to produce geometry for.
+     * Also, validates the version of the text annotation data and migrates it if necessary.
+     * @beta
      */
-    static updateGeometry(iModelDb, props) {
-        if (props.elementGeometryBuilderParams || !props.textAnnotationData) {
-            return;
+    static validateVersionAndUpdateGeometry(arg) {
+        const props = arg.props;
+        const textAnnotationData = parseTextAnnotationData(props.textAnnotationData);
+        if (!props.elementGeometryBuilderParams && textAnnotationData) {
+            props.elementGeometryBuilderParams = getElementGeometryBuilderParams(arg.iModel, props.model, props.category, props.placement ?? Placement2d.fromJSON(), textAnnotationData.data, props.defaultTextStyle?.id);
         }
-        props.elementGeometryBuilderParams = getElementGeometryBuilderParams(iModelDb, props.model, props.placement ?? Placement2d.fromJSON(), props.textAnnotationData, props.category);
     }
     /**
-     * Collects reference IDs used by this `TextAnnotation2d`.
+     * TextAnnotation2d custom HandledProps include 'textAnnotationData'.
      * @inheritdoc
+     * @internal
      */
-    collectReferenceIds(ids) {
-        super.collectReferenceIds(ids);
-        const annotation = this.getAnnotation();
-        if (!annotation) {
-            return;
+    static _customHandledProps = [
+        { propertyName: "textAnnotationData", source: "Class" },
+    ];
+    /**
+     * TextAnnotation2d deserializes 'textAnnotationData'.
+     * @inheritdoc
+     * @beta
+     */
+    static deserialize(props) {
+        const elProps = super.deserialize(props);
+        const textAnnotationData = parseTextAnnotationData(props.row.textAnnotationData);
+        if (textAnnotationData) {
+            elProps.textAnnotationData = JSON.stringify(textAnnotationData);
+        }
+        return elProps;
+    }
+    /**
+     * TextAnnotation2d serializes 'textAnnotationData'.
+     * @inheritdoc
+     * @beta
+     */
+    static serialize(props, iModel) {
+        const inst = super.serialize(props, iModel);
+        if (props.textAnnotationData !== undefined) {
+            inst.textAnnotationData = props.textAnnotationData;
         }
-        if (annotation.textBlock.styleId)
-            ids.addElement(annotation.textBlock.styleId);
+        return inst;
     }
     /** @internal */
     getTextBlocks() {
@@ -154,6 +217,19 @@ export class TextAnnotation2d extends AnnotationElement2d /* implements ITextAnn
         super.onUpdated(arg);
         ElementDrivesTextAnnotation.updateFieldDependencies(arg.id, arg.iModel);
     }
+    collectReferenceIds(referenceIds) {
+        super.collectReferenceIds(referenceIds);
+        collectReferenceIds(this, referenceIds);
+    }
+    /** @internal */
+    static onCloned(context, srcProps, dstProps) {
+        super.onCloned(context, srcProps, dstProps);
+        const srcElem = TextAnnotation2d.fromJSON(srcProps, context.sourceDb);
+        ElementDrivesTextAnnotation.remapFields(srcElem, context);
+        const anno = srcElem.getAnnotation();
+        dstProps.textAnnotationData = anno ? JSON.stringify({ version: TEXT_ANNOTATION_JSON_VERSION, data: anno.toJSON() }) : undefined;
+        remapTextStyle(context, srcElem, dstProps);
+    }
 }
 /** An element that displays textual content within a 3d model.
  * The text is stored as a [TextAnnotation]($common) from which the element's [geometry]($docs/learning/common/GeometryStream.md) and [Placement]($common) are computed.
@@ -163,25 +239,32 @@ export class TextAnnotation2d extends AnnotationElement2d /* implements ITextAnn
 export class TextAnnotation3d extends GraphicalElement3d /* implements ITextAnnotation */ {
     /** @internal */
     static get className() { return "TextAnnotation3d"; }
-    /** Optional string containing the data associated with the text annotation. */
-    _textAnnotationData;
+    /**
+     * The default [[AnnotationTextStyle]] used by the TextAnnotation3d.
+     * @beta
+     */
+    defaultTextStyle;
+    /** The data associated with the text annotation. */
+    _textAnnotationProps;
     /** Extract the textual content, if present.
      * @see [[setAnnotation]] to change it.
      */
     getAnnotation() {
-        const textAnnotationProps = parseTextAnnotationData(this._textAnnotationData);
-        return textAnnotationProps ? TextAnnotation.fromJSON(textAnnotationProps) : undefined;
+        return this._textAnnotationProps ? TextAnnotation.fromJSON(this._textAnnotationProps) : undefined;
     }
     /** Change the textual content of the `TextAnnotation3d`.
      * @see [[getAnnotation]] to extract the current annotation.
      * @param annotation The new annotation
      */
     setAnnotation(annotation) {
-        this._textAnnotationData = annotation ? JSON.stringify(annotation.toJSON()) : undefined;
+        this._textAnnotationProps = annotation.toJSON();
     }
     constructor(props, iModel) {
         super(props, iModel);
-        this._textAnnotationData = props.textAnnotationData;
+        if (props.defaultTextStyle) {
+            this.defaultTextStyle = new TextAnnotationUsesTextStyleByDefault(props.defaultTextStyle.id);
+        }
+        this._textAnnotationProps = parseTextAnnotationData(props.textAnnotationData)?.data;
     }
     /** Creates a new instance of `TextAnnotation3d` from its JSON representation. */
     static fromJSON(props, iModel) {
@@ -194,71 +277,92 @@ export class TextAnnotation3d extends GraphicalElement3d /* implements ITextAnno
      */
     toJSON() {
         const props = super.toJSON();
-        props.textAnnotationData = this._textAnnotationData;
-        if (this._textAnnotationData) {
-            props.elementGeometryBuilderParams = getElementGeometryBuilderParams(this.iModel, this.model, this.placement, this._textAnnotationData, this.category);
+        props.textAnnotationData = this._textAnnotationProps ? JSON.stringify({ version: TEXT_ANNOTATION_JSON_VERSION, data: this._textAnnotationProps }) : undefined;
+        if (this._textAnnotationProps) {
+            props.elementGeometryBuilderParams = getElementGeometryBuilderParams(this.iModel, this.model, this.category, this.placement, this._textAnnotationProps, this.defaultTextStyle ? this.defaultTextStyle.id : undefined);
         }
         return props;
     }
     /** Creates a new `TextAnnotation3d` instance with the specified properties.
      * @param iModelDb The iModel.
-     * @param category The category ID for the annotation.
-     * @param model The model ID where the annotation will be placed.
-     * @param placement The placement properties for the annotation.
-     * @param textAnnotationData Optional [[TextAnnotation]] JSON representation used to create the `TextAnnotation3d`. Essentially an empty element if not provided.
-     * @param code Optional code for the element.
+     * @param arg The arguments for creating the TextAnnotation3d.
+     * @beta
      */
-    static create(iModelDb, category, model, placement, textAnnotationData, code) {
-        const props = {
+    static create(iModelDb, arg) {
+        const elementProps = {
             classFullName: this.classFullName,
-            textAnnotationData: JSON.stringify(textAnnotationData),
-            placement,
-            model,
-            category,
-            code: code ?? Code.createEmpty(),
+            textAnnotationData: arg.textAnnotationProps ? JSON.stringify({ version: TEXT_ANNOTATION_JSON_VERSION, data: arg.textAnnotationProps }) : undefined,
+            defaultTextStyle: arg.defaultTextStyleId ? new TextAnnotationUsesTextStyleByDefault(arg.defaultTextStyleId).toJSON() : undefined,
+            placement: arg.placement,
+            model: arg.model,
+            category: arg.category,
+            code: arg.code ?? Code.createEmpty(),
         };
-        return new this(props, iModelDb);
+        return new this(elementProps, iModelDb);
     }
     /**
-     * Updates the geometry of the TextAnnotation3d on insert.
+     * Updates the geometry of the TextAnnotation3d on insert and validates version..
      * @inheritdoc
      * @beta
      */
     static onInsert(arg) {
         super.onInsert(arg);
-        this.updateGeometry(arg.iModel, arg.props);
+        this.validateVersionAndUpdateGeometry(arg);
     }
     /**
-     * Updates the geometry of the TextAnnotation3d on update.
+     * Updates the geometry of the TextAnnotation3d on update and validates version..
      * @inheritdoc
      * @beta
      */
     static onUpdate(arg) {
         super.onUpdate(arg);
-        this.updateGeometry(arg.iModel, arg.props);
+        this.validateVersionAndUpdateGeometry(arg);
     }
     /**
      * Populates the `elementGeometryBuilderParams` property in the [TextAnnotation3dProps]($common).
-     * It only does this if the `elementGeometryBuilderParams` is not already set and if there is actually a text annotation to produce geometry for.
+     * Only does this if the `elementGeometryBuilderParams` is not already set and if there is actually a text annotation to produce geometry for.
+     * Also, validates the version of the text annotation data and migrates it if necessary.
+     * @beta
      */
-    static updateGeometry(iModelDb, props) {
-        if (props.elementGeometryBuilderParams || !props.textAnnotationData) {
-            return;
+    static validateVersionAndUpdateGeometry(arg) {
+        const props = arg.props;
+        const textAnnotationData = parseTextAnnotationData(props.textAnnotationData);
+        if (!props.elementGeometryBuilderParams && textAnnotationData) {
+            props.elementGeometryBuilderParams = getElementGeometryBuilderParams(arg.iModel, props.model, props.category, props.placement ?? Placement3d.fromJSON(), textAnnotationData.data, props.defaultTextStyle?.id);
         }
-        props.elementGeometryBuilderParams = getElementGeometryBuilderParams(iModelDb, props.model, props.placement ?? Placement3d.fromJSON(), props.textAnnotationData, props.category);
     }
     /**
-     * Collects reference IDs used by this `TextAnnotation3d`.
+     * TextAnnotation3d custom HandledProps include 'textAnnotationData'.
      * @inheritdoc
+     * @internal
      */
-    collectReferenceIds(ids) {
-        super.collectReferenceIds(ids);
-        const annotation = this.getAnnotation();
-        if (!annotation) {
-            return;
+    static _customHandledProps = [
+        { propertyName: "textAnnotationData", source: "Class" },
+    ];
+    /**
+     * TextAnnotation3d deserializes 'textAnnotationData'.
+     * @inheritdoc
+     * @beta
+     */
+    static deserialize(props) {
+        const elProps = super.deserialize(props);
+        const textAnnotationData = parseTextAnnotationData(props.row.textAnnotationData);
+        if (textAnnotationData) {
+            elProps.textAnnotationData = JSON.stringify(textAnnotationData);
+        }
+        return elProps;
+    }
+    /**
+     * TextAnnotation3d serializes 'textAnnotationData'.
+     * @inheritdoc
+     * @beta
+     */
+    static serialize(props, iModel) {
+        const inst = super.serialize(props, iModel);
+        if (props.textAnnotationData !== undefined) {
+            inst.textAnnotationData = props.textAnnotationData;
         }
-        if (annotation.textBlock.styleId)
-            ids.addElement(annotation.textBlock.styleId);
+        return inst;
     }
     /** @internal */
     getTextBlocks() {
@@ -278,6 +382,40 @@ export class TextAnnotation3d extends GraphicalElement3d /* implements ITextAnno
         super.onUpdated(arg);
         ElementDrivesTextAnnotation.updateFieldDependencies(arg.id, arg.iModel);
     }
+    collectReferenceIds(referenceIds) {
+        super.collectReferenceIds(referenceIds);
+        collectReferenceIds(this, referenceIds);
+    }
+    /** @internal */
+    static onCloned(context, srcProps, dstProps) {
+        super.onCloned(context, srcProps, dstProps);
+        const srcElem = TextAnnotation3d.fromJSON(srcProps, context.sourceDb);
+        ElementDrivesTextAnnotation.remapFields(srcElem, context);
+        const anno = srcElem.getAnnotation();
+        dstProps.textAnnotationData = anno ? JSON.stringify({ version: TEXT_ANNOTATION_JSON_VERSION, data: anno.toJSON() }) : undefined;
+        remapTextStyle(context, srcElem, dstProps);
+    }
+}
+function remapTextStyle(context, srcElem, dstProps) {
+    const dstStyleId = AnnotationTextStyle.remapTextStyleId(srcElem.defaultTextStyle?.id ?? Id64.invalid, context);
+    dstProps.defaultTextStyle = Id64.isValid(dstStyleId) ? new TextAnnotationUsesTextStyleByDefault(dstStyleId).toJSON() : undefined;
+}
+function collectReferenceIds(elem, referenceIds) {
+    const style = elem.defaultTextStyle?.id;
+    if (style && Id64.isValidId64(style)) {
+        referenceIds.addElement(style);
+    }
+    const block = elem.getAnnotation()?.textBlock;
+    if (block) {
+        for (const { child } of traverseTextBlockComponent(block)) {
+            if (child.type === "field") {
+                const hostId = child.propertyHost.elementId;
+                if (Id64.isValidId64(hostId)) {
+                    referenceIds.addElement(hostId);
+                }
+            }
+        }
+    }
 }
 function getTextBlocks(elem) {
     const annotation = elem.getAnnotation();
@@ -294,7 +432,17 @@ function updateTextBlocks(elem, textBlocks) {
     }
     annotation.textBlock = textBlocks[0].textBlock;
     elem.setAnnotation(annotation);
-    elem.update();
+}
+/** The version of the JSON stored in `AnnotationTextStyleProps.settings` used by the code.
+ * Uses the same semantics as [ECVersion]($ecschema-metadata).
+ * @internal
+*/
+export const TEXT_STYLE_SETTINGS_JSON_VERSION = "1.0.0";
+function migrateTextStyleSettings(oldData) {
+    if (oldData.version === TEXT_STYLE_SETTINGS_JSON_VERSION)
+        return oldData.data;
+    // Place migration logic here.
+    throw new Error(`Migration for settings from version ${oldData.version} to ${TEXT_STYLE_SETTINGS_JSON_VERSION} failed.`);
 }
 /**
  * The definition element that holds text style information.
@@ -317,7 +465,7 @@ export class AnnotationTextStyle extends DefinitionElement {
         super(props, iModel);
         this.description = props.description;
         const settingsProps = AnnotationTextStyle.parseTextStyleSettings(props.settings);
-        this.settings = TextStyleSettings.fromJSON(settingsProps);
+        this.settings = TextStyleSettings.fromJSON(settingsProps?.data);
     }
     /**
      * Creates a Code for an `AnnotationTextStyle` given a name that is meant to be unique within the scope of the specified DefinitionModel.
@@ -325,6 +473,7 @@ export class AnnotationTextStyle extends DefinitionElement {
      * @param iModel - The IModelDb.
      * @param definitionModelId - The ID of the DefinitionModel that contains the AnnotationTextStyle and provides the scope for its name.
      * @param name - The AnnotationTextStyle name.
+     * @beta
      */
     static createCode(iModel, definitionModelId, name) {
         const codeSpec = iModel.codeSpecs.getByName(BisCodeSpec.annotationTextStyle);
@@ -334,18 +483,16 @@ export class AnnotationTextStyle extends DefinitionElement {
      * Creates a new instance of `AnnotationTextStyle` with the specified properties.
      *
      * @param iModelDb - The iModelDb.
-     * @param definitionModelId - The ID of the [[DefinitionModel]].
-     * @param name - The name to assign to the `AnnotationTextStyle`.
-     * @param settings - Optional text style settings used to create the `AnnotationTextStyle`. Default settings will be used if not provided.
-     * @param description - Optional description for the `AnnotationTextStyle`.
+     * @param arg - The arguments for creating the AnnotationTextStyle.
+     * @beta
      */
-    static create(iModelDb, definitionModelId, name, settings, description) {
+    static create(iModelDb, arg) {
         const props = {
             classFullName: this.classFullName,
-            model: definitionModelId,
-            code: this.createCode(iModelDb, definitionModelId, name).toJSON(),
-            description,
-            settings: JSON.stringify(settings),
+            model: arg.definitionModelId,
+            code: this.createCode(iModelDb, arg.definitionModelId, arg.name).toJSON(),
+            description: arg.description,
+            settings: arg.settings ? JSON.stringify({ version: TEXT_STYLE_SETTINGS_JSON_VERSION, data: arg.settings }) : undefined,
         };
         return new this(props, iModelDb);
     }
@@ -356,7 +503,7 @@ export class AnnotationTextStyle extends DefinitionElement {
     toJSON() {
         const props = super.toJSON();
         props.description = this.description;
-        props.settings = JSON.stringify(this.settings.toJSON());
+        props.settings = JSON.stringify({ version: TEXT_STYLE_SETTINGS_JSON_VERSION, data: this.settings.toJSON() });
         return props;
     }
     /** Creates a new instance of `AnnotationTextStyle` from its JSON representation. */
@@ -385,21 +532,83 @@ export class AnnotationTextStyle extends DefinitionElement {
         const settingProps = AnnotationTextStyle.parseTextStyleSettings(props.settings);
         if (!settingProps)
             return;
-        const settings = TextStyleSettings.fromJSON(settingProps);
+        const settings = TextStyleSettings.fromJSON(settingProps.data);
         const errors = settings.getValidationErrors();
         if (errors.length > 0) {
             throw new Error(`Invalid AnnotationTextStyle settings: ${errors.join(", ")}`);
         }
     }
+    /**
+     * AnnotationTextStyle custom HandledProps include 'settings'.
+     * @inheritdoc
+     * @beta
+     */
+    static _customHandledProps = [
+        { propertyName: "settings", source: "Class" },
+    ];
+    /**
+     * AnnotationTextStyle deserializes 'settings'.
+     * @inheritdoc
+     * @beta
+     */
+    static deserialize(props) {
+        const elProps = super.deserialize(props);
+        const settings = this.parseTextStyleSettings(props.row.settings);
+        if (settings) {
+            elProps.settings = JSON.stringify(settings);
+        }
+        return elProps;
+    }
+    /**
+     * AnnotationTextStyle serializes 'settings'.
+     * @inheritdoc
+     * @beta
+     */
+    static serialize(props, iModel) {
+        const inst = super.serialize(props, iModel);
+        if (props.settings !== undefined) {
+            inst.settings = props.settings;
+        }
+        return inst;
+    }
+    /** Parses, validates, and potentially migrates the text style settings data from a JSON string. */
     static parseTextStyleSettings(json) {
         if (!json)
             return undefined;
-        try {
-            return JSON.parse(json);
+        return validateAndMigrateVersionedJSON(json, TEXT_STYLE_SETTINGS_JSON_VERSION, migrateTextStyleSettings);
+    }
+    /** When copying an element from one iModel to another, returns the Id of the AnnotationTextStyle in the `context`'s target iModel
+     * corresponding to `sourceTextStyleId`, or [Id64.invalid]($bentley) if no corresponding text style exists.
+     * If a text style with the same [Code]($common) exists in the target iModel, the style Id will be remapped to refer to that style.
+     * Otherwise, a copy of the style will be imported into the target iModel and its element Id returned.
+     * Implementations of [[ITextAnnotation]] should invoke this function when implementing their [[Element._onCloned]] method.
+     * @throws Error if an attempt to import the text style failed.
+     */
+    static remapTextStyleId(sourceTextStyleId, context) {
+        // No remapping necessary if there's no text style or we're not copying to a different iModel.
+        if (!Id64.isValid(sourceTextStyleId) || !context.isBetweenIModels) {
+            return sourceTextStyleId;
         }
-        catch {
-            return undefined;
+        // If the style's already been remapped, we're finished.
+        let dstStyleId = context.findTargetElementId(sourceTextStyleId);
+        if (Id64.isValid(dstStyleId)) {
+            return dstStyleId;
+        }
+        // Look up the style. It really ought to exist.
+        const srcStyle = context.sourceDb.elements.tryGetElement(sourceTextStyleId);
+        if (!srcStyle) {
+            return Id64.invalid;
+        }
+        // If a style with the same code exists in the target iModel, remap to that one.
+        dstStyleId = context.targetDb.elements.queryElementIdByCode(srcStyle.code);
+        if (undefined !== dstStyleId) {
+            return dstStyleId;
         }
+        // Copy the style into the target iModel and remap its Id.
+        const dstStyleProps = context.cloneElement(srcStyle);
+        dstStyleId = context.targetDb.elements.insertElement(dstStyleProps);
+        context.remapElement(sourceTextStyleId, dstStyleId);
+        return dstStyleId;
     }
 }
 //# sourceMappingURL=TextAnnotationElement.js.map