@jay-framework/wix-stores 0.19.5 → 0.19.7

package/dist/agent-kit/aiditor/add-menu.template.yaml

@@ -25,19 +25,33 @@ items:
       Script key: p
       Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md.
 
-  - id: wix-stores:related-products
-    title: Related products
+  - id: wix-stores:category-products
+    title: Category products
     category: Store
     subCategory: Components
     pluginName: wix-stores
     packageName: "@jay-framework/wix-stores"
-    thumbnail: thumbnails/wix-stores/related-products.png
+    thumbnail: thumbnails/wix-stores/category-products.png
     prompt: |
-      Use headless component @jay-framework/wix-stores / contract related-products.
-      Read agent-kit/materialized-contracts/wix-stores/related-products.jay-contract.
+      Use headless component @jay-framework/wix-stores / contract category-products.
+      Read agent-kit/materialized-contracts/wix-stores/category-products.jay-contract.
       Script key: r
       Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md.
-      Use alongside product-page; pass productId and categorySlug as instance props.
+      Pass categorySlug to show products from a category. Pass productId to exclude a product (e.g. on a product page).
+
+  - id: wix-stores:product-spotlight
+    title: Product spotlight
+    category: Store
+    subCategory: Components
+    pluginName: wix-stores
+    packageName: "@jay-framework/wix-stores"
+    thumbnail: thumbnails/wix-stores/product-spotlight.png
+    prompt: |
+      Use headless component @jay-framework/wix-stores / contract product-spotlight.
+      Read agent-kit/materialized-contracts/wix-stores/product-spotlight.jay-contract.
+      Script key: spotlight
+      Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md.
+      Pass slug as a prop to specify which product to display.
 
   - id: wix-stores:category-list
     title: Category list

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

@@ -0,0 +1,31 @@
+name: category-products
+description: Products from a specific category. Use for category product showcases, or as related products on a product page (pass productId to exclude the current product).
+props:
+  - name: productId
+    type: string
+    description: Product ID to exclude from results (optional, use for related products)
+  - name: categorySlug
+    type: string
+    description: Category slug to filter products by
+  - name: limit
+    type: number
+    description: Maximum number of products to show (default 4)
+tags:
+  - tag: products
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    phase: fast+interactive
+    description: Product cards from the category
+    link: ./product-card
+
+  - tag: hasProducts
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Whether there are products to show
+
+  - tag: categoryName
+    type: data
+    dataType: string
+    description: Name of the category these products belong to

package/dist/contracts/category-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 CategoryProductsViewState {
+  products: Array<ProductCardViewState>,
+  hasProducts: boolean,
+  categoryName: string
+}
+
+export type CategoryProductsSlowViewState = Pick<CategoryProductsViewState, 'categoryName'>;
+
+export type CategoryProductsFastViewState = Pick<CategoryProductsViewState, 'hasProducts'> & {
+    products: Array<CategoryProductsViewState['products'][number]>;
+};
+
+export type CategoryProductsInteractiveViewState = Pick<CategoryProductsViewState, 'hasProducts'> & {
+    products: Array<CategoryProductsViewState['products'][number]>;
+};
+
+
+export interface CategoryProductsRefs {
+  products: ProductCardRepeatedRefs
+}
+
+
+export interface CategoryProductsRepeatedRefs {
+  products: ProductCardRepeatedRefs
+}
+
+export interface CategoryProductsProps {
+  productId?: string;
+  categorySlug?: string;
+  limit?: number;
+}
+
+export type CategoryProductsContract = JayContract<CategoryProductsViewState, CategoryProductsRefs, CategoryProductsSlowViewState, CategoryProductsFastViewState, CategoryProductsInteractiveViewState, CategoryProductsProps>

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

@@ -0,0 +1,16 @@
+name: product-spotlight
+description: A single product card by slug. Use to feature a specific product on any page (homepage, content pages, etc.).
+props:
+  - name: slug
+    type: string
+    description: Product slug to display
+tags:
+  - tag: product
+    type: sub-contract
+    description: The product card
+    link: ./product-card
+
+  - tag: hasProduct
+    type: variant
+    dataType: boolean
+    description: Whether the product was found

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

