`@stesura/docx`

DOCX import and export, framework-free. The toolbar buttons are in @stesura/docx-react; behaviour and round-trip limits are in the DOCX guide.

Import

`importDocx`

Parameters:

Name	Type	Default
`file`	`File \| ArrayBuffer`
`schema`	`Schema<any, any>`
`options`	`DocxImportOptions`

Returns:

Promise<DocxImportResult>

`DocxImportOptions`

Name	Type	Default
`uploadImage`	`(buffer: ArrayBuffer, contentType: string, filename: string) => Promise<string \| undefined>` Uploads an embedded image and returns its URL. When provided, every supported image is uploaded in parallel and the doc’s `src`s point at the returned URLs, keeping base64 out of the doc (it bloats the collab payload). `filename` is the media entry name (e.g. “image1.png”).
`inlineImageFallback`	`boolean` Whether an image may fall back to a base64 data URL when there is no `uploadImage` or its upload fails. Default true. Collab mounts pass false; such images then keep their placeholder src and raise a `missing_image` warning.

`DocxImportResult`

Name	Type	Default
`doc`	`Node`
`numbering`	`NumberingConfig[]`
`warnings`	`ImportWarning[]` Anything that could not be imported faithfully.
`images`	`ImportedImage[]`
`comments`	`ImportedThread[]` Comment threads. The doc’s `comment_open`/`comment_close` anchors carry each thread’s import-minted `id`: the caller creates the threads in its comments store and rewrites the anchors’ `threadId` to the store’s ids before mounting — or strips the anchors when there is no store.

`DocxImportError`

Thrown by importDocx when the file isn’t a readable DOCX: wrong format, corrupt archive, or over the size limits (50 MB, 200 MB decompressed, 5,000 entries). Its message is written for end users.

`ImportWarning`

Name	Type	Default
`type`	`ImportWarningType`
`message`	`string`
`element`	`string`
`position`	`number`

`ImportWarningType`

Name	Type	Default
`toString`	`() => string`
`charAt`	`(pos: number) => string`
`charCodeAt`	`(index: number) => number`
`concat`	`(...strings: string[]) => string`
`indexOf`	`(searchString: string, position?: number \| undefined) => number`
`lastIndexOf`	`(searchString: string, position?: number \| undefined) => number`
`localeCompare`	`{ (that: string): number; (that: string, locales?: string \| string[] \| undefined, options?: CollatorOptions \| undefined): number; (that: string, locales?: LocalesArgument, options?: CollatorOptions \| undefined): number; }`
`match`	`{ (regexp: string \| RegExp): RegExpMatchArray \| null; (matcher: { [Symbol.match](string: string): RegExpMatchArray \| null; }): RegExpMatchArray \| null; }`
`replace`	`{ (searchValue: string \| RegExp, replaceValue: string): string; (searchValue: string \| RegExp, replacer: (substring: string, ...args: any[]) => string): string; (searchValue: { ...; }, replaceValue: string): string; (searchValue: { ...; }, replacer: (substring: string, ...args: any[]) => string): string; }`
`search`	`{ (regexp: string \| RegExp): number; (searcher: { [Symbol.search](string: string): number; }): number; }`
`slice`	`(start?: number \| undefined, end?: number \| undefined) => string`
`split`	`{ (separator: string \| RegExp, limit?: number \| undefined): string[]; (splitter: { [Symbol.split](string: string, limit?: number \| undefined): string[]; }, limit?: number \| undefined): string[]; }`
`substring`	`(start: number, end?: number \| undefined) => string`
`toLowerCase`	`() => string`
`toLocaleLowerCase`	`{ (locales?: string \| string[] \| undefined): string; (locales?: LocalesArgument): string; }`
`toUpperCase`	`() => string`
`toLocaleUpperCase`	`{ (locales?: string \| string[] \| undefined): string; (locales?: LocalesArgument): string; }`
`trim`	`() => string`
`length`	`number`
`substr`	`(from: number, length?: number \| undefined) => string`
`valueOf`	`() => string`
`codePointAt`	`(pos: number) => number \| undefined`
`includes`	`(searchString: string, position?: number \| undefined) => boolean`
`endsWith`	`(searchString: string, endPosition?: number \| undefined) => boolean`
`normalize`	`{ (form: "NFC" \| "NFD" \| "NFKC" \| "NFKD"): string; (form?: string \| undefined): string; }`
`repeat`	`(count: number) => string`
`startsWith`	`(searchString: string, position?: number \| undefined) => boolean`
`anchor`	`(name: string) => string`
`big`	`() => string`
`blink`	`() => string`
`bold`	`() => string`
`fixed`	`() => string`
`fontcolor`	`(color: string) => string`
`fontsize`	`{ (size: number): string; (size: string): string; }`
`italics`	`() => string`
`link`	`(url: string) => string`
`small`	`() => string`
`strike`	`() => string`
`sub`	`() => string`
`sup`	`() => string`
`padStart`	`(maxLength: number, fillString?: string \| undefined) => string`
`padEnd`	`(maxLength: number, fillString?: string \| undefined) => string`
`trimEnd`	`() => string`
`trimStart`	`() => string`
`trimLeft`	`() => string`
`trimRight`	`() => string`
`matchAll`	`(regexp: RegExp) => RegExpStringIterator<RegExpExecArray>`
`replaceAll`	`{ (searchValue: string \| RegExp, replaceValue: string): string; (searchValue: string \| RegExp, replacer: (substring: string, ...args: any[]) => string): string; }`
`at`	`(index: number) => string \| undefined`
`__@iterator@36`	`() => StringIterator<string>`

