@wix/agent-skills 1.16.3 → 1.18.0

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

@@ -0,0 +1,78 @@
+# Portfolio — seeding
+
+Seed by **running `seed-portfolio.mjs` with a plan file** — don't hand-write the REST calls.
+The script mints its own site token via the Wix CLI (logged-in session + `wix.config.json`
+required), installs the Portfolio app if needed, and creates everything in the right order:
+collections first (a project's `collectionIds` are NOT validated — a wrong id silently
+orphans the project), then projects, gallery items, and covers.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/references/portfolio/seed/seed-portfolio.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 2 collections × 2 projects
+each** (the seed shows the shape; the owner adds the rest in the dashboard) and make them
+exercise the UI: every collection and project gets a cover, every project gets 2–3 gallery
+`items` (a portfolio without images looks broken), and a couple of projects get `details`
+rows (Role, Year, Client…).
+
+```json
+{
+  "collections": [
+    { "title": "Brand Identity", "description": "Logo systems and visual identities.",
+      "coverImageUrl": "https://…" },
+    { "title": "Editorial", "description": "Print and digital editorial design.",
+      "coverImageUrl": "https://…" }
+  ],
+  "projects": [
+    { "title": "Northwind Rebrand", "description": "Full identity refresh for a logistics firm.",
+      "collection": "Brand Identity",
+      "details": [ { "label": "Role", "text": "Brand & Art Direction" }, { "label": "Year", "text": "2025" } ],
+      "coverImageUrl": "https://…",
+      "items": [
+        { "sortOrder": 1, "title": "Logo system", "imageUrl": "https://…" },
+        { "sortOrder": 2, "title": "Stationery", "imageUrl": "https://…" }
+      ] },
+    { "title": "Harbor Coffee", "description": "Packaging and label suite.",
+      "collection": "Brand Identity", "coverImageUrl": "https://…",
+      "items": [ { "sortOrder": 1, "title": "Label set", "imageUrl": "https://…" } ] },
+    { "title": "Field Notes Quarterly", "description": "Magazine layout and typography.",
+      "collection": "Editorial", "coverImageUrl": "https://…",
+      "items": [ { "sortOrder": 1, "title": "Spread", "imageUrl": "https://…" } ] },
+    { "title": "City Guides", "description": "Travel series covers.",
+      "collection": "Editorial", "coverImageUrl": "https://…",
+      "items": [ { "sortOrder": 1, "title": "Covers", "imageUrl": "https://…" } ] }
+  ]
+}
+```
+
+- `collection` — a collection **title from this plan**; resolved to its created id. A project
+  without one belongs to no collection (reachable only from an all-projects list).
+- `details` — optional `[{ label, text }]` rows; render on the project page. Omit for none.
+- Every image field's default is a prompt (`coverImagePrompt` / `items[].imagePrompt` —
+  AI-generated, ~1 Wix AI credit per image, account-billed): brand-contextual — subject,
+  aesthetic/mood, palette, lighting — always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied
+  use a path (`coverImagePath` / `items[].imagePath` — a file on this machine, uploaded to
+  Wix Media) or a url (`coverImageUrl` / `items[].imageUrl` — their own hosted URL; verify it
+  with `curl -sI` → 200) — never a stock-photo or guessed URL. All images —
+  covers and gallery items alike — resolve in one parallel wave and never block the seed; a
+  failed image skips just that item/cover. The **cover** is the
+  listing thumbnail; **items** are the detail-page gallery — separate entities, both wanted.
+  If a project has only a cover, reuse its url as item 1 so the gallery isn't empty.
+- `sortOrder` (1, 2, 3…) sets the gallery render order.
+- `hidden` defaults to shown — omit it; send `hidden: true` only to hide an entity.
+- Gallery items seed as images only; the owner adds videos in the dashboard.
+- A fresh Portfolio install ships sample content ("My Portfolio" + sample projects). **Seeding
+  is additive — never delete or overwrite existing content**; if removing the samples seems
+  wanted, ask the owner first.
+
+## Escape hatch — individual functions
+`setupPortfolio` composes exported steps — `installPortfolioApp`, `createCollections`,
+`createProjects`, `importImage`, `attachProjectCovers`, `attachCollectionCovers`,
+`createProjectItems`, `listCollections`, `listProjects`, plus `makeCtx()` — import them only
+for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; the
+authoritative source recipe is `wix-headless/references/inline-recipes/setup-portfolio.md`.

