beautiful-grid 1.0.11 → 1.0.13

package/types/types.d.ts

@@ -148,6 +148,15 @@ export interface BGridSearchCellParams<T> {
     values: T;
     value: unknown;
 }
+export interface BGridCellExportValueParams<T> {
+    column: BGridColumn<T>;
+    columnId: string;
+    visibleIndex?: number;
+    sourceIndex: number;
+    item: BGridDataItem<T>;
+    values: T;
+    value: unknown;
+}
 export interface BGridColumn<T> {
     id?: string;
     key: string | string[];
@@ -184,6 +193,9 @@ export interface BGridColumn<T> {
         aItem: BGridDataItem<T>;
         bItem: BGridDataItem<T>;
     }) => number;
+    exportable?: boolean;
+    exportHeader?: string | ((column: BGridColumn<T>) => string);
+    getExportValue?: (params: BGridCellExportValueParams<T>) => unknown;
 }
 export interface BGridColumnGroup {
     label: ReactNode;
@@ -657,13 +669,72 @@ export interface BGridScrollToRowOptions {
     /** Defaults to nearest: scroll only as far as needed to reveal the row. */
     align?: 'start' | 'center' | 'end' | 'nearest';
 }
-export interface BGridRef {
+export type BGridExportRowScope = 'displayed' | 'checked' | 'source';
+export type BGridExportColumnScope = 'visible' | 'all' | readonly string[];
+export interface BGridExportColumn<T> {
+    columnId: string;
+    header: string;
+    column: BGridColumn<T>;
+    columnIndex: number;
+}
+export interface BGridExportRow<T> {
+    visibleIndex?: number;
+    sourceIndex: number;
+    rowKey?: React.Key;
+    item: BGridDataItem<T>;
+    values: T;
+    cells: unknown[];
+}
+export interface BGridExportData<T> {
+    columns: BGridExportColumn<T>[];
+    rows: BGridExportRow<T>[];
+}
+export interface BGridExportDataOptions {
+    rows?: BGridExportRowScope;
+    columns?: BGridExportColumnScope;
+}
+export interface BGridCsvSerializeOptions {
+    delimiter?: string;
+    newline?: '\n' | '\r\n';
+    includeHeader?: boolean;
+    bom?: boolean;
+    preventFormulaInjection?: boolean;
+}
+export interface BGridCsvExportOptions extends BGridExportDataOptions {
+    fileName?: string;
+    delimiter?: string;
+    newline?: '\n' | '\r\n';
+    includeHeader?: boolean;
+    bom?: boolean;
+    preventFormulaInjection?: boolean;
+}
+export interface BGridExcelSerializeOptions {
+    sheetName?: string;
+    includeHeader?: boolean;
+}
+export interface BGridExcelExportOptions extends BGridExportDataOptions, BGridExcelSerializeOptions {
+    fileName?: string;
+}
+export interface BGridRef<T = any> {
     /**
      * Reveal a zero-based row in the displayed (sorted/filtered) data on the current page.
      * Runs after pending data updates. Invalid indexes and frozen rows are ignored.
      * Preserves horizontal scroll, cell focus and selection; does not load other pages.
      */
     scrollToRow: (rowIndex: number, options?: BGridScrollToRowOptions) => void;
+    /**
+     * Extract logical grid data for export without touching the DOM.
+     * Supports displayed, checked, or source row scopes, and visible, all, or custom column scopes.
+     */
+    getExportData: (options?: BGridExportDataOptions) => BGridExportData<T>;
+    /**
+     * Serialize grid data and trigger a browser CSV file download.
+     */
+    exportCsv: (options?: BGridCsvExportOptions) => void;
+    /**
+     * Serialize grid data and trigger a browser Excel (.xlsx) file download.
+     */
+    exportExcel: (options?: BGridExcelExportOptions) => void;
 }
 export interface BGridToolboxMessages {
     sort?: string;
@@ -712,7 +783,7 @@ export interface BGridMessages {
     toolbox?: BGridToolboxMessages;
 }
 export interface BGridProps<T> {
-    ref?: React.Ref<BGridRef>;
+    ref?: React.Ref<BGridRef<T>>;
     width: number;
     height: number;
     headerHeight?: number;
@@ -840,6 +911,50 @@ export interface BGridProps<T> {
     columnVisibility?: boolean | BGridColumnVisibilityOptions<T>;
     searchOptions?: BGridSearchOptions<T>;
     contextMenuOptions?: BGridContextMenuOptions<T>;
+    /** Enables hierarchical rows from flat data related by rowKey and parentRowKey. */
+    tree?: BGridTreeOptions<T>;
+}
+export interface BGridTreeIcons {
+    expanded?: React.ReactNode;
+    collapsed?: React.ReactNode;
+    leaf?: React.ReactNode;
+}
+export interface BGridTreeRowMeta {
+    rowKey: React.Key;
+    parentRowKey?: React.Key;
+    depth: number;
+    hasChildren: boolean;
+    expanded: boolean;
+    sourceIndex: number;
+    parentSourceIndex?: number;
+    siblingIndex: number;
+    siblingCount: number;
+}
+export interface BGridTreeOptions<T> {
+    enabled?: boolean;
+    /** Field containing the parent row's rowKey value. */
+    parentRowKey: React.Key | React.Key[];
+    /** Column ID that renders indentation and the folding control. Defaults to the first visible column. */
+    treeColumnId?: string;
+    expandedRowKeys?: readonly React.Key[];
+    defaultExpandedRowKeys?: readonly React.Key[];
+    onExpandedRowKeysChange?: (keys: React.Key[], event: {
+        rowKey: React.Key;
+        expanded: boolean;
+        item: BGridDataItem<T>;
+        sourceIndex: number;
+    }) => void;
+    indentSize?: number;
+    icons?: BGridTreeIcons;
+    expandAriaLabel?: string;
+    collapseAriaLabel?: string;
+}
+export interface BGridTreeChangeDataMeta {
+    rowKey: React.Key;
+    parentRowKey?: React.Key;
+    sourceIndex: number;
+    depth: number;
+    path: readonly React.Key[];
 }
 export type CheckedAll = true | false | 'indeterminate';
 export interface BGridChangeDataMeta<T> {
@@ -852,6 +967,8 @@ export interface BGridChangeDataMeta<T> {
      * item to preserve cell and value change state after synchronizing `data`.
      */
     dataItem: BGridDataItem<T>;
+    /** Tree identity for the edited row. Undefined in flat mode. */
+    tree?: BGridTreeChangeDataMeta;
     transaction: {
         merged: boolean;
         canonicalCell: BGridCellAddress;
@@ -863,6 +980,8 @@ export interface AppModelColumn<T> extends BGridColumn<T> {
     columnId: string;
     keyToken?: string;
     left: number;
+    /** @internal Marks the single column that hosts tree indentation and folding controls. */
+    treeCell?: boolean;
 }
 export interface AppModel<T> extends BGridProps<T> {
     initialized: boolean;

package/types/utils/exportCsv.d.ts

@@ -0,0 +1,5 @@
+import { BGridCsvSerializeOptions, BGridExportData } from '../types';
+export declare function formatCsvCellValue(value: unknown, preventFormulaInjection?: boolean): string;
+export declare function escapeCsvCell(cell: string, delimiter?: string): string;
+export declare function serializeGridExportDataToCsv<T>(data: BGridExportData<T>, options?: BGridCsvSerializeOptions): string;
+export declare function downloadCsv(csv: string, fileName?: string): void;

package/types/utils/exportData.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { BGridColumn, BGridDataItem, BGridExportColumn, BGridExportColumnScope, BGridExportData, BGridExportDataOptions, BGridExportRow } from '../types';
+export declare function resolveExportColumns<T>(columns: readonly BGridColumn<T>[], sourceColumns?: readonly BGridColumn<T>[], scope?: BGridExportColumnScope): BGridExportColumn<T>[];
+export interface CreateGridExportDataParams<T> {
+    options?: BGridExportDataOptions;
+    columns: readonly BGridColumn<T>[];
+    sourceColumns?: readonly BGridColumn<T>[];
+    data: readonly BGridDataItem<T>[];
+    sourceData?: readonly BGridDataItem<T>[];
+    sourceIndexByVisibleIndex?: readonly number[];
+    visibleIndexBySourceIndex?: ReadonlyMap<number, number>;
+    checkedIndexesMap?: ReadonlyMap<number, unknown>;
+    rowKey?: React.Key | React.Key[];
+}
+export declare function resolveExportRows<T>(exportColumns: readonly BGridExportColumn<T>[], params: CreateGridExportDataParams<T>): BGridExportRow<T>[];
+export declare function createGridExportData<T>(params: CreateGridExportDataParams<T>): BGridExportData<T>;

package/types/utils/exportExcel.d.ts

@@ -0,0 +1,5 @@
+import { BGridExcelSerializeOptions, BGridExportData } from '../types';
+export declare function escapeXml(value: string): string;
+export declare function colIndexToExcelColumn(colIndex: number): string;
+export declare function serializeGridExportDataToExcel<T>(data: BGridExportData<T>, options?: BGridExcelSerializeOptions): Uint8Array;
+export declare function downloadExcel(blobOrBytes: Blob | Uint8Array, fileName?: string): void;

package/types/utils/index.d.ts

@@ -16,6 +16,7 @@ export * from './number';
 export * from './buildHeaderMatrix';
 export * from './getVisibleScrollableRowRange';
 export * from './virtualScrollWindow';
+export * from './treeData';
 export * from './rowHeightMetrics';
 export * from './cellEditState';
 export * from './getCellSelectionAxisState';
@@ -26,3 +27,6 @@ export * from './rowReorder';
 export * from './checkboxEditor';
 export * from './columnVisibility';
 export * from './checkedIndexes';
+export * from './exportData';
+export * from './exportCsv';
+export * from './exportExcel';

package/types/utils/treeData.d.ts

@@ -0,0 +1,22 @@
+import type { Key } from 'react';
+import type { BGridDataItem, BGridTreeRowMeta } from '../types';
+export type BGridTreeDiagnostic = 'missingRowKey' | 'duplicateRowKey' | 'cycle';
+export interface BGridTreeProjection<T> {
+    valid: boolean;
+    data: BGridDataItem<T>[];
+    sourceIndexByVisibleIndex: number[];
+    visibleIndexBySourceIndex: Map<number, number>;
+    metaByRowKey: Map<Key, BGridTreeRowMeta>;
+    metaBySourceIndex: Map<number, BGridTreeRowMeta>;
+    diagnostics: BGridTreeDiagnostic[];
+}
+/** Projects flat parent-key data into visible pre-order rows without mutating the input. */
+export declare function projectTreeData<T>(params: {
+    data: BGridDataItem<T>[];
+    rowKey: Key | Key[];
+    parentRowKey: Key | Key[];
+    expandedRowKeys: readonly Key[];
+    includedSourceIndexes?: readonly number[];
+    orderedSourceIndexes?: readonly number[];
+}): BGridTreeProjection<T>;
+export declare function getTreeRowPath(metaBySourceIndex: ReadonlyMap<number, BGridTreeRowMeta>, sourceIndex: number): Key[];