@p10node/office-engine 0.0.0 → 0.1.1

package/dist/types/core/pptx/types.d.ts

@@ -0,0 +1,238 @@
+/** Geometry in px (96 dpi, EMU/9525); font sizes in pt. */
+export type Fill = {
+    t: 'solid';
+    c: string;
+} | {
+    t: 'grad';
+    css: string;
+} | {
+    t: 'img';
+    target: string;
+    tile?: boolean;
+} | {
+    t: 'none';
+};
+export interface Stroke {
+    c: string;
+    w: number;
+    dash?: string;
+    head?: string;
+    tail?: string;
+}
+export interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    rot?: number;
+    flipH?: boolean;
+    flipV?: boolean;
+}
+export interface TRun {
+    text: string;
+    sz: number;
+    b?: boolean;
+    i?: boolean;
+    u?: boolean;
+    strike?: boolean;
+    color?: string;
+    font?: string;
+    baseline?: number;
+    caps?: boolean;
+    href?: string;
+    hl?: string;
+    br?: boolean;
+    /** slide field (number/date): kept as an object when editing */
+    fld?: boolean;
+    /** [paragraph, run] index in the original shape XML */
+    src?: [number, number];
+}
+export interface TPara {
+    algn: 'left' | 'center' | 'right' | 'justify';
+    marL: number;
+    indent: number;
+    /** line height multiplier or px */
+    lnPct?: number;
+    lnPx?: number;
+    spcBef: number;
+    spcAft: number;
+    bullet?: {
+        text: string;
+        color?: string;
+        font?: string;
+        sz: number;
+    };
+    /** outline level and bullet kind (editor state) */
+    lvl?: number;
+    buKind?: 'none' | 'bullet' | 'number';
+    runs: TRun[];
+    endSz: number;
+    /** template paragraph index in the original shape XML */
+    k?: number;
+}
+export interface TextBody {
+    anchor: 't' | 'ctr' | 'b';
+    ins: [number, number, number, number];
+    wrap: boolean;
+    vert?: string;
+    paras: TPara[];
+    /** placeholder without text (editable, invisible when viewing) */
+    empty?: boolean;
+}
+/** `top`: id of the slide-level element (selection / move); `sid`: own id of a text shape (text editing) */
+export type SlideEl = ({
+    t: 'shape';
+    box: Box;
+    geom: string;
+    adj?: Record<string, number>;
+    fill?: Fill;
+    stroke?: Stroke;
+    text?: TextBody;
+    path?: string;
+    sid?: number;
+} | {
+    t: 'pic';
+    box: Box;
+    target?: string;
+    crop?: [number, number, number, number];
+    stroke?: Stroke;
+    geom?: string;
+    video?: boolean;
+} | {
+    t: 'table';
+    box: Box;
+    cols: number[];
+    rows: {
+        h: number;
+        cells: TCell[];
+    }[];
+} | {
+    t: 'placeholder';
+    box: Box;
+    label: string;
+}) & {
+    top?: number;
+};
+/** 'text', 'line', 'image' or any DrawingML preset geometry name (rect, ellipse, star5, chevron…) */
+export type ShapeKind = 'text' | 'line' | 'image' | (string & {});
+export type ShapeOp = {
+    op: 'xfrm';
+    top: number;
+    box: Box;
+} | {
+    op: 'delete';
+    top: number;
+} | {
+    op: 'fill';
+    top: number;
+    color: string | null;
+} | {
+    op: 'line';
+    top: number;
+    color?: string | null;
+    w?: number;
+    dash?: string;
+} | {
+    op: 'order';
+    top: number;
+    to: 'front' | 'back' | 'forward' | 'backward';
+} | {
+    op: 'duplicate';
+    top: number;
+    dx?: number;
+    dy?: number;
+}
+/** vertical text anchor of a text shape (by shape id) */
+ | {
+    op: 'anchor';
+    sid: number;
+    anchor: 't' | 'ctr' | 'b';
+}
+/** slide background color (null = follow layout) */
+ | {
+    op: 'bg';
+    color: string | null;
+} | {
+    op: 'insert';
+    kind: ShapeKind;
+    box: Box;
+    text?: string;
+    rid?: string;
+};
+export type SlideOp = {
+    op: 'add';
+    after: number;
+    layout?: 'title' | 'content' | 'blank';
+} | {
+    op: 'duplicate';
+    index: number;
+} | {
+    op: 'delete';
+    index: number;
+} | {
+    op: 'move';
+    from: number;
+    to: number;
+} | {
+    op: 'hide';
+    index: number;
+    hidden: boolean;
+};
+export interface TCell {
+    text?: TextBody;
+    fill?: Fill;
+    bl?: Stroke;
+    br?: Stroke;
+    bt?: Stroke;
+    bb?: Stroke;
+    colSpan: number;
+    rowSpan: number;
+    hidden: boolean;
+}
+export interface SlideModel {
+    index: number;
+    w: number;
+    h: number;
+    bg?: Fill;
+    els: SlideEl[];
+    notes?: string;
+    hidden?: boolean;
+}
+export interface PresentationMeta {
+    w: number;
+    h: number;
+    count: number;
+    slides: {
+        index: number;
+        path: string;
+        hidden: boolean;
+    }[];
+}
+export interface PRunSet {
+    b?: boolean;
+    i?: boolean;
+    u?: boolean;
+    strike?: boolean;
+    sz?: number;
+    color?: string | null;
+    font?: string;
+    hl?: string | null;
+    /** percent of the font size (+30 superscript, -25 subscript), null = normal */
+    baseline?: number | null;
+}
+export interface PRunSpec {
+    text: string;
+    src?: [number, number];
+    set?: PRunSet;
+    fld?: boolean;
+}
+export interface PParaSpec {
+    k?: number;
+    algn?: 'left' | 'center' | 'right' | 'justify';
+    /** outline level 0-8 */
+    lvl?: number;
+    bullet?: 'none' | 'bullet' | 'number';
+    /** line spacing multiplier */
+    lnPct?: number;
+    runs: PRunSpec[];
+}

