@docx-editor.dev/react 2.31.0 → 2.32.0

package/dist/index.d.ts

@@ -10,8 +10,8 @@
  */
 import * as react from 'react';
 import react__default, { ReactNode, CSSProperties, ReactElement, ComponentType, ButtonHTMLAttributes, ForwardRefExoticComponent, RefAttributes, HTMLAttributes, Ref } from 'react';
-import { RevisionMarkupDialogSession, ResolvedRevisionMarkup, RevisionMarkupOptions, ChromeExportFormat, InvalidTextFormFieldSession, ContentControlWidgetSession, CalendarMonth, ContentControlListNavigation, CalendarDay, TextFormFieldDialogSession, RevisionAuthorStyle, ParagraphDialogFields, ParagraphDialogMixed, BookmarkSortOrder, ChromeMenuId, ChromeSlotId, ChromeMenuEntry, DocxEditorInstance, FontConfigurationFragment, FontResolver, FontShapingOptions, EditorModule, ReviewDisplayMode, FieldResultsMode, ContentLockPolicy, LockedControlNavigation, ImageDecodePort, ChromeGroupId, SupportedImageMime, TableChromeSlotId, ChromeExportHandlers, DocumentSearchHighlight, DocumentSearchFindOptions, SurfaceHyperlink, FontOrigin, MarkedFontResolver, ReviewAuthorInfo, EditorCommandExecute, ToolbarValueMap, HighlightSource, ParagraphFormatRead, ParagraphFormatUpdate, TextMeasurer, PaginatedSurfaceState, NavigationCommand, SurfaceFormatting, SectionProperties, RulerIndent, HistoryGroupBindingOptions } from '@docx-editor.dev/core/editor';
-export { CHROME_GROUPS, CHROME_MENUS, ChromeExportFormat, ChromeExportHandlers, ChromeMenu, ChromeMenuEntry, ChromeMenuId, ChromeMenuItemEntry, ChromeMenuSeparatorEntry, ChromeMenuSubmenuEntry, ChromeSlotId, ClearRefreshHighlightsOptions, DEFAULT_FONT, DocumentRefresh, DocumentRefreshError, DocumentRefreshState, DocumentSearchFindOptions, DocumentSearchHighlight, DocumentSearchNavigateOptions, DocumentSearchOptions, FontConfigurationBase, FontConfigurationFragment, FontLoadFailure, FontLoadFailureReason, FontOrigin, FontResolutionRequest, FontResolver, FontResolverMark, FontUrlSource, HIGHLIGHT_REFRESH_MS, HighlightSource, ImageWrapTarget, LOADING_SNAPSHOT, LoadFontsRequest, LoadFontsResult, MAX_RESOLVER_FAMILIES, MarkedFontResolver, NavigateToChangeOptions, PX_PER_CM, PX_PER_INCH, ParagraphFlagState, ParagraphFormatRead, ParagraphFormatUpdate, ParagraphTabStop, RefreshChange, RefreshChangeInput, RefreshFailureCode, RefreshHighlightAnimation, RefreshHighlightOptions, RefreshLocation, RefreshResult, RefreshSubmission, RefreshUpdate, ResolvedRevisionMarkup, ReviewAuthorInfo, ReviewDisplayMode, RevisionAuthorAssignments, RevisionAuthorStyle, RevisionChangedLinesMark, RevisionDeletionMark, RevisionMarkupChromeHandlers, RevisionMarkupColor, RevisionMarkupDialogSession, RevisionMarkupMark, RevisionMarkupNamedColor, RevisionMarkupOptions, RevisionStyles, RulerTick, RulerUnit, SEARCH_DEBOUNCE_MS, SEARCH_HIGHLIGHT_PRIORITY, SEARCH_HIGHLIGHT_SET, SEARCH_MATCH_LIMIT, ToolbarCommandState, WORD_DEFAULT_FONT, chromeMenuSlots, commandForSlot, composeFontConfiguration, composeFontOrigins, createDocumentRefresh, createFontSource, defineFontResolver, generateRulerTicks, isFontResolver, loadFonts, rulerPageBox, runToolbarCommand, toolbarCommandState } from '@docx-editor.dev/core/editor';
+import { UnsupportedElementRule, UnsupportedElement, RevisionMarkupDialogSession, ResolvedRevisionMarkup, RevisionMarkupOptions, ChromeExportFormat, InvalidTextFormFieldSession, ContentControlWidgetSession, CalendarMonth, ContentControlListNavigation, CalendarDay, TextFormFieldDialogSession, RevisionAuthorStyle, ParagraphDialogFields, ParagraphDialogMixed, BookmarkSortOrder, SplitCellLimits, ChromeMenuId, ChromeSlotId, ChromeMenuEntry, DocxEditorInstance, FontConfigurationFragment, FontResolver, FontShapingOptions, EditorModule, ReviewDisplayMode, FieldResultsMode, ContentLockPolicy, LockedControlNavigation, ImageDecodePort, ChromeGroupId, SupportedImageMime, TableChromeSlotId, ChromeExportHandlers, DocumentSearchHighlight, DocumentSearchFindOptions, SurfaceHyperlink, FontOrigin, MarkedFontResolver, ReviewAuthorInfo, EditorCommandExecute, ToolbarValueMap, HighlightSource, ParagraphFormatRead, ParagraphFormatUpdate, TextMeasurer, PaginatedSurfaceState, NavigationCommand, SurfaceFormatting, SectionProperties, RulerIndent, HistoryGroupBindingOptions } from '@docx-editor.dev/core/editor';
+export { CHROME_GROUPS, CHROME_MENUS, ChromeExportFormat, ChromeExportHandlers, ChromeMenu, ChromeMenuEntry, ChromeMenuId, ChromeMenuItemEntry, ChromeMenuSeparatorEntry, ChromeMenuSubmenuEntry, ChromeSlotId, ClearRefreshHighlightsOptions, DEFAULT_FONT, DocumentRefresh, DocumentRefreshError, DocumentRefreshState, DocumentSearchFindOptions, DocumentSearchHighlight, DocumentSearchNavigateOptions, DocumentSearchOptions, FontConfigurationBase, FontConfigurationFragment, FontLoadFailure, FontLoadFailureReason, FontOrigin, FontResolutionRequest, FontResolver, FontResolverMark, FontUrlSource, HIGHLIGHT_REFRESH_MS, HighlightSource, ImageWrapTarget, LOADING_SNAPSHOT, LoadFontsRequest, LoadFontsResult, MAX_RESOLVER_FAMILIES, MarkedFontResolver, NavigateToChangeOptions, PX_PER_CM, PX_PER_INCH, ParagraphFlagState, ParagraphFormatRead, ParagraphFormatUpdate, ParagraphTabStop, RefreshChange, RefreshChangeInput, RefreshFailureCode, RefreshHighlightAnimation, RefreshHighlightOptions, RefreshLocation, RefreshResult, RefreshSubmission, RefreshUpdate, ResolvedRevisionMarkup, ReviewAuthorInfo, ReviewDisplayMode, RevisionAuthorAssignments, RevisionAuthorStyle, RevisionChangedLinesMark, RevisionDeletionMark, RevisionMarkupChromeHandlers, RevisionMarkupColor, RevisionMarkupDialogSession, RevisionMarkupMark, RevisionMarkupNamedColor, RevisionMarkupOptions, RevisionStyles, RulerTick, RulerUnit, SEARCH_DEBOUNCE_MS, SEARCH_HIGHLIGHT_PRIORITY, SEARCH_HIGHLIGHT_SET, SEARCH_MATCH_LIMIT, ToolbarCommandState, UnsupportedElement, UnsupportedElementLayout, UnsupportedElementRule, WORD_DEFAULT_FONT, chromeMenuSlots, commandForSlot, composeFontConfiguration, composeFontOrigins, createDocumentRefresh, createFontSource, defineFontResolver, generateRulerTicks, isFontResolver, loadFonts, rulerPageBox, runToolbarCommand, toolbarCommandState } from '@docx-editor.dev/core/editor';
 import { Editor, ViewScope, EditorCommand, WatermarkState, BookmarkSummary, DocumentSource, FontConfiguration, ZoomMode, DocumentChange, EditorFontError, TextMatch, ExecResult, DocumentOpenFailure, DocumentHandle, EditorExecOptions, EditorScope, EditorSnapshot, Watermark, EditorEvents, HighlightOptions, HighlightResult, HighlightRange, HighlightHit, PageSetup, IndentFormatting, ColorValue, Theme } from '@docx-editor.dev/core/contracts/editor';
 export { AnchorHighlightAnimation, AnchorHighlightOptions, ClearAnchorHighlightOptions, DocumentOpenFailure, DocumentOpenFailureReason, Editor, EditorCommand, EditorFontError, EditorFontErrorCode, EditorQuery, EditorScope, EditorSnapshot, FontConfiguration, FontFaceRequest, FontSource, FontSourceSubstitution, HighlightHit, HighlightOptions, HighlightRange, HighlightRect, HighlightResult, PageSetup, ScrollToAnchorOptions, TextMatch, Watermark, WatermarkState } from '@docx-editor.dev/core/contracts/editor';
 import { TFunction, Translations, LocaleStrings } from '@docx-editor.dev/i18n';
