@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/query/style-resolve.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Style Resolution (Effective/Computed Style)
+ *
+ * Resolve the effective style for a paragraph by walking the style inheritance chain.
+ */
+import type { DocxDocument, Paragraph, ParagraphProperties, Run, RunProperties, TableLook, TableProperties } from "../types.js";
+/** Context for style resolution when a paragraph is inside a table. */
+export interface StyleResolveContext {
+    /** If the paragraph is inside a table, provide table context. */
+    readonly tableContext?: {
+        readonly tableStyleId?: string;
+        readonly tblLook?: TableLook;
+        readonly rowIndex: number;
+        readonly colIndex: number;
+        readonly totalRows: number;
+        readonly totalCols: number;
+    };
+}
+/** Resolved paragraph properties with all inherited values merged. */
+export interface ResolvedParagraphStyle {
+    /** The style chain (from most specific to base). */
+    readonly chain: readonly string[];
+    /** Merged paragraph properties (inherited + own). */
+    readonly paragraphProperties: ParagraphProperties;
+    /** Merged run properties (inherited + own). */
+    readonly runProperties: RunProperties;
+}
+/**
+ * Resolve the effective (computed) style for a paragraph by walking the style inheritance chain.
+ *
+ * Merges properties from the document defaults → base style chain → table conditional formats → paragraph's own properties.
+ *
+ * @param doc - The document containing styles and defaults.
+ * @param para - The paragraph to resolve styles for.
+ * @param context - Optional context providing table position for conditional format overlay.
+ * @returns The fully resolved paragraph style with all inherited properties merged.
+ */
+export declare function resolveStyle(doc: DocxDocument, para: Paragraph, context?: StyleResolveContext): ResolvedParagraphStyle;
+/** Resolved run style with full inheritance chain. */
+export interface ResolvedRunStyle {
+    /** Style chain (most specific → base). */
+    readonly chain: readonly string[];
+    /** Merged run properties. */
+    readonly runProperties: RunProperties;
+}
+/**
+ * Resolve the effective style for a single Run by walking the character
+ * style inheritance chain.
+ *
+ * Resolution order (low → high specificity):
+ * 1. Document defaults
+ * 2. Paragraph's resolved style (if `paragraphRunProperties` provided)
+ * 3. Run's character style chain (if `run.properties.style` is set)
+ * 4. Run's own direct properties
+ *
+ * @param doc - The document containing styles.
+ * @param run - The run to resolve.
+ * @param paragraphRunProperties - Optional inherited run properties from the
+ *   parent paragraph's resolved style. Pass `resolveStyle(doc, para).runProperties`
+ *   to layer the paragraph style on top of doc defaults.
+ * @returns The fully resolved run style.
+ */
+export declare function resolveRunStyle(doc: DocxDocument, run: Run, paragraphRunProperties?: RunProperties): ResolvedRunStyle;
+/** Resolved numbering level information. */
+export interface ResolvedNumberingLevel {
+    /** The level index (0-8). */
+    readonly level: number;
+    /** Number format. */
+    readonly format?: string;
+    /** Level text template (e.g. `"%1."`). */
+    readonly text?: string;
+    /** Justification. */
+    readonly justification?: string;
+    /** Run properties for the numbering text itself (bullet/number marker). */
+    readonly runProperties?: RunProperties;
+    /** Paragraph properties from the level (indent, alignment, etc.). */
+    readonly paragraphProperties?: ParagraphProperties;
+}
+/**
+ * Resolve the numbering level for a paragraph that has a numbering reference.
+ *
+ * Walks: paragraph.numbering → numberingInstances → abstractNumberings → level definition.
+ * Also applies `LevelOverride` if present.
+ *
+ * @param doc - The document.
+ * @param para - The paragraph (must have `numbering` set).
+ * @returns The resolved level, or undefined if no numbering or level not found.
+ */
+export declare function resolveNumberingLevel(doc: DocxDocument, para: Paragraph): ResolvedNumberingLevel | undefined;
+/**
+ * Resolve table-level styles for a given table.
+ *
+ * Walks the table style inheritance chain (basedOn) to merge table properties.
+ *
+ * @param doc - The document.
+ * @param tableStyleId - The starting table style ID.
+ * @returns The merged table-level style chain.
+ */
+export declare function resolveTableStyle(doc: DocxDocument, tableStyleId: string): {
+    chain: string[];
+    paragraphProperties: ParagraphProperties;
+    runProperties: RunProperties;
+    tableProperties?: TableProperties;
+};

package/dist/browser/modules/word/query/style-resolve.js

