@growth-operations/ui-shared 1.26.2 → 1.28.0

package/package.json

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

package/src/home/FeatureUsage.jsx

@@ -61,16 +61,19 @@ function RecommendedTile({ notInUse, isSuperAdmin, onNavigate }) {
       <Flex direction="column" gap="small">
         <Text format={{ fontWeight: "bold" }}>Recommended to explore</Text>
         {picks.map((f) => {
-          // Setup CTAs point at admin-only surfaces (the layout editor above
-          // all) — show them to super admins only; everyone else gets name +
-          // rationale alone (a non-admin clicking into a HubSpot permission
-          // wall is worse than no link).
+          // Setup CTAs are gated PER ITEM (1.28.0): adminOnly items point at
+          // HubSpot permission-wall surfaces (the layout editor above all) —
+          // super admins only, since a non-admin clicking into a permission
+          // wall is worse than no link. Items marked adminOnly: false are
+          // per-user surfaces (install the Chrome extension, open the in-app
+          // extension page) and render for everyone. Old backends emit no
+          // marker → adminOnly defaults true → the blanket gate is preserved.
           //
           // "Learn more →" (docs_url) intentionally NOT rendered (Jasper
           // 2026-10-14): every feature's docs_url points at the same single
           // setup guide — noise until per-feature articles exist. docs_url
           // stays in the wire contract; re-enabling is a one-line revert.
-          const ctas = isSuperAdmin ? f.ctas : [];
+          const ctas = f.ctas.filter((c) => !c.adminOnly || isSuperAdmin);
           return (
             <Flex key={f.key} direction="column" gap="extra-small">
               <Text format={{ fontWeight: "demibold" }}>{f.name}</Text>

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/featureUsage.js

@@ -18,13 +18,17 @@ const normalizeUnit = (u) =>
 // One well-formed setup CTA is {label: non-empty string, url XOR route:
 // non-empty string}. Anything else (missing label, both targets, neither
 // target, wrong types) is dropped — a malformed item never renders.
+// admin_only (1.28.0): an explicit false marks a per-user surface (installing
+// the Chrome extension) that renders for EVERYONE; a missing marker means
+// admin-only, so old backends keep the blanket super-admin gate.
 const normalizeCta = (c) => {
   if (!c || typeof c !== "object") return null;
   const label = typeof c.label === "string" && c.label ? c.label : null;
   const url = typeof c.url === "string" && c.url ? c.url : null;
   const route = typeof c.route === "string" && c.route ? c.route : null;
   if (!label || !(url || route) || (url && route)) return null;
-  return url ? { label, url } : { label, route };
+  const adminOnly = c.admin_only !== false;
+  return { label, ...(url ? { url } : { route }), adminOnly };
 };
 
 // Resolve the feature_usage block into render-ready shape:

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