oasis-editor 0.0.1 → 0.0.2

package/dist/core/model/types/nodes.d.ts

@@ -0,0 +1,192 @@
+import { EditorBorderStyle, EditorDocxWidthValue, EditorEndnoteReferenceData, EditorFieldChar, EditorFieldData, EditorFootnoteReferenceData, EditorImageFloatingLayout, EditorImageRunData, EditorParagraphListStyle, EditorRevision, EditorTableRowHeightRule } from '../../../primitives.js';
+import { EditorParagraphStyle, EditorTableStyle, EditorTextStyle } from '../../../styles.js';
+
+/**
+ * Geometry/appearance of a text box shape (`wps:spPr`). All values are
+ * optional; an unset field means "inherit Word's default / leave as-is".
+ */
+export interface EditorTextBoxShape {
+    /** `a:prstGeom/@prst` preset geometry, e.g. "rect". */
+    preset?: string;
+    /** Solid fill color (`a:solidFill/a:srgbClr`) as `#RRGGBB`. */
+    fill?: string;
+    /** Outline color (`a:ln/a:solidFill/a:srgbClr`) as `#RRGGBB`. */
+    borderColor?: string;
+    /** Outline width in points (`a:ln/@w`, originally EMU). */
+    borderWidthPt?: number;
+}
+/**
+ * Text body properties of a text box (`wps:bodyPr`): internal padding (insets),
+ * vertical anchoring and wrap behaviour.
+ */
+export interface EditorTextBoxBody {
+    /** Internal insets in px (`@lIns/@tIns/@rIns/@bIns`, originally EMU). */
+    paddingLeft?: number;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    /** `@anchor`: vertical anchor of the text (t/ctr/b). */
+    anchor?: string;
+    /** `@wrap`: text wrap mode inside the box (e.g. "square"). */
+    wrap?: string;
+    /** True when `a:spAutoFit` is present (auto-resize box to text). */
+    autoFit?: boolean;
+    /** `@vert`: text flow direction inside the box (DrawingML vertical text). */
+    vert?: "horz" | "vert" | "vert270" | "wordArtVert" | null;
+}
+/**
+ * A Word text box (`w:drawing` containing a `wps:wsp` WordprocessingShape with
+ * `wps:txbx/w:txbxContent`). Modeled as inline run content (analogous to
+ * `EditorImageRunData`): the owning run's text is the object replacement
+ * character `\uFFFC`. The text box's own content is a list of block nodes.
+ */
+export interface EditorTextBoxData {
+    /** Box width in px (`wp:extent/@cx`, originally EMU). */
+    width: number;
+    /** Box height in px (`wp:extent/@cy`, originally EMU). */
+    height: number;
+    /** Block content of `w:txbxContent` (paragraphs and/or tables). */
+    blocks: EditorBlockNode[];
+    /** Floating/anchor layout when the drawing is a `wp:anchor`. */
+    floating?: EditorImageFloatingLayout;
+    /** Shape rotation in degrees (`wps:spPr/a:xfrm/@rot`, originally 1/60000°). */
+    rotation?: number;
+    /** `wp:docPr/@name`. */
+    name?: string;
+    /** `wp:docPr/@descr` or `@title`. */
+    alt?: string;
+    shape?: EditorTextBoxShape;
+    body?: EditorTextBoxBody;
+}
+export interface EditorTextRun {
+    id: string;
+    text: string;
+    styles?: EditorTextStyle;
+    image?: EditorImageRunData;
+    textBox?: EditorTextBoxData;
+    field?: EditorFieldData;
+    /**
+     * Preserved complex-field control char (`w:fldChar`). Zero-length marker run;
+     * see {@link EditorFieldChar}.
+     */
+    fieldChar?: EditorFieldChar;
+    /** Preserved field instruction text (`w:instrText`). Zero-length marker run. */
+    fieldInstruction?: string;
+    revision?: EditorRevision;
+    /**
+     * Inline marker of a footnote whose body lives in
+     * `EditorDocument.footnotes.items[footnoteReference.footnoteId]`.
+     */
+    footnoteReference?: EditorFootnoteReferenceData;
+    /**
+     * Inline marker of an endnote whose body lives in
+     * `EditorDocument.endnotes.items[endnoteReference.endnoteId]`.
+     */
+    endnoteReference?: EditorEndnoteReferenceData;
+}
+/**
+ * A drop cap (Word's `w:framePr/@dropCap`): a large initial letter sunk into
+ * the first lines of the paragraph, with body text wrapping around it. In OOXML
+ * the cap lives in a separate preceding frame paragraph; we attach it to the
+ * wrapping paragraph so the per-paragraph layout owns its own exclusion + glyph.
+ */
+export interface EditorDropCap {
+    /** Cap letter(s), e.g. "L". */
+    text: string;
+    /** `w:framePr/@lines` — number of body lines the cap spans (default 3). */
+    lines: number;
+    /** `w:framePr/@dropCap`: "drop" (in text) or "margin" (in the left margin). */
+    type: "drop" | "margin";
+    /** Cap run style: fontSize (`w:sz`), font, color, baselineShift (`w:position`). */
+    style?: EditorTextStyle;
+}
+export interface EditorParagraphNode {
+    id: string;
+    type: "paragraph";
+    runs: EditorTextRun[];
+    style?: EditorParagraphStyle;
+    list?: EditorParagraphListStyle;
+    /** Drop cap that body text in this paragraph wraps around, when present. */
+    dropCap?: EditorDropCap;
+}
+export interface EditorTableCellStyle {
+    shading?: string;
+    width?: number | string;
+    borderTop?: EditorBorderStyle;
+    borderRight?: EditorBorderStyle;
+    borderBottom?: EditorBorderStyle;
+    borderLeft?: EditorBorderStyle;
+    /** Bidi-aware leading/trailing borders (`w:start` / `w:end`). */
+    borderStart?: EditorBorderStyle;
+    borderEnd?: EditorBorderStyle;
+    /** Diagonal cell borders (`w:tl2br` / `w:tr2bl`). */
+    borderTopLeftToBottomRight?: EditorBorderStyle;
+    borderTopRightToBottomLeft?: EditorBorderStyle;
+    padding?: number;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    /** Bidi-aware leading/trailing margins (`w:start` / `w:end`). */
+    paddingStart?: number;
+    paddingEnd?: number;
+    verticalAlign?: "top" | "middle" | "bottom";
+    horizontalAlign?: "left" | "center" | "right" | "justify";
+    /** `w:tcPr/w:textDirection/@w:val`: cell text flow direction (vertical text). */
+    textDirection?: "lrTb" | "tbRl" | "btLr" | "lrTbV" | "tbRlV" | null;
+    /** `w:noWrap`: prevent normal wrapping inside the cell. */
+    noWrap?: boolean;
+    /** `w:tcFitText`: request Word-style text fitting within the cell width. */
+    fitText?: boolean;
+    /** `w:hideMark`: hide the cell-end marker for layout. */
+    hideMark?: boolean;
+    /** `w:headers/@w:val`: semantic header cell references. */
+    headers?: string;
+    /** Preservation-only table-cell revision/property XML children. */
+    revisionXml?: string[];
+}
+export interface EditorTableCellNode {
+    id: string;
+    blocks: EditorParagraphNode[];
+    colSpan?: number;
+    rowSpan?: number;
+    vMerge?: "restart" | "continue";
+    style?: EditorTableCellStyle;
+}
+export interface EditorTableRowStyle {
+    height?: number | string;
+    heightRule?: EditorTableRowHeightRule;
+    gridBefore?: number;
+    gridAfter?: number;
+    widthBefore?: EditorDocxWidthValue;
+    widthAfter?: EditorDocxWidthValue;
+    /** `w:cantSplit`: keep this row together during pagination. */
+    cantSplit?: boolean;
+    /** `w:hidden`: do not display this row in normal view. */
+    hidden?: boolean;
+    /** Row-level cell spacing override (`w:trPr/w:tblCellSpacing`). */
+    cellSpacing?: EditorDocxWidthValue;
+    /** Preservation-only row revision/property XML children. */
+    revisionXml?: string[];
+}
+export interface EditorTableRowNode {
+    id: string;
+    cells: EditorTableCellNode[];
+    isHeader?: boolean;
+    style?: EditorTableRowStyle;
+    /**
+     * Raw w:tblPrEx XML (per-row table property exceptions), serialized verbatim
+     * before w:trPr. Preserved for DOCX round-trip fidelity only; not editable.
+     */
+    tblPrExXml?: string;
+}
+export interface EditorTableNode {
+    id: string;
+    type: "table";
+    rows: EditorTableRowNode[];
+    gridCols?: number[];
+    style?: EditorTableStyle;
+    /** Preservation-only `w:tblGridChange` XML. */
+    tblGridChangeXml?: string;
+}
+export type EditorBlockNode = EditorParagraphNode | EditorTableNode;

