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

package/src/common/report-filters/date-range.ts

@@ -0,0 +1,137 @@
+import dayjs from 'dayjs';
+
+/** The wire format every report resource expects for dates */
+export const DATE_FORMAT = 'YYYY-MM-DD';
+
+/** The format the month dropdown round-trips through */
+export const MONTH_FORMAT = 'YYYY-MM';
+
+export function formatDate(date: dayjs.ConfigType): string {
+  return dayjs(date).format(DATE_FORMAT);
+}
+
+export function formatMonth(date: dayjs.ConfigType): string {
+  return dayjs(date).format(MONTH_FORMAT);
+}
+
+/**
+ * Expands `YYYY-MM` into the first and last day of that month.
+ *
+ * Parsed in local time on purpose: reporting periods are calendar months at the
+ * facility, so a UTC parse would shift the boundaries for facilities east of
+ * Greenwich and pull a day of data in from the neighbouring month.
+ */
+export function monthToDateRange(month: string): { startDate: string; endDate: string } {
+  const start = dayjs(`${month}-01`).startOf('month');
+
+  return {
+    startDate: start.format(DATE_FORMAT),
+    endDate: start.endOf('month').format(DATE_FORMAT),
+  };
+}
+
+export function describePeriod(startDate: string, endDate: string, month?: string): string {
+  if (month) {
+    return dayjs(`${month}-01`).format('MMMM YYYY');
+  }
+
+  return `${dayjs(startDate).format('DD MMM YYYY')} to ${dayjs(endDate).format('DD MMM YYYY')}`;
+}
+
+/** The raw field values the user has entered, before they resolve to a period */
+export interface PeriodDraft {
+  /** `true` for the Custom range tab and for daily mode, `false` for Monthly */
+  usesDateRange: boolean;
+  /** `YYYY`, Monthly only */
+  year?: string;
+  /** `MM`, Monthly only */
+  month?: string;
+  /** `YYYY-MM-DD`, Custom range only */
+  startDate?: string;
+  /** `YYYY-MM-DD`, Custom range only */
+  endDate?: string;
+}
+
+/** Messages keyed by the field they belong against, so each shows its own */
+export interface PeriodErrors {
+  year?: string;
+  month?: string;
+  startDate?: string;
+  endDate?: string;
+}
+
+/** Order the fields appear in, so the summary quotes the first thing to fix */
+const FIELD_ORDER: Array<keyof PeriodErrors> = ['year', 'month', 'startDate', 'endDate'];
+
+export function firstError(errors: PeriodErrors): string | undefined {
+  return FIELD_ORDER.map((field) => errors[field]).find(Boolean);
+}
+
+/**
+ * Validates whichever period the active tab is collecting.
+ *
+ * Each tab has its own failure modes and each message is attached to the field
+ * that caused it, so nothing is reported against a control the user cannot see
+ * on the tab they are on.
+ *
+ * The Monthly tab needs the future check in particular: the date picker
+ * enforces `maxDate` itself, but Year and Month are independent dropdowns, so a
+ * later month in the current year yields a period that has not happened yet.
+ */
+export function validatePeriod({ usesDateRange, year, month, startDate, endDate }: PeriodDraft): PeriodErrors {
+  const errors: PeriodErrors = {};
+  const today = dayjs();
+
+  if (usesDateRange) {
+    const start = dayjs(startDate);
+    const end = dayjs(endDate);
+    const hasStart = Boolean(startDate) && start.isValid();
+    const hasEnd = Boolean(endDate) && end.isValid();
+
+    if (!hasStart) {
+      errors.startDate = 'Enter a start date as dd/mm/yyyy.';
+    }
+
+    if (!hasEnd) {
+      errors.endDate = 'Enter an end date as dd/mm/yyyy.';
+    }
+
+    if (hasStart && hasEnd && start.isAfter(end, 'day')) {
+      errors.startDate = 'The start date must be on or before the end date.';
+    }
+
+    if (hasStart && !errors.startDate && start.isAfter(today, 'day')) {
+      errors.startDate = 'The start date cannot be in the future.';
+    }
+
+    if (hasEnd && end.isAfter(today, 'day')) {
+      errors.endDate = 'The end date cannot be in the future.';
+    }
+
+    return errors;
+  }
+
+  if (!year) {
+    errors.year = 'Choose a year.';
+  }
+
+  if (!month) {
+    errors.month = 'Choose a month.';
+  }
+
+  if (year && month) {
+    // dayjs rolls an out-of-range month over into the next year rather than
+    // reporting it invalid, so `2026-13` would read as a future date instead of
+    // a malformed one. Check the parts before trusting the parse.
+    const monthNumber = Number(month);
+    const isWellFormed = /^\d{4}$/.test(year) && Number.isInteger(monthNumber) && monthNumber >= 1 && monthNumber <= 12;
+
+    if (!isWellFormed) {
+      errors.month = 'That is not a valid month.';
+    } else if (dayjs(`${year}-${month}-01`).isAfter(today, 'month')) {
+      errors.month = 'That month has not started yet.';
+    }
+  }
+
+  return errors;
+}

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

