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

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

@@ -1,49 +1,281 @@
+@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;
 }
 
-.dateContainer label {
-  font-weight: 500;
+/* 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;
 }
 
-.input {
+.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;
+}
+
+/* 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%;
+}
+
+/* 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%;
-  padding: 6px 8px;
-  box-sizing: border-box;
-  border: 1px solid #ccc;
-  outline: none;
+
+  :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;
+  }
 }
-.input:focus {
-  border-color: #999; 
+
+/* 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. A quiet note rather than
+   a banner, in smaller italic type: nothing is wrong, the figures are simply
+   for another period. Warning-toned rather than error-toned. */
+
+.summaryStale {
+  @include type.type-style('label-01');
+  align-items: center;
+  font-style: italic;
+  color: $text-02;
+
+  svg {
+    width: 0.875rem;
+    height: 0.875rem;
+    margin-top: 0;
+    fill: #b28600; // Carbon yellow 50: the warning hue, legible on white
+  }
+
+  strong {
+    font-weight: 600;
+  }
+}
+
+/* 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,79 @@
+/**
+ * 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;
+  /**
+   * Saves the report as a PDF file. Without it, Download PDF opens the
+   * browser's print dialog on the report's print layout.
+   */
+  onDownloadPdf?: () => Promise<void>;
+  /**
+   * The period type a `both` filter bar opens on when the URL carries no
+   * period: `monthly` (last month, the reports' default) or `custom` (today to
+   * today, the registers' default).
+   */
+  defaultTab?: 'monthly' | 'custom';
+  /** Where the breadcrumb leads back to; defaults to All reports on the landing page */
+  backLink?: { label: string; to: string };
+}

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