superdoc 2.2.1 → 2.4.0-next.1

package/dist/layout-engine/style-engine/src/index.d.ts

@@ -0,0 +1,121 @@
+import { TabStop, FieldAnnotationMetadata, StructuredContentMetadata, DocumentSectionMetadata, DocPartMetadata, SdtMetadata } from '../../contracts/src/index.js';
+/**
+ * @superdoc/style-engine
+ *
+ * Resolves OOXML styles to normalized ComputedStyle objects that engines can consume.
+ * This module owns the cascade rules (defaults -> styles -> numbering -> direct formatting).
+ *
+ * Tab Stops:
+ * - Passes through OOXML TabStop values unchanged (positions in twips, val: start/end/etc.)
+ * - No unit conversion happens here - preserves exact OOXML values for round-trip fidelity
+ * - Conversion to pixels happens at measurement boundary only
+ */
+export { combineProperties, combineRunProperties, combineIndentProperties, type PropertyObject } from './cascade.js';
+export type { FieldAnnotationMetadata, StructuredContentMetadata, DocumentSectionMetadata, DocPartMetadata, SdtMetadata, };
+export type SdtNodeType = 'fieldAnnotation' | 'structuredContent' | 'structuredContentBlock' | 'documentSection' | 'docPartObject';
+export interface ResolveSdtMetadataInput {
+    nodeType?: SdtNodeType | string | null;
+    attrs?: Record<string, unknown> | null;
+    /**
+     * Optional cache key for reusing normalized metadata between identical SDT nodes.
+     * When omitted, the helper derives a key from attrs.hash/id when available.
+     */
+    cacheKey?: string | null;
+}
+export interface ResolveStyleOptions {
+    sdt?: ResolveSdtMetadataInput | null;
+}
+export interface BorderStyle {
+    style?: 'none' | 'solid' | 'dashed' | 'dotted' | 'double';
+    width?: number;
+    color?: string;
+}
+export interface ComputedParagraphStyle {
+    alignment?: 'left' | 'center' | 'right' | 'justify';
+    spacing?: {
+        before?: number;
+        after?: number;
+        line?: number;
+        lineRule?: 'auto' | 'exact' | 'atLeast';
+    };
+    indent?: {
+        left?: number;
+        right?: number;
+        firstLine?: number;
+        hanging?: number;
+    };
+    borders?: {
+        top?: BorderStyle;
+        right?: BorderStyle;
+        bottom?: BorderStyle;
+        left?: BorderStyle;
+    };
+    shading?: {
+        fill?: string;
+        pattern?: string;
+    };
+    tabs?: TabStop[];
+}
+export interface StyleContext {
+    styles?: Record<string, unknown>;
+    numbering?: Record<string, unknown>;
+    theme?: Record<string, unknown>;
+    defaults?: {
+        paragraphFont?: string;
+        fontSize?: number;
+        paragraphFontFallback?: string;
+        paragraphFontFamily?: string;
+        decimalSeparator?: string;
+        defaultTabIntervalTwips?: number;
+    };
+}
+/**
+ * Clears the internal SDT metadata cache.
+ *
+ * This is primarily useful for testing to ensure a clean state between test runs.
+ * In production, the cache persists for the lifetime of the module to maximize performance.
+ *
+ * @example
+ * ```typescript
+ * import { clearSdtMetadataCache } from './index.js';
+ *
+ * // Before each test
+ * beforeEach(() => {
+ *   clearSdtMetadataCache();
+ * });
+ * ```
+ */
+export declare function clearSdtMetadataCache(): void;
+/**
+ * Normalizes Structured Document Tag (SDT) metadata into a stable contract shape.
+ *
+ * Supports the following SDT node types:
+ * - `fieldAnnotation`: Inline field annotations with display labels, colors, and visibility
+ * - `structuredContent` / `structuredContentBlock`: Inline or block-level structured content containers
+ * - `documentSection`: Document section metadata with locks and descriptions
+ * - `docPartObject`: Document part objects (e.g., TOC, bibliography)
+ *
+ * Results are cached by hash/id to avoid recomputing metadata for identical SDT instances.
+ *
+ * @param input - SDT node information including nodeType, attrs, and optional cacheKey
+ * @returns Normalized SdtMetadata or undefined if nodeType is unsupported/missing
+ *
+ * @example
+ * ```typescript
+ * import { resolveSdtMetadata } from './index.js';
+ *
+ * const metadata = resolveSdtMetadata({
+ *   nodeType: 'fieldAnnotation',
+ *   attrs: {
+ *     fieldId: 'CLIENT_NAME',
+ *     displayLabel: 'Client Name',
+ *     fieldColor: '#980043',
+ *     visibility: 'visible'
+ *   }
+ * });
+ *
+ * console.log(metadata?.type); // 'fieldAnnotation'
+ * console.log(metadata?.fieldColor); // '#980043'
+ * ```
+ */
+export declare function resolveSdtMetadata(input?: ResolveSdtMetadataInput | null): SdtMetadata | undefined;

