@openmrs/esm-report-builder 0.1.1-pre.101

package/src/features/report-visualizer/components/TableView/ReportTable.tsx

@@ -0,0 +1,253 @@
+/**
+ * Report Table Component
+ *
+ * DataTable for displaying report results with sticky header.
+ * Supports pagination, sorting, column visibility controls, and status color coding.
+ *
+ * Phase 7: Complete column visibility menu integration
+ */
+import React, { useState, useMemo } from 'react';
+import {
+  DataTable,
+  Table,
+  TableBody,
+  TableCell,
+  TableContainer,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Pagination,
+  Button,
+  Tile,
+  Tag,
+} from '@carbon/react';
+import { Renew as Refresh } from '@carbon/react/icons';
+import { getStatusTagColor, isStatusColumn } from '../../utils/status-colors';
+import ColumnVisibilityMenu from './ColumnVisibilityMenu';
+
+interface ReportTableProps {
+  data: Record<string, any>[];
+  columns: string[];
+  loading?: boolean;
+  onRefresh?: () => void;
+  title?: string;
+  description?: string;
+}
+
+const ReportTable: React.FC<ReportTableProps> = ({
+  data,
+  columns,
+  loading,
+  onRefresh,
+  title,
+  description,
+}) => {
+  // Pagination state
+  const [currentPage, setCurrentPage] = useState(1);
+  const [pageSize, setPageSize] = useState(25);
+
+  // Column visibility state
+  const [hiddenColumns, setHiddenColumns] = useState<Set<string>>(new Set());
+
+  // Calculate pagination and add unique IDs
+  const { paginatedData, totalPages } = useMemo(() => {
+    const startIndex = (currentPage - 1) * pageSize;
+    const endIndex = startIndex + pageSize;
+    const pageData = data.slice(startIndex, endIndex);
+    const total = Math.ceil(data.length / pageSize);
+    // Add unique IDs required by Carbon DataTable
+    const rowsWithIds = pageData.map((row, index) => ({
+      ...row,
+      id: `row-${startIndex + index}`,
+    }));
+    return { paginatedData: rowsWithIds, totalPages: total };
+  }, [data, currentPage, pageSize]);
+
+  // Filter visible columns
+  const visibleColumns = useMemo(() => {
+    return columns.filter(col => !hiddenColumns.has(col));
+  }, [columns, hiddenColumns]);
+
+  const toggleColumnVisibility = (columnName: string) => {
+    setHiddenColumns(prev => {
+      const newSet = new Set(prev);
+      if (newSet.has(columnName)) {
+        newSet.delete(columnName);
+      } else {
+        newSet.add(columnName);
+      }
+      return newSet;
+    });
+  };
+
+  const handleShowAllColumns = () => {
+    setHiddenColumns(new Set());
+  };
+
+  const handleHideAllColumns = () => {
+    setHiddenColumns(new Set(columns));
+  };
+
+  const renderCellValue = (columnName: string, value: any) => {
+    if (value == null) return '—';
+
+    // Check if this is a status column
+    if (isStatusColumn(columnName)) {
+      const colorProps = getStatusTagColor(value);
+      return <Tag {...colorProps}>{String(value)}</Tag>;
+    }
+
+    // Handle Date objects
+    if (value instanceof Date) {
+      return value.toLocaleDateString();
+    }
+
+    // Handle serialized Java date objects (from backend serialization)
+    // Format: {year: 2004, month: 1, day: 1, hour: 0, minute: 0, second: 0}
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      const { year, month, day, date } = value as any;
+      // Check if this looks like a serialized date
+      if (typeof year === 'number' && typeof month === 'number') {
+        const d = (day || date) || 1;
+        const dateObj = new Date(year, month - 1, d);
+        if (!isNaN(dateObj.getTime())) {
+          return dateObj.toLocaleDateString();
+        }
+      }
+    }
+
+    // Handle date arrays (like [2004,1,1,0,0] from legacy serialization)
+    if (Array.isArray(value) && value.length >= 3) {
+      const [year, month, day] = value;
+      // Check if it looks like a date array (numeric values)
+      if (typeof year === 'number' && typeof month === 'number' && typeof day === 'number') {
+        // Java months are 1-based (1=Jan), JavaScript months are 0-based (0=Jan)
+        // So we subtract 1 from the month
+        const date = new Date(year, month - 1, day);
+        // Sanity check: dates like year=-153 or negative values should be shown as-is
+        if (year > 1000 && !isNaN(date.getTime())) {
+          return date.toLocaleDateString();
+        }
+      }
+    }
+
+    // Return string value for everything else
+    return String(value);
+  };
+
+  if (loading) {
+    return (
+      <Tile style={{ width: '100%', minHeight: '200px', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+        Loading data...
+      </Tile>
+    );
+  }
+
+  if (data.length === 0) {
+    return (
+      <Tile style={{ width: '100%', minHeight: '200px' }}>
+        <h4>No results</h4>
+        <p>No data found for the current parameters.</p>
+        {onRefresh && (
+          <Button
+            kind="ghost"
+            size="sm"
+            renderIcon={Refresh}
+            onClick={onRefresh}
+            style={{ marginTop: '1rem' }}
+          >
+            Refresh
+          </Button>
+        )}
+      </Tile>
+    );
+  }
+
+  return (
+    <div style={{ width: '100%' }}>
+      {/* Table with toolbar and pagination */}
+      <DataTable
+        rows={paginatedData}
+        headers={visibleColumns.map((col) => ({ key: col, header: col }))}
+        render={({
+          rows,
+          headers,
+          getHeaderProps,
+          getRowProps,
+          getTableProps,
+        }) => (
+          <TableContainer title={title} description={description}>
+            <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '1rem', flexWrap: 'wrap', gap: '0.5rem' }}>
+              <div>
+                <strong>{data.length} total results</strong>
+              </div>
+              <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
+                {columns.length > 1 && (
+                  <ColumnVisibilityMenu
+                    columns={columns}
+                    hiddenColumns={hiddenColumns}
+                    onToggleColumn={toggleColumnVisibility}
+                    onShowAll={handleShowAllColumns}
+                    onHideAll={handleHideAllColumns}
+                    disabled={loading}
+                  />
+                )}
+                {onRefresh && (
+                  <Button
+                    kind="ghost"
+                    size="sm"
+                    renderIcon={Refresh}
+                    iconDescription="Refresh data"
+                    onClick={onRefresh}
+                    disabled={loading}
+                  >
+                    Refresh
+                  </Button>
+                )}
+              </div>
+            </div>
+            <Table {...getTableProps()}>
+              <TableHead>
+                <TableRow>
+                  {headers.map((header) => (
+                    <TableHeader {...getHeaderProps({ header })}>
+                      {header.header}
+                    </TableHeader>
+                  ))}
+                </TableRow>
+              </TableHead>
+              <TableBody>
+                {rows.map((row) => (
+                  <TableRow {...getRowProps({ row })}>
+                    {row.cells.map((cell) => {
+                      const columnName = cell.info.header;
+                      return (
+                        <TableCell key={cell.id}>
+                          {renderCellValue(columnName, cell.value)}
+                        </TableCell>
+                      );
+                    })}
+                  </TableRow>
+                ))}
+              </TableBody>
+            </Table>
+            {totalPages > 1 && (
+              <Pagination
+                page={currentPage}
+                pageSize={pageSize}
+                pageSizes={[10, 25, 50, 100]}
+                totalItems={data.length}
+                onChange={({ page, pageSize: newSize }) => {
+                  setCurrentPage(page);
+                  if (newSize) setPageSize(newSize);
+                }}
+              />
+            )}
+          </TableContainer>
+        )}
+      />
+    </div>
+  );
+};
+
+export default ReportTable;

