@tebuto/react-booking-widget 1.0.5 → 1.1.0

package/dist/types.d.ts

@@ -1,10 +1,49 @@
-import { JSX } from 'react';
+import { JSX, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
+/**
+ * Theme configuration for the Tebuto Booking Widget.
+ * All colors should be valid CSS color strings (e.g., '#00B4A9', 'rgb(0, 180, 169)').
+ *
+ * Note: The widget automatically generates color variations (light, dark, etc.)
+ * from the primaryColor, so only the base colors need to be configured.
+ */
+type TebutoWidgetTheme = {
+    /** Primary brand color - used for buttons, highlights, selected states */
+    primaryColor?: string;
+    /** Main widget background color */
+    backgroundColor?: string;
+    /** Main text color */
+    textPrimary?: string;
+    /** Secondary/muted text color */
+    textSecondary?: string;
+    /** General border color */
+    borderColor?: string;
+    /** Widget font family */
+    fontFamily?: string;
+    /** Inherit font from parent page instead of using widget font */
+    inheritFont?: boolean;
+};
+/**
+ * Configuration options for the Tebuto Booking Widget.
+ */
 type TebutoBookingWidgetConfiguration = {
+    /** UUID of the therapist whose calendar should be displayed (required) */
     therapistUUID: string;
+    /** Background color of the widget (shorthand for theme.backgroundColor) */
     backgroundColor?: string;
+    /** Array of category IDs to filter available appointments */
     categories?: number[];
+    /** Whether to display a border around the widget (default: true) */
     border?: boolean;
+    /** Include subuser appointments in the calendar (default: false) */
+    includeSubusers?: boolean;
+    /** Show quick filter buttons for time slots (default: false) */
+    showQuickFilters?: boolean;
+    /** Inherit font from parent page instead of using widget font (default: false) */
+    inheritFont?: boolean;
+    /** Theme configuration for customizing colors and fonts */
+    theme?: TebutoWidgetTheme;
 };
 
 type TebutoBookingWidgetProps = {
@@ -12,5 +51,456 @@ type TebutoBookingWidgetProps = {
 } & TebutoBookingWidgetConfiguration;
 declare function TebutoBookingWidget({ noScriptText, ...config }: TebutoBookingWidgetProps): JSX.Element;
 
-export { TebutoBookingWidget };
-export type { TebutoBookingWidgetConfiguration };
+type CustomBookingExampleProps = {
+    therapistUUID: string;
+    categories?: number[];
+};
+/**
+ * CustomBookingExample - A modern, fully-featured booking interface
+ *
+ * This example demonstrates how to use the Tebuto hooks to build
+ * a completely custom booking experience.
+ *
+ * @example
+ * ```tsx
+ * import { CustomBookingExample } from '@tebuto/react-booking-widget'
+ *
+ * function BookingPage() {
+ *   return <CustomBookingExample therapistUUID="your-uuid" />
+ * }
+ * ```
+ */
+declare function CustomBookingExample({ therapistUUID, categories }: CustomBookingExampleProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * API Types for Tebuto Booking Hooks
+ * These types represent the data structures returned by the Tebuto API.
+ */
+/** Location type for appointments */
+type AppointmentLocation = 'virtual' | 'onsite' | 'not-fixed';
+/** Address structure for therapist/location */
+type Address = {
+    streetAndNumber: string;
+    additionalInformation?: string;
+    city: {
+        name: string;
+        zip: string;
+    };
+};
+/** Therapist information */
+type Therapist = {
+    name: string;
+    firstName: string;
+    lastName: string;
+    address: Address;
+    showWatermark: boolean;
+};
+/** Therapist reference in events */
+type TherapistReference = {
+    id: number;
+    uuid: string;
+    name: string;
+};
+/** Available time slot / event */
+type TimeSlot = {
+    title: string;
+    start: string;
+    end: string;
+    location: AppointmentLocation;
+    color: string;
+    price: string;
+    taxRate: string;
+    outageFeeEnabled: boolean;
+    outageFeeHours: number;
+    outageFeePrice: number;
+    eventRuleId: number;
+    eventCategoryId: number;
+    paymentEnabled: boolean;
+    paymentDuringBooking: boolean;
+    therapist: TherapistReference;
+};
+/** Response from claim endpoint */
+type ClaimResponse = {
+    isAvailable: boolean;
+    requirePhoneNumber: boolean;
+    requireAddress: boolean;
+};
+/** Payment configuration */
+type PaymentConfiguration = {
+    paymentTypes: string[];
+    onlinePaymentMethods: string[];
+};
+/** Client information for booking */
+type ClientInfo = {
+    firstName: string;
+    lastName: string;
+    email: string;
+    phone?: string;
+    address?: {
+        streetAndNumber: string;
+        additionalInformation?: string;
+        city: string;
+        zip: string;
+    };
+    notes?: string;
+};
+/** Booking request payload */
+type BookingRequest = {
+    start: string;
+    end: string;
+    eventRuleId: number;
+    locationSelection: AppointmentLocation;
+    client: ClientInfo;
+};
+/** Booking response */
+type BookingResponse = {
+    id: number;
+    createdAt: string;
+    locationSelection: AppointmentLocation;
+    isConfirmed: boolean;
+    isOutage: boolean;
+    ics: string;
+};
+/** Hook state for async operations */
+type AsyncState<T> = {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+/** Category for filtering */
+type EventCategory = {
+    id: number;
+    name: string;
+    color: string;
+    price: string;
+    location: AppointmentLocation;
+};
+/** Grouped time slots by date */
+type SlotsByDate = {
+    [date: string]: TimeSlot[];
+};
+/** Time slot with additional computed properties */
+type EnrichedTimeSlot = TimeSlot & {
+    dateKey: string;
+    timeString: string;
+    durationMinutes: number;
+    formattedPrice: string;
+    isToday: boolean;
+    isPast: boolean;
+};
+
+type TebutoConfig = {
+    therapistUUID: string;
+    apiBaseUrl: string;
+    categories?: number[];
+    includeSubusers?: boolean;
+};
+type TebutoContextValue = TebutoConfig & {
+    buildUrl: (path: string) => string;
+};
+type TebutoProviderProps = {
+    therapistUUID: string;
+    apiBaseUrl?: string;
+    categories?: number[];
+    includeSubusers?: boolean;
+    children: ReactNode;
+};
+/**
+ * TebutoProvider - Context provider for Tebuto booking hooks
+ *
+ * Wrap your booking components with this provider to share configuration
+ * across all Tebuto hooks.
+ *
+ * @example
+ * ```tsx
+ * <TebutoProvider therapistUUID="your-uuid">
+ *   <YourBookingComponent />
+ * </TebutoProvider>
+ * ```
+ */
+declare function TebutoProvider({ therapistUUID, apiBaseUrl, categories, includeSubusers, children }: TebutoProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * useTebutoContext - Access the Tebuto configuration context
+ *
+ * Must be used within a TebutoProvider.
+ *
+ * @throws Error if used outside of TebutoProvider
+ */
+declare function useTebutoContext(): TebutoContextValue;
+
+type UseTherapistReturn = AsyncState<Therapist> & {
+    refetch: () => Promise<void>;
+};
+/**
+ * useTherapist - Fetch therapist information
+ *
+ * Automatically fetches the therapist data when the component mounts.
+ * Uses the therapistUUID from the TebutoProvider context.
+ *
+ * @example
+ * ```tsx
+ * const { data: therapist, isLoading, error } = useTherapist()
+ *
+ * if (isLoading) return <Spinner />
+ * if (error) return <Error message={error.message} />
+ *
+ * return <h1>Book with {therapist.name}</h1>
+ * ```
+ */
+declare function useTherapist(): UseTherapistReturn;
+
+type UseAvailableSlotsOptions = {
+    /** Auto-fetch on mount (default: true) */
+    autoFetch?: boolean;
+    /** Filter by specific category IDs */
+    categories?: number[];
+};
+type UseAvailableSlotsReturn = AsyncState<TimeSlot[]> & {
+    /** Refetch available slots */
+    refetch: () => Promise<void>;
+    /** Slots grouped by date (YYYY-MM-DD) */
+    slotsByDate: SlotsByDate;
+    /** All unique dates with available slots */
+    availableDates: Date[];
+    /** Get enriched slots for a specific date */
+    getSlotsForDate: (date: Date) => EnrichedTimeSlot[];
+    /** All unique categories from available slots */
+    categories: Array<{
+        id: number;
+        name: string;
+        color: string;
+    }>;
+    /** Total count of available slots */
+    totalSlots: number;
+};
+/**
+ * useAvailableSlots - Fetch and manage available time slots
+ *
+ * Provides available appointment slots with helpers for grouping,
+ * filtering, and date navigation.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   slotsByDate,
+ *   availableDates,
+ *   getSlotsForDate,
+ *   isLoading
+ * } = useAvailableSlots()
+ *
+ * const [selectedDate, setSelectedDate] = useState<Date | null>(null)
+ *
+ * return (
+ *   <div>
+ *     <DatePicker dates={availableDates} onSelect={setSelectedDate} />
+ *     {selectedDate && (
+ *       <TimeSlotList slots={getSlotsForDate(selectedDate)} />
+ *     )}
+ *   </div>
+ * )
+ * ```
+ */
+declare function useAvailableSlots(options?: UseAvailableSlotsOptions): UseAvailableSlotsReturn;
+
+type ClaimState = {
+    claimedSlot: TimeSlot | null;
+    claimResponse: ClaimResponse | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+type UseClaimSlotReturn = ClaimState & {
+    /** Claim a time slot to reserve it temporarily */
+    claim: (slot: TimeSlot) => Promise<ClaimResponse | null>;
+    /** Release the currently claimed slot */
+    unclaim: () => Promise<void>;
+    /** Check if a specific slot is currently claimed */
+    isClaimed: (slot: TimeSlot) => boolean;
+    /** Clear error state */
+    clearError: () => void;
+};
+/**
+ * useClaimSlot - Temporarily claim a time slot
+ *
+ * Claims a time slot to reserve it while the user fills out
+ * their booking information. Automatically handles unclaiming
+ * when claiming a new slot.
+ *
+ * @example
+ * ```tsx
+ * const { claim, unclaim, claimedSlot, claimResponse, isLoading } = useClaimSlot()
+ *
+ * const handleSlotSelect = async (slot: TimeSlot) => {
+ *   const response = await claim(slot)
+ *   if (response?.isAvailable) {
+ *     setStep('booking-form')
+ *   }
+ * }
+ *
+ * const handleCancel = () => {
+ *   unclaim()
+ *   setStep('slot-selection')
+ * }
+ * ```
+ */
+declare function useClaimSlot(): UseClaimSlotReturn;
+
+type BookingState = {
+    booking: BookingResponse | null;
+    isLoading: boolean;
+    error: Error | null;
+    isSuccess: boolean;
+};
+type BookAppointmentParams = {
+    slot: TimeSlot;
+    client: ClientInfo;
+    locationSelection?: AppointmentLocation;
+};
+type UseBookAppointmentReturn = BookingState & {
+    /** Book the appointment */
+    book: (params: BookAppointmentParams) => Promise<BookingResponse | null>;
+    /** Reset the booking state */
+    reset: () => void;
+    /** Download the calendar file (.ics) */
+    downloadCalendar: () => void;
+};
+/**
+ * useBookAppointment - Complete the booking process
+ *
+ * Submits the booking with client information and handles
+ * the response including calendar download.
+ *
+ * @example
+ * ```tsx
+ * const { book, booking, isLoading, isSuccess, downloadCalendar, reset } = useBookAppointment()
+ *
+ * const handleSubmit = async (clientInfo: ClientInfo) => {
+ *   const result = await book({
+ *     slot: claimedSlot,
+ *     client: clientInfo,
+ *     locationSelection: selectedLocation
+ *   })
+ *
+ *   if (result) {
+ *     setStep('confirmation')
+ *   }
+ * }
+ *
+ * if (isSuccess) {
+ *   return (
+ *     <SuccessMessage>
+ *       <button onClick={downloadCalendar}>Add to Calendar</button>
+ *       <button onClick={reset}>Book Another</button>
+ *     </SuccessMessage>
+ *   )
+ * }
+ * ```
+ */
+declare function useBookAppointment(): UseBookAppointmentReturn;
+
+type BookingStep = 'loading' | 'date-selection' | 'time-selection' | 'booking-form' | 'confirmation' | 'error';
+type UseBookingFlowOptions = {
+    /** Categories to filter by */
+    categories?: number[];
+    /** Callback when booking is complete */
+    onBookingComplete?: (booking: BookingResponse) => void;
+    /** Callback on any error */
+    onError?: (error: Error) => void;
+};
+type UseBookingFlowReturn = {
+    /** Current booking step */
+    step: BookingStep;
+    /** Go to a specific step */
+    goToStep: (step: BookingStep) => void;
+    /** Therapist information */
+    therapist: ReturnType<typeof useTherapist>;
+    /** Available slots management */
+    slots: ReturnType<typeof useAvailableSlots>;
+    /** Selected date */
+    selectedDate: Date | null;
+    /** Select a date */
+    selectDate: (date: Date | null) => void;
+    /** Slots for the selected date */
+    selectedDateSlots: EnrichedTimeSlot[];
+    /** Selected time slot */
+    selectedSlot: TimeSlot | null;
+    /** Select a time slot (claims it) */
+    selectSlot: (slot: TimeSlot | null) => Promise<boolean>;
+    /** Selected location (for not-fixed appointments) */
+    selectedLocation: AppointmentLocation | null;
+    /** Set the location selection */
+    setLocation: (location: AppointmentLocation) => void;
+    /** Claim state */
+    claim: ReturnType<typeof useClaimSlot>;
+    /** Booking state */
+    booking: ReturnType<typeof useBookAppointment>;
+    /** Submit booking with client info */
+    submitBooking: (client: ClientInfo) => Promise<boolean>;
+    /** Start over from the beginning */
+    reset: () => void;
+    /** Overall loading state */
+    isLoading: boolean;
+    /** Current error if any */
+    error: Error | null;
+};
+/**
+ * useBookingFlow - Complete booking flow orchestration
+ *
+ * A convenience hook that combines all booking hooks and manages
+ * the booking flow state. Perfect for quickly building a booking UI.
+ *
+ * @example
+ * ```tsx
+ * function BookingPage() {
+ *   const {
+ *     step,
+ *     therapist,
+ *     slots,
+ *     selectedDate,
+ *     selectDate,
+ *     selectedDateSlots,
+ *     selectSlot,
+ *     submitBooking,
+ *     booking,
+ *     reset
+ *   } = useBookingFlow()
+ *
+ *   switch (step) {
+ *     case 'loading':
+ *       return <LoadingSpinner />
+ *
+ *     case 'date-selection':
+ *       return (
+ *         <DatePicker
+ *           availableDates={slots.availableDates}
+ *           onSelect={selectDate}
+ *         />
+ *       )
+ *
+ *     case 'time-selection':
+ *       return (
+ *         <TimeSlotPicker
+ *           slots={selectedDateSlots}
+ *           onSelect={selectSlot}
+ *         />
+ *       )
+ *
+ *     case 'booking-form':
+ *       return (
+ *         <BookingForm onSubmit={submitBooking} />
+ *       )
+ *
+ *     case 'confirmation':
+ *       return (
+ *         <Confirmation
+ *           booking={booking.booking}
+ *           onReset={reset}
+ *         />
+ *       )
+ *   }
+ * }
+ * ```
+ */
+declare function useBookingFlow(options?: UseBookingFlowOptions): UseBookingFlowReturn;
+
+export { CustomBookingExample, TebutoBookingWidget, TebutoProvider, useAvailableSlots, useBookAppointment, useBookingFlow, useClaimSlot, useTebutoContext, useTherapist };
+export type { Address, AppointmentLocation, AsyncState, BookingRequest, BookingResponse, ClaimResponse, ClientInfo, EnrichedTimeSlot, EventCategory, PaymentConfiguration, SlotsByDate, TebutoBookingWidgetConfiguration, TebutoWidgetTheme, Therapist, TherapistReference, TimeSlot };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tebuto/react-booking-widget",
-    "version": "1.0.5",
+    "version": "1.1.0",
     "description": "React Component for the Tebuto Booking Widget",
     "author": "Tebuto GmbH",
     "homepage": "https://tebuto.de",
@@ -9,6 +9,8 @@
     "module": "dist/esm/index.js",
     "types": "dist/types.d.ts",
     "scripts": {
+        "dev": "storybook dev -p 6006",
+        "build:storybook": "storybook build",
         "test": "jest",
         "build": "rollup -c --bundleConfigAsCjs",
         "prepare": "husky",
@@ -21,30 +23,39 @@
         "react-dom": "^19.0.0"
     },
     "devDependencies": {
-        "@babel/core": "7.27.4",
-        "@babel/preset-env": "7.27.2",
-        "@babel/preset-react": "7.27.1",
-        "@babel/preset-typescript": "7.27.1",
-        "@biomejs/biome": "1.9.4",
-        "@rollup/plugin-commonjs": "28.0.3",
-        "@rollup/plugin-node-resolve": "16.0.1",
+        "@babel/core": "7.28.5",
+        "@babel/preset-env": "7.28.5",
+        "@babel/preset-react": "7.28.5",
+        "@babel/preset-typescript": "7.28.5",
+        "@biomejs/biome": "2.3.10",
+        "@rollup/plugin-commonjs": "29.0.0",
+        "@rollup/plugin-node-resolve": "16.0.3",
         "@rollup/plugin-terser": "0.4.4",
-        "@rollup/plugin-typescript": "12.1.2",
-        "@testing-library/react": "16.3.0",
-        "@types/jest": "29.5.14",
-        "@types/react": "19.1.6",
-        "babel-jest": "29.7.0",
+        "@rollup/plugin-typescript": "12.3.0",
+        "@storybook/react": "^10.1.10",
+        "@storybook/react-vite": "^10.1.10",
+        "@testing-library/react": "16.3.1",
+        "@types/jest": "30.0.0",
+        "@types/react": "19.2.7",
+        "@vitejs/plugin-react": "^5.1.2",
+        "babel-jest": "30.2.0",
         "husky": "9.1.7",
-        "jest": "29.7.0",
-        "jest-environment-jsdom": "29.7.0",
-        "rollup": "4.41.1",
-        "rollup-plugin-dts": "6.2.1",
+        "jest": "30.2.0",
+        "jest-environment-jsdom": "30.2.0",
+        "msw": "^2.12.6",
+        "rollup": "4.54.0",
+        "rollup-plugin-dts": "6.3.0",
         "rollup-plugin-peer-deps-external": "2.2.4",
+        "storybook": "^10.1.10",
         "tslib": "2.8.1",
-        "typescript": "5.8.3"
+        "typescript": "5.9.3",
+        "vite": "^7.3.0"
     },
     "jest": {
-        "testEnvironment": "jsdom"
+        "testEnvironment": "jsdom",
+        "setupFilesAfterEnv": [
+            "<rootDir>/src/setupTests.ts"
+        ]
     },
     "babel": {
         "presets": [
@@ -66,10 +77,25 @@
         "url": "https://github.com/tebuto/react-booking-widget/issues"
     },
     "engines": {
-        "node": ">=22"
+        "node": ">=24"
     },
-    "keywords": ["appointment", "booking", "calendar", "react", "tebuto", "widget", "online", "therapist", "psychologist"],
+    "keywords": [
+        "appointment",
+        "booking",
+        "calendar",
+        "react",
+        "tebuto",
+        "widget",
+        "online",
+        "therapist",
+        "psychologist"
+    ],
     "publishConfig": {
         "access": "public"
+    },
+    "msw": {
+        "workerDirectory": [
+            "public"
+        ]
     }
 }

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - unrs-resolver

package/vite.config.ts

@@ -0,0 +1,6 @@
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+    plugins: [react()]
+})