@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.
Files changed (71) hide show
  1. package/_sdk-exports/context-booking-checkout/runtime.d.ts +791 -143
  2. package/_sdk-exports/context-booking-checkout/runtime.js +3 -2
  3. package/_sdk-exports/context-categories/runtime.d.ts +164 -2
  4. package/_sdk-exports/context-categories/runtime.js +2 -1
  5. package/_sdk-exports/context-locations/runtime.d.ts +186 -2
  6. package/_sdk-exports/context-locations/runtime.js +2 -1
  7. package/_sdk-exports/context-service/runtime.d.ts +1540 -144
  8. package/_sdk-exports/context-service/runtime.js +3 -2
  9. package/_sdk-exports/context-service-addons/runtime.d.ts +215 -13
  10. package/_sdk-exports/context-service-addons/runtime.js +2 -1
  11. package/_sdk-exports/context-services/runtime.d.ts +371 -77
  12. package/_sdk-exports/context-services/runtime.js +3 -2
  13. package/_sdk-exports/context-time-slots/runtime.d.ts +854 -72
  14. package/_sdk-exports/context-time-slots/runtime.js +3 -2
  15. package/build/cjs/context-booking-checkout.d.ts +791 -143
  16. package/build/cjs/context-booking-checkout.js +1759 -1640
  17. package/build/cjs/context-booking-checkout.js.map +1 -1
  18. package/build/cjs/context-categories.d.ts +164 -2
  19. package/build/cjs/context-categories.js +116 -114
  20. package/build/cjs/context-categories.js.map +1 -1
  21. package/build/cjs/context-locations.d.ts +186 -2
  22. package/build/cjs/context-locations.js +126 -124
  23. package/build/cjs/context-locations.js.map +1 -1
  24. package/build/cjs/context-service-addons.d.ts +215 -13
  25. package/build/cjs/context-service-addons.js +323 -321
  26. package/build/cjs/context-service-addons.js.map +1 -1
  27. package/build/cjs/context-service.d.ts +1540 -144
  28. package/build/cjs/context-service.js +1622 -1616
  29. package/build/cjs/context-service.js.map +1 -1
  30. package/build/cjs/context-services.d.ts +371 -77
  31. package/build/cjs/context-services.js +460 -458
  32. package/build/cjs/context-services.js.map +1 -1
  33. package/build/cjs/context-time-slots.d.ts +854 -72
  34. package/build/cjs/context-time-slots.js +1033 -1000
  35. package/build/cjs/context-time-slots.js.map +1 -1
  36. package/build/es/context-booking-checkout.d.mts +791 -143
  37. package/build/es/context-booking-checkout.mjs +1778 -1650
  38. package/build/es/context-booking-checkout.mjs.map +1 -1
  39. package/build/es/context-categories.d.mts +164 -2
  40. package/build/es/context-categories.mjs +116 -114
  41. package/build/es/context-categories.mjs.map +1 -1
  42. package/build/es/context-locations.d.mts +186 -2
  43. package/build/es/context-locations.mjs +126 -124
  44. package/build/es/context-locations.mjs.map +1 -1
  45. package/build/es/context-service-addons.d.mts +215 -13
  46. package/build/es/context-service-addons.mjs +323 -321
  47. package/build/es/context-service-addons.mjs.map +1 -1
  48. package/build/es/context-service.d.mts +1540 -144
  49. package/build/es/context-service.mjs +1622 -1616
  50. package/build/es/context-service.mjs.map +1 -1
  51. package/build/es/context-services.d.mts +371 -77
  52. package/build/es/context-services.mjs +460 -458
  53. package/build/es/context-services.mjs.map +1 -1
  54. package/build/es/context-time-slots.d.mts +854 -72
  55. package/build/es/context-time-slots.mjs +1033 -1000
  56. package/build/es/context-time-slots.mjs.map +1 -1
  57. package/build/internal/cjs/context-booking-checkout.d.ts +791 -143
  58. package/build/internal/cjs/context-categories.d.ts +164 -2
  59. package/build/internal/cjs/context-locations.d.ts +186 -2
  60. package/build/internal/cjs/context-service-addons.d.ts +215 -13
  61. package/build/internal/cjs/context-service.d.ts +1540 -144
  62. package/build/internal/cjs/context-services.d.ts +371 -77
  63. package/build/internal/cjs/context-time-slots.d.ts +854 -72
  64. package/build/internal/es/context-booking-checkout.d.mts +791 -143
  65. package/build/internal/es/context-categories.d.mts +164 -2
  66. package/build/internal/es/context-locations.d.mts +186 -2
  67. package/build/internal/es/context-service-addons.d.mts +215 -13
  68. package/build/internal/es/context-service.d.mts +1540 -144
  69. package/build/internal/es/context-services.d.mts +371 -77
  70. package/build/internal/es/context-time-slots.d.mts +854 -72
  71. 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$1 {
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`); the public `@wix/bookings` typings don't declare it yet, so
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
- * `found`: selected the first bookable date (maybe the selected one). `none`: no bookable slot,
440
- * or nothing to search (no service, a course). `error`: see `timeSlotsErrorCode`. `cancelled`:
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
- type NextAvailableDateOutcome = 'found' | 'none' | 'error' | 'cancelled';
444
- /** Raw SDK slot, kept private for booking. */
445
- type TimeSlot = TimeSlot$1;
446
- /** Builder-safe slot. */
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
- /** Local date-time. */
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
- /** Local date-time. */
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
- /** What the visitor can book under current policy. */
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
- /** Class slots only. */
495
+ /**
496
+ * ID of the class session's calendar event.
497
+ *
498
+ * `null` for an appointment.
499
+ */
459
500
  readonly eventId: string | null;
460
- /** Class slots only. */
501
+ /**
502
+ * Title of the class session's calendar event.
503
+ *
504
+ * `null` for an appointment.
505
+ */
461
506
  readonly eventTitle: string | null;
462
- /** Remaining waitlist spots; class slots only. */
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
- /** Minutes, in the slot's timezone. */
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
- /** Empty when staff choice is hidden (CUSTOMER_CANNOT_CHOOSE, no staff-priced variant). */
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
- * Why the time slots can't be shown. Untranslated: word each code in your own text.
495
- * - `onlineBookingOff`: the service can't be booked online.
496
- * - `rescheduleLoginRequired`: the visitor must log in to reschedule the booking.
497
- * - `rescheduleNotFound`: the booking to reschedule wasn't found or didn't load, or it isn't for this service.
498
- * - `rescheduleAccessDenied`: the visitor isn't allowed to view the booking to reschedule.
499
- * - `rescheduleNotReschedulable`: the booking can't be rescheduled online.
500
- * - `timeZoneMissing`: session times can't be shown because the time zone is unknown.
501
- * - `upcomingSlotsLoadFailed`: the upcoming time slots (with no date picked) failed to load.
502
- * - `timeSlotsLoadFailed`: the time slots failed to load.
503
- * - `loadFailed`: the time slots context failed to load.
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
- type TimeSlotsErrorCode = 'onlineBookingOff' | 'rescheduleLoginRequired' | 'rescheduleNotFound' | 'rescheduleAccessDenied' | 'rescheduleNotReschedulable' | 'timeZoneMissing' | 'upcomingSlotsLoadFailed' | 'timeSlotsLoadFailed' | 'loadFailed';
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
- /** The availability of the current service or multi-service appointment: its time slots, day availability, upcoming slots, filters, and the actions to browse and pick them. */
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
- /** The default, and one of the visitor's zone options. */
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
- /** Only when the booking policy allows. */
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
- * Idempotent: callers share one query, which refetches on input change. Resolves when page 1
529
- * lands or fails, or at once when there is nothing to list.
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
- /** Shows the previous cached page. */
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
- /** On the selected slot. Empty when the business hides the staff choice. */
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
- * From service-context's `b=` (entry, else `?resource=`, else the preferences modal). Null is
541
- * "Any available" or no choice yet.
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
- /** Writes the staff choice to the blob; null is an explicit "Any available". */
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
- /** "Any available" is bookable on the selected slot (OOI canAutoAssignStaff). */
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
- /** Rows per day before "load all"; null when uncapped. */
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
- /** Exact, not guessed. */
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
- /** Empty until first loaded. With `onlyAvailableSlots`, a day with only full slots is `none`. */
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
- * Replaces `timeSlots` with that day's slots. Ignores past or malformed dates; reselecting
574
- * refreshes. Resolves once stored (watch `timeSlotsLoading`). Before the service is known it
575
- * waits, then drops for a course or no service.
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
- /** An inverted or malformed range is ignored. */
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
- /** A calendar month moves by month; any other range by its length. */
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
- /** A calendar month moves by month; any other range by its length. */
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 date on or after the selected date (or today), moving the range
586
- * if needed. Reports via `timeSlotsLoading`/`timeSlotsErrorCode`. Held until service, zone and
587
- * today are known (no service resolves `none`); a `selectDate` meanwhile cancels it.
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
- * Multi-Service Appointment calendar: no service, service-context settled without error, and
593
- * 2+ services in the Booking Preferences (valid or not).
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
- * Changes with the request target (service, or MSA services/staff/choices/location), not with
599
- * a picked time. Null with no valid input. An MSA changes in place without a remount, so
600
- * builders that remember a search outcome key on this.
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
- * Invalid or missing Booking Preferences, or a service with online booking off (nothing
605
- * loading, no service-context error); nothing is requested. The editor keeps its placeholders,
606
- * so builders gate it.
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
- * Independent of the location filter. Empty when the business hides the staff choice. The two
611
- * gender options lead when the business allows gender selection and 2+ staff members are offered.
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
- * Takes an option's id; a staff member and a gender replace each other. Only narrows the
620
- * requests; a slot picked under a staff member writes them to the blob.
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
- /** The picked gender option's id, which the requests narrow by; null under a named staff member. */
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
- * The business offers 'any female/male staff member' here (settings on, not rejected, an
627
- * appointment). Ignores the staff count; the editor's Staff Filter sample uses it.
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
- /** Writes the slot and its location to the blob. Null drops the pick. */
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
- * A slot is selected and, for an appointment, staff is chosen, auto-assign is allowed, or the
635
- * slot has at most one staff member. On the MSA calendar a slot is enough.
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
- /** The selection still exists in availability. */
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
- /** Reads the time slots state; throws when no TimeSlotsContextProvider is above. */
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;