package/src/features/report-visualizer/components/TableView/index.ts

@@ -0,0 +1,2 @@
+export { default as ReportTable } from './ReportTable';
+export { default as ColumnVisibilityMenu } from './ColumnVisibilityMenu';

package/src/features/report-visualizer/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useReports } from './useReports';
+export { useReportParameters } from './useReportParameters';
+export { useExplorerPreferences } from './useExplorerPreferences';
+export { useReportCapabilities } from './useReportCapabilities';

package/src/features/report-visualizer/hooks/useExplorerPreferences.ts

@@ -0,0 +1,103 @@
+/**
+ * useExplorerPreferences Hook
+ *
+ * Manages user preferences for the report visualizer using localStorage.
+ * Persists explorer state (expanded/collapsed, width, etc.) across sessions.
+ *
+ * Phase 5.3: Preferences hook
+ */
+import { useState, useCallback, useEffect } from 'react';
+import type { ReportVisualizerPreferences } from '../types';
+
+const STORAGE_KEY = 'reportVisualizer.preferences';
+
+const DEFAULT_PREFERENCES: ReportVisualizerPreferences = {
+  explorerExpanded: true,
+  explorerWidth: 350,
+  rowsPerPage: 25,
+  lastActiveView: undefined,
+};
+
+/**
+ * Hook for managing report visualizer preferences
+ */
+export function useExplorerPreferences() {
+  const [preferences, setPreferencesState] = useState<ReportVisualizerPreferences>(DEFAULT_PREFERENCES);
+  const [isLoaded, setIsLoaded] = useState(false);
+
+  // Load preferences from localStorage on mount
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        // Merge with defaults to handle new properties
+        setPreferencesState({
+          ...DEFAULT_PREFERENCES,
+          ...parsed,
+        });
+      }
+    } catch (error) {
+      console.error('Failed to load preferences:', error);
+    } finally {
+      setIsLoaded(true);
+    }
+  }, []);
+
+  // Save preferences to localStorage whenever they change
+  useEffect(() => {
+    if (isLoaded) {
+      try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(preferences));
+      } catch (error) {
+        console.error('Failed to save preferences:', error);
+      }
+    }
+  }, [preferences, isLoaded]);
+
+  // Update specific preference(s)
+  const updatePreferences = useCallback(
+    (updates: Partial<ReportVisualizerPreferences>) => {
+      setPreferencesState((prev) => ({
+        ...prev,
+        ...updates,
+      }));
+    },
+    []
+  );
+
+  // Reset to defaults
+  const resetPreferences = useCallback(() => {
+    setPreferencesState(DEFAULT_PREFERENCES);
+  }, []);
+
+  // Individual preference setters for convenience
+  const setExplorerExpanded = useCallback((expanded: boolean) => {
+    updatePreferences({ explorerExpanded: expanded });
+  }, [updatePreferences]);
+
+  const setExplorerWidth = useCallback((width: number) => {
+    updatePreferences({ explorerWidth: width });
+  }, [updatePreferences]);
+
+  const setRowsPerPage = useCallback((rows: number) => {
+    updatePreferences({ rowsPerPage: rows });
+  }, [updatePreferences]);
+
+  const setLastActiveView = useCallback((view: string | undefined) => {
+    updatePreferences({ lastActiveView: view });
+  }, [updatePreferences]);
+
+  return {
+    preferences,
+    updatePreferences,
+    resetPreferences,
+    setExplorerExpanded,
+    setExplorerWidth,
+    setRowsPerPage,
+    setLastActiveView,
+    isLoaded,
+  };
+}
+
+export default useExplorerPreferences;

