@ui0/util 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,771 @@
+import { CSSModuleClassList, CSSUnit, Indexed, MaybeUnits, Numberish, RgbTuple, StyleList, Ui0Core } from "@ui0/types";
+import { App, AppContext } from "vue";
+/**
+ * Omit values from arr based on values list and return new array with this values
+ * @param {T[]} arr
+ * @param {T[]} omitted
+ * @return {T[]}
+ */
+export declare function arrayOmit<T, U extends T>(arr: readonly T[] | null | undefined, omitted?: U[] | null): OmitValues<T, U>[];
+type OmitValues<T, U> = T extends U ? never : T;
+/**
+ * Omit values from arr based on values list
+ * Mutable version of arrayOmit
+ * @param {T[]} arr
+ * @param {T[]} omitted
+
+ */
+export declare function arrayOmitArray<T>(arr: readonly T[] | undefined, omitted: T[]): void;
+/**
+ * Make this array items unique
+ * [1,2,3,3,2,5] => [1,2,3,5]
+ * @param {T[]} arr
+ * @return {T[]}
+ */
+export declare function toUnique<T>(arr: T[]): T[];
+/**
+ * Return the last element of an array.
+ *
+ * @param arr - the array to read
+ * @returns the last item, or `undefined` for an empty array
+ */
+export declare function getLastItemFromArray<T = unknown>(arr: T[]): T;
+/**
+ * Pick element with offset from item's position in arr
+ * Next item - +1
+ * Prev item - -1
+ * returns same item if not found
+ * @param {T[]} arr
+ * @param {T} item
+ * @param {number} offset
+ * @return {T}
+ */
+export declare function arrayPickFromItemOffset<T>(arr: T[], item: T, offset: number): T;
+/**
+ * Pick the element `offset` positions after `item`.
+ *
+ * Thin wrapper over {@link arrayPickFromItemOffset} with a positive offset;
+ * out-of-range offsets and unknown items return `item` itself.
+ *
+ * @param arr - the array to walk
+ * @param item - the anchor element
+ * @param offset - how many positions to move forward, defaults to `1`
+ * @returns the neighbor element, or `item`
+ */
+export declare function arrayPickNext<T>(arr: T[], item: T, offset?: number): T;
+/**
+ * Pick the element `offset` positions before `item`.
+ *
+ * Thin wrapper over {@link arrayPickFromItemOffset} with a negative offset;
+ * out-of-range offsets and unknown items return `item` itself.
+ *
+ * @param arr - the array to walk
+ * @param item - the anchor element
+ * @param offset - how many positions to move back, defaults to `1`
+ * @returns the neighbor element, or `item`
+ */
+export declare function arrayPickPrev<T>(arr: T[], item: T, offset?: number): T;
+/**
+ * get item from array when iterating over length
+ * getItemByOverflowIndex([0,1,2,3], 8) // => 1 ([0,1,2,3], 6) => 3
+ *
+ * @param {T[]} arr
+ * @param {number} index
+ * @param offset takes inc/dec by offset value,
+ * @default 1
+ * @return {T}
+ */
+export declare function getItemByOverflowIndex<T = unknown>(arr: T[], index: number, offset?: number): T;
+/**
+ * Coerce every element of an array to a number.
+ *
+ * Nullish entries become `0`; non-numeric strings coerce to `NaN`.
+ *
+ * @param arr - the source array
+ * @returns a parallel array of numbers
+ */
+export declare function arrayToNumberArray(arr: Array<any>): Array<number>;
+/**
+ * Compare two arrays item by item, recursing into nested arrays.
+ *
+ * @param a - the first array
+ * @param b - the second array
+ * @returns `true` when the lengths match and every pair is `===` (nested
+ *   arrays compared recursively)
+ */
+export declare function arrayIsEqual<T>(a: T[], b: T[]): boolean;
+/**
+ * insert `items` to array at specific `index`
+ * delete `deleteCount` items from `index`
+ * @param arr
+ * @param index
+ * @param items
+ * @param deleteCount
+ */
+export declare function arrayInsertAtIndex<T>(arr: T[], index: number, items: T[], deleteCount?: number): void;
+/**
+ * Type guard: value is an array.
+ *
+ * @param value - the value to check
+ * @returns `true` when `value` is an array
+ */
+export declare function isArray<T>(value: unknown): value is T[];
+/**
+ * Pick keys from object to new object with key-value
+ *
+ * @param {T} obj
+ * @param keys
+ * @example objectPickKeys({key1: true, key2: 0, key3: 'str'}, 'key2', 'key3') // {key2: 0, key3: 'str'}
+ * @return {{[P in keyof T]?: any}}
+ */
+export declare function objectPickKeys<T extends Record<string, any>, P extends keyof T>(obj: T, ...keys: P[]): Pick<T, P>;
+/**
+ * Opposite to objectPickKeys
+ * Return new object without selected keys
+ * @param {T} obj
+ * @param {P} args
+ * @example objectOmitKeys({key1: true, key2: 0, key3: 'str'}, 'key2', 'key3') // {key1: true}
+ * @return {{[P in keyof T]?: any}}
+ */
+export declare function objectOmitKeys<T extends Record<string | symbol | number, any>, P extends keyof T>(obj: T, ...args: P[]): Omit<T, P>;
+/**
+ * Objects customizable deep merging
+ * @param {Record<string, any>} to
+ * @param {Record<string, any>} from
+ * @param {{replaceNonObjectIfObject: boolean}} options
+ * @return {Record<string, any>}
+ */
+export declare function objectMerge<T, Y>(to: T, from: Y, options?: {
+  replaceNonObjectIfObject?: boolean;
+  /**
+   * Merge all functions into single function
+   * @default false
+   */
+  mergeFunctions?: boolean;
+  overwrite?: boolean;
+}): T & Y;
+/**
+ * Type guard: value is an object (not `null`, not an array).
+ *
+ * @param v - the value to check
+ * @returns `true` for non-null, non-array objects
+ */
+export declare function isObject(v: any): v is Record<string, any>;
+/**
+ * Replace `undefined` with `false`, keeping any other value as-is.
+ *
+ * @param x - the value to guard
+ * @returns `x`, or `false` when `x` is `undefined`
+ */
+export declare function notUndefined(x: unknown): {} | null;
+/**
+ * Type guard: value is a function (anything callable).
+ *
+ * @param fn - the value to check
+ * @returns `true` when `fn` is callable
+ */
+export declare const isFunction: (fn: unknown) => fn is Function;
+/**
+ * Type guard: value is a symbol.
+ *
+ * @param s - the value to check
+ * @returns `true` when `s` is a symbol
+ */
+export declare const isSymbol: (s: unknown) => s is symbol;
+/**
+ * Convert CaseWordAAA to 'case-word-a-a-a'
+ * @param {string} str
+ * @return {string}
+ */
+export declare function hyphenate(str: string): string;
+/**
+ * Converts `is-name` to 'isName'
+ * @param s
+ */
+export declare function toCamelCase(s?: string): string;
+/**
+ * Converts string to kebab-case (including spaces).
+ * @example
+ * toKebabCase('Hello World') => 'hello-world'
+ * toKebabCase('camelCase') => 'camel-case'
+ */
+export declare function toKebabCase(str: string): string;
+/**
+ * Convert a kebab-case string to PascalCase (`'is-name'` → `'IsName'`).
+ *
+ * @param s - the kebab-case input
+ * @returns the PascalCase string
+ */
+export declare function toPascalCase(s?: string): string;
+/**
+ * Kebab-case a string, collapsing uppercase runs as whole words.
+ *
+ * Unlike {@link toKebabCase} (which only splits on lower→upper edges),
+ * consecutive capitals collapse together: `'FOOBar'` → `'foo-bar'`,
+ * `'XMLHttpRequest'` → `'xml-http-request'`.
+ *
+ * @param str - the string to kebab-case
+ * @returns the kebab-cased string
+ */
+export declare function kebabize(str: string): string;
+/**
+ * Remove vowels form word
+ * @param {string} str
+ * @example  removeVowels('hello world') // hll wrld
+ * @return {string}
+ */
+export declare function removeVowels(str: string): string;
+/**
+ * returns filename from a path
+ * @param {string} name
+ * @example  extractFileName('/some/path/to/file.txt') // file.txt
+ * @return {string | undefined}
+ */
+export declare function extractFileName(name: string): string | undefined;
+/**
+ * Return the directory part of a path — everything before the file name.
+ *
+ * @param file - the path to split
+ * @returns the trailing-slash directory, or `''` when the path has none
+ */
+export declare function extractFileDir(file: string): string;
+/**
+ * process pack/icon?value=123 to {params: {value: 123}, res: ['pack', 'icon']}
+ * @param query
+ */
+export declare function parseQueryString(query: string): {
+  params: Record<string, boolean | string | number | string[]>;
+  res: string[];
+};
+/**
+ * convert 'some content here' to 'sch'
+ * @param {string} str
+ * @return {string}
+ */
+export declare function stringToFirstLetters(str: string): string;
+/**
+ * Generate random  string (a-z 0-9) with specific len
+ *
+ * @param {number} len  6 by default
+ * @default 6
+ * @return {string}
+ */
+export declare function genRandomString(len?: number): string;
+/**
+ * Typed String.split() wrapper
+ * @param input
+ * @param separator
+ */
+export declare function splitString<U extends string, Y extends string = ','>(input: `${U}${'' | `${Y}${U}`}` | U[], separator: RegExp | string): U[];
+/**
+ * typeof guard
+ */
+export declare function isString(v?: unknown): v is string;
+/**
+ * retrieve instance of a any framework plugin from vue instance if exists
+ * @param app
+ * @param name
+ */
+export declare function findFrameworkInstance<T = Ui0Core>(app: App | AppContext, name: string): T | undefined;
+/**
+ * Merge two CSS-module class maps, the second winning on key conflicts.
+ *
+ * Mirrors how a component's own local `$style` overrides the class map
+ * shipped by a contract.
+ *
+ * @param $from - the base map (e.g. the contract's shipped classes)
+ * @param $to - the overriding map (e.g. the component's local `$style`)
+ * @returns the merged class map
+ */
+export declare function mergeCssModulesStyles($from?: CSSModuleClassList, $to?: CSSModuleClassList): {
+  [x: string]: string;
+};
+/**
+ * Floor the mantissa of a number's scientific notation after shifting its
+ * exponent by `-exp`, then shift the exponent back.
+ *
+ * Operates on the printed `toString()` digits rather than on decimal
+ * places: `decimalAdjust(0, 2.7)` → `2`, `decimalAdjust(2, 123.456)` →
+ * `100`. A non-integer `exp` or a non-numeric `value` yields `NaN`.
+ *
+ * @param exp - the decimal exponent shift (integer)
+ * @param value - the number to adjust
+ * @returns the adjusted number
+ */
+export declare function decimalAdjust(exp: number, value: number): number;
+/**
+ * Extract the exponent of a number's scientific-notation form.
+ *
+ * `123.456` → `2` (`1.23456e+2`), `0.00123` → `-3` (`1.23e-3`).
+ *
+ * @param num - the number to inspect
+ * @returns the decimal exponent as a signed number
+ */
+export declare function exponentialToNumber(num: number): number;
+/**
+ * Tell floats from integers.
+ *
+ * @param n - the number to check
+ * @returns `true` when `n` has a non-zero fractional part
+ */
+export declare function isFloat(n: number): boolean;
+/**
+ * Count the digits after the decimal point.
+ *
+ * @param int - the (float) number to inspect
+ * @returns the number of fractional digits; `0` for integers
+ */
+export declare function getFloatDigitsCount(int: number): number;
+/**
+ * Type guard: value is a number or a string coercible to one.
+ *
+ * Coercion follows `+v` — numeric strings pass, non-numeric ones don't.
+ *
+ * @param v - the value to check
+ * @returns `true` when `v` is a string/number and `+v` is not `NaN`
+ */
+export declare function isNumberish(v?: Numberish): v is number;
+/**
+ * Strict numeric-validity check: real, finite, non-`NaN` numbers — and
+ * numeric strings that aren't blank.
+ *
+ * @param val - the value to check
+ * @returns `true` only for genuine numeric values
+ */
+export declare function isValidNumber(val: unknown): boolean;
+/**
+ * Coerce a number-ish value with `+val`.
+ *
+ * @param val - the value to coerce; `undefined` falls back to `def`
+ * @param def - the default for `undefined`, defaults to `0`
+ * @returns the coerced number, `def` for `undefined`, or `NaN` when `val`
+ *   coerces to `NaN` (no validation is applied)
+ */
+export declare function numberCast(val: number | string | undefined, def?: number): number;
+/**
+ * Clamp a number into the inclusive `[min, max]` range.
+ *
+ * @param value - the number to clamp
+ * @param min - the lower bound
+ * @param max - the upper bound
+ * @returns the bounded value
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Parse a CSS time literal into milliseconds.
+ *
+ * Accepts the two CSS time units: `<number>s` and `<number>ms`. Anything
+ * that doesn't match the `value + unit` shape — unitless numbers, other
+ * units, arbitrary strings — returns `0`, mirroring an unset duration.
+ *
+ * @param cssTime - a CSS time literal, e.g. `'300ms'`, `'2.5s'`
+ * @returns the time in milliseconds (`'2.5s'` → `2500`), or `0` when invalid
+ */
+export declare function parseCssTime(cssTime: string): number;
+/**
+ * Append a CSS unit to a unitless value.
+ *
+ * Numbers and numeric strings get `units` appended (`20` → `'20px'`,
+ * `'2.5'` → `'2.5px'`). Anything else — strings that already carry a unit
+ * or a keyword (`'20em'`, `'auto'`), `undefined` — returns an empty string;
+ * use {@link tryToUnits} when the original value should survive.
+ *
+ * @param val - a number or a numeric string
+ * @param units - the unit to append, defaults to `'px'`
+ * @returns the value with the unit attached, or `''` when `val` is not
+ *   unitless-numeric
+ */
+export declare function toUnits(val: MaybeUnits, units?: CSSUnit): string;
+/**
+ * Like {@link toUnits}, but passes non-numeric values through untouched.
+ *
+ * Numberish input gets the unit appended (`20` → `'20px'`); strings that
+ * already read as CSS (`'20em'`, `'auto'`) are returned as-is; `undefined`
+ * collapses to `'0'` so an omitted value never leaks into a style
+ * declaration.
+ *
+ * @param val - a number, a numeric string, or any other CSS value
+ * @param units - the unit for numberish input, defaults to `'px'`
+ * @returns the unit-bearing value, the original string, or `'0'`
+ */
+export declare function tryToUnits(val: MaybeUnits, units?: CSSUnit): string;
+/**
+ * Serialize a style object into an inline CSS declaration string.
+ *
+ * camelCase keys are kebab-cased (`zIndex` → `z-index`, an initial capital
+ * becomes a vendor prefix: `WebkitBackdropFilter` → `-webkit-backdrop-filter`),
+ * each pair becomes `key:value;` and pairs are concatenated without
+ * separators — the result targets a single `style` attribute or a css-in-js
+ * template, not pretty printing.
+ *
+ * @param obj - the style object (`StyleList` / any plain record)
+ * @returns the declaration string, e.g. `'width:20px;z-index:2;'`
+ */
+export declare function objectToCss(obj: StyleList): string;
+/**
+ * convert 123px to {value:  123, units: 'px'}
+ * @param {string} str
+ * @return {{units: string, value: number}}
+ */
+export declare function parseUnits(str?: string): {
+  value: number;
+  units: CSSUnit;
+  calc: string;
+};
+/**
+ * Build the error a composable throws when it is called outside of a
+ * component's setup or lifecycle hooks.
+ *
+ * @param funcName - the composable's name for the message
+ * @returns the ready `Error` instance
+ */
+export declare function newErrorForSetupCall(funcName: string): Error;
+/**
+ * Build a core-prefixed framework error (`[core]: <msg>`).
+ *
+ * @param msg - the error detail
+ * @returns the ready `Error` instance
+ */
+export declare function newFrameworkError(msg: string): Error;
+/**
+ * Build the error thrown when an app is requested by a name nothing
+ * registered under.
+ *
+ * @param data - the missing app's name
+ * @returns the ready `Error` instance
+ */
+export declare function newErrorAppNotFound(data: string): Error;
+/**
+ * Build the error thrown when an app name is registered twice.
+ *
+ * @param data - the duplicated app's name
+ * @returns the ready `Error` instance
+ */
+export declare function newErrorAppExists(data: string): Error;
+/**
+ * Build the error `useApp` throws when no app context is active.
+ *
+ * @returns the ready `Error` instance
+ */
+export declare function newErrorUseAppCall(): Error;
+/**
+ * SHA-256 of a string as a lowercase hex digest.
+ *
+ * Pure JS implementation (FIPS 180-4) — runs identically in the browser
+ * and in Node, so generated class-name hashes can be computed at runtime
+ * on either side without `node:crypto`.
+ *
+ * @param message - the string to hash (UTF-8 encoded)
+ * @returns the 64-character hex digest
+ */
+export declare function sha256hex(message: string): string;
+/** color space the ramp math runs in - perceptual `oklch` or legacy `hsl` */
+export type ColorSpace = 'hsl' | 'oklch';
+/**
+ * Parse a CSS hex color into an sRGB triple.
+ *
+ * Accepts the long (`#rrggbb`) and short (`#rgb`) forms, with or without
+ * the leading `#`.
+ *
+ * @param hex - the hex literal, e.g. `'#16e3c5'`, `'f00'`
+ * @returns `[r, g, b]` with integer channels 0-255
+ */
+export declare function hexToRgb(hex: string): RgbTuple;
+/**
+ * Extract the RGB channels from an `rgb()` / `rgba()` string.
+ *
+ * Handles the legacy comma syntax (`rgb(1, 2, 3)`) and the modern space
+ * syntax with alpha (`rgb(1 2 3 / .5)`); the alpha component is dropped.
+ *
+ * @param s - the CSS color function string
+ * @returns `[r, g, b]` as parsed (fractional for decimals/percentages)
+ */
+export declare function parseRgbString(s: string): RgbTuple;
+/**
+ * The CSS named colors (CSS Color Module Level 4) as sRGB triples,
+ * keyed by lowercase name.
+ */
+export declare const NAMED_COLORS: Record<string, RgbTuple>;
+/**
+ * Tell literal CSS colors from palette references.
+ *
+ * Literal means the string is a color by itself: `#hex`, `rgb(...)` /
+ * `rgba(...)`, or a CSS named color (case-insensitive) — as opposed to
+ * theme references like `'brand-l2'`.
+ *
+ * @param s - the color string to classify
+ * @returns `true` when `s` is directly usable as a CSS color value
+ */
+export declare function isLiteralColor(s: string): boolean;
+/**
+ * Resolve any literal CSS color string to an sRGB triple.
+ *
+ * Dispatches on the format: `#hex` → {@link hexToRgb}, `rgb(...)` →
+ * {@link parseRgbString}, anything else is looked up among the CSS named
+ * colors (case-insensitive). Theme references are rejected.
+ *
+ * @param color - a literal color string
+ * @returns the sRGB triple
+ * @throws when `color` is not a literal color (e.g. a palette reference)
+ */
+export declare function toRgb(color: string): RgbTuple;
+/**
+ * Convert an sRGB triple to HSL.
+ *
+ * @param rgb - the color (channels 0-255)
+ * @returns `[hue 0-360, saturation 0-100, lightness 0-100]` (fractional)
+ */
+export declare function rgbToHsl([r, g, b]: RgbTuple): [number, number, number];
+/**
+ * Convert an HSL triple to a fractional sRGB triple.
+ *
+ * @param hsl - `[hue 0-360, saturation 0-100, lightness 0-100]`
+ * @returns fractional sRGB channels (0-255, not rounded)
+ */
+export declare function hslToRgb([h, s, l]: [number, number, number]): RgbTuple;
+/**
+ * Rebuild a color with a new HSL lightness, keeping hue and saturation.
+ *
+ * @param rgb - the source color (sRGB triple)
+ * @param l - the target lightness, percent 0-100
+ * @returns the recolored sRGB triple (fractional channels)
+ */
+export declare function withLightnessHsl(rgb: RgbTuple, l: number): RgbTuple;
+/**
+ * Read the HSL lightness (percent, 0-100) of an sRGB color.
+ *
+ * @param rgb - the color to measure (sRGB triple)
+ * @returns the lightness percentage (fractional)
+ */
+export declare function lightnessOfHsl(rgb: RgbTuple): number;
+/**
+ * Decode one gamma-encoded sRGB channel to linear light.
+ *
+ * @param v - the sRGB channel, 0-255
+ * @returns the linear-light value (0-1)
+ */
+export declare function srgbToLinear(v: number): number;
+/**
+ * Gamma-encode one linear-light channel to sRGB.
+ *
+ * @param v - the linear channel, nominally 0-1
+ * @returns the sRGB channel, 0-255, clamped to the gamut
+ */
+export declare function linearToSrgb(v: number): number;
+/**
+ * Convert a linear-light sRGB triple to OKLab.
+ *
+ * Björn Ottosson's LMS-based transform; the input must be linear (run
+ * {@link srgbToLinear} over gamma-encoded channels first).
+ *
+ * @param rgb - linear sRGB channels (0-1)
+ * @returns `[L, a, b]` OKLab coordinates
+ */
+export declare function linearRgbToOklab([r, g, b]: RgbTuple): [number, number, number];
+/**
+ * Convert OKLab coordinates back to a linear-light sRGB triple.
+ *
+ * Inverse of {@link linearRgbToOklab}; run {@link linearToSrgb} over the
+ * result to get gamma-encoded channels.
+ *
+ * @param L - OKLab lightness
+ * @param a - green-red opponent channel
+ * @param b - blue-yellow opponent channel
+ * @returns linear sRGB channels (0-1)
+ */
+export declare function oklabToLinearRgb([L, a, b]: [number, number, number]): RgbTuple;
+/**
+ * Convert an sRGB triple to OKLCH (via linear sRGB + OKLab).
+ *
+ * @param rgb - the color (channels 0-255)
+ * @returns `[L 0-100, C, H degrees]` (fractional)
+ */
+export declare function rgbToOklch(rgb: RgbTuple): [number, number, number];
+/**
+ * Convert OKLCH coordinates to a gamma-encoded sRGB triple.
+ *
+ * @param L100 - lightness in percent (0-100)
+ * @param C - chroma
+ * @param H - hue in degrees
+ * @returns the sRGB triple (channels 0-255, fractional)
+ */
+export declare function oklchToRgb([L100, C, H]: [number, number, number]): RgbTuple;
+/**
+ * Rebuild a color with a new OKLCH lightness, keeping chroma and hue.
+ *
+ * @param rgb - the source color (sRGB triple)
+ * @param l - the target lightness, percent 0-100
+ * @returns the recolored sRGB triple (fractional channels)
+ */
+export declare function withLightnessOklch(rgb: RgbTuple, l: number): RgbTuple;
+/**
+ * Read the OKLCH lightness (percent, 0-100) of an sRGB color.
+ *
+ * @param rgb - the color to measure (sRGB triple)
+ * @returns the OKLCH L dimension (fractional)
+ */
+export declare function lightnessOfOklch(rgb: RgbTuple): number;
+/**
+ * The color spaces the ramp math (`lighten` / `darken`) can run in.
+ *
+ * `oklch` is perceptually uniform — a ramp looks evenly spaced regardless
+ * of hue; `hsl` is the legacy (cheaper) path.
+ */
+export declare const SPACES: Record<ColorSpace, {
+  lightnessOf: (rgb: RgbTuple) => number;
+  withLightness: (rgb: RgbTuple, l: number) => RgbTuple;
+}>;
+/**
+ * Lighten a color by `step` steps of a `steps`-step ramp.
+ *
+ * Scales the color's lightness up toward 100 percent proportionally
+ * (`l -> l + (100 - l) * (step / steps)`) in the given color space;
+ * `oklch` keeps ramps perceptually even, `hsl` is the legacy path.
+ *
+ * @param rgb - the color to lighten (sRGB triple)
+ * @param step - how many steps up the ramp (1-based)
+ * @param steps - the total number of ramp steps
+ * @param space - the color space the lightness math runs in
+ * @returns the lightened color (fractional channels)
+ */
+export declare function lighten(rgb: RgbTuple, step: number, steps: number, space?: ColorSpace): RgbTuple;
+/**
+ * Darken a color by `step` steps of a `steps`-step ramp.
+ *
+ * Scales the color's lightness down proportionally
+ * (`l -> l * (1 - step / steps)`) in the given color space; `oklch` keeps
+ * ramps perceptually even, `hsl` is the legacy path.
+ *
+ * @param rgb - the color to darken (sRGB triple)
+ * @param step - how many steps down the ramp (1-based)
+ * @param steps - the total number of ramp steps
+ * @param space - the color space the lightness math runs in
+ * @returns the darkened color (fractional channels)
+ */
+export declare function darken(rgb: RgbTuple, step: number, steps: number, space?: ColorSpace): RgbTuple;
+/**
+ * Mix two sRGB colors by a depth percentage.
+ *
+ * Linear interpolation per channel: `depthPercent` of 0 returns `rgb1`
+ * untouched, 100 returns `rgb2`; the channels stay fractional (not
+ * rounded).
+ *
+ * @param rgb1 - the base color (sRGB triple, channels 0-255)
+ * @param rgb2 - the color blended in
+ * @param depthPercent - blend weight of `rgb2`, 0-100
+ * @returns the mixed color as a fractional sRGB triple
+ */
+export declare function blend(rgb1: RgbTuple, rgb2: RgbTuple, depthPercent: number): RgbTuple;
+/**
+ * A prop-to-class mapping entry: either a bare prop name (the prop's own
+ * value drives the emitted classes) or a `[propName, modifiers]` tuple that
+ * maps the prop's value tokens onto modifier classes.
+ */
+type PropClassImpl<T = Record<string, unknown>> = keyof T | [keyof T, Indexed];
+/**
+ * Coerces an arbitrary prop value to a boolean the way presence-classes
+ * expect it: an empty string means "present" (`true`), an empty array means
+ * "absent" (`false`), anything else falls through to the default truthiness
+ * rules.
+ * @param value - the prop value
+ * @returns the boolean presence of the value
+ */
+export declare function castAnyPropToBoolean(value: any): boolean;
+/**
+ * Builds a `{ [className]: true }` record from a list of state names,
+ * keeping only the names whose prop value is "on" (defined, not `false`
+ * and not a function).
+ * @param names - space-separated string, list, or map of state names
+ * @param props - the props to test each name against
+ * @param className - prefix joined with `_` to each name; empty = bare name
+ * @param debug - log the inputs before computing
+ * @returns record of `className_name -> true` for the active names
+ */
+export declare function namesToClassNames(names: string | string[], props?: Record<string, any>, className?: string, debug?: boolean): any;
+/**
+ * Converts a prop value to a class via a value -> class alias record: the
+ * alias may be a single class name or a list of class names.
+ * @param propValue - the prop's value token
+ * @param values - record of value token -> class alias (string or string[])
+ * @returns `{ className: true }` for the aliased class(es), `{}` when the
+ * value has no alias or the alias is neither a string nor a list
+ */
+export declare function propValueToClass<Prop extends string>(propValue: Prop, values: Indexed): Indexed;
+/**
+ * Converts a prop value to class names via a value -> class alias record:
+ * the alias may be a single class name or a list of class names.
+ * @param propValue - the prop's value token
+ * @param values - record of value token -> class alias (string or string[])
+ * @returns the aliased class name list, `[]` when the value has no alias or
+ * the alias is neither a string nor a list
+ */
+export declare function propValueToClasses<Prop extends string>(propValue: Prop, values: Indexed): string[];
+/**
+ * Converts prop names and values to css-module classes, returned as a
+ * `{ [className]: boolean }` record (a `false` entry means the prop is off
+ * but the class slot is still reported).
+ *
+ * A picked entry is either a bare prop name - the prop's own class is keyed
+ * by the css module and the value's tokens add their own module classes - or
+ * a `[propName, modifiers]` tuple that maps the value's tokens onto modifier
+ * classes via {@link propValueToClass}.
+ * @param props - the instance props
+ * @param picked - the props to map (bare names or `[name, modifiers]` tuples)
+ * @param cssModule - the css-module class map
+ * @returns record of class name -> on/off flag
+ */
+export declare function propsToCssModuleClass<Props extends Indexed, PropName extends PropClassImpl<Props>>(props: Props, picked: PropName[], cssModule: CSSModuleClassList): Indexed<boolean>;
+/**
+ * Converts prop names and values to a flat list of css-module classes -
+ * the array form of {@link propsToCssModuleClass}: same mapping rules, but
+ * only the "on" classes are collected (no `false` entries) and an extra
+ * class can be prepended via `options.extraClass`.
+ * @param props - the instance props
+ * @param picked - the props to map (bare names or `[name, modifiers]` tuples)
+ * @param cssModule - the css-module class map
+ * @param options - `extraClass` is prepended to the result when given
+ * @returns the resolved class name list
+ */
+export declare function propsToCssModuleClassNext<Props extends Indexed, PropName extends PropClassImpl<Props>>(props: Props, picked: PropName[], cssModule: CSSModuleClassList, options?: {
+  extraClass?: string;
+}): string[];
+export declare const isBrowser: boolean;
+export declare function safetyWindow(): {};
+export declare function safetyDocument(): {};
+interface RecordContainerImpl<T> {
+  items: T[];
+  length: number;
+  clear: () => void;
+  add: (item: T) => number;
+  remove: (id: number) => void;
+  getItemById: (id: number) => T | undefined;
+}
+interface StackOptions<T> {
+  /** Transforms an accepted item before insertion; does not run on removal or clear. */
+  onChange?: (v: T) => T;
+  /** Rejects an item when returning false, without consuming an ID. */
+  onBeforeChange?: (v: T) => boolean;
+}
+export declare class RecordContainer<T> implements RecordContainerImpl<T> {
+  private readonly records;
+  private counter;
+  private options;
+  constructor(options?: StackOptions<T>);
+  /** Returns the item with the highest remaining ID, or undefined when empty. */
+  get last(): T | undefined;
+  /** Returns a shallow snapshot; item objects retain their original references. */
+  get raw(): {
+    [index: number]: T;
+  };
+  get items(): T[];
+  get length(): number;
+  clear(): void;
+  /** Validates and transforms an item before allocating its ID; returns -1 on rejection. */
+  add(item: T): number;
+  remove(id: number): void;
+  getItemById(id: number): T;
+}
+export declare function getClientHeight(): number;
+export declare function getClientWidth(): number;
+export type { PropClassImpl, RecordContainerImpl, StackOptions };
+//# sourceMappingURL=index.d.ts.map