@wix/headless-bookings 0.0.42 → 0.0.44

package/cjs/dist/services/location-list/location-list.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Location List Service Implementation
+ * Manages location state, auto-detection, and BookingService integration
+ *
+ * @module Services/LocationList
+ */
+import type { ServiceFactoryConfig } from '@wix/services-definitions';
+import { type LocationData } from './location-list.def.js';
+/**
+ * Configuration interface for LocationListService
+ */
+export interface LocationListServiceConfig {
+    /** Locations array (can include any type: BUSINESS, CUSTOM, CUSTOMER) */
+    locations?: LocationData[];
+    /** Explicit flag for custom locations (overrides auto-detection) */
+    hasCustomLocations?: boolean;
+    /** Explicit flag for customer locations (overrides auto-detection) */
+    hasCustomerLocations?: boolean;
+}
+/**
+ * Implementation of the LocationList service
+ * Manages location state and integrates with BookingService for selection (optional)
+ */
+export declare const LocationListService: import("@wix/services-definitions").ServiceFactory<string & {
+    __api: import("./location-list.def.js").LocationListServiceAPI;
+    __config: {};
+    isServiceDefinition?: boolean;
+} & import("./location-list.def.js").LocationListServiceAPI, LocationListServiceConfig>;
+/**
+ * Result type for SSR loader
+ */
+export type LoadLocationListServiceResult = {
+    type: 'success';
+    config: LocationListServiceConfig;
+} | {
+    type: 'error';
+    error: string;
+};
+/**
+ * SSR Loader: Fetches locations from API for server-side rendering.
+ *
+ * @param options - Optional configuration
+ * @returns Configuration result for LocationListService with pre-fetched locations
+ *
+ * @example
+ * ```typescript
+ * // Fetch from API
+ * const result = await loadLocationListServiceInitialData();
+ *
+ * if (result.type === 'error') {
+ *   return Astro.redirect('/500');
+ * }
+ *
+ * const locationListConfig = result.config;
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Pass locations directly (e.g., from service.locations)
+ * const result = await loadLocationListServiceInitialData({
+ *   locations: service.locations,
+ *   // hasCustom/hasCustomer will be auto-detected from array
+ * });
+ * ```
+ */
+export declare function loadLocationListServiceInitialData(options?: {
+    /** Pass locations directly instead of fetching */
+    locations?: LocationData[];
+    /** Explicit flag for custom locations */
+    hasCustomLocations?: boolean;
+    /** Explicit flag for customer locations */
+    hasCustomerLocations?: boolean;
+}): Promise<LoadLocationListServiceResult>;
+/**
+ * Service binding helper for LocationListService.
+ * Bundles definition, implementation, and config for ServicesManager.
+ *
+ * @param servicesConfigs - Object containing LocationListServiceDefinition config
+ * @returns Tuple of [Definition, Implementation, Config] for addService()
+ *
+ * @example
+ * ```typescript
+ * const servicesManager = createServicesManager(
+ *   createServicesMap()
+ *     .addService(...locationListServiceBinding(configs))
+ * );
+ * ```
+ */
+export declare const locationListServiceBinding: <T extends {
+    [key: string]: LocationListServiceConfig;
+}>(servicesConfigs: T) => readonly [string & {
+    __api: import("./location-list.def.js").LocationListServiceAPI;
+    __config: {};
+    isServiceDefinition?: boolean;
+} & import("./location-list.def.js").LocationListServiceAPI, import("@wix/services-definitions").ServiceFactory<string & {
+    __api: import("./location-list.def.js").LocationListServiceAPI;
+    __config: {};
+    isServiceDefinition?: boolean;
+} & import("./location-list.def.js").LocationListServiceAPI, LocationListServiceConfig>, LocationListServiceConfig];
+export { LocationListServiceDefinition, LocationType, type LocationData, type DisplayLocation, type LocationListActions, type LocationListServiceAPI, } from './location-list.def.js';

