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

package/src/common/report-page/download-sheet-pdf.ts

@@ -0,0 +1,225 @@
+import type { toCanvas as ToCanvas } from 'html-to-image';
+
+/** Paper sizes, in millimetres, portrait */
+const PAPER_MM = {
+  a4: { width: 210, height: 297 },
+  a3: { width: 297, height: 420 },
+};
+
+export type PaperSize = keyof typeof PAPER_MM;
+export type PageOrientation = 'portrait' | 'landscape';
+
+/** Capture resolution: 3 device pixels per CSS pixel keeps 5.5pt type sharp */
+const PIXEL_RATIO = 3;
+
+/**
+ * Pages stored as JPEG are captured at 2.5 device pixels per CSS pixel (some
+ * 240 dpi on paper) and quality 0.8: 3.6pt type stays crisp, and a page is
+ * about 0.7MB rather than 1.1MB at 3x and 0.92
+ */
+const JPEG_PIXEL_RATIO = 2.5;
+const JPEG_QUALITY = 0.8;
+
+/** Waits for the browser to lay out and paint a change */
+const nextPaint = () =>
+  new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+
+/**
+ * A copy of a sheet at paper size, without the on-screen magnification
+ * (`--page-zoom`), laid out off screen: the sheet the user is looking at never
+ * changes while the file is prepared, and a sheet in a hidden tab, which has
+ * no size of its own, can be measured and saved without showing it.
+ */
+const stageCopy = (sheet: HTMLElement) => {
+  const stage = document.createElement('div');
+  stage.setAttribute('aria-hidden', 'true');
+  Object.assign(stage.style, { position: 'fixed', top: '0', left: '-100000px', pointerEvents: 'none' });
+  const copy = sheet.cloneNode(true) as HTMLElement;
+  copy.style.setProperty('--page-zoom', '1');
+  copy.style.margin = '0';
+  stage.appendChild(copy);
+  document.body.appendChild(stage);
+  return { stage, copy };
+};
+
+/**
+ * Captures a sheet by copying every element's computed style onto the capture,
+ * so it works for any sheet, web fonts included.
+ */
+async function captureWithComputedStyles(
+  sheet: HTMLElement,
+  toCanvas: typeof ToCanvas,
+  fontEmbedCSS: string,
+  pixelRatio: number,
+): Promise<HTMLCanvasElement> {
+  const { stage, copy } = stageCopy(sheet);
+
+  try {
+    await nextPaint();
+    return await toCanvas(copy, {
+      pixelRatio,
+      backgroundColor: '#fff',
+      width: copy.offsetWidth,
+      height: copy.offsetHeight,
+      fontEmbedCSS,
+    });
+  } finally {
+    stage.remove();
+  }
+}
+
+/**
+ * The page's own CSS rules that can apply to the sheets: those naming a class
+ * used in them, and the element-only rules (the styleguide's reset), within
+ * the media queries that hold now.
+ */
+function sheetStyles(sheets: HTMLElement[]): string {
+  const classes = new Set<string>();
+  for (const sheet of sheets) {
+    for (const element of [sheet, ...Array.from(sheet.querySelectorAll('[class]'))]) {
+      element.classList.forEach((name) => classes.add(`.${CSS.escape(name)}`));
+    }
+  }
+  const classList = Array.from(classes);
+
+  const rules: string[] = [];
+  const keep = (rule: CSSRule) => {
+    if (rule instanceof CSSStyleRule) {
+      const selector = rule.selectorText;
+      if (!/[.#]/.test(selector) || classList.some((name) => selector.includes(name))) {
+        rules.push(rule.cssText);
+      }
+    } else if (rule instanceof CSSMediaRule && window.matchMedia(rule.conditionText).matches) {
+      Array.from(rule.cssRules).forEach(keep);
+    }
+  };
+  for (const styleSheet of Array.from(document.styleSheets)) {
+    let sheetRules: CSSRuleList;
+    try {
+      sheetRules = styleSheet.cssRules;
+    } catch {
+      // a stylesheet from another origin cannot be read, and styles no sheet
+      continue;
+    }
+    Array.from(sheetRules).forEach(keep);
+  }
+  return rules.join('\n');
+}
+
+/**
+ * Captures a sheet styled wholly by the page's stylesheets and set in fonts
+ * every computer has, by drawing its markup with those rules: some twenty times
+ * quicker than copying every element's computed style, which matters for a
+ * register of many pages. Web fonts would not load in the drawing.
+ */
+async function captureWithStylesheets(sheet: HTMLElement, css: string, pixelRatio: number): Promise<HTMLCanvasElement> {
+  const { stage, copy } = stageCopy(sheet);
+  const width = copy.offsetWidth;
+  const height = copy.offsetHeight;
+  stage.remove();
+
+  const markup = new XMLSerializer().serializeToString(copy);
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">` +
+    `<foreignObject width="100%" height="100%"><div xmlns="http://www.w3.org/1999/xhtml">` +
+    `<style>${css.replace(/</g, '\\3c ')}</style>${markup}</div></foreignObject></svg>`;
+
+  const image = new Image();
+  image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+  await image.decode();
+
+  const canvas = document.createElement('canvas');
+  canvas.width = Math.round(width * pixelRatio);
+  canvas.height = Math.round(height * pixelRatio);
+  const context = canvas.getContext('2d');
+  if (!context) {
+    throw new Error('This browser cannot draw the page for the PDF');
+  }
+  context.fillStyle = '#fff';
+  context.fillRect(0, 0, canvas.width, canvas.height);
+  context.drawImage(image, 0, 0, canvas.width, canvas.height);
+  return canvas;
+}
+
+/**
+ * Saves sheets as a PDF file, one sheet to a page: A4 unless another paper
+ * size is given (the Presumptive TB Register is an A3 form).
+ *
+ * Each sheet is captured as drawn on screen and placed on its page within the
+ * given margin, scaled down only if it would not otherwise fit, so the file is
+ * the form itself rather than the browser's print layout (no headers, footers
+ * or print dialog). Sheets are captured one at a time, so a long register does
+ * not hold every page's image in memory at once.
+ *
+ * Two options keep a many-page file quick to make:
+ * - `stylesheetsOnly`, for sheets styled wholly by the page's stylesheets and
+ *   set in fonts every computer has (Arial, Georgia): each is drawn from its
+ *   markup and those rules, in a fraction of a second rather than seconds.
+ * - `image: 'jpeg'`: each page is stored as a JPEG rather than a PNG, which is
+ *   many times quicker to put in the file and makes it smaller, with no
+ *   visible loss in printed type.
+ */
+export async function downloadSheetsPdf(
+  sheets: HTMLElement[],
+  fileName: string,
+  {
+    paperSize = 'a4',
+    orientation = 'portrait',
+    marginMm = 8,
+    stylesheetsOnly = false,
+    image = 'png',
+  }: {
+    paperSize?: PaperSize;
+    orientation?: PageOrientation;
+    marginMm?: number;
+    stylesheetsOnly?: boolean;
+    image?: 'png' | 'jpeg';
+  } = {},
+): Promise<void> {
+  if (!sheets.length) {
+    return;
+  }
+  const [{ toCanvas, getFontEmbedCSS }, { jsPDF }] = await Promise.all([import('html-to-image'), import('jspdf')]);
+
+  /* Rules and web fonts are gathered once for the whole file, not per page */
+  const css = stylesheetsOnly ? sheetStyles(sheets) : '';
+  const fontEmbedCSS = stylesheetsOnly ? '' : await getFontEmbedCSS(sheets[0]);
+
+  const pixelRatio = image === 'jpeg' ? JPEG_PIXEL_RATIO : PIXEL_RATIO;
+  const portrait = PAPER_MM[paperSize];
+  const paper = orientation === 'portrait' ? portrait : { width: portrait.height, height: portrait.width };
+  const maxWidth = paper.width - 2 * marginMm;
+  const maxHeight = paper.height - 2 * marginMm;
+  const pdf = new jsPDF({ orientation, unit: 'mm', format: paperSize, compress: true });
+
+  for (const [index, sheet] of sheets.entries()) {
+    const canvas = stylesheetsOnly
+      ? await captureWithStylesheets(sheet, css, pixelRatio)
+      : await captureWithComputedStyles(sheet, toCanvas, fontEmbedCSS, pixelRatio);
+    const aspect = canvas.width / canvas.height;
+    const width = Math.min(maxWidth, maxHeight * aspect);
+    const height = width / aspect;
+
+    if (index > 0) {
+      pdf.addPage(paperSize, orientation);
+    }
+    const pageImage = image === 'jpeg' ? canvas.toDataURL('image/jpeg', JPEG_QUALITY) : canvas;
+    pdf.addImage(
+      pageImage,
+      image === 'jpeg' ? 'JPEG' : 'PNG',
+      (paper.width - width) / 2,
+      marginMm,
+      width,
+      height,
+      undefined,
+      'FAST',
+    );
+  }
+
+  pdf.save(fileName);
+}
+
+/** Saves an A4 sheet as a one-page A4 portrait PDF file */
+export function downloadSheetPdf(sheet: HTMLElement, fileName: string, marginMm = 8): Promise<void> {
+  return downloadSheetsPdf([sheet], fileName, { marginMm });
+}

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

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

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';

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) : '',
+    })),
+  );
+}