import { Icon } from '../core';
/**
 * Service for displaying different notification messages to users
 *
 * The Notifications service provides four types of user notifications:
 * - **alert**: Blocking dialog for important messages requiring acknowledgment
 * - **confirm**: Blocking dialog for yes/no decisions
 * - **notify**: Non-blocking toast-style notifications for feedback
 * - **report**: Persistent banner notifications for ongoing status
 *
 * All notification methods return promises, allowing you to handle user
 * interactions asynchronously in your Stencil components.
 *
 * ## Use Cases
 *
 * - **Alerts**: Critical errors, warnings, or information that blocks workflow
 * - **Confirms**: Deletion confirmations, unsaved changes warnings, destructive actions
 * - **Notifications**: Success messages, info updates, action feedback
 * - **Reports**: Connection status, background process updates, system messages
 *
 * @example Simple alert
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const notifications = platform.get(PlatformServiceName.Notification);
 *
 * await notifications.alert(
 *     'Error',
 *     'Failed to save changes. Please try again.',
 *     { icon: 'error' }
 * );
 * ```
 *
 * @example Confirm before deletion
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const notifications = platform.get(PlatformServiceName.Notification);
 * const repository = platform.get(PlatformServiceName.LimeObjectRepository);
 *
 * const confirmed = await notifications.confirm(
 *     'Delete Item',
 *     'Are you sure you want to delete this item? This action cannot be undone.',
 *     {
 *         acceptText: 'Delete',
 *         cancelText: 'Cancel',
 *         icon: { name: 'trash_can', color: 'rgb(var(--color-red-default))' },
 *     }
 * );
 *
 * if (confirmed && context.limetype && context.id) {
 *     await repository.deleteObject(context.limetype, context.id);
 *     await notifications.notify('Item deleted successfully');
 * }
 * ```
 *
 * @example Success notification with action
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const notifications = platform.get(PlatformServiceName.Notification);
 * const navigator = platform.get(PlatformServiceName.Navigator);
 *
 * const actionClicked = await notifications.notify('Form saved successfully', {
 *     actionText: 'View',
 *     timeout: 5000,
 *     dismissible: true,
 * });
 *
 * if (actionClicked && context.limetype && context.id) {
 *     navigator.navigate(`/${context.limetype}/${context.id}`);
 * }
 * ```
 *
 * @example Persistent status report
 * ```ts
 * import { PlatformServiceName } from '@limetech/lime-web-components';
 *
 * const notifications = platform.get(PlatformServiceName.Notification);
 * const http = platform.get(PlatformServiceName.Http);
 *
 * const actionClicked = await notifications.report(
 *     'Syncing data in the background...',
 *     {
 *         actionText: 'Cancel',
 *         icon: 'sync',
 *     }
 * );
 *
 * if (actionClicked) {
 *     await http.post('my_addon/sync/cancel');
 * }
 * ```
 *
 * @public
 * @group Notifications
 */
