@qvac/harness 0.7.3 → 0.8.0

package/dist-lib/lib/office/engine/drawingml/text.js

@@ -0,0 +1,352 @@
+import * as xml from '../xml.js';
+import { DocsError } from '../errors.js';
+import { isRecord } from '../../../guards.js';
+const A = xml.ns.a;
+const STYLE_KEYS = ['size', 'bold', 'italic', 'underline', 'color', 'font', 'align'];
+const TOGGLES = ['bold', 'italic', 'underline'];
+const ALIGNMENTS = {
+    left: 'l',
+    center: 'ctr',
+    right: 'r',
+    justify: 'just'
+};
+const FILLS = ['noFill', 'solidFill', 'gradFill', 'blipFill', 'pattFill', 'grpFill'];
+const LINKS = ['hlinkClick', 'hlinkMouseOver'];
+const RUN_PROPERTY_ORDER = [
+    'ln',
+    'noFill',
+    'solidFill',
+    'gradFill',
+    'blipFill',
+    'pattFill',
+    'grpFill',
+    'effectLst',
+    'effectDag',
+    'highlight',
+    'uLnTx',
+    'uLn',
+    'uFillTx',
+    'uFill',
+    'latin',
+    'ea',
+    'cs',
+    'sym',
+    'hlinkClick',
+    'hlinkMouseOver',
+    'rtl',
+    'extLst'
+];
+function isAlignment(value) {
+    return typeof value === 'string' && value in ALIGNMENTS;
+}
+function paragraphText(p) {
+    let out = '';
+    for (const node of xml.children(p, A)) {
+        if (node.localName === 'r' || node.localName === 'fld') {
+            out += xml.text(xml.child(node, A, 't'));
+        }
+        else if (node.localName === 'br') {
+            out += '\n';
+        }
+    }
+    return out;
+}
+function paragraphLevel(p) {
+    const pPr = xml.child(p, A, 'pPr');
+    return pPr?.hasAttribute('lvl') ? Number(pPr.getAttribute('lvl')) : 0;
+}
+export function readParagraphs(txBody) {
+    return xml
+        .children(txBody, A, 'p')
+        .map((p) => ({ text: paragraphText(p), level: paragraphLevel(p) }));
+}
+export function readText(txBody) {
+    return readParagraphs(txBody)
+        .map((p) => p.text)
+        .join('\n');
+}
+function normalizeItem(item) {
+    if (typeof item === 'string') {
+        return { text: item };
+    }
+    if (typeof item !== 'object' ||
+        item === null ||
+        !('text' in item) ||
+        typeof item.text !== 'string') {
+        throw new DocsError('INVALID_TEXT', 'each paragraph must be a string or { text, level }');
+    }
+    const level = 'level' in item ? item.level : undefined;
+    if (level !== undefined &&
+        !(typeof level === 'number' && Number.isInteger(level) && level >= 0 && level <= 8)) {
+        throw new DocsError('INVALID_TEXT', `paragraph level must be an integer from 0 to 8, got ${String(level)}`);
+    }
+    return { text: item.text, level };
+}
+export function normalizeParagraphs(input) {
+    if (typeof input === 'string') {
+        return input.split('\n').map((text) => ({ text }));
+    }
+    if (!Array.isArray(input)) {
+        throw new DocsError('INVALID_TEXT', 'text must be a string or an array of paragraphs');
+    }
+    return input.map(normalizeItem);
+}
+function unlinked(rPr) {
+    for (const local of LINKS) {
+        for (const el of xml.children(rPr, A, local)) {
+            xml.remove(el);
+        }
+    }
+    return rPr;
+}
+export function losses(txBody) {
+    const out = {};
+    const hyperlinks = LINKS.reduce((n, local) => n + xml.descendants(txBody, A, local).length, 0);
+    const fields = xml.descendants(txBody, A, 'fld').length;
+    if (hyperlinks) {
+        out.hyperlinks = hyperlinks;
+    }
+    if (fields) {
+        out.fields = fields;
+    }
+    return out;
+}
+function runPropertiesOf(template) {
+    if (!template)
+        return null;
+    const run = xml.child(template, A, 'r');
+    if (run) {
+        const rPr = xml.child(run, A, 'rPr');
+        return rPr ? unlinked(xml.clone(rPr)) : null;
+    }
+    const end = xml.child(template, A, 'endParaRPr');
+    if (!end) {
+        return null;
+    }
+    const rPr = xml.builder(xml.owner(template), A)('rPr');
+    for (const attr of Array.from(end.attributes)) {
+        rPr.setAttribute(attr.name, attr.value);
+    }
+    for (const node of xml.children(end)) {
+        rPr.appendChild(xml.clone(node));
+    }
+    return unlinked(rPr);
+}
+function paragraphProperties(template, paragraph, a) {
+    const existing = template ? xml.child(template, A, 'pPr') : null;
+    const pPr = existing ? xml.clone(existing) : null;
+    if (paragraph.level === undefined) {
+        return pPr;
+    }
+    const out = pPr ?? a('pPr');
+    if (paragraph.level === 0) {
+        out.removeAttribute('lvl');
+    }
+    else {
+        out.setAttribute('lvl', String(paragraph.level));
+    }
+    return out;
+}
+function appendLine(p, line, rPr) {
+    const doc = xml.owner(p);
+    const a = xml.builder(doc, A);
+    const r = xml.append(p, a('r'));
+    if (rPr) {
+        r.appendChild(xml.clone(rPr));
+    }
+    xml.append(r, a('t')).appendChild(doc.createTextNode(line));
+}
+function buildParagraph(template, paragraph, a) {
+    const p = a('p');
+    const pPr = paragraphProperties(template, paragraph, a);
+    if (pPr) {
+        p.appendChild(pPr);
+    }
+    const rPr = runPropertiesOf(template);
+    paragraph.text.split(/\r\n|[\n\v]/).forEach((raw, i) => {
+        const line = xml.clean(raw);
+        if (i > 0) {
+            const br = xml.append(p, a('br'));
+            if (rPr) {
+                br.appendChild(xml.clone(rPr));
+            }
+        }
+        if (line !== '') {
+            appendLine(p, line, rPr);
+        }
+    });
+    const end = template ? xml.child(template, A, 'endParaRPr') : null;
+    if (end) {
+        p.appendChild(unlinked(xml.clone(end)));
+    }
+    return p;
+}
+export function writeParagraphs(txBody, input) {
+    const paragraphs = normalizeParagraphs(input);
+    if (paragraphs.length === 0) {
+        paragraphs.push({ text: '' });
+    }
+    const a = xml.builder(xml.owner(txBody), A);
+    const old = xml.children(txBody, A, 'p');
+    const built = paragraphs.map((paragraph, i) => buildParagraph(old[Math.min(i, old.length - 1)], paragraph, a));
+    const anchor = old.length ? old[old.length - 1].nextSibling : null;
+    for (const p of old) {
+        xml.remove(p);
+    }
+    for (const p of built) {
+        txBody.insertBefore(p, anchor);
+    }
+    return built.length;
+}
+export function ensureTextBody(parent, order) {
+    const namespace = parent.namespaceURI ?? A;
+    const existing = xml.child(parent, namespace, 'txBody');
+    if (existing) {
+        return existing;
+    }
+    const doc = xml.owner(parent);
+    const a = xml.builder(doc, A);
+    const txBody = xml.builder(doc, namespace)('txBody');
+    for (const local of ['bodyPr', 'lstStyle', 'p']) {
+        txBody.appendChild(a(local));
+    }
+    if (order) {
+        xml.insertOrdered(parent, txBody, order);
+    }
+    else {
+        parent.appendChild(txBody);
+    }
+    return txBody;
+}
+function isRecordLike(value) {
+    return isRecord(value) && !Array.isArray(value);
+}
+function checkStyleKeys(style) {
+    const keys = Object.keys(style);
+    if (keys.length === 0) {
+        throw new DocsError('INVALID_STYLE', `style names nothing to change; use ${STYLE_KEYS.join(', ')}`);
+    }
+    const unknownKey = keys.find((key) => !STYLE_KEYS.includes(key));
+    if (unknownKey) {
+        throw new DocsError('INVALID_STYLE', `unknown style "${unknownKey}"; use ${STYLE_KEYS.join(', ')}`);
+    }
+}
+function checkStyleValues(style) {
+    const { size, color, font, align } = style;
+    if (size !== undefined && !(typeof size === 'number' && size >= 1 && size <= 400)) {
+        throw new DocsError('INVALID_STYLE', `size is in points, from 1 to 400, got ${String(size)}`);
+    }
+    const toggle = TOGGLES.find((key) => style[key] !== undefined && typeof style[key] !== 'boolean');
+    if (toggle) {
+        throw new DocsError('INVALID_STYLE', `${toggle} must be true or false`);
+    }
+    if (color !== undefined && !(typeof color === 'string' && /^#?[0-9a-fA-F]{6}$/.test(color))) {
+        throw new DocsError('INVALID_STYLE', `color must be a hex RGB value like "1A73E8", got ${String(color)}`);
+    }
+    if (align !== undefined && !isAlignment(align)) {
+        throw new DocsError('INVALID_STYLE', `align must be left, center, right or justify, got ${String(align)}`);
+    }
+    if (font !== undefined && !(typeof font === 'string' && font.trim())) {
+        throw new DocsError('INVALID_STYLE', 'font must be a typeface name');
+    }
+}
+function flag(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+export function validateStyle(style) {
+    if (!isRecordLike(style)) {
+        throw new DocsError('INVALID_STYLE', 'style must be an object');
+    }
+    checkStyleKeys(style);
+    checkStyleValues(style);
+    const { size, color, font, align } = style;
+    return {
+        size: typeof size === 'number' ? size : undefined,
+        bold: flag(style.bold),
+        italic: flag(style.italic),
+        underline: flag(style.underline),
+        color: typeof color === 'string' ? color : undefined,
+        font: typeof font === 'string' ? font : undefined,
+        align: isAlignment(align) ? align : undefined
+    };
+}
+function setColor(rPr, color) {
+    const a = xml.builder(xml.owner(rPr), A);
+    for (const fill of xml.children(rPr, A)) {
+        if (FILLS.includes(fill.localName ?? '')) {
+            xml.remove(fill);
+        }
+    }
+    const solid = a('solidFill');
+    solid.appendChild(a('srgbClr', { val: color.replace('#', '').toUpperCase() }));
+    xml.insertOrdered(rPr, solid, RUN_PROPERTY_ORDER);
+}
+function applyRunStyle(rPr, style) {
+    if (style.size !== undefined) {
+        rPr.setAttribute('sz', String(Math.round(style.size * 100)));
+    }
+    if (style.bold !== undefined) {
+        rPr.setAttribute('b', style.bold ? '1' : '0');
+    }
+    if (style.italic !== undefined) {
+        rPr.setAttribute('i', style.italic ? '1' : '0');
+    }
+    if (style.underline !== undefined) {
+        rPr.setAttribute('u', style.underline ? 'sng' : 'none');
+    }
+    if (style.color !== undefined) {
+        setColor(rPr, style.color);
+    }
+    if (style.font !== undefined) {
+        const latin = xml.child(rPr, A, 'latin') ??
+            xml.insertOrdered(rPr, xml.builder(xml.owner(rPr), A)('latin'), RUN_PROPERTY_ORDER);
+        latin.setAttribute('typeface', style.font);
+    }
+}
+function ensureChild(parent, local, before) {
+    const existing = xml.child(parent, A, local);
+    if (existing) {
+        return existing;
+    }
+    const el = xml.builder(xml.owner(parent), A)(local);
+    parent.insertBefore(el, before);
+    return el;
+}
+function styleParagraph(p, style, styleRuns) {
+    if (style.align !== undefined) {
+        ensureChild(p, 'pPr', p.firstChild).setAttribute('algn', ALIGNMENTS[style.align]);
+    }
+    let runs = 0;
+    for (const node of xml.children(p, A)) {
+        if (node.localName === 'r' || node.localName === 'fld') {
+            if (styleRuns) {
+                applyRunStyle(ensureChild(node, 'rPr', node.firstChild), style);
+            }
+            runs++;
+        }
+        else if (node.localName === 'br') {
+            const rPr = xml.child(node, A, 'rPr');
+            if (rPr) {
+                applyRunStyle(rPr, style);
+            }
+        }
+    }
+    if (styleRuns) {
+        applyRunStyle(ensureChild(p, 'endParaRPr', null), style);
+    }
+    return runs;
+}
+export function applyStyle(txBody, input, target = {}) {
+    const style = validateStyle(input);
+    const paragraphs = xml.children(txBody, A, 'p');
+    let targets = paragraphs;
+    if (target.paragraph !== undefined) {
+        const p = paragraphs[target.paragraph];
+        if (!p) {
+            throw new DocsError('PARAGRAPH_NOT_FOUND', `paragraph ${target.paragraph} does not exist; this text has ${paragraphs.length} (0 to ${paragraphs.length - 1})`);
+        }
+        targets = [p];
+    }
+    const styleRuns = Object.keys(input ?? {}).some((key) => key !== 'align');
+    return targets.reduce((runs, p) => runs + styleParagraph(p, style, styleRuns), 0);
+}

package/dist-lib/lib/office/engine/errors.d.ts

@@ -0,0 +1,6 @@
+import { CODES, type DocsErrorCode } from './codes.ts';
+export declare class DocsError extends Error {
+    code: DocsErrorCode;
+    constructor(code: DocsErrorCode, message: string);
+    static get codes(): typeof CODES;
+}

package/dist-lib/lib/office/engine/errors.js

@@ -0,0 +1,12 @@
+import { CODES } from './codes.js';
+export class DocsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'DocsError';
+        this.code = code;
+    }
+    static get codes() {
+        return CODES;
+    }
+}

