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

package/src/features/dashboards/components/ReportLaunchCard.tsx

@@ -0,0 +1,51 @@
+/**
+ * Report Launch Card
+ * REPORT widget rendering: report name/description/category + an
+ * "Open in Run Reports" action. Not a live render — a launch point.
+ */
+
+import React from 'react';
+import { Button, Tag, Tile } from '@carbon/react';
+import { ArrowRight, Document } from '@carbon/icons-react';
+import { useNavigate } from 'react-router-dom';
+import type { ReportDto } from '../../../resources/report/reports.api';
+import styles from '../dashboards.scss';
+
+interface ReportLaunchCardProps {
+  title: string;
+  report?: ReportDto;
+}
+
+export function ReportLaunchCard({ title, report }: ReportLaunchCardProps) {
+  const navigate = useNavigate();
+
+  return (
+    <Tile className={styles['report-launch-card']}>
+      <div className={styles['report-launch-card__header']}>
+        <span className={styles['report-launch-card__icon']}>
+          <Document size={20} />
+        </span>
+        <h4 className={styles['report-launch-card__title']}>{title}</h4>
+      </div>
+      {report?.description && (
+        <p className={styles['report-launch-card__description']}>{report.description}</p>
+      )}
+      <div className={styles['report-launch-card__footer']}>
+        <div className={styles['report-launch-card__tags']}>
+          {report?.reportType && <Tag size="sm" type="blue">{report.reportType}</Tag>}
+          {report?.code && <Tag size="sm" type="gray">{report.code}</Tag>}
+        </div>
+        <Button
+          size="sm"
+          kind="primary"
+          renderIcon={ArrowRight}
+          onClick={() => navigate('/run')}
+        >
+          Open in Run Reports
+        </Button>
+      </div>
+    </Tile>
+  );
+}
+
+export default ReportLaunchCard;

package/src/features/dashboards/components/WidgetSlotDispatcher.tsx

@@ -0,0 +1,61 @@
+/**
+ * Widget Slot Dispatcher
+ * Maps a resolved slot to its rendering: ETL monitors via the shared
+ * EtlMonitorWidget, REPORT widgets via the launch card, missing refs via
+ * the unavailable placeholder. UNSUPPORTED slots are skipped upstream.
+ */
+
+import React from 'react';
+import type { ResolvedWidgetSlot } from '../../../types/dashboard/dashboard.types';
+import type { MonitorDataResponse } from '../../../types/etl-monitor/etl-monitor.types';
+import { EtlMonitorWidget } from '../../../components/etl-monitor/renderers/EtlMonitorWidget';
+import ReportLaunchCard from './ReportLaunchCard';
+import WidgetUnavailableCard from './WidgetUnavailableCard';
+
+interface WidgetSlotDispatcherProps {
+  slot: ResolvedWidgetSlot;
+  position: number;
+  data?: MonitorDataResponse;
+  error?: string;
+  loading: boolean;
+  onRefreshMonitor: (uuid: string) => void;
+}
+
+export function WidgetSlotDispatcher({
+  slot,
+  position,
+  data,
+  error,
+  loading,
+  onRefreshMonitor,
+}: WidgetSlotDispatcherProps) {
+  if (slot.status === 'UNAVAILABLE') {
+    return <WidgetUnavailableCard title={slot.title} reason={slot.unavailableReason} />;
+  }
+
+  if (slot.status === 'UNSUPPORTED') {
+    return null;
+  }
+
+  if (slot.kind === 'ETL' && slot.monitor) {
+    return (
+      <EtlMonitorWidget
+        monitor={slot.monitor}
+        data={data}
+        error={error}
+        loading={loading}
+        onRefresh={() => onRefreshMonitor(slot.monitor!.uuid!)}
+        position={position}
+        title={slot.title !== slot.monitor.name ? slot.title : undefined}
+      />
+    );
+  }
+
+  if (slot.kind === 'REPORT') {
+    return <ReportLaunchCard title={slot.title} report={slot.report} />;
+  }
+
+  return null;
+}
+
+export default WidgetSlotDispatcher;

package/src/features/dashboards/components/WidgetUnavailableCard.tsx

