npm - @bigz-app/booking-widget - Versions diffs - 0.3.11 → 1.0.0 - Mend

@bigz-app/booking-widget 0.3.11 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/README.md CHANGED Viewed

@@ -1,130 +1,242 @@
-# @bigz-app/booking-widget
+# bigZ Booking Widget
-A flexible and themeable booking widget for BigZ Bookings in React.
+A modern, customizable booking widget for bigZ Booking System built with React, TypeScript, and Tailwind CSS v4.
-## Installation
+## Features
-```bash
-pnpm install @bigz-app/booking-widget
-```
+- 🎯 **Multi-format support**: ESM, CommonJS, and UMD builds
+- ⚡ **Performance optimized**: Built with Preact for UMD, React for npm
+- 🎨 **Fully customizable**: Theme-based styling with CSS custom properties
+- 🌍 **Internationalization ready**: Support for multiple currencies and locales
+- 📱 **Responsive design**: Mobile-first approach with Tailwind CSS
+- 🔒 **Type-safe**: Full TypeScript support with strict type checking
+- 🧩 **Modular architecture**: Well-organized component structure
+- 💳 **Payment integration**: Stripe-powered payment processing
+- 🎫 **Discount system**: Voucher and gift card support
 ## Quick Start
-Import the widget and provide the necessary configuration. The widget handles the entire booking flow, from event selection to payment, with optional Google Ads conversion tracking.
+### For Vanilla JavaScript (UMD)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@bigz-app/booking-widget@latest/dist/styles.css">
+</head>
+<body>
+  <div id="booking-widget"></div>
+  <script src="https://cdn.jsdelivr.net/npm/@bigz-app/booking-widget@latest/dist/booking-widget.js"></script>
+  <script>
+    BigZBookingWidget.init({
+      target: '#booking-widget',
+      config: {
+        apiUrl: 'https://api.bigz.app',
+        locale: 'de',
+        currency: 'EUR',
+        theme: {
+          primary: '#007bff',
+          secondary: '#6c757d',
+          success: '#28a745',
+          warning: '#ffc107',
+          error: '#dc3545'
+        }
+      }
+    });
+  </script>
+</body>
+</html>
+```
+### For React Applications
+```bash
+npm install @bigz-app/booking-widget
+# or
+pnpm add @bigz-app/booking-widget
+```
 ```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",
+function App() {
+  const config = {
+    apiUrl: 'https://api.bigz.app',
+    locale: 'de',
+    currency: 'EUR',
+    // ... other config options
+  };
+  return <UniversalBookingWidget config={config} />;
+}
+```
+## Configuration
-    // Choose one event selection method
-    eventTypeId: 123,
+### UniversalBookingConfig
-    // Optional theming
-    theme: "light-professional",
+```typescript
+interface UniversalBookingConfig {
+  // API Configuration
+  apiUrl: string;
+  apiKey?: string;
+  // Localization
+  locale?: SupportedLocale; // 'de' | 'en'
+  currency?: CurrencyCode; // 'EUR' | 'USD' | 'GBP' | etc.
+  // Theming
+  theme?: {
+    surface?: string;
+    background?: string;
+    highlight?: string;
+    text?: string;
+    muted?: string;
+    border?: string;
+    success?: string;
+    warning?: string;
+    error?: string;
   };
-  return <UniversalBookingWidget config={config} />;
-};
+  // UI Options
+  view?: 'next-events' | 'button' | 'cards';
+  maxEvents?: number;
+  showPrices?: boolean;
+  showDescriptions?: boolean;
+  // Promo Dialog
+  promoDialog?: PromoDialogConfig;
+  // Callbacks
+  onBookingComplete?: (booking: BookingResult) => void;
+  onError?: (error: Error) => void;
+}
+```
+## Component Architecture
+```
+src/components/
+├── booking/          # Booking flow components
+│   ├── BookingForm.tsx
+│   ├── PaymentForm.tsx
+│   └── VoucherInput.tsx
+├── events/           # Event selection components
+│   ├── EventTypeSelection.tsx
+│   ├── EventInstanceSelection.tsx
+│   └── NextEventsPreview.tsx
+├── shared/           # Reusable UI components
+│   ├── Button.tsx
+│   ├── Input.tsx
+│   ├── Spinner.tsx
+│   └── skeletons/
+└── UniversalBookingWidget.tsx  # Main entry point
+```
+## Styling & Theming
+The widget uses Tailwind CSS v4 with CSS custom properties for theming. All colors, spacing, and typography can be customized through CSS variables:
+```css
+:root {
+  --bw-surface-color: #ffffff;
+  --bw-background-color: #f8f9fa;
+  --bw-highlight-color: #007bff;
+  --bw-text-color: #212529;
+  --bw-text-muted: #6c757d;
+  --bw-border-color: #dee2e6;
+  --bw-success-color: #28a745;
+  --bw-warning-color: #ffc107;
+  --bw-error-color: #dc3545;
+  --bw-border-radius: 8px;
+  --bw-font-family: system-ui, sans-serif;
+}
 ```
-## Theming & Customization
+## Development
-The widget includes several built-in themes and can be deeply customized.
+### Prerequisites
-**Available Themes:**
-`light-fresh`, `light-elegant`, `light-vibrant`, `light-professional`, `dark-modern`, `dark-forest`, `dark-matrix`, `dark-luxury`, `dark-energetic`.
+- Node.js 18+
+- pnpm
-**Customizing a Theme:**
-You can override any theme's colors, border radius, or font family.
+### Setup
-```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
-};
+```bash
+# Install dependencies
+pnpm install
+# Start development server
+pnpm dev
+# Build for production
+pnpm build
+# Run linting
+pnpm lint
+# Type checking
+pnpm exec tsc --noEmit
 ```
