react-open-source-grid 1.5.0 → 1.5.1

package/dist/assets/components/AccessibilityDemo.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AccessibilityDemo.tsx
+ *
+ * Comprehensive demonstration of DataGrid accessibility features
+ * including keyboard navigation, ARIA support, and screen reader compatibility.
+ */
+import React from 'react';
+export declare const AccessibilityDemo: React.FC;

package/dist/assets/components/ApiReferencePage.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare const ApiReferencePage: React.FC;

package/dist/assets/components/BenchmarkDemo.d.ts

@@ -0,0 +1,2 @@
+export declare const BenchmarkDemo: () => import("react/jsx-runtime").JSX.Element;
+export default BenchmarkDemo;

package/dist/assets/components/CellRenderersDemo.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+/**
+ * CellRenderersDemo - Showcase of Custom Cell Renderer Framework
+ *
+ * This demo demonstrates all available custom cell renderers:
+ * - StatusChip: Color-coded status badges
+ * - ProgressBar: Visual progress indicators
+ * - IconCell: Cells with icons
+ * - ImageCell: Cells with images/avatars
+ * - ButtonCell: Actionable buttons
+ * - BadgeCell: Generic badge component
+ * - PriorityIndicator: Priority levels
+ * - Rating: Star ratings
+ * - CurrencyCell: Formatted currency values
+ */
+export declare const CellRenderersDemo: React.FC;

package/dist/assets/components/CodeBlock.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+interface CodeBlockProps {
+    code: string;
+    language?: string;
+    title?: string;
+    showLineNumbers?: boolean;
+    maxHeight?: string;
+}
+export declare const CodeBlock: React.FC<CodeBlockProps>;
+export default CodeBlock;

package/dist/assets/components/ColumnFiltersDemo.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+/**
+ * Demo component showcasing the Column Filters feature
+ */
+export declare const ColumnFiltersDemo: React.FC;

package/dist/assets/components/CompleteApiReferencePage.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare const CompleteApiReferencePage: React.FC;

package/dist/assets/components/ContextMenuDemo.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+/**
+ * ContextMenuDemo Component
+ *
+ * Demonstrates the context menu feature with:
+ * - Right-click on cells: Copy, Copy with Headers, Export Selected Range, Filter by Value
+ * - Right-click on headers: Pin/Unpin, Auto-size, Resize to Fit, Hide Column, Filter by Value
+ * - Custom menu items
+ * - Enable/disable context menu options
+ */
+export declare const ContextMenuDemo: React.FC;
+export default ContextMenuDemo;

package/dist/assets/components/DataGrid/ARCHITECTURE.md.d.ts

