@growth-operations/ui-shared 1.28.0 → 1.30.0

package/package.json

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

package/src/home/FeatureUsage.jsx

@@ -61,19 +61,25 @@ function RecommendedTile({ notInUse, isSuperAdmin, onNavigate }) {
       <Flex direction="column" gap="small">
         <Text format={{ fontWeight: "bold" }}>Recommended to explore</Text>
         {picks.map((f) => {
-          // 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.
+          // Setup CTAs render for EVERYONE (1.29.0, Jasper 2026-10-14: "why
+          // gate so much on super admin?"). The old blanket super-admin gate
+          // assumed the targets were admin-only surfaces — but HubSpot
+          // permissions are granular (CRM customization ≠ super admin), and
+          // hiding the CTA kept non-admins from even knowing what to ask
+          // their admin for. adminOnly items instead carry a "(Super Admin)"
+          // hint for non-admin viewers, so the permission wall is never a
+          // blind click. The adminOnly marker still distinguishes the two
+          // surface kinds; old backends emit no marker → every item gets the
+          // hint for non-admins (conservative, and matches the old gate's
+          // assumption that the targets are admin surfaces).
           //
           // "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 = f.ctas.filter((c) => !c.adminOnly || isSuperAdmin);
+          const ctas = f.ctas;
+          const hint = (c) =>
+            c.adminOnly && !isSuperAdmin ? " (Super Admin)" : "";
           return (
             <Flex key={f.key} direction="column" gap="extra-small">
               <Text format={{ fontWeight: "demibold" }}>{f.name}</Text>
@@ -81,7 +87,8 @@ function RecommendedTile({ notInUse, isSuperAdmin, onNavigate }) {
               {ctas.map((cta) =>
                 cta.url ? (
                   <Link key={cta.label} href={{ url: cta.url, external: true }}>
-                    {cta.label} →
+                    {cta.label}
+                    {hint(cta)} →
                   </Link>
                 ) : onNavigate ? (
                   <Button
@@ -90,6 +97,7 @@ function RecommendedTile({ notInUse, isSuperAdmin, onNavigate }) {
                     onClick={() => onNavigate(cta.route)}
                   >
                     {cta.label}
+                    {hint(cta)}
                   </Button>
                 ) : null
               )}

package/src/index.js

@@ -28,8 +28,17 @@ export { AutoProvisionToggle } from "./billing/AutoProvisionToggle";
 // Alerts — the shared customer alerts table (level filter, sort, dismiss).
 export { AlertsTab } from "./alerts/AlertsTab";
 
-// Usage — the shared credit usage view (per-day LineChart + window stats).
+// Usage — the shared credit usage view (per-day LineChart + window stats, or
+// the billing-period stacked BarChart via UsageTab chart="billingPeriods").
 export { UsageTab } from "./usage/UsageTab";
+export {
+  BillingPeriodUsage,
+  BillingPeriodUsageView,
+  BILLING_PERIOD_OPTIONS,
+  makeUsageFetcher,
+  usageUrl,
+  usedWindowLabel,
+} from "./usage/BillingPeriodUsage";
 
 // Sandbox — the shared "Install on a sandbox" action (mints a signed link).
 export { SandboxInstall } from "./sandbox/SandboxInstall";

package/src/usage/BillingPeriodUsage.jsx

@@ -0,0 +1,220 @@
+// BillingPeriodUsage — usage-over-time chart bucketed by BILLING PERIOD.
+//
+// The billing-period alternative to UsageTab's rolling-days LineChart
+// (Jasper 2026-10-14: the internal Installation card went billing-period —
+// "Current / Last 2 / Last 3 / Last 6 / Last 12" — and the customer Usage
+// tab converts to the exact same style; one shared component serves both).
+// One stacked BarChart, one bar per billing period (backend-supplied label,
+// e.g. "Oct 12 – Nov 12"), stacks = features, with the lookback Select in
+// the heading row.
+//
+// Backend contract: GET {base}{basePath}?portalId=<id>&periods=<N> →
+//   { series: [{ period: "Oct 12 – Nov 12", feature: "Fit Scores", credits: 3 }],
+//     used_in_window: <int>, granted: <int|null>, remaining: <int|null> }
+// `series` is sparse (no zero-filled bars); window math lives in common's
+// billing_period_windows + CreditService.usage_series_by_period.
+//
+// fetchUsage override: non-standard hosts (the GOAA internal card, whose
+// endpoint is keyed by installation id, not portalId) pass their own
+// (periods) => Promise<{series, ...}>; the default hits the standard
+// basePath/portalId URL via hubspot.fetch.
+import React, { useState } from "react";
+import {
+  hubspot,
+  Alert,
+  BarChart,
+  Box,
+  EmptyState,
+  Flex,
+  Heading,
+  LoadingSpinner,
+  Select,
+  Statistics,
+  StatisticsItem,
+  Text,
+  Tile,
+} from "@hubspot/ui-extensions";
+
+import { useStrictModeEffect } from "../lib/useStrictModeEffect";
+
+const DEFAULT_BASE_PATH = "/api/v1/usage";
+
+// The dropdown is billing-period scoped, not day scoped: "Current" = just
+// the in-flight period; "Last N" = N periods ending with the current one.
+export const BILLING_PERIOD_OPTIONS = [
+  { label: "Current", value: "1" },
+  { label: "Last 2", value: "2" },
+  { label: "Last 3", value: "3" },
+  { label: "Last 6", value: "6" },
+  { label: "Last 12", value: "12" },
+];
+
+export function usedWindowLabel(periodsValue) {
+  return periodsValue === "1"
+    ? "Used (current billing period)"
+    : `Used (last ${periodsValue} billing periods)`;
+}
+
+export function usageUrl({ baseUrl = "", basePath, portalId, periods }) {
+  return `${baseUrl}${basePath}?portalId=${portalId}&periods=${periods}`;
+}
+
+// The standard fetcher: the app's own usage endpoint with a periods param.
+// Exported so hosts with the standard URL shape but custom fetch needs (auth
+// headers, etc.) can wrap it.
+export function makeUsageFetcher({ context, basePath = DEFAULT_BASE_PATH, portalId }) {
+  return async (periods) => {
+    const base = context.variables?.BASE_URL ?? "";
+    const pid = portalId ?? context.portal.id;
+    const res = await hubspot.fetch(usageUrl({ baseUrl: base, basePath, portalId: pid, periods }), {
+      method: "GET",
+      timeout: 15000,
+    });
+    return res.json();
+  };
+}
+
+// Hook-free presentational core (exported for tests): stats + stacked chart
+// from an already-loaded payload.
+export function BillingPeriodUsageView({ data, periods, appName, showStats }) {
+  const series = data?.series ?? [];
+  const usedInWindow = data?.used_in_window ?? 0;
+  const remaining = data?.remaining;
+  const granted = data?.granted;
+  const hasBalance = remaining != null && granted != null;
+
+  return (
+    <Flex direction="column" gap="medium">
+      {showStats && (
+        <Tile>
+          <Statistics>
+            <StatisticsItem label={usedWindowLabel(periods)} number={usedInWindow} />
+            {hasBalance && <StatisticsItem label="Remaining" number={remaining} />}
+            {hasBalance && <StatisticsItem label="Granted" number={granted} />}
+          </Statistics>
+        </Tile>
+      )}
+
+      {series.length === 0 ? (
+        <EmptyState title="No usage in this window" layout="vertical">
+          <Text>
+            Once you run a metered {appName} action, your credit usage shows
+            here by billing period. Try a longer lookback.
+          </Text>
+        </EmptyState>
+      ) : (
+        <Tile>
+          <Flex direction="column" gap="small">
+            <Text format={{ fontWeight: "bold" }}>Credits used per billing period</Text>
+            <BarChart
+              data={series}
+              axes={{
+                x: { field: "period", fieldType: "category", label: "Billing period" },
+                y: { field: "credits", fieldType: "linear", label: "Credits" },
+                // Category axes render in DATA order (ui-extensions docs), so
+                // the backend's oldest-first series gives chronological bars.
+                options: { groupFieldByColor: "feature", stacking: true },
+              }}
+              options={{ showLegend: true, showTooltips: true }}
+            />
+          </Flex>
+        </Tile>
+      )}
+    </Flex>
+  );
+}
+
+export function BillingPeriodUsage({
+  context,
+  basePath = DEFAULT_BASE_PATH,
+  portalId,
+  fetchUsage,
+  appName = "this app",
+  title = "Usage",
+  titleAs = "heading", // "text" for CRM-card contexts (bold Text, not Heading)
+  showStats = true,
+}) {
+  const [periods, setPeriods] = useState("1");
+  const fetcher = fetchUsage ?? makeUsageFetcher({ context, basePath, portalId });
+
+  return (
+    <Flex direction="column" gap="medium">
+      <Flex direction="row" justify="between" align="end">
+        {titleAs === "heading" ? (
+          <Heading>{title}</Heading>
+        ) : (
+          <Text format={{ fontWeight: "bold" }}>{title}</Text>
+        )}
+        <Select
+          label="Billing period"
+          name="billing-period"
+          options={BILLING_PERIOD_OPTIONS}
+          value={periods}
+          onChange={setPeriods}
+        />
+      </Flex>
+
+      {/* key={periods}: a lookback change must hard-remount everything below
+          the Select, not just re-render with new props. BarChart is a HubSpot
+          "remote component" (rendered outside this iframe via HubSpot's own
+          bridge) — a prop/data change alone was confirmed NOT to update the
+          rendered chart (the UsageTab LineChart lesson). The Select stays
+          OUTSIDE this key boundary so the control triggering the change is
+          never torn down mid-interaction. */}
+      <BillingPeriodContent
+        key={periods}
+        periods={periods}
+        fetchUsage={fetcher}
+        appName={appName}
+        showStats={showStats}
+      />
+    </Flex>
+  );
+}
+
+function BillingPeriodContent({ periods, fetchUsage, appName, showStats }) {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useStrictModeEffect(
+    async ({ mounted }) => {
+      setLoading(true);
+      try {
+        const res = await fetchUsage(periods);
+        if (mounted.current) {
+          setData(res);
+          setError(null);
+        }
+      } catch (err) {
+        if (mounted.current) setError(String(err));
+      } finally {
+        if (mounted.current) setLoading(false);
+      }
+    },
+    [periods, fetchUsage]
+  );
+
+  if (loading) return <LoadingSpinner showLabel label="Loading usage…" />;
+
+  if (error) {
+    return (
+      <Alert title="Couldn't load usage" variant="warning">
+        <Box flex="auto">
+          <Text>{error}</Text>
+        </Box>
+      </Alert>
+    );
+  }
+
+  return (
+    <BillingPeriodUsageView
+      data={data}
+      periods={periods}
+      appName={appName}
+      showStats={showStats}
+    />
+  );
+}
+
+export default BillingPeriodUsage;

package/src/usage/UsageTab.jsx

@@ -30,6 +30,7 @@ import {
 import { useStrictModeEffect } from "../lib/useStrictModeEffect";
 import { creditsBlockOf } from "../lib/creditDisplay";
 import { CreditMeter } from "../home/CreditMeter";
+import { BillingPeriodUsage } from "./BillingPeriodUsage";
 
 const DEFAULT_BASE_PATH = "/api/v1/usage";
 
@@ -45,13 +46,16 @@ const WINDOW_OPTIONS = [
 // (base-hosted apps pass both). appName: chart copy. state: the /v1/home
 // payload (optional) — when present, the credit meter renders at the TOP of
 // the tab (Andrew's 2026-10 feedback: the meter moved off Home); without it
-// the tab is chart-only, same as before.
+// the tab is chart-only, same as before. chart: "days" (default, rolling-day
+// LineChart) or "billingPeriods" (stacked BarChart bucketed by billing period
+// — requires the backend's ?periods= mode, shipped in common v1.35.0).
 export function UsageTab({
   context,
   basePath = DEFAULT_BASE_PATH,
   portalId,
   appName = "this app",
   state = null,
+  chart = "days",
 }) {
   const [days, setDays] = useState("30");
 
@@ -68,6 +72,31 @@ export function UsageTab({
         />
       )}
 
+      {chart === "billingPeriods" ? (
+        <BillingPeriodUsage
+          context={context}
+          basePath={basePath}
+          portalId={portalId}
+          appName={appName}
+          title="Usage"
+        />
+      ) : (
+        <DaysUsage
+          days={days}
+          onDaysChange={setDays}
+          context={context}
+          basePath={basePath}
+          portalId={portalId}
+          appName={appName}
+        />
+      )}
+    </Flex>
+  );
+}
+
+function DaysUsage({ days, onDaysChange, context, basePath, portalId, appName }) {
+  return (
+    <>
       <Flex direction="row" justify="between" align="end">
         <Heading>Usage</Heading>
         <Select
@@ -75,7 +104,7 @@ export function UsageTab({
           name="time-period"
           options={WINDOW_OPTIONS}
           value={days}
-          onChange={setDays}
+          onChange={onDaysChange}
         />
       </Flex>
 
@@ -95,7 +124,7 @@ export function UsageTab({
         appName={appName}
         days={days}
       />
-    </Flex>
+    </>
   );
 }