@extend-ai/react-xlsx 0.16.5 → 0.17.0

package/dist/index.d.cts

@@ -117,6 +117,7 @@ interface XlsxSheetData {
     hasVerticalMerges: boolean;
     maxHorizontalMergeEndCol: number;
     maxVerticalMergeEndRow: number;
+    mergedRanges?: XlsxCellRange[];
     minUsedCol: number;
     minUsedRow: number;
     maxUsedCol: number;
@@ -146,6 +147,23 @@ interface XlsxCellRange {
     end: XlsxCellAddress;
     start: XlsxCellAddress;
 }
+interface XlsxParsedRange {
+    kind: "cells" | "rows" | "columns";
+    range: XlsxCellRange;
+    sheetName: string | null;
+}
+interface XlsxHighlightRangeOptions {
+    /** Navigates to the worksheet and reveals the first range. Defaults to true. */
+    autoScroll?: boolean;
+    /** Visible worksheet index for an unqualified reference. Defaults to the active worksheet. */
+    sheetIndex?: number;
+}
+interface XlsxRangeHighlight extends XlsxParsedRange {
+    /** Whether this entry is the navigation target for the current highlight update. */
+    autoScroll: boolean;
+    sheetName: string;
+    workbookSheetIndex: number;
+}
 /**
  * Color value accepted by persisted workbook style mutation APIs.
  *
@@ -1037,6 +1055,11 @@ interface XlsxViewerController {
     addFormControl: (input: XlsxFormControlInput, sheetIndex?: number) => number | null;
     clearSelectedCells: () => void;
     clearSelection: () => void;
+    /** Removes all render-only range highlights. */
+    clearHighlightedRanges: () => void;
+    /** Replaces the highlights with validated A1 ranges. Returns false without changing state if any reference cannot be resolved. */
+    highlightRanges: (references: string | readonly string[], options?: XlsxHighlightRangeOptions) => boolean;
+    highlightedRanges: XlsxRangeHighlight[];
     continueDeferredLoad: () => void;
     copySelectionToClipboard: () => Promise<boolean>;
     defaultZoomScale: number;
@@ -1397,6 +1420,15 @@ interface XlsxTableHeaderMenuRenderProps {
     /** Props that must be applied to your menu trigger button so grid selection does not receive the click. */
     triggerProps: React.ButtonHTMLAttributes<HTMLButtonElement>;
 }
+interface XlsxActiveCellOverlayRenderProps {
+    /** Address of the active cell. For merged cells this is the merge anchor. */
+    cell: XlsxCellAddress;
+    /**
+     * Pixel rect of the active cell (spanning the full merge) within the grid's scroll content,
+     * at the current zoom. The rendered node is already positioned to fill this rect.
+     */
+    rect: XlsxImageRect;
+}
 interface XlsxCellStyleContext {
     /** Address of the cell being styled. */
     cell: XlsxCellAddress;
@@ -1446,6 +1478,12 @@ interface XlsxViewerProviderProps extends UseXlsxViewerControllerOptions {
     isDark?: boolean;
 }
 interface XlsxViewerProps extends UseXlsxViewerControllerOptions {
+    /** Render-only A1 ranges to highlight. Null or an empty array clears them; undefined leaves controller state alone. */
+    highlightedRanges?: string | readonly string[] | null;
+    /** Reveals the first newly highlighted range, including switching worksheets. Defaults to true. */
+    autoScrollToHighlightedRanges?: boolean;
+    /** Additional CSS class applied to the range highlight in both renderers. */
+    highlightClassName?: string;
     /**
      * Allows row and column resizing even while editing is disabled by `readOnly`.
      *
@@ -1612,6 +1650,24 @@ interface XlsxViewerProps extends UseXlsxViewerControllerOptions {
      * Apply `triggerProps` to your actual trigger button so clicks do not leak into grid selection.
      */
     renderTableHeaderMenu?: (props: XlsxTableHeaderMenuRenderProps) => React.ReactNode;
+    /**
+     * Renders custom content positioned over the active cell. The returned node is placed in a
+     * container that exactly covers the cell, so it can carry classes, data attributes, or refs
+     * for measuring the cell with `getBoundingClientRect()`.
+     *
+     * The container ignores pointer events so grid interaction is unaffected; set
+     * `pointerEvents: "auto"` on your own elements to make them interactive.
+     *
+     * @example
+     * ```tsx
+     * <XlsxViewer
+     *   renderActiveCellOverlay={({ cell }) => (
+     *     <div data-active-cell={`${cell.row}:${cell.col}`} style={{ height: "100%", width: "100%" }} />
+     *   )}
+     * />
+     * ```
+     */
+    renderActiveCellOverlay?: (props: XlsxActiveCellOverlayRenderProps) => React.ReactNode;
     /**
      * Shows worksheet images, charts, shapes, and form controls.
      *
@@ -1642,6 +1698,9 @@ declare class XlsxFileSizeLimitExceededError extends Error {
 }
 declare function useXlsxViewerController(options: UseXlsxViewerControllerOptions): XlsxViewerController;
 
+/** Parses one rectangular A1 reference into normalized, zero-based coordinates. */
+declare function parseXlsxRange(reference: string): XlsxParsedRange | null;
+
 type XlsxWasmSource = string | URL | Request | Response | BufferSource | WebAssembly.Module;
 declare function setWasmSource(source: XlsxWasmSource): void;
 declare function initWasm(source?: XlsxWasmSource): Promise<typeof _dukelib_sheets_wasm>;
@@ -1658,4 +1717,4 @@ declare function useXlsxViewerThumbnails(options?: UseXlsxViewerThumbnailsOption
 declare function XlsxViewer(props: XlsxViewerProps): react_jsx_runtime.JSX.Element;
 declare function DefaultXlsxToolbar(): react_jsx_runtime.JSX.Element;
 
-export { DefaultXlsxToolbar, type UseXlsxViewerControllerOptions, type UseXlsxViewerThumbnailsOptions, type XlsxCellAddress, type XlsxCellAlignmentInput, type XlsxCellBorderEdgeInput, type XlsxCellBorderStyleInput, type XlsxCellFillStyleInput, type XlsxCellFontStyleInput, type XlsxCellGradientStopInput, type XlsxCellNumberFormatInput, type XlsxCellProtectionInput, type XlsxCellRange, type XlsxCellStyleColorInput, type XlsxCellStyleContext, type XlsxCellStyleInput, type XlsxChart, type XlsxChartAxis, type XlsxChartDataLabels, type XlsxChartElementSelection, type XlsxChartLoadingRenderProps, type XlsxChartReference, type XlsxChartSeries, type XlsxChartsheet, type XlsxDrawingLayout, XlsxFileSizeLimitExceededError, type XlsxFileTooLargeRenderProps, type XlsxFormControl, type XlsxFormControlActionEvent, type XlsxFormControlCaption, type XlsxFormControlCaptionInput, type XlsxFormControlCaptionRun, type XlsxFormControlChangeEvent, type XlsxFormControlInput, type XlsxFormControlKind, type XlsxFormControlKindInput, type XlsxFormControlPatch, type XlsxFormControlRenderProps, type XlsxFormControlSelectionMode, type XlsxFormControlState, type XlsxFormulaTarget, type XlsxImage, type XlsxImageAnchor, type XlsxImageRect, type XlsxImageRenderProps, type XlsxImageResizeHandlePosition, type XlsxImageSelectionRenderProps, type XlsxScrollerRenderProps, type XlsxShape, type XlsxShapeFill, type XlsxShapeParagraph, type XlsxShapeStroke, type XlsxShapeTextBox, type XlsxShapeTextRun, type XlsxSheetData, type XlsxSheetThumbnail, type XlsxSheetThumbnailResolution, type XlsxSheetVisibility, type XlsxTable, type XlsxTableColumn, type XlsxTableHeaderMenuRenderProps, type XlsxTableSortDirection, type XlsxTableSortState, type XlsxThemePalette, XlsxViewer, type XlsxViewerCharts, type XlsxViewerController, type XlsxViewerEditing, type XlsxViewerImages, type XlsxViewerProps, XlsxViewerProvider, type XlsxViewerProviderProps, type XlsxViewerSelection, type XlsxViewerTables, type XlsxViewerThumbnails, type XlsxViewerZoom, type XlsxWasmSource, type XlsxWorkbookTab, initWasm, setWasmSource, useXlsxViewer, useXlsxViewerCharts, useXlsxViewerController, useXlsxViewerEditing, useXlsxViewerImages, useXlsxViewerSelection, useXlsxViewerTables, useXlsxViewerThumbnails, useXlsxViewerZoom };
+export { DefaultXlsxToolbar, type UseXlsxViewerControllerOptions, type UseXlsxViewerThumbnailsOptions, type XlsxActiveCellOverlayRenderProps, type XlsxCellAddress, type XlsxCellAlignmentInput, type XlsxCellBorderEdgeInput, type XlsxCellBorderStyleInput, type XlsxCellFillStyleInput, type XlsxCellFontStyleInput, type XlsxCellGradientStopInput, type XlsxCellNumberFormatInput, type XlsxCellProtectionInput, type XlsxCellRange, type XlsxCellStyleColorInput, type XlsxCellStyleContext, type XlsxCellStyleInput, type XlsxChart, type XlsxChartAxis, type XlsxChartDataLabels, type XlsxChartElementSelection, type XlsxChartLoadingRenderProps, type XlsxChartReference, type XlsxChartSeries, type XlsxChartsheet, type XlsxDrawingLayout, XlsxFileSizeLimitExceededError, type XlsxFileTooLargeRenderProps, type XlsxFormControl, type XlsxFormControlActionEvent, type XlsxFormControlCaption, type XlsxFormControlCaptionInput, type XlsxFormControlCaptionRun, type XlsxFormControlChangeEvent, type XlsxFormControlInput, type XlsxFormControlKind, type XlsxFormControlKindInput, type XlsxFormControlPatch, type XlsxFormControlRenderProps, type XlsxFormControlSelectionMode, type XlsxFormControlState, type XlsxFormulaTarget, type XlsxHighlightRangeOptions, type XlsxImage, type XlsxImageAnchor, type XlsxImageRect, type XlsxImageRenderProps, type XlsxImageResizeHandlePosition, type XlsxImageSelectionRenderProps, type XlsxParsedRange, type XlsxRangeHighlight, type XlsxScrollerRenderProps, type XlsxShape, type XlsxShapeFill, type XlsxShapeParagraph, type XlsxShapeStroke, type XlsxShapeTextBox, type XlsxShapeTextRun, type XlsxSheetData, type XlsxSheetThumbnail, type XlsxSheetThumbnailResolution, type XlsxSheetVisibility, type XlsxTable, type XlsxTableColumn, type XlsxTableHeaderMenuRenderProps, type XlsxTableSortDirection, type XlsxTableSortState, type XlsxThemePalette, XlsxViewer, type XlsxViewerCharts, type XlsxViewerController, type XlsxViewerEditing, type XlsxViewerImages, type XlsxViewerProps, XlsxViewerProvider, type XlsxViewerProviderProps, type XlsxViewerSelection, type XlsxViewerTables, type XlsxViewerThumbnails, type XlsxViewerZoom, type XlsxWasmSource, type XlsxWorkbookTab, initWasm, parseXlsxRange, setWasmSource, useXlsxViewer, useXlsxViewerCharts, useXlsxViewerController, useXlsxViewerEditing, useXlsxViewerImages, useXlsxViewerSelection, useXlsxViewerTables, useXlsxViewerThumbnails, useXlsxViewerZoom };

package/dist/index.d.ts

@@ -117,6 +117,7 @@ interface XlsxSheetData {
     hasVerticalMerges: boolean;
     maxHorizontalMergeEndCol: number;
     maxVerticalMergeEndRow: number;
+    mergedRanges?: XlsxCellRange[];
     minUsedCol: number;
     minUsedRow: number;
     maxUsedCol: number;
@@ -146,6 +147,23 @@ interface XlsxCellRange {
     end: XlsxCellAddress;
     start: XlsxCellAddress;
 }
+interface XlsxParsedRange {
+    kind: "cells" | "rows" | "columns";
+    range: XlsxCellRange;
+    sheetName: string | null;
+}
+interface XlsxHighlightRangeOptions {
+    /** Navigates to the worksheet and reveals the first range. Defaults to true. */
+    autoScroll?: boolean;
+    /** Visible worksheet index for an unqualified reference. Defaults to the active worksheet. */
+    sheetIndex?: number;
+}
+interface XlsxRangeHighlight extends XlsxParsedRange {
+    /** Whether this entry is the navigation target for the current highlight update. */
+    autoScroll: boolean;
+    sheetName: string;
+    workbookSheetIndex: number;
+}
 /**
  * Color value accepted by persisted workbook style mutation APIs.
  *
@@ -1037,6 +1055,11 @@ interface XlsxViewerController {
     addFormControl: (input: XlsxFormControlInput, sheetIndex?: number) => number | null;
     clearSelectedCells: () => void;
     clearSelection: () => void;
+    /** Removes all render-only range highlights. */
+    clearHighlightedRanges: () => void;
+    /** Replaces the highlights with validated A1 ranges. Returns false without changing state if any reference cannot be resolved. */
+    highlightRanges: (references: string | readonly string[], options?: XlsxHighlightRangeOptions) => boolean;
+    highlightedRanges: XlsxRangeHighlight[];
     continueDeferredLoad: () => void;
     copySelectionToClipboard: () => Promise<boolean>;
     defaultZoomScale: number;
@@ -1397,6 +1420,15 @@ interface XlsxTableHeaderMenuRenderProps {
     /** Props that must be applied to your menu trigger button so grid selection does not receive the click. */
     triggerProps: React.ButtonHTMLAttributes<HTMLButtonElement>;
 }
+interface XlsxActiveCellOverlayRenderProps {
+    /** Address of the active cell. For merged cells this is the merge anchor. */
+    cell: XlsxCellAddress;
+    /**
+     * Pixel rect of the active cell (spanning the full merge) within the grid's scroll content,
+     * at the current zoom. The rendered node is already positioned to fill this rect.
+     */
+    rect: XlsxImageRect;
+}
 interface XlsxCellStyleContext {
     /** Address of the cell being styled. */
     cell: XlsxCellAddress;
@@ -1446,6 +1478,12 @@ interface XlsxViewerProviderProps extends UseXlsxViewerControllerOptions {
     isDark?: boolean;
 }
 interface XlsxViewerProps extends UseXlsxViewerControllerOptions {
+    /** Render-only A1 ranges to highlight. Null or an empty array clears them; undefined leaves controller state alone. */
+    highlightedRanges?: string | readonly string[] | null;
+    /** Reveals the first newly highlighted range, including switching worksheets. Defaults to true. */
+    autoScrollToHighlightedRanges?: boolean;
+    /** Additional CSS class applied to the range highlight in both renderers. */
+    highlightClassName?: string;
     /**
      * Allows row and column resizing even while editing is disabled by `readOnly`.
      *
@@ -1612,6 +1650,24 @@ interface XlsxViewerProps extends UseXlsxViewerControllerOptions {
      * Apply `triggerProps` to your actual trigger button so clicks do not leak into grid selection.
      */
     renderTableHeaderMenu?: (props: XlsxTableHeaderMenuRenderProps) => React.ReactNode;
+    /**
+     * Renders custom content positioned over the active cell. The returned node is placed in a
+     * container that exactly covers the cell, so it can carry classes, data attributes, or refs
+     * for measuring the cell with `getBoundingClientRect()`.
+     *
+     * The container ignores pointer events so grid interaction is unaffected; set
+     * `pointerEvents: "auto"` on your own elements to make them interactive.
+     *
+     * @example
+     * ```tsx
+     * <XlsxViewer
+     *   renderActiveCellOverlay={({ cell }) => (
+     *     <div data-active-cell={`${cell.row}:${cell.col}`} style={{ height: "100%", width: "100%" }} />
+     *   )}
+     * />
+     * ```
+     */
+    renderActiveCellOverlay?: (props: XlsxActiveCellOverlayRenderProps) => React.ReactNode;
     /**
      * Shows worksheet images, charts, shapes, and form controls.
      *
@@ -1642,6 +1698,9 @@ declare class XlsxFileSizeLimitExceededError extends Error {
 }
 declare function useXlsxViewerController(options: UseXlsxViewerControllerOptions): XlsxViewerController;
 
+/** Parses one rectangular A1 reference into normalized, zero-based coordinates. */
+declare function parseXlsxRange(reference: string): XlsxParsedRange | null;
+
 type XlsxWasmSource = string | URL | Request | Response | BufferSource | WebAssembly.Module;
 declare function setWasmSource(source: XlsxWasmSource): void;
 declare function initWasm(source?: XlsxWasmSource): Promise<typeof _dukelib_sheets_wasm>;
@@ -1658,4 +1717,4 @@ declare function useXlsxViewerThumbnails(options?: UseXlsxViewerThumbnailsOption
 declare function XlsxViewer(props: XlsxViewerProps): react_jsx_runtime.JSX.Element;
 declare function DefaultXlsxToolbar(): react_jsx_runtime.JSX.Element;
 
-export { DefaultXlsxToolbar, type UseXlsxViewerControllerOptions, type UseXlsxViewerThumbnailsOptions, type XlsxCellAddress, type XlsxCellAlignmentInput, type XlsxCellBorderEdgeInput, type XlsxCellBorderStyleInput, type XlsxCellFillStyleInput, type XlsxCellFontStyleInput, type XlsxCellGradientStopInput, type XlsxCellNumberFormatInput, type XlsxCellProtectionInput, type XlsxCellRange, type XlsxCellStyleColorInput, type XlsxCellStyleContext, type XlsxCellStyleInput, type XlsxChart, type XlsxChartAxis, type XlsxChartDataLabels, type XlsxChartElementSelection, type XlsxChartLoadingRenderProps, type XlsxChartReference, type XlsxChartSeries, type XlsxChartsheet, type XlsxDrawingLayout, XlsxFileSizeLimitExceededError, type XlsxFileTooLargeRenderProps, type XlsxFormControl, type XlsxFormControlActionEvent, type XlsxFormControlCaption, type XlsxFormControlCaptionInput, type XlsxFormControlCaptionRun, type XlsxFormControlChangeEvent, type XlsxFormControlInput, type XlsxFormControlKind, type XlsxFormControlKindInput, type XlsxFormControlPatch, type XlsxFormControlRenderProps, type XlsxFormControlSelectionMode, type XlsxFormControlState, type XlsxFormulaTarget, type XlsxImage, type XlsxImageAnchor, type XlsxImageRect, type XlsxImageRenderProps, type XlsxImageResizeHandlePosition, type XlsxImageSelectionRenderProps, type XlsxScrollerRenderProps, type XlsxShape, type XlsxShapeFill, type XlsxShapeParagraph, type XlsxShapeStroke, type XlsxShapeTextBox, type XlsxShapeTextRun, type XlsxSheetData, type XlsxSheetThumbnail, type XlsxSheetThumbnailResolution, type XlsxSheetVisibility, type XlsxTable, type XlsxTableColumn, type XlsxTableHeaderMenuRenderProps, type XlsxTableSortDirection, type XlsxTableSortState, type XlsxThemePalette, XlsxViewer, type XlsxViewerCharts, type XlsxViewerController, type XlsxViewerEditing, type XlsxViewerImages, type XlsxViewerProps, XlsxViewerProvider, type XlsxViewerProviderProps, type XlsxViewerSelection, type XlsxViewerTables, type XlsxViewerThumbnails, type XlsxViewerZoom, type XlsxWasmSource, type XlsxWorkbookTab, initWasm, setWasmSource, useXlsxViewer, useXlsxViewerCharts, useXlsxViewerController, useXlsxViewerEditing, useXlsxViewerImages, useXlsxViewerSelection, useXlsxViewerTables, useXlsxViewerThumbnails, useXlsxViewerZoom };
+export { DefaultXlsxToolbar, type UseXlsxViewerControllerOptions, type UseXlsxViewerThumbnailsOptions, type XlsxActiveCellOverlayRenderProps, type XlsxCellAddress, type XlsxCellAlignmentInput, type XlsxCellBorderEdgeInput, type XlsxCellBorderStyleInput, type XlsxCellFillStyleInput, type XlsxCellFontStyleInput, type XlsxCellGradientStopInput, type XlsxCellNumberFormatInput, type XlsxCellProtectionInput, type XlsxCellRange, type XlsxCellStyleColorInput, type XlsxCellStyleContext, type XlsxCellStyleInput, type XlsxChart, type XlsxChartAxis, type XlsxChartDataLabels, type XlsxChartElementSelection, type XlsxChartLoadingRenderProps, type XlsxChartReference, type XlsxChartSeries, type XlsxChartsheet, type XlsxDrawingLayout, XlsxFileSizeLimitExceededError, type XlsxFileTooLargeRenderProps, type XlsxFormControl, type XlsxFormControlActionEvent, type XlsxFormControlCaption, type XlsxFormControlCaptionInput, type XlsxFormControlCaptionRun, type XlsxFormControlChangeEvent, type XlsxFormControlInput, type XlsxFormControlKind, type XlsxFormControlKindInput, type XlsxFormControlPatch, type XlsxFormControlRenderProps, type XlsxFormControlSelectionMode, type XlsxFormControlState, type XlsxFormulaTarget, type XlsxHighlightRangeOptions, type XlsxImage, type XlsxImageAnchor, type XlsxImageRect, type XlsxImageRenderProps, type XlsxImageResizeHandlePosition, type XlsxImageSelectionRenderProps, type XlsxParsedRange, type XlsxRangeHighlight, type XlsxScrollerRenderProps, type XlsxShape, type XlsxShapeFill, type XlsxShapeParagraph, type XlsxShapeStroke, type XlsxShapeTextBox, type XlsxShapeTextRun, type XlsxSheetData, type XlsxSheetThumbnail, type XlsxSheetThumbnailResolution, type XlsxSheetVisibility, type XlsxTable, type XlsxTableColumn, type XlsxTableHeaderMenuRenderProps, type XlsxTableSortDirection, type XlsxTableSortState, type XlsxThemePalette, XlsxViewer, type XlsxViewerCharts, type XlsxViewerController, type XlsxViewerEditing, type XlsxViewerImages, type XlsxViewerProps, XlsxViewerProvider, type XlsxViewerProviderProps, type XlsxViewerSelection, type XlsxViewerTables, type XlsxViewerThumbnails, type XlsxViewerZoom, type XlsxWasmSource, type XlsxWorkbookTab, initWasm, parseXlsxRange, setWasmSource, useXlsxViewer, useXlsxViewerCharts, useXlsxViewerController, useXlsxViewerEditing, useXlsxViewerImages, useXlsxViewerSelection, useXlsxViewerTables, useXlsxViewerThumbnails, useXlsxViewerZoom };