/**
 * Comparator that sorts empty values (see `isEmpty`) to one end, uses `comparator` for two strings, and falls back to
 * `<` / `>` for everything else.
 *
 * @param value1 Left value.
 * @param value2 Right value.
 * @param comparator String comparator, typically from `localeComparator`.
 * @param order Sort direction; also decides which end empty values land on. Defaults to `1`.
 * @returns `-1`, `0` or `1`.
 */
declare function compare<T = unknown>(value1: T, value2: T, comparator: (val1: T, val2: T) => number, order?: number): number;

/**
 * Determines whether `list` holds a value deep-equal to `value`. A `null` or `undefined` `value` is never contained.
 *
 * @param value Value to look for.
 * @param list List to search.
 * @returns True when a deep-equal element exists.
 */
declare function contains<T = unknown>(value: T, list: T[]): boolean;

/**
 * Structural equality for arbitrary values. Handles arrays, plain objects, `Date` (by timestamp), `RegExp` (by source
 * and flags), `Map` and `Set`, and treats `NaN` as equal to itself. Cyclic graphs terminate.
 *
 * `Set` members are matched by `has`, so sets of structurally equal but distinct objects compare as unequal.
 *
 * @param obj1 First value.
 * @param obj2 Second value.
 * @returns True when both values are structurally equal.
 */
declare function deepEquals(obj1: unknown, obj2: unknown): boolean;

/**
 * Deep-merges objects into a fresh object graph; inputs are never mutated and the result shares no
 * references with them. Arrays are replaced (not element-merged). Cyclic sources are handled.
 *
 * A reference shared within a single source object keeps its shared identity in the result, but only
 * when first reached against an empty slot; references shared across separate arguments are cloned
 * independently.
 * @param args Objects to merge, left to right.
 * @returns Merged object.
 */
declare function deepMerge(...args: Record<string, unknown>[]): Record<string, unknown>;

/**
 * Compares two values, either structurally or by a single field.
 *
 * @param obj1 First value.
 * @param obj2 Second value.
 * @param field Optional field path resolved on both operands and compared with `===`; when omitted the values are compared with `deepEquals`.
 * @returns True when the values are considered equal.
 */
declare function equals(obj1: unknown, obj2: unknown, field?: string): boolean;

/**
 * Filters items whose value at any of `fields` contains `filterValue` as a case-insensitive substring. Field values are
 * coerced with `String`, so a missing field matches the literal text `undefined`.
 *
 * @param value Items to filter.
 * @param fields Field paths resolved per item, matched with OR semantics.
 * @param filterValue Search text.
 * @returns Matching items, in source order.
 */
declare function filter<T = unknown>(value: T[], fields: string[], filterValue: string): T[];

/**
 * Index of the first element strictly equal (`===`) to `value`, or `-1` when absent or `list` is nullish.
 *
 * @param value Value to locate.
 * @param list List to search.
 * @returns Zero-based index, or `-1`.
 */
declare function findIndexInList<T = unknown>(value: T, list: T[]): number;

/**
 * Firefox-v103 does not currently support the "findLast" method. It is stated that this method will be supported with Firefox-v104.
 * https://caniuse.com/mdn-javascript_builtins_array_findlast
 */
declare function findLast<T = unknown>(arr: T[], callback: (value: T, index: number, array: T[]) => boolean): T | undefined;

/**
 * Firefox-v103 does not currently support the "findLastIndex" method. It is stated that this method will be supported with Firefox-v104.
 * https://caniuse.com/mdn-javascript_builtins_array_findlastindex
 */
declare function findLastIndex<T = unknown>(arr: T[], callback: (value: T, index: number, array: T[]) => boolean): number;

/**
 * Reads a dot-separated path from an object, matching each segment case-insensitively and ignoring `-` and `_` (see
 * `toFlatCase`). Every value along the path is passed through `resolve`, so functions are invoked with `params` and
 * their return value is traversed.
 *
 * @param obj Source object or array.
 * @param key Dot-separated path. An empty path resolves `obj` itself.
 * @param params Arguments applied to any function encountered along the path.
 * @returns The resolved value, or `undefined` when a segment cannot be traversed.
 *
 * @example
 * ```ts
 * getKeyValue({ colorScheme: { darkMode: { background: '#000' } } }, 'color-scheme.dark_mode.background'); // '#000'
 * getKeyValue({ root: ({ severity }) => severity }, 'root', { severity: 'danger' }); // 'danger'
 * ```
 */
