@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/model/properties/PropertyResolver.d.mts

@@ -0,0 +1,216 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { NumberingDefinitions } from '../listnumbering/definitions.mjs';
+/** The parts the resolver reads. Structural, so this module imports no part class. */
+export interface ResolverSource {
+    /** The styles part's `w:styles`, or undefined when the package has none. */
+    styles?: wml.Styles;
+    /** The numbering part's `w:numbering`, or undefined. */
+    numbering?: wml.Numbering;
+}
+/** As much of an `XmlPart<T>` as the resolver uses. */
+interface ReadablePart<T> {
+    readContents(): Promise<T>;
+    readonly isUnmarshalled: boolean;
+    readonly contents: T;
+}
+/** What `create` accepts: a WordprocessingMLPackage, or the trees on their own. */
+interface PackageLike {
+    getMainDocumentPart(): {
+        styleDefinitionsPart?: ReadablePart<wml.Styles>;
+        numberingDefinitionsPart?: ReadablePart<wml.Numbering>;
+    };
+}
+/** 108 twips (0.08in): the left and right cell margin of Word's built-in Normal Table. */
+export declare const WORD_DEFAULT_CELL_MARGIN_TWIPS = 108;
+/**
+ * The outline level (1-9) of a built-in heading style, from its `w:name` ("heading 1" ...
+ * "heading 9"), or -1. Word identifies built-in styles by name, so this holds in every locale;
+ * {@link PropertyResolver.getLvlFromHeadingStyle} keys on the English style id.
+ */
+export declare function headingLevelByName(style: wml.Style | undefined): number;
+export declare class PropertyResolver {
+    private readonly provider;
+    /** Set when the styles tree the resolver holds is not the styles part's own. */
+    private readonly stylesArePrivate;
+    private documentDefaultPPr;
+    private documentDefaultRPr;
+    /** All styles in the styles part, keyed by style id (docx4j's `liveStyles`). */
+    private readonly liveStyles;
+    /** How many styles the part held when `liveStyles` was last scanned; a miss rescans only when that has changed. */
+    private scannedStyleCount;
+    /** A style's `w:basedOn` chain merged root-first, WITHOUT the document defaults, per style id. */
+    private readonly chainPPrCache;
+    private readonly chainRPrCache;
+    /** The document defaults with the chain applied over them: what the style overloads return. */
+    private readonly effectivePPrByStyle;
+    private readonly effectiveRPrByStyle;
+    /** Missing styles are logged once each per resolver. */
+    private readonly missingLogged;
+    private numberingDefinitions;
+    defaultParagraphStyleId: string | undefined;
+    private defaultCharacterStyleId;
+    private defaultTableStyleId;
+    private source;
+    private constructor();
+    /**
+     * Builds a resolver over a package's styles and numbering parts (docx4j's constructor,
+     * which can do this synchronously because JAXB is).
+     *
+     * The parts are read with `readContents()`, which does **not** mark them unmarshalled, so a
+     * document whose styles nobody has edited still saves byte for byte. Once something else
+     * unmarshals the part - the comment styles, a caller's `getContents()` - `refresh()` picks
+     * up that live tree instead of the private copy.
+     */
+    static create(pkg: PackageLike | ResolverSource): Promise<PropertyResolver>;
+    /** Builds a resolver over object trees directly (a test, or parts already in hand). */
+    static fromSource(source: ResolverSource): PropertyResolver;
+    private init;
+    /** (Re)read the styles part into `liveStyles`. A style with no id is skipped. */
+    private scanStyles;
+    /**
+     * The style with this id, rescanning the styles part on a miss - and only when the list's
+     * size has changed - so that a style *added* to the part after this resolver was built is
+     * still found. A style *modified* or *removed* needs {@link refresh}.
+     */
+    private getLiveStyle;
+    private logMissing;
+    /**
+     * Discard cached state and re-read the styles part. A style merely *added* is picked up
+     * automatically; call this when a style has been modified or removed, or the styles part's
+     * contents replaced. The content API calls it where it creates a style.
+     */
+    refresh(): void;
+    getDocumentDefaultPPr(): wml.PPr;
+    getDocumentDefaultRPr(): wml.RPr;
+    /** The style id of the `w:default="1"` paragraph style, or undefined when the part declares none. */
+    getDefaultParagraphStyleId(): string | undefined;
+    /** The default paragraph style's effective `w:pPr`, as `getEffectivePPr(styleId)` gives it. */
+    getResolvedDefaultParagraphStyle(): wml.PPr;
+    /** The style with this id, or undefined (docx4j `getStyle`). */
+    getStyle(styleId: string | undefined): wml.Style | undefined;
+    /**
+     * The list definitions of the numbering part this resolver read (CR-001 Phase B step 3), or
+     * undefined where the package has none. The resolver builds them because the paragraph merge
+     * folds a numbering level's `w:ind` into every layer (`NumberingDefinitionsPart.getInd`);
+     * `NumberingDefinitionsPart.definitions` hands out this same object, so the counting and the
+     * indents read one set of definitions.
+     */
+    getNumberingDefinitions(): NumberingDefinitions | undefined;
+    /**
+     * The style and the styles it is based on, root first (the base of the chain at index 0, the
+     * style itself last); empty for an unknown id. A cycle, or a chain deeper than 32, ends the
+     * walk where it is detected (and throws `CyclicStylesException` when
+     * `throwOnCyclicStyles(true)` is set).
+     */
+    ancestry(styleId: string | undefined): wml.Style[];
+    /**
+     * A paragraph style's `w:basedOn` chain merged root-first, WITHOUT the document defaults:
+     * what the style contributes on its own. A live, cached object: copy before changing.
+     */
+    getChainPPr(styleId: string | undefined): wml.PPr;
+    /**
+     * A style's `w:basedOn` chain merged root-first, WITHOUT the document defaults: for a
+     * character style, what it contributes over the paragraph's run properties. A live, cached
+     * object: copy before changing.
+     */
+    getChainRPr(styleId: string | undefined): wml.RPr;
+    /**
+     * A style's own `w:pPr` as a layer of its chain. The built-in heading styles have a fixed
+     * outline level, which Word takes from the style's built-in NAME ("heading 1" ...
+     * "heading 9", the same in every locale; the style id is localised: "Überschrift1",
+     * "Titre1"), whatever `w:outlineLvl` the style declares: where they differ the layer is a
+     * copy with the level from the name, and the styles part is not touched.
+     */
+    private headingLayer;
+    private applyPPrLayer;
+    /** The paragraph's style: its `w:pStyle` where that names a style that exists, else the default paragraph style. */
+    private paragraphStyleOf;
+    /** `styleId` if it names a style that exists, else the default paragraph style's id (logged once). */
+    private existingParagraphStyle;
+    /**
+     * The paragraph properties which actually apply, given a paragraph's own `w:pPr`: the
+     * document defaults, the paragraph style's chain, then the direct formatting. Run properties
+     * are not resolved here; the paragraph mark's `w:rPr` is carried as `pPr/rPr` but is not a
+     * run's formatting ({@link getEffectiveParagraphMarkRPr}).
+     *
+     * What is returned is a live object when the paragraph states no direct formatting: copy it
+     * before changing it.
+     */
+    getEffectivePPr(pPr: wml.PPr | undefined): wml.PPr;
+    /**
+     * The paragraph properties a style resolves to (document defaults included). A style id
+     * naming no style resolves as the default paragraph style does.
+     */
+    getEffectivePPr(styleId: string | undefined): wml.PPr;
+    private effectivePPrOfStyle;
+    /**
+     * The run properties which apply to a run, given its own `w:rPr` and the `w:pPr` of the
+     * paragraph it is in: document defaults, the paragraph style's run properties, the run's
+     * character style, then its direct formatting. A new object each call.
+     *
+     * The paragraph mark's `w:rPr` is never applied to a run; for the mark itself see
+     * {@link getEffectiveParagraphMarkRPr}.
+     */
+    getEffectiveRPr(rPr: wml.RPr | undefined, pPr?: wml.PPr | undefined): wml.RPr;
+    /**
+     * The run properties a style resolves to on its own: document defaults, then its `w:basedOn`
+     * chain. For a paragraph style, the run properties of its paragraphs; for a character style,
+     * what it contributes with nothing under it. Undefined when no such style exists.
+     */
+    getEffectiveRPr(styleId: string): wml.RPr | undefined;
+    private effectiveRPrOfStyle;
+    /**
+     * The character style's chain, then the direct formatting.
+     *
+     * The character style is a **level** of the style hierarchy over the paragraph's, so its
+     * toggle properties are XORed with what is beneath rather than overriding it (ECMA-376-1
+     * §17.7.3). The direct formatting after it is not a level: an explicit value there is used
+     * as it stands.
+     */
+    private applyCharacterStyleAndDirect;
+    /**
+     * The run properties of the paragraph mark: document defaults, the paragraph style's run
+     * properties, then the `w:pPr`'s own `w:rPr`. What sizes an empty paragraph, and what a list
+     * label starts from.
+     */
+    getEffectiveParagraphMarkRPr(pPr: wml.PPr | undefined): wml.RPr;
+    /** Whether the run states any formatting of its own (docx4j's deprecated `hasDirectRPrFormatting`). */
+    hasDirectRPrFormatting(rPr: wml.RPr | undefined): boolean;
+    /**
+     * The table style which applies, merged root-first down its `w:basedOn` chain, then the
+     * table's own `w:tblPr` over it.
+     *
+     * Word's built-in "Normal Table" (`w:tblInd` 0; cell margins 108 twips left and right, 0 top
+     * and bottom) underlies a table naming no style and a table whose chain reaches the
+     * document's default table style - and it is the built-in that applies, not the document's
+     * definition of that style (measured, CR-015 probe styles-table-default). So the default
+     * style's own layer is skipped in favour of the built-in, and a chain that does not reach it
+     * starts from nothing.
+     *
+     * A new `Style` each call, with a non-null `w:tblPr`.
+     */
+    getEffectiveTableStyle(tblPr: wml.CTTblPrBase | undefined): wml.Style;
+    /**
+     * Whether a table's style chain reaches the document's default table style - the flag
+     * {@link getEffectiveTableStyle} decides Word's built-in Normal Table by (a table naming no
+     * style counts as reaching it).
+     */
+    reachesDefaultTableStyle(tblPr: wml.CTTblPrBase | undefined): boolean;
+    /** Word's built-in Normal Table, as a style: what it applies whatever the document's own definition says. */
+    private builtInTableNormal;
+    /**
+     * The level of a heading style from its **id** ("Heading2" -> 2), or -1. docx4j keeps this
+     * because callers pass a style id; {@link headingLevelByName} is the rule Word applies, and
+     * is what resolution uses.
+     */
+    getLvlFromHeadingStyle(styleId: string): number;
+    /**
+     * Make a style available for use in the document, adding it to the styles part - and,
+     * recursively, whatever it is `w:basedOn` and whatever it is linked to. Given a style id,
+     * the style must be one this package knows (there is no KnownStyles.xml here yet; a style id
+     * that is not already live and not supplied as an object returns false).
+     */
+    activateStyle(style: wml.Style | string): boolean;
+    private activate;
+}
+export {};