bromcom-ui-next 0.1.29 → 0.1.31

package/dist/types/components/pop-confirm/pop-confirm.component.d.ts

@@ -1,195 +1,315 @@
-import { EventEmitter, ComponentInterface } from '../../stencil-public-runtime';
-import { type Placement } from '@floating-ui/dom';
+import { EventEmitter } from '../../stencil-public-runtime';
+export type PopConfirmPlacement = 'top' | 'right' | 'bottom' | 'left';
+export type PopConfirmSize = 'small' | 'medium' | 'large';
+export type PopConfirmStatus = 'info' | 'success' | 'warning' | 'error';
 /**
  * @component BcmPopConfirm
- * @description A floating confirmation pop-up component that prompts users for action confirmation, triggered by click or hover events.
- * Offers customizable header, body content, and footer areas through slots, with accessibility and positioning features.
- *
- * @example Basic usage
- * <bcm-pop-confirm target-id="trigger-btn" placement="right" header-text="Confirm Action" description="Are you sure?" confirm-text="Yes" cancel-text="No" status="warning"></bcm-pop-confirm>
- *
- * @example With all slots and custom styling
- * <bcm-pop-confirm target-id="trigger-btn" placement="left" header-text="Delete Item" description="Are you sure you want to delete this item?" confirm-text="Delete" cancel-text="Cancel" status="error" arrow-color="#ffffff">
- *   <span slot="header">Custom Header Text</span>
- *   <span slot="body">Additional details here</span>
- *   <span slot="footer">Custom Footer Action</span>
- * </bcm-pop-confirm>
- *
- * @example Event handling
- * // Listen to confirmation events
- * const popConfirm = document.querySelector('bcm-pop-confirm');
- * popConfirm.addEventListener('bcmConfirm', () => {
- *   console.log('User confirmed the action!');
- * });
- * popConfirm.addEventListener('bcmCancel', () => {
- *   console.log('User canceled the action!');
- * });
- *
- * // Programmatically control pop-up
- * await popConfirm.show(); // Show the pop-up
- * await popConfirm.hide(); // Hide the pop-up
- *
- * @prop {string} arrowColor - The color of the arrow pointing to the trigger element (default: 'var(--bcm-ui-color-background-basic-panel)')
- * @prop {string} cancelText - Text displayed on the cancel button (default: 'Cancel')
- * @prop {string} confirmText - Text displayed on the confirm button (default: 'Yes')
- * @prop {string} description - The description or body content of the pop-up (default: '')
- * @prop {string} headerText - The header text displayed at the top of the pop-up (default: '')
- * @prop {Placement} placement - The placement position of the pop-up relative to the trigger (default: 'right')
- * @prop {('small' | 'medium' | 'large')} size - The size of the pop-up, determining its dimensions (default: 'medium')
- * @prop {('info' | 'error' | 'warning' | 'success' | 'default')} status - The status of the pop-up, affecting its icon and color (default: 'info')
- * @prop {boolean} statusIcon - Whether to display a status icon based on the `status` prop (default: true)
- * @prop {string} targetId - The ID of the trigger element (e.g., a button) that opens the pop-up
- *
- * @slot header - Custom content for the header area (optional)
- * @slot body - Custom content for the main body area (optional, falls back to `description`)
- * @slot footer - Custom content for the footer area (optional)
- *
- * @event {EventEmitter<void>} bcmConfirm - Emitted when the user confirms the action in the pop-up
- * @event {EventEmitter<void>} bcmCancel - Emitted when the user cancels the action in the pop-up
- *
- * @csspart container - The root container element of the pop-up
- * @csspart header - The header section with title and close icon
- * @csspart content - The main content section of the pop-up
- * @csspart footer - The footer section with confirm/cancel buttons
- * @csspart arrow - The positioning arrow pointing to the trigger
- *
- * @css {string} --popover-radius - Border radius of the pop-up (default: defined in CSS)
- * @css {string} --popover-bg - Background color of the pop-up
- * @css {string} --text-color - Text color of the pop-up based on status
- *
- * @methods
- * show() - Programmatically shows the pop-up
- * hide() - Programmatically hides the pop-up
+ * @description A confirmation popover component that displays a confirmation dialog with customizable actions.
+ * Built on the native Popover API for top-layer rendering and Floating UI for intelligent positioning.
+ * Ideal for confirming destructive actions or important decisions inline.
+ *
+ * @slot - Default slot for the trigger element that opens the confirmation popover
+ * @slot header - Custom header content (overrides headerText prop)
+ * @slot body - Custom body content (overrides description prop)
+ * @slot footer - Custom footer content with action buttons (overrides default confirm/cancel buttons)
+ *
+ * @csspart container - The main popover container element
+ * @csspart arrow - The arrow pointer element
+ * @csspart body - The body/description section
+ * @csspart footer - The footer section with action buttons
+ *
+ * @example Basic Usage
+ * ```html
+ * <bcm-pop-confirm
+ *   header-text="Delete Item?"
+ *   description="Are you sure you want to delete this item? This action cannot be undone."
+ *   status="error"
+ * >
+ *   <bcm-button status="error">Delete</bcm-button>
+ * </bcm-pop-confirm>
+ * ```
+ *
+ * @example With Event Handlers
+ * ```html
+ * <bcm-pop-confirm
+ *   id="deleteConfirm"
+ *   header-text="Confirm Delete"
+ *   description="This will permanently delete the item."
+ *   status="warning"
+ *   confirm-text="Yes, Delete"
+ *   cancel-text="No, Keep It"
+ * >
+ *   <bcm-button>Delete Item</bcm-button>
+ * </bcm-pop-confirm>
+ *
+ * <script>
+ *   const popconfirm = document.getElementById('deleteConfirm');
+ *   popconfirm.addEventListener('bcmConfirm', () => {
+ *     console.log('User confirmed deletion');
+ *     // Perform delete operation
+ *   });
+ *   popconfirm.addEventListener('bcmCancel', () => {
+ *     console.log('User cancelled deletion');
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Different Status Types
+ * ```html
+ * <!-- Info (default) -->
+ * <bcm-pop-confirm header-text="Information" description="This is an info message">
+ *   <bcm-button>Info</bcm-button>
+ * </bcm-pop-confirm>
+ *
+ * <!-- Success -->
+ * <bcm-pop-confirm status="success" header-text="Confirm Action" description="Proceed with this action?">
+ *   <bcm-button status="success">Proceed</bcm-button>
+ * </bcm-pop-confirm>
+ *
+ * <!-- Warning -->
+ * <bcm-pop-confirm status="warning" header-text="Warning" description="This action may have consequences">
+ *   <bcm-button status="warning">Continue</bcm-button>
+ * </bcm-pop-confirm>
+ *
+ * <!-- Error/Danger -->
+ * <bcm-pop-confirm status="error" header-text="Danger Zone" description="This is a destructive action">
+ *   <bcm-button status="error">Delete</bcm-button>
+ * </bcm-pop-confirm>
+ * ```
+ *
+ * @example Custom Content with Slots
+ * ```html
+ * <bcm-pop-confirm status="warning">
+ *   <bcm-button>Custom Confirm</bcm-button>
+ *
+ *   <div slot="header">
+ *     <strong>Custom Header</strong>
+ *   </div>
+ *
+ *   <div slot="body">
+ *     <p>This is custom body content with <strong>HTML formatting</strong>.</p>
+ *     <ul>
+ *       <li>Point 1</li>
+ *       <li>Point 2</li>
+ *     </ul>
+ *   </div>
+ *
+ *   <div slot="footer">
+ *     <bcm-button kind="outline" size="small">Maybe Later</bcm-button>
+ *     <bcm-button status="success" size="small">Confirm</bcm-button>
+ *   </div>
+ * </bcm-pop-confirm>
+ * ```
+ *
+ * @example Different Sizes
+ * ```html
+ * <!-- Small -->
+ * <bcm-pop-confirm size="small" header-text="Small" description="Compact confirmation">
+ *   <bcm-button size="small">Small</bcm-button>
+ * </bcm-pop-confirm>
+ *
+ * <!-- Medium (default) -->
+ * <bcm-pop-confirm size="medium" header-text="Medium" description="Standard confirmation">
+ *   <bcm-button size="medium">Medium</bcm-button>
+ * </bcm-pop-confirm>
+ *
+ * <!-- Large -->
+ * <bcm-pop-confirm size="large" header-text="Large" description="Spacious confirmation with more room for content">
+ *   <bcm-button size="large">Large</bcm-button>
+ * </bcm-pop-confirm>
+ * ```
+ *
+ * @example Programmatic Control
+ * ```html
+ * <bcm-pop-confirm id="myConfirm" header-text="Confirm" description="Are you sure?">
+ *   <bcm-button>Trigger</bcm-button>
+ * </bcm-pop-confirm>
+ *
+ * <bcm-button id="showBtn">Show Programmatically</bcm-button>
+ * <bcm-button id="hideBtn">Hide Programmatically</bcm-button>
+ *
+ * <script>
+ *   const popconfirm = document.getElementById('myConfirm');
+ *   document.getElementById('showBtn').addEventListener('click', () => {
+ *     popconfirm.show();
+ *   });
+ *   document.getElementById('hideBtn').addEventListener('click', () => {
+ *     popconfirm.hide();
+ *   });
+ * </script>
+ * ```
+ *
+ * @example Without Status Icon
+ * ```html
+ * <bcm-pop-confirm
+ *   header-text="Simple Confirmation"
+ *   description="No status icon shown"
+ *   status-icon={false}
+ * >
+ *   <bcm-button>Click Me</bcm-button>
+ * </bcm-pop-confirm>
+ * ```
+ *
+ * @example Different Placements
+ * ```html
+ * <bcm-pop-confirm placement="top" header-text="Top" description="Opens above">
+ *   <bcm-button>Top</bcm-button>
+ * </bcm-pop-confirm>
+ *
+ * <bcm-pop-confirm placement="right" header-text="Right" description="Opens to the right">
+ *   <bcm-button>Right</bcm-button>
+ * </bcm-pop-confirm>
+ *
+ * <bcm-pop-confirm placement="bottom" header-text="Bottom" description="Opens below">
+ *   <bcm-button>Bottom</bcm-button>
+ * </bcm-pop-confirm>
+ *
+ * <bcm-pop-confirm placement="left" header-text="Left" description="Opens to the left">
+ *   <bcm-button>Left</bcm-button>
+ * </bcm-pop-confirm>
+ * ```
  */
