JavaScript Components

/**
 * Abstract base class for all Bootstrap components
 */
class BaseComponent {
  /**
   * Creates a new component instance
   * @param element - DOM element to attach component to
   * @param config - Optional configuration object
   */
  constructor(element: Element | string, config?: ComponentConfig);
  
  /**
   * Destroys the component and cleans up all references
   */
  dispose(): void;
  
  /**
   * Retrieves an existing component instance from the element
   * @param element - DOM element to check for component instance
   * @returns Component instance or null if not found
   */
  static getInstance(element: Element | string): BaseComponent | null;
  
  /**
   * Gets existing component instance or creates new one
   * @param element - DOM element for component
   * @param config - Optional configuration object
   * @returns Component instance
   */
  static getOrCreateInstance(element: Element | string, config?: ComponentConfig): BaseComponent;
  
  /**
   * Bootstrap version string
   */
  static readonly VERSION: string; // "5.3.3"
  
  /**
   * Component-specific data key for DOM storage
   */
  static readonly DATA_KEY: string;
  
  /**
   * Component-specific event namespace
   */
  static readonly EVENT_KEY: string;
  
  /**
   * Creates namespaced event name
   * @param name - Event name to namespace
   * @returns Namespaced event string
   */
  static eventName(name: string): string;
}

interface ComponentConfig {
  [key: string]: any;
}

/**
 * Bootstrap Alert component for dismissible messages
 */
class Alert extends BaseComponent {
  static readonly NAME: string; // "alert"
  
  /**
   * Closes the alert with fade transition
   */
  close(): void;
}

// Alert events
interface AlertEvents {
  'close.bs.alert': CustomEvent;    // Fired when close method is called
  'closed.bs.alert': CustomEvent;   // Fired when alert is fully closed
}

import { Alert } from "bootstrap";

// Initialize alert
const alertElement = document.querySelector('.alert');
const alert = new Alert(alertElement);

// Close programmatically
alert.close();

// Listen for events
alertElement.addEventListener('close.bs.alert', () => {
  console.log('Alert is closing');
});

/**
 * Bootstrap Button component for enhanced button behavior
 */
class Button extends BaseComponent {
  static readonly NAME: string; // "button"
  
  /**
   * Toggles the active state of the button
   */
  toggle(): void;
}

/**
 * Bootstrap Carousel component for content slideshows
 */
class Carousel extends BaseComponent {
  static readonly NAME: string; // "carousel"
  
  /**
   * Creates carousel with configuration options
   * @param element - Carousel container element
   * @param config - Carousel configuration
   */
  constructor(element: Element | string, config?: CarouselConfig);
  
  /**
   * Move to the next slide
   */
  next(): void;
  
  /**
   * Move to the next slide only when carousel is visible
   */
  nextWhenVisible(): void;
  
  /**
   * Move to the previous slide
   */
  prev(): void;
  
  /**
   * Pause the auto-cycling of slides
   */
  pause(): void;
  
  /**
   * Start auto-cycling of slides
   */
  cycle(): void;
  
  /**
   * Move to a specific slide by index
   * @param index - Zero-based slide index
   */
  to(index: number): void;
}

interface CarouselConfig extends ComponentConfig {
  /** Time between automatic slide transitions in ms (default: 5000) */
  interval?: number;
  /** Enable keyboard navigation (default: true) */
  keyboard?: boolean;
  /** Pause behavior on hover: 'hover' or false (default: 'hover') */
  pause?: 'hover' | boolean;
  /** Auto-start carousel: true, false, or 'carousel' (default: false) */
  ride?: boolean | 'carousel';
  /** Enable continuous cycling (default: true) */
  wrap?: boolean;
  /** Enable swipe/touch gestures (default: true) */
  touch?: boolean;
}

// Carousel events
interface CarouselEvents {
  'slide.bs.carousel': CustomEvent<{ direction: string; from: number; to: number; relatedTarget: Element; }>;
  'slid.bs.carousel': CustomEvent<{ direction: string; from: number; to: number; relatedTarget: Element; }>;
}

/**
 * Bootstrap Collapse component for expandable content
 */
class Collapse extends BaseComponent {
  static readonly NAME: string; // "collapse"
  
  /**
   * Creates collapse with configuration options
   * @param element - Element to make collapsible
   * @param config - Collapse configuration
   */
  constructor(element: Element | string, config?: CollapseConfig);
  
  /**
   * Toggle the collapsed state
   */
  toggle(): void;
  
  /**
   * Show the collapsed content
   */
  show(): void;
  
