beautiful-grid 1.0.0-rc.1

package/types/utils/buildHeaderMatrix.d.ts

@@ -0,0 +1,32 @@
+import type { AlignDirection, AppModelColumn, BGridColumnGroup, BGridColumnGroupNode } from '../types';
+import type { CSSProperties, ReactNode } from 'react';
+export interface HeaderCellDescriptor<T> {
+    key: string;
+    type: 'group' | 'column';
+    columnIndex?: number;
+    startColumnIndex: number;
+    endColumnIndex: number;
+    rowSpan: number;
+    colSpan: number;
+    depth: number;
+    label: ReactNode;
+    headerAlign?: AlignDirection;
+    className?: string;
+    headerStyle?: CSSProperties;
+    groupId?: string;
+    parentGroupId?: string;
+    column?: AppModelColumn<T>;
+}
+export interface BuildHeaderMatrixOptions<T> {
+    columns: AppModelColumn<T>[];
+    columnGroups?: BGridColumnGroupNode[];
+    columnsGroup?: BGridColumnGroup[];
+    startColumnIndex?: number;
+    endColumnIndex?: number;
+}
+export interface HeaderMatrix<T> {
+    rows: HeaderCellDescriptor<T>[][];
+    rowCount: number;
+    errors: string[];
+}
+export declare function buildHeaderMatrix<T>({ columns, columnGroups, columnsGroup, startColumnIndex, endColumnIndex, }: BuildHeaderMatrixOptions<T>): HeaderMatrix<T>;

package/types/utils/cellEditState.d.ts

@@ -0,0 +1,12 @@
+import { BGridColumn, BGridDataItem } from '../types';
+type ResolvedColumnKey<T> = BGridColumn<T> & {
+    keyToken?: string;
+};
+export declare function markCellEdited<T>(item: BGridDataItem<T>, column: BGridColumn<T>): void;
+export declare function isCellEdited<T>(item: BGridDataItem<T>, column: BGridColumn<T>): boolean;
+export declare function markCellValueChanged<T>(item: BGridDataItem<T>, column: ResolvedColumnKey<T>): void;
+export declare function isCellValueChanged<T>(item: BGridDataItem<T>, column: ResolvedColumnKey<T>): boolean;
+export declare function clearEditedCells<T>(item: BGridDataItem<T>): void;
+export declare function clearChangedValues<T>(item: BGridDataItem<T>): void;
+export declare function clearCellChangeState<T>(item: BGridDataItem<T>): void;
+export {};

package/types/utils/cellEditTransaction.d.ts

@@ -0,0 +1,14 @@
+import { AppModelColumn, BGridCellValueChange, BGridColumn, BGridDataItem } from '../types';
+export interface BGridResolvedCellValueChange<T> {
+    column: AppModelColumn<T>;
+    change: BGridCellValueChange<T>;
+}
+export interface BGridAppliedRowChanges<T> {
+    item: BGridDataItem<T>;
+    changes: BGridCellValueChange<T>[];
+    columns: AppModelColumn<T>[];
+}
+export declare function resolveCellValueChanges<T>(changes: readonly BGridCellValueChange<T>[], columns: AppModelColumn<T>[]): BGridResolvedCellValueChange<T>[];
+export declare function setCellValueImmutable<T>(values: T, key: BGridColumn<T>['key'], value: unknown): T;
+export declare function createNextValues<T>(values: T, changes: readonly BGridResolvedCellValueChange<T>[]): T;
+export declare function applyChangesToItem<T>(item: BGridDataItem<T>, changes: readonly BGridResolvedCellValueChange<T>[]): BGridAppliedRowChanges<T>;

package/types/utils/cellSelectionGeometry.d.ts

