@wix/agent-skills 1.20.0 → 1.20.1

package/skills/wix-headless-fast/references/blog/rest/posts.ts

@@ -0,0 +1,42 @@
+// Post reads over REST — the twin of app/wix/blog/posts.ts. Same exports, same DTOs; the rules and
+// mappers come from posts-core (the SAME file the SDK transport uses, deployed flat next to this one
+// by deploy.mjs --stack static), so this file is only the transport: one fetch with a literal body
+// per function. Every call here is safe from a browser with a visitor token — only PUBLISHED posts
+// come back to it. Porting: keep the paths, keep the bodies, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/query-posts.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/posts-stats/get-post-by-slug.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { BLOG_APP_ID, DETAIL_FIELDSETS, feedQuery, postMetaLine, slugQuery, toDetail, toSummary, type FetchPostsOptions, type Raw } from "./posts-core.js";
+import type { PostDetail, PostPage } from "./types.js";
+
+export { BLOG_APP_ID, postMetaLine, type FetchPostsOptions };
+
+const POSTS_QUERY = "/blog/v3/posts/query";
+
+/**
+ * One page of published posts, newest first (pinned posts lead); `nextCursor` continues the same
+ * query — send it alone, the filters ride inside it.
+ * POST /blog/v3/posts/query  { query: { filter?, sort, cursorPaging: { limit } } }   — first page
+ * POST /blog/v3/posts/query  { query: { cursorPaging: { limit, cursor } } }            — later pages
+ */
+export async function fetchPosts(o: FetchPostsOptions = {}): Promise<PostPage> {
+  const res = await wixRequest<Raw>(POSTS_QUERY, { body: { query: feedQuery(o) } });
+  const paging: Raw = res?.pagingMetadata ?? {};
+  return {
+    posts: ((res?.posts ?? []) as Raw[]).map((p) => toSummary(p, imgSrc)),
+    nextCursor: paging.hasNext ? (paging.cursors?.next ?? null) : null,
+  };
+}
+
+/**
+ * One post by URL slug with the full body (the RICH_CONTENT + CONTENT_TEXT fieldsets — without
+ * them richContent and contentText are absent). Null when the slug resolves to nothing — a real
+ * 404 for the page, never a fallback to another post.
+ * POST /blog/v3/posts/query  { fieldsets: ["RICH_CONTENT", "CONTENT_TEXT"], query: { filter: { slug: { $eq } }, cursorPaging: { limit: 1 } } }
+ */
+export async function fetchPostBySlug(slug: string): Promise<PostDetail | null> {
+  const res = await wixRequest<Raw>(POSTS_QUERY, { body: { fieldsets: DETAIL_FIELDSETS, query: slugQuery(slug) } });
+  const raw: Raw | undefined = res?.posts?.[0];
+  return raw ? toDetail(raw, imgSrc) : null;
+}

package/skills/wix-headless-fast/references/blog/rest/taxonomy.ts

