import { Maybe } from 'yummies/types';
import { Config } from 'dompurify';

/**
 * Calculates the scrollbar width.
 */
declare const calcScrollbarWidth: (elementToAppend?: HTMLElement) => number;

/**
 * Checks whether the element is nested inside the provided parent element.
 *
 * @example
 * ```ts
 * checkElementHasParent(childElement, modalElement);
 * ```
 */
declare const checkElementHasParent: (element: HTMLElement | null, parent: Maybe<HTMLElement>) => boolean;

/**
 * Collects the cumulative `offsetTop` value through the element parent chain.
 *
 * @example
 * ```ts
 * const offsetTop = collectOffsetTop(document.getElementById('section'));
 * ```
 */
declare const collectOffsetTop: (element: HTMLElement | null) => number;

/**
 * Triggers a file download by creating and clicking a temporary anchor element.
 *
 * @example
 * ```ts
 * downloadUsingAnchor('/report.pdf', 'report.pdf');
 * ```
 */
declare const downloadUsingAnchor: (urlOrBlob: string | Blob, fileName?: string) => void;

/**
 * Extracts an RGB value from any valid CSS color.
 *
 * Not recommended for frequent use because it triggers a reflow.
 */
declare const getComputedColor: (color?: string) => string | null;

/**
 * Calculates the inner height of an HTML element, accounting for padding.
 */
declare function getElementInnerHeight(element: HTMLElement): number;

/**
 * Calculates the inner width of an HTML element, accounting for padding.
 */
declare function getElementInnerWidth(el: HTMLElement): number;

/**
 * Scrolls the page vertically to the viewport section containing the target element.
 *
 * @example
 * ```ts
 * globalScrollIntoViewForY(document.getElementById('footer')!);
 * ```
 */
declare const globalScrollIntoViewForY: (node: HTMLElement) => void;

/**
 * Checks whether the user prefers a dark color scheme.
 *
 * @example
 * ```ts
 * const prefersDark = isPrefersDarkTheme();
 * ```
 */
declare const isPrefersDarkTheme: () => boolean;

/**
 * Checks whether the user prefers a light color scheme.
 *
 * @example
 * ```ts
 * const prefersLight = isPrefersLightTheme();
 * ```
 */
declare const isPrefersLightTheme: () => boolean;

/**
 * @internal Separate chunk so DOMPurify is tree-shaken away when `sanitizeHtml` is not used.
 * Consumers import from `yummies/html` — this module is not a public entry point.
 */

type SanitizeHtmlFn = ((html: Maybe<string>, config?: Config) => string) & {
    /**
     * Default DOMPurify settings
     */
    defaults: Config;
};
/**
 * Sanitizes HTML using the default allowlist merged with custom DOMPurify config.
 *
 * Default DOMPurify settings are exposed on `sanitizeHtml.defaults` and can be
 * overridden per call via `config`.
 *
 * @example
 * ```ts
 * sanitizeHtml('<img src=x onerror=alert(1) />');
 * ```
 */
declare const sanitizeHtml: SanitizeHtmlFn;

/**
 * Prevents the default browser action and stops event propagation.
 *
 * @example
 * ```ts
 * button.addEventListener('click', (event) => skipEvent(event));
 * ```
 */
declare const skipEvent: (e: Event) => boolean;

/**
 * Executes a function within a view transition if supported by the browser.
 *
 * @param {VoidFunction} fn - The function to be executed.
 * @returns {ViewTransition} - The result of the executed function.
 *
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition | MDN: Document.startViewTransition}
 */
declare const startViewTransitionSafety: (fn: VoidFunction, params?: {
    disabled?: boolean;
}) => ViewTransition | undefined;

/**
 * Surrounds string in an anchor tag
 */
declare function wrapTextToTagLink(link: string): string;

export { calcScrollbarWidth, checkElementHasParent, collectOffsetTop, downloadUsingAnchor, getComputedColor, getElementInnerHeight, getElementInnerWidth, globalScrollIntoViewForY, isPrefersDarkTheme, isPrefersLightTheme, sanitizeHtml, skipEvent, startViewTransitionSafety, wrapTextToTagLink };