@docx4j/core-ts 0.1.0 → 0.1.1

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

@@ -0,0 +1,179 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+/** Run properties: `w:rPr` and the paragraph mark's `w:pPr/w:rPr`, which have the same members. */
+export type RunProps = wml.RPr | wml.ParaRPr;
+/** How a more specific value merges over an inherited one. Returns the value to store. */
+export type Merge<V> = (source: V | undefined, destination: V | undefined) => V | undefined;
+/**
+ * One member of a properties element: its name, accessors, merge, emptiness and whether it
+ * formats the content (as opposed to naming a style, recording a revision, or caching a
+ * computed condition).
+ */
+export interface Property<O, V> {
+    readonly name: string;
+    /** False for a style reference, a revision record or Word's condition cache: `hasDirectFormatting` leaves those out. */
+    readonly isFormatting: boolean;
+    /**
+     * Whether `isEmpty(owner)` counts this member. False for the few members docx4j's
+     * hand-written `isEmpty` omits (`w:bidiVisual`, `w:tblCaption`, `w:tblDescription`), kept
+     * so that the tables stay one-entry-per-member and the quirk stays visible.
+     */
+    readonly countsEmpty: boolean;
+    get(owner: O): V | undefined;
+    set(owner: O, value: V | undefined): void;
+    merge(source: V | undefined, destination: V | undefined): V | undefined;
+    isEmpty(value: V | undefined): boolean;
+    /** A copy of a value of this member's type, sharing nothing with it. */
+    copyOf(value: V): V;
+}
+/**
+ * A structural copy of a leaf value, without its `PARENT` link: what the merges store, so
+ * that nothing in an effective `w:pPr` or `w:rPr` is a styles-part object.
+ */
+export declare function copyLeaf<T>(value: T): T;
+/** A merge with no per-attribute rule: a copy of the source where it has one, else the inherited. */
+export declare function mergeReplace<V>(source: V | undefined, destination: V | undefined): V | undefined;
+/** `<w:b/>` and `<w:b w:val="0"/>` both count: an explicit false is applied. */
+export declare function isEmptyBool(value: wml.BooleanDefaultTrue | undefined): boolean;
+/** A `BooleanDefaultTrue`'s value: absent `w:val` means true (docx4j `isVal()`). */
+export declare function isTrue(value: wml.BooleanDefaultTrue | undefined): boolean;
+export declare function isEmptyRStyle(value: wml.RStyle | undefined): boolean;
+/** docx4j `isEmpty(RFonts)`: insensitive to a `w:hint` (which `apply` still carries). */
+export declare function isEmptyRFonts(value: wml.RFonts | undefined): boolean;
+export declare function isEmptyColor(value: wml.Color | undefined): boolean;
+export declare function isEmptyU(value: wml.U | undefined): boolean;
+export declare function isEmptyHighlight(value: wml.Highlight | undefined): boolean;
+/** @since CR-015 phase 1: a style stating only `w:lang` used to count as empty and was never applied. */
+export declare function isEmptyLang(value: wml.CTLanguage | undefined): boolean;
+export declare function isEmptyShd(value: wml.CTShd | undefined): boolean;
+export declare function isEmptyBorder(value: wml.CTBorder | undefined): boolean;
+export declare function isEmptyPBdr(value: wml.PPrBase.PBdr | undefined): boolean;
+/**
+ * docx4j `isEmpty(Ind)`: `w:start`/`w:end` (the strict-conformance spellings) count too
+ * (17.0.5); dropping them lost them in style resolution.
+ */
+export declare function isEmptyInd(value: wml.PPrBase.Ind | undefined): boolean;
+/** An explicit `w:beforeAutospacing`/`w:afterAutospacing` of either value is a statement too. */
+export declare function isEmptySpacing(value: wml.PPrBase.Spacing | undefined): boolean;
+export declare function isEmptyTabs(value: wml.Tabs | undefined): boolean;
+/**
+ * A `w:numPr` is empty only when it states neither `w:numId` nor `w:ilvl`: each inherits on
+ * its own (CR-015 probe styles-numpr-ilvl-only).
+ */
+export declare function isEmptyNumPr(value: wml.PPrBase.NumPr | undefined): boolean;
+/** `w:anchorLock` defaults to true, so only an explicit `w:anchorLock="0"` makes a frame non-empty by itself. */
+export declare function isEmptyFramePr(value: wml.CTFramePr | undefined): boolean;
+/** docx4j `apply(BooleanDefaultTrue, BooleanDefaultTrue)`: a copy of the source where it states one. */
+export declare function mergeBool(source: wml.BooleanDefaultTrue | undefined, destination: wml.BooleanDefaultTrue | undefined): wml.BooleanDefaultTrue | undefined;
+export declare const mergeRStyle: Merge<wml.RStyle>;
+export declare const mergeHighlight: Merge<wml.Highlight>;
+export declare const mergeEm: Merge<wml.CTEm>;
+export declare const mergeVertAlign: Merge<wml.CTVerticalAlignRun>;
+export declare const mergeEffect: Merge<wml.CTTextEffect>;
+export declare const mergeHps: Merge<wml.HpsMeasure>;
+export declare const mergeSignedHps: Merge<wml.CTSignedHpsMeasure>;
+export declare const mergeSignedTwips: Merge<wml.CTSignedTwipsMeasure>;
+export declare const mergeTextScale: Merge<wml.CTTextScale>;
+export declare const mergeJc: Merge<wml.Jc>;
+export declare const mergeOutlineLvl: Merge<wml.PPrBase.OutlineLvl>;
+export declare const mergeTextAlignment: Merge<wml.PPrBase.TextAlignment>;
+export declare const mergeTextDirection: Merge<wml.TextDirection>;
+export declare const mergeTextboxTightWrap: Merge<wml.CTTextboxTightWrap>;
+export declare const mergeCnf: Merge<wml.CTCnf>;
+export declare const mergePStyle: Merge<wml.PPrBase.PStyle>;
+/**
+ * `w:rFonts`: a theme reference trumps an explicit face within one element, and a source with
+ * only a `w:hint` still says something. A null source leaves the destination alone (until
+ * CR-015 phase 1 it was given an empty `w:rFonts`, so every merged `w:rPr` read as directly
+ * formatted).
+ */
+export declare const mergeRFonts: Merge<wml.RFonts>;
+export declare const mergeColor: Merge<wml.Color>;
+/** `w:val` and the colour attributes each inherit on their own (CR-015 phase 1). */
+export declare const mergeU: Merge<wml.U>;
+/** `w:val`, `w:eastAsia` and `w:bidi` each name the language of one script range and each inherits. */
+export declare const mergeLang: Merge<wml.CTLanguage>;
+export declare const mergeShd: Merge<wml.CTShd>;
+export declare const mergeBorder: Merge<wml.CTBorder>;
+export declare const mergePBdr: Merge<wml.PPrBase.PBdr>;
+/** `w:numId` and `w:ilvl` each inherit on their own; see {@link isEmptyNumPr}. */
+export declare const mergeNumPr: Merge<wml.PPrBase.NumPr>;
+/**
+ * `w:ind`: `w:firstLine` and `w:hanging` are two spellings of one property (ECMA-376
+ * 17.3.1.12), so whichever of the two the more specific `w:ind` states replaces both; the
+ * rest inherit per attribute.
+ */
+export declare const mergeInd: Merge<wml.PPrBase.Ind>;
+/**
+ * `w:spacing`: the autospacing attributes survive the merge, and `w:lineRule` qualifies
+ * `w:line` - a source stating `w:line` states a rule too (auto when it names none), and a
+ * source stating no `w:line` leaves both inherited (CR-015 probe styles-linerule).
+ */
+export declare const mergeSpacing: Merge<wml.PPrBase.Spacing>;
+/**
+ * `w:tabs`: the custom tab stops are the union of those declared and those inherited, a stop
+ * at the same position replaces the inherited one, and `w:val="clear"` only removes
+ * (ECMA-376 17.3.1.38, 17.3.1.37). Word holds them in ascending position order.
+ */
+export declare const mergeTabs: Merge<wml.Tabs>;
+/**
+ * `w:framePr`'s attributes each inherit on their own: a paragraph whose direct `w:framePr`
+ * gives only `w:x`/`w:y` keeps the anchors its style states. `w:anchorLock` defaults to true,
+ * and docx4j's merge writes that default out explicitly.
+ */
+export declare const mergeFramePr: Merge<wml.CTFramePr>;
+/**
+ * The members of `w:rPr` (17.3.2) and of the paragraph mark's `w:pPr/w:rPr`, in schema order,
+ * plus the w14 extensions the generated interfaces carry. Not listed: `w:rPrChange` and the
+ * paragraph mark's `w:ins`/`w:del`/`w:moveFrom`/`w:moveTo`, which record revisions and are
+ * never inherited.
+ */
+export declare const RUN: readonly Property<RunProps, never>[];
+/** Members of `w:rPr` and `w:pPr/w:rPr` that are not in {@link RUN} (revision records). */
+export declare const RUN_EXCLUDED: readonly string[];
+/**
+ * The names of the **toggle properties** of `w:rPr`, in the order ECMA-376-1 §17.7.3 lists
+ * them. Twelve, and no more: `w:dstrike`, `w:noProof`, `w:snapToGrid`, `w:webHidden`,
+ * `w:rtl`, `w:cs`, `w:specVanish` and `w:oMath` are Boolean but are not toggles.
+ */
+export declare const TOGGLE_NAMES: ReadonlySet<string>;
+/** {@link TOGGLE_NAMES} as members of {@link RUN}. */
+export declare const TOGGLES: readonly Property<RunProps, wml.BooleanDefaultTrue>[];
+/** The `w:ind` member's name: the paragraph merge applies it last, after the numbering level's. */
+export declare const IND = "ind";
+/**
+ * The members of `w:pPr` shared with a style's `w:pPr` (`PPrBase`, 17.3.1), in schema order.
+ * Not formatting: `w:pStyle` (the style reference), `w:divId` (an HTML import artefact),
+ * `w:cnfStyle` (Word's cache of the table conditions that apply) and `w14:collapsed` (the
+ * outline view's state). A `w:pPr`'s own `w:rPr` (the paragraph mark) and `w:sectPr` are
+ * outside `PPrBase` and outside this list.
+ */
+export declare const PARAGRAPH: readonly Property<wml.PPrBase, never>[];
+/** Members of `w:pPr` that are not in {@link PARAGRAPH}: the mark, the section, the revision. */
+export declare const PARAGRAPH_EXCLUDED: readonly string[];
+/**
+ * The members of `w:tblPr` (`CTTblPrBase`, 17.4.60), in schema order.
+ *
+ * Three quirks of docx4j's hand-written pair are reproduced and flagged: `w:bidiVisual` is
+ * applied but not counted by `isEmpty`, and `w:tblCaption` and `w:tblDescription` are neither
+ * applied nor counted (they are a table's accessibility text, not formatting a style carries).
+ */
+export declare const TABLE: readonly Property<wml.CTTblPrBase, never>[];
+export declare const TABLE_EXCLUDED: readonly string[];
+/**
+ * The members of `w:tcPr` (`TcPr`, 17.4.68), in schema order. `w:cellIns`, `w:cellDel`,
+ * `w:cellMerge` and `w:tcPrChange` record revisions and are excluded.
+ */
+export declare const CELL: readonly Property<wml.TcPr, never>[];
+export declare const CELL_EXCLUDED: readonly string[];
+/** The member of that name, or undefined. */
+export declare function namedProperty<O>(catalogue: readonly Property<O, never>[], name: string): Property<O, never> | undefined;
+/** Whether every member of `owner` is empty. */
+export declare function isEmptyOf<O>(catalogue: readonly Property<O, never>[], owner: O | undefined): boolean;
+/** Whether any formatting member is present (an element that is there, even with no attributes, counts: it was stated). */
+export declare function hasDirectFormattingOf<O>(catalogue: readonly Property<O, never>[], owner: O | undefined): boolean;
+/** Apply every member of `source` over `destination`, in place, except those named. */
+export declare function applyCatalogue<O>(catalogue: readonly Property<O, never>[], source: O, destination: O, except?: ReadonlySet<string>): void;
+/** Apply one member of `source` over `destination`. */
+export declare function applyProperty<O, V>(p: Property<O, V>, source: O, destination: O): void;
+/** Unset in `destination` every member that `source` states. */
+export declare function unsetCatalogue<O>(catalogue: readonly Property<O, never>[], source: O, destination: O): void;