@growth-operations/ui-shared 1.19.0 → 1.21.0

package/src/home/CreditMeter.jsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { Flex, Tile, Text, ProgressBar, StatusTag, Alert } from "@hubspot/ui-extensions";
-import { daysUntil } from "../lib/format";
+import { daysUntil, fmtDate } from "../lib/format";
 import { resolveCreditMeter } from "../lib/creditDisplay";
 
 // THE credit-archetype activity tile + hero signal. For credit apps, "credits
@@ -25,7 +25,10 @@ import { resolveCreditMeter } from "../lib/creditDisplay";
 //      used-of-granted bar would drift to permanently-near-full over multiple
 //      purchases; the remaining level refills on purchase and drains on
 //      spend), colored by ITS OWN level: success above 50% full, warning at
-//      20–50%, danger at <=20% (view.bankBarVariant).
+//      <=50% (view.bankBarVariant). NO danger on this bar — HubSpot's
+//      ProgressBar paints the whole track red in danger, so a low gauge
+//      would read as FULL; at <=20% a warning "Running low" StatusTag rides
+//      the line instead (bank.bankLow).
 // Each bar colors by its own fill, NOT the account's threshold state — the
 // StatusTag keeps the account-state colors. Hosts whose backend predates
 // top_up_bank_granted degrade gracefully: the bank renders as a text-only
@@ -37,8 +40,11 @@ import { resolveCreditMeter } from "../lib/creditDisplay";
 // Props:
 //   entitlement  — the /v1/home entitlement union (uses the credits arm).
 //   creditMeter  — the /v1/home credit_meter block (optional).
