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

package/src/shr/shr-viewer/shr-categories.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Tests for bucketing SHR resources into viewer tabs — in particular that an
+ * Observation category nobody configured is still shown, under its own name,
+ * rather than folded into an unrelated tab.
+ *
+ * The category codes used here are the ones this SHR's own Observation profiles
+ * actually fix: the standard `vital-signs`, `exam` and `survey`, plus
+ * `caller-reported` from its site-specific `em-observation-category` system.
+ */
+import { buildCategories, categoryCodings, hasCategoryCode } from './shr-categories';
+import type { ShrResourceTypeConfig } from '../../config-schema';
+import type { ShrAnyResource } from '../shr.types';
+
+const HL7_CATEGORY = 'http://terminology.hl7.org/CodeSystem/observation-category';
+const SHA_CATEGORY = 'https://nshr-uat.sha.go.ke/fhir/CodeSystem/em-observation-category';
+
+const UNCATEGORISED = { uncategorisedLabel: 'Uncategorised' };
+
+/** The shipped default: three named Observation categories plus a catch-all. */
+const configured: ShrResourceTypeConfig[] = [
+  { resourceType: 'Encounter', label: 'Encounters' },
+  { resourceType: 'Observation', label: 'Vitals', categoryCode: 'vital-signs' },
+  { resourceType: 'Observation', label: 'Exam findings', categoryCode: 'exam' },
+  { resourceType: 'Observation', label: 'Lab results', categoryCode: 'laboratory' },
+  { resourceType: 'Observation', label: 'Other observations' },
+];
+
+function observation(id: string, category?: { system: string; code: string; display?: string }): ShrAnyResource {
+  return {
+    resourceType: 'Observation',
+    id,
+    status: 'final',
+    ...(category ? { category: [{ coding: [category] }] } : {}),
+  } as any;
+}
+
+/** label → count, for terse assertions about the resulting tab strip. */
+function counts(categories: ReturnType<typeof buildCategories>) {
+  return categories.map((c) => [c.label, c.resources.length] as const);
+}
+
+describe('categoryCodings / hasCategoryCode', () => {
+  it('reads every coding that carries a code', () => {
+    const resource = observation('o1', { system: HL7_CATEGORY, code: 'vital-signs' });
+    expect(categoryCodings(resource).map((c) => c.code)).toEqual(['vital-signs']);
+    expect(hasCategoryCode(resource, 'vital-signs')).toBe(true);
+    expect(hasCategoryCode(resource, 'exam')).toBe(false);
+  });
+
+  it('treats a resource with no category, or a coding with no code, as uncategorised', () => {
+    expect(categoryCodings(observation('o2'))).toEqual([]);
+    expect(hasCategoryCode(observation('o2'), 'exam')).toBe(false);
+    expect(categoryCodings({ resourceType: 'Observation', category: [{ coding: [{}] }] } as any)).toEqual([]);
+  });
+
+  it('reads AllergyIntolerance categories, which are plain codes rather than CodeableConcepts', () => {
+    // R4 binds AllergyIntolerance.category to `code`, not CodeableConcept —
+    // `["medication"]`, not `[{ coding: [...] }]`. A site splitting allergies
+    // by categoryCode must not silently get an empty match.
+    const allergy = { resourceType: 'AllergyIntolerance', id: 'a1', category: ['medication'] } as any;
+    expect(categoryCodings(allergy).map((c) => c.code)).toEqual(['medication']);
+    expect(hasCategoryCode(allergy, 'medication')).toBe(true);
+    expect(hasCategoryCode(allergy, 'environment')).toBe(false);
+  });
+});
+
+describe('buildCategories', () => {
+  it('routes each observation to its configured category', () => {
+    const categories = buildCategories(
+      [
+        observation('v', { system: HL7_CATEGORY, code: 'vital-signs' }),
+        observation('e', { system: HL7_CATEGORY, code: 'exam' }),
+        observation('l', { system: HL7_CATEGORY, code: 'laboratory' }),
+      ],
+      configured,
+      UNCATEGORISED,
+    );
+
+    expect(counts(categories)).toEqual([
+      ['Encounters', 0],
+      ['Vitals', 1],
+      ['Exam findings', 1],
+      ['Lab results', 1],
+      ['Other observations', 0],
+    ]);
+  });
+
+  it('gives an unconfigured standard category its own tab instead of mislabelling it', () => {
+    // `survey` is what this SHR's triage-acuity profile fixes, and nothing in
+    // the config claims it. Before this it landed under the catch-all, which
+    // read "Lab results" — a triage score displayed as a lab result.
+    const categories = buildCategories(
+      [observation('t', { system: HL7_CATEGORY, code: 'survey' })],
+      configured,
+      UNCATEGORISED,
+    );
+
+    expect(counts(categories)).toContainEqual(['Survey', 1]);
+    expect(counts(categories)).toContainEqual(['Lab results', 0]);
+    expect(counts(categories)).toContainEqual(['Other observations', 0]);
+  });
+
+  it('labels a discovered category from the payload’s own display when it has one', () => {
+    const categories = buildCategories(
+      [observation('c', { system: SHA_CATEGORY, code: 'caller-reported', display: 'Reported by caller' })],
+      configured,
+      UNCATEGORISED,
+    );
+
+    // Distinct from the bundled display ("Caller reported"), so this really does
+    // prove the payload's own display wins.
+    expect(counts(categories)).toContainEqual(['Reported by caller', 1]);
+  });
+
+  it('falls back to a readable form of a code it cannot resolve a display for', () => {
+    const categories = buildCategories(
+      [observation('s', { system: HL7_CATEGORY, code: 'social-history' })],
+      configured,
+      UNCATEGORISED,
+    );
+
+    expect(counts(categories)).toContainEqual(['Social history', 1]);
+  });
+
+  it('groups every observation sharing a discovered code into one tab, sorted by label', () => {
+    const categories = buildCategories(
+      [
+        observation('c1', { system: SHA_CATEGORY, code: 'emt-assessed' }),
+        observation('t1', { system: HL7_CATEGORY, code: 'survey' }),
+        observation('c2', { system: SHA_CATEGORY, code: 'emt-assessed' }),
+      ],
+      configured,
+      UNCATEGORISED,
+    );
+
+    // `emt-assessed` resolves to its bundled display rather than a humanised code.
+    const discovered = counts(categories).filter(([label]) =>
+      ['Emergency practitioner assessed', 'Survey'].includes(label),
+    );
+    expect(discovered).toEqual([
+      ['Emergency practitioner assessed', 2],
+      ['Survey', 1],
+    ]);
+  });
+
+  it('sends only genuinely uncategorised observations to the catch-all', () => {
+    const categories = buildCategories(
+      [
+        observation('none'),
+        observation('v', { system: HL7_CATEGORY, code: 'vital-signs' }),
+        observation('t', { system: HL7_CATEGORY, code: 'survey' }),
+      ],
+      configured,
+      UNCATEGORISED,
+    );
+
+    expect(counts(categories)).toContainEqual(['Other observations', 1]);
+    expect(counts(categories)).toContainEqual(['Vitals', 1]);
+    expect(counts(categories)).toContainEqual(['Survey', 1]);
+  });
+
+  it('still holds every resource type nothing splits by category', () => {
+    const categories = buildCategories(
+      [
+        { resourceType: 'Encounter', id: 'e1' } as any,
+        // A category on a type nobody split must not change where it goes.
+        { resourceType: 'Encounter', id: 'e2', category: [{ coding: [{ code: 'whatever' }] }] } as any,
+      ],
+      configured,
+      UNCATEGORISED,
+    );
+
+    expect(counts(categories)).toContainEqual(['Encounters', 2]);
+  });
+
+  it('never drops a record, even with no catch-all configured for a split type', () => {
+    const noCatchAll: ShrResourceTypeConfig[] = [
+      { resourceType: 'Observation', label: 'Vitals', categoryCode: 'vital-signs' },
+    ];
+    const categories = buildCategories(
+      [observation('none'), observation('v', { system: HL7_CATEGORY, code: 'vital-signs' })],
+      noCatchAll,
+      UNCATEGORISED,
+    );
+
+    expect(counts(categories)).toEqual([
+      ['Vitals', 1],
+      ['Uncategorised', 1],
+    ]);
+    const total = categories.reduce((sum, c) => sum + c.resources.length, 0);
+    expect(total).toBe(2);
+  });
+
+  it('files a resource carrying two configured codes under the earlier one only', () => {
+    const both = {
+      resourceType: 'Observation',
+      id: 'both',
+      category: [{ coding: [{ system: HL7_CATEGORY, code: 'exam' }] }, { coding: [{ code: 'vital-signs' }] }],
+    } as any;
+
+    const categories = buildCategories([both], configured, UNCATEGORISED);
+
+    // Vitals is configured before Exam findings, so it claims it — and it is
+    // claimed exactly once, not shown under both.
+    expect(counts(categories)).toContainEqual(['Vitals', 1]);
+    expect(counts(categories)).toContainEqual(['Exam findings', 0]);
+    expect(categories.reduce((sum, c) => sum + c.resources.length, 0)).toBe(1);
+  });
+
+  it('ignores resource types the viewer was not configured to show', () => {
+    const categories = buildCategories([{ resourceType: 'Patient', id: 'p1' } as any], configured, UNCATEGORISED);
+
+    expect(categories.every((c) => c.resourceType !== 'Patient')).toBe(true);
+    expect(categories.reduce((sum, c) => sum + c.resources.length, 0)).toBe(0);
+  });
+
+  it('splits a site-configured AllergyIntolerance category tab, with an unconfigured one still discovered', () => {
+    const allergyConfig: ShrResourceTypeConfig[] = [
+      { resourceType: 'AllergyIntolerance', label: 'Drug allergies', categoryCode: 'medication' },
+      { resourceType: 'AllergyIntolerance', label: 'Other allergies' },
+    ];
+    const categories = buildCategories(
+      [
+        { resourceType: 'AllergyIntolerance', id: 'a1', category: ['medication'] } as any,
+        { resourceType: 'AllergyIntolerance', id: 'a2', category: ['environment'] } as any,
+        { resourceType: 'AllergyIntolerance', id: 'a3' } as any,
+      ],
+      allergyConfig,
+      UNCATEGORISED,
+    );
+
+    // The same rules as the Observation splits: the configured code claims its
+    // matches, an unconfigured code gets its own discovered tab, and only a
+    // category-less resource lands on the configured catch-all.
+    expect(counts(categories)).toEqual([
+      ['Drug allergies', 1],
+      ['Other allergies', 1],
+      ['Environment', 1],
+    ]);
+  });
+});

