@p10node/office-engine 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,193 @@
+export interface SheetInfo {
+    name: string;
+    index: number;
+    path: string;
+    hidden: boolean;
+}
+/** CSS-ish props for a cell format (cellXfs entry). Keys are React style keys. */
+export type CellCss = Record<string, string | number>;
+export interface WorkbookMeta {
+    sheets: SheetInfo[];
+    styles: CellCss[];
+    /** number format code per style */
+    formats: string[];
+    /** CSS for font 0 (grid default) */
+    baseFont: CellCss;
+    date1904: boolean;
+}
+export interface ColInfo {
+    min: number;
+    max: number;
+    /** px; 0 when hidden */
+    w: number;
+    /** width before hiding (px) */
+    prevW?: number;
+}
+export interface Merge {
+    r0: number;
+    c0: number;
+    r1: number;
+    c1: number;
+}
+export interface SheetProgress {
+    sheet: number;
+    /** number of rows known so far (max row index + 1) */
+    rows: number;
+    cols: number;
+    /** custom row sizes discovered since last progress: [row, px] (0 = hidden) */
+    rowSizes: [number, number][];
+    done: boolean;
+    /** only in the first progress message */
+    colInfo?: ColInfo[];
+    defaultColW?: number;
+    defaultRowH?: number;
+    frozen?: {
+        rows: number;
+        cols: number;
+    };
+    gridLines?: boolean;
+    /** only when done */
+    merges?: Merge[];
+    error?: string;
+    /** formula values were (re)computed: cached rows are stale */
+    recalc?: boolean;
+}
+/** [col, text, styleIndex, kind (0 text,1 number,2 center), color?] */
+export type CellOut = [number, string, number, number, string?];
+export interface RowOut {
+    r: number;
+    cells: CellOut[];
+}
+export interface BlockOut {
+    sheet: number;
+    r0: number;
+    r1: number;
+    rows: RowOut[];
+    complete: boolean;
+}
+export interface CellDetail {
+    value: string;
+    formula?: string;
+    type: string;
+}
+export interface CellInput {
+    r: number;
+    c: number;
+    /** raw user input ('' clears; '=…' formula) */
+    input: string;
+}
+export type BorderKind = 'all' | 'outer' | 'inner' | 'none' | 'top' | 'bottom' | 'left' | 'right';
+export interface FmtPatch {
+    border?: BorderKind;
+    borderColor?: string;
+    b?: boolean;
+    i?: boolean;
+    u?: boolean;
+    strike?: boolean;
+    color?: string | null;
+    fill?: string | null;
+    align?: 'left' | 'center' | 'right' | null;
+    valign?: 'top' | 'center' | 'bottom' | null;
+    /** text rotation in degrees (-90…90), 255 = vertical stack, null = none */
+    rotate?: number | null;
+    wrap?: boolean;
+    numFmt?: string;
+    sz?: number;
+    font?: string;
+    borderStyle?: 'thin' | 'medium' | 'thick' | 'dashed' | 'dotted' | 'double';
+    /** reset to the default style */
+    clear?: boolean;
+    /** apply this exact style index (paint format) */
+    xf?: number;
+}
+export interface Range {
+    r0: number;
+    c0: number;
+    r1: number;
+    c1: number;
+}
+export interface XlsxEditResult {
+    sheet: number;
+    range: Range;
+    /** style entries appended to the workbook (index → css/format) */
+    styles?: {
+        index: number;
+        css: CellCss;
+        format: string;
+    }[];
+    /** full layout after structural edits (sizes, merges, frozen panes…) */
+    layout?: SheetProgress;
+    /** sheet list changed */
+    sheets?: SheetInfo[];
+    /** sheets whose formula values changed (cached rows are stale) */
+    recalc?: number[];
+}
+export type SheetOp = {
+    op: 'insertRows' | 'deleteRows' | 'insertCols' | 'deleteCols';
+    at: number;
+    n: number;
+} | {
+    op: 'merge' | 'unmerge';
+    range: Range;
+    mode?: 'all' | 'across' | 'down';
+} | {
+    op: 'hideRows' | 'hideCols';
+    a: number;
+    b: number;
+    hidden: boolean;
+} | {
+    op: 'gridlines';
+    show: boolean;
+} | {
+    op: 'colWidth';
+    c0: number;
+    c1: number;
+    px: number;
+} | {
+    op: 'rowHeight';
+    r0: number;
+    r1: number;
+    px: number;
+} | {
+    op: 'freeze';
+    rows: number;
+    cols: number;
+} | {
+    op: 'fill';
+    range: Range;
+    dir: 'down' | 'right';
+} | {
+    op: 'sort';
+    range: Range;
+    col: number;
+    desc?: boolean;
+};
+export type BookOp = {
+    op: 'add';
+    name?: string;
+    after?: number;
+} | {
+    op: 'rename';
+    index: number;
+    name: string;
+} | {
+    op: 'delete';
+    index: number;
+} | {
+    op: 'move';
+    from: number;
+    to: number;
+};
+export interface FindOptions {
+    matchCase?: boolean;
+    /** whole cell contents */
+    whole?: boolean;
+    /** search formula text instead of values */
+    formulas?: boolean;
+}
+export interface FindMatch {
+    r: number;
+    c: number;
+    /** text the match was found in (value or formula) */
+    text: string;
+}

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