package/dist-lib/lib/office/engine/image.d.ts

@@ -0,0 +1,8 @@
+export type ImageFormat = 'png' | 'jpeg' | 'gif';
+export interface ImageInfo {
+    format: ImageFormat;
+    contentType: string;
+    width: number;
+    height: number;
+}
+export declare function probe(bytes: Uint8Array): ImageInfo;

package/dist-lib/lib/office/engine/image.js

@@ -0,0 +1,48 @@
+import { DocsError } from './errors.js';
+function jpegSize(bytes, view) {
+    let offset = 2;
+    while (offset + 9 < bytes.byteLength && bytes[offset] === 0xff) {
+        const marker = bytes[offset + 1];
+        if (marker === 0xff) {
+            offset++;
+            continue;
+        }
+        const frame = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
+        if (frame) {
+            return {
+                format: 'jpeg',
+                contentType: 'image/jpeg',
+                width: view.getUint16(offset + 7),
+                height: view.getUint16(offset + 5)
+            };
+        }
+        offset += 2 + view.getUint16(offset + 2);
+    }
+    throw new DocsError('INVALID_IMAGE', 'the JPEG has no frame header, so its size is unknown');
+}
+export function probe(bytes) {
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength < 24) {
+        throw new DocsError('INVALID_IMAGE', 'the image is empty or truncated');
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(0) === 0x89504e47 && view.getUint32(4) === 0x0d0a1a0a) {
+        return {
+            format: 'png',
+            contentType: 'image/png',
+            width: view.getUint32(16),
+            height: view.getUint32(20)
+        };
+    }
+    if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) {
+        return {
+            format: 'gif',
+            contentType: 'image/gif',
+            width: view.getUint16(6, true),
+            height: view.getUint16(8, true)
+        };
+    }
+    if (bytes[0] === 0xff && bytes[1] === 0xd8) {
+        return jpegSize(bytes, view);
+    }
+    throw new DocsError('UNSUPPORTED_IMAGE', 'only PNG, JPEG and GIF images can be embedded');
+}

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

