Add comprehensive @example tags to all hooks

Author: Copilot

src/hooks/useDeepCompareEffect.ts

@@ -1,6 +1,47 @@
 import { useEffect, useRef, useMemo, type EffectCallback, type DependencyList } from "react"
 import { deepCompare } from "../utils/compare"
 
+/**
+ * Similar to useEffect but performs deep comparison of dependencies instead of shallow comparison.
+ * Useful when dependencies are objects or arrays that may be recreated on each render.
+ * 
+ * @example
+ * ```tsx
+ * import { useDeepCompareEffect } from '@nosto/nosto-react'
+ * 
+ * function MyComponent({ user }: { user: { id: string, preferences: string[] } }) {
+ *   useDeepCompareEffect(() => {
+ *     console.log('User preferences changed:', user.preferences)
+ *     // This will only run when user object actually changes,
+ *     // not when it's recreated with same values
+ *   }, [user])
+ * 
+ *   return <div>User: {user.id}</div>
+ * }
+ * ```
+ * 
+ * @example Comparing arrays and objects
+ * ```tsx
+ * import { useDeepCompareEffect } from '@nosto/nosto-react'
+ * 
+ * function ProductList({ filters, sortOptions }: { 
+ *   filters: { category: string, price: { min: number, max: number } }
+ *   sortOptions: string[]
+ * }) {
+ *   useDeepCompareEffect(() => {
+ *     // This effect will only run when filters or sortOptions actually change
+ *     fetchProducts(filters, sortOptions)
+ *   }, [filters, sortOptions])
+ * 
+ *   return <div>Product list</div>
+ * }
+ * ```
+ * 
+ * @param callback The effect callback function
+ * @param dependencies Array of dependencies to deep compare
+ * 
+ * @group Utilities
+ */
 export function useDeepCompareEffect(callback: EffectCallback, dependencies: DependencyList) {
   return useEffect(callback, useDeepCompareMemoize(dependencies))
 }

src/hooks/useLoadClientScript.ts

@@ -7,6 +7,59 @@ type NostoScriptProps = Pick<NostoProviderProps, "account" | "host" | "shopifyMa
 
 const defaultAttributes = { "nosto-client-script": "" }
 
