@eigenpal/docx-editor-core/utils

areSelectionStylesInjectedfunctionSource ↗

Check if selection styles are injected

declare function areSelectionStylesInjected(): boolean;

blendColorsfunctionSource ↗

Blend two colors together

declare function blendColors(color1: ColorValue | undefined | null, color2: ColorValue | undefined | null, ratio: number, theme: Theme | null | undefined): string;

borderToStylefunctionSource ↗

Convert a BorderSpec to CSS border properties

declare function borderToStyle(border: BorderSpec | undefined | null, side?: 'Top' | 'Bottom' | 'Left' | 'Right' | '', theme?: Theme | null): CSSProperties$1;

buildAnchorMapsfunctionSource ↗

Build lookup maps from an anchor list — by start position and by covered slot.

declare function buildAnchorMaps<T>(anchors: CellAnchor<T>[]): {
    byStart: Map<string, CellAnchor<T>>;
    byCoveredSlot: Map<string, CellAnchor<T>>;
};

canRenderFontfunctionSource ↗

Check if a font is available on the system using canvas measurement

Compares text width with the target font vs a known fallback font (and the opposite fallback, for names that collide with the browser defaults). If the widths differ, the font is available. Reuses one shared canvas; the fallback widths are session constants and memoized.

declare function canRenderFont(fontFamily: string, fallbackFont?: string): boolean;

clampfunctionSource ↗

Clamp a value between min and max

declare function clamp(value: number, min: number, max: number): number;

cleanWordHtmlfunctionSource ↗

Clean Microsoft Word HTML

declare function cleanWordHtml(html: string): string;

clearSelectionfunctionSource ↗

Clear the current selection

declare function clearSelection(): void;

collectHeadingsfunctionSource ↗

Collect all headings from a ProseMirror document.

Detection logic: 1. Check outlineLevel attr (set by OOXML parsing or style resolution) 2. Fallback to styleId matching /^[Hh]eading(d)$/

declare function collectHeadings(doc: Node): HeadingInfo[];

colorsEqualfunctionSource ↗

Check if two colors are equal

declare function colorsEqual(color1: ColorValue | undefined | null, color2: ColorValue | undefined | null, theme: Theme | null | undefined): boolean;

computeSplitDialogDefaultsfunctionSource ↗

Compute the initial dialog values for a split-cell dialog.

declare function computeSplitDialogDefaults(rowspan: number, colspan: number): {
    minRows: number;
    minCols: number;
    initialRows: number;
    initialCols: number;
};

computeSplitLayoutfunctionSource ↗

Compute the new anchor layout after splitting a target cell.

This is the core algorithm shared between ProseMirror and Document-model paths. It adjusts neighbor spans, shifts positions for inserted rows/cols, and creates placeholder anchors for the new split cells.

declare function computeSplitLayout<T>(anchors: CellAnchor<T>[], target: CellAnchor<T>, rows: number, cols: number, totalRows: number, createSplitCellData: (isOriginal: boolean, rowOffset: number, colOffset: number) => T): SplitLayoutResult<T>;

copyParagraphsfunctionSource ↗

Copy paragraphs to clipboard with formatting

declare function copyParagraphs(paragraphs: Paragraph[], options?: ClipboardOptions): Promise<boolean>;

copyRunsfunctionSource ↗

Copy runs to clipboard with formatting

declare function copyRuns(runs: Run[], options?: ClipboardOptions): Promise<boolean>;

countPageBreaksfunctionSource ↗

Count page breaks in a document

declare function countPageBreaks(doc: Document): number;

createClipboardHandlersfunctionSource ↗

Create clipboard keyboard handlers for an editor

declare function createClipboardHandlers(options: {
    onCopy?: () => {
        runs: Run[];
    } | null;
    onCut?: () => {
        runs: Run[];
    } | null;
    onPaste?: (content: ParsedClipboardContent) => void;
    clipboardOptions?: ClipboardOptions;
}): {
    handleCopy: (event: ClipboardEvent) => Promise<void>;
    handleCut: (event: ClipboardEvent) => Promise<void>;
    handlePaste: (event: ClipboardEvent) => void;
    handleKeyDown: (event: KeyboardEvent) => Promise<void>;
};

createColumnBreakfunctionSource ↗

Create a column break content element

declare function createColumnBreak(): BreakContent;

createDocumentWithTextfunctionSource ↗

Create a document with a single paragraph containing the given text

declare function createDocumentWithText(text: string, options?: Omit<CreateEmptyDocumentOptions, 'initialText'>): Document;

createDoubleClickWordSelectorfunctionSource ↗

Create a double-click handler that selects words. Returns a function that should be called on dblclick events.

declare function createDoubleClickWordSelector(): (event: MouseEvent) => void;

createEmptyDocumentfunctionSource ↗

Create an empty document with a single paragraph

declare function createEmptyDocument(options?: CreateEmptyDocumentOptions): Document;

```ts
// Create a blank document
const doc = createEmptyDocument();

// Create with custom margins
const doc = createEmptyDocument({
  marginTop: 720,  // 0.5 inch
  marginBottom: 720,
});

// Create with initial text
const doc = createEmptyDocument({
  initialText: 'Hello, World!'
});
```

createHorizontalRulefunctionSource ↗

Create a horizontal rule paragraph Uses a paragraph with bottom border to simulate horizontal rule

declare function createHorizontalRule(): Paragraph;

createLineBreakfunctionSource ↗

Create a text wrapping break (line break)

declare function createLineBreak(clear?: 'none' | 'left' | 'right' | 'all'): BreakContent;

createPageBreakfunctionSource ↗

Create a page break content element

declare function createPageBreak(): BreakContent;

