@docx4j/core-ts 0.3.2 → 0.5.0

package/README.md

@@ -43,10 +43,15 @@ const ooxml = await pkg.saveFlatOpc();              // pkg:package, for insertOo
 ```
 
 A part that is never touched is written back byte for byte; `getContents()` (or a view over
-it) marks a part for re-marshalling. `mc:AlternateContent` is resolved when a part is
-unmarshalled, as Word does on open (`{ mcePreprocess: false }` to keep it). Subpaths
+it) marks a part for re-marshalling. `mc:AlternateContent` is kept with every branch, as docx4j
+keeps it: the content API reads the branch Word would (the first `mc:Choice` whose namespaces are
+understood, else the `mc:Fallback`), an edit lands in every branch, and a save writes them all
+(`{ mcePreprocess: true }` resolves the element when a part is unmarshalled instead, as Word does on
+open). Subpaths
 `@docx4j/core-ts/opc`, `/parts`, `/packages` and `/model` give the layers separately,
-`/office-js` the `Word` shim (below), and `/node` the one Node-only piece (the unzipped-directory
+`/office-js` the `Word` shim (below), `/html` HTML to WordprocessingML (a converter to an
+intermediate form and a builder from it, CR-005 section 8; the HTML parser is yours, a browser's
+`DOMParser` by default), and `/node` the one Node-only piece (the unzipped-directory
 container; nothing else in the package imports a `node:` builtin, so a browser or add-in bundle
 never sees one).
 

package/dist/html/convert.d.mts

@@ -0,0 +1,116 @@
+/** The '#RRGGBB' of one of Word's sixteen highlight names, or undefined for anything else (`mso-highlight` is read through it). */
+export declare function highlightHexOf(name: string): string | undefined;
+/** The highlight name for one of the sixteen colours, by its '#RRGGBB'. */
+export declare function highlightNameOf(hex: string): string | undefined;
+/** A web or mail address a link may keep (`http`, `https`, `mailto`), trimmed; anything else undefined. */
+export declare function webAddress(url: string): string | undefined;
+export interface PasteRun {
+    text: string;
+    bold?: true;
+    italic?: true;
+    underline?: true;
+    strike?: true;
+    vertAlign?: 'superscript' | 'subscript';
+    /** The first family of `font-family`, when it is a name and not a generic. */
+    fontName?: string;
+    /** Points. */
+    fontSize?: number;
+    /** '#RRGGBB', or 'auto' for `windowtext`. */
+    color?: string;
+    /** '#RRGGBB' of one of Word's highlight names (`mso-highlight`, else a `background` naming one). */
+    highlight?: string;
+    /** A character style id of the document (Markdown's inline code, `HTMLCode`). */
+    style?: string;
+    /** A link's address (Markdown's links): a relationship made before the transaction, the text in Word's look. */
+    link?: string;
+}
+export type PasteInline = PasteRun | {
+    br: true;
+} | {
+    tab: true;
+};
+export interface PasteList {
+    /** Word's `lfoN`, or the list element's own key: one definition per key. */
+    key: string;
+    level: number;
+    bullet: boolean;
+}
+export interface PasteParagraph {
+    kind: 'paragraph';
+    /** A style id of the document, or null for the default. */
+    style: string | null;
+    list?: PasteList;
+    /** `w:jc` from `text-align` or the `align` attribute. */
+    jc?: string;
+    /** Twips from `margin-left`, `margin-right` and `text-indent` (a negative one a hanging indent). */
+    ind?: {
+        start?: number;
+        end?: number;
+        firstLine?: number;
+        hanging?: number;
+    };
+    /** Twips from `margin-top`; `margin-bottom` and `line-height` are dropped and counted. */
+    spacing?: {
+        before: number;
+    };
+    inlines: PasteInline[];
+}
+export interface PasteCell {
+    blocks: PasteBlock[];
+    colspan: number;
+    rowspan: number;
+    /** Twips, when the cell said. */
+    width?: number;
+}
+export interface PasteTable {
+    kind: 'table';
+    rows: PasteCell[][];
+    /** The document's table grid style, when it has one. */
+    style: string | null;
+    /** The first row repeated at the top of each page (`w:tblHeader`): a Markdown table's header row. */
+    headerRow?: boolean;
+}
+export type PasteBlock = PasteParagraph | PasteTable;
+export interface PasteReport {
+    paragraphs: number;
+    lists: number;
+    tables: number;
+    /** What was dropped, by kind, with how many times. */
+    dropped: Record<string, number>;
+    /** Built-in styles the paste names that the document lacked: a caller splices them in from the defaults (`styles.ensure`) before building, else the paragraphs stay plain. */
+    stylesWanted: string[];
+}
+export interface PasteResult {
+    blocks: PasteBlock[];
+    report: PasteReport;
+}
+/** What the converter asks of the document: its styles, by id and by name. */
+export interface StyleLookup {
+    /** The style id for a name (`heading 1`, `Title`), case-insensitively, or undefined. */
+    idFor(name: string): string | undefined;
+    hasId(id: string): boolean;
+}
+/** The lookup over the document's paragraph and character styles, plus the table style ids the caller found (the styles list carries no table styles). */
+/** A style's id and name, as a document's styles part lists them. */
+export interface StyleNaming {
+    id: string;
+    name: string;
+}
+export declare function styleLookupOf(entries: readonly StyleNaming[], tableStyleIds?: readonly string[]): StyleLookup;
+/** Word's `CF_HTML` header (`Version:`, `StartHTML:` and the rest) precedes `<html` in a saved capture; a browser hands the markup alone. */
+export declare function clipboardMarkup(text: string): string;
+/**
+ * True when the HTML is a terminal's screen (ED-005 section 12.67): inline content only, every
+ * piece of text in a monospace font, as Konsole's "Copy text as HTML" writes it (a span in
+ * `font-family:monospace` holding a coloured span per run and a `<br>` per line,
+ * `fixtures/paste/terminal/`). Its colours and font are the terminal's theme, not content, and the
+ * converter would make a paragraph of each span, so the paste takes the plain text instead.
+ */
+export declare function isTerminalHtml(html: string, options?: {
+    parser?: (html: string) => Document;
+}): boolean;
+/** Convert clipboard HTML to the intermediate form, keeping what the outline names and counting the rest. */
+export declare function convertHtml(html: string, lookup: StyleLookup, options?: {
+    parser?: (html: string) => Document;
+}): PasteResult;
+/** The list definitions a paste needs: a `w:numId` per list key. */