@bailierich/booking-components 2.0.0

package/docs/DATA_SHAPES.md

@@ -0,0 +1,684 @@
+# Data Shapes & Interfaces
+
+Complete reference for all data structures used in `@oviah/booking-components`.
+
+## Table of Contents
+
+- [Service Data](#service-data)
+- [Category Data](#category-data)
+- [Booking Data](#booking-data)
+- [Section Configuration](#section-configuration)
+- [Theme Configuration](#theme-configuration)
+- [Step Settings](#step-settings)
+
+---
+
+## Service Data
+
+### Service Object
+
+```typescript
+interface Service {
+  id: string;
+  name: string;
+  description: string;
+  price: number;
+  duration: number; // in minutes
+  category?: string;
+  image?: string;
+  available?: boolean;
+}
+```
+
+**Example:**
+```typescript
+const service: Service = {
+  id: 'haircut-1',
+  name: 'Haircut & Style',
+  description: 'Professional haircut with styling',
+  price: 65,
+  duration: 60,
+  category: 'hair',
+  image: 'https://example.com/haircut.jpg',
+  available: true
+};
+```
+
+---
+
+## Category Data
+
+### Category Object
+
+```typescript
+interface ServiceCategory {
+  id: string;
+  name: string;
+  description: string;
+  services: Service[];
+  icon?: string;
+  image?: string;
+}
+```
+
+**Example:**
+```typescript
+const category: ServiceCategory = {
+  id: 'hair',
+  name: 'Hair Services',
+  description: 'Professional hair care and styling',
+  services: [
+    { id: '1', name: 'Haircut', price: 65, duration: 60, description: '...' },
+    { id: '2', name: 'Color', price: 150, duration: 120, description: '...' }
+  ],
+  icon: '💇',
+  image: 'https://example.com/hair-category.jpg'
+};
+```
+
+---
+
+## Booking Data
+
+### Addon Object
+
+```typescript
+interface Addon {
+  id: string;
+  name: string;
+  description: string;
+  price: number;
+  duration: number; // in minutes
+  image?: string;
+  available?: boolean;
+}
+```
+
+### Contact Information
+
+```typescript
+interface ContactInfo {
+  name: string;
+  email: string;
+  phone: string;
+  notes?: string;
+}
+```
+
+### Complete Booking Data
+
+```typescript
+interface BookingData {
+  service: string | null;      // Selected service ID
+  date: string | null;          // ISO date string (YYYY-MM-DD)
+  time: string | null;          // Time string (e.g., "10:00 AM")
+  addons: string[];             // Array of addon IDs
+  contact: ContactInfo;
+  optIn?: {                     // Optional opt-in module data
+    [key: string]: any;
+  };
+}
+```
+
+**Example:**
+```typescript
+const bookingData: BookingData = {
+  service: 'haircut-1',
+  date: '2025-01-15',
+  time: '10:00 AM',
+  addons: ['addon-1', 'addon-2'],
+  contact: {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+    phone: '(555) 123-4567',
+    notes: 'Please use low-ammonia products'
+  },
+  optIn: {
+    colorConsultation: {
+      currentColor: 'Brown',
+      desiredColor: 'Blonde highlights'
+    }
+  }
+};
+```
+
+---
+
+## Section Configuration
+
+### Base Section Object
+
+```typescript
+interface Section {
+  id: string;
+  type: string;
+  enabled: boolean;
+  position: number;
+  settings: any; // Type-specific settings
+}
+```
+
+### Section Types & Settings
+
+#### Logo Section
+```typescript
+interface LogoSettings {
+  logoUrl?: string;
+  fallbackText?: string;
+  size?: 'small' | 'medium' | 'large';
+  alignment?: 'left' | 'center' | 'right';
+}
+```
+
+#### Header Section
+```typescript
+interface HeaderSettings {
+  name?: string;
+  title?: string;
+  bio?: string;
+  showName?: boolean;
+  showTitle?: boolean;
+  showBio?: boolean;
+}
+```
+
+#### Hero Section
+```typescript
+interface HeroSettings {
+  headline?: string;
+  subheadline?: string;
+  heroImage?: string;
+  ctaButton?: {
+    text: string;
+    url: string;
+  };
+  layout?: 'split' | 'full';
+  imagePosition?: 'left' | 'right';
+  contentDisplay?: 'side' | 'overlay';
+}
+```
+
+#### Gallery Section
+```typescript
+interface GalleryImage {
+  id: string;
+  url: string;
+  alt?: string;
+  caption?: string;
+}
+
+interface GallerySettings {
+  title?: string;
+  images?: GalleryImage[];
+  columns?: 2 | 3 | 4;
+}
+```
+
+#### Testimonials Section
+```typescript
+interface Testimonial {
+  id: string | number;
+  text: string;
+  author: string;
+  rating: number; // 1-5
+  image?: string;
+  date?: string;
+}
+
+interface TestimonialsSettings {
+  title?: string;
+  testimonials?: Testimonial[];
+  layout?: 'grid' | 'carousel';
+}
+```
+
+#### Link List Section
+```typescript
+interface Link {
+  id: string;
+  label: string;
+  url: string;
+}
+
+interface LinkListSettings {
+  links: Link[];
+  style?: 'pill' | 'square' | 'outline';
+}
+```
+
+#### Social Bar Section
+```typescript
+interface SocialBarSettings {
+  platforms: string[]; // ['instagram', 'facebook', 'tiktok', etc.]
+  socialLinks?: Record<string, string>;
+  style?: 'filled' | 'outline' | 'ghost';
+  size?: 'small' | 'medium' | 'large';
+  position?: 'center' | 'left-vertical' | 'right-vertical';
+  invertIcons?: boolean;
+}
+```
+
+#### Fixed Info Card Section
+```typescript
+interface FixedInfoCardSettings {
+  name?: string;
+  subheading?: string;
+  bio?: string;
+  links?: Link[];
+  bookingButtonText?: string;
+  bookingButtonUrl?: string;
+  showBookingButton?: boolean;
+  position?: 'bottom-left' | 'bottom-right' | 'bottom-center';
+  cardWidth?: 'small' | 'medium' | 'large';
+  cardColor?: string; // hex color
+}
+```
+
+**Complete Example:**
+```typescript
+const heroSection: Section = {
+  id: 'hero-1',
+  type: 'hero',
+  enabled: true,
+  position: 0,
+  settings: {
+    headline: 'Welcome to Our Salon',
+    subheadline: 'Transform your look with our expert stylists',
+    heroImage: 'https://example.com/hero.jpg',
+    ctaButton: {
+      text: 'Book Now',
+      url: '/book'
+    },
+    layout: 'split',
+    imagePosition: 'right',
+    contentDisplay: 'side'
+  }
+};
+```
+
+---
+
+## Theme Configuration
+
+### Colors Object
+
+```typescript
+interface ColorScheme {
+  primary: string;          // Main brand color (hex)
+  secondary: string;        // Secondary brand color (hex)
+  text: string;             // Main text color (hex)
+  bookingText?: string;     // Booking widget text color
+  linkBackground?: string;  // Link button background
+  linkText?: string;        // Link button text
+  buttonText?: string;      // Button text color
+}
+```
+
+### Typography Object
+
+```typescript
+interface TypographyConfig {
+  headingFont?: string;     // Font family for headings
+  bodyFont?: string;        // Font family for body text
+  bodySize?: string;        // Base font size (e.g., "16px")
+}
+```
+
+### Complete Theme
+
+```typescript
+interface Theme {
+  colors: ColorScheme;
+  typography: TypographyConfig;
+}
+```
+
+**Example:**
+```typescript
+const theme: Theme = {
+  colors: {
+    primary: '#D8C4FF',
+    secondary: '#014421',
+    text: '#000000',
+    bookingText: '#1A1A1A',
+    linkBackground: '#D8C4FF',
+    linkText: '#FFFFFF',
+    buttonText: '#FFFFFF'
+  },
+  typography: {
+    headingFont: 'Geist Sans',
+    bodyFont: 'Inter',
+    bodySize: '16px'
+  }
+};
+```
+
+---
+
+## Step Settings
+
+### Service Selection Settings
+
+```typescript
+interface ServiceSelectionSettings {
+  headerContent?: {
+    value: string;
+  };
+  subheaderContent?: {
+    value: string;
+  };
+  serviceLayout?: 'grid' | 'list';
+  columns?: 1 | 2 | 3 | 4;
+  showPricing?: boolean;
+  showDuration?: boolean;
+  showDescription?: boolean;
+  enableCategories?: boolean;
+  categoryStyle?: 'dropdown' | 'tabs' | 'pills' | 'chips' | 'accordion';
+  defaultCategoryView?: 'all' | string; // category ID
+  policyImages?: Array<{
+    url: string;
+    alt: string;
+  }>;
+  policyText?: string; // HTML string
+  imageSpacing?: 'none' | 'small' | 'medium' | 'large';
+  imageBorderRadius?: string; // CSS value
+}
+```
+
+### Date Selection Settings
+
+```typescript
+interface DateSelectionSettings {
+  headerContent?: {
+    value: string;
+  };
+  calendarView?: 'month' | 'week';
+  minDate?: string; // ISO date
+  maxDate?: string; // ISO date
+  disabledDates?: string[]; // Array of ISO dates
+}
+```
+
+### Time Selection Settings
+
+```typescript
+interface TimeSelectionSettings {
+  headerContent?: {
+    value: string;
+  };
+  timeFormat?: '12h' | '24h';
+  showDuration?: boolean;
+  columns?: 2 | 3 | 4;
+  slotDuration?: number; // minutes
+}
+```
+
+### Addon Selection Settings
+
+```typescript
+interface AddonSelectionSettings {
+  headerContent?: {
+    value: string;
+  };
+  subheaderContent?: {
+    value: string;
+  };
+  showPricing?: boolean;
+  showDuration?: boolean;
+  showDescription?: boolean;
+  maxAddons?: number; // Maximum number of addons
+}
+```
+
+### Contact Form Settings
+
+```typescript
+interface ContactFormSettings {
+  headerContent?: {
+    value: string;
+  };
+  requiredFields?: string[]; // ['name', 'email', 'phone']
+  showNotesField?: boolean;
+  notesLabel?: string;
+  notesPlaceholder?: string;
+}
+```
+
+### Opt-In Module Data
+
+```typescript
+interface OptInModule {
+  id: string;
+  label: string;
+  description?: string;
+  required?: boolean;
+  formFields: Array<{
+    id: string;
+    label: string;
+    type: 'text' | 'textarea' | 'select' | 'checkbox';
+    placeholder?: string;
+    required?: boolean;
+    options?: string[]; // for select fields
+  }>;
+}
+```
+
+**Example:**
+```typescript
+const colorConsultationModule: OptInModule = {
+  id: 'color-consultation',
+  label: 'I need color consultation services',
+  description: 'Provide additional info for your color service',
+  required: false,
+  formFields: [
+    {
+      id: 'currentColor',
+      label: 'Current Hair Color',
+      type: 'text',
+      placeholder: 'Natural, dyed, etc.',
+      required: true
+    },
+    {
+      id: 'desiredColor',
+      label: 'Desired Color/Look',
+      type: 'textarea',
+      placeholder: 'Describe what you want to achieve...',
+      required: true
+    },
+    {
+      id: 'previousTreatments',
+      label: 'Previous Chemical Treatments',
+      type: 'text',
+      placeholder: 'Perms, relaxers, etc.',
+      required: false
+    }
+  ]
+};
+```
+
+---
+
+## Background Configuration
+
+### Background Object
+
+```typescript
+interface BackgroundConfig {
+  type: 'color' | 'gradient' | 'image';
+  value: string;
+}
+```
+
+**Examples:**
+```typescript
+// Solid color
+const colorBg: BackgroundConfig = {
+  type: 'color',
+  value: '#FFFFFF'
+};
+
+// Gradient
+const gradientBg: BackgroundConfig = {
+  type: 'gradient',
+  value: 'linear-gradient(135deg, #D8C4FF 0%, #014421 100%)'
+};
+
+// Image
+const imageBg: BackgroundConfig = {
+  type: 'image',
+  value: 'https://example.com/background.jpg'
+};
+```
+
+---
+
+## Payment Configuration
+
+### Payment Provider Config
+
+```typescript
+interface PaymentConfig {
+  provider: 'square' | 'stripe';
+  depositPercentage?: number; // 0-100
+  requireDeposit?: boolean;
+  acceptedMethods?: string[]; // ['card', 'apple_pay', 'google_pay']
+}
+```
+
+**Example:**
+```typescript
+const paymentConfig: PaymentConfig = {
+  provider: 'square',
+  depositPercentage: 20,
+  requireDeposit: true,
+  acceptedMethods: ['card', 'apple_pay', 'google_pay']
+};
+```
+
+---
+
+## Complete Configuration Example
+
+```typescript
+const completeConfig = {
+  // Theme
+  theme: {
+    colors: {
+      primary: '#D8C4FF',
+      secondary: '#014421',
+      text: '#000000'
+    },
+    typography: {
+      headingFont: 'Geist Sans',
+      bodyFont: 'Inter',
+      bodySize: '16px'
+    }
+  },
+
+  // Background
+  background: {
+    type: 'gradient',
+    value: 'linear-gradient(135deg, #D8C4FF 0%, #014421 100%)'
+  },
+
+  // Page sections
+  sections: [
+    {
+      id: 'logo-1',
+      type: 'logo',
+      enabled: true,
+      position: 0,
+      settings: {
+        logoUrl: 'https://example.com/logo.png',
+        size: 'medium',
+        alignment: 'center'
+      }
+    },
+    {
+      id: 'hero-1',
+      type: 'hero',
+      enabled: true,
+      position: 1,
+      settings: {
+        headline: 'Welcome',
+        subheadline: 'Book your appointment today',
+        heroImage: 'https://example.com/hero.jpg',
+        ctaButton: {
+          text: 'Book Now',
+          url: '#booking'
+        }
+      }
+    }
+  ],
+
+  // Booking flow
+  booking_flow: {
+    steps: {
+      service_selection: {
+        enabled: true,
+        settings: {
+          headerContent: { value: 'Choose Your Service' },
+          serviceLayout: 'grid',
+          columns: 2,
+          showPricing: true
+        }
+      },
+      date_selection: {
+        enabled: true,
+        settings: {
+          headerContent: { value: 'Select a Date' },
+          calendarView: 'month'
+        }
+      },
+      time_selection: {
+        enabled: true,
+        settings: {
+          headerContent: { value: 'Pick a Time' },
+          timeFormat: '12h',
+          columns: 3
+        }
+      },
+      addon_selection: {
+        enabled: true,
+        settings: {
+          headerContent: { value: 'Add Extras' },
+          showPricing: true
+        }
+      },
+      contact_form: {
+        enabled: true,
+        settings: {
+          headerContent: { value: 'Your Information' }
+        }
+      }
+    },
+    progressBar: {
+      style: 'dots'
+    },
+    transitions: {
+      style: 'slide',
+      speed: 'normal'
+    },
+    background: {
+      type: 'color',
+      value: '#FFFFFF'
+    }
+  }
+};
+```
+
+---
+
+## Type Safety Tips
+
+1. **Always define interfaces** for your data structures
+2. **Use TypeScript** for compile-time type checking
+3. **Validate at runtime** for user-provided data
+4. **Provide defaults** for optional fields
+5. **Document required vs optional** fields clearly
+
+## See Also
+
+- [API.md](./API.md) - Component API reference
+- [CALLBACKS.md](./CALLBACKS.md) - Callback patterns
+- [STYLING.md](./STYLING.md) - Theme customization