@openmrs/esm-report-builder 0.1.1-pre.87

package/src/hooks/use-report-builder-privileges.test.tsx

@@ -0,0 +1,98 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+
+import { useSession } from '@openmrs/esm-framework';
+import { useReportBuilderPrivileges } from './use-report-builder-privileges';
+import { RB } from '../constants/privileges';
+
+jest.mock('@openmrs/esm-framework', () => ({
+    useSession: jest.fn(),
+}));
+
+const mockUseSession = useSession as unknown as jest.Mock;
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+const priv = (name: string) => ({ uuid: name, name, display: name });
+
+function renderHook<T>(hook: () => T): { current: T | undefined; rerender: () => void; unmount: () => void } {
+    const container = document.createElement('div');
+    const root = createRoot(container);
+    let current: T | undefined;
+    const Probe = () => {
+        current = hook();
+        return null;
+    };
+    const render = () => act(() => {
+        root.render(React.createElement(Probe));
+    });
+    render();
+    return {
+        get current() {
+            return current;
+        },
+        rerender: render,
+        unmount: () => act(() => root.unmount()),
+    };
+}
+
+function sessionWith(privileges: string[], roles: string[] = [], authenticated = true) {
+    return {
+        authenticated,
+        user: {
+            uuid: 'u-1',
+            display: 'User',
+            privileges: privileges.map(priv),
+            roles: roles.map((r) => ({ uuid: r, display: r })),
+        },
+    } as any;
+}
+
+describe('useReportBuilderPrivileges', () => {
+    it('matches held privileges by name', () => {
+        mockUseSession.mockReturnValue(sessionWith([RB.REPORT_VIEW]));
+        const { current, unmount } = renderHook(() => useReportBuilderPrivileges());
+        expect(current!.has(RB.REPORT_VIEW)).toBe(true);
+        expect(current!.has(RB.REPORT_EDIT)).toBe(false);
+        expect(current!.isAuthenticated).toBe(true);
+        unmount();
+    });
+
+    it('uses OR semantics like the backend @Authorized({a, b})', () => {
+        mockUseSession.mockReturnValue(sessionWith([RB.REPORT_ADD]));
+        const { current, unmount } = renderHook(() => useReportBuilderPrivileges());
+        expect(current!.has(RB.REPORT_ADD, RB.REPORT_EDIT)).toBe(true);
+        expect(current!.hasAll(RB.REPORT_ADD, RB.REPORT_EDIT)).toBe(false);
+        unmount();
+    });
+
+    it('treats the System Developer role as superuser', () => {
+        mockUseSession.mockReturnValue(sessionWith([], ['System Developer']));
+        const { current, unmount } = renderHook(() => useReportBuilderPrivileges());
+        expect(current!.isSuperUser).toBe(true);
+        expect(current!.has(RB.ETLMONITOR_PURGE)).toBe(true);
+        expect(current!.hasAll(RB.PACKAGE_IMPORT, RB.PACKAGE_EXPORT)).toBe(true);
+        unmount();
+    });
+
+    it('exposes convenience flags', () => {
+        mockUseSession.mockReturnValue(
+            sessionWith([RB.REPORT_VIEW, RB.REPORT_RUN, RB.PACKAGE_EXPORT]),
+        );
+        const { current, unmount } = renderHook(() => useReportBuilderPrivileges());
+        expect(current!.canAuthor).toBe(false);
+        expect(current!.canRun).toBe(true);
+        expect(current!.canPublish).toBe(true);
+        expect(current!.canManageEtl).toBe(false);
+        unmount();
+    });
+
+    it('is false on everything for an unauthenticated session', () => {
+        mockUseSession.mockReturnValue({ authenticated: false, user: undefined });
+        const { current, unmount } = renderHook(() => useReportBuilderPrivileges());
+        expect(current!.isAuthenticated).toBe(false);
+        expect(current!.has(RB.REPORT_VIEW)).toBe(false);
+        unmount();
+    });
+});

