@growth-operations/ui-shared 1.17.2 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-operations/ui-shared",
-  "version": "1.17.2",
+  "version": "1.18.0",
   "description": "Shared HubSpot UI-extension modules (Home, Billing) for Growth Operations apps.",
   "license": "MIT",
   "private": false,

package/src/home/CreditMeter.jsx

@@ -9,16 +9,27 @@ import { resolveCreditMeter } from "../lib/creditDisplay";
 // `credit_meter` block (CONTRACT.md). Renders nothing when there is no credit
 // data to show.
 //
-// All branch math (number precedence, threshold_state → tag/alert, the
-// pool+bank split) lives in ../lib/creditDisplay so it's unit-testable — this
-// component is pure rendering.
+// All branch math (number precedence, threshold_state → tag/alert/bar
+// variants, the pool+bank split) lives in ../lib/creditDisplay so it's
+// unit-testable — this component is pure rendering.
 //
-// Two-segment bank display: accounts with a top-up bank (topup billing model)
-// get the combined marker bar — `${used} of ${granted}` over the combined
-// pool+bank denominator, so after a period reset with bank left it reads e.g.
-// "0 of 1,700" while the bank segment shows what's left — plus the
-// pool/bank breakdown lines. Accounts with NO bank (top_up_bank_remaining 0
-// AND never a top-up) render exactly the legacy single-segment bar.
+// Stacked-bars bank display: an account with top-up bank credits left (topup
+// billing model) gets TWO bars, one per bucket, and NO combined headline (the
+// combined pool+bank denominator read as one big confusing allowance):
+//   1. Monthly plan credits — a DEPLETION meter (value = pool used of the
+//      period grant), color-coded by the account's depletion state: success
+//      when healthy, warning at/below the low threshold, danger when
+//      depleted (view.barVariant).
+//   2. Additional credits — a LEVEL gauge (value = bank remaining of the
+//      bank's granted total), always success: the bank is cumulative and
+//      never expires, so a used-of-granted bar would drift to
+//      permanently-near-full over multiple purchases; the remaining level
+//      refills on purchase and drains on spend.
+// Hosts whose backend predates top_up_bank_granted degrade gracefully: the
+// bank renders as a text-only line (no bar, never "of 0"). An account with
+// NO bank credits left (never topped up, or the bank is spent) renders
+// exactly the legacy view — the "{remaining} of {granted} credits left"
+// headline plus the single color-coded bar.
 //
 // Props:
 //   entitlement  — the /v1/home entitlement union (uses the credits arm).
