From 46a50f1299b513fe2bd0b876a367dfb3c34f184d Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Mon, 14 Jul 2025 13:14:24 +0300
Subject: [PATCH 01/17] initial improvements

---
 .../stores/src/react/Collection.tsx           | 123 +++++++++++-------
 1 file changed, 74 insertions(+), 49 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index b5cd7e982..b3f3d8085 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -7,33 +7,38 @@ import {
 } from "@wix/auto_sdk_stores_products-v-3";
 
 /**
- * Props for Grid headless component
+ * Props for the Grid headless component.
  */
 export interface GridProps {
-  /** Render prop function that receives product grid data */
+  /** Render prop function that receives product grid data from the collection. */
   children: (props: GridRenderProps) => React.ReactNode;
 }
 
 /**
- * Render props for Grid component
+ * Render props for the Grid component.
  */
 export interface GridRenderProps {
-  /** Array of products */
+  /** Array of products from the collection. Each product can have multiple variants based on different choices, such as color or size. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
   products: V3Product[];
-  /** Whether products are loading */
+  /** Whether the collection data is being fetched. */
   isLoading: boolean;
-  /** Error message if any */
+  /** Error message if loading fails. */
   error: string | null;
-  /** Whether there are no products */
+  /** Indicates if the collection is empty, meaning there are no products in the collection. */
   isEmpty: boolean;
-  /** Total number of products */
+  /** Total number of products in the collection. */
   totalProducts: number;
-  /** Whether collection has products */
+  /** Whether the collection contains any products. */
   hasProducts: boolean;
 }
 
 /**
- * Headless component for product grid
+ * <blockquote class="caution">
+ * Headless components are in Developer Preview and subject to change.
+ * </blockquote>
+ *
+ * Headless component for displaying products from a collection in a grid layout.
+ * Collections are themed groupings of products that store owners create to organize their catalog.
  *
  * @component
  */
