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

package/src/link-hie-dependant/link-hie-dependant.workspace.tsx

@@ -0,0 +1,207 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Controller, useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import {
+  Button,
+  ButtonSet,
+  Form,
+  InlineLoading,
+  InlineNotification,
+  RadioButton,
+  RadioButtonGroup,
+} from '@carbon/react';
+import { showSnackbar, useConfig, Workspace2, type Workspace2DefinitionProps } from '@openmrs/esm-framework';
+
+import { type PcsConfig } from '../config-schema';
+import { useIdentifierTypeUuids } from '../resources/use-identifier-type-uuids';
+import { getDependentsFromContacts } from '../resources/hie-contacts';
+import { linkHieDependantWithTemporaryId, useHieDependantLinkState } from '../resources/link-dependant.resource';
+import styles from './link-hie-dependant.scss';
+
+export interface LinkHieDependantWorkspaceProps {
+  /** The mother's PCS individual ID — the new participant is created against it. */
+  motherIndividualId: string;
+  /** The mother's HIE record; her `contact` array is the candidate list. */
+  hiePatient?: fhir.Patient;
+  parentPhoneNumber?: string;
+  onLinked?: () => void;
+}
+
+const schema = z.object({
+  dependantId: z.string().min(1),
+});
+
+type LinkHieDependantFormData = z.infer<typeof schema>;
+
+const LinkHieDependantWorkspace: React.FC<Workspace2DefinitionProps<LinkHieDependantWorkspaceProps, {}, {}>> = ({
+  closeWorkspace,
+  workspaceProps,
+}) => {
+  const { t } = useTranslation();
+  const uuids = useIdentifierTypeUuids();
+
+  const { pcsIdentifiers } = useConfig<PcsConfig>();
+  const { motherIndividualId, hiePatient, parentPhoneNumber, onLinked } = workspaceProps ?? {};
+  const [submitError, setSubmitError] = useState<string | null>(null);
+
+  // Read straight off the record already in hand — no request.
+  const candidates = useMemo(() => (hiePatient ? getDependentsFromContacts(hiePatient as any) : []), [hiePatient]);
+
+  // A child already holding either study identifier is in PCS, so this flow does not apply to
+  // her — she is shown with the ID she holds rather than hidden, so an operator hunting for her
+  // can tell "already linked" apart from "not in the HIE at all".
+  const { linkedById, isChecking } = useHieDependantLinkState(candidates, [
+    pcsIdentifiers.studyParticipantID,
+    pcsIdentifiers.studyTemporaryParticipantID,
+  ]);
+
+  const {
+    control,
+    handleSubmit,
+    formState: { isSubmitting },
+  } = useForm<LinkHieDependantFormData>({
+    resolver: zodResolver(schema),
+    defaultValues: { dependantId: '' },
+  });
+
+  const onSubmit = async ({ dependantId }: LinkHieDependantFormData) => {
+    const dependant = candidates.find((candidate) => candidate.id === dependantId);
+    if (!dependant || !motherIndividualId) {
+      return;
+    }
+
+    setSubmitError(null);
+    try {
+      const { participant } = await linkHieDependantWithTemporaryId({
+        dependant,
+        parentPhoneNumber,
+        motherIndividualId,
+        uuids,
+      });
+
+      showSnackbar({
+        title: t('dependantLinkedToPcs', 'Dependant added to PCS'),
+        subtitle: participant?.individualId
+          ? t('dependantAddedSubtitle', 'PCS issued {{individualId}} for this dependant.', {
+              individualId: participant.individualId,
+            })
+          : undefined,
+        kind: 'success',
+        isLowContrast: true,
+      });
+
+      onLinked?.();
+      closeWorkspace();
+    } catch (e: any) {
+      // A child linked elsewhere since the list rendered comes back as a 409 — worth showing
+      // the module's own wording rather than a generic failure.
+      setSubmitError(
+        e?.responseBody?.error?.message ??
+          e?.message ??
+          t('dependantLinkToPcsFailed', 'The dependant could not be added to PCS.'),
+      );
+    }
+  };
+
+  if (!workspaceProps) {
+    return null;
+  }
+
+  return (
+    <Workspace2 title={t('dependantInHieNotPcs', 'Dependant in HIE and not PCS?')}>
+      <Form onSubmit={handleSubmit(onSubmit)} className={styles.workspaceForm}>
+        <div className={styles.workspaceContent}>
+          {candidates.length === 0 ? (
+            <div className={styles.emptyState}>
+              <p className={styles.emptyTitle}>
+                {t('noHieDependants', 'The HIE record lists no dependants for this mother.')}
+              </p>
+              <p className={styles.emptySubtitle}>
+                {t(
+                  'noHieDependantsSubtitle',
+                  'Use "Dependant not in HIE and PCS?" to register the child from their own details.',
+                )}
+              </p>
+            </div>
+          ) : (
+            <>
+              <p className={styles.prompt}>
+                {t('chooseDependantToAdd', 'Choose the dependant to add to PCS. One at a time.')}
+              </p>
+
+              <Controller
+                name="dependantId"
+                control={control}
+                render={({ field: { onChange, value } }) => (
+                  <RadioButtonGroup
+                    name="hieDependant"
+                    orientation="vertical"
+                    legendText={t('mothersDependantsInHie', "Mother's dependants in the HIE")}
+                    valueSelected={value ?? ''}
+                    // Load-bearing: without it Carbon's internal state ignores a programmatic
+                    // change to the selected value.
+                    key={value ?? 'empty'}
+                    onChange={(selected) => onChange(String(selected))}>
+                    {candidates.map((candidate) => {
+                      const linkedTo = linkedById[candidate.id];
+
+                      return (
+                        <RadioButton
+                          key={candidate.id}
+                          value={candidate.id}
+                          // Disabled while the check runs too, so nothing can be picked in the
+                          // window before its state is known.
+                          disabled={isChecking || Boolean(linkedTo)}
+                          labelText={`${candidate.name} · ${candidate.relationship} · ${candidate.gender}${
+                            candidate.birthDate && candidate.birthDate !== 'Unknown' ? ` · ${candidate.birthDate}` : ''
+                          }${
+                            linkedTo
+                              ? ` — ${t('alreadyLinkedTo', 'already linked to {{individualId}}', {
+                                  individualId: linkedTo,
+                                })}`
+                              : ''
+                          }`}
+                        />
+                      );
+                    })}
+                  </RadioButtonGroup>
+                )}
+              />
+
+              {isChecking && (
+                <InlineLoading
+                  className={styles.checking}
+                  description={t('checkingPcsLinks', 'Checking which dependants are already in PCS...')}
+                />
+              )}
+            </>
+          )}
+
+          {submitError && (
+            <InlineNotification
+              className={styles.notification}
+              kind="error"
+              lowContrast
+              hideCloseButton
+              title={t('dependantLinkToPcsFailedTitle', 'Could not add dependant to PCS')}
+              subtitle={submitError}
+            />
+          )}
+        </div>
+
+        <ButtonSet className={styles.workspaceButtonSet}>
+          <Button kind="secondary" onClick={() => closeWorkspace()}>
+            {t('cancel', 'Cancel')}
+          </Button>
+          <Button kind="primary" type="submit" disabled={isSubmitting || candidates.length === 0}>
+            {isSubmitting ? <InlineLoading description={t('addingDependant', 'Adding...')} /> : t('save', 'Save')}
+          </Button>
+        </ButtonSet>
+      </Form>
+    </Workspace2>
+  );
+};
+
+export default LinkHieDependantWorkspace;

