@growth-operations/ui-shared 1.21.2 → 1.23.0

package/package.json

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

package/src/billing/BillingBanner.jsx

@@ -19,6 +19,11 @@ import { resolveBillingBanner } from "../lib/creditDisplay";
 //                     successful top-up): actions are paused until the next
 //                     billing period or a successful top-up.
 //
+// Andrew 2026-10-13 (banner consolidation): this is the ONE banner — the
+// free-grant trial states (out of credits / trial ended -> RED, trial active
+// -> YELLOW, with the "Need help?" footer) fly HERE on every page; the
+// separate Home-mounted TrialBanner is retired. Copy reused verbatim from it.
+//
 // Legacy metered accounts are unchanged: they only ever see threshold_state
 // "healthy"/"depleted" with over_included doing the talking — overage is
 // "paying overage, not blocked" (the 2026-09-02 incident: a paid account
@@ -35,6 +40,8 @@ import { resolveBillingBanner } from "../lib/creditDisplay";
 //   actionsNoun — short noun phrase for the running-low / paused messages,
 //                 e.g. "file actions" / "task actions". Falls back to
 //                 "actions".
+//   appName     — display name override for the trial-state copy; defaults to
+//                 state.app.name, then "this app".
 //   onNavigate  — in-app PageLink-equivalent callback (the host owns the
 //                 router — see ui-shared's OnboardingChecklist for the same
 //                 pattern). Renders the in-app Billing CTA when provided;
@@ -49,10 +56,11 @@ import { resolveBillingBanner } from "../lib/creditDisplay";
 //                 and the external portal CTA (kind "portal") is NOT
 //                 suppressed. Omitting the prop keeps the legacy behavior
 //                 (button always rendered), so non-updated hosts don't break.
