@alaarab/ogrid-react-xlsx-browser 2.16.0 → 2.17.1

package/dist/types/XlsxGrid.d.ts

@@ -0,0 +1,18 @@
+import type ExcelJS from 'exceljs';
+import { type SheetToGridDataOptions } from './sheetMapper.js';
+export interface XlsxGridProps {
+    workbook: ExcelJS.Workbook;
+    sheetName: string;
+    /** CSS height for the grid container. Defaults to '100%'. */
+    height?: number | string;
+    /** Override grid density. Defaults to 'compact' (matches Excel-like row size). */
+    density?: 'compact' | 'normal' | 'comfortable';
+    /** See {@link SheetToGridDataOptions.headerRow}. Defaults to 'auto'. */
+    headerRow?: SheetToGridDataOptions['headerRow'];
+    /**
+     * Load limits for untrusted files; see {@link SheetToGridDataOptions}.
+     * When a sheet exceeds them a notice above the grid says what was cut.
+     */
+    limits?: Pick<SheetToGridDataOptions, 'maxRows' | 'maxCols' | 'maxCells'>;
+}
+export declare function XlsxGrid({ workbook, sheetName, height, density, headerRow, limits, }: XlsxGridProps): import("react").JSX.Element;

package/dist/types/XlsxWorkbookGrid.d.ts

@@ -0,0 +1,23 @@
+import type ExcelJS from 'exceljs';
+import { type XlsxGridProps } from './XlsxGrid.js';
+import { type SheetToGridDataOptions } from './sheetMapper.js';
+type Source = {
+    blob: Blob;
+} | {
+    workbook: ExcelJS.Workbook;
+};
+export type XlsxWorkbookGridProps = Source & {
+    /** CSS height of the whole component. Defaults to '100%'. */
+    height?: number | string;
+    /** Initial sheet to display. Defaults to the first sheet. */
+    initialSheet?: string;
+    density?: 'compact' | 'normal' | 'comfortable';
+    /** Called when the user switches sheets. */
+    onSheetChange?: (sheetName: string) => void;
+    /** See {@link SheetToGridDataOptions.headerRow}. Defaults to 'auto'. */
+    headerRow?: SheetToGridDataOptions['headerRow'];
+    /** Per-sheet load limits; see {@link XlsxGridProps.limits}. */
+    limits?: XlsxGridProps['limits'];
+};
+export declare function XlsxWorkbookGrid(props: XlsxWorkbookGridProps): import("react").JSX.Element;
+export {};

package/dist/types/exportToXlsx.d.ts

@@ -0,0 +1,34 @@
+import ExcelJS from 'exceljs';
+import { type CsvColumn } from '@alaarab/ogrid-core';
+export declare const XLSX_MIME_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+export interface XlsxExportOptions {
+    /** Worksheet name. Defaults to 'Sheet1'. */
+    sheetName?: string;
+    /**
+     * Formula cells to emit, in the same `{col, row, formula}` shape
+     * `sheetToGridData` produces on import (0-based data coordinates, header
+     * row excluded). Each is written as `{ formula, result }` — Excel shows the
+     * cached result immediately and recalculates on open. The public grid API
+     * does not expose formulas, so pass this through from the `initialFormulas`
+     * you already hold (e.g. from an imported workbook).
+     */
+    formulas?: Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>;
+}
+/**
+ * Build an ExcelJS workbook from grid data: a header row from column names,
+ * then one row per item. Values are written as native JS types (number, Date,
+ * boolean, string) so ExcelJS assigns the matching cell type — symmetric with
+ * how `sheetToGridData` detects column types on import.
+ */
+export declare function workbookFromGridData<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => unknown, options?: XlsxExportOptions): ExcelJS.Workbook;
+/** Serialize a workbook to a Blob with the .xlsx MIME type. */
+export declare function xlsxBlobFromWorkbook(wb: ExcelJS.Workbook): Promise<Blob>;
+/**
+ * Export grid data as a downloaded .xlsx file (browser-only). Mirrors
+ * `exportToCsv(items, columns, getValue, filename)` from @alaarab/ogrid-core.
+ */
+export declare function exportToXlsx<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => unknown, filename?: string, options?: XlsxExportOptions): Promise<void>;