package/dist/types/core/raw.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Byte-faithful XML tree: keeps qualified names, raw attribute text and raw
+ * (still-escaped) text, so untouched parts serialize back exactly as read.
+ */
+export interface RNode {
+    q: string;
+    a: string;
+    c: RChild[];
+    self: boolean;
+}
+export type RChild = RNode | string;
+export declare const isNode: (x: RChild | undefined) => x is RNode;
+export declare function parseRaw(xml: string): RChild[];
+export declare function serialize(x: RChild | RChild[]): string;
+export declare const local: (q: string) => string;
+export declare const prefixOf: (q: string) => string;
+export declare function rootEl(nodes: RChild[]): RNode | undefined;
+export declare function kidsOf(n: RNode | undefined, loc?: string): RNode[];
+export declare function kidOf(n: RNode | undefined, loc: string): RNode | undefined;
+/** Attribute value by exact qualified name, or by local name when `loose`. */
+export declare function getAttr(n: RNode, name: string, loose?: boolean): string | undefined;
+export declare function setAttr(n: RNode, name: string, value: string | undefined): void;
+export declare function el(q: string, attrs?: Record<string, string | undefined>, children?: RChild[]): RNode;
+export declare function clone<T extends RChild>(x: T): T;
+export declare function removeKids(n: RNode, loc: string | ((l: string) => boolean)): void;
+/**
+ * Replaces (or inserts) the child with local name `loc`, keeping schema order:
+ * the new child goes before the first existing sibling that comes later in `order`.
+ */
+export declare function setOrdered(parent: RNode, child: RNode | undefined, loc: string, order: string[]): void;
+export declare function escText(s: string): string;
+export declare function escAttr(s: string): string;
+export declare function textContent(n: RChild): string;
+/**
+ * Preorder walk mirroring TreeBuilder semantics: mc:Fallback skipped, only the first
+ * mc:Choice of an mc:AlternateContent is visited. `visit` returns true to stop descending.
+ */
+export declare function walkOoxml(n: RNode, visit: (node: RNode, parent: RNode, index: number) => boolean | void): void;
+/** attributes for an `r:id`-style reference that are valid whatever prefixes the root declared */
+export declare function relIdAttrs(root: RNode, local: string | undefined, value: string): Record<string, string>;