@@ -0,0 +1,36 @@
+/**
+ * Widget Unavailable Card
+ * Placeholder for a widget whose referenced monitor/report is missing,
+ * retired, or inactive — keeps the grid geometry intact.
+ */
+
+import React from 'react';
+import { Tile } from '@carbon/react';
+import { WarningAlt } from '@carbon/icons-react';
+import styles from '../dashboards.scss';
+
+interface WidgetUnavailableCardProps {
+  title: string;
+  reason?: 'monitor-missing' | 'report-missing';
+}
+
+const REASON_TEXT: Record<string, string> = {
+  'monitor-missing': 'The ETL monitor for this widget no longer exists or is inactive.',
+  'report-missing': 'The report for this widget no longer exists or is retired.',
+};
+
+export function WidgetUnavailableCard({ title, reason }: WidgetUnavailableCardProps) {
+  return (
+    <Tile className={styles['widget-unavailable-card']}>
+      <div className={styles['widget-unavailable-card__icon']}>
+        <WarningAlt size={24} />
+      </div>
+      <h4 className={styles['widget-unavailable-card__title']}>{title}</h4>
+      <p className={styles['widget-unavailable-card__message']}>
+        {reason ? REASON_TEXT[reason] : 'This widget is currently unavailable.'}
+      </p>
+    </Tile>
+  );
+}
+
+export default WidgetUnavailableCard;

package/src/features/dashboards/dashboards.scss