@@ -0,0 +1,34 @@
+import { AppModelColumn, BGridCellSelectionRange } from '../types';
+export type BGridSelectionQuadrant = 'top-left' | 'top-main' | 'body-left' | 'body-main';
+export interface BGridSelectionFragmentEdges {
+    top: boolean;
+    right: boolean;
+    bottom: boolean;
+    left: boolean;
+}
+export interface BGridSelectionFragment {
+    rangeIndex: number;
+    quadrant: BGridSelectionQuadrant;
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    edges: BGridSelectionFragmentEdges;
+}
+export interface BGridSelectionGeometryParams {
+    ranges: readonly BGridCellSelectionRange[];
+    columns: readonly AppModelColumn<any>[];
+    rowCount: number;
+    rowHeight: number;
+    frozenColumnCount: number;
+    frozenRowCount: number;
+    frozenColumnsWidth: number;
+}
+export declare function getCellSelectionFragments({ ranges, columns, rowCount, rowHeight, frozenColumnCount, frozenRowCount, frozenColumnsWidth, }: BGridSelectionGeometryParams): BGridSelectionFragment[];
+export declare function clipCellSelectionFragment(fragment: BGridSelectionFragment, viewport: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}): BGridSelectionFragment | undefined;
+export declare function normalizeCellSelectionRange(range: BGridCellSelectionRange): BGridCellSelectionRange;

package/types/utils/common.d.ts

@@ -0,0 +1,3 @@
+export declare function isObject(value: any): boolean;
+export declare function debounce(func: any, wait: any, options?: any): any;
+export declare function throttle(func: any, wait: any, options?: any): any;

package/types/utils/coordinate.d.ts

@@ -0,0 +1,29 @@
+import { AppModelColumn, BGridCellAddress } from '../types';
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function clampCellAddress(address: BGridCellAddress, rowCount: number, columnCount: number): BGridCellAddress;
+export declare function getColumnLeft(columnIndex: number, columns: AppModelColumn<any>[]): number;
+export declare function getColumnRight(columnIndex: number, columns: AppModelColumn<any>[]): number;
+export declare function getRowTop(rowIndex: number, rowHeight: number): number;
+export declare function getRowBottom(rowIndex: number, rowHeight: number): number;
+export interface EnsureCellVisibleParams {
+    cell: BGridCellAddress;
+    scrollContainer: HTMLElement | null;
+    frozenColumnCount?: number;
+    frozenRowCount?: number;
+    columns: AppModelColumn<any>[];
+    rowHeight: number;
+    viewportInsets?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+}
+export interface EnsureCellVisibleResult {
+    scrollTop: number;
+    scrollLeft: number;
+    didScroll: boolean;
+    didScrollTop: boolean;
+    didScrollLeft: boolean;
+}
+export declare function ensureCellVisible({ cell, scrollContainer, frozenColumnCount, frozenRowCount, columns, rowHeight, viewportInsets, }: EnsureCellVisibleParams): EnsureCellVisibleResult;

package/types/utils/createPivotData.d.ts

@@ -0,0 +1,12 @@
+import { BGridColumnGroup, BGridColumnWithOptionalWidth, BGridDataItem, BGridPivotOptions } from '../types';
+interface CreatePivotDataParams<T> {
+    data: BGridDataItem<T>[];
+    pivot?: BGridPivotOptions<T>;
+}
+export interface PivotDataResult {
+    data: BGridDataItem<Record<string, any>>[];
+    columns: BGridColumnWithOptionalWidth<Record<string, any>>[];
+    columnsGroup: BGridColumnGroup[];
+}
+export declare function createPivotData<T>({ data, pivot }: CreatePivotDataParams<T>): PivotDataResult | undefined;
+export {};

package/types/utils/delay.d.ts

@@ -0,0 +1 @@
+export declare const delay: <T>(ms: number, result?: T) => Promise<T>;

package/types/utils/filterData.d.ts