export interface Notifications {
    /**
     * Display a blocking alert dialog
     *
     * Shows a modal dialog that blocks user interaction until dismissed.
     * Use this for important messages that require user acknowledgment,
     * such as errors, warnings, or critical information.
     *
     * The dialog can be customized with an {@link Icon} and custom button text.
     * The promise resolves when the user dismisses the dialog.
     *
     * @param title - title of the dialog
     * @param message - message to display in the dialog
     * @param options - optional configuration for the alert appearance
     * @returns a promise that will be resolved when the dialog is closed
     *
     * @example Simple error alert
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const notifications = platform.get(PlatformServiceName.Notification);
     *
     * await notifications.alert('Error', 'Something went wrong');
     * ```
     *
     * @example Alert with custom icon and button
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const notifications = platform.get(PlatformServiceName.Notification);
     *
     * await notifications.alert(
     *     'Warning',
     *     'This action may have unintended consequences',
     *     {
     *         icon: {
     *             name: 'warning_shield',
     *             color: 'rgb(var(--color-orange-default))',
     *         },
     *         acceptText: 'I Understand',
     *     }
     * );
     * ```
     */
    alert(title: string, message: string, options?: AlertOptions): Promise<void>;
    /**
     * Display a blocking confirm dialog
     *
     * Shows a modal dialog with accept/cancel buttons for user decisions.
     * Use this before destructive actions, when saving changes, or any
     * time you need explicit user confirmation.
     *
     * The dialog can be customized with an {@link Icon} and custom button labels.
     * The promise resolves to true if the user accepts, false if they cancel.
     *
     * @param title - title of the dialog
     * @param message - message to display in the dialog
     * @param options - optional configuration for button labels and icon
     * @returns a promise that resolves to true if accepted, false if cancelled
     *
     * @example Delete confirmation
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const notifications = platform.get(PlatformServiceName.Notification);
     * const http = platform.get(PlatformServiceName.Http);
     *
     * const shouldDelete = await notifications.confirm(
     *     'Delete File',
     *     'Are you sure you want to delete this file?'
     * );
     *
     * if (shouldDelete) {
     *     await http.delete('my_addon/files/123');
     * }
     * ```
     *
     * @example Unsaved changes warning
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const notifications = platform.get(PlatformServiceName.Notification);
     * const navigator = platform.get(PlatformServiceName.Navigator);
     *
     * const shouldDiscard = await notifications.confirm(
     *     'Unsaved Changes',
     *     'You have unsaved changes. Do you want to discard them?',
     *     {
     *         acceptText: 'Discard',
     *         cancelText: 'Keep Editing',
     *         icon: 'warning_shield',
     *     }
     * );
     *
     * if (shouldDiscard) {
     *     navigator.navigate('/');
     * }
     * ```
     */
    confirm(title: string, message: string, options?: ConfirmOptions): Promise<boolean>;
    /**
     * Display a non-blocking notification
     *
     * Shows a toast-style notification that doesn't block user interaction.
     * Use this for success messages, informational updates, or action feedback.
     * Notifications auto-dismiss after a timeout or can be manually dismissed.
     *
     * You can optionally add an action button. The promise resolves to true
     * if the action button was clicked, false if the notification was dismissed
     * or timed out.
     *
     * @param message - message to display in the notification
     * @param options - optional configuration for timeout, action button, and appearance
     * @returns a promise that resolves to true if action clicked, false otherwise
     *
     * @example Simple success notification
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const notifications = platform.get(PlatformServiceName.Notification);
     *
     * await notifications.notify('Changes saved successfully');
     * ```
     *
     * @example Notification with action
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const notifications = platform.get(PlatformServiceName.Notification);
     * const http = platform.get(PlatformServiceName.Http);
     *
     * const undoClicked = await notifications.notify('Item deleted', {
     *     actionText: 'Undo',
     *     timeout: 5000,
     *     dismissible: true,
     * });
     *
     * if (undoClicked) {
     *     await http.post('my_addon/items/123/restore');
     * }
     * ```
     *
     * @example Long message notification
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const notifications = platform.get(PlatformServiceName.Notification);
     *
     * await notifications.notify(
     *     'Your export is ready. The file has been saved to your downloads folder.',
     *     { timeout: 8000 }
     * );
     * ```
     */
    notify(message: string, options?: NotificationOptions): Promise<boolean>;
    /**
     * Display a non-blocking and non-transient message
     *
     * Shows a persistent banner notification that remains visible until the user
     * dismisses it or clicks an action. Use this for ongoing status updates,
     * connection issues, or background processes.
     *
     * Unlike notify(), reports don't auto-dismiss and are more prominent.
     * The promise resolves to true if the action button was clicked,
     * false if the banner was manually dismissed.
     *
     * @param message - message to display in the banner
     * @param options - optional configuration for action button and icon
     * @returns a promise that resolves to true if action clicked, false otherwise
     *
     * @example Connection status
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const notifications = platform.get(PlatformServiceName.Notification);
     *
     * await notifications.report(
     *     'You are currently offline. Changes will sync when connection is restored.',
     *     { icon: 'sad_cloud' }
     * );
     * ```
     *
     * @example Background process with action
     * ```ts
     * import { PlatformServiceName } from '@limetech/lime-web-components';
     *
     * const notifications = platform.get(PlatformServiceName.Notification);
     * const http = platform.get(PlatformServiceName.Http);
     *
     * const cancelled = await notifications.report('Processing 1,234 items...', {
     *     actionText: 'Cancel',
     *     icon: 'hourglass',
     * });
     *
     * if (cancelled) {
     *     await http.post('my_addon/jobs/current/stop');
     * }
     * ```
     */
    report(message: string, options?: ReportOptions): Promise<boolean>;
}
/**
 * Options for alert dialogs
 *
 * Customize the appearance and button text of alert dialogs displayed
 * via {@link Notifications.alert}.
 *
 * @public
 * @group Notifications
 */
