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

package/src/routes.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json.openmrs.org/routes.schema.json",
+  "backendDependencies": {
+    "webservices.rest": "^2.24.0"
+  },
+  "extensions": [
+    {
+      "name": "pcs-search-results",
+      "component": "pcsSearchResults",
+      "slot": "ewf-registration-patient-extras-slot",
+      "featureFlag": "pcsSite",
+      "online": true,
+      "offline": false
+    }
+  ],
+  "modals": [
+    {
+      "name": "pcs-link-participant-modal",
+      "component": "pcsLinkParticipantModal"
+    },
+    {
+      "name": "pcs-delink-participant-modal",
+      "component": "pcsDelinkParticipantModal"
+    },
+    {
+      "name": "pcs-link-dependant-modal",
+      "component": "pcsLinkDependantModal"
+    }
+  ],
+  "workspaces2": [
+    {
+      "name": "pcs-add-dependant-workspace-form",
+      "component": "pcsAddDependantWorkspace",
+      "window": "pcs-dependant"
+    },
+    {
+      "name": "pcs-link-hie-dependant-workspace-form",
+      "component": "pcsLinkHieDependantWorkspace",
+      "window": "pcs-dependant"
+    }
+  ],
+  "workspaceWindows2": [
+    {
+      "name": "pcs-dependant",
+      "group": "pcs-registration",
+      "width": "narrow"
+    }
+  ],
+  "workspaceGroups2": [
+    {
+      "name": "pcs-registration"
+    }
+  ]
+}

package/src/search/participant-results.component.tsx

@@ -0,0 +1,96 @@
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { ErrorState } from '@openmrs/esm-framework';
+import styles from '../pcs.scss';
+import { getPcsErrorMessage, isPcsUnavailable } from '../resources/pcs.resource';
+import { type PcsParticipant, type PcsSearchSubject } from '../types';
+import PCSParticipantTile from './participant-tile.component';
+import PcsEmptyState from './pcs-empty-state.component';
+import PcsResultsSkeleton from './pcs-results-skeleton.component';
+
+interface ParticipantResultsProps {
+  subject: PcsSearchSubject;
+  participants: Array<PcsParticipant>;
+  totalCount: number;
+  /** False until a filter has actually been submitted — no search has been made yet. */
+  hasCommittedFilters: boolean;
+  isLoading: boolean;
+  error: unknown;
+  onReset: () => void;
+  onLinked: () => void;
+}
+
+/** The body of the search pane: nothing asked yet, loading, failed, empty, or results. */
+const ParticipantResults: React.FC<ParticipantResultsProps> = ({
+  subject,
+  participants,
+  totalCount,
+  hasCommittedFilters,
+  isLoading,
+  error,
+  onReset,
+  onLinked,
+}) => {
+  const { t } = useTranslation();
+
+  if (!hasCommittedFilters) {
+    return (
+      <PcsEmptyState
+        title={t('noFilters', 'No filters')}
+        subtitle={t('pcsAddFilterToSearch', 'Add a filter to search the PCS registry')}
+        onReset={onReset}
+      />
+    );
+  }
+
+  if (isLoading) {
+    return <PcsResultsSkeleton />;
+  }
+
+  if (error) {
+    return (
+      <ErrorState
+        error={error}
+        headerTitle={
+          // A downed VPN to the SQL Server reads very differently to a bug, so it is named.
+          isPcsUnavailable(error)
+            ? t('pcsRegistryUnavailable', 'PCS registry unavailable')
+            : getPcsErrorMessage(error) ?? t('errorLoadingPcsRecords', 'Error loading PCS records')
+        }
+      />
+    );
+  }
+
+  if (participants.length === 0) {
+    return (
+      <PcsEmptyState
+        title={t('noPcsRecordsFound', 'No PCS records found')}
+        subtitle={t('noPcsRecordsForFilters', 'No participant matched these filters')}
+        onReset={onReset}
+      />
+    );
+  }
+
+  return (
+    <div className={styles.pcsResults}>
+      <span className={styles.pcsResultsCount}>
+        {totalCount > participants.length
+          ? t('pcsShowingOf', 'Showing {{shown}} of {{total}} PCS records', {
+              shown: participants.length,
+              total: totalCount,
+            })
+          : t('pcsRecordsFound', 'PCS record(s) found ({{count}})', { count: participants.length })}
+      </span>
+      {participants.map((participant) => (
+        <PCSParticipantTile
+          key={participant.individualId}
+          participant={participant}
+          subject={subject}
+          onLinked={onLinked}
+        />
+      ))}
+    </div>
+  );
+};
+
+export default ParticipantResults;

package/src/search/participant-tile.component.tsx