  /**
   * Hide the content
   */
  hide(): void;
}

interface CollapseConfig extends ComponentConfig {
  /** Parent element for accordion behavior (default: null) */
  parent?: Element | string | null;
  /** Toggle collapse on initialization (default: true) */
  toggle?: boolean;
}

// Collapse events
interface CollapseEvents {
  'show.bs.collapse': CustomEvent;     // Fired when show method is called
  'shown.bs.collapse': CustomEvent;    // Fired when content is fully visible
  'hide.bs.collapse': CustomEvent;     // Fired when hide method is called
  'hidden.bs.collapse': CustomEvent;   // Fired when content is fully hidden
}

/**
 * Bootstrap Dropdown component for contextual menus
 */
class Dropdown extends BaseComponent {
  static readonly NAME: string; // "dropdown"
  
  /**
   * Creates dropdown with configuration options
   * @param element - Dropdown toggle element
   * @param config - Dropdown configuration
   */
  constructor(element: Element | string, config?: DropdownConfig);
  
  /**
   * Toggle dropdown visibility
   */
  toggle(): void;
  
  /**
   * Show the dropdown menu
   */
  show(): void;
  
  /**
   * Hide the dropdown menu
   */
  hide(): void;
  
  /**
   * Update dropdown position (useful after content changes)
   */
  update(): void;
}

interface DropdownConfig extends ComponentConfig {
  /** Auto-close behavior: true, false, 'inside', 'outside' (default: true) */
  autoClose?: boolean | 'inside' | 'outside';
  /** Overflow constraint boundary (default: 'clippingParents') */
  boundary?: 'viewport' | 'window' | 'scrollParent' | Element;
  /** Positioning strategy: 'absolute' or 'fixed' (default: 'absolute') */
  display?: 'static' | 'dynamic';
  /** Dropdown offset [skidding, distance] (default: [0, 2]) */
  offset?: [number, number] | string | ((popper: any) => [number, number]);
  /** Popper.js configuration object (default: null) */
  popperConfig?: object | null;
  /** Reference element: 'toggle', 'parent', or Element (default: 'toggle') */
  reference?: 'toggle' | 'parent' | Element;
}

// Dropdown events
interface DropdownEvents {
  'show.bs.dropdown': CustomEvent<{ relatedTarget: Element; }>;
  'shown.bs.dropdown': CustomEvent<{ relatedTarget: Element; }>;
  'hide.bs.dropdown': CustomEvent<{ relatedTarget: Element; }>;
  'hidden.bs.dropdown': CustomEvent<{ relatedTarget: Element; }>;
}

/**
 * Bootstrap Modal component for dialog overlays
 */
class Modal extends BaseComponent {
  static readonly NAME: string; // "modal"
  
  /**
   * Creates modal with configuration options
   * @param element - Modal container element
   * @param config - Modal configuration
   */
  constructor(element: Element | string, config?: ModalConfig);
  
  /**
   * Toggle modal visibility
   * @param relatedTarget - Element that triggered the modal
   */
  toggle(relatedTarget?: Element): void;
  
  /**
   * Show the modal
   * @param relatedTarget - Element that triggered the modal
   */
  show(relatedTarget?: Element): void;
  
  /**
   * Hide the modal
   */
  hide(): void;
  
  /**
   * Update modal layout (useful after content changes)
   */
  handleUpdate(): void;
}

interface ModalConfig extends ComponentConfig {
  /** Show backdrop: true, false, or 'static' (default: true) */
  backdrop?: boolean | 'static';
  /** Focus modal on open (default: true) */
  focus?: boolean;
  /** Close modal on escape key (default: true) */
  keyboard?: boolean;
}

// Modal events
interface ModalEvents {
  'show.bs.modal': CustomEvent<{ relatedTarget?: Element; }>;
  'shown.bs.modal': CustomEvent<{ relatedTarget?: Element; }>;
  'hide.bs.modal': CustomEvent<{ relatedTarget?: Element; }>;
  'hidden.bs.modal': CustomEvent<{ relatedTarget?: Element; }>;
  'hidePrevented.bs.modal': CustomEvent;
}

/**
 * Bootstrap Offcanvas component for sidebar overlays
 */
class Offcanvas extends BaseComponent {
  static readonly NAME: string; // "offcanvas"
  
  /**
   * Creates offcanvas with configuration options
   * @param element - Offcanvas container element
   * @param config - Offcanvas configuration
   */
  constructor(element: Element | string, config?: OffcanvasConfig);
  
