@bailierich/booking-components 2.0.0

package/docs/API.md

@@ -0,0 +1,849 @@
+# @oviah/booking-components API Reference
+
+Complete API documentation for all components in the OVIAH booking components library.
+
+## Table of Contents
+
+- [Section Components](#section-components)
+- [Booking Flow Components](#booking-flow-components)
+- [UI Components](#ui-components)
+- [Common Props](#common-props)
+
+---
+
+## Section Components
+
+### Logo
+
+Display a logo or brand mark with customizable size and alignment.
+
+```tsx
+import { Logo } from '@oviah/booking-components';
+
+<Logo
+  logoUrl="https://example.com/logo.png"
+  fallbackText="AB"
+  size="medium"
+  alignment="center"
+  colors={{ primary: '#D8C4FF' }}
+/>
+```
+
+**Props:**
+- `logoUrl?: string` - URL to logo image
+- `fallbackText?: string` - Text to show if no logo (shows first 2 chars)
+- `size?: 'small' | 'medium' | 'large'` - Logo size (80px/120px/160px)
+- `alignment?: 'left' | 'center' | 'right'` - Horizontal alignment
+- `colors: { primary: string }` - Theme colors
+
+---
+
+### Header
+
+Simple text header with name, title, and bio.
+
+```tsx
+import { Header } from '@oviah/booking-components';
+
+<Header
+  name="Jane Doe"
+  title="Master Stylist"
+  bio="Transform your look ✨"
+  showName={true}
+  showTitle={true}
+  showBio={true}
+  colors={{ text: '#000000' }}
+  typography={{ headingFont: 'Geist Sans' }}
+/>
+```
+
+**Props:**
+- `name?: string` - Display name
+- `title?: string` - Professional title
+- `bio?: string` - Short bio text
+- `showName?: boolean` - Show/hide name
+- `showTitle?: boolean` - Show/hide title
+- `showBio?: boolean` - Show/hide bio
+- `colors: { text: string }` - Text color
+- `typography: { headingFont?: string }` - Font settings
+
+---
+
+### FeaturedLink
+
+Large call-to-action button with multiple styles.
+
+```tsx
+import { FeaturedLink } from '@oviah/booking-components';
+
+<FeaturedLink
+  text="💅 Book Now"
+  url="/book"
+  style="gradient"
+  size="large"
+  colors={{ primary: '#D8C4FF', secondary: '#014421' }}
+/>
+```
+
+**Props:**
+- `text?: string` - Button text
+- `url?: string` - Link URL
+- `style?: 'gradient' | 'solid' | 'outline'` - Visual style
+- `size?: 'small' | 'medium' | 'large'` - Button size
+- `colors: { primary: string; secondary: string }` - Theme colors
+
+---
+
+### LinkList
+
+List of clickable links in various styles.
+
+```tsx
+import { LinkList } from '@oviah/booking-components';
+
+<LinkList
+  links={[
+    { id: '1', label: 'Portfolio', url: 'https://example.com' },
+    { id: '2', label: 'Instagram', url: 'https://instagram.com' }
+  ]}
+  style="pill"
+  colors={{ primary: '#D8C4FF' }}
+/>
+```
+
+**Props:**
+- `links: Link[]` - Array of link objects
+  - `id: string` - Unique identifier
+  - `label: string` - Link text
+  - `url: string` - Link URL
+- `style?: 'pill' | 'square' | 'outline'` - Button style
+- `colors: { primary: string; linkBackground?: string; linkText?: string }`
+
+---
+
+### SocialBar
+
+Social media icons with links.
+
+```tsx
+import { SocialBar } from '@oviah/booking-components';
+
+<SocialBar
+  platforms={['instagram', 'facebook', 'tiktok']}
+  socialLinks={{
+    instagram: 'https://instagram.com/handle',
+    facebook: 'https://facebook.com/handle'
+  }}
+  style="filled"
+  size="large"
+  position="center"
+  colors={{ primary: '#D8C4FF' }}
+/>
+```
+
+**Props:**
+- `platforms: string[]` - Array of platform names
+- `socialLinks?: Record<string, string>` - URLs for each platform
+- `style?: 'filled' | 'outline' | 'ghost'` - Icon style
+- `size?: 'small' | 'medium' | 'large'` - Icon size
+- `position?: 'center' | 'left-vertical' | 'right-vertical'` - Layout position
+- `invertIcons?: boolean` - Invert icon colors
+- `colors: { primary: string }`
+
+---
+
+### Hero
+
+Large hero section with image and CTA.
+
+```tsx
+import { Hero } from '@oviah/booking-components';
+
+<Hero
+  headline="Welcome to Our Salon"
+  subheadline="Professional beauty services"
+  heroImage="https://example.com/hero.jpg"
+  ctaButton={{ text: 'Book Now', url: '/book' }}
+  layout="split"
+  imagePosition="right"
+  contentDisplay="side"
+  colors={{ primary: '#D8C4FF', text: '#000000' }}
+  typography={{ headingFont: 'Geist Sans' }}
+/>
+```
+
+**Props:**
+- `headline?: string` - Main heading
+- `subheadline?: string` - Subheading text
+- `heroImage?: string` - Background/feature image URL
+- `ctaButton?: { text: string; url: string }` - Call-to-action button
+- `layout?: 'split' | 'full'` - Layout type
+- `imagePosition?: 'left' | 'right'` - Image side (split layout)
+- `contentDisplay?: 'side' | 'overlay'` - Text positioning
+- `colors: { primary: string; text: string }`
+- `typography: { headingFont?: string }`
+
+---
+
+### About
+
+About section with image and text.
+
+```tsx
+import { About } from '@oviah/booking-components';
+
+<About
+  title="About Us"
+  content="Tell your story here..."
+  image="https://example.com/about.jpg"
+  layout="split"
+  colors={{ primary: '#D8C4FF', text: '#000000' }}
+  typography={{ headingFont: 'Geist Sans' }}
+/>
+```
+
+**Props:**
+- `title?: string` - Section heading
+- `content?: string` - About text content
+- `image?: string` - Feature image URL
+- `layout?: 'centered' | 'split' | 'wide'` - Layout style
+- `colors: { primary: string; text: string }`
+- `typography: { headingFont?: string }`
+
+---
+
+### ServicesPreview
+
+Display service offerings in grid/list/carousel.
+
+```tsx
+import { ServicesPreview } from '@oviah/booking-components';
+
+<ServicesPreview
+  title="Our Services"
+  services={[
+    { id: 1, name: 'Haircut', description: '...', price: 75, duration: 60 }
+  ]}
+  layout="grid"
+  columns={3}
+  showPrices={true}
+  showDuration={true}
+  colors={{ primary: '#D8C4FF', text: '#000000' }}
+  typography={{ headingFont: 'Geist Sans' }}
+/>
+```
+
+**Props:**
+- `title?: string` - Section heading
+- `services?: Service[]` - Array of service objects
+- `layout?: 'grid' | 'list' | 'carousel'` - Display layout
+- `columns?: 2 | 3 | 4` - Grid columns
+- `showPrices?: boolean` - Show prices
+- `showDuration?: boolean` - Show duration
+- `colors: { primary: string; text: string }`
+- `typography: { headingFont?: string }`
+
+---
+
+### Gallery
+
+Image gallery with grid layout.
+
+```tsx
+import { Gallery } from '@oviah/booking-components';
+
+<Gallery
+  title="Gallery"
+  images={[
+    { id: '1', url: 'https://example.com/1.jpg', alt: 'Photo 1' }
+  ]}
+  columns={3}
+  colors={{ primary: '#D8C4FF', text: '#000000' }}
+  typography={{ headingFont: 'Geist Sans' }}
+/>
+```
+
+**Props:**
+- `title?: string` - Section heading
+- `images?: GalleryImage[]` - Array of image objects
+- `columns?: 2 | 3 | 4` - Grid columns
+- `colors: { primary: string; text: string }`
+- `typography: { headingFont?: string }`
+
+---
+
+### Testimonials
+
+Client testimonials with star ratings.
+
+```tsx
+import { Testimonials } from '@oviah/booking-components';
+
+<Testimonials
+  title="What Clients Say"
+  testimonials={[
+    { id: 1, text: 'Amazing!', author: 'Sarah M.', rating: 5 }
+  ]}
+  layout="grid"
+  colors={{ primary: '#D8C4FF', text: '#000000' }}
+  typography={{ headingFont: 'Geist Sans' }}
+/>
+```
+
+**Props:**
+- `title?: string` - Section heading
+- `testimonials?: Testimonial[]` - Array of testimonial objects
+- `layout?: 'grid' | 'carousel'` - Display layout
+- `colors: { primary: string; text: string }`
+- `typography: { headingFont?: string }`
+
+---
+
+### Team
+
+Team member showcase section.
+
+**Props:** See Team.tsx for complete props interface
+
+---
+
+### Contact
+
+Contact information and form section.
+
+**Props:** See Contact.tsx for complete props interface
+
+---
+
+### MinimalHeader
+
+Minimal sticky header with logo/text.
+
+**Props:** See MinimalHeader.tsx for complete props interface
+
+---
+
+### MinimalNavigation
+
+Clean navigation links (horizontal/vertical).
+
+**Props:** See MinimalNavigation.tsx for complete props interface
+
+---
+
+### MinimalFooter
+
+Footer with social links and contact info.
+
+**Props:** See MinimalFooter.tsx for complete props interface
+
+---
+
+### FeatureContent
+
+Feature content with image and text.
+
+**Props:** See FeatureContent.tsx for complete props interface
+
+---
+
+### BeforeAfter
+
+Before/after comparison section.
+
+**Props:** See BeforeAfter.tsx for complete props interface
+
+---
+
+### PricingTable
+
+Pricing plans in grid layout.
+
+**Props:** See PricingTable.tsx for complete props interface
+
+---
+
+### InstagramFeed
+
+Instagram feed grid display.
+
+**Props:** See InstagramFeed.tsx for complete props interface
+
+---
+
+### FixedInfoCard
+
+Fixed info card pinned to page corners.
+
+```tsx
+import { FixedInfoCard } from '@oviah/booking-components';
+
+<FixedInfoCard
+  name="Jane Doe"
+  subheading="Master Stylist"
+  bio="Transform your look ✨"
+  links={[
+    { id: '1', label: 'Portfolio', url: 'https://example.com' }
+  ]}
+  bookingButtonText="Book Now"
+  bookingButtonUrl="/book"
+  showBookingButton={true}
+  position="bottom-left"
+  cardWidth="medium"
+  cardColor="#FFFFFF"
+  colors={{ primary: '#D8C4FF', text: '#000000', buttonText: '#FFFFFF' }}
+  typography={{ headingFont: 'Geist Sans' }}
+/>
+```
+
+**Props:** See FixedInfoCard.tsx for complete props interface
+
+---
+
+### BookingSection
+
+Wrapper section for embedding booking flows.
+
+```tsx
+import { BookingSection } from '@oviah/booking-components';
+import { BookingFlowPreview } from './your-booking-flow';
+
+<BookingSection
+  config={{
+    theme: {
+      colors: { primary: '#D8C4FF', secondary: '#014421', text: '#000000' },
+      typography: { headingFont: 'Geist Sans' }
+    },
+    bookingSettings: { /* your booking settings */ }
+  }}
+  colors={{ primary: '#D8C4FF', secondary: '#014421', text: '#000000' }}
+  BookingFlowComponent={BookingFlowPreview}
+/>
+```
+
+**Props:**
+- `config: BookingConfig` - Full booking configuration object
+- `colors: { primary: string; secondary: string; text: string; bookingText?: string }` - Theme colors
+- `BookingFlowComponent?: React.ComponentType` - Optional custom booking flow component
+
+---
+
+## Section Renderer
+
+### SectionRenderer
+
+Universal renderer that dynamically renders any section type from configuration.
+
+```tsx
+import { SectionRenderer } from '@oviah/booking-components';
+
+// Render a hero section
+<SectionRenderer
+  section={{
+    id: 'hero-1',
+    type: 'hero',
+    settings: {
+      headline: 'Welcome to Our Salon',
+      subheadline: 'Professional beauty services',
+      heroImage: '/hero.jpg',
+      layout: 'split',
+      imagePosition: 'right'
+    },
+    enabled: true,
+    position: 0
+  }}
+  theme={{
+    colors: {
+      primary: '#D8C4FF',
+      secondary: '#014421',
+      text: '#000000'
+    },
+    typography: {
+      headingFont: 'Geist Sans',
+      bodyFont: 'Inter',
+      bodySize: '16px'
+    }
+  }}
+/>
+
+// Render a booking section with custom flow component
+<SectionRenderer
+  section={{
+    id: 'booking-1',
+    type: 'booking',
+    settings: {},
+    enabled: true,
+    position: 5
+  }}
+  theme={theme}
+  config={fullConfig}
+  BookingFlowComponent={YourBookingFlow}
+/>
+
+// Render from a dynamic sections array
+{sections.map((section) => (
+  <SectionRenderer
+    key={section.id}
+    section={section}
+    theme={theme}
+  />
+))}
+
+// Enable inline editing mode (for Studio preview)
+<SectionRenderer
+  section={section}
+  theme={theme}
+  enableInlineEditing={true}  // Adds data-editable, data-section-id, data-field-path
+/>
+```
+
+**Props:**
+- `section: Section` - Section configuration object
+  - `id: string` - Unique section ID
+  - `type: string` - Section type (hero, about, gallery, etc.)
+  - `settings: any` - Type-specific settings
+  - `enabled?: boolean` - Whether section is enabled
+  - `position?: number` - Sort order
+- `theme: Theme` - Theme configuration
+  - `colors: ColorScheme` - Color palette
+  - `typography: TypographyConfig` - Font settings
+- `enableInlineEditing?: boolean` - Enable inline editing mode (adds data-editable attributes)
+- `BookingFlowComponent?: React.ComponentType` - Custom booking flow (for 'booking' type)
+- `config?: any` - Full app config (for 'booking' type)
+
+**Supported Section Types:**
+- `logo` - Logo/brand mark
+- `header` - Text header (name, title, bio)
+- `featured_link` - Large CTA button
+- `link_list` - List of links
+- `social_bar` - Social media icons
+- `instagram_feed` - Instagram grid
+- `minimal_header` - Sticky header
+- `minimal_navigation` - Navigation links
+- `minimal_footer` - Footer section
+- `feature_content` - Feature with image/text
+- `hero` - Hero section
+- `about` - About section
+- `services_preview` - Services grid/list
+- `gallery` - Image gallery
+- `testimonials` - Client testimonials
+- `team` - Team members
+- `contact` - Contact info/form
+- `before_after` - Before/after comparisons
+- `pricing_table` - Pricing plans
+- `booking` - Booking flow wrapper
+- `fixed_info_card` - Fixed corner card
+
+**Benefits:**
+- ✅ Single component for all section types
+- ✅ Type-safe section configuration
+- ✅ Automatic prop mapping
+- ✅ Theme inheritance
+- ✅ Unknown type handling (renders placeholder)
+
+---
+
+## Booking Flow Orchestrator
+
+### BookingFlow
+
+Main orchestrator component that manages the entire booking flow with state and navigation.
+
+```tsx
+import { BookingFlow } from '@oviah/booking-components';
+
+<BookingFlow
+  config={{
+    steps: {
+      service_selection: { enabled: true, settings: { ... } },
+      date_selection: { enabled: true, settings: { ... } },
+      time_selection: { enabled: true, settings: { ... } },
+      addon_selection: { enabled: true, settings: { ... } },
+      contact_form: { enabled: true, settings: { ... } }
+    },
+    progressBar: { style: 'dots' },
+    transitions: { style: 'slide', speed: 'normal' },
+    background: { type: 'color', value: '#FFFFFF' }
+  }}
+  colors={{
+    primary: '#D8C4FF',
+    secondary: '#014421',
+    text: '#000000'
+  }}
+  services={services}
+  categories={categories}
+  dates={availableDates}
+  times={availableTimes}
+  addons={addons}
+  onComplete={(bookingData) => {
+    console.log('Booking complete!', bookingData);
+    // Submit to backend
+  }}
+  onStepChange={(index, stepId) => {
+    console.log('Changed to step:', stepId);
+  }}
+/>
+```
+
+**Props:**
+- `config: BookingFlowConfig` - Flow configuration
+  - `steps` - Enable/disable and configure each step
+  - `progressBar.style?: 'dots' | 'bar' | 'minimal'` - Progress indicator style
+  - `transitions.style?: 'slide' | 'fade'` - Step transition animation
+  - `transitions.speed?: 'fast' | 'normal' | 'slow'` - Animation speed
+  - `background` - Background styling
+- `colors: ColorScheme` - Theme colors
+- `services?: any[]` - Available services (for service selection step)
+- `categories?: any[]` - Service categories
+- `dates?: string[]` - Available dates (for date selection step)
+- `times?: string[]` - Available times (for time selection step)
+- `addons?: any[]` - Add-on services (for addons step)
+- `onComplete?: (bookingData) => void` - Called when booking is completed
+- `onStepChange?: (stepIndex, stepId) => void` - Called on step navigation
+- `validateStep?: (stepId, data) => boolean` - Custom step validation
+
+**Features:**
+- ✅ Automatic step state management
+- ✅ Built-in navigation with validation
+- ✅ Smooth animated transitions
+- ✅ Progress indicator (dots/bar/minimal)
+- ✅ Responsive layout
+- ✅ Accessibility support
+- ✅ Custom validation hooks
+
+**Booking Data Structure:**
+```typescript
+{
+  service: string | null;      // Selected service ID
+  date: string | null;          // Selected date
+  time: string | null;          // Selected time slot
+  addons: string[];             // Selected addon IDs
+  contact: {                    // Contact information
+    name: string;
+    email: string;
+    phone: string;
+    notes?: string;
+  };
+  optIn: any;                   // Opt-in module data
+}
+```
+
+---
+
+## Booking Flow Components
+
+### ServiceSelection
+
+Select a service from available options.
+
+```tsx
+import { ServiceSelection } from '@oviah/booking-components';
+
+<ServiceSelection
+  services={services}
+  categories={categories}
+  selectedService={selectedId}
+  onServiceSelect={(id) => setSelectedId(id)}
+  settings={{
+    headerContent: { value: 'Choose Your Service' },
+    serviceLayout: 'grid',
+    columns: 2
+  }}
+  colors={{ primary: '#D8C4FF', secondary: '#014421' }}
+/>
+```
+
+**Props:** See `types/index.ts` for full `ServiceSelectionStepProps`
+
+---
+
+### DateSelection
+
+Pick appointment date from calendar.
+
+```tsx
+import { DateSelection } from '@oviah/booking-components';
+
+<DateSelection
+  availableDates={['2025-01-15', '2025-01-16']}
+  selectedDate={selected}
+  onDateSelect={setSelected}
+  settings={{ calendarView: 'month' }}
+  colors={{ primary: '#D8C4FF', secondary: '#014421' }}
+/>
+```
+
+---
+
+### TimeSelection
+
+Choose appointment time slot.
+
+```tsx
+import { TimeSelection } from '@oviah/booking-components';
+
+<TimeSelection
+  availableTimes={['9:00 AM', '10:00 AM', '11:00 AM']}
+  selectedTime={selected}
+  onTimeSelect={setSelected}
+  settings={{ timeFormat: '12h', columns: 3 }}
+  serviceDuration={60}
+  colors={{ primary: '#D8C4FF', secondary: '#014421' }}
+/>
+```
+
+---
+
+### AddonsSelection
+
+Select optional add-on services.
+
+```tsx
+import { AddonsSelection } from '@oviah/booking-components';
+
+<AddonsSelection
+  addons={addons}
+  selectedAddons={selected}
+  onAddonsChange={setSelected}
+  settings={{ showPricing: true, showDuration: true }}
+  colors={{ primary: '#D8C4FF', secondary: '#014421' }}
+/>
+```
+
+---
+
+### ContactForm
+
+Collect customer contact information.
+
+```tsx
+import { ContactForm } from '@oviah/booking-components';
+
+<ContactForm
+  contactInfo={info}
+  onContactInfoChange={setInfo}
+  settings={{ headerContent: { value: 'Your Information' } }}
+  optInModules={modules}
+  onOptInData={handleOptIn}
+  colors={{ primary: '#D8C4FF', secondary: '#014421' }}
+/>
+```
+
+---
+
+### Confirmation
+
+Review and confirm booking with payment.
+
+```tsx
+import { Confirmation } from '@oviah/booking-components';
+
+<Confirmation
+  service={selectedService}
+  addons={selectedAddons}
+  selectedDate="2025-01-15"
+  selectedTime="10:00 AM"
+  paymentProvider="square"
+  paymentConfig={{ depositPercentage: 20 }}
+  onConfirm={handleConfirm}
+  colors={{ primary: '#D8C4FF', secondary: '#014421' }}
+/>
+```
+
+---
+
+## UI Components
+
+### BottomSheet
+
+Slide-up modal for forms and content.
+
+```tsx
+import { BottomSheet } from '@oviah/booking-components';
+
+<BottomSheet
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Form Title"
+  isRequired={false}
+  maxHeight="80vh"
+>
+  <YourFormContent />
+</BottomSheet>
+```
+
+**Props:**
+- `isOpen: boolean` - Control visibility
+- `onClose: () => void` - Close handler
+- `title?: string` - Modal title
+- `children: React.ReactNode` - Modal content
+- `isRequired?: boolean` - Prevent closing (no close button/escape)
+- `maxHeight?: string` - Maximum height (default: 80vh)
+
+---
+
+## Common Props
+
+### Colors Object
+
+```typescript
+{
+  primary: string;        // Main brand color
+  secondary: string;      // Secondary brand color
+  text: string;           // Text color
+  bookingText?: string;   // Booking widget text
+  linkBackground?: string;// Link button background
+  linkText?: string;      // Link button text
+  buttonText?: string;    // Button text color
+}
+```
+
+### Typography Object
+
+```typescript
+{
+  headingFont?: string;   // Font family for headings
+  bodyFont?: string;      // Font family for body text
+  bodySize?: string;      // Base font size
+}
+```
+
+### Settings Object
+
+Each step/section has specific settings. See `types/index.ts` for complete definitions.
+
+---
+
+## Animation Utilities
+
+Import animation helpers for consistent motion:
+
+```tsx
+import {
+  getSlideVariants,
+  getFadeVariants,
+  animations,
+  createEntranceAnimation,
+  shouldReduceMotion
+} from '@oviah/booking-components/styles';
+
+// Use with Framer Motion
+<motion.div {...createEntranceAnimation(0.1)}>
+  Content
+</motion.div>
+```
+
+**Available Functions:**
+- `getAnimationDuration(speed, reducedMotion)` - Calculate animation duration
+- `getSlideVariants(distance)` - Slide transition variants
+- `getFadeVariants()` - Fade transition variants
+- `getTransitionVariants(style, distance)` - Get variants by type
+- `createEntranceAnimation(delay, duration)` - Entry animation config
+- `createStaggerAnimation(count, baseDelay, increment)` - Stagger list items
+- `shouldReduceMotion()` - Check reduced motion preference
+
+---
+
+## Full Type Definitions
+
+See `types/index.ts` for complete TypeScript definitions of all props, interfaces, and types.