@bailierich/booking-components 2.0.0

package/docs/MIGRATION.md

@@ -0,0 +1,662 @@
+# Migration Guide
+
+Guide for migrating from inline components to the `@oviah/booking-components` package.
+
+## Table of Contents
+
+- [Why Migrate?](#why-migrate)
+- [Before You Start](#before-you-start)
+- [Migration Steps](#migration-steps)
+- [Breaking Changes](#breaking-changes)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Why Migrate?
+
+### Benefits
+
+✅ **Reusability** - Use components across dashboard and tenant apps
+✅ **Maintainability** - Single source of truth for updates
+✅ **Type Safety** - Full TypeScript support
+✅ **Performance** - Optimized bundle size
+✅ **Testing** - Easier to test isolated components
+✅ **Documentation** - Comprehensive API docs
+
+### What's Different?
+
+| Old (Inline) | New (Package) |
+|--------------|---------------|
+| Components in page files | Separate package |
+| Props passed directly | Structured config objects |
+| Scattered settings | Centralized configuration |
+| Duplicate code | Shared components |
+| Hard to maintain | Easy updates |
+
+---
+
+## Before You Start
+
+### 1. Check Your Current Implementation
+
+Identify which components you're using:
+
+```tsx
+// Old: src/app/[businessId]/page.tsx
+function SectionRenderer({ section, theme }) {
+  switch (section.type) {
+    case 'logo':
+      // Inline logo rendering
+      return <div>...</div>;
+    case 'hero':
+      // Inline hero rendering
+      return <div>...</div>;
+    // ... more cases
+  }
+}
+```
+
+### 2. Review Your Configuration
+
+Document your current config structure:
+
+```typescript
+const currentConfig = {
+  sections: [...], // What sections do you have?
+  theme: {...},    // What colors/fonts?
+  bookingFlow: {...} // What booking steps?
+};
+```
+
+### 3. Backup Your Code
+
+```bash
+git checkout -b backup-before-migration
+git add .
+git commit -m "Backup before component migration"
+```
+
+---
+
+## Migration Steps
+
+### Step 1: Install the Package
+
+```bash
+# From the root of your monorepo
+npm install
+# The package is already in your workspace
+```
+
+### Step 2: Update Imports
+
+#### Before (Inline Components)
+
+```tsx
+// src/app/[businessId]/page.tsx
+'use client';
+
+import { useState } from 'react';
+import BookingFlowPreview from '@/components/preview/BookingFlowPreview';
+
+function SectionRenderer({ section, theme }) {
+  // 1000+ lines of inline rendering logic
+}
+
+export default function TenantPage() {
+  // Component logic
+}
+```
+
+#### After (Package Components)
+
+```tsx
+// src/app/[businessId]/page.tsx
+'use client';
+
+import { SectionRenderer, BookingFlow } from '@oviah/booking-components';
+
+export default function TenantPage() {
+  // Much cleaner!
+}
+```
+
+---
+
+### Step 3: Migrate Section Rendering
+
+#### Before
+
+```tsx
+function SectionRenderer({ section, theme }) {
+  const { type, settings } = section;
+  const colors = theme?.colors || {};
+
+  switch (type) {
+    case 'logo':
+      return (
+        <div className="container mx-auto px-4">
+          {settings.logoUrl ? (
+            <img src={settings.logoUrl} alt="Logo" />
+          ) : (
+            <div>{settings.fallbackText}</div>
+          )}
+        </div>
+      );
+
+    case 'hero':
+      return (
+        <div className="hero">
+          <h1>{settings.headline}</h1>
+          <p>{settings.subheadline}</p>
+          {/* ... more JSX */}
+        </div>
+      );
+
+    // ... 20 more cases
+  }
+}
+```
+
+#### After
+
+```tsx
+import { SectionRenderer } from '@oviah/booking-components';
+
+// Just pass section and theme - that's it!
+<SectionRenderer
+  section={section}
+  theme={theme}
+/>
+```
+
+**That's a reduction from 1000+ lines to 5 lines!** 🎉
+
+---
+
+### Step 4: Migrate Booking Flow
+
+#### Before
+
+```tsx
+// src/components/preview/BookingFlowPreview.tsx (1200+ lines)
+export default function BookingFlowPreview({ config, colors }) {
+  const [currentStep, setCurrentStep] = useState(0);
+  const [selectedService, setSelectedService] = useState(null);
+  const [selectedDate, setSelectedDate] = useState(null);
+  // ... 50+ state variables
+
+  const renderServiceSelection = () => {
+    // 200+ lines of JSX
+  };
+
+  const renderDateSelection = () => {
+    // 150+ lines of JSX
+  };
+
+  // ... more render functions
+
+  return (
+    <div>
+      {/* Complex flow logic */}
+    </div>
+  );
+}
+```
+
+#### After
+
+```tsx
+import { BookingFlow } from '@oviah/booking-components';
+
+<BookingFlow
+  config={config.booking_flow}
+  colors={colors}
+  services={services}
+  dates={availableDates}
+  times={availableTimes}
+  addons={addons}
+  onComplete={(bookingData) => {
+    // Handle booking completion
+  }}
+/>
+```
+
+**From 1200 lines to 15 lines!** 🚀
+
+---
+
+### Step 5: Update Configuration Structure
+
+Your config structure should remain mostly the same, but here are the key mappings:
+
+#### Section Configuration
+
+```typescript
+// Your existing config works as-is!
+const section = {
+  id: 'hero-1',
+  type: 'hero',
+  enabled: true,
+  position: 0,
+  settings: {
+    headline: 'Welcome',
+    subheadline: 'Book your appointment',
+    heroImage: '/hero.jpg',
+    layout: 'split'
+  }
+};
+
+// Just pass it to SectionRenderer
+<SectionRenderer section={section} theme={theme} />
+```
+
+#### Booking Flow Configuration
+
+```typescript
+// Your existing booking_flow config works!
+const config = {
+  booking_flow: {
+    steps: {
+      service_selection: {
+        enabled: true,
+        settings: {
+          headerContent: { value: 'Choose Service' },
+          serviceLayout: 'grid',
+          columns: 2
+        }
+      },
+      date_selection: {
+        enabled: true,
+        settings: {
+          headerContent: { value: 'Select Date' },
+          calendarView: 'month'
+        }
+      }
+      // ... more steps
+    },
+    progressBar: { style: 'dots' },
+    transitions: { style: 'slide', speed: 'normal' }
+  }
+};
+
+<BookingFlow config={config.booking_flow} colors={colors} />
+```
+
+---
+
+### Step 6: Handle Data Fetching
+
+#### Before (Inline)
+
+```tsx
+// Data fetching mixed with rendering
+export default function TenantPage({ params }) {
+  const [config, setConfig] = useState(null);
+  const [services, setServices] = useState([]);
+
+  useEffect(() => {
+    // Fetch config and services
+  }, []);
+
+  return (
+    <div>
+      {/* Render sections */}
+    </div>
+  );
+}
+```
+
+#### After (Separated Concerns)
+
+```tsx
+// src/app/[businessId]/page.tsx
+export default function TenantPage({ params }) {
+  const { config, services, dates, times, addons } = useBookingData(params.businessId);
+
+  return (
+    <div>
+      {sections.map(section => (
+        <SectionRenderer
+          key={section.id}
+          section={section}
+          theme={config.theme}
+        />
+      ))}
+
+      {showBookingFlow && (
+        <BookingFlow
+          config={config.booking_flow}
+          colors={config.theme.colors}
+          services={services}
+          dates={dates}
+          times={times}
+          addons={addons}
+          onComplete={handleBookingComplete}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Breaking Changes
+
+### 1. Import Paths
+
+```tsx
+// ❌ Old
+import BookingFlowPreview from '@/components/preview/BookingFlowPreview';
+
+// ✅ New
+import { BookingFlow } from '@oviah/booking-components';
+```
+
+### 2. Component Names
+
+| Old | New |
+|-----|-----|
+| `BookingFlowPreview` | `BookingFlow` |
+| `SectionRenderer` (inline) | `SectionRenderer` (from package) |
+
+### 3. Props Structure
+
+Some components now expect structured config objects:
+
+```tsx
+// ❌ Old (individual props)
+<ServiceSelection
+  services={services}
+  categories={categories}
+  layout="grid"
+  columns={2}
+  showPricing={true}
+/>
+
+// ✅ New (settings object)
+<ServiceSelection
+  services={services}
+  categories={categories}
+  settings={{
+    serviceLayout: 'grid',
+    columns: 2,
+    showPricing: true
+  }}
+  colors={colors}
+/>
+```
+
+### 4. Callback Patterns
+
+```tsx
+// ❌ Old
+<BookingFlowPreview
+  config={config}
+  colors={colors}
+  onComplete={() => {
+    // Limited data
+  }}
+/>
+
+// ✅ New (full booking data)
+<BookingFlow
+  config={config}
+  colors={colors}
+  onComplete={(bookingData) => {
+    // Full structured data
+    console.log(bookingData.service);
+    console.log(bookingData.date);
+    console.log(bookingData.contact);
+  }}
+  onStepChange={(index, stepId) => {
+    // Track step changes
+  }}
+/>
+```
+
+---
+
+## Step-by-Step Migration Checklist
+
+### Phase 1: Preparation
+- [ ] Backup your code
+- [ ] Document current configuration
+- [ ] Review all components you're using
+- [ ] Test current implementation
+
+### Phase 2: Install & Setup
+- [ ] Install package (already in workspace)
+- [ ] Update TypeScript paths if needed
+- [ ] Import components in your files
+
+### Phase 3: Migrate Sections
+- [ ] Replace inline `SectionRenderer` with package version
+- [ ] Test each section type renders correctly
+- [ ] Verify styling matches
+
+### Phase 4: Migrate Booking Flow
+- [ ] Replace `BookingFlowPreview` with `BookingFlow`
+- [ ] Pass data providers (services, dates, times)
+- [ ] Update callbacks
+- [ ] Test complete booking flow
+
+### Phase 5: Cleanup
+- [ ] Remove old component files
+- [ ] Remove unused imports
+- [ ] Update tests
+- [ ] Update documentation
+
+### Phase 6: Testing
+- [ ] Test all section types
+- [ ] Test booking flow end-to-end
+- [ ] Test on mobile devices
+- [ ] Test payment integration
+- [ ] Performance testing
+
+### Phase 7: Deploy
+- [ ] Deploy to staging
+- [ ] QA testing
+- [ ] Deploy to production
+- [ ] Monitor for errors
+
+---
+
+## Troubleshooting
+
+### Issue: Components Not Rendering
+
+**Problem:** Components show blank or throw errors
+
+**Solution:**
+```tsx
+// Check that you're passing all required props
+<SectionRenderer
+  section={section}  // ✅ Required
+  theme={theme}      // ✅ Required
+/>
+
+// Check section has required fields
+const section = {
+  id: 'hero-1',      // ✅ Required
+  type: 'hero',      // ✅ Required
+  settings: {...}    // ✅ Required
+};
+```
+
+### Issue: TypeScript Errors
+
+**Problem:** Type errors on component props
+
+**Solution:**
+```tsx
+// Import types
+import type { SectionRendererProps } from '@oviah/booking-components';
+
+// Use correct types
+const section: Section = {
+  id: 'hero-1',
+  type: 'hero',
+  enabled: true,
+  position: 0,
+  settings: {
+    headline: 'Welcome'
+  }
+};
+```
+
+### Issue: Styling Looks Different
+
+**Problem:** Components don't match previous styling
+
+**Solution:**
+```tsx
+// Ensure colors are passed correctly
+const colors = {
+  primary: '#D8C4FF',
+  secondary: '#014421',
+  text: '#000000',
+  // Add all color properties
+};
+
+// Check custom CSS isn't overriding
+// The package components use inline styles for theming
+```
+
+### Issue: Booking Flow State Not Persisting
+
+**Problem:** User loses progress on navigation
+
+**Solution:**
+```tsx
+// Save state to localStorage
+useEffect(() => {
+  const progress = {
+    service: selectedService,
+    date: selectedDate,
+    // ... other selections
+  };
+  localStorage.setItem('bookingProgress', JSON.stringify(progress));
+}, [selectedService, selectedDate]);
+
+// Restore on mount
+useEffect(() => {
+  const saved = localStorage.getItem('bookingProgress');
+  if (saved) {
+    const progress = JSON.parse(saved);
+    // Restore state
+  }
+}, []);
+```
+
+### Issue: Payment Integration Broken
+
+**Problem:** Payment processing fails after migration
+
+**Solution:**
+```tsx
+// The Confirmation component is presentational only
+// You need to handle payment logic yourself
+
+<Confirmation
+  // ... props
+  onConfirm={async () => {
+    // YOUR payment processing logic here
+    await processPayment();
+    await createBooking();
+  }}
+/>
+```
+
+---
+
+## Example: Complete Migration
+
+### Before (app/[businessId]/page.tsx)
+
+```tsx
+// 2000+ lines of code
+'use client';
+
+import { use, useEffect, useState } from 'react';
+// ... many imports
+
+export default function TenantPage({ params }) {
+  // 50+ state variables
+  // 500+ lines of logic
+
+  function SectionRenderer() {
+    // 1000+ lines of switch statement
+  }
+
+  return (
+    <div>
+      {/* Complex rendering logic */}
+    </div>
+  );
+}
+```
+
+### After (app/[businessId]/page.tsx)
+
+```tsx
+// ~100 lines of code
+'use client';
+
+import { use, useEffect, useState } from 'react';
+import { SectionRenderer, BookingFlow } from '@oviah/booking-components';
+import { useBookingData } from '@/hooks/useBookingData';
+
+export default function TenantPage({ params }) {
+  const { businessId } = use(params);
+  const { config, services, dates, times, addons } = useBookingData(businessId);
+
+  if (!config) return <Loading />;
+
+  const { theme, sections, booking_flow } = config;
+
+  return (
+    <div style={{ backgroundColor: config.background?.value }}>
+      {sections.map(section => (
+        <SectionRenderer
+          key={section.id}
+          section={section}
+          theme={theme}
+        />
+      ))}
+
+      {booking_flow && (
+        <BookingFlow
+          config={booking_flow}
+          colors={theme.colors}
+          services={services}
+          dates={dates}
+          times={times}
+          addons={addons}
+          onComplete={handleBookingComplete}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+**Result:** 95% reduction in code! 🎉
+
+---
+
+## Need Help?
+
+- Check [API.md](./API.md) for component reference
+- See [DATA_SHAPES.md](./DATA_SHAPES.md) for data structures
+- Review [CALLBACKS.md](./CALLBACKS.md) for event handling
+- Read [STYLING.md](./STYLING.md) for customization
+
+If you encounter issues:
+1. Check the troubleshooting section above
+2. Review the example code in this guide
+3. Verify your configuration matches the data shapes
+4. Test components individually before full integration
+
+Happy migrating! 🚀