superdoc 2.2.0 → 2.3.0

package/dist/layout-engine/contracts/src/justify-utils.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared justify alignment utilities.
+ *
+ * CRITICAL: This module provides the single source of truth for justify decisions.
+ * Both the painter (visual rendering) and text measurement (caret positioning) MUST use
+ * these functions to ensure consistent behavior and prevent caret drift.
+ */
+/**
+ * Set of characters considered as spaces for justify distribution.
+ * Includes both regular space and non-breaking space.
+ */
+export declare const SPACE_CHARS: Set<string>;
+/**
+ * Parameters for determining whether to apply justify to a line.
+ */
+export type ShouldApplyJustifyParams = {
+    /** Paragraph alignment value (must be 'justify' for justify to apply). */
+    alignment: string | undefined;
+    /** Whether the line has explicit segment positioning. Used as a legacy fallback. */
+    hasExplicitPositioning?: boolean;
+    /** Whether the line used author-defined OOXML tab stops. */
+    hasExplicitTabStops?: boolean;
+    /** Whether this is the last line of the paragraph. */
+    isLastLineOfParagraph: boolean;
+    /** Whether the paragraph ends with a soft break (Shift+Enter / LineBreak run). */
+    paragraphEndsWithLineBreak: boolean;
+    /** Explicit override to skip justify (e.g., from rendering context). */
+    skipJustifyOverride?: boolean;
+};
+/**
+ * Determines whether justify spacing should be applied to a line.
+ *
+ * Justify is applied when ALL of the following are true:
+ * - Alignment is 'justify'
+ * - No explicit skip override
+ * - Line doesn't have author-defined tab stops
+ * - Line is NOT the last line, OR paragraph ends with a soft break
+ *
+ * This matches Microsoft Word's behavior:
+ * - All lines are justified except the true last line
+ * - Soft breaks (Shift+Enter) do NOT count as "last line"
+ * - Explicit tab-aligned text is never justified
+ * - Default/manual tab-aligned text can still be justified
+ *
+ * @param params - Parameters for justify decision
+ * @returns true if justify should be applied, false otherwise
+ */
+export declare function shouldApplyJustify(params: ShouldApplyJustifyParams): boolean;
+/**
+ * Parameters for calculating justify spacing.
+ */
+export type CalculateJustifySpacingParams = {
+    /** Line width (use naturalWidth ?? width to support compression). */
+    lineWidth: number;
+    /** Available width for the line. */
+    availableWidth: number;
+    /** Number of space characters in the line. */
+    spaceCount: number;
+    /** Whether justify should be applied (from shouldApplyJustify). */
+    shouldJustify: boolean;
+};
+/**
+ * Calculates the extra spacing to apply per space character for justify.
+ *
+ * Returns the number of pixels to add after each space (via CSS word-spacing).
+ * Can be negative for compression (when line is slightly too wide).
+ *
+ * Returns 0 if:
+ * - Justify should not be applied
+ * - There are no spaces in the line (division by zero prevention)
+ *
+ * Formula: (availableWidth - lineWidth) / spaceCount
+ *
+ * @param params - Parameters for spacing calculation
+ * @returns Extra spacing per space in pixels (can be negative)
+ */
+/**
+ * Computes the first-line indent offset from paragraph indent attributes.
+ *
+ * Returns 0 when first-line indent is suppressed.
+ * The result is positive for firstLine indent, negative for hanging indent.
+ */
+export declare function getFirstLineIndentOffset(indent: {
+    firstLine?: number;
+    hanging?: number;
+} | undefined, suppressFirstLineIndent: boolean): number;
+/**
+ * Adjusts availableWidth for first-line text indent.
+ *
+ * Negative textIndent (hanging indent): the measurer sets line.maxWidth to the
+ * correct wider value, but Math.min with fallbackAvailableWidth clamps it back down.
+ * Always adjust to restore actual available space.
+ *
+ * Positive textIndent (firstLine indent): the measurer already bakes it into
+ * line.maxWidth, so only adjust on the fallback path (maxWidth not set).
+ */
+export declare function adjustAvailableWidthForTextIndent(availableWidth: number, textIndentOffset: number, lineMaxWidth: number | null | undefined): number;
+export declare function calculateJustifySpacing(params: CalculateJustifySpacingParams): number;