package/src/linked/dependant-row.component.test.tsx

@@ -0,0 +1,134 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import DependantRow from './dependant-row.component';
+import { useLinkedPatientForParticipant, useSyncStudyAttributes } from '../resources/link-participant.resource';
+import { type PcsParticipant } from '../types';
+
+vi.mock('@openmrs/esm-framework', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@openmrs/esm-framework')>()),
+  age: () => '14 yrs',
+  useConfig: () => ({
+    pcsIdentifiers: { studyParticipantID: 'study-id-type', studyTemporaryParticipantID: 'temp-id-type' },
+    pcsAttributeTypes: { pbidsEnrollmentStatus: 'pbids-attr', cardseEnrollmentStatus: 'cardse-attr' },
+  }),
+}));
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({ t: (_key: string, fallback: string) => fallback }),
+}));
+
+vi.mock('../resources/link-participant.resource', () => ({
+  useLinkedPatientForParticipant: vi.fn(),
+  useSyncStudyAttributes: vi.fn(),
+}));
+
+vi.mock('./use-study-sync-snackbars', () => ({
+  useStudySyncSnackbars: () => ({ onSynced: vi.fn(), onSyncError: vi.fn() }),
+}));
+
+vi.mock('../resources/pcs.resource', () => ({ formatParticipantName: () => 'DENNIS OMONDI ODONGO' }));
+
+const mockUseLinkedPatientForParticipant = vi.mocked(useLinkedPatientForParticipant);
+const mockUseSyncStudyAttributes = vi.mocked(useSyncStudyAttributes);
+
+const dependant = {
+  individualId: '901-1-1-3',
+  firstName: 'DENNIS',
+  middleName: 'OMONDI',
+  lastName: 'ODONGO',
+  sex: 'M',
+  dateOfBirth: '2011-06-12',
+  pbidsEnrolled: true,
+  cardse: false,
+  mother: null,
+  compound: { compoundId: '901-1', headIndividualId: '901-1-1-1', headFirstName: 'JOHN', headLastName: 'ODONGO' },
+  village: { code: '901', name: 'TEST ABUYA' },
+  contacts: [],
+  matchedOn: null,
+  matchType: null,
+} as PcsParticipant;
+
+beforeEach(() => vi.clearAllMocks());
+
+describe('DependantRow', () => {
+  it('reports the patient a dependant is already linked to', () => {
+    mockUseLinkedPatientForParticipant.mockReturnValue({
+      linkedPatient: { uuid: 'p1', person: { personName: { display: 'Dennis Odongo' } } },
+      isLoading: false,
+      error: undefined,
+      mutate: vi.fn(),
+    } as any);
+
+    render(<DependantRow dependant={dependant} />);
+
+    expect(screen.getByText('Linked')).toBeInTheDocument();
+    expect(screen.getByText('Dennis Odongo')).toBeInTheDocument();
+    // A linked row offers the undo, not the link.
+    expect(screen.getByRole('button', { name: /Unlink/ })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Link dependant' })).not.toBeInTheDocument();
+  });
+
+  it("reconciles a linked dependant's enrolment attributes in the background", () => {
+    const linkedPatient = { uuid: 'p1', person: { personName: { display: 'Dennis Odongo' } } };
+    mockUseLinkedPatientForParticipant.mockReturnValue({
+      linkedPatient,
+      isLoading: false,
+      error: undefined,
+      mutate: vi.fn(),
+    } as any);
+
+    render(<DependantRow dependant={dependant} />);
+
+    expect(mockUseSyncStudyAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({ participant: dependant, localPatient: linkedPatient }),
+    );
+  });
+
+  it('leaves an unlinked dependant with nothing to sync', () => {
+    mockUseLinkedPatientForParticipant.mockReturnValue({
+      linkedPatient: null,
+      isLoading: false,
+      error: undefined,
+      mutate: vi.fn(),
+    } as any);
+
+    render(<DependantRow dependant={dependant} />);
+
+    // A null patient is what makes the hook a no-op, so unlinked rows cost no request.
+    expect(mockUseSyncStudyAttributes).toHaveBeenCalledWith(expect.objectContaining({ localPatient: null }));
+  });
+
+  it('offers to create a dependant nobody is linked to', () => {
+    mockUseLinkedPatientForParticipant.mockReturnValue({
+      linkedPatient: null,
+      isLoading: false,
+      error: undefined,
+      mutate: vi.fn(),
+    } as any);
+
+    render(<DependantRow dependant={dependant} />);
+
+    expect(screen.getByRole('button', { name: 'Link dependant' })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /Unlink/ })).not.toBeInTheDocument();
+    expect(screen.queryByText('Linked')).not.toBeInTheDocument();
+  });
+
+  it('shows neither while the lookup is still in flight', () => {
+    mockUseLinkedPatientForParticipant.mockReturnValue({
+      linkedPatient: null,
+      isLoading: true,
+      error: undefined,
+      mutate: vi.fn(),
+    } as any);
+
+    render(<DependantRow dependant={dependant} />);
+
+    // Flashing the action before the answer arrives invites a misclick on a child who is
+    // already registered.
+    expect(screen.queryByRole('button', { name: 'Link dependant' })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /Unlink/ })).not.toBeInTheDocument();
+    expect(screen.queryByText('Linked')).not.toBeInTheDocument();
+  });
+});

