@nutrient-sdk/document-authoring 1.9.0-preview.202511031041.d2efec9ac26d9fc0413fb4d08ac87fa1b08c30bb → 1.9.0-preview.202511131316.377b000364a35312f8f23fe4ff69cca7240f68c6

package/lib/index.d.mts

@@ -1,34 +1,109 @@
 /**
  * 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 {@link 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.
-     * To self-host the assets, consult the `README.md`.
+     *
+     * @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 {@link 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 {@link DocAuthSystem.importDOCX} for importing DOCX files.
+ * @see {@link FontFile} for using BlobInput with fonts.
  */
 export declare type BlobInput = Promise<Response | Blob | ArrayBuffer> | Response | Blob | ArrayBuffer;
 
 /**
- * Built-in action - can omit handler, will use default implementation
+ * Built-in actions have pre-defined IDs from {@link BuiltInActionId} and automatically use
+ * default handlers if not provided. This allows you to customize things without having to
+ * reimplement internal functionality.
+ *
+ * @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'] },
+ * ]);
+ * ```
+ *
+ * @since 1.9.0
  * @public
+ * @sidebarGroup actions
+ * @sidebarGroupOrder 3
+ * @see {@link BuiltInActionId} for available built-in action IDs.
+ * @see {@link CustomAction} for defining custom actions.
  */
 export declare type BuiltInAction = {
-    readonly id: BuiltInActionId;
-    readonly label: string;
-    readonly description?: string;
+    /** Built-in action ID from {@link BuiltInActionId} */
+    id: BuiltInActionId;
+    label: string;
+    description?: string;
     /**
      * Keyboard shortcuts for the action.
      * Use "Mod" as the primary modifier key - it will be automatically resolved to:
@@ -39,21 +114,23 @@ export declare type BuiltInAction = {
      * - "Mod+B" becomes "Ctrl+B" on Windows, "⌘B" on Mac
      * - "Mod+Shift+P" becomes "Ctrl+Shift+P" on Windows, "⌘⇧P" on Mac
      */
-    readonly shortcuts?: string[];
+    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. */
-    readonly icon?: string;
-    readonly isEnabled?: () => boolean;
-    readonly order?: number;
-    readonly handler?: (...args: unknown[]) => void | Promise<void>;
+    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
- * @public
  */
 /**
  * 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';
 
@@ -62,27 +139,169 @@ export declare type BuiltInActionId = 'document.undo' | 'document.redo' | 'docum
  * like creating editors, importing Word documents or creating PDFs.
  *
  * This loads the JavaScript and WASM code and manages the font cache.
+ *
+ * @see <a href="https://www.nutrient.io/sdk/document-authoring/getting-started/" target="_blank">Getting started guide</a>
  * @public
+ * @sidebarGroup core
+ * @sidebarGroupOrder 1
  */
-export declare const createDocAuthSystem: (options?: CreateDocAuthSystemOptions) => Promise<DocAuthSystem>;
+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 {@link createDocAuthSystem} for creating a system instance.
+ * @see {@link FontConfig} for font configuration details.
+ * @see {@link 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 v1.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 {@link DocAuthSystem.createDocumentFromPlaintext} for creating documents from text.
  */
 export declare type CreateDocumentFromPlaintextOptions = {
     /**
@@ -107,19 +326,78 @@ export declare type CreateDocumentFromPlaintextOptions = {
 };
 
 /**
+ * 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 {@link DocAuthSystem.createEditor} for creating editors.
+ * @see {@link 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 {@link DocAuthEditor.setCurrentDocument}
+     * @see {@link DocAuthEditor.setCurrentDocument} for setting the document after the editor is created.
      */
     document?: DocAuthDocument;
     /**
+     * @since 1.5.0
      * Allows toggling/changing various UI options.
-     *
-     * See {@link UIOptions}
      */
     ui?: UIOptions;
     /**
@@ -133,13 +411,70 @@ export declare type CreateEditorOptions = {
 };
 
 /**
- * Custom action - must provide handler
+ * Custom actions allow you to add your own functionality to the editor.
+ * Unlike {@link BuiltInAction}, custom actions must provide a handler function.
+ *
+ * @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);
+ *     },
+ *   },
+ * ]);
+ * ```
+ *
+ * @since 1.9.0
  * @public
+ * @sidebarGroup actions
+ * @sidebarGroupOrder 4
+ * @see {@link BuiltInAction} for built-in actions with default implementations.
+ * @see {@link ToolbarActionItem} for adding custom actions to the toolbar.
  */
 export declare type CustomAction = {
-    readonly id: string;
-    readonly label: string;
-    readonly description?: string;
+    /** Unique identifier for this action (must not be a {@link BuiltInActionId}) */
+    id: string;
+    label: string;
+    description?: string;
     /**
      * Keyboard shortcuts for the action.
      * Use "Cmd" as the modifier key - it will be resolved to:
@@ -151,19 +486,20 @@ export declare type CustomAction = {
      * - "Cmd+B" becomes "Ctrl+B" on Windows, "⌘B" on Mac
      * - "Cmd+Shift+P" becomes "Ctrl+Shift+P" on Windows, "⌘⇧P" on Mac
      */
-    readonly shortcuts?: string[];
+    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. */
-    readonly icon?: string;
-    readonly isEnabled?: () => boolean;
-    readonly order?: number;
-    readonly handler: (...args: unknown[]) => void | Promise<void>;
+    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>;
 };
 
 /**
  * @hidden
  */
 declare const _default: {
-    createDocAuthSystem: (options?: CreateDocAuthSystemOptions) => Promise<DocAuthSystem>;
+    createDocAuthSystem: typeof createDocAuthSystem;
     defaultFontIndex: DefaultFontIndex;
     defaultActions: BuiltInAction[];
     defaultToolbarConfig: ToolbarConfig;
@@ -171,8 +507,7 @@ declare const _default: {
 export default _default;
 
 /**
- * Get the default set of actions available in the editor.
- * Can be combined with custom actions using spread operator.
+ * Get the default set of actions available in the editor. Can be combined with custom actions.
  *
  * Note: Built-in actions (those with IDs from {@link BuiltInActionId}) can omit handlers -
  * they will be automatically populated with default implementations when passed to
@@ -183,18 +518,18 @@ export default _default;
  * Custom actions (those with any other string ID) must provide a handler function.
  *
  * @example
- * ```typescript
+ * ```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,
+ *   ...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,
+ *   ...defaultActions.filter(({ id }) => id !== 'formatting.bold'),
  *   { id: 'formatting.bold', label: 'Bold', handler: () => console.log('custom bold!') }
  * ]);
  *
@@ -205,7 +540,10 @@ export default _default;
  * ]);
  * ```
  *
+ * @since 1.9.0
  * @public
+ * @sidebarGroup actions
+ * @sidebarGroupOrder 1
  */
 export declare const defaultActions: BuiltInAction[];
 
@@ -215,6 +553,10 @@ export declare const defaultActions: BuiltInAction[];
  * See {@link FontConfig} for how to customize the set of fonts used by the SDK.
  *
  * @public
+ * @sidebarGroup fonts
+ * @sidebarGroupOrder 2
+ * @since v1.0.26
+ * @see {@link FontConfig} for configuring fonts, including using the default font index.
  */
 export declare type DefaultFontIndex = {
     type: 'default-index';
@@ -225,7 +567,10 @@ export declare type DefaultFontIndex = {
  *
  * See {@link 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;
 
@@ -234,41 +579,62 @@ export declare const defaultFontIndex: DefaultFontIndex;
  * Can be used as-is or customized.
  *
  * @example
- * ```typescript
+ * ```ts
  * import { defaultToolbarConfig } from '@nutrient-sdk/document-authoring';
  *
- * editor.setToolbarConfig(defaultToolbarConfig);
- * // or customize:
+ * // remove the first two items
+ * editor.setToolbarConfig(defaultToolbarConfig.slice(2));
+ *
+ * // add a custom item
  * editor.setToolbarConfig({
  *   items: [...defaultToolbarConfig.items, myCustomItem]
  * });
  * ```
  *
+ * @since 1.9.0
  * @public
+ * @sidebarGroup toolbar
+ * @sidebarGroupOrder 1
+ *
+ * @see {@link 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 {@link DocAuthEditor} and/or {@link 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 {@link 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>;
     /**
@@ -286,12 +652,64 @@ export declare type DocAuthDocument = {
  * 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 {@link 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 {@link createDocAuthSystem}.
+ *
  * @public
+ * @sidebarGroup core
+ * @sidebarGroupOrder 7
  */
 export declare type DocAuthEditor = {
     /**
@@ -316,6 +734,7 @@ export declare type DocAuthEditor = {
      * If there's a selection, it will be replaced with the provided text.
      *
      * @param text - The text to insert at the cursor position
+     * @since 1.8.0
      */
     insertTextAtCursor(text: string): void;
     /**
@@ -323,63 +742,9 @@ export declare type DocAuthEditor = {
      * This is useful for custom actions to determine if they should be enabled.
      *
      * @returns true if cursor is active and insertion is possible, false otherwise
-     *
-     * @internal
+     * @since 1.9.0
      */
     hasActiveCursor(): boolean;
-    /**
-     * 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;
     /**
      * Set all actions (replaces any existing actions).
      * Allows setting and executing editor actions programmatically.
@@ -387,7 +752,7 @@ export declare type DocAuthEditor = {
      * @param actions - Array of actions to register
      *
      * @example
-     * ```typescript
+     * ```ts
      * import { defaultActions } from '@nutrient-sdk/document-authoring';
      *
      * // Register custom actions alongside default actions
@@ -399,12 +764,15 @@ export declare type DocAuthEditor = {
      *     handler: () => {
      *       editor.insertTextAtCursor('\n\nBest regards,\nJohn Doe');
      *     },
-     *     shortcuts: [{ mac: '⌘⇧S', windows: 'Ctrl+Shift+S' }]
-     *   }
+     *     shortcuts: ['Mod+Shift+S'],
+     *   },
      * ]);
      * ```
      *
+     * @since 1.9.0
      * @public
+     * @sidebarGroup actions
+     * @sidebarGroupOrder 6
      */
     setActions(actions: Action[]): void;
     /**
@@ -414,11 +782,17 @@ export declare type DocAuthEditor = {
      * @param config - Toolbar configuration object
      *
      * @example
-     * ```typescript
+     * ```ts
      * import { defaultToolbarConfig } from '@nutrient-sdk/document-authoring';
      *
-     * // Use default toolbar
-     * editor.setToolbarConfig(defaultToolbarConfig);
+     * // 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({
@@ -433,9 +807,132 @@ export declare type DocAuthEditor = {
      * });
      * ```
      *
+     * @since 1.9.0
      * @public
+     * @sidebarGroup toolbar
+     * @sidebarGroupOrder 7
      */
     setToolbarConfig(config: ToolbarConfig): void;
+    /**
+     * 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
+     * ```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'));
+     * ```
+     *
+     * @since 1.8.0
+     * @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
+     * ```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();
+     *   };
+     * };
+     * ```
+     *
+     * @since 1.8.0
+     * @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
+     * ```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');
+     * ```
+     *
+     * @since 1.8.0
+     * @eventMap DocAuthEditorEvents
+     */
+    once<EventName extends keyof DocAuthEditorEvents>(event: EventName, handler: DocAuthEditorEventHandler<EventName>): DocAuthEditor;
 };
 
 /**
@@ -465,21 +962,122 @@ export declare type DocAuthEditorEvents = {
  * A `DocAuthSystem` instance holds the internal WASM engine and loaded fonts.
  * It is used to load or import documents and create `DocAuthEditor` instances.
  *
+ * @see <a href="https://www.nutrient.io/sdk/document-authoring/getting-started/" target="_blank">Getting started guide</a>
  * @public
+ * @sidebarGroup core
+ * @sidebarGroupOrder 4
  */
 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 {@link 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 {@link 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 {@link CreateEditorOptions} for available options.
      */
     createEditor(target: HTMLElement, options?: CreateEditorOptions): Promise<DocAuthEditor>;
     /**
@@ -488,17 +1086,71 @@ export declare type DocAuthSystem = {
      * - `\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 {@link 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;
 };
 
 /**
+ * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/docx/#exporting-docx" target="_blank">DOCX export guide</a>
  * @public
+ * @sidebarGroup import / export
+ * @sidebarGroupOrder 1
+ * @see {@link DocAuthDocument.exportDOCX} for exporting documents to DOCX with these options.
  */
 export declare type ExportDOCXOptions = {
     /**
@@ -508,7 +1160,11 @@ export declare type ExportDOCXOptions = {
 };
 
 /**
+ * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/pdf/" target="_blank">PDF export guide</a>
  * @public
+ * @sidebarGroup import / export
+ * @sidebarGroupOrder 2
+ * @see {@link DocAuthDocument.exportPDF} for exporting documents to PDF with these options.
  */
 export declare type ExportPDFOptions = {
     /**
@@ -516,13 +1172,97 @@ export declare type ExportPDFOptions = {
      */
     abortSignal?: AbortSignal;
     /**
+     * @since v1.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:
+ * - {@link DefaultFontIndex}: Built-in fonts (included by default)
+ * - {@link FontFile}: Individual font files loaded upfront
+ * - {@link FontIndex}: Efficient lazy-loading from a font index
+ *
+ * @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
+ * @since v1.0.26
+ * @see {@link CreateDocAuthSystemOptions} for all available options when creating a DocAuthSystem.
+ * @see {@link FontFile} for loading individual fonts.
+ * @see {@link FontIndex} for efficient font loading.
+ * @see {@link DefaultFontIndex} for built-in fonts.
  */
 export declare type FontConfig = {
     /**
@@ -530,31 +1270,8 @@ export declare type FontConfig = {
      * 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 pre-built {@link 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.
-     *
-     * @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)[];
 };
@@ -567,11 +1284,15 @@ export declare type FontConfig = {
  * the system to load only fonts that are actually needed.
  *
  * @example
- * ```TypeScript
+ * ```ts
  * { type:'file', blob: fetch('/fonts/awesome.ttf') }
  * ```
  *
  * @public
+ * @sidebarGroup fonts
+ * @sidebarGroupOrder 4
+ * @since v1.0.26
+ * @see {@link FontConfig} for configuring fonts, including using FontFile.
  */
 export declare type FontFile = {
     type: 'file';
@@ -594,7 +1315,7 @@ export declare type FontFile = {
  * This will generate a `font-index.json` file that you can then host and load using the `FontIndex` configuration.
  *
  * @example
- * ```TypeScript
+ * ```ts
  * {
  *   type: 'index',
  *   index: fetch('/fonts/font-index.json'),
@@ -603,6 +1324,10 @@ export declare type FontFile = {
  * ```
  *
  * @public
+ * @sidebarGroup fonts
+ * @sidebarGroupOrder 5
+ * @since v1.0.26
+ * @see {@link FontConfig} for configuring fonts, including using FontIndex.
  */
 export declare type FontIndex = {
     type: 'index';
@@ -611,7 +1336,11 @@ export declare type FontIndex = {
 };
 
 /**
+ * @see <a href="https://www.nutrient.io/guides/document-authoring/working-with-documents/docx/#importing-docx" target="_blank">DOCX import guide</a>
  * @public
+ * @sidebarGroup import / export
+ * @sidebarGroupOrder 3
+ * @see {@link DocAuthSystem.importDOCX} for importing DOCX files with these options.
  */
 export declare type ImportDOCXOptions = {
     /**
@@ -625,18 +1354,28 @@ export declare type ImportDOCXOptions = {
  *
  * See {@link UIOptions | UIOptions.locale}
  *
+ * @since 1.5.0
  * @public
+ * @sidebarGroup ui
+ * @sidebarGroupOrder 2
  */
 export declare type Locale = 'en' | 'fr' | 'de';
 
 /**
  * @alpha
+ * @sidebarGroup programmatic api
  */
 export declare namespace Programmatic {
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Range = {
         begin: number;
         end?: number;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Formatting = {
         font: string | null;
         fontSize: number | null;
@@ -647,18 +1386,39 @@ export declare namespace Programmatic {
         strikeout: boolean | null;
         underline: boolean | null;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type SearchFor = string | RegExp;
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Replacement = {
         text?: string;
         formatting?: Partial<Formatting>;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type ReplaceFn = (value: string) => Replacement | string;
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type ReplacementOrReplaceFn = Replacement | ReplaceFn | string;
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type ReplaceTextSignature = (searchFor: SearchFor, replace: ReplacementOrReplaceFn) => number;
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type SearchResult = {
         range: Range;
         text: string;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type TextView = {
         getPlainText(range?: Range): string;
         searchText(searchFor: SearchFor, after?: Range): SearchResult | undefined;
@@ -676,64 +1436,118 @@ export declare namespace Programmatic {
         }): InlineText;
         removeInline(index?: number): Inline | undefined;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Extent = {
         width: number;
         height: number;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Image = {
         type: 'image';
         extent(): Extent;
         setExtent(extent: Partial<Extent>): void;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Field = {
         type: 'field';
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Footnote = {
         type: 'footnote';
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type FootnoteRef = {
         type: 'footnote/ref';
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Endnote = {
         type: 'endnote';
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type EndnoteRef = {
         type: 'endnote/ref';
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type LineBreak = {
         type: 'line-break';
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type PageBreak = {
         type: 'page-break';
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Tab = {
         type: 'tab';
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Separator = {
         type: 'sep';
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type InlineText = {
         type: 'text';
         plainText(): string;
         formatting(): Formatting;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Inline = InlineText | Tab | Separator | LineBreak | PageBreak | Image | Field | Footnote | FootnoteRef | Endnote | EndnoteRef;
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type RangeInline = {
         range: Range;
         inline: Inline;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Paragraph = {
         type: 'paragraph';
         asTextView(): TextView;
         replaceText: ReplaceTextSignature;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type TableCell = BlockLevelContainer;
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type TableRow = {
         cells(): TableCell[];
         addCell(index?: number): TableCell;
         removeCell(index: number): TableCell | undefined;
         replaceText: ReplaceTextSignature;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Table = {
         type: 'table';
         rows(): TableRow[];
@@ -741,7 +1555,13 @@ export declare namespace Programmatic {
         removeRow(index: number): TableRow | undefined;
         replaceText: ReplaceTextSignature;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type BlockLevel = Paragraph | Table;
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type BlockLevelContainer = {
         blocklevels(): BlockLevel[];
         addParagraph(index?: number): Paragraph;
@@ -749,45 +1569,72 @@ export declare namespace Programmatic {
         removeElement(index: number): BlockLevel | undefined;
         replaceText: ReplaceTextSignature;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type PageSize = {
         width: number;
         height: number;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type PageMargins = {
         left: number;
         right: number;
         top: number;
         bottom: number;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type PageSetup = {
         setPageSize(size: Partial<PageSize>): void;
         setPageMargins(margins: Partial<PageMargins>): void;
         pageSize(): PageSize;
         pageMargins(): PageMargins;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type HeaderFooter = BlockLevelContainer;
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type HeadersFooters = {
         default(): HeaderFooter | null;
         first(): HeaderFooter | null;
         even(): HeaderFooter | null;
         replaceText: ReplaceTextSignature;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type HeadersAndFooters = {
         headers(): HeadersFooters;
         footers(): HeadersFooters;
         replaceText: ReplaceTextSignature;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Section = {
         pageSetup(): PageSetup;
         headersAndFooters(): HeadersAndFooters;
         content(): BlockLevelContainer;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Body = {
         sections(): Section[];
         addSection(index?: number): Section;
         removeSection(index: number): Section | undefined;
         replaceText: ReplaceTextSignature;
     };
+    /**
+     * @sidebarGroup programmatic api
+     */
     export type Document = {
         body(): Body;
         replaceText: ReplaceTextSignature;
@@ -797,32 +1644,155 @@ export declare namespace Programmatic {
 
 /**
  * Toolbar API - Type definitions for customizing the editor toolbar
- * @public
  */
 /**
  * Action toolbar item - references an action by ID
+ *
+ * Use this to add custom actions to the toolbar. The action must be registered
+ * via {@link DocAuthEditor.setActions} or {@link UIOptions.actions}.
+ *
+ * @example
+ * ```ts
+ * // First, register a custom action
+ * editor.setActions([
+ *   {
+ *     id: 'custom.insert-signature',
+ *     label: 'Insert Signature',
+ *     handler: () => editor.insertTextAtCursor('\n\nBest regards,\nJohn Doe'),
+ *   },
+ * ]);
+ *
+ * // Then add it to the toolbar
+ * editor.setToolbarConfig({
+ *   items: [
+ *     { type: 'action', id: 'sig-btn', actionId: 'custom.insert-signature' }
+ *   ]
+ * });
+ * ```
+ *
+ * @since 1.9.0
  * @public
+ * @sidebarGroup toolbar
+ * @sidebarGroupOrder 4
+ * @see {@link Action} for defining actions.
+ * @see {@link ToolbarConfig} for full toolbar configuration.
  */
 export declare type ToolbarActionItem = {
     type: 'action';
+    /** Unique ID for this toolbar item */
     id: string;
+    /** ID of the action to trigger when this item is clicked */
     actionId: string;
 };
 
 /**
  * Built-in toolbar item - uses original toolbar components directly
- * Self-contained with no external configuration properties
+ *
+ * These are pre-built toolbar components that come with the SDK.
+ * Each has its own UI and functionality built-in.
+ *
+ * @example
+ * ```ts
+ * // Add undo/redo buttons
+ * editor.setToolbarConfig({
+ *   items: [
+ *     { type: 'built-in', id: 'undo-btn', builtInType: 'undo' },
+ *     { type: 'built-in', id: 'redo-btn', builtInType: 'redo' },
+ *   ]
+ * });
+ *
+ * // Add text formatting buttons
+ * editor.setToolbarConfig({
+ *   items: [
+ *     { type: 'built-in', id: 'bold-btn', builtInType: 'bold' },
+ *     { type: 'built-in', id: 'italic-btn', builtInType: 'italic' },
+ *     { type: 'built-in', id: 'underline-btn', builtInType: 'underline' },
+ *   ]
+ * });
+ *
+ * // Add dropdown menus
+ * editor.setToolbarConfig({
+ *   items: [
+ *     { type: 'built-in', id: 'font-menu', builtInType: 'font-family' },
+ *     { type: 'built-in', id: 'size-menu', builtInType: 'font-size' },
+ *     { type: 'built-in', id: 'insert', builtInType: 'insert-menu' },
+ *   ]
+ * });
+ * ```
+ *
+ * @since 1.9.0
  * @public
+ * @sidebarGroup toolbar
+ * @sidebarGroupOrder 5
+ * @see {@link ToolbarConfig} for full toolbar configuration.
  */
 export declare type ToolbarBuiltInItem = {
     type: 'built-in';
+    /** Unique ID for this toolbar item */
     id: string;
+    /** The type of built-in toolbar component to use */
     builtInType: 'undo' | 'redo' | 'bold' | 'italic' | 'underline' | 'strikethrough' | 'subscript' | 'superscript' | 'text-color' | 'highlight-color' | 'align-left' | 'align-center' | 'align-right' | 'align-justify' | 'bulleted-list' | 'numbered-list' | 'decrease-indent' | 'increase-indent' | 'clear-formatting' | 'formatting-marks' | 'zoom' | 'mobile-lock' | 'font-family' | 'font-size' | 'style-menu' | 'line-spacing-menu' | 'page-setup-menu' | 'insert-menu' | 'table-menu' | 'download-menu' | 'ui-settings-menu';
 };
 
 /**
  * Toolbar configuration
+ *
+ * @example
+ * ```ts
+ * import { defaultToolbarConfig, defaultActions } from '@nutrient-sdk/document-authoring';
+ *
+ * // Add custom action and toolbar button
+ * editor.setActions([
+ *   ...defaultActions,
+ *   {
+ *     id: 'custom.save',
+ *     label: 'Save',
+ *     handler: async () => {
+ *       const doc = await editor.currentDocument().saveDocument();
+ *       await fetch('/api/save', { method: 'POST', body: JSON.stringify(doc) });
+ *     },
+ *   },
+ * ]);
+ * editor.setToolbarConfig({
+ *   ...defaultToolbarConfig,
+ *   items: [
+ *     ...defaultToolbarConfig.items,
+ *     { type: 'separator', id: 'sep-custom' },
+ *     { type: 'action', id: 'save-btn', actionId: 'custom.save' }
+ *   ]
+ * });
+ *
+ * // Create a minimal toolbar with essential formatting
+ * editor.setToolbarConfig({
+ *   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: 'built-in', id: 'underline', builtInType: 'underline' },
+ *     { type: 'separator', id: 'sep-2' },
+ *     { type: 'built-in', id: 'align-left', builtInType: 'align-left' },
+ *     { type: 'built-in', id: 'align-center', builtInType: 'align-center' },
+ *     { type: 'built-in', id: 'align-right', builtInType: 'align-right' },
+ *   ]
+ * });
+ *
+ * // Customize default toolbar by filtering/adding items
+ * const customItems = [
+ *   ...defaultToolbarConfig.items.filter(item => item.id !== 'download-menu'),
+ *   { type: 'separator', id: 'custom-sep' },
+ *   { type: 'action', id: 'save-btn', actionId: 'custom.save' }
+ * ];
+ * editor.setToolbarConfig({ ...defaultToolbarConfig, items: customItems });
+ * ```
+ *
+ * @since 1.9.0
  * @public
+ * @sidebarGroup toolbar
+ * @sidebarGroupOrder 2
+ * @see {@link ToolbarItem} for the different types of toolbar items.
+ * @see {@link UIOptions.toolbar} for setting toolbar during editor creation.
  */
 export declare type ToolbarConfig = {
     /**
@@ -833,21 +1803,50 @@ export declare type ToolbarConfig = {
 
 /**
  * Union type for all toolbar items
+ * @since 1.9.0
  * @public
+ * @sidebarGroup toolbar
+ * @sidebarGroupOrder 3
  */
 export declare type ToolbarItem = ToolbarActionItem | ToolbarBuiltInItem | ToolbarSeparatorItem;
 
 /**
- * Visual separator
+ * Visual separator - adds a vertical line between toolbar items
+ *
+ * Use separators to visually group related toolbar items.
+ *
+ * @example
+ * ```ts
+ * editor.setToolbarConfig({
+ *   items: [
+ *     { type: 'built-in', id: 'undo', builtInType: 'undo' },
+ *     { type: 'built-in', id: 'redo', builtInType: 'redo' },
+ *     { type: 'separator', id: 'sep-1' },  // Separate undo/redo from formatting
+ *     { type: 'built-in', id: 'bold', builtInType: 'bold' },
+ *     { type: 'built-in', id: 'italic', builtInType: 'italic' },
+ *     { type: 'separator', id: 'sep-2' },  // Separate formatting from alignment
+ *     { type: 'built-in', id: 'align-left', builtInType: 'align-left' },
+ *     { type: 'built-in', id: 'align-center', builtInType: 'align-center' },
+ *   ]
+ * });
+ * ```
+ *
+ * @since 1.9.0
  * @public
+ * @sidebarGroup toolbar
+ * @sidebarGroupOrder 6
+ * @see {@link ToolbarConfig} for full toolbar configuration.
  */
 export declare type ToolbarSeparatorItem = {
     type: 'separator';
+    /** Unique ID for this separator */
     id: string;
 };
 
 /**
  * @alpha
+ * @sidebarGroup programmatic api
+ * @see {@link DocAuthDocument.transaction} for running transactions with this callback type.
  */
 export declare type TransactionCallback<T = void> = (context: {
     draft: Programmatic.Document;
@@ -855,6 +1854,8 @@ export declare type TransactionCallback<T = void> = (context: {
 
 /**
  * @alpha
+ * @sidebarGroup programmatic api
+ * @see {@link TransactionCallback} for the callback signature that returns this result type.
  */
 export declare type TransactionResult<T = void> = undefined | boolean | {
     commit: boolean;
@@ -867,7 +1868,11 @@ export declare type TransactionResult<T = void> = undefined | boolean | {
 /**
  * Configuration options for the user interface.
  *
+ * @since 1.5.0
  * @public
+ * @sidebarGroup ui
+ * @sidebarGroupOrder 1
+ * @see {@link CreateEditorOptions} for all available options when creating an editor.
  */
 export declare type UIOptions = {
     /**
@@ -909,6 +1914,72 @@ export declare type UIOptions = {
      * Initial toolbar configuration.
      *
      * The toolbar can also be customized at runtime using `editor.setToolbarConfig()`.
+     *
+     * @example
+     * ```ts
+     * import { defaultToolbarConfig, defaultActions } from '@nutrient-sdk/document-authoring';
+     *
+     * // Add a separator and custom action to the default toolbar
+     * const editor = await system.createEditor(target, {
+     *   ui: {
+     *     actions: [
+     *       ...defaultActions,
+     *       { id: 'custom.hello', label: 'Say Hello', handler: () => alert('Hello!') },
+     *     ],
+     *     toolbar: {
+     *       items: [
+     *         ...defaultToolbarConfig.items,
+     *         { type: 'separator', id: 'sep-custom' },
+     *         { type: 'action', id: 'custom-action', actionId: 'custom.hello' },
+     *       ],
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Create a minimal toolbar with just undo/redo and bold/italic
+     * const editor = await system.createEditor(target, {
+     *   ui: {
+     *     toolbar: {
+     *       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' },
+     *       ],
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Mix built-in items with custom actions
+     * const editor = await system.createEditor(target, {
+     *   ui: {
+     *     toolbar: {
+     *       items: [
+     *         { type: 'built-in', id: 'undo', builtInType: 'undo' },
+     *         { type: 'action', id: 'custom-btn', actionId: 'custom.my-action' }
+     *       ]
+     *     },
+     *     actions: [
+     *       {
+     *         id: 'custom.my-action',
+     *         label: 'My Action',
+     *         handler: () => console.log('clicked!'),
+     *       },
+     *     ],
+     *   },
+     * });
+     * ```
+     *
+     * @since 1.9.0
+     * @see {@link ToolbarConfig} for the toolbar configuration type.
+     * @see {@link defaultToolbarConfig} for the default toolbar configuration.
      */
     toolbar?: ToolbarConfig;
     /**
@@ -917,7 +1988,7 @@ export declare type UIOptions = {
      * Actions can also be customized at runtime using `editor.setActions()`.
      *
      * @example
-     * ```typescript
+     * ```ts
      * import { defaultActions } from '@nutrient-sdk/document-authoring';
      *
      * const editor = await system.createEditor(target, {
@@ -928,11 +1999,13 @@ export declare type UIOptions = {
      *         id: 'custom.hello',
      *         label: 'Say Hello',
      *         handler: () => alert('Hello!'),
-     *       }
-     *     ]
-     *   }
+     *       },
+     *     ],
+     *   },
      * });
      * ```
+     *
+     * @since 1.9.0
      */
     actions?: Action[];
 };
@@ -942,7 +2015,10 @@ export declare type UIOptions = {
  *
  * See {@link UIOptions | UIOptions.unit}
  *
+ * @since 1.5.0
  * @public
+ * @sidebarGroup ui
+ * @sidebarGroupOrder 3
  */
 export declare type Unit = 'cm' | 'in' | 'pt' | 'pc' | 'mm';