@wix/agent-skills 1.16.0 → 1.16.2

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]);
+}

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

@@ -0,0 +1,76 @@
+// Headless data layer for product option/variant/modifier picking.
+// Normalises raw Wix product options + modifiers into flat, render-agnostic structures so you
+// can build whatever UI you want (pills, radios, dropdowns, swatches) without touching the
+// data-edge-case logic (visible filtering, color detection, modifier key resolution).
+//
+// Usage:
+//   const { optionGroups, modifierGroups } = useVariantOptions(
+//     options, modifiers, selectedOptions, modifierValues
+//   );
+//   // then map over optionGroups/modifierGroups to render your own controls and call
+//   // selectOption(optionId, choiceId) / setModifier(key, value) from useProductDetail.
+
+import { useMemo } from "react";
+
+export function useVariantOptions(options, modifiers, selectedOptions, modifierValues) {
+  const optionGroups = useMemo(() =>
+    (options || []).map((option) => {
+      const rawChoices = option.choicesSettings?.choices || [];
+      // `visible: false` = a choice the merchant retired — filter it so buyers can't select it.
+      const choices = rawChoices
+        .filter((c) => c.visible !== false)
+        .map((c) => ({
+          choiceId:   c.choiceId,
+          name:       c.name,
+          colorCode:  c.colorCode || null,
+          // true when this choice should render as a colour swatch (circle) rather than a pill.
+          isColorSwatch: !!(
+            (option.optionRenderType === "COLOR_CHOICES" ||
+             option.optionRenderType === "SWATCH_CHOICES" ||
+             c.choiceType === "ONE_COLOR") &&
+            c.colorCode
+          ),
+          inStock:  c.inStock !== false,
+          selected: selectedOptions[option.id] === c.choiceId,
+        }));
+      return {
+        id:      option.id,
+        name:    option.name,
+        // true if ANY choice in this group is a colour swatch — lets you branch on group type.
+        isColor: choices.some((c) => c.isColorSwatch),
+        choices,
+      };
+    }),
+    [options, selectedOptions]
+  );
+
+  const modifierGroups = useMemo(() =>
+    (modifiers || []).map((m) => {
+      const isText = m.modifierRenderType === "FREE_TEXT";
+      const key = isText ? m.freeTextSettings?.key : m.key;
+      if (isText) {
+        return {
+          key,
+          name:      m.name,
+          mandatory: !!m.mandatory,
+          type:      "text",
+          value:     modifierValues[key] || "",
+        };
+      }
+      return {
+        key,
+        name:      m.name,
+        mandatory: !!m.mandatory,
+        type:      "choices",
+        choices:   (m.choicesSettings?.choices || []).map((c) => ({
+          key:      c.key,
+          name:     c.name,
+          selected: modifierValues[key] === c.key,
+        })),
+      };
+    }),
+    [modifiers, modifierValues]
+  );
+
+  return { optionGroups, modifierGroups };
+}

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

@@ -6,7 +6,7 @@ seed operation. Load it and call **`setupStore` — the one-call path** — with
 
 ```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/seed/seed-store.js

@@ -82,14 +82,51 @@ async function waitForCatalogV3(ctx, { attempts = 40, delayMs = 2000 } = {}) {
   }
 }
 
-// plain string -> Wix rich-text description node tree (plainDescription is HTML/nodes, not text)
+// description string -> Wix rich-text node tree.
+//
+// Descriptions arrive as HTML as often as not: asked to describe a product, a model writes
+// <p>…</p><strong>Care:</strong><br/>. The writable field is `description` (Ricos nodes) — the HTML
+// `plainDescription` the storefront renders is read-only, derived from them. So markup dropped into
+// a single TEXT node is stored as literal text, comes back escaped, and the PDP shows the tags to
+// the buyer. Convert the tags a model actually emits; a string with no tags stays one paragraph.
+const HTML_ENTITIES = { "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#39;": "'", "&nbsp;": " " };
+
+function decodeEntities(s) {
+  return s.replace(/&(?:amp|lt|gt|quot|#39|nbsp);/g, (m) => HTML_ENTITIES[m] ?? m);
+}
+
+// One paragraph's inner HTML -> TEXT nodes, carrying bold/italic as Ricos decorations.
+function mkTextNodes(html) {
+  const nodes = [];
+  let bold = 0, italic = 0, last = 0, m;
+  const tag = /<(\/?)(strong|b|em|i)\s*\/?>/gi;
+  const push = (raw) => {
+    const text = decodeEntities(raw.replace(/<[^>]*>/g, ""));
+    if (!text) return;
+    const decorations = [];
+    if (bold > 0) decorations.push({ type: "BOLD" });
+    if (italic > 0) decorations.push({ type: "ITALIC" });
+    nodes.push({ type: "TEXT", textData: { text, decorations } });
+  };
+  while ((m = tag.exec(html)) !== null) {
+    push(html.slice(last, m.index));
+    const step = m[1] ? -1 : 1;
+    if (/^(strong|b)$/i.test(m[2])) bold = Math.max(0, bold + step);
+    else italic = Math.max(0, italic + step);
+    last = tag.lastIndex;
+  }
+  push(html.slice(last));
+  return nodes.length ? nodes : [{ type: "TEXT", textData: { text: "", decorations: [] } }];
+}
+
 function mkDesc(text, i) {
+  const blocks = String(text ?? "").split(/<\/p\s*>|<br\s*\/?>/i).map((b) => b.trim()).filter(Boolean);
   return {
-    nodes: [{
-      type: "PARAGRAPH", id: `desc-${i}`,
-      nodes: [{ type: "TEXT", textData: { text: text || "" } }],
+    nodes: (blocks.length ? blocks : [""]).map((block, n) => ({
+      type: "PARAGRAPH", id: `desc-${i}-${n}`,
+      nodes: mkTextNodes(block),
       paragraphData: { textStyle: { textAlignment: "AUTO" } },
-    }],
+    })),
     metadata: { version: 1, id: `desc-meta-${i}` },
   };
 }
@@ -157,6 +194,8 @@ async function listProducts(ctx) {
  * Bulk-create products.
  * @param products [{ name, description, price, compareAtPrice?, quantity,
  *   options?: [{ name, type?:"text"|"color", choices:["8","9"] | [{name,colorCode}] }] }]
+ *   description: plain text, or simple HTML (`<p>`, `<br/>`, `<strong>`, `<em>`) — converted to
+ *   Wix rich text here, so the storefront renders paragraphs and bold rather than tag text.
  *   options = ONLY things the buyer selects-and-buys (Size, Color) -> become variants.
  *   Display-only attributes go in name/category/description, NOT options. Default: no options.
  *   visible/physicalProperties/variant-expansion handled here. `quantity` is the stock created.