@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/io/ooxml/fit.d.ts

@@ -0,0 +1,252 @@
+/**
+ * The width a scanned text box gives its text, or why it cannot be known.
+ * @param {import("./slots.js").AlternateContentRecord} ac  a box the slot scan accepted
+ * @returns {{box: BoxGeometry} | {unknown: Unknown}}
+ */
+export function boxGeometry(ac: import("./slots.js").AlternateContentRecord): {
+    box: BoxGeometry;
+} | {
+    unknown: Unknown;
+};
+/**
+ * @typedef {{cp: number, u: number, sp: number, tab?: true}} Item  a character, or a tab's jump to its stop
+ * @typedef {{lines: LineMeasure[], stops: number[]}} Laid  the lines, and the stop each tab reached (u)
+ * @typedef {{unknown: Unknown & {codePoint?: number}} | {overflow: {code: "TAB_STOP_PASSED"}}} NotLaid
+ */
+/**
+ * The lines a paragraph holds once its tags are filled, each measured: where it
+ * starts, where it must end, how wide it is (ADR-0042 Karar 5). A line ends at a
+ * w:br — the template's, or one a multi-line value's LF becomes. No break point is
+ * ever chosen (invariant #9): a line is measured whole, as the template and the
+ * values give it.
+ *
+ * A tab jumps to the first left stop past the pen, stops measured from the box's
+ * inner left edge (H6). The paragraph is laid out once with its tags empty: that
+ * fixes the stop each tab reaches. Filled, a tab whose text has passed that stop
+ * has broken the column the template aligned — an overflow, TAB_STOP_PASSED, even
+ * if the line itself still fits.
+ * @param {object} input
+ * @param {XmlElement} input.paragraph
+ * @param {BoxGeometry} input.box
+ * @param {ReturnType<typeof import("./run-fonts.js").layoutResolver>} input.layout
+ * @param {Map<XmlElement, string>} input.values  tag run -> the value written into it
+ * @param {boolean} [input.preserve]  every w:t inherits xml:space="preserve" (inheritsPreserve);
+ *   otherwise a template text with edge whitespace and no preserve of its own is unknown —
+ *   Word may drop that whitespace
+ * @returns {{lines: LineMeasure[]} | NotLaid}
+ */
+export function measureParagraph({ paragraph, box, layout, values, preserve }: {
+    paragraph: XmlElement;
+    box: BoxGeometry;
+    layout: ReturnType<typeof import("./run-fonts.js").layoutResolver>;
+    values: Map<XmlElement, string>;
+    preserve?: boolean | undefined;
+}): {
+    lines: LineMeasure[];
+} | NotLaid;
+/**
+ * @typedef {"fits" | "overflows" | "unknown" | "empty"} FitStatus
+ * @typedef {{status: "fits" | "overflows"} | {status: "unknown", reason: Unknown}} LineVerdict
+ * @typedef {object} FitOccurrence
+ * @property {number | null} docPrId
+ * @property {number} page
+ * @property {FitStatus} status
+ * @property {string} [reason]  from a closed list (ADR-0042)
+ * @property {string} [property]  the property or element the reason names
+ * @property {number} [codePoint]  the character the table lacks
+ * @property {number} [widthPt]  the tightest line's width
+ * @property {number} [availablePt]  the room it has
+ * @property {number} [marginPt]  room less width; negative when it overflows
+ * @property {number} [lines]  a multi-line value's line count
+ * @property {number} [capacity]
+ * @property {string[]} [paragraphTags]  the other tags measured on the same line
+ * @typedef {{name: string, status: FitStatus, occurrences: FitOccurrence[]}} FitTag
+ * @typedef {object} FitReport
+ * @property {boolean} ok  no occurrence overflows or is unknown — the caller's approval rule
+ * @property {FitTag[]} tags  sorted by name
+ * @property {{tags: number, occurrences: number, fits: number, overflows: number, unknown: number, empty: number}} counts
+ * @property {{version: string, metrics: {family: string, carlito: string | null, calibri: string | null}}} engine
+ */
+/**
+ * One line against its room: fits when even with its trailing spaces counted and τ more it would
+ * fit, overflows when even with them hanging and τ less it would not; between, unknown (ADR-0042
+ * Karar 6) — TRAILING_SPACE when the trailing spaces alone decide.
+ * @param {LineMeasure} line
+ * @returns {LineVerdict}
+ */
+export function decideLine(line: LineMeasure): LineVerdict;
+/**
+ * Whether every w:t of the document inherits xml:space="preserve": the root sets it and no element
+ * below sets anything else (Word writes the root's; all 46 corpus documents carry it).
+ * @param {XmlElement} root
+ * @returns {boolean}
+ */
+export function inheritsPreserve(root: XmlElement): boolean;
+/**
+ * Settings that change every line, or that the evidence does not cover: the compatibility mode
+ * (14 only), the w:compat options, East Asian punctuation compression, a character grid.
+ * @param {Uint8Array | undefined} settingsXml
+ * @param {XmlElement} documentRoot
+ * @returns {Unknown | null}
+ */
+export function documentUnknown(settingsXml: Uint8Array | undefined, documentRoot: XmlElement): Unknown | null;
+/**
+ * Whether each value of `data` stays on the lines its box gives it, as Word lays the filled
+ * template out (ADR-0042). Validates exactly as fillTemplate does — the same TemplateError for
+ * the same input — and writes nothing. The report carries no value: widths, reasons, code points.
+ * @param {Uint8Array} bytes  a .docx template
+ * @param {import("./fill.js").FillData} data
+ * @param {{expectedTags?: readonly string[], multiline?: readonly string[], capacity?: Record<string, number>}} [options]
+ *   `capacity`: tag -> lines, for multi-line tags only; a binding manifest carries it as `fit`
+ * @returns {Promise<FitReport>}
+ */
+export function checkFit(bytes: Uint8Array, data: import("./fill.js").FillData, options?: {
+    expectedTags?: readonly string[];
+    multiline?: readonly string[];
+    capacity?: Record<string, number>;
+}): Promise<FitReport>;
+/** DrawingML's default left and right inset (ECMA-376 §21.1.2.1.1 bodyPr: 91440 EMU, 0.1 in). */
+export const DEFAULT_INSET_EMU: 91440;
+/** u per EMU */
+export const U_PER_EMU: 2048;
+/** τ = 0.05 pt + 0.025 pt a glyph (ADR-0042 Karar 6), in u. */
+export const TAU_BASE_U: number;
+export const TAU_PER_GLYPH_U: number;
+/**
+ * a character, or a tab's jump to its stop
+ */
+export type Item = {
+    cp: number;
+    u: number;
+    sp: number;
+    tab?: true;
+};
+/**
+ * the lines, and the stop each tab reached (u)
+ */
+export type Laid = {
+    lines: LineMeasure[];
+    stops: number[];
+};
+export type NotLaid = {
+    unknown: Unknown & {
+        codePoint?: number;
+    };
+} | {
+    overflow: {
+        code: "TAB_STOP_PASSED";
+    };
+};
+export type FitStatus = "fits" | "overflows" | "unknown" | "empty";
+export type LineVerdict = {
+    status: "fits" | "overflows";
+} | {
+    status: "unknown";
+    reason: Unknown;
+};
+export type FitOccurrence = {
+    docPrId: number | null;
+    page: number;
+    status: FitStatus;
+    /**
+     * from a closed list (ADR-0042)
+     */
+    reason?: string | undefined;
+    /**
+     * the property or element the reason names
+     */
+    property?: string | undefined;
+    /**
+     * the character the table lacks
+     */
+    codePoint?: number | undefined;
+    /**
+     * the tightest line's width
+     */
+    widthPt?: number | undefined;
+    /**
+     * the room it has
+     */
+    availablePt?: number | undefined;
+    /**
+     * room less width; negative when it overflows
+     */
+    marginPt?: number | undefined;
+    /**
+     * a multi-line value's line count
+     */
+    lines?: number | undefined;
+    capacity?: number | undefined;
+    /**
+     * the other tags measured on the same line
+     */
+    paragraphTags?: string[] | undefined;
+};
+export type FitTag = {
+    name: string;
+    status: FitStatus;
+    occurrences: FitOccurrence[];
+};
+export type FitReport = {
+    /**
+     * no occurrence overflows or is unknown — the caller's approval rule
+     */
+    ok: boolean;
+    /**
+     * sorted by name
+     */
+    tags: FitTag[];
+    counts: {
+        tags: number;
+        occurrences: number;
+        fits: number;
+        overflows: number;
+        unknown: number;
+        empty: number;
+    };
+    engine: {
+        version: string;
+        metrics: {
+            family: string;
+            carlito: string | null;
+            calibri: string | null;
+        };
+    };
+};
+export type XmlElement = import("./xml-scan.js").XmlElement;
+export type Unknown = import("./run-fonts.js").Unknown;
+/**
+ * `textWidthEmu`: the width between the insets, where a paragraph's indents start
+ */
+export type BoxGeometry = {
+    widthEmu: number;
+    lInsEmu: number;
+    rInsEmu: number;
+    textWidthEmu: number;
+};
+/**
+ * one line of a filled paragraph
+ */
+export type LineMeasure = {
+    /**
+     * where it starts, from the box's inner left edge: the indents
+     */
+    startEmu: number;
+    /**
+     * where it must end: the text width less the right indent
+     */
+    limitEmu: number;
+    /**
+     * its natural width, every character counted — trailing spaces too (u = EMU × 2048)
+     */
+    widthU: number;
+    /**
+     * the same with the trailing spaces left out, as if Word hung them (H3)
+     */
+    widthWithoutTrailingU: number;
+    /**
+     * characters in `widthU` since its last exact place — the line start or a tab stop — whose
+     * deviations τ covers
+     */
+    glyphs: number;
+};