@superdangerous/app-framework 4.14.0 → 4.15.1

package/ui/data-table/components/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Data Table Components
+ *
+ * Reusable components for building data tables:
+ * - DataTable: Full-featured generic data table
+ * - DataTablePage: Full-page layout with header controls
+ * - PaginationControls: Compact inline pagination
+ * - Pagination: Full pagination with page numbers
+ * - BatchActionsBar: Multi-select action bar
+ * - ColumnVisibility: Column toggle dropdown
+ * - TableFilters: Search and filter controls
+ */
+
+export { DataTable } from './DataTable';
+export type {
+  DataTableProps,
+  ColumnDef,
+  ColumnWidth,
+  ColumnVisibility as ColumnVisibilityConfig,
+  HeaderCellProps,
+  CellProps,
+  ExternalPaginationState,
+  ColumnConfigCompat,
+  ColumnSizeConfig,
+} from './types';
+
+export { DataTablePage } from './DataTablePage';
+export type { DataTablePageProps, FilterOption } from './DataTablePage';
+
+export { PaginationControls } from './PaginationControls';
+export type { PaginationControlsProps } from './PaginationControls';
+
+export { Pagination } from './Pagination';
+
+export { BatchActionsBar } from './BatchActionsBar';
+export type { BatchActionsBarProps } from './BatchActionsBar';
+
+export { ColumnVisibility } from './ColumnVisibility';
+
+export { TableFilters } from './TableFilters';
+export type { TableFiltersProps, FilterOption as TableFilterOption } from './TableFilters';

package/ui/data-table/components/types.ts

@@ -0,0 +1,181 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Column width configuration
+ */
+export interface ColumnWidth {
+  default: number;
+  min: number;
+  max?: number;
+}
+
+/**
+ * Column visibility configuration
+ */
+export interface ColumnVisibility {
+  default: boolean;
+  locked?: boolean;  // If true, column cannot be hidden
+}
+
+/**
+ * Props passed to header cell render function
+ */
+export interface HeaderCellProps {
+  columnId: string;
+  isSorted: boolean;
+  sortDirection?: 'asc' | 'desc';
+}
+
+/**
+ * Props passed to cell render function
+ */
+export interface CellProps {
+  columnId: string;
+  isDragging: boolean;
+}
+
+/**
+ * Column definition for DataTable
+ */
+export interface ColumnDef<T> {
+  /** Unique column identifier */
+  id: string;
+
+  /** Header content - string or render function */
+  header: string | ((props: HeaderCellProps) => ReactNode);
+
+  /** Cell content render function */
+  cell: (item: T, props: CellProps) => ReactNode;
+
+  /** Key to use for sorting (if sortable) */
+  sortKey?: string;
+
+  /** Width configuration */
+  width?: ColumnWidth;
+
+  /** Visibility configuration */
+  visibility?: ColumnVisibility;
+
+  /** Additional CSS class for cells */
+  className?: string;
+
+  /** Whether this column should use column style from resize hook */
+  resizable?: boolean;
+}
+
+// DragState is exported from ../hooks/useColumnOrder
+
+/**
+ * External pagination state (from usePagination hook)
+ */
+export interface ExternalPaginationState<T> {
+  paginatedData: T[];
+  page: number;
+  pageSize: number;
+  totalPages: number;
+  totalItems: number;
+  startIndex: number;
+  endIndex: number;
+  canGoNext: boolean;
+  canGoPrev: boolean;
+  pageSizeOptions: number[];
+  setPage: (page: number) => void;
+  setPageSize: (size: number) => void;
+  nextPage: () => void;
+  prevPage: () => void;
+}
+
+/**
+ * DataTable props
+ */
+export interface DataTableProps<T> {
+  /** Data array to display */
+  data: T[];
+
+  /** Column definitions */
+  columns: ColumnDef<T>[];
+
+  /** Storage key for persisting table state (column widths, order, visibility) */
+  storageKey: string;
+
+  /** Function to get unique ID from item */
+  getRowId: (item: T) => string;
+
+  // Selection
+  /** Enable row selection with checkboxes */
+  selectable?: boolean;
+  /** Set of selected row IDs */
+  selectedIds?: Set<string>;
+  /** Callback when selection changes */
+  onSelectionChange?: (ids: Set<string>) => void;
+
+  // Row interactions
+  /** Callback when row is clicked */
+  onRowClick?: (item: T) => void;
+  /** Callback when row is right-clicked (for context menu) */
+  onRowContextMenu?: (item: T, position: { x: number; y: number }) => void;
+
+  // Sorting
+  /** Current sort field */
+  sortField?: string;
+  /** Current sort order */
+  sortOrder?: 'asc' | 'desc';
+  /** Callback when sort changes */
+  onSort?: (field: string) => void;
+
+  // Actions column
+  /** Render function for actions column (always last, sticky) */
+  actionsColumn?: (item: T) => ReactNode;
+  /** Width for actions column */
+  actionsColumnWidth?: number;
+
+  // Pagination
+  /** Page size for pagination (used when no external pagination provided) */
+  pageSize?: number;
+  /** External pagination state from usePagination hook (overrides internal pagination) */
+  pagination?: ExternalPaginationState<T>;
+  /** Hide the built-in pagination controls (use when pagination is shown elsewhere) */
+  hidePagination?: boolean;
+
+  // Styling
+  /** Additional CSS class for table container */
+  className?: string;
+  /** Function to compute row CSS class */
+  rowClassName?: (item: T) => string;
+
+  // Features
+  /** Enable header right-click for column visibility menu */
+  enableHeaderContextMenu?: boolean;
+  /** Columns that cannot be reordered */
+  lockedColumns?: string[];
+  /** Default column order (if not persisted) */
+  defaultColumnOrder?: string[];
+
+  // Loading state
+  /** Show loading indicator */
+  loading?: boolean;
+
+  // Empty state
+  /** Content to show when no data */
+  emptyState?: ReactNode;
+}
+
+/**
+ * Column config for visibility hook (for compatibility)
+ */
+export interface ColumnConfigCompat {
+  id: string;
+  label: string;
+  defaultVisible?: boolean;
+  locked?: boolean;
+}
+
+/**
+ * Column config for resize hook (for compatibility)
+ */
+export interface ColumnSizeConfig {
+  key: string;
+  defaultWidth: number;
+  minWidth: number;
+  maxWidth?: number;
+}

