@itwin/core-common 5.2.0-dev.8 → 5.2.0

package/lib/esm/annotation/TextBlock.js

@@ -5,26 +5,36 @@
 /** @packageDocumentation
  * @module Annotation
  */
-import { TextStyleSettings } from "./TextStyle";
-/** Abstract representation of any of the building blocks that make up a [[TextBlock]] document - namely [[Run]]s, [[Paragraph]]s, and [[TextBlock]] itself.
- * The [[TextBlock]] can specify an [AnnotationTextStyle]($backend) that formats its contents. Each component can specify an optional [[styleOverrides]] to customize that formatting.
+import { ListMarkerEnumerator, TextStyleSettings } from "./TextStyle";
+function clearStyleOverrides(component, options) {
+    component.styleOverrides = {};
+    if (!options?.preserveChildrenOverrides) {
+        for (const child of component.children) {
+            child.clearStyleOverrides(options);
+        }
+    }
+}
+/**
+ * Abstract representation of any of the building blocks that make up a [[TextBlock]] document - namely [[Run]]s and [[StructuralTextBlockComponent]]s.
+ * The [[TextBlock]] can specify an [AnnotationTextStyle]($backend) that formats its contents.
+ * Each component can specify an optional [[styleOverrides]] to customize that formatting.
  * @beta
  */
 export class TextBlockComponent {
     _styleOverrides;
     /** @internal */
     constructor(props) {
-        this._styleOverrides = TextStyleSettings.cloneProps(props?.styleOverrides ?? {});
+        this._styleOverrides = structuredClone(props?.styleOverrides ?? {});
     }
-    /** Deviations in individual properties of the [[TextStyleSettings]] in the [AnnotationTextStyle]($backend) specified by `styleId` on the [[TextBlock]].
-     * For example, if the style uses the "Arial" font, you can override that by settings `styleOverrides.fontName` to "Comic Sans".
+    /** Deviations in individual properties of the [[TextStyleSettings]] in the [AnnotationTextStyle]($backend).
+     * For example, if the style uses the "Arial" font, you can override that by settings `styleOverrides.font.name` to "Comic Sans".
      * @see [[clearStyleOverrides]] to reset this to an empty object.
      */
     get styleOverrides() {
         return this._styleOverrides;
     }
     set styleOverrides(overrides) {
-        this._styleOverrides = TextStyleSettings.cloneProps(overrides);
+        this._styleOverrides = structuredClone(overrides);
     }
     /** Reset any [[styleOverrides]] applied to this component. */
     clearStyleOverrides(_options) {
@@ -45,23 +55,14 @@ export class TextBlockComponent {
     /** Convert this component to its JSON representation. */
     toJSON() {
         return {
-            styleOverrides: TextStyleSettings.cloneProps(this.styleOverrides),
+            styleOverrides: structuredClone(this.styleOverrides),
         };
     }
     /** Returns true if `this` is equivalent to `other`. */
     equals(other) {
-        const myKeys = Object.keys(this.styleOverrides);
-        const yrKeys = Object.keys(other._styleOverrides);
-        if (myKeys.length !== yrKeys.length) {
-            return false;
-        }
-        for (const name of myKeys) {
-            const key = name;
-            if (this.styleOverrides[key] !== other.styleOverrides[key]) {
-                return false;
-            }
-        }
-        return true;
+        const mySettings = TextStyleSettings.fromJSON(this.styleOverrides);
+        const otherSettings = TextStyleSettings.fromJSON(other.styleOverrides);
+        return mySettings.equals(otherSettings);
     }
 }
 /** A sequence of characters within a [[Paragraph]] that share a single style. Runs are the leaf nodes of a [[TextBlock]] document. When laid out for display, a single run may span
@@ -72,15 +73,15 @@ export class TextBlockComponent {
 export var Run;
 (function (Run) {
     /** Create a run from its JSON representation.
-     * @see [[TextRun.create]], [[FractionRun.create]], and [[LineBreakRun.create]] to create a run directly.
+     * @see [[TextRun.create]], [[FractionRun.create]], [[FieldRun.create]], [[TabRun.create]], and [[LineBreakRun.create]] to create a run directly.
      */
     function fromJSON(props) {
         switch (props.type) {
-            case "text": return TextRun.create(props);
+            case "field": return FieldRun.create(props);
             case "fraction": return FractionRun.create(props);
-            case "tab": return TabRun.create(props);
             case "linebreak": return LineBreakRun.create(props);
-            case "field": return FieldRun.create(props);
+            case "tab": return TabRun.create(props);
+            case "text": return TextRun.create(props);
         }
     }
     Run.fromJSON = fromJSON;
@@ -112,7 +113,10 @@ export class TextRun extends TextBlockComponent {
         };
     }
     static create(props) {
-        return new TextRun(props);
+        return new TextRun({ ...props, type: "text" });
+    }
+    get isEmpty() {
+        return this.stringify().length === 0;
     }
     /** Simply returns [[content]]. */
     stringify() {
@@ -150,7 +154,10 @@ export class FractionRun extends TextBlockComponent {
         return new FractionRun(this.toJSON());
     }
     static create(props) {
-        return new FractionRun(props);
+        return new FractionRun({ ...props, type: "fraction" });
+    }
+    get isEmpty() {
+        return this.stringify().length === 0;
     }
     /** Formats the fraction as a string with the [[numerator]] and [[denominator]] separated by [[TextBlockStringifyOptions.fractionSeparator]]. */
     stringify(options) {
@@ -177,11 +184,14 @@ export class LineBreakRun extends TextBlockComponent {
         };
     }
     static create(props) {
-        return new LineBreakRun(props);
+        return new LineBreakRun({ ...props, type: "linebreak" });
     }
     clone() {
         return new LineBreakRun(this.toJSON());
     }
+    get isEmpty() {
+        return this.stringify().length === 0;
+    }
     /** Simply returns [[TextBlockStringifyOptions.lineBreak]]. */
     stringify(options) {
         return options?.lineBreak ?? " ";
@@ -209,6 +219,9 @@ export class TabRun extends TextBlockComponent {
     static create(props) {
         return new TabRun(props);
     }
+    get isEmpty() {
+        return this.stringify().length === 0;
+    }
     /**
    * Converts a [[TabRun]] to its string representation.
    * If the `tabsAsSpaces` option is provided, returns a string of spaces of the specified length.
@@ -227,7 +240,8 @@ export class TabRun extends TextBlockComponent {
 /** A [[Run]] that displays the formatted value of a property of some [Element]($backend).
  * When a [[TextBlock]] containing a [[FieldRun]] is written into the iModel as an [ITextAnnotation]($backend) element,
  * a dependency is established between the two elements via the [ElementDrivesTextAnnotation]($backend) relationship such that
- * whenever the source element specified by [[propertyHost]] is modified, the field(s) in the `ITextAnnotation` element are automatically
+ * whenever the source element specified by [[propertyHost]] is modified or the `ITextAnnotation` element is inserted or updated in the iModel,
+ * the field(s) in the `ITextAnnotation` element are automatically
  * recalculated, causing their [[cachedContent]] to update. If the field's display string cannot be evaluated (for example, because the specified element or
  * property does not exist), then its cached content is set to [[FieldRun.invalidContentIndicator]].
  * A [[FieldRun]] displays its [[cachedContent]] in the same way that [[TextRun]]s display their `content`, including word wrapping where appropriate.
@@ -242,8 +256,10 @@ export class FieldRun extends TextBlockComponent {
     propertyHost;
     /** Describes how to obtain the property value from [[propertyHost]]. */
     propertyPath;
-    /** Specifies how to format the property value obtained from [[propertyPath]] into a string to be stored in [[cachedContent]]. */
-    formatter;
+    /** Specifies how to format the property value obtained from [[propertyPath]] into a string to be stored in [[cachedContent]].
+     * The specific options used depend upon the [[FieldPropertyType]].
+     */
+    formatOptions;
     _cachedContent;
     /** The field's most recently evaluated display string. */
     get cachedContent() {
@@ -258,7 +274,7 @@ export class FieldRun extends TextBlockComponent {
         this._cachedContent = props.cachedContent ?? FieldRun.invalidContentIndicator;
         this.propertyHost = props.propertyHost;
         this.propertyPath = props.propertyPath;
-        this.formatter = props.formatter;
+        this.formatOptions = props.formatOptions;
     }
     /** Create a FieldRun from its JSON representation. */
     static create(props) {
@@ -266,7 +282,8 @@ export class FieldRun extends TextBlockComponent {
             ...props,
             propertyHost: { ...props.propertyHost },
             propertyPath: structuredClone(props.propertyPath),
-            formatter: structuredClone(props.formatter),
+            formatOptions: structuredClone(props.formatOptions),
+            type: "field",
         });
     }
     /** Convert the FieldRun to its JSON representation. */
@@ -280,8 +297,8 @@ export class FieldRun extends TextBlockComponent {
         if (this.cachedContent !== FieldRun.invalidContentIndicator) {
             json.cachedContent = this.cachedContent;
         }
-        if (this.formatter) {
-            json.formatter = structuredClone(this.formatter);
+        if (this.formatOptions) {
+            json.formatOptions = structuredClone(this.formatOptions);
         }
         return json;
     }
@@ -289,6 +306,9 @@ export class FieldRun extends TextBlockComponent {
     clone() {
         return new FieldRun(this.toJSON());
     }
+    get isEmpty() {
+        return this.stringify().length === 0;
+    }
     /** Convert this FieldRun to a simple string representation. */
     stringify() {
         return this.cachedContent;
@@ -308,194 +328,263 @@ export class FieldRun extends TextBlockComponent {
         }
         const thisAccessors = this.propertyPath.accessors ?? [];
         const otherAccessors = other.propertyPath.accessors ?? [];
-        const thisJsonAccessors = this.propertyPath.jsonAccessors ?? [];
-        const otherJsonAccessors = other.propertyPath.jsonAccessors ?? [];
-        if (thisAccessors.length !== otherAccessors.length || thisJsonAccessors.length !== otherJsonAccessors.length) {
+        if (thisAccessors.length !== otherAccessors.length) {
             return false;
         }
         if (!thisAccessors.every((value, index) => value === otherAccessors[index])) {
             return false;
         }
-        if (!thisJsonAccessors.every((value, index) => value === otherJsonAccessors[index])) {
-            return false;
-        }
-        if (this.formatter && other.formatter) {
-            // ###TODO better comparison of formatter objects.
-            if (JSON.stringify(this.formatter) !== JSON.stringify(other.formatter)) {
+        if (this.formatOptions && other.formatOptions) {
+            // We anticipate new formatting options being added in the future.
+            // So to account for properties we don't know about, just compare the string representations.
+            if (JSON.stringify(this.formatOptions) !== JSON.stringify(other.formatOptions)) {
                 return false;
             }
         }
-        else if (this.formatter || other.formatter) {
+        else if (this.formatOptions || other.formatOptions) {
             return false;
         }
         return true;
     }
 }
-/** A collection of [[Run]]s within a [[TextBlock]]. Each paragraph within a text block is laid out on a separate line.
+/** A collection of [[Run]]s and [[List]]s. Paragraphs can be appended to [[List]]s and [[TextBlock]]s.
+ * Each paragraph is laid out on a separate line. If included in a [[List]], the paragraph will be treated as a list item.
  * @beta
  */
 export class Paragraph extends TextBlockComponent {
-    /** The runs within the paragraph. You can modify the contents of this array to change the content of the paragraph. */
-    runs;
+    type = "paragraph";
+    children;
     constructor(props) {
         super(props);
-        this.runs = props?.runs?.map((run) => Run.fromJSON(run)) ?? [];
+        this.children = props?.children?.map((child) => child.type === "list" ? List.create(child) : Run.fromJSON(child)) ?? [];
+    }
+    /** Create a paragraph from its JSON representation. */
+    static create(props) {
+        return new Paragraph(props);
+    }
+    clearStyleOverrides(options) {
+        clearStyleOverrides(this, options);
+    }
+    get isEmpty() {
+        return this.children.length === 0;
+    }
+    clone() {
+        return new Paragraph(this.toJSON());
     }
     toJSON() {
         return {
             ...super.toJSON(),
-            runs: this.runs.map((run) => run.toJSON()),
+            children: this.children.map((child) => child.toJSON()),
         };
     }
-    /** Create a paragraph from its JSON representation. */
+    /** Compute a string representation of this paragraph by concatenating the string representations of all of its children. */
+    stringify(options, context) {
+        return this.children.map((x, index) => (index > 0 && x.type === "list") ? `${options?.paragraphBreak ?? " "}${x.stringify(options, context)}` : x.stringify(options, context)).join("") ?? "";
+    }
+    equals(other) {
+        return (other instanceof Paragraph) && super.equals(other);
+    }
+}
+/** A collection of list items ([[Paragraph]]s). Lists can be appended to [[Paragraph]]s.
+ * Lists will be laid out on a new line. Each item in a list is laid out on a separate line.
+ * @beta
+ */
+export class List extends TextBlockComponent {
+    type = "list";
+    children;
+    constructor(props) {
+        super(props);
+        this.children = props?.children?.map((child) => Paragraph.create(child)) ?? [];
+    }
+    /** Create a list from its JSON representation. */
     static create(props) {
-        return new Paragraph(props);
+        return new List({ ...props, type: "list" });
+    }
+    clearStyleOverrides(options) {
+        clearStyleOverrides(this, options);
+    }
+    get isEmpty() {
+        return this.children.length === 0;
     }
     clone() {
-        return new Paragraph(this.toJSON());
+        return new List(this.toJSON());
     }
-    /**
-     * Clears any [[styleOverrides]] applied to this Paragraph.
-     * Will also clear [[styleOverrides]] from all child components unless [[ClearTextStyleOptions.preserveChildrenOverrides]] is `true`.
-     */
-    clearStyleOverrides(options) {
-        super.clearStyleOverrides();
-        if (options?.preserveChildrenOverrides)
-            return;
-        for (const run of this.runs) {
-            run.clearStyleOverrides();
-        }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            type: "list",
+            children: this.children.map((run) => run.toJSON()),
+        };
     }
-    /** Compute a string representation of this paragraph by concatenating the string representations of all of its [[runs]]. */
-    stringify(options) {
-        return this.runs.map((x) => x.stringify(options)).join("");
+    /** Compute a string representation of this list by concatenating the string representations of all of its [[children]]. */
+    stringify(options, context) {
+        const children = this.children.map((x, index) => {
+            const depth = context?.depth ?? 0;
+            const marker = getMarkerText(this.styleOverrides.listMarker ?? TextStyleSettings.defaultProps.listMarker, index + 1);
+            const tab = (options?.tabsAsSpaces ? " ".repeat(options.tabsAsSpaces) : "\t").repeat(depth);
+            return `${tab}${marker}${options?.listMarkerBreak ?? " "}${x.stringify(options, { depth: depth + 1 })}`;
+        });
+        return children.join(options?.paragraphBreak ?? " ") ?? "";
     }
     equals(other) {
-        if (!(other instanceof Paragraph)) {
-            return false;
-        }
-        if (this.runs.length !== other.runs.length || !super.equals(other)) {
-            return false;
-        }
-        return this.runs.every((run, index) => run.equals(other.runs[index]));
+        return (other instanceof List) && super.equals(other);
     }
 }
-;
-/** Represents a formatted text document consisting of a series of [[Paragraph]]s, each laid out on a separate line and containing their own content in the form of [[Run]]s.
- * You can change the content of the document by directly modifying the contents of its [[paragraphs]], or via [[appendParagraph]] and [[appendRun]].
+/** Represents a formatted text document consisting of a series of [[Paragraph]]s, each laid out on a separate line and containing their own content.
  * No word-wrapping is applied to the document unless a [[width]] greater than zero is specified.
  * @see [[TextAnnotation]] to position a text block as an annotation in 2d or 3d space.
  * @beta
  */
 export class TextBlock extends TextBlockComponent {
-    /** The ID of the [AnnotationTextStyle]($backend) that provides the base formatting for the contents of this TextBlock.
-     * @note Assigning to this property retains all style overrides on the TextBlock and its child components.
-     * Call [[clearStyleOverrides]] to clear the TextBlock's and optionally all children's style overrides.
-     */
-    styleId;
+    children;
     /** The width of the document in meters. Lines that would exceed this width are instead wrapped around to the next line if possible.
      * A value less than or equal to zero indicates no wrapping is to be applied.
      * Default: 0
      */
     width;
-    /** The alignment of the document's content. */
-    justification;
-    /** The margins of the document. */
-    margins;
-    /** The ordered list of paragraphs within the document. */
-    paragraphs;
     constructor(props) {
         super(props);
-        this.styleId = props.styleId;
         this.width = props.width ?? 0;
-        this.justification = props.justification ?? "left";
-        // Assign default margins if not provided
-        this.margins = {
-            left: props.margins?.left ?? 0,
-            right: props.margins?.right ?? 0,
-            top: props.margins?.top ?? 0,
-            bottom: props.margins?.bottom ?? 0,
-        };
-        this.paragraphs = props.paragraphs?.map((x) => Paragraph.create(x)) ?? [];
+        this.children = props?.children?.map((para) => Paragraph.create(para)) ?? [];
+    }
+    clearStyleOverrides(options) {
+        clearStyleOverrides(this, options);
     }
     toJSON() {
         return {
             ...super.toJSON(),
-            styleId: this.styleId,
             width: this.width,
-            justification: this.justification,
-            margins: this.margins,
-            paragraphs: this.paragraphs.map((x) => x.toJSON()),
+            children: this.children.map((x) => x.toJSON()),
         };
     }
     /** Create a text block from its JSON representation. */
     static create(props) {
-        return new TextBlock(props);
-    }
-    /** Create an empty text block containing no [[paragraphs]] and an empty [[styleId]]. */
-    static createEmpty() {
-        return TextBlock.create({ styleId: "" });
+        return new TextBlock(props ?? {});
     }
     /** Returns true if every paragraph in this text block is empty. */
     get isEmpty() {
-        return this.paragraphs.every((p) => p.runs.length === 0);
+        return !this.children || this.children.every((child) => child.isEmpty);
     }
     clone() {
         return new TextBlock(this.toJSON());
     }
-    /**
-     * Clears any [[styleOverrides]] applied to this TextBlock.
-     * Will also clear [[styleOverrides]] from all child components unless [[ClearTextStyleOptions.preserveChildrenOverrides]] is `true`.
-     */
-    clearStyleOverrides(options) {
-        super.clearStyleOverrides();
-        if (options?.preserveChildrenOverrides)
-            return;
-        for (const paragraph of this.paragraphs) {
-            paragraph.clearStyleOverrides();
-        }
-    }
-    /** Compute a string representation of the document's contents by concatenating the string representations of each of its [[paragraphs]], separated by [[TextBlockStringifyOptions.paragraphBreak]]. */
+    /** Compute a string representation of the document's contents by concatenating the string representations of each of its [[children]], separated by [[TextBlockStringifyOptions.paragraphBreak]]. */
     stringify(options) {
-        return this.paragraphs.map((x) => x.stringify(options)).join(options?.paragraphBreak ?? " ");
+        return this.children.map((x) => x.stringify(options)).join(options?.paragraphBreak ?? " ") || "";
     }
     /** Add and return a new paragraph.
      * By default, the paragraph will be created with no [[styleOverrides]], so that it inherits the style of this block.
-     * @param seedFromLast If true and [[paragraphs]] is not empty, the new paragraph will inherit the style overrides of the last [[Paragraph]] in this block.
+     * @param seedFromLast If true and [[children]] is not empty, the new paragraph will inherit the style overrides of the last child in this block.
+     * @note Be sure you pass in [[ParagraphProps]] and not [[Paragraph]] or style overrides will be ignored.
      */
-    appendParagraph(seedFromLast = false) {
-        let styleOverrides = {};
-        if (seedFromLast && this.paragraphs.length > 0) {
-            const seed = this.paragraphs[this.paragraphs.length - 1];
-            styleOverrides = { ...seed.styleOverrides };
-        }
-        const paragraph = Paragraph.create({
-            styleOverrides
-        });
-        this.paragraphs.push(paragraph);
+    appendParagraph(props, seedFromLast = false) {
+        const seed = seedFromLast ? this.children[this.children.length - 1] : undefined;
+        const styleOverrides = { ...seed?.styleOverrides, ...props?.styleOverrides };
+        const paragraph = Paragraph.create({ ...props, styleOverrides });
+        this.children.push(paragraph);
         return paragraph;
     }
     /** Append a run to the last [[Paragraph]] in this block.
-     * If the block contains no [[paragraphs]], a new one will first be created using [[appendParagraph]].
+     * If the block contains no [[children]], a new [[Paragraph]] will first be created using [[appendParagraph]].
      */
     appendRun(run) {
-        const paragraph = this.paragraphs[this.paragraphs.length - 1] ?? this.appendParagraph();
-        paragraph.runs.push(run);
+        const paragraph = this.children[this.children.length - 1] ?? this.appendParagraph();
+        paragraph.children.push(run);
     }
     equals(other) {
         if (!(other instanceof TextBlock)) {
             return false;
         }
-        if (this.styleId !== other.styleId || !super.equals(other)) {
+        if (!super.equals(other)) {
             return false;
         }
-        if (this.width !== other.width || this.justification !== other.justification || this.paragraphs.length !== other.paragraphs.length) {
+        if (this.width !== other.width) {
             return false;
         }
-        const marginsAreEqual = Object.entries(this.margins).every(([key, value]) => value === other.margins[key]);
-        if (!marginsAreEqual)
-            return false;
-        return this.paragraphs.every((paragraph, index) => paragraph.equals(other.paragraphs[index]));
+        if (this.children && other.children) {
+            if (this.children.length !== other.children.length) {
+                return false;
+            }
+            return this.children.every((child, index) => other.children && child.equals(other.children[index]));
+        }
+        return true;
     }
 }
+/**
+ * Recursively traverses a [[StructuralTextBlockComponent]] tree, yielding each child component along with its parent container.
+ * This generator enables depth-first iteration over all components in a text block structure, including paragraphs, lists, and runs.
+ *
+ * @param parent The root container whose children should be traversed.
+ * @returns An IterableIterator yielding objects with the child component and its parent container.
+ * @beta
+ */
+export function* traverseTextBlockComponent(parent) {
+    for (const child of parent.children) {
+        yield { parent, child };
+        if (child.type === "list" || child.type === "paragraph") {
+            yield* traverseTextBlockComponent(child);
+        }
+    }
+}
+/**
+ * Returns the formatted marker text for a list item based on the marker type and item number.
+ * Supports ordered and unordered list markers, including alphabetic, Roman numeral, and numeric formats.
+ * @param marker The type of list marker to use.
+ * @param num The item number in the list.
+ * @returns The formatted marker string for the list item.
+ * @beta
+ */
+export function getMarkerText(marker, num) {
+    let markerString = "";
+    switch (marker.enumerator) {
+        case undefined:
+        case ListMarkerEnumerator.Number:
+            markerString = `${num}`;
+            break;
+        case ListMarkerEnumerator.Letter:
+            markerString = integerToAlpha(num);
+            break;
+        case ListMarkerEnumerator.RomanNumeral:
+            markerString = integerToRoman(num);
+            break;
+        default:
+            markerString = marker.enumerator;
+            break;
+    }
+    if (marker.case) {
+        markerString = marker.case === "upper" ? markerString.toUpperCase() : markerString.toLowerCase();
+    }
+    const terminator = marker.terminator === "period" ? "." : marker.terminator === "parenthesis" ? ")" : "";
+    return `${markerString}${terminator}`;
+}
+/**
+ * Converts an integer to its Roman numeral representation.
+ * Supports numbers from 1 and above.
+ * @param num The integer to convert.
+ * @returns The Roman numeral string.
+ */
+function integerToRoman(num) {
+    const values = [1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1];
+    const symbols = ['M', 'CM', 'D', 'CD', 'C', 'XC', 'L', 'XL', 'X', 'IX', 'V', 'IV', 'I'];
+    let roman = '';
+    for (let i = 0; i < values.length; i++) {
+        while (num >= values[i]) {
+            roman += symbols[i];
+            num -= values[i];
+        }
+    }
+    return roman;
+}
+/**
+ * Converts an integer to its alphabetic representation (A-Z, AA-ZZ, etc.).
+ * Used for ordered list markers with alphabetic styles.
+ * @param num The integer to convert (1-based).
+ * @returns The alphabetic string for the given number.
+ */
+function integerToAlpha(num) {
+    const letterOffset = (num - 1) % 26;
+    const letter = String.fromCharCode(65 + letterOffset);
+    const depth = Math.ceil(num / 26);
+    return letter.repeat(depth);
+}
 //# sourceMappingURL=TextBlock.js.map