@sobree/core 0.1.0

package/dist/docx/import/styles.d.ts

@@ -0,0 +1,3 @@
+import { NamedStyle } from '../../doc/types';
+import { DocSettings } from './settings';
+export declare function parseStylesXml(xml: string | undefined, settings?: DocSettings): NamedStyle[] | null;

package/dist/docx/import/tables.d.ts

@@ -0,0 +1,12 @@
+import { ConvertContext } from './paragraph';
+import { Table } from '../../doc/types';
+/**
+ * Convert a `<w:tbl>` element into a native Table block. Handles:
+ *   - Column widths from `<w:tblGrid>` (twips).
+ *   - Horizontal merges via `<w:gridSpan>`.
+ *   - Vertical merges via `<w:vMerge>` (restart / continue).
+ *   - Header rows flagged with `<w:tblHeader/>` in `<w:trPr>`.
+ *   - Cell vertical alignment via `<w:vAlign>`.
+ *   - Cell content as a sequence of Blocks (paragraphs, nested tables).
+ */
+export declare function convertTable(tbl: Element, ctx: ConvertContext): Table;

package/dist/docx/import/unzip.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Read a .docx file into a map of part-path → UTF-8 text for the parts we
+ * need as strings (all the `*.xml` parts), and bytes for the parts we need
+ * as binary (images, fonts). Kept synchronous: fflate is fast enough that a
+ * 100-page document unpacks in milliseconds on the main thread.
+ */
+export interface UnzippedDocx {
+    /** `word/document.xml` → text, `word/styles.xml` → text, etc. */
+    readonly text: Record<string, string>;
+    /** `word/media/image1.png` → bytes. */
+    readonly binary: Record<string, Uint8Array>;
+}
+export declare function unzipDocx(src: File | Blob | ArrayBuffer | Uint8Array): Promise<UnzippedDocx>;

package/dist/docx/shared/namespaces.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OOXML namespace URIs. The spec uses a rich set of prefixes
+ * (`w:`, `r:`, `wp:` …); we keep them as constants so both the
+ * importer and exporter reference the same strings. Typos here
+ * are silent parse failures, so: one source of truth.
+ */
+export declare const NS: {
+    /** WordprocessingML — the main body namespace. */
+    readonly w: "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+    /** Relationships (images, headers, hyperlinks). */
+    readonly r: "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+    /** DrawingML — image anchors and inline drawings. */
+    readonly wp: "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+    /** DrawingML core. */
+    readonly a: "http://schemas.openxmlformats.org/drawingml/2006/main";
+    /** Picture (DrawingML). */
+    readonly pic: "http://schemas.openxmlformats.org/drawingml/2006/picture";
+    /** Word-processing shapes (textboxes, geometric primitives). */
+    readonly wps: "http://schemas.microsoft.com/office/word/2010/wordprocessingShape";
+    /** Word-processing groups (containers for shapes / pictures). */
+    readonly wpg: "http://schemas.microsoft.com/office/word/2010/wordprocessingGroup";
+    /** VML — the legacy `<v:shape>` / `<w:pict>` path Word still emits
+     *  for OLE-embedded images and some compatibility shapes. */
+    readonly v: "urn:schemas-microsoft-com:vml";
+    /** Relationships package part. */
+    readonly rel: "http://schemas.openxmlformats.org/package/2006/relationships";
+    /** Content types. */
+    readonly ct: "http://schemas.openxmlformats.org/package/2006/content-types";
+};
+/** Minimal attr mapping we emit on `<w:document>` (only the namespaces we use). */
+export declare const ROOT_DOCUMENT_ATTRS: Record<string, string>;

package/dist/docx/shared/pageSize.d.ts

