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

package/src/common/linelist-table/linelist-table.scss

@@ -0,0 +1,306 @@
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+/* A screen table for reading and analysing a list: compact rows, a header
+ * that stays in view while scrolling, and cells that truncate (full value on
+ * hover) so one long name cannot stretch every row. */
+
+.linelist {
+  /* Light gridlines: just darker than the striping, so columns stay distinct on
+     both white and grey rows without the grid competing with the values */
+  --linelist-grid: #e2e2e2;
+  --linelist-grid-header: #cfcfcf;
+
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.toolbar {
+  position: relative;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.25rem 0.5rem;
+}
+
+.search {
+  flex: 1 1 16rem;
+  max-width: 24rem;
+}
+
+.count {
+  margin-left: auto;
+  font-size: 0.75rem;
+  color: var(--cds-text-secondary, #525252);
+  white-space: nowrap;
+}
+
+.activeFilters {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+}
+
+/* Bounded height so the sticky header has something to stick within */
+.scroll {
+  max-height: calc(100vh - 18rem);
+  min-height: 12rem;
+  overflow: auto;
+  border: 1px solid var(--linelist-grid);
+}
+
+.table {
+  width: 100%;
+  border-collapse: separate;
+  border-spacing: 0;
+  font-size: 0.8125rem;
+  line-height: 1.25;
+
+  th,
+  td {
+    padding: 0.3125rem 0.625rem;
+    text-align: left;
+    vertical-align: middle;
+    border-right: 1px solid var(--linelist-grid);
+    border-bottom: 1px solid var(--linelist-grid);
+  }
+
+  /* The scroll frame already draws the outer edge */
+  th:last-child,
+  td:last-child {
+    border-right: none;
+  }
+
+  thead th {
+    border-right-color: var(--linelist-grid-header);
+    border-bottom-color: var(--linelist-grid-header);
+  }
+
+  td {
+    max-width: 18rem;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--cds-text-primary, #161616);
+  }
+
+  thead th {
+    position: sticky;
+    top: 0;
+    z-index: 2;
+    padding: 0;
+    font-weight: 600;
+    white-space: nowrap;
+    background-color: var(--cds-layer-accent-01, #e0e0e0);
+    cursor: grab;
+  }
+
+  tbody tr:nth-of-type(even) td {
+    background-color: var(--cds-layer-01, #f4f4f4);
+  }
+
+  tbody tr:hover td {
+    background-color: $brand-primary-10;
+  }
+}
+
+/* The filter row sits under the headings and sticks with them */
+.filterRow th {
+  top: 2rem;
+  padding: 0.25rem 0.375rem;
+  cursor: default;
+  background-color: var(--cds-layer-01, #f4f4f4);
+}
+
+.filterInput {
+  width: 100%;
+  min-width: 5rem;
+  height: 1.5rem;
+  padding: 0 0.375rem;
+  font: inherit;
+  font-size: 0.75rem;
+  font-weight: 400;
+  background-color: var(--cds-field-01, #fff);
+  border: 1px solid var(--cds-border-strong-01, #8d8d8d);
+  border-width: 0 0 1px;
+
+  &:focus {
+    outline: 2px solid var(--cds-focus, #0f62fe);
+    outline-offset: -2px;
+  }
+}
+
+.sortButton {
+  display: flex;
+  width: 100%;
+  height: 2rem;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  padding: 0 0.625rem;
+  font: inherit;
+  font-weight: 600;
+  color: var(--cds-text-primary, #161616);
+  text-align: left;
+  background: none;
+  border: none;
+  cursor: pointer;
+
+  &:hover {
+    background-color: var(--cds-layer-accent-hover-01, #d1d1d1);
+  }
+
+  &:hover .sortIdle {
+    opacity: 1;
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--cds-focus, #0f62fe);
+    outline-offset: -2px;
+  }
+}
+
+.sortIdle {
+  flex-shrink: 0;
+  opacity: 0.3;
+}
+
+.sortActive {
+  flex-shrink: 0;
+  fill: var(--cds-link-primary, #0f62fe);
+}
+
+.dragging {
+  opacity: 0.4;
+}
+
+.dropTarget {
+  box-shadow: inset 3px 0 0 var(--cds-focus, #0f62fe);
+}
+
+/* The running row number stays in view when scrolling sideways */
+.table .rowNumber {
+  position: sticky;
+  left: 0;
+  z-index: 1;
+  width: 3rem;
+  padding: 0.3125rem 0.5rem;
+  color: var(--cds-text-secondary, #525252);
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+  background-color: var(--cds-layer-accent-01, #e0e0e0);
+  border-right: 1px solid var(--linelist-grid);
+  cursor: default;
+}
+
+.table thead .rowNumber {
+  z-index: 3;
+}
+
+/* In the body the row number takes its row's striping and hover like any other
+   cell; it only needs an opaque background so cells slide beneath it. */
+.table tbody td.rowNumber {
+  background-color: var(--cds-background, #fff);
+}
+
+.table td.wrap {
+  min-width: 10rem;
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+
+.noMatches {
+  padding: 2rem 1rem !important;
+  color: var(--cds-text-secondary, #525252);
+  text-align: center !important;
+}
+
+.linkButton {
+  padding: 0;
+  font: inherit;
+  color: var(--cds-link-primary, #0f62fe);
+  text-decoration: underline;
+  background: none;
+  border: none;
+  cursor: pointer;
+}
+
+.pagination {
+  border-top: none;
+}
+
+.columnsPanel {
+  position: absolute;
+  z-index: 10;
+  width: min(20rem, 100%);
+  padding: 0.75rem;
+  background-color: var(--cds-layer-01, #f4f4f4);
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
+}
+
+.columnsHint {
+  margin-bottom: 0.5rem;
+  font-size: 0.75rem;
+  color: var(--cds-text-secondary, #525252);
+}
+
+.columnsList {
+  max-height: 22rem;
+  overflow-y: auto;
+}
+
+.columnsItem {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  min-height: 2rem;
+
+  :global(.cds--form-item) {
+    flex: 1;
+  }
+}
+
+.dragHandle {
+  flex-shrink: 0;
+  fill: var(--cds-icon-secondary, #525252);
+}
+
+.columnsMove {
+  display: flex;
+  flex-shrink: 0;
+}
+
+.columnsReset {
+  margin-top: 0.5rem;
+}
+
+/* Touch screens: headings and filter boxes get finger-sized targets. Rows stay
+   compact -- they are read, not tapped. Headings cannot be dragged on touch
+   (no native drag and drop), so reordering there is done from the Columns menu. */
+@media (pointer: coarse) {
+  .sortButton {
+    height: 2.5rem;
+  }
+
+  .filterRow th {
+    top: 2.5rem;
+  }
+
+  .filterInput {
+    height: 2rem;
+    font-size: 1rem; /* below 16px, iOS zooms the page on focus */
+  }
+}
+
+/* Phones: the search takes a line of its own, and the table leaves room for the
+   toolbar above it. */
+@media (max-width: 42rem) {
+  .search {
+    flex-basis: 100%;
+    max-width: none;
+  }
+
+  .scroll {
+    max-height: calc(100vh - 14rem);
+  }
+}

package/src/common/linelist-table/linelist-table.test.tsx

@@ -0,0 +1,120 @@
+import React from 'react';
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import LinelistTable from './linelist-table.component';
+import { type LinelistColumn } from './linelist-columns';
+import { downloadCsv } from '../report-register';
+
+jest.mock('../report-register', () => ({
+  ...jest.requireActual('../report-register'),
+  downloadCsv: jest.fn(),
+}));
+
+const columns: LinelistColumn[] = [
+  { header: 'Name', field: 'name' },
+  { header: 'Sex', field: 'sex' },
+  { header: 'Age', field: 'age' },
+];
+
+const rows = [
+  { name: 'Achieng', sex: 'F', age: 34 },
+  { name: 'Kiprop', sex: 'M', age: 9 },
+  { name: 'Wanjiru', sex: 'F', age: null },
+  { name: 'Otieno', sex: 'M', age: 41 },
+];
+
+const renderTable = () =>
+  render(<LinelistTable rows={rows} columns={columns} layoutKey="test" exportName="Test linelist" />);
+
+const headings = () =>
+  within(screen.getAllByRole('rowgroup')[0])
+    .getAllByRole('columnheader')
+    .map((cell) => cell.textContent);
+
+const names = () =>
+  within(screen.getAllByRole('rowgroup')[1])
+    .getAllByRole('row')
+    .map((row) => within(row).getAllByRole('cell')[1].textContent);
+
+describe('LinelistTable', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    jest.mocked(downloadCsv).mockClear();
+  });
+
+  it('lists every row under the configured columns', () => {
+    renderTable();
+
+    expect(headings()).toEqual(['#', 'Name', 'Sex', 'Age']);
+    expect(names()).toEqual(['Achieng', 'Kiprop', 'Wanjiru', 'Otieno']);
+    expect(screen.getByText('4 records')).toBeInTheDocument();
+  });
+
+  it('searches across columns', async () => {
+    renderTable();
+
+    await userEvent.type(screen.getByRole('searchbox', { name: /search the linelist/i }), 'kip');
+
+    expect(names()).toEqual(['Kiprop']);
+    expect(screen.getByText('1 of 4 records')).toBeInTheDocument();
+  });
+
+  it('filters by a single column', async () => {
+    renderTable();
+
+    await userEvent.click(screen.getByRole('button', { name: /filters/i }));
+    await userEvent.type(screen.getByRole('searchbox', { name: 'Filter Sex' }), 'm');
+
+    expect(names()).toEqual(['Kiprop', 'Otieno']);
+  });
+
+  it('sorts numerically, both ways, with blanks last', async () => {
+    renderTable();
+    const age = screen.getByRole('button', { name: /^age/i });
+
+    await userEvent.click(age);
+    expect(names()).toEqual(['Kiprop', 'Achieng', 'Otieno', 'Wanjiru']);
+
+    await userEvent.click(age);
+    expect(names()).toEqual(['Otieno', 'Achieng', 'Kiprop', 'Wanjiru']);
+
+    await userEvent.click(age);
+    expect(names()).toEqual(['Achieng', 'Kiprop', 'Wanjiru', 'Otieno']);
+  });
+
+  it('hides and reorders columns, and remembers the layout', async () => {
+    const { unmount } = renderTable();
+
+    await userEvent.click(screen.getByRole('button', { name: /^columns/i }));
+    await userEvent.click(screen.getByRole('checkbox', { name: 'Sex' }));
+    // Age is last in the menu; two steps left puts it before Name
+    await userEvent.click(screen.getAllByRole('button', { name: 'Move left' })[2]);
+    await userEvent.click(screen.getAllByRole('button', { name: 'Move left' })[1]);
+
+    expect(headings()).toEqual(['#', 'Age', 'Name']);
+
+    unmount();
+    renderTable();
+    expect(headings()).toEqual(['#', 'Age', 'Name']);
+
+    await userEvent.click(screen.getByRole('button', { name: /^columns/i }));
+    await userEvent.click(screen.getByRole('button', { name: /reset columns/i }));
+    expect(headings()).toEqual(['#', 'Name', 'Sex', 'Age']);
+  });
+
+  it('exports what is on screen: visible columns in order, filtered and sorted rows', async () => {
+    renderTable();
+
+    await userEvent.click(screen.getByRole('button', { name: /^columns/i }));
+    await userEvent.click(screen.getByRole('checkbox', { name: 'Sex' }));
+    await userEvent.type(screen.getByRole('searchbox', { name: /search the linelist/i }), 'o');
+    await userEvent.click(screen.getByRole('button', { name: /^age/i }));
+    await userEvent.click(screen.getByRole('button', { name: /export csv/i }));
+
+    const [csv, filename] = jest.mocked(downloadCsv).mock.calls[0];
+    expect(filename).toBe('test-linelist.csv');
+    // "o" matches Kiprop and Otieno; the hidden Sex column is neither searched nor exported
+    expect(csv.split('\r\n')).toEqual(['No,Name,Age', '1,Kiprop,9', '2,Otieno,41']);
+  });
+});

package/src/common/linelist-table/use-all-rows.ts

@@ -0,0 +1,93 @@
+import { useEffect, useRef, useState } from 'react';
+
+import { type PatientListPage } from '../../resources/patient-list-page';
+import { showReportError } from '../report-error';
+
+type Fetcher = (paging: { startIndex: number; limit: number }) => Promise<PatientListPage>;
+
+const BATCH_SIZE = 500;
+
+/* Figures of a total loaded at once, so a large total is not one long queue
+   yet the ETL server is not sent every figure's query together */
+const PARALLEL_FIGURES = 4;
+
+/**
+ * Every row of a linelist, fetched in batches.
+ *
+ * Sorting, filtering and export all have to see the whole list: sorting one
+ * server page of 50 would present the top of that page as the top of the list.
+ * A figure's linelist is one facility's clients for one month, so holding it
+ * in memory is cheap; only the page on screen is rendered.
+ *
+ * Given several fetchers -- a total made of separate figures -- they are read a
+ * few at a time, and their rows listed one figure after another.
+ */
+export function useAllRows(fetcher: Fetcher | Fetcher[], deps: React.DependencyList) {
+  const [rows, setRows] = useState<Array<Record<string, any>>>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [loadedCount, setLoadedCount] = useState(0);
+
+  /* A newer query supersedes one still loading, so its batches are discarded */
+  const request = useRef(0);
+
+  useEffect(() => {
+    const id = ++request.current;
+
+    setRows([]);
+    setLoadedCount(0);
+    setIsLoading(true);
+
+    (async () => {
+      const fetchers = Array.isArray(fetcher) ? fetcher : [fetcher];
+      /* each figure's rows kept apart, so the list keeps the figures' order */
+      const byFigure: Array<Array<Record<string, any>>> = fetchers.map(() => []);
+      let loaded = 0;
+      let next = 0;
+
+      const readFigure = async (index: number) => {
+        for (let startIndex = 0; ; startIndex += BATCH_SIZE) {
+          const page = await fetchers[index]({ startIndex, limit: BATCH_SIZE });
+
+          if (id !== request.current) {
+            return;
+          }
+
+          byFigure[index].push(...page.results);
+          loaded += page.results.length;
+          setLoadedCount(loaded);
+
+          if (page.results.length < BATCH_SIZE) {
+            return;
+          }
+        }
+      };
+
+      const worker = async () => {
+        while (next < fetchers.length && id === request.current) {
+          await readFigure(next++);
+        }
+      };
+
+      try {
+        await Promise.all(Array.from({ length: Math.min(PARALLEL_FIGURES, fetchers.length) }, worker));
+
+        if (id !== request.current) {
+          return;
+        }
+
+        setRows(byFigure.flat());
+      } catch (error) {
+        if (id === request.current) {
+          showReportError('the linelist', error);
+        }
+      } finally {
+        if (id === request.current) {
+          setIsLoading(false);
+        }
+      }
+    })();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps);
+
+  return { rows, isLoading, loadedCount };
+}

package/src/common/linelist-table/use-column-layout.ts

@@ -0,0 +1,123 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { type LinelistColumn } from './linelist-columns';
+
+interface ColumnLayout {
+  /** Column headers in display order */
+  order: string[];
+  hidden: string[];
+}
+
+const storageKeyFor = (key: string) => `ampath-linelist-layout:${key}`;
+
+function readLayout(key: string): ColumnLayout | null {
+  try {
+    const saved = JSON.parse(localStorage.getItem(storageKeyFor(key)) ?? 'null');
+    return saved && Array.isArray(saved.order) && Array.isArray(saved.hidden) ? saved : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeLayout(key: string, layout: ColumnLayout | null) {
+  try {
+    if (layout) {
+      localStorage.setItem(storageKeyFor(key), JSON.stringify(layout));
+    } else {
+      localStorage.removeItem(storageKeyFor(key));
+    }
+  } catch {
+    /* storage unavailable (private window, blocked site data): the layout just isn't remembered */
+  }
+}
+
+const defaultLayout = (columns: LinelistColumn[]): ColumnLayout => ({
+  order: columns.map((column) => column.header),
+  hidden: columns.filter((column) => column.hidden).map((column) => column.header),
+});
+
+/**
+ * The order and visibility of a linelist's columns, remembered per linelist in
+ * this browser.
+ *
+ * The saved layout is reconciled with the configured columns every time, so a
+ * column added to the configuration later still appears (at the end), and one
+ * removed from it is dropped from the layout rather than breaking it.
+ */
+export function useColumnLayout(columns: LinelistColumn[], storageKey: string) {
+  const [layout, setLayout] = useState<ColumnLayout>(() => readLayout(storageKey) ?? defaultLayout(columns));
+
+  useEffect(() => {
+    setLayout(readLayout(storageKey) ?? defaultLayout(columns));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [storageKey]);
+
+  const byHeader = useMemo(() => new Map(columns.map((column) => [column.header, column])), [columns]);
+
+  /** Every configured column, in the user's order */
+  const ordered = useMemo(() => {
+    const known = layout.order.filter((header) => byHeader.has(header));
+    const added = columns.map((column) => column.header).filter((header) => !known.includes(header));
+    return [...known, ...added].map((header) => byHeader.get(header)!);
+  }, [layout.order, byHeader, columns]);
+
+  const isVisible = useCallback((header: string) => !layout.hidden.includes(header), [layout.hidden]);
+  const visible = useMemo(() => ordered.filter((column) => isVisible(column.header)), [ordered, isVisible]);
+
+  const update = useCallback(
+    (next: ColumnLayout) => {
+      setLayout(next);
+      writeLayout(storageKey, next);
+    },
+    [storageKey],
+  );
+
+  const toggle = useCallback(
+    (header: string) => {
+      const hidden = layout.hidden.includes(header)
+        ? layout.hidden.filter((item) => item !== header)
+        : [...layout.hidden, header];
+      update({ order: ordered.map((column) => column.header), hidden });
+    },
+    [layout.hidden, ordered, update],
+  );
+
+  /** Moves `header` to where `target` is, shifting the columns between them */
+  const move = useCallback(
+    (header: string, target: string) => {
+      const order = ordered.map((column) => column.header).filter((item) => item !== header);
+      const at = order.indexOf(target);
+      if (at === -1 || header === target) {
+        return;
+      }
+      const from = ordered.findIndex((column) => column.header === header);
+      const to = ordered.findIndex((column) => column.header === target);
+      order.splice(from < to ? at + 1 : at, 0, header);
+      update({ order, hidden: layout.hidden });
+    },
+    [ordered, layout.hidden, update],
+  );
+
+  /** Moves a column one place left (-1) or right (1) */
+  const shift = useCallback(
+    (header: string, step: -1 | 1) => {
+      const index = ordered.findIndex((column) => column.header === header);
+      const target = ordered[index + step];
+      if (target) {
+        move(header, target.header);
+      }
+    },
+    [ordered, move],
+  );
+
+  const reset = useCallback(() => {
+    writeLayout(storageKey, null);
+    setLayout(defaultLayout(columns));
+  }, [storageKey, columns]);
+
+  const isCustomised =
+    JSON.stringify({ order: ordered.map((column) => column.header), hidden: layout.hidden }) !==
+    JSON.stringify(defaultLayout(columns));
+
+  return { ordered, visible, isVisible, toggle, move, shift, reset, isCustomised };
+}

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

@@ -0,0 +1 @@
+export * from './show-report-error';

package/src/common/report-error/show-report-error.ts

@@ -0,0 +1,25 @@
+import { showSnackbar } from '@openmrs/esm-framework';
+
+/**
+ * The single way a report reports a failure.
+ *
+ * Reports previously each rendered their own error markup driven by local
+ * state, which is easy to get wrong and easy to leave out. A snackbar keeps the
+ * report body showing whatever was last generated instead of replacing it, and
+ * behaves the same whether the failure came from the fetch, the ETL
+ * configuration or a malformed response.
+ */
+export function showReportError(reportName: string, error: unknown): void {
+  const message = error instanceof Error ? error.message : String(error);
+
+  // still worth a console entry: the snackbar is transient and truncates
+  console.error(`Failed to generate ${reportName}`, error);
+
+  showSnackbar({
+    kind: 'error',
+    title: `Could not generate ${reportName}`,
+    subtitle: message,
+    isLowContrast: false,
+    autoClose: false,
+  });
+}