Subchapter 16.685

INSTRUCTIONS

restaurants/INSTRUCTIONS.mdMarkdown37 KBView on GitHub

Restaurants — playbook

The restaurant machinery ships as files — the assembled menu tree (menus → sections → items with variants, modifiers, labels, every price formatted in the site’s currency), the modifier rule engine and the dish-ordering cart on the eCom current cart with the exact restaurant catalogReference (context ids AND the visitor’s choices), the hosted checkout, and the table-reservation flow (hold → reserve, or a request when the restaurant approves by hand) driven by the location’s own form configuration, typed end-to-end. : you design and implement the dish card, the dish sheet, the menu surface, the order-cart chrome, and the reservations surface on the shipped hooks/DTOs, plus the home page and the brand. You never write ordering or reservation logic; you never skip designing.

INSTRUCTIONS · Wix Headless Templates · wix/skills · Skills Docs

file	what it is
`wix/config.ts` · `wix/sdk.ts`	shared auth seam (deploy configures it — nothing to set by hand)
`wix/media.ts` · `wix/money.ts`	`imgAttrs(url, sizes)` — every `<img>` attribute for a DTO image (`src`, `srcSet`, `sizes`, lazy): `<img {...imgAttrs(item.imageUrl, "6rem")} alt={item.name} />`; `imgSrc()` / `imgSrcSet()` / `formatMoney()` underneath, already used by everything shipped
`wix/restaurants/types.ts`	the DTOs (`MenuData`, `MenuSection`, `MenuItem`, `OrderSelection`, `OrderCart`, `OrderingStatus`, `ReservationLocationInfo`, `ReservationSlot`, …) — contracts below
`wix/restaurants/menu.ts`	`fetchMenus` — the whole display-ordered menu tree, every price formatted with the site’s currency + locale (read once from the eCommerce settings, `fetchSiteMoney`); the transport only — the id-array stitching, the item mapping, the money formatting, and the modifier rule engine (`initialSelection`, `toggleModifier`, `validateSelection`, `itemPrice`, `needsSelection`, `ruleLabel`) are in `menu-core.ts` beside it (shared with the REST layer)
`wix/restaurants/ordering.ts` · `order-store.ts`	the operation’s state (`resolveOrdering`), each menu’s ordering settings under it (`fetchMenuOrdering`), the operation’s fulfillment methods and times, dish add-to-cart (Orders-app `catalogReference` with the selection) + eCom Cart V2, the order’s pickup/delivery + time (the cart’s delivery method) + the hosted checkout, and the shared cart state (module store — spans Astro islands); the request shapes, the availability-window check, and the refusal checks are in `ordering-core.ts`
`wix/restaurants/reservations.ts`	locations (enabled for online reservations, with name/address/timezone/approval/form config), AVAILABLE slots in the location’s timezone, `holdReservation` → `completeReservation` (automatic approval), `requestReservation` (manual approval, no hold); the mappers, the form validation, and the reservee body are in `reservations-core.ts`
`wix/restaurants/time-core.ts`	wall-clock arithmetic in an IANA zone with `Intl` only (`zonedIso`, `zonedDayKey`, `zonedTimeLabel`, `zonedDateTimeLabel`) — what the two cores and the stores use for the restaurant’s timezone
`wix/restaurants/menu-store.ts` · `reservation-store.ts`	the menu-browsing and reservation state machines, framework-free (`createMenuStore()`, `createReservationStore()` — `getState`/`subscribe` + actions, one instance per surface); the hooks below bind them to React, every other stack uses them directly
`hooks/restaurants/useMenus.ts`	React binding of `menu-store.ts`: menu browsing + menu switching — contract below
`hooks/restaurants/useOrderCart.ts`	React binding of `order-store.ts`: order-cart state, the ordering gates, and actions — contract below
`hooks/restaurants/useReservation.ts`	React binding of `reservation-store.ts`: the whole reservation state machine — contract below
`components/restaurants/MenuView.tsx` (+ `MenuItemCard`, `MenuItemSheet`) · `OrderCartButton.tsx` · `OrderCartDrawer.tsx` · `ReservationView.tsx`	reference implementations — tested, plain, on the tokens; the layout mounts the cart chrome as shipped, and you replace all four with your own designs (new file names)
`styles/global.css`	the design system: Tailwind v4 + the `@theme` token block (colors, radii, fonts — shared across verticals). Everything, shipped and yours, styles from these tokens