package/src/hooks/use-report-builder-privileges.ts

@@ -0,0 +1,58 @@
+import { useCallback, useMemo } from 'react';
+import { useSession } from '@openmrs/esm-framework';
+import { RB } from '../constants/privileges';
+
+const SUPERUSER_ROLE = 'System Developer';
+
+/**
+ * Privileges of the signed-in user, as resolved by the backend session endpoint
+ * (inherited roles already expanded). Backed by the framework session store —
+ * the same fetch the SPA shell and headers already use — so there is no extra
+ * network call and values refresh automatically on re-login.
+ *
+ * `has` uses OR semantics: has(RB.REPORT_ADD, RB.REPORT_EDIT) is true when the
+ * user holds either, mirroring the backend's @Authorized({a, b}) behaviour.
+ */
+export function useReportBuilderPrivileges() {
+    const session = useSession();
+    const user = session?.user;
+
+    const held = useMemo(() => {
+        const names = new Set<string>();
+        for (const privilege of user?.privileges ?? []) {
+            names.add(privilege.name);
+            names.add(privilege.display);
+        }
+        return names;
+    }, [user]);
+
+    const isSuperUser = useMemo(
+        () => !!user?.roles?.some((role) => role.display === SUPERUSER_ROLE),
+        [user],
+    );
+
+    const has = useCallback(
+        (...needed: string[]) =>
+            needed.length === 0 || isSuperUser || needed.some((privilege) => held.has(privilege)),
+        [held, isSuperUser],
+    );
+
+    const hasAll = useCallback(
+        (...needed: string[]) =>
+            needed.length === 0 || isSuperUser || needed.every((privilege) => held.has(privilege)),
+        [held, isSuperUser],
+    );
+
+    return {
+        /** has(RB.X, RB.Y) — true when the user holds ANY of the privileges. */
+        has,
+        /** hasAll(RB.X, RB.Y) — true only when the user holds ALL of the privileges. */
+        hasAll,
+        isSuperUser,
+        isAuthenticated: !!session?.authenticated,
+        canAuthor: has(RB.REPORT_ADD, RB.REPORT_EDIT),
+        canRun: has(RB.REPORT_RUN),
+        canPublish: has(RB.PACKAGE_IMPORT, RB.PACKAGE_EXPORT),
+        canManageEtl: has(RB.ETLSOURCE_ADD, RB.ETLSOURCE_EDIT, RB.ETLMONITOR_ADD, RB.ETLMONITOR_EDIT),
+    };
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+import { defineConfigSchema, getAsyncLifecycle } from '@openmrs/esm-framework';
+import { configSchema } from './config-schema';
+
+const moduleName = '@openmrs/esm-report-builder';
+
+const options = {
+  featureName: 'report-builder',
+  moduleName,
+};
+
+export const reportBuilderAdminLink = getAsyncLifecycle(
+  () => import('./admin-card-link.extension'),
+  options,
+);
+
+// Optional but recommended if you add translations folder
+export const importTranslation = require.context('../translations', true, /.json$/, 'lazy');
+
+export const root = getAsyncLifecycle(() => import('./root.component'), options);
+
+// Data Visualizer confirm modal (used for sending reports to DHIS2)
+export const confirmModal = getAsyncLifecycle(
+  () => import('./components/data-visualizer/components/model/confirm.component'),
+  options
+);
+
+export function startupApp() {
+  defineConfigSchema(moduleName, configSchema);
+}

package/src/resources/address-template/address-template.api.ts

@@ -0,0 +1,180 @@
+/**
+ * Address Template API
+ *
+ * Fetches and parses the OpenMRS address template configuration.
+ * The address template is stored in the system setting "layout.address.format"
+ * and defines the mapping between standard OpenMRS address fields and
+ * implementation-specific names (e.g., UgandaEMR: address5 → Village).
+ */
+
+import { omrsGet } from '../openmrs-api';
+
+/**
+ * Parsed address field mapping
+ */
+export type AddressFieldMapping = {
+  /** Standard OpenMRS field name (e.g., "address5", "stateProvince") */
+  field: string;
+  /** Implementation-specific label (e.g., "ugandaemr.address.village") */
+  label: string;
+  /** Display name extracted from label (e.g., "Village") */
+  display: string;
+};
+
+/**
+ * Address template configuration
+ */
+export type AddressTemplate = {
+  /** Mappings of field names to labels */
+  nameMappings: AddressFieldMapping[];
+  /** Size mappings for each field */
+  sizeMappings: Record<string, number>;
+  /** Default values for fields */
+  elementDefaults: Record<string, string>;
+  /** Ordered list of fields for line-by-line format */
+  lineByLineFormat: string[];
+};
+
+/**
+ * Parse XML string to extract address template configuration
+ */
+function parseAddressTemplateXml(xmlString: string): AddressTemplate {
+  const parser = new DOMParser();
+  const xmlDoc = parser.parseFromString(xmlString, 'text/xml');
+
+  // Parse nameMappings
+  const nameMappings: AddressFieldMapping[] = [];
+  const entryNodes = xmlDoc.querySelectorAll('nameMappings entry');
+
+  entryNodes.forEach((entry) => {
+    const fieldNode = entry.querySelector('string');
+    if (!fieldNode) return;
+
+    const field = fieldNode.textContent?.trim();
+    const labelNode = entry.querySelectorAll('string')[1];
+    const label = labelNode?.textContent?.trim();
+
+    if (field && label) {
+      // Extract display name from label (e.g., "ugandaemr.address.village" → "Village")
+      const parts = label.split('.');
+      const display = parts[parts.length - 1] || field;
+
+      nameMappings.push({
+        field,
+        label,
+        display: display.charAt(0).toUpperCase() + display.slice(1),
+      });
+    }
+  });
+
+  // Parse sizeMappings
+  const sizeMappings: Record<string, number> = {};
+  const sizeEntries = xmlDoc.querySelectorAll('sizeMappings entry');
+
+  sizeEntries.forEach((entry) => {
+    const fieldNode = entry.querySelector('string');
+    const sizeNode = entry.querySelectorAll('string')[1];
+
+    const field = fieldNode?.textContent?.trim();
+    const size = sizeNode?.textContent?.trim();
+
+    if (field && size) {
+      sizeMappings[field] = parseInt(size, 10);
+    }
+  });
+
+  // Parse elementDefaults
+  const elementDefaults: Record<string, string> = {};
+  const defaultEntries = xmlDoc.querySelectorAll('elementDefaults entry');
+
+  defaultEntries.forEach((entry) => {
+    const fieldNode = entry.querySelector('string');
+    const valueNode = entry.querySelectorAll('string')[1];
+
+    const field = fieldNode?.textContent?.trim();
+    const value = valueNode?.textContent?.trim();
+
+    if (field && value) {
+      elementDefaults[field] = value;
+    }
+  });
+
+  // Parse lineByLineFormat
+  const lineByLineFormat: string[] = [];
+  const formatNodes = xmlDoc.querySelectorAll('lineByLineFormat string');
+
+  formatNodes.forEach((node) => {
+    const value = node.textContent?.trim();
+    if (value) {
+      lineByLineFormat.push(value);
+    }
+  });
+
+  return {
+    nameMappings,
+    sizeMappings,
+    elementDefaults,
+    lineByLineFormat,
+  };
+}
+
+/**
+ * Fetch address template from OpenMRS system setting
+ */
+export async function getAddressTemplate(): Promise<AddressTemplate> {
+  try {
+    const response = await omrsGet<any>(
+      '/systemsetting?q=layout.address.format&v=full'
+    );
+
+    // Extract the value from the response
+    const xmlValue = response?.results?.[0]?.value;
+
+    if (!xmlValue) {
+      console.warn('No address template found in system settings');
+      return getDefaultAddressTemplate();
+    }
+
+    return parseAddressTemplateXml(xmlValue);
+  } catch (error) {
+    console.error('Failed to fetch address template:', error);
+    return getDefaultAddressTemplate();
+  }
+}
+
+/**
+ * Get default address template (fallback)
+ * Uses standard OpenMRS address field names
+ */
+function getDefaultAddressTemplate(): AddressTemplate {
+  return {
+    nameMappings: [
+      { field: 'address1', label: 'Address Line 1', display: 'Address 1' },
+      { field: 'address2', label: 'Address Line 2', display: 'Address 2' },
+      { field: 'address3', label: 'Address 3', display: 'Address 3' },
+      { field: 'address4', label: 'Address 4', display: 'Address 4' },
+      { field: 'address5', label: 'Address 5', display: 'Address 5' },
+      { field: 'cityVillage', label: 'City/Village', display: 'City/Village' },
+      { field: 'stateProvince', label: 'State/Province', display: 'State' },
+      { field: 'countyDistrict', label: 'County/District', display: 'District' },
+      { field: 'country', label: 'Country', display: 'Country' },
+      { field: 'postalCode', label: 'Postal Code', display: 'Postal Code' },
+      { field: 'latitude', label: 'Latitude', display: 'Latitude' },
+      { field: 'longitude', label: 'Longitude', display: 'Longitude' },
+    ],
+    sizeMappings: {},
+    elementDefaults: {},
+    lineByLineFormat: [],
+  };
+}
+
+/**
+ * Get display label for an address field
+ */
+export function getAddressFieldLabel(
+  field: string,
+  template: AddressTemplate
+): string {
+  const mapping = template.nameMappings.find(m => m.field === field);
+  return mapping?.display || field;
+}

package/src/resources/agegroup/agegroups.api.ts

@@ -0,0 +1,58 @@
+import { omrsGet } from '../openmrs-api';
+
+type RestList<T> = { results?: T[] };
+
+export type AgeGroupRef = {
+    id: number;
+    display: string;
+    code?: string;
+    label: string;
+    minAgeDays: number;
+    maxAgeDays: number;
+    sortOrder: number;
+    active: boolean;
+};
+
+export type AgeCategoryDto = {
+    uuid: string;
+    display: string;
+    name: string;
+    description?: string;
+    code: string;
+    version?: string;
+    effectiveFrom?: string;
+    effectiveTo?: string | null;
+    active: boolean;
+    ageGroups?: AgeGroupRef[];
+    retired?: boolean;
+};
+
+export type AgeCategoryOption = {
+    uuid: string;
+    code: string;
+    label: string; // what we show in dropdown
+    name: string;
+    description?: string;
+    ageGroups: AgeGroupRef[];
+};
+
+export async function listAgeCategoriesWithGroups(signal?: AbortSignal): Promise<AgeCategoryOption[]> {
+    // ✅ categories endpoint
+    const data = await omrsGet<RestList<AgeCategoryDto>>('/reportbuilder/agecategory?v=full', signal);
+
+    const results = Array.isArray(data?.results) ? data.results : [];
+
+    return results
+        .filter((c) => !c.retired)
+        .map((c) => ({
+            uuid: c.uuid,
+            code: c.code,
+            name: c.name ?? c.display ?? c.code,
+            description: c.description,
+            label: `${c.name ?? c.display ?? c.code} (${c.code})`,
+            ageGroups: Array.isArray(c.ageGroups)
+                ? c.ageGroups.slice().sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))
+                : [],
+        }))
+        .sort((a, b) => a.label.localeCompare(b.label));
+}

