superdoc 2.2.1 → 2.3.0

package/dist/layout-engine/style-engine/src/ooxml/numbering-types.d.ts

@@ -0,0 +1,126 @@
+import { ParagraphProperties, RunProperties } from './types.js';
+/**
+ * Encoded properties for the w:numbering document.
+ */
+export interface NumberingProperties {
+    /** Numbering namespace identifier. */
+    nsid?: number;
+    /** Numbering template identifier. */
+    tmpl?: number;
+    /** Numbering name. */
+    name?: string;
+    /** Style link identifier. */
+    styleLink?: string;
+    /** Numbering style link identifier. */
+    numStyleLink?: string;
+    /** Multi-level type value. */
+    multiLevelType?: string;
+    /** Mac at cleanup numbering identifier. */
+    numIdMacAtCleanup?: number;
+    /** Abstract numbering definitions keyed by abstractNumId. */
+    abstracts?: Record<string, AbstractNumberingDefinition>;
+    /** Concrete numbering definitions keyed by numId. */
+    definitions?: Record<string, NumberingDefinition>;
+}
+/**
+ * Abstract numbering definition encoded from w:abstractNum.
+ */
+export interface AbstractNumberingDefinition {
+    /** Abstract numbering identifier. */
+    abstractNumId?: number;
+    /** Numbering namespace identifier. */
+    nsid?: number;
+    /** Numbering template identifier. */
+    tmpl?: number;
+    /** Abstract numbering name. */
+    name?: string;
+    /** Style link identifier. */
+    styleLink?: string;
+    /** Numbering style link identifier. */
+    numStyleLink?: string;
+    /** Multi-level type value. */
+    multiLevelType?: string;
+    /** Level definitions keyed by ilvl. */
+    levels?: Record<string, NumberingLevel>;
+}
+/**
+ * Concrete numbering definition encoded from w:num.
+ */
+export interface NumberingDefinition {
+    /** Numbering identifier. */
+    numId?: number;
+    /** Abstract numbering identifier reference. */
+    abstractNumId?: number;
+    /** Level overrides keyed by ilvl. */
+    lvlOverrides?: Record<string, NumberingLevelOverride>;
+}
+/**
+ * Numbering level definition encoded from w:lvl.
+ */
+export interface NumberingLevel {
+    /** Level index. */
+    ilvl?: number;
+    /** Template code. */
+    tplc?: number;
+    /** Tentative level flag. */
+    tentative?: boolean;
+    /** Level start value. */
+    start?: number;
+    /** Picture bullet identifier. */
+    lvlPicBulletId?: number;
+    /** Use legal numbering style. */
+    isLgl?: boolean;
+    /** Paragraph style identifier. */
+    styleId?: string;
+    /** Suffix setting. */
+    suff?: string;
+    /** Level text pattern. */
+    lvlText?: string;
+    /** Level justification. */
+    lvlJc?: string;
+    /** Numbering format properties. */
+    numFmt?: NumberingFormat;
+    /** Legacy numbering properties. */
+    legacy?: NumberingLegacyProperties;
+    /**
+     * Level restart limit. When set, counters at higher levels restart only when
+     * an ancestor level at or below this index has been used between the
+     * previous sibling and the current paragraph. `0` forces increment-only.
+     */
+    lvlRestart?: number;
+    /** Paragraph properties applied at this level. */
+    paragraphProperties?: ParagraphProperties;
+    /** Run properties applied at this level. */
+    runProperties?: RunProperties;
+}
+/**
+ * Numbering level override definition encoded from w:lvlOverride.
+ */
+export interface NumberingLevelOverride {
+    /** Level index. */
+    ilvl?: number;
+    /** Start override value. */
+    startOverride?: number;
+    /** Level definition override. */
+    lvl?: NumberingLevel;
+}
+/**
+ * Numbering format properties encoded from w:numFmt.
+ */
+export interface NumberingFormat {
+    /** Numbering format value. */
+    val?: string;
+    /** Numbering format string. */
+    format?: string;
+}
+/**
+ * Legacy numbering properties encoded from w:legacy.
+ */
+export interface NumberingLegacyProperties {
+    /** Legacy numbering flag. */
+    legacy?: boolean;
+    /** Legacy spacing value. */
+    legacySpace?: number;
+    /** Legacy indentation value. */
+    legacyIndent?: number;
+}

