@wix/agent-skills 1.0.0

package/skills/wix-headless/templates/stores/categories.ts

@@ -0,0 +1,155 @@
+// Wix Stores Categories — visible, in-use categories under the @wix/stores
+// tree. Drops the auto-provisioned "All Products" root and any category
+// with zero items so the storefront only surfaces curator-meaningful
+// buckets. Returns [] on any failure so consumers can render gracefully.
+//
+// Only one category-tree is in scope here: @wix/stores. Sites with multiple
+// stores trees (B2B, marketplaces) should pass an explicit treeKey.
+
+// The official `@wix/categories` package re-exports these functions; the
+// auto_sdk module is already on disk via every other @wix/* package's
+// transitive deps, so no extra `npm install` is needed.
+import * as categories from "@wix/auto_sdk_categories_categories";
+import { productsV3 } from "@wix/stores";
+
+const STORES_NAMESPACE = "@wix/stores";
+const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+const ALL_PRODUCTS_HANDLE = "online_stores_all_products";
+
+// Module-level TTL cache — opportunistic across requests on warm worker
+// isolates, harmless on cold starts. Categories rarely change; 5 min is fine.
+// Errors are NOT cached so a transient failure doesn't lock out the listing.
+const CATEGORIES_TTL_MS = 5 * 60 * 1000;
+let categoriesCache: { at: number; data: StoreCategory[]; bySlug: Map<string, StoreCategory> } | null = null;
+let inflightCategories: Promise<StoreCategory[]> | null = null;
+
+// Per-category product-ID list — cached under the same TTL so the
+// 2-call listProductsInCategory pipeline doesn't re-fetch IDs on every page.
+const categoryItemIdsCache = new Map<string, { at: number; ids: string[] }>();
+
+export interface StoreCategory {
+  id: string;
+  name: string;
+  slug: string;
+  description?: string;
+  itemCounter: number;
+  imageUrl?: string;
+}
+
+function toStoreCategory(c: any): StoreCategory | null {
+  if (!c?._id || !c?.slug || !c?.name) return null;
+  return {
+    id: c._id,
+    name: c.name,
+    slug: c.slug,
+    description: c.description ?? undefined,
+    itemCounter: typeof c.itemCounter === "number" ? c.itemCounter : 0,
+    imageUrl: c.image?.url ?? undefined,
+  };
+}
+
+async function fetchCategories(): Promise<StoreCategory[]> {
+  // The SDK builder rejects empty filter expressions with INVALID_FILTER.
+  // `.eq("visible", true)` is the constraint we want anyway and satisfies
+  // the validator.
+  const res = await categories
+    .queryCategories({
+      treeReference: { appNamespace: STORES_NAMESPACE },
+    })
+    .eq("visible", true)
+    .ascending("name")
+    .limit(100)
+    .find();
+  return (res.items ?? [])
+    .filter((c: any) => c?.handle !== ALL_PRODUCTS_HANDLE)
+    .filter((c: any) => typeof c?.itemCounter === "number" && c.itemCounter > 0)
+    .map(toStoreCategory)
+    .filter((c): c is StoreCategory => c !== null);
+}
+
+export async function listStoreCategories(): Promise<StoreCategory[]> {
+  if (categoriesCache && Date.now() - categoriesCache.at < CATEGORIES_TTL_MS) {
+    return categoriesCache.data;
+  }
+  if (inflightCategories) return inflightCategories;
+  inflightCategories = (async () => {
+    try {
+      const data = await fetchCategories();
+      const bySlug = new Map(data.map((c) => [c.slug, c]));
+      categoriesCache = { at: Date.now(), data, bySlug };
+      return data;
+    } catch (err) {
+      console.error("[categories] list failed:", err);
+      return [];
+    } finally {
+      inflightCategories = null;
+    }
+  })();
+  return inflightCategories;
+}
+
+export async function getCategoryBySlug(slug: string): Promise<StoreCategory | null> {
+  const all = await listStoreCategories();
+  return categoriesCache?.bySlug.get(slug) ?? all.find((c) => c.slug === slug) ?? null;
+}
+
+async function fetchCategoryItemIds(categoryId: string): Promise<string[]> {
+  try {
+    const res = await categories.listItemsInCategory(
+      categoryId,
+      { appNamespace: STORES_NAMESPACE },
+    );
+    return (res.items ?? [])
+      .map((it: any) => it?.catalogItemId)
+      .filter((id: any): id is string => typeof id === "string" && id.length > 0);
+  } catch (err) {
+    console.error("[categories] listItemsInCategory failed:", err);
+    return [];
+  }
+}
+
+async function getCategoryItemIds(categoryId: string): Promise<string[]> {
+  const cached = categoryItemIdsCache.get(categoryId);
+  if (cached && Date.now() - cached.at < CATEGORIES_TTL_MS) return cached.ids;
+  const ids = await fetchCategoryItemIds(categoryId);
+  categoryItemIdsCache.set(categoryId, { at: Date.now(), ids });
+  return ids;
+}
+
+export interface ProductPage {
+  items: any[];
+  nextCursor: string | null;
+  prevCursor: string | null;
+}
+
+// Cursor-paginated product list for a single category. Two calls under the
+// hood — there is no Wix endpoint that does category filter + cursor paging
+// in one shot. The cursor we surface is the productsV3 cursor, so paging is
+// stable as long as the category membership doesn't change mid-session.
+export async function listProductsInCategory(
+  categoryId: string,
+  opts: { limit: number; cursor?: string },
+): Promise<ProductPage> {
+  try {
+    const ids = await getCategoryItemIds(categoryId);
+    if (ids.length === 0) {
+      return { items: [], nextCursor: null, prevCursor: null };
+    }
+    let builder = productsV3
+      .queryProducts({ fields: ["CURRENCY"] })
+      .in("_id", ids)
+      .limit(opts.limit);
+    if (opts.cursor) builder = builder.skipTo(opts.cursor);
+    const result = await builder.find();
+    return {
+      items: result.items ?? [],
+      nextCursor: result.cursors?.next ?? null,
+      prevCursor: result.cursors?.prev ?? null,
+    };
+  } catch (err) {
+    console.error(`[categories] listProductsInCategory(${categoryId}) failed:`, err);
+    return { items: [], nextCursor: null, prevCursor: null };
+  }
+}
+
+export { STORES_APP_ID };

