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

A web SDK for word processing and rich text capabilities.

/**
 * Action definition that users can register
 *
 * @since 1.9.0
 * @public
 * @sidebarGroup actions
 * @sidebarGroupOrder 2
 */
export declare type Action = BuiltInAction | CustomAction;

/**
 * @public
 * @sidebarGroup core
 * @sidebarGroupOrder 3
 * @see {@linkcode CreateDocAuthSystemOptions} for all available options when creating a DocAuthSystem.
 */
export declare type Assets = {
    /**
     * The base path to the Document Authoring assets. If not set, assets will be fetched from a public CDN.
     *
     * @see <a href="https://www.nutrient.io/guides/document-authoring/self-hosting-assets/" target="_blank">Self-hosting assets guide</a> for information about hosting assets elsewhere.
     */
    base?: string;
};

/**
 * Input type for binary data like DOCX files or font files. Used by {@linkcode DocAuthSystem.importDOCX} and font loading functions.
 *
 * @example
 *
 * ```ts
 * // From a Blob (e.g. file input)
 * const fileInput = document.querySelector('input[type="file"]');
 * const blob = fileInput.files[0];
 * const doc = await system.importDOCX(blob);
 *
 * // From an ArrayBuffer
 * const arrayBuffer = await fetch('/document.docx').then((r) => r.arrayBuffer());
 * const doc = await system.importDOCX(arrayBuffer);
 *
 * // From a fetch Response
 * const response = await fetch('/document.docx');
 * const doc = await system.importDOCX(response);
 *
 * // From a Promise (automatically awaited)
 * const doc = await system.importDOCX(fetch('/document.docx'));
 *
 * // From a Promise that resolves to ArrayBuffer
 * const bufferPromise = fetch('/document.docx').then((r) => r.arrayBuffer());
 * const doc = await system.importDOCX(bufferPromise);
 * ```
 *
 * @public
 * @sidebarGroup core
 * @sidebarGroupOrder 10
 * @see {@linkcode DocAuthSystem.importDOCX} for importing DOCX files.
 * @see {@linkcode FontFile} for using BlobInput with fonts.
 */
export declare type BlobInput = Promise<Response | Blob | ArrayBuffer> | Response | Blob | ArrayBuffer;

/**
 * Built-in actions have pre-defined IDs from {@linkcode BuiltInActionId} and automatically use default handlers if not provided. This allows you
 * to customize things without having to reimplement internal functionality.
 *
 * @since 1.9.0
 * @example
 *
 * ```ts
 * import { defaultActions } from '@nutrient-sdk/document-authoring';
 *
 * // Remove all built-in actions except bold built-in (handler auto-populated)
 * editor.setActions([{ id: 'formatting.bold', label: 'Bold', shortcuts: ['Mod+B'] }]);
 *
 * // Override the default handler for bold
 * editor.setActions([
 * 	...defaultActions.filter(({ id }) => id !== 'formatting.bold'),
 * 	{
 * 		id: 'formatting.bold',
 * 		label: 'Bold',
 * 		shortcuts: ['Mod+B'],
 * 		handler: () => {
 * 			console.log('Custom bold implementation');
 * 		},
 * 	},
 * ]);
 *
 * // Customize shortcuts and labels while keeping default behavior
 * editor.setActions([
 * 	...defaultActions.filter(({ id }) => id !== 'document.export-pdf'),
 * 	{ id: 'document.export-pdf', label: 'Download PDF', shortcuts: ['Mod+P'] },
 * ]);
 * ```
 *
 * @public
 * @sidebarGroup actions
 * @sidebarGroupOrder 3
 * @see {@linkcode BuiltInActionId} for available built-in action IDs.
 * @see {@linkcode CustomAction} for defining custom actions.
 */
export declare type BuiltInAction = {
    id: BuiltInActionId;
    label: string;
    description?: string;
    /**
     * Keyboard shortcuts for the action. Use "Mod" as the primary modifier key - it will be automatically resolved to:
     *
     * - "Ctrl" on Windows/Linux
     * - "⌘" (Command) on Mac
     *
     * Examples:
     *
     * - "Mod+B" becomes "Ctrl+B" on Windows, "⌘B" on Mac
     * - "Mod+Shift+P" becomes "Ctrl+Shift+P" on Windows, "⌘⇧P" on Mac
     */
    shortcuts?: string[];
    /** Icon as data URI (e.g., data:image/svg+xml;base64,... or data:image/png;base64,...). Only data:image/ URIs are allowed for security. */
    icon?: string;
    isEnabled?: () => boolean;
    /** Handler function - optional for built-in actions (defaults will be used if omitted) */
    handler?: (...args: unknown[]) => void | Promise<void>;
};

/**
 * Actions API - Type definitions for registering and executing editor actions
 */
/**
 * Built-in action IDs that have default implementations
 *
 * @since 1.9.0
 * @public
 * @sidebarGroup actions
 * @sidebarGroupOrder 5
 */
