@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/document/paragraph-format.d.ts

@@ -0,0 +1,880 @@
+import { OpenXmlElement } from '../../core/xml/index';
+import { ParagraphAlignment } from './alignment';
+import { Color } from './color';
+import { CnfStyle, NormalizedCnfStyle } from '../tables/tbl-pr';
+/**
+ * Line spacing rule (`ST_LineSpacingRule`). §17.18.48
+ * @public
+ */
+export declare type LineSpacingRule = 'auto' | 'exact' | 'atLeast';
+/**
+ * Tab stop justification / alignment (`ST_TabJc`). §17.18.83
+ *
+ * Prefer named members such as {@link TabJustification.Left} in authoring APIs.
+ * Wire tokens are the member values and are unchanged for serialization.
+ *
+ * @public
+ */
+export declare const TabJustification: {
+    Left: "left";
+    Center: "center";
+    Right: "right";
+    Decimal: "decimal";
+    Bar: "bar";
+    Clear: "clear";
+    Num: "num";
+    Start: "start";
+    End: "end";
+};
+/**
+ * One of the {@link TabJustification} wire tokens.
+ *
+ * @public
+ */
+export declare type TabJustification = (typeof TabJustification)[keyof typeof TabJustification];
+/**
+ * Alias of {@link TabJustification} kept for older `TabStop.alignment` typing.
+ *
+ * @public
+ */
+export declare type TabStopAlignment = TabJustification;
+/**
+ * Tab stop leader character (`ST_TabTlc`). §17.18.84
+ *
+ * Prefer named members such as {@link TabLeader.Dot} / {@link TabLeader.NoLeader}.
+ * Wire tokens are the member values and are unchanged for serialization.
+ *
+ * @public
+ */
+export declare const TabLeader: {
+    NoLeader: "none";
+    Dot: "dot";
+    Heavy: "heavy";
+    Hyphen: "hyphen";
+    MiddleDot: "middleDot";
+    Single: "single";
+};
+/**
+ * One of the {@link TabLeader} wire tokens.
+ *
+ * @public
+ */
+export declare type TabLeader = (typeof TabLeader)[keyof typeof TabLeader];
+/**
+ * Alias of {@link TabLeader} kept for older `TabStop.leader` typing.
+ *
+ * @public
+ */
+export declare type TabStopLeader = TabLeader;
+/**
+ * A single tab stop (`w:tab` inside `w:tabs`). §17.3.1.37
+ * @public
+ */
+export interface TabStop {
+    /** `@w:pos` — position in points (twips on the wire). */
+    readonly position: number;
+    /** `@w:val` — alignment. */
+    readonly alignment: TabJustification;
+    /** `@w:leader` — leader character. */
+    readonly leader?: TabLeader;
+}
+/**
+ * Mutable DocIO-style tab-stop entry backed by {@link TabStop} storage.
+ * Distinct from run-level `w:r/w:tab` ({@link import('./text-range').Tab}).
+ *
+ * @public
+ */
+export declare class ParagraphTabStop {
+    private positionValue;
+    private justificationValue;
+    private leaderValue;
+    /**
+     * @public
+     */
+    constructor(position?: number, justification?: TabJustification, leader?: TabLeader);
+    /** Position in points. */
+    position: number;
+    /** Alignment / justification (`@w:val`). */
+    justification: TabJustification;
+    /** Alias of {@link ParagraphTabStop.justification}. */
+    alignment: TabStopAlignment;
+    /** Leader character. */
+    leader: TabLeader;
+    /** @private */
+    toBagStop(): TabStop;
+    /** @private */
+    static fromTabStop(stop: TabStop): ParagraphTabStop;
+}
+/**
+ * Live collection over paragraph tab stops. Mirrors bag {@link ParagraphFormat.tabStops}.
+ *
+ * @public
+ */
+export declare class TabCollection {
+    private readonly owner;
+    /** @private */
+    constructor(owner: ParagraphFormat);
+    /** Number of tab stops. */
+    readonly count: number;
+    /**
+     * Tab stop at index, or `undefined`.
+     */
+    item(index: number): ParagraphTabStop | undefined;
+    /**
+     * Add a tab stop (points / justification / leader).
+     * Prefer {@link TabCollection.addTab} for DocIO-aligned naming.
+     */
+    add(position: number, justification?: TabJustification, leader?: TabLeader): ParagraphTabStop;
+    /**
+     * DocIO-aligned add. Zero-arg adds a default left stop at position `0`.
+     *
+     * @example
+     * ```ts
+     * pf.tabs.addTab();
+     * pf.tabs.addTab(36);
+     * pf.tabs.addTab(72, TabJustification.Right, TabLeader.Dot);
+     * ```
+     */
+    addTab(position?: number, justification?: TabJustification, leader?: TabLeader): ParagraphTabStop;
+    /**
+     * Remove the tab stop at `index` (`0…count-1`).
+     * @throws RangeError when the index is out of range.
+     */
+    removeAt(index: number): void;
+    /**
+     * Remove the first tab stop whose position equals `position` (points).
+     * No-op when no matching stop exists.
+     */
+    removeByPosition(position: number): void;
+    /** Remove all tab stops. */
+    clear(): void;
+}
+/**
+ * Live single paragraph border edge (`w:pBdr` child).
+ *
+ * @public
+ */
+export declare class ParagraphBorderFace {
+    private readonly owner;
+    private readonly edge;
+    /** @private */
+    constructor(owner: ParagraphFormat, edge: keyof ParagraphBorders);
+    private read;
+    private write;
+    /** Line style. */
+    borderType: BorderStyle;
+    /** Hex RGB or `'auto'`. Setter also accepts a {@link Color} enum value. */
+    color: string | Color;
+    /** Thickness in points (public); stored as eighths of a point. */
+    lineWidth: number;
+    /** Space from text in points. */
+    space: number;
+}
+/**
+ * Live paragraph borders with per-edge access. Whole-bag assign/clear via
+ * {@link ParagraphFormat.setBorders}.
+ *
+ * @public
+ */
+export declare class ParagraphBordersFace {
+    private readonly owner;
+    private topFace;
+    private leftFace;
+    private bottomFace;
+    private rightFace;
+    private betweenFace;
+    private barFace;
+    /** @private */
+    constructor(owner: ParagraphFormat);
+    readonly top: ParagraphBorderFace;
+    readonly left: ParagraphBorderFace;
+    readonly bottom: ParagraphBorderFace;
+    readonly right: ParagraphBorderFace;
+    readonly between: ParagraphBorderFace;
+    readonly bar: ParagraphBorderFace;
+    /** Stamp line style onto all outer edges. */
+    borderType: BorderStyle;
+    /** Stamp color onto all outer edges (hex/`'auto'` or {@link Color}). */
+    color: string | Color;
+    /** Stamp line width (points) onto all outer edges. */
+    lineWidth: number;
+    /** Stamp space from text (points) onto all outer edges. */
+    space: number;
+}
+/**
+ * Paragraph border line style (`ST_Border` subset on `CT_Border/@w:val`).
+ *
+ * Authoring accepts string literals such as `'single'`; invalid tokens such as
+ * `'abc'` fail at compile time. Wire tokens match the page-setup `BorderStyle`
+ * enum; runtime known-set is derived from that enum (see `BORDER_STYLES`).
+ *
+ * @public
+ */
+export declare type BorderStyle = 'nil' | 'none' | 'single' | 'thick' | 'double' | 'dotted' | 'dashed' | 'dotDash' | 'dotDotDash' | 'triple' | 'thinThickSmallGap' | 'thickThinSmallGap' | 'thinThickThinSmallGap' | 'thinThickMediumGap' | 'thickThinMediumGap' | 'thinThickThinMediumGap' | 'thinThickLargeGap' | 'thickThinLargeGap' | 'thinThickThinLargeGap' | 'wave' | 'doubleWave' | 'dashSmallGap' | 'dashDotStroked' | 'threeDEmboss' | 'threeDEngrave' | 'outset' | 'inset';
+/**
+ * A single paragraph border edge (`CT_Border`). §17.3.4
+ * @public
+ */
+export interface ParagraphBorder {
+    /** `@w:val` — border style (`ST_Border`). */
+    readonly style: BorderStyle;
+    /** `@w:color` — hex color or `'auto'`. */
+    readonly color?: string;
+    /** `@w:sz` — border width in eighths-of-a-point. */
+    readonly size?: number;
+    /** `@w:space` — space from text in points. */
+    readonly space?: number;
+}
+/**
+ * Paragraph borders (`w:pBdr`). §17.3.1.24
+ * @public
+ */
+export interface ParagraphBorders {
+    readonly top?: ParagraphBorder;
+    readonly left?: ParagraphBorder;
+    readonly bottom?: ParagraphBorder;
+    readonly right?: ParagraphBorder;
+    readonly between?: ParagraphBorder;
+    readonly bar?: ParagraphBorder;
+}
+/**
+ * Shading pattern (`ST_Shd` subset). §17.18.78
+ * @public
+ */
+export declare type ShadingPattern = 'clear' | 'solid' | 'horzStripe' | 'vertStripe' | 'reverseDiagStripe' | 'diagStripe' | 'horzCross' | 'diagCross' | 'thinHorzStripe' | 'thinVertStripe' | 'thinReverseDiagStripe' | 'thinDiagStripe' | 'thinHorzCross' | 'thinDiagCross' | 'pct5' | 'pct10' | 'pct12' | 'pct15' | 'pct20' | 'pct25' | 'pct30' | 'pct35' | 'pct37' | 'pct40' | 'pct45' | 'pct50' | 'pct55' | 'pct60' | 'pct62' | 'pct65' | 'pct70' | 'pct75' | 'pct80' | 'pct85' | 'pct87' | 'pct90' | 'pct95';
+/**
+ * Paragraph text direction (`ST_TextDirection`). §17.18.93 / wml.xsd 798–813.
+ * Twelve schema tokens; unknown loaded values round-trip via the format raw slot.
+ * @public
+ */
+export declare type ParagraphTextDirection = 'lr' | 'rl' | 'tb' | 'tbV' | 'rlV' | 'lrV' | 'btLr' | 'lrTb' | 'lrTbV' | 'tbLrV' | 'tbRl' | 'tbRlV';
+/**
+ * Paragraph indentation bag (`w:ind`). §17.3.1.12
+ * Used by styles modeled payload codecs — not a `Paragraph` property surface.
+ * Body authoring uses flat {@link ParagraphFormat} indent properties.
+ * `left` may be negative (e.g. outdented list text).
+ * @public
+ */
+export interface ParagraphIndentation {
+    /** `@w:left` in points (twips on the wire); may be negative. */
+    readonly left?: number;
+    /** `@w:right` in points (twips on the wire). */
+    readonly right?: number;
+    /** `@w:firstLine` in points (twips on the wire). Mutually exclusive with `hanging`. */
+    readonly firstLine?: number;
+    /** `@w:hanging` in points (twips on the wire). Mutually exclusive with `firstLine`. */
+    readonly hanging?: number;
+}
+/**
+ * Paragraph spacing bag (`w:spacing`). §17.3.1.33
+ * Used by styles modeled payload codecs — not a `Paragraph` property surface.
+ * Body authoring uses flat {@link ParagraphFormat} spacing properties.
+ * @public
+ */
+export interface ParagraphSpacing {
+    /** `@w:before` — space before paragraph, in points (twips on the wire). */
+    readonly before?: number;
+    /** `@w:after` — space after paragraph, in points (twips on the wire). */
+    readonly after?: number;
+    /**
+     * `@w:line` — line spacing in points (`w:lineRule` determines interpretation;
+     * twips on the wire). Prefer {@link ParagraphSpacing.lineSpacing} in styles authoring.
+     */
+    readonly line?: number;
+    /**
+     * `@w:line` — line spacing in points (twips on the wire). Alias of
+     * {@link ParagraphSpacing.line} used by the styles feature codec and builtin catalog.
+     */
+    readonly lineSpacing?: number;
+    /** `@w:lineRule` — how `line` / `lineSpacing` is interpreted. */
+    readonly lineRule?: LineSpacingRule;
+    /** `@w:beforeAutospacing` — ignore `before` and use automatic spacing. */
+    readonly beforeAutospacing?: boolean;
+    /** `@w:afterAutospacing` — ignore `after` and use automatic spacing. */
+    readonly afterAutospacing?: boolean;
+}
+/**
+ * Paragraph shading bag (`w:shd`). §17.3.1.31
+ * Used where a value-bag is required — not a `Paragraph` property surface.
+ * Body authoring uses flat {@link ParagraphFormat} `backColor` / `foreColor` /
+ * `shadingPattern`.
+ * @public
+ */
+export interface ParagraphShading {
+    /** `@w:fill` — background fill color (hex or `'auto'`). */
+    readonly fill?: string;
+    /** `@w:color` — pattern foreground color (hex or `'auto'`). */
+    readonly color?: string;
+    /** `@w:val` — shading pattern. */
+    readonly pattern?: ShadingPattern;
+}
+/**
+ * Baseline alignment for the paragraph's lines (`ST_TextAlignment`,
+ * `w:textAlignment`). §17.3.1.39.
+ * @public
+ */
+export declare type BaselineAlignment = 'auto' | 'top' | 'center' | 'baseline' | 'bottom';
+/**
+ * Host that owns a {@link ParagraphFormat} and receives mutation
+ * notifications. Implemented by {@link Paragraph} — the host performs the
+ * owner (detachment) check and invalidation.
+ * @private
+ */
+export interface ParagraphFormatHost {
+    notifyParagraphFormatMutation(): void;
+    /**
+     * Optional effective resolver (Paragraph host). Style-hosted PF must omit this
+     * so public getters stay direct/authored-only for style-chain walks.
+     * @private
+     */
+    resolveEffectiveParagraphValue?(key: string): unknown;
+}
+/**
+ * @private
+ * Internal indents record (`w:ind`) — round-trip slots for spellings not
+ * surfaced on the public flat properties. Authored values live in the flat
+ * `*Indent` properties; `start`/`end`/`*Chars` twins are preserved verbatim
+ * here when loaded and re-emitted on no-op saves.
+ */
+export interface ParagraphIndentsRecord {
+    left?: number;
+    right?: number;
+    firstLine?: number;
+    hanging?: number;
+    start?: number;
+    end?: number;
+    leftChars?: number;
+    rightChars?: number;
+    firstLineChars?: number;
+    hangingChars?: number;
+}
+/**
+ * @private
+ * Internal spacing record (`w:spacing`) — authored values in the flat
+ * properties plus `@w:beforeLines`/`@w:afterLines` round-trip slots.
+ */
+export interface ParagraphSpacingRecord {
+    before?: number;
+    after?: number;
+    line?: number;
+    lineRule?: LineSpacingRule;
+    beforeAutospacing?: boolean;
+    afterAutospacing?: boolean;
+    beforeLines?: number;
+    afterLines?: number;
+}
+/**
+ * @private
+ * Formatting snapshot for hydrate/serialize (ParagraphFormat module).
+ * Wire-unit storage (twips numbers) for exact round-trips; the public
+ * accessors convert to points.
+ */
+export interface ParagraphFormatSnapshot {
+    pPrExtra: OpenXmlElement[];
+    /** Raw `w:jc/@w:val` (unknown values preserved verbatim). */
+    jcRaw: string | undefined;
+    keepNextValue: boolean | undefined;
+    keepLinesValue: boolean | undefined;
+    pageBreakBeforeValue: boolean | undefined;
+    /** API-only (no ECMA `w:pPr` child); store/hydrate/snapshot only. */
+    pageBreakAfterValue: boolean | undefined;
+    widowControlValue: boolean | undefined;
+    bidiValue: boolean | undefined;
+    outlineLevelValue: number | undefined;
+    indentsValue: ParagraphIndentsRecord | undefined;
+    spacingValue: ParagraphSpacingRecord | undefined;
+    tabStopsValue: TabStop[] | undefined;
+    bordersValue: ParagraphBorders | undefined;
+    shadingValue: ParagraphShading | undefined;
+    suppressAutoHyphensValue: boolean | undefined;
+    suppressLineNumbersValue: boolean | undefined;
+    contextualSpacingValue: boolean | undefined;
+    mirrorIndentsValue: boolean | undefined;
+    adjustRightIndentValue: boolean | undefined;
+    textDirectionValue: ParagraphTextDirection | undefined;
+    /** Raw `w:textDirection/@w:val` for out-of-union tokens (round-trip only). */
+    textDirectionRaw: string | undefined;
+    baselineAlignmentValue: BaselineAlignment | undefined;
+    /** Raw `w:textAlignment/@w:val` for out-of-union tokens. */
+    baselineAlignmentRaw: string | undefined;
+    snapToGridValue: boolean | undefined;
+    wordWrapValue: boolean | undefined;
+    overflowPunctuationValue: boolean | undefined;
+    autoSpaceDEValue: boolean | undefined;
+    autoSpaceDNValue: boolean | undefined;
+    /** @private Round-trip only — `w:kinsoku`. */
+    kinsokuValue: boolean | undefined;
+    /** @private Round-trip only — `w:topLinePunct`. */
+    topLinePunctuationValue: boolean | undefined;
+}
+/**
+ * Batch-assign delta for {@link ParagraphFormat.assign}. One optional key
+ * per public property (points / booleans / string unions — no `Length`
+ * brand, ADR D1).
+ *
+ * @public
+ */
+export interface ParagraphFormatDelta {
+    horizontalAlignment?: ParagraphAlignment;
+    keepFollow?: boolean;
+    keepLines?: boolean;
+    pageBreakBefore?: boolean;
+    /** API-only; not serialized to OOXML. */
+    pageBreakAfter?: boolean;
+    widowControl?: boolean;
+    bidi?: boolean;
+    outlineLevel?: number;
+    leftIndent?: number;
+    rightIndent?: number;
+    firstLineIndent?: number;
+    beforeSpacing?: number;
+    afterSpacing?: number;
+    beforeAutospacing?: boolean;
+    afterAutospacing?: boolean;
+    beforeLines?: number;
+    afterLines?: number;
+    lineSpacing?: number;
+    lineSpacingRule?: LineSpacingRule;
+    lineSpacingCount?: number;
+    tabStops?: TabStop[];
+    borders?: ParagraphBorders;
+    /** Hex `RRGGBB` / `'auto'`, or a {@link Color} enum value. */
+    backColor?: string | Color;
+    /** Hex `RRGGBB` / `'auto'`, or a {@link Color} enum value. */
+    foreColor?: string | Color;
+    shadingPattern?: ShadingPattern;
+    suppressAutoHyphens?: boolean;
+    suppressLineNumbers?: boolean;
+    contextualSpacing?: boolean;
+    mirrorIndents?: boolean;
+    adjustRightIndent?: boolean;
+    textDirection?: ParagraphTextDirection;
+    baselineAlignment?: BaselineAlignment;
+    snapToGrid?: boolean;
+    wordWrap?: boolean;
+    overflowPunctuation?: boolean;
+    autoSpaceDE?: boolean;
+    autoSpaceDN?: boolean;
+}
+/**
+ * @private
+ * Empty snapshot factory.
+ */
+export declare function emptyParagraphFormatSnapshot(): ParagraphFormatSnapshot;
+/**
+ * Direct paragraph formatting (`w:p/w:pPr`) — the only public
+ * paragraph-formatting surface. One live instance per
+ * {@link Paragraph}, lazily created via `paragraph.paragraphFormat`,
+ * never null. Mirrors the .NET DocIO `WParagraphFormat` flat property
+ * surface (ADR `docs/adr/2026-09-24-paragraph-format-facade.md`).
+ *
+ * @example
+ * ```ts
+ * paragraph.paragraphFormat.beforeSpacing = 18;
+ * paragraph.paragraphFormat.lineSpacing = 10;
+ * paragraph.paragraphFormat.firstLineIndent = 10;   // negative = hanging
+ * paragraph.paragraphFormat.backColor = 'D3D3D3';
+ * paragraph.paragraphFormat.horizontalAlignment = 'end';
+ * ```
+ *
+ * @public
+ */
+export declare class ParagraphFormat {
+    private readonly host;
+    private pPrExtra;
+    private jcRaw;
+    private keepNextValue;
+    private keepLinesValue;
+    private pageBreakBeforeValue;
+    private pageBreakAfterValue;
+    private widowControlValue;
+    private tabsCollection;
+    private bordersFace;
+    private bidiValue;
+    private outlineLevelValue;
+    private indentsValue;
+    private spacingValue;
+    private tabStopsValue;
+    private bordersValue;
+    private shadingValue;
+    private suppressAutoHyphensValue;
+    private suppressLineNumbersValue;
+    private contextualSpacingValue;
+    private mirrorIndentsValue;
+    private adjustRightIndentValue;
+    private textDirectionValue;
+    private textDirectionRaw;
+    private baselineAlignmentValue;
+    private baselineAlignmentRaw;
+    private snapToGridValue;
+    private wordWrapValue;
+    private overflowPunctuationValue;
+    private autoSpaceDEValue;
+    private autoSpaceDNValue;
+    private kinsokuValue;
+    private topLinePunctuationValue;
+    /**
+     * @private
+     */
+    constructor(host: ParagraphFormatHost);
+    private mutate;
+    private effective;
+    private effectiveOrDefault;
+    /**
+     * Horizontal alignment of the paragraph (`w:jc`). `undefined` = inherit.
+     *
+     * Loaded directional `left`/`right` wording is surfaced as the neutral
+     * `start`/`end` without rewriting the stored value on a no-op save;
+     * unknown `w:jc` values (distribute-family) round-trip verbatim and this
+     * getter returns `undefined` for them.
+     *
+     * @public
+     */
+    horizontalAlignment: ParagraphAlignment | undefined;
+    /** Keep paragraph with the next (`w:keepNext`). `undefined` = inherit. */
+    keepFollow: boolean | undefined;
+    /** Keep all lines of the paragraph on one page (`w:keepLines`). */
+    keepLines: boolean | undefined;
+    /** Force this paragraph onto a new page (`w:pageBreakBefore`). */
+    pageBreakBefore: boolean | undefined;
+    /**
+     * DocIO-aligned page-break-after flag.
+     *
+     * There is no ECMA-376 `w:pageBreakAfter` on `w:pPr` (see
+     * `docs/specs/paragraph-formatting.md` § deliberate omissions). The typed flag
+     * is still stored for assign / clear / style resolve. On serialize, when the
+     * direct value is `true`, body writers emit a **following** paragraph whose
+     * only content is `w:r/w:br/@w:type="page"` after the content `w:p` — without
+     * inventing a non-schema pPr child and without placing the break run inside
+     * the content paragraph.
+     */
+    pageBreakAfter: boolean | undefined;
+    /** Widow/orphan line control (`w:widowControl`). */
+    widowControl: boolean | undefined;
+    /** Right-to-left base flow (`w:bidi`). */
+    bidi: boolean | undefined;
+    /**
+     * Outline/navigation level (`w:outlineLvl`): 0–8 = Heading 1–9,
+     * 9 = body text. `undefined` = inherit. Authoring an integer outside
+     * 0–9 throws `RangeError` (no silent clamp).
+     */
+    outlineLevel: number | undefined;
+    /**
+     * Left-of-flow indent in points (`w:ind/@w:left` authored; loaded
+     * `@w:start` preserved). Signed: negative values are legal outdents.
+     * Range ±1584 points; out-of-range throws `RangeError`.
+     * Setting a value drops a loaded `start`/`leftChars` twin (ADR D11).
+     */
+    leftIndent: number | undefined;
+    /**
+     * Right-of-flow indent in points (`@w:right` authored; loaded `@w:end`
+     * preserved). Signed; range ±1584 points. Setting a value drops a loaded
+     * `end`/`rightChars` twin.
+     */
+    rightIndent: number | undefined;
+    /**
+     * First-line indent in points, **signed** (ADR D3): positive = first-line
+     * indent (`@w:firstLine`); negative = hanging indent (`@w:hanging`,
+     * emitted as the absolute twips). Range ±1584 points. Setting a value
+     * drops a loaded `firstLineChars` twin. Loading a legacy `w:ind` that
+     * carries both `@w:firstLine` and `@w:hanging` is deterministic
+     * (firstLine wins) — the pair cannot be co-authored through this API.
+     */
+    firstLineIndent: number | undefined;
+    /**
+     * Space above the paragraph in points (`@w:before`). Range 0–1584.
+     * User-set clears an explicit `beforeAutospacing` (set-path only, never
+     * on load). Setting a value drops a loaded `@w:beforeLines` twin.
+     */
+    beforeSpacing: number | undefined;
+    /**
+     * Space below the paragraph in points (`@w:after`). Range 0–1584.
+     * User-set clears an explicit `afterAutospacing` and drops a loaded
+     * `@w:afterLines` twin.
+     */
+    afterSpacing: number | undefined;
+    /** Automatic spacing above (`@w:beforeAutospacing`). */
+    beforeAutospacing: boolean | undefined;
+    /** Automatic spacing below (`@w:afterAutospacing`). */
+    afterAutospacing: boolean | undefined;
+    /**
+     * Line-grid spacing above in hundredths of a line (`@w:beforeLines`),
+     * round-trip slot for the East-Asian line-grid authoring style. Authored
+     * `beforeSpacing` drops a loaded twin.
+     */
+    beforeLines: number | undefined;
+    /** Line-grid spacing below in hundredths of a line (`@w:afterLines`). */
+    afterLines: number | undefined;
+    /**
+     * Fixed/minimum line spacing in points (`@w:line` with
+     * `lineSpacingRule` `'atLeast'` or `'exact'`). Range 0.7–1584 points.
+     * Setting it clears {@link lineSpacingCount} — both are views of one
+     * `@line` slot (ADR D4).
+     */
+    lineSpacing: number | undefined;
+    /**
+     * Interpretation rule for `@w:line`: `'auto'` (multiple of single
+     * spacing — use {@link lineSpacingCount}), `'exact'` (exactly the given
+     * height), `'atLeast'` (at least the given height). Default when
+     * `lineSpacing` is authored without a rule: `'exact'`.
+     */
+    lineSpacingRule: LineSpacingRule | undefined;
+    /**
+     * Multiple-of-single line spacing (authoring view over
+     * `@line = round(n × 240)` + `@lineRule="auto"`), e.g. `1.5` or `2`.
+     * Range 0–100; mutually clears with {@link lineSpacing} (ADR D4).
+     * Getter returns `n` only when the stored rule is `'auto'` and `@line`
+     * is set; otherwise `undefined` (effective style may still resolve).
+     */
+    lineSpacingCount: number | undefined;
+    /**
+     * Custom tab stops (`w:tabs`), assigned whole as an array. `undefined`
+     * clears explicit stops (style/default resolution may still supply some).
+     */
+    tabStops: TabStop[] | undefined;
+    /**
+     * Live DocIO-style tab-stop collection. Mutates the same storage as
+     * {@link ParagraphFormat.tabStops}.
+     */
+    readonly tabs: TabCollection;
+    /**
+     * Live paragraph borders (`w:pBdr`) facade — always a
+     * {@link ParagraphBordersFace} (aggregate `borderType` / `color` /
+     * `lineWidth` / `space`, plus `top` / `left` / `bottom` / `right` /
+     * `horizontal` / `vertical`). Never `undefined` and never a plain bag.
+     *
+     * Whole-bag replace or clear: {@link ParagraphFormat.setBorders}.
+     */
+    readonly borders: ParagraphBordersFace;
+    /**
+     * Replace or clear the whole paragraph-borders bag (`w:pBdr`).
+     * Pass `undefined` to clear authored borders. Per-edge edits use
+     * {@link ParagraphFormat.borders}.
+     */
+    setBorders(value: ParagraphBorders | undefined): void;
+    /**
+     * @private
+     * Direct bag read for facades / serializers (avoids face getter recursion).
+     */
+    readBordersBag(): ParagraphBorders | undefined;
+    /**
+     * @private
+     */
+    writeBordersBag(value: ParagraphBorders | undefined): void;
+    /**
+     * Background fill color (`w:shd/@w:fill`).
+     *
+     * - **Get (runtime)**: OOXML wire string — hex `RRGGBB`, `'auto'`, or the
+     *   default `''` when unset. Loaded wire values are preserved (never a
+     *   {@link Color} enum).
+     * - **Set**: hex string / `'auto'`, a {@link Color} enum value (converted to
+     *   hex immediately), or `undefined` to clear the authored fill.
+     *
+     * TypeScript 3.3 requires identical get/set types, so the declared type is
+     * `string | Color | undefined`; the getter always returns a string.
+     */
+    backColor: string | Color | undefined;
+    /**
+     * Pattern foreground color (`w:shd/@w:color`).
+     *
+     * - **Get (runtime)**: OOXML wire string — hex `RRGGBB`, `'auto'`, or the
+     *   default `''` when unset. Loaded wire values are preserved (never a
+     *   {@link Color} enum).
+     * - **Set**: hex string / `'auto'`, a {@link Color} enum value (converted to
+     *   hex immediately), or `undefined` to clear.
+     *
+     * TypeScript 3.3 requires identical get/set types, so the declared type is
+     * `string | Color | undefined`; the getter always returns a string.
+     */
+    foreColor: string | Color | undefined;
+    /**
+     * Shading pattern (`w:shd/@w:val`). Authoring an out-of-subset token
+     * throws `DocxError('content/invalid-shading-pattern', …)`; unknown
+     * loaded tokens round-trip via the parked-element path (never throw).
+     */
+    shadingPattern: ShadingPattern | undefined;
+    /**
+     * Suppress automatic hyphenation for this paragraph
+     * (`w:suppressAutoHyphens`, ECMA-376-1 §17.3.1.34 — the only
+     * hyphenation element; ADR D5). Foreign `w:suppressHyphenation` markup
+     * (not an ECMA-376 element) parks verbatim in `pPrExtra`.
+     */
+    suppressAutoHyphens: boolean;
+    /** Exclude this paragraph from line numbering (`w:suppressLineNumbers`). */
+    suppressLineNumbers: boolean;
+    /** Ignore before/after spacing between same-style paragraphs (`w:contextualSpacing`). */
+    contextualSpacing: boolean;
+    /** Treat left/right indents as inside/outside for mirrored margins (`w:mirrorIndents`). */
+    mirrorIndents: boolean;
+    /** Auto-adjust right indent against the document grid (`w:adjustRightInd`). */
+    adjustRightIndent: boolean;
+    /**
+     * Physical text flow direction (`w:textDirection`,
+     * `ST_TextDirection` — all 12 tokens). Unknown loaded tokens round-trip
+     * verbatim (raw slot) and the getter returns `undefined` for them;
+     * authoring an invalid token throws
+     * `DocxError('content/invalid-text-direction', …)`.
+     */
+    textDirection: ParagraphTextDirection | undefined;
+    /**
+     * How characters of different sizes align vertically on a line
+     * (`w:textAlignment`, `ST_TextAlignment`). Unknown loaded tokens
+     * round-trip verbatim and the getter returns `undefined` for them;
+     * authoring an invalid token throws
+     * `DocxError('content/invalid-baseline-alignment', …)`.
+     */
+    baselineAlignment: BaselineAlignment | undefined;
+    /** Use document grid line pitch (`w:snapToGrid`). */
+    snapToGrid: boolean;
+    /** Break lines on word level (`w:wordWrap`). */
+    wordWrap: boolean;
+    /** Allow trailing punctuation to extend beyond the line (`w:overflowPunct`). */
+    overflowPunctuation: boolean;
+    /** Auto space between East-Asian and Latin text (`w:autoSpaceDE`). */
+    autoSpaceDE: boolean;
+    /** Auto space between East-Asian text and numbers (`w:autoSpaceDN`). */
+    autoSpaceDN: boolean;
+    /**
+     * @private
+     * `w:kinsoku` — East-Asian line-breaking rules (round-trip only).
+     */
+    /** @private */
+    kinsoku: boolean | undefined;
+    /**
+     * @private
+     * `w:topLinePunct` — punctuation at line start preference (round-trip only).
+     */
+    /** @private */
+    topLinePunctuation: boolean | undefined;
+    /**
+     * @private
+     * Raw loaded `w:textDirection/@w:val` for tokens outside the public union.
+     */
+    textDirectionRawValue(): string | undefined;
+    /**
+     * @private
+     * Raw loaded `w:textAlignment/@w:val` for tokens outside the public union.
+     */
+    baselineAlignmentRawValue(): string | undefined;
+    /**
+     * Apply a partial delta. Uses setters — cross-property effects
+     * (autospacing clearing, mutual line-slot clearing) apply.
+     * @public
+     */
+    assign(delta: ParagraphFormatDelta): void;
+    /**
+     * Clear all typed formatting. Does not clear `pPrExtra`.
+     * @public
+     */
+    clear(): void;
+    /**
+     * @private
+     * Load a snapshot without set-path cross-property effects.
+     */
+    hydrate(data: ParagraphFormatSnapshot): void;
+    /**
+     * @private
+     */
+    snapshot(): ParagraphFormatSnapshot;
+    /**
+     * @private
+     * Parked children (`framePr`, `pPrChange`, unknowns, foreign invalid markup).
+     * Mark `w:rPr` is owned by {@link Paragraph.breakCharacterFormat}, not parked here.
+     * Read/write for the paragraph-owned serializer.
+     */
+    extraChildren(): OpenXmlElement[];
+    /**
+     * @private
+     * Paragraph conditional formatting membership (`w:pPr/w:cnfStyle`).
+     */
+    readCnfStyle(): CnfStyle | undefined;
+    /**
+     * @private
+     * Write or clear paragraph `w:cnfStyle` in parked extra children.
+     * `undefined` removes the element; a supplied state always writes
+     * (including all-false normalized form).
+     */
+    writeCnfStyle(state: NormalizedCnfStyle | CnfStyle | undefined): void;
+    /**
+     * @private
+     * Materialize `w:pPr` children owned by this format (CT_PPrBase order).
+     * Does not emit `pStyle` / `numPr` / `rPr` / `sectPr` — those stay on {@link Paragraph}.
+     */
+    buildPPrChildren(inject?: ParagraphPPrInject): OpenXmlElement[];
+}
+/**
+ * Optional inject hooks for paragraph-owned children that must sit at fixed
+ * CT_PPrBase / CT_PPr positions inside the materialised `w:pPr` list.
+ * @private
+ */
+export interface ParagraphPPrInject {
+    /** Pre-built `w:numPr` element, emitted after `widowControl`. */
+    numPr?: OpenXmlElement;
+    /**
+     * Pre-built mark `w:rPr` from {@link Paragraph.breakCharacterFormat},
+     * emitted after `outlineLvl` and before `sectPr` (CT_PPr order).
+     */
+    rPr?: OpenXmlElement;
+    /** Pre-built `w:sectPr` element, emitted after mark `rPr` and before `pPrChange`. */
+    sectPr?: OpenXmlElement;
+}
+/**
+ * Parse `w:ind` into a wire-twips {@link ParagraphIndentsRecord}.
+ * Preserves `@start`/`@end`/`*Chars` for D2 round-trip.
+ * @private
+ */
+export declare function parseIndentsRecord(el: OpenXmlElement): ParagraphIndentsRecord | undefined;
+/**
+ * Parse `w:spacing` into a wire-unit {@link ParagraphSpacingRecord}.
+ * Preserves `@beforeLines`/`@afterLines` for round-trip.
+ * @private
+ */
+export declare function parseSpacingRecord(el: OpenXmlElement): ParagraphSpacingRecord | undefined;
+/**
+ * Parse `w:pPr` children into a {@link ParagraphFormatSnapshot}.
+ * Invalid / unmodeled markup is parked in `pPrExtra` (never throws on load).
+ * Does not consume `pStyle` / `numPr` / `rPr` / `sectPr` — callers handle those.
+ *
+ * @private
+ */
+export declare function parseParagraphFormat(pPrElement: OpenXmlElement): ParagraphFormatSnapshot;
+/**
+ * Serialize wire-twips indents record → `w:ind`.
+ * D2: authored `left`/`right` plus any RT `start`/`end`/`*Chars` slots.
+ * @private
+ */
+export declare function serializeIndentsRecord(ind: ParagraphIndentsRecord): OpenXmlElement;
+/**
+ * Serialize wire-unit spacing record → `w:spacing`.
+ * @private
+ */
+export declare function serializeSpacingRecord(sp: ParagraphSpacingRecord): OpenXmlElement;
+/**
+ * Materialize format-owned `w:pPr` children in CT_PPrBase / CT_PPr order.
+ * Inject optional paragraph-owned `numPr` / `sectPr` at schema positions.
+ * D5: never emits `w:suppressHyphenation` from typed state.
+ *
+ * @private
+ */
+export declare function buildPPrChildrenFromSnapshot(snap: ParagraphFormatSnapshot, inject?: ParagraphPPrInject): OpenXmlElement[];
+/**
+ * Wire `w:spacing` → public points {@link ParagraphSpacing} with `lineSpacing` key.
+ * Used by the styles feature; preserves prior payload shape.
+ * @private
+ */
+export declare function parseParagraphSpacingPoints(el: OpenXmlElement): ParagraphSpacing | undefined;
+/**
+ * Wire `w:ind` → public points {@link ParagraphIndentation}.
+ * @private
+ */
+export declare function parseParagraphIndentationPoints(el: OpenXmlElement): ParagraphIndentation | undefined;
+/**
+ * Points {@link ParagraphSpacing} → `w:spacing` (styles `lineSpacing` key).
+ * @private
+ */
+export declare function serializeParagraphSpacingPoints(spacing: ParagraphSpacing): OpenXmlElement;
+/**
+ * Points {@link ParagraphIndentation} → `w:ind` (D2 left/right spellings).
+ * @private
+ */
+export declare function serializeParagraphIndentationPoints(indentation: ParagraphIndentation): OpenXmlElement;