package/skills/wix-headless/templates/stores/category/[slug].astro

@@ -0,0 +1,130 @@
+---
+// /category/[slug] — server-side filtered, cursor-paginated category
+// landing. Renders the same product grid as /products, but constrained to
+// one category, with breadcrumbs and a category-specific page header.
+//
+// The CategoryRail is shared with /products via transition:persist, so
+// switching categories swaps only the grid and header.
+import Layout from "../../layouts/Layout.astro";
+import ProductCard from "../../components/ProductCard.astro";
+import CategoryRail from "../../components/CategoryRail.astro";
+import {
+  getCategoryBySlug,
+  listProductsInCategory,
+  listStoreCategories,
+} from "../../utils/categories";
+
+const PAGE_SIZE = 24;
+const { slug } = Astro.params;
+
+if (!slug) {
+  return Astro.redirect("/products");
+}
+
+const category = await getCategoryBySlug(slug);
+if (!category) {
+  return new Response("Category not found", { status: 404 });
+}
+
+const cursor = Astro.url.searchParams.get("cursor") ?? undefined;
+const page = await listProductsInCategory(category.id, {
+  limit: PAGE_SIZE,
+  cursor,
+});
+
+// Drop the Wix Gift Card app's auto-mirror products (DIGITAL stand-ins
+// tagged "Gift Card") — real purchases happen via /gift-cards.
+const productList = page.items.filter((p: any) => p.ribbon?.name !== "Gift Card");
+
+const allCategories = await listStoreCategories();
+
+const impressionContents = productList.map((p, index) => ({
+  id: p._id,
+  name: p.name,
+  price: Number(p.actualPriceRange?.minValue?.amount ?? 0),
+  currency: p.actualPriceRange?.minValue?.currency ?? undefined,
+  position: index + 1,
+}));
+
+function pageHref(c: string | null): string | null {
+  if (!c) return null;
+  const params = new URLSearchParams();
+  params.set("cursor", c);
+  return `/category/${category!.slug}?${params.toString()}`;
+}
+---
+
+<Layout
+  title={`${category.name}`}
+  description={category.description ?? `Browse our ${category.name.toLowerCase()} collection.`}
+>
+  <section class="page-header">
+    <div class="container-page">
+      <nav class="breadcrumbs" aria-label="Breadcrumb">
+        <a href="/" data-astro-prefetch="hover">Home</a>
+        <span aria-hidden="true">&middot;</span>
+        <a href="/products" data-astro-prefetch="hover">Shop</a>
+        <span aria-hidden="true">&middot;</span>
+        <span aria-current="page">{category.name}</span>
+      </nav>
+      <h1 class="page-header-title">{category.name}</h1>
+      {category.description && (
+        <p class="page-header-lede">{category.description}</p>
+      )}
+    </div>
+    {category.imageUrl && (
+      <div class="page-header-image" aria-hidden="true">
+        <img
+          src={category.imageUrl}
+          alt=""
+          loading="lazy"
+          decoding="async"
+        />
+      </div>
+    )}
+  </section>
+
+  <CategoryRail
+    categories={allCategories}
+    activeSlug={category.slug}
+    prevHref={pageHref(page.prevCursor)}
+    nextHref={pageHref(page.nextCursor)}
+  />
+
+  <section class="section-pad">
+    <div class="container-page">
+      {productList.length === 0 ? (
+        <p class="products-empty">
+          Nothing in {category.name} just now &mdash; please check back shortly.
+        </p>
+      ) : (
+        <div class="product-grid">
+          {productList.map((product, idx) => (
+            <ProductCard product={product} index={idx} />
+          ))}
+        </div>
+      )}
+    </div>
+  </section>
+</Layout>
+
+<script
+  type="application/json"
+  id="analytics-impressions"
+  is:inline
+  set:html={JSON.stringify(impressionContents)}
+/>
+<script>
+  import { trackEvent } from "../../utils/analytics";
+  function fireImpressions() {
+    const el = document.getElementById("analytics-impressions");
+    if (!el?.textContent) return;
+    trackEvent("AddProductImpression", {
+      contents: JSON.parse(el.textContent),
+      origin: "Category Page",
+    });
+  }
+  // astro:page-load fires on initial load AND after every <ClientRouter />
+  // navigation, so a single listener covers both fresh hits and swaps.
+  document.addEventListener("astro:page-load", fireImpressions);
+</script>