@@ -0,0 +1,133 @@
+import React from 'react';
+import { Button, Tag } from '@carbon/react';
+import { GenderFemale, GenderMale, Link as LinkIcon } from '@carbon/react/icons';
+import { age, formatDate, parseDate, showModal } from '@openmrs/esm-framework';
+import { useTranslation } from 'react-i18next';
+import styles from '../pcs.scss';
+import {
+  formatCompoundHeadName,
+  formatMotherName,
+  formatParticipantName,
+  getPrimaryContact,
+} from '../resources/pcs.resource';
+import { type PcsMatchType, type PcsMatchedOn, type PcsParticipant, type PcsSearchSubject } from '../types';
+
+interface PCSParticipantTileProps {
+  participant: PcsParticipant;
+  subject: PcsSearchSubject;
+  /** Lets the pane re-read the patient's study link once one has been written. */
+  onLinked?: () => void;
+}
+
+const GENDER_ICONS = {
+  F: <GenderFemale />,
+  M: <GenderMale />,
+} as const;
+
+const SEX_LABELS: Record<PcsParticipant['sex'], string> = { F: 'Female', M: 'Male' };
+
+const PCSParticipantTile: React.FC<PCSParticipantTileProps> = ({ participant, subject, onLinked }) => {
+  const { t } = useTranslation();
+
+  const name = formatParticipantName(participant);
+  const contact = getPrimaryContact(participant);
+
+  // The registry scores the name itself, tiered and per field, which beats comparing
+  // strings here. Both are null when `name` was not one of the filters.
+  const matchLabel = (matchType: PcsMatchType, matchedOn: PcsMatchedOn): string => {
+    const field = {
+      name: t('pcsFieldName', 'name'),
+      motherName: t('pcsFieldMotherName', "mother's name"),
+      compoundName: t('pcsFieldCompoundName', 'compound head'),
+    }[matchedOn];
+
+    switch (matchType) {
+      case 'EXACT':
+        return t('pcsMatchExact', 'Exact match on {{field}}', { field });
+      case 'CONTAINS':
+        return t('pcsMatchContains', 'Partial match on {{field}}', { field });
+      case 'SOUNDEX':
+        return t('pcsMatchSoundex', 'Sounds like {{field}}', { field });
+    }
+  };
+
+  const matchTagType = participant.matchType === 'EXACT' ? 'green' : 'teal';
+
+  // Linking creates the patient if needed and writes to their record, so it confirms first.
+  const openLinkModal = () => {
+    const dispose = showModal('pcs-link-participant-modal', {
+      closeModal: () => dispose(),
+      subject,
+      participant,
+      onLinked,
+    });
+  };
+
+  return (
+    <div className={styles.pcsTile}>
+      <div className={styles.pcsRow}>
+        <span className={styles.pcsName}>{name}</span>
+      </div>
+
+      {participant.matchType && participant.matchedOn && (
+        <Tag className={styles.matchTag} type={matchTagType} size="sm">
+          {matchLabel(participant.matchType, participant.matchedOn)}
+        </Tag>
+      )}
+
+      <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>
+            <span className={styles.separator}>&middot;</span>
+            <span>{contact?.phone || '--'}</span>
+          </>
+        ) : (
+          <>
+            <span className={styles.separator}>&middot;</span>
+            <span>{t('unknownDateOfBirth', 'Unknown date of birth')}</span>
+          </>
+        )}
+      </div>
+
+      <div className={styles.pcsRow}>
+        <span className={styles.pcsFieldLabel}>{t('individualId', 'Individual ID')}:</span>
+        <span>{participant.individualId}</span>
+        <span className={styles.separator}>&middot;</span>
+        <span className={styles.pcsFieldLabel}>{t('nationalId', 'National ID')}:</span>
+        <span>{contact?.nationalId || '--'}</span>
+      </div>
+
+      {participant.mother && (
+        <div className={styles.pcsRow}>
+          <span className={styles.pcsFieldLabel}>{t('mother', 'Mother')}:</span>
+          <span>{formatMotherName(participant.mother)}</span>
+          <span className={styles.separator}>&middot;</span>
+          <span>{participant.mother.individualId}</span>
+        </div>
+      )}
+
+      <div className={styles.pcsHousehold}>
+        {t('pcsHousehold', '{{village}} village | Head: {{compoundHead}}', {
+          village: participant.village?.name || '--',
+          compoundHead: formatCompoundHeadName(participant.compound) || '--',
+        })}
+      </div>
+
+      <div className={styles.pcsTileActions}>
+        <Button kind="ghost" size="sm" renderIcon={LinkIcon} onClick={openLinkModal}>
+          {t('linkRecords', 'Link records')}
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export default PCSParticipantTile;

