@wix/agent-skills 1.17.0 → 1.18.0

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

@@ -0,0 +1,121 @@
+// Slide-over cart with quantity stepper, remove, live subtotal, and Wix-hosted checkout.
+// Mount ONCE per page, as-is; opens via useCart().openCart() / CartButton. Styled from the
+// @theme tokens.
+import { useCart } from "../../hooks/storefront/useCart";
+
+export default function CartDrawer() {
+  const { cart, open, closeCart, busy, error, updateQuantity, removeLine, checkout } = useCart();
+  if (!open) return null;
+  const lines = cart?.lines ?? [];
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex justify-end bg-foreground/40 backdrop-blur-[2px]"
+      onClick={closeCart}
+    >
+      <aside
+        role="dialog"
+        aria-label="Cart"
+        onClick={(e) => e.stopPropagation()}
+        className="flex h-full w-full max-w-md flex-col bg-background text-foreground shadow-2xl"
+      >
+        <div className="flex items-center justify-between border-b border-border px-6 py-5">
+          <span className="text-base font-semibold">
+            Cart{cart && cart.itemCount > 0 ? ` (${cart.itemCount})` : ""}
+          </span>
+          <button
+            type="button"
+            aria-label="Close cart"
+            onClick={closeCart}
+            className="text-xl leading-none text-muted-foreground transition-colors hover:text-foreground"
+          >
+            ×
+          </button>
+        </div>
+
+        <div className="flex-1 overflow-y-auto px-6 py-5">
+          {lines.length === 0 && (
+            <p className="py-16 text-center text-sm text-muted-foreground">Your cart is empty.</p>
+          )}
+          {lines.map((line) => (
+            <div className="mb-6 flex gap-4" key={line.lineItemId}>
+              {line.imageUrl ? (
+                <img
+                  src={line.imageUrl}
+                  alt=""
+                  loading="lazy"
+                  className="h-16 w-16 flex-shrink-0 rounded-md bg-secondary object-cover"
+                />
+              ) : (
+                <div aria-hidden="true" className="h-16 w-16 flex-shrink-0 rounded-md bg-secondary" />
+              )}
+              <div className="min-w-0 flex-1">
+                <p className="text-sm font-medium">{line.productName}</p>
+                {line.descriptionLines.map((d) => (
+                  <p className="mt-0.5 text-xs text-muted-foreground" key={d}>
+                    {d}
+                  </p>
+                ))}
+                {line.status !== "IN_STOCK" && (
+                  <p className="mt-1 text-xs text-red-600">No longer available at this quantity</p>
+                )}
+                <div className="mt-2 flex items-center">
+                  <div className="inline-flex items-center gap-3 rounded-full border border-border px-2 py-0.5">
+                    <button
+                      type="button"
+                      aria-label="Decrease quantity"
+                      disabled={busy || line.quantity <= 1}
+                      onClick={() => updateQuantity(line.lineItemId, line.quantity - 1).catch(() => {})}
+                      className="px-1 text-base disabled:opacity-40"
+                    >
+                      −
+                    </button>
+                    <span className="text-sm tabular-nums">{line.quantity}</span>
+                    <button
+                      type="button"
+                      aria-label="Increase quantity"
+                      disabled={busy}
+                      onClick={() => updateQuantity(line.lineItemId, line.quantity + 1).catch(() => {})}
+                      className="px-1 text-base disabled:opacity-40"
+                    >
+                      +
+                    </button>
+                  </div>
+                  <button
+                    type="button"
+                    disabled={busy}
+                    onClick={() => removeLine(line.lineItemId).catch(() => {})}
+                    className="ml-3 text-xs text-muted-foreground underline transition-colors hover:text-foreground disabled:opacity-40"
+                  >
+                    Remove
+                  </button>
+                </div>
+              </div>
+              <p className="text-sm font-medium">{line.linePrice}</p>
+            </div>
+          ))}
+        </div>
+
+        {lines.length > 0 && (
+          <div className="border-t border-border px-6 py-5">
+            {cart?.subtotal && (
+              <div className="mb-4 flex justify-between text-sm">
+                <span className="text-muted-foreground">Subtotal</span>
+                <strong className="font-semibold">{cart.subtotal}</strong>
+              </div>
+            )}
+            {error && <p className="mb-3 text-xs text-red-600">{error}</p>}
+            <button
+              type="button"
+              disabled={busy}
+              onClick={() => checkout().catch(() => {})}
+              className="w-full rounded-full bg-primary py-3.5 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
+            >
+              {busy ? "One moment…" : "Checkout"}
+            </button>
+          </div>
+        )}
+      </aside>
+    </div>
+  );
+}

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

