@ampath/esm-dha-workflow-app 4.0.0-next.34 → 4.0.0-next.340

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;
+}

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

@@ -0,0 +1,90 @@
+import React from 'react';
+import { Button, Tag } from '@carbon/react';
+import { closeWorkspace, formatDate, parseDate } from '@openmrs/esm-framework';
+import { type VisitDiagnosis } from '../../types';
+import { RECORD_DETAILS_WORKSPACE } from '../shared/record-details.workspace';
+import styles from './claim-diagnosis-panel.component.scss';
+
+/** What the claim page states above this panel, so the panel doesn't restate it. */
+export interface DiagnosisClaimFacts {
+  memberNumber?: string;
+  patientNumber?: string;
+}
+
+interface ClaimDiagnosisPanelProps {
+  diagnosis: VisitDiagnosis;
+  claimFacts?: DiagnosisClaimFacts;
+}
+
+const sameValue = (a?: string | null, b?: string | null): boolean =>
+  (a ?? '').trim().toUpperCase() === (b ?? '').trim().toUpperCase();
+
+const asDate = (value?: string | null): string => {
+  const v = (value ?? '').trim();
+  if (!v) {
+    return '';
+  }
+  try {
+    return formatDate(parseDate(v));
+  } catch {
+    return v;
+  }
+};
+
+/**
+ * A diagnosis as the side panel shows it.
+ *
+ * A diagnosis carries little, so the work here is in what it doesn't show: the member
+ * number the claim above already names, and an intervention code that is only worth
+ * stating when it differs from the diagnosis' own. What it adds is the flag — whether the
+ * payer has marked this diagnosis for attention — which the card never surfaced at all.
+ */
+const ClaimDiagnosisPanel: React.FC<ClaimDiagnosisPanelProps> = ({ diagnosis, claimFacts }) => {
+  const recorded = asDate(diagnosis.recorded_on);
+
+  const facts = [
+    { label: 'Diagnosis code', value: diagnosis.diagnosis_code },
+    // The same code on both sides says nothing twice; only a differing one is a fact.
+    ...(sameValue(diagnosis.intervention_code, diagnosis.diagnosis_code)
+      ? []
+      : [{ label: 'Intervention code', value: diagnosis.intervention_code }]),
+    { label: 'Recorded', value: recorded },
+    ...(sameValue(diagnosis.patient_number, claimFacts?.memberNumber) ||
+    sameValue(diagnosis.patient_number, claimFacts?.patientNumber)
+      ? []
+      : [{ label: 'Member number', value: diagnosis.patient_number }]),
+  ].filter((fact) => Boolean((fact.value ?? '').trim()));
+
+  return (
+    <div className={styles.panel}>
+      {/* Only when it is set: a diagnosis not flagged is the norm and says nothing. */}
+      {diagnosis.is_flagged_diagnosis ? (
+        <div className={styles.flagRow}>
+          <Tag size="sm" type="red">
+            Flagged diagnosis
+          </Tag>
+        </div>
+      ) : null}
+
+      <dl className={styles.meta}>
+        {facts.map((fact) => (
+          <div key={fact.label}>
+            <dt>{fact.label}</dt>
+            <dd>{fact.value}</dd>
+          </div>
+        ))}
+      </dl>
+
+      {/* Held to the bottom of the panel. This panel is rendered from a record model
+          rather than as a child of the workspace, so it has no closeWorkspace prop to
+          call — it dismisses the panel by name instead. */}
+      <div className={styles.footer}>
+        <Button kind="secondary" size="sm" onClick={() => closeWorkspace(RECORD_DETAILS_WORKSPACE)}>
+          Close
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export default ClaimDiagnosisPanel;

package/src/billing/dashboard/v2/claim-visits/claim-doctors/claim-doctors.scss

@@ -0,0 +1,28 @@
+@use '../shared/empty-state' as empty;
+
+/* Plain names, run together — no chips, no avatars. */
+.doctors {
+  margin: 0;
+  font-size: 0.875rem;
+  line-height: 1.4;
+  color: #161616;
+  overflow-wrap: anywhere;
+}
+
+/* Compact inline note — doctors don't warrant a full empty-state tile. */
+.empty {
+  margin: 0;
+  font-size: 0.8125rem;
+  color: #6f6f6f;
+}
+
+/* Unless the claim can still be worked on, when the same gap is something to act on.
+   Shares its look with the diagnoses callout, which is rendered by a different component
+   entirely — see the partial. */
+.emptyDanger {
+  @include empty.blocking-callout;
+}
+
+.emptyDangerIcon {
+  @include empty.blocking-callout-icon;
+}

package/src/billing/dashboard/v2/claim-visits/claim-doctors/claim-doctors.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { WarningFilled } from '@carbon/react/icons';
+import { type ClaimDoctor } from '../../types';
+import styles from './claim-doctors.scss';
+
+interface claimDoctorsProps {
+  claimDoctors: ClaimDoctor[];
+  /** The claim can still be worked on, so a missing doctor is a gap to fill rather than
+      a record of what never happened. Colours the empty state to match the other
+      sections whose emptiness is holding the claim up. */
+  blocking?: boolean;
+}
+
+// A claim doctor carries nothing but a name, so the names are set as plain text — an
+// avatar and a pill around each said no more than the name already does.
+const ClaimDoctors: React.FC<claimDoctorsProps> = ({ claimDoctors, blocking }) => {
+  const names = (claimDoctors ?? []).map((cd) => (cd.doctor_name ?? '').trim()).filter(Boolean);
+
+  if (names.length === 0) {
+    if (blocking) {
+      return (
+        // `role="alert"` only here: a claim that is past being worked on has nothing to
+        // announce, and its empty state stays the quiet note below.
+        <p className={styles.emptyDanger} role="alert">
+          <WarningFilled size={20} className={styles.emptyDangerIcon} />
+          <span>No doctor recorded. One must be recorded before this claim can be submitted.</span>
+        </p>
+      );
+    }
+    return <p className={styles.empty}>No doctors on this claim.</p>;
+  }
+
+  return <p className={styles.doctors}>{names.join(', ')}</p>;
+};
+
+export default ClaimDoctors;

package/src/billing/dashboard/v2/claim-visits/claim-history/claim-history.component.scss

@@ -0,0 +1,119 @@
+/* Chips, not a track: nothing here claims one entry led to the next, only that each
+   happened. Being unordered, they can wrap — which is what keeps this section to two or
+   three lines however much the claim carries. */
+.history {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  min-width: 0;
+}
+
+/* The live one, leading, set apart from the settled facts below it. */
+.status {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.25rem 0.5rem;
+  min-width: 0;
+}
+
+/* Same micro-label as the claim's other headers, so the rail reads as one column. */
+.statusLabel {
+  font-size: 0.625rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+  color: #6f6f6f;
+  flex-shrink: 0;
+}
+
+.statusTag {
+  /* Carbon tags carry their own margin, which would knock the tag out of line with the
+     text beside it. */
+  margin: 0;
+}
+
+.statusNote {
+  font-size: 0.75rem;
+  color: #6f6f6f;
+  overflow-wrap: anywhere;
+}
+
+/* Pushed to the end of the status line so the caveat costs no line of its own. */
+.caveat {
+  margin-left: auto;
+}
+
+.caveatTrigger {
+  display: inline-flex;
+  align-items: center;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: #8d8d8d;
+  cursor: help;
+
+  &:hover,
+  &:focus-visible {
+    color: #525252;
+  }
+}
+
+.confirming {
+  min-height: 1.25rem;
+
+  :global(.cds--inline-loading__text) {
+    font-size: 0.75rem;
+    color: #6f6f6f;
+  }
+}
+
+.chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  min-width: 0;
+}
+
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.125rem 0.5rem 0.125rem 0.375rem;
+  border-radius: 0.75rem;
+  font-size: 0.75rem;
+  line-height: 1.34;
+  white-space: nowrap;
+  /* A long note — an authorisation status, say — gives up the nowrap rather than push
+     the row wider than the pane. */
+  max-width: 100%;
+  overflow: hidden;
+}
+
+.chipDone {
+  background: #defbe6;
+  color: #0e6027;
+}
+
+.chipWarning {
+  background: #fcf4d6;
+  color: #684e00;
+}
+
+.chipLabel {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* The qualifier — a count, a retry, an outcome — carried at a lower weight than the
+   fact it qualifies. */
+.chipNote {
+  padding-left: 0.25rem;
+  border-left: 1px solid currentColor;
+  opacity: 0.7;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}