package/src/search/pcs-empty-state.component.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import { Button } from '@carbon/react';
+import { Reset } from '@carbon/react/icons';
+import { useTranslation } from 'react-i18next';
+import styles from '../pcs.scss';
+import { EmptySvg } from '../empty-svg.component';
+
+interface PcsEmptyStateProps {
+  title: string;
+  subtitle: string;
+  /** Puts the patient's own details back into the filters. */
+  onReset: () => void;
+}
+
+/** Shown both before a search has been made and when one returned nothing. */
+const PcsEmptyState: React.FC<PcsEmptyStateProps> = ({ title, subtitle, onReset }) => {
+  const { t } = useTranslation();
+
+  return (
+    <div className={styles.pcsEmptyState}>
+      <EmptySvg />
+      <p className={styles.pcsEmptyTitle}>{title}</p>
+      <p className={styles.pcsEmptySubtitle}>{subtitle}</p>
+      <Button kind="ghost" size="sm" renderIcon={Reset} onClick={onReset}>
+        {t('resetToPatient', 'Reset to patient details')}
+      </Button>
+    </div>
+  );
+};
+
+export default PcsEmptyState;

package/src/search/pcs-results-skeleton.component.tsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import { SkeletonText } from '@carbon/react';
+import styles from '../pcs.scss';
+
+interface PcsResultsSkeletonProps {
+  /** How many placeholder tiles to show. */
+  count?: number;
+}
+
+const PcsResultsSkeleton: React.FC<PcsResultsSkeletonProps> = ({ count = 3 }) => (
+  <div className={styles.pcsLoading}>
+    {Array.from({ length: count }).map((_, index) => (
+      <div className={styles.pcsSkeletonTile} key={`pcs-skeleton-${index}`}>
+        <SkeletonText heading width="60%" />
+        <SkeletonText paragraph lineCount={3} />
+      </div>
+    ))}
+  </div>
+);
+
+export default PcsResultsSkeleton;

package/src/search/pcs-search.component.test.tsx

