Core API

/**
 * Creates a new SimpleBar instance with custom scrollbars
 * @param element - The HTML element to apply SimpleBar to
 * @param options - Configuration options for scrollbar behavior
 */
constructor(element: HTMLElement, options?: SimpleBarOptions);

import SimpleBar from "simplebar";

// Basic initialization
const simpleBar = new SimpleBar(document.getElementById('myDiv'));

// With configuration options
const simpleBar = new SimpleBar(document.getElementById('chatBox'), {
  autoHide: false,
  scrollbarMinSize: 25,
  clickOnTrack: true,
  classNames: {
    scrollbar: 'my-custom-scrollbar'
  }
});

/**
 * Returns the element that contains the scrollable content
 * Use this element to attach scroll event listeners
 * @returns The scrollable HTML element or null if not initialized
 */
getScrollElement(): HTMLElement | null;

const simpleBar = new SimpleBar(document.getElementById('myDiv'));
const scrollEl = simpleBar.getScrollElement();

if (scrollEl) {
  scrollEl.addEventListener('scroll', (e) => {
    console.log('Scroll position:', scrollEl.scrollTop);
  });
}

/**
 * Returns the element that contains the actual content
 * Use this element to add or modify scrollable content
 * @returns The content HTML element or null if not initialized
 */
getContentElement(): HTMLElement | null;

const simpleBar = new SimpleBar(document.getElementById('myDiv'));
const contentEl = simpleBar.getContentElement();

if (contentEl) {
  // Add new content
  const newItem = document.createElement('div');
  newItem.textContent = 'New scrollable item';
  contentEl.appendChild(newItem);
}

/**
 * Recalculates scrollbar size and position
 * Call this method when content dimensions change programmatically
 */
recalculate(): void;

const simpleBar = new SimpleBar(document.getElementById('myDiv'));

// After adding content dynamically
const contentEl = simpleBar.getContentElement();
contentEl.innerHTML += '<div>New content that changes height</div>';

// Manually trigger recalculation
simpleBar.recalculate();

/**
 * Remove all event listeners from DOM elements
 * Called automatically by unMount(), but can be called separately
 */
removeListeners(): void;

/**
 * Removes SimpleBar from the element and cleans up resources
 * Removes all event listeners and DOM modifications
 */
unMount(): void;

const simpleBar = new SimpleBar(document.getElementById('myDiv'));

// Remove only event listeners (keep DOM structure)
simpleBar.removeListeners();

// Later, when fully cleaning up
simpleBar.unMount();

/**
 * Show scrollbar for specified axis
 * @param axis - The axis ('x' or 'y') to show scrollbar for
 */
showScrollbar(axis?: Axis): void;

/**
 * Hide scrollbar for specified axis
 * @param axis - The axis ('x' or 'y') to hide scrollbar for  
 */
hideScrollbar(axis?: Axis): void;

/**
 * Position scrollbar handle for specified axis
 * @param axis - The axis ('x' or 'y') to position scrollbar for
 */
positionScrollbar(axis?: Axis): void;

/**
 * Toggle track visibility for specified axis
 * @param axis - The axis ('x' or 'y') to toggle track visibility for
 */
toggleTrackVisibility(axis?: Axis): void;

/**
 * Calculate scrollbar size for specified axis
 * @param axis - The axis ('x' or 'y') to calculate size for
 * @returns Scrollbar size in pixels
 */
getScrollbarSize(axis?: Axis): number;

/**
 * Get the width of the native browser scrollbar
 * @returns Width of native scrollbar in pixels
 */
getScrollbarWidth(): number;

const simpleBar = new SimpleBar(document.getElementById('myDiv'));

// Manually show vertical scrollbar
simpleBar.showScrollbar('y');

// Hide horizontal scrollbar
simpleBar.hideScrollbar('x');

// Get current scrollbar size
const verticalScrollbarSize = simpleBar.getScrollbarSize('y');
console.log('Vertical scrollbar size:', verticalScrollbarSize);

// Get native browser scrollbar width
const nativeScrollbarWidth = simpleBar.getScrollbarWidth();
console.log('Native scrollbar width:', nativeScrollbarWidth);

/**
 * Hide native browser scrollbar
 * Internal method that positions content to hide native scrollbar
 */
hideNativeScrollbar(): void;

/**
 * Check if mouse position is within bounds of a rectangle
 * @param bbox - DOMRect to check bounds against
 * @returns True if mouse is within bounds
 */
isWithinBounds(bbox: DOMRect): boolean;

/**
 * Find child element matching query selector
 * @param el - Parent element to search within
 * @param query - CSS selector query
 * @returns First matching child element or undefined
 */
findChild(el: HTMLElement, query: string): HTMLElement | undefined;

/**
 * Get options from HTML data attributes
 * Used internally for data-attribute parsing
 */
static getOptions: (attributes: NamedNodeMap) => SimpleBarOptions;

/**
 * Helper functions for DOM manipulation and environment detection
 */
static helpers: {
  getElementWindow(element: Element): Window;
  getElementDocument(element: Element): Document;
  getOptions(attributes: NamedNodeMap): SimpleBarOptions;
  addClasses(el: HTMLElement | null, classes: string): void;
  removeClasses(el: HTMLElement | null, classes: string): void;
  classNamesToQuery(classNames: string): string;
  canUseDOM: boolean;
};

/**
 * Get RTL (right-to-left) browser compatibility helpers
 * @returns RTL configuration object or null if not supported
 */
static getRtlHelpers(): {
  isScrollOriginAtZero: boolean;
  isScrollingToNegative: boolean;
} | null;

/**
 * Get element offset position relative to document
 * @param el - Element to get offset for
 * @returns Object with top and left properties
 */
static getOffset(el: Element): { top: number; left: number };

/**
 * Default configuration options
 */
static defaultOptions: SimpleBarOptions;

interface SimpleBarOptions {
  /** Force scrollbar visibility. true/false for both axes, 'x'/'y' for specific axis */
  forceVisible?: boolean | 'x' | 'y';
  
  /** Enable clicking on track to scroll (default: true) */
  clickOnTrack?: boolean;
  
  /** Minimum scrollbar size in pixels (default: 25) */
  scrollbarMinSize?: number;
  
  /** Maximum scrollbar size in pixels (default: 0 = no limit) */
  scrollbarMaxSize?: number;
  
  /** Custom CSS class names for scrollbar components */
  classNames?: Partial<ClassNames>;
  
  /** Accessibility label for screen readers (default: "scrollable content") */
  ariaLabel?: string;
  
  /** Tab index for keyboard navigation (default: 0) */
  tabIndex?: number;
  
  /** Custom scrollable element (advanced usage) */
  scrollableNode?: HTMLElement | null;
  
  /** Custom content element (advanced usage) */
  contentNode?: HTMLElement | null;
  
  /** Auto-hide scrollbar when not scrolling (default: true) */
  autoHide?: boolean;
}