@@ -0,0 +1,288 @@
+/**
+ * COMPONENT ARCHITECTURE GUIDE
+ *
+ * This document explains the internal design and architecture of the DataGrid component.
+ */
+/**
+ * The DataGrid uses useReducer for centralized state management.
+ * This provides several benefits:
+ * - Single source of truth for all grid state
+ * - Predictable state updates through actions
+ * - Easier debugging and testing
+ * - Better performance (fewer re-renders)
+ *
+ * State Structure:
+ * - columns: Column configuration
+ * - sortConfig: Current sort field and direction
+ * - filterConfig: Filter values for each column
+ * - currentPage: Active page number (0-indexed)
+ * - pageSize: Rows per page
+ * - selection: Selected row IDs and tracking
+ * - editState: Currently editing cell info
+ * - focusState: Keyboard focus position
+ * - columnOrder: Display order of columns
+ * - columnWidths: Width of each column in pixels
+ */
+/**
+ * Data flows through the component in the following order:
+ *
+ * Raw Data (props.rows)
+ *    ↓
+ * Apply Sorting (sortedRows)
+ *    ↓
+ * Apply Filtering (filteredRows)
+ *    ↓
+ * Apply Pagination (paginatedRows)
+ *    ↓
+ * Render in GridBody
+ *
+ * Each transformation is done with useMemo for performance optimization.
+ * The transformations only recalculate when their dependencies change.
+ */
+/**
+ * DataGrid (Parent)
+ *   │
+ *   ├── GridHeader
+ *   │     ├── Column Headers (sortable, draggable)
+ *   │     ├── Column Resizers
+ *   │     └── Filter Inputs
+ *   │
+ *   ├── GridBody
+ *   │     └── Rows
+ *   │           └── Cells (editable, focusable, selectable)
+ *   │
+ *   └── GridPagination
+ *         ├── Page Size Selector
+ *         ├── Row Count Info
+ *         └── Page Navigation Buttons
+ */
+/**
+ * A) Compound Component Pattern
+ * - Main DataGrid orchestrates sub-components
+ * - Each sub-component has a specific responsibility
+ * - State and dispatch are passed down as props
+ *
+ * B) Reducer Pattern
+ * - All state updates go through the reducer
+ * - Actions are dispatched from child components
+ * - Reducer handles state transitions
+ *
+ * C) Controlled Components
+ * - Parent component (DataGrid) owns the data
+ * - Child components receive data and callbacks
+ * - Edits are communicated back via callbacks
+ *
+ * D) Memoization Strategy
+ * - useMemo for expensive computations (sorting, filtering)
+ * - useCallback for event handlers passed to children
+ * - Prevents unnecessary re-renders
+ */
+/**
+ * Column resizing uses a custom implementation:
+ *
+ * 1. Each column has a resize handle (1px div at right edge)
+ * 2. On mousedown:
+ *    - Store starting X position and current width
+ *    - Set resizing state
+ * 3. On mousemove (document level):
+ *    - Calculate difference from start position
+ *    - Update column width (with minimum constraint)
+ * 4. On mouseup (document level):
+ *    - Clear resizing state
+ *    - Clean up event listeners
+ *
+ * This approach allows dragging outside the column without losing the resize.
+ */
+/**
+ * Column reordering uses HTML5 Drag & Drop API:
+ *
+ * 1. Each column header is draggable
+ * 2. On dragstart:
+ *    - Store which column is being dragged
+ *    - Set drag effect to 'move'
+ * 3. On dragover:
+ *    - Prevent default to allow drop
+ *    - Set drop effect to 'move'
+ * 4. On drop:
+ *    - Calculate new position
+ *    - Dispatch REORDER_COLUMNS action
+ *    - Update columnOrder array in state
+ */
+/**
+ * Three selection modes:
+ *
+ * A) Single Selection (regular click)
+ *    - Clear all selections
+ *    - Select clicked row
+ *
+ * B) Multi Selection (Ctrl/Cmd + click)
+ *    - Toggle clicked row
+ *    - Preserve other selections
+ *
+ * C) Range Selection (Shift + click)
+ *    - Find last selected row
+ *    - Select all rows between last and current
+ *    - Add to existing selection
+ *
+ * Selection state is stored as a Set for O(1) lookups.
+ */
+/**
+ * Cell editing workflow:
+ *
+ * 1. Enter Edit Mode:
+ *    - Double-click cell OR
+ *    - Press Enter on focused cell
+ *    - Dispatch START_EDIT action
+ *    - Replace cell content with input element
+ *
+ * 2. During Editing:
+ *    - Input is focused and selected
+ *    - Value changes update editState
+ *    - Click outside or press Enter/Escape to exit
+ *
+ * 3. Exit Edit Mode:
+ *    - Enter: Save changes, call onCellEdit callback
+ *    - Escape: Discard changes
+ *    - Blur: Save changes
+ *    - Dispatch END_EDIT action
+ */
+/**
+ * Keyboard navigation with focus tracking:
+ *
+ * 1. Focus State:
+ *    - Stored as { rowIndex, columnIndex }
+ *    - Rendered cell gets tabIndex={0}, others get tabIndex={-1}
+ *    - Visual indicator (ring) shows focused cell
+ *
+ * 2. Arrow Key Handling:
+ *    - Calculate new position
+ *    - Apply boundary constraints (0 to max)
+ *    - Update focus state
+ *    - Focused cell automatically receives keyboard focus
+ *
+ * 3. Enter Key:
+ *    - Starts editing if cell is editable
+ *    - During editing, saves and exits
+ *
+ * 4. Escape Key:
+ *    - During editing, cancels and exits
+ *    - Otherwise, clears focus
+ */
+/**
+ * A) useMemo for derived data:
+ *    - sortedRows, filteredRows, paginatedRows
+ *    - Only recalculate when dependencies change
+ *
+ * B) useCallback for event handlers:
+ *    - Prevents child component re-renders
+ *    - Stable function references
+ *
+ * C) Early returns in reducer:
+ *    - No-op actions don't create new state
+ *
+ * D) Set for selection tracking:
+ *    - O(1) lookups for "is selected" checks
+ *
+ * E) Column map in GridHeader/GridBody:
+ *    - Quick column lookup by field name
+ *    - Avoids O(n) array.find() in render
+ *
+ * Future optimization opportunities:
+ * - Virtual scrolling for large datasets
+ * - Web Workers for sorting/filtering
+ * - React.memo for sub-components
+ * - Debounced filter updates
+ */
+/**
+ * Recommended testing approach:
+ *
+ * A) Unit Tests:
+ *    - gridReducer.ts: Test all action types
+ *    - Utility functions: Test sorting, filtering logic
+ *
+ * B) Component Tests:
+ *    - GridHeader: Test sorting, filtering, resizing
+ *    - GridBody: Test cell editing, selection, navigation
+ *    - GridPagination: Test page changes, size changes
+ *
+ * C) Integration Tests:
+ *    - Full DataGrid: Test feature interactions
+ *    - Example: Sort → Filter → Edit → Page change
+ *
+ * D) E2E Tests:
+ *    - User workflows: Select → Edit → Sort → Filter
+ *    - Keyboard navigation flows
+ */
+/**
+ * Current accessibility features:
+ * - Keyboard navigation (arrow keys, Enter, Escape)
+ * - Focus indicators (visible ring)
+ * - Semantic HTML where possible
+ *
+ * Recommended improvements:
+ * - ARIA labels for interactive elements
+ * - aria-sort on column headers
+ * - aria-selected on selected rows
+ * - Screen reader announcements for state changes
+ * - Focus management when editing
+ * - Proper role attributes (grid, row, columnheader, gridcell)
+ * - Keyboard shortcuts documentation
+ */
+/**
+ * How to add new features:
+ *
+ * A) Add new state:
+ *    1. Update GridState interface in types.ts
+ *    2. Add to createInitialState in gridReducer.ts
+ *    3. Create new action type(s)
+ *    4. Handle in reducer switch statement
+ *
+ * B) Add new column feature:
+ *    1. Update Column interface in types.ts
+ *    2. Handle in GridHeader.tsx
+ *    3. Update rendering logic in GridBody.tsx
+ *
+ * C) Add new UI component:
+ *    1. Create new component file
+ *    2. Import in DataGrid.tsx
+ *    3. Pass necessary state and dispatch
+ *    4. Add to component hierarchy
+ *
+ * Example: Adding column pinning
+ *    1. Add pinnedColumns: string[] to GridState
+ *    2. Add PIN_COLUMN/UNPIN_COLUMN actions
+ *    3. Update GridHeader with pin button
+ *    4. Update GridBody to render pinned columns separately
+ *    5. Update column ordering logic
+ */
+/**
+ * A) Column Lookup Pattern:
+ *    const columnMap = new Map(columns.map(col => [col.field, col]));
+ *    const column = columnMap.get(field);
+ *    // Faster than columns.find(col => col.field === field)
+ *
+ * B) Conditional Rendering Pattern:
+ *    if (!column || column.editable === false) return;
+ *    // Handle missing or disabled features
+ *
+ * C) Event Handler Pattern:
+ *    const handleAction = (data) => {
+ *      dispatch({ type: 'ACTION_TYPE', payload: data });
+ *      if (onAction) onAction(data);
+ *    };
+ *    // Update internal state + notify parent
+ *
+ * D) Style Computation Pattern:
+ *    const className = `base-class ${condition ? 'conditional-class' : ''}`;
+ *    // Dynamic class names based on state
+ *
+ * E) Ref Usage Pattern:
+ *    const ref = useRef<HTMLElement>(null);
+ *    useEffect(() => {
+ *      if (ref.current) {
+ *        ref.current.focus();
+ *      }
+ *    }, [dependency]);
+ *    // Imperative DOM operations when needed
+ */
+export {};

