@docx-editor.dev/core/output
@docx-editor.dev/core/output — painting a layout into DOM.
The painted pages ARE the editable surface, but the DOM is a picture: browser mutations are prevented and re-expressed as tree ops, and selection maps only through data-paragraph-id and data-start.
Functions (5)
collectPageChangeBarsfunctionSource ↗
The rules one page needs, in sheet coordinates: every root story the page paints, the blocks of each (tracked rows and rotated cells included), and the text-box stories its anchored drawings carry, each at the origin the painter places it at.
declare function collectPageChangeBars(page: PageRecord, scale: number, mode: ChangeBarsMode, toggle?: boolean, markup?: ResolvedRevisionMarkup, facingPages?: boolean, colors?: RevisionStyleContext): PageChangeBars;lumTransferfunctionSource ↗
Word's a:lum transfer for bright/contrast given in percent (70.001 for 70001). Returns null for the identity transfer and for non-finite input.
declare function lumTransfer(brightPercent: number, contrastPercent: number): LumTransfer | null;observeUnsupportedElementsfunctionSource ↗
Observe placeholder mounts across repaint, pagination, and document replacement. The returned function disconnects the observer. Component mutations do not publish another list unless the engine's mount points change.
declare function observeUnsupportedElements(container: HTMLElement, listener: (hosts: readonly UnsupportedElementHost[]) => void): () => void;paintSelectionOverlayfunctionSource ↗
Draw a set of rectangles over the pages.
The layer is a SIBLING of the pages, never a child: the page painter sweeps anything it did not paint out of its own subtree, and a stray child of a contenteditable is editable content a keystroke could land in.
declare function paintSelectionOverlay(layer: HTMLElement, layout: SemanticLayout, rects: readonly OverlayRect[], options: SelectionOverlayOptions): void;paintSemanticLayoutfunctionSource ↗
Paint a whole layout into a container, reusing the pages that did not change.
The DOM is built with createElement and textContent only — no file-derived string is ever parsed as markup — and stray children (nothing this module painted) are removed, so the container's content is always exactly the painted pages.
declare function paintSemanticLayout(container: HTMLElement, layout: SemanticLayout, options?: PaintOptions): void;Interfaces (14)
BreakMarkStringsinterfaceSource ↗
Localized break labels; adapters supply i18n-backed implementations.
interface BreakMarkStrings| Member | Type | Summary |
|---|---|---|
| columnBreak | string | |
| pageBreak | string | |
| sectionBreakContinuous | string | |
| sectionBreakEvenPage | string | |
| sectionBreakNextColumn | string | |
| sectionBreakNextPage | string | |
| sectionBreakOddPage | string |
DrawingSupportIssueinterfaceSource ↗
A drawing feature that the editor does not show as authored. Each code means:
- unsupported-effect: the editor ignores an explicit effect, such as a:blur, a:duotone, or a14:imgProps. The drawing renders without it. - renderer-required: an optional effect, such as a:glow, needs the drawing module: drawingModule() or installDrawing() from @docx-editor.dev/pro/drawing. It appears only while that module is not installed in the current process, for occurrences and reports alike. - unverified-3d: the drawing has 3-D properties (a:scene3d, a:sp3d), which render flat. - saved-fallback: the editor shows the saved mc:Fallback content, not the main content. - unplaced-drawing: the drawing has no layout position, so the editor does not show it. - inspection-limit: a scan budget stopped the check, so the result is incomplete. - projection-diagnostic: the source is malformed or partly unusable. detail holds the diagnostic code, such as invalid-geometry or resource-refused.
The check reads the drawing's own XML. It does not read chart or diagram parts, inherited theme effects, or image bytes, so an empty list does not prove full fidelity.
interface DrawingSupportIssue| Member | Type | Summary |
|---|---|---|
| code | 'unsupported-effect' | 'renderer-required' | 'unverified-3d' | 'saved-fallback' | 'unplaced-drawing' | 'inspection-limit' | 'projection-diagnostic' | The kind of limitation. The list in this type's description explains each code. |
| detail | string | The feature, such as `a:blur` or `mc:Fallback`, or the projection diagnostic code. |
| localName | string | The local name of the node with the feature, such as `blur`. |
| namespaceUri | string | The namespace of the node with the feature. |
| nodeId | string | The source node with the feature: in the inspected package for a report, or in the editor's current document for an occurrence's `drawingIssues`. |
LumTransferinterfaceSource ↗
out = slope * in + intercept over sRGB channels in [0, 1].
interface LumTransfer| Member | Type | Summary |
|---|---|---|
| intercept | number | |
| slope | number |
OverlayRectinterfaceSource ↗
A rectangle in page-content coordinates, on a named page.
interface OverlayRect| Member | Type | Summary |
|---|---|---|
| activeBackground? | string | Background for the OPEN revision's band, from the author's declared `activeBackground`. Applied inline, so it outranks the kind tokens in the stylesheet, and the kind-coloured rule under the band is cleared with it. |
| className? | string | Class for THIS rectangle, overriding the layer's default. |
| height | number | |
| pageIndex | number | |
| reviewAuthor? | ReviewAuthorInfo | WHOSE band this is, as CSS hooks on the rectangle: `data-review-author`, `data-review-author-slot`, and `--doc-review-author-current` set to the colour that author resolves to. |
| width | number | |
| x | number | |
| y | number |
PageChangeBarsinterfaceSource ↗
Page change bars in page coordinates.
interface PageChangeBars| Member | Type | Summary |
|---|---|---|
| color? | string | |
| left | number | Sheet-relative x of the column, already scaled and snapped to a whole pixel. |
| mode | ChangeBarsMode | |
| runs | readonly BarRun[] | |
| signature | string | Cheap identity of `left` + `runs`, for the block-adoption path to compare. |
| toggle | boolean | Whether the bars take the pointer as Word's toggle. |
PaintOptionsinterfaceSource ↗
How a layout is painted into DOM. Every field is optional.
The painted pages ARE the editable surface, so everything here is presentation-only — nothing set through these options is ever serialised back into the document.
interface PaintOptions| Member | Type | Summary |
|---|---|---|
| activeHeaderFooterPageIndex? | number | Sheet that hosts the active visual occurrence of a shared furniture part. |
| activeHeaderFooterRId? | string | Relationship id of the header/footer story currently open for editing. |
| breakMarkStrings? | BreakMarkStrings | Localized labels for the break furniture paragraph marks show (defaults to English). |
| changeBars? | ChangeBarsMode | Which change bars the margin draws: All Markup's neutral rule beside attributed lines (the default, whatever the layout's projection — a layout that carries attribution gets its bars), Simple Markup's red rule beside the change sites a resolved layout published, or none, which the review chrome names for its resolved views. |
| changeBarsToggle? | boolean | Whether a change bar takes the pointer as Word's does — a click swaps Simple and All Markup. Only a host that can act on the press should set it; the bars stay inert furniture otherwise. |
| contentControlChrome? | {
readonly showAll?: boolean;
readonly activeIds?: ReadonlySet<string>;
readonly hoverIds?: ReadonlySet<string>;
readonly suppressedIds?: ReadonlySet<string>;
readonly checkedIds?: ReadonlySet<string>;
readonly additionalBoundaries?: readonly ContentControlBoundaryRecord[];
readonly tocControlIds?: ReadonlySet<string>;
readonly readOnly?: boolean;
} | On-demand content-control boundary chrome (show-all and/or caret-entry). |
| defaultFontFamily? | string | See [PaintContext.defaultFontFamily](PaintContext.defaultFontFamily). |
| drawingStrings? | DrawingPaintStrings | |
| emptyTocPlaceholderIds? | ReadonlySet<string> | Empty-TOC begin paragraphs that paint subtle identifiable furniture. Paint-only — never serialised into the document. |
| facingPages? | boolean | |
| fieldShading? | FieldShadingMode | See [PaintContext.fieldShading](PaintContext.fieldShading). |
| fontAlias? | (family: string) => string | undefined | Family-alias lookup for fonts the host registered on behalf of THIS document (see [PaintContext.fontAlias](PaintContext.fontAlias)). Painted runs emit the alias ahead of the declared family, so a file can never shadow a family name the host page uses. |
| imageUrlPort? | PaintImageUrlPort | |
| includePartial? | boolean | |
| materialize? | ReadonlySet<number> | Page indices to build in detail (task 9.4). |
| readOnlyParagraphIds? | ReadonlySet<string> | Generated paragraphs that paint as non-editable navigation surfaces. |
| revisionKindColors? | boolean | |
| revisionMarkup? | ResolvedRevisionMarkup | |
| revisionStyles? | RevisionStyles | How tracked changes are coloured: by AUTHOR through the `--doc-review-author-N` ramp (the default, as in Word), by kind, or by author with host-pinned colours. See [RevisionStyles](RevisionStyles). |
| scale? | number | Points to CSS pixels. 96/72 renders a point as a CSS point at 100% zoom. |
| shadeFormFields? | boolean | See [PaintContext.shadeFormFields](PaintContext.shadeFormFields). |
| showParagraphMarks? | boolean | Paint paragraph-end and manual-line-break furniture. Tracked marks also follow Show/Hide. |
| unsupportedOwnerPartName? | (nodeId: string) => string | |
| unsupportedSource? | (nodeId: string, ownerPartName?: string) => OoxmlElement | null |
ReviewAuthorInfointerfaceSource ↗
One document author, resolved: who, which ramp slot, and what they draw in.
interface ReviewAuthorInfo| Member | Type | Summary |
|---|---|---|
| author | string | The `w:author` string, exactly as the file carries it. |
| color | string | The colour this author is DRAWN IN by the review chrome — their declared colour, or their ramp slot's token. |
| slot | number | Stable session rank, seeded by order of first appearance — an UNBOUNDED index. |
| style? | RevisionAuthorStyle | The host-supplied style, normalised; absent when the author rides the ramp. |
RevisionAuthorAssignmentsinterfaceSource ↗
Per-author style assignments.
Keys match w:author exactly; a value is a CSS colour or a full [RevisionAuthorStyle](RevisionAuthorStyle). others says what authors WITHOUT an entry take: the --doc-review-author-N ramp by default, or 'kind' to leave them on the kind colours — which is how "highlight these reviewers, leave everyone else green and red" is said.
interface RevisionAuthorAssignments| Member | Type | Summary |
|---|---|---|
| authors | Readonly<Record<string, string | RevisionAuthorStyle>> | |
| others? | 'kind' | 'author' | Authors without an entry: the ramp (default), or the `'kind'` colours. |
RevisionAuthorStyleinterfaceSource ↗
Everything a host can say about ONE author's presentation. Every field is optional and every field is presentation-only — nothing here is ever serialised into the document.
Deliberately about the PAINTED DOCUMENT (which only the painter can style) plus the author's identity data. Review-card DESIGN is not configured here: the review chrome follows color as its accent automatically, and everything further is composition — a custom card reading this style through the review surface's useReviewAuthor, or CSS on the cards' data-review-author/data-review-author-slot hooks.
interface RevisionAuthorStyle| Member | Type | Summary |
|---|---|---|
| activeBackground? | string | Background of the highlight band over this author's OPEN change — the one the caret is in. Applied inline, so it outranks the `--doc-revision-*-active-bg` kind tokens, and the kind-coloured rule under the band goes with it: a custom background with a green or red rule beneath it would contradict the decoration it sits behind, and a `transparent` that left a floating rule would not read as cleared at all. |
| avatarUrl? | string | Avatar image for this author; the packaged card renders it in place of initials. |
| background? | string | Background wash behind this author's changes in the document. |
| color? | string | Ink and decoration colour of this author's changes in the document — and the accent the review chrome keys on (avatar disc, card variable, marker). |
| spanClassName? | string | Class names added to every painted span of this author's changes, for styling the typed fields do not cover. Keep the rules metric-safe (outlines, shadows, accents): the engine measures the text it paints, and a class that resizes glyphs drifts the page from its layout. |
SelectionOverlayOptionsinterfaceSource ↗
How the selection overlay draws its rectangles over the painted pages.
scale and pageOffsetX must match what the page painter used, or the highlight lands beside the content it describes rather than on it.
interface SelectionOverlayOptions| Member | Type | Summary |
|---|---|---|
| className? | string | Class for each painted rectangle. Defaults to the cell-selection class, because a cell rectangle was the only thing this layer drew when it was written. |
| pageOffsetX? | ReadonlyMap<number, number> | Per-page horizontal offset the page painter applied, by page index. |
| scale | number | Points to CSS pixels. |
UnsupportedElementinterfaceSource ↗
One occurrence that a custom component can replace: a placeholder for content the editor cannot render, or, with includePartial, a drawing that the editor renders without some features. The drawing fields are present only for drawings.
interface UnsupportedElement| Member | Type | Summary |
|---|---|---|
| bounds? | LayoutBox | Reserved geometry in document points, when the element has been laid out. Always present for a drawing, and it includes the effect extent, as the page of `createDrawingPreviewPackage` does. |
| drawing? | InlineDrawingRecord | AnchoredDrawingRecord | The layout record of a drawing. Use `graphicKind` to identify the graphic: the record's `placeholderGraphicKind` names the graphic only for placeholders. A chart whose chart part can be read also carries `chart`, whose `shownAs` describes the native presentation. Absent for other content. |
| drawingIssues? | readonly DrawingSupportIssue[] | The features of this drawing that the editor does not show as authored, read from its own XML. Chart and diagram parts, inherited theme effects, and image bytes are not read, so an empty list does not prove fidelity. Never holds `unplaced-drawing` or `projection-diagnostic`, which only a report lists. For a placeholder, `graphicKind` names the graphic that the editor cannot draw. |
| equation? | EquationSpanRecord | The layout record of an equation shown as the built-in placeholder. |
| graphicKind? | DrawingGraphicKind | The graphic a drawing holds, such as `picture`, `chart`, or `diagram`, from its source. Note: `textbox` names every DrawingML shape, with or without text, and `shape` names only legacy VML drawings. |
| label | string | The text of the built-in placeholder. |
| localName | string | The local name of the source element, such as `drawing` or `AlternateContent`. |
| namespaceUri | string | null | The namespace of the source element, such as the WordprocessingML namespace. |
| nodeId | string | The node the occurrence comes from, in the editor's current document. |
| ownerPartName | string | The part that holds it, such as `/word/document.xml` or `/word/header1.xml`. |
| placement | 'inline' | 'block' | `inline` inside a line of text, or `block` between paragraphs. |
| source | OoxmlElement | null | Lossless canonical source. Treat this value as read-only and untrusted. The object identity stays unchanged until the drawing content changes. Use `source` to identify cached previews across component remounts. Editor occurrences always provide a source. Standalone painters without a source lookup return `null`. |
| support? | Exclude<DrawingSupport, 'native'> | How completely the editor shows this drawing: `unrendered` for a placeholder, or `partial` for a drawing that renders without some features, offered only with `includePartial`. Absent for content that is not a drawing. |
UnsupportedElementHostinterfaceSource ↗
A component mount point and its built-in fallback.
interface UnsupportedElementHost| Member | Type | Summary |
|---|---|---|
| element | HTMLElement | |
| fallback | HTMLElement | |
| key | string | Stable identity for one painted occurrence. |
| setCustomized | | Hide the default and expose custom controls to assistive technology. Restore with false. |
| slot | HTMLElement | |
| unsupported | UnsupportedElement |
UnsupportedElementLayoutinterfaceSource ↗
Dimensions reserved before pagination, in document points.
interface UnsupportedElementLayout| Member | Type | Summary |
|---|---|---|
| height | number | Height in points: finite, positive, and at most 100,000. |
| width | number | Width in points: finite, positive, and at most 100,000. |
UnsupportedElementRuleinterfaceSource ↗
The first matching registration renders each unsupported element.
interface UnsupportedElementRule| Member | Type | Summary |
|---|---|---|
| includePartial? | boolean | Include partially rendered drawings (`support: 'partial'`). Defaults to `false`. Excludes fully supported drawings, hidden drawings, and drawings without a layout position. Excludes shapes with editable text. Partially rendered shapes without text remain eligible. |
| layout? | UnsupportedElementLayout | The box to reserve for content that has no layout box of its own, in points. |
| match? | (element: UnsupportedElement) => boolean | Return true to replace this occurrence. Omit to match every offered occurrence. Offered occurrences also include equations and other content that is not a drawing; test `element.drawing` to match drawings only. |
Type aliases (5)
ChangeBarsModetypeSource ↗
Which bars a paint draws.
type ChangeBarsMode = 'all-markup' | 'simple-markup' | 'none';DrawingGraphicKindtypeSource ↗
The kind of graphic a drawing holds. Note: textbox names every DrawingML shape, with or without text, and shape names only legacy VML drawings.
Read from its source: picture, chart (a chart), diagram (SmartArt), textbox (a DrawingML shape, with or without text), group (a shape group), canvas (a drawing canvas), shape (a legacy VML drawing, such as WordArt), or graphic (any other graphic). It does not say whether the engine renders the graphic. The names match placeholderGraphicKind, which adds no picture and is set only for placeholders.
type DrawingGraphicKind = 'picture' | 'chart' | 'diagram' | 'shape' | 'group' | 'textbox' | 'canvas' | 'graphic';DrawingSupporttypeSource ↗
How completely the editor shows a drawing:
- native: the editor renders the drawing and found no unsupported feature in its source. - partial: the editor renders the drawing, but without some features, or it shows a saved fallback. The issue list names the features. - unrendered: the editor shows a placeholder, or the drawing has no layout position.
A drawing that the document itself hides is native or partial: the editor shows it as authored, which is not at all.
Charts and SmartArt diagrams that the editor draws report native, because the check does not read their chart or diagram parts. Inherited theme effects and image bytes are not checked either.
type DrawingSupport = 'native' | 'partial' | 'unrendered';FieldShadingModetypeSource ↗
When a field's result is drawn on its grey block, following Word's own View option.
when-selected is Word's default and the reason the option exists at all: a document dense with cross-references turns largely grey under always, and under never a reader cannot tell computed text from typed text at all.
type FieldShadingMode = 'never' | 'when-selected' | 'always';RevisionStylestypeSource ↗
How painted tracked changes are coloured.
- 'author' (the DEFAULT) — every change takes its author's colour from the --doc-review-author-N ramp. An attached document seeds slots by order of first appearance, then keeps those assignments stable for that session. Word's own default, and the reason it is this engine's: a paragraph three people edited has to read as three people. Restyle a slot under .docx-editor to change the ramp. - 'kind' — insertions and deletions take the two kind colours (--doc-revision-insertion / --doc-revision-deletion), so "added" and "removed" are what a reader tells apart at a glance, whoever proposed them. - [RevisionAuthorAssignments](RevisionAuthorAssignments) — style the named authors; others decides whether the rest take the ramp (the default) or the kind colours.
Presentation only: nothing here is ever serialised into the document.
type RevisionStyles = 'kind' | 'author' | RevisionAuthorAssignments;Variables (1)
DEFAULT_FIELD_SHADINGconstSource ↗
Word's default: shaded only while the caret is inside the field.
DEFAULT_FIELD_SHADING: FieldShadingMode