setRanges(r)}\n height={600}\n />\n {box && (\n \n {ranges.length} range(s) selected\n
\n )}\n \n );\n}\n```\n\nThe grid is virtualized, so the highlighted **cells** are not all in the DOM — most of a large range has no cell node at all. This element is a single invisible box covering the highlight's bounding rectangle instead, positioned in grid content coordinates. Behavior:\n\n- **One element, always.** For a multi-range highlight like `\"A1:B2, D1:E3\"` you get a single element spanning the union (`A1:E3`) — which also covers column `C`, since it is one rectangle.\n- **`null` when there is no highlight.** The element unmounts, so an object ref's `.current` becomes `null` and a callback ref is called with `null`.\n- Populated for **any** selection: `setHighlight()`, the `highlight` prop, drag-selection, and a plain single-cell click (even though a single click draws no tint).\n- Still provided when `highlightable={false}` — that prop suppresses *visuals*, and this element has none.\n- Stays pinned to the content while scrolling, and repositions when columns or rows are resized.\n- Invisible and `pointer-events: none`. You can style it via the `.sv-highlight-area` class if you want your own outline.\n\n> **Do not read the ref inside `onSelectionChange`.** That callback fires synchronously while the store updates, *before* React commits, so the element is not yet positioned (or may not exist). Store the ranges in state as above and read the rect in a `useEffect` / `useLayoutEffect`. If you call `setHighlight()` from outside a React event handler on React 17, updates are unbatched — wrap it in `unstable_batchedUpdates` or read the rect in a `requestAnimationFrame`.\n\n`ref.current?.getHighlightElement()` returns the same element if you already hold a `SheetViewerHandle` and would rather not pass a second ref.\n\n### Attributes on the highlight area\n\n`highlightAreaProps` puts arbitrary HTML attributes on that same element — an `id` for a popover library to resolve as its anchor, a test id, ARIA wiring, or your own styling:\n\n```tsx\n console.log('highlight clicked'),\n }}\n/>\n```\n\nTwo merge rules keep the element working:\n\n- **`className` is appended** to `sv-highlight-area`, never replaces it — the class carries the CSS and is what `getHighlightElement()` queries.\n- **The measured geometry wins** over `style`. `top`/`left`/`width`/`height` are always the computed box; everything else in `style` is applied as given.\n\n`aria-hidden=\"true\"` is the default and can be overridden. The element is `pointer-events: none` by default — set `pointerEvents: 'auto'` if you want it clickable (note that this makes it swallow drag-selection over the highlighted cells).\n\n### Scrolling the selection into view\n\n`ref.current?.scrollToSelection()` scrolls so the **entire** selection is visible:\n\n```tsx\nviewerRef.current?.setHighlight('C400:F420');\nviewerRef.current?.scrollToSelection();\n```\n\n- Spans the **union** of every selected range, so multi-range highlights like `A1:B5,D1:E5` are fully revealed.\n- Moves the **minimum** amount needed on each axis — a selection already fully in view does not move, and an axis that is already visible is left alone.\n- A selection larger than the viewport is aligned to its top-left corner.\n- Returns `false` when there is no selection.\n\nThis is separate from the automatic scroll that already runs when the selection changes; calling it does not alter that behavior.\n\n---\n\n## Edit Mode\n\nEnable inline cell editing:\n\n```tsx\n {\n console.log(`${sheet}[${row},${col}] = ${value}`);\n }}\n/>\n```\n\nDouble-click a cell to start editing. Press Enter to confirm or Escape to cancel.\n\n---\n\n## Copy & Paste with Formatting\n\n- **Ctrl+C** (Cmd+C on Mac) — copies the selected range as HTML (with inline styles) and TSV\n- **Ctrl+V** (Cmd+V on Mac) — pastes HTML (preferred, preserves styles) or plain TSV\n- **Escape** — clears the marching ants copy indicator\n\nPaste requires `mode=\"edit\"`.\n\n---\n\n## Large Cell Content\n\nWhen a cell contains long text, inactive cells truncate with ellipsis. The formula bar always shows the complete value, and highlighted range anchor cells can expand to show full content.\n\n---\n\n## Undo & Redo\n\n- **Ctrl+Z** (Cmd+Z) — undo\n- **Ctrl+Y** or **Ctrl+Shift+Z** — redo\n\nAlso available via ref:\n\n```tsx\nif (ref.current?.canUndo()) ref.current.undo();\nif (ref.current?.canRedo()) ref.current.redo();\n```\n\n---\n\n## Keyboard interactions\n\nBy default the viewer listens on the document for the shortcuts and navigation keys\nlisted above. `keyboardInteractions` turns that off — useful when the viewer is\nembedded in a page or modal that owns those keys itself.\n\n```tsx\n// Nothing the viewer handles at the document level fires\n\n```\n\nPass an object to disable individual groups and leave the rest working:\n\n```tsx\n// Arrows and Enter still move the active cell; the app keeps Ctrl+F and Ctrl+Z\n\n```\n\n| Group | Default | Keys |\n| --- | --- | --- |\n| `navigation` | `true` | Arrow keys, Tab / Shift+Tab, Enter, Home, End — plus everything the browser would do by itself, see below |\n| `editing` | `true` | Enter and F2 to open the cell editor (edit mode only) |\n| `clipboard` | `true` | Ctrl/Cmd+C, Ctrl/Cmd+V, Escape to clear the copy marquee |\n| `history` | `true` | Ctrl/Cmd+Z, Ctrl/Cmd+Y, Ctrl/Cmd+Shift+Z |\n| `search` | `true` | Ctrl/Cmd+F to open search, Escape to close it |\n\nTurning `navigation` off also takes away the two keyboard moves the viewer does\nnot handle itself, so the grid really is inert under the keyboard:\n\n- **The browser's own scrolling.** With focus inside the viewer, arrow keys, Page\n keys, Home/End and Space scroll the grid as a default action, with no handler of\n the viewer's involved. Those keys are swallowed. Key presses aimed at the page\n outside the viewer are left alone — scrolling the host document stays the host\n page's business.\n- **The tab order.** The viewer's buttons and inputs are given `tabindex=\"-1\"`, so\n Tab walks straight past the whole viewer instead of stepping through the toolbar,\n sheet tabs, zoom picker and range box. Nothing is trapped: Tab from inside moves\n on to the next control after the viewer, and mouse clicks still focus and operate\n every control as before.\n\nNotes:\n\n- Typing inside the viewer's own inputs is never affected. Once the cell editor,\n the range box, or the search box has focus, text entry works normally — arrow keys\n move the caret, and Enter commits an edit — because the editor is opened by mouse\n and would otherwise have no way to finish. This prop governs shortcuts, focus and\n grid navigation, not text entry.\n- `tabNavigation` applies on top of `navigation`: Tab moves between cells, and\n commits from the cell editor, only when both are enabled.\n- With `search: false` there is no way left to open the search bar, since Ctrl+F is\n its only trigger. Mouse-driven behavior — click, drag-select, double-click to\n edit, column resize, Ctrl+scroll zoom — is untouched either way.\n\n---\n\n## Zoom\n\nA Google Sheets-style zoom picker sits at the start of the formula bar row. Users can also hold Ctrl/Cmd and scroll over the grid. Because it lives in the formula bar rather than the toolbar, `showToolbar={false}` does not hide it.\n\nZoom scales the grid's real geometry — column widths, row heights, headers and type — rather than CSS-transforming it, so selection, scrolling, overlays and hit testing stay exact at every level.\n\n```tsx\n console.log(`${zoom * 100}%`)}\n/>\n```\n\nProgrammatic control:\n\n```tsx\nref.current?.zoomIn();\nref.current?.zoomOut();\nref.current?.setZoom(1.5);\nref.current?.resetZoom();\nref.current?.getZoom(); // 1\n```\n\n`zoomIn`/`zoomOut` walk the `zoomLevels` ladder and stop at its ends — at 200% (the top level) `zoomIn` is a no-op rather than jumping to `maxZoom`. `minZoom`/`maxZoom` are the limits for `setZoom`, not extra rungs, so stepping never lands on a level the picker does not offer.\n\nHide the control entirely with `zoomable={false}` — the `zoom` prop and ref API still work.\n\n---\n\n## Column & Row Resizing\n\nDrag the right edge of column headers or the bottom edge of row headers to resize. Minimum column: 30px, minimum row: 20px.\n\n**Excel column widths are preserved.** Columns explicitly sized in the source workbook render at that width; columns the author never touched fall back to the viewer's default of 100px.\n\n**Auto-fit:** double-click a column header's right edge to size that column to its widest content, the same gesture as Excel and Google Sheets. Results are clamped to 30–500px so one long cell cannot push everything else off-screen, and very tall sheets are fitted from their leading rows to keep the gesture instant.\n\nProgrammatic control:\n\n```tsx\nref.current?.setColumnWidth(0, 200); // Column A → 200px\nref.current?.setRowHeight(0, 50); // Row 1 → 50px\nref.current?.autoFitColumn(0); // Column A → fits its content\n```\n\n---\n\n## Tools\n\nThe formula bar row hosts a Tools section that renders whatever you register through the `tools` prop, alongside the zoom control. The viewer never knows what a tool does, so new functionality is added from the outside — no changes to the component itself. Tools stay visible when `showToolbar={false}`.\n\nUse `toolsPlacement` to put them at either end of the row, and `zoomPlacement` for the zoom control — the two are independent, so they can sit at opposite ends. An individual tool can opt out with its own `placement`:\n\n```tsx\n\n```\n\nA tool with no configuration is a plain object:\n\n```tsx\nimport { SheetViewer } from 'rc-sheet-viewer-17';\nimport type { SheetViewerTool } from 'rc-sheet-viewer-17';\n\nconst copyStats: SheetViewerTool = {\n id: 'copy-stats',\n label: 'Copy stats',\n icon: StatsIcon, // component, or a ready-made element\n isDisabled: (ctx) => ctx.selection.length === 0,\n onClick: (ctx) => {\n const rows = ctx.viewer.getSelectedRangeData();\n navigator.clipboard.writeText(JSON.stringify(rows));\n },\n};\n\n\n```\n\nTools that carry their own settings use `defineSheetViewerTool`, which infers the config type and type-checks every callback against it before binding it in:\n\n```tsx\nimport { defineSheetViewerTool } from 'rc-sheet-viewer-17';\n\nconst exportTool = defineSheetViewerTool({\n id: 'export-selection',\n label: 'Export selection',\n icon: DownloadIcon,\n config: { format: 'csv' as const, endpoint: '/api/export' },\n onClick: (ctx, config) => {\n // config is fully typed here — a typo is a compile error\n fetch(config.endpoint, {\n method: 'POST',\n body: JSON.stringify({ format: config.format, rows: ctx.viewer.getSelectedRangeData() }),\n });\n },\n});\n```\n\nThat binding is what keeps `tools` a single concrete `SheetViewerTool[]` — no `any`, no union to widen — while each tool's own options stay checked where the tool is written.\n\n### Tool fields\n\n| Field | Type | Description |\n|---|---|---|\n| `id` | `string` | Stable identifier, unique within the array |\n| `label` | `string` | Tooltip and accessible name |\n| `icon` | `ComponentType<{ size: number }> \\| ReactElement` | Icon component (rendered at 16px) or a ready-made element |\n| `onClick` | `(ctx: SheetViewerToolClickContext) => void` | Runs when the user activates the tool |\n| `showLabel` | `boolean` | Render the label beside the icon. Default: `false` |\n| `placement` | `'left' \\| 'right'` | Pin this tool to one end, overriding the viewer's `toolsPlacement` |\n| `isDisabled` | `(ctx: SheetViewerToolContext) => boolean` | Grey the tool out; re-evaluated as viewer state changes |\n| `isActive` | `(ctx: SheetViewerToolContext) => boolean` | Render the tool pressed |\n\n`defineSheetViewerTool` takes the same fields plus `config`, and passes it as a second argument to `onClick`, `isDisabled` and `isActive`.\n\n### Tool context\n\nEvery callback receives a snapshot of the viewer:\n\n| Field | Type | Description |\n|---|---|---|\n| `viewer` | `SheetViewerHandle` | The same imperative API the `ref` exposes |\n| `fileName` | `string \\| null` | Loaded file name |\n| `sheetNames` | `string[]` | Every sheet in the workbook |\n| `activeSheet` | `string \\| null` | Sheet currently on screen |\n| `sheetData` | `SheetData \\| null` | Data for the active sheet |\n| `selection` | `CellRange[]` | Selected ranges — empty when nothing is selected |\n| `activeCell` | `ActiveCell \\| null` | Anchor cell of the selection |\n| `zoom` | `number` | Current zoom factor |\n| `mode` | `'view' \\| 'edit'` | Current viewer mode |\n\n`onClick` also gets `element`, the tool's own button, for anchoring a popover or menu to it.\n\n---\n\n## Custom loading UI\n\n`renderLoading` replaces the built-in card shown while the file is fetched and parsed. Your node renders inside the viewer's own full-bleed overlay, so you only describe the content — positioning and stacking are handled.\n\n```tsx\n (\n \n )}\n/>\n```\n\n| Field | Type | Description |\n|---|---|---|\n| `progress` | `number` | Overall progress, 0–100 |\n| `status` | `string` | Current step, e.g. `\"Parsing workbook...\"`. Empty while fetching |\n| `fileName` | `string \\| null` | Name of the file being loaded, once known |\n| `isFetching` | `boolean` | True while the source is still being fetched or read, before parsing starts |\n\nReturn `null` to show nothing at all. Omit the prop to keep the default card.\n\n---\n\n## Cell Comments\n\nCells with comments display a red triangle in the top-right corner. Hover to see the comment. Manage via ref:\n\n```tsx\nref.current?.setCellComment('A1', 'Review this value', 'Alice');\nconst comment = ref.current?.getCellComment('A1');\nref.current?.setCellComment('A1', null); // Remove\n```\n\n---\n\n## Conditional Formatting\n\n```typescript\nconst rules: ConditionalFormatRule[] = [\n {\n type: 'greaterThan',\n range: { startRow: 0, startCol: 0, endRow: 99, endCol: 0 },\n values: [100],\n style: { bgColor: '#e6f4ea', fontColor: '#137333' },\n },\n {\n type: 'colorScale',\n range: { startRow: 0, startCol: 1, endRow: 99, endCol: 1 },\n colorScale: ['#f4cccc', '#fce8b2', '#b7e1cd'],\n },\n];\n```\n\nSupported rule types: `greaterThan`, `lessThan`, `between`, `equalTo`, `textContains`, `top10`, `bottom10`, `colorScale`, `dataBar`.\n\n---\n\n## Data Validation\n\n```typescript\nconst validations: Record = {\n '0,0': { type: 'list', listItems: ['High', 'Medium', 'Low'] },\n '0,1': { type: 'number', min: 0, max: 100, errorMessage: 'Must be 0–100' },\n};\n```\n\n---\n\n## Formula Engine\n\nParse and evaluate Excel-style formulas. 24 built-in functions:\n\n| Category | Functions |\n|---|---|\n| Math | `SUM`, `AVERAGE`, `COUNT`, `COUNTA`, `MIN`, `MAX`, `ABS`, `SQRT`, `POWER`, `ROUND` |\n| Logical | `IF`, `AND`, `OR`, `NOT` |\n| Text | `CONCATENATE`, `LEFT`, `RIGHT`, `MID`, `LEN`, `UPPER`, `LOWER`, `TRIM` |\n| Lookup | `VLOOKUP`, `HLOOKUP`, `INDEX`, `MATCH` |\n\n---\n\n## Types\n\nAll types are exported:\n\n```tsx\nimport type {\n SheetViewerProps,\n SheetViewerHandle,\n SheetViewerKeyboardConfig,\n SheetViewerSource,\n SheetViewerMode,\n SheetViewerTheme,\n SheetViewerTool,\n SheetViewerToolDefinition,\n SheetViewerToolContext,\n SheetViewerToolClickContext,\n SheetViewerToolIcon,\n SheetViewerToolIconProps,\n SheetViewerToolsPlacement,\n SheetViewerLoadingState,\n SheetData,\n CellRange,\n CellValue,\n CellComment,\n CellStyle,\n ChartOverlay,\n ChartSeries,\n ChartType,\n ConditionalFormatRule,\n ConditionalFormatRuleType,\n GridLineConfig,\n GridLineBorderStyle,\n ParsedGridLineConfig,\n MergeCell,\n SelectionState,\n UndoEntry,\n ValidationRule,\n ValidationRuleType,\n} from 'rc-sheet-viewer-17';\n```\n\n---\n\n## Multiple Instances\n\nEach `` is fully isolated with its own state:\n\n```tsx\n\n \n \n
\n```\n\n---\n\n## Styling\n\nImport the CSS once:\n\n```tsx\nimport 'rc-sheet-viewer-17/style.css';\n```\n\nAll classes are scoped under `.sheet-viewer` and prefixed with `sv-`. Override CSS variables via the `theme` prop or directly in CSS:\n\n```css\n.sheet-viewer {\n --sv-color-bg: #1e1e2e;\n --sv-color-primary: #89b4fa;\n --sv-search-match-color: rgba(137, 180, 250, 0.3);\n --sv-search-active-color: rgba(137, 180, 250, 0.6);\n}\n```\n\n---\n\n## Development\n\n### Prerequisites\n\n- Node.js 18+\n- pnpm 8+\n\n### Commands\n\n```bash\npnpm dev # Start demo app (dev server)\npnpm build # Build demo app\npnpm build:lib # Build library package\npnpm typecheck # TypeScript type checking\npnpm test # Run all tests\npnpm test:watch # Tests in watch mode\npnpm lint # ESLint\npnpm storybook # Storybook at localhost:6006\npnpm build-storybook # Static Storybook build\npnpm chromatic # Visual regression tests\n```\n\n---\n\n## Browser Support\n\nWorks in all modern browsers (Chrome, Firefox, Safari, Edge). No IE11 support.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}