bsmnt 0.6.4 → 0.7.1

package/src/modules/features/forms/hubspot/files/_sanity-adapter/form-select-input.tsx

@@ -0,0 +1,169 @@
+"use client"
+
+import {
+  Autocomplete,
+  Box,
+  Button,
+  Card,
+  Flex,
+  Spinner,
+  Stack,
+  Text,
+} from "@sanity/ui"
+import { useCallback, useMemo, useRef, useState } from "react"
+import { PatchEvent, type StringInputProps, set, unset } from "sanity"
+import {
+  decodeHubSpotFormSelection,
+  getHubSpotFormSelectionLabel,
+} from "../form-selection"
+import { getHubSpotFormOptions, type HubSpotFormOption } from "../forms"
+
+type LoadStatus = "idle" | "loading" | "loaded" | "error"
+
+function HubSpotFormOptionPreview({ option }: { option: HubSpotFormOption }) {
+  const form = decodeHubSpotFormSelection(option.value)
+
+  return (
+    <Card padding={3} style={{ cursor: "pointer" }}>
+      <Stack space={2}>
+        <Text size={1} weight="medium">
+          {form?.name ?? option.label}
+        </Text>
+        {form ? (
+          <Text muted size={1}>
+            {form.formId}
+            {option.renderRawHtml === false ? " · iframe embed" : ""}
+          </Text>
+        ) : null}
+      </Stack>
+    </Card>
+  )
+}
+
+/**
+ * Sanity Studio input that lazy-loads the connected portal's HubSpot forms and
+ * stores the chosen one as a single encoded string (see `hubspotFormField`).
+ */
+export function HubSpotFormSelectInput(props: StringInputProps) {
+  const { value, onChange, readOnly, elementProps } = props
+  const { onChange: _ignoreElementOnChange, ...autocompleteElementProps } =
+    elementProps
+
+  const [forms, setForms] = useState<HubSpotFormOption[]>([])
+  const [status, setStatus] = useState<LoadStatus>("idle")
+  const [error, setError] = useState<string | null>(null)
+  const statusRef = useRef<LoadStatus>("idle")
+
+  const selectedForm = useMemo(() => decodeHubSpotFormSelection(value), [value])
+  const isLoading = status === "loading"
+
+  const loadForms = useCallback(async () => {
+    if (statusRef.current === "loading") return
+    statusRef.current = "loading"
+    setStatus("loading")
+    setError(null)
+
+    try {
+      const result = await getHubSpotFormOptions()
+      setForms(result.forms)
+      setError(result.error ?? null)
+      const next: LoadStatus = result.error ? "error" : "loaded"
+      statusRef.current = next
+      setStatus(next)
+    } catch (err) {
+      const message =
+        err instanceof Error ? err.message : "Unable to load forms."
+      setError(message)
+      statusRef.current = "error"
+      setStatus("error")
+    }
+  }, [])
+
+  const loadFormsOnce = useCallback(() => {
+    if (statusRef.current === "idle") void loadForms()
+  }, [loadForms])
+
+  // Keep the already-selected form visible while options are still loading.
+  const options =
+    selectedForm && !forms.some((form) => form.value === value)
+      ? [
+          {
+            label: getHubSpotFormSelectionLabel(selectedForm),
+            value: value as string,
+            renderRawHtml: null,
+          },
+          ...forms,
+        ]
+      : forms
+
+  return (
+    <Stack space={3}>
+      <Flex gap={2} align="center">
+        <Box flex={1}>
+          <Autocomplete
+            {...autocompleteElementProps}
+            disabled={readOnly || isLoading}
+            filterOption={(query, option) =>
+              option.label.toLowerCase().includes(query.toLowerCase())
+            }
+            loading={isLoading}
+            openButton
+            openOnFocus
+            options={options}
+            onFocus={loadFormsOnce}
+            onMouseDown={loadFormsOnce}
+            onQueryChange={(query) => {
+              if (query) loadFormsOnce()
+            }}
+            onSelect={(nextValue) =>
+              onChange(PatchEvent.from(nextValue ? set(nextValue) : unset()))
+            }
+            placeholder={
+              isLoading ? "Loading HubSpot forms..." : "Select a HubSpot form"
+            }
+            popover={{ portal: true, width: "auto" }}
+            radius={2}
+            renderOption={(option) => (
+              <HubSpotFormOptionPreview option={option} />
+            )}
+            renderValue={(_, option) => {
+              const form = option
+                ? decodeHubSpotFormSelection(option.value)
+                : selectedForm
+              return form ? getHubSpotFormSelectionLabel(form) : ""
+            }}
+            value={value ?? ""}
+          />
+        </Box>
+        <Button
+          disabled={readOnly || isLoading}
+          mode="ghost"
+          onClick={() => void loadForms()}
+          text="Refresh"
+          type="button"
+        />
+      </Flex>
+
+      {isLoading ? (
+        <Flex align="center" gap={2}>
+          <Spinner muted />
+          <Text muted size={1}>
+            Fetching forms from HubSpot
+          </Text>
+        </Flex>
+      ) : null}
+
+      {selectedForm ? (
+        <Text muted size={1}>
+          Selected form ID: {selectedForm.formId}
+        </Text>
+      ) : null}
+
+      {error ? (
+        <Text size={1} style={{ color: "var(--card-critical-fg-color)" }}>
+          {error}
+        </Text>
+      ) : null}
+    </Stack>
+  )
+}

