/**
 * Service for application-wide event communication
 *
 * The {@link EventDispatcher} enables loosely-coupled communication between
 * components through a publish-subscribe pattern.
 *
 * Components can dispatch custom events and subscribe to events from other
 * components without direct coupling. This is particularly useful for:
 * - Cross-component communication
 * - Responding to platform-level events (navigation, data changes)
 * - Notifying other components of state changes
 *
 * @example Basic usage
 * ```ts
 * import {
 *     PlatformServiceName,
 *     createLogger,
 * } from '@limetech/lime-web-components';
 *
 * const logger = createLogger('my-component');
 * const eventDispatcher = platform.get(PlatformServiceName.EventDispatcher);
 *
 * const onDataChanged = (event: CustomEvent<{ id: number }>) => {
 *     logger.debug('Data changed', { id: event.detail.id });
 * };
 *
 * eventDispatcher.addListener('data-changed', onDataChanged);
 *
 * eventDispatcher.dispatch('data-changed', { id: 123 });
 *
 * // Remember to remove the listener in `disconnectedCallback()`
 * eventDispatcher.removeListener('data-changed', onDataChanged);
 * ```
 *
 * @public
 * @group Event dispatching
 */
export interface EventDispatcher {
    /**
     * Dispatch a custom event to all registered listeners
     *
     * Creates and dispatches a `CustomEvent` with the provided data. All components
     * that have registered listeners for this event name will be notified.
     *
     * @param eventName - Unique name identifying the event type
     * @param data - Data payload to include in the event's `detail` property
     * @returns The `CustomEvent` that was dispatched
     *
     * @example Dispatch an event
     * ```ts
     * import {
     *     PlatformServiceName,
     *     createLogger,
     * } from '@limetech/lime-web-components';
     *
     * const logger = createLogger('my-component');
     * const eventDispatcher = platform.get(PlatformServiceName.EventDispatcher);
     *
     * const event = eventDispatcher.dispatch('item-selected', {
     *     itemId: 42,
     *     name: 'Widget',
     * });
     *
     * // `dispatch` returns the event it created
     * logger.debug('Item selected', { itemId: event.detail.itemId });
     * ```
     */
    dispatch<T>(eventName: string, data: T): CustomEvent<T>;
    /**
     * Register a listener for a specific event type
     *
     * The listener function will be called whenever an event with the matching
     * name is dispatched. The same listener can be registered multiple times,
     * but should typically be registered only once per component instance.
     *
     * **Important:** Always remove listeners in `disconnectedCallback()` to
     * prevent memory leaks.
     *
     * @param eventName - Name of the event to listen for
     * @param listener - Callback function to invoke when the event is dispatched
     *
     * @example Listen for an event
     * ```ts
     * import {
     *     PlatformServiceName,
     *     createLogger,
     * } from '@limetech/lime-web-components';
     *
     * const logger = createLogger('my-component');
     * const eventDispatcher = platform.get(PlatformServiceName.EventDispatcher);
     *
     * eventDispatcher.addListener(
     *     'message-received',
     *     (event: CustomEvent<string>) => {
     *         logger.debug('Message received', { message: event.detail });
     *     }
     * );
     * ```
     */
    addListener<T>(eventName: string, listener: (event: CustomEvent<T>) => void): void;
    /**
     * Unregister a previously registered event listener
     *
     * Removes the specified listener function for the given event name. The
     * listener reference must be the same function instance that was passed
     * to {@link addListener}.
     *
     * Always call this in `disconnectedCallback()` to clean up listeners and
     * prevent memory leaks.
     *
     * @param eventName - Name of the event to stop listening for
     * @param listener - The exact listener function that was previously registered
     *
     * @example Remove a listener
     * ```ts
     * import {
     *     PlatformServiceName,
     *     createLogger,
     * } from '@limetech/lime-web-components';
     *
     * const logger = createLogger('my-component');
     * const eventDispatcher = platform.get(PlatformServiceName.EventDispatcher);
     *
     * const onMessageReceived = (event: CustomEvent<string>) => {
     *     logger.debug('Message received', { message: event.detail });
     * };
     *
     * eventDispatcher.addListener('message-received', onMessageReceived);
     *
     * // Only the exact same function reference is removed
     * eventDispatcher.removeListener('message-received', onMessageReceived);
     * ```
     */
    removeListener<T>(eventName: string, listener: (event: CustomEvent<T>) => void): void;
}