@tribe-nest/forge 1.13.0

package/src/ui/payment/ForgeStripePayment.tsx

@@ -0,0 +1,171 @@
+import { useCallback, useMemo, useState } from "react";
+import { type Appearance, loadStripe } from "@stripe/stripe-js";
+import { Elements, PaymentElement, useElements, useStripe } from "@stripe/react-stripe-js";
+import { useForgeTheme } from "../theme/ForgeThemeProvider";
+import { readableTextOn } from "../theme/contrast";
+import { useFormatCurrency } from "../format/useFormatCurrency";
+import { useSiteConfig } from "../../data/queries/useWebsite";
+import type { PaymentRenderProps } from "./ForgePaymentProvider";
+
+function alpha(hex: number) {
+  return Math.round(hex * 255)
+    .toString(16)
+    .padStart(2, "0");
+}
+
+/**
+ * Forge's built-in Stripe payment UI — the default renderer used by every
+ * payment block (Checkout, Donation, Offer, …) when the app hasn't registered
+ * its own via `<ForgePaymentProvider>`. It is fully self-contained: the Stripe
+ * publishable key + connected account are read from the tenant's runtime
+ * `useSiteConfig()` (Stripe Connect: `loadStripe(platformKey, { stripeAccount })`),
+ * the appearance from `ForgeThemeProvider`, and the pay-button amount from
+ * `useFormatCurrency()`. The consuming site wires nothing.
+ */
+export function ForgeStripePayment({
+  clientSecret,
+  returnUrl,
+  amount,
+  currency,
+  mode = "redirect",
+  onSucceeded,
+  onFailed,
+}: PaymentRenderProps) {
+  const theme = useForgeTheme();
+  const { data: siteConfig } = useSiteConfig();
+  const publishableKey = siteConfig?.stripePublishableKey ?? undefined;
+  const stripeAccountId = siteConfig?.stripeAccountId ?? undefined;
+
+  const stripePromise = useMemo(
+    () => (publishableKey && stripeAccountId ? loadStripe(publishableKey, { stripeAccount: stripeAccountId }) : null),
+    [publishableKey, stripeAccountId],
+  );
+
+  // Fully themed Stripe Elements appearance (variables + rules), ported from the
+  // client app's payment form so the inputs/tabs match the site theme.
+  const appearance: Appearance = useMemo(
+    () => ({
+      theme: "flat",
+      variables: {
+        fontLineHeight: "1.5",
+        borderRadius: `${theme.cornerRadius}px`,
+        colorBackground: theme.colors.background,
+        accessibleColorOnColorPrimary: theme.colors.text,
+        colorPrimary: theme.colors.primary,
+        colorText: theme.colors.text,
+        logoColor: theme.colors.text,
+        colorTextPlaceholder: `${theme.colors.text}${alpha(0.5)}`,
+      },
+      rules: {
+        ".AccordionItem": { backgroundColor: theme.colors.background },
+        ".Block": { backgroundColor: theme.colors.background, boxShadow: "none", padding: "12px" },
+        ".Input": {
+          padding: "12px",
+          borderRadius: `${theme.cornerRadius}px`,
+          border: `1px solid ${theme.colors.primary}${alpha(0.4)}`,
+        },
+        ".Input:disabled, .Input--invalid:disabled": { color: "lightgray" },
+        ".Tab": { padding: "10px 12px 8px 12px", border: "none", backgroundColor: theme.colors.background },
+        ".Tab:hover": {
+          border: "none",
+          boxShadow: "0px 1px 1px rgba(0, 0, 0, 0.03), 0px 3px 7px rgba(18, 42, 66, 0.04)",
+        },
+        ".Tab--selected, .Tab--selected:focus, .Tab--selected:hover": {
+          border: "none",
+          backgroundColor: theme.colors.background,
+          boxShadow:
+            "0 0 0 1.5px var(--colorPrimaryText), 0px 1px 1px rgba(0, 0, 0, 0.03), 0px 3px 7px rgba(18, 42, 66, 0.04)",
+        },
+        ".Label": { fontWeight: "500" },
+      },
+    }),
+    [theme],
+  );
+
+  if (!clientSecret) return null;
+  if (!stripePromise) {
+    return (
+      <p style={{ color: "#ef4444", fontSize: 14 }}>Payment is not configured.</p>
+    );
+  }
+
+  return (
+    <Elements options={{ clientSecret, appearance, loader: "auto" }} stripe={stripePromise}>
+      <Inner returnUrl={returnUrl} amount={amount} currency={currency} mode={mode} onSucceeded={onSucceeded} onFailed={onFailed} />
+    </Elements>
+  );
+}
+
+function Inner({
+  returnUrl,
+  amount,
+  currency,
+  mode = "redirect",
+  onSucceeded,
+  onFailed,
+}: Omit<PaymentRenderProps, "clientSecret">) {
+  const theme = useForgeTheme();
+  const { formatCurrency } = useFormatCurrency();
+  const stripe = useStripe();
+  const elements = useElements();
+  const [message, setMessage] = useState("");
+  const [isLoading, setIsLoading] = useState(false);
+
+  const buttonText = `Pay ${formatCurrency(amount, currency || undefined)} Now`;
+
+  const handleSubmit = useCallback(async () => {
+    if (!stripe || !elements) return;
+    setIsLoading(true);
+    setMessage("");
+
+    if (mode === "manual") {
+      const { error, paymentIntent } = await stripe.confirmPayment({
+        elements,
+        confirmParams: { return_url: returnUrl },
+        redirect: "if_required",
+      });
+      if (error) {
+        const msg = error.message ?? "Your payment could not be processed.";
+        setMessage(msg);
+        setIsLoading(false);
+        onFailed?.(msg);
+        return;
+      }
+      if (paymentIntent?.status === "succeeded" || paymentIntent?.status === "processing") {
+        setIsLoading(false);
+        onSucceeded?.();
+        return;
+      }
+      setIsLoading(false);
+      onFailed?.("Payment did not complete.");
+      return;
+    }
+
+    const { error } = await stripe.confirmPayment({ elements, confirmParams: { return_url: returnUrl } });
+    setMessage(error.message ?? "An unexpected error occurred.");
+    setIsLoading(false);
+  }, [stripe, elements, mode, returnUrl, onSucceeded, onFailed]);
+
+  return (
+    <form onSubmit={(e) => e.preventDefault()} style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+      <PaymentElement options={{ layout: "accordion" }} />
+      {message && <div style={{ color: "#ef4444", fontSize: 14 }}>{message}</div>}
+      <button
+        onClick={handleSubmit}
+        disabled={isLoading || !stripe || !elements}
+        style={{
+          background: theme.colors.primary,
+          color: readableTextOn(theme.colors.primary),
+          border: "none",
+          borderRadius: theme.cornerRadius,
+          padding: "12px 18px",
+          fontWeight: 600,
+          cursor: "pointer",
+          opacity: isLoading ? 0.6 : 1,
+        }}
+      >
+        {isLoading ? "Processing…" : buttonText}
+      </button>
+    </form>
+  );
+}