package/dist/assets/components/DataGrid/AdvancedFilterBuilder.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { Column, AdvancedFilterValue, Row } from './types';
+interface AdvancedFilterBuilderProps {
+    column: Column;
+    filterValue: AdvancedFilterValue | null;
+    onApply: (value: AdvancedFilterValue | null) => void;
+    onClose: () => void;
+    rows: Row[];
+    anchorEl: HTMLElement | null;
+}
+export declare const AdvancedFilterBuilder: React.FC<AdvancedFilterBuilderProps>;
+export {};

package/dist/assets/components/DataGrid/CellRenderers.d.ts

@@ -0,0 +1,64 @@
+import React from 'react';
+/**
+ * Cell Renderer Components
+ *
+ * Reusable custom cell renderer components for common use cases:
+ * - StatusChip: Badge component for status indicators
+ * - ProgressBar: Visual progress bar
+ * - IconCell: Cell with icon
+ * - ImageCell: Cell with image
+ * - ButtonCell: Actionable button in cell
+ * - BadgeCell: Generic badge component
+ */
+interface StatusChipProps {
+    status: string;
+}
+export declare const StatusChip: React.FC<StatusChipProps>;
+interface ProgressBarProps {
+    value: number;
+    color?: string;
+    showLabel?: boolean;
+}
+export declare const ProgressBar: React.FC<ProgressBarProps>;
+interface IconCellProps {
+    icon: string;
+    text?: string;
+    iconColor?: string;
+}
+export declare const IconCell: React.FC<IconCellProps>;
+interface ImageCellProps {
+    src: string;
+    alt: string;
+    text?: string;
+    size?: number;
+}
+export declare const ImageCell: React.FC<ImageCellProps>;
+interface ButtonCellProps {
+    label: string;
+    onClick: (e: React.MouseEvent) => void;
+    variant?: 'primary' | 'secondary' | 'danger';
+    disabled?: boolean;
+}
+export declare const ButtonCell: React.FC<ButtonCellProps>;
+interface BadgeCellProps {
+    text: string;
+    color?: string;
+    backgroundColor?: string;
+}
+export declare const BadgeCell: React.FC<BadgeCellProps>;
+interface PriorityIndicatorProps {
+    priority: 'low' | 'medium' | 'high' | 'critical';
+}
+export declare const PriorityIndicator: React.FC<PriorityIndicatorProps>;
+interface RatingProps {
+    rating: number;
+    maxRating?: number;
+}
+export declare const Rating: React.FC<RatingProps>;
+interface CurrencyCellProps {
+    amount: number;
+    currency?: string;
+    locale?: string;
+}
+export declare const CurrencyCell: React.FC<CurrencyCellProps>;
+export {};