package/src/features/report-visualizer/hooks/useReportCapabilities.ts

@@ -0,0 +1,112 @@
+/**
+ * useReportCapabilities Hook
+ *
+ * Determines which views and actions are available for a given report.
+ * Based on report type and metadata.
+ *
+ * Phase 5.4: Capabilities hook
+ */
+import { useMemo } from 'react';
+import type { ReportLibraryItem, ReportCapabilities } from '../types';
+
+interface UseReportCapabilitiesResult {
+  capabilities: ReportCapabilities;
+  canTable: boolean;
+  canPivot: boolean;
+  canChart: boolean;
+  canReportLayout: boolean;
+  canExport: boolean;
+  canSendToDhis2: boolean;
+}
+
+/**
+ * Hook for determining report capabilities
+ * @param report - Report to determine capabilities for
+ */
+export function useReportCapabilities(report: ReportLibraryItem | null): UseReportCapabilitiesResult {
+  const capabilities = useMemo((): ReportCapabilities => {
+    if (!report) {
+      return {
+        table: false,
+        pivot: false,
+        chart: false,
+        reportLayout: false,
+        export: false,
+        sendToDhis2: false,
+      };
+    }
+
+    // Default capabilities
+    const caps: ReportCapabilities = {
+      table: true,
+      pivot: false,
+      chart: false,
+      reportLayout: false,
+      export: true,
+      sendToDhis2: false,
+    };
+
+    // Determine capabilities based on report type
+    const reportType = report.reportType?.toLowerCase();
+    const categoryName = report.category?.name?.toLowerCase() || report.category?.display?.toLowerCase() || '';
+
+    if (reportType === 'linelist' || reportType === 'line_list') {
+      // Linelist reports can pivot, chart, and have report layout (HTML)
+      caps.pivot = true;
+      caps.chart = true;
+      caps.reportLayout = true; // Enable HTML view for linelists
+    } else if (reportType === 'aggregate') {
+      // Aggregate reports have fixed layout, can chart, and can send to DHIS2
+      caps.reportLayout = true;
+      caps.chart = true;
+      caps.sendToDhis2 = true; // Enable DHIS2 export for aggregate reports
+    } else if (reportType === 'indicator') {
+      // Indicator reports can chart
+      caps.chart = true;
+    }
+
+    // Enable DHIS2 for specific aggregate report categories (NATIONAL REPORTS, MER INDICATOR REPORTS)
+    // These categories have renderType: "html" in the old system
+    if (categoryName.includes('national') || categoryName.includes('mer') || categoryName.includes('donor') || categoryName.includes('indicator report')) {
+      caps.sendToDhis2 = true;
+      caps.reportLayout = true; // These also have HTML layout
+    }
+
+    // Check metaJson for additional capabilities
+    if (report.metaJson) {
+      try {
+        const meta = JSON.parse(report.metaJson);
+
+        // Explicit capability overrides from metaJson
+        if (meta.capabilities) {
+          if (meta.capabilities.pivot !== undefined) caps.pivot = meta.capabilities.pivot;
+          if (meta.capabilities.chart !== undefined) caps.chart = meta.capabilities.chart;
+          if (meta.capabilities.reportLayout !== undefined) caps.reportLayout = meta.capabilities.reportLayout;
+          if (meta.capabilities.export !== undefined) caps.export = meta.capabilities.export;
+          if (meta.capabilities.sendToDhis2 !== undefined) caps.sendToDhis2 = meta.capabilities.sendToDhis2;
+        }
+
+        // Check for DHIS2 configuration
+        if (meta.dhis2 || meta.dhis2Config) {
+          caps.sendToDhis2 = true;
+        }
+      } catch (error) {
+        console.error('Failed to parse metaJson for capabilities:', error);
+      }
+    }
+
+    return caps;
+  }, [report]);
+
+  return {
+    capabilities,
+    canTable: capabilities.table,
+    canPivot: capabilities.pivot,
+    canChart: capabilities.chart,
+    canReportLayout: capabilities.reportLayout,
+    canExport: capabilities.export,
+    canSendToDhis2: capabilities.sendToDhis2,
+  };
+}
+
+export default useReportCapabilities;

