@growth-operations/ui-shared 1.22.0 → 1.24.0

package/package.json

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

package/src/home/AppHome.jsx

@@ -159,7 +159,7 @@ export function AppHome({ state, onNavigate, appName, onRetry, helpfulLinks }) {
           on the non-billing setup steps (NOT the paid-gated plan step) so a
           fresh install sees setup first but free/trial installs aren't
           locked out. */}
-      {setupStepsComplete && <FeatureUsage state={state} />}
+      {setupStepsComplete && <FeatureUsage state={state} onNavigate={onNavigate} />}
 
       <FeatureNudges nudges={state.nudges} onNavigate={onNavigate} />
 

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 { Flex, Tile, Text, Link, Button } from "@hubspot/ui-extensions";
+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
@@ -42,35 +46,68 @@ function MostUsedTile({ mostUsed }) {
   );
 }
 
-function RecommendedTile({ notInUse }) {
+function RecommendedTile({ notInUse, isSuperAdmin, onNavigate }) {
   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) => (
-          <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>
-        ))}
+        {picks.map((f) => {
+          // Setup CTAs point at admin-only surfaces (the layout editor above
+          // all) — show them to super admins only; everyone else keeps the
+          // docs link (a non-admin clicking into a HubSpot permission wall is
+          // worse than no link).
+          const showCta = isSuperAdmin && f.ctaLabel && (f.ctaUrl || f.ctaRoute);
+          return (
+            <Flex key={f.key} direction="column" gap="extra-small">
+              <Text format={{ fontWeight: "demibold" }}>{f.name}</Text>
+              {f.rationale ? <Text>{f.rationale}</Text> : null}
+              {showCta && f.ctaUrl ? (
+                <Link href={{ url: f.ctaUrl, external: true }}>
+                  {f.ctaLabel} →
+                </Link>
+              ) : null}
+              {showCta && !f.ctaUrl && f.ctaRoute && onNavigate ? (
+                <Button variant="secondary" onClick={() => onNavigate(f.ctaRoute)}>
+                  {f.ctaLabel}
+                </Button>
+              ) : null}
+              {f.docsUrl ? (
+                <Link href={{ url: f.docsUrl, external: true }}>
+                  Learn more →
+                </Link>
+              ) : null}
+            </Flex>
+          );
+        })}
+        {recommendationsRotated(notInUse) ? (
+          <Text variant="microcopy">
+            New picks daily — {notInUse.length} features to explore in all.
+          </Text>
+        ) : null}
       </Flex>
     </Tile>
   );
 }
 
-export function FeatureUsage({ state }) {
+export function FeatureUsage({ state, onNavigate }) {
   const view = featureUsageOf(state);
   if (!view) return null;
   return (
     <>
       <MostUsedTile mostUsed={view.mostUsed} />
-      <RecommendedTile notInUse={view.notInUse} />
+      <RecommendedTile
+        notInUse={view.notInUse}
+        isSuperAdmin={state?.user?.is_super_admin === true}
+        onNavigate={onNavigate}
+      />
     </>
   );
 }

package/src/index.js

@@ -50,7 +50,12 @@ export {
   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,

package/src/lib/featureUsage.js

@@ -39,6 +39,12 @@ export function resolveFeatureUsage(featureUsage) {
       name: f.name,
       docsUrl: typeof f.docs_url === "string" && f.docs_url ? f.docs_url : null,
       rationale: typeof f.rationale === "string" ? f.rationale : "",
+      // Optional SETUP action (the same cta_* vocabulary as nudges): the "go
+      // do the thing" deep link for an unused feature — layout editor, store
+      // listing, or in-app route. Absent on backends that predate it.
+      ctaLabel: typeof f.cta_label === "string" && f.cta_label ? f.cta_label : null,
+      ctaUrl: typeof f.cta_url === "string" && f.cta_url ? f.cta_url : null,
+      ctaRoute: typeof f.cta_route === "string" && f.cta_route ? f.cta_route : null,
     }));
 
   if (mostUsed.length === 0 && notInUse.length === 0) return null;
@@ -52,3 +58,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;
+}