@@ -0,0 +1,12 @@
+export * as pptx from './pptx/index.ts';
+export * as docx from './docx/index.ts';
+export * as xlsx from './xlsx/index.ts';
+export * as units from './units.ts';
+export { Package } from './opc/package.ts';
+export { DocsError } from './errors.ts';
+export { CODES } from './codes.ts';
+export type { DocsErrorCode } from './codes.ts';
+export type { OpenOptions, PartData } from './opc/package.ts';
+export type { SaveOptions } from './opc/properties.ts';
+export type { ChartData, ChartInfo, ChartSpec, ChartType } from './drawingml/chart.ts';
+export type { Paragraph, Style, TextInput } from './drawingml/text.ts';

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

@@ -0,0 +1,7 @@
+export * as pptx from './pptx/index.js';
+export * as docx from './docx/index.js';
+export * as xlsx from './xlsx/index.js';
+export * as units from './units.js';
+export { Package } from './opc/package.js';
+export { DocsError } from './errors.js';
+export { CODES } from './codes.js';

package/dist-lib/lib/office/engine/opc/content-types.d.ts

@@ -0,0 +1,17 @@
+import type { Document, Element } from '../xml.ts';
+export declare const CONTENT_TYPES_NAME = "/[Content_Types].xml";
+export declare class ContentTypes {
+    doc: Document;
+    dirty: boolean;
+    private original;
+    constructor(bytes: Uint8Array | null);
+    get root(): Element;
+    get(partName: string): string | null;
+    hasDefault(ext: string): boolean;
+    addDefault(ext: string, contentType: string): void;
+    setOverride(partName: string, contentType: string): void;
+    removeOverride(partName: string): void;
+    serialize(): Uint8Array;
+    private defaults;
+    private override;
+}

