@optilogic/core 1.0.0-beta.0

package/src/components/data-grid/types.ts

@@ -0,0 +1,478 @@
+/**
+ * DataGrid Types
+ *
+ * Enhanced type definitions for the DataGrid component with support for
+ * resizable columns, filtering, sorting, cell editing, and keyboard navigation.
+ */
+
+import * as React from "react";
+
+/**
+ * Filter operators for different filter types
+ */
+export type TextFilterOperator =
+  | "contains"
+  | "notContains"
+  | "equals"
+  | "notEquals"
+  | "startsWith"
+  | "endsWith"
+  | "isEmpty"
+  | "isNotEmpty";
+
+export type NumberFilterOperator =
+  | "equals"
+  | "notEquals"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "between"
+  | "isEmpty"
+  | "isNotEmpty";
+
+export type DateFilterOperator =
+  | "equals"
+  | "notEquals"
+  | "before"
+  | "after"
+  | "between"
+  | "isEmpty"
+  | "isNotEmpty";
+
+export type FilterOperator =
+  | TextFilterOperator
+  | NumberFilterOperator
+  | DateFilterOperator;
+
+/**
+ * Filter type options
+ */
+export type FilterType = "text" | "number" | "date" | "select" | "boolean";
+
+/**
+ * Editor type options
+ */
+export type EditorType = "text" | "number" | "date" | "select" | "boolean";
+
+/**
+ * Option for select-type filters and editors
+ */
+export interface SelectOption {
+  value: string;
+  label: string;
+}
+
+/**
+ * Represents possible cell values in the DataGrid.
+ * Used for filter values, editing values, and cell accessors.
+ */
+export type CellValue = string | number | boolean | Date | null | undefined;
+
+/**
+ * Filter value type - includes array for multi-select filters
+ */
+export type FilterValue = CellValue | CellValue[];
+
+/**
+ * Filter configuration for a single column
+ */
+export interface FilterConfig {
+  /** Column key this filter applies to */
+  columnKey: string;
+  /** Filter operator */
+  operator: FilterOperator;
+  /** Filter value */
+  value: FilterValue;
+  /** Secondary value for 'between' operator */
+  valueTo?: FilterValue;
+}
+
+/**
+ * Sort configuration for a single column
+ */
+export interface SortConfig {
+  /** Column key to sort by */
+  field: string;
+  /** Sort direction */
+  direction: "asc" | "desc";
+}
+
+/**
+ * Focused cell position
+ */
+export interface CellPosition {
+  /** Row index */
+  rowIndex: number;
+  /** Column key */
+  columnKey: string;
+}
+
+/**
+ * Cell editing state
+ */
+export interface EditingCell extends CellPosition {
+  /** Current editing value */
+  value: CellValue;
+  /** Original value before editing */
+  originalValue: CellValue;
+}
+
+/**
+ * Column definition for the grid
+ */
+export interface ColumnDef<T = Record<string, CellValue>> {
+  /** Unique key for the column */
+  key: string;
+  /** Column header (can be string or React node) */
+  header: string | React.ReactNode;
+  /** Column width (number for px) */
+  width?: number;
+  /** Minimum column width when resizing */
+  minWidth?: number;
+  /** Maximum column width when resizing */
+  maxWidth?: number;
+  /** Custom cell renderer */
+  cell?: (row: T, rowIndex: number) => React.ReactNode;
+  /** Accessor function to get cell value (defaults to row[key]) */
+  accessor?: (row: T) => CellValue;
+
+  // Sorting
+  /** Whether this column is sortable */
+  sortable?: boolean;
+  /** Custom sort comparator function */
+  sortComparator?: (a: T, b: T) => number;
+
+  // Resizing
+  /** Whether this column is resizable (overrides global setting) */
+  resizable?: boolean;
+
+  // Filtering
+  /** Whether this column is filterable */
+  filterable?: boolean;
+  /** Filter type for this column */
+  filterType?: FilterType;
+  /** Options for select-type filters */
+  filterOptions?: SelectOption[];
+  /** Custom filter function for uncontrolled filtering */
+  filterFn?: (row: T, filterValue: FilterValue, operator: FilterOperator) => boolean;
+
+  // Editing
+  /** Whether this column is editable */
+  editable?: boolean;
+  /** Editor type for this column */
+  editorType?: EditorType;
+  /** Options for select-type editors */
+  editorOptions?: SelectOption[];
+  /** Validator function - returns true if valid, or error message string */
+  validator?: (value: CellValue, row: T) => boolean | string;
+
+  // Visibility
+  /** Whether column is hidden */
+  hidden?: boolean;
+
+  // Pinning (future enhancement)
+  /** Pin column to left or right */
+  pinned?: "left" | "right";
+
+  // Alignment
+  /** Text alignment */
+  align?: "left" | "center" | "right";
+}
+
+/**
+ * Pagination configuration
+ */
+export interface PaginationConfig {
+  /** Current page (0-indexed) */
+  currentPage: number;
+  /** Number of rows per page */
+  pageSize: number;
+  /** Total number of pages */
+  totalPages: number;
+  /** Total number of items */
+  totalItems?: number;
+  /** Callback when page changes */
+  onPageChange: (page: number) => void;
+  /** Callback when page size changes */
+  onPageSizeChange: (size: number) => void;
+  /** Available page size options */
+  pageSizeOptions?: number[];
+  /** Show "go to page" input */
+  showGoToPage?: boolean;
+}
+
+/**
+ * Search configuration (global search)
+ */
+export interface SearchConfig {
+  /** Current search query */
+  searchQuery: string;
+  /** Callback when search query changes */
+  onSearchChange: (query: string) => void;
+  /** Search input placeholder */
+  placeholder?: string;
+}
+
+/**
+ * Complete grid state for controlled/uncontrolled modes
+ */
+export interface DataGridState {
+  /** Current sorting configuration */
+  sorting?: SortConfig[];
+  /** Current filter configuration */
+  filters?: FilterConfig[];
+  /** Current column widths */
+  columnWidths?: Record<string, number>;
+  /** Hidden column keys */
+  hiddenColumns?: string[];
+  /** Current pagination state (for uncontrolled mode) */
+  pagination?: {
+    page: number;
+    pageSize: number;
+  };
+  /** Currently focused cell */
+  focusedCell?: CellPosition | null;
+  /** Currently editing cell */
+  editingCell?: EditingCell | null;
+}
+
+/**
+ * Callback for cell edit events
+ */
+export interface CellEditEvent<T = Record<string, CellValue>> {
+  /** Row index */
+  rowIndex: number;
+  /** Column key */
+  columnKey: string;
+  /** New value */
+  newValue: CellValue;
+  /** Original value */
+  oldValue: CellValue;
+  /** The row data */
+  row: T;
+}
+
+/**
+ * DataGrid props
+ */
+export interface DataGridProps<T = Record<string, CellValue>> {
+  // ============ DATA ============
+  /** Data to display in the grid */
+  data: T[];
+  /** Column definitions */
+  columns: ColumnDef<T>[];
+  /** Key accessor for row identification */
+  getRowKey?: (row: T, index: number) => string;
+
+  // ============ FEATURE TOGGLES ============
+  /** Enable column resizing globally (default: false) */
+  resizableColumns?: boolean;
+  /** Enable virtualization for large datasets (default: true if data.length > 100) */
+  virtualized?: boolean;
+  /** Make header sticky (default: true) */
+  stickyHeader?: boolean;
+  /** Enable hover tooltips for long content (default: true) */
+  showTooltips?: boolean;
+  /** Minimum cell content length to show tooltip (default: 30) */
+  tooltipMinLength?: number;
+  /** Show column dividing borders between cells (default: true) */
+  showColumnBorders?: boolean;
+  /** Enable internal sorting when in uncontrolled mode (default: true) */
+  enableInternalSorting?: boolean;
+  /** Enable internal filtering when in uncontrolled mode (default: true) */
+  enableInternalFiltering?: boolean;
+
+  // ============ SORTING (Controlled) ============
+  /** Current sorting configuration */
+  sorting?: SortConfig[];
+  /** Callback when sorting changes */
+  onSortChange?: (sorting: SortConfig[]) => void;
+
+  // ============ FILTERING (Controlled) ============
+  /** Current filter configuration */
+  filters?: FilterConfig[];
+  /** Callback when filters change */
+  onFilterChange?: (filters: FilterConfig[]) => void;
+
+  // ============ COLUMN WIDTHS (Controlled) ============
+  /** Current column widths */
+  columnWidths?: Record<string, number>;
+  /** Callback when a column is resized */
+  onColumnResize?: (columnKey: string, width: number) => void;
+  /** Callback when column resize starts */
+  onColumnResizeStart?: (columnKey: string) => void;
+  /** Callback when column resize ends */
+  onColumnResizeEnd?: (columnKey: string, width: number) => void;
+
+  // ============ UNCONTROLLED DEFAULTS ============
+  /** Default sorting for uncontrolled mode */
+  defaultSorting?: SortConfig[];
+  /** Default filters for uncontrolled mode */
+  defaultFilters?: FilterConfig[];
+  /** Default column widths for uncontrolled mode */
+  defaultColumnWidths?: Record<string, number>;
+
+  // ============ STATE CHANGE CALLBACK ============
+  /** Callback when any internal state changes (for uncontrolled mode) */
+  onStateChange?: (state: DataGridState) => void;
+
+  // ============ ROW INTERACTIONS ============
+  /** Row click handler */
+  onRowClick?: (row: T, rowIndex: number) => void;
+  /** Row double-click handler */
+  onRowDoubleClick?: (row: T, rowIndex: number) => void;
+  /** Selected row keys/ids */
+  selectedRows?: string[];
+  /** Callback when row selection changes */
+  onSelectedRowsChange?: (selectedKeys: string[]) => void;
+  /** Row class name function */
+  rowClassName?: (row: T, rowIndex: number) => string;
+
+  // ============ CELL EDITING ============
+  /** Cell edit handler - called when cell value changes */
+  onCellEdit?: (
+    rowIndex: number,
+    columnKey: string,
+    newValue: CellValue,
+    oldValue: CellValue
+  ) => void;
+  /** Callback before cell edit starts - return false to prevent */
+  onCellEditStart?: (rowIndex: number, columnKey: string) => boolean | void;
+  /** Callback when cell edit is cancelled */
+  onCellEditCancel?: (rowIndex: number, columnKey: string) => void;
+
+  // ============ KEYBOARD NAVIGATION ============
+  /** Currently focused cell (controlled) */
+  focusedCell?: CellPosition | null;
+  /** Callback when focused cell changes */
+  onFocusedCellChange?: (cell: CellPosition | null) => void;
+  /** Enable keyboard navigation (default: true) */
+  enableKeyboardNavigation?: boolean;
+
+  // ============ PAGINATION ============
+  /** Pagination configuration */
+  pagination?: PaginationConfig;
+
+  // ============ SEARCH ============
+  /** Search configuration */
+  search?: SearchConfig;
+
+  // ============ LOADING & EMPTY STATES ============
+  /** Loading state */
+  loading?: boolean;
+  /** Custom loading component */
+  loadingComponent?: React.ReactNode;
+  /** Empty state message */
+  emptyMessage?: string;
+  /** Custom empty state component */
+  emptyComponent?: React.ReactNode;
+
+  // ============ STYLING ============
+  /** Additional class name for container */
+  className?: string;
+  /** Additional class name for table */
+  tableClassName?: string;
+
+  // ============ INFINITE SCROLL ============
+  /** Enable infinite scroll mode */
+  infiniteScroll?: boolean;
+  /** Callback when more data should be loaded */
+  onLoadMore?: () => void;
+  /** Whether more data is available */
+  hasMore?: boolean;
+  /** Whether currently loading more data */
+  loadingMore?: boolean;
+}
+
+/**
+ * Internal state for the DataGrid
+ */
+export interface DataGridInternalState {
+  sorting: SortConfig[];
+  filters: FilterConfig[];
+  columnWidths: Record<string, number>;
+  focusedCell: CellPosition | null;
+  editingCell: EditingCell | null;
+}
+
+/**
+ * Context for DataGrid sub-components
+ */
+export interface DataGridContextValue<T = Record<string, CellValue>> {
+  // Data
+  data: T[];
+  columns: ColumnDef<T>[];
+  getRowKey: (row: T, index: number) => string;
+
+  // State
+  state: DataGridInternalState;
+
+  // Actions
+  setFocusedCell: (cell: CellPosition | null) => void;
+  startEditing: (rowIndex: number, columnKey: string) => void;
+  commitEdit: (value: CellValue) => void;
+  cancelEdit: () => void;
+  updateColumnWidth: (columnKey: string, width: number) => void;
+  updateSorting: (sorting: SortConfig[]) => void;
+  updateFilters: (filters: FilterConfig[]) => void;
+
+  // Feature flags
+  resizableColumns: boolean;
+  enableKeyboardNavigation: boolean;
+}
+
+/**
+ * Props for HeaderCell component
+ */
+export interface HeaderCellProps<T = Record<string, CellValue>> {
+  column: ColumnDef<T>;
+  columnIndex: number;
+  width: number;
+  sorting?: SortConfig;
+  filter?: FilterConfig;
+  isResizable: boolean;
+  onSort?: () => void;
+  onFilterChange?: (filter: FilterConfig | null) => void;
+  onResize?: (width: number) => void;
+  onResizeStart?: () => void;
+  onResizeEnd?: (width: number) => void;
+}
+
+/**
+ * Props for FilterPopover component
+ */
+export interface FilterPopoverProps {
+  column: ColumnDef;
+  filter?: FilterConfig;
+  onFilterChange: (filter: FilterConfig | null) => void;
+}
+
+/**
+ * Props for CellEditor component
+ */
+export interface CellEditorProps<T = Record<string, CellValue>> {
+  column: ColumnDef<T>;
+  value: CellValue;
+  row: T;
+  rowIndex: number;
+  onCommit: (value: CellValue) => void;
+  onCancel: () => void;
+}
+
+/**
+ * Props for GridCell component
+ */
+export interface GridCellProps<T = Record<string, CellValue>> {
+  column: ColumnDef<T>;
+  row: T;
+  rowIndex: number;
+  columnIndex: number;
+  width: number;
+  isEditing: boolean;
+  isFocused: boolean;
+  onStartEdit: () => void;
+  onCommitEdit: (value: CellValue) => void;
+  onCancelEdit: () => void;
+  onFocus: () => void;
+}