@@ -0,0 +1,169 @@
+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 PCSSearchResults from './pcs-search.component';
+import { usePcsParticipantSearch } from '../resources/pcs.resource';
+import { usePatientStudyLink } from '../resources/link-participant.resource';
+import { type PcsSearchSubject } from '../types';
+
+vi.mock('@openmrs/esm-framework', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@openmrs/esm-framework')>()),
+  ErrorState: () => null,
+  useConfig: () => ({
+    pcsIdentifiers: { studyParticipantID: 'study-id-type-uuid', studyTemporaryParticipantID: '' },
+    pcsAttributeTypes: { pbidsEnrollmentStatus: 'pbids-uuid', cardseEnrollmentStatus: 'cardse-uuid' },
+  }),
+}));
+
+// The pane checks whether the patient is already linked before deciding what to render.
+vi.mock('../resources/link-participant.resource', () => ({ usePatientStudyLink: vi.fn() }));
+
+vi.mock('../linked/linked-participant.component', () => ({
+  default: ({ studyParticipantId }: any) => <span>{`Linked view for ${studyParticipantId}`}</span>,
+}));
+
+// Interpolates, unlike the bare fallback mock used elsewhere — the tag labels under test
+// are built from `{{value}}`.
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (_key: string, fallback: string, options?: Record<string, unknown>) =>
+      fallback.replace(/{{(\w+)}}/g, (_match, name) => String(options?.[name] ?? '')),
+  }),
+}));
+
+// The boundary that receives the committed filters. Keeping the rest of the module real
+// means `toPcsParticipantFilters` and `hasAnyFilter` still drive the component.
+vi.mock('../resources/pcs.resource', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../resources/pcs.resource')>()),
+  usePcsParticipantSearch: vi.fn(),
+}));
+
+vi.mock('./participant-tile.component', () => ({ default: () => null }));
+
+const mockUsePcsParticipantSearch = vi.mocked(usePcsParticipantSearch);
+const mockUsePatientStudyLink = vi.mocked(usePatientStudyLink);
+
+const subject: PcsSearchSubject = {
+  id: 'patient-uuid',
+  source: 'local',
+  patient: { resourceType: 'Patient', id: 'patient-uuid' },
+  name: 'Mary Akinyi Odongo',
+  gender: 'female',
+  birthDate: '1991-04-12',
+  nationalId: '12345678',
+  phoneNumber: '0712345678',
+};
+
+const committedFilters = () => mockUsePcsParticipantSearch.mock.calls.at(-1)?.[0];
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockUsePatientStudyLink.mockReturnValue({
+    localPatient: null,
+    studyParticipantId: undefined,
+    isLoading: false,
+    error: undefined,
+    mutate: vi.fn(),
+  } as any);
+  mockUsePcsParticipantSearch.mockReturnValue({
+    participants: [],
+    totalCount: 0,
+    isLoading: false,
+    error: undefined,
+  });
+});
+
+describe('PCS filter bar', () => {
+  it('searches on the patient demographics, tagging what was derived for you', () => {
+    render(<PCSSearchResults subject={subject} />);
+
+    expect(committedFilters()).toEqual({ name: 'Mary Akinyi Odongo', village: '', phone: '0712345678' });
+    expect(screen.getByText('Name: Mary Akinyi Odongo')).toBeInTheDocument();
+    expect(screen.getByText('Phone: 0712345678')).toBeInTheDocument();
+    // Village is the search box, so it never appears as a tag — and a patient carries no
+    // village, so the box starts empty.
+    expect(screen.getByPlaceholderText('Village name')).toHaveValue('');
+    expect(screen.queryByText(/^Village:/)).not.toBeInTheDocument();
+  });
+
+  it('dismissing the name tag drops that filter and re-searches immediately', async () => {
+    const user = userEvent.setup();
+    render(<PCSSearchResults subject={subject} />);
+
+    await user.click(screen.getByRole('button', { name: 'Remove Name: Mary Akinyi Odongo' }));
+
+    expect(committedFilters()).toEqual({ name: '', village: '', phone: '0712345678' });
+    expect(screen.queryByText('Name: Mary Akinyi Odongo')).not.toBeInTheDocument();
+    expect(screen.getByText('Phone: 0712345678')).toBeInTheDocument();
+  });
+
+  it('searches the village typed into the box without tagging it', async () => {
+    const user = userEvent.setup();
+    render(<PCSSearchResults subject={subject} />);
+
+    await user.type(screen.getByPlaceholderText('Village name'), 'KAMBI{Enter}');
+
+    expect(committedFilters()).toEqual({ name: 'Mary Akinyi Odongo', village: 'KAMBI', phone: '0712345678' });
+    expect(screen.queryByText('Village: KAMBI')).not.toBeInTheDocument();
+  });
+
+  it('discards an uncommitted name edit when the panel is collapsed', async () => {
+    const user = userEvent.setup();
+    render(<PCSSearchResults subject={subject} />);
+
+    await user.click(screen.getByRole('button', { name: 'Edit filters' }));
+    await user.clear(screen.getByLabelText('Name'));
+    await user.type(screen.getByLabelText('Name'), 'Someone Else');
+    await user.click(screen.getByRole('button', { name: 'Hide filters' }));
+
+    // Never searched, so it must not appear as a tag describing the results.
+    expect(screen.queryByText('Name: Someone Else')).not.toBeInTheDocument();
+    expect(screen.getByText('Name: Mary Akinyi Odongo')).toBeInTheDocument();
+    expect(committedFilters()).toEqual({ name: 'Mary Akinyi Odongo', village: '', phone: '0712345678' });
+  });
+
+  it('commits an edited name on submit and tags it', async () => {
+    const user = userEvent.setup();
+    render(<PCSSearchResults subject={subject} />);
+
+    await user.click(screen.getByRole('button', { name: 'Edit filters' }));
+    await user.clear(screen.getByLabelText('Name'));
+    await user.type(screen.getByLabelText('Name'), 'Someone Else');
+    await user.click(screen.getByRole('button', { name: 'Search' }));
+
+    expect(committedFilters()).toEqual({ name: 'Someone Else', village: '', phone: '0712345678' });
+
+    await user.click(screen.getByRole('button', { name: 'Hide filters' }));
+    expect(screen.getByText('Name: Someone Else')).toBeInTheDocument();
+  });
+
+  it('opens the panel and stops searching once every filter is gone', async () => {
+    const user = userEvent.setup();
+    render(<PCSSearchResults subject={{ ...subject, phoneNumber: null }} />);
+
+    await user.click(screen.getByRole('button', { name: 'Remove Name: Mary Akinyi Odongo' }));
+
+    expect(committedFilters()).toEqual({ name: '', village: '', phone: '' });
+    expect(screen.getByText('Add a filter to search the PCS registry')).toBeInTheDocument();
+    // The panel opens itself so there are fields to type into.
+    expect(screen.getByLabelText('Name')).toBeInTheDocument();
+  });
+
+  it('reports on the linked participant instead of searching when the patient has a study ID', () => {
+    mockUsePatientStudyLink.mockReturnValue({
+      localPatient: { uuid: 'local-uuid' },
+      studyParticipantId: '901-1-1-3',
+      isLoading: false,
+      error: undefined,
+      mutate: vi.fn(),
+    } as any);
+
+    render(<PCSSearchResults subject={subject} />);
+
+    expect(screen.getByText('Linked view for 901-1-1-3')).toBeInTheDocument();
+    // The filter bar is gone entirely — the pane is reporting, not searching.
+    expect(screen.queryByPlaceholderText('Village name')).not.toBeInTheDocument();
+  });
+});