@ampath/esm-reports-app 1.0.0-next.7 → 1.0.0-next.71

package/src/common/report-register/register-table.scss

@@ -0,0 +1,71 @@
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+/* The one stylesheet every register table uses.
+ *
+ * Registers previously borrowed their parent report's sheet, so a report sized
+ * for an A4 page dragged its paper typography into its line lists, and the same
+ * table rules were restated in half a dozen files that drifted apart. These are
+ * screen tables: dense, scrollable, and independent of how their report prints.
+ */
+
+.tableContainer {
+  width: 100%;
+}
+
+/* Sized to content rather than to the frame, so a long value -- a full name,
+   say -- widens its own column instead of wrapping. `.tableScroll` in the
+   layout scrolls when the table outgrows the page. */
+
+.table {
+  width: auto;
+  min-width: 100%;
+  margin: 0;
+  font-size: 0.75rem;
+  border-collapse: collapse;
+}
+
+.tableBordered td,
+.tableBordered th {
+  padding: 0.125rem 0.5rem;
+  font-size: 0.75rem;
+  line-height: 1.3;
+  border: 1px solid $ui-04;
+}
+
+.tableBordered th {
+  font-weight: 600;
+  color: $color-gray-100;
+  background-color: $ui-01;
+  /* headings carry deliberate line breaks, so they wrap where the markup says */
+  white-space: normal;
+}
+
+.tableBordered td {
+  white-space: nowrap;
+}
+
+/* Long prose columns (diagnoses, referrals, comments) wrap inside a bounded
+   width instead of stretching the row past the fold. */
+.tableBordered td.wrapCell {
+  white-space: normal;
+  min-width: 8rem;
+  max-width: 16rem;
+  overflow-wrap: anywhere;
+}
+
+.tableStriped tbody tr:nth-of-type(odd) {
+  background-color: $ui-01;
+}
+
+.tableStriped tbody tr:hover {
+  background-color: $brand-primary-10;
+}
+
+.textCentre {
+  text-align: center;
+}
+
+.verticalText {
+  writing-mode: vertical-rl;
+  transform: rotate(180deg);
+}

package/src/common/report-register/report-parents.ts

@@ -0,0 +1,27 @@
+/**
+ * The report each register can be opened from.
+ *
+ * Several registers serve more than one report -- MOH 333, 405 and 406 are
+ * reached from both MOH-711 and MOH-717, and MOH 412 from both MOH-711 and
+ * MOH-745. A register cannot name its parent as a constant, then: whichever
+ * report it named, the trail would be wrong for everyone arriving from the
+ * other one. The link carries `from`, and the trail is resolved from it.
+ */
+export interface ReportParent {
+  label: string;
+  path: string;
+}
+
+export const REPORT_PARENTS: Record<string, ReportParent> = {
+  'moh-240': { label: 'MOH-240 Register', path: '/moh-240' },
+  'moh-505': { label: 'MOH-505 Report', path: '/moh-505' },
+  'moh-705a': { label: 'MOH-705A Report', path: '/moh-705a' },
+  'moh-705b': { label: 'MOH-705B Report', path: '/moh-705b' },
+  'moh-706': { label: 'MOH-706 Report', path: '/moh-706' },
+  'moh-710': { label: 'MOH-710 Report', path: '/moh-710' },
+  'moh-711': { label: 'MOH-711 Report', path: '/moh-711' },
+  'moh-717': { label: 'MOH-717 Report', path: '/moh-717' },
+  'moh-731': { label: 'MOH-731 Report', path: '/moh-731' },
+  'moh-740': { label: 'MOH-740 Report', path: '/moh-740' },
+  'moh-745': { label: 'MOH-745 Report', path: '/moh-745' },
+};

package/src/common/report-register/rows-to-csv.ts