@@ -0,0 +1,62 @@
+// Category + tag reads over REST — the twin of app/wix/blog/taxonomy.ts. Same exports, same DTOs;
+// the mappers come from taxonomy-core (the SAME file the SDK transport uses, deployed flat next to
+// this one). Taxonomy queries page by OFFSET (`paging`), unlike posts (`cursorPaging`); a blog's
+// taxonomy fits in one read of 100. All four calls are visitor-safe.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/query-categories.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/get-category-by-slug.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/query-tags.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/get-tag-by-slug.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { CATEGORY_SORT, TAG_SORT, TAXONOMY_LIMIT, toCategory, toTag } from "./taxonomy-core.js";
+import type { Raw } from "./posts-core.js";
+import type { BlogCategory, BlogTag } from "./types.js";
+
+/**
+ * Categories in menu order. Non-fatal: [] on failure (the feed renders without its filter row).
+ * POST /blog/v3/categories/query  { query: { sort: [{ fieldName: "displayPosition", order: "ASC" }], paging: { limit: 100 } } }
+ */
+export async function fetchBlogCategories(): Promise<BlogCategory[]> {
+  try {
+    const res = await wixRequest<Raw>("/blog/v3/categories/query", { body: { query: { sort: CATEGORY_SORT, paging: { limit: TAXONOMY_LIMIT } } } });
+    return ((res?.categories ?? []) as Raw[]).map((c) => toCategory(c, imgSrc)).filter((c) => c.id);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Tags, most-published-posts first. Non-fatal: [] on failure.
+ * POST /blog/v3/tags/query  { query: { sort: [{ fieldName: "publishedPostCount", order: "DESC" }], paging: { limit: 100 } } }
+ */
+export async function fetchBlogTags(): Promise<BlogTag[]> {
+  try {
+    const res = await wixRequest<Raw>("/blog/v3/tags/query", { body: { query: { sort: TAG_SORT, paging: { limit: TAXONOMY_LIMIT } } } });
+    return ((res?.tags ?? []) as Raw[]).map(toTag).filter((t) => t.id);
+  } catch {
+    return [];
+  }
+}
+
+// The two by-slug getters answer in DIFFERENT envelopes ({ category } and { tag }); a missing slug
+// is a 404 — mapped to null here, as the SDK transport does.
+
+/** One category by its URL slug. Null when not found.  GET /blog/v3/categories/slugs/{slug} */
+export async function fetchCategoryBySlug(slug: string): Promise<BlogCategory | null> {
+  try {
+    const res = await wixRequest<Raw>(`/blog/v3/categories/slugs/${encodeURIComponent(slug)}`, { method: "GET" });
+    return res?.category ? toCategory(res.category, imgSrc) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One tag by its URL slug. Null when not found.  GET /blog/v3/tags/slugs/{slug} */
+export async function fetchTagBySlug(slug: string): Promise<BlogTag | null> {
+  try {
+    const res = await wixRequest<Raw>(`/blog/v3/tags/slugs/${encodeURIComponent(slug)}`, { method: "GET" });
+    return res?.tag ? toTag(res.tag) : null;
+  } catch {
+    return null;
+  }
+}

package/skills/wix-headless-fast/references/blog/seed/SEED.md

@@ -62,6 +62,15 @@ feed without covers looks broken.
 **Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
 seems needed.
 
+## Supplied content
+
+The general rules are in `references/shared/SUPPLIED-CONTENT.md`. For a blog, each post the user
+hands over is one entry. Its title becomes `title`; its body becomes `content` blocks, one block per
+paragraph, heading or list, whether the body arrived as text, HTML or Markdown; a category becomes
+`category` (and joins the `categories` list); tags become `tags`; their cover image becomes
+`coverImageUrl`. A post with no body is a question for the user. Authors and publish dates are
+not seeded — say so.
+
 ## Escape hatch — individual functions
 `setupBlog` composes exported steps — `installBlogApp`, `getAuthorMemberId`, `createPosts`,
 `createCategories`, `createTags`, `importImage`, `attachPostCovers`, plus `makeCtx()` —

package/skills/wix-headless-fast/references/bookings/INSTRUCTIONS.md

@@ -8,18 +8,25 @@ the home page and the brand. You never write booking logic; you never skip desig
 
 ## The file map (deployed into `src/`)
 
-**Don't read the shipped files** — this table and the contracts below are everything you
-need. Open a shipped file's source only on a real fallback (runtime error / uncovered field),
-or to read a reference component's pattern.
+**On Astro and React the shipped files are tested and work as they are** — this table and the
+contracts below are everything you need to use them, so don't spend the run reading their source;
+wire them and build your surfaces. Reading them is the right move when something is off (a runtime
+error, a field this playbook doesn't cover) or when the brief wants a behaviour they don't offer —
+then read the file that owns it and change or extend it. On `lib`, `static`, and a port the
+components don't deploy at all, and each wiring section below opens with the files to read before
+writing their equivalents. Files you edit: `SiteLayout.astro`, `styles/global.css`, and the two
+pages' island imports. Files you **create**: your listing and booking components, plus your home page.
 
 | file | what it is |
 |---|---|
-| `wix/config.ts` · `wix/sdk.ts` · `wix/media.ts` · `wix/money.ts` | shared auth seam + helpers (deploy configures; nothing to set) |
-| `wix/bookings/types.ts` | the DTOs (`ServiceSummary`, `ServiceDetail`, `Slot`, `BookingFormField`, `BookingResult`) — contracts below |
-| `wix/bookings/services.ts` | `fetchServices`, `fetchServiceBySlug`, `fetchBookingCategories` |
-| `wix/bookings/booking.ts` | `fetchSlots`, `fetchBookingForm`, `bookService` — the exact booking sequence lives here |
-| `hooks/bookings/useServices.ts` | listing + category filter — contract below |
-| `hooks/bookings/useBookingFlow.ts` | the whole booking state machine — contract below |
+| `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(s.imageUrl, "33vw")} alt={s.name} />`; `imgSrc()` / `imgSrcSet()` / `formatMoney()` underneath |
+| `wix/bookings/types.ts` | the DTOs (`ServiceSummary`, `ServiceDetail`, `BookingCategory`, `Slot`, `BookingFormField`, `BookingResult`) — contracts below |
+| `wix/bookings/services.ts` | `fetchServices`, `fetchServiceBySlug`, `fetchBookingCategories` — the transport; the rules and DTO mappers are in `services-core.ts` beside it (shared with the REST layer) |
+| `wix/bookings/booking.ts` | `fetchSlots`, `fetchBookingForm`, `bookService` — the transport; the request bodies, the slot and form mappers, and the checkout-or-place rule are in `booking-core.ts` beside it (shared with the REST layer) |
+| `wix/bookings/services-store.ts` · `booking-flow-store.ts` | the listing and booking state machines, framework-free (`createServicesStore()`, `createBookingFlowStore(service)` — `getState`/`subscribe` + actions, one instance per surface); the hooks below bind them to React, every other stack uses them directly |
+| `hooks/bookings/useServices.ts` | React binding of `services-store.ts`: listing + category filter — contract below |
+| `hooks/bookings/useBookingFlow.ts` | React binding of `booking-flow-store.ts`: the whole booking state machine — contract below |
 | `components/bookings/ServicesView.tsx` (+ `ServiceCard`) · `ServiceBookingView.tsx` | **REFERENCE implementations** — correct, plain; build your own instead of shipping them |
 | `styles/global.css` | the design system: Tailwind v4 + the `@theme` token block (shared across verticals) |
 
@@ -45,30 +52,79 @@ Astro stack additionally gets:
 Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass).
 Style everything with Tailwind utilities on the tokens.
 
+### What a complete booking site shows (recommended defaults)
+
+Defaults for a brief that says nothing about them; the prompt wins where it differs. Look at the
+services before designing (appointments vs classes, categories, staff, prices, images) and design
+for this business, not a stereotype of its category. Then, by default:
+
+- **Home:** what the business offers and one booking action in the first screen; real services
+  under truthful headings; not a repeat of the listing.
+- **Listing:** a real service card — image, name, duration and price, link — in the first screen;
+  category pills only when there is more than one category; `services === null` → skeleton tiles,
+  `[]` → your honest empty state.
+- **Service page:** name, price, and the first bookable day's times in the first screen **at 390px
+  wide too** — the image is a bounded band on a phone, not a full-screen hero; week paging beside
+  the times; the staff filter only when `service.staff.length > 1`; the form under the times, the
+  CTA under the form with its label from `service.free` / `service.price`; a week with no times says
+  so and points to the next one.
+- **Confirmed state:** rendered only from `confirmed`; a visitor returning from the hosted checkout
+  is not a success signal.
+- **A slug that resolves to nothing** shows only the not-found state — no heading or empty picker
+  rendered around it.
+- **Copy:** nothing the owner didn't supply — no invented reviews, availability pressure, or
+  guarantees; no Wix IDs or technical words in visible text.
+
 ### The contracts your components consume
 
+Everything you need to build on the shipped code; read the source only when something is off.
+
 ```ts
 // ServiceSummary (tiles) — display-ready:
 // { id, slug, name, tagLine, type: "APPOINTMENT"|"CLASS", price /* "€75.00" | "Free" */,
-//   free, durationMinutes|null, imageUrl, categoryId|null, staff: [{id,name}] }
+//   free, durationMinutes|null, imageUrl /* https or "" */, categoryId|null, staff: [{id,name}] }
 // ServiceDetail adds: description, formId, paymentOption, cancellationFeeEnabled.
+// BookingCategory = { id, name }.
 
 // useServices({ initialServices?, initialCategories? }) →
 // { services: ServiceSummary[]|null /* null = loading → skeletons */,
-//   categories: [{id,name}], activeCategoryId, setActiveCategoryId(id|null), error }
+//   categories: BookingCategory[], activeCategoryId, setActiveCategoryId(id|null), error }
+// Category filtering is client-side (a bookings catalog is small and fully fetched).
 
 // useBookingFlow(service: ServiceDetail) →
 // { days: [{ dayKey, dayLabel, slots: Slot[] }] | null,   // day-grouped; null = loading
 //   windowStart, nextWeek(), prevWeek(),                  // 7-day paging (prev clamps to today)
 //   staffId, setStaffId(id|undefined),                    // show a picker only when service.staff.length > 1
-//   selectedSlot, setSelectedSlot(slot|null),             // Slot = { startLocal, endLocal, dayKey, label, … }
-//   formFields: [{ target, label, type, options? }],      // never empty (contact-basics fallback)
+//   selectedSlot, setSelectedSlot(slot|null),             // Slot = { startLocal, endLocal, dayKey, label, scheduleId|null, eventId|null, staff }
+//   formFields: [{ target, label, type, options?, required }], // never empty (contact-basics fallback); only required ones gate canBook
 //   values, setValue(target, value),                      // inputs write here, keyed by target
 //   canBook,                                              // gate the CTA on this
-//   book(): Promise<BookingResult>,                       // paid → the browser redirects to Wix checkout;
+//   book(): Promise<BookingResult>,                       // paid → the browser navigates to the Wix checkout;
 //   booking, confirmed, error }                           // free/offline → confirmed is set (REAL success)
+// A window or staff change clears selectedSlot and sets days to null while the new week loads.
+// book() rejects on refusal (slot taken, invalid form) AND records .error — render it beside the CTA.
 ```
 
+### The reference files for stacks where the components don't deploy
+
+On `lib`, `static`, and a port, nothing under `components/` or `hooks/` arrives. The state machines
+behind the hooks do arrive — `wix/bookings/services-store.ts`, `booking-flow-store.ts` — so you
+never rewrite them: create a store per surface, `subscribe`, render from `getState()`, call its
+actions. Their `ServicesState` / `BookingFlowState` interfaces are the render contract; read those.
+What you write is the rendering — tiles, the slot picker, the form, the CTA — and for that read
+these first; they are tested code for exactly that behaviour:
+
+1. `components/bookings/ServiceBookingView.tsx` — the booking surface as working code: day
+   groups with slot chips, week paging controls, the staff filter only when there is more than one
+   staff member, one input per `formFields` entry typed from its `type` (a `<select>` when it has
+   `options`), the CTA disabled until `canBook`, labelled free vs priced, `error` inline, and the
+   confirmed state rendered only from `confirmed`.
+2. `components/bookings/ServicesView.tsx` — category pills only when `categories.length > 1`,
+   skeleton tiles while `services === null`, the honest empty state, and `ServiceCard`: image with
+   the type badge, name, tagLine, "duration · price".
+
+All under `references/bookings/app/`.
+
 ### Wiring — Astro (default)
 
 1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass — merge into the
@@ -80,11 +136,92 @@ Style everything with Tailwind utilities on the tokens.
    batch multiple Writes per message.
 3. Write `pages/index.astro` (home) — it exists from the scaffold; Read it before overwriting.
 
+### Wiring — another JS framework (`--stack lib`: Vue, Svelte, Solid, plain Vite)
+
+Read the reference files listed above before writing any surface.
+
+`deploy.mjs bookings --stack lib` put the data layer in `src/wix/` and nothing else: `sdk.ts`
+(the visitor client, configured with the public client id), `media.ts`, `money.ts`, and
+`wix/bookings/` — `services.ts`, `booking.ts`, `types.ts`, the `*-core.ts` rules, and the two
+stores `services-store.ts`, `booking-flow-store.ts`. None of it is React. The hooks and components
+don't ship on this stack; the stores replace the hooks, and you write the components in your
+framework to the contracts on this page:
+
+- bind the stores with your framework's external-store primitive (Vue: `shallowRef` updated in
+  `subscribe`; Svelte: `readable(store.getState(), (set) => store.subscribe(() => set(store.getState())))`;
+  Solid: a signal set in `subscribe`). `createServicesStore(options)` per listing (`start()` when
+  mounted, `stop()` when unmounted), `createBookingFlowStore(service)` per booking surface (the
+  `ServiceDetail` from `fetchServiceBySlug`; `start()` in the browser only — availability is
+  timezone-specific). State in, actions out — exactly the hooks' contracts above;
+- your tiles, slot picker, form, and CTA to the defaults in "What a complete booking site shows" —
+  the shipped `ServiceBookingView.tsx` and `ServicesView.tsx` are readable as behaviour specs.
+
+Routes `/services`, `/services/:slug` (via `fetchServiceBySlug`, null → your 404); dev server on
+4321; a static build goes through `npx @wix/cli@latest release` with `site.outputDirectory`
+pointing at the build folder, an SSR build is hosted by you. Service-page tags from the
+`ServiceDetail` (name, tagLine, description).
+
+### Wiring — static site (`--stack static`, no bundler)
+
+Read the reference files listed above before writing any surface.
+
+`deploy.mjs bookings --stack static --out site` put the REST layer in `site/js/wix/` (browser
+ESM, the `.ts` beside each `.js` for reading). Everything the visitor loads lives under `site/` —
+pages, styles, `js/` — and `wix.config.json`'s `site.outputDirectory` is `"./site"`; the project
+root (config, plan, seed output) is never the upload. Same function names and DTOs as the table
+above, so the contracts on this page hold unchanged: `fetchServices`, `fetchServiceBySlug`,
+`fetchBookingCategories` from `./js/wix/services.js`; `fetchSlots`, `fetchBookingForm`,
+`bookService` from `./js/wix/booking.js`. The state machines ship too: `createServicesStore` from
+`./js/wix/services-store.js` (the listing — `start()` once the page is up, `setActiveCategoryId`)
+and `createBookingFlowStore(service)` from `./js/wix/booking-flow-store.js` (the booking surface —
+`fetchServiceBySlug(slug)` first, then the store: days, week paging, staff filter, `formFields`,
+`setValue`, `canBook`, `book()`). No components ship — you write the rendering in plain JS: one
+render function per surface that reads `getState()`, called from `subscribe`, with the surface's
+controls calling the store's actions. `book()` navigates the full document to the hosted checkout
+for a paid service on its own (`window.location.origin` must be on the OAuth app's allowed domains
+so checkout can return); for a free or pay-in-person service it sets `confirmed`. Pages are
+`services.html` and `service.html?slug=…` (Wix static hosting serves files, not directories — name
+the file and link to it). Set `document.title` and the meta description from the `ServiceDetail`
+once it loads. The visitor token persists in `localStorage` on its own; never mint per page.
+`npx @wix/cli@latest release` uploads `site/`.
+
+### Wiring — server-rendered, another language (Flask, Laravel, Rails, …)
+
+Read the reference files listed above before writing any surface.
+
+Run `deploy.mjs bookings --stack static` in the project folder anyway: `js/wix/` is both the
+browser-side code and the readable spec. Then split by where the call runs. **Reads on the
+server:** port `js/wix/services.ts` and `services-core.ts` to your language — the same three
+functions returning the same DTO shapes as dicts, one anonymous visitor token per process for these
+public reads (mint and refresh per `client.ts`) — and render the listing and the service page in
+your templates to the contracts above, so service names and prices are in the HTML; page tags from
+the `ServiceDetail`. **Booking in the browser:** the booking surface on
+`./js/wix/booking-flow-store.js` with the rendered `ServiceDetail` (a JSON script tag, or
+`fetchServiceBySlug(slug)` from `./js/wix/services.js`), exactly as the static wiring above — the
+browser owns the visitor's token, so the server never handles per-visitor tokens, and the booking,
+its cart, and the checkout redirect are the visitor's. Routes stay `/services`, `/services/<slug>`.
+Add your public https origin to the OAuth app's allowed domains before checkout can return.
+
+**Pre-rendered (Frozen-Flask, Pelican, any static-site generator) → Wix-hosted.** Same port for
+the reads, run at build time with one anonymous token; the generator must emit a page for every
+slug `fetchServices()` returns. Run `deploy.mjs bookings --stack static --out <build dir>` so
+`js/wix/` is inside the output the pages import from, point `site.outputDirectory` at that folder,
+`wix release`. Pages sit at different depths (`/`, `/services/…`): give the templates one base path
+to `js/wix/` (a template variable, or root-relative `/js/wix/…`), never a relative `./js/wix/` — it
+breaks one level down. The frozen listing is the first paint; availability and booking still run
+client-side on the service page through `createBookingFlowStore()` from
+`./js/wix/booking-flow-store.js`, exactly as on a static site, so the booking contract above
+applies. Close with the live URL, the rebuild + release command, and one line for the owner:
+dashboard edits to services reach the site when that command runs; availability and booking are
+live regardless.
+
 ### Wiring — React SPA (Vite etc.)
 
 Import `./styles/global.css` once at the app entry (needs `@tailwindcss/vite` in the vite
 plugins — deploy added the dep). Routes: `/services` → your listing; `/services/:slug` →
-fetch with `fetchServiceBySlug(slug)` client-side, then your booking surface.
+fetch with `fetchServiceBySlug(slug)` client-side, then your booking surface on
+`useBookingFlow(service)`. Deploy wrote the public client id into `wix/config.ts`; nothing else
+to configure.
 
 ## Hard rules
 
@@ -99,31 +236,40 @@ fetch with `fetchServiceBySlug(slug)` client-side, then your booking surface.
 - **The confirmed state must reflect REAL success**: render it only from `confirmed` (set by
   the free/offline branch). A visitor returning from the hosted checkout redirect is NOT a
   success signal — don't fake a confirmation page off the return URL.
-- Theme via the `@theme` tokens; no parallel theme files, no hardcoded palettes.
+- 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.
 - Live data or an honest empty state — never mock services, slots, or availability.
-- Keep the detail page's SEO pieces exactly as shipped.
+- Keep the detail page's SEO pieces exactly as shipped (Astro).
+- **Browsing and booking need no login.** They run on the Wix visitor session the shipped client
+  already holds; don't gate services or booking behind sign-in unless the brief asks for accounts.
+- **Call every hook before any conditional return.** Hooks first, branches after.
 
 ## Point the user to their dashboard
 
-Give the owner the dashboard link plus the Bookings services/calendar pages — the deploy
-step's JSON printed `dashboardUrl`; append `/bookings/services` for service management.
-Taking real online payments needs a premium plan + a connected payment method — mention it.
+Hand the owner these links — `{siteId}` is `siteId` in `wix.config.json` (the deploy JSON prints it as
+`dashboardUrl`); a service id fills the placeholder from the seed result.
+
+| page | `https://manage.wix.com/dashboard/{siteId}/` + |
+|---|---|
+| Services | `bookings/services` |
+| Edit a service | `bookings/services/form/{serviceId}` |
+| Calendar | `bookings/calendar` |
+| Bookings list | `bookings/bookings/bookings-list` |
+| Staff | `bookings/staff` |
+| Availability | `bookings/availability` |
+| Booking form | `bookings/settings/booking-form-page` |
+| Policies | `bookings/settings/policies` |
+
+Completing a booking online — free services included — needs a payment method on the site (Settings →
+Accept payments; "manual payments" is enough for free and pay-in-person); taking real online payments
+also needs a premium plan. Until then `book()` surfaces "the site is not accepting payments" — mention
+it, don't treat it as a code failure.
 
 ## Seeding
 
 Per `seed/SEED.md` — plain-data `plan.json` into `seed-bookings.mjs` from the project root.
 Seed services that exercise the UI (an APPOINTMENT with duration+price, a free one, a CLASS
 with future sessions when it fits the business; an image per service).
-
-## Verify (before declaring done)
-
-- [ ] `/services` renders live services SSR (view-source shows names) through YOUR components;
-      empty catalog shows your honest empty state.
-- [ ] A service page shows day-grouped bookable times; week paging works; the form renders
-      (schema or fallback) and the CTA stays disabled until a slot + all fields are set.
-- [ ] A FREE service books end-to-end: `book()` resolves, your confirmed state renders.
-- [ ] A PAID service redirects to the Wix-hosted checkout.
-- [ ] Service page view-source carries the SEO tags (Astro).
-- [ ] Card/listing/booking surfaces/home are YOUR designs on the tokens; data-layer/hook files
-      unedited.
-- [ ] Dashboard links handed to the owner.

package/skills/wix-headless-fast/references/bookings/app/components/bookings/ServiceBookingView.tsx

@@ -105,7 +105,7 @@ export default function ServiceBookingView({ service }: { service: ServiceDetail
       <div className="mt-6 grid max-w-md gap-3">
         {formFields.map((f) => (
           <label key={f.target} className="block">
-            <span className="mb-1 block text-xs font-semibold uppercase tracking-wider text-muted-foreground">{f.label}</span>
+            <span className="mb-1 block text-xs font-semibold uppercase tracking-wider text-muted-foreground">{f.label}{f.required ? " *" : ""}</span>
             {f.options?.length ? (
               <select
                 value={values[f.target] ?? ""}
@@ -121,6 +121,7 @@ export default function ServiceBookingView({ service }: { service: ServiceDetail
               <input
                 type={f.type === "EMAIL" ? "email" : f.type === "PHONE" ? "tel" : f.type === "NUMBER" ? "number" : f.type === "URL" ? "url" : "text"}
                 value={values[f.target] ?? ""}
+                required={f.required}
                 onChange={(e) => setValue(f.target, e.target.value)}
                 className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none transition-shadow focus:ring-2 focus:ring-primary"
               />

package/skills/wix-headless-fast/references/bookings/app/hooks/bookings/useBookingFlow.ts

@@ -1,138 +1,32 @@
-// The whole booking state machine for one service: availability window (day-grouped slots,
-// week paging, optional staff filter), the schema-driven form, and book(). All correctness
-// (slot scheduleId vs eventId, ANY_RESOURCE, formSubmission, payment option, checkout-or-
-// place) lives in the data layer — this hook orchestrates; you own how it looks.
-import { useEffect, useMemo, useState } from "react";
-import { bookService, fetchBookingForm, fetchSlots } from "../../wix/bookings/booking";
-import type { BookingFormField, BookingResult, ServiceDetail, Slot } from "../../wix/bookings/types";
-
-export interface UseBookingFlow {
-  /** Slots grouped by day, in order — [{ dayKey, dayLabel, slots }]. null while loading. */
-  days: { dayKey: string; dayLabel: string; slots: Slot[] }[] | null;
-  /** The 7-day window start; page with nextWeek/prevWeek (prev clamps to today). */
-  windowStart: Date;
-  nextWeek: () => void;
-  prevWeek: () => void;
-  /** Staff filter — render a picker only when service.staff.length > 1. */
-  staffId: string | undefined;
-  setStaffId: (id: string | undefined) => void;
-  selectedSlot: Slot | null;
-  setSelectedSlot: (s: Slot | null) => void;
-  /** Schema-driven form fields (never empty — contact basics fallback). */
-  formFields: BookingFormField[];
-  values: Record<string, string>;
-  setValue: (target: string, value: string) => void;
-  /** True when a slot is selected and every field has a value. */
-  canBook: boolean;
-  /** Books the selected slot. On "redirect" the browser is already navigating. */
-  book: () => Promise<BookingResult>;
-  booking: boolean;
-  /** Set after a free/offline booking completes. */
-  confirmed: BookingResult | null;
-  error: string | null;
-}
-
-const dayLabel = (dayKey: string): string => {
-  try {
-    return new Date(`${dayKey}T12:00:00`).toLocaleDateString(undefined, {
-      weekday: "short",
-      month: "short",
-      day: "numeric",
-    });
-  } catch {
-    return dayKey;
-  }
-};
+// 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: availability window (day-grouped
+// slots, week paging, optional staff filter), the schema-driven form, and book(). All correctness
+// (slot scheduleId vs eventId, ANY_RESOURCE, formSubmission, payment option, checkout-or-place)
+// 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" | "setStaffId" | "setSelectedSlot" | "setValue" | "book">;
 
 export function useBookingFlow(service: ServiceDetail): UseBookingFlow {
-  const [windowStart, setWindowStart] = useState<Date>(() => new Date());
-  const [staffId, setStaffId] = useState<string | undefined>(undefined);
-  const [slots, setSlots] = useState<Slot[] | null>(null);
-  const [selectedSlot, setSelectedSlot] = useState<Slot | null>(null);
-  const [formFields, setFormFields] = useState<BookingFormField[]>([]);
-  const [values, setValues] = useState<Record<string, string>>({});
-  const [booking, setBooking] = useState(false);
-  const [confirmed, setConfirmed] = useState<BookingResult | null>(null);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    let alive = true;
-    setSlots(null);
-    setSelectedSlot(null);
-    fetchSlots(service, { from: windowStart, days: 7, staffId })
-      .then((s) => alive && setSlots(s))
-      .catch((e) => {
-        if (!alive) return;
-        setSlots([]);
-        setError(e instanceof Error ? e.message : String(e));
-      });
-    return () => {
-      alive = false;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [service.id, windowStart, staffId]);
-
+  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(() => {
-    let alive = true;
-    fetchBookingForm(service.formId).then((f) => alive && setFormFields(f));
-    return () => {
-      alive = false;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [service.formId]);
-
-  const days = useMemo(() => {
-    if (slots === null) return null;
-    const byDay = new Map<string, Slot[]>();
-    for (const s of slots) byDay.set(s.dayKey, [...(byDay.get(s.dayKey) ?? []), s]);
-    return [...byDay.entries()]
-      .sort(([a], [b]) => a.localeCompare(b))
-      .map(([dayKey, daySlots]) => ({ dayKey, dayLabel: dayLabel(dayKey), slots: daySlots }));
-  }, [slots]);
-
-  const canBook =
-    !!selectedSlot && formFields.every((f) => (values[f.target] ?? "").trim().length > 0);
-
-  async function book(): Promise<BookingResult> {
-    if (!selectedSlot) throw new Error("Pick a time first.");
-    setBooking(true);
-    setError(null);
-    try {
-      const result = await bookService(service, selectedSlot, values, { staffId });
-      if (result.kind === "redirect") {
-        window.location.href = result.url;
-      } else {
-        setConfirmed(result);
-      }
-      return result;
-    } catch (e) {
-      setError(e instanceof Error ? e.message : String(e));
-      throw e;
-    } finally {
-      setBooking(false);
-    }
-  }
-
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
   return {
-    days,
-    windowStart,
-    nextWeek: () => setWindowStart((d) => new Date(d.getTime() + 7 * 24 * 3600 * 1000)),
-    prevWeek: () =>
-      setWindowStart((d) => {
-        const prev = new Date(d.getTime() - 7 * 24 * 3600 * 1000);
-        return prev < new Date() ? new Date() : prev;
-      }),
-    staffId,
-    setStaffId,
-    selectedSlot,
-    setSelectedSlot,
-    formFields,
-    values,
-    setValue: (target, value) => setValues((v) => ({ ...v, [target]: value })),
-    canBook,
-    book,
-    booking,
-    confirmed,
-    error,
+    ...state,
+    nextWeek: store.nextWeek,
+    prevWeek: store.prevWeek,
+    setStaffId: store.setStaffId,
+    setSelectedSlot: store.setSelectedSlot,
+    setValue: store.setValue,
+    book: store.book,
   };
 }