@qvac/harness 1.0.0-rc.0 → 1.0.0-rc.2

package/dist-lib/lib/office/engine/docx/index.d.ts

@@ -0,0 +1,7 @@
+import { Document } from './document.ts';
+import type { OpenOptions } from '../opc/package.ts';
+import type { CreateOptions } from './template.ts';
+export { Document } from './document.ts';
+export type * from './document.ts';
+export declare function open(bytes: Uint8Array | ArrayBuffer, opts?: OpenOptions): Document;
+export declare function create(opts?: CreateOptions): Document;

package/dist-lib/lib/office/engine/docx/index.js

@@ -0,0 +1,8 @@
+import { Document } from './document.js';
+export { Document } from './document.js';
+export function open(bytes, opts) {
+    return Document.open(bytes, opts);
+}
+export function create(opts) {
+    return Document.create(opts);
+}

package/dist-lib/lib/office/engine/docx/styles.d.ts

@@ -0,0 +1,31 @@
+import type { Document, Element } from '../xml.ts';
+import type { Package } from '../opc/package.ts';
+export interface StyleInfo {
+    el: Element;
+    id: string;
+    type: string;
+    name: string;
+    isDefault: boolean;
+    basedOn: string | null;
+}
+export interface FormattedStyle {
+    style: string;
+}
+export declare class Styles {
+    package: Package;
+    part: string | null;
+    constructor(pkg: Package, part: string | null);
+    get doc(): Document | null;
+    all(): StyleInfo[];
+    names(type?: string): string[];
+    byId(id: string | null): StyleInfo | null;
+    resolve(ref: unknown, type?: string): StyleInfo | null;
+    require(ref: unknown, type?: string): StyleInfo;
+    defaultParagraph(): StyleInfo | null;
+    nameOf(styleId: string | null): string;
+    headingLevel(styleId: string | null): number | null;
+    numIdOf(styleId: string | null): string | null;
+    isList(styleId: string | null): boolean;
+    format(ref: unknown, input: unknown): FormattedStyle;
+    private chain;
+}

package/dist-lib/lib/office/engine/docx/styles.js