@@ -0,0 +1,61 @@
+import {JayContract} from "@jay-framework/runtime";
+import {ProductCardViewState, ProductCardRefs, ProductCardRepeatedRefs} from "./product-card.jay-contract";
+
+export interface ProductSpotlightViewState {
+  product: ProductCardViewState,
+  hasProduct: boolean
+}
+
+export type ProductSpotlightSlowViewState = Pick<ProductSpotlightViewState, 'hasProduct'> & {
+    product: Pick<ProductSpotlightViewState['product'], '_id' | 'name' | 'slug' | 'productUrl' | 'categoryPrefix' | 'hasDiscount' | 'hasRibbon' | 'productType' | 'quickAddType'> & {
+    mainMedia: ProductSpotlightViewState['product']['mainMedia'];
+    thumbnail: ProductSpotlightViewState['product']['thumbnail'];
+    inventory: ProductSpotlightViewState['product']['inventory'];
+    ribbon: ProductSpotlightViewState['product']['ribbon'];
+    brand: ProductSpotlightViewState['product']['brand'];
+    quickOption: Pick<ProductSpotlightViewState['product']['quickOption'], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode'>>;
+};
+    secondQuickOption: Pick<ProductSpotlightViewState['product']['secondQuickOption'], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode'>>;
+};
+};
+};
+
+export type ProductSpotlightFastViewState = {
+    product: Pick<ProductSpotlightViewState['product'], 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+    secondQuickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+};
+};
+
+export type ProductSpotlightInteractiveViewState = {
+    product: Pick<ProductSpotlightViewState['product'], 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+    secondQuickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+};
+};
+
+
+export interface ProductSpotlightRefs {
+  product: ProductCardRefs
+}
+
+
+export interface ProductSpotlightRepeatedRefs {
+  product: ProductCardRepeatedRefs
+}
+
+export interface ProductSpotlightProps {
+  slug?: string;
+}
+
+export type ProductSpotlightContract = JayContract<ProductSpotlightViewState, ProductSpotlightRefs, ProductSpotlightSlowViewState, ProductSpotlightFastViewState, ProductSpotlightInteractiveViewState, ProductSpotlightProps>

package/dist/index.client.js

@@ -886,7 +886,7 @@ function ProductSearchInteractive(props, refs, viewStateSignals, fastCarryForwar
   };
 }
 const productSearch = makeJayStackComponent().withProps().withContexts(WIX_STORES_CONTEXT).withInteractive(ProductSearchInteractive);
-function RelatedProductsInteractive(_props, refs, viewStateSignals, _fastCarryForward, storesContext) {
+function CategoryProductsInteractive(_props, refs, viewStateSignals, _fastCarryForward, storesContext) {
   const { products: [products, setProducts], hasProducts: [hasProducts] } = viewStateSignals;
   setupCardInteractions(refs.products, { get: products, set: setProducts }, storesContext);
   return {
@@ -896,7 +896,34 @@ function RelatedProductsInteractive(_props, refs, viewStateSignals, _fastCarryFo
     })
   };
 }
