import { Observable } from 'rxjs';

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/**
 * Represents a value that may be absent.
 *
 * Preferred over inline `T | null | undefined` unions for consistency
 * across the codebase and to reduce repetition in public API signatures.
 *
 * @example
 * ```ts
 * function findUser(id: string): Maybe<User> {
 *   return db.get(id) ?? null;
 * }
 *
 * const user: Maybe<User> = findUser('42');
 *
 * if (isDefined(user)) {
 *   // user is User
 * }
 * ```
 *
 * @see {@link isDefined} — type guard that narrows `Maybe<T>` to `T`.
 */
type Maybe<T> = T | null | undefined;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/**
 * Explicitly untyped value.
 *
 * Use in places where `any` is intentional and unavoidable,
 * such as generic wrappers around third-party APIs that do not
 * expose precise types.
 *
 * Prefer narrowing to a concrete type whenever possible.
 *
 * @example
 * ```ts
 * function wrapThirdPartyCallback(fn: (...args: SafeAny[]) => SafeAny): void {
 *   // ...
 * }
 * ```
 */
type SafeAny = any;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */

/**
 * Type guard that checks if a value is neither `null` nor `undefined`.
 *
 * @example
 * ```ts
 * const maybeValue: Maybe<number> = getValue();
 *
 * if (isDefined(maybeValue)) {
 *   // here maybeValue is number
 *   console.log(maybeValue.toFixed(2));
 * }
 * ```
 *
 * @see {@link Maybe}
 */
declare function isDefined<T>(value: Maybe<T>): value is T;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */

/**
 * Type guard that checks if a value is an array with at least one element.
 *
 * @example
 * ```ts
 * const items: Maybe<string[]> = getItems();
 *
 * if (isNonEmptyArray(items)) {
 *   // items is string[]
 *   console.log(items[0]);
 * }
 * ```
 */
declare function isNonEmptyArray<T>(value: Maybe<T[]>): value is [T, ...T[]];

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */

/**
 * Type guard that checks whether a value looks like an RxJS `Observable`.
 *
 * Uses duck-typing: verifies that the object has a `subscribe` function.
 * Does not require an actual `Observable` instance.
 *
 * @example
 * ```ts
 * if (isObservable(stream)) {
 *   stream.subscribe(value => console.log(value));
 * }
 * ```
 */
declare function isObservable<T = unknown>(value: unknown): value is Observable<T>;

/**
 * Clamps `value` into the inclusive `[min, max]` range.
 *
 * @example
 * ```ts
 * clamp(140, 0, 100); // 100
 * clamp(-3, 0, 100);  // 0
 * clamp(42, 0, 100);  // 42
 * ```
 */
declare function clamp(value: number, min: number, max: number): number;

/**
 * Rounds `value` to `decimals` fraction digits, compensating the usual
 * floating point drift (`0.1 + 0.2` rounds to `0.3`, not `0.30000000000000004`).
 *
 * @example
 * ```ts
 * round(0.1 + 0.2, 2); // 0.3
 * round(1.005, 2);     // 1.01
 * round(7.4);          // 7
 * ```
 */
declare function round(value: number, decimals?: number): number;

/**
 * Input-transform factory: coerces any bound value to a number, falling
 * back to `fallback` for `null` / `undefined` / unparsable input. The
 * standard transform for numeric `input()`s across ngwr.
 *
 * @example
 * ```ts
 * readonly speed = input(4, { transform: numAttr(4) });
 * ```
 */
declare const numAttr: (fallback: number) => (value: unknown) => number;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/**
 * Options for {@link resolveCssSize}.
 */
interface ResolveCssSizeOptions {
    /**
     * Fallback value used when the raw input is `null` or `undefined`.
     *
     * Accepts the same formats as the `raw` parameter:
     * numbers, pixel strings, rem strings, percentages, etc.
     */
    defaultValue?: unknown;
}

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/**
 * Result of resolving a CSS size value via {@link resolveCssSize}.
 */