package/src/resources/concept/concept.api.ts

@@ -0,0 +1,116 @@
+/**
+ * Concept API
+ *
+ * OpenMRS REST API for concepts
+ * GET /ws/rest/v1/concept
+ *
+ * Used for searching and selecting concepts in observations and encounter diagnoses
+ */
+
+import { omrsGet } from '../openmrs-api';
+
+type RestList<T> = { results?: T[] } & Record<string, any>;
+
+function unwrapRestList<T>(data: RestList<T> | T[] | undefined): T[] {
+  if (!data) return [];
+  if (Array.isArray(data)) return data;
+  return Array.isArray(data.results) ? data.results : [];
+}
+
+export type ConceptDto = {
+  uuid: string;
+  display: string;
+  name: {
+    uuid: string;
+    name: string;
+    locale: string;
+    localePreferred: boolean;
+  };
+  datatype: {
+    uuid: string;
+    display: string;
+    name: string;
+  };
+  conceptClass: {
+    uuid: string;
+    display: string;
+    name: string;
+  };
+  descriptions?: Array<{
+    uuid: string;
+    display: string;
+    description: string;
+    locale: string;
+  }>;
+  answers?: ConceptDto[];
+  retired?: boolean;
+  version?: string;
+};
+
+/**
+ * Search concepts by name or UUID
+ * @param query - Search term (concept name or UUID)
+ * @param signal - AbortSignal for request cancellation
+ */
+export async function searchConcepts(
+  query: string,
+  signal?: AbortSignal
+): Promise<Array<ConceptDto>> {
+  if (!query?.trim()) {
+    return [];
+  }
+
+  // Search by name or UUID
+  const data = await omrsGet<RestList<ConceptDto> | ConceptDto[] | undefined>(
+    `concept?q=${encodeURIComponent(query)}&v=full`,
+    signal
+  );
+  return unwrapRestList(data);
+}
+
+/**
+ * Get a concept by UUID
+ * @param uuid - Concept UUID
+ * @param signal - AbortSignal for request cancellation
+ */
+export async function getConcept(uuid: string, signal?: AbortSignal): Promise<ConceptDto> {
+  return omrsGet<ConceptDto>(`concept/${uuid}?v=full`, signal);
+}
+
+/**
+ * Get concepts by UUIDs (batch)
+ * @param uuids - Array of concept UUIDs
+ * @param signal - AbortSignal for request cancellation
+ */
+export async function getConceptsByUuids(
+  uuids: string[],
+  signal?: AbortSignal
+): Promise<Array<ConceptDto>> {
+  if (!uuids || uuids.length === 0) {
+    return [];
+  }
+
+  // OpenMRS REST API supports multiple UUIDs separated by comma
+  const uuidsParam = uuids.join(',');
+  const data = await omrsGet<RestList<ConceptDto> | ConceptDto[] | undefined>(
+    `concept?uuids=${uuidsParam}&v=full`,
+    signal
+  );
+  return unwrapRestList(data);
+}
+
+/**
+ * List concepts by class (e.g., for specific types of concepts)
+ * @param conceptClassUuid - UUID of the concept class to filter by
+ * @param signal - AbortSignal for request cancellation
+ */
+export async function listConceptsByClass(
+  conceptClassUuid: string,
+  signal?: AbortSignal
+): Promise<Array<ConceptDto>> {
+  const data = await omrsGet<RestList<ConceptDto> | ConceptDto[] | undefined>(
+    `concept?class=${conceptClassUuid}&v=full`,
+    signal
+  );
+  return unwrapRestList(data);
+}