createPageBreakParagraphfunctionSource ↗

Create an empty paragraph with a page break before it

declare function createPageBreakParagraph(): Paragraph;

createPageBreakRunfunctionSource ↗

Create a run containing a page break

declare function createPageBreakRun(): Run;

createRgbColorfunctionSource ↗

Create a ColorValue from RGB hex

declare function createRgbColor(hex: string): ColorValue;

createSelectionChangeHandlerfunctionSource ↗

Create a selection change handler that updates highlight rects

declare function createSelectionChangeHandler(containerElement: HTMLElement | null, onRectsChange: (rects: HighlightRect[]) => void, merge?: boolean): () => void;

createTemplateProcessorfunctionSource ↗

Create a template processor with preset options

declare function createTemplateProcessor(defaultOptions?: ProcessTemplateOptions): (buffer: ArrayBuffer, variables: Record<string, string>) => ArrayBuffer;

createThemeColorfunctionSource ↗

Create a ColorValue from theme color reference

declare function createThemeColor(themeColor: ThemeColorSlot, tint?: number, shade?: number): ColorValue;

createTripleClickParagraphSelectorfunctionSource ↗

Create a triple-click handler that selects paragraphs. This uses our custom click counting since browsers have inconsistent triple-click.

declare function createTripleClickParagraphSelector(): (event: MouseEvent) => void;

darkenColorfunctionSource ↗

Darken a color by a percentage

declare function darkenColor(color: ColorValue | undefined | null, theme: Theme | null | undefined, percent: number): string;

deobfuscateFontfunctionSource ↗

De-obfuscate an embedded .odttf font into a usable OpenType/TrueType binary by XOR-ing its first 32 bytes with the reversed w:fontKey GUID.

Returns a new buffer; the input is not mutated. Throws if fontKey is not a valid 128-bit GUID.

declare function deobfuscateFont(data: ArrayBuffer, fontKey: string): ArrayBuffer;

describeShortcutfunctionSource ↗

Get a human-readable description of a shortcut

declare function describeShortcut(shortcut: KeyboardShortcut): string;

eighthsToPixelsfunctionSource ↗

Convert eighths of a point to pixels (at 96 DPI)

Eighths of a point are used for border widths in OOXML.

declare function eighthsToPixels(eighths: number): number;

emuToPixelsfunctionSource ↗

Convert EMUs to pixels (at 96 DPI)

1 inch = 914400 EMUs = 96 pixels Returns 0 for null/undefined/NaN inputs.

declare function emuToPixels(emu: number | undefined | null): number;

emuToTwipsfunctionSource ↗

Convert EMUs to twips

declare function emuToTwips(emu: number): number;

ensureHexPrefixfunctionSource ↗

Ensure a hex color string has a '#' prefix.

declare function ensureHexPrefix(hex: string): string;

excludeFontsByNamefunctionSource ↗

Drop fonts whose names already appear in existingNames (case-insensitive), also deduping the input. Used by both adapters' pickers to render the "Document fonts" group without repeating a font the built-in list covers.

declare function excludeFontsByName(fonts: readonly FontOption[] | undefined, existingNames: Iterable<string>): FontOption[];

expandSelectionToWordfunctionSource ↗

Expand selection to word boundaries Used for double-click word selection

declare function expandSelectionToWord(): boolean;

expandSelectionToWordBoundariesfunctionSource ↗

Expand the current selection to word boundaries. If there's a collapsed selection (cursor), selects the word at cursor. If there's an existing selection, expands to include complete words.

declare function expandSelectionToWordBoundaries(): boolean;

extendSelectionTofunctionSource ↗

Extend selection to a specific position

declare function extendSelectionTo(node: Node, offset: number): void;

extractFontsFromDocumentfunctionSource ↗

Extract all font families used in a document

Uses loose typing to handle any document-like structure.

declare function extractFontsFromDocument(document: unknown): Set<string>;

findNextWordStartfunctionSource ↗

Find the next word start (for Ctrl+Right navigation)

declare function findNextWordStart(text: string, position: number): number;

findPageBreaksfunctionSource ↗

Find all page break positions in a document

declare function findPageBreaks(doc: Document): InsertPosition[];

findParagraphFragmentsByParaIdfunctionSource ↗

Find all painted paragraph fragments with a stable data-para-id.

declare function findParagraphFragmentsByParaId(root: ParentNode, paraId: string): HTMLElement[];

findPreviousWordStartfunctionSource ↗

Find the previous word start (for Ctrl+Left navigation)

declare function findPreviousWordStart(text: string, position: number): number;

findVisualLineEndfunctionSource ↗

Find the end of the current line in a text node Uses visual line detection based on bounding rectangles

declare function findVisualLineEnd(container: Node, offset: number): {
    node: Node;
    offset: number;
} | null;

findVisualLineStartfunctionSource ↗

Find the start of the current line in a text node Uses visual line detection based on bounding rectangles

declare function findVisualLineStart(container: Node, offset: number): {
    node: Node;
    offset: number;
} | null;

findWordAtfunctionSource ↗

Find the word at a position and return detailed info

declare function findWordAt(text: string, position: number): WordSelectionResult;

findWordBoundariesfunctionSource ↗

Find word boundaries around a position in text Returns [startIndex, endIndex] inclusive start, exclusive end

declare function findWordBoundaries(text: string, position: number): [number, number];

findWordEndfunctionSource ↗

Find the end of the current or next word

declare function findWordEnd(text: string, position: number): number;

findWordStartfunctionSource ↗

Find the start of the current or previous word

declare function findWordStart(text: string, position: number): number;

flashParagraphElementsfunctionSource ↗