interface ResolvedCssSize {
    /**
     * Value suitable for use in CSS styles (e.g. `"48px"`, `"3rem"`, `"80%"`).
     */
    cssValue: string;
    /**
     * Equivalent value in pixels, when computable.
     *
     * `null` for percentage-based or unknown units where a pixel
     * equivalent cannot be determined.
     */
    pxValue: number | null;
}

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */

/**
 * Resolves a raw size value into a CSS string and an optional pixel equivalent.
 *
 * Supported formats:
 * - `number`   → pixels        (`48`    → `"48px"`)
 * - `"12px"`   → pixels        (`"12px"` → `"12px"`)
 * - `"3rem"`   → rems via root (`"3rem"` → `"3rem"`, pxValue = 3 × root font size)
 * - `"80%"`    → percentage    (`"80%"`  → `"80%"`,  pxValue = null)
 * - `"15"`     → pixels        (`"15"`   → `"15px"`)
 * - anything else → passed through as-is, pxValue = null
 *
 * @example
 * ```ts
 * const size = resolveCssSize('3rem', { defaultValue: '6rem' });
 * // size.cssValue === '3rem'
 * // size.pxValue  === 3 * getRootFontSize()
 * ```
 *
 * @param raw - Value to resolve. Accepts numbers, pixel/rem/percent strings, or `null`/`undefined`.
 * @param options - Optional configuration.
 * @returns Resolved CSS value and its pixel equivalent when computable.
 *
 * @see {@link ResolvedCssSize}
 * @see {@link ResolveCssSizeOptions}
 */
declare function resolveCssSize(raw: unknown, options?: ResolveCssSizeOptions): ResolvedCssSize;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/**
 * Reads the root font size (in pixels) from
 * `getComputedStyle(document.documentElement).fontSize`.
 *
 * Typical use case: converting `rem` values to pixels for layout calculations.
 *
 * Falls back to the provided value when:
 * - DOM is not available (SSR);
 * - `getComputedStyle` fails or returns an unparseable value.
 *
 * @example
 * ```ts
 * const rootFontSize = getRootFontSize();      // e.g. 16
 * const customFallback = getRootFontSize(14);  // uses 14 if DOM is unavailable
 * ```
 *
 * @param fallback - Value in pixels when DOM is unavailable. Defaults to `16`.
 * @returns Root font size in pixels.
 */
declare function getRootFontSize(fallback?: number): number;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/** Return every focusable descendant of `root` in DOM order. */
declare function getFocusableElements(root: HTMLElement): readonly HTMLElement[];
/**
 * Trap Tab navigation inside `root` for a keyboard event — call from a
 * `keydown` handler. Cycles focus from first ↔ last focusable element.
 * Returns `true` when focus was redirected (event was handled).
 */
declare function trapFocus(root: HTMLElement, event: KeyboardEvent): boolean;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/**
 * Generates a pseudo-random, DOM-safe identifier.
 *
 * Produced ids:
 * - are prefixed to avoid collisions with host-application ids;
 * - contain only `[a-z0-9-]` characters;
 * - use `crypto.getRandomValues` when available, falling back to `Math.random`.
 *
 * **Not suitable for cryptographic or security-sensitive purposes** —
 * intended only for UI element identifiers (`id`, `for`, `aria-*`, etc.).
 *
 * @example
 * ```ts
 * randomId();
 * // → "wr-a8f2bx1k9q4z"
 *
 * randomId('ng', 8);
 * // → "ng-k2f9mbeo"
 *
 * randomId('wr', 24);
 * // → "wr-a8f2bx1k9q4zmneo73wplr"
 * ```
 *
 * @param prefix - Namespace prefix prepended before the random segment. Defaults to `'wr'`.
 * @param length - Length of the random segment. Clamped to `[4, 64]`. Defaults to `12`.
 * @param random - Custom random byte source `(byteLength) => Uint8Array`.
 *   When omitted, uses `crypto.getRandomValues` with a `Math.random` fallback.
 * @returns A pseudo-random id string matching `/^[a-z]+-[a-z0-9]+$/`.
 */