@@ -85,42 +90,46 @@ export const Grid = (props: GridProps) => {
 };
 
 /**
- * Props for Item headless component
+ * Props for the Item headless component.
  */
 export interface ItemProps {
-  /** Product data */
+  /** Product data with all available variants and options. */
   product: V3Product;
   /** Render prop function that receives product item data */
   children: (props: ItemRenderProps) => React.ReactNode;
 }
 
 /**
- * Render props for Item component
+ * Render props for the Item component.
  */
 export interface ItemRenderProps {
-  /** Product ID */
+  /** Product ID. */
   id: string;
-  /** Product title */
+  /** Display name of the product. */
   title: string;
-  /** Product slug for URL */
+  /** URL-friendly product identifier */
   slug: string;
   /** Main product image URL */
   image: string | null;
-  /** Product price */
+  /** Formatted product price that reflects the current variant pricing. */
   price: string;
-  /** Compare at price (for strikethrough) */
+  /** Original price for comparison. Indicates a discount when available. */
   compareAtPrice: string | null;
-  /** Product description */
+  /** Product description. */
   description: string;
-  /** Whether product is available */
+  /** Whether the product is currently available for purchase. */
   available: boolean;
-  /** Product URL */
+  /** Direct link to the product page. */
   href: string;
 }
 
 /**
- * Headless component for individual product item
+ * <blockquote class="caution">
+ * Headless components are in Developer Preview and subject to change.
+ * </blockquote>
  *
+ * Headless component for displaying an individual product item.
+ * Handles product variants and provides ready-to-use product information for UI components.
  * @component
  */
 export const Item = (props: ItemProps) => {
@@ -159,33 +168,38 @@ export const Item = (props: ItemProps) => {
 };
 
 /**
- * Props for LoadMore headless component
+ * Props for the LoadMore headless component.
  */
 export interface LoadMoreProps {
-  /** Render prop function that receives load more data */
+  /** Render prop function that receives pagination and loading state data */
   children: (props: LoadMoreRenderProps) => React.ReactNode;
 }
 
 /**
- * Render props for LoadMore component
+ * Render props for the LoadMore component.
  */
 export interface LoadMoreRenderProps {
-  /** Function to load more products */
+  /** Function to load additional products from the collection */
   loadMore: () => Promise<void>;
-  /** Function to refresh products */
+  /** Function to refresh the entire collection */
   refresh: () => Promise<void>;
-  /** Whether load more is currently loading */
+  /** Whether additional products are being fetched */
   isLoading: boolean;
-  /** Whether there are products */
+  /** Whether the collection contains any products */
   hasProducts: boolean;
-  /** Total number of products currently loaded */
-  totalProducts: number;
-  /** Whether there are more products to load */
+  /** Number of products currently loaded from the collection */
+  loadedCount: number;
+  /** Whether there are more products available to load */
   hasMoreProducts: boolean;
 }
 
 /**
- * Headless component for load more products functionality
+ * <blockquote class="caution">
+ * Headless components are in Developer Preview and subject to change.
+ * </blockquote>
+ *
+ * Headless component for progressive loading of collection products.
+ * Enables loading additional products from the collection without traditional pagination.
  * Note: V3 API uses simplified loading without traditional pagination
  *
  * @component
@@ -236,27 +250,32 @@ export const LoadMore = (props: LoadMoreProps) => {
 };
 
 /**
- * Props for Header headless component
+ * Props for the Header headless component.
  */
 export interface HeaderProps {
-  /** Render prop function that receives collection header data */
+  /** Render prop function that receives collection summary data */
   children: (props: HeaderRenderProps) => React.ReactNode;
 }
 
 /**
- * Render props for Header component
+ * Render props for the Header component.
  */
 export interface HeaderRenderProps {
-  /** Total number of products */
+  /** Total number of products in the collection */
   totalProducts: number;
-  /** Whether collection is loading */
+  /** Whether the collection data is being fetched */
   isLoading: boolean;
-  /** Whether collection has products */
+  /** Whether the collection contains any products */
   hasProducts: boolean;
 }
 
 /**
- * Headless component for collection header with product count
+ * <blockquote class="caution">
+ * Headless components are in Developer Preview and subject to change.
+ * </blockquote>
+ *
+ * Headless component for displaying collection summary information such as product count.
+ * Useful for creating collection headers and navigation elements.
  *
  * @component
  */
@@ -296,30 +315,36 @@ export const Header = (props: HeaderProps) => {
 };
 
 /**
- * Props for Actions headless component
+ * Props for the Actions headless component.
  */
 export interface ActionsProps {
-  /** Render prop function that receives collection actions data */
+  /** Render prop function that receives collection action controls and state */
   children: (props: ActionsRenderProps) => React.ReactNode;
 }
 
 /**
- * Render props for Actions component
+ * Render props for the Actions component.
  */
 export interface ActionsRenderProps {
-  /** Function to refresh the collection */
+  /** Function to refresh the collection data */
   refresh: () => Promise<void>;
-  /** Function to load more products */
+  /** Function to load additional products from the collection */
   loadMore: () => Promise<void>;
-  /** Whether actions are loading */
+  /** Whether an action is being processed */
   isLoading: boolean;
-  /** Error message if any */
+  /** Error message if an action fails */
   error: string | null;
 }
 
 /**
- * Headless component for collection actions (refresh, load more)
- * Replaces traditional pagination for V3 API
+ * <blockquote class="caution">
+ * Headless components are in Developer Preview and subject to change.
+ * </blockquote>
+ *
+ * Headless component for performing actions on collections, such as refresh and load more.
+ * Collections are themed groupings of products that store owners create to organize their catalog
+ * (for example, Spring 2019, Running shoes, etc.). Products can belong to multiple collections.
+ * This component replaces traditional pagination for V3 API.
  *
  * @component
  */

From 8f822ed54d4870c64f40c466c465dd975e205fb8 Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Mon, 14 Jul 2025 15:04:42 +0300
Subject: [PATCH 02/17] docs improvements

---
 .../stores/src/react/Collection.tsx           | 48 +++++++++----------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index b3f3d8085..9cb3c95d2 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -10,15 +10,15 @@ import {
  * Props for the Grid headless component.
  */
 export interface GridProps {
-  /** Render prop function that receives product grid data from the collection. */
-  children: (props: GridRenderProps) => React.ReactNode;
+  /** Function that receives product grid data and loading states. Use this function to render your custom UI components with the provided data. */
+  children: (props: GridRenderProps) => JSX.Element;
 }
 
 /**
  * Render props for the Grid component.
  */
 export interface GridRenderProps {
-  /** Array of products from the collection. Each product can have multiple variants based on different choices, such as color or size. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
+  /** Array of products from the collection. Products can have multiple variants based on different choices, such as color or size. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
   products: V3Product[];
   /** Whether the collection data is being fetched. */
   isLoading: boolean;
@@ -95,7 +95,7 @@ export const Grid = (props: GridProps) => {
 export interface ItemProps {
   /** Product data with all available variants and options. */
   product: V3Product;
-  /** Render prop function that receives product item data */
+  /** Function that receives product item data. Use this function to render your custom UI components with the provided product information. */
   children: (props: ItemRenderProps) => React.ReactNode;
 }
 
@@ -107,17 +107,17 @@ export interface ItemRenderProps {
   id: string;
   /** Display name of the product. */
   title: string;
-  /** URL-friendly product identifier */
+  /** URL-friendly product identifier used in product page URLs. */
   slug: string;
-  /** Main product image URL */
+  /** Main product image URL. */
   image: string | null;
-  /** Formatted product price that reflects the current variant pricing. */
+  /** Formatted product price that reflects the variant pricing. */
   price: string;
   /** Original price for comparison. Indicates a discount when available. */
   compareAtPrice: string | null;
   /** Product description. */
   description: string;
-  /** Whether the product is currently available for purchase. */
+  /** Whether the product is available for purchase based on inventory status. */
   available: boolean;
   /** Direct link to the product page. */
   href: string;
@@ -171,7 +171,7 @@ export const Item = (props: ItemProps) => {
  * Props for the LoadMore headless component.
  */
 export interface LoadMoreProps {
-  /** Render prop function that receives pagination and loading state data */
+  /** Function that receives pagination and loading state data. Use this function to render your custom loading and pagination UI components. */
   children: (props: LoadMoreRenderProps) => React.ReactNode;
 }
 
@@ -179,17 +179,17 @@ export interface LoadMoreProps {
  * Render props for the LoadMore component.
  */
 export interface LoadMoreRenderProps {
-  /** Function to load additional products from the collection */
+  /** Function to load additional products from the collection. */
   loadMore: () => Promise<void>;
-  /** Function to refresh the entire collection */
+  /** Function to refresh the entire collection data. */
   refresh: () => Promise<void>;
-  /** Whether additional products are being fetched */
+  /** Whether additional products are being fetched. */
   isLoading: boolean;
-  /** Whether the collection contains any products */
+  /** Whether the collection contains any products. */
   hasProducts: boolean;
-  /** Number of products currently loaded from the collection */
+  /** Number of products loaded from the collection. */
   loadedCount: number;
-  /** Whether there are more products available to load */
+  /** Whether there are more products available to load. */
   hasMoreProducts: boolean;
 }
 
@@ -253,7 +253,7 @@ export const LoadMore = (props: LoadMoreProps) => {
  * Props for the Header headless component.
  */
 export interface HeaderProps {
-  /** Render prop function that receives collection summary data */
+  /** Function that receives collection summary data. Use this function to render your custom header UI components with collection information. */
   children: (props: HeaderRenderProps) => React.ReactNode;
 }
 
@@ -261,11 +261,11 @@ export interface HeaderProps {
  * Render props for the Header component.
  */
 export interface HeaderRenderProps {
-  /** Total number of products in the collection */
+  /** Total number of products in the collection. */
   totalProducts: number;
-  /** Whether the collection data is being fetched */
+  /** Whether the collection data is being fetched. */
   isLoading: boolean;
-  /** Whether the collection contains any products */
+  /** Whether the collection contains any products. */
   hasProducts: boolean;
 }
 
@@ -318,7 +318,7 @@ export const Header = (props: HeaderProps) => {
  * Props for the Actions headless component.
  */
 export interface ActionsProps {
-  /** Render prop function that receives collection action controls and state */
+  /** Function that receives collection action controls and state. Use this function to render your custom action UI components. */
   children: (props: ActionsRenderProps) => React.ReactNode;
 }
 
@@ -326,13 +326,13 @@ export interface ActionsProps {
  * Render props for the Actions component.
  */
 export interface ActionsRenderProps {
-  /** Function to refresh the collection data */
+  /** Function to refresh the collection data. */
   refresh: () => Promise<void>;
-  /** Function to load additional products from the collection */
+  /** Function to load additional products from the collection. */
   loadMore: () => Promise<void>;
-  /** Whether an action is being processed */
+  /** Whether an action is being processed. */
   isLoading: boolean;
-  /** Error message if an action fails */
+  /** Error message if an action fails. */
   error: string | null;
 }
 

From 5bda48aab460874ed6091be01e8807ff2f944898 Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Mon, 14 Jul 2025 15:09:16 +0300
Subject: [PATCH 03/17] refine description of collection

---
 packages/headless-components/stores/src/react/Collection.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index 9cb3c95d2..2600bcc18 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -39,6 +39,8 @@ export interface GridRenderProps {
  *
  * Headless component for displaying products from a collection in a grid layout.
  * Collections are themed groupings of products that store owners create to organize their catalog.
+ * For example, a store owner might create collections like "Spring 2019" or "Running shoes".
+ * Products can belong to multiple collections.
  *
  * @component
  */
@@ -342,8 +344,6 @@ export interface ActionsRenderProps {
  * </blockquote>
  *
  * Headless component for performing actions on collections, such as refresh and load more.
- * Collections are themed groupings of products that store owners create to organize their catalog
- * (for example, Spring 2019, Running shoes, etc.). Products can belong to multiple collections.
  * This component replaces traditional pagination for V3 API.
  *
  * @component

From dc7d840fd975edc3e9645f1896260d9919032a6e Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Mon, 14 Jul 2025 15:21:41 +0300
Subject: [PATCH 04/17] minor edits

---
 .../stores/src/react/Collection.tsx             | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index 2600bcc18..d9a53e262 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -18,13 +18,13 @@ export interface GridProps {
  * Render props for the Grid component.
  */
 export interface GridRenderProps {
-  /** Array of products from the collection. Products can have multiple variants based on different choices, such as color or size. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
+  /** Array of products from the collection. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
   products: V3Product[];
-  /** Whether the collection data is being fetched. */
+  /** Whether the collection data is loading. */
   isLoading: boolean;
   /** Error message if loading fails. */
   error: string | null;
-  /** Indicates if the collection is empty, meaning there are no products in the collection. */
+  /** Whether the collection is empty. */
   isEmpty: boolean;
   /** Total number of products in the collection. */
   totalProducts: number;
@@ -185,7 +185,7 @@ export interface LoadMoreRenderProps {
   loadMore: () => Promise<void>;
   /** Function to refresh the entire collection data. */
   refresh: () => Promise<void>;
-  /** Whether additional products are being fetched. */
+  /** Whether additional products are loading. */
   isLoading: boolean;
   /** Whether the collection contains any products. */
   hasProducts: boolean;
@@ -255,7 +255,7 @@ export const LoadMore = (props: LoadMoreProps) => {
  * Props for the Header headless component.
  */
 export interface HeaderProps {
-  /** Function that receives collection summary data. Use this function to render your custom header UI components with collection information. */
+  /** Function that receives collection metadata such as product count and loading state. Use this function to render your custom header UI components. */
   children: (props: HeaderRenderProps) => React.ReactNode;
 }
 
@@ -265,7 +265,7 @@ export interface HeaderProps {
 export interface HeaderRenderProps {
   /** Total number of products in the collection. */
   totalProducts: number;
-  /** Whether the collection data is being fetched. */
+  /** Whether the collection data is loading. */
   isLoading: boolean;
   /** Whether the collection contains any products. */
   hasProducts: boolean;
@@ -276,8 +276,7 @@ export interface HeaderRenderProps {
  * Headless components are in Developer Preview and subject to change.
  * </blockquote>
  *
- * Headless component for displaying collection summary information such as product count.
- * Useful for creating collection headers and navigation elements.
+ * Headless component for displaying collection metadata such as product count and loading state.
  *
  * @component
  */
@@ -332,7 +331,7 @@ export interface ActionsRenderProps {
   refresh: () => Promise<void>;
   /** Function to load additional products from the collection. */
   loadMore: () => Promise<void>;
-  /** Whether an action is being processed. */
+  /** Whether an action is loading. */
   isLoading: boolean;
   /** Error message if an action fails. */
   error: string | null;

From 4f527575aaf2cbef0f0c642dc2835e00ec34d944 Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Mon, 14 Jul 2025 15:40:18 +0300
Subject: [PATCH 05/17] add note

---
 .../stores/src/react/Collection.tsx                   | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index d9a53e262..bed88b261 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -42,6 +42,8 @@ export interface GridRenderProps {
  * For example, a store owner might create collections like "Spring 2019" or "Running shoes".
  * Products can belong to multiple collections.
  *
+ * > **Note:** This component is designed for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ *
  * @component
  */
 export const Grid = (props: GridProps) => {
@@ -132,6 +134,9 @@ export interface ItemRenderProps {
  *
  * Headless component for displaying an individual product item.
  * Handles product variants and provides ready-to-use product information for UI components.
+ *
+ * > **Note:** This component is designed for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ *
  * @component
  */
 export const Item = (props: ItemProps) => {
@@ -204,6 +209,8 @@ export interface LoadMoreRenderProps {
  * Enables loading additional products from the collection without traditional pagination.
  * Note: V3 API uses simplified loading without traditional pagination
  *
+ * > **Note:** This component is designed for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ *
  * @component
  */
 export const LoadMore = (props: LoadMoreProps) => {
@@ -278,6 +285,8 @@ export interface HeaderRenderProps {
  *
  * Headless component for displaying collection metadata such as product count and loading state.
  *
+ * > **Note:** This component is designed for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ *
  * @component
  */
 export const Header = (props: HeaderProps) => {
@@ -345,6 +354,8 @@ export interface ActionsRenderProps {
  * Headless component for performing actions on collections, such as refresh and load more.
  * This component replaces traditional pagination for V3 API.
  *
+ * > **Note:** This component is designed for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ *
  * @component
  */
 export const Actions = (props: ActionsProps) => {

From 246a64cc59d0e360ca688f35b0caafe68f141eb0 Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Mon, 14 Jul 2025 15:55:56 +0300
Subject: [PATCH 06/17] reword

---
 .../stores/src/react/Collection.tsx                    | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index bed88b261..eeb1d6734 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -42,7 +42,7 @@ export interface GridRenderProps {
  * For example, a store owner might create collections like "Spring 2019" or "Running shoes".
  * Products can belong to multiple collections.
  *
- * > **Note:** This component is designed for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
  * @component
  */
@@ -135,7 +135,7 @@ export interface ItemRenderProps {
  * Headless component for displaying an individual product item.
  * Handles product variants and provides ready-to-use product information for UI components.
  *
- * > **Note:** This component is designed for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
  * @component
  */
@@ -209,7 +209,7 @@ export interface LoadMoreRenderProps {
  * Enables loading additional products from the collection without traditional pagination.
  * Note: V3 API uses simplified loading without traditional pagination
  *
- * > **Note:** This component is designed for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
  * @component
  */
@@ -285,7 +285,7 @@ export interface HeaderRenderProps {
  *
  * Headless component for displaying collection metadata such as product count and loading state.
  *
- * > **Note:** This component is designed for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
  * @component
  */
@@ -354,7 +354,7 @@ export interface ActionsRenderProps {
  * Headless component for performing actions on collections, such as refresh and load more.
  * This component replaces traditional pagination for V3 API.
  *
- * > **Note:** This component is designed for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
  * @component
  */

From ba5e6ecc922dd2f2be2f09a139f0696142c86506 Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Mon, 14 Jul 2025 16:05:50 +0300
Subject: [PATCH 07/17] remove details about store collections

---
 .../stores/src/react/Collection.tsx            | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index eeb1d6734..97b4b6eb2 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -37,10 +37,8 @@ export interface GridRenderProps {
  * Headless components are in Developer Preview and subject to change.
  * </blockquote>
  *
- * Headless component for displaying products from a collection in a grid layout.
- * Collections are themed groupings of products that store owners create to organize their catalog.
- * For example, a store owner might create collections like "Spring 2019" or "Running shoes".
- * Products can belong to multiple collections.
+ * Headless component for displaying products in a grid layout.
+ * Handles the display of product collections with loading states and error handling.
  *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
@@ -186,15 +184,15 @@ export interface LoadMoreProps {
  * Render props for the LoadMore component.
  */
 export interface LoadMoreRenderProps {
-  /** Function to load additional products from the collection. */
+  /** Function to load additional products. */
   loadMore: () => Promise<void>;
-  /** Function to refresh the entire collection data. */
+  /** Function to refresh the collection data. */
   refresh: () => Promise<void>;
   /** Whether additional products are loading. */
   isLoading: boolean;
   /** Whether the collection contains any products. */
   hasProducts: boolean;
-  /** Number of products loaded from the collection. */
+  /** Number of products currently loaded. */
   loadedCount: number;
   /** Whether there are more products available to load. */
   hasMoreProducts: boolean;
@@ -205,8 +203,8 @@ export interface LoadMoreRenderProps {
  * Headless components are in Developer Preview and subject to change.
  * </blockquote>
  *
- * Headless component for progressive loading of collection products.
- * Enables loading additional products from the collection without traditional pagination.
+ * Headless component for progressive loading of products.
+ * Enables loading additional products without traditional pagination.
  * Note: V3 API uses simplified loading without traditional pagination
  *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
@@ -338,7 +336,7 @@ export interface ActionsProps {
 export interface ActionsRenderProps {
   /** Function to refresh the collection data. */
   refresh: () => Promise<void>;
-  /** Function to load additional products from the collection. */
+  /** Function to load additional products. */
   loadMore: () => Promise<void>;
   /** Whether an action is loading. */
   isLoading: boolean;

From ecfef375bceb6f682fc71f3c9a8bc83b6fed0599 Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Tue, 15 Jul 2025 13:49:45 +0300
Subject: [PATCH 08/17] add examples

---
 .../stores/src/react/Collection.tsx           | 93 +++++++++++++++++++
 1 file changed, 93 insertions(+)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index 97b4b6eb2..cf51127f8 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -42,6 +42,27 @@ export interface GridRenderProps {
  *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
+ * @example
+ * import { Grid } from "@wix/stores/components";
+ *
+ * <Grid>
+ *   {({ products, isLoading, error, isEmpty }) => (
+ *     <div className="product-grid">
+ *       {isLoading && <div>Loading products...</div>}
+ *       {error && <div>Error: {error}</div>}
+ *       {isEmpty && <div>No products found</div>}
+ *       <div className="grid">
+ *         {products.map(product => (
+ *           <div key={product._id} className="product-card">
+ *             <img src={product.media?.main?.image} alt={product.name} />
+ *             <h3>{product.name}</h3>
+ *           </div>
+ *         ))}
+ *       </div>
+ *     </div>
+ *   )}
+ * </Grid>
+ *
  * @component
  */
 export const Grid = (props: GridProps) => {
@@ -135,6 +156,31 @@ export interface ItemRenderProps {
  *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
+ * @example
+ * import { Item } from "@wix/stores/components";
+ *
+ * <Item product={product}>
+ *   {({ title, price, compareAtPrice, image, available, href }) => (
+ *     <div className="product-item">
+ *       {image && <img src={image} alt={title} />}
+ *       <h3>{title}</h3>
+ *       <div className="price">
+ *         <span className="current-price">{price}</span>
+ *         {compareAtPrice && (
+ *           <span className="compare-price">{compareAtPrice}</span>
+ *         )}
+ *       </div>
+ *       {available ? (
+ *         <a href={href} className="product-link">
+ *           View Product
+ *         </a>
+ *       ) : (
+ *         <span className="out-of-stock">Out of Stock</span>
+ *       )}
+ *     </div>
+ *   )}
+ * </Item>
+ *
  * @component
  */
 export const Item = (props: ItemProps) => {
@@ -209,6 +255,21 @@ export interface LoadMoreRenderProps {
  *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
+ * @example
+ * import { LoadMore } from "@wix/stores/components";
+ *
+ * <LoadMore>
+ *   {({ loadMore, isLoading, hasMoreProducts }) => (
+ *     <div className="load-more">
+ *       {hasMoreProducts && (
+ *         <button onClick={loadMore} disabled={isLoading}>
+ *           {isLoading ? 'Loading...' : 'Load More Products'}
+ *         </button>
+ *       )}
+ *     </div>
+ *   )}
+ * </LoadMore>
+ *
  * @component
  */
 export const LoadMore = (props: LoadMoreProps) => {
@@ -285,6 +346,21 @@ export interface HeaderRenderProps {
  *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
+ * @example
+ * import { Header } from "@wix/stores/components";
+ *
+ * <Header>
+ *   {({ totalProducts, isLoading }) => (
+ *     <div className="collection-header">
+ *       {isLoading ? (
+ *         <p>Loading...</p>
+ *       ) : (
+ *         <h2>{totalProducts} Products</h2>
+ *       )}
+ *     </div>
+ *   )}
+ * </Header>
+ *
  * @component
  */
 export const Header = (props: HeaderProps) => {
@@ -354,6 +430,23 @@ export interface ActionsRenderProps {
  *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
+ * @example
+ * import { Actions } from "@wix/stores/components";
+ *
+ * <Actions>
+ *   {({ refresh, loadMore, isLoading, error }) => (
+ *     <div className="collection-actions">
+ *       {error && <p>Error: {error}</p>}
+ *       <button onClick={refresh} disabled={isLoading}>
+ *         Refresh
+ *       </button>
+ *       <button onClick={loadMore} disabled={isLoading}>
+ *         Load More
+ *       </button>
+ *     </div>
+ *   )}
+ * </Actions>
+ *
  * @component
  */
 export const Actions = (props: ActionsProps) => {

From 2cd9b3d6fe8ba4954af4bb5773fdae6b18193464 Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Tue, 15 Jul 2025 14:20:03 +0300
Subject: [PATCH 09/17] standard dev preview note

---
 .../stores/src/react/Collection.tsx               | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index cf51127f8..eac9c7509 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -34,7 +34,8 @@ export interface GridRenderProps {
 
 /**
  * <blockquote class="caution">
- * Headless components are in Developer Preview and subject to change.
+ * **Developer Preview**
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
  * </blockquote>
  *
  * Headless component for displaying products in a grid layout.
@@ -148,7 +149,8 @@ export interface ItemRenderProps {
 
 /**
  * <blockquote class="caution">
- * Headless components are in Developer Preview and subject to change.
+ * **Developer Preview**
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
  * </blockquote>
  *
  * Headless component for displaying an individual product item.
@@ -246,7 +248,8 @@ export interface LoadMoreRenderProps {
 
 /**
  * <blockquote class="caution">
- * Headless components are in Developer Preview and subject to change.
+ * **Developer Preview**
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
  * </blockquote>
  *
  * Headless component for progressive loading of products.
@@ -339,7 +342,8 @@ export interface HeaderRenderProps {
 
 /**
  * <blockquote class="caution">
- * Headless components are in Developer Preview and subject to change.
+ * **Developer Preview**
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
  * </blockquote>
  *
  * Headless component for displaying collection metadata such as product count and loading state.
@@ -422,7 +426,8 @@ export interface ActionsRenderProps {
 
 /**
  * <blockquote class="caution">
- * Headless components are in Developer Preview and subject to change.
+ * **Developer Preview**
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
  * </blockquote>
  *
  * Headless component for performing actions on collections, such as refresh and load more.

From de72cc69cd11d6ae30da3115b4bc5a4875b8892d Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Tue, 15 Jul 2025 14:21:02 +0300
Subject: [PATCH 10/17] add standard line about what a headless component is

---
 .../stores/src/react/Collection.tsx                 | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index eac9c7509..ea6c5678b 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -38,8 +38,9 @@ export interface GridRenderProps {
  * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
  * </blockquote>
  *
- * Headless component for displaying products in a grid layout.
- * Handles the display of product collections with loading states and error handling.
+ * Headless component for displaying products in a grid layout. Handles the display of product collections with loading states and error handling.
+ *
+ * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
  *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
@@ -156,6 +157,8 @@ export interface ItemRenderProps {
  * Headless component for displaying an individual product item.
  * Handles product variants and provides ready-to-use product information for UI components.
  *
+ * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
  * @example
@@ -256,6 +259,8 @@ export interface LoadMoreRenderProps {
  * Enables loading additional products without traditional pagination.
  * Note: V3 API uses simplified loading without traditional pagination
  *
+ * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
  * @example
@@ -348,6 +353,8 @@ export interface HeaderRenderProps {
  *
  * Headless component for displaying collection metadata such as product count and loading state.
  *
+ * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
  * @example
@@ -433,6 +440,8 @@ export interface ActionsRenderProps {
  * Headless component for performing actions on collections, such as refresh and load more.
  * This component replaces traditional pagination for V3 API.
  *
+ * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ *
  * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  *
  * @example

From 021840736498ecf20537c33f6158897696a67d8d Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Tue, 15 Jul 2025 19:36:18 +0300
Subject: [PATCH 11/17] docs for category list comp

---
 .../stores/src/react/Category.tsx             | 49 ++++++++++++++++++-
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Category.tsx b/packages/headless-components/stores/src/react/Category.tsx
index 2cdb43ad1..91fdf1799 100644
--- a/packages/headless-components/stores/src/react/Category.tsx
+++ b/packages/headless-components/stores/src/react/Category.tsx
@@ -3,17 +3,62 @@ import { useService } from "@wix/services-manager-react";
 import React, { type ReactNode } from "react";
 import { CategoryServiceDefinition } from "../services/category-service.js";
 
-// Grid component for displaying filtered products
+/**
+ * Props for the List headless component.
+ */
 export interface CategoryListProps {
+  /** Function that receives category data and selection state. Use this function to render your custom category UI components with the provided category information. */
   children: (data: {
+    /** Array of available product categories. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
     categories: Category[];
+    /** ID of the currently selected category, or null if no category is selected. */
     selectedCategory: string | null;
+    /** Function to change the selected category. Pass null to show all products or a category ID to filter by that category. */
     setSelectedCategory: (categoryId: string | null) => void;
   }) => ReactNode;
 }
 
 /**
- * Headless component for displaying a list of categories
+ * <blockquote class="caution">
+ * **Developer Preview**
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ * </blockquote>
+ *
+ * Headless component for displaying and managing product categories.
+ * Provides category selection functionality with real-time state management for filtering products by category.
+ * Handles category data retrieval and maintains the current selection state.
+ *
+ * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ *
+ * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ *
+ * @example
+ * import { List } from "@wix/stores/components";
+ *
+ * <List>
+ *   {({ categories, selectedCategory, setSelectedCategory }) => (
+ *     <div className="category-filter">
+ *       <h3>Shop by Category</h3>
+ *       <div className="category-list">
+ *         <button
+ *           className={selectedCategory === null ? 'active' : ''}
+ *           onClick={() => setSelectedCategory(null)}
+ *         >
+ *           All Products
+ *         </button>
+ *         {categories.map(category => (
+ *           <button
+ *             key={category._id}
+ *             className={selectedCategory === category._id ? 'active' : ''}
+ *             onClick={() => setSelectedCategory(category._id)}
+ *           >
+ *             {category.name}
+ *           </button>
+ *         ))}
+ *       </div>
+ *     </div>
+ *   )}
+ * </List>
  *
  * @component
  */

From 8fe3a27bbc69db209fc0794655eea3338dd7489b Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Tue, 15 Jul 2025 19:39:04 +0300
Subject: [PATCH 12/17] add proper spacing for dev preview alert

---
 .../stores/src/react/Category.tsx                 |  3 +++
 .../stores/src/react/Collection.tsx               | 15 +++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/packages/headless-components/stores/src/react/Category.tsx b/packages/headless-components/stores/src/react/Category.tsx
index 91fdf1799..4239aa5ff 100644
--- a/packages/headless-components/stores/src/react/Category.tsx
+++ b/packages/headless-components/stores/src/react/Category.tsx
@@ -20,8 +20,11 @@ export interface CategoryListProps {
 
 /**
  * <blockquote class="caution">
+ *
  * **Developer Preview**
+ *
  * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
  * </blockquote>
  *
  * Headless component for displaying and managing product categories.
diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index ea6c5678b..5d2ab4919 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -34,8 +34,11 @@ export interface GridRenderProps {
 
 /**
  * <blockquote class="caution">
+ *
  * **Developer Preview**
+ *
  * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
  * </blockquote>
  *
  * Headless component for displaying products in a grid layout. Handles the display of product collections with loading states and error handling.
@@ -150,8 +153,11 @@ export interface ItemRenderProps {
 
 /**
  * <blockquote class="caution">
+ *
  * **Developer Preview**
+ *
  * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
  * </blockquote>
  *
  * Headless component for displaying an individual product item.
@@ -251,8 +257,11 @@ export interface LoadMoreRenderProps {
 
 /**
  * <blockquote class="caution">
+ *
  * **Developer Preview**
+ *
  * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
  * </blockquote>
  *
  * Headless component for progressive loading of products.
@@ -347,8 +356,11 @@ export interface HeaderRenderProps {
 
 /**
  * <blockquote class="caution">
+ *
  * **Developer Preview**
+ *
  * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
  * </blockquote>
  *
  * Headless component for displaying collection metadata such as product count and loading state.
@@ -433,8 +445,11 @@ export interface ActionsRenderProps {
 
 /**
  * <blockquote class="caution">
+ *
  * **Developer Preview**
+ *
  * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
  * </blockquote>
  *
  * Headless component for performing actions on collections, such as refresh and load more.

From 9a44616bfe8b79b6d710ab4f1e0d8f271129afa3 Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Tue, 15 Jul 2025 21:51:33 +0300
Subject: [PATCH 13/17] update note to notes

---
 .../stores/src/react/Category.tsx             |  6 ++--
 .../stores/src/react/Collection.tsx           | 30 +++++++++----------
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Category.tsx b/packages/headless-components/stores/src/react/Category.tsx
index 4239aa5ff..323fa6e0f 100644
--- a/packages/headless-components/stores/src/react/Category.tsx
+++ b/packages/headless-components/stores/src/react/Category.tsx
@@ -31,9 +31,9 @@ export interface CategoryListProps {
  * Provides category selection functionality with real-time state management for filtering products by category.
  * Handles category data retrieval and maintains the current selection state.
  *
- * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
- *
- * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
  *
  * @example
  * import { List } from "@wix/stores/components";
diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index 5d2ab4919..e903494e7 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -43,9 +43,9 @@ export interface GridRenderProps {
  *
  * Headless component for displaying products in a grid layout. Handles the display of product collections with loading states and error handling.
  *
- * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
- *
- * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
  *
  * @example
  * import { Grid } from "@wix/stores/components";
@@ -163,9 +163,9 @@ export interface ItemRenderProps {
  * Headless component for displaying an individual product item.
  * Handles product variants and provides ready-to-use product information for UI components.
  *
- * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
- *
- * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
  *
  * @example
  * import { Item } from "@wix/stores/components";
@@ -268,9 +268,9 @@ export interface LoadMoreRenderProps {
  * Enables loading additional products without traditional pagination.
  * Note: V3 API uses simplified loading without traditional pagination
  *
- * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
- *
- * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
  *
  * @example
  * import { LoadMore } from "@wix/stores/components";
@@ -365,9 +365,9 @@ export interface HeaderRenderProps {
  *
  * Headless component for displaying collection metadata such as product count and loading state.
  *
- * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
- *
- * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
  *
  * @example
  * import { Header } from "@wix/stores/components";
@@ -455,9 +455,9 @@ export interface ActionsRenderProps {
  * Headless component for performing actions on collections, such as refresh and load more.
  * This component replaces traditional pagination for V3 API.
  *
- * Headless components provide ready-to-use business logic and state management for common scenarios, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
- *
- * > **Note:** This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
  *
  * @example
  * import { Actions } from "@wix/stores/components";

From 0def6d40f65ef927ad24539089ba093b08e0b7e4 Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Tue, 15 Jul 2025 21:56:58 +0300
Subject: [PATCH 14/17] docs for filtered collection

---
 .../stores/src/react/FilteredCollection.tsx   | 250 +++++++++++++++++-
 1 file changed, 239 insertions(+), 11 deletions(-)

diff --git a/packages/headless-components/stores/src/react/FilteredCollection.tsx b/packages/headless-components/stores/src/react/FilteredCollection.tsx
index 501643940..93163e7dc 100644
--- a/packages/headless-components/stores/src/react/FilteredCollection.tsx
+++ b/packages/headless-components/stores/src/react/FilteredCollection.tsx
@@ -14,13 +14,47 @@ import {
 
 export type { AvailableOptions, Filter, FilterServiceAPI };
 
-// Filters Loading component with pulse animation
+/**
+ * Props for the FiltersLoading headless component.
+ */
 export interface FiltersLoadingProps {
-  children: (data: { isFullyLoaded: boolean }) => ReactNode;
+  /** Function that receives loading state data. Use this function to render your custom loading UI components while filters are being prepared. */
+  children: (data: {
+    /** Whether all filter options have been fully loaded and are ready to display. */
+    isFullyLoaded: boolean;
+  }) => ReactNode;
 }
 
 /**
- * Headless component for displaying a loading state for filters
+ * <blockquote class="caution">
+ *
+ * **Developer Preview**
+ *
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
+ * </blockquote>
+ *
+ * Headless component for displaying a loading state while filters are being prepared.
+ * Provides real-time loading state to show appropriate UI during filter initialization.
+ *
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ *
+ * @example
+ * import { FiltersLoading } from "@wix/stores/components";
+ *
+ * <FiltersLoading>
+ *   {({ isFullyLoaded }) => (
+ *     <div className="filters-loading">
+ *       {!isFullyLoaded && (
+ *         <div className="loading-spinner">
+ *           Loading filter options...
+ *         </div>
+ *       )}
+ *     </div>
+ *   )}
+ * </FiltersLoading>
  *
  * @component
  */
@@ -32,20 +66,67 @@ export const FiltersLoading: React.FC<FiltersLoadingProps> = ({ children }) => {
   return <>{children({ isFullyLoaded })}</>;
 };
 
-// Grid component for displaying filtered products
+/**
+ * Props for the Grid headless component.
+ */
 export interface FilteredGridProps {
+  /** Function that receives filtered product grid data and loading states. Use this function to render your custom UI components with the provided filtered product data. */
   children: (data: {
+    /** Array of filtered products from the collection. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
     products: V3Product[];
+    /** Total number of products matching the current filters. */
     totalProducts: number;
+    /** Whether the filtered collection data is loading. */
     isLoading: boolean;
+    /** Error message if loading fails. */
     error: string | null;
+    /** Whether the filtered collection is empty. */
     isEmpty: boolean;
+    /** Whether there are more filtered products available to load. */
     hasMoreProducts: boolean;
   }) => ReactNode;
 }
 
 /**
- * Headless component for displaying a grid of filtered products
+ * <blockquote class="caution">
+ *
+ * **Developer Preview**
+ *
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
+ * </blockquote>
+ *
+ * Headless component for displaying filtered products in a grid layout.
+ * Handles the display of product collections with applied filters, loading states and error handling.
+ * Automatically updates when filters are applied or removed.
+ *
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ *
+ * @example
+ * import { Grid } from "@wix/stores/components";
+ *
+ * <Grid>
+ *   {({ products, isLoading, error, isEmpty, totalProducts }) => (
+ *     <div className="filtered-product-grid">
+ *       {isLoading && <div>Loading filtered products...</div>}
+ *       {error && <div>Error: {error}</div>}
+ *       {isEmpty && <div>No products found matching your filters</div>}
+ *       <div className="grid-header">
+ *         <h2>{totalProducts} Products Found</h2>
+ *       </div>
+ *       <div className="grid">
+ *         {products.map(product => (
+ *           <div key={product._id} className="product-card">
+ *             <img src={product.media?.main?.image} alt={product.name} />
+ *             <h3>{product.name}</h3>
+ *           </div>
+ *         ))}
+ *       </div>
+ *     </div>
+ *   )}
+ * </Grid>
  *
  * @component
  */
@@ -73,23 +154,75 @@ export const Grid: React.FC<FilteredGridProps> = ({ children }) => {
   );
 };
 
-// Item component for individual product rendering
+/**
+ * Props for the Item headless component.
+ */
 export interface FilteredItemProps {
+  /** Product data with all available variants and options. */
   product: V3Product;
+  /** Function that receives filtered product item data. Use this function to render your custom UI components with the provided product information. */
   children: (data: {
+    /** Display name of the product. */
     title: string;
+    /** Main product image URL. */
     image: string | null;
+    /** Alternative text for the product image for accessibility. */
     imageAltText: string | null;
+    /** Formatted product price that reflects the variant pricing. */
     price: string;
+    /** Original price for comparison. Indicates a discount when available. */
     compareAtPrice: string | null;
+    /** Whether the product is available for purchase based on inventory status. */
     available: boolean;
+    /** URL-friendly product identifier used in product page URLs. */
     slug: string;
+    /** Product description. */
     description?: string;
   }) => ReactNode;
 }
 
 /**
- * Headless component for displaying a filtered product item
+ * <blockquote class="caution">
+ *
+ * **Developer Preview**
+ *
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
+ * </blockquote>
+ *
+ * Headless component for displaying an individual filtered product item.
+ * Handles product variants and provides ready-to-use product information for UI components.
+ * Works seamlessly with filtered collections to display products that match applied filters.
+ *
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ *
+ * @example
+ * import { Item } from "@wix/stores/components";
+ *
+ * <Item product={product}>
+ *   {({ title, price, compareAtPrice, image, available, slug, description }) => (
+ *     <div className="filtered-product-item">
+ *       {image && <img src={image} alt={title} />}
+ *       <h3>{title}</h3>
+ *       {description && <p className="description">{description}</p>}
+ *       <div className="price">
+ *         <span className="current-price">{price}</span>
+ *         {compareAtPrice && (
+ *           <span className="compare-price">{compareAtPrice}</span>
+ *         )}
+ *       </div>
+ *       {available ? (
+ *         <a href={`/store/products/${slug}`} className="product-link">
+ *           View Product
+ *         </a>
+ *       ) : (
+ *         <span className="out-of-stock">Out of Stock</span>
+ *       )}
+ *     </div>
+ *   )}
+ * </Item>
  *
  * @component
  */
@@ -137,20 +270,64 @@ export const Item: React.FC<FilteredItemProps> = ({ product, children }) => {
   );
 };
 
-// Load More component for pagination
+/**
+ * Props for the LoadMore headless component.
+ */
 export interface FilteredLoadMoreProps {
+  /** Function that receives pagination and loading state data for filtered products. Use this function to render your custom loading and pagination UI components. */
   children: (data: {
+    /** Function to load additional filtered products. */
     loadMore: () => Promise<void>;
+    /** Function to refresh the filtered collection data. */
     refresh: () => Promise<void>;
+    /** Whether additional filtered products are loading. */
     isLoading: boolean;
+    /** Whether the filtered collection contains any products. */
     hasProducts: boolean;
+    /** Total number of products matching the current filters. */
     totalProducts: number;
+    /** Whether there are more filtered products available to load. */
     hasMoreProducts: boolean;
   }) => ReactNode;
 }
 
 /**
- * Headless component for load more filtered products functionality
+ * <blockquote class="caution">
+ *
+ * **Developer Preview**
+ *
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
+ * </blockquote>
+ *
+ * Headless component for progressive loading of filtered products.
+ * Enables loading additional products that match the applied filters without traditional pagination.
+ * Automatically respects current filter settings when loading more products.
+ *
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ *
+ * @example
+ * import { LoadMore } from "@wix/stores/components";
+ *
+ * <LoadMore>
+ *   {({ loadMore, refresh, isLoading, hasMoreProducts, totalProducts }) => (
+ *     <div className="filtered-load-more">
+ *       <div className="results-info">
+ *         Showing filtered results ({totalProducts} total)
+ *       </div>
+ *       {hasMoreProducts && (
+ *         <button onClick={loadMore} disabled={isLoading}>
+ *           {isLoading ? 'Loading...' : 'Load More Filtered Products'}
+ *         </button>
+ *       )}
+ *       <button onClick={refresh} disabled={isLoading}>
+ *         Refresh Results
+ *       </button>
+ *     </div>
+ *   )}
+ * </LoadMore>
  *
  * @component
  */
@@ -178,20 +355,71 @@ export const LoadMore: React.FC<FilteredLoadMoreProps> = ({ children }) => {
   );
 };
 
-// Filters component for managing filters
+/**
+ * Props for the Filters headless component.
+ */
 export interface FilteredFiltersProps {
+  /** Function that receives filter management data and state. Use this function to render your custom filter UI components with the provided filter options and controls. */
   children: (data: {
+    /** Function to apply selected filters to the product collection. */
     applyFilters: (filters: Filter) => void;
+    /** Function to clear all applied filters and show all products. */
     clearFilters: () => void;
+    /** Currently applied filter settings including price ranges and selected options. */
     currentFilters: Filter;
+    /** Array of all products available for filtering. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
     allProducts: V3Product[];
+    /** Available filter options including price ranges and product attributes. */
     availableOptions: AvailableOptions;
+    /** Whether any filters are currently applied to the collection. */
     isFiltered: boolean;
   }) => ReactNode;
 }
 
 /**
- * Headless component for product filters with available options
+ * <blockquote class="caution">
+ *
+ * **Developer Preview**
+ *
+ * This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
+ *
+ * </blockquote>
+ *
+ * Headless component for managing product filters with available options.
+ * Provides comprehensive filter functionality including price ranges, product attributes, and custom options.
+ * Handles filter state management and automatically updates the product collection when filters are applied.
+ *
+ * > **Notes:**
+ * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
+ * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ *
+  * @example
+ * import { Filters } from "@wix/stores/components";
+ *
+ * <Filters>
+ *   {({ applyFilters, clearFilters, currentFilters, availableOptions, isFiltered }) => (
+ *     <div className="product-filters">
+ *       <h3>Filter Products</h3>
+ *       {isFiltered && (
+ *         <button onClick={clearFilters}>Clear All Filters</button>
+ *       )}
+ *
+ *       <div className="price-filter">
+ *         <label>Price: ${currentFilters.priceRange.min} - ${currentFilters.priceRange.max}</label>
+ *         <input
+ *           type="range"
+ *           min={availableOptions.priceRange.min}
+ *           max={availableOptions.priceRange.max}
+ *           value={currentFilters.priceRange.min}
+ *           onChange={(e) => applyFilters({
+ *             ...currentFilters,
+ *             priceRange: { ...currentFilters.priceRange, min: parseInt(e.target.value) }
+ *           })}
+ *         />
+ *       </div>
+ *     </div>
+ *   )}
+ * </Filters>
  *
  * @component
  */

From 4db35bf2acc5386e9e228f0bbd44274cec706ecc Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Tue, 15 Jul 2025 22:31:24 +0300
Subject: [PATCH 15/17] edits to desc with mention of render props

---
 .../stores/src/react/Category.tsx             |  7 ++--
 .../stores/src/react/Collection.tsx           | 29 +++++++--------
 .../stores/src/react/FilteredCollection.tsx   | 36 +++++++++----------
 3 files changed, 34 insertions(+), 38 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Category.tsx b/packages/headless-components/stores/src/react/Category.tsx
index 323fa6e0f..fc4ae5fcc 100644
--- a/packages/headless-components/stores/src/react/Category.tsx
+++ b/packages/headless-components/stores/src/react/Category.tsx
@@ -27,13 +27,12 @@ export interface CategoryListProps {
  *
  * </blockquote>
  *
- * Headless component for displaying and managing product categories.
- * Provides category selection functionality with real-time state management for filtering products by category.
- * Handles category data retrieval and maintains the current selection state.
+ * A headless component for displaying and managing product categories.
+ * Manages category data retrieval and maintains selection state for filtering products by category.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
  * @example
  * import { List } from "@wix/stores/components";
diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index e903494e7..a67c262d5 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -41,11 +41,12 @@ export interface GridRenderProps {
  *
  * </blockquote>
  *
- * Headless component for displaying products in a grid layout. Handles the display of product collections with loading states and error handling.
+ * A headless component for displaying products in a grid layout.
+ * Handles product collection display with loading states and error handling.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
  *
  * @example
  * import { Grid } from "@wix/stores/components";
@@ -160,12 +161,12 @@ export interface ItemRenderProps {
  *
  * </blockquote>
  *
- * Headless component for displaying an individual product item.
- * Handles product variants and provides ready-to-use product information for UI components.
+ * A headless component for displaying individual product items.
+ * Provides structured product details including pricing, availability, images, and navigation links.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
  * @example
  * import { Item } from "@wix/stores/components";
@@ -264,13 +265,12 @@ export interface LoadMoreRenderProps {
  *
  * </blockquote>
  *
- * Headless component for progressive loading of products.
- * Enables loading additional products without traditional pagination.
- * Note: V3 API uses simplified loading without traditional pagination
+ * A headless component that enables progressive loading of products.
+ * Loads additional products without traditional pagination for infinite scroll functionality.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
  * @example
  * import { LoadMore } from "@wix/stores/components";
@@ -363,11 +363,12 @@ export interface HeaderRenderProps {
  *
  * </blockquote>
  *
- * Headless component for displaying collection metadata such as product count and loading state.
+ * A headless component for displaying collection metadata.
+ * Provides product count and loading state information for use in collection headers.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
  * @example
  * import { Header } from "@wix/stores/components";
@@ -452,12 +453,12 @@ export interface ActionsRenderProps {
  *
  * </blockquote>
  *
- * Headless component for performing actions on collections, such as refresh and load more.
- * This component replaces traditional pagination for V3 API.
+ * A headless component that provides collection action controls.
+ * Manages refresh and load more functionality, and replaces the need for traditional pagination.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
  * @example
  * import { Actions } from "@wix/stores/components";
diff --git a/packages/headless-components/stores/src/react/FilteredCollection.tsx b/packages/headless-components/stores/src/react/FilteredCollection.tsx
index 93163e7dc..9105f2828 100644
--- a/packages/headless-components/stores/src/react/FilteredCollection.tsx
+++ b/packages/headless-components/stores/src/react/FilteredCollection.tsx
@@ -34,12 +34,12 @@ export interface FiltersLoadingProps {
  *
  * </blockquote>
  *
- * Headless component for displaying a loading state while filters are being prepared.
- * Provides real-time loading state to show appropriate UI during filter initialization.
+ * A headless component that provides filter initialization status.
+ * Tracks whether all filter options have been fully loaded and are ready for user interaction.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
  * @example
  * import { FiltersLoading } from "@wix/stores/components";
@@ -96,13 +96,12 @@ export interface FilteredGridProps {
  *
  * </blockquote>
  *
- * Headless component for displaying filtered products in a grid layout.
- * Handles the display of product collections with applied filters, loading states and error handling.
- * Automatically updates when filters are applied or removed.
+ * A headless component for displaying filtered products in a grid layout.
+ * Handles product collection display with applied filters and automatically updates when filters change.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
  * @example
  * import { Grid } from "@wix/stores/components";
@@ -190,13 +189,12 @@ export interface FilteredItemProps {
  *
  * </blockquote>
  *
- * Headless component for displaying an individual filtered product item.
- * Handles product variants and provides ready-to-use product information for UI components.
- * Works seamlessly with filtered collections to display products that match applied filters.
+ * A headless component for displaying individual filtered product items.
+ * Provides structured product details including pricing, availability, images, and navigation links for filtered results.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
  * @example
  * import { Item } from "@wix/stores/components";
@@ -300,13 +298,12 @@ export interface FilteredLoadMoreProps {
  *
  * </blockquote>
  *
- * Headless component for progressive loading of filtered products.
- * Enables loading additional products that match the applied filters without traditional pagination.
- * Automatically respects current filter settings when loading more products.
+ * A headless component that enables progressive loading of filtered products.
+ * Loads additional products that match applied filters without traditional pagination.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
  * @example
  * import { LoadMore } from "@wix/stores/components";
@@ -385,15 +382,14 @@ export interface FilteredFiltersProps {
  *
  * </blockquote>
  *
- * Headless component for managing product filters with available options.
- * Provides comprehensive filter functionality including price ranges, product attributes, and custom options.
- * Handles filter state management and automatically updates the product collection when filters are applied.
+ * A headless component for managing product filters with available options.
+ * Provides comprehensive filter functionality including price ranges, product attributes, and custom options, and automatically updates the product collection when filters are applied.
  *
  * > **Notes:**
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
- * > * Headless components provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
+ * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
-  * @example
+ * @example
  * import { Filters } from "@wix/stores/components";
  *
  * <Filters>

From e68640e36020301dcdfbd723077409db1dffda7d Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Tue, 15 Jul 2025 22:32:53 +0300
Subject: [PATCH 16/17] updates to product desc

---
 packages/headless-components/stores/src/react/Collection.tsx    | 2 +-
 .../headless-components/stores/src/react/FilteredCollection.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index a67c262d5..a094a3f84 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -18,7 +18,7 @@ export interface GridProps {
  * Render props for the Grid component.
  */
 export interface GridRenderProps {
-  /** Array of products from the collection. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
+  /** Array of products. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
   products: V3Product[];
   /** Whether the collection data is loading. */
   isLoading: boolean;
diff --git a/packages/headless-components/stores/src/react/FilteredCollection.tsx b/packages/headless-components/stores/src/react/FilteredCollection.tsx
index 9105f2828..e023b65aa 100644
--- a/packages/headless-components/stores/src/react/FilteredCollection.tsx
+++ b/packages/headless-components/stores/src/react/FilteredCollection.tsx
@@ -72,7 +72,7 @@ export const FiltersLoading: React.FC<FiltersLoadingProps> = ({ children }) => {
 export interface FilteredGridProps {
   /** Function that receives filtered product grid data and loading states. Use this function to render your custom UI components with the provided filtered product data. */
   children: (data: {
-    /** Array of filtered products from the collection. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
+    /** Array of filtered products. Learn about [managing products and categories](https://support.wix.com/en/managing-products-and-categories). */
     products: V3Product[];
     /** Total number of products matching the current filters. */
     totalProducts: number;

From b4eea0cb80ab2c21f2f35b446d3e8a517e468b38 Mon Sep 17 00:00:00 2001
From: daniellekorn <danielleko@wix.com>
Date: Thu, 17 Jul 2025 11:47:40 +0300
Subject: [PATCH 17/17] remove examples

---
 .../stores/src/react/Category.tsx             |  29 +----
 .../stores/src/react/Collection.tsx           | 102 ++-------------
 .../stores/src/react/FilteredCollection.tsx   | 119 +-----------------
 3 files changed, 13 insertions(+), 237 deletions(-)

diff --git a/packages/headless-components/stores/src/react/Category.tsx b/packages/headless-components/stores/src/react/Category.tsx
index fc4ae5fcc..c0acff313 100644
--- a/packages/headless-components/stores/src/react/Category.tsx
+++ b/packages/headless-components/stores/src/react/Category.tsx
@@ -34,34 +34,7 @@ export interface CategoryListProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
- * @example
- * import { List } from "@wix/stores/components";
- *
- * <List>
- *   {({ categories, selectedCategory, setSelectedCategory }) => (
- *     <div className="category-filter">
- *       <h3>Shop by Category</h3>
- *       <div className="category-list">
- *         <button
- *           className={selectedCategory === null ? 'active' : ''}
- *           onClick={() => setSelectedCategory(null)}
- *         >
- *           All Products
- *         </button>
- *         {categories.map(category => (
- *           <button
- *             key={category._id}
- *             className={selectedCategory === category._id ? 'active' : ''}
- *             onClick={() => setSelectedCategory(category._id)}
- *           >
- *             {category.name}
- *           </button>
- *         ))}
- *       </div>
- *     </div>
- *   )}
- * </List>
- *
+
  * @component
  */
 export const List: React.FC<CategoryListProps> = ({ children }) => {
diff --git a/packages/headless-components/stores/src/react/Collection.tsx b/packages/headless-components/stores/src/react/Collection.tsx
index a094a3f84..ec29d6b79 100644
--- a/packages/headless-components/stores/src/react/Collection.tsx
+++ b/packages/headless-components/stores/src/react/Collection.tsx
@@ -48,27 +48,7 @@ export interface GridRenderProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide ready-to-use business logic and state management, while giving you complete control over the UI, so you can build custom experiences faster without maintaining the underlying logic yourself.
  *
- * @example
- * import { Grid } from "@wix/stores/components";
- *
- * <Grid>
- *   {({ products, isLoading, error, isEmpty }) => (
- *     <div className="product-grid">
- *       {isLoading && <div>Loading products...</div>}
- *       {error && <div>Error: {error}</div>}
- *       {isEmpty && <div>No products found</div>}
- *       <div className="grid">
- *         {products.map(product => (
- *           <div key={product._id} className="product-card">
- *             <img src={product.media?.main?.image} alt={product.name} />
- *             <h3>{product.name}</h3>
- *           </div>
- *         ))}
- *       </div>
- *     </div>
- *   )}
- * </Grid>
- *
+
  * @component
  */
 export const Grid = (props: GridProps) => {
@@ -168,31 +148,7 @@ export interface ItemRenderProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
- * @example
- * import { Item } from "@wix/stores/components";
- *
- * <Item product={product}>
- *   {({ title, price, compareAtPrice, image, available, href }) => (
- *     <div className="product-item">
- *       {image && <img src={image} alt={title} />}
- *       <h3>{title}</h3>
- *       <div className="price">
- *         <span className="current-price">{price}</span>
- *         {compareAtPrice && (
- *           <span className="compare-price">{compareAtPrice}</span>
- *         )}
- *       </div>
- *       {available ? (
- *         <a href={href} className="product-link">
- *           View Product
- *         </a>
- *       ) : (
- *         <span className="out-of-stock">Out of Stock</span>
- *       )}
- *     </div>
- *   )}
- * </Item>
- *
+
  * @component
  */
 export const Item = (props: ItemProps) => {
@@ -250,8 +206,8 @@ export interface LoadMoreRenderProps {
   isLoading: boolean;
   /** Whether the collection contains any products. */
   hasProducts: boolean;
-  /** Number of products currently loaded. */
-  loadedCount: number;
+  /** Total number of products in the collection. */
+  totalProducts: number;
   /** Whether there are more products available to load. */
   hasMoreProducts: boolean;
 }
@@ -272,21 +228,7 @@ export interface LoadMoreRenderProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
- * @example
- * import { LoadMore } from "@wix/stores/components";
- *
- * <LoadMore>
- *   {({ loadMore, isLoading, hasMoreProducts }) => (
- *     <div className="load-more">
- *       {hasMoreProducts && (
- *         <button onClick={loadMore} disabled={isLoading}>
- *           {isLoading ? 'Loading...' : 'Load More Products'}
- *         </button>
- *       )}
- *     </div>
- *   )}
- * </LoadMore>
- *
+
  * @component
  */
 export const LoadMore = (props: LoadMoreProps) => {
@@ -370,21 +312,7 @@ export interface HeaderRenderProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
- * @example
- * import { Header } from "@wix/stores/components";
- *
- * <Header>
- *   {({ totalProducts, isLoading }) => (
- *     <div className="collection-header">
- *       {isLoading ? (
- *         <p>Loading...</p>
- *       ) : (
- *         <h2>{totalProducts} Products</h2>
- *       )}
- *     </div>
- *   )}
- * </Header>
- *
+
  * @component
  */
 export const Header = (props: HeaderProps) => {
@@ -460,23 +388,7 @@ export interface ActionsRenderProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
- * @example
- * import { Actions } from "@wix/stores/components";
- *
- * <Actions>
- *   {({ refresh, loadMore, isLoading, error }) => (
- *     <div className="collection-actions">
- *       {error && <p>Error: {error}</p>}
- *       <button onClick={refresh} disabled={isLoading}>
- *         Refresh
- *       </button>
- *       <button onClick={loadMore} disabled={isLoading}>
- *         Load More
- *       </button>
- *     </div>
- *   )}
- * </Actions>
- *
+
  * @component
  */
 export const Actions = (props: ActionsProps) => {
diff --git a/packages/headless-components/stores/src/react/FilteredCollection.tsx b/packages/headless-components/stores/src/react/FilteredCollection.tsx
index e023b65aa..87efa3254 100644
--- a/packages/headless-components/stores/src/react/FilteredCollection.tsx
+++ b/packages/headless-components/stores/src/react/FilteredCollection.tsx
@@ -41,21 +41,7 @@ export interface FiltersLoadingProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
- * @example
- * import { FiltersLoading } from "@wix/stores/components";
- *
- * <FiltersLoading>
- *   {({ isFullyLoaded }) => (
- *     <div className="filters-loading">
- *       {!isFullyLoaded && (
- *         <div className="loading-spinner">
- *           Loading filter options...
- *         </div>
- *       )}
- *     </div>
- *   )}
- * </FiltersLoading>
- *
+
  * @component
  */
 export const FiltersLoading: React.FC<FiltersLoadingProps> = ({ children }) => {
@@ -103,30 +89,7 @@ export interface FilteredGridProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
- * @example
- * import { Grid } from "@wix/stores/components";
- *
- * <Grid>
- *   {({ products, isLoading, error, isEmpty, totalProducts }) => (
- *     <div className="filtered-product-grid">
- *       {isLoading && <div>Loading filtered products...</div>}
- *       {error && <div>Error: {error}</div>}
- *       {isEmpty && <div>No products found matching your filters</div>}
- *       <div className="grid-header">
- *         <h2>{totalProducts} Products Found</h2>
- *       </div>
- *       <div className="grid">
- *         {products.map(product => (
- *           <div key={product._id} className="product-card">
- *             <img src={product.media?.main?.image} alt={product.name} />
- *             <h3>{product.name}</h3>
- *           </div>
- *         ))}
- *       </div>
- *     </div>
- *   )}
- * </Grid>
- *
+
  * @component
  */
 export const Grid: React.FC<FilteredGridProps> = ({ children }) => {
@@ -196,32 +159,7 @@ export interface FilteredItemProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
- * @example
- * import { Item } from "@wix/stores/components";
- *
- * <Item product={product}>
- *   {({ title, price, compareAtPrice, image, available, slug, description }) => (
- *     <div className="filtered-product-item">
- *       {image && <img src={image} alt={title} />}
- *       <h3>{title}</h3>
- *       {description && <p className="description">{description}</p>}
- *       <div className="price">
- *         <span className="current-price">{price}</span>
- *         {compareAtPrice && (
- *           <span className="compare-price">{compareAtPrice}</span>
- *         )}
- *       </div>
- *       {available ? (
- *         <a href={`/store/products/${slug}`} className="product-link">
- *           View Product
- *         </a>
- *       ) : (
- *         <span className="out-of-stock">Out of Stock</span>
- *       )}
- *     </div>
- *   )}
- * </Item>
- *
+
  * @component
  */
 export const Item: React.FC<FilteredItemProps> = ({ product, children }) => {
@@ -305,27 +243,7 @@ export interface FilteredLoadMoreProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
- * @example
- * import { LoadMore } from "@wix/stores/components";
- *
- * <LoadMore>
- *   {({ loadMore, refresh, isLoading, hasMoreProducts, totalProducts }) => (
- *     <div className="filtered-load-more">
- *       <div className="results-info">
- *         Showing filtered results ({totalProducts} total)
- *       </div>
- *       {hasMoreProducts && (
- *         <button onClick={loadMore} disabled={isLoading}>
- *           {isLoading ? 'Loading...' : 'Load More Filtered Products'}
- *         </button>
- *       )}
- *       <button onClick={refresh} disabled={isLoading}>
- *         Refresh Results
- *       </button>
- *     </div>
- *   )}
- * </LoadMore>
- *
+
  * @component
  */
 export const LoadMore: React.FC<FilteredLoadMoreProps> = ({ children }) => {
@@ -389,34 +307,7 @@ export interface FilteredFiltersProps {
  * > * This component is only relevant for [Wix Vibe](https://support.wix.com/en/article/wix-vibe-an-overview) and [Wix Headless](https://dev.wix.com/docs/go-headless/get-started/about-headless/about-wix-headless) developers.
  * > * Headless components use the render props pattern. They provide business logic and state management, while giving you full control over the UI so you can build custom experiences faster.
  *
- * @example
- * import { Filters } from "@wix/stores/components";
- *
- * <Filters>
- *   {({ applyFilters, clearFilters, currentFilters, availableOptions, isFiltered }) => (
- *     <div className="product-filters">
- *       <h3>Filter Products</h3>
- *       {isFiltered && (
- *         <button onClick={clearFilters}>Clear All Filters</button>
- *       )}
- *
- *       <div className="price-filter">
- *         <label>Price: ${currentFilters.priceRange.min} - ${currentFilters.priceRange.max}</label>
- *         <input
- *           type="range"
- *           min={availableOptions.priceRange.min}
- *           max={availableOptions.priceRange.max}
- *           value={currentFilters.priceRange.min}
- *           onChange={(e) => applyFilters({
- *             ...currentFilters,
- *             priceRange: { ...currentFilters.priceRange, min: parseInt(e.target.value) }
- *           })}
- *         />
- *       </div>
- *     </div>
- *   )}
- * </Filters>
- *
+
  * @component
  */
 export const Filters: React.FC<FilteredFiltersProps> = ({ children }) => {