@gridstorm/react 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,405 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ComponentType, ReactNode, Component, ErrorInfo } from 'react';
+import { ColumnState, GridApi, RowNode, ColumnDef, CellPosition, SortModelItem, FilterModel, SelectionSource, GridConfig, GridEventMap, SortDirection, GridEngine, GridState, PinnedPosition } from '@gridstorm/core';
+export { CellEditorDef, CellPosition, ColumnDef, ColumnState, EditingState, FilterModel, GridApi, GridConfig, GridEventMap, GridPlugin, GridState, PinnedPosition, RowNode, SelectionState, SortDirection, SortModelItem } from '@gridstorm/core';
+
+/** Props passed to React cell renderer components. */
+interface CellRendererProps<TData = any, TValue = any> {
+    /** The cell's current value (after valueGetter). */
+    value: TValue;
+    /** The formatted display value (after valueFormatter). */
+    formattedValue: string;
+    /** The row data object. */
+    data: TData | undefined;
+    /** The RowNode for this row. */
+    node: RowNode<TData>;
+    /** Column definition. */
+    colDef: ColumnDef<TData, TValue>;
+    /** Column ID. */
+    colId: string;
+    /** Display row index. */
+    rowIndex: number;
+    /** Grid API reference. */
+    api: GridApi<TData>;
+}
+/** A React component used as a cell renderer. */
+type ReactCellRenderer<TData = any, TValue = any> = ComponentType<CellRendererProps<TData, TValue>>;
+/** Props passed to React header renderer components. */
+interface HeaderRendererProps<TData = any> {
+    /** Column definition. */
+    colDef: ColumnDef<TData>;
+    /** Column ID. */
+    colId: string;
+    /** Display name for the header. */
+    displayName: string;
+    /** Current sort direction for this column. */
+    sortDirection: SortDirection;
+    /** Sort priority index (for multi-sort). */
+    sortIndex: number | null;
+    /** Grid API reference. */
+    api: GridApi<TData>;
+    /** Function to request sort toggle. */
+    onSortRequested: (multiSort: boolean) => void;
+}
+/** A React component used as a header renderer. */
+type ReactHeaderRenderer<TData = any> = ComponentType<HeaderRendererProps<TData>>;
+/** Props passed to React cell editor components. */
+interface CellEditorProps<TData = any, TValue = any> {
+    /** Current cell value. */
+    value: TValue;
+    /** Row data. */
+    data: TData;
+    /** Column ID. */
+    colId: string;
+    /** Row ID. */
+    rowId: string;
+    /** Column state. */
+    column: ColumnState;
+    /** Additional editor params from column def. */
+    editorParams: Record<string, unknown>;
+    /** Callback to update the value while editing. */
+    onValueChange: (value: TValue) => void;
+    /** Callback to stop editing. */
+    stopEditing: (cancel?: boolean) => void;
+    /** Grid API reference. */
+    api: GridApi<TData>;
+}
+/** A React component used as a cell editor. */
+type ReactCellEditor<TData = any, TValue = any> = ComponentType<CellEditorProps<TData, TValue>>;
+/** Props passed to a context menu component. */
+interface ContextMenuProps<TData = any> {
+    /** The cell position that was right-clicked. */
+    position: CellPosition;
+    /** The row node. */
+    node: RowNode<TData>;
+    /** Column ID. */
+    colId: string;
+    /** Cell value. */
+    value: any;
+    /** Grid API. */
+    api: GridApi<TData>;
+    /** Close the menu. */
+    closeMenu: () => void;
+}
+/** A React component used as a context menu. */
+type ReactContextMenu<TData = any> = ComponentType<ContextMenuProps<TData>>;
+/**
+ * Column definition that supports React component renderers.
+ * Extends the core ColumnDef to accept React components for
+ * cellRenderer, headerRenderer, and cellEditorComponent.
+ */
+interface ReactColumnDef<TData = any, TValue = any> extends Omit<ColumnDef<TData, TValue>, 'cellRenderer' | 'headerRenderer'> {
+    /** Original string/HTMLElement renderer OR React component. */
+    cellRenderer?: ColumnDef<TData, TValue>['cellRenderer'] | ReactCellRenderer<TData, TValue>;
+    /** Original string/HTMLElement header renderer OR React component. */
+    headerRenderer?: ColumnDef<TData>['headerRenderer'] | ReactHeaderRenderer<TData>;
+    /** React component cell editor (alternative to cellEditor string name). */
+    cellEditorComponent?: ReactCellEditor<TData, TValue>;
+}
+/** Props for controlled mode — parent owns state. */
+interface ControlledStateProps<_TData = any> {
+    /** Controlled sort model. When provided, grid won't update sort internally. */
+    sortModel?: SortModelItem[];
+    /** Called when user tries to change sort (controlled mode). */
+    onSortModelChange?: (sortModel: SortModelItem[]) => void;
+    /** Controlled filter model. */
+    filterModel?: Record<string, FilterModel>;
+    /** Called when user tries to change filters. */
+    onFilterModelChange?: (filterModel: Record<string, FilterModel>) => void;
+    /** Controlled selection (set of row IDs). */
+    selectedRowIds?: Set<string>;
+    /** Called when user tries to change selection. */
+    onSelectedRowIdsChange?: (selectedRowIds: Set<string>, source: SelectionSource) => void;
+    /** Controlled pagination page. */
+    currentPage?: number;
+    /** Called when user tries to change page. */
+    onCurrentPageChange?: (page: number) => void;
+}
+/** All supported event callback props for the GridStorm component. */
+interface GridStormEventProps<TData = any> {
+    onGridReady?: (api: GridApi<TData>) => void;
+    onRowDataChanged?: (event: GridEventMap<TData>['rowData:changed']) => void;
+    onSelectionChanged?: (event: GridEventMap<TData>['selection:changed']) => void;
+    onSortChanged?: (event: GridEventMap<TData>['column:sort:changed']) => void;
+    onFilterChanged?: (event: GridEventMap<TData>['filter:changed']) => void;
+    onCellValueChanged?: (event: GridEventMap<TData>['cell:valueChanged']) => void;
+    onCellClicked?: (event: GridEventMap<TData>['cell:clicked']) => void;
+    onCellDoubleClicked?: (event: GridEventMap<TData>['cell:doubleClicked']) => void;
+    onRowClicked?: (event: GridEventMap<TData>['row:clicked']) => void;
+    onCellEditingStarted?: (event: GridEventMap<TData>['cell:editingStarted']) => void;
+    onCellEditingStopped?: (event: GridEventMap<TData>['cell:editingStopped']) => void;
+    onPaginationChanged?: (event: GridEventMap<TData>['pagination:changed']) => void;
+    onColumnResized?: (event: GridEventMap<TData>['column:resized']) => void;
+}
+/** Options forwarded to the DomRenderer for Tier 1 feature rendering. */
+interface RendererConfigProps {
+    /** Enable inline cell editing overlay. Default: auto-detect EditingPlugin. */
+    enableCellEditing?: boolean;
+    /** Enable row grouping visual (chevron, indent, group label). Default: auto-detect GroupingPlugin. */
+    enableGrouping?: boolean;
+    /** Indentation per group level in pixels. Default: 24. */
+    groupIndent?: number;
+    /** Show checkbox selection column as the first column. Default: false. */
+    checkboxSelection?: boolean;
+    /** Width of the checkbox column in pixels. Default: 48. */
+    checkboxColumnWidth?: number;
+    /** Show floating filter inputs below the header. Default: false. */
+    floatingFilter?: boolean;
+    /** Debounce delay for filter input in ms. Default: 300. */
+    floatingFilterDebounce?: number;
+    /** Show pagination bar below the grid. Default: auto-detect PaginationPlugin. */
+    enablePagination?: boolean;
+    /** Available page size options for the page size selector. Default: [25, 50, 100, 250]. */
+    pageSizeOptions?: number[];
+}
+/** Full props interface for the <GridStorm> component. */
+interface GridStormProps<TData = any> extends Omit<GridConfig<TData>, 'columns' | 'onGridReady' | 'onRowDataChanged' | 'onSelectionChanged' | 'onSortChanged' | 'onFilterChanged' | 'onCellValueChanged'>, ControlledStateProps<TData>, GridStormEventProps<TData>, RendererConfigProps {
+    /** Column definitions (supports React component renderers). */
+    columns: ReactColumnDef<TData>[];
+    /** Container height. Default: 400. */
+    height?: number | string;
+    /** Container width. Default: '100%'. */
+    width?: number | string;
+    /** Additional CSS class for the container. */
+    containerClass?: string;
+    /** Additional inline styles for the container. */
+    containerStyle?: React.CSSProperties;
+    /** Custom context menu component. */
+    contextMenu?: ReactContextMenu<TData>;
+    /** Children (rendered for context consumers). */
+    children?: ReactNode;
+}
+
+declare function GridStorm<TData = any>(props: GridStormProps<TData>): react_jsx_runtime.JSX.Element;
+
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+declare class GridErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    state: ErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): ReactNode;
+}
+
+interface GridContextValue<TData = any> {
+    engine: GridEngine<TData>;
+    api: GridApi<TData>;
+    /** The root DOM element (.gs-root) of the grid. */
+    rootElement: HTMLElement | null;
+}
+declare const GridContext: react.Context<GridContextValue<any> | null>;
+/**
+ * Internal helper — gets grid context with null-check.
+ * All public hooks use this internally.
+ */
+declare function useGridContext<TData = any>(): GridContextValue<TData>;
+
+/**
+ * Access the GridApi instance.
+ * Must be used within a `<GridStorm>` component.
+ */
+declare function useGridApi<TData = any>(): GridApi<TData>;
+
+/**
+ * Subscribe to grid state changes with a selector.
+ * Re-renders only when the selected value changes (reference equality).
+ *
+ * @example
+ * ```tsx
+ * const rowCount = useGridState(state => state.displayedRowIds.length);
+ * const sortModel = useGridState(state => state.sortModel);
+ * ```
+ */
+declare function useGridState<TData = any, TResult = any>(selector: (state: GridState<TData>) => TResult): TResult;
+
+interface GridSelectionResult<TData = any> {
+    /** Set of selected row IDs. */
+    selectedRowIds: Set<string>;
+    /** Number of selected rows. */
+    selectedCount: number;
+    /** Get selected row data objects. */
+    getSelectedRows: () => TData[];
+    /** Get selected RowNode objects. */
+    getSelectedNodes: () => RowNode<TData>[];
+    /** Check if a specific row is selected. */
+    isRowSelected: (rowId: string) => boolean;
+    /** Select all visible rows. */
+    selectAll: () => void;
+    /** Deselect all rows. */
+    deselectAll: () => void;
+}
+/**
+ * Access selection state and actions.
+ *
+ * @example
+ * ```tsx
+ * const { selectedCount, selectAll, deselectAll, isRowSelected } = useGridSelection();
+ * ```
+ */
+declare function useGridSelection<TData = any>(): GridSelectionResult<TData>;
+
+interface GridSortResult {
+    /** Current sort model. */
+    sortModel: SortModelItem[];
+    /** Whether any sort is active. */
+    isSorted: boolean;
+    /** Set the sort model directly. */
+    setSortModel: (model: SortModelItem[]) => void;
+    /** Toggle sort on a column. */
+    toggleSort: (colId: string, multiSort?: boolean) => void;
+    /** Clear all sort. */
+    clearSort: () => void;
+}
+/**
+ * Access sort state and actions.
+ *
+ * @example
+ * ```tsx
+ * const { sortModel, isSorted, toggleSort, clearSort } = useGridSort();
+ * ```
+ */
+declare function useGridSort(): GridSortResult;
+
+interface GridFilterResult {
+    /** Current filter model (keyed by column ID). */
+    filterModel: Record<string, FilterModel>;
+    /** Current quick filter text. */
+    quickFilterText: string;
+    /** Whether any filter is active. */
+    isFiltered: boolean;
+    /** Set the filter model. */
+    setFilterModel: (model: Record<string, FilterModel>) => void;
+    /** Set quick filter text. */
+    setQuickFilter: (text: string) => void;
+    /** Clear all filters. */
+    clearFilters: () => void;
+}
+/**
+ * Access filter state and actions.
+ *
+ * @example
+ * ```tsx
+ * const { isFiltered, setQuickFilter, clearFilters } = useGridFilter();
+ * ```
+ */
+declare function useGridFilter(): GridFilterResult;
+
+interface GridPaginationResult {
+    /** Current page (0-indexed). */
+    currentPage: number;
+    /** Total number of pages. */
+    totalPages: number;
+    /** Rows per page. */
+    pageSize: number;
+    /** Total row count (after filtering). */
+    totalRows: number;
+    /** Is there a next page? */
+    hasNextPage: boolean;
+    /** Is there a previous page? */
+    hasPreviousPage: boolean;
+    /** Go to a specific page. */
+    goToPage: (page: number) => void;
+    /** Go to next page. */
+    nextPage: () => void;
+    /** Go to previous page. */
+    previousPage: () => void;
+    /** Go to first page. */
+    firstPage: () => void;
+    /** Go to last page. */
+    lastPage: () => void;
+}
+/**
+ * Access pagination state and actions.
+ *
+ * @example
+ * ```tsx
+ * const { currentPage, totalPages, nextPage, previousPage } = useGridPagination();
+ * ```
+ */
+declare function useGridPagination(): GridPaginationResult;
+
+/**
+ * Subscribe to a specific grid event.
+ * Handler ref prevents stale closures without re-subscribing.
+ *
+ * @example
+ * ```tsx
+ * useGridEvent('cell:clicked', (event) => {
+ *   console.log('Clicked cell:', event.colId, event.value);
+ * });
+ * ```
+ */
+declare function useGridEvent<TData = any, K extends keyof GridEventMap<TData> = any>(event: K, handler: (payload: GridEventMap<TData>[K]) => void): void;
+
+interface GridColumnResult {
+    /** All columns (including hidden). */
+    allColumns: ColumnState[];
+    /** Only visible columns. */
+    visibleColumns: ColumnState[];
+    /** Set a column's visibility. */
+    setColumnVisible: (colId: string, visible: boolean) => void;
+    /** Set a column's width. */
+    setColumnWidth: (colId: string, width: number) => void;
+    /** Move a column to a new index. */
+    moveColumn: (colId: string, toIndex: number) => void;
+    /** Pin a column. */
+    setColumnPinned: (colId: string, pinned: PinnedPosition) => void;
+    /** Get a single column by ID. */
+    getColumn: (colId: string) => ColumnState | undefined;
+}
+/**
+ * Access column state and actions.
+ *
+ * @example
+ * ```tsx
+ * const { visibleColumns, setColumnVisible, setColumnWidth } = useGridColumn();
+ * ```
+ */
+declare function useGridColumn(): GridColumnResult;
+
+/**
+ * Wrap a React component to use as a cell renderer.
+ *
+ * @example
+ * ```tsx
+ * const StatusCell = ({ value }: CellRendererProps) => (
+ *   <span className={value ? 'active' : 'inactive'}>{value ? 'Yes' : 'No'}</span>
+ * );
+ *
+ * const columns = [
+ *   { field: 'active', cellRenderer: reactCellRenderer(StatusCell) },
+ * ];
+ * ```
+ */
+declare function reactCellRenderer<TData = any, TValue = any>(Component: ReactCellRenderer<TData, TValue>): any;
+/** Check if a cellRenderer is a wrapped React component. */
+declare function isReactCellRenderer(fn: unknown): boolean;
+
+/**
+ * Wrap a React component to use as a header renderer.
+ *
+ * @example
+ * ```tsx
+ * const SortHeader = ({ displayName, sortDirection, onSortRequested }: HeaderRendererProps) => (
+ *   <div onClick={() => onSortRequested(false)}>
+ *     {displayName} {sortDirection === 'asc' ? '▲' : sortDirection === 'desc' ? '▼' : ''}
+ *   </div>
+ * );
+ *
+ * const columns = [
+ *   { field: 'name', headerRenderer: reactHeaderRenderer(SortHeader) },
+ * ];
+ * ```
+ */
+declare function reactHeaderRenderer<TData = any>(Component: ReactHeaderRenderer<TData>): any;
+/** Check if a headerRenderer is a wrapped React component. */
+declare function isReactHeaderRenderer(fn: unknown): boolean;
+
+export { type CellEditorProps, type CellRendererProps, type ContextMenuProps, type ControlledStateProps, GridContext, type GridContextValue, GridErrorBoundary, GridStorm, type GridStormEventProps, type GridStormProps, type HeaderRendererProps, type ReactCellEditor, type ReactCellRenderer, type ReactColumnDef, type ReactContextMenu, type ReactHeaderRenderer, type RendererConfigProps, isReactCellRenderer, isReactHeaderRenderer, reactCellRenderer, reactHeaderRenderer, useGridApi, useGridColumn, useGridContext, useGridEvent, useGridFilter, useGridPagination, useGridSelection, useGridSort, useGridState };