mazey 5.10.0 → 5.10.2

package/README.md

@@ -81,6 +81,9 @@ There are some examples maintained by hand below. For more information, please c
   - [isNullish](#isnullish)
   - [isJSONString](#isjsonstring)
   - [parseJsonSafe](#parsejsonsafe)
+  - [isCNMobileNumber](#iscnmobilenumber)
+  - [escapeHTML and unescapeHTML](#escapehtml-and-unescapehtml)
+  - [truncateByWeightedLength](#truncatebyweightedlength)
   - [escapeHtmlAttribute](#escapehtmlattribute)
   - [sha256Hex](#sha256hex)
   - [isValidData](#isvaliddata)
@@ -105,10 +108,13 @@ There are some examples maintained by hand below. For more information, please c
   - [debounce](#debounce)
   - [throttle](#throttle)
   - [convertCamelToKebab](#convertcameltokebab)
-  - [convertCamelToUnder](#convertcameltounder)
+  - [convertCamelToSnake](#convertcameltosnake)
+  - [convertSnakeToCamel](#convertsnaketocamel)
+  - [formatPercentage](#formatpercentage)
   - [toJavaScriptGlobalName](#tojavascriptglobalname)
   - [derivePackageMetadata](#derivepackagemetadata)
 - [URL](#url)
+  - [getURLPathExtension](#geturlpathextension)
   - [getQueryParam](#getqueryparam)
   - [getUrlParam](#geturlparam)
   - [getHashQueryParam](#gethashqueryparam)
@@ -127,7 +133,7 @@ There are some examples maintained by hand below. For more information, please c
   - [resolveElementTarget](#resolveelementtarget)
   - [extractElementText](#extractelementtext)
   - [injectStyle](#injectstyle)
-  - [genStyleString](#genstylestring)
+  - [createCSSRule](#createcssrule)
   - [newLine](#newline)
 - [Event](#event)
   - [onEvent](#onevent)
@@ -153,6 +159,7 @@ There are some examples maintained by hand below. For more information, please c
   - [isWindows](#iswindows)
   - [isLinux](#islinux)
   - [getBrowserInfo](#getbrowserinfo)
+  - [getBrowserClassNames](#getbrowserclassnames)
   - [isSafePWAEnv](#issafepwaenv)
   - [isStandalonePWA](#isstandalonepwa)
   - [listenMediaQueryChanges](#listenmediaquerychanges)
@@ -373,6 +380,55 @@ const fallback = parseJsonSafe("invalid", {});
 console.log(data, fallback);
 ```
 
+#### isCNMobileNumber
+
+Check the Chinese mobile-number format: `1` followed by ten digits. This checks
+format only, without verifying assigned prefixes, ownership, or reachability.
+
+```javascript
+import { isCNMobileNumber } from "mazey";
+
+isCNMobileNumber("13800138000"); // true
+isCNMobileNumber("+8613800138000"); // false
+```
+
+`isValidPhoneNumber` and `isMobile` remain deprecated aliases.
+
+#### escapeHTML and unescapeHTML
+
+Escape six HTML-sensitive characters or decode that fixed entity set in one
+pass. These helpers do not sanitize arbitrary HTML or validate URLs.
+`unescapeHTML` preserves unrecognized entities.
+
+```javascript
+import { escapeHTML, unescapeHTML } from "mazey";
+
+escapeHTML('<b title="x">A&B</b>');
+// '&lt;b title=&quot;x&quot;&gt;A&amp;B&lt;&#x2F;b&gt;'
+unescapeHTML("&lt;b&gt;A&amp;B&lt;&#x2F;b&gt;");
+// "<b>A&B</b>"
+```
+
+`sanitizeInput` and `unsanitizeInput` remain deprecated aliases. The legacy
+`unsanitize` alias also remains available.
+
+#### truncateByWeightedLength
+
+Truncate 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 limit. This does not measure bytes or rendered width and can
+split surrogate pairs.
+
+```javascript
+import { truncateByWeightedLength } from "mazey";
+
+truncateByWeightedLength("Hello世界", 7); // "Hello世"
+truncateByWeightedLength("Hello世界", 7, { hasDot: true }); // "Hello世..."
+```
+
+`cutZHString` remains a deprecated alias. The legacy `truncateZHString` and
+`cutCHSString` signatures retain their boolean `hasDot` argument.
+
 #### escapeHtmlAttribute
 
 Escape text for use inside a quoted HTML attribute without escaping `/`.
@@ -836,15 +892,18 @@ a-b-c
 a-b-c
 ```
 
-#### convertCamelToUnder
+#### convertCamelToSnake
 
-Transfer CamelCase to Underscore.
+Insert an underscore before each uppercase ASCII letter, lowercase the result,
+and remove one leading underscore. `XMLParser` becomes `x_m_l_parser`.
+Other existing underscores are preserved. `convertCamelToUnder` remains a
+deprecated direct alias; `camelCase2Underscore` remains available.
 
 Usage:
 
 ```javascript
-const ret1 = convertCamelToUnder("ABC");
-const ret2 = convertCamelToUnder("aBC");
+const ret1 = convertCamelToSnake("ABC");
+const ret2 = convertCamelToSnake("aBC");
 console.log(ret1);
 console.log(ret2);
 ```
@@ -856,6 +915,32 @@ a_b_c
 a_b_c
 ```
 
+#### convertSnakeToCamel
+
+Replace `_` followed by a lowercase ASCII letter with its uppercase letter.
+Other underscores and characters remain unchanged. `convertUnderToCamel`
+remains a deprecated direct alias.
+
+```javascript
+convertSnakeToCamel("a_b_c"); // "aBC"
+convertSnakeToCamel("a__b_"); // "a_B_"
+```
+
+#### formatPercentage
+
+Multiply a numeric ratio by 100 and append `%`. Precision defaults to `0`.
+Falsy precision uses `Math.floor`, including for negative values; truthy
+precision uses native `toFixed`, preserving trailing zeros, floating-point
+behavior, and exceptions for unsupported precision. `floatToPercent` remains
+a deprecated direct alias.
+
+```javascript
+formatPercentage(0.129); // "12%"
+formatPercentage(-0.129); // "-13%"
+formatPercentage(0.125, 1); // "12.5%"
+formatPercentage(0.12, 2); // "12.00%"
+```
+
 #### toJavaScriptGlobalName
 
 Convert text to a deterministic uppercase ASCII identifier suitable for an
@@ -912,6 +997,23 @@ manifest.
 
 ### URL
 
+#### getURLPathExtension
+
+Extract a file extension from a URL or path, excluding query and fragment text.
+This helper does not detect MIME types or inspect file contents.
+It preserves the existing string-based behavior: `archive.tar.gz` returns
+`tar.gz`, and an origin-only input such as `https://example.com` returns `com`.
+
+```javascript
+import { getURLPathExtension } from "mazey";
+
+getURLPathExtension("https://example.com/image.png?width=200#preview"); // "png"
+getURLPathExtension("/images/photo.jpg"); // "jpg"
+getURLPathExtension("/images/photo"); // ""
+```
+
+`getUrlFileType` remains a deprecated alias.
+
 #### getQueryParam
 
 Get the query param's value of the current Web URL(`location.search`).
@@ -1264,18 +1366,18 @@ Output:
 <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'`,
@@ -1295,15 +1397,19 @@ Output:
 <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>
 ```
 
-#### genStyleString
+#### createCSSRule
 
-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. The helper
+joins declarations with semicolons without validating or escaping CSS.
+`genStyleString` remains a deprecated alias.
 
 Usage:
 
 ```javascript
-const ret1 = genStyleString(".a", [ "color:red" ]);
-const ret2 = genStyleString("#b", [ "color:red", "font-size:12px" ]);
+import { createCSSRule } from "mazey";
+
+const ret1 = createCSSRule(".a", [ "color:red" ]);
+const ret2 = createCSSRule("#b", [ "color:red", "font-size:12px" ]);
 console.log(ret1);
 console.log(ret2);
 ```
@@ -1315,18 +1421,18 @@ Output:
 #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'`,
@@ -1421,7 +1527,7 @@ The dates may be supported structured date strings, millisecond timestamps, or `
 Number input is a decimal ratio, so `0.202` represents `20.2%`. String input is a percentage value, so `"20.2%"` and `"20.2"` both represent `20.2%`; strict scientific notation such as `"2.02e1%"` is also accepted. The returned CAGR is an unrounded decimal ratio.
 
 ```javascript
-import { calculateCAGR, floatToPercent } from "mazey";
+import { calculateCAGR, formatPercentage } from "mazey";
 
 const cagr = calculateCAGR(
   "2022-04-01",
@@ -1431,7 +1537,7 @@ const cagr = calculateCAGR(
 
 console.log({
   cagr,
-  percentage: floatToPercent(cagr, 2),
+  percentage: formatPercentage(cagr, 2),
 });
 ```
 
@@ -1815,7 +1921,7 @@ reports iOS and Android as `"mobile"`; the new helpers provide a more specific
 phone, tablet, or desktop classification.
 
 `isPhone` checks device form factor. The separate `isMobile` API is a direct
-alias of `isValidPhoneNumber`; it validates an 11-digit Chinese mobile-shaped
+alias of `isCNMobileNumber`; it validates an 11-digit Chinese mobile-shaped
 number and does not inspect the browser or device.
 
 #### isIOS
@@ -1930,6 +2036,20 @@ const { system, shell } = getBrowserInfo();
 const isMobileQQ = ["android", "ios"].includes(system) && ["qq_browser", "qq_app"].includes(shell);
 ```
 
+#### getBrowserClassNames
+
+Return class-name tokens from the cached browser classification. An optional
+prefix and separator apply to each token; the helper does not modify the DOM.
+
+```javascript
+import { getBrowserClassNames } from "mazey";
+
+console.log(getBrowserClassNames("browser"));
+// Possible output: ["browser-windows", "browser-desktop", "browser-webkit", "browser-chrome"]
+```
+
+`genBrowserAttrs` remains a deprecated alias.
+
 #### isSafePWAEnv
 
 Detect whether the current browser document provides the minimum prerequisites

package/README.zh-CN.md

@@ -92,7 +92,9 @@ isNumber(z, { isInfinityAsNumber: true }); // 输出: true
   - [debounce](#debounce)
   - [throttle](#throttle)
   - [convertCamelToKebab](#convertcameltokebab)
-  - [convertCamelToUnder](#convertcameltounder)
+  - [convertCamelToSnake](#convertcameltosnake)
+  - [convertSnakeToCamel](#convertsnaketocamel)
+  - [formatPercentage](#formatpercentage)
   - [toJavaScriptGlobalName](#tojavascriptglobalname)
 - [URL](#url)
   - [getQueryParam](#getqueryparam)
@@ -599,15 +601,17 @@ a-b-c
 a-b-c
 ```
 
-#### convertCamelToUnder
+#### convertCamelToSnake
 
-将驼峰命名转换为下划线命名。
+在每个 ASCII 大写字母前插入下划线，将结果转换为小写，并删除第一个前导下划线。
+`XMLParser` 转换为 `x_m_l_parser`，其余已有下划线保留。
+`convertCamelToUnder` 保留为弃用的直接别名，`camelCase2Underscore` 仍可使用。
 
 用法:
 
 ```javascript
-const ret1 = convertCamelToUnder("ABC");
-const ret2 = convertCamelToUnder("aBC");
+const ret1 = convertCamelToSnake("ABC");
+const ret2 = convertCamelToSnake("aBC");
 console.log(ret1);
 console.log(ret2);
 ```
@@ -619,6 +623,30 @@ a_b_c
 a_b_c
 ```
 
+#### convertSnakeToCamel
+
+将下划线及其后的 ASCII 小写字母替换为大写字母，其他字符保持不变。
+`convertUnderToCamel` 保留为弃用的直接别名。
+
+```javascript
+convertSnakeToCamel("a_b_c"); // "aBC"
+convertSnakeToCamel("a__b_"); // "a_B_"
+```
+
+#### formatPercentage
+
+将数值比率乘以 100 并添加 `%`。小数位数默认为 `0`。
+小数位数为假值时使用 `Math.floor`，负数也向下取整；为真值时使用原生 `toFixed`，
+保留末尾零、浮点数行为，以及不支持的小数位数导致的异常。
+`floatToPercent` 保留为弃用的直接别名。
+
+```javascript
+formatPercentage(0.129); // "12%"
+formatPercentage(-0.129); // "-13%"
+formatPercentage(0.125, 1); // "12.5%"
+formatPercentage(0.12, 2); // "12.00%"
+```
+
 #### toJavaScriptGlobalName
 
 将文本转换为确定的、全大写的 ASCII JavaScript 标识符。该标识符适合作为 IIFE 全局名称。函数会将无效字符替换为下划线。结果以数字开头时，函数会添加下划线前缀。
@@ -1097,7 +1125,7 @@ CAGR = (1 + totalReturnRate)^(365 / durationInDays) - 1
 数值输入使用十进制比率，因此 `0.202` 表示 `20.2%`。字符串输入使用百分比数值，因此 `"20.2%"` 和 `"20.2"` 都表示 `20.2%`；也支持 `"2.02e1%"` 这类严格的科学记数法。返回的 CAGR 是未经舍入的十进制比率。
 
 ```javascript
-import { calculateCAGR, floatToPercent } from "mazey";
+import { calculateCAGR, formatPercentage } from "mazey";
 
 const cagr = calculateCAGR(
   "2022-04-01",
@@ -1107,7 +1135,7 @@ const cagr = calculateCAGR(
 
 console.log({
   cagr,
-  percentage: floatToPercent(cagr, 2),
+  percentage: formatPercentage(cagr, 2),
 });
 ```