export interface AlertOptions {
    /**
     * Text to display on the acknowledgment button
     *
     * Defaults to "OK" if not specified.
     */
    acceptText?: string;
    /**
     * Icon to display in the dialog header
     *
     * Can be either a string icon name or an {@link Icon} object with
     * name and color properties. The icon provides visual context for
     * the alert type (error, warning, info, etc.).
     *
     * @example Icon name or Icon object
     * ```ts
     * import type { AlertOptions } from '@limetech/lime-web-components';
     *
     * const withIconName: AlertOptions = { icon: 'warning_shield' };
     *
     * const withIconObject: AlertOptions = {
     *     icon: { name: 'error', color: 'rgb(var(--color-red-default))' },
     * };
     * ```
     */
    icon?: string | Icon;
}
/**
 * Options for confirmation dialogs
 *
 * Customize the appearance and button labels of confirmation dialogs
 * displayed via {@link Notifications.confirm}.
 *
 * @public
 * @group Notifications
 */
export interface ConfirmOptions {
    /**
     * Text to display on the button for the accept action
     *
     * Use action-oriented text that clearly indicates what will happen
     * when clicked (e.g., "Delete", "Save", "Continue").
     */
    acceptText?: string;
    /**
     * Text to display on the button for the cancel action
     *
     * Use text that clearly indicates the action will be cancelled
     * (e.g., "Cancel", "Keep", "Go Back").
     */
    cancelText?: string;
    /**
     * Icon to display in the dialog header
     *
     * Can be either a string icon name or an {@link Icon} object with
     * name and color properties. Use icons that match the action's
     * severity (e.g., red for destructive actions).
     *
     * @example Icon name or Icon object
     * ```ts
     * import type { ConfirmOptions } from '@limetech/lime-web-components';
     *
     * const withIconName: ConfirmOptions = { icon: 'warning_shield' };
     *
     * const withIconObject: ConfirmOptions = {
     *     icon: { name: 'trash_can', color: 'rgb(var(--color-red-default))' },
     * };
     * ```
     */
    icon?: string | Icon;
}
/**
 * Options for toast notifications
 *
 * Customize the behavior and appearance of non-blocking notifications
 * displayed via {@link Notifications.notify}.
 *
 * @public
 * @group Notifications
 */
export interface NotificationOptions {
    /**
     * Number of milliseconds to wait before the notification auto-dismisses
     *
     * After this duration, the notification will automatically fade out.
     * If not specified, uses a default timeout. Set to a higher value
     * for longer messages that need more reading time, for example 8000
     * for eight seconds.
     */
    timeout?: number;
    /**
     * Text to display on the optional action button
     *
     * If provided, an action button will be shown. When clicked,
     * the notification's promise resolves to true. Use action buttons
     * for quick follow-up actions like "Undo", "View", or "Dismiss".
     */
    actionText?: string;
    /**
     * Set to true to display the message on multiple lines
     *
     * @deprecated Setting this property has no effect. The underlying
     * `limel-snackbar` ignores it and will remove it in a future major
     * version. Long messages already wrap, use {@link timeout} to give
     * readers more time.
     */
    multiline?: boolean;
    /**
     * Set to false to hide the close button
     *
     * By default the notification carries a close button, so users can
     * dismiss it before the timeout expires. Hide the button when an
     * {@link actionText} button is the only answer you want.
     *
     * @defaultValue true
     */
    dismissible?: boolean;
}
/**
 * Options for persistent report banners
 *
 * Customize the appearance and action button of persistent banner
 * notifications displayed via {@link Notifications.report}.
 *
 * @public
 * @group Notifications
 */
export interface ReportOptions {
    /**
     * Text to display on the optional action button
     *
     * If provided, an action button will be shown. When clicked,
     * the report's promise resolves to true. Use action buttons for
     * actions like "Retry", "Cancel", or "View Details".
     */
    actionText?: string;
    /**
     * Icon to display on the banner
     *
     * Use an icon name string to provide visual context for the
     * report's status, for example 'sync' for syncing or 'dashed_cloud'
     * for offline.
     */
    icon?: string;
}