@twip/web 0.1.0-alpha.1 → 0.1.0-pre.2

package/dist/commands.js

@@ -0,0 +1,188 @@
+/** How each command's argument travels: checked against {@link Encoding} by the compiler. */
+const encodings = {
+    insertText: 'value',
+    insertParagraph: 'none',
+    insertLineBreak: 'none',
+    insertPageBreak: 'none',
+    insertColumnBreak: 'none',
+    insertSectionBreak: 'value',
+    insertTab: 'none',
+    insertSymbol: 'spread',
+    delete: 'spread',
+    cut: 'none',
+    copy: 'none',
+    paste: 'spread',
+    pasteText: 'value',
+    undo: 'none',
+    redo: 'none',
+    repeat: 'none',
+    selectAll: 'none',
+    select: 'value',
+    moveSelection: 'spread',
+    moveToCell: 'value',
+    setSelectionMode: 'value',
+    goBack: 'none',
+    escape: 'none',
+    selectNextObject: 'value',
+    goToPage: 'value',
+    setBold: 'value',
+    setItalic: 'value',
+    setUnderline: 'value',
+    setStrikethrough: 'value',
+    setDoubleStrikethrough: 'value',
+    setSubscript: 'value',
+    setSuperscript: 'value',
+    setSmallCaps: 'value',
+    setAllCaps: 'value',
+    setHidden: 'value',
+    setFont: 'value',
+    setFontSize: 'value',
+    growFont: 'none',
+    shrinkFont: 'none',
+    setFontColor: 'value',
+    setHighlight: 'value',
+    setCharacterSpacing: 'value',
+    setCharacterPosition: 'value',
+    clearFormatting: 'none',
+    changeCase: 'value',
+    copyFormatting: 'none',
+    pasteFormatting: 'none',
+    setAlignment: 'value',
+    setLineSpacing: 'spread',
+    setParagraphSpacing: 'spread',
+    setIndents: 'spread',
+    increaseIndent: 'none',
+    decreaseIndent: 'none',
+    setParagraphStyle: 'value',
+    setList: 'value',
+    setListLevel: 'value',
+    setParagraphFlow: 'spread',
+    setParagraphBorders: 'value',
+    setParagraphShading: 'value',
+    addTabStop: 'spread',
+    moveTabStop: 'spread',
+    deleteTabStop: 'value',
+    clearTabStops: 'none',
+    setDefaultTabStop: 'value',
+    setMargins: 'spread',
+    setOrientation: 'value',
+    setPaperSize: 'spread',
+    setColumns: 'spread',
+    setHeaderFooterDistance: 'spread',
+    setDifferentFirstPage: 'value',
+    setDifferentOddEvenPages: 'value',
+    moveColumnBoundary: 'spread',
+    editHeader: 'none',
+    editFooter: 'none',
+    closeHeaderFooter: 'none',
+    insertPageNumber: 'spread',
+    insertTable: 'spread',
+    insertPicture: 'spread',
+    insertTextBox: 'none',
+    insertFootnote: 'none',
+    insertEndnote: 'none',
+    insertHyperlink: 'spread',
+    editHyperlink: 'spread',
+    removeHyperlink: 'none',
+    insertField: 'spread',
+    insertRows: 'spread',
+    insertColumns: 'spread',
+    deleteRows: 'none',
+    deleteColumns: 'none',
+    deleteTable: 'none',
+    deleteCells: 'value',
+    mergeCells: 'none',
+    splitCells: 'spread',
+    splitTable: 'none',
+    distributeRows: 'none',
+    distributeColumns: 'none',
+    moveRows: 'value',
+    autoFitColumns: 'value',
+    setCellAlignment: 'value',
+    setCellShading: 'value',
+    setCellBorders: 'spread',
+    setCellMargins: 'spread',
+    setHeaderRow: 'value',
+    setRowHeight: 'value',
+    setRowCanBreak: 'value',
+    setColumnWidth: 'value',
+    moveTableColumnBoundary: 'spread',
+    moveTableRowBoundary: 'spread',
+    setTableWidth: 'spread',
+    setTableAlignment: 'value',
+    setTableIndent: 'value',
+    setTableStyle: 'value',
+    setTableStyleOptions: 'spread',
+    setObjectSize: 'spread',
+    resetObjectSize: 'none',
+    setObjectWrap: 'value',
+    setAnchorLocked: 'value',
+    setAltText: 'spread',
+    deleteObject: 'none',
+    setField: 'spread',
+    setFieldResults: 'spread',
+    updateFields: 'spread',
+    setFieldsLocked: 'spread',
+    unlinkFields: 'spread',
+    showFieldCodes: 'spread',
+    setFieldLabels: 'spread',
+    insertControl: 'spread',
+    setControl: 'spread',
+    removeControl: 'spread',
+    fillControl: 'spread',
+    setCheckbox: 'spread',
+    wrapInRepeatingSection: 'spread',
+    removeElement: 'value',
+    replaceInElements: 'spread',
+    markElements: 'spread',
+    setPlaceholderLooks: 'spread',
+    fillPlaceholder: 'spread',
+    writeDataPart: 'spread',
+    removeDataPart: 'spread',
+    setTrackChanges: 'value',
+    setMarkupView: 'value',
+    acceptRevision: 'value',
+    rejectRevision: 'value',
+    acceptRevisionsInSelection: 'none',
+    rejectRevisionsInSelection: 'none',
+    acceptAllRevisions: 'spread',
+    rejectAllRevisions: 'spread',
+    selectRevision: 'value',
+    addComment: 'value',
+    replyToComment: 'spread',
+    editComment: 'spread',
+    deleteComment: 'value',
+    resolveComment: 'spread',
+    setActiveComment: 'value',
+    selectComment: 'value',
+    setAuthorColor: 'spread',
+    setZoom: 'value',
+    setViewOptions: 'spread',
+    setMode: 'value',
+};
+/** Builds a command's op from its method arguments. */
+export function toOp(id, arg) {
+    const how = encodings[id];
+    if (how === 'none' || arg === undefined)
+        return { type: id };
+    if (how === 'value')
+        return { type: id, value: arg };
+    return { type: id, ...arg };
+}
+/** The inverse of {@link toOp}: the command id and its method argument. */
+export function fromOp(op) {
+    const { type, ...fields } = op;
+    const how = encodings[type];
+    if (how === 'none')
+        return [type, undefined];
+    if (how === 'value')
+        return [type, fields.value];
+    return [type, fields];
+}
+/** Builds the `commands` object: every method turns its arguments into an op and runs it. */
+export function createCommands(run) {
+    const commands = {};
+    for (const id of Object.keys(encodings))
+        commands[id] = (arg) => run(toOp(id, arg));
+    return Object.freeze(commands);
+}