Apply a transient flash to a collection of paragraph elements.

declare function flashParagraphElements(elements: Iterable<HTMLElement>, options?: ParagraphHighlightOptions): number;

flashParagraphFragmentsByParaIdfunctionSource ↗

Find paragraph fragments by paraId and flash them.

declare function flashParagraphFragmentsByParaId(root: ParentNode, paraId: string, options?: ParagraphHighlightOptions): boolean;

formatPxfunctionSource ↗

Format a pixel value as CSS string

declare function formatPx(px: number): string;

generateSelectionCSSfunctionSource ↗

Generate inline CSS for selection pseudo-elements

This is used to inject consistent selection styling across all editable elements.

declare function generateSelectionCSS(selector: string, config?: SelectionHighlightConfig): string;

generateThemeTintShadeMatrixfunctionSource ↗

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

declare function generateThemeTintShadeMatrix(colorScheme?: ThemeColorScheme | null): ThemeMatrixCell[][];

getClipboardImageFilesfunctionSource ↗

Extract image files from clipboard data (if present).

declare function getClipboardImageFiles(clipboardData: DataTransfer | null): File[];

getContrastingColorfunctionSource ↗

Get contrasting text color for a background

declare function getContrastingColor(backgroundColor: ColorValue | undefined | null, theme: Theme | null | undefined): string;

getEmbeddedFontFacesfunctionSource ↗

Resolve and de-obfuscate every embedded font face declared in a font table. Pure: does not touch the DOM. Faces whose relationship or binary is missing, or whose key is unusable, are skipped.

declare function getEmbeddedFontFaces(fontTable: FontTable | undefined, rawFonts: ReadonlyMap<string, ArrayBuffer>, fontTableRelsXml: string | null | undefined): EmbeddedFontFace[];

getEmbeddedFontFamiliesfunctionSource ↗

Names of the fonts a table embeds at least one face for. Used by the picker to surface embedded fonts even when the canvas probe is unreliable for a subsetted face.

declare function getEmbeddedFontFamilies(fontTable: FontTable | undefined): Set<string>;

getGoogleFontEquivalentfunctionSource ↗

Get the Google Fonts equivalent for a font name

declare function getGoogleFontEquivalent(fontName: string): string;

getHighlightRectStylefunctionSource ↗

Generate CSS styles for a highlight rectangle

declare function getHighlightRectStyle(rect: HighlightRect, config?: SelectionHighlightConfig): CSSProperties;

getLoadedFontsfunctionSource ↗

Get list of all loaded fonts

declare function getLoadedFonts(): string[];

getMergedSelectionRectsfunctionSource ↗

Get selection rectangles with merging applied

declare function getMergedSelectionRects(containerElement?: HTMLElement | null): HighlightRect[];

getMissingVariablesfunctionSource ↗

Check if all required variables have values

declare function getMissingVariables(tags: string[], variables: Record<string, string>): string[];

getNavigationShortcutDescriptionsfunctionSource ↗

Get all navigation shortcuts with descriptions

declare function getNavigationShortcutDescriptions(): Array<{
    action: string;
    shortcut: string;
}>;

getRenderableDocumentFontsfunctionSource ↗

Walk a parsed document for the fonts it references and return those the browser can render (embedded or system-resolved) as picker options.

declare function getRenderableDocumentFonts(doc: Document, options?: RenderableFontOptions): FontOption[];

getSelectedTextfunctionSource ↗

Get the selected text

declare function getSelectedText(): string;

getSelectionBoundingRectfunctionSource ↗

Get the bounding rect of the current selection

declare function getSelectionBoundingRect(): DOMRect | null;

getSelectionInfofunctionSource ↗

Get the current selection info

declare function getSelectionInfo(): {
    node: Node;
    offset: number;
    anchorNode: Node | null;
    anchorOffset: number;
    focusNode: Node | null;
    focusOffset: number;
    isCollapsed: boolean;
    text: string;
} | null;

getSelectionRectsfunctionSource ↗

Get all selection rectangles from the current DOM selection

Uses getClientRects() to get accurate rectangles even when selection spans multiple inline elements.

declare function getSelectionRects(containerElement?: HTMLElement | null): HighlightRect[];

getTemplateTagsfunctionSource ↗

Get all template tags in a document without processing

declare function getTemplateTags(buffer: ArrayBuffer): string[];

getThemeTintShadeHexfunctionSource ↗

Compute a single tinted or shaded hex color from a base color.

declare function getThemeTintShadeHex(baseHex: string, type: 'tint' | 'shade', fraction: number): string;

getWordAtfunctionSource ↗

Get the word at a position in text

declare function getWordAt(text: string, position: number): string;

getWordAtCursorfunctionSource ↗

Get the word at the current cursor position

declare function getWordAtCursor(): string | null;

halfPointsToPixelsfunctionSource ↗

Convert half-points to pixels (at 96 DPI)

Half-points are commonly used for font sizes in OOXML (w:sz).

declare function halfPointsToPixels(halfPoints: number): number;

halfPointsToPointsfunctionSource ↗

Convert half-points to points

declare function halfPointsToPoints(halfPoints: number): number;

handleClickForMultiClickfunctionSource ↗

Handle click event for multi-click detection. Call this in your click handler. Returns the click count (1 = single, 2 = double, 3 = triple).

declare function handleClickForMultiClick(event: MouseEvent): number;

handleNavigationKeyfunctionSource ↗

Handle a keyboard navigation event Returns true if the event was handled

declare function handleNavigationKey(event: KeyboardEvent, options?: {
    onDocumentStart?: () => void;
    onDocumentEnd?: () => void;
}): boolean;

handlePasteEventfunctionSource ↗