-const relatedProducts = makeJayStackComponent().withProps().withContexts(WIX_STORES_CONTEXT).withInteractive(RelatedProductsInteractive);
+const categoryProducts = makeJayStackComponent().withProps().withContexts(WIX_STORES_CONTEXT).withInteractive(CategoryProductsInteractive);
+function ProductSpotlightInteractive(_props, refs, viewStateSignals, fastCarryForward, storesContext) {
+  const { product: [product, setProduct] } = viewStateSignals;
+  const fullProduct = fastCarryForward.product;
+  refs.product.addToCartButton.onclick(async () => {
+    if (!fullProduct._id || fullProduct.quickAddType !== QuickAddType.SIMPLE)
+      return;
+    setProduct({ ...product(), isAddingToCart: true });
+    try {
+      await storesContext.addToCart(fullProduct._id, 1);
+    } catch (error) {
+      console.error("Failed to add to cart:", error);
+    } finally {
+      setProduct({ ...product(), isAddingToCart: false });
+    }
+  });
+  refs.product.viewOptionsButton.onclick(() => {
+    if (fullProduct.productUrl) {
+      window.location.href = fullProduct.productUrl;
+    }
+  });
+  return {
+    render: () => ({
+      product: product()
+    })
+  };
+}
+const productSpotlight = makeJayStackComponent().withProps().withContexts(WIX_STORES_CONTEXT).withInteractive(ProductSpotlightInteractive);
 const categoryList = makeJayStackComponent().withProps();
 const init = makeJayInit().withClient(async (data) => {
   console.log("[wix-stores] Initializing client-side stores context...");
@@ -909,9 +936,10 @@ export {
   cartIndicator,
   cartPage,
   categoryList,
+  categoryProducts,
   init,
   productPage,
   productSearch,
-  provideWixStoresContext,
-  relatedProducts
+  productSpotlight,
+  provideWixStoresContext
 };

package/dist/index.d.ts

@@ -41,6 +41,13 @@ interface ProductOptionsViewState {
 }
 
 
+interface ProductOptionsRefs {
+  choices: {
+    choiceButton: HTMLElementCollectionProxy<ChoiceOfProductOptionsViewState, HTMLButtonElement>
+  }
+}
+
+
 interface ProductOptionsRepeatedRefs {
   choices: {
     choiceButton: HTMLElementCollectionProxy<ChoiceOfProductOptionsViewState, HTMLButtonElement>
@@ -127,6 +134,16 @@ interface ProductCardViewState {
 }
 
 
+interface ProductCardRefs {
+  productLink: HTMLElementProxy<ProductCardViewState, HTMLAnchorElement>,
+  addToCartButton: HTMLElementProxy<ProductCardViewState, HTMLButtonElement>,
+  cardContainer: HTMLElementProxy<ProductCardViewState, HTMLElement>,
+  viewOptionsButton: HTMLElementProxy<ProductCardViewState, HTMLButtonElement>,
+  quickOption: ProductOptionsRefs,
+  secondQuickOption: ProductOptionsRefs
+}
+
+
 interface ProductCardRepeatedRefs {
   productLink: HTMLElementCollectionProxy<ProductCardViewState, HTMLAnchorElement>,
   addToCartButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
@@ -865,36 +882,92 @@ 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 {
+interface CategoryProductsViewState {
   products: Array<ProductCardViewState>,
   hasProducts: boolean,
   categoryName: string
 }
 
-type RelatedProductsSlowViewState = Pick<RelatedProductsViewState, 'categoryName'>;
+type CategoryProductsSlowViewState = Pick<CategoryProductsViewState, 'categoryName'>;
 
-type RelatedProductsFastViewState = Pick<RelatedProductsViewState, 'hasProducts'> & {
-    products: Array<RelatedProductsViewState['products'][number]>;
+type CategoryProductsFastViewState = Pick<CategoryProductsViewState, 'hasProducts'> & {
+    products: Array<CategoryProductsViewState['products'][number]>;
 };
 
-type RelatedProductsInteractiveViewState = Pick<RelatedProductsViewState, 'hasProducts'> & {
-    products: Array<RelatedProductsViewState['products'][number]>;
+type CategoryProductsInteractiveViewState = Pick<CategoryProductsViewState, 'hasProducts'> & {
+    products: Array<CategoryProductsViewState['products'][number]>;
 };
 
 
-interface RelatedProductsRefs {
+interface CategoryProductsRefs {
   products: ProductCardRepeatedRefs
 }
 
-interface RelatedProductsProps {
-    productId: string;
+interface CategoryProductsProps {
+    productId?: string;
     categorySlug?: string;
     limit?: number;
 }
-interface RelatedSlowCarryForward {
+interface SlowCarryForward {
     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>>;
+declare const categoryProducts: _jay_framework_fullstack_component.JayStackComponentDefinition<CategoryProductsRefs, CategoryProductsSlowViewState, CategoryProductsFastViewState, CategoryProductsInteractiveViewState, [SlowCarryForward, WixStoresService], [Signals<CategoryProductsFastViewState>, Record<string, never>, WixStoresContext], PageProps & CategoryProductsProps, {}, _jay_framework_component.JayComponentCore<PageProps & CategoryProductsProps, CategoryProductsInteractiveViewState>>;
+
+interface ProductSpotlightViewState {
+  product: ProductCardViewState,
+  hasProduct: boolean
+}
+
+type ProductSpotlightSlowViewState = Pick<ProductSpotlightViewState, 'hasProduct'> & {
+    product: Pick<ProductSpotlightViewState['product'], '_id' | 'name' | 'slug' | 'productUrl' | 'categoryPrefix' | 'hasDiscount' | 'hasRibbon' | 'productType' | 'quickAddType'> & {
+    mainMedia: ProductSpotlightViewState['product']['mainMedia'];
+    thumbnail: ProductSpotlightViewState['product']['thumbnail'];
+    inventory: ProductSpotlightViewState['product']['inventory'];
+    ribbon: ProductSpotlightViewState['product']['ribbon'];
+    brand: ProductSpotlightViewState['product']['brand'];
+    quickOption: Pick<ProductSpotlightViewState['product']['quickOption'], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode'>>;
+};
+    secondQuickOption: Pick<ProductSpotlightViewState['product']['secondQuickOption'], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode'>>;
+};
+};
+};
+
+type ProductSpotlightFastViewState = {
+    product: Pick<ProductSpotlightViewState['product'], 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+    secondQuickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+};
+};
+
+type ProductSpotlightInteractiveViewState = {
+    product: Pick<ProductSpotlightViewState['product'], 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+    secondQuickOption: {
+    choices: Array<Pick<ProductSpotlightViewState['product']['secondQuickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+};
+};
+
+
+interface ProductSpotlightRefs {
+  product: ProductCardRefs
+}
+
+interface ProductSpotlightProps {
+    slug: string;
+}
+interface SpotlightCarryForward {
+    product: ProductCardViewState;
+}
+declare const productSpotlight: _jay_framework_fullstack_component.JayStackComponentDefinition<ProductSpotlightRefs, ProductSpotlightSlowViewState, ProductSpotlightFastViewState, ProductSpotlightInteractiveViewState, [SpotlightCarryForward, WixStoresService], [Signals<ProductSpotlightFastViewState>, SpotlightCarryForward, WixStoresContext], PageProps & ProductSpotlightProps, {}, _jay_framework_component.JayComponentCore<PageProps & ProductSpotlightProps, ProductSpotlightInteractiveViewState>>;
 
 interface CategoryOfCategoryListViewState {
   _id: string,
@@ -1065,4 +1138,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, 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 };
+export { type CategoryListParams, type CategoryProductsProps, type CategoryTree, type GetProductBySlugInput, type ProductPageParams, type ProductSearchParams, type ProductSpotlightProps, WIX_STORES_CONTEXT, WIX_STORES_SERVICE_MARKER, type WixStoresContext, type WixStoresInitData, type WixStoresService, type WixStoresServiceOptions, buildCategoryUrl, buildProductUrl, categoryList, categoryProducts, findCategoryImage, findRootCategoryId, findRootCategorySlug, generateWixStoresReferences, getCategories, getProductBySlug, getVariantStock, init, productPage, generator as productPageContractGenerator, productSearch, productSpotlight, provideWixStoresService, searchProducts, setupWixStores };

package/dist/index.js

@@ -716,6 +716,7 @@ const getProductBySlug = makeJayQuery("wixStores.getProductBySlug").withServices
       const fields = [
         "MEDIA_ITEMS_INFO",
         "VARIANT_OPTION_CHOICE_NAMES",
+        "CURRENCY",
         ...needsCategoryInfo(wixStores) ? ["ALL_CATEGORIES_INFO"] : []
       ];
       const result = await wixStores.products.getProductBySlug(slug, {
@@ -955,7 +956,7 @@ async function buildCategoryHeader(wixStoreService, category, categoryUrlTemplat
   }
   return header;
 }
-async function renderSlowlyChanging$3(props, wixStores) {
+async function renderSlowlyChanging$4(props, wixStores) {
   const Pipeline = RenderPipeline.for();
   const categorySlug = props.category ?? null;
   const prefixSlug = props.prefix ?? null;
@@ -1028,7 +1029,7 @@ async function renderSlowlyChanging$3(props, wixStores) {
     };
   });
 }
-async function renderFastChanging$2(props, slowCarryForward, _wixStores) {
+async function renderFastChanging$3(props, slowCarryForward, _wixStores) {
   const Pipeline = RenderPipeline.for();
   const urlFilters = parseUrlFilters(props.url);
   const initialSort = parseSortParam(urlFilters.sort);
@@ -1215,7 +1216,7 @@ async function* loadSearchParams([wixStores]) {
     yield [];
   }
 }
-const productSearch = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadSearchParams).withSlowlyRender(renderSlowlyChanging$3).withFastRender(renderFastChanging$2);
+const productSearch = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadSearchParams).withSlowlyRender(renderSlowlyChanging$4).withFastRender(renderFastChanging$3);
 var ProductType = /* @__PURE__ */ ((ProductType2) => {
   ProductType2[ProductType2["PHYSICAL"] = 0] = "PHYSICAL";
   ProductType2[ProductType2["DIGITAL"] = 1] = "DIGITAL";
@@ -1314,15 +1315,22 @@ function mapInfoSections(infoSections) {
     uniqueName: infoSection.uniqueName || ""
   }));
 }
-function mapSeoHeadTags(seoData) {
-  if (!seoData)
-    return [];
-  const headTags = (seoData.tags || []).map((tag) => ({
+function mapSeoHeadTags(product, seoData) {
+  const headTags = (seoData?.tags || []).map((tag) => ({
     tag: tag.type || "meta",
     attrs: Object.fromEntries(Object.entries(tag.props || {}).map(([key, value]) => [key, value])),
     children: tag.children || void 0
   }));
-  const keywords = seoData.settings?.keywords;
+  if (!headTags.some((t) => t.tag === "title") && product.name) {
+    headTags.push({ tag: "title", children: product.name });
+  }
+  if (!headTags.some((t) => t.tag === "meta" && t.attrs?.name === "description") && product.plainDescription) {
+    headTags.push({
+      tag: "meta",
+      attrs: { name: "description", content: product.plainDescription }
+    });
+  }
+  const keywords = seoData?.settings?.keywords;
   if (keywords?.length) {
     const terms = keywords.map((k) => k.term).filter(Boolean);
     if (terms.length) {
@@ -1442,7 +1450,7 @@ function mapVariants(variantsInfo) {
     strikethroughPrice: variant.price.compareAtPrice?.formattedAmount || ""
   })) || [];
 }
-async function renderSlowlyChanging$2(props, wixStores) {
+async function renderSlowlyChanging$3(props, wixStores) {
   const Pipeline = RenderPipeline.for();
   const template = wixStores.urls.product;
   const needsCategories = template.includes("{category}") || template.includes("{prefix}");
@@ -1482,7 +1490,7 @@ async function renderSlowlyChanging$2(props, wixStores) {
         modifiers: mapModifiersToSlowVS(modifiers),
         extendedFields: mapExtendedFields(product)
       },
-      headTags: mapSeoHeadTags(seoData),
+      headTags: mapSeoHeadTags({ name, plainDescription }, seoData),
       carryForward: {
         productId: _id,
         mediaGallery: mapMedia(media),
@@ -1498,7 +1506,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 { variants } = slowCarryForward;
   const defaultVariant = variants.find((v) => v.inventoryStatus === StockStatus.IN_STOCK) || variants[0];
@@ -1548,9 +1556,9 @@ async function renderFastChanging$1(props, slowCarryForward, wixStores) {
     }
   }));
 }
-const productPage = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadProductParams).withSlowlyRender(renderSlowlyChanging$2).withFastRender(renderFastChanging$1);
+const productPage = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withLoadParams(loadProductParams).withSlowlyRender(renderSlowlyChanging$3).withFastRender(renderFastChanging$2);
 const DEFAULT_LIMIT = 4;
-async function renderSlowlyChanging$1(props, wixStores) {
+async function renderSlowlyChanging$2(props, wixStores) {
   const Pipeline = RenderPipeline.for();
   const limit = props.limit ?? DEFAULT_LIMIT;
   const categorySlug = props.categorySlug;
@@ -1594,7 +1602,7 @@ async function renderSlowlyChanging$1(props, wixStores) {
     carryForward: { products }
   }));
 }
-async function renderFastChanging(_props, slowCarryForward, _wixStores) {
+async function renderFastChanging$1(_props, slowCarryForward, _wixStores) {
   const Pipeline = RenderPipeline.for();
   const { products } = slowCarryForward;
   return Pipeline.ok({
@@ -1602,7 +1610,95 @@ async function renderFastChanging(_props, slowCarryForward, _wixStores) {
     hasProducts: products.length > 0
   }).toPhaseOutput((viewState) => ({ viewState, carryForward: {} }));
 }
-const relatedProducts = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withSlowlyRender(renderSlowlyChanging$1).withFastRender(renderFastChanging);
+const categoryProducts = makeJayStackComponent().withProps().withServices(WIX_STORES_SERVICE_MARKER).withSlowlyRender(renderSlowlyChanging$2).withFastRender(renderFastChanging$1);
+async function renderSlowlyChanging$1(props, _wixStores) {
+  const Pipeline = RenderPipeline.for();
+  return Pipeline.try(async () => {
+    if (!props.slug) {
+      throw new Error("No product slug provided");
+    }
+    const card = await getProductBySlug({ slug: props.slug });
+    if (!card) {
+      throw new Error(`Product not found: ${props.slug}`);
+    }
+    return card;
+  }).recover((error) => {
+    return handleError(error);
+  }).toPhaseOutput((product) => {
+    return {
+      viewState: {
+        hasProduct: true,
+        product: {
+          _id: product._id,
+          name: product.name,
+          slug: product.slug,
+          productUrl: product.productUrl,
+          categoryPrefix: product.categoryPrefix,
+          mainMedia: product.mainMedia,
+          thumbnail: product.thumbnail,
+          hasDiscount: product.hasDiscount,
+          inventory: product.inventory,
+          ribbon: product.ribbon,
+          hasRibbon: product.hasRibbon,
+          brand: product.brand,
+          productType: product.productType,
+          quickAddType: product.quickAddType,
+          quickOption: {
+            _id: product.quickOption?._id,
+            name: product.quickOption?.name,
+            optionRenderType: product.quickOption?.optionRenderType,
+            choices: (product.quickOption?.choices ?? []).map((c) => ({
+              choiceId: c.choiceId,
+              name: c.name,
+              choiceType: c.choiceType,
+              colorCode: c.colorCode
+            }))
+          },
+          secondQuickOption: {
+            _id: product.secondQuickOption?._id,
+            name: product.secondQuickOption?.name,
+            optionRenderType: product.secondQuickOption?.optionRenderType,
+            choices: (product.secondQuickOption?.choices ?? []).map((c) => ({
+              choiceId: c.choiceId,
+              name: c.name,
+              choiceType: c.choiceType,
+              colorCode: c.colorCode
+            }))
+          }
+        }
+      },
+      carryForward: { product }
+    };
+  });
+}
+async function renderFastChanging(_props, carryForward, _wixStores) {
+  const Pipeline = RenderPipeline.for();
+  const { product } = carryForward;
+  return Pipeline.ok({
+    product: {
+      price: product.price,
+      strikethroughPrice: product.strikethroughPrice,
+      isAddingToCart: false,
+      quickOption: {
+        choices: (product.quickOption?.choices ?? []).map((c) => ({
+          choiceId: c.choiceId,
+          inStock: c.inStock,
+          isSelected: c.isSelected
+        }))
+      },
+      secondQuickOption: {
+        choices: (product.secondQuickOption?.choices ?? []).map((c) => ({
+          choiceId: c.choiceId,
+          inStock: c.inStock,
+          isSelected: c.isSelected
+        }))
+      }
+    }
+  }).toPhaseOutput((viewState) => {
+    return { viewState, carryForward: { product } };
+  });
+}
+const productSpotlight = 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;
@@ -1691,15 +1787,19 @@ const init = makeJayInit().withServer(async () => {
     enableClientSearch: true
   };
 });
-function flattenCategoryTree(roots, parentNames = [], parentSlugs = [], rootSlug = null) {
+function flattenCategoryTree(roots, parentNames = [], parentSlugs = [], rootSlug = null, rootName = null, rootHasChildren = null) {
   const entries = [];
   for (const node of roots) {
     const entryRootSlug = rootSlug ?? node.slug;
+    const entryRootName = rootName ?? node.name;
+    const entryRootHasChildren = rootHasChildren ?? node.children.length > 0;
     entries.push({
       node,
       breadcrumbNames: parentNames,
       breadcrumbSlugs: parentSlugs,
       rootSlug: entryRootSlug,
+      rootName: entryRootName,
+      rootHasChildren: entryRootHasChildren,
       parentSlug: parentSlugs.length > 0 ? parentSlugs[parentSlugs.length - 1] : null
     });
     if (node.children.length > 0) {
@@ -1708,7 +1808,9 @@ function flattenCategoryTree(roots, parentNames = [], parentSlugs = [], rootSlug
           node.children,
           [...parentNames, node.name],
           [...parentSlugs, node.slug],
-          entryRootSlug
+          entryRootSlug,
+          entryRootName,
+          entryRootHasChildren
         )
       );
     }
@@ -1794,12 +1896,12 @@ function buildCategoryPrompt(config, entry) {
     );
   }
   lines.push(
-    `  related-products — pass categorySlug="${node.slug}" alongside a productId when showing related items in this category`,
+    `  category-products — pass categorySlug="${node.slug}" to show products from this category; optionally pass productId to exclude a product`,
     "",
     "Contracts:",
     "  agent-kit/materialized-contracts/wix-stores/product-search.jay-contract",
     "  agent-kit/materialized-contracts/wix-stores/category-list.jay-contract",
-    "  agent-kit/materialized-contracts/wix-stores/related-products.jay-contract",
+    "  agent-kit/materialized-contracts/wix-stores/category-products.jay-contract",
     "",
     "Bind ViewState and refs per agent-kit/designer/INSTRUCTIONS.md."
   );
@@ -1811,6 +1913,12 @@ function buildCategoryPrompt(config, entry) {
   }
   return lines.join("\n");
 }
+function resolveCategorySubCategory(entry) {
+  if (entry.rootHasChildren) {
+    return entry.rootName;
+  }
+  return "Categories";
+}
 function buildCategoryAddMenuItems(roots, config) {
   const usedIds = /* @__PURE__ */ new Set();
   const entries = flattenCategoryTree(roots);
@@ -1818,7 +1926,7 @@ function buildCategoryAddMenuItems(roots, config) {
     id: uniqueCategoryItemId(entry.node.slug, entry.node._id, usedIds),
     title: formatCategoryTitle(entry),
     category: "Store",
-    subCategory: "Categories",
+    subCategory: resolveCategorySubCategory(entry),
     pluginName: "wix-stores",
     packageName: "@jay-framework/wix-stores",
     prompt: buildCategoryPrompt(config, entry)
@@ -2257,6 +2365,7 @@ export {
   cartIndicator,
   cartPage,
   categoryList,
+  categoryProducts,
   findCategoryImage,
   findRootCategoryId,
   findRootCategorySlug,
@@ -2268,10 +2377,10 @@ export {
   productPage,
   generator as productPageContractGenerator,
   productSearch,
+  productSpotlight,
   provideWixCartContext,
   provideWixCartService,
   provideWixStoresService,
-  relatedProducts,
   searchProducts,
   setupWixStores
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/wix-stores",
-  "version": "0.19.5",
+  "version": "0.19.7",
   "type": "module",
   "description": "Wix Stores API client for Jay Framework",
   "license": "Apache-2.0",
@@ -17,7 +17,8 @@
     "./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-products.jay-contract": "./dist/contracts/category-products.jay-contract",
+    "./product-spotlight.jay-contract": "./dist/contracts/product-spotlight.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",
@@ -38,16 +39,16 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@jay-framework/component": "^0.19.5",
-    "@jay-framework/fullstack-component": "^0.19.5",
-    "@jay-framework/reactive": "^0.19.5",
-    "@jay-framework/runtime": "^0.19.5",
-    "@jay-framework/secure": "^0.19.5",
-    "@jay-framework/stack-client-runtime": "^0.19.5",
-    "@jay-framework/stack-server-runtime": "^0.19.5",
-    "@jay-framework/wix-cart": "^0.19.5",
-    "@jay-framework/wix-server-client": "^0.19.5",
-    "@jay-framework/wix-utils": "^0.19.5",
+    "@jay-framework/component": "^0.19.7",
+    "@jay-framework/fullstack-component": "^0.19.7",
+    "@jay-framework/reactive": "^0.19.7",
+    "@jay-framework/runtime": "^0.19.7",
+    "@jay-framework/secure": "^0.19.7",
+    "@jay-framework/stack-client-runtime": "^0.19.7",
+    "@jay-framework/stack-server-runtime": "^0.19.7",
+    "@jay-framework/wix-cart": "^0.19.7",
+    "@jay-framework/wix-server-client": "^0.19.7",
+    "@jay-framework/wix-utils": "^0.19.7",
     "@wix/categories": "^1.0.185",
     "@wix/data-extension-schema": "^1.0.221",
     "@wix/sdk": "^1.21.5",
@@ -59,10 +60,10 @@
     "@babel/core": "^7.23.7",
     "@babel/preset-env": "^7.23.8",
     "@babel/preset-typescript": "^7.23.3",
-    "@jay-framework/compiler-jay-stack": "^0.19.5",
-    "@jay-framework/jay-cli": "^0.19.5",
-    "@jay-framework/jay-stack-cli": "^0.19.5",
-    "@jay-framework/vite-plugin": "^0.19.5",
+    "@jay-framework/compiler-jay-stack": "^0.19.7",
+    "@jay-framework/jay-cli": "^0.19.7",
+    "@jay-framework/jay-stack-cli": "^0.19.7",
+    "@jay-framework/vite-plugin": "^0.19.7",
     "nodemon": "^3.0.3",
     "rimraf": "^5.0.5",
     "tslib": "^2.6.2",

package/plugin.yaml

@@ -7,10 +7,14 @@ 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-products
+    contract: category-products.jay-contract
+    component: categoryProducts
+    description: Products from a category — use for showcases or as related products (exclude current product via productId)
+  - name: product-spotlight
+    contract: product-spotlight.jay-contract
+    component: productSpotlight
+    description: A single product card by product ID — use to feature a product on any page
   - name: category-list
     contract: category-list.jay-contract
     component: categoryList
@@ -22,6 +26,9 @@ dynamic_contracts:
   - prefix: 'product-page'
     component: productPage
     generator: productPageContractGenerator
+    headTags:
+      - title
+      - meta:description
 
 # Server actions (named exports from main module)
 actions:

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

@@ -1,31 +0,0 @@
-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

@@ -1,36 +0,0 @@
-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>