package/dist-lib/lib/office/engine/opc/content-types.js

@@ -0,0 +1,74 @@
+import * as xml from '../xml.js';
+import { extension } from './paths.js';
+export const CONTENT_TYPES_NAME = '/[Content_Types].xml';
+export class ContentTypes {
+    doc;
+    dirty;
+    original;
+    constructor(bytes) {
+        this.original = bytes;
+        this.doc = xml.parse(bytes ?? `<Types xmlns="${xml.ns.ct}"/>`, CONTENT_TYPES_NAME);
+        this.dirty = !bytes;
+    }
+    get root() {
+        return xml.root(this.doc);
+    }
+    get(partName) {
+        const override = this.override(partName);
+        if (override) {
+            return override.getAttribute('ContentType');
+        }
+        const ext = extension(partName);
+        const entry = this.defaults().find((el) => xml.attr(el, 'Extension').toLowerCase() === ext);
+        return entry ? entry.getAttribute('ContentType') : null;
+    }
+    hasDefault(ext) {
+        return this.defaults().some((el) => xml.attr(el, 'Extension').toLowerCase() === ext.toLowerCase());
+    }
+    addDefault(ext, contentType) {
+        if (this.hasDefault(ext))
+            return;
+        const el = xml.setAttributes(xml.named(this.doc, 'Default', xml.ns.ct), {
+            Extension: ext,
+            ContentType: contentType
+        });
+        this.root.insertBefore(el, xml.child(this.root, xml.ns.ct, 'Override'));
+        this.dirty = true;
+    }
+    setOverride(partName, contentType) {
+        const existing = this.override(partName);
+        if (existing?.getAttribute('ContentType') === contentType) {
+            return;
+        }
+        if (existing) {
+            existing.setAttribute('ContentType', contentType);
+        }
+        else {
+            const el = xml.named(this.doc, 'Override', xml.ns.ct);
+            this.root.appendChild(xml.setAttributes(el, { PartName: partName, ContentType: contentType }));
+        }
+        this.dirty = true;
+    }
+    removeOverride(partName) {
+        const existing = this.override(partName);
+        if (!existing) {
+            return;
+        }
+        xml.remove(existing);
+        this.dirty = true;
+    }
+    serialize() {
+        if (!this.dirty && this.original)
+            return this.original;
+        return xml.serialize(this.doc);
+    }
+    defaults() {
+        return xml.children(this.root, xml.ns.ct, 'Default');
+    }
+    override(partName) {
+        const wanted = partName.toLowerCase();
+        return xml
+            .children(this.root, xml.ns.ct, 'Override')
+            .find((el) => xml.attr(el, 'PartName').toLowerCase() === wanted);
+    }
+}

