mazey 5.1.1 → 5.3.0

package/lib/index.d.ts

@@ -1,7 +1,5 @@
 /**
- * EN: Computes the longest common substring of two strings.
- *
- * ZH: 计算两个字符串的最长公共子串。
+ * Compute the length of the longest common substring of two strings.
  *
  * Usage:
  *
@@ -31,9 +29,7 @@ declare function longestComSubstring(aStr: string, bStr: string): number;
  */
 declare function calLongestCommonSubstring(aStr: string, bStr: string): number;
 /**
- * EN: Computes the longest common subsequence of two strings.
- *
- * ZH: 计算两个字符串的最长公共子序列。
+ * Compute the length of the longest common subsequence of two strings.
  *
  * Usage:
  *
@@ -50,9 +46,9 @@ declare function calLongestCommonSubstring(aStr: string, bStr: string): number;
  * 4
  * ```
  *
- * @param {string} aStr 字符串
- * @param {string} bStr 字符串
- * @returns {number} 长度
+ * @param {string} aStr The first string.
+ * @param {string} bStr The second string.
+ * @returns {number} The length of the longest common subsequence.
  * @category Calculate and Formula
  */
 declare function longestComSubsequence(aStr: string, bStr: string): number;
@@ -63,16 +59,14 @@ declare function longestComSubsequence(aStr: string, bStr: string): number;
  */
 declare function calLongestCommonSubsequence(aStr: string, bStr: string): number;
 /**
- * EN: Hit probability (1% ~ 100%).
- *
- * ZH: 百分位概率。
+ * Return whether a random value falls within the given probability.
  *
  * Usage:
  *
  * ```javascript
  * import { isHit } from "mazey";
  *
- * const ret = isHit(0.5); // 0.01 ~ 1 true/false
+ * const ret = isHit(0.5); // A 50% chance of returning true.
  * console.log(ret);
  * ```
  *
@@ -103,8 +97,8 @@ declare function calLongestCommonSubsequence(aStr: string, bStr: string): number
  * 499994 500006
  * ```
  *
- * @param {number} rate 0.1 ~ 1 => 1% ~ 100%
- * @returns {boolean} true 命中
+ * @param {number} rate Probability expressed as a value from 0 to 1.
+ * @returns {boolean} Whether the random value is less than the probability.
  * @category Calculate and Formula
  */
 declare function isHit(rate: number): boolean;
@@ -467,6 +461,24 @@ declare function isJSONString(str: string): boolean;
  * @hidden
  */
 declare function isJsonString(str: string): boolean;
+/**
+ * Parse a JSON string and return a caller-defined fallback when parsing fails.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { parseJsonSafe } from "mazey";
+ *
+ * const data = parseJsonSafe('{"enabled":true}');
+ * const fallback = parseJsonSafe("invalid", {});
+ * ```
+ *
+ * @param value JSON string to parse.
+ * @param fallback Value returned when parsing fails. Defaults to `null`.
+ * @returns The parsed JSON value or the supplied fallback.
+ * @category Util
+ */
+declare function parseJsonSafe<T, F = null>(value: string, fallback?: F): T | F;
 /**
  * Generate a random string of number, `genRndNumString(7)` => "7658495".
  *
@@ -500,9 +512,8 @@ declare function genRndNumString(n?: number): string;
  */
 declare function generateRndNum(n?: number): string;
 /**
- * EN: Generate a unique identifier number based on time: `genUniqueNumString()` => `1538324722364123`
- *
- * ZH: 根据时间生成唯一标志的数字：`genUniqueNumString()` => `1538324722364123`。
+ * Generate a numeric identifier by combining the current timestamp with a
+ * random numeric suffix.
  *
  * Usage:
  *
@@ -522,7 +533,8 @@ declare function generateRndNum(n?: number): string;
  * 1538324722364123
  * ```
  *
- * @param {number} n 随机数的长度
+ * @param {number} n Length of the random numeric suffix.
+ * @returns {string} A timestamp-based numeric identifier.
  * @category Util
  */
 declare function genUniqueNumString(n?: number): string;
