mazey 5.10.0 → 5.10.1

package/lib/index.d.ts

@@ -1782,37 +1782,50 @@ declare function escapeHtmlAttribute(value: string, options?: {
     preserveEntities?: boolean;
 }): string;
 /**
- * Sanitizes user input to prevent XSS attacks.
+ * Escape ampersands, angle brackets, quotes, and forward slashes as HTML entities.
+ *
+ * This performs character escaping only. It does not sanitize arbitrary HTML,
+ * validate URLs, or make every HTML, JavaScript, or CSS context safe.
  *
  * Usage:
  *
  * ```javascript
- * import { sanitizeInput } from "mazey";
+ * import { escapeHTML } from "mazey";
  *
- * const ret = sanitizeInput("<div>hello world</div>");
+ * const ret = escapeHTML("<div>hello world</div>");
  * console.log(ret);
  * ```
  *
  * Output:
  *
  * ```text
- * &lt;div&gt;hello world&lt;/div&gt;
+ * &lt;div&gt;hello world&lt;&#x2F;div&gt;
  * ```
  *
- * @param input - The input string to sanitize
- * @returns The sanitized input string
+ * @param input The string to escape.
+ * @returns The escaped string.
+ * @category Util
+ */
+declare function escapeHTML(input: string): string;
+/**
+ * Deprecated alias of {@link escapeHTML}.
+ *
+ * @deprecated Use `escapeHTML` instead.
  * @category Util
  */
-declare function sanitizeInput(input: string): string;
+declare const sanitizeInput: typeof escapeHTML;
 /**
- * Reverses the sanitization done by the `sanitizeInput` function.
+ * Decode the fixed HTML entity set emitted by {@link escapeHTML}.
+ *
+ * Decoding uses one pass and preserves unrecognized entities. This is not a
+ * general HTML entity decoder, and the result may contain active HTML markup.
  *
  * Usage:
  *
  * ```javascript
- * import { unsanitizeInput } from "mazey";
+ * import { unescapeHTML } from "mazey";
  *
- * const ret = unsanitizeInput("&lt;div&gt;hello world&lt;/div&gt;");
+ * const ret = unescapeHTML("&lt;div&gt;hello world&lt;&#x2F;div&gt;");
  * console.log(ret);
  * ```
  *
@@ -1822,27 +1835,37 @@ declare function sanitizeInput(input: string): string;
  * <div>hello world</div>
  * ```
  *
- * @param input - The input string to unsanitize
- * @returns The unsanitized input string
+ * @param input The string containing escaped characters.
+ * @returns The decoded string.
+ * @category Util
+ */
+declare function unescapeHTML(input: string): string;
+/**
+ * Deprecated alias of {@link unescapeHTML}.
+ *
+ * @deprecated Use `unescapeHTML` instead.
  * @category Util
  */
-declare function unsanitizeInput(input: string): string;
+declare const unsanitizeInput: typeof unescapeHTML;
 /**
- * Alias of `unsanitizeInput`.
+ * Alias of `unescapeHTML`.
  *
  * @hidden
  */
 declare function unsanitize(str: string): string;
 /**
- * Truncate a string by weighted length, counting non-ASCII characters as two
- * units.
+ * Truncate a string by weighted UTF-16 length.
+ *
+ * Code units from U+0000 through U+00FF count as one; all other code units
+ * count as two. Optional truncation text is appended after the length limit.
+ * This does not measure bytes or rendered width and can split surrogate pairs.
  *
  * Usage:
  *
  * ```javascript
- * import { cutZHString } from "mazey";
+ * import { truncateByWeightedLength } from "mazey";
  *
- * const ret = cutZHString("hello world", 5);
+ * const ret = truncateByWeightedLength("hello world", 5);
  * console.log(ret);
  * ```
  *
@@ -1859,12 +1882,19 @@ declare function unsanitize(str: string): string;
  * @returns {string} The truncated string.
  * @category Util
  */