package/dist/assets/components/DataGrid/ColumnChooser.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { Column } from './types';
+interface ColumnChooserProps {
+    columns: Column[];
+    columnOrder: string[];
+    hiddenColumns: string[];
+    onToggleVisibility: (field: string) => void;
+    onReorderColumns: (fromIndex: number, toIndex: number) => void;
+    onResetLayout: () => void;
+}
+export declare const ColumnChooser: React.FC<ColumnChooserProps>;
+export {};

package/dist/assets/components/DataGrid/ColumnFilters.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import type { Column, FilterConfig, GridAction, Row } from './types';
+interface ColumnFiltersProps {
+    columns: Column[];
+    displayColumnOrder: string[];
+    columnWidths: {
+        [field: string]: number;
+    };
+    filterConfig: FilterConfig;
+    dispatch: React.Dispatch<GridAction>;
+    pinnedLeft: string[];
+    pinnedRight: string[];
+    rows: Row[];
+}
+export declare const ColumnFilters: React.FC<ColumnFiltersProps>;
+export {};

package/dist/assets/components/DataGrid/ContextMenu.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import type { ContextMenuProps } from './types';
+import './ContextMenu.css';
+/**
+ * ContextMenu Component
+ *
+ * A customizable right-click context menu for the DataGrid.
+ * Supports nested submenus, separators, disabled items, and custom menu items.
+ */
+export declare const ContextMenu: React.FC<ContextMenuProps>;

package/dist/assets/components/DataGrid/DataGrid.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { DataGridProps } from './types';
+import type { GridApi } from './gridApi.types';
+/**
+ * DataGrid Component
+ *
+ * A feature-rich data grid component with sorting, filtering, pagination,
+ * column resizing, column reordering, row selection, cell editing, and keyboard navigation.
+ *
+ * Features:
+ * - Sortable columns (click header to sort asc/desc/none)
+ * - Column filtering (text filter for each column)
+ * - Pagination with configurable page size (10, 20, 50)
+ * - Column resizing (drag column border to resize)
+ * - Column reorder (drag and drop column headers)
+ * - Row selection (single click, Ctrl+click for multi, Shift+click for range)
+ * - Editable cells (double-click to edit, Enter to confirm, Escape to cancel)
+ * - Keyboard navigation (arrow keys to move focus, Enter to edit)
+ * - Sticky header (header stays visible when scrolling)
+ * - Grid API: Programmatic control via ref (AG Grid-inspired API)
+ */
+export declare const DataGrid: React.ForwardRefExoticComponent<DataGridProps & React.RefAttributes<GridApi>>;