`ImportedThread`

A comment thread from the file. The doc’s comment anchors carry its id; create the thread in your comments store and remap the anchors before mounting (see Loading the result into an editor).

Name	Type	Default
`id`	`string` The id the document’s comment anchors carry — replace it with the store’s. The root comment’s durable id when the file has one, so the same thread gets the same id on every import.
`resolved`	`boolean`
`comments`	`ImportedComment[]`

`ImportedComment`

Name	Type	Default
`id`	`string` The comment’s `w:id` in the file.
`durableId`	`string \| null` `w16cid:durableId` from commentsIds.xml: Word keeps it across saves, where `w:id` is renumbered — what identifies the same comment in a later import. Null when the file has no commentsIds part.
`author`	`string \| null`
`initials`	`string \| null`
`date`	`string \| null` ISO date, or null when the file states none.
`body`	`JSONContent` The body as comment-schema JSON (`doc` of paragraphs, shared marks, links as `href`).

`ImportedImage`

Name	Type	Default
`originalId`	`string` The drawing’s `r:embed` relationship id.
`filename`	`string` Media entry name, e.g. “image1.png”.
`buffer`	`ArrayBuffer`
`contentType`	`string` Guessed from the extension; replaced by the type sniffed from the bytes before upload.
`placeholderSrc`	`string` The src image nodes carry until `importDocx` rewrites it to the resolved one.
`src`	`string` Uploaded URL or data URL; stays `placeholderSrc` when unresolved.

`NumberingConfig`

NumberingLevel.pStyle carries Word’s level→style back-link for style-linked numbering.

Name	Type	Default
`ref`	`string` The editor `listRef`: the resolved `abstractNumId` (Word runs one counter per abstractNum), or `${abstractNumId}.${numId}` for a `w:num` that redefines the abstract.
`abstractNumId`	`string`
`levels`	`NumberingLevel[]`

`NumberingLevel`

Name	Type	Default
`level`	`number` `w:ilvl`, 0-based.
`format`	`"decimal" \| "upperRoman" \| "lowerRoman" \| "upperLetter" \| "lowerLetter" \| "ordinal" \| "cardinalText" \| "ordinalText" \| "hex" \| "chicago" \| "ideographDigital" \| "japaneseCounting" \| ... 51 more ... \| undefined`
`text`	`string` `w:lvlText` pattern, e.g. “%1.%2”.
`start`	`number`
`suffix`	`"tab" \| "space" \| "nothing"` `w:suff`. Absent = tab.
`alignment`	`"center" \| "end"` `w:lvlJc`. Absent = start (Word’s left).
`isLegalNumberingStyle`	`boolean` `w:isLgl`: this level’s text renders every number as a decimal.
`tabStop`	`number` Px from the number’s start, from the level’s explicit `w:tabs` and `w:ind`. Absent without an explicit tab.
`indent`	`IndentAttrs` `w:lvl/w:pPr/w:ind`, px: the lowest tier of the indent cascade, which most numbered paragraphs in real files rely on.
`pStyle`	`string` `w:lvl/w:pStyle`: the paragraph style linked to this level. Imported as the style’s numbering binding; the style’s own `w:numPr` wins on conflict.

Export

`downloadDocx`

Parameters:

Name	Type	Default
`state`	`EditorState`
`comments`	`CommentsDocx[]`
`outputFileName`	`string`

Returns:

Promise<{ warnings: string[]; }>

`generateDocxBuffer`

Parameters:

Name	Type	Default
`state`	`EditorState`
`comments`	`CommentsDocx[]`

Returns:

Promise<{ buffer: Uint8Array<ArrayBuffer>; warnings: string[]; }>

`generateDocx`

Returns the unpacked docx-js Document. It skips the post-pack stage: packing it yourself loses comment threads, endnote options, section direction, style→level links and validation. Prefer downloadDocx / generateDocxBuffer (details).

Parameters:

Name	Type	Default
`state`	`EditorState`
`comments`	`CommentsDocx[]`

Returns:

Promise<GeneratedDocx>

`GeneratedDocx`

Name	Type	Default
`doc`	`File_2`
`warnings`	`string[]` Content the serializer skipped or degraded — surface these to the user.
`commentMeta`	`CommentExportMeta[]` Thread structure per comment id, consumed by the post-pack stage.
`sectionDirs`	`("rtl" \| null)[]` Per-section text direction in document order, consumed by the post-pack stage.

`threadsToDocx`

Parameters:

Name	Type	Default
`threads`	`Thread[]`
`schema`	`Schema<any, any>`
`resolveUserName`	`ResolveUserName` Display name for a mentioned user id. Optional: authors named in the same threads are the fallback, then the raw id.

Returns:

CommentsDocx[]

`CommentsDocx`

Name	Type	Default
`threadId`	`string \| number`
`children`	`Node[]`
`author`	`string`
`date`	`Date`
`isReply`	`boolean` True for every comment after the first in its thread — drives commentsExtended.xml reply linking.
`resolved`	`boolean` Thread resolved state — becomes w15:done in commentsExtended.xml.

`DocxValidationError`

Thrown by downloadDocx / generateDocxBuffer when the packed file breaks a rule Word enforces, instead of shipping a file Word would reject or repair. problems lists every violation as a DocxProblem. This points to a serializer bug, not bad input.

`DocxProblem`

Name	Type	Default
`part`	`string` OPC part the violation was found in, e.g. `word/document.xml`.
`rule`	`string` Rule id, e.g. `foreign-element`.
`detail`	`string` What is wrong, in one clause.
`context`	`string` Whitespace-collapsed XML around the first offending offset.