-export function BillingBanner({ state, actionLabel, actionsNoun, onNavigate, context, currentPath }) {
+export function BillingBanner({ state, actionLabel, actionsNoun, appName, onNavigate, context, currentPath }) {
   const banner = resolveBillingBanner(state?.entitlement, {
     actionLabel,
     actionsNoun,
+    appName: appName ?? state?.app?.name,
   });
   if (!banner) return null;
 
@@ -88,6 +96,9 @@ export function BillingBanner({ state, actionLabel, actionsNoun, onNavigate, con
     <Alert title={banner.title} variant={banner.variant}>
       <Flex direction="column" gap="extra-small">
         <Text>{banner.message}</Text>
+        {/* The support footer line rides the trial-state banners (the same
+            microcopy the retired Home TrialBanner rendered). */}
+        {banner.footer && <Text variant="microcopy">{banner.footer}</Text>}
         {banner.cta?.kind === "portal" && portalStartUrl ? (
           <Button
             variant="secondary"

package/src/billing/BillingTab.jsx

@@ -16,7 +16,7 @@ import {
   TableRow,
   TableCell,
 } from "@hubspot/ui-extensions";
-import { fmtDate, fmtMoney, daysUntil } from "../lib/format";
+import { fmtDate, fmtMoney, daysUntil, SUPPORT_FOOTER } from "../lib/format";
 import { useStrictModeEffect } from "../lib/useStrictModeEffect";
 import { CreditMeter } from "../home/CreditMeter";
 import { PlanGrid } from "./PlanGrid";
@@ -82,7 +82,14 @@ function useRefreshedBillingActionTokens(billingBaseUrl, initialTokens) {
 // Color-coded account-status panel (per Andrew's billing feedback): trial =>
 // yellow + days left + end date; active => green + next renewal; past_due =>
 // red + warning. Replaces the low-value flat-rate invoice chart.
-function StatusPanel({ entitlement }) {
+//
+// plansAvailable / restartAvailable describe what the canceled customer can
+// actually SEE below the panel (exported for tests). When a catalog gap
+// leaves plans EMPTY (2026-10-13 sparkfly incident) the "below" copy would
+// promise a grid that isn't there — so it swaps to copy that matches the
+// standalone restart button (or, without a restart token, the Stripe link
+// above), plus the support footer the dead end needs.
+export function StatusPanel({ entitlement, plansAvailable = true, restartAvailable = false }) {
   if (!entitlement) return null;
   const {
     status,
@@ -207,8 +214,15 @@ function StatusPanel({ entitlement }) {
   }
 
   if (status === "canceled") {
-    const resumeCta =
-      mode === "credits"
+    // plansAvailable === false means the catalog mirror came back EMPTY — no
+    // grid renders below, so the copy must not say "below". With a restart
+    // token the standalone one-click restart button (rendered under this
+    // panel) is the recovery path; without one, the Stripe link above is.
+    const resumeCta = !plansAvailable
+      ? restartAvailable
+        ? "Restart your previous plan in one click — we charge your card on file and your data starts syncing again."
+        : "Manage your billing in Stripe with the link above to resume — your data starts syncing again."
+      : mode === "credits"
         ? "Choose a plan below to start a new subscription."
         : "Restart your previous plan below in one click, or choose a different one — either way your data starts syncing again.";
     return (
@@ -216,6 +230,9 @@ function StatusPanel({ entitlement }) {
         <Flex direction="column" gap="extra-small">
           <Text format={{ fontWeight: "bold" }}>Your subscription was canceled</Text>
           <Text>{resumeCta}</Text>
+          {!plansAvailable && (
+            <Text variant="microcopy">{SUPPORT_FOOTER}</Text>
+          )}
         </Flex>
       </Alert>
     );
@@ -228,7 +245,8 @@ function StatusPanel({ entitlement }) {
   );
 }
 
-function TrialSubscriptionBilling({ context, state, appKey, openIframe = null }) {
+// Exported for tests (the canceled/empty-catalog restart fallback).
+export function TrialSubscriptionBilling({ context, state, appKey, openIframe = null }) {
   const ent = state?.entitlement;
 
   // Install not provisioned with a Stripe customer yet — calm "finish setup"
@@ -316,6 +334,21 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
     (isTrialing && currentOrder != null && plans.length > 0) ||
     (needsCheckout && plans.length > 0);
 
+  // Empty-catalog restart fallback (2026-10-13 sparkfly incident): a catalog
+  // data gap can leave `plans` EMPTY for a canceled account — showPicker then
+  // hides the grid while the panel copy still promised one. With no grid to
+  // pick from, the one-click restart becomes THE recovery path: a standalone
+  // primary button hitting /v1/billing/restart/start with NO price_id (the
+  // billing service resolves the account's last subscription price
+  // server-side). Requires the restart action token; legacy/Anvil-mode
+  // entitlements are excluded defensively (BillingTab's mode switch already
+  // routes mode "legacy" to LegacyBilling, so this arm is unreachable for
+  // them — the guard keeps it that way if the switch ever changes).
+  const standaloneRestartUrl =
+    isCanceled && plans.length === 0 && ent.mode !== "legacy"
+      ? keepSubscriptionUrl
+      : null;
+
   return (
     <Flex direction="column" gap="medium">
       {/* PRIMARY CTA when there's an existing subscription to manage
@@ -331,7 +364,11 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
         {portalStartUrl ? "Manage billing in Stripe" : "Preparing billing…"}
       </LoadingButton>
 
-      <StatusPanel entitlement={state?.entitlement} />
+      <StatusPanel
+        entitlement={state?.entitlement}
+        plansAvailable={!needsCheckout || plans.length > 0}
+        restartAvailable={standaloneRestartUrl != null}
+      />
 
       {/* Scheduled-cancel on an ACTIVE sub: one click flips
           cancel_at_period_end off in place (no re-checkout, no new sub) —
@@ -343,9 +380,23 @@ function TrialSubscriptionBilling({ context, state, appKey, openIframe = null })
         </Button>
       )}
 
+      {/* CANCELED with an EMPTY catalog (no grid to pick from): the
+          price_id-less one-click restart is the recovery path, rendered
+          under the status panel. Reuses keepSubscriptionUrl — the restart
+          endpoint never needed a price_id client-side. */}
+      {standaloneRestartUrl && (
+        <Button href={{ url: standaloneRestartUrl, external: true }} variant="primary">
+          Restart your previous plan
+        </Button>
+      )}
+
       <Text format={{ fontStyle: "italic" }}>
         {needsCheckout
-          ? "Choose a plan below to resume. Once you have an active subscription, use the link above to manage payment methods or view invoices."
+          ? isCanceled && plans.length === 0
+            ? standaloneRestartUrl
+              ? "Restart charges your card on file and resumes syncing immediately — no checkout page. Once you have an active subscription, use the link above to manage payment methods or view invoices."
+              : "Once you have an active subscription, use the link above to manage payment methods or view invoices."
+            : "Choose a plan below to resume. Once you have an active subscription, use the link above to manage payment methods or view invoices."
           : "Billing is managed in Stripe across all Growth Operations apps. Use the link above to update your plan, payment method, or view invoices."}
       </Text>
 

package/src/home/AppHome.jsx

@@ -5,7 +5,6 @@ import { HealthHero } from "./HealthHero";
 import { OnboardingChecklist } from "./OnboardingChecklist";
 import { SyncPulse } from "./SyncPulse";
 import { FeatureUsage } from "./FeatureUsage";
-import { TrialBanner } from "./TrialBanner";
 import { PlanFitBanner } from "./PlanFitBanner";
 import { PeriodComparison } from "./PeriodComparison";
 import { FeatureNudges } from "./FeatureNudges";
@@ -49,8 +48,9 @@ function PipelineTile({ pipeline }) {
 // Picks the single archetype activity tile (CONTRACT: at most ONE present).
 // sync_pulse -> SyncPulse; pipeline -> PipelineTile. The credit meter is
 // deliberately NOT on Home anymore (Andrew's 2026-10 feedback) — it lives at
-// the top of the Usage tab; Home's credit story is the trial banner plus the
-// post-checklist period comparison. Renders nothing when no tile applies.
+// the top of the Usage tab; Home's credit story is the top BillingBanner's
+// trial states plus the post-checklist period comparison. Renders nothing
+// when no tile applies.
 function ArchetypeTile({ state }) {
   if (state.sync_pulse) return <SyncPulse syncPulse={state.sync_pulse} />;
   if (state.pipeline) return <PipelineTile pipeline={state.pipeline} />;
@@ -63,8 +63,7 @@ function ArchetypeTile({ state }) {
 // Lifecycle composition:
 //   no state            -> LoadingSpinner (still fetching /v1/home)
 //   activation pending  -> <InstallProgress> (install isn't finished yet)
-//   activated cockpit   -> <TrialBanner> (credit apps on the free grant)
-//                          + <HealthHero> (+ "...on the right plan" when
+//   activated cockpit   -> <HealthHero> (+ "...on the right plan" when
 //                            plan_fit says so)
 //                          + <PlanFitBanner> (upgrade_recommended only)
 //                          + <OnboardingChecklist> (only if not complete)
@@ -136,10 +135,9 @@ export function AppHome({ state, onNavigate, appName, onRetry, helpfulLinks }) {
           callout above the cockpit; InstallProgress renders null when clean. */}
       <InstallProgress state={state} onRetry={onRetry} />
 
-      {/* Trial states (active countdown / ended / out of credits) fly above
-          the hero — they're the strongest call to action a free account
-          has. Renders null for paid plans and non-credits modes. */}
-      <TrialBanner state={state} appName={appName} />
+      {/* No Home trial banner anymore — Andrew 2026-10-13: trial states (and
+          every other app-stopping billing condition) fly in the ONE top
+          <BillingBanner> the app layout mounts above every route. */}
 
       <HealthHero appName={appName} state={state} />
 

package/src/home/FeatureUsage.jsx

@@ -1,6 +1,10 @@
 import React from "react";
 import { Flex, Tile, Text, Link } from "@hubspot/ui-extensions";
-import { featureUsageOf } from "../lib/featureUsage";
+import {
+  featureUsageOf,
+  pickDailyRecommendations,
+  recommendationsRotated,
+} 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
@@ -44,21 +48,33 @@ function MostUsedTile({ mostUsed }) {
 
 function RecommendedTile({ notInUse }) {
   if (notInUse.length === 0) return null;
+  // Long lists (ATS: 13 features) render as a rotating daily slice instead of
+  // a wall — the whole list still arrives in the payload; the window is a
+  // pure function of the UTC date (see ../lib/featureUsage).
+  const picks = pickDailyRecommendations(
+    notInUse,
+    new Date().toISOString().slice(0, 10)
+  );
   return (
     <Tile>
       <Flex direction="column" gap="small">
         <Text format={{ fontWeight: "bold" }}>Recommended to explore</Text>
-        {notInUse.map((f) => (
+        {picks.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 →
+                Learn more →
               </Link>
             ) : null}
           </Flex>
         ))}
+        {recommendationsRotated(notInUse) ? (
+          <Text variant="microcopy">
+            New picks daily — {notInUse.length} features to explore in all.
+          </Text>
+        ) : null}
       </Flex>
     </Tile>
   );

package/src/index.js

@@ -14,7 +14,6 @@ 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";
@@ -48,9 +47,15 @@ export {
   statusVariant,
   STATUS_LABELS,
   STATUS_VARIANT,
+  SUPPORT_FOOTER,
 } from "./lib/format";
 export { useStrictModeEffect } from "./lib/useStrictModeEffect";
-export { resolveFeatureUsage, featureUsageOf } from "./lib/featureUsage";
+export {
+  resolveFeatureUsage,
+  featureUsageOf,
+  pickDailyRecommendations,
+  recommendationsRotated,
+} from "./lib/featureUsage";
 export {
   hasTopUpBank,
   creditsBlockOf,
@@ -59,8 +64,6 @@ export {
   parseLimitInput,
 } from "./lib/creditDisplay";
 export {
-  TRIAL_BANNER_FOOTER,
-  resolveTrialBanner,
   resolvePlanFit,
   planFitOf,
   resolvePeriodComparison,

package/src/lib/creditDisplay.js

@@ -25,6 +25,7 @@
 //   double-guards so a stale/mixed payload can't regress the 2026-09-02
 //   incident where a paying, overage account was shown a blocking
 //   "Depleted"/"out of credits" panel).
+import { daysUntil, SUPPORT_FOOTER } from "./format";
 
 // 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 >
@@ -311,9 +312,77 @@ export function resolveCreditMeter(entitlement, creditMeter, credits = null) {
   };
 }
 
+// --- Free-grant trial states (consolidated into the TOP banner) ------------
+
+// Andrew 2026-10-13: ONE banner at the top of every page. Anything that STOPS
+// the app — out of credits, trial ended, payment failed — flies RED in the
+// top BillingBanner; "trial active" flies YELLOW there too. The separate
+// Home-mounted TrialBanner is retired; its copy (approved by the product
+// owner) is reused VERBATIM here — only the placement and the trial-ended
+// variant (warning -> error: it stops the app) changed.
+//
+// First match wins inside trialStateOf, mirroring the retired resolver:
+//   out of credits  — the free grant is spent (depleted / remaining <= 0).
+//                     Beats the clock: a burned-through grant is "out of
+//                     credits" even with days left.
+//   trial ended     — the grant's 30-day clock ran out with credits left.
+//   trial active    — the clock is still running: "[XX] trial days remaining".
+// Returns { kind, title, body } or null (no grant clock on record).
+function trialStateOf(ent, { appName } = {}) {
+  const name = appName ?? "this app";
+  const granted = ent.granted ?? 0;
+  const used = ent.used ?? 0;
+  const remaining = ent.remaining ?? Math.max(granted - used, 0);
+  const daysLeft =
+    ent.grant_expires_at != null ? daysUntil(ent.grant_expires_at) : null;
+
+  if (ent.depleted === true || remaining <= 0) {
+    return {
+      kind: "out_of_credits",
+      title: "You're out of credits",
+      body: `You have used ${used}/${granted} free credits. Select one of the plans below to continue use of ${name}.`,
+    };
+  }
+  if (daysLeft != null && daysLeft <= 0) {
+    return {
+      kind: "trial_ended",
+      title: "Your trial has ended",
+      body: `Your free trial has ended. Select a plan to continue use of ${name}.`,
+    };
+  }
+  if (daysLeft != null) {
+    return {
+      kind: "trial_active",
+      title: `${daysLeft} trial days remaining`,
+      body: `You have ${daysLeft} days remaining in your trial period. Select a plan to continue use of ${name}.`,
+    };
+  }
+  return null;
+}
+
+// Trial states map onto the banner shape with the shared support footer and a
+// Billing-tab CTA (the copy asks for a plan; on non-Home pages nothing is
+// "below", so the button routes to the picker). out-of-credits/trial-ended
+// are RED (they stop the app), trial-active is YELLOW — Andrew 2026-10-13.
+const TRIAL_STATE_VARIANT = {
+  out_of_credits: "error",
+  trial_ended: "error",
+  trial_active: "warning",
+};
+
+function trialBannerView(trial) {
+  return {
+    variant: TRIAL_STATE_VARIANT[trial.kind],
+    title: trial.title,
+    message: trial.body,
+    footer: SUPPORT_FOOTER,
+    cta: { kind: "billing", label: "Go to Billing →" },
+  };
+}
+
 // Resolve the app-wide BillingBanner from the credits entitlement arm.
 // Returns null to render nothing (non-credits mode, pre-install, or healthy),
-// else { variant, title, message, cta } where cta is null or:
+// else { variant, title, message, footer?, cta } where cta is null or:
 //   { kind: "portal",  label } — link out to the Stripe billing-portal entry
 //                                point (payment-method fixes)
 //   { kind: "billing", label } — in-app navigate to the Billing tab
@@ -321,7 +390,23 @@ export function resolveCreditMeter(entitlement, creditMeter, credits = null) {
 // Driven by threshold_state for the top-up model; the legacy metered branches
 // (free depleted / paid over_included / free running-low) are byte-identical
 // to the pre-top-up banner.
-export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } = {}) {
+//
+// Precedence (first match wins):
+//   1. top_up_pending  (info)    — transient in-flight top-up
+//   2. top_up_failed   (error)   — card on file failed to process
+//   3. limit_reached   (warning)
+//   4. depleted        (error)   — THE out-of-credits block; existing
+//                                  byte-identical copy wins whenever the
+//                                  explicit signals (threshold_state /
+//                                  depleted flag / entitled=false) fire
+//   5. trial out_of_credits (error) — free grant spent WITHOUT the explicit
+//                                  signals (remaining <= 0 catch-all)
+//   6. trial ended     (error)   — the grant clock ran out with credits left
+//   7. over_included   (warning) — paid metered overage (never blocked)
+//   8. running low     (warning) — free grant under low_threshold
+//   9. trial active    (warning) — the countdown; yields to running-low, the
+//                                  more urgent of the two yellow states
+export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun, appName } = {}) {
   const ent = entitlement;
   if (!ent || ent.mode !== "credits" || ent.status === "not_installed") {
     return null;
@@ -362,6 +447,14 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
     };
   }
 
+  // The free-grant trial states (null for paid plans — a paid plan is past
+  // the trial). Computed BEFORE the depleted branch: a lapsed trial clock
+  // explains a legacy `entitled: false` reading better than "out of credits"
+  // (credits remain; the GRANT expired), so trial_ended wins over that one
+  // legacy signal below — but never over an explicit depleted flag or
+  // threshold_state "depleted".
+  const trial = onPaidPlan ? null : trialStateOf(ent, { appName });
+
   // --- Hard-blocked. threshold_state "depleted" is the ONLY blocking state
   // (a topup-model paid plan blocks at true zero); `over_included` overrides
   // a depleted reading so a metered paid account in overage is never shown as
@@ -371,7 +464,9 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
   const depleted =
     thresholdState != null
       ? thresholdState === "depleted" && !overIncluded
-      : !onPaidPlan && (ent.depleted === true || ent.entitled === false);
+      : !onPaidPlan &&
+        (ent.depleted === true ||
+          (ent.entitled === false && trial?.kind !== "trial_ended"));
 
   if (depleted) {
     return {
@@ -383,6 +478,11 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
       cta: { kind: "billing", label: "Go to Billing →" },
     };
   }
+  // Free-grant blockers the explicit signals didn't catch: the spent grant
+  // (remaining <= 0 without any flag) and the lapsed trial clock.
+  if (trial && (trial.kind === "out_of_credits" || trial.kind === "trial_ended")) {
+    return trialBannerView(trial);
+  }
   if (overIncluded) {
     return {
       variant: "warning",
@@ -405,6 +505,11 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
       cta: { kind: "billing", label: "Go to Billing →" },
     };
   }
+  // Trial active — the countdown flies at the top in YELLOW for the whole
+  // trial (Andrew 2026-10-13), yielding only to running-low above.
+  if (trial?.kind === "trial_active") {
+    return trialBannerView(trial);
+  }
 
   return null;
 }

package/src/lib/featureUsage.js

@@ -52,3 +52,44 @@ export function featureUsageOf(state) {
   if (!state || typeof state !== "object") return null;
   return resolveFeatureUsage(state.state?.feature_usage ?? state.feature_usage);
 }
+
+// --- Recommendation rotation ------------------------------------------------
+
+// A long not_in_use list is a firehose: a fresh install of a big app (ATS
+// has 13 registered features) gets the whole registry dumped on Home exactly
+// when focus matters most, and a wall of 13 "Read the guide" links teaches
+// nothing. So short lists (<= RECOMMENDATION_WHOLE_LIST_MAX) render whole;
+// longer lists show a deterministic daily slice that rotates day over day.
+// The seed is the UTC date alone — same picks all day, no per-portal state,
+// no backend involvement (the full list still arrives in the payload).
+export const RECOMMENDATION_PICK_COUNT = 3;
+export const RECOMMENDATION_WHOLE_LIST_MAX = 4;
+
+// djb2 over the date string — tiny, stable across browsers, good enough for
+// a day offset (not a security or money decision).
+export function rotationDayHash(dateISO) {
+  let h = 5381;
+  for (let i = 0; i < dateISO.length; i++) {
+    h = ((h << 5) + h + dateISO.charCodeAt(i)) >>> 0;
+  }
+  return h;
+}
+
+// The slice to render for `todayISO` ("YYYY-MM-DD", UTC). Order within the
+// day stays registry order; the window wraps around the end of the list.
+// Pure + date-injected so tests don't depend on the wall clock.
+export function pickDailyRecommendations(notInUse, todayISO) {
+  if (!Array.isArray(notInUse)) return [];
+  if (notInUse.length <= RECOMMENDATION_WHOLE_LIST_MAX) return notInUse;
+  const start = rotationDayHash(todayISO) % notInUse.length;
+  return Array.from(
+    { length: RECOMMENDATION_PICK_COUNT },
+    (_, i) => notInUse[(start + i) % notInUse.length]
+  );
+}
+
+// True when rotation truncated the list — the tile shows a quiet "new picks
+// daily" hint only then, so small registries read exactly as before.
+export function recommendationsRotated(notInUse) {
+  return Array.isArray(notInUse) && notInUse.length > RECOMMENDATION_WHOLE_LIST_MAX;
+}

package/src/lib/format.js

@@ -1,6 +1,12 @@
 // Shared formatting + status helpers for Growth Operations app UIs.
 // Framework-agnostic (no React) so they can be unit-reasoned and reused.
 
+// The support footer line shared by customer-facing dead-end/urgency surfaces
+// (the top billing banner's trial states, the Billing tab's empty-catalog
+// canceled panel). Formerly TRIAL_BANNER_FOOTER on the retired Home
+// TrialBanner — promoted here once a second surface needed it.
+export const SUPPORT_FOOTER = "Need help? info@growthoperationsco.com";
+
 // ISO datetime string (or ms epoch) -> "Mon DD, YYYY", null-safe.
 // new Date(NaN).toLocaleDateString() would throw, so guard it.
 export function fmtDate(value) {

package/src/lib/homeBlocks.js

@@ -1,71 +1,16 @@
 // Pure resolvers for the Home cockpit blocks added for Andrew's 2026-10
-// App Home feedback: the trial banner (three states), the plan-fit signal,
-// and the period-over-period credit comparison. Framework-free (no React) so
-// the branch math is unit-testable; the components in ../home stay thin.
+// App Home feedback: the plan-fit signal and the period-over-period credit
+// comparison. Framework-free (no React) so the branch math is unit-testable;
+// the components in ../home stay thin.
+//
+// (The trial banner used to live here. Andrew 2026-10-13: ONE banner at the
+// top of every page — the trial states moved into resolveBillingBanner in
+// ./creditDisplay, copy verbatim, and the Home-mounted <TrialBanner> is
+// retired.)
 //
 // Everything here degrades gracefully: every block is additive on the
 // /v1/home payload, and a resolver returns null (render nothing) whenever
 // the fields it needs are absent.
-import { daysUntil } from "./format";
-
-// --- Trial banner ----------------------------------------------------------
-
-// Rides under every trial banner (Andrew's exact copy).
-export const TRIAL_BANNER_FOOTER = "Need help? info@growthoperationsco.com";
-
-// Resolve the Home trial banner from the credits entitlement arm.
-// Returns null (render nothing) for non-credits modes, paid plans (the trial
-// is over), pre-install, or a backend that carries no grant clock. Otherwise
-// { variant, title, body, footer } — copy verbatim from Andrew, with the app
-// display name templated in.
-//
-// State selection (first match wins):
-//   out of credits  — the free grant is spent (depleted / remaining <= 0).
-//                     Beats the clock: a burned-through grant is "out of
-//                     credits" even with days left.
-//   trial ended     — the grant's 30-day clock ran out with credits left.
-//   trial active    — the clock is still running: "[XX] trial days remaining".
-export function resolveTrialBanner(entitlement, { appName } = {}) {
-  const ent = entitlement;
-  if (!ent || ent.mode !== "credits") return null;
-  if (ent.plan) return null; // a paid plan is past the trial
-  if (ent.status === "not_installed") return null;
-  const name = appName ?? "this app";
-
-  const granted = ent.granted ?? 0;
-  const used = ent.used ?? 0;
-  const remaining = ent.remaining ?? Math.max(granted - used, 0);
-  const daysLeft =
-    ent.grant_expires_at != null ? daysUntil(ent.grant_expires_at) : null;
-
-  if (ent.depleted === true || remaining <= 0) {
-    return {
-      variant: "error",
-      title: "You're out of credits",
-      body: `You have used ${used}/${granted} free credits. Select one of the plans below to continue use of ${name}.`,
-      footer: TRIAL_BANNER_FOOTER,
-    };
-  }
-  if (daysLeft != null && daysLeft <= 0) {
-    return {
-      variant: "warning",
-      title: "Your trial has ended",
-      body: `Your free trial has ended. Select a plan to continue use of ${name}.`,
-      footer: TRIAL_BANNER_FOOTER,
-    };
-  }
-  if (daysLeft != null) {
-    return {
-      variant: "info",
-      title: `${daysLeft} trial days remaining`,
-      body: `You have ${daysLeft} days remaining in your trial period. Select a plan to continue use of ${name}.`,
-      footer: TRIAL_BANNER_FOOTER,
-    };
-  }
-  // No grant clock on record (a backend that predates grant_expires_at) —
-  // nothing to count down, so no banner.
-  return null;
-}
 
 // --- Plan fit ---------------------------------------------------------------
 

package/src/home/TrialBanner.jsx

@@ -1,32 +0,0 @@
-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;