Handle paste event

declare function handlePasteEvent(event: ClipboardEvent, options?: ClipboardOptions): ParsedClipboardContent | null;

hasActiveSelectionfunctionSource ↗

Check if there is an active text selection (not collapsed)

declare function hasActiveSelection(): boolean;

hasPageBreakBeforefunctionSource ↗

Check if a paragraph has pageBreakBefore

declare function hasPageBreakBefore(paragraph: Paragraph): boolean;

highlightTextRangefunctionSource ↗

Create a selection highlight for a specific text range

This is useful for find/replace highlighting, AI action previews, etc.

declare function highlightTextRange(_containerElement: HTMLElement, startNode: Node, startOffset: number, endNode: Node, endOffset: number): Range | null;

htmlToRunsfunctionSource ↗

Convert HTML to runs

declare function htmlToRuns(html: string, plainTextFallback: string): Run[];

injectSelectionStylesfunctionSource ↗

Inject selection highlight CSS into document

declare function injectSelectionStyles(config?: SelectionHighlightConfig): void;

insertHorizontalRulefunctionSource ↗

Insert a horizontal rule at a position in the document

declare function insertHorizontalRule(doc: Document, position: InsertPosition): Document;

insertPageBreakfunctionSource ↗

Insert a page break at a position in the document This inserts a new paragraph with pageBreakBefore: true

declare function insertPageBreak(doc: Document, position: InsertPosition): Document;

isBlackfunctionSource ↗

Check if a color is effectively black

declare function isBlack(color: ColorValue | undefined | null, theme: Theme | null | undefined): boolean;

isBreakContentfunctionSource ↗

Check if content is any type of break

declare function isBreakContent(content: RunContent): content is BreakContent;

isColumnBreakfunctionSource ↗

Check if content is a column break

declare function isColumnBreak(content: RunContent): boolean;

isEditorHtmlfunctionSource ↗

Check if HTML is from our editor

declare function isEditorHtml(html: string): boolean;

isFontLoadedfunctionSource ↗

Check if a font is loaded

declare function isFontLoaded(fontFamily: string): boolean;

isGoogleFontsEnabledfunctionSource ↗

Whether the automatic Google Fonts lookup is currently enabled.

declare function isGoogleFontsEnabled(): boolean;

isLineBreakfunctionSource ↗

Check if content is a line break

declare function isLineBreak(content: RunContent): boolean;

isLoadingfunctionSource ↗

Check if any fonts are currently loading

declare function isLoading(): boolean;

isNavigationKeyfunctionSource ↗

Check if an event is a navigation key event

declare function isNavigationKey(event: KeyboardEvent): boolean;

isPageBreakfunctionSource ↗

Check if content is a page break

declare function isPageBreak(content: RunContent): boolean;

isPunctuationfunctionSource ↗

Check if a character is a punctuation character

declare function isPunctuation(char: string): boolean;

isSelectionBackwardsfunctionSource ↗

Check if selection is backwards (focus before anchor)

declare function isSelectionBackwards(): boolean;

isSelectionWithinfunctionSource ↗

Check if selection is within a specific element

declare function isSelectionWithin(element: HTMLElement): boolean;

isValidFontKeyfunctionSource ↗

Whether a string is a usable embedded-font obfuscation key (a 128-bit GUID, with or without braces/hyphens).

declare function isValidFontKey(fontKey: string | undefined | null): boolean;

isWhitefunctionSource ↗

Check if a color is effectively white

declare function isWhite(color: ColorValue | undefined | null, theme: Theme | null | undefined): boolean;

isWhitespacefunctionSource ↗

Check if a character is whitespace

declare function isWhitespace(char: string): boolean;

isWordCharacterfunctionSource ↗

Check if a character is a word character (letter, digit, or underscore)

declare function isWordCharacter(char: string): boolean;

isWordHtmlfunctionSource ↗

Check if HTML is from Microsoft Word

declare function isWordHtml(html: string): boolean;

lightenColorfunctionSource ↗

Lighten a color by a percentage

declare function lightenColor(color: ColorValue | undefined | null, theme: Theme | null | undefined, percent: number): string;

loadDocumentFontsfunctionSource ↗

Extract fonts from a document and load them from Google Fonts

declare function loadDocumentFonts(document: unknown): Promise<void>;

loadEmbeddedFontsfunctionSource ↗

Register every embedded font face with the browser via @font-face. No-op outside a DOM (headless/SSR). Resolves to the set of font family names that were registered (deduped), so callers can surface them in the font picker.

declare function loadEmbeddedFonts(fontTable: FontTable | undefined, rawFonts: ReadonlyMap<string, ArrayBuffer>, fontTableRelsXml: string | null | undefined): Promise<Set<string>>;

loadFontfunctionSource ↗

Load a font from Google Fonts

declare function loadFont(fontFamily: string, options?: {
    weights?: number[];
    styles?: ('normal' | 'italic')[];
}): Promise<boolean>;

loadFontDefinitionsfunctionSource ↗

Register a list of custom font faces. Used by the fonts prop on <DocxEditor> (React + Vue). Idempotent — safe to call on every render.

declare function loadFontDefinitions(defs: ReadonlyArray<FontDefinition> | undefined): Promise<void>;

loadFontFromBufferfunctionSource ↗

Load a font from a raw buffer (e.g., embedded in DOCX)

Call before loading the document when possible: registration marks the family as ours, which is what keeps the metric-compatible Google fallback in play for subsetted faces during the document's font resolution pass. Late registration still self-heals on the next pass. Under setGoogleFontsEnabled(false) that fallback fetch is suppressed and glyphs missing from the registered faces render via the CSS stack.

