@ampath/esm-reports-app 1.0.0-next.8 → 1.0.0-next.81

package/src/common/report-register/use-patient-list.ts

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { PAGE_SIZE, type PatientListPage } from '../../resources/patient-list-page';
+import { showReportError } from '../report-error';
+
+type Fetcher = (paging: { startIndex: number; limit: number }) => Promise<PatientListPage>;
+
+/**
+ * Page state and fetching for a register's line list.
+ *
+ * Registers used to ask for a hardcoded 300 rows and render every one of them.
+ * At 41 columns that is 12,300 cells, and anything past 300 was silently
+ * dropped. This fetches a page at a time, so the DOM stays flat however large
+ * the list is, and reports the total so truncation is never invisible.
+ */
+export function usePatientList(fetcher: Fetcher, deps: React.DependencyList) {
+  const [rows, setRows] = useState<Array<Record<string, any>>>([]);
+  const [total, setTotal] = useState(0);
+  const [isTotalExact, setIsTotalExact] = useState(true);
+  const [isLoading, setIsLoading] = useState(false);
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(PAGE_SIZE);
+
+  /* Guards against an earlier page landing after a later one and overwriting
+     it, which is easy to trigger by clicking through pages quickly. */
+  const request = useRef(0);
+
+  const load = useCallback(
+    async (nextPage: number, size: number) => {
+      const id = ++request.current;
+
+      setIsLoading(true);
+
+      try {
+        const result = await fetcher({ startIndex: (nextPage - 1) * size, limit: size });
+
+        if (id !== request.current) {
+          return;
+        }
+
+        setRows(result.results);
+        setTotal(result.total);
+        setIsTotalExact(result.isTotalExact);
+      } catch (error) {
+        if (id === request.current) {
+          setRows([]);
+          showReportError('the register', error);
+        }
+      } finally {
+        if (id === request.current) {
+          setIsLoading(false);
+        }
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    deps,
+  );
+
+  /** Back to page one whenever the query behind the list changes */
+  useEffect(() => {
+    setPage(1);
+    load(1, pageSize);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+
+  const onPageChange = useCallback(
+    ({ page: nextPage, pageSize: nextSize }: { page: number; pageSize: number }) => {
+      setPage(nextPage);
+      setPageSize(nextSize);
+      load(nextPage, nextSize);
+    },
+    [load],
+  );
+
+  /** Every row across every page, for the CSV export */
+  const fetchAll = useCallback(async () => {
+    const all: Array<Record<string, any>> = [];
+    const size = 500;
+
+    for (let index = 0; ; index += size) {
+      const result = await fetcher({ startIndex: index, limit: size });
+      all.push(...result.results);
+
+      if (result.results.length < size) {
+        return all;
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+
+  return { rows, total, isTotalExact, isLoading, page, pageSize, onPageChange, fetchAll };
+}

package/src/common/report-skeleton/index.ts

@@ -0,0 +1 @@
+export * from './report-skeleton.component';

package/src/common/report-skeleton/report-skeleton.component.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import { DataTableSkeleton, SkeletonText } from '@carbon/react';
+
+import styles from './report-skeleton.scss';
+
+interface ReportSkeletonProps {
+  /** How many indicator blocks to outline. Roughly the sections a form has. */
+  blocks?: number;
+}
+
+/**
+ * Placeholder in the shape of a generated report.
+ *
+ * Reports replaced their whole body while fetching, so a centred spinner left
+ * the page blank and shifted everything when the data landed. Outlining the
+ * masthead and the indicator tables keeps the layout stable and shows how much
+ * is coming.
+ */
+export const ReportSkeleton: React.FC<ReportSkeletonProps> = ({ blocks = 2 }) => (
+  <div className={styles.skeleton} aria-busy="true" aria-label="Loading report">
+    <div className={styles.header}>
+      <SkeletonText heading width="45%" />
+      <SkeletonText width="70%" />
+    </div>
+
+    {Array.from({ length: blocks }, (_, index) => (
+      <div key={index} className={styles.block}>
+        <SkeletonText heading width="30%" />
+        <DataTableSkeleton showHeader={false} showToolbar={false} columnCount={4} rowCount={5} size="sm" />
+      </div>
+    ))}
+  </div>
+);
+
+/**
+ * Placeholder for the register and patient-list pages, which are a single
+ * table rather than a form.
+ */
+export const RegisterSkeleton: React.FC<{ columnCount?: number; rowCount?: number }> = ({
+  columnCount = 6,
+  rowCount = 8,
+}) => (
+  <div className={styles.skeleton} aria-busy="true" aria-label="Loading register">
+    <DataTableSkeleton showHeader={false} showToolbar={false} columnCount={columnCount} rowCount={rowCount} size="sm" />
+  </div>
+);

package/src/common/report-skeleton/report-skeleton.scss

@@ -0,0 +1,29 @@
+@use '@carbon/layout';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.skeleton {
+  padding: layout.$spacing-05;
+  margin-bottom: layout.$spacing-05;
+  background-color: $ui-02;
+  border: 1px solid $ui-03;
+}
+
+/* When it stands in for a register table it sits under the caption bar */
+.skeleton:not(:first-child) {
+  margin-bottom: 0;
+  border-top: none;
+}
+
+.header {
+  padding-bottom: layout.$spacing-05;
+  margin-bottom: layout.$spacing-05;
+  border-bottom: 1px solid $ui-03;
+}
+
+.block {
+  margin-bottom: layout.$spacing-06;
+
+  &:last-child {
+    margin-bottom: 0;
+  }
+}

package/src/config-schema.ts

@@ -3,10 +3,18 @@ export const configSchema = {
   etlBaseUrl: {
     _type: Type.String,
     _default: '',
-    _description: 'ETL endpoint',
+    _description: 'Base URL of the ETL service every report reads from, e.g. "/etl"',
+  },
+  /* Declared because the deployment sets it in this section. Nothing reads it
+     yet; without it the config validator reports it as an unknown key. */
+  subDomainUrl: {
+    _type: Type.String,
+    _default: '',
+    _description: 'Origin this instance is served from',
   },
 };
 
 export type Config = {
   etlBaseUrl: string;
+  subDomainUrl: string;
 };

package/src/dashboard/report-catalog.ts

@@ -0,0 +1,191 @@
+import {
+  Activity,
+  ChartColumn,
+  Document,
+  DocumentTasks,
+  GenderFemale,
+  Growth,
+  HealthCross,
+  Medication,
+  Microscope,
+  Stethoscope,
+  UserMultiple,
+  Warning,
+  type CarbonIconType,
+} from '@carbon/react/icons';
+
+export type ReportTone = 'violet' | 'magenta' | 'teal' | 'blue';
+
+export interface ReportDefinition {
+  /** The MOH form number, e.g. `MOH 731` */
+  code: string;
+  /** Human readable name of the form */
+  name: string;
+  description: string;
+  /** Route registered in root.component.tsx */
+  path: string;
+  icon: CarbonIconType;
+  /** Extra terms matched by the search field */
+  keywords: string[];
+}
+
+export interface ReportCategory {
+  id: string;
+  title: string;
+  description: string;
+  tone: ReportTone;
+  reports: ReportDefinition[];
+}
+
+export const reportCategories: ReportCategory[] = [
+  {
+    id: 'hiv-and-chronic-care',
+    title: 'HIV & chronic care',
+    description: 'Comprehensive care programme summaries',
+    tone: 'violet',
+    reports: [
+      {
+        code: 'MOH 731',
+        name: 'Comprehensive HIV/AIDS',
+        description: 'NASCOP monthly summary for HIV testing, EMTCT, care and treatment.',
+        path: '/moh-731',
+        icon: HealthCross,
+        keywords: ['hiv', 'nascop', 'art', 'prep', 'emtct', 'pmtct', 'tb'],
+      },
+      {
+        code: 'MOH 729B',
+        name: 'Facility ARV patient summary (F-MAPS)',
+        description: 'Monthly count of current active patients on each ARV and OI regimen.',
+        path: '/moh-729b',
+        icon: Medication,
+        keywords: ['fmaps', 'f-maps', 'arv', 'regimen', 'art', 'pmtct', 'pep', 'prep', 'tpt', 'pharmacy'],
+      },
+      {
+        code: 'MOH 740',
+        name: 'Diabetes & hypertension',
+        description: 'Monthly summary for the NCD comprehensive care clinic.',
+        path: '/moh-740',
+        icon: Activity,
+        keywords: ['ncd', 'diabetes', 'hypertension', 'chronic'],
+      },
+    ],
+  },
+  {
+    id: 'reproductive-and-child-health',
+    title: 'Reproductive & child health',
+    description: 'RMNCAH service delivery summaries',
+    tone: 'magenta',
+    reports: [
+      {
+        code: 'MOH 710',
+        name: 'Immunization',
+        description: 'Child immunization and vitamin A supplementation summary.',
+        path: '/moh-710',
+        icon: Growth,
+        keywords: ['immunization', 'vaccine', 'child', 'khis', 'bcg', 'polio'],
+      },
+      {
+        code: 'MOH 711',
+        name: 'Integrated programme summary',
+        description: 'Reproductive and child health, medical and rehabilitation services.',
+        path: '/moh-711',
+        icon: UserMultiple,
+        keywords: ['rmncah', 'anc', 'pnc', 'maternity', 'family planning', 'gbv', 'physiotherapy'],
+      },
+      {
+        code: 'MOH 745',
+        name: 'Cancer screening',
+        description: 'Monthly cervical and breast cancer screening summary.',
+        path: '/moh-745',
+        icon: GenderFemale,
+        keywords: ['cancer', 'cervical', 'screening', 'via', 'hpv'],
+      },
+    ],
+  },
+  {
+    id: 'outpatient-and-workload',
+    title: 'Outpatient & workload',
+    description: 'Morbidity and facility workload returns',
+    tone: 'teal',
+    reports: [
+      {
+        code: 'MOH 705A',
+        name: 'Outpatient morbidity, under 5',
+        description: 'Summary of diagnoses for children under five years.',
+        path: '/moh-705a',
+        icon: DocumentTasks,
+        keywords: ['morbidity', 'outpatient', 'under five', 'children', 'khis'],
+      },
+      {
+        code: 'MOH 705B',
+        name: 'Outpatient morbidity, over 5',
+        description: 'Summary of diagnoses for clients aged five years and above.',
+        path: '/moh-705b',
+        icon: Document,
+        keywords: ['morbidity', 'outpatient', 'above five', 'adults', 'khis'],
+      },
+      {
+        code: 'MOH 717',
+        name: 'Service workload',
+        description: 'Monthly service workload across facility departments.',
+        path: '/moh-717',
+        icon: ChartColumn,
+        keywords: ['workload', 'inpatient', 'pharmacy', 'mortuary', 'theatre', 'maternity'],
+      },
+    ],
+  },
+  {
+    id: 'diagnostics-and-surveillance',
+    title: 'Diagnostics & surveillance',
+    description: 'Laboratory and disease surveillance returns',
+    tone: 'blue',
+    reports: [
+      {
+        code: 'MOH 706',
+        name: 'Laboratory services',
+        description: 'Monthly summary of laboratory investigations and results.',
+        path: '/moh-706',
+        icon: Microscope,
+        keywords: ['laboratory', 'lab', 'urine', 'parasitology', 'blood chemistry'],
+      },
+      {
+        code: 'MOH 505',
+        name: 'IDSR epidemic monitoring',
+        description: 'Weekly monitoring form for priority notifiable diseases.',
+        path: '/moh-505',
+        icon: Warning,
+        keywords: ['idsr', 'surveillance', 'epidemic', 'notifiable', 'outbreak'],
+      },
+      {
+        code: 'MOH/F/DNTLDP/02',
+        name: 'TB active case finding summary',
+        description: 'Monthly facility summary of TB screening, investigation, diagnosis and treatment by department.',
+        path: '/acf-summary',
+        icon: Stethoscope,
+        keywords: ['tb', 'tuberculosis', 'acf', 'active case finding', 'screening', 'presumptive', 'dntldp'],
+      },
+    ],
+  },
+];
+
+export const totalReportCount = reportCategories.reduce((count, category) => count + category.reports.length, 0);
+
+export function filterCategories(categories: ReportCategory[], searchTerm: string): ReportCategory[] {
+  const term = searchTerm.trim().toLowerCase();
+
+  if (!term) {
+    return categories;
+  }
+
+  return categories
+    .map((category) => ({
+      ...category,
+      reports: category.reports.filter((report) =>
+        [report.code, report.name, report.description, category.title, ...report.keywords]
+          .join(' ')
+          .toLowerCase()
+          .includes(term),
+      ),
+    }))
+    .filter((category) => category.reports.length > 0);
+}

package/src/dashboard/reports-dasboard.tsx

@@ -1,28 +1,199 @@
-import React from 'react';
-import { useNavigate } from 'react-router-dom';
-import { ClickableTile } from '@carbon/react';
+import React, { useState } from 'react';
+import { useNavigate, useSearchParams } from 'react-router-dom';
+import { Button, ClickableTile, Layer, Search, Tab, TabList, TabPanel, TabPanels, Tabs, Tag } from '@carbon/react';
+import { ArrowRight, DocumentMultiple_01, Report, type CarbonIconType } from '@carbon/react/icons';
+import { formatDate, useSession } from '@openmrs/esm-framework';
 
+import { registerCategories, totalRegisterCount } from '../registers/register-catalog';
+import {
+  filterCategories,
+  reportCategories,
+  totalReportCount,
+  type ReportCategory,
+  type ReportDefinition,
+} from './report-catalog';
 import styles from './reports-dashboard.module.scss';
+
 interface ReportsDashboardProps {}
+
 const ReportsDashboard: React.FC<ReportsDashboardProps> = () => {
   const navigate = useNavigate();
+  const session = useSession();
+  /* each tab keeps its own search */
+  const [reportSearch, setReportSearch] = useState<string>('');
+  const [registerSearch, setRegisterSearch] = useState<string>('');
+
+  /* Reports first, Registers second; the open tab is kept in the URL */
+  const [searchParams, setSearchParams] = useSearchParams();
+  const selectedTab = searchParams.get('tab') === 'registers' ? 1 : 0;
+  const selectTab = ({ selectedIndex }: { selectedIndex: number }) => {
+    const next = new URLSearchParams(searchParams);
+    if (selectedIndex === 1) {
+      next.set('tab', 'registers');
+    } else {
+      next.delete('tab');
+    }
+    setSearchParams(next, { replace: true });
+  };
+
+  const facilityName = session?.sessionLocation?.display;
+  const today = formatDate(new Date(), { mode: 'standard', time: false, noToday: true });
+
+  const renderReportTile = (report: ReportDefinition, tone: string) => {
+    const Icon = report.icon;
+
+    return (
+      <ClickableTile
+        key={report.path}
+        className={styles.tile}
+        data-tone={tone}
+        onClick={() => navigate(report.path)}
+        aria-label={`${report.code} ${report.name}`}
+      >
+        <div className={styles.tileIcon}>
+          <Icon size={20} />
+        </div>
+        <div className={styles.tileCopy}>
+          <p className={styles.tileCode}>{report.code}</p>
+          <h4 className={styles.tileName}>{report.name}</h4>
+        </div>
+        <ArrowRight size={16} className={styles.tileArrow} />
+      </ClickableTile>
+    );
+  };
+
+  const renderCategory = (category: ReportCategory) => (
+    <section key={category.id} className={styles.category}>
+      <div className={styles.categoryHeader} data-tone={category.tone}>
+        <h5 className={styles.categoryTitle}>{category.title}</h5>
+        <Tag size="sm" type="outline">
+          {category.reports.length}
+        </Tag>
+      </div>
+      <div className={styles.grid}>{category.reports.map((report) => renderReportTile(report, category.tone))}</div>
+    </section>
+  );
+
+  /** A tab's list: search row, then its categories, or a message when nothing matches */
+  const renderCatalog = ({
+    id,
+    noun,
+    categories,
+    total,
+    term,
+    setTerm,
+    icon: Icon,
+    hint,
+  }: {
+    id: string;
+    noun: string;
+    categories: ReportCategory[];
+    total: number;
+    term: string;
+    setTerm: (term: string) => void;
+    icon: CarbonIconType;
+    hint: string;
+  }) => {
+    const visible = filterCategories(categories, term);
+    const matches = visible.reduce((count, category) => count + category.reports.length, 0);
+    const isSearching = term.trim().length > 0;
+    const label = `Search ${noun}`;
+    /* "1 register", "10 reports" */
+    const counted = (n: number) => (n === 1 ? noun.replace(/s$/, '') : noun);
+
+    return (
+      <>
+        <div className={styles.toolbar}>
+          <Layer className={styles.searchLayer}>
+            <Search
+              id={id}
+              labelText={label}
+              placeholder={label}
+              size="md"
+              value={term}
+              onChange={(event) => setTerm(event.target.value)}
+              onClear={() => setTerm('')}
+            />
+          </Layer>
+          <p className={styles.resultCount}>
+            {isSearching ? `${matches} of ${total} ${counted(total)}` : `${total} ${counted(total)} available`}
+          </p>
+        </div>
+
+        {visible.length > 0 ? (
+          visible.map(renderCategory)
+        ) : (
+          <Layer className={styles.emptyState}>
+            <Icon size={32} className={styles.emptyStateIcon} />
+            <h5>
+              No {noun} match &ldquo;{term}&rdquo;
+            </h5>
+            <p>{hint}</p>
+            <Button kind="ghost" size="sm" onClick={() => setTerm('')}>
+              Clear search
+            </Button>
+          </Layer>
+        )}
+      </>
+    );
+  };
+
   return (
-    <>
-      <div className={styles.container}>
-        <ClickableTile onClick={() => navigate('/moh-710')} className={styles.tile}>
-          MOH-710 REPORT
-        </ClickableTile>
-        <ClickableTile onClick={() => navigate('/moh-711')} className={styles.tile}>
-          MOH-711 REPORT
-        </ClickableTile>
-        <ClickableTile onClick={() => navigate('/moh-717')} className={styles.tile}>
-          MOH-717 REPORT
-        </ClickableTile>
-        <ClickableTile onClick={() => navigate('/moh-706')} className={styles.tile}>
-          MOH-706 REPORT
-        </ClickableTile>
+    <div className={styles.dashboard}>
+      {/* The facility and date sit at the right end of the tab row */}
+      <div className={styles.tabsArea}>
+        <p className={styles.headerMeta}>{[facilityName, today].filter(Boolean).join(' · ')}</p>
+        <Tabs selectedIndex={selectedTab} onChange={selectTab}>
+          <TabList aria-label="Reports and registers" className={styles.tabList}>
+            <Tab>
+              <span className={styles.tabLabel}>
+                <Report size={16} />
+                Reports
+                <Tag size="sm" type="gray" className={styles.tabCount}>
+                  {totalReportCount}
+                </Tag>
+              </span>
+            </Tab>
+            <Tab>
+              <span className={styles.tabLabel}>
+                <DocumentMultiple_01 size={16} />
+                Registers
+                <Tag size="sm" type="gray" className={styles.tabCount}>
+                  {totalRegisterCount}
+                </Tag>
+              </span>
+            </Tab>
+          </TabList>
+          <TabPanels>
+            <TabPanel className={styles.tabPanel}>
+              {renderCatalog({
+                id: 'reports-search',
+                noun: 'reports',
+                categories: reportCategories,
+                total: totalReportCount,
+                term: reportSearch,
+                setTerm: setReportSearch,
+                icon: Report,
+                hint: 'Try a form number such as 731, or a service such as immunization.',
+              })}
+            </TabPanel>
+            <TabPanel className={styles.tabPanel}>
+              {/* Registers, from src/registers, listed and searched as the reports are */}
+              {renderCatalog({
+                id: 'registers-search',
+                noun: 'registers',
+                categories: registerCategories,
+                total: totalRegisterCount,
+                term: registerSearch,
+                setTerm: setRegisterSearch,
+                icon: DocumentMultiple_01,
+                hint: 'Try a register number such as 362, or a service such as HTS.',
+              })}
+            </TabPanel>
+          </TabPanels>
+        </Tabs>
       </div>
-    </>
+    </div>
   );
 };