package/src/shr/shr-viewer/shr-categories.ts

@@ -0,0 +1,209 @@
+import type { ShrResourceTypeConfig } from '../../config-schema';
+import type { ShrAnyResource, ShrCodeableConcept, ShrCoding } from '../shr.types';
+import { lookupCodeDisplay } from '../shr-terminology.resource';
+import { humanise } from './shr-presentation';
+
+/**
+ * Grouping of SHR resources into the viewer's category tabs.
+ *
+ * FHIR does not model "kind of observation" as a resource type — every reading,
+ * exam finding, lab result and questionnaire answer is an `Observation`, told
+ * apart by `Observation.category`. R4 binds that element to the
+ * `observation-category` value set (`social-history`, `vital-signs`, `imaging`,
+ * `laboratory`, `procedure`, `survey`, `exam`, `therapy`, `activity`), but the
+ * binding is *preferred*, not required, so an implementer may add their own
+ * codes — and this SHR does: alongside the standard `vital-signs`, `exam` and
+ * `survey`, its own `em-observation-category` system defines `caller-reported`
+ * and `emt-assessed`.
+ *
+ * So the set of categories cannot be pinned down in config: a fixed list is
+ * either incomplete now or goes stale the next time the SHR adds a profile, and
+ * the failure mode is silent mislabelling — an imaging or triage observation
+ * displayed under whichever category happened to be the catch-all. Instead,
+ * config curates the categories worth naming and ordering deliberately, and
+ * anything else present in the payload is discovered from the data and labelled
+ * for what it actually is.
+ */
+
+export interface ShrCategory {
+  resourceType: string;
+  /** The `category` code this tab holds, when it is scoped to one. */
+  categoryCode?: string;
+  label: string;
+  resources: ShrAnyResource[];
+}
+
+/**
+ * Every category coding on a resource that carries an actual code, in order.
+ *
+ * Two element shapes occur: `Observation.category` is CodeableConcept[], but
+ * `AllergyIntolerance.category` is an array of plain FHIR codes
+ * (`"medication"`, `"environment"` — R4 binds it to a code, not a concept). A
+ * site splitting either type by `categoryCode` must have both work, so bare
+ * strings are read as codings of their own.
+ */
+export function categoryCodings(resource: ShrAnyResource): ShrCoding[] {
+  const concepts = (resource as any)?.category as Array<ShrCodeableConcept | string> | undefined;
+  return (concepts ?? [])
+    .flatMap((concept) => {
+      if (typeof concept === 'string') {
+        return concept ? [{ code: concept }] : [];
+      }
+      return concept?.coding ?? [];
+    })
+    .filter((coding): coding is ShrCoding => Boolean(coding?.code));
+}
+
+/** True when `resource.category[].coding[]` carries the given code, e.g. "vital-signs" or "exam". */
+export function hasCategoryCode(resource: ShrAnyResource, code: string): boolean {
+  return categoryCodings(resource).some((coding) => coding.code === code);
+}
+
+/**
+ * Clinician-facing name for a category nobody configured a label for: what the
+ * payload itself said, else the display from the bundled copy of the coding's
+ * own code system (see `shr-terminology.resource`), else the code made readable
+ * ("social-history" → "Social history").
+ *
+ * The middle step is what turns this SHR's `emt-assessed` into "Emergency
+ * practitioner assessed" — a display the humanised code could not have reached.
+ * Codes from systems we don't carry, HL7's own among them, fall through to
+ * humanising, which reads correctly for them anyway.
+ */
+function discoveredLabel(coding: ShrCoding): string {
+  return coding.display?.trim() || lookupCodeDisplay(coding.system, coding.code) || humanise(coding.code);
+}
+
+/**
+ * Bucket `resources` into display categories.
+ *
+ * Precedence, and why:
+ *  1. Configured entries scoped to a `categoryCode` claim their matches first,
+ *     in config order — so a site's curated wording and ordering always wins,
+ *     and a resource carrying two configured codes lands in the earlier tab
+ *     rather than an arbitrary one.
+ *  2. A configured entry with no `categoryCode` is the type's catch-all. For a
+ *     type nobody split by category it keeps its plain meaning of "everything of
+ *     this type"; for a split type it means "carries no category at all", since
+ *     coded leftovers are better served by (3) than by being folded into an
+ *     unrelated label.
+ *  3. Whatever is left carrying a category code becomes its own category, one
+ *     per distinct code, labelled from the data. This is what keeps an
+ *     unconfigured category (`survey`, `caller-reported`, a code added upstream
+ *     tomorrow) visible and correctly named instead of mislabelled.
+ *  4. Anything still unclaimed is emitted under `uncategorisedLabel`. Reachable
+ *     only when a split type has no configured catch-all, and present so that a
+ *     record can never be silently dropped from a health record view.
+ *
+ * Resource types absent from `configured` are not returned at all — the fetch
+ * only asks for configured types, so anything else is not something the viewer
+ * was asked to show.
+ */
+export function buildCategories(
+  resources: ShrAnyResource[],
+  configured: ShrResourceTypeConfig[],
+  { uncategorisedLabel }: { uncategorisedLabel: string },
+): ShrCategory[] {
+  const byType = new Map<string, ShrAnyResource[]>();
+  resources.forEach((resource) => {
+    const type = resource?.resourceType;
+    if (!type) {
+      return;
+    }
+    const bucket = byType.get(type);
+    if (bucket) {
+      bucket.push(resource);
+    } else {
+      byType.set(type, [resource]);
+    }
+  });
+
+  const claimed = new Set<ShrAnyResource>();
+  const claimedBy = new Map<ShrResourceTypeConfig, ShrAnyResource[]>();
+  /** Types the site has opted into splitting by category. */
+  const splitTypes = new Set(configured.filter((c) => c.categoryCode).map((c) => c.resourceType));
+
+  // (1) Configured, category-scoped entries.
+  configured
+    .filter((config) => config.categoryCode)
+    .forEach((config) => {
+      const pool = byType.get(config.resourceType) ?? [];
+      const matched = pool.filter((r) => !claimed.has(r) && hasCategoryCode(r, config.categoryCode!));
+      matched.forEach((r) => claimed.add(r));
+      claimedBy.set(config, matched);
+    });
+
+  // (2) Configured catch-alls.
+  configured
+    .filter((config) => !config.categoryCode)
+    .forEach((config) => {
+      const pool = byType.get(config.resourceType) ?? [];
+      const matched = pool.filter(
+        (r) => !claimed.has(r) && (!splitTypes.has(config.resourceType) || categoryCodings(r).length === 0),
+      );
+      matched.forEach((r) => claimed.add(r));
+      claimedBy.set(config, matched);
+    });
+
+  const categories: ShrCategory[] = configured.map((config) => ({
+    resourceType: config.resourceType,
+    categoryCode: config.categoryCode || undefined,
+    label: config.label,
+    resources: claimedBy.get(config) ?? [],
+  }));
+
+  // (3) Categories discovered in the data. Keyed by type + code; a resource
+  // carrying several unconfigured codes is filed under its first, so that it
+  // lands somewhere predictable rather than being duplicated across tabs.
+  const discovered = new Map<string, { coding: ShrCoding; resourceType: string; resources: ShrAnyResource[] }>();
+  byType.forEach((pool, type) => {
+    if (!splitTypes.has(type)) {
+      return;
+    }
+    pool.forEach((resource) => {
+      if (claimed.has(resource)) {
+        return;
+      }
+      const [coding] = categoryCodings(resource);
+      if (!coding) {
+        return;
+      }
+      claimed.add(resource);
+      const key = `${type}|${coding.code}`;
+      const bucket = discovered.get(key);
+      if (bucket) {
+        bucket.resources.push(resource);
+      } else {
+        discovered.set(key, { coding, resourceType: type, resources: [resource] });
+      }
+    });
+  });
+
+  categories.push(
+    ...Array.from(discovered.values())
+      .map((entry) => ({
+        resourceType: entry.resourceType,
+        categoryCode: entry.coding.code,
+        label: discoveredLabel(entry.coding),
+        resources: entry.resources,
+      }))
+      // Alphabetical, so a discovered tab's position doesn't shift with the
+      // order resources happened to arrive in.
+      .sort((a, b) => a.label.localeCompare(b.label)),
+  );
+
+  // (4) Safety net — see the precedence note above.
+  byType.forEach((pool, type) => {
+    if (!splitTypes.has(type)) {
+      return;
+    }
+    const leftover = pool.filter((r) => !claimed.has(r));
+    if (!leftover.length) {
+      return;
+    }
+    leftover.forEach((r) => claimed.add(r));
+    categories.push({ resourceType: type, label: uncategorisedLabel, resources: leftover });
+  });
+
+  return categories;
+}