declare function loadFontFromBuffer(fontFamily: string, buffer: ArrayBuffer, options?: {
    weight?: number | string;
    style?: 'normal' | 'italic';
}): Promise<boolean>;

loadFontFromUrlfunctionSource ↗

Load a font face from a URL (woff2, woff, ttf, otf).

Injects an @font-face rule pointing at the URL. Multiple weights of the same family can be registered independently. Families registered here are treated as potentially subsetted: the editor still fetches their metric-compatible Google equivalent as a glyph-coverage fallback, unless disabled via setGoogleFontsEnabled(false).

declare function loadFontFromUrl(fontFamily: string, src: string, options?: {
    weight?: number | string;
}): Promise<boolean>;

loadFontsfunctionSource ↗

Load multiple fonts from Google Fonts

declare function loadFonts(families: string[], options?: {
    weights?: number[];
    styles?: ('normal' | 'italic')[];
}): Promise<void>;

loadFontsWithMappingfunctionSource ↗

Load multiple fonts with automatic mapping to Google Fonts equivalents

declare function loadFontsWithMapping(families: string[]): Promise<void>;

loadFontWithMappingfunctionSource ↗

Load a font, automatically mapping to Google Fonts equivalent if needed. If the font needs mapping, also creates a CSS alias so the original font name works in stylesheets.

declare function loadFontWithMapping(fontFamily: string): Promise<boolean>;

matchesShortcutfunctionSource ↗

Check if a keyboard event matches a shortcut definition

declare function matchesShortcut(event: KeyboardEvent, shortcut: KeyboardShortcut): boolean;

mergeAdjacentRectsfunctionSource ↗

Merge adjacent or overlapping rectangles

This reduces the number of highlight elements needed and creates a cleaner visual appearance.

declare function mergeAdjacentRects(rects: HighlightRect[], tolerance?: number): HighlightRect[];

mergeStylesfunctionSource ↗

Merge multiple CSSProperties objects

Later objects override earlier ones for conflicting properties.

declare function mergeStyles(...styles: (CSSProperties$1 | undefined | null)[]): CSSProperties$1;

moveByWordfunctionSource ↗

Move selection by word in a text node

declare function moveByWord(direction: 'left' | 'right', extend?: boolean): boolean;

moveToLineEdgefunctionSource ↗

Move to start/end of line

declare function moveToLineEdge(edge: 'start' | 'end', extend?: boolean): boolean;

normalizeSelectionDirectionfunctionSource ↗

Normalize selection to always be forward (start before end)

declare function normalizeSelectionDirection(): void;

onFontErrorfunctionSource ↗

Register a callback to be notified when a font fails to load.

Adapters subscribe and forward to their onError prop. Returns the unsub.

declare function onFontError(callback: (error: Error) => void): () => void;

onFontsLoadedfunctionSource ↗

Register a callback to be notified when fonts are loaded

declare function onFontsLoaded(callback: (fonts: string[]) => void): () => void;

paragraphsToClipboardContentfunctionSource ↗

Convert paragraphs to clipboard content.

declare function paragraphsToClipboardContent(paragraphs: Paragraph[], includeFormatting?: boolean, theme?: Theme | null): ClipboardContent;

paragraphToStylefunctionSource ↗

Convert ParagraphFormatting to CSS properties

declare function paragraphToStyle(formatting: ParagraphFormatting | undefined | null, theme?: Theme | null): CSSProperties$1;

parseClipboardHtmlfunctionSource ↗

Parse HTML from clipboard

declare function parseClipboardHtml(html: string, plainText: string, cleanWordFormatting?: boolean): ParsedClipboardContent;

parseColorStringfunctionSource ↗

Parse a color string (various formats) to ColorValue

declare function parseColorString(colorString: string | undefined): ColorValue | undefined;

parseNavigationActionfunctionSource ↗

Parse a keyboard event into a navigation action

declare function parseNavigationAction(event: KeyboardEvent): NavigationAction | null;

pixelsToEmufunctionSource ↗

Convert pixels to EMUs. EMU coordinates in OOXML are integer-typed (xs:long); rounding here keeps floating-point drift (e.g. 52 px → 495299.99999999994) out of the document.

declare function pixelsToEmu(px: number): number;

pixelsToTwipsfunctionSource ↗

Convert pixels to twips

declare function pixelsToTwips(px: number): number;

pointsToHalfPointsfunctionSource ↗

Convert points to half-points

declare function pointsToHalfPoints(points: number): number;

pointsToPixelsfunctionSource ↗

Convert points to pixels (at 96 DPI)

1 inch = 72 points = 96 pixels → 1 point = 96/72 pixels = 4/3 pixels

declare function pointsToPixels(points: number): number;

prefersColorSchemeDarkfunctionSource ↗

Current OS dark-mode preference. Returns false when matchMedia is unavailable (e.g. server-side render), so it is safe to call as a state seed.

declare function prefersColorSchemeDark(): boolean;

preloadCommonFontsfunctionSource ↗

Preload a list of common document fonts

This preloads fonts commonly used in DOCX documents that have Google Fonts equivalents.

declare function preloadCommonFonts(): Promise<void>;

previewTemplatefunctionSource ↗

Preview what the document will look like after processing Returns the document text with variables replaced (for preview purposes)

declare function previewTemplate(buffer: ArrayBuffer, variables: Record<string, string>): string;

processTemplatefunctionSource ↗

Process a DOCX template with variable substitution

declare function processTemplate(buffer: ArrayBuffer, variables: Record<string, string>, options?: ProcessTemplateOptions): ArrayBuffer;

processTemplateAdvancedfunctionSource ↗

Process template with conditional sections Supports #if, #unless, #each loops