declare function getKeyValue<T extends Record<string, unknown>>(obj: T | undefined, key?: string, params?: unknown): unknown;

/**
 * Inserts `item` into `arr` so that `arr` stays ordered by each element's position in `sourceArr`. Mutates `arr` in
 * place; appends when no existing element ranks after `index`.
 *
 * @param item Item to insert.
 * @param index Position of `item` within `sourceArr`, used as its sort rank.
 * @param arr Ordered target array, mutated.
 * @param sourceArr Reference array defining the canonical order.
 *
 * @example
 * ```ts
 * const source = ['a', 'b', 'c'];
 * const target = ['a', 'c'];
 *
 * insertIntoOrderedArray('b', 1, target, source); // target === ['a', 'b', 'c']
 * ```
 */
declare function insertIntoOrderedArray<T>(item: T, index: number, arr: T[], sourceArr: T[]): void;

/**
 * Returns true when the value is an array; pass `empty` as `false` to also require at least one element.
 */
declare function isArray(value: unknown): value is unknown[];
declare function isArray(value: unknown, empty?: boolean): boolean;

/**
 * Returns true when the value is a `Date` instance, including invalid dates; cross-realm dates are not recognized.
 */
declare function isDate(value: unknown): value is Date;

/**
 * Returns true for `null`, `undefined`, `''`, an empty array, or any non-`Date` object with no own enumerable keys; `0` and `false` are not empty.
 */
declare function isEmpty(value: unknown): boolean;

/**
 * Returns true when the value is callable and exposes `call` and `apply`.
 */
declare function isFunction(value: unknown): value is (...args: unknown[]) => unknown;

/**
 * Returns true when the string is exactly one ASCII or Latin-1/Latin Extended-A letter (`A-Z`, `a-z`, `U+00C0`-`U+017F`).
 */
declare function isLetter(char: string): boolean;

/**
 * Negation of `isEmpty`.
 */
declare function isNotEmpty(value: unknown): boolean;

/**
 * Returns true when the value is non-empty and numeric after coercion, so numeric strings pass and `NaN` fails; this is not a `number` type check.
 */
declare function isNumber(value: unknown): boolean;

/**
 * Returns true only for plain objects built by `Object`, excluding arrays, class instances and null-prototype objects; pass `empty` as `false` to also require at least one key.
 */
declare function isObject(value: unknown, empty?: boolean): value is object;

/**
 * Returns true when the string is a single character that is either a space or a non-whitespace character, as used to detect type-ahead keystrokes.
 */
declare function isPrintableCharacter(char?: string): boolean;

/**
 * Returns true for a non-nullish `string`, `number`, `bigint` or `boolean`; symbols are not scalar.
 */
declare function isScalar(value: unknown): boolean;

/**
 * Returns true when the value is a string primitive; pass `empty` as `false` to reject `''`.
 */
declare function isString(value: unknown, empty?: boolean): value is string;

/**
 * Builds a string comparator bound to the runtime's default locale with numeric collation, so `'item2'` sorts before
 * `'item10'`. Prefer reusing the returned function over `String.prototype.localeCompare` when sorting large arrays.
 *
 * @returns Comparator suitable for `Array.prototype.sort`.
 */
declare function localeComparator(): (val1: string, val2: string) => number;

/**
 * Tests a string against a pattern, resetting `lastIndex` before and after so a sticky or global `regex` gives the same
 * result on every call.
 *
 * @param str String to test.
 * @param regex Pattern; when omitted the result is `false`.
 * @returns True when the pattern matches.
 */
declare function matchRegex(str: string, regex?: RegExp): boolean;

/**
 * @deprecated Use `deepMerge` instead.
 *
 * Merges multiple objects into one.
 * @param args Objects to merge.
 * @returns Merged object.
 */
declare function mergeKeys(...args: Record<string, unknown>[]): Record<string, unknown>;

/**
 * Strips comments and collapses insignificant whitespace around `{`, `}`, `:`, `;`, `,` and `!` in a CSS string. Quoted
 * strings are copied verbatim, including escaped quotes, so content and URLs survive intact.
 *
 * @param css CSS source. A nullish or empty input is returned unchanged.
 * @returns Minified CSS.
 */