@@ -0,0 +1,368 @@
+/**
+ * Style Resolution (Effective/Computed Style)
+ *
+ * Resolve the effective style for a paragraph by walking the style inheritance chain.
+ */
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Resolve the effective (computed) style for a paragraph by walking the style inheritance chain.
+ *
+ * Merges properties from the document defaults → base style chain → table conditional formats → paragraph's own properties.
+ *
+ * @param doc - The document containing styles and defaults.
+ * @param para - The paragraph to resolve styles for.
+ * @param context - Optional context providing table position for conditional format overlay.
+ * @returns The fully resolved paragraph style with all inherited properties merged.
+ */
+export function resolveStyle(doc, para, context) {
+    const styleMap = new Map();
+    if (doc.styles) {
+        for (const s of doc.styles) {
+            styleMap.set(s.styleId, s);
+        }
+    }
+    // Walk the chain from paragraph's style to root
+    const chain = [];
+    const styleId = para.properties?.style;
+    if (styleId) {
+        let current = styleId;
+        const visited = new Set();
+        while (current && !visited.has(current)) {
+            visited.add(current);
+            chain.push(current);
+            const def = styleMap.get(current);
+            current = def?.basedOn;
+        }
+    }
+    // Build merged properties: start from doc defaults, apply chain bottom-up, then paragraph
+    let mergedPProps = {};
+    let mergedRProps = {};
+    // Document defaults
+    if (doc.docDefaults) {
+        if (doc.docDefaults.paragraphProperties) {
+            mergedPProps = { ...doc.docDefaults.paragraphProperties };
+        }
+        if (doc.docDefaults.runProperties) {
+            mergedRProps = { ...doc.docDefaults.runProperties };
+        }
+    }
+    // Apply style chain (from base to most specific)
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const def = styleMap.get(chain[i]);
+        if (!def) {
+            continue;
+        }
+        if (def.paragraphProperties) {
+            mergedPProps = { ...mergedPProps, ...stripUndefined(def.paragraphProperties) };
+        }
+        if (def.runProperties) {
+            mergedRProps = { ...mergedRProps, ...stripUndefined(def.runProperties) };
+        }
+        // Linked styles: if a paragraph style links to a character style, merge its runProperties.
+        // The linked character style's runProperties layer on top of the paragraph style's own
+        // runProperties at the same level, giving the linked style slightly higher specificity.
+        if (def.type === "paragraph" && def.link) {
+            const linkedDef = styleMap.get(def.link);
+            if (linkedDef?.type === "character" && linkedDef.runProperties) {
+                mergedRProps = { ...mergedRProps, ...stripUndefined(linkedDef.runProperties) };
+            }
+        }
+    }
+    // Apply table conditional format overlay (higher priority than base table/paragraph style,
+    // but lower priority than paragraph's own direct properties).
+    if (context?.tableContext?.tableStyleId) {
+        const tblCtx = context.tableContext;
+        const tableStyleId = tblCtx.tableStyleId;
+        const tblStyleDef = styleMap.get(tableStyleId);
+        if (tblStyleDef?.tableStyleConditions) {
+            const matchingConditions = getMatchingTableConditions(tblStyleDef.tableStyleConditions, tblCtx.tblLook, tblCtx.rowIndex, tblCtx.colIndex, tblCtx.totalRows, tblCtx.totalCols);
+            for (const cond of matchingConditions) {
+                if (cond.paragraphProperties) {
+                    mergedPProps = { ...mergedPProps, ...stripUndefined(cond.paragraphProperties) };
+                }
+                if (cond.runProperties) {
+                    mergedRProps = { ...mergedRProps, ...stripUndefined(cond.runProperties) };
+                }
+            }
+        }
+    }
+    // Apply paragraph's own properties (most specific)
+    if (para.properties) {
+        const { style: _s, sectionProperties: _sp, ...ownPProps } = para.properties;
+        mergedPProps = { ...mergedPProps, ...stripUndefined(ownPProps) };
+    }
+    return {
+        chain,
+        paragraphProperties: mergedPProps,
+        runProperties: mergedRProps
+    };
+}
+// =============================================================================
+// Internal helpers
+// =============================================================================
+/** Remove undefined values from an object (so spreading doesn't override with undefined). */
+function stripUndefined(obj) {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined) {
+            result[k] = v;
+        }
+    }
+    return result;
+}
+/**
+ * Determine which table style conditions match the given cell position.
+ *
+ * Returns matching conditions in application order (banding → whole row/col → corner cells).
+ * Within Word, the specificity order from lowest to highest is:
+ *   banding → first/last row/col → corner cells.
+ */
+function getMatchingTableConditions(conditions, look, rowIndex, colIndex, totalRows, totalCols) {
+    // Resolve effective banding flags: noHBand means band rows are disabled,
+    // noVBand means band columns are disabled.
+    const bandRow = look?.noHBand !== true;
+    const bandCol = look?.noVBand !== true;
+    // Build a set of applicable condition types based on position and tblLook.
+    const applicable = new Set();
+    // Banding (lowest priority among conditions)
+    if (bandRow) {
+        if (rowIndex % 2 === 0) {
+            applicable.add("oddRowBanding");
+        }
+        else {
+            applicable.add("evenRowBanding");
+        }
+    }
+    if (bandCol) {
+        if (colIndex % 2 === 0) {
+            applicable.add("oddColumnBanding");
+        }
+        else {
+            applicable.add("evenColumnBanding");
+        }
+    }
+    // Whole row/column conditions
+    if (rowIndex === 0 && look?.firstRow !== false) {
+        applicable.add("firstRow");
+    }
+    if (rowIndex === totalRows - 1 && look?.lastRow !== false) {
+        applicable.add("lastRow");
+    }
+    if (colIndex === 0 && look?.firstColumn !== false) {
+        applicable.add("firstColumn");
+    }
+    if (colIndex === totalCols - 1 && look?.lastColumn !== false) {
+        applicable.add("lastColumn");
+    }
+    // Corner cells (highest priority among conditions)
+    if (rowIndex === 0 && colIndex === 0 && look?.firstRow !== false && look?.firstColumn !== false) {
+        applicable.add("topLeftCell");
+    }
+    if (rowIndex === 0 &&
+        colIndex === totalCols - 1 &&
+        look?.firstRow !== false &&
+        look?.lastColumn !== false) {
+        applicable.add("topRightCell");
+    }
+    if (rowIndex === totalRows - 1 &&
+        colIndex === 0 &&
+        look?.lastRow !== false &&
+        look?.firstColumn !== false) {
+        applicable.add("bottomLeftCell");
+    }
+    if (rowIndex === totalRows - 1 &&
+        colIndex === totalCols - 1 &&
+        look?.lastRow !== false &&
+        look?.lastColumn !== false) {
+        applicable.add("bottomRightCell");
+    }
+    // Filter and sort conditions by specificity order:
+    // banding < first/last row/col < corner cells
+    const priorityOrder = [
+        "oddRowBanding",
+        "evenRowBanding",
+        "oddColumnBanding",
+        "evenColumnBanding",
+        "firstRow",
+        "lastRow",
+        "firstColumn",
+        "lastColumn",
+        "topLeftCell",
+        "topRightCell",
+        "bottomLeftCell",
+        "bottomRightCell"
+    ];
+    const priorityMap = new Map();
+    for (let i = 0; i < priorityOrder.length; i++) {
+        priorityMap.set(priorityOrder[i], i);
+    }
+    return conditions
+        .filter(c => applicable.has(c.type))
+        .sort((a, b) => (priorityMap.get(a.type) ?? 0) - (priorityMap.get(b.type) ?? 0));
+}
+/**
+ * Resolve the effective style for a single Run by walking the character
+ * style inheritance chain.
+ *
+ * Resolution order (low → high specificity):
+ * 1. Document defaults
+ * 2. Paragraph's resolved style (if `paragraphRunProperties` provided)
+ * 3. Run's character style chain (if `run.properties.style` is set)
+ * 4. Run's own direct properties
+ *
+ * @param doc - The document containing styles.
+ * @param run - The run to resolve.
+ * @param paragraphRunProperties - Optional inherited run properties from the
+ *   parent paragraph's resolved style. Pass `resolveStyle(doc, para).runProperties`
+ *   to layer the paragraph style on top of doc defaults.
+ * @returns The fully resolved run style.
+ */
+export function resolveRunStyle(doc, run, paragraphRunProperties) {
+    const styleMap = new Map();
+    if (doc.styles) {
+        for (const s of doc.styles) {
+            styleMap.set(s.styleId, s);
+        }
+    }
+    // Build chain from run's character style
+    const chain = [];
+    const runStyleId = run.properties?.style;
+    if (runStyleId) {
+        let current = runStyleId;
+        const visited = new Set();
+        while (current && !visited.has(current)) {
+            visited.add(current);
+            chain.push(current);
+            const def = styleMap.get(current);
+            current = def?.basedOn;
+        }
+    }
+    let merged = {};
+    // 1. Document defaults
+    if (doc.docDefaults?.runProperties) {
+        merged = { ...doc.docDefaults.runProperties };
+    }
+    // 2. Inherited from paragraph's resolved style
+    if (paragraphRunProperties) {
+        merged = { ...merged, ...stripUndefined(paragraphRunProperties) };
+    }
+    // 3. Run's character style chain (base → specific)
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const def = styleMap.get(chain[i]);
+        if (def?.runProperties) {
+            merged = { ...merged, ...stripUndefined(def.runProperties) };
+        }
+    }
+    // 4. Run's own direct properties (highest priority)
+    if (run.properties) {
+        const { style: _s, ...own } = run.properties;
+        merged = { ...merged, ...stripUndefined(own) };
+    }
+    return {
+        chain,
+        runProperties: merged
+    };
+}
+/**
+ * Resolve the numbering level for a paragraph that has a numbering reference.
+ *
+ * Walks: paragraph.numbering → numberingInstances → abstractNumberings → level definition.
+ * Also applies `LevelOverride` if present.
+ *
+ * @param doc - The document.
+ * @param para - The paragraph (must have `numbering` set).
+ * @returns The resolved level, or undefined if no numbering or level not found.
+ */
+export function resolveNumberingLevel(doc, para) {
+    const numRef = para.properties?.numbering;
+    if (!numRef) {
+        return undefined;
+    }
+    // Find numbering instance
+    const instance = doc.numberingInstances?.find(n => n.numId === numRef.numId);
+    if (!instance) {
+        return undefined;
+    }
+    // Check for level override first
+    const override = instance.overrides?.find(o => o.level === numRef.level);
+    let levelDef;
+    if (override?.levelDef) {
+        levelDef = override.levelDef;
+    }
+    else {
+        // Walk to abstract numbering
+        const absNum = doc.abstractNumberings?.find(a => a.abstractNumId === instance.abstractNumId);
+        levelDef = absNum?.levels.find(l => l.level === numRef.level);
+    }
+    if (!levelDef) {
+        return undefined;
+    }
+    return {
+        level: levelDef.level,
+        format: levelDef.format,
+        text: levelDef.text,
+        justification: levelDef.justification,
+        runProperties: levelDef.runProperties,
+        paragraphProperties: levelDef.paragraphProperties
+    };
+}
+/**
+ * Resolve table-level styles for a given table.
+ *
+ * Walks the table style inheritance chain (basedOn) to merge table properties.
+ *
+ * @param doc - The document.
+ * @param tableStyleId - The starting table style ID.
+ * @returns The merged table-level style chain.
+ */
+export function resolveTableStyle(doc, tableStyleId) {
+    const styleMap = new Map();
+    if (doc.styles) {
+        for (const s of doc.styles) {
+            styleMap.set(s.styleId, s);
+        }
+    }
+    const chain = [];
+    let current = tableStyleId;
+    const visited = new Set();
+    while (current && !visited.has(current)) {
+        visited.add(current);
+        chain.push(current);
+        const def = styleMap.get(current);
+        current = def?.basedOn;
+    }
+    let pProps = {};
+    let rProps = {};
+    let tProps = {};
+    // Apply doc defaults first
+    if (doc.docDefaults?.paragraphProperties) {
+        pProps = { ...doc.docDefaults.paragraphProperties };
+    }
+    if (doc.docDefaults?.runProperties) {
+        rProps = { ...doc.docDefaults.runProperties };
+    }
+    // Apply chain (base → specific)
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const def = styleMap.get(chain[i]);
+        if (!def) {
+            continue;
+        }
+        if (def.paragraphProperties) {
+            pProps = { ...pProps, ...stripUndefined(def.paragraphProperties) };
+        }
+        if (def.runProperties) {
+            rProps = { ...rProps, ...stripUndefined(def.runProperties) };
+        }
+        if (def.tableProperties) {
+            tProps = { ...tProps, ...stripUndefined(def.tableProperties) };
+        }
+    }
+    return {
+        chain,
+        paragraphProperties: pProps,
+        runProperties: rProps,
+        tableProperties: Object.keys(tProps).length > 0 ? tProps : undefined
+    };
+}