export declare type BuiltInActionId = 'document.undo' | 'document.redo' | 'document.export-pdf' | 'document.export-docx' | 'formatting.bold' | 'formatting.italic' | 'formatting.underline' | 'formatting.strikethrough' | 'formatting.subscript' | 'formatting.superscript' | 'formatting.clear' | 'insert.page-break' | 'insert.section-break-next-page' | 'insert.section-break-continuous' | 'insert.column-break' | 'insert.image' | 'insert.link' | 'table.insert' | 'table.delete' | 'table.insert-row-above' | 'table.insert-row-below' | 'table.insert-column-left' | 'table.insert-column-right' | 'table.delete-row' | 'table.delete-column' | 'table.merge-cells' | 'table.split-cells' | 'view.zoom-in' | 'view.zoom-out' | 'view.zoom-reset' | 'view.toggle-ruler' | 'view.toggle-formatting-marks' | 'layout.align-left' | 'layout.align-center' | 'layout.align-right' | 'layout.align-justify' | 'layout.increase-indent' | 'layout.decrease-indent' | 'layout.bulleted-list' | 'layout.numbered-list' | 'style.apply';

/**
 * 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
 * @sidebarGroup core
 * @sidebarGroupOrder 1
 * @see <a href="https://www.nutrient.io/sdk/document-authoring/getting-started/" target="_blank">Getting started guide</a>
 */
export declare function createDocAuthSystem(options?: CreateDocAuthSystemOptions): Promise<DocAuthSystem>;

/**
 * Configuration options for creating a Document Authoring system.
 *
 * @example
 *
 * ```ts
 * // Basic setup with CDN assets
 * // Don't forget your license key with all the examples below
 * const system = await createDocAuthSystem({
 * 	licenseKey: 'YOUR_LICENSE_KEY',
 * });
 * ```
 *
 * @example
 *
 * ```ts
 * // Self-hosted assets
 * const system = await createDocAuthSystem({
 * 	assets: {
 * 		base: '/static/assets/',
 * 	},
 * });
 * ```
 *
 * @example
 *
 * ```ts
 * // With custom fonts using FontFile
 * import { defaultFontIndex } from '@nutrient-sdk/document-authoring';
 *
 * const system = await createDocAuthSystem({
 * 	fontConfig: {
 * 		fonts: [
 * 			defaultFontIndex,
 * 			{ type: 'file', blob: fetch('/fonts/custom-font.ttf') },
 * 			{ type: 'file', blob: fetch('/fonts/another-font.ttf') },
 * 		],
 * 	},
 * });
 * ```
 *
 * @example
 *
 * ```ts
 * // With custom font index for large font libraries
 * const system = await createDocAuthSystem({
 * 	fontConfig: {
 * 		fonts: [
 * 			defaultFontIndex,
 * 			{
 * 				type: 'index',
 * 				index: fetch('/fonts/font-index.json'),
 * 				loadFn: (name) => fetch(`/fonts/${name}`),
 * 			},
 * 		],
 * 	},
 * });
 * ```
 *
 * @example
 *
 * ```ts
 * // Complete configuration
 * const system = await createDocAuthSystem({
 * 	licenseKey: 'YOUR_LICENSE_KEY',
 * 	assets: {
 * 		base: '/static/docauth/',
 * 	},
 * 	fontConfig: {
 * 		fonts: [
 * 			defaultFontIndex,
 * 			{
 * 				type: 'index',
 * 				index: fetch('/fonts/corporate-fonts.json'),
 * 				loadFn: (name) => fetch(`/fonts/${name}`),
 * 			},
 * 		],
 * 	},
 * });
 * ```
 *
 * @public
 * @sidebarGroup core
 * @sidebarGroupOrder 2
 * @see {@linkcode createDocAuthSystem} for creating a system instance.
 * @see {@linkcode FontConfig} for font configuration details.
 * @see {@linkcode Assets} for asset hosting configuration.
 */
export declare type CreateDocAuthSystemOptions = {
    licenseKey?: string;
    /**
     * Assets configuration. If unset the system will use the assets from a CDN.
     *
     * @see <a href="https://www.nutrient.io/guides/document-authoring/self-hosting-assets/" target="_blank">Self-hosting assets guide</a> for information about hosting assets elsewhere.
     */
    assets?: Assets;
    /**
     * @since 1.0.26
     *
     * Font configuration.
     */
    fontConfig?: FontConfig;
};

/**
 * Options for creating documents from plain text.
 *
 * @example
 *
 * ```ts
 * // Create document with default page settings
 * const doc = await system.createDocumentFromPlaintext('Hello World');
 * ```
 *
 * @example
 *
 * ```ts
 * // Create document with standard page size
 * const doc = await system.createDocumentFromPlaintext('My content', {
 * 	pageSize: 'A4',
 * });
 * ```
 *
 * @example
 *
 * ```ts
 * // Create document with custom page size (in points, 72 points = 1 inch)
 * const doc = await system.createDocumentFromPlaintext('My content', {
 * 	pageSize: { width: 612, height: 792 }, // US Letter in points
 * });
 * ```
 *
 * @example
 *
 * ```ts
 * // Create document with custom margins
 * const doc = await system.createDocumentFromPlaintext('My content', {
 * 	pageSize: 'Letter',
 * 	pageMargins: {
 * 		left: 72, // 1 inch
 * 		right: 72, // 1 inch
 * 		top: 72, // 1 inch
 * 		bottom: 72, // 1 inch
 * 	},
 * });
 * ```
 *
 * @example
 *
 * ```ts
 * // Process multi-paragraph text
 * const text = `First paragraph
 *
 * Second paragraph with line break\nand continuation.
 *
 * Third paragraph with\ttab character.`;
 * const doc = await system.createDocumentFromPlaintext(text, {
 * 	pageSize: 'Letter',
 * });
 * ```
 *
 * @public
 * @sidebarGroup core
 * @sidebarGroupOrder 8
 * @see {@linkcode DocAuthSystem.createDocumentFromPlaintext} for creating documents from text.
 */
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;
    };
};

