@openmrs/esm-billing-app 1.1.2-pre.8 → 1.2.0

package/src/refunds/admin/refund-requests.test.tsx

@@ -0,0 +1,99 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { showModal } from '@openmrs/esm-framework';
+import RefundRequests from './refund-requests.component';
+import { useRefundRequests } from '../refunds.resource';
+import { RefundStatus } from '../../types';
+
+vi.mock('@openmrs/esm-framework', () => ({
+  showModal: vi.fn(),
+  useConfig: () => ({ defaultCurrency: 'USD', pageSize: 10 }),
+  formatDate: () => 'date',
+  parseDate: (s: string) => new Date(s),
+  restBaseUrl: '/ws/rest/v1',
+  useLayoutType: () => 'small-desktop',
+  isDesktop: () => true,
+  usePagination: <T,>(items: T[]) => ({
+    paginated: (items?.length ?? 0) > 10,
+    goTo: vi.fn(),
+    results: items ?? [],
+    currentPage: 1,
+  }),
+  usePaginationInfo: () => ({ pageSizes: [10, 20, 30, 40, 50] }),
+  EmptyCardIllustration: () => null,
+  ErrorState: ({ headerTitle }: { headerTitle: string }) => <div>{headerTitle} error</div>,
+}));
+
+globalThis.i18next = { language: 'en-US' } as any;
+vi.mock('../refunds.resource');
+
+const sampleBill = {
+  uuid: 'b1',
+  receiptNumber: 'INV-1',
+  status: 'PAID',
+  total: 5000,
+  amountAfterDiscount: 5000,
+  dateCreated: '2026-05-21T00:00:00.000+0000',
+  patient: { display: '10001V - Jane Doe' },
+  cashier: { display: 'cashier' },
+  refunds: [{ uuid: 'r1', status: RefundStatus.REQUESTED, voided: false }],
+};
+
+beforeEach(() => vi.clearAllMocks());
+
+describe('RefundRequests page', () => {
+  it('renders empty state when no bills match', () => {
+    vi.mocked(useRefundRequests).mockReturnValue({
+      bills: [],
+      isLoading: false,
+      error: null,
+      mutate: vi.fn(),
+    } as any);
+    render(<RefundRequests />);
+    expect(screen.getByText(/no refund requests to display/i)).toBeInTheDocument();
+  });
+
+  it('lists one row per bill', () => {
+    vi.mocked(useRefundRequests).mockReturnValue({
+      bills: [sampleBill],
+      isLoading: false,
+      error: null,
+      mutate: vi.fn(),
+    } as any);
+    render(<RefundRequests />);
+    expect(screen.getByText(/INV-1/)).toBeInTheDocument();
+    expect(screen.getByText(/10001V - Jane Doe/)).toBeInTheDocument();
+  });
+
+  it('opens review modal on row click', async () => {
+    vi.mocked(useRefundRequests).mockReturnValue({
+      bills: [sampleBill],
+      isLoading: false,
+      error: null,
+      mutate: vi.fn(),
+    } as any);
+    const user = userEvent.setup();
+    render(<RefundRequests />);
+    await user.click(screen.getByText(/INV-1/));
+    expect(showModal).toHaveBeenCalledWith(
+      'review-bill-refunds-modal',
+      expect.objectContaining({ bill: expect.objectContaining({ uuid: 'b1' }) }),
+    );
+  });
+
+  it('changes status filter', async () => {
+    vi.mocked(useRefundRequests).mockReturnValue({
+      bills: [],
+      isLoading: false,
+      error: null,
+      mutate: vi.fn(),
+    } as any);
+    const user = userEvent.setup();
+    render(<RefundRequests />);
+    await user.click(screen.getByRole('combobox'));
+    await user.click(screen.getByText(/approved/i));
+    expect(vi.mocked(useRefundRequests).mock.calls.at(-1)?.[0].statuses).toEqual([RefundStatus.APPROVED]);
+  });
+});

