@nutrient-sdk/document-authoring/lib/index.d.cts

A web SDK for word processing and rich text capabilities.

/**
 * @public
 */
export declare type Assets = {
    /**
     * The base path to the Document Authoring assets.
     * If not set, assets will be fetched from a public CDN.
     * To self-host the assets, consult the `README.md`.
     */
    base?: string;
};

/**
 * @public
 */
export declare type BlobInput = Promise<Response | Blob | ArrayBuffer> | Response | Blob | ArrayBuffer;

/**
 * Creates an instance of the Document Authoring system which can be shared between different tasks
 * like creating editors, importing Word documents or creating PDFs.
 *
 * This loads the JavaScript and WASM code and manages the font cache.
 * @public
 */
export declare const createDocAuthSystem: (options?: CreateDocAuthSystemOptions) => Promise<DocAuthSystem>;

/**
 * @public
 */
export declare type CreateDocAuthSystemOptions = {
    licenseKey?: string;
    /**
     * Assets configuration. If unset the system will use the assets from a CDN.
     */
    assets?: Assets;
    /**
     * Font configuration.
     */
    fontConfig?: FontConfig;
};

/**
 * @public
 */
export declare type CreateDocumentFromPlaintextOptions = {
    /**
     * Defines the size of the document pages.
     * Can be custom dimensions or standard sizes ('Letter', 'A4', 'A5', 'A6').
     */
    pageSize?: {
        width: number;
        height: number;
    } | 'Letter' | 'A4' | 'A5' | 'A6';
    /**
     * Defines the margins of the document pages.
     */
    pageMargins?: {
        left: number;
        right: number;
        bottom: number;
        top: number;
        header?: number;
        footer?: number;
    };
};

/**
 * @public
 */
export declare type CreateEditorOptions = {
    /**
     * The document to attach to this editor.
     * If no document is provided, an empty document will be created.
     * @see {@link DocAuthEditor.setCurrentDocument}
     */
    document?: DocAuthDocument;
    /**
     * Allows toggling/changing various UI options.
     *
     * See {@link UIOptions}
     */
    ui?: UIOptions;


};

/**
 * @hidden
 */
declare const _default: {
    createDocAuthSystem: (options?: CreateDocAuthSystemOptions) => Promise<DocAuthSystem>;
    defaultFontIndex: DefaultFontIndex;
};
export default _default;

/**
 * The default font index that is part of the Document Authoring SDK bundle.
 *
 * See {@link FontConfig} for how to customize the set of fonts used by the SDK.
 *
 * @public
 */
export declare type DefaultFontIndex = {
    type: 'default-index';
};

/**
 * The default font index that is part of the Document Authoring SDK bundle.
 *
 * See {@link FontConfig} for how to customize the set of fonts used by the SDK.
 *
 * @public
 */
export declare const defaultFontIndex: DefaultFontIndex;

/**
 * @public
 */
export declare type DocAuthDocument = {
    /**
     * Returns the current document in the Document Authoring format as a JavaScript object.
     * This object can be safely persisted.
     */
    saveDocument(): Promise<object>;
    /**
     * Returns the current document in the Document Authoring format as a JSON string.
     * This string can be safely persisted.
     * @see {@link DocAuthDocument.saveDocument}
     */
    saveDocumentJSONString(): Promise<string>;
    /**
     * Exports a snapshot of the current document as a PDF file.
     */
    exportPDF(options?: ExportPDFOptions): Promise<ArrayBuffer>;
    /**
     * Exports a snapshot of the current document as a DOCX file.
     */
    exportDOCX(options?: ExportDOCXOptions): Promise<ArrayBuffer>;

    /**
     * The `DocAuthSystem` this document is bound to.
     */
    docAuthSystem(): DocAuthSystem;
};

/**
 * A `string` will be treated as a document authoring document in JSON format and loaded.
 * An `object` will be treated as a JavaScript representation of a Document Authoring document
 * (e.g. the result of `JSON.parse` on a Document Authoring JSON string).
 *
 * @public
 */
export declare type DocAuthDocumentInput = string | object | Blob | Response | Promise<string | object | Blob | Response>;

/**
 * @public
 */
