@wix/agent-skills 1.20.0 → 1.20.1

package/skills/wix-headless-fast/references/storefront/app/components/storefront/OptionPicker.tsx

@@ -0,0 +1,95 @@
+// The purchase controls for one product — option groups (swatches for a color option, pills
+// otherwise, out-of-stock choices disabled), choice modifiers, an optional quantity stepper, and
+// the buy button gated by the hook: disabled with a plain reason ("Choose Size") until every
+// choice is made, "Pre-order" when the resolved variant is pre-orderable, the hook's error inline.
+// QuickAdd's picker and your product page mount the same component, so buying behaves the same
+// in the gallery and on the PDP. Wire as-is; style via the tokens.
+//
+//   const d = useProductDetail({ initial });            // the PDP
+//   <OptionPicker detail={d} showQuantity />
+//
+// Price, name, gallery, description, and layout stay yours — render d.price / d.compareAtPrice
+// beside this (the range until every option is picked, then the variant's price).
+import type { UseProductDetail } from "../../hooks/storefront/useProductDetail";
+
+export default function OptionPicker({
+  detail: d,
+  showQuantity = false,
+  onAdded,
+}: {
+  detail: UseProductDetail;
+  /** The PDP shows a quantity stepper; a tile picker adds one. */
+  showQuantity?: boolean;
+  /** Called after a successful add (a tile picker closes itself here). */
+  onAdded?: () => void;
+}) {
+  if (!d.product) return null;
+  return (
+    <div className="flex flex-col gap-3">
+      {d.optionGroups.map((g) => (
+        <fieldset key={g.id}>
+          <legend className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">{g.name}</legend>
+          <div className="flex flex-wrap gap-1.5">
+            {g.choices.map((c) =>
+              g.isColor && c.colorCode ? (
+                <button key={c.choiceId} type="button" aria-label={c.name} title={c.name} aria-pressed={c.selected}
+                  disabled={!c.inStock} onClick={() => d.selectOption(g.name, c.name)}
+                  className={`h-8 w-8 rounded-full border-2 disabled:opacity-30 ${c.selected ? "border-foreground" : "border-border"}`}
+                  style={{ backgroundColor: c.colorCode }} />
+              ) : (
+                <button key={c.choiceId} type="button" aria-pressed={c.selected} disabled={!c.inStock}
+                  onClick={() => d.selectOption(g.name, c.name)}
+                  className={`rounded-full border px-3 py-1 text-sm disabled:line-through disabled:opacity-40 ${c.selected ? "border-foreground bg-foreground text-background" : "border-border"}`}>
+                  {c.name}
+                </button>
+              ),
+            )}
+          </div>
+        </fieldset>
+      ))}
+      {d.product.modifiers.filter((m) => m.type === "choices").map((m) => (
+        <fieldset key={m.key}>
+          <legend className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            {m.name}{m.mandatory ? " *" : ""}
+          </legend>
+          <div className="flex flex-wrap gap-1.5">
+            {m.choices.map((c) => (
+              <button key={c.key} type="button" aria-pressed={d.modifierValues[m.key] === c.key}
+                onClick={() => d.setModifier(m.key, c.key)}
+                className={`rounded-full border px-3 py-1 text-sm ${d.modifierValues[m.key] === c.key ? "border-foreground bg-foreground text-background" : "border-border"}`}>
+                {c.name}
+              </button>
+            ))}
+          </div>
+        </fieldset>
+      ))}
+      {d.product.modifiers.filter((m) => m.type === "text").map((m) => (
+        <label key={m.key} className="flex flex-col gap-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+          {m.name}{m.mandatory ? " *" : ""}
+          <input type="text" value={d.modifierValues[m.key] ?? ""} onChange={(e) => d.setModifier(m.key, e.target.value)}
+            className="rounded-md border border-border bg-background px-3 py-2 text-sm normal-case tracking-normal text-foreground" />
+        </label>
+      ))}
+      <div className="flex items-stretch gap-2">
+        {showQuantity && (
+          <div className="flex items-center rounded-full border border-border">
+            <button type="button" aria-label="Decrease quantity" disabled={d.quantity <= 1} onClick={() => d.setQuantity(d.quantity - 1)}
+              className="px-3 py-2 text-sm disabled:opacity-40">−</button>
+            <span className="min-w-6 text-center text-sm tabular-nums">{d.quantity}</span>
+            <button type="button" aria-label="Increase quantity" onClick={() => d.setQuantity(d.quantity + 1)} className="px-3 py-2 text-sm">+</button>
+          </div>
+        )}
+        <button
+          type="button"
+          disabled={!d.canAdd || d.adding}
+          onClick={() => d.add().then(() => onAdded?.()).catch(() => {})}
+          className="flex-1 rounded-full bg-primary py-2.5 text-sm font-semibold text-primary-foreground disabled:opacity-50"
+        >
+          {d.adding ? "Adding…" : d.isPreorder ? "Pre-order" : "Add to cart"}
+        </button>
+      </div>
+      {d.blockedReason && !d.canAdd && <p className="text-xs text-muted-foreground">{d.blockedReason}</p>}
+      {d.error && <p className="text-xs text-red-600">{d.error}</p>}
+    </div>
+  );
+}