package/dist/layout-engine/style-engine/src/ooxml/styles-types.d.ts

@@ -0,0 +1,363 @@
+import { BorderProperties, ParagraphConditionalFormatting, ParagraphProperties, RunProperties, ShadingProperties } from './types.js';
+/**
+ * Encoded properties for the w:styles document.
+ */
+export interface StylesDocumentProperties {
+    /** Default run and paragraph properties for the document. */
+    docDefaults: DocDefaults;
+    /** Latent style definitions and defaults. */
+    latentStyles: LatentStyles;
+    /** Styles keyed by styleId. */
+    styles: Record<string, StyleDefinition>;
+}
+/**
+ * Default run and paragraph properties stored under w:docDefaults.
+ */
+export interface DocDefaults {
+    /** Default run properties. */
+    runProperties?: RunProperties;
+    /** Default paragraph properties. */
+    paragraphProperties?: ParagraphProperties;
+}
+/**
+ * Latent style defaults and per-style exceptions.
+ */
+export interface LatentStyles {
+    /** Default locked state for latent styles. */
+    defLockedState?: boolean;
+    /** Default UI priority value for latent styles (ST_DecimalNumber). */
+    defUIPriority?: number;
+    /** Default semi-hidden flag for latent styles. */
+    defSemiHidden?: boolean;
+    /** Default unhide-when-used flag for latent styles. */
+    defUnhideWhenUsed?: boolean;
+    /** Default quick-format flag for latent styles. */
+    defQFormat?: boolean;
+    /** Latent style exceptions keyed by style name. */
+    lsdExceptions?: Record<string, LsdException>;
+}
+/**
+ * Latent style exception definition.
+ */
+export interface LsdException {
+    /** Latent style name. */
+    name?: string;
+    /** Locked flag for the latent style. */
+    locked?: boolean;
+    /** Quick format flag for the latent style. */
+    qFormat?: boolean;
+    /** Semi-hidden flag for the latent style. */
+    semiHidden?: boolean;
+    /** Unhide-when-used flag for the latent style. */
+    unhideWhenUsed?: boolean;
+    /** UI priority value for the latent style. */
+    uiPriority?: number;
+}
+/**
+ * Encoded style definition from w:style.
+ */
+export interface StyleDefinition {
+    /** Style type (paragraph, character, table, etc.). */
+    type?: string;
+    /** Style identifier. */
+    styleId?: string;
+    /** Default style flag. */
+    default?: boolean;
+    /** Custom style flag. */
+    customStyle?: boolean;
+    /** Human-readable style name. */
+    name?: string;
+    /** Comma-separated style aliases. */
+    aliases?: string;
+    /** Based-on style identifier. */
+    basedOn?: string;
+    /** Next style identifier. */
+    next?: string;
+    /** Linked style identifier. */
+    link?: string;
+    /** Auto-redefine flag. */
+    autoRedefine?: boolean;
+    /** Hidden style flag. */
+    hidden?: boolean;
+    /** Semi-hidden style flag. */
+    semiHidden?: boolean;
+    /** Unhide-when-used style flag. */
+    unhideWhenUsed?: boolean;
+    /** Quick-format style flag. */
+    qFormat?: boolean;
+    /** Locked style flag. */
+    locked?: boolean;
+    /** Personal style flag. */
+    personal?: boolean;
+    /** Personal compose flag. */
+    personalCompose?: boolean;
+    /** Personal reply flag. */
+    personalReply?: boolean;
+    /** UI priority value. */
+    uiPriority?: number;
+    /** Revision identifier. */
+    rsid?: number;
+    /** Paragraph properties applied by the style. */
+    paragraphProperties?: ParagraphProperties;
+    /** Run properties applied by the style. */
+    runProperties?: RunProperties;
+    /** Table properties applied by the style. */
+    tableProperties?: TableProperties;
+    /** Table row properties applied by the style. */
+    tableRowProperties?: TableRowProperties;
+    /** Table cell properties applied by the style. */
+    tableCellProperties?: TableCellProperties;
+    /** Table style properties applied by the style. */
+    tableStyleProperties?: Record<TableStyleType, TableStyleProperties>;
+}
+/**
+ * Generic measurement properties used by table layout elements.
+ */
+export interface MeasurementProperties {
+    /** Measurement value, usually in twentieths of a point. */
+    value?: number;
+    /** Measurement type (auto, dxa, pct, etc.). */
+    type?: string;
+}
+/**
+ * Table properties encoded from w:tblPr.
+ */
+export interface TableProperties {
+    /** Right-to-left visual order for table rendering. */
+    rightToLeft?: boolean;
+    /** Table justification value. */
+    justification?: string;
+    /** Table shading properties. */
+    shading?: ShadingProperties;
+    /** Table caption text. */
+    caption?: string;
+    /** Table cell spacing properties. */
+    tableCellSpacing?: MeasurementProperties;
+    /** Table description text. */
+    description?: string;
+    /** Table indent properties. */
+    tableIndent?: MeasurementProperties;
+    /** Table layout algorithm. */
+    tableLayout?: string;
+    /** Table look settings. */
+    tblLook?: TableLookProperties;
+    /** Table overlap behavior. */
+    overlap?: string;
+    /** Table style identifier. */
+    tableStyleId?: string;
+    /** Table style column band size. */
+    tableStyleColBandSize?: number;
+    /** Table style row band size. */
+    tableStyleRowBandSize?: number;
+    /** Table width properties. */
+    tableWidth?: MeasurementProperties;
+    /** Floating table properties. */
+    floatingTableProperties?: TableFloatingProperties;
+    /** Table border properties. */
+    borders?: TableBorders;
+    /** Table cell margin properties. */
+    cellMargins?: TableCellMargins;
+}
+/**
+ * Table look properties from w:tblLook.
+ */
+export interface TableLookProperties {
+    /** Apply first column formatting. */
+    firstColumn?: boolean;
+    /** Apply first row formatting. */
+    firstRow?: boolean;
+    /** Apply last column formatting. */
+    lastColumn?: boolean;
+    /** Apply last row formatting. */
+    lastRow?: boolean;
+    /** Disable horizontal banding. */
+    noHBand?: boolean;
+    /** Disable vertical banding. */
+    noVBand?: boolean;
+    /** Raw table look value. */
+    val?: string;
+}
+/**
+ * Floating table positioning properties.
+ */
+export interface TableFloatingProperties {
+    /** Distance from left text boundary. */
+    leftFromText?: number;
+    /** Distance from right text boundary. */
+    rightFromText?: number;
+    /** Distance from top text boundary. */
+    topFromText?: number;
+    /** Distance from bottom text boundary. */
+    bottomFromText?: number;
+    /** Horizontal position value. */
+    tblpX?: number;
+    /** Vertical position value. */
+    tblpY?: number;
+    /** Horizontal anchor reference. */
+    horzAnchor?: string;
+    /** Vertical anchor reference. */
+    vertAnchor?: string;
+    /** Horizontal position specifier. */
+    tblpXSpec?: string;
+    /** Vertical position specifier. */
+    tblpYSpec?: string;
+}
+/**
+ * Table border properties.
+ */
+export interface TableBorders {
+    /** Bottom border definition. */
+    bottom?: BorderProperties;
+    /** End border definition. */
+    end?: BorderProperties;
+    /** Inside horizontal border definition. */
+    insideH?: BorderProperties;
+    /** Inside vertical border definition. */
+    insideV?: BorderProperties;
+    /** Left border definition. */
+    left?: BorderProperties;
+    /** Right border definition. */
+    right?: BorderProperties;
+    /** Start border definition. */
+    start?: BorderProperties;
+    /** Top border definition. */
+    top?: BorderProperties;
+}
+/**
+ * Table cell border properties, including diagonal borders.
+ */
+export interface TableCellBorders {
+    /** Top border definition. */
+    top?: BorderProperties;
+    /** Start border definition. */
+    start?: BorderProperties;
+    /** Left border definition. */
+    left?: BorderProperties;
+    /** Bottom border definition. */
+    bottom?: BorderProperties;
+    /** End border definition. */
+    end?: BorderProperties;
+    /** Right border definition. */
+    right?: BorderProperties;
+    /** Inside horizontal border definition. */
+    insideH?: BorderProperties;
+    /** Inside vertical border definition. */
+    insideV?: BorderProperties;
+    /** Top-left to bottom-right diagonal border definition. */
+    tl2br?: BorderProperties;
+    /** Top-right to bottom-left diagonal border definition. */
+    tr2bl?: BorderProperties;
+}
+/**
+ * Table cell margin properties.
+ */
+export interface TableCellMargins {
+    /** Bottom margin properties. */
+    marginBottom?: MeasurementProperties;
+    /** End margin properties. */
+    marginEnd?: MeasurementProperties;
+    /** Left margin properties. */
+    marginLeft?: MeasurementProperties;
+    /** Right margin properties. */
+    marginRight?: MeasurementProperties;
+    /** Start margin properties. */
+    marginStart?: MeasurementProperties;
+    /** Top margin properties. */
+    marginTop?: MeasurementProperties;
+}
+/**
+ * Table row properties encoded from w:trPr.
+ */
+export interface TableRowProperties {
+    /** Prevent row from splitting across pages. */
+    cantSplit: boolean;
+    /** Conditional formatting properties. */
+    cnfStyle?: ParagraphConditionalFormatting;
+    /** Division identifier value. */
+    divId?: string;
+    /** Grid cells after the row. */
+    gridAfter?: number;
+    /** Grid cells before the row. */
+    gridBefore?: number;
+    /** Hide the row. */
+    hidden: boolean;
+    /** Row justification value. */
+    justification?: string;
+    /** Table property-exception borders from `w:tblPrEx/w:tblBorders`. */
+    tblPrExBorders?: TableBorders;
+    /** Table cell spacing properties. */
+    tableCellSpacing?: MeasurementProperties;
+    /** Repeat header row flag. */
+    repeatHeader: boolean;
+    /** Row height properties. */
+    rowHeight?: TableRowHeight;
+    /** Width after the row. */
+    wAfter?: MeasurementProperties;
+    /** Width before the row. */
+    wBefore?: MeasurementProperties;
+}
+/**
+ * Table row height properties.
+ */
+export interface TableRowHeight {
+    /** Row height value. */
+    value?: number;
+    /** Row height rule. */
+    rule?: string;
+}
+/**
+ * Table cell properties encoded from w:tcPr.
+ */
+export interface TableCellProperties {
+    /** Conditional formatting properties. */
+    cnfStyle?: ParagraphConditionalFormatting;
+    /** Table cell width properties. */
+    cellWidth?: MeasurementProperties;
+    /** Horizontal grid span for the cell. */
+    gridSpan?: number;
+    /** Vertical merge behavior. */
+    vMerge?: string;
+    /** Table cell border properties. */
+    borders?: TableCellBorders;
+    /** Table cell shading properties. */
+    shading?: ShadingProperties;
+    /** Disable wrapping within the cell. */
+    noWrap?: boolean;
+    /** Table cell margin properties. */
+    cellMargins?: TableCellMargins;
+    /** Text direction within the cell. */
+    textDirection?: string;
+    /** Fit text within the cell. */
+    tcFitText?: boolean;
+    /** Vertical alignment within the cell. */
+    vAlign?: string;
+    /** Hide the cell mark. */
+    hideMark?: boolean;
+    /** Header references applied to the cell. */
+    headers?: TableHeaderReference[];
+}
+/**
+ * Header reference entry encoded from w:headers.
+ */
+export interface TableHeaderReference {
+    /** Header value. */
+    header: string;
+}
+export type TableStyleType = 'wholeTable' | 'firstRow' | 'lastRow' | 'firstCol' | 'lastCol' | 'band1Vert' | 'band2Vert' | 'band1Horz' | 'band2Horz' | 'neCell' | 'nwCell' | 'seCell' | 'swCell';
+/**
+ * Table style properties encoded from w:tblStylePr.
+ */
+export interface TableStyleProperties {
+    /** Table style property type. */
+    type?: TableStyleType;
+    /** Paragraph properties for the table style. */
+    paragraphProperties?: ParagraphProperties;
+    /** Run properties for the table style. */
+    runProperties?: RunProperties;
+    /** Table properties for the table style. */
+    tableProperties?: TableProperties;
+    /** Table row properties for the table style. */
+    tableRowProperties?: TableRowProperties;
+    /** Table cell properties for the table style. */
+    tableCellProperties?: TableCellProperties;
+}