package/skills/wix-headless-fast/references/portfolio/seed/seed-portfolio.mjs

@@ -0,0 +1,258 @@
+// Portfolio seed — a BUILD-TIME script, never shipped in the app. Run from the project root
+// (where wix.config.json lives) with a plan file:
+//
+//   node <SKILL_ROOT>/references/portfolio/seed/seed-portfolio.mjs plan.json
+//
+// It mints its own site token via the Wix CLI, installs the Wix Portfolio app if needed,
+// creates collections then projects (collections FIRST — a project's collectionIds are NOT
+// validated, so a wrong id is silently accepted and orphans the project), creates each
+// project's gallery items, and imports+attaches cover images. Prints a JSON result to stdout.
+//
+// Plan shape (see SEED.md):
+//   { "collections": [{ "title", "description"?, "hidden"?, "coverImageUrl"? | "coverImagePrompt"? }],
+//     "projects":    [{ "title", "description"?, "hidden"?,
+//                       "collection"? (title),        // resolved to that collection's id
+//                       "details"?: [{ "label", "text" }],
+//                       "coverImageUrl"? | "coverImagePrompt"?,
+//                       "items"?: [{ "sortOrder", "title"?, "imageUrl" | "imagePrompt" }] }] }
+//
+// Seeding is ADDITIVE — never deletes or overwrites existing content. A fresh Portfolio
+// install ships its own sample content ("My Portfolio" + sample projects); removing it is the
+// owner's call, not this script's. Unexpected shapes → read the live API reference;
+// authoritative source recipe: wix-headless/references/inline-recipes/setup-portfolio.md.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolveItemImages } from "../../shared/seed/images.mjs";
+
+const API = "https://www.wixapis.com";
+const PORTFOLIO_APP_ID = "d90652a2-f5a1-4c7c-84c4-d4cdcc41f130";
+
+export function makeCtx({ cwd = process.cwd() } = {}) {
+  const config = JSON.parse(readFileSync(`${cwd}/wix.config.json`, "utf8"));
+  const siteId = config.siteId ?? config.projectId;
+  if (!siteId) throw new Error("wix.config.json has no siteId — is this a Wix CLI project?");
+  const token = execFileSync("npx", ["@wix/cli@latest", "token", "--site", siteId], {
+    encoding: "utf8",
+    cwd,
+  }).trim();
+  if (!token) throw new Error("The Wix CLI returned no token — run `npx @wix/cli@latest login` first.");
+  return { token, siteId };
+}
+
+async function req(ctx, path, { method = "POST", body } = {}) {
+  const res = await fetch(API + path, {
+    method,
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      "wix-site-id": ctx.siteId,
+      "Content-Type": "application/json",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
+  return json;
+}
+
+// ---- operations ----------------------------------------------------------------------------------
+
+// Idempotent — re-installing returns 200.
+// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+export async function installPortfolioApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId: PORTFOLIO_APP_ID, enabled: true },
+    } });
+  } catch {
+    /* already installed is fine */
+  }
+}
+
+// Read-only listing helpers (partial re-seeds, verification).
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/list-collections.md
+export async function listCollections(ctx) {
+  const r = await req(ctx, "/portfolio/v1/collections", { method: "GET" });
+  return (r.collections ?? []).map((c) => ({ id: c.id, title: c.title, slug: c.slug }));
+}
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/list-projects.md
+export async function listProjects(ctx) {
+  const r = await req(ctx, "/portfolio/v1/projects", { method: "GET" });
+  return (r.projects ?? []).map((p) => ({ id: p.id, title: p.title, slug: p.slug }));
+}
+
+// STEP 1 — collections. The display name is `title`, not `name`; `slug` auto-generates from
+// the title; `hidden` defaults to false = shown (omit it — send true only to hide). No
+// bulk-create: one call per collection.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/create-collection.md
+export async function createCollections(ctx, collections) {
+  const out = [];
+  for (const c of collections) {
+    const body = { collection: { title: c.title, description: c.description } };
+    if (c.hidden) body.collection.hidden = true;
+    const r = await req(ctx, "/portfolio/v1/collections", { body });
+    out.push({ id: r.collection?.id, slug: r.collection?.slug, revision: r.collection?.revision });
+  }
+  return out;
+}
+
+// STEP 2 — projects, AFTER collections: collectionIds must hold real ids from createCollections
+// (they are NOT validated — a wrong/missing id silently orphans the project). `details` is an
+// optional [{ label, text }] array. No bulk-create: one call per project.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/create-project.md
+export async function createProjects(ctx, projects) {
+  const out = [];
+  for (const p of projects) {
+    const project = {
+      title: p.title,
+      description: p.description,
+      collectionIds: p.collectionIds ?? [],
+    };
+    if (p.details) project.details = p.details;
+    if (p.hidden) project.hidden = true;
+    const r = await req(ctx, "/portfolio/v1/projects", { body: { project } });
+    out.push({ id: r.project?.id, slug: r.project?.slug, revision: r.project?.revision });
+  }
+  return out;
+}
+
+// Portfolio binds covers + gallery items by Wix Media file ID — an external url must be
+// imported first (a raw url renders nothing); a plan `imagePrompt`/`coverImagePrompt` is
+// generated (Wix AI, 1 credit) then imported. Both live in the shared util (parallel,
+// resilient, never blocks the seed).
+export { importImage } from "../../shared/seed/images.mjs";
+
+// Cover = the listing-card thumbnail. PATCH per entity, echoing the current revision (missing/
+// stale revision fails); height + width are required alongside the imported file id.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/projects/update-project.md
+export async function attachProjectCovers(ctx, items) {
+  for (const it of items) {
+    await req(ctx, `/portfolio/v1/projects/${it.id}`, {
+      method: "PATCH",
+      body: { project: { id: it.id, revision: it.revision, coverImage: { imageInfo: { id: it.imageId, height: it.height, width: it.width } } } },
+    });
+  }
+}
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/collections/update-collection.md
+export async function attachCollectionCovers(ctx, items) {
+  for (const it of items) {
+    await req(ctx, `/portfolio/v1/collections/${it.id}`, {
+      method: "PATCH",
+      body: { collection: { id: it.id, revision: it.revision, coverImage: { imageInfo: { id: it.imageId, height: it.height, width: it.width } } } },
+    });
+  }
+}
+
+// The detail-page gallery is a SEPARATE `item` entity — one POST per image; sortOrder (1,2,3…)
+// sets render order. Lowercase `items` — `/Items` 404s. There is NO public list endpoint.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/portfolio/project-items/create-project-item.md
+export async function createProjectItems(ctx, items) {
+  const out = [];
+  for (const it of items) {
+    const r = await req(ctx, "/portfolio/v1/items", {
+      body: { item: { projectId: it.projectId, sortOrder: it.sortOrder, title: it.title, image: { imageInfo: { id: it.imageId, height: it.height, width: it.width } } } },
+    });
+    out.push({ id: r.item?.id });
+  }
+  return out;
+}
+
+/**
+ * ONE-CALL seed: install → collections → projects (into collections) → gallery items →
+ * covers, ids threaded in memory. The default path.
+ */
+export async function setupPortfolio(ctx, { collections = [], projects = [] } = {}) {
+  await installPortfolioApp(ctx);
+
+  const cols = await createCollections(ctx, collections);
+  const idByTitle = new Map(collections.map((c, i) => [c.title, cols[i].id]));
+
+  const projs = await createProjects(
+    ctx,
+    projects.map((p) => ({
+      title: p.title,
+      description: p.description,
+      details: p.details,
+      hidden: p.hidden,
+      collectionIds: p.collection ? [idByTitle.get(p.collection)].filter(Boolean) : [],
+    })),
+  );
+
+  // Pass 2 — images: gallery items + project covers + collection covers, flattened into ONE
+  // parallel wave (import by url / generate by prompt), then mapped back to each attach.
+  // A failed image skips just that item/cover; the seed's exit never depends on images.
+  const specs = [];
+  const galleryRefs = [];
+  projects.forEach((p, pi) => {
+    for (const it of p.items ?? []) {
+      galleryRefs.push({ pi, it, spec: specs.length });
+      specs.push({ path: it.imagePath, url: it.imageUrl, prompt: it.imagePrompt, displayName: `${it.title || "item"}.png` });
+    }
+  });
+  const projCoverAt = specs.length;
+  projects.forEach((p) => specs.push({ path: p.coverImagePath, url: p.coverImageUrl, prompt: p.coverImagePrompt, displayName: `${p.title || "project"}-cover.png` }));
+  const colCoverAt = specs.length;
+  collections.forEach((c) => specs.push({ path: c.coverImagePath, url: c.coverImageUrl, prompt: c.coverImagePrompt, displayName: `${c.title || "collection"}-cover.png` }));
+  const files = await resolveItemImages(ctx, specs);
+  const dims = { height: 1024, width: 1024 };
+
+  const itemsFlat = galleryRefs
+    .map(({ pi, it, spec }) => (files[spec] && projs[pi]?.id
+      ? { projectId: projs[pi].id, sortOrder: it.sortOrder, title: it.title, imageId: files[spec].id, ...dims }
+      : null))
+    .filter(Boolean);
+  let items = [];
+  try {
+    if (itemsFlat.length) items = await createProjectItems(ctx, itemsFlat);
+  } catch {
+    /* the remaining gallery items stay unseeded */
+  }
+
+  const projCovers = projs
+    .map((p, i) => (files[projCoverAt + i] && p.id
+      ? { id: p.id, revision: p.revision, imageId: files[projCoverAt + i].id, ...dims }
+      : null))
+    .filter(Boolean);
+  const colCovers = cols
+    .map((c, i) => (files[colCoverAt + i] && c.id
+      ? { id: c.id, revision: c.revision, imageId: files[colCoverAt + i].id, ...dims }
+      : null))
+    .filter(Boolean);
+  let coversAttached = 0;
+  try {
+    if (projCovers.length) { await attachProjectCovers(ctx, projCovers); coversAttached += projCovers.length; }
+  } catch {
+    /* those projects stay cover-less */
+  }
+  try {
+    if (colCovers.length) { await attachCollectionCovers(ctx, colCovers); coversAttached += colCovers.length; }
+  } catch {
+    /* those collections stay cover-less */
+  }
+
+  return {
+    collections: cols,
+    projects: projs,
+    itemsCreated: items.length,
+    coversAttached,
+  };
+}
+
+// ---- CLI entry ----------------------------------------------------------------------------------
+
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (invokedDirectly) {
+  const planPath = process.argv[2];
+  if (!planPath) {
+    console.error("usage: node seed-portfolio.mjs <plan.json>   (run from the project root)");
+    process.exit(1);
+  }
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  const ctx = makeCtx();
+  setupPortfolio(ctx, plan)
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+}