package/skills/wix-headless-fast/references/storefront/app/components/storefront/QuickAdd.tsx

@@ -3,25 +3,45 @@
 //   • options / choice mods → Quick Add: a picker on the card (bottom sheet on small screens)
 //   • free-text modifier    → the product page (the gallery can't collect the text)
 // Mount as the LAST ROW of the tile's text block (under name and price), as a direct child of the
-// tile root that carries `relative` — the picker anchors to that root and takes its width. Never
-// overlay it on the image, never wrap it in a narrower positioned box.
+// tile root that carries `relative flex flex-col` — the picker anchors to that root and takes its
+// width, and the control pins itself to the tile's bottom (mt-auto) so the action row lines up
+// across a grid row whether or not a neighbour carries swatches or a struck price. Never overlay
+// it on the image, never wrap it in a narrower positioned box.
 //   <QuickAdd product={p} />   Wire as-is; style via the tokens.
 import { useEffect, useRef, useState } from "react";
 import { useCart } from "../../hooks/storefront/useCart";
 import { useProductDetail } from "../../hooks/storefront/useProductDetail";
 import type { ProductSummary } from "../../wix/storefront/types";
+import OptionPicker from "./OptionPicker";
 
 export default function QuickAdd({ product }: { product: ProductSummary }) {
+  return (
+    // A tile is often one big <a>. A click inside the buy control must never become a navigation
+    // to the product page — this boundary cancels the link's default for everything below it
+    // (the button, the picker, the sheet). Still: keep the control OUTSIDE the tile's link.
+    <div
+      className="contents"
+      onClick={(e) => {
+        e.preventDefault();
+        e.stopPropagation();
+      }}
+    >
+      <QuickAddControl product={product} />
+    </div>
+  );
+}
+
+function QuickAddControl({ product }: { product: ProductSummary }) {
   const { addToCart, busy } = useCart();
   const [open, setOpen] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
   if (product.availability === "OUT_OF_STOCK" && !product.preorder) {
-    return <span className="text-sm text-muted-foreground">Out of stock</span>;
+    return <span className="mt-auto block pt-3 text-sm text-muted-foreground">Out of stock</span>;
   }
   if (product.quickAddable) {
     return (
-      <div>
+      <div className="mt-auto pt-3">
         <button
           type="button"
           disabled={busy}
@@ -39,7 +59,7 @@ export default function QuickAdd({ product }: { product: ProductSummary }) {
   // Options to pick, or a single variant that isn't plainly in stock (pre-order, partial stock):
   // the picker resolves it through useProductDetail, exactly as the PDP would.
   return (
-    <>
+    <div className="mt-auto pt-3">
       <button
         type="button"
         onClick={() => setOpen(true)}
@@ -48,11 +68,12 @@ export default function QuickAdd({ product }: { product: ProductSummary }) {
         {product.optionsSummary ? "Choose options" : product.preorder ? "Pre-order" : "Add to cart"}
       </button>
       {open && <QuickAddPicker product={product} onClose={() => setOpen(false)} />}
-    </>
+    </div>
   );
 }
 
-// The picker fetches the full product only when it opens — cards never carry PDP data.
+// The picker fetches the full product only when it opens — cards never carry PDP data. Its controls
+// are the shipped OptionPicker, the same component the PDP mounts.
 function QuickAddPicker({ product, onClose }: { product: ProductSummary; onClose: () => void }) {
   const d = useProductDetail({ slug: product.slug });
   const panelRef = useRef<HTMLElement>(null);
@@ -108,57 +129,7 @@ function QuickAddPicker({ product, onClose }: { product: ProductSummary; onClose
           </a>
         )}
 
-        {d.product && !needsPdp && (
-          <div className="flex flex-col gap-3">
-            {d.optionGroups.map((g) => (
-              <fieldset key={g.id}>
-                <legend className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">{g.name}</legend>
-                <div className="flex flex-wrap gap-1.5">
-                  {g.choices.map((c) =>
-                    g.isColor && c.colorCode ? (
-                      <button key={c.choiceId} type="button" aria-label={c.name} title={c.name} aria-pressed={c.selected}
-                        disabled={!c.inStock} onClick={() => d.selectOption(g.name, c.name)}
-                        className={`h-8 w-8 rounded-full border-2 disabled:opacity-30 ${c.selected ? "border-foreground" : "border-border"}`}
-                        style={{ backgroundColor: c.colorCode }} />
-                    ) : (
-                      <button key={c.choiceId} type="button" aria-pressed={c.selected} disabled={!c.inStock}
-                        onClick={() => d.selectOption(g.name, c.name)}
-                        className={`rounded-full border px-3 py-1 text-sm disabled:line-through disabled:opacity-40 ${c.selected ? "border-foreground bg-foreground text-background" : "border-border"}`}>
-                        {c.name}
-                      </button>
-                    ),
-                  )}
-                </div>
-              </fieldset>
-            ))}
-            {d.product.modifiers.filter((m) => m.type === "choices").map((m) => (
-              <fieldset key={m.key}>
-                <legend className="mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
-                  {m.name}{m.mandatory ? " *" : ""}
-                </legend>
-                <div className="flex flex-wrap gap-1.5">
-                  {m.choices.map((c) => (
-                    <button key={c.key} type="button" aria-pressed={d.modifierValues[m.key] === c.key}
-                      onClick={() => d.setModifier(m.key, c.key)}
-                      className={`rounded-full border px-3 py-1 text-sm ${d.modifierValues[m.key] === c.key ? "border-foreground bg-foreground text-background" : "border-border"}`}>
-                      {c.name}
-                    </button>
-                  ))}
-                </div>
-              </fieldset>
-            ))}
-            <button
-              type="button"
-              disabled={!d.canAdd || d.adding}
-              onClick={() => d.add().then(onClose).catch(() => {})}
-              className="rounded-full bg-primary py-2.5 text-sm font-semibold text-primary-foreground disabled:opacity-50"
-            >
-              {d.adding ? "Adding…" : d.isPreorder ? "Pre-order" : "Add to cart"}
-            </button>
-            {d.blockedReason && !d.canAdd && <p className="text-xs text-muted-foreground">{d.blockedReason}</p>}
-            {d.error && <p className="text-xs text-red-600">{d.error}</p>}
-          </div>
-        )}
+        {d.product && !needsPdp && <OptionPicker detail={d} onAdded={onClose} />}
       </section>
     </>
   );

package/skills/wix-headless-fast/references/storefront/app/hooks/storefront/useProductDetail.ts

@@ -1,173 +1,39 @@
-// Product detail state: option selection → variant resolution → add-to-cart, plus modifier
-// inputs. This is the logic the turtle-run class of bugs comes from (adding variants[0]
-// regardless of the buyer's choice) — always drive a PDP through this hook.
+// React binding of the product-detail store (wix/storefront/product-detail-store.ts) — option
+// selection → variant resolution → add-to-cart lives there, framework-free. Always drive a PDP or
+// quick-add picker through this hook (or the store): resolving variants by hand is where
+// "added variants[0] regardless of the buyer's choice" comes from.
 //
-// SSR-friendly: pass the server-fetched ProductDetail as `initial` (Astro/Next); in a SPA
-// pass the slug and it fetches on mount.
-import { useEffect, useMemo, useState } from "react";
-import { fetchProductBySlug, resolveVariant } from "../../wix/storefront/catalog";
-import type { ProductDetail, ProductOption, ProductVariant } from "../../wix/storefront/types";
-import { useCart } from "./useCart";
+// SSR-friendly: pass the server-fetched ProductDetail as `initial` (Astro/Next); in a SPA pass
+// the slug and it fetches on mount.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import {
+  createProductDetailStore,
+  type ProductDetailState,
+  type ProductDetailStore,
+  type ProductDetailStoreOptions,
+} from "../../wix/storefront/product-detail-store";
 
-export interface UseProductDetailOptions {
-  initial?: ProductDetail | null;
-  slug?: string;
-}
+export { type OptionGroupView } from "../../wix/storefront/product-detail-store";
 
-export interface OptionGroupView extends ProductOption {
-  choices: (ProductOption["choices"][number] & { selected: boolean })[];
-}
+export type UseProductDetailOptions = ProductDetailStoreOptions;
 
-export interface UseProductDetail {
-  /** null while loading (or when the slug doesn't resolve — check notFound). */
-  product: ProductDetail | null;
-  notFound: boolean;
-  /** Option groups with per-choice `selected`, ready to render as pills/swatches. */
-  optionGroups: OptionGroupView[];
-  selectOption: (optionName: string, choiceName: string) => void;
-  /** Modifier inputs keyed by modifier key. */
-  modifierValues: Record<string, string>;
-  setModifier: (key: string, value: string) => void;
-  /** The resolved variant; null while the selection is incomplete. */
-  variant: ProductVariant | null;
-  /**
-   * Price to display right now: the product RANGE ("€24.99 – €34.99", one value when equal) until
-   * every option is picked, then the selected variant's price (an automatic discount applied).
-   */
-  price: string;
-  /** Struck "was" price — only once a variant is resolved (or for a single-price product), never beside a range. */
-  compareAtPrice: string | null;
-  /** The resolved variant is out of stock but pre-orderable — label the action "Pre-order". */
-  isPreorder: boolean;
-  /** False until every option is selected and the resolved variant is in stock or pre-orderable. */
-  canAdd: boolean;
-  /**
-   * Why the action is disabled — neutral guidance to render beside it ("Choose Size"), not an
-   * error; null when the buyer can add. Promote to error styling only after they try to buy.
-   */
-  blockedReason: string | null;
-  quantity: number;
-  setQuantity: (n: number) => void;
-  /** Adds the resolved variant to the cart (opens the drawer). Throws on refusal. */
-  add: () => Promise<void>;
-  adding: boolean;
-  error: string | null;
-}
+export type UseProductDetail = ProductDetailState &
+  Pick<ProductDetailStore, "selectOption" | "setModifier" | "setQuantity" | "add">;
 
 export function useProductDetail({ initial, slug }: UseProductDetailOptions): UseProductDetail {
-  const [product, setProduct] = useState<ProductDetail | null>(initial ?? null);
-  const [notFound, setNotFound] = useState(false);
-  const [selections, setSelections] = useState<Record<string, string>>({});
-  const [modifierValues, setModifierValues] = useState<Record<string, string>>({});
-  const [quantity, setQuantity] = useState(1);
-  const [adding, setAdding] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const { addToCart } = useCart();
-
+  const ref = useRef<{ slug?: string; store: ProductDetailStore } | null>(null);
+  if (!ref.current || ref.current.slug !== slug) ref.current = { slug, store: createProductDetailStore({ initial, slug }) };
+  const store = ref.current.store;
   useEffect(() => {
-    if (initial || !slug) return;
-    let alive = true;
-    fetchProductBySlug(slug)
-      .then((p) => {
-        if (!alive) return;
-        setProduct(p);
-        setNotFound(p === null);
-      })
-      .catch(() => alive && setNotFound(true));
-    return () => {
-      alive = false;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [slug]);
-
-  const variant = useMemo(
-    () => (product ? resolveVariant(product, selections) : null),
-    [product, selections],
-  );
-
-  const optionGroups: OptionGroupView[] = useMemo(
-    () =>
-      (product?.options ?? []).map((o) => ({
-        ...o,
-        choices: o.choices.map((c) => ({ ...c, selected: selections[o.name] === c.name })),
-      })),
-    [product, selections],
-  );
-
-  const missingModifier = (product?.modifiers ?? []).find(
-    (m) => m.mandatory && (modifierValues[m.key] ?? "").length === 0,
-  );
-  const missingOptions = (product?.options ?? []).filter((o) => !selections[o.name]).map((o) => o.name);
-  const selectionComplete = missingOptions.length === 0;
-
-  // In stock OR pre-orderable counts as buyable; a preorder add carries preOrderRequested.
-  const isPreorder = !!variant && !variant.inStock && variant.preorderEnabled;
-  const available = !!variant && (variant.inStock || variant.preorderEnabled);
-
-  const canAdd = !!product && available && !missingModifier;
-
-  const blockedReason: string | null = !product
-    ? null
-    : !selectionComplete
-      ? `Choose ${missingOptions.join(" and ")}`
-      : !variant
-        ? "This combination isn't available"
-        : !available
-          ? "Out of stock"
-          : missingModifier
-            ? `Add ${missingModifier.name}`
-            : null;
-
-  // Before every option is picked, the range — never an empty price, never a lone struck minimum.
-  const isRange = !!product && product.price !== product.maxPrice && !!product.maxPrice;
-  const rangeDisplay = product ? (isRange ? `${product.price} – ${product.maxPrice}` : product.price) : "";
-
-  async function add(): Promise<void> {
-    if (!product || !variant) return;
-    setAdding(true);
-    setError(null);
-    try {
-      const choiceModifiers: Record<string, string> = {};
-      const textModifiers: Record<string, string> = {};
-      for (const m of product.modifiers) {
-        const value = modifierValues[m.key];
-        if (!value) continue;
-        if (m.type === "text") textModifiers[m.key] = value;
-        else choiceModifiers[m.key] = value;
-      }
-      await addToCart(product.id, variant.variantId, quantity, {
-        modifierChoices: choiceModifiers,
-        customTextFields: textModifiers,
-        preorder: isPreorder,
-      });
-    } catch (e) {
-      setError(e instanceof Error ? e.message : String(e));
-      throw e;
-    } finally {
-      setAdding(false);
-    }
-  }
-
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
   return {
-    product,
-    notFound,
-    optionGroups,
-    selectOption: (optionName, choiceName) => {
-      setSelections((s) => ({ ...s, [optionName]: choiceName }));
-      setQuantity(1); // the ceiling belongs to the newly resolved variant
-    },
-    modifierValues,
-    setModifier: (key, value) => setModifierValues((v) => ({ ...v, [key]: value })),
-    variant,
-    price: variant?.price || rangeDisplay,
-    compareAtPrice: variant ? variant.compareAtPrice : isRange ? null : (product?.compareAtPrice ?? null),
-    isPreorder,
-    canAdd,
-    blockedReason,
-    quantity,
-    setQuantity,
-    add,
-    adding,
-    error,
+    ...state,
+    selectOption: store.selectOption,
+    setModifier: store.setModifier,
+    setQuantity: store.setQuantity,
+    add: store.add,
   };
 }