package/src/ui/shell/TribeNestApp.tsx

@@ -0,0 +1,121 @@
+import { useEffect, type ReactNode } from "react";
+import { ForgeProvider, type ForgeProviderProps } from "../../provider/ForgeAppProvider";
+import { AudioPlayer } from "../styled/AudioPlayer";
+import { ForgeAnalytics } from "../analytics/ForgeAnalytics";
+import { PwaRegistration } from "../styled/PwaRegistration";
+import { InstallBanner } from "../styled/InstallBanner";
+import { CookieConsent } from "../styled/CookieConsent";
+import { useThemeTokens } from "../theme/ForgeThemeProvider";
+import { shellPwaEnabled } from "./shellGating";
+import { captureAttributionRefFromUrl, readAttributionRef } from "../../utils/attribution";
+import { captureLandingFromUrl, postLandingBeacon } from "../../utils/landing";
+
+// Captures both attribution signals on first paint: the tracked-link `?tn_ref`
+// (stripped afterwards) and the first-touch landing snapshot (all utm/click-id
+// params + referrer, kept in the URL for page-level ad pixels). On a FRESH
+// landing it also fires the visit-level beacon so the sale-less visit is counted.
+// Client-only, renders null. Lives in the shell so every code website gets ad
+// attribution without editing the tenant-owned __root. See docs/ads-attribution-initiative.md.
+function AttributionCapture({ enabled, apiUrl, profileId }: { enabled: boolean; apiUrl?: string; profileId?: string }) {
+  useEffect(() => {
+    if (!enabled) return;
+    captureAttributionRefFromUrl();
+    const fresh = captureLandingFromUrl();
+    if (fresh && apiUrl && profileId) {
+      postLandingBeacon(apiUrl, profileId, readAttributionRef() ?? undefined);
+    }
+  }, [enabled, apiUrl, profileId]);
+  return null;
+}
+
+export interface TribeNestAppProps extends Omit<ForgeProviderProps, "children"> {
+  /** The page tree — the tenant's own Nav / <Outlet/> / Footer. */
+  children: ReactNode;
+  /** "published" on the live site, "draft" in the editor preview / review Worker.
+   * With `editable`, gates the PWA (register + install) to the live site only. */
+  state?: "draft" | "published";
+  /** Href for the client-injected manifest link fallback. */
+  manifestHref?: string;
+  /** Turn individual shell concerns off (all default on). */
+  analytics?: boolean;
+  pwa?: boolean;
+  cookieConsent?: boolean;
+}
+
+// Ensure the PWA `<link rel="manifest">` + a `theme-color` meta exist even if the
+// route's head() never called buildPwaHead (retrofit for older shells). Runs
+// inside ForgeProvider so it can read the resolved theme; client-only, renders null.
+function PwaHeadClient({ enabled, manifestHref }: { enabled: boolean; manifestHref: string }) {
+  const t = useThemeTokens();
+  useEffect(() => {
+    if (!enabled || typeof document === "undefined") return;
+    if (!document.querySelector('link[rel="manifest"]')) {
+      const link = document.createElement("link");
+      link.rel = "manifest";
+      link.href = manifestHref;
+      document.head.appendChild(link);
+    }
+    if (t.primary && !document.querySelector('meta[name="theme-color"]')) {
+      const meta = document.createElement("meta");
+      meta.name = "theme-color";
+      meta.content = t.primary;
+      document.head.appendChild(meta);
+    }
+  }, [enabled, manifestHref, t.primary]);
+  return null;
+}
+
+/**
+ * The single root component for a TribeNest code website. Wrap the page tree once
+ * — it owns the whole provider tree (via `ForgeProvider`) PLUS the global shell
+ * UI: audio player, analytics + Meta Pixel, PWA (service-worker registration +
+ * install banner + manifest link), and cookie consent. Because these live in
+ * Forge, a Forge version bump delivers shell changes to every site without
+ * editing the tenant-owned `__root.tsx`.
+ *
+ *     <TribeNestApp apiUrl={API_URL} profileId={PROFILE_ID} subdomain={SUBDOMAIN}
+ *       editable={FORGE_EDIT} state={FORGE_STATE}
+ *       initialContentDoc={contentDoc} initialSiteConfig={siteConfig}>
+ *       <Nav />
+ *       <main><Outlet /></main>
+ *       <SiteFooter />
+ *     </TribeNestApp>
+ *
+ * Nav / footer / pages stay tenant-owned children. A footer "Cookie settings"
+ * link re-opens the consent banner via `useCookieConsent().reopen()`.
+ */
+export function TribeNestApp({
+  children,
+  editable,
+  state,
+  manifestHref = "/manifest.webmanifest",
+  analytics = true,
+  pwa = true,
+  cookieConsent = true,
+  ...forgeProps
+}: TribeNestAppProps) {
+  // Register the SW + offer install only on the live published site — never in
+  // the HMR editor or on a preview-<versionId>.* review Worker (state="draft").
+  const pwaEnabled = shellPwaEnabled({ pwa, editable, state });
+  return (
+    <ForgeProvider editable={editable} {...forgeProps}>
+      {children}
+      {/* Global playback bar — self-pins to the viewport bottom, renders nothing
+          until a track loads. */}
+      <AudioPlayer />
+      {/* Auto page views + clicks (+ Meta Pixel, gated on marketing consent).
+          First-party runs cookieless. Off in the editor so preview isn't counted. */}
+      {analytics && <ForgeAnalytics enabled={!editable} firstPartyMode="cookieless" />}
+      {/* Ad attribution capture (tracked-link ref + first-touch landing + visit
+          beacon). Off in the editor so preview visits aren't credited. */}
+      <AttributionCapture enabled={!editable} apiUrl={forgeProps.apiUrl} profileId={forgeProps.profileId} />
+      {/* PWA — SW registration + install banner + (fallback) manifest link. */}
+      {pwa && <PwaRegistration enabled={pwaEnabled} />}
+      {pwa && <InstallBanner enabled={pwaEnabled} />}
+      {pwa && <PwaHeadClient enabled={pwaEnabled} manifestHref={manifestHref} />}
+      {/* Consent banner — shown on first visit, re-openable from anywhere via
+          useCookieConsent().reopen(). Hidden in the editor. */}
+      {cookieConsent && !editable && <CookieConsent useTribeNestPrivacy />}
+    </ForgeProvider>
+  );
+}

