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

package/src/hooks/openmrs-reference-data.ts

@@ -0,0 +1,432 @@
+/**
+ * OpenMRS Reference Data Hooks
+ *
+ * Custom hooks for fetching OpenMRS reference data used in parameter selection.
+ * These hooks handle loading states, caching, and error handling for:
+ * - Locations
+ * - Concepts
+ * - Programs
+ * - Providers
+ * - Patient Identifier Types
+ * - Person Attribute Types
+ */
+
+import { useState, useEffect, useRef } from 'react';
+
+import {
+  listLocations,
+  searchLocations,
+  type LocationDto,
+} from '../resources/location/location.api';
+import {
+  searchConcepts,
+  type ConceptDto,
+} from '../resources/concept/concept.api';
+import {
+  listPatientIdentifierTypes,
+  searchPatientIdentifierTypes,
+  type PatientIdentifierTypeDto,
+} from '../resources/patient-identifier-type/patient-identifier-type.api';
+import {
+  listPersonAttributeTypes,
+  searchPersonAttributeTypes,
+  type PersonAttributeTypeDto,
+} from '../resources/person-attribute-type/person-attribute-type.api';
+
+/**
+ * Hook for fetching locations with optional tag filtering
+ * @param tagUuid - Optional tag UUID to filter locations
+ */
+export function useLocations(tagUuid?: string) {
+  const [locations, setLocations] = useState<LocationDto[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const loadLocations = async () => {
+      setLoading(true);
+      setError(null);
+      try {
+        const data = await listLocations(false, tagUuid);
+        if (!cancelled) {
+          setLocations(data);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : 'Failed to load locations');
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    };
+
+    loadLocations();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [tagUuid]);
+
+  return { locations, loading, error };
+}
+
+/**
+ * Hook for searching locations with debouncing
+ * @param query - Search query
+ * @param tagUuid - Optional tag UUID to filter locations
+ */
+export function useLocationSearch(query: string, tagUuid?: string) {
+  const [results, setResults] = useState<LocationDto[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const debounceRef = useRef<NodeJS.Timeout>();
+
+  useEffect(() => {
+    // Clear previous debounce timer
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+    }
+
+    // Don't search for empty queries
+    if (!query?.trim()) {
+      setResults([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Debounce search
+    debounceRef.current = setTimeout(async () => {
+      setLoading(true);
+      setError(null);
+      try {
+        const data = await searchLocations(query, tagUuid);
+        setResults(data);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to search locations');
+        setResults([]);
+      } finally {
+        setLoading(false);
+      }
+    }, 300);
+
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, [query, tagUuid]);
+
+  return { results, loading, error };
+}
+
+/**
+ * Hook for searching concepts with debouncing
+ * @param query - Search query
+ * @param conceptClassUuids - Optional array of concept class UUIDs to filter by
+ */
+export function useConceptSearch(query: string, conceptClassUuids?: string[]) {
+  const [results, setResults] = useState<ConceptDto[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const debounceRef = useRef<NodeJS.Timeout>();
+
+  useEffect(() => {
+    // Clear previous debounce timer
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+    }
+
+    // Don't search for empty queries
+    if (!query?.trim()) {
+      setResults([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Debounce search
+    debounceRef.current = setTimeout(async () => {
+      setLoading(true);
+      setError(null);
+      try {
+        const data = await searchConcepts(query);
+        let filtered = data;
+
+        // Filter by concept classes if specified
+        if (conceptClassUuids && conceptClassUuids.length > 0) {
+          filtered = data.filter((concept) =>
+            conceptClassUuids.includes(concept.conceptClass?.uuid)
+          );
+        }
+
+        setResults(filtered);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to search concepts');
+        setResults([]);
+      } finally {
+        setLoading(false);
+      }
+    }, 300);
+
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, [query, conceptClassUuids]);
+
+  return { results, loading, error };
+}
+
+/**
+ * Hook for fetching patient identifier types
+ * @param includeAll - Include retired identifier types
+ */
+export function usePatientIdentifierTypes(includeAll: boolean = false) {
+  const [identifierTypes, setIdentifierTypes] = useState<PatientIdentifierTypeDto[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const loadIdentifierTypes = async () => {
+      setLoading(true);
+      setError(null);
+      try {
+        const data = await listPatientIdentifierTypes(includeAll);
+        if (!cancelled) {
+          setIdentifierTypes(data);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : 'Failed to load identifier types');
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    };
+
+    loadIdentifierTypes();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [includeAll]);
+
+  return { identifierTypes, loading, error };
+}
+
+/**
+ * Hook for searching patient identifier types with debouncing
+ * @param query - Search query
+ */
+export function usePatientIdentifierTypeSearch(query: string) {
+  const [results, setResults] = useState<PatientIdentifierTypeDto[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const debounceRef = useRef<NodeJS.Timeout>();
+
+  useEffect(() => {
+    // Clear previous debounce timer
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+    }
+
+    // Don't search for empty queries
+    if (!query?.trim()) {
+      setResults([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Debounce search
+    debounceRef.current = setTimeout(async () => {
+      setLoading(true);
+      setError(null);
+      try {
+        const data = await searchPatientIdentifierTypes(query);
+        setResults(data);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to search identifier types');
+        setResults([]);
+      } finally {
+        setLoading(false);
+      }
+    }, 300);
+
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, [query]);
+
+  return { results, loading, error };
+}
+
+/**
+ * Hook for fetching person attribute types
+ * @param includeAll - Include retired attribute types
+ * @param format - Filter by format (e.g., 'org.openmrs.Concept')
+ */
+export function usePersonAttributeTypes(includeAll: boolean = false, format?: string) {
+  const [attributeTypes, setAttributeTypes] = useState<PersonAttributeTypeDto[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const loadAttributeTypes = async () => {
+      setLoading(true);
+      setError(null);
+      try {
+        const data = await listPersonAttributeTypes(includeAll);
+        let filtered = data;
+
+        // Filter by format if specified
+        if (format) {
+          filtered = data.filter((attr) => attr.format === format);
+        }
+
+        if (!cancelled) {
+          setAttributeTypes(filtered);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : 'Failed to load attribute types');
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    };
+
+    loadAttributeTypes();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [includeAll, format]);
+
+  return { attributeTypes, loading, error };
+}
+
+/**
+ * Hook for searching person attribute types with debouncing
+ * @param query - Search query
+ */
+export function usePersonAttributeTypeSearch(query: string) {
+  const [results, setResults] = useState<PersonAttributeTypeDto[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const debounceRef = useRef<NodeJS.Timeout>();
+
+  useEffect(() => {
+    // Clear previous debounce timer
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+    }
+
+    // Don't search for empty queries
+    if (!query?.trim()) {
+      setResults([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Debounce search
+    debounceRef.current = setTimeout(async () => {
+      setLoading(true);
+      setError(null);
+      try {
+        const data = await searchPersonAttributeTypes(query);
+        setResults(data);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to search attribute types');
+        setResults([]);
+      } finally {
+        setLoading(false);
+      }
+    }, 300);
+
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, [query]);
+
+  return { results, loading, error };
+}
+
+/**
+ * Hook for fetching configurable list options
+ * @param options - Array of predefined options
+ */
+export function useListOptions(options: Array<{ value: string; label: string }> = []) {
+  const [listOptions, setListOptions] = useState<Array<{ value: string; label: string }>>(options);
+
+  useEffect(() => {
+    setListOptions(options);
+  }, [options]);
+
+  return { listOptions };
+}
+
+/**
+ * Unified hook for fetching reference data based on parameter type
+ * @param paramType - The parameter type
+ * @param config - The parameter configuration
+ * @param searchQuery - Optional search query for search-based types
+ */
+export function useReferenceData(
+  paramType: string,
+  config?: any,
+  searchQuery?: string
+) {
+  // Location types
+  const locationData = useLocationSearch(searchQuery, config?.tagUuid);
+  const allLocations = useLocations(config?.tagUuid);
+
+  // Concept types
+  const conceptData = useConceptSearch(searchQuery, config?.conceptClassUuids);
+
+  // Identifier types
+  const identifierData = usePatientIdentifierTypeSearch(searchQuery);
+  const allIdentifiers = usePatientIdentifierTypes();
+
+  // Person attribute types
+  const attributeData = usePersonAttributeTypeSearch(searchQuery);
+  const allAttributes = usePersonAttributeTypes(false, config?.format);
+
+  // List options (static)
+  const listData = useListOptions(config?.options);
+
+  // Select the appropriate data based on parameter type
+  switch (paramType) {
+    case 'LOCATION':
+      return searchQuery ? locationData : allLocations;
+    case 'CONCEPT':
+      return conceptData;
+    case 'IDENTIFIER_TYPE':
+      return searchQuery ? identifierData : allIdentifiers;
+    case 'PERSON_ATTRIBUTE':
+      return searchQuery ? attributeData : allAttributes;
+    case 'LIST':
+      return listData;
+    default:
+      return { results: [], loading: false, error: null };
+  }
+}

package/src/hooks/theme/index.ts

@@ -0,0 +1,4 @@
+export { useETLTables, useETLSchemaTables } from './useMambaTables';
+export { useETLTableMeta } from './useMambaTableMeta';
+export { useDataThemes } from './useDataThemes';
+export { useDataTheme } from './useDataTheme';

package/src/hooks/theme/useDataTheme.ts

@@ -0,0 +1,61 @@
+/**
+ * Hook to fetch a single data theme with its configuration
+ */
+
+import { useEffect, useState } from 'react';
+import { getDataTheme } from '../../resources/theme/data-theme.api';
+import type { DataThemeDto } from '../../resources/theme/data-theme.api';
+import type { DataThemeConfig } from '../../types/theme/data-theme.types';
+
+type Result = {
+  theme: DataThemeDto | null;
+  config: DataThemeConfig | null;
+  loading: boolean;
+  error: string | null;
+};
+
+export function useDataTheme(uuid: string | undefined): Result {
+  const [theme, setTheme] = useState<DataThemeDto | null>(null);
+  const [config, setConfig] = useState<DataThemeConfig | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!uuid) {
+      setTheme(null);
+      setConfig(null);
+      setError(null);
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    getDataTheme(uuid)
+      .then((data) => {
+        setTheme(data);
+        // Parse configJson if present
+        if (data.configJson) {
+          try {
+            const parsed = JSON.parse(data.configJson);
+            setConfig(parsed);
+          } catch (e) {
+            console.error('Failed to parse theme config:', e);
+            setConfig(null);
+          }
+        } else {
+          setConfig(null);
+        }
+      })
+      .catch((err) => {
+        setError(err instanceof Error ? err.message : 'Failed to fetch theme');
+        setTheme(null);
+        setConfig(null);
+      })
+      .finally(() => {
+        setLoading(false);
+      });
+  }, [uuid]);
+
+  return { theme, config, loading, error };
+}

package/src/hooks/theme/useDataThemes.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+import type { DataTheme } from '../../types/theme/data-theme.types';
+import { listThemes } from '../../resources/theme/data-theme.api';
+
+export function useDataThemes(query: string) {
+    const [loading, setLoading] = React.useState(false);
+    const [error, setError] = React.useState<string | null>(null);
+    const [themes, setThemes] = React.useState<DataTheme[]>([]);
+
+    const reload = React.useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const data = await listThemes(query?.trim() || undefined);
+            setThemes(data);
+        } catch (e: any) {
+            setError(e?.message ?? String(e));
+        } finally {
+            setLoading(false);
+        }
+    }, [query]);
+
+    React.useEffect(() => {
+        reload();
+    }, [reload]);
+
+    return { themes, loading, error, reload, setThemes };
+}

package/src/hooks/theme/useMambaTableMeta.ts

@@ -0,0 +1,34 @@
+import React from 'react';
+import { getETLTableMeta } from '../../resources/theme/etl-table-meta.api';
+import type { TableColumn } from '../../resources/theme/etl-table-meta.api';
+
+export function useETLTableMeta(table?: string, enabled: boolean = true) {
+    const [columns, setColumns] = React.useState<TableColumn[]>([]);
+    const [loading, setLoading] = React.useState(false);
+    const [error, setError] = React.useState<string | null>(null);
+
+    React.useEffect(() => {
+        // ✅ don’t load until enabled AND a table is selected
+        if (!enabled || !table) {
+            setColumns([]);
+            setLoading(false);
+            setError(null);
+            return;
+        }
+
+        const ac = new AbortController();
+        setLoading(true);
+        setError(null);
+
+        getETLTableMeta(table, ac.signal)
+            .then((cols) => setColumns(Array.isArray(cols) ? cols : []))
+            .catch((e) => {
+                if (e?.name !== 'AbortError') setError(e?.message ?? 'Failed to load columns');
+            })
+            .finally(() => setLoading(false));
+
+        return () => ac.abort();
+    }, [table, enabled]);
+
+    return { columns, loading, error };
+}

package/src/hooks/theme/useMambaTables.ts

@@ -0,0 +1,95 @@
+import React from 'react';
+import { getSchemaTables, type SchemaTable } from '../../resources/theme/etl-schema.api';
+
+function toTableName(t: SchemaTable | any): string {
+    // Try common backend shapes
+    return (
+        t?.name ??
+        t?.table ??
+        t?.tableName ??
+        t?.view ??
+        t?.value ?? // fallback (some APIs)
+        ''
+    );
+}
+
+export function useETLTables(enabled: boolean) {
+    const [tables, setTables] = React.useState<string[]>([]);
+    const [loading, setLoading] = React.useState(false);
+    const [error, setError] = React.useState<string | null>(null);
+
+    React.useEffect(() => {
+        if (!enabled) {
+            setTables([]);
+            setLoading(false);
+            setError(null);
+            return;
+        }
+
+        const ac = new AbortController();
+        setLoading(true);
+        setError(null);
+
+        getSchemaTables(ac.signal).then((data) => {
+                // data is expected to be SchemaTable[] or something close
+                const names = (data ?? [])
+                    .map((t) => toTableName(t))
+                    .map((x) => x.trim())
+                    .filter(Boolean);
+
+                // de-dupe while preserving order
+                const uniq: string[] = [];
+                const seen = new Set<string>();
+                for (const n of names) {
+                    if (!seen.has(n)) {
+                        seen.add(n);
+                        uniq.push(n);
+                    }
+                }
+
+                setTables(uniq);
+            })
+            .catch((e) => {
+                if (e?.name !== 'AbortError') setError(e?.message ?? 'Failed to load tables');
+            })
+            .finally(() => setLoading(false));
+
+        return () => ac.abort();
+    }, [enabled]);
+
+    return { tables, loading, error };
+}
+
+/**
+ * Like useETLTables but keeps the rich per-table metadata
+ * (rows / updateTime / tableType) needed by the ETL Data Browser.
+ */
+export function useETLSchemaTables(enabled: boolean) {
+    const [tables, setTables] = React.useState<SchemaTable[]>([]);
+    const [loading, setLoading] = React.useState(false);
+    const [error, setError] = React.useState<string | null>(null);
+
+    React.useEffect(() => {
+        if (!enabled) {
+            setTables([]);
+            setLoading(false);
+            setError(null);
+            return;
+        }
+
+        const ac = new AbortController();
+        setLoading(true);
+        setError(null);
+
+        getSchemaTables(ac.signal)
+            .then((data) => setTables(data ?? []))
+            .catch((e) => {
+                if (e?.name !== 'AbortError') setError(e?.message ?? 'Failed to load tables');
+            })
+            .finally(() => setLoading(false));
+
+        return () => ac.abort();
+    }, [enabled]);
+
+    return { tables, loading, error };
+}