file	what it is
`layouts/SiteLayout.astro`	site chrome — yours to brand (keep the `seo-tags` slot, the global.css import, and one `OrderCartButton` + one `OrderCartDrawer`, both `client:only`). If another vertical is also deployed, its layout won — merge the Menu/Reservations links + cart mounts there
`pages/menu.astro`	SSR menu — keep the frontmatter, swap the island import to YOUR component
`pages/reservations.astro`	reservations — the island stays `client:only="react"` (availability is time-specific); swap the import to YOUR component

Menu: dish names in view-source (the page fetches server-side and passes initialMenus); sections in the menu’s own order; a dish card shows name, description, price (or its variants, or “Market price”), labels, and the add control; skeletons while menus === null, an honest empty state for []. Prices render as given — they are already formatted in the site’s currency ("" only when the site’s currency couldn’t be read; then render nothing, never a guessed symbol).
Add control: its states come from the data — hidden for a market-priced dish and for a menu whose menuOrderable(menuId) === false (not enabled for online ordering, or outside its hours — say so once at the menu level); “Sold out” (item.soldOut: the dish, or a required group with nothing in stock); the operation’s reason when ordering === false (“Ordering unavailable”, or “paused” with orderingStatus.pausedUntilIso rendered in orderingStatus.timeZone); else “Add to order”. A dish with needsSelection(item) opens your sheet; a plain dish adds at once. Adding opens the cart drawer on its own; the header badge is the live itemCount.
Dish sheet: open on initialSelection(item) (pre-selected in-stock modifiers, the cheapest variant); every change through toggleModifier; the CTA shows itemPrice(item, selection, quantity, menu.money).formatted; on submit validateSelection → per-group messages beside the group, then addToOrder(item, { menuId, sectionId }, quantity, selection); out-of-stock modifiers disabled.
Cart: lines with quantity stepper and remove, descriptionLines under the name, subtotal as given, checkout as a button in the drawer; the order survives a reload (same visitor token) — nothing to wire. Pickup/delivery and the time are chosen in the drawer, before checkout: a Pickup/Delivery switch when fulfillment has both types, a time select from fulfillmentTimes of that type (ASAP first, labelled in orderingStatus.timeZone), and for delivery street, city and postal code (country and subdivision default to the restaurant’s; on blur the drawer reloads the times with that address, so delivery times are only those of methods that deliver there) with the delivery fee and minimum; the CTA calls chooseFulfillment(choice) then checkout().
Reservations: only AVAILABLE times offered, labelled in the restaurant’s timezone; the query date defaults to today at the restaurant; approval === "AUTOMATIC" → hold → details form with the holdSecondsLeft countdown → confirm; approval === "MANUAL" (or slot.manualApproval) → pick → details form → request, no hold; confirmed.outcome “confirmed” reads as confirmed, “pending” as “pending the restaurant’s approval”; the toggle-off and not-set-up cases read as “call us to book”, never as a broken form. A location picker only when locations.length > 1 (each has name, address).
Overlays you build (cart drawer, dish sheet as a modal, mobile nav): mount at the document root, lock background scroll, close on Escape, return focus on close — as the shipped OrderCartDrawer does.
Copy: nothing the restaurant didn’t supply — no invented hours, reviews, or delivery promises; no Wix IDs or technical words in visible text.

// MenuData → sections → items, all display-ordered. EVERY money value is a formatted string in the
// site's currency + locale ("" when the currency couldn't be read); the decimal rides in *Amount.
// MenuData = { id, name, description, slug, sections, money: { currency, locale } }
// MenuItem = { id, name, description,
//   price /* formatted; null when variant- or market-priced */, priceAmount,
//   marketPrice /* true → "Market price", not orderable */,
//   variants: [{ variantId, name, price, priceAmount }],         // the cheapest is the default
//   imageUrl, gallery: string[], labels: [{ id, name, iconUrl }],
//   modifierGroups: [{ id, name, required, minSelections, maxSelections, rule, singleSelect,
//                      modifiers: [{ id, key /* `${id}~${index}` — the selection key */, name,
//                                    preSelected, additionalCharge /* "" when free */, additionalChargeAmount, inStock }] }],
//   inStock, soldOut /* !inStock or a required group with too few in-stock modifiers */,
//   orderable /* !marketPrice && !soldOut */, acceptsSpecialRequests, featured }
//
// The selection helpers (wix/restaurants/menu-core.ts) — the rule engine, framework-free:
//   OrderSelection = { variantId: string|null, modifiers: Record<groupId, key[]>, specialRequest }
//   initialSelection(item)                       → preSelected && inStock modifiers (first only when singleSelect), cheapest variant

