@ampath/esm-dha-workflow-app 4.0.0-next.44 → 4.0.0-next.448

package/src/billing/dashboard/v2/cash-checklist/payment-drawer.component.scss

@@ -0,0 +1,246 @@
+@use '@carbon/layout';
+@use '@carbon/type';
+@use '@carbon/colors';
+@use '@openmrs/esm-styleguide/src/vars' as *;
+
+.overlay {
+  position: fixed;
+  inset: 0;
+  background-color: rgba(0, 0, 0, 0.5);
+  z-index: 8000;
+}
+
+.drawer {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 34rem;
+  max-width: 100%;
+  background-color: colors.$white;
+  z-index: 8001;
+  display: flex;
+  flex-direction: column;
+  box-shadow: -2px 0 8px rgba(0, 0, 0, 0.15);
+  animation: paymentDrawerIn 160ms ease-out;
+}
+
+@keyframes paymentDrawerIn {
+  from {
+    transform: translateX(100%);
+  }
+  to {
+    transform: translateX(0);
+  }
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: layout.$spacing-05;
+  border-bottom: 1px solid $ui-03;
+}
+
+.title {
+  @include type.type-style('heading-compact-02');
+  color: $ui-05;
+  margin: 0;
+}
+
+.subtitle {
+  @include type.type-style('label-01');
+  color: $text-02;
+}
+
+.close {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: $ui-05;
+  padding: layout.$spacing-02;
+
+  &:hover {
+    background-color: $ui-03;
+  }
+}
+
+.body {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  padding: layout.$spacing-06;
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-06;
+
+  /* Carbon reserves a helper/invalid-text row under each field; collapse it when
+     empty so fields sit closer together. */
+  :global(.cds--form-requirement:empty) {
+    display: none;
+  }
+}
+
+.itemName {
+  @include type.type-style('heading-compact-02');
+  color: $ui-05;
+}
+
+.summaryCard {
+  display: flex;
+  padding: layout.$spacing-05;
+  border: 1px solid $ui-03;
+  background-color: $ui-01;
+}
+
+.summaryItem {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-02;
+  flex: 1 1 0;
+  min-width: 0;
+
+  & + & {
+    padding-left: layout.$spacing-05;
+    border-left: 1px solid $ui-03;
+  }
+}
+
+.summaryLabel {
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+  color: $text-03;
+}
+
+.summaryValue {
+  @include type.type-style('heading-compact-01');
+  color: $ui-05;
+  font-variant-numeric: tabular-nums;
+}
+
+.summaryBalance {
+  color: colors.$red-60;
+}
+
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-06;
+  width: 100%;
+}
+
+.sectionLabel {
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+  font-weight: 700;
+  color: $text-02;
+  padding-bottom: layout.$spacing-03;
+  border-bottom: 1px solid $ui-03;
+  margin-bottom: -(layout.$spacing-02);
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: layout.$spacing-03;
+}
+
+.fieldLabel {
+  @include type.type-style('label-01');
+  color: $text-02;
+}
+
+.methodCard {
+  display: flex;
+  align-items: center;
+  gap: layout.$spacing-03;
+  padding: layout.$spacing-04 layout.$spacing-05;
+  border: 1px solid $ui-03;
+  background-color: $ui-01;
+}
+
+.methodDot {
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: 50%;
+  background-color: colors.$green-50;
+  flex-shrink: 0;
+}
+
+.methodCardText {
+  @include type.type-style('body-compact-01');
+  font-weight: 600;
+  color: $ui-05;
+}
+
+.methodCardSub {
+  @include type.type-style('label-01');
+  color: $text-03;
+  margin-left: auto;
+}
+
+.required {
+  color: colors.$red-60;
+  margin-left: 2px;
+}
+
+.methodNote {
+  @include type.type-style('body-compact-01');
+  color: $text-02;
+  margin: 0;
+}
+
+.divider {
+  border: none;
+  border-top: 1px solid $ui-03;
+  margin: 0;
+  width: 100%;
+}
+
+.newBalance {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: layout.$spacing-05;
+  padding: layout.$spacing-04 layout.$spacing-05;
+  border: 1px solid transparent;
+  @include type.type-style('label-01');
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+}
+
+.newBalanceValue {
+  @include type.type-style('heading-compact-02');
+  color: inherit;
+  font-variant-numeric: tabular-nums;
+  text-transform: none;
+  letter-spacing: 0;
+}
+
+/* Outstanding balance remaining */
+.newBalanceDue {
+  border-color: colors.$red-20;
+  background-color: colors.$red-10;
+  color: colors.$red-70;
+}
+
+/* Fully paid after this payment */
+.newBalanceClear {
+  border-color: colors.$green-30;
+  background-color: colors.$green-10;
+  color: colors.$green-70;
+}
+
+.footer {
+  display: flex;
+  border-top: 1px solid $ui-03;
+
+  :global(.cds--btn) {
+    flex: 1 1 50%;
+    max-width: none;
+  }
+}

