@jay-framework/wix-stores 0.16.5 → 0.17.1

package/dist/contracts/product-card.jay-contract

@@ -183,6 +183,11 @@ tags:
     description: Secondary option for quick selection (text choices for COLOR_AND_TEXT_OPTIONS). Rendered as buttons or dropdown. Selection adds to cart.
     link: ./product-options
 
+  - tag: cardContainer
+    type: interactive
+    elementType: HTMLElement
+    description: The product card root element. Must be placed on the outermost card wrapper so that mouseenter preloads variant stock for quick-add options.
+
   - tag: viewOptionsButton
     type: interactive
     elementType: HTMLButtonElement

package/dist/contracts/product-card.jay-contract.d.ts

@@ -116,6 +116,7 @@ export type ProductCardInteractiveViewState = Pick<ProductCardViewState, 'price'
 export interface ProductCardRefs {
   productLink: HTMLElementProxy<ProductCardViewState, HTMLAnchorElement>,
   addToCartButton: HTMLElementProxy<ProductCardViewState, HTMLButtonElement>,
+  cardContainer: HTMLElementProxy<ProductCardViewState, HTMLElement>,
   viewOptionsButton: HTMLElementProxy<ProductCardViewState, HTMLButtonElement>,
   quickOption: ProductOptionsRefs,
   secondQuickOption: ProductOptionsRefs
@@ -125,6 +126,7 @@ export interface ProductCardRefs {
 export interface ProductCardRepeatedRefs {
   productLink: HTMLElementCollectionProxy<ProductCardViewState, HTMLAnchorElement>,
   addToCartButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
+  cardContainer: HTMLElementCollectionProxy<ProductCardViewState, HTMLElement>,
   viewOptionsButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
   quickOption: ProductOptionsRepeatedRefs,
   secondQuickOption: ProductOptionsRepeatedRefs

package/dist/contracts/product-page.jay-contract

@@ -16,6 +16,7 @@ tags:
   - {tag: description, type: data, dataType: string, description: Product description}
   - {tag: brand, type: data, dataType: string, description: Brand name}
   - {tag: ribbon, type: data, dataType: string, description: "Ribbon text (e.g., \"New\", \"Sale\")"}
+  - {tag: categorySlug, type: data, dataType: string, description: Slug of the product's main category}
   - {tag: productType, type: variant, dataType: "enum (PHYSICAL | DIGITAL)", description: Product type }
 
   - {tag: sku, type: data, dataType: string, phase: fast+interactive, description: Product SKU, or chosen variant SKU}

package/dist/contracts/product-page.jay-contract.d.ts

@@ -84,6 +84,7 @@ export interface ProductPageViewState {
   description: string,
   brand: string,
   ribbon: string,
+  categorySlug: string,
   productType: ProductType,
   sku: string,
   price: string,
@@ -98,7 +99,7 @@ export interface ProductPageViewState {
   modifiers: Array<ModifierOfProductPageViewState>
 }
 
-export type ProductPageSlowViewState = Pick<ProductPageViewState, '_id' | 'productName' | 'description' | 'brand' | 'ribbon' | 'productType'> & {
+export type ProductPageSlowViewState = Pick<ProductPageViewState, '_id' | 'productName' | 'description' | 'brand' | 'ribbon' | 'categorySlug' | 'productType'> & {
     options: Array<Pick<ProductPageViewState['options'][number], '_id' | 'name' | 'optionRenderType'> & {
     choices: Array<Pick<ProductPageViewState['options'][number]['choices'][number], 'choiceId' | 'choiceType' | 'name' | 'colorCode' | 'inStock'>>;
 }>;

package/dist/contracts/related-products.jay-contract

@@ -0,0 +1,31 @@
+name: related-products
+description: Related products grid showing products from the same category. Use on product pages alongside the product-page component.
+props:
+  - name: productId
+    type: string
+    description: Product ID to exclude from results
+  - name: categorySlug
+    type: string
+    description: Category slug to filter related products by
+  - name: limit
+    type: number
+    description: Maximum number of related products to show (default 4)
+tags:
+  - tag: products
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    phase: fast+interactive
+    description: Related product cards
+    link: ./product-card
+
+  - tag: hasProducts
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Whether there are related products to show
+
+  - tag: categoryName
+    type: data
+    dataType: string
+    description: Name of the category these products belong to

package/dist/contracts/related-products.jay-contract.d.ts

@@ -0,0 +1,36 @@
+import {JayContract} from "@jay-framework/runtime";
+import {ProductCardViewState, ProductCardRefs, ProductCardRepeatedRefs} from "./product-card.jay-contract";
+
+export interface RelatedProductsViewState {
+  products: Array<ProductCardViewState>,
+  hasProducts: boolean,
+  categoryName: string
+}
+
+export type RelatedProductsSlowViewState = Pick<RelatedProductsViewState, 'categoryName'>;
+
+export type RelatedProductsFastViewState = Pick<RelatedProductsViewState, 'hasProducts'> & {
+    products: Array<RelatedProductsViewState['products'][number]>;
+};
+
+export type RelatedProductsInteractiveViewState = Pick<RelatedProductsViewState, 'hasProducts'> & {
+    products: Array<RelatedProductsViewState['products'][number]>;
+};
+
+
+export interface RelatedProductsRefs {
+  products: ProductCardRepeatedRefs
+}
+
+
+export interface RelatedProductsRepeatedRefs {
+  products: ProductCardRepeatedRefs
+}
+
+export interface RelatedProductsProps {
+  productId?: string;
+  categorySlug?: string;
+  limit?: number;
+}
+
+export type RelatedProductsContract = JayContract<RelatedProductsViewState, RelatedProductsRefs, RelatedProductsSlowViewState, RelatedProductsFastViewState, RelatedProductsInteractiveViewState, RelatedProductsProps>

package/dist/index.client.js

@@ -339,6 +339,186 @@ var QuickAddType = /* @__PURE__ */ ((QuickAddType2) => {
   QuickAddType2[QuickAddType2["NEEDS_CONFIGURATION"] = 3] = "NEEDS_CONFIGURATION";
   return QuickAddType2;
 })(QuickAddType || {});
+function setupCardInteractions(refs, cards, storesContext) {
+  const variantStockCache = {};
+  let variantStockApplied = /* @__PURE__ */ new Set();
+  const variantStockLoading = /* @__PURE__ */ new Set();
+  const loadVariantStock = async (productId) => {
+    if (variantStockApplied.has(productId) || variantStockLoading.has(productId)) return;
+    variantStockLoading.add(productId);
+    try {
+      const currentResults = cards.get();
+      const productIndex = currentResults.findIndex((p) => p._id === productId);
+      if (productIndex === -1) return;
+      const product = currentResults[productIndex];
+      if (product?.quickAddType !== QuickAddType.COLOR_AND_TEXT_OPTIONS) return;
+      const stockMap = variantStockCache[productId] ?? await getVariantStock({ productId });
+      variantStockCache[productId] = stockMap;
+      variantStockApplied.add(productId);
+      const selectedColor = product.quickOption?.choices?.find((c) => c.isSelected);
+      const textChoices = product.secondQuickOption?.choices;
+      if (!selectedColor || !textChoices) return;
+      const colorStock = stockMap[selectedColor.choiceId];
+      const updatedTextChoices = textChoices.map((c) => ({
+        ...c,
+        inStock: colorStock?.[c.choiceId] ?? false
+      }));
+      cards.set(
+        patch(cards.get(), [
+          {
+            op: REPLACE,
+            path: [productIndex, "secondQuickOption", "choices"],
+            value: updatedTextChoices
+          }
+        ])
+      );
+    } finally {
+      variantStockLoading.delete(productId);
+    }
+  };
+  refs.addToCartButton.onclick(async ({ coordinate }) => {
+    const [productId] = coordinate;
+    const currentResults = cards.get();
+    const productIndex = currentResults.findIndex((p) => p._id === productId);
+    if (productIndex === -1) return;
+    cards.set(
+      patch(currentResults, [
+        { op: REPLACE, path: [productIndex, "isAddingToCart"], value: true }
+      ])
+    );
+    try {
+      await storesContext.addToCart(productId, 1);
+    } catch (error) {
+      console.error("Failed to add to cart:", error);
+    } finally {
+      cards.set(
+        patch(cards.get(), [
+          { op: REPLACE, path: [productIndex, "isAddingToCart"], value: false }
+        ])
+      );
+    }
+  });
+  refs.cardContainer.onmouseenter(({ coordinate }) => {
+    const [productId] = coordinate;
+    loadVariantStock(productId);
+  });
+  refs.quickOption.choices.choiceButton.onclick(async ({ coordinate }) => {
+    const [productId, choiceId] = coordinate;
+    const currentResults = cards.get();
+    const productIndex = currentResults.findIndex((p) => p._id === productId);
+    if (productIndex === -1) return;
+    const product = currentResults[productIndex];
+    if (product.quickAddType === QuickAddType.COLOR_AND_TEXT_OPTIONS) {
+      const choices = product.quickOption?.choices;
+      if (!choices) return;
+      const updatedChoices = choices.map((c) => ({
+        ...c,
+        isSelected: c.choiceId === choiceId
+      }));
+      let updated = patch(currentResults, [
+        {
+          op: REPLACE,
+          path: [productIndex, "quickOption", "choices"],
+          value: updatedChoices
+        }
+      ]);
+      const stockMap = variantStockCache[productId];
+      if (stockMap) {
+        const colorStock = stockMap[choiceId];
+        const textChoices = product.secondQuickOption?.choices;
+        if (textChoices) {
+          const updatedTextChoices = textChoices.map((c) => ({
+            ...c,
+            inStock: colorStock?.[c.choiceId] ?? false
+          }));
+          updated = patch(updated, [
+            {
+              op: REPLACE,
+              path: [productIndex, "secondQuickOption", "choices"],
+              value: updatedTextChoices
+            }
+          ]);
+        }
+      } else {
+        loadVariantStock(productId);
+      }
+      cards.set(updated);
+      return;
+    }
+    const choice = product.quickOption?.choices?.find((c) => c.choiceId === choiceId);
+    if (!choice || !choice.inStock) return;
+    cards.set(
+      patch(currentResults, [
+        { op: REPLACE, path: [productIndex, "isAddingToCart"], value: true }
+      ])
+    );
+    try {
+      const optionId = product.quickOption._id;
+      await storesContext.addToCart(productId, 1, {
+        options: { [optionId]: choice.choiceId },
+        modifiers: {},
+        customTextFields: {}
+      });
+    } catch (error) {
+      console.error("Failed to add to cart:", error);
+    } finally {
+      cards.set(
+        patch(cards.get(), [
+          { op: REPLACE, path: [productIndex, "isAddingToCart"], value: false }
+        ])
+      );
+    }
+  });
+  refs.secondQuickOption.choices.choiceButton.onclick(async ({ coordinate }) => {
+    const [productId, choiceId] = coordinate;
+    const currentResults = cards.get();
+    const productIndex = currentResults.findIndex((p) => p._id === productId);
+    if (productIndex === -1) return;
+    const product = currentResults[productIndex];
+    const textChoice = product.secondQuickOption?.choices?.find(
+      (c) => c.choiceId === choiceId
+    );
+    const selectedColor = product.quickOption?.choices?.find((c) => c.isSelected);
+    if (!textChoice || !textChoice.inStock) return;
+    cards.set(
+      patch(currentResults, [
+        { op: REPLACE, path: [productIndex, "isAddingToCart"], value: true }
+      ])
+    );
+    try {
+      const colorOptionId = product.quickOption?._id || "";
+      const textOptionId = product.secondQuickOption?._id || "";
+      await storesContext.addToCart(productId, 1, {
+        options: {
+          [colorOptionId]: selectedColor?.choiceId || "",
+          [textOptionId]: textChoice.choiceId
+        },
+        modifiers: {},
+        customTextFields: {}
+      });
+    } catch (error) {
+      console.error("Failed to add to cart:", error);
+    } finally {
+      cards.set(
+        patch(cards.get(), [
+          { op: REPLACE, path: [productIndex, "isAddingToCart"], value: false }
+        ])
+      );
+    }
+  });
+  refs.viewOptionsButton.onclick(({ coordinate }) => {
+    const [productId] = coordinate;
+    const product = cards.get().find((p) => p._id === productId);
+    if (product?.productUrl) {
+      window.location.href = product.productUrl;
+    }
+  });
+  return {
+    resetCache() {
+      variantStockApplied = /* @__PURE__ */ new Set();
+    }
+  };
+}
 const PAGE_SIZE = 12;
 function mapSortToAction(sort) {
   switch (sort) {
@@ -425,7 +605,6 @@ function buildOptionFiltersViewState(baseOptionFilters, filteredResult, optionSe
 }
 function ProductSearchInteractive(props, refs, viewStateSignals, fastCarryForward, storesContext) {
   const baseCategoryId = fastCarryForward.baseCategoryId;
-  const variantStockCache = {};
   const { searchExpression: [searchExpression, setSearchExpression], isSearching: [isSearching, setIsSearching], hasSearched: [hasSearched, setHasSearched], searchResults: [searchResults, setSearchResults], resultCount: [resultCount, setResultCount], hasResults: [hasResults, setHasResults], hasSuggestions: [hasSuggestions, setHasSuggestions], suggestions: [suggestions, setSuggestions], filters: [filters, setFilters], sortBy: [sortBy, setSortBy], hasMore: [hasMore, setHasMore], loadedCount: [loadedCount, setLoadedCount], totalCount: [totalCount, setTotalCount] } = viewStateSignals;
   const [submittedSearchTerm, setSubmittedSearchTerm] = createSignal(null);
   let currentCursor = null;
@@ -476,6 +655,7 @@ function ProductSearchInteractive(props, refs, viewStateSignals, fastCarryForwar
       if (version !== searchVersion) {
         return;
       }
+      resetCardCache();
       setSearchResults(result.products);
       setResultCount(result.products.length);
       setTotalCount(result.totalCount);
@@ -688,182 +868,7 @@ function ProductSearchInteractive(props, refs, viewStateSignals, fastCarryForwar
       setSubmittedSearchTerm(suggestion.suggestionText);
     }
   });
-  refs.searchResults.addToCartButton.onclick(async ({ coordinate }) => {
-    const [productId] = coordinate;
-    const currentResults = searchResults();
-    const productIndex = currentResults.findIndex((p) => p._id === productId);
-    if (productIndex === -1)
-      return;
-    setSearchResults(patch(currentResults, [
-      { op: REPLACE, path: [productIndex, "isAddingToCart"], value: true }
-    ]));
-    try {
-      await storesContext.addToCart(productId, 1);
-    } catch (error) {
-      console.error("Failed to add to cart:", error);
-    } finally {
-      setSearchResults(patch(searchResults(), [
-        { op: REPLACE, path: [productIndex, "isAddingToCart"], value: false }
-      ]));
-    }
-  });
-  const variantStockLoading = /* @__PURE__ */ new Set();
-  const loadVariantStock = async (productId) => {
-    if (variantStockCache[productId] || variantStockLoading.has(productId))
-      return;
-    variantStockLoading.add(productId);
-    try {
-      const currentResults = searchResults();
-      const productIndex = currentResults.findIndex((p) => p._id === productId);
-      if (productIndex === -1)
-        return;
-      const product = currentResults[productIndex];
-      if (product?.quickAddType !== QuickAddType.COLOR_AND_TEXT_OPTIONS)
-        return;
-      const stockMap = await getVariantStock({ productId });
-      variantStockCache[productId] = stockMap;
-      const selectedColor = product.quickOption?.choices?.find((c) => c.isSelected);
-      const textChoices = product.secondQuickOption?.choices;
-      if (!selectedColor || !textChoices)
-        return;
-      const colorStock = stockMap[selectedColor.choiceId];
-      const updatedTextChoices = textChoices.map((c) => ({
-        ...c,
-        inStock: colorStock?.[c.choiceId] ?? false
-      }));
-      setSearchResults(patch(searchResults(), [
-        {
-          op: REPLACE,
-          path: [productIndex, "secondQuickOption", "choices"],
-          value: updatedTextChoices
-        }
-      ]));
-    } finally {
-      variantStockLoading.delete(productId);
-    }
-  };
-  refs.searchResults.productLink.onmouseenter(({ coordinate }) => {
-    const [productId] = coordinate;
-    loadVariantStock(productId);
-  });
-  refs.searchResults.quickOption.choices.choiceButton.onmouseenter(({ coordinate }) => {
-    const [productId] = coordinate;
-    loadVariantStock(productId);
-  });
-  refs.searchResults.quickOption.choices.choiceButton.onclick(async ({ coordinate }) => {
-    const [productId, choiceId] = coordinate;
-    const currentResults = searchResults();
-    const productIndex = currentResults.findIndex((p) => p._id === productId);
-    if (productIndex === -1)
-      return;
-    const product = currentResults[productIndex];
-    if (product.quickAddType === QuickAddType.COLOR_AND_TEXT_OPTIONS) {
-      const choices = product.quickOption?.choices;
-      if (!choices)
-        return;
-      const updatedChoices = choices.map((c) => ({
-        ...c,
-        isSelected: c.choiceId === choiceId
-      }));
-      let updated = patch(currentResults, [
-        {
-          op: REPLACE,
-          path: [productIndex, "quickOption", "choices"],
-          value: updatedChoices
-        }
-      ]);
-      const stockMap = variantStockCache[productId];
-      if (stockMap) {
-        const colorStock = stockMap[choiceId];
-        const textChoices = product.secondQuickOption?.choices;
-        if (textChoices) {
-          const updatedTextChoices = textChoices.map((c) => ({
-            ...c,
-            inStock: colorStock?.[c.choiceId] ?? false
-          }));
-          updated = patch(updated, [
-            {
-              op: REPLACE,
-              path: [productIndex, "secondQuickOption", "choices"],
-              value: updatedTextChoices
-            }
-          ]);
-        }
-      } else {
-        loadVariantStock(productId);
-      }
-      setSearchResults(updated);
-      return;
-    }
-    const choice = product.quickOption?.choices?.find((c) => c.choiceId === choiceId);
-    if (!choice || !choice.inStock) {
-      console.warn("Choice not available or out of stock");
-      return;
-    }
-    setSearchResults(patch(currentResults, [
-      { op: REPLACE, path: [productIndex, "isAddingToCart"], value: true }
-    ]));
-    try {
-      const optionId = product.quickOption._id;
-      await storesContext.addToCart(productId, 1, {
-        options: { [optionId]: choice.choiceId },
-        modifiers: {},
-        customTextFields: {}
-      });
-    } catch (error) {
-      console.error("Failed to add to cart:", error);
-    } finally {
-      setSearchResults(patch(searchResults(), [
-        { op: REPLACE, path: [productIndex, "isAddingToCart"], value: false }
-      ]));
-    }
-  });
-  refs.searchResults.secondQuickOption.choices.choiceButton.onclick(async ({ coordinate }) => {
-    const [productId, choiceId] = coordinate;
-    const currentResults = searchResults();
-    const productIndex = currentResults.findIndex((p) => p._id === productId);
-    if (productIndex === -1)
-      return;
-    const product = currentResults[productIndex];
-    const textChoice = product.secondQuickOption?.choices?.find((c) => c.choiceId === choiceId);
-    const selectedColor = product.quickOption?.choices?.find((c) => c.isSelected);
-    if (!textChoice || !textChoice.inStock) {
-      console.warn("Text choice not available or out of stock");
-      return;
-    }
-    setSearchResults(patch(currentResults, [
-      { op: REPLACE, path: [productIndex, "isAddingToCart"], value: true }
-    ]));
-    try {
-      const colorOptionId = product.quickOption?._id || "";
-      const textOptionId = product.secondQuickOption?._id || "";
-      await storesContext.addToCart(productId, 1, {
-        options: {
-          [colorOptionId]: selectedColor?.choiceId || "",
-          [textOptionId]: textChoice.choiceId
-        },
-        modifiers: {},
-        customTextFields: {}
-      });
-    } catch (error) {
-      console.error("Failed to add to cart:", error);
-    } finally {
-      setSearchResults(patch(searchResults(), [
-        { op: REPLACE, path: [productIndex, "isAddingToCart"], value: false }
-      ]));
-    }
-  });
-  refs.searchResults.secondQuickOption.choices.choiceButton.onmouseenter(({ coordinate }) => {
-    const [productId] = coordinate;
-    loadVariantStock(productId);
-  });
-  refs.searchResults.viewOptionsButton.onclick(({ coordinate }) => {
-    const [productId] = coordinate;
-    const product = searchResults().find((p) => p._id === productId);
-    if (product?.productUrl) {
-      window.location.href = product.productUrl;
-    }
-  });
+  const { resetCache: resetCardCache } = setupCardInteractions(refs.searchResults, { get: searchResults, set: setSearchResults }, storesContext);
   return {
     render: () => ({
       searchExpression: searchExpression(),
@@ -883,6 +888,17 @@ function ProductSearchInteractive(props, refs, viewStateSignals, fastCarryForwar
   };
 }
 const productSearch = makeJayStackComponent().withProps().withContexts(WIX_STORES_CONTEXT).withInteractive(ProductSearchInteractive);
+function RelatedProductsInteractive(_props, refs, viewStateSignals, _fastCarryForward, storesContext) {
+  const { products: [products, setProducts], hasProducts: [hasProducts] } = viewStateSignals;
+  setupCardInteractions(refs.products, { get: products, set: setProducts }, storesContext);
+  return {
+    render: () => ({
+      products: products(),
+      hasProducts: hasProducts()
+    })
+  };
+}
+const relatedProducts = makeJayStackComponent().withProps().withContexts(WIX_STORES_CONTEXT).withInteractive(RelatedProductsInteractive);
 const categoryList = makeJayStackComponent().withProps();
 const init = makeJayInit().withClient(async (data) => {
   console.log("[wix-stores] Initializing client-side stores context...");
@@ -898,5 +914,6 @@ export {
   init,
   productPage,
   productSearch,
-  provideWixStoresContext
+  provideWixStoresContext,
+  relatedProducts
 };

package/dist/index.d.ts

@@ -130,6 +130,7 @@ interface ProductCardViewState {
 interface ProductCardRepeatedRefs {
   productLink: HTMLElementCollectionProxy<ProductCardViewState, HTMLAnchorElement>,
   addToCartButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
+  cardContainer: HTMLElementCollectionProxy<ProductCardViewState, HTMLElement>,
   viewOptionsButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
   quickOption: ProductOptionsRepeatedRefs,
   secondQuickOption: ProductOptionsRepeatedRefs
@@ -744,6 +745,7 @@ interface ProductPageViewState {
   description: string,
   brand: string,
   ribbon: string,
+  categorySlug: string,
   productType: ProductType,
   sku: string,
   price: string,
@@ -758,7 +760,7 @@ interface ProductPageViewState {
   modifiers: Array<ModifierOfProductPageViewState>
 }
 
-type ProductPageSlowViewState = Pick<ProductPageViewState, '_id' | 'productName' | 'description' | 'brand' | 'ribbon' | 'productType'> & {
+type ProductPageSlowViewState = Pick<ProductPageViewState, '_id' | 'productName' | 'description' | 'brand' | 'ribbon' | 'categorySlug' | 'productType'> & {
     options: Array<Pick<ProductPageViewState['options'][number], '_id' | 'name' | 'optionRenderType'> & {
     choices: Array<Pick<ProductPageViewState['options'][number]['choices'][number], 'choiceId' | 'choiceType' | 'name' | 'colorCode' | 'inStock'>>;
 }>;
@@ -864,6 +866,39 @@ interface ProductFastCarryForward {
  */
 declare const productPage: _jay_framework_fullstack_component.JayStackComponentDefinition<ProductPageRefs, ProductPageSlowViewState, ProductPageFastViewState, ProductPageInteractiveViewState, [ProductSlowCarryForward, WixStoresService], [Signals<ProductPageFastViewState>, ProductFastCarryForward, WixStoresContext], PageProps & ProductPageParams, ProductPageParams, _jay_framework_component.JayComponentCore<PageProps & ProductPageParams, ProductPageInteractiveViewState>>;
 
+interface RelatedProductsViewState {
+  products: Array<ProductCardViewState>,
+  hasProducts: boolean,
+  categoryName: string
+}
+
+type RelatedProductsSlowViewState = Pick<RelatedProductsViewState, 'categoryName'>;
+
+type RelatedProductsFastViewState = Pick<RelatedProductsViewState, 'hasProducts'> & {
+    products: Array<RelatedProductsViewState['products'][number]>;
+};
+
+type RelatedProductsInteractiveViewState = Pick<RelatedProductsViewState, 'hasProducts'> & {
+    products: Array<RelatedProductsViewState['products'][number]>;
+};
+
+
+interface RelatedProductsRefs {
+  products: ProductCardRepeatedRefs
+}
+
+interface RelatedProductsProps {
+    productId: string;
+    categorySlug?: string;
+    limit?: number;
+}
+interface RelatedSlowCarryForward {
+    categoryId: string;
+    productId: string;
+    limit: number;
+}
+declare const relatedProducts: _jay_framework_fullstack_component.JayStackComponentDefinition<RelatedProductsRefs, RelatedProductsSlowViewState, RelatedProductsFastViewState, RelatedProductsInteractiveViewState, [RelatedSlowCarryForward, WixStoresService], [Signals<RelatedProductsFastViewState>, Record<string, never>, WixStoresContext], PageProps & RelatedProductsProps, {}, _jay_framework_component.JayComponentCore<PageProps & RelatedProductsProps, RelatedProductsInteractiveViewState>>;
+
 interface CategoryOfCategoryListViewState {
   _id: string,
   name: string,
@@ -1033,4 +1068,4 @@ declare function generateWixStoresReferences(ctx: PluginReferencesContext): Prom
  */
 declare const generator: _jay_framework_fullstack_component.DynamicContractGenerator<[WixStoresService]>;
 
-export { type CategoryListParams, type CategoryTree, type GetProductBySlugInput, type ProductPageParams, type ProductSearchParams, WIX_STORES_CONTEXT, WIX_STORES_SERVICE_MARKER, type WixStoresContext, type WixStoresInitData, type WixStoresService, type WixStoresServiceOptions, buildCategoryUrl, buildProductUrl, categoryList, findCategoryImage, findRootCategoryId, findRootCategorySlug, generateWixStoresReferences, getCategories, getProductBySlug, getVariantStock, init, productPage, generator as productPageContractGenerator, productSearch, provideWixStoresService, searchProducts, setupWixStores };
+export { type CategoryListParams, type CategoryTree, type GetProductBySlugInput, type ProductPageParams, type ProductSearchParams, type RelatedProductsProps, WIX_STORES_CONTEXT, WIX_STORES_SERVICE_MARKER, type WixStoresContext, type WixStoresInitData, type WixStoresService, type WixStoresServiceOptions, buildCategoryUrl, buildProductUrl, categoryList, findCategoryImage, findRootCategoryId, findRootCategorySlug, generateWixStoresReferences, getCategories, getProductBySlug, getVariantStock, init, productPage, generator as productPageContractGenerator, productSearch, provideWixStoresService, relatedProducts, searchProducts, setupWixStores };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { WIX_CART_CONTEXT, WIX_CART_SERVICE, cartIndicator, cartPage, provideWixCartContext, provideWixCartService } from "@jay-framework/wix-cart";
-import { createJayService, makeJayQuery, ActionError, makeJayStackComponent, RenderPipeline, makeJayInit, makeContractGenerator } from "@jay-framework/fullstack-component";
+import { createJayService, makeJayQuery, ActionError, RenderPipeline, makeJayStackComponent, makeJayInit, makeContractGenerator } from "@jay-framework/fullstack-component";
 import { customizationsV3, inventoryItemsV3, productsV3 } from "@wix/stores";
 import { categories } from "@wix/categories";
 import { registerService, getService } from "@jay-framework/stack-server-runtime";
@@ -763,6 +763,19 @@ const getCategories = makeJayQuery("wixStores.getCategories").withServices(WIX_S
     }
   }
 );
+function handleError(error) {
+  const errorCode = error["details"]?.applicationError?.code;
+  if (!!errorCode) {
+    error["details"]?.requestId;
+    if (errorCode === "NOT_FOUND") {
+      return RenderPipeline.for().clientError(404, "not found");
+    }
+    return RenderPipeline.for().serverError(
+      500,
+      "Wix SDK Error: " + error.message
+    );
+  } else return RenderPipeline.for().serverError(500, "unknown server error");
+}
 const PAGE_SIZE = 12;
 function mapSortToAction(sort) {
   switch (sort) {
@@ -941,7 +954,7 @@ async function buildCategoryHeader(wixStoreService, category, categoryUrlTemplat
   }
   return header;
 }
-async function renderSlowlyChanging$2(props, wixStores) {
+async function renderSlowlyChanging$3(props, wixStores) {
   const Pipeline = RenderPipeline.for();
   const categorySlug = props.category ?? null;
   const prefixSlug = props.prefix ?? null;
@@ -982,11 +995,7 @@ async function renderSlowlyChanging$2(props, wixStores) {
       productsResult
     };
   }).recover((error) => {
-    console.error("Failed to load categories/products:", error);
-    return Pipeline.ok({
-      categories: [],
-      productsResult: null
-    });
+    return handleError(error);
   }).toPhaseOutput(({ categories: categories2, productsResult }) => {
     const categoryInfos = categories2.map((cat) => ({
       categoryId: cat._id || "",
@@ -1018,7 +1027,7 @@ async function renderSlowlyChanging$2(props, wixStores) {
     };
   });
 }
-async function renderFastChanging$1(props, slowCarryForward, _wixStores) {
+async function renderFastChanging$2(props, slowCarryForward, _wixStores) {
   const Pipeline = RenderPipeline.for();
   const urlFilters = parseUrlFilters(props.url);
   const initialSort = parseSortParam(urlFilters.sort);
@@ -1134,15 +1143,22 @@ async function renderFastChanging$1(props, slowCarryForward, _wixStores) {
 }
 async function* loadSearchParams([wixStores]) {
   try {
-    let findRootParent = function(cat) {
-      let current = cat;
-      while (current.parentCategory?._id) {
-        const parent = categoryById.get(current.parentCategory._id);
-        if (!parent)
-          break;
-        current = parent;
+    let sumItems = function(node) {
+      for (const child of node.children) {
+        node.itemCount += sumItems(child);
+      }
+      return node.itemCount;
+    }, collectParams = function(node, rootSlug) {
+      if (!node.slug || node.itemCount === 0)
+        return;
+      if (rootSlug) {
+        params.push({ prefix: rootSlug, category: node.slug });
+      } else {
+        params.push({ prefix: node.slug });
+      }
+      for (const child of node.children) {
+        collectParams(child, rootSlug ?? node.slug);
       }
-      return current._id !== cat._id ? current : null;
     };
     const allCategories = [];
     let result = await wixStores.categories.queryCategories({
@@ -1153,29 +1169,52 @@ async function* loadSearchParams([wixStores]) {
       result = await result.next();
       allCategories.push(...result.items || []);
     }
-    const categoryById = /* @__PURE__ */ new Map();
+    const nodeById = /* @__PURE__ */ new Map();
+    const roots = [];
+    const childPendingParent = /* @__PURE__ */ new Map();
     for (const cat of allCategories) {
-      if (cat._id)
-        categoryById.set(cat._id, cat);
-    }
-    const params = [];
-    for (const cat of allCategories) {
-      if (!cat.slug || (cat.itemCounter ?? 0) === 0)
+      if (!cat._id)
         continue;
-      const rootParent = findRootParent(cat);
-      if (rootParent?.slug) {
-        params.push({ prefix: rootParent.slug, category: cat.slug });
+      const node = {
+        slug: cat.slug || "",
+        itemCount: cat.itemCounter ?? 0,
+        children: []
+      };
+      nodeById.set(cat._id, node);
+      const pending = childPendingParent.get(cat._id);
+      if (pending) {
+        node.children.push(...pending);
+        childPendingParent.delete(cat._id);
+      }
+      if (cat.parentCategory?._id) {
+        const parent = nodeById.get(cat.parentCategory._id);
+        if (parent) {
+          parent.children.push(node);
+        } else {
+          const siblings = childPendingParent.get(cat.parentCategory._id);
+          if (siblings)
+            siblings.push(node);
+          else
+            childPendingParent.set(cat.parentCategory._id, [node]);
+        }
       } else {
-        params.push({ prefix: cat.slug });
+        roots.push(node);
       }
     }
+    for (const root of roots) {
+      sumItems(root);
+    }
+    const params = [];
+    for (const root of roots) {
+      collectParams(root, null);
+    }
     yield params;
   } catch (error) {
     console.error("Failed to load category params:", error);
     yield [];
   }
 }
-const productSearch = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadSearchParams).withSlowlyRender(renderSlowlyChanging$2).withFastRender(renderFastChanging$1);
+const productSearch = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadSearchParams).withSlowlyRender(renderSlowlyChanging$3).withFastRender(renderFastChanging$2);
 var ProductType = /* @__PURE__ */ ((ProductType2) => {
   ProductType2[ProductType2["PHYSICAL"] = 0] = "PHYSICAL";
   ProductType2[ProductType2["DIGITAL"] = 1] = "DIGITAL";
@@ -1404,7 +1443,7 @@ function mapVariants(variantsInfo) {
     strikethroughPrice: variant.price.compareAtPrice?.formattedAmount || ""
   })) || [];
 }
-async function renderSlowlyChanging$1(props, wixStores) {
+async function renderSlowlyChanging$2(props, wixStores) {
   const Pipeline = RenderPipeline.for();
   const template = wixStores.urls.product;
   const needsCategories = template.includes("{category}") || template.includes("{prefix}");
@@ -1417,21 +1456,25 @@ async function renderSlowlyChanging$1(props, wixStores) {
       "CURRENCY",
       ...needsCategories ? ["ALL_CATEGORIES_INFO"] : []
     ];
-    const response = await wixStores.products.getProductBySlug(props.slug, {
-      fields: [...fields]
-    });
-    return response;
+    const [response, tree] = await Promise.all([
+      wixStores.products.getProductBySlug(props.slug, {
+        fields: [...fields]
+      }),
+      wixStores.getCategoryTree()
+    ]);
+    return { response, tree };
   }).recover((error) => {
-    console.log("product page error", error);
-    return Pipeline.clientError(404, "not found");
-  }).toPhaseOutput((getProductResponse) => {
+    return handleError(error);
+  }).toPhaseOutput(({ response: getProductResponse, tree }) => {
     const product = getProductResponse.product;
     const { _id, name, plainDescription, options, modifiers, actualPriceRange, compareAtPriceRange, media, productType, brand, ribbon, infoSections, seoData, physicalProperties, inventory, variantsInfo } = product;
+    const categorySlug = tree.slugMap.get(product.mainCategoryId) || "";
     return {
       viewState: {
         _id,
         productName: name || "",
         description: plainDescription,
+        categorySlug,
         brand: brand?.name || "",
         ribbon: ribbon?.name || "",
         productType: mapProductType(productType),
@@ -1456,7 +1499,7 @@ async function renderSlowlyChanging$1(props, wixStores) {
     };
   });
 }
-async function renderFastChanging(props, slowCarryForward, wixStores) {
+async function renderFastChanging$1(props, slowCarryForward, wixStores) {
   const Pipeline = RenderPipeline.for();
   const { variants } = slowCarryForward;
   const defaultVariant = variants.find((v) => v.inventoryStatus === StockStatus.IN_STOCK) || variants[0];
@@ -1506,7 +1549,78 @@ async function renderFastChanging(props, slowCarryForward, wixStores) {
     }
   }));
 }
-const productPage = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadProductParams).withSlowlyRender(renderSlowlyChanging$1).withFastRender(renderFastChanging);
+const productPage = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadProductParams).withSlowlyRender(renderSlowlyChanging$2).withFastRender(renderFastChanging$1);
+const DEFAULT_LIMIT = 4;
+async function renderSlowlyChanging$1(props, wixStores) {
+  const Pipeline = RenderPipeline.for();
+  const limit = props.limit ?? DEFAULT_LIMIT;
+  return Pipeline.try(async () => {
+    const categorySlug = props.categorySlug;
+    if (!categorySlug) {
+      return { categoryId: "", categoryName: "" };
+    }
+    const tree = await wixStores.getCategoryTree();
+    let categoryId = "";
+    let categoryName = "";
+    for (const [id, slug] of tree.slugMap) {
+      if (slug === categorySlug) {
+        categoryId = id;
+        categoryName = slug;
+        break;
+      }
+    }
+    if (categoryId) {
+      try {
+        const result = await wixStores.categories.queryCategories({ treeReference: { appNamespace: "@wix/stores" } }).eq("_id", categoryId).limit(1).find();
+        if (result.items?.[0]?.name) {
+          categoryName = result.items[0].name;
+        }
+      } catch {
+      }
+    }
+    return { categoryId, categoryName };
+  }).recover((error) => {
+    return handleError(error);
+  }).toPhaseOutput(({ categoryId, categoryName }) => ({
+    viewState: {
+      categoryName
+    },
+    carryForward: {
+      categoryId,
+      productId: props.productId,
+      limit
+    }
+  }));
+}
+async function renderFastChanging(_props, slowCarryForward, _wixStores) {
+  const Pipeline = RenderPipeline.for();
+  const { categoryId, productId, limit } = slowCarryForward;
+  if (!categoryId) {
+    return Pipeline.ok({
+      products: [],
+      hasProducts: false
+    }).toPhaseOutput((viewState) => ({ viewState, carryForward: {} }));
+  }
+  return Pipeline.try(async () => {
+    const result = await searchProducts({
+      query: "",
+      filters: { categoryIds: [categoryId] },
+      pageSize: limit + 1
+    });
+    const products = result.products.filter((p) => p._id !== productId).slice(0, limit);
+    return {
+      products,
+      hasProducts: products.length > 0
+    };
+  }).recover((error) => {
+    console.error("Failed to load related products:", error);
+    return Pipeline.ok({
+      products: [],
+      hasProducts: false
+    });
+  }).toPhaseOutput((viewState) => ({ viewState, carryForward: {} }));
+}
+const relatedProducts = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withSlowlyRender(renderSlowlyChanging$1).withFastRender(renderFastChanging);
 async function findCategoryBySlug(categoriesClient, slug) {
   const result = await categoriesClient.queryCategories({ treeReference: { appNamespace: "@wix/stores" } }).eq("slug", slug).eq("visible", true).limit(1).find();
   return result.items?.[0] ?? null;
@@ -1859,6 +1973,7 @@ tags:
   - {tag: description, type: data, dataType: string, description: Product description}
   - {tag: brand, type: data, dataType: string, description: Brand name}
   - {tag: ribbon, type: data, dataType: string, description: "Ribbon text (e.g., \\"New\\", \\"Sale\\")"}
+  - {tag: categorySlug, type: data, dataType: string, description: Slug of the product's main category}
   - {tag: productType, type: variant, dataType: "enum (PHYSICAL | DIGITAL)", description: Product type }
 
   - {tag: sku, type: data, dataType: string, phase: fast+interactive, description: Product SKU, or chosen variant SKU}
@@ -1991,6 +2106,7 @@ export {
   provideWixCartContext,
   provideWixCartService,
   provideWixStoresService,
+  relatedProducts,
   searchProducts,
   setupWixStores
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/wix-stores",
-  "version": "0.16.5",
+  "version": "0.17.1",
   "type": "module",
   "description": "Wix Stores API client for Jay Framework",
   "license": "Apache-2.0",
@@ -17,6 +17,7 @@
     "./media.jay-contract": "./dist/contracts/media.jay-contract",
     "./media-gallery.jay-contract": "./dist/contracts/media-gallery.jay-contract",
     "./product-search.jay-contract": "./dist/contracts/product-search.jay-contract",
+    "./related-products.jay-contract": "./dist/contracts/related-products.jay-contract",
     "./category-list.jay-contract": "./dist/contracts/category-list.jay-contract",
     "./search-products.jay-action": "./dist/actions/search-products.jay-action",
     "./get-product-by-slug.jay-action": "./dist/actions/get-product-by-slug.jay-action",
@@ -37,16 +38,16 @@
     "test": ":"
   },
   "dependencies": {
-    "@jay-framework/component": "^0.16.5",
-    "@jay-framework/fullstack-component": "^0.16.5",
-    "@jay-framework/reactive": "^0.16.5",
-    "@jay-framework/runtime": "^0.16.5",
-    "@jay-framework/secure": "^0.16.5",
-    "@jay-framework/stack-client-runtime": "^0.16.5",
-    "@jay-framework/stack-server-runtime": "^0.16.5",
-    "@jay-framework/wix-cart": "^0.16.5",
-    "@jay-framework/wix-server-client": "^0.16.5",
-    "@jay-framework/wix-utils": "^0.16.5",
+    "@jay-framework/component": "^0.17.1",
+    "@jay-framework/fullstack-component": "^0.17.1",
+    "@jay-framework/reactive": "^0.17.1",
+    "@jay-framework/runtime": "^0.17.1",
+    "@jay-framework/secure": "^0.17.1",
+    "@jay-framework/stack-client-runtime": "^0.17.1",
+    "@jay-framework/stack-server-runtime": "^0.17.1",
+    "@jay-framework/wix-cart": "^0.17.1",
+    "@jay-framework/wix-server-client": "^0.17.1",
+    "@jay-framework/wix-utils": "^0.17.1",
     "@wix/categories": "^1.0.185",
     "@wix/data-extension-schema": "^1.0.221",
     "@wix/sdk": "^1.21.5",
@@ -58,10 +59,10 @@
     "@babel/core": "^7.23.7",
     "@babel/preset-env": "^7.23.8",
     "@babel/preset-typescript": "^7.23.3",
-    "@jay-framework/compiler-jay-stack": "^0.16.5",
-    "@jay-framework/jay-cli": "^0.16.5",
-    "@jay-framework/jay-stack-cli": "^0.16.5",
-    "@jay-framework/vite-plugin": "^0.16.5",
+    "@jay-framework/compiler-jay-stack": "^0.17.1",
+    "@jay-framework/jay-cli": "^0.17.1",
+    "@jay-framework/jay-stack-cli": "^0.17.1",
+    "@jay-framework/vite-plugin": "^0.17.1",
     "nodemon": "^3.0.3",
     "rimraf": "^5.0.5",
     "tslib": "^2.6.2",

package/plugin.yaml

@@ -7,6 +7,10 @@ contracts:
     component: productSearch
     description: Headless product search page
   # category-page removed — use product-search with prefix/category params instead
+  - name: related-products
+    contract: related-products.jay-contract
+    component: relatedProducts
+    description: Related products from the same category
   - name: category-list
     contract: category-list.jay-contract
     component: categoryList