@wix/agent-skills 1.16.1 → 1.16.2

package/skills/wix-vibe-headless/references/pricing-plans/seed/SEED.md

@@ -9,7 +9,7 @@ plain data.
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

package/skills/wix-vibe-headless/references/restaurants/seed/SEED.md

@@ -17,7 +17,7 @@ across exec calls. Online ordering and table reservations run only when the plan
 
 ```js
 // build-time exec_tool
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
 const fs = require("fs");
 // exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
 const seed = (() => { const m = { exports: {} };

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

@@ -24,12 +24,15 @@ so you don't need to open them:**
 | `context/CartContext.jsx` | `useCart()` provider: server cart, add/update/remove, checkout |
 | `hooks/useProductDetail.js` | PDP data — product + variant resolution for a slug, plus load/add state |
 | `hooks/useShop.js` | catalog listing — category menu, cursor paging, sort, failure state |
-| `components/ProductCard.jsx`, `ProductGrid.jsx` | product listing UI (grid + card, skeletons, empty state). The tile carries quick add for single-variant products, colour dots + an option summary, and pre-order / sold-out / limited-stock / percent-off / merchant-ribbon badges — all from the list query, no extra request |
+| `hooks/useProductCard.js` | headless data layer for a grid tile — returns `leftBadges`, `promoBadge`, `priceDisplay`, `compareAtDisplay`, `colors`, `optionLabel`, `isQuickAddable`, `image`, `hoverImage`; **always use this to build your own product card UI on the grid** |
+| `components/ProductCard.jsx` | reference implementation of a grid tile built on `useProductCard` — read it for inspiration, build your own component rather than using it directly |
+| `components/ProductGrid.jsx` | reference grid layout (2-col mobile → auto-fill desktop) with skeleton + empty state — read it for the skeleton/empty-state patterns, build your own layout rather than using it directly |
 | `components/ProductGallery.jsx` | PDP main image + thumbnails |
 | `lib/storeImage.js` | `productImage()` / `productGallery()` / `storeImage()` — normalise Wix image urls |
 | `components/CartButton.jsx` | header cart **icon** button with a live-count badge |
 | `components/CartDrawer.jsx` | slide-over cart (mount once; opens from `useCart`) |
-| `components/VariantPicker.jsx` | option/variant selector used on the PDP — colour options render as real swatches, and picking one moves the gallery to that colour's photo |
+| `hooks/useVariantOptions.js` | headless data layer for options/modifiers — returns `optionGroups` + `modifierGroups` (normalised, render-agnostic); **always use this to build your own variant UI on the PDP** |
+| `components/VariantPicker.jsx` | reference implementation of a variant selector built on `useVariantOptions` (pills + colour swatches) — read it for inspiration, but build your own component rather than using it directly |
 | `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 3) |
 | `pages/Shop.jsx`, `pages/ProductDetail.jsx` | the two shipped routes (`/shop`, `/product/:slug`) |
 | `rest/wix-config.js` | the two ids, written by the install step |
@@ -70,6 +73,69 @@ replace it.
   banner is dismissed.
 - Routes under the Layout: `/shop` → `Shop`, `/product/:slug` → `ProductDetail` (both shipped, as-is).
   **You add `/` → your own Home** page.