/**
 * Options for creating an editor instance.
 *
 * @example
 *
 * ```ts
 * // Create editor with empty document
 * const editor = await system.createEditor(targetElement);
 * ```
 *
 * @example
 *
 * ```ts
 * // Create editor with existing document
 * const doc = await system.loadDocument(docJSON);
 * const editor = await system.createEditor(targetElement, { document: doc });
 * ```
 *
 * @example
 *
 * ```ts
 * // Create editor with custom UI settings
 * const editor = await system.createEditor(targetElement, {
 * 	ui: {
 * 		locale: 'de',
 * 		unit: 'cm',
 * 		ruler: { enabled: false },
 * 	},
 * });
 * ```
 *
 * @example
 *
 * ```ts
 * // Create editor with custom actions and toolbar
 * const editor = await system.createEditor(targetElement, {
 * 	ui: {
 * 		actions: [
 * 			...defaultActions,
 * 			{
 * 				id: 'custom.save',
 * 				label: 'Save',
 * 				shortcuts: ['Mod+S'],
 * 				handler: async () => {
 * 					const doc = await editor.currentDocument().saveDocument();
 * 					await fetch('/api/save', { method: 'POST', body: JSON.stringify(doc) });
 * 				},
 * 			},
 * 		],
 * 		toolbar: {
 * 			items: [
 * 				{ type: 'built-in', id: 'undo', builtInType: 'undo' },
 * 				{ type: 'built-in', id: 'redo', builtInType: 'redo' },
 * 				{ type: 'separator', id: 'sep-1' },
 * 				{ type: 'action', id: 'save-btn', actionId: 'custom.save' },
 * 			],
 * 		},
 * 	},
 * });
 * ```
 *
 * @public
 * @sidebarGroup core
 * @sidebarGroupOrder 6
 * @see {@linkcode DocAuthSystem.createEditor} for creating editors.
 * @see {@linkcode UIOptions} for available UI configuration options.
 */
export declare type CreateEditorOptions = {
    /**
     * The document to attach to this editor. If no document is provided, an empty document will be created.
     *
     * @see {@linkcode DocAuthEditor.setCurrentDocument} for setting the document after the editor is created.
     */
    document?: DocAuthDocument;
    /**
     * @since 1.5.0 Allows toggling/changing various UI options.
     */
    ui?: UIOptions;


};

/**
 * Custom actions allow you to add your own functionality to the editor. Unlike {@linkcode BuiltInAction}, custom actions must provide a handler
 * function.
 *
 * @since 1.9.0
 * @example
 *
 * ```ts
 * import { defaultActions } from '@nutrient-sdk/document-authoring';
 *
 * // Add a custom action with keyboard shortcut
 * editor.setActions([
 * 	...defaultActions,
 * 	{
 * 		id: 'custom.insert-signature',
 * 		label: 'Insert Signature',
 * 		shortcuts: ['Mod+Shift+S'],
 * 		handler: () => {
 * 			editor.insertTextAtCursor('\n\nBest regards,\nJohn Doe');
 * 		},
 * 	},
 * ]);
 *
 * // Add a custom action with custom icon
 * editor.setActions([
 * 	...defaultActions,
 * 	{
 * 		id: 'custom.save',
 * 		label: 'Save Document',
 * 		icon: 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiPi4uLjwvc3ZnPg==',
 * 		handler: async () => {
 * 			const doc = await editor.currentDocument().saveDocument();
 * 			await fetch('/api/save', {
 * 				method: 'POST',
 * 				body: JSON.stringify(doc),
 * 			});
 * 		},
 * 	},
 * ]);
 *
 * // Add a conditional action (disabled when no cursor/selection)
 * editor.setActions([
 * 	...defaultActions,
 * 	{
 * 		id: 'custom.insert-date',
 * 		label: "Insert Today's Date",
 * 		isEnabled: () => editor.hasActiveCursor(),
 * 		handler: () => {
 * 			const date = new Date().toLocaleDateString();
 * 			editor.insertTextAtCursor(date);
 * 		},
 * 	},
 * ]);
 * ```
 *
 * @public
 * @sidebarGroup actions
 * @sidebarGroupOrder 4
 * @see {@linkcode BuiltInAction} for built-in actions with default implementations.
 * @see {@linkcode ToolbarActionItem} for adding custom actions to the toolbar.
 */
export declare type CustomAction = {
    /** Unique identifier for this action (must not be a {@linkcode BuiltInActionId}) */
    id: string;
    label: string;
    description?: string;
    /**
     * Keyboard shortcuts for the action. Use "Cmd" as the modifier key - it will be resolved to:
     *
     * - "Ctrl" on Windows/Linux (for keyboard handling)
     * - "⌘" on Mac (for keyboard handling)
     * - "Ctrl" or "⌘" for display based on platform
     *
     * Examples:
     *
     * - "Cmd+B" becomes "Ctrl+B" on Windows, "⌘B" on Mac
     * - "Cmd+Shift+P" becomes "Ctrl+Shift+P" on Windows, "⌘⇧P" on Mac
     */
    shortcuts?: string[];
    /** Icon as data URI (e.g., data:image/svg+xml;base64,... or data:image/png;base64,...). Only data:image/ URIs are allowed for security. */
    icon?: string;
    /** Optional function to determine if this action should be enabled */
    isEnabled?: () => boolean;
    /** Handler function that executes when the action is triggered (required for custom actions) */
    handler: (...args: unknown[]) => void | Promise<void>;
};

