@wix/agent-skills 1.19.2 → 1.20.0

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -107,6 +107,7 @@ export default function ProductCard({ product }) {
     promoBadge,       // { type: 'ribbon', label } | null — the primary ribbon, for a single-badge slot
     priceDisplay,     // the price the buyer pays (discounted when an automatic discount applies), or a min–max range
     compareAtDisplay, // struck "was" price | null — never beside a range (the PDP shows the real comparison)
+    teaser,           // plain-text description for the tile — plainDescription is HTML; never render it raw on a card
     colors,           // hex colour strings
     optionLabel,      // e.g. "3 sizes · 2 materials", or ""
     isQuickAddable,   // no product options and not sold out; does NOT check modifiers
@@ -265,7 +266,9 @@ The product-detail example above provides both groups:
 // Text modifier: d.setModifier(m.key, text)
 ```
 Retired option choices are filtered out. Respect each choice's `inStock` and modifier's
-`mandatory` flag; the hook supplies colour values and selection state without prescribing layout.
+`mandatory` flag. A choice with `isColorSwatch` renders as a **color swatch** filled with its
+`colorCode` and labelled by its name — not as a text pill; the hook supplies the values and selection
+state without prescribing the rest of the layout.
 
 ### Images
 `useProductCard` returns normalized `image`/`hoverImage`, and `useProductDetail` returns normalized
@@ -341,13 +344,26 @@ currency; `convertedAmount` is in display currency. Format
 back to `USD`). Use `summary.priceSummary.subtotal` (after discounts) with `cart.subtotal` as the
 fallback while `summary` is null, a Discount row only when `priceSummary.discount` is above zero, and
 line `pricing.totalPrice`; never sum lines yourself. Shipping and tax resolve at checkout — say
-"calculated at checkout", never a hardcoded charge, threshold, or a made-up zero.
+"calculated at checkout", never a hardcoded charge, threshold, or a made-up zero. The estimate's
+`priceSummary.delivery`, `tax`, and `additionalFees` read `"0"` when nothing was calculated (verified
+live), so a zero there is not "Free shipping" or "No tax" — don't render those rows from the estimate.
 
 Line `quantityInfo.confirmedQuantity` is the current quantity; `availableQuantity` caps increases
 when finite. `status` can be `IN_STOCK`, `PARTIALLY_IN_STOCK`, `OUT_OF_STOCK`, or
 `REMOVED_FROM_CATALOG`; surface unavailable lines and prevent checkout until resolved.
 
 ## Routes and provider
+
+> **The template decides this step, and `src/routes/__root.jsx` is the question to ask first.**
+> Present → TanStack Start, which mounts these pages as route files at the end of this step; absent
+> → React Router, which the wiring below is written for. Ask in that order: an `src/App.jsx` can
+> exist on a TanStack app because an agent created one, and `__root.jsx` is never there by mistake.
+> The installed `src/lib/nav.js` defaults to the React Router adapter, so on TanStack swap it:
+> [both patterns](../_shared/routing.md).
+>
+> **Import `Link`, `useParams` and friends from `@/lib/nav` in the pages you write too** — same
+> names as the router exports, and nothing you write is pinned to one template.
+
 **No shipped source reads needed to wire this.** `CartDrawer` and `CartButton`
 are default exports that take **no props**. `CartProvider` is a named export accepting `children`;
 wire these exactly as shown below.
@@ -434,6 +450,31 @@ function Layout() {
 }
 ```
 
+
+### TanStack Start template — the same pages, mounted as files
+
+Chrome (header, footer, the fixed banner region described above) goes in `src/routes/__root.jsx`
+around its `<Outlet/>`, and any provider this vertical asks for wraps that `<Outlet/>` once. Each
+route is a two-line file; shipped pages stay in `src/pages/` untouched.
+
+| route | file | component |
+|---|---|---|
+| `/` | `src/routes/index.jsx` | `Home` |
+| `/shop` | `src/routes/shop.jsx` | `Shop` |
+| `/product/:slug` | `src/routes/product.$slug.jsx` | `ProductDetail` |
+
+```jsx
+// src/routes/shop.jsx
+import { createFileRoute } from "@tanstack/react-router";
+import Shop from "@/pages/Shop";
+
+export const Route = createFileRoute("/shop")({ component: Shop });
+```
+
+Path params are `$name` in both the filename and the route path; `useParams()` from `@/lib/nav`
+reads them unchanged. Full pattern, including `ssr: false` for per-user routes:
+[`../_shared/routing.md`](../_shared/routing.md).
+
 ## What a complete storefront shows
 
 The wiring above is necessary, not sufficient. These are defaults for when the brief doesn't say

package/skills/wix-vibe-headless/references/storefront/app/hooks/useProductCard.js

@@ -4,7 +4,7 @@
 // without touching the badge logic, price rules, or colour-dot extraction.
 //
 // Usage:
-//   const { isSoldOut, leftBadges, ribbons, promoBadge, priceDisplay, compareAtDisplay,
+//   const { isSoldOut, leftBadges, ribbons, promoBadge, priceDisplay, compareAtDisplay, teaser,
 //           colors, optionLabel, isQuickAddable, directAddVariantId, image, hoverImage } = useProductCard(product);
 //   // then render however you want; quick-add: addToCart(product.id, directAddVariantId) from useCart().
 
@@ -73,6 +73,11 @@ export function useProductCard(product) {
     // The variant a direct add sends (a product with no options still has one variant).
     const directAddVariantId = isQuickAddable ? minVariant?.id ?? null : null;
 
+    // plainDescription is an HTML string despite its name (<p>…</p>). A card wants plain text:
+    // strip the tags and cut at a word boundary, so no tile ever prints a literal "<p>".
+    const text = (product?.plainDescription || "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    const teaser = text.length > 140 ? `${text.slice(0, 140).replace(/\s+\S*$/, "")}…` : text;
+
     // Images: normalised through lib/storeImage so URLs are consistent across the tile,
     // the PDP gallery, and the cart. Hover image is the second gallery shot (if one exists).
     const image      = productImage(product);
@@ -87,6 +92,7 @@ export function useProductCard(product) {
       promoBadge,          // { type: 'ribbon', label } | null — the primary ribbon, for a single-badge slot
       priceDisplay,        // formatted price the buyer pays, or a min–max range
       compareAtDisplay,    // formatted struck "was" price | null (never beside a range)
+      teaser,              // plain-text description for the tile (tags stripped, ~140 chars) — never render plainDescription raw on a card
       colors,              // hex strings — render as dots; the tile shows up to however many you want
       optionLabel,         // "3 sizes · 2 materials" or empty string
       isQuickAddable,