@growth-operations/ui-shared 1.26.1 → 1.27.0

package/package.json

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

package/src/home/HealthHero.jsx

@@ -31,21 +31,31 @@ export function HealthHero({ appName, state }) {
     const planFit = state.state?.plan_fit ?? state.plan_fit;
     const onRightPlan =
       health.level === "healthy" && planFit?.verdict === "right_plan";
+    const reasons = health.reasons ?? [];
+    // The reassurance rides in the TITLE, not the Alert body: HubSpot's Alert
+    // lays icon + title + children out side-by-side and the children column
+    // does NOT grow to fill the banner (Box flex="auto" didn't win — the body
+    // still wrapped narrow with half the banner empty, seen on the ATS Home
+    // hero 2026-10-14). The title slot grows with its content, so the line
+    // renders full-width on one line. The body is reserved for actual
+    // reasons (attention/critical), and omitted entirely when there are none.
+    const baseTitle = HEALTH_TITLE[health.level] ?? "Status";
+    const title = onRightPlan
+      ? `${baseTitle} — and you're on the right plan`
+      : baseTitle;
     return (
       <Flex direction="column" gap="small">
         {name && <Heading>{name}</Heading>}
-        <Alert
-          title={HEALTH_TITLE[health.level] ?? "Status"}
-          variant={HEALTH_VARIANT[health.level] ?? "info"}
-        >
-          <Box flex="auto">
-            <Flex direction="column" gap="extra-small">
-              {(health.reasons ?? []).map((r, i) => (
-                <Text key={i}>{r}</Text>
-              ))}
-              {onRightPlan && <Text>...and you're on the right plan</Text>}
-            </Flex>
-          </Box>
+        <Alert title={title} variant={HEALTH_VARIANT[health.level] ?? "info"}>
+          {reasons.length > 0 && (
+            <Box flex="auto">
+              <Flex direction="column" gap="extra-small">
+                {reasons.map((r, i) => (
+                  <Text key={i}>{r}</Text>
+                ))}
+              </Flex>
+            </Box>
+          )}
         </Alert>
       </Flex>
     );

package/src/home/PeriodComparison.jsx

@@ -1,17 +1,23 @@
 import React from "react";
-import { Flex, Tile, Text, ProgressBar } from "@hubspot/ui-extensions";
+import { Flex, Tile, Text, ProgressBar, BarChart } from "@hubspot/ui-extensions";
 import { periodComparisonOf } 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.
+// The post-checklist Home usage block: credits per billing period. Two
+// renderings, picked off the resolved view's `kind`:
 //
-// 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).
+//   "periods" — the backend shipped the additive `periods` payload (2–3
+//     windows, oldest → newest, friendly slice names): ONE stacked BarChart,
+//     one bar per billing period, stacks = features. The per-period totals
+//     line underneath preserves what the progress bars showed.
+//   "legacy"  — pre-periods backend: the last full period vs the current
+//     period-to-date as two progress-bar columns with the raw per-action
+//     breakdown beneath each.
+//
+// Both are fed by state.period_comparison, which the backend leaves null
+// until the install has one full closed period; this renders nothing then.
+// Normalization (labels, totals, chart rows/colors/caption) lives in
+// ../lib/homeBlocks (unit-tested).
+
 function PeriodColumn({ period, maxTotal }) {
   return (
     <Flex direction="column" gap="extra-small">
@@ -40,6 +46,35 @@ function PeriodColumn({ period, maxTotal }) {
   );
 }
 
+// key={fingerprint}: BarChart is a HubSpot "remote component" (rendered
+// outside this iframe via HubSpot's bridge) — a prop/data change alone was
+// confirmed NOT to update a rendered chart (see UsageTab), so a payload
+// refresh must HARD-REMOUNT it via the React key, not re-render in place.
+function PeriodsChart({ chart }) {
+  const fingerprint = chart.rows
+    .map((r) => `${r.period}|${r.feature}|${r.credits}`)
+    .join(";");
+  return (
+    <Flex direction="column" gap="small">
+      <BarChart
+        key={fingerprint}
+        data={chart.rows}
+        axes={{
+          x: { field: "period", fieldType: "category", label: "Billing period" },
+          y: { field: "credits", fieldType: "linear", label: "Credits" },
+          options: {
+            groupFieldByColor: "feature",
+            stacking: true,
+            colors: chart.colors,
+          },
+        }}
+        options={{ showLegend: true, showTooltips: true, showDataLabels: false }}
+      />
+      <Text variant="microcopy">{chart.caption}</Text>
+    </Flex>
+  );
+}
+
 export function PeriodComparison({ state }) {
   // periodComparisonOf dual-reads payload.state.period_comparison (base) ??
   // payload.period_comparison (self-hosted).
@@ -50,10 +85,14 @@ export function PeriodComparison({ state }) {
     <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>
+        {view.kind === "periods" ? (
+          <PeriodsChart chart={view.chart} />
+        ) : (
+          <Flex direction="row" gap="large">
+            <PeriodColumn period={view.last} maxTotal={view.maxTotal} />
+            <PeriodColumn period={view.current} maxTotal={view.maxTotal} />
+          </Flex>
+        )}
       </Flex>
     </Tile>
   );

package/src/lib/homeBlocks.js

@@ -70,13 +70,81 @@ export function planFitOf(state) {
 
 // --- Period comparison ------------------------------------------------------
 
+// The stacked chart's slice palette, in assignment order. HubSpot's chart
+// `colors` map takes NAMED palette colors only (hex values are not in the
+// ChartColor union). "Other" — the server-side fold of every slice past the
+// top 7 — is pinned to darkOrange so folding never reshuffles the named
+// slices' colors.
+const CHART_PALETTE = ["orange", "aqua", "purple", "yellow", "pink", "blue", "green"];
+const OTHER_SLICE = "Other";
+const OTHER_SLICE_COLOR = "darkOrange";
+
+// The chart payload off the additive `periods` key (2–3 billing-period
+// windows, oldest → newest, friendly slice names). Returns:
+//   { rows, colors, labels, caption }
+// rows    — long-format [{period, feature, credits}], period-major
+//           oldest→newest, ready for BarChart's category x-axis. A zero-usage
+//           period contributes ONE 0-credit row so its bar renders empty
+//           instead of the category collapsing off the x-axis; the filler
+//           borrows the first named slice so the legend gains no phantom
+//           entry.
+// colors  — {featureName: paletteColor} over the alphabetical union of slice
+//           names across ALL periods (the same feature keeps its color across
+//           bars); "Other" pinned to darkOrange.
+// caption — the per-period totals line ("Sep 1 – Sep 30: 210 credits · …")
+//           preserving what the legacy progress bars showed.
+// Returns null for a missing/malformed `periods` (the caller falls back to
+// the legacy two-column rendering).
+function resolvePeriodsChart(periods) {
+  if (!Array.isArray(periods) || periods.length === 0) return null;
+  const normd = [];
+  for (const p of periods) {
+    if (!p || typeof p !== "object" || typeof p.label !== "string") return null;
+    const slices = Array.isArray(p.by_action)
+      ? p.by_action
+          .filter((a) => a && (a.name ?? a.action) != null)
+          .map((a) => ({ name: a.name ?? a.action, credits: a.credits ?? 0 }))
+      : [];
+    normd.push({ label: p.label, total: p.total_credits ?? 0, slices });
+  }
+
+  const names = new Set();
+  normd.forEach((p) => p.slices.forEach((s) => names.add(s.name)));
+  const sorted = [...names].filter((n) => n !== OTHER_SLICE).sort();
+  const colors = {};
+  sorted.forEach((n, i) => {
+    colors[n] = CHART_PALETTE[i % CHART_PALETTE.length];
+  });
+  colors[OTHER_SLICE] = OTHER_SLICE_COLOR;
+
+  const filler = sorted[0] ?? OTHER_SLICE;
+  const rows = [];
+  normd.forEach((p) => {
+    if (p.slices.length === 0) {
+      rows.push({ period: p.label, feature: filler, credits: 0 });
+    } else {
+      p.slices.forEach((s) =>
+        rows.push({ period: p.label, feature: s.name, credits: s.credits })
+      );
+    }
+  });
+
+  const caption = normd
+    .map((p) => `${p.label}: ${p.total} ${p.total === 1 ? "credit" : "credits"}`)
+    .join(" · ");
+  return { rows, colors, labels: normd.map((p) => p.label), caption };
+}
+
 // Resolve the period_comparison block (null until the install has one full
-// closed period) into render-ready shape:
-//   { last, current, maxTotal } where each period is
-//   { label, total, byAction: [{ action, credits }] } and maxTotal is the
-//   shared bar denominator (so the two bars are visually comparable; >= 1 so
-//   a pair of zero periods never divides by zero).
-// Returns null when the block or either period is missing.
+// closed period) into render-ready shape. Discriminated on `kind`:
+//   { kind: "periods", chart, last, current, maxTotal } — the backend shipped
+//     the additive `periods` chart payload; render the stacked BarChart.
+//   { kind: "legacy", last, current, maxTotal } — pre-periods backend; render
+//     the two-column progress-bar layout.
+// `last` / `current` are { label, total, byAction: [{ action, credits }] }
+// and maxTotal the shared bar denominator (>= 1 so a pair of zero periods
+// never divides by zero). Returns null when the block or either legacy period
+// is missing.
 export function resolvePeriodComparison(periodComparison) {
   if (!periodComparison || typeof periodComparison !== "object") return null;
   const norm = (p) => {
@@ -92,11 +160,14 @@ export function resolvePeriodComparison(periodComparison) {
   const last = norm(periodComparison.last_period);
   const current = norm(periodComparison.current_period);
   if (!last || !current) return null;
-  return {
+  const base = {
     last,
     current,
     maxTotal: Math.max(last.total, current.total, 1),
   };
+  const chart = resolvePeriodsChart(periodComparison.periods);
+  if (!chart) return { kind: "legacy", ...base };
+  return { kind: "periods", chart, ...base };
 }
 
 // Same nested-vs-top-level duality as planFitOf: base serves