/**
 * Service for creating and managing dialogs
 *
 * The {@link DialogRenderer} enables displaying web components in dialogs,
 * which can be modal or non-modal.
 *
 * Dialogs are useful for:
 * - User input forms
 * - Confirmation prompts
 * - Detail views
 * - Multi-step wizards
 *
 * The rendering implementation depends on the platform. Most commonly, dialogs
 * are rendered directly on the current page. On some platforms, dialogs may be
 * opened as separate native windows.
 *
 * @emits dialog.destroyed - When a dialog is externally destroyed (e.g., popup
 * window closed by user), a {@link DialogDestroyedEvent} is emitted via
 * {@link EventDispatcher}
 *
 * @example Create, update and close a dialog
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const dialogRenderer = platform.get(PlatformServiceName.Dialog);
 *
 * const dialogId = dialogRenderer.create('my-dialog-component', {
 *     title: 'Confirmation',
 *     message: 'Are you sure?',
 * });
 *
 * dialogRenderer.update(dialogId, { message: 'Processing...' });
 *
 * dialogRenderer.destroy(dialogId);
 * ```
 *
 * @public
 * @group Dialog
 */
export interface DialogRenderer {
    /**
     * Create and display a new dialog
     *
     * Creates a dialog containing the specified web component. The dialog can be
     * modal or non-modal depending on the component implementation. The rendering
     * approach depends on the platform - most commonly as an overlay on the current
     * page, but on some platforms as a separate native window.
     *
     * @param name - Tag name of the web component to render in the dialog (e.g., 'my-dialog-component')
     * @param properties - Props to pass to the dialog component. These will be set as properties on the component instance.
     * @param listeners - Event listeners to register on the dialog component. Keys are event names, values are handler functions.
     * @returns Unique identifier for the created dialog. Use this ID with {@link DialogRenderer.update} and {@link DialogRenderer.destroy}.
     *
     * @example Create a dialog with event listeners
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * class DeleteItemButton {
     *     private dialogId: number;
     *
     *     public openConfirmation(itemId: number) {
     *         const dialogRenderer = platform.get(PlatformServiceName.Dialog);
     *
     *         this.dialogId = dialogRenderer.create(
     *             'confirmation-dialog',
     *             { title: 'Delete Item', message: 'This cannot be undone' },
     *             {
     *                 confirm: () => this.deleteItem(itemId),
     *                 cancel: () => dialogRenderer.destroy(this.dialogId),
     *             }
     *         );
     *     }
     *
     *     private deleteItem(itemId: number) {
     *         const http = platform.get(PlatformServiceName.Http);
     *
     *         return http.delete(`items/${itemId}`);
     *     }
     * }
     * ```
     */
    create(name: string, properties?: DialogProperties, listeners?: DialogListeners): number;
    /**
     * Update an existing dialog's properties
     *
     * Updates the properties of a dialog that was previously created. This is
     * useful for updating dialog content based on user interactions or data changes.
     *
     * Event listeners cannot be updated and will remain as originally registered.
     *
     * @param id - The dialog identifier returned from {@link DialogRenderer.create}
     * @param properties - New property values to set on the dialog component
     *
     * @example Update the progress shown in a dialog
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const dialogRenderer = platform.get(PlatformServiceName.Dialog);
     *
     * const dialogId = dialogRenderer.create('progress-dialog', {
     *     progress: 0,
     *     status: 'Starting',
     * });
     *
     * function reportProgress(percent: number) {
     *     dialogRenderer.update(dialogId, {
     *         progress: percent,
     *         status: 'Processing',
     *     });
     * }
     *
     * reportProgress(50);
     * ```
     */
    update(id: number, properties?: DialogProperties): void;
    /**
     * Close and destroy a dialog
     *
     * Removes the dialog from the DOM and cleans up all associated resources
     * and event listeners. If the dialog was rendered as a popup window, the
     * window will be closed.
     *
     * @param id - The dialog identifier returned from {@link DialogRenderer.create}
     *
     * @example Close a dialog when the component goes away
     * ```ts
     * import {
     *     DialogRenderer,
     *     PlatformServiceName,
     * } from '@limetech/lime-web-components';
     *
     * // The id from `create` is the only handle on the dialog, so a component that
     * // has to close it later keeps the id around.
     * class TaskDetails {
     *     private dialogRenderer: DialogRenderer;
     *
     *     private dialogId: number;
     *
     *     public connectedCallback() {
     *         this.dialogRenderer = platform.get(PlatformServiceName.Dialog);
     *         this.dialogId = this.dialogRenderer.create('task-details-dialog');
     *     }
     *
     *     public disconnectedCallback() {
     *         this.dialogRenderer.destroy(this.dialogId);
     *     }
     * }
     * ```
     */
    destroy(id: number): void;
}
/**
 * Properties to pass to a dialog component
 *
 * An object mapping property names to values. These will be set as properties
 * on the dialog's web component instance when the dialog is created or updated.
 *
 * @example Pass properties to a dialog component
 * ```ts
 * import {
 *     DialogProperties,
 *     PlatformServiceName,
 * } from '@limetech/lime-web-components';
 *
 * const properties: DialogProperties = {
 *     userId: 123,
 *     mode: 'edit',
 *     allowDelete: true,
 *     fields: ['name', 'email', 'phone'],
 * };
 *
 * const dialogRenderer = platform.get(PlatformServiceName.Dialog);
 *
 * dialogRenderer.create('user-form-dialog', properties);
 * ```
 *
 * @public
 * @group Dialog
 */
