fix: fix percentage label consistency across all data-viz components (#5515)

Author: fpigeonjr

AGENTS.md

@@ -350,6 +350,77 @@ create("suiteName", (data) => {
 
 If you need validation state in a component, store the result with `useEffect` or call `suite.run()` inline during render (not in an effect that also resets state). See `ReviewAgreement.hooks.js` for the `useEffect`-based pattern.
 
+### Data-Visualization Percentage Display Convention
+
+**CRITICAL**: Data-viz components use a custom rounding scheme to avoid contradictory or broken labels. Never use `Math.round()` directly on chart percentages — always go through the shared helpers in `frontend/src/helpers/utils.js`.
+
+#### Figma design rules (source of truth)
+
+| Scenario | Display value |
+|---|---|
+| Value is exactly zero | `0%` |
+| Non-zero value that rounds to 0% | `<1%` — never show `0%` for a real non-zero value |
+| Dominant value that rounds to 100% while non-zero peers exist | `99%` — never show `100%` when other categories exist |
+| Integer labels would otherwise sum to 99% or 101% | Use largest remainder so the displayed whole-number labels sum to `100%` |
+| All other values | Rounded to nearest whole number |
+
+**What NOT to show**: `>99%`, `0%` for non-zero values, `100%` when other non-zero items exist.
+
+#### Three shared helpers (all exported from `utils.js`)
+
+| Helper | Purpose |
+|---|---|
+| `computeDisplayPercent(value, total)` | Single-item display percent; returns `"<1"` instead of `0` for non-zero tiny values |
+| `computeDisplayPercents(items)` | Cross-item normalisation; caps a dominant item at `99` and uses largest remainder so integer labels sum to `100` when possible |
+| `applyMinimumArcValue(items, total)` | Floors arc slices to 1% of total **for chart geometry only** (never for legend labels) |
+
+#### Why `"<1"`, `99`, and largest remainder exist
+
+- `Math.round(0.4%)` → `0` — renders as "0%" in the legend, hiding a real slice.
+- `Math.round(99.6%)` with a non-zero peer → `100%` — contradicts the peer's label (e.g. "100% + <1%").
+- `Math.round(33.3%) + Math.round(33.3%) + Math.round(33.4%)` → `33 + 33 + 33 = 99` — the legend no longer adds up to the whole.
+
+The helpers fix both cases:
+
+```javascript
+// ✅ CORRECT: use shared helpers for chart labels
+import { computeDisplayPercents } from "../../helpers/utils";
+
+const itemsWithPercent = computeDisplayPercents(rawItems);
+// Each item now has a `percent` field: integer (including 99 for capped dominant), or "<1"
+// Example: 333/333/334 becomes 33/33/34 so the legend sums to 100%
+```
+
+```javascript
+// ❌ INCORRECT: raw Math.round produces "0%" for tiny non-zero values
+const percent = Math.round((item.value / total) * 100); // may return 0 for <0.5%
+```
+
+#### Arc-visibility vs. legend values
+
+`applyMinimumArcValue` is applied **inside `ResponsiveDonutWithInnerPercent`** automatically. Callers must **not** apply it before passing data to the component — it would corrupt the legend numbers. Supply the real `value` fields; the component floors arc geometry internally.
+
+```javascript
+// ✅ CORRECT: pass real values; arc flooring is automatic
+<ResponsiveDonutWithInnerPercent data={itemsWithRealValues} />
+
+// ❌ INCORRECT: pre-flooring distorts both chart AND legend
+const safeData = applyMinimumArcValue(items, total);
+<ResponsiveDonutWithInnerPercent data={safeData} />
+```
+
+#### `HorizontalStackedBar` segment filtering
+
+`HorizontalStackedBar` filters and sizes bars by `item.value` (always numeric), **not** by `item.percent` (which may be the string `"<1"`). Ensure every segment object has a numeric `value` field alongside the display `percent`.
+
+```javascript
+// ✅ CORRECT: segment has numeric value
+{ id: 1, value: 500, percent: "<1", color: "...", label: "..." }
+
+// ❌ INCORRECT: filtering/sizing by percent string breaks layout
+// Do not rely on item.percent for conditional rendering inside bar components
+```
+
 ### Fee Percentage Format Convention
 
 **CRITICAL**: Fee percentages must be consistently formatted throughout the application:

docs/developers/frontend/accessibility/issue-5149-wave-3.md

@@ -86,7 +86,7 @@ Use Wave 3 to convert the existing accessibility baseline and regression-gate sc
   - `npx cypress run --config-file ./cypress.config.js --headless --spec "cypress/e2e/agreementDetails.cy.js,cypress/e2e/budgetLineItemsList.cy.js,cypress/e2e/createAgreementWithValidations.cy.js,cypress/e2e/uploadDocument.cy.js"` passes
   - no structural allowlist-backed failures remain in that targeted regression set
 - Completed `svg-img-alt` burn-down for the remaining tracked specs:
-  - hid decorative portfolio legend and CAN funding icons from assistive tech in `frontend/src/components/Portfolios/PortfolioSummaryCards/PortfolioLegend.jsx` and `frontend/src/components/Portfolios/PortfolioFundingByCAN/PortfolioFundingByCAN.jsx`
+  - hid decorative portfolio legend and CAN funding icons from assistive tech in `frontend/src/components/Portfolios/PortfolioSummaryCards/PortfolioLegend.jsx` and `frontend/src/components/Portfolios/PortfolioFundingByCAN/PortfolioFundingByCAN.jsx` (note: `PortfolioFundingByCAN` was subsequently removed in #5515)
   - hid decorative external-link icon in `frontend/src/components/Portfolios/PortfolioHero/HeroDescription.jsx`
   - hid decorative budget line summary and change-action icons in `frontend/src/components/BudgetLineItems/BLIStatusSummaryCard/BLIStatusSummaryCard.jsx` and `frontend/src/components/BudgetLineItems/ChangeIcons/ChangeIcons.jsx`
   - removed the final `svg-img-alt` allowlist entries from `frontend/cypress/support/a11yAllowlist.js`

frontend/AGENTS.md

@@ -0,0 +1,55 @@
+# Frontend AGENTS.md
+
+This file provides frontend-scoped guidance for agents and developers working in `frontend/`.
+
+## Key Frontend Conventions
+
+### Vest v6 Form Validation
+
+Canonical guidance: repository root `AGENTS.md` under `Vest v6 Form Validation Patterns`.
+
+- Numeric fields must not use `isNotBlank()`.
+- Use `suite.run(data)`, not `suite(data)`.
+- Do not call `only(data)` with a whole form object.
+- Avoid `suite.reset()` during render.
+
+See root `AGENTS.md` for examples and rationale.
+
+### Data-Viz Percentage Display Convention
+
+Canonical guidance: repository root `AGENTS.md` under `Data-Visualization Percentage Display Convention`.
+
+- Source of truth: `frontend/src/helpers/utils.js`
+- Use `computeDisplayPercent(value, total)` for single-item display percent logic.
+- Use `computeDisplayPercents(items)` for whole-part chart legends and labels.
+- Do not use raw `Math.round()` directly for displayed chart percentages.
+- Do not pre-apply `applyMinimumArcValue` to legend data.
+- `HorizontalStackedBar` must size and filter by numeric `value`, not display `percent`.
+
+Key display rules:
+
+- Exact zero displays as `0%`.
+- Non-zero values that would round to `0%` display as `<1%`.
+- A dominant value that would round to `100%` with non-zero peers displays as `99%`.
+- Whole-part labels use largest remainder when needed so displayed integers sum to `100%`.
+
+#### Components affected by this convention
+
+This rule applies to shared chart components and to feature components that prepare chart legend data, including:
+
+- `src/components/Agreements/`
+- `src/components/BudgetLineItems/`
+- `src/components/Portfolios/`
+- `src/components/Projects/`
+- `src/components/UI/DataViz/`
+
+### Fee Percentage Format Convention
+
+Canonical guidance: repository root `AGENTS.md` under `Fee Percentage Format Convention`.
+
+- Backend/storage format: `5.0` means `5%`
+- `calculateTotal` in `src/helpers/agreement.helpers.js` expects whole numbers
+- Do not pre-divide fee percentages by `100` before calling helpers
+- Use whole-number fee percentages in frontend tests too
+
+For full examples and rationale, see the repository root `AGENTS.md`.

frontend/cypress/e2e/agreementList.cy.js

@@ -513,7 +513,10 @@ describe("Agreement List", () => {
                 let totalPercent = 0;
                 $tags.each((_, tag) => {
                     const percentText = Cypress.$(tag).text();
-                    totalPercent += parseInt(percentText, 10);
+                    // Strip display-string prefixes (">99%" → 99, "<1%" → 1, "0%" → 0)
+                    // so the sum check works correctly after cross-item normalisation.
+                    const normalized = percentText.replace(/^[><]/, "").replace(/%/g, "").trim();
+                    totalPercent += parseInt(normalized, 10) || 0;
                 });
                 // Due to rounding, the sum may not be exactly 100 but should be close
                 // (within 2% due to Math.round on each individual percentage)

frontend/src/components/Agreements/AgreementSpendingCards/AgreementSpendingCards.helpers.js

@@ -1,4 +1,4 @@
-import { calculatePercent } from "../../../helpers/utils";
+import { computeDisplayPercents } from "../../../helpers/utils";
 import { AGREEMENT_TYPE_ORDER } from "./AgreementSpendingCards.constants";
 
 /**
@@ -12,33 +12,37 @@ export const transformToChartData = (agreementTypes, totalSpending) => {
         return [];
     }
 
-    return AGREEMENT_TYPE_ORDER.flatMap((config) => {
+    // Build all segments first without percents so we can normalise across
+    // the full set in one pass — prevents independent-rounding sum drift and
+    // the 100% + <1% contradiction.
+    const segments = AGREEMENT_TYPE_ORDER.flatMap((config) => {
         const typeData = agreementTypes.find((at) => at.type === config.type);
         const newAmount = Number(typeData?.new || 0);
         const continuingAmount = Number(typeData?.continuing || 0);
 
-        const segments = [];
+        const result = [];
 
         if (newAmount > 0) {
-            segments.push({
+            result.push({
                 id: config.type,
                 label: `${config.label} (New)`,
                 value: newAmount,
-                color: config.color,
-                percent: calculatePercent(newAmount, totalSpending)
+                color: config.color
             });
         }
 
         if (continuingAmount > 0) {
-            segments.push({
+            result.push({
                 id: `${config.type}_CONTINUING`,
                 label: `${config.label} (Continuing)`,
                 value: continuingAmount,
-                color: config.continuingColor,
-                percent: calculatePercent(continuingAmount, totalSpending)
+                color: config.continuingColor
             });
         }
 
-        return segments;
+        return result;
     });
+
+    // Apply cross-item normalisation: 99-cap when dominant + <1% guard across all segments
+    return computeDisplayPercents(segments);
 };

frontend/src/components/Agreements/AgreementSpendingCards/AgreementSpendingCards.helpers.test.js

@@ -67,4 +67,50 @@ describe("transformToChartData", () => {
         expect(result[6].id).toBe("DIRECT_OBLIGATION");
         expect(result[7].id).toBe("DIRECT_OBLIGATION_CONTINUING");
     });
+
+    it("each segment has a percent field", () => {
+        const result = transformToChartData(mockAgreementTypes, totalSpending);
+        result.forEach((segment) => {
+            expect(segment).toHaveProperty("percent");
+        });
+    });
+
+    it("dominant segment shows 99 (not 100 or '>99') when non-zero peers exist", () => {
+        const dominantTypes = [
+            { type: "CONTRACT", new: 996, continuing: 0 },
+            { type: "GRANT", new: 4, continuing: 0 }
+        ];
+        const result = transformToChartData(dominantTypes, 1000);
+        const contract = result.find((d) => d.id === "CONTRACT");
+        const grant = result.find((d) => d.id === "GRANT");
+        expect(contract.percent).toBe(99);
+        expect(grant.percent).toBe("<1");
+    });
+
+    it("3-way equal split: largest remainder assigns the extra point to the biggest segment", () => {
+        const equalTypes = [
+            { type: "CONTRACT", new: 333, continuing: 0 },
+            { type: "GRANT", new: 333, continuing: 0 },
+            { type: "DIRECT_OBLIGATION", new: 334, continuing: 0 }
+        ];
+        const result = transformToChartData(equalTypes, 1000);
+
+        expect(result.map((segment) => segment.percent)).toEqual([33, 33, 34]);
+    });
+
+    it("sub-1% non-zero segment shows '<1' instead of 0", () => {
+        const tinyTypes = [
+            { type: "CONTRACT", new: 996, continuing: 0 },
+            { type: "GRANT", new: 4, continuing: 0 }
+        ];
+        const result = transformToChartData(tinyTypes, 1000);
+        const grant = result.find((d) => d.id === "GRANT");
+        expect(grant.percent).toBe("<1");
+    });
+
+    it("single segment gets 100% (no non-zero peers — correct)", () => {
+        const singleType = [{ type: "CONTRACT", new: 1000, continuing: 0 }];
+        const result = transformToChartData(singleType, 1000);
+        expect(result[0].percent).toBe(100);
+    });
 });

frontend/src/components/Agreements/AgreementSpendingSummaryCard/AgreementSpendingSummaryCard.jsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { calculatePercent } from "../../../helpers/utils";
+import { computeDisplayPercents } from "../../../helpers/utils";
 import ResponsiveDonutWithInnerPercent from "../../UI/DataViz/ResponsiveDonutWithInnerPercent";
 import CustomLayerComponent from "../../UI/DataViz/ResponsiveDonutWithInnerPercent/CustomLayerComponent";
 import LegendItem from "../../UI/Cards/LineGraphWithLegendCard/LegendItem";
@@ -28,41 +28,45 @@ const AgreementSpendingSummaryCard = ({
 
     const totalAmount = contractTotal + partnerTotal + grantTotal + directObligationTotal;
 
-    const data = [
+    // Build raw items then apply cross-item percent normalisation so that no
+    // single slice can show "100%" while non-zero peers exist, and no non-zero
+    // slice rounds down to "0%".
+    const rawItems = [
         {
             id: 1,
             label: "Contract",
             value: contractTotal,
             color: "var(--data-viz-agreement-contract)",
-            percent: calculatePercent(contractTotal, totalAmount),
             tagStyleActive: "whiteOnContractBlue"
         },
         {
             id: 2,
             label: "Partner",
             value: partnerTotal,
             color: "var(--data-viz-agreement-partner)",
-            percent: calculatePercent(partnerTotal, totalAmount),
             tagStyleActive: "darkOnPartnerGreen"
         },
         {
             id: 3,
             label: "Grant",
             value: grantTotal,
             color: "var(--data-viz-agreement-grant)",
-            percent: calculatePercent(grantTotal, totalAmount),
             tagStyleActive: "darkOnGrantOrange"
         },
         {
             id: 4,
             label: "Direct Obligation",
             value: directObligationTotal,
             color: "var(--data-viz-agreement-direct-obligation)",
-            percent: calculatePercent(directObligationTotal, totalAmount),
             tagStyleActive: "whiteOnDirectObligationPink"
         }
     ];
 
+    // Legend data: real values + cross-item-normalised display percents
+    const legendData = computeDisplayPercents(rawItems);
+
+    // ResponsiveDonutWithInnerPercent applies applyMinimumArcValue internally.
+
     return (
         <RoundedBox
             dataCy="agreement-spending-summary-card"
@@ -75,7 +79,7 @@ const AgreementSpendingSummaryCard = ({
                     className="font-12px flex-fill"
                     style={{ marginRight: "1rem" }}
                 >
-                    {data.map((item) => (
+                    {legendData.map((item) => (
                         <LegendItem
                             key={item.id}
                             id={item.id}
@@ -96,7 +100,7 @@ const AgreementSpendingSummaryCard = ({
                         role="img"
                     >
                         <ResponsiveDonutWithInnerPercent
-                            data={data}
+                            data={legendData}
                             width={150}
                             height={150}
                             margin={{ top: 10, right: 10, bottom: 10, left: 10 }}