package/dist/layout-engine/style-engine/src/ooxml/table-style-selection.d.ts

@@ -0,0 +1,86 @@
+import { StylesDocumentProperties } from './styles-types.js';
+export declare const TABLE_STYLE_ID_TABLE_GRID = "TableGrid";
+export declare const TABLE_STYLE_ID_TABLE_NORMAL = "TableNormal";
+/** Fallback border applied when no table style exists at all (source: 'none'). */
+export declare const TABLE_FALLBACK_BORDER: {
+    readonly val: "single";
+    readonly size: 4;
+    readonly color: "#000000";
+};
+export declare const TABLE_FALLBACK_BORDERS: {
+    readonly top: {
+        readonly val: "single";
+        readonly size: 4;
+        readonly color: "#000000";
+    };
+    readonly left: {
+        readonly val: "single";
+        readonly size: 4;
+        readonly color: "#000000";
+    };
+    readonly bottom: {
+        readonly val: "single";
+        readonly size: 4;
+        readonly color: "#000000";
+    };
+    readonly right: {
+        readonly val: "single";
+        readonly size: 4;
+        readonly color: "#000000";
+    };
+    readonly insideH: {
+        readonly val: "single";
+        readonly size: 4;
+        readonly color: "#000000";
+    };
+    readonly insideV: {
+        readonly val: "single";
+        readonly size: 4;
+        readonly color: "#000000";
+    };
+};
+/** Default cell padding in dxa (twips). left/right = 108 dxa ≈ 0.075in, matching Word defaults. */
+export declare const TABLE_FALLBACK_CELL_PADDING: {
+    readonly top: 0;
+    readonly bottom: 0;
+    readonly left: 108;
+    readonly right: 108;
+};
+export type ResolvedStyleSource = 'explicit' | 'settings-default' | 'type-default' | 'builtin-fallback' | 'none';
+export interface ResolvedStyle {
+    styleId: string | null;
+    source: ResolvedStyleSource;
+}
+export interface TableSemanticStyleHints {
+    readonly normalTableStyleId?: string | null;
+    readonly tableGridStyleId?: string | null;
+}
+/**
+ * Checks whether a style ID exists in the catalog and is of type `table`.
+ */
+export declare function isKnownTableStyleId(styleId: string | null | undefined, translatedLinkedStyles: StylesDocumentProperties | null | undefined): boolean;
+/**
+ * Finds the type-default table style: `w:style w:type="table" w:default="1"`.
+ * Typically `TableNormal`.
+ */
+export declare function findTypeDefaultTableStyleId(translatedLinkedStyles: StylesDocumentProperties | null | undefined): string | null;
+/**
+ * Determines the effective style ID for a table already in the document.
+ *
+ * Precedence:
+ *  1. Explicit `tableStyleId` on the node, if valid (exists + type=table).
+ *  2. Type-default table style from catalog (`w:default="1"`).
+ *  3. No style (`source: 'none'`).
+ */
+export declare function resolveExistingTableEffectiveStyleId(explicitTableStyleId: string | null | undefined, translatedLinkedStyles: StylesDocumentProperties | null | undefined): ResolvedStyle;
+/**
+ * Determines the preferred style ID for a newly created table.
+ *
+ * Precedence:
+ *  1. `w:defaultTableStyle` from settings, if present and resolvable.
+ *  2. Type-default table style (`w:default="1"`).
+ *  3. `TableGrid` if it exists in catalog (builtin-fallback).
+ *  4. `TableNormal` if it exists in catalog (builtin-fallback).
+ *  5. No style (`source: 'none'`).
+ */
+export declare function resolvePreferredNewTableStyleId(settingsDefaultTableStyleId: string | null | undefined, translatedLinkedStyles: StylesDocumentProperties | null | undefined, semanticHints?: TableSemanticStyleHints): ResolvedStyle;