refactor: fe and be improvements and added jsdocs to new components

Author: Santi-3rd

backend/ops_api/ops/resources/agreements.py

@@ -161,9 +161,12 @@ def get(self) -> Response:
             request_schema = AgreementRequestSchema()
             data = request_schema.load(request.args.to_dict(flat=False))
 
+            include_procurement_list = data.pop("include_procurement", [False])
+            include_procurement = include_procurement_list[0] if include_procurement_list else False
+
             logger.debug("Beginning agreement queries")
             service = AgreementsService(current_app.db_session)
-            agreements, metadata = service.get_list(agreement_classes, data)
+            agreements, metadata = service.get_list(agreement_classes, data, include_procurement)
             logger.debug("Agreement queries complete")
 
             logger.debug("Serializing results")

backend/ops_api/ops/schemas/agreements.py

@@ -153,6 +153,7 @@ class Meta:
     only_my = fields.List(fields.Boolean(), required=False)
     award_type = fields.List(fields.Enum(AgreementClassification), required=False)
     exact_match = fields.List(fields.Boolean(), required=False, load_default=[True])
+    include_procurement = fields.List(fields.Boolean(), required=False, load_default=[False])
 
 
 class AgreementFiltersQueryParametersSchema(Schema):

backend/ops_api/ops/services/agreements.py

