@growth-operations/ui-shared 1.33.0 → 1.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-operations/ui-shared",
-  "version": "1.33.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,17 @@ 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";
+
 // Forms — shared HubSpot-options dropdown (forms/lists/pipeline-stages picker).
 export { OptionSelect } from "./forms/OptionSelect";
 

package/src/support/SupportTab.jsx

@@ -0,0 +1,198 @@
+// SupportTab — the shared in-app support request form.
+//
+// Renders a native Form mirroring the "Growth Ops Apps - Support Form" on the
+// website (First name*, Last name*, Email*, "What can we help you with
+// today?"*, optional screenshot) and POSTs it to the app's own support route
+// (common.support), which forwards it into the real form via the Forms API.
+// Name/email prefill from the signed-in HubSpot user and stay editable.
+//
+// Props:
+//   context     — the HubSpot extension context (user prefill, portal.id,
+//                 variables.BASE_URL).
+//   supportPath — the app's support route path, e.g.
+//                 "/v1/hubspot/app_pages/<app_key>/support" (base-hosted) or
+//                 "/api/v1/support" (self-hosted).
+//   appName     — display name, used in headings/success copy.
+//   supportUrl  — external support link shown as a fallback on error.
+import React, { useState } from "react";
+import {
+  Alert,
+  Button,
+  Divider,
+  Flex,
+  Form,
+  Heading,
+  Input,
+  Link,
+  Text,
+  TextArea,
+} from "@hubspot/ui-extensions";
+import { FileInput } from "@hubspot/ui-extensions/experimental";
+
+import { callAppApi } from "../sdk/app/base";
+import {
+  buildSupportBody,
+  readFileAsBase64,
+  unwrapFileEvent,
+  validateSupportFields,
+} from "./supportLogic";
+
+export function SupportTab({ context, supportPath, appName = "the app", supportUrl }) {
+  const [fields, setFields] = useState({
+    firstname: context.user?.firstName ?? "",
+    lastname: context.user?.lastName ?? "",
+    email: context.user?.email ?? "",
+    content: "",
+  });
+  const [file, setFile] = useState(null); // { name, contentBase64 }
+  const [submitting, setSubmitting] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
+  const [error, setError] = useState(null);
+
+  const set = (key) => (value) =>
+    setFields((prev) => ({ ...prev, [key]: value }));
+
+  const handleFileChange = async (event) => {
+    const picked = unwrapFileEvent(event);
+    if (!picked) return;
+    try {
+      const contentBase64 = await readFileAsBase64(picked);
+      setFile({ name: picked.name, contentBase64 });
+    } catch {
+      setError("Couldn't read that file — try a different one.");
+    }
+  };
+
+  const handleSubmit = async () => {
+    const validationError = validateSupportFields(fields);
+    if (validationError) {
+      setError(validationError);
+      return;
+    }
+    setSubmitting(true);
+    setError(null);
+    try {
+      await callAppApi(
+        context,
+        `${supportPath}?portalId=${context.portal.id}`,
+        "POST",
+        buildSupportBody(fields, file)
+      );
+      setSubmitted(true);
+    } catch (err) {
+      setError(
+        err?.message ||
+          "Something went wrong sending your request. Please try again."
+      );
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  if (submitted) {
+    return (
+      <Flex direction="column" gap="medium">
+        <Alert title="Request received" variant="success">
+          <Text>
+            Thanks — we've received your request and will be in touch soon
+            (typical response time is under 1–2 hours). You can reply to the
+            confirmation email with anything else.
+          </Text>
+        </Alert>
+        <Button
+          onClick={() => {
+            setSubmitted(false);
+            setFields((prev) => ({ ...prev, content: "" }));
+            setFile(null);
+          }}
+        >
+          Submit another request
+        </Button>
+      </Flex>
+    );
+  }
+
+  return (
+    <Flex direction="column" gap="medium">
+      <Flex direction="column" gap="small">
+        <Heading>Contact {appName} support</Heading>
+        <Text>
+          Send us a message and we'll get back to you. For urgent issues you
+          can also{" "}
+          {supportUrl ? (
+            <Link href={{ url: supportUrl, external: true }}>
+              use our contact page
+            </Link>
+          ) : (
+            "use our contact page"
+          )}
+          .
+        </Text>
+      </Flex>
+      <Divider />
+      {error && (
+        <Alert title="Couldn't send your request" variant="error">
+          <Text>{error}</Text>
+          {supportUrl ? (
+            <Text>
+              You can also reach us via{" "}
+              <Link href={{ url: supportUrl, external: true }}>
+                our contact page
+              </Link>
+              .
+            </Text>
+          ) : null}
+        </Alert>
+      )}
+      <Form onSubmit={handleSubmit}>
+        <Flex direction="column" gap="medium">
+          <Input
+            label="First name"
+            name="firstname"
+            required={true}
+            value={fields.firstname}
+            onChange={set("firstname")}
+          />
+          <Input
+            label="Last name"
+            name="lastname"
+            required={true}
+            value={fields.lastname}
+            onChange={set("lastname")}
+          />
+          <Input
+            label="Email"
+            name="email"
+            required={true}
+            value={fields.email}
+            onChange={set("email")}
+          />
+          <TextArea
+            label="What can we help you with today?"
+            name="content"
+            required={true}
+            value={fields.content}
+            onChange={set("content")}
+          />
+          <Flex direction="column" gap="extra-small">
+            <Text format={{ fontWeight: "bold" }}>Screenshot (optional)</Text>
+            <FileInput name="file" value={null} onChange={handleFileChange} />
+            {file && (
+              <Flex direction="row" gap="small" align="center">
+                <Text>Attached: {file.name}</Text>
+                <Button variant="secondary" size="xs" onClick={() => setFile(null)}>
+                  Remove
+                </Button>
+              </Flex>
+            )}
+          </Flex>
+          <Button variant="primary" type="submit" disabled={submitting}>
+            {submitting ? "Sending…" : "Send"}
+          </Button>
+        </Flex>
+      </Form>
+    </Flex>
+  );
+}
+
+export default SupportTab;

package/src/support/supportLogic.js

@@ -0,0 +1,50 @@
+// supportLogic — pure helpers for SupportTab, kept separate so the validation
+// and payload shaping are unit-testable without rendering (see
+// tests/supportTab.test.js).
+
+// Mirrors common.support's contract: contact fields + the ticket `content`,
+// optional file as base64 (hubspot.fetch carries JSON only, no multipart).
+export function validateSupportFields({ firstname, lastname, email, content }) {
+  if (!firstname?.trim()) return "First name is required.";
+  if (!lastname?.trim()) return "Last name is required.";
+  const e = email?.trim() ?? "";
+  if (!e || !e.includes("@") || e.startsWith("@") || e.endsWith("@")) {
+    return "A valid email is required.";
+  }
+  if (!content?.trim()) return "Tell us what we can help with.";
+  return null;
+}
+
+// Body for POST {supportPath}?portalId=N — plain object (callAppApi
+// serializes; NEVER pre-stringify for hubspot.fetch).
+export function buildSupportBody({ firstname, lastname, email, content }, file) {
+  const body = {
+    firstname: firstname.trim(),
+    lastname: lastname.trim(),
+    email: email.trim(),
+    content: content.trim(),
+  };
+  if (file) {
+    body.file = { filename: file.name, contentBase64: file.contentBase64 };
+  }
+  return body;
+}
+
+// FileInput (@hubspot/ui-extensions/experimental) has an ambiguous event
+// shape per HubSpot's own types (`any`) — defensively unwrap to a real File.
+// Same empirically-verified pattern as ATS AddCandidate's resume picker.
+export function unwrapFileEvent(event) {
+  const file = event?.target?.files?.[0] || event;
+  return file instanceof File ? file : null;
+}
+
+// FileReader → raw base64 (strips the "data:<mime>;base64," prefix).
+export function readFileAsBase64(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result).split(",")[1] || "");
+    reader.onerror = () =>
+      reject(reader.error || new Error("Failed to read file"));
+    reader.readAsDataURL(file);
+  });
+}