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

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

@@ -27,18 +27,23 @@ export function expectedTagProblems(tags: TagInfo[], expectedTags: readonly stri
  * @returns {Problem[]}
  */
 export function multilineProblems(tags: TagInfo[], multiline: readonly string[]): Problem[];
+/**
+ * @typedef {object} ReadOptions
+ * @property {string[] | undefined} expectedTags
+ * @property {string[] | undefined} multiline
+ * @property {Record<string, unknown>} given  the options object as passed ({} when undefined), for keys a caller adds
+ * @property {Problem[]} problems
+ */
 /**
  * Validates the options object: `expectedTags` and `multiline`, each an
- * array of strings.
+ * array of strings, plus whatever other keys the caller accepts (checkFit's
+ * `capacity`, which it reads itself); any other key is UNKNOWN_OPTION.
  * @param {string} where
  * @param {unknown} options
- * @returns {{expectedTags: string[] | undefined, multiline: string[] | undefined, problems: Problem[]}}
+ * @param {readonly string[]} [accepted]
+ * @returns {ReadOptions}
  */
-export function readOptions(where: string, options: unknown): {
-    expectedTags: string[] | undefined;
-    multiline: string[] | undefined;
-    problems: Problem[];
-};
+export function readOptions(where: string, options: unknown, accepted?: readonly string[]): ReadOptions;
 /**
  * Reads the filled output back. Throws a plain Error — a failure here is a
  * bug in the engine, never in the template or the data. Exported for its own
@@ -69,6 +74,47 @@ export function fillDocumentXml(xmlBytes: Uint8Array, data: FillData, options?:
     xml: Uint8Array;
     report: FillReport;
 };
+/**
+ * @typedef {object} PreparedFill  everything a fill decides before it writes a byte
+ * @property {Record<string, unknown>} record  the data
+ * @property {import("./slots.js").ScanResult} scan
+ * @property {TagInfo[]} tags
+ * @property {Set<string>} multilineSet
+ * @property {Map<string, string>} valueOf  tag -> value as written ("" for null)
+ * @property {string[]} empty  tags with an empty value, in document order
+ * @property {string[]} order  tag names in document order of their first occurrence
+ * @property {Problem[]} warnings
+ * @property {ReadOptions} options
+ */
+/**
+ * Every check a fill makes before writing: the data's shape, the template's
+ * problems, the options', the expected tag set's, each value's. Throws ONE
+ * TemplateError (named for `where`) with all of them. fillTemplate and
+ * checkFit both go through here, so they refuse exactly the same inputs
+ * (ADR-0042 Karar 2).
+ * @param {string} where  the public function's name
+ * @param {import("./xml-scan.js").XmlElement} root
+ * @param {Uint8Array} xmlBytes
+ * @param {unknown} data
+ * @param {unknown} rawOptions
+ * @param {Problem[]} extraProblems  the package layer's other-part findings
+ * @param {readonly string[]} [accepted]  option keys the caller accepts (readOptions)
+ * @param {(options: ReadOptions) => Problem[]} [ownOptionProblems]  the caller's check of its own keys, run
+ *   right after the shared ones so its problems join the same TemplateError
+ * @returns {PreparedFill}
+ */
+export function prepareFill(where: string, root: import("./xml-scan.js").XmlElement, xmlBytes: Uint8Array, data: unknown, rawOptions: unknown, extraProblems: Problem[], accepted?: readonly string[], ownOptionProblems?: (options: ReadOptions) => Problem[]): PreparedFill;
+/**
+ * Reads the package: word/document.xml parsed, and every other XML part
+ * checked for braces (ADR-0037 Karar 6 — the engine fills only the main
+ * document, so a tag anywhere else would ship unfilled). An unreadable zip
+ * or XML part is PACKAGE_UNREADABLE.
+ * @param {string} where
+ * @param {unknown} bytes
+ * @param {readonly string[]} [keep]  part names whose inflated bytes the caller needs (checkFit: styles, settings, theme)
+ * @returns {Promise<TemplatePackage>}
+ */
+export function readTemplatePackage(where: string, bytes: unknown, keep?: readonly string[]): Promise<TemplatePackage>;
 /**
  * What a template holds: its tags with their boxes and pages, every problem
  * that would stop a fill, and the warnings. Template problems are reported,
@@ -114,7 +160,7 @@ export function fillTemplate(bytes: Uint8Array, data: FillData, options?: FillOp
     report: FillReport;
 }>;
 /** The package version this engine ships in; a test holds it equal to package.json. */
-export const ENGINE_VERSION: "0.2.0-alpha";
+export const ENGINE_VERSION: "0.3.0-alpha";
 /**
  * @typedef {import("./slots.js").TemplateProblem & {index?: number, codePoint?: number, count?: number, type?: string}} Problem
  */
@@ -162,6 +208,41 @@ export class TemplateError extends Error {
     /** @type {Problem[]} */
     problems: Problem[];
 }
+export type ReadOptions = {
+    expectedTags: string[] | undefined;
+    multiline: string[] | undefined;
+    /**
+     * the options object as passed ({} when undefined), for keys a caller adds
+     */
+    given: Record<string, unknown>;
+    problems: Problem[];
+};
+/**
+ * everything a fill decides before it writes a byte
+ */
+export type PreparedFill = {
+    /**
+     * the data
+     */
+    record: Record<string, unknown>;
+    scan: import("./slots.js").ScanResult;
+    tags: TagInfo[];
+    multilineSet: Set<string>;
+    /**
+     * tag -> value as written ("" for null)
+     */
+    valueOf: Map<string, string>;
+    /**
+     * tags with an empty value, in document order
+     */
+    empty: string[];
+    /**
+     * tag names in document order of their first occurrence
+     */
+    order: string[];
+    warnings: Problem[];
+    options: ReadOptions;
+};
 export type TemplatePackage = {
     entries: import("./zip-container.js").ZipEntry[];
     main: import("./zip-container.js").ZipEntry;
@@ -171,6 +252,10 @@ export type TemplatePackage = {
     xml: Uint8Array;
     root: import("./xml-scan.js").XmlElement;
     otherPartProblems: Problem[];
+    /**
+     * the inflated XML parts the caller asked to keep
+     */
+    parts: Map<string, Uint8Array>;
 };
 export type Problem = import("./slots.js").TemplateProblem & {
     index?: number;