@@ -0,0 +1,94 @@
+import { OpcPackage, type Rels } from '../opc';
+import { type Theme } from '../theme';
+import { Calc } from './calc';
+import { type SheetStyles } from './styles';
+import type { BlockOut, CellDetail, ColInfo, FindMatch, FindOptions, Merge, SheetInfo, SheetProgress, WorkbookMeta } from './types';
+export declare const T_NUM = 0;
+export declare const T_SST = 1;
+export declare const T_STR = 2;
+export declare const T_BOOL = 3;
+export declare const T_ERR = 4;
+export declare const T_DATE = 5;
+export declare const T_EMPTY = 6;
+export declare const MAX_COL = 16384;
+export declare function colIndex(letters: string): number;
+export declare function colName(c: number): string;
+export declare function parseRef(ref: string): [number, number];
+export declare function parseRange(ref: string): Merge | undefined;
+export declare class SheetData {
+    /** shared formula groups: si → master cell key + formula text */
+    shared: Map<number, {
+        master: number;
+        text: string;
+    }>;
+    /** dependent cell key → shared formula si */
+    depOf: Map<number, number>;
+    /** edited cell keys (r * MAX_COL + c) */
+    edited: Set<number>;
+    /** row heights in pt / hidden flags (from the file or the editor) */
+    rowAttrs: Map<number, {
+        ht?: number;
+        hidden?: boolean;
+    }>;
+    /** rows grown to fit a large font (no explicit height in the file): px */
+    autoRowH: Map<number, number>;
+    /** whole-sheet rewrite needed (rows/cols inserted or deleted) */
+    structural: boolean;
+    /** sections to regenerate on save */
+    dirtyCols: boolean;
+    dirtyMerges: boolean;
+    dirtyView: boolean;
+    /** rows whose height/visibility changed */
+    dirtyRows: Set<number>;
+    /** formulas rewritten because another sheet changed */
+    formulaChanged: boolean;
+    /** formula cells stored without a cached value (to compute after load) */
+    uncached: number[];
+    rows: (unknown[] | undefined)[];
+    maxRow: number;
+    maxCol: number;
+    formulas: Map<number, string>;
+    merges: Merge[];
+    colInfo: ColInfo[];
+    defaultColW: number;
+    defaultRowH: number;
+    frozen: {
+        rows: number;
+        cols: number;
+    };
+    gridLines: boolean;
+    done: boolean;
+    error?: string;
+    loading?: Promise<void>;
+}
+export declare class XlsxWorkbook {
+    readonly pkg: OpcPackage;
+    readonly mainPath: string;
+    readonly rels: Rels;
+    readonly sheets: SheetInfo[];
+    styles: SheetStyles;
+    readonly date1904: boolean;
+    readonly theme: Theme;
+    sheetsData: Map<number, SheetData>;
+    readonly calc: Calc;
+    sst: string[];
+    private sstLoading?;
+    private constructor();
+    static open(pkg: OpcPackage, mainPath: string): Promise<XlsxWorkbook>;
+    meta(): WorkbookMeta;
+    private loadSst;
+    /**
+     * Streams a sheet into memory, reporting progress so the UI can grow while parsing.
+     * Calling again for a loaded/in-flight sheet is a no-op.
+     */
+    loadSheet(index: number, emit: (p: SheetProgress) => void, onBytes?: (phase: string, loaded: number, total: number) => void): Promise<void>;
+    private snapshot;
+    /** Formatted cells for rows [r0, r1). */
+    block(sheet: number, r0: number, r1: number): BlockOut;
+    /** cells whose shown value (or formula) contains `query`, in row order */
+    find(sheet: number, query: string, opts?: FindOptions, limit?: number): FindMatch[];
+    cell(sheet: number, r: number, c: number): CellDetail | undefined;
+    unload(sheet: number): void;
+}
+/** pixel heights of every non-default row: explicit heights / hidden rows win over font-grown ones */
+export declare function rowSizesOf(d: SheetData): [number, number][];

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