package/cjs/dist/services/location-list/location-list.def.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Location List Service Definition
+ * Defines types and service interface for managing location lists
+ *
+ * @module Services/LocationList/Definition
+ */
+import type { Signal, ReadOnlySignal } from '@wix/services-definitions/core-services/signals';
+import { LocationType, type Service } from '@wix/auto_sdk_bookings_services';
+/**
+ * LocationData type - from Service['locations'][number]
+ */
+export type LocationData = NonNullable<Service['locations']>[number];
+/**
+ * Display location wrapper - includes metadata for rendering
+ */
+export interface DisplayLocation {
+    /** Original location data, null for synthetic entries */
+    location: LocationData | null;
+    /** Location type */
+    type: LocationType;
+    /** True if created from flag (not from array) */
+    isSynthetic: boolean;
+    /** Unique ID for list rendering */
+    id: string;
+}
+/**
+ * Actions interface for location list management
+ */
+export interface LocationListActions {
+    /** Select a location (updates BookingService.location if available) */
+    select: (displayLocation: DisplayLocation) => void;
+}
+/**
+ * API interface for the LocationList service
+ */
+export interface LocationListServiceAPI {
+    /** Reactive signal containing the raw locations array */
+    locations: Signal<LocationData[]>;
+    /** Reactive signal containing the display locations (processed for UI) */
+    displayLocations: ReadOnlySignal<DisplayLocation[]>;
+    /** Whether custom locations exist */
+    hasCustomLocations: ReadOnlySignal<boolean>;
+    /** Whether customer locations exist */
+    hasCustomerLocations: ReadOnlySignal<boolean>;
+    /** Reactive signal indicating if locations are loading */
+    isLoading: Signal<boolean>;
+    /** Reactive signal containing any error message */
+    error: Signal<string | null>;
+    /** Computed signal for selected location (from BookingService, null if standalone) */
+    selectedLocation: ReadOnlySignal<LocationData | null>;
+    /** Actions for location management */
+    actions: LocationListActions;
+}
+/**
+ * Service definition for LocationList
+ */
+export declare const LocationListServiceDefinition: string & {
+    __api: LocationListServiceAPI;
+    __config: {};
+    isServiceDefinition?: boolean;
+} & LocationListServiceAPI;
+export { LocationType };

package/cjs/dist/services/location-list/location-list.def.js

@@ -0,0 +1,17 @@
+/**
+ * Location List Service Definition
+ * Defines types and service interface for managing location lists
+ *
+ * @module Services/LocationList/Definition
+ */
+import { defineService } from '@wix/services-definitions';
+import { LocationType } from '@wix/auto_sdk_bookings_services';
+// ============================================================================
+// Service Definition
+// ============================================================================
+/**
+ * Service definition for LocationList
+ */
+export const LocationListServiceDefinition = defineService('location-list');
+// Re-export LocationType for consumers
+export { LocationType };

package/cjs/dist/services/location-list/location-list.js

