void;
+ isCreateModalOpenExternal?: boolean;
+ onCloseCreateModalExternal?: () => void;
+}
+
+export const ContractsManagement: React.FC = ({
+ isCreateModalOpenExternal,
+ onCloseCreateModalExternal,
+}) => {
+ const queryClient = useQueryClient();
+ const { success, error: toastError, info } = useToast();
+
+ // Component state
+ const [internalCreateModalOpen, setInternalCreateModalOpen] = useState(false);
+ const isCreateModalOpen = isCreateModalOpenExternal ?? internalCreateModalOpen;
+ const setCreateModalOpen = (open: boolean) => {
+ if (onCloseCreateModalExternal && !open) {
+ onCloseCreateModalExternal();
+ }
+ setInternalCreateModalOpen(open);
+ };
+
+ const [statusFilter, setStatusFilter] = useState('all');
+ const [searchTerm, setSearchTerm] = useState('');
+
+ // Selected contract for status update
+ const [contractToUpdate, setContractToUpdate] = useState(null);
+ const [newStatus, setNewStatus] = useState(ContractStatus.Active);
+
+ // Selected contract for file upload / replace
+ const [contractForFileUpload, setContractForFileUpload] = useState(null);
+ const [selectedUploadFile, setSelectedUploadFile] = useState(null);
+ const fileInputRef = useRef(null);
+
+ // Create contract form state
+ const [selectedAwardId, setSelectedAwardId] = useState('');
+ const [totalValueInput, setTotalValueInput] = useState(0);
+ const [effectiveAtInput, setEffectiveAtInput] = useState(
+ new Date().toISOString().split('T')[0]
+ );
+ const [expiresAtInput, setExpiresAtInput] = useState(() => {
+ const d = new Date();
+ d.setFullYear(d.getFullYear() + 1);
+ return d.toISOString().split('T')[0];
+ });
+ const [contractPdfFile, setContractPdfFile] = useState(null);
+ const [onlyApprovedAwards, setOnlyApprovedAwards] = useState(true);
+
+ // API Error states for modal banner display
+ const [createApiError, setCreateApiError] = useState(null);
+ const [uploadApiError, setUploadApiError] = useState(null);
+ const [updateApiError, setUpdateApiError] = useState(null);
+
+ // Loading indicator for secure download
+ const [downloadingContractId, setDownloadingContractId] = useState(null);
+
+ // Queries
+ const {
+ data: contracts = [],
+ isLoading: loadingContracts,
+ refetch: refetchContracts,
+ isRefetching: refetchingContracts,
+ } = useQuery({
+ queryKey: ['contracts'],
+ queryFn: () => getContracts(1, 100),
+ });
+
+ const { data: awards = [], isLoading: loadingAwards } = useQuery({
+ queryKey: ['awards'],
+ queryFn: () => getAwards(1, 100),
+ });
+
+ const { data: organisations = [] } = useQuery({
+ queryKey: ['organisations'],
+ queryFn: () => getOrganisations(1, 100),
+ });
+
+ const { data: programmes = [] } = useQuery({
+ queryKey: ['all-programmes'],
+ queryFn: () => getAllProgrammes(1, 100),
+ });
+
+ const { data: projects = [] } = useQuery({
+ queryKey: ['projects'],
+ queryFn: () => getProjects(),
+ });
+
+ // Helper to match award and its related metadata
+ const getAwardForContract = (contract: Contract): Award | undefined => {
+ return awards.find(
+ (a) =>
+ String(a.id) === String(contract.awardId) ||
+ toolsService.encodeIdSync(a.id) === String(contract.awardId)
+ );
+ };
+
+ const getOrganisationForAward = (award?: Award): Organisation | undefined => {
+ if (!award) return undefined;
+ return organisations.find(
+ (o) =>
+ String(o.id) === String(award.organisationId) ||
+ toolsService.encodeIdSync(o.id) === String(award.organisationId)
+ );
+ };
+
+ const getProgrammeForAward = (award?: Award): Programme | undefined => {
+ if (!award) return undefined;
+ return programmes.find(
+ (p) =>
+ String(p.id) === String(award.programmeId) ||
+ toolsService.encodeIdSync(p.id) === String(award.programmeId)
+ );
+ };
+
+ const getProjectForAward = (award?: Award, prog?: Programme): Project | undefined => {
+ if (!award) return undefined;
+ // Match by direct project ID on award or by programme link
+ return projects.find(
+ (pr) =>
+ (award.projectId && (String(pr.id) === String(award.projectId) || toolsService.encodeIdSync(pr.id) === String(award.projectId))) ||
+ (award.programmeId && String(pr.programmeId) === String(award.programmeId)) ||
+ (prog && String(pr.programmeId) === String(prog.id))
+ );
+ };
+
+ // Filter awards for dropdown: Approved status or all
+ const filteredAwardsForDropdown = awards.filter((a) => {
+ if (onlyApprovedAwards) {
+ return Number(a.status) === ApprovalStatus.Approved;
+ }
+ return true;
+ });
+
+ // When selected award changes in modal, auto-populate value and defaults
+ const handleAwardSelect = (awardIdStr: string) => {
+ setSelectedAwardId(awardIdStr);
+ setCreateApiError(null);
+ const award = awards.find(
+ (a) =>
+ String(a.id) === awardIdStr ||
+ toolsService.encodeIdSync(a.id) === awardIdStr
+ );
+ if (award) {
+ if (award.amount && award.amount > 0) {
+ setTotalValueInput(award.amount);
+ }
+ }
+ };
+
+ // Selected award metadata preview
+ const activeSelectedAward = awards.find(
+ (a) =>
+ String(a.id) === selectedAwardId ||
+ toolsService.encodeIdSync(a.id) === selectedAwardId
+ );
+ const activeSelectedOrg = getOrganisationForAward(activeSelectedAward);
+ const activeSelectedProg = getProgrammeForAward(activeSelectedAward);
+ const activeSelectedProj = getProjectForAward(activeSelectedAward, activeSelectedProg);
+
+ // Mutations
+ const createContractMutation = useMutation({
+ mutationFn: async () => {
+ setCreateApiError(null);
+ if (!selectedAwardId) {
+ throw new Error('Please select an approved award from the list.');
+ }
+ if (!totalValueInput || totalValueInput <= 0) {
+ throw new Error('Please enter a valid total contract value greater than 0.');
+ }
+ if (!contractPdfFile) {
+ throw new Error('Please upload a PDF document of the contract.');
+ }
+
+ // Step 1: Create contract via POST /v1/api/grants/contracts (awardId will be hashed by service)
+ const createdContract = await createContract({
+ awardId: selectedAwardId,
+ totalValue: Number(totalValueInput),
+ effectiveAt: new Date(effectiveAtInput).toISOString(),
+ expiresAt: new Date(expiresAtInput).toISOString(),
+ });
+
+ // Target contractId for upload
+ const contractIdToUploadAgainst =
+ createdContract?.id ?? (createdContract as any)?.contractId ?? selectedAwardId;
+
+ // Step 2: Upload PDF document to POST /v1/api/grants/contracts/{contractId}
+ if (contractPdfFile && contractIdToUploadAgainst) {
+ await uploadContractFile(contractIdToUploadAgainst, contractPdfFile);
+ }
+
+ return createdContract;
+ },
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['contracts'] });
+ queryClient.invalidateQueries({ queryKey: ['awards'] });
+ queryClient.invalidateQueries({ queryKey: ['dashboard'] });
+ success(
+ 'Contract Created & Document Uploaded',
+ 'The contract record has been registered and the PDF document securely stored in S3.'
+ );
+ setCreateModalOpen(false);
+ resetCreateForm();
+ },
+ onError: (err: unknown) => {
+ setCreateApiError(err);
+ toastError('Contract Creation Failed', err);
+ },
+ });
+
+ const uploadFileMutation = useMutation({
+ mutationFn: async () => {
+ setUploadApiError(null);
+ if (!contractForFileUpload) throw new Error('No contract selected for upload.');
+ if (!selectedUploadFile) throw new Error('Please select a PDF document to upload.');
+
+ await uploadContractFile(contractForFileUpload.id, selectedUploadFile);
+ },
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['contracts'] });
+ success('Contract Document Updated', 'New contract PDF document uploaded successfully.');
+ setContractForFileUpload(null);
+ setSelectedUploadFile(null);
+ },
+ onError: (err: unknown) => {
+ setUploadApiError(err);
+ toastError('Document Upload Failed', err);
+ },
+ });
+
+ const updateStatusMutation = useMutation({
+ mutationFn: async () => {
+ setUpdateApiError(null);
+ if (!contractToUpdate) throw new Error('No contract selected.');
+ await updateContract({
+ contractId: contractToUpdate.id,
+ status: newStatus,
+ });
+ },
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ['contracts'] });
+ queryClient.invalidateQueries({ queryKey: ['dashboard'] });
+ success('Contract Status Updated', 'The contract lifecycle status has been updated.');
+ setContractToUpdate(null);
+ },
+ onError: (err: unknown) => {
+ setUpdateApiError(err);
+ toastError('Status Update Failed', err);
+ },
+ });
+
+ const resetCreateForm = () => {
+ setSelectedAwardId('');
+ setTotalValueInput(0);
+ setContractPdfFile(null);
+ setCreateApiError(null);
+ };
+
+ // Secure download link handler (15-minute on-demand link)
+ const handleDownloadSecureLink = async (contract: Contract) => {
+ setDownloadingContractId(contract.id);
+ try {
+ const url = await getContractSecureLink(contract.id);
+ if (url && typeof url === 'string' && url.trim() !== '') {
+ const link = document.createElement('a');
+ link.href = url.trim();
+ link.target = '_blank';
+ link.rel = 'noopener noreferrer';
+ document.body.appendChild(link);
+ link.click();
+ document.body.removeChild(link);
+
+ success(
+ '15-Minute Secure Link Generated',
+ 'A time-limited download URL has been generated on-demand and opened.'
+ );
+ } else {
+ toastError('Download Link Unavailable', 'The server returned an empty secure download URL.');
+ }
+ } catch (err: unknown) {
+ toastError('Failed to Retrieve Secure Link', err);
+ } finally {
+ setDownloadingContractId(null);
+ }
+ };
+
+ // Filter and search contracts
+ const filteredContracts = contracts.filter((c) => {
+ // Status filter
+ if (statusFilter !== 'all') {
+ const statusNum = Number(c.status);
+ if (statusNum !== Number(statusFilter)) return false;
+ }
+
+ // Search filter
+ if (searchTerm.trim()) {
+ const q = searchTerm.toLowerCase();
+ const cId = String(c.id).toLowerCase();
+ const aId = String(c.awardId).toLowerCase();
+
+ const award = getAwardForContract(c);
+ const org = getOrganisationForAward(award);
+ const prog = getProgrammeForAward(award);
+ const proj = getProjectForAward(award, prog);
+
+ const orgName = org?.name?.toLowerCase() || '';
+ const progName = prog?.name?.toLowerCase() || '';
+ const projName = proj?.name?.toLowerCase() || '';
+
+ if (
+ !cId.includes(q) &&
+ !aId.includes(q) &&
+ !orgName.includes(q) &&
+ !progName.includes(q) &&
+ !projName.includes(q)
+ ) {
+ return false;
+ }
+ }
+
+ return true;
+ });
+
+ // Calculate summary metrics
+ const totalContractCount = contracts.length;
+ const activeContractsValue = contracts
+ .filter((c) => Number(c.status) === ContractStatus.Active)
+ .reduce((sum, c) => sum + (Number(c.totalValue) || 0), 0);
+ const pendingContractsCount = contracts.filter(
+ (c) =>
+ Number(c.status) === ContractStatus.Draft ||
+ Number(c.status) === ContractStatus.PendingApproval
+ ).length;
+
+ return (
+ = ({
size = 'md',
diff --git a/PostFundManagement.ConsoleUI/src/components/ui/HelpTooltip.tsx b/PostFundManagement.ConsoleUI/src/components/ui/HelpTooltip.tsx
new file mode 100644
index 0000000..dfcd092
--- /dev/null
+++ b/PostFundManagement.ConsoleUI/src/components/ui/HelpTooltip.tsx
@@ -0,0 +1,125 @@
+import React, { useState, useRef, useEffect, ReactNode } from 'react';
+import { Info, X } from 'lucide-react';
+
+export interface HelpTooltipProps {
+ /** Concise context-sensitive explanation of the section, control, metric, or dialog */
+ content: ReactNode;
+ /** Optional title for the tooltip popover */
+ title?: string;
+ /** Custom alignment: top, bottom, left, right (defaults to top) */
+ placement?: 'top' | 'bottom' | 'left' | 'right';
+ /** Size of the (i) icon: sm (13px), md (15px), lg (18px) */
+ size?: 'sm' | 'md' | 'lg';
+ /** Additional styling classes for the container or trigger button */
+ className?: string;
+ /** Accessible label or ARIA label */
+ ariaLabel?: string;
+}
+
+export const HelpTooltip: React.FC = ({
+ content,
+ title,
+ placement = 'top',
+ size = 'md',
+ className = '',
+ ariaLabel = 'Information and guidance',
+}) => {
+ const [isOpen, setIsOpen] = useState(false);
+ const containerRef = useRef(null);
+
+ // Close on Escape or click outside
+ useEffect(() => {
+ if (!isOpen) return;
+
+ const handleOutsideClick = (e: MouseEvent | TouchEvent) => {
+ if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+ setIsOpen(false);
+ }
+ };
+
+ const handleKeyDown = (e: KeyboardEvent) => {
+ if (e.key === 'Escape') {
+ setIsOpen(false);
+ }
+ };
+
+ document.addEventListener('mousedown', handleOutsideClick);
+ document.addEventListener('touchstart', handleOutsideClick);
+ document.addEventListener('keydown', handleKeyDown);
+
+ return () => {
+ document.removeEventListener('mousedown', handleOutsideClick);
+ document.removeEventListener('touchstart', handleOutsideClick);
+ document.removeEventListener('keydown', handleKeyDown);
+ };
+ }, [isOpen]);
+
+ const sizeClasses = {
+ sm: 'w-3.5 h-3.5 text-[11px]',
+ md: 'w-4 h-4 text-xs',
+ lg: 'w-5 h-5 text-sm',
+ }[size];
+
+ const iconSizes = {
+ sm: 'w-3 h-3',
+ md: 'w-3.5 h-3.5',
+ lg: 'w-4 h-4',
+ }[size];
+
+ const placementClasses = {
+ top: 'bottom-full left-1/2 -translate-x-1/2 mb-2',
+ bottom: 'top-full left-1/2 -translate-x-1/2 mt-2',
+ left: 'right-full top-1/2 -translate-y-1/2 mr-2',
+ right: 'left-full top-1/2 -translate-y-1/2 ml-2',
+ }[placement];
+
+ return (
+ = ({
onClose,
title,
subtitle,
+ helpText,
children,
maxWidth = 'lg',
}) => {
@@ -56,7 +59,17 @@ export const Modal: React.FC = ({
>
diff --git a/PostFundManagement.ConsoleUI/src/components/ui/Toast.tsx b/PostFundManagement.ConsoleUI/src/components/ui/Toast.tsx
index a07afbd..e4a741c 100644
--- a/PostFundManagement.ConsoleUI/src/components/ui/Toast.tsx
+++ b/PostFundManagement.ConsoleUI/src/components/ui/Toast.tsx
@@ -25,6 +25,7 @@ export interface ToastItem {
categoryLabel?: string;
technicalDetails?: string;
fieldErrors?: Array<{ field: string; message: string }>;
+ errorsList?: string[];
}
export interface ToastOptions {
@@ -34,6 +35,7 @@ export interface ToastOptions {
categoryLabel?: string;
technicalDetails?: string;
fieldErrors?: Array<{ field: string; message: string }>;
+ errorsList?: string[];
}
interface ToastContextType {
@@ -153,11 +155,21 @@ const ToastCard: React.FC<{
)}
+ {/* Summary Cards */}
+ setCreateModalOpen(false)}
+ title="Create Legal Contract & Attach PDF"
+ >
+
+
+
+ {/* ======================================================== */}
+ {/* MODAL 2: Replace / Upload New Contract PDF File */}
+ {/* ======================================================== */}
+ setContractForFileUpload(null)}
+ title={`Upload New Contract Document (Contract #${contractForFileUpload?.id})`}
+ >
+
+
+
+ {/* ======================================================== */}
+ {/* MODAL 3: Update Contract Status */}
+ {/* ======================================================== */}
+ setContractToUpdate(null)}
+ title={`Update Contract Status (Contract #${contractToUpdate?.id})`}
+ >
+
+
+
+ );
+};
diff --git a/PostFundManagement.ConsoleUI/src/components/ui/BrandLogo.tsx b/PostFundManagement.ConsoleUI/src/components/ui/BrandLogo.tsx
index 3d53a33..9018f96 100644
--- a/PostFundManagement.ConsoleUI/src/components/ui/BrandLogo.tsx
+++ b/PostFundManagement.ConsoleUI/src/components/ui/BrandLogo.tsx
@@ -17,12 +17,7 @@ const sizeMap = {
};
/**
- * Modern, stylized SVG brand emblem representing Post Fund Management (PFM).
- * Features an isometric kinetic nexus with three interlocking governance facets:
- * 1. Top Canopy: Governance, Strategy & Portfolios (Radiant Indigo / Violet)
- * 2. Left Vault: Capital, Grants & Disbursement Assurance (Electric Sapphire)
- * 3. Right Wing: Milestones, Evidence & Impact Delivery (Cyan to Emerald)
- * 4. Center Core: Luminous Floating Diamond Milestone Star
+ * SVG brand logo component for Post Fund Management (PFM).
*/
export const BrandLogo: React.FC
+
+
+ {/* Action and Filter Bar */}
+
+
+
+
+
+ Total Contracts
+
+
+
+
+
+ {loadingContracts ? '...' : totalContractCount}
+
+ + Linked to approved grant funding awards +
+
+
+
+
+
+ Active Value (ZAR)
+
+
+
+
+
+ {loadingContracts ? '...' : formatZAR(activeContractsValue)}
+
+ + Legally executed active commitments +
+
+
+
+
+
+ In Review / Draft
+
+
+
+
+
+ {loadingContracts ? '...' : pendingContractsCount}
+
+ + Pending legal review or signature +
+
+
+
+
+ Approved Awards Available
+
+
+
+
+
+ {loadingAwards
+ ? '...'
+ : awards.filter((a) => Number(a.status) === ApprovalStatus.Approved).length}
+
+ + Ready to establish contractual legal binding +
+
+
+
+ {/* Contracts Table */}
+
+ {/* Search */}
+
+
+
+
+
+
+ {/* Status Filter */}
+
+
+
+
+
+
+
+ {/* ======================================================== */}
+ {/* MODAL 1: Create Contract & Initial PDF Upload Workflow */}
+ {/* ======================================================== */}
+
+
+
+
+ Showing {filteredContracts.length} of {contracts.length} contracts
+
+
+
+ {loadingContracts ? (
+
+
+
+ Showing {filteredContracts.length} of {contracts.length} contracts
+
+
+
+ ) : filteredContracts.length === 0 ? (
+
+
+ ) : (
+ No contracts found
++ {searchTerm || statusFilter !== 'all' + ? 'No contracts match the current search filters. Try resetting the filters.' + : 'No contracts have been created yet. Click "Create Contract & Upload PDF" to link an approved award.'} +
+ {!(searchTerm || statusFilter !== 'all') && ( + + )} +
+
+
+
+
+ )}
+ | Contract / Ref | +Award & Amount | +Programme & Project | +Organisation | +Validity Period | +Status | +Document / S3 | +Actions | +
|---|---|---|---|---|---|---|---|
|
+
+ #{contract.id}
+
+
+ Hash: {toolsService.encodeIdSync(contract.id)}
+
+
+ {formatZAR(contract.totalValue)}
+
+ |
+
+ {/* Linked Award */}
+
+ {award ? (
+
+
+ ) : (
+
+ Award #{contract.awardId}
+
+ )}
+
+ Award #{award.id}
+ {award.referenceNo && (
+
+ ({award.referenceNo})
+
+ )}
+
+
+ Funded: {formatZAR(award.amount)}
+
+ {award.status && (
+
+ {getApprovalStatusBadge(award.status).label}
+
+ )}
+ |
+
+ {/* Programme & Project */}
+
+
+
+
+
+ |
+
+ {/* Organisation */}
+
+
+
+ {org?.registrationNo && (
+
+ Reg: {org.registrationNo}
+
+ )}
+ |
+
+ {/* Validity Period */}
+
+
+
+
+ to {formatDate(contract.expiresAt)}
+
+ |
+
+ {/* Status */}
+ + + {statusBadge.label} + + | + + {/* Document / File S3 Download */} +
+
+
+
+
+
+
+
+ |
+
+ {/* Actions */}
+ + + | +
+
+
+ {isOpen && (
+
+ );
+};
diff --git a/PostFundManagement.ConsoleUI/src/components/ui/Modal.tsx b/PostFundManagement.ConsoleUI/src/components/ui/Modal.tsx
index a12097b..cfad194 100644
--- a/PostFundManagement.ConsoleUI/src/components/ui/Modal.tsx
+++ b/PostFundManagement.ConsoleUI/src/components/ui/Modal.tsx
@@ -1,11 +1,13 @@
import React, { ReactNode, useEffect } from 'react';
import { X } from 'lucide-react';
+import { HelpTooltip } from './HelpTooltip';
interface ModalProps {
isOpen: boolean;
onClose: () => void;
title: string;
subtitle?: string;
+ helpText?: ReactNode;
children: ReactNode;
maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl';
}
@@ -15,6 +17,7 @@ export const Modal: React.FC e.stopPropagation()}
+ className={`absolute ${placementClasses} z-50 w-72 max-w-[calc(100vw-32px)] p-3 rounded-xl bg-[#0c121e] border border-blue-500/30 text-slate-200 shadow-2xl backdrop-blur-md animate-in fade-in zoom-in-95 duration-150`}
+ >
+
+ )}
+
+
+
+
+
+
+
+ {content}
+
+
-
{title}
+
+
{subtitle && {title}
+ {helpText && ( +{subtitle}
}