package/src/billing/dashboard/v2/cash-checklist/payment-drawer.component.tsx

@@ -0,0 +1,182 @@
+import React, { useState } from 'react';
+import { Button, Dropdown, NumberInput, TextInput } from '@carbon/react';
+import { Close } from '@carbon/react/icons';
+import styles from './payment-drawer.component.scss';
+import { itemBalance, type BillLineItem, type BillSource, type PayInput, type PaymentMethod } from './cash-checklist.resource';
+
+const money = (n: number) => `KES ${n.toLocaleString('en-KE')}`;
+
+interface PaymentDrawerProps {
+  item: BillLineItem;
+  source: BillSource;
+  busy?: boolean;
+  onClose: () => void;
+  onSubmit: (input: PayInput) => void;
+}
+
+/** Side drawer to record a payment against a bill line item. Defaults to M-Pesa
+ *  (reference entered manually pre-integration); SHA copays may also settle via SHA. */
+const PaymentDrawer: React.FC<PaymentDrawerProps> = ({ item, source, busy, onClose, onSubmit }) => {
+  const balance = itemBalance(item);
+  const methods: PaymentMethod[] = source === 'SHA_COPAY' ? ['M-Pesa', 'SHA'] : ['M-Pesa'];
+  const [method, setMethod] = useState<PaymentMethod>('M-Pesa');
+  const [reference, setReference] = useState('');
+  const [amount, setAmount] = useState<number>(balance);
+  const [refError, setRefError] = useState('');
+  const [amtError, setAmtError] = useState('');
+
+  const amountValid = amount > 0 && amount <= balance;
+  const refValid = method !== 'M-Pesa' || reference.trim().length > 0;
+  const canSubmit = amountValid && refValid && !busy;
+  const newBalance = Math.max(0, balance - (amountValid ? amount : 0));
+
+  const handleAmount = (value: string | number) => {
+    const v = Number(value) || 0;
+    setAmount(v);
+    if (v <= 0) {
+      setAmtError('Enter an amount to pay.');
+    } else if (v > balance) {
+      setAmtError(`Amount cannot exceed the balance of ${money(balance)}.`);
+    } else {
+      setAmtError('');
+    }
+  };
+
+  const submit = () => {
+    if (!amountValid) {
+      setAmtError(amount <= 0 ? 'Enter an amount to pay.' : `Amount cannot exceed the balance of ${money(balance)}.`);
+    }
+    if (!refValid) {
+      setRefError('Enter the M-Pesa reference number.');
+    }
+    if (!amountValid || !refValid) {
+      return;
+    }
+    onSubmit({ amount, method, reference: method === 'M-Pesa' ? reference.trim() : undefined });
+  };
+
+  return (
+    <>
+      <div className={styles.overlay} onClick={onClose} />
+      <aside className={styles.drawer} role="dialog" aria-label="Record payment">
+        <header className={styles.header}>
+          <div>
+            <h5 className={styles.title}>Record payment</h5>
+            <span className={styles.subtitle}>{item.service}</span>
+          </div>
+          <button type="button" className={styles.close} onClick={onClose} aria-label="Close">
+            <Close size={20} />
+          </button>
+        </header>
+
+        <div className={styles.body}>
+          <div className={styles.summaryCard}>
+            <div className={styles.summaryItem}>
+              <span className={styles.summaryLabel}>Amount</span>
+              <span className={styles.summaryValue}>{money(item.amount)}</span>
+            </div>
+            <div className={styles.summaryItem}>
+              <span className={styles.summaryLabel}>Paid</span>
+              <span className={styles.summaryValue}>{money(item.paidAmount)}</span>
+            </div>
+            <div className={styles.summaryItem}>
+              <span className={styles.summaryLabel}>Balance</span>
+              <span className={`${styles.summaryValue} ${styles.summaryBalance}`}>{money(balance)}</span>
+            </div>
+          </div>
+
+          <div className={styles.form}>
+            <div className={styles.sectionLabel}>Payment</div>
+            {methods.length > 1 ? (
+              <Dropdown
+                id="pay-method"
+                titleText="Payment method"
+                label="Select method"
+                items={methods}
+                selectedItem={method}
+                onChange={({ selectedItem }) => {
+                  setMethod((selectedItem as PaymentMethod) ?? 'M-Pesa');
+                  setRefError('');
+                }}
+              />
+            ) : (
+              <div className={styles.field}>
+                <span className={styles.fieldLabel}>Payment method</span>
+                <div className={styles.methodCard}>
+                  <span className={styles.methodDot} />
+                  <span className={styles.methodCardText}>M-Pesa</span>
+                  <span className={styles.methodCardSub}>Mobile money</span>
+                </div>
+              </div>
+            )}
+
+            {method === 'M-Pesa' ? (
+              <TextInput
+                id="mpesa-ref"
+                labelText={
+                  <span>
+                    M-Pesa reference number<span className={styles.required}>*</span>
+                  </span>
+                }
+                placeholder="e.g. SGH7X1K2QP"
+                value={reference}
+                invalid={!!refError}
+                invalidText={refError}
+                onFocus={() => {
+                  if (!reference.trim()) {
+                    setRefError('M-Pesa reference number is required.');
+                  }
+                }}
+                onChange={(e) => {
+                  setReference(e.target.value);
+                  setRefError(e.target.value.trim() ? '' : 'M-Pesa reference number is required.');
+                }}
+              />
+            ) : (
+              <p className={styles.methodNote}>Settled against the patient&apos;s SHA cover.</p>
+            )}
+
+            <NumberInput
+              id="pay-amount"
+              label={
+                <span>
+                  Amount to pay (KES)<span className={styles.required}>*</span>
+                </span>
+              }
+              helperText={`Up to the balance of ${money(balance)}`}
+              min={0}
+              max={balance}
+              value={amount}
+              invalid={!!amtError}
+              invalidText={amtError}
+              onFocus={() => {
+                if (!amount || amount <= 0) {
+                  setAmtError('Amount to pay is required.');
+                }
+              }}
+              onChange={(_e, { value }) => handleAmount(value)}
+            />
+
+            <hr className={styles.divider} />
+
+            <div className={`${styles.newBalance} ${newBalance > 0 ? styles.newBalanceDue : styles.newBalanceClear}`}>
+              <span>{newBalance > 0 ? 'Balance after payment' : 'Fully paid after payment'}</span>
+              <span className={styles.newBalanceValue}>{money(newBalance)}</span>
+            </div>
+          </div>
+        </div>
+
+        <footer className={styles.footer}>
+          <Button kind="secondary" onClick={onClose}>
+            Cancel
+          </Button>
+          <Button kind="primary" disabled={!canSubmit} onClick={submit}>
+            {busy ? 'Recording…' : 'Record payment'}
+          </Button>
+        </footer>
+      </aside>
+    </>
+  );
+};
+
+export default PaymentDrawer;