package/dist/editor.d.ts

@@ -0,0 +1,218 @@
+import { type CommandInfo, type Commands, type Op } from './commands.js';
+import type { TwipEvents } from './events.js';
+import { FontLibrary } from './fonts/library.js';
+import { type MountedReview, type Review } from './review.js';
+import { type Accessibility, type Shortcuts } from './services/accessibility.js';
+import { type Dialogs } from './services/dialogs.js';
+import { type DataParts, type Elements, type MountedElements } from './services/elements.js';
+import { type Find } from './services/find.js';
+import { type Menus } from './services/menus.js';
+import { type Navigation, type Styles } from './services/navigation.js';
+import { type Ruler, type RulerModelSource, type RulerUnit } from './services/ruler.js';
+import { type Dictionary, type Spelling } from './services/spelling.js';
+import { type Gestures, type View } from './services/view.js';
+import type { EditorState } from './state.js';
+import { type FrameInfo, Method, type Input, type Message, type Transport } from './transport/protocol.js';
+import type { Author, Color, OverlayColors, Warning, WordCount } from './types.js';
+/** Options for a new session. */
+export interface SessionOptions {
+    /** Start read only. Default false. */
+    readOnly?: boolean;
+    /** Start in editing (the default) or design mode. */
+    mode?: 'editing' | 'design';
+    /** Who makes changes. */
+    author?: Author;
+    /** The fonts to draw with: share one per page, {@link FontLibrary.default} (the default). */
+    fonts?: FontLibrary;
+    /** The default language, BCP 47. Default `'en-US'`. */
+    language?: string;
+    /** Spelling dictionaries. */
+    dictionaries?: Dictionary[];
+    /** Turns tracking on after open, unless the document locks it. */
+    trackChanges?: boolean;
+}
+/** Options for {@link Editor.mount}. */
+export interface MountOptions extends SessionOptions {
+    /** The document to open; blank when absent. */
+    document?: Uint8Array;
+    /** Where the engine runs. Default `'auto'`: a worker where supported. */
+    execution?: 'auto' | 'main' | 'worker';
+    /** The built-in rulers. Default off. */
+    rulers?: boolean | {
+        horizontal?: boolean;
+        vertical?: boolean;
+    };
+    /** The ruler unit. Default from `language`: inches for en-US, centimeters otherwise. */
+    rulerUnit?: RulerUnit;
+    /** Room beside the pages for balloons, CSS px. Default 0. */
+    markupPaneWidth?: number;
+    /** The zoom. Default 100. */
+    zoom?: number | 'pageWidth' | 'wholePage';
+    /** The background around the pages. Default `'#E6E6E6'`; the paper stays white. */
+    background?: Color;
+    /**
+     * The caret's blink: ms per phase, 0 for a steady caret. Default 530, or steady while the platform asks for reduced
+     * motion (`prefers-reduced-motion`), which the editor then follows.
+     */
+    caretBlink?: number;
+    /** Stop blinking after this many ms without input, the caret left visible. Default: never. */
+    caretBlinkStopAfter?: number;
+    /**
+     * The colours of what the editor draws over the document. Default: the engine's, or the system's colours while the
+     * platform is in forced-colours (high contrast) mode, which the editor then follows.
+     */
+    overlayColors?: Partial<OverlayColors>;
+    /**
+     * The memory the editor keeps pages' drawing in, bytes: their recordings (default 32 MB). Past it, what was drawn
+     * longest ago goes first.
+     */
+    paintBudget?: {
+        recordings?: number;
+    };
+    /**
+     * The editor draws each attached balloon's leader line (from `balloonsLaidOut`'s placements) in the overlay colours'
+     * `leaders` colour, so the application draws only the cards. Default false: the application draws them.
+     */
+    drawLeaders?: boolean;
+    /** Aborts the mount; everything it created is released. */
+    signal?: AbortSignal;
+}
+/** An exported document. */
+export interface ExportResult {
+    /** The file. */
+    bytes: Uint8Array;
+    /** The revision it captures; later edits don't change these bytes. */
+    revision: number;
+    /** Fidelity warnings. */
+    warnings: Warning[];
+}
+/** A request in the engine's JSON shape: bytes travel as base64. */
+export declare function toWire(value: unknown): unknown;
+/** One editor's session over a transport: the state cache, the listeners and the calls. Internal. */
+export declare class Session {
+    #private;
+    readonly transport: Transport;
+    readonly id: number;
+    state: EditorState;
+    readonly catalog: readonly CommandInfo[];
+    destroyed: boolean;
+    /** Mounted hosts listen for frame and host requests here. */
+    readonly hostListeners: Set<(message: Message) => void>;
+    /** A mounted host's view of an engine event before it is emitted: its viewport points become client points. */
+    adjust: ((type: keyof TwipEvents, event: unknown) => unknown) | undefined;
+    /** Run once on destroy, last added first. */
+    readonly disposers: (() => void)[];
+    private constructor();
+    /** Creates a session on the page's engine: on this thread, or in the page's engine worker. */
+    static start(options?: SessionOptions, execution?: 'main' | 'worker'): Promise<Session>;
+    /** Rejects `destroyed` once destroyed, or with the fault after one, else runs `call`. */
+    guard<T>(call: () => Promise<T>): Promise<T>;
+    /** A structured call, with the request in the engine's JSON shape. */
+    call<T = void>(method: Method, request?: unknown): Promise<T>;
+    /** A call that commits: resolves with its value once the state cache holds the revision it committed. */
+    commit<T = void>(method: Method, request?: unknown): Promise<T>;
+    run(op: Op): Promise<unknown>;
+    input(input: Input): Promise<number>;
+    frame(width: number, height: number): Promise<FrameInfo | null>;
+    subscribe(listener: (state: EditorState) => void): () => void;
+    on<K extends keyof TwipEvents>(type: K, listener: (event: TwipEvents[K]) => void): () => void;
+    /** Whether anything listens to `type`. */
+    listening(type: keyof TwipEvents): boolean;
+    emit<K extends keyof TwipEvents>(type: K, event: TwipEvents[K]): void;
+    destroy(): Promise<void>;
+}
+/** The session behind an editor. Internal: for the SDK's own hosts and tests. */
+export declare function sessionOf(editor: HeadlessEditor): Session;
+/** A session with no DOM: Node, workers, tests and servers. */
+export declare class HeadlessEditor {
+    #private;
+    /** Every edit, one method per command. */
+    readonly commands: Commands;
+    /** Every command's id, label, group, shortcuts and undo grouping. */
+    readonly catalog: readonly CommandInfo[];
+    /** The context menu. */
+    readonly menus: Menus;
+    /** The dialogs. */
+    readonly dialogs: Dialogs;
+    /** Find and replace. */
+    readonly find: Find;
+    /** Spell checking. */
+    readonly spelling: Spelling;
+    /** The document's headings. */
+    readonly navigation: Navigation;
+    /** The document's styles. */
+    readonly styles: Styles;
+    /** Tracked changes and comments. */
+    readonly review: Review;
+    /** The merge designer's elements. */
+    readonly elements: Elements;
+    /** The custom XML data parts. */
+    readonly data: DataParts;
+    /** The ruler model. */
+    readonly ruler: RulerModelSource;
+    /** The accessibility tree. */
+    readonly accessibility: Accessibility;
+    /** Keyboard shortcuts. */
+    readonly shortcuts: Shortcuts;
+    /** Editors are made by {@link HeadlessEditor.create} and {@link Editor.mount}. */
+    protected constructor();
+    /** Creates a session with a blank document. */
+    static create(options?: SessionOptions): Promise<HeadlessEditor>;
+    /** Replaces the document, only after it was read successfully. Resolves with the read's warnings. */
+    open(bytes: Uint8Array, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        warnings: Warning[];
+    }>;
+    /** Replaces the document with a blank one. */
+    newDocument(): Promise<void>;
+    /** Exports the document as DOCX or PDF, with the revision it captures. */
+    export(options: {
+        format: 'docx' | 'pdf';
+        signal?: AbortSignal;
+    }): Promise<ExportResult>;
+    /** Runs several commands atomically: one transaction and one undo step, or nothing when one fails. */
+    batch(ops: readonly Op[], options?: {
+        label?: string;
+    }): Promise<void>;
+    /** The latest state snapshot: synchronous and immutable. */
+    getState(): EditorState;
+    /** Calls `listener` with the current state now, then after every change. Returns the unsubscribe function. */
+    subscribe(listener: (state: EditorState) => void): () => void;
+    /** Listens to an event. Returns the unsubscribe function. */
+    on<K extends keyof TwipEvents>(type: K, listener: (event: TwipEvents[K]) => void): () => void;
+    /** Makes the editor read only, or editable again, without reopening. */
+    setReadOnly(value: boolean): Promise<void>;
+    /** Switches between editing and design mode. */
+    setMode(mode: 'editing' | 'design'): Promise<void>;
+    /** Sets who makes the next changes. */
+    setAuthor(author: Author): Promise<void>;
+    /** Counts words, characters, paragraphs, lines and pages. */
+    wordCount(): Promise<WordCount>;
+    /** Releases the editor. Idempotent; later calls reject `destroyed`. */
+    destroy(): Promise<void>;
+}
+/** An editor mounted in a page: it owns input, rendering, scrolling and its DOM inside the container. */
+export declare class Editor extends HeadlessEditor {
+    #private;
+    /** The element the editor was mounted in. */
+    readonly container: HTMLElement;
+    /** Where the engine runs. */
+    readonly executionMode: 'main' | 'worker';
+    /** The rulers: the model, the built-in rulers and the viewport mapping. */
+    readonly ruler: Ruler;
+    /** Review, with the markup pane and balloons. */
+    readonly review: MountedReview;
+    /** Elements, with drop targets and hit testing. */
+    readonly elements: MountedElements;
+    /** The view. */
+    readonly view: View;
+    /** The pointer gestures. */
+    readonly gestures: Gestures;
+    /** Editors are made by {@link Editor.mount}. */
+    protected constructor();
+    /** Mounts an editor in `container`, which must be empty of other editors. Resolves when it accepts commands. */
+    static mount(container: HTMLElement, options?: MountOptions): Promise<Editor>;
+    /** Focuses the editor, keeping the selection. Mounting never takes focus by itself. */
+    focus(): void;
+}