package/src/modules/features/forms/hubspot/files/lib/integrations/hubspot/README.md

@@ -0,0 +1,114 @@
+# HubSpot Forms integration
+
+Agnostic, reusable HubSpot Forms embed. The core (`form.tsx`, `embed.tsx`,
+`forms.ts`, `form-selection.ts`, `hubspot-form.css`) has **no CMS dependency**
+and adds **no runtime packages** — it loads HubSpot's official forms script and
+styles the injected DOM with self-contained, themeable CSS.
+
+## 1. Environment
+
+Create a HubSpot **private app** with the `forms` and
+`account-info.security.read` scopes, then add its token to `.env.local`:
+
+```bash
+HUBSPOT_ACCESS_TOKEN=pat-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+The token is only read server-side (in `forms.ts`); it is never exposed to the
+client.
+
+## 2. Render a form
+
+If you already know the form, pass `portalId` / `formId` / `region` directly:
+
+```tsx
+import { HubSpotForm } from "@/lib/integrations/hubspot/form"
+
+export function Contact() {
+  return (
+    <HubSpotForm
+      portalId="1234567"
+      formId="00000000-0000-0000-0000-000000000000"
+      region="na1"
+    />
+  )
+}
+```
+
+`region` is the portal's data-hosting location (`na1`, `eu1`, …).
+
+## 3. Theming
+
+By default the form inherits the **basement starter** design tokens, so it
+matches the surrounding site with no extra work:
+
+| `--hs-*` token | Maps to (fallback) |
+| --- | --- |
+| `--hs-surface` | `--color-primary` (`#ffffff`) |
+| `--hs-text` / `--hs-text-strong` | `--color-secondary` (`#18181b`) |
+| `--hs-accent` | `--color-contrast` (`#ff4d00`) |
+| `--hs-muted` | `--color-gray-400` (`#858585`) |
+| `--hs-font-sans` | `--font-sans` → `--font-mono` → system |
+
+Light/dark follows the host's `[data-theme]` automatically (via
+`--color-primary` / `--color-secondary`). Outside the starter, the fallbacks
+render a clean light theme.
+
+Override any token from a parent scope to customize:
+
+```css
+.my-section {
+  --hs-accent: #487cff;
+  --hs-surface: #0a0a0a;
+  --hs-text: #ededed;
+  --hs-radius: 8px;
+}
+```
+
+## 4. Listing forms programmatically
+
+`getHubSpotFormOptions()` (from `forms.ts`) returns every published form in the
+portal as `{ label, value, renderRawHtml }`. Each `value` is a JSON-encoded
+selection — decode it with `decodeHubSpotFormSelection` and spread it into
+`<HubSpotForm />`.
+
+## 5. Optional: Sanity Studio form picker
+
+When this integration is added to a project that already has Sanity, a
+`sanity/` folder ships alongside the core with a Studio picker:
+
+- `sanity/form-field.ts` — a ready-to-use `hubspotFormField` (`defineField`)
+- `sanity/form-select-input.tsx` — the `<Autocomplete>` input it uses
+- `sanity/form-block.ts` — a sample `hubspotFormBlock` document type
+
+Wire the field into any schema:
+
+```ts
+import { defineType } from "sanity"
+import { hubspotFormField } from "@/lib/integrations/hubspot/sanity/form-field"
+
+export const contactBlock = defineType({
+  name: "contactBlock",
+  type: "object",
+  fields: [hubspotFormField],
+})
+```
+
+Or register the sample block by adding `hubspotFormBlock` to your schema's
+document list, then render it (see the example in `sanity/form-block.ts`).
+
+## 6. Use as a page-builder block
+
+In a basement **Sanity page-builder** project, `hubspotFormBlock` can be a
+selectable block. Adding this integration installs the
+**`hubspot-pagebuilder-block`** agent skill — ask your coding agent to "wire the
+HubSpot form into the page builder" and it makes the edits and verifies the
+typecheck. To do it by hand:
+
+1. `schemas/index.ts` — import `hubspotFormBlock`, add it to `schema.types`
+2. `page-builder-config.ts` — add `"hubspotFormBlock"` to
+   `PageBuilderDocumentType` and a `hubspotFormBlockReference` member
+3. `structure.ts` — add `S.documentTypeListItem("hubspotFormBlock")`
+4. `components/page-builder/renderer.tsx` — add a `case "hubspotFormBlock"` that
+   decodes `block.form` and renders `<HubSpotForm />`
+5. `bun run sanity:typegen && bun typecheck`