-## Configuration
+### Build Outputs
-The widget is configured with a single object. You must provide `apiBaseUrl`, `organizationId`, and one event selection method.
+- `dist/index.esm.js` - ES modules for modern bundlers
+- `dist/index.cjs` - CommonJS for Node.js
+- `dist/booking-widget.js` - UMD build with Preact for vanilla JS
+- `dist/styles.css` - Extracted CSS styles
-```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' | '...' ;
-  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"
+## API Reference
+### UniversalBookingWidget Props
-  // --- Optional ---
-  locale?: string;
-  onSuccess?: (result: any) => void;
-  onError?: (error: string) => void;
+```typescript
+interface UniversalBookingWidgetProps {
+  config: UniversalBookingConfig;
+  className?: string;
 }
 ```
-## URL Parameter Overrides
+### Supported Locales
-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.
+- `de` - German
+- `en` - English
-| Parameter        | Maps to Config   | Example URL           |
-|------------------|------------------|-----------------------|
-| `instanceId`     | `eventInstanceId`| `?instanceId=123`     |
-| `categoryId`     | `categoryId`     | `?categoryId=1`       |
-| `eventTypeId`    | `eventTypeId`    | `?eventTypeId=5`      |
-| `eventTypeIds`   | `eventTypeIds`   | `?eventTypeIds=1,3,5` |
+### Supported Currencies
-## Google Ads Conversion Tracking
+- `EUR` - Euro (€)
+- `USD` - US Dollar ($)
+- `GBP` - British Pound (£)
+- `CHF` - Swiss Franc (CHF)
+- `SEK` - Swedish Krona (kr)
+- `NOK` - Norwegian Krone (kr)
+- `DKK` - Danish Krone (kr)
+- `PLN` - Polish Zloty (zł)
+- `CZK` - Czech Koruna (Kč)
-The widget supports automatic Google Ads conversion tracking when payments are successful. This feature requires Google Consent Mode to be implemented on your website.
+## Browser Support
-```tsx
-const config = {
-  // ... your existing config
-  googleAds: {
-    tagId: 'AW-XXXXXXX',           // Your Google Ads Tag ID (required)
-    conversionId: 'booking_conversion', // Your conversion label (required)
-    conversionCurrency: 'EUR',     // Optional, defaults to 'EUR'
-    includeValue: true,             // Optional, defaults to true
-    consent: true // send the users consent to the widget when initializing.
-  }
-};
-```
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+## Contributing
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Ensure TypeScript compilation passes
+6. Submit a pull request
+## License
-**Key Features:**
-- ✅ Uses Google Consent Mode for proper consent management
-- ✅ Prevents duplicate gtag initialization
-- ✅ Includes booking value and transaction ID
-- ✅ Automatic error handling and fallbacks
+UNLICENSED - All rights reserved
-**Required:** You must implement [Google Consent Mode](https://developers.google.com/tag-platform/security/consent) on your website for tracking to work.
+## Bundle Size
-For detailed setup instructions, see [Google Ads Tracking Documentation](./docs/google-ads-tracking.md).
+- UMD: ~585KB (gzipped: ~150KB)
+- ESM: ~494KB (gzipped: ~130KB)
+- CSS: ~46KB (gzipped: ~8KB)