+
= (props) => {
children,
} = props;
+ const handleAddToCartClick = useCallback(
+ (e: React.MouseEvent) => {
+ dispatchCioEvent(
+ CIO_EVENTS.productCard.conversion,
+ { product: renderProps.product },
+ e.currentTarget,
+ );
+ onAddToCart?.(e, renderProps.product);
+ },
+ [renderProps.product, onAddToCart],
+ );
+
return (
= (props) => {
props.className,
)}
conversionType='add_to_cart'
- onClick={onAddToCart}>
+ onClick={handleAddToCartClick}>
{addToCartText}
)}
@@ -350,6 +399,21 @@ function ProductCard({ componentOverrides, children, className, ...props }: Prod
...restProps
} = props;
+ const handleProductClick = useCallback(
+ (e: React.MouseEvent) => {
+ const target = e.target as HTMLElement;
+
+ // Do not fire if a conversion button (AddToCart / Wishlist) is clicked
+ if (target.closest('[data-cnstrc-btn]')) {
+ return;
+ }
+
+ dispatchCioEvent(CIO_EVENTS.productCard.click, { product }, e.currentTarget);
+ onProductClick?.(product);
+ },
+ [product, onProductClick],
+ );
+
const renderPropFn = typeof children === 'function' && children;
// Default layout when no children provided or render prop function
@@ -361,7 +425,7 @@ function ProductCard({ componentOverrides, children, className, ...props }: Prod
'cio-product-card min-w-[176px] max-w-[256px] h-full cursor-pointer border-0',
className,
)}
- onClick={onProductClick}
+ onClick={handleProductClick}
{...getProductCardDataAttributes(product)}
{...restProps}>
@@ -393,7 +457,7 @@ function ProductCard({ componentOverrides, children, className, ...props }: Prod
);
}
-// Create compound component with all sub-components attached
+// Attach compound components to ProductCard
ProductCard.ImageSection = ImageSection;
ProductCard.Badge = Badge;
ProductCard.WishlistButton = WishlistButton;
diff --git a/src/index.ts b/src/index.ts
index b310ab0..eeb0fe2 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -3,11 +3,16 @@ export { default as Button } from '@/components/button';
export { default as Badge } from '@/components/badge';
export { default as ProductCard } from '@/components/product-card';
export { default as Carousel } from '@/components/carousel';
-export { RenderPropsWrapper } from '@/utils';
+export { RenderPropsWrapper, CIO_EVENTS, dispatchCioEvent } from '@/utils';
// Hooks
// Types
+export type {
+ ProductCardEventDetail,
+ CarouselNavEventDetail,
+ CioEventDetailMap,
+} from '@/utils/events';
export type { ButtonVariants, ButtonOverrides, ButtonProps } from '@/components/button';
export type { BadgeVariants, BadgeOverrides, BadgeProps } from '@/components/badge';
export * from '@/types';
diff --git a/src/stories/components/Carousel/CarouselEvents.stories.tsx b/src/stories/components/Carousel/CarouselEvents.stories.tsx
new file mode 100644
index 0000000..32db193
--- /dev/null
+++ b/src/stories/components/Carousel/CarouselEvents.stories.tsx
@@ -0,0 +1,90 @@
+import React, { useEffect, useRef, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import CioCarousel from '../../../components/carousel';
+import { Product } from '../../../types/productCardTypes';
+import { CIO_EVENTS } from '../../../utils/events';
+import { DEMO_IMAGE_URL } from '../../constants';
+
+const meta = {
+ title: 'Components/Carousel',
+ component: CioCarousel,
+ parameters: {
+ layout: 'fullscreen',
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+const mockProducts: Product[] = Array.from({ length: 10 }, (_, i) => ({
+ id: `product-${i + 1}`,
+ name: `Product ${i + 1}`,
+ description: `This is a description for product ${i + 1}`,
+ imageUrl: DEMO_IMAGE_URL,
+ price: (Math.random() * 100 + 20).toFixed(2),
+ salePrice: Math.random() > 0.5 ? (Math.random() * 80 + 10).toFixed(2) : undefined,
+ rating: (Math.random() * 2 + 3).toFixed(1),
+ reviewsCount: Math.floor(Math.random() * 500 + 10),
+ tags: ['Tag 1', 'Tag 2'].slice(0, Math.floor(Math.random() * 3)),
+}));
+
+function CarouselEventListeningDemo() {
+ const wrapperRef = useRef(null);
+ const [eventLog, setEventLog] = useState([]);
+
+ useEffect(() => {
+ const el = wrapperRef.current;
+ if (!el) return;
+
+ const logEvent = (label: string) => (e: Event) => {
+ const detail = (e as CustomEvent).detail;
+ setEventLog((prev) => [
+ `[${new Date().toLocaleTimeString()}] ${label} — direction: ${detail?.direction}`,
+ ...prev.slice(0, 49),
+ ]);
+ };
+
+ const handlers = [
+ [CIO_EVENTS.carousel.next, logEvent('carousel.next')] as const,
+ [CIO_EVENTS.carousel.previous, logEvent('carousel.previous')] as const,
+ ];
+
+ handlers.forEach(([name, fn]) => el.addEventListener(name, fn));
+ return () => handlers.forEach(([name, fn]) => el.removeEventListener(name, fn));
+ }, []);
+
+ return (
+ (null);
+
+ useEffect(() => {
+ const el = wrapperRef.current;
+ if (!el) return;
+
+ const handleNav = (e: Event) => {
+ const { direction } = (e as CustomEvent).detail;
+ console.log(`Scrolled ${direction}`);
+ };
+
+ el.addEventListener(CIO_EVENTS.carousel.next, handleNav);
+ el.addEventListener(CIO_EVENTS.carousel.previous, handleNav);
+
+ return () => {
+ el.removeEventListener(CIO_EVENTS.carousel.next, handleNav);
+ el.removeEventListener(CIO_EVENTS.carousel.previous, handleNav);
+ };
+ }, []);
+
+ return (
+ (null);
+
+ useEffect(() => {
+ const el = wrapperRef.current;
+ if (!el) return;
+
+ const handleClick = (e: Event) => {
+ const { product } = (e as CustomEvent).detail;
+ console.log('Card clicked:', product.name);
+ };
+
+ el.addEventListener(CIO_EVENTS.productCard.click, handleClick);
+ return () => el.removeEventListener(CIO_EVENTS.productCard.click, handleClick);
+ }, []);
+
+ return (
+
@@ -90,7 +90,7 @@ function CompactListStyleCard(props) {
diff --git a/src/stories/components/ProductCard/ProductCard.stories.tsx b/src/stories/components/ProductCard/ProductCard.stories.tsx
index 5702fa3..f65c24b 100644
--- a/src/stories/components/ProductCard/ProductCard.stories.tsx
+++ b/src/stories/components/ProductCard/ProductCard.stories.tsx
@@ -1,7 +1,7 @@
import type { Meta, StoryObj } from '@storybook/react-vite';
import ProductCard from '../../../components/product-card';
import { CompleteCustomOverrideCard, CompactListStyleCard } from './ProductCardVariants';
-import { ProductCardProps } from '../../../types/productCardTypes';
+import { Product, ProductCardProps } from '../../../types/productCardTypes';
import { DEMO_IMAGE_URL } from '../../constants';
const meta = {
@@ -114,7 +114,7 @@ export const WithAddToCart: Story = {
imageUrl: DEMO_IMAGE_URL,
price: '299',
},
- onAddToCart: (e) => console.log('Added to cart', e),
+ onAddToCart: (e, product) => console.log('Added to cart', e, product),
},
argTypes: {
onAddToCart: { action: 'add to cart clicked' },
@@ -131,7 +131,7 @@ export const WithWishlist: Story = {
imageUrl: DEMO_IMAGE_URL,
price: '299',
},
- onAddToWishlist: (e) => console.log('Added to wishlist', e),
+ onAddToWishlist: (e, product) => console.log('Added to wishlist', e, product),
},
argTypes: {
onAddToWishlist: { action: 'add to wishlist clicked' },
@@ -162,7 +162,7 @@ export const CustomAddToCartText: Story = {
imageUrl: DEMO_IMAGE_URL,
price: '299',
},
- onAddToCart: (e) => console.log('Added to cart', e),
+ onAddToCart: (e, product) => console.log('Added to cart', e, product),
addToCartText: 'Buy Now',
},
argTypes: {
@@ -184,8 +184,8 @@ export const CustomCurrency: Story = {
reviewsCount: 89,
},
priceCurrency: '€',
- onAddToCart: (e) => console.log('Added to cart', e),
- onAddToWishlist: (e) => console.log('Added to wishlist', e),
+ onAddToCart: (e, product) => console.log('Added to cart', e, product),
+ onAddToWishlist: (e, product) => console.log('Added to wishlist', e, product),
},
argTypes: {
onAddToCart: { action: 'add to cart clicked' },
@@ -211,8 +211,8 @@ export const FullyFeatured: Story = {
badge: 'New',
},
priceCurrency: '$',
- onAddToCart: (e) => console.log('Added to cart', e),
- onAddToWishlist: (e) => console.log('Added to wishlist', e),
+ onAddToCart: (e, product) => console.log('Added to cart', e, product),
+ onAddToWishlist: (e, product) => console.log('Added to wishlist', e, product),
onProductClick: () => console.log('Product clicked'),
addToCartText: 'Add to Cart',
},
@@ -238,8 +238,8 @@ export const InWishlist: Story = {
},
priceCurrency: '$',
isInWishlist: true,
- onAddToWishlist: (e) => console.log('Removed from wishlist', e),
- onAddToCart: (e) => console.log('Added to cart', e),
+ onAddToWishlist: (e, product) => console.log('Removed from wishlist', e, product),
+ onAddToCart: (e, product) => console.log('Added to cart', e, product),
},
argTypes: {
onAddToCart: { action: 'add to cart clicked' },
@@ -278,8 +278,8 @@ export const CustomBadge: Story = {
reviewsCount: 2713,
},
priceCurrency: '$',
- onAddToCart: (e) => console.log('Added to cart', e),
- onAddToWishlist: (e) => console.log('Added to wishlist', e),
+ onAddToCart: (e, product) => console.log('Added to cart', e, product),
+ onAddToWishlist: (e, product) => console.log('Added to wishlist', e, product),
componentOverrides: {
image: {
badge: {
@@ -316,8 +316,8 @@ export const CustomBadgeCompound: Story = {
reviewsCount: 2713,
},
priceCurrency: '$',
- onAddToCart: (e) => console.log('Added to cart', e),
- onAddToWishlist: (e) => console.log('Added to wishlist', e),
+ onAddToCart: (e, product) => console.log('Added to cart', e, product),
+ onAddToWishlist: (e, product) => console.log('Added to wishlist', e, product),
},
render: (args) => (
+
+ );
+}
+
+export const EventListening: Story = {
+ render: () =>
+
+
+
+ Event Log
+ {eventLog.length === 0 ? (
+ Click the carousel arrows to see events...
+ ) : (
+ eventLog.map((entry, i) => (
+
+ {entry}
+
+ ))
+ )}
+
+
+ );
+}
+```
+
+## Available Events
+
+Both events carry a `CarouselNavEventDetail` payload with the scroll direction.
+
+| Event Name | Constant | Fires When |
+| ------------------------------------- | --------------------------------- | ---------------------- |
+| `cio.components.carousel.next` | `CIO_EVENTS.carousel.next` | Next button clicked |
+| `cio.components.carousel.previous` | `CIO_EVENTS.carousel.previous` | Previous button clicked|
+
+**Payload type:** `CarouselNavEventDetail`
+
+```ts
+interface CarouselNavEventDetail {
+ direction: 'next' | 'previous';
+}
+```
+
+## Notes
+
+- All events are dispatched with `bubbles: true`, so you can listen on any ancestor element instead of the carousel itself.
+- Use `CIO_EVENTS` constants instead of raw strings to avoid typos and get autocomplete.
diff --git a/src/stories/components/ProductCard/Code Examples - Component Overrides.mdx b/src/stories/components/ProductCard/Code Examples - Component Overrides.mdx
index ef3f17a..4a814ff 100644
--- a/src/stories/components/ProductCard/Code Examples - Component Overrides.mdx
+++ b/src/stories/components/ProductCard/Code Examples - Component Overrides.mdx
@@ -101,7 +101,7 @@ const addToCartButtonOverride = {
reactNode: (props) => (
@@ -144,7 +144,7 @@ const wishlistButtonOverride = {
reactNode: (props) => (
diff --git a/src/stories/components/ProductCard/Code Examples - Events.mdx b/src/stories/components/ProductCard/Code Examples - Events.mdx
new file mode 100644
index 0000000..3a04c45
--- /dev/null
+++ b/src/stories/components/ProductCard/Code Examples - Events.mdx
@@ -0,0 +1,74 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import * as ProductCardEventsStories from './ProductCardEvents.stories';
+
+
+
+# `ProductCard` - Scoped Event Listening
+
+Listen for user-interaction events on a `ProductCard` instance by wrapping it in a container element, instead of listening on `window`.
+
+## Why scoped events?
+
+When multiple `ProductCard` instances exist on the same page, listening on `window` means **every** listener fires for **every** card. Scoped events solve this: each card dispatches events on its own root DOM element with `bubbles: true`, so a listener attached to any ancestor element only receives events from cards within that subtree.
+
+## Interactive Demo
+
+Click the card, hover the image, or click "Add to Cart" to see events appear in the log panel below.
+
+
+
+## Basic Setup
+
+```tsx
+import { useRef, useEffect } from 'react';
+import ProductCard from '@constructorio/ui-components/product-card';
+import { CIO_EVENTS } from '@constructorio/ui-components';
+
+function MyProductCard({ product }) {
+ const wrapperRef = useRef
+
+ );
+}
+```
+
+## Available Events
+
+All events carry a `ProductCardEventDetail` payload containing the `product: Product` for the card that fired.
+
+| Event Name | Constant | Fires When |
+| --------------------------------------------- | ------------------------------------- | ------------------------- |
+| `cio.components.productCard.click` | `CIO_EVENTS.productCard.click` | Card is clicked |
+| `cio.components.productCard.conversion` | `CIO_EVENTS.productCard.conversion` | Add to Cart is clicked |
+| `cio.components.productCard.imageEnter` | `CIO_EVENTS.productCard.imageEnter` | Mouse enters card image |
+| `cio.components.productCard.imageLeave` | `CIO_EVENTS.productCard.imageLeave` | Mouse leaves card image |
+
+**Payload type:** `ProductCardEventDetail`
+
+```ts
+interface ProductCardEventDetail {
+ product: Product;
+}
+```
+
+## Notes
+
+- All events are dispatched with `bubbles: true`, so you can listen on any ancestor element instead of the card itself.
+- The `detail` payload always contains the `Product` object for the card that fired the event.
+- Use `CIO_EVENTS` constants instead of raw strings to avoid typos and get autocomplete.
diff --git a/src/stories/components/ProductCard/Code Examples - Render Props.mdx b/src/stories/components/ProductCard/Code Examples - Render Props.mdx
index 36fc7f9..59cfd3c 100644
--- a/src/stories/components/ProductCard/Code Examples - Render Props.mdx
+++ b/src/stories/components/ProductCard/Code Examples - Render Props.mdx
@@ -36,7 +36,7 @@ function CustomOverrideExample() {
{props.priceCurrency}{props.product.price}
-