bromcom-ui-next 0.1.29 → 0.1.31

package/dist/types/components/linked/linked.component.d.ts

@@ -1,59 +1,175 @@
 import { ComponentInterface, EventEmitter } from '../../stencil-public-runtime';
 import { type Placement } from '@floating-ui/dom';
 export type TriggerType = 'hover' | 'click' | 'focus' | 'manual';
+/**
+ * @component BcmLinked
+ * @description A flexible linked floating element component that displays contextual content relative to a trigger element.
+ * Built on the native Popover API for top-layer rendering and Floating UI for intelligent positioning.
+ * Supports different trigger types (click, hover, focus, manual) and comprehensive event system.
+ *
+ * @example Basic Click Trigger
+ * <bcm-linked trigger="click">
+ *   <button slot="trigger">Click Me</button>
+ *   <div>Floating content here</div>
+ * </bcm-linked>
+ *
+ * @example Hover Trigger with Delays
+ * <bcm-linked trigger="hover" show-delay="200" hide-delay="100">
+ *   <span slot="trigger">Hover Me</span>
+ *   <div>This appears on hover</div>
+ * </bcm-linked>
+ *
+ * @example Manual Control
+ * <bcm-linked id="my-linked" trigger="manual">
+ *   <button slot="trigger">Trigger</button>
+ *   <div>Controlled content</div>
+ * </bcm-linked>
+ * <script>
+ *   const linked = document.querySelector('#my-linked');
+ *   linked.show(); // Opens the floating element
+ *   linked.hide(); // Closes the floating element
+ * </script>
+ *
+ * @slot trigger - The trigger element that controls the floating element visibility
+ * @slot - Default slot for the floating content
+ *
+ * @csspart floating - The floating container element
+ * @csspart arrow - The arrow element pointing to the trigger
+ * @csspart content - The content wrapper element
+ */
 export declare class BcmLinked implements ComponentInterface {
     host: HTMLElement;
-    targetId?: string;
-    targetElement?: HTMLElement;
+    private floatingRef?;
+    private triggerRef?;
+    private arrowRef?;
+    private cleanupAutoUpdate?;
+    private showTimeout?;
+    private hideTimeout?;
+    private componentId;
+    /**
+     * @prop {boolean} visible - Controls the visibility state of the floating element.
+     * Can be set programmatically or toggled by user interaction.
+     * Default: false
+     */
+    visible: boolean;
+    /**
+     * @prop {TriggerType} trigger - Defines the interaction type to show/hide the floating element.
+     * 'click' toggles on click, 'hover' shows on mouse enter and hides on mouse leave,
+     * 'focus' shows on focus and hides on blur, 'manual' requires programmatic control.
+     * Default: 'click'
+     */
     trigger: TriggerType;
+    /**
+     * @prop {Placement} placement - Defines the position of the floating element relative to the trigger.
+     * Default: 'bottom-start'
+     */
     placement: Placement;
+    /**
+     * @prop {number} showDelay - Delay in milliseconds before showing the floating element.
+     * Default: 0
+     */
     showDelay: number;
+    /**
+     * @prop {number} hideDelay - Delay in milliseconds before hiding the floating element.
+     * Default: 0
+     */
     hideDelay: number;
-    offset: number;
-    arrow: boolean;
+    /**
+     * @prop {number} offsetDistance - Distance in pixels between the floating element and the trigger.
+     * Default: 8
+     */
+    offsetDistance: number;
+    /**
+     * @prop {boolean} showArrow - Whether to show an arrow pointing to the trigger element.
+     * Default: true
+     */
+    showArrow: boolean;
+    /**
+     * @prop {boolean} disabled - Disables the floating element, preventing it from showing.
+     * Default: false
+     */
     disabled: boolean;
-    zIndex: number;
-    appendToBody: boolean;
-    destroyOnHide: boolean;
+    /**
+     * @prop {boolean} closeOnOutsideClick - Whether to close when clicking outside.
+     * Default: true
+     */
+    closeOnOutsideClick: boolean;
+    /**
+     * @prop {boolean} closeOnEscape - Whether to close when pressing Escape key.
+     * Default: true
+     */
+    closeOnEscape: boolean;
     isVisible: boolean;
-    isReady: boolean;
+    /**
+     * @event bcmBeforeShow - Emitted before the floating element shows.
+     */
+    bcmBeforeShow: EventEmitter<void>;
+    /**
+     * @event bcmShow - Emitted when the floating element is shown.
+     */
     bcmShow: EventEmitter<void>;
+    /**
+     * @event bcmBeforeHide - Emitted before the floating element hides.
+     */
+    bcmBeforeHide: EventEmitter<void>;
+    /**
+     * @event bcmHide - Emitted when the floating element is hidden.
+     */
     bcmHide: EventEmitter<void>;
+    /**
+     * @event bcmShown - Emitted after the floating element is fully shown (after animation).
+     */
     bcmShown: EventEmitter<void>;
+    /**
+     * @event bcmHidden - Emitted after the floating element is fully hidden (after animation).
+     */
     bcmHidden: EventEmitter<void>;
-    private floatingEl?;
-    private targetEl?;
-    private showTimeout?;
-    private hideTimeout?;
-    private cleanup?;
-    private clickOutsideHandler?;
-    private resizeObserver?;
-    private originalParent?;
-    private originalNextSibling?;
-    setupTarget(): void;
-    onVisibilityChange(newValue: boolean): void;
-    componentDidLoad(): Promise<void>;
-    disconnectedCallback(): void;
-    private connectTarget;
-    private disconnectTarget;
-    private setupEventListeners;
-    private removeEventListeners;
-    private setupClickOutside;
-    private removeClickOutside;
+    handleVisibleChange(newValue: boolean): void;
+    handleDisabledChange(isDisabled: boolean): void;
+    handlePositionPropsChange(): void;
+    private showInternal;
+    private hideInternal;
+    /**
+     * Programmatically shows the floating element.
+     * Respects the showDelay prop.
+     */
+    show(): Promise<void>;
+    /**
+     * Programmatically hides the floating element.
+     * Respects the hideDelay prop.
+     */
+    hide(): Promise<void>;
+    /**
+     * Toggles the floating element visibility.
+     */
+    toggle(): Promise<void>;
+    /**
+     * Updates the position of the floating element.
+     * Useful when the trigger element moves or resizes.
+     */
+    updatePosition(): Promise<void>;
+    private clearTimeouts;
+    private handleTriggerSlotChange;
+    private setupAriaAttributes;
+    private setupTriggerListeners;
+    private removeTriggerListeners;
     private handleMouseEnter;
     private handleMouseLeave;
     private handleFloatingMouseEnter;
     private handleFloatingMouseLeave;
-    private handleClick;
+    private handleTriggerClick;
     private handleFocus;
     private handleBlur;
-    private clearTimeouts;
-    private updatePosition;
-    private updateArrow;
-    show(): Promise<void>;
-    hide(): Promise<void>;
-    toggle(): Promise<void>;
-    updatePositioning(): Promise<void>;
-    private setupFloatingObserver;
+    handleKeyDown(event: KeyboardEvent): void;
+    private handleOutsideClick;
+    private addOutsideClickListener;
+    private removeOutsideClickListener;
+    private calculatePosition;
+    private startAutoUpdate;
+    private stopAutoUpdate;
+    private handleToggle;
+    componentDidLoad(): void;
+    disconnectedCallback(): void;
+    private linkedClass;
     render(): any;
 }

