@wix/agent-skills 1.15.1 → 1.16.0

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

@@ -0,0 +1,150 @@
+// Slide-over cart. Reads everything from useCart(); mutate by lineItem.id (NOT catalogItemId),
+// check out via the context (redirect-session URL). Styled with base44 design tokens (shadcn Tailwind classes).
+//
+// Load-bearing beyond the styling:
+// • prices come from the SERVER cart — `price` is post-discount, `fullPrice` is before it, so the
+//   two together are the strikethrough. Never compute a total in the client: tax, shipping and
+//   promotions are resolved server-side, so `subtotal` is the only figure safe to show pre-checkout.
+//   Money objects carry { amount, convertedAmount, formattedAmount, formattedConvertedAmount }; use a
+//   formatted one so the currency symbol and grouping come from Wix. Prefer `subtotalAfterDiscounts`
+//   over `subtotal` — the two are equal until a cart-level coupon applies, and then `subtotal` is the
+//   pre-discount figure, which would quote the buyer more than they'll pay.
+// • `availability.quantityAvailable` caps the stepper, so exceeding stock is refused here rather than
+//   at checkout.
+// • `availability.status` is flagged per line here because checkout() refuses the whole cart when
+//   any item isn't AVAILABLE — showing it on the row is what makes that refusal understandable.
+import { useEffect } from "react";
+import { useCart } from "@/context/CartContext";
+import { storeImage } from "@/lib/storeImage";
+
+export default function CartDrawer() {
+  const { cart, isOpen, setIsOpen, removeItem, updateQuantity, checkout, loading, error, clearError } = useCart();
+  const lineItems = cart?.lineItems ?? [];
+  const money = (m) => m?.formattedConvertedAmount || m?.formattedAmount;
+  const subtotal = money(cart?.subtotalAfterDiscounts) || money(cart?.subtotal);
+  const discount = money(cart?.discount);
+  const hasDiscount = (cart?.appliedDiscounts?.length || 0) > 0 && Number(cart?.discount?.amount) > 0;
+  const unavailable = lineItems.filter((li) => li.availability?.status && li.availability.status !== "AVAILABLE");
+
+  // Escape closes the drawer while it's open — expected of anything modal, and the only way out for
+  // keyboard users (the backdrop click is pointer-only).
+  useEffect(() => {
+    if (!isOpen) return;
+    const onKey = (e) => e.key === "Escape" && setIsOpen(false);
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [isOpen, setIsOpen]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div onClick={() => setIsOpen(false)} className="fixed inset-0 z-50 bg-black/40 flex justify-end">
+      <aside onClick={(e) => e.stopPropagation()} role="dialog" aria-modal="true" aria-label="Your cart"
+        className="w-[min(420px,100%)] h-full flex flex-col bg-background text-foreground border-l border-border font-body">
+        <header className="flex justify-between items-center p-4 border-b border-border">
+          <strong className="font-display">Your cart{lineItems.length ? ` (${lineItems.length})` : ""}</strong>
+          <button onClick={() => setIsOpen(false)} aria-label="Close cart"
+            className="border-none bg-transparent cursor-pointer text-xl text-muted-foreground">×</button>
+        </header>
+
+        {error && (
+          <div role="alert" className="m-4 mb-0 p-3 rounded-sm border border-destructive/40 bg-destructive/10 text-sm">
+            <div className="flex items-start gap-2">
+              <span className="flex-1">{error}</span>
+              <button onClick={clearError} aria-label="Dismiss"
+                className="border-none bg-transparent cursor-pointer text-muted-foreground leading-none">×</button>
+            </div>
+          </div>
+        )}
+
+        <div className="flex-1 overflow-y-auto p-4">
+          {lineItems.length === 0 ? (
+            <div className="h-full flex flex-col items-center justify-center text-center gap-3 py-10">
+              <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5"
+                className="text-muted-foreground/40" aria-hidden="true">
+                <path d="M6 2 3 6v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V6l-3-4Z" /><path d="M3 6h18" />
+                <path d="M16 10a4 4 0 0 1-8 0" />
+              </svg>
+              <p className="m-0 text-muted-foreground">Your cart is empty.</p>
+              <button onClick={() => setIsOpen(false)}
+                className="border border-border bg-card text-foreground rounded-sm py-2 px-4 cursor-pointer text-sm">Continue shopping</button>
+            </div>
+          ) : lineItems.map((item) => {
+            const image = storeImage(item.image?.url);
+            const struck = item.fullPrice?.formattedAmount;
+            const paid = item.price?.formattedAmount;
+            const isOut = item.availability?.status && item.availability.status !== "AVAILABLE";
+            const stock = item.availability?.quantityAvailable;
+            const atStockLimit = Number.isFinite(stock) && item.quantity >= stock;
+            return (
+              <div key={item.id} className="flex gap-3 py-3 px-0 border-b border-border">
+                <div className="w-16 h-16 shrink-0 rounded-sm bg-card overflow-hidden">
+                  {image && <img src={image} alt={item.productName?.original || ""} className="w-full h-full object-cover" />}
+                </div>
+                <div className="flex-1 flex flex-col gap-1 min-w-0">
+                  <span className="font-semibold truncate">{item.productName?.original}</span>
+                  {item.descriptionLines?.map((dl, i) => (
+                    <small key={i} className="text-muted-foreground">
+                      {dl.name?.original}: {dl.plainText?.original || dl.colorInfo?.original}
+                    </small>
+                  ))}
+                  {isOut ? (
+                    <small className="text-destructive">
+                      {item.availability.status === "NOT_AVAILABLE" ? "No longer available" : "Not enough stock"}
+                    </small>
+                  ) : atStockLimit ? (
+                    <small className="text-muted-foreground">Only {stock} left</small>
+                  ) : null}
+                  <div className="flex items-center gap-2 mt-1">
+                    <QtyButton disabled={loading || item.quantity <= 1} label="Decrease quantity"
+                      onClick={() => updateQuantity(item.id, item.quantity - 1)}>−</QtyButton>
+                    <span className="min-w-5 text-center" aria-label={`Quantity ${item.quantity}`}>{item.quantity}</span>
+                    <QtyButton disabled={loading || atStockLimit} label="Increase quantity"
+                      onClick={() => updateQuantity(item.id, item.quantity + 1)}>+</QtyButton>
+                    <button onClick={() => removeItem(item.id)} disabled={loading}
+                      className="ml-auto border-none bg-transparent cursor-pointer text-muted-foreground text-[13px] underline disabled:opacity-50">Remove</button>
+                  </div>
+                </div>
+                <div className="flex flex-col items-end shrink-0">
+                  <span className="font-semibold">{paid}</span>
+                  {struck && struck !== paid && (
+                    <span className="text-muted-foreground line-through text-[13px]">{struck}</span>
+                  )}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+
+        {lineItems.length > 0 && (
+          <footer className="p-4 border-t border-border flex flex-col gap-3">
+            {hasDiscount && (
+              <div className="flex justify-between items-baseline text-sm">
+                <span className="text-muted-foreground">Discount</span>
+                <span>−{discount}</span>
+              </div>
+            )}
+            {subtotal && (
+              <div className="flex justify-between items-baseline">
+                <span className="text-muted-foreground">Subtotal</span>
+                <strong className="text-[17px]">{subtotal}</strong>
+              </div>
+            )}
+            <p className="m-0 text-[12px] text-muted-foreground">Shipping and taxes are calculated at checkout.</p>
+            <button disabled={loading || unavailable.length > 0} onClick={checkout}
+              className="w-full p-3 bg-primary text-primary-foreground border-none rounded-sm text-[15px] font-semibold cursor-pointer disabled:cursor-not-allowed disabled:opacity-60">
+              {loading ? "Working…" : unavailable.length > 0 ? "Remove unavailable items to continue" : "Checkout"}
+            </button>
+          </footer>
+        )}
+      </aside>
+    </div>
+  );
+}
+
+function QtyButton({ children, onClick, disabled, label }) {
+  return (
+    <button onClick={onClick} disabled={disabled} aria-label={label}
+      className="w-7 h-7 cursor-pointer leading-none bg-card text-foreground border border-border rounded-sm disabled:opacity-40 disabled:cursor-not-allowed">{children}</button>
+  );
+}

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

@@ -0,0 +1,167 @@
+// 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.
+import { useState } from "react";
+import { Link } from "react-router-dom";
+import { productGallery, productImage } from "@/lib/storeImage";
+import { useCart } from "@/context/CartContext";
+
+// 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`;
+
+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;
+
+  // 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);
+    setAdding(false);
+  };
+
+  return (
+    <div className="group relative flex flex-col bg-card border border-border rounded-lg overflow-hidden shadow-sm">
+      <div className="relative aspect-square bg-background">
+        <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" />
+              )}
+            </>
+          ) : (
+            <div className="w-full h-full bg-muted flex items-center justify-center" aria-hidden="true">
+              <svg viewBox="0 0 24 24" className="w-8 h-8 text-muted-foreground/40" fill="none" stroke="currentColor" strokeWidth="1.5">
+                <rect x="3" y="3" width="18" height="18" rx="2" /><circle cx="8.5" cy="8.5" r="1.5" /><path d="m21 15-5-5L5 21" />
+              </svg>
+            </div>
+          )}
+        </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>}
+        </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}
+        </div>
+
+        {/* Sold out with no pre-order has nothing to offer, so no control appears at all. */}
+        {(!soldOut || preorder) && (
+          <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>
+            ) : (
+              <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>
+            )}
+          </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>
+            )}
+          </div>
+        </div>
+
+        {(colors.length > 0 || optionLabel) && (
+          <div className="flex items-center gap-2 text-[13px] text-muted-foreground min-h-[18px]">
+            {colors.length > 0 && (
+              <span className="flex items-center gap-1" aria-label={`${colors.length} colors available`}>
+                {colors.slice(0, 5).map((c, i) => (
+                  <span key={`${c}-${i}`} className="w-3 h-3 rounded-full ring-1 ring-inset ring-black/20" style={{ backgroundColor: c }} />
+                ))}
+                {colors.length > 5 && <span>+{colors.length - 5}</span>}
+              </span>
+            )}
+            {optionLabel && <span>{optionLabel}</span>}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,51 @@
+// PDP image gallery — main image plus thumbnails from productGallery(product), which puts
+// media.main first and drops the duplicate of it that media.itemsInfo.items carries. A product with a
+// single image renders just the main frame, so this is safe for a one-photo catalog.
+// Styled with base44 design tokens (shadcn Tailwind classes).
+import { useEffect, useState } from "react";
+
+export default function ProductGallery({ images, name, focusUrl }) {
+  const [index, setIndex] = useState(0);
+  // Reset when navigating between products — the component stays mounted across a slug change.
+  // `images` must keep a stable identity per product (the PDP memoises it), or every parent render —
+  // a quantity bump, an option click — would land here and throw away the image the buyer picked.
+  useEffect(() => { setIndex(0); }, [images]);
+
+  // Picking a colour swatch shows that colour: focusUrl is the choice's linked photo. Runs after the
+  // reset effect, so a first paint with a colour pre-selected opens on the right image.
+  useEffect(() => {
+    const i = images?.findIndex((img) => img.url === focusUrl) ?? -1;
+    if (i >= 0) setIndex(i);
+  }, [focusUrl, images]);
+
+  const current = images?.[index];
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="aspect-square bg-card rounded-lg overflow-hidden">
+        {current ? (
+          <img src={current.url} alt={current.altText || name} className="w-full h-full object-cover" />
+        ) : (
+          <div className="w-full h-full bg-muted flex items-center justify-center" aria-hidden="true">
+            <svg viewBox="0 0 24 24" className="w-10 h-10 text-muted-foreground/40" fill="none" stroke="currentColor" strokeWidth="1.5">
+              <rect x="3" y="3" width="18" height="18" rx="2" /><circle cx="8.5" cy="8.5" r="1.5" /><path d="m21 15-5-5L5 21" />
+            </svg>
+          </div>
+        )}
+      </div>
+
+      {images?.length > 1 && (
+        <div className="flex gap-2 flex-wrap" role="group" aria-label={`${name} images`}>
+          {images.map((img, i) => (
+            <button key={img.url} onClick={() => setIndex(i)} aria-label={`Show image ${i + 1}`} aria-current={i === index}
+              className={`w-16 h-16 rounded-sm overflow-hidden cursor-pointer bg-card border ${
+                i === index ? "border-primary" : "border-border"
+              }`}>
+              <img src={img.url} alt="" loading="lazy" className="w-full h-full object-cover" />
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,54 @@
+// 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.
+import ProductCard from "./ProductCard";
+
+// Skeleton tiles match ProductCard's aspect-square + two text lines, so nothing shifts when the real
+// products land.
+export function ProductGridSkeleton({ count = 8 }) {
+  return (
+    <div className="grid gap-4 grid-cols-2 md:[grid-template-columns:repeat(auto-fill,minmax(220px,1fr))]" aria-hidden="true">
+      {Array.from({ length: count }).map((_, i) => (
+        <div key={i} className="bg-card border border-border rounded-lg overflow-hidden">
+          <div className="aspect-square bg-muted animate-pulse" />
+          <div className="p-3 flex flex-col gap-2">
+            <div className="flex justify-between gap-3">
+              <div className="h-3.5 w-1/2 bg-muted rounded-sm animate-pulse" />
+              <div className="h-3.5 w-1/5 bg-muted rounded-sm animate-pulse" />
+            </div>
+            <div className="h-3 w-1/3 bg-muted rounded-sm animate-pulse" />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export default function ProductGrid({ products, loading, empty = "No products yet.", emptyHint }) {
+  if (loading) return <ProductGridSkeleton />;
+
+  if (!products?.length) {
+    return (
+      <div className="flex flex-col items-center justify-center text-center gap-3 py-16 px-4">
+        <svg width="44" height="44" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5"
+          className="text-muted-foreground/40" aria-hidden="true">
+          <path d="M6 2 3 6v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V6l-3-4Z" /><path d="M3 6h18" />
+          <path d="M16 10a4 4 0 0 1-8 0" />
+        </svg>
+        <h2 className="font-display m-0 text-lg font-semibold">{empty}</h2>
+        {emptyHint && <p className="m-0 text-muted-foreground max-w-[46ch]">{emptyHint}</p>}
+      </div>
+    );
+  }
+
+  return (
+    <div className="grid gap-4 grid-cols-2 md:[grid-template-columns:repeat(auto-fill,minmax(220px,1fr))]">
+      {products.map((p) => <ProductCard key={p.id} product={p} />)}
+    </div>
+  );
+}

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

@@ -0,0 +1,119 @@
+// 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).
+
+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 }) {
+  return (
+    <>
+      {options.map((o) => (
+        <OptionSelector key={o.id} option={o} selected={selectedOptions[o.id]} onSelect={selectOption} />
+      ))}
+      {modifiers.map((m) => (
+        <ModifierSelector key={m.key || m.freeTextSettings?.key} modifier={m}
+          value={modifierValues[m.key || m.freeTextSettings?.key]} onChange={setModifier} />
+      ))}
+    </>
+  );
+}

package/skills/wix-vibe-headless/references/storefront/app/context/CartContext.jsx

@@ -0,0 +1,71 @@
+// Cart state — mirrors the Wix SERVER cart (never a local copy). Wrap the app in <CartProvider>;
+// every component reads useCart(). Data wiring is correct as-is — do not restyle or re-derive it.
+import { createContext, useContext, useState, useEffect, useCallback } from "react";
+import {
+  getCurrentCart,
+  addToCart as apiAdd,
+  removeFromCart as apiRemove,
+  updateCartItemQuantity as apiQty,
+  checkout as apiCheckout,
+} from "@/rest/wix-store-cart";
+
+const CartContext = createContext(null);
+
+export function CartProvider({ children }) {
+  const [cart, setCart] = useState(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+  // The cart helpers throw on refusal with a buyer-readable reason — an empty cart, or line items
+  // whose availability.status isn't AVAILABLE. Hold the message so the drawer can show it; without
+  // this the rejection is unhandled and the shopper sees the spinner stop with nothing said.
+  const [error, setError] = useState(null);
+
+  const refreshCart = useCallback(async () => setCart(await getCurrentCart()), []);
+  useEffect(() => {
+    refreshCart();
+    const onVisible = () => document.visibilityState === "visible" && refreshCart();
+    document.addEventListener("visibilitychange", onVisible);
+    return () => document.removeEventListener("visibilitychange", onVisible);
+  }, [refreshCart]);
+
+  const itemCount = (cart?.lineItems ?? []).reduce((n, li) => n + (li.quantity || 0), 0);
+
+  // Every mutation runs through here so a rejection always lands somewhere visible. `run` keeps the
+  // cart untouched on failure — the server stays the source of truth — and re-reads it for anything
+  // that may have changed underneath (an item selling out between page load and checkout).
+  const run = async (fn, { reread = false } = {}) => {
+    setLoading(true);
+    setError(null);
+    try {
+      return await fn();
+    } catch (e) {
+      setError(e?.message || "Something went wrong. Please try again.");
+      if (reread) await refreshCart().catch(() => {});
+      return null;
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const addToCart = async (id, variantId, qty = 1, extras) =>
+    run(async () => {
+      setCart(await apiAdd(id, variantId, qty, extras));
+      setIsOpen(true);
+    });
+  const removeItem = (lineItemId) => run(async () => setCart(await apiRemove(lineItemId)));
+  const updateQuantity = (lineItemId, qty) => run(async () => setCart(await apiQty(lineItemId, qty)));
+  const checkout = () =>
+    run(async () => { window.location.href = await apiCheckout(); }, { reread: true });
+
+  return (
+    <CartContext.Provider value={{ cart, itemCount, isOpen, setIsOpen, loading, error, clearError: () => setError(null), addToCart, removeItem, updateQuantity, checkout, refreshCart }}>
+      {children}
+    </CartContext.Provider>
+  );
+}
+
+export function useCart() {
+  const ctx = useContext(CartContext);
+  if (!ctx) throw new Error("useCart must be used within <CartProvider>");
+  return ctx;
+}