package/src/billing/dashboard/v2/claim-statuses.ts

@@ -0,0 +1,143 @@
+/**
+ * Provider claim statuses, grouped the way the HIE documents them.
+ * https://hie-docs.dha.go.ke/docs/claims/guides/understandingClaimStatuses
+ *
+ * Only the provider claim's two fields are modelled here — `workflow_state` (where the
+ * claim is in its lifecycle) and `claim_auth_status` (whether the visit itself is
+ * authorised). The payer-side outcomes (PAID, APPROVED, REJECTED…) live on the payer
+ * claim, which this app never fetches, so nothing here should be read as a financial
+ * result.
+ */
+
+/** Phase 1 — Preparation. The claim has not yet left our system. */
+export const PREPARATION_STATES = [
+  'DRAFT',
+  'PENDING',
+  'SUBMISSION_READY',
+  'ON_HOLD',
+  'TIME_BARRED',
+] as const;
+
+/** Phase 2 — Submission & dispatch. The hand-off to the payer. */
+export const SUBMISSION_STATES = ['SUBMITTED', 'DISPATCHED', 'FAILED_TO_SUBMIT'] as const;
+
+/** Phase 3 — Payer processing & feedback, including the states handed back to us. */
+export const PAYER_STATES = [
+  'SUBMITTED_PAYER',
+  'AUTOMATIC_CHECKS_DONE',
+  'DRAFT_RESUBMIT',
+  'DRAFT_RESUBMIT_DOCUMENTS',
+] as const;
+
+/** Phase 4 — Final outcomes. */
+export const FINAL_STATES = ['CLOSED'] as const;
+
+export type ClaimWorkflowPhase = 'preparation' | 'submission' | 'payer' | 'final' | 'unknown';
+
+const normalise = (value?: string): string => (value ?? '').trim().toUpperCase();
+
+const PHASE_BY_STATE = new Map<string, ClaimWorkflowPhase>([
+  ...PREPARATION_STATES.map((s) => [s, 'preparation'] as const),
+  ...SUBMISSION_STATES.map((s) => [s, 'submission'] as const),
+  ...PAYER_STATES.map((s) => [s, 'payer'] as const),
+  ...FINAL_STATES.map((s) => [s, 'final'] as const),
+]);
+
+export function getClaimWorkflowPhase(workflowState?: string): ClaimWorkflowPhase {
+  return PHASE_BY_STATE.get(normalise(workflowState)) ?? 'unknown';
+}
+
+/**
+ * States in which the claim's clinical content — billing lines and diagnoses — can
+ * still be changed.
+ *
+ * DRAFT is the obvious one. DRAFT_RESUBMIT matters just as much: it is the state a
+ * claim enters when it has been pulled back to answer a payer clarification, and the
+ * docs describe it as editable. Treating only DRAFT as open would lock the very claims
+ * that were handed back to be corrected.
+ */
+const CONTENT_EDITABLE_STATES = new Set<string>(['DRAFT', 'DRAFT_RESUBMIT']);
+
+/**
+ * States that accept attachments. A superset of the above: DRAFT_RESUBMIT_DOCUMENTS
+ * exists specifically so missing documents can be supplied, without reopening the
+ * lines and diagnoses.
+ */
+const DOCUMENT_EDITABLE_STATES = new Set<string>([...CONTENT_EDITABLE_STATES, 'DRAFT_RESUBMIT_DOCUMENTS']);
+
+/**
+ * Whether billing lines and diagnoses can still be added to this claim.
+ *
+ * An unrecognised or empty state answers `false`. Callers should already be holding
+ * back while the claim is still loading; once it has arrived, a state we cannot place
+ * is not a licence to offer writes the payer will refuse.
+ */
+export function canEditClaimContent(workflowState?: string): boolean {
+  return CONTENT_EDITABLE_STATES.has(normalise(workflowState));
+}
+
+/** Whether attachments can still be added to this claim. */
+export function canEditClaimDocuments(workflowState?: string): boolean {
+  return DOCUMENT_EDITABLE_STATES.has(normalise(workflowState));
+}
+
+/** Whether the claim can still be submitted or closed from here. */
+export function canDispatchClaim(workflowState?: string): boolean {
+  const state = normalise(workflowState);
+  return CONTENT_EDITABLE_STATES.has(state) || state === 'SUBMISSION_READY' || state === 'FAILED_TO_SUBMIT';
+}
+
+/**
+ * Tag colour for any claim, invoice, dispatch or authorisation status.
+ *
+ * green   settled and healthy — authorised, checked, dispatched, paid
+ * red     needs attention — rejected, expired, timed out, failed
+ * blue    in flight — being prepared, submitted, or awaiting a payer decision
+ * gray    dormant — closed, held, or a status we don't recognise
+ */
+export function claimStatusTagType(value?: string): 'green' | 'red' | 'blue' | 'gray' {
+  switch (normalise(value)) {
+    // Healthy, settled states.
+    case 'AUTHORIZED':
+    case 'AUTHORIZED_PENDING_VISIT':
+    case 'AUTHORIZED_MULTISESSION':
+    case 'EMERGENCY_AUTHORIZED':
+    case 'AUTOMATIC_CHECKS_DONE':
+    case 'DISPATCHED':
+    case 'APPROVED':
+    case 'PAID':
+    case 'VALID':
+      return 'green';
+
+    // Problem states needing someone to act.
+    case 'REJECTED':
+    case 'EXPIRED':
+    case 'FAILED_TO_SUBMIT':
+    case 'FAILED':
+    case 'TIME_BARRED':
+    case 'INVALID':
+    case 'CANCELLED':
+      return 'red';
+
+    // In flight, nothing to do but wait or finish preparing.
+    case 'DRAFT':
+    case 'PENDING':
+    case 'SUBMISSION_READY':
+    case 'SUBMITTED':
+    case 'SUBMITTED_PAYER':
+    case 'SUBMITTED_CLAIM':
+    case 'DRAFT_RESUBMIT':
+    case 'DRAFT_RESUBMIT_DOCUMENTS':
+      return 'blue';
+
+    // Dormant: CLOSED, ON_HOLD and anything unrecognised.
+    default:
+      return 'gray';
+  }
+}
+
+/** "DRAFT_RESUBMIT" -> "Draft resubmit", for display beside the raw code. */
+export function humaniseClaimStatus(value?: string): string {
+  const spaced = normalise(value).replace(/_/g, ' ').trim().toLowerCase();
+  return spaced ? spaced.charAt(0).toUpperCase() + spaced.slice(1) : '';
+}