@@ -415,14 +415,18 @@ def get(self, id: int) -> Agreement:
         return agreement
 
     def get_list(
-        self, agreement_classes: list[Type[Agreement]], data: dict[str, Any]
+        self,
+        agreement_classes: list[Type[Agreement]],
+        data: dict[str, Any],
+        include_procurement: bool = False,
     ) -> tuple[list[Agreement], dict[str, Any]]:
         """
         Get list of agreements with optional filtering and pagination.
 
         Args:
             agreement_classes: List of Agreement subclasses to query (e.g., ContractAgreement, GrantAgreement)
             data: Dictionary containing filter parameters including limit and offset
+            include_procurement: When True, eager-load BLIs/trackers and compute procurement metrics
 
         Returns:
             Tuple of (paginated agreements list, metadata dict with count/limit/offset)
@@ -433,7 +437,7 @@ def get_list(
         # Collect all agreements across types using existing resource helpers
         all_results = []
         for agreement_cls in agreement_classes:
-            agreements = _get_agreements(self.db_session, agreement_cls, data)
+            agreements = _get_agreements(self.db_session, agreement_cls, data, include_procurement)
             all_results.extend(agreements)
 
         # Filter by award_type (computed property, must be done post-query)
@@ -454,10 +458,15 @@ def get_list(
         # Calculate aggregate totals before pagination (for summary cards)
         totals = _compute_agreement_totals(all_results)
 
-        # Calculate procurement overview and step summary before pagination
-        overview_fiscal_year = filters.fiscal_year[0] if filters.fiscal_year and len(filters.fiscal_year) == 1 else None
-        procurement_overview = _compute_procurement_overview(all_results, overview_fiscal_year)
-        procurement_step_summary = _compute_procurement_step_summary(all_results, overview_fiscal_year)
+        # Calculate procurement overview and step summary before pagination (only when requested)
+        procurement_overview = None
+        procurement_step_summary = None
+        if include_procurement:
+            overview_fiscal_year = (
+                filters.fiscal_year[0] if filters.fiscal_year and len(filters.fiscal_year) == 1 else None
+            )
+            procurement_overview = _compute_procurement_overview(all_results, overview_fiscal_year)
+            procurement_step_summary = _compute_procurement_step_summary(all_results, overview_fiscal_year)
 
         # Apply pagination slicing
         if filters.limit is not None and filters.offset is not None:
@@ -836,6 +845,13 @@ def _validate_special_topics(db_session: Session, special_topics: List[SpecialTo
         raise ValidationError({"special_topics": [f"Special Topic IDs do not exist: {invalid_special_topic_ids}"]})
 
 
+def _percent(value, total):
+    """Return ``value / total`` as a rounded whole-number percentage, or 0.0 when *total* is zero."""
+    if total == 0:
+        return 0.0
+    return float(round((float(value) / float(total)) * 100))
+
+
 def _compute_agreement_totals(all_results: list[Agreement]) -> dict[str, Any]:
     """Compute aggregate totals across all filtered agreements for summary cards."""
     totals = {
@@ -917,11 +933,6 @@ def _compute_procurement_overview(all_results: list[Agreement], fiscal_year: int
     # This means per-status percentages may not sum to 100%.
     total_agreements = len(all_results)
 
-    def _percent(value, total):
-        if total == 0:
-            return 0.0
-        return float(round((float(value) / float(total)) * 100))
-
     status_data = []
     for status in tracked_statuses:
         amount = amount_by_status[status]
@@ -988,11 +999,6 @@ def _compute_procurement_step_summary(all_results: list[Agreement], fiscal_year:
 
     total_agreement_count = sum(agreements_by_step.values())
 
-    def _percent(value, total):
-        if total == 0:
-            return 0.0
-        return float(round((float(value) / float(total)) * 100))
-
     step_data = []
     for step in range(1, 7):
         step_data.append(
@@ -1010,8 +1016,13 @@ def _percent(value, total):
     }
 
 
-def _get_agreements(session: Session, agreement_cls: Type[Agreement], data: dict[str, Any]) -> Sequence[Agreement]:
-    query = _build_base_query(agreement_cls)
+def _get_agreements(
+    session: Session,
+    agreement_cls: Type[Agreement],
+    data: dict[str, Any],
+    include_procurement: bool = False,
+) -> Sequence[Agreement]:
+    query = _build_base_query(agreement_cls, include_procurement)
     query = _apply_filters(query, agreement_cls, data)
 
     logger.debug(f"query: {query}")
@@ -1020,18 +1031,16 @@ def _get_agreements(session: Session, agreement_cls: Type[Agreement], data: dict
     return _filter_by_ownership(all_results, data.get("only_my", []))
 
 
-def _build_base_query(agreement_cls: Type[Agreement]) -> Select[tuple[Agreement]]:
-    return (
-        select(agreement_cls)
-        .distinct()
-        .join(BudgetLineItem, isouter=True)
-        .join(CAN, isouter=True)
-        .options(
+def _build_base_query(agreement_cls: Type[Agreement], include_procurement: bool = False) -> Select[tuple[Agreement]]:
+    query = select(agreement_cls).distinct().join(BudgetLineItem, isouter=True).join(CAN, isouter=True)
+
+    if include_procurement:
+        query = query.options(
             selectinload(agreement_cls.budget_line_items),
             selectinload(agreement_cls.procurement_trackers),
         )
-        .order_by(agreement_cls.id)
-    )
+
+    return query.order_by(agreement_cls.id)
 
 
 def _apply_filters(query: Select[Agreement], agreement_cls: Type[Agreement], data: dict[str, Any]) -> Select[Agreement]:

frontend/src/api/opsAPI.js

@@ -97,7 +97,8 @@ export const opsApi = createApi({
                     projectTitle,
                     contractNumber,
                     awardType,
-                    awardingEntityId
+                    awardingEntityId,
+                    includeProcurement
                 },
                 onlyMy,
                 sortConditions,
@@ -142,6 +143,9 @@ export const opsApi = createApi({
                 if (awardingEntityId) {
                     awardingEntityId.forEach((id) => queryParams.push(`awarding_entity_id=${id}`));
                 }
+                if (includeProcurement) {
+                    queryParams.push("include_procurement=true");
+                }
                 if (onlyMy) {
                     queryParams.push("only_my=true");
                 }
@@ -1059,9 +1063,6 @@ export const opsApi = createApi({
         }),
         getProcurementTrackersByAgreementIds: builder.query({
             query: (agreementIds) => {
-                if (!agreementIds || agreementIds.length === 0) {
-                    return `/procurement-trackers/?agreement_id=-1&limit=0`;
-                }
                 const queryParams = agreementIds.map((id) => `agreement_id=${id}`);
                 queryParams.push(`limit=${agreementIds.length}`);
                 return `/procurement-trackers/?${queryParams.join("&")}`;

frontend/src/pages/procurementDashboard/ProcShopFilter.jsx

@@ -1,3 +1,15 @@
+/**
+ * @typedef {Object} ProcShopFilterProps
+ * @property {string} value - The currently selected procurement shop abbreviation or "all".
+ * @property {(value: string) => void} onChange - Callback when the selection changes.
+ * @property {string[]} [options] - List of procurement shop abbreviations.
+ */
+
+/**
+ * @component ProcShopFilter
+ * @param {ProcShopFilterProps} props
+ * @returns {JSX.Element}
+ */
 const ProcShopFilter = ({ value, onChange, options = [] }) => {
     return (
         <div

frontend/src/pages/procurementDashboard/ProcurementDashboardPage.jsx

@@ -45,6 +45,7 @@ const ProcurementDashboard = () => {
     const { agreements, metadata, isLoading, error } = useGetAllAgreements({
         filters: {
             fiscalYear: [CURRENT_FISCAL_YEAR],
+            includeProcurement: true,
             ...(awardTypeFilter ? { awardType: [{ awardType: awardTypeFilter }] } : {}),
             ...(selectedProcShopId ? { awardingEntityId: [selectedProcShopId] } : {})
         }

frontend/src/pages/procurementDashboard/ProcurementOverviewCard.jsx

@@ -34,6 +34,36 @@ const buildStatusData = (procurementOverview) => {
     return { statusData, totalAmount: total_amount, totalAgreements: total_agreements };
 };
 
+/**
+ * @typedef {Object} StatusDataItem
+ * @property {string} status - Status key (e.g. "PLANNED", "IN_EXECUTION", "OBLIGATED").
+ * @property {string} label - Human-readable status label.
+ * @property {number} amount - Dollar amount for this status.
+ * @property {number} amount_percent - Percentage of total amount.
+ * @property {number} agreements - Number of agreements with this status.
+ * @property {number} agreements_percent - Percentage of total agreements.
+ */
+
+/**
+ * @typedef {Object} ProcurementOverview
+ * @property {StatusDataItem[]} status_data - Breakdown by BLI status.
+ * @property {number} total_amount - Total dollar amount across all tracked statuses.
+ * @property {number} total_agreements - Total number of agreements in the result set.
+ */
+
+/**
+ * @typedef {Object} ProcurementOverviewCardProps
+ * @property {ProcurementOverview | null} procurementOverview - Overview data from the API.
+ * @property {number} fiscalYear - The fiscal year being displayed.
+ * @property {boolean} isLoading - Whether data is still loading.
+ * @property {*} error - Error object, if any.
+ */
+
+/**
+ * @component ProcurementOverviewCard
+ * @param {ProcurementOverviewCardProps} props
+ * @returns {JSX.Element}
+ */
 const ProcurementOverviewCard = ({ procurementOverview, fiscalYear, isLoading, error }) => {
     const { statusData, totalAmount, totalAgreements } = useMemo(
         () => buildStatusData(procurementOverview),

frontend/src/pages/procurementDashboard/ProcurementStepSummaryCard.jsx

@@ -4,6 +4,26 @@ import CustomLayerComponent from "../../components/UI/DataViz/ResponsiveDonutWit
 import RoundedBox from "../../components/UI/RoundedBox";
 import StepLegendItem from "./StepLegendItem";
 
+/**
+ * @typedef {Object} StepDataItem
+ * @property {number} id - The step number (used as chart segment id).
+ * @property {string} label - Display label (e.g. "Step 1").
+ * @property {string} color - CSS color for the chart segment and legend.
+ * @property {number} value - Number of agreements in this step.
+ * @property {number} percent - Percentage of total agreements.
+ */
+
+/**
+ * @typedef {Object} ProcurementStepSummaryCardProps
+ * @property {StepDataItem[]} [stepData] - Per-step agreement counts for the donut chart.
+ * @property {number} fiscalYear - The fiscal year being displayed.
+ */
+
+/**
+ * @component ProcurementStepSummaryCard
+ * @param {ProcurementStepSummaryCardProps} props
+ * @returns {JSX.Element}
+ */
 const ProcurementStepSummaryCard = ({ stepData = [], fiscalYear }) => {
     const [percent, setPercent] = React.useState("");
     const [hoverId, setHoverId] = React.useState(-1);

frontend/src/pages/procurementDashboard/ProcurementSummaryCards.jsx

@@ -56,6 +56,20 @@ const buildStepData = (procurementStepSummary) => {
     return { stepData, budgetByStep };
 };
 
+/**
+ * @typedef {Object} ProcurementSummaryCardsProps
+ * @property {import("./ProcurementOverviewCard").ProcurementOverview | null} procurementOverview - Overview data from the API.
+ * @property {Object | null} procurementStepSummary - Step summary data from the API.
+ * @property {number} fiscalYear - The fiscal year being displayed.
+ * @property {boolean} isLoading - Whether data is still loading.
+ * @property {*} error - Error object, if any.
+ */
+
+/**
+ * @component ProcurementSummaryCards
+ * @param {ProcurementSummaryCardsProps} props
+ * @returns {JSX.Element}
+ */
 const ProcurementSummaryCards = ({ procurementOverview, procurementStepSummary, fiscalYear, isLoading, error }) => {
     const { stepData, budgetByStep } = useMemo(() => buildStepData(procurementStepSummary), [procurementStepSummary]);
 

frontend/src/pages/procurementDashboard/StepLegendItem.jsx

@@ -2,6 +2,21 @@ import { faCircle } from "@fortawesome/free-solid-svg-icons";
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
 import Tag from "../../components/UI/Tag/Tag";
 
+/**
+ * @typedef {Object} StepLegendItemProps
+ * @property {number} id - The step id.
+ * @property {number} activeId - The currently hovered/active step id.
+ * @property {string} label - The step label (e.g. "Step 1").
+ * @property {number} value - The number of agreements in this step.
+ * @property {string} color - CSS color for the legend dot.
+ * @property {number} percent - The percentage of total agreements.
+ */
+
+/**
+ * @component StepLegendItem
+ * @param {StepLegendItemProps} props
+ * @returns {JSX.Element}
+ */
 const StepLegendItem = ({ id, activeId, label, value, color, percent }) => {
     const isActive = activeId === id;
     return (