package/dist-lib/lib/office/engine/opc/media.d.ts

@@ -0,0 +1,13 @@
+import { type ImageInfo } from '../image.ts';
+import type { Package } from './package.ts';
+export declare const IMAGE_REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+export interface ImagePlacement {
+    source: string;
+    dir: string;
+}
+export interface AddedImage {
+    rId: string;
+    part: string;
+    info: ImageInfo;
+}
+export declare function addImage(pkg: Package, bytes: Uint8Array, at: ImagePlacement): AddedImage;

package/dist-lib/lib/office/engine/opc/media.js

@@ -0,0 +1,11 @@
+import { probe } from '../image.js';
+import * as paths from './paths.js';
+export const IMAGE_REL = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image';
+export function addImage(pkg, bytes, at) {
+    const info = probe(bytes);
+    pkg.contentTypes.addDefault(info.format, info.contentType);
+    const part = pkg.freeName(paths.resolve(at.source, `${at.dir}/image%d.${info.format}`));
+    pkg.add(part, bytes);
+    const rId = pkg.rels(at.source).add(IMAGE_REL, part);
+    return { rId, part, info };
+}

package/dist-lib/lib/office/engine/opc/package.d.ts

@@ -0,0 +1,51 @@
+import { ContentTypes } from './content-types.ts';
+import { Relationships } from './relationships.ts';
+import type { Document, Element } from '../xml.ts';
+import type { Limits } from './zip.ts';
+export type PartData = Uint8Array | Document;
+export interface OpenOptions {
+    limits?: Partial<Limits>;
+    strict?: boolean;
+}
+export declare class Package {
+    static strict: boolean;
+    strict: boolean;
+    contentTypes: ContentTypes;
+    private parts;
+    private folded;
+    private order;
+    private relsBySource;
+    private removed;
+    private edited;
+    private strays;
+    constructor(entries: [string, Uint8Array][], opts?: OpenOptions);
+    static open(bytes: Uint8Array | ArrayBuffer, opts?: OpenOptions): Package;
+    static create(opts?: OpenOptions): Package;
+    get changed(): boolean;
+    names(): string[];
+    has(name: string | null): boolean;
+    bytes(name: string): Uint8Array;
+    xml(name: string): Document;
+    root(name: string): Element;
+    touch(name: string): void;
+    contentType(name: string): string | null;
+    add(name: string, data: PartData, contentType?: string): void;
+    write(name: string, data: PartData): void;
+    remove(input: string): boolean;
+    rels(source: string): Relationships;
+    related(source: string, type: string): string[];
+    dropUnreferenced(source: string, types: readonly string[]): string[];
+    freeName(pattern: string): string;
+    reachable(): Set<string>;
+    prune(): string[];
+    private unreachable;
+    save(): Uint8Array;
+    private checkUntouched;
+    private flushRels;
+    private require;
+    private resolveExisting;
+    private find;
+    private store;
+    private forget;
+}
+export declare function referencedIds(top: Element): Set<string>;