declare function minifyCSS(css?: string): string | undefined;

/**
 * Flattens an object into the dot-separated paths of its leaves. Only plain objects are descended into, so arrays and
 * class instances count as leaves; an empty nested object contributes no path.
 *
 * @param obj Object to walk.
 * @param parentKey Prefix prepended to every produced path.
 * @returns Leaf paths, in key order.
 *
 * @example
 * ```ts
 * nestedKeys({ button: { root: { background: '#fff' }, tags: ['a'] } }); // ['button.root.background', 'button.tags']
 * ```
 */
declare function nestedKeys(obj?: Record<string, unknown>, parentKey?: string): string[];

/**
 * Shallow copy of a plain object without the given keys. Key arrays are flattened one level, so both `omit(o, 'a', 'b')`
 * and `omit(o, ['a', 'b'])` work. Non-plain-object inputs (arrays, class instances, primitives) are returned as-is.
 *
 * @param obj Source object.
 * @param keys Keys to drop.
 * @returns New object without `keys`.
 */
declare function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, ...keys: K[]): Omit<T, K>;
declare function omit(obj: unknown, ...keys: string[]): unknown;

/**
 * Replaces Latin-1 Supplement and Latin Extended-A accented characters with their unaccented equivalents, expanding
 * ligatures (`Æ` to `AE`, `œ` to `oe`). Strings without such characters are returned untouched after a single regex
 * test; the lookup tables are built once at module load.
 *
 * @param str String to normalize.
 * @returns String with accents removed.
 */
declare function removeAccents(str: string): string;

/**
 * Moves the element at `from` to `to`, mutating the array in place. When `to` is past the end, both indexes are wrapped
 * modulo the array length.
 *
 * @param value Array to reorder, mutated.
 * @param from Index of the element to move.
 * @param to Destination index.
 */
declare function reorderArray<T>(value: T[], from: number, to: number): void;

/**
 * Calls `obj` with `params` when it is a function, otherwise returns it unchanged.
 *
 * @param obj Value or factory function.
 * @param params Arguments forwarded when `obj` is callable.
 * @returns The function's return value, or `obj` itself.
 */
declare function resolve<P extends unknown[], R>(obj: (...params: P) => R, ...params: P): R;
declare function resolve<T>(obj: T, ...params: unknown[]): Exclude<T, (...args: never[]) => unknown>;

/**
 * Reads a value out of a data object by field name, dot-separated path, or accessor function.
 *
 * A direct property lookup is attempted first and wins whenever it yields a non-empty value, so a literal key
 * containing dots takes precedence over path traversal. Returns `null` when `data` or `field` is falsy, when `data` has
 * no own keys, or when traversal hits a nullish intermediate value.
 *
 * @param data Object to read from.
 * @param field Property name, dot-separated path, or a function invoked with `data`.
 * @returns The resolved value, or `null`.
 *
 * @example
 * ```ts
 * resolveFieldData({ user: { name: 'Ada' } }, 'user.name'); // 'Ada'
 * resolveFieldData({ 'user.name': 'Grace', user: { name: 'Ada' } }, 'user.name'); // 'Grace'
 * resolveFieldData({ first: 'Ada', last: 'L' }, (d) => `${d.first} ${d.last}`); // 'Ada L'
 * ```
 */
declare function resolveFieldData(data: any, field: any): any;

/**
 * Shallow equal for React/Vue props comparison
 * Ignores functions (common in props)
 */
declare function shallowEqualProps(propsA: Record<string, unknown>, propsB: Record<string, unknown>): boolean;

/**
 * Checks if two values are shallowly equal
 * - Primitives: compared by value (===)
 * - Objects/Arrays: compared by reference and first-level properties
 *
 * @param objA First value to compare
 * @param objB Second value to compare
 * @returns True if values are shallowly equal, false otherwise
 *
 * @example
 * shallowEquals(1, 1) // true
 * shallowEquals('a', 'a') // true
 * shallowEquals({ a: 1 }, { a: 1 }) // true (shallow)
 * shallowEquals({ a: { b: 1 } }, { a: { b: 1 } }) // false (nested objects are different references)
 * shallowEquals([1, 2], [1, 2]) // true (shallow)
 * shallowEquals([1, [2]], [1, [2]]) // false (nested arrays are different references)
 */