package/dist/core/model/types/primitives.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Primitive building blocks shared across the editor model: borders, tabs,
+ * image run data, footnote references, revisions, fields, list styles.
+ * Kept dependency-free so it can be imported by every other model module
+ * without risk of circular imports.
+ */
+export type EditorUnderlineStyle = "single" | "double" | "thick" | "dotted" | "dottedHeavy" | "dash" | "dashedHeavy" | "dashLong" | "dashLongHeavy" | "dotDash" | "dashDotHeavy" | "dotDotDash" | "dashDotDotHeavy" | "wave" | "wavyHeavy" | "wavyDouble" | "words";
+export type EditorLigatures = "none" | "standard" | "contextual" | "historical" | "standardContextual";
+export type EditorNumberSpacing = "default" | "proportional" | "tabular";
+export type EditorNumberForm = "default" | "lining" | "oldStyle";
+export interface EditorTextLanguage {
+    value?: string | null;
+    eastAsia?: string | null;
+    bidi?: string | null;
+}
+export interface EditorBorderStyle {
+    width: number;
+    type: "solid" | "dashed" | "dotted" | "none";
+    color: string;
+}
+export interface EditorTabStop {
+    position: number;
+    type: "left" | "center" | "right" | "decimal" | "bar" | "clear";
+    leader?: "none" | "dot" | "hyphen" | "underscore" | "heavy" | "middleDot";
+}
+export interface EditorParagraphListStyle {
+    kind: "bullet" | "ordered";
+    level?: number;
+    format?: "decimal" | "lowerLetter" | "upperLetter" | "lowerRoman" | "upperRoman" | "bullet";
+    startAt?: number;
+    /**
+     * Separator between the list label and the paragraph text (`w:lvl/w:suff`).
+     * OOXML default is "tab"; Word renders the label, then advances to the next
+     * tab stop (or a space / nothing). Undefined is treated as "tab".
+     */
+    suffix?: "tab" | "space" | "nothing";
+}
+/**
+ * Image crop, mapped from DrawingML `a:srcRect`. Values are fractions of the
+ * source image (0..1), where OOXML's thousandths-of-a-percent (`100000` = 100%)
+ * have already been normalized. Each side is the amount trimmed from that edge.
+ */
+export interface EditorImageCrop {
+    left?: number;
+    top?: number;
+    right?: number;
+    bottom?: number;
+}
+export type EditorImageFillMode = "stretch" | "tile";
+export interface EditorImageFloatingPosition {
+    relativeFrom?: string;
+    align?: string;
+    offset?: number;
+}
+export interface EditorImageFloatingLayout {
+    type: "floating";
+    distT?: number;
+    distB?: number;
+    distL?: number;
+    distR?: number;
+    simplePos?: boolean;
+    relativeHeight?: number;
+    behindDoc?: boolean;
+    locked?: boolean;
+    layoutInCell?: boolean;
+    allowOverlap?: boolean;
+    positionH?: EditorImageFloatingPosition;
+    positionV?: EditorImageFloatingPosition;
+    wrap?: "none" | "square" | "tight" | "through" | "topAndBottom";
+}
+/** A point on the tight/through wrap contour, fractional (0..1) relative to the
+ * image bounding box with origin at the top-left corner. */
+export interface EditorWrapPolygonPoint {
+    x: number;
+    y: number;
+}
+export interface EditorImageRunData {
+    src: string;
+    width: number;
+    height: number;
+    alt?: string;
+    linkedSrc?: string;
+    crop?: EditorImageCrop;
+    fillMode?: EditorImageFillMode;
+    rotation?: number;
+    flipH?: boolean;
+    flipV?: boolean;
+    floating?: EditorImageFloatingLayout;
+    /** Tight/through wrap outline (fractional 0..1). Auto-traced from the image
+     * alpha or round-tripped from OOXML <wp:wrapPolygon>. Absent ⇒ rectangular. */
+    wrapPolygon?: EditorWrapPolygonPoint[];
+}
+export interface EditorFieldData {
+    type: "PAGE" | "NUMPAGES";
+}
+/**
+ * A preserved complex-field control character (`w:fldChar`). Carried on a
+ * zero-length run so that fields the editor does not evaluate (REF, PAGEREF,
+ * TOC, and unknown fields) round-trip 1:1. The instruction text between a
+ * `begin` and `separate` is carried on sibling runs via
+ * {@link EditorTextRun.fieldInstruction}. A field may span multiple paragraphs
+ * (e.g. a TOC); document order reconstructs the structure on export.
+ */
+export interface EditorFieldChar {
+    kind: "begin" | "separate" | "end";
+    /** `w:fldChar/@w:fldLock`. */
+    fieldLock?: boolean;
+    /** `w:fldChar/@w:dirty`. */
+    dirty?: boolean;
+}
+export interface EditorFootnoteReferenceData {
+    footnoteId: string;
+    customMark?: string;
+}
+export interface EditorEndnoteReferenceData {
+    endnoteId: string;
+    customMark?: string;
+}
+export interface EditorRevision {
+    id: string;
+    type: "insert" | "delete";
+    author: string;
+    date: number;
+}
+export interface EditorAsset {
+    id: string;
+    url: string;
+}
+export declare const EDITOR_ASSET_REF_PREFIX = "asset:";
+export type EditorFootnoteNumberFormat = "decimal" | "lowerRoman" | "upperRoman" | "lowerLetter" | "upperLetter" | "symbol";
+export type EditorFootnoteRestart = "continuous" | "eachSection";
+/**
+ * A DOCX width-like value.
+ * - number: points, serialized as w:type="dxa"
+ * - "NN%": percentage, serialized as w:type="pct"
+ * - "auto": serialized as w:type="auto" w:w="0"
+ */
+export type EditorDocxWidthValue = number | string;
+export type EditorTableLayout = "fixed" | "autofit";
+export type EditorTableRowHeightRule = "auto" | "exact" | "atLeast";