package/dist/assets/components/DataGrid/DensityToggle.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import type { DensityMode } from './densityModes';
+export interface DensityToggleProps {
+    value: DensityMode;
+    onChange: (mode: DensityMode) => void;
+    className?: string;
+    disabled?: boolean;
+}
+/**
+ * DensityToggle Component
+ *
+ * A segmented control for switching between Compact, Normal, and Comfortable density modes.
+ * Displays as a horizontal button group with clear visual feedback.
+ *
+ * @example
+ * ```tsx
+ * <DensityToggle
+ *   value={densityMode}
+ *   onChange={setDensityMode}
+ * />
+ * ```
+ */
+export declare const DensityToggle: React.FC<DensityToggleProps>;

package/dist/assets/components/DataGrid/DragHandle.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface DragHandleProps {
+    position?: 'left' | 'right';
+    isDragging?: boolean;
+}
+export declare const DragHandle: React.FC<DragHandleProps>;
+export default DragHandle;

package/dist/assets/components/DataGrid/DraggableRow.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { Row, DragRowConfig } from './types';
+interface DraggableRowProps {
+    row: Row;
+    rowIndex: number;
+    config: DragRowConfig;
+    sourceTableId?: string;
+    onRowReorder?: (rows: Row[]) => void;
+    rows: Row[];
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+}
+export declare const DraggableRow: React.FC<DraggableRowProps>;
+export default DraggableRow;

package/dist/assets/components/DataGrid/ExportMenu.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import type { Column, Row } from './types';
+interface ExportMenuProps {
+    columns: Column[];
+    fullDataset: Row[];
+    filteredData: Row[];
+    selectedRows: Set<string | number>;
+    currentPageData: Row[];
+    onExport?: (exported: boolean) => void;
+}
+export declare const ExportMenu: React.FC<ExportMenuProps>;
+export {};

package/dist/assets/components/DataGrid/FacetedSearch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * FacetedSearch Component
+ *
+ * A filter panel that shows value counts for categorical fields.
+ * Perfect for e-commerce and analytics dashboards.
+ * Provides instant visual feedback about data distribution and filtering options.
+ */
+import React from 'react';
+import type { Column, Row, FilterConfig } from './types';
+export interface FacetConfig {
+    field: string;
+    label?: string;
+    maxItems?: number;
+    sortBy?: 'count' | 'value' | 'alpha';
+    expanded?: boolean;
+}
+export interface FacetedSearchProps {
+    columns: Column[];
+    rows: Row[];
+    facetConfigs: FacetConfig[];
+    filterConfig: FilterConfig;
+    onFilterChange: (field: string, values: any[] | null) => void;
+    onClearAll?: () => void;
+    className?: string;
+    showSearch?: boolean;
+    collapsible?: boolean;
+}
+export declare const FacetedSearch: React.FC<FacetedSearchProps>;
+export default FacetedSearch;

package/dist/assets/components/DataGrid/FilteredSearchBar.d.ts

@@ -0,0 +1,36 @@
+/**
+ * FilteredSearchBar Component
+ *
+ * Advanced search bar with token-based filtering (similar to GitLab/GitHub)
+ * Features:
+ * - Token/pill-based filters
+ * - Autocomplete dropdown
+ * - Multi-criteria search
+ * - Visual feedback with colored tokens
+ * - Keyboard navigation
+ */
+import React from 'react';
+export interface SearchToken {
+    id: string;
+    field: string;
+    label: string;
+    value: string | string[];
+    operator?: 'equals' | 'contains' | 'startsWith' | 'in';
+    color?: string;
+}
+export interface FilterOption {
+    field: string;
+    label: string;
+    type: 'text' | 'select' | 'multiselect' | 'date' | 'number';
+    options?: string[];
+    placeholder?: string;
+    color?: string;
+}
+export interface FilteredSearchBarProps {
+    filters: FilterOption[];
+    onSearch: (tokens: SearchToken[]) => void;
+    placeholder?: string;
+    maxTokens?: number;
+}
+export declare const FilteredSearchBar: React.FC<FilteredSearchBarProps>;
+export default FilteredSearchBar;

package/dist/assets/components/DataGrid/FocusTrap.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+export interface FocusTrapProps {
+    children: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    enabled?: boolean;
+    initialFocus?: 'first' | 'last' | HTMLElement | null;
+    returnFocus?: boolean;
+    escapeDeactivates?: boolean;
+    onEscape?: () => void;
+}
+export declare const FocusTrap: React.FC<FocusTrapProps>;

package/dist/assets/components/DataGrid/GridApiDemo.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+/**
+ * Grid API Demo Component
+ * Demonstrates how to use the GridApi ref to programmatically control the grid
+ */
+export declare const GridApiDemo: React.FC;