@globalpayments/vega 2.98.0 → 2.100.0

package/dist/collection/components/vega-rich-text-editor/extensions/paste/word-paste-transformers/word-structure-list-transformer.js

@@ -0,0 +1,591 @@
+/** Font families Word uses to render bullet symbols rather than real characters. */
+const BULLET_FONT_PATTERN = /symbol|wingdings|webdings/i;
+/**
+ * Matches the paragraph-level Word list marker (`mso-list:l0 level1 lfo1`). The
+ * presence of `l<number>` distinguishes a genuine list paragraph from the inner
+ * `mso-list:Ignore` marker span.
+ */
+const PARAGRAPH_LIST_PATTERN = /mso-list\s*:\s*l\d+/i;
+/** Extracts the Word nesting depth (`level<number>`) from a list paragraph. */
+const LIST_LEVEL_PATTERN = /mso-list\s*:\s*l\d+\s+level(\d+)/i;
+/** Extracts the abstract Word list template id (`l<number>`). */
+const LIST_TEMPLATE_ID_PATTERN = /mso-list\s*:\s*l(\d+)/i;
+/** Extracts the Word list-format override id (`lfo<number>`), unique per list instance. */
+const LIST_OVERRIDE_ID_PATTERN = /\blfo(\d+)/i;
+/** Matches the inner span that holds the Word-rendered bullet / number glyph. */
+const LIST_IGNORE_PATTERN = /mso-list\s*:\s*ignore/i;
+/** Extracts a `font-family` declaration value from a preserved style string. */
+const FONT_FAMILY_PATTERN = /font-family\s*:\s*([^;]+)/i;
+/** Fallback Word list paragraph class when no `mso-list` style is present. */
+const LIST_PARAGRAPH_CLASS_PATTERN = /MsoListParagraph/i;
+/**
+ * CSS `list-style-type` values keyed by the shape of the Word marker token.
+ * Decimal markers are intentionally absent: a plain `<ol>` already renders as
+ * `1. 2. 3.`, so numeric lists keep the current behavior with no inline style.
+ *
+ * Roman patterns explicitly accept a lone `i` / `I` (representing 1), which is
+ * the typical first item of a Roman-numeral list. Multi-character sequences
+ * must contain only Roman letters.
+ */
+const LOWER_ROMAN_PATTERN = /^(i|[ivxlcdm]{2,})$/;
+const UPPER_ROMAN_PATTERN = /^(I|[IVXLCDM]{2,})$/;
+const LOWER_ALPHA_PATTERN = /^[a-z]+$/;
+const UPPER_ALPHA_PATTERN = /^[A-Z]+$/;
+const DECIMAL_PATTERN = /^[0-9]+$/;
+/** Extracts the `list-style-type` value from a preserved style string. */
+const LIST_STYLE_TYPE_PATTERN = /list-style-type\s*:\s*([^;]+)/i;
+/**
+ * Maps the HTML `<ol type>` attribute values Word emits on real ordered lists
+ * to the equivalent CSS `list-style-type`. Decimal (`type=1`) is intentionally
+ * absent: a plain `<ol>` already renders as `1. 2. 3.`, so it needs no inline
+ * style (matching the marker-derived handling above).
+ */
+const OL_TYPE_TO_LIST_STYLE_TYPE = {
+  a: 'lower-alpha',
+  A: 'upper-alpha',
+  i: 'lower-roman',
+  I: 'upper-roman',
+};
+/**
+ * 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 class WordListRoleTransformer {
+  /** @inheritDoc */
+  apply(root) {
+    // Word can also emit real `<ol>` / `<ul>` structures where a nested list
+    // is a **sibling** of the preceding `<li>` rather than a child of it (an
+    // invalid nesting the HTML parser preserves as-is). Fix that first so the
+    // rest of the pipeline sees the standard `<li><ol>…</ol></li>` shape.
+    this.nestSiblingLists(root);
+    // Word may nest list paragraphs inside containers (e.g. `<div>`, table
+    // cells). Group by their direct parent so contiguous siblings in each
+    // container are folded together, regardless of where they sit in the tree.
+    const containers = new Set();
+    Array.from(root.querySelectorAll('p')).forEach((paragraph) => {
+      if (this.isWordListParagraph(paragraph) && paragraph.parentElement) {
+        containers.add(paragraph.parentElement);
+      }
+    });
+    // Include the root itself when it hosts list paragraphs directly.
+    if (Array.from(root.children).some((child) => this.isWordListParagraph(child))) {
+      containers.add(root);
+    }
+    containers.forEach((container) => this.processContainer(container));
+    // Word also emits real `<ol type=...>` elements whose numbering style lives
+    // on the (non-allowlisted) `type` attribute. Fold that into a preserved
+    // `list-style-type` so the marker style survives the allowlist pass.
+    this.applyOrderedListTypeAttributes(root);
+  }
+  /** @inheritDoc */
+  getAllowedTags() {
+    return ['UL', 'OL', 'LI'];
+  }
+  /** @inheritDoc */
+  getAllowedAttributes() {
+    return new Map();
+  }
+  /** @inheritDoc */
+  getAllowedStyles() {
+    return ['list-style'];
+  }
+  /**
+   * 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.
+   */
+  nestSiblingLists(root) {
+    const lists = Array.from(root.querySelectorAll('ol, ul'));
+    for (let index = lists.length - 1; index >= 0; index--) {
+      Array.from(lists[index].children).forEach((child) => {
+        if (child.tagName !== 'OL' && child.tagName !== 'UL') {
+          return;
+        }
+        const previousItem = child.previousElementSibling;
+        if (previousItem && previousItem.tagName === 'LI') {
+          previousItem.appendChild(child);
+        }
+      });
+    }
+  }
+  /**
+   * 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.
+   */
+  applyOrderedListTypeAttributes(root) {
+    Array.from(root.querySelectorAll('ol[type]')).forEach((orderedList) => {
+      const type = orderedList.getAttribute('type') || '';
+      const listStyleType = OL_TYPE_TO_LIST_STYLE_TYPE[type];
+      if (!listStyleType) {
+        return;
+      }
+      const style = orderedList.getAttribute('data-style') || '';
+      if (LIST_STYLE_TYPE_PATTERN.test(style)) {
+        return;
+      }
+      const prefix = style.trim() === '' ? '' : `${style.replace(/;\s*$/, '')}; `;
+      orderedList.setAttribute('data-style', `${prefix}list-style-type: ${listStyleType}`);
+    });
+  }
+  /**
+   * 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.
+   */
+  processContainer(container) {
+    const children = Array.from(container.children);
+    let index = 0;
+    while (index < children.length) {
+      if (!this.isWordListParagraph(children[index])) {
+        index++;
+        continue;
+      }
+      const run = [];
+      while (index < children.length && this.isWordListParagraph(children[index])) {
+        run.push(children[index]);
+        index++;
+      }
+      this.transformRun(run, container);
+    }
+  }
+  /**
+   * 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.
+   */
+  isWordListParagraph(element) {
+    if (element.tagName !== 'P') {
+      return false;
+    }
+    const style = element.getAttribute('data-style') || '';
+    if (PARAGRAPH_LIST_PATTERN.test(style)) {
+      return true;
+    }
+    const className = element.getAttribute('class') || '';
+    return LIST_PARAGRAPH_CLASS_PATTERN.test(className) && this.findMarker(element) !== undefined;
+  }
+  /**
+   * 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.
+   */
+  transformRun(run, container) {
+    const anchor = run[0];
+    const stack = [];
+    run.forEach((paragraph) => {
+      // Compute the marker once per paragraph and thread it through the
+      // helpers that need it, so the DOM is not re-queried multiple times.
+      const marker = this.findMarker(paragraph);
+      const level = this.resolveLevel(paragraph);
+      const ordered = marker ? this.isOrderedMarker(marker, paragraph) : false;
+      const listId = this.resolveListId(paragraph);
+      // Close any lists deeper than the current item.
+      while (stack.length > 0 && stack[stack.length - 1].level > level) {
+        stack.pop();
+      }
+      // Resolve the marker style with the same-level list already open in
+      // context, so an ambiguous lone "i" / "I" continues an alpha list
+      // instead of being misread as Roman 1. The marker text is still on the
+      // paragraph here (buildListItem strips it below).
+      let top = stack[stack.length - 1];
+      const listStyleType = ordered && marker ? this.resolveListStyleType(marker, top, level, listId) : null;
+      const listItem = this.buildListItem(paragraph, marker);
+      if (!top || top.level < level) {
+        top = this.openNestedList(stack, container, anchor, ordered, level, listStyleType, listId);
+      }
+      else if (this.needsSiblingList(top, ordered, listStyleType, listId)) {
+        top = this.openSiblingList(stack, ordered, level, listStyleType, listId);
+      }
+      top.listEl.appendChild(listItem);
+    });
+    run.forEach((paragraph) => paragraph.remove());
+  }
+  /**
+   * 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.
+   */
+  needsSiblingList(top, ordered, listStyleType, listId) {
+    // A known change of list instance means the two runs are distinct lists.
+    if (top.listId !== null && listId !== null && top.listId !== listId) {
+      return true;
+    }
+    if (top.ordered !== ordered) {
+      return true;
+    }
+    if (!ordered) {
+      return false;
+    }
+    return this.readListStyleType(top.listEl) !== listStyleType;
+  }
+  /**
+   * 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.
+   */
+  readListStyleType(listEl) {
+    const match = LIST_STYLE_TYPE_PATTERN.exec(listEl.getAttribute('data-style') || '');
+    return match ? match[1].trim() : null;
+  }
+  /**
+   * 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.
+   */
+  openNestedList(stack, container, anchor, ordered, level, listStyleType, listId) {
+    let currentTop = stack[stack.length - 1];
+    let currentLevel = currentTop ? currentTop.level : 0;
+    while (currentLevel < level - 1) {
+      const bridge = this.createListElement(container, ordered, null);
+      this.attachList(bridge, currentTop, container, anchor);
+      // Empty `<li>` anchor so the next deeper list can be nested inside it.
+      bridge.appendChild(bridge.ownerDocument.createElement('li'));
+      stack.push({ level: currentLevel + 1, ordered, listId, listEl: bridge });
+      currentTop = stack[stack.length - 1];
+      currentLevel = currentTop.level;
+    }
+    const parent = stack[stack.length - 1];
+    const listEl = this.createListElement(container, ordered, listStyleType);
+    this.attachList(listEl, parent, container, anchor);
+    const opened = { level, ordered, listId, listEl };
+    stack.push(opened);
+    return opened;
+  }
+  /**
+   * 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.
+   */
+  openSiblingList(stack, ordered, level, listStyleType, listId) {
+    const current = stack[stack.length - 1];
+    const listEl = this.createListElement(current.listEl, ordered, listStyleType);
+    const parentNode = current.listEl.parentNode;
+    if (parentNode) {
+      parentNode.insertBefore(listEl, current.listEl.nextSibling);
+    }
+    stack.pop();
+    const opened = { level, ordered, listId, listEl };
+    stack.push(opened);
+    return opened;
+  }
+  /**
+   * 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.
+   */
+  attachList(listEl, parent, container, anchor) {
+    if (parent) {
+      const parentItem = parent.listEl.lastElementChild;
+      (parentItem || parent.listEl).appendChild(listEl);
+    }
+    else {
+      container.insertBefore(listEl, anchor);
+    }
+  }
+  /**
+   * 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.
+   */
+  createListElement(reference, ordered, listStyleType) {
+    const listEl = reference.ownerDocument.createElement(ordered ? 'ol' : 'ul');
+    if (ordered && listStyleType) {
+      // Styles are preserved as `data-style` across the DOMParser boundary and
+      // restored to `style` after the allowlist pass.
+      listEl.setAttribute('data-style', `list-style-type: ${listStyleType}`);
+    }
+    return listEl;
+  }
+  /**
+   * 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.
+   */
+  buildListItem(paragraph, marker) {
+    const listItem = paragraph.ownerDocument.createElement('li');
+    if (marker) {
+      this.preserveMarkerPlaceholderImages(marker, paragraph);
+      this.removeMarker(marker, paragraph);
+    }
+    while (paragraph.firstChild) {
+      listItem.appendChild(paragraph.firstChild);
+    }
+    return listItem;
+  }
+  /**
+   * 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).
+   */
+  preserveMarkerPlaceholderImages(marker, paragraph) {
+    const localImages = Array.from(marker.querySelectorAll('img')).filter((image) => (image.getAttribute('src') || '').startsWith('file://'));
+    // Capture the original first child once so images land ahead of the list
+    // content in their document order (repeated inserts before a stable anchor).
+    const anchor = paragraph.firstChild;
+    localImages.forEach((image) => {
+      paragraph.insertBefore(image, anchor);
+    });
+  }
+  /**
+   * 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).
+   */
+  removeMarker(marker, paragraph) {
+    let current = marker;
+    while (current !== paragraph) {
+      const parent = current.parentElement;
+      current.remove();
+      if (!parent || parent === paragraph || !this.isEmptyElement(parent)) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  /**
+   * 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.
+   */
+  findMarker(paragraph) {
+    return Array.from(paragraph.querySelectorAll('span')).find((span) => LIST_IGNORE_PATTERN.test(span.getAttribute('data-style') || ''));
+  }
+  /**
+   * Reports whether an element has no meaningful (non-whitespace) content left.
+   *
+   * @param {HTMLElement} element Element to inspect.
+   * @returns {boolean} `true` when only whitespace remains.
+   */
+  isEmptyElement(element) {
+    return (element.textContent || '').replace(/[\s\u00A0]/g, '') === '';
+  }
+  /**
+   * Resolves the Word nesting depth for a list paragraph (defaults to 1).
+   *
+   * @param {HTMLElement} paragraph Word list paragraph.
+   * @returns {number} One-based nesting depth.
+   */
+  resolveLevel(paragraph) {
+    const style = paragraph.getAttribute('data-style') || '';
+    const match = LIST_LEVEL_PATTERN.exec(style);
+    return match ? parseInt(match[1], 10) : 1;
+  }
+  /**
+   * 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.
+   */
+  resolveListId(paragraph) {
+    const style = paragraph.getAttribute('data-style') || '';
+    const override = LIST_OVERRIDE_ID_PATTERN.exec(style);
+    if (override) {
+      return `lfo${override[1]}`;
+    }
+    const template = LIST_TEMPLATE_ID_PATTERN.exec(style);
+    return template ? `l${template[1]}` : null;
+  }
+  /**
+   * 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.
+   */
+  isOrderedMarker(marker, paragraph) {
+    const markerText = marker.textContent.replace(/[\s\u00A0]/g, '');
+    if (BULLET_FONT_PATTERN.test(this.resolveMarkerFont(marker, paragraph))) {
+      return false;
+    }
+    // Numbered markers are alphanumeric sequences ("1.", "a)", "iv)");
+    // bullet markers are standalone symbols.
+    return /[0-9]/.test(markerText) || /^[a-z]+[.)]/i.test(markerText);
+  }
+  /**
+   * 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.
+   */
+  resolveListStyleType(marker, openList, level, listId) {
+    // Drop surrounding whitespace and the trailing "." / ")" separator to
+    // isolate the numbering token (e.g. "a)" -> "a", "iv." -> "iv").
+    const token = marker.textContent.replace(/[\s\u00A0]/g, '').replace(/[.)]+$/, '');
+    if (DECIMAL_PATTERN.test(token)) {
+      return null;
+    }
+    // Disambiguate a lone "i" / "I" from list context before the Roman check:
+    // if the current same-level list is already alpha, continue it.
+    if (token === 'i' || token === 'I') {
+      const alphaStyle = token === 'i' ? 'lower-alpha' : 'upper-alpha';
+      if (this.continuesAlphaList(openList, level, listId, alphaStyle)) {
+        return alphaStyle;
+      }
+    }
+    // Roman tokens are checked before alpha so "i" / "I" (Roman numeral 1) and
+    // multi-character sequences like "ii" / "IV" are not mistaken for letters.
+    if (LOWER_ROMAN_PATTERN.test(token)) {
+      return 'lower-roman';
+    }
+    if (UPPER_ROMAN_PATTERN.test(token)) {
+      return 'upper-roman';
+    }
+    if (LOWER_ALPHA_PATTERN.test(token)) {
+      return 'lower-alpha';
+    }
+    if (UPPER_ALPHA_PATTERN.test(token)) {
+      return 'upper-alpha';
+    }
+    return null;
+  }
+  /**
+   * 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.
+   */
+  continuesAlphaList(openList, level, listId, alphaStyle) {
+    if (!openList || !openList.ordered || openList.level !== level) {
+      return false;
+    }
+    // Distinct Word list instances are separate lists; do not carry style over.
+    if (openList.listId !== null && listId !== null && openList.listId !== listId) {
+      return false;
+    }
+    return this.readListStyleType(openList.listEl) === alphaStyle;
+  }
+  /**
+   * 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.
+   */
+  resolveMarkerFont(marker, paragraph) {
+    let node = marker;
+    while (node && node !== paragraph.parentElement) {
+      const match = FONT_FAMILY_PATTERN.exec(node.getAttribute('data-style') || '');
+      if (match) {
+        return match[1];
+      }
+      node = node.parentElement;
+    }
+    return '';
+  }
+}