@wix/agent-skills 1.26.0 → 1.28.0

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

@@ -0,0 +1,171 @@
+// The purchase controls for one product — option groups (swatches for a color option, pills
+// otherwise, choices unavailable WITH the current selection disabled), choice and free-text
+// modifiers (with the merchant's character limit), the plan picker for a subscription product, an
+// optional quantity stepper capped at the stock left, and the buy button gated by the hook:
+// disabled with a plain reason ("Choose Size") until every choice is made, "Pre-order" (with the
+// merchant's pre-order note) when the resolved variant is pre-orderable, "Only N left" when stock
+// runs low, an email form to be notified when a sold-out item returns, 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 /
+// d.pricePerUnit beside this (the range until every option is picked, then the variant's price).
+import { useState } from "react";
+import { ONE_TIME_PLAN, 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;
+  const legend = "mb-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground";
+  return (
+    <div className="flex flex-col gap-3">
+      {d.optionGroups.map((g) => (
+        <fieldset key={g.id}>
+          <legend className={legend}>{g.name}</legend>
+          <div className="flex flex-wrap gap-1.5">
+            {g.choices.map((c) => {
+              // unavailable = sold out with the other picks, or no variant has this combination
+              const unavailable = !c.inStock || !c.exists;
+              return g.isColor && c.colorCode ? (
+                <button key={c.choiceId} type="button" aria-label={c.name} title={unavailable ? `${c.name} (unavailable)` : c.name} aria-pressed={c.selected}
+                  disabled={unavailable} onClick={() => d.selectOption(g.id, c.choiceId)}
+                  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={unavailable}
+                  onClick={() => d.selectOption(g.id, c.choiceId)}
+                  className={`rounded-control 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={legend}>
+            {m.name}{m.mandatory ? " *" : ""}
+          </legend>
+          <div className="flex flex-wrap gap-1.5">
+            {m.choices.map((c) => {
+              const on = d.modifierValues[m.key] === c.key;
+              return (
+                <button key={c.key} type="button" aria-pressed={on}
+                  // an optional modifier can be un-picked; a mandatory one only re-picked
+                  onClick={() => d.setModifier(m.key, on && !m.mandatory ? "" : c.key)}
+                  className={`rounded-control border px-3 py-1 text-sm ${on ? "border-foreground bg-foreground text-background" : "border-border"}`}>
+                  {c.name}
+                </button>
+              );
+            })}
+          </div>
+        </fieldset>
+      ))}
+      {d.product.modifiers.filter((m) => m.type === "text").map((m) => {
+        const value = d.modifierValues[m.key] ?? "";
+        return (
+          <label key={m.key} className={`flex flex-col gap-1.5 ${legend} mb-0`}>
+            <span className="flex justify-between">
+              <span>{m.title}{m.mandatory ? " *" : ""}</span>
+              {m.maxChars && <span className="tabular-nums normal-case tracking-normal">{value.length}/{m.maxChars}</span>}
+            </span>
+            <textarea rows={2} value={value} maxLength={m.maxChars ?? undefined} 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>
+        );
+      })}
+      {d.plans.length > 0 && (
+        <fieldset>
+          <legend className={legend}>Purchase option</legend>
+          <div className="flex flex-col gap-1.5">
+            {d.plans.map((p) => (
+              <label key={p.id} className={`flex cursor-pointer items-start justify-between gap-3 rounded-md border px-3 py-2 text-sm ${p.selected ? "border-foreground" : "border-border"}`}>
+                <span className="flex items-start gap-2">
+                  <input type="radio" name="purchase-option" className="mt-1" checked={p.selected} onChange={() => d.selectPlan(p.id)} />
+                  <span>
+                    <span className="font-medium">{p.name}</span>
+                    <span className="block text-xs text-muted-foreground">{p.terms}{p.description ? ` · ${p.description}` : ""}</span>
+                  </span>
+                </span>
+                {p.price && <span className="whitespace-nowrap tabular-nums">{p.price}</span>}
+              </label>
+            ))}
+            {d.product.allowOneTimePurchase && (
+              <label className={`flex cursor-pointer items-center gap-2 rounded-md border px-3 py-2 text-sm ${d.subscriptionPlanId === ONE_TIME_PLAN ? "border-foreground" : "border-border"}`}>
+                <input type="radio" name="purchase-option" checked={d.subscriptionPlanId === ONE_TIME_PLAN} onChange={() => d.selectPlan(ONE_TIME_PLAN)} />
+                <span className="font-medium">One-time purchase</span>
+                {d.variant && <span className="ml-auto tabular-nums">{d.variant.price}</span>}
+              </label>
+            )}
+          </div>
+        </fieldset>
+      )}
+      <div className="flex items-stretch gap-2">
+        {showQuantity && (
+          <div className="flex items-center rounded-control 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" disabled={d.quantity >= d.maxQuantity} onClick={() => d.setQuantity(d.quantity + 1)}
+              className="px-3 py-2 text-sm disabled:opacity-40">+</button>
+          </div>
+        )}
+        <button
+          type="button"
+          disabled={!d.canAdd || d.adding}
+          onClick={() => d.add().then(() => onAdded?.()).catch(() => {})}
+          className="flex-1 rounded-control 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.remaining !== null && d.remaining > 0 && d.remaining <= 10 && d.canAdd && !d.isPreorder && (
+        <p className="text-xs text-muted-foreground">Only {d.remaining} left in stock</p>
+      )}
+      {d.isPreorder && d.preorderMessage && <p className="text-xs text-muted-foreground">{d.preorderMessage}</p>}
+      {d.blockedReason && !d.canAdd && <p className="text-xs text-muted-foreground">{d.blockedReason}</p>}
+      {d.canNotify && <NotifyMe detail={d} />}
+      {d.error && <p className="text-xs text-destructive">{d.error}</p>}
+    </div>
+  );
+}
+
+// "Notify me when it's back": one email field; the store validates, calls Wix, and reports
+// "created" / "already-subscribed".
+function NotifyMe({ detail: d }: { detail: UseProductDetail }) {
+  const [email, setEmail] = useState("");
+  if (d.notifyResult === "created") return <p className="text-xs text-muted-foreground">We'll email you when it's back in stock.</p>;
+  if (d.notifyResult === "already-subscribed") return <p className="text-xs text-muted-foreground">You're already on the list for this item.</p>;
+  return (
+    <form
+      className="flex flex-col gap-1.5"
+      onSubmit={(e) => {
+        e.preventDefault();
+        d.notify(email).catch(() => {});
+      }}
+    >
+      <label className="text-xs font-medium uppercase tracking-wide text-muted-foreground" htmlFor="notify-email">Notify me when it's back</label>
+      <div className="flex gap-2">
+        <input id="notify-email" type="email" required value={email} onChange={(e) => setEmail(e.target.value)} placeholder="you@example.com"
+          className="min-w-0 flex-1 rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground" />
+        <button type="submit" disabled={d.notifying} className="rounded-control border border-foreground px-4 py-2 text-sm font-medium disabled:opacity-50">
+          {d.notifying ? "Saving…" : "Notify me"}
+        </button>
+      </div>
+      {d.notifyError && <p className="text-xs text-destructive">{d.notifyError}</p>}
+    </form>
+  );
+}

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

@@ -0,0 +1,148 @@
+// The card's purchase control — the gallery purchase paths, decided from the product:
+//   • no options            → Direct Add: one click, the cheapest variant, quantity 1
+//   • 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)
+//   • subscription plans    → the product page (the plan is chosen there, as on Wix's own storefront)
+// 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 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>
+  );
+}
+
+const control = "w-full rounded-control border border-foreground py-2 text-center text-sm font-medium transition-colors hover:bg-foreground hover:text-background disabled:opacity-50";
+
+function QuickAddControl({ product }: { product: ProductSummary }) {
+  const { addToCart, pendingProductId } = useCart();
+  // This card's add only: the cart's `busy` is the drawer's flag, and binding to it dims every card.
+  const adding = pendingProductId === product.id;
+  const [open, setOpen] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  if (product.availability === "OUT_OF_STOCK" && !product.preorder) {
+    // the PDP offers "notify me" when the merchant collects requests; a tile only says so
+    return <a href={`/products/${encodeURIComponent(product.slug)}`} className="mt-auto block pt-3 text-sm text-muted-foreground">Out of stock</a>;
+  }
+  if (product.hasSubscriptions) {
+    return (
+      <div className="mt-auto pt-3">
+        <a href={`/products/${encodeURIComponent(product.slug)}`} className={`block ${control}`}>Choose a plan</a>
+      </div>
+    );
+  }
+  if (product.quickAddable) {
+    return (
+      <div className="mt-auto pt-3">
+        <button
+          type="button"
+          disabled={adding}
+          aria-busy={adding}
+          onClick={() =>
+            addToCart(product.id, product.minPriceVariantId, 1).catch((e) => setError(e instanceof Error ? e.message : String(e)))
+          }
+          className={control}
+        >
+          {adding ? "Adding…" : product.preorder ? "Pre-order" : "Add to cart"}
+        </button>
+        {error && <p className="mt-1 text-xs text-destructive">{error}</p>}
+      </div>
+    );
+  }
+  // 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)} className={control}>
+        {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. 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);
+
+  // Overlay contract: Escape closes, scroll locks under md, focus moves in and back.
+  useEffect(() => {
+    const opener = document.activeElement;
+    const isSmall = window.matchMedia("(max-width: 767px)").matches;
+    const previousOverflow = document.body.style.overflow;
+    if (isSmall) document.body.style.overflow = "hidden";
+    panelRef.current?.focus();
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose();
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = previousOverflow;
+      if (opener instanceof HTMLElement) opener.focus();
+    };
+  }, [onClose]);
+
+  // Free text and plans belong on the product page.
+  const needsPdp = (d.product?.modifiers ?? []).some((m) => m.type === "text") || (d.product?.subscriptions.length ?? 0) > 0;
+
+  return (
+    <>
+      <div className="fixed inset-0 z-40 bg-foreground/40 md:hidden" onClick={onClose} />
+      <section
+        ref={panelRef}
+        tabIndex={-1}
+        role="dialog"
+        aria-modal="true"
+        aria-label={`Choose options for ${product.name}`}
+        // md+: anchored to the tile (its nearest `relative` ancestor), the tile's full width — and never
+        // narrower than 18rem even when mounted inside a small wrapper.
+        className="fixed inset-x-0 bottom-0 z-50 max-h-[85vh] overflow-y-auto rounded-t-2xl bg-background p-5 text-foreground shadow-2xl outline-none md:absolute md:inset-x-auto md:bottom-0 md:right-0 md:w-[max(100%,18rem)] md:max-h-none md:rounded-lg md:p-4"
+      >
+        <div className="mb-3 flex items-start justify-between gap-3">
+          <div className="min-w-0">
+            <p className="truncate text-sm font-semibold">{product.name}</p>
+            <p className="text-sm">
+              {d.price}
+              {d.compareAtPrice && <span className="ml-2 text-muted-foreground line-through">{d.compareAtPrice}</span>}
+              {d.pricePerUnit && <span className="ml-2 text-xs text-muted-foreground">{d.pricePerUnit}</span>}
+            </p>
+          </div>
+          <button type="button" aria-label="Close" onClick={onClose} className="text-xl leading-none text-muted-foreground">×</button>
+        </div>
+
+        {!d.product && !d.notFound && <p className="text-sm text-muted-foreground">Loading options…</p>}
+        {d.notFound && <p className="text-sm text-muted-foreground">This product isn't available anymore.</p>}
+
+        {d.product && needsPdp && (
+          <a href={`/products/${encodeURIComponent(product.slug)}`} className="block rounded-control bg-primary py-2.5 text-center text-sm font-semibold text-primary-foreground">
+            Customize on the product page
+          </a>
+        )}
+
+        {d.product && !needsPdp && <OptionPicker detail={d} onAdded={onClose} />}
+      </section>
+    </>
+  );
+}

package/skills/wix-headless-templates/storefront/app/hooks/storefront/useCart.ts

@@ -0,0 +1,59 @@
+// React binding for the cart store. Works in any React root — Astro islands (several on one
+// page share the same store) and SPAs alike.
+import { useSyncExternalStore } from "react";
+import {
+  addLine,
+  applyCartCoupon,
+  getCartState,
+  goToCheckout,
+  refreshCart,
+  removeCartCoupon,
+  removeCartLine,
+  setCartNote,
+  setCartOpen,
+  subscribeCart,
+  updateLineQuantity,
+  type CartState,
+} from "../../wix/storefront/cart-store";
+import type { AddToCartExtras } from "../../wix/storefront/cart";
+
+const SERVER_STATE = getCartState();
+
+export interface UseCart extends CartState {
+  itemCount: number;
+  addToCart: (
+    productId: string,
+    variantId?: string | null,
+    quantity?: number,
+    extras?: AddToCartExtras,
+  ) => Promise<void>;
+  updateQuantity: (lineItemId: string, quantity: number) => Promise<void>;
+  removeLine: (lineItemId: string) => Promise<void>;
+  /** Apply a coupon code — rejects with buyer copy (and sets .error) when it can't be applied. */
+  applyCoupon: (code: string) => Promise<void>;
+  removeCoupon: () => Promise<void>;
+  /** Save the buyer's note to the merchant (call on blur). */
+  setNote: (note: string) => Promise<void>;
+  checkout: () => Promise<void>;
+  openCart: () => void;
+  closeCart: () => void;
+  refresh: () => Promise<void>;
+}
+
+export function useCart(): UseCart {
+  const state = useSyncExternalStore(subscribeCart, getCartState, () => SERVER_STATE);
+  return {
+    ...state,
+    itemCount: state.cart?.itemCount ?? 0,
+    addToCart: addLine,
+    updateQuantity: updateLineQuantity,
+    removeLine: removeCartLine,
+    applyCoupon: applyCartCoupon,
+    removeCoupon: removeCartCoupon,
+    setNote: setCartNote,
+    checkout: goToCheckout,
+    openCart: () => setCartOpen(true),
+    closeCart: () => setCartOpen(false),
+    refresh: refreshCart,
+  };
+}

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

@@ -0,0 +1,42 @@
+// React binding of the product-detail store (wix/storefront/product-detail-store.ts) — option
+// selection → variant resolution → add-to-cart lives there, framework-free, with the plan picker,
+// live inventory and notify-me. 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, useRef, useSyncExternalStore } from "react";
+import {
+  createProductDetailStore,
+  type ProductDetailState,
+  type ProductDetailStore,
+  type ProductDetailStoreOptions,
+} from "../../wix/storefront/product-detail-store";
+
+export { ONE_TIME_PLAN, type OptionGroupView, type PlanView } from "../../wix/storefront/product-detail-store";
+
+export type UseProductDetailOptions = ProductDetailStoreOptions;
+
+export type UseProductDetail = ProductDetailState &
+  Pick<ProductDetailStore, "selectOption" | "setModifier" | "setQuantity" | "selectPlan" | "add" | "notify">;
+
+export function useProductDetail({ initial, slug }: UseProductDetailOptions): UseProductDetail {
+  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(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return {
+    ...state,
+    selectOption: store.selectOption,
+    setModifier: store.setModifier,
+    setQuantity: store.setQuantity,
+    selectPlan: store.selectPlan,
+    add: store.add,
+    notify: store.notify,
+  };
+}

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

@@ -0,0 +1,34 @@
+// 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 { SORTS, type ShopFilters } from "../../wix/storefront/shop-store";
+
+export type UseShopOptions = ShopStoreOptions;
+
+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(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return {
+    ...state,
+    setActiveCategoryId: store.setActiveCategoryId,
+    setSort: store.setSort,
+    setFilters: store.setFilters,
+    toggleChoice: store.toggleChoice,
+    clearFilters: store.clearFilters,
+    retry: store.retry,
+    loadMore: store.loadMore,
+  };
+}