package/src/resources/concepts/concept-mapper.ts

@@ -0,0 +1,21 @@
+export type ConceptMappingSummary = {
+    source: string;   // e.g. "CIEL", "ICD-10-WHO", "SNOMED CT"
+    code: string;     // e.g. "116128", "B54", "61462000"
+    mapType?: string; // e.g. "SAME-AS"
+    display: string;  // original display string e.g. "CIEL: 116128"
+};
+
+export type ConceptSummary = {
+    uuid: string;
+    display: string;
+
+    conceptClass?: string; // e.g. "Diagnosis"
+    datatype?: string;     // e.g. "Coded", "Numeric", "N/A"
+
+    // “best effort” external codes for showing + decisioning
+    mappings: ConceptMappingSummary[];
+
+    // convenience fields
+    cielCode?: string;     // if present
+    icd10Code?: string;    // if present
+};

package/src/resources/concepts/concept-types.ts

@@ -0,0 +1,31 @@
+export type ConceptMapping = {
+    display: string;
+    uuid: string;
+    conceptMapType?: {
+        display?: string;
+    };
+};
+
+export type ConceptSummary = {
+    id: number;
+    uuid: string;
+    display: string;
+
+    datatype?: {
+        uuid: string;
+        name: string;
+    };
+
+    conceptClass?: {
+        uuid: string;
+        name: string;
+    };
+
+    answers?: Array<{
+        id: number;
+        uuid: string;
+        display: string;
+    }>;
+
+    mappings?: ConceptMapping[];
+};

