@extend-ai/react-xlsx 0.10.4 → 0.11.0

package/dist/index.d.cts

@@ -889,6 +889,34 @@ 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 XlsxCellStyleContext {
+    /** Address of the cell being styled. */
+    cell: XlsxCellAddress;
+    /** True when the cell is part of a selected chart's highlighted source range. */
+    hasChartHighlight: boolean;
+    /** True when a conditional format (color scale, data bar, or icon set) applies to the cell. */
+    hasConditionalFormat: boolean;
+    /** True when the cell has a hyperlink. */
+    hasHyperlink: boolean;
+    /** True when the cell has a data validation rule. */
+    hasValidation: boolean;
+    /** True when the cell is the anchor of a merged range. */
+    isMerged: boolean;
+    /** True when the cell is a table header cell. */
+    isTableHeader: boolean;
+    /**
+     * The fully resolved style the viewer computed for this cell, combining the workbook's
+     * own formatting with the viewer's built-in styling. Treat this as read-only; returning
+     * a partial style from `getCellStyle` merges on top of it.
+     */
+    resolvedStyle: React.CSSProperties;
+    /** Display name of the sheet the cell belongs to. */
+    sheetName: string;
+    /** The cell's resolved display value. */
+    value: string;
+    /** Workbook sheet index of the cell's sheet. */
+    workbookSheetIndex: number;
+}
 interface XlsxViewerProviderProps extends UseXlsxViewerControllerOptions {
     /** Viewer UI and hooks that should share this provider's workbook controller. */
     children: React.ReactNode;
@@ -956,6 +984,33 @@ interface XlsxViewerProps extends UseXlsxViewerControllerOptions {
     errorState?: React.ReactNode | ((error: Error) => React.ReactNode);
     /** Content shown when `maxFileSizeBytes` rejects a file. */
     fileTooLargeState?: React.ReactNode | ((props: XlsxFileTooLargeRenderProps) => React.ReactNode);
+    /**
+     * Returns extra CSS style overrides for an individual cell. Called for every rendered cell
+     * with the cell's address, sheet, resolved style, and contextual flags. Return `undefined`
+     * (or `null`) to leave a cell untouched, or a partial style object that merges on top of the
+     * viewer's resolved style. Use this as an escape hatch for custom per-cell styling such as
+     * highlights, outlines, or status tints, without forking the workbook data.
+     *
+     * The DOM renderer applies every returned CSS property. The canvas renderer
+     * (`experimentalCanvas`, the default) honors the subset it can paint: `backgroundColor`,
+     * `backgroundImage` gradients, `color`, the four `border*` sides, `padding`, `textAlign`,
+     * `textDecoration`, `textOverflow`, and font properties. CSS-only effects such as `boxShadow`,
+     * `outline`, or `animation` apply in the DOM renderer (`experimentalCanvas={false}`).
+     *
+     * Keep this callback stable (e.g. wrap it in `useCallback`) so cell styling is not recomputed
+     * on every render. When the callback identity changes, the viewer re-resolves and repaints
+     * cell styles.
+     *
+     * @example
+     * ```tsx
+     * const getCellStyle = React.useCallback<NonNullable<XlsxViewerProps["getCellStyle"]>>(
+     *   ({ cell }) => (cell.row === 3 && cell.col === 1 ? { backgroundColor: "#dbeafe" } : undefined),
+     *   []
+     * );
+     * return <XlsxViewer file={buffer} getCellStyle={getCellStyle} />;
+     * ```
+     */
+    getCellStyle?: (context: XlsxCellStyleContext) => React.CSSProperties | null | undefined;
     /**
      * CSS height for the viewer container.
      *
@@ -1081,4 +1136,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 XlsxCellRange, type XlsxChart, type XlsxChartAxis, type XlsxChartDataLabels, type XlsxChartLoadingRenderProps, type XlsxChartReference, type XlsxChartSeries, type XlsxChartsheet, XlsxFileSizeLimitExceededError, type XlsxFileTooLargeRenderProps, 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 XlsxCellAddress, type XlsxCellRange, type XlsxCellStyleContext, type XlsxChart, type XlsxChartAxis, type XlsxChartDataLabels, type XlsxChartLoadingRenderProps, type XlsxChartReference, type XlsxChartSeries, type XlsxChartsheet, XlsxFileSizeLimitExceededError, type XlsxFileTooLargeRenderProps, 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 };

package/dist/index.d.ts

@@ -889,6 +889,34 @@ 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 XlsxCellStyleContext {
+    /** Address of the cell being styled. */
+    cell: XlsxCellAddress;
+    /** True when the cell is part of a selected chart's highlighted source range. */
+    hasChartHighlight: boolean;
+    /** True when a conditional format (color scale, data bar, or icon set) applies to the cell. */
+    hasConditionalFormat: boolean;
+    /** True when the cell has a hyperlink. */
+    hasHyperlink: boolean;
+    /** True when the cell has a data validation rule. */
+    hasValidation: boolean;
+    /** True when the cell is the anchor of a merged range. */
+    isMerged: boolean;
+    /** True when the cell is a table header cell. */
+    isTableHeader: boolean;
+    /**
+     * The fully resolved style the viewer computed for this cell, combining the workbook's
+     * own formatting with the viewer's built-in styling. Treat this as read-only; returning
+     * a partial style from `getCellStyle` merges on top of it.
+     */
+    resolvedStyle: React.CSSProperties;
+    /** Display name of the sheet the cell belongs to. */
+    sheetName: string;
+    /** The cell's resolved display value. */
+    value: string;
+    /** Workbook sheet index of the cell's sheet. */
+    workbookSheetIndex: number;
+}
 interface XlsxViewerProviderProps extends UseXlsxViewerControllerOptions {
     /** Viewer UI and hooks that should share this provider's workbook controller. */
     children: React.ReactNode;
@@ -956,6 +984,33 @@ interface XlsxViewerProps extends UseXlsxViewerControllerOptions {
     errorState?: React.ReactNode | ((error: Error) => React.ReactNode);
     /** Content shown when `maxFileSizeBytes` rejects a file. */
     fileTooLargeState?: React.ReactNode | ((props: XlsxFileTooLargeRenderProps) => React.ReactNode);
+    /**
+     * Returns extra CSS style overrides for an individual cell. Called for every rendered cell
+     * with the cell's address, sheet, resolved style, and contextual flags. Return `undefined`
+     * (or `null`) to leave a cell untouched, or a partial style object that merges on top of the
+     * viewer's resolved style. Use this as an escape hatch for custom per-cell styling such as
+     * highlights, outlines, or status tints, without forking the workbook data.
+     *
+     * The DOM renderer applies every returned CSS property. The canvas renderer
+     * (`experimentalCanvas`, the default) honors the subset it can paint: `backgroundColor`,
+     * `backgroundImage` gradients, `color`, the four `border*` sides, `padding`, `textAlign`,
+     * `textDecoration`, `textOverflow`, and font properties. CSS-only effects such as `boxShadow`,
+     * `outline`, or `animation` apply in the DOM renderer (`experimentalCanvas={false}`).
+     *
+     * Keep this callback stable (e.g. wrap it in `useCallback`) so cell styling is not recomputed
+     * on every render. When the callback identity changes, the viewer re-resolves and repaints
+     * cell styles.
+     *
+     * @example
+     * ```tsx
+     * const getCellStyle = React.useCallback<NonNullable<XlsxViewerProps["getCellStyle"]>>(
+     *   ({ cell }) => (cell.row === 3 && cell.col === 1 ? { backgroundColor: "#dbeafe" } : undefined),
+     *   []
+     * );
+     * return <XlsxViewer file={buffer} getCellStyle={getCellStyle} />;
+     * ```
+     */
+    getCellStyle?: (context: XlsxCellStyleContext) => React.CSSProperties | null | undefined;
     /**
      * CSS height for the viewer container.
      *
@@ -1081,4 +1136,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 XlsxCellRange, type XlsxChart, type XlsxChartAxis, type XlsxChartDataLabels, type XlsxChartLoadingRenderProps, type XlsxChartReference, type XlsxChartSeries, type XlsxChartsheet, XlsxFileSizeLimitExceededError, type XlsxFileTooLargeRenderProps, 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 XlsxCellAddress, type XlsxCellRange, type XlsxCellStyleContext, type XlsxChart, type XlsxChartAxis, type XlsxChartDataLabels, type XlsxChartLoadingRenderProps, type XlsxChartReference, type XlsxChartSeries, type XlsxChartsheet, XlsxFileSizeLimitExceededError, type XlsxFileTooLargeRenderProps, 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 };

package/dist/index.js

@@ -21511,6 +21511,7 @@ function XlsxGrid({
   enableCanvasSelectionAnimation = true,
   errorState,
   fileTooLargeState,
+  getCellStyle,
   loadingComponent,
   loadingState,
   renderChartLoading,
@@ -23470,7 +23471,7 @@ function XlsxGrid({
   const viewportRowBatch = getRowsBatchAsync ? asyncViewportRowBatch : syncViewportRowBatch;
   React4.useEffect(() => {
     cellRenderCacheRef.current.clear();
-  }, [activeSheetIndex, displayColLimit, displayRowLimit, palette, revision, viewportRowBatch, worksheet, zoomFactor]);
+  }, [activeSheetIndex, displayColLimit, displayRowLimit, getCellStyle, palette, revision, viewportRowBatch, worksheet, zoomFactor]);
   React4.useEffect(() => {
     setAsyncViewportRowBatch(null);
   }, [activeSheetIndex, revision]);
@@ -23595,6 +23596,29 @@ function XlsxGrid({
       validation: resolveCellDataValidation(row, col, activeSheet),
       value: sparkline ? "" : checkboxState !== null ? "" : batchCoversRow || !worksheet ? batchedCell?.value ?? "" : getCellDisplayValue(worksheet, row, col, activeSheet)
     };
+    if (getCellStyle) {
+      const styleOverrides = getCellStyle({
+        cell: { row, col },
+        hasChartHighlight: Boolean(nextData.chartHighlight),
+        hasConditionalFormat: Boolean(
+          nextData.conditionalColorScale || nextData.conditionalDataBar || nextData.conditionalIcon
+        ),
+        hasHyperlink: Boolean(nextData.hyperlink),
+        hasValidation: Boolean(nextData.validation),
+        isMerged: Boolean(nextData.colSpan || nextData.rowSpan),
+        isTableHeader: Boolean(nextData.isTableHeader),
+        resolvedStyle: { ...nextData.style },
+        sheetName: activeSheet?.name ?? "",
+        value: nextData.value,
+        workbookSheetIndex: activeSheet?.workbookSheetIndex ?? -1
+      });
+      if (styleOverrides) {
+        nextData.style = { ...nextData.style, ...styleOverrides };
+        if (nextData.conditionalColorScale && (styleOverrides.backgroundColor !== void 0 || styleOverrides.background !== void 0)) {
+          nextData.conditionalColorScale = null;
+        }
+      }
+    }
     nextData.canvas = buildCanvasCellStyleCache(nextData.style);
     if (canCellTextOverflow(nextData)) {
       const startColIndex = colIndexByActual.get(col);
@@ -23680,6 +23704,7 @@ function XlsxGrid({
     displayDefaultColWidth,
     displayEffectiveColWidths,
     effectiveTables,
+    getCellStyle,
     palette,
     sparklinesByCell,
     viewportRowBatch,
@@ -28715,6 +28740,7 @@ function XlsxViewerInner({
   errorState,
   experimentalCanvas = true,
   fileTooLargeState,
+  getCellStyle,
   height,
   isDark = false,
   loadingComponent,
@@ -28778,6 +28804,7 @@ function XlsxViewerInner({
             errorState,
             experimentalCanvas,
             fileTooLargeState,
+            getCellStyle,
             loadingComponent,
             loadingState,
             palette,