@jay-framework/wix-stores 0.17.0 → 0.17.2

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,184 @@ 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,8 +603,6 @@ function buildOptionFiltersViewState(baseOptionFilters, filteredResult, optionSe
 }
 function ProductSearchInteractive(props, refs, viewStateSignals, fastCarryForward, storesContext) {
   const baseCategoryId = fastCarryForward.baseCategoryId;
-  const variantStockCache = {};
-  let variantStockApplied = /* @__PURE__ */ new Set();
   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;
@@ -477,7 +653,7 @@ function ProductSearchInteractive(props, refs, viewStateSignals, fastCarryForwar
       if (version !== searchVersion) {
         return;
       }
-      variantStockApplied = /* @__PURE__ */ new Set();
+      resetCardCache();
       setSearchResults(result.products);
       setResultCount(result.products.length);
       setTotalCount(result.totalCount);
@@ -690,175 +866,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 (variantStockApplied.has(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 = 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
-      }));
-      setSearchResults(patch(searchResults(), [
-        {
-          op: REPLACE,
-          path: [productIndex, "secondQuickOption", "choices"],
-          value: updatedTextChoices
-        }
-      ]));
-    } finally {
-      variantStockLoading.delete(productId);
-    }
-  };
-  refs.searchResults.cardContainer.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.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(),
@@ -878,6 +886,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...");
@@ -893,5 +912,6 @@ export {
   init,
   productPage,
   productSearch,
-  provideWixStoresContext
+  provideWixStoresContext,
+  relatedProducts
 };

package/dist/index.d.ts

@@ -745,6 +745,7 @@ interface ProductPageViewState {
   description: string,
   brand: string,
   ribbon: string,
+  categorySlug: string,
   productType: ProductType,
   sku: string,
   price: string,
@@ -759,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'>>;
 }>;
@@ -865,6 +866,37 @@ 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 {
+    products: ProductCardViewState[];
+}
+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,
@@ -1034,4 +1066,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

@@ -954,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;
@@ -1027,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);
@@ -1214,7 +1214,7 @@ async function* loadSearchParams([wixStores]) {
     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";
@@ -1443,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}");
@@ -1456,20 +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) => {
     return handleError(error);
-  }).toPhaseOutput((getProductResponse) => {
+  }).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),
@@ -1494,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];
@@ -1544,7 +1549,61 @@ 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;
+  const categorySlug = props.categorySlug;
+  if (!categorySlug) {
+    return Pipeline.ok({ categoryName: "" }).toPhaseOutput((viewState) => ({
+      viewState,
+      carryForward: { products: [] }
+    }));
+  }
+  return Pipeline.try(async () => {
+    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) {
+      return { categoryName: "", products: [] };
+    }
+    const [categoryResult, searchResult] = await Promise.all([
+      wixStores.categories.queryCategories({ treeReference: { appNamespace: "@wix/stores" } }).eq("_id", categoryId).limit(1).find().catch(() => null),
+      searchProducts({
+        query: "",
+        filters: { categoryIds: [categoryId] },
+        pageSize: limit + 1
+      })
+    ]);
+    if (categoryResult?.items?.[0]?.name) {
+      categoryName = categoryResult.items[0].name;
+    }
+    const products = searchResult.products.filter((p) => p._id !== props.productId).slice(0, limit);
+    return { categoryName, products };
+  }).recover((error) => {
+    return handleError(error);
+  }).toPhaseOutput(({ categoryName, products }) => ({
+    viewState: { categoryName },
+    carryForward: { products }
+  }));
+}
+async function renderFastChanging(_props, slowCarryForward, _wixStores) {
+  const Pipeline = RenderPipeline.for();
+  const { products } = slowCarryForward;
+  return Pipeline.ok({
+    products,
+    hasProducts: products.length > 0
+  }).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;
@@ -1897,6 +1956,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}
@@ -2029,6 +2089,7 @@ export {
   provideWixCartContext,
   provideWixCartService,
   provideWixStoresService,
+  relatedProducts,
   searchProducts,
   setupWixStores
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/wix-stores",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "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.17.0",
-    "@jay-framework/fullstack-component": "^0.17.0",
-    "@jay-framework/reactive": "^0.17.0",
-    "@jay-framework/runtime": "^0.17.0",
-    "@jay-framework/secure": "^0.17.0",
-    "@jay-framework/stack-client-runtime": "^0.17.0",
-    "@jay-framework/stack-server-runtime": "^0.17.0",
-    "@jay-framework/wix-cart": "^0.17.0",
-    "@jay-framework/wix-server-client": "^0.17.0",
-    "@jay-framework/wix-utils": "^0.17.0",
+    "@jay-framework/component": "^0.17.2",
+    "@jay-framework/fullstack-component": "^0.17.2",
+    "@jay-framework/reactive": "^0.17.2",
+    "@jay-framework/runtime": "^0.17.2",
+    "@jay-framework/secure": "^0.17.2",
+    "@jay-framework/stack-client-runtime": "^0.17.2",
+    "@jay-framework/stack-server-runtime": "^0.17.2",
+    "@jay-framework/wix-cart": "^0.17.2",
+    "@jay-framework/wix-server-client": "^0.17.2",
+    "@jay-framework/wix-utils": "^0.17.2",
     "@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.17.0",
-    "@jay-framework/jay-cli": "^0.17.0",
-    "@jay-framework/jay-stack-cli": "^0.17.0",
-    "@jay-framework/vite-plugin": "^0.17.0",
+    "@jay-framework/compiler-jay-stack": "^0.17.2",
+    "@jay-framework/jay-cli": "^0.17.2",
+    "@jay-framework/jay-stack-cli": "^0.17.2",
+    "@jay-framework/vite-plugin": "^0.17.2",
     "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