keystone-design-bootstrap 1.0.66 → 1.0.69

package/src/design_system/sections/job-application-form.barelux.tsx

@@ -5,6 +5,7 @@ import { Form, Button } from '../elements';
 import { DynamicFormFields } from '../components/DynamicFormFields';
 import type { FormDefinition } from '../../types/api/form';
 import { useFormDefinitions } from '../../next/contexts/form-definitions';
+import { captureEvent } from '../../tracking/captureEvent';
 
 interface JobApplicationFormBareluxProps {
     jobSlug: string;
@@ -47,14 +48,18 @@ export const JobApplicationForm = ({ jobSlug, formDefinition, inline = false }:
                 setSubmitStatus('success');
                 setStatusMessage(result.message || "Thank you for applying! We'll be in touch soon.");
                 formRef.current?.reset();
+                captureEvent('form_submitted', { form_type: 'job_application' });
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
+                const errorMsg = result.error || 'Something went wrong. Please try again.';
                 setSubmitStatus('error');
-                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+                setStatusMessage(errorMsg);
+                captureEvent('form_failed', { form_type: 'job_application', error: errorMsg });
             }
         } catch {
             setSubmitStatus('error');
             setStatusMessage('Network error. Please try again.');
+            captureEvent('form_failed', { form_type: 'job_application', error: 'network_error' });
         }
         setIsSubmitting(false);
     };

package/src/design_system/sections/job-application-form.tsx

@@ -5,6 +5,7 @@ import { Form, Button } from '../elements';
 import { DynamicFormFields } from '../components/DynamicFormFields';
 import type { FormDefinition } from '../../types/api/form';
 import { useFormDefinitions } from '../../next/contexts/form-definitions';
+import { captureEvent } from '../../tracking/captureEvent';
 
 interface JobApplicationFormProps {
     jobSlug: string;
@@ -50,14 +51,18 @@ export const JobApplicationForm = ({ jobSlug, formDefinition, inline = false }:
                 setSubmitStatus('success');
                 setStatusMessage(result.message || "Thank you for applying! We'll be in touch soon.");
                 formRef.current?.reset();
+                captureEvent('form_submitted', { form_type: 'job_application' });
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
+                const errorMsg = result.error || 'Something went wrong. Please try again.';
                 setSubmitStatus('error');
-                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+                setStatusMessage(errorMsg);
+                captureEvent('form_failed', { form_type: 'job_application', error: errorMsg });
             }
         } catch {
             setSubmitStatus('error');
             setStatusMessage('Network error. Please try again.');
+            captureEvent('form_failed', { form_type: 'job_application', error: 'network_error' });
         }
         setIsSubmitting(false);
     };

package/src/lib/cta-urls.ts

