react-open-source-grid 1.5.3 → 1.5.4

package/dist/lib/App.d.ts

@@ -0,0 +1,3 @@
+import './App.css';
+declare function App(): import("react/jsx-runtime").JSX.Element;
+export default App;

package/dist/lib/chunk-FG3FLQAE.js

@@ -0,0 +1,296 @@
+// src/components/DataGrid/layoutPersistence.ts
+var LocalStorageAdapter = class {
+  async save(key, preset) {
+    try {
+      const existingData = localStorage.getItem(key);
+      const presets = existingData ? JSON.parse(existingData) : [];
+      const index = presets.findIndex((p) => p.id === preset.id);
+      if (index !== -1) {
+        presets[index] = preset;
+      } else {
+        presets.push(preset);
+      }
+      localStorage.setItem(key, JSON.stringify(presets));
+    } catch (error) {
+      console.error("Failed to save preset to localStorage:", error);
+      throw error;
+    }
+  }
+  async load(key, presetId) {
+    try {
+      const data = localStorage.getItem(key);
+      if (!data) return null;
+      const presets = JSON.parse(data);
+      if (presetId) {
+        return presets.find((p) => p.id === presetId) || null;
+      }
+      return presets;
+    } catch (error) {
+      console.error("Failed to load preset from localStorage:", error);
+      throw error;
+    }
+  }
+  async delete(key, presetId) {
+    try {
+      const data = localStorage.getItem(key);
+      if (!data) return;
+      const presets = JSON.parse(data);
+      const filtered = presets.filter((p) => p.id !== presetId);
+      localStorage.setItem(key, JSON.stringify(filtered));
+    } catch (error) {
+      console.error("Failed to delete preset from localStorage:", error);
+      throw error;
+    }
+  }
+  async list(key) {
+    try {
+      const data = localStorage.getItem(key);
+      if (!data) return [];
+      return JSON.parse(data);
+    } catch (error) {
+      console.error("Failed to list presets from localStorage:", error);
+      throw error;
+    }
+  }
+};
+var ServerAdapter = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  async save(key, preset) {
+    const endpoint = this.config.saveEndpoint || `${this.config.baseUrl}/layouts`;
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.config.headers
+        },
+        body: JSON.stringify({ key, preset })
+      });
+      if (!response.ok) {
+        throw new Error(`Server responded with ${response.status}`);
+      }
+    } catch (error) {
+      console.error("Failed to save preset to server:", error);
+      throw error;
+    }
+  }
+  async load(key, presetId) {
+    const endpoint = this.config.loadEndpoint || `${this.config.baseUrl}/layouts`;
+    const url = presetId ? `${endpoint}/${key}/${presetId}` : `${endpoint}/${key}`;
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.config.headers
+        }
+      });
+      if (response.status === 404) {
+        return null;
+      }
+      if (!response.ok) {
+        throw new Error(`Server responded with ${response.status}`);
+      }
+      return await response.json();
+    } catch (error) {
+      console.error("Failed to load preset from server:", error);
+      throw error;
+    }
+  }
+  async delete(key, presetId) {
+    const endpoint = this.config.deleteEndpoint || `${this.config.baseUrl}/layouts`;
+    const url = `${endpoint}/${key}/${presetId}`;
+    try {
+      const response = await fetch(url, {
+        method: "DELETE",
+        headers: this.config.headers
+      });
+      if (!response.ok) {
+        throw new Error(`Server responded with ${response.status}`);
+      }
+    } catch (error) {
+      console.error("Failed to delete preset from server:", error);
+      throw error;
+    }
+  }
+  async list(key) {
+    const endpoint = this.config.listEndpoint || `${this.config.baseUrl}/layouts`;
+    const url = `${endpoint}/${key}`;
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.config.headers
+        }
+      });
+      if (response.status === 404) {
+        return [];
+      }
+      if (!response.ok) {
+        throw new Error(`Server responded with ${response.status}`);
+      }
+      return await response.json();
+    } catch (error) {
+      console.error("Failed to list presets from server:", error);
+      throw error;
+    }
+  }
+};
+var UserProfileAdapter = class {
+  config;
+  baseAdapter;
+  constructor(config) {
+    this.config = config;
+    this.baseAdapter = config.adapter || new LocalStorageAdapter();
+  }
+  getUserKey(key) {
+    const profileKey = this.config.profileKey || "user-layouts";
+    return `${profileKey}:${this.config.userId}:${key}`;
+  }
+  async save(key, preset) {
+    return this.baseAdapter.save(this.getUserKey(key), preset);
+  }
+  async load(key, presetId) {
+    return this.baseAdapter.load(this.getUserKey(key), presetId);
+  }
+  async delete(key, presetId) {
+    return this.baseAdapter.delete(this.getUserKey(key), presetId);
+  }
+  async list(key) {
+    return this.baseAdapter.list(this.getUserKey(key));
+  }
+};
+function getStorageAdapter(config) {
+  if (config.customAdapter) {
+    return config.customAdapter;
+  }
+  switch (config.strategy) {
+    case "server":
+      if (!config.serverConfig) {
+        throw new Error("Server configuration is required for server storage strategy");
+      }
+      return new ServerAdapter(config.serverConfig);
+    case "userProfile":
+      if (!config.userProfileConfig) {
+        throw new Error("User profile configuration is required for userProfile storage strategy");
+      }
+      return new UserProfileAdapter(config.userProfileConfig);
+    case "localStorage":
+    default:
+      return new LocalStorageAdapter();
+  }
+}
+function generatePresetId() {
+  return `preset_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+function createPreset(name, layout, description, id) {
+  const now = Date.now();
+  return {
+    id: id || generatePresetId(),
+    name,
+    description,
+    createdAt: now,
+    updatedAt: now,
+    layout
+  };
+}
+var LayoutPersistenceManager = class {
+  adapter;
+  storageKey;
+  constructor(config) {
+    this.adapter = getStorageAdapter(config);
+    this.storageKey = config.storageKey;
+  }
+  /**
+   * Save a layout preset
+   */
+  async savePreset(preset) {
+    const updatedPreset = {
+      ...preset,
+      updatedAt: Date.now()
+    };
+    await this.adapter.save(this.storageKey, updatedPreset);
+  }
+  /**
+   * Load a specific preset by ID
+   */
+  async loadPreset(presetId) {
+    const result = await this.adapter.load(this.storageKey, presetId);
+    if (Array.isArray(result)) {
+      return result.find((p) => p.id === presetId) || null;
+    }
+    return result;
+  }
+  /**
+   * Load the most recently updated preset
+   */
+  async loadLastPreset() {
+    const presets = await this.listPresets();
+    if (presets.length === 0) {
+      return null;
+    }
+    return presets.reduce(
+      (latest, current) => current.updatedAt > latest.updatedAt ? current : latest
+    );
+  }
+  /**
+   * Delete a preset
+   */
+  async deletePreset(presetId) {
+    await this.adapter.delete(this.storageKey, presetId);
+  }
+  /**
+   * List all presets
+   */
+  async listPresets() {
+    return await this.adapter.list(this.storageKey);
+  }
+  /**
+   * Check if a preset exists
+   */
+  async hasPreset(presetId) {
+    const preset = await this.loadPreset(presetId);
+    return preset !== null;
+  }
+  /**
+   * Save current layout as auto-save (with special ID)
+   */
+  async autoSave(layout) {
+    const autoSaveId = "__autosave__";
+    const preset = createPreset("Auto-saved Layout", layout, "Automatically saved layout", autoSaveId);
+    await this.savePreset(preset);
+  }
+  /**
+   * Load auto-saved layout
+   */
+  async loadAutoSave() {
+    return await this.loadPreset("__autosave__");
+  }
+};
+function debounce(func, delay) {
+  let timeoutId = null;
+  return function(...args) {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      func.apply(this, args);
+      timeoutId = null;
+    }, delay);
+  };
+}
+
+export {
+  LocalStorageAdapter,
+  ServerAdapter,
+  UserProfileAdapter,
+  getStorageAdapter,
+  generatePresetId,
+  createPreset,
+  LayoutPersistenceManager,
+  debounce
+};

package/dist/lib/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/lib/components/ApiReferencePage.d.ts

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

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

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

package/dist/lib/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/lib/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/lib/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/lib/components/CompleteApiReferencePage.d.ts

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

package/dist/lib/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/lib/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/lib/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 {};