@@ -0,0 +1,212 @@
+/**
+ * Location List Service Implementation
+ * Manages location state, auto-detection, and BookingService integration
+ *
+ * @module Services/LocationList
+ */
+import { implementService } from '@wix/services-definitions';
+import { SignalsServiceDefinition, } from '@wix/services-definitions/core-services/signals';
+import { LocationType } from '@wix/auto_sdk_bookings_services';
+import { LocationListServiceDefinition, } from './location-list.def.js';
+import { BookingServiceDefinition } from '../booking/booking.js';
+import { queryLocations } from '../../api/query-locations/index.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Synthetic location IDs for non-business locations
+ */
+const SYNTHETIC_CUSTOM_ID = '__synthetic_custom__';
+const SYNTHETIC_CUSTOMER_ID = '__synthetic_customer__';
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Build display locations from raw locations and flags
+ */
+function buildDisplayLocations(locations, hasCustomLocations, hasCustomerLocations) {
+    const displayLocations = [];
+    // 1. Add all BUSINESS locations
+    const businessLocations = locations.filter((loc) => loc.type === LocationType.BUSINESS || loc.type === undefined);
+    for (const loc of businessLocations) {
+        displayLocations.push({
+            location: loc,
+            type: LocationType.BUSINESS,
+            isSynthetic: false,
+            id: loc.business?._id || loc._id || String(displayLocations.length),
+        });
+    }
+    // Check for existing CUSTOM/CUSTOMER in array
+    const customFromArray = locations.find((loc) => loc.type === LocationType.CUSTOM);
+    const customerFromArray = locations.find((loc) => loc.type === LocationType.CUSTOMER);
+    // 2. Add CUSTOM location (from array or synthetic)
+    if (customFromArray) {
+        displayLocations.push({
+            location: customFromArray,
+            type: LocationType.CUSTOM,
+            isSynthetic: false,
+            id: customFromArray.custom?._id || SYNTHETIC_CUSTOM_ID,
+        });
+    }
+    else if (hasCustomLocations) {
+        // Synthetic custom location (only from explicit flag, not array)
+        displayLocations.push({
+            location: null,
+            type: LocationType.CUSTOM,
+            isSynthetic: true,
+            id: SYNTHETIC_CUSTOM_ID,
+        });
+    }
+    // 3. Add CUSTOMER location (always synthetic display, real or flag-based)
+    if (customerFromArray || hasCustomerLocations) {
+        displayLocations.push({
+            location: customerFromArray || null,
+            type: LocationType.CUSTOMER,
+            isSynthetic: !customerFromArray,
+            id: SYNTHETIC_CUSTOMER_ID,
+        });
+    }
+    return displayLocations;
+}
+// ============================================================================
+// Service Implementation
+// ============================================================================
+/**
+ * Implementation of the LocationList service
+ * Manages location state and integrates with BookingService for selection (optional)
+ */
+export const LocationListService = implementService.withConfig()(LocationListServiceDefinition, ({ getService, config }) => {
+    const signalsService = getService(SignalsServiceDefinition);
+    // Try to get BookingService - it's optional (Location can be standalone)
+    let bookingService = null;
+    try {
+        bookingService = getService(BookingServiceDefinition);
+    }
+    catch {
+        // BookingService not available - Location is used standalone
+        bookingService = null;
+    }
+    // Initialize raw locations signal
+    const locationsSignal = signalsService.signal(config.locations || []);
+    // Auto-detect from array
+    const hasCustomInArray = (config.locations || []).some((loc) => loc.type === LocationType.CUSTOM);
+    const hasCustomerInArray = (config.locations || []).some((loc) => loc.type === LocationType.CUSTOMER);
+    // Final flags: explicit config OR auto-detected
+    const hasCustomLocationsSignal = signalsService.computed(() => config.hasCustomLocations ?? hasCustomInArray);
+    const hasCustomerLocationsSignal = signalsService.computed(() => config.hasCustomerLocations ?? hasCustomerInArray);
+    // Display locations - computed from raw + flags
+    const displayLocationsSignal = signalsService.computed(() => buildDisplayLocations(locationsSignal.get(), hasCustomLocationsSignal.get(), hasCustomerLocationsSignal.get()));
+    const isLoadingSignal = signalsService.signal(false);
+    const errorSignal = signalsService.signal(null);
+    // Selected location from BookingService (null if standalone)
+    const selectedLocationSignal = signalsService.computed(() => {
+        if (!bookingService)
+            return null;
+        return bookingService.location.get();
+    });
+    // Actions - integrate with BookingService if available
+    const actions = {
+        select: (displayLocation) => {
+            if (bookingService) {
+                bookingService.actions.setLocation(displayLocation.location);
+            }
+            // If standalone, selection is handled by consumer via asChild
+        },
+    };
+    return {
+        locations: locationsSignal,
+        displayLocations: displayLocationsSignal,
+        hasCustomLocations: hasCustomLocationsSignal,
+        hasCustomerLocations: hasCustomerLocationsSignal,
+        isLoading: isLoadingSignal,
+        error: errorSignal,
+        selectedLocation: selectedLocationSignal,
+        actions,
+    };
+});
+/**
+ * SSR Loader: Fetches locations from API for server-side rendering.
+ *
+ * @param options - Optional configuration
+ * @returns Configuration result for LocationListService with pre-fetched locations
+ *
+ * @example
+ * ```typescript
+ * // Fetch from API
+ * const result = await loadLocationListServiceInitialData();
+ *
+ * if (result.type === 'error') {
+ *   return Astro.redirect('/500');
+ * }
+ *
+ * const locationListConfig = result.config;
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Pass locations directly (e.g., from service.locations)
+ * const result = await loadLocationListServiceInitialData({
+ *   locations: service.locations,
+ *   // hasCustom/hasCustomer will be auto-detected from array
+ * });
+ * ```
+ */
+export async function loadLocationListServiceInitialData(options) {
+    try {
+        // If locations are passed directly, use them (flags auto-detected if not provided)
+        if (options?.locations) {
+            return {
+                type: 'success',
+                config: {
+                    locations: options.locations,
+                    hasCustomLocations: options.hasCustomLocations,
+                    hasCustomerLocations: options.hasCustomerLocations,
+                },
+            };
+        }
+        // Otherwise, fetch from API
+        const result = await queryLocations();
+        return {
+            type: 'success',
+            config: {
+                locations: result.locations,
+                hasCustomLocations: result.hasCustomLocations,
+                hasCustomerLocations: result.hasCustomerLocations,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Failed to load locations';
+        console.error('loadLocationListServiceInitialData error:', error);
+        return { type: 'error', error: message };
+    }
+}
+// ============================================================================
+// Service Binding Helper
+// ============================================================================
+/**
+ * Service binding helper for LocationListService.
+ * Bundles definition, implementation, and config for ServicesManager.
+ *
+ * @param servicesConfigs - Object containing LocationListServiceDefinition config
+ * @returns Tuple of [Definition, Implementation, Config] for addService()
+ *
+ * @example
+ * ```typescript
+ * const servicesManager = createServicesManager(
+ *   createServicesMap()
+ *     .addService(...locationListServiceBinding(configs))
+ * );
+ * ```
+ */
+export const locationListServiceBinding = (servicesConfigs) => {
+    return [
+        LocationListServiceDefinition,
+        LocationListService,
+        servicesConfigs['location-list'],
+    ];
+};
+// ============================================================================
+// Re-exports
+// ============================================================================
+export { LocationListServiceDefinition, LocationType, } from './location-list.def.js';

package/dist/api/index.d.ts

@@ -8,6 +8,7 @@ export { getServiceById, getServiceBySlug, queryServices, type PagingMetadata, t
 export { fetchAvailability } from './fetch-availability/index.js';
 export { createBooking, type CreateBookingOptions, type Booking, type CreateBookingRequest, type CreateBookingResponse, type ParticipantNotification, type ContactDetails, } from './create-booking/index.js';
 export { createCheckout, ChannelType, type CreateCheckoutRequest, type CreateCheckoutResponse, } from './create-checkout/index.js';
+export { queryLocations, type QueryLocationsResult, type LocationData, } from './query-locations/index.js';
 /**
  * PagingMetadata includes:
  * - limit: Number of items per page

package/dist/api/index.js

@@ -8,6 +8,7 @@ export { getServiceById, getServiceBySlug, queryServices, } from './query-servic
 export { fetchAvailability } from './fetch-availability/index.js';
 export { createBooking, } from './create-booking/index.js';
 export { createCheckout, ChannelType, } from './create-checkout/index.js';
+export { queryLocations, } from './query-locations/index.js';
 /**
  * PagingMetadata includes:
  * - limit: Number of items per page

package/dist/api/query-locations/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Query Locations API
+ * Fetches business locations from Wix Bookings Services
+ *
+ * @module API/QueryLocations
+ */
+import type { Service } from '@wix/auto_sdk_bookings_services';
+/**
+ * LocationData type - from Service['locations'][number]
+ */
+export type LocationData = NonNullable<Service['locations']>[number];
+/**
+ * Result from querying locations
+ */
+export interface QueryLocationsResult {
+    /** Business locations array */
+    locations: LocationData[];
+    /** Whether custom locations exist for any service */
+    hasCustomLocations: boolean;
+    /** Whether customer locations (at customer's place) exist for any service */
+    hasCustomerLocations: boolean;
+}
+/**
+ * Query all locations connected to services.
+ * Returns business locations array and existence flags for custom/customer locations.
+ *
+ * @returns Promise resolving to locations and existence flags
+ *
+ * @example
+ * ```ts
+ * const { locations, hasCustomLocations, hasCustomerLocations } = await queryLocations();
+ *
+ * // locations contains all business locations
+ * // hasCustomLocations indicates if any service uses custom locations
+ * // hasCustomerLocations indicates if any service is at customer's place
+ * ```
+ */
+export declare function queryLocations(): Promise<QueryLocationsResult>;

package/dist/api/query-locations/index.js

@@ -0,0 +1,30 @@
+/**
+ * Query Locations API
+ * Fetches business locations from Wix Bookings Services
+ *
+ * @module API/QueryLocations
+ */
+import { queryLocations as queryLocationsApi, } from '@wix/auto_sdk_bookings_services';
+/**
+ * Query all locations connected to services.
+ * Returns business locations array and existence flags for custom/customer locations.
+ *
+ * @returns Promise resolving to locations and existence flags
+ *
+ * @example
+ * ```ts
+ * const { locations, hasCustomLocations, hasCustomerLocations } = await queryLocations();
+ *
+ * // locations contains all business locations
+ * // hasCustomLocations indicates if any service uses custom locations
+ * // hasCustomerLocations indicates if any service is at customer's place
+ * ```
+ */
+export async function queryLocations() {
+    const response = await queryLocationsApi();
+    return {
+        locations: (response.businessLocations?.locations || []),
+        hasCustomLocations: response.customLocations?.exists || false,
+        hasCustomerLocations: response.customerLocations?.exists || false,
+    };
+}

package/dist/react/core/location/Location.d.ts

@@ -2,6 +2,8 @@
  * Core Location Component - Parses service location data
  * Handles business, custom, and customer location types
  * Converts location data to Address component format
+ *
+ * @module Core/Location
  */
 import React from 'react';
 import { LocationType, type Service } from '@wix/auto_sdk_bookings_services';
@@ -10,35 +12,132 @@ import type { AddressData as AddressDataType } from '@wix/headless-components/re
  * Re-export AddressData type from Address component for convenience
  */
 export type AddressData = AddressDataType;
+/**
+ * Service location type - from Service['locations'][number]
+ */
+export type ServiceLocation = NonNullable<Service['locations']>[number];
+/**
+ * Synthetic location - represents a location type without real data
+ * Used for CUSTOMER or CUSTOM locations when no real location data exists
+ */
+export interface SyntheticLocation {
+    /** Location type */
+    locationType: LocationType.CUSTOMER | LocationType.CUSTOM;
+    /** Marker to identify synthetic locations */
+    synthetic: true;
+    /** Optional ID for tracking */
+    id?: string;
+}
+/**
+ * Union type - location prop accepts Service or Synthetic location
+ */
+export type LocationInput = ServiceLocation | SyntheticLocation;
 /**
  * Location render props passed to children
  */
 export interface LocationRenderProps {
+    /** Location type */
     locationType: LocationType;
+    /** Parsed address data compatible with Address.Root, null if not available */
     address: AddressData | null;
+    /** Location name (business.name or custom name) */
+    name: string | undefined;
+    /** Location ID */
+    locationId: string | undefined;
+    /** Whether this is a customer location */
+    isCustomerLocation: boolean;
+    /** Whether this is a custom location */
+    isCustomLocation: boolean;
+    /** Whether this is a synthetic entry (not from array) */
+    isSynthetic: boolean;
+    /** Phone number (only for BUSINESS ServiceLocations) */
+    phone: string | undefined;
+    /** Email address (only for BUSINESS ServiceLocations) */
+    email: string | undefined;
+    /** Raw location object (Service or Synthetic location) */
+    rawLocation: LocationInput | null;
 }
 /**
- * Props for the core Location component
+ * Props for the Core Location Root component
  */
-export interface LocationProps {
-    location: NonNullable<Service['locations']>[number];
+export interface RootProps {
+    /** Raw location data - accepts Service or Synthetic location */
+    location?: LocationInput;
+    /** Children */
+    children: React.ReactNode;
+}
+/**
+ * Props for the Core Location Data component
+ */
+export interface DataProps {
+    /** Children render prop that receives location data */
     children: (props: LocationRenderProps) => React.ReactNode;
 }
 /**
- * Core Location component that parses service location data
- * and provides location type and address data to children
+ * Hook to access location context from CoreLocation.Root
+ * @throws Error if used outside of CoreLocation.Root
+ */
+export declare function useLocationContext(): LocationRenderProps;
+/**
+ * Core Location Root component that provides location context.
+ * Parses location data and makes it available to all child components via context.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CoreLocation.Root location={serviceLocation}>
+ *   <Location.Name />
+ *   <Location.Address />
+ * </CoreLocation.Root>
+ * ```
+ */
+export declare function Root(props: RootProps): React.ReactNode;
+/**
+ * Core Location Data component that exposes location data via render props.
+ * Must be used within a CoreLocation.Root component.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CoreLocation.Root location={serviceLocation}>
+ *   <CoreLocation.Data>
+ *     {({ displayName, address }) => (
+ *       <div>
+ *         <span>{displayName}</span>
+ *         {address && <Address.Formatted address={address} />}
+ *       </div>
+ *     )}
+ *   </CoreLocation.Data>
+ * </CoreLocation.Root>
+ * ```
+ */
+export declare function Data(props: DataProps): React.ReactNode;
+/**
+ * Props for Actions render prop component
+ */
+export interface ActionsProps {
+    children: (actions: {
+        select: () => void;
+        rawLocation: LocationInput | null;
+        selected: boolean;
+    }) => React.ReactNode;
+}
+/**
+ * Core component that provides location selection actions via render props.
+ * Sets the location in BookingService when select is called.
  *
  * @component
  * @example
  * ```tsx
- * <CoreLocation location={serviceLocation}>
- *   {({ locationType, address }) => (
- *     <div>
- *       <span>Type: {locationType}</span>
- *       {address && <Address.Root address={address}><Address.Formatted /></Address.Root>}
- *     </div>
- *   )}
- * </CoreLocation>
+ * <CoreLocation.Root location={serviceLocation}>
+ *   <CoreLocation.Actions>
+ *     {({ select, selected, rawLocation }) => (
+ *       <button onClick={select}>
+ *         {selected ? 'Selected' : 'Select'}
+ *       </button>
+ *     )}
+ *   </CoreLocation.Actions>
+ * </CoreLocation.Root>
  * ```
  */
-export declare function Location(props: LocationProps): React.ReactNode;
+export declare function Actions(props: ActionsProps): React.ReactNode;