package/dist/types/core/source.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Random-access byte sources. The ZIP reader only touches the bytes it needs
+ * (central directory + requested entries), so a 500 MB file is never read in full.
+ */
+export interface ByteSource {
+    readonly size: number;
+    readonly name?: string;
+    read(offset: number, length: number): Promise<Uint8Array>;
+    stream(offset: number, length: number): ReadableStream<Uint8Array>;
+    /** Zero-copy sub-Blob when available (used when re-zipping unchanged entries). */
+    slice?(offset: number, length: number): Blob;
+}
+export type ProgressFn = (loaded: number, total: number) => void;
+export declare class BlobSource implements ByteSource {
+    private blob;
+    readonly name?: string | undefined;
+    readonly size: number;
+    constructor(blob: Blob, name?: string | undefined);
+    read(offset: number, length: number): Promise<Uint8Array>;
+    stream(offset: number, length: number): ReadableStream<Uint8Array>;
+    slice(offset: number, length: number): Blob;
+}
+export declare class BufferSource implements ByteSource {
+    readonly name?: string | undefined;
+    readonly size: number;
+    private bytes;
+    constructor(data: ArrayBuffer | Uint8Array, name?: string | undefined);
+    read(offset: number, length: number): Promise<Uint8Array>;
+    stream(offset: number, length: number): ReadableStream<Uint8Array>;
+}
+export interface HttpSourceOptions {
+    headers?: Record<string, string>;
+    credentials?: RequestCredentials;
+    /** Block size used for cached range reads (default 256 KB). */
+    blockSize?: number;
+    /** Max cached blocks (default 128 → 32 MB). */
+    maxBlocks?: number;
+    onProgress?: ProgressFn;
+    signal?: AbortSignal;
+}
+/**
+ * HTTP source using Range requests. Falls back to a full download when the
+ * server does not honour ranges (or CORS hides the needed headers).
+ */
+export declare class HttpRangeSource implements ByteSource {
+    readonly url: string;
+    readonly size: number;
+    private opts;
+    readonly name?: string | undefined;
+    private cache;
+    private inflight;
+    private blockSize;
+    private maxBlocks;
+    private constructor();
+    static open(url: string, opts?: HttpSourceOptions): Promise<ByteSource>;
+    private fetchRange;
+    private ensureBlocks;
+    private evict;
+    read(offset: number, length: number): Promise<Uint8Array>;
+    stream(offset: number, length: number): ReadableStream<Uint8Array>;
+}
+export type DocSource = Blob | File | ArrayBuffer | Uint8Array | string | URL;
+export declare function openSource(src: DocSource, opts?: HttpSourceOptions & {
+    name?: string;
+}): Promise<ByteSource>;

package/dist/types/core/theme.d.ts

@@ -0,0 +1,11 @@
+import { type XEl } from './xml';
+export interface Theme {
+    colors: Record<string, string>;
+    major: string;
+    minor: string;
+    fillStyles: XEl[];
+    bgFillStyles: XEl[];
+    lineStyles: XEl[];
+}
+export declare const DEFAULT_THEME: Theme;
+export declare function parseTheme(root: XEl | undefined): Theme;

package/dist/types/core/units.d.ts

@@ -0,0 +1,7 @@
+export declare const EMU_PER_PX = 9525;
+export declare const EMU_PER_PT = 12700;
+export declare const emuToPx: (v: number | undefined) => number;
+export declare const emuToPt: (v: number | undefined) => number;
+export declare const twipToPt: (v: number | undefined) => number;
+export declare const ptToPx: (pt: number) => number;
+export declare const round2: (v: number) => number;

package/dist/types/core/worker/client.d.ts