@@ -0,0 +1,27 @@
+import { Orientation, PageSizeKey } from '../../paperStack/pageSetup';
+export interface PageGeometry {
+    size: PageSizeKey;
+    orientation: Orientation;
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+/**
+ * Resolve twips W×H back to a named page size at a given orientation. If it
+ * doesn't match a known size within a small tolerance, return the nearest
+ * one — users editing a custom-sized doc in Sobree still get a sensible
+ * landing spot, and the exact dimensions come back on export because we
+ * write our own sectPr anyway.
+ */
+export declare function matchPageSize(widthTwips: number, heightTwips: number): {
+    size: PageSizeKey;
+    orientation: Orientation;
+};
+/** Convert a PageSetup's logical size+orientation to the twip W/H pair. */
+export declare function geometryToTwips(geom: PageGeometry): {
+    w: number;
+    h: number;
+};

package/dist/docx/shared/shading.d.ts

@@ -0,0 +1,2 @@
+import { Shading } from '../../doc/types';
+export declare function readShading(parent: Element): Shading | undefined;

package/dist/docx/shared/units.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OOXML unit conversions. Word mixes several units throughout the spec:
+ * - **Half-points** (`w:sz`, `w:szCs`) — divide by 2 to get pt.
+ * - **Twentieths of a point** aka "twips" (`w:spacing`, page margins in
+ *   `w:pgMar`) — divide by 20 to get pt, by 567 to get mm.
+ * - **EMU** (English Metric Units, `wp:extent`) — 914400 per inch,
+ *   360000 per cm.
+ * - **Half-points via `w:line` for line spacing** — when `w:lineRule="auto"`,
+ *   the value is twentieths-of-a-point multiplied by a factor: 240 twips
+ *   = single-spacing.
+ *
+ * One file, one place to get them wrong or right.
+ */
+/** Half-point integer → floating-point pt. */
+export declare const halfPtToPt: (n: number) => number;
+/** Floating-point pt → rounded half-point integer. */
+export declare const ptToHalfPt: (pt: number) => number;
+/** EMU → CSS px (assuming 96 DPI). */
+export declare const emuToPx: (emu: number) => number;
+/** CSS px → EMU. */
+export declare const pxToEmu: (px: number) => number;
+/** Twips → mm. */
+export declare const twipsToMm: (t: number) => number;
+/** mm → twips. */
+export declare const mmToTwips: (mm: number) => number;
+/** Twips → pt. */
+export declare const twipsToPt: (t: number) => number;
+/** pt → twips. */
+export declare const ptToTwips: (pt: number) => number;
+/**
+ * `w:line` for line spacing in "auto" mode: 240 twips = single-spacing.
+ * So `line-height: 1.5` → `240 * 1.5 = 360`.
+ */
+export declare const lineHeightToOoxml: (lineHeight: number) => number;
+export declare const ooxmlLineHeightToCss: (line: number) => number;

package/dist/docx/shared/xml.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Thin wrappers around the browser's `DOMParser` and `XMLSerializer`.
+ * Pure functions; keep anything stateful (caches, registries) out of this
+ * file. One helper per concern so call sites stay readable.
+ */
+export declare function parseXml(src: string): Document;
+export declare function serializeXml(node: Node): string;
+/** Get the first descendant element in the WordprocessingML namespace. */
+export declare function wFirst(root: Document | Element, localName: string): Element | null;
+/** Get all descendants in the WordprocessingML namespace. */
+export declare function wAll(root: Document | Element, localName: string): Element[];
+/** Get direct-child elements in the WordprocessingML namespace. */
+export declare function wChildren(parent: Element, localName: string): Element[];
+/**
+ * Read a `w:val` attribute, Word's standard way of carrying a single value.
+ * Accepts either namespaced or non-namespaced attribute lookup since
+ * serialised documents differ.
+ */
+export declare function wVal(el: Element | null): string | null;
+/** Build an XML declaration header + root element. Used by the exporter. */
+export declare function xmlDocument(rootXml: string): string;
+/**
+ * Emit a single element as a string. Attributes are rendered in insertion
+ * order; children are pre-serialized strings. Prefers a tiny, composable
+ * string builder over a virtual DOM — the OOXML shapes we emit are flat
+ * enough that this is clearer than juggling `document.createElementNS`.
+ */
+export declare function el(tag: string, attrs?: Record<string, string | number | undefined> | null, children?: string[] | string | null): string;
+export declare function escapeXmlText(s: string): string;

package/dist/docx/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Lightweight OOXML-flavoured types used by the DOCX importer/exporter.
+ *
+ * These are NOT a general OOXML model — they carry only the fields we
+ * actually care about. Anything unknown is dropped (and logged to the
+ * warnings channel by the caller).
+ */
+/** Result of an `importDocx()` call — the SobreeDocument plus any warnings. */
+export interface DocxImportResult {
+    document: import('../doc/types').SobreeDocument;
+    warnings: string[];
+}
+/** Result of an `exportDocx()` call. */
+export interface DocxExportResult {
+    blob: Blob;
+    bytes: Uint8Array;
+    warnings: string[];
+}
+/** A single inline run's formatting flags — what `<w:rPr>` tells us. */
+export interface RunFormat {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    /** `<w:caps/>` — render the run with `text-transform: uppercase`. */
+    caps?: boolean;
+    /** CSS-ready `#rrggbb`. */
+    color?: string;
+    /** Highlight colour name or CSS-ready `#rrggbb`. */
+    highlight?: string;
+    /** CSS-ready `font-family` value. */
+    fontFamily?: string;
+    /** Size in pt. */
+    fontSizePt?: number;
+    verticalAlign?: "subscript" | "superscript";
+    /**
+     * `<w:rPrChange>` — a snapshot of the run's properties before the
+     * most recent tracked format edit. The inner `<w:rPr>` is parsed
+     * into the same `RunFormat` shape (recursion-free: the snapshot
+     * itself doesn't carry an `revisionFormat`).
+     */
+    revisionFormat?: {
+        before: RunFormat;
+        author?: string;
+        date?: string;
+    };
+}
+/** Paragraph-level formatting — from `<w:pPr>`. */
+export interface ParagraphFormat {
+    /** 1..6 if the paragraph carries a `Heading{N}` style; 0 otherwise. */
+    headingLevel?: number;
+    /** Verbatim `w:pStyle` value (`ListParagraph`, `BodyText`, …). Carries
+     *  the cascade anchor for non-heading paragraphs — without it, the
+     *  renderer falls back to Normal and any style-defined spacing /
+     *  indent / font is lost. */
+    styleId?: string;
+    alignment?: "left" | "center" | "right" | "justify";
+    /** Parsed `w:line` / `w:lineRule` into a CSS `line-height` multiplier. */
+    lineHeight?: number;
+    /** Explicit `<w:spacing w:after>` in twips. Stored as-is (including
+     *  0) so the value overrides cascaded defaults. */
+    spacingAfterTwips?: number;
+    /** Explicit `<w:spacing w:before>` in twips. */
+    spacingBeforeTwips?: number;
+    /** Raw numbering reference (`numId`, `ilvl`) if this para is part of a list. */
+    numId?: number;
+    numLevel?: number;
+    /** Paragraph indentation (`<w:ind w:left/right/firstLine/hanging>`). */
+    indent?: import('../doc/types').ParagraphIndent;
+    /** Custom tab stops from `<w:pPr><w:tabs>` — positions in twips,
+     *  alignment ("left" / "center" / "right" / "decimal"), and optional
+     *  leader (dots / dashes / etc.). Translated to CSS by the renderer. */
+    tabStops?: {
+        positionTwips: number;
+        alignment: string;
+        leader?: string;
+    }[];
+    /** Font properties of the paragraph mark itself, from
+     *  `<w:pPr><w:rPr>`. Used by the renderer to size the paragraph's
+     *  line height when there are no inline runs to provide a font. */
+    markFormat?: {
+        fontFamily?: string;
+        fontSizePt?: number;
+    };
+    /** Paragraph background colour (`<w:shd w:fill="…">`). */
+    shading?: import('../doc/types').Shading;
+    /** Paragraph borders (`<w:pBdr>` — top / bottom / left / right /
+     *  between). Used for inline rules like the dotted divider Word
+     *  draws beneath the page-header text on complex-multipage.docx. */
+    borders?: import('../doc/types').ParagraphProperties["borders"];
+    /**
+     * Paragraph-mark revision (`<w:pPr><w:rPr><w:ins/></w:rPr></w:pPr>`).
+     * Semantically: the paragraph break that *precedes* this paragraph
+     * is a tracked change. See `ParagraphProperties.revision` for the
+     * accept/reject contract.
+     */
+    revision?: import('../doc/types').RevisionMark;
+}