package/skills/wix-headless-fast/references/pricing-plans/INSTRUCTIONS.md

@@ -0,0 +1,133 @@
+# Pricing Plans — playbook
+
+The plans machinery ships as files — plan reads (grid + by-slug) and the hosted purchase
+redirect, typed end-to-end. **The presentation is yours**: you design and implement the plan
+card, the pricing grid, and the plan detail surface on the shipped hooks/DTOs, plus the home
+page and the brand. You never write purchase logic; you never skip designing.
+
+## 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.
+
+| 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/pricing-plans/types.ts` | the DTOs (`PlanSummary`, `PlanDetail`) — contracts below |
+| `wix/pricing-plans/plans.ts` | `fetchPlans`, `fetchPlanBySlug` |
+| `wix/pricing-plans/purchase.ts` | `purchasePlan` — the hosted-checkout redirect session lives here |
+| `hooks/pricing-plans/usePlans.ts` | plans listing — contract below |
+| `hooks/pricing-plans/usePlanPurchase.ts` | the purchase action — contract below |
+| `components/pricing-plans/PlansView.tsx` (+ `PlanCard`) · `PlanDetailView.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) |
+
+Astro stack additionally gets:
+
+| file | what it is |
+|---|---|
+| `layouts/SiteLayout.astro` | site chrome — **yours to brand** (keep the `seo-tags` slot + global.css import). If another vertical is also deployed, its layout won — add a Plans nav link there |
+| `pages/plans.astro` | SSR pricing grid — **keep the frontmatter**, swap the island import to YOUR component |
+| `pages/plans/[slug].astro` | SSR plan detail — **keep the frontmatter** (plain `<title>`/`<meta>` from the DTO: Pricing Plans has no owner-editable SEO item type); swap the island import |
+
+## What you build — the design job
+
+1. **The plan card + pricing grid** — your tier card (name, price + billing cadence, trial
+   badge, perks list, Subscribe CTA — only when `buyable`) and grid rhythm (a highlighted
+   recommended tier is a classic), with skeletons while loading and an honest empty state —
+   on `usePlans` + `usePlanPurchase`.
+2. **The plan detail surface** — the full pitch: price block, perks, terms & conditions
+   (plain text — render pre-wrap), subscribe CTA — on `usePlanPurchase` (the plan itself
+   arrives as an SSR-fetched DTO prop).
+3. **The home page** — hero, a featured-plans strip (fetch in frontmatter → your components),
+   brand story.
+
+Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass).
+Style everything with Tailwind utilities on the tokens.
+
+### The contracts your components consume
+
+```ts
+// PlanSummary (cards) — display-ready:
+// { id, slug, name, description, price /* "$29.00" | "Free" */, free,
+//   billing /* "per month" | "every 3 months" | "one-time" | "" (free) */,
+//   freeTrialDays: number|null, perks: string[], buyable, imageUrl /* "" when none */ }
+// PlanDetail adds: termsAndConditions (plain text; "" when not set).
+
+// usePlans({ initialPlans? }) →
+// { plans: PlanSummary[]|null /* null = loading → skeletons */, error }
+
+// usePlanPurchase() →
+// { purchase(planId, { thankYouPageUrl?, postFlowUrl? }?): Promise<void>,
+//     // resolves as the browser navigates to the Wix-hosted checkout;
+//     // rejects with a visitor-facing message — surface it
+//   purchasingId,   // plan id in flight (null when idle) — key the CTA spinner off it
+//   error }
+```
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass — merge into the
+   other vertical's layout instead if both are deployed).
+2. Write your components under `src/components/pricing-plans/` (new names — don't overwrite
+   the references), swap the island imports in `pages/plans.astro` and
+   `pages/plans/[slug].astro`. Both islands: `client:load` with the SSR DTO props. **Author
+   your surfaces in as few messages as possible** — batch multiple Writes per message.
+3. Write `pages/index.astro` (home) — it exists from the scaffold; Read it before overwriting.
+
+### 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: `/plans` → your grid; `/plans/:slug` → fetch with
+`fetchPlanBySlug(slug)` client-side, then your detail surface (null → your not-found state).
+
+## Hard rules
+
+- **Purchase only through the shipped exports** — `usePlanPurchase`/`purchasePlan` own the
+  hosted redirect session. Never hand-build a checkout URL, never call
+  `orders.createOnlineOrder` (member-only, and it leaves payment unhandled), never mark
+  anything paid.
+- **Purchasing is members-only, and that's fine as-is**: the hosted flow handles member
+  login/signup, the order form, and payment, then returns to your site. Don't build a login
+  gate in front of the CTA.
+- **No success theater.** Returning from checkout is NOT a success signal — `postFlowUrl` is
+  hit on abandon too. Success arrives only at a `thankYouPageUrl` you pass, as
+  `?planOrderId=<GUID>`; if you build a thank-you page, read that param — never fake a
+  confirmation off the mere return.
+- **Prices are display-only.** `price`/`billing` come pre-formatted; never compute a charge,
+  discount, or proration — Wix settles price, tax, and schedule at the hosted checkout.
+- **Show the Subscribe CTA only when `buyable`** — a PUBLIC plan can be merchant-assigned.
+- Theme via the `@theme` tokens; no parallel theme files, no hardcoded palettes.
+- Live data or an honest empty state — never mock plans, prices, or perks.
+
+## Out of scope (don't improvise these)
+
+Member-gated surfaces — a "my plans" page, the member's orders (`orders.memberListOrders`),
+cancel/pause flows, and booking a covered bookings service with a membership — require a
+logged-in member session this skill doesn't ship yet. Subscribers manage their plan through
+Wix's emails and hosted member flows. If the user asks for a member area, route to
+`wix-headless` (members recipes) rather than shipping code that returns nothing for visitors.
+
+## Point the user to their dashboard
+
+Give the owner the dashboard link plus the Pricing Plans page — the deploy step's JSON
+printed `dashboardUrl`; append `/pricing-plans` for plan management (edit plans, connect
+plans to content, see orders). Taking real payments needs a premium plan + a connected
+payment method — mention it.
+
+## Seeding
+
+Per `seed/SEED.md` — plain-data `plan.json` into `seed-pricing-plans.mjs` from the project
+root. Seed a tier ladder that exercises the UI (a free tier, a monthly, a yearly or
+one-time; 3–4 perks each).
+
+## Verify (before declaring done)
+
+- [ ] `/plans` renders live plans SSR (view-source shows names) through YOUR components;
+      empty catalog shows your honest empty state.
+- [ ] Every price shape reads right: free ("Free", no cadence), recurring ("$29.00 per
+      month"), one-time; Subscribe renders only on `buyable` plans.
+- [ ] A plan page loads by slug and 404s (Astro) / shows not-found (SPA) on a bad slug.
+- [ ] Subscribe redirects to the Wix-hosted checkout (login/signup + payment live there).
+- [ ] Card/grid/detail/home are YOUR designs on the tokens; data-layer/hook files unedited.
+- [ ] Dashboard links handed to the owner.

package/skills/wix-headless-fast/references/pricing-plans/app/components/pricing-plans/PlanDetailView.tsx

@@ -0,0 +1,58 @@
+// REFERENCE detail surface: price/billing block + perks + terms + subscribe CTA, on the
+// @theme tokens. Correct and complete; per the skill's model you design and build your own
+// on usePlanPurchase (the plan itself arrives as an SSR-fetched DTO prop).
+import { usePlanPurchase } from "../../hooks/pricing-plans/usePlanPurchase";
+import type { PlanDetail } from "../../wix/pricing-plans/types";
+
+export default function PlanDetailView({ plan }: { plan: PlanDetail }) {
+  const { purchase, purchasingId, error } = usePlanPurchase();
+  const purchasing = purchasingId === plan.id;
+
+  return (
+    <div>
+      <p>
+        <span className="text-4xl font-bold tracking-tight text-foreground">{plan.price}</span>
+        {plan.billing && <span className="ml-2 text-muted-foreground">{plan.billing}</span>}
+      </p>
+      {plan.freeTrialDays !== null && (
+        <p className="mt-1 text-sm text-muted-foreground">{plan.freeTrialDays}-day free trial</p>
+      )}
+
+      {plan.perks.length > 0 && (
+        <ul className="mt-6 space-y-2.5">
+          {plan.perks.map((perk) => (
+            <li key={perk} className="flex gap-2 text-sm text-foreground">
+              <span className="text-muted-foreground" aria-hidden="true">
+                ✓
+              </span>
+              <span>{perk}</span>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {error && <p className="mt-4 text-sm text-red-600">{error}</p>}
+      {plan.buyable ? (
+        <button
+          type="button"
+          disabled={purchasing}
+          onClick={() => void purchase(plan.id).catch(() => {})}
+          className="mt-6 rounded-full bg-primary px-8 py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
+        >
+          {purchasing ? "Redirecting…" : plan.free ? "Get this plan" : `Subscribe · ${plan.price}`}
+        </button>
+      ) : (
+        <p className="mt-6 text-sm text-muted-foreground">This plan is assigned by the site owner.</p>
+      )}
+
+      {plan.termsAndConditions && (
+        <div className="mt-10 border-t border-border pt-5">
+          <p className="eyebrow">Terms &amp; conditions</p>
+          <p className="mt-2 whitespace-pre-wrap text-sm leading-relaxed text-muted-foreground">
+            {plan.termsAndConditions}
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}

package/skills/wix-headless-fast/references/pricing-plans/app/components/pricing-plans/PlansView.tsx

@@ -0,0 +1,126 @@
+// REFERENCE pricing surface: plan cards in a grid on the @theme tokens. Correct and
+// complete; per the skill's model you design and build your own on usePlans +
+// usePlanPurchase.
+import type { ComponentType, ReactNode } from "react";
+import { usePlans } from "../../hooks/pricing-plans/usePlans";
+import { usePlanPurchase } from "../../hooks/pricing-plans/usePlanPurchase";
+import type { PlanSummary } from "../../wix/pricing-plans/types";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+export interface PlanCardProps {
+  plan: PlanSummary;
+  onSubscribe: (planId: string) => void;
+  purchasing: boolean;
+  planHref?: (slug: string) => string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+export function PlanCard({
+  plan,
+  onSubscribe,
+  purchasing,
+  planHref = (slug) => `/plans/${slug}`,
+  LinkComponent = PlainLink,
+}: PlanCardProps) {
+  return (
+    <div className="flex h-full flex-col rounded-lg border border-border bg-background p-6">
+      <p className="text-base font-semibold text-foreground">{plan.name}</p>
+      {plan.description && <p className="mt-1 text-sm text-muted-foreground">{plan.description}</p>}
+      <p className="mt-4">
+        <span className="text-3xl font-bold tracking-tight text-foreground">{plan.price}</span>
+        {plan.billing && <span className="ml-1.5 text-sm text-muted-foreground">{plan.billing}</span>}
+      </p>
+      {plan.freeTrialDays !== null && (
+        <p className="mt-1 text-xs font-medium text-muted-foreground">{plan.freeTrialDays}-day free trial</p>
+      )}
+      {plan.perks.length > 0 && (
+        <ul className="mt-4 space-y-2">
+          {plan.perks.map((perk) => (
+            <li key={perk} className="flex gap-2 text-sm text-foreground">
+              <span className="text-muted-foreground" aria-hidden="true">
+                ✓
+              </span>
+              <span>{perk}</span>
+            </li>
+          ))}
+        </ul>
+      )}
+      <div className="mt-auto grid gap-2 pt-6">
+        {plan.buyable && (
+          <button
+            type="button"
+            disabled={purchasing}
+            onClick={() => onSubscribe(plan.id)}
+            className="rounded-full bg-primary px-6 py-2.5 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
+          >
+            {purchasing ? "Redirecting…" : "Subscribe"}
+          </button>
+        )}
+        <LinkComponent
+          href={planHref(plan.slug)}
+          className="rounded-full border border-border px-6 py-2.5 text-center text-sm font-semibold text-foreground no-underline transition-colors hover:bg-secondary"
+        >
+          View details
+        </LinkComponent>
+      </div>
+    </div>
+  );
+}
+
+export interface PlansViewProps {
+  initialPlans?: PlanSummary[];
+  emptyMessage?: string;
+  planHref?: PlanCardProps["planHref"];
+  LinkComponent?: ComponentType<LinkLikeProps>;
+  CardComponent?: ComponentType<PlanCardProps>;
+}
+
+export default function PlansView({
+  initialPlans,
+  emptyMessage = "No plans yet — check back soon.",
+  planHref,
+  LinkComponent,
+  CardComponent = PlanCard,
+}: PlansViewProps) {
+  const { plans, error } = usePlans({ initialPlans });
+  const { purchase, purchasingId, error: purchaseError } = usePlanPurchase();
+
+  return (
+    <div>
+      {(error ?? purchaseError) && <p className="mb-4 text-sm text-red-600">{error ?? purchaseError}</p>}
+      {plans === null ? (
+        <div className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3" aria-busy="true">
+          {Array.from({ length: 3 }, (_, i) => (
+            <div key={i} className="h-80 animate-pulse rounded-lg bg-secondary" />
+          ))}
+        </div>
+      ) : plans.length === 0 ? (
+        <p className="py-16 text-center text-muted-foreground">{emptyMessage}</p>
+      ) : (
+        <div className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
+          {plans.map((p) => (
+            <CardComponent
+              key={p.id}
+              plan={p}
+              onSubscribe={(id) => void purchase(id).catch(() => {})}
+              purchasing={purchasingId === p.id}
+              planHref={planHref}
+              LinkComponent={LinkComponent}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}