@@ -0,0 +1,80 @@
+/**
+ * Minimal streaming XML tokenizer tailored to OOXML (works inside Web Workers,
+ * where DOMParser is unavailable). Element names are reduced to local names;
+ * attributes too, except relationship-namespace ones which become `r:<local>`.
+ */
+export type Attrs = Record<string, string>;
+export interface SaxHandler {
+    /** Return `true` to skip the element's whole subtree (no `close` is emitted then). */
+    open(name: string, attrs: Attrs, selfClosing: boolean): boolean | void;
+    close(name: string): void;
+    text(text: string): void;
+}
+export declare function decodeEntities(s: string): string;
+export declare class SaxParser {
+    private h;
+    private raw?;
+    private buf;
+    private depth;
+    private skipDepth;
+    private relPrefixes;
+    /**
+     * @param raw optional tap receiving every consumed source segment verbatim (tags, text, comments…),
+     *   called right before the matching handler event. Used for byte-preserving rewrites.
+     */
+    constructor(h: SaxHandler, raw?: ((segment: string) => void) | undefined);
+    write(chunk: string): void;
+    end(): void;
+    private run;
+    private onText;
+    private onOpen;
+    private onClose;
+}
+export declare class AbortedError extends Error {
+    constructor();
+}
+export interface StreamParseOptions {
+    signal?: AbortSignal;
+    /** verbatim source tap, see SaxParser */
+    raw?: (segment: string) => void;
+    /** Called after each chunk (decompressed byte count); may return a promise to yield. */
+    onChunk?: (bytes: number) => void | Promise<void>;
+}
+export declare function parseXmlStream(stream: ReadableStream<Uint8Array>, h: SaxHandler, opts?: StreamParseOptions): Promise<void>;
+export interface XEl {
+    n: string;
+    a: Attrs;
+    c: XEl[];
+    t: string;
+}
+export interface TreeBuilderOptions {
+    /** When set, elements at this depth are built and emitted one by one; ancestors are not kept. */
+    emitDepth?: number;
+    onElement?: (el: XEl) => void;
+    onShallowOpen?: (name: string, attrs: Attrs, depth: number) => void;
+    /** Element local names whose subtree is dropped. */
+    skip?: Set<string>;
+}
+/** Builds XEl trees; resolves mc:AlternateContent by taking the first mc:Choice. */
+export declare class TreeBuilder implements SaxHandler {
+    private o;
+    root: XEl | null;
+    private stack;
+    private parents;
+    private depth;
+    private alt;
+    constructor(o?: TreeBuilderOptions);
+    open(name: string, a: Attrs): boolean | void;
+    close(name: string): void;
+    text(t: string): void;
+}
+export declare function parseXml(xml: string, skip?: Set<string>): XEl;
+export declare function kid(el: XEl | undefined, name: string): XEl | undefined;
+export declare function kids(el: XEl | undefined, name: string): XEl[];
+export declare function path(el: XEl | undefined, ...names: string[]): XEl | undefined;
+export declare function desc(el: XEl | undefined, name: string): XEl | undefined;
+export declare function descAll(el: XEl | undefined, name: string, out?: XEl[]): XEl[];
+export declare function num(v: string | undefined, def?: number): number | undefined;
+/** OOXML on/off value: absent element → undefined, `<x/>` → true. */
+export declare function onOff(el: XEl | undefined, attr?: string): boolean | undefined;
+export declare function textOf(el: XEl | undefined): string;

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