declare function processTemplateAdvanced(buffer: ArrayBuffer, data: Record<string, unknown>, options?: ProcessTemplateOptions): ArrayBuffer;

processTemplateAndDownloadfunctionSource ↗

Process template and trigger download

declare function processTemplateAndDownload(buffer: ArrayBuffer, variables: Record<string, string>, filename?: string, options?: ProcessTemplateOptions): void;

processTemplateAsBlobfunctionSource ↗

Process template and return as Blob

declare function processTemplateAsBlob(buffer: ArrayBuffer, variables: Record<string, string>, options?: ProcessTemplateOptions): Blob;

processTemplateDetailedfunctionSource ↗

Process template with detailed result

declare function processTemplateDetailed(buffer: ArrayBuffer, variables: Record<string, string>, options?: ProcessTemplateOptions): ProcessTemplateResult;

readDocxFileFromInputfunctionSource ↗

Read the first selected file out of an <input type="file"> change event, return its ArrayBuffer + a stem-form name. Always resets input.value so re-selecting the same file in the same picker fires the next change event.

declare function readDocxFileFromInput(event: Event): Promise<ReadDocxFileResult | null>;

readFromClipboardfunctionSource ↗

Read content from clipboard

declare function readFromClipboard(options?: ClipboardOptions): Promise<ParsedClipboardContent | null>;

redistributeColumnWidthsfunctionSource ↗

Redistribute column widths when splitting a cell's column span.

declare function redistributeColumnWidths(existing: number[], startCol: number, currentSpan: number, targetSpan: number): number[];

removePageBreakfunctionSource ↗

Remove a page break at a specific position

declare function removePageBreak(doc: Document, position: InsertPosition): Document;

removeSelectionStylesfunctionSource ↗

Remove injected selection styles

declare function removeSelectionStyles(): void;

resolveColorfunctionSource ↗

Resolve a ColorValue to a CSS color string

declare function resolveColor(color: ColorValue | undefined | null, theme: Theme | null | undefined, defaultColor?: string): string;

resolveColorToHexfunctionSource ↗

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 (PM attrs, layout-bridge, clipboard HTML, toolbar swatches).

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.

declare function resolveColorToHex(color: ColorValue | undefined | null, theme: Theme | null | undefined): string | undefined;

resolveHighlightColorfunctionSource ↗

Resolve a highlight color name to CSS

declare function resolveHighlightColor(highlight: string | undefined): string;

resolveHighlightToCssfunctionSource ↗

Resolve a highlight color value to a CSS-ready string. Tries OOXML named highlight first, then ensures hex prefix.

declare function resolveHighlightToCss(value: string): string;

resolveIsDarkfunctionSource ↗

Resolve the effective dark flag from a [ColorMode](ColorMode) and the current OS preference. 'system' follows the OS; 'dark'/'light' are explicit.

declare function resolveIsDark(colorMode: ColorMode, systemDark: boolean): boolean;

resolveShadingColorfunctionSource ↗

Resolve a shading fill or pattern color to CSS

declare function resolveShadingColor(color: ColorValue | undefined | null, theme: Theme | null | undefined): string;

resolveShadingFillfunctionSource ↗

Convert ShadingProperties to background color

declare function resolveShadingFill(shading: ShadingProperties | undefined | null, theme?: Theme | null): string;

roundPixelsfunctionSource ↗

Round a pixel value to avoid sub-pixel rendering issues

declare function roundPixels(px: number, decimalPlaces?: number): number;

runsToClipboardContentfunctionSource ↗

Convert runs to clipboard content (HTML and plain text).

declare function runsToClipboardContent(runs: Run[], includeFormatting?: boolean, theme?: Theme | null): ClipboardContent;

sanitizeHreffunctionSource ↗

Allowlist URL schemes on hrefs that originate from untrusted input (DOCX relationship targets, pasted HTML). Fragments and relative paths pass through; anything with a scheme outside the allowlist is dropped.

declare function sanitizeHref(href: string | null | undefined): string | undefined;

sectionToStylefunctionSource ↗

Get CSS for page/section container

declare function sectionToStyle(sectionProps: {
    pageWidth?: number;
    pageHeight?: number;
    marginTop?: number;
    marginBottom?: number;
    marginLeft?: number;
    marginRight?: number;
    background?: {
        color?: {
            rgb?: string;
            themeColor?: string;
        };
    };
} | undefined | null, theme?: Theme | null): CSSProperties$1;

selectParagraphAtCursorfunctionSource ↗

Select the entire paragraph containing the current selection. Looks for the nearest element with [data-paragraph-index] attribute.

declare function selectParagraphAtCursor(): boolean;

selectRangefunctionSource ↗

Select a text range programmatically

declare function selectRange(range: Range): void;

selectRenderableFontsfunctionSource ↗

Filter a list of referenced font names down to renderable [FontOption](FontOption)s. Pure and DOM-free when canRender is injected.

declare function selectRenderableFonts(names: readonly string[], options?: RenderableFontOptions): FontOption[];

selectWordAtCursorfunctionSource ↗

Select a word at the current cursor position using the browser's native APIs. This works reliably across different browsers and handles contentEditable well.

declare function selectWordAtCursor(): boolean;

selectWordInTextNodefunctionSource ↗

Select a word in a specific text node at the given offset

declare function selectWordInTextNode(textNode: Text, offset: number): boolean;

setGoogleFontsEnabledfunctionSource ↗

Enable or disable the editor's automatic Google Fonts lookup.