package/src/modules/features/forms/hubspot/files/lib/integrations/hubspot/embed.tsx

@@ -0,0 +1,165 @@
+"use client"
+
+import { useCallback, useEffect, useId, useRef, useState } from "react"
+import { HubSpotFormSkeleton } from "./skeleton"
+import "./hubspot-form.css"
+
+const HUBSPOT_FORMS_SCRIPT_SRC = "https://js.hsforms.net/forms/embed/v2.js"
+// A form that hasn't rendered within this window is treated as failed.
+const FORM_READY_TIMEOUT_MS = 12_000
+
+let hubspotFormsScriptPromise: Promise<void> | null = null
+
+type HubSpotFormCreateOptions = {
+  portalId: string
+  formId: string
+  region: string
+  target: string
+  cssRequired?: string
+  css?: string
+  onFormReady?: (form: HTMLFormElement) => void
+}
+
+declare global {
+  interface Window {
+    hbspt?: {
+      forms?: {
+        create: (options: HubSpotFormCreateOptions) => void
+      }
+    }
+  }
+}
+
+const loadHubSpotFormsScript = () => {
+  if (typeof window === "undefined") return Promise.resolve()
+  if (window.hbspt?.forms) return Promise.resolve()
+  if (hubspotFormsScriptPromise) return hubspotFormsScriptPromise
+
+  hubspotFormsScriptPromise = new Promise((resolve, reject) => {
+    // Drop the dead tag on error so a later mount refetches instead of awaiting
+    // a `load` that already fired.
+    const fail = (script: HTMLScriptElement) => {
+      hubspotFormsScriptPromise = null
+      script.remove()
+      reject(new Error("Failed to load the HubSpot forms script."))
+    }
+
+    // An existing tag means a load is in flight (a finished one set window.hbspt,
+    // caught above) — attach to its events.
+    const existing = document.querySelector<HTMLScriptElement>(
+      `script[src="${HUBSPOT_FORMS_SCRIPT_SRC}"]`
+    )
+    if (existing) {
+      existing.addEventListener("load", () => resolve(), { once: true })
+      existing.addEventListener("error", () => fail(existing), { once: true })
+      return
+    }
+
+    const script = document.createElement("script")
+    script.src = HUBSPOT_FORMS_SCRIPT_SRC
+    script.async = true
+    script.charset = "utf-8"
+    script.onload = () => resolve()
+    script.onerror = () => fail(script)
+    document.head.appendChild(script)
+  })
+
+  return hubspotFormsScriptPromise
+}
+
+type HubSpotFormEmbedProps = {
+  portalId: string
+  formId: string
+  region: string
+}
+
+export function HubSpotFormEmbed({
+  portalId,
+  formId,
+  region,
+}: HubSpotFormEmbedProps) {
+  // Sanitize useId() (it can contain `:`) for use as a DOM id / selector.
+  const containerId = `hubspot-form-${useId().replace(/[^a-zA-Z0-9_-]/g, "")}`
+  const containerRef = useRef<HTMLDivElement | null>(null)
+  const readyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const unmountedRef = useRef(false)
+  const [hasError, setHasError] = useState(false)
+  const [isReady, setIsReady] = useState(false)
+
+  const createForm = useCallback(() => {
+    const target = containerRef.current
+    const formsApi = window.hbspt?.forms
+    if (!(target && formsApi)) {
+      setHasError(true)
+      return
+    }
+
+    setIsReady(false)
+    target.innerHTML = ""
+
+    // create() is fire-and-forget: a bad portal/region or archived form never
+    // calls onFormReady, so fall back to the error state on timeout.
+    if (readyTimeoutRef.current) clearTimeout(readyTimeoutRef.current)
+    readyTimeoutRef.current = setTimeout(() => {
+      if (unmountedRef.current) return
+      target.innerHTML = ""
+      setHasError(true)
+    }, FORM_READY_TIMEOUT_MS)
+
+    // cssRequired/css are emptied so HubSpot doesn't inject its own stylesheet —
+    // the form is styled by hubspot-form.css instead. Everything else (submit,
+    // validation, the post-submit thank-you message) is HubSpot's default.
+    formsApi.create({
+      portalId,
+      formId,
+      region,
+      target: `#${containerId}`,
+      cssRequired: "",
+      css: "",
+      onFormReady: () => {
+        if (unmountedRef.current) return
+        if (readyTimeoutRef.current) clearTimeout(readyTimeoutRef.current)
+        setIsReady(true)
+        setHasError(false)
+      },
+    })
+  }, [containerId, formId, portalId, region])
+
+  useEffect(() => {
+    unmountedRef.current = false
+    setHasError(false)
+
+    void loadHubSpotFormsScript()
+      .then(() => {
+        if (unmountedRef.current) return
+        createForm()
+      })
+      .catch((error: unknown) => {
+        if (unmountedRef.current) return
+        console.error("Failed to mount HubSpot form", error)
+        setHasError(true)
+      })
+
+    return () => {
+      unmountedRef.current = true
+      if (readyTimeoutRef.current) clearTimeout(readyTimeoutRef.current)
+      if (containerRef.current) containerRef.current.innerHTML = ""
+    }
+  }, [createForm])
+
+  const showSkeleton = !(isReady || hasError)
+
+  return (
+    <div className="hubspot-form-wrapper">
+      <div className="hubspot-form-embed" id={containerId} ref={containerRef} />
+
+      {showSkeleton ? <HubSpotFormSkeleton /> : null}
+
+      {hasError ? (
+        <p className="hubspot-form-error">
+          We couldn&apos;t load this form right now.
+        </p>
+      ) : null}
+    </div>
+  )
+}

