@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/src/page-templates/EntityDashboard.tsx

@@ -0,0 +1,519 @@
+import React, { useState, useEffect, useCallback } from 'react';
+import {
+  Stack,
+  Text,
+  MessageBar,
+  MessageBarType,
+  Spinner,
+  SpinnerSize,
+  CommandBar,
+  ICommandBarItemProps,
+  Pivot,
+  PivotItem,
+  DetailsList,
+  IColumn,
+  SelectionMode,
+} from '@fluentui/react';
+import { BaseEntity } from '../models/BaseEntity';
+import { useDynamicsApi } from '../providers/DynamicsProvider';
+import { Logger } from '../components/Logging/logger';
+
+interface KPICard {
+  title: string;
+  value: string | number;
+  trend?: 'up' | 'down' | 'neutral';
+  trendValue?: string;
+  color?: string;
+  icon?: string;
+}
+
+interface ChartData {
+  title: string;
+  data: any[];
+  type: 'bar' | 'line' | 'pie' | 'donut';
+}
+
+interface EntityDashboardProps<T extends BaseEntity> {
+  title: string;
+  entityLogicalName: string;
+  entityClass: any;
+  kpiQueries: { [key: string]: string }; // FetchXML queries for KPIs
+  chartQueries?: { [key: string]: string }; // FetchXML queries for charts
+  recentItemsQuery: string; // FetchXML for recent items
+  recentItemsColumns: IColumn[];
+  renderKPICards: (data: { [key: string]: any[] }) => KPICard[];
+  renderCharts?: (data: { [key: string]: any[] }) => ChartData[];
+  onItemSelected?: (item: T) => void;
+  onCreateNew?: () => void;
+  customCommands?: ICommandBarItemProps[];
+  refreshInterval?: number; // Auto-refresh interval in seconds
+}
+
+/**
+ * Generic entity dashboard template for Dynamics 365
+ * Displays KPIs, charts, and recent items with real-time updates
+ */
+export function EntityDashboard<T extends BaseEntity>({
+  title,
+  entityLogicalName,
+  entityClass,
+  kpiQueries,
+  chartQueries = {},
+  recentItemsQuery,
+  recentItemsColumns,
+  renderKPICards,
+  renderCharts,
+  onItemSelected,
+  onCreateNew,
+  customCommands = [],
+  refreshInterval = 300, // 5 minutes default
+}: EntityDashboardProps<T>) {
+  const { apiService } = useDynamicsApi();
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [kpiData, setKpiData] = useState<{ [key: string]: any[] }>({});
+  const [chartData, setChartData] = useState<{ [key: string]: any[] }>({});
+  const [recentItems, setRecentItems] = useState<T[]>([]);
+  const [lastRefresh, setLastRefresh] = useState<Date>(new Date());
+  const [refreshTrigger, setRefreshTrigger] = useState(0);
+
+  // Load all dashboard data
+  const loadDashboardData = useCallback(async () => {
+    if (!apiService) {
+      setError('API service not available');
+      setLoading(false);
+      return;
+    }
+
+    try {
+      setLoading(true);
+      setError(null);
+      Logger.log(`Loading ${title} dashboard...`);
+
+      // Load KPI data
+      const kpiResults: { [key: string]: any[] } = {};
+      for (const [key, query] of Object.entries(kpiQueries)) {
+        try {
+          const result = await apiService.retrieveMultipleRecords(
+            entityLogicalName,
+            query
+          );
+          kpiResults[key] = result.entities || [];
+        } catch (err) {
+          const errorMessage = err instanceof Error ? err.message : String(err);
+          Logger.warn(`Failed to load KPI data for ${key}:`, errorMessage);
+          kpiResults[key] = [];
+        }
+      }
+      setKpiData(kpiResults);
+
+      // Load chart data
+      const chartResults: { [key: string]: any[] } = {};
+      for (const [key, query] of Object.entries(chartQueries)) {
+        try {
+          const result = await apiService.retrieveMultipleRecords(
+            entityLogicalName,
+            query
+          );
+          chartResults[key] = result.entities || [];
+        } catch (err) {
+          const errorMessage = err instanceof Error ? err.message : String(err);
+          Logger.warn(`Failed to load chart data for ${key}:`, errorMessage);
+          chartResults[key] = [];
+        }
+      }
+      setChartData(chartResults);
+
+      // Load recent items
+      try {
+        const result = await apiService.retrieveMultipleRecords(
+          entityLogicalName,
+          recentItemsQuery
+        );
+        const items = (result.entities || []).map(
+          (data: any) => new entityClass(data)
+        );
+        setRecentItems(items);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        Logger.warn('Failed to load recent items:', errorMessage);
+        setRecentItems([]);
+      }
+
+      setLastRefresh(new Date());
+      Logger.log(`${title} dashboard loaded successfully`);
+    } catch (err) {
+      const errorMessage =
+        err instanceof Error
+          ? err.message
+          : `Failed to load ${title} dashboard`;
+      setError(errorMessage);
+      Logger.error(`Error loading ${title} dashboard:`, 'EntityDashboard', err);
+    } finally {
+      setLoading(false);
+    }
+  }, [
+    apiService,
+    title,
+    entityLogicalName,
+    entityClass,
+    kpiQueries,
+    chartQueries,
+    recentItemsQuery,
+  ]);
+
+  // Initial load and auto-refresh
+  useEffect(() => {
+    loadDashboardData();
+
+    if (refreshInterval > 0) {
+      const interval = setInterval(loadDashboardData, refreshInterval * 1000);
+      return () => clearInterval(interval);
+    }
+  }, [loadDashboardData, refreshInterval, refreshTrigger]);
+
+  // Handle manual refresh
+  const handleRefresh = () => {
+    setRefreshTrigger((prev) => prev + 1);
+  };
+
+  // Handle item selection
+  const handleItemClick = (item: T) => {
+    if (onItemSelected) {
+      onItemSelected(item);
+    }
+  };
+
+  // Generate KPI cards
+  const kpiCards = renderKPICards(kpiData);
+
+  // Generate charts
+  const charts = renderCharts ? renderCharts(chartData) : [];
+
+  // Command bar items
+  const commandBarItems: ICommandBarItemProps[] = [
+    {
+      key: 'refresh',
+      text: 'Refresh',
+      iconProps: { iconName: 'Refresh' },
+      onClick: handleRefresh,
+    },
+    ...(onCreateNew
+      ? [
+          {
+            key: 'new',
+            text: `New ${title}`,
+            iconProps: { iconName: 'Add' },
+            onClick: onCreateNew,
+          },
+        ]
+      : []),
+    ...customCommands,
+  ];
+
+  // Enhanced columns with click handlers
+  const enhancedColumns = recentItemsColumns.map((column) => ({
+    ...column,
+    onRender:
+      column.onRender ||
+      ((item: T) => {
+        const value = (item as any)[column.fieldName || ''];
+        if (column.key === recentItemsColumns[0].key) {
+          // Make first column clickable
+          return (
+            <span
+              style={{ color: '#0078d4', cursor: 'pointer', fontWeight: 500 }}
+              onClick={() => handleItemClick(item)}
+            >
+              {value || ''}
+            </span>
+          );
+        }
+        return <span>{value || ''}</span>;
+      }),
+  }));
+
+  const formatLastRefresh = () => {
+    const now = new Date();
+    const diffMs = now.getTime() - lastRefresh.getTime();
+    const diffMins = Math.floor(diffMs / 60000);
+
+    if (diffMins < 1) return 'Just now';
+    if (diffMins === 1) return '1 minute ago';
+    return `${diffMins} minutes ago`;
+  };
+
+  return (
+    <div style={{ padding: '20px', maxWidth: '100%' }}>
+      <Stack tokens={{ childrenGap: 24 }}>
+        {/* Header */}
+        <Stack
+          horizontal
+          horizontalAlign="space-between"
+          verticalAlign="center"
+        >
+          <Stack>
+            <Text
+              variant="xxLarge"
+              style={{ fontWeight: 600, color: '#323130' }}
+            >
+              {title} Dashboard
+            </Text>
+            <Text variant="small" style={{ color: '#605e5c' }}>
+              Last updated: {formatLastRefresh()}
+            </Text>
+          </Stack>
+        </Stack>
+
+        {/* Error Message */}
+        {error && (
+          <MessageBar
+            messageBarType={MessageBarType.error}
+            onDismiss={() => setError(null)}
+          >
+            {error}
+          </MessageBar>
+        )}
+
+        {/* Command Bar */}
+        <CommandBar items={commandBarItems} />
+
+        {loading ? (
+          <div
+            style={{
+              display: 'flex',
+              justifyContent: 'center',
+              alignItems: 'center',
+              minHeight: 300,
+              flexDirection: 'column',
+            }}
+          >
+            <Spinner
+              size={SpinnerSize.large}
+              label={`Loading ${title} dashboard...`}
+            />
+          </div>
+        ) : (
+          <Pivot defaultSelectedKey="overview">
+            {/* Overview Tab */}
+            <PivotItem headerText="Overview" itemKey="overview">
+              <Stack tokens={{ childrenGap: 20 }}>
+                {/* KPI Cards */}
+                <Stack>
+                  <Text
+                    variant="large"
+                    style={{ fontWeight: 600, marginBottom: 16 }}
+                  >
+                    Key Metrics
+                  </Text>
+                  <Stack horizontal wrap tokens={{ childrenGap: 16 }}>
+                    {kpiCards.map((kpi, index) => (
+                      <div
+                        key={index}
+                        style={{
+                          minWidth: 200,
+                          maxWidth: 250,
+                          padding: 16,
+                          border: `2px solid ${kpi.color || '#edebe9'}`,
+                          borderRadius: 4,
+                          backgroundColor: '#ffffff',
+                          boxShadow: '0 1px 3px rgba(0,0,0,0.1)',
+                        }}
+                      >
+                        <Stack>
+                          <Stack
+                            horizontal
+                            horizontalAlign="space-between"
+                            verticalAlign="center"
+                          >
+                            <Text variant="medium" style={{ color: '#605e5c' }}>
+                              {kpi.title}
+                            </Text>
+                            {kpi.icon && (
+                              <div
+                                style={{
+                                  fontSize: 16,
+                                  color: kpi.color || '#605e5c',
+                                }}
+                              >
+                                {kpi.icon}
+                              </div>
+                            )}
+                          </Stack>
+                          <Text
+                            variant="xxLarge"
+                            style={{
+                              fontWeight: 700,
+                              color: kpi.color || '#323130',
+                              margin: '8px 0',
+                            }}
+                          >
+                            {kpi.value}
+                          </Text>
+                          {kpi.trend && kpi.trendValue && (
+                            <Stack
+                              horizontal
+                              verticalAlign="center"
+                              tokens={{ childrenGap: 4 }}
+                            >
+                              <span
+                                style={{
+                                  fontSize: 12,
+                                  color:
+                                    kpi.trend === 'up'
+                                      ? '#107c10'
+                                      : kpi.trend === 'down'
+                                        ? '#d13438'
+                                        : '#605e5c',
+                                }}
+                              >
+                                {kpi.trend === 'up'
+                                  ? '↗️'
+                                  : kpi.trend === 'down'
+                                    ? '↘️'
+                                    : '➡️'}
+                              </span>
+                              <Text
+                                variant="small"
+                                style={{
+                                  color:
+                                    kpi.trend === 'up'
+                                      ? '#107c10'
+                                      : kpi.trend === 'down'
+                                        ? '#d13438'
+                                        : '#605e5c',
+                                }}
+                              >
+                                {kpi.trendValue}
+                              </Text>
+                            </Stack>
+                          )}
+                        </Stack>
+                      </div>
+                    ))}
+                  </Stack>
+                </Stack>
+
+                {/* Recent Items */}
+                <Stack>
+                  <Text
+                    variant="large"
+                    style={{ fontWeight: 600, marginBottom: 16 }}
+                  >
+                    Recent {title}
+                  </Text>
+                  {recentItems.length === 0 ? (
+                    <div
+                      style={{
+                        textAlign: 'center',
+                        padding: '40px 20px',
+                        color: '#605e5c',
+                        border: '1px solid #edebe9',
+                        borderRadius: 4,
+                      }}
+                    >
+                      <Text variant="medium">No recent items found</Text>
+                    </div>
+                  ) : (
+                    <DetailsList
+                      items={recentItems}
+                      columns={enhancedColumns}
+                      setKey="recent"
+                      layoutMode={0}
+                      selectionMode={SelectionMode.none}
+                      isHeaderVisible={true}
+                    />
+                  )}
+                </Stack>
+              </Stack>
+            </PivotItem>
+
+            {/* Charts Tab */}
+            {charts.length > 0 && (
+              <PivotItem headerText="Analytics" itemKey="analytics">
+                <Stack tokens={{ childrenGap: 20 }}>
+                  {charts.map((chart, index) => (
+                    <div
+                      key={index}
+                      style={{
+                        padding: 16,
+                        backgroundColor: '#ffffff',
+                        border: '1px solid #edebe9',
+                        borderRadius: 4,
+                        boxShadow: '0 1px 3px rgba(0,0,0,0.1)',
+                      }}
+                    >
+                      <Stack>
+                        <Text
+                          variant="large"
+                          style={{ fontWeight: 600, marginBottom: 16 }}
+                        >
+                          {chart.title}
+                        </Text>
+                        <div
+                          style={{
+                            minHeight: 300,
+                            display: 'flex',
+                            alignItems: 'center',
+                            justifyContent: 'center',
+                            border: '1px dashed #c8c6c4',
+                            borderRadius: 4,
+                            color: '#605e5c',
+                          }}
+                        >
+                          <Text variant="medium">
+                            Chart visualization for {chart.title} ({chart.type})
+                          </Text>
+                        </div>
+                      </Stack>
+                    </div>
+                  ))}
+                </Stack>
+              </PivotItem>
+            )}
+          </Pivot>
+        )}
+      </Stack>
+    </div>
+  );
+}
+
+// Helper functions for common KPI calculations
+export const KPIHelpers = {
+  count: (data: any[]): number => data.length,
+
+  sum: (data: any[], field: string): number =>
+    data.reduce((sum, item) => sum + (parseFloat(item[field]) || 0), 0),
+
+  average: (data: any[], field: string): number => {
+    const total = KPIHelpers.sum(data, field);
+    return data.length > 0 ? total / data.length : 0;
+  },
+
+  percentage: (part: number, total: number): string =>
+    total > 0 ? `${Math.round((part / total) * 100)}%` : '0%',
+
+  formatCurrency: (amount: number): string =>
+    new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: 'USD',
+    }).format(amount),
+
+  formatNumber: (num: number): string =>
+    new Intl.NumberFormat('en-US').format(num),
+
+  trend: (
+    current: number,
+    previous: number
+  ): { trend: 'up' | 'down' | 'neutral'; value: string } => {
+    if (previous === 0) return { trend: 'neutral', value: 'N/A' };
+
+    const change = ((current - previous) / previous) * 100;
+    if (Math.abs(change) < 1) return { trend: 'neutral', value: '0%' };
+
+    return {
+      trend: change > 0 ? 'up' : 'down',
+      value: `${Math.abs(Math.round(change))}%`,
+    };
+  },
+};