@@ -0,0 +1,48 @@
+import type { DocKind } from '../opc';
+import type { DocSource } from '../source';
+import type { Events, Methods, OpenParams, OpenResult } from './protocol';
+export interface OpenOptions extends OpenParams {
+    /** Custom worker factory (e.g. for strict CSP setups). Pass `false` to run on the main thread. */
+    worker?: (() => Worker) | false;
+    /** Download / parse progress, including progress emitted while opening. */
+    onProgress?: (p: Events['progress']) => void;
+}
+type Listener<K extends keyof Events> = (data: Events[K]) => void;
+/** Registers the worker factory used when none is passed to `DocumentClient.open`. */
+export declare function setDefaultWorker(factory: () => Worker): void;
+/**
+ * Main-thread handle to a document living in a Web Worker.
+ * Parsing, unzipping and formatting never block the UI thread.
+ */
+export declare class DocumentClient {
+    kind: DocKind;
+    name?: string;
+    size: number;
+    info: OpenResult;
+    private worker?;
+    private engine?;
+    private seq;
+    private pending;
+    private listeners;
+    private urls;
+    private destroyed;
+    private constructor();
+    static open(src: DocSource, opts?: OpenOptions): Promise<DocumentClient>;
+    private onMessage;
+    /**
+     * Set by a collaboration session: sees every call first and handles the ones that change the
+     * document (returns a promise), or returns undefined to let the call through unchanged.
+     */
+    interceptor?: (method: keyof Methods, args: unknown[]) => Promise<unknown> | undefined;
+    call<M extends keyof Methods>(method: M, ...args: Parameters<Methods[M]>): Promise<ReturnType<Methods[M]>>;
+    /** calls the engine directly, bypassing `interceptor` */
+    direct<M extends keyof Methods>(method: M, ...args: Parameters<Methods[M]>): Promise<ReturnType<Methods[M]>>;
+    /** dispatches an event to listeners on this thread (e.g. remote changes applied by a collaboration session) */
+    notify<K extends keyof Events>(event: K, data: Events[K]): void;
+    on<K extends keyof Events>(event: K, fn: Listener<K>): () => void;
+    /** Object URL for a package part (images, media). Cached per client; revoked on destroy. */
+    mediaUrl(path: string): Promise<string>;
+    static canRender(path: string): boolean;
+    destroy(): void;
+}
+export {};

package/dist/types/core/worker/engine.d.ts

@@ -0,0 +1,27 @@
+import { type DocSource } from '../source';
+import type { Events, Methods, OpenParams, OpenResult } from './protocol';
+type Emit = <K extends keyof Events>(event: K, data: Events[K]) => void;
+/** Format-agnostic engine; runs inside the worker (or directly, e.g. in tests). */
+export declare class Engine {
+    private emit;
+    private pkg?;
+    private kind?;
+    private docx?;
+    private xlsx?;
+    private xlsxEd?;
+    private pptx?;
+    private abort;
+    constructor(emit: Emit);
+    open(src: DocSource, params?: OpenParams): Promise<OpenResult>;
+    private writes;
+    call<M extends keyof Methods>(method: M, args: unknown[]): Promise<unknown>;
+    private dispatch;
+    private xcollab?;
+    private pcollab?;
+    private xc;
+    private xed;
+    private save;
+    dispose(): void;
+    private need;
+}
+export {};

package/dist/types/core/worker/protocol.d.ts