// src/components/restaurants/YourMenu.tsx — YOU build it; pages/menu.astro mounts it with initialMenus.
import { useState } from "react";
import { useMenus } from "../../hooks/restaurants/useMenus";
import { useOrderCart } from "../../hooks/restaurants/useOrderCart";
import { imgAttrs } from "../../wix/media";
import { initialSelection, itemPrice, needsSelection, ruleLabel, toggleModifier, validateSelection } from "../../wix/restaurants/menu-core";
import type { MenuData, MenuItem, OrderSelection } from "../../wix/restaurants/types";

export default function YourMenu({ initialMenus }: { initialMenus?: MenuData[] }) {
  const { menus, activeMenuId, setActiveMenuId, activeMenu, error } = useMenus({ initialMenus });
  const { addToOrder, ordering, orderingStatus, menuOrderable, pendingItemId } = useOrderCart();
  // …you implement the render:
  //   • menus === null → skeletons; [] → your empty state (error when set)
  //   • menu tabs when menus.length > 1 (setActiveMenuId); a section nav when activeMenu.sections.length > 1;
  //     one notice when menuOrderable(activeMenu.id) === false ("not available for online ordering right now")
  //   • per section, YOUR dish card: <img {...imgAttrs(item.imageUrl, "6rem")} alt={item.name} /> when
  //     item.imageUrl, name, description, item.marketPrice ? "Market price" : item.price ?? variants, labels
  //   • the add control: hidden for item.marketPrice or menuOrderable(menuId) === false; "Sold out" when
  //     item.soldOut; the operation's reason when ordering === false; else "Add to order" — which, when
  //     needsSelection(item), opens YOUR sheet (below) and otherwise calls
  //     addToOrder(item, { menuId: activeMenu.id, sectionId: section.id }) — the ids of the menu and section
  //     the card is rendered under, never looked up again; the rejection message rendered beside it;
  //     disabled (and reading "Adding…") only while pendingItemId === item.id — never on the cart's busy,
  //     which is the drawer's flag and would dim every dish in the grid for every add
  //   • YOUR sheet: const [sel, setSel] = useState<OrderSelection>(() => initialSelection(item)); variant radios
  //     (sel.variantId), per group a fieldset titled `${g.name} · ${ruleLabel(g)}` with radios when g.singleSelect
  //     else checkboxes, keyed by m.key, onChange → setSel(toggleModifier(item, sel, g.id, m.key)), disabled when
  //     !m.inStock, m.additionalCharge beside it; a textarea when item.acceptsSpecialRequests → sel.specialRequest;
  //     a quantity stepper; the CTA reads itemPrice(item, sel, qty, activeMenu.money).formatted; on submit
  //     validateSelection(item, sel) → errors per group, else addToOrder(item, ctx, qty, sel)
}

// src/components/restaurants/YourReservations.tsx — YOU build it; pages/reservations.astro mounts it client:only.
import { useReservation } from "../../hooks/restaurants/useReservation";

export default function YourReservations() {
  const r = useReservation();   // full contract above — the flow lives HERE
  // …you implement the render, in this order:
  //   r.locations === null → loading; [] or !r.location → "call us to book";
  //   !r.location.onlineReservationsEnabled → "online reservations aren't open yet";
  //   r.confirmed → outcome "confirmed" as confirmed (r.location.form.submitMessage when set), "pending" as
  //   pending approval, "other" as not completed; r.reset() to start over;
  //   else: a location picker only when locations.length > 1 (name, address); guests (bounded by
  //   partySizeMin/Max), date, time → r.findSlots(); a note when r.approval === "MANUAL"; r.slots as pills →
  //   r.holdSlot(slot); r.selectedSlot → the details form: first name + phone always, last name / email with
  //   an asterisk when r.location.form.lastNameRequired / emailRequired, one input per
  //   r.location.form.customFields (r.setCustomField), the marketing checkbox when form.marketingCheckbox
  //   (r.setMarketingConsent), terms/privacy links when form.terms / form.privacy; the countdown from
  //   r.holdSecondsLeft when r.held; r.fieldErrors beside the fields; the CTA gated by r.canConfirm reading
  //   "Complete reservation" (held) or "Request reservation" (manual); r.error inline
}