+/**
+ * Hook for loading the Nosto client script and managing its load state.
+ * 
+ * @example
+ * ```tsx
+ * import { useLoadClientScript } from '@nosto/nosto-react'
+ * 
+ * function MyNostoProvider() {
+ *   const { clientScriptLoaded } = useLoadClientScript({
+ *     account: 'shopify-123456',
+ *     loadScript: true,
+ *     shopifyMarkets: {
+ *       marketId: 'US',
+ *       language: 'en'
+ *     }
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       {clientScriptLoaded ? (
+ *         <p>Nosto script loaded successfully</p>
+ *       ) : (
+ *         <p>Loading Nosto script...</p>
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Custom script loader
+ * ```tsx
+ * import { useLoadClientScript } from '@nosto/nosto-react'
+ * 
+ * function CustomNostoProvider() {
+ *   const customScriptLoader = (url: string) => {
+ *     const script = document.createElement('script')
+ *     script.src = url
+ *     script.async = true
+ *     document.head.appendChild(script)
+ *     return script
+ *   }
+ * 
+ *   const { clientScriptLoaded } = useLoadClientScript({
+ *     account: 'my-nosto-account',
+ *     scriptLoader: customScriptLoader
+ *   })
+ * 
+ *   return <div>Script loaded: {String(clientScriptLoaded)}</div>
+ * }
+ * ```
+ * 
+ * @group Essential Functions
+ */
 export function useLoadClientScript(props: NostoScriptProps) {
   const {
     scriptLoader = scriptLoaderFn,

src/hooks/useNosto404.tsx

@@ -7,7 +7,43 @@ import { useRenderCampaigns } from "./useRenderCampaigns"
 export type Nosto404Props = { placements?: string[] }
 
 /**
- * You can personalise your cart and checkout pages by using the `useNosto404` hook.
+ * You can personalise your 404 error pages by using the `useNosto404` hook.
+ *
+ * @example Basic 404 page usage
+ * ```tsx
+ * import { useNosto404 } from '@nosto/nosto-react'
+ * 
+ * function NotFoundPage() {
+ *   useNosto404({
+ *     placements: ['notfound-nosto-1', 'notfound-popular-products']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Page Not Found</h1>
+ *       <p>Sorry, the page you're looking for doesn't exist.</p>
+ *       <div id="notfound-popular-products" />
+ *       <div id="notfound-nosto-1" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example 404 page with default placements
+ * ```tsx
+ * import { useNosto404 } from '@nosto/nosto-react'
+ * 
+ * function Simple404Page() {
+ *   useNosto404() // Uses all available placements
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Oops! Page not found</h1>
+ *       <p>Let us help you find what you're looking for:</p>
+ *     </div>
+ *   )
+ * }
+ * ```
  *
  * @group Hooks
  */

src/hooks/useNostoApi.ts

@@ -4,6 +4,51 @@ import { useDeepCompareEffect } from "./useDeepCompareEffect"
 import { nostojs } from "@nosto/nosto-js"
 import { API } from "@nosto/nosto-js/client"
 
+/**
+ * Hook for executing code that requires access to the Nosto API.
+ * Waits for the client script to load before executing the callback.
+ * 
+ * @example
+ * ```tsx
+ * import { useNostoApi } from '@nosto/nosto-react'
+ * 
+ * function ProductRecommendations({ productId }: { productId: string }) {
+ *   useNostoApi(async (api) => {
+ *     const data = await api
+ *       .defaultSession()
+ *       .viewProduct(productId)
+ *       .setPlacements(['productpage-nosto-1', 'productpage-nosto-2'])
+ *       .load()
+ *     
+ *     console.log('Recommendations loaded:', data)
+ *   }, [productId])
+ * 
+ *   return <div>Product recommendations will appear here</div>
+ * }
+ * ```
+ * 
+ * @example Using deep comparison for complex dependencies
+ * ```tsx
+ * import { useNostoApi } from '@nosto/nosto-react'
+ * 
+ * function OrderThankYou({ order }: { order: Order }) {
+ *   useNostoApi(async (api) => {
+ *     await api
+ *       .defaultSession()
+ *       .addOrder(order)
+ *       .load()
+ *   }, [order], { deep: true })
+ * 
+ *   return <div>Thank you for your order!</div>
+ * }
+ * ```
+ * 
+ * @param cb Callback function that receives the Nosto API instance
+ * @param deps Optional dependency list for useEffect
+ * @param flags Optional flags, including `deep` for deep comparison of dependencies
+ * 
+ * @group Essential Functions
+ */
 export function useNostoApi(cb: (api: API) => void, deps?: DependencyList, flags?: { deep?: boolean }): void {
   const { clientScriptLoaded } = useNostoContext()
   const useEffectFn = flags?.deep ? useDeepCompareEffect : useEffect

src/hooks/useNostoCategory.tsx

@@ -12,6 +12,47 @@ export type NostoCategoryProps = {
 /**
  * You can personalise your category and collection pages by using the useNostoCategory hook.
  *
+ * @example Basic category page usage
+ * ```tsx
+ * import { useNostoCategory } from '@nosto/nosto-react'
+ * 
+ * function CategoryPage({ categoryName }: { categoryName: string }) {
+ *   useNostoCategory({
+ *     category: categoryName,
+ *     placements: ['categorypage-nosto-1', 'categorypage-nosto-2']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Category: {categoryName}</h1>
+ *       <div id="categorypage-nosto-1" />
+ *       <div id="categorypage-nosto-2" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Collection page with custom placements
+ * ```tsx
+ * import { useNostoCategory } from '@nosto/nosto-react'
+ * 
+ * function CollectionPage({ collection }: { collection: { name: string, id: string } }) {
+ *   useNostoCategory({
+ *     category: `collection-${collection.id}`,
+ *     placements: ['collection-banner', 'collection-recommendations']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>{collection.name} Collection</h1>
+ *       <div id="collection-banner" />
+ *       {/\* Product grid here *\/}
+ *       <div id="collection-recommendations" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoCategory({ category, placements }: NostoCategoryProps) {

src/hooks/useNostoCheckout.tsx

@@ -9,6 +9,46 @@ export type NostoCheckoutProps = { placements?: string[] }
 /**
  * You can personalise your cart and checkout pages by using the useNostoCheckout hook.
  *
+ * @example Basic cart page usage
+ * ```tsx
+ * import { useNostoCheckout } from '@nosto/nosto-react'
+ * 
+ * function CartPage() {
+ *   useNostoCheckout({
+ *     placements: ['cartpage-nosto-1', 'cartpage-cross-sell']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Your Cart</h1>
+ *       {/\* Cart items here *\/}
+ *       <div id="cartpage-cross-sell" />
+ *       <div id="cartpage-nosto-1" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Checkout page with recommendations
+ * ```tsx
+ * import { useNostoCheckout } from '@nosto/nosto-react'
+ * 
+ * function CheckoutPage() {
+ *   useNostoCheckout({
+ *     placements: ['checkout-upsell', 'checkout-last-chance']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Checkout</h1>
+ *       <div id="checkout-upsell" />
+ *       {/\* Checkout form here *\/}
+ *       <div id="checkout-last-chance" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoCheckout(props?: NostoCheckoutProps) {

src/hooks/useNostoContext.ts

@@ -4,6 +4,44 @@ import { NostoContext, NostoContextType } from "../context"
 /**
  * A hook that allows you to access the NostoContext and retrieve Nosto-related data from it in React components.
  *
+ * @example
+ * ```tsx
+ * import { useNostoContext } from '@nosto/nosto-react'
+ * 
+ * function NostoStatus() {
+ *   const { clientScriptLoaded, account, responseMode } = useNostoContext()
+ * 
+ *   return (
+ *     <div>
+ *       <p>Account: {account}</p>
+ *       <p>Script loaded: {String(clientScriptLoaded)}</p>
+ *       <p>Response mode: {responseMode}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Using context for conditional rendering
+ * ```tsx
+ * import { useNostoContext } from '@nosto/nosto-react'
+ * 
+ * function ConditionalRecommendations() {
+ *   const { clientScriptLoaded, recommendationComponent } = useNostoContext()
+ * 
+ *   if (!clientScriptLoaded) {
+ *     return <div>Loading recommendations...</div>
+ *   }
+ * 
+ *   return (
+ *     <div>
+ *       {recommendationComponent && (
+ *         <div id="nosto-recommendation-placeholder" />
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Essential Functions
  */
 export function useNostoContext(): NostoContextType {

src/hooks/useNostoHome.tsx

@@ -9,6 +9,43 @@ export type NostoHomeProps = { placements?: string[] }
 /**
  * You can personalise your home page by using the useNostoHome hook.
  *
+ * @example Basic home page usage
+ * ```tsx
+ * import { useNostoHome } from '@nosto/nosto-react'
+ * 
+ * function HomePage() {
+ *   useNostoHome({
+ *     placements: ['frontpage-nosto-1', 'frontpage-nosto-2', 'frontpage-hero']
+ *   })
+ * 
+ *   return (
+ *     <div>
+ *       <div id="frontpage-hero" />
+ *       <h1>Welcome to our store</h1>
+ *       <div id="frontpage-nosto-1" />
+ *       <div id="frontpage-nosto-2" />
+ *     </div>
+ *   )
+ * }
+ * ```
+ * 
+ * @example Home page with default placements
+ * ```tsx
+ * import { useNostoHome } from '@nosto/nosto-react'
+ * 
+ * function SimpleHomePage() {
+ *   // Uses all available placements configured in Nosto admin
+ *   useNostoHome()
+ * 
+ *   return (
+ *     <div>
+ *       <h1>Home Page</h1>
+ *       {/\* Nosto will inject content into configured placements *\/}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @group Hooks
  */
 export function useNostoHome(props?: NostoHomeProps) {