@@ -0,0 +1,4 @@
+export { default as ReportFiltersComponent } from './report-filters.component';
+export * from './date-range';
+export * from './types';
+export * from './use-restore-period';

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

@@ -1,124 +1,342 @@
-import { ArrowLeft } from '@carbon/react/icons';
-import { useNavigate } from 'react-router-dom';
 import React from 'react';
-import { Button } from '@carbon/react';
+import { Link, useSearchParams } from 'react-router-dom';
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  Button,
+  ContentSwitcher,
+  DatePicker,
+  DatePickerInput,
+  Layer,
+  Select,
+  SelectItem,
+  Switch,
+} from '@carbon/react';
+import { Calendar, ChartColumn, Download, WarningAlt } from '@carbon/react/icons';
+import classNames from 'classnames';
+import dayjs from 'dayjs';
 
+import {
+  DATE_FORMAT,
+  describePeriod,
+  firstError,
+  formatDate,
+  formatMonth,
+  monthToDateRange,
+  validatePeriod,
+} from './date-range';
+import { showReportError } from '../report-error';
+import { type ReportFiltersProps } from './types';
 import styles from './report-filters.scss';
 
-interface ReportFiltersComponentProps {
-  reportName: string;
-  mode?: 'monthly' | 'daily';
-  isFacility?: false | 'true';
-  onGenerate?: (filters: { startDate?: string; endDate?: string; month?: string }) => void;
-  isLoding?: boolean;
-}
-const ReportFiltersComponent: React.FC<ReportFiltersComponentProps> = ({
+const months = Array.from({ length: 12 }, (_, index) => ({
+  value: String(index + 1).padStart(2, '0'),
+  label: dayjs().month(index).format('MMMM'),
+}));
+
+const ReportFiltersComponent: React.FC<ReportFiltersProps> = ({
   reportName,
-  mode = 'daily',
-  isFacility,
+  mode = 'both',
+  facilities,
+  yearsBack = 6,
+  isLoading = false,
+  isReportGenerated = false,
+  generatedPeriod,
   onGenerate,
-  isLoding = false,
+  onPeriodChange,
+  onDownloadPdf,
+  backLink = { label: 'All reports', to: '/' },
+  defaultTab = 'monthly',
 }) => {
-  const navigate = useNavigate();
+  /* A register's breadcrumb links back here carrying the period the report was
+     generated for. Seeding the controls from it matters as much as restoring
+     the figures: left on their defaults the bar would compare last month
+     against the restored period and warn that figures are stale on arrival. */
+  const [params] = useSearchParams();
+  const urlStart = params.get('startDate');
+  const urlEnd = params.get('endDate');
+  const urlMonth = params.get('month');
+
+  /* A period covering exactly one calendar month came from the Monthly tab,
+     however it is spelled in the URL. */
+  const urlWholeMonth =
+    urlMonth ??
+    (urlStart &&
+    urlEnd &&
+    dayjs(urlStart).isSame(dayjs(urlStart).startOf('month'), 'day') &&
+    dayjs(urlEnd).isSame(dayjs(urlStart).endOf('month'), 'day')
+      ? dayjs(urlStart).format('YYYY-MM')
+      : null);
+
+  /* a period in the URL decides; otherwise the report's own default */
+  const [activeTab, setActiveTab] = React.useState<'monthly' | 'custom'>(
+    urlStart && urlEnd ? (urlWholeMonth ? 'monthly' : 'custom') : defaultTab,
+  );
+
+  const [startDateString, setStartDateString] = React.useState<string>(() => urlStart ?? formatDate(new Date()));
+  const [endDateString, setEndDateString] = React.useState<string>(() => urlEnd ?? formatDate(new Date()));
+  const [monthString, setMonthString] = React.useState<string>(
+    () => urlWholeMonth ?? formatMonth(dayjs().subtract(1, 'month')),
+  );
+
+  const [selectedFacility, setSelectedFacility] = React.useState<string>('');
+
+  const [selectedYear, selectedMonth] = monthString.split('-');
+
+  /** Recomputed per render so a session open across New Year still offers this year */
+  const years = React.useMemo(
+    () => Array.from({ length: yearsBack }, (_, index) => String(dayjs().year() - index)),
+    [yearsBack],
+  );
+
+  const showsSwitcher = mode === 'both';
+  const usesDateRange = mode === 'range' || (showsSwitcher && activeTab === 'custom');
+  const usesMonth = mode === 'monthly' || (showsSwitcher && activeTab === 'monthly');
+
+  const dateRange = React.useMemo(
+    () => [dayjs(startDateString).toDate(), dayjs(endDateString).toDate()],
+    [startDateString, endDateString],
+  );
+
+  const period = React.useMemo(() => {
+    const month = usesDateRange ? undefined : monthString;
+    const { startDate, endDate } = month
+      ? monthToDateRange(month)
+      : { startDate: startDateString, endDate: endDateString };
+
+    return {
+      startDate,
+      endDate,
+      month,
+      facility: facilities ? selectedFacility : undefined,
+      label: describePeriod(startDate, endDate, month),
+    };
+  }, [usesDateRange, monthString, startDateString, endDateString, facilities, selectedFacility]);
+
+  /* What the report currently on screen was generated for, so a change to the
+     filters can be called out rather than silently leaving stale figures up. */
+  const [generatedFor, setGeneratedFor] = React.useState<{ key: string; label: string } | null>(null);
+
+  const errors = React.useMemo(
+    () =>
+      validatePeriod({
+        usesDateRange,
+        year: selectedYear,
+        month: selectedMonth,
+        startDate: startDateString,
+        endDate: endDateString,
+      }),
+    [usesDateRange, selectedYear, selectedMonth, startDateString, endDateString],
+  );
+  const isValid = Object.keys(errors).length === 0;
 
-  const getToday = () => {
-    return new Date().toISOString().split('T')[0];
+  /* Reported on change so a report can label its form with the chosen period
+     before any figures exist for it. */
+  React.useEffect(() => {
+    onPeriodChange?.(period);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [period]);
+
+  const periodKey = `${period.startDate}|${period.endDate}|${period.facility ?? ''}`;
+
+  /* Falls back to the period the caller says is on screen, which is what makes
+     the warning work after a reload rather than only after a generate. */
+  const shownPeriod =
+    generatedFor ??
+    (generatedPeriod?.startDate && generatedPeriod?.endDate
+      ? {
+          key: `${generatedPeriod.startDate}|${generatedPeriod.endDate}|`,
+          label: describePeriod(generatedPeriod.startDate, generatedPeriod.endDate),
+        }
+      : null);
+
+  const [isPreparingPdf, setIsPreparingPdf] = React.useState(false);
+  const downloadPdf = async () => {
+    if (!onDownloadPdf) {
+      window.print();
+      return;
+    }
+    setIsPreparingPdf(true);
+    try {
+      await onDownloadPdf();
+    } catch (error) {
+      showReportError(`the ${reportName} PDF`, error);
+    } finally {
+      setIsPreparingPdf(false);
+    }
   };
 
-  const getPreviousMonth = () => {
-    const date = new Date();
-    date.setMonth(date.getMonth() - 1);
+  const isStale = isReportGenerated && shownPeriod !== null && shownPeriod.key !== periodKey;
 
-    const year = date.getFullYear();
-    const month = String(date.getMonth() + 1).padStart(2, '0');
+  const handleGenerate = () => {
+    if (!isValid) {
+      return;
+    }
 
-    return `${year}-${month}`;
+    setGeneratedFor({ key: periodKey, label: period.label });
+    onGenerate(period);
   };
 
-  const [startDateString, setStartDateString] = React.useState<string>(getToday());
-  const [endDateString, setEndDateString] = React.useState<string>(getToday());
-  const [monthString, setMonthString] = React.useState<string>(getPreviousMonth());
-  const [selectedFacility, setSelectedFacility] = React.useState<string>('');
-  const [facility, setFacility] = React.useState<string>('Select Facility');
-
-  const generateReport = () => {
-    if (onGenerate) {
-      const filters: { startDate?: string; endDate?: string; month?: string } = {};
-      if (mode === 'daily') {
-        filters.startDate = startDateString;
-        filters.endDate = endDateString;
-      } else if (mode === 'monthly') {
-        filters.month = monthString;
-      }
-      onGenerate(filters);
+  /** Only commit a complete range, so re-rendering does not interrupt the second pick */
+  const handleDateRangeChange = (dates: Array<Date>) => {
+    const [start, end] = dates;
+
+    if (start && end) {
+      setStartDateString(dayjs(start).format(DATE_FORMAT));
+      setEndDateString(dayjs(end).format(DATE_FORMAT));
     }
   };
+
+  const dateRangePicker = (
+    <DatePicker
+      datePickerType="range"
+      dateFormat="d/m/Y"
+      maxDate={new Date()}
+      value={dateRange}
+      onChange={handleDateRangeChange}
+      className={styles.datePicker}
+    >
+      <DatePickerInput
+        id="report-start-date"
+        labelText="Start date"
+        placeholder="dd/mm/yyyy"
+        size="sm"
+        invalid={Boolean(errors.startDate)}
+        invalidText={errors.startDate}
+      />
+      <DatePickerInput
+        id="report-end-date"
+        labelText="End date"
+        placeholder="dd/mm/yyyy"
+        size="sm"
+        invalid={Boolean(errors.endDate)}
+        invalidText={errors.endDate}
+      />
+    </DatePicker>
+  );
+
   return (
-    <>
-      <div className={styles.titleContainer}>
-        <ArrowLeft className={styles.backIcon} onClick={() => navigate(-1)} />
-        <h2 className={styles.title}>{reportName}</h2>
-      </div>
-      <div className={styles.filtersContainer}>
-        {mode === 'daily' && (
-          <div className={styles.dateContainer}>
-            <label htmlFor="startingMonth">Start Date:</label>
-            <label htmlFor="endingMonth">End Date:</label>
-
-            <input
-              id="startingMonth"
-              type="date"
-              className={styles.input}
-              value={startDateString}
-              onChange={(e) => setStartDateString(e.target.value)}
-            />
-
-            <input
-              id="endingMonth"
-              type="date"
-              className={styles.input}
-              value={endDateString}
-              onChange={(e) => setEndDateString(e.target.value)}
-            />
-          </div>
-        )}
-        {mode === 'monthly' && (
-          <div>
-            <div>
-              <div>
-                <label htmlFor="month">Month:</label>
-                <input
-                  id="month"
-                  type="month"
-                  className={styles.input}
-                  value={monthString}
-                  onChange={(e) => setMonthString(e.target.value)}
-                />
-              </div>
+    <div className={styles.filters}>
+      <Breadcrumb noTrailingSlash className={styles.breadcrumb}>
+        <BreadcrumbItem>
+          <Link to={backLink.to}>{backLink.label}</Link>
+        </BreadcrumbItem>
+        {/* The report name doubles as the page heading, so it stays an `h3`
+            rather than being repeated in a separate title row. */}
+        <BreadcrumbItem isCurrentPage>
+          <h3 className={styles.title}>{reportName}</h3>
+        </BreadcrumbItem>
+      </Breadcrumb>
+
+      <Layer className={styles.filtersContainer}>
+        <div className={styles.fields}>
+          {showsSwitcher && (
+            <div className={classNames(styles.field, styles.periodField)}>
+              <span className={styles.fieldLabel}>Period type</span>
+              <ContentSwitcher
+                selectedIndex={activeTab === 'monthly' ? 0 : 1}
+                onChange={({ index }) => setActiveTab(index === 0 ? 'monthly' : 'custom')}
+                size="sm"
+                className={styles.switcher}
+              >
+                <Switch name="monthly" text="Monthly" />
+                <Switch name="custom" text="Custom range" />
+              </ContentSwitcher>
             </div>
-            <div className={styles.clearFix}></div>
-          </div>
-        )}
-        {isFacility === 'true' && (
-          <div>
-            <label>Facility</label>
-            <select
-              className={styles.input}
-              name="selectedFacility"
+          )}
+
+          {usesMonth && (
+            <>
+              <Select
+                id="report-year"
+                labelText="Year"
+                size="sm"
+                className={classNames(styles.field, styles.yearField)}
+                invalid={Boolean(errors.year)}
+                invalidText={errors.year}
+                value={selectedYear}
+                onChange={(event) => setMonthString(`${event.target.value}-${selectedMonth}`)}
+              >
+                {years.map((year) => (
+                  <SelectItem key={year} value={year} text={year} />
+                ))}
+              </Select>
+              <Select
+                id="report-month"
+                labelText="Month"
+                size="sm"
+                className={classNames(styles.field, styles.monthField)}
+                invalid={Boolean(errors.month)}
+                invalidText={errors.month}
+                value={selectedMonth}
+                onChange={(event) => setMonthString(`${selectedYear}-${event.target.value}`)}
+              >
+                {months.map((month) => (
+                  <SelectItem key={month.value} value={month.value} text={month.label} />
+                ))}
+              </Select>
+            </>
+          )}
+
+          {usesDateRange && <div className={classNames(styles.field, styles.rangeField)}>{dateRangePicker}</div>}
+
+          {facilities && (
+            <Select
+              id="report-facility"
+              labelText="Facility"
+              size="sm"
+              className={styles.field}
               value={selectedFacility}
-              onChange={(e) => setSelectedFacility(e.target.value)}
+              onChange={(event) => setSelectedFacility(event.target.value)}
             >
-              <option value="">{facility}</option>
-            </select>
+              <SelectItem value="" text="All facilities" />
+              {facilities.map((facility) => (
+                <SelectItem key={facility.value} value={facility.value} text={facility.label} />
+              ))}
+            </Select>
+          )}
+        </div>
+
+        <div className={styles.actions}>
+          {/* Restating a period that cannot be generated reads as if it will be,
+              so the blocking reason takes its place. Each message is the icon
+              plus one span: left as loose text and <strong> in the flex row,
+              every fragment became a column of its own and wrapped apart. */}
+          {isValid && isStale ? (
+            <p className={classNames(styles.summary, styles.summaryStale)}>
+              <WarningAlt size={16} />
+              <span>
+                Filters changed. The report below is for <strong>{shownPeriod?.label}</strong> &mdash; select Generate
+                report to refresh it.
+              </span>
+            </p>
+          ) : isValid ? (
+            <p className={styles.summary}>
+              <Calendar size={16} />
+              <span>
+                Reporting period: <strong>{period.label}</strong>
+              </span>
+            </p>
+          ) : (
+            <p className={classNames(styles.summary, styles.summaryInvalid)}>
+              <WarningAlt size={16} />
+              <span>{firstError(errors)}</span>
+            </p>
+          )}
+          <div className={styles.actionButtons}>
+            {/* Only offered once there is something on screen to put on paper */}
+            {isReportGenerated && !isLoading && (
+              <Button kind="tertiary" size="sm" renderIcon={Download} onClick={downloadPdf} disabled={isPreparingPdf}>
+                {isPreparingPdf ? 'Preparing PDF…' : 'Download PDF'}
+              </Button>
+            )}
+            <Button size="sm" renderIcon={ChartColumn} onClick={handleGenerate} disabled={isLoading || !isValid}>
+              {isLoading ? 'Generating…' : 'Generate report'}
+            </Button>
           </div>
-        )}
-      </div>
-      {!isLoding && (
-        <div className={styles.buttonContainer}>
-          <Button onClick={generateReport}>Generate Report</Button>
         </div>
-      )}
-    </>
+      </Layer>
+    </div>
   );
 };