@@ -0,0 +1,35 @@
+import type { ByteSource } from './source';
+export interface ZipEntry {
+    name: string;
+    method: number;
+    flags: number;
+    crc: number;
+    time: number;
+    date: number;
+    compSize: number;
+    size: number;
+    localOffset: number;
+    dataOffset?: number;
+}
+/**
+ * Lazy ZIP reader: parses only the central directory, then inflates single
+ * entries on demand straight from the byte source (native DecompressionStream).
+ */
+export declare class ZipArchive {
+    readonly src: ByteSource;
+    private entries;
+    private constructor();
+    static open(src: ByteSource): Promise<ZipArchive>;
+    private readDirectory;
+    list(): ZipEntry[];
+    get(path: string): ZipEntry | undefined;
+    has(path: string): boolean;
+    private dataOffset;
+    /** Compressed bytes of an entry, as stored (zero-copy Blob slice when the source allows). */
+    rawData(e: ZipEntry): Promise<Blob | Uint8Array>;
+    /** Decompressed stream of an entry. `onRaw` reports compressed bytes consumed. */
+    stream(path: string, onRaw?: (consumed: number, total: number) => void): Promise<ReadableStream<Uint8Array>>;
+    bytes(path: string): Promise<Uint8Array>;
+    text(path: string): Promise<string>;
+}
+export declare function normalize(path: string): string;

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

@@ -0,0 +1,9 @@
+import { type ZipArchive } from './zip';
+export declare function crc32(data: Uint8Array, crc?: number): number;
+export type PartData = Uint8Array | string | (() => ReadableStream<Uint8Array>);
+/**
+ * Re-packs an archive: unchanged entries are copied as stored (no recompression,
+ * zero-copy when the source is a Blob); changed/added entries are deflated.
+ * `changes`: path → new data, or null to delete.
+ */
+export declare function rebuildZip(zip: ZipArchive, changes: Map<string, PartData | null>, type?: string): Promise<Blob>;

package/dist/types/embed.d.ts