package/dist/layout-engine/contracts/src/layout-identity.d.ts

@@ -0,0 +1,136 @@
+import { SourceAnchor } from './index.js';
+/**
+ * Schema version for the editor-neutral layout boundary substrate.
+ *
+ * Bump when an additive field becomes load-bearing or a field changes
+ * semantics. Pure additive growth (adding optional fields) does not require a
+ * bump, but a renamed/typed-change field does.
+ */
+export declare const LAYOUT_BOUNDARY_SCHEMA = "layout-identity/1";
+/**
+ * Stable opaque identifier for a rendered fragment.
+ *
+ * The painter writes this as `data-layout-fragment-id` and the layout-bridge
+ * neutral hit-test entry points return it. Format is an opaque string; callers
+ * MUST NOT parse it. Today it is derived from `blockId` plus the fragment's
+ * local position (`fromLine`/`fromRow` / atomic anchor) so it stays stable
+ * across re-layouts that preserve a fragment's identity. Future producers may
+ * mint stronger ids without invalidating this contract.
+ */
+export type LayoutFragmentId = string;
+/**
+ * Story kind for the surface a rendered fragment belongs to.
+ *
+ * The set mirrors the surfaces SuperDoc currently renders. `'unknown'` is
+ * used when the producer cannot classify a fragment yet (for example
+ * standalone footnote/endnote stories that have not been wired up to the
+ * neutral boundary). Consumers MUST treat `'unknown'` as a diagnostic
+ * fallback, not as a default value.
+ */
+export type LayoutStoryKind = 'body' | 'header' | 'footer' | 'footnote' | 'endnote' | 'textbox' | 'unknown';
+/**
+ * Story locator carried alongside every neutral identity.
+ *
+ * `id` is set when the producer can name the story (a header/footer part
+ * relationship id, a footnote/endnote story id). For body content it is
+ * omitted.
+ */
+export type LayoutStoryLocator = {
+    kind: LayoutStoryKind;
+    id?: string;
+};
+/**
+ * Reference to the source block a fragment belongs to.
+ *
+ * Today this is the producer's existing `blockId`. The type is intentionally
+ * opaque so a future v2 source provider can substitute a richer reference
+ * (e.g. a part-uri / xpath tuple) without reopening the layout boundary
+ * contract.
+ */
+export type LayoutBlockRef = string;
+/**
+ * Composite editor-neutral identity for a rendered fragment.
+ *
+ * Carries the minimum information needed to address a rendered fragment
+ * without consulting ProseMirror: the story, the source block, the stable
+ * fragment id, and (when available) a layout-side cross-reference to the
+ * DOCX source anchor that produced the fragment.
+ */
+export type LayoutSourceIdentity = {
+    schema: typeof LAYOUT_BOUNDARY_SCHEMA;
+    story: LayoutStoryLocator;
+    blockRef: LayoutBlockRef;
+    fragmentId: LayoutFragmentId;
+    sourceAnchor?: SourceAnchor;
+};
+export type LayoutPartialRowIdentity = {
+    rowIndex?: number;
+    fromLineByCell?: readonly number[];
+    toLineByCell?: readonly number[];
+};
+/**
+ * Build a `LayoutStoryLocator` for body content.
+ */
+export declare const bodyStoryLocator: () => LayoutStoryLocator;
+/**
+ * Build a `LayoutStoryLocator` for an HF / footnote / endnote story.
+ */
+export declare const namedStoryLocator: (kind: Exclude<LayoutStoryKind, "body" | "unknown">, id: string) => LayoutStoryLocator;
+/**
+ * Compute a stable `LayoutFragmentId` for a fragment.
+ *
+ * Inputs are the values the producer already has on hand. The shape of the
+ * output is intentionally opaque; consumers compare ids for equality and
+ * round-trip them through DOM datasets, but never parse them.
+ */
+export declare const computeLayoutFragmentId: (input: {
+    blockId: string;
+    story?: LayoutStoryLocator;
+    kind: string;
+    fromLine?: number;
+    toLine?: number;
+    fromRow?: number;
+    toRow?: number;
+    itemId?: string;
+    x?: number;
+    y?: number;
+    partialRow?: LayoutPartialRowIdentity;
+}) => LayoutFragmentId;
+/**
+ * Build a `LayoutSourceIdentity` from producer-known fields.
+ */
+export declare const buildLayoutSourceIdentity: (input: {
+    blockId: string;
+    story?: LayoutStoryLocator;
+    kind: string;
+    fromLine?: number;
+    toLine?: number;
+    fromRow?: number;
+    toRow?: number;
+    itemId?: string;
+    x?: number;
+    y?: number;
+    partialRow?: LayoutPartialRowIdentity;
+    sourceAnchor?: SourceAnchor;
+}) => LayoutSourceIdentity;
+type LayoutIdentityFragmentLike = {
+    kind: string;
+    blockId: string;
+    layoutSourceIdentity?: LayoutSourceIdentity;
+    sourceAnchor?: SourceAnchor;
+    fromLine?: number;
+    toLine?: number;
+    fromRow?: number;
+    toRow?: number;
+    itemId?: string;
+    x?: number;
+    y?: number;
+    partialRow?: LayoutPartialRowIdentity;
+};
+/**
+ * Build neutral identity from the fragment fields already used by renderer and
+ * resolved-layout fragment keys. Keeping this in the contract package prevents
+ * drift between DOM datasets, neutral hit tests, and resolved paint items.
+ */
+export declare const buildLayoutSourceIdentityForFragment: (fragment: LayoutIdentityFragmentLike, story?: LayoutStoryLocator) => LayoutSourceIdentity;
+export {};