@@ -35,6 +35,27 @@ type MaybeRefOrGetter<T> = T;
  */
 type DocxEditorChildren = ReactNode;
 
+/** Props for a registered unsupported-content renderer. @public */
+interface DocxEditorUnsupportedElementProps extends UnsupportedElementRule {
+    /**
+     * Render this occurrence. Return `null`, `false`, an empty fragment or array, or whitespace to
+     * keep the default placeholder.
+     */
+    children: (props: {
+        element: UnsupportedElement;
+    }) => ReactNode;
+}
+/**
+ * Register a renderer under DocxEditor or DocxEditor.Root.
+ * The first mounted matching declaration wins. Prop updates retain its priority.
+ * Omit match for a catch-all. Returning `null`, `false`, an empty fragment or array, or
+ * whitespace keeps the default placeholder.
+ * Layout uses points and only sizes content without an existing layout box.
+ * Components can remount when pagination or virtualization removes an occurrence.
+ * @public
+ */
+declare function DocxEditorUnsupportedElement({ match, layout, children, }: DocxEditorUnsupportedElementProps): react.JSX.Element[];
+
 /**
  * Presentation overrides for a dialog part. @public
  *
@@ -639,8 +660,8 @@ interface DocxEditorLoadingProps {
     style?: CSSProperties;
     /**
      * Your own loading indicator, in place of the packaged spinner. The packaged screen keeps
-     * its page and centers this on it. With `overlay`, it then moves onto the document's first
-     * page while a large document lays out its remaining pages, and scrolls with it.
+     * its page and centers this on it. With `overlay`, it then moves below the laid-out pages
+     * while a large document lays out its remaining pages, and scrolls with them.
      *
      * Include text for screen readers, as the packaged indicator does.
      *
@@ -652,8 +673,8 @@ interface DocxEditorLoadingProps {
     /**
      * The whole first loading screen, in place of the packaged page. Compose your own around
      * `DocxEditor.Loading.Spinner` to keep the packaged indicator beside your own copy. To
-     * change only the indicator, and keep it on the first page as the document opens, use
-     * `indicator`.
+     * change only the indicator, and keep it below the laid-out pages as the document opens,
+     * use `indicator`.
      */
     children?: DocxEditorChildren;
 }