@@ -0,0 +1,112 @@
+import type { DocKind } from '../opc';
+import type { XOp } from '../../collab/xlsx-ops';
+import type { POp } from '../../collab/pptx-ops';
+import type { PptxCollabResult } from '../../collab/pptx-worker';
+import type { CanonStyle, DocxMeta, Block, EditOp, EditResult, StyleInfo, TableOp } from '../docx/types';
+import type { BlockOut, BookOp, CellDetail, CellInput, FindMatch, FindOptions, FmtPatch, Range, SheetOp, SheetProgress, WorkbookMeta, XlsxEditResult } from '../xlsx/types';
+import type { PParaSpec, PresentationMeta, ShapeOp, SlideModel, SlideOp } from '../pptx/types';
+export interface OpenParams {
+    name?: string;
+    headers?: Record<string, string>;
+    credentials?: RequestCredentials;
+}
+export interface OpenResult {
+    kind: DocKind;
+    name?: string;
+    size: number;
+    xlsx?: WorkbookMeta;
+    pptx?: PresentationMeta;
+}
+export interface Methods {
+    open(src: Blob | ArrayBuffer | string, params: OpenParams): OpenResult;
+    part(path: string): Blob;
+    'docx.start'(): void;
+    'docx.edit'(op: EditOp): EditResult;
+    'docx.table'(op: TableOp): void;
+    'docx.image'(bytes: ArrayBuffer, ext: string): {
+        rid: string;
+        path: string;
+    };
+    'docx.link'(url: string): string;
+    /** id of a built-in paragraph style, created in styles.xml when missing */
+    'docx.style'(kind: CanonStyle): {
+        id: string;
+        styles: StyleInfo[];
+    };
+    /** builds the edited file */
+    save(): Blob;
+    dirty(): boolean;
+    'xlsx.load'(sheet: number): void;
+    'xlsx.block'(sheet: number, r0: number, r1: number): BlockOut;
+    'xlsx.cell'(sheet: number, r: number, c: number): CellDetail | undefined;
+    /** cells whose shown value (or formula) contains the text */
+    'xlsx.find'(sheet: number, query: string, opts?: FindOptions): FindMatch[];
+    /** replaces text in matching cells (or only `at`); null when nothing changed */
+    'xlsx.replace'(sheet: number, query: string, by: string, opts?: FindOptions, at?: {
+        r: number;
+        c: number;
+    }): XlsxEditResult | null;
+    'xlsx.set'(sheet: number, cells: CellInput[]): XlsxEditResult;
+    'xlsx.format'(sheet: number, range: Range, patch: FmtPatch): XlsxEditResult;
+    'xlsx.sheetOp'(sheet: number, op: SheetOp): XlsxEditResult;
+    'xlsx.bookOp'(op: BookOp): XlsxEditResult;
+    'xlsx.undo'(): XlsxEditResult | null;
+    'xlsx.redo'(): XlsxEditResult | null;
+    'pptx.slide'(index: number): SlideModel;
+    'pptx.setText'(index: number, sid: number, paras: PParaSpec[]): SlideModel;
+    'pptx.shapes'(index: number, ops: ShapeOp[]): SlideModel;
+    'pptx.slides'(op: SlideOp): PresentationMeta;
+    'pptx.image'(index: number, bytes: ArrayBuffer, ext: string): string;
+    /** undo (or redo) the last shape edit */
+    'pptx.undo'(redo?: boolean): {
+        index: number;
+        model: SlideModel;
+    } | null;
+    /** collaboration (src/collab): a shared XLSX operation, outside the undo history; `rec` reverts it */
+    'collab.xlsx.apply'(op: XOp): {
+        res: XlsxEditResult | null;
+        rec: number | null;
+    };
+    'collab.xlsx.revert'(rec: number): XlsxEditResult | null;
+    /** collaboration: a shared PPTX operation (recorded as slide snapshots) */
+    'collab.pptx.apply'(op: POp): {
+        res: PptxCollabResult;
+        rec: number | null;
+    };
+    'collab.pptx.revert'(rec: number): PptxCollabResult;
+}
+export interface Events {
+    progress: {
+        phase: string;
+        loaded: number;
+        total: number;
+    };
+    'docx:blocks': Block[];
+    'docx:meta': DocxMeta;
+    'docx:done': {
+        error?: string;
+    };
+    'xlsx:progress': SheetProgress;
+    /** collaboration: remote (or rebased) XLSX changes applied on this client */
+    'collab:xlsx': XlsxEditResult;
+    /** collaboration: a slide (or the slide list) changed remotely */
+    'collab:pptx': PptxCollabResult;
+}
+export type Req = {
+    id: number;
+    method: keyof Methods;
+    args: unknown[];
+};
+export type Res = {
+    id: number;
+    ok: true;
+    result: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};
+export type Evt = {
+    event: keyof Events;
+    data: unknown;
+};

package/dist/types/core/worker/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/core/xlsx/calc.d.ts

@@ -0,0 +1,31 @@
+import { type XlsxWorkbook } from './workbook';
+export declare class Calc {
+    private wb;
+    private asts;
+    private cellDeps;
+    private rangeDeps;
+    private indexed;
+    constructor(wb: XlsxWorkbook);
+    invalidate(): void;
+    private sheetIndex;
+    private ast;
+    private index;
+    private addDeps;
+    /** a formula was added / changed / removed at (sheet, key) */
+    formulaChanged(sheet: number, key: number): void;
+    /** current value of a cell as the formula engine sees it */
+    private value;
+    private provider;
+    private cur;
+    private compute;
+    /** Evaluates the given formula cells and everything that depends on the changed cells. */
+    recalc(changed: {
+        sheet: number;
+        key: number;
+    }[], formulas?: {
+        sheet: number;
+        key: number;
+    }[]): Set<number>;
+    /** formulas whose value is missing (files written without cached values) */
+    computeMissing(sheet: number, keys: number[]): void;
+}

