@growth-operations/ui-shared 1.34.0 → 1.35.0

package/package.json

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

package/src/billing/SubscriptionGate.jsx

@@ -1,4 +1,4 @@
-import React, { useState } from "react";
+import React, { useEffect, useReducer, useState } from "react";
 import {
   Alert,
   Box,
@@ -6,10 +6,12 @@ import {
   Link,
   LoadingSpinner,
   Text,
+  logger,
 } from "@hubspot/ui-extensions";
 
 import { useStrictModeEffect } from "../lib/useStrictModeEffect";
 import { callAppApi } from "../sdk/app/base";
+import { contextReadiness } from "../context/readiness";
 
 // Full-surface "no active subscription" gate for CRM cards (and any other
 // extension surface that should hard-block a canceled install).
@@ -38,15 +40,31 @@ import { callAppApi } from "../sdk/app/base";
 //   the card's existing error handling, since the gated endpoints 402 with the
 //   same { detail, code: "subscription_canceled", billing_url } body.
 //
+// Children also wait for the extension IDENTIFIER context to hydrate
+// (2026.03 runtime race — see context/readiness.js): at first render
+// context.extension.appId is the placeholder string "Identifier context is
+// not found", so CRM hooks subscribing immediately send garbage property
+// names and can wedge in isLoading forever when the corrected re-subscription's
+// delivery is dropped (the "spinner until the user switches browser tabs"
+// freeze). The entitlement check above doesn't need the identifier context
+// (portal.id only), so it starts immediately and runs in parallel; only the
+// children render is held, polled at 4Hz (the hydration re-render trigger is
+// platform-internal), with a bounded 8s fallback that renders children anyway
+// rather than spinning forever if hydration never comes.
+//
 // Props:
 //   context   — the hubspot.extend context (portal.id, app.id, variables).
 //   checkPath — backend entitlement-check path; default "/v1/entitlement".
 //   appName   — display name for the copy, e.g. "Applicant Tracking System".
+//   requiredVariables — context.variables keys the child tree's hooks depend
+//               on (e.g. ATS's ["APPLICATION_OBJECT_TYPE_ID"]); the context
+//               gate waits for these too.
 export function SubscriptionGate({
   context,
   children,
   checkPath = "/v1/entitlement",
   appName = "this app",
+  requiredVariables = [],
 }) {
   // null = still loading; { entitled, status, billing_url } once resolved.
   const [check, setCheck] = useState(null);
@@ -67,6 +85,32 @@ export function SubscriptionGate({
     [context, checkPath]
   );
 
+  const { ready: contextReady, missing: contextMissing } = contextReadiness(
+    context,
+    requiredVariables
+  );
+  const contextMissingKey = contextMissing.join(", ");
+  const [contextTimedOut, setContextTimedOut] = useState(false);
+  const [, forcePoll] = useReducer((x) => x + 1, 0);
+
+  useEffect(() => {
+    if (contextReady || contextTimedOut) return;
+    const poll = setInterval(forcePoll, 250);
+    const timeout = setTimeout(() => {
+      logger.error(
+        `[SubscriptionGate] Extension context never hydrated (missing: ${contextMissingKey}) — rendering children anyway`
+      );
+      setContextTimedOut(true);
+    }, 8000);
+    return () => {
+      clearInterval(poll);
+      clearTimeout(timeout);
+    };
+  }, [contextReady, contextTimedOut, contextMissingKey]);
+
+  if (!contextReady && !contextTimedOut) {
+    return <LoadingSpinner label="Loading…" showLabel />;
+  }
   if (failedOpen) return children;
   if (!check) {
     return <LoadingSpinner label="Checking subscription…" showLabel />;

package/src/context/readiness.js

@@ -0,0 +1,33 @@
+// Extension identifier-context readiness (pure helpers).
+//
+// Platform race (HubSpot 2026.03 runtime, verified live 2026-10-22 on the ATS
+// demo portal): context.extension.appId is NOT usable at first render — it
+// evaluates to the placeholder string "Identifier context is not found", so
+// every `a${context.extension.appId}_*` property name composed during that
+// window is garbage until the identifier context hydrates a beat later. CRM
+// hooks (useCrmProperties / useAssociations) that subscribe in that window
+// send a first resolveData wave with garbage names, then re-subscribe with
+// correct ones; when the runtime drops that second delivery into the iframe,
+// the hook wedges in isLoading forever — the card "loads instantly" only
+// after the user switches browser tabs (HubSpot re-resolves the record on
+// window focus). SubscriptionGate uses these to hold children until hooks
+// can subscribe with correct names on the FIRST try.
+
+export const isUsableAppId = (appId) =>
+  appId != null && /^\d+$/.test(String(appId));
+
+// What (if anything) is still missing before hooks may subscribe.
+// requiredVariables names context.variables keys the tree's hooks depend on
+// (e.g. ATS's APPLICATION_OBJECT_TYPE_ID).
+export const contextReadiness = (context, requiredVariables = []) => {
+  const missing = [];
+  if (!isUsableAppId(context?.extension?.appId)) {
+    missing.push("extension.appId");
+  }
+  for (const name of requiredVariables) {
+    if (!context?.variables?.[name]) {
+      missing.push(`variables.${name}`);
+    }
+  }
+  return { ready: missing.length === 0, missing };
+};

package/src/index.js

@@ -43,6 +43,13 @@ export {
 // Sandbox — the shared "Install on a sandbox" action (mints a signed link).
 export { SandboxInstall } from "./sandbox/SandboxInstall";
 
+// Platform — extension identifier-context readiness (2026.03 runtime:
+// context.extension.appId is a placeholder string at first render; hooks that
+// subscribe in that window can wedge isLoading forever). SubscriptionGate
+// holds children on this internally; the pure helpers are exported for
+// surfaces that gate without SubscriptionGate. See src/context/readiness.js.
+export { contextReadiness, isUsableAppId } from "./context/readiness";
+
 // Support — the shared in-app support request form (posts to the app's
 // support route; see common.support).
 export { SupportTab } from "./support/SupportTab";