-export declare class PopConfirm implements ComponentInterface {
-    el: HTMLElement;
+export declare class BcmPopConfirm {
+    host: HTMLElement;
+    private popconfirmRef?;
+    private arrowRef?;
+    private triggerRef?;
+    private cleanupAutoUpdate?;
+    private popconfirmId;
     /**
-     * The color of the arrow pointing to the trigger element.
-     * Can be a CSS custom property or a specific color value.
-     * @default 'var(--bcm-ui-color-background-basic-panel)'
+     * @prop {PopConfirmPlacement} placement - Position of the popover relative to the trigger element.
+     * Automatically flips if there's not enough space.
+     * Default: 'top'
      */
-    arrowColor: string;
+    placement: PopConfirmPlacement;
     /**
-     * The text displayed on the cancel button.
-     * @default 'Cancel'
+     * @prop {PopConfirmSize} size - Size variant that controls padding and text size.
+     * - 'small': Compact size with minimal padding
+     * - 'medium': Standard size
+     * - 'large': Spacious size with more padding
+     * Default: 'medium'
      */
-    cancelText: string;
+    size: PopConfirmSize;
     /**
-     * The text displayed on the confirm button.
-     * @default 'Yes'
+     * @prop {PopConfirmStatus} status - Status type that determines the color scheme and icon.
+     * - 'info': Informational (blue)
+     * - 'success': Success/positive action (green)
+     * - 'warning': Warning/caution (yellow)
+     * - 'error': Error/destructive action (red)
+     * Default: 'info'
      */
-    confirmText: string;
+    status: PopConfirmStatus;
     /**
-     * The description or body content of the pop-up.
-     * @default ''
+     * @prop {string} headerText - Text displayed in the header section.
+     * Can be overridden by using the 'header' slot.
+     * Default: ''
      */
-    description: string;
+    headerText: string;
     /**
-     * The header text displayed at the top of the pop-up.
-     * @default ''
+     * @prop {string} description - Description text displayed in the body section.
+     * Can be overridden by using the 'body' slot.
+     * Default: ''
      */
-    headerText: string;
+    description: string;
     /**
-     * The placement position of the pop-up relative to the trigger element.
-     * @default 'bottom'
+     * @prop {string} confirmText - Text for the confirm button.
+     * Default: 'Yes'
      */
-    placement: Placement;
+    confirmText: string;
     /**
-     * The size of the pop-up, determining its dimensions and padding.
-     * @default 'medium'
+     * @prop {string} cancelText - Text for the cancel button.
+     * Default: 'Cancel'
      */
-    size: 'small' | 'medium' | 'large';
+    cancelText: string;
     /**
-     * The status of the pop-up, affecting its icon and color scheme.
-     * @default 'info'
+     * @prop {boolean} showArrow - Whether to show the arrow pointing to the trigger.
+     * Default: true
      */
-    status: 'info' | 'error' | 'warning' | 'success';
+    showArrow: boolean;
     /**
-     * Whether to display a status icon based on the `status` prop.
-     * @default true
+     * @prop {boolean} statusIcon - Whether to show the status icon in the header.
+     * Icon only shows if headerText is also provided.
+     * Default: true
      */
     statusIcon: boolean;
     /**
-     * The ID of the trigger element (e.g., a button) that opens the pop-up.
+     * @prop {number} offsetDistance - Distance in pixels between the popover and trigger element.
+     * Default: 12
      */
-    targetId: string;
+    offsetDistance: number;
     /**
-     * Indicates whether the pop-up is currently open or closed.
-     * @default false
+     * @prop {boolean} closeOnOutsideClick - Whether to close when clicking outside the popover.
+     * Default: true
      */
-    isOpen: boolean;
+    closeOnOutsideClick: boolean;
     /**
-     * The current placement position of the pop-up after computation.
+     * @prop {boolean} closeOnEscape - Whether to close when pressing the Escape key.
+     * Default: true
      */
-    currentPlacement: 'top' | 'bottom' | 'left' | 'right';
+    closeOnEscape: boolean;
+    isOpen: boolean;
     /**
-     * Emits an event when the user confirms the action in the pop-up.
+     * @event bcmBeforeOpen - Emitted before the popover opens.
+     * Useful for performing actions before the popover becomes visible.
      */
-    bcmConfirm: EventEmitter<void>;
+    bcmBeforeOpen: EventEmitter<void>;
     /**
-     * Emits an event when the user cancels the action in the pop-up.
+     * @event bcmOpen - Emitted when the popover is opened.
+     * Useful for tracking when the popover becomes visible.
      */
-    bcmCancel: EventEmitter<void>;
-    private triggerElement;
-    private popoverElement;
-    private arrowElement;
+    bcmOpen: EventEmitter<void>;
     /**
-     * Lifecycle method called when the component is loaded.
-     * Initializes the trigger element and attaches a click event listener.
+     * @event bcmBeforeClose - Emitted before the popover closes.
+     * Useful for performing cleanup actions before hiding.
      */
-    componentDidLoad(): void;
+    bcmBeforeClose: EventEmitter<void>;
     /**
-     * Handles the click event on the trigger element to open the pop-up.
-     * Prevents default behavior and propagation, then opens the pop-up if it's closed.
-     * @param event The mouse event triggering the action.
+     * @event bcmClose - Emitted when the popover is closed.
+     * Useful for tracking when the popover is hidden.
      */
-    private handleTriggerClick;
+    bcmClose: EventEmitter<void>;
     /**
-     * Handles the confirm button click, closing the pop-up and emitting the confirm event.
-     * Prevents default behavior and propagation.
-     * @param event The mouse event triggering the action.
+     * @event bcmConfirm - Emitted when the user clicks the confirm button.
+     * This is where you should handle the confirmed action.
      */
-    private handleConfirm;
+    bcmConfirm: EventEmitter<void>;
     /**
-     * Handles the cancel button click, closing the pop-up and emitting the cancel event.
-     * Prevents default behavior and propagation.
-     * @param event The mouse event triggering the action.
+     * @event bcmCancel - Emitted when the user clicks cancel, presses Escape, or clicks outside.
+     * Useful for tracking when the user dismisses the confirmation.
      */
-    private handleCancel;
+    bcmCancel: EventEmitter<void>;
+    handleOpenChange(open: boolean): Promise<void>;
     /**
-     * Programmatically shows the pop-up by setting `isOpen` to true and updating its position.
-     * @returns A promise that resolves when the pop-up is shown.
+     * Programmatically shows the popconfirm.
+     * @returns Promise that resolves when the show operation begins
      */
     show(): Promise<void>;
     /**
-     * Programmatically hides the pop-up by setting `isOpen` to false.
-     * @returns A promise that resolves when the pop-up is hidden.
+     * Programmatically hides the popconfirm.
+     * @returns Promise that resolves when the hide operation begins
      */
     hide(): Promise<void>;
     /**
-     * Updates the position of the pop-up relative to the trigger element using Floating UI.
-     * Ensures the pop-up stays within viewport bounds and positions the arrow correctly.
+     * Toggles the popconfirm visibility.
+     * If open, it will close. If closed, it will open.
+     * @returns Promise that resolves when the toggle operation completes
      */
+    toggle(): Promise<void>;
+    private startAutoUpdate;
+    private stopAutoUpdate;
     private updatePosition;
-    /**
-     * Returns the dynamic styles for the pop-up, including text and arrow colors.
-     * @returns An object containing CSS custom properties.
-     */
-    private get popoverStyle();
-    /**
-     * Lifecycle method called when the component is removed from the DOM.
-     * Cleans up the event listener to prevent memory leaks.
-     */
+    private handleSlotChange;
+    private setupTriggerListeners;
+    private removeTriggerListeners;
+    private handleTriggerClick;
+    private handleOutsideClick;
+    handleKeyDown(e: KeyboardEvent): void;
+    private handleToggle;
+    private handleConfirm;
+    private handleCancel;
+    componentWillLoad(): void;
+    componentDidLoad(): void;
     disconnectedCallback(): void;
-    /**
-     * Defines Tailwind Variants classes for the pop-up's structure and styling.
-     * Supports different sizes and generates dynamic class names.
-     */
-    private classes;
-    /**
-     * Renders the pop-up component, showing it only when `isOpen` is true.
-     * Includes header, main content, and footer sections with dynamic styling and slots for customization.
-     * @returns JSX.Element representing the pop-up or an empty fragment if closed.
-     */
+    private popconfirmClass;
     render(): any;
 }