@wix/agent-skills 1.19.2 → 1.20.1

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

@@ -1,140 +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 (variant price once resolved, else the product range). */
-  price: string;
-  compareAtPrice: string | null;
-  /** False until every option is selected (and the resolved variant is in stock). */
-  canAdd: boolean;
-  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 mandatoryModifiersFilled = (product?.modifiers ?? [])
-    .filter((m) => m.mandatory)
-    .every((m) => (modifierValues[m.key] ?? "").length > 0);
-
-  const canAdd =
-    !!product &&
-    product.availability !== "OUT_OF_STOCK" &&
-    variant !== null &&
-    variant.inStock &&
-    mandatoryModifiersFilled;
-
-  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,
-      });
-    } 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 })),
-    modifierValues,
-    setModifier: (key, value) => setModifierValues((v) => ({ ...v, [key]: value })),
-    variant,
-    price: variant?.price || product?.price || "",
-    compareAtPrice: variant ? variant.compareAtPrice : (product?.compareAtPrice ?? null),
-    canAdd,
-    quantity,
-    setQuantity,
-    add,
-    adding,
-    error,
+    ...state,
+    selectOption: store.selectOption,
+    setModifier: store.setModifier,
+    setQuantity: store.setQuantity,
+    add: store.add,
   };
 }

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

@@ -1,190 +1,34 @@
-// Catalog listing for a shop surface: category filter, sort, price/stock/search filters, and
-// cursor paging — all applied by Wix across the whole catalog (searchCatalog), never to a page
-// already in hand. A changed selection starts a fresh cursor chain.
-//
-// SSR-friendly: pass `initialProducts`/`initialCategories` (Astro frontmatter) and they render
-// immediately — the hook still revalidates the first page once on mount to open the cursor
-// chain, replacing the seed without a skeleton flash.
-import { useCallback, useEffect, useRef, useState } from "react";
-import {
-  CATALOG_SORTS,
-  fetchCategories,
-  searchCatalog,
-  type CatalogSort,
-} from "../../wix/storefront/catalog";
-import type { Category, ProductSummary } from "../../wix/storefront/types";
+// React binding of the shop store (wix/storefront/shop-store.ts) — the listing state machine
+// lives there, framework-free; this hook subscribes to one instance per mounted listing and
+// exposes its state and actions under one name. Astro islands and React SPAs use this; a static
+// page, Vue, or Svelte uses the store directly.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createShopStore, type ShopState, type ShopStore, type ShopStoreOptions } from "../../wix/storefront/shop-store";
 
-export const SORTS = CATALOG_SORTS;
+export { SORTS, type ShopFilters } from "../../wix/storefront/shop-store";
 
-export interface ShopFilters {
-  minPrice?: number | string;
-  maxPrice?: number | string;
-  inStockOnly?: boolean;
-  /** Name search, max 100 chars. */
-  search?: string;
-}
-
-export interface UseShopOptions {
-  initialProducts?: ProductSummary[];
-  initialCategories?: Category[];
-  pageSize?: number;
-}
-
-export interface UseShop {
-  /** null while the first load is in flight — render skeletons, not an empty state. */
-  products: ProductSummary[] | null;
-  categories: Category[];
-  /** null = "all products". */
-  activeCategoryId: string | null;
-  setActiveCategoryId: (id: string | null) => void;
-  sort: CatalogSort;
-  setSort: (sort: CatalogSort) => void;
-  filters: ShopFilters;
-  setFilters: (filters: ShopFilters) => void;
-  loading: boolean;
-  error: string | null;
-  retry: () => void;
-  hasMore: boolean;
-  loadMore: () => Promise<void>;
-  loadingMore: boolean;
-}
-
-interface PageState {
-  key: string | null;
-  products: ProductSummary[] | null;
-  cursor: string | null;
-  error: string | null;
-  loadingMore: boolean;
-}
+export type UseShopOptions = ShopStoreOptions;
 