package/dist/types/index.d.ts

@@ -0,0 +1,22 @@
+import type ExcelJS from 'exceljs';
+import { type XlsxWorkbookGridProps } from './XlsxWorkbookGrid.js';
+export { XlsxGrid, type XlsxGridProps } from './XlsxGrid.js';
+export { XlsxWorkbookGrid, type XlsxWorkbookGridProps } from './XlsxWorkbookGrid.js';
+export { workbookFromBlob, sheetToGridData, listSheets, type SheetGridData, type SheetRow, type SheetToGridDataOptions, DEFAULT_MAX_ROWS, DEFAULT_MAX_COLS, DEFAULT_MAX_CELLS, } from './sheetMapper.js';
+export { exportToXlsx, workbookFromGridData, xlsxBlobFromWorkbook, XLSX_MIME_TYPE, type XlsxExportOptions, } from './exportToXlsx.js';
+export interface MountOptions {
+    /** Pre-parsed workbook (use this OR blob, not both). */
+    workbook?: ExcelJS.Workbook;
+    /** Raw blob — parsed lazily inside the component. */
+    blob?: Blob;
+    initialSheet?: string;
+    density?: 'compact' | 'normal' | 'comfortable';
+    height?: number | string;
+    onSheetChange?: (sheetName: string) => void;
+    /** See {@link SheetToGridDataOptions.headerRow}. Defaults to 'auto'. */
+    headerRow?: 'auto' | 'header' | 'none';
+    /** Load limits for untrusted files; see {@link XlsxWorkbookGridProps.limits}. */
+    limits?: XlsxWorkbookGridProps['limits'];
+}
+/** Imperative mount for non-React hosts. Returns an unmount function. */
+export declare function mount(node: Element, opts: MountOptions): () => void;

package/dist/types/sheetMapper.d.ts