@@ -0,0 +1,30 @@
+import './core/default-worker';
+import { DocViewer, type DocViewerProps } from './react/DocViewer';
+export type MountOptions = Omit<DocViewerProps, 'styleTarget'>;
+export interface MountedViewer {
+    update(next: Partial<MountOptions>): void;
+    destroy(): void;
+}
+/** Framework-free embedding: renders the viewer into `el`. */
+export declare function mount(el: HTMLElement, options: MountOptions): MountedViewer;
+/**
+ * `<office-viewer src="/file.xlsx" style="height:600px"></office-viewer>`
+ * Rendered inside a shadow root so host page CSS cannot leak in.
+ * Attributes: src, name, editable, toolbar ("false" to hide), thumbnails ("false" to hide);
+ * real-time collaboration: collab (hub WebSocket URL), room, user (display name).
+ * Property: `file` (File/Blob/ArrayBuffer) for local data.
+ */
+export declare class OfficeViewerElement extends HTMLElement {
+    static observedAttributes: string[];
+    private viewer?;
+    private _file?;
+    get file(): Blob | ArrayBuffer | undefined;
+    set file(v: Blob | ArrayBuffer | undefined);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    private props;
+    private sync;
+}
+export declare function defineElement(tag?: string): void;
+export { DocViewer };

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+import './core/default-worker';
+export { DocViewer, type DocViewerProps } from './react/DocViewer';
+export { DocxView, type DocxViewProps } from './react/docx/DocxView';
+export { XlsxView, type XlsxViewProps } from './react/xlsx/XlsxView';
+export { PptxView, type PptxViewProps } from './react/pptx/PptxView';
+export { SlideView } from './react/pptx/Slide';
+export { useDocument, type DocumentState } from './react/useDocument';
+export { injectStyles, stylesText } from './react/injectStyles';
+export type { Zoom } from './react/common/ZoomControl';
+export { DocumentClient, setDefaultWorker, type OpenOptions } from './core/worker/client';
+export type { DocSource } from './core/source';
+export type { DocKind } from './core/opc';
+export type * from './core/docx/types';
+export type * from './core/xlsx/types';
+export type * from './core/pptx/types';
+export { startCollab, CollabHub, CollabSession, MemoryTransport, WebSocketTransport, type Collab, type CollabOptions, type CollabStatus, type Transport } from './collab';
+export type { PeerInfo, UserInfo } from './collab/protocol';
+export { useCollab, CollabBar, PeerOverlay } from './collab/react';

package/dist/types/react/DocViewer.d.ts

@@ -0,0 +1,43 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import type { DocSource } from '../core/source';
+import type { DocumentClient, OpenOptions } from '../core/worker/client';
+import type { Zoom } from './common/ZoomControl';
+import type { CollabOptions } from '../collab';
+export interface DocViewerProps {
+    /** File, Blob, ArrayBuffer, Uint8Array or URL (HTTP Range requests are used when the server supports them). */
+    src: DocSource | null | undefined;
+    /** Display name (defaults to File.name or the URL's last segment). */
+    name?: string;
+    className?: string;
+    style?: CSSProperties;
+    /** Show the top bar (name, status, progress). Default true. */
+    toolbar?: boolean;
+    /** Extra toolbar content (rendered at the right). */
+    toolbarExtra?: ReactNode;
+    /** Initial zoom for documents and presentations. Default 'fit'. */
+    zoom?: Zoom;
+    /** Show slide thumbnails for presentations. Default true. */
+    thumbnails?: boolean;
+    headers?: Record<string, string>;
+    credentials?: RequestCredentials;
+    /** Custom worker factory, or false to parse on the main thread. */
+    worker?: OpenOptions['worker'];
+    /** Where to inject the stylesheet (document or a shadow root). */
+    styleTarget?: Document | ShadowRoot;
+    onLoad?: (client: DocumentClient) => void;
+    onError?: (error: Error) => void;
+    /** Start in edit mode. Default false (view). */
+    editable?: boolean;
+    /** Show the Edit/View toggle. Default true. */
+    allowEdit?: boolean;
+    /** Receives the saved file instead of downloading it. */
+    onSave?: (file: Blob, name: string) => void | Promise<void>;
+    /** Called when the document gets / loses unsaved changes. */
+    onDirtyChange?: (dirty: boolean) => void;
+    /**
+     * Real-time collaboration: everyone opening the same base document (`src`) with the same `room`
+     * edits it together through the hub at `transport` (see src/collab).
+     */
+    collab?: CollabOptions;
+}
+export declare function DocViewer(props: DocViewerProps): import("react").JSX.Element;

package/dist/types/react/common/ContextMenu.d.ts