-export function CreditMeter({ entitlement, creditMeter }) {
-  const view = resolveCreditMeter(entitlement, creditMeter);
+//   credits      — the /v1/home credits block (optional; the authoritative
+//                  two-bucket monthly/additional numbers + renews_on when the
+//                  backend carries it — see CONTRACT.md).
+export function CreditMeter({ entitlement, creditMeter, credits = null }) {
+  const view = resolveCreditMeter(entitlement, creditMeter, credits);
   if (!view) return null;
 
   const { granted, used, remaining, bank, tagVariant, tagLabel, poolBarVariant, bankBarVariant, alert } = view;
@@ -60,27 +66,40 @@ export function CreditMeter({ entitlement, creditMeter }) {
                 Monthly plan credits: {bank.poolRemaining} of {bank.poolGrant}{" "}
                 left
               </Text>
+              {view.renewsOn && (
+                <Text variant="microcopy">Renews on {fmtDate(view.renewsOn)}</Text>
+              )}
               <ProgressBar
                 title={`${bank.poolUsed} of ${bank.poolGrant} used`}
                 value={bank.poolUsed}
                 maxValue={bank.poolGrant > 0 ? bank.poolGrant : 1}
                 showPercentage={true}
+                valueDescription={`${bank.poolUsed} of ${bank.poolGrant} used`}
                 variant={poolBarVariant}
               />
             </Flex>
-            {bank.bankGranted > 0 ? (
+            {/* The additional-credits line rides along only when the account
+                has (or ever bought) a bank — never "0 of 0 left". */}
+            {bank.showAdditional && (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>
+                <Flex direction="row" gap="extra-small" align="center">
+                  <Text>
+                    Additional credits: {bank.bankRemaining} of{" "}
+                    {bank.bankGranted} left
+                  </Text>
+                  {bank.bankLow && (
+                    <StatusTag variant="warning">Running low</StatusTag>
+                  )}
+                </Flex>
+                <Text variant="microcopy">Does not expire</Text>
                 <ProgressBar
                   title={`${bank.bankRemaining} of ${bank.bankGranted} left`}
                   value={bank.bankRemaining}
                   maxValue={bank.bankGranted > 0 ? bank.bankGranted : 1}
                   showPercentage={true}
+                  valueDescription={`${bank.bankRemaining} of ${bank.bankGranted} left`}
                   variant={bankBarVariant}
                 />
               </Flex>
@@ -90,11 +109,9 @@ export function CreditMeter({ entitlement, creditMeter }) {
               // 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>
+                <Text variant="microcopy">Does not expire</Text>
               </Flex>
-            )}
+            ))}
           </>
         ) : (
           <>
@@ -107,6 +124,7 @@ export function CreditMeter({ entitlement, creditMeter }) {
               value={used}
               maxValue={granted > 0 ? granted : 1}
               showPercentage={true}
+              valueDescription={`${used} of ${granted} used`}
               variant={poolBarVariant}
             />
           </>

package/src/home/FeatureUsage.jsx

@@ -0,0 +1,75 @@
+import React from "react";
+import { Flex, Tile, Text, Link } from "@hubspot/ui-extensions";
+import { featureUsageOf } from "../lib/featureUsage";
+
+// The Home "Most used features" / "Recommended to explore" sections, fed by
+// the additive state.feature_usage block (per-app feature registry + credit
+// ledger aggregation in growth-ops-apps-base).
+//
+// Composition: most-used first (what this install actually runs on), then
+// the not-in-use catalog as "Recommended to explore" — each with its
+// one-line rationale and setup-guide link. Each section renders only when it
+// has rows, and the whole thing renders NOTHING when the block is absent
+// (older backends, legacy installs) — absence is never an empty box.
+
+// Singular/plural label for a row's unit ("credits" | "events") — the wire
+// field is credits_or_events, so an event-denominated feature must not be
+// mislabeled as credits.
+const unitLabel = (unit, count) => {
+  const singular = unit === "events" ? "event" : "credit";
+  return count === 1 ? singular : `${singular}s`;
+};
+
+function MostUsedTile({ mostUsed }) {
+  if (mostUsed.length === 0) return null;
+  return (
+    <Tile>
+      <Flex direction="column" gap="small">
+        <Text format={{ fontWeight: "bold" }}>Most used features</Text>
+        {mostUsed.map((f) => (
+          <Flex key={f.key} direction="row" gap="small">
+            <Text>{f.name}</Text>
+            <Text variant="microcopy">
+              {f.count} {unitLabel(f.unit, f.count)}
+            </Text>
+          </Flex>
+        ))}
+      </Flex>
+    </Tile>
+  );
+}
+
+function RecommendedTile({ notInUse }) {
+  if (notInUse.length === 0) return null;
+  return (
+    <Tile>
+      <Flex direction="column" gap="small">
+        <Text format={{ fontWeight: "bold" }}>Recommended to explore</Text>
+        {notInUse.map((f) => (
+          <Flex key={f.key} direction="column" gap="extra-small">
+            <Text format={{ fontWeight: "demibold" }}>{f.name}</Text>
+            {f.rationale ? <Text>{f.rationale}</Text> : null}
+            {f.docsUrl ? (
+              <Link href={{ url: f.docsUrl, external: true }}>
+                Read the guide →
+              </Link>
+            ) : null}
+          </Flex>
+        ))}
+      </Flex>
+    </Tile>
+  );
+}
+
+export function FeatureUsage({ state }) {
+  const view = featureUsageOf(state);
+  if (!view) return null;
+  return (
+    <>
+      <MostUsedTile mostUsed={view.mostUsed} />
+      <RecommendedTile notInUse={view.notInUse} />
+    </>
+  );
+}
+
+export default FeatureUsage;

package/src/home/HealthHero.jsx

@@ -23,6 +23,11 @@ export function HealthHero({ appName, state }) {
   const name = appName ?? state.app?.name;
 
   if (health?.level) {
+    // Plan-fit reinforcement: a healthy verdict on the right plan gets the
+    // extra reassurance line; upgrade_recommended is carried by health
+    // v2's "attention" reasons + the PlanFitBanner, not here.
+    const onRightPlan =
+      health.level === "healthy" && state.plan_fit?.verdict === "right_plan";
     return (
       <Flex direction="column" gap="small">
         {name && <Heading>{name}</Heading>}
@@ -34,6 +39,7 @@ export function HealthHero({ appName, state }) {
             {(health.reasons ?? []).map((r, i) => (
               <Text key={i}>{r}</Text>
             ))}
+            {onRightPlan && <Text>...and you're on the right plan</Text>}
           </Flex>
         </Alert>
       </Flex>

package/src/home/OnboardingChecklist.jsx

@@ -10,6 +10,12 @@ import { Flex, Tile, Text, ProgressBar, Link, Button } from "@hubspot/ui-extensi
 // `onNavigate(route)` is supplied by the host app (PageLink can't be created
 // here without the router); cta_url renders as an external Link.
 export function OnboardingChecklist({ onboarding, onNavigate }) {
+  // The Getting Started checklist disappears entirely once complete — no
+  // "all done" state (Andrew's 2026-10 feedback). AppHome gates on the same
+  // flag; this guard covers direct consumers.
+  if (onboarding?.complete === true) {
+    return null;
+  }
   if (!onboarding || !Array.isArray(onboarding.steps) || onboarding.steps.length === 0) {
     return null;
   }

package/src/home/PeriodComparison.jsx

@@ -0,0 +1,60 @@
+import React from "react";
+import { Flex, Tile, Text, ProgressBar } from "@hubspot/ui-extensions";
+import { resolvePeriodComparison } from "../lib/homeBlocks";
+
+// The post-checklist Home usage block: the last full billing period vs the
+// current period-to-date, side by side — one bar per period (shared
+// denominator, so the bars are visually comparable) with the per-action
+// credit breakdown beneath each. Fed by state.period_comparison, which the
+// backend leaves null until the install has one full closed period; this
+// renders nothing then.
+//
+// Bars are sentiment-free (always "success") — this is a comparison, not a
+// health signal. Normalization (labels, totals, by-action lists, the shared
+// maxTotal) lives in ../lib/homeBlocks (unit-tested).
+function PeriodColumn({ period, maxTotal }) {
+  return (
+    <Flex direction="column" gap="extra-small">
+      <Text format={{ fontWeight: "demibold" }}>{period.label}</Text>
+      <Text>
+        {period.total} {period.total === 1 ? "credit" : "credits"}
+      </Text>
+      <ProgressBar
+        title={`${period.label}: ${period.total} credits`}
+        value={period.total}
+        maxValue={maxTotal}
+        showPercentage={false}
+        valueDescription={`${period.total} credits`}
+        variant="success"
+      />
+      {period.byAction.length > 0 && (
+        <Flex direction="column" gap="extra-small">
+          {period.byAction.map((a) => (
+            <Text key={a.action} variant="microcopy">
+              {a.action}: {a.credits} {a.credits === 1 ? "credit" : "credits"}
+            </Text>
+          ))}
+        </Flex>
+      )}
+    </Flex>
+  );
+}
+
+export function PeriodComparison({ state }) {
+  const view = resolvePeriodComparison(state?.period_comparison);
+  if (!view) return null;
+
+  return (
+    <Tile>
+      <Flex direction="column" gap="small">
+        <Text format={{ fontWeight: "bold" }}>Credits by period</Text>
+        <Flex direction="row" gap="large">
+          <PeriodColumn period={view.last} maxTotal={view.maxTotal} />
+          <PeriodColumn period={view.current} maxTotal={view.maxTotal} />
+        </Flex>
+      </Flex>
+    </Tile>
+  );
+}
+
+export default PeriodComparison;

package/src/home/PlanFitBanner.jsx

@@ -0,0 +1,27 @@
+import React from "react";
+import { Text, Alert } from "@hubspot/ui-extensions";
+import { resolvePlanFit } from "../lib/homeBlocks";
+
+// The plan-fit savings banner: when state.plan_fit.verdict is
+// "upgrade_recommended", tell the customer what staying on their current tier
+// is costing them ("You could save $X/mo by moving to Professional — you
+// bought 3 additional credit packs this period."). The right_plan verdict is
+// NOT a banner — it reinforces the healthy hero instead (HealthHero reads
+// state.plan_fit directly). Copy assembly lives in ../lib/homeBlocks
+// (unit-tested), including the degraded phrasings when the backend can't
+// price the savings yet.
+//
+// Renders nothing when the block is absent or the verdict isn't
+// upgrade_recommended.
+export function PlanFitBanner({ state }) {
+  const fit = resolvePlanFit(state?.plan_fit);
+  if (!fit || fit.kind !== "upgrade_recommended") return null;
+
+  return (
+    <Alert title="You could save on a higher plan" variant="warning">
+      <Text>{fit.text}</Text>
+    </Alert>
+  );
+}
+
+export default PlanFitBanner;

package/src/home/TrialBanner.jsx

@@ -0,0 +1,32 @@
+import React from "react";
+import { Flex, Text, Alert } from "@hubspot/ui-extensions";
+import { resolveTrialBanner } from "../lib/homeBlocks";
+
+// The Home trial banner for credit apps — Andrew's 2026-10 copy, in all three
+// states (active countdown / ended-with-credits-left / out of credits), with
+// the "Need help?" footer line. State selection + copy live in
+// ../lib/homeBlocks (unit-tested); this is pure rendering.
+//
+// Renders nothing for paid plans, non-credits modes, pre-install, or a
+// backend that carries no grant clock (resolveTrialBanner returns null).
+//
+// Props:
+//   state   — the /v1/home payload (reads entitlement + app.name).
+//   appName — display name override; defaults to state.app.name.
+export function TrialBanner({ state, appName }) {
+  const banner = resolveTrialBanner(state?.entitlement, {
+    appName: appName ?? state?.app?.name,
+  });
+  if (!banner) return null;
+
+  return (
+    <Alert title={banner.title} variant={banner.variant}>
+      <Flex direction="column" gap="extra-small">
+        <Text>{banner.body}</Text>
+        <Text variant="microcopy">{banner.footer}</Text>
+      </Flex>
+    </Alert>
+  );
+}
+
+export default TrialBanner;

package/src/home/UsageHighlights.jsx

@@ -0,0 +1,10 @@
+// Reserved slot for the later "most used / not in use" Home section
+// (separate workstream — do NOT build it here). AppHome renders this directly
+// below PeriodComparison in the post-checklist cockpit; it intentionally
+// renders nothing until that section lands, so the composition boundary is
+// already in place.
+export function UsageHighlights({ state }) {
+  return null;
+}
+
+export default UsageHighlights;

package/src/index.js

@@ -11,14 +11,20 @@ export { HealthHero } from "./home/HealthHero";
 export { OnboardingChecklist } from "./home/OnboardingChecklist";
 export { SyncPulse } from "./home/SyncPulse";
 export { FeatureNudges } from "./home/FeatureNudges";
+export { FeatureUsage } from "./home/FeatureUsage";
 export { CreditMeter } from "./home/CreditMeter";
 export { HelpfulLinks } from "./home/HelpfulLinks";
+export { TrialBanner } from "./home/TrialBanner";
+export { PlanFitBanner } from "./home/PlanFitBanner";
+export { PeriodComparison } from "./home/PeriodComparison";
+export { UsageHighlights } from "./home/UsageHighlights";
 
 // Billing.
 export { BillingTab } from "./billing/BillingTab";
 export { PlanGrid } from "./billing/PlanGrid";
 export { BillingBanner } from "./billing/BillingBanner";
 export { SubscriptionGate } from "./billing/SubscriptionGate";
+export { AutoProvisionToggle } from "./billing/AutoProvisionToggle";
 
 // Alerts — the shared customer alerts table (level filter, sort, dismiss).
 export { AlertsTab } from "./alerts/AlertsTab";
@@ -44,12 +50,29 @@ export {
   STATUS_VARIANT,
 } from "./lib/format";
 export { useStrictModeEffect } from "./lib/useStrictModeEffect";
+export { resolveFeatureUsage, featureUsageOf } from "./lib/featureUsage";
 export {
   hasTopUpBank,
   resolveCreditMeter,
   resolveBillingBanner,
   parseLimitInput,
 } from "./lib/creditDisplay";
+export {
+  TRIAL_BANNER_FOOTER,
+  resolveTrialBanner,
+  resolvePlanFit,
+  resolvePeriodComparison,
+} from "./lib/homeBlocks";
+export {
+  AUTO_PROVISION_TITLE,
+  AUTO_PROVISION_CONFIRM_YES,
+  AUTO_PROVISION_CONFIRM_NO,
+  AUTO_PROVISION_IDLE,
+  autoProvisionSubtext,
+  autoProvisionConfirmBody,
+  resolveAutoProvision,
+  autoProvisionReducer,
+} from "./lib/autoProvision";
 
 // HubSpot URL builders (app.hubspot.com record/property/list links).
 export {
@@ -74,6 +97,7 @@ export {
   getTopUps,
   getInvoices,
   setBillingLimit,
+  setAutoProvision,
   getSettings,
   updateSettings,
   makeSettingsApi,

package/src/lib/autoProvision.js

@@ -0,0 +1,82 @@
+// "Add Additional Credits Automatically" — the auto-provision toggle's copy
+// (verbatim from Andrew's 2026-10 feedback, app name templated) plus the tiny
+// state machine behind its ON→OFF confirmation flow. Framework-free so the
+// flow is unit-testable; AutoProvisionToggle (../billing) stays thin.
+//
+// state.auto_provision = { enabled } is additive on the /v1/home payload and
+// REPLACES the old billing-limit concept: enabled (the DEFAULT — also when
+// the block is absent) buys another pack when monthly credits run out;
+// disabled means no purchase and actions start failing the entitlement gate.
+
+export const AUTO_PROVISION_TITLE = "Add Additional Credits Automatically";
+
+export function autoProvisionSubtext(appName) {
+  return `If monthly credits are used, this will automatically purchase another pack of credits so use of ${appName} is not impacted.`;
+}
+
+export function autoProvisionConfirmBody(appName) {
+  return `Are you sure you want to disable automatic credit provisioning? If monthly credits are used, ${appName} will no longer function and workflow actions will fail.`;
+}
+
+export const AUTO_PROVISION_CONFIRM_YES = "Yes, disable this feature.";
+export const AUTO_PROVISION_CONFIRM_NO =
+  "No, keep automatic credit provisioning enabled.";
+
+// Read the account flag with its contract default: enabled UNLESS the block
+// explicitly says false.
+export function resolveAutoProvision(autoProvision) {
+  return { enabled: autoProvision?.enabled !== false };
+}
+
+// The toggle's interaction state. `enabled` itself lives in the component
+// (seeded from the payload, updated on save); this machine owns everything
+// around it: the ON→OFF confirmation and the in-flight POST.
+//   idle       — nothing happening
+//   confirming — the user flipped ON→OFF; the confirmation panel is up and
+//                the toggle stays checked until they decide
+//   saving     — the auto-provision POST is in flight
+export const AUTO_PROVISION_IDLE = {
+  phase: "idle",
+  notice: null, // null | { variant: "success"|"error", text }
+};
+
+// Events:
+//   { type: "request", enabled }  — the user flipped the toggle to `enabled`.
+//       OFF requests park in `confirming` (the dangerous direction); ON
+//       requests save immediately (no confirmation to turn protection ON).
+//   { type: "confirm" }           — "Yes, disable this feature."
+//   { type: "cancel" }            — "No, keep automatic credit provisioning enabled."
+//   { type: "saved" }             — the POST succeeded
+//   { type: "failed", message }   — the POST failed
+export function autoProvisionReducer(state, action) {
+  switch (action.type) {
+    case "request":
+      if (state.phase === "saving") return state;
+      return action.enabled === false
+        ? { phase: "confirming", notice: null }
+        : { phase: "saving", notice: null };
+    case "confirm":
+      if (state.phase !== "confirming") return state;
+      return { phase: "saving", notice: null };
+    case "cancel":
+      if (state.phase !== "confirming") return state;
+      return { phase: "idle", notice: null };
+    case "saved":
+      return {
+        phase: "idle",
+        notice: { variant: "success", text: "Saved." },
+      };
+    case "failed":
+      return {
+        phase: "idle",
+        notice: {
+          variant: "error",
+          text: action.message ?? "Couldn't update automatic credit provisioning.",
+        },
+      };
+    case "dismiss-notice":
+      return { ...state, notice: null };
+    default:
+      return state;
+  }
+}