@ampath/esm-reports-app 1.0.0-next.41 → 1.0.0-next.45

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

@@ -1,91 +1,216 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
 
+.filters {
+  padding: layout.$spacing-05 0 0;
+}
 
-.filtersContainer {
-    margin: 0 2rem;
-    margin-bottom: 0.5rem;
-    border: 1px solid #ccc;
-    padding: 1rem;
+/* Breadcrumb trail. The trailing crumb is the page heading, so the items are
+   baseline-aligned rather than centred on differing font sizes. */
+
+.breadcrumb {
+  margin-bottom: layout.$spacing-04;
+
+  :global(.cds--breadcrumb-item) {
+    display: inline-flex;
+    align-items: baseline;
+  }
 }
 
+/* An `h3` inside the trailing crumb, so it keeps heading semantics without
+   repeating the report name in a separate title row. */
 .title {
-    font-size: 1.5rem;
-    font-weight: bold;
-    margin-top: 1rem;
-    color: green;
-    text-decoration: underline;
+  @include type.type-style('productive-heading-03');
+  display: inline;
+  color: $color-gray-100;
 }
 
-.titleContainer {
-    margin: 2rem;
+/* Filter card */
+
+.filtersContainer {
+  padding: layout.$spacing-04 layout.$spacing-05;
+  background-color: $ui-02;
+  border: 1px solid $ui-03;
+  border-left: layout.$spacing-02 solid var(--brand-01);
 }
 
-.dateContainer {
-  display: grid;
-  grid-template-columns: 1fr 1fr; 
-  gap: 8px 16px;
-  align-items: center;
+.fields {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  gap: layout.$spacing-05;
+  margin-bottom: layout.$spacing-04;
+}
+
+/* Nested so it beats the `flex: 0 1 auto` that Carbon puts on `.cds--form-item`.
+
+   Fields grow into the row but stop at a width suited to what they hold. Left
+   to share the row unbounded, a monthly report -- which shows only Year and
+   Month -- gave a four-digit year a 434px box and the month 650px. The cap
+   keeps every control a sensible size and leaves the slack at the end of the
+   row rather than inside the inputs. */
+
+.fields .field {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.fields .periodField {
+  min-width: 14rem;
+  max-width: 16rem;
+}
+
+/* Wide enough for the validation message, not just the value. Carbon renders
+   `invalidText` under the input at the field's own width, so a field sized to
+   "2026" or "September" makes "That month has not started yet." wrap onto a
+   second line and jog the row below it. */
+
+.fields .yearField {
+  min-width: 7rem;
+  max-width: 9rem;
+}
+
+.fields .monthField {
+  min-width: 9rem;
+  max-width: 13rem;
+}
+
+/* The range picker holds two inputs, so it is allowed roughly twice the width */
+.fields .rangeField {
+  min-width: 16rem;
+  max-width: 24rem;
 }
 
-.dateContainer label {
-  font-weight: 500;
+/* Matches Carbon's `.cds--label` so the switcher's label sits on the same
+   baseline as the labels Carbon renders for the selects. */
+.fieldLabel {
+  @include type.type-style('label-01');
+  display: inline-block;
+  color: $text-02;
+  line-height: 1rem;
+  margin-bottom: layout.$spacing-03;
+  vertical-align: baseline;
 }
 
-.input {
+/* Carbon sizes these to their content, so they need telling to fill the field */
+
+.switcher,
+.fields .field :global(.cds--select-input) {
   width: 100%;
-  padding: 6px 8px;
-  box-sizing: border-box;
-  border: 1px solid #ccc;
-  outline: none;
 }
-.input:focus {
-  border-color: #999; 
+
+.datePicker {
+  display: flex;
+  gap: layout.$spacing-05;
+  width: 100%;
 }
 
-.buttonContainer {
-    display: flex;
-    justify-content: flex-end;
-    gap: 10px;
-    margin: 0 2rem;
+/* Carbon pins `inline-size: 143.5px` on both the container and the input in
+   range mode. Overridden through the range class so this wins on specificity
+   rather than on stylesheet order. */
+.fields .datePicker:global(.cds--date-picker--range) {
+  :global(.cds--date-picker-container) {
+    flex: 1 1 0;
+    inline-size: auto;
+    min-inline-size: 0;
+  }
+
+  :global(.cds--date-picker__input) {
+    inline-size: 100%;
+    min-inline-size: 0;
+  }
 }
 
-.tabsContainer {
+/* Action row */
+
+.actions {
   display: flex;
-  gap: 1rem;
-  margin-bottom: 1rem;
   align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: layout.$spacing-04;
+  padding-top: layout.$spacing-04;
+  border-top: 1px solid $ui-03;
 }
 
-.tab,
-.activeTab {
-  display: flex;
+.summary {
+  @include type.type-style('body-short-01');
+  display: inline-flex;
   align-items: center;
-  justify-content: center;
-  min-height: 2.5rem;
+  gap: layout.$spacing-03;
+  color: $text-02;
+
+  svg {
+    fill: var(--brand-01);
+  }
+
+  strong {
+    color: $color-gray-100;
+    font-weight: 600;
+  }
 }
 
-.tab {
+.actionButtons {
   display: flex;
   align-items: center;
-  justify-content: center;
+  gap: layout.$spacing-03;
+  margin-left: auto;
+}
 
-  min-height: 2.5rem;
+/* The filter bar is application chrome, not part of the report */
 
-  background: transparent;
-  color: green;
+@media print {
+  .filters {
+    display: none;
+  }
+}
 
-  border: 1px solid black; 
-  cursor: pointer;
+@media (max-width: $breakpoint-tablet-max) {
+  .filters {
+    padding: layout.$spacing-05 0 0;
+  }
+
+  .fields,
+  .datePicker {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .fields .field,
+  .switcher {
+    min-width: 0;
+    width: 100%;
+  }
+
+  .actionButtons {
+    margin-left: 0;
+    width: 100%;
+
+    button {
+      flex: 1 1 0;
+    }
+  }
 }
 
-.activeTab {
-  display: flex;
-  align-items: center;
-  justify-content: center;
+/* The summary doubles as the blocking reason when the period is not valid */
+.summaryInvalid {
+  color: $danger;
+
+  svg {
+    fill: $danger;
+  }
+}
 
-  min-height: 2.5rem;
+/* The filters no longer match the report on screen. Warning-toned rather than
+   error-toned: nothing is wrong, the figures are simply for another period. */
 
-  background: green;
-  color: white;
+.summaryStale {
+  padding: layout.$spacing-02 layout.$spacing-03;
+  color: $color-gray-100;
+  background-color: $warning-background;
 
-  border: 1px solid black;
-}
+  svg {
+    fill: $color-gray-70;
+  }
+}

package/src/common/report-filters/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Which period controls a report offers.
+ *
+ * `monthly` suits returns that are only ever compiled for a calendar month --
+ * offering a date range there invites a period the return is not defined for.
+ * `range` suits reports read over arbitrary dates. `both` lets the user choose.
+ */
+export type ReportFilterMode =
+  | 'monthly' // year and month only
+  | 'range' // start and end date only
+  | 'both'; // a switcher between the two
+
+export interface FacilityOption {
+  value: string;
+  label: string;
+}
+
+/**
+ * What the filter bar hands back when the user generates a report.
+ *
+ * `startDate` and `endDate` are always resolved to `YYYY-MM-DD`, whichever way
+ * the period was picked, so a report never has to expand a month into a range
+ * itself.
+ */
+export interface ReportPeriod {
+  startDate: string;
+  endDate: string;
+  /** Set only when the user picked a whole month, as `YYYY-MM` */
+  month?: string;
+  /** Set only when the caller supplied `facilities` */
+  facility?: string;
+  /** Human readable period, e.g. `June 2026` or `01 Jun 2026 to 14 Jun 2026` */
+  label: string;
+}
+
+export interface ReportFiltersProps {
+  /** Shown as the page title, e.g. `MOH-731 Report` */
+  reportName: string;
+  /** Defaults to `both`. See {@link ReportFilterMode}. */
+  mode?: ReportFilterMode;
+  /** Renders a facility picker when supplied. Omit to hide it. */
+  facilities?: FacilityOption[];
+  /** How many years the year dropdown offers, counting back from now */
+  yearsBack?: number;
+  /** Disables the generate button and shows a pending label */
+  isLoading?: boolean;
+  /** Reveals the Download PDF button beside Generate once a report is on screen */
+  isReportGenerated?: boolean;
+  /**
+   * The period the report currently on screen was generated for.
+   *
+   * Reports that restore their data from session storage come back with a
+   * report showing but no record here of which period produced it. Passing it
+   * lets the filter bar flag stale figures on the first change after a reload,
+   * rather than only after the user has generated once in this session.
+   */
+  generatedPeriod?: { startDate?: string; endDate?: string };
+  onGenerate: (period: ReportPeriod) => void;
+  /**
+   * Fires whenever the selected period changes, before Generate is pressed.
+   *
+   * Lets a report show the period on its form as soon as it is chosen, rather
+   * than only once figures have been fetched for it.
+   */
+  onPeriodChange?: (period: ReportPeriod) => void;
+}

package/src/common/report-filters/use-restore-period.ts

@@ -0,0 +1,43 @@
+import { useEffect, useRef } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+import { describePeriod } from './date-range';
+import { type ReportPeriod } from './types';
+
+/**
+ * Regenerates a report when its URL carries a period.
+ *
+ * A register's breadcrumb links back to the report the figure came from, and
+ * carries the period it was generated for. Without this the user lands on the
+ * report's "not generated yet" placeholder and has to pick the same month
+ * again -- the trail leads back to the page but not to what was on it.
+ *
+ * Reports that keep their figures in session storage restore themselves
+ * already; this is for the ones that do not.
+ */
+export function useRestorePeriod(onRestore: (period: ReportPeriod) => void) {
+  const [searchParams] = useSearchParams();
+
+  const startDate = searchParams.get('startDate');
+  const endDate = searchParams.get('endDate');
+  const month = searchParams.get('month') ?? undefined;
+
+  /* Keyed on the period rather than a bare "has run" flag, so following a
+     second register back to a different month still regenerates. */
+  const restored = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!startDate || !endDate) {
+      return;
+    }
+
+    const key = `${startDate}|${endDate}`;
+
+    if (restored.current === key) {
+      return;
+    }
+
+    restored.current = key;
+    onRestore({ startDate, endDate, month, label: describePeriod(startDate, endDate, month) });
+  }, [startDate, endDate, month, onRestore]);
+}

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

@@ -0,0 +1,2 @@
+export { default as ReportPage } from './report-page.component';
+export * from './use-page-scale';

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

@@ -0,0 +1,32 @@
+import React from 'react';
+
+import { usePageScale } from './use-page-scale';
+import styles from './report-page.scss';
+
+interface ReportPageProps {
+  children: React.ReactNode;
+}
+
+/**
+ * An A4 sheet that fills the width it is given.
+ *
+ * Reports that mirror a paper return are drawn at true A4 so they print 1:1,
+ * but a fixed page wastes most of a wide monitor. The sheet is scaled up to
+ * fill its container and floored at A4, below which the viewport scrolls
+ * instead -- shrinking a dense return past its paper size makes it unreadable.
+ */
+const ReportPage: React.FC<ReportPageProps> = ({ children }) => {
+  const { ref, scale } = usePageScale<HTMLDivElement>();
+
+  return (
+    <div className={styles.viewport} ref={ref}>
+      {/* a custom property rather than an inline `zoom`, so the print
+          stylesheet can still reset it to 1 */}
+      <div className={styles.sheet} style={{ '--page-zoom': scale } as React.CSSProperties}>
+        {children}
+      </div>
+    </div>
+  );
+};
+
+export default ReportPage;

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

@@ -0,0 +1,45 @@
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+/* A4 portrait, in the units the paper is measured in, so the sheet occupies
+   exactly one page on screen and prints at 1:1. */
+
+$page-w: 210mm;
+$page-h: 297mm;
+$page-margin: 10mm;
+
+.viewport {
+  overflow-x: auto;
+}
+
+.sheet {
+  box-sizing: border-box;
+  width: $page-w;
+  min-height: $page-h;
+  padding: $page-margin;
+  margin: 0 auto;
+  background-color: #fff;
+  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.18);
+  /* set by `usePageScale` from the measured container width, floored at 1 */
+  zoom: var(--page-zoom, 1);
+}
+
+@media print {
+  @page {
+    size: A4 portrait;
+    margin: $page-margin;
+  }
+
+  .viewport {
+    overflow: visible;
+  }
+
+  .sheet {
+    width: auto;
+    min-height: 0;
+    padding: 0;
+    margin: 0;
+    box-shadow: none;
+    /* paper geometry stands on its own; magnification is for screens */
+    zoom: 1;
+  }
+}

package/src/common/report-page/use-page-scale.ts

@@ -0,0 +1,50 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/** A4 portrait width, 210mm, in CSS pixels at the reference 96dpi */
+const A4_WIDTH_PX = (210 * 96) / 25.4;
+
+/**
+ * Scales the sheet to fill whatever width it is given, never going below A4.
+ *
+ * The report is drawn at true A4 so it prints at 1:1, but a fixed page wastes
+ * most of a wide monitor and is hard to read. This measures the containing
+ * element and returns the factor that makes the page fill it, floored at 1 so
+ * the sheet is never rendered smaller than the paper it represents -- below
+ * that width the container scrolls instead, which keeps the form legible rather
+ * than shrinking it into illegibility.
+ *
+ * A callback ref rather than `useRef` + `useEffect`, because the page it
+ * measures only mounts once a report has been generated: a mount effect would
+ * run while the placeholder is still showing, find nothing to measure, and
+ * never run again -- leaving the generated sheet stuck at A4.
+ *
+ * Returned as a factor for `zoom`, which scales the layout box as well as the
+ * paint, so the scroll container stays the right size around the page.
+ */
+export function usePageScale<T extends HTMLElement>() {
+  const [scale, setScale] = useState(1);
+  const observer = useRef<ResizeObserver | null>(null);
+
+  const ref = useCallback((node: T | null) => {
+    observer.current?.disconnect();
+
+    if (!node) {
+      return;
+    }
+
+    const measure = () => {
+      // clientWidth excludes the scrollbar, so the page cannot chase a
+      // scrollbar it has just caused
+      setScale(Math.max(1, node.clientWidth / A4_WIDTH_PX));
+    };
+
+    measure();
+
+    observer.current = new ResizeObserver(measure);
+    observer.current.observe(node);
+  }, []);
+
+  useEffect(() => () => observer.current?.disconnect(), []);
+
+  return { ref, scale };
+}

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,2 @@
+export { default as ReportPlaceholder } from './report-placeholder.component';
+export * from './has-report-data';

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

@@ -0,0 +1,56 @@
+import React from 'react';
+import { Layer } from '@carbon/react';
+import { Report } from '@carbon/react/icons';
+
+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;
+}
+
+/**
+ * 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 }) => (
+  <Layer className={styles.placeholder}>
+    <Report size={32} className={styles.icon} />
+
+    {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,46 @@
+@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;
+  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-register/index.ts

@@ -0,0 +1,5 @@
+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';

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

@@ -0,0 +1,34 @@
+/** 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;
+}
+
+/** 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) : '',
+    })),
+  );
+}