@@ -0,0 +1,18 @@
+import { BGridColumn, BGridDataItem, BGridFilterParam } from '../types';
+/**
+ * Normalizes a raw cell value for values-based filtering.
+ * undefined is normalized to null and Date is serialized to an ISO string so
+ * values-filter candidates and row comparisons share the public primitive type.
+ */
+export declare function normalizeValueForFilter(value: unknown): unknown;
+/**
+ * Evaluates whether a single row matches the filter condition for a column.
+ */
+export declare function matchColumnFilter<T>(item: BGridDataItem<T>, column: BGridColumn<T>, filter: BGridFilterParam): boolean;
+/**
+ * Filters rows against all active filter parameters (AND combination).
+ */
+export declare function filterRows<T>(data: BGridDataItem<T>[], columns: BGridColumn<T>[], filterParams: BGridFilterParam[]): {
+    item: BGridDataItem<T>;
+    sourceIndex: number;
+}[];

package/types/utils/getCellSelectionAxisState.d.ts

@@ -0,0 +1,12 @@
+import { BGridCellAddress, BGridCellSelectionRange } from '../types';
+export interface BGridCellSelectionAxisState {
+    rowIndexes: Set<number>;
+    columnIndexes: Set<number>;
+}
+/**
+ * Collects the row and column indexes represented by the active cell and every
+ * selection range. The returned sets are shared by the header and line-number
+ * renderers so frozen and scrollable regions use identical selection semantics.
+ */
+export declare function getCellSelectionAxisState(activeCell: BGridCellAddress | undefined, ranges: BGridCellSelectionRange[]): BGridCellSelectionAxisState;
+export declare function isColumnAxisRangeActive(columnIndexes: Set<number>, startColumnIndex: number, columnSpan?: number): boolean;

package/types/utils/getCellValue.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare function getCellValueByRowKey<T>(rowKey: React.Key | React.Key[], values: T): any;

package/types/utils/getColumnId.d.ts

@@ -0,0 +1,19 @@
+import { BGridColumn } from '../types';
+/**
+ * Returns a stable identifier for the data field referenced by a column.
+ * Unlike getColumnId, explicit column ids do not affect this token, so columns
+ * that render the same key share the same value-change identity.
+ */
+export declare function getColumnKeyToken<T>(key: BGridColumn<T>['key']): string;
+/**
+ * Returns a stable unique column identifier.
+ * If column.id is explicitly provided, it is returned as is.
+ * Otherwise, column.key is serialized in a conflict-free manner.
+ */
+export declare function getColumnId<T>(column: BGridColumn<T>): string;
+/**
+ * Checks for duplicate column IDs in development mode.
+ * If onlyToolbox is true, only returns duplicates among toolbox-enabled columns.
+ * Returns a Set of duplicated IDs if any.
+ */
+export declare function findDuplicateColumnIds<T>(columns: BGridColumn<T>[], onlyToolbox?: boolean): Set<string>;

package/types/utils/getFrozenColumnsWidth.d.ts

@@ -0,0 +1,12 @@
+import { BGridColumn, BGridRowChecked } from '../types';
+interface Props<T> {
+    showLineNumber?: boolean;
+    rowChecked?: BGridRowChecked<T>;
+    itemHeight: number;
+    frozenColumnIndex: number;
+    columns: BGridColumn<T>[];
+    dataLength: number;
+    reorderable?: boolean;
+}
+export declare function getFrozenColumnsWidth<T>({ showLineNumber, rowChecked, itemHeight, frozenColumnIndex, columns, dataLength, reorderable, }: Props<T>): number;
+export {};

package/types/utils/getLineNumber.d.ts

@@ -0,0 +1,6 @@
+interface Props {
+    dataLength: number;
+    reorderable?: boolean;
+}
+export declare function getLineNumberWidth({ dataLength, reorderable }: Props): number;
+export {};

package/types/utils/getVisibleScrollableRowRange.d.ts