  /**
   * Toggle offcanvas visibility
   * @param relatedTarget - Element that triggered the offcanvas
   */
  toggle(relatedTarget?: Element): void;
  
  /**
   * Show the offcanvas
   * @param relatedTarget - Element that triggered the offcanvas
   */
  show(relatedTarget?: Element): void;
  
  /**
   * Hide the offcanvas
   */
  hide(): void;
}

interface OffcanvasConfig extends ComponentConfig {
  /** Show backdrop: true or false (default: true) */
  backdrop?: boolean;
  /** Close on escape key (default: true) */
  keyboard?: boolean;
  /** Allow body scrolling while offcanvas is open (default: false) */
  scroll?: boolean;
}

// Offcanvas events
interface OffcanvasEvents {
  'show.bs.offcanvas': CustomEvent<{ relatedTarget?: Element; }>;
  'shown.bs.offcanvas': CustomEvent<{ relatedTarget?: Element; }>;
  'hide.bs.offcanvas': CustomEvent<{ relatedTarget?: Element; }>;
  'hidden.bs.offcanvas': CustomEvent<{ relatedTarget?: Element; }>;
}

/**
 * Bootstrap Popover component extending Tooltip with rich content
 */
class Popover extends Tooltip {
  static readonly NAME: string; // "popover"
  
  /**
   * Set popover content dynamically
   * @param content - New content object with title and/or content
   */
  setContent(content?: { title?: string; content?: string; }): void;
  
  /** @private Get popover title */
  _getTitle(): string;
  
  /** @private Get popover content */
  _getContent(): string;
}

interface PopoverConfig extends TooltipConfig {
  /** Popover content (default: '') */
  content?: string;
  /** Popover HTML template */
  template?: string;
}

/**
 * Bootstrap ScrollSpy component for scroll-based navigation
 */
class ScrollSpy extends BaseComponent {
  static readonly NAME: string; // "scrollspy"
  
  /**
   * Creates scrollspy with configuration options
   * @param element - Element to spy on scroll (usually document.body)
   * @param config - ScrollSpy configuration
   */
  constructor(element: Element | string, config?: ScrollSpyConfig);
  
  /**
   * Refresh scrollspy calculations (call after DOM changes)
   */
  refresh(): void;
}

interface ScrollSpyConfig extends ComponentConfig {
  /** @deprecated Use rootMargin instead - Offset from top when calculating scroll position (default: null) */
  offset?: number | null;
  /** IntersectionObserver rootMargin for detecting elements (default: '0px 0px -25%') */
  rootMargin?: string;
  /** Enable smooth scrolling when clicking navigation links (default: false) */
  smoothScroll?: boolean;
  /** Target navigation element containing spy links (required) */
  target: Element | string;
  /** IntersectionObserver threshold values (default: [0.1, 0.5, 1]) */
  threshold?: number[];
}

// ScrollSpy events
interface ScrollSpyEvents {
  'activate.bs.scrollspy': CustomEvent<{ relatedTarget: Element; }>;
}

/**
 * Bootstrap Tab component for tabbed navigation
 */
class Tab extends BaseComponent {
  static readonly NAME: string; // "tab"
  
  /**
   * Show the tab panel associated with this tab
   */
  show(): void;
}

// Tab events
interface TabEvents {
  'hide.bs.tab': CustomEvent<{ target: Element; relatedTarget: Element; }>;
  'hidden.bs.tab': CustomEvent<{ target: Element; relatedTarget: Element; }>;
  'show.bs.tab': CustomEvent<{ target: Element; relatedTarget: Element; }>;
  'shown.bs.tab': CustomEvent<{ target: Element; relatedTarget: Element; }>;
}

/**
 * Bootstrap Toast component for notifications
 */
class Toast extends BaseComponent {
  static readonly NAME: string; // "toast"
  
  /**
   * Creates toast with configuration options
   * @param element - Toast container element
   * @param config - Toast configuration
   */
  constructor(element: Element | string, config?: ToastConfig);
  
  /**
   * Show the toast
   */
  show(): void;
  
  /**
   * Hide the toast
   */
  hide(): void;
}

interface ToastConfig extends ComponentConfig {
  /** Apply CSS fade transition (default: true) */
  animation?: boolean;
  /** Auto-hide the toast (default: true) */
  autohide?: boolean;
  /** Delay before hiding in milliseconds (default: 5000) */
  delay?: number;
}

// Toast events
interface ToastEvents {
  'show.bs.toast': CustomEvent;     // Fired when show() is called
  'shown.bs.toast': CustomEvent;    // Fired when toast is fully shown
  'hide.bs.toast': CustomEvent;     // Fired when hide() is called  
  'hidden.bs.toast': CustomEvent;   // Fired when toast is fully hidden
}

