@wix/bookings 1.0.1754 → 1.0.1756
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.
- package/_sdk-exports/context-booking-checkout/runtime.d.ts +791 -143
- package/_sdk-exports/context-booking-checkout/runtime.js +3 -2
- package/_sdk-exports/context-categories/runtime.d.ts +164 -2
- package/_sdk-exports/context-categories/runtime.js +2 -1
- package/_sdk-exports/context-locations/runtime.d.ts +186 -2
- package/_sdk-exports/context-locations/runtime.js +2 -1
- package/_sdk-exports/context-service/runtime.d.ts +1540 -144
- package/_sdk-exports/context-service/runtime.js +3 -2
- package/_sdk-exports/context-service-addons/runtime.d.ts +215 -13
- package/_sdk-exports/context-service-addons/runtime.js +2 -1
- package/_sdk-exports/context-services/runtime.d.ts +371 -77
- package/_sdk-exports/context-services/runtime.js +3 -2
- package/_sdk-exports/context-time-slots/runtime.d.ts +854 -72
- package/_sdk-exports/context-time-slots/runtime.js +3 -2
- package/build/cjs/context-booking-checkout.d.ts +791 -143
- package/build/cjs/context-booking-checkout.js +1759 -1640
- package/build/cjs/context-booking-checkout.js.map +1 -1
- package/build/cjs/context-categories.d.ts +164 -2
- package/build/cjs/context-categories.js +116 -114
- package/build/cjs/context-categories.js.map +1 -1
- package/build/cjs/context-locations.d.ts +186 -2
- package/build/cjs/context-locations.js +126 -124
- package/build/cjs/context-locations.js.map +1 -1
- package/build/cjs/context-service-addons.d.ts +215 -13
- package/build/cjs/context-service-addons.js +323 -321
- package/build/cjs/context-service-addons.js.map +1 -1
- package/build/cjs/context-service.d.ts +1540 -144
- package/build/cjs/context-service.js +1622 -1616
- package/build/cjs/context-service.js.map +1 -1
- package/build/cjs/context-services.d.ts +371 -77
- package/build/cjs/context-services.js +460 -458
- package/build/cjs/context-services.js.map +1 -1
- package/build/cjs/context-time-slots.d.ts +854 -72
- package/build/cjs/context-time-slots.js +1033 -1000
- package/build/cjs/context-time-slots.js.map +1 -1
- package/build/es/context-booking-checkout.d.mts +791 -143
- package/build/es/context-booking-checkout.mjs +1778 -1650
- package/build/es/context-booking-checkout.mjs.map +1 -1
- package/build/es/context-categories.d.mts +164 -2
- package/build/es/context-categories.mjs +116 -114
- package/build/es/context-categories.mjs.map +1 -1
- package/build/es/context-locations.d.mts +186 -2
- package/build/es/context-locations.mjs +126 -124
- package/build/es/context-locations.mjs.map +1 -1
- package/build/es/context-service-addons.d.mts +215 -13
- package/build/es/context-service-addons.mjs +323 -321
- package/build/es/context-service-addons.mjs.map +1 -1
- package/build/es/context-service.d.mts +1540 -144
- package/build/es/context-service.mjs +1622 -1616
- package/build/es/context-service.mjs.map +1 -1
- package/build/es/context-services.d.mts +371 -77
- package/build/es/context-services.mjs +460 -458
- package/build/es/context-services.mjs.map +1 -1
- package/build/es/context-time-slots.d.mts +854 -72
- package/build/es/context-time-slots.mjs +1033 -1000
- package/build/es/context-time-slots.mjs.map +1 -1
- package/build/internal/cjs/context-booking-checkout.d.ts +791 -143
- package/build/internal/cjs/context-categories.d.ts +164 -2
- package/build/internal/cjs/context-locations.d.ts +186 -2
- package/build/internal/cjs/context-service-addons.d.ts +215 -13
- package/build/internal/cjs/context-service.d.ts +1540 -144
- package/build/internal/cjs/context-services.d.ts +371 -77
- package/build/internal/cjs/context-time-slots.d.ts +854 -72
- package/build/internal/es/context-booking-checkout.d.mts +791 -143
- package/build/internal/es/context-categories.d.mts +164 -2
- package/build/internal/es/context-locations.d.mts +186 -2
- package/build/internal/es/context-service-addons.d.mts +215 -13
- package/build/internal/es/context-service.d.mts +1540 -144
- package/build/internal/es/context-services.d.mts +371 -77
- package/build/internal/es/context-time-slots.d.mts +854 -72
- package/package.json +5 -5
|
@@ -73,7 +73,7 @@ declare global {
|
|
|
73
73
|
*
|
|
74
74
|
* For multi-service bookings, the top-level time slot acts as a container spanning the entire service sequence (from the start of the first service to the end of the last service). Individual service details are provided in nested time slots.
|
|
75
75
|
*/
|
|
76
|
-
interface TimeSlot
|
|
76
|
+
interface TimeSlot {
|
|
77
77
|
/**
|
|
78
78
|
* [Service ID] (https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/introduction).
|
|
79
79
|
*
|
|
@@ -401,8 +401,7 @@ type Image = {
|
|
|
401
401
|
/**
|
|
402
402
|
* Where a staff member has working hours, derived server-side from their WORKING_HOURS
|
|
403
403
|
* calendar events. Returned only when `STAFF_WORKING_HOURS_LOCATIONS` is requested (see
|
|
404
|
-
* `SERVICE_CONDITIONAL_FIELDS`)
|
|
405
|
-
* it's read through this narrow shape.
|
|
404
|
+
* `SERVICE_CONDITIONAL_FIELDS`).
|
|
406
405
|
*/
|
|
407
406
|
interface StaffLocationCoverage {
|
|
408
407
|
availableAtAllLocations: boolean;
|
|
@@ -420,7 +419,9 @@ interface StaffMemberItem {
|
|
|
420
419
|
//#region src/mappers/date-time.d.ts
|
|
421
420
|
/** Inclusive. */
|
|
422
421
|
interface LocalDateRange {
|
|
422
|
+
/** First date of the range, as a local date in `YYYY-MM-DD` format. The range includes it. */
|
|
423
423
|
readonly startDate: string;
|
|
424
|
+
/** Last date of the range, as a local date in `YYYY-MM-DD` format. The range includes it. */
|
|
424
425
|
readonly endDate: string;
|
|
425
426
|
}
|
|
426
427
|
//#endregion
|
|
@@ -435,38 +436,111 @@ interface DayAvailabilityItem {
|
|
|
435
436
|
//#region src/extensions/contexts/time-slots-context/time-slots-context.types.d.ts
|
|
436
437
|
/** A local date in `YYYY-MM-DD` format. */
|
|
437
438
|
type LocalDate = string;
|
|
439
|
+
/** How a `goToNextAvailableDate()` search ended. */
|
|
440
|
+
type NextAvailableDateOutcome =
|
|
438
441
|
/**
|
|
439
|
-
*
|
|
440
|
-
*
|
|
441
|
-
* superseded by a newer slot action or input change.
|
|
442
|
+
* The search found and selected a date with a bookable time slot. It can be the date that
|
|
443
|
+
* was already selected.
|
|
442
444
|
*/
|
|
443
|
-
|
|
444
|
-
/**
|
|
445
|
-
|
|
446
|
-
|
|
445
|
+
'found'
|
|
446
|
+
/**
|
|
447
|
+
* The search selected no date: there's no bookable time slot on or after the start date, or
|
|
448
|
+
* nothing to search, such as no service or a course. While rescheduling a booking paid with a
|
|
449
|
+
* pricing plan, it's also the outcome when the first bookable date is after the plan's last
|
|
450
|
+
* date.
|
|
451
|
+
*/
|
|
452
|
+
| 'none' /** The search failed. `timeSlotsErrorCode` is `'timeSlotsLoadFailed'`. */ | 'error'
|
|
453
|
+
/**
|
|
454
|
+
* The search stopped before it ended, because a component called `selectDate()`, or because
|
|
455
|
+
* the context was still loading its settings or failed to load.
|
|
456
|
+
*/
|
|
457
|
+
| 'cancelled';
|
|
458
|
+
/** Time slot that a component can show and select. */
|
|
447
459
|
interface TimeSlotItem {
|
|
460
|
+
/**
|
|
461
|
+
* ID of the time slot. Specify it when you call `selectTimeSlot()`.
|
|
462
|
+
*
|
|
463
|
+
* It identifies the time slot only in the context, so other APIs don't accept it.
|
|
464
|
+
*/
|
|
448
465
|
readonly slotId: string;
|
|
449
|
-
/**
|
|
466
|
+
/**
|
|
467
|
+
* Start of the time slot, as a local date-time in [ISO
|
|
468
|
+
* 8601](https://en.wikipedia.org/wiki/ISO_8601) format with no offset, such as
|
|
469
|
+
* `2026-11-03T10:00:00`.
|
|
470
|
+
*
|
|
471
|
+
* `null` when it's unknown.
|
|
472
|
+
*/
|
|
450
473
|
readonly slotStartTime: string | null;
|
|
451
|
-
/**
|
|
474
|
+
/**
|
|
475
|
+
* End of the time slot, as a local date-time in [ISO
|
|
476
|
+
* 8601](https://en.wikipedia.org/wiki/ISO_8601) format with no offset, such as
|
|
477
|
+
* `2026-11-03T11:00:00`.
|
|
478
|
+
*
|
|
479
|
+
* `null` when it's unknown.
|
|
480
|
+
*/
|
|
452
481
|
readonly slotEndTime: string | null;
|
|
482
|
+
/** Whether the visitor can book the time slot. */
|
|
453
483
|
readonly bookable: boolean;
|
|
484
|
+
/** Total number of spots in the time slot. `null` when it's unknown. */
|
|
454
485
|
readonly totalCapacity: number | null;
|
|
486
|
+
/** Number of spots left in the time slot. `null` when it's unknown. */
|
|
455
487
|
readonly remainingCapacity: number | null;
|
|
456
|
-
/**
|
|
488
|
+
/**
|
|
489
|
+
* Number of spots that the visitor can book in the time slot, under the business's booking
|
|
490
|
+
* policy.
|
|
491
|
+
*
|
|
492
|
+
* `null` when it's unknown.
|
|
493
|
+
*/
|
|
457
494
|
readonly bookableCapacity: number | null;
|
|
458
|
-
/**
|
|
495
|
+
/**
|
|
496
|
+
* ID of the class session's calendar event.
|
|
497
|
+
*
|
|
498
|
+
* `null` for an appointment.
|
|
499
|
+
*/
|
|
459
500
|
readonly eventId: string | null;
|
|
460
|
-
/**
|
|
501
|
+
/**
|
|
502
|
+
* Title of the class session's calendar event.
|
|
503
|
+
*
|
|
504
|
+
* `null` for an appointment.
|
|
505
|
+
*/
|
|
461
506
|
readonly eventTitle: string | null;
|
|
462
|
-
/**
|
|
507
|
+
/**
|
|
508
|
+
* Number of spots left on the class session's waitlist.
|
|
509
|
+
*
|
|
510
|
+
* `null` for an appointment, and for a session with no waitlist.
|
|
511
|
+
*/
|
|
463
512
|
readonly waitlistCapacity: number | null;
|
|
513
|
+
/**
|
|
514
|
+
* ID of the business location where the time slot takes place. To get the location's details,
|
|
515
|
+
* use the [Locations
|
|
516
|
+
* API](https://dev.wix.com/docs/api-reference/business-management/locations/introduction).
|
|
517
|
+
*
|
|
518
|
+
* `null` when the time slot has no location, or takes place at a location with no ID, such as
|
|
519
|
+
* a custom address.
|
|
520
|
+
*/
|
|
464
521
|
readonly locationId: string | null;
|
|
522
|
+
/**
|
|
523
|
+
* Name of the time slot's location, or its address when the location has no name, such as a
|
|
524
|
+
* custom address. `null` when the time slot has no location.
|
|
525
|
+
*/
|
|
465
526
|
readonly locationName: string | null;
|
|
466
|
-
/**
|
|
527
|
+
/**
|
|
528
|
+
* Length of the time slot, in minutes.
|
|
529
|
+
*
|
|
530
|
+
* `null` when it's unknown.
|
|
531
|
+
*/
|
|
467
532
|
readonly durationMinutes: number | null;
|
|
533
|
+
/** Whether the time slot lasts all day. */
|
|
468
534
|
readonly isAllDay: boolean;
|
|
469
|
-
/**
|
|
535
|
+
/**
|
|
536
|
+
* Staff members available for the time slot, each with its `staffMemberId` and `name`. To get
|
|
537
|
+
* a staff member's details, use the
|
|
538
|
+
* [Staff Members
|
|
539
|
+
* API](https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-members/introduction).
|
|
540
|
+
*
|
|
541
|
+
* Empty when the business assigns the staff member for an appointment itself, and for a
|
|
542
|
+
* multi-service appointment.
|
|
543
|
+
*/
|
|
470
544
|
readonly staff: ReadonlyArray<TimeSlotStaffMember>;
|
|
471
545
|
}
|
|
472
546
|
interface TimeSlotStaffMember {
|
|
@@ -491,69 +565,410 @@ interface StaffGenderFilterOption {
|
|
|
491
565
|
/** A staff member, or "any female/male staff member" (`gender` set). */
|
|
492
566
|
type StaffFilterOption = StaffMemberFilterOption | StaffGenderFilterOption;
|
|
493
567
|
/**
|
|
494
|
-
*
|
|
495
|
-
*
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
*
|
|
500
|
-
*
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
568
|
+
* Reason the time slots can't be shown. The codes aren't text to display. Show your own message
|
|
569
|
+
* for each.
|
|
570
|
+
*/
|
|
571
|
+
type TimeSlotsErrorCode = /** The service, or a service in the multi-service appointment, can't be booked online. */'onlineBookingOff' /** The visitor must log in to reschedule the booking. */ | 'rescheduleLoginRequired'
|
|
572
|
+
/**
|
|
573
|
+
* The booking to reschedule wasn't found or failed to load, or it isn't a booking of this
|
|
574
|
+
* service.
|
|
575
|
+
*/
|
|
576
|
+
| 'rescheduleNotFound' /** The visitor isn't allowed to view the booking to reschedule. */ | 'rescheduleAccessDenied' /** The booking can't be rescheduled online. */ | 'rescheduleNotReschedulable' /** The upcoming time slots can't be shown, because the time zone is unknown. */ | 'timeZoneMissing'
|
|
577
|
+
/**
|
|
578
|
+
* The upcoming time slots failed to load: their first page, a later page, or a day's full list
|
|
579
|
+
* from `loadAllTimeSlotsForDay()`.
|
|
504
580
|
*/
|
|
505
|
-
|
|
581
|
+
| 'upcomingSlotsLoadFailed'
|
|
582
|
+
/**
|
|
583
|
+
* The selected date's time slots failed to load, or the `goToNextAvailableDate()` search
|
|
584
|
+
* failed.
|
|
585
|
+
*/
|
|
586
|
+
| 'timeSlotsLoadFailed' /** The context failed to load. */ | 'loadFailed';
|
|
506
587
|
interface NextAvailability {
|
|
507
588
|
readonly timeSlots: ReadonlyArray<TimeSlot>;
|
|
508
589
|
readonly timeZone: string | null;
|
|
509
590
|
readonly hasError: boolean;
|
|
510
591
|
}
|
|
511
|
-
/**
|
|
592
|
+
/**
|
|
593
|
+
* The availability of the current service or multi-service appointment: its time slots, day
|
|
594
|
+
* availability, upcoming slots, filters, and the actions to browse and pick them.
|
|
595
|
+
*
|
|
596
|
+
* @beta
|
|
597
|
+
*/
|
|
512
598
|
interface TimeSlotsContextValue extends TimeSlotsContextFields {
|
|
599
|
+
/**
|
|
600
|
+
* Time slots to show.
|
|
601
|
+
*
|
|
602
|
+
* While a date is selected, they're the selected date's time slots, and an appointment's time
|
|
603
|
+
* slot shows once, with all its staff members. Otherwise, they're the current page of upcoming
|
|
604
|
+
* time slots, after a call to `loadUpcomingTimeSlots()`. In that list, a time slot with
|
|
605
|
+
* several staff members shows once for each, and each day shows up to `timeSlotLimitPerDay`
|
|
606
|
+
* time slots. Empty before either.
|
|
607
|
+
*
|
|
608
|
+
* Each item has the same fields as `selectedTimeSlot`.
|
|
609
|
+
*/
|
|
513
610
|
readonly timeSlots: ReadonlyArray<TimeSlotItem>;
|
|
611
|
+
/**
|
|
612
|
+
* Whether `timeSlots` is loading, or waiting to load. The same as `timeSlotsLoading`.
|
|
613
|
+
*
|
|
614
|
+
* It's `true`:
|
|
615
|
+
* - Before the context loads in the visitor's browser.
|
|
616
|
+
* - While a selected date's time slots, or a page of upcoming time slots, load.
|
|
617
|
+
* - While `goToNextAvailableDate()` searches.
|
|
618
|
+
*/
|
|
514
619
|
readonly isLoading: boolean;
|
|
620
|
+
/**
|
|
621
|
+
* Whether the context has an availability error. `errorCode` holds the reason.
|
|
622
|
+
*
|
|
623
|
+
* When a later page or a full day of upcoming time slots fails to load, `timeSlots` keeps what
|
|
624
|
+
* it shows.
|
|
625
|
+
*/
|
|
515
626
|
readonly hasError: boolean;
|
|
516
627
|
/** The most relevant availability error; null without one. */
|
|
517
628
|
readonly errorCode: TimeSlotsErrorCode | null;
|
|
518
|
-
/**
|
|
629
|
+
/**
|
|
630
|
+
* Business's time zone, as an [IANA time
|
|
631
|
+
* zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
|
|
632
|
+
*
|
|
633
|
+
* Times show in it unless the business shows times in the visitor's time zone. When
|
|
634
|
+
* `canChangeTimeZone` is `true`, it's 1 of the 2 time zones the visitor can switch between.
|
|
635
|
+
*
|
|
636
|
+
* `null` when it's unknown.
|
|
637
|
+
*/
|
|
519
638
|
readonly businessTimeZone: string | null;
|
|
520
|
-
/**
|
|
639
|
+
/**
|
|
640
|
+
* Changes the time zone that the time slots and dates show in.
|
|
641
|
+
*
|
|
642
|
+
* Ignored when `canChangeTimeZone` is `false`, and for a time zone that isn't
|
|
643
|
+
* `businessTimeZone` or the visitor's own time zone.
|
|
644
|
+
*
|
|
645
|
+
* Changing the time zone reloads the time slots and the day availability, and clears
|
|
646
|
+
* the selected time slot.
|
|
647
|
+
*
|
|
648
|
+
* @param timeZone - Time zone to show times in, as an
|
|
649
|
+
* [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Must be
|
|
650
|
+
* `businessTimeZone` or the visitor's own time zone.
|
|
651
|
+
* @example Switch between the business's and the visitor's time zone
|
|
652
|
+
* ```tsx
|
|
653
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
654
|
+
*
|
|
655
|
+
* function TimeZoneSwitch() {
|
|
656
|
+
* const { canChangeTimeZone, businessTimeZone, timeZone, setTimeZone } = useTimeSlotsContext();
|
|
657
|
+
* const visitorTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
|
|
658
|
+
*
|
|
659
|
+
* if (!canChangeTimeZone || !businessTimeZone) {
|
|
660
|
+
* return null;
|
|
661
|
+
* }
|
|
662
|
+
*
|
|
663
|
+
* return (
|
|
664
|
+
* <select value={timeZone ?? ''} onChange={(event) => setTimeZone(event.target.value)}>
|
|
665
|
+
* <option value={businessTimeZone}>Business time ({businessTimeZone})</option>
|
|
666
|
+
* <option value={visitorTimeZone}>Your time ({visitorTimeZone})</option>
|
|
667
|
+
* </select>
|
|
668
|
+
* );
|
|
669
|
+
* }
|
|
670
|
+
* ```
|
|
671
|
+
*/
|
|
521
672
|
readonly setTimeZone: (timeZone: string) => void;
|
|
522
673
|
/** One-based. */
|
|
523
674
|
readonly currentTimeSlotsPage: number;
|
|
675
|
+
/**
|
|
676
|
+
* Whether the upcoming time slots have a page after the current one. `false` while a date is
|
|
677
|
+
* selected.
|
|
678
|
+
*/
|
|
524
679
|
readonly hasNextTimeSlotsPage: boolean;
|
|
680
|
+
/**
|
|
681
|
+
* Whether the upcoming time slots have a page before the current one. `false` while a date is
|
|
682
|
+
* selected.
|
|
683
|
+
*/
|
|
525
684
|
readonly hasPreviousTimeSlotsPage: boolean;
|
|
685
|
+
/**
|
|
686
|
+
* Shows the next page of upcoming time slots in `timeSlots`.
|
|
687
|
+
*
|
|
688
|
+
* Shows a page that already loaded at once, and loads any other page first.
|
|
689
|
+
*
|
|
690
|
+
* Ignored when `hasNextTimeSlotsPage` is `false`, while a page is loading, and while a date is
|
|
691
|
+
* selected.
|
|
692
|
+
*
|
|
693
|
+
* When the page fails to load, `timeSlots` keeps the current page, and `errorCode` is
|
|
694
|
+
* `'upcomingSlotsLoadFailed'`. When the next page is empty, the current page stays, and
|
|
695
|
+
* `hasNextTimeSlotsPage` changes to `false`.
|
|
696
|
+
*
|
|
697
|
+
* @returns Promise that resolves when the page shows, or fails to load.
|
|
698
|
+
* @example Page through the upcoming time slots
|
|
699
|
+
* ```tsx
|
|
700
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
701
|
+
*
|
|
702
|
+
* function UpcomingSlotsPager() {
|
|
703
|
+
* const {
|
|
704
|
+
* currentTimeSlotsPage,
|
|
705
|
+
* hasNextTimeSlotsPage,
|
|
706
|
+
* hasPreviousTimeSlotsPage,
|
|
707
|
+
* isLoading,
|
|
708
|
+
* nextTimeSlotsPage,
|
|
709
|
+
* previousTimeSlotsPage,
|
|
710
|
+
* } = useTimeSlotsContext();
|
|
711
|
+
*
|
|
712
|
+
* return (
|
|
713
|
+
* <nav>
|
|
714
|
+
* <button disabled={!hasPreviousTimeSlotsPage || isLoading} onClick={() => previousTimeSlotsPage()}>
|
|
715
|
+
* Earlier times
|
|
716
|
+
* </button>
|
|
717
|
+
* <span>Page {currentTimeSlotsPage}</span>
|
|
718
|
+
* <button disabled={!hasNextTimeSlotsPage || isLoading} onClick={() => nextTimeSlotsPage()}>
|
|
719
|
+
* Later times
|
|
720
|
+
* </button>
|
|
721
|
+
* </nav>
|
|
722
|
+
* );
|
|
723
|
+
* }
|
|
724
|
+
* ```
|
|
725
|
+
*/
|
|
526
726
|
readonly nextTimeSlotsPage: () => Promise<void>;
|
|
527
727
|
/**
|
|
528
|
-
*
|
|
529
|
-
*
|
|
728
|
+
* Starts loading the upcoming time slots, which are the service's time slots from the current
|
|
729
|
+
* time on, a page at a time. `timeSlots` holds them while no date is selected.
|
|
730
|
+
*
|
|
731
|
+
* Until it's called, `timeSlots` is empty while no date is selected. Calling it again has no
|
|
732
|
+
* effect, so every component that shows the upcoming time slots can call it. After the first
|
|
733
|
+
* call, the list reloads when the time zone or a filter changes. When the service changes, the
|
|
734
|
+
* context starts over and the components inside it mount again, so they call it again.
|
|
735
|
+
*
|
|
736
|
+
* A multi-service appointment, and a course whose last session has ended, have no upcoming
|
|
737
|
+
* time slots. When the first page fails to load, `errorCode` is `'upcomingSlotsLoadFailed'`.
|
|
738
|
+
*
|
|
739
|
+
* @returns Promise that resolves when the first page loads or fails to load, or, when there's
|
|
740
|
+
* nothing to list, as soon as the context loads.
|
|
741
|
+
* @example List the upcoming time slots
|
|
742
|
+
* ```tsx
|
|
743
|
+
* import { useEffect } from 'react';
|
|
744
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
745
|
+
*
|
|
746
|
+
* function UpcomingSlots() {
|
|
747
|
+
* const { timeSlots, isLoading, hasError, loadUpcomingTimeSlots } = useTimeSlotsContext();
|
|
748
|
+
*
|
|
749
|
+
* useEffect(() => {
|
|
750
|
+
* void loadUpcomingTimeSlots();
|
|
751
|
+
* }, [loadUpcomingTimeSlots]);
|
|
752
|
+
*
|
|
753
|
+
* if (isLoading) return <p>Loading times...</p>;
|
|
754
|
+
* if (hasError && !timeSlots.length) return <p>We couldn't load the times. Try again later.</p>;
|
|
755
|
+
* if (!timeSlots.length) return <p>No upcoming times.</p>;
|
|
756
|
+
*
|
|
757
|
+
* return (
|
|
758
|
+
* <ul>
|
|
759
|
+
* {timeSlots.map((slot) => (
|
|
760
|
+
* <li key={slot.slotId}>{slot.slotStartTime?.replace('T', ' ').slice(0, 16)}</li>
|
|
761
|
+
* ))}
|
|
762
|
+
* </ul>
|
|
763
|
+
* );
|
|
764
|
+
* }
|
|
765
|
+
* ```
|
|
530
766
|
*/
|
|
531
767
|
readonly loadUpcomingTimeSlots: () => Promise<void>;
|
|
768
|
+
/** Whether a component called `loadUpcomingTimeSlots()`. */
|
|
532
769
|
readonly upcomingTimeSlotsRequested: boolean;
|
|
533
|
-
/**
|
|
770
|
+
/**
|
|
771
|
+
* Shows the previous page of upcoming time slots in `timeSlots`, from the pages that already
|
|
772
|
+
* loaded.
|
|
773
|
+
*
|
|
774
|
+
* Ignored on the first page, while a page is loading, and while a date is selected.
|
|
775
|
+
*
|
|
776
|
+
* @example Go back to earlier upcoming time slots
|
|
777
|
+
* ```tsx
|
|
778
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
779
|
+
*
|
|
780
|
+
* function EarlierTimesButton() {
|
|
781
|
+
* const { hasPreviousTimeSlotsPage, isLoading, previousTimeSlotsPage } = useTimeSlotsContext();
|
|
782
|
+
*
|
|
783
|
+
* if (!hasPreviousTimeSlotsPage) return null;
|
|
784
|
+
*
|
|
785
|
+
* return (
|
|
786
|
+
* <button disabled={isLoading} onClick={() => previousTimeSlotsPage()}>
|
|
787
|
+
* Earlier times
|
|
788
|
+
* </button>
|
|
789
|
+
* );
|
|
790
|
+
* }
|
|
791
|
+
* ```
|
|
792
|
+
*/
|
|
534
793
|
readonly previousTimeSlotsPage: () => void;
|
|
794
|
+
/**
|
|
795
|
+
* Number of time slots requested for each page of upcoming time slots, from 1 to 1000. A Wix
|
|
796
|
+
* user sets it in the context's settings.
|
|
797
|
+
*
|
|
798
|
+
* A page can show more rows, because a time slot with several staff members shows once for
|
|
799
|
+
* each.
|
|
800
|
+
*/
|
|
535
801
|
readonly nextAvailableSlotsCount: number;
|
|
802
|
+
/**
|
|
803
|
+
* Time zone that the time slots and dates show in, as an
|
|
804
|
+
* [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Each local
|
|
805
|
+
* date and date-time in the context is in this time zone.
|
|
806
|
+
*
|
|
807
|
+
* It's the visitor's own time zone when the business shows times in the visitor's time zone,
|
|
808
|
+
* and `businessTimeZone` otherwise. When `canChangeTimeZone` is `true`, the visitor can switch
|
|
809
|
+
* it with `setTimeZone()`, and a time zone they selected on an earlier page applies when it's
|
|
810
|
+
* `businessTimeZone` or the visitor's own time zone.
|
|
811
|
+
*
|
|
812
|
+
* `null` until the context loads in the visitor's browser.
|
|
813
|
+
*/
|
|
536
814
|
readonly timeZone: string | null;
|
|
537
|
-
/**
|
|
815
|
+
/**
|
|
816
|
+
* Staff members the visitor can select from to book the selected time slot. Each has its
|
|
817
|
+
* `staffMemberId`, its `name`, and `isSelected`, which is `true` for `selectedResourceId`.
|
|
818
|
+
* `image` is always `null`.
|
|
819
|
+
*
|
|
820
|
+
* Empty when no time slot is selected, when the business assigns the staff member itself, when
|
|
821
|
+
* the visitor selected a staff member before reaching the page, and for a multi-service
|
|
822
|
+
* appointment. For a class or course, it lists the time slot's staff members, and selecting
|
|
823
|
+
* one doesn't apply to the booking.
|
|
824
|
+
*/
|
|
538
825
|
readonly staffFromSlots: ReadonlyArray<StaffMemberItem>;
|
|
539
826
|
/**
|
|
540
|
-
*
|
|
541
|
-
*
|
|
827
|
+
* ID of the staff member the visitor selected to book the selected time slot with.
|
|
828
|
+
*
|
|
829
|
+
* `null` when the visitor selected "Any available", or hasn't selected a staff member. It
|
|
830
|
+
* starts from a staff member the visitor selected before reaching the page.
|
|
542
831
|
*/
|
|
543
832
|
readonly selectedResourceId: string | null;
|
|
544
|
-
/**
|
|
833
|
+
/**
|
|
834
|
+
* Sets the staff member the visitor books the selected time slot with.
|
|
835
|
+
*
|
|
836
|
+
* Use it with `staffFromSlots`, the staff members available for the selected time slot. Specify
|
|
837
|
+
* `null` for "Any available", which leaves the choice of staff member to the business. Offer
|
|
838
|
+
* "Any available" only when `canAutoAssignStaff` is `true`.
|
|
839
|
+
*
|
|
840
|
+
* The choice applies to the booking and doesn't filter the time slots. To filter them, call
|
|
841
|
+
* `setStaffFilter()`. Selecting another time slot starts the staff choice over.
|
|
842
|
+
*
|
|
843
|
+
* @param id - ID of the staff member, from `staffFromSlots`. `null` for "Any available".
|
|
844
|
+
* @example Let the visitor select a staff member
|
|
845
|
+
* ```tsx
|
|
846
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
847
|
+
*
|
|
848
|
+
* function StaffChoice() {
|
|
849
|
+
* const { staffFromSlots, selectedResourceId, canAutoAssignStaff, setSelectedResource } =
|
|
850
|
+
* useTimeSlotsContext();
|
|
851
|
+
*
|
|
852
|
+
* if (!staffFromSlots.length) return null;
|
|
853
|
+
*
|
|
854
|
+
* return (
|
|
855
|
+
* <select
|
|
856
|
+
* value={selectedResourceId ?? ''}
|
|
857
|
+
* onChange={(event) => setSelectedResource(event.target.value || null)}
|
|
858
|
+
* >
|
|
859
|
+
* {canAutoAssignStaff ? <option value="">Any available</option> : <option value="" disabled>Choose</option>}
|
|
860
|
+
* {staffFromSlots.map((member) => (
|
|
861
|
+
* <option key={member.staffMemberId} value={member.staffMemberId}>
|
|
862
|
+
* {member.name}
|
|
863
|
+
* </option>
|
|
864
|
+
* ))}
|
|
865
|
+
* </select>
|
|
866
|
+
* );
|
|
867
|
+
* }
|
|
868
|
+
* ```
|
|
869
|
+
*/
|
|
545
870
|
readonly setSelectedResource: (id: string | null) => void;
|
|
546
|
-
/**
|
|
871
|
+
/**
|
|
872
|
+
* Whether the visitor can book the selected time slot with "Any available", which leaves the
|
|
873
|
+
* choice of staff member to the business.
|
|
874
|
+
*
|
|
875
|
+
* `true` for an appointment's time slot with more than 1 staff member, when all of these apply:
|
|
876
|
+
* - The time slots aren't filtered to 1 staff member.
|
|
877
|
+
* - The service isn't priced per staff member.
|
|
878
|
+
* - The business doesn't require the visitor to select a staff member, or the staff filter is
|
|
879
|
+
* set to a gender.
|
|
880
|
+
*
|
|
881
|
+
* Also `true` when the visitor selected "Any available" before reaching the page. `false` when
|
|
882
|
+
* no time slot is selected.
|
|
883
|
+
*/
|
|
547
884
|
readonly canAutoAssignStaff: boolean;
|
|
885
|
+
/**
|
|
886
|
+
* Time slot the visitor selected with `selectTimeSlot()`. `null` when none is selected.
|
|
887
|
+
*
|
|
888
|
+
* The selection clears when a date is selected, and when the time zone, the staff filter, or
|
|
889
|
+
* the location filter changes. Moving between pages of upcoming time slots keeps it.
|
|
890
|
+
*/
|
|
548
891
|
readonly selectedTimeSlot: TimeSlotItem | null;
|
|
892
|
+
/**
|
|
893
|
+
* Sends the visitor to the booking form to book the selected time slot.
|
|
894
|
+
*
|
|
895
|
+
* Ignored when no time slot is selected, and while rescheduling a booking.
|
|
896
|
+
*
|
|
897
|
+
* For an appointment whose staff choice is still open, the visitor books the time slot's first
|
|
898
|
+
* staff member. If your component lets the visitor select a staff member, check `isComplete`
|
|
899
|
+
* first. For a multi-service appointment, it sends the visitor to the booking form for the
|
|
900
|
+
* whole appointment.
|
|
901
|
+
*
|
|
902
|
+
* @example Add a book button
|
|
903
|
+
* ```tsx
|
|
904
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
905
|
+
*
|
|
906
|
+
* function BookButton() {
|
|
907
|
+
* const { isComplete, isRescheduling, navigateToBookingForm } = useTimeSlotsContext();
|
|
908
|
+
*
|
|
909
|
+
* if (isRescheduling) return null;
|
|
910
|
+
*
|
|
911
|
+
* return (
|
|
912
|
+
* <button disabled={!isComplete} onClick={() => navigateToBookingForm()}>
|
|
913
|
+
* Book now
|
|
914
|
+
* </button>
|
|
915
|
+
* );
|
|
916
|
+
* }
|
|
917
|
+
* ```
|
|
918
|
+
*/
|
|
549
919
|
readonly navigateToBookingForm: () => void;
|
|
550
|
-
/**
|
|
920
|
+
/**
|
|
921
|
+
* Maximum number of time slots each day shows in the upcoming time slots, until
|
|
922
|
+
* `loadAllTimeSlotsForDay()` shows the rest. A Wix user sets it in the context's settings.
|
|
923
|
+
*
|
|
924
|
+
* `null` while the context's settings load, and when the context fails to load.
|
|
925
|
+
*/
|
|
551
926
|
readonly timeSlotLimitPerDay: number | null;
|
|
927
|
+
/**
|
|
928
|
+
* Dates in the upcoming time slots that show all their time slots, after
|
|
929
|
+
* `loadAllTimeSlotsForDay()`. Each is a local date in `YYYY-MM-DD` format.
|
|
930
|
+
*
|
|
931
|
+
* Empty again when the upcoming time slots reload.
|
|
932
|
+
*/
|
|
552
933
|
readonly expandedDates: ReadonlySet<LocalDate>;
|
|
553
|
-
/**
|
|
934
|
+
/**
|
|
935
|
+
* Dates in the upcoming time slots that have more time slots than `timeSlotLimitPerDay` shows.
|
|
936
|
+
* To show all of a date's time slots, call `loadAllTimeSlotsForDay()`.
|
|
937
|
+
*/
|
|
554
938
|
readonly daysWithMore: ReadonlySet<LocalDate>;
|
|
555
939
|
/** The date whose full schedule is loading. */
|
|
556
940
|
readonly loadingDate: LocalDate | null;
|
|
941
|
+
/**
|
|
942
|
+
* Shows all of a day's time slots in the upcoming time slots, past the `timeSlotLimitPerDay`
|
|
943
|
+
* limit.
|
|
944
|
+
*
|
|
945
|
+
* Call it for a date in `daysWithMore`. While the day loads, `loadingDate` is that date. Then
|
|
946
|
+
* the date is in `expandedDates`, and `timeSlots` shows the day without the limit.
|
|
947
|
+
*
|
|
948
|
+
* Ignored while a page or another day is loading, and for a date in `expandedDates`.
|
|
949
|
+
*
|
|
950
|
+
* When the day fails to load, `errorCode` is `'upcomingSlotsLoadFailed'`.
|
|
951
|
+
*
|
|
952
|
+
* @param date - Date to show in full, as a local date in `YYYY-MM-DD` format.
|
|
953
|
+
* @returns Promise that resolves when the day's time slots show, or fail to load.
|
|
954
|
+
* @example Show all of a day's times
|
|
955
|
+
* ```tsx
|
|
956
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
957
|
+
*
|
|
958
|
+
* // date is a day in your list of upcoming times, such as '2026-11-03'.
|
|
959
|
+
* function ShowAllTimesButton({ date }: { date: string }) {
|
|
960
|
+
* const { daysWithMore, loadingDate, loadAllTimeSlotsForDay } = useTimeSlotsContext();
|
|
961
|
+
*
|
|
962
|
+
* if (!daysWithMore.has(date)) return null;
|
|
963
|
+
*
|
|
964
|
+
* return (
|
|
965
|
+
* <button disabled={loadingDate !== null} onClick={() => loadAllTimeSlotsForDay(date)}>
|
|
966
|
+
* {loadingDate === date ? 'Loading...' : 'Show all times'}
|
|
967
|
+
* </button>
|
|
968
|
+
* );
|
|
969
|
+
* }
|
|
970
|
+
* ```
|
|
971
|
+
*/
|
|
557
972
|
readonly loadAllTimeSlotsForDay: (date: LocalDate) => Promise<void>;
|
|
558
973
|
}
|
|
559
974
|
interface TimeSlotsContextFields {
|
|
@@ -561,81 +976,441 @@ interface TimeSlotsContextFields {
|
|
|
561
976
|
readonly selectedDate: LocalDate | null;
|
|
562
977
|
/** Inclusive; null until today is known. */
|
|
563
978
|
readonly daysAvailabilityRange: LocalDateRange | null;
|
|
564
|
-
/**
|
|
979
|
+
/**
|
|
980
|
+
* Availability of each date in `daysAvailabilityRange`, such as for a date picker. Each item
|
|
981
|
+
* has its `date`, as a local date in `YYYY-MM-DD` format, and its `availability`:
|
|
982
|
+
* - `'available'`: The date has a bookable time slot.
|
|
983
|
+
* - `'unavailable'`: The date has time slots, and none is bookable.
|
|
984
|
+
* - `'none'`: The date has no time slots to show.
|
|
985
|
+
*
|
|
986
|
+
* Empty until it first loads. To load it, call `setDaysAvailabilityRange()`,
|
|
987
|
+
* `nextDaysAvailabilityRange()`, or `previousDaysAvailabilityRange()`.
|
|
988
|
+
*
|
|
989
|
+
* Dates before today are `'none'`. When the context's settings show only available time slots,
|
|
990
|
+
* which they do by default, a date with only full time slots is `'none'`. While rescheduling a
|
|
991
|
+
* booking paid with a pricing plan, dates after the plan's last date are `'none'`.
|
|
992
|
+
*/
|
|
565
993
|
readonly daysAvailability: ReadonlyArray<DayAvailabilityItem>;
|
|
994
|
+
/** Whether `daysAvailability` is loading. */
|
|
566
995
|
readonly daysAvailabilityLoading: boolean;
|
|
567
996
|
/** The day availability failed to load. */
|
|
568
997
|
readonly daysAvailabilityHasError: boolean;
|
|
998
|
+
/** Whether `timeSlots` is loading. The same as `isLoading`. */
|
|
569
999
|
readonly timeSlotsLoading: boolean;
|
|
570
1000
|
/** The same as `errorCode`. */
|
|
571
1001
|
readonly timeSlotsErrorCode: TimeSlotsErrorCode | null;
|
|
572
1002
|
/**
|
|
573
|
-
*
|
|
574
|
-
*
|
|
575
|
-
*
|
|
1003
|
+
* Selects a date and replaces `timeSlots` with that date's time slots.
|
|
1004
|
+
*
|
|
1005
|
+
* While they load, `timeSlotsLoading` is `true`. When they fail to load, `timeSlotsErrorCode`
|
|
1006
|
+
* is `'timeSlotsLoadFailed'`. Today's time slots start from the current time. Selecting the
|
|
1007
|
+
* selected date again reloads its time slots.
|
|
1008
|
+
*
|
|
1009
|
+
* Ignored for a malformed date, a date before today, and a course, which has no time slots per
|
|
1010
|
+
* day. When it's called before the service is known, the date waits for it, and is dropped
|
|
1011
|
+
* when there's no service or the service is a course.
|
|
1012
|
+
*
|
|
1013
|
+
* Selecting a date clears the selected time slot, and stops a `goToNextAvailableDate()`
|
|
1014
|
+
* search, which resolves with `'cancelled'`.
|
|
1015
|
+
*
|
|
1016
|
+
* @param date - Date to select, as a local date in `YYYY-MM-DD` format.
|
|
1017
|
+
* @returns Promise that resolves once the date is selected, before its time slots load. To
|
|
1018
|
+
* know when they load, use `timeSlotsLoading`.
|
|
1019
|
+
* @example Select a date with a date input
|
|
1020
|
+
* ```tsx
|
|
1021
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
1022
|
+
*
|
|
1023
|
+
* function DateInput() {
|
|
1024
|
+
* const { selectedDate, timeSlots, timeSlotsLoading, selectDate } = useTimeSlotsContext();
|
|
1025
|
+
*
|
|
1026
|
+
* return (
|
|
1027
|
+
* <div>
|
|
1028
|
+
* <input type="date" value={selectedDate ?? ''} onChange={(event) => selectDate(event.target.value)} />
|
|
1029
|
+
* {selectedDate && <p>{timeSlotsLoading ? 'Loading times...' : `${timeSlots.length} times`}</p>}
|
|
1030
|
+
* </div>
|
|
1031
|
+
* );
|
|
1032
|
+
* }
|
|
1033
|
+
* ```
|
|
576
1034
|
*/
|
|
577
1035
|
readonly selectDate: (date: LocalDate) => Promise<void>;
|
|
578
|
-
/**
|
|
1036
|
+
/**
|
|
1037
|
+
* Sets the dates that `daysAvailability` covers and loads their availability.
|
|
1038
|
+
*
|
|
1039
|
+
* While it loads, `daysAvailabilityLoading` is `true`, and `daysAvailability` keeps the
|
|
1040
|
+
* previous dates. When it fails to load, `daysAvailabilityHasError` is `true`. A course has no
|
|
1041
|
+
* day availability.
|
|
1042
|
+
*
|
|
1043
|
+
* Ignored for a malformed range, and a range that ends before it starts.
|
|
1044
|
+
*
|
|
1045
|
+
* @param range - Dates to cover, including both ends. A range that's a calendar month moves by
|
|
1046
|
+
* month with `nextDaysAvailabilityRange()` and `previousDaysAvailabilityRange()`.
|
|
1047
|
+
* @returns Promise that resolves once the range is set, before its availability loads.
|
|
1048
|
+
* @example Show the next 7 days' availability
|
|
1049
|
+
* ```tsx
|
|
1050
|
+
* import { useEffect } from 'react';
|
|
1051
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
1052
|
+
*
|
|
1053
|
+
* function WeekAvailability() {
|
|
1054
|
+
* const { timeZone, daysAvailability, daysAvailabilityLoading, setDaysAvailabilityRange } =
|
|
1055
|
+
* useTimeSlotsContext();
|
|
1056
|
+
*
|
|
1057
|
+
* useEffect(() => {
|
|
1058
|
+
* if (!timeZone) return;
|
|
1059
|
+
* // 'en-CA' formats a date as YYYY-MM-DD, here in the context's time zone.
|
|
1060
|
+
* const toLocalDate = (date: Date) => date.toLocaleDateString('en-CA', { timeZone });
|
|
1061
|
+
* const inSixDays = new Date(Date.now() + 6 * 24 * 60 * 60 * 1000);
|
|
1062
|
+
* void setDaysAvailabilityRange({ startDate: toLocalDate(new Date()), endDate: toLocalDate(inSixDays) });
|
|
1063
|
+
* }, [timeZone, setDaysAvailabilityRange]);
|
|
1064
|
+
*
|
|
1065
|
+
* if (daysAvailabilityLoading && !daysAvailability.length) return <p>Loading...</p>;
|
|
1066
|
+
*
|
|
1067
|
+
* return (
|
|
1068
|
+
* <ul>
|
|
1069
|
+
* {daysAvailability.map((day) => (
|
|
1070
|
+
* <li key={day.date}>{day.date}: {day.availability === 'available' ? 'Open' : 'Full or closed'}</li>
|
|
1071
|
+
* ))}
|
|
1072
|
+
* </ul>
|
|
1073
|
+
* );
|
|
1074
|
+
* }
|
|
1075
|
+
* ```
|
|
1076
|
+
*/
|
|
579
1077
|
readonly setDaysAvailabilityRange: (range: LocalDateRange) => Promise<void>;
|
|
580
|
-
/**
|
|
1078
|
+
/**
|
|
1079
|
+
* Moves `daysAvailabilityRange` forward and loads the new dates' availability.
|
|
1080
|
+
*
|
|
1081
|
+
* A range that's a calendar month moves to the next month. Any other range moves forward by
|
|
1082
|
+
* its own length. Does nothing to the range while `daysAvailabilityRange` is `null`.
|
|
1083
|
+
*
|
|
1084
|
+
* @returns Promise that resolves once the range moves, before its availability loads.
|
|
1085
|
+
* @example Move to the next month
|
|
1086
|
+
* ```tsx
|
|
1087
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
1088
|
+
*
|
|
1089
|
+
* function NextMonthButton() {
|
|
1090
|
+
* const { daysAvailabilityRange, daysAvailabilityLoading, nextDaysAvailabilityRange } =
|
|
1091
|
+
* useTimeSlotsContext();
|
|
1092
|
+
*
|
|
1093
|
+
* if (!daysAvailabilityRange) return null;
|
|
1094
|
+
*
|
|
1095
|
+
* return (
|
|
1096
|
+
* <button disabled={daysAvailabilityLoading} onClick={() => nextDaysAvailabilityRange()}>
|
|
1097
|
+
* Next month
|
|
1098
|
+
* </button>
|
|
1099
|
+
* );
|
|
1100
|
+
* }
|
|
1101
|
+
* ```
|
|
1102
|
+
*/
|
|
581
1103
|
readonly nextDaysAvailabilityRange: () => Promise<void>;
|
|
582
|
-
/**
|
|
1104
|
+
/**
|
|
1105
|
+
* Moves `daysAvailabilityRange` back and loads the new dates' availability.
|
|
1106
|
+
*
|
|
1107
|
+
* A range that's a calendar month moves to the previous month. Any other range moves back by
|
|
1108
|
+
* its own length. Does nothing to the range while `daysAvailabilityRange` is `null`.
|
|
1109
|
+
*
|
|
1110
|
+
* @returns Promise that resolves once the range moves, before its availability loads.
|
|
1111
|
+
* @example Move to the previous month
|
|
1112
|
+
* ```tsx
|
|
1113
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
1114
|
+
*
|
|
1115
|
+
* function PreviousMonthButton() {
|
|
1116
|
+
* const { daysAvailabilityRange, daysAvailabilityLoading, previousDaysAvailabilityRange } =
|
|
1117
|
+
* useTimeSlotsContext();
|
|
1118
|
+
*
|
|
1119
|
+
* if (!daysAvailabilityRange) return null;
|
|
1120
|
+
*
|
|
1121
|
+
* return (
|
|
1122
|
+
* <button disabled={daysAvailabilityLoading} onClick={() => previousDaysAvailabilityRange()}>
|
|
1123
|
+
* Previous month
|
|
1124
|
+
* </button>
|
|
1125
|
+
* );
|
|
1126
|
+
* }
|
|
1127
|
+
* ```
|
|
1128
|
+
*/
|
|
583
1129
|
readonly previousDaysAvailabilityRange: () => Promise<void>;
|
|
584
1130
|
/**
|
|
585
|
-
* Selects the first bookable
|
|
586
|
-
*
|
|
587
|
-
*
|
|
1131
|
+
* Selects the first date with a bookable time slot, starting from the selected date, or from
|
|
1132
|
+
* today when no date is selected.
|
|
1133
|
+
*
|
|
1134
|
+
* When that date is outside `daysAvailabilityRange`, the range moves to the date's month. While
|
|
1135
|
+
* it searches, `timeSlotsLoading` is `true`.
|
|
1136
|
+
*
|
|
1137
|
+
* You can call it before the context loads, such as when your component mounts. The search
|
|
1138
|
+
* waits until the service and the time zone are known. Calling `selectDate()` before the
|
|
1139
|
+
* search ends stops it.
|
|
1140
|
+
*
|
|
1141
|
+
* @returns Promise that resolves with the outcome when the search ends.
|
|
1142
|
+
* @example Jump to the next available date
|
|
1143
|
+
* ```tsx
|
|
1144
|
+
* import { useState } from 'react';
|
|
1145
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
1146
|
+
*
|
|
1147
|
+
* function NextAvailableButton() {
|
|
1148
|
+
* const { goToNextAvailableDate } = useTimeSlotsContext();
|
|
1149
|
+
* const [message, setMessage] = useState('');
|
|
1150
|
+
*
|
|
1151
|
+
* async function handleClick() {
|
|
1152
|
+
* const outcome = await goToNextAvailableDate();
|
|
1153
|
+
* if (outcome === 'none') setMessage('No upcoming availability.');
|
|
1154
|
+
* else if (outcome === 'error') setMessage("We couldn't check availability. Try again later.");
|
|
1155
|
+
* else setMessage('');
|
|
1156
|
+
* }
|
|
1157
|
+
*
|
|
1158
|
+
* return (
|
|
1159
|
+
* <div>
|
|
1160
|
+
* <button onClick={handleClick}>Next available date</button>
|
|
1161
|
+
* {message && <p>{message}</p>}
|
|
1162
|
+
* </div>
|
|
1163
|
+
* );
|
|
1164
|
+
* }
|
|
1165
|
+
* ```
|
|
588
1166
|
*/
|
|
589
1167
|
readonly goToNextAvailableDate: () => Promise<NextAvailableDateOutcome>;
|
|
1168
|
+
/**
|
|
1169
|
+
* Whether the visitor can switch the time zone with `setTimeZone()`.
|
|
1170
|
+
*
|
|
1171
|
+
* `true` when the business lets visitors change the time zone, and the visitor's own time zone
|
|
1172
|
+
* differs from `businessTimeZone`. `false` until the context loads in the visitor's browser.
|
|
1173
|
+
*/
|
|
590
1174
|
readonly canChangeTimeZone: boolean;
|
|
591
1175
|
/**
|
|
592
|
-
*
|
|
593
|
-
*
|
|
1176
|
+
* Whether the context holds a multi-service appointment's availability instead of a single
|
|
1177
|
+
* service's. That's the case when the Service context has no service, and the page URL holds
|
|
1178
|
+
* 2 or more services that the visitor selected.
|
|
1179
|
+
*
|
|
1180
|
+
* `false` while the Service context loads, and when it fails to load. `true` even when the
|
|
1181
|
+
* appointment isn't valid. To check that there's availability to request, use
|
|
1182
|
+
* `hasValidSchedulingInput`.
|
|
594
1183
|
*/
|
|
595
1184
|
readonly isMultiService: boolean;
|
|
1185
|
+
/**
|
|
1186
|
+
* Whether the context has a service or a valid multi-service appointment to request
|
|
1187
|
+
* availability for.
|
|
1188
|
+
*
|
|
1189
|
+
* `false` when the service can't be booked online, and while a booking to reschedule loads or
|
|
1190
|
+
* can't be rescheduled.
|
|
1191
|
+
*/
|
|
596
1192
|
readonly hasValidSchedulingInput: boolean;
|
|
597
1193
|
/**
|
|
598
|
-
*
|
|
599
|
-
*
|
|
600
|
-
*
|
|
1194
|
+
* Key that changes whenever the availability request's target changes: the service, or a
|
|
1195
|
+
* multi-service appointment's services, staff members, choices, or location. Selecting a time
|
|
1196
|
+
* slot doesn't change it.
|
|
1197
|
+
*
|
|
1198
|
+
* A multi-service appointment can change while your component stays on the page. To reset
|
|
1199
|
+
* state you keep about a search, such as a "no availability" message, compare this key.
|
|
1200
|
+
*
|
|
1201
|
+
* `null` when `hasValidSchedulingInput` is `false`.
|
|
601
1202
|
*/
|
|
602
1203
|
readonly availabilityRequestKey: string | null;
|
|
603
1204
|
/**
|
|
604
|
-
*
|
|
605
|
-
*
|
|
606
|
-
*
|
|
1205
|
+
* Whether there's no service to show availability for, so nothing is requested.
|
|
1206
|
+
*
|
|
1207
|
+
* `true` when:
|
|
1208
|
+
* - The Service context has no service, and the page URL has no valid multi-service appointment.
|
|
1209
|
+
* - The service, or a service in the appointment, can't be booked online.
|
|
1210
|
+
* - The booking to reschedule can't be rescheduled.
|
|
1211
|
+
*
|
|
1212
|
+
* `false` while the context, the Service context, or a booking to reschedule loads. Also `false`
|
|
1213
|
+
* when the Service context failed to load.
|
|
607
1214
|
*/
|
|
608
1215
|
readonly needsServiceChoice: boolean;
|
|
609
1216
|
/**
|
|
610
|
-
*
|
|
611
|
-
*
|
|
1217
|
+
* Options for a staff filter. Each option is one of:
|
|
1218
|
+
* - A staff member, with its `id`, its `name`, and a `gender` of `null`.
|
|
1219
|
+
* - Any female or any male staff member, with `id` and `gender` both `'ANY_FEMALE'` or
|
|
1220
|
+
* `'ANY_MALE'`, and no name. Label these options in your own words.
|
|
1221
|
+
*
|
|
1222
|
+
* While a location is selected in the location filter, the staff members are only those whose
|
|
1223
|
+
* working hours include that location. A staff member whose working hours aren't known is
|
|
1224
|
+
* always included.
|
|
1225
|
+
*
|
|
1226
|
+
* The 2 gender options come first, when the business offers them and the service has 2 or more
|
|
1227
|
+
* staff members. They're counted before the location narrows them, so the gender options stay
|
|
1228
|
+
* when 1 or no staff member works at the selected location.
|
|
1229
|
+
*
|
|
1230
|
+
* Empty when:
|
|
1231
|
+
* - The business assigns the staff member for an appointment itself.
|
|
1232
|
+
* - The visitor selected a staff member before reaching the page.
|
|
1233
|
+
* - The visitor books a multi-service appointment.
|
|
1234
|
+
* - The business's staff rules fail to load, for an appointment.
|
|
612
1235
|
*/
|
|
613
1236
|
readonly staffFilterOptions: ReadonlyArray<StaffFilterOption>;
|
|
1237
|
+
/**
|
|
1238
|
+
* Options for a location filter, which are the business locations the service is offered at
|
|
1239
|
+
* and at least 1 of its staff members works at, sorted by name, each with its `id` and `name`.
|
|
1240
|
+
* When the visitor selected a staff member before reaching the page, only the locations that
|
|
1241
|
+
* staff member works at. All the service's locations when none would be left. When
|
|
1242
|
+
* rescheduling, the booking's location is included whoever works there, as long as the service
|
|
1243
|
+
* is still offered there. To get a location's details, use the [Locations
|
|
1244
|
+
* API](https://dev.wix.com/docs/api-reference/business-management/locations/introduction).
|
|
1245
|
+
*
|
|
1246
|
+
* Empty when the service is offered at no business location, when the visitor selected a
|
|
1247
|
+
* location before reaching the page, and for a multi-service appointment.
|
|
1248
|
+
*/
|
|
614
1249
|
readonly locationFilterOptions: ReadonlyArray<SelectionOption>;
|
|
615
1250
|
/** The picked staff member's id; null under a gender (see `requestedGender`) or "any". */
|
|
616
1251
|
readonly selectedStaffFilter: string | null;
|
|
1252
|
+
/**
|
|
1253
|
+
* ID of the location that the time slots and the day availability are filtered to. `null`
|
|
1254
|
+
* when they aren't filtered by location.
|
|
1255
|
+
*
|
|
1256
|
+
* It starts from the location the visitor selected before reaching the page, the page URL's
|
|
1257
|
+
* `location` query parameter, or, when rescheduling, the booking's location, when the service
|
|
1258
|
+
* is offered there. The URL's location is also ignored when it isn't in
|
|
1259
|
+
* `locationFilterOptions`, such as a location none of the service's staff members works at.
|
|
1260
|
+
*
|
|
1261
|
+
* When the service is offered at 2 or more locations and its staff members work at only 1 of
|
|
1262
|
+
* them, it's that location, even when the visitor didn't select it.
|
|
1263
|
+
*/
|
|
617
1264
|
readonly selectedLocationFilter: string | null;
|
|
618
1265
|
/**
|
|
619
|
-
*
|
|
620
|
-
*
|
|
1266
|
+
* Filters the time slots and the day availability to 1 staff member, or to any staff member
|
|
1267
|
+
* of 1 gender.
|
|
1268
|
+
*
|
|
1269
|
+
* A staff member and a gender replace each other. Specify `null` to show every staff member's
|
|
1270
|
+
* time slots. Ignored for an ID that isn't in `staffFilterOptions`.
|
|
1271
|
+
*
|
|
1272
|
+
* Changing the filter reloads the time slots, and clears the selected time slot. A time slot
|
|
1273
|
+
* that the visitor selects while the filter is set to a staff member books that staff member.
|
|
1274
|
+
*
|
|
1275
|
+
* @param id - `id` of an option in `staffFilterOptions`: a staff member's ID, `'ANY_FEMALE'`,
|
|
1276
|
+
* or `'ANY_MALE'`. `null` to clear the filter.
|
|
1277
|
+
* @example Add a staff filter
|
|
1278
|
+
* ```tsx
|
|
1279
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
1280
|
+
*
|
|
1281
|
+
* const GENDER_LABELS = {
|
|
1282
|
+
* ANY_FEMALE: 'Any female staff member',
|
|
1283
|
+
* ANY_MALE: 'Any male staff member',
|
|
1284
|
+
* };
|
|
1285
|
+
*
|
|
1286
|
+
* function StaffFilter() {
|
|
1287
|
+
* const { staffFilterOptions, selectedStaffFilter, requestedGender, setStaffFilter } = useTimeSlotsContext();
|
|
1288
|
+
*
|
|
1289
|
+
* if (!staffFilterOptions.length) return null;
|
|
1290
|
+
*
|
|
1291
|
+
* return (
|
|
1292
|
+
* <select
|
|
1293
|
+
* value={selectedStaffFilter ?? requestedGender ?? ''}
|
|
1294
|
+
* onChange={(event) => setStaffFilter(event.target.value || null)}
|
|
1295
|
+
* >
|
|
1296
|
+
* <option value="">Any staff member</option>
|
|
1297
|
+
* {staffFilterOptions.map((option) => (
|
|
1298
|
+
* <option key={option.id} value={option.id}>
|
|
1299
|
+
* {option.gender === null ? option.name : GENDER_LABELS[option.gender]}
|
|
1300
|
+
* </option>
|
|
1301
|
+
* ))}
|
|
1302
|
+
* </select>
|
|
1303
|
+
* );
|
|
1304
|
+
* }
|
|
1305
|
+
* ```
|
|
621
1306
|
*/
|
|
622
1307
|
readonly setStaffFilter: (id: string | null) => void;
|
|
623
|
-
/**
|
|
1308
|
+
/**
|
|
1309
|
+
* Gender that the time slots are filtered to. It comes from a gender option in
|
|
1310
|
+
* `staffFilterOptions`, or from "any female staff member" or "any male staff member" that the
|
|
1311
|
+
* visitor selected before reaching the page.
|
|
1312
|
+
*
|
|
1313
|
+
* `null` when the staff filter is set to a staff member, or to no gender.
|
|
1314
|
+
*
|
|
1315
|
+
* Supported values: `'ANY_FEMALE'`, `'ANY_MALE'`.
|
|
1316
|
+
*/
|
|
624
1317
|
readonly requestedGender: RequestedGender | null;
|
|
625
1318
|
/**
|
|
626
|
-
*
|
|
627
|
-
*
|
|
1319
|
+
* Whether the business offers "any female staff member" and "any male staff member" as staff
|
|
1320
|
+
* choices for this appointment.
|
|
1321
|
+
*
|
|
1322
|
+
* It doesn't depend on how many staff members the service has. `staffFilterOptions` includes
|
|
1323
|
+
* the 2 options only when there are 2 or more.
|
|
628
1324
|
*/
|
|
629
1325
|
readonly genderSelectionAllowed: boolean;
|
|
1326
|
+
/**
|
|
1327
|
+
* Filters the time slots and the day availability to 1 of the business locations the service
|
|
1328
|
+
* is offered at.
|
|
1329
|
+
*
|
|
1330
|
+
* Specify `null` to show the time slots at every location. Ignored for an ID that isn't in
|
|
1331
|
+
* `locationFilterOptions`, and while `locationFilterOptions` is empty.
|
|
1332
|
+
*
|
|
1333
|
+
* Changing the filter reloads the time slots, and clears the selected time slot. It also clears
|
|
1334
|
+
* a staff filter set to a staff member who doesn't work at the new location.
|
|
1335
|
+
*
|
|
1336
|
+
* @param id - ID of the location, from `locationFilterOptions`. `null` to clear the filter.
|
|
1337
|
+
* @example Add a location filter
|
|
1338
|
+
* ```tsx
|
|
1339
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
1340
|
+
*
|
|
1341
|
+
* function LocationFilter() {
|
|
1342
|
+
* const { locationFilterOptions, selectedLocationFilter, setLocationFilter } = useTimeSlotsContext();
|
|
1343
|
+
*
|
|
1344
|
+
* if (locationFilterOptions.length < 2) return null;
|
|
1345
|
+
*
|
|
1346
|
+
* return (
|
|
1347
|
+
* <select
|
|
1348
|
+
* value={selectedLocationFilter ?? ''}
|
|
1349
|
+
* onChange={(event) => setLocationFilter(event.target.value || null)}
|
|
1350
|
+
* >
|
|
1351
|
+
* <option value="">All locations</option>
|
|
1352
|
+
* {locationFilterOptions.map((location) => (
|
|
1353
|
+
* <option key={location.id} value={location.id}>
|
|
1354
|
+
* {location.name}
|
|
1355
|
+
* </option>
|
|
1356
|
+
* ))}
|
|
1357
|
+
* </select>
|
|
1358
|
+
* );
|
|
1359
|
+
* }
|
|
1360
|
+
* ```
|
|
1361
|
+
*/
|
|
630
1362
|
readonly setLocationFilter: (id: string | null) => void;
|
|
631
|
-
/**
|
|
1363
|
+
/**
|
|
1364
|
+
* Selects a time slot for the visitor to book, or clears the selection.
|
|
1365
|
+
*
|
|
1366
|
+
* `selectedTimeSlot` then holds the time slot, and `navigateToBookingForm()` books it. For an
|
|
1367
|
+
* appointment, the staff choice starts over: the staff filter's staff member, the time slot's
|
|
1368
|
+
* only staff member, or "Any available" when it's allowed.
|
|
1369
|
+
*
|
|
1370
|
+
* Ignored for an ID that isn't in `timeSlots`. For a multi-service appointment, a time slot
|
|
1371
|
+
* that doesn't fit the appointment's services isn't selected.
|
|
1372
|
+
*
|
|
1373
|
+
* The selection clears when a date is selected, and when the time zone, the staff filter, or
|
|
1374
|
+
* the location filter changes. Moving between pages of upcoming time slots keeps it.
|
|
1375
|
+
*
|
|
1376
|
+
* @param slotId - `slotId` of a time slot in `timeSlots`. `null` to clear the selection.
|
|
1377
|
+
* @example Show time slots to select
|
|
1378
|
+
* ```tsx
|
|
1379
|
+
* import { useTimeSlotsContext } from '@wix/bookings/context/time-slots';
|
|
1380
|
+
*
|
|
1381
|
+
* function TimeSlotButtons() {
|
|
1382
|
+
* const { timeSlots, selectedTimeSlot, selectTimeSlot } = useTimeSlotsContext();
|
|
1383
|
+
*
|
|
1384
|
+
* return (
|
|
1385
|
+
* <div>
|
|
1386
|
+
* {timeSlots.map((slot) => (
|
|
1387
|
+
* <button
|
|
1388
|
+
* key={slot.slotId}
|
|
1389
|
+
* disabled={!slot.bookable}
|
|
1390
|
+
* aria-pressed={slot.slotId === selectedTimeSlot?.slotId}
|
|
1391
|
+
* onClick={() => selectTimeSlot(slot.slotId)}
|
|
1392
|
+
* >
|
|
1393
|
+
* {slot.slotStartTime?.slice(11, 16)}
|
|
1394
|
+
* </button>
|
|
1395
|
+
* ))}
|
|
1396
|
+
* </div>
|
|
1397
|
+
* );
|
|
1398
|
+
* }
|
|
1399
|
+
* ```
|
|
1400
|
+
*/
|
|
632
1401
|
readonly selectTimeSlot: (slotId: string | null) => void;
|
|
633
1402
|
/**
|
|
634
|
-
*
|
|
635
|
-
*
|
|
1403
|
+
* Whether the visitor can go to the booking form with their choices.
|
|
1404
|
+
*
|
|
1405
|
+
* It's `true` when a time slot is selected. For an appointment, 1 of these must also apply:
|
|
1406
|
+
* - A staff member is chosen.
|
|
1407
|
+
* - "Any available" is allowed.
|
|
1408
|
+
* - The time slot has at most 1 staff member.
|
|
1409
|
+
*
|
|
1410
|
+
* For a multi-service appointment, a selected time slot is enough.
|
|
636
1411
|
*/
|
|
637
1412
|
readonly isComplete: boolean;
|
|
638
|
-
/**
|
|
1413
|
+
/** Whether the selected time slot is confirmed to still be available. Always `false`. */
|
|
639
1414
|
readonly isSelectionValidated: boolean;
|
|
640
1415
|
/** The calendar moves an existing booking (`bookingId` or `token` in its URL). */
|
|
641
1416
|
readonly isRescheduling: boolean;
|
|
@@ -664,7 +1439,14 @@ interface TimeSlotsContextAuthoringProps {
|
|
|
664
1439
|
//#endregion
|
|
665
1440
|
//#region src/extensions/contexts/time-slots-context/time-slots-context.d.ts
|
|
666
1441
|
declare const timeSlotsContext: React.Context<TimeSlotsContextValue | null>;
|
|
667
|
-
/**
|
|
1442
|
+
/**
|
|
1443
|
+
* The `useTimeSlotsContext()` hook provides access to the available dates and time slots of a
|
|
1444
|
+
* service or a multi-service appointment, and to the visitor's choices of date, time zone, staff
|
|
1445
|
+
* member, location, and time slot. Use it to show when a visitor can book, narrow the time slots,
|
|
1446
|
+
* and send the visitor to the booking form with the time slot they select.
|
|
1447
|
+
*
|
|
1448
|
+
* It throws an error where the context isn't available.
|
|
1449
|
+
*/
|
|
668
1450
|
declare function useTimeSlotsContext(): TimeSlotsContextValue;
|
|
669
1451
|
/** Loads the availability of the service in the surrounding ServiceContextProvider, or of the multi-service appointment in the page URL, and holds the visitor's date, time zone, staff, location and slot choices. */
|
|
670
1452
|
declare function TimeSlotsContextProvider(props: TimeSlotsContextProviderProps): React.JSX.Element;
|