@kenyaemr/esm-pcs-app 5.4.5-pre.1092

package/src/linked/linked-participant.component.test.tsx

@@ -0,0 +1,134 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { launchWorkspace2 } from '@openmrs/esm-framework';
+import LinkedParticipant from './linked-participant.component';
+import { usePcsDependants, usePcsParticipant } from '../resources/pcs.resource';
+import { type PcsParticipant } from '../types';
+
+vi.mock('@openmrs/esm-framework', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@openmrs/esm-framework')>()),
+  launchWorkspace2: vi.fn(),
+  showModal: vi.fn(),
+  useConfig: () => ({
+    pcsAttributeTypes: { pbidsEnrollmentStatus: 'pbids-attr', cardseEnrollmentStatus: 'cardse-attr' },
+  }),
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (_key: string, fallback: string) => fallback }),
+}));
+
+vi.mock('../resources/pcs.resource', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../resources/pcs.resource')>()),
+  usePcsParticipant: vi.fn(),
+  usePcsDependants: vi.fn(),
+}));
+
+vi.mock('../resources/link-participant.resource', () => ({
+  useSyncStudyAttributes: () => ({ syncNow: vi.fn() }),
+}));
+
+vi.mock('./use-study-sync-snackbars', () => ({
+  useStudySyncSnackbars: () => ({ onSynced: vi.fn(), onSyncError: vi.fn() }),
+}));
+
+// The panels are exercised by their own tests; here they would only add mocking noise.
+vi.mock('./participant-details.component', () => ({ default: () => null }));
+vi.mock('./dependants-list.component', () => ({ default: () => null }));
+
+const mockUsePcsParticipant = vi.mocked(usePcsParticipant);
+const mockUsePcsDependants = vi.mocked(usePcsDependants);
+
+const participant = { individualId: '901-1-1-2', firstName: 'JANE', lastName: 'ODONGO' } as PcsParticipant;
+
+const subject = { name: 'Jane Odongo', phoneNumber: '0712345678', hiePatient: { id: 'hie-1' } } as any;
+
+const renderBanner = () =>
+  render(
+    <LinkedParticipant
+      subject={subject}
+      studyParticipantId="901-1-1-2"
+      localPatient={{ uuid: 'mother-uuid' }}
+      onDelinked={vi.fn()}
+    />,
+  );
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockUsePcsParticipant.mockReturnValue({ participant, isLoading: false, error: null, mutate: vi.fn() } as any);
+  mockUsePcsDependants.mockReturnValue({
+    dependants: [],
+    totalCount: 0,
+    isLoading: false,
+    error: null,
+    mutate: vi.fn(),
+  } as any);
+});
+
+describe('LinkedParticipant dependant questions', () => {
+  it("launches the add-dependant workspace with the mother's individual ID", async () => {
+    renderBanner();
+
+    await userEvent.click(screen.getByRole('button', { name: /Dependant not in HIE and PCS\?/ }));
+
+    // The feature's only entry point — a drifted workspace name fails silently in the browser.
+    expect(launchWorkspace2).toHaveBeenCalledWith(
+      'pcs-add-dependant-workspace-form',
+      expect.objectContaining({ motherIndividualId: '901-1-1-2' }),
+    );
+  });
+
+  it('revalidates the dependants list once the child is created', async () => {
+    const mutateDependants = vi.fn();
+    mockUsePcsDependants.mockReturnValue({
+      dependants: [],
+      totalCount: 0,
+      isLoading: false,
+      error: null,
+      mutate: mutateDependants,
+    } as any);
+
+    renderBanner();
+    await userEvent.click(screen.getByRole('button', { name: /Dependant not in HIE and PCS\?/ }));
+
+    // Without this the new child does not appear until the page is refreshed.
+    vi.mocked(launchWorkspace2).mock.calls[0][1].onCreated();
+    expect(mutateDependants).toHaveBeenCalled();
+  });
+
+  it('holds the question closed until the participant has loaded', () => {
+    mockUsePcsParticipant.mockReturnValue({ participant: null, isLoading: true, error: null, mutate: vi.fn() } as any);
+
+    renderBanner();
+
+    // The handler reads participant.individualId, so an early click would throw.
+    expect(screen.getByRole('button', { name: /Dependant not in HIE and PCS\?/ })).toBeDisabled();
+  });
+
+  it("launches the HIE-dependant workspace with the mother's record and ID", async () => {
+    renderBanner();
+
+    await userEvent.click(screen.getByRole('button', { name: /Dependant in HIE and not PCS\?/ }));
+
+    // hiePatient is the candidate list's only source — without it the workspace shows empty.
+    expect(launchWorkspace2).toHaveBeenCalledWith(
+      'pcs-link-hie-dependant-workspace-form',
+      expect.objectContaining({
+        motherIndividualId: '901-1-1-2',
+        hiePatient: subject.hiePatient,
+        parentPhoneNumber: '0712345678',
+      }),
+    );
+  });
+
+  it('holds the HIE question closed until the participant has loaded', () => {
+    mockUsePcsParticipant.mockReturnValue({ participant: null, isLoading: true, error: null, mutate: vi.fn() } as any);
+
+    renderBanner();
+
+    expect(screen.getByRole('button', { name: /Dependant in HIE and not PCS\?/ })).toBeDisabled();
+  });
+});