export declare type DocAuthEditor = {
    /**
     * Attaches the provided document as the current document to the editor.
     */
    setCurrentDocument(doc: DocAuthDocument): void;
    /**
     * Returns a reference to the currently attached document.
     */
    currentDocument(): DocAuthDocument;
    /**
     * Removes all DOM elements and releases resources held by the editor.
     * Note: This does not release the underlying `DocAuthSystem`. Use `DocAuthSystem.destroy` after calling `DocAuthEditor.destroy` for a complete teardown.
     */
    destroy(): void;
    /**
     * Retrieves the `DocAuthSystem` instance this editor is bound to.
     */
    docAuthSystem(): DocAuthSystem;

    /**
     * Adds an event listener that will be called every time the specified event is emitted.
     *
     * @param event - The event name to listen for
     * @param handler - The function to call when the event is emitted
     * @returns The editor instance for method chaining
     *
     * @example
     * ```typescript
     * // Get the latest document content
     * editor.on('content.change', async () => console.log(await editor.currentDocument().saveDocument()));
     * ```
     *
     * @eventMap DocAuthEditorEvents
     */
    on: <EventName extends keyof DocAuthEditorEvents>(event: EventName, handler: DocAuthEditorEventHandler<EventName>) => DocAuthEditor;
    /**
     * Removes an event listener. If no handler is provided, removes all listeners for the event.
     *
     * @param event - The event name to remove listeners from
     * @param handler - The specific handler to remove (optional)
     * @returns The editor instance for method chaining
     *
     * @example
     * ```typescript
     * // Remove specific handler
     * editor.off('content.change', myHandler);
     *
     * // Remove all handlers for an event
     * editor.off('content.change');
     * ```
     *
     * @eventMap DocAuthEditorEvents
     */
    off: <EventName extends keyof DocAuthEditorEvents>(event: EventName, handler?: DocAuthEditorEventHandler<EventName>) => DocAuthEditor;
    /**
     * Adds an event listener that will be called only once when the specified event is emitted.
     * The listener is automatically removed after being called.
     *
     * @param event - The event name to listen for
     * @param handler - The function to call when the event is emitted
     * @returns The editor instance for method chaining
     *
     * @example
     * ```typescript
     * editor.once('document.load', () => {
     *   console.log('Document loaded for the first time');
     * });
     * ```
     *
     * @eventMap DocAuthEditorEvents
     */
    once: <EventName extends keyof DocAuthEditorEvents>(event: EventName, handler: DocAuthEditorEventHandler<EventName>) => DocAuthEditor;
};

/**
 * @public
 * @excludeFromDocs
 */
export declare type DocAuthEditorEventHandler<EventName extends keyof DocAuthEditorEvents> = DocAuthEditorEvents[EventName] extends void ? () => void : (payload: DocAuthEditorEvents[EventName]) => void;

/**
 * @public
 * @excludeFromDocs
 */
export declare type DocAuthEditorEvents = {
    /**
     * Fired when a document is initially loaded into the editor.
     * This event is triggered once per document load, including when switching documents.
     */
    'document.load': void;
    /**
     * Fired when the document content has changed due to user editing or programmatic modifications.
     * Use this event to react to document changes, such as saving drafts or updating UI state.
     */
    'content.change': void;
};

/**
 * A `DocAuthSystem` instance holds the internal WASM engine and loaded fonts.
 * It is used to load or import documents and create `DocAuthEditor` instances.
 *
 * @public
 */
export declare type DocAuthSystem = {
    /**
     * Loads a document stored in the Document Authoring format.
     * The document can be provided as a JSON string or a JavaScript object.
     */
    loadDocument(documentInput: DocAuthDocumentInput): Promise<DocAuthDocument>;
    /**
     * Imports a DOCX document.
     */
    importDOCX(docx: BlobInput, options?: ImportDOCXOptions): Promise<DocAuthDocument>;
    /**
     * Creates an editor in the specified HTML element.
     * **IMPORTANT**: The `position` of the target element cannot be `static` or unset. If unsure, use `relative`.
     */
    createEditor(target: HTMLElement, options?: CreateEditorOptions): Promise<DocAuthEditor>;
    /**
     * Creates a document from plain text by interpreting patterns and replacing characters.
     * E.g.:
     * - `\n` creates a line break in a paragraph
     * - `\n\n` separates paragraphs
     * - `\t` is replaced with spaces
     */
    createDocumentFromPlaintext(text: string, options?: CreateDocumentFromPlaintextOptions): Promise<DocAuthDocument>;
    /**
     * Releases resources held by the system.
     * **IMPORTANT**: The system and any editors created by this system can no longer be used after calling this.
     */
    destroy(): void;
};

/**
 * @public
 */
export declare type ExportDOCXOptions = {
    /**
     * An optional signal to abort the export operation.
     */
    abortSignal?: AbortSignal;
};

/**
 * @public
 */
