@eigenpal/docx-editor-react/hooks
React hooks for editor history, table selection, find/replace, autosave, clipboard, and zoom. Use alongside the main `DocxEditor` component.
Functions(22)
clampZoom
Clamp zoom to valid range
declare function clampZoom(zoom: number, minZoom?: number, maxZoom?: number): number;findNearestZoomPreset
Find nearest zoom preset
declare function findNearestZoomPreset(zoom: number): number;formatZoom
Format zoom level for display
declare function formatZoom(zoom: number): string;generateOverlayElements
Generate selection overlay elements (for use in JSX)
Usage:
```tsx const { highlightRects } = useSelectionHighlight({ ... }); return ( <div style={{ position: 'relative' }}> {generateOverlayElements(highlightRects)} <div>... content ...</div> </div> ); ```
declare function generateOverlayElements(rects: HighlightRect[], config?: SelectionHighlightConfig): React__default.ReactNode[];getNextZoomPreset
Get next zoom preset (for zoom in)
declare function getNextZoomPreset(zoom: number): number;getPreviousZoomPreset
Get previous zoom preset (for zoom out)
declare function getPreviousZoomPreset(zoom: number): number;getZoomPresets
Get zoom presets
declare function getZoomPresets(): number[];isZoomPreset
Check if zoom level is at a preset
declare function isZoomPreset(zoom: number): boolean;parseZoom
Parse zoom from percentage string
declare function parseZoom(zoomString: string): number | null;useAspectLockedSize
declare function useAspectLockedSize(): UseAspectLockedSizeReturn;useAutoHistory
Simplified hook that just tracks state changes automatically
declare function useAutoHistory<T>(value: T, options?: UseHistoryOptions<T>): Omit<UseHistoryReturn<T>, 'push'>;useAutoSave
declare function useAutoSave(document: Document | null | undefined, options?: UseAutoSaveOptions): UseAutoSaveReturn;useClipboard
declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;useDocumentHistory
Hook for document history with specialized comparison
declare function useDocumentHistory<T extends {
package?: {
document?: unknown;
headers?: unknown;
footers?: unknown;
} | null;
} | null>(document: T, options?: Omit<UseHistoryOptions<T>, 'isEqual'>): UseHistoryReturn<T>;useDragAutoScroll
declare function useDragAutoScroll(input: DragAutoScrollOptions): {
updateMousePosition: (clientX: number, clientY: number) => void;
stopAutoScroll: () => void;
};useFindReplace
Hook for managing find/replace dialog state
declare function useFindReplace(hookOptions?: FindReplaceOptions): UseFindReplaceReturn;useFixedDropdown
declare function useFixedDropdown(input: UseFixedDropdownOptions): UseFixedDropdownReturn;useHistory
Custom hook for managing undo/redo history
declare function useHistory<T>(initialState: T, options?: UseHistoryOptions<T>): UseHistoryReturn<T>;useSelectionHighlight
Hook to manage selection highlighting in the editor
declare function useSelectionHighlight(options: UseSelectionHighlightOptions): UseSelectionHighlightReturn;useTableSelection
declare function useTableSelection(input: UseTableSelectionOptions): UseTableSelectionReturn;useWheelZoom
React hook for Ctrl+scroll zoom functionality
declare function useWheelZoom(options?: UseWheelZoomOptions): UseWheelZoomReturn;Classes(1)
HistoryManager
Create a history manager for non-React usage
declare class HistoryManager<T>| Member | Type | Summary |
|---|---|---|
| (constructor) | — | Constructs a new instance of the `HistoryManager` class |
| canRedo | boolean | |
| canUndo | boolean | |
| clear | — | |
| push | — | |
| redo | — | |
| reset | — | |
| state | T | |
| undo | — |
Interfaces(23)
DragAutoScrollOptions
Drag Auto-Scroll Hook
When the user is drag-selecting text and moves the mouse near the top or bottom edge of the scroll container, this hook auto-scrolls the container and continues extending the selection.
interface DragAutoScrollOptions| Member | Type | Summary |
|---|---|---|
| onScrollExtendSelection | (clientX: number, clientY: number) => void | Called during auto-scroll to extend the selection at the current mouse position. |
| pagesContainerRef | React.RefObject<HTMLDivElement | null> | Ref to the pages container (used to find the scroll parent). |
FindReplaceOptions
Options for the useFindReplace hook
interface FindReplaceOptions| Member | Type | Summary |
|---|---|---|
| initialReplaceMode? | boolean | Whether to show replace functionality initially |
| onCurrentMatchChange? | (match: FindMatch | null, index: number) => void | Callback when current match changes |
| onMatchesChange? | (matches: FindMatch[]) => void | Callback when matches change |
FindReplaceState
State for the find/replace hook
interface FindReplaceState| Member | Type | Summary |
|---|---|---|
| currentIndex | number | Current match index |
| isOpen | boolean | Whether the dialog is open |
| matches | FindMatch[] | All matches found |
| options | FindOptions | Find options |
| replaceMode | boolean | Whether in replace mode |
| replaceText | string | Current replace text |
| searchText | string | Current search text |
HistoryEntry
History entry containing state and metadata
interface HistoryEntry<T>| Member | Type | Summary |
|---|---|---|
| description? | string | Optional description of what changed |
| state | T | The state at this point |
| timestamp | number | Timestamp when this entry was created |
SelectionOverlayProps
Props for selection overlay component
interface SelectionOverlayProps| Member | Type | Summary |
|---|---|---|
| className? | string | Additional class name |
| config? | SelectionHighlightConfig | Style configuration |
| rects | HighlightRect[] | Highlight rectangles to render |
TableSelectionState
useTableSelection Hook
Thin React wrapper around the framework-agnostic TableSelectionManager. Provides table selection tracking and table operation dispatch.
interface TableSelectionState| Member | Type | Summary |
|---|---|---|
| columnIndex | number | null | |
| context | TableContext | null | |
| rowIndex | number | null | |
| table | Table | null | |
| tableIndex | number | null |
UseAspectLockedSizeReturn
Width/height inputs with an optional aspect-ratio lock. `width`/`height` are `number | ''` so a cleared field shows empty instead of 0.
interface UseAspectLockedSizeReturn| Member | Type | Summary |
|---|---|---|
| handleHeightChange | (raw: string) => void | |
| handleWidthChange | (raw: string) => void | Number-input onChange handlers. Empty string clears, otherwise clamps to = 1. |
| height | number | '' | |
| lockAspect | boolean | |
| seed | (w: number | null | undefined, h: number | null | undefined) => void | Seed both fields and re-lock. Null/undefined values clear the input. |
| setLockAspect | (locked: boolean) => void | |
| width | number | '' |
UseAutoSaveOptions
Options for useAutoSave hook
interface UseAutoSaveOptions| Member | Type | Summary |
|---|---|---|
| debounceDelay? | number | Debounce delay for saveOnChange in milliseconds (default: 2000) |
| enabled? | boolean | Whether auto-save is enabled (default: true) |
| interval? | number | Save interval in milliseconds (default: 30000 - 30 seconds) |
| maxAge? | number | Maximum age of auto-save in milliseconds before it's considered stale (default: 24 hours) |
| onError? | (error: Error) => void | Callback when save fails |
| onRecoveryAvailable? | (savedDocument: SavedDocumentData) => void | Callback when recovery data is found |
| onSave? | (timestamp: Date) => void | Callback when save succeeds |
| saveOnChange? | boolean | Whether to save immediately when document changes (debounced) |
| storageKey? | string | Storage key for localStorage (default: 'docx-editor-autosave') |
UseAutoSaveReturn
Return value of useAutoSave hook
interface UseAutoSaveReturn| Member | Type | Summary |
|---|---|---|
| acceptRecovery | () => Document | null | |
| clearAutoSave | () => void | |
| disable | () => void | |
| dismissRecovery | () => void | |
| enable | () => void | |
| getRecoveryData | () => SavedDocumentData | null | |
| hasRecoveryData | boolean | |
| isEnabled | boolean | |
| lastSaveTime | Date | null | |
| save | () => Promise<boolean> | |
| status | AutoSaveStatus |
UseClipboardOptions
useClipboard Hook
Thin React wrapper around the framework-agnostic ClipboardManager. Handles clipboard operations with formatting preservation.
interface UseClipboardOptions| Member | Type | Summary |
|---|---|---|
| cleanWordFormatting? | boolean | |
| editable? | boolean | |
| onCopy? | (selection: ClipboardSelection) => void | |
| onCut? | (selection: ClipboardSelection) => void | |
| onError? | (error: Error) => void | |
| onPaste? | (content: ParsedClipboardContent, asPlainText: boolean) => void | |
| theme? | Theme | null | Document theme — used to resolve themed colors in the HTML clipboard payload. |
UseClipboardReturn
interface UseClipboardReturn| Member | Type | Summary |
|---|---|---|
| copy | (selection: ClipboardSelection) => Promise<boolean> | |
| cut | (selection: ClipboardSelection) => Promise<boolean> | |
| handleCopy | (event: ClipboardEvent) => void | |
| handleCut | (event: ClipboardEvent) => void | |
| handleKeyDown | (event: KeyboardEvent) => void | |
| handlePaste | (event: ClipboardEvent) => void | |
| isProcessing | boolean | |
| lastPastedContent | ParsedClipboardContent | null | |
| paste | (asPlainText?: boolean) => Promise<ParsedClipboardContent | null> |
UseFindReplaceReturn
Return type for the useFindReplace hook
interface UseFindReplaceReturn| Member | Type | Summary |
|---|---|---|
| close | () => void | Close the dialog |
| getCurrentMatch | () => FindMatch | null | Get current match |
| goToMatch | (index: number) => void | Go to a specific match by index |
| goToNextMatch | () => number | Go to next match |
| goToPreviousMatch | () => number | Go to previous match |
| hasMatches | () => boolean | Check if has matches |
| openFind | (selectedText?: string) => void | Open the find dialog |
| openReplace | (selectedText?: string) => void | Open the replace dialog |
| setMatches | (matches: FindMatch[], currentIndex?: number) => void | Set search results |
| setOptions | (options: Partial<FindOptions>) => void | Update find options |
| setReplaceText | (text: string) => void | Update replace text |
| setSearchText | (text: string) => void | Update search text |
| state | FindReplaceState | Current state |
| toggle | () => void | Toggle dialog visibility |
UseFixedDropdownOptions
Hook for toolbar dropdowns that need position:fixed to escape overflow:auto/hidden ancestors.
Returns refs and styles for a dropdown that positions itself below its trigger using fixed coordinates (like MenuDropdown), so it isn't clipped by the toolbar's overflow-x-auto container.
interface UseFixedDropdownOptions| Member | Type | Summary |
|---|---|---|
| align? | 'left' | 'right' | 'left' aligns dropdown left edge to trigger, 'right' aligns right edge |
| isOpen | boolean | |
| onClose | () => void |
UseFixedDropdownReturn
interface UseFixedDropdownReturn| Member | Type | Summary |
|---|---|---|
| containerRef | RefObject<HTMLDivElement | null> | |
| dropdownRef | RefObject<HTMLDivElement | null> | |
| dropdownStyle | CSSProperties | |
| handleMouseDown | (e: React.MouseEvent) => void |
UseHistoryOptions
Options for the useHistory hook
interface UseHistoryOptions<T>| Member | Type | Summary |
|---|---|---|
| containerRef? | React.RefObject<HTMLElement> | Ref to the container element for keyboard events |
| enableKeyboardShortcuts? | boolean | Whether to enable keyboard shortcuts (default: true) |
| groupingInterval? | number | Time in ms to group rapid changes (default: 500) |
| isEqual? | (a: T, b: T) => boolean | Custom comparison function for detecting changes |
| maxEntries? | number | Maximum number of entries in history (default: 100) |
| onRedo? | (state: T) => void | Callback when redo is triggered |
| onUndo? | (state: T) => void | Callback when undo is triggered |
UseHistoryReturn
Return type of the useHistory hook
interface UseHistoryReturn<T>| Member | Type | Summary |
|---|---|---|
| canRedo | boolean | Whether redo is available |
| canUndo | boolean | Whether undo is available |
| clear | () => void | Clear all history |
| getRedoStack | () => HistoryEntry<T>[] | Get all redo entries (for debugging/display) |
| getUndoStack | () => HistoryEntry<T>[] | Get all undo entries (for debugging/display) |
| push | (newState: T, description?: string) => void | Push a new state to history |
| redo | () => T | undefined | Redo to next state |
| redoCount | number | Number of entries in redo stack |
| reset | (newInitialState?: T) => void | Reset to initial state and clear history |
| state | T | Current state |
| transformAll | (fn: (state: T) => T) => void | Transform all stored states (current + undo/redo stacks) |
| undo | () => T | undefined | Undo to previous state |
| undoCount | number | Number of entries in undo stack |
UseSelectionHighlightOptions
Options for the useSelectionHighlight hook
interface UseSelectionHighlightOptions| Member | Type | Summary |
|---|---|---|
| config? | SelectionHighlightConfig | Custom highlight configuration |
| containerRef | React__default.RefObject<HTMLElement> | Reference to the container element |
| debounceMs? | number | Debounce delay for rect updates in ms (default: 16) |
| enabled? | boolean | Whether to enable selection highlighting |
| onSelectionChange? | (hasSelection: boolean, text: string) => void | Callback when selection changes |
| useOverlay? | boolean | Whether to use overlay rectangles (default: false, uses CSS) |
UseSelectionHighlightReturn
Return value from the useSelectionHighlight hook
interface UseSelectionHighlightReturn| Member | Type | Summary |
|---|---|---|
| getOverlayStyle | (rect: HighlightRect) => CSSProperties | Get styles for a highlight rect overlay |
| hasSelection | boolean | Whether there is an active selection |
| highlightRects | HighlightRect[] | Highlight rectangles (only populated if useOverlay is true) |
| isSelectionInContainer | boolean | Whether selection is within the container |
| refresh | () => void | Refresh the highlight state |
| selectedText | string | The selected text |
UseTableSelectionOptions
interface UseTableSelectionOptions| Member | Type | Summary |
|---|---|---|
| document | Document | null | |
| onChange? | (document: Document) => void | |
| onSelectionChange? | (context: TableContext | null) => void |
UseTableSelectionReturn
interface UseTableSelectionReturn| Member | Type | Summary |
|---|---|---|
| applySplitCell | (rows: number, cols: number) => void | |
| clearSelection | () => void | |
| getSplitCellConfig | () => TableSplitConfig | null | |
| handleAction | (action: TableAction) => void | |
| handleCellClick | (tableIndex: number, rowIndex: number, columnIndex: number) => void | |
| isCellSelected | (tableIndex: number, rowIndex: number, columnIndex: number) => boolean | |
| state | TableSelectionState | |
| tableContext | TableContext | null |
UseWheelZoomOptions
Options for useWheelZoom hook
interface UseWheelZoomOptions| Member | Type | Summary |
|---|---|---|
| containerRef? | React.RefObject<HTMLElement> | Container element ref to attach wheel listener |
| enabled? | boolean | Whether zoom is enabled (default: true) |
| enableKeyboardShortcuts? | boolean | Whether to enable keyboard shortcuts (Ctrl++, Ctrl+-, Ctrl+0) |
| initialZoom? | number | Initial zoom level (default: 1.0) |
| maxZoom? | number | Maximum zoom level (default: 4.0) |
| minZoom? | number | Minimum zoom level (default: 0.25) |
| onZoomChange? | (zoom: number) => void | Callback when zoom changes |
| preventDefault? | boolean | Whether to prevent default browser zoom behavior |
| zoomStep? | number | Zoom step for each scroll event (default: 0.1) |
UseWheelZoomReturn
Return value of useWheelZoom hook
interface UseWheelZoomReturn| Member | Type | Summary |
|---|---|---|
| handleKeyDown | (event: KeyboardEvent) => void | Keyboard event handler (for manual attachment) |
| handleWheel | (event: WheelEvent) => void | Wheel event handler (for manual attachment) |
| isMaxZoom | boolean | Whether currently at maximum zoom |
| isMinZoom | boolean | Whether currently at minimum zoom |
| resetZoom | () => void | Reset zoom to initial level |
| setZoom | (zoom: number) => void | Set zoom level directly |
| zoom | number | Current zoom level |
| zoomIn | () => void | Zoom in by step |
| zoomOut | () => void | Zoom out by step |
| zoomPercent | number | Zoom percentage (e.g., 100 for zoom level 1.0) |
| zoomTo100 | () => void | Reset zoom to 100% |
| zoomToFit | (containerWidth: number, contentWidth: number) => void | Zoom to fit width |
Variables(1)
ZOOM_PRESETS
Preset zoom levels for snapping
ZOOM_PRESETS: number[]