package/ui/data-table/hooks/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Data Table Hooks
+ *
+ * Comprehensive hooks for building data tables with:
+ * - Pagination with localStorage persistence
+ * - Column visibility toggling
+ * - Column resizing with drag handles
+ * - Column reordering with drag-and-drop
+ */
+
+export { usePagination } from './usePagination';
+export { useColumnVisibility } from './useColumnVisibility';
+export type { ColumnConfig, ColumnVisibilityState } from './useColumnVisibility';
+export { useResizableColumns } from './useResizableColumns';
+export type { ResizableColumnResult } from './useResizableColumns';
+export { useColumnOrder, useColumnDragDrop } from './useColumnOrder';
+export type { ColumnOrderConfig, DragState } from './useColumnOrder';

package/ui/data-table/hooks/useColumnOrder.ts

@@ -0,0 +1,233 @@
+import { useState, useCallback, useEffect } from 'react';
+
+export interface ColumnOrderConfig {
+  id: string;
+  label: string;
+  locked?: boolean; // Locked columns can't be moved
+}
+
+interface UseColumnOrderOptions {
+  storageKey: string;
+  defaultOrder: string[];
+}
+
+interface UseColumnOrderReturn {
+  columnOrder: string[];
+  moveColumn: (fromIndex: number, toIndex: number) => void;
+  moveColumnById: (columnId: string, direction: 'left' | 'right') => void;
+  resetOrder: () => void;
+  getOrderedColumns: <T extends { id: string }>(columns: T[]) => T[];
+}
+
+/**
+ * Hook for managing column order with localStorage persistence
+ */
+export function useColumnOrder({
+  storageKey,
+  defaultOrder,
+}: UseColumnOrderOptions): UseColumnOrderReturn {
+  const [columnOrder, setColumnOrder] = useState<string[]>(() => {
+    try {
+      const stored = localStorage.getItem(storageKey);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        const storedSet = new Set(parsed);
+        const defaultSet = new Set(defaultOrder);
+
+        // Remove old columns that aren't in default anymore
+        const validStored = parsed.filter((col: string) => defaultSet.has(col));
+
+        // Find missing columns and insert them at their default positions
+        const missingColumns = defaultOrder.filter(col => !storedSet.has(col));
+
+        if (missingColumns.length > 0) {
+          // Build new order by inserting missing columns at their default positions
+          const result = [...validStored];
+          for (const missing of missingColumns) {
+            const defaultIndex = defaultOrder.indexOf(missing);
+            // Find the best insertion point based on surrounding columns in default order
+            let insertAt = result.length;
+            for (let i = 0; i < result.length; i++) {
+              const currentDefaultIndex = defaultOrder.indexOf(result[i]);
+              if (currentDefaultIndex > defaultIndex) {
+                insertAt = i;
+                break;
+              }
+            }
+            result.splice(insertAt, 0, missing);
+          }
+          return result;
+        }
+
+        return validStored.length > 0 ? validStored : defaultOrder;
+      }
+    } catch (e) {
+      console.warn('Failed to load column order from localStorage:', e);
+    }
+    return defaultOrder;
+  });
+
+  // Persist to localStorage
+  useEffect(() => {
+    try {
+      localStorage.setItem(storageKey, JSON.stringify(columnOrder));
+    } catch (e) {
+      console.warn('Failed to save column order to localStorage:', e);
+    }
+  }, [storageKey, columnOrder]);
+
+  const moveColumn = useCallback((fromIndex: number, toIndex: number) => {
+    if (fromIndex === toIndex) return;
+
+    setColumnOrder(prev => {
+      const newOrder = [...prev];
+      const [removed] = newOrder.splice(fromIndex, 1);
+      newOrder.splice(toIndex, 0, removed);
+      return newOrder;
+    });
+  }, []);
+
+  const moveColumnById = useCallback((columnId: string, direction: 'left' | 'right') => {
+    setColumnOrder(prev => {
+      const currentIndex = prev.indexOf(columnId);
+      if (currentIndex === -1) return prev;
+
+      const newIndex = direction === 'left'
+        ? Math.max(0, currentIndex - 1)
+        : Math.min(prev.length - 1, currentIndex + 1);
+
+      if (currentIndex === newIndex) return prev;
+
+      const newOrder = [...prev];
+      const [removed] = newOrder.splice(currentIndex, 1);
+      newOrder.splice(newIndex, 0, removed);
+      return newOrder;
+    });
+  }, []);
+
+  const resetOrder = useCallback(() => {
+    setColumnOrder(defaultOrder);
+  }, [defaultOrder]);
+
+  const getOrderedColumns = useCallback(<T extends { id: string }>(columns: T[]): T[] => {
+    const columnMap = new Map(columns.map(col => [col.id, col]));
+    return columnOrder
+      .map(id => columnMap.get(id))
+      .filter((col): col is T => col !== undefined);
+  }, [columnOrder]);
+
+  return {
+    columnOrder,
+    moveColumn,
+    moveColumnById,
+    resetOrder,
+    getOrderedColumns,
+  };
+}
+
+/**
+ * Drag and drop helpers for column reordering
+ */
+export interface DragState {
+  isDragging: boolean;
+  draggedId: string | null;
+  dropIndex: number | null; // Index where the column will be inserted
+}
+
+export function useColumnDragDrop(
+  columnOrder: string[],
+  moveColumn: (from: number, to: number) => void,
+  lockedColumns: string[] = []
+) {
+  const [dragState, setDragState] = useState<DragState>({
+    isDragging: false,
+    draggedId: null,
+    dropIndex: null,
+  });
+
+  const handleDragStart = useCallback((columnId: string) => {
+    if (lockedColumns.includes(columnId)) return;
+    setDragState({
+      isDragging: true,
+      draggedId: columnId,
+      dropIndex: null,
+    });
+  }, [lockedColumns]);
+
+  const handleDragOver = useCallback((columnId: string, e: React.DragEvent) => {
+    if (lockedColumns.includes(columnId)) return;
+
+    const targetIndex = columnOrder.indexOf(columnId);
+    if (targetIndex === -1) return;
+
+    // Determine drop index based on mouse position relative to column center
+    const rect = e.currentTarget.getBoundingClientRect();
+    const midpoint = rect.left + rect.width / 2;
+    const dropIndex = e.clientX < midpoint ? targetIndex : targetIndex + 1;
+
+    setDragState(prev => ({
+      ...prev,
+      dropIndex,
+    }));
+  }, [lockedColumns, columnOrder]);
+
+  const handleDrop = useCallback(() => {
+    if (!dragState.draggedId || dragState.dropIndex === null) {
+      setDragState({ isDragging: false, draggedId: null, dropIndex: null });
+      return;
+    }
+
+    const fromIndex = columnOrder.indexOf(dragState.draggedId);
+    let toIndex = dragState.dropIndex;
+
+    // Adjust if moving from before the drop position
+    if (fromIndex < toIndex) {
+      toIndex = toIndex - 1;
+    }
+
+    if (fromIndex !== -1 && toIndex !== -1 && fromIndex !== toIndex) {
+      moveColumn(fromIndex, toIndex);
+    }
+
+    setDragState({ isDragging: false, draggedId: null, dropIndex: null });
+  }, [dragState.draggedId, dragState.dropIndex, columnOrder, moveColumn]);
+
+  const handleDragEnd = useCallback(() => {
+    setDragState({ isDragging: false, draggedId: null, dropIndex: null });
+  }, []);
+
+  const getDragHandleProps = useCallback((columnId: string) => ({
+    draggable: !lockedColumns.includes(columnId),
+    onDragStart: (e: React.DragEvent) => {
+      if (lockedColumns.includes(columnId)) {
+        e.preventDefault();
+        return;
+      }
+      e.dataTransfer.effectAllowed = 'move';
+      handleDragStart(columnId);
+    },
+    onDragOver: (e: React.DragEvent) => {
+      e.preventDefault();
+      e.dataTransfer.dropEffect = 'move';
+      handleDragOver(columnId, e);
+    },
+    onDrop: (e: React.DragEvent) => {
+      e.preventDefault();
+      handleDrop();
+    },
+    onDragEnd: handleDragEnd,
+  }), [lockedColumns, handleDragStart, handleDragOver, handleDrop, handleDragEnd]);
+
+  // Helper to check if drop indicator should show on the left of a column
+  const showDropIndicator = useCallback((columnId: string) => {
+    if (!dragState.isDragging || dragState.dropIndex === null) return false;
+    const columnIndex = columnOrder.indexOf(columnId);
+    return columnIndex === dragState.dropIndex;
+  }, [dragState.isDragging, dragState.dropIndex, columnOrder]);
+
+  return {
+    dragState,
+    getDragHandleProps,
+    showDropIndicator,
+  };
+}