@@ -0,0 +1,173 @@
+import * as xml from '../xml.js';
+import * as text from './text.js';
+import { DocsError } from '../errors.js';
+const W = xml.ns.w;
+const STYLE_ORDER = [
+    'name',
+    'aliases',
+    'basedOn',
+    'next',
+    'link',
+    'autoRedefine',
+    'hidden',
+    'uiPriority',
+    'semiHidden',
+    'unhideWhenUsed',
+    'qFormat',
+    'locked',
+    'personal',
+    'personalCompose',
+    'personalReply',
+    'rsid',
+    'pPr',
+    'rPr',
+    'tblPr',
+    'trPr',
+    'tcPr',
+    'tblStylePr'
+];
+function displayName(name) {
+    if (name !== name.toLowerCase())
+        return name;
+    return name.replace(/(^|\s)\S/g, (c) => c.toUpperCase());
+}
+function wVal(el) {
+    return el ? el.getAttributeNS(W, 'val') : null;
+}
+export class Styles {
+    package;
+    part;
+    constructor(pkg, part) {
+        this.package = pkg;
+        this.part = part;
+    }
+    get doc() {
+        return this.part ? this.package.xml(this.part) : null;
+    }
+    all() {
+        const doc = this.doc;
+        if (!doc) {
+            return [];
+        }
+        return xml.children(xml.root(doc), W, 'style').map((el) => {
+            const id = text.wGet(el, 'styleId');
+            const name = wVal(xml.child(el, W, 'name')) || id;
+            return {
+                el,
+                id,
+                type: text.wGet(el, 'type') || 'paragraph',
+                name: displayName(name),
+                isDefault: ['1', 'true', 'on'].includes(text.wGet(el, 'default')),
+                basedOn: wVal(xml.child(el, W, 'basedOn'))
+            };
+        });
+    }
+    names(type = 'paragraph') {
+        return this.all()
+            .filter((s) => s.type === type)
+            .map((s) => s.name);
+    }
+    byId(id) {
+        return this.all().find((s) => s.id === id) ?? null;
+    }
+    resolve(ref, type = 'paragraph') {
+        const wanted = String(ref).toLowerCase();
+        const styles = this.all().filter((s) => s.type === type);
+        return (styles.find((s) => s.id === ref) ??
+            styles.find((s) => s.name.toLowerCase() === wanted) ??
+            styles.find((s) => s.id.toLowerCase() === wanted.replace(/\s+/g, '')) ??
+            null);
+    }
+    require(ref, type = 'paragraph') {
+        const style = this.resolve(ref, type);
+        if (!style) {
+            const names = this.names(type).map((n) => `"${n}"`);
+            throw new DocsError('STYLE_NOT_FOUND', `the document has no ${type} style "${String(ref)}"; it has ${names.join(', ') || 'none'}`);
+        }
+        return style;
+    }
+    defaultParagraph() {
+        return this.all().find((s) => s.type === 'paragraph' && s.isDefault) ?? null;
+    }
+    nameOf(styleId) {
+        const style = styleId ? this.byId(styleId) : this.defaultParagraph();
+        if (style) {
+            return style.name;
+        }
+        return styleId || 'Normal';
+    }
+    headingLevel(styleId) {
+        let style = styleId ? this.byId(styleId) : this.defaultParagraph();
+        const seen = new Set();
+        while (style && !seen.has(style.id)) {
+            seen.add(style.id);
+            const level = ownHeadingLevel(style);
+            if (level !== null) {
+                return level;
+            }
+            style = style.basedOn ? this.byId(style.basedOn) : null;
+        }
+        return null;
+    }
+    numIdOf(styleId) {
+        for (const style of this.chain(styleId)) {
+            const pPr = xml.child(style.el, W, 'pPr');
+            const numPr = pPr ? xml.child(pPr, W, 'numPr') : null;
+            const numId = numPr ? wVal(xml.child(numPr, W, 'numId')) : null;
+            if (numId) {
+                return numId;
+            }
+        }
+        return null;
+    }
+    isList(styleId) {
+        const numId = this.numIdOf(styleId);
+        return numId !== null && numId !== '0';
+    }
+    format(ref, input) {
+        const format = text.validateFormat(input);
+        const style = this.require(ref);
+        const doc = xml.owner(style.el);
+        const { align, ...run } = format;
+        if (Object.keys(run).length) {
+            const rPr = xml.child(style.el, W, 'rPr') ??
+                xml.insertOrdered(style.el, text.wEl(doc, 'rPr'), STYLE_ORDER);
+            text.applyRunFormat(rPr, run);
+        }
+        if (align) {
+            const pPr = xml.child(style.el, W, 'pPr') ??
+                xml.insertOrdered(style.el, text.wEl(doc, 'pPr'), STYLE_ORDER);
+            text.wAttr(text.ensure(pPr, 'jc', text.PARAGRAPH_ORDER), 'val', text.ALIGNMENTS[align]);
+        }
+        if (this.part) {
+            this.package.touch(this.part);
+        }
+        return { style: style.name };
+    }
+    chain(styleId) {
+        const out = [];
+        const seen = new Set();
+        let style = styleId ? this.byId(styleId) : null;
+        while (style && !seen.has(style.id)) {
+            seen.add(style.id);
+            out.push(style);
+            style = style.basedOn ? this.byId(style.basedOn) : null;
+        }
+        return out;
+    }
+}
+function ownHeadingLevel(style) {
+    const match = /^heading ([1-9])$/i.exec(style.name);
+    if (match) {
+        return Number(match[1]);
+    }
+    if (style.name.toLowerCase() === 'title') {
+        return 0;
+    }
+    const pPr = xml.child(style.el, W, 'pPr');
+    const outline = pPr ? wVal(xml.child(pPr, W, 'outlineLvl')) : null;
+    if (outline !== null && outline !== '' && Number(outline) < 9) {
+        return Number(outline) + 1;
+    }
+    return null;
+}

package/dist-lib/lib/office/engine/docx/template.d.ts

@@ -0,0 +1,18 @@
+import type { Package } from '../opc/package.ts';
+export interface Fonts {
+    heading: string;
+    body: string;
+}
+export interface CreateOptions {
+    title?: string;
+    page?: 'letter' | 'a4';
+    size?: number;
+    fonts?: Partial<Fonts>;
+}
+interface Page {
+    width: number;
+    height: number;
+}
+export declare const PAGES: Record<string, Page>;
+export declare function build(pkg: Package, input?: unknown): void;
+export {};

package/dist-lib/lib/office/engine/docx/template.js

