@extend-ai/react-xlsx 0.8.3 → 0.8.6

package/README.md

@@ -0,0 +1,392 @@
+# @extend-ai/react-xlsx
+
+React components and hooks for rendering `.xlsx` workbooks in the browser.
+
+`@extend-ai/react-xlsx` gives you:
+
+- A drop-in `XlsxViewer` for workbook previews
+- A provider/controller API for custom spreadsheet experiences
+- Worksheet rendering with frozen panes, tables, merged cells, conditional formatting, sparklines, selection, resizing, copy/paste, and zoom
+- Embedded worksheet images, shapes, form controls, charts, and chartsheet tabs
+- Worker-backed parsing and large-file guardrails
+- Thumbnail helpers for building sheet strips, previews, and navigation UIs
+- TypeScript types for viewer state, workbook metadata, charts, images, tables, and render hooks
+
+## Install
+
+```bash
+npm install @extend-ai/react-xlsx react react-dom
+```
+
+```bash
+pnpm add @extend-ai/react-xlsx react react-dom
+```
+
+`react` and `react-dom` are peer dependencies.
+
+## Main Entry Points
+
+The package exports three useful levels of API:
+
+1. `XlsxViewer`
+   A ready-to-render workbook viewer with built-in toolbar, sheet tabs, grid rendering, charts, images, and selection state.
+
+2. `XlsxViewerProvider` + viewer hooks
+   Shared controller context for custom toolbars, side panels, thumbnail strips, or other UI around the workbook.
+
+3. `useXlsxViewerController`
+   A lower-level controller hook for fully controlled integrations.
+
+## Quick Start
+
+### Basic viewer
+
+Use `XlsxViewer` when you want the smallest integration surface.
+
+```tsx
+import * as React from "react";
+import { XlsxViewer } from "@extend-ai/react-xlsx";
+
+export function WorkbookPreview() {
+  const [file, setFile] = React.useState<ArrayBuffer | undefined>();
+  const [fileName, setFileName] = React.useState<string | undefined>();
+
+  return (
+    <div style={{ display: "grid", gap: 12 }}>
+      <input
+        type="file"
+        accept=".xlsx,.xlsm,.xls"
+        onChange={async (event) => {
+          const nextFile = event.target.files?.[0];
+          setFile(nextFile ? await nextFile.arrayBuffer() : undefined);
+          setFileName(nextFile?.name);
+        }}
+      />
+
+      <XlsxViewer
+        file={file}
+        fileName={fileName}
+        height={600}
+        emptyState="Choose a workbook to preview."
+      />
+    </div>
+  );
+}
+```
+
+You can also load a remote workbook with `src`:
+
+```tsx
+import { XlsxViewer } from "@extend-ai/react-xlsx";
+
+export function RemoteWorkbookPreview() {
+  return <XlsxViewer src="/reports/quarterly-model.xlsx" height="70vh" />;
+}
+```
+
+### Provider and hooks
+
+Use `XlsxViewerProvider` when custom UI needs access to the active workbook, selection, zoom, charts, images, tables, or editing commands.
+
+```tsx
+import {
+  DefaultXlsxToolbar,
+  XlsxViewer,
+  XlsxViewerProvider,
+  useXlsxViewerSelection,
+  useXlsxViewerZoom,
+} from "@extend-ai/react-xlsx";
+
+function WorkbookStatus() {
+  const { activeCellAddress, selectedRangeAddress } = useXlsxViewerSelection();
+  const { zoomScale, zoomIn, zoomOut, canZoomIn, canZoomOut } = useXlsxViewerZoom();
+
+  return (
+    <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
+      <span>{selectedRangeAddress ?? activeCellAddress ?? "No selection"}</span>
+      <button type="button" onClick={zoomOut} disabled={!canZoomOut}>
+        -
+      </button>
+      <span>{zoomScale}%</span>
+      <button type="button" onClick={zoomIn} disabled={!canZoomIn}>
+        +
+      </button>
+    </div>
+  );
+}
+
+export function WorkbookWorkspace({ file }: { file: ArrayBuffer }) {
+  return (
+    <XlsxViewerProvider file={file} fileName="model.xlsx">
+      <DefaultXlsxToolbar />
+      <WorkbookStatus />
+      <XlsxViewer height="70vh" showDefaultToolbar={false} />
+    </XlsxViewerProvider>
+  );
+}
+```
+
+### Controlled controller
+
+Use `useXlsxViewerController` when you want to own the controller instance and pass it into several components.
+
+```tsx
+import {
+  XlsxViewer,
+  useXlsxViewerController,
+} from "@extend-ai/react-xlsx";
+
+export function ControlledWorkbook({ file }: { file: ArrayBuffer }) {
+  const controller = useXlsxViewerController({
+    file,
+    fileName: "forecast.xlsx",
+    readOnlyAboveBytes: 10 * 1024 * 1024,
+  });
+
+  return (
+    <div style={{ display: "grid", gap: 12 }}>
+      <button type="button" onClick={controller.exportXlsx} disabled={!controller.canExport}>
+        Export XLSX
+      </button>
+
+      <XlsxViewer controller={controller} height={640} />
+    </div>
+  );
+}
+```
+
+## Useful Hooks
+
+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
+- `useXlsxViewerTables()` for table metadata and table sorting
+- `useXlsxViewerImages()` for embedded image and chart selection, movement, and resizing
+- `useXlsxViewerCharts()` for chart and chartsheet state
+- `useXlsxViewerThumbnails(options)` for painting worksheet thumbnails into your own canvases
+
+## Thumbnail Hook
+
+`useXlsxViewerThumbnails` returns paint functions for each worksheet so you can build your own sheet strip or navigation UI.
+
+```tsx
+import * as React from "react";
+import {
+  XlsxViewerProvider,
+  useXlsxViewerThumbnails,
+  type XlsxSheetThumbnail,
+} from "@extend-ai/react-xlsx";
+
+function SheetThumbnail({ thumbnail }: { thumbnail: XlsxSheetThumbnail }) {
+  const canvasRef = React.useRef<HTMLCanvasElement | null>(null);
+
+  React.useEffect(() => {
+    thumbnail.paint(canvasRef.current);
+  }, [thumbnail]);
+
+  return (
+    <canvas
+      ref={canvasRef}
+      width={thumbnail.width}
+      height={thumbnail.height}
+      style={{ width: thumbnail.width, height: thumbnail.height }}
+    />
+  );
+}
+
+function SheetThumbnailStrip() {
+  const { thumbnails } = useXlsxViewerThumbnails({
+    includeHeaders: true,
+    resolution: { maxWidth: 180, maxHeight: 120 },
+  });
+
+  return (
+    <div style={{ display: "flex", gap: 12, overflowX: "auto" }}>
+      {thumbnails.map((thumbnail) => (
+        <SheetThumbnail
+          key={thumbnail.workbookSheetIndex}
+          thumbnail={thumbnail}
+        />
+      ))}
+    </div>
+  );
+}
+
+export function ThumbnailExample({ file }: { file: ArrayBuffer }) {
+  return (
+    <XlsxViewerProvider file={file}>
+      <SheetThumbnailStrip />
+    </XlsxViewerProvider>
+  );
+}
+```
+
+Notes:
+
+- `resolution` accepts either a single max dimension or `{ maxWidth, maxHeight }`.
+- Thumbnails preserve worksheet aspect ratio and paint into your supplied `<canvas>`.
+- The current implementation renders a bounded top-left worksheet preview, including loaded embedded worksheet images, shapes, and form controls, but does not include charts.
+
+## Custom Rendering
+
+The viewer exposes render props for common UI integration points.
+
+```tsx
+import { XlsxViewer } from "@extend-ai/react-xlsx";
+
+export function CustomWorkbook({ file }: { file: ArrayBuffer }) {
+  return (
+    <XlsxViewer
+      file={file}
+      height={600}
+      selectionColor="#2563eb"
+      renderImage={({ image, style }) => (
+        <img
+          src={image.src}
+          alt={image.description ?? image.name ?? ""}
+          style={{ ...style, objectFit: "contain" }}
+        />
+      )}
+      renderTableHeaderMenu={({ column, direction, sortAscending, sortDescending, triggerIcon, triggerProps }) => (
+        <span>
+          <button type="button" {...triggerProps}>
+            {triggerIcon}
+          </button>
+          <button type="button" onClick={sortAscending}>
+            Sort A to Z{direction === "ascending" ? " selected" : ""}
+          </button>
+          <button type="button" onClick={sortDescending}>
+            Sort Z to A{direction === "descending" ? " selected" : ""}
+          </button>
+          <span>{column.name}</span>
+        </span>
+      )}
+    />
+  );
+}
+```
+
+Apply `triggerProps` to the table-header trigger button so clicks do not leak into grid selection.
+
+## Large Files
+
+`XlsxViewer` includes guardrails for large workbooks.
+
+```tsx
+import { XlsxViewer } from "@extend-ai/react-xlsx";
+
+export function LargeWorkbookPreview({ file }: { file: ArrayBuffer }) {
+  return (
+    <XlsxViewer
+      file={file}
+      maxFileSizeBytes={50 * 1024 * 1024}
+      readOnlyAboveBytes={10 * 1024 * 1024}
+      deferLoadingAboveBytes={20 * 1024 * 1024}
+      fileTooLargeState={({ displayFileName, fileSizeBytes, maxFileSizeBytes }) => (
+        <div>
+          <strong>{displayFileName}</strong> is too large to open here.
+          <div>
+            {Math.round(fileSizeBytes / (1024 * 1024))} MB of{" "}
+            {Math.round(maxFileSizeBytes / (1024 * 1024))} MB allowed
+          </div>
+        </div>
+      )}
+    />
+  );
+}
+```
+
+Notes:
+
+- `maxFileSizeBytes` defaults to `25 MB`.
+- `readOnlyAboveBytes` can disable mutation actions for larger files.
+- `deferLoadingAboveBytes` waits for `controller.continueDeferredLoad()` before parsing files above the threshold.
+- `useWorker` defaults to `true` when browser workers are available.
+
+## Viewer Props
+
+`XlsxViewerProps` includes all controller options plus rendering options.
+
+Common source and loading props:
+
+- `file?: ArrayBuffer`
+- `src?: string`
+- `fileName?: string`
+- `controller?: XlsxViewerController`
+- `useWorker?: boolean`
+- `maxFileSizeBytes?: number`
+- `readOnly?: boolean`
+- `readOnlyAboveBytes?: number`
+- `deferLoadingAboveBytes?: number`
+- `showHiddenSheets?: boolean`
+- `skipXmlParsing?: boolean`
+
+Common rendering props:
+
+- `height?: React.CSSProperties["height"]`
+- `className?: string`
+- `isDark?: boolean`
+- `rounded?: boolean`
+- `showDefaultToolbar?: boolean`
+- `toolbar?: React.ReactNode | ((controller: XlsxViewerController) => React.ReactNode)`
+- `experimentalCanvas?: boolean`
+- `enableGestureZoom?: boolean`
+- `enableCanvasSelectionAnimation?: boolean`
+- `allowResizeInReadOnly?: boolean`
+- `selectionColor?: string`
+- `selectionFillColor?: string`
+- `selectionHeaderColor?: string`
+- `showImages?: boolean`
+- `emptyState?: React.ReactNode`
+- `loadingState?: React.ReactNode`
+- `errorState?: React.ReactNode | ((error: Error) => React.ReactNode)`
+- `fileTooLargeState?: React.ReactNode | ((props: XlsxFileTooLargeRenderProps) => React.ReactNode)`
+- `renderImage?: (props: XlsxImageRenderProps) => React.ReactNode`
+- `renderImageSelection?: (props: XlsxImageSelectionRenderProps) => React.ReactNode`
+- `renderChartLoading?: (props: XlsxChartLoadingRenderProps) => React.ReactNode`
+- `renderTableHeaderMenu?: (props: XlsxTableHeaderMenuRenderProps) => React.ReactNode`
+
+## Workbook Support
+
+Primary support is for OOXML `.xlsx` workbooks.
+
+Supported worksheet features include:
+
+- Frozen panes, merged cells, row and column sizing, hidden rows and columns, and gridline settings
+- Cell styles, fills, borders, alignment, number formats, formulas, cached formula values, and cell controls
+- Tables, table sorting, conditional formatting, data validation metadata, and sparklines
+- Embedded images, shapes, form controls, worksheet charts, and chartsheet tabs
+- Copy, paste, undo, redo, merge, unmerge, fill, CSV export, and XLSX export
+
+Chart rendering supports common Excel chart families including column, bar, line, area, scatter, pie, doughnut, radar, bubble, stock, surface, waterfall, funnel, box-and-whisker, sunburst, treemap, region map, combo charts, and chartsheets.
+
+Legacy `.xls` and macro-enabled `.xlsm` files have limited support. The viewer only displays workbook data that `@dukelib/sheets-wasm` can parse, and format-specific XML features may be missing or skipped.
+
+## Exported Types
+
+The package exports the main types you are likely to use for custom integrations:
+
+- `UseXlsxViewerControllerOptions`
+- `XlsxViewerProps`
+- `XlsxViewerProviderProps`
+- `XlsxViewerController`
+- `XlsxViewerSelection`
+- `XlsxViewerZoom`
+- `XlsxViewerEditing`
+- `XlsxViewerTables`
+- `XlsxViewerImages`
+- `XlsxViewerCharts`
+- `XlsxViewerThumbnails`
+- `XlsxSheetThumbnail`
+- `UseXlsxViewerThumbnailsOptions`
+- `XlsxChart`, `XlsxChartSeries`, `XlsxChartAxis`, `XlsxChartsheet`
+- `XlsxImage`, `XlsxImageRect`, `XlsxImageRenderProps`, `XlsxImageSelectionRenderProps`
+- `XlsxTable`, `XlsxTableColumn`, `XlsxTableHeaderMenuRenderProps`
+- `XlsxWorkbookTab`, `XlsxCellAddress`, `XlsxCellRange`
+
+## License
+
+See the repository license for usage terms.