@globalpayments/vega 2.98.0 → 2.100.0

package/dist/types/components/vega-rich-text-editor/extensions/paste/strategies/word-paste-strategy.d.ts

@@ -0,0 +1,186 @@
+import { AbstractPasteProcessingStrategy, RTEPasteMode } from './paste-processing-strategy.abstract';
+import { WordStructureTransformer } from '../word-paste-transformers/word-structure-transformer';
+/**
+ * Dynamic allowlist configuration for the Word paste sanitizer. Every rule is
+ * data-driven so the supported surface can grow per requirement without touching
+ * the sanitizer algorithm.
+ */
+export declare type WordSanitizeConfig = {
+  /** Allowed HTML tag names (upper case). */
+  allowedTags: string[];
+  /**
+   * Attribute names allowed per tag (upper case key). Use
+   * {@link WORD_SANITIZE_ALL_TAGS_KEY} for attributes allowed on every tag.
+   */
+  allowedAttributes: Record<string, string[]>;
+  /**
+   * CSS property **prefixes** to preserve. A property is kept if its canonical
+   * name (lower-case) starts with any prefix in this list; all others
+   * (including `mso-*` Word artifacts) are stripped.
+   *
+   * Examples:
+   * - `'margin'` keeps `margin`, `margin-left`, `margin-right`, etc.
+   * - `'background'` keeps `background`, `background-color`, etc.
+   * - `'text-align'` keeps only `text-align` (exact match when no variants).
+   */
+  allowedStylePrefixes: string[];
+};
+/**
+ * Default Word transformers. Sanitizer allowlist is aggregated from these
+ * transformer contracts so adding a new transformer automatically extends the
+ * allowlist surface.
+ */
+export declare const WORD_STRUCTURE_TRANSFORMERS: WordStructureTransformer[];
+/**
+ * Default sanitizer allowlist aggregated from
+ * {@link WORD_STRUCTURE_TRANSFORMERS}. Exported so tests and callers can still
+ * provide stable overrides.
+ */
+export declare const WORD_SANITIZE_CONFIG: WordSanitizeConfig;
+/**
+ * Pre processes raw Word/Office clipboard HTML into clean, RTE-friendly HTML.
+ *
+ * The pipeline mirrors the two-phase design of the source Word cleaner:
+ * 1. Structure fixing — maps Word paragraph styles onto RTE text styles and
+ *    drops Word list marker artifacts.
+ * 2. Dynamic allowlist sanitizing — recursively strips disallowed tags,
+ *    attributes and inline style declarations while keeping inner content.
+ */
+export declare class WordPasteProcessingStrategy extends AbstractPasteProcessingStrategy {
+  /**
+   * Ordered list of structure transformers applied in Phase 1 before allowlist
+   * sanitization. To add support for a new node type (table, image, list…),
+   * create a class that implements {@link WordStructureTransformer} and append
+   * it here — no other changes to the pipeline are needed.
+   */
+  static readonly STRUCTURE_TRANSFORMERS: WordStructureTransformer[];
+  /**
+   * Signatures that identify clipboard HTML produced by Microsoft Word / Office.
+   * Any single match is enough to treat the payload as Word content because
+   * these markers do not appear in ordinary web or plain rich-text clipboards.
+   */
+  private static readonly WORD_SIGNATURE_PATTERNS;
+  /**
+   * Downstream paste mode marker for Word-specific processing.
+   *
+   * @returns {RTEPasteMode} `word` so downstream handlers preserve Word annotations.
+   */
+  get type(): RTEPasteMode;
+  /**
+   * Detects whether raw clipboard HTML originated from Microsoft Word / Office.
+   *
+   * Used to auto-route a normal "rich text" paste through the Word cleaning
+   * pipeline when the source is actually Word, so users get correct formatting
+   * without having to explicitly pick the Word paste option.
+   *
+   * @param {string} html Raw `text/html` clipboard payload.
+   * @returns {boolean} `true` when the HTML carries Word/Office signatures.
+   */
+  canHandle(html: string): boolean;
+  /**
+   * Returns the priority of this strategy relative to others; higher values run first.
+   *
+   * @returns {number} The priority value.
+   */
+  get priority(): number;
+  /**
+   * Whether this strategy extracts pasted images and produces local previews.
+   *
+   * @returns {boolean} Always `true`; Word paste swaps `file://` images to previews.
+   */
+  get supportsImageProcessing(): boolean;
+  /**
+   * Cleans raw Word clipboard HTML so it can flow through the normal RTE paste
+   * pipeline.
+   *
+   * @param {string} html Raw `text/html` clipboard payload from Word.
+   * @param {WordSanitizeConfig} [config] Optional allowlist override.
+   * @returns {string} Sanitized HTML string.
+   */
+  process(html: string, config?: WordSanitizeConfig): string;
+  /**
+   * Removes Office XML comments and down-level conditional markup that would
+   * otherwise confuse `DOMParser`.
+   *
+   * @param {string} html Raw HTML string.
+   * @returns {string} HTML without Word comment blocks.
+   */
+  private stripWordComments;
+  /**
+   * First phase: repairs Word-specific structure so it aligns with RTE text
+   * styles before the allowlist pass runs.
+   *
+   * @param {HTMLElement} root Parsed body element.
+   */
+  private fixWordStructure;
+  /**
+   * Removes the whitespace-only text nodes Word emits directly between block
+   * elements (the `\n\n` at the top level of the fragment). After the allowlist
+   * pass, disallowed containers are already unwrapped, so any remaining
+   * top-level text node that is pure whitespace is an inter-block artifact.
+   * Whitespace inside inline/text elements is left untouched.
+   *
+   * @param {HTMLElement} root Parsed body element.
+   */
+  private removeInterBlockWhitespace;
+  /**
+   * Collapses insignificant ASCII whitespace inside text nodes the way a
+   * browser would when rendering. Word wraps long runs of text across multiple
+   * source lines, so a single logical line such as "Number list 1" arrives as
+   * "Number\nlist 1"; without normalization the newline surfaces as a spurious
+   * line break in the editor. Non-breaking spaces (`\u00A0`) are left untouched
+   * so intentional Word spacing and blank lines survive.
+   *
+   * @param {Node} node Node whose text descendants are normalized in place.
+   */
+  private collapseInsignificantWhitespace;
+  /**
+   * Preserves intentional blank lines authored in Word (empty paragraphs whose
+   * only content is a non-breaking space). The downstream paste pipeline drops
+   * any block whose text content trims to empty, and `trim()` also removes a
+   * non-breaking space; replacing the content with a zero-width space keeps the
+   * blank line because it survives `trim()` while still rendering as empty.
+   *
+   * @param {HTMLElement} root Parsed body element.
+   */
+  private preserveWordEmptyLines;
+  /**
+   * Second phase: recursively enforces the dynamic allowlist on a node tree.
+   *
+   * @param {Node} node Node to sanitize in place.
+   * @param {WordSanitizeConfig} config Active allowlist configuration.
+   */
+  private sanitizeNode;
+  /**
+   * Removes disallowed attributes and filters style declarations.
+   *
+   * @param {Element} element Element being sanitized.
+   * @param {string} tagName Upper-case tag name.
+   * @param {WordSanitizeConfig} config Active sanitize configuration.
+   */
+  private sanitizeAttributes;
+  /**
+   * Filters CSS declarations inside a preserved style attribute: keeps only
+   * properties matching a prefix in {@link WordSanitizeConfig.allowedStylePrefixes};
+   * all others (including `mso-*` Word artifacts) are stripped.
+   *
+   * @param {Element} element Element owning the style attribute.
+   * @param {string} attrName Preserved style attribute name.
+   * @param {WordSanitizeConfig} config Active sanitize configuration.
+   */
+  private sanitizeStyleAttribute;
+  /**
+   * Converts preserved `data-style` attributes back to `style` in the final
+   * HTML string so downstream paste handling receives standard markup.
+   *
+   * @param {string} html Serialized sanitized HTML.
+   * @returns {string} HTML with `style` attributes restored.
+   */
+  private restoreStyleAttributeName;
+  /**
+   * Removes the element from its parent node if it has one.
+   *
+   * @param {Node | Element} elementToBeRemoved The element to be removed from the DOM.
+   */
+  private removeSelf;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/word-paste-transformers/word-structure-code-block-transformer.d.ts

@@ -0,0 +1,51 @@
+import { WordStructureTransformer } from './word-structure-transformer';
+/**
+ * Normalizes pasted `<pre>` nodes so they can be parsed as RTE code blocks.
+ *
+ * The RTE recognizes a code block only when `data-language` is present on
+ * `<pre>`. Word-exported snippets commonly use plain `<pre>` with no
+ * language metadata, so this transformer adds a default language and copies any
+ * detectable language hint from nested code markup when available.
+ */
+export declare class WordCodeBlockTransformer implements WordStructureTransformer {
+  /**
+   * Determines whether a node is a code block whose whitespace must be preserved.
+   *
+   * @param {Node} node Node to inspect.
+   * @returns {boolean} `true` when the node is a `<pre>` element.
+   */
+  static isCodeBlock(node: Node): boolean;
+  /** @inheritDoc */
+  apply(root: HTMLElement): void;
+  /** @inheritDoc */
+  getAllowedTags(): string[];
+  /** @inheritDoc */
+  getAllowedAttributes(): Map<string, string[]>;
+  /** @inheritDoc */
+  getAllowedStyles(): string[];
+  /**
+   * Resolves code language metadata from `<pre>` class hints, falling back to
+   * {@link DEFAULT_CODE_LANGUAGE}.
+   *
+   * `apply()` only invokes this method when the `<pre>` has no
+   * `data-language` attribute, so class-based inference is the only source
+   * this method needs to consult.
+   *
+   * @param {HTMLElement} preElement Source `<pre>` element.
+   * @returns {string} Resolved language id or `plainText` fallback.
+   */
+  private resolveLanguage;
+  /**
+   * Extracts a language id from class names like `language-js` or `lang-ts`.
+   *
+   * @param {HTMLElement} preElement Source `<pre>` element.
+   * @returns {string} Extracted language id or empty string.
+   */
+  private resolveLanguageFromClassName;
+  /**
+   * Removes Word-only `Mso*` class names and keeps any non-Word classes.
+   *
+   * @param {HTMLElement} preElement Source `<pre>` element.
+   */
+  private stripWordClassArtifacts;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/word-paste-transformers/word-structure-image-transformer.d.ts

@@ -0,0 +1,86 @@
+import { WordStructureTransformer } from './word-structure-transformer';
+/**
+ * Normalizes Word image markup into plain <img> tags, drops list-marker images,
+ * and optionally remaps image source paths.
+ */
+export declare class WordImageTransformer implements WordStructureTransformer {
+  /** @inheritDoc */
+  getAllowedTags(): string[];
+  /** @inheritDoc */
+  getAllowedAttributes(): Map<string, string[]>;
+  /** @inheritDoc */
+  getAllowedStyles(): string[];
+  /** @inheritDoc */
+  apply(root: HTMLElement): void;
+  /**
+   * Lifts images out of text-style blocks (`h1`-`h6`, Word title / subtitle
+   * paragraphs) so they become standalone top-level images.
+   *
+   * The RTE data model represents these blocks as text blocks whose children
+   * are text nodes only, so an `<img>` nested inside one has no text-node
+   * representation and would be silently dropped during DTO conversion. Moving
+   * each image to a sibling position right after its block lets the downstream
+   * image-block strategies pick it up. Images are re-inserted in document order
+   * so they stay aligned with the RTF files paired later.
+   *
+   * Word title / subtitle paragraphs still carry their raw `MsoTitle` /
+   * `MsoSubtitle` class here because {@link WordParagraphRoleTransformer} runs
+   * after this transformer.
+   *
+   * @param {HTMLElement} root Parsed Word fragment root.
+   */
+  private liftImagesOutOfTextStyleBlocks;
+  /**
+   * Reports whether a block hosts its images as text-only children, requiring
+   * nested images to be lifted out: any heading (`h1`-`h6`) or a Word title /
+   * subtitle paragraph.
+   *
+   * @param {HTMLElement} element Candidate block element.
+   * @returns {boolean} `true` when nested images must be lifted out of the block.
+   */
+  private isImageLiftTargetBlock;
+  /**
+   * Converts Word VML `v:imagedata` elements to plain `<img>` elements.
+   *
+   * @param {HTMLElement} root Parsed Word fragment root.
+   */
+  private normalizeWordImageDataElements;
+  /**
+   * Removes non-VML fallback images that reference a specific Word VML shape id.
+   *
+   * Word clipboard HTML often includes both `v:imagedata` and an `<img v:shapes="...">`
+   * fallback for the same visual image. Once VML is normalized, the fallback must
+   * be removed to avoid duplicated image handling.
+   *
+   * @param {HTMLElement} root Parsed Word fragment root.
+   * @param {string} shapeId VML shape id referenced by fallback images.
+   */
+  private removeFallbackImagesForShapeId;
+  /**
+   * Removes list-marker images and sourceless `<img>` elements.
+   *
+   * @param {HTMLElement} root Parsed Word fragment root.
+   */
+  private normalizeStandardImages;
+  /**
+   * Inserts an empty `<span> </span>` between adjacent images to avoid
+   * downstream image-block parsing treating a compact image run as a single image.
+   *
+   * @param {HTMLElement} root Parsed Word fragment root.
+   */
+  private insertSpanBetweenAdjacentImages;
+  /**
+   * Currently the RTE does not support list images, so they must be removed from the paste content.
+   * Local (file://) list images are kept as placeholders here and removed later during preview pairing
+   * so the local images stay aligned with the RTF images; non-local list images are removed immediately.
+   * Returns true when the image is part of list content and should be ignored.
+   *
+   * Word list markup (`MsoListParagraph` / `mso-list`) is already normalized into
+   * real `li/ul/ol` by {@link WordListRoleTransformer}, which runs before this
+   * transformer, so a plain list-ancestor check is sufficient here.
+   *
+   * @param {Element} element Image element (or its wrapper).
+   * @returns {boolean} Whether this image belongs to list content.
+   */
+  private isListImage;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/word-paste-transformers/word-structure-list-transformer.d.ts

@@ -0,0 +1,271 @@
+import { WordStructureTransformer } from './word-structure-transformer';
+/**
+ * Rebuilds Word list paragraphs into real `<ul>` / `<ol>` / `<li>` structures.
+ *
+ * Word does not emit list elements: it emits a flat sequence of `<p>` blocks
+ * that each carry an `mso-list:l<id> level<depth> lfo<override>` marker plus an
+ * inner `mso-list:Ignore` span that renders the visible bullet or number. This
+ * transformer walks every container that hosts list paragraphs (so nested
+ * `<div>` / table cells are covered), strips the marker span, decides bullet
+ * vs. numbered from the marker text / font, and folds the flat items back into
+ * a nested list tree the RTE slimmer can parse.
+ *
+ * Runs before {@link WordParagraphRoleTransformer} so the converted `<li>`
+ * elements are no longer seen as paragraphs during role resolution.
+ */
+export declare class WordListRoleTransformer implements WordStructureTransformer {
+  /** @inheritDoc */
+  apply(root: HTMLElement): void;
+  /** @inheritDoc */
+  getAllowedTags(): string[];
+  /** @inheritDoc */
+  getAllowedAttributes(): Map<string, string[]>;
+  /** @inheritDoc */
+  getAllowedStyles(): string[];
+  /**
+   * Moves any `<ol>` / `<ul>` that appears as a direct child of another
+   * `<ol>` / `<ul>` into the preceding `<li>` sibling, so downstream strategies
+   * see a well-formed nested list. Word emits this invalid shape when it uses
+   * real list elements (rather than flat `mso-list` paragraphs) — the browser
+   * parser keeps the nested list as a sibling of the `<li>` it should belong
+   * to, and the RTE's OL/UL block strategy would drop it because its
+   * `appendChildBlocks` only keeps `<li>` children.
+   *
+   * Runs bottom-up so a nested list that also has misplaced children is fixed
+   * before its own parent list picks it up.
+   *
+   * @param {HTMLElement} root Parsed body element.
+   */
+  private nestSiblingLists;
+  /**
+   * Converts the HTML `<ol type>` attribute into a preserved
+   * `list-style-type` declaration for every ordered list that carries one.
+   *
+   * Word can paste genuine `<ol>` elements (rather than flat list paragraphs)
+   * that encode alpha / Roman numbering via the legacy `type` attribute
+   * (`type=a`, `type=i`, `type=I`, …). The `type` attribute is not on the
+   * allowlist and would be dropped, losing the numbering style, so it is mapped
+   * onto `list-style-type` inside `data-style`. Decimal (`type=1`) lists are
+   * left untouched because a bare `<ol>` already renders as `1. 2. 3.`. An
+   * existing `list-style-type` declaration wins and is never overwritten.
+   *
+   * @param {HTMLElement} root Parsed body element.
+   */
+  private applyOrderedListTypeAttributes;
+  /**
+   * Walks a container, folding each contiguous run of Word list paragraphs
+   * into a nested list tree in place of the original paragraphs.
+   *
+   * @param {HTMLElement} container Element whose direct children may include list paragraphs.
+   */
+  private processContainer;
+  /**
+   * Determines whether an element is a Word list paragraph.
+   *
+   * A paragraph is only treated as a list when it carries a genuine Word list
+   * marker: either the `mso-list:l<n>` paragraph style, or the `MsoListParagraph`
+   * class **together with** an inner `mso-list:Ignore` marker span. The
+   * `MsoListParagraph` class alone is not sufficient — Word also uses that
+   * paragraph style for plain indented content (e.g. headings), which must not
+   * be folded into a `<ul>` / `<ol>`.
+   *
+   * @param {HTMLElement} element Candidate element.
+   * @returns {boolean} `true` when the element is a `<p>` carrying a Word list marker.
+   */
+  private isWordListParagraph;
+  /**
+   * Folds a flat run of Word list paragraphs into a nested list tree inserted
+   * before the run, then removes the original paragraphs.
+   *
+   * @param {HTMLElement[]} run Consecutive Word list paragraphs.
+   * @param {HTMLElement} container Element hosting the run.
+   */
+  private transformRun;
+  /**
+   * Reports whether a same-level item must break out into a new sibling list.
+   * A different Word list instance always splits (so two separate lists pasted
+   * back-to-back keep independent numbering). Bullet-vs-numbered switches also
+   * split, and numbered lists additionally split when the CSS `list-style-type`
+   * changes (e.g. `1.` → `a)`).
+   *
+   * @param {OpenList} top Currently open list at the same nesting depth.
+   * @param {boolean} ordered Whether the incoming item is numbered.
+   * @param {string | null} listStyleType Incoming numbered list style, if any.
+   * @param {string | null} listId Incoming Word list instance id, if any.
+   * @returns {boolean} `true` when a new sibling list should be opened.
+   */
+  private needsSiblingList;
+  /**
+   * Reads a previously-written `list-style-type` from an open list element.
+   *
+   * @param {HTMLElement} listEl List element.
+   * @returns {string | null} The style value, or `null` when none is set.
+   */
+  private readListStyleType;
+  /**
+   * Opens a new list nested one or more levels deeper than the current top.
+   * Word occasionally skips indent levels on paste (e.g. jumping from `level1`
+   * to `level3`); this walks the gap one level at a time, inserting placeholder
+   * lists so the deeper list is nested through empty `<li>` anchors instead of
+   * appearing as a sibling of the shallower list.
+   *
+   * @param {OpenList[]} stack Stack of currently open lists.
+   * @param {HTMLElement} container Host element for the top-level list.
+   * @param {HTMLElement} anchor Element the top-level list is inserted before.
+   * @param {boolean} ordered Whether the new list is numbered.
+   * @param {number} level Word nesting depth for the new list.
+   * @param {string | null} listStyleType CSS `list-style-type` for ordered lists.
+   * @param {string | null} listId Word list instance id for the new list.
+   * @returns {OpenList} The newly opened list.
+   */
+  private openNestedList;
+  /**
+   * Replaces the current top list with a sibling list at the same nesting
+   * depth. Used when the list flavor (bullet vs. numbered, or the ordered
+   * marker style) flips between two consecutive same-level items.
+   *
+   * @param {OpenList[]} stack Stack of currently open lists.
+   * @param {boolean} ordered Whether the sibling list is numbered.
+   * @param {number} level Word nesting depth for the sibling list.
+   * @param {string | null} listStyleType CSS `list-style-type` for ordered lists.
+   * @param {string | null} listId Word list instance id for the sibling list.
+   * @returns {OpenList} The newly opened sibling list.
+   */
+  private openSiblingList;
+  /**
+   * Attaches a freshly created list element either inside the last item of the
+   * parent list (for nested lists) or before the run anchor (top-level lists).
+   *
+   * @param {HTMLElement} listEl List element to attach.
+   * @param {OpenList | undefined} parent Currently open parent list, if any.
+   * @param {HTMLElement} container Host element used for top-level insertion.
+   * @param {HTMLElement} anchor Element the top-level list is inserted before.
+   */
+  private attachList;
+  /**
+   * Creates an empty `<ol>` or `<ul>` element, tagging ordered lists with a
+   * `list-style-type` when their markers are not plain decimals.
+   *
+   * @param {HTMLElement} reference Element whose document creates the list.
+   * @param {boolean} ordered Whether to create a numbered list.
+   * @param {string | null} listStyleType CSS `list-style-type` for ordered lists.
+   * @returns {HTMLElement} The new list element.
+   */
+  private createListElement;
+  /**
+   * Converts a Word list paragraph into an `<li>` element: the marker span is
+   * removed and the remaining content is moved into the list item.
+   *
+   * @param {HTMLElement} paragraph Word list paragraph.
+   * @param {HTMLElement | undefined} marker Pre-resolved `mso-list:Ignore` span.
+   * @returns {HTMLLIElement} The populated list item.
+   */
+  private buildListItem;
+  /**
+   * Moves any local (`file://`) images out of the marker span so they survive
+   * marker removal as list-item placeholders.
+   *
+   * Word renders a picture bullet as an `<img>` inside the `mso-list:Ignore`
+   * marker span. That bullet still occupies one image slot in the clipboard RTF,
+   * so silently dropping it here would leave its RTF blip unconsumed and shift
+   * every following image onto the wrong file. Keeping the bullet as a `file://`
+   * placeholder inside the `<li>` lets downstream preview pairing consume its RTF
+   * slot and then drop it (list images have no editor representation), keeping the
+   * remaining images aligned with their files. Non-local bullet images have no RTF
+   * counterpart and are left in the marker to be removed with it.
+   *
+   * @param {HTMLElement} marker Marker span holding the bullet glyph / image.
+   * @param {HTMLElement} paragraph Owning list paragraph (placeholder host).
+   */
+  private preserveMarkerPlaceholderImages;
+  /**
+   * Removes the `mso-list:Ignore` marker span and any wrapper elements it
+   * leaves empty behind.
+   *
+   * @param {HTMLElement} marker Marker span to remove.
+   * @param {HTMLElement} paragraph Owning list paragraph (stop boundary).
+   */
+  private removeMarker;
+  /**
+   * Finds the `mso-list:Ignore` marker span within a list paragraph.
+   *
+   * @param {HTMLElement} paragraph Word list paragraph.
+   * @returns {HTMLElement | undefined} The marker span, if present.
+   */
+  private findMarker;
+  /**
+   * Reports whether an element has no meaningful (non-whitespace) content left.
+   *
+   * @param {HTMLElement} element Element to inspect.
+   * @returns {boolean} `true` when only whitespace remains.
+   */
+  private isEmptyElement;
+  /**
+   * Resolves the Word nesting depth for a list paragraph (defaults to 1).
+   *
+   * @param {HTMLElement} paragraph Word list paragraph.
+   * @returns {number} One-based nesting depth.
+   */
+  private resolveLevel;
+  /**
+   * Resolves the Word list instance id for a paragraph. Prefers the list-format
+   * override (`lfo<n>`), which is unique per pasted list, and falls back to the
+   * abstract list template id (`l<n>`). Returns `null` when neither is present
+   * (e.g. the `MsoListParagraph` class fallback).
+   *
+   * @param {HTMLElement} paragraph Word list paragraph.
+   * @returns {string | null} The list instance id, or `null` when unknown.
+   */
+  private resolveListId;
+  /**
+   * Decides whether a resolved marker span represents a numbered (`<ol>`) or
+   * bulleted (`<ul>`) item based on its text and font.
+   *
+   * @param {HTMLElement} marker Marker span.
+   * @param {HTMLElement} paragraph Owning list paragraph.
+   * @returns {boolean} `true` for numbered items, `false` for bulleted items.
+   */
+  private isOrderedMarker;
+  /**
+   * Resolves the CSS `list-style-type` for a numbered list marker.
+   * Plain decimal markers ("1.", "2.") return `null` so a bare `<ol>` is used;
+   * alphabetic and Roman markers map to the matching CSS value so their marker
+   * style is preserved.
+   *
+   * A lone `i` / `I` is ambiguous: it is both Roman numeral 1 and the 9th
+   * letter of the alphabet. When the same-level list already open for this
+   * instance is alpha, the marker is kept alpha so a long `a) ... h) i) j)`
+   * run does not split into a Roman sibling at item 9; otherwise the lone
+   * marker is treated as Roman 1 (the first item of a Roman list).
+   *
+   * @param {HTMLElement} marker Marker span.
+   * @param {OpenList | undefined} openList Same-depth list already open, if any.
+   * @param {number} level Word nesting depth of the incoming item.
+   * @param {string | null} listId Word list instance id of the incoming item.
+   * @returns {string | null} The CSS `list-style-type`, or `null` for decimals.
+   */
+  private resolveListStyleType;
+  /**
+   * Reports whether a lone `i` / `I` marker continues an already-open alpha
+   * list rather than starting a Roman one. True only when the same-depth list
+   * is a matching alpha `<ol>` for the same Word list instance, so an ambiguous
+   * marker at item 9 stays part of the surrounding `lower-alpha` / `upper-alpha`
+   * run instead of opening a Roman sibling.
+   *
+   * @param {OpenList | undefined} openList Same-depth list already open, if any.
+   * @param {number} level Word nesting depth of the incoming item.
+   * @param {string | null} listId Word list instance id of the incoming item.
+   * @param {string} alphaStyle The alpha style the marker would continue.
+   * @returns {boolean} `true` when the marker should be treated as alpha.
+   */
+  private continuesAlphaList;
+  /**
+   * Resolves the effective `font-family` for a marker by walking up to the
+   * paragraph, so Word's `Symbol` / `Wingdings` bullet fonts can be detected.
+   *
+   * @param {HTMLElement} marker Marker span.
+   * @param {HTMLElement} paragraph Owning list paragraph.
+   * @returns {string} The resolved font family, or an empty string.
+   */
+  private resolveMarkerFont;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/word-paste-transformers/word-structure-paragraph-transformer.d.ts

@@ -0,0 +1,25 @@
+import { WordStructureTransformer } from './word-structure-transformer';
+/**
+ * Maps Word title / subtitle / heading paragraph style class names onto RTE
+ * CSS text-style classes. Any pre-existing `data-type` attributes are stripped
+ * first so only trusted values remain. Using a class instead of a custom
+ * attribute prevents the value from leaking into the DTO's custom-attribute
+ * annotation and subsequently into the serialized HTML output.
+ */
+export declare class WordParagraphRoleTransformer implements WordStructureTransformer {
+  /** @inheritDoc */
+  apply(root: HTMLElement): void;
+  /** @inheritDoc */
+  getAllowedTags(): string[];
+  /** @inheritDoc */
+  getAllowedAttributes(): Map<string, string[]>;
+  /** @inheritDoc */
+  getAllowedStyles(): string[];
+  /**
+   * Resolves the RTE text style for a Word paragraph class name.
+   *
+   * @param {string | null} className Raw `class` attribute value.
+   * @returns {WordParagraphRole | null} Matched role or `null`.
+   */
+  private resolveRole;
+}