package/dist/browser/modules/word/reader/chart-parser.d.ts

@@ -0,0 +1,20 @@
+/**
+ * DOCX Reader - Chart Parser (c: and cx: namespaces)
+ *
+ * Parses traditional and ChartEx (Microsoft 365) chart XML into Chart model
+ * objects. Also resolves chart references in the document body, replacing
+ * opaque chart drawings with parsed Chart instances.
+ */
+import type { BodyContent, Chart, ChartExContent, ChartExData } from "../types.js";
+/** Replace OpaqueDrawing items referencing chart rIds with ChartContent. */
+declare function replaceOpaqueCharts(body: BodyContent[], chartRIdToChart: Map<string, Chart>): void;
+/** Replace OpaqueDrawing items referencing ChartEx rIds with ChartExContent. */
+declare function replaceOpaqueChartExDrawings(body: BodyContent[], chartExRIdToContent: Map<string, ChartExContent>): void;
+/** Parse a chart part XML string into a Chart object. */
+declare function parseChartXml(xmlStr: string): Chart | undefined;
+/**
+ * Parse a ChartEx XML string (cx:chartSpace) into structured ChartExData.
+ * Returns undefined if parsing fails or the structure is unrecognizable.
+ */
+declare function parseChartExXml(xmlStr: string): ChartExData | undefined;
+export { replaceOpaqueCharts, replaceOpaqueChartExDrawings, parseChartXml, parseChartExXml };