@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/components/DataTable/types/features.ts

@@ -0,0 +1,81 @@
+/**
+ * @file DataTable feature configuration type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import React from 'react';
+
+/**
+ * Unified feature configuration for DataTable
+ * All features are disabled by default and must be explicitly enabled
+ */
+export interface DataTableFeatureFlags {
+  search: boolean;
+  pagination: boolean;
+  sorting: boolean;
+  filtering: boolean;
+  import: boolean;
+  export: boolean;
+  selection: boolean;
+  creation: boolean;
+  editing: boolean;
+  deletion: boolean;
+  deleteSelected: boolean;
+  grouping: boolean;
+  columnVisibility: boolean;
+  columnReordering: boolean;
+  hierarchical: boolean;
+}
+
+/**
+ * Consumer-facing feature configuration. All properties are optional and will be
+ * merged with defaultDataTableFeatures at runtime.
+ */
+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.
+ * Downstream consumers can rely on every flag being present.
+ */
+export function normalizeDataTableFeatures(
+  features?: DataTableFeatureConfig
+): NormalizedDataTableFeatureConfig {
+  return {
+    ...defaultDataTableFeatures,
+    ...(features ?? {}),
+  };
+}
+
+/** Empty state configuration */
+export interface EmptyStateConfig {
+  title?: string;
+  description?: string;
+  icon?: React.ComponentType<{ className?: string }>;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+}

package/src/components/DataTable/types/hierarchical.ts

@@ -0,0 +1,44 @@
+/**
+ * @file DataTable hierarchical type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import type { DataRecord } from './base';
+
+/** 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;
+}
+
+/** Runtime state for hierarchical expand/collapse (injected by useHierarchicalState). */
+export interface HierarchicalState {
+  isExpanded: (rowId: string) => boolean;
+  hasChildren: (rowId: string) => boolean;
+  getChildrenCount: (rowId: string) => number;
+  toggleRow: (rowId: string) => void;
+}
+
+/** 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;
+}
+
+/** Hierarchical config with optional runtime state (used by RowComponent). */
+export type HierarchicalConfigWithState = HierarchicalConfig & { state?: HierarchicalState };

package/src/components/DataTable/types/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @file DataTable type definitions - barrel export
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ *
+ * Import base first so TanStack module augmentation is applied.
+ */
+
+import './base';
+
+export type { CellValue, DataRecord, RowId, GetRowId } from './base';
+export type { HierarchicalDataRow, HierarchicalConfig, HierarchicalState, HierarchicalConfigWithState } from './hierarchical';
+export type { PerformanceConfig, SearchIndexConfig, ChunkingConfig } from './performance';
+export type {
+  PaginationMode,
+  ServerSideParams,
+  ServerSideResponse,
+  ServerSideConfig,
+  PaginationConfig,
+  PaginationCallbacks,
+} from './pagination';
+export type {
+  AggregateConfig,
+  DataTableColumn,
+  EditableColumnDef,
+  SimpleColumn,
+} from './columns';
+export type {
+  DataTableFeatureFlags,
+  DataTableFeatureConfig,
+  NormalizedDataTableFeatureConfig,
+  EmptyStateConfig,
+} from './features';
+export { defaultDataTableFeatures, normalizeDataTableFeatures } from './features';
+export type {
+  ActionCondition,
+  DataTableAction,
+  RowActionsProp,
+  DataTableToolbarButton,
+} from './actions';
+export type { DataTableRBACConfig, DataTableRowPermissions, DataTablePermissionSlot, RBACContext } from './rbac';
+export type { ExportOptions } from './export';
+export type { DataTableProps } from './props';

package/src/components/DataTable/types/pagination.ts