@@ -0,0 +1,20 @@
+export interface VisibleScrollableRowRangeParams {
+    scrollTop: number;
+    viewportHeight: number;
+    rowHeight: number;
+    frozenRowCount: number;
+    totalRowCount: number;
+    overscan?: number;
+    windowSize?: number;
+}
+export interface VisibleScrollableRowRange {
+    startRowIndex: number;
+    endRowIndex: number;
+    paddingTop: number;
+    scrollContentHeight: number;
+}
+/**
+ * Maps the scrollable body's physical scroll offset to logical data row indexes.
+ * The returned end index is exclusive.
+ */
+export declare function getVisibleScrollableRowRange({ scrollTop, viewportHeight, rowHeight, frozenRowCount, totalRowCount, overscan, windowSize, }: VisibleScrollableRowRangeParams): VisibleScrollableRowRange;

package/types/utils/gridSearch.d.ts

@@ -0,0 +1,18 @@
+import type * as React from 'react';
+import { AppModelColumn, BGridDataItem, BGridProps, BGridSearchMatch, BGridSearchOptions } from '../types';
+export declare function normalizeSearchText(value: unknown): string;
+export interface FindGridSearchMatchesParams<T> {
+    data: BGridDataItem<T>[];
+    columns: AppModelColumn<T>[];
+    sourceIndexByVisibleIndex: number[];
+    rowKey?: React.Key | React.Key[];
+    cellMergeOptions?: BGridProps<T>['cellMergeOptions'];
+    searchOptions?: BGridSearchOptions<T>;
+    query: string;
+    startRowIndex?: number;
+    endRowIndex?: number;
+    onGetSearchTextError?: (columnId: string, error: unknown) => void;
+}
+export declare function findGridSearchMatches<T>({ data, columns, sourceIndexByVisibleIndex, rowKey, cellMergeOptions, searchOptions, query, startRowIndex, endRowIndex, onGetSearchTextError, }: FindGridSearchMatchesParams<T>): BGridSearchMatch[];
+export declare function dedupeSearchMatches(matches: BGridSearchMatch[]): BGridSearchMatch[];
+export declare function findMatchingSearchResultIndex(matches: BGridSearchMatch[], previous?: BGridSearchMatch, previousIndex?: number): number | undefined;

package/types/utils/index.d.ts

@@ -0,0 +1,23 @@
+export * from './getCellValue';
+export * from './getFrozenColumnsWidth';
+export * from './mouseEventSubscribe';
+export * from './common';
+export * from './useForceUpdate';
+export * from './delay';
+export * from './getLineNumber';
+export * from './useBodyData';
+export * from './createPivotData';
+export * from './getColumnId';
+export * from './updateDataQuery';
+export * from './filterData';
+export * from './processDataQuery';
+export * from './scrollbar';
+export * from './number';
+export * from './buildHeaderMatrix';
+export * from './getVisibleScrollableRowRange';
+export * from './cellEditState';
+export * from './getCellSelectionAxisState';
+export * from './mergedCells';
+export * from './gridSearch';
+export * from './cellEditTransaction';
+export * from './rowReorder';

package/types/utils/mergedCells.d.ts

@@ -0,0 +1,14 @@
+import { BGridCellAddress, BGridDataItem, BGridProps } from '../types';
+export interface BGridMergedRowRange {
+    startRowIndex: number;
+    endRowIndex: number;
+}
+export interface BGridLogicalCell {
+    cell: BGridCellAddress;
+    rowRange: BGridMergedRowRange;
+    rowIndexes: number[];
+    merged: boolean;
+}
+export declare function getMergedRowRange<T>(data: BGridDataItem<T>[], mergeBy: string | string[], requestedRowIndex: number): BGridMergedRowRange;
+export declare function resolveLogicalCell<T>(data: BGridDataItem<T>[], cellMergeOptions: BGridProps<T>['cellMergeOptions'], requestedCell: BGridCellAddress): BGridLogicalCell;
+export declare function isRowInLogicalCell(logicalCell: BGridLogicalCell, rowIndex: number): boolean;

package/types/utils/mouseEventSubscribe.d.ts