/**
 * @ignore
 */
declare const _default: {
    createDocAuthSystem: typeof createDocAuthSystem;
    defaultFontIndex: DefaultFontIndex;
    defaultActions: BuiltInAction[];
    defaultToolbarConfig: ToolbarConfig;
};
export default _default;

/**
 * Get the default set of actions available in the editor. Can be combined with custom actions.
 *
 * Note: Built-in actions (those with IDs from {@linkcode BuiltInActionId}) can omit handlers - they will be automatically populated with default
 * implementations when passed to {@linkcode DocAuthEditor#setActions | editor.setActions()}. This allows you to customize labels, shortcuts, and order without needing to
 * implement the behavior yourself. Built-in handlers can also be overridden by providing your own handler function.
 *
 * Custom actions (those with any other string ID) must provide a handler function.
 *
 * @since 1.9.0
 * @example
 *
 * ```ts
 * import { defaultActions } from '@nutrient-sdk/document-authoring';
 *
 * // Customize a built-in action's metadata (handlers auto-populate for built-in actions)
 * editor.setActions([
 * 	...defaultActions.filter(({ id }) => id !== 'formatting.bold'),
 * 	{ id: 'formatting.bold', label: 'Make Bold', shortcuts: ['Ctrl+B'] },
 * ]);
 *
 * // Override a built-in action's behavior
 * editor.setActions([
 * 	...defaultActions.filter(({ id }) => id !== 'formatting.bold'),
 * 	{ id: 'formatting.bold', label: 'Bold', handler: () => console.log('custom bold!') },
 * ]);
 *
 * // Add custom actions (must provide handler)
 * editor.setActions([
 * 	...defaultActions.filter((a) => a.id !== 'document.export-pdf'),
 * 	{ id: 'custom.my-action', label: 'My Action', handler: () => console.log('clicked') },
 * ]);
 * ```
 *
 * @public
 * @sidebarGroup actions
 * @sidebarGroupOrder 1
 */
export declare const defaultActions: BuiltInAction[];

/**
 * The default font index that is part of the Document Authoring SDK bundle.
 *
 * See {@linkcode FontConfig} for how to customize the set of fonts used by the SDK.
 *
 * @since 1.0.26
 * @public
 * @sidebarGroup fonts
 * @sidebarGroupOrder 2
 * @see {@linkcode FontConfig} for configuring fonts, including using the default font index.
 */
export declare type DefaultFontIndex = {
    type: 'default-index';
};

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

/**
 * Get the default toolbar configuration. Can be used as-is or customized.
 *
 * @since 1.9.0
 * @example
 *
 * ```ts
 * import { defaultToolbarConfig } from '@nutrient-sdk/document-authoring';
 *
 * // remove the first two items
 * editor.setToolbarConfig({
 * 	...defaultToolbarConfig,
 * 	items: defaultToolbarConfig.items.slice(2),
 * });
 *
 * // add a custom item
 * editor.setToolbarConfig({
 * 	...defaultToolbarConfig,
 * 	items: [...defaultToolbarConfig.items, myCustomItem],
 * });
 * ```
 *
 * @public
 * @sidebarGroup toolbar
 * @sidebarGroupOrder 1
 *
 * @see {@linkcode CustomAction} for the shape of custom items.
 */
export declare const defaultToolbarConfig: ToolbarConfig;

/**
 * A document instance. Holds the content and provides methods for saving, exporting to PDF/DOCX, and more.
 *
 * Create documents via {@linkcode DocAuthEditor} and/or {@linkcode DocAuthSystem}.
 *
 * @public
 * @sidebarGroup core
 * @sidebarGroupOrder 9
 */
