@nutrient-sdk/document-authoring 1.3.0

package/lib/index.d.cts

@@ -0,0 +1,331 @@
+/**
+ * @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;
+
+
+};
+
+/**
+ * @hidden
+ */
+declare const _default: {
+    createDocAuthSystem: (options?: CreateDocAuthSystemOptions | undefined) => 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;
+};
+
+/**
+ * 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;
+};
+
+export { }

package/lib/index.d.mts

@@ -0,0 +1,331 @@
+/**
+ * @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;
+
+
+};
+
+/**
+ * @hidden
+ */
+declare const _default: {
+    createDocAuthSystem: (options?: CreateDocAuthSystemOptions | undefined) => 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;
+};
+
+/**
+ * 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;
+};
+
+export { }

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@nutrient-sdk/document-authoring",
+	"version": "1.3.0",
+	"description": "A web SDK for word processing and rich text capabilities.",
+	"type": "commonjs",
+	"main": "lib/docauth.umd.js",
+	"module": "lib/docauth.mjs",
+	"types": "lib/index.d.cts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./lib/index.d.mts",
+				"default": "./lib/docauth.mjs"
+			},
+			"require": {
+				"types": "./lib/index.d.cts",
+				"default": "./lib/docauth.umd.js"
+			}
+		}
+	},
+	"bin": {
+		"document-authoring": "./lib/cli.js"
+	},
+	"keywords": [
+		"document",
+		"authoring",
+		"word processing",
+		"rich text",
+		"SDK",
+		"rich text editor",
+		"WYSIWYG",
+		"editor",
+		"text editor",
+		"content creation",
+		"TypeScript",
+		"React",
+		"JavaScript",
+		"text formatting",
+		"DOCX"
+	],
+	"homepage": "https://www.nutrient.io/sdk/document-authoring/",
+	"author": {
+		"name": "Nutrient",
+		"url": "https://nutrient.io"
+	},
+	"license": "SEE LICENSE IN https://www.nutrient.io/legal/Nutrient_SDK_User_Evaluation_Subscription_Agreement",
+	"bugs": {
+		"email": "support@nutrient.io"
+	}
+}