package/src/modules/features/forms/hubspot/files/lib/integrations/hubspot/form-selection.ts

@@ -0,0 +1,40 @@
+export type HubSpotFormSelection = {
+  name: string
+  formId: string
+  portalId: string
+  region: string
+}
+
+export function decodeHubSpotFormSelection(
+  value?: string | null
+): HubSpotFormSelection | null {
+  if (!value) return null
+
+  try {
+    const parsed: unknown = JSON.parse(value)
+
+    if (typeof parsed !== "object" || parsed === null) return null
+
+    const { name, formId, portalId, region } = parsed as Record<string, unknown>
+
+    if (
+      typeof name !== "string" ||
+      typeof formId !== "string" ||
+      typeof portalId !== "string" ||
+      typeof region !== "string"
+    ) {
+      return null
+    }
+
+    // Fields that drive hbspt.forms.create must be non-empty (name is cosmetic).
+    if (!(formId.trim() && portalId.trim() && region.trim())) return null
+
+    return { name, formId, portalId, region }
+  } catch {
+    return null
+  }
+}
+
+export function getHubSpotFormSelectionLabel(selection: HubSpotFormSelection) {
+  return `${selection.name} (${selection.formId})`
+}

package/src/modules/features/forms/hubspot/files/lib/integrations/hubspot/form.tsx

@@ -0,0 +1,29 @@
+import { HubSpotFormEmbed } from "./embed"
+import "./hubspot-form.css"
+
+type HubSpotFormProps = {
+  portalId: string
+  formId: string
+  region: string
+  className?: string | undefined
+}
+
+/**
+ * Renders a HubSpot form, fully styled and decoupled from any CMS. Pass the
+ * portal/form/region directly, or decode them from a stored selection with
+ * `decodeHubSpotFormSelection`.
+ */
+export function HubSpotForm({
+  portalId,
+  formId,
+  region,
+  className,
+}: HubSpotFormProps) {
+  const classes = ["hubspot-form-card", className].filter(Boolean).join(" ")
+
+  return (
+    <div className={classes}>
+      <HubSpotFormEmbed formId={formId} portalId={portalId} region={region} />
+    </div>
+  )
+}

