superdoc 2.2.1 → 2.3.0

package/dist/layout-engine/contracts/src/engines/tabs.d.ts

@@ -0,0 +1,117 @@
+import { ParagraphIndent } from './paragraph.js';
+/**
+ * OOXML-aligned tab stop definition.
+ * Positions are in twips (1/1440 inch) to preserve exact OOXML values.
+ * Common conversions: 720 twips = 0.5", 1440 twips = 1"
+ */
+export interface TabStop {
+    val: 'start' | 'end' | 'center' | 'decimal' | 'bar' | 'clear';
+    pos: number;
+    leader?: 'none' | 'dot' | 'hyphen' | 'heavy' | 'underscore' | 'middleDot';
+    source?: 'explicit' | 'default';
+}
+/**
+ * Context for tab stop computation.
+ * All measurements in twips to match OOXML precision.
+ */
+export interface TabContext {
+    explicitStops: TabStop[];
+    defaultTabInterval: number;
+    paragraphIndent: ParagraphIndent;
+    rawParagraphIndent?: ParagraphIndent;
+}
+/**
+ * A run with its computed horizontal position.
+ * Generic over run type so both PM and layout can use it.
+ */
+export interface RunPosition<T = unknown> {
+    run: T;
+    x: number;
+    width: number;
+    tabStop?: TabStop;
+}
+export interface TabbedRun<T = unknown> {
+    run: T;
+    width: number;
+    isTab?: boolean;
+    text?: string;
+}
+export interface LayoutWithTabsOptions<T = unknown> {
+    measureTextWidth?: (run: T, text: string) => number;
+    decimalSeparator?: string;
+}
+export interface CalculateTabWidthParams {
+    /**
+     * Current horizontal position before the tab, in the same units as tabStops (usually px)
+     */
+    currentX: number;
+    /**
+     * Sorted tab stops in the same units as currentX. Use computeTabStops + unit conversion first.
+     */
+    tabStops: TabStop[];
+    /**
+     * Available paragraph width in the same units.
+     */
+    paragraphWidth: number;
+    /**
+     * Default tab distance (fallback) in the same units.
+     */
+    defaultTabDistance: number;
+    /**
+     * Default line length (used to repeat the default grid) in the same units.
+     */
+    defaultLineLength: number;
+    /**
+     * Text immediately following the tab (used for center/end/decimal).
+     */
+    followingText?: string;
+    /**
+     * Optional measurement function for followingText; if omitted, length-based approximation is used.
+     */
+    measureText?: (text: string) => number;
+    /**
+     * Decimal separator character for decimal/num tabs.
+     */
+    decimalSeparator?: string;
+}
+export interface CalculateTabWidthResult {
+    width: number;
+    leader?: TabStop['leader'];
+    alignment: TabStop['val'] | 'default';
+    tabStopPosUsed: number | 'default';
+}
+/**
+ * Compute the full set of tab stops for a paragraph.
+ *
+ * Merges explicit stops from the style with default stops at regular intervals.
+ * Filters out stops that fall before the paragraph's left indent.
+ *
+ * @param context - Tab context (explicit stops, defaults, indents in twips)
+ * @returns Sorted array of tab stops in twips
+ */
+export declare function computeTabStops(context: TabContext): TabStop[];
+/**
+ * Layout runs with tab awareness, computing horizontal positions.
+ *
+ * Handles all OOXML tab alignment types:
+ * - start: Text begins at tab stop (left-aligned)
+ * - end: Text ends at tab stop (right-aligned)
+ * - center: Text is centered at tab stop
+ * - decimal: Decimal separator aligns at tab stop
+ * - bar: Vertical line at tab stop (handled by painters, not layout)
+ *
+ * Note: This function operates in the measurer's coordinate space (typically pixels).
+ * Tab stop positions should be converted from twips before calling this function.
+ *
+ * @param runs - Array of runs with pre-computed widths (in measurer units)
+ * @param stops - Sorted tab stops (positions converted to measurer units)
+ * @param lineWidth - Maximum line width (in measurer units)
+ * @param options - Optional config (measureTextWidth for accuracy, decimalSeparator for locale)
+ * @returns Runs with computed x positions
+ */
+export declare function layoutWithTabs<T>(runs: TabbedRun<T>[], stops: TabStop[], lineWidth: number, options?: LayoutWithTabsOptions<T>): RunPosition<T>[];
+/**
+ * Compute the visual width a tab should occupy based on tab stops and following text.
+ * This is a pure helper for consumers that only need a single tab width (e.g., adapters).
+ */
+export declare function calculateTabWidth(params: CalculateTabWidthParams): CalculateTabWidthResult;

