@wix/himalaya-cli 0.1528.0 → 0.1530.0

package/templates/gym-fitness/tier5-src/_shared/collection-service.ts

@@ -12,11 +12,15 @@ export interface CollectionSaving {
 type State = Record<string, unknown>;
 interface BackendCollection {
   restorePagesOnLoad?: boolean;
-  /** Sees the load action's argument (the screen's onAppear params) BEFORE the query runs. */
-  onLoad?(arg: unknown): void;
+  /** Sees the load action's argument (the screen's onAppear params) BEFORE the query runs. A returned
+   *  `{ filter, sort }` resets the criteria for that load (a screen that always opens on one view). */
+  onLoad?(arg: unknown): CollectionCriteriaReset | void;
   controller: ReturnType<typeof createCollectionQuery<CollectionRow>>;
   apply(state: State, page: CollectionQueryState<CollectionRow>): State;
 }
+/** A filter and a sort set together (`collectionCriteria`, `onLoad`). Values the collection's contract does
+ *  not list are ignored. */
+export interface CollectionCriteriaReset { filter?: string; sort?: string; query?: string }
 type Reducer = (s: State, ...args: unknown[]) => State | undefined | Promise<State | undefined>;
 const object = (x: unknown): State => x && typeof x === 'object' && !Array.isArray(x) ? x as State : {};
 const str = (arg: unknown, key: string): string => typeof arg === 'string' ? arg : String(object(arg)[key] ?? '');
@@ -262,6 +266,16 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     if (backend && config.backendQuery && criteriaBefore !== criteriaKey()) return backend.controller.query(criteria()).then(() => undefined);
     return derive(s);
   };
+  /** Filter and sort in ONE criteria change, so a tab that sets both runs one query, not two. */
+  const setCriteria = (arg: unknown): void => {
+    const input = object(arg);
+    const sort = String(input.sort ?? '');
+    if (sort === 'default' || sort === 'az' || sort === 'za') prefs.sort = sort;
+    const filter = String(input.filter ?? '');
+    if (filter === 'all' || (filter.startsWith('value:') && (config.filterValues ?? []).includes(filter.slice(6)))) prefs.filter = filter;
+    // A screen with no search field clears a query an older screen persisted, or it narrows every view for good.
+    if (typeof input.query === 'string') prefs.query = input.query.slice(0, 256);
+  };
   const criteria = () => ({ query: prefs.query, sort: prefs.sort, filter: prefs.filter, savedIds: prefs.filter === 'saved' ? prefs.savedIds : [] });
   const criteriaKey = () => JSON.stringify(criteria());
   actions.collectionDismissFilters = change(() => { filtersPresented = false; });