Defaults to enabled. Set to false in no-egress embedders (strict CSP, offline) so loadFont / loadFontWithMapping never inject a fonts.googleapis.com stylesheet <link>. This gates ONLY the implicit Google Fonts lookup — font URLs you register yourself (the fonts prop / loadFontFromUrl) are still fetched by the browser, and embedded blobs (loadFontFromBuffer) and system fonts still resolve.

The flag is page-global (module-level), not per-editor: with multiple editors on one page the last caller wins. Call it before loading documents; disabling does not cancel fetches already in flight. A document font that is neither local nor registered then resolves loadFont to false silently (no onFontError) and renders via its CSS fallback stack.

declare function setGoogleFontsEnabled(enabled: boolean): void;

setSelectionPositionfunctionSource ↗

Set the selection to a specific position

declare function setSelectionPosition(node: Node, offset: number): void;

subscribeSystemDarkfunctionSource ↗

Subscribe to OS dark-mode changes. Invokes onChange immediately with the current value (so a stale seed is corrected on entry), then on every change. Returns an unsubscribe function. A no-op under SSR.

declare function subscribeSystemDark(onChange: (dark: boolean) => void): () => void;

sumColumnWidthsfunctionSource ↗

declare function sumColumnWidths(widths: number[], start: number, span: number): number;

tableCellToStylefunctionSource ↗

Get CSS for a table cell based on formatting

declare function tableCellToStyle(formatting: {
    verticalAlign?: 'top' | 'center' | 'bottom';
    textDirection?: string;
    shading?: ShadingProperties;
    borders?: {
        top?: BorderSpec;
        bottom?: BorderSpec;
        left?: BorderSpec;
        right?: BorderSpec;
    };
    margins?: {
        top?: {
            value: number;
            type: string;
        };
        bottom?: {
            value: number;
            type: string;
        };
        left?: {
            value: number;
            type: string;
        };
        right?: {
            value: number;
            type: string;
        };
    };
} | undefined | null, theme?: Theme | null): CSSProperties$1;

textToStylefunctionSource ↗

Convert TextFormatting to CSS properties for a run/span

declare function textToStyle(formatting: TextFormatting | undefined | null, theme?: Theme | null): CSSProperties$1;

toArrayBufferfunctionSource ↗

Normalize any [DocxInput](DocxInput) into an ArrayBuffer for internal use.

declare function toArrayBuffer(input: DocxInput): Promise<ArrayBuffer>;

twipsToEmufunctionSource ↗

Convert twips to EMUs

declare function twipsToEmu(twips: number): number;

twipsToPixelsfunctionSource ↗

Convert twips to pixels (at 96 DPI)

1 inch = 1440 twips = 96 pixels → 1 twip = 96/1440 pixels = 1/15 pixels

declare function twipsToPixels(twips: number): number;

validateTemplatefunctionSource ↗

Validate that a document is a valid docxtemplater template

declare function validateTemplate(buffer: ArrayBuffer): {
    valid: boolean;
    errors: TemplateError[];
    tags: string[];
};

writeToClipboardfunctionSource ↗

Write content to clipboard

declare function writeToClipboard(content: ClipboardContent): Promise<boolean>;

CellAnchorinterfaceSource ↗

A cell's position and span within the logical grid.

interface CellAnchor<T>

ClipboardContentinterfaceSource ↗

Clipboard content format

interface ClipboardContent

ClipboardOptionsinterfaceSource ↗

Options for clipboard operations

interface ClipboardOptions

CreateEmptyDocumentOptionsinterfaceSource ↗

Options for creating an empty document

interface CreateEmptyDocumentOptions

EmbeddedFontFaceinterfaceSource ↗

A single de-obfuscated embedded font face, ready for loadFontFromBuffer.

interface EmbeddedFontFace

FontDefinitioninterfaceSource ↗

Declarative description of a single font face to register with the editor.

Each entry injects one @font-face rule pointing at a URL. Multiple entries can share family to register distinct weights as separate faces.

For Google Fonts, call loadFont(family) directly — the fonts prop is for fonts the consumer hosts themselves. For raw bytes already in memory (DOCX-embedded fonts, user uploads), call loadFontFromBuffer(family, buf).

interface FontDefinition

HeadingInfointerfaceSource ↗

Information about a heading found in the document.

interface HeadingInfo

HighlightRectinterfaceSource ↗

Highlight rectangle representing a selected region

interface HighlightRect

InsertPosition_2interface

Insert position in the document

interface InsertPosition

KeyboardShortcutinterfaceSource ↗

Keyboard shortcut definition

interface KeyboardShortcut

NavigationActioninterfaceSource ↗

Keyboard navigation action

interface NavigationAction

ParagraphHighlightOptionsinterfaceSource ↗

Customization for the transient paragraph flash applied by scrollToParaId(paraId, { highlight }).

interface ParagraphHighlightOptions

ParsedClipboardContentinterfaceSource ↗

Parsed clipboard content

interface ParsedClipboardContent

ProcessTemplateOptionsinterfaceSource ↗

Options for template processing

interface ProcessTemplateOptions

ProcessTemplateResultinterfaceSource ↗

Result of template processing

interface ProcessTemplateResult

ReadDocxFileResultinterfaceSource ↗

Shared file-input → docx-buffer reader.

React (DocxEditor.tsx handleDocxFileChange) and Vue (DocxEditor.vue handleDocxFileChange) had byte-equivalent await file.arrayBuffer() + name.replace(/\.docx$/i, '') boilerplate around their hidden file inputs. This helper folds the common steps into one place so the two adapters can never drift on filename normalization or on the "reset input.value so re-picking the same file fires change again" detail.

Returns null when the user cancelled the picker (no file chosen).

interface ReadDocxFileResult

RenderableFontOptionsinterfaceSource ↗

