keystone-design-bootstrap 1.0.64 → 1.0.65

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.65",
   "description": "Keystone Design Bootstrap - Sections, Elements, and Theme System for customer websites",
   "type": "module",
   "main": "./src/index.ts",

package/src/design_system/portal/PortalPage.tsx

@@ -575,7 +575,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 +595,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 +646,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 +690,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>

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,6 +3,7 @@
 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';
@@ -58,6 +59,16 @@ 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 = (() => {
+    const url = companyInformation?.portal_url?.trim();
+    if (!url) return null;
+    try { return new URL(url).pathname; } catch { return url.startsWith('/') ? url : null; }
+  })();
+  const isPortalPage = portalPath ? pathname?.startsWith(portalPath) : false;
+
   // Cancel any pending close timeout
   const cancelCloseTimeout = useCallback(() => {
     if (closeTimeoutRef.current) {
@@ -390,8 +401,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 +425,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,6 +3,7 @@
 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';
@@ -37,6 +38,16 @@ 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 = (() => {
+    const url = companyInformation?.portal_url?.trim();
+    if (!url) return null;
+    try { return new URL(url).pathname; } catch { return url.startsWith('/') ? url : null; }
+  })();
+  const isPortalPage = portalPath ? pathname?.startsWith(portalPath) : false;
+
   const cancelCloseTimeout = useCallback(() => {
     if (closeTimeoutRef.current) {
       clearTimeout(closeTimeoutRef.current);
@@ -301,8 +312,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 +337,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,6 +3,7 @@
 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';
@@ -43,6 +44,16 @@ 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 = (() => {
+      const url = companyInformation?.portal_url?.trim();
+      if (!url) return null;
+      try { return new URL(url).pathname; } catch { return url.startsWith('/') ? url : null; }
+    })();
+    const isPortalPage = portalPath ? pathname?.startsWith(portalPath) : false;
+
     // Cancel any pending close timeout
     const cancelCloseTimeout = useCallback(() => {
         if (closeTimeoutRef.current) {
@@ -343,8 +354,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 +378,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";
@@ -108,6 +109,16 @@ 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 = (() => {
+    const url = companyInformation?.portal_url?.trim();
+    if (!url) return null;
+    try { return new URL(url).pathname; } catch { return url.startsWith('/') ? url : null; }
+  })();
+  const isPortalPage = portalPath ? pathname?.startsWith(portalPath) : false;
+
   const getVariantClasses = () => {
     switch (variant) {
       case 'minimal':
@@ -366,8 +377,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 +403,7 @@ export function HeaderNavigation({
             {(cta_button?.secondary_label && ctaUrls.hasSecondary) ? cta_button.secondary_label : (cta_button?.label || 'Contact')}
           </Button>
         </div>
-      </div>
+      </div>}
     </>
   );
 }

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';