keystone-design-bootstrap 1.0.51 → 1.0.54

package/package.json

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

package/src/design_system/sections/email-signup-section.tsx

@@ -0,0 +1,115 @@
+"use client";
+
+import React, { useRef, useState } from 'react';
+import { Form, Button } from '../elements';
+import { DynamicFormFields } from '../components/DynamicFormFields';
+import type { FormDefinition } from '../../types/api/form';
+import { useFormDefinitions } from '../../next/contexts/form-definitions';
+
+export interface EmailSignupSectionProps {
+    title?: string;
+    subtitle?: string;
+    buttonText?: string;
+    successMessage?: string;
+    /** Override the form definition (falls back to context). */
+    formDefinition?: FormDefinition | null;
+}
+
+export const EmailSignupSection = ({
+    title = "Stay in the loop",
+    subtitle = "Subscribe to our newsletter for updates, tips, and exclusive offers.",
+    buttonText = "Subscribe",
+    successMessage = "You're subscribed! Thank you.",
+    formDefinition,
+}: EmailSignupSectionProps) => {
+    const { marketingListSignupFormDefinition } = useFormDefinitions();
+    const resolvedFormDefinition = formDefinition ?? marketingListSignupFormDefinition;
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [submitStatus, setSubmitStatus] = useState<'idle' | 'success' | 'error'>('idle');
+    const [statusMessage, setStatusMessage] = useState('');
+    const formRef = useRef<HTMLFormElement>(null);
+
+    const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+        e.preventDefault();
+        setIsSubmitting(true);
+        setSubmitStatus('idle');
+        setStatusMessage('');
+
+        const formData = new FormData(e.currentTarget);
+        const data: Record<string, string> = { formType: 'marketing_list_signup' };
+        formData.forEach((value, key) => {
+            if (key.endsWith('_prefix')) return;
+            if (typeof value === 'string') data[key] = value;
+        });
+
+        try {
+            const response = await fetch('/api/form/', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(data),
+            });
+            const result = await response.json();
+
+            if (result.success) {
+                setSubmitStatus('success');
+                setStatusMessage(result.message || successMessage);
+                formRef.current?.reset();
+                setTimeout(() => setSubmitStatus('idle'), 6000);
+            } else {
+                setSubmitStatus('error');
+                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+            }
+        } catch {
+            setSubmitStatus('error');
+            setStatusMessage('Network error. Please try again later.');
+        }
+
+        setIsSubmitting(false);
+    };
+
+    if (!resolvedFormDefinition) return null;
+
+    return (
+        <section className="bg-secondary py-16 md:py-20">
+            <div className="mx-auto max-w-container px-4 md:px-8">
+                <div className="mx-auto max-w-xl text-center">
+                    <h2 className="font-display text-display-sm font-semibold text-primary md:text-display-md">
+                        {title}
+                    </h2>
+                    {subtitle && (
+                        <p className="mt-4 font-body text-lg text-tertiary">
+                            {subtitle}
+                        </p>
+                    )}
+                    <Form
+                        ref={formRef}
+                        onSubmit={handleSubmit}
+                        className="mt-8 flex flex-col gap-6 text-left"
+                    >
+                        <DynamicFormFields form={resolvedFormDefinition} />
+                        {submitStatus === 'success' && (
+                            <div className="rounded-lg bg-success-50 p-4 text-success-700">
+                                {statusMessage || successMessage}
+                            </div>
+                        )}
+                        {submitStatus === 'error' && (
+                            <div className="rounded-lg bg-error-50 p-4 text-error-700">
+                                {statusMessage}
+                            </div>
+                        )}
+                        <Button
+                            type="submit"
+                            color="primary"
+                            size="xl"
+                            isDisabled={isSubmitting}
+                            isLoading={isSubmitting}
+                            className="w-full"
+                        >
+                            {isSubmitting ? 'Subscribing...' : buttonText}
+                        </Button>
+                    </Form>
+                </div>
+            </div>
+        </section>
+    );
+};

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