package/dist/layout-engine/contracts/src/ooxml-z-index.d.ts

@@ -0,0 +1,46 @@
+import { ImageBlock, DrawingBlock } from './index.js';
+/** Checks whether `value` is a non-null, non-array object. */
+export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+/**
+ * Base value for OOXML relativeHeight z-ordering.
+ *
+ * @example
+ * - 251658240 → 0 (base/background)
+ * - 251658242 → 2 (slightly above base)
+ * - 251658291 → 51 (further above)
+ */
+export declare const OOXML_Z_INDEX_BASE = 251658240;
+/**
+ * Coerces relativeHeight from OOXML (number or string) to a finite number.
+ */
+export declare function coerceRelativeHeight(raw: unknown): number | undefined;
+/**
+ * Normalizes z-index from OOXML relativeHeight value.
+ *
+ * OOXML uses large numbers starting around 251658240. To preserve the relative
+ * stacking order, we subtract the base value to get a small positive number
+ * suitable for CSS z-index. This ensures elements with close relativeHeight
+ * values maintain their correct stacking order.
+ *
+ * @param originalAttributes - The originalAttributes object from ProseMirror node attrs
+ * @returns Normalized z-index number or undefined if no relativeHeight
+ *
+ * @example
+ * ```typescript
+ * normalizeZIndex({ relativeHeight: 251658240 }); // 0 (background)
+ * normalizeZIndex({ relativeHeight: 251658242 }); // 2 (above background)
+ * normalizeZIndex({ relativeHeight: 251658291 }); // 51 (further above)
+ * normalizeZIndex({}); // undefined
+ * normalizeZIndex(null); // undefined
+ * ```
+ */
+export declare function normalizeZIndex(originalAttributes: unknown): number | undefined;
+/**
+ * Resolves floating z-index based on behindDoc flag and raw OOXML value.
+ */
+export declare function resolveFloatingZIndex(behindDoc: boolean, raw: number | undefined, fallback?: number): number;
+/**
+ * Returns z-index for an image or drawing block.
+ * Uses block.zIndex when present, otherwise derives from originalAttributes.
+ */
+export declare function getFragmentZIndex(block: ImageBlock | DrawingBlock): number;

package/dist/layout-engine/contracts/src/page-number-formatting.d.ts