package/src/linked/dependant-row.component.tsx

@@ -0,0 +1,122 @@
+import React from 'react';
+import { Button, Tag } from '@carbon/react';
+import { Link as LinkIcon, Unlink } from '@carbon/react/icons';
+import { age, showModal, useConfig } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import styles from '../pcs.scss';
+import { type PcsConfig } from '../config-schema';
+import { formatParticipantName } from '../resources/pcs.resource';
+import { useLinkedPatientForParticipant, useSyncStudyAttributes } from '../resources/link-participant.resource';
+import { useStudySyncSnackbars } from './use-study-sync-snackbars';
+import { type PcsParticipant } from '../types';
+import { GENDER_ICONS, SEX_LABELS } from './participant-details.component';
+
+interface DependantRowProps {
+  dependant: PcsParticipant;
+  /** The mother's HIE record — the modal picks her dependants out of its contacts. */
+  hiePatient?: fhir.Patient;
+  parentPhoneNumber?: string;
+}
+
+const getPatientName = (localPatient: any) =>
+  localPatient?.person?.personName?.display || localPatient?.display || localPatient?.person?.display;
+
+/** One of the mother's PCS children, with whether they are already a patient here. */
+const DependantRow: React.FC<DependantRowProps> = ({ dependant, hiePatient, parentPhoneNumber }) => {
+  const { t } = useTranslation();
+  const { pcsIdentifiers, pcsAttributeTypes } = useConfig<PcsConfig>();
+
+  // Either type counts: a child linked through "Not in PCS" holds the temporary one, and the
+  // module makes that id the participant's INDIVIDID, so they come back in this list too.
+  const { linkedPatient, isLoading, mutate } = useLinkedPatientForParticipant(dependant.individualId, [
+    pcsIdentifiers.studyParticipantID,
+    pcsIdentifiers.studyTemporaryParticipantID,
+  ]);
+
+  // Same reconciliation the mother's banner does, so a linked child's flags don't go stale.
+  // Called unconditionally, as hooks must be — the hook no-ops while `linkedPatient` is null,
+  // which is what keeps unlinked rows free.
+  useSyncStudyAttributes({
+    participant: dependant,
+    localPatient: linkedPatient,
+    pbidsEnrollmentAttributeType: pcsAttributeTypes.pbidsEnrollmentStatus,
+    cardseEnrollmentAttributeType: pcsAttributeTypes.cardseEnrollmentStatus,
+    ...useStudySyncSnackbars(formatParticipantName(dependant)),
+  });
+
+  const openLinkModal = () => {
+    const dispose = showModal('pcs-link-dependant-modal', {
+      closeModal: () => dispose(),
+      participant: dependant,
+      hiePatient,
+      parentPhoneNumber,
+      onLinked: () => mutate(),
+    });
+  };
+
+  const openUnlinkModal = () => {
+    const dispose = showModal('pcs-delink-participant-modal', {
+      closeModal: () => dispose(),
+      localPatient: linkedPatient,
+      studyParticipantId: dependant.individualId,
+      participantName: formatParticipantName(dependant),
+      onDelinked: () => mutate(),
+    });
+  };
+
+  return (
+    <div className={styles.pcsTile}>
+      <div className={styles.pcsRow}>
+        <span className={styles.pcsName}>{formatParticipantName(dependant)}</span>
+        {linkedPatient && (
+          <Tag className={styles.enrollmentTag} type="green" size="sm">
+            {t('linked', 'Linked')}
+          </Tag>
+        )}
+      </div>
+
+      <div className={styles.pcsRow}>
+        <span className={styles.genderIcon}>
+          {GENDER_ICONS[dependant.sex]}
+          <span>{SEX_LABELS[dependant.sex]}</span>
+        </span>
+        {dependant.dateOfBirth && (
+          <>
+            <span className={styles.separator}>&middot;</span>
+            <span>{age(dependant.dateOfBirth)}</span>
+          </>
+        )}
+      </div>
+
+      <div className={styles.pcsRow}>
+        <span className={styles.pcsFieldLabel}>{t('individualId', 'Individual ID')}:</span>
+        <span>{dependant.individualId}</span>
+      </div>
+
+      {linkedPatient && (
+        <div className={styles.pcsRow}>
+          <span className={styles.pcsFieldLabel}>{t('emrPatient', 'EMR patient')}:</span>
+          <span>{getPatientName(linkedPatient) || '--'}</span>
+        </div>
+      )}
+
+      {/* Nothing is rendered while the lookup is in flight: showing the link action first
+          would flash it on every row and invite a misclick on a child already registered. */}
+      {!isLoading && (
+        <div className={styles.pcsTileActions}>
+          {linkedPatient ? (
+            <Button kind="danger--ghost" size="sm" renderIcon={Unlink} onClick={openUnlinkModal}>
+              {t('unlink', 'Unlink')}
+            </Button>
+          ) : (
+            <Button kind="tertiary" size="sm" renderIcon={LinkIcon} onClick={openLinkModal}>
+              {t('linkDependant', 'Link dependant')}
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default DependantRow;

package/src/linked/dependants-list.component.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import { SkeletonText } from '@carbon/react';
+import { ErrorState } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import styles from '../pcs.scss';
+import { usePcsDependants } from '../resources/pcs.resource';
+import DependantRow from './dependant-row.component';
+
+interface DependantsListProps {
+  /** The linked participant — dependants are those whose mother is this individual. */
+  motherIndividualId: string;
+  /** The mother's HIE record, passed down so a row can offer to link one of her contacts. */
+  hiePatient?: fhir.Patient;
+  parentPhoneNumber?: string;
+}
+
+/** The linked client's children in PCS. Display-only. */
+const DependantsList: React.FC<DependantsListProps> = ({ motherIndividualId, hiePatient, parentPhoneNumber }) => {
+  const { t } = useTranslation();
+  // SWR dedupes this with the identical call in the parent that supplies the tab count.
+  const { dependants, isLoading, error } = usePcsDependants(motherIndividualId);
+
+  if (isLoading) {
+    return (
+      <div className={styles.pcsSkeletonTile}>
+        <SkeletonText paragraph lineCount={3} />
+      </div>
+    );
+  }
+
+  if (error) {
+    return <ErrorState error={error} headerTitle={t('errorLoadingDependants', 'Error loading dependants')} />;
+  }
+
+  if (dependants.length === 0) {
+    return (
+      <div className={styles.pcsLinkError}>
+        <p className={styles.pcsEmptyTitle}>{t('noDependants', 'No dependants')}</p>
+        <p className={styles.pcsEmptySubtitle}>
+          {t('noDependantsSubtitle', 'PCS has no participants recorded with this mother.')}
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.pcsResults}>
+      {dependants.map((dependant) => (
+        <DependantRow
+          key={dependant.individualId}
+          dependant={dependant}
+          hiePatient={hiePatient}
+          parentPhoneNumber={parentPhoneNumber}
+        />
+      ))}
+    </div>
+  );
+};
+
+export default DependantsList;

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

@@ -0,0 +1,82 @@
+import React from 'react';
+import { SkeletonText, Tab, TabList, TabPanel, TabPanels, Tabs } from '@carbon/react';
+import { useTranslation } from 'react-i18next';
+import styles from '../pcs.scss';
+import { type PcsParticipant, type PcsSearchSubject } from '../types';
+import DependantsList from './dependants-list.component';
+import ParticipantDetails from './participant-details.component';
+
+interface LinkedParticipantBodyProps {
+  subject: PcsSearchSubject;
+  participant: PcsParticipant | null;
+  /** The study participant ID stamped on the patient — shown when PCS cannot resolve it. */
+  studyParticipantId: string;
+  isLoading: boolean;
+  error: unknown;
+  dependantCount: number;
+  isLoadingDependants: boolean;
+}
+
+/** Everything below the linked banner: loading, unresolvable, or the participant's tabs. */
+const LinkedParticipantBody: React.FC<LinkedParticipantBodyProps> = ({
+  subject,
+  participant,
+  studyParticipantId,
+  isLoading,
+  error,
+  dependantCount,
+  isLoadingDependants,
+}) => {
+  const { t } = useTranslation();
+
+  if (isLoading) {
+    return (
+      <div className={styles.pcsSkeletonTile}>
+        <SkeletonText heading width="60%" />
+        <SkeletonText paragraph lineCount={5} />
+      </div>
+    );
+  }
+
+  // A PCS record that cannot be resolved must not strand the patient — the unlink action stays
+  // available above, so a stale or mistyped study ID can always be removed.
+  if (error || !participant) {
+    return (
+      <div className={styles.pcsLinkError}>
+        <p className={styles.pcsEmptyTitle}>{t('pcsParticipantUnavailable', 'Participant could not be loaded')}</p>
+        <p className={styles.pcsEmptySubtitle}>
+          {t('pcsParticipantUnavailableSubtitle', 'PCS did not return a record for {{individualId}}.', {
+            individualId: studyParticipantId,
+          })}
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <Tabs>
+      <TabList aria-label={t('pcsParticipantTabs', 'PCS participant')} contained>
+        <Tab>{t('details', 'Details')}</Tab>
+        <Tab>
+          {isLoadingDependants
+            ? t('dependants', 'Dependants')
+            : t('dependantsWithCount', 'Dependants ({{count}})', { count: dependantCount })}
+        </Tab>
+      </TabList>
+      <TabPanels>
+        <TabPanel>
+          <ParticipantDetails participant={participant} />
+        </TabPanel>
+        <TabPanel>
+          <DependantsList
+            motherIndividualId={participant.individualId}
+            hiePatient={subject.hiePatient}
+            parentPhoneNumber={subject.phoneNumber ?? undefined}
+          />
+        </TabPanel>
+      </TabPanels>
+    </Tabs>
+  );
+};
+
+export default LinkedParticipantBody;