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

package/src/registers/tb-lab-register/tb-lab-register-table.component.tsx

@@ -0,0 +1,116 @@
+import React from 'react';
+
+import { TB_LAB_COLUMNS, type TbLabColumn, type TbLabRow, text } from './tb-lab-register.columns';
+import styles from './tb-lab-register-table.scss';
+
+interface TbLabRegisterTableProps {
+  rows: TbLabRow[];
+  facility?: string;
+  startDate?: string;
+  endDate?: string;
+}
+
+interface HeaderCell {
+  /** A two-tier group spanning its member columns; undefined for a tall column */
+  group?: string;
+  /** The column's own label, repeated once per member under a group */
+  label: string;
+  /** Columns the header spans */
+  span: number;
+  /** 2 for a column that stands alone across both header rows */
+  height: number;
+}
+
+/**
+ * The printed template's two-tier header, rebuilt from the column spec:
+ * consecutive members of a group sit under one spanning group cell, standalone
+ * columns stand two rows tall.
+ */
+export function headerCellsFor(columns: TbLabColumn[]): HeaderCell[][] {
+  const top: HeaderCell[] = [];
+  const bottom: HeaderCell[] = [];
+
+  columns.forEach((column, index) => {
+    if (!column.group) {
+      top.push({ group: undefined, label: column.header, span: 1, height: 2 });
+      return;
+    }
+    const previous = columns[index - 1];
+    if (previous?.group === column.group) {
+      top[top.length - 1].span += 1;
+    } else {
+      top.push({ group: column.group, label: column.group, span: 1, height: 1 });
+    }
+    bottom.push({ group: undefined, label: column.header, span: 1, height: 1 });
+  });
+
+  return [top, bottom];
+}
+
+/**
+ * The TB Laboratory Register as the printed template lays it out: one row per
+ * specimen tested, the two-tier header over the appearance and microscopy
+ * columns, drawn as a landscape sheet that scrolls sideways in its frame.
+ */
+const TbLabRegisterTable: React.FC<TbLabRegisterTableProps> = ({ rows, facility = '', startDate, endDate }) => {
+  const [topRow, bottomRow] = headerCellsFor(TB_LAB_COLUMNS);
+  const period = [startDate, endDate]
+    .filter(Boolean)
+    .map((value) => asDay(value))
+    .join(' to ');
+
+  return (
+    <div className={styles.sheet}>
+      <div className={styles.runningHead}>
+        <span>Ministry of Health</span>
+        <span>TB LABORATORY REGISTER</span>
+        <span>{facility}</span>
+      </div>
+      {period && <div className={styles.period}>{period}</div>}
+
+      <div className={styles.tableScroll}>
+        <table className={styles.register}>
+          <thead>
+            <tr>
+              {topRow.map((cell, index) =>
+                cell.group ? (
+                  <th key={index} colSpan={cell.span}>
+                    {cell.label}
+                  </th>
+                ) : (
+                  <th key={index} rowSpan={2} className={styles.tall}>
+                    {cell.label}
+                  </th>
+                ),
+              )}
+            </tr>
+            <tr>
+              {bottomRow.map((cell, index) => (
+                <th key={index}>{cell.label}</th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map((row, index) => (
+              <tr key={text(row.lab_no) || index}>
+                {TB_LAB_COLUMNS.map((column, cellIndex) => (
+                  <td key={cellIndex} className={column.align === 'left' ? styles.left : undefined}>
+                    {text(column.value(row, index))}
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+};
+
+/** Renders a filter-bar period (YYYY-MM-DD) the way the register reads it */
+function asDay(value: string): string {
+  const parts = value.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  return parts ? `${parts[3]}/${parts[2]}/${parts[1]}` : value;
+}
+
+export default TbLabRegisterTable;

package/src/registers/tb-lab-register/tb-lab-register-table.scss

@@ -0,0 +1,123 @@
+@use '@carbon/layout';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+/* The TB Laboratory Register sheet, drawn as on the printed template: black
+   rules, small type, a two-tier header over the appearance and microscopy
+   columns. It is a wide landscape sheet, so it scrolls sideways inside its
+   frame rather than widening the page. */
+
+$ink: #000;
+$rule: 1px solid $ink;
+$text: 0.6875rem; // 11px body
+$small: 0.625rem; // 10px codes
+
+.sheet {
+  margin-top: layout.$spacing-05;
+  padding: layout.$spacing-05;
+  color: $ink;
+  font-size: $text;
+  line-height: 1.25;
+  background-color: $ui-02;
+  border: 1px solid $ui-03;
+}
+
+.runningHead {
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  gap: layout.$spacing-05;
+  font-size: $small;
+  font-weight: 700;
+
+  span:nth-child(2) {
+    text-align: center;
+  }
+
+  span:last-child {
+    text-align: right;
+    font-weight: 400;
+  }
+}
+
+.period {
+  margin-top: layout.$spacing-02;
+  font-size: $small;
+  text-align: right;
+}
+
+.tableScroll {
+  margin-top: layout.$spacing-03;
+  overflow-x: auto;
+}
+
+.register {
+  width: 100%;
+  min-width: 105rem;
+  border-collapse: collapse;
+
+  th,
+  td {
+    padding: layout.$spacing-02;
+    text-align: center;
+    vertical-align: middle;
+    border: $rule;
+  }
+
+  th {
+    font-weight: 400;
+    vertical-align: top;
+  }
+
+  /* a group header stays centred over its member columns */
+  thead tr:first-child th[colspan] {
+    font-weight: 700;
+    text-align: center;
+    vertical-align: middle;
+  }
+
+  td {
+    height: 1.125rem;
+  }
+}
+
+/* a column that stands alone across both header rows reads from the middle */
+.tall {
+  vertical-align: middle !important;
+}
+
+.left {
+  text-align: left !important;
+}
+
+/* Page furniture around the sheet */
+
+.toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: layout.$spacing-05;
+  margin-top: layout.$spacing-05;
+}
+
+.total {
+  margin-right: auto;
+  font-size: 0.8125rem;
+  color: $text-02;
+}
+
+.pager {
+  margin-top: layout.$spacing-04;
+}
+
+.empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: layout.$spacing-03;
+  margin-top: layout.$spacing-06;
+  padding: layout.$spacing-08 layout.$spacing-05;
+  text-align: center;
+}
+
+.emptyIcon {
+  fill: $text-03;
+}

package/src/registers/tb-lab-register/tb-lab-register.columns.ts

@@ -0,0 +1,164 @@
+import dayjs from 'dayjs';
+
+import { type RegisterColumn } from '../../common/report-register';
+
+/**
+ * One row of the TB Laboratory Register: a lab-706 patient-list payload row for
+ * a TB test, fetched with the `total_tb_smear` indicator -- the one TB row
+ * filter the existing dataset carries (MOH 706 5.29). The columns the dataset
+ * does not carry yet (time in/out, ID/NEMIS, patient type, HIV status, TB-LAMP,
+ * LF-LAM, GeneXpert/Truenat) read blank until the ETL layer grows them.
+ */
+export type TbLabRow = Record<string, any>;
+
+/** Blank rather than "null" / "undefined" in a cell */
+export const text = (value: unknown) => (value === null || value === undefined ? '' : String(value).trim());
+
+/** DD/MM/YYYY, as the register prints it; values already in that shape pass through */
+export function asRegisterDate(value: unknown): string {
+  const raw = text(value);
+  if (!raw) {
+    return '';
+  }
+  return /^\d{4}-\d{2}-\d{2}/.test(raw) ? dayjs(raw.slice(0, 10)).format('DD/MM/YYYY') : raw;
+}
+
+/** The date part of either an ISO datetime or an already-formatted DD/MM/YYYY, as YYYY-MM-DD */
+const toIsoDate = (value: unknown): string => {
+  const raw = text(value);
+  if (/^\d{4}-\d{2}-\d{2}/.test(raw)) {
+    return raw.slice(0, 10);
+  }
+  const parts = raw.match(/^(\d{2})\/(\d{2})\/(\d{4})/);
+  return parts ? `${parts[3]}-${parts[2]}-${parts[1]}` : '';
+};
+
+/** Turnaround in whole calendar days, from sample collected to results dispatched */
+export function tatDays(row: TbLabRow): string {
+  const from = toIsoDate(row.test_datetime);
+  const to = toIsoDate(row.date_results_dispatched);
+  if (!from || !to) {
+    return '';
+  }
+  const days = dayjs(to).diff(dayjs(from), 'day');
+  return days >= 0 ? String(days) : '';
+}
+
+/**
+ * Which sputum the row's sample is. The dataset does not carry the sample's
+ * timing yet, so it is read off the specimen label; rows that do not say print
+ * under Spot rather than being dropped, until the ETL carries the timing.
+ */
+export function timingOf(row: TbLabRow): 'spot' | 'morning' {
+  return /morning/i.test(text(row.type_of_specimen)) ? 'morning' : 'spot';
+}
+
+/** The stain the microscopy used, as the template's Type ZN/FM column reads it */
+export function stainType(row: TbLabRow): string {
+  const investigation = text(row.investigation_required).toLowerCase();
+  if (/fluor|\bfm\b/.test(investigation)) {
+    return 'FM';
+  }
+  if (/ziehl|\bzn\b/.test(investigation)) {
+    return 'ZN';
+  }
+  return '';
+}
+
+/** Which of the register's result columns the row's test result belongs in */
+function resultKindOf(row: TbLabRow): 'microscopy' | 'tb_lamp' | 'lf_lam' | 'genexpert' {
+  const investigation = text(row.investigation_required).toLowerCase();
+  if (/lamp/.test(investigation)) {
+    return 'tb_lamp';
+  }
+  if (/\blam\b|lf.?lam|lateral flow/.test(investigation)) {
+    return 'lf_lam';
+  }
+  if (/xpert|genexp|truenat|mtb|rif/.test(investigation)) {
+    return 'genexpert';
+  }
+  return 'microscopy';
+}
+
+/** The row's result, placed in its own column: blank in the other result columns */
+const resultIn = (kind: 'microscopy' | 'tb_lamp' | 'lf_lam' | 'genexpert') => (row: TbLabRow) =>
+  resultKindOf(row) === kind ? text(row.results) : '';
+
+/** The sample appearance, under the sub-column its timing names */
+const appearanceIn = (timing: 'spot' | 'morning') => (row: TbLabRow) =>
+  timingOf(row) === timing ? text(row.condition_of_specimen) : '';
+
+/** The microscopy result, under the sub-column its timing names */
+const microscopyIn = (timing: 'spot' | 'morning') => (row: TbLabRow) =>
+  resultKindOf(row) === 'microscopy' && timingOf(row) === timing ? text(row.results) : '';
+
+export interface TbLabColumn {
+  /** The two-tier header group the column sits under, e.g. `Microscopy result` */
+  group?: string;
+  /** The column's own label, as the printed template reads it */
+  header: string;
+  value: (row: TbLabRow, index: number) => unknown;
+  /** Identifiers and phones stay text in the CSV */
+  text?: boolean;
+  /** Prose columns read left-aligned; the rest centre, as on the template */
+  align?: 'left';
+}
+
+/** The register's columns, in the order the printed template runs them */
+export const TB_LAB_COLUMNS: TbLabColumn[] = [
+  { header: 'Lab S/No.', value: (row, index) => text(row.lab_no) || index + 1 },
+  { header: 'Date sample collected', value: (row) => asRegisterDate(row.test_datetime) },
+  { header: 'Date sample received', value: (row) => asRegisterDate(row.date_sample_received) },
+  /* not in the dataset yet: the ETL layer will carry it with the sample's timing */
+  { header: 'Time in', value: () => '' },
+  { header: 'Name (full)', value: (row) => text(row.full_name), align: 'left' },
+  { header: 'TB Reg. No. for follow ups / OPD No.', value: (row) => text(row.opd_ip_ref_no) },
+  { header: 'Sex M/F', value: (row) => text(row.sex) },
+  { header: 'Age (years)', value: (row) => text(row.age) },
+  /* not in the dataset yet: national ID / NEMIS / passport */
+  { header: "Patient's ID No./ NEMIS/ Passport", value: () => '' },
+  {
+    header: "Patient's physical address",
+    value: (row) => [text(row.village_estate_landmark), text(row.county_sub_county)].filter(Boolean).join(', '),
+    align: 'left',
+  },
+  { header: "Patient's/ guardian phone no.", value: (row) => text(row.telephone_number), text: true },
+  /* the dataset's referrals carry the from/to facility, which is what the
+     template's referring-facility column holds until a department is carried */
+  { header: 'Name of referring facility/ Department', value: (row) => text(row.referrals), align: 'left' },
+  /* not in the dataset yet: N / F2/F3/F5/F6 / O */
+  { header: 'Type of patient N, F2/F3/F5/F6, O', value: () => '' },
+  /* not in the dataset yet: Pos/Neg/ND/D */
+  { header: 'HIV status Pos/Neg/ND/D', value: () => '' },
+  { group: 'Sample appearance S / M / B', header: 'Spot', value: appearanceIn('spot') },
+  { group: 'Sample appearance S / M / B', header: 'Morning', value: appearanceIn('morning') },
+  { group: 'Microscopy result 0 = No AFB | actual no. | 1+ 2+ 3+', header: 'Type ZN/FM', value: stainType },
+  { group: 'Microscopy result 0 = No AFB | actual no. | 1+ 2+ 3+', header: 'Spot', value: microscopyIn('spot') },
+  {
+    group: 'Microscopy result 0 = No AFB | actual no. | 1+ 2+ 3+',
+    header: 'Morning',
+    value: microscopyIn('morning'),
+  },
+  { header: 'TB-LAMP', value: resultIn('tb_lamp') },
+  { header: 'LF-LAM', value: resultIn('lf_lam') },
+  { header: 'GeneXpert/ Truenat', value: resultIn('genexpert') },
+  { header: 'Date tested', value: (row) => asRegisterDate(row.date_sample_analysed) },
+  { header: 'Date results dispatched', value: (row) => asRegisterDate(row.date_results_dispatched) },
+  /* not in the dataset yet */
+  { header: 'Time out (results dispatch)', value: () => '' },
+  { header: 'TAT (days)', value: tatDays },
+  { header: "Laboratory officer's name", value: (row) => text(row.testing_officer), align: 'left' },
+  { header: 'Remarks (date & place sample referred etc.)', value: (row) => text(row.comments), align: 'left' },
+];
+
+/**
+ * The register as exportable CSV columns: the two-tier header flattened into
+ * one unambiguous label per column, so the file reads without the grouping.
+ */
+export function tbLabCsvColumns(): RegisterColumn[] {
+  return TB_LAB_COLUMNS.map((column) => ({
+    header: column.group ? `${column.group} - ${column.header}` : column.header,
+    value: column.value,
+    text: column.text,
+  }));
+}

package/src/registers/tb-lab-register/tb-lab-register.component.test.tsx

@@ -0,0 +1,232 @@
+import React from 'react';
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter } from 'react-router-dom';
+
+import TbLabRegister from './tb-lab-register.component';
+import { TB_LAB_COLUMNS, tbLabCsvColumns } from './tb-lab-register.columns';
+import { downloadCsv } from '../../common/report-register';
+import { getMoh706PatientList } from '../../resources/moh-706.resource';
+
+jest.mock('../../common/report-register', () => ({
+  ...jest.requireActual('../../common/report-register'),
+  downloadCsv: jest.fn(),
+}));
+
+jest.mock('../../resources/moh-706.resource', () => ({
+  getMoh706PatientList: jest.fn(),
+}));
+
+jest.mock('@openmrs/esm-framework', () => ({
+  useSession: () => ({ sessionLocation: { uuid: 'loc-uuid', display: 'Test Facility' } }),
+  openmrsFetch: jest.fn().mockResolvedValue({ ok: false }),
+  showSnackbar: jest.fn(),
+}));
+
+/* The filter bar is Carbon-heavy and its period picking is not what this page
+   is about, so it is stood in by a button that generates a fixed period. The
+   restore-from-URL hook stays real, as it is part of the page's behaviour. */
+jest.mock('../../common/report-filters', () => {
+  const actual = jest.requireActual('../../common/report-filters');
+  return {
+    ...actual,
+    ReportFiltersComponent: ({
+      onGenerate,
+    }: {
+      onGenerate: (period: { startDate: string; endDate: string; label?: string }) => void;
+    }) => (
+      <button onClick={() => onGenerate({ startDate: '2026-10-01', endDate: '2026-10-02', label: 'period' })}>
+        generate
+      </button>
+    ),
+  };
+});
+
+/** A TB smear row as the lab-706 patient list returns it: a spot sputum, ZN stain */
+const aRow = (overrides: Record<string, unknown> = {}) => ({
+  lab_no: 'L-0007',
+  test_datetime: '2026-10-01T09:00:00.000Z',
+  date_sample_received: '2026-10-01',
+  full_name: 'Jane Akinyi',
+  opd_ip_ref_no: 'OPD-12',
+  sex: 'F',
+  age: 34,
+  village_estate_landmark: 'Mama Ngina',
+  county_sub_county: 'Kisumu East',
+  telephone_number: '0700123456',
+  referrals: 'Kisumu County Hospital',
+  type_of_specimen: 'Spot',
+  condition_of_specimen: 'B',
+  investigation_required: 'Ziehl-Neelsen stain',
+  results: '1+',
+  date_sample_analysed: '2026-10-02',
+  date_results_dispatched: '2026-10-03',
+  testing_officer: 'J. Otieno',
+  comments: '',
+  ...overrides,
+});
+
+const renderRegister = () =>
+  render(
+    <MemoryRouter>
+      <TbLabRegister />
+    </MemoryRouter>,
+  );
+
+const page = (results: Array<Record<string, unknown>>, total = results.length) => ({
+  results,
+  total,
+  isTotalExact: true,
+});
+
+const cellValues = (row: HTMLTableRowElement) =>
+  within(row)
+    .getAllByRole('cell')
+    .map((cell) => cell.textContent);
+
+describe('TbLabRegister', () => {
+  beforeEach(() => {
+    jest.mocked(downloadCsv).mockClear();
+    jest.mocked(getMoh706PatientList).mockReset();
+  });
+
+  it('asks for the register to be generated before showing anything', () => {
+    renderRegister();
+
+    expect(screen.getByText('No report generated yet')).toBeInTheDocument();
+    expect(getMoh706PatientList).not.toHaveBeenCalled();
+  });
+
+  it('fetches the whole TB workload and lays the template out', async () => {
+    jest
+      .mocked(getMoh706PatientList)
+      .mockResolvedValue(
+        page([
+          aRow(),
+          aRow({
+            type_of_specimen: 'Morning',
+            investigation_required: 'Fluorescent microscopy',
+            results: 'No AFB seen',
+            condition_of_specimen: 'S',
+          }),
+        ]),
+      );
+
+    const { container } = renderRegister();
+    await userEvent.click(screen.getByRole('button', { name: 'generate' }));
+
+    await waitFor(() => expect(screen.getByText('2 records')).toBeInTheDocument());
+
+    /* the register's own row filter: every TB smear of the period */
+    expect(getMoh706PatientList).toHaveBeenCalledWith(
+      expect.objectContaining({
+        locationUuids: 'loc-uuid',
+        startDate: '2026-10-01',
+        endDate: '2026-10-02',
+        indicators: 'total_tb_smear',
+      }),
+    );
+
+    const table = within(container.querySelector('table') as HTMLTableElement);
+    const headerRows = within(table.getAllByRole('rowgroup')[0]).getAllByRole('row');
+    expect(headerRows).toHaveLength(2);
+
+    /* the top tier: the standalone columns, with the two groups sitting
+       between the columns they span */
+    const tallLabels = TB_LAB_COLUMNS.filter((column) => !column.group).map((column) => column.header);
+    const groups = [...new Set(TB_LAB_COLUMNS.filter((column) => column.group).map((column) => column.group!))];
+    const topCells = within(headerRows[0])
+      .getAllByRole('columnheader')
+      .map((cell) => cell.textContent);
+    expect(topCells).toEqual([...tallLabels.slice(0, 14), ...groups, ...tallLabels.slice(14)]);
+    /* the bottom tier: the five sub-columns under the groups */
+    expect(
+      within(headerRows[1])
+        .getAllByRole('columnheader')
+        .map((cell) => cell.textContent),
+    ).toEqual(['Spot', 'Morning', 'Type ZN/FM', 'Spot', 'Morning']);
+
+    const bodyRows = within(table.getAllByRole('rowgroup')[1]).getAllByRole('row');
+    /* the spot row: appearance and result under Spot, the stain read off the test, two-day TAT */
+    expect(cellValues(bodyRows[0] as HTMLTableRowElement)).toEqual([
+      'L-0007',
+      '01/10/2026',
+      '01/10/2026',
+      '',
+      'Jane Akinyi',
+      'OPD-12',
+      'F',
+      '34',
+      '',
+      'Mama Ngina, Kisumu East',
+      '0700123456',
+      'Kisumu County Hospital',
+      '',
+      '',
+      'B',
+      '',
+      'ZN',
+      '1+',
+      '',
+      '',
+      '',
+      '',
+      '02/10/2026',
+      '03/10/2026',
+      '',
+      '2',
+      'J. Otieno',
+      '',
+    ]);
+    /* the morning row: appearance and result under Morning, stain FM */
+    expect(cellValues(bodyRows[1] as HTMLTableRowElement)[15]).toBe('S');
+    expect(cellValues(bodyRows[1] as HTMLTableRowElement)[16]).toBe('FM');
+    expect(cellValues(bodyRows[1] as HTMLTableRowElement)[18]).toBe('No AFB seen');
+  });
+
+  it('exports every page with the two-tier header flattened into one label per column', async () => {
+    jest.mocked(getMoh706PatientList).mockResolvedValue(page([aRow()]));
+
+    renderRegister();
+    await userEvent.click(screen.getByRole('button', { name: 'generate' }));
+    await waitFor(() => expect(screen.getByRole('button', { name: /Export CSV/ })).toBeInTheDocument());
+
+    await userEvent.click(screen.getByRole('button', { name: /Export CSV/ }));
+
+    await waitFor(() => expect(jest.mocked(downloadCsv)).toHaveBeenCalledTimes(1));
+    const [csv, filename] = jest.mocked(downloadCsv).mock.calls[0];
+    const lines = (csv as string).split('\r\n');
+    /* labels holding commas come out quoted, as CSV requires */
+    expect(lines[0]).toBe(
+      tbLabCsvColumns()
+        .map((column) => (column.header.includes(',') ? `"${column.header}"` : column.header))
+        .join(','),
+    );
+    /* phones and lab numbers survive Excel as text */
+    expect(lines[1]).toContain('="0700123456"');
+    expect(filename).toBe('tb-laboratory-register-2026-10-01-2026-10-02.csv');
+  });
+
+  it('pagers past the first page when the period holds more rows than one page', async () => {
+    jest.mocked(getMoh706PatientList).mockResolvedValue(
+      page(
+        Array.from({ length: 50 }, () => aRow()),
+        120,
+      ),
+    );
+
+    renderRegister();
+    await userEvent.click(screen.getByRole('button', { name: 'generate' }));
+
+    await waitFor(() => expect(screen.getByText(/120 items/)).toBeInTheDocument());
+  });
+
+  it('falls back to the placeholder when the register cannot be fetched', async () => {
+    jest.mocked(getMoh706PatientList).mockRejectedValue(new Error('etl down'));
+
+    renderRegister();
+    await userEvent.click(screen.getByRole('button', { name: 'generate' }));
+
+    await waitFor(() => expect(screen.getByText('No report generated yet')).toBeInTheDocument());
+  });
+});