@forgebuild/hotal-ui 0.23.48 → 0.23.88

package/dist/index.d.ts

@@ -111,9 +111,16 @@ export interface BookingFlowElement extends HTMLElement {
 }
 
 export interface MenuItem {
+	/** Needed to add this item to a cart (see MenuSectionElement.cartEnabled)
+	 *  -- an item missing this never gets a quantity stepper. */
+	id?: string;
 	name: string;
 	description?: string;
 	price?: string;
+	/** Numeric price for cart math, independent of `price` above (which may
+	 *  be an arbitrary display override a cart can't add up) -- like `id`,
+	 *  required for this item to get a stepper. */
+	priceValue?: number;
 	tagline?: string;
 	group?: string;
 	country?: string;
@@ -125,6 +132,18 @@ export interface MenuCategory {
 	items: MenuItem[];
 }
 
+export interface MenuCartItem {
+	id: string;
+	name: string;
+	price: number;
+	quantity: number;
+}
+
+export interface MenuSectionCartChangeEventDetail {
+	items: MenuCartItem[];
+	total: number;
+}
+
 export interface MenuInfoItem {
 	label: string;
 	value: string;
@@ -156,6 +175,16 @@ export interface MenuSectionElement extends HTMLElement {
 	countryFilter?: boolean;
 	groupFilterAllLabel?: string;
 	countryFilterAllLabel?: string;
+	/** Adds a +/- stepper next to any item with both `id` and `priceValue`
+	 *  (classic variant only, not `panel`) and emits `cart-change` on every
+	 *  change. Off by default -- most hosts use this purely as a read-only
+	 *  display. */
+	cartEnabled?: boolean;
+	/** Restore cart quantities, e.g. from localStorage: [{ id, quantity }].
+	 *  Reactive, not mount-only -- reassign it (a new array) to re-sync
+	 *  quantities a host changed elsewhere, same as
+	 *  ProshopCatalogueElement's own `initial`. */
+	initial?: { id: string; quantity: number }[];
 }
 
 export interface EventInquiry {
@@ -220,10 +249,36 @@ export interface EventInquiryPayload {
 	eventType: string;
 	format: string;
 	message: string;
+	/** The order found via showOrderLookup, or null when the lookup is
+	 *  hidden / nothing was looked up. */
+	orderReference: string | null;
+	/** Ticked lines from that order (empty when none) -- the host decides
+	 *  what an enquiry with items on it means, e.g. a return request. */
+	returnItems: { orderItemId: string; quantity: number }[];
 }
 
 export type SubmitInquiryResult = { ok: true } | { ok: false; error?: string };
 
+export interface ReturnableOrderItem {
+	/** The order line's own id -- echoed back as returnItems[].orderItemId. */
+	id: string;
+	name: string;
+	/** e.g. "Grey — L"; omitted for a plain item. */
+	variant?: string;
+	/** Quantity that can come back -- the cap on the stepper. */
+	quantity: number;
+	/** Unit price; null hides the price. */
+	price: number | null;
+	image?: string;
+}
+
+export interface ReturnableOrder {
+	reference: string;
+	items: ReturnableOrderItem[];
+}
+
+export type LookupOrderResult = { ok: true; order: ReturnableOrder } | { ok: false; error?: string };
+
 export interface EventContactFormStrings {
 	nameLabel: string;
 	namePlaceholder: string;
@@ -252,6 +307,18 @@ export interface EventContactFormStrings {
 	notWiredError: string;
 	genericSubmitError: string;
 	successMessage: string;
+	orderLabel: string;
+	orderPlaceholder: string;
+	findOrderLabel: string;
+	findingOrderLabel: string;
+	clearOrderLabel: string;
+	orderEmailFirstError: string;
+	orderLookupError: string;
+	returnItemsLabel: string;
+	/** `{count}` is replaced with the quantity bought. */
+	boughtLabel: string;
+	decreaseReturnAriaLabel: string;
+	increaseReturnAriaLabel: string;
 }
 
 export interface EventContactFormElement extends HTMLElement {
@@ -299,8 +366,18 @@ export interface EventContactFormElement extends HTMLElement {
 	/** BCP 47 locale (e.g. "fr-FR") used to format month/weekday names in the
 	 *  calendar; defaults to the browser's own locale. */
 	locale?: string;
+	/** Adds an "Order number" input with a Find button (shops: return or
+	 *  exchange enquiries). Finding an order via `lookupOrder` lists its lines
+	 *  as a tick list under the input; ticked lines go out on the payload as
+	 *  returnItems. Default false. */
+	showOrderLookup?: boolean;
+	/** ISO 4217 for the looked-up lines' unit prices. Default 'USD'. */
+	currency?: string;
 	strings?: Partial<EventContactFormStrings>;
 	submitInquiry?: (payload: EventInquiryPayload) => Promise<SubmitInquiryResult>;
+	/** Resolves an order number + the email typed in the form to its returnable
+	 *  lines. Only used when showOrderLookup is true. */
+	lookupOrder?: (reference: string, email: string) => Promise<LookupOrderResult>;
 }
 
 export interface SpaTreatment {
@@ -366,6 +443,10 @@ export interface SpaBookingWidgetElement extends HTMLElement {
 	/** Shown as a "Staff" row in the summary panel once a service is picked.
 	 *  Purely presentational -- there is no staff picker. Omit to hide the row. */
 	staffLabel?: string;
+	/** Hides every price display (service list, summary rows, total) -- for
+	 *  a free service (e.g. a consultation call) where showing "£0.00"
+	 *  throughout would read oddly. */
+	hidePrice?: boolean;
 	/** JS `Date#getDay()` values (0 = Sunday) to gray out on the calendar,
 	 *  e.g. `[2]` for a Tuesday closure. Visual hint only -- fetchAvailability
 	 *  is the real source of truth for what's bookable. */
@@ -698,6 +779,64 @@ export interface LiveDiningOrdersFeedElement extends HTMLElement {
 	filterBookingId?: string;
 }
 
+export interface ShopOrderItem {
+	id?: string;
+	item_id?: string;
+	item_name: string;
+	quantity: number;
+	unit_price?: string | number;
+	total?: string | number;
+	/** e.g. size/color ("M / Navy") for apparel-style items. */
+	variant?: string | null;
+}
+
+export interface ShopOrder {
+	id: string;
+	booking_id?: string | null;
+	guest_id?: string | null;
+	status: string;
+	notes?: string | null;
+	fulfillment_method?: 'pickup' | 'shipping' | null;
+	total_price: string | number;
+	created_at: string;
+	items: ShopOrderItem[];
+}
+
+export interface ShopOrderBookingRef {
+	id: string;
+	room_number?: string | null;
+	guest_name?: string | null;
+}
+
+export interface LiveShopOrdersFeedElement extends HTMLElement {
+	heading?: string;
+	channelName?: string;
+	ablyAuthUrl?: string;
+	/** Fetches one page of order history, newest-first; Ably only delivers
+	 *  events published after the subscription starts, so history has to
+	 *  come from a REST call. Omit `cursor` for the first page; each
+	 *  subsequent call passes the `created_at` of the oldest loaded order so
+	 *  only the next page is fetched. Return fewer than `limit` items to
+	 *  signal there's nothing older left. */
+	fetchOrders?: (params: { cursor?: string; limit: number }) => Promise<ShopOrder[]>;
+	/** Resolves booking_id -> room/guest, since the order payload carries
+	 *  only the id. */
+	bookings?: ShopOrderBookingRef[];
+	maxItems?: number;
+	/** Set false to stop fetching further pages once the first one loads --
+	 *  disables the scroll-to-bottom sentinel entirely rather than swapping
+	 *  in a manual button. Default true. */
+	autoLoadMore?: boolean;
+	emptyLabel?: string;
+	/** Symbol prefixed to money amounts ('€', '$', ...); the payload carries
+	 *  no currency of its own. Default empty (bare amount). */
+	currency?: string;
+	/** Restricts the feed to one booking's orders -- `fetchOrders` should
+	 *  already be scoped server-side; this only filters the live `new-order`
+	 *  events, which otherwise arrive unfiltered off the channel. */
+	filterBookingId?: string;
+}
+
 export interface VenueCarouselSlide {
 	key: string;
 	src: string;
@@ -957,6 +1096,9 @@ export interface BookingCheckoutElement extends HTMLElement {
 	locations?: BookingCheckoutLocation[];
 	defaultPhoneCode?: string;
 	allowBookingForOther?: boolean;
+	/** Hides the "Booking for myself/someone else" toggle entirely (not just
+	 *  the "other" option) -- for checkouts that aren't a booking at all. */
+	showBookingFor?: boolean;
 	termsHref?: string;
 	prefill?: BookingCheckoutPrefill;
 	resolveInitialLocation?: () => Promise<BookingCheckoutResolvedLocation | null>;
@@ -1161,6 +1303,11 @@ export interface GoogleReviewItem {
 	text: string;
 	relative_time?: string;
 	published_at?: string | null;
+	/** Photos the reviewer attached to their review (not the same as
+	 *  author_photo, which is their profile picture). Only ever populated
+	 *  when the host's fetchReviews is backed by SerpApi's Google Maps
+	 *  Reviews API -- Google's own official Places API never exposes these. */
+	photos?: string[] | null;
 }
 
 /** The payload <google-reviews> renders -- the shape served by the OTA's
@@ -1192,10 +1339,62 @@ export interface GoogleReviewsElement extends HTMLElement {
 	/** Slider only: seconds between automatic advances; 0/unset = off. */
 	autoAdvance?: number;
 	maxReviews?: number;
+	/** Sweeps a light band across the CTA on hover instead of the default
+	 *  opacity dip. Off by default. */
+	ctaShimmer?: boolean;
 	strings?: Partial<GoogleReviewsStrings>;
 	fetchReviews?: () => Promise<GoogleReviewsPayload>;
 }
 
+export interface TripadvisorReviewItem {
+	author: string;
+	author_photo?: string | null;
+	rating: number;
+	text: string;
+	relative_time?: string;
+	published_at?: string | null;
+	/** Photos the reviewer attached to their review. */
+	photos?: string[] | null;
+}
+
+/** The payload <tripadvisor-reviews> renders. Same shape as
+ *  GoogleReviewsPayload (maps_url/write_review_url renamed to place_url,
+ *  since Tripadvisor has no equivalent one-click write-review deep link). */
+export interface TripadvisorReviewsPayload {
+	rating: number | null;
+	count: number;
+	place_url?: string | null;
+	write_review_url?: string | null;
+	reviews: TripadvisorReviewItem[];
+	fetched_at?: string;
+}
+
+export interface TripadvisorReviewsStrings {
+	reviewsLabel: string;
+	ctaLabel: string;
+	seeAllLabel: string;
+	loadingLabel: string;
+	errorLabel: string;
+}
+
+/** <tripadvisor-reviews>: live Tripadvisor rating, count, and the latest
+ *  review cards. Same shape and behaviour as <google-reviews> (see its own
+ *  doc comment) -- a separate component rather than a shared one because
+ *  each review source gets its own summary doc, seed script, and branding.
+ *  Theme via --ta-*. */
+export interface TripadvisorReviewsElement extends HTMLElement {
+	/** 'grid' (default) or 'slider' (scroll-snap track with prev/next arrows). */
+	variant?: 'grid' | 'slider';
+	/** Slider only: seconds between automatic advances; 0/unset = off. */
+	autoAdvance?: number;
+	maxReviews?: number;
+	/** Sweeps a light band across the CTA on hover instead of the default
+	 *  opacity dip. Off by default. */
+	ctaShimmer?: boolean;
+	strings?: Partial<TripadvisorReviewsStrings>;
+	fetchReviews?: () => Promise<TripadvisorReviewsPayload>;
+}
+
 /** <ai-chat-widget>: a floating chat launcher + panel that talks to a
  *  host-provided chat API endpoint (any AI SDK v5+ UI-message-stream route).
  *  Knows nothing about the model, tools, or business data behind `api` --
@@ -1214,10 +1413,138 @@ export interface AiChatWidgetElement extends HTMLElement {
 	phone?: string;
 }
 
+/** One purchasable combination within a variant group -- a real, distinct
+ *  catalogue item (own id, own price, own stock on the host's backend), just
+ *  presented as a pill (or a pill pair, one per axis) under the group's
+ *  single card instead of a separate card of its own. */
+export interface ProshopVariant {
+	id: string;
+	/** First axis value, e.g. a color: "Blue". */
+	option1: string;
+	/** Second, independent axis value, e.g. a size: "Small". Omit when this
+	 *  group only varies along one axis -- the second pill row never renders
+	 *  unless at least one variant sets this. */
+	option2?: string;
+	price: number | null;
+	/** Swaps the card's photo when this variant becomes selected -- e.g. a
+	 *  different photo per color. Omit on a variant that doesn't change the
+	 *  photo (e.g. a size-only difference): the card falls back to the group
+	 *  item's own `image` whenever the selected variant has none of its own. */
+	image?: string | null;
+}
+
+export interface ProshopItem {
+	id: string;
+	name: string;
+	description?: string;
+	category?: string;
+	image?: string | null;
+	price: number | null;
+	/** When set, the photo + name link here (e.g. a product detail page).
+	 *  Omit for a catalogue with no such page -- the card stays static. */
+	href?: string | null;
+	/** Renders this card as a variant group: one pill row per axis (e.g.
+	 *  color, and independently size) beneath the description, switching
+	 *  which real item id/price the qty stepper and cart operate on.
+	 *  `id`/`price` above are only the initial (first-variant) display
+	 *  values. Each entry is a genuinely separate catalogue item, so per-
+	 *  variant stock still works with no other change -- the host just
+	 *  supplies N real items grouped under one display card instead of N
+	 *  separate cards. */
+	variants?: ProshopVariant[];
+	/** Header shown above each pill row, e.g. ["Color", "Size"]. Purely
+	 *  cosmetic -- omit for no header, or supply just the first to label
+	 *  only a single-axis group. */
+	variantAxisLabels?: [string, string?];
+}
+
+export interface ProshopCartItem {
+	id: string;
+	name: string;
+	price: number;
+	quantity: number;
+}
+
+export interface ProshopCatalogueChangeEventDetail {
+	items: ProshopCartItem[];
+	total: number;
+}
+
+/** <proshop-catalogue>: browse + cart-build a shop/pro-shop catalogue (merch,
+ *  equipment, etc.) -- category tabs, a card grid (photo/name/price/qty
+ *  stepper), and a sticky cart-total bar. Stops at the cart on purpose:
+ *  checkout (contact details + Stripe payment) is <booking-checkout>'s job --
+ *  feed this component's `cart-change` total/items into that one rather than
+ *  building a second payment flow. Emits `cart-change` on every quantity
+ *  change. Theme via --pc-*. */
+export interface ProshopCatalogueElement extends HTMLElement {
+	items?: ProshopItem[];
+	currency?: string;
+	/** Explicit category display order; categories not listed here are
+	 *  appended in first-seen order. Omit to use first-seen order only. */
+	categoryOrder?: string[];
+	/** Overrides the auto-generated label for a category key -- otherwise a
+	 *  category key is shown verbatim. */
+	categoryLabels?: Record<string, string>;
+	/** Restore cart quantities, e.g. from localStorage: [{ id, quantity }].
+	 *  Reactive, not mount-only -- reassign it (a new array) after mount to
+	 *  re-sync quantities a host changed elsewhere, e.g. a checkout sidebar. */
+	initial?: { id: string; quantity: number }[];
+	/** Adds a leading tab (before every real category) that shows every item
+	 *  across all categories in one grid, and becomes the default active tab.
+	 *  Omit (default false) to keep the default of the first real category
+	 *  with no all-items tab. */
+	showAllTab?: boolean;
+	/** Label for the all-items tab. Only used when `showAllTab` is true.
+	 *  Default: `'All'`. */
+	allTabLabel?: string;
+}
+
+export interface InstagramFeedPost {
+	id: string;
+	image: string;
+	caption?: string | null;
+	permalink?: string | null;
+	likeCount?: number | null;
+	commentCount?: number | null;
+}
+
+export interface InstagramFeedStrings {
+	followersLabel: string;
+	viewProfileLabel: string;
+	emptyLabel: string;
+}
+
+/** <instagram-feed>: a curated grid/slider of Instagram posts plus a
+ *  follower-count header and "View profile" link. Unlike GoogleReviews/
+ *  TripadvisorReviews, `posts` arrives as a plain prop, not a fetchX
+ *  callback -- there's no live per-request fetch to make, so no loading/
+ *  error state. Same slider mechanics (continuous loop, auto-advance,
+ *  pause on hover/focus) as those two for consistency. No heading/eyebrow
+ *  of its own -- that's host-page copy, same split as <google-reviews>.
+ *  Theme via --if-*. */
+export interface InstagramFeedElement extends HTMLElement {
+	posts?: InstagramFeedPost[];
+	/** Shown as the header stat, e.g. "4.3K Followers". Omit to hide the stat entirely. */
+	followers?: number;
+	/** The real instagram.com/<handle> URL -- the "View profile" link, and a
+	 *  post's link fallback when it has no permalink of its own. */
+	profileUrl?: string;
+	/** 'grid' (default) or 'slider' (scroll-snap track with prev/next arrows). */
+	variant?: 'grid' | 'slider';
+	/** Slider only: seconds between automatic advances; 0/unset = off. */
+	autoAdvance?: number;
+	/** Cap on rendered post tiles. Default 12. */
+	maxPosts?: number;
+	strings?: Partial<InstagramFeedStrings>;
+}
+
 declare global {
 	interface HTMLElementTagNameMap {
 		'ai-chat-widget': AiChatWidgetElement;
 		'google-reviews': GoogleReviewsElement;
+		'tripadvisor-reviews': TripadvisorReviewsElement;
+		'instagram-feed': InstagramFeedElement;
 		'service-booking-bar': ServiceBookingBarElement;
 		'reservation-bar': ReservationBarElement;
 		'booking-flow': BookingFlowElement;
@@ -1231,6 +1558,7 @@ declare global {
 		'live-spa-bookings-feed': LiveSpaBookingsFeedElement;
 		'live-golf-bookings-feed': LiveGolfBookingsFeedElement;
 		'live-dining-orders-feed': LiveDiningOrdersFeedElement;
+		'live-shop-orders-feed': LiveShopOrdersFeedElement;
 		'venue-carousel': VenueCarouselElement;
 		'room-grid': RoomGridElement;
 		'island-map': IslandMapElement;
@@ -1247,12 +1575,14 @@ declare global {
 		'searchable-select': SearchableSelectElement;
 		'booking-confirmed': BookingConfirmedElement;
 		'restaurant-order-form': RestaurantOrderFormElement;
+		'proshop-catalogue': ProshopCatalogueElement;
 	}
 
 	interface HTMLElementEventMap {
 		reservationchange: CustomEvent<{ date: string; guests: number; time: string }>;
 		'booking-confirmed': CustomEvent<{ date: string; time: string; guests: number }>;
 		'inquiry-submitted': CustomEvent<EventInquiryPayload>;
+		'order-found': CustomEvent<{ reference: string }>;
 		'booking-submitted': CustomEvent<SpaBookingPayload>;
 		'cancel-requested': CustomEvent<ReservationCancelPayload>;
 		'cancel-confirmed': CustomEvent<{ token: string }>;
@@ -1267,6 +1597,7 @@ declare global {
 		'checkout-confirmed': CustomEvent<{ ref?: string }>;
 		ready: CustomEvent<undefined>;
 		'extras-change': CustomEvent<ExtrasCatalogueChangeEventDetail>;
+		'cart-change': CustomEvent<ProshopCatalogueChangeEventDetail>;
 		'order-placed': CustomEvent<RestaurantOrderPlacedEventDetail>;
 		'date-filter-change': CustomEvent<LiveReservationsFeedDateFilterEventDetail>;
 		// Not declared here: `searchable-select` dispatches a CustomEvent named

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgebuild/hotal-ui",
-  "version": "0.23.48",
+  "version": "0.23.88",
   "description": "Reusable Svelte UI components for booking and reservation experiences.",
   "type": "module",
   "license": "MIT",