package/src/billing/dashboard/v2/claim-visits/claim-diagnosis-details/claim-diagnosis-details.component.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { type VisitDiagnosis } from '../../types';
+import { formatDate, parseDate } from '@openmrs/esm-framework';
+import RecordCards, { type RecordCardModel } from '../shared/record-cards.component';
+import ClaimDiagnosisPanel, { type DiagnosisClaimFacts } from './claim-diagnosis-panel.component';
+
+interface claimDiagnosisDetailsProps {
+  claimDiagnosiss: VisitDiagnosis[];
+}
+
+// Builder so the cards can be merged into a shared grid with the doctors.
+export function buildDiagnosisRecords(
+  claimDiagnosiss: VisitDiagnosis[],
+  /** What the claim page states above the panel, so the panel doesn't restate it. */
+  claimFacts?: DiagnosisClaimFacts,
+): RecordCardModel[] {
+  return (claimDiagnosiss ?? []).map((cd) => ({
+    tone: 'green',
+    kind: 'Diagnosis',
+    title: cd.diagnosis_name,
+    // How the side panel renders this diagnosis, in place of the generic field grid.
+    panel: <ClaimDiagnosisPanel diagnosis={cd} claimFacts={claimFacts} />,
+    fields: [
+      { label: 'Recorded on', value: cd.recorded_on ? formatDate(parseDate(cd.recorded_on)) : '' },
+      { label: 'Diagnosis code', value: cd.diagnosis_code },
+      { label: 'Intervention code', value: cd.intervention_code },
+    ],
+  }));
+}
+
+const ClaimDiagnosisDetails: React.FC<claimDiagnosisDetailsProps> = ({ claimDiagnosiss }) => (
+  <RecordCards records={buildDiagnosisRecords(claimDiagnosiss)} emptyMessage="No diagnosis data." layout="grid" />
+);
+
+export default ClaimDiagnosisDetails;