@@ -0,0 +1,26 @@
+export type PageNumberFieldFormat = {
+    format?: 'decimal' | 'upperRoman' | 'lowerRoman' | 'upperLetter' | 'lowerLetter' | 'numberInDash' | 'ordinal';
+    zeroPadding?: number;
+    numericPicture?: string;
+};
+export type PageNumberFormat = NonNullable<PageNumberFieldFormat['format']>;
+export type PageNumberChapterSeparator = 'hyphen' | 'period' | 'colon' | 'emDash' | 'enDash';
+export declare function formatPageNumber(pageNumber: number, format: PageNumberFormat): string;
+export declare function formatPageNumberFieldValue(pageNumber: number, fieldFormat?: PageNumberFieldFormat): string;
+export declare function formatChapterPageNumberText(args: {
+    pageComponent: string;
+    chapterNumberText?: string;
+    chapterSeparator?: PageNumberChapterSeparator;
+}): string;
+export declare function formatSectionPageNumberText(args: {
+    displayNumber: number;
+    pageFormat: PageNumberFormat;
+    chapterNumberText?: string;
+    chapterSeparator?: PageNumberChapterSeparator;
+}): string;
+/**
+ * Formats integer page field values with a Word numeric picture subset.
+ * Unsupported ECMA features are intentionally out of scope here: backtick
+ * numbered-item references, localized separators, and fractional rounding.
+ */
+export declare function formatIntegerWithNumericPicture(value: number, picture: string): string;

package/dist/layout-engine/contracts/src/page-ref-anchor.d.ts

@@ -0,0 +1,2 @@
+import { FlowBlock, Layout, Measure, PageRefLocation } from './index.js';
+export declare function buildPageRefAnchorMap(bookmarks: Map<string, number>, layout: Layout, blocks?: FlowBlock[], measures?: Measure[]): Map<string, PageRefLocation>;

package/dist/layout-engine/contracts/src/pm-range.d.ts

@@ -0,0 +1,45 @@
+import { FlowBlock, Line, ParagraphBlock, ParagraphMeasure } from './index.js';
+/**
+ * Represents a ProseMirror position range for a line or fragment.
+ */
+export type LinePmRange = {
+    pmStart?: number;
+    pmEnd?: number;
+};
+/**
+ * Computes the ProseMirror position range covered by a single line.
+ *
+ * Iterates through the runs that comprise the line (from line.fromRun to line.toRun),
+ * extracting PM positions and handling both text runs and atomic runs (images, breaks, etc.).
+ * For text runs, accounts for partial line slices using fromChar and toChar offsets.
+ *
+ * @param block - The flow block containing the line (must be a paragraph block)
+ * @param line - The line to compute the PM range for
+ * @returns Object with pmStart and pmEnd properties, or empty object if block is not a paragraph
+ *
+ * @remarks
+ * - Returns empty object {} if block.kind !== 'paragraph'
+ * - Atomic runs are treated as single-position elements (pmEnd defaults to pmStart + 1)
+ * - For text runs, uses character offsets to compute precise PM boundaries
+ * - Handles first/last run slicing based on line.fromChar and line.toChar
+ */
+export declare function computeLinePmRange(block: FlowBlock, line: Line): LinePmRange;
+/**
+ * Computes the ProseMirror position range covered by a fragment (a range of lines).
+ *
+ * Iterates through lines from fromLine to toLine (exclusive), computing the PM range
+ * for each line and merging them into a single continuous range.
+ *
+ * @param block - The paragraph block containing the lines
+ * @param lines - Array of lines from the paragraph measure
+ * @param fromLine - Starting line index (inclusive)
+ * @param toLine - Ending line index (exclusive)
+ * @returns Object with pmStart and pmEnd properties representing the entire fragment range
+ *
+ * @remarks
+ * - The fragment spans lines [fromLine, toLine) (toLine is exclusive)
+ * - pmStart is taken from the first line with a valid pmStart
+ * - pmEnd is continuously updated to the last valid pmEnd encountered
+ * - Returns empty pmStart/pmEnd if no lines have valid PM ranges
+ */
+export declare function computeFragmentPmRange(block: ParagraphBlock, lines: ParagraphMeasure['lines'], fromLine: number, toLine: number): LinePmRange;