-export function useShop({
-  initialProducts,
-  initialCategories,
-  pageSize = 24,
-}: UseShopOptions = {}): UseShop {
-  const [categories, setCategories] = useState<Category[]>(initialCategories ?? []);
-  const [activeCategoryId, setActiveCategoryId] = useState<string | null>(null);
-  const [sort, setSort] = useState<CatalogSort>("featured");
-  const [filters, setFilters] = useState<ShopFilters>({});
-  const [attempt, setAttempt] = useState(0);
-  const [page, setPage] = useState<PageState>({
-    key: null,
-    products: initialProducts ?? null,
-    cursor: null,
-    error: null,
-    loadingMore: false,
-  });
-  const generation = useRef(0);
-  const pendingMore = useRef<object | null>(null);
-
-  const key = JSON.stringify([
-    pageSize,
-    activeCategoryId,
-    sort,
-    filters.minPrice ?? null,
-    filters.maxPrice ?? null,
-    !!filters.inStockOnly,
-    filters.search ?? "",
-    attempt,
-  ]);
-  const currentKey = useRef(key);
-  currentKey.current = key;
-
-  useEffect(() => {
-    if (initialCategories) return;
-    let alive = true;
-    fetchCategories().then((list) => alive && setCategories(list)).catch(() => alive && setCategories([]));
-    return () => {
-      alive = false;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+export type UseShop = ShopState &
+  Pick<ShopStore, "setActiveCategoryId" | "setSort" | "setFilters" | "toggleChoice" | "clearFilters" | "retry" | "loadMore">;
 
+export function useShop(options: UseShopOptions = {}): UseShop {
+  const ref = useRef<ShopStore | null>(null);
+  if (!ref.current) ref.current = createShopStore(options);
+  const store = ref.current;
   useEffect(() => {
-    const id = ++generation.current;
-    let alive = true;
-    pendingMore.current = null;
-    // Keep the SSR seed (or the previous page) on screen while the fresh query runs;
-    // only a selection change with no seed shows skeletons.
-    setPage((p) => ({ key, products: p.key === null ? p.products : null, cursor: null, error: null, loadingMore: false }));
-    const [limit, categoryId, selectedSort, minPrice, maxPrice, inStockOnly, search] = JSON.parse(key);
-    searchCatalog({ limit, categoryId, sort: selectedSort, minPrice, maxPrice, inStockOnly, search })
-      .then((res) => {
-        if (alive && generation.current === id && currentKey.current === key) {
-          setPage({ key, products: res.products, cursor: res.nextCursor, error: null, loadingMore: false });
-        }
-      })
-      .catch((e) => {
-        if (alive && generation.current === id && currentKey.current === key) {
-          setPage({
-            key,
-            products: [],
-            cursor: null,
-            error: e instanceof Error ? e.message : "Couldn't load products.",
-            loadingMore: false,
-          });
-        }
-      });
-    return () => {
-      alive = false;
-      generation.current++;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [key]);
-
-  const loadMore = useCallback(async () => {
-    if (page.key !== key || !page.cursor || pendingMore.current) return;
-    const request = { generation: generation.current, key };
-    pendingMore.current = request; // blocks repeated clicks before React rerenders
-    const isCurrent = () => generation.current === request.generation && currentKey.current === key;
-    setPage((p) => ({ ...p, loadingMore: true, error: null }));
-    try {
-      const res = await searchCatalog({ limit: pageSize, cursor: page.cursor });
-      if (isCurrent())
-        setPage((p) => {
-          const seen = new Set((p.products ?? []).map((product) => product.id));
-          return {
-            ...p,
-            products: [
-              ...(p.products ?? []),
-              ...res.products.filter((product) => {
-                if (seen.has(product.id)) return false;
-                seen.add(product.id);
-                return true;
-              }),
-            ],
-            cursor: res.nextCursor,
-          };
-        });
-    } catch (e) {
-      if (isCurrent())
-        setPage((p) => ({ ...p, error: e instanceof Error ? e.message : "Couldn't load more products." }));
-    } finally {
-      if (pendingMore.current === request) pendingMore.current = null;
-      if (isCurrent()) setPage((p) => ({ ...p, loadingMore: false }));
-    }
-  }, [key, page.key, page.cursor, pageSize]);
-
-  const retry = useCallback(() => setAttempt((n) => n + 1), []);
-
-  const current = page.key === key;
-  const seeded = page.key === null && page.products !== null; // SSR seed, first query in flight
-  // Seeded content on screen is not "loading" — skeletons are only for a genuinely empty wait.
-  const loading = (!current && !seeded) || (current && page.products === null);
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
   return {
-    categories,
-    activeCategoryId,
-    setActiveCategoryId,
-    sort,
-    setSort,
-    filters,
-    setFilters,
-    products: current || seeded ? page.products : null,
-    loading,
-    error: current ? page.error : null,
-    retry,
-    hasMore: current && !!page.cursor,
-    loadMore,
-    loadingMore: current && page.loadingMore,
+    ...state,
+    setActiveCategoryId: store.setActiveCategoryId,
+    setSort: store.setSort,
+    setFilters: store.setFilters,
+    toggleChoice: store.toggleChoice,
+    clearFilters: store.clearFilters,
+    retry: store.retry,
+    loadMore: store.loadMore,
   };
 }

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/cart-core.ts

@@ -0,0 +1,121 @@
+// Cart rules and DTO mapping — transport-agnostic, imported by both ./cart.ts (SDK) and the REST
+// twin in references/storefront/rest/cart.ts (fetch). Raw Cart V2 entities may carry `_id` (SDK)
+// or `id` (REST). Has its own formatMoney (a copy of ../money.ts) so it stands alone when stripped.
+import type { Cart, CartLine } from "./types";
+import type { ImgSrc, Raw } from "./catalog-core";
+
+/** Public app id of the Wix Stores catalog — required inside every catalogReference. */
+export const WIX_STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+
+export const rawId = (raw: Raw | undefined | null): string => raw?._id ?? raw?.id ?? "";
+
+/**
+ * Cart V2 money is ConvertedMoney { amount, convertedAmount } with NO formatted string, and the
+ * currency lives on the cart, not on the money. Format with the buyer's display currency when
+ * present, else the site's. Never hardcode "$" or assume USD.
+ */
+export function formatMoney(money: Raw | null | undefined, currencyCode: string | null | undefined): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}
+
+export const cartCurrency = (raw: Raw | null | undefined): string =>
+  raw?.customerInfo?.currencyCode ?? raw?.businessInfo?.currencyCode ?? "";
+
+/**
+ * "Monthly plan · every 2 months · 6 payments" from the line's subscriptionInfo (Cart V2 carries
+ * the plan on the line); "" for a one-time purchase. Every word comes from the plan — a
+ * subscription line must read as one in the cart, never a generic "recurring".
+ */
+export function subscriptionTerms(info: Raw | undefined): string {
+  if (!info) return "";
+  const s: Raw = info.subscriptionSettings ?? {};
+  const unit: Record<string, string> = { DAY: "day", WEEK: "week", MONTH: "month", YEAR: "year" };
+  const parts: string[] = [];
+  const title = info.title?.original ?? info.title?.translated ?? "";
+  if (title) parts.push(title);
+  const u = unit[String(s.frequency ?? "")];
+  if (u) parts.push(`every ${s.interval && s.interval > 1 ? `${s.interval} ${u}s` : u}`);
+  if (!s.autoRenewal && s.billingCycles) parts.push(`${s.billingCycles} payments`);
+  return parts.join(" · ");
+}
+
+export function toLine(raw: Raw, currency: string, imgSrc: ImgSrc): CartLine {
+  return {
+    lineItemId: rawId(raw), // the LINE id — what update/remove take, never the product id
+    productName: raw.name?.original ?? "",
+    quantity: raw.quantityInfo?.confirmedQuantity ?? 0,
+    unitPrice: formatMoney(raw.pricing?.unitPrice, currency),
+    linePrice: formatMoney(raw.pricing?.totalPrice, currency),
+    imageUrl: imgSrc(raw.attributes?.image, 300, 300),
+    descriptionLines: ((raw.attributes?.descriptionLines ?? []) as Raw[])
+      .map((d) => {
+        const label = d.name?.original ?? "", value = d.plainText?.original ?? d.colorInfo?.original ?? "";
+        return label && value ? `${label}: ${value}` : value || label;
+      })
+      .filter(Boolean),
+    status: raw.status ?? "IN_STOCK", // not IN_STOCK → the line can't be checked out as-is
+    subscription: subscriptionTerms(raw.subscriptionInfo),
+  };
+}
+
+export function toCart(raw: Raw | null, subtotal: string, discount: string, imgSrc: ImgSrc): Cart {
+  const currency = cartCurrency(raw);
+  const lines = ((raw?.lineItems ?? []) as Raw[]).map((l) => toLine(l, currency, imgSrc));
+  return { lines, itemCount: lines.reduce((n, l) => n + l.quantity, 0), subtotal, discount, currency };
+}
+
+/** The after-discount subtotal and the CART-level discount from an estimate; "" when unknown. */
+export function summaryTotals(estimate: Raw | null | undefined, raw: Raw): { subtotal: string; discount: string } {
+  const s = estimate?.summary?.priceSummary;
+  const currency = cartCurrency(raw);
+  const d = s?.discount;
+  return {
+    subtotal: formatMoney(s?.subtotal, currency),
+    discount: Number(d?.convertedAmount ?? d?.amount ?? 0) > 0 ? formatMoney(d, currency) : "",
+  };
+}
+
+/** The catalogReference.options object for an add — omits every key the buyer didn't use. */
+export function addOptions({ variantId, modifierChoices, customTextFields, subscriptionOptionId, preorder }: {
+  variantId?: string | null; modifierChoices?: Record<string, string>; customTextFields?: Record<string, string>;
+  subscriptionOptionId?: string; preorder?: boolean;
+}): Raw {
+  const o: Raw = {};
+  if (variantId) o.variantId = variantId;                                            // REQUIRED for any product with options
+  if (modifierChoices && Object.keys(modifierChoices).length) o.options = modifierChoices; // MODIFIERS only, never Size/Color
+  if (customTextFields && Object.keys(customTextFields).length) o.customTextFields = customTextFields;
+  if (subscriptionOptionId) o.subscriptionOptionId = subscriptionOptionId;
+  if (preorder) o.preOrderRequested = true;
+  return o;
+}
+
+/** Read the add result — a refused add still returns 200: a line whose status isn't IN_STOCK, or no line, is a refusal. */
+export function assertAdded(cart: Raw | null | undefined, productId: string, variantId?: string | null): void {
+  const line = ((cart?.lineItems ?? []) as Raw[]).find(
+    (l) => l.source?.catalogReference?.catalogItemId === productId && (!variantId || l.source?.catalogReference?.options?.variantId === variantId),
+  );
+  if (line?.status && line.status !== "IN_STOCK") {
+    throw new Error(`This item isn't available right now (${String(line.status).toLowerCase().replace(/_/g, " ")}).`);
+  }
+  if (!line || line.quantityInfo?.confirmedQuantity === 0) {
+    throw new Error("The item couldn't be added. Make sure every required selection was made (options for a product with variants, and all mandatory customizations).");
+  }
+}
+
+/** Refuse checkout for an empty cart or any line not IN_STOCK — say which. */
+export function assertCheckoutable(raw: Raw | null): void {
+  const lines: Raw[] = raw?.lineItems ?? [];
+  if (!lines.length) throw new Error("Your cart is empty.");
+  const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
+  if (unavailable.length) {
+    throw new Error(`Some items are no longer available: ${unavailable.map((l) => l.name?.original).filter(Boolean).join(", ")}.`);
+  }
+  if (!rawId(raw)) throw new Error("Checkout couldn't start: the cart has no id.");
+}