@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
@@ -65,7 +65,7 @@ declare global {
65
65
  interface SDKTypeMode {}
66
66
  }
67
67
  //#endregion
68
- //#region ../../node_modules/@wix/auto_sdk_bookings_services/build/es/bookings-services-v2-service-services.universal-Bf4TC5aj.d.mts
68
+ //#region ../../node_modules/@wix/auto_sdk_bookings_services/build/es/bookings-services-v2-service-services.universal-p5eQUd5f.d.mts
69
69
  interface V2Category {
70
70
  /**
71
71
  * Category ID.
@@ -101,22 +101,178 @@ interface CategoriesPickerFilter {
101
101
  //#region src/extensions/contexts/categories-context/categories-context.d.ts
102
102
  /** A service category as shown in a category list, with its selected state. */
103
103
  interface CategoryItem {
104
+ /**
105
+ * Category ID. Pass it to `selectCategory()` to select the category.
106
+ *
107
+ * `null` when the category has no ID. A category with no ID can't be selected, because passing
108
+ * `null` to `selectCategory()` clears the selection. Leave these items out of a category filter.
109
+ */
104
110
  categoryId: string | null;
111
+ /**
112
+ * Category name.
113
+ *
114
+ * `null` when the category has no name.
115
+ */
105
116
  categoryName: string | null;
117
+ /**
118
+ * Whether the category is selected, meaning its ID is in the page URL's `category` query
119
+ * parameter.
120
+ */
106
121
  isSelected: boolean;
107
122
  }
108
123
  /** The business service categories, the selected category, the loading and error state, and the actions to change or reload them. */
109
124
  interface CategoriesContextValue {
125
+ /**
126
+ * Service categories, sorted by their sort order. Each category holds its details, such as its
127
+ * ID, name, and sort order. To manage categories, use the
128
+ * [Categories V2
129
+ * API](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/categories-v2/introduction).
130
+ *
131
+ * Holds only the categories that have bookable services. When the Data Source's settings pick
132
+ * categories, it holds only the picked categories.
133
+ *
134
+ * Empty while the categories load, and when they fail to load.
135
+ *
136
+ * Don't change the array or its items, for example by sorting the array in place. Every
137
+ * component that uses the context gets the same array.
138
+ */
110
139
  categories: Category[];
140
+ /**
141
+ * Service categories as list items, each with its ID, name, and whether it's selected. Use them
142
+ * to render a list of categories that site visitors select from.
143
+ *
144
+ * Holds the same categories as `categories`, in the same order.
145
+ */
111
146
  categoryItems: CategoryItem[];
147
+ /**
148
+ * ID of the selected category, from the page URL's `category` query parameter.
149
+ *
150
+ * It already holds the URL's category while the categories load, before `categories` fills. It
151
+ * can hold an ID that isn't in `categories`, such as an ID from an outdated link.
152
+ * `selectedCategory` is then `null`.
153
+ *
154
+ * `null` when no category is selected.
155
+ */
112
156
  selectedCategoryId: string | null;
157
+ /**
158
+ * Position of the selected category in `categories`, starting at `0`.
159
+ *
160
+ * `-1` when no category is selected, when `selectedCategoryId` isn't in `categories`, and while
161
+ * the categories load.
162
+ */
113
163
  selectedCategoryIndex: number;
164
+ /**
165
+ * Selected category, with its details, such as its ID, name, and sort order.
166
+ *
167
+ * `null` when no category is selected, when `selectedCategoryId` isn't in `categories`, and
168
+ * while the categories load.
169
+ */
114
170
  selectedCategory: Category | null;
171
+ /**
172
+ * Name of the selected category.
173
+ *
174
+ * `null` when `selectedCategory` is `null`, or when the category has no name.
175
+ */
115
176
  selectedCategoryName: string | null;
177
+ /**
178
+ * Whether `categories` holds multiple categories with an ID. Use it to hide a category filter
179
+ * when there's nothing to choose between.
180
+ *
181
+ * `false` while the categories load, and when they fail to load.
182
+ */
116
183
  hasMultipleCategories: boolean;
184
+ /**
185
+ * Whether the categories are loading. It's `true` during the first load, and while `refetch()`
186
+ * reloads them.
187
+ *
188
+ * While it's `true`, `categories` and `categoryItems` are empty, and `selectCategory()` does
189
+ * nothing.
190
+ */
117
191
  isLoading: boolean;
192
+ /**
193
+ * Whether the categories failed to load.
194
+ *
195
+ * When it's `true`, `categories` and `categoryItems` are empty. To try again, call `refetch()`.
196
+ *
197
+ * It's also `true`, with the same empty values, after a component under the context fails to
198
+ * render. Then it stays `true` until the page reloads: `refetch()` doesn't clear it, and
199
+ * `selectCategory()` does nothing.
200
+ */
118
201
  hasError: boolean;
202
+ /**
203
+ * Reloads the service categories.
204
+ *
205
+ * While they reload, `isLoading` is `true`, and `categories` and `categoryItems` are empty. The
206
+ * selected category doesn't change.
207
+ *
208
+ * Use it to try again after the categories fail to load, when `hasError` is `true`. It doesn't
209
+ * clear `hasError` when a component under the context failed to render.
210
+ *
211
+ * @example Retry loading the categories after a failure
212
+ * ```tsx
213
+ * import { useCategoriesContext } from '@wix/bookings/context/categories';
214
+ *
215
+ * function CategoriesErrorMessage() {
216
+ * const { hasError, refetch } = useCategoriesContext();
217
+ *
218
+ * if (!hasError) {
219
+ * return null;
220
+ * }
221
+ *
222
+ * return (
223
+ * <p>
224
+ * We couldn't load the service categories.{' '}
225
+ * <button onClick={() => refetch()}>Try again</button>
226
+ * </p>
227
+ * );
228
+ * }
229
+ * ```
230
+ */
119
231
  refetch: () => void;
232
+ /**
233
+ * Selects a category, or clears the selection.
234
+ *
235
+ * Selecting a category sets the page URL's `category` query parameter, which updates
236
+ * `selectedCategoryId` and the other properties about the selected category. When it changes
237
+ * the selection, `selectCategory()`:
238
+ * - Adds an entry to the browser history, so the browser's Back button returns to the previous
239
+ * selection.
240
+ * - Removes the URL's `page` query parameter, so a list of services on the page starts again
241
+ * from its first page.
242
+ * - Keeps the page's scroll position.
243
+ *
244
+ * It doesn't check that the ID is in `categories`.
245
+ *
246
+ * Does nothing while `isLoading` is `true`.
247
+ *
248
+ * @param categoryId - ID of the category to select. Pass `null` to clear the selection, such as
249
+ * for an "All services" option.
250
+ *
251
+ * @example Select a category from a dropdown
252
+ * ```tsx
253
+ * import { useCategoriesContext } from '@wix/bookings/context/categories';
254
+ *
255
+ * function CategoryDropdown() {
256
+ * const { categoryItems, selectedCategoryId, selectCategory } = useCategoriesContext();
257
+ *
258
+ * return (
259
+ * <select
260
+ * value={selectedCategoryId ?? ''}
261
+ * onChange={(event) => selectCategory(event.target.value || null)}
262
+ * >
263
+ * <option value="">All services</option>
264
+ * {categoryItems
265
+ * .filter((item) => item.categoryId)
266
+ * .map((item) => (
267
+ * <option key={item.categoryId} value={item.categoryId ?? ''}>
268
+ * {item.categoryName}
269
+ * </option>
270
+ * ))}
271
+ * </select>
272
+ * );
273
+ * }
274
+ * ```
275
+ */
120
276
  selectCategory: (categoryId: string | null) => void;
121
277
  }
122
278
  /** Props accepted by {@link CategoriesContextProvider}. */
@@ -131,7 +287,13 @@ interface CategoriesContextProviderProps {
131
287
  }
132
288
  declare const categoriesContext: React.Context<CategoriesContextValue | null>;
133
289
  declare const CATEGORIES_CONTEXT_MISSING_PROVIDER_ERROR = "useCategoriesContext must be used within CategoriesContextProvider";
134
- /** Reads the categories state; throws when no CategoriesContextProvider is above. */
290
+ /**
291
+ * The `useCategoriesContext()` hook provides access to the business's service categories and the
292
+ * category a site visitor selected. Use it to show the categories and let site visitors select one
293
+ * to filter the services on the page.
294
+ *
295
+ * It throws an error where the context isn't available.
296
+ */
135
297
  declare function useCategoriesContext(): CategoriesContextValue;
136
298
  /** Loads the business service categories and tracks the selected category in the page URL. */
137
299
  declare function CategoriesContextProvider({