declare function randomId(prefix?: string, length?: number, random?: (byteLength: number) => Uint8Array): string;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/**
 * A function that does nothing.
 *
 * Useful as a default callback, placeholder event handler,
 * or to explicitly signal intentional no-ops.
 *
 * @example
 * ```ts
 * @Component({ ... })
 * export class MyComponent {
 *   onTouched: () => void = noop;
 * }
 * ```
 */
declare const noop: () => void;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/** A debounced function — same signature as the original plus `cancel`. */
type WrDebouncedFn<TArgs extends readonly unknown[]> = ((...args: TArgs) => void) & {
    readonly cancel: () => void;
};
/**
 * Wrap `fn` so it only fires `waitMs` after the last invocation.
 * Useful for resize / scroll / input handlers.
 *
 * @example
 * ```ts
 * const onResize = debounce(() => recalcLayout(), 150);
 * window.addEventListener('resize', onResize);
 * ```
 */
declare function debounce<TArgs extends readonly unknown[]>(fn: (...args: TArgs) => void, waitMs: number): WrDebouncedFn<TArgs>;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/** A throttled function — same signature as the original plus `cancel`. */
type WrThrottledFn<TArgs extends readonly unknown[]> = ((...args: TArgs) => void) & {
    readonly cancel: () => void;
};
/**
 * Wrap `fn` so it fires at most once every `waitMs`. Leading-edge call
 * fires immediately; trailing-edge call fires once at the end of the window
 * if there were further invocations.
 */
declare function throttle<TArgs extends readonly unknown[]>(fn: (...args: TArgs) => void, waitMs: number): WrThrottledFn<TArgs>;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/**
 * Canonical `KeyboardEvent.key` values used across ngwr components.
 * Use these constants instead of magic strings so refactors are searchable.
 */
declare const KEYS: {
    readonly ENTER: "Enter";
    readonly ESCAPE: "Escape";
    readonly TAB: "Tab";
    readonly SPACE: " ";
    readonly BACKSPACE: "Backspace";
    readonly DELETE: "Delete";
    readonly ARROW_UP: "ArrowUp";
    readonly ARROW_DOWN: "ArrowDown";
    readonly ARROW_LEFT: "ArrowLeft";
    readonly ARROW_RIGHT: "ArrowRight";
    readonly HOME: "Home";
    readonly END: "End";
    readonly PAGE_UP: "PageUp";
    readonly PAGE_DOWN: "PageDown";
};
type WrKey = (typeof KEYS)[keyof typeof KEYS];

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/** True when any modifier key (Ctrl / Cmd / Alt / Shift / Meta) is held. */
declare function hasModifier(event: KeyboardEvent): boolean;
/**
 * True when the key is a single printable character (letters, digits,
 * punctuation, etc.). Skips function keys, arrows, modifiers, and named
 * keys like `Backspace` or `Tab`.
 */
declare function isPrintableKey(event: KeyboardEvent): boolean;

/**
 * @license
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
 */
/**
 * Logs a coloured pill to the browser console followed by a payload.
 *
 * Useful when you need to scan a noisy console for a specific subsystem's
 * messages. The pill is rendered with the CSS `%c` console formatting trick.
 *
 * @example
 * ```ts
 * badgeLog('icons', '#3969e2', { name: 'plus', registered: true });
 * // → [icons] { name: 'plus', registered: true }
 * ```
 *
 * @param badgeText Short label shown inside the pill.
 * @param color    CSS colour applied to the pill border and text.
 * @param message  Anything you'd pass to `console.log` as the second argument.
 *
 * @internal
 */
declare function badgeLog(badgeText: string, color: string, message: unknown): void;

export { KEYS, badgeLog, clamp, debounce, getFocusableElements, getRootFontSize, hasModifier, isDefined, isNonEmptyArray, isObservable, isPrintableKey, noop, numAttr, randomId, resolveCssSize, round, throttle, trapFocus };
export type { Maybe, ResolveCssSizeOptions, ResolvedCssSize, SafeAny, WrDebouncedFn, WrKey, WrThrottledFn };