package/dist/layout-engine/style-engine/src/normalize/colors.d.ts

@@ -0,0 +1,13 @@
+import { WordThemeColorPalette } from '../ooxml/word-style-model/parse-theme.js';
+export declare function normalizeHexColor(value: string | undefined | null): string | undefined;
+export declare function resolveThemeColor(themeColor: string | undefined, palette: WordThemeColorPalette | undefined): string | undefined;
+/**
+ * Apply OOXML theme tint / shade to a base hex color.
+ *
+ * Both attributes are encoded as a hex byte (00..FF). tint blends the color
+ * toward white; shade blends it toward black. This is an approximation of
+ * the HSL-based Word behavior good enough for first-paint visual parity
+ * and proven elsewhere in the v1 pipeline. The painter / pm-adapter parity
+ * gate will harden corner cases if needed.
+ */
+export declare function applyThemeTintShade(hexInput: string, themeTint?: string, themeShade?: string): string;

package/dist/layout-engine/style-engine/src/normalize/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Editor-neutral normalize layer.
+ *
+ * Maps the typed style-engine `ParagraphProperties` / `RunProperties` into
+ * the visual subset of `@superdoc/contracts` `ParagraphAttrs` / `TextRun`
+ * that the v2 review-layout adapter can safely emit without depending on
+ * ProseMirror or v1 editor runtime.
+ */
+export { normalizeParagraphAttrsFromOoxml } from './paragraph-attrs.js';
+export { normalizeRunAttrsFromOoxml, type NormalizeRunAttrsContext } from './run-attrs.js';
+export type { TextRunStyleAttrs, ParagraphAttrs } from './types.js';
+export { applyThemeTintShade, normalizeHexColor, resolveThemeColor } from './colors.js';
+export { PX_PER_EIGHTH_POINT, PX_PER_POINT, PX_PER_TWIP, eighthPointsToPx, halfPointsToPx, twipsToPx, } from './units.js';

package/dist/layout-engine/style-engine/src/normalize/paragraph-attrs.d.ts

@@ -0,0 +1,3 @@
+import { ParagraphProperties } from '../ooxml/types.js';
+import { ParagraphAttrs } from '../../../contracts/src/index.js';
+export declare function normalizeParagraphAttrsFromOoxml(props: ParagraphProperties | null | undefined): Partial<ParagraphAttrs>;

package/dist/layout-engine/style-engine/src/normalize/run-attrs.d.ts