package/src/resources/concepts/concepts.resource.ts

@@ -0,0 +1,44 @@
+import type { ConceptSummary } from './concept-types';
+
+import { omrsGet } from '../openmrs-api';
+
+
+const RESOURCE = '/concept';
+const cutomConceptRepresentation = 'custom:(id,uuid,display,datatype:(uuid,name),conceptClass:(uuid,name),answers:(id,uuid,display),mappings:(display,uuid,conceptMapType:(display)))';
+
+type ConceptSearchResponse = {
+    results: ConceptSummary[];
+};
+
+type ConceptAnswersResponse = {
+    answers?: Array<{ uuid: string; display: string; id?: number; mappings?: any[]; conceptClass?: any; datatype?: any }>;
+};
+
+export async function searchConcepts(
+    query: string,
+    signal?: AbortSignal,
+): Promise<ConceptSummary[]> {
+    const res = await omrsGet<ConceptSearchResponse>(
+        `${RESOURCE}/?q=${encodeURIComponent(query)}&v=${cutomConceptRepresentation}`,
+        signal);
+
+    return res?.results ?? [];
+}
+
+export async function getConceptByUuid(uuid: string, signal?: AbortSignal): Promise<ConceptSummary> {
+    const u = String(uuid ?? '').trim();
+    if (!u) {
+        throw new Error('Concept uuid is required');
+    }
+
+    // /concept/{uuid} returns a single Concept object
+    return omrsGet<ConceptSummary>(`${RESOURCE}/${encodeURIComponent(u)}?v=${cutomConceptRepresentation}`, signal);
+}
+
+
+export async function getConceptAnswers(questionUuid: string, signal?: AbortSignal): Promise<ConceptSummary[]> {
+    const res = await omrsGet<ConceptAnswersResponse>(`${RESOURCE}/${questionUuid}?v=${cutomConceptRepresentation}`, signal );
+
+    const answers = (res as any)?.answers ?? [];
+    return answers as ConceptSummary[];
+}

package/src/resources/concepts/useConceptSearch.ts

@@ -0,0 +1,41 @@
+import { useState, useEffect } from 'react';
+import { searchConcepts } from './concepts.resource';
+import type { ConceptSummary } from './concept-types';
+
+export function useConceptSearch(query: string) {
+    const [loading, setLoading] = useState(false);
+    const [results, setResults] = useState<ConceptSummary[]>([]);
+    const [error, setError] = useState<string | null>(null);
+
+    useEffect(() => {
+        const q = query.trim();
+        if (q.length < 2) {
+            setResults([]);
+            setError(null);
+            return;
+        }
+
+        const ctrl = new AbortController();
+
+        const t = window.setTimeout(async () => {
+            try {
+                setLoading(true);
+                setError(null);
+
+                const res = await searchConcepts(q, ctrl.signal); // ✅ returns ConceptSummary[]
+                setResults(res);
+            } catch (e: any) {
+                if (e?.name !== 'AbortError') setError('Failed to search concepts');
+            } finally {
+                setLoading(false);
+            }
+        }, 300);
+
+        return () => {
+            ctrl.abort();
+            window.clearTimeout(t);
+        };
+    }, [query]);
+
+    return { loading, results, error };
+}