@jmruthers/pace-core 0.6.10 → 0.6.12

package/src/components/DataTable/types.ts

@@ -1,764 +0,0 @@
-/**
- * @file DataTable Type Definitions
- * @package @jmruthers/pace-core
- * @module Components/DataTable/Types
- * @since 0.2.0
- */
-
-import React from 'react';
-import type { 
-  SortingState, 
-  ColumnFiltersState, 
-  GroupingState, 
-  ColumnDef
-} from '@tanstack/react-table';
-import type { ImportModalConfig } from './components/ImportModal';
-
-// Extend TanStack Table types to include custom meta properties
-declare module '@tanstack/react-table' {
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  interface ColumnMeta<TData, TValue> {
-    /** Text alignment for the column content */
-    align?: 'left' | 'right' | 'center';
-    /** Column type for styling purposes */
-    type?: 'text' | 'number' | 'date' | 'boolean' | 'custom';
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  interface ColumnDefBase<TData, TValue> {
-    /** Alternative accessor key used while editing */
-    editAccessorKey?: string;
-  }
-}
-
-// ============================================================================
-// CORE DATA TYPES
-// ============================================================================
-
-/**
- * Core value types that can exist in a data record
- */
-export type CellValue = string | number | boolean | null | undefined | Date;
-
-/**
- * Base data record type - all DataTable data must extend this
- * This is a marker type that allows any object to be used as a data record
- * Individual implementations should define more specific types
- */
-export interface DataRecord {
-  [key: string]: unknown;
-}
-
-/**
- * Row ID type - always a string
- */
-export type RowId = string;
-
-/**
- * Row identifier function type
- */
-export type GetRowId<TData extends DataRecord> = (row: TData, index: number) => RowId;
-
-// ============================================================================
-// HIERARCHICAL DATA TYPES
-// ============================================================================
-
-/**
- * Hierarchical data row interface for parent/child relationships
- */
-export interface HierarchicalDataRow extends DataRecord {
-  /** Whether this row is a parent row */
-  isParent: boolean;
-  /** For child rows, references the parent row ID */
-  parentId?: string;
-  /** Unique identifier for this row */
-  id: string;
-}
-
-/**
- * Hierarchical configuration for DataTable
- */
-export interface HierarchicalConfig {
-  /** Enable hierarchical functionality */
-  enabled: boolean;
-  /** Default expanded state - true = all expanded, false = all collapsed, array = specific IDs */
-  defaultExpanded?: boolean | string[];
-  /** Callback when expanded state changes */
-  onExpandedChange?: (expandedIds: string[]) => void;
-  /** Visual indentation for child rows (in pixels) */
-  indentSize?: number;
-  /** Custom styling for parent rows */
-  parentRowClassName?: string;
-  /** Custom styling for child rows */
-  childRowClassName?: string;
-}
-
-// ============================================================================
-// PERFORMANCE & PAGINATION TYPES
-// ============================================================================
-
-/**
- * Pagination mode determines how data is handled
- */
-export type PaginationMode = 'client' | 'server' | 'hybrid';
-
-/**
- * Performance configuration for large datasets
- */
-export interface PerformanceConfig {
-  /** Enable virtual scrolling */
-  virtualScrolling?: boolean;
-  /** Virtual scrolling overscan count */
-  overscan?: number;
-  /** Enable memoization of cell renderers */
-  memoizeCells?: boolean;
-  /** Enable debounced search */
-  debounceSearch?: number;
-  /** Enable data chunking for memory management */
-  enableChunking?: boolean;
-  /** Chunk size for data processing */
-  chunkSize?: number;
-  /** Enable Web Workers for heavy operations */
-  enableWebWorkers?: boolean;
-  /** Threshold for switching to server-side mode */
-  serverSideThreshold?: number;
-}
-
-/**
- * Server-side data fetching configuration
- */
-export interface ServerSideConfig<TData extends DataRecord> {
-  /** Function to fetch data from server */
-  fetchData: (params: ServerSideParams) => Promise<ServerSideResponse<TData>>;
-  /** Enable server-side sorting */
-  enableServerSorting?: boolean;
-  /** Enable server-side filtering */
-  enableServerFiltering?: boolean;
-  /** Enable server-side search */
-  enableServerSearch?: boolean;
-  /** Enable server-side pagination */
-  enableServerPagination?: boolean;
-  /** Debounce delay for server requests */
-  debounceMs?: number;
-  /** Cache duration for server responses */
-  cacheMs?: number;
-}
-
-/**
- * Parameters sent to server for data fetching
- */
-export interface ServerSideParams {
-  /** Current page index */
-  pageIndex: number;
-  /** Page size */
-  pageSize: number;
-  /** Sorting configuration */
-  sorting: SortingState;
-  /** Column filters */
-  columnFilters: ColumnFiltersState;
-  /** Global filter/search term */
-  globalFilter: string;
-  /** Grouping configuration */
-  grouping: GroupingState;
-}
-
-/**
- * Response from server for data fetching
- */
-export interface ServerSideResponse<TData extends DataRecord> {
-  /** Array of data records */
-  data: TData[];
-  /** Total number of records (for pagination) */
-  totalCount: number;
-  /** Current page index */
-  pageIndex: number;
-  /** Page size */
-  pageSize: number;
-  /** Total number of pages */
-  pageCount: number;
-  /** Whether there are more pages */
-  hasNextPage: boolean;
-  /** Whether there are previous pages */
-  hasPreviousPage: boolean;
-}
-
-/**
- * Unified pagination configuration for consistent behavior across modes
- */
-export interface PaginationConfig {
-  /** Pagination mode */
-  mode: PaginationMode;
-  /** Available page size options */
-  pageSizeOptions?: number[];
-  /** Initial page size */
-  initialPageSize?: number;
-  /** Show enhanced pagination controls (jump to page, etc.) */
-  enhanced?: boolean;
-  /** Show performance mode indicator */
-  showPerformanceInfo?: boolean;
-}
-
-/**
- * Pagination callbacks for server-side and hybrid modes
- */
-export interface PaginationCallbacks {
-  /** Called when page index changes */
-  onPageChange?: (pageIndex: number) => void;
-  /** Called when page size changes */
-  onPageSizeChange?: (pageSize: number) => void;
-}
-
-/**
- * Data chunking configuration
- */
-export interface ChunkingConfig {
-  /** Size of each data chunk */
-  chunkSize: number;
-  /** Number of chunks to keep in memory */
-  maxChunksInMemory: number;
-  /** Enable progressive loading */
-  progressiveLoading?: boolean;
-}
-
-/**
- * Search index configuration for performance
- */
-export interface SearchIndexConfig {
-  /** Fields to index for search */
-  indexedFields: string[];
-  /** Enable fuzzy search */
-  fuzzySearch?: boolean;
-  /** Fuzzy search threshold */
-  fuzzyThreshold?: number;
-  /** Enable search highlighting */
-  enableHighlighting?: boolean;
-}
-
-// ============================================================================
-// COLUMN DEFINITIONS
-// ============================================================================
-
-/**
- * Enhanced column definition that extends TanStack's ColumnDef
- */
-export interface DataTableColumn<TData extends DataRecord = DataRecord> extends Omit<ColumnDef<TData>, 'id' | 'accessorKey'> {
-  /** Column identifier */
-  id?: string;
-  /** Accessor key for data */
-  accessorKey?: string;
-  /** Alternative accessor key used while editing */
-  editAccessorKey?: string;
-  /** Custom header label for the column */
-  header: string;
-  /** Whether this column should be searchable in global filter */
-  searchable?: boolean;
-  /** Enable sorting */
-  sortable?: boolean;
-  /** Enable column filter (inherits from ColumnDef) */
-  enableColumnFilter?: boolean;
-  /** Enable grouping (inherits from ColumnDef) */
-  enableGrouping?: boolean;
-  /** Enable hiding (inherits from ColumnDef) */
-  enableHiding?: boolean;
-  /** Aggregate configuration for this column */
-  aggregate?: AggregateConfig;
-  /** Enable virtual scrolling for this column */
-  virtualizable?: boolean;
-  /** Custom cell renderer with memoization */
-  memoizedCell?: React.ComponentType<{ row: TData }>;
-  /** Field type for editing (text, select, date, etc.) */
-  fieldType?: 'text' | 'select' | 'date' | 'number' | 'boolean';
-  /** Options for select fields - can be simple items or grouped with labels and separators */
-  fieldOptions?: Array<
-    | { value: string | number; label: string } // Simple option
-    | { type: 'group'; label: string; items: Array<{ value: string | number; label: string }> } // Group with label
-    | { type: 'separator' } // Visual separator
-  >;
-  /** Enable keyboard search/filtering in select dropdowns within editable columns (default: true). When fieldType is 'select', this controls dropdown searchability, not global search. */
-  selectSearchable?: boolean;
-  /** Enable creating new items in select dropdowns (default: false) */
-  creatable?: boolean;
-  /** Callback to create a new item when user types non-matching text in select dropdown */
-  onCreateNew?: (inputValue: string) => Promise<string | number> | string | number;
-  /** Maximum height for select dropdown content (default: "20rem") */
-  selectMaxHeight?: string;
-  /** Custom className for select content dropdown */
-  selectContentClassName?: string;
-  /** Custom style for select content dropdown */
-  selectContentStyle?: React.CSSProperties;
-  /** Hide spinner arrows on number input fields (default: true for DataTable) */
-  hideNumberSpinners?: boolean;
-  /** Filter type for column filtering (text, select, number, date) */
-  filterType?: 'text' | 'select' | 'number' | 'date';
-  /** Options for select filters (alternative to fieldOptions) */
-  filterSelectOptions?: Array<{ value: string | number; label: string }>;
-  /** Whether this column is editable in edit mode (default: true) */
-  editable?: boolean;
-  /** Alternative CSV headers that should map to this column during import */
-  importAliases?: string[];
-  
-  // Hierarchical rendering
-  /** Custom renderer for parent rows */
-  renderForParent?: (row: TData) => React.ReactNode;
-  /** Custom renderer for child rows */
-  renderForChild?: (row: TData) => React.ReactNode;
-  /** Hide this column for parent rows */
-  hideForParent?: boolean;
-  /** Hide this column for child rows */
-  hideForChild?: boolean;
-  
-  // Grouped row aggregation
-  /**
-   * Aggregation function for grouped rows.
-   * Receives all rows in the group and returns the aggregated value.
-   * If not provided, grouped rows will show empty/undefined for this column.
-   */
-  aggregateFn?: (rows: TData[], column: DataTableColumn<TData>) => unknown;
-  /**
-   * Optional: Custom cell renderer for aggregated values in grouped rows.
-   * If not provided, uses the column's regular cell renderer.
-   */
-  aggregateCell?: (value: unknown, rows: TData[], column: DataTableColumn<TData>) => React.ReactNode;
-}
-
-/**
- * Extended column definition used when rendering editable rows
- */
-export interface EditableColumnDef<TData extends DataRecord = DataRecord> extends DataTableColumn<TData> {
-  /** Whether the column can be edited */
-  editable?: boolean;
-  /** Field type used to determine edit control */
-  fieldType?: 'text' | 'select' | 'date' | 'number' | 'boolean';
-  /** Options for select based editors - can be simple items or grouped with labels and separators */
-  fieldOptions?: Array<
-    | { value: string | number; label: string } // Simple option
-    | { type: 'group'; label: string; items: Array<{ value: string | number; label: string }> } // Group with label
-    | { type: 'separator' } // Visual separator
-  >;
-  /** Enable keyboard search/filtering in select dropdowns (inherits from DataTableColumn.selectSearchable) */
-  selectSearchable?: boolean;
-  /** Enable creating new items in select dropdowns */
-  creatable?: boolean;
-  /** Callback to create a new item when user types non-matching text */
-  onCreateNew?: (inputValue: string) => Promise<string | number> | string | number;
-  /** Hide spinner arrows on number input fields */
-  hideNumberSpinners?: boolean;
-}
-
-/**
- * Simple column interface for basic use cases
- */
-export interface SimpleColumn<TData extends DataRecord = DataRecord> {
-  /** Data accessor key */
-  key: keyof TData | string;
-  /** Display label */
-  label: string;
-  /** Enable sorting */
-  sortable?: boolean;
-  /** Enable filtering */
-  filterable?: boolean;
-}
-
-// ============================================================================
-// ACTION DEFINITIONS
-// ============================================================================
-
-/**
- * Action definition for row-level operations
- */
-/**
- * Boolean condition or predicate evaluated against a row
- */
-export type ActionCondition<TData extends DataRecord> = boolean | ((row: TData) => boolean);
-
-/**
- * Action definition for DataTable rows.
- * Defines custom actions that can be performed on table rows.
- * 
- * @template TData - The type of data records in the table
- */
-export interface DataTableAction<TData extends DataRecord> {
-  /** Display label for the action */
-  label: string;
-  /** Icon component */
-  icon?: React.ComponentType<{ className?: string }>;
-  /** Action handler */
-  onClick: (row: TData) => void;
-  /** Visual variant */
-  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost';
-  /** Whether action is disabled */
-  disabled?: ActionCondition<TData>;
-  /** Whether action is hidden (for RBAC) */
-  hidden?: boolean;
-  /** Explicit visibility override */
-  visible?: ActionCondition<TData>;
-  /** Test ID for testing */
-  testId?: string;
-  /** Whether this action should only show for parent rows (hierarchical mode) */
-  showForParent?: boolean;
-  /** Whether this action should only show for child rows (hierarchical mode) */
-  showForChild?: boolean;
-  /** Icon component for parent rows (overrides icon when showForParent is true) */
-  parentIcon?: React.ComponentType<{ className?: string }>;
-  /** Icon component for child rows (overrides icon when showForChild is true) */
-  childIcon?: React.ComponentType<{ className?: string }>;
-  /** Label for parent rows (overrides label when showForParent is true) */
-  parentLabel?: string;
-  /** Label for child rows (overrides label when showForChild is true) */
-  childLabel?: string;
-  /** Whether the action should be shown while the row is in edit mode */
-  showInEditMode?: boolean;
-  /** Whether the action should be hidden while the row is in view mode */
-  hideInViewMode?: boolean;
-  /** Whether the action should explicitly render while in view mode */
-  showInViewMode?: boolean;
-}
-
-/**
- * Toolbar button definition
- */
-export interface DataTableToolbarButton {
-  /** Display label */
-  label: string;
-  /** Icon component */
-  icon?: React.ComponentType<{ className?: string }>;
-  /** Click handler */
-  onClick: () => void;
-  /** Visual variant */
-  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost';
-  /** Whether button is disabled */
-  disabled?: boolean;
-  /** Test ID for testing */
-  testId?: string;
-}
-
-// ============================================================================
-// CONFIGURATION TYPES
-// ============================================================================
-
-/**
- * Aggregate configuration
- */
-export interface AggregateConfig {
-  field: string;
-  function: 'sum' | 'avg' | 'count' | 'min' | 'max';
-  label: string;
-}
-
-/**
- * Empty state configuration
- */
-export interface EmptyStateConfig {
-  title?: string;
-  description?: string;
-  icon?: React.ComponentType<{ className?: string }>;
-  action?: {
-    label: string;
-    onClick: () => void;
-  };
-}
-
-// ============================================================================
-// FEATURE CONFIGURATION TYPES
-// ============================================================================
-
-/**
- * Unified feature configuration for DataTable
- * All features are disabled by default and must be explicitly enabled
- */
-export interface DataTableFeatureFlags {
-  // Core Features
-  /** Enable global search functionality */
-  search: boolean;
-  /** Enable pagination controls */
-  pagination: boolean;
-  /** Enable column sorting */
-  sorting: boolean;
-  /** Enable column filtering */
-  filtering: boolean;
-  
-  // Data Management
-  /** Enable data import functionality */
-  import: boolean;
-  /** Enable data export functionality */
-  export: boolean;
-  
-  // Row Operations
-  /** Enable row selection for bulk operations */
-  selection: boolean;
-  /** Enable row creation */
-  creation: boolean;
-  /** Enable row editing */
-  editing: boolean;
-  /** Enable row deletion */
-  deletion: boolean;
-  /** Enable bulk deletion of selected rows */
-  deleteSelected: boolean;
-  
-  // Table Customization
-  /** Enable data grouping */
-  grouping: boolean;
-  /** Enable column visibility controls */
-  columnVisibility: boolean;
-  /** Enable column reordering */
-  columnReordering: boolean;
-  /** Enable hierarchical parent/child rows */
-  hierarchical: boolean;
-
-  // Performance
-  // Virtualization is now handled automatically based on data size
-
-  // Layout
-}
-
-/**
- * Consumer-facing feature configuration. All properties are optional and will be
- * merged with {@link defaultDataTableFeatures} at runtime to keep the public API
- * ergonomic while maintaining strict internal guarantees.
- */
-export type DataTableFeatureConfig = Partial<DataTableFeatureFlags>;
-
-/** Fully normalized feature configuration used internally by the table. */
-export type NormalizedDataTableFeatureConfig = DataTableFeatureFlags;
-
-/** Default feature configuration with every capability disabled. */
-export const defaultDataTableFeatures: NormalizedDataTableFeatureConfig = {
-  search: false,
-  pagination: false,
-  sorting: false,
-  filtering: false,
-  import: false,
-  export: false,
-  selection: false,
-  creation: false,
-  editing: false,
-  deletion: false,
-  deleteSelected: false,
-  grouping: false,
-  columnVisibility: false,
-  columnReordering: false,
-  hierarchical: false,
-};
-
-/**
- * Normalize a potentially partial feature configuration. This keeps the
- * rendering pipeline simple and predictable because downstream consumers can
- * rely on every flag being present.
- */
-export function normalizeDataTableFeatures(
-  features?: DataTableFeatureConfig
-): NormalizedDataTableFeatureConfig {
-  return {
-    ...defaultDataTableFeatures,
-    ...(features ?? {}),
-  };
-}
-
-
-
-// ============================================================================
-// RBAC TYPES
-// ============================================================================
-
-/**
- * RBAC configuration for DataTable - MANDATORY for all DataTables
- * 
- * @example
- * ```tsx
- * <DataTable 
- *   data={dishes} 
- *   rbac={{ pageName: 'dishes' }} // Use page name (recommended)
- *   features={features}
- * />
- * 
- * <DataTable 
- *   data={dishes} 
- *   rbac={{ pageId: 'uuid-here' }} // Use page ID directly
- *   features={features}
- * />
- * ```
- */
-export interface DataTableRBACConfig {
-  /** Page name for page-based permissions - will be resolved to page ID */
-  pageName?: string;
-  /** Page ID for page-based permissions - used directly if provided */
-  pageId?: string;
-}
-
-/**
- * RBAC context passed to server-side requests
- */
-export interface RBACContext {
-  /** User ID for permission checking */
-  userId: string;
-  /** Organisation ID for scope isolation */
-  organisationId: string;
-  /** Event ID for event-based apps */
-  eventId?: string;
-  /** App ID for app-specific permissions */
-  appId?: string;
-  /** Page ID for granular permissions */
-  pageId: string;
-}
-
-// ============================================================================
-// EXPORT TYPES
-// ============================================================================
-
-/**
- * Options provided to the onExport handler for custom export functionality
- * 
- * @example
- * ```tsx
- * <DataTable
- *   onExport={async (options) => {
- *     // Export only specific columns
- *     const customColumns = options.allColumns.filter(col => 
- *       ['name', 'email', 'role'].includes(col.accessorKey || '')
- *     );
- *     await exportToCSVWithTableRows(
- *       options.tableRows,
- *       customColumns,
- *       options.columnIdToTableColumn,
- *       'custom-export.csv'
- *     );
- *   }}
- * />
- * ```
- */
-export interface ExportOptions<TData extends DataRecord> {
-  /** Filtered table rows with getValue() method for proper accessorFn evaluation */
-  tableRows: Array<{
-    original: TData;
-    getValue: (columnId: string) => unknown;
-    id: string;
-  }>;
-  /** All column definitions passed to the DataTable */
-  allColumns: DataTableColumn<TData>[];
-  /** Currently visible columns in the table */
-  visibleColumns: DataTableColumn<TData>[];
-  /** Mapping of column IDs to TanStack table column instances (for getValue() calls) */
-  columnIdToTableColumn: Map<string, unknown>;
-  /** Raw data array (unfiltered) */
-  data: TData[];
-  /** Default filename generated from table title */
-  filename: string;
-  /** TanStack table instance for advanced operations */
-  table: unknown; // Using unknown to avoid tight coupling with TanStack types
-}
-
-// ============================================================================
-// MAIN COMPONENT PROPS
-// ============================================================================
-
-/**
- * Enhanced DataTable props with unified feature configuration and MANDATORY RBAC
- */
-export interface DataTableProps<TData extends DataRecord> {
-  // Core data
-  /** Array of data to display */
-  data: TData[];
-  /** Column definitions - supports both DataTableColumn and SimpleColumn formats */
-  columns: (DataTableColumn<TData> | SimpleColumn<TData>)[];
-  
-  // MANDATORY RBAC - NO OPTIONAL
-  /** RBAC configuration - REQUIRED for all DataTables */
-  rbac: DataTableRBACConfig;
-
-  // Display
-  /** Table title */
-  title?: string;
-  /** Table description */
-  description?: string;
-  /** Theme variant */
-  variant?: 'default' | 'compact' | 'spacious';
-  /** Custom CSS classes */
-  className?: string;
-
-  // NEW: Unified feature configuration
-  /** Feature configuration - all features are disabled by default */
-  features?: DataTableFeatureConfig;
-
-  // Hierarchical Configuration
-  /** Hierarchical parent/child row configuration */
-  hierarchical?: HierarchicalConfig;
-
-  // Performance Configuration
-  /** Performance optimization settings */
-  performance?: PerformanceConfig;
-  /** Server-side data fetching configuration */
-  serverSide?: ServerSideConfig<TData>;
-  /** Pagination mode */
-  paginationMode?: PaginationMode;
-  /** Data chunking configuration */
-  chunking?: ChunkingConfig;
-  /** Search index configuration */
-  searchIndex?: SearchIndexConfig;
-  /** Initial page size for pagination */
-  initialPageSize?: number;
-
-  // Default state configuration
-  /** Initial grouping configuration - columns to group by on load */
-  defaultGrouping?: string[];
-  /** Initial sorting configuration - sort state to apply on load */
-  defaultSorting?: Array<{
-    id: string;
-    desc: boolean;
-  }>;
-  /** Initial column visibility state - columns with value `false` will be hidden by default. Keys should match column `id` or `accessorKey`. */
-  initialColumnVisibility?: Record<string, boolean>;
-
-  // Event handlers
-  /** Row edit handler */
-  onEditRow?: (row: TData, data: Partial<TData>) => void;
-  /** Row deletion handler */
-  onDeleteRow?: (row: TData) => void;
-  /** Row creation handler */
-  onCreateRow?: (data: Partial<TData>) => void;
-  /** Import handler */
-  onImport?: (data: TData[]) => void | Promise<void>;
-  /** 
-   * Export handler - allows custom export logic with full control over columns and data
-   * 
-   * If not provided, defaults to exporting all visible columns.
-   * 
-   * @example
-   * ```tsx
-   * // Custom export with specific columns
-   * onExport={async (options) => {
-   *   const exportColumns = options.allColumns.filter(col => 
-   *     ['name', 'email'].includes(col.accessorKey || '')
-   *   );
-   *   await exportToCSVWithTableRows(
-   *     options.tableRows,
-   *     exportColumns,
-   *     options.columnIdToTableColumn,
-   *     'users-export.csv'
-   *   );
-   * }}
-   * ```
-   */
-  onExport?: (options: ExportOptions<TData>) => void | Promise<void>;
-  /** Row selection change handler */
-  onRowSelectionChange?: (selection: Record<string, boolean>) => void;
-  /** Controlled selection state */
-  selection?: Record<string, boolean>;
-  /** Bulk delete selected rows handler */
-  onDeleteSelected?: (selectedRows: Record<string, boolean>) => void;
-
-  // Utilities
-  /** Function to get unique ID for each row */
-  getRowId?: GetRowId<TData>;
-  /** Loading state */
-  isLoading?: boolean;
-  /** Empty state customization */
-  emptyState?: EmptyStateConfig;
-  /** Aggregate configurations */
-  aggregates?: AggregateConfig[];
-
-  // Import Modal Configuration
-  /** Import modal configuration */
-  importModalConfig?: ImportModalConfig;
-}
-
-