@bigz-app/booking-widget 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @bigz-app/booking-widget
+
+A flexible and themeable booking widget for BigZ Bookings in React.
+
+## Installation
+
+```bash
+pnpm install @bigz-app/booking-widget
+```
+
+## Quick Start
+
+Import the widget and provide the necessary configuration. The widget handles the entire booking flow, from event selection to payment.
+
+```tsx
+import { UniversalBookingWidget } from '@bigz-app/booking-widget';
+import type { UniversalBookingConfig } from '@bigz-app/booking-widget';
+
+const MyBookingPage = () => {
+  const config: UniversalBookingConfig = {
+    // Required
+    apiBaseUrl: "https://bigz.app",
+    organizationId: "your-org-id",
+
+    // Choose one event selection method
+    eventTypeId: 123,
+
+    // Optional theming
+    theme: "light-professional",
+  };
+
+  return <UniversalBookingWidget config={config} />;
+};
+```
+
+## Theming & Customization
+
+The widget includes several built-in themes and can be deeply customized.
+
+**Available Themes:**
+`light-fresh`, `light-elegant`, `light-vibrant`, `light-professional`, `dark-modern`, `dark-forest`, `dark-matrix`, `dark-luxury`, `dark-energetic`.
+
+**shadcn/ui Theme:**
+Use `theme: "shadcn"` to automatically adopt your existing `shadcn/ui` CSS variables. It seamlessly adapts to your site's light/dark mode.
+
+**Customizing a Theme:**
+You can override any theme's colors, border radius, or font family.
+
+```tsx
+const config = {
+  // ...
+  theme: "dark-modern", // Start with a base theme
+  colors: {
+    highlight: "#10b981",    // Custom accent: hex, rgb, or tailwind name ("emerald-500")
+    surface: "#1f2937",      // Custom card background ("gray-800")
+  },
+  borderRadius: "16px",      // e.g. "4px", "md"
+  fontFamily: "'Courier New', monospace", // Any valid CSS font-family
+};
+```
+
+## Configuration
+
+The widget is configured with a single object. You must provide `apiBaseUrl`, `organizationId`, and one event selection method.
+
+```typescript
+interface UniversalBookingConfig {
+  // --- Required ---
+  apiBaseUrl: string;       // Your booking system API base URL
+  organizationId: string;   // Your organization's ID
+
+  // --- Event Selection (choose ONE) ---
+  eventInstanceId?: number; // Directly book a specific instance
+  categoryId?: number;      // Show all event types in a category
+  eventTypeIds?: number[];  // Show a specific list of event types
+  eventTypeId?: number;     // Show instances for a single event type
+
+  // --- Theming & Customization ---
+  theme?: 'light-fresh' | 'light-elegant' | '...' | 'shadcn';
+  colors?: {
+    highlight?: string;     // Main action/accent color
+    background?: string;    // Page background
+    surface?: string;       // Card/surface background
+    text?: string;          // Main text color
+    border?: string;        // Border color
+  };
+  borderRadius?: string;    // e.g., "lg", "8px"
+  fontFamily?: string;      // e.g., "Inter", "system-ui"
+
+  // --- Optional ---
+  locale?: string;
+  onSuccess?: (result: any) => void;
+  onError?: (error: string) => void;
+}
+```
+
+## URL Parameter Overrides
+
+The widget can be configured dynamically using URL query parameters. These will override any props passed in the `config` object, which is useful for creating dynamic booking links.
+
+| Parameter        | Maps to Config   | Example URL           |
+|------------------|------------------|-----------------------|
+| `instanceId`     | `eventInstanceId`| `?instanceId=123`     |
+| `categoryId`     | `categoryId`     | `?categoryId=1`       |
+| `eventTypeId`    | `eventTypeId`    | `?eventTypeId=5`      |
+| `eventTypeIds`   | `eventTypeIds`   | `?eventTypeIds=1,3,5` |