@@ -703,7 +724,7 @@ interface DocxEditorLoadingComponent {
  * LARGE document opens — the engine mounts it behind one painted frame precisely so this
  * screen can paint before the blocking parse and layout — it holds until the pages land;
  * pass `overlay` to pin it over the previous document for that window. With `overlay`, once
- * the first pages show, the indicator moves onto the first page until the rest are laid out.
+ * the first pages show, the indicator moves below the laid-out pages until the rest are laid out.
  * Pass `indicator` to replace only the spinner, in both places:
  *
  * ```tsx
@@ -1085,6 +1106,57 @@ declare const DocxEditorBookmarkDialog: typeof BookmarkDialogRoot & {
     KeepFirst: PartComponent;
 };
 
+/** Props for `DocxEditor.SplitCellDialog`. @public */
+interface DocxEditorSplitCellDialogProps extends DialogCustomizationProps {
+    /** Whether the dialog is shown. The host owns this state. */
+    open: boolean;
+    /** Called on Cancel, Escape, overlay click, and after a successful Split. */
+    onClose: () => void;
+}
+/** The Split cells dialog's draft, as typed. @public */
+interface SplitCellDialogFields {
+    /** The number of columns, as typed. */
+    columns: string;
+    /** The number of rows, as typed. */
+    rows: string;
+}
+/** Split cells dialog draft and actions. `apply` is Split. @public */
+interface UseSplitCellDialogReturn extends UseDialogReturn<SplitCellDialogFields> {
+    /** The most columns and rows the cell splits into, or null outside a cell that splits. */
+    readonly limits: SplitCellLimits | null;
+}
+declare function SplitCellDialogRoot(props: DocxEditorSplitCellDialogProps): ReactElement | null;
+/** Read the enclosing Split cells dialog draft. @public */
+declare function useSplitCellDialog(): UseSplitCellDialogReturn;
+/** The Split cells dialog with replaceable controls and layout. @public */
+declare const DocxEditorSplitCellDialog: typeof SplitCellDialogRoot & {
+    Header: (props: DialogPartProps & {
+        name?: "columns" | "rows" | undefined;
+    }) => string | number | bigint | boolean | react.JSX.Element | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | Iterable<react.ReactNode> | ReactElement<unknown, string | react.JSXElementConstructor<any>> | react.ReactPortal | null | undefined> | null;
+    Title: (props: DialogPartProps & {
+        name?: "columns" | "rows" | undefined;
+    }) => string | number | bigint | boolean | react.JSX.Element | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | Iterable<react.ReactNode> | ReactElement<unknown, string | react.JSXElementConstructor<any>> | react.ReactPortal | null | undefined> | null;
+    Body: (props: DialogPartProps & {
+        name?: "columns" | "rows" | undefined;
+    }) => string | number | bigint | boolean | react.JSX.Element | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | Iterable<react.ReactNode> | ReactElement<unknown, string | react.JSXElementConstructor<any>> | react.ReactPortal | null | undefined> | null;
+    Footer: (props: DialogPartProps & {
+        name?: "columns" | "rows" | undefined;
+    }) => string | number | bigint | boolean | react.JSX.Element | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | Iterable<react.ReactNode> | ReactElement<unknown, string | react.JSXElementConstructor<any>> | react.ReactPortal | null | undefined> | null;
+    /** Split: divide the cell at the selection into the typed counts. */
+    Apply: (props: DialogPartProps & {
+        name?: "columns" | "rows" | undefined;
+    }) => string | number | bigint | boolean | react.JSX.Element | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | Iterable<react.ReactNode> | ReactElement<unknown, string | react.JSXElementConstructor<any>> | react.ReactPortal | null | undefined> | null;
+    Cancel: (props: DialogPartProps & {
+        name?: "columns" | "rows" | undefined;
+    }) => string | number | bigint | boolean | react.JSX.Element | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | Iterable<react.ReactNode> | ReactElement<unknown, string | react.JSXElementConstructor<any>> | react.ReactPortal | null | undefined> | null;
+    Error: (props: DialogPartProps & {
+        name?: "columns" | "rows" | undefined;
+    }) => string | number | bigint | boolean | react.JSX.Element | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | Iterable<react.ReactNode> | ReactElement<unknown, string | react.JSXElementConstructor<any>> | react.ReactPortal | null | undefined> | null;
+    Field: (props: DialogPartProps & {
+        name: "columns" | "rows";
+    }) => react.ReactNode;
+};
+
 /** Shared props for every part. @public */
 interface HyperLinkPartProps {
     className?: string;
@@ -1614,6 +1686,14 @@ declare const ContextMenuInsertColumnLeft: (({ icon, labelKey, className, hidden
 declare const ContextMenuInsertColumnRight: (({ icon, labelKey, className, hidden, destructive }: ContextMenuTableRowProps) => react.JSX.Element | null) & {
     docxRow: string;
 };
+/** Merge the selected cells into one cell. @public */
+declare const ContextMenuMergeCells: (({ icon, labelKey, className, hidden, destructive }: ContextMenuTableRowProps) => react.JSX.Element | null) & {
+    docxRow: string;
+};
+/** Open the Split cells dialog for the cell at the selection. @public */
+declare const ContextMenuSplitCell: (({ icon, labelKey, className, hidden }: ContextMenuCommandProps) => react.JSX.Element | null) & {
+    docxRow: string;
+};
 /** Delete the current table row. @public */
 declare const ContextMenuDeleteTableRow: (({ icon, labelKey, className, hidden, destructive }: ContextMenuTableRowProps) => react.JSX.Element | null) & {
     docxRow: string;
@@ -1715,6 +1795,8 @@ interface DocxEditorContextMenuNamespace {
     readonly InsertRowBelow: typeof ContextMenuInsertRowBelow;
     readonly InsertColumnLeft: typeof ContextMenuInsertColumnLeft;
     readonly InsertColumnRight: typeof ContextMenuInsertColumnRight;
+    readonly MergeCells: typeof ContextMenuMergeCells;
+    readonly SplitCell: typeof ContextMenuSplitCell;
     readonly DeleteTableRow: typeof ContextMenuDeleteTableRow;
     readonly DeleteTableColumn: typeof ContextMenuDeleteTableColumn;
     readonly DeleteTable: typeof ContextMenuDeleteTable;
@@ -1821,6 +1903,8 @@ interface DocxEditorPopups {
     watermark?: DocxEditorPopup<DocxEditorWatermarkDialogProps>;
     /** The Bookmark dialog the Insert menu and Ctrl/Cmd+Shift+F5 open. */
     bookmark?: DocxEditorPopup<DocxEditorBookmarkDialogProps>;
+    /** The Split cells dialog the table context menu and toolbar open. */
+    splitCell?: DocxEditorPopup<DocxEditorSplitCellDialogProps>;
     revisionMarkup?: DocxEditorPopup<DocxEditorRevisionMarkupDialogProps>;
     textFormField?: DocxEditorPopup<DocxEditorTextFormFieldDialogProps>;
     hyperlink?: DocxEditorPopup<HyperLinkProps>;
@@ -1892,9 +1976,10 @@ interface ReviewRailRegistry {
 declare const ReviewRailContext: react.Context<ReviewRailRegistry | null>;
 
 /**
- * Props for `DocxEditor.Root`. `document`, `fonts` and `imageDecodePort` identity changes remount
- * the editor. Changing `fontShaping.maxFontBytes` also remounts. Later `author`, `locale`, `mode`, `translate`, `zoom`, and `zoomMode` changes use
- * instance setters. `modules` is sampled at mount only.
+ * Props for `DocxEditor.Root`. `document` and `imageDecodePort` identity changes remount the
+ * editor. Changing `fontShaping.maxFontBytes` also remounts. Later `fonts`, `author`, `locale`,
+ * `mode`, `translate`, `zoom`, and `zoomMode` changes use instance setters, so edits, selection
+ * and undo history survive them. `modules` is sampled at mount only.
  *
  * @public
  */
@@ -1910,8 +1995,9 @@ interface DocxEditorRootProps {
      * uses a fixed-width estimate; fonts embedded in the document are wired automatically
      * either way. Pass `await loadDefaultFonts()` from `@docx-editor.dev/fonts` for
      * Word's default faces — a bare fragment is accepted — or compose several origins
-     * with `composeFontConfiguration`. Sampled at mount; identity change remounts;
-     * failures degrade to the fixed measurer and report through `onFontError`.
+     * with `composeFontConfiguration`. An identity change replaces the fonts in place
+     * (`setFonts`), keeping the document, selection and undo history; keep the reference stable
+     * across renders. Failures degrade to the fixed measurer and report through `onFontError`.
      */
     fonts?: FontConfiguration | FontConfigurationFragment | FontResolver;
     /** Explicit shaping byte ceiling; a changed maxFontBytes value remounts. */
@@ -2680,6 +2766,10 @@ interface DocxEditorToolbarNamespace {
     readonly TableBorderWidth: TableBorderWidthNamespace;
     /** Cell background fill split compound (quick-apply main + swatch dialog). */
     readonly TableCellFill: TableCellFillNamespace;
+    /** Merge the selected cells. */
+    readonly TableMergeCells: ToolbarPartComponent;
+    /** Open the Split cells dialog. */
+    readonly TableSplitCell: ToolbarPartComponent;
     readonly Comments: ToolbarPartComponent;
     readonly FontFamily: typeof FontFamily;
     readonly FontSize: ToolbarSlotPartComponent;
@@ -3592,8 +3682,8 @@ interface DocxEditorProps {
     /** Customize automatically mounted popups. Set an entry to false for manual ownership. */
     popups?: DocxEditorPopups;
     /**
-     * Immutable byte-backed font sources sampled at mount. Remount to replace this
-     * configuration atomically.
+     * Font sources for layout and paint. A new value replaces the fonts in place, keeping the
+     * document, selection and undo history; keep the reference stable across renders.
      *
      * Optional, but it decides layout FIDELITY. With it, the engine shapes text through
      * HarfBuzz and measures line and page breaks from real font metrics. Without it, layout
@@ -3604,6 +3694,8 @@ interface DocxEditorProps {
     fonts?: FontConfiguration | FontConfigurationFragment | FontResolver;
     /** Explicit shaping byte ceiling. A changed maxFontBytes value remounts; equal values keep the instance. */
     fontShaping?: FontShapingOptions;
+    /** Inject image decoding and preserved-image conversion. A changed port identity remounts the editor. */
+    imageDecodePort?: ImageDecodePort;
     /**
      * Title-bar slots. The host owns what goes here — brand lockup, switchers, theme
      * toggle, Open/New/Save controls — and passes them in; the editor renders them
@@ -3914,6 +4006,7 @@ interface DocxEditorNamespace extends ForwardRefExoticComponent<DocxEditorProps
     readonly ColorByChangeType: typeof DocxEditorColorByChangeType;
     readonly RevisionMarkupDialog: typeof DocxEditorRevisionMarkupDialog;
     readonly RevisionMarkup: typeof DocxEditorRevisionMarkup;
+    readonly UnsupportedElement: typeof DocxEditorUnsupportedElement;
     readonly AuthorStyle: typeof DocxEditorAuthorStyle;
     /** Context-fed horizontal ruler with draggable margins (props-driven export stays). */
     readonly HorizontalRuler: typeof DocxEditorHorizontalRuler;
@@ -3937,6 +4030,8 @@ interface DocxEditorNamespace extends ForwardRefExoticComponent<DocxEditorProps
     readonly WatermarkDialog: typeof DocxEditorWatermarkDialog;
     /** Bookmark dialog — list, add, delete and go to bookmarks. */
     readonly BookmarkDialog: typeof DocxEditorBookmarkDialog;
+    /** Split cells dialog — split the cell at the selection into columns and rows. */
+    readonly SplitCellDialog: typeof DocxEditorSplitCellDialog;
     /** The Paragraph dialog: alignment, indentation, spacing and the paragraph flags. */
     readonly TextFormFieldDialog: typeof DocxEditorTextFormFieldDialog;
     readonly ParagraphDialog: typeof DocxEditorParagraphDialog;
@@ -4675,7 +4770,8 @@ declare function useEditorValueCommand<K extends keyof ToolbarValueMap>(slotId:
 /** @public */
 type DocxEditorRefCallback<T> = (node: T | null) => void;
 
-type AnchorPlacement = 'before' | 'after' | 'story-label';
+/** Where a scoped chrome anchor sits relative to its story: before it, after it, or on its label. */
+type ScopedChromeAnchorPlacement = 'before' | 'after' | 'story-label';
 interface ScopedChromeAnchor {
     readonly ref: DocxEditorRefCallback<HTMLDivElement>;
     readonly style: CSSProperties;
@@ -4687,7 +4783,7 @@ interface ScopedChromeAnchor {
  * portal controls into a header, footer, or note node. This hook keeps the controls as a
  * sibling overlay and derives only their screen placement from the current painted host.
  */
-declare function useScopedChromeAnchor(findAnchor: (viewport: HTMLElement) => HTMLElement | null, placement: AnchorPlacement): ScopedChromeAnchor;
+declare function useScopedChromeAnchor(findAnchor: (viewport: HTMLElement) => HTMLElement | null, placement: ScopedChromeAnchorPlacement): ScopedChromeAnchor;
 
 /**
  * Subscribe to an editor event (`'change'`, `'selectionChange'`, `'error'`, …) for the
@@ -4778,6 +4874,8 @@ declare function useEditorHostDocument(): UseEditorHostDocumentReturn;
  * );
  * useHighlights('glossary', findTerms, { className: 'glossary-term' });
  * ```
+ *
+ * @see {@link https://www.docx-editor.dev/docs/2.x/recipes/highlight-ranges | Highlight ranges}
  * @public
  */
 declare function useHighlights(name: string, source: HighlightSource, options?: HighlightOptions): HighlightResult;
@@ -5641,5 +5739,5 @@ interface UseHistoryGroupReturn {
 /** Bind a control's native gesture lifecycle. Apply values through the existing command hooks. @public */
 declare function useHistoryGroup({ kind }: HistoryGroupBindingOptions): UseHistoryGroupReturn;
 
-export { CONTENT_CONTROL_SLOTS, ContextMenuCellVerticalAlignment, ContextMenuCopy, ContextMenuCopyFormatting, ContextMenuCut, ContextMenuDelete, ContextMenuDeleteTable, ContextMenuDeleteTableColumn, ContextMenuDeleteTableRow, ContextMenuInsertColumnLeft, ContextMenuInsertColumnRight, ContextMenuInsertRowAbove, ContextMenuInsertRowBelow, ContextMenuItem, ContextMenuPaste, ContextMenuPasteFormatting, ContextMenuPasteWithoutFormatting, ContextMenuRefreshToc, ContextMenuRefreshTocPageNumbers, ContextMenuSelectAll, DEFAULT_WATERMARK_PRESETS, DocumentName, DocumentOutline, DocxEditor, DocxEditorAuthorStyle, DocxEditorBookmarkDialog, DocxEditorColorByChangeType, DocxEditorContent, DocxEditorContentControl, DocxEditorContentControlWidget, DocxEditorContextMenu, DocxEditorDocumentOutline, DocxEditorEquation, DocxEditorExportDialog, DocxEditorFontNotice, DocxEditorHeaderFooterChrome, DocxEditorHorizontalRuler, DocxEditorHyperLink, DocxEditorImageAltTextPopup, DocxEditorImageInsertErrorDialog, DocxEditorImagePropertiesDialog, DocxEditorInvalidTextFormFieldDialog, DocxEditorLoading, DocxEditorLoadingSpinner, DocxEditorMenu, DocxEditorNavigation, DocxEditorNotePreview, DocxEditorNotePropertiesDialog, DocxEditorNotesChrome, DocxEditorNotesContextMenu, DocxEditorOpenFailure, DocxEditorOpenFailureAction, DocxEditorPageNumber, DocxEditorPageSetupDialog, DocxEditorParagraphDialog, DocxEditorPrintDialog, DocxEditorRevisionMarkup, DocxEditorRevisionMarkupDialog, DocxEditorRoot, DocxEditorShell, DocxEditorTextFormFieldDialog, DocxEditorToolbar, DocxEditorVerticalRuler, DocxEditorViewport, DocxEditorWatermarkDialog, DocxEditorWindow, HorizontalRuler, ImageAltText, ImageInsertProvider, ImageInsertTrigger, ImagePropertiesTrigger, ImageWrap, LocaleProvider, Logo, MenuBar, NAVIGATION_PANE_GAP, NAVIGATION_PANE_INSET, NAVIGATION_PANE_MIN_PAGE_ROOM, NAVIGATION_PANE_WIDTH, NavigationClose, NavigationFind, NavigationGoTo, NavigationHeader, NavigationHeadings, NavigationTab, NavigationTabs, NavigationTitle, NavigationToggle, OUTLINE_BUTTON_LEFT_OFFSET, OUTLINE_BUTTON_RESERVED_SPACE, OUTLINE_LEFT_OFFSET, OUTLINE_RESERVED_SPACE, PageIndicator, PageNumberTranslationContext, PaginatedDocxEditor, PaginatedDocxEditorShell, REVIEW_MARKERS_GUTTER, REVIEW_PANE_GUTTER, RULER_WIDTH, ReviewRailContext, Slot, TitleBar, TitleBarRight, Toolbar, ToolbarButton, ToolbarContext, ToolbarGroup, ToolbarImageProperties, VERSION, VerticalRuler, definePopup, editorStateActiveSubscriptionCount, isFieldLink, navigationPaneOverlays, navigationPaneReservation, navigationShift, normalizeImageBytes, notificationYieldsToTask, useProvidedDocxEditor as provideDocxEditor, reviewGutter, useBookmarkDialog, useBookmarks, useChromeTranslate, useCommentDraftRequest, useContentControl, useContentControlInstance, useContentControlWidget, useContextMenuTarget, useDocumentOutline, useDocumentSearch, useDocxEditor, useDocxSource, useEditorCaret, useEditorCommand, useEditorEvent, useEditorHostDocument, useEditorSnapshot, useEditorState, useEditorValueCommand, useFontFamily, useFonts, useGoToBookmark, useHeaderFooterState, useHighlightAt, useHighlights, useHistoryGroup, useHyperlinkPopup, useHyperlinkPopupInstance, useNavigationPane, useNavigationShift, useNotePropertiesState, useNoteScopeState, useOpenFailure, usePageSetup, usePageSetupDialog, useParagraphDialog, useParagraphFormat, useParagraphIndent, useParagraphStyle, useReviewAuthors, useReviewGutter, useRevisionMarkupDialog, useScopeClassName, useScopedChromeAnchor, useTableBorderTargetLabel, useTextFormFieldDialog, useToolbarContext, useToolbarLabel, useToolbarLabelFor, useTranslation, useWatermark, useWatermarkDialog, useZoom };
-export type { BookmarkDialogFields, ChromeTranslate, ContentControlActionProps, ContentControlInspectorState, ContentControlLock, ContentControlPartProps, ContentControlProps, ContentControlSlotId, ContentControlWidgetDayProps, ContentControlWidgetEntry, ContentControlWidgetItemProps, ContentControlWidgetPictureProps, ContextMenuAnchor, ContextMenuCommandProps, ContextMenuContextValue, ContextMenuItemProps, ContextMenuTableRowProps, DialogCustomizationProps, DialogPartProps, DocxEditorAuthorStyleProps, DocxEditorBookmarkDialogProps, DocxEditorChildren, DocxEditorContentControlNamespace, DocxEditorContentControlWidgetNamespace, DocxEditorContentControlWidgetPartProps, DocxEditorContentControlWidgetProps, DocxEditorContentProps, DocxEditorContextMenuNamespace, DocxEditorContextMenuProps, DocxEditorDocumentOutlineProps, DocxEditorExportDialogProps, DocxEditorFontNoticeProps, DocxEditorHeaderFooterChromeProps, DocxEditorHyperLinkNamespace, DocxEditorImageAltTextPopupProps, DocxEditorImageInsertErrorDialogProps, DocxEditorImagePropertiesDialogProps, DocxEditorInvalidTextFormFieldDialogProps, DocxEditorLoadingComponent, DocxEditorLoadingProps, DocxEditorLoadingSpinnerProps, DocxEditorMenuNamespace, DocxEditorMenuProps, DocxEditorNamespace, DocxEditorNavigationNamespace, DocxEditorNavigationProps, DocxEditorNotePreviewProps, DocxEditorNotePropertiesDialogProps, DocxEditorNotesChromeProps, DocxEditorNotesContextMenuProps, DocxEditorOpenFailureActionProps, DocxEditorOpenFailureComponent, DocxEditorOpenFailureContext, DocxEditorOpenFailureMessage, DocxEditorOpenFailureProps, DocxEditorPageNumberProps, DocxEditorPageSetupDialogProps, DocxEditorParagraphDialogProps, DocxEditorPopup, DocxEditorPopups, DocxEditorPrintDialogProps, DocxEditorProps, DocxEditorRef, DocxEditorRevisionMarkupDialogProps, DocxEditorRevisionMarkupProps, DocxEditorRootListeners, DocxEditorRootProps, DocxEditorRulerProps, DocxEditorTextFormFieldDialogProps, DocxEditorToolbarGroupProps, DocxEditorToolbarNamespace, DocxEditorToolbarProps, DocxEditorToolbarSlotProps, DocxEditorViewportProps, DocxEditorWatermarkDialogProps, DocxEditorWindowProps, DocxFontOrigin, DocxFontsInput, DocxFontsSource, DocxSource, EditorCaret, EditorCommandState, EditorMode, EditorValueCommandState, FontFamilyItemProps, FontFamilyNamespace, FontFamilyPartProps, FontFamilyProps, FontsInput, GoToBookmarkProblem, HeaderFooterState, HorizontalRulerProps$1 as HorizontalRulerProps, HyperLinkActionProps, HyperLinkPartProps, HyperLinkProps, HyperlinkPopupAnchor, HyperlinkPopupMode, HyperlinkPopupState, ImagePropertiesTriggerProps, IndentUpdate, LocaleProviderProps, MaybeRefOrGetter, MenuActionProps, MenuGroupProps, MenuId, MenuItemBaseProps, MenuItemProps, MenuPartComponent, MenuProps, MenuReportIssueProps, MenuReviewersProps, MenuRowProps, MenuSeparatorProps, MenuSubmenuBaseProps, MenuSubmenuProps, MenuTableGridProps, NavigationPartProps, NavigationShiftInput, NavigationTabProps, NavigationTab$1 as NavigationTabValue, NormalizedImagePayload, NotePropertiesState, OutlineHeading$1 as OutlineHeading, OutlineHeadingItem, PageIndicatorProps, PageSetupDialogFields, PageSetupUpdate, PaginatedDocxEditorExpose, PaginatedDocxEditorHandle, PaginatedDocxEditorProps, PaginatedDocxEditorShellProps, ParagraphStyleItemProps, ParagraphStyleNamespace, ParagraphStyleOption, ParagraphStylePartProps, ParagraphStyleProps, ProvideDocxEditorResult, ReviewGutter, ReviewGutterInput, ReviewRailRegistry, ScopedChromeAnchor, SlotProps, TableBorderColorNamespace, TableBorderStyleNamespace, TableBorderTargetNamespace, TableBorderWidthNamespace, TableCellFillNamespace, TableChromeItemProps, TableChromePartComponent, TableChromePartProps, TextFormFieldDialogFields, ToolbarActionProps, ToolbarAlignmentComponent, ToolbarButtonProps$1 as ToolbarButtonProps, ToolbarContextValue, ToolbarPartComponent, ToolbarPartProps, ToolbarProps, ToolbarReviewersProps, ToolbarSeparatorProps, ToolbarSlotPartComponent, ToolbarSlotPartProps, ToolbarTranslate, UseBookmarkDialogReturn, UseBookmarksReturn, UseContentControlResult, UseContentControlWidgetResult, UseDialogReturn, UseDocumentOutlineResult, UseDocumentSearchOptions, UseDocumentSearchResult, UseDocxSourceOptions, UseDocxSourceResult, UseEditorHostDocumentReturn, UseFontFamilyResult, UseGoToBookmarkOptions, UseGoToBookmarkReturn, UseHistoryGroupReturn, UseHyperlinkPopupResult, UseNavigationPaneOptions, UseNavigationPaneResult, UseOpenFailureOptions, UseOpenFailureReturn, UsePageSetupDialogReturn, UsePageSetupReturn, UseParagraphDialogReturn, UseParagraphFormatReturn, UseParagraphIndentReturn, UseParagraphStyleResult, UseRevisionMarkupDialogReturn, UseTextFormFieldDialogReturn, UseWatermarkDialogReturn, UseWatermarkReturn, UseZoomResult, VerticalRulerProps, WatermarkDialogFieldName, WatermarkDialogFields, WatermarkDialogKind, WatermarkDialogLayout };
+export { CONTENT_CONTROL_SLOTS, ContextMenuCellVerticalAlignment, ContextMenuCopy, ContextMenuCopyFormatting, ContextMenuCut, ContextMenuDelete, ContextMenuDeleteTable, ContextMenuDeleteTableColumn, ContextMenuDeleteTableRow, ContextMenuInsertColumnLeft, ContextMenuInsertColumnRight, ContextMenuInsertRowAbove, ContextMenuInsertRowBelow, ContextMenuItem, ContextMenuMergeCells, ContextMenuPaste, ContextMenuPasteFormatting, ContextMenuPasteWithoutFormatting, ContextMenuRefreshToc, ContextMenuRefreshTocPageNumbers, ContextMenuSelectAll, ContextMenuSplitCell, DEFAULT_WATERMARK_PRESETS, DocumentName, DocumentOutline, DocxEditor, DocxEditorAuthorStyle, DocxEditorBookmarkDialog, DocxEditorColorByChangeType, DocxEditorContent, DocxEditorContentControl, DocxEditorContentControlWidget, DocxEditorContextMenu, DocxEditorDocumentOutline, DocxEditorEquation, DocxEditorExportDialog, DocxEditorFontNotice, DocxEditorHeaderFooterChrome, DocxEditorHorizontalRuler, DocxEditorHyperLink, DocxEditorImageAltTextPopup, DocxEditorImageInsertErrorDialog, DocxEditorImagePropertiesDialog, DocxEditorInvalidTextFormFieldDialog, DocxEditorLoading, DocxEditorLoadingSpinner, DocxEditorMenu, DocxEditorNavigation, DocxEditorNotePreview, DocxEditorNotePropertiesDialog, DocxEditorNotesChrome, DocxEditorNotesContextMenu, DocxEditorOpenFailure, DocxEditorOpenFailureAction, DocxEditorPageNumber, DocxEditorPageSetupDialog, DocxEditorParagraphDialog, DocxEditorPrintDialog, DocxEditorRevisionMarkup, DocxEditorRevisionMarkupDialog, DocxEditorRoot, DocxEditorShell, DocxEditorSplitCellDialog, DocxEditorTextFormFieldDialog, DocxEditorToolbar, DocxEditorUnsupportedElement, DocxEditorVerticalRuler, DocxEditorViewport, DocxEditorWatermarkDialog, DocxEditorWindow, HorizontalRuler, ImageAltText, ImageInsertProvider, ImageInsertTrigger, ImagePropertiesTrigger, ImageWrap, LocaleProvider, Logo, MenuBar, NAVIGATION_PANE_GAP, NAVIGATION_PANE_INSET, NAVIGATION_PANE_MIN_PAGE_ROOM, NAVIGATION_PANE_WIDTH, NavigationClose, NavigationFind, NavigationGoTo, NavigationHeader, NavigationHeadings, NavigationTab, NavigationTabs, NavigationTitle, NavigationToggle, OUTLINE_BUTTON_LEFT_OFFSET, OUTLINE_BUTTON_RESERVED_SPACE, OUTLINE_LEFT_OFFSET, OUTLINE_RESERVED_SPACE, PageIndicator, PageNumberTranslationContext, PaginatedDocxEditor, PaginatedDocxEditorShell, REVIEW_MARKERS_GUTTER, REVIEW_PANE_GUTTER, RULER_WIDTH, ReviewRailContext, Slot, TitleBar, TitleBarRight, Toolbar, ToolbarButton, ToolbarContext, ToolbarGroup, ToolbarImageProperties, VERSION, VerticalRuler, definePopup, editorStateActiveSubscriptionCount, isFieldLink, navigationPaneOverlays, navigationPaneReservation, navigationShift, normalizeImageBytes, notificationYieldsToTask, useProvidedDocxEditor as provideDocxEditor, reviewGutter, useBookmarkDialog, useBookmarks, useChromeTranslate, useCommentDraftRequest, useContentControl, useContentControlInstance, useContentControlWidget, useContextMenuTarget, useDocumentOutline, useDocumentSearch, useDocxEditor, useDocxSource, useEditorCaret, useEditorCommand, useEditorEvent, useEditorHostDocument, useEditorSnapshot, useEditorState, useEditorValueCommand, useFontFamily, useFonts, useGoToBookmark, useHeaderFooterState, useHighlightAt, useHighlights, useHistoryGroup, useHyperlinkPopup, useHyperlinkPopupInstance, useNavigationPane, useNavigationShift, useNotePropertiesState, useNoteScopeState, useOpenFailure, usePageSetup, usePageSetupDialog, useParagraphDialog, useParagraphFormat, useParagraphIndent, useParagraphStyle, useReviewAuthors, useReviewGutter, useRevisionMarkupDialog, useScopeClassName, useScopedChromeAnchor, useSplitCellDialog, useTableBorderTargetLabel, useTextFormFieldDialog, useToolbarContext, useToolbarLabel, useToolbarLabelFor, useTranslation, useWatermark, useWatermarkDialog, useZoom };
+export type { BookmarkDialogFields, ChromeTranslate, ContentControlActionProps, ContentControlInspectorState, ContentControlLock, ContentControlPartProps, ContentControlProps, ContentControlSlotId, ContentControlWidgetDayProps, ContentControlWidgetEntry, ContentControlWidgetItemProps, ContentControlWidgetPictureProps, ContextMenuAnchor, ContextMenuCommandProps, ContextMenuContextValue, ContextMenuItemProps, ContextMenuTableRowProps, DialogCustomizationProps, DialogPartProps, DocumentStyleSummary, DocxEditorAuthorStyleProps, DocxEditorBookmarkDialogProps, DocxEditorChildren, DocxEditorContentControlNamespace, DocxEditorContentControlWidgetNamespace, DocxEditorContentControlWidgetPartProps, DocxEditorContentControlWidgetProps, DocxEditorContentProps, DocxEditorContextMenuNamespace, DocxEditorContextMenuProps, DocxEditorDocumentOutlineProps, DocxEditorExportDialogProps, DocxEditorFontNoticeProps, DocxEditorHeaderFooterChromeProps, DocxEditorHyperLinkNamespace, DocxEditorImageAltTextPopupProps, DocxEditorImageInsertErrorDialogProps, DocxEditorImagePropertiesDialogProps, DocxEditorInvalidTextFormFieldDialogProps, DocxEditorLoadingComponent, DocxEditorLoadingProps, DocxEditorLoadingSpinnerProps, DocxEditorMenuNamespace, DocxEditorMenuProps, DocxEditorNamespace, DocxEditorNavigationNamespace, DocxEditorNavigationProps, DocxEditorNotePreviewProps, DocxEditorNotePropertiesDialogProps, DocxEditorNotesChromeProps, DocxEditorNotesContextMenuProps, DocxEditorOpenFailureActionProps, DocxEditorOpenFailureComponent, DocxEditorOpenFailureContext, DocxEditorOpenFailureMessage, DocxEditorOpenFailureProps, DocxEditorPageNumberProps, DocxEditorPageSetupDialogProps, DocxEditorParagraphDialogProps, DocxEditorPopup, DocxEditorPopups, DocxEditorPrintDialogProps, DocxEditorProps, DocxEditorRef, DocxEditorRefCallback, DocxEditorRevisionMarkupDialogProps, DocxEditorRevisionMarkupProps, DocxEditorRootListeners, DocxEditorRootProps, DocxEditorRulerProps, DocxEditorSplitCellDialogProps, DocxEditorTextFormFieldDialogProps, DocxEditorToolbarGroupProps, DocxEditorToolbarNamespace, DocxEditorToolbarProps, DocxEditorToolbarSlotProps, DocxEditorUnsupportedElementProps, DocxEditorViewportProps, DocxEditorWatermarkDialogProps, DocxEditorWindowProps, DocxFontOrigin, DocxFontsInput, DocxFontsSource, DocxSource, EditorCaret, EditorCommandState, EditorMode, EditorValueCommandState, FontFamilyItemProps, FontFamilyNamespace, FontFamilyPartProps, FontFamilyProps, FontOption, FontsInput, FormattingAction, GoToBookmarkProblem, HeaderFooterState, HorizontalRulerProps$1 as HorizontalRulerProps, HyperLinkActionProps, HyperLinkPartProps, HyperLinkProps, HyperlinkPopupAnchor, HyperlinkPopupMode, HyperlinkPopupState, ImagePropertiesTriggerProps, IndentUpdate, ListState, ListType, LocaleProviderProps, MaybeRefOrGetter, MenuActionProps, MenuGroupProps, MenuId, MenuItemBaseProps, MenuItemProps, MenuPartComponent, MenuProps, MenuReportIssueProps, MenuReviewersProps, MenuRowProps, MenuSeparatorProps, MenuSubmenuBaseProps, MenuSubmenuProps, MenuTableGridProps, NavigationPartProps, NavigationShiftInput, NavigationTabProps, NavigationTab$1 as NavigationTabValue, NormalizedImagePayload, NotePropertiesState, OutlineHeading$1 as OutlineHeading, OutlineHeadingItem, PageIndicatorProps, PageSetupDialogFields, PageSetupUpdate, PaginatedDocxEditorExpose, PaginatedDocxEditorHandle, PaginatedDocxEditorProps, PaginatedDocxEditorShellProps, ParagraphAlignment, ParagraphStyleItemProps, ParagraphStyleNamespace, ParagraphStyleOption, ParagraphStylePartProps, ParagraphStyleProps, ProvideDocxEditorResult, ReviewGutter, ReviewGutterInput, ReviewRailRegistry, ScopedChromeAnchor, ScopedChromeAnchorPlacement, SelectionFormatting, SlotProps, SplitCellDialogFields, TableAction, TableBorderColorNamespace, TableBorderStyleNamespace, TableBorderTargetNamespace, TableBorderWidthNamespace, TableCellFillNamespace, TableChromeItemProps, TableChromePartComponent, TableChromePartProps, TextFormFieldDialogFields, ToolbarActionProps, ToolbarAlignmentComponent, ToolbarButtonProps$1 as ToolbarButtonProps, ToolbarContextValue, ToolbarPartComponent, ToolbarPartProps, ToolbarProps, ToolbarReviewersProps, ToolbarSeparatorProps, ToolbarSlotPartComponent, ToolbarSlotPartProps, ToolbarTranslate, UseBookmarkDialogReturn, UseBookmarksReturn, UseContentControlResult, UseContentControlWidgetResult, UseDialogReturn, UseDocumentOutlineResult, UseDocumentSearchOptions, UseDocumentSearchResult, UseDocxSourceOptions, UseDocxSourceResult, UseEditorHostDocumentReturn, UseFontFamilyResult, UseGoToBookmarkOptions, UseGoToBookmarkReturn, UseHistoryGroupReturn, UseHyperlinkPopupResult, UseNavigationPaneOptions, UseNavigationPaneResult, UseOpenFailureOptions, UseOpenFailureReturn, UsePageSetupDialogReturn, UsePageSetupReturn, UseParagraphDialogReturn, UseParagraphFormatReturn, UseParagraphIndentReturn, UseParagraphStyleResult, UseRevisionMarkupDialogReturn, UseSplitCellDialogReturn, UseTextFormFieldDialogReturn, UseWatermarkDialogReturn, UseWatermarkReturn, UseZoomResult, VerticalRulerProps, WatermarkDialogFieldName, WatermarkDialogFields, WatermarkDialogKind, WatermarkDialogLayout };