@betteroffice/docx 0.0.1

package/dist/formatting-DoL7KBSL.d.mts

@@ -0,0 +1,823 @@
+/**
+ * Theme parsing — colors and fonts from a DrawingML theme part
+ * (e.g. word/theme/theme1.xml, ppt/theme/theme1.xml).
+ *
+ * Extracts color scheme (dk1, lt1, dk2, lt2, accent1-6, hlink, folHlink)
+ * and font scheme (majorFont, minorFont) from the theme.
+ *
+ * OOXML Reference:
+ * - Uses DrawingML namespace (a:)
+ * - Colors can be srgbClr, sysClr, or schemeClr
+ */
+
+/**
+ * Theme color scheme (a:clrScheme)
+ *
+ * @public
+ */
+interface ThemeColorScheme {
+    /** Dark 1 color (usually black) */
+    dk1?: string;
+    /** Light 1 color (usually white) */
+    lt1?: string;
+    /** Dark 2 color */
+    dk2?: string;
+    /** Light 2 color */
+    lt2?: string;
+    /** Accent colors 1-6 */
+    accent1?: string;
+    accent2?: string;
+    accent3?: string;
+    accent4?: string;
+    accent5?: string;
+    accent6?: string;
+    /** Hyperlink color */
+    hlink?: string;
+    /** Followed hyperlink color */
+    folHlink?: string;
+}
+/**
+ * Theme font (with script variants)
+ *
+ * @public
+ */
+interface ThemeFont {
+    /** Latin font */
+    latin?: string;
+    /** East Asian font */
+    ea?: string;
+    /** Complex script font */
+    cs?: string;
+    /** Script-specific fonts */
+    fonts?: Record<string, string>;
+}
+/**
+ * Theme font scheme (a:fontScheme)
+ *
+ * @public
+ */
+interface ThemeFontScheme {
+    /** Major font (headings) */
+    majorFont?: ThemeFont;
+    /** Minor font (body text) */
+    minorFont?: ThemeFont;
+}
+/**
+ * Theme (from a theme1.xml part)
+ *
+ * @public
+ */
+interface Theme {
+    /** Theme name */
+    name?: string;
+    /** Color scheme */
+    colorScheme?: ThemeColorScheme;
+    /** Font scheme */
+    fontScheme?: ThemeFontScheme;
+    /** Format scheme (fills, lines, effects) - simplified */
+    formatScheme?: {
+        name?: string;
+    };
+}
+
+/**
+ * Color primitives and math shared across OOXML formats.
+ *
+ * Handles theme color slot references (accent1, dk1, ...), RGB hex values,
+ * tint/shade modifiers, and the derived color helpers (lighten/darken/blend/
+ * contrast) built on top of them.
+ *
+ * Tint/Shade Calculations (ECMA-376 §17.3.2.41):
+ * - Tint makes a color lighter (per-channel interpolation toward white)
+ * - Shade makes a color darker (per-channel interpolation toward black)
+ * - The wire value is a hex byte (00-FF) meaning "how much color to keep"
+ */
+
+/**
+ * Theme color slots from a theme's clrScheme (plus the WordprocessingML
+ * alias slots background1/text1/background2/text2).
+ *
+ * @public
+ */
+type ThemeColorSlot = 'dk1' | 'lt1' | 'dk2' | 'lt2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink' | 'background1' | 'text1' | 'background2' | 'text2';
+/**
+ * ECMA-376 color reference — either a direct RGB hex, a theme slot
+ * reference (with optional tint/shade), or `auto` for context-dependent
+ * defaults (usually black for text on light backgrounds). When both
+ * `rgb` and `themeColor` are set, the theme wins on Word import and the
+ * `rgb` acts as a fallback for renderers without theme support.
+ *
+ * See ECMA-376 §17.18.39 (`ST_ThemeColor`).
+ *
+ * @public
+ */
+interface ColorValue {
+    /** RGB hex value without # (e.g., "FF0000") */
+    rgb?: string;
+    /** Theme color slot reference */
+    themeColor?: ThemeColorSlot;
+    /** Tint modifier (0-255 as hex string, e.g., "80") - makes color lighter */
+    themeTint?: string;
+    /** Shade modifier (0-255 as hex string) - makes color darker */
+    themeShade?: string;
+    /** Auto color - context-dependent (usually black for text) */
+    auto?: boolean;
+}
+/**
+ * Resolve a ColorValue to a CSS color string
+ *
+ * @param color - ColorValue object with rgb, themeColor, tint/shade, or auto
+ * @param theme - Theme for resolving theme colors
+ * @param defaultColor - Default color if auto or undefined (default: black)
+ * @returns CSS color string (e.g., "#FF0000" or "inherit")
+ *
+ * @public
+ */
+declare function resolveColor(color: ColorValue | undefined | null, theme: Theme | null | undefined, defaultColor?: string): string;
+/**
+ * Resolve any ColorValue (text, fill/shading, border, underline) to a 6-char
+ * uppercase hex string — or `undefined` if transparent/unset/unresolvable.
+ *
+ * Shared display-side resolver. Prefer this over reading `.rgb` directly so
+ * that `themeColor` + `themeTint`/`themeShade` are honored consistently across
+ * all render paths.
+ *
+ * When a themed color is present but `theme` is null/undefined, falls back to
+ * `color.rgb` if Word wrote one for compat; otherwise returns `undefined`.
+ *
+ * @returns 6-char uppercase hex without `#`, or `undefined`.
+ *
+ * @public
+ */
+declare function resolveColorToHex(color: ColorValue | undefined | null, theme: Theme | null | undefined): string | undefined;
+/**
+ * Get contrasting text color for a background
+ *
+ * @param backgroundColor - Background ColorValue
+ * @param theme - Theme for resolving theme colors
+ * @returns Black or white hex color for best contrast
+ *
+ * @public
+ */
+declare function getContrastingColor(backgroundColor: ColorValue | undefined | null, theme: Theme | null | undefined): string;
+/**
+ * Darken a color by a percentage
+ *
+ * @param color - ColorValue to darken
+ * @param theme - Theme for resolving
+ * @param percent - Percentage to darken (0-100)
+ * @returns CSS color string
+ *
+ * @public
+ */
+declare function darkenColor(color: ColorValue | undefined | null, theme: Theme | null | undefined, percent: number): string;
+/**
+ * Lighten a color by a percentage
+ *
+ * @param color - ColorValue to lighten
+ * @param theme - Theme for resolving
+ * @param percent - Percentage to lighten (0-100)
+ * @returns CSS color string
+ *
+ * @public
+ */
+declare function lightenColor(color: ColorValue | undefined | null, theme: Theme | null | undefined, percent: number): string;
+/**
+ * Blend two colors together
+ *
+ * @param color1 - First color
+ * @param color2 - Second color
+ * @param ratio - Blend ratio (0 = all color1, 1 = all color2)
+ * @param theme - Theme for resolving
+ * @returns CSS color string
+ *
+ * @public
+ */
+declare function blendColors(color1: ColorValue | undefined | null, color2: ColorValue | undefined | null, ratio: number, theme: Theme | null | undefined): string;
+/**
+ * Theme color matrix cell
+ *
+ * @public
+ */
+interface ThemeMatrixCell {
+    /** Resolved hex color (6 chars, no #) */
+    hex: string;
+    /** Theme color slot */
+    themeSlot: ThemeColorSlot;
+    /** Tint hex modifier if applicable (e.g., "CC") */
+    tint?: string;
+    /** Shade hex modifier if applicable (e.g., "BF") */
+    shade?: string;
+    /** Human-readable label (e.g., "Accent 1, Lighter 60%") */
+    label: string;
+}
+/**
+ * Compute a single tinted or shaded hex color from a base color.
+ *
+ * @param baseHex - 6-character hex color (no #)
+ * @param type - 'tint' to lighten, 'shade' to darken
+ * @param fraction - Amount (0-1). For tint: 0=no change, 1=white. For shade: 0=black, 1=no change.
+ * @returns 6-character hex color (no #)
+ *
+ * @public
+ */
+declare function getThemeTintShadeHex(baseHex: string, type: 'tint' | 'shade', fraction: number): string;
+/**
+ * Generate the 10×6 theme color matrix for an advanced color picker.
+ *
+ * Columns: lt1, dk1, lt2, dk2, accent1-6 (matches Word's order)
+ * Rows: base, 80% tint, 60% tint, 40% tint, 25% shade, 50% shade
+ *
+ * @param colorScheme - Theme color scheme (falls back to Office 2016 defaults)
+ * @returns 6 rows × 10 columns of ThemeMatrixCell
+ *
+ * @public
+ */
+declare function generateThemeTintShadeMatrix(colorScheme?: ThemeColorScheme | null): ThemeMatrixCell[][];
+
+/**
+ * Color & Styling Primitives
+ *
+ * Basic types used throughout OOXML for colors, borders, and shading.
+ * The color primitives (ColorValue, ThemeColorSlot) are shared across OOXML
+ * formats; the WordprocessingML border/shading types stay here.
+ */
+
+/**
+ * One side of a border — style, color, width, spacing. Used by paragraph
+ * borders, table borders (per-cell or whole-table), and page borders.
+ * `size` is in eighths of a point (Word's wire format); `space` is in
+ * points.
+ *
+ * See ECMA-376 §17.18.2 (`ST_Border`).
+ */
+interface BorderSpec {
+    /** Border style */
+    style: 'none' | 'single' | 'double' | 'dotted' | 'dashed' | 'thick' | 'triple' | 'thinThickSmallGap' | 'thickThinSmallGap' | 'thinThickMediumGap' | 'thickThinMediumGap' | 'thinThickLargeGap' | 'thickThinLargeGap' | 'wave' | 'doubleWave' | 'dashSmallGap' | 'dashDotStroked' | 'threeDEmboss' | 'threeDEngrave' | 'outset' | 'inset' | 'nil';
+    /** Color of the border */
+    color?: ColorValue;
+    /** Width in eighths of a point (1/8 pt) */
+    size?: number;
+    /** Spacing from text in points */
+    space?: number;
+    /** Shadow effect */
+    shadow?: boolean;
+    /** Frame effect */
+    frame?: boolean;
+    /**
+     * Relationship id for relationship-backed border art. Undefined means a
+     * normal line border; renderers must not fetch external relationships.
+     */
+    relationshipId?: string;
+    /** Optional authored art/corner token retained when `style` is approximated. */
+    artName?: string;
+}
+/**
+ * Cell/paragraph/run shading — Word's combined "fill + pattern overlay"
+ * model. `fill` is the solid background; `color` is the pattern overlay
+ * drawn on top; `pattern` selects the pattern type (defaults to
+ * `'clear'` = solid `fill`, no pattern).
+ *
+ * See ECMA-376 §17.4.32 (`CT_Shd`).
+ */
+interface ShadingProperties {
+    /** Pattern fill color */
+    color?: ColorValue;
+    /** Background fill color */
+    fill?: ColorValue;
+    /** Shading pattern type */
+    pattern?: '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' | 'nil';
+}
+
+/**
+ * Text, Paragraph, and Table Formatting Types
+ *
+ * Properties that control how text, paragraphs, and table structures
+ * are formatted in OOXML (w:rPr, w:pPr, w:tblPr, etc.).
+ */
+
+/**
+ * Underline style options
+ */
+type UnderlineStyle = 'none' | 'single' | 'words' | 'double' | 'thick' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashedHeavy' | 'dashLong' | 'dashLongHeavy' | 'dotDash' | 'dashDotHeavy' | 'dotDotDash' | 'dashDotDotHeavy' | 'wave' | 'wavyHeavy' | 'wavyDouble';
+/**
+ * Text effect animations
+ */
+type TextEffect = 'none' | 'blinkBackground' | 'lights' | 'antsBlack' | 'antsRed' | 'shimmer' | 'sparkle';
+/**
+ * Emphasis mark type
+ */
+type EmphasisMark = 'none' | 'dot' | 'comma' | 'circle' | 'underDot';
+/** Word font-binding hint from `w:rFonts/@w:hint`. Undefined means `default`. */
+type RunFontHint = 'default' | 'eastAsia' | 'cs';
+/**
+ * Modern (Office 2010+ `w14:*`) run text effects — glow, modern shadow,
+ * reflection, text fill, and compound text outline. Distances/radii are in
+ * CSS px (converted from EMU at parse); directions are degrees clockwise;
+ * opacities are 0..1 fractions; colors are resolved `#rrggbb` strings.
+ * All members optional and additive so documents without w14 effects
+ * round-trip byte-identically.
+ */
+interface TextModernEffects {
+    /** `w14:glow` — colored halo around the glyph outline. */
+    glow?: {
+        color?: string;
+        radius?: number;
+    };
+    /** `w14:shadow` — parameterized modern shadow. */
+    shadow?: {
+        color?: string;
+        blurRadius?: number;
+        distance?: number;
+        direction?: number;
+    };
+    /** `w14:reflection` — mirrored copy below the text. */
+    reflection?: {
+        blurRadius?: number;
+        startOpacity?: number;
+        endOpacity?: number;
+        distance?: number;
+        direction?: number;
+    };
+    /** `w14:textFill` — solid or gradient glyph fill replacing the run color. */
+    textFill?: {
+        kind?: 'none' | 'solid' | 'gradient';
+        color?: string;
+        angle?: number;
+        stops?: Array<{
+            position?: number;
+            color?: string;
+        }>;
+    };
+    /** `w14:textOutline` — stroked glyph outline. Width in px. */
+    textOutline?: {
+        color?: string;
+        width?: number;
+        dash?: string;
+        noFill?: boolean;
+    };
+}
+/**
+ * The three independent language slots in `w:lang`. Missing slots inherit
+ * through the style/default chain and therefore have no effect.
+ */
+interface RunLanguage {
+    /** Latin/default language (`w:lang/@w:val`). */
+    latin?: string;
+    /** East Asian language (`w:lang/@w:eastAsia`). */
+    eastAsia?: string;
+    /** Complex-script language (`w:lang/@w:bidi`). */
+    bidi?: string;
+}
+/**
+ * Character-level formatting (`w:rPr`) — the full set of run properties
+ * Word supports: weight, slant, font, size, color, highlight, underline,
+ * strikethrough, vertical position, language, complex-script variants,
+ * spacing/kerning, emphasis marks, and more.
+ *
+ * Most fields mirror their ECMA-376 element names (see §17.3.2). Missing
+ * keys inherit from the run's paragraph style → linked style → document
+ * defaults chain.
+ */
+interface TextFormatting {
+    /** Bold (w:b) */
+    bold?: boolean;
+    /** Bold complex script (w:bCs) */
+    boldCs?: boolean;
+    /** Italic (w:i) */
+    italic?: boolean;
+    /** Italic complex script (w:iCs) */
+    italicCs?: boolean;
+    /** Underline style and color (w:u) */
+    underline?: {
+        style: UnderlineStyle;
+        color?: ColorValue;
+    };
+    /** Strikethrough (w:strike) */
+    strike?: boolean;
+    /** Double strikethrough (w:dstrike) */
+    doubleStrike?: boolean;
+    /** Superscript/subscript (w:vertAlign) */
+    vertAlign?: 'baseline' | 'superscript' | 'subscript';
+    /** Small caps (w:smallCaps) */
+    smallCaps?: boolean;
+    /** All caps (w:caps) */
+    allCaps?: boolean;
+    /** Hidden text (w:vanish) */
+    hidden?: boolean;
+    /** Text color (w:color) */
+    color?: ColorValue;
+    /** Highlight/background color (w:highlight) */
+    highlight?: 'black' | 'blue' | 'cyan' | 'darkBlue' | 'darkCyan' | 'darkGray' | 'darkGreen' | 'darkMagenta' | 'darkRed' | 'darkYellow' | 'green' | 'lightGray' | 'magenta' | 'none' | 'red' | 'white' | 'yellow';
+    /** Character shading (w:shd) */
+    shading?: ShadingProperties;
+    /** Font size in half-points (w:sz) - e.g., 24 = 12pt */
+    fontSize?: number;
+    /** Font size complex script (w:szCs) */
+    fontSizeCs?: number;
+    /** Font family (w:rFonts) */
+    fontFamily?: {
+        ascii?: string;
+        hAnsi?: string;
+        eastAsia?: string;
+        cs?: string;
+        /** Theme font reference */
+        asciiTheme?: 'majorAscii' | 'majorHAnsi' | 'majorEastAsia' | 'majorBidi' | 'minorAscii' | 'minorHAnsi' | 'minorEastAsia' | 'minorBidi';
+        hAnsiTheme?: string;
+        eastAsiaTheme?: string;
+        csTheme?: string;
+        /** Script-binding hint (`w:rFonts/@w:hint`). Undefined = `default`. */
+        hint?: RunFontHint;
+    };
+    /** Three-slot run language (`w:lang`). Undefined = inherit/no override. */
+    language?: RunLanguage;
+    /** Character spacing in twips (w:spacing) */
+    spacing?: number;
+    /** Raised/lowered text position in half-points (w:position) */
+    position?: number;
+    /** Horizontal text scale percentage (w:w) */
+    scale?: number;
+    /** Kerning threshold in half-points (w:kern) */
+    kerning?: number;
+    /** Text effect animation (w:effect) */
+    effect?: TextEffect;
+    /** Emphasis mark (w:em) */
+    emphasisMark?: EmphasisMark;
+    /** Emboss effect (w:emboss) */
+    emboss?: boolean;
+    /** Imprint/engrave effect (w:imprint) */
+    imprint?: boolean;
+    /** Outline effect (w:outline) */
+    outline?: boolean;
+    /** Shadow effect (w:shadow) */
+    shadow?: boolean;
+    /** Modern w14 text effects (glow/shadow/reflection/textFill/textOutline). */
+    modernEffects?: TextModernEffects;
+    /** Right-to-left text (w:rtl) */
+    rtl?: boolean;
+    /** Complex script formatting (w:cs) */
+    cs?: boolean;
+    /** Character style ID (w:rStyle) */
+    styleId?: string;
+}
+/**
+ * Tab stop alignment
+ */
+type TabStopAlignment = 'left' | 'center' | 'right' | 'decimal' | 'bar' | 'clear' | 'num';
+/**
+ * Tab leader character
+ */
+type TabLeader = 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';
+/**
+ * Tab stop definition
+ */
+interface TabStop {
+    /** Position in twips from left margin */
+    position: number;
+    /** Alignment at tab stop */
+    alignment: TabStopAlignment;
+    /** Leader character */
+    leader?: TabLeader;
+}
+/**
+ * Line spacing rule
+ */
+type LineSpacingRule = 'auto' | 'exact' | 'atLeast';
+/**
+ * Paragraph alignment/justification
+ */
+type ParagraphAlignment = 'left' | 'center' | 'right' | 'both' | 'distribute' | 'mediumKashida' | 'highKashida' | 'lowKashida' | 'thaiDistribute';
+/**
+ * Per-side flags identifying which `<w:spacing>` attrs were inline (not
+ * inherited from a style chain). Used to suppress style-only spacing on
+ * empty paragraphs per Word's behavior.
+ */
+type SpacingExplicit = {
+    before?: boolean;
+    after?: boolean;
+};
+/**
+ * Paragraph-level formatting (`w:pPr`) — alignment, indentation, spacing
+ * (before/after, line height), pagination flags (keepNext, keepLines,
+ * pageBreakBefore, widowControl), tabs, borders, shading, numbering
+ * reference, style reference, and frame/anchored-text properties.
+ *
+ * Most fields mirror their ECMA-376 element names (see §17.3.1).
+ * Inheritance: direct formatting beats the linked style which beats
+ * document defaults.
+ */
+interface ParagraphFormatting {
+    /** Paragraph alignment (w:jc) */
+    alignment?: ParagraphAlignment;
+    /** Text direction (w:bidi) */
+    bidi?: boolean;
+    /** Spacing before in twips (w:spacing/@w:before) */
+    spaceBefore?: number;
+    /** Spacing after in twips (w:spacing/@w:after) */
+    spaceAfter?: number;
+    /** Line spacing value (w:spacing/@w:line) */
+    lineSpacing?: number;
+    /** Line spacing rule (w:spacing/@w:lineRule) */
+    lineSpacingRule?: LineSpacingRule;
+    /** Auto space before (w:spacing/@w:beforeAutospacing) */
+    beforeAutospacing?: boolean;
+    /** Auto space after (w:spacing/@w:afterAutospacing) */
+    afterAutospacing?: boolean;
+    /**
+     * Per-side flags marking which `<w:spacing>` attrs came from this
+     * paragraph's own pPr (vs inherited). Word collapses style-inherited
+     * spacing on empty paragraphs but honors the explicit values.
+     */
+    spacingExplicit?: SpacingExplicit;
+    /** Left indent in twips (w:ind/@w:left) */
+    indentLeft?: number;
+    /** Right indent in twips (w:ind/@w:right) */
+    indentRight?: number;
+    /** First line indent in twips - positive for indent, negative for hanging (w:ind/@w:firstLine or @w:hanging) */
+    indentFirstLine?: number;
+    /** Whether first line is hanging indent */
+    hangingIndent?: boolean;
+    /** Paragraph borders (w:pBdr) */
+    borders?: {
+        top?: BorderSpec;
+        bottom?: BorderSpec;
+        left?: BorderSpec;
+        right?: BorderSpec;
+        between?: BorderSpec;
+        bar?: BorderSpec;
+    };
+    /** Paragraph shading (w:shd) */
+    shading?: ShadingProperties;
+    /** Custom tab stops (w:tabs) */
+    tabs?: TabStop[];
+    /** Keep with next paragraph (w:keepNext) */
+    keepNext?: boolean;
+    /** Keep lines together (w:keepLines) */
+    keepLines?: boolean;
+    /** Widow/orphan control (w:widowControl) */
+    widowControl?: boolean;
+    /** Page break before (w:pageBreakBefore) */
+    pageBreakBefore?: boolean;
+    /** Contextual spacing — suppress space between paragraphs of the same style (w:contextualSpacing) */
+    contextualSpacing?: boolean;
+    /** Numbering properties (w:numPr) */
+    numPr?: {
+        /** Numbering definition ID (w:numId) */
+        numId?: number;
+        /** List level (0-8) (w:ilvl) */
+        ilvl?: number;
+    };
+    /**
+     * When `numPr` was resolved from the paragraph STYLE's pPr rather than the
+     * paragraph's own `<w:numPr>`, this records the style-sourced value. The
+     * serializer omits `numPr` while it still equals this value — writing it as
+     * direct formatting would flip Word's indent precedence (a directly
+     * referenced level's indents beat the style's; a style-referenced level's
+     * do not) and break the document on save/reload. Cleared the moment the
+     * user changes the numbering (values diverge).
+     */
+    numPrFromStyle?: {
+        numId?: number;
+        ilvl?: number;
+    };
+    /** Outline level 0-9 (w:outlineLvl) */
+    outlineLevel?: number;
+    /** Paragraph style ID (w:pStyle) */
+    styleId?: string;
+    /** Text frame properties (w:framePr) */
+    frame?: {
+        width?: number;
+        height?: number;
+        hAnchor?: 'text' | 'margin' | 'page';
+        vAnchor?: 'text' | 'margin' | 'page';
+        x?: number;
+        y?: number;
+        xAlign?: 'left' | 'center' | 'right' | 'inside' | 'outside';
+        yAlign?: 'top' | 'center' | 'bottom' | 'inside' | 'outside' | 'inline';
+        wrap?: 'around' | 'auto' | 'none' | 'notBeside' | 'through' | 'tight';
+    };
+    /** Suppress line numbers (w:suppressLineNumbers) */
+    suppressLineNumbers?: boolean;
+    /** Suppress auto hyphens (w:suppressAutoHyphens) */
+    suppressAutoHyphens?: boolean;
+    /** Run properties to apply to all runs (w:rPr) */
+    runProperties?: TextFormatting;
+}
+/**
+ * Table width type
+ */
+type TableWidthType = 'auto' | 'dxa' | 'nil' | 'pct';
+/**
+ * Table measurement (width or height)
+ */
+interface TableMeasurement {
+    /** Value in twips (for dxa) or fifths of a percent (for pct) */
+    value: number;
+    /** Measurement type */
+    type: TableWidthType;
+}
+/**
+ * Table borders
+ */
+interface TableBorders {
+    top?: BorderSpec;
+    bottom?: BorderSpec;
+    left?: BorderSpec;
+    right?: BorderSpec;
+    insideH?: BorderSpec;
+    insideV?: BorderSpec;
+    /** Logical leading edge (`w:start`); undefined = no authored edge. */
+    start?: BorderSpec;
+    /** Logical trailing edge (`w:end`); undefined = no authored edge. */
+    end?: BorderSpec;
+    /** Top-left to bottom-right diagonal (`w:tl2br`). */
+    tl2br?: BorderSpec;
+    /** Top-right to bottom-left diagonal (`w:tr2bl`). */
+    tr2bl?: BorderSpec;
+}
+/**
+ * Cell margins
+ */
+interface CellMargins {
+    top?: TableMeasurement;
+    bottom?: TableMeasurement;
+    left?: TableMeasurement;
+    right?: TableMeasurement;
+    /** Logical leading margin (`w:start`); undefined falls back to physical left/right. */
+    start?: TableMeasurement;
+    /** Logical trailing margin (`w:end`); undefined falls back to physical left/right. */
+    end?: TableMeasurement;
+}
+/**
+ * Table look flags (for table styles)
+ */
+interface TableLook {
+    firstColumn?: boolean;
+    firstRow?: boolean;
+    lastColumn?: boolean;
+    lastRow?: boolean;
+    noHBand?: boolean;
+    noVBand?: boolean;
+    /** Original hexadecimal `w:tblLook/@w:val`; undefined = derive from flags. */
+    value?: string;
+}
+/** One conditional region selected by `w:tblStylePr`/`w:cnfStyle`. */
+type TableStyleRegion = 'band1Horz' | 'band1Vert' | 'band2Horz' | 'band2Vert' | 'firstCol' | 'firstRow' | 'lastCol' | 'lastRow' | 'neCell' | 'nwCell' | 'seCell' | 'swCell';
+/**
+ * Lossless style-cascade provenance carried after resolution. Every member is
+ * optional; an absent object means legacy direct-formatting behavior.
+ */
+interface TableStyleCascade {
+    /** Explicitly selected `w:tblStyle`, if any. */
+    selectedStyleId?: string;
+    /** Type-default table style used when no explicit style exists. */
+    defaultStyleId?: string;
+    /** `basedOn` chain, base first. Undefined = not resolved yet. */
+    basedOnStyleIds?: string[];
+    /** Exact conditional regions applied, in cascade order. */
+    appliedRegions?: TableStyleRegion[];
+}
+/**
+ * Floating table properties
+ */
+interface FloatingTableProperties {
+    /** Horizontal anchor */
+    horzAnchor?: 'margin' | 'page' | 'text';
+    /** Vertical anchor */
+    vertAnchor?: 'margin' | 'page' | 'text';
+    /** Horizontal position */
+    tblpX?: number;
+    tblpXSpec?: 'left' | 'center' | 'right' | 'inside' | 'outside';
+    /** Vertical position */
+    tblpY?: number;
+    tblpYSpec?: 'top' | 'center' | 'bottom' | 'inside' | 'outside' | 'inline';
+    /** Distance from surrounding text */
+    topFromText?: number;
+    bottomFromText?: number;
+    leftFromText?: number;
+    rightFromText?: number;
+}
+/**
+ * Table formatting properties (w:tblPr)
+ */
+interface TableFormatting {
+    /** Table width */
+    width?: TableMeasurement;
+    /** Table justification */
+    justification?: 'left' | 'center' | 'right';
+    /** Cell spacing */
+    cellSpacing?: TableMeasurement;
+    /** Table indent from left margin */
+    indent?: TableMeasurement;
+    /** Table borders */
+    borders?: TableBorders;
+    /** Default cell margins */
+    cellMargins?: CellMargins;
+    /** Table layout */
+    layout?: 'fixed' | 'autofit';
+    /** Table style ID */
+    styleId?: string;
+    /** Table look (conditional formatting flags) */
+    look?: TableLook;
+    /** Shading/background */
+    shading?: ShadingProperties;
+    /** Overlap for floating tables */
+    overlap?: 'never' | 'overlap';
+    /** Floating table properties */
+    floating?: FloatingTableProperties;
+    /** Right to left table */
+    bidi?: boolean;
+    /** Horizontal band size (`w:tblStyleRowBandSize`). Undefined = 1. */
+    styleRowBandSize?: number;
+    /** Vertical band size (`w:tblStyleColBandSize`). Undefined = 1. */
+    styleColBandSize?: number;
+    /** Optional resolved style provenance. Undefined = legacy cascade. */
+    styleCascade?: TableStyleCascade;
+}
+/**
+ * Table row formatting properties (w:trPr)
+ */
+interface TableRowFormatting {
+    /** Row height */
+    height?: TableMeasurement;
+    /** Height rule */
+    heightRule?: 'auto' | 'atLeast' | 'exact';
+    /** Header row (repeats on each page) */
+    header?: boolean;
+    /** Allow row to break across pages */
+    cantSplit?: boolean;
+    /** Row justification */
+    justification?: 'left' | 'center' | 'right';
+    /** Hidden row */
+    hidden?: boolean;
+    /** Conditional format style */
+    conditionalFormat?: ConditionalFormatStyle;
+    /** Leading omitted grid columns (`w:gridBefore`). Undefined = 0. */
+    gridBefore?: number;
+    /** Trailing omitted grid columns (`w:gridAfter`). Undefined = 0. */
+    gridAfter?: number;
+    /** Preferred width before cells (`w:wBefore`). */
+    widthBefore?: TableMeasurement;
+    /** Preferred width after cells (`w:wAfter`). */
+    widthAfter?: TableMeasurement;
+}
+/**
+ * Conditional format style
+ */
+interface ConditionalFormatStyle {
+    /** First row */
+    firstRow?: boolean;
+    /** Last row */
+    lastRow?: boolean;
+    /** First column */
+    firstColumn?: boolean;
+    /** Last column */
+    lastColumn?: boolean;
+    /** Odd horizontal band */
+    oddHBand?: boolean;
+    /** Even horizontal band */
+    evenHBand?: boolean;
+    /** Odd vertical band */
+    oddVBand?: boolean;
+    /** Even vertical band */
+    evenVBand?: boolean;
+    /** Northwest corner */
+    nwCell?: boolean;
+    /** Northeast corner */
+    neCell?: boolean;
+    /** Southwest corner */
+    swCell?: boolean;
+    /** Southeast corner */
+    seCell?: boolean;
+}
+/**
+ * Table cell formatting properties (w:tcPr)
+ */
+interface TableCellFormatting {
+    /** Cell width */
+    width?: TableMeasurement;
+    /** Cell borders */
+    borders?: TableBorders;
+    /** Cell margins (override table default) */
+    margins?: CellMargins;
+    /** Cell shading/background */
+    shading?: ShadingProperties;
+    /** Vertical alignment */
+    verticalAlign?: 'top' | 'center' | 'bottom';
+    /** Text direction */
+    textDirection?: 'lr' | 'lrV' | 'rl' | 'rlV' | 'tb' | 'tbV' | 'tbRl' | 'tbRlV' | 'btLr';
+    /** Grid span (horizontal merge) */
+    gridSpan?: number;
+    /** Vertical merge */
+    vMerge?: 'restart' | 'continue';
+    /** Fit text to cell width */
+    fitText?: boolean;
+    /** Wrap text */
+    noWrap?: boolean;
+    /** Hide cell marker */
+    hideMark?: boolean;
+    /** Conditional format style */
+    conditionalFormat?: ConditionalFormatStyle;
+}
+
+export { type ThemeFont as A, type BorderSpec as B, type ColorValue as C, type ThemeFontScheme as D, type EmphasisMark as E, type FloatingTableProperties as F, type ThemeMatrixCell as G, generateThemeTintShadeMatrix as H, getThemeTintShadeHex as I, resolveColorToHex as J, type LineSpacingRule as L, type ParagraphFormatting as P, type RunFontHint as R, type ShadingProperties as S, type TextFormatting as T, type UnderlineStyle as U, type Theme as a, blendColors as b, type CellMargins as c, darkenColor as d, type ConditionalFormatStyle as e, type ParagraphAlignment as f, getContrastingColor as g, type RunLanguage as h, type TabLeader as i, type TabStop as j, type TabStopAlignment as k, lightenColor as l, type TableBorders as m, type TableCellFormatting as n, type TableFormatting as o, type TableLook as p, type TableMeasurement as q, resolveColor as r, type TableRowFormatting as s, type TableStyleCascade as t, type TableStyleRegion as u, type TableWidthType as v, type TextEffect as w, type TextModernEffects as x, type ThemeColorScheme as y, type ThemeColorSlot as z };