@@ -0,0 +1,17 @@
+import { RunProperties } from '../ooxml/types.js';
+import { WordThemeColorPalette, WordThemeFontScheme } from '../ooxml/word-style-model/parse-theme.js';
+import { TextRunStyleAttrs } from './types.js';
+export interface NormalizeRunAttrsContext {
+    /** Compiled theme color palette from the Word style model. */
+    themeColors?: WordThemeColorPalette;
+    /** Compiled theme font scheme. */
+    themeFontScheme?: WordThemeFontScheme;
+    /**
+     * Resolved background color in which the run will render (e.g. shaded cell
+     * background). When set and the run color resolves to `auto`, the
+     * normalizer picks a contrasting color so dark-on-dark text does not
+     * silently render unreadable inside shaded cells.
+     */
+    backgroundColor?: string;
+}
+export declare function normalizeRunAttrsFromOoxml(props: RunProperties | null | undefined, context?: NormalizeRunAttrsContext): TextRunStyleAttrs;

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

@@ -0,0 +1,36 @@
+import { ParagraphAttrs, TextRun } from '../../../contracts/src/index.js';
+/**
+ * Visual text-run style attributes the adapter is allowed to emit safely.
+ * This is the **partial** typed shape — every field is optional because
+ * the resolver may only know a subset and must not invent defaults.
+ *
+ * Caller responsibility:
+ * - `fontFamily` / `fontSize` are visual defaults; only emit when resolved.
+ * - Run text is always built with a non-empty `fontFamily` and a positive
+ *   `fontSize` at the projection layer; partial attrs only override.
+ */
+export interface TextRunStyleAttrs {
+    fontFamily?: string;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: NonNullable<TextRun['underline']>;
+    strike?: boolean;
+    doubleStrike?: boolean;
+    color?: string;
+    highlight?: string;
+    textTransform?: TextRun['textTransform'];
+    allCaps?: boolean;
+    smallCaps?: boolean;
+    vertAlign?: TextRun['vertAlign'];
+    baselineShift?: number;
+    letterSpacing?: number;
+    horizontalScale?: number;
+    script?: TextRun['script'];
+    vanish?: boolean;
+    specVanish?: boolean;
+    noProof?: boolean;
+    bidi?: NonNullable<TextRun['bidi']>;
+}
+/** Re-export so v2 adapter can consume one paragraph attrs type. */
+export type { ParagraphAttrs };

package/dist/layout-engine/style-engine/src/normalize/units.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Unit helpers used by the editor-neutral normalize layer.
+ *
+ * Kept tiny and pure so v2 rendering can map twips/half-points/eighth-points
+ * into the layout-engine pixel domain without depending on pm-adapter or v1
+ * editor runtime.
+ */
+export declare const PX_PER_TWIP: number;
+export declare const PX_PER_POINT: number;
+export declare const PX_PER_EIGHTH_POINT: number;
+export declare function twipsToPx(value: number): number;
+export declare function halfPointsToPx(value: number): number;
+export declare function eighthPointsToPx(value: number): number;

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

