@stll/docx-core 0.17.3 → 0.19.0

package/README.md

@@ -4,8 +4,9 @@ A typed OOXML/DOCX document model with parsing, validation, and serialization.
 
 The package exposes a structured document model (paragraphs, runs, tables,
 styles, section properties) together with the tools to produce and check DOCX
-packages, plus a legal-source compiler that turns a plain legal draft into that
-model or a finished DOCX file.
+packages, plus a legal-source compiler that turns a legal draft (GFM markdown
+plus `@` directives) into that model or a finished DOCX file, and a plain
+markdown reader (`compileMarkdownToContent`) that shares its parser.
 
 ```ts
 import { compileLegalSourceToDocx, validateDocxPackage } from "@stll/docx-core";
@@ -30,7 +31,8 @@ bun add @stll/docx-core
 
 - `.` — the document model types, the legal-source compiler
   (`parseLegalSource`, `compileLegalSourceToDocument`,
-  `compileLegalSourceToDocx`, `validateLegalDraft`), DOCX serialization
+  `compileLegalSourceToDocx`, `validateLegalDraft`), the markdown reader
+  (`compileMarkdownToContent`, `sanitizeExternalUrl`), DOCX serialization
   (`serializeDocumentToDocx`), and validation (`validateDocxPackage`,
   `validateDocumentModel`, `assertValidDocumentModel`).
 - `./model` — the document model types only.

package/dist/{document-C4ms2O35.d.ts → document-CR8P25Qh.d.ts}

@@ -1303,6 +1303,8 @@ type PropertyChangeInfo = {
   /** Optional revision session ID */
   rsid?: string;
 } & TrackedChangeInfo;
+/** Inline content that may sit inside a run-level tracked-change wrapper. */
+type TrackedRunContent = Run | Hyperlink | BookmarkStart | BookmarkEnd | SimpleField | ComplexField | TrackedRunChange;
 /**
  * Insertion wrapper (w:ins) — runs inserted by tracked changes
  */
@@ -1311,7 +1313,7 @@ type Insertion = {
   /** Tracked change metadata */
   info: TrackedChangeInfo;
   /** Inserted content */
-  content: (Run | Hyperlink)[];
+  content: TrackedRunContent[];
 };
 /**
  * Deletion wrapper (w:del) — runs deleted by tracked changes
@@ -1321,7 +1323,7 @@ type Deletion = {
   /** Tracked change metadata */
   info: TrackedChangeInfo;
   /** Deleted content */
-  content: (Run | Hyperlink)[];
+  content: TrackedRunContent[];
 };
 /**
  * Move-from wrapper (w:moveFrom) — content moved away from this position
@@ -1331,7 +1333,7 @@ type MoveFrom = {
   /** Tracked change metadata */
   info: TrackedChangeInfo;
   /** Moved content */
-  content: (Run | Hyperlink)[];
+  content: TrackedRunContent[];
 };
 /**
  * Move-to wrapper (w:moveTo) — content moved into this position
@@ -1341,7 +1343,7 @@ type MoveTo = {
   /** Tracked change metadata */
   info: TrackedChangeInfo;
   /** Moved content */
-  content: (Run | Hyperlink)[];
+  content: TrackedRunContent[];
 };
 /**
  * Move-from range start marker (w:moveFromRangeStart) — ECMA-376 §17.13.5.22
@@ -1579,21 +1581,29 @@ type BlockSdt = {
  */
 type ParagraphContent = Run | Hyperlink | BookmarkStart | BookmarkEnd | SimpleField | ComplexField | InlineSdt | CommentRangeStart | CommentRangeEnd | CommentReference | Insertion | Deletion | MoveFrom | MoveTo | MoveFromRangeStart | MoveFromRangeEnd | MoveToRangeStart | MoveToRangeEnd | MathEquation;
 /**
- * Paragraph (w:p)
- */
-/**
- * Paragraph-mark tracked-change marker (ECMA-376 §17.13.5).
+ * The kinds a paragraph-mark tracked change can be (ECMA-376 §17.13.5).
  *
- * Word writes this as a child of `<w:pPr><w:rPr>` — `<w:ins/>` when the
- * paragraph break itself was inserted in track-changes mode (the user
- * pressed Enter mid-paragraph), `<w:del/>` when the paragraph break is
- * pending deletion (Backspace at paragraph start or Delete at paragraph
- * end). The mark is independent of the inline runs the paragraph carries.
- */
+ * Written as a child of `<w:pPr><w:rPr>` — `<w:ins/>` when the paragraph
+ * break itself was inserted in track-changes mode (the user pressed Enter
+ * mid-paragraph), `<w:del/>` when the paragraph break is pending deletion
+ * (Backspace at paragraph start or Delete at paragraph end). The mark is
+ * independent of the inline runs the paragraph carries.
+ *
+ * A relocated paragraph's break is `<w:moveFrom/>` at the source and
+ * `<w:moveTo/>` at the destination. They resolve exactly as `del` and `ins`
+ * do — a move is a deletion and an insertion that a reader is told belong
+ * together — but they are not those kinds: writing `w:del` on a moved
+ * paragraph's mark reports the relocation as a deletion as well.
+ */
+declare const PARAGRAPH_MARK_CHANGE_KINDS: readonly ["moveFrom", "moveTo", "ins", "del"];
+/** One of {@link PARAGRAPH_MARK_CHANGE_KINDS}. */
+type ParagraphMarkChangeKind = (typeof PARAGRAPH_MARK_CHANGE_KINDS)[number];
+/** A paragraph-mark tracked change, written under `<w:pPr><w:rPr>`. */
 type ParagraphMarkChange = {
-  kind: "ins" | "del";
+  kind: ParagraphMarkChangeKind;
   info: TrackedChangeInfo;
 };
+/** Paragraph (w:p) */
 type Paragraph = {
   type: "paragraph";
   /** Unique paragraph ID */
@@ -2308,4 +2318,4 @@ type Document = {
   warnings?: string[];
 };
 //#endregion
-export { ImagePosition as $, TextBox as $t, ComplexField as A, TableFormatting as An, SdtType as At, FieldCharContent as B, KnownBorderStyle as Bn, ShapeTextBody as Bt, BookmarkStart as C, SpacingExplicit as Cn, PictureWatermark as Ct, CommentRangeEnd as D, TableBorders as Dn, RunContent as Dt, Comment as E, TabStopAlignment as En, Run as Et, DrawingRawXmlMode as F, TextEffect as Fn, Shape as Ft, FootnoteProperties as G, TabContent as Gt, FooterReference as H, ThemeColorSlot as Hn, SimpleField as Ht, Endnote as I, TextFormatting as In, ShapeContent as It, HeaderReference as J, TableCellPropertyChange as Jt, HeaderFooter as K, Table as Kt, EndnotePosition as L, UnderlineStyle as Ln, ShapeFill as Lt, Deletion as M, TableMeasurement as Mn, SectionProperties as Mt, DocumentBody as N, TableRowFormatting as Nn, SectionPropertyChange as Nt, CommentRangeStart as O, TableCellBorders as On, RunPropertyChange as Ot, DrawingContent as P, TableWidthType as Pn, SectionStart as Pt, ImagePadding as Q, TableStructuralChangeInfo as Qt, EndnoteProperties as R, BorderSpec as Rn, ShapeGeometryAdjustment as Rt, BookmarkEnd as S, ParagraphFormatting as Sn, ParagraphPropertyChange as St, Column as T, TabStop as Tn, PropertyChangeInfo as Tt, Footnote as U, SoftHyphenContent as Ut, FieldType as V, ShadingProperties as Vn, ShapeType as Vt, FootnotePosition as W, SymbolContent as Wt, Image as X, TableRow as Xt, Hyperlink as Y, TablePropertyChange as Yt, ImageCrop as Z, TableRowPropertyChange as Zt, ThemeColorScheme as _, ConditionalFormatStyle as _n, NoteReferenceContent as _t, DocxPackage as a, Watermark as an, InstrTextContent as at, BlockContent as b, LineSpacingRule as bn, ParagraphContent as bt, FontTable as c, AbstractNumbering as cn, MathEquation as ct, RelationshipMap as d, ListMarkerFormatting as dn, MoveFromRangeStart as dt, TextContent as en, ImageSize as et, RelationshipType as f, ListRendering as fn, MoveTo as ft, Theme as g, CellMargins as gn, NoteNumberRestart as gt, StyleType as h, NumberingInstance as hn, NoBreakHyphenContent as ht, DocxConformanceClass as i, VerticalAlign as in, Insertion as it, DRAWING_RAW_XML_MODES as j, TableLook as jn, Section as jt, CommentReference as k, TableCellFormatting as kn, SdtProperties as kt, MediaFile as l, LevelSuffix as ln, MoveFrom as lt, StyleDefinitions as m, NumberingDefinitions as mn, MoveToRangeStart as mt, Document as n, TrackedChangeInfo as nn, ImageWrap as nt, DocDefaults as o, isOoxmlSymbolCharacter as on, LineNumberRestart as ot, Style as p, NumberFormat as pn, MoveToRangeEnd as pt, HeaderFooterType as q, TableCell as qt, DocumentSettings as r, TrackedRunChange as rn, InlineSdt as rt, FontInfo as s, normalizeRevisionId as sn, MAX_REVISION_ID as st, DOCX_CONFORMANCE_CLASSES as t, TextWatermark as tn, ImageTransform as tt, Relationship as u, ListLevel as un, MoveFromRangeEnd as ut, ThemeFont as v, EmphasisMark as vn, PageOrientation as vt, BreakContent as w, TabLeader as wn, PositionalTab as wt, BlockSdt as x, ParagraphAlignment as xn, ParagraphMarkChange as xt, ThemeFontScheme as y, FloatingTableProperties as yn, Paragraph as yt, Field as z, ColorValue as zn, ShapeOutline as zt };
+export { ImagePosition as $, TableRowPropertyChange as $t, ComplexField as A, TableBorders as An, RunPropertyChange as At, FieldCharContent as B, UnderlineStyle as Bn, ShapeGeometryAdjustment as Bt, BookmarkStart as C, LineSpacingRule as Cn, ParagraphMarkChangeKind as Ct, CommentRangeEnd as D, TabLeader as Dn, PropertyChangeInfo as Dt, Comment as E, SpacingExplicit as En, PositionalTab as Et, DrawingRawXmlMode as F, TableMeasurement as Fn, SectionPropertyChange as Ft, FootnoteProperties as G, ThemeColorSlot as Gn, SoftHyphenContent as Gt, FooterReference as H, ColorValue as Hn, ShapeTextBody as Ht, Endnote as I, TableRowFormatting as In, SectionStart as It, HeaderReference as J, Table as Jt, HeaderFooter as K, SymbolContent as Kt, EndnotePosition as L, TableWidthType as Ln, Shape as Lt, Deletion as M, TableCellFormatting as Mn, SdtType as Mt, DocumentBody as N, TableFormatting as Nn, Section as Nt, CommentRangeStart as O, TabStop as On, Run as Ot, DrawingContent as P, TableLook as Pn, SectionProperties as Pt, ImagePadding as Q, TableRow as Qt, EndnoteProperties as R, TextEffect as Rn, ShapeContent as Rt, BookmarkEnd as S, FloatingTableProperties as Sn, ParagraphMarkChange as St, Column as T, ParagraphFormatting as Tn, PictureWatermark as Tt, Footnote as U, KnownBorderStyle as Un, ShapeType as Ut, FieldType as V, BorderSpec as Vn, ShapeOutline as Vt, FootnotePosition as W, ShadingProperties as Wn, SimpleField as Wt, Image as X, TableCellPropertyChange as Xt, Hyperlink as Y, TableCell as Yt, ImageCrop as Z, TablePropertyChange as Zt, ThemeColorScheme as _, NumberingDefinitions as _n, NoteReferenceContent as _t, DocxPackage as a, TrackedRunChange as an, InstrTextContent as at, BlockContent as b, ConditionalFormatStyle as bn, Paragraph as bt, FontTable as c, Watermark as cn, MathEquation as ct, RelationshipMap as d, AbstractNumbering as dn, MoveFromRangeStart as dt, TableStructuralChangeInfo as en, ImageSize as et, RelationshipType as f, LevelSuffix as fn, MoveTo as ft, Theme as g, NumberFormat as gn, NoteNumberRestart as gt, StyleType as h, ListRendering as hn, NoBreakHyphenContent as ht, DocxConformanceClass as i, TrackedChangeInfo as in, Insertion as it, DRAWING_RAW_XML_MODES as j, TableCellBorders as jn, SdtProperties as jt, CommentReference as k, TabStopAlignment as kn, RunContent as kt, MediaFile as l, isOoxmlSymbolCharacter as ln, MoveFrom as lt, StyleDefinitions as m, ListMarkerFormatting as mn, MoveToRangeStart as mt, Document as n, TextContent as nn, ImageWrap as nt, DocDefaults as o, TrackedRunContent as on, LineNumberRestart as ot, Style as p, ListLevel as pn, MoveToRangeEnd as pt, HeaderFooterType as q, TabContent as qt, DocumentSettings as r, TextWatermark as rn, InlineSdt as rt, FontInfo as s, VerticalAlign as sn, MAX_REVISION_ID as st, DOCX_CONFORMANCE_CLASSES as t, TextBox as tn, ImageTransform as tt, Relationship as u, normalizeRevisionId as un, MoveFromRangeEnd as ut, ThemeFont as v, NumberingInstance as vn, PARAGRAPH_MARK_CHANGE_KINDS as vt, BreakContent as w, ParagraphAlignment as wn, ParagraphPropertyChange as wt, BlockSdt as x, EmphasisMark as xn, ParagraphContent as xt, ThemeFontScheme as y, CellMargins as yn, PageOrientation as yt, Field as z, TextFormatting as zn, ShapeFill as zt };

package/dist/{document-BPDUWV3O.js → document-Cj4uqQEw.js}

@@ -28,6 +28,27 @@ function normalizeRevisionId(id) {
 	if (id > 2147483647) return id % 2147483648;
 	return id;
 }
+/**
+* The kinds a paragraph-mark tracked change can be (ECMA-376 §17.13.5).
+*
+* Written as a child of `<w:pPr><w:rPr>` — `<w:ins/>` when the paragraph
+* break itself was inserted in track-changes mode (the user pressed Enter
+* mid-paragraph), `<w:del/>` when the paragraph break is pending deletion
+* (Backspace at paragraph start or Delete at paragraph end). The mark is
+* independent of the inline runs the paragraph carries.
+*
+* A relocated paragraph's break is `<w:moveFrom/>` at the source and
+* `<w:moveTo/>` at the destination. They resolve exactly as `del` and `ins`
+* do — a move is a deletion and an insertion that a reader is told belong
+* together — but they are not those kinds: writing `w:del` on a moved
+* paragraph's mark reports the relocation as a deletion as well.
+*/
+const PARAGRAPH_MARK_CHANGE_KINDS = Object.freeze([
+	"moveFrom",
+	"moveTo",
+	"ins",
+	"del"
+]);
 //#endregion
 //#region src/model/document.ts
 /** DOCX package conformance classes. */
@@ -37,4 +58,4 @@ const DOCX_CONFORMANCE_CLASSES = Object.freeze({
 	UNKNOWN: "unknown"
 });
 //#endregion
-export { normalizeRevisionId as a, isOoxmlSymbolCharacter as i, DRAWING_RAW_XML_MODES as n, MAX_REVISION_ID as r, DOCX_CONFORMANCE_CLASSES as t };
+export { isOoxmlSymbolCharacter as a, PARAGRAPH_MARK_CHANGE_KINDS as i, DRAWING_RAW_XML_MODES as n, normalizeRevisionId as o, MAX_REVISION_ID as r, DOCX_CONFORMANCE_CLASSES as t };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Dt as RunContent, Et as Run, Kt as Table, Mt as SectionProperties, N as DocumentBody, Xt as TableRow, a as DocxPackage, b as BlockContent, bt as ParagraphContent, en as TextContent, i as DocxConformanceClass, n as Document, p as Style, qt as TableCell, t as DOCX_CONFORMANCE_CLASSES, w as BreakContent, wt as PositionalTab, yt as Paragraph } from "./document-C4ms2O35.js";
+import { Et as PositionalTab, Jt as Table, N as DocumentBody, Ot as Run, Pt as SectionProperties, Qt as TableRow, Yt as TableCell, _n as NumberingDefinitions, a as DocxPackage, b as BlockContent, bt as Paragraph, i as DocxConformanceClass, kt as RunContent, n as Document, nn as TextContent, p as Style, t as DOCX_CONFORMANCE_CLASSES, w as BreakContent, xt as ParagraphContent } from "./document-CR8P25Qh.js";
 import { Buffer } from "node:buffer";
 //#region src/legal-source/types.d.ts
 type LegalDocumentKind = "agreement" | "letter" | "memo" | "checklist" | "pleading" | "other";
@@ -24,6 +24,12 @@ type LegalSignatureParty = {
   signatory?: string;
   title?: string;
 };
+/**
+ * A parsed draft block. Every `text`, `heading`, paragraph, list item, and
+ * table cell string keeps its inline GFM markdown (`**bold**`, `*italic*`,
+ * `[link](https://…)`, `` `code` ``) and `[[placeholder]]` markers; the
+ * compiler renders them into runs.
+ */
 type LegalDraftBlock = {
   type: "title";
   text: string;
@@ -114,6 +120,29 @@ declare const validateLegalDraft: (draft: LegalDraft) => LegalDraftDiagnostic[];
 //#region src/legal-source/index.d.ts
 declare const compileLegalSourceToDocx: (source: string, options?: LegalSourceCompileOptions) => Promise<LegalSourceDocxCompileResult>;
 //#endregion
+//#region src/markdown/content.d.ts
+/** Block content and the numbering definitions its list paragraphs reference. */
+type MarkdownContent = {
+  content: BlockContent[];
+  /** Present only when the markdown contained at least one list. */
+  numbering?: NumberingDefinitions;
+};
+/**
+ * Parse GFM markdown into document blocks plus the numbering its lists need.
+ * Synchronous. The caller places the blocks into a `Document` of its own
+ * (page geometry, styles, and presets are the host's decision).
+ */
+declare const compileMarkdownToContent: (markdown: string) => MarkdownContent;
+//#endregion
+//#region src/markdown/href.d.ts
+/**
+ * Keep only http(s), mailto, and tel URLs, normalised through the URL parser.
+ * Anything else (javascript:, data:, relative paths, malformed input) drops to
+ * `undefined` so a markdown link degrades to its text instead of carrying an
+ * executable target into the document.
+ */
+declare const sanitizeExternalUrl: (rawUrl: string | undefined) => string | undefined;
+//#endregion
 //#region src/serialize/docx.d.ts
 type SerializeDocumentOptions = {
   /** BCP-47 language tag (e.g. "en", "cs", "cs-CZ"); used for footer labels. */
@@ -150,4 +179,4 @@ declare const validateDocxPackage: (buffer: ArrayBuffer | Uint8Array) => Promise
 declare const validateDocumentModel: (document: Document) => ValidateDocumentModelResult;
 declare const assertValidDocumentModel: (document: Document) => void;
 //#endregion
-export { type Autofix, type BlockContent, type BreakContent, type CompiledLegalDocument, DOCX_CONFORMANCE_CLASSES, DOCX_PACKAGE_ISSUE_CODES, type Document, type DocumentBody, type DocxConformanceClass, type DocxPackage, type DocxPackageIssueCode, type LegalDraft, type LegalDraftBlock, type LegalDraftDiagnostic, type LegalSourceCompileOptions, type LegalSourceCompileResult, type LegalSourceDocxCompileResult, type LegalSourceParseResult, type Paragraph, type ParagraphContent, type PositionalTab, type Run, type RunContent, type SectionProperties, type Style, type Table, type TableCell, type TableRow, type TextContent, type ValidateDocumentModelIssue, type ValidateDocumentModelResult, type ValidateDocxPackageResult, assertValidDocumentModel, compileLegalSourceToDocument, compileLegalSourceToDocx, parseLegalSource, serializeDocumentToDocx, validateDocumentModel, validateDocxPackage, validateLegalDraft };
+export { type Autofix, type BlockContent, type BreakContent, type CompiledLegalDocument, DOCX_CONFORMANCE_CLASSES, DOCX_PACKAGE_ISSUE_CODES, type Document, type DocumentBody, type DocxConformanceClass, type DocxPackage, type DocxPackageIssueCode, type LegalDraft, type LegalDraftBlock, type LegalDraftDiagnostic, type LegalSourceCompileOptions, type LegalSourceCompileResult, type LegalSourceDocxCompileResult, type LegalSourceParseResult, type MarkdownContent, type Paragraph, type ParagraphContent, type PositionalTab, type Run, type RunContent, type SectionProperties, type Style, type Table, type TableCell, type TableRow, type TextContent, type ValidateDocumentModelIssue, type ValidateDocumentModelResult, type ValidateDocxPackageResult, assertValidDocumentModel, compileLegalSourceToDocument, compileLegalSourceToDocx, compileMarkdownToContent, parseLegalSource, sanitizeExternalUrl, serializeDocumentToDocx, validateDocumentModel, validateDocxPackage, validateLegalDraft };