+- **Build your own variant selector on the PDP — this is required, not optional, and it's your chance to be creative.** `ProductDetail.jsx` ships with a `VariantPicker` import — remove it and replace with your own component built on `useVariantOptions`. Design the controls to fit the brief: the business type, the tone, the audience. A fashion brand might want large colour swatches and a size chart link; a tech store might want a compact dropdown. `VariantPicker.jsx` is in `src/` for reference — read it, don't use it:
+- **Build your own product card for the grid — this is required, not optional, and it's your chance to be creative.** `ProductGrid.jsx` ships with a `ProductCard` import — replace it with your own component built on `useProductCard`. The hook hands you everything the tile needs (badges, price display, colour dots, quick-add flag, images) — you decide the layout, shape, hover behaviour, and CTA style. A lifestyle brand might want full-bleed images with an overlay gradient; a tech store might want a compact horizontal list item. `ProductCard.jsx` is in `src/` for reference — read it, don't use it:
+- **Build your own grid layout — this is required, not optional, and it's your chance to be creative.** `ProductGrid.jsx` ships as a reference (2-col mobile → auto-fill desktop, 220px min) — replace it with an arrangement that fits the brief. A curated boutique might want a 3-col asymmetric editorial layout; a high-volume store might want a dense 4-col grid; a featured strip on the home page might want horizontal scroll. Keep the skeleton and empty-state patterns from `ProductGrid.jsx` (copy them into your own component) — the states themselves are correct, just the layout is yours to choose.
+
+```jsx
+import { Link } from "react-router-dom";
+import { useCart } from "@/context/CartContext";
+import { useProductCard } from "@/hooks/useProductCard";
+
+export default function MyProductCard({ product }) {
+  const { addToCart } = useCart();
+  const {
+    isSoldOut, isPreorder,
+    leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }] — render left side of image
+    promoBadge,       // { type: 'discount'|'ribbon', label } | null — render right side
+    priceDisplay,     // "€10" or "€10 – €20" (range when variants differ)
+    compareAtDisplay, // original price string | null
+    colors,           // hex strings → render as dots (slice to how many you want)
+    optionLabel,      // "3 sizes · 2 materials" or empty string
+    isQuickAddable,   // true for single-variant, in-stock products
+    image,            // primary image URL | null
+    hoverImage,       // second image URL | null
+  } = useProductCard(product);
+
+  // Then render however you want:
+  return (
+    <div>
+      {/* image, badges, price, colour dots, quick-add or "Choose options" CTA */}
+      {isQuickAddable && <button onClick={() => addToCart(product.id)}>Quick add</button>}
+      {!isQuickAddable && !isSoldOut && <Link to={`/product/${product.slug}`}>Choose options</Link>}
+      {isSoldOut && isPreorder && <Link to={`/product/${product.slug}`}>Pre-order</Link>}
+    </div>
+  );
+}
+```
+
+```jsx
+import { useVariantOptions } from "@/hooks/useVariantOptions";
+
+// options/modifiers/selectedOptions/modifierValues come from useProductDetail:
+const { optionGroups, modifierGroups } = useVariantOptions(options, modifiers, selectedOptions, modifierValues);
+
+// optionGroups: [{ id, name, isColor, choices: [{ choiceId, name, colorCode, isColorSwatch, inStock, selected }] }]
+// modifierGroups: [{ key, name, mandatory, type: 'choices'|'text', choices?: [{ key, name, selected }], value?: string }]
+
+// Then render however you want:
+optionGroups.map((group) =>
+  group.choices.map((c) =>
+    c.isColorSwatch
+      ? <MySwatch key={c.choiceId} color={c.colorCode} active={c.selected} disabled={!c.inStock}
+                  onClick={() => selectOption(group.id, c.choiceId)} />
+      : <MyPill  key={c.choiceId} active={c.selected} disabled={!c.inStock}
+                  onClick={() => selectOption(group.id, c.choiceId)}>{c.name}</MyPill>
+  )
+);
+modifierGroups.map((m) =>
+  m.type === "text"
+    ? <MyInput key={m.key} label={m.name} value={m.value} onChange={(v) => setModifier(m.key, v)} />
+    : m.choices.map((c) =>
+        <MyPill key={c.key} active={c.selected} onClick={() => setModifier(m.key, c.key)}>{c.name}</MyPill>
+      )
+);
+```
 
 ```jsx
 import { useRef, useState, useEffect } from "react";

package/skills/wix-vibe-headless/references/storefront/app/components/ProductCard.jsx

@@ -1,72 +1,29 @@
-// Grid tile. Styled with base44 design tokens (shadcn Tailwind classes: bg-card / text-foreground /
-// border-border) — re-skin via the app's design tokens (src/index.css :root/.dark), not this JSX.
-// The price / stock / ribbon field paths are load-bearing; image URLs go through lib/storeImage so the
-// grid, the PDP gallery and the cart all normalise them the same way.
-//
-// Everything here comes from the list query — the tile costs no extra request. What the list query
-// does NOT carry is a stock COUNT (inventory has availabilityStatus only), so "Limited stock" is as
-// precise as a tile can honestly get; "Only 2 left" would need per-variant inventory per product.
+// Reference implementation of a product grid tile built on useProductCard.
+// Styled with base44 design tokens (shadcn Tailwind classes: bg-card / text-foreground / border-border).
+// Build your own card on useProductCard instead — read this for inspiration, don't use it directly.
 import { useState } from "react";
 import { Link } from "react-router-dom";
-import { productGallery, productImage } from "@/lib/storeImage";
 import { useCart } from "@/context/CartContext";
+import { useProductCard } from "@/hooks/useProductCard";
 
-// Percent off, from the raw amounts — the formatted strings ("€129.00") can't be subtracted.
-function discountPercent(product) {
-  const now = Number(product?.actualPriceRange?.minValue?.amount);
-  const was = Number(product?.compareAtPriceRange?.minValue?.amount);
-  if (!now || !was || was <= now) return null;
-  return Math.round(((was - now) / was) * 100);
-}
-
-// What the buyer gets to choose, previewed on the tile: colour options become real dots (the colours
-// say more than "3 colors" could), everything else becomes "4 sizes". Pluralised from the option's own
-// name, so the wording follows the merchant's catalogue rather than a hardcoded English word.
-function optionsPreview(product) {
-  const labels = [], colors = [];
-  for (const o of product?.options || []) {
-    const choices = (o.choicesSettings?.choices || []).filter((c) => c.visible !== false);
-    if (!choices.length) continue;
-    const swatches = choices.map((c) => c.colorCode).filter(Boolean);
-    if (swatches.length) { colors.push(...swatches); continue; }
-    const n = o.name.toLowerCase();
-    labels.push(`${choices.length} ${choices.length === 1 || n.endsWith("s") ? n : `${n}s`}`);
-  }
-  return { label: labels.join(" · "), colors };
-}
-
-// One rule for every chip on the tile, so a new badge has an obvious home instead of a fresh colour:
-// promotional shouts in the brand colour, informational sits quietly on a card surface, and only a
-// blocking state is destructive. Each background travels with its own foreground token.
 const badge = "px-2 py-0.5 text-[11px] font-semibold uppercase tracking-wide rounded-full";
-const badgePromo = `${badge} bg-primary text-primary-foreground`;
-const badgeInfo = `${badge} bg-card text-foreground border border-border`;
-const badgeBlocked = `${badge} bg-destructive text-destructive-foreground`;
+const badgePromo    = `${badge} bg-primary text-primary-foreground`;
+const badgeInfo     = `${badge} bg-card text-foreground border border-border`;
+const badgeBlocked  = `${badge} bg-destructive text-destructive-foreground`;
+
+const badgeClass = { "pre-order": badgeInfo, "sold-out": badgeBlocked, "limited-stock": badgeInfo };
 
 export default function ProductCard({ product }) {
   const { addToCart } = useCart();
   const [adding, setAdding] = useState(false);
 
-  const image = productImage(product);
-  const hoverImage = productGallery(product)[1]?.url;
-  const price = product?.actualPriceRange?.minValue?.formattedAmount;
-  const priceMax = product?.actualPriceRange?.maxValue?.formattedAmount;
-  const compareAt = product?.compareAtPriceRange?.minValue?.formattedAmount;
-
-  const status = product?.inventory?.availabilityStatus;
-  const soldOut = status === "OUT_OF_STOCK";
-  const preorder = product?.inventory?.preorderStatus === "ENABLED";
-  const discount = discountPercent(product);
-  // A merchant-set ribbon ("New", "Best Seller") is the catalogue's own badge, so it beats anything
-  // derived here — a "new" label computed from createdDate would flag the whole catalogue at once
-  // right after seeding. Suppressed when a discount badge is showing, since that ribbon is "Sale".
-  const ribbon = product?.ribbon?.name;
-  const { label: optionLabel, colors } = optionsPreview(product);
-  const hasOptions = (product?.options?.length || 0) > 0;
+  const {
+    isSoldOut, isPreorder, leftBadges, promoBadge,
+    priceDisplay, compareAtDisplay,
+    colors, optionLabel,
+    isQuickAddable, image, hoverImage,
+  } = useProductCard(product);
 
-  // No options means a single variant, which the cart resolves from the product id alone — so the
-  // tile can add straight to the cart with no extra request. The drawer opening is the confirmation
-  // (and carries the reason when it fails), which is why there's no "Added ✓" state to fake here.
   const quickAdd = async () => {
     setAdding(true);
     await addToCart(product.id);
@@ -79,11 +36,8 @@ export default function ProductCard({ product }) {
         <Link to={`/product/${product.slug}`} aria-label={product.name} className="block w-full h-full">
           {image ? (
             <>
-              {/* Fade out only when there IS a second shot behind it — a one-photo product would
-                  otherwise hover to an empty frame. */}
               <img src={image} alt={product.name} loading="lazy"
                 className={`w-full h-full object-cover ${hoverImage ? "transition-opacity duration-300 md:group-hover:opacity-0" : ""}`} />
-              {/* Second catalogue shot on hover. `hidden` below md so phones never fetch it. */}
               {hoverImage && (
                 <img src={hoverImage} alt="" aria-hidden="true" loading="lazy"
                   className="hidden md:block absolute inset-0 w-full h-full object-cover opacity-0 transition-opacity duration-300 group-hover:opacity-100" />
@@ -99,51 +53,40 @@ export default function ProductCard({ product }) {
         </Link>
 
         <div className="absolute top-2 left-2 flex flex-col items-start gap-1 pointer-events-none">
-          {soldOut && preorder && <span className={badgeInfo}>Pre-order</span>}
-          {soldOut && !preorder && <span className={badgeBlocked}>Sold out</span>}
-          {status === "PARTIALLY_OUT_OF_STOCK" && <span className={badgeInfo}>Limited stock</span>}
+          {leftBadges.map((b) => (
+            <span key={b.type} className={badgeClass[b.type]}>{b.label}</span>
+          ))}
         </div>
-        {/* Discount and ribbon are mutually exclusive, so both can claim the promotional slot. */}
         <div className="absolute top-2 right-2 pointer-events-none">
-          {discount ? <span className={badgePromo}>−{discount}%</span>
-            : ribbon ? <span className={badgePromo}>{ribbon}</span> : null}
+          {promoBadge && <span className={badgePromo}>{promoBadge.label}</span>}
         </div>
 
-        {/* Sold out with no pre-order has nothing to offer, so no control appears at all. */}
-        {(!soldOut || preorder) && (
+        {(!isSoldOut || isPreorder) && (
           <div className="absolute inset-x-2 bottom-2 opacity-100 transition-opacity md:opacity-0 md:group-hover:opacity-100 md:group-focus-within:opacity-100">
-            {/* Same tokens as the PDP's Add-to-cart button: one action, one treatment, so the tile's
-                CTA is the brand colour rather than "whatever the text colour is". */}
-            {hasOptions || soldOut ? (
-              <Link to={`/product/${product.slug}`}
-                className="block w-full text-center py-2.5 px-4 rounded-full bg-primary text-primary-foreground no-underline text-sm font-semibold">
-                {soldOut ? "Pre-order" : "Choose options"}
-              </Link>
-            ) : (
+            {isQuickAddable ? (
               <button onClick={quickAdd} disabled={adding}
                 className="w-full py-2.5 px-4 rounded-full bg-primary text-primary-foreground border-none text-sm font-semibold cursor-pointer transition-opacity hover:opacity-90 disabled:opacity-60 disabled:cursor-wait">
                 {adding ? "Adding…" : "Quick add"}
               </button>
+            ) : (
+              <Link to={`/product/${product.slug}`}
+                className="block w-full text-center py-2.5 px-4 rounded-full bg-primary text-primary-foreground no-underline text-sm font-semibold">
+                {isSoldOut ? "Pre-order" : "Choose options"}
+              </Link>
             )}
           </div>
         )}
       </div>
 
       <div className="p-3 flex flex-col gap-1">
-        {/* Side by side once the tile is wide enough; stacked on a phone's two-up grid, where a long
-            name wrapping to three lines against a top-right price reads as broken. */}
         <div className="flex flex-col gap-1 md:flex-row md:items-baseline md:justify-between md:gap-3">
-          {/* Clamped to two lines: a 220px tile turns a long product name into three or four ragged
-              lines beside a top-right price. The full name is on the tile's link and the PDP. */}
           <h3 className="m-0 font-display text-[15px] font-semibold line-clamp-2">
             <Link to={`/product/${product.slug}`} className="no-underline text-foreground">{product.name}</Link>
           </h3>
           <div className="flex gap-2 items-baseline flex-wrap md:justify-end">
-            {/* A product whose variants differ in price spans a range — showing only minValue reads as
-                the price of everything, then the PDP appears to raise it once a variant is picked. */}
-            <span className="font-semibold whitespace-nowrap">{priceMax && priceMax !== price ? `${price} – ${priceMax}` : price}</span>
-            {compareAt && compareAt !== price && (
-              <span className="text-muted-foreground line-through text-[13px] whitespace-nowrap">{compareAt}</span>
+            <span className="font-semibold whitespace-nowrap">{priceDisplay}</span>
+            {compareAtDisplay && (
+              <span className="text-muted-foreground line-through text-[13px] whitespace-nowrap">{compareAtDisplay}</span>
             )}
           </div>
         </div>

package/skills/wix-vibe-headless/references/storefront/app/components/ProductGrid.jsx

@@ -1,11 +1,6 @@
-// Responsive product grid, with the two states a fresh store spends most of its life in: loading and
-// empty. Styled with base44 design tokens (shadcn Tailwind classes).
-//
-// Two columns on phones — a 220px minmax leaves room for only one, and a one-up catalog scrolls
-// forever — then auto-fill from md up.
-//
-// The empty state carries weight here — a catalog is seeded separately from the build, so it is
-// routinely empty when the merchant first opens the page. Say why, rather than showing a bare line.
+// Reference implementation of a product grid — 2-col mobile, auto-fill desktop, with a skeleton
+// loading state and a descriptive empty state. Build your own layout instead (see INSTRUCTIONS.md
+// STEP 3) — read this for the skeleton/empty-state patterns, don't use it directly.
 import ProductCard from "./ProductCard";
 
 // Skeleton tiles match ProductCard's aspect-square + two text lines, so nothing shifts when the real

package/skills/wix-vibe-headless/references/storefront/app/components/VariantPicker.jsx

@@ -1,118 +1,91 @@
-// PDP choice controls: one OptionSelector per product.options[] (variant choices) and one
-// ModifierSelector per product.modifiers[] (TEXT_CHOICES → buttons, FREE_TEXT → input). Driven by
-// useProductDetail — pass its selection state/handlers in. Styled with base44 design tokens (shadcn Tailwind classes).
+// PDP choice controls built on useVariantOptions — swap this component for your own if you want
+// a different look; the data contract (optionGroups / modifierGroups) stays the same.
+// Styled with base44 design tokens (shadcn Tailwind classes).
+import { useVariantOptions } from "@/hooks/useVariantOptions";
 
 const chipBase = "py-1.5 px-3 cursor-pointer text-sm font-body border rounded-sm";
 const chipIdle = "border-border bg-card text-foreground";
 const chipActive = "border-primary bg-primary text-primary-foreground";
 const label = "block mb-1.5 text-[13px] font-semibold text-muted-foreground";
 
-// A colour/swatch option renders as swatches, a text option as pills — the render type is on the
-// option (`optionRenderType`) and mirrored per choice (`choiceType`: ONE_COLOR vs CHOICE_TEXT).
-// Colour choices carry `colorCode` (hex) and usually `linkedMedia`, so a swatch is real colour, and
-// picking one moves the gallery to that colour's photo.
-const isColorChoice = (option, choice) =>
-  option?.optionRenderType === "COLOR_CHOICES" ||
-  option?.optionRenderType === "SWATCH_CHOICES" ||
-  choice?.choiceType === "ONE_COLOR";
-
-function OptionSelector({ option, selected, onSelect }) {
-  // `visible: false` is a choice the merchant retired — it stays in the payload, so filter it out or
-  // the buyer can pick something the catalogue no longer offers.
-  const choices = (option.choicesSettings?.choices || []).filter((c) => c.visible !== false);
-  if (!choices.length) return null;
-  const swatches = choices.some((c) => isColorChoice(option, c) && c.colorCode);
-
-  return (
-    <div className="mb-4">
-      <label className={label}>
-        {option.name}
-        {/* With swatches the chosen colour's name isn't otherwise on screen — echo it. */}
-        {swatches && selected && (
-          <span className="ml-1.5 font-normal text-foreground">
-            {choices.find((c) => c.choiceId === selected)?.name}
-          </span>
-        )}
-      </label>
-      <div className="flex flex-wrap gap-2">
-        {choices.map((c) => {
-          const active = selected === c.choiceId;
-          const out = c.inStock === false;
-          if (swatches && c.colorCode) {
-            return (
-              <button
-                key={c.choiceId}
-                type="button"
-                disabled={out}
-                onClick={() => onSelect(option.id, c.choiceId)}
-                aria-pressed={active}
-                aria-label={`${c.name}${out ? " (out of stock)" : ""}`}
-                title={c.name}
-                className={`relative w-9 h-9 rounded-full cursor-pointer transition-shadow ring-1 ring-inset ring-black/15 ${
-                  active ? "ring-2 ring-offset-2 ring-offset-background ring-primary" : ""
-                } ${out ? "opacity-40 cursor-not-allowed" : "hover:ring-2 hover:ring-offset-1 hover:ring-offset-background hover:ring-border"}`}
-                style={{ backgroundColor: c.colorCode }}
-              >
-                {/* A struck line reads as "unavailable" without hiding which colour it was. */}
-                {out && (
-                  <span aria-hidden="true" className="absolute inset-0 grid place-items-center">
-                    <span className="w-full h-px bg-destructive rotate-45" />
-                  </span>
-                )}
-              </button>
-            );
-          }
-          return (
-            <button
-              key={c.choiceId}
-              type="button"
-              disabled={out}
-              aria-pressed={active}
-              onClick={() => onSelect(option.id, c.choiceId)}
-              className={`${chipBase} ${active ? chipActive : chipIdle} ${out ? "opacity-40 line-through" : ""}`}
-            >
-              {c.name}
-            </button>
-          );
-        })}
-      </div>
-    </div>
-  );
-}
-
-function ModifierSelector({ modifier, value, onChange }) {
-  const key = modifier.modifierRenderType === "FREE_TEXT" ? modifier.freeTextSettings?.key : modifier.key;
-  if (modifier.modifierRenderType === "FREE_TEXT") {
-    return (
-      <div className="mb-4">
-        <label className={label}>{modifier.name}{modifier.mandatory && " *"}</label>
-        <input value={value || ""} onChange={(e) => onChange(key, e.target.value)}
-          className="w-full py-2 px-3 font-body border border-input rounded-sm bg-background text-foreground" />
-      </div>
-    );
-  }
-  return (
-    <div className="mb-4">
-      <label className={label}>{modifier.name}{modifier.mandatory && " *"}</label>
-      <div className="flex flex-wrap gap-2">
-        {modifier.choicesSettings?.choices?.map((c) => (
-          <button key={c.key} aria-pressed={value === c.key} onClick={() => onChange(key, c.key)}
-            className={`${chipBase} ${value === c.key ? chipActive : chipIdle}`}>{c.name}</button>
-        ))}
-      </div>
-    </div>
-  );
-}
-
 export default function VariantPicker({ options, modifiers, selectedOptions, selectOption, modifierValues, setModifier }) {
+  const { optionGroups, modifierGroups } = useVariantOptions(options, modifiers, selectedOptions, modifierValues);
+
   return (
     <>
-      {options.map((o) => (
-        <OptionSelector key={o.id} option={o} selected={selectedOptions[o.id]} onSelect={selectOption} />
+      {optionGroups.map((group) => (
+        <div key={group.id} className="mb-4">
+          <label className={label}>
+            {group.name}
+            {group.isColor && (
+              <span className="ml-1.5 font-normal text-foreground">
+                {group.choices.find((c) => c.selected)?.name}
+              </span>
+            )}
+          </label>
+          <div className="flex flex-wrap gap-2">
+            {group.choices.map((c) =>
+              c.isColorSwatch ? (
+                <button
+                  key={c.choiceId}
+                  type="button"
+                  disabled={!c.inStock}
+                  onClick={() => selectOption(group.id, c.choiceId)}
+                  aria-pressed={c.selected}
+                  aria-label={`${c.name}${!c.inStock ? " (out of stock)" : ""}`}
+                  title={c.name}
+                  className={`relative w-9 h-9 rounded-full cursor-pointer transition-shadow ring-1 ring-inset ring-black/15 ${
+                    c.selected ? "ring-2 ring-offset-2 ring-offset-background ring-primary" : ""
+                  } ${!c.inStock ? "opacity-40 cursor-not-allowed" : "hover:ring-2 hover:ring-offset-1 hover:ring-offset-background hover:ring-border"}`}
+                  style={{ backgroundColor: c.colorCode }}
+                >
+                  {!c.inStock && (
+                    <span aria-hidden="true" className="absolute inset-0 grid place-items-center">
+                      <span className="w-full h-px bg-destructive rotate-45" />
+                    </span>
+                  )}
+                </button>
+              ) : (
+                <button
+                  key={c.choiceId}
+                  type="button"
+                  disabled={!c.inStock}
+                  aria-pressed={c.selected}
+                  onClick={() => selectOption(group.id, c.choiceId)}
+                  className={`${chipBase} ${c.selected ? chipActive : chipIdle} ${!c.inStock ? "opacity-40 line-through" : ""}`}
+                >
+                  {c.name}
+                </button>
+              )
+            )}
+          </div>
+        </div>
       ))}
-      {modifiers.map((m) => (
-        <ModifierSelector key={m.key || m.freeTextSettings?.key} modifier={m}
-          value={modifierValues[m.key || m.freeTextSettings?.key]} onChange={setModifier} />
+
+      {modifierGroups.map((m) => (
+        <div key={m.key} className="mb-4">
+          <label className={label}>{m.name}{m.mandatory && " *"}</label>
+          {m.type === "text" ? (
+            <input
+              value={m.value}
+              onChange={(e) => setModifier(m.key, e.target.value)}
+              className="w-full py-2 px-3 font-body border border-input rounded-sm bg-background text-foreground"
+            />
+          ) : (
+            <div className="flex flex-wrap gap-2">
+              {m.choices.map((c) => (
+                <button
+                  key={c.key}
+                  aria-pressed={c.selected}
+                  onClick={() => setModifier(m.key, c.key)}
+                  className={`${chipBase} ${c.selected ? chipActive : chipIdle}`}
+                >
+                  {c.name}
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
       ))}
     </>
   );

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

@@ -0,0 +1,92 @@
+// Headless data layer for a product grid tile.
+// Normalises raw Wix product fields into render-agnostic structures so you can build
+// whatever card UI you want (image layout, badge style, price display, quick-add trigger)
+// without touching the badge-priority logic, price-range maths, or colour-dot extraction.
+//
+// Usage:
+//   const { isSoldOut, leftBadges, promoBadge, priceDisplay, compareAtDisplay,
+//           colors, optionLabel, isQuickAddable, image, hoverImage } = useProductCard(product);
+//   // then render however you want, call addToCart(product.id) from useCart() for quick-add.
+
+import { useMemo } from "react";
+import { productImage, productGallery } from "@/lib/storeImage";
+
+function discountPercent(product) {
+  const now = Number(product?.actualPriceRange?.minValue?.amount);
+  const was = Number(product?.compareAtPriceRange?.minValue?.amount);
+  if (!now || !was || was <= now) return null;
+  return Math.round(((was - now) / was) * 100);
+}
+
+export function useProductCard(product) {
+  return useMemo(() => {
+    const status = product?.inventory?.availabilityStatus;
+    const isSoldOut = status === "OUT_OF_STOCK";
+    // preorderStatus is only meaningful when the product is out of stock
+    const isPreorder = isSoldOut && product?.inventory?.preorderStatus === "ENABLED";
+    const isPartiallyOutOfStock = status === "PARTIALLY_OUT_OF_STOCK";
+
+    // Left-side badges (stacked, top-left of the image): stock / pre-order state.
+    const leftBadges = [];
+    if (isPreorder)                leftBadges.push({ type: "pre-order",     label: "Pre-order"     });
+    else if (isSoldOut)            leftBadges.push({ type: "sold-out",      label: "Sold out"      });
+    if (isPartiallyOutOfStock)     leftBadges.push({ type: "limited-stock", label: "Limited stock" });
+
+    // Right-side promo badge: discount % beats a merchant ribbon (a "Sale" ribbon is redundant
+    // when the % is already showing). Only one at a time.
+    const discount = discountPercent(product);
+    const ribbon   = product?.ribbon?.name;
+    const promoBadge = discount
+      ? { type: "discount", label: `-${discount}%` }
+      : ribbon
+      ? { type: "ribbon",   label: ribbon }
+      : null;
+
+    // Price: show a min–max range when variants span different prices so the PDP doesn't
+    // appear to raise the price once a variant is selected.
+    const priceMin = product?.actualPriceRange?.minValue?.formattedAmount;
+    const priceMax = product?.actualPriceRange?.maxValue?.formattedAmount;
+    const compareAt = product?.compareAtPriceRange?.minValue?.formattedAmount;
+    const priceDisplay      = priceMax && priceMax !== priceMin ? `${priceMin} – ${priceMax}` : priceMin;
+    const compareAtDisplay  = compareAt && compareAt !== priceMin ? compareAt : null;
+
+    // Options preview for the tile summary row.
+    // Colour options → real hex dots (more informative than "3 colours").
+    // Non-colour options → "3 sizes · 2 materials" (pluralised from the merchant's own name).
+    const labels = [], colors = [];
+    for (const o of product?.options || []) {
+      const choices = (o.choicesSettings?.choices || []).filter((c) => c.visible !== false);
+      if (!choices.length) continue;
+      const swatches = choices.map((c) => c.colorCode).filter(Boolean);
+      if (swatches.length) { colors.push(...swatches); continue; }
+      const n = o.name.toLowerCase();
+      labels.push(`${choices.length} ${choices.length === 1 || n.endsWith("s") ? n : `${n}s`}`);
+    }
+    const optionLabel = labels.join(" · ");
+    const hasOptions  = (product?.options?.length || 0) > 0;
+
+    // Quick-add is only safe for single-variant products (no option choices to resolve).
+    // Sold-out with pre-order still shows a CTA, but it links to the PDP, not quick-add.
+    const isQuickAddable = !hasOptions && !isSoldOut;
+
+    // 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);
+    const hoverImage = productGallery(product)[1]?.url ?? null;
+
+    return {
+      isSoldOut,
+      isPreorder,
+      isPartiallyOutOfStock,
+      leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }]
+      promoBadge,       // { type: 'discount'|'ribbon', label } | null
+      priceDisplay,     // formatted price (range or single value)
+      compareAtDisplay, // formatted compare-at price | null
+      colors,           // hex strings — render as dots; the tile shows up to however many you want
+      optionLabel,      // "3 sizes · 2 materials" or empty string
+      isQuickAddable,
+      image,            // primary image URL | null
+      hoverImage,       // second image URL for hover effect | null
+    };
+  }, [product]);
+}