@@ -0,0 +1,133 @@
+import * as xml from '../xml.js';
+import { DocsError } from '../errors.js';
+import { isRecord } from '../../../guards.js';
+const W = xml.ns.w;
+const R = xml.ns.r;
+const REL_BASE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/';
+const WML = 'application/vnd.openxmlformats-officedocument.wordprocessingml.';
+const TYPES = {
+    document: WML + 'document.main+xml',
+    styles: WML + 'styles+xml',
+    numbering: WML + 'numbering+xml',
+    settings: WML + 'settings+xml',
+    core: 'application/vnd.openxmlformats-package.core-properties+xml',
+    app: 'application/vnd.openxmlformats-officedocument.extended-properties+xml'
+};
+export const PAGES = {
+    letter: { width: 12240, height: 15840 },
+    a4: { width: 11906, height: 16838 }
+};
+const BULLETS = ['\u2022', 'o', '\u25AA'];
+const BULLET_FONTS = [null, 'Courier New', 'Wingdings'];
+const NUMBER_FORMATS = ['decimal', 'lowerLetter', 'lowerRoman'];
+function escape(value) {
+    return String(value)
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+function fontsOf(input) {
+    const fonts = { heading: 'Calibri Light', body: 'Calibri' };
+    if (isRecord(input)) {
+        Object.assign(fonts, input);
+    }
+    for (const [key, value] of Object.entries(fonts)) {
+        if (!['heading', 'body'].includes(key)) {
+            throw new DocsError('INVALID_OPTIONS', `unknown font "${key}"; use heading or body`);
+        }
+        if (typeof value !== 'string' || !value.trim()) {
+            throw new DocsError('INVALID_OPTIONS', `font ${key} must be a typeface name`);
+        }
+    }
+    return { heading: String(fonts.heading), body: String(fonts.body) };
+}
+function options(opts) {
+    const page = PAGES[String(opts.page || 'letter').toLowerCase()];
+    if (!page) {
+        throw new DocsError('INVALID_OPTIONS', 'page must be "letter" or "a4"');
+    }
+    const fonts = fontsOf(opts.fonts);
+    const size = opts.size === undefined ? 11 : opts.size;
+    if (!(typeof size === 'number' && size >= 6 && size <= 72)) {
+        throw new DocsError('INVALID_OPTIONS', `size is the body text size in points, from 6 to 72, got ${String(size)}`);
+    }
+    return { page, fonts, size, title: opts.title };
+}
+function fontsXml(face) {
+    const f = escape(face);
+    return `<w:rFonts w:ascii="${f}" w:hAnsi="${f}" w:eastAsia="${f}" w:cs="${f}"/>`;
+}
+function heading(style) {
+    const { id, name, level, size, color, before } = style;
+    return `<w:style w:type="paragraph" w:styleId="${id}"><w:name w:val="${name}"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:uiPriority w:val="9"/><w:qFormat/><w:pPr><w:keepNext/><w:keepLines/><w:spacing w:before="${before}" w:after="0"/><w:outlineLvl w:val="${level}"/></w:pPr><w:rPr>{heading}<w:color w:val="${color}"/><w:sz w:val="${size}"/><w:szCs w:val="${size}"/></w:rPr></w:style>`;
+}
+function stylesXml(fonts, size) {
+    const half = Math.round(size * 2);
+    const body = fontsXml(fonts.body);
+    const head = fontsXml(fonts.heading);
+    const styles = [
+        `<w:docDefaults><w:rPrDefault><w:rPr>${body}<w:sz w:val="${half}"/><w:szCs w:val="${half}"/><w:lang w:val="en-US"/></w:rPr></w:rPrDefault><w:pPrDefault><w:pPr><w:spacing w:after="160" w:line="259" w:lineRule="auto"/></w:pPr></w:pPrDefault></w:docDefaults>`,
+        '<w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/><w:qFormat/></w:style>',
+        '<w:style w:type="character" w:default="1" w:styleId="DefaultParagraphFont"><w:name w:val="Default Paragraph Font"/><w:uiPriority w:val="1"/><w:semiHidden/><w:unhideWhenUsed/></w:style>',
+        '<w:style w:type="table" w:default="1" w:styleId="TableNormal"><w:name w:val="Normal Table"/><w:uiPriority w:val="99"/><w:semiHidden/><w:unhideWhenUsed/><w:tblPr><w:tblInd w:w="0" w:type="dxa"/><w:tblCellMar><w:top w:w="0" w:type="dxa"/><w:left w:w="108" w:type="dxa"/><w:bottom w:w="0" w:type="dxa"/><w:right w:w="108" w:type="dxa"/></w:tblCellMar></w:tblPr></w:style>',
+        '<w:style w:type="numbering" w:default="1" w:styleId="NoList"><w:name w:val="No List"/><w:uiPriority w:val="99"/><w:semiHidden/><w:unhideWhenUsed/></w:style>',
+        `<w:style w:type="paragraph" w:styleId="Title"><w:name w:val="Title"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:uiPriority w:val="10"/><w:qFormat/><w:pPr><w:spacing w:after="0" w:line="240" w:lineRule="auto"/><w:contextualSpacing/></w:pPr><w:rPr>${head}<w:kern w:val="28"/><w:sz w:val="56"/><w:szCs w:val="56"/></w:rPr></w:style>`,
+        `<w:style w:type="paragraph" w:styleId="Subtitle"><w:name w:val="Subtitle"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:uiPriority w:val="11"/><w:qFormat/><w:rPr><w:color w:val="5A5A5A"/><w:spacing w:val="15"/><w:sz w:val="${half + 6}"/><w:szCs w:val="${half + 6}"/></w:rPr></w:style>`,
+        heading({
+            id: 'Heading1',
+            name: 'heading 1',
+            level: 0,
+            size: 32,
+            color: '2F5496',
+            before: 240
+        }),
+        heading({ id: 'Heading2', name: 'heading 2', level: 1, size: 26, color: '2F5496', before: 40 }),
+        heading({ id: 'Heading3', name: 'heading 3', level: 2, size: 24, color: '1F3763', before: 40 }),
+        '<w:style w:type="paragraph" w:styleId="ListBullet"><w:name w:val="List Bullet"/><w:basedOn w:val="Normal"/><w:uiPriority w:val="99"/><w:unhideWhenUsed/><w:qFormat/><w:pPr><w:numPr><w:numId w:val="1"/></w:numPr><w:contextualSpacing/></w:pPr></w:style>',
+        '<w:style w:type="paragraph" w:styleId="ListNumber"><w:name w:val="List Number"/><w:basedOn w:val="Normal"/><w:uiPriority w:val="99"/><w:unhideWhenUsed/><w:qFormat/><w:pPr><w:numPr><w:numId w:val="2"/></w:numPr><w:contextualSpacing/></w:pPr></w:style>',
+        '<w:style w:type="paragraph" w:styleId="Quote"><w:name w:val="Quote"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:uiPriority w:val="29"/><w:qFormat/><w:pPr><w:spacing w:before="200"/><w:ind w:left="864" w:right="864"/><w:jc w:val="center"/></w:pPr><w:rPr><w:i/><w:iCs/><w:color w:val="404040"/></w:rPr></w:style>',
+        '<w:style w:type="table" w:styleId="TableGrid"><w:name w:val="Table Grid"/><w:basedOn w:val="TableNormal"/><w:uiPriority w:val="39"/><w:pPr><w:spacing w:after="0" w:line="240" w:lineRule="auto"/></w:pPr><w:tblPr><w:tblBorders><w:top w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:left w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:bottom w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:right w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:insideH w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:insideV w:val="single" w:sz="4" w:space="0" w:color="auto"/></w:tblBorders></w:tblPr></w:style>'
+    ];
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w:styles xmlns:w="${W}">${styles.join('').replace(/\{heading\}/g, head)}</w:styles>`;
+}
+function levelXml(level) {
+    const font = level.font
+        ? `<w:rPr><w:rFonts w:ascii="${level.font}" w:hAnsi="${level.font}" w:hint="default"/></w:rPr>`
+        : '';
+    return `<w:lvl w:ilvl="${level.ilvl}"><w:start w:val="1"/><w:numFmt w:val="${level.format}"/><w:lvlText w:val="${level.text}"/><w:lvlJc w:val="left"/><w:pPr><w:ind w:left="${360 + 360 * level.ilvl}" w:hanging="360"/></w:pPr>${font}</w:lvl>`;
+}
+function numberingXml() {
+    const nine = Array.from({ length: 9 }, (_, i) => i);
+    const bulletLevels = nine
+        .map((i) => levelXml({ ilvl: i, format: 'bullet', text: BULLETS[i % 3], font: BULLET_FONTS[i % 3] }))
+        .join('');
+    const numberLevels = nine
+        .map((i) => levelXml({ ilvl: i, format: NUMBER_FORMATS[i % 3], text: `%${i + 1}.`, font: null }))
+        .join('');
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w:numbering xmlns:w="${W}"><w:abstractNum w:abstractNumId="0"><w:multiLevelType w:val="hybridMultilevel"/>${bulletLevels}</w:abstractNum><w:abstractNum w:abstractNumId="1"><w:multiLevelType w:val="hybridMultilevel"/>${numberLevels}</w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num><w:num w:numId="2"><w:abstractNumId w:val="1"/></w:num></w:numbering>`;
+}
+function documentXml(page) {
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w:document xmlns:w="${W}" xmlns:r="${R}" xmlns:wp="${xml.ns.wp}" xmlns:a="${xml.ns.a}" xmlns:pic="${xml.ns.pic}"><w:body><w:p/><w:sectPr><w:pgSz w:w="${page.width}" w:h="${page.height}"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720" w:gutter="0"/><w:cols w:space="720"/></w:sectPr></w:body></w:document>`;
+}
+function addProperties(pkg, title) {
+    const heading = title ? `<dc:title>${escape(title)}</dc:title>` : '';
+    pkg.add('/docProps/core.xml', xml.parse(`<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/">${heading}</cp:coreProperties>`), TYPES.core);
+    pkg.add('/docProps/app.xml', xml.parse('<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties"><Application>QVAC</Application></Properties>'), TYPES.app);
+    const rels = pkg.rels('/');
+    rels.add(REL_BASE + 'officeDocument', '/word/document.xml');
+    rels.add('http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties', '/docProps/core.xml');
+    rels.add(REL_BASE + 'extended-properties', '/docProps/app.xml');
+}
+export function build(pkg, input = {}) {
+    const { page, fonts, size, title } = options(isRecord(input) ? input : {});
+    pkg.add('/word/document.xml', xml.parse(documentXml(page)), TYPES.document);
+    pkg.add('/word/styles.xml', xml.parse(stylesXml(fonts, size)), TYPES.styles);
+    pkg.add('/word/numbering.xml', xml.parse(numberingXml()), TYPES.numbering);
+    pkg.add('/word/settings.xml', xml.parse(`<w:settings xmlns:w="${W}"><w:defaultTabStop w:val="720"/><w:characterSpacingControl w:val="doNotCompress"/><w:compat><w:compatSetting w:name="compatibilityMode" w:uri="http://schemas.microsoft.com/office/word" w:val="15"/></w:compat></w:settings>`), TYPES.settings);
+    const main = pkg.rels('/word/document.xml');
+    main.add(REL_BASE + 'styles', '/word/styles.xml');
+    main.add(REL_BASE + 'numbering', '/word/numbering.xml');
+    main.add(REL_BASE + 'settings', '/word/settings.xml');
+    addProperties(pkg, title);
+}

package/dist-lib/lib/office/engine/docx/text.d.ts

@@ -0,0 +1,55 @@
+import type { Document, Element } from '../xml.ts';
+export type Alignment = 'left' | 'center' | 'right' | 'justify';
+export interface RunFormat {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    size?: number;
+    color?: string;
+    font?: string;
+}
+export interface Format extends RunFormat {
+    align?: Alignment;
+}
+export interface Run extends RunFormat {
+    text: string;
+}
+export interface ParagraphSpec {
+    text?: string;
+    runs?: (string | Run)[];
+    style?: string;
+    styleId?: string;
+    align?: Alignment;
+    pageBreak?: boolean;
+    level?: number;
+}
+export interface Removed {
+    hyperlinks?: number;
+    images?: number;
+    fields?: number;
+    contentControls?: number;
+    equations?: number;
+    objects?: number;
+    breaks?: number;
+}
+export type WAttributes = Record<string, string | number | undefined | null>;
+export declare const W: "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+export declare const RUN_ORDER: string[];
+export declare const PARAGRAPH_ORDER: string[];
+export declare const ALIGNMENTS: Record<Alignment, string>;
+export declare const FORMAT_KEYS: readonly string[];
+export declare const RUN_KEYS: readonly string[];
+export declare function wGet(el: Element | null, name: string): string;
+export declare function paragraphText(el: Element): string;
+export declare function blockText(el: Element): string;
+export declare function hasPageBreak(p: Element): boolean;
+export declare function wAttr(el: Element, name: string, value: string | number): void;
+export declare function wEl(doc: Document, local: string, attributes?: WAttributes): Element;
+export declare function validateFormat(format: unknown, known?: readonly string[]): Format;
+export declare function applyRunFormat(rPr: Element, format: RunFormat): void;
+export declare function ensure(parent: Element, local: string, order?: readonly string[]): Element;
+export declare function setAlign(p: Element, align: Alignment): void;
+export declare function normalizeRuns(input: unknown): Run[];
+export declare function assertUntracked(p: Element, where: string): void;
+export declare function replaceContent(p: Element, input: unknown): Removed;
+export declare function buildParagraph(doc: Document, input: unknown, template: Element | null): Element;