@kenyaemr/esm-reports-app 5.4.4-pre.483

package/src/components/report-view/report-view.component.tsx

@@ -0,0 +1,183 @@
+import React, { useMemo, useState } from 'react';
+import { useNavigate, useParams } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { Pagination, SkeletonText, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@carbon/react';
+import { ErrorState, formatDate, formatDatetime, parseDate } from '@openmrs/esm-framework';
+
+import { useReportData } from '../../hooks/useReportData';
+import { type ReportDataSet } from '../../types';
+import ReportDownloadMenu from '../report-download-menu/report-download-menu.component';
+import styles from './report-view.scss';
+import dayjs from 'dayjs';
+
+const PAGE_SIZE = 20;
+
+const renderValue = (value: unknown): string => {
+  if (value === null || value === undefined || value === '') {
+    return '--';
+  }
+  if (typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    return String(record.display ?? record.value ?? record.name ?? JSON.stringify(value));
+  }
+
+  if (typeof value === 'number') {
+    const unixConvertedDate = dayjs(value).toDate();
+    return formatDate(unixConvertedDate, { noToday: true, time: false });
+  }
+
+  return String(value);
+};
+
+const RowDataSetTable: React.FC<{ dataSet: ReportDataSet }> = ({ dataSet }) => {
+  const { t } = useTranslation();
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(PAGE_SIZE);
+
+  const pagedRows = useMemo(
+    () => dataSet.rows.slice((page - 1) * pageSize, page * pageSize),
+    [dataSet.rows, page, pageSize],
+  );
+
+  return (
+    <>
+      <div className={styles.tableWrapper}>
+        <Table size="sm" useZebraStyles>
+          <TableHead>
+            <TableRow>
+              {dataSet.columns.map((column) => (
+                <TableHeader key={column.name}>{column.label || column.name}</TableHeader>
+              ))}
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {pagedRows.map((row, rowIndex) => (
+              <TableRow key={rowIndex}>
+                {dataSet.columns.map((column) => (
+                  <TableCell key={column.name}>{renderValue(row[column.name])}</TableCell>
+                ))}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+      {dataSet.rows.length > PAGE_SIZE && (
+        <Pagination
+          page={page}
+          pageSize={pageSize}
+          pageSizes={[20, 50, 100]}
+          totalItems={dataSet.rows.length}
+          itemRangeText={(min, max, total) =>
+            t('minMaxItems', '{{min}}-{{max}} of {{total}} items', { min, max, total })
+          }
+          onChange={({ page: newPage, pageSize: newPageSize }) => {
+            setPage(newPage);
+            setPageSize(newPageSize);
+          }}
+        />
+      )}
+    </>
+  );
+};
+
+const IndicatorDataSetTable: React.FC<{ dataSet: ReportDataSet }> = ({ dataSet }) => {
+  const { t } = useTranslation();
+  const values = dataSet.values ?? {};
+
+  return (
+    <div className={`${styles.tableWrapper} ${styles.indicatorTable}`}>
+      <Table size="sm" useZebraStyles>
+        <TableHead>
+          <TableRow>
+            <TableHeader>{t('indicator', 'Indicator')}</TableHeader>
+            <TableHeader>{t('value', 'Value')}</TableHeader>
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {dataSet.columns.map((column) => (
+            <TableRow key={column.name}>
+              <TableCell>{column.label || column.name}</TableCell>
+              <TableCell>{renderValue(values[column.name])}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+};
+
+const ReportView: React.FC = () => {
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const { reportUuid = '', requestId = '' } = useParams();
+  const { reportData, isLoading, error } = useReportData(requestId);
+
+  if (isLoading) {
+    return (
+      <div className={styles.loadingState}>
+        <SkeletonText heading width="40%" />
+        <SkeletonText paragraph lineCount={5} />
+      </div>
+    );
+  }
+
+  if (error || !reportData) {
+    return (
+      <div className={styles.errorState}>
+        <ErrorState error={error} headerTitle={t('reportData', 'Report data')} />
+      </div>
+    );
+  }
+
+  const { request, definition, parameters, dataSets } = reportData;
+
+  return (
+    <div className={styles.container}>
+      <div className={styles.breadcrumb}>
+        <button type="button" className={styles.backButton} onClick={() => navigate(`/report/${reportUuid}`)}>
+          {t('reportsHistory', 'Report History')}
+        </button>
+        <span>/</span>
+        <span>{t('reportData', 'Report data')}</span>
+      </div>
+
+      <div className={styles.titleRow}>
+        <div>
+          <h2 className={styles.title}>{definition?.name}</h2>
+          {request?.requestDate && (
+            <p className={styles.subtitle}>
+              {t('generatedOn', 'Generated on {{date}}', {
+                date: formatDatetime(parseDate(request.requestDate), { mode: 'standard', noToday: true }),
+              })}
+              {request?.requestedBy?.display ? ` · ${request.requestedBy.display}` : ''}
+            </p>
+          )}
+        </div>
+        {request && <ReportDownloadMenu request={request} reportName={definition?.name} />}
+      </div>
+
+      {parameters && Object.keys(parameters).length > 0 && (
+        <div className={styles.parameters}>
+          {Object.entries(parameters).map(([name, value]) => (
+            <div key={name} className={styles.parameter}>
+              <span className={styles.parameterLabel}>{name}</span>
+              <span className={styles.parameterValue}>{renderValue(value)}</span>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {Object.values(dataSets ?? {}).map((dataSet) => {
+        const isIndicator = (!dataSet.rows || dataSet.rows.length === 0) && dataSet.values;
+        return (
+          <div key={dataSet.key} className={styles.dataSet}>
+            <h3 className={styles.dataSetTitle}>{dataSet.name || dataSet.key}</h3>
+            {isIndicator ? <IndicatorDataSetTable dataSet={dataSet} /> : <RowDataSetTable dataSet={dataSet} />}
+          </div>
+        );
+      })}
+    </div>
+  );
+};
+
+export default ReportView;

package/src/components/report-view/report-view.scss

@@ -0,0 +1,111 @@
+@use '@carbon/colors';
+@use '@carbon/layout';
+@use '@carbon/type';
+
+.container {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-05;
+  background-color: colors.$white;
+  padding: layout.$spacing-05;
+  margin: layout.$spacing-02;
+  border: 1px solid colors.$gray-10;
+}
+
+.breadcrumb {
+  display: flex;
+  align-items: center;
+  gap: layout.$spacing-03;
+  @include type.type-style('body-compact-01');
+  color: colors.$gray-70;
+}
+
+.backButton {
+  display: inline-flex;
+  align-items: center;
+  gap: layout.$spacing-02;
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: 0;
+  color: colors.$blue-60;
+  @include type.type-style('body-compact-01');
+
+  &:hover {
+    text-decoration: underline;
+  }
+}
+
+.titleRow {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: layout.$spacing-05;
+  padding-bottom: layout.$spacing-03;
+  border-bottom: 1px solid colors.$gray-20;
+}
+
+.title {
+  @include type.type-style('heading-05');
+  color: colors.$gray-100;
+  margin: 0;
+}
+
+.subtitle {
+  @include type.type-style('body-01');
+  color: colors.$gray-70;
+  margin-top: layout.$spacing-02;
+}
+
+.parameters {
+  display: flex;
+  flex-wrap: wrap;
+  gap: layout.$spacing-03 layout.$spacing-06;
+  padding: layout.$spacing-04 0;
+  border-bottom: 1px solid colors.$gray-20;
+}
+
+.parameter {
+  display: flex;
+  flex-direction: column;
+}
+
+.parameterLabel {
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: colors.$gray-70;
+}
+
+.parameterValue {
+  @include type.type-style('body-compact-01');
+  color: colors.$gray-100;
+}
+
+.dataSet {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-03;
+  border:1px solid colors.$gray-10;
+}
+
+.dataSetTitle {
+  @include type.type-style('heading-03');
+  color: colors.$gray-100;
+  margin-top: layout.$spacing-05;
+  margin-left: layout.$spacing-05;
+}
+
+.tableWrapper {
+  overflow-x: auto;
+  border: 1px solid colors.$gray-20;
+}
+
+.indicatorTable {
+  width: 100%;
+}
+
+.errorState,
+.loadingState {
+  padding: layout.$spacing-07;
+}

package/src/components/utils.tsx

@@ -0,0 +1,65 @@
+import dayjs from 'dayjs';
+import React, { type ReactElement } from 'react';
+import { Csv, DocumentPdf, Json, Xls, Xml, type CarbonIconType } from '@carbon/react/icons';
+import { openmrsFetch } from '@openmrs/esm-framework';
+import type { DownloadFormats } from '../types';
+
+const UNIX_TIMESTAMP_SECONDS_PATTERN = /^\d{10}$/;
+
+export const isUnixTimestampString = (value: string): boolean => {
+  const trimmedValue = value.trim();
+  const timestamp = Number(trimmedValue);
+
+  return (
+    UNIX_TIMESTAMP_SECONDS_PATTERN.test(trimmedValue) &&
+    Number.isSafeInteger(timestamp) &&
+    dayjs.unix(timestamp).isValid()
+  );
+};
+
+const downloadFormatIconMap = {
+  pdf: DocumentPdf,
+  csv: Csv,
+  excel: Xls,
+  json: Json,
+  adx: Xml,
+} as const satisfies Record<DownloadFormats, CarbonIconType>;
+
+export const getDownloadFormatIcon = (downloadFormat: DownloadFormats, size = 20): ReactElement => {
+  const Icon = downloadFormatIconMap[downloadFormat];
+  return <Icon size={size} />;
+};
+
+export const downloadFormatLabel: Record<DownloadFormats, string> = {
+  pdf: 'PDF',
+  csv: 'CSV',
+  excel: 'Excel',
+  json: 'JSON',
+  adx: 'ADX',
+};
+
+const parseFilename = (contentDisposition: string | null): string | null => {
+  if (!contentDisposition) {
+    return null;
+  }
+  const match = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(contentDisposition);
+  return match ? decodeURIComponent(match[1]) : null;
+};
+
+/**
+ * Fetches a completed report request export and triggers a browser download.
+ * The backend serves the file as an attachment, so the response body is read as a
+ * blob rather than parsed as JSON.
+ */
+export const downloadReportRequestFile = async (downloadUrl: string, fallbackFilename: string): Promise<void> => {
+  const response = await openmrsFetch(downloadUrl, { headers: { Accept: '*/*' } });
+  const blob = await response.blob();
+  const objectUrl = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = objectUrl;
+  anchor.download = parseFilename(response.headers?.get('content-disposition')) ?? fallbackFilename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  URL.revokeObjectURL(objectUrl);
+};

package/src/config-schema.ts

@@ -0,0 +1 @@
+export const configSchema = {};

package/src/declarations.d.ts

@@ -0,0 +1,2 @@
+declare module '*.css';
+declare module '*.scss';

package/src/hooks/useReportData.tsx

@@ -0,0 +1,20 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import useSWR from 'swr';
+import { type ReportData } from '../types';
+
+/**
+ * useReportData
+ * Loads the rendered data (datasets, columns, rows) for a completed report request.
+ */
+export const useReportData = (requestId?: string | number) => {
+  const url = requestId ? `${restBaseUrl}/kenyaemr/reportRequests/${requestId}/data` : null;
+
+  const { data, isLoading, error, mutate } = useSWR<{ data: ReportData }>(url, openmrsFetch);
+
+  return {
+    reportData: data?.data ?? null,
+    isLoading,
+    error,
+    mutate,
+  };
+};

package/src/hooks/useReportDefinition.tsx

@@ -0,0 +1,33 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import useSWRImmutable from 'swr/immutable';
+import { type ReportWithDefinition } from '../types';
+
+/**
+ * useReportDefinition
+ * Fetches a single KenyaEMR report together with its definition and parameters.
+ */
+export const useReportDefinition = (reportUuid: string) => {
+  const url = reportUuid ? `${restBaseUrl}/kenyaemr/reports/${reportUuid}` : null;
+
+  const { data, isLoading, error, mutate } = useSWRImmutable<{ data: ReportWithDefinition }>(url, openmrsFetch);
+
+  return {
+    report: data?.data ?? null,
+    parameters: data?.data?.definition?.parameters ?? [],
+    isLoading,
+    error,
+    mutate,
+  };
+};
+
+/**
+ * requestReport
+ * Queues a report request with the supplied parameter values.
+ */
+export const requestReport = (reportUuid: string, parameterValues: Record<string, unknown>) => {
+  return openmrsFetch(`${restBaseUrl}/kenyaemr/reports/${reportUuid}/requests`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: parameterValues,
+  });
+};

package/src/hooks/useReportRequests.tsx

@@ -0,0 +1,26 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import useSWR from 'swr';
+import { type ReportRequest } from '../types';
+
+/**
+ * useReportRequests
+ * Fetches the execution history (report requests) for a given report.
+ * Polls while there are in-flight requests so running rows update automatically.
+ */
+export const useReportRequests = (reportUuid: string) => {
+  const url = reportUuid ? `${restBaseUrl}/kenyaemr/reportRequests?reportUuid=${reportUuid}` : null;
+
+  const { data, isLoading, isValidating, error, mutate } = useSWR<{ data: { results: Array<ReportRequest> } }>(
+    url,
+    openmrsFetch,
+    { refreshInterval: 10000 },
+  );
+
+  return {
+    requests: data?.data?.results ?? [],
+    isLoading,
+    isValidating,
+    error,
+    mutate,
+  };
+};

package/src/hooks/useReports.tsx

@@ -0,0 +1,30 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import useSWRImmutable from 'swr/immutable';
+import { type ReportCategory, type ReportDescriptor, type ReportsResponse } from '../types';
+
+const byName = (a: ReportDescriptor, b: ReportDescriptor) => a.name.localeCompare(b.name);
+
+/**
+ * useGroupedReports
+ * Fetches grouped KenyaEMR reports with each category's reports sorted alphabetically.
+ */
+const useGroupedReports = () => {
+  const url = `${restBaseUrl}/kenyaemr/reports/grouped`;
+
+  const { data, isLoading, error, mutate } = useSWRImmutable<{ data: ReportsResponse }>(url, openmrsFetch);
+
+  const reports: Array<ReportCategory> = (data?.data.results ?? []).map((group) => ({
+    ...group,
+    indicator: [...(group.indicator ?? [])].sort(byName),
+    patientFollowUpReports: [...(group.patientFollowUpReports ?? [])].sort(byName),
+  }));
+
+  return {
+    reports,
+    isLoading,
+    error,
+    mutate,
+  };
+};
+
+export default useGroupedReports;

package/src/index.ts

@@ -0,0 +1,20 @@
+import { defineConfigSchema, getAsyncLifecycle } from '@openmrs/esm-framework';
+import { configSchema } from './config-schema';
+
+const moduleName = '@kenyaemr/esm-esm-reports-app';
+
+const options = {
+  featureName: 'esm-reports-app',
+  moduleName,
+};
+
+export const importTranslation = require.context('../translations', false, /.json$/, 'lazy');
+export const reportsDashboard = getAsyncLifecycle(() => import('./root.component'), options);
+export const reportRequestWorkspaces = getAsyncLifecycle(
+  () => import('./workspaces/report-request.workspaces'),
+  options,
+);
+
+export function startupApp() {
+  defineConfigSchema(moduleName, configSchema);
+}

package/src/root.component.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { Routes, BrowserRouter, Route } from 'react-router-dom';
+import Header from './components/header/header.component';
+import GroupReports from './components/group-reports.component';
+import ReportHistory from './components/report-history/report-history.component';
+import ReportView from './components/report-view/report-view.component';
+
+const ReportDashboard = () => {
+  const spaBasePath = `${(globalThis as any).spaBase}/reporting`;
+  return (
+    <main>
+      <BrowserRouter basename={spaBasePath}>
+        <Header />
+        <Routes>
+          <Route path="/" element={<GroupReports />} />
+          <Route path="/report/:reportUuid" element={<ReportHistory />} />
+          <Route path="/report/:reportUuid/requests/:requestId" element={<ReportView />} />
+        </Routes>
+      </BrowserRouter>
+    </main>
+  );
+};
+
+export default ReportDashboard;

package/src/routes.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json.openmrs.org/routes.schema.json",
+  "backendDependencies": {
+    "kenyaemr": "^19.0.0"
+  },
+  "pages": [
+    {
+      "component": "reportsDashboard",
+      "route": "reporting"
+    }
+  ],
+  "workspaces2": [
+    {
+      "name":"report-request-workspace",
+      "component":"reportRequestWorkspaces",
+      "window":"reporting-window"
+    }
+  ],
+  "workspaceWindows2": [
+    {
+      "name" : "reporting-window",
+      "group" : "reporting-group",
+      "width": "wider",
+      "canMaximize":true
+    }
+  ],
+  "workspaceGroups2": [
+   {
+    "name":"reporting-group",
+    "closeable":true,
+    "scopePattern":"reporting"
+   }
+  ],
+  "extensions": [
+    
+  ],
+  "modals": [
+    
+  ]
+}

package/src/types/index.ts

@@ -0,0 +1,96 @@
+export type ReportDescriptor = {
+  uuid: string;
+  name: string;
+  description: string | null;
+  type: 'IndicatorReportDescriptor' | 'HybridReportDescriptor' | 'CalculationReportDescriptor';
+  indicator: boolean;
+  hybrid: boolean;
+  template?: string | null;
+  repeatingSection?: string | null;
+};
+
+export type ReportCategory = {
+  name: string;
+  indicator: Array<ReportDescriptor>;
+  patientFollowUpReports: Array<ReportDescriptor>;
+};
+
+export type ReportsResponse = {
+  appId: string;
+  results: Array<ReportCategory>;
+};
+
+export type ReportParameterType =
+  | 'java.util.Date'
+  | 'java.lang.String'
+  | 'java.lang.Integer'
+  | 'java.lang.Long'
+  | 'java.lang.Double'
+  | 'java.lang.Boolean';
+
+export interface ReportParameter {
+  name: string;
+  label: string;
+  type: ReportParameterType | string;
+  defaultValue: string | number | boolean | null;
+}
+
+export interface ReportDefinition {
+  uuid: string;
+  name: string;
+  description: string;
+  parameters: Array<ReportParameter>;
+  dataSets: Array<string>;
+}
+
+export type ReportWithDefinition = ReportDescriptor & {
+  requestUrl: string;
+  requestsUrl: string;
+  definition: ReportDefinition | null;
+};
+
+export type ReportRequestStatus = 'REQUESTED' | 'SAVED' | 'SCHEDULED' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | string;
+
+export interface ReportRequest {
+  id: number;
+  uuid: string;
+  status: ReportRequestStatus;
+  requestDate: string;
+  evaluateStartDatetime: string | null;
+  evaluateCompleteDatetime: string | null;
+  priority: string;
+  parameters: Record<string, unknown>;
+  requestedBy?: {
+    uuid: string;
+    display: string;
+  };
+  report?: {
+    uuid: string;
+    name: string;
+    description: string | null;
+  };
+  downloadUrls: Partial<Record<DownloadFormats, string>>;
+  downloadFormats: Array<DownloadFormats>;
+}
+
+export type DownloadFormats = 'pdf' | 'csv' | 'json' | 'excel' | 'adx';
+
+export interface ReportDataSetColumn {
+  name: string;
+  label: string;
+}
+
+export interface ReportDataSet {
+  key: string;
+  name: string;
+  columns: Array<ReportDataSetColumn>;
+  rows: Array<Record<string, unknown>>;
+  values?: Record<string, unknown>;
+}
+
+export interface ReportData {
+  request: ReportRequest;
+  definition: ReportDefinition;
+  parameters: Record<string, unknown>;
+  dataSets: Record<string, ReportDataSet>;
+}

package/src/usePrintPreview.tsx

@@ -0,0 +1,17 @@
+import useSWR from 'swr';
+
+const fetcher = async (url: string) => {
+  const res = await fetch(url, {
+    headers: {
+      'Content-Type': 'application/pdf',
+    },
+  });
+  const fileData = await res.arrayBuffer();
+  const blob = new Blob([fileData], { type: 'application/pdf' });
+  return URL.createObjectURL(blob);
+};
+
+export const usePrintPreview = (url: string) => {
+  const { data, isLoading, error, mutate } = useSWR<String>(url, fetcher);
+  return { data, isLoading, error, mutate };
+};