[Feat]: Enhanced Event System with Context and Cancellable Events

[davidjerleke]

Which variants of Embla Carousel are relevant to this feature request?

• embla-carousel (Core)
• embla-carousel-react
• embla-carousel-vue
• embla-carousel-svelte
• embla-carousel-autoplay
• embla-carousel-auto-scroll
• embla-carousel-solid
• embla-carousel-auto-height
• embla-carousel-class-names
• embla-carousel-fade
• embla-carousel-docs (Documentation)
• embla-carousel-docs (Generator)

Feature description

Introduce a more powerful event system for Embla Carousel that provides rich event context and allows event cancellation through return values.

Key Features:

1. Rich Event Context
Events now include detailed context information through a structured event model:

type EmblaEventModelType<EventType> = {
  api: EmblaCarouselType
  type: EmblaEventType
  detail: EmblaEventListType[EventType]
}

2. Cancellable Events
Event listeners can prevent default behavior by returning false:

emblaApi.on('resize', (event) => {
  // Custom resize handling
  if (shouldPreventDefault) {
    return false // Prevents core resize logic
  }
})

3. Event-Specific Details
Each event type provides relevant context data:

• resize: ResizeObserverEntry[]
• slidefocus: FocusEvent
• select: SelectEventType with scroll information
• scroll: ScrollEventType with position data
• And more...

Benefits:

• Plugin Architecture: Plugins can intercept and customize core behaviors
• Better Debugging: Rich context helps understand what triggered events
• Enhanced Control: Developers can prevent or modify default behaviors
• Type Safety: Full TypeScript support with event-specific typing
• Backwards Compatible: Existing event listeners continue to work

This enables powerful customisations like custom resize handling, advanced focus management, and sophisticated plugin development while maintaining the simplicity of the existing API.

Additional Context

This enhancement builds upon the existing event system to provide:

1. Event Interception: Plugins and user code can intercept events before core logic executes
2. Prevention Mechanism: Returning false from event handlers prevents default behavior
3. Execution Order: Plugin listeners execute before core handlers, allowing override of default behaviors
4. Rich Data: Events carry comprehensive context about what triggered them

Example Use Cases:

• AutoHeight plugin preventing default resize behavior when handling slide height changes
• Custom focus management that overrides default scroll-to-focused-slide behavior
• Advanced scroll optimization that replaces core scroll handling
• Debug plugins that log detailed event information

Before submitting

• I've made research efforts and searched the documentation
• I've searched for existing issues
• I agree to follow this project's Contributing Guidelines for feature requests

[davidjerleke]

Implemented in d7f875a.