/** * @docen/docx — Type definitions. * * Design: Tiptap attr interfaces mirror @office-open/docx Option interfaces * via the AttrNullable mapped type. This maximizes reuse and keeps attr * structure identical to the persistence model, so parseDocx/renderDocx * become near-identity mappings. * * Attr design principles: * - Mirror @office-open/docx Option interfaces, INCLUDING nesting * (indent/spacing/border/run/frame are nested objects) * - Store office-open native values (twips, points, AlignmentType strings) * so DOCX round-trip is lossless by construction * NOTE: `size` is in POINTS (new office-open convention), not half-points * - CSS conversion happens only in the canvas layout/paint layer via utils mappers * - Keep structural names only where no OOXML counterpart exists (src, alt) * * @module */ import type { ParagraphPropertiesOptionsBase, RunPropertiesOptions, RunStylePropertiesOptions, SectionPropertiesOptions, TableOptions, TableRowPropertiesOptionsBase, TableCellOptions, Floating, PictureOptions, } from "@office-open/docx"; import type { JSONContent as TiptapJSONContent } from "@tiptap/core"; // ============================================================ // Layer 1: Re-export @office-open/docx types (persistence model) // ============================================================ // The five office-open types used internally for attr derivation (below) are // imported once and re-exported by reference — instead of a second // `export ... from "@office-open/docx"` — so each type has a single // dependency declaration in this file. export type { TiptapJSONContent as JSONContent }; export type { ParagraphPropertiesOptionsBase, RunStylePropertiesOptions, TableOptions, TableRowPropertiesOptionsBase, TableCellOptions, }; export type { // Document structure DocumentOptions, SectionOptions, SectionChild, SectionPropertiesOptions, PageBordersOptions, // Paragraph ParagraphOptions, ParagraphChild, ParagraphPropertiesOptions, ParagraphStylePropertiesOptions, LevelParagraphStylePropertiesOptions, // Run RunOptions, RunPropertiesOptions, ParagraphRunPropertiesOptions, // Picture PictureOptions, MediaTransformation, // Table TableRowOptions, // Indent, spacing, borders, shading IndentProperties, SpacingProperties, BordersOptions, BorderOptions, ShadingProperties, // Table structural types (reused in attr interfaces) TableBordersOptions, TableCellBordersOptions, TableFloatOptions, TableLookOptions, TableWidthProperties, TableLayoutType, TableVerticalAlign, HeightRule, WidthType, Margins, // Run structural types (reused in attr interfaces) FontProperties, EmphasisMarkType, UnderlineType, // Alignment, heading, tab stops, line rule AlignmentType, HeadingLevel, TabStopDefinition, TabStopType, TabStopPosition, LeaderType, LineRuleType, TextAlignmentType, // Floating, hyperlinks, math Floating, ExternalHyperlinkOptions, InternalHyperlinkOptions, MathInput, // Underline, highlight HighlightColor, // Frame (paragraph text frames) FrameOptions, // Bookmark, ruby BookmarkOptions, RubyOptions, } from "@office-open/docx"; // ============================================================ // Layer 2: Tiptap attr interfaces (runtime model) // // Derived from @office-open/docx Option interfaces via AttrNullable. // Every property becomes `T | null` (required, explicit null) to match // ProseMirror's attr storage model (every declared attr is stored, // even when null). Nesting reduces the attr count vs flattening. // ============================================================ /** * Make every property of T nullable and required. * ProseMirror stores every declared attr; explicit null matches that model. */ export type AttrNullable = { [K in keyof T]-?: T[K] | null }; /** Paragraph attrs — mirrors ParagraphPropertiesOptionsBase verbatim * (heading/style/bullet/numbering/thematicBreak included: a heading IS a * paragraph), plus engine-only section* extras (OOXML sectPr lives on a * section's last paragraph, so the engine hauls the section boundary + its * header/footer slots on that paragraph). * * indent/spacing/border/run/frame are nested objects (matching office-open), * so one `indent` attr replaces 13 flattened indent attrs. */ export type ParagraphAttrs = AttrNullable & { sectionProperties: SectionPropertiesOptions | null; sectionHeaders: HeaderFooterSlots | null; sectionFooters: HeaderFooterSlots | null; }; /** Text style mark attrs — mirrors RunPropertiesOptions (rStyle `style` * included). Omits properties handled by dedicated marks (bold, italic, * strike, doubleStrike, subScript, superScript). `size` is in POINTS. */ export type TextStyleAttrs = AttrNullable< Omit< RunPropertiesOptions, | "bold" | "boldComplexScript" | "italic" | "italicComplexScript" | "strike" | "doubleStrike" | "subScript" | "superScript" > >; /** * Link mark attrs. */ export interface LinkAttrs { href: string | null; target: string | null; rel: string | null; class: string | null; title: string | null; } /** * Table attrs — mirrors TableOptions (minus `rows`, which is structural). */ export type TableAttrs = AttrNullable>; /** * Table row attrs — mirrors TableRowPropertiesOptionsBase. * height is nested { value, rule } matching office-open. */ export type TableRowAttrs = AttrNullable; /** * Table cell attrs — mirrors TableCellOptions directly (the OOXML grid shape * is the PM shape; vMerge expands into rowspan only at the layout projection * point). */ export type TableCellAttrs = AttrNullable>; /** * Image attrs. * src/alt/title kept as Tiptap structural names. * width/height are pixel dimensions for editor display. */ export interface ImageAttrs { src: string; alt: string | null; title: string | null; width: number | null; height: number | null; rotation: number | null; floating: Floating | null; outline: NonNullable | null; crop: NonNullable | null; display: string | null; // Fidelity fields (office-open native; near-identity passthrough) nonVisualProperties: NonNullable | null; // pic:cNvPr (id/name/descr) effectExtent: { l: number; t: number; r: number; b: number } | null; // wp:effectExtent EMUs graphicFrameLocks: NonNullable | null; blipEffects: NonNullable | null; useLocalDpi: boolean | null; // a14:useLocalDpi fill: NonNullable | null; effects: NonNullable | null; tile: NonNullable | null; runProperties: NonNullable | null; } /** * Strike mark attrs. */ export interface StrikeAttrs { doubleStrike: boolean | null; } // ============================================================ // Layer 3: Tiptap JSON node types // // These describe the structure of JSONContent produced by our // custom extensions. Useful for consumers who need typed access. // ============================================================ // -- Inline content -- export interface TextNode { type: "text"; text: string; marks?: Mark[]; } export interface HardBreakNode { type: "hardBreak"; marks?: Mark[]; } // -- Mark types -- /** OOXML track-change metadata (w:ins / w:del). Mirrors office-open's * ChangedProperties: `id` is the w:id (number), `author`/`date` are * the revision author and timestamp. */ export interface TrackChangeAttrs { id: number | null; author: string | null; date: string | null; } export type Mark = | { type: "bold" } | { type: "italic" } | { type: "underline" } | { type: "strike"; attrs?: StrikeAttrs } | { type: "code" } | { type: "subscript" } | { type: "superscript" } | { type: "highlight"; attrs?: { color?: string } } | { type: "textStyle"; attrs?: TextStyleAttrs } | { type: "link"; attrs?: LinkAttrs } | { type: "insertion"; attrs?: TrackChangeAttrs } | { type: "deletion"; attrs?: TrackChangeAttrs }; // -- Block nodes -- export interface ParagraphNode extends TiptapJSONContent { type: "paragraph"; attrs?: ParagraphAttrs; content?: InlineContent[]; } /** * Header/footer slots in Tiptap JSON — each slot is the JSONContent[] produced * by resolving that slot's SectionChild[] (paragraphs/tables/…). Mirrors * SectionOptions.headers/footers in the runtime model. */ export interface HeaderFooterSlots { default?: TiptapJSONContent[]; first?: TiptapJSONContent[]; even?: TiptapJSONContent[]; } // -- Table nodes -- export interface TableNode extends TiptapJSONContent { type: "table"; attrs?: TableAttrs; content?: Array; } export interface TableRowNode extends TiptapJSONContent { type: "tableRow"; attrs?: TableRowAttrs; content?: Array; } export interface TableCellNode extends TiptapJSONContent { type: "tableCell"; attrs?: TableCellAttrs; content?: Array; } // -- Image node -- export interface ImageNode extends TiptapJSONContent { type: "image"; attrs?: ImageAttrs; } /** * Drawing group (wpg) carried as an opaque blob — the full WpgGroupRunOptions * (pictures/shapes/nested groups + transform) round-trips verbatim; the canvas * layer lays out every child at its transformed position (Office-style group * rendering). */ export interface WpgGroupNode extends TiptapJSONContent { type: "wpgGroup"; attrs?: { wpgGroup: Record | null }; } /** * Standalone floating text-box shape (wp:anchor > wps:wsp). The shape geometry * + styling (transformation/floating/fill/outline/bodyProperties) ride on * attrs.wpsShape; the editable text body is PM content (one ParagraphNode per * office-open ParagraphOptions). Unlike a group's interior wps children, this * shape floats on its own anchor and is editable via its NodeView contentDOM. */ export interface WpsShapeNode extends TiptapJSONContent { type: "wpsShape"; attrs?: { wpsShape: Record | null }; content?: Array; } // -- Inline atom nodes: DOCX breaks (page/column) -- export interface PageBreakNode extends TiptapJSONContent { type: "pageBreak"; } export interface ColumnBreakNode extends TiptapJSONContent { type: "columnBreak"; } // -- Inline atom: DOCX tab character (``) — leader/dot-leader marker -- export interface TabNode extends TiptapJSONContent { type: "tab"; } // -- Passthrough node (block atom; opaque SectionChild blob) -- export interface PassthroughNode extends TiptapJSONContent { type: "passthrough"; attrs?: { data: string }; } // -- InlinePassthrough node (inline atom; opaque inline ParagraphChild blob) -- export interface InlinePassthroughNode extends TiptapJSONContent { type: "inlinePassthrough"; attrs?: { data: string }; } /** * TOC field node (`tocField`) — a block container whose `content` is the * editable TOC entry paragraphs. `attrs.options` carries the TOC field switches * (hyperlink, headingStyleRange, …). Named `tocField` (not `tableOfContents`) * to avoid the @tiptap/extension-table-of-contents name. See TocField extension. */ export interface TocFieldNode extends TiptapJSONContent { type: "tocField"; attrs?: { options: Record | null }; content?: Array; } // -- Union types -- export type InlineContent = | TextNode | HardBreakNode | ImageNode | PageBreakNode | ColumnBreakNode | TabNode | InlinePassthroughNode; export type BlockNode = | ParagraphNode | TableNode | WpsShapeNode | WpgGroupNode | TocFieldNode | PassthroughNode;