@ampath/esm-reports-app 1.0.0-next.6 → 1.0.0-next.61

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

@@ -1,49 +1,272 @@
+@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;
 }
 
-.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;
 }
 
-.dateContainer label {
-  font-weight: 500;
+.fields .monthField {
+  min-width: 9rem;
+  max-width: 13rem;
 }
 
-.input {
+/* The range picker holds two inputs, so it is allowed roughly twice the width */
+.fields .rangeField {
+  min-width: 16rem;
+  max-width: 24rem;
+}
+
+/* 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;
+}
+
+/* Carbon sizes these to their content, so they need telling to fill the field */
+
+.switcher,
+.fields .field :global(.cds--select-input) {
+  width: 100%;
+}
+
+.datePicker {
+  display: flex;
+  gap: layout.$spacing-05;
   width: 100%;
-  padding: 6px 8px;
-  box-sizing: border-box;
-  border: 1px solid #ccc;
-  outline: none;
 }
-.input:focus {
-  border-color: #999; 
+
+/* Carbon pins `inline-size: 143.5px` on both the container and the input in
+   range mode, so the two dates never fill the field. `.datePicker` lands on
+   the form-item wrapper, not on the range element itself, so the range is
+   matched as its descendant. */
+.fields .datePicker :global(.cds--date-picker--range) {
+  gap: layout.$spacing-05;
+  width: 100%;
+
+  :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;
+  }
+}
+
+/* Action row */
+
+.actions {
+  display: flex;
+  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;
 }
 
-.buttonContainer {
-    display: flex;
-    justify-content: flex-end;
-    gap: 10px;
-    margin: 0 2rem;
-}
+.summary {
+  @include type.type-style('body-short-01');
+  display: flex;
+  flex: 1 1 18rem;
+  align-items: flex-start;
+  gap: layout.$spacing-03;
+  min-width: 0;
+  margin: 0;
+  color: $text-02;
+
+  /* level with the first line however many lines the message wraps to */
+  svg {
+    flex-shrink: 0;
+    margin-top: 0.0625rem;
+    fill: var(--brand-01);
+  }
+
+  /* a period such as "01 Sep 2026 to 30 Sep 2026" never breaks mid-range */
+  strong {
+    color: $color-gray-100;
+    font-weight: 600;
+    white-space: nowrap;
+  }
+}
+
+.actionButtons {
+  display: flex;
+  align-items: center;
+  gap: layout.$spacing-03;
+  margin-left: auto;
+}
+
+/* The filter bar is application chrome, not part of the report */
+
+@media print {
+  .filters {
+    display: none;
+  }
+}
+
+@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;
+    }
+  }
+}
+
+/* The summary doubles as the blocking reason when the period is not valid */
+.summaryInvalid {
+  color: $danger;
+
+  svg {
+    fill: $danger;
+  }
+}
+
+/* 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. */
+
+.summaryStale {
+  padding: layout.$spacing-03 layout.$spacing-04;
+  color: $color-gray-100;
+  background-color: $warning-background;
+
+  svg {
+    fill: $color-gray-70;
+  }
+}
+
+/* Stacked fields fill the card. The desktop caps above (a year box no wider
+   than a year needs) would otherwise leave each stacked field a different,
+   arbitrary width. Placed after them so it wins at equal specificity. */
+@media (max-width: $breakpoint-tablet-max) {
+  .fields .periodField,
+  .fields .yearField,
+  .fields .monthField,
+  .fields .rangeField {
+    max-width: none;
+  }
+
+  /* Carbon caps buttons at 20rem; sharing the row, they should split it */
+  .actionButtons :global(.cds--btn) {
+    max-width: none;
+  }
+}
+
+/* Phones: one column throughout. Side by side, "Download PDF" and "Generate
+   report" each wrapped onto two lines and together overran the card. */
+@media (max-width: $breakpoint-phone-max) {
+  .filtersContainer {
+    padding: layout.$spacing-04;
+  }
+
+  .actions {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  /* Its flex basis is a width on the row; stacked, it would become a height */
+  .summary {
+    flex: none;
+  }
+
+  .actionButtons {
+    flex-direction: column;
+    align-items: stretch;
+
+    :global(.cds--btn) {
+      flex: none;
+      width: 100%;
+    }
+  }
+}

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-header/index.ts

@@ -0,0 +1 @@
+export * from './use-location-details';

package/src/common/report-header/use-location-details.ts

@@ -0,0 +1,58 @@
+import { useEffect, useState } from 'react';
+import { openmrsFetch, useSession } from '@openmrs/esm-framework';
+
+export interface LocationDetails {
+  county?: string;
+  subCounty?: string;
+  /** The location attribute carrying the Kenya Master Health Facility List code */
+  kmhflCode?: string;
+}
+
+/**
+ * The extra masthead facts the MOH forms print but the session object does
+ * not carry: County / Sub-County map to the location's address fields, and
+ * the KMHFL code is whichever location attribute's type names the master
+ * facility list (its exact type name varies by server, so the type is
+ * matched by name). Values stay blank until the location answers.
+ */
+export function useLocationDetails(): LocationDetails {
+  const session = useSession();
+  const locationUuid = session?.sessionLocation?.uuid;
+  const [details, setDetails] = useState<LocationDetails>({});
+
+  useEffect(() => {
+    if (!locationUuid) {
+      return;
+    }
+
+    const abortController = new AbortController();
+
+    openmrsFetch(
+      `/ws/rest/v1/location/${locationUuid}?v=custom:(display,stateProvince,countyDistrict,attributes:(display,attributeType:(display)))`,
+      { signal: abortController.signal },
+    )
+      .then(async (response) => {
+        if (!response.ok) {
+          return;
+        }
+
+        const location = await response.json();
+        const kmhfl = (location?.attributes ?? []).find((attribute: any) =>
+          /kmhfl|mfl|master health facility/i.test(attribute?.attributeType?.display ?? ''),
+        );
+
+        setDetails({
+          county: location?.stateProvince || undefined,
+          subCounty: location?.countyDistrict || undefined,
+          kmhflCode: kmhfl?.display || undefined,
+        });
+      })
+      .catch(() => {
+        /* the header simply keeps its blanks when the lookup fails */
+      });
+
+    return () => abortController.abort();
+  }, [locationUuid]);
+
+  return details;
+}

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,60 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/** A4 portrait width */
+const A4_WIDTH_MM = 210;
+
+/** Millimetres to CSS pixels at the reference 96dpi */
+const mmToPx = (mm: number) => (mm * 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.
+ *
+ * `pageWidthMm` is the width of the sheet as drawn on screen: the full A4 by
+ * default, or less for a sheet drawn without its paper margins (they are added
+ * back only for print).
+ */
+export function usePageScale<T extends HTMLElement>(pageWidthMm = A4_WIDTH_MM) {
+  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 / mmToPx(pageWidthMm)));
+      };
+
+      measure();
+
+      observer.current = new ResizeObserver(measure);
+      observer.current.observe(node);
+    },
+    [pageWidthMm],
+  );
+
+  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,3 @@
+export { default as ReportPlaceholder } from './report-placeholder.component';
+export * from './has-report-data';
+export * from './use-generated-location';