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

package/src/common/report-placeholder/has-report-data.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether a report has been generated and came back with something to show.
+ *
+ * Reports flatten their response with `Object.assign({}, ...data.result)`, but
+ * they initialise that state variously as `{}`, `[]` or a value restored from
+ * sessionStorage, so "has it run yet" is really "does it have any keys". An
+ * empty array has none, which is what makes this work across all of them.
+ */
+export function hasReportData(data: unknown): boolean {
+  if (!data || typeof data !== 'object') {
+    return false;
+  }
+
+  return Object.keys(data).length > 0;
+}

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

@@ -0,0 +1,3 @@
+export { default as ReportPlaceholder } from './report-placeholder.component';
+export * from './has-report-data';
+export * from './use-generated-location';

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

@@ -0,0 +1,81 @@
+import React from 'react';
+import { Layer } from '@carbon/react';
+import { Location, Report } from '@carbon/react/icons';
+import { useSession } from '@openmrs/esm-framework';
+
+import styles from './report-placeholder.scss';
+
+interface ReportPlaceholderProps {
+  /** Named so the guidance says which return is about to be produced */
+  reportName?: string;
+  /** Shown when a report was generated but came back with nothing in it */
+  isEmptyResult?: boolean;
+  /** A report was generated, but for another location than the current one */
+  isLocationChanged?: boolean;
+}
+
+/**
+ * Stands in for the report template until a report has actually been generated,
+ * and explains how to produce one.
+ *
+ * Report templates are large pre-printed MOH forms; rendering one with every
+ * value blank reads as "the facility reported zeroes" rather than "you have not
+ * run this yet", so the template is held back until there is data to put in it.
+ * That leaves the page empty, hence the guidance here.
+ */
+const ReportPlaceholder: React.FC<ReportPlaceholderProps> = ({
+  reportName,
+  isEmptyResult = false,
+  isLocationChanged = false,
+}) => {
+  const session = useSession();
+  const location = session?.sessionLocation?.display;
+
+  return (
+    <Layer className={styles.placeholder}>
+      {isLocationChanged ? (
+        <Location size={32} className={styles.icon} />
+      ) : (
+        <Report size={32} className={styles.icon} />
+      )}
+
+      {isLocationChanged ? (
+        <>
+          <h5>Location changed</h5>
+          <p>
+            The last {reportName ?? 'report'} was generated for a different location, so it is not shown here. Select{' '}
+            <strong>Generate report</strong> to produce it for{' '}
+            {location ? <strong>{location}</strong> : 'this location'}.
+          </p>
+        </>
+      ) : isEmptyResult ? (
+        <>
+          <h5>No records for this period</h5>
+          <p>
+            {reportName ?? 'The report'} ran successfully but returned no data for the period you selected. Try a
+            different reporting period, or confirm that data has been entered for this facility.
+          </p>
+        </>
+      ) : (
+        <>
+          <h5>No report generated yet</h5>
+          <p>
+            {reportName ? `The ${reportName} form` : 'The report'} will appear here, filled in with your
+            facility&rsquo;s figures, once you generate it.
+          </p>
+          <ol className={styles.steps}>
+            <li>Choose the reporting period in the filters above.</li>
+            <li>
+              Select <strong>Generate report</strong>.
+            </li>
+            <li>
+              Use <strong>Download PDF</strong> to save or print the completed form.
+            </li>
+          </ol>
+        </>
+      )}
+    </Layer>
+  );
+};
+
+export default ReportPlaceholder;

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

@@ -0,0 +1,48 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.placeholder {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: layout.$spacing-03;
+  padding: layout.$spacing-07 layout.$spacing-05;
+  /* the same gap below the filter card as a generated report's panel has */
+  margin-top: layout.$spacing-05;
+  margin-bottom: layout.$spacing-05;
+  text-align: center;
+  background-color: $ui-02;
+  border: 1px solid $ui-03;
+
+  h5 {
+    @include type.type-style('productive-heading-02');
+    color: $color-gray-100;
+  }
+
+  p {
+    @include type.type-style('body-long-01');
+    color: $text-02;
+  }
+}
+
+.icon {
+  fill: $ui-04;
+}
+
+/* The steps that produce a report. Left aligned inside the centred card: a
+   numbered sequence is read down its left edge, not from a ragged centre. */
+
+.steps {
+  max-width: 28rem;
+  margin-top: layout.$spacing-03;
+  padding-left: layout.$spacing-06;
+  text-align: left;
+  list-style: decimal;
+
+  li {
+    @include type.type-style('body-long-01');
+    color: $text-02;
+    margin-bottom: layout.$spacing-02;
+  }
+}