/**
 * Bootstrap Tooltip component for contextual information
 */
class Tooltip extends BaseComponent {
  static readonly NAME: string; // "tooltip"
  
  /**
   * Creates tooltip with configuration options
   * @param element - Element to attach tooltip to
   * @param config - Tooltip configuration
   */
  constructor(element: Element | string, config?: TooltipConfig);
  
  /**
   * Enable tooltip
   */
  enable(): void;
  
  /**
   * Disable tooltip
   */
  disable(): void;
  
  /**
   * Toggle enabled state
   */
  toggleEnabled(): void;
  
  /**
   * Toggle tooltip visibility
   */
  toggle(): void;
  
  /**
   * Show the tooltip
   */
  show(): void;
  
  /**
   * Hide the tooltip
   */
  hide(): void;
  
  /**
   * Update tooltip position
   */
  update(): void;
  
  /**
   * Update tooltip content
   * @param content - New content object
   */
  setContent(content?: { title?: string; }): void;
}

interface TooltipConfig extends ComponentConfig {
  /** Allowed HTML tags and attributes for sanitization (default: DefaultAllowlist) */
  allowList?: { [key: string]: string[] };
  /** Apply CSS fade transition (default: true) */
  animation?: boolean;
  /** Overflow constraint boundary (default: 'clippingParents') */
  boundary?: 'viewport' | 'window' | 'scrollParent' | 'clippingParents' | Element;
  /** Tooltip container element (default: false) */
  container?: Element | string | false;
  /** Custom CSS class to add (default: '') */
  customClass?: string | (() => string);
  /** Show/hide delay in ms: number or {show: ms, hide: ms} (default: 0) */
  delay?: number | { show: number; hide: number; };
  /** Fallback placement positions when preferred placement doesn't fit (default: ['top', 'right', 'bottom', 'left']) */
  fallbackPlacements?: string[];
  /** Allow HTML content (default: false) */
  html?: boolean;
  /** Tooltip offset [skidding, distance] (default: [0, 6]) */
  offset?: [number, number] | string | ((popper: any) => [number, number]);
  /** Tooltip placement (default: 'top') */
  placement?: 'auto' | 'top' | 'right' | 'bottom' | 'left' | ((tooltip: Element, trigger: Element) => string);
  /** Popper.js configuration (default: null) */
  popperConfig?: object | null | ((popperConfig: object) => object);
  /** Sanitize HTML content (default: true) */
  sanitize?: boolean;
  /** Custom sanitizer function */
  sanitizeFn?: ((input: string) => string) | null;
  /** Delegation selector for event binding (default: false) */
  selector?: string | false;
  /** Tooltip HTML template */
  template?: string;
  /** Tooltip title content (default: '') */
  title?: string | Element | (() => string | Element);
  /** Trigger events: space-separated list (default: 'hover focus') */
  trigger?: 'click' | 'hover' | 'focus' | 'manual' | string;
}

// Tooltip events
interface TooltipEvents {
  'show.bs.tooltip': CustomEvent;      // Fired when tooltip is about to show
  'shown.bs.tooltip': CustomEvent;     // Fired when tooltip is fully shown
  'hide.bs.tooltip': CustomEvent;      // Fired when tooltip is about to hide
  'hidden.bs.tooltip': CustomEvent;    // Fired when tooltip is fully hidden
  'inserted.bs.tooltip': CustomEvent;  // Fired when tooltip template is added to DOM
}

// Direct instantiation
const modal = new Modal(document.getElementById('myModal'));

// Get or create instance
const tooltip = Tooltip.getOrCreateInstance('[data-bs-toggle="tooltip"]');

// Initialize all tooltips
document.querySelectorAll('[data-bs-toggle="tooltip"]')
  .forEach(el => new Tooltip(el));

// Listen for component events
document.addEventListener('shown.bs.modal', (event) => {
  console.log('Modal shown:', event.target);
});

// Component-specific events
const myModal = document.getElementById('myModal');
myModal.addEventListener('hide.bs.modal', (event) => {
  if (someCondition) {
    event.preventDefault(); // Prevent modal from closing
  }
});

// Pass config during initialization
const carousel = new Carousel('#myCarousel', {
  interval: 2000,
  wrap: false,
  keyboard: false
});

// Data attributes (alternative)
// <div class="carousel" data-bs-interval="2000" data-bs-wrap="false">