@itwin/core-common 5.2.0-dev.31 → 5.2.0-dev.33

package/lib/esm/annotation/TextBlock.js

@@ -5,9 +5,19 @@
 /** @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 {
@@ -72,15 +82,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 +122,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 +163,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 +193,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 +228,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.
@@ -270,6 +292,7 @@ export class FieldRun extends TextBlockComponent {
             propertyHost: { ...props.propertyHost },
             propertyPath: structuredClone(props.propertyPath),
             formatOptions: structuredClone(props.formatOptions),
+            type: "field",
         });
     }
     /** Convert the FieldRun to its JSON representation. */
@@ -292,6 +315,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;
@@ -330,63 +356,97 @@ export class FieldRun extends TextBlockComponent {
         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 {
+    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
@@ -396,8 +456,6 @@ export class TextBlock extends TextBlockComponent {
     justification;
     /** The margins of the document. */
     margins;
-    /** The ordered list of paragraphs within the document. */
-    paragraphs;
     constructor(props) {
         super(props);
         this.width = props.width ?? 0;
@@ -409,7 +467,10 @@ export class TextBlock extends TextBlockComponent {
             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 {
@@ -417,7 +478,7 @@ export class TextBlock extends TextBlockComponent {
             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. */
@@ -426,61 +487,131 @@ export class TextBlock extends TextBlockComponent {
     }
     /** 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.width !== other.width || this.justification !== other.justification || this.paragraphs.length !== other.paragraphs.length) {
+        if (!super.equals(other)) {
+            return false;
+        }
+        if (this.width !== other.width || this.justification !== other.justification) {
             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