@@ -0,0 +1,21 @@
+export interface MenuItem {
+    label: string;
+    run: () => void;
+    disabled?: boolean;
+    /** separator above this item */
+    sep?: boolean;
+    /** shortcut / secondary text */
+    hint?: string;
+    icon?: string;
+    /** small section title above this item */
+    head?: string;
+}
+/** Right-click menu at viewport coordinates; never steals focus from the editor. */
+export declare function ContextMenu({ x, y, items, onClose }: {
+    x: number;
+    y: number;
+    items: MenuItem[];
+    onClose: () => void;
+}): import("react").JSX.Element;
+/** platform modifier label for shortcut hints */
+export declare const MOD: string;

package/dist/types/react/common/Dialog.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+export interface PromptSpec {
+    title: string;
+    label?: string;
+    initial?: string;
+    placeholder?: string;
+    ok?: string;
+    /** multi-line input */
+    area?: boolean;
+    onOk: (value: string) => void;
+    /** extra button (e.g. "Remove link") */
+    extra?: {
+        label: string;
+        run: () => void;
+    };
+    note?: ReactNode;
+}
+/** Small modal prompt (no window.prompt: works in sandboxed / embedded pages). */
+export declare function PromptDialog({ spec, onClose }: {
+    spec: PromptSpec;
+    onClose: () => void;
+}): import("react").JSX.Element;
+/** Short-lived message at the bottom of the viewer. */
+export declare function Toast({ text, onDone }: {
+    text: string;
+    onDone: () => void;
+}): import("react").JSX.Element;

package/dist/types/react/common/Slots.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+import type { DocumentClient } from '../../core/worker/client';
+export interface ViewerApi {
+    /** editor bar mount point (null when the viewer toolbar is hidden) */
+    bar: HTMLElement | null;
+    editable: boolean;
+    /** report unsaved changes */
+    setDirty: (dirty: boolean) => void;
+    /** build + hand off the edited file */
+    save: () => Promise<void>;
+    client: DocumentClient | null;
+}
+export declare const ViewerContext: import("react").Context<ViewerApi>;
+export declare const useViewer: () => ViewerApi;
+/** Renders the editor bar into the viewer's toolbar row. */
+export declare function EditorBar({ children }: {
+    children: ReactNode;
+}): import("react").ReactPortal | null;

package/dist/types/react/common/Status.d.ts

@@ -0,0 +1,6 @@
+/** Toolbar slot provided by DocViewer; views portal their status text into it (no parent re-render). */
+export declare const StatusContext: import("react").Context<HTMLElement | null>;
+export declare function Status({ text, onStatus }: {
+    text: string;
+    onStatus?: (s: string) => void;
+}): import("react").ReactPortal | null;

package/dist/types/react/common/ZoomControl.d.ts

@@ -0,0 +1,6 @@
+export type Zoom = number | 'fit';
+export declare function ZoomControl({ zoom, effective, onChange }: {
+    zoom: Zoom;
+    effective: number;
+    onChange: (z: Zoom) => void;
+}): import("react").JSX.Element;

package/dist/types/react/common/hooks.d.ts

@@ -0,0 +1,20 @@
+import { useLayoutEffect } from 'react';
+import type { DocumentClient } from '../../core/worker/client';
+export declare const useIsoLayoutEffect: typeof useLayoutEffect;
+export declare function useForceUpdate(): [number, () => void];
+/** Element size via ResizeObserver. */
+export declare function useSize<T extends HTMLElement>(): [React.RefObject<T | null>, {
+    w: number;
+    h: number;
+}];
+/** Scroll position of an element, batched to animation frames. */
+export declare function useScroll(ref: React.RefObject<HTMLElement | null>): {
+    x: number;
+    y: number;
+};
+/** Lazily resolves a package part to an object URL (null while loading / unsupported). */
+export declare function useMediaUrl(client: DocumentClient, path: string | undefined, enabled?: boolean): string | null | 'unsupported';
+/** Binary search: last index i with arr[i] <= v. */
+export declare function lowerIndex(arr: ArrayLike<number>, v: number): number;
+export declare function useLatest<T>(v: T): import("react").RefObject<T>;
+export declare function useStableCallback<A extends unknown[], R>(fn: (...a: A) => R): (...a: A) => R;