@bailierich/booking-components 2.0.0

package/docs/STYLING.md

@@ -0,0 +1,735 @@
+# Styling & Theme Customization
+
+Complete guide to customizing the appearance of `@oviah/booking-components`.
+
+## Table of Contents
+
+- [Theme Configuration](#theme-configuration)
+- [Color Schemes](#color-schemes)
+- [Typography](#typography)
+- [Custom CSS](#custom-css)
+- [Animations](#animations)
+- [Responsive Design](#responsive-design)
+- [Dark Mode](#dark-mode)
+- [Best Practices](#best-practices)
+
+---
+
+## Theme Configuration
+
+### Basic Theme Setup
+
+All components accept `colors` and `typography` props for theming:
+
+```tsx
+const theme = {
+  colors: {
+    primary: '#D8C4FF',
+    secondary: '#014421',
+    text: '#000000',
+    bookingText: '#1A1A1A',
+    linkBackground: '#D8C4FF',
+    linkText: '#FFFFFF',
+    buttonText: '#FFFFFF'
+  },
+  typography: {
+    headingFont: 'Geist Sans',
+    bodyFont: 'Inter',
+    bodySize: '16px'
+  }
+};
+
+// Use with any component
+<Hero
+  headline="Welcome"
+  colors={theme.colors}
+  typography={theme.typography}
+/>
+```
+
+### Global Theme Provider (Recommended)
+
+Create a theme context to avoid prop drilling:
+
+```tsx
+// contexts/ThemeContext.tsx
+import { createContext, useContext } from 'react';
+
+interface Theme {
+  colors: ColorScheme;
+  typography: TypographyConfig;
+}
+
+const ThemeContext = createContext<Theme | null>(null);
+
+export function ThemeProvider({ children, theme }: { children: React.ReactNode; theme: Theme }) {
+  return (
+    <ThemeContext.Provider value={theme}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const theme = useContext(ThemeContext);
+  if (!theme) throw new Error('useTheme must be used within ThemeProvider');
+  return theme;
+}
+
+// Usage
+<ThemeProvider theme={theme}>
+  <BookingFlow config={config} colors={theme.colors} />
+</ThemeProvider>
+```
+
+---
+
+## Color Schemes
+
+### Primary Colors
+
+Define your brand's main colors:
+
+```typescript
+interface ColorScheme {
+  primary: string;    // Main brand color
+  secondary: string;  // Secondary/accent color
+  text: string;       // Main text color
+}
+```
+
+**Examples:**
+
+```tsx
+// Purple & Green (Default OVIAH theme)
+const oviahTheme = {
+  primary: '#D8C4FF',
+  secondary: '#014421',
+  text: '#000000'
+};
+
+// Blue & Orange
+const blueOrangeTheme = {
+  primary: '#3B82F6',
+  secondary: '#F97316',
+  text: '#1F2937'
+};
+
+// Pink & Teal
+const pinkTealTheme = {
+  primary: '#EC4899',
+  secondary: '#14B8A6',
+  text: '#111827'
+};
+
+// Monochrome
+const monochromeTheme = {
+  primary: '#000000',
+  secondary: '#6B7280',
+  text: '#111827'
+};
+```
+
+### Extended Colors
+
+Additional colors for specific use cases:
+
+```typescript
+interface ExtendedColorScheme extends ColorScheme {
+  bookingText?: string;     // Text color in booking widget
+  linkBackground?: string;  // Link button background
+  linkText?: string;        // Link button text
+  buttonText?: string;      // Button text color
+}
+```
+
+**Example:**
+
+```tsx
+const extendedTheme = {
+  primary: '#D8C4FF',
+  secondary: '#014421',
+  text: '#000000',
+  bookingText: '#1A1A1A',      // Slightly softer than pure black
+  linkBackground: '#D8C4FF',    // Same as primary
+  linkText: '#FFFFFF',          // White text on colored buttons
+  buttonText: '#FFFFFF'         // White text on primary buttons
+};
+```
+
+### Color Utilities
+
+Helper functions for color manipulation:
+
+```typescript
+// Convert hex to RGBA
+function hexToRgba(hex: string, alpha: number): string {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+// Usage
+const transparentPrimary = hexToRgba(colors.primary, 0.1);
+```
+
+```typescript
+// Get contrast color (black or white) for backgrounds
+function getContrastColor(hexColor: string): string {
+  const hex = hexColor.replace('#', '');
+  const r = parseInt(hex.substr(0, 2), 16);
+  const g = parseInt(hex.substr(2, 2), 16);
+  const b = parseInt(hex.substr(4, 2), 16);
+  const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+  return luminance > 0.5 ? '#000000' : '#FFFFFF';
+}
+
+// Usage
+const textColor = getContrastColor(colors.primary);
+```
+
+---
+
+## Typography
+
+### Font Configuration
+
+```typescript
+interface TypographyConfig {
+  headingFont?: string;  // Font family for headings
+  bodyFont?: string;     // Font family for body text
+  bodySize?: string;     // Base font size
+}
+```
+
+### Loading Custom Fonts
+
+#### Using Google Fonts (Next.js)
+
+```tsx
+// app/layout.tsx
+import { Geist_Sans, Inter } from 'next/font/google';
+
+const geistSans = Geist_Sans({
+  subsets: ['latin'],
+  variable: '--font-geist-sans'
+});
+
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-inter'
+});
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${geistSans.variable} ${inter.variable}`}>
+      <body>{children}</body>
+    </html>
+  );
+}
+
+// Use in theme
+const theme = {
+  typography: {
+    headingFont: 'var(--font-geist-sans)',
+    bodyFont: 'var(--font-inter)',
+    bodySize: '16px'
+  }
+};
+```
+
+#### Using Custom Fonts
+
+```css
+/* globals.css */
+@font-face {
+  font-family: 'MyCustomFont';
+  src: url('/fonts/MyCustomFont.woff2') format('woff2');
+  font-weight: normal;
+  font-style: normal;
+}
+
+@font-face {
+  font-family: 'MyCustomFont';
+  src: url('/fonts/MyCustomFont-Bold.woff2') format('woff2');
+  font-weight: bold;
+  font-style: normal;
+}
+```
+
+```tsx
+const theme = {
+  typography: {
+    headingFont: 'MyCustomFont',
+    bodyFont: 'system-ui',
+    bodySize: '16px'
+  }
+};
+```
+
+### Font Size Scale
+
+Recommended font sizes for different screen sizes:
+
+```tsx
+const fontSizes = {
+  mobile: {
+    xs: '12px',
+    sm: '14px',
+    base: '16px',
+    lg: '18px',
+    xl: '20px',
+    '2xl': '24px',
+    '3xl': '30px'
+  },
+  tablet: {
+    xs: '12px',
+    sm: '14px',
+    base: '16px',
+    lg: '18px',
+    xl: '22px',
+    '2xl': '28px',
+    '3xl': '36px'
+  },
+  desktop: {
+    xs: '12px',
+    sm: '14px',
+    base: '16px',
+    lg: '20px',
+    xl: '24px',
+    '2xl': '32px',
+    '3xl': '48px'
+  }
+};
+```
+
+---
+
+## Custom CSS
+
+### Overriding Component Styles
+
+Use CSS custom properties (CSS variables) for easy overrides:
+
+```css
+/* globals.css */
+:root {
+  /* Override component spacing */
+  --booking-padding: 1.5rem;
+  --booking-gap: 1rem;
+
+  /* Override component sizes */
+  --button-height: 44px;
+  --input-height: 48px;
+
+  /* Override borders */
+  --border-radius: 12px;
+  --border-width: 2px;
+
+  /* Override shadows */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
+  --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.15);
+}
+```
+
+### Custom Wrapper Styles
+
+Wrap components with custom styling:
+
+```tsx
+<div className="custom-booking-wrapper">
+  <BookingFlow
+    config={config}
+    colors={colors}
+  />
+</div>
+
+<style jsx>{`
+  .custom-booking-wrapper {
+    max-width: 800px;
+    margin: 0 auto;
+    padding: 2rem;
+    background: linear-gradient(135deg, #f5f5f5 0%, #ffffff 100%);
+    border-radius: 24px;
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.1);
+  }
+
+  @media (max-width: 768px) {
+    .custom-booking-wrapper {
+      padding: 1rem;
+      border-radius: 16px;
+    }
+  }
+`}</style>
+```
+
+### Tailwind CSS Integration
+
+If using Tailwind CSS:
+
+```tsx
+<div className="max-w-4xl mx-auto p-6 bg-gradient-to-br from-purple-50 to-green-50 rounded-3xl shadow-2xl">
+  <BookingFlow
+    config={config}
+    colors={{
+      primary: '#D8C4FF',
+      secondary: '#014421',
+      text: '#000000'
+    }}
+  />
+</div>
+```
+
+---
+
+## Animations
+
+### Using Built-in Animations
+
+```tsx
+import {
+  createEntranceAnimation,
+  createStaggerAnimation,
+  getSlideVariants,
+  getFadeVariants
+} from '@oviah/booking-components/styles';
+
+// Entrance animation
+<motion.div {...createEntranceAnimation(0.2)}>
+  <Hero headline="Welcome" colors={colors} />
+</motion.div>
+
+// Stagger animation for lists
+const staggerConfig = createStaggerAnimation(items.length, 0.1, 0.05);
+
+{items.map((item, index) => (
+  <motion.div
+    key={item.id}
+    initial="hidden"
+    animate="visible"
+    variants={staggerConfig.variants}
+    transition={{ delay: staggerConfig.getDelay(index) }}
+  >
+    {item.content}
+  </motion.div>
+))}
+```
+
+### Custom Transition Speeds
+
+Configure animation speeds in BookingFlow:
+
+```tsx
+<BookingFlow
+  config={{
+    steps: { ... },
+    transitions: {
+      style: 'slide',      // 'slide' | 'fade'
+      speed: 'fast'        // 'fast' | 'normal' | 'slow'
+    }
+  }}
+  colors={colors}
+/>
+```
+
+### Respecting User Preferences
+
+The components automatically respect `prefers-reduced-motion`:
+
+```tsx
+// This is handled internally
+const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+const duration = reducedMotion ? 0.15 : 0.3;
+```
+
+---
+
+## Responsive Design
+
+### Breakpoints
+
+Components use these breakpoints:
+
+```typescript
+const breakpoints = {
+  sm: '640px',   // Mobile landscape
+  md: '768px',   // Tablet
+  lg: '1024px',  // Desktop
+  xl: '1280px',  // Large desktop
+  '2xl': '1536px' // Extra large
+};
+```
+
+### Responsive Layouts
+
+#### Service Selection
+
+```tsx
+<ServiceSelection
+  settings={{
+    serviceLayout: 'grid',
+    columns: 2  // 1 col on mobile, 2 on tablet+
+  }}
+  colors={colors}
+/>
+```
+
+#### Gallery
+
+```tsx
+<Gallery
+  columns={3}  // Responsive: 2 cols on mobile, 3 on tablet+
+  images={images}
+  colors={colors}
+/>
+```
+
+### Mobile-First Considerations
+
+```css
+/* Mobile-first approach */
+.booking-container {
+  padding: 1rem;
+  font-size: 14px;
+}
+
+@media (min-width: 768px) {
+  .booking-container {
+    padding: 2rem;
+    font-size: 16px;
+  }
+}
+
+@media (min-width: 1024px) {
+  .booking-container {
+    padding: 3rem;
+    font-size: 18px;
+  }
+}
+```
+
+---
+
+## Dark Mode
+
+### Implementing Dark Mode
+
+```tsx
+'use client';
+
+import { useState, useEffect } from 'react';
+
+function useDarkMode() {
+  const [isDark, setIsDark] = useState(false);
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    setIsDark(mediaQuery.matches);
+
+    const handler = (e: MediaQueryListEvent) => setIsDark(e.matches);
+    mediaQuery.addEventListener('change', handler);
+    return () => mediaQuery.removeEventListener('change', handler);
+  }, []);
+
+  return isDark;
+}
+
+// Usage
+export function BookingWithDarkMode() {
+  const isDark = useDarkMode();
+
+  const lightTheme = {
+    colors: {
+      primary: '#D8C4FF',
+      secondary: '#014421',
+      text: '#000000',
+      bookingText: '#1A1A1A'
+    }
+  };
+
+  const darkTheme = {
+    colors: {
+      primary: '#B8A4DF',
+      secondary: '#02652F',
+      text: '#FFFFFF',
+      bookingText: '#E5E5E5'
+    }
+  };
+
+  const theme = isDark ? darkTheme : lightTheme;
+
+  return (
+    <div style={{
+      backgroundColor: isDark ? '#1A1A1A' : '#FFFFFF',
+      minHeight: '100vh'
+    }}>
+      <BookingFlow
+        config={config}
+        colors={theme.colors}
+      />
+    </div>
+  );
+}
+```
+
+### Dark Mode Color Palettes
+
+```typescript
+const themes = {
+  light: {
+    colors: {
+      primary: '#D8C4FF',
+      secondary: '#014421',
+      text: '#000000',
+      background: '#FFFFFF',
+      surface: '#F9FAFB'
+    }
+  },
+  dark: {
+    colors: {
+      primary: '#B8A4DF',
+      secondary: '#02652F',
+      text: '#FFFFFF',
+      background: '#1A1A1A',
+      surface: '#2D2D2D'
+    }
+  }
+};
+```
+
+---
+
+## Best Practices
+
+### 1. Use CSS Variables for Consistency
+
+```css
+:root {
+  --primary-color: #D8C4FF;
+  --secondary-color: #014421;
+  --text-color: #000000;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 2rem;
+}
+```
+
+### 2. Maintain WCAG Contrast Ratios
+
+```tsx
+// Ensure sufficient contrast (minimum 4.5:1 for normal text)
+const colors = {
+  primary: '#D8C4FF',
+  text: '#000000'  // Good contrast against white backgrounds
+};
+
+// For text on colored backgrounds
+const buttonStyles = {
+  backgroundColor: colors.primary,
+  color: getContrastColor(colors.primary)  // Automatically white or black
+};
+```
+
+### 3. Test on Multiple Devices
+
+```tsx
+// Use responsive testing
+const testSizes = {
+  mobile: '375px',
+  tablet: '768px',
+  desktop: '1440px'
+};
+```
+
+### 4. Keep Brand Consistency
+
+```tsx
+// Create a brand constants file
+export const BRAND_COLORS = {
+  primary: '#D8C4FF',
+  secondary: '#014421',
+  accent: '#FF6F61'
+} as const;
+
+export const BRAND_FONTS = {
+  heading: 'Geist Sans',
+  body: 'Inter'
+} as const;
+
+// Use throughout your app
+<BookingFlow
+  config={config}
+  colors={BRAND_COLORS}
+/>
+```
+
+### 5. Optimize for Performance
+
+```tsx
+// Lazy load heavy components
+import dynamic from 'next/dynamic';
+
+const BookingFlow = dynamic(
+  () => import('@oviah/booking-components').then(mod => mod.BookingFlow),
+  { ssr: false }
+);
+```
+
+---
+
+## Example: Complete Custom Theme
+
+```tsx
+// theme.ts
+export const customTheme = {
+  colors: {
+    primary: '#8B5CF6',      // Violet
+    secondary: '#10B981',     // Emerald
+    text: '#111827',          // Gray 900
+    bookingText: '#374151',   // Gray 700
+    linkBackground: '#8B5CF6',
+    linkText: '#FFFFFF',
+    buttonText: '#FFFFFF'
+  },
+  typography: {
+    headingFont: 'Poppins',
+    bodyFont: 'Inter',
+    bodySize: '16px'
+  },
+  spacing: {
+    container: '1.5rem',
+    section: '4rem',
+    element: '1rem'
+  },
+  borderRadius: {
+    sm: '8px',
+    md: '12px',
+    lg: '16px',
+    full: '9999px'
+  },
+  shadows: {
+    sm: '0 1px 2px rgba(0, 0, 0, 0.05)',
+    md: '0 4px 6px rgba(0, 0, 0, 0.1)',
+    lg: '0 10px 15px rgba(0, 0, 0, 0.15)',
+    xl: '0 20px 25px rgba(0, 0, 0, 0.15)'
+  }
+};
+
+// Use throughout your app
+<ThemeProvider theme={customTheme}>
+  <BookingFlow
+    config={config}
+    colors={customTheme.colors}
+  />
+</ThemeProvider>
+```
+
+---
+
+## See Also
+
+- [DATA_SHAPES.md](./DATA_SHAPES.md) - Data structures
+- [API.md](./API.md) - Component API reference
+- [CALLBACKS.md](./CALLBACKS.md) - Event handling

package/index.ts

@@ -0,0 +1,4 @@
+// Main package exports
+export * from './components';
+export * from './types';
+export * from './styles';