package/dist/layout-engine/contracts/src/graphic-placement.d.ts

@@ -0,0 +1,76 @@
+type AnchorVRelative = 'paragraph' | 'page' | 'margin';
+type AnchorHRelative = 'column' | 'page' | 'margin';
+type AnchorAlignH = 'left' | 'center' | 'right';
+type AnchorAlignV = 'top' | 'center' | 'bottom';
+export declare function isPositionedParagraphFrame<T extends {
+    wrap?: string;
+}>(frame: T | undefined): frame is T & {
+    wrap: 'around' | 'none';
+};
+export declare function isPagePositionedParagraphFrame(frame: {
+    wrap?: string;
+    vAnchor?: string;
+    y?: number;
+} | undefined): frame is {
+    wrap: 'around' | 'none';
+    vAnchor: 'page';
+    y: number;
+};
+/**
+ * Resolve the page-space origin used for page-anchored paragraph frames in a footer.
+ * Invalid or negative bottom margins behave like a zero margin.
+ */
+export declare function resolveFooterPageFrameOriginY(pageHeight: number, bottomMargin?: number): number;
+export type ColumnLayoutForAnchor = {
+    width: number;
+    gap: number;
+    count: number;
+    widths?: number[];
+    gaps?: number[];
+};
+/**
+ * Inputs for resolving the paint Y of an anchored image, drawing, or floating table.
+ * `offsetV` is applied inside this function; callers must pass the resolved value to
+ * text-wrap registration without adding `offsetV` again.
+ */
+export type ResolveAnchoredGraphicYInput = {
+    anchor?: {
+        vRelativeFrom?: AnchorVRelative;
+        alignV?: AnchorAlignV;
+        offsetV?: number;
+    };
+    objectHeight: number;
+    contentTop: number;
+    contentBottom: number;
+    /** Bottom page margin in px (used when vRelativeFrom is `page`). */
+    pageBottomMargin?: number;
+    /**
+     * Anchor paragraph top Y (body cursor when laying out the anchor paragraph).
+     * Used for `paragraph` and legacy (undefined vRelativeFrom) positioning.
+     */
+    anchorParagraphY?: number;
+    /** First line height of the anchor paragraph (paragraph-relative alignV). */
+    firstLineHeight?: number;
+    /**
+     * When true, anchor has no host paragraph (pre-registered / paragraphless layout).
+     * For `vRelativeFrom: 'paragraph'`, use `contentTop + offsetV` instead of alignV on a
+     * synthetic paragraph (defaults would wrongly center/bottom against contentTop).
+     */
+    preRegisteredFallbackToContentTop?: boolean;
+};
+/**
+ * Resolve the vertical paint position for an anchored graphic (image, drawing, or table).
+ */
+export declare function resolveAnchoredGraphicY(input: ResolveAnchoredGraphicYInput): number;
+/**
+ * Resolve horizontal paint position for an anchored graphic.
+ */
+export declare function resolveAnchoredGraphicX(anchor: {
+    hRelativeFrom?: AnchorHRelative;
+    alignH?: AnchorAlignH;
+    offsetH?: number;
+}, columnIndex: number, columns: ColumnLayoutForAnchor, objectWidth: number, margins?: {
+    left?: number;
+    right?: number;
+}, pageWidth?: number): number;
+export {};

package/dist/layout-engine/contracts/src/header-footer-inheritance.d.ts