@@ -0,0 +1,89 @@
+import { type RegisterColumn } from './register-columns';
+
+/**
+ * Serialises line-list rows to CSV.
+ *
+ * Built from the data rather than from the rendered table: with pagination the
+ * DOM only ever holds one page, so scraping it would quietly export 50 rows
+ * while looking like it exported all 2,000 -- the worst way for an export to
+ * fail. The trade-off is that the file carries the API's own fields rather
+ * than the register's printed column headings, which is what a spreadsheet
+ * wants anyway.
+ */
+
+/**
+ * Forces text Excel cannot mangle. A cell starting with `=`, `+`, `-` or `@`
+ * is parsed as a formula (`+2547...` becomes `#NAME?`), and a long digit-only
+ * cell is reinterpreted as a number (leading zeros dropped, switched to
+ * scientific notation), so both are emitted as an explicit text formula
+ * (`"..."` quoted inside `=`, which Excel renders as literal text).
+ */
+const FORMULA_PREFIX = /^[=+\-@]/;
+const LONG_DIGITS = /^\d{9,}$/;
+
+function escapeCell(value: unknown, forceText = false): string {
+  const text = value === null || value === undefined ? '' : String(value).replace(/\s+/g, ' ').trim();
+
+  if (forceText && text !== '') {
+    return `="${text.replace(/"/g, '""')}"`;
+  }
+
+  if (text !== '' && (FORMULA_PREFIX.test(text) || LONG_DIGITS.test(text))) {
+    return `="${text.replace(/"/g, '""')}"`;
+  }
+
+  return /[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+/** Serialises using the register's own columns, so the file matches the form */
+export function columnsToCsv(
+  rows: Array<Record<string, any>>,
+  columns: RegisterColumn[],
+  options?: {
+    /** A second header row (e.g. the printed form's column letters) */
+    subHeaderRow?: string[];
+  },
+): string {
+  const headerRows = [
+    columns.map((column) => escapeCell(column.header)).join(','),
+    ...(options?.subHeaderRow ? [options.subHeaderRow.map((cell) => escapeCell(cell)).join(',')] : []),
+  ];
+
+  return [
+    ...headerRows,
+    ...rows.map((row, index) => columns.map((column) => escapeCell(column.value(row, index), column.text)).join(',')),
+  ].join('\r\n');
+}
+
+/** Fallback for registers with no column spec yet: the response's own fields */
+export function rowsToCsv(rows: Array<Record<string, any>>): string {
+  if (!rows.length) {
+    return '';
+  }
+
+  /* Union of keys, not just the first row's: endpoints omit fields that are
+     null for a given client, so keying off row one drops columns. */
+  const keys = new Set<string>();
+  rows.forEach((row) => Object.keys(row).forEach((key) => keys.add(key)));
+  const columns = Array.from(keys);
+
+  return [
+    columns.map((column) => escapeCell(column)).join(','),
+    ...rows.map((row) => columns.map((column) => escapeCell(row[column])).join(',')),
+  ].join('\r\n');
+}
+
+/** Prompts the browser to save `csv` under `filename` */
+export function downloadCsv(csv: string, filename: string): void {
+  // the BOM is what makes Excel read the file as UTF-8 rather than latin-1
+  const blob = new Blob([`${csv}`], { type: 'text/csv;charset=utf-8;' });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+
+  link.href = url;
+  link.download = filename;
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  URL.revokeObjectURL(url);
+}

package/src/common/report-register/use-location-name.ts

@@ -0,0 +1,54 @@
+import { useEffect, useState } from 'react';
+import { openmrsFetch, useSession } from '@openmrs/esm-framework';
+
+/**
+ * The display name of the location(s) a register was generated for.
+ *
+ * Read from the link's `locationUuids` rather than the session: the user may
+ * have switched location since generating the report, and the register must
+ * name the location its rows came from. The session location answers without
+ * a request when it is the one asked for; any other is looked up. Several
+ * uuids (comma-separated) are named in order.
+ */
+export function useLocationName(locationUuids: string | null | undefined): string {
+  const session = useSession();
+  const uuids = (locationUuids ?? '')
+    .split(',')
+    .map((uuid) => uuid.trim())
+    .filter(Boolean);
+  const key = uuids.join(',');
+  const sessionUuid = session?.sessionLocation?.uuid;
+  const sessionName = session?.sessionLocation?.display;
+
+  const [names, setNames] = useState<Record<string, string>>({});
+
+  useEffect(() => {
+    const missing = uuids.filter((uuid) => uuid !== sessionUuid);
+    if (missing.length === 0) {
+      return;
+    }
+
+    const abortController = new AbortController();
+
+    Promise.all(
+      missing.map((uuid) =>
+        openmrsFetch(`/ws/rest/v1/location/${uuid}?v=custom:(display)`, { signal: abortController.signal })
+          .then((response) => response.json())
+          .then((location) => [uuid, location?.display ?? ''] as const)
+          .catch(() => [uuid, ''] as const),
+      ),
+    ).then((found) => {
+      if (!abortController.signal.aborted) {
+        setNames(Object.fromEntries(found.filter(([, name]) => name)));
+      }
+    });
+
+    return () => abortController.abort();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, sessionUuid]);
+
+  return uuids
+    .map((uuid) => (uuid === sessionUuid ? sessionName : names[uuid]))
+    .filter(Boolean)
+    .join(', ');
+}

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,173 @@
+import {
+  Activity,
+  ChartColumn,
+  Document,
+  DocumentTasks,
+  GenderFemale,
+  Growth,
+  HealthCross,
+  Microscope,
+  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 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'],
+      },
+    ],
+  },
+];
+
+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);
+}