keystone-design-bootstrap 1.0.64 → 1.0.66

package/README.md

@@ -95,6 +95,37 @@ import type { Service, Testimonial } from '@keystone-pzjr/design-bootstrap/types
 import { themes } from '@keystone-pzjr/design-bootstrap/themes'
 ```
 
+## Meta Pixel Tracking
+
+Meta Pixel is initialised automatically in `KeystoneRootLayout` when the account has a connected Meta integration with a pixel configured. Most events fire without any extra work. The one place you need to add tracking manually is **custom form submissions**.
+
+### What fires automatically
+
+| Event | Trigger |
+|---|---|
+| `PageView` | Every page load |
+| `ViewContent` | Route changes to `/services`, `/services/:slug`, `/locations`, `/locations/:slug`, `/portal`, `/service-menu`, `/faq`, `/contact` |
+| `InitiateCheckout` | Click on any link to the account's external booking URL |
+| Portal tab events | Opening Services, Packages, Specials, or Booking tabs in the member portal |
+
+### Adding tracking to a custom form
+
+On successful submission, add two calls:
+
+```tsx
+import { firePixelEvent, setPixelUserData } from 'keystone-design-bootstrap/tracking';
+
+// inside your success handler, after a confirmed API response:
+await setPixelUserData({ email: data.email, phone: data.phone });
+firePixelEvent('Lead');
+```
+
+Also submit with `formType: 'lead'` in the POST body — this triggers the server-side CAPI `Lead` event automatically with no extra backend work.
+
+Both calls are silent no-ops when no Meta Pixel is configured for the site.
+
+See `components/sections/VipReferralForm.tsx` in any customer site for a complete working example.
+
 ## Architecture
 
 - **Server-first**: Data fetching happens server-side, components render as Server Components where possible

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keystone-design-bootstrap",
-  "version": "1.0.64",
+  "version": "1.0.66",
   "description": "Keystone Design Bootstrap - Sections, Elements, and Theme System for customer websites",
   "type": "module",
   "main": "./src/index.ts",

package/src/design_system/portal/BookIframePanel.tsx

@@ -0,0 +1,132 @@
+'use client';
+
+import React, { useState, useEffect, useRef } from 'react';
+
+interface BookIframePanelProps {
+  bookingHref: string;
+  businessName: string;
+}
+
+export function BookIframePanel({ bookingHref, businessName }: BookIframePanelProps) {
+  const [hasOpened, setHasOpened] = useState(false);
+  const [modalOpen, setModalOpen] = useState(false);
+  const [isVisible, setIsVisible] = useState(false);
+  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const openModal = () => {
+    setHasOpened(true);
+    setModalOpen(true);
+  };
+
+  const closeModal = () => {
+    setIsVisible(false);
+    closeTimerRef.current = setTimeout(() => setModalOpen(false), 300);
+  };
+
+  // Clear any pending close timer on unmount.
+  useEffect(() => {
+    return () => {
+      if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
+    };
+  }, []);
+
+  // Animate in after mount — double rAF ensures the transition fires after the
+  // element is painted rather than immediately on insertion.
+  useEffect(() => {
+    if (!modalOpen) return;
+    let cancelled = false;
+    const id = requestAnimationFrame(() =>
+      requestAnimationFrame(() => {
+        if (!cancelled) setIsVisible(true);
+      })
+    );
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(id);
+    };
+  }, [modalOpen]);
+
+  // Prevent body scroll while modal is open.
+  useEffect(() => {
+    document.body.style.overflow = modalOpen ? 'hidden' : '';
+    return () => { document.body.style.overflow = ''; };
+  }, [modalOpen]);
+
+  return (
+    <>
+      {/* Blurred iframe preview with overlay message */}
+      <div className="relative rounded-component border border-secondary overflow-hidden" style={{ height: '70vh' }}>
+        {/* iframe — purely visual, non-interactive */}
+        <iframe
+          src={bookingHref}
+          className="w-full h-full pointer-events-none select-none"
+          title="Booking preview"
+          tabIndex={-1}
+          aria-hidden="true"
+        />
+
+        {/* Backdrop blur + message overlay */}
+        <div className="absolute inset-0 flex flex-col items-center justify-center px-6 py-8 backdrop-blur-[3.9px] bg-primary/70">
+          <div className="w-full max-w-sm rounded-component border border-secondary bg-primary px-6 py-6 text-center shadow-sm">
+            <p className="text-xl font-bold text-primary">Booking Instructions</p>
+            <p className="mt-5 text-sm text-secondary leading-relaxed">
+              We use a separate platform that may ask for an additional sign in or intake details to fully create your profile and collect your appointment information.
+            </p>
+            <div className="mt-5 flex flex-wrap items-center justify-center gap-3">
+              <button
+                onClick={openModal}
+                className="inline-flex items-center gap-2 rounded-interactive bg-brand-solid px-5 py-2.5 text-sm font-semibold text-white transition-colors hover:bg-brand-solid_hover"
+              >
+                Start Booking
+              </button>
+              <a
+                href={bookingHref}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="inline-flex items-center gap-1.5 rounded-interactive border border-secondary bg-secondary px-5 py-2.5 text-sm font-semibold text-primary transition-colors hover:bg-secondary_hover"
+              >
+                Open in New Tab
+                <svg className="size-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M13.5 6H5.25A2.25 2.25 0 003 8.25v10.5A2.25 2.25 0 005.25 21h10.5A2.25 2.25 0 0018 18.75V10.5m-10.5 6L21 3m0 0h-5.25M21 3v5.25" />
+                </svg>
+              </a>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Full-screen modal — kept mounted after first open so the iframe session persists on close/reopen */}
+      {hasOpened && (
+        <div
+          className={`fixed inset-0 z-50 flex flex-col bg-primary transition-[opacity,transform] duration-300 ease-out ${
+            modalOpen && isVisible
+              ? 'opacity-100 translate-y-0'
+              : 'opacity-0 translate-y-3 pointer-events-none'
+          }`}
+        >
+          {/* Modal header */}
+          <div className="flex shrink-0 items-center justify-between border-b border-secondary bg-primary px-4 py-3">
+            <span className="text-sm font-semibold text-primary">{businessName} Booking</span>
+            <button
+              onClick={closeModal}
+              className="inline-flex items-center gap-2 rounded-interactive bg-brand-solid px-4 py-1.5 text-sm font-semibold text-white transition-colors hover:bg-brand-solid_hover"
+            >
+              <svg className="size-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2.5}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+              </svg>
+              Close
+            </button>
+          </div>
+
+          {/* iframe fills the rest of the screen */}
+          <iframe
+            src={bookingHref}
+            className="min-h-0 flex-1 w-full"
+            title="Book appointment"
+            allow="payment"
+          />
+        </div>
+      )}
+    </>
+  );
+}

package/src/design_system/portal/PortalPage.tsx

@@ -7,6 +7,7 @@ import { LoginModalController } from './LoginModalController';
 import { MessageComposer } from './MessageComposer';
 import { RowThumbnail } from './RowThumbnail';
 import { PortalTabTracker } from './PortalTabTracker';
+import { BookIframePanel } from './BookIframePanel';
 import {
   CONSUMER_TOKEN_COOKIE,
   fetchConsumerMe,
@@ -508,11 +509,13 @@ function BookPanel({
   bookingLabel,
   bookingAllowsIframe,
   isLoggedIn,
+  businessName,
 }: {
   bookingHref: string;
   bookingLabel: string;
   bookingAllowsIframe: boolean;
   isLoggedIn: boolean;
+  businessName: string;
 }) {
   if (!isLoggedIn) {
     return <LoginWall message="Continue to view booking options." cta="View Booking Options" />;
@@ -522,14 +525,7 @@ function BookPanel({
     return (
       <>
         <PortalTabTracker event="InitiateCheckout" />
-        <div className="rounded-component border border-secondary overflow-hidden" style={{ height: '70vh' }}>
-          <iframe
-            src={bookingHref}
-            className="w-full h-full"
-            title="Book appointment"
-            allow="payment"
-          />
-        </div>
+        <BookIframePanel bookingHref={bookingHref} businessName={businessName} />
       </>
     );
   }
@@ -575,7 +571,7 @@ export async function PortalPage({
   contactHref = '/contact',
 }: PortalPageProps) {
   const params = await searchParams ?? {};
-  const tab: Tab = VALID_TABS.includes(params.tab as Tab) ? (params.tab as Tab) : 'services';
+  const tabParam = VALID_TABS.includes(params.tab as Tab) ? (params.tab as Tab) : null;
   const contactIdParsed = params.contact ? parseInt(params.contact, 10) : NaN;
   const contactId = Number.isFinite(contactIdParsed) ? contactIdParsed : null;
 
@@ -595,6 +591,19 @@ export async function PortalPage({
   const resolvedBookingHref =
     bookingHref ?? companyInformation?.external_management_url ?? null;
 
+  // Build the tabs array first so the default can simply be whatever is first.
+  const tabs: Array<{ id: Tab; label: string }> = [
+    ...(resolvedBookingHref ? [{ id: 'book' as Tab, label: bookingLabel }] : []),
+    { id: 'services', label: 'Services' },
+    { id: 'packages', label: 'Packages' },
+    { id: 'specials', label: 'Specials' },
+    { id: 'messages', label: 'Messages' },
+    ...(!resolvedBookingHref ? [{ id: 'book' as Tab, label: bookingLabel }] : []),
+  ];
+
+  // Default to the first tab so tab order and default selection are always in sync.
+  const tab: Tab = tabParam ?? tabs[0].id;
+
   // Auto-detect iframe support by inspecting the booking URL's framing headers.
   // Only runs when the book tab is active to avoid unnecessary requests.
   // Skipped entirely when forceExternalBooking is set.
@@ -633,14 +642,6 @@ export async function PortalPage({
   const packageList = packages ?? [];
   const specials = aggregateSpecials(serviceList, packageList);
 
-  const tabs: Array<{ id: Tab; label: string }> = [
-    { id: 'services', label: 'Services' },
-    { id: 'packages', label: 'Packages' },
-    { id: 'specials', label: 'Specials' },
-    { id: 'messages', label: 'Messages' },
-    { id: 'book', label: bookingLabel },
-  ];
-
   return (
     <div className="min-h-screen bg-primary">
       {/* Portal Header */}
@@ -685,33 +686,37 @@ export async function PortalPage({
             </div>
           </div>
 
-          {/* Tabs */}
-          <div className="mt-4 flex gap-1 overflow-x-auto pb-px scrollbar-none">
-            {tabs.map((t) => {
-              const isActive = tab === t.id;
-              const isGated = !isLoggedIn && (t.id === 'specials' || t.id === 'messages' || t.id === 'book');
-              const href = `${portalHref}?tab=${t.id}`;
-              const className = `shrink-0 rounded-interactive px-4 py-2 text-sm font-medium transition-colors whitespace-nowrap ${
-                isActive ? 'bg-brand-solid text-white' : 'text-secondary hover:bg-secondary hover:text-primary'
-              }`;
-              if (isGated) {
+          {/* Tabs — scrollable on mobile; fade on right edge hints at overflow */}
+          <div className="relative mt-4">
+            <div className="flex gap-1 overflow-x-auto pb-px scrollbar-none">
+              {tabs.map((t) => {
+                const isActive = tab === t.id;
+                const isGated = !isLoggedIn && (t.id === 'specials' || t.id === 'messages' || t.id === 'book');
+                const href = `${portalHref}?tab=${t.id}`;
+                const className = `shrink-0 rounded-interactive px-4 py-2 text-sm font-medium transition-colors whitespace-nowrap ${
+                  isActive ? 'bg-brand-solid text-white' : 'text-secondary hover:bg-secondary hover:text-primary'
+                }`;
+                if (isGated) {
+                  return (
+                    <button
+                      key={t.id}
+                      data-open-login-modal
+                      data-login-redirect={href}
+                      className={className}
+                    >
+                      {t.label}
+                    </button>
+                  );
+                }
                 return (
-                  <button
-                    key={t.id}
-                    data-open-login-modal
-                    data-login-redirect={href}
-                    className={className}
-                  >
+                  <Link key={t.id} href={href} className={className}>
                     {t.label}
-                  </button>
+                  </Link>
                 );
-              }
-              return (
-                <Link key={t.id} href={href} className={className}>
-                  {t.label}
-                </Link>
-              );
-            })}
+              })}
+            </div>
+            {/* Right-edge fade: visible on small screens only, hints that tabs are scrollable */}
+            <div className="pointer-events-none absolute inset-y-0 right-0 w-8 bg-gradient-to-l from-primary to-transparent md:hidden" />
           </div>
         </div>
       </div>
@@ -750,6 +755,7 @@ export async function PortalPage({
               bookingLabel={bookingLabel}
               bookingAllowsIframe={bookingAllowsIframe}
               isLoggedIn={isLoggedIn}
+              businessName={businessName}
             />
           ) : (
             <div className="flex flex-col items-center justify-center py-20 text-center">

package/src/design_system/sections/contact-section-form.aman.tsx

@@ -62,7 +62,7 @@ export const ContactSectionForm = ({
                 formRef.current?.reset();
                 onSuccess?.();
                 await setPixelUserData({ email: data.email, phone: data.phone });
-                firePixelEvent('Lead');
+                firePixelEvent('Lead', undefined, result.eventId);
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
                 setSubmitStatus('error');

package/src/design_system/sections/contact-section-form.balance.tsx

@@ -62,7 +62,7 @@ export const ContactSectionForm = ({
                 formRef.current?.reset();
                 onSuccess?.();
                 await setPixelUserData({ email: data.email, phone: data.phone });
-                firePixelEvent('Lead');
+                firePixelEvent('Lead', undefined, result.eventId);
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
                 setSubmitStatus('error');

package/src/design_system/sections/contact-section-form.barelux.tsx

@@ -62,7 +62,7 @@ export const ContactSectionForm = ({
                 formRef.current?.reset();
                 onSuccess?.();
                 await setPixelUserData({ email: data.email, phone: data.phone });
-                firePixelEvent('Lead');
+                firePixelEvent('Lead', undefined, result.eventId);
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
                 setSubmitStatus('error');

package/src/design_system/sections/contact-section-form.tsx

@@ -70,7 +70,7 @@ export const ContactSectionForm = ({
                 formRef.current?.reset();
                 onSuccess?.();
                 await setPixelUserData({ email: data.email, phone: data.phone });
-                firePixelEvent('Lead');
+                firePixelEvent('Lead', undefined, result.eventId);
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
                 setSubmitStatus('error');

package/src/design_system/sections/header-navigation.aman.tsx

@@ -3,12 +3,13 @@
 import React, { useState, useRef, useCallback } from 'react';
 import Link from 'next/link';
 import Image from 'next/image';
+import { usePathname } from 'next/navigation';
 import { Button } from '../elements';
 import { cx } from '../../utils/cx';
 import { getLogoUrl } from '../../utils/photo-helpers';
 import type { HeaderComponentProps } from './header-navigation';
 import type { NavItem } from '../../types/config';
-import { resolveCtaUrls, isExternalCtaUrl } from '../../lib/cta-urls';
+import { resolveCtaUrls, isExternalCtaUrl, resolvePortalPath } from '../../lib/cta-urls';
 
 // Maximum items to show before "View All" link
 const MAX_DROPDOWN_ITEMS = 3;
@@ -58,6 +59,12 @@ export function HeaderNavigation({
   const navigation = navigationOverride || config?.navigation?.header || [];
   const ctaUrls = resolveCtaUrls(companyInformation);
 
+  // Hide the sticky bottom bar when the user is already on the portal page —
+  // the portal has its own Book Now tab so the bar is redundant and confusing.
+  const pathname = usePathname();
+  const portalPath = resolvePortalPath(companyInformation);
+  const isPortalPage = portalPath ? pathname?.startsWith(portalPath) : false;
+
   // Cancel any pending close timeout
   const cancelCloseTimeout = useCallback(() => {
     if (closeTimeoutRef.current) {
@@ -390,8 +397,8 @@ export function HeaderNavigation({
         </div>
       )}
 
-      {/* Sticky Contact Button (Mobile) - Left=Contact Us, Right=Book Now */}
-      <div className="fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary">
+      {/* Sticky Contact Button (Mobile) — hidden on portal page where it would be redundant */}
+      {!isPortalPage && <div className="fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary">
         <div className="flex gap-0">
                 {props?.cta_button?.secondary_label && ctaUrls.hasSecondary && (
                     <Button
@@ -414,7 +421,7 @@ export function HeaderNavigation({
                     {(props?.cta_button?.secondary_label && ctaUrls.hasSecondary) ? props.cta_button.secondary_label : (props?.cta_button?.label || "Contact")}
                   </Button>
         </div>
-      </div>
+      </div>}
     </>
   );
 }

package/src/design_system/sections/header-navigation.balance.tsx

@@ -3,11 +3,12 @@
 import React, { useState, useRef, useCallback } from 'react';
 import Link from 'next/link';
 import Image from 'next/image';
+import { usePathname } from 'next/navigation';
 import { Button } from '../elements';
 import { getLogoUrl } from '../../utils/photo-helpers';
 import type { HeaderComponentProps } from './header-navigation';
 import type { NavItem } from '../../types/config';
-import { resolveCtaUrls, isExternalCtaUrl } from '../../lib/cta-urls';
+import { resolveCtaUrls, isExternalCtaUrl, resolvePortalPath } from '../../lib/cta-urls';
 
 export function HeaderNavigation({ 
   props, 
@@ -37,6 +38,12 @@ export function HeaderNavigation({
   const navigation = navigationOverride || config?.navigation?.header || [];
   const ctaUrls = resolveCtaUrls(companyInformation);
 
+  // Hide the sticky bottom bar when the user is already on the portal page —
+  // the portal has its own Book Now tab so the bar is redundant and confusing.
+  const pathname = usePathname();
+  const portalPath = resolvePortalPath(companyInformation);
+  const isPortalPage = portalPath ? pathname?.startsWith(portalPath) : false;
+
   const cancelCloseTimeout = useCallback(() => {
     if (closeTimeoutRef.current) {
       clearTimeout(closeTimeoutRef.current);
@@ -301,8 +308,8 @@ export function HeaderNavigation({
         </div>
       )}
 
-      {/* Sticky Bottom Bar (mobile only) */}
-      <div className="fixed bottom-0 left-0 right-0 z-40 md:hidden" style={{ backgroundColor: 'rgb(148, 133, 84)' }}>
+      {/* Sticky Bottom Bar (mobile only) — hidden on portal page where it would be redundant */}
+      {!isPortalPage && <div className="fixed bottom-0 left-0 right-0 z-40 md:hidden" style={{ backgroundColor: 'rgb(148, 133, 84)' }}>
         <div className="flex gap-0">
           {props?.cta_button?.secondary_label && ctaUrls.hasSecondary && (
             <Button
@@ -326,7 +333,7 @@ export function HeaderNavigation({
             {(props?.cta_button?.secondary_label && ctaUrls.hasSecondary) ? props.cta_button.secondary_label : (props?.cta_button?.label || "Contact")}
           </Button>
         </div>
-      </div>
+      </div>}
     </>
   );
 }

package/src/design_system/sections/header-navigation.barelux.tsx

@@ -3,11 +3,12 @@
 import React, { useState, useRef, useCallback } from 'react';
 import Link from 'next/link';
 import Image from 'next/image';
+import { usePathname } from 'next/navigation';
 import { Button } from '../elements';
 import { getLogoUrl } from '../../utils/photo-helpers';
 import type { HeaderComponentProps } from './header-navigation';
 import type { NavItem } from '../../types/config';
-import { resolveCtaUrls, isExternalCtaUrl } from '../../lib/cta-urls';
+import { resolveCtaUrls, isExternalCtaUrl, resolvePortalPath } from '../../lib/cta-urls';
 
 // Maximum items to show before "View All" link
 const MAX_DROPDOWN_ITEMS = 6;
@@ -43,6 +44,12 @@ export function HeaderNavigation({
     const navigation = navigationOverride || config?.navigation?.header || [];
     const ctaUrls = resolveCtaUrls(companyInformation);
 
+    // Hide the sticky bottom bar when the user is already on the portal page —
+    // the portal has its own Book Now tab so the bar is redundant and confusing.
+    const pathname = usePathname();
+    const portalPath = resolvePortalPath(companyInformation);
+    const isPortalPage = portalPath ? pathname?.startsWith(portalPath) : false;
+
     // Cancel any pending close timeout
     const cancelCloseTimeout = useCallback(() => {
         if (closeTimeoutRef.current) {
@@ -343,8 +350,8 @@ export function HeaderNavigation({
                 </div>
             )}
 
-            {/* Sticky Book/Contact bar (mobile only) - matches barelux theme */}
-            <div className="fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary">
+            {/* Sticky Book/Contact bar (mobile only) — hidden on portal page where it would be redundant */}
+            {!isPortalPage && <div className="fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary">
                 <div className="flex gap-0">
                     {props?.cta_button?.secondary_label && ctaUrls.hasSecondary && (
                             <Button
@@ -367,7 +374,7 @@ export function HeaderNavigation({
                             {(props?.cta_button?.secondary_label && ctaUrls.hasSecondary) ? props.cta_button.secondary_label : (props?.cta_button?.label || "Contact")}
                         </Button>
                 </div>
-            </div>
+            </div>}
         </>
     );
 }

package/src/design_system/sections/header-navigation.tsx

@@ -1,6 +1,7 @@
 'use client';
 import React, { useRef, useState } from 'react';
 import Link from 'next/link';
+import { usePathname } from 'next/navigation';
 import Image from 'next/image';
 import { ChevronDown } from "@untitledui/icons";
 import { Button as AriaButton, Dialog as AriaDialog, DialogTrigger as AriaDialogTrigger, Popover as AriaPopover } from "react-aria-components";
@@ -11,7 +12,7 @@ import { getLogoUrl } from '../../utils/photo-helpers';
 import type { CompanyInformation } from '../../types/api/company-information';
 import type { WebsitePhotos } from '../../types/api/website-photos';
 import type { NavItem, SiteConfig } from '../../types/config';
-import { resolveCtaUrls, isExternalCtaUrl } from '../../lib/cta-urls';
+import { resolveCtaUrls, isExternalCtaUrl, resolvePortalPath } from '../../lib/cta-urls';
 
 export interface HeaderProps {
   logo: {
@@ -108,6 +109,12 @@ export function HeaderNavigation({
   
   const dynamicNavigation = navigation;
 
+  // Hide the sticky bottom bar when the user is already on the portal page —
+  // the portal has its own Book Now tab so the bar is redundant and confusing.
+  const pathname = usePathname();
+  const portalPath = resolvePortalPath(companyInformation);
+  const isPortalPage = portalPath ? pathname?.startsWith(portalPath) : false;
+
   const getVariantClasses = () => {
     switch (variant) {
       case 'minimal':
@@ -366,8 +373,8 @@ export function HeaderNavigation({
       </div>
     </header>
 
-      {/* Sticky Book/Contact bar (mobile only) */}
-      <div className="fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary">
+      {/* Sticky Book/Contact bar (mobile only) — hidden on portal page where it would be redundant */}
+      {!isPortalPage && <div className="fixed bottom-0 left-0 right-0 z-40 md:hidden bg-fg-primary">
         <div className="flex gap-0">
           {/* Left: Contact Us -> /contact */}
           {cta_button?.secondary_label && ctaUrls.hasSecondary && (
@@ -392,7 +399,7 @@ export function HeaderNavigation({
             {(cta_button?.secondary_label && ctaUrls.hasSecondary) ? cta_button.secondary_label : (cta_button?.label || 'Contact')}
           </Button>
         </div>
-      </div>
+      </div>}
     </>
   );
 }

package/src/lib/cta-urls.ts

@@ -25,6 +25,22 @@ export interface ResolvedCtaUrls {
   hasSecondary: boolean;
 }
 
+/**
+ * Extracts the pathname from portal_url for use in client-side route comparisons.
+ * Handles both absolute URLs (https://domain.com/portal → /portal) and relative paths (/portal).
+ */
+export function resolvePortalPath(
+  companyInformation?: CompanyInformation | null
+): string | null {
+  const url = companyInformation?.portal_url?.trim();
+  if (!url) return null;
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url.startsWith('/') ? url : null;
+  }
+}
+
 export function resolveCtaUrls(
   companyInformation?: CompanyInformation | null
 ): ResolvedCtaUrls {

package/src/next/routes/form.ts

@@ -8,6 +8,22 @@
  * Env (server-side only):
  * - API_URL (default: http://localhost:3000/api/v1)
  * - API_KEY
+ *
+ * ## Meta Pixel + CAPI tracking for custom forms
+ *
+ * POST body must include `formType: 'lead'` for conversion tracking to fire:
+ *   - Server-side: the API automatically fires a CAPI Lead event (no extra work needed).
+ *   - Client-side: the response includes `eventId` for browser/server deduplication.
+ *     After a successful response, call these two functions from 'keystone-design-bootstrap/tracking':
+ *
+ *     const result = await response.json();
+ *     if (result.success) {
+ *       await setPixelUserData({ email, phone });               // hash + store identity for the session
+ *       firePixelEvent('Lead', undefined, result.eventId);      // fire fbq('track', 'Lead') with server event ID for dedup
+ *     }
+ *
+ * Both tracking calls are silent no-ops when no Meta Pixel is configured for the site.
+ * Non-lead form types (e.g. 'job_application') do not fire any tracking events.
  */
 
 // IMPORTANT:

package/src/next/routes/proxy-headers.ts

@@ -1,22 +1,44 @@
 /**
- * Extracts the real client IP and user-agent from an incoming Next.js route
- * request and returns them as headers to forward to the upstream Rails API.
+ * Extracts the real client IP, user-agent, and Meta browser cookies (_fbp / _fbc)
+ * from an incoming Next.js route request and returns them as headers to forward
+ * to the upstream Rails API.
  *
  * Cloudflare and other load-balancers set x-real-ip (or x-forwarded-for) on
  * inbound requests before they reach the Next.js function. Without this, the
  * Rails API sees the Next.js server IP instead of the real browser IP, which
  * produces inaccurate server-side CAPI signals.
  *
- * Convention: forwarded as X-Real-Client-IP / X-Real-Client-UA so that Rails
- * can read them explicitly without conflicting with its own proxy middleware.
+ * _fbp (Meta Browser ID) and _fbc (Meta Click ID) are first-party cookies set by
+ * the Meta Pixel. Forwarding them allows the API to store them on the Contact
+ * record so they can be included in all subsequent CAPI events — even those fired
+ * from background jobs that have no live HTTP request.
+ *
+ * Convention:
+ *   X-Real-Client-IP  — real browser IP
+ *   X-Real-Client-UA  — real browser user-agent
+ *   X-Meta-FBP        — value of the _fbp cookie
+ *   X-Meta-FBC        — value of the _fbc cookie (or built from fbclid param)
  */
 export function clientContextHeaders(request: Request): Record<string, string> {
   const ip =
     request.headers.get('x-real-ip') ||
     request.headers.get('x-forwarded-for')?.split(',')[0]?.trim();
   const ua = request.headers.get('user-agent');
+
+  const cookieHeader = request.headers.get('cookie') || '';
+  const cookies = Object.fromEntries(
+    cookieHeader.split(';').map((c) => {
+      const [k, ...v] = c.trim().split('=');
+      return [k, v.join('=')];
+    })
+  );
+  const fbp = cookies['_fbp'];
+  const fbc = cookies['_fbc'];
+
   const headers: Record<string, string> = {};
   if (ip) headers['X-Real-Client-IP'] = ip;
   if (ua) headers['X-Real-Client-UA'] = ua;
+  if (fbp) headers['X-Meta-FBP'] = fbp;
+  if (fbc) headers['X-Meta-FBC'] = fbc;
   return headers;
 }

package/src/tracking/firePixelEvent.ts

@@ -82,8 +82,13 @@ export async function setPixelUserData(userData: PixelUserData): Promise<void> {
  * Automatically applies any stored user identity before firing so that Meta
  * can match events to known users across the entire session.
  * Silently no-ops if fbq is not loaded (pixel not configured for this site).
+ *
+ * @param eventId - Optional server-side event ID for browser/server deduplication.
+ *   Pass the `eventId` returned by the form submission API so Meta can match and
+ *   deduplicate the browser Lead event against the server-side CAPI Lead event.
+ *   Format: fbq('track', event, params, { eventID: eventId })
  */
-export function firePixelEvent(event: PixelEvent, params?: PixelEventParams): void {
+export function firePixelEvent(event: PixelEvent, params?: PixelEventParams, eventId?: string): void {
   const fbq = getFbq();
   if (!fbq) {
     console.debug('[MetaPixel] skipped — fbq not loaded', { event });
@@ -98,6 +103,9 @@ export function firePixelEvent(event: PixelEvent, params?: PixelEventParams): vo
   if (params?.contentName) normalized.content_name = params.contentName;
   if (params?.contentCategory) normalized.content_category = params.contentCategory;
 
-  console.debug('[MetaPixel]', event, normalized);
-  fbq('track', event, Object.keys(normalized).length > 0 ? normalized : undefined);
+  const customData = Object.keys(normalized).length > 0 ? normalized : undefined;
+  const eventData = eventId ? { eventID: eventId } : undefined;
+
+  console.debug('[MetaPixel]', event, normalized, eventId ? { eventID: eventId } : '');
+  fbq('track', event, customData, eventData);
 }

package/src/tracking/index.ts

@@ -1,3 +1,23 @@
+/**
+ * Meta Pixel tracking utilities.
+ *
+ * Most events (PageView, ViewContent, InitiateCheckout) fire automatically via
+ * MetaPixel + MetaPixelTracker, which are mounted in KeystoneRootLayout.
+ *
+ * For custom forms, add two calls in your success handler:
+ *
+ *   import { firePixelEvent, setPixelUserData } from 'keystone-design-bootstrap/tracking';
+ *
+ *   await setPixelUserData({ email, phone }); // hash + store identity for the session
+ *   firePixelEvent('Lead');                   // fire fbq('track', 'Lead')
+ *
+ * Also make sure the form submits with `formType: 'lead'` so the server-side CAPI
+ * Lead event fires automatically. See 'keystone-design-bootstrap/next/routes/form'
+ * for the full tracking contract.
+ *
+ * All calls are silent no-ops when no Meta Pixel is configured for the site.
+ */
+
 export { MetaPixel } from './MetaPixel';
 export type { MetaPixelProps } from './MetaPixel';
 export { MetaPixelTracker } from './MetaPixelTracker';