package/src/modules/features/forms/hubspot/files/lib/integrations/hubspot/forms.ts

@@ -0,0 +1,142 @@
+"use server"
+
+import {
+  getHubSpotFormSelectionLabel,
+  type HubSpotFormSelection,
+} from "./form-selection"
+
+type HubSpotAccountDetailsResponse = {
+  portalId?: number | string
+  dataHostingLocation?: string
+}
+
+type HubSpotApiForm = {
+  id?: string
+  name?: string
+  archived?: boolean
+  displayOptions?: {
+    renderRawHtml?: boolean
+  }
+}
+
+type HubSpotFormsResponse = {
+  results?: HubSpotApiForm[]
+  paging?: { next?: { after?: string } }
+}
+
+export type HubSpotFormOption = {
+  label: string
+  value: string
+  /** False when HubSpot will iframe-embed (Free portals); used only as a hint. */
+  renderRawHtml: boolean | null
+}
+
+const HUBSPOT_API_BASE_URL = "https://api.hubapi.com"
+
+async function fetchHubSpotJson<T>(path: string, accessToken: string) {
+  const response = await fetch(`${HUBSPOT_API_BASE_URL}${path}`, {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: "application/json",
+    },
+    cache: "no-store",
+  })
+
+  if (!response.ok) {
+    // Keep the full body for the server log, but throw a clean status so the
+    // caller-facing message never leaks HubSpot's raw response.
+    const body = await response.text()
+    console.error(
+      `HubSpot request failed (${response.status}) ${path}: ${body}`
+    )
+    throw new Error(`HubSpot request failed (${response.status}).`)
+  }
+
+  return (await response.json()) as T
+}
+
+async function fetchHubSpotForms(accessToken: string) {
+  const forms: HubSpotApiForm[] = []
+  let after: string | undefined
+
+  do {
+    const searchParams = new URLSearchParams({
+      formTypes: "hubspot",
+      limit: "100",
+    })
+    if (after) searchParams.set("after", after)
+
+    const response = await fetchHubSpotJson<HubSpotFormsResponse>(
+      `/marketing/v3/forms?${searchParams.toString()}`,
+      accessToken
+    )
+
+    forms.push(...(response.results ?? []))
+    after = response.paging?.next?.after
+  } while (after)
+
+  return forms
+}
+
+/**
+ * Lists every published HubSpot form in the connected portal as a flat list of
+ * options. Each option's `value` is the JSON-encoded selection consumed by
+ * `decodeHubSpotFormSelection` and ultimately by `<HubSpotForm />`.
+ *
+ * Requires a private-app token in `HUBSPOT_ACCESS_TOKEN` with the `forms` and
+ * `account-info.security.read` scopes.
+ */
+export async function getHubSpotFormOptions(): Promise<{
+  forms: HubSpotFormOption[]
+  error: string | null
+}> {
+  const accessToken = process.env.HUBSPOT_ACCESS_TOKEN
+
+  if (!accessToken) {
+    return { forms: [], error: "Missing HUBSPOT_ACCESS_TOKEN." }
+  }
+
+  try {
+    const [accountDetails, forms] = await Promise.all([
+      fetchHubSpotJson<HubSpotAccountDetailsResponse>(
+        "/account-info/v3/details",
+        accessToken
+      ),
+      fetchHubSpotForms(accessToken),
+    ])
+
+    const portalId = accountDetails.portalId
+    if (!portalId) {
+      return {
+        forms: [],
+        error: "HubSpot account details did not include a portal ID.",
+      }
+    }
+
+    const region = accountDetails.dataHostingLocation || "na1"
+
+    const options = forms
+      .filter((form) => form.id && form.name && !form.archived)
+      .map<HubSpotFormOption>((form) => {
+        const selection: HubSpotFormSelection = {
+          name: form.name as string,
+          formId: form.id as string,
+          portalId: String(portalId),
+          region,
+        }
+        return {
+          label: getHubSpotFormSelectionLabel(selection),
+          value: JSON.stringify(selection),
+          renderRawHtml: form.displayOptions?.renderRawHtml ?? null,
+        }
+      })
+      .sort((a, b) => a.label.localeCompare(b.label))
+
+    return { forms: options, error: null }
+  } catch (error) {
+    return {
+      forms: [],
+      error: error instanceof Error ? error.message : "Unable to load forms.",
+    }
+  }
+}