@extend-ai/react-xlsx 0.10.4 → 0.12.0

package/README.md

@@ -225,7 +225,7 @@ These hooks work inside `XlsxViewer` or `XlsxViewerProvider` context.
 - `useXlsxViewer()` for full controller access
 - `useXlsxViewerSelection()` for active cell and range state
 - `useXlsxViewerZoom()` for zoom controls and limits
-- `useXlsxViewerEditing()` for editing, undo/redo, fill, merge, clipboard, and export actions
+- `useXlsxViewerEditing()` for editing, persisted style writes, undo/redo, fill, merge, clipboard, and export actions
 - `useXlsxViewerTables()` for table metadata and table sorting
 - `useXlsxViewerImages()` for embedded image and chart selection, movement, and resizing
 - `useXlsxViewerCharts()` for chart and chartsheet state
@@ -407,12 +407,108 @@ Common rendering props:
 - `loadingState?: React.ReactNode`
 - `errorState?: React.ReactNode | ((error: Error) => React.ReactNode)`
 - `fileTooLargeState?: React.ReactNode | ((props: XlsxFileTooLargeRenderProps) => React.ReactNode)`
+- `getCellStyle?: (context: XlsxCellStyleContext) => React.CSSProperties | null | undefined`
 - `renderImage?: (props: XlsxImageRenderProps) => React.ReactNode`
 - `renderImageSelection?: (props: XlsxImageSelectionRenderProps) => React.ReactNode`
 - `renderChartLoading?: (props: XlsxChartLoadingRenderProps) => React.ReactNode`
 - `renderTableHeaderMenu?: (props: XlsxTableHeaderMenuRenderProps) => React.ReactNode`
 - `renderScroller?: (props: XlsxScrollerRenderProps) => React.ReactNode`
 
+### Persisted Cell Styling
+
+Use `setCellStyle`, `setSelectedCellStyle`, and `setRangeStyle` when a custom toolbar should write Excel formatting into the workbook. These APIs mutate workbook data, participate in undo/redo, refresh the viewer, and are included in `exportXlsx()`.
+
+```tsx
+import {
+  useXlsxViewer,
+  type XlsxCellStyleInput
+} from "@extend-ai/react-xlsx";
+
+const highlightStyle: XlsxCellStyleInput = {
+  font: { bold: true, color: { colorType: "rgb", hex: "1D4ED8" } },
+  fill: { fillType: "solid", color: { colorType: "rgb", hex: "DBEAFE" } },
+  alignment: { horizontal: "center", vertical: "center", wrapText: true }
+};
+
+function FormattingButton() {
+  const { selection, setRangeStyle, setSelectedCellStyle } = useXlsxViewer();
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (selection) {
+          setRangeStyle(selection, highlightStyle);
+          return;
+        }
+        setSelectedCellStyle(highlightStyle);
+      }}
+    >
+      Highlight
+    </button>
+  );
+}
+```
+
+`XlsxCellStyleInput` supports these persisted Excel style groups:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `font` | `XlsxCellFontStyleInput` | Font family, size, bold, italic, underline, strikethrough, color, superscript/subscript. |
+| `fill` | `XlsxCellFillStyleInput` | Solid, pattern, and gradient fills. |
+| `border` | `XlsxCellBorderStyleInput` | Per-edge borders, colors, styles, and diagonal borders. |
+| `alignment` | `XlsxCellAlignmentInput` | Horizontal/vertical alignment, wrap text, shrink to fit, indent, rotation, reading order. |
+| `numberFormat` | `XlsxCellNumberFormatInput` | General, builtin, or custom Excel number format strings. |
+| `protection` | `XlsxCellProtectionInput` | Locked/hidden flags used when sheet protection is enabled. |
+
+### Render-Only Cell Styling
+
+`getCellStyle` is an escape hatch for styling individual cells without forking the workbook data. It is called for every rendered cell and returns a partial `React.CSSProperties` that merges on top of the viewer's resolved style. Return `undefined` (or `null`) to leave a cell untouched.
+
+```tsx
+import { XlsxViewer, type XlsxViewerProps } from "@extend-ai/react-xlsx";
+
+function Workbook({ buffer, highlighted }: { buffer: ArrayBuffer; highlighted: Set<string> }) {
+  const getCellStyle = React.useCallback<NonNullable<XlsxViewerProps["getCellStyle"]>>(
+    ({ cell, isTableHeader }) => {
+      if (isTableHeader) {
+        return undefined;
+      }
+      if (highlighted.has(`${cell.row}:${cell.col}`)) {
+        return { backgroundColor: "rgba(37, 99, 235, 0.12)", outline: "1px solid #2563eb" };
+      }
+      return undefined;
+    },
+    [highlighted]
+  );
+
+  return <XlsxViewer file={buffer} getCellStyle={getCellStyle} />;
+}
+```
+
+The `context` passed to `getCellStyle` is an `XlsxCellStyleContext`:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `cell` | `XlsxCellAddress` | Address of the cell being styled. |
+| `workbookSheetIndex` | `number` | Workbook sheet index of the cell's sheet. |
+| `sheetName` | `string` | Display name of the cell's sheet. |
+| `resolvedStyle` | `React.CSSProperties` | The style the viewer computed (workbook formatting + built-ins). Read-only. |
+| `value` | `string` | The cell's resolved display value. |
+| `hasValidation` | `boolean` | Cell has a data validation rule. |
+| `hasHyperlink` | `boolean` | Cell has a hyperlink. |
+| `hasConditionalFormat` | `boolean` | Cell is affected by a color scale, data bar, or icon set. |
+| `hasChartHighlight` | `boolean` | Cell is in a selected chart's highlighted source range. |
+| `isMerged` | `boolean` | Cell is the anchor of a merged range. |
+| `isTableHeader` | `boolean` | Cell is a table header cell. |
+
+Notes:
+
+- Keep the callback stable (e.g. `useCallback`) so cell styling is not recomputed every render. When the callback identity changes, the viewer re-resolves and repaints cells.
+- The DOM renderer (`experimentalCanvas={false}`) applies every returned CSS property.
+- The canvas renderer (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.
+- `getCellStyle` is not applied to worksheet thumbnails painted via `useXlsxViewerThumbnails(...)`.
+
 ### Custom Scroll Area
 
 By default, the viewer renders its native scroll viewport with the browser scrollbar. To use a custom scroll area, provide `renderScroller` and spread `viewportProps` onto the actual scrollable viewport element:
@@ -478,6 +574,8 @@ The package exports the main types you are likely to use for custom integrations
 - `XlsxViewerCharts`
 - `XlsxViewerThumbnails`
 - `XlsxScrollerRenderProps`
+- `XlsxCellStyleContext`
+- `XlsxCellStyleInput`, `XlsxCellFontStyleInput`, `XlsxCellFillStyleInput`, `XlsxCellBorderStyleInput`
 - `XlsxSheetThumbnail`
 - `UseXlsxViewerThumbnailsOptions`
 - `XlsxChart`, `XlsxChartSeries`, `XlsxChartAxis`, `XlsxChartsheet`