@@ -27,7 +38,7 @@ export function CreditMeter({ entitlement, creditMeter }) {
   const view = resolveCreditMeter(entitlement, creditMeter);
   if (!view) return null;
 
-  const { granted, used, remaining, bank, tagVariant, tagLabel, alert } = view;
+  const { granted, used, remaining, bank, tagVariant, tagLabel, barVariant, alert } = view;
   const grantDaysLeft = view.grantExpiresAt ? daysUntil(view.grantExpiresAt) : null;
 
   return (
@@ -38,42 +49,64 @@ export function CreditMeter({ entitlement, creditMeter }) {
           <StatusTag variant={tagVariant}>{tagLabel}</StatusTag>
         </Flex>
 
-        {/* PRIMARY signal — large and obvious. */}
-        <Text format={{ fontWeight: "bold", fontSize: "lg" }}>
-          {remaining} of {granted} credits left
-        </Text>
-
         {bank ? (
           <>
-            {/* Current-position marker over the COMBINED pool+bank
-                denominator (used = granted - remaining). The HubSpot
-                ProgressBar is single-value, so the two segments are the
-                labeled breakdown below; this bar is the position within the
-                whole. */}
-            <ProgressBar
-              title={`${used} of ${granted} used`}
-              value={used}
-              maxValue={granted > 0 ? granted : 1}
-              showPercentage={true}
-            />
+            {/* Pool — depletion meter over the period grant. */}
             <Flex direction="column" gap="extra-small">
               <Text>
                 Monthly plan credits: {bank.poolRemaining} of {bank.poolGrant}{" "}
                 left
               </Text>
-              <Text>Additional credits: {bank.bankRemaining} left</Text>
-              <Text format={{ fontStyle: "italic" }}>
-                Additional credits don't expire.
-              </Text>
+              <ProgressBar
+                title={`${bank.poolUsed} of ${bank.poolGrant} used`}
+                value={bank.poolUsed}
+                maxValue={bank.poolGrant > 0 ? bank.poolGrant : 1}
+                showPercentage={true}
+                variant={barVariant}
+              />
             </Flex>
+            {bank.bankGranted > 0 ? (
+              // Bank — level gauge over the granted total (refills on
+              // purchase, drains on spend; never expires).
+              <Flex direction="column" gap="extra-small">
+                <Text>
+                  Additional credits (never expire): {bank.bankRemaining} of{" "}
+                  {bank.bankGranted} left
+                </Text>
+                <ProgressBar
+                  title={`${bank.bankRemaining} of ${bank.bankGranted} left`}
+                  value={bank.bankRemaining}
+                  maxValue={bank.bankGranted > 0 ? bank.bankGranted : 1}
+                  showPercentage={true}
+                  variant="success"
+                />
+              </Flex>
+            ) : (
+              // Graceful degradation: the host's backend predates
+              // top_up_bank_granted, so the bank total is unknown — text
+              // only, no bar (never divide by zero, never "of 0").
+              <Flex direction="column" gap="extra-small">
+                <Text>Additional credits: {bank.bankRemaining} left</Text>
+                <Text format={{ fontStyle: "italic" }}>
+                  Additional credits don't expire.
+                </Text>
+              </Flex>
+            )}
           </>
         ) : (
-          <ProgressBar
-            title={`${used} used`}
-            value={used}
-            maxValue={granted > 0 ? granted : 1}
-            showPercentage={true}
-          />
+          <>
+            {/* PRIMARY signal — large and obvious. */}
+            <Text format={{ fontWeight: "bold", fontSize: "lg" }}>
+              {remaining} of {granted} credits left
+            </Text>
+            <ProgressBar
+              title={`${used} used`}
+              value={used}
+              maxValue={granted > 0 ? granted : 1}
+              showPercentage={true}
+              variant={barVariant}
+            />
+          </>
         )}
 
         {/* Free-grant countdown: "100 free credits — N days left". */}

package/src/lib/creditDisplay.js

@@ -26,9 +26,10 @@
 //   incident where a paying, overage account was shown a blocking
 //   "Depleted"/"out of credits" panel).
 
-// True when the account has (or ever had) a top-up bank: the two-segment
-// meter renders only then — a zero bank with NO top-up ever (last_top_up_at
-// null) renders exactly the legacy single-segment bar.
+// True when the account has (or ever had) a top-up bank. Note the CreditMeter
+// bank section renders only while the bank HAS credits left (bankRemaining >
+// 0 — see resolveCreditMeter); this predicate stays the looser "ever had one"
+// for consumers that render history/summary surfaces.
 export function hasTopUpBank(ent) {
   if (!ent) return false;
   return (ent.top_up_bank_remaining ?? 0) > 0 || ent.last_top_up_at != null;
@@ -38,12 +39,25 @@ export function hasTopUpBank(ent) {
 // Returns null when there is no credit data to show (component renders
 // nothing). Otherwise:
 //   granted/used/remaining — combined (topup) or raw (legacy) display numbers
-//   bank                 — { bankRemaining, poolGrant, poolRemaining, poolUsed }
-//                          when the account has a bank, else null
+//   bank                 — { bankRemaining, bankGranted, poolGrant,
+//                          poolRemaining, poolUsed } when the account has bank
+//                          credits LEFT (bankRemaining > 0), else null — a
+//                          zero bank renders the plain single-pool bar (with
+//                          bankRemaining 0 the combined numbers ARE the pool
+//                          numbers). bankGranted is the bank's lifetime
+//                          granted total (the bank bar's denominator); 0 on
+//                          backends that predate top_up_bank_granted — the
+//                          component degrades to a text-only bank line.
 //   thresholdState       — the arm's threshold_state, or null on a backend
 //                          that predates it
 //   depleted/overIncluded/low — mutually-exclusive urgency flags
 //   tagVariant/tagLabel  — StatusTag rendering
+//   barVariant           — ProgressBar sentiment for the pool/single bar:
+//                          the tag's depletion mapping minus "info"
+//                          (ProgressBar only takes success/warning/danger;
+//                          top_up_pending is calm/positive, so success).
+//                          The bank bar is always "success" (a never-expiring
+//                          balance has no negative direction).
 //   alert                — { variant, title, message } or null
 //   grantExpiresAt       — pass-through for the free-grant countdown
 export function resolveCreditMeter(entitlement, creditMeter) {
@@ -82,13 +96,23 @@ export function resolveCreditMeter(entitlement, creditMeter) {
   // Bank split. Drawdown is monthly-first, so of the combined `remaining` the
   // bank portion is bankRemaining and the rest is pool remaining; the pool
   // segment's full size is the combined denominator minus the bank.
+  //
+  // The bank section renders ONLY while the bank has credits left
+  // (bankRemaining > 0): a zero bank — never topped up, or fully burned —
+  // renders the plain single-pool bar, and with bankRemaining 0 the combined
+  // numbers ARE the pool numbers (granted == poolGrant, remaining ==
+  // poolRemaining), so nothing is lost.
   let bank = null;
-  if (hasTopUpBank(ent)) {
-    const bankRemaining = Math.max(0, ent?.top_up_bank_remaining ?? 0);
+  const bankRemaining = Math.max(0, ent?.top_up_bank_remaining ?? 0);
+  if (bankRemaining > 0) {
     const poolGrant = Math.max(granted - bankRemaining, 0);
     const poolRemaining = Math.min(Math.max(remaining - bankRemaining, 0), poolGrant);
     bank = {
       bankRemaining,
+      // The bank's lifetime granted total — the bank bar's denominator. 0 on
+      // backends that predate top_up_bank_granted (the component degrades to
+      // a text-only bank line; never divide by zero, never "of 0").
+      bankGranted: Math.max(0, ent?.top_up_bank_granted ?? 0),
       poolGrant,
       poolRemaining,
       poolUsed: poolGrant - poolRemaining,
@@ -120,6 +144,13 @@ export function resolveCreditMeter(entitlement, creditMeter) {
     tagLabel = "Healthy";
   }
 
+  // ProgressBar sentiment for the pool bar (and the no-bank single bar):
+  // color-coded by depletion — success when healthy, warning at/below the
+  // low threshold (and for the other warning-level states), danger when
+  // depleted/top-up-failed. ProgressBar has no "info" variant, so the calm
+  // top_up_pending state renders success.
+  const barVariant = tagVariant === "info" ? "success" : tagVariant;
+
   // The inline meter alert mirrors the banner's messaging at the point of
   // glance. Legacy branches keep their pre-top-up copy byte-for-byte.
   let alert = null;
@@ -171,6 +202,7 @@ export function resolveCreditMeter(entitlement, creditMeter) {
     low,
     tagVariant,
     tagLabel,
+    barVariant,
     alert,
     grantExpiresAt: ent?.grant_expires_at ?? null,
   };