export declare type DocAuthDocument = {
    /**
     * Returns the current document in the Document Authoring format as a JavaScript object. This object can be safely persisted.
     *
     * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/docjson/" target="_blank">DocJSON guide</a>
     */
    saveDocument(): Promise<object>;
    /**
     * Returns the current document in the Document Authoring format as a JSON string. This string can be safely persisted.
     *
     * @see {@linkcode DocAuthDocument.saveDocument}
     * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/docjson/" target="_blank">DocJSON guide</a>
     */
    saveDocumentJSONString(): Promise<string>;
    /**
     * Exports a snapshot of the current document as a PDF file.
     *
     * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/pdf/" target="_blank">PDF export guide</a>
     */
    exportPDF(options?: ExportPDFOptions): Promise<ArrayBuffer>;
    /**
     * Exports a snapshot of the current document as a DOCX file.
     *
     * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/docx/" target="_blank">DOCX export guide</a>
     */
    exportDOCX(options?: ExportDOCXOptions): Promise<ArrayBuffer>;
    /**
     * Executes a transaction to programmatically read or modify the document.
     * @since 1.10.0
     *
     * @remarks
     * Provides programmatic access to the document structure through a draft document that can be
     * read and modified. Changes are atomic and isolated until the transaction commits.
     *
     * The callback executes after all pending transactions and input have been processed. While
     * the callback runs, document access is blocked, preventing any UI interactions until the
     * transaction completes.
     *
     * @param callback - A {@linkcode TransactionCallback} function that receives a draft document
     * @returns A Promise that resolves to the result value from the callback
     *
     * @example
     * ```typescript
     * await doc.transaction(async ({ draft }) => {
     *   const section = draft.body().sections()[0];
     *   const para = section.content().addParagraph();
     *   para.asTextView().setText('Hello, World!');
     *   return { commit: true };
     * });
     * ```
     *
     * @see {@linkcode TransactionCallback} for the callback function signature
     * @see {@linkcode TransactionResult} for return value options
     * @see {@linkcode Programmatic} for the full programmatic API namespace
     */
    transaction<T = void>(callback: TransactionCallback<T>): Promise<T>;
    /**
     * 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).
 *
 * @example
 *
 * ```ts
 * // Load from JSON
 * const docString = '{"version":"7.0","content":[...]}';
 * const docFromString = await system.loadDocument(docString);
 * ```
 *
 * @example
 *
 * ```ts
 * // Load from a JavaScript object
 * const docObject = { version: '7.0', content: [...] };
 * const docFromObject = await system.loadDocument(docObject);
 * ```
 *
 * @example
 *
 * ```ts
 * // Load from a Blob (e.g. from a file input)
 * const fileInput = document.querySelector('input[type="file"]');
 * const blob = fileInput.files[0];
 * const docFromBlob = await system.loadDocument(blob);
 * ```
 *
 * @example
 *
 * ```ts
 * // Load from a fetch Response
 * const response = await fetch('/api/document.json');
 * const docFromResponse = await system.loadDocument(response);
 * ```
 *
 * @example
 *
 * ```ts
 * // Load from a Promise (fetch is automatically awaited)
 * const docFromPromise = await system.loadDocument(fetch('/api/document.json'));
 * ```
 *
 * @example
 *
 * ```ts
 * // Load from a Promise that resolves to a Blob
 * const blobPromise = fetch('/api/document.json').then((r) => r.blob());
 * const docFromBlobPromise = await system.loadDocument(blobPromise);
 * ```
 *
 * @public
 * @sidebarGroup core
 * @sidebarGroupOrder 5
 * @see {@linkcode DocAuthSystem.loadDocument} for how this is used.
 * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/docjson/" target="_blank">DocJSON guide</a>
 */
export declare type DocAuthDocumentInput = string | object | Blob | Response | Promise<string | object | Blob | Response>;

/**
 * The visual editor UI. Binds to a DOM element and lets users edit documents.
 *
 * Create editors using {@linkcode createDocAuthSystem}.
 *
 * @public
 * @sidebarGroup core
 * @sidebarGroupOrder 7
 */
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;
    /**
     * Inserts text at the current cursor position. If there's a selection, it will be replaced with the provided text.
     *
     * @since 1.9.0
     * @param text - The text to insert at the cursor position
     */
    insertTextAtCursor(text: string): void;
    /**
     * Checks if the editor has an active cursor/insertion point. This is useful for custom actions to determine if they should be enabled.
     *
     * @since 1.9.0
     * @returns True if cursor is active and insertion is possible, false otherwise
     */
    hasActiveCursor(): boolean;
    /**
     * Set all actions (replaces any existing actions). Allows setting and executing editor actions programmatically.
     *
     * @since 1.9.0
     * @example
     *
     * ```ts
     * import { defaultActions } from '@nutrient-sdk/document-authoring';
     *
     * // Register custom actions alongside default actions
     * editor.setActions([
     * 	...defaultActions, // Keep default actions
     * 	{
     * 		id: 'custom.insert-signature',
     * 		label: 'Insert Signature',
     * 		handler: () => {
     * 			editor.insertTextAtCursor('\n\nBest regards,\nJohn Doe');
     * 		},
     * 		shortcuts: ['Mod+Shift+S'],
     * 	},
     * ]);
     * ```
     *
     * @param actions - Array of actions to register
     * @public
     * @sidebarGroup actions
     * @sidebarGroupOrder 6
     */
    setActions(actions: Action[]): void;
    /**
     * Set the toolbar configuration. Use this to customize the editor's toolbar.
     *
     * @since 1.9.0
     * @example
     *
     * ```ts
     * import { defaultToolbarConfig } from '@nutrient-sdk/document-authoring';
     *
     * // Use default toolbar config but add a custom item
     * editor.setToolbarConfig({
     * 	...defaultToolbarConfig,
     * 	items: [...defaultToolbarConfig.items, { type: 'action', id: 'custom', actionId: 'custom.insert-signature' }],
     * });
     *
     * // Or create a minimal toolbar
     * editor.setToolbarConfig({
     * 	...defaultToolbarConfig,
     * 	items: [
     * 		{ type: 'built-in', id: 'undo', builtInType: 'undo' },
     * 		{ type: 'built-in', id: 'redo', builtInType: 'redo' },
     * 		{ type: 'separator', id: 'sep-1' },
     * 		{ type: 'built-in', id: 'bold', builtInType: 'bold' },
     * 		{ type: 'built-in', id: 'italic', builtInType: 'italic' },
     * 		{ type: 'action', id: 'custom', actionId: 'custom.insert-signature' },
     * 	],
     * });
     * ```
     *
     * @param config - Toolbar configuration object
     * @public
     * @sidebarGroup toolbar
     * @sidebarGroupOrder 7
     */
    setToolbarConfig(config: ToolbarConfig): void;
    /**
     * Sets the author name used when creating comments and replies.
     *
     * @since 1.10.0
     * @example
     *
     * ```ts
     * // Set author when user logs in
     * editor.setAuthor('John Doe');
     *
     * // Clear author when user logs out (will use localized "Anonymous")
     * editor.setAuthor('');
     * ```
     *
     * @param name - The author name to use for new comments
     * @see {@linkcode UIOptions#author | UIOptions.author} for setting the initial author.
     */
    setAuthor(name: string): void;
    /**
     * Adds an event listener that will be called every time the specified event is emitted.
     *
     * @since 1.8.0
     * @example
     *
     * ```ts
     * // Auto-save on content changes
     * editor.on('content.change', async () => {
     * 	const doc = await editor.currentDocument().saveDocument();
     * 	localStorage.setItem('draft', JSON.stringify(doc));
     * });
     *
     * // Track document load
     * editor.on('document.load', () => {
     * 	console.log('Document loaded successfully');
     * });
     *
     * // Debounced save to prevent excessive API calls
     * let saveTimeout;
     * editor.on('content.change', async () => {
     * 	clearTimeout(saveTimeout);
     * 	saveTimeout = setTimeout(async () => {
     * 		const doc = await editor.currentDocument().saveDocument();
     * 		await fetch('/api/save', {
     * 			method: 'POST',
     * 			body: JSON.stringify(doc),
     * 		});
     * 	}, 1000);
     * });
     *
     * // Method chaining
     * editor.on('document.load', () => console.log('loaded')).on('content.change', () => console.log('changed'));
     * ```
     *
     * @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
     * @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.
     *
     * @since 1.8.0
     * @example
     *
     * ```ts
     * // Remove specific handler (prevent memory leaks)
     * const handleChange = async () => {
     * 	const doc = await editor.currentDocument().saveDocument();
     * 	localStorage.setItem('draft', JSON.stringify(doc));
     * };
     * editor.on('content.change', handleChange);
     * // ... later ...
     * editor.off('content.change', handleChange);
     *
     * // Remove all handlers for an event
     * editor.off('content.change');
     *
     * // Cleanup pattern
     * const setupEditor = (target) => {
     * 	const editor = await system.createEditor(target);
     *
     * 	const handleChange = () => console.log('changed');
     * 	const handleLoad = () => console.log('loaded');
     *
     * 	editor.on('content.change', handleChange);
     * 	editor.on('document.load', handleLoad);
     *
     * 	return () => {
     * 		editor.off('content.change', handleChange);
     * 		editor.off('document.load', handleLoad);
     * 		editor.destroy();
     * 	};
     * };
     * ```
     *
     * @param event - The event name to remove listeners from
     * @param handler - The specific handler to remove (optional)
     * @returns The editor instance for method chaining
     * @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.
     *
     * @since 1.8.0
     * @example
     *
     * ```ts
     * // Wait for initial document load
     * editor.once('document.load', () => {
     * 	console.log('Document loaded for the first time');
     * });
     *
     * // Perform action after first change
     * editor.once('content.change', () => {
     * 	console.log('User made their first edit');
     * });
     *
     * // Promise-based pattern for waiting on load
     * const waitForLoad = (editor) => {
     * 	return new Promise((resolve) => {
     * 		editor.once('document.load', resolve);
     * 	});
     * };
     * await waitForLoad(editor);
     * console.log('Ready to use');
     * ```
     *
     * @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
     * @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
 * @sidebarGroup core
 * @sidebarGroupOrder 4
 * @see <a href="https://www.nutrient.io/sdk/document-authoring/getting-started/" target="_blank">Getting started guide</a>
 */
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.
     *
     * @example
     *
     * ```ts
     * // Load from JSON string
     * const doc = await system.loadDocument('{"version":"7.0","content":[...]}');
     * ```
     *
     * @example
     *
     * ```ts
     * // Load from object
     * const docData = { version: '7.0', content: [...] };
     * const doc = await system.loadDocument(docData);
     * ```
     *
     * @example
     *
     * ```ts
     * // Load from server
     * const doc = await system.loadDocument(fetch('/api/documents/123'));
     * ```
     *
     * @example
     *
     * ```ts
     * // Load and create editor
     * const doc = await system.loadDocument(savedDocJSON);
     * const editor = await system.createEditor(targetElement, { document: doc });
     * ```
     *
     * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/docjson/#loading-docjson" target="_blank">DocJSON guide</a>
     * @see {@linkcode DocAuthDocumentInput} for supported input types.
     */
    loadDocument(documentInput: DocAuthDocumentInput): Promise<DocAuthDocument>;
    /**
     * Imports a DOCX document.
     *
     * @example
     *
     * ```ts
     * // Import from file input
     * const fileInput = document.querySelector('input[type="file"]');
     * const file = fileInput.files[0];
     * const doc = await system.importDOCX(file);
     * ```
     *
     * @example
     *
     * ```ts
     * // Import from URL
     * const doc = await system.importDOCX(fetch('/documents/template.docx'));
     * ```
     *
     * @example
     *
     * ```ts
     * // Import with abort signal
     * const controller = new AbortController();
     * const doc = await system.importDOCX(file, {
     * 	abortSignal: controller.signal,
     * });
     * ```
     *
     * @example
     *
     * ```ts
     * // Complete workflow: import DOCX, edit, export PDF
     * const doc = await system.importDOCX(fetch('/template.docx'));
     * const editor = await system.createEditor(targetElement, { document: doc });
     * // ... user edits document ...
     * const pdfBuffer = await editor.currentDocument().exportPDF();
     * ```
     *
     * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/docx/#importing-docx" target="_blank">DOCX import guide</a>
     * @see {@linkcode BlobInput} for supported input types.
     */
    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`.
     *
     * @example
     *
     * ```ts
     * // Shared code for the examples below - ensure target element has proper positioning
     * const target = document.getElementById('editor');
     * target.style.position = 'relative';
     * target.style.height = '600px';
     * ```
     *
     * @example
     *
     * ```ts
     * // Create editor with empty document
     * const editor = await system.createEditor(target);
     * ```
     *
     * @example
     *
     * ```ts
     * // Create editor with existing document
     * const doc = await system.loadDocument(docJSON);
     * const editor = await system.createEditor(target, { document: doc });
     * ```
     *
     * @example
     *
     * ```ts
     * // Complete workflow with event handling
     * const editor = await system.createEditor(target);
     * editor.on('content.change', async () => {
     * 	const doc = await editor.currentDocument().saveDocument();
     * 	localStorage.setItem('draft', JSON.stringify(doc));
     * });
     * ```
     *
     * @see <a href="https://www.nutrient.io/sdk/document-authoring/getting-started/using-npm/#integrating-into-your-project" target="_blank">Getting started guide</a>
     * @see {@linkcode CreateEditorOptions} for available options.
     */
    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
     *
     * @example
     *
     * ```ts
     * // Simple text document
     * const doc = await system.createDocumentFromPlaintext('Hello World');
     * ```
     *
     * @example
     *
     * ```ts
     * // Multi-paragraph document
     * const text = `First paragraph.
     *
     * Second paragraph with line break\nand continuation.`;
     * const doc = await system.createDocumentFromPlaintext(text);
     * ```
     *
     * @example
     *
     * ```ts
     * // With custom page settings
     * const doc = await system.createDocumentFromPlaintext('My content', {
     * 	pageSize: 'A4',
     * 	pageMargins: { left: 72, right: 72, top: 72, bottom: 72 },
     * });
     * ```
     *
     * @example
     *
     * ```ts
     * // Create document and editor in one flow
     * const doc = await system.createDocumentFromPlaintext('Initial content');
     * const editor = await system.createEditor(targetElement, { document: doc });
     * ```
     *
     * @see {@linkcode CreateDocumentFromPlaintextOptions} for available options.
     */
    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.
     *
     * @example
     *
     * ```ts
     * // Clean up when done
     * editor.destroy();
     * system.destroy();
     *
     * // Or use try-finally pattern
     * const system = await createDocAuthSystem();
     * try {
     * 	const editor = await system.createEditor(target);
     * 	// ... use editor ...
     * 	editor.destroy();
     * } finally {
     * 	system.destroy();
     * }
     * ```
     */
    destroy(): void;
};

/**
 * @public
 * @sidebarGroup import / export
 * @sidebarGroupOrder 1
 * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/docx/#exporting-docx" target="_blank">DOCX export guide</a>
 * @see {@linkcode DocAuthDocument.exportDOCX} for exporting documents to DOCX with these options.
 */
export declare type ExportDOCXOptions = {
    /**
     * An optional signal to abort the export operation.
     */
    abortSignal?: AbortSignal;
};

/**
 * @public
 * @sidebarGroup import / export
 * @sidebarGroupOrder 2
 * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/pdf/" target="_blank">PDF export guide</a>
 * @see {@linkcode DocAuthDocument.exportPDF} for exporting documents to PDF with these options.
 */
export declare type ExportPDFOptions = {
    /**
     * An optional signal to abort the export operation.
     */
    abortSignal?: AbortSignal;
    /**
     * @since 1.1.0 Generate a PDF/A compliant PDF. Defaults to `false`.
     */
    PDF_A?: boolean;
};

/**
 * Font configuration for the Document Authoring system.
 *
 * The font system supports three approaches:
 *
 * - {@linkcode DefaultFontIndex}: Built-in fonts (included by default)
 * - {@linkcode FontFile}: Individual font files loaded upfront
 * - {@linkcode FontIndex}: Efficient lazy-loading from a font index
 *
 * @since 1.0.26
 * @example Quick start - add individual fonts (loaded during initialization):
 *
 * ```ts
 * import { createDocAuthSystem, defaultFontIndex } from '@nutrient-sdk/document-authoring';
 *
 * const system = await createDocAuthSystem({
 * 	fontConfig: {
 * 		fonts: [
 * 			defaultFontIndex,
 * 			{ type: 'file', blob: fetch('/fonts/custom-font.ttf') },
 * 			{ type: 'file', blob: fetch('/fonts/another-font.ttf') },
 * 		],
 * 	},
 * });
 * ```
 *
 * @example Production setup - use font index for lazy loading (recommended):
 *
 * ```ts
 * // Step 1: Generate font index using CLI
 * // $ npx document-authoring create-font-index --scan-directory ./fonts --write-to public/fonts/font-index.json
 *
 * // Step 2: Configure system to use the index
 * import { createDocAuthSystem, defaultFontIndex } from '@nutrient-sdk/document-authoring';
 *
 * const system = await createDocAuthSystem({
 * 	fontConfig: {
 * 		fonts: [
 * 			defaultFontIndex, // Built-in fonts
 * 			{
 * 				type: 'index',
 * 				index: fetch('/fonts/font-index.json'),
 * 				loadFn: (name) => fetch(`/fonts/${name}`),
 * 			},
 * 		],
 * 	},
 * });
 *
 * // Fonts from the index are loaded on-demand as documents use them
 * ```
 *
 * @example Complete workflow with custom fonts:
 *
 * ```ts
 * import { createDocAuthSystem, defaultFontIndex } from '@nutrient-sdk/document-authoring';
 *
 * // Configure font sources
 * const system = await createDocAuthSystem({
 * 	fontConfig: {
 * 		fonts: [
 * 			defaultFontIndex,
 * 			{
 * 				type: 'index',
 * 				index: fetch('/fonts/corporate-fonts.json'),
 * 				loadFn: (name) => fetch(`/fonts/${name}`),
 * 			},
 * 		],
 * 	},
 * });
 *
 * // Import a DOCX that uses custom fonts
 * const doc = await system.importDOCX(fetch('/template.docx'));
 * // System automatically loads required fonts from the index
 *
 * // Create editor with the document
 * const editor = await system.createEditor(targetElement, { document: doc });
 * // Users can now select from all available fonts in the UI
 * ```
 *
 * @public
 * @sidebarGroup fonts
 * @sidebarGroupOrder 3
 * @see {@linkcode CreateDocAuthSystemOptions} for all available options when creating a DocAuthSystem.
 * @see {@linkcode FontFile} for loading individual fonts.
 * @see {@linkcode FontIndex} for efficient font loading.
 * @see {@linkcode DefaultFontIndex} for built-in fonts.
 */
export declare type FontConfig = {
    /**
     * The set of fonts available to the Document Authoring system. If unset the {@linkcode DefaultFontIndex} is used.
     *
     * Individual fonts can be added directly using a {@linkcode FontFile} or loaded by the system as they are needed using a pre-built
     * {@linkcode FontIndex} that lists all available fonts. A {@link FontIndex} is the recommended way to provide a set of fonts to the system in a
     * production environment.
     */
    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 {@linkcode FontIndex} of all available fonts, which enables the system to load only fonts that
 * are actually needed.
 *
 * @since 1.0.26
 * @example
 *
 * ```ts
 * { type:'file', blob: fetch('/fonts/awesome.ttf') }
 * ```
 *
 * @public
 * @sidebarGroup fonts
 * @sidebarGroupOrder 4
 * @see {@linkcode FontConfig} for configuring fonts, including using FontFile.
 */
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.
 *
 * @since 1.0.26
 * @example
 *
 * ```ts
 * {
 *   type: 'index',
 *   index: fetch('/fonts/font-index.json'),
 *   loadFn: (name) => fetch(`/fonts/${name}`),
 * }
 * ```
 *
 * @public
 * @sidebarGroup fonts
 * @sidebarGroupOrder 5
 * @see {@linkcode FontConfig} for configuring fonts, including using FontIndex.
 */
export declare type FontIndex = {
    type: 'index';
    index: BlobInput;
    loadFn: (name: string) => BlobInput;
};

/**
 * @public
 * @sidebarGroup import / export
 * @sidebarGroupOrder 3
 * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/docx/#importing-docx" target="_blank">DOCX import guide</a>
 * @see {@linkcode DocAuthSystem.importDOCX} for importing DOCX files with these options.
 */
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 {@linkcode UIOptions#locale | UIOptions.locale}
 *
 * @since 1.5.0
 * @public
 * @sidebarGroup ui
 * @sidebarGroupOrder 2
 */
export declare type Locale = 'en' | 'fr' | 'de';

/**
 * @public
 * @sidebarGroup programmatic api
 * @since 1.10.0
 */
export declare namespace Programmatic {
    /**
     * Opaque type representing a contiguous region within the content.
     *
     * @remarks
     * Ranges can be obtained from various API methods and then passed to other operations.
     *
     * **Examples:**
     * - {@linkcode TextView.searchText} - Returns a range for a text match
     * - {@linkcode TextView.setText} - Can be used to replace a given range
     * - {@linkcode TextView.getPlainText} - Can be used to extract text at a specific range
     * - {@linkcode TextView.setFormatting} - Can be used to apply formatting to a specific range
     *
     * @sidebarGroup programmatic api
     */
    export type Range = {


    };
    /**
     * Defines text formatting properties that can be applied to document content.
     *
     * @remarks
     * The `Formatting` type specifies visual styling properties for text. All properties
     * use `null` to represent "inherited from style".
     *
     * When applying formatting via e.g. {@linkcode TextView.setFormatting}, you typically use
     * `Partial<Formatting>` to specify only the properties you want to change.
     *
     * @example
     * Apply bold and color to text:
     * ```typescript
     * textView.setFormatting({
     *   bold: true,
     *   color: "#ff0000"
     * });
     * ```
     *
     * @sidebarGroup programmatic api
     */
    export type Formatting = {
        /**
         * Font family name (e.g., "Arial", "Times New Roman").
         *
         * @remarks
         * Specifies the typeface for the text.
         * `null` means no explicit font is set (inherits from style).
         */
        font: string | null;
        /**
         * Font size in points (e.g., 12, 14, 18).
         *
         * @remarks
         * Specifies the size of the text in typographic points (1 point = 1/72 inch).
         * Common sizes are 10-12 for body text, 14-18 for headings. `null` means no
         * explicit size is set (inherits from style).
         */
        fontSize: number | null;
        /**
         * Bold text weight.
         *
         * @remarks
         * When `true`, text is rendered in bold weight. `false` or `null` means normal weight.
         */
        bold: boolean | null;
        /**
         * Italic text style.
         *
         * @remarks
         * When `true`, text is rendered in italic style. `false` or `null` means normal (upright) style.
         */
        italic: boolean | null;
        /**
         * Text foreground color.
         *
         * @remarks
         * Specifies the color of the text characters. Accepts hex color codes (e.g., "#ff0000" for red,
         * "#0000ff" for blue). `null` means no expl