@wix/agent-skills 1.17.0 → 1.18.0

package/skills/wix-headless-fast/references/restaurants/app/components/restaurants/OrderCartButton.tsx

@@ -0,0 +1,26 @@
+// REFERENCE header order button with a live count badge — opens the OrderCartDrawer.
+// Correct and complete; per the skill's model you design your own chrome on useOrderCart.
+import { useOrderCart } from "../../hooks/restaurants/useOrderCart";
+
+export default function OrderCartButton() {
+  const { itemCount, openCart } = useOrderCart();
+  return (
+    <button
+      type="button"
+      aria-label={`Order, ${itemCount} items`}
+      onClick={openCart}
+      className="relative inline-flex items-center p-1.5 text-foreground transition-opacity hover:opacity-70"
+    >
+      <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.6">
+        <path d="M6 2L3 6v14a2 2 0 002 2h14a2 2 0 002-2V6l-3-4z" />
+        <line x1="3" y1="6" x2="21" y2="6" />
+        <path d="M16 10a4 4 0 01-8 0" />
+      </svg>
+      {itemCount > 0 && (
+        <span className="absolute -right-1 -top-1 flex h-[18px] min-w-[18px] items-center justify-center rounded-full bg-primary px-1 text-[10px] font-bold text-primary-foreground">
+          {itemCount}
+        </span>
+      )}
+    </button>
+  );
+}

package/skills/wix-headless-fast/references/restaurants/app/components/restaurants/OrderCartDrawer.tsx

@@ -0,0 +1,121 @@
+// REFERENCE slide-over order cart with quantity stepper, remove, live subtotal, and the
+// Wix-hosted checkout. Mount ONCE per page; opens via useOrderCart().openCart(). Correct and
+// complete; per the skill's model you design your own chrome on useOrderCart.
+import { useOrderCart } from "../../hooks/restaurants/useOrderCart";
+
+export default function OrderCartDrawer() {
+  const { cart, open, closeCart, busy, error, updateQuantity, removeLine, checkout } = useOrderCart();
+  if (!open) return null;
+  const lines = cart?.lines ?? [];
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex justify-end bg-foreground/40 backdrop-blur-[2px]"
+      onClick={closeCart}
+    >
+      <aside
+        role="dialog"
+        aria-label="Your order"
+        onClick={(e) => e.stopPropagation()}
+        className="flex h-full w-full max-w-md flex-col bg-background text-foreground shadow-2xl"
+      >
+        <div className="flex items-center justify-between border-b border-border px-6 py-5">
+          <span className="text-base font-semibold">
+            Your order{cart && cart.itemCount > 0 ? ` (${cart.itemCount})` : ""}
+          </span>
+          <button
+            type="button"
+            aria-label="Close order"
+            onClick={closeCart}
+            className="text-xl leading-none text-muted-foreground transition-colors hover:text-foreground"
+          >
+            ×
+          </button>
+        </div>
+
+        <div className="flex-1 overflow-y-auto px-6 py-5">
+          {lines.length === 0 && (
+            <p className="py-16 text-center text-sm text-muted-foreground">Your order is empty.</p>
+          )}
+          {lines.map((line) => (
+            <div className="mb-6 flex gap-4" key={line.lineItemId}>
+              {line.imageUrl ? (
+                <img
+                  src={line.imageUrl}
+                  alt=""
+                  loading="lazy"
+                  className="h-16 w-16 flex-shrink-0 rounded-md bg-secondary object-cover"
+                />
+              ) : (
+                <div aria-hidden="true" className="h-16 w-16 flex-shrink-0 rounded-md bg-secondary" />
+              )}
+              <div className="min-w-0 flex-1">
+                <p className="text-sm font-medium">{line.itemName}</p>
+                {line.descriptionLines.map((d) => (
+                  <p className="mt-0.5 text-xs text-muted-foreground" key={d}>
+                    {d}
+                  </p>
+                ))}
+                {line.status !== "IN_STOCK" && (
+                  <p className="mt-1 text-xs text-red-600">No longer available</p>
+                )}
+                <div className="mt-2 flex items-center">
+                  <div className="inline-flex items-center gap-3 rounded-full border border-border px-2 py-0.5">
+                    <button
+                      type="button"
+                      aria-label="Decrease quantity"
+                      disabled={busy || line.quantity <= 1}
+                      onClick={() => updateQuantity(line.lineItemId, line.quantity - 1).catch(() => {})}
+                      className="px-1 text-base disabled:opacity-40"
+                    >
+                      −
+                    </button>
+                    <span className="text-sm tabular-nums">{line.quantity}</span>
+                    <button
+                      type="button"
+                      aria-label="Increase quantity"
+                      disabled={busy}
+                      onClick={() => updateQuantity(line.lineItemId, line.quantity + 1).catch(() => {})}
+                      className="px-1 text-base disabled:opacity-40"
+                    >
+                      +
+                    </button>
+                  </div>
+                  <button
+                    type="button"
+                    disabled={busy}
+                    onClick={() => removeLine(line.lineItemId).catch(() => {})}
+                    className="ml-3 text-xs text-muted-foreground underline transition-colors hover:text-foreground disabled:opacity-40"
+                  >
+                    Remove
+                  </button>
+                </div>
+              </div>
+              <p className="text-sm font-medium">{line.linePrice}</p>
+            </div>
+          ))}
+        </div>
+
+        {lines.length > 0 && (
+          <div className="border-t border-border px-6 py-5">
+            {cart?.subtotal && (
+              <div className="mb-4 flex justify-between text-sm">
+                <span className="text-muted-foreground">Subtotal</span>
+                <strong className="font-semibold">{cart.subtotal}</strong>
+              </div>
+            )}
+            {error && <p className="mb-3 text-xs text-red-600">{error}</p>}
+            <button
+              type="button"
+              disabled={busy}
+              onClick={() => checkout().catch(() => {})}
+              className="w-full rounded-full bg-primary py-3.5 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
+            >
+              {busy ? "One moment…" : "Checkout"}
+            </button>
+          </div>
+        )}
+      </aside>
+    </div>
+  );
+}

