@bailierich/booking-components 2.0.0

package/docs/CALLBACKS.md

@@ -0,0 +1,760 @@
+# Callback Patterns & Event Handling
+
+Guide to implementing callbacks, event handlers, and data flow in `@oviah/booking-components`.
+
+## Table of Contents
+
+- [BookingFlow Callbacks](#bookingflow-callbacks)
+- [Step Component Callbacks](#step-component-callbacks)
+- [Section Interactions](#section-interactions)
+- [Payment Callbacks](#payment-callbacks)
+- [Error Handling](#error-handling)
+- [Best Practices](#best-practices)
+
+---
+
+## BookingFlow Callbacks
+
+### onComplete
+
+Called when the booking flow is completed and the user confirms their booking.
+
+```typescript
+interface BookingData {
+  service: string | null;
+  date: string | null;
+  time: string | null;
+  addons: string[];
+  contact: ContactInfo;
+  optIn?: any;
+}
+
+const handleComplete = async (bookingData: BookingData) => {
+  try {
+    // 1. Validate data
+    if (!bookingData.service || !bookingData.date || !bookingData.time) {
+      throw new Error('Missing required booking information');
+    }
+
+    // 2. Submit to backend
+    const response = await fetch('/api/bookings', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(bookingData)
+    });
+
+    if (!response.ok) {
+      throw new Error('Failed to create booking');
+    }
+
+    const booking = await response.json();
+
+    // 3. Show success message
+    toast.success('Booking confirmed!');
+
+    // 4. Redirect to confirmation page
+    router.push(`/booking/confirmation/${booking.id}`);
+
+  } catch (error) {
+    console.error('Booking error:', error);
+    toast.error('Failed to complete booking. Please try again.');
+  }
+};
+
+<BookingFlow
+  config={config}
+  colors={colors}
+  onComplete={handleComplete}
+/>
+```
+
+---
+
+### onStepChange
+
+Called whenever the user navigates between steps.
+
+```typescript
+const handleStepChange = (stepIndex: number, stepId: string) => {
+  // Track analytics
+  analytics.track('Booking Step Changed', {
+    stepIndex,
+    stepId,
+    timestamp: new Date().toISOString()
+  });
+
+  // Update URL (optional)
+  const searchParams = new URLSearchParams(window.location.search);
+  searchParams.set('step', stepId);
+  router.replace(`?${searchParams.toString()}`, { scroll: false });
+
+  // Save progress (optional)
+  localStorage.setItem('bookingProgress', JSON.stringify({
+    currentStep: stepIndex,
+    timestamp: Date.now()
+  }));
+};
+
+<BookingFlow
+  config={config}
+  colors={colors}
+  onStepChange={handleStepChange}
+/>
+```
+
+---
+
+### validateStep
+
+Custom validation for each step before allowing navigation to the next step.
+
+```typescript
+const validateStep = (stepId: string, data: any): boolean => {
+  switch (stepId) {
+    case 'service':
+      // Ensure service is selected
+      if (!data.service) {
+        toast.error('Please select a service');
+        return false;
+      }
+      return true;
+
+    case 'date':
+      // Ensure date is in the future
+      if (!data.date) {
+        toast.error('Please select a date');
+        return false;
+      }
+      const selectedDate = new Date(data.date);
+      if (selectedDate < new Date()) {
+        toast.error('Please select a future date');
+        return false;
+      }
+      return true;
+
+    case 'time':
+      // Ensure time is selected
+      if (!data.time) {
+        toast.error('Please select a time slot');
+        return false;
+      }
+      return true;
+
+    case 'details':
+      // Validate contact information
+      const { name, email, phone } = data.contact || {};
+
+      if (!name || name.trim().length < 2) {
+        toast.error('Please enter your name');
+        return false;
+      }
+
+      if (!email || !isValidEmail(email)) {
+        toast.error('Please enter a valid email address');
+        return false;
+      }
+
+      if (!phone || !isValidPhone(phone)) {
+        toast.error('Please enter a valid phone number');
+        return false;
+      }
+
+      return true;
+
+    default:
+      return true;
+  }
+};
+
+<BookingFlow
+  config={config}
+  colors={colors}
+  validateStep={validateStep}
+/>
+```
+
+---
+
+## Step Component Callbacks
+
+### Service Selection
+
+```typescript
+import { ServiceSelection } from '@oviah/booking-components';
+
+const [selectedService, setSelectedService] = useState<string | null>(null);
+
+const handleServiceSelect = (serviceId: string) => {
+  // Update state
+  setSelectedService(serviceId);
+
+  // Track analytics
+  analytics.track('Service Selected', {
+    serviceId,
+    timestamp: new Date().toISOString()
+  });
+
+  // Fetch available dates for this service (optional)
+  fetchAvailableDates(serviceId).then(dates => {
+    setAvailableDates(dates);
+  });
+
+  // Update pricing display (optional)
+  const service = services.find(s => s.id === serviceId);
+  if (service) {
+    setEstimatedPrice(service.price);
+  }
+};
+
+<ServiceSelection
+  services={services}
+  categories={categories}
+  selectedService={selectedService}
+  onServiceSelect={handleServiceSelect}
+  settings={settings}
+  colors={colors}
+/>
+```
+
+---
+
+### Date Selection
+
+```typescript
+import { DateSelection } from '@oviah/booking-components';
+
+const [selectedDate, setSelectedDate] = useState<string | null>(null);
+const [availableTimes, setAvailableTimes] = useState<string[]>([]);
+
+const handleDateSelect = async (date: string) => {
+  // Update state
+  setSelectedDate(date);
+
+  // Fetch available time slots for this date
+  try {
+    const response = await fetch(`/api/availability?date=${date}&service=${selectedService}`);
+    const data = await response.json();
+    setAvailableTimes(data.times);
+  } catch (error) {
+    console.error('Failed to fetch time slots:', error);
+    toast.error('Failed to load available times');
+  }
+
+  // Track analytics
+  analytics.track('Date Selected', { date });
+};
+
+<DateSelection
+  availableDates={availableDates}
+  selectedDate={selectedDate}
+  onDateSelect={handleDateSelect}
+  settings={settings}
+  colors={colors}
+/>
+```
+
+---
+
+### Time Selection
+
+```typescript
+import { TimeSelection } from '@oviah/booking-components';
+
+const [selectedTime, setSelectedTime] = useState<string | null>(null);
+
+const handleTimeSelect = (time: string) => {
+  // Update state
+  setSelectedTime(time);
+
+  // Calculate end time
+  const serviceDuration = selectedServiceData?.duration || 60;
+  const endTime = calculateEndTime(time, serviceDuration);
+  setEstimatedEndTime(endTime);
+
+  // Track analytics
+  analytics.track('Time Selected', {
+    time,
+    endTime,
+    duration: serviceDuration
+  });
+};
+
+<TimeSelection
+  availableTimes={availableTimes}
+  selectedTime={selectedTime}
+  onTimeSelect={handleTimeSelect}
+  serviceDuration={selectedServiceData?.duration}
+  settings={settings}
+  colors={colors}
+/>
+```
+
+---
+
+### Addons Selection
+
+```typescript
+import { AddonsSelection } from '@oviah/booking-components';
+
+const [selectedAddons, setSelectedAddons] = useState<string[]>([]);
+const [totalPrice, setTotalPrice] = useState(0);
+
+const handleAddonsChange = (addonIds: string[]) => {
+  // Update state
+  setSelectedAddons(addonIds);
+
+  // Calculate total price
+  const basePrice = selectedServiceData?.price || 0;
+  const addonsPrice = addonIds.reduce((sum, id) => {
+    const addon = addons.find(a => a.id === id);
+    return sum + (addon?.price || 0);
+  }, 0);
+  const total = basePrice + addonsPrice;
+  setTotalPrice(total);
+
+  // Calculate total duration
+  const baseDuration = selectedServiceData?.duration || 0;
+  const addonsDuration = addonIds.reduce((sum, id) => {
+    const addon = addons.find(a => a.id === id);
+    return sum + (addon?.duration || 0);
+  }, 0);
+  const totalDuration = baseDuration + addonsDuration;
+  setEstimatedDuration(totalDuration);
+
+  // Track analytics
+  analytics.track('Addons Changed', {
+    addonIds,
+    totalPrice: total,
+    totalDuration
+  });
+};
+
+<AddonsSelection
+  addons={addons}
+  selectedAddons={selectedAddons}
+  onAddonsChange={handleAddonsChange}
+  settings={settings}
+  colors={colors}
+/>
+```
+
+---
+
+### Contact Form
+
+```typescript
+import { ContactForm } from '@oviah/booking-components';
+
+const [contactInfo, setContactInfo] = useState({
+  name: '',
+  email: '',
+  phone: '',
+  notes: ''
+});
+
+const [optInData, setOptInData] = useState<any>({});
+
+const handleContactInfoChange = (info: any) => {
+  // Update state
+  setContactInfo(info);
+
+  // Validate in real-time (optional)
+  validateContactInfo(info);
+
+  // Save to localStorage (optional)
+  localStorage.setItem('bookingContact', JSON.stringify(info));
+};
+
+const handleOptInData = (data: any) => {
+  // Store opt-in module data
+  setOptInData(data);
+
+  // Track that user opted in
+  analytics.track('Opt-In Completed', {
+    moduleId: data.moduleId,
+    timestamp: new Date().toISOString()
+  });
+};
+
+<ContactForm
+  contactInfo={contactInfo}
+  onContactInfoChange={handleContactInfoChange}
+  optInModules={optInModules}
+  onOptInData={handleOptInData}
+  settings={settings}
+  colors={colors}
+/>
+```
+
+---
+
+### Confirmation
+
+```typescript
+import { Confirmation } from '@oviah/booking-components';
+
+const handleConfirm = async () => {
+  try {
+    // 1. Create booking
+    const bookingResponse = await fetch('/api/bookings', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        serviceId: selectedService,
+        date: selectedDate,
+        time: selectedTime,
+        addonIds: selectedAddons,
+        contact: contactInfo,
+        optInData
+      })
+    });
+
+    if (!bookingResponse.ok) {
+      throw new Error('Failed to create booking');
+    }
+
+    const booking = await bookingResponse.json();
+
+    // 2. Process payment
+    const paymentResponse = await fetch('/api/payments/process', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        bookingId: booking.id,
+        amount: depositAmount,
+        paymentMethod: paymentMethodId
+      })
+    });
+
+    if (!paymentResponse.ok) {
+      // Rollback booking
+      await fetch(`/api/bookings/${booking.id}`, { method: 'DELETE' });
+      throw new Error('Payment failed');
+    }
+
+    const payment = await paymentResponse.json();
+
+    // 3. Send confirmation email
+    await fetch('/api/emails/booking-confirmation', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        bookingId: booking.id,
+        email: contactInfo.email
+      })
+    });
+
+    // 4. Track conversion
+    analytics.track('Booking Completed', {
+      bookingId: booking.id,
+      paymentId: payment.id,
+      amount: depositAmount,
+      revenue: totalPrice
+    });
+
+    // 5. Redirect to success page
+    router.push(`/booking/success?id=${booking.id}`);
+
+  } catch (error) {
+    console.error('Confirmation error:', error);
+    toast.error('Failed to complete booking. Please try again.');
+  }
+};
+
+<Confirmation
+  service={selectedServiceData}
+  addons={selectedAddonsData}
+  selectedDate={selectedDate}
+  selectedTime={selectedTime}
+  contactInfo={contactInfo}
+  paymentProvider="square"
+  paymentConfig={{ depositPercentage: 20 }}
+  onConfirm={handleConfirm}
+  colors={colors}
+/>
+```
+
+---
+
+## Section Interactions
+
+Most section components are presentational, but some have interactive elements:
+
+### Navigation Links
+
+```typescript
+const handleNavClick = (url: string, linkType: 'internal' | 'external') => {
+  // Track click
+  analytics.track('Navigation Link Clicked', { url, linkType });
+
+  // Handle internal navigation
+  if (linkType === 'internal') {
+    router.push(url);
+  }
+  // External links handled automatically by anchor tag
+};
+```
+
+### CTA Buttons
+
+```typescript
+const handleCTAClick = (buttonText: string, url: string) => {
+  // Track conversion opportunity
+  analytics.track('CTA Clicked', { buttonText, url });
+
+  // Custom handling (e.g., open booking modal)
+  if (url === '#booking') {
+    openBookingModal();
+  } else {
+    router.push(url);
+  }
+};
+```
+
+---
+
+## Payment Callbacks
+
+### Square Payment
+
+```typescript
+const handleSquarePayment = async (paymentMethodId: string) => {
+  try {
+    const response = await fetch('/api/payments/square', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        paymentMethodId,
+        amount: depositAmount,
+        bookingId: booking.id
+      })
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.message || 'Payment failed');
+    }
+
+    const result = await response.json();
+    return result;
+
+  } catch (error) {
+    console.error('Square payment error:', error);
+    throw error;
+  }
+};
+```
+
+### Stripe Payment
+
+```typescript
+const handleStripePayment = async (paymentIntentId: string) => {
+  try {
+    const stripe = await loadStripe(process.env.NEXT_PUBLIC_STRIPE_KEY!);
+
+    const result = await stripe.confirmCardPayment(paymentIntentId, {
+      payment_method: {
+        card: cardElement,
+        billing_details: {
+          name: contactInfo.name,
+          email: contactInfo.email,
+          phone: contactInfo.phone
+        }
+      }
+    });
+
+    if (result.error) {
+      throw new Error(result.error.message);
+    }
+
+    return result.paymentIntent;
+
+  } catch (error) {
+    console.error('Stripe payment error:', error);
+    throw error;
+  }
+};
+```
+
+---
+
+## Error Handling
+
+### Global Error Handler
+
+```typescript
+const handleBookingError = (error: Error, context: string) => {
+  // Log error
+  console.error(`Booking error in ${context}:`, error);
+
+  // Track error
+  analytics.track('Booking Error', {
+    context,
+    error: error.message,
+    stack: error.stack
+  });
+
+  // Show user-friendly message
+  const userMessage = getUserFriendlyError(error);
+  toast.error(userMessage);
+
+  // Optional: Send to error tracking service
+  if (typeof window !== 'undefined' && window.Sentry) {
+    window.Sentry.captureException(error, {
+      tags: { context },
+      extra: { bookingData: getCurrentBookingData() }
+    });
+  }
+};
+
+const getUserFriendlyError = (error: Error): string => {
+  if (error.message.includes('network')) {
+    return 'Network error. Please check your connection and try again.';
+  }
+  if (error.message.includes('payment')) {
+    return 'Payment failed. Please check your payment details.';
+  }
+  return 'Something went wrong. Please try again or contact support.';
+};
+```
+
+### Step-Specific Error Handling
+
+```typescript
+const validateStepWithErrors = (stepId: string, data: any): {
+  valid: boolean;
+  errors: string[]
+} => {
+  const errors: string[] = [];
+
+  switch (stepId) {
+    case 'service':
+      if (!data.service) errors.push('Please select a service');
+      break;
+
+    case 'date':
+      if (!data.date) {
+        errors.push('Please select a date');
+      } else if (new Date(data.date) < new Date()) {
+        errors.push('Selected date must be in the future');
+      }
+      break;
+
+    case 'time':
+      if (!data.time) errors.push('Please select a time slot');
+      break;
+
+    case 'details':
+      const { name, email, phone } = data.contact || {};
+      if (!name) errors.push('Name is required');
+      if (!email) errors.push('Email is required');
+      else if (!isValidEmail(email)) errors.push('Email is invalid');
+      if (!phone) errors.push('Phone number is required');
+      else if (!isValidPhone(phone)) errors.push('Phone number is invalid');
+      break;
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+};
+```
+
+---
+
+## Best Practices
+
+### 1. Always Handle Errors
+
+```typescript
+// ❌ Bad
+const handleComplete = async (data: BookingData) => {
+  const response = await fetch('/api/bookings', { ... });
+  const booking = await response.json();
+  router.push(`/confirmation/${booking.id}`);
+};
+
+// ✅ Good
+const handleComplete = async (data: BookingData) => {
+  try {
+    const response = await fetch('/api/bookings', { ... });
+    if (!response.ok) throw new Error('Failed to create booking');
+
+    const booking = await response.json();
+    router.push(`/confirmation/${booking.id}`);
+  } catch (error) {
+    handleBookingError(error, 'complete');
+  }
+};
+```
+
+### 2. Provide User Feedback
+
+```typescript
+// ✅ Show loading states
+const [isSubmitting, setIsSubmitting] = useState(false);
+
+const handleSubmit = async () => {
+  setIsSubmitting(true);
+  try {
+    await submitBooking();
+    toast.success('Booking confirmed!');
+  } catch (error) {
+    toast.error('Failed to book');
+  } finally {
+    setIsSubmitting(false);
+  }
+};
+```
+
+### 3. Track Analytics
+
+```typescript
+// ✅ Track important events
+const handleStepChange = (index: number, stepId: string) => {
+  analytics.track('Booking Step Changed', {
+    step: stepId,
+    stepIndex: index,
+    timestamp: new Date().toISOString()
+  });
+};
+```
+
+### 4. Validate Early and Often
+
+```typescript
+// ✅ Real-time validation
+const handleContactInfoChange = (info: ContactInfo) => {
+  setContactInfo(info);
+
+  // Validate as user types
+  const errors = validateContactInfo(info);
+  setValidationErrors(errors);
+};
+```
+
+### 5. Save Progress
+
+```typescript
+// ✅ Auto-save booking progress
+useEffect(() => {
+  const progress = {
+    service: selectedService,
+    date: selectedDate,
+    time: selectedTime,
+    addons: selectedAddons,
+    contact: contactInfo
+  };
+
+  localStorage.setItem('bookingProgress', JSON.stringify(progress));
+}, [selectedService, selectedDate, selectedTime, selectedAddons, contactInfo]);
+```
+
+---
+
+## See Also
+
+- [DATA_SHAPES.md](./DATA_SHAPES.md) - Data structures reference
+- [API.md](./API.md) - Component API reference
+- [PAYMENT_INTEGRATION.md](./PAYMENT_INTEGRATION.md) - Payment setup guide