@@ -28,17 +28,28 @@ export interface ResolvedCtaUrls {
 /**
  * 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).
+ *
+ * Returns null when:
+ *  - portal_url is not set
+ *  - the URL cannot be resolved to a non-root pathname (would otherwise match every page)
  */
 export function resolvePortalPath(
   companyInformation?: CompanyInformation | null
 ): string | null {
   const url = companyInformation?.portal_url?.trim();
   if (!url) return null;
+
+  let pathname: string | null = null;
   try {
-    return new URL(url).pathname;
+    pathname = new URL(url).pathname;
   } catch {
-    return url.startsWith('/') ? url : null;
+    pathname = url.startsWith('/') ? url : null;
   }
+
+  if (!pathname || pathname === '/') return null;
+
+  // Normalize trailing slash so startsWith comparisons are consistent.
+  return pathname.endsWith('/') ? pathname.slice(0, -1) : pathname;
 }
 
 export function resolveCtaUrls(

package/src/lib/server-api.ts

@@ -78,6 +78,24 @@ export function getMetaPixelId(adsConfig: { meta_pixel_id?: string } | null | un
   return str !== '' && str !== 'null' && /^\d+$/.test(str) ? str : null;
 }
 
+export type AnalyticsConfig = {
+  /** PostHog project API key — platform-wide, from POSTHOG_API_KEY env var on the Rails server. */
+  posthog_api_key?: string;
+};
+
+/** Analytics config for customer sites. Returns platform-wide analytics keys (e.g. PostHog). */
+export async function getAnalyticsConfig(): Promise<AnalyticsConfig | null> {
+  const data = await serverFetch<AnalyticsConfig>('/public/analytics_config', defaultOptions);
+  return data ?? null;
+}
+
+/** Extract PostHog API key from analytics config for use with <PostHogProvider apiKey={...} />. */
+export function getPostHogApiKey(analyticsConfig: AnalyticsConfig | null | undefined): string | null {
+  const key = analyticsConfig?.posthog_api_key;
+  const str = key != null && key !== '' ? String(key).trim() : '';
+  return str !== '' && str !== 'null' ? str : null;
+}
+
 export async function getServices(): Promise<Service[] | null> {
   return serverFetch<Service[]>('/public/services', defaultOptions);
 }

package/src/next/layouts/root-layout.tsx

@@ -3,7 +3,7 @@ import type { Metadata } from 'next';
 
 import { HeaderNavigation, FooterHome } from '../../design_system/sections';
 import { ThemeProvider } from '../../contexts';
-import { MetaPixel, MetaPixelTracker } from '../../tracking';
+import { MetaPixel, MetaPixelTracker, PostHogProvider, KeystoneAnalyticsTracker } from '../../tracking';
 import { ChatWidget } from '../../design_system/components/ChatWidget';
 import { FormDefinitionsProvider } from '../contexts/form-definitions';
 import { KeystoneSSRProvider } from '../providers/ssr-provider';
@@ -16,6 +16,8 @@ import {
   getForm,
   getAdsConfig,
   getMetaPixelId,
+  getAnalyticsConfig,
+  getPostHogApiKey,
 } from '../../lib/server-api';
 
 import type { CompanyInformation, Location, NavItem, Service, SiteConfig } from '../../types';
@@ -35,6 +37,13 @@ export type KeystoneRootLayoutOptions = {
   headerOverrides?: KeystoneRootLayoutHeaderOverrides;
   /** Chat widget position */
   chatPosition?: 'bottom-right' | 'bottom-left';
+  /**
+   * PostHog ingest host. Defaults to `https://us.i.posthog.com`.
+   * Override when self-hosting or using the EU cloud (`https://eu.i.posthog.com`).
+   * The API key is fetched automatically from the Rails analytics_config endpoint
+   * (set POSTHOG_API_KEY on the Rails server — no client-side env var needed).
+   */
+  posthogHost?: string;
 };
 
 function buildNavigationWithDynamicData(
@@ -91,7 +100,7 @@ function buildNavigationWithDynamicData(
  * Note: Next's `export const metadata` must remain in the site/app.
  * This component focuses on:
  * - fetching shared data
- * - injecting Meta Pixel
+ * - injecting Meta Pixel (from ads_config) and PostHog (from analytics_config)
  * - applying theme
  * - rendering Header + Footer
  * - rendering ChatWidget gated by `companyInformation.chat_enabled`
@@ -113,6 +122,7 @@ export async function KeystoneRootLayout(props: {
     jobApplicationFormDefinition,
     marketingListSignupFormDefinition,
     adsConfig,
+    analyticsConfig,
   ] =
     await Promise.all([
       getCompanyInformation(),
@@ -124,9 +134,11 @@ export async function KeystoneRootLayout(props: {
       getForm('job_application'),
       getForm('marketing_list_signup'),
       getAdsConfig(),
+      getAnalyticsConfig(),
     ]);
 
   const metaPixelId = getMetaPixelId(adsConfig);
+  const posthogApiKey = getPostHogApiKey(analyticsConfig);
 
   const services = Array.isArray(servicesData) ? servicesData : [];
   const locations = Array.isArray(locationsData) ? locationsData : [];
@@ -137,12 +149,15 @@ export async function KeystoneRootLayout(props: {
   const theme = config.site.theme;
 
   const ci = companyInformation as CompanyInformation | null;
+  const accountId = ci?.id ?? undefined;
+  const accountName = ci?.company_name ?? undefined;
   const externalManagementUrl = ci?.external_management_url?.trim() || null;
   const portalUrl = ci?.portal_url?.trim() || null;
   const bookingHref = portalUrl ?? externalManagementUrl ?? null;
   const chatEnabled = Boolean(ci?.chat_enabled);
 
   const headerOverrides = options?.headerOverrides;
+  const posthogHost = options?.posthogHost?.trim() || undefined;
   const headerProps = {
     logo: {
       href: headerOverrides?.logoHref || '/',
@@ -154,40 +169,58 @@ export async function KeystoneRootLayout(props: {
     },
   };
 
+  const bodyContent = (
+    <>
+      {metaPixelId ? <MetaPixel pixelId={metaPixelId} /> : null}
+      {metaPixelId ? <MetaPixelTracker bookingUrl={externalManagementUrl} /> : null}
+      <ThemeProvider theme={theme}>
+        <KeystoneSSRProvider>
+          <FormDefinitionsProvider
+            leadFormDefinition={leadFormDefinition ?? null}
+            jobApplicationFormDefinition={jobApplicationFormDefinition ?? null}
+            marketingListSignupFormDefinition={marketingListSignupFormDefinition ?? null}
+          >
+            <HeaderNavigation
+              config={dynamicConfig}
+              companyInformation={companyInformation}
+              websitePhotos={websitePhotos}
+              props={headerProps}
+              logoText={headerOverrides?.logoText}
+            />
+            {children}
+            <FooterHome
+              config={dynamicConfig}
+              companyInformation={companyInformation}
+              websitePhotos={websitePhotos}
+            />
+            {chatEnabled ? (
+              <ChatWidget
+                position={options?.chatPosition || 'bottom-right'}
+                teamMembers={teamMembers}
+              />
+            ) : null}
+          </FormDefinitionsProvider>
+        </KeystoneSSRProvider>
+      </ThemeProvider>
+    </>
+  );
+
   return (
     <html lang="en" data-theme={theme}>
       <body>
-        {metaPixelId ? <MetaPixel pixelId={metaPixelId} /> : null}
-        {metaPixelId ? <MetaPixelTracker bookingUrl={externalManagementUrl} /> : null}
-        <ThemeProvider theme={theme}>
-          <KeystoneSSRProvider>
-            <FormDefinitionsProvider
-              leadFormDefinition={leadFormDefinition ?? null}
-              jobApplicationFormDefinition={jobApplicationFormDefinition ?? null}
-              marketingListSignupFormDefinition={marketingListSignupFormDefinition ?? null}
-            >
-              <HeaderNavigation
-                config={dynamicConfig}
-                companyInformation={companyInformation}
-                websitePhotos={websitePhotos}
-                props={headerProps}
-                logoText={headerOverrides?.logoText}
-              />
-              {children}
-              <FooterHome
-                config={dynamicConfig}
-                companyInformation={companyInformation}
-                websitePhotos={websitePhotos}
-              />
-              {chatEnabled ? (
-                <ChatWidget
-                  position={options?.chatPosition || 'bottom-right'}
-                  teamMembers={teamMembers}
-                />
-              ) : null}
-            </FormDefinitionsProvider>
-          </KeystoneSSRProvider>
-        </ThemeProvider>
+        {posthogApiKey ? (
+          <PostHogProvider
+            apiKey={posthogApiKey}
+            apiHost={posthogHost}
+            accountId={accountId}
+            accountName={accountName}
+          >
+            <KeystoneAnalyticsTracker bookingUrl={bookingHref} />
+            {bodyContent}
+          </PostHogProvider>
+        ) : (
+          bodyContent
+        )}
       </body>
     </html>
   );

package/src/tracking/KeystoneAnalyticsTracker.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { captureEvent } from './captureEvent';
+
+type Props = {
+  /** External booking / portal URL. When set, fires booking_cta_clicked on any click to that URL. */
+  bookingUrl?: string | null;
+};
+
+/**
+ * Page-level PostHog event tracker. Mount once inside PostHogProvider in
+ * KeystoneRootLayout alongside MetaPixelTracker.
+ *
+ * Responsibilities:
+ * - booking_cta_clicked: fires when any link to the booking URL is clicked,
+ *   capturing the page the visitor was on when they clicked.
+ */
+export function KeystoneAnalyticsTracker({ bookingUrl }: Props) {
+  const pathname = usePathname();
+
+  useEffect(() => {
+    if (!bookingUrl) return;
+
+    const handleClick = (e: MouseEvent) => {
+      const anchor = (e.target as Element).closest('a');
+      if (anchor?.href?.startsWith(bookingUrl)) {
+        captureEvent('booking_cta_clicked', {
+          source_path: pathname,
+          booking_url: bookingUrl,
+        });
+      }
+    };
+
+    document.addEventListener('click', handleClick);
+    return () => document.removeEventListener('click', handleClick);
+  }, [bookingUrl, pathname]);
+
+  return null;
+}

package/src/tracking/PostHogProvider.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import posthog from 'posthog-js';
+import { PostHogProvider as PHProvider } from 'posthog-js/react';
+import { useEffect, Suspense } from 'react';
+import { usePathname, useSearchParams } from 'next/navigation';
+
+const DEFAULT_HOST = 'https://us.i.posthog.com';
+
+export type PostHogProviderProps = {
+  apiKey: string;
+  apiHost?: string;
+  /** Keystone account ID — attached to every event as a super property. */
+  accountId?: number;
+  /** Keystone account name (company_name) — attached to every event as a super property. */
+  accountName?: string;
+  children: React.ReactNode;
+};
+
+// ---------------------------------------------------------------------------
+// Page name resolution
+// ---------------------------------------------------------------------------
+
+type PageInfo = { page_name: string; page_slug?: string };
+
+function resolvePageInfo(pathname: string): PageInfo {
+  if (pathname === '/') return { page_name: 'home' };
+
+  const patterns: Array<[RegExp, (m: RegExpMatchArray) => PageInfo]> = [
+    [/^\/services\/(.+)$/, ([, slug]) => ({ page_name: 'service_detail', page_slug: slug })],
+    [/^\/locations\/(.+)$/, ([, slug]) => ({ page_name: 'location_detail', page_slug: slug })],
+    [/^\/blog\/(.+)$/, ([, slug]) => ({ page_name: 'blog_post', page_slug: slug })],
+    [/^\/jobs\/(.+)$/, ([, slug]) => ({ page_name: 'job_detail', page_slug: slug })],
+    [/^\/packages\/(.+)$/, ([, slug]) => ({ page_name: 'package_detail', page_slug: slug })],
+  ];
+
+  for (const [pattern, resolve] of patterns) {
+    const match = pathname.match(pattern);
+    if (match) return resolve(match);
+  }
+
+  const staticNames: Record<string, string> = {
+    '/services': 'services',
+    '/locations': 'locations',
+    '/contact': 'contact',
+    '/about': 'about',
+    '/blog': 'blog',
+    '/portal': 'portal',
+    '/gallery': 'gallery',
+    '/team': 'team',
+    '/faq': 'faq',
+    '/reviews': 'reviews',
+    '/jobs': 'jobs',
+    '/packages': 'packages',
+    '/service-menu': 'service_menu',
+    '/privacy-policy': 'privacy_policy',
+    '/terms': 'terms_of_service',
+  };
+
+  return { page_name: staticNames[pathname] ?? 'unknown' };
+}
+
+// ---------------------------------------------------------------------------
+// Pageview tracker — must be wrapped in <Suspense> (useSearchParams)
+// ---------------------------------------------------------------------------
+
+function PostHogPageviewTracker() {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  useEffect(() => {
+    if (!pathname) return;
+
+    const search = searchParams?.toString();
+    const url = window.location.origin + pathname + (search ? `?${search}` : '');
+    const { page_name, page_slug } = resolvePageInfo(pathname);
+
+    posthog.capture('$pageview', {
+      $current_url: url,
+      page_name,
+      page_path: pathname,
+      ...(page_slug && { page_slug }),
+    });
+  }, [pathname, searchParams]);
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialises PostHog, registers account-level super properties, and fires
+ * an enriched `$pageview` on every App Router navigation.
+ *
+ * Super properties attached to every event automatically:
+ *   - account_id    (Keystone account ID)
+ *   - account_name  (company_name)
+ *   - site_domain   (window.location.hostname)
+ *
+ * Mount once in the root layout body. One project key covers all customer
+ * sites — filter by account_name or site_domain in the PostHog dashboard.
+ */
+export function PostHogProvider({ apiKey, apiHost, accountId, accountName, children }: PostHogProviderProps) {
+  useEffect(() => {
+    posthog.init(apiKey, {
+      api_host: apiHost ?? DEFAULT_HOST,
+      person_profiles: 'identified_only',
+      capture_pageview: false,
+    });
+
+    posthog.register({
+      ...(accountId !== undefined && { account_id: accountId }),
+      ...(accountName && { account_name: accountName }),
+      site_domain: window.location.hostname,
+    });
+  }, [apiKey, apiHost, accountId, accountName]);
+
+  return (
+    <PHProvider client={posthog}>
+      <Suspense fallback={null}>
+        <PostHogPageviewTracker />
+      </Suspense>
+      {children}
+    </PHProvider>
+  );
+}

package/src/tracking/captureEvent.ts

@@ -0,0 +1,140 @@
+/**
+ * PostHog event capture — Keystone customer sites.
+ *
+ * ## Naming convention
+ * All events use snake_case `object_action` format.
+ * Properties use snake_case as well.
+ *
+ * ## Event taxonomy
+ * Add new events here: define the name in `KsEventName` and its required
+ * properties in `KsEventProperties`. Every callsite is then type-checked.
+ *
+ * ## Usage
+ *
+ *   import { captureEvent } from 'keystone-design-bootstrap/tracking';
+ *
+ *   captureEvent('form_submitted', { form_type: 'lead' });
+ *   captureEvent('booking_cta_clicked', { source_path: '/services/massage', booking_url: url });
+ *
+ * All calls are safe no-ops when PostHog has not been initialised (e.g. no
+ * POSTHOG_API_KEY configured on the server).
+ *
+ * ## Super properties
+ * account_id, account_name, and site_domain are registered as super properties
+ * by PostHogProvider and are automatically attached to every event — you do not
+ * need to include them in individual captureEvent calls.
+ */
+
+import posthog from 'posthog-js';
+
+// ---------------------------------------------------------------------------
+// Event taxonomy
+// ---------------------------------------------------------------------------
+
+export type KsEventName =
+  // Navigation
+  | 'page_viewed'
+  // Booking / conversion
+  | 'booking_cta_clicked'
+  // Forms
+  | 'form_submitted'
+  | 'form_failed'
+  // Chat widget
+  | 'chat_opened'
+  | 'chat_message_sent'
+  | 'chat_message_failed'
+  // Member portal — tab navigation
+  | 'portal_tab_viewed'
+  // Member portal — authentication flow
+  | 'portal_login_started'
+  | 'portal_login_identified'
+  | 'portal_login_completed'
+  | 'portal_login_failed';
+
+export type KsEventProperties = {
+  /** Fired on every page navigation. $pageview is also fired for PostHog web analytics. */
+  page_viewed: {
+    page_name: string;
+    page_path: string;
+    page_slug?: string;
+  };
+
+  /** Fired when a visitor clicks any CTA that links to the external booking URL. */
+  booking_cta_clicked: {
+    source_path: string;
+    booking_url: string;
+  };
+
+  /** Fired when a Keystone form is successfully submitted. */
+  form_submitted: {
+    /** One of: lead | job_application | marketing_list_signup */
+    form_type: string;
+    /** Server-generated event ID for CAPI deduplication (when present). */
+    event_id?: string;
+  };
+
+  /** Fired when a form submission fails (validation error or network error). */
+  form_failed: {
+    form_type: string;
+    error: string;
+  };
+
+  /** Fired when the chat widget is first opened by the visitor. */
+  chat_opened: Record<string, never>;
+
+  /** Fired when a chat message is successfully sent. */
+  chat_message_sent: {
+    /** Whether the visitor is authenticated (contactId present). */
+    is_authenticated: boolean;
+  };
+
+  /** Fired when a chat message fails to send. */
+  chat_message_failed: {
+    error: string;
+  };
+
+  /** Fired when a member portal tab is opened. */
+  portal_tab_viewed: {
+    tab: string;
+  };
+
+  /** Fired when the portal login modal is opened / login flow starts. */
+  portal_login_started: Record<string, never>;
+
+  /**
+   * Fired after the identifier step resolves — we know whether the user
+   * already has an account.
+   */
+  portal_login_identified: {
+    method: 'email' | 'phone' | 'email_and_phone';
+    user_exists: boolean;
+  };
+
+  /** Fired after the user successfully signs in or creates an account. */
+  portal_login_completed: {
+    flow: 'signin' | 'signup';
+  };
+
+  /** Fired when any step of the login flow returns an error. */
+  portal_login_failed: {
+    step: 'identifier' | 'signin' | 'signup';
+    reason: string;
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Capture helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Captures a typed Keystone analytics event via PostHog.
+ * Safe no-op when PostHog has not been initialised.
+ */
+export function captureEvent<E extends KsEventName>(
+  event: E,
+  ...args: KsEventProperties[E] extends Record<string, never>
+    ? []
+    : [properties: KsEventProperties[E]]
+): void {
+  posthog.capture(event, args[0] as Record<string, unknown>);
+}

package/src/tracking/index.ts

@@ -23,3 +23,8 @@ export type { MetaPixelProps } from './MetaPixel';
 export { MetaPixelTracker } from './MetaPixelTracker';
 export { firePixelEvent, setPixelUserData } from './firePixelEvent';
 export type { PixelEvent, PixelEventParams, PixelUserData } from './firePixelEvent';
+export { PostHogProvider } from './PostHogProvider';
+export type { PostHogProviderProps } from './PostHogProvider';
+export { KeystoneAnalyticsTracker } from './KeystoneAnalyticsTracker';
+export { captureEvent } from './captureEvent';
+export type { KsEventName, KsEventProperties } from './captureEvent';