@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/bookings/project/src/components/bookings/ServicesView.tsx

@@ -0,0 +1,193 @@
+// REFERENCE listing surface: category + location filters, services grid, load-more, on the @theme
+// tokens. Correct and complete; per the skill's model you design and build your own on useServices.
+import type { ComponentType, ReactNode } from "react";
+import { useServices } from "../../hooks/bookings/useServices";
+import { OTHER_LOCATIONS_ID } from "../../wix/bookings/services-store";
+import type { BookingCategory, LocationOption, ServiceSummary, Weekday } from "../../wix/bookings/types";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+const TYPE_LABEL: Record<ServiceSummary["type"], string> = { APPOINTMENT: "Appointment", CLASS: "Class", COURSE: "Course" };
+const DAY_SHORT: Record<Weekday, string> = { MONDAY: "Mon", TUESDAY: "Tue", WEDNESDAY: "Wed", THURSDAY: "Thu", FRIDAY: "Fri", SATURDAY: "Sat", SUNDAY: "Sun" };
+
+/** The price line a tile shows: "From €30", a struck-through base price beside a discount, or the plain price. */
+export function PriceLine({ service }: { service: ServiceSummary }) {
+  if (!service.price) return null;
+  return (
+    <span className="text-foreground">
+      {service.priceFrom ? "From " : ""}
+      {service.price}
+      {service.basePrice && <s className="ml-1 text-muted-foreground">{service.basePrice}</s>}
+      {service.discountName && <span className="ml-1 text-xs text-muted-foreground">{service.discountName}</span>}
+      {service.calculatedAtCheckout && <span className="ml-1 text-xs text-muted-foreground">(discount at checkout)</span>}
+    </span>
+  );
+}
+
+export interface ServiceCardProps {
+  service: ServiceSummary;
+  serviceHref?: (slug: string) => string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+export function ServiceCard({
+  service,
+  serviceHref = (slug) => `/services/${slug}`,
+  LinkComponent = PlainLink,
+}: ServiceCardProps) {
+  return (
+    <LinkComponent href={serviceHref(service.slug)} className="group block no-underline">
+      <div className="relative aspect-[4/3] overflow-hidden rounded-lg bg-secondary">
+        {service.imageUrl && (
+          <img
+            src={service.imageUrl}
+            alt={service.name}
+            loading="lazy"
+            className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-[1.03]"
+          />
+        )}
+        <span className="absolute left-3 top-3 flex gap-1">
+          <span className="rounded-control bg-background/90 px-3 py-1 text-xs font-semibold text-foreground backdrop-blur">{TYPE_LABEL[service.type]}</span>
+          {service.conferencing && <span className="rounded-control bg-background/90 px-3 py-1 text-xs font-semibold text-foreground backdrop-blur">Online</span>}
+        </span>
+      </div>
+      <p className="mt-3 text-sm font-medium text-foreground">{service.name}</p>
+      {service.tagLine && <p className="mt-0.5 text-xs text-muted-foreground">{service.tagLine}</p>}
+      <p className="mt-1 text-sm text-muted-foreground">
+        {service.durationLabel ? `${service.durationLabel} · ` : ""}
+        <PriceLine service={service} />
+      </p>
+      {service.offeredDays.length > 0 && <p className="mt-0.5 text-xs text-muted-foreground">{service.offeredDays.map((d) => DAY_SHORT[d]).join(", ")}</p>}
+      {service.locations.length > 0 && service.locations[0].name && (
+        <p className="mt-0.5 text-xs text-muted-foreground">{service.locations.map((l) => l.name).filter(Boolean).join(" · ")}</p>
+      )}
+    </LinkComponent>
+  );
+}
+
+export interface ServicesViewProps {
+  initialServices?: ServiceSummary[];
+  initialHasMore?: boolean;
+  initialCategories?: BookingCategory[];
+  initialLocations?: { locations: LocationOption[]; hasOtherLocations: boolean };
+  initialCategoryId?: string | null;
+  initialLocationId?: string | null;
+  emptyMessage?: string;
+  serviceHref?: ServiceCardProps["serviceHref"];
+  LinkComponent?: ComponentType<LinkLikeProps>;
+  CardComponent?: ComponentType<ServiceCardProps>;
+}
+
+const pill = (active: boolean) =>
+  `rounded-control border px-4 py-1.5 text-sm font-medium transition-colors ${
+    active
+      ? "border-primary bg-primary text-primary-foreground"
+      : "border-border text-foreground hover:bg-secondary"
+  }`;
+
+export default function ServicesView({
+  initialServices,
+  initialHasMore,
+  initialCategories,
+  initialLocations,
+  initialCategoryId,
+  initialLocationId,
+  emptyMessage = "No services yet — check back soon.",
+  serviceHref,
+  LinkComponent,
+  CardComponent = ServiceCard,
+}: ServicesViewProps) {
+  const {
+    services,
+    categories,
+    locations,
+    hasOtherLocations,
+    activeCategoryId,
+    setActiveCategoryId,
+    activeLocationId,
+    setActiveLocationId,
+    hasMore,
+    loadingMore,
+    loadMore,
+    error,
+  } = useServices({ initialServices, initialHasMore, initialCategories, initialLocations, initialCategoryId, initialLocationId });
+
+  const locationOptions = locations.length + (hasOtherLocations ? 1 : 0);
+
+  return (
+    <div>
+      {categories.length > 1 && (
+        <div className="mb-4 flex flex-wrap gap-2" role="group" aria-label="Categories">
+          <button type="button" className={pill(activeCategoryId === null)} onClick={() => setActiveCategoryId(null)}>
+            All
+          </button>
+          {categories.map((c) => (
+            <button key={c.id} type="button" className={pill(activeCategoryId === c.id)} onClick={() => setActiveCategoryId(c.id)}>
+              {c.name}
+            </button>
+          ))}
+        </div>
+      )}
+      {locationOptions > 1 && (
+        <div className="mb-8 flex flex-wrap gap-2" role="group" aria-label="Locations">
+          <button type="button" className={pill(activeLocationId === null)} onClick={() => setActiveLocationId(null)}>
+            All locations
+          </button>
+          {locations.map((l) => (
+            <button key={l.id} type="button" className={pill(activeLocationId === l.id)} onClick={() => setActiveLocationId(l.id)}>
+              {l.name}
+            </button>
+          ))}
+          {hasOtherLocations && (
+            <button type="button" className={pill(activeLocationId === OTHER_LOCATIONS_ID)} onClick={() => setActiveLocationId(OTHER_LOCATIONS_ID)}>
+              Other locations
+            </button>
+          )}
+        </div>
+      )}
+      {error && <p className="mb-4 text-sm text-destructive">{error}</p>}
+      {services === null ? (
+        <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3" aria-busy="true">
+          {Array.from({ length: 6 }, (_, i) => (
+            <div key={i}>
+              <div className="aspect-[4/3] animate-pulse rounded-lg bg-secondary" />
+              <div className="mt-3 h-3.5 w-2/3 animate-pulse rounded bg-secondary" />
+            </div>
+          ))}
+        </div>
+      ) : services.length === 0 ? (
+        <p className="py-16 text-center text-muted-foreground">{emptyMessage}</p>
+      ) : (
+        <>
+          <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3">
+            {services.map((s) => (
+              <CardComponent key={s.id} service={s} serviceHref={serviceHref} LinkComponent={LinkComponent} />
+            ))}
+          </div>
+          {hasMore && (
+            <div className="mt-10 text-center">
+              <button
+                type="button"
+                disabled={loadingMore}
+                onClick={() => void loadMore()}
+                className="rounded-control border border-border px-6 py-2 text-sm font-medium text-foreground transition-colors hover:bg-secondary disabled:opacity-50"
+              >
+                {loadingMore ? "Loading…" : "Load more"}
+              </button>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  );
+}

package/skills/wix-headless-templates/bookings/project/src/hooks/bookings/useBookingFlow.ts

@@ -0,0 +1,56 @@
+// React binding of the booking-flow store (wix/bookings/booking-flow-store.ts) — the whole booking
+// state machine for one service lives there, framework-free: the display zone, the availability
+// window (day-grouped slots, week paging, staff filter, next availability), a course's seats, a
+// class's sessions, participants, deposit choice, add-ons, the schema-driven form, the CTA state,
+// and book(). All correctness lives in the data layer; you own how it looks. Mount the surface
+// client-only: availability is timezone/session-specific.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createBookingFlowStore, type BookingFlowState, type BookingFlowStore } from "../../wix/bookings/booking-flow-store";
+import type { ServiceDetail } from "../../wix/bookings/types";
+
+export type UseBookingFlow = BookingFlowState &
+  Pick<
+    BookingFlowStore,
+    | "nextWeek"
+    | "prevWeek"
+    | "jumpTo"
+    | "setStaffId"
+    | "setSelectedSlot"
+    | "setDisplayTimeZone"
+    | "setParticipants"
+    | "setPayDeposit"
+    | "toggleAddOn"
+    | "setAddOnQuantity"
+    | "canSelectMore"
+    | "loadMoreSessions"
+    | "setValue"
+    | "book"
+  >;
+
+export function useBookingFlow(service: ServiceDetail): UseBookingFlow {
+  const ref = useRef<{ serviceId: string; store: BookingFlowStore } | null>(null);
+  if (!ref.current || ref.current.serviceId !== service.id) ref.current = { serviceId: service.id, store: createBookingFlowStore(service) };
+  const store = ref.current.store;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return {
+    ...state,
+    nextWeek: store.nextWeek,
+    prevWeek: store.prevWeek,
+    jumpTo: store.jumpTo,
+    setStaffId: store.setStaffId,
+    setSelectedSlot: store.setSelectedSlot,
+    setDisplayTimeZone: store.setDisplayTimeZone,
+    setParticipants: store.setParticipants,
+    setPayDeposit: store.setPayDeposit,
+    toggleAddOn: store.toggleAddOn,
+    setAddOnQuantity: store.setAddOnQuantity,
+    canSelectMore: store.canSelectMore,
+    loadMoreSessions: store.loadMoreSessions,
+    setValue: store.setValue,
+    book: store.book,
+  };
+}

package/skills/wix-headless-templates/bookings/project/src/hooks/bookings/useServices.ts

@@ -0,0 +1,23 @@
+// React binding of the services store (wix/bookings/services-store.ts) — the listing state lives
+// there, framework-free; this hook subscribes to one instance per mounted listing and exposes its
+// state and actions under one name. SSR-friendly: pass server-fetched data as `initial*` (Astro
+// frontmatter / server component) and no client fetch happens for the first paint; a SPA passes
+// nothing. Astro islands and React SPAs use this; a static page, Vue, or Svelte uses the store directly.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createServicesStore, type ServicesState, type ServicesStore, type ServicesStoreOptions } from "../../wix/bookings/services-store";
+
+export type UseServicesOptions = ServicesStoreOptions;
+
+export type UseServices = ServicesState & Pick<ServicesStore, "setActiveCategoryId" | "setActiveLocationId" | "loadMore">;
+
+export function useServices(options: UseServicesOptions = {}): UseServices {
+  const ref = useRef<ServicesStore | null>(null);
+  if (!ref.current) ref.current = createServicesStore(options);
+  const store = ref.current;
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return { ...state, setActiveCategoryId: store.setActiveCategoryId, setActiveLocationId: store.setActiveLocationId, loadMore: store.loadMore };
+}

package/skills/wix-headless-templates/bookings/project/src/layouts/Layout.astro

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Wix Astro Basics</title>
+	</head>
+	<body>
+		<slot />
+	</body>
+</html>
+
+<style>
+	html,
+	body {
+		margin: 0;
+		width: 100%;
+		height: 100%;
+	}
+</style>

package/skills/wix-headless-templates/bookings/project/src/layouts/SiteLayout.astro

@@ -0,0 +1,40 @@
+---
+// The site chrome for every bookings page — THIS file (header/footer/nav) plus the @theme
+// token block in src/styles/global.css are what you brand. Keep the <slot name="seo-tags" />
+// in <head> and the global.css import. (If the storefront vertical is also deployed, its
+// SiteLayout won; merge nav links there instead.)
+import "../styles/global.css";
+
+interface Props {
+  title: string;
+  description?: string;
+}
+const { title, description } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    <slot name="seo-tags" />
+  </head>
+  <body>
+    <header class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur">
+      <div class="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
+        <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
+        <nav class="flex items-center gap-6 text-sm">
+          <a href="/services" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Services</a>
+        </nav>
+      </div>
+    </header>
+    <main class="mx-auto max-w-6xl px-6 pb-24 pt-10">
+      <slot />
+    </main>
+    <footer class="border-t border-border px-6 py-10 text-center text-sm text-muted-foreground">
+      © Brand Name
+    </footer>
+  </body>
+</html>

package/skills/wix-headless-templates/bookings/project/src/pages/index.astro

@@ -0,0 +1,8 @@
+---
+import Hero from '../components/Hero.astro';
+import Layout from '../layouts/Layout.astro';
+---
+
+<Layout>
+	<Hero />
+</Layout>

package/skills/wix-headless-templates/bookings/project/src/pages/services/[slug].astro

@@ -0,0 +1,81 @@
+---
+// Service detail + booking page.
+//
+// This is a Wix ITEM PAGE: the wixMetadata export + <SEO.Tags> below let the site owner edit
+// this page's title/description/OG in the dashboard and register the route in the sitemap.
+// Keep all three SEO pieces and this frontmatter; swap the island import to YOUR booking
+// component. The booking island is client:only — availability is timezone/session-specific.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import ServiceBookingView from "../../components/bookings/ServiceBookingView";
+import { fetchServiceBySlug } from "../../wix/bookings/services";
+import { WIX_APPS } from "@wix/essentials";
+import { SEO } from "@wix/seo/components";
+import { loadSEOTagsServiceConfig } from "@wix/seo/services";
+import { seoTags } from "@wix/seo";
+
+export const wixMetadata = {
+  appDefId: WIX_APPS.bookings.id,
+  pageIdentifier: WIX_APPS.bookings.servicePageMetadata.pageIdentifier,
+  identifiers: {
+    slug: WIX_APPS.bookings.servicePageMetadata.identifiers.slug,
+  },
+};
+
+const slug = Astro.params.slug!;
+
+// Behind Wix's proxy the request URL is internal — the real public page URL arrives on
+// x-wix-forwarded-url; the SEO service needs the public one.
+const forwardedUrl = Astro.request.headers.get("x-wix-forwarded-url");
+const pageUrl =
+  forwardedUrl && URL.canParse(forwardedUrl) && /^https?:$/.test(new URL(forwardedUrl).protocol)
+    ? forwardedUrl
+    : Astro.url.href;
+
+let service = null;
+let seoTagsServiceConfig = null;
+try {
+  [service, seoTagsServiceConfig] = await Promise.all([
+    fetchServiceBySlug(slug),
+    loadSEOTagsServiceConfig({
+      pageUrl,
+      itemType: seoTags.ItemType.BOOKINGS_SERVICE,
+      itemData: { slug },
+    }).catch(() => null),
+  ]);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!service) {
+  return new Response(null, { status: 404 });
+}
+---
+
+<SiteLayout title={service.name}>
+  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
+
+  <div class="grid gap-10 md:grid-cols-2">
+    <div>
+      {service.imageUrl && (
+        <div class="aspect-[4/3] overflow-hidden rounded-xl bg-secondary">
+          <img src={service.imageUrl} alt={service.name} class="h-full w-full object-cover" />
+        </div>
+      )}
+      <h1 class="mt-5 text-2xl font-semibold tracking-tight">{service.name}</h1>
+      {service.tagLine && <p class="mt-1 text-muted-foreground">{service.tagLine}</p>}
+      <p class="mt-2 text-sm text-muted-foreground">
+        {service.durationLabel ? `${service.durationLabel} · ` : ""}
+        {service.price && <span class="text-foreground">{service.priceFrom ? "From " : ""}{service.price}</span>}
+        {service.basePrice && <s class="ml-1">{service.basePrice}</s>}
+        {service.discountName && <span class="ml-1 text-xs">{service.discountName}</span>}
+      </p>
+      {service.locations.some((l) => l.name) && (
+        <p class="mt-1 text-sm text-muted-foreground">{service.locations.map((l) => l.name).filter(Boolean).join(" · ")}</p>
+      )}
+      {service.description && <p class="mt-4 text-sm leading-relaxed text-muted-foreground">{service.description}</p>}
+    </div>
+    <div>
+      <ServiceBookingView client:only="react" service={service} />
+    </div>
+  </div>
+</SiteLayout>

package/skills/wix-headless-templates/bookings/project/src/pages/services.astro

@@ -0,0 +1,40 @@
+---
+// Services listing — the first page fetched SERVER-SIDE (SEO) with the URL's filter (`?category=`,
+// `?location=`) and handed to the island as DTO props; the island pages and re-filters from there.
+// Keep this frontmatter; swap the island import to YOUR listing component.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import ServicesView from "../components/bookings/ServicesView";
+import { fetchServices, fetchBookingCategories, fetchLocations } from "../wix/bookings/services";
+import type { BookingCategory, LocationOption, ServiceSummary } from "../wix/bookings/types";
+
+const categoryId = Astro.url.searchParams.get("category") || null;
+const locationId = Astro.url.searchParams.get("location") || null;
+
+let services: ServiceSummary[] = [];
+let hasMore = false;
+let categories: BookingCategory[] = [];
+let locations: { locations: LocationOption[]; hasOtherLocations: boolean } = { locations: [], hasOtherLocations: false };
+try {
+  const [page, cats, locs] = await Promise.all([fetchServices({ categoryId, locationId }), fetchBookingCategories(), fetchLocations()]);
+  services = page.items;
+  hasMore = page.hasMore;
+  categories = cats;
+  locations = locs;
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the island renders the
+  // empty state instead.
+}
+---
+
+<SiteLayout title="Services">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Services</h1>
+  <ServicesView
+    client:load
+    initialServices={services}
+    initialHasMore={hasMore}
+    initialCategories={categories}
+    initialLocations={locations}
+    initialCategoryId={categoryId}
+    initialLocationId={locationId}
+  />
+</SiteLayout>

package/skills/wix-headless-templates/bookings/project/src/styles/global.css

@@ -0,0 +1,57 @@
+@import url('https://fonts.googleapis.com/css2?family=Wix+Madefor+Text:wght@400;500;600;700;800&display=swap');
+@import 'tailwindcss';
+
+/* ─── THE design system ─────────────────────────────────────────────────────────────────
+   Theme the entire store by editing THIS @theme block (same token family as the official
+   Wix headless templates). Every shipped component styles itself from these via Tailwind
+   utilities (bg-primary, text-muted-foreground, text-destructive, rounded-lg, …) — change a token, everything
+   follows. A dark theme is just flipped values (dark background/foreground, adjusted
+   secondary/border). Don't restyle shipped component markup; restyle the tokens.
+
+   Choosing values: argue polarity from the business — light is not "cheap" (wellness/food
+   usually read better light); never dark-by-default for "premium". Palette: one dominant +
+   accents from ADJACENT hues (~30° arc), 2-4 colors total. Every background/foreground pair
+   you set must hit WCAG 4.5:1 (3:1 for text ≥24px); body copy never below 16px/1.5. Derive
+   from THIS brand — a look repeated across projects is a failure, not a shortcut. The user's
+   explicit direction beats all of this except the contrast floor. */
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(230 24% 14%);
+  --color-primary: hsl(230 24% 14%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(228 24% 96%);
+  --color-secondary-foreground: hsl(230 24% 14%);
+  --color-muted-foreground: hsl(228 8% 46%);
+  --color-border: hsl(220 14% 90%);
+  --color-destructive: hsl(0 72% 51%);
+
+  --radius-lg: 12px;
+  --radius-md: 8px;
+  --radius-sm: 6px;
+  /* Buttons, chips, labels, steppers and the progress bar. Follows --radius-md unless the brand
+     wants otherwise: 9999px is the pill, 0 is square. Genuine circles (swatches, avatars, dots)
+     stay rounded-full and do not read this. */
+  --radius-control: var(--radius-md);
+
+  --font-sans: 'Wix Madefor Text', system-ui, sans-serif;
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
+  }
+}
+
+@layer utilities {
+  .eyebrow {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground);
+  }
+}