-declare function cutZHString(str: string | null | undefined, len: number, options?: {
+declare function truncateByWeightedLength(str: string | null | undefined, len: number, options?: {
     hasDot?: boolean;
     dotText?: string;
 }): string;
 /**
- * Alias of `cutZHString`.
+ * Deprecated alias of {@link truncateByWeightedLength}.
+ *
+ * @deprecated Use `truncateByWeightedLength` instead.
+ * @category Util
+ */
+declare const cutZHString: typeof truncateByWeightedLength;
+/**
+ * Alias of `truncateByWeightedLength`.
  *
  * Usage:
  *
@@ -2037,17 +2067,20 @@ declare function genHashCode(str: string): number;
  */
 declare function sha256Hex(input: string | BufferSource): Promise<string>;
 /**
- * Check if the given string is a mobile phone number.
+ * Check whether a string has the 11-digit Chinese mobile-number format.
+ *
+ * The pattern requires a leading `1` followed by ten digits. It does not
+ * verify assigned prefixes, ownership, reachability, or international formats.
  *
  * Usage:
  *
  * ```javascript
- * import { isValidPhoneNumber } from "mazey";
+ * import { isCNMobileNumber } from "mazey";
  *
- * const ret1 = isValidPhoneNumber("13800138000");
- * const ret2 = isValidPhoneNumber("1380013800");
- * const ret3 = isValidPhoneNumber("138001380000");
- * const ret4 = isValidPhoneNumber("1380013800a");
+ * const ret1 = isCNMobileNumber("13800138000");
+ * const ret2 = isCNMobileNumber("1380013800");
+ * const ret3 = isCNMobileNumber("138001380000");
+ * const ret4 = isCNMobileNumber("1380013800a");
  * console.log(ret1, ret2, ret3, ret4);
  * ```
  *
@@ -2057,21 +2090,28 @@ declare function sha256Hex(input: string | BufferSource): Promise<string>;
  * true false false false
  * ```
  *
- * @param mobile
- * @returns {boolean} Return true if the given string is a mobile phone number.
+ * @param mobile The string to check.
+ * @returns Whether the string matches the Chinese mobile-number format.
  * @category Util
  */
-declare function isValidPhoneNumber(mobile: string): boolean;
+declare function isCNMobileNumber(mobile: string): boolean;
 /**
- * Deprecated alias of {@link isValidPhoneNumber}.
+ * Deprecated alias of {@link isCNMobileNumber}.
+ *
+ * @deprecated Use `isCNMobileNumber` instead.
+ * @category Util
+ */
+declare const isValidPhoneNumber: typeof isCNMobileNumber;
+/**
+ * Deprecated alias of {@link isCNMobileNumber}.
  *
  * This helper validates an 11-digit Chinese mobile-shaped number. It does not
  * detect a browser's device form factor; use `isPhone` for that purpose.
  *
- * @deprecated Use `isValidPhoneNumber` instead.
+ * @deprecated Use `isCNMobileNumber` instead.
  * @category Util
  */
-declare const isMobile: typeof isValidPhoneNumber;
+declare const isMobile: typeof isCNMobileNumber;
 /**
  * Check if the given string is a valid email.
  *
@@ -2487,18 +2527,23 @@ declare function isValidHttpUrl(url: string, options?: {
     strict: boolean;
 }): boolean;
 /**
- * Get the file extension from a URL or path.
+ * Extract the extension from a URL or path after removing query and fragment text.
+ *
+ * This string-based helper does not inspect file contents or detect MIME types.
+ * It retains everything after the first dot in the final slash-delimited
+ * segment, so `archive.tar.gz` returns `tar.gz`. It does not parse URL authority:
+ * an origin-only input such as `https://example.com` returns `com`.
  *
  * Usage:
  *
  * ```javascript
- * import { getUrlFileType } from "mazey";
+ * import { getURLPathExtension } from "mazey";
  *
- * const ret1 = getUrlFileType("https://example.com/a/b/c.png");
- * const ret2 = getUrlFileType("https://example.com/a/b/c.jpg");
- * const ret3 = getUrlFileType("https://example.com/a/b/c.jpeg");
- * const ret4 = getUrlFileType("/a/b/c.jpeg");
- * const ret5 = getUrlFileType("https://example.com/a/b/c.v/a");
+ * const ret1 = getURLPathExtension("https://example.com/a/b/c.png");
+ * const ret2 = getURLPathExtension("https://example.com/a/b/c.jpg");
+ * const ret3 = getURLPathExtension("https://example.com/a/b/c.jpeg");
+ * const ret4 = getURLPathExtension("/a/b/c.jpeg");
+ * const ret5 = getURLPathExtension("https://example.com/a/b/c.v/a");
  * console.log(ret1, ret2, ret3, ret4, ret5);
  * ```
  *
@@ -2508,11 +2553,18 @@ declare function isValidHttpUrl(url: string, options?: {
  * png jpg jpeg jpeg ""
  * ```
  *
- * @param url
- * @returns
+ * @param url The URL or path to inspect.
+ * @returns The extension without the leading dot, or an empty string when absent.
  * @category URL
  */
-declare function getUrlFileType(url: string): boolean | string;
+declare function getURLPathExtension(url: string): boolean | string;
+/**
+ * Deprecated alias of {@link getURLPathExtension}.
+ *
+ * @deprecated Use `getURLPathExtension` instead.
+ * @category URL
+ */
+declare const getUrlFileType: typeof getURLPathExtension;
 /**
  * Retrieve a query parameter from a script URL in the browser.
  *
@@ -2697,10 +2749,10 @@ declare function hasClass(obj: MazeyElement, cls: string): boolean;
  * Advanced Usage:
  *
  * ```javascript
- * import { addClass, genBrowserAttrs } from "mazey";
+ * import { addClass, getBrowserClassNames } from "mazey";
  *
  * const ele = document.querySelector("html");
- * addClass(ele, genBrowserAttrs());
+ * addClass(ele, getBrowserClassNames());
  * ```
  *
  * Output:
@@ -2774,18 +2826,18 @@ declare function removeClass(obj: MazeyElement, cls: string): void;
  * <style>body { background-color: #444; }</style>
  * ```
  *
- * Example 3: Combine `genStyleString` and `injectStyle` to add multiple styles at once.
+ * Example 3: Combine `createCSSRule` and `injectStyle` to add multiple styles at once.
  *
  * ```javascript
- * import { genStyleString, injectStyle } from "mazey";
+ * import { createCSSRule, injectStyle } from "mazey";
  *
- * const xStyle = genStyleString(
+ * const xStyle = createCSSRule(
  *   ".footer>.x-wish>a:first-child" +
  *   ",div.wish-flex>a[href^='https://github.com/chengchuu']" +
  *   ",.m-hide",
  *   [ "display: none" ]
  * );
- * const yStyle = genStyleString(
+ * const yStyle = createCSSRule(
  *   ".footer>.y-wish:before",
  *   [
  *     `content: 'Copyright (c) chengchuu'`,
@@ -2855,13 +2907,16 @@ declare function setImgSizeBySrc(): boolean;
  */
 declare function setImgWidHeiBySrc(): boolean;
 /**
- * Generate the inline style string from the given parameters. The first parameter is the query selector, and the second parameter is the style array.
+ * Create CSS rule text from a selector and an array of declarations.
+ *
+ * Declarations are joined with semicolons. The selector and declarations are
+ * used verbatim without validation or escaping; this function does not modify the DOM.
  *
  * Usage:
  *
  * ```javascript
- * const ret1 = genStyleString(".a", [ "color:red" ]);
- * const ret2 = genStyleString("#b", [ "color:red", "font-size:12px" ]);
+ * const ret1 = createCSSRule(".a", [ "color:red" ]);
+ * const ret2 = createCSSRule("#b", [ "color:red", "font-size:12px" ]);
  * console.log(ret1);
  * console.log(ret2);
  * ```
@@ -2873,18 +2928,18 @@ declare function setImgWidHeiBySrc(): boolean;
  * #b{color:red;font-size:12px;}
  * ```
  *
- * Example: Combine `genStyleString` and `injectStyle` to add multiple styles at once.
+ * Example: Combine `createCSSRule` and `injectStyle` to add multiple styles at once.
  *
  * ```javascript
- * import { genStyleString, injectStyle } from "mazey";
+ * import { createCSSRule, injectStyle } from "mazey";
  *
- * const xStyle = genStyleString(
+ * const xStyle = createCSSRule(
  *   ".footer>.x-wish>a:first-child" +
  *   ",div.wish-flex>a[href^='https://github.com/chengchuu']" +
  *   ",.m-hide",
  *   [ "display: none" ]
  * );
- * const yStyle = genStyleString(
+ * const yStyle = createCSSRule(
  *   ".footer>.y-wish:before",
  *   [
  *     `content: 'Copyright (c) chengchuu'`,
@@ -2906,10 +2961,17 @@ declare function setImgWidHeiBySrc(): boolean;
  *
  * @param {string} selector
  * @param {array} styleArray
- * @returns {string} The inline style string.
+ * @returns {string} The CSS selector and declaration block.
  * @category DOM
  */
-declare function genStyleString(selector: string, styleArray: Array<string>): string;
+declare function createCSSRule(selector: string, styleArray: Array<string>): string;
+/**
+ * Deprecated alias of {@link createCSSRule}.
+ *
+ * @deprecated Use `createCSSRule` instead.
+ * @category DOM
+ */
+declare const genStyleString: typeof createCSSRule;
 /**
  * Get the value of the meta tag by the given name.
  *
@@ -3848,7 +3910,7 @@ type VisitorType = "crawler" | "automation" | "unknown";
  * @remarks Device classification is heuristic and spoofable. Do not use this
  * helper as a security boundary or as a substitute for responsive CSS or
  * feature detection. It does not inspect viewport dimensions. The separate
- * `isMobile` export is an alias of the `isValidPhoneNumber` string validator.
+ * `isMobile` export is an alias of the `isCNMobileNumber` string validator.
  * @category Browser Information
  */
 declare function isPhone(userAgent?: string): boolean;
@@ -4224,14 +4286,17 @@ declare function isStandalonePWA(options?: IsStandalonePWAOptions): boolean;
  */
 declare function getBrowserInfo(): BrowserInfo;
 /**
- * Generate browser attributes from the detected browser information.
+ * Get CSS class-name tokens from the cached browser classification.
+ *
+ * Each available classification value receives the optional prefix and
+ * separator. This function returns strings without modifying the DOM.
  *
  * Usage:
  *
  * ```javascript
- * import { genBrowserAttrs } from "mazey";
+ * import { getBrowserClassNames } from "mazey";
  *
- * const attrs = genBrowserAttrs();
+ * const attrs = getBrowserClassNames();
  * console.log(attrs);
  * ```
  *
@@ -4242,11 +4307,19 @@ declare function getBrowserInfo(): BrowserInfo;
  * ```
  *
  * @remarks Browser only.
- * @param {string} prefix
- * @returns {array} Browser attributes
+ * @param prefix Optional prefix for every class name.
+ * @param separator Separator between a non-empty prefix and each value. Defaults to `-`.
+ * @returns Browser classification class names.
+ * @category Browser Information
+ */
+declare function getBrowserClassNames(prefix?: string, separator?: string): string[];
+/**
+ * Deprecated alias of {@link getBrowserClassNames}.
+ *
+ * @deprecated Use `getBrowserClassNames` instead.
  * @category Browser Information
  */
-declare function genBrowserAttrs(prefix?: string, separator?: string): string[];
+declare const genBrowserAttrs: typeof getBrowserClassNames;
 /**
  * Detect webp support.
  *
@@ -4655,5 +4728,5 @@ declare const mazeyCon: Console;
  */
 declare const timeCon: Console;
 
-export { addClass, addEvent, addStyle, assignDefined, calLongestCommonSubsequence, calLongestCommonSubstring, calculateAspectRatio, calculateCAGR, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, derivePackageMetadata, detectVisitorType, doFn, escapeHtmlAttribute, extractElementText, fireEvent, floatFixed, floatToPercent, formatByteSize, formatDate, formatDistanceToNow, formatDurationFromMs, formatLocalDateTime, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalJSON, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionJSON, getSessionStorage, getSystemTheme, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, hide, hideElements, inRate, injectStyle, invokeEvent, invokeFn, isAndroid, isArray, isBool, isBoolean, isBrowser, isDesktop, isFunction, isHit, isIOS, isJSONString, isJsonString, isLinux, isMacOS, isMobile, isNonEmptyArray, isNonEmptyObject, isNullish, isNumber, isPhone, isPureObject, isSafePWAEnv, isStandalonePWA, isString, isSupportWebp, isSupportedEntryType, isTablet, isThisHour, isThisMonth, isThisWeek, isThisYear, isToday, isUdfOrNul, isValidCssSelector, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, isWindows, listenMediaQueryChanges, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onEvent, onURLChange, parseGitHubRepository, parseJsonSafe, parseLocalDateTime, randomBoolean, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, resolveElementTarget, resolveLanguagePreference, resolveThemePreference, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLanguagePreference, setLocalJSON, setLocalStorage, setSessionJSON, setSessionStorage, setThemePreference, sha256Hex, show, showElements, sleep, subYears, throttle, timeCon, toJavaScriptGlobalName, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, watchServiceWorkerUpdates, windowLoaded, zAxiosIsValidRes };
+export { addClass, addEvent, addStyle, assignDefined, calLongestCommonSubsequence, calLongestCommonSubstring, calculateAspectRatio, calculateCAGR, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, createCSSRule, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, derivePackageMetadata, detectVisitorType, doFn, escapeHTML, escapeHtmlAttribute, extractElementText, fireEvent, floatFixed, floatToPercent, formatByteSize, formatDate, formatDistanceToNow, formatDurationFromMs, formatLocalDateTime, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserClassNames, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalJSON, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionJSON, getSessionStorage, getSystemTheme, getTTFB, getURLPathExtension, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, hide, hideElements, inRate, injectStyle, invokeEvent, invokeFn, isAndroid, isArray, isBool, isBoolean, isBrowser, isCNMobileNumber, isDesktop, isFunction, isHit, isIOS, isJSONString, isJsonString, isLinux, isMacOS, isMobile, isNonEmptyArray, isNonEmptyObject, isNullish, isNumber, isPhone, isPureObject, isSafePWAEnv, isStandalonePWA, isString, isSupportWebp, isSupportedEntryType, isTablet, isThisHour, isThisMonth, isThisWeek, isThisYear, isToday, isUdfOrNul, isValidCssSelector, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, isWindows, listenMediaQueryChanges, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onEvent, onURLChange, parseGitHubRepository, parseJsonSafe, parseLocalDateTime, randomBoolean, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, resolveElementTarget, resolveLanguagePreference, resolveThemePreference, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLanguagePreference, setLocalJSON, setLocalStorage, setSessionJSON, setSessionStorage, setThemePreference, sha256Hex, show, showElements, sleep, subYears, throttle, timeCon, toJavaScriptGlobalName, truncateByWeightedLength, truncateZHString, unescapeHTML, unsanitize, unsanitizeInput, updateQueryParam, waitTime, watchServiceWorkerUpdates, windowLoaded, zAxiosIsValidRes };
 export type { DerivePackageMetadataOptions, DerivedPackageMetadata, DomVisibilityTarget, FormatByteSizeOptions, GitHubRepositoryDetails, InvestmentReturnRate, IsNumberOptions, IsSafePWAEnvOptions, IsStandalonePWAOptions, LocalDateTimePrecision, PWAEnvironment, PackageManager, PackageManifest, PackageManifestAuthor, PreferenceResult, ResolveElementTargetOptions, ResolvedTheme, ServiceWorkerUpdateCallbacks, ServiceWorkerUpdateWatcher, ThemePreference, VisitorType };