package/dist/types/components/modal/modal.component.d.ts

@@ -1,33 +1,154 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 export type ModalSize = 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge' | 'full';
 export type ModalPlacement = 'center' | 'top';
+/**
+ * @component BcmModal
+ * @description A flexible modal dialog component built on the native HTML Dialog API.
+ * Provides a powerful way to display content in a layer above the page with full keyboard and focus management.
+ *
+ * @slot - Main content area of the modal
+ * @slot header - Custom header content (overrides header-text prop)
+ * @slot helper - Custom helper text content (overrides helper-text prop)
+ * @slot footer - Footer content for action buttons
+ *
+ * @part dialog - The native dialog element
+ * @part container - The container wrapper for centering and scrolling
+ * @part modal - The main modal box
+ * @part header - The header section
+ * @part header-content - The content wrapper inside header
+ * @part title - The title heading element
+ * @part helper-text - The helper text paragraph
+ * @part close-button - The close button in header
+ * @part content - The main content area
+ * @part footer - The footer section
+ *
+ * @example
+ * ```html
+ * <!-- Basic usage -->
+ * <bcm-modal open header-text="Welcome" helper-text="Please read carefully">
+ *   <p>Modal content goes here</p>
+ *   <div slot="footer">
+ *     <button data-dismiss>Close</button>
+ *   </div>
+ * </bcm-modal>
+ *
+ * <!-- Custom size and placement -->
+ * <bcm-modal size="large" placement="top">
+ *   <div slot="header">Custom Header</div>
+ *   <p>Content here</p>
+ *   <div slot="footer">
+ *     <button>Cancel</button>
+ *     <button>Confirm</button>
+ *   </div>
+ * </bcm-modal>
+ *
+ * <!-- Full screen modal -->
+ * <bcm-modal full-screen no-footer>
+ *   <p>Full screen content</p>
+ * </bcm-modal>
+ *
+ * <!-- Programmatic usage -->
+ * <bcm-modal id="myModal">Content</bcm-modal>
+ * <script>
+ *   document.getElementById('myModal').show();
+ * </script>
+ * ```
+ */
 export declare class BcmModal {
     host: HTMLBcmModalElement;
     private dialogRef?;
+    /**
+     * Controls whether the modal is open or closed
+     */
     open: boolean;
+    /**
+     * The size of the modal
+     * - 'small': 400px
+     * - 'medium': 600px
+     * - 'large': 800px
+     * - 'xlarge': 1024px
+     * - 'xxlarge': 1200px
+     * - 'full': 100% width
+     */
     size: ModalSize;
+    /**
+     * The placement of the modal on the screen
+     * - 'center': Centered vertically and horizontally
+     * - 'top': Aligned to the top with 80px padding
+     */
     placement: ModalPlacement;
+    /**
+     * Controls backdrop behavior
+     * - true: Shows backdrop, modal can be closed by clicking outside
+     * - false: No backdrop
+     * - 'static': Shows backdrop but prevents closing by clicking outside (triggers shake animation)
+     */
     backdrop: boolean | 'static';
+    /**
+     * Makes the modal take full width of the viewport (max-width: 100%)
+     */
     fullWidth: boolean;
+    /**
+     * Makes the modal take the full screen (100vw x 100vh, no border radius)
+     */
     fullScreen: boolean;
+    /**
+     * Text to display in the modal header
+     */
     headerText?: string;
+    /**
+     * Helper text to display below the header title
+     */
     helperText?: string;
+    /**
+     * Hides the header section completely
+     */
     noHeader: boolean;
+    /**
+     * Hides the footer section completely
+     */
     noFooter: boolean;
+    /**
+     * Allows closing the modal by clicking on the backdrop
+     */
     closeOnBackdrop: boolean;
+    /**
+     * Allows closing the modal by pressing the Escape key
+     */
     closeOnEscape: boolean;
     isAnimating: boolean;
     shake: boolean;
+    /**
+     * Emitted after the modal has opened
+     */
     bcmOpen: EventEmitter<void>;
+    /**
+     * Emitted after the modal has closed
+     */
     bcmClose: EventEmitter<void>;
+    /**
+     * Emitted before the modal opens. Can be cancelled by calling event.preventDefault()
+     */
     bcmBeforeOpen: EventEmitter<void>;
+    /**
+     * Emitted before the modal closes. Can be cancelled by calling event.preventDefault()
+     */
     bcmBeforeClose: EventEmitter<void>;
     private modalClass;
     handleOpenChange(isOpen: boolean): Promise<void>;
     handleClick(event: MouseEvent): void;
     handleKeyDown(event: KeyboardEvent): void;
+    /**
+     * Programmatically opens the modal
+     */
     show(): Promise<void>;
+    /**
+     * Programmatically closes the modal
+     */
     hide(): Promise<void>;
+    /**
+     * Toggles the modal open/closed state
+     */
     toggle(): Promise<void>;
     private shakeModal;
     private handleBackdropClick;