@@ -533,9 +545,7 @@ declare function genUniqueNumString(n?: number): string;
  */
 declare function generateUniqueNum(n?: number): string;
 /**
- * EN: Get timestamp.
- *
- * ZH: 获取时间戳。
+ * Get the current timestamp in milliseconds.
  *
  * Usage:
  *
@@ -552,13 +562,12 @@ declare function generateUniqueNum(n?: number): string;
  * 1585325367122
  * ```
  *
+ * @returns {number} The current timestamp in milliseconds.
  * @category Util
  */
 declare function mNow(): number;
 /**
- * EN: Floating point number to percentage 0.2 => 20%
- *
- * ZH: 浮点数转为百分比 0.2 => 20%。
+ * Convert a floating-point ratio to a percentage string.
  *
  * Usage:
  *
@@ -578,15 +587,14 @@ declare function mNow(): number;
  * 20.00%
  * ```
  *
- * @param {number} num 浮点数
- * @param {number} fixSize 保留几位浮点数
+ * @param {number} num Floating-point ratio to convert.
+ * @param {number} fixSize Number of decimal places in the percentage.
+ * @returns {string} The percentage string.
  * @category Util
  */
 declare function floatToPercent(num: number, fixSize?: number): string;
 /**
- * EN: Keep the specified number of decimal places for floating-point numbers.
- *
- * ZH: 浮点数保留指定位。
+ * Format a number with a fixed number of decimal places.
  *
  * Usage:
  *
@@ -606,13 +614,14 @@ declare function floatToPercent(num: number, fixSize?: number): string;
  * 0.20
  * ```
  *
+ * @param num Number or numeric string to format.
+ * @param size Number of decimal places.
+ * @returns The fixed-point string.
  * @category Util
  */
 declare function floatFixed(num: number | string, size?: number): string;
 /**
- * EN: Throttle, used to limit the frequency of function execution over time.
- *
- * ZH: 节流，用于限制函数在一段时间内的执行频率。
+ * Limit how frequently a function can be invoked over time.
  *
  * Usage:
  *
@@ -626,6 +635,11 @@ declare function floatFixed(num: number | string, size?: number): string;
  *
  * Reference: [Lodash](https://lodash.com/docs/4.17.15#throttle)
  *
+ * @param func Function to throttle.
+ * @param wait Minimum interval between invocations, in milliseconds.
+ * @param options.leading Whether to invoke on the leading edge.
+ * @param options.trailing Whether to invoke on the trailing edge.
+ * @returns The throttled function.
  * @category Util
  */
 declare function throttle<T extends (...args: MazeyFnParams) => MazeyFnReturn>(func: T, wait: number, options?: {
@@ -633,9 +647,8 @@ declare function throttle<T extends (...args: MazeyFnParams) => MazeyFnReturn>(f
     trailing?: boolean;
 }): ThrottleFunc<T>;
 /**
- * EN: Debounce, used to delay the execution of a function until a specified time has passed since the last invocation.
- *
- * ZH: 防抖，用于在最后一次调用后的指定时间内延迟函数的执行。
+ * Delay function execution until the specified time has passed since the last
+ * invocation.
  *
  * Usage:
  *
@@ -647,6 +660,10 @@ declare function throttle<T extends (...args: MazeyFnParams) => MazeyFnReturn>(f
  * }, 1000, true);
  * ```
  *
+ * @param func Function to debounce.
+ * @param wait Delay after the last invocation, in milliseconds.
+ * @param immediate Whether to invoke on the leading edge instead.
+ * @returns The debounced function.
  * @category Util
  */
 declare function debounce<T extends (...args: MazeyFnParams) => MazeyFnReturn>(func: T, wait: number, immediate?: boolean): DebounceFunc<T>;
@@ -727,9 +744,7 @@ declare function getFriendlyInterval(start?: number | string | Date, end?: numbe
  */
 declare function formatDurationFromMs(durationMs: number): string;
 /**
- * EN: Check whether it is a right number.
- *
- * ZH: 判断是否有效数字。
+ * Check whether a value is a number allowed by the supplied options.
  *
  * Usage:
  *
@@ -752,16 +767,14 @@ declare function formatDurationFromMs(durationMs: number): string;
  * true false false true false true
  * ```
  *
- * @param {*} num 被判断的值
+ * @param {*} num Value to check.
  * @param options Controls whether `NaN`, `Infinity`, or other non-finite values count as numbers.
- * @returns {boolean} true 是数字
+ * @returns {boolean} Whether the value is an allowed number.
  * @category Util
  */
 declare function isNumber(num: unknown, options?: IsNumberOptions): boolean;
 /**
- * EN: Invoke effective function.
- *
- * ZH: 执行有效函数。
+ * Invoke a value only when it is a function.
  *
  * Usage:
  *
@@ -773,7 +786,9 @@ declare function isNumber(num: unknown, options?: IsNumberOptions): boolean;
  * });
  * ```
  *
- * @param {function} fn 等待被执行的未知是否有效的函数
+ * @param {function} fn Potential function to invoke.
+ * @param params Arguments passed to the function.
+ * @returns The function result, or `null` when `fn` is not callable.
  * @category Util
  */
 declare function invokeFn(fn: MazeyFunction | null | undefined, ...params: Parameters<MazeyFunction>): ReturnType<MazeyFunction> | null;
@@ -1037,8 +1052,8 @@ declare function newLine(str: string): string;
  * hello world
  * ```
  *
- * @param {string} str 带 HTML 标签的字符串
- * @returns {string} 字符串
+ * @param {string} str A string that may contain HTML tags.
+ * @returns {string} The string with HTML tags removed.
  * @category Util
  */
 declare function removeHTML(str: string, options?: {
@@ -1121,9 +1136,8 @@ declare function unsanitizeInput(input: string): string;
  */
 declare function unsanitize(str: string): string;
 /**
- * EN: Truncate string, Chinese characters count as 2 bytes.
- *
- * ZH: 截取字符串，中文算 2 个字节。
+ * Truncate a string by weighted length, counting non-ASCII characters as two
+ * units.
  *
  * Usage:
  *
@@ -1140,11 +1154,11 @@ declare function unsanitize(str: string): string;
  * hello
  * ```
  *
- * @param {string} str 要截取的字符串
- * @param {number} len
- * @param {boolean} options.hasDot
- * @param {string} options.dotText
- * @returns {string} 返回截取后的字符串
+ * @param {string} str String to truncate.
+ * @param {number} len Maximum weighted length.
+ * @param {boolean} options.hasDot Whether to append truncation text.
+ * @param {string} options.dotText Text appended when truncation occurs.
+ * @returns {string} The truncated string.
  * @category Util
  */
 declare function cutZHString(str: string | null | undefined, len: number, options?: {
@@ -1167,11 +1181,12 @@ declare function cutZHString(str: string | null | undefined, len: number, option
  *
  * ```text
  * hello
+ * ```
  *
- * @param {string} str 要截取的字符串
- * @param {number} len
- * @param {boolean} hasDot
- * @returns {string} 返回截取后的字符串
+ * @param {string} str String to truncate.
+ * @param {number} len Maximum weighted length.
+ * @param {boolean} hasDot Whether to append the default truncation text.
+ * @returns {string} The truncated string.
  * @hidden
  */
 declare function truncateZHString(str: string | null | undefined, len: number, hasDot?: boolean): string;
@@ -1229,9 +1244,7 @@ declare function zAxiosIsValidRes(res: ZResResponse | undefined, options?: ZResI
  */
 declare function isValidData(data: MazeyObject, attributes: string[], validValue: SimpleType): boolean;
 /**
- * EN: Semantic file size, convert bytes into a readable file size.
- *
- * ZH: 语义化文件大小，把字节转换成正常文件大小。
+ * Convert a byte count to a human-readable file size.
  *
  * Usage:
  *
@@ -1248,6 +1261,8 @@ declare function isValidData(data: MazeyObject, attributes: string[], validValue
  * 1 KB
  * ```
  *
+ * @param size File size in bytes.
+ * @returns A rounded file-size string, or an empty string for a non-positive or non-finite value.
  * @category Util
  */
 declare function getFileSize(size: number): string;
@@ -1274,6 +1289,31 @@ declare function getFileSize(size: number): string;
  * @category Util
  */
 declare function genHashCode(str: string): number;
+/**
+ * Generate a lowercase SHA-256 hexadecimal digest with the Web Crypto API.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { sha256Hex } from "mazey";
+ *
+ * const digest = await sha256Hex("hello world");
+ * console.log(digest);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
+ * ```
+ *
+ * @remarks Requires Web Crypto. String input also requires `TextEncoder`.
+ * @param input Text or binary data to hash.
+ * @returns A promise that resolves to the lowercase hexadecimal digest.
+ * @throws When the required platform API is unavailable. Digest failures are propagated.
+ * @category Util
+ */
+declare function sha256Hex(input: string | BufferSource): Promise<string>;
 /**
  * Check whether an unknown value represents a valid date.
  *
@@ -1310,6 +1350,150 @@ declare function genHashCode(str: string): number;
  * @category Util
  */
 declare function isValidDate(value: unknown): boolean;
+/**
+ * Check whether a date is today in the runtime's local timezone.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isToday } from "mazey";
+ *
+ * const ret = isToday(new Date());
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns Whether the value has the current local year, month, and day. Invalid input returns `false`.
+ * @remarks Hours, minutes, seconds, and milliseconds are ignored. Results depend on the runtime's local timezone.
+ * @category Util
+ */
+declare function isToday(date: MazeyDate): boolean;
+/**
+ * Check whether a date is in the current local calendar year.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isThisYear } from "mazey";
+ *
+ * const ret = isThisYear(new Date());
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns Whether the value has the current local year. Invalid input returns `false`.
+ * @remarks Results depend on the runtime's local timezone.
+ * @category Util
+ */
+declare function isThisYear(date: MazeyDate): boolean;
+/**
+ * Check whether a date is in the current local calendar month and year.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isThisMonth } from "mazey";
+ *
+ * const ret = isThisMonth(new Date());
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns Whether the value has the current local year and month. Invalid input returns `false`.
+ * @remarks Results depend on the runtime's local timezone.
+ * @category Util
+ */
+declare function isThisMonth(date: MazeyDate): boolean;
+/**
+ * Check whether a date is in the current Monday-first local calendar week.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isThisWeek } from "mazey";
+ *
+ * const ret = isThisWeek(new Date());
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns Whether the value is in the current local week. Invalid input returns `false`.
+ * @remarks The week begins on Monday and ends before the following Monday. Boundaries use local time and a half-open range.
+ * @category Util
+ */
+declare function isThisWeek(date: MazeyDate): boolean;
+/**
+ * Check whether a date is within the current local clock hour.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isThisHour } from "mazey";
+ *
+ * const ret = isThisHour(new Date());
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns Whether the value has the current local year, month, day, and hour. Invalid input returns `false`.
+ * @remarks Minutes, seconds, and milliseconds are ignored. Results depend on the runtime's local timezone.
+ * @category Util
+ */
+declare function isThisHour(date: MazeyDate): boolean;
+/**
+ * Format the absolute distance from a date to now in concise English words.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { formatDistanceToNow } from "mazey";
+ *
+ * const ret = formatDistanceToNow(new Date(Date.now() - 60 * 60 * 1000));
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * about 1 hour
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns The absolute approximate distance phrase, or an empty string for invalid input.
+ * @remarks Past and future dates use the same wording without `ago` or `in`. Months and years use fixed approximate durations of 30 and 365 days.
+ * @category Util
+ */
+declare function formatDistanceToNow(date: MazeyDate): string;
 /**
  * Return the formatted date string in the given format.
  *
@@ -1828,9 +2012,7 @@ declare function isValidHttpUrl(url: string, options?: {
     strict: boolean;
 }): boolean;
 /**
- * EN: Get the file type of the url.
- *
- * ZH: 获取文件后缀名。
+ * Get the file extension from a URL or path.
  *
  * Usage:
  *
@@ -2082,9 +2264,7 @@ declare function setClass(ele: HTMLElement, cls: string): void;
  */
 declare function removeClass(obj: MazeyElement, cls: string): void;
 /**
- * EN: Add `<style>` in `<head>`.
- *
- * ZH: 添加样式标签; style: 样式标签内的字符串; id: `<style>` 标签的 `id`; 返回: 添加成功/失败。
+ * Add a `<style>` element to the document `<head>`.
  *
  * Usage:
  *
@@ -2150,6 +2330,10 @@ declare function removeClass(obj: MazeyElement, cls: string): void;
  * <style id="z-style">.footer>.x-wish>a:first-child,div.wish-flex>a[href^='https://github.com/chengchuu'],.m-hide{display: none;}.footer>.y-wish:before{content: 'Copyright (c) chengchuu';color: inherit;padding-inline-start: var(--y-wish-1_5);padding-inline-end: var(--y-wish-1_5);padding-top: var(--y-wish-1);padding-bottom: var(--y-wish-1);}</style>
  * ```
  *
+ * @param style CSS text to add to the document.
+ * @param options.id Optional `<style>` element ID. An existing element with
+ * the same ID is updated instead of duplicated.
+ * @returns Whether non-empty CSS text was added or updated.
  * @category DOM
  */
 declare function addStyle(style: string, options?: {
@@ -2271,6 +2455,62 @@ declare function genStyleString(selector: string, styleArray: Array<string>): st
  * @category DOM
  */
 declare function getPageMeta(name: string): string;
+/**
+ * Check whether a value is a CSS selector supported by the supplied query
+ * root without allowing selector syntax errors to escape.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isValidCssSelector } from "mazey";
+ *
+ * isValidCssSelector(".message > img"); // true
+ * isValidCssSelector("["); // false
+ * isValidCssSelector("", { allowEmpty: true }); // true
+ * ```
+ *
+ * @remarks Browser only unless a compatible `ParentNode` is supplied.
+ * @param selector Value to validate as a CSS selector.
+ * @param options.allowEmpty Whether an empty or whitespace-only string is accepted. Defaults to `false`.
+ * @param options.root Query root used to validate browser support. Defaults to `document` when available.
+ * @returns Whether the selector is accepted by the query root.
+ * @category DOM
+ */
+declare function isValidCssSelector(selector: unknown, options?: {
+    allowEmpty?: boolean;
+    root?: ParentNode;
+}): boolean;
+/**
+ * Extract text from a cloned element without modifying the original DOM.
+ * Images can be replaced by their `alt` text, selected descendants can be
+ * removed, and whitespace can be normalized before returning the text.
+ *
+ * Invalid exclusion selectors are ignored.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { extractElementText } from "mazey";
+ *
+ * const element = document.querySelector(".message");
+ * const text = extractElementText(element, {
+ *   excludeSelector: ".message-actions",
+ * });
+ * ```
+ *
+ * @remarks Browser only.
+ * @param element Element whose cloned contents are read.
+ * @param options.excludeSelector Selector for descendants to remove from the clone.
+ * @param options.replaceImagesWithAlt Whether images with an `alt` attribute are replaced by that text. Defaults to `true`.
+ * @param options.normalizeWhitespace Whether whitespace is collapsed and trimmed. Defaults to `true`.
+ * @returns Extracted text from the cloned element.
+ * @category DOM
+ */
+declare function extractElementText(element: Element, options?: {
+    excludeSelector?: string;
+    replaceImagesWithAlt?: boolean;
+    normalizeWhitespace?: boolean;
+}): string;
 
 /**
  * Prevent bubbling.
@@ -2373,9 +2613,7 @@ declare function invokeEvent(type: string, params?: MazeyObject): void;
 declare function removeEvent(type: string, fn?: MazeyFn): void;
 
 /**
- * EN: Handle Storage (Keep fit for JSON, it can transfer format automatically).
- *
- * ZH: 存储/获取数据到 sessionStorage/localStorage。
+ * Serialize a value as JSON and store it in `sessionStorage`.
  *
  * Usage:
  *
@@ -2388,7 +2626,7 @@ declare function removeEvent(type: string, fn?: MazeyFn): void;
  * const ret2 = getLocalStorage("test");
  * console.log(ret1, ret2);
  *
- * // or package in usage
+ * // Wrap the helpers with a project-specific key prefix.
  * const projectName = "mazey";
  * function mSetLocalStorage (key, value) {
  *   return setLocalStorage(`${projectName}_${key}`, value);
@@ -2405,15 +2643,14 @@ declare function removeEvent(type: string, fn?: MazeyFn): void;
  * 123 123
  * ```
  *
- * @param {string} key 键
- * @returns {void} 返回值
+ * @param {string} key Storage key.
+ * @param value Value to serialize and store.
+ * @returns {void} This function does not return a value.
  * @category Store
  */
 declare function setSessionStorage<T>(key: string, value?: T | null): void;
 /**
- * EN: Handle Storage (Keep fit for JSON, it can transfer format automatically).
- *
- * ZH: 存储/获取数据到 sessionStorage/localStorage。
+ * Read a value from `sessionStorage`, parsing JSON when possible.
  *
  * Usage:
  *
@@ -2426,7 +2663,7 @@ declare function setSessionStorage<T>(key: string, value?: T | null): void;
  * const ret2 = getLocalStorage("test");
  * console.log(ret1, ret2);
  *
- * // or package in usage
+ * // Wrap the helpers with a project-specific key prefix.
  * const projectName = "mazey";
  * function mSetLocalStorage (key, value) {
  *   return setLocalStorage(`${projectName}_${key}`, value);
@@ -2443,15 +2680,13 @@ declare function setSessionStorage<T>(key: string, value?: T | null): void;
  * 123 123
  * ```
  *
- * @param {string} key 键
- * @returns {any} 返回值
+ * @param {string} key Storage key.
+ * @returns The parsed value, raw stored value, or `null` when no value exists.
  * @category Store
  */
 declare function getSessionStorage<T>(key: string): T | null;
 /**
- * EN: Handle Storage (Keep fit for JSON, it can transfer format automatically).
- *
- * ZH: 存储/获取数据到 sessionStorage/localStorage。
+ * Serialize a value as JSON and store it in `localStorage`.
  *
  * Usage:
  *
@@ -2464,7 +2699,7 @@ declare function getSessionStorage<T>(key: string): T | null;
  * const ret2 = getLocalStorage("test");
  * console.log(ret1, ret2);
  *
- * // or package in usage
+ * // Wrap the helpers with a project-specific key prefix.
  * const projectName = "mazey";
  * function mSetLocalStorage (key, value) {
  *   return setLocalStorage(`${projectName}_${key}`, value);
@@ -2481,15 +2716,14 @@ declare function getSessionStorage<T>(key: string): T | null;
  * 123 123
  * ```
  *
- * @param {string} key 键
- * @returns {void} 返回值
+ * @param {string} key Storage key.
+ * @param value Value to serialize and store.
+ * @returns {void} This function does not return a value.
  * @category Store
  */
 declare function setLocalStorage<T>(key: string, value?: T | null): void;
 /**
- * EN: Handle Storage (Keep fit for JSON, it can transfer format automatically).
- *
- * ZH: 存储/获取数据到 sessionStorage/localStorage。
+ * Read a value from `localStorage`, parsing JSON when possible.
  *
  * Usage:
  *
@@ -2502,7 +2736,7 @@ declare function setLocalStorage<T>(key: string, value?: T | null): void;
  * const ret2 = getLocalStorage("test");
  * console.log(ret1, ret2);
  *
- * // or package in usage
+ * // Wrap the helpers with a project-specific key prefix.
  * const projectName = "mazey";
  * function mSetLocalStorage (key, value) {
  *   return setLocalStorage(`${projectName}_${key}`, value);
@@ -2519,22 +2753,20 @@ declare function setLocalStorage<T>(key: string, value?: T | null): void;
  * 123 123
  * ```
  *
- * @param {string} key 键
- * @returns {void} 返回值
+ * @param {string} key Storage key.
+ * @returns The parsed value, raw stored value, or `null` when no value exists.
  * @category Store
  */
 declare function getLocalStorage<T>(key: string): T | null;
 /**
- * EN: Handle Cookie.
- *
- * ZH: 设置/获取 Cookie。
+ * Get a cookie value by name.
  *
  * Usage:
  *
  * ```javascript
  * import { setCookie, getCookie } from "mazey";
  *
- * setCookie("test", "123", 30, "example.com"); // key value day domain
+ * setCookie("test", "123", 30, "example.com"); // name, value, days, domain
  * const ret = getCookie("test");
  * console.log(ret);
  * ```
@@ -2545,20 +2777,20 @@ declare function getLocalStorage<T>(key: string): T | null;
  * 123
  * ```
  *
+ * @param name Cookie name.
+ * @returns The cookie value, or an empty string when the cookie does not exist.
  * @category Store
  */
 declare function getCookie(name: string): string;
 /**
- * EN: Handle Cookie.
- *
- * ZH: 设置/获取 Cookie。
+ * Set a cookie value.
  *
  * Usage:
  *
  * ```javascript
  * import { setCookie, getCookie } from "mazey";
  *
- * setCookie("test", "123", 30, "example.com"); // key value day domain
+ * setCookie("test", "123", 30, "example.com"); // name, value, days, domain
  * const ret = getCookie("test");
  * console.log(ret);
  * ```
@@ -2569,6 +2801,11 @@ declare function getCookie(name: string): string;
  * 123
  * ```
  *
+ * @param name Cookie name.
+ * @param value Cookie value.
+ * @param days Number of days until expiration. Omit for a session cookie.
+ * @param domain Optional cookie domain.
+ * @returns {void} This function does not return a value.
  * @category Store
  */
 declare function setCookie(name: string, value: string, days?: number, domain?: string): void;
@@ -2603,9 +2840,7 @@ declare function removeCookie(name: string): boolean;
 declare function delCookie(name: string): void;
 
 /**
- * EN: Load a CSS file from the server.
- *
- * ZH: 动态加载 CSS 文件。
+ * Load a CSS file dynamically.
  *
  * Usage:
  *
@@ -2636,18 +2871,16 @@ declare function delCookie(name: string): void;
  * Load CSS Success: loaded
  * ```
  *
- * @param {string} url -- css资源路径
- * @param {string} options.id -- link标签id
- * @returns {Promise<string>} true -- 加载成功
+ * @param {string} url URL of the CSS resource.
+ * @param {string} options.id Optional ID for the `<link>` element.
+ * @returns {Promise<string>} A promise that resolves to `"loaded"` after the stylesheet loads.
  * @category Load
  */
 declare function loadCSS(url: string, options?: {
     id?: string;
 }): Promise<string>;
 /**
- * EN: Load a JavaScript file from the server and execute it.
- *
- * ZH: 动态加载 JavaScript 文件。
+ * Load and execute a JavaScript file dynamically.
  *
  * Usage:
  *
@@ -2679,16 +2912,16 @@ declare function loadCSS(url: string, options?: {
  * Load JavaScript script: loaded
  * ```
  *
- * @param {string} url -- JavaScript 资源路径
- * @param {string} options.id -- DOM ID
- * @param {function} options.callback -- 加载后回调函数
- * @param {number} options.timeout -- 超时时长
- * @param {boolean} options.isDefer -- 是否添加 defer 标签
- * @param {boolean} options.isAsync -- 是否添加 async 标签
- * @param {boolean} options.isCrossOrigin -- 是否跨域
- * @param {object} options.attributes -- 其他属性
- * @param {string} options.cssUrl -- CSS 资源路径
- * @returns {Promise<string>} -- true 成功
+ * @param {string} url URL of the JavaScript resource.
+ * @param {string} options.id Optional ID for the `<script>` element.
+ * @param {function} options.callback Callback invoked after the script loads.
+ * @param {number} options.timeout Timeout in milliseconds.
+ * @param {boolean} options.isDefer Whether to set the `defer` attribute.
+ * @param {boolean} options.isAsync Whether to set the `async` attribute.
+ * @param {boolean} options.isCrossOrigin Whether to request the script anonymously across origins.
+ * @param {object} options.attributes Additional attributes for the `<script>` element.
+ * @param {string} options.cssUrl Optional CSS resource to begin loading before the script is inserted.
+ * @returns {Promise<string>} A promise that resolves to `"loaded"` after the script loads.
  * @category Load
  */
 declare function loadScript(url: string, options?: {
@@ -2702,9 +2935,8 @@ declare function loadScript(url: string, options?: {
     cssUrl?: string;
 }): LoadScriptReturns;
 /**
- * EN: Check whether the page is loaded successfully (Keep the compatibility if the browser's `load` event has been triggered).
- *
- * ZH: 页面加载完成。
+ * Wait for the page to finish loading, including when the `load` event has
+ * already fired.
  *
  * Usage:
  *
@@ -2726,8 +2958,8 @@ declare function loadScript(url: string, options?: {
  * Load Success: load
  * ```
  *
- * @param {number} timeout 超时时间 / 单位：毫秒，默认：30000(30 秒)
- * @returns {Promise<string>} document is loaded? "complete" "load" / "timeout"
+ * @param {number} timeout Timeout in milliseconds. Defaults to 30,000.
+ * @returns {Promise<string>} A promise that resolves to `"complete"` or `"load"`, or rejects on timeout.
  * @category Load
  */
 declare function windowLoaded(timeout?: number): Promise<string>;
@@ -2948,9 +3180,7 @@ declare function getCLS(): Promise<number>;
  */
 declare function getTTFB(): Promise<number>;
 /**
- * EN: Get page load time(`PerformanceNavigationTiming`).
- *
- * ZH: 获取页面加载相关的各项数据。
+ * Get page-load metrics from the Navigation Timing APIs.
  *
  * @remarks
  * This function uses the [`PerformanceNavigationTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming) API to get page load time data.
@@ -2961,8 +3191,8 @@ declare function getTTFB(): Promise<number>;
  * ```javascript
  * import { getPerformance } from "mazey";
  *
- * // `camelCase：false` (Default) Return underline(`a_b`) data.
- * // `camelCase：true` Return hump(`aB`) data.
+ * // `camelCase: false` (default) returns snake_case keys such as `a_b`.
+ * // `camelCase: true` returns camelCase keys such as `aB`.
  * getPerformance()
  *  .then(res => {
  *   console.log(JSON.stringify(res));
@@ -2992,8 +3222,8 @@ declare function getTTFB(): Promise<number>;
  * | ssl_time | SSL | number | (Optional) connectEnd - secureConnectionStart |
  * | download_time | Download | number | (Optional) responseEnd - responseStart |
  *
- * @param {boolean} camelCase -- false（默认） 以下划线形式返回数据 true 以驼峰形式返回数据
- * @returns {Promise<object>} 加载数据
+ * @param {boolean} camelCase Whether to return camelCase keys. Defaults to `false`, which returns snake_case keys.
+ * @returns {Promise<object>} The collected page-load metrics.
  * @category Perf
  */
 declare function getPerformance(camelCase?: boolean): Promise<WebPerformance>;
@@ -3060,9 +3290,7 @@ declare function isSafePWAEnv(options?: IsSafePWAEnvOptions): boolean;
  */
 declare function isStandalonePWA(): boolean;
 /**
- * EN: Provides detailed information about the browser.
- *
- * ZH: 返回有关浏览器的详细信息。
+ * Return detailed information about the current browser.
  *
  * Usage:
  *
@@ -3107,9 +3335,7 @@ declare function isStandalonePWA(): boolean;
  */
 declare function getBrowserInfo(): BrowserInfo;
 /**
- * EN: Generate browser attributes.
- *
- * ZH: 生成浏览器属性。
+ * Generate browser attributes from the detected browser information.
  *
  * Usage:
  *
@@ -3158,9 +3384,119 @@ declare function genBrowserAttrs(prefix?: string, separator?: string): string[];
 declare function isSupportWebp(): Promise<boolean>;
 
 /**
- * EN: Custom console printing (`console`).
+ * A user-selectable color-theme preference.
  *
- * ZH: 生成自定义控制台打印。
+ * @category Browser Information
+ */
+type ThemePreference = "system" | "light" | "dark";
+/**
+ * A concrete color theme that can be applied to a page.
+ *
+ * @category Browser Information
+ */
+type ResolvedTheme = "light" | "dark";
+/**
+ * Human-readable names for supported theme preferences.
+ *
+ * @category Browser Information
+ */
+type ThemePreferenceDisplayName = "System" | "Light" | "Dark";
+/**
+ * The highest-priority source that selected a theme preference.
+ *
+ * @category Browser Information
+ */
+type ThemePreferenceSource = "query" | "storage" | "system" | "fallback";
+/**
+ * Options for {@link resolveThemePreference}.
+ *
+ * @category Browser Information
+ */
+interface ResolveThemePreferenceOptions {
+    /** Project-specific local-storage key, such as `MAZEY_THEME`. */
+    storageKey: string;
+    /** URL query parameter name. Defaults to `theme`. */
+    queryParam?: string;
+    /** URL inspected for a query override. Defaults to `window.location.href` when available. */
+    url?: string | URL;
+    /** Storage used to read a persisted preference. Defaults to `window.localStorage` when available. */
+    storage?: Pick<Storage, "getItem"> | null;
+    /** Media-query implementation. Defaults to `window.matchMedia` when available. */
+    matchMedia?: (query: string) => Pick<MediaQueryList, "matches">;
+    /** Theme used when the system preference is unavailable. Defaults to `light`. */
+    fallback?: ResolvedTheme;
+}
+/**
+ * Result returned by {@link resolveThemePreference}.
+ *
+ * @category Browser Information
+ */
+interface ThemePreferenceResult {
+    /** Selected user-facing preference. */
+    preference: ThemePreference;
+    /** Effective light or dark theme. */
+    resolvedTheme: ResolvedTheme;
+    /** Human-readable name of the selected preference. */
+    displayName: ThemePreferenceDisplayName;
+    /** Highest-priority source that supplied the selected preference. */
+    source: ThemePreferenceSource;
+}
+/**
+ * Resolve a website theme preference without mutating the DOM or storage.
+ *
+ * Resolution uses four priority levels: a `light` or `dark` URL query
+ * override, a stored `system`/`light`/`dark` preference, the current system
+ * color scheme, and finally a configured `light` or `dark` fallback. The
+ * default query parameter is `theme`, and the storage key must be supplied by
+ * the consuming project. Query `system` and all unsupported values are ignored.
+ *
+ * The result separates the selected preference from the effective theme and
+ * includes its display name (`System`, `Light`, or `Dark`) and source. A stored
+ * `system` preference retains `source: "storage"` while its effective theme is
+ * resolved from the current media query or fallback.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { resolveThemePreference } from "mazey";
+ *
+ * const theme = resolveThemePreference({
+ *   storageKey: "MY_WEBSITE_THEME",
+ * });
+ * console.log(theme.preference);
+ * console.log(theme.resolvedTheme);
+ * console.log(theme.displayName);
+ * console.log(theme.source);
+ * ```
+ *
+ * Possible output:
+ *
+ * ```text
+ * system
+ * dark
+ * System
+ * system
+ * ```
+ *
+ * URL override:
+ *
+ * ```javascript
+ * const theme = resolveThemePreference({
+ *   storageKey: "MY_WEBSITE_THEME",
+ *   url: "https://example.com/?theme=light",
+ * });
+ * ```
+ *
+ * @param options Project storage key and optional URL, storage, media-query, and fallback inputs.
+ * @returns The selected preference, effective theme, display name, and preference source.
+ * @throws {TypeError} If required options or explicitly supplied option values are invalid.
+ * @remarks Safe during SSR and resilient to unavailable or throwing browser APIs. This function does not write storage, mutate the DOM, or add listeners. System resolution reads the current media-query result rather than cached browser information.
+ * @category Browser Information
+ */
+declare function resolveThemePreference(options: ResolveThemePreferenceOptions): ThemePreferenceResult;
+
+/**
+ * Create a configurable wrapper around the global `console`.
  *
  * Usage:
  *
@@ -3211,9 +3547,7 @@ declare function genCustomConsole(prefix?: string, options?: {
  */
 declare const mazeyCon: Console;
 /**
- * EN: Print logs with Time.
- *
- * ZH: 打印带有时间的日志。
+ * Print logs with a localized timestamp.
  *
  * Usage:
  *
@@ -3224,12 +3558,12 @@ declare const mazeyCon: Console;
  * Output:
  *
  * ```text
- * 2024年11月2日周六 09:24:40 I am string.
+ * [localized date and time] I am string.
  * ```
  *
  * @hidden
  */
 declare const timeCon: Console;
 
-export { addClass, addEvent, addStyle, calLongestCommonSubsequence, calLongestCommonSubstring, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, doFn, fireEvent, floatFixed, floatToPercent, formatDate, formatDurationFromMs, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionStorage, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, inRate, invokeEvent, invokeFn, isArray, isBool, isBoolean, isBrowser, isFunction, isHit, isJSONString, isJsonString, isNonEmptyArray, isNonEmptyObject, isNumber, isPureObject, isSafePWAEnv, isStandalonePWA, isString, isSupportWebp, isSupportedEntryType, isUdfOrNul, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onURLChange, parseGitHubRepository, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLocalStorage, setSessionStorage, sleep, throttle, timeCon, toJavaScriptGlobalName, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, windowLoaded, zAxiosIsValidRes };
-export type { GitHubRepositoryDetails, IsSafePWAEnvOptions };
+export { addClass, addEvent, addStyle, calLongestCommonSubsequence, calLongestCommonSubstring, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, doFn, extractElementText, fireEvent, floatFixed, floatToPercent, formatDate, formatDistanceToNow, formatDurationFromMs, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionStorage, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, inRate, invokeEvent, invokeFn, isArray, isBool, isBoolean, isBrowser, isFunction, isHit, isJSONString, isJsonString, isNonEmptyArray, isNonEmptyObject, isNumber, isPureObject, isSafePWAEnv, isStandalonePWA, isString, isSupportWebp, isSupportedEntryType, isThisHour, isThisMonth, isThisWeek, isThisYear, isToday, isUdfOrNul, isValidCssSelector, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onURLChange, parseGitHubRepository, parseJsonSafe, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, resolveThemePreference, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLocalStorage, setSessionStorage, sha256Hex, sleep, throttle, timeCon, toJavaScriptGlobalName, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, windowLoaded, zAxiosIsValidRes };
+export type { GitHubRepositoryDetails, IsSafePWAEnvOptions, ResolveThemePreferenceOptions, ResolvedTheme, ThemePreference, ThemePreferenceDisplayName, ThemePreferenceResult, ThemePreferenceSource };