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

package/src/common/report-register/register-layout.component.tsx

@@ -0,0 +1,265 @@
+import React from 'react';
+import { Breadcrumb, BreadcrumbItem, Button, Layer, Pagination } from '@carbon/react';
+import { Link, useSearchParams } from 'react-router-dom';
+import { ArrowLeft, Calendar, Document, Download, Location } from '@carbon/react/icons';
+import { formatDate } from '@openmrs/esm-framework';
+
+import { formatIndicatorName } from '../../utils/format-indicator';
+import { showReportError } from '../report-error';
+import { columnsToCsv, downloadCsv, rowsToCsv } from './rows-to-csv';
+import { type RegisterColumn } from './register-columns';
+import { REPORT_PARENTS } from './report-parents';
+
+import { RegisterSkeleton } from '../report-skeleton';
+import styles from './register-layout.scss';
+
+interface RegisterLayoutProps {
+  /** The report this register was opened from, e.g. `MOH-731 Report` */
+  parentLabel: string;
+  /** Route back to that report, e.g. `/moh-731` */
+  parentPath?: string;
+  /**
+   * Returns to the report in place, for a register that is a view on the
+   * report's own route rather than a route of its own.
+   *
+   * MOH-740 toggles its registers in place, so there is nowhere to navigate:
+   * a breadcrumb would link the page to itself. Given this, the trail is
+   * replaced by a button that puts the report back.
+   */
+  onBack?: () => void;
+  /** Register name, e.g. `HIV Care Treatment Daily Activity Register MOH 366` */
+  title: string;
+  /**
+   * The page heading, when the register can name the figure itself. Without
+   * it the heading is built from the link's `label` and `gender`.
+   */
+  heading?: string;
+  /** The location the register was generated for, shown beside the period */
+  location?: string;
+  isLoading: boolean;
+  /** `true` once loaded with nothing to show */
+  isEmpty: boolean;
+  /** Paging state from `usePatientList` */
+  page?: number;
+  pageSize?: number;
+  total?: number;
+  /** `false` when the total is a lower bound the endpoint did not confirm */
+  isTotalExact?: boolean;
+  onPageChange?: (change: { page: number; pageSize: number }) => void;
+  /** Every row across every page, used to build the export */
+  fetchAll?: () => Promise<Array<Record<string, any>>>;
+  /** The register's own columns. Without them the export falls back to the
+      response's raw fields, which will not match the printed form. */
+  columns?: RegisterColumn[];
+  /**
+   * The printed form's own sub-headings (e.g. its column letters), written as
+   * a second CSV row so exports stay line-numbered against the paper form.
+   */
+  subHeaders?: string[];
+  /** The register table. Optional: MOH 510 has no table implemented yet. */
+  children?: React.ReactNode;
+}
+
+/**
+ * The frame every drill-down register renders inside.
+ *
+ * Registers are opened from a value box on a report, so the trail back matters
+ * more than a bare Back button: the breadcrumb shows where the figure came
+ * from and lets the user step to either level. The table itself is wide -- the
+ * MOH 366 register runs to 41 columns -- so it scrolls within the page rather
+ * than forcing the whole layout sideways.
+ */
+const GENDERS: Record<string, string> = { M: 'Male', F: 'Female' };
+
+const RegisterLayout: React.FC<RegisterLayoutProps> = ({
+  parentLabel,
+  parentPath,
+  onBack,
+  title,
+  heading: headingProp,
+  location,
+  isLoading,
+  isEmpty,
+  page,
+  pageSize,
+  total,
+  isTotalExact = true,
+  onPageChange,
+  fetchAll,
+  columns,
+  subHeaders,
+  children,
+}) => {
+  /* The same register serves every indicator that links to it, so without this
+     each drill-down looks identical no matter which box was clicked. */
+  const [params] = useSearchParams();
+  const [isExporting, setIsExporting] = React.useState(false);
+  const indicator = params.get('indicator') ?? params.get('indicators');
+  /* The report passes the row label it displayed, so the crumb reads the way
+     the figure was labelled on the form. `formatIndicatorName` is the fallback
+     for links made before the label was carried through. */
+  const label = params.get('label');
+  const gender = params.get('gender');
+  const startDate = params.get('startDate');
+  const endDate = params.get('endDate');
+  const locationUuids = params.get('locationUuids');
+
+  /* Where the drill-down came from. Registers shared by two reports cannot
+     name their parent as a constant, so the link says which one it was; the
+     props remain the fallback for links made before it was carried. */
+  const from = params.get('from');
+  const parent = (from && REPORT_PARENTS[from]) || { label: parentLabel, path: parentPath ?? '' };
+
+  /* The crumb has to carry the period, not just the path: a report that does
+     not keep its figures in session storage regenerates from its URL, and
+     linking to the bare path would land the user on the placeholder instead of
+     the figures the register was opened from. */
+  const parentQuery = new URLSearchParams();
+  if (locationUuids) parentQuery.append('locationUuids', locationUuids);
+  if (startDate) parentQuery.append('startDate', startDate);
+  if (endDate) parentQuery.append('endDate', endDate);
+  /* back to the report tab the register was opened from, e.g. a summary view */
+  const view = params.get('view');
+  if (view) parentQuery.append('view', view);
+  const section = params.get('section');
+  if (section) parentQuery.append('section', section);
+  const parentLink = parentQuery.toString() ? `${parent.path}?${parentQuery}` : parent.path;
+
+  const heading =
+    headingProp ??
+    (label
+      ? `${label}${gender && GENDERS[gender] ? ` (${GENDERS[gender]})` : ''}`
+      : formatIndicatorName(indicator ?? ''));
+
+  /* Exports every page, not the one on screen: the DOM only holds the current
+     page once paginated, so a scrape would silently export 50 of 2,000. */
+  const exportCsv = async () => {
+    if (!fetchAll) {
+      return;
+    }
+
+    setIsExporting(true);
+
+    try {
+      const all = await fetchAll();
+      const slug = [title, label ?? indicator, startDate, endDate]
+        .filter(Boolean)
+        .join('-')
+        .replace(/[^a-z0-9]+/gi, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase();
+
+      downloadCsv(columns ? columnsToCsv(all, columns, { subHeaderRow: subHeaders }) : rowsToCsv(all), `${slug}.csv`);
+    } catch (error) {
+      showReportError('the register export', error);
+    } finally {
+      setIsExporting(false);
+    }
+  };
+
+  const canExport = !isLoading && !isEmpty;
+  const pageSizeOrDefault = pageSize ?? 50;
+
+  const period =
+    startDate && endDate
+      ? `${formatDate(new Date(startDate), { mode: 'standard', time: false, noToday: true })} to ${formatDate(
+          new Date(endDate),
+          { mode: 'standard', time: false, noToday: true },
+        )}`
+      : null;
+
+  return (
+    <div className={styles.register}>
+      {onBack ? (
+        <div className={styles.breadcrumb}>
+          <Button kind="ghost" size="sm" renderIcon={ArrowLeft} onClick={onBack} className={styles.back}>
+            {parent.label}
+          </Button>
+          <h3 className={styles.title}>{heading || title}</h3>
+        </div>
+      ) : (
+        <Breadcrumb noTrailingSlash className={styles.breadcrumb}>
+          <BreadcrumbItem>
+            <Link to="/">All reports</Link>
+          </BreadcrumbItem>
+          <BreadcrumbItem>
+            <Link to={parentLink}>{parent.label}</Link>
+          </BreadcrumbItem>
+          <BreadcrumbItem isCurrentPage>
+            <h3 className={styles.title}>{heading || title}</h3>
+          </BreadcrumbItem>
+        </Breadcrumb>
+      )}
+
+      {/* Register, period and the export sit on one line: they all describe the
+          table below, and splitting them stacked two sparse rows above it. */}
+      {(indicator || period || canExport) && (
+        <div className={styles.context}>
+          {/* Register and period read as one caption for the table, so they
+              share a panel rather than sitting as two loose fragments. */}
+          <span className={styles.summary}>
+            <span className={styles.summaryTitle}>{title}</span>
+            <span className={styles.period}>
+              {period && (
+                <>
+                  <Calendar size={14} />
+                  {period}
+                </>
+              )}
+              {location && (
+                <span className={styles.location}>
+                  <Location size={14} />
+                  {location}
+                </span>
+              )}
+              {typeof total === 'number' && total > 0 && (
+                <span>{isTotalExact ? `${total.toLocaleString()} patients` : `${total.toLocaleString()}+ patients`}</span>
+              )}
+            </span>
+          </span>
+          {canExport && fetchAll && (
+            <Button
+              kind="tertiary"
+              size="sm"
+              renderIcon={Download}
+              onClick={exportCsv}
+              disabled={isExporting}
+              className={styles.export}
+            >
+              {isExporting ? 'Preparing…' : 'Export CSV'}
+            </Button>
+          )}
+        </div>
+      )}
+
+      {isLoading && <RegisterSkeleton />}
+
+      {!isLoading && isEmpty && (
+        <Layer className={styles.empty}>
+          <Document size={32} className={styles.emptyIcon} />
+          <h4>No records to list</h4>
+          <p>No clients matched this indicator for the selected period and facility.</p>
+        </Layer>
+      )}
+
+      {canExport && (
+        <>
+          <div className={styles.tableScroll}>{children}</div>
+          {onPageChange && typeof total === 'number' && total > pageSizeOrDefault && (
+            <Pagination
+              className={styles.pagination}
+              page={page}
+              pageSize={pageSizeOrDefault}
+              pageSizes={[25, 50, 100, 200]}
+              totalItems={total}
+              size="sm"
+              onChange={onPageChange}
+            />
+          )}
+        </>
+      )}
+    </div>
+  );
+};
+
+export default RegisterLayout;

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

@@ -0,0 +1,150 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.register {
+  padding: layout.$spacing-05 0 layout.$spacing-07;
+}
+
+.breadcrumb {
+  margin-bottom: layout.$spacing-05;
+
+  :global(.cds--breadcrumb-item) {
+    display: inline-flex;
+    align-items: baseline;
+  }
+}
+
+/* The register name doubles as the page heading, so it stays an `h3` rather
+   than being repeated in a title row of its own. */
+
+.title {
+  @include type.type-style('productive-heading-03');
+  display: inline;
+  color: $color-gray-100;
+}
+
+/* Registers run to dozens of columns, so the table scrolls inside the page
+   instead of pushing the whole layout sideways. */
+
+.tableScroll {
+  overflow-x: auto;
+  padding: layout.$spacing-05;
+  background-color: $ui-02;
+  border: 1px solid $ui-03;
+  border-top: none;
+
+  /* Each register carries its own table margins -- 1rem here, 0.5rem there,
+     0.75rem elsewhere -- which land inside this frame and give every register a
+     different gap to the border. The padding above is the spacing now, so those
+     are levelled out. */
+
+  table,
+  > div {
+    margin: 0;
+  }
+}
+
+
+.empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: layout.$spacing-03;
+  padding: layout.$spacing-07 layout.$spacing-05;
+  text-align: center;
+  background-color: $ui-02;
+  border: 1px solid $ui-03;
+  border-top: none;
+
+  h4 {
+    @include type.type-style('productive-heading-02');
+    color: $color-gray-100;
+  }
+
+  p {
+    @include type.type-style('body-long-01');
+    color: $text-02;
+  }
+}
+
+.emptyIcon {
+  fill: $ui-04;
+}
+
+/* The caption and the table below it are one card: the bar carries the register
+   name, the period it covers and the export, and sits flush on whatever follows
+   -- skeleton, empty state or table -- so the page reads as a single object
+   rather than three stacked fragments. */
+
+.context {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: layout.$spacing-03 layout.$spacing-05;
+  padding: layout.$spacing-04 layout.$spacing-05;
+  background-color: $ui-02;
+  border: 1px solid $ui-03;
+  border-bottom: none;
+}
+
+/* Register name over the period it covers: side by side they made one long
+   line that crowded the action; stacked, the name leads and the period reads
+   as its caption. */
+
+.summary {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-02;
+  min-width: 0;
+}
+
+.summaryTitle {
+  @include type.type-style('body-short-01');
+  font-weight: 600;
+  color: $color-gray-100;
+}
+
+.period {
+  @include type.type-style('label-01');
+  display: inline-flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: layout.$spacing-02;
+  color: $text-02;
+
+  svg {
+    fill: var(--brand-01);
+    transform: translateY(0.125rem);
+  }
+}
+
+/* Location sits after the period as one unit, so on a narrow screen it wraps
+   to its own line whole rather than leaving its pin behind */
+.location {
+  display: inline-flex;
+  align-items: center;
+  gap: layout.$spacing-02;
+  margin-left: layout.$spacing-03;
+}
+
+.export {
+  flex-shrink: 0;
+  margin-left: auto;
+}
+
+/* Sits directly under the table, completing the card */
+
+.pagination {
+  border: 1px solid $ui-03;
+  border-top: none;
+}
+
+/* A register rendered as a view on its report's own route has nowhere to
+   navigate, so the trail is a button and the register name beside it. */
+
+.back {
+  padding-inline: 0.25rem;
+  min-block-size: auto;
+}

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,29 @@
+/**
+ * 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> = {
+  'acf-summary': { label: 'ACF Facility Summary Tool', path: '/acf-summary' },
+  '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-729b': { label: 'MOH 729B F-MAPS Report', path: '/moh-729b' },
+  '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(', ');
+}