@@ -0,0 +1,18 @@
+export interface IMousePosition {
+    pageX: number;
+    pageY: number;
+    clientX: number;
+    clientY: number;
+}
+export type MouseEventSubscribeCallbackFn = (mousePosition: IMousePosition, stopEvent: () => void) => void;
+export interface IMouseEventSubscribeOptions {
+    interval?: number;
+    target?: EventTarget & {
+        ownerDocument?: Document;
+        setPointerCapture?: (pointerId: number) => void;
+        releasePointerCapture?: (pointerId: number) => void;
+    };
+    pointerId?: number;
+    initialClientX?: number;
+}
+export declare const mouseEventSubscribe: (callBack: MouseEventSubscribeCallbackFn, onEnd?: () => void, options?: IMouseEventSubscribeOptions) => void;

package/types/utils/number/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./toFixed";
+export * from "./toMoney";
+export * from "./toNumber";

package/types/utils/number/toFixed.d.ts

@@ -0,0 +1 @@
+export declare function toFixed(value: number): number;

package/types/utils/number/toMoney.d.ts

@@ -0,0 +1 @@
+export declare function toMoney(value: unknown): string;

package/types/utils/number/toNumber.d.ts

@@ -0,0 +1 @@
+export declare function toNumber(value: unknown): number;

package/types/utils/processDataQuery.d.ts

@@ -0,0 +1,19 @@
+import { BGridColumn, BGridDataItem, BGridDataQuery, BGridProcessedRow, BGridProps } from '../types';
+export interface BGridProcessDataQueryParams<T> {
+    data: BGridDataItem<T>[];
+    columns: BGridColumn<T>[];
+    query: BGridDataQuery;
+    rowKey?: BGridProps<T>['rowKey'];
+    /** Skip BGridProcessedRow metadata when the caller only needs data and index mappings. */
+    includeRows?: boolean;
+}
+export interface BGridProcessDataQueryResult<T> {
+    rows: BGridProcessedRow<T>[];
+    data: BGridDataItem<T>[];
+    sourceIndexByVisibleIndex: number[];
+    visibleIndexBySourceIndex: Map<number, number>;
+}
+/**
+ * Pure data processing pipeline: filter then stable multi-sort.
+ */
+export declare function processDataQuery<T>(params: BGridProcessDataQueryParams<T>): BGridProcessDataQueryResult<T>;

package/types/utils/rowReorder.d.ts

@@ -0,0 +1,24 @@
+import { BGridDataItem } from '../types';
+export type BGridRowReorderPhase = 'dragging' | 'settling' | 'cancelling';
+export type BGridRowReorderRole = 'source' | 'shift' | 'target' | undefined;
+export declare function moveRowItem<T>(items: readonly BGridDataItem<T>[], fromIndex: number, toIndex: number): BGridDataItem<T>[];
+export declare function remapRowIndex(index: number, fromIndex: number, toIndex: number): number;
+export declare function remapCheckedIndexesMap(checkedIndexesMap: ReadonlyMap<number, any>, fromIndex: number, toIndex: number): Map<number, any>;
+export declare function getRowReorderTargetIndex(params: {
+    fromIndex: number;
+    pointerOffsetY: number;
+    rowHeight: number;
+    rowCount: number;
+}): number;
+export declare function getRowReorderOffset(params: {
+    rowIndex: number;
+    fromIndex: number;
+    toIndex: number;
+    rowHeight: number;
+}): number;
+export declare function getRowReorderRole(params: {
+    rowIndex: number;
+    fromIndex: number;
+    toIndex: number;
+}): BGridRowReorderRole;
+export declare function getMaxTransitionTimeMs(style: Pick<CSSStyleDeclaration, 'transitionDelay' | 'transitionDuration'>): number;