package/src/linked/linked-participant.component.tsx

@@ -0,0 +1,142 @@
+import React from 'react';
+import { Button, InlineLoading } from '@carbon/react';
+import { ArrowRight, Renew, Unlink } from '@carbon/react/icons';
+import { launchWorkspace2, showModal, showSnackbar, useConfig } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import { type PcsConfig } from '../config-schema';
+import styles from '../pcs.scss';
+import { formatParticipantName, usePcsDependants, usePcsParticipant } from '../resources/pcs.resource';
+import { useSyncStudyAttributes } from '../resources/link-participant.resource';
+import { useStudySyncSnackbars } from './use-study-sync-snackbars';
+import { type PcsSearchSubject } from '../types';
+import LinkedParticipantBody from './linked-participant-body.component';
+
+interface LinkedParticipantProps {
+  subject: PcsSearchSubject;
+  /** The study participant ID already stamped on the patient — the key into PCS. */
+  studyParticipantId: string;
+  localPatient: any;
+  onDelinked: () => void;
+}
+
+const LinkedParticipant: React.FC<LinkedParticipantProps> = ({
+  subject,
+  studyParticipantId,
+  localPatient,
+  onDelinked,
+}) => {
+  const { t } = useTranslation();
+  const { pcsAttributeTypes } = useConfig<PcsConfig>();
+  const { participant, isLoading, error, mutate } = usePcsParticipant(studyParticipantId);
+  // Same key as the list inside the panel, so SWR issues one request and the tab can show a
+  // real count without anyone opening it.
+  const {
+    totalCount: dependantCount,
+    isLoading: isLoadingDependants,
+    mutate: mutateDependants,
+  } = usePcsDependants(participant?.individualId ?? null);
+
+  // PCS owns these two flags, so every pull by id reconciles the patient record with them.
+  const { syncNow } = useSyncStudyAttributes({
+    participant,
+    localPatient,
+    pbidsEnrollmentAttributeType: pcsAttributeTypes.pbidsEnrollmentStatus,
+    cardseEnrollmentAttributeType: pcsAttributeTypes.cardseEnrollmentStatus,
+    ...useStudySyncSnackbars(participant ? formatParticipantName(participant) : ''),
+  });
+
+  const refresh = async () => {
+    await mutate();
+    // Bypasses the sync guard: the PCS values may be identical while the patient's own
+    // attributes have drifted, and Refresh should mean "reconcile now".
+    syncNow();
+  };
+
+  const openAddDependant = () => {
+    launchWorkspace2('pcs-add-dependant-workspace-form', {
+      motherIndividualId: participant!.individualId,
+      // The new child is a participant with this mother, so the same key that feeds the tab
+      // count and the list picks them up.
+      onCreated: () => mutateDependants(),
+    });
+  };
+
+  const openLinkHieDependant = () => {
+    launchWorkspace2('pcs-link-hie-dependant-workspace-form', {
+      motherIndividualId: participant!.individualId,
+      hiePatient: subject.hiePatient,
+      parentPhoneNumber: subject.phoneNumber ?? undefined,
+      // The child becomes a participant with this mother, so the key behind the tab count and
+      // the list picks her up.
+      onLinked: () => mutateDependants(),
+    });
+  };
+
+  const openDelinkModal = () => {
+    const dispose = showModal('pcs-delink-participant-modal', {
+      closeModal: () => dispose(),
+      localPatient,
+      studyParticipantId,
+      participantName: participant ? formatParticipantName(participant) : undefined,
+      onDelinked,
+    });
+  };
+
+  return (
+    <>
+      <div className={styles.pcsLinkedBanner}>
+        <span className={styles.pcsLinkedTitle}>{t('linkedToPcs', 'Linked to PCS')}</span>
+        <span className={styles.pcsLinkedSubtitle}>
+          {t('linkedAs', '{{patientName}} is linked as {{individualId}}', {
+            patientName: subject.name,
+            individualId: studyParticipantId,
+          })}
+        </span>
+        <div className={styles.pcsLinkedActions}>
+          <Button kind="ghost" size="sm" renderIcon={Renew} disabled={isLoading} onClick={refresh}>
+            {isLoading ? <InlineLoading description={t('refreshing', 'Refreshing...')} /> : t('refresh', 'Refresh')}
+          </Button>
+          <Button kind="danger--ghost" size="sm" renderIcon={Unlink} onClick={openDelinkModal}>
+            {t('unlink', 'Unlink')}
+          </Button>
+        </div>
+
+        {/* The Dependants tab lists PCS rows, so by construction it cannot reach a child PCS has
+            never heard of. These two questions are exactly those cases, named by the situation at
+            the desk rather than by what the flow does. */}
+        <div className={styles.pcsLinkedQuestions}>
+          <Button
+            kind="ghost"
+            size="sm"
+            renderIcon={ArrowRight}
+            // Needs the mother's individualId, which only arrives with the participant.
+            disabled={!participant}
+            onClick={openAddDependant}>
+            {t('dependantNotInHieAndPcs', 'Dependant not in HIE and PCS?')}
+          </Button>
+          <Button
+            kind="ghost"
+            size="sm"
+            renderIcon={ArrowRight}
+            // Same guard as above — the handler reads participant.individualId.
+            disabled={!participant}
+            onClick={openLinkHieDependant}>
+            {t('dependantInHieNotPcs', 'Dependant in HIE and not PCS?')}
+          </Button>
+        </div>
+      </div>
+
+      <LinkedParticipantBody
+        subject={subject}
+        participant={participant}
+        studyParticipantId={studyParticipantId}
+        isLoading={isLoading}
+        error={error}
+        dependantCount={dependantCount}
+        isLoadingDependants={isLoadingDependants}
+      />
+    </>
+  );
+};
+
+export default LinkedParticipant;