@@ -0,0 +1,90 @@
+import ExcelJS from 'exceljs';
+import type { IColumnDef } from '@alaarab/ogrid-core';
+/**
+ * Output of sheetToGridData. Feeds straight into <OGrid> as
+ * `columns={data.columns}` `data={data.rows}` `initialFormulas={data.initialFormulas}`.
+ */
+export interface SheetGridData {
+    columns: IColumnDef<SheetRow>[];
+    rows: SheetRow[];
+    initialFormulas: Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>;
+    /**
+     * Set when the sheet's populated area exceeded `maxRows`/`maxCols`/
+     * `maxCells` and was cut down. Holds the untruncated extent so callers can
+     * tell the user what was left out.
+     */
+    truncated?: {
+        rowCount: number;
+        columnCount: number;
+    };
+}
+/** Row shape — keyed by column letter (A, B, C, ..., AA, AB, ...).
+ *  `__rowIdx` is a synthetic id (0-based) so getRowId can be `(r) => r.__rowIdx`. */
+export type SheetRow = Record<string, unknown> & {
+    __rowIdx: number;
+};
+/** Options accepted by {@link sheetToGridData}. */
+export interface SheetToGridDataOptions {
+    /**
+     * Whether to promote row 1 of the worksheet into column names.
+     *
+     * - `'auto'` (default): promote when row 1 looks like a header row —
+     *   every non-empty cell is a non-empty string and the sheet has at
+     *   least 2 rows. Otherwise keep A/B/C as column names.
+     * - `'header'`: always promote row 1, coercing values to strings.
+     *   Falls back to the column letter when a cell is empty.
+     * - `'none'`: legacy behaviour — column names stay as A/B/C and
+     *   row 1 is returned as the first data row.
+     *
+     * `columnId` is always the column letter so the `cellReferences`
+     * strip and any `INDIRECT("A1")`-style formula references keep
+     * resolving the same way.
+     */
+    headerRow?: 'auto' | 'header' | 'none';
+    /** Maximum worksheet rows to load (default 1,048,576, Excel's own limit). */
+    maxRows?: number;
+    /** Maximum worksheet columns to load (default 1,000). */
+    maxCols?: number;
+    /**
+     * Maximum rows × columns to load (default 5,000,000). A few-KB xlsx with
+     * one far-away cell has a used range of billions of cells; this keeps an
+     * untrusted file from freezing the page. Rows are dropped from the bottom
+     * to fit.
+     */
+    maxCells?: number;
+}
+export declare const DEFAULT_MAX_ROWS = 1048576;
+export declare const DEFAULT_MAX_COLS = 1000;
+export declare const DEFAULT_MAX_CELLS = 5000000;
+/**
+ * Read an xlsx Blob into an ExcelJS Workbook. Falls back to a CSV/TSV
+ * parser when the bytes don't look like a zip-backed xlsx (xlsx files
+ * start with `PK\x03\x04`). The fallback synthesizes a single-sheet
+ * workbook so downstream code paths stay identical.
+ */
+export declare function workbookFromBlob(blob: Blob): Promise<ExcelJS.Workbook>;
+/**
+ * Map one ExcelJS worksheet to OGrid columns + rows + initialFormulas.
+ *
+ * Column ids are Excel letters (A, B, …, AA) so the grid's
+ * `cellReferences` mode shows A1/B1 notation that matches the
+ * source workbook exactly.
+ *
+ * Row keys are the same letters; ogrid's default valueGetter reads
+ * `row[columnId]` so no per-column getter is needed.
+ *
+ * Type detection samples up to SAMPLE_SIZE rows per column. All-numbers
+ * → 'numeric', all-Date instances → 'date', mixed/text → 'text'.
+ *
+ * Formulas (cell value `{formula, result}`) get pulled into
+ * initialFormulas; the cached `result` still goes into the row so the
+ * grid renders the right thing on first paint, before the engine
+ * recalculates.
+ */
+export declare function sheetToGridData(sheet: ExcelJS.Worksheet | null | undefined, options?: SheetToGridDataOptions): SheetGridData;
+/** List sheet names in display order. */
+export declare function listSheets(workbook: ExcelJS.Workbook): string[];

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "@alaarab/ogrid-react-xlsx-browser",
-  "version": "2.16.0",
+  "version": "2.17.1",
   "type": "module",
   "description": "Self-contained browser ESM bundle of @alaarab/ogrid-react-xlsx. React + ReactDOM + ExcelJS + every @alaarab/ogrid-* dep inlined into one file. Drop into a static vendor/ directory and `import()` from a no-bundler app.",
   "main": "dist/ogrid-xlsx.js",
   "module": "dist/ogrid-xlsx.js",
+  "types": "dist/ogrid-xlsx.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/ogrid-xlsx.d.ts",
       "import": "./dist/ogrid-xlsx.js",
       "default": "./dist/ogrid-xlsx.js"
     },
     "./ogrid-xlsx.css": "./dist/ogrid-xlsx.css"
   },
   "scripts": {
-    "build": "rimraf dist && tsup",
+    "build": "rimraf dist && tsup && node scripts/copy-types.mjs",
     "test": "echo 'no tests — this package only re-bundles @alaarab/ogrid-react-xlsx; tests live there'"
   },
   "keywords": [
@@ -33,16 +35,18 @@
     "README.md",
     "LICENSE"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "**/*.css"
+  ],
   "engines": {
     "node": ">=18"
   },
   "devDependencies": {
-    "@alaarab/ogrid-react-xlsx": "2.16.0",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "@alaarab/ogrid-react-xlsx": "2.17.1",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "rimraf": "^6.1.3",
     "tsup": "^8.5.1"
   },