package/dist/core/model/types/selection.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Selection and editing-zone types. Kept separate from document data so
+ * editor-state modules can depend on them without pulling the whole document.
+ */
+export interface EditorPosition {
+    paragraphId: string;
+    runId: string;
+    offset: number;
+}
+export interface EditorSelection {
+    anchor: EditorPosition;
+    focus: EditorPosition;
+}
+export type EditorEditingZone = "main" | "header" | "footer" | "footnote";

package/dist/core/model/types/styles.d.ts

@@ -0,0 +1,149 @@
+import { EditorBorderStyle, EditorDocxWidthValue, EditorLigatures, EditorNumberForm, EditorNumberSpacing, EditorTabStop, EditorTextLanguage, EditorUnderlineStyle } from '../../../primitives.js';
+
+export interface EditorTextStyle {
+    styleId?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    underlineStyle?: EditorUnderlineStyle | null;
+    underlineColor?: string | null;
+    strike?: boolean;
+    doubleStrike?: boolean;
+    superscript?: boolean;
+    subscript?: boolean;
+    smallCaps?: boolean;
+    allCaps?: boolean;
+    hidden?: boolean;
+    noProof?: boolean;
+    webHidden?: boolean;
+    specVanish?: boolean;
+    textEffect?: string | null;
+    characterScale?: number | null;
+    characterSpacing?: number | null;
+    baselineShift?: number | null;
+    kerningThreshold?: number | null;
+    ligatures?: EditorLigatures | null;
+    numberSpacing?: EditorNumberSpacing | null;
+    numberForm?: EditorNumberForm | null;
+    stylisticSet?: number | null;
+    contextualAlternates?: boolean;
+    fontFamily?: string | null;
+    fontSize?: number | null;
+    color?: string | null;
+    highlight?: string | null;
+    shading?: string | null;
+    language?: EditorTextLanguage | null;
+    link?: string | null;
+}
+export interface EditorParagraphStyle {
+    styleId?: string;
+    align?: "left" | "center" | "right" | "justify";
+    spacingBefore?: number | null;
+    spacingAfter?: number | null;
+    contextualSpacing?: boolean;
+    /**
+     * Line spacing value. Interpretation depends on `lineRule`:
+     * - `auto`/absent: multiplier of single line spacing (e.g. 1.15).
+     * - `exact`/`atLeast`: absolute height in px.
+     */
+    lineHeight?: number | null;
+    /** `w:spacing/@w:lineRule`. Defaults to `auto` (multiplier) when absent. */
+    lineRule?: "auto" | "exact" | "atLeast" | null;
+    lineGridPitch?: number | null;
+    lineGridType?: "lines" | "linesAndChars" | "snapToChars" | null;
+    snapToGrid?: boolean;
+    indentLeft?: number | null;
+    indentRight?: number | null;
+    indentFirstLine?: number | null;
+    indentHanging?: number | null;
+    shading?: string | null;
+    borderTop?: EditorBorderStyle | null;
+    borderRight?: EditorBorderStyle | null;
+    borderBottom?: EditorBorderStyle | null;
+    borderLeft?: EditorBorderStyle | null;
+    tabs?: EditorTabStop[] | null;
+    pageBreakBefore?: boolean;
+    keepWithNext?: boolean;
+    keepLinesTogether?: boolean;
+    widowControl?: boolean;
+    /** `w:textDirection/@w:val`: paragraph flow direction (vertical text). */
+    textDirection?: "lrTb" | "tbRl" | "btLr" | "lrTbV" | "tbRlV" | null;
+}
+/** Row properties from a conditional format's `w:trPr`. */
+export interface EditorConditionalRowStyle {
+    height?: number | string;
+    heightRule?: "auto" | "exact" | "atLeast";
+    cantSplit?: boolean;
+    hidden?: boolean;
+}
+export interface EditorTableConditionalFormat {
+    shading?: string;
+    /** Run formatting (bold/color) from the conditional's `w:rPr`. */
+    textStyle?: EditorTextStyle;
+    /** Cell borders from the conditional's `w:tcPr/w:tcBorders`. */
+    borders?: {
+        borderTop?: EditorBorderStyle;
+        borderRight?: EditorBorderStyle;
+        borderBottom?: EditorBorderStyle;
+        borderLeft?: EditorBorderStyle;
+    };
+    /** Paragraph properties from the conditional's `w:pPr`. */
+    paragraphStyle?: EditorParagraphStyle;
+    /** Row properties from the conditional's `w:trPr`. */
+    rowStyle?: EditorConditionalRowStyle;
+}
+export interface EditorTableStyle {
+    styleId?: string;
+    width?: EditorDocxWidthValue;
+    align?: "left" | "center" | "right";
+    indentLeft?: EditorDocxWidthValue;
+    layout?: "fixed" | "autofit";
+    cellSpacing?: EditorDocxWidthValue;
+    pageBreakBefore?: boolean;
+    /** `w:bidiVisual`: visually order table columns right-to-left. */
+    bidiVisual?: boolean;
+    /** `w:tblOverlap/@w:val`: floating-table overlap behavior. */
+    tblOverlap?: string;
+    /** `w:tblCellMar`: default margins for cells unless overridden by `w:tcMar`. */
+    defaultCellMargins?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+        start?: number;
+        end?: number;
+    };
+    /** Raw `w:tblpPr` attributes for floating table round-trip preservation. */
+    floating?: Record<string, string>;
+    /** Table alt text title, corresponding to Word's table properties Alt Text title. */
+    altTitle?: string;
+    /** Table alt text description, corresponding to Word's table properties Alt Text description. */
+    altDescription?: string;
+    /** Preservation-only table revision/property XML children. */
+    revisionXml?: string[];
+    /** `w:tblStyleRowBandSize` — rows per horizontal band (default 1). */
+    rowBandSize?: number;
+    /** `w:tblStyleColBandSize` — columns per vertical band (default 1). */
+    colBandSize?: number;
+    /** Keyed by conditional type ("firstRow", "lastRow", "band1Horz", etc.). */
+    conditionalFormats?: Record<string, EditorTableConditionalFormat>;
+    /** `w:tblLook` flags from the instance table; preserved for re-export. */
+    tblLook?: {
+        firstRow: boolean;
+        lastRow: boolean;
+        firstCol: boolean;
+        lastCol: boolean;
+        noHBand: boolean;
+        noVBand: boolean;
+    };
+}
+export interface EditorNamedStyle {
+    id: string;
+    name: string;
+    type: "paragraph" | "character" | "table";
+    basedOn?: string;
+    nextStyle?: string;
+    paragraphStyle?: EditorParagraphStyle;
+    textStyle?: EditorTextStyle;
+    tableStyle?: EditorTableStyle;
+}