igniteui-webcomponents/components/common/util.d.ts

Ignite UI for Web Components is a complete library of UI components, giving you the ability to build modern web applications using encapsulation and the concept of reusable components in a dependency-free approach.

import { type TemplateResult } from 'lit';
import type IgcFileInputComponent from '../file-input/file-input.js';
export declare const asPercent: (part: number, whole: number) => number;
export declare const clamp: (number: number, min: number, max: number) => number;
export declare function numberOfDecimals(number: number): number;
export declare function roundPrecise(number: number, magnitude?: number): number;
export declare function numberInRangeInclusive(value: number, min: number, max: number): boolean;
/**
 * Returns whether an element has a Left-to-Right directionality.
 */
export declare function isLTR(element: HTMLElement): boolean;
/**
 * Builds a string from format specifiers and replacement parameters.
 * Will coerce non-string parameters to their string representations.
 *
 * @example
 * ```typescript
 * formatString('{0} says "{1}".', 'John', 'Hello'); // 'John says "Hello".'
 * formatString('{1} is greater than {0}', 0, 1); // '1 is greater than 0'
 * ```
 */
export declare function formatString(template: string, ...params: unknown[]): string;
/**
 * Parse the passed `value` as a number or return the `fallback` if it can't be done.
 *
 * @example
 * ```typescript
 * asNumber('5'); // 5
 * asNumber('3.14'); // 3.14
 * asNumber('five'); // 0
 * asNUmber('five', 5); // 5
 * ```
 */
export declare function asNumber(value: unknown, fallback?: number): number;
/**
 * Returns the value wrapped between the min and max bounds.
 *
 * If the value is greater than max, returns the min and vice-versa.
 * If the value is between the bounds, it is returned unchanged.
 *
 * @example
 * ```typescript
 * wrap(1, 4, 2); // 2
 * wrap(1, 4, 5); // 1
 * wrap(1, 4, -1); // 4
 * ```
 */
export declare function wrap(min: number, max: number, value: number): number;
export declare function isDefined<T = unknown>(value: T): value is T & ({} | null);
export type IterNodesOptions<T = Node> = {
    show?: keyof typeof NodeFilter;
    filter?: (node: T) => boolean;
};
export declare function iterNodes<T extends Node>(root: Node, options?: IterNodesOptions<T>): Generator<T>;
export declare function getRoot(element: Element, options?: GetRootNodeOptions): Document | ShadowRoot;
export declare function getElementByIdFromRoot(root: HTMLElement, id: string): HTMLElement | null;
export declare function isElement(node: unknown): node is Element;
export declare function findElementFromEventPath<K extends keyof HTMLElementTagNameMap>(predicate: K, event: Event): HTMLElementTagNameMap[K] | undefined;
export declare function findElementFromEventPath<T extends Element>(predicate: string | ((element: Element) => boolean), event: Event): T | undefined;
export declare function first<T>(arr: T[]): T;
export declare function last<T>(arr: T[]): T;
export declare function modulo(n: number, d: number): number;
/**
 * Splits an array into chunks of a specified size and returns a generator that yields each chunk.
 *
 * @example
 * ```typescript
 * [...chunk([1, 2, 3, 4, 5], 2)]; // [[1, 2], [3, 4], [5]]
 * ```
 *
 * @throws If the `size` parameter is not a safe integer greater than or equal to 1.
 */
export declare function chunk<T>(arr: T[], size: number): Generator<T[]>;
export declare function splitToWords(text: string): string[];
export declare function toKebabCase(text: string): string;
export declare function isFunction(value: unknown): value is CallableFunction;
export declare function isString(value: unknown): value is string;
export declare function isObject(value: unknown): value is object;
export declare function isPlainObject(value: unknown): value is Record<PropertyKey, unknown>;
export declare function isEventListenerObject(x: unknown): x is EventListenerObject;
export declare function addWeakEventListener(element: Element, event: string, listener: EventListenerOrEventListenerObject, options?: AddEventListenerOptions | boolean): void;
type EventTypeOf<T extends keyof HTMLElementEventMap | keyof WindowEventMap> = (HTMLElementEventMap & WindowEventMap)[T];
/**
 * Safely adds an event listener to an HTMLElement, automatically handling
 * server-side rendering environments by doing nothing if `isServer` is true.
 * This function also correctly binds the `handler`'s `this` context to the `target` element
 * and ensures proper event type inference.
 */
export declare function addSafeEventListener<E extends keyof HTMLElementEventMap | keyof WindowEventMap>(target: HTMLElement, eventName: E, handler: (event: EventTypeOf<E>) => unknown, options?: boolean | AddEventListenerOptions): void;
/**
 * Returns whether a given collection is empty.
 */
export declare function isEmpty<T, U extends object>(x: ArrayLike<T> | Set<T> | Map<U, T>): boolean;
export declare function asArray<T>(value?: T | T[]): T[];
export declare function partition<T>(array: T[], isTruthy: (value: T) => boolean): [truthy: T[], falsy: T[]];
/** Returns the center x/y coordinate of a given element. */
export declare function getCenterPoint(element: Element): {
    x: number;
    y: number;
};
/** Returns the scale factor of a given element based on its bounding client rect and offset dimensions. */
export declare function getScaleFactor(element: HTMLElement): {
    x: number;
    y: number;
};
export declare function roundByDPR(value: number): number;
export declare function scrollIntoView(element?: HTMLElement | null, config?: ScrollIntoViewOptions): void;
export declare function isRegExp(value: unknown): value is RegExp;
export declare function equal<T>(a: unknown, b: T, visited?: WeakSet<WeakKey>): boolean;
/**
 *  Escapes any potential regex syntax characters in a string, and returns a new string
 *  that can be safely used as a literal pattern for the `RegExp()` constructor.
 *
 *  @remarks
 *  Substitute with `RegExp.escape` once it has enough support:
 *
 * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/escape#browser_compatibility
 */
export declare function escapeRegex(value: string): string;
/** Required utility type for specific props */
export type RequiredProps<T, K extends keyof T> = T & {
    [P in K]-?: T[P];
};
export declare function setStyles(element: HTMLElement, styles: Partial<CSSStyleDeclaration>): void;
/**
 * Merges the properties of `source` into `target` performing a recursive deep merge over POJOs and arrays.
 *
 * @remarks
 * This function mutates the `target` object.
 * If that is not the desired outcome, see {@link toMerged} for another approach.
 */
export declare function merge<T extends Record<PropertyKey, any>, S extends Record<PropertyKey, any>>(target: T, source: S): T & S;
/**
 * Just like {@link merge} but it does not mutate the `target` object instead
 * mutating a structured clone of it.
 */
export declare function toMerged<T extends Record<PropertyKey, any>, S extends Record<PropertyKey, any>>(target: T, source: S): T & S;
/**
 * Similar to Lit's `ifDefined` directive except one can check `assertion`
 * and bind a different `value` through this wrapper.
 */
export declare function bindIf<T>(assertion: unknown, value: T): NonNullable<T>;
export declare function nanoid(size?: number): string;
export declare function hasFiles(input: HTMLInputElement | IgcFileInputComponent): boolean;
/** @internal */
export declare function trimmedHtml(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
export {};