package/dist/types/core/xlsx/editor.d.ts

@@ -0,0 +1,95 @@
+import type { BookOp, CellInput, ColInfo, FindOptions, FmtPatch, Merge, Range, SheetOp, SheetProgress, XlsxEditResult } from './types';
+import { type Snapshot } from './structure';
+import { SheetData, XlsxWorkbook } from './workbook';
+export declare const XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+type Entry = [number, unknown, number];
+interface CellChange {
+    key: number;
+    prev: Entry | null;
+    prevF?: string;
+    next: Entry | null;
+    nextF?: string;
+}
+interface LayoutState {
+    merges?: Merge[];
+    colInfo?: ColInfo[];
+    rowAttrs?: [number, {
+        ht?: number;
+        hidden?: boolean;
+    }][];
+    frozen?: {
+        rows: number;
+        cols: number;
+    };
+    gridLines?: boolean;
+}
+export interface Change {
+    sheet: number;
+    cells: CellChange[];
+    range: Range;
+    /** cheap layout state (merges, sizes, panes) before/after */
+    lay?: {
+        before: LayoutState;
+        after: LayoutState;
+    };
+    /** whole-sheet snapshots (row/column insert/delete) */
+    full?: {
+        before: Snapshot;
+        after: Snapshot;
+    };
+}
+export declare function getEntry(d: SheetData, r: number, c: number): Entry | null;
+export declare class XlsxEditor {
+    private wb;
+    private undoStack;
+    private redoStack;
+    private styleEd?;
+    private stylesPath?;
+    private formulaTouched;
+    constructor(wb: XlsxWorkbook);
+    get dirty(): boolean;
+    private sheet;
+    private lastRecalc;
+    private apply;
+    private applyRaw;
+    private record;
+    /** after rows/columns moved: rebuild the dependency graph and recompute every formula */
+    private recalcAll;
+    setCells(sheet: number, inputs: CellInput[]): XlsxEditResult;
+    private styles;
+    format(sheet: number, range: Range, patch: FmtPatch): Promise<XlsxEditResult>;
+    private step;
+    undo(): XlsxEditResult | null;
+    redo(): XlsxEditResult | null;
+    /** takes the change recorded by the last operation out of the (unused) undo history */
+    takeRecord(): Change | undefined;
+    /** exactly undoes a recorded change (rolling back an unconfirmed operation) */
+    revertRecord(ch: Change): XlsxEditResult;
+    /** sets the cells / layout touched by `ch` to its `which` state, recorded as a new change */
+    restoreRecord(ch: Change, which: 'prev' | 'next'): XlsxEditResult;
+    /** style table sizes before an operation */
+    styleMark(): Promise<Record<string, number>>;
+    /** drops styles derived after `m` (the operations that used them were rolled back) */
+    styleTruncate(m: Record<string, number>): Promise<void>;
+    /** style index of a cell (0 when empty) */
+    styleAt(sheet: number, r: number, c: number): number;
+    /** current layout of a sheet (after structural edits) */
+    layout(sheet: number): SheetProgress;
+    private allSheets;
+    sheetOp(sheet: number, op: SheetOp): Promise<XlsxEditResult>;
+    /** replaces `query` in matching cells (one undo step); `at` limits it to one cell */
+    replace(sheet: number, query: string, by: string, opts?: FindOptions, at?: {
+        r: number;
+        c: number;
+    }): XlsxEditResult | null;
+    private fill;
+    private sort;
+    bookOp(op: BookOp): Promise<XlsxEditResult>;
+    private bookChanged;
+    /** XML of sheets created in this session (no original to stream from) */
+    private newSheets;
+    save(): Promise<Blob>;
+    /** Streams the original sheet XML, patching only rows that contain edits. */
+    private rewrite;
+}
+export {};