package/ui/data-table/hooks/useColumnVisibility.ts

@@ -0,0 +1,128 @@
+import { useState, useEffect, useCallback } from 'react';
+
+export interface ColumnConfig {
+  id: string;
+  label: string;
+  defaultVisible?: boolean;
+  locked?: boolean; // If true, column cannot be hidden
+}
+
+export interface ColumnVisibilityState {
+  [key: string]: boolean;
+}
+
+interface UseColumnVisibilityOptions {
+  columns: ColumnConfig[];
+  storageKey: string;
+}
+
+interface UseColumnVisibilityReturn {
+  visibleColumns: ColumnVisibilityState;
+  isColumnVisible: (columnId: string) => boolean;
+  toggleColumn: (columnId: string) => void;
+  showAllColumns: () => void;
+  hideAllColumns: () => void;
+  columns: ColumnConfig[];
+}
+
+export function useColumnVisibility({
+  columns,
+  storageKey,
+}: UseColumnVisibilityOptions): UseColumnVisibilityReturn {
+  const fullStorageKey = `column-visibility-${storageKey}`;
+
+  // Initialize state from localStorage or defaults (with SSR guard)
+  const [visibleColumns, setVisibleColumns] = useState<ColumnVisibilityState>(() => {
+    // Default state
+    const defaults: ColumnVisibilityState = {};
+    columns.forEach(col => {
+      defaults[col.id] = col.defaultVisible !== false;
+    });
+
+    // SSR guard - localStorage is not available on server
+    if (typeof window === 'undefined') {
+      return defaults;
+    }
+
+    try {
+      const stored = localStorage.getItem(fullStorageKey);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        // Merge with defaults to handle new columns
+        const merged: ColumnVisibilityState = {};
+        columns.forEach(col => {
+          if (col.locked) {
+            merged[col.id] = true;
+          } else if (parsed[col.id] !== undefined) {
+            merged[col.id] = parsed[col.id];
+          } else {
+            merged[col.id] = col.defaultVisible !== false;
+          }
+        });
+        return merged;
+      }
+    } catch (e) {
+      console.error('Error loading column visibility state:', e);
+    }
+
+    return defaults;
+  });
+
+  // Persist to localStorage (with SSR guard)
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    try {
+      localStorage.setItem(fullStorageKey, JSON.stringify(visibleColumns));
+    } catch (e) {
+      console.error('Error saving column visibility state:', e);
+    }
+  }, [visibleColumns, fullStorageKey]);
+
+  const isColumnVisible = useCallback(
+    (columnId: string): boolean => {
+      const col = columns.find(c => c.id === columnId);
+      if (col?.locked) return true;
+      return visibleColumns[columnId] !== false;
+    },
+    [visibleColumns, columns]
+  );
+
+  const toggleColumn = useCallback(
+    (columnId: string) => {
+      const col = columns.find(c => c.id === columnId);
+      if (col?.locked) return; // Cannot toggle locked columns
+
+      setVisibleColumns(prev => ({
+        ...prev,
+        [columnId]: !prev[columnId],
+      }));
+    },
+    [columns]
+  );
+
+  const showAllColumns = useCallback(() => {
+    const allVisible: ColumnVisibilityState = {};
+    columns.forEach(col => {
+      allVisible[col.id] = true;
+    });
+    setVisibleColumns(allVisible);
+  }, [columns]);
+
+  const hideAllColumns = useCallback(() => {
+    const onlyLocked: ColumnVisibilityState = {};
+    columns.forEach(col => {
+      onlyLocked[col.id] = col.locked === true;
+    });
+    setVisibleColumns(onlyLocked);
+  }, [columns]);
+
+  return {
+    visibleColumns,
+    isColumnVisible,
+    toggleColumn,
+    showAllColumns,
+    hideAllColumns,
+    columns,
+  };
+}