export type DialogProperties = Record<string, unknown>;
/**
 * Event listeners for a dialog component
 *
 * An object mapping event names to handler functions. These listeners will be
 * registered on the dialog's web component instance when the dialog is created.
 *
 * @example Listen to events from a dialog component
 * ```ts
 * import {
 *     DialogListeners,
 *     DialogProperties,
 *     PlatformServiceName,
 *     createLogger,
 * } from '@limetech/lime-web-components';
 *
 * interface User {
 *     id: number;
 *     name: string;
 * }
 *
 * const logger = createLogger('my-component');
 *
 * const listeners: DialogListeners = {
 *     save: (event?: CustomEvent<User>) => {
 *         logger.info('User saved', { user: event?.detail });
 *     },
 *     cancel: () => {
 *         logger.info('Dialog cancelled');
 *     },
 *     delete: (event?: CustomEvent<number>) => {
 *         logger.info('Delete user', { userId: event?.detail });
 *     },
 * };
 *
 * const properties: DialogProperties = { mode: 'edit' };
 *
 * const dialogRenderer = platform.get(PlatformServiceName.Dialog);
 *
 * dialogRenderer.create('user-form-dialog', properties, listeners);
 * ```
 *
 * @public
 * @group Dialog
 */
export type DialogListeners = Record<string, (event?: CustomEvent<any>) => void>;
/**
 * Event emitted when a dialog is externally destroyed
 *
 * This event is dispatched via {@link EventDispatcher} when a dialog is closed
 * by external means, such as the user closing a popup window. The event detail
 * contains the dialog ID that was destroyed.
 *
 * This allows the component that created the dialog to clean up any references
 * or state associated with the dialog.
 *
 * @event dialog.destroyed
 *
 * @example React to a dialog being closed from outside
 * ```ts
 * import {
 *     DialogDestroyedEvent,
 *     PlatformServiceName,
 *     createLogger,
 * } from '@limetech/lime-web-components';
 *
 * const logger = createLogger('my-component');
 * const eventDispatcher = platform.get(PlatformServiceName.EventDispatcher);
 *
 * eventDispatcher.addListener(
 *     'dialog.destroyed',
 *     (event: DialogDestroyedEvent) => {
 *         logger.debug('Dialog was closed', { dialogId: event.detail });
 *     }
 * );
 * ```
 *
 * @public
 * @group Dialog
 */
export type DialogDestroyedEvent = CustomEvent<number>;