package/skills/wix-headless-fast/references/restaurants/app/components/restaurants/ReservationView.tsx

@@ -0,0 +1,155 @@
+// REFERENCE reservations surface: party/date/time query → AVAILABLE slot pills → hold →
+// details form → confirmed, on the @theme tokens. Correct and complete; per the skill's
+// model you design and build your own on useReservation (which owns ALL booking logic).
+import { useReservation } from "../../hooks/restaurants/useReservation";
+
+const input =
+  "w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none focus:border-primary";
+
+export default function ReservationView() {
+  const r = useReservation();
+
+  if (r.locations === null) {
+    return <div className="h-64 animate-pulse rounded-lg bg-secondary" aria-busy="true" />;
+  }
+  if (r.locations.length === 0 || !r.location) {
+    return (
+      <p className="py-16 text-center text-muted-foreground">
+        Table reservations aren't set up yet — call us to book.
+      </p>
+    );
+  }
+  if (!r.location.onlineReservationsEnabled) {
+    // Premium-gated toggle is off — slots/booking would fail; be honest, don't fake a form.
+    return (
+      <p className="py-16 text-center text-muted-foreground">
+        Online reservations aren't open yet — call us to book a table.
+      </p>
+    );
+  }
+
+  if (r.confirmed) {
+    return (
+      <div className="mx-auto max-w-md rounded-lg border border-border p-8 text-center">
+        <p className="text-lg font-semibold">
+          {r.confirmed.status === "RESERVED" ? "Table reserved" : "Request sent"}
+        </p>
+        <p className="mt-2 text-sm text-muted-foreground">
+          {r.confirmed.status === "RESERVED"
+            ? "See you soon — a confirmation is on its way."
+            : "The restaurant will confirm your reservation shortly."}
+        </p>
+        <button
+          type="button"
+          onClick={r.reset}
+          className="mt-6 rounded-full border border-border px-5 py-2 text-sm font-medium hover:bg-secondary"
+        >
+          Make another reservation
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto max-w-xl">
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+        <label className="block text-sm">
+          <span className="text-muted-foreground">Guests</span>
+          <input
+            type="number"
+            min={r.location.partySizeMin}
+            max={r.location.partySizeMax}
+            value={r.partySize}
+            onChange={(e) => r.setPartySize(Number(e.target.value))}
+            className={`mt-1 ${input}`}
+          />
+        </label>
+        <label className="block text-sm">
+          <span className="text-muted-foreground">Date</span>
+          <input type="date" value={r.date} onChange={(e) => r.setDate(e.target.value)} className={`mt-1 ${input}`} />
+        </label>
+        <label className="block text-sm">
+          <span className="text-muted-foreground">Around</span>
+          <input type="time" value={r.time} onChange={(e) => r.setTime(e.target.value)} className={`mt-1 ${input}`} />
+        </label>
+      </div>
+      <button
+        type="button"
+        disabled={r.loading}
+        onClick={() => void r.findSlots()}
+        className="mt-4 w-full rounded-full bg-primary py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
+      >
+        {r.loading && r.slots === null ? "Finding times…" : "Find a table"}
+      </button>
+
+      {r.error && <p className="mt-4 text-sm text-red-600">{r.error}</p>}
+
+      {r.slots !== null && r.slots.length === 0 && !r.error && (
+        <p className="mt-6 text-center text-sm text-muted-foreground">
+          No tables around that time — try another time or party size.
+        </p>
+      )}
+
+      {r.slots !== null && r.slots.length > 0 && !r.held && (
+        <div className="mt-6 flex flex-wrap gap-2" role="group" aria-label="Available times">
+          {r.slots.map((slot) => (
+            <button
+              key={slot.startIso}
+              type="button"
+              disabled={r.loading}
+              onClick={() => void r.holdSlot(slot)}
+              className="rounded-full border border-border px-4 py-1.5 text-sm font-medium transition-colors hover:bg-secondary disabled:opacity-40"
+            >
+              {slot.label}
+            </button>
+          ))}
+        </div>
+      )}
+
+      {r.held && (
+        <div className="mt-6 rounded-lg border border-border p-5">
+          <p className="text-sm font-medium">
+            Holding {new Date(r.held.startIso).toLocaleString(undefined, { weekday: "short", month: "short", day: "numeric", hour: "numeric", minute: "2-digit" })}{" "}
+            for {r.held.partySize} — complete within 10 minutes.
+          </p>
+          <div className="mt-4 grid grid-cols-1 gap-3 sm:grid-cols-2">
+            <input
+              placeholder="First name *"
+              value={r.reservee.firstName}
+              onChange={(e) => r.setReserveeField("firstName", e.target.value)}
+              className={input}
+            />
+            <input
+              placeholder="Last name"
+              value={r.reservee.lastName ?? ""}
+              onChange={(e) => r.setReserveeField("lastName", e.target.value)}
+              className={input}
+            />
+            <input
+              placeholder="Phone (+15551234567) *"
+              type="tel"
+              value={r.reservee.phone}
+              onChange={(e) => r.setReserveeField("phone", e.target.value)}
+              className={input}
+            />
+            <input
+              placeholder="Email"
+              type="email"
+              value={r.reservee.email ?? ""}
+              onChange={(e) => r.setReserveeField("email", e.target.value)}
+              className={input}
+            />
+          </div>
+          <button
+            type="button"
+            disabled={!r.canConfirm}
+            onClick={() => void r.confirm()}
+            className="mt-4 w-full rounded-full bg-primary py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
+          >
+            {r.loading ? "Reserving…" : "Complete reservation"}
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

package/skills/wix-headless-fast/references/restaurants/app/hooks/restaurants/useMenus.ts

@@ -0,0 +1,55 @@
+// Menu browsing. SSR-friendly: pass server-fetched menus as `initialMenus` (Astro
+// frontmatter) and no client fetch happens; a SPA passes nothing. Menu switching is
+// client-side (the whole tree is fetched once).
+import { useEffect, useMemo, useState } from "react";
+import { fetchMenus } from "../../wix/restaurants/menu";
+import type { MenuData } from "../../wix/restaurants/types";
+
+export interface UseMenusOptions {
+  initialMenus?: MenuData[];
+}
+
+export interface UseMenus {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  menus: MenuData[] | null;
+  /** Defaults to the first menu once loaded. */
+  activeMenuId: string | null;
+  setActiveMenuId: (id: string) => void;
+  /** The menu to render (its sections/items are display-ordered). */
+  activeMenu: MenuData | null;
+  error: string | null;
+}
+
+export function useMenus({ initialMenus }: UseMenusOptions = {}): UseMenus {
+  const [menus, setMenus] = useState<MenuData[] | null>(initialMenus ?? null);
+  const [activeMenuId, setActiveMenuId] = useState<string | null>(initialMenus?.[0]?.id ?? null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    if (!initialMenus) {
+      fetchMenus()
+        .then((m) => {
+          if (!alive) return;
+          setMenus(m);
+          setActiveMenuId((id) => id ?? m[0]?.id ?? null);
+        })
+        .catch((e) => {
+          if (!alive) return;
+          setMenus([]);
+          setError(e instanceof Error ? e.message : String(e));
+        });
+    }
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const activeMenu = useMemo(() => {
+    if (!menus) return null;
+    return menus.find((m) => m.id === activeMenuId) ?? menus[0] ?? null;
+  }, [menus, activeMenuId]);
+
+  return { menus, activeMenuId: activeMenu?.id ?? null, setActiveMenuId, activeMenu, error };
+}

package/skills/wix-headless-fast/references/restaurants/app/hooks/restaurants/useOrderCart.ts

@@ -0,0 +1,43 @@
+// React binding for the order-cart store. Works in any React root — Astro islands (several
+// on one page share the same store) and SPAs alike.
+import { useSyncExternalStore } from "react";
+import {
+  addOrderLine,
+  getOrderCartState,
+  goToOrderCheckout,
+  refreshOrderCart,
+  removeLineFromOrder,
+  setOrderCartOpen,
+  subscribeOrderCart,
+  updateOrderLineQuantity,
+  type OrderCartState,
+} from "../../wix/restaurants/order-store";
+
+const SERVER_STATE = getOrderCartState();
+
+export interface UseOrderCart extends OrderCartState {
+  itemCount: number;
+  /** menuId/sectionId come from the render context (the fetchMenus tree) — pass both. */
+  addToOrder: (itemId: string, context: { menuId: string; sectionId: string }, quantity?: number) => Promise<void>;
+  updateQuantity: (lineItemId: string, quantity: number) => Promise<void>;
+  removeLine: (lineItemId: string) => Promise<void>;
+  checkout: () => Promise<void>;
+  openCart: () => void;
+  closeCart: () => void;
+  refresh: () => Promise<void>;
+}
+
+export function useOrderCart(): UseOrderCart {
+  const state = useSyncExternalStore(subscribeOrderCart, getOrderCartState, () => SERVER_STATE);
+  return {
+    ...state,
+    itemCount: state.cart?.itemCount ?? 0,
+    addToOrder: addOrderLine,
+    updateQuantity: updateOrderLineQuantity,
+    removeLine: removeLineFromOrder,
+    checkout: goToOrderCheckout,
+    openCart: () => setOrderCartOpen(true),
+    closeCart: () => setOrderCartOpen(false),
+    refresh: refreshOrderCart,
+  };
+}

package/skills/wix-headless-fast/references/restaurants/app/hooks/restaurants/useReservation.ts

@@ -0,0 +1,177 @@
+// The whole table-reservation state machine: location, date + party size, AVAILABLE slots,
+// the 10-minute hold, the details form, and confirm. All correctness (AVAILABLE-only slots,
+// hold → reserve with the revision, firstName + E.164 phone, RESERVED vs REQUESTED) lives in
+// the data layer — this hook orchestrates; you own how it looks. Client-only: availability
+// is timezone-specific, so render the surface with client:only="react" in Astro.
+import { useEffect, useState } from "react";
+import {
+  completeReservation,
+  fetchReservationLocations,
+  fetchReservationSlots,
+  holdReservation,
+} from "../../wix/restaurants/reservations";
+import type {
+  ReservationConfirmation,
+  ReservationHold,
+  ReservationLocationInfo,
+  ReservationReservee,
+  ReservationSlot,
+} from "../../wix/restaurants/types";
+
+const todayKey = (): string => {
+  const d = new Date();
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+};
+
+export interface UseReservation {
+  /** null while loading; [] when Table Reservations isn't set up (honest empty state). */
+  locations: ReservationLocationInfo[] | null;
+  /** The active location (default first). Render a picker only when locations.length > 1. */
+  location: ReservationLocationInfo | null;
+  setLocationId: (id: string) => void;
+  /** "YYYY-MM-DD" for a date input. */
+  date: string;
+  setDate: (date: string) => void;
+  /** "HH:mm" anchor for the slot fan-out. */
+  time: string;
+  setTime: (time: string) => void;
+  /** Clamped to the location's partySizeMin/Max. */
+  partySize: number;
+  setPartySize: (size: number) => void;
+  /** AVAILABLE slots for the current query; null until findSlots ran. */
+  slots: ReservationSlot[] | null;
+  findSlots: () => Promise<void>;
+  /** Set after holdSlot — the visitor has 10 minutes to confirm. */
+  held: ReservationHold | null;
+  holdSlot: (slot: ReservationSlot) => Promise<void>;
+  reservee: ReservationReservee;
+  setReserveeField: (field: keyof ReservationReservee, value: string) => void;
+  /** True when a slot is held and firstName + phone are filled — gate the confirm CTA. */
+  canConfirm: boolean;
+  confirm: () => Promise<void>;
+  /** Set on success. REQUESTED → tell the visitor approval is pending, not confirmed. */
+  confirmed: ReservationConfirmation | null;
+  /** Back to slot picking (keeps date/party). */
+  reset: () => void;
+  loading: boolean;
+  error: string | null;
+}
+
+export function useReservation(): UseReservation {
+  const [locations, setLocations] = useState<ReservationLocationInfo[] | null>(null);
+  const [locationId, setLocationId] = useState<string | null>(null);
+  const [date, setDate] = useState<string>(todayKey());
+  const [time, setTime] = useState<string>("19:00");
+  const [partySize, setPartySizeRaw] = useState<number>(2);
+  const [slots, setSlots] = useState<ReservationSlot[] | null>(null);
+  const [held, setHeld] = useState<ReservationHold | null>(null);
+  const [reservee, setReservee] = useState<ReservationReservee>({ firstName: "", phone: "" });
+  const [confirmed, setConfirmed] = useState<ReservationConfirmation | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    fetchReservationLocations()
+      .then((locs) => {
+        if (!alive) return;
+        setLocations(locs);
+        setLocationId((id) => id ?? locs[0]?.id ?? null);
+      })
+      .catch((e) => {
+        if (!alive) return;
+        setLocations([]);
+        setError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  const location = locations?.find((l) => l.id === locationId) ?? locations?.[0] ?? null;
+
+  const setPartySize = (size: number) => {
+    const min = location?.partySizeMin ?? 1;
+    const max = location?.partySizeMax ?? 20;
+    setPartySizeRaw(Math.min(Math.max(size, min), max));
+  };
+
+  async function findSlots(): Promise<void> {
+    if (!location) return;
+    setError(null);
+    setSlots(null);
+    setHeld(null);
+    setConfirmed(null);
+    setLoading(true);
+    try {
+      const aroundIso = new Date(`${date}T${time}:00`).toISOString();
+      setSlots(await fetchReservationSlots(location.id, aroundIso, partySize));
+    } catch (e) {
+      setSlots([]);
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function holdSlot(slot: ReservationSlot): Promise<void> {
+    if (!location) return;
+    setError(null);
+    setLoading(true);
+    try {
+      setHeld(await holdReservation(location.id, slot.startIso, partySize));
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  const canConfirm =
+    !!held && reservee.firstName.trim().length > 0 && reservee.phone.trim().length > 0 && !loading;
+
+  async function confirm(): Promise<void> {
+    if (!held) return;
+    setError(null);
+    setLoading(true);
+    try {
+      setConfirmed(await completeReservation(held, reservee));
+    } catch (e) {
+      // An expired hold can't be reserved — send the visitor back to slot picking.
+      setError(e instanceof Error ? e.message : String(e));
+      setHeld(null);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return {
+    locations,
+    location,
+    setLocationId,
+    date,
+    setDate,
+    time,
+    setTime,
+    partySize,
+    setPartySize,
+    slots,
+    findSlots,
+    held,
+    holdSlot,
+    reservee,
+    setReserveeField: (field, value) => setReservee((r) => ({ ...r, [field]: value })),
+    canConfirm,
+    confirm,
+    confirmed,
+    reset: () => {
+      setHeld(null);
+      setConfirmed(null);
+      setSlots(null);
+      setError(null);
+    },
+    loading,
+    error,
+  };
+}