@@ -0,0 +1,64 @@
+import { combineIndentProperties, combineProperties, combineRunProperties, FONT_SLOT_THEME_PAIRS, PropertyObject } from '../cascade.js';
+import { ParagraphConditionalFormatting, ParagraphProperties, RunProperties } from './types.js';
+import { NumberingProperties } from './numbering-types.js';
+import { StylesDocumentProperties, TableProperties, TableLookProperties, TableCellProperties } from './styles-types.js';
+export { combineIndentProperties, combineProperties, combineRunProperties, FONT_SLOT_THEME_PAIRS };
+export type { PropertyObject };
+export type * from './types.js';
+export type * from './numbering-types.js';
+export type * from './styles-types.js';
+export { TABLE_STYLE_ID_TABLE_GRID, TABLE_STYLE_ID_TABLE_NORMAL, TABLE_FALLBACK_BORDER, TABLE_FALLBACK_BORDERS, TABLE_FALLBACK_CELL_PADDING, isKnownTableStyleId, findTypeDefaultTableStyleId, resolveExistingTableEffectiveStyleId, resolvePreferredNewTableStyleId, } from './table-style-selection.js';
+export type { ResolvedStyle, ResolvedStyleSource, TableSemanticStyleHints } from './table-style-selection.js';
+export interface OoxmlResolverParams {
+    translatedNumbering: NumberingProperties | null | undefined;
+    translatedLinkedStyles: StylesDocumentProperties | null | undefined;
+    /** Actual `w:type="paragraph" w:default="1"` style ID. */
+    defaultParagraphStyleId?: string;
+    /** Bounded read-only aliases for legacy dangling semantic references. */
+    styleIdAliases?: Readonly<Record<string, string>>;
+    /**
+     * Opt-in memoization of `resolveStyleChain` results, keyed per params
+     * object. Only set this when `translatedLinkedStyles` is immutable for the
+     * lifetime of this params object (the compiled WordStyleModel guarantees
+     * that; callers that rebuild styles in place must not opt in).
+     */
+    enableChainMemo?: boolean;
+}
+export interface TableInfo {
+    tableProperties: TableProperties | null | undefined;
+    directTableProperties?: TableProperties | null | undefined;
+    rowIndex: number;
+    cellIndex: number;
+    numCells: number;
+    numRows: number;
+    rowCnfStyle?: ParagraphConditionalFormatting | null;
+    cellCnfStyle?: ParagraphConditionalFormatting | null;
+}
+/**
+ * OOXML default tblLook value (0x04A0) per ECMA-376 §17.4.56.
+ * Word applies these flags when a table has no explicit w:tblLook element.
+ */
+export declare const DEFAULT_TBL_LOOK: TableLookProperties;
+export declare function resolveRunProperties(params: OoxmlResolverParams, inlineRpr: RunProperties | null | undefined, resolvedPpr: ParagraphProperties | null | undefined, tableInfo?: TableInfo | null | undefined, isListNumber?: boolean, numberingDefinedInline?: boolean): RunProperties;
+export declare function resolveParagraphProperties(params: OoxmlResolverParams, inlineProps: ParagraphProperties | null | undefined, tableInfo: TableInfo | null | undefined): ParagraphProperties;
+export declare function resolveStyleChain<T extends PropertyObject>(propertyType: 'paragraphProperties' | 'runProperties' | 'tableProperties', params: OoxmlResolverParams, styleId: string | undefined, followBasedOnChain?: boolean): T;
+export declare function getNumberingProperties<T extends ParagraphProperties | RunProperties>(propertyType: 'paragraphProperties' | 'runProperties', params: OoxmlResolverParams, ilvl: number, numId: number, tries?: number): T;
+/**
+ * Resolves table-level properties (borders, cellMargins, justification,
+ * tableWidth, tableCellSpacing) by walking the full basedOn chain.
+ *
+ * Returns raw OOXML-translated shapes exactly as stored in
+ * `translatedLinkedStyles`. Conversion to layout units (px, pt)
+ * remains in the pm-adapter hydrator.
+ */
+export declare function resolveTableProperties(tableStyleId: string | null | undefined, translatedLinkedStyles: StylesDocumentProperties | null | undefined): TableProperties;
+export declare function resolveDocxFontFamily(attributes: Record<string, unknown> | null | undefined, docx: Record<string, unknown> | null | undefined, toCssFontFamily?: (fontName: string, docx?: Record<string, unknown>) => string): string | null;
+export declare function resolveCellStyles<T extends PropertyObject>(propertyType: 'paragraphProperties' | 'runProperties' | 'tableCellProperties', tableInfo: TableInfo | null | undefined, translatedLinkedStyles: StylesDocumentProperties): T[];
+/**
+ * Resolve table cell properties (shading, borders, margins) by cascading
+ * conditional table style properties with inline cell properties.
+ *
+ * Cascade order (low → high priority):
+ *   wholeTable → bands → firstRow/lastRow/firstCol/lastCol → corner cells → inline
+ */
+export declare function resolveTableCellProperties(inlineProps: TableCellProperties | null | undefined, tableInfo: TableInfo | null | undefined, translatedLinkedStyles: StylesDocumentProperties | null | undefined): TableCellProperties;

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;
+}