@@ -30,13 +30,15 @@ export function HeaderNavigation({
   // Timeout ref for delayed dropdown closing
   const closeTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   
-  // Track scroll position for header animation
+  // Track scroll position for header animation; close dropdown on scroll to
+  // avoid a stale fixed `top` value creating a gap between the nav and dropdown.
   React.useEffect(() => {
     const handleScroll = () => {
       setIsScrolled(window.scrollY > 10);
+      setActiveDropdown(null);
     };
     
-    window.addEventListener('scroll', handleScroll);
+    window.addEventListener('scroll', handleScroll, { passive: true });
     return () => window.removeEventListener('scroll', handleScroll);
   }, []);
   
@@ -67,7 +69,8 @@ export function HeaderNavigation({
     }
   }, []);
 
-  // Open dropdown immediately
+  // Open dropdown immediately; clear it when hovering a childless item so the
+  // previous dropdown doesn't linger while a different top-level item is active.
   const handleMouseEnter = useCallback((item: NavItem, e: React.MouseEvent<HTMLDivElement>) => {
     cancelCloseTimeout();
     if (item.children && item.children.length > 0) {
@@ -77,6 +80,8 @@ export function HeaderNavigation({
         setDropdownTop(rect.bottom);
       }
       setActiveDropdown(item.label);
+    } else {
+      setActiveDropdown(null);
     }
   }, [cancelCloseTimeout]);
 

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

@@ -51,6 +51,8 @@ export function HeaderNavigation({
     cancelCloseTimeout();
     if (item.children && item.children.length > 0) {
       setActiveDropdown(item.label);
+    } else {
+      setActiveDropdown(null);
     }
   }, [cancelCloseTimeout]);
 

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

@@ -54,11 +54,14 @@ export function HeaderNavigation({
         }
     }, []);
 
-    // Open dropdown immediately
+    // Open dropdown immediately; clear it when hovering a childless item so the
+    // previous dropdown doesn't linger while a different top-level item is active.
     const handleMouseEnter = useCallback((item: NavItem) => {
         cancelCloseTimeout();
         if (item.children && item.children.length > 0) {
             setActiveDropdown(item.label);
+        } else {
+            setActiveDropdown(null);
         }
     }, [cancelCloseTimeout]);
 

package/src/design_system/sections/index.tsx

@@ -178,6 +178,10 @@ export const HomeHeroComponent = createThemedExport('home-hero-component', BaseH
 // Re-export application form (client component, no theme variants)
 export { JobApplicationForm } from './job-application-form';
 
+// Email / newsletter signup section (client component, no theme variants needed)
+export { EmailSignupSection } from './email-signup-section';
+export type { EmailSignupSectionProps } from './email-signup-section';
+
 // Service Menu: packages + treatments; nested specials as badges / modal callouts
 export { ServiceMenuSection } from './service-menu-section';
 export type { ServiceMenuSectionProps, PackagePublic } from './service-menu-section';

package/src/next/contexts/form-definitions.tsx

@@ -6,21 +6,24 @@ import type { FormDefinition } from '../../types/api/form';
 export type FormDefinitionsContextValue = {
   leadFormDefinition: FormDefinition | null;
   jobApplicationFormDefinition: FormDefinition | null;
+  marketingListSignupFormDefinition: FormDefinition | null;
 };
 
 const FormDefinitionsContext = createContext<FormDefinitionsContextValue>({
   leadFormDefinition: null,
   jobApplicationFormDefinition: null,
+  marketingListSignupFormDefinition: null,
 });
 
 export function FormDefinitionsProvider(props: {
   leadFormDefinition: FormDefinition | null;
   jobApplicationFormDefinition: FormDefinition | null;
+  marketingListSignupFormDefinition: FormDefinition | null;
   children: React.ReactNode;
 }) {
-  const { leadFormDefinition, jobApplicationFormDefinition, children } = props;
+  const { leadFormDefinition, jobApplicationFormDefinition, marketingListSignupFormDefinition, children } = props;
   return (
-    <FormDefinitionsContext.Provider value={{ leadFormDefinition, jobApplicationFormDefinition }}>
+    <FormDefinitionsContext.Provider value={{ leadFormDefinition, jobApplicationFormDefinition, marketingListSignupFormDefinition }}>
       {children}
     </FormDefinitionsContext.Provider>
   );

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 } from '../../tracking';
+import { MetaPixel, MetaPixelTracker } from '../../tracking';
 import { ChatWidget } from '../../design_system/components/ChatWidget';
 import { FormDefinitionsProvider } from '../contexts/form-definitions';
 import { KeystoneSSRProvider } from '../providers/ssr-provider';
@@ -111,6 +111,7 @@ export async function KeystoneRootLayout(props: {
     teamMembersData,
     leadFormDefinition,
     jobApplicationFormDefinition,
+    marketingListSignupFormDefinition,
     adsConfig,
   ] =
     await Promise.all([
@@ -121,6 +122,7 @@ export async function KeystoneRootLayout(props: {
       getTeamMembers(),
       getForm('lead'),
       getForm('job_application'),
+      getForm('marketing_list_signup'),
       getAdsConfig(),
     ]);
 
@@ -157,11 +159,13 @@ export async function KeystoneRootLayout(props: {
     <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}

package/src/tracking/BookingCtaTracker.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+import { useEffect } from 'react';
+import { trackInitiateCheckout } from './trackInitiateCheckout';
+
+type Props = {
+  bookingUrl: string | null | undefined;
+};
+
+/**
+ * Drop into the root layout to fire Meta Pixel InitiateCheckout whenever a visitor
+ * clicks any anchor whose href points to the external booking URL.
+ * Uses document-level click delegation — no changes needed to individual buttons.
+ */
+export function BookingCtaTracker({ bookingUrl }: Props) {
+  useEffect(() => {
+    if (!bookingUrl) return;
+
+    const handleClick = (e: MouseEvent) => {
+      const anchor = (e.target as Element).closest('a');
+      if (!anchor) return;
+      if (anchor.href && anchor.href.startsWith(bookingUrl)) {
+        trackInitiateCheckout();
+      }
+    };
+
+    document.addEventListener('click', handleClick);
+    return () => document.removeEventListener('click', handleClick);
+  }, [bookingUrl]);
+
+  return null;
+}

package/src/tracking/MetaPixelTracker.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { trackViewContent } from './trackViewContent';
+import { trackInitiateCheckout } from './trackInitiateCheckout';
+
+type RouteRule = {
+  pattern: RegExp;
+  getParams: (match: RegExpMatchArray) => { contentName: string; contentCategory: string };
+};
+
+// Checked in order — first match wins. More specific patterns come first.
+const ROUTE_RULES: RouteRule[] = [
+  {
+    pattern: /^\/services\/(.+)$/,
+    getParams: ([, slug]) => ({ contentName: slugToTitle(slug), contentCategory: 'Service' }),
+  },
+  {
+    pattern: /^\/locations\/(.+)$/,
+    getParams: ([, slug]) => ({ contentName: slugToTitle(slug), contentCategory: 'Location' }),
+  },
+  {
+    pattern: /^\/services$/,
+    getParams: () => ({ contentName: 'Services', contentCategory: 'Services' }),
+  },
+  {
+    pattern: /^\/locations$/,
+    getParams: () => ({ contentName: 'Locations', contentCategory: 'Locations' }),
+  },
+  {
+    pattern: /^\/service-menu$/,
+    getParams: () => ({ contentName: 'Service Menu', contentCategory: 'Pricing' }),
+  },
+  {
+    pattern: /^\/faq$/,
+    getParams: () => ({ contentName: 'FAQ', contentCategory: 'FAQ' }),
+  },
+  {
+    pattern: /^\/contact$/,
+    getParams: () => ({ contentName: 'Contact', contentCategory: 'Contact' }),
+  },
+];
+
+function slugToTitle(slug: string): string {
+  return slug
+    .split('-')
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+type Props = {
+  /** External booking URL. When set, fires InitiateCheckout on any click targeting that URL. */
+  bookingUrl?: string | null;
+};
+
+/**
+ * Single client-side tracker placed once in KeystoneRootLayout.
+ * - Fires ViewContent on every route change for known page patterns.
+ * - Fires InitiateCheckout whenever a visitor clicks a link to the external booking URL.
+ */
+export function MetaPixelTracker({ bookingUrl }: Props) {
+  const pathname = usePathname();
+
+  useEffect(() => {
+    for (const rule of ROUTE_RULES) {
+      const match = pathname.match(rule.pattern);
+      if (match) {
+        const { contentName, contentCategory } = rule.getParams(match);
+        trackViewContent(contentName, contentCategory);
+        break;
+      }
+    }
+  }, [pathname]);
+
+  useEffect(() => {
+    if (!bookingUrl) return;
+
+    const handleClick = (e: MouseEvent) => {
+      const anchor = (e.target as Element).closest('a');
+      if (anchor?.href?.startsWith(bookingUrl)) {
+        trackInitiateCheckout();
+      }
+    };
+
+    document.addEventListener('click', handleClick);
+    return () => document.removeEventListener('click', handleClick);
+  }, [bookingUrl]);
+
+  return null;
+}

package/src/tracking/ViewContentTracker.tsx

@@ -0,0 +1,21 @@
+'use client';
+
+import { useEffect } from 'react';
+import { trackViewContent } from './trackViewContent';
+
+type Props = {
+  contentName?: string;
+  contentCategory?: string;
+};
+
+/**
+ * Drop into any server-rendered page to fire the Meta Pixel ViewContent event on mount.
+ * Renders nothing — purely a tracking side-effect component.
+ */
+export function ViewContentTracker({ contentName, contentCategory }: Props) {
+  useEffect(() => {
+    trackViewContent(contentName, contentCategory);
+  }, [contentName, contentCategory]);
+
+  return null;
+}

package/src/tracking/index.ts

@@ -1,3 +1,9 @@
 export { MetaPixel } from './MetaPixel';
 export type { MetaPixelProps } from './MetaPixel';
 export { trackMetaLead } from './trackMetaLead';
+export { trackViewContent } from './trackViewContent';
+export { trackInitiateCheckout } from './trackInitiateCheckout';
+export { MetaPixelTracker } from './MetaPixelTracker';
+// Kept for custom use — MetaPixelTracker covers the standard cases automatically.
+export { ViewContentTracker } from './ViewContentTracker';
+export { BookingCtaTracker } from './BookingCtaTracker';

package/src/tracking/trackInitiateCheckout.ts

@@ -0,0 +1,11 @@
+type FbqFn = (method: string, eventName: string, params?: object) => void;
+
+/**
+ * Fires the client-side Meta Pixel InitiateCheckout event.
+ * Call this when a visitor clicks a booking / scheduling button.
+ */
+export function trackInitiateCheckout(): void {
+  if (typeof window === 'undefined') return;
+  const fbq = (window as Window & { fbq?: FbqFn }).fbq;
+  if (fbq) fbq('track', 'InitiateCheckout');
+}

package/src/tracking/trackViewContent.ts

@@ -0,0 +1,15 @@
+type FbqFn = (method: string, eventName: string, params?: object) => void;
+
+/**
+ * Fires the client-side Meta Pixel ViewContent event.
+ * Call this on service/offer detail pages so Meta knows which content is most engaging.
+ */
+export function trackViewContent(contentName?: string, contentCategory?: string): void {
+  if (typeof window === 'undefined') return;
+  const fbq = (window as Window & { fbq?: FbqFn }).fbq;
+  if (!fbq) return;
+  const params: Record<string, string> = {};
+  if (contentName) params.content_name = contentName;
+  if (contentCategory) params.content_category = contentCategory;
+  fbq('track', 'ViewContent', params);
+}

package/src/types/api/form.ts

@@ -28,4 +28,4 @@ export interface FormDefinition {
   updated_at?: string;
 }
 
-export type FormType = 'lead' | 'job_application';
+export type FormType = 'lead' | 'job_application' | 'marketing_list_signup';