@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 (2)
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 (6)
OverlayRectinterfaceSource ↗
A rectangle in page-content coordinates, on a named page.
interface OverlayRect| Member | Type | Summary |
|---|---|---|
| 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 |
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. |
| 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. |
| 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 | |
| materialize? | ReadonlySet<number> | Page indices to build in detail (task 9.4). |
| readOnlyParagraphIds? | ReadonlySet<string> | Generated paragraphs that paint as non-editable navigation surfaces. |
| 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). |
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 |
|---|---|---|
| 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. |
Type aliases (2)
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