package/skills/wix-headless/templates/stores/components-stores.css

@@ -0,0 +1,295 @@
+/* src/styles/components-stores.css
+ *
+ * Stores-pack component CSS. Owned by the stores Phase 3 components agent.
+ *
+ * This file is the SINGLE source of truth for stores-component classes.
+ * The designer's global.css does NOT publish .product-card, .product-grid,
+ * .product-card-media, .product-card-ribbon, .product-card-index, or the
+ * .offer-callout family — those all live here. See references/shared/STYLING.md
+ * § "Component-specific CSS is owned by the component, not the designer".
+ *
+ * Class groups in this file:
+ * - .product-card / .product-grid / .product-card-* → product cards (ProductCard.astro), product listings (products/index.astro, category/[slug].astro), home grid (index.astro)
+ * - .offer-callout family → discount callout above ProductPurchase on /products/[slug]
+ * - .option-* / .stock-status / .modifier-text → ProductPurchase.tsx (variant pills, stock label, free-text modifier)
+ * - .quantity-* → ProductPurchase.tsx + CartView.tsx (quantity stepper)
+ * - .back-in-stock-* → BackInStockForm.tsx (out-of-stock subscribe)
+ *
+ * Uses the palette + typography custom properties declared in global.css.
+ */
+
+/* =========================================================================
+   Product card + grid — owned here, NOT in global.css.
+   The .product-card uses overflow: hidden + border-radius, so inner padding
+   is the responsibility of THIS file (whoever sets the radius owns the
+   inset). Don't ship a stub rule and rely on the template to add padding
+   utilities — that's the leak this file was created to prevent.
+   ========================================================================= */
+.product-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: var(--spacing-xl);
+  transition: opacity 200ms ease;
+}
+body[data-navigating="true"] .product-grid {
+  opacity: 0.55;
+  pointer-events: none;
+}
+
+.product-card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-md);
+  padding-bottom: var(--spacing-md);
+  background: var(--color-paper, var(--color-cream));
+  border-radius: var(--radius-xl);
+  overflow: hidden;
+  text-decoration: none;
+  color: inherit;
+  transition: transform 280ms ease, box-shadow 280ms ease;
+  box-shadow: var(--shadow-card, 0 4px 16px -8px rgba(0, 0, 0, 0.15));
+}
+.product-card:hover {
+  transform: translateY(-4px);
+}
+.product-card:hover .product-card-media > img {
+  transform: scale(1.04);
+}
+
+.product-card-media {
+  position: relative;
+  margin: var(--spacing-md);
+  aspect-ratio: 4 / 5;
+  background: var(--color-paper-warm, var(--color-cream));
+  border-radius: var(--radius-md);
+  overflow: hidden;
+}
+.product-card-media > img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transition: transform 600ms ease;
+}
+
+.product-card-body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-xs);
+  padding-inline: var(--spacing-md);
+}
+.product-card-name {
+  margin: 0;
+  font-family: var(--font-display);
+  font-size: 1.125rem;
+  line-height: 1.25;
+  color: var(--color-ink);
+}
+.product-card-price {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 0.875rem;
+  letter-spacing: 0.02em;
+  color: var(--color-mute);
+}
+
+.product-card-ribbon {
+  position: absolute;
+  top: var(--spacing-md);
+  left: var(--spacing-md);
+  padding: 0.375rem 0.625rem;
+  background: var(--color-accent);
+  color: var(--color-ink);
+  font-family: var(--font-body);
+  font-size: 0.6875rem;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  border-radius: var(--radius-sm);
+  z-index: 2;
+}
+.product-card-index {
+  position: absolute;
+  top: var(--spacing-md);
+  right: var(--spacing-md);
+  padding: 0.375rem 0.5rem;
+  background: rgba(255, 255, 255, 0.85);
+  color: var(--color-ink);
+  font-family: var(--font-display);
+  font-size: 0.75rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  border-radius: var(--radius-pill, 9999px);
+  z-index: 2;
+}
+
+/* =========================================================================
+   Offer callout — bordered panel above ProductPurchase on /products/[slug].
+   Compound multi-element pattern. The dashboard-authored offer string can
+   contain `\n` line breaks; -detail must preserve them via white-space.
+   ========================================================================= */
+.offer-callout {
+  background: var(--color-paper-warm, var(--color-cream));
+  border: 1px solid var(--color-rule);
+  border-left: 2px solid var(--color-accent);
+  padding: var(--spacing-lg);
+  border-radius: var(--radius-md);
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-md);
+}
+.offer-callout-item {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-xs);
+}
+.offer-callout-item + .offer-callout-item {
+  padding-top: var(--spacing-md);
+  border-top: 1px solid var(--color-rule);
+}
+.offer-callout-badge {
+  align-self: flex-start;
+  padding: 0.25rem 0.5rem;
+  background: var(--color-ink);
+  color: var(--color-paper);
+  font-family: var(--font-body);
+  font-size: 0.625rem;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  border-radius: var(--radius-sm);
+}
+.offer-callout-name {
+  font-family: var(--font-display);
+  font-size: 1rem;
+  color: var(--color-ink);
+  margin: 0;
+}
+.offer-callout-detail {
+  font-family: var(--font-body);
+  font-size: 0.875rem;
+  color: var(--color-ink-soft, var(--color-mute));
+  white-space: pre-line;
+  margin: 0;
+}
+.offer-callout-foot {
+  font-family: var(--font-body);
+  font-size: 0.75rem;
+  color: var(--color-mute);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  margin: 0;
+}
+
+
+/* --- Variant / option pills (ProductPurchase.tsx) --- */
+.option-group {
+  @apply flex flex-col gap-sm mb-lg;
+}
+.option-label {
+  @apply font-heading text-sm uppercase tracking-wider text-bark/70;
+}
+.option-choices {
+  @apply flex flex-wrap gap-sm;
+}
+.option-pill {
+  @apply px-md py-sm border border-bark bg-transparent text-bark font-body rounded-full cursor-pointer transition-colors;
+}
+.option-pill.selected {
+  @apply bg-bark text-cream;
+}
+.option-pill:disabled {
+  @apply opacity-40 cursor-not-allowed;
+}
+
+/* --- Quantity stepper (ProductPurchase.tsx, CartView.tsx qty editing) --- */
+.quantity-selector {
+  @apply inline-flex items-center border border-bark rounded-md overflow-hidden;
+}
+.quantity-btn {
+  @apply px-3 py-2 bg-transparent border-none cursor-pointer text-bark font-body;
+}
+.quantity-btn:disabled {
+  @apply opacity-40 cursor-not-allowed;
+}
+.quantity-value {
+  @apply px-md py-sm tabular-nums;
+}
+
+/* --- Modifier free-text input (ProductPurchase.tsx, FREE_TEXT render type) --- */
+.modifier-text {
+  @apply w-full px-sm py-sm font-body text-sm border border-rule rounded bg-parchment text-ink;
+  resize: vertical;
+}
+.modifier-text:focus {
+  @apply outline-none border-ink bg-cream;
+}
+
+/* --- Stock status (ProductPurchase.tsx) --- */
+.stock-status {
+  @apply text-sm text-bark/70 italic;
+}
+
+/* --- Back-in-stock subscribe form (BackInStockForm.tsx) ---
+ * Rendered inside .purchase-area in three OOS branches when
+ * backInStockEnabled=true (probe in [slug].astro). */
+.back-in-stock-form {
+  @apply flex flex-col gap-md mt-md p-lg border border-rule rounded;
+  background-color: var(--color-cream);
+}
+.back-in-stock-headline {
+  @apply flex flex-col gap-sm;
+}
+.back-in-stock-eyebrow {
+  @apply font-heading text-xs uppercase tracking-wider text-bark/70;
+}
+.back-in-stock-lede {
+  @apply font-body text-sm text-ink;
+  line-height: 1.5;
+}
+.back-in-stock-label {
+  @apply font-heading text-xs uppercase tracking-wider text-bark/70;
+}
+.back-in-stock-row {
+  @apply flex flex-row flex-wrap gap-sm;
+}
+.back-in-stock-input {
+  @apply flex-1 px-md py-sm font-body text-sm border border-rule rounded bg-parchment text-ink;
+  min-width: 0;
+  transition: border-color 0.15s ease;
+}
+.back-in-stock-input:focus {
+  @apply outline-none border-ink;
+}
+.back-in-stock-submit {
+  @apply px-lg py-sm font-heading text-xs uppercase tracking-wider bg-bark text-cream rounded cursor-pointer transition-colors;
+  border: 1px solid var(--color-bark);
+}
+.back-in-stock-submit:hover:not(:disabled) {
+  @apply bg-ink;
+}
+.back-in-stock-submit:disabled {
+  @apply opacity-50 cursor-not-allowed;
+}
+.back-in-stock-error {
+  @apply font-body text-sm;
+  color: var(--color-rust, var(--color-ink));
+}
+.back-in-stock-success {
+  @apply mt-md p-lg border border-rule rounded;
+  background-color: var(--color-cream);
+}
+.back-in-stock-success-headline {
+  @apply font-heading text-base text-ink;
+  margin: 0 0 0.5rem 0;
+}
+.back-in-stock-success-detail {
+  @apply font-body text-sm text-ink;
+  line-height: 1.55;
+  margin: 0;
+}
+.stock-status.back-in-stock-alt {
+  @apply mt-sm font-body text-sm italic text-bark/70;
+}
+
+/* Cart CSS (.cart-item-*, .qty-*) lives in components-ecom.css — not in this file. */