package/src/common/report-placeholder/use-generated-location.ts

@@ -0,0 +1,62 @@
+import { useCallback, useState } from 'react';
+import { useSession } from '@openmrs/esm-framework';
+
+function readLocation(storageKey?: string): string {
+  if (!storageKey) {
+    return '';
+  }
+  try {
+    return sessionStorage.getItem(storageKey) ?? '';
+  } catch {
+    return '';
+  }
+}
+
+function writeLocation(storageKey: string | undefined, locationUuid: string) {
+  if (!storageKey) {
+    return;
+  }
+  try {
+    sessionStorage.setItem(storageKey, locationUuid);
+  } catch {
+    /* storage unavailable: the report just won't survive a reload */
+  }
+}
+
+/**
+ * Which location the report on screen was generated for, compared with the
+ * one the user is at now.
+ *
+ * A report's figures belong to the location they were fetched for, but its
+ * masthead names the session location. After switching location, the old
+ * figures would be shown -- and labelled -- as the new location's. So a report
+ * only counts as generated while it is for the current location; otherwise the
+ * page falls back to the placeholder and asks for it to be generated again.
+ *
+ * Reports that keep their figures in session storage pass `storageKey`, so the
+ * location is restored alongside them. Figures restored without a location
+ * (saved before this was recorded) are treated as not generated, rather than
+ * assumed to be for wherever the user happens to be.
+ */
+export function useGeneratedLocation(storageKey?: string) {
+  const session = useSession();
+  const currentLocation = session?.sessionLocation?.uuid ?? '';
+  const [generatedLocation, setGeneratedLocation] = useState(() => readLocation(storageKey));
+
+  /** Call once a report has been fetched, with the location it was fetched for */
+  const markGenerated = useCallback(
+    (locationUuid: string) => {
+      setGeneratedLocation(locationUuid);
+      writeLocation(storageKey, locationUuid);
+    },
+    [storageKey],
+  );
+
+  return {
+    /** The report held is for the location the user is at now */
+    isForCurrentLocation: Boolean(generatedLocation) && generatedLocation === currentLocation,
+    /** A report is held, but for a different location than the current one */
+    hasLocationChanged: Boolean(generatedLocation) && generatedLocation !== currentLocation,
+    markGenerated,
+  };
+}

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

@@ -0,0 +1,6 @@
+export { default as RegisterLayout } from './register-layout.component';
+export * from './register-columns';
+export * from './report-parents';
+export * from './rows-to-csv';
+export * from './use-patient-list';
+export * from './use-location-name';

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

@@ -0,0 +1,46 @@
+/** One exported column: the heading it carries on the register, and its value */
+export interface RegisterColumn {
+  header: string;
+  value: (row: Record<string, any>, index: number) => unknown;
+  /**
+   * Keep the cell as text in the CSV so Excel never reinterprets it:
+   * identifiers lose leading zeros and phone numbers become `#NAME?`
+   * formulas when the spreadsheet parses them as numbers.
+   */
+  text?: boolean;
+  /**
+   * Allow the cell to wrap on screen. Registers keep their columns
+   * `nowrap` so short cells stay compact; prose columns (diagnoses,
+   * referrals, comments) would otherwise stretch the whole row wide.
+   */
+  wrap?: boolean;
+}
+
+/** The age bands the registers tabulate against, in the order they appear */
+export const AGE_BANDS = [
+  { label: '< 1 yrs', min: 0, max: 0 },
+  { label: '1-4 yrs', min: 1, max: 4 },
+  { label: '5-9 yrs', min: 5, max: 9 },
+  { label: '10-14 yrs', min: 10, max: 14 },
+  { label: '15-19 yrs', min: 15, max: 19 },
+  { label: '20-24 yrs', min: 20, max: 24 },
+  { label: '25+ yrs', min: 25, max: Number.POSITIVE_INFINITY },
+] as const;
+
+/**
+ * Expands one indicator into the fourteen age-band by gender columns the
+ * register prints for it.
+ *
+ * The registers spell these out as fourteen near-identical cells; describing
+ * the rule once keeps the export in step with the table without restating it
+ * fourteen times per block.
+ */
+export function ageBandColumns(heading: string, value: (row: Record<string, any>) => unknown): RegisterColumn[] {
+  return AGE_BANDS.flatMap((band) =>
+    (['M', 'F'] as const).map((gender) => ({
+      header: `${heading} ${band.label} (${gender})`,
+      value: (row: Record<string, any>) =>
+        row.age >= band.min && row.age <= band.max && row.gender === gender ? value(row) : '',
+    })),
+  );
+}

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;
+}