@modusoperandi/licit-import-utils 0.1.0

package/licit-transform.d.ts

@@ -0,0 +1,360 @@
+/**
+ * @license MIT
+ * @copyright Copyright 2026 Modus Operandi Inc. All Rights Reserved.
+ */
+import type { LicitDocumentJSON } from './licit-elements';
+import { LicitBulletListElement, LicitDocumentElement, LicitEnhancedImageElement, LicitTableRowElement } from './licit-elements';
+import type { UpdatedCapco } from './capco.util';
+import type { MessageSink } from './types';
+export interface ParserElement {
+    node: Element;
+    class: string;
+    type: ParserElementType;
+    level: number;
+    subText: string;
+}
+interface ImageInfo {
+    src: string;
+    alt: string;
+    width: number;
+    height: number;
+}
+declare enum ParserElementType {
+    ChapterTitle = 0,
+    ChapterSubtitle = 1,
+    ChapterFigureTitle = 2,
+    Header = 3,
+    Note = 4,
+    Paragraph = 5,
+    SectionTitle = 6,
+    TableTitle = 7,
+    FigureTitle = 8,
+    BulletListItem = 9,
+    OrderedListItem = 10,
+    Table = 11,
+    EnhancedTable = 12,
+    Figure = 13,
+    ChangeBarPara = 14,
+    hr = 15,
+    vignet = 16,
+    Uncategorized = 17,
+    infoIcon = 18,
+    NewFigureTitle = 19
+}
+export interface StyleInfo {
+    styleName: string;
+    styles?: {
+        styleLevel?: number | string;
+    };
+}
+export interface TransformConfig {
+    customStylesUrl: string;
+    replacementChars: {
+        find: string;
+        replace: string;
+    }[];
+    replaceCharacters: boolean;
+    stripSectionNumbers: boolean;
+    replaceWithLinks: {
+        find: string;
+        href: string;
+    }[];
+    messageSink?: MessageSink;
+    customStyles: StyleInfo[];
+}
+export declare const DEFAULT_Config: TransformConfig;
+export declare function asTransformConfig(config?: Partial<TransformConfig>): {
+    customStylesUrl: string;
+    replacementChars: {
+        find: string;
+        replace: string;
+    }[];
+    replaceCharacters: boolean;
+    stripSectionNumbers: boolean;
+    replaceWithLinks: {
+        find: string;
+        href: string;
+    }[];
+    messageSink?: MessageSink;
+    customStyles: StyleInfo[];
+};
+export interface AddCellOptions {
+    bgColor: string;
+    isChapterHeader: boolean;
+    verAlign: string;
+    cellIndex: number;
+    widthArray: number[];
+    isTransparent: boolean;
+}
+export declare class LicitConverter {
+    private readonly config;
+    elementsParsedMap: Map<string, boolean>;
+    elements: ParserElement[];
+    constructor(config: TransformConfig);
+    parseHTML(html: Document, isDoctorine: boolean, moDocType?: string): LicitDocumentJSON;
+    parseFrameMakerHTML5(html: Element[]): LicitDocumentJSON;
+    render_FrameMakerHTML5_zip(nodes: NodeList, infoIconData?: HTMLOListElement[], _moDocType?: string, renderedContentList?: Node[]): LicitDocumentJSON;
+    render_FrameMakerHTML5_zip_SwitchHelper(e: ParserElement, infoIconData: HTMLOListElement[], renderedContentList: Node[], isNumberReseted: boolean, licitDocument: LicitDocumentElement): boolean;
+    private handleNodes;
+    fetchRenderedContent(nodes: NodeList): Node[];
+    /**
+     * Returns a map elements which were parsed.
+     *
+     * @returns Map of elements
+     */
+    getElementsParsedMap(): Map<string, boolean>;
+    getCustomStyle(styleName: string): StyleInfo | undefined;
+    handleOrderedListItem(e: ParserElement, licitDocument: LicitDocumentElement): void;
+    /**
+     * Renders the HTML as a Licit JSON structure
+     *
+     * @returns The document as an `LicitDocumentJSON` object
+     */
+    render(nodes: NodeListOf<Element>): LicitDocumentJSON;
+    renderSwitchHelper(e: ParserElement, licitDocument: LicitDocumentElement): void;
+    private renderTable;
+    private renderParagraph;
+    private renderHeader;
+    private buildElements;
+    checkChildNode(node: HTMLElement | Element, nextNode: HTMLElement | Element): number;
+    render_doc(nodes: NodeListOf<Element>, infoIconData: HTMLOListElement[] | undefined, moDocType: string): LicitDocumentJSON;
+    render_docSwitchHelper(e: ParserElement, licitDocument: LicitDocumentElement, tocRemoved: boolean, infoIconData: HTMLOListElement[], moDocType: string): boolean;
+    renderTypeParagraph(e: ParserElement, licitDocument: LicitDocumentElement, infoIconData?: HTMLOListElement[]): void;
+    handle_UrlText(text: string, licitDocument: LicitDocumentElement, infoIconData?: HTMLOListElement[]): void;
+    text_WithoutUrl(n: Node, licitDocument: LicitDocumentElement, infoIconData?: HTMLOListElement[]): void;
+    private handleNode;
+    mergeSpans(node: Element, nextNode: Element): number;
+    updateChildCapcoContent(e: ParserElement): void;
+    updateChildCapcoContentLoopHelper(childNodes: ChildNode[], res: UpdatedCapco): void;
+    processChildNodesCapco(childNodes: NodeListOf<ChildNode>): void;
+    updateCapcoToParagraph(child: ChildNode, res: UpdatedCapco): void;
+    processTableCapco(tableNode: HTMLTableElement): void;
+    figureTitleCase(e: ParserElement, licitDocument: LicitDocumentElement): void;
+    handleImageChild(child: Element, licitDocument: LicitDocumentElement): void;
+    renderNewFigureTitle(e: ParserElement, licitDocument: LicitDocumentElement): void;
+    figureParagraphCase(e: ParserElement, licitDocument: LicitDocumentElement, infoIconData: HTMLOListElement[] | undefined, renderedContentList: Node[]): void;
+    figureNoteCase(e: ParserElement, licitDocument: LicitDocumentElement): void;
+    figureTableTitleCase(e: ParserElement, licitDocument: LicitDocumentElement): void;
+    private renderDocVignet;
+    private parseUntypedDocVignet;
+    private parseTypedDocVignet;
+    parseTypedDocVignetHelper(val: string, bgColor: string, borderColor: string, boxWidth: number): {
+        bgColor: string;
+        borderColor: string;
+        boxWidth: number;
+    };
+    private renderDocTable;
+    private renderEnhancedTable;
+    private getLicitTable;
+    renderNewLicitImage(imageElement: HTMLImageElement, capco: string | null): LicitEnhancedImageElement;
+    renderDocBulletItems(e: ParserElement, licitDocument: LicitDocumentElement): void;
+    processBulletNodes(childNodes: Node[], bulletList: LicitBulletListElement, licitDocument: any, indent: number, e: any): void;
+    addElementLicit(licitDocument: any, bulletList: LicitBulletListElement): void;
+    removeEmptyATags(node: Node): void;
+    private handleULNode;
+    private renderDocFigure;
+    renderImage(imgElement: HTMLImageElement, licitDocument: LicitDocumentElement): void;
+    parseOL(e: ParserElement, licitDocument: LicitDocumentElement): void;
+    /**
+     * To parse table data
+     * @param e - element
+     * @param tableTag - The tag name or identifier of the table.
+     * @param querySel Selector for Querying from table row
+     * @param isChapterHeader  flag to determine ChapterHeader
+     * @param licitTable -Licit Table Element
+     * @param widthArray - To scale the table to specific sizes
+     * @param isTransparent - flag to distinguish preface table
+     * @returns void
+     */
+    parseTableContent(_e: any, tableTag: any, querySel: any, isChapterHeader: any, licitTable: any, widthArray: number[], isTransparent: boolean): void;
+    parseTableContentInnerLoopHelper(cells: any, _cellIndex: number, isChapterHeader: boolean, licitRow: LicitTableRowElement, widthArray: number[], isTransparent: boolean): void;
+    private addCell;
+    checkCellStyle(style: string | null): string | null;
+    private addTableImageCell;
+    ParseNestedList(_listType: string, node: ChildNode, licitDocument: LicitDocumentElement, indent: number): void;
+    /**
+     * Returns the level of an element as described by the number at the end of its classname
+     *
+     * @param className - The className of the element
+     * @returns The level as a number or zero if the level cannot be determined
+     */
+    extractLevel(className: string): number;
+    /**
+     * Determines if an element is a table or image then calls the appropriate parse method
+     */
+    parseTableFigure(element: Element): void;
+    /**
+     * Parse a table element
+     */
+    parseTable(element: Element, useEnhancedTables: boolean): void;
+    /**
+     * Parse a table element
+     */
+    parseVignet(element: Element): void;
+    /**
+     * Parse a figure (image) element
+     */
+    parseFigure(element: Element): void;
+    /**
+     * Parse a note element
+     */
+    parseNote(element: Element): void;
+    /**
+     * Parse a hr element
+     */
+    parseHR(element: Element): void;
+    /**
+     * Parse a chapter title element
+     */
+    parseChapterTitle(element: Element): void;
+    /**
+     * Parse a chapter subtitle element
+     */
+    parseChapterSubtitle(element: Element): void;
+    /**
+     * Parse a header element
+     */
+    parseHeader(element: Element, nextElement: Element): void;
+    /**
+     * Parse a bullet point item element
+     */
+    parseBullet(element: Element): void;
+    /**
+     * Parse a ordered list point item element
+     */
+    parseOrdered(element: Element): void;
+    /**
+     * Parse a paragraph element
+     */
+    parseParagraph(element: Element): void;
+    parseDynamicHeader(element: Element): void;
+    /** Sanitize the text content by removing specific characters */
+    sanitizeText(element: Element): void;
+    /**
+     * Parse a figure (image) title element
+     */
+    parseFigureTitle(element: Element): void;
+    /**
+     * Parse a ChangeBarPara element
+     */
+    parseChangeBarPara(element: Element): void;
+    /**
+     * Parse a table title element
+     */
+    parseTableTitle(element: Element): void;
+    /**
+     * Parse an unknown element. Currently does nothing besides printing a warning to the console.
+     */
+    parseUnknownElement(element: Element, message: string): void;
+    /**
+     * Parse a section title element
+     */
+    parseSectionTitle(element: Element): void;
+    /**
+     * Parses an `Element` as determined by its `className`
+     *
+     * @param element - The `Element` to be parsed
+     */
+    parseElement(element: Element, nextElement: Element): void;
+    parseElement_doc(element: Element, nextElement: Element): void;
+    /**
+     * Cleans up the HTML by calling certain helper methods
+     */
+    sanitizeHTML(html: string): string;
+    /**
+     * Replaces characters in the HTML as defined by the `replacementChars` parameter in the config
+     */
+    replaceUnwantedChars(html: string): string;
+    /**
+     * Replaces keywords in the HTML with links, as defined by the `replaceWithLinks` parameter in the config
+     */
+    replaceKeywordsWithLinks(html: string): string;
+    matchClassToExcludeNumber(className: string): boolean;
+    sanitizeElement(element: Element): void;
+    removeLastNumber(inputString: string): string;
+    getScaledWidth(width: number): string;
+    isTransparentTable(element: Element): boolean;
+    /**
+     * Extracts and calculates the column widths from a given HTML table element.
+     *
+     * This function reads `<col>` elements within a `<colgroup>` of the table and
+     * computes the pixel-based width for each column. It handles widths specified
+     * in percentages and pixels. If all widths are in pixels, they are scaled using
+     * a separate scaling method. If the computed widths are invalid or incomplete,
+     * the function returns `undefined`.
+     *
+     * @param {HTMLTableElement} table - The HTML table element from which column widths are to be extracted.
+     * @returns {number[] | undefined} An array of column widths in pixels, or `undefined` if the widths are invalid or missing.
+     */
+    getColWidthArray(table: HTMLTableElement): number[] | undefined;
+    setCellWidth(colSpan: number, cellIndex: number, colWidthArray: number[]): number[];
+    scaleWidthArray(rawWidthArray: number[]): number[];
+    getSumOfArray(array: number[]): number;
+    /**
+     * Determines the orientation (portrait or landscape) based on the total width.
+     *
+     * @param {number} totalWidth - The total width (in pixels) used to determine orientation.
+     * @returns {'portrait' | 'landscape'} Returns 'portrait' if the width is less than 700 pixels; otherwise, returns 'landscape'.
+     */
+    findOrientation(totalWidth: number): 'portrait' | 'landscape';
+    /**
+     * Extracts image information from an HTMLImageElement.
+     *
+     * @param {HTMLImageElement} img - The image element to extract information from.
+     * @returns {{ src: string; alt: string; width: number; height: number }} An object containing the image's source URL, alt text, width, and height.
+     */
+    extractImageInfo(img: HTMLImageElement): ImageInfo;
+    /**
+     * Extracts note paragraphs from the last row of an HTML table if that row
+     * contains a note header such as "OVERALL NOTE:" or "NOTES:".
+     *
+     * This function is designed for tables where the final row may optionally
+     * contain a note. If such a note exists, it returns all <p> elements inside
+     * the first <td> of that row, excluding the header line itself
+     * (e.g., "OVERALL NOTE:" / "NOTES:").
+     *
+     * The returned <p> elements are kept as HTMLElement nodes so that they can
+     * be further converted into structured ProseMirror content
+     * (e.g., using NewLicitParagraphElement).
+     *
+     * If the table doesn't contain a note row, or if the expected structure is missing,
+     * the function safely returns null.
+     *
+     * @param {HTMLTableSectionElement} table - The HTML table section (tbody) to extract the note from.
+     * @returns {HTMLElement[] | null} - An array of <p> nodes representing the note paragraphs,
+     *                                   or null if no note row was found.
+     */
+    private extractNote;
+    /**
+     * Determines whether the given DOM element should be treated as a "table figure".
+     *
+     * Business context:
+     * As per mail send on 07 Aug 2025:
+     * > "Can we sense when there is an image and a line or two of text – maybe remove the vignette control."
+     *
+     * This function implements that detection logic by identifying elements that match
+     * either of the following patterns:
+     *
+     * 1. It is **not** a <DIV> element, and its first child element is an <IMG>.
+     * 2. It is a <DIV> element that:
+     *    - Contains at least one <IMG> element anywhere inside (at any depth),
+     *    - Contains exactly one <P> element anywhere inside,
+     *    - That <P> element's trimmed text content is less than 100 characters
+     *      (representing "a line or two of text").
+     *
+     * @param {Element} node - The DOM element to check.
+     * @returns {boolean} `true` if the element qualifies as a table figure, otherwise `false`.
+     */
+    isTableFigureNode(node: Element): boolean;
+    /**
+     * Determines whether the provided class name corresponds to a note-related node.
+     *
+     * Checks if the given `className` matches any of the predefined note classes,
+     * such as examples, notes, cautions, or warnings.
+     *
+     * @param className - The CSS class name to check.
+     * @returns `true` if the class name is a recognized note node; otherwise, `false`.
+     */
+    private isNoteNode;
+}
+export {};