@@ -273,6 +287,7 @@ export function decorateCollection(name: string, def: { state: State; actions?:
   actions.collectionSort = change(arg => { const value = str(arg, 'selectedId'); if (value === 'default' || value === 'az' || value === 'za') prefs.sort = value; });
   actions.collectionFilter = change(arg => { const values = object(arg).selectedIds; prefs.filter = Array.isArray(values) && typeof values[0] === 'string' ? values[0] : 'all'; });
   actions.collectionSearch = change(arg => { prefs.query = str(arg, 'value').slice(0, 256); });
+  actions.collectionCriteria = change(arg => setCriteria(arg));
   actions.collectionViewName = change(arg => { viewName = str(arg, 'value').slice(0, 40); viewMessage = ''; });
   actions.collectionRememberView = change(() => {
     const name = viewName.trim();
@@ -305,7 +320,8 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     actions.collectionDataChanged = s => derive(backend.apply(s, backend.controller.getState()));
     actions.load = (_s, arg) => {
       stashCopy(arg); syncSaved(); applyNavigationCriteria(arg, _s);
-      backend.onLoad?.(arg);
+      const reset = backend.onLoad?.(arg);
+      if (reset) { setCriteria(reset); persisted.write(prefs); }
       // A load of what the screen already shows is the screen coming back: it revalidates behind its rows.
       return backend.controller.query(criteria(), backend.restorePagesOnLoad, true).then(() => undefined);
     };
@@ -334,11 +350,13 @@ export function defineBackendCollection<S extends object, Row extends object>(na
   register?: typeof register;
   /** Explicit mutation preflight; unrelated collection services keep their current reducers. */
   onlineWrites?: boolean;
+  /** Where the offline refusal is written (default `actionMessage`) — the field the screen shows next to the action. */
+  onlineWriteMessageFields?: readonly string[];
   /** Revalidate already opened pages on navigation return; explicit refresh resets. */
   restorePagesOnLoad?: boolean;
   /** The load action's argument (onAppear params beyond `copy`), before the query runs — for a
    *  domain setting that rides the descriptor, e.g. My Bookings' `weeklyGoal`. */
-  onLoad?(arg: unknown): void;
+  onLoad?(arg: unknown): CollectionCriteriaReset | void;
   state: S;
   source: CollectionQuerySource<Row>;
   apply(state: S, page: CollectionQueryState<Row>): S;
@@ -353,7 +371,7 @@ export function defineBackendCollection<S extends object, Row extends object>(na
     controller: controller as unknown as BackendCollection['controller'],
     apply: (state, page) => options.apply(state as S, page as unknown as CollectionQueryState<Row>) as State,
   });
-  const registerService = options.onlineWrites ? withOnlineWrites(options.register ?? register, ['confirmCancel', 'confirmOperation', 'retryOperation', 'commitWrite'], { messageFields: ['actionMessage'] }) : (options.register ?? register);
+  const registerService = options.onlineWrites ? withOnlineWrites(options.register ?? register, ['confirmCancel', 'confirmOperation', 'retryOperation', 'commitWrite'], { messageFields: options.onlineWriteMessageFields ?? ['actionMessage'] }) : (options.register ?? register);
   const handle = registerService(name, definition);
   // Registration restored the state a cold boot saved: the page it showed is this run's, before the first load. Only
   // when the service's own rows came back with it: a bundle that keeps them out of the restore (its `notHydrated`)

package/templates/gym-fitness/tier5-src/_shared/engine-intl.ts

@@ -108,6 +108,24 @@ export function formatMonthDayLong(date: Date, locale = "en-US", timeZone?: stri
   return `${MONTHS_LONG[date.getMonth()]} ${date.getDate()}`;
 }
 
+const WEEKDAYS_LONG = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"] as const;
+
+/** `{ weekday: "short", month: "short", day: "numeric" }` — "Mon, Jan 5". */
+export function formatWeekdayMonthDay(date: Date, locale = "en-US", timeZone?: string): string {
+  if (hasIntl()) {
+    return dateFormat(locale, { weekday: "short", month: "short", day: "numeric" }, timeZone).format(date);
+  }
+  return `${WEEKDAYS_SHORT[date.getDay()]}, ${MONTHS_SHORT[date.getMonth()]} ${date.getDate()}`;
+}
+
+/** `{ weekday: "long", month: "long", day: "numeric" }` — "Monday, January 5". */
+export function formatWeekdayMonthDayLong(date: Date, locale = "en-US", timeZone?: string): string {
+  if (hasIntl()) {
+    return dateFormat(locale, { weekday: "long", month: "long", day: "numeric" }, timeZone).format(date);
+  }
+  return `${WEEKDAYS_LONG[date.getDay()]}, ${MONTHS_LONG[date.getMonth()]} ${date.getDate()}`;
+}
+
 /** `{ weekday: "short", month: "short", day: "numeric", hour: "numeric", minute: "2-digit" }`
  *  — "Mon, Jan 5, 3:07 PM". */
 export function formatWeekdayDateTime(date: Date, locale = "en-US", timeZone?: string): string {

package/templates/gym-fitness/tier5-src/_shared/himi-restaurants.ts

@@ -133,15 +133,18 @@ export function itemLabels(value: unknown, limit = 3): string[] {
 }
 
 /** Price-variant rows ({ name, priceLine }) from the item's loose
- *  `priceVariants.variants` payload — [] when the item has a single price. */
-export function itemPriceVariants(item: WixItem): Array<{ id: string; name: string; priceLine: string }> {
+ *  `priceVariants.variants` payload — [] when the item has a single price.
+ *  `variantId` is Wix's own id for the variant (live rows carry `variantId`; older
+ *  fixtures `id`), "" when the payload has none — a synthetic `variant-<n>` row id is
+ *  only for the UI and must never be sent to Wix. `price` is the decimal price. */
+export function itemPriceVariants(item: WixItem): Array<{ id: string; variantId: string; name: string; priceLine: string; price: string }> {
   const raw = item as unknown as { priceVariants?: { variants?: unknown[] } };
   const variants = raw.priceVariants?.variants;
   if (!Array.isArray(variants)) return [];
-  const rows: Array<{ id: string; name: string; priceLine: string }> = [];
+  const rows: Array<{ id: string; variantId: string; name: string; priceLine: string; price: string }> = [];
   for (const [index, entry] of variants.entries()) {
     if (!entry || typeof entry !== "object") continue;
-    const node = entry as { id?: unknown; name?: unknown; priceInfo?: { price?: unknown; currency?: unknown } };
+    const node = entry as { id?: unknown; variantId?: unknown; name?: unknown; priceInfo?: { price?: unknown; currency?: unknown; formattedPrice?: unknown } };
     const name = typeof node.name === "string" ? cleanTitle(node.name) : "";
     const price = node.priceInfo?.price;
     if (price == null || price === "" || Number.isNaN(Number(price))) continue;
@@ -152,7 +155,11 @@ export function itemPriceVariants(item: WixItem): Array<{ id: string; name: stri
         priceLine = formatCurrency(Number(price), currency, "en");
       } catch { /* keep the bare amount */ }
     }
-    rows.push({ id: typeof node.id === "string" && node.id ? node.id : `variant-${index}`, name: name || "Option", priceLine });
+    const formatted = typeof node.priceInfo?.formattedPrice === "string" ? node.priceInfo.formattedPrice.trim() : "";
+    if (formatted) priceLine = normalizeFormattedPrice(formatted);
+    const variantId = typeof node.variantId === "string" && node.variantId ? node.variantId
+      : typeof node.id === "string" && node.id ? node.id : "";
+    rows.push({ id: variantId || `variant-${index}`, variantId, name: name || "Option", priceLine, price: `${price}` });
   }
   return rows;
 }

package/templates/gym-fitness/tier5-src/_shared/member-bookings.ts

@@ -6,27 +6,69 @@ import { copyParam } from "./himi-copy.js";
 import { formatWeekdayDateTime } from "./engine-intl.js";
 import { dayKey } from "@himalaya/time";
 
+/** The statuses that put a booking in the Canceled tab. Upcoming and Past exclude them, so each
+ *  booking is in exactly one tab. */
+export const CANCELLED_STATUSES = ["CANCELED", "CANCELLED", "DECLINED"];
+
 export interface MemberBookingRow {
   id: string; title: string; subtitle: string; status: string; revision: string;
   start: string; end: string; day: string; serviceId: string;
   canCancel: boolean; cannotCancel: boolean; cannotRebook: boolean;
+  // Added for the My Bookings redesign. Each is "" / 0 / false when the record has nothing for it.
+  /** The staff member (the slot's resource), "" when the booking names none. */
+  staff: string;
+  /** The location's name, else its address. */
+  placeName: string;
+  /** The location's formatted address. */
+  placeAddress: string;
+  /** `BUSINESS`, `CUSTOM` or `CUSTOMER` (the client's place), upper case. */
+  placeType: string;
+  participants: number;
+  /** Wix's raw payment status, upper case (`PAID`, `NOT_PAID`, …). */
+  paymentStatus: string;
+  /** Wix's raw booking status, upper case (`CONFIRMED`, `WAITING_LIST`, …). */
+  statusKey: string;
+  /** A course booking: it books a schedule, not a slot. */
+  isCourse: boolean;
+  courseStart: string;
+  courseEnd: string;
 }
 export function bookingStart(booking: WixBooking): string {
   // Top-level instants are UTC. Slot dates may be LOCAL to slot.timezone.
   const value = booking.startDate || booking.bookedEntity?.slot?.startDate || "";
   return /(?:Z|[+-]\d{2}:?\d{2})$/i.test(value) && Number.isFinite(Date.parse(value)) ? value : "";
 }
+const instant = (value: unknown): string =>
+  typeof value === "string" && /(?:Z|[+-]\d{2}:?\d{2})$/i.test(value) && Number.isFinite(Date.parse(value)) ? value : "";
+const word = (value: unknown): string => typeof value === "string" ? value.trim() : "";
 export function memberBookingRow(booking: WixBooking): MemberBookingRow {
   const start = bookingStart(booking);
   const entity = booking.bookedEntity;
+  const slot = entity?.slot, schedule = entity?.schedule;
   const status = (booking.status || "").toUpperCase();
   const revision = String((booking as WixBooking & { revision?: string | number }).revision ?? "");
-  const serviceId = entity?.slot?.serviceId || "";
-  const canCancel = !!booking.id && !!revision && Date.parse(start) > Date.now() && !["CANCELED", "CANCELLED", "DECLINED"].includes(status);
+  // A course booking carries a schedule, not a slot: its service id is on the schedule.
+  const serviceId = slot?.serviceId || schedule?.serviceId || "";
+  const canCancel = !!booking.id && !!revision && Date.parse(start) > Date.now() && !CANCELLED_STATUSES.includes(status);
+  const location = slot?.location ?? schedule?.location;
+  const placeAddress = word(location?.formattedAddress);
+  const participants = Number(booking.totalParticipants);
   return { id: booking.id, title: entity?.title || copyParam("bookings.booking", "Booking"),
     subtitle: start ? formatWeekdayDateTime(new Date(start)) : copyParam("bookings.timeUnavailable", "Time unavailable"),
-    status: status.replace(/_/g, " "), revision, start, end: booking.endDate || "", day: start ? dayKey(new Date(start)) : "",
-    serviceId, canCancel, cannotCancel: !canCancel, cannotRebook: !serviceId };
+    status: status.replace(/_/g, " "), revision, start,
+    // Wix may carry the end only on the slot (same instant rule as the start).
+    end: booking.endDate || instant(slot?.endDate), day: start ? dayKey(new Date(start)) : "",
+    serviceId, canCancel, cannotCancel: !canCancel, cannotRebook: !serviceId,
+    staff: word(slot?.resource?.name),
+    placeName: word(location?.name) || placeAddress,
+    placeAddress,
+    placeType: word(location?.locationType).toUpperCase(),
+    participants: Number.isFinite(participants) && participants > 0 ? Math.floor(participants) : 0,
+    paymentStatus: word(booking.paymentStatus).toUpperCase(),
+    statusKey: status,
+    isCourse: !slot && !!schedule,
+    courseStart: instant(schedule?.firstSessionStart),
+    courseEnd: instant(schedule?.lastSessionEnd) };
 }
 export async function fetchMemberBookings(criteria: CollectionQuery, cursor: string, now: string, expected?: MemberAccess) {
   const member = expected ?? await memberAccess();
@@ -37,9 +79,10 @@ export async function fetchMemberBookings(criteria: CollectionQuery, cursor: str
   const filter: Record<string, unknown> = { "contactDetails.email": { $eq: member.email } };
   if (criteria.query) filter.id = { $eq: criteria.query };
   if (criteria.filter === "saved") filter.id = criteria.query ? { $in: criteria.savedIds.filter(id => id === criteria.query) } : { $in: criteria.savedIds };
-  if (criteria.filter === "value:Upcoming") { filter.startDate = { $gte: now }; filter.status = { $nin: ["CANCELED", "CANCELLED", "DECLINED"] }; }
-  if (criteria.filter === "value:Past") filter.startDate = { $lt: now };
-  if (criteria.filter === "value:Cancelled") filter.status = { $in: ["CANCELED", "CANCELLED"] };
+  if (criteria.filter === "value:Upcoming") { filter.startDate = { $gte: now }; filter.status = { $nin: CANCELLED_STATUSES }; }
+  // Past is what took place: a canceled or declined booking is in the Canceled tab only.
+  if (criteria.filter === "value:Past") { filter.startDate = { $lt: now }; filter.status = { $nin: CANCELLED_STATUSES }; }
+  if (criteria.filter === "value:Cancelled") filter.status = { $in: CANCELLED_STATUSES };
   const response = await queryBookings({ query: { filter, paging: { limit: 50, offset: Number(cursor || 0) },
     sort: [{ fieldName: "startDate", order: criteria.sort === "za" ? "DESC" : "ASC" }, { fieldName: "id", order: "ASC" }] } });
   await assertMemberAccess(member);

package/templates/gym-fitness/tier5-src/_shared/restaurant-ordering.ts

@@ -0,0 +1,201 @@
+// Restaurants online ordering — Wix's visitor "Place an order from a custom storefront" flow,
+// shared by the dish detail (himi-branded-lite-menu-item: add a dish to the Wix cart) and the
+// order screen (wix-spaces-food-orders: cart → pickup/delivery → hosted checkout → history).
+//
+// The cart is the site's eCom CURRENT cart (Cart V2). It is the same cart the Stores cart screen
+// reads (V1 and V2 answer the same cart id), so a restaurant line is told apart by its catalog
+// app — Restaurants Orders — never assumed. Every call here is visitor-scope; the member's placed
+// orders are read through the eCom orders search the member Orders screen already uses, never
+// through the owner-capable Restaurants Orders API.
+import {
+  getFirstAvailableTimeSlotPerFulfillmentType,
+  listFulfillmentMethods,
+  listOperations,
+  queryMenus,
+  querySections,
+  type WixFulfillmentMethod,
+  type WixFulfillmentTimeSlot,
+  type WixMenu,
+  type WixOperation,
+  type WixRestaurantsAddress,
+  type WixSection,
+} from "@himalaya/wix-restaurants";
+import type { WixCartV2, WixCartV2LineItem, WixCatalogReference } from "@himalaya/wix-ecom";
+import { formatCurrency } from "../_shared/engine-intl.js";
+
+/** Wix Restaurants Orders — the catalog app a restaurant cart line belongs to. */
+export const RESTAURANTS_ORDERS_APP_ID = "9a5d83fd-8570-482e-81ab-cfa88942ee60";
+
+export type FulfillmentType = "PICKUP" | "DELIVERY";
+
+/** The operation a visitor orders from: an `ENABLED` one, the site's default first. None means
+ *  online ordering is closed (`DISABLED`, `PAUSED_UNTIL`, or no operation at all). */
+export function orderingOperation(operations: WixOperation[] | undefined, selection: { businessLocationId?: string; operationId?: string } = {}): WixOperation | undefined {
+  const open = (operations ?? []).filter((operation) => !!operation?.id && operation.onlineOrderingStatus === "ENABLED");
+  if (selection.operationId) return open.find((operation) => operation.id === selection.operationId);
+  if (selection.businessLocationId) return open.find((operation) => operation.businessLocationId === selection.businessLocationId);
+  return open.find((operation) => operation.default === true) ?? open[0];
+}
+
+export async function loadOrderingOperation(selection: { businessLocationId?: string; operationId?: string } = {}): Promise<WixOperation | undefined> {
+  return orderingOperation((await listOperations()).operations, selection);
+}
+
+/** The enabled pickup/delivery methods [operation] offers: the ones its `fulfillmentIds` name. An
+ *  operation that names none falls back only to methods at its own business location — never to
+ *  every method on the site, which on a multi-location site would offer another location's pickup. */
+export function offeredMethods(operation: WixOperation, methods: WixFulfillmentMethod[] | undefined): WixFulfillmentMethod[] {
+  const ids = new Set(operation.fulfillmentIds ?? []);
+  const belongs = (method: WixFulfillmentMethod) => ids.size > 0
+    ? ids.has(method.id)
+    : !!operation.businessLocationId && method.businessLocationId === operation.businessLocationId;
+  return (methods ?? []).filter((method) =>
+    !!method?.id && method.enabled === true && (method.type === "PICKUP" || method.type === "DELIVERY") && belongs(method));
+}
+
+export async function loadOfferedMethods(operation: WixOperation): Promise<WixFulfillmentMethod[]> {
+  const all: WixFulfillmentMethod[] = [];
+  let cursor = "";
+  // A site has a handful of methods; five pages of 100 is a bound, not an expectation.
+  for (let page = 0; page < 5; page++) {
+    const response = await listFulfillmentMethods({ limit: 100, ...(cursor ? { cursor } : {}) });
+    all.push(...(response.fulfillmentMethods ?? []));
+    cursor = response.pagingMetadata?.hasNext ? response.pagingMetadata.cursors?.next ?? "" : "";
+    if (!cursor) break;
+  }
+  return offeredMethods(operation, all);
+}
+
+/** A decimal string from Wix ("6.99", "0") as a number; anything else is 0 (a missing fee is free). */
+export function decimal(value: unknown): number {
+  const n = typeof value === "number" ? value : Number(typeof value === "string" ? value.trim() : NaN);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** Cart V2 money carries no formatted string: format the decimal with the cart's currency. */
+export function money(amount: unknown, currency: string | undefined): string {
+  return formatCurrency(decimal(amount), (currency ?? "").trim() || "USD", "en");
+}
+
+export function cartCurrency(cart: WixCartV2 | undefined): string {
+  return cart?.businessInfo?.currencyCode || cart?.customerInfo?.currencyCode || "";
+}
+
+/** Where a dish is ordered from. Checkout validates the line against `menuSectionId`, so it must
+ *  be a visible section that lists the dish, inside a visible menu that lists the section. */
+export interface DishPlacement {
+  menuId: string;
+  sectionId: string;
+  businessLocationId?: string;
+}
+
+/** The section the dish was shown under wins when it qualifies; otherwise the first visible
+ *  menu → section that lists it. None → the dish is on no orderable menu. */
+export function pickPlacement(
+  dishId: string,
+  menus: WixMenu[],
+  sections: WixSection[],
+  hint: { menuId?: string; sectionId?: string } = {},
+): DishPlacement | undefined {
+  const listing = new Map(sections
+    .filter((section) => !!section?.id && section.visible !== false && (section.itemIds ?? []).includes(dishId))
+    .map((section) => [section.id, section]));
+  const candidates: DishPlacement[] = [];
+  for (const menu of menus) {
+    if (!menu?.id || menu.visible === false) continue;
+    for (const sectionId of menu.sectionIds ?? []) {
+      if (listing.has(sectionId)) candidates.push({ menuId: menu.id, sectionId, businessLocationId: menu.businessLocationId });
+    }
+  }
+  return candidates.find((c) => c.sectionId === hint.sectionId && (!hint.menuId || c.menuId === hint.menuId)) ?? candidates[0];
+}
+
+export async function loadDishPlacement(dishId: string, hint: { menuId?: string; sectionId?: string }): Promise<DishPlacement | undefined> {
+  const [sections, menus] = await Promise.all([
+    querySections({ paging: { limit: 100 } }),
+    queryMenus({ paging: { limit: 50 } }),
+  ]);
+  return pickPlacement(dishId, menus.menus ?? [], sections.sections ?? [], hint);
+}
+
+/** The catalog reference for one dish line. There is no `variantId` key in `options`. */
+export function dishReference(dishId: string, operationId: string, placement: DishPlacement): WixCatalogReference {
+  return {
+    appId: RESTAURANTS_ORDERS_APP_ID,
+    catalogItemId: dishId,
+    options: {
+      operationId,
+      menuId: placement.menuId,
+      menuSectionId: placement.sectionId,
+      sectionId: placement.sectionId,
+    },
+  };
+}
+
+export function isRestaurantLine(line: WixCartV2LineItem | undefined): boolean {
+  return line?.source?.catalogReference?.appId === RESTAURANTS_ORDERS_APP_ID;
+}
+
+function lineVariantId(line: WixCartV2LineItem): string {
+  const variant = (line.source?.catalogReference?.options as { priceVariant?: { id?: unknown } } | undefined)?.priceVariant;
+  return typeof variant?.id === "string" ? variant.id : "";
+}
+
+/** The cart line Wix kept for [reference] — same dish, operation, menu, section and variant — or
+ *  undefined when Wix dropped it. Wix can refuse an item and still answer 200, so the returned cart
+ *  is the proof. The operation and menu matter: the same dish added from two restaurant locations
+ *  is two lines, and only the one just added proves this add. */
+export function addedLine(cart: WixCartV2 | undefined, reference: WixCatalogReference): WixCartV2LineItem | undefined {
+  type PlacementOptions = { operationId?: unknown; menuId?: unknown; menuSectionId?: unknown };
+  const options = (reference.options ?? {}) as PlacementOptions & { priceVariant?: { id?: unknown } };
+  const variantId = typeof options.priceVariant?.id === "string" ? options.priceVariant.id : "";
+  return (cart?.lineItems ?? []).find((line) => {
+    const ref = line.source?.catalogReference;
+    if (!ref || ref.appId !== reference.appId || ref.catalogItemId !== reference.catalogItemId) return false;
+    const lineOptions = (ref.options ?? {}) as PlacementOptions;
+    if (lineOptions.operationId !== options.operationId || lineOptions.menuId !== options.menuId) return false;
+    if (lineOptions.menuSectionId !== options.menuSectionId) return false;
+    if (lineVariantId(line) !== variantId) return false;
+    if (line.status === "OUT_OF_STOCK" || line.status === "REMOVED_FROM_CATALOG") return false;
+    const confirmed = line.quantityInfo?.confirmedQuantity;
+    return confirmed === undefined || confirmed > 0;
+  });
+}
+
+export function lineQuantity(line: WixCartV2LineItem): number {
+  const q = line.quantityInfo?.confirmedQuantity ?? line.quantityInfo?.requestedQuantity ?? 1;
+  return Number.isFinite(q) && q >= 0 ? Math.floor(q) : 0;
+}
+
+/** How many dishes the cart holds (restaurant lines only). */
+export function restaurantItemCount(cart: WixCartV2 | undefined): number {
+  return (cart?.lineItems ?? []).filter(isRestaurantLine).reduce((total, line) => total + lineQuantity(line), 0);
+}
+
+export function slotFor(slots: WixFulfillmentTimeSlot[] | undefined, type: FulfillmentType): WixFulfillmentTimeSlot | undefined {
+  return (slots ?? []).find((slot) => slot?.fulfilmentType === type);
+}
+
+/** The `deliveryMethod.code` for [type]: `<TYPE>|ASAP`, or the slot's own window for a pre-order.
+ *  An ASAP slot must be sent as ASAP — its start/end window is refused as `DELIVERY_METHOD_NOT_FOUND`. */
+export function deliveryCode(type: FulfillmentType, slot?: WixFulfillmentTimeSlot): string {
+  const window = slot?.timeSlot;
+  if (window?.orderSchedulingType === "PREORDER") {
+    const start = Date.parse(window.startTime ?? ""), end = Date.parse(window.endTime ?? "");
+    if (Number.isFinite(start) && Number.isFinite(end)) return `${type}|${start}|${end}`;
+  }
+  return `${type}|ASAP`;
+}
+
+export async function firstSlots(operationId: string, deliveryAddress?: WixRestaurantsAddress): Promise<WixFulfillmentTimeSlot[]> {
+  return (await getFirstAvailableTimeSlotPerFulfillmentType(operationId, deliveryAddress)).timeslotsPerFulfillmentType ?? [];
+}
+
+/** The pickup address the cart needs before a pickup method can be set: the restaurant's own
+ *  country (and region when Wix gives one) — Wix requires an address even for pickup. */
+export function pickupCartAddress(method: WixFulfillmentMethod | undefined, fallbackCountry = ""): WixRestaurantsAddress | undefined {
+  const address = method?.pickupOptions?.address;
+  const country = (address?.country || fallbackCountry).trim();
+  if (!country) return undefined;
+  return { country, ...(address?.subdivision ? { subdivision: address.subdivision } : {}) };
+}