@@ -0,0 +1,22 @@
+import { HeaderFooterType } from './index.js';
+export type HeaderFooterRefMap = Partial<Record<HeaderFooterType, string | null | undefined>>;
+export type HeaderFooterRefIdentifier = {
+    headerIds?: HeaderFooterRefMap;
+    footerIds?: HeaderFooterRefMap;
+    sectionCount?: number;
+    sectionHeaderIds?: Map<number, HeaderFooterRefMap>;
+    sectionFooterIds?: Map<number, HeaderFooterRefMap>;
+};
+export type ResolveInheritedHeaderFooterRefInput = {
+    identifier: HeaderFooterRefIdentifier;
+    sectionIndex: number;
+    kind: 'header' | 'footer';
+    variantType: HeaderFooterType;
+    pageRefs?: HeaderFooterRefMap;
+};
+export type ResolvedInheritedHeaderFooterRef = {
+    ref: string;
+    variantType: HeaderFooterType;
+};
+export declare function resolveInheritedHeaderFooterRefWithType({ identifier, sectionIndex, kind, variantType, pageRefs, }: ResolveInheritedHeaderFooterRefInput): ResolvedInheritedHeaderFooterRef | null;
+export declare function resolveInheritedHeaderFooterRef(input: ResolveInheritedHeaderFooterRefInput): string | null;

package/dist/layout-engine/contracts/src/header-footer-resolution.d.ts

@@ -0,0 +1,28 @@
+export type HeaderFooterKind = 'header' | 'footer';
+export type HeaderFooterVariant = 'default' | 'first' | 'even' | 'odd';
+export type HeaderFooterSectionRefs = Partial<Record<HeaderFooterVariant, string | null>>;
+export type HeaderFooterResolutionSection = {
+    sectionIndex: number;
+    titlePg?: boolean;
+    headerRefs?: HeaderFooterSectionRefs | null;
+    footerRefs?: HeaderFooterSectionRefs | null;
+};
+export type HeaderFooterVariantSelectionInput = {
+    documentPageNumber: number;
+    sectionPageNumber: number;
+    titlePg?: boolean;
+    alternateHeaders?: boolean;
+};
+export type HeaderFooterEffectiveRefInput = {
+    sections: readonly HeaderFooterResolutionSection[];
+    sectionIndex: number;
+    kind: HeaderFooterKind;
+    variant: HeaderFooterVariant;
+};
+export type HeaderFooterEffectiveRefResult = {
+    refId: string;
+    matchedSectionIndex: number;
+    matchedVariant: HeaderFooterVariant;
+};
+export declare function selectHeaderFooterVariantForPage({ documentPageNumber, sectionPageNumber, titlePg, alternateHeaders, }: HeaderFooterVariantSelectionInput): HeaderFooterVariant | null;
+export declare function resolveEffectiveHeaderFooterRef({ sections, sectionIndex, kind, variant, }: HeaderFooterEffectiveRefInput): HeaderFooterEffectiveRefResult | null;

package/dist/layout-engine/contracts/src/incremental-dependency.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Stable dependency classes that an incremental page checkpoint may fence.
+ *
+ * This list is proof metadata, never a feature switch. Producers must name
+ * every retained dependency that required the checkpoint; consumers reject
+ * empty, duplicate, or unknown lists instead of trusting a generic boolean.
+ */
+export type PageCheckpointDependencyClass = 'multiple-sections' | 'furniture-page-tokens' | 'non-balanceable-multi-column-sections' | 'body-anchored-objects' | 'footnotes' | 'page-references' | 'keep-constraints' | 'tables' | 'furniture-anchored-objects';
+export declare const PAGE_CHECKPOINT_DEPENDENCY_CLASSES: readonly ["multiple-sections", "furniture-page-tokens", "non-balanceable-multi-column-sections", "body-anchored-objects", "footnotes", "page-references", "keep-constraints", "tables", "furniture-anchored-objects"];
+export declare function areValidPageCheckpointDependencyClasses(value: unknown): value is readonly PageCheckpointDependencyClass[];