package/src/linked/participant-details.component.tsx

@@ -0,0 +1,89 @@
+import React from 'react';
+import { Tag } from '@carbon/react';
+import { GenderFemale, GenderMale } from '@carbon/react/icons';
+import { age, formatDate, parseDate } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import styles from '../pcs.scss';
+import { formatCompoundHeadName, formatMotherName, formatParticipantName } from '../resources/pcs.resource';
+import { type PcsParticipant } from '../types';
+
+interface ParticipantDetailsProps {
+  participant: PcsParticipant;
+}
+
+export const GENDER_ICONS = {
+  F: <GenderFemale />,
+  M: <GenderMale />,
+} as const;
+
+export const SEX_LABELS: Record<PcsParticipant['sex'], string> = { F: 'Female', M: 'Male' };
+
+/** The linked participant's full PCS record. Read-only. */
+const ParticipantDetails: React.FC<ParticipantDetailsProps> = ({ participant }) => {
+  const { t } = useTranslation();
+
+  const row = (label: string, value?: string | null) => (
+    <div className={styles.pcsRow} key={label}>
+      <span className={styles.pcsFieldLabel}>{label}:</span>
+      <span>{value || '--'}</span>
+    </div>
+  );
+
+  const contacts = participant.contacts?.length ? participant.contacts : [{}];
+
+  return (
+    <div className={styles.pcsTile}>
+      <div className={styles.pcsRow}>
+        <span className={styles.pcsName}>{formatParticipantName(participant)}</span>
+      </div>
+
+      <div className={styles.pcsRow}>
+        <span className={styles.genderIcon}>
+          {GENDER_ICONS[participant.sex]}
+          <span>{SEX_LABELS[participant.sex]}</span>
+        </span>
+        {participant.dateOfBirth && (
+          <>
+            <span className={styles.separator}>&middot;</span>
+            <span>{age(participant.dateOfBirth)}</span>
+            <span className={styles.separator}>&middot;</span>
+            <span>{formatDate(parseDate(participant.dateOfBirth))}</span>
+          </>
+        )}
+      </div>
+
+      <div className={styles.pcsRow}>
+        {participant.pbidsEnrolled && (
+          <Tag className={styles.enrollmentTag} type="green" size="sm">
+            {t('pbidsEnrolled', 'PBIDS enrolled')}
+          </Tag>
+        )}
+        {participant.cardse && (
+          <Tag className={styles.enrollmentTag} type="purple" size="sm">
+            {t('cardse', 'CARDSE')}
+          </Tag>
+        )}
+      </div>
+
+      {row(t('individualId', 'Individual ID'), participant.individualId)}
+      {participant.mother && row(t('mother', 'Mother'), formatMotherName(participant.mother))}
+      {row(
+        t('compound', 'Compound'),
+        `${participant.compound.compoundId} · ${formatCompoundHeadName(participant.compound)}`,
+      )}
+      {row(t('village', 'Village'), `${participant.village.name} (${participant.village.code})`)}
+
+      <div className={styles.pcsContacts}>
+        {contacts.map((contact, index) => (
+          <div key={`contact-${index}`}>
+            {row(t('phone', 'Phone'), contact.phone)}
+            {row(t('nationalId', 'National ID'), contact.nationalId)}
+            {row(t('email', 'Email'), contact.email)}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export default ParticipantDetails;

package/src/linked/use-study-sync-snackbars.ts

@@ -0,0 +1,41 @@
+import { showSnackbar } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import { type StudyAttributeFlag } from '../resources/link-participant.resource';
+
+/**
+ * The snackbars `useSyncStudyAttributes` fires, shared by the mother's banner and each linked
+ * dependant row so the two can't drift apart.
+ *
+ * The participant's name is in the subtitle because several rows can sync at once — an
+ * unattributed "Updated from PCS: PBIDS enrollment" says nothing about which child changed.
+ *
+ * `useSyncStudyAttributes` keeps its callbacks in a ref refreshed each render, so these do not
+ * need to be referentially stable.
+ */
+export function useStudySyncSnackbars(participantName: string) {
+  const { t } = useTranslation();
+
+  const flagLabels: Record<StudyAttributeFlag, string> = {
+    pbids: t('pbidsEnrollment', 'PBIDS enrollment'),
+    cardse: t('cardseEnrollment', 'CARDSE enrollment'),
+  };
+
+  return {
+    onSynced: (changed: Array<StudyAttributeFlag>) =>
+      showSnackbar({
+        title: t('studyAttributesUpdated', 'Study attributes updated'),
+        subtitle: t('studyAttributesUpdatedSubtitle', 'Updated {{name}} from PCS: {{fields}}', {
+          name: participantName,
+          fields: changed.map((flag) => flagLabels[flag]).join(', '),
+        }),
+        kind: 'success',
+        isLowContrast: true,
+      }),
+    onSyncError: (syncError: any) =>
+      showSnackbar({
+        title: t('studyAttributesSyncFailed', 'Could not sync study attributes'),
+        subtitle: syncError?.responseBody?.error?.message ?? syncError?.message,
+        kind: 'error',
+      }),
+  };
+}

package/src/modals/delink-participant.modal.tsx

@@ -0,0 +1,96 @@
+import React, { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Button, InlineLoading, InlineNotification, ModalBody, ModalFooter, ModalHeader } from '@carbon/react';
+import { showSnackbar, useConfig } from '@openmrs/esm-framework';
+
+import { type PcsConfig } from '../config-schema';
+import { delinkParticipant } from '../resources/link-participant.resource';
+
+interface DelinkParticipantModalProps {
+  closeModal: () => void;
+  localPatient: any;
+  studyParticipantId: string;
+  participantName?: string;
+  onDelinked?: () => void;
+}
+
+const DelinkParticipantModal: React.FC<DelinkParticipantModalProps> = ({
+  closeModal,
+  localPatient,
+  studyParticipantId,
+  participantName,
+  onDelinked,
+}) => {
+  const { t } = useTranslation();
+  const { pcsIdentifiers, pcsAttributeTypes } = useConfig<PcsConfig>();
+  const [isDelinking, setIsDelinking] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleDelink = async () => {
+    setError(null);
+    setIsDelinking(true);
+    try {
+      await delinkParticipant({
+        localPatient,
+        studyParticipantIdentifierType: pcsIdentifiers.studyParticipantID,
+        pbidsEnrollmentAttributeType: pcsAttributeTypes.pbidsEnrollmentStatus,
+        cardseEnrollmentAttributeType: pcsAttributeTypes.cardseEnrollmentStatus,
+      });
+      showSnackbar({
+        title: t('participantUnlinked', 'Records unlinked'),
+        subtitle: t('participantUnlinkedSubtitle', 'The study participant ID and study attributes were removed.'),
+        kind: 'success',
+        isLowContrast: true,
+      });
+      onDelinked?.();
+      closeModal();
+    } catch (e: any) {
+      setError(
+        e?.responseBody?.error?.message ??
+          e?.message ??
+          t('participantUnlinkFailedSubtitle', 'The patient record could not be updated.'),
+      );
+    } finally {
+      setIsDelinking(false);
+    }
+  };
+
+  return (
+    <>
+      <ModalHeader closeModal={closeModal} title={t('unlinkFromPcs', 'Unlink from PCS')} />
+      <ModalBody>
+        <p>
+          {t('unlinkConfirmation', 'Remove the link between this patient and PCS participant {{individualId}}?', {
+            individualId: participantName ? `${studyParticipantId} (${participantName})` : studyParticipantId,
+          })}
+        </p>
+        <p>
+          {t(
+            'unlinkWhatIsRemoved',
+            'The study participant ID and both enrollment status attributes will be removed from the patient record.',
+          )}
+        </p>
+
+        {error && (
+          <InlineNotification
+            kind="error"
+            lowContrast
+            hideCloseButton
+            title={t('participantUnlinkFailed', 'Could not unlink records')}
+            subtitle={error}
+          />
+        )}
+      </ModalBody>
+      <ModalFooter>
+        <Button kind="secondary" onClick={closeModal} disabled={isDelinking}>
+          {t('cancel', 'Cancel')}
+        </Button>
+        <Button kind="danger" onClick={handleDelink} disabled={isDelinking}>
+          {isDelinking ? <InlineLoading description={t('unlinking', 'Unlinking...')} /> : t('unlink', 'Unlink')}
+        </Button>
+      </ModalFooter>
+    </>
+  );
+};
+
+export default DelinkParticipantModal;