package/src/billing/dashboard/v2/claim-visits/claim-diagnosis-details/claim-diagnosis-panel.component.scss

@@ -0,0 +1,67 @@
+/* Fills the workspace body so the footer can be held to the bottom — a diagnosis carries
+   little, so without this the buttons would float just under a line or two of text. */
+.panel {
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+  min-height: 100%;
+}
+
+.flagRow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+
+  /* Carbon tags carry their own margin, which would knock them out of alignment. */
+  :global(.cds--tag) {
+    margin: 0;
+  }
+}
+
+/* The diagnosis' particulars, in columns, stepping down to fewer on a narrow panel. */
+.meta {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(9rem, 1fr));
+  gap: 0.75rem 1.5rem;
+  margin: 0;
+
+  div {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    min-width: 0;
+  }
+
+  dt {
+    font-size: 0.625rem;
+    font-weight: 700;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: #6f6f6f;
+  }
+
+  dd {
+    margin: 0;
+    font-size: 0.875rem;
+    line-height: 1.35;
+    color: #161616;
+    overflow-wrap: anywhere;
+  }
+}
+
+/* ---- Footer ---- */
+/* margin-top:auto drops it to the bottom of the panel; sticky keeps it there if the
+   content ever outgrows the view. The negative margins bleed it over the panel's own
+   padding, so it spans the width. */
+.footer {
+  position: sticky;
+  bottom: 0;
+  z-index: 1;
+  margin: auto -1rem -1rem;
+  padding: 0.5rem 1rem;
+  display: flex;
+  justify-content: flex-start;
+  gap: 0.5rem;
+  background-color: #ffffff;
+  border-top: 1px solid #e0e0e0;
+}