Data and ordering logic only through the shipped exports — useOrderCart/addToOrder own the restaurant catalogReference (the Orders app id + operationId/menuId/menuSectionId — all three — plus the visitor’s choices as options.priceVariant, options.modifierGroups, options.specialRequests), the line-refusal checks, and the checkout redirect. Never re-derive any of it, never hand-build a checkout URL; extend by adding a function in wix/restaurants/ for what they don’t cover (API contracts: the wix-docs skill).
Thread item + menuId + sectionId from the render context — each dish is rendered inside a known section of a known menu (the fetchMenus tree); pass the item DTO and those ids to addToOrder. Never look them up again.
Selections go through the rule engine — a dish with variants, modifier groups, or a note gets a sheet: initialSelection → toggleModifier → validateSelection → addToOrder(item, ctx, quantity, selection). Never send a modifier id as a selection key (keys are MenuModifier.key), never invent an option shape, never compute a price outside itemPrice.
Money is already formatted — render price, additionalCharge, fee, subtotal as given; arithmetic uses the *Amount decimals; nothing prefixes a symbol, nothing assumes a currency.
Three gates before an add control shows “Add to order”: ordering === true (the operation), menuOrderable(menuId) !== false (the menu’s settings and hours), item.orderable (the dish). Each false state has its own copy; a market-priced dish has no control.
Reservations only through useReservation (or its store) — AVAILABLE-only slots in the restaurant’s timezone, the two approval paths (hold → reserve; request without a hold), the hold’s revision, the form rules from location.form, and the real status all live in the data layer. Render the form from location.form (don’t hardcode which fields exist or are required), gate the CTA on canConfirm, surface error and fieldErrors (holds expire in 10 minutes — the store counts down and restarts the flow).
The confirmed state must reflect REAL success: render it only from confirmed, and only outcome === "confirmed" as confirmed — “pending” (REQUESTED, PAYMENT_INFORMATION_PENDING) as “pending the restaurant’s approval”, “other” as not completed. A visitor returning from the hosted checkout is NOT an order-success signal.
Honest unavailability: ordering === false → the operation’s reason on the add button (orderingStatus.status, pausedUntilIso); menuOrderable(id) === false → no add controls and one notice for that menu; onlineReservationsEnabled === false → a “call us to book” notice (the toggle is premium-gated). Never mock menus, dishes, prices, slots, or availability.
Fulfillment is set on the cart before checkout — the hosted checkout has no pickup/delivery or time picker for restaurant orders and refuses one without them (“There was an issue updating your fulfillment details…”). Set it with chooseFulfillment (times from fulfillmentTimes, the address for delivery); checkout() falls back to pickup ASAP only when nothing was chosen, and says “Choose pickup or delivery” when the restaurant has no pickup. Never build the delivery method code yourself.
Don’t wrap shipped calls in your own API routes — they run client-side by design.
Cart totals come from cart — never summed or hardcoded in the client; fees, tax, and delivery are shown on the hosted checkout. The sheet’s itemPrice is a preview of one line, not a total.
Browsing, ordering and reserving need no login. They run on the visitor session the shipped client already holds; don’t add a members/auth flow unless the brief asks for accounts.
Call every hook before any conditional return. Hooks first, branches after.
Where the shipped components deploy (Astro, React): theme via the @theme tokens, and your markup uses Tailwind utilities on the same tokens — one design system across shipped and written code. No parallel theme files, no hardcoded palette values. Where they don’t (lib, static, a port): style with whatever your stack does well, on one token set of your own; the rule that survives is the token set, not Tailwind.

page	`https://manage.wix.com/dashboard/{siteId}/` +
Menus	`wix-restaurants-menus-new`
Edit a menu	`wix-restaurants-menus-new/menu/{menuId}`
Items	`wix-restaurants-menus-new/items`
Online orders board	`wix-restaurants-orders-new`
Ordering settings (pickup/delivery hours, fees, menu hours)	`wix-restaurants-orders-new/settings`
Reservations	`wix-table-reservations/table-reservations`
Floor plan	`wix-table-reservations/floor-plan`
Accept payments — connect a payment method	`wix-cashier/payments`
Upgrade the plan — online payments need premium	full URL: `https://www.wix.com/upgrade/website?metaSiteId={siteId}`

INSTRUCTIONS

Restaurants — playbook

INSTRUCTIONS

Restaurants — playbook

The file map (deployed into `src/`)

What you build — the design job

What a complete restaurant site shows (recommended defaults)

The contracts your components consume (tested and work as they are; read the source when something is off or the brief wants more)

The islands you create — skeletons

The reference files for stacks where the components don’t deploy

Wiring — Astro (default)

Wiring — another JS framework (`--stack lib`: Vue, Svelte, Solid, plain Vite)

Wiring — static site (`--stack static`, no bundler)

Wiring — server-rendered, another language (Flask, Laravel, Rails, …)

Wiring — React SPA (Vite etc.)

Hard rules

Point the user to their dashboard

Seeding