declare function shallowEquals(objA: unknown, objB: unknown): boolean;

/**
 * Comparator wrapping `compare` that applies a separate sort direction to empty values.
 *
 * @param value1 Left value.
 * @param value2 Right value.
 * @param order Sort direction for non-empty values. Defaults to `1`.
 * @param comparator String comparator, typically from `localeComparator`.
 * @param nullSortOrder Direction applied when either value is empty. `1` keeps the Excel-style behavior of sorting empty values last regardless of `order`; any other value overrides `order` outright. Defaults to `1`.
 * @returns Negative, zero or positive ordering result.
 */
declare function sort<T>(value1: T, value2: T, order: number | undefined, comparator: (val1: T, val2: T) => number, nullSortOrder?: number): number;

/**
 * Serializes a value to a readable, JavaScript-like string: plain objects are expanded over multiple indented lines,
 * arrays stay on one line, dates become ISO strings and functions are emitted as source. Anything else falls through to
 * `JSON.stringify`, so cyclic inputs throw.
 *
 * @param value Value to serialize.
 * @param indent Spaces added per nesting level. Defaults to `2`.
 * @param currentIndent Starting indentation, used by the recursive calls. Defaults to `0`.
 * @returns Serialized representation.
 */
declare function stringify(value: unknown, indent?: number, currentIndent?: number): string;

/**
 * Converts kebab-case and snake_case to camelCase by removing each `-`/`_` and upper-casing the character after it. The
 * first character is left as-is, so PascalCase input stays PascalCase. Non-string input is returned unchanged.
 *
 * @param str String to convert.
 * @returns Converted string.
 */
declare function toCamelCase(str: string): string;

/**
 * Upper-cases the first character and leaves the rest untouched. Empty and non-string input is returned unchanged.
 *
 * @param str String to capitalize.
 * @returns Capitalized string.
 */
declare function toCapitalCase(str: string): string;

/**
 * Normalizes kebab-case, snake_case, camelCase and PascalCase to flat lowercase by stripping `-`/`_` and lower-casing.
 * Used to compare keys case- and separator-insensitively. Non-string input is returned unchanged.
 *
 * @param str String to convert.
 * @returns Flattened string.
 */
declare function toFlatCase(str: string): string;

/**
 * Converts snake_case, camelCase and PascalCase to kebab-case: `_` becomes `-`, a hyphen is inserted at each
 * lower-to-upper boundary, and the result is lower-cased. Consecutive capitals are not split. Non-string input is
 * returned unchanged.
 *
 * @param str String to convert.
 * @returns Kebab-cased string.
 */
declare function toKebabCase(str: string): string;

/**
 * Parses a CSS time value into milliseconds. Values ending in `ms` are taken as-is, everything else is treated as
 * seconds and multiplied by 1000. Commas are read as decimal separators, so `'0,3s'` yields `300`. `'auto'` yields `0`,
 * and numbers pass through unchanged.
 *
 * @param value CSS duration such as `'150ms'`, `'0.3s'` or `'auto'`, or a number already in milliseconds.
 * @returns Duration in milliseconds, or `NaN` when no digits are present.
 */
declare function toMs(value: string | number): number;

/**
 * Converts a camelCase property name to a dot-separated design token path, inserting a `.` before each capital except a
 * leading one, then lower-casing. Non-string input is returned unchanged.
 *
 * @param str Property name such as `hoverBackground`.
 * @returns Token key such as `hover.background`.
 */
declare function toTokenKey(str: string): string;

/**
 * Resolves the underlying value from various wrapper patterns
 * Supports React refs, Vue refs, Lit directives, Angular signals, and direct values/functions
 * @param value The value to resolve
 */
declare function toValue(value: unknown): unknown;

export { compare, contains, deepEquals, deepMerge, equals, filter, findIndexInList, findLast, findLastIndex, getKeyValue, insertIntoOrderedArray, isArray, isDate, isEmpty, isFunction, isLetter, isNotEmpty, isNumber, isObject, isPrintableCharacter, isScalar, isString, localeComparator, matchRegex, mergeKeys, minifyCSS, nestedKeys, omit, removeAccents, reorderArray, resolve, resolveFieldData, shallowEqualProps, shallowEquals, sort, stringify, toCamelCase, toCapitalCase, toFlatCase, toKebabCase, toMs, toTokenKey, toValue };