package/src/ui/shell/shellGating.spec.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest";
+import { shellPwaEnabled } from "./shellGating";
+
+// The PWA (SW register + install prompt) must be ON only for the live published
+// site, and OFF everywhere else (editor, preview/draft), so review Workers never
+// SW-cache or prompt to install.
+describe("shellPwaEnabled", () => {
+  it("is true only for a live published, non-editable site", () => {
+    expect(shellPwaEnabled({ editable: false, state: "published" })).toBe(true);
+  });
+
+  it("is false in the editor even when published", () => {
+    expect(shellPwaEnabled({ editable: true, state: "published" })).toBe(false);
+  });
+
+  it("is false for a draft/preview deploy", () => {
+    expect(shellPwaEnabled({ editable: false, state: "draft" })).toBe(false);
+    expect(shellPwaEnabled({ editable: false })).toBe(false); // state undefined
+  });
+
+  it("is false when pwa is explicitly opted out", () => {
+    expect(shellPwaEnabled({ pwa: false, editable: false, state: "published" })).toBe(false);
+  });
+
+  it("defaults pwa to on when omitted", () => {
+    expect(shellPwaEnabled({ editable: false, state: "published" })).toBe(true);
+  });
+});

package/src/ui/shell/shellGating.ts

@@ -0,0 +1,11 @@
+// Pure gating logic for TribeNestApp, kept React-free so it's unit-testable in the
+// node test env (no jsdom). The PWA (service-worker registration + install
+// prompt) must run ONLY on the live published site — never in the HMR editor
+// (`editable`) or on a preview-<versionId>.* review Worker (state="draft").
+export function shellPwaEnabled(opts: {
+  pwa?: boolean;
+  editable?: boolean;
+  state?: "draft" | "published";
+}): boolean {
+  return (opts.pwa ?? true) && !opts.editable && opts.state === "published";
+}