@@ -0,0 +1,85 @@
+/**
+ * @file DataTable pagination type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import type { SortingState, ColumnFiltersState, GroupingState } from '@tanstack/react-table';
+import type { DataRecord } from './base';
+
+/** Pagination mode determines how data is handled */
+export type PaginationMode = 'client' | 'server' | 'hybrid';
+
+/** 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;
+}
+
+/** 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;
+}
+
+/** 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;
+}

package/src/components/DataTable/types/performance.ts

@@ -0,0 +1,47 @@
+/**
+ * @file DataTable performance type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+/** 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;
+}
+
+/** 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;
+}
+
+/** 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;
+}

package/src/components/DataTable/types/props.ts

@@ -0,0 +1,62 @@
+/**
+ * @file DataTable props type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import type { DataRecord, GetRowId } from './base';
+import type { HierarchicalConfig } from './hierarchical';
+import type { PerformanceConfig, SearchIndexConfig, ChunkingConfig } from './performance';
+import type { PaginationMode, ServerSideConfig } from './pagination';
+import type { DataTableColumn, SimpleColumn, AggregateConfig } from './columns';
+import type { DataTableFeatureConfig, EmptyStateConfig } from './features';
+import type { DataTableRBACConfig } from './rbac';
+import type { ExportOptions } from './export';
+import type { ImportModalConfig } from '../ui/modals/ImportModal';
+import type { ImportHandlerResult } from '../ui/modals/importModalPersistence';
+
+/**
+ * Enhanced DataTable props with unified feature configuration and MANDATORY RBAC
+ */
+export interface DataTableProps<TData extends DataRecord> {
+  /** Array of data to display */
+  data: TData[];
+  /** Column definitions - supports both DataTableColumn and SimpleColumn formats */
+  columns: (DataTableColumn<TData> | SimpleColumn<TData>)[];
+  /** RBAC configuration - REQUIRED for all DataTables */
+  rbac: DataTableRBACConfig;
+
+  title?: string;
+  description?: string;
+  variant?: 'default' | 'compact' | 'spacious';
+  className?: string;
+  features?: DataTableFeatureConfig;
+  hierarchical?: HierarchicalConfig;
+  performance?: PerformanceConfig;
+  serverSide?: ServerSideConfig<TData>;
+  paginationMode?: PaginationMode;
+  chunking?: ChunkingConfig;
+  searchIndex?: SearchIndexConfig;
+  initialPageSize?: number;
+
+  defaultGrouping?: string[];
+  defaultSorting?: Array<{ id: string; desc: boolean }>;
+  initialColumnVisibility?: Record<string, boolean>;
+
+  onEditRow?: (row: TData, data: Partial<TData>) => void;
+  onDeleteRow?: (row: TData) => void;
+  onCreateRow?: (data: Partial<TData>) => void;
+  onImport?: (data: TData[]) => ImportHandlerResult;
+  onExport?: (options: ExportOptions<TData>) => void | Promise<void>;
+  onRowSelectionChange?: (selection: Record<string, boolean>) => void;
+  selection?: Record<string, boolean>;
+  onDeleteSelected?: (selectedRows: Record<string, boolean>) => void;
+
+  getRowId?: GetRowId<TData>;
+  isLoading?: boolean;
+  emptyState?: EmptyStateConfig;
+  aggregates?: AggregateConfig[];
+  importModalConfig?: ImportModalConfig;
+  /** Called when the import modal is closed (e.g. to refetch table data). */
+  onImportModalClose?: () => void;
+}

package/src/components/DataTable/types/rbac.ts

@@ -0,0 +1,45 @@
+/**
+ * @file DataTable RBAC type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+/** Single permission slot (can + loading) used by row-level permission checks. */
+export interface DataTablePermissionSlot {
+  can: boolean;
+  isLoading: boolean;
+}
+
+/** Row-level permissions passed to RowComponent for action visibility. */
+export interface DataTableRowPermissions {
+  canRead: DataTablePermissionSlot;
+  canCreate: DataTablePermissionSlot;
+  canUpdate: DataTablePermissionSlot;
+  canDelete: DataTablePermissionSlot;
+  canExport: DataTablePermissionSlot;
+  canImport: DataTablePermissionSlot;
+}
+
+/**
+ * RBAC configuration for DataTable - MANDATORY for all DataTables
+ */
+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;
+}