@@ -0,0 +1,100 @@
+// Grid tile — a REFERENCE implementation over the ProductSummary DTO. Complete and correct
+// (badges, sale price, hover image, quick-add); styled entirely from the @theme tokens via
+// Tailwind utilities. Designing your own card on the same DTO is encouraged.
+import type { ComponentType, ReactNode } from "react";
+import type { ProductSummary } from "../../wix/storefront/types";
+import { useCart } from "../../hooks/storefront/useCart";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+}
+
+export interface ProductCardProps {
+  product: ProductSummary;
+  /** Route pattern for detail pages; default matches the shipped /products/[slug] page. */
+  productHref?: (slug: string) => string;
+  /** Router-specific link (react-router Link, next/link); defaults to a plain <a>. */
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+export default function ProductCard({
+  product,
+  productHref = (slug) => `/products/${slug}`,
+  LinkComponent = PlainLink,
+}: ProductCardProps) {
+  const { addToCart, busy } = useCart();
+  const soldOut = product.availability === "OUT_OF_STOCK" && !product.preorder;
+  const priceLabel =
+    product.maxPrice && product.maxPrice !== product.price
+      ? `${product.price} – ${product.maxPrice}`
+      : product.price;
+
+  return (
+    <div className="group">
+      <LinkComponent href={productHref(product.slug)} className="block no-underline">
+        <div className="relative aspect-square overflow-hidden rounded-lg bg-secondary">
+          {product.imageUrl && (
+            <img
+              src={product.imageUrl}
+              alt={product.name}
+              loading="lazy"
+              className="h-full w-full object-cover transition-transform duration-300 group-hover:scale-[1.03]"
+            />
+          )}
+          {product.hoverImageUrl && (
+            <img
+              src={product.hoverImageUrl}
+              alt=""
+              aria-hidden="true"
+              loading="lazy"
+              className="absolute inset-0 h-full w-full object-cover opacity-0 transition-opacity duration-300 group-hover:opacity-100"
+            />
+          )}
+          {product.ribbon && (
+            <span className="absolute left-3 top-3 rounded-full bg-background/90 px-3 py-1 text-xs font-semibold text-foreground backdrop-blur">
+              {product.ribbon}
+            </span>
+          )}
+          {soldOut && (
+            <span className="absolute right-3 top-3 rounded-full bg-background/90 px-3 py-1 text-xs font-semibold text-muted-foreground backdrop-blur">
+              Sold out
+            </span>
+          )}
+          {product.preorder && (
+            <span className="absolute right-3 top-3 rounded-full bg-background/90 px-3 py-1 text-xs font-semibold text-foreground backdrop-blur">
+              Pre-order
+            </span>
+          )}
+        </div>
+        <p className="mt-3 text-sm font-medium text-foreground">{product.name}</p>
+        <p className="mt-0.5 flex items-baseline gap-2 text-sm">
+          <span className="text-foreground">{priceLabel}</span>
+          {product.compareAtPrice && (
+            <span className="text-muted-foreground line-through">{product.compareAtPrice}</span>
+          )}
+        </p>
+        {product.optionsSummary && (
+          <p className="mt-0.5 text-xs text-muted-foreground">{product.optionsSummary}</p>
+        )}
+      </LinkComponent>
+      {product.quickAddable && (
+        <button
+          type="button"
+          disabled={busy}
+          onClick={() => addToCart(product.id).catch(() => {})}
+          className="mt-2 rounded-full border border-border px-4 py-1.5 text-xs font-medium text-foreground transition-colors hover:bg-secondary disabled:opacity-50"
+        >
+          Add to cart
+        </button>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,130 @@
+// The full product detail surface: gallery, price, option/modifier picker, quantity,
+// add-to-cart — styled from the @theme tokens. Mount as-is (Astro: an island with the
+// server-fetched `initial` product; SPA: pass the `slug`). All selection→variant logic lives
+// in useProductDetail — never bypass it to add a product with options.
+import { useState } from "react";
+import { useProductDetail } from "../../hooks/storefront/useProductDetail";
+import VariantPicker from "./VariantPicker";
+
+export interface ProductDetailViewProps {
+  /** Server-fetched product (Astro/Next SSR). */
+  initial?: import("../../wix/storefront/types").ProductDetail | null;
+  /** SPA alternative: fetch by slug on mount. */
+  slug?: string;
+}
+
+export default function ProductDetailView({ initial, slug }: ProductDetailViewProps) {
+  const {
+    product,
+    notFound,
+    optionGroups,
+    selectOption,
+    modifierValues,
+    setModifier,
+    price,
+    compareAtPrice,
+    canAdd,
+    quantity,
+    setQuantity,
+    add,
+    adding,
+    error,
+  } = useProductDetail({ initial, slug });
+  const [imageIndex, setImageIndex] = useState(0);
+
+  if (notFound)
+    return <p className="py-16 text-center text-muted-foreground">This product doesn't exist (anymore).</p>;
+  if (!product) return <div className="aspect-square max-w-md animate-pulse rounded-xl bg-secondary" />;
+
+  const soldOut = product.availability === "OUT_OF_STOCK" && !product.preorder;
+  const mainImage = product.gallery[imageIndex] ?? product.imageUrl;
+
+  return (
+    <div className="grid gap-10 md:grid-cols-2">
+      <div>
+        <div className="aspect-square overflow-hidden rounded-xl bg-secondary">
+          {mainImage && <img src={mainImage} alt={product.name} className="h-full w-full object-cover" />}
+        </div>
+        {product.gallery.length > 1 && (
+          <div className="mt-3 flex flex-wrap gap-2">
+            {product.gallery.map((url, i) => (
+              <button
+                key={url}
+                type="button"
+                aria-label={`Image ${i + 1}`}
+                onClick={() => setImageIndex(i)}
+                className={`h-16 w-16 overflow-hidden rounded-md border-2 transition-colors ${
+                  i === imageIndex ? "border-primary" : "border-transparent hover:border-border"
+                }`}
+              >
+                <img src={url} alt="" className="h-full w-full object-cover" />
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+
+      <div>
+        <h1 className="text-2xl font-semibold tracking-tight">{product.name}</h1>
+        <p className="mt-2 flex items-baseline gap-3">
+          <span className="text-xl font-medium">{price}</span>
+          {compareAtPrice && <span className="text-base text-muted-foreground line-through">{compareAtPrice}</span>}
+        </p>
+        {soldOut && <p className="mt-2 text-sm font-medium text-red-600">Out of stock</p>}
+        {product.preorder && <p className="mt-2 text-sm text-muted-foreground">Available for pre-order</p>}
+
+        {product.descriptionHtml && (
+          // plainDescription is HTML (despite the name) — render it, don't print it.
+          <div
+            className="mt-4 space-y-2 text-sm leading-relaxed text-muted-foreground [&_strong]:font-semibold [&_strong]:text-foreground"
+            dangerouslySetInnerHTML={{ __html: product.descriptionHtml }}
+          />
+        )}
+
+        <div className="mt-6">
+          <VariantPicker
+            optionGroups={optionGroups}
+            selectOption={selectOption}
+            modifiers={product.modifiers}
+            modifierValues={modifierValues}
+            setModifier={setModifier}
+          />
+        </div>
+
+        {!soldOut && (
+          <div className="mt-2 flex items-center gap-3">
+            <div className="inline-flex items-center gap-3 rounded-full border border-border px-3 py-2">
+              <button
+                type="button"
+                aria-label="Decrease quantity"
+                disabled={quantity <= 1}
+                onClick={() => setQuantity(quantity - 1)}
+                className="px-1 text-base disabled:opacity-40"
+              >
+                −
+              </button>
+              <span className="text-sm tabular-nums">{quantity}</span>
+              <button
+                type="button"
+                aria-label="Increase quantity"
+                onClick={() => setQuantity(quantity + 1)}
+                className="px-1 text-base"
+              >
+                +
+              </button>
+            </div>
+            <button
+              type="button"
+              disabled={!canAdd || adding}
+              onClick={() => add().catch(() => {})}
+              className="rounded-full bg-primary px-8 py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50"
+            >
+              {adding ? "Adding…" : canAdd ? "Add to cart" : "Select options"}
+            </button>
+          </div>
+        )}
+        {error && <p className="mt-3 text-sm text-red-600">{error}</p>}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,48 @@
+// Listing grid with loading skeletons and an honest empty state — a REFERENCE layout on the
+// @theme tokens. Keep the states (they're correct); choosing a grid arrangement that fits the
+// brand is encouraged. Never mock products: empty catalog → the empty state.
+import type { ComponentType } from "react";
+import type { ProductSummary } from "../../wix/storefront/types";
+import ProductCard, { type ProductCardProps } from "./ProductCard";
+
+export interface ProductGridProps {
+  /** null → loading skeletons; [] → the empty state. */
+  products: ProductSummary[] | null;
+  emptyMessage?: string;
+  productHref?: ProductCardProps["productHref"];
+  LinkComponent?: ProductCardProps["LinkComponent"];
+  /** Swap in your own tile (built on ProductSummary) without re-doing the states. */
+  CardComponent?: ComponentType<ProductCardProps>;
+}
+
+export default function ProductGrid({
+  products,
+  emptyMessage = "No products yet — check back soon.",
+  productHref,
+  LinkComponent,
+  CardComponent = ProductCard,
+}: ProductGridProps) {
+  if (products === null) {
+    return (
+      <div className="grid grid-cols-2 gap-x-5 gap-y-8 sm:grid-cols-3 lg:grid-cols-4" aria-busy="true">
+        {Array.from({ length: 8 }, (_, i) => (
+          <div key={i}>
+            <div className="aspect-square animate-pulse rounded-lg bg-secondary" />
+            <div className="mt-3 h-3.5 w-3/4 animate-pulse rounded bg-secondary" />
+            <div className="mt-2 h-3.5 w-1/3 animate-pulse rounded bg-secondary" />
+          </div>
+        ))}
+      </div>
+    );
+  }
+  if (products.length === 0) {
+    return <p className="py-16 text-center text-muted-foreground">{emptyMessage}</p>;
+  }
+  return (
+    <div className="grid grid-cols-2 gap-x-5 gap-y-8 sm:grid-cols-3 lg:grid-cols-4">
+      {products.map((p) => (
+        <CardComponent key={p.id} product={p} productHref={productHref} LinkComponent={LinkComponent} />
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,66 @@
+// The full shop surface: live category filter bar + product grid, styled from the @theme
+// tokens. Mount as-is (Astro: one island with server-fetched initial data; SPA: no props).
+import { useShop } from "../../hooks/storefront/useShop";
+import type { Category, ProductSummary } from "../../wix/storefront/types";
+import ProductGrid, { type ProductGridProps } from "./ProductGrid";
+
+export interface ShopViewProps {
+  /** Server-fetched data (Astro/Next SSR) — omit in a SPA and it fetches client-side. */
+  initialProducts?: ProductSummary[];
+  initialCategories?: Category[];
+  emptyMessage?: string;
+  productHref?: ProductGridProps["productHref"];
+  LinkComponent?: ProductGridProps["LinkComponent"];
+  CardComponent?: ProductGridProps["CardComponent"];
+}
+
+const pill = (active: boolean) =>
+  `rounded-full border px-4 py-1.5 text-sm font-medium transition-colors ${
+    active
+      ? "border-primary bg-primary text-primary-foreground"
+      : "border-border text-foreground hover:bg-secondary"
+  }`;
+
+export default function ShopView({
+  initialProducts,
+  initialCategories,
+  emptyMessage,
+  productHref,
+  LinkComponent,
+  CardComponent,
+}: ShopViewProps) {
+  const { products, categories, activeCategoryId, setActiveCategoryId, loading, error } = useShop({
+    initialProducts,
+    initialCategories,
+  });
+
+  return (
+    <div>
+      {categories.length > 1 && (
+        <div className="mb-8 flex flex-wrap gap-2" role="group" aria-label="Categories">
+          <button type="button" className={pill(activeCategoryId === null)} onClick={() => setActiveCategoryId(null)}>
+            All
+          </button>
+          {categories.map((c) => (
+            <button
+              key={c.id}
+              type="button"
+              className={pill(activeCategoryId === c.id)}
+              onClick={() => setActiveCategoryId(c.id)}
+            >
+              {c.name}
+            </button>
+          ))}
+        </div>
+      )}
+      {error && <p className="mb-4 text-sm text-red-600">{error}</p>}
+      <ProductGrid
+        products={loading ? null : products}
+        emptyMessage={emptyMessage}
+        productHref={productHref}
+        LinkComponent={LinkComponent}
+        CardComponent={CardComponent}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,103 @@
+// Option/modifier selector — wire as-is on the PDP (color options render as swatches, text
+// options as pills, modifiers as pills or a text input). Styled from the @theme tokens.
+import type { ProductModifier } from "../../wix/storefront/types";
+import type { OptionGroupView } from "../../hooks/storefront/useProductDetail";
+
+export interface VariantPickerProps {
+  optionGroups: OptionGroupView[];
+  selectOption: (optionName: string, choiceName: string) => void;
+  modifiers?: ProductModifier[];
+  modifierValues?: Record<string, string>;
+  setModifier?: (key: string, value: string) => void;
+}
+
+const chip = (selected: boolean) =>
+  `rounded-full border px-4 py-1.5 text-sm transition-colors disabled:cursor-not-allowed disabled:opacity-40 disabled:line-through ${
+    selected
+      ? "border-primary bg-primary text-primary-foreground"
+      : "border-border text-foreground hover:bg-secondary"
+  }`;
+
+export default function VariantPicker({
+  optionGroups,
+  selectOption,
+  modifiers = [],
+  modifierValues = {},
+  setModifier,
+}: VariantPickerProps) {
+  return (
+    <div>
+      {optionGroups.map((group) => (
+        <div className="mb-5" key={group.id || group.name}>
+          <p className="mb-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+            {group.name}
+          </p>
+          <div className="flex flex-wrap items-center gap-2">
+            {group.choices.map((choice) =>
+              group.isColor && choice.colorCode ? (
+                <button
+                  key={choice.choiceId || choice.name}
+                  type="button"
+                  style={{ background: choice.colorCode }}
+                  title={choice.name}
+                  aria-label={`${group.name}: ${choice.name}`}
+                  aria-pressed={choice.selected}
+                  disabled={!choice.inStock}
+                  onClick={() => selectOption(group.name, choice.name)}
+                  className={`h-8 w-8 rounded-full border transition-shadow disabled:cursor-not-allowed disabled:opacity-35 ${
+                    choice.selected
+                      ? "border-primary ring-2 ring-primary ring-offset-2 ring-offset-background"
+                      : "border-border"
+                  }`}
+                />
+              ) : (
+                <button
+                  key={choice.choiceId || choice.name}
+                  type="button"
+                  aria-pressed={choice.selected}
+                  disabled={!choice.inStock}
+                  onClick={() => selectOption(group.name, choice.name)}
+                  className={chip(choice.selected)}
+                >
+                  {choice.name}
+                </button>
+              ),
+            )}
+          </div>
+        </div>
+      ))}
+
+      {modifiers.map((m) => (
+        <div className="mb-5" key={m.key}>
+          <p className="mb-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+            {m.name}
+            {m.mandatory ? " *" : ""}
+          </p>
+          {m.type === "text" ? (
+            <input
+              type="text"
+              value={modifierValues[m.key] ?? ""}
+              onChange={(e) => setModifier?.(m.key, e.target.value)}
+              aria-label={m.name}
+              className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none transition-shadow focus:ring-2 focus:ring-primary"
+            />
+          ) : (
+            <div className="flex flex-wrap gap-2">
+              {m.choices.map((c) => (
+                <button
+                  key={c.key}
+                  type="button"
+                  aria-pressed={modifierValues[m.key] === c.key}
+                  onClick={() => setModifier?.(m.key, c.key)}
+                  className={chip(modifierValues[m.key] === c.key)}
+                >
+                  {c.name}
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,48 @@
+// 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,
+  getCartState,
+  goToCheckout,
+  refreshCart,
+  removeCartLine,
+  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>;
+  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,
+    checkout: goToCheckout,
+    openCart: () => setCartOpen(true),
+    closeCart: () => setCartOpen(false),
+    refresh: refreshCart,
+  };
+}