> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# @reductoai/xlsx/view

The grid in a page. See [View](https://docs.reducto.ai/office/xlsx/rendering/view.md).

## `previewWorkbook()`

```ts theme={null}
function previewWorkbook(
  container: HTMLElement,
  wb: Workbook,
  options?: WorkbookViewOptions,
): WorkbookView
```

Mounts a grid for a workbook in `container`; read-only unless `editable` is set.

Import from `@reductoai/xlsx/view`.

## `WorkbookView`

Read-only workbook grid: formula bar, scrolling canvas with frozen panes, sheet tabs and zoom.

Import from `@reductoai/xlsx/view`.

| Name | Type | Description |
| - | - | - |
| `addingToSelection` | `boolean` | Shift+F8's Add to Selection is on: moving or clicking starts a new area. |
| `canvas` | `HTMLCanvasElement` | |
| `chartSheet` | `string \| null` | The chart sheet shown in place of the worksheets, or null. |
| `chartSheetEdits` | `{ rename: any } \| null` | Set by an editor to rename chart sheets from their tabs. |
| `editingShapeText` | `boolean` | |
| `edits` | `EditSession \| null` | The edit history when the view is editable. |
| `layout` | `WorkbookLayout` | |
| `pageBreakPreview` | `boolean` | View > Page Break Preview for the active sheet: the print area's pages over the grid. Not saved. |
| `pageLayoutView` | `boolean` | View > Page Layout: the sheet on pages, with its header and footer. |
| `root` | `HTMLElement` | |
| `shapesTakeFormat` | `boolean` | True when the Home tab's font and align commands act on shapes instead of cells. |
| `sheetView` | `"pageBreak" \| "normal" \| "pageLayout"` | Which of the three sheet views the active sheet shows. |
| `showAllNotes` | `boolean` | Review > Show All Notes: every note's box stays on the sheet. Not saved. |
| `showFormulas` | `boolean` | Cells of the active sheet show their formulas, as Ctrl+\` toggles. |
| `split` | `boolean` | View > Split for the active sheet: up to four panes, each row and column band scrolled on its own. Not saved. |
| `statusBar` | `HTMLElement` | An empty box in the tab row before zoom, where Excel's status bar shows Sum, Count and Average. |
| `cancelInsertFunction()` | `() => void` | Cancel in Insert Function: back to the edit, or out of it when Shift+F3 started it. |
| `cancelInsertText()` | `() => void` | Cancel in Paste Name: back to the edit F3 was pressed in. |
| `cellAtPoint()` | `(clientX: number, clientY: number) => { c: number; r: number } \| null` | The cell under a client point, or null off the cells. |
| `cellBox()` | `(r: number, c: number) => DOMRect` | A cell's box in client px (a merged cell's whole block), for a window opened beside it. |
| `changed()` | `(block: CellBlock) => void` | Redraws after an edit made outside the grid (a toolbar, a script) and fires `edit` with its cells. |
| `chartPartAt()` | `(clientX: number, clientY: number, picked?: string) => string \| null` | The element of the selected chart under a pointer, as Excel's second click picks it; null off it. With the `picked` series or one of its points, a click on a point picks that point. |
| `circleInvalid()` | `() => number` | Circle Invalid Data on the active sheet: rings cells that fail their validation (at most 255) and returns how many. |
| `clearCircles()` | `() => void` | Clear Validation Circles on the active sheet. |
| `destroy()` | `() => void` | |
| `editChartText()` | `(target: FormulaBarTarget, at?: { clientX: number; clientY: number }) => boolean` | Edits the picked chart element's text in place, the caret at a client point; false when it shows none. |
| `editShapeText()` | `(index: number, how?: ShapeTextOpen) => boolean` | Opens the text of drawing `index` for typing in place; false when it takes none. |
| `endChartText()` | `(cancel?: boolean) => void` | Commits an open in-place chart text edit; `cancel` drops it. |
| `endShapeText()` | `(cancel?: boolean) => void` | Closes the shape text editor, writing its text unless `cancel`. |
| `formatShapeText()` | `(patch: ShapeTextPatch) => boolean` | A font or align command on the open shape text, else on all text of the selected shapes. |
| `getActiveCell()` | `() => { c: number; r: number }` | |
| `getActiveSheet()` | `() => Sheet` | |
| `getActiveSheetIndex()` | `() => number` | |
| `getAreas()` | `() => Selection[]` | Every selected area, the one with the active cell last; one unless Ctrl+click added more. |
| `getSelectedDrawing()` | `() => DrawingSelection \| null` | The selected drawing object; a click on one selects it, a click on a cell or Escape lets go. |
| `getSelectedDrawings()` | `() => DrawingSelection[]` | Every selected drawing object; Shift or Ctrl/Cmd+click adds one, Ctrl/Cmd+A on a drawing takes all. |
| `getSelection()` | `() => Selection` | |
| `getSheetGroup()` | `() => number[] \| null` | The grouped sheets (Ctrl or Shift+click on tabs), with the active one; null for one sheet. |
| `getState()` | `() => PreviewerState` | |
| `getZoom()` | `() => number` | |
| `insertFunction()` | `(name: string, args?: string[]) => boolean` | OK in Insert Function or Function Arguments: writes `NAME(args)` where Shift+F3 was pressed and enters the formula. |
| `insertText()` | `(text: string) => boolean` | Use in Formula: `text` goes in at the caret of the edit, or starts one as `=text`. |
| `off()` | `(name: PreviewerEventName, listener: EventListener) => void` | |
| `on()` | `(name: PreviewerEventName, listener: EventListener) => void` | |
| `rangeImage()` | `(range?: string, options?: RangeImageOptions) => Promise<Blob>` | A PNG of `range` ("B2:F20", "Summary!A1:H30"; the selection when left out) as Excel's Copy Picture paints it: no headers, no selection, the shown column widths and row heights. Waits for the fonts and pictures it uses. At most 1,000 rows by 100 columns. |
| `redraw()` | `() => void` | |
| `refresh()` | `() => void` | Redraws after workbook edits, keeping the sheet, selection, scroll and whatever the edits did not touch. |
| `renameTab()` | `(index?: number) => void` | Edits a sheet tab's name in place, the active one by default; an editable grid only. |
| `replaceLayout()` | `(layout: WorkbookLayout) => void` | |
| `run()` | `(command: "cursor.left" \| "cursor.right" \| "cursor.down" \| "cursor.up" \| "cursor.lastCell" \| "cursor.edgeLeft" \| "cursor.edgeRight" \| "cursor.edgeUp" \| "cursor.edgeDown" \| "cursor.rowStart" \| "cursor.sheetStart" \| "cursor.pageUp" \| "cursor.pageDown" \| "cursor.pageLeft" \| "cursor.pageRight" \| "cursor.left.select" \| "cursor.right.select" \| "cursor.down.select" \| "cursor.up.select" \| "cursor.lastCell.select" \| "cursor.edgeLeft.select" \| "cursor.edgeRight.select" \| "cursor.edgeUp.select" \| "cursor.edgeDown.select" \| "cursor.rowStart.select" \| "cursor.sheetStart.select" \| "cursor.pageUp.select" \| "cursor.pageDown.select" \| "cursor.pageLeft.select" \| "cursor.pageRight.select" \| "cursor.enterDown" \| "cursor.enterUp" \| "cursor.tabRight" \| "cursor.tabLeft" \| "cursor.nextCorner" \| "view.showActiveCell" \| "edit.selectAll" \| "select.region" \| "select.rows" \| "select.columns" \| "select.activeCell" \| "selection.addMode" \| "selection.endMode" \| "sheet.next" \| "sheet.previous" \| "cell.pickFromList" \| "edit.undo" \| "edit.redo" \| "cell.edit" \| "cell.clear" \| "cell.backspace" \| "cell.insertDate" \| "cell.insertTime" \| "cell.copyFormulaAbove" \| "cell.copyValueAbove" \| "formula.insertFunction" \| "fill.down" \| "fill.right" \| "edit.pasteValues" \| "cells.insert" \| "cells.delete" \| "view.contextMenu" \| "view.formulas" \| "view.notes" \| "view.normal" \| "view.pageBreakPreview" \| "view.pageLayout" \| "view.split") => boolean` | Runs a grid command as its key does (`GRID_COMMANDS`, Excel's key in `gridKeyCommand`); false when it does not apply here. |
| `scrollToCell()` | `(r: number, c: number) => void` | |
| `selectAreas()` | `(areas: Selection[], options?: { activeCell?: { c: number; r: number }; scroll?: boolean }) => void` | Selects several areas at once; the active cell goes in the last. |
| `selectCell()` | `(r: number, c: number, options?: { scroll?: boolean }) => void` | |
| `selectDrawing()` | `(index: number \| null) => void` | Selects the drawing at `index` in the active sheet's drawings, or none. |
| `selectDrawings()` | `(indices: number[]) => void` | Selects the drawings at `indices` in the active sheet's drawings; the last is the one clicked last. |
| `selectedLines()` | `() => "rows" \| "cols" \| null` | "rows" or "cols" when the selection is whole lines (a header press), else null. |
| `selectRange()` | `(selection: Selection, options?: { activeCell?: { c: number; r: number }; scroll?: boolean }) => void` | |
| `setActiveSheet()` | `(sheet: string \| number) => void` | |
| `setChartPart()` | `(part: string \| null) => void` | Outlines an element of the selected chart, as the Format pane edits it; null clears it. |
| `setFormulaBar()` | `(target: FormulaBarTarget \| null) => void` | Lets the formula bar edit `target` (a chart title) instead of the active cell; null gives it back. |
| `setPeerMarks()` | `(marks: PeerMark[]) => void` | Other writers' selections in a shared session, drawn in their colours. |
| `setSheetGroup()` | `(sheets: readonly number[] \| null) => void` | Groups these sheets; null, one sheet or a set without the active sheet ungroups. |
| `setSourceMarks()` | `(marks: PeerMark[]) => void` | Outlines the cells the picked chart element reads, each on its own sheet; an empty list clears them. |
| `setTraceArrows()` | `(arrows: TraceArrow[]) => void` | Formula auditing's tracer arrows, each on its own sheet; an empty list clears them. |
| `setZoom()` | `(zoom: number) => void` | |
| `shapeTextFormat()` | `() => ShapeTextState \| null` | The Home tab's state on the open shape text, else on the first selected shape's text. |
| `sheetPointAt()` | `(clientX: number, clientY: number) => { left: number; top: number } \| null` | A client point in points from the corner of A1, where a dropped picture goes; null off the cells. |
| `sheetsChanged()` | `(active: number, remap: (index: number) => number \| null) => void` | Redraws after sheets were added, deleted, moved or hidden; `remap` takes an old tab index to its new one. |
| `showChartSheet()` | `(name: string \| null) => void` | Opens a chart sheet by name; null goes back to the active worksheet. |
| `showPageBreaks()` | `(on?: boolean) => void` | Shows the active sheet's page break lines; Excel turns them on when a break is inserted. |
| `splitAt()` | `(r: number, c: number) => void` | Splits so the bottom-right pane starts at row `r` and column `c`; 0 leaves that way whole. |
| `splitCell()` | `() => { c: number; r: number } \| null` | Where Freeze Panes freezes a split window: past the rows and columns its top-left pane shows; null when not split. |
| `viewCenter()` | `() => { left: number; top: number } \| null` | The middle of the cells in view, in points from the corner of A1, where Insert Chart centres a chart. |
| `zoomToSelection()` | `() => void` | View > Zoom to Selection: fits the selection and centres it. |

## `WorkbookViewOptions`

Construct a type with the properties of T except for those in type K.

Import from `@reductoai/xlsx/view`.

| Name | Type | Description |
| - | - | - |
| `className?` | `string` | |
| `editable?` | `boolean` | Lets the user type into cells; edits go through the `Excel.*` facade and recalculate. |
| `hostKeys?` | `boolean` | The host binds the grid's command keys and calls `run`; the grid then reads only Escape, typing and a selected drawing's keys. |
| `initialSheet?` | `string \| number` | |
| `initialZoom?` | `number` | |
| `readOnly?` | `boolean` | With `editable`: the edit session stays for scripts and shared edits, the grid takes only selection and Copy. |
| `session?` | `EditSession` | With `editable`: the session to keep, so a remount does not lose its history or its shared edits. |
| `showHidden?` | `boolean` | |

## `setDrawingHost()`

```ts theme={null}
function setDrawingHost(next: DrawingHost | null): void
```

Import from `@reductoai/xlsx/view`.

## `browserDrawingHost()`

```ts theme={null}
function browserDrawingHost(provider: FaceProvider): DrawingHost
```

Import from `@reductoai/xlsx/view`.

## `DrawingHost`

Import from `@reductoai/xlsx/view`.

| Name | Type | Description |
| - | - | - |
| `addFaces?` | `(manifest: FaceManifest, traced: string[]) => Promise<boolean> \| boolean` | The faces a drawing used (`manifest`) and every face id its layout asked the registry for (`traced`). Resolves true when the drawing should be painted again. |
| `faces` | `CanvasFaces` | |
| `measurer` | `FontMeasurer` | Drawings are laid out again whenever this changes, so a host swaps it once new faces arrive. |

## `portableFaceProvider()`

```ts theme={null}
function portableFaceProvider(urlFor: (file: string) => string): TableFaceProvider
```

The portable profile served as static files from `urlFor(file)`. Lazy: the
first document pulls the faces it uses (a Calibri letter costs Carlito's four
files, about 1 MB), not the 16 MB profile.

Import from `@reductoai/xlsx/view`.

## `tableFaceProvider()`

```ts theme={null}
function tableFaceProvider(
  source: FaceTable | (() => Promise<FaceTable>),
  urlFor: (file: string) => string,
): TableFaceProvider
```

Lazy, content-addressed faces served as plain files. `install` costs the
table alone; each face downloads once, the first time a document needs it,
and stays for the session. A face that fails to download is left absent, so
layout falls back exactly as it would on a machine missing that font.

Import from `@reductoai/xlsx/view`.