package/src/refunds/admin/review-bill-refunds/bill-line-items-table/bill-line-items-table.component.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { useConfig } from '@openmrs/esm-framework';
+import type { BillingConfig } from '../../../../config-schema';
+import { convertToCurrency } from '../../../../helpers';
+import type { LineItem } from '../../../../types';
+import styles from './bill-line-items-table.scss';
+
+interface Props {
+  lineItems: Array<LineItem>;
+}
+
+const BillLineItemsTable: React.FC<Props> = ({ lineItems }) => {
+  const { t } = useTranslation();
+  const { defaultCurrency } = useConfig<BillingConfig>();
+
+  return (
+    <section className={styles.ledger}>
+      <h3 className={styles.ledgerHeading}>{t('lineItems', 'Line items')}</h3>
+      <table className={styles.ledgerTable}>
+        <thead>
+          <tr>
+            <th>{t('item', 'Item')}</th>
+            <th>{t('qty', 'Qty')}</th>
+            <th className={styles.right}>{t('price', 'Price')}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {lineItems.map((li: LineItem, idx: number) => (
+            <tr key={li.uuid ?? idx}>
+              <td className={styles.itemName}>{li.item || li.billableService || '--'}</td>
+              <td>{li.quantity}</td>
+              <td className={styles.right}>{convertToCurrency(li.price ?? 0, defaultCurrency)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+};
+
+export default BillLineItemsTable;

package/src/refunds/admin/review-bill-refunds/bill-line-items-table/bill-line-items-table.scss

@@ -0,0 +1,76 @@
+@use '@carbon/styles/scss/spacing' as *;
+@use '@carbon/styles/scss/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.ledger {
+  margin-bottom: $spacing-05;
+}
+
+.ledgerHeading {
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--cds-text-helper);
+  margin: 0 0 $spacing-03;
+}
+
+.ledgerTable {
+  width: 100%;
+  border-collapse: collapse;
+  @include type.type-style('body-compact-01');
+}
+
+.ledgerTable thead th {
+  text-align: left;
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--cds-text-helper);
+  font-weight: 500;
+  padding: $spacing-02 0;
+  border-bottom: 1px solid $ui-03;
+}
+
+.ledgerTable tbody td {
+  padding: $spacing-03 0;
+  border-bottom: 1px dashed $ui-03;
+  color: var(--cds-text-secondary);
+  font-variant-numeric: tabular-nums;
+}
+
+.ledgerTable tbody tr:last-child td {
+  border-bottom: 0;
+}
+
+.center {
+  text-align: center;
+  width: 36px;
+}
+
+.right {
+  text-align: right;
+}
+
+.itemName {
+  color: var(--cds-text-primary);
+}
+
+.ref {
+  display: inline-block;
+  min-width: 20px;
+  height: 20px;
+  padding: 0 $spacing-02;
+  background: $ui-02;
+  border: 1px solid $color-gray-30;
+  @include type.type-style('code-01');
+  font-weight: 500;
+  text-align: center;
+  line-height: 18px;
+  color: var(--cds-text-secondary);
+}
+
+.refSolid {
+  background: $ui-05;
+  border-color: $ui-05;
+  color: $ui-02;
+}

package/src/refunds/admin/review-bill-refunds/bill-payments-table/bill-payments-table.component.tsx

@@ -0,0 +1,50 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { formatDate, useConfig } from '@openmrs/esm-framework';
+import type { BillingConfig } from '../../../../config-schema';
+import { convertToCurrency } from '../../../../helpers';
+import type { Payment } from '../../../../types';
+import styles from './bill-payments-table.scss';
+
+interface Props {
+  payments: Array<Payment>;
+}
+
+const BillPaymentsTable: React.FC<Props> = ({ payments }) => {
+  const { t } = useTranslation();
+  const { defaultCurrency } = useConfig<BillingConfig>();
+
+  if (payments.length === 0) return null;
+
+  return (
+    <section className={styles.ledger}>
+      <h3 className={styles.ledgerHeading}>{t('payments', 'Payments')}</h3>
+      <table className={styles.ledgerTable}>
+        <thead>
+          <tr>
+            <th>{t('method', 'Method')}</th>
+            <th>{t('date', 'Date')}</th>
+            <th className={styles.right}>{t('tendered', 'Tendered')}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {payments.map((p: Payment) => (
+            <tr key={p.uuid}>
+              <td>
+                <span className={styles.paymentKind}>{p.instanceType?.name ?? '--'}</span>
+              </td>
+              <td>
+                <span className={styles.paymentDate}>
+                  {p.dateCreated ? formatDate(new Date(p.dateCreated), { mode: 'wide' }) : '--'}
+                </span>
+              </td>
+              <td className={styles.right}>{convertToCurrency(p.amountTendered ?? 0, defaultCurrency)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+};
+
+export default BillPaymentsTable;

package/src/refunds/admin/review-bill-refunds/bill-payments-table/bill-payments-table.scss

@@ -0,0 +1,63 @@
+@use '@carbon/styles/scss/spacing' as *;
+@use '@carbon/styles/scss/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.ledger {
+  margin-bottom: $spacing-05;
+}
+
+.ledgerHeading {
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--cds-text-helper);
+  margin: 0 0 $spacing-03;
+}
+
+.ledgerTable {
+  width: 100%;
+  border-collapse: collapse;
+  @include type.type-style('body-compact-01');
+}
+
+.ledgerTable thead th {
+  text-align: left;
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--cds-text-helper);
+  font-weight: 500;
+  padding: $spacing-02 0;
+  border-bottom: 1px solid $ui-03;
+}
+
+.ledgerTable tbody td {
+  padding: $spacing-03 0;
+  border-bottom: 1px dashed $ui-03;
+  color: var(--cds-text-secondary);
+  font-variant-numeric: tabular-nums;
+}
+
+.ledgerTable tbody tr:last-child td {
+  border-bottom: 0;
+}
+
+.right {
+  text-align: right;
+}
+
+.paymentKind {
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--cds-text-helper);
+  padding: 2px $spacing-02;
+  background: $ui-02;
+  border: 1px solid $ui-03;
+  display: inline-block;
+}
+
+.paymentDate {
+  @include type.type-style('label-01');
+  color: var(--cds-text-helper);
+}

package/src/refunds/admin/review-bill-refunds/bill-receipt-rail/bill-receipt-rail.component.tsx

@@ -0,0 +1,84 @@
+import React from 'react';
+import { Tag } from '@carbon/react';
+import { useTranslation } from 'react-i18next';
+import { formatDate, parseDate } from '@openmrs/esm-framework';
+import BillLineItemsTable from '../bill-line-items-table/bill-line-items-table.component';
+import BillPaymentsTable from '../bill-payments-table/bill-payments-table.component';
+import BillTotalsSummary from '../bill-totals-summary/bill-totals-summary.component';
+import type { BillRefund, LineItem, PatientInvoice, Payment } from '../../../../types';
+import styles from './bill-receipt-rail.scss';
+
+interface Props {
+  bill: PatientInvoice;
+  lineItems: Array<LineItem>;
+  payments: Array<Payment>;
+  paymentsTotal: number;
+  subtotal: number;
+  totalApprovedRefunds: number;
+  approvedRefunds: BillRefund[];
+  completedRefunds: BillRefund[];
+  totalCompletedRefunds: number;
+}
+
+/**
+ * DO NOT DELETE — BillStatus values for translation.
+ * t('adjusted', 'Adjusted')
+ * t('paid', 'Paid')
+ * t('partially_refunded', 'Partially refunded')
+ * t('pending', 'Pending')
+ * t('posted', 'Posted')
+ * t('refunded', 'Refunded')
+ * t('refund_requested', 'Refund requested')
+ */
+
+const BillReceiptRail: React.FC<Props> = ({
+  bill,
+  lineItems,
+  payments,
+  paymentsTotal,
+  subtotal,
+  totalApprovedRefunds,
+  approvedRefunds,
+  completedRefunds,
+  totalCompletedRefunds,
+}) => {
+  const { t } = useTranslation();
+
+  return (
+    <aside className={styles.receipt}>
+      <div className={styles.patient}>
+        <div>
+          <p className={styles.patientName}>{bill.patient?.display}</p>
+          <p className={styles.patientId}>
+            {t('receiptNumber', 'Receipt #')}: {bill.receiptNumber}
+          </p>
+        </div>
+        {bill.status && (
+          <Tag type="blue" size="sm">
+            {t(String(bill.status).toLowerCase(), String(bill.status))}
+          </Tag>
+        )}
+      </div>
+
+      <dl className={styles.meta}>
+        <dt>{t('issued', 'Issued')}</dt>
+        <dd>{bill.dateCreated ? formatDate(parseDate(bill.dateCreated), { mode: 'wide' }) : '--'}</dd>
+        <dt>{t('cashier', 'Cashier')}</dt>
+        <dd>{bill.cashier?.display ?? '--'}</dd>
+      </dl>
+
+      <BillLineItemsTable lineItems={lineItems} />
+      <BillPaymentsTable payments={payments} />
+      <BillTotalsSummary
+        subtotal={subtotal}
+        paymentsTotal={paymentsTotal}
+        totalApprovedRefunds={totalApprovedRefunds}
+        approvedRefunds={approvedRefunds}
+        completedRefunds={completedRefunds}
+        totalCompletedRefunds={totalCompletedRefunds}
+      />
+    </aside>
+  );
+};
+
+export default React.memo(BillReceiptRail);

package/src/refunds/admin/review-bill-refunds/bill-receipt-rail/bill-receipt-rail.scss

@@ -0,0 +1,54 @@
+@use '@carbon/styles/scss/spacing' as *;
+@use '@carbon/styles/scss/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.receipt {
+    border-right: 1px solid $ui-03;
+    background: $ui-01;
+    padding: $spacing-06 $spacing-06 $spacing-07;
+}
+
+.patient {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: $spacing-03;
+    margin-bottom: $spacing-04;
+}
+
+.patientName {
+    @include type.type-style('heading-03');
+    margin: 0 0 $spacing-01;
+    color: var(--cds-text-primary);
+}
+
+.patientId {
+    @include type.type-style('code-01');
+    color: var(--cds-text-helper);
+    margin: 0;
+}
+
+.meta {
+    display: grid;
+    grid-template-columns: max-content 1fr;
+    gap: $spacing-02 $spacing-05;
+    padding: $spacing-04 0;
+    border-top: 1px solid $ui-03;
+    border-bottom: 1px solid $ui-03;
+    margin: 0 0 $spacing-05;
+}
+
+.meta dt {
+    @include type.type-style('label-01');
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--cds-text-helper);
+    margin: 0;
+}
+
+.meta dd {
+    @include type.type-style('body-compact-01');
+    color: var(--cds-text-primary);
+    margin: 0;
+    font-variant-numeric: tabular-nums;
+}

package/src/refunds/admin/review-bill-refunds/bill-totals-summary/bill-totals-summary.component.tsx

@@ -0,0 +1,83 @@
+import React from 'react';
+import classNames from 'classnames';
+import { useTranslation } from 'react-i18next';
+import { useConfig } from '@openmrs/esm-framework';
+import { convertToCurrency } from '../../../../helpers';
+import type { BillingConfig } from '../../../../config-schema';
+import type { BillRefund } from '../../../../types';
+import styles from './bill-totals-summary.scss';
+
+interface Props {
+  subtotal: number;
+  paymentsTotal: number;
+  totalApprovedRefunds: number;
+  approvedRefunds: BillRefund[];
+  completedRefunds: BillRefund[];
+  totalCompletedRefunds: number;
+}
+
+const BillTotalsSummary: React.FC<Props> = ({
+  subtotal,
+  paymentsTotal,
+  totalApprovedRefunds,
+  approvedRefunds,
+  completedRefunds,
+  totalCompletedRefunds,
+}) => {
+  const { t } = useTranslation();
+  const { defaultCurrency } = useConfig<BillingConfig>();
+
+  return (
+    <section className={styles.totals}>
+      <div className={classNames(styles.totalsRow, styles.totalsSubtotal)}>
+        <span>{t('billTotal', 'Bill total')}</span>
+        <span>{convertToCurrency(subtotal, defaultCurrency)}</span>
+      </div>
+
+      <div className={classNames(styles.totalsRow, styles.totalsRowAdd)}>
+        <span>{t('totalPaid', 'Total paid')}</span>
+        <span>{convertToCurrency(paymentsTotal, defaultCurrency)}</span>
+      </div>
+
+      {completedRefunds.length > 0 && (
+        <>
+          <hr className={styles.totalsRule} />
+          {completedRefunds.map((r) => (
+            <div key={r.uuid} className={classNames(styles.totalsRow, styles.totalsRowAdd)}>
+              <span>✓ {t('refundPaidOut', 'Refund paid out')}</span>
+              <span>{convertToCurrency(r.refundAmount, defaultCurrency)}</span>
+            </div>
+          ))}
+          <hr className={styles.totalsRuleStrong} />
+          <div className={classNames(styles.totalsRow, styles.totalsOutstanding)}>
+            <span>{t('totalRefunded', 'Total refunded')}</span>
+            <span className={styles.totalsOutstandingAmount}>
+              {convertToCurrency(totalCompletedRefunds, defaultCurrency)}
+            </span>
+          </div>
+        </>
+      )}
+
+      {approvedRefunds.length > 0 && (
+        <>
+          <hr className={styles.totalsRule} />
+          {approvedRefunds.map((r) => (
+            <div key={r.uuid} className={classNames(styles.totalsRow, styles.totalsRowMinus)}>
+              <span>↑ {t('approvedRefundPendingPayout', 'Approved refund (pending payout)')}</span>
+              <span>{convertToCurrency(r.refundAmount, defaultCurrency)}</span>
+            </div>
+          ))}
+          <hr className={styles.totalsRuleStrong} />
+          <div className={classNames(styles.totalsRow, styles.totalsOutstanding)}>
+            <span>{t('totalPendingPayout', 'Total pending payout')}</span>
+            <span className={styles.totalsOutstandingAmount}>
+              {convertToCurrency(totalApprovedRefunds, defaultCurrency)}
+            </span>
+          </div>
+        </>
+      )}
+    </section>
+  );
+};
+
+export default BillTotalsSummary;

package/src/refunds/admin/review-bill-refunds/bill-totals-summary/bill-totals-summary.scss

@@ -0,0 +1,65 @@
+@use '@carbon/styles/scss/spacing' as *;
+@use '@carbon/styles/scss/type';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.totals {
+    @include type.type-style('body-compact-01');
+}
+
+.totalsRow {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    padding: $spacing-02 0;
+    font-variant-numeric: tabular-nums;
+}
+
+.totalsRow span:first-child {
+    color: var(--cds-text-secondary);
+}
+
+.totalsSubtotal span:first-child {
+    @include type.type-style('label-01');
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--cds-text-secondary);
+}
+
+.totalsRowMinus,
+.totalsRowMinus span:first-child {
+    color: $danger;
+}
+
+.totalsRowAdd,
+.totalsRowAdd span:first-child {
+    color: $support-02;
+}
+
+.totalsRule {
+    border: 0;
+    border-top: 1px solid $ui-03;
+    margin: $spacing-02 0 $spacing-01;
+}
+
+.totalsRuleStrong {
+    border: 0;
+    border-top: 1px solid $ui-05;
+    margin: $spacing-03 0 $spacing-02;
+}
+
+.totalsOutstanding {
+    padding: $spacing-03 0 $spacing-02;
+}
+
+.totalsOutstanding span:first-child {
+    @include type.type-style('label-01');
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--cds-text-primary);
+}
+
+.totalsOutstandingAmount {
+    @include type.type-style('heading-05');
+    color: var(--cds-text-primary);
+    letter-spacing: -0.015em;
+}