package/types/utils/scrollbar.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { BGridPaginationViewOptions, BGridResolvedPaginationViewOptions, BGridResolvedScrollbarOptions, BGridResolvedStatusOptions, BGridScrollbarOptions, BGridStatusOptions, BGridStatusContent, BGridStatusContext } from '../types';
+export declare function resolveStatusOptions(options?: BGridStatusOptions): BGridResolvedStatusOptions;
+export declare function resolvePaginationViewOptions(options?: BGridPaginationViewOptions): BGridResolvedPaginationViewOptions;
+export declare function resolveScrollbarOptions(options: BGridScrollbarOptions | undefined): BGridResolvedScrollbarOptions;
+export declare function shouldRenderBottomBar(params: {
+    hasPage: boolean;
+    hasHorizontalOverflow?: boolean;
+    scrollbar: BGridResolvedScrollbarOptions;
+    status: BGridResolvedStatusOptions;
+    pagination: BGridResolvedPaginationViewOptions;
+}): boolean;
+export declare function resolveStatusContent(content: BGridStatusContent | undefined, context: BGridStatusContext): React.ReactNode;

package/types/utils/updateDataQuery.d.ts

@@ -0,0 +1,28 @@
+import { BGridDataQuery, BGridFilterParam, BGridSortParam } from '../types';
+/**
+ * Checks if a filter parameter has a valid, non-empty condition.
+ */
+export declare function isFilterParamActive(filter: BGridFilterParam | undefined | null): filter is BGridFilterParam;
+/**
+ * Normalizes a text filter by trimming whitespace.
+ */
+export declare function normalizeFilterParam(filter: BGridFilterParam): BGridFilterParam | null;
+/**
+ * Creates an immutable updated query while keeping sort and filter params sanitized.
+ */
+export declare function updateDataQuery(current: BGridDataQuery, updater: (draft: {
+    sortParams: BGridSortParam[];
+    filterParams: BGridFilterParam[];
+}) => void): BGridDataQuery;
+/**
+ * Sets or clears column sort on the query.
+ */
+export declare function applySortToQuery(query: BGridDataQuery, columnId: string, key: string | string[] | undefined, order: 'asc' | 'desc' | null, multiSort?: boolean): BGridDataQuery;
+/**
+ * Sets or updates column filter on the query.
+ */
+export declare function applyFilterToQuery(query: BGridDataQuery, filter: BGridFilterParam): BGridDataQuery;
+/**
+ * Clears column filter from the query.
+ */
+export declare function clearFilterFromQuery(query: BGridDataQuery, columnId: string): BGridDataQuery;

package/types/utils/useBodyData.d.ts

@@ -0,0 +1,9 @@
+import { BGridColumn, BGridDataItem, MoveDirection } from '../types';
+export declare function useBodyData(startIdx: number, endNumber: number, data: BGridDataItem<any>[]): {
+    dataSet: BGridDataItem<any>[];
+    setItemValue: (_ri: number, _ci: number, column: BGridColumn<any>, newValue: any) => Promise<void>;
+    handleMoveEditFocus: (rowIndex: number, columnIndex: number, columnDirection?: MoveDirection, rowDirection?: MoveDirection) => Promise<void>;
+    handleChangeChecked: (index: number, checked: boolean) => Promise<void>;
+    handleChangeCheckedRadio: (index: number) => Promise<void>;
+    getRowSpan: (rowIndex: number, columnIndex: number) => number;
+};

package/types/utils/useForceUpdate.d.ts

@@ -0,0 +1 @@
+export declare function useForceUpdate(): () => void;

package/types/utils/useRowReorderController.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+export interface BGridRowReorderPreviewState {
+    text: string;
+    visible: boolean;
+    phase: 'dragging' | 'settling' | 'cancelling';
+}
+interface UseRowReorderControllerParams {
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    bodyContainerRef: React.RefObject<HTMLDivElement | null>;
+    scrollContainerRef: React.RefObject<HTMLDivElement | null>;
+    rowHeight: number;
+}
+export declare function useRowReorderController<T>({ containerRef, bodyContainerRef, scrollContainerRef, rowHeight, }: UseRowReorderControllerParams): {
+    announcement: string;
+    onKeyDown: (event: React.KeyboardEvent<HTMLButtonElement>, rowIndex: number) => void;
+    onPointerDown: (event: React.PointerEvent<HTMLButtonElement>, rowIndex: number) => void;
+    preview: BGridRowReorderPreviewState | undefined;
+};
+export {};