Discover the fonts a document actually references and that the browser can render, so they can be offered in the font picker under a "Document fonts" group. A font qualifies when it is embedded in the file (already loaded via [loadEmbeddedFonts](loadEmbeddedFonts)) or when the host system can render it ([canRenderFont](canRenderFont)). Fonts that would only fall back to a substitute are left out, so the selector never lists a face it cannot actually show.

interface RenderableFontOptions

ScrollToParaIdOptionsinterfaceSource ↗

Optional reveal behavior for scrollToParaId.

interface ScrollToParaIdOptions

SelectionHighlightConfiginterfaceSource ↗

Selection highlight configuration

interface SelectionHighlightConfig

SelectionRangeinterfaceSource ↗

Selection range in document coordinates

interface SelectionRange

SplitLayoutResultinterfaceSource ↗

Result of computeSplitLayout.

interface SplitLayoutResult<T>

SplitTargetinterfaceSource ↗

Parameters describing the split target.

interface SplitTarget

TemplateErrorinterfaceSource ↗

Error details from template processing

interface TemplateError

ThemeMatrixCellinterfaceSource ↗

Theme color matrix cell

interface ThemeMatrixCell

WordSelectionResultinterfaceSource ↗

Word selection result

interface WordSelectionResult

ColorModetypeSource ↗

UI color theme for the editor chrome and canvas.

type ColorMode = 'light' | 'dark' | 'system';

DocxInputtypeSource ↗

Any binary representation of a DOCX file that the editor can consume.

- ArrayBuffer — from FileReader.readAsArrayBuffer() or fetch().arrayBuffer() - Uint8Array — from Node.js fs.readFile() or streaming APIs - Blob — from drag-and-drop or <input type="file"> - File — subclass of Blob, from <input type="file">

type DocxInput = ArrayBuffer | Uint8Array | Blob | File;

NavigationDirectiontypeSource ↗

Navigation direction

type NavigationDirection = 'left' | 'right' | 'up' | 'down';

NavigationUnittypeSource ↗

Navigation unit

type NavigationUnit = 'character' | 'word' | 'line' | 'paragraph' | 'document';

CLIPBOARD_TYPESconstSource ↗

Standard clipboard MIME types

CLIPBOARD_TYPES: {
    readonly HTML: "text/html";
    readonly PLAIN: "text/plain";
}

DEFAULT_PARAGRAPH_FLASH_COLORconstSource ↗

Default color used by paragraph flashes.

DEFAULT_PARAGRAPH_FLASH_COLOR = "rgba(255, 235, 59, 0.55)"

DEFAULT_PARAGRAPH_FLASH_DURATION_MSconstSource ↗

Default duration for paragraph flashes.

DEFAULT_PARAGRAPH_FLASH_DURATION_MS = 1200

DEFAULT_SELECTION_STYLEconstSource ↗

Default selection highlight style (matches Word/Google Docs)

DEFAULT_SELECTION_STYLE: SelectionHighlightConfig

FONT_MAPPINGconstSource ↗

Mapping from common Office/system fonts to Google Fonts equivalents

Google Fonts doesn't have exact matches for many Microsoft fonts, but these are close alternatives that work well for document rendering.

FONT_MAPPING: Record<string, string>

HIGH_CONTRAST_SELECTION_STYLEconstSource ↗

High contrast selection style

HIGH_CONTRAST_SELECTION_STYLE: SelectionHighlightConfig

INTERNAL_CLIPBOARD_TYPEconstSource ↗

Custom MIME type for internal clipboard format

INTERNAL_CLIPBOARD_TYPE = "application/x-docx-editor"

MIN_CARD_GAPconstSource ↗

MIN_CARD_GAP = 8

NAVIGATION_SHORTCUTSconstSource ↗

Common navigation shortcuts

NAVIGATION_SHORTCUTS: {
    readonly wordLeft: KeyboardShortcut;
    readonly wordRight: KeyboardShortcut;
    readonly selectWordLeft: KeyboardShortcut;
    readonly selectWordRight: KeyboardShortcut;
    readonly lineStart: KeyboardShortcut;
    readonly lineEnd: KeyboardShortcut;
    readonly selectToLineStart: KeyboardShortcut;
    readonly selectToLineEnd: KeyboardShortcut;
    readonly documentStart: KeyboardShortcut;
    readonly documentEnd: KeyboardShortcut;
    readonly selectToDocumentStart: KeyboardShortcut;
    readonly selectToDocumentEnd: KeyboardShortcut;
}

PARAGRAPH_FLASH_CLASS_NAMEconstSource ↗

CSS class applied to paragraph fragments during a transient flash.

PARAGRAPH_FLASH_CLASS_NAME = "docx-paragraph-flash"

PIXELS_PER_INCHconstSource ↗

Pixels per inch at standard DPI

PIXELS_PER_INCH = 96

SELECTION_CSS_VARSconstSource ↗

Selection highlight CSS custom properties

SELECTION_CSS_VARS: {
    readonly backgroundColor: "--docx-selection-bg";
    readonly borderColor: "--docx-selection-border";
    readonly textColor: "--docx-selection-text";
}

SIDEBAR_DOCUMENT_SHIFTconstSource ↗

SIDEBAR_DOCUMENT_SHIFT: number

SIDEBAR_PAGE_GAPconstSource ↗

SIDEBAR_PAGE_GAP = 12

SIDEBAR_WIDTHconstSource ↗

Sidebar geometry constants — shared by both adapters so the page-shift and card-gap math stays consistent.

SIDEBAR_WIDTH = 340

TWIPS_PER_INCHconstSource ↗

Twips per inch (1 inch = 1440 twips)

TWIPS_PER_INCH = 1440