+ );
+}
+
+export const EventListening: Story = {
+ render: () => ,
+ tags: ['!autodocs', '!dev'],
+};
diff --git a/src/stories/components/Carousel/Code Examples - Events.mdx b/src/stories/components/Carousel/Code Examples - Events.mdx
new file mode 100644
index 0000000..084af6b
--- /dev/null
+++ b/src/stories/components/Carousel/Code Examples - Events.mdx
@@ -0,0 +1,79 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+import * as CarouselEventsStories from './CarouselEvents.stories';
+
+
+
+# `Carousel` - Scoped Event Listening
+
+Listen for navigation events on a `Carousel` instance by wrapping it in a container element, instead of listening on `window`.
+
+## Why scoped events?
+
+When multiple `Carousel` instances exist on the same page, listening on `window` means **every** listener fires for **every** carousel. Scoped events solve this: each carousel dispatches events on its own root DOM element with `bubbles: true`, so a listener attached to any ancestor element only receives events from carousels within that subtree.
+
+## Interactive Demo
+
+Click the previous/next arrows to see navigation events appear in the log panel below.
+
+
+
+## Basic Setup
+
+```tsx
+import { useRef, useEffect } from 'react';
+import CioCarousel from '@constructorio/ui-components/carousel';
+import { CIO_EVENTS } from '@constructorio/ui-components';
+
+function MyCarousel({ products }) {
+ const wrapperRef = useRef(null);
+
+ useEffect(() => {
+ const el = wrapperRef.current;
+ if (!el) return;
+
+ const handleNav = (e: Event) => {
+ const { direction, canScrollNext, canScrollPrev } = (e as CustomEvent).detail;
+ console.log(`Scrolled ${direction}`, { canScrollNext, canScrollPrev });
+ };
+
+ 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 (
+
+
+
+ );
+}
+```
+
+## Available Events
+
+Both events carry a `CarouselNavEventDetail` payload with the scroll direction and current scroll state.
+
+| 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';
+ canScrollNext: boolean;
+ canScrollPrev: boolean;
+}
+```
+
+## Notes
+
+- All events are dispatched with `bubbles: true`, so you can listen on any ancestor element instead of the carousel itself.
+- The `detail` payload includes the current scroll state (`canScrollNext`, `canScrollPrev`) so you can update UI accordingly.
+- Use `CIO_EVENTS` constants instead of raw strings to avoid typos and get autocomplete.
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(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 (
+
+
+
+ );
+}
+```
+
+## 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/ProductCardEvents.stories.tsx b/src/stories/components/ProductCard/ProductCardEvents.stories.tsx
new file mode 100644
index 0000000..12f1cf0
--- /dev/null
+++ b/src/stories/components/ProductCard/ProductCardEvents.stories.tsx
@@ -0,0 +1,91 @@
+import React, { useEffect, useRef, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import ProductCard from '../../../components/product-card';
+import { CIO_EVENTS } from '../../../utils/events';
+import { DEMO_IMAGE_URL } from '../../constants';
+
+const meta = {
+ title: 'Components/ProductCard',
+ component: ProductCard,
+ parameters: {
+ layout: 'centered',
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+function ProductCardEventListeningDemo() {
+ 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} — product: ${detail?.product?.name ?? 'N/A'}`,
+ ...prev.slice(0, 49),
+ ]);
+ };
+
+ const handlers = [
+ [CIO_EVENTS.productCard.click, logEvent('productCard.click')] as const,
+ [CIO_EVENTS.productCard.conversion, logEvent('productCard.conversion')] as const,
+ [CIO_EVENTS.productCard.imageEnter, logEvent('productCard.imageEnter')] as const,
+ [CIO_EVENTS.productCard.imageLeave, logEvent('productCard.imageLeave')] as const,
+ ];
+
+ handlers.forEach(([name, fn]) => el.addEventListener(name, fn));
+ return () => handlers.forEach(([name, fn]) => el.removeEventListener(name, fn));
+ }, []);
+
+ return (
+
+
+ {}}
+ />
+
+
+
Event Log
+ {eventLog.length === 0 ? (
+
Interact with the card above to see events...
+ ) : (
+ eventLog.map((entry, i) => (
+
+ {entry}
+
+ ))
+ )}
+
+
+ );
+}
+
+export const EventListening: Story = {
+ render: () => ,
+ tags: ['!autodocs', '!dev'],
+};
diff --git a/src/utils/events.ts b/src/utils/events.ts
index 353f4dc..b423efd 100644
--- a/src/utils/events.ts
+++ b/src/utils/events.ts
@@ -36,25 +36,29 @@ export interface CioEventDetailMap {
}
/**
- * Dispatches a typed CustomEvent on `window` for the given CIO event name.
+ * Dispatches a typed CustomEvent for the given CIO event name.
*
* This is the primary pub-sub mechanism for Constructor.io UI component events.
- * Consumers subscribe via `window.addEventListener(CIO_EVENTS.*.*, handler)`.
- * No-ops in SSR environments where `window` is undefined.
+ * When a `target` element is provided, the event is dispatched on that element
+ * and bubbles up the DOM tree. Consumers can listen on the component element or
+ * any ancestor. When no target is provided (or during SSR), falls back to
+ * dispatching on `window` for backwards compatibility.
*
* @param eventName - A key from {@link CioEventDetailMap} (use `CIO_EVENTS` constants).
* @param detail - The strongly-typed payload for the event.
+ * @param target - Optional DOM element to dispatch the event on. Falls back to `window`.
*/
export function dispatchCioEvent(
eventName: K,
detail: CioEventDetailMap[K],
+ target?: EventTarget | null,
): void {
if (typeof window === 'undefined') return;
const event = new CustomEvent(eventName, {
- bubbles: false,
+ bubbles: true, // lets consumers listen on any ancestor, not just the dispatching element.
cancelable: true,
detail,
});
- window.dispatchEvent(event);
+ (target || window).dispatchEvent(event);
}