@@ -0,0 +1,196 @@
+// Dashboard viewing pages center their content in the framework's
+// full-width slot; admin/CRUD pages stay full-bleed.
+.dashboard-renderer {
+  width: 100%;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.dashboard-section__accordion {
+  width: 100%;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+
+.dashboard-loading {
+  padding: 3rem 0;
+}
+
+.dashboard-grid {
+  width: 100%;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+// Scoped override of Carbon's .cds--css-grid for the dashboards feature only.
+// Composed with the Carbon class (specificity 0,2,0) so it wins over
+// Carbon's base rule regardless of stylesheet order, and leaves every
+// other Carbon grid in the shell untouched.
+.dashboard-grid:global(.cds--css-grid) {
+  // Drop Carbon's 99rem page cap — the grid spans the full content area
+  max-width: none;
+
+  // The page/shell provides its own outer gutters; Carbon's page padding off
+  padding-inline: 0;
+
+  // Tune column gutters if needed (Carbon columns read these):
+  // --cds-grid-gutter: 1rem;
+}
+
+.dashboard-grid__cell {
+  padding: 1rem;
+}
+
+.dashboard-section {
+  margin-top: 0.5rem;
+
+  &__header {
+    display: flex;
+    align-items: baseline;
+    gap: 0.5rem;
+    margin-bottom: 0.25rem;
+    margin-left: auto;
+    margin-right: auto;
+    width: 100%;
+    padding-left: 1.5rem;
+  }
+
+  &__label {
+    font-size: 1rem;
+    font-weight: 600;
+    margin: 0;
+  }
+
+  &__count {
+    font-size: 0.75rem;
+    color: var(--cds-text-secondary, #525252);
+  }
+
+  &__accordion {
+    margin-bottom: 0.5rem;
+  }
+}
+
+.report-launch-card {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  height: 100%;
+
+  &__header {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  &__icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.25rem;
+    height: 2.25rem;
+    border-radius: 50%;
+    background: var(--cds-layer-accent, #e8e8e8);
+    color: var(--cds-link-primary, #0f62fe);
+  }
+
+  &__title {
+    font-size: 0.9375rem;
+    font-weight: 600;
+    margin: 0;
+  }
+
+  &__description {
+    font-size: 0.8125rem;
+    color: var(--cds-text-secondary, #525252);
+    margin: 0;
+  }
+
+  &__footer {
+    margin-top: auto;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem;
+  }
+
+  &__tags {
+    display: flex;
+    gap: 0.25rem;
+    flex-wrap: wrap;
+  }
+}
+
+.widget-unavailable-card {
+  height: 100%;
+  text-align: center;
+  padding: 2rem 1rem;
+
+  &__icon {
+    color: var(--cds-text-secondary, #525252);
+    margin-bottom: 0.5rem;
+  }
+
+  &__title {
+    font-size: 0.9375rem;
+    margin: 0 0 0.25rem;
+  }
+
+  &__message {
+    font-size: 0.8125rem;
+    color: var(--cds-text-secondary, #525252);
+    margin: 0;
+  }
+}
+
+.dashboard-empty-state {
+  text-align: center;
+  padding: 3rem 1rem;
+
+  &__icon {
+    color: var(--cds-text-secondary, #525252);
+  }
+
+  &__title {
+    margin: 0.5rem 0 0.25rem;
+  }
+
+  &__message {
+    color: var(--cds-text-secondary, #525252);
+    margin: 0 0 1rem;
+  }
+
+  &__actions {
+    display: flex;
+    justify-content: center;
+    gap: 0.5rem;
+  }
+}
+
+.dashboards-index__auto-tile {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.dashboards-index__auto-main {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.dashboards-index__auto-icon {
+  color: var(--cds-link-primary, #0f62fe);
+}
+
+.dashboards-index__auto-note {
+  font-size: 0.8125rem;
+  color: var(--cds-text-secondary, #525252);
+  margin: 0.125rem 0 0;
+}
+
+.dashboards-index__empty-note {
+  color: var(--cds-text-secondary, #525252);
+}

package/src/features/dashboards/hooks/useDashboard.ts

@@ -0,0 +1,61 @@
+import React from 'react';
+import { getDashboard } from '../../../resources/dashboard/dashboard.api';
+import type { DashboardDto } from '../../../types/dashboard/dashboard.types';
+
+interface UseDashboardResult {
+  dashboard: DashboardDto | null;
+  isLoading: boolean;
+  error: string | null;
+  notFound: boolean;
+}
+
+/**
+ * Fetch a single dashboard by uuid, code, or numeric id.
+ */
+export function useDashboard(uuidOrCode?: string): UseDashboardResult {
+  const [dashboard, setDashboard] = React.useState<DashboardDto | null>(null);
+  const [isLoading, setIsLoading] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+  const [notFound, setNotFound] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!uuidOrCode) {
+      setDashboard(null);
+      setNotFound(false);
+      setError(null);
+      return undefined;
+    }
+
+    const ac = new AbortController();
+    let isMounted = true;
+
+    setIsLoading(true);
+    setError(null);
+    setNotFound(false);
+
+    getDashboard(uuidOrCode, ac.signal)
+      .then((data) => {
+        if (isMounted) setDashboard(data ?? null);
+      })
+      .catch((e: any) => {
+        if (!isMounted || e?.name === 'AbortError') return;
+        if (e?.status === 404 || e?.response?.status === 404 || /not found|404/i.test(String(e?.message))) {
+          setNotFound(true);
+        } else {
+          setError(e?.message ?? 'Failed to load dashboard');
+        }
+      })
+      .finally(() => {
+        if (isMounted) setIsLoading(false);
+      });
+
+    return () => {
+      isMounted = false;
+      ac.abort();
+    };
+  }, [uuidOrCode]);
+
+  return { dashboard, isLoading, error, notFound };
+}
+
+export default useDashboard;

package/src/features/dashboards/hooks/useDashboardWidgets.ts

@@ -0,0 +1,74 @@
+import React from 'react';
+import { listActiveETLMonitors } from '../../../resources/etl-monitor/etl-monitor.api';
+import { listReports } from '../../../resources/report/reports.api';
+import type { DashboardConfigV1 } from '../../../types/dashboard/dashboard.types';
+import type { ETLMonitorDto } from '../../../types/etl-monitor/etl-monitor.types';
+import type { ReportDto } from '../../../resources/report/reports.api';
+
+interface UseDashboardWidgetsResult {
+  monitors: ETLMonitorDto[];
+  reports: ReportDto[];
+  isLoading: boolean;
+  error: string | null;
+}
+
+/**
+ * Fetch the resolution inputs for a dashboard config: active ETL monitors
+ * and reports, in parallel. A failure on one side is tolerated (resolves
+ * to an empty list) — only a total failure surfaces as an error.
+ */
+export function useDashboardWidgets(config?: DashboardConfigV1 | null): UseDashboardWidgetsResult {
+  const [monitors, setMonitors] = React.useState<ETLMonitorDto[]>([]);
+  const [reports, setReports] = React.useState<ReportDto[]>([]);
+  const [isLoading, setIsLoading] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+
+  // Re-fetch when the config's shape changes (widget refs / autoInclude), not on identity churn
+  const configKey = React.useMemo(
+    () => JSON.stringify({ w: config?.widgets ?? [], ai: config?.autoInclude ?? null }),
+    [config?.widgets, config?.autoInclude],
+  );
+
+  React.useEffect(() => {
+    const ac = new AbortController();
+    let isMounted = true;
+
+    setIsLoading(true);
+    setError(null);
+
+    Promise.all([
+      listActiveETLMonitors(ac.signal).catch((e: any) => {
+        if (e?.name === 'AbortError') throw e;
+        return null; // tolerate — monitors may be unavailable for report-only dashboards
+      }),
+      listReports({ v: 'default' }, ac.signal).catch((e: any) => {
+        if (e?.name === 'AbortError') throw e;
+        return null;
+      }),
+    ])
+      .then(([monitorsResult, reportsResult]) => {
+        if (!isMounted) return;
+        if (monitorsResult === null && reportsResult === null) {
+          setError('Failed to load dashboard contents');
+        }
+        setMonitors(monitorsResult ?? []);
+        setReports(reportsResult ?? []);
+      })
+      .catch(() => {
+        /* aborted */
+      })
+      .finally(() => {
+        if (isMounted) setIsLoading(false);
+      });
+
+    return () => {
+      isMounted = false;
+      ac.abort();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [configKey]);
+
+  return { monitors, reports, isLoading, error };
+}
+
+export default useDashboardWidgets;

package/src/features/dashboards/hooks/useDashboards.ts

@@ -0,0 +1,56 @@
+import React from 'react';
+import { listDashboards } from '../../../resources/dashboard/dashboard.api';
+import type { DashboardDto, DashboardType } from '../../../types/dashboard/dashboard.types';
+
+interface UseDashboardsResult {
+  dashboards: DashboardDto[];
+  isLoading: boolean;
+  error: string | null;
+  reload: () => void;
+}
+
+/**
+ * List dashboards (for the index page and the admin table).
+ */
+export function useDashboards(params?: {
+  q?: string;
+  type?: DashboardType;
+  activeOnly?: boolean;
+  includeRetired?: boolean;
+}): UseDashboardsResult {
+  const { q, type, activeOnly, includeRetired } = params ?? {};
+  const [dashboards, setDashboards] = React.useState<DashboardDto[]>([]);
+  const [isLoading, setIsLoading] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+  const [tick, setTick] = React.useState(0);
+
+  React.useEffect(() => {
+    const ac = new AbortController();
+    let isMounted = true;
+
+    setIsLoading(true);
+    setError(null);
+
+    listDashboards({ q, type, activeOnly, includeRetired, v: 'default' }, ac.signal)
+      .then((data) => {
+        if (isMounted) setDashboards((data ?? []).filter((d) => d.uuid));
+      })
+      .catch((e: any) => {
+        if (isMounted && e?.name !== 'AbortError') setError(e?.message ?? 'Failed to load dashboards');
+      })
+      .finally(() => {
+        if (isMounted) setIsLoading(false);
+      });
+
+    return () => {
+      isMounted = false;
+      ac.abort();
+    };
+  }, [q, type, activeOnly, includeRetired, tick]);
+
+  const reload = React.useCallback(() => setTick((t) => t + 1), []);
+
+  return { dashboards, isLoading, error, reload };
+}
+
+export default useDashboards;

package/src/features/dashboards/hooks/useMonitorDataMap.ts

@@ -0,0 +1,84 @@
+import React from 'react';
+import { fetchMonitorData } from '../../../resources/etl-monitor/etl-monitor.api';
+import type { ETLMonitorDto, MonitorDataResponse } from '../../../types/etl-monitor/etl-monitor.types';
+
+export type DashboardAggregateStatus = 'success' | 'warning' | 'error';
+
+interface UseMonitorDataMapResult {
+  dataMap: Record<string, MonitorDataResponse>;
+  errorMap: Record<string, string>;
+  loadingMap: Record<string, boolean>;
+  lastRefreshed: Date | null;
+  refreshAll: () => void;
+  refreshOne: (uuid: string) => void;
+  aggregateStatus: DashboardAggregateStatus;
+}
+
+/**
+ * Fetch and auto-refresh data for every ETL monitor placed on a dashboard.
+ * Mirrors the legacy dashboard's model (browser-side fetchMonitorData,
+ * min-interval polling) with per-widget refresh and an aggregate status
+ * for the dashboard header pill.
+ */
+export function useMonitorDataMap(
+  monitors: ETLMonitorDto[],
+  minRefreshInterval: number,
+): UseMonitorDataMapResult {
+  const [dataMap, setDataMap] = React.useState<Record<string, MonitorDataResponse>>({});
+  const [errorMap, setErrorMap] = React.useState<Record<string, string>>({});
+  const [loadingMap, setLoadingMap] = React.useState<Record<string, boolean>>({});
+  const [lastRefreshed, setLastRefreshed] = React.useState<Date | null>(null);
+
+  const monitorKey = React.useMemo(() => monitors.map((m) => m.uuid).join(','), [monitors]);
+
+  const loadOne = React.useCallback(async (uuid: string) => {
+    setLoadingMap((prev) => ({ ...prev, [uuid]: true }));
+    try {
+      const data = await fetchMonitorData(uuid);
+      setDataMap((prev) => ({ ...prev, [uuid]: data }));
+      setErrorMap((prev) => {
+        const next = { ...prev };
+        delete next[uuid];
+        return next;
+      });
+    } catch (e: any) {
+      setErrorMap((prev) => ({ ...prev, [uuid]: e?.message ?? 'Failed to load data' }));
+    } finally {
+      setLoadingMap((prev) => ({ ...prev, [uuid]: false }));
+    }
+  }, []);
+
+  const loadAll = React.useCallback(() => {
+    const uuids = monitorKey.split(',').filter(Boolean);
+    if (uuids.length === 0) return;
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+    Promise.all(uuids.map((uuid) => loadOne(uuid))).then(() => setLastRefreshed(new Date()));
+  }, [monitorKey, loadOne]);
+
+  React.useEffect(() => {
+    loadAll();
+  }, [loadAll]);
+
+  // Auto-refresh at the minimum refresh interval across included monitors
+  React.useEffect(() => {
+    if (!monitorKey) return undefined;
+    const intervalMs = Math.max(5, minRefreshInterval) * 1000;
+    const interval = setInterval(() => loadAll(), intervalMs);
+    return () => clearInterval(interval);
+  }, [monitorKey, minRefreshInterval, loadAll]);
+
+  const refreshAll = React.useCallback(() => loadAll(), [loadAll]);
+  const refreshOne = React.useCallback((uuid: string) => loadOne(uuid), [loadOne]);
+
+  const aggregateStatus: DashboardAggregateStatus = React.useMemo(() => {
+    const errors = Object.values(errorMap).filter(Boolean);
+    if (errors.length > 0) return 'error';
+    const uuids = monitorKey.split(',').filter(Boolean);
+    const hasEmpty = uuids.some((uuid) => !dataMap[uuid]);
+    return hasEmpty ? 'warning' : 'success';
+  }, [errorMap, dataMap, monitorKey]);
+
+  return { dataMap, errorMap, loadingMap, lastRefreshed, refreshAll, refreshOne, aggregateStatus };
+}
+
+export default useMonitorDataMap;

package/src/features/dashboards/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Dashboards feature - public surface
+ */
+export { DashboardRendererPage, default as DashboardRendererPageDefault } from './DashboardRendererPage';
+export { DashboardsPage, default as DashboardsPageDefault } from './DashboardsPage';
+export { resolveDashboardLayout, parseDashboardConfig, synthesizeEtlDashboardConfig } from './utils/dashboard-config.util';
+export { useDashboard } from './hooks/useDashboard';
+export { useDashboards } from './hooks/useDashboards';
+export { useDashboardWidgets } from './hooks/useDashboardWidgets';
+export { useMonitorDataMap } from './hooks/useMonitorDataMap';
+export { default as EtlDashboardPage } from './EtlDashboardPage';