export declare type ExportPDFOptions = {
    /**
     * An optional signal to abort the export operation.
     */
    abortSignal?: AbortSignal;
    /**
     * Generate a PDF/A compliant PDF. Defaults to `false`.
     */
    PDF_A?: boolean;
};

/**
 * @public
 */
export declare type FontConfig = {
    /**
     * The set of fonts available to the Document Authoring system.
     * If unset the {@link DefaultFontIndex} is used.
     *
     * Individual fonts can be added directly using a {@link FontFile} or loaded by the system as they are needed using
     * a pre-built {@link FontIndex} that all lists all available fonts. A {@link FontIndex} is the recommended way to provide
     * a set of fonts to the system in a production environment.
     *
     * @example
     * Providing two additional fonts next to the built-in default fonts. In this scenario the system will load both fonts during initialization:
     * ```TypeScript
     * fonts: [
     *   DocAuth.defaultFontIndex,
     *   { type: 'file', blob: fetch('/fonts/awesome.ttf') },
     *   { type: 'file', blob: fetch('/fonts/more-awesome.ttf') },
     * ],
     * ```
     *
     * @example
     * Providing multiple additional fonts using a font index in addition to the built-in default fonts. In this scenario the system will only load the fonts that are actually needed:
     * ```TypeScript
     * fonts: [
     *   DocAuth.defaultFontIndex,
     *   {
     *     type: 'index',
     *     index: fetch('/fonts/font-index.json'),
     *     loadFn: (name) => fetch(`/fonts/${name}`),
     *   },
     * ],
     * ```
     */
    fonts?: (DefaultFontIndex | FontIndex | FontFile)[];
};

/**
 * `FontFile` provides a quick way to add a single additional font to the system. The system will load and scan
 * all provided `FontFile`s to extract all the required metadata during initialization.
 *
 * For a production system we recommend building a {@link FontIndex} of all available fonts, which enables
 * the system to load only fonts that are actually needed.
 *
 * @example
 * ```TypeScript
 * { type:'file', blob: fetch('/fonts/awesome.ttf') }
 * ```
 *
 * @public
 */
export declare type FontFile = {
    type: 'file';
    blob: BlobInput;
};

/**
 * A `FontIndex` is the preferred way to add additional fonts to the system.
 *
 * Document Authoring can efficiently load a single `index` of available fonts, and will then only load the actually
 * required fonts as they are needed by calling `loadFn` with the font name. `loadFn` must return a `BlobInput` for
 * the font file requested.
 *
 * In order to generate a font index from a set of fonts you want to provide to your users, use the Document Authoring CLI utility:
 *
 * ```shell
 * npx document-authoring create-font-index --scan-directory path-to-fonts --write-to font-index.json
 * ```
 *
 * This will generate a `font-index.json` file that you can then host and load using the `FontIndex` configuration.
 *
 * @example
 * ```TypeScript
 * {
 *   type: 'index',
 *   index: fetch('/fonts/font-index.json'),
 *   loadFn: (name) => fetch(`/fonts/${name}`),
 * }
 * ```
 *
 * @public
 */
export declare type FontIndex = {
    type: 'index';
    index: BlobInput;
    loadFn: (name: string) => BlobInput;
};

/**
 * @public
 */
export declare type ImportDOCXOptions = {
    /**
     * An optional signal to abort the export operation.
     */
    abortSignal?: AbortSignal;
};

/**
 * English, French and German are currently supported (two-letter ISO 639-1 codes).
 *
 * See {@link UIOptions | UIOptions.locale}
 *
 * @public
 */
export declare type Locale = 'en' | 'fr' | 'de';

/**
 * Configuration options for the user interface.
 *
 * @public
 */
export declare type UIOptions = {
    /**
     * The locale to use for displaying text, formatting numbers etc.
     *
     * `auto` will automatically detect the user's locale based on their browser settings. If this doesn't match a supported locale, it will fall back to `en`.
     *
     * @defaultValue `auto`
     */
    locale?: Locale | 'auto';
    /**
     * The unit system for measurements shown in the UI.
     *
     * @defaultValue `pt`
     */
    unit?: Unit;
    /**
     * Configuration for the ruler feature.
     */
    ruler?: {
        /**
         * Controls whether the ruler is shown by default when the editor loads.
         *
         * @defaultValue `true`
         */
        enabled: boolean;
    };

};

/**
 * The list of supported units in Document Authoring.
 *
 * See {@link UIOptions | UIOptions.unit}
 *
 * @public
 */
export declare type Unit = 'cm' | 'in' | 'pt' | 'pc' | 'mm';

export { }