package/src/features/report-visualizer/hooks/useReportParameters.ts

@@ -0,0 +1,152 @@
+/**
+ * useReportParameters Hook
+ *
+ * Manages runtime parameters for a selected report.
+ * Loads parameters from metaJson, initializes defaults, validates required fields.
+ *
+ * Phase 5.2: Parameters hook
+ */
+import { useState, useCallback, useMemo } from 'react';
+import type { LinelistParameter } from '../../../types/linelist-types';
+import type { ReportLibraryItem } from '../types';
+
+interface UseReportParametersResult {
+  parameters: LinelistParameter[];
+  values: Record<string, any>;
+  errors: Record<string, string>;
+  loading: boolean;
+  setValues: (values: Record<string, any>) => void;
+  validate: () => boolean;
+  reset: () => void;
+  clear: () => void;
+  hasParameters: boolean;
+  requiredParamsCount: number;
+}
+
+interface UseReportParametersOptions {
+  report: ReportLibraryItem | null;
+}
+
+/**
+ * Hook for managing report parameters
+ * @param options - Report to extract parameters from
+ */
+export function useReportParameters(
+  options: UseReportParametersOptions
+): UseReportParametersResult {
+  const { report } = options;
+
+  // Parse parameters from report's metaJson
+  const parameters = useMemo((): LinelistParameter[] => {
+    if (!report?.metaJson) return [];
+
+    try {
+      const meta = JSON.parse(report.metaJson);
+      if (meta?.parameters && Array.isArray(meta.parameters)) {
+        return meta.parameters;
+      }
+    } catch (error) {
+      console.error('Failed to parse metaJson:', error);
+    }
+
+    return [];
+  }, [report?.metaJson]);
+
+  // Count required parameters
+  const requiredParamsCount = useMemo(() => {
+    return parameters.filter((p) => p.required).length;
+  }, [parameters]);
+
+  const hasParameters = parameters.length > 0;
+
+  // Initialize parameter values with defaults
+  const initialValues = useMemo((): Record<string, any> => {
+    const defaults: Record<string, any> = {};
+    const today = new Date().toISOString().split('T')[0];
+
+    parameters.forEach((param) => {
+      if (param.defaultValue !== undefined) {
+        defaults[param.name] = param.defaultValue;
+      } else if (param.type === 'DATE' || param.type === 'DATETIME') {
+        // Default all date parameters to today if no defaultValue
+        if (param.name === 'startDate' ||
+            param.name === 'endDate' ||
+            param.name.toLowerCase().includes('date')) {
+          defaults[param.name] = today;
+        }
+      }
+    });
+
+    return defaults;
+  }, [parameters]);
+
+  const [values, setValues] = useState<Record<string, any>>(initialValues);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  // Reset values when report changes
+  const [lastReportUuid, setLastReportUuid] = useState<string | null>(null);
+
+  // Detect report change and reset
+  useMemo(() => {
+    if (report?.uuid !== lastReportUuid) {
+      setValues(initialValues);
+      setErrors({});
+      setLastReportUuid(report?.uuid || null);
+    }
+  }, [report?.uuid, initialValues, lastReportUuid]);
+
+  // Set all values
+  const setAllValues = useCallback((newValues: Record<string, any>) => {
+    setValues(newValues);
+  }, []);
+
+  // Validate all required parameters
+  const validate = useCallback((): boolean => {
+    const newErrors: Record<string, string> = {};
+
+    parameters.forEach((param) => {
+      const value = values[param.name];
+
+      if (param.required && (!value || value.toString().trim() === '')) {
+        newErrors[param.name] = `${param.label} is required`;
+      }
+
+      // Type-specific validation
+      if (value && param.type === 'NUMBER') {
+        if (isNaN(Number(value))) {
+          newErrors[param.name] = `${param.label} must be a number`;
+        }
+      }
+    });
+
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  }, [parameters, values]);
+
+  // Reset to initial defaults
+  const reset = useCallback(() => {
+    setValues(initialValues);
+    setErrors({});
+  }, [initialValues]);
+
+  // Clear all values and errors
+  const clear = useCallback(() => {
+    setValues({});
+    setErrors({});
+  }, []);
+
+  return {
+    parameters,
+    values,
+    errors,
+    loading: false,
+    setValues: setAllValues,
+    validate,
+    reset,
+    clear,
+    hasParameters,
+    requiredParamsCount,
+  };
+}
+
+export default useReportParameters;