mazey 5.6.10 → 5.7.1

package/README.md

@@ -34,6 +34,17 @@ You can also download and serve the
 [latest browser bundle](https://cdn.jsdelivr.net/npm/mazey@latest/lib/mazey.min.js)
 yourself.
 
+## Browser support
+
+Mazey supports Chrome 109+, Edge 109+, Firefox 115+, Safari 16.4+, iOS Safari
+16.4+, Android Chrome 109+, and Samsung Internet 21+. Package output can
+contain ES2022 syntax and does not include JavaScript polyfills. Internet
+Explorer, Opera Mini, KaiOS, the legacy Android Browser, and older browser
+versions are outside this support policy.
+
+Node.js 22 is used for development and continuous integration. Mazey does not
+declare a Node.js runtime compatibility range.
+
 ## Usage
 
 Example: Use a function to verify if a value is a number suitable for standard calculations and comparisons.
@@ -121,6 +132,7 @@ There are some examples maintained by hand below. For more information, please c
   - [Storage Helpers](#storage-helpers)
 - [DOM](#dom)
   - [Class Helpers](#class-helpers)
+  - [hide and show](#hide-and-show)
   - [isValidCssSelector](#isvalidcssselector)
   - [resolveElementTarget](#resolveelementtarget)
   - [extractElementText](#extractelementtext)
@@ -139,6 +151,9 @@ There are some examples maintained by hand below. For more information, please c
   - [resolveLanguagePreference](#resolvelanguagepreference)
   - [setLanguagePreference](#setlanguagepreference)
   - [detectVisitorType](#detectvisitortype)
+  - [isPhone](#isphone)
+  - [isDesktop](#isdesktop)
+  - [isTablet](#istablet)
   - [isIOS](#isios)
   - [isAndroid](#isandroid)
   - [isMacOS](#ismacos)
@@ -1125,6 +1140,29 @@ addClass(dom, "test");
 removeClass(dom, "test");
 ```
 
+#### hide and show
+
+Hide or show a CSS selector, one element, or an iterable or array-like element
+collection. Both helpers return the original target, so a caller can retain its
+own chaining convention. Duplicate elements are changed only once, and invalid
+selectors or unsupported values are ignored.
+
+`hide()` preserves a visible element's inline `display` value. `show()` restores
+that value, or recovers the element's normal display when a stylesheet would
+otherwise keep it hidden.
+
+```javascript
+import { hide, show } from "mazey";
+
+const notices = document.querySelectorAll(".notice");
+
+hide(notices);
+show(notices);
+
+hide("#temporary-message");
+show(document.querySelector("#temporary-message"));
+```
+
 #### isValidCssSelector
 
 Check whether a value is a CSS selector supported by the supplied query root.
@@ -1541,8 +1579,8 @@ Output: `true`
 
 #### listenMediaQueryChanges
 
-Register a media-query change callback using the modern event API or the
-legacy `addListener` fallback. The returned cleanup function is idempotent.
+Register a media-query change callback using the standard `change` event. The
+returned cleanup function is idempotent.
 
 ```javascript
 const media = window.matchMedia("(prefers-color-scheme: dark)");
@@ -1636,6 +1674,84 @@ or changed, so false positives and false negatives are possible.
 > generally requires server-side request information and provider-specific
 > validation.
 
+#### isPhone
+
+Check whether the current browser represents a phone or handset-class device.
+The result excludes tablets.
+
+```javascript
+const result = isPhone();
+
+console.log(result);
+```
+
+#### isDesktop
+
+Check whether the current browser represents a desktop or laptop-class device.
+Recognized touchscreen Windows laptops remain desktop devices.
+
+```javascript
+const result = isDesktop();
+
+console.log(result);
+```
+
+#### isTablet
+
+Check whether the current browser represents a tablet. The helper recognizes
+conventional iPads, modern iPadOS desktop mode, Android user agents without a
+`Mobile` token, and bounded `Tablet` tokens.
+
+```javascript
+const result = isTablet();
+
+console.log(result);
+```
+
+You can pass a user-agent string for deterministic or server-side
+classification:
+
+```javascript
+const result = isTablet(
+  "Mozilla/5.0 (Linux; Android 14; SM-X710) AppleWebKit/537.36"
+);
+
+console.log(result);
+```
+
+Output:
+
+```text
+true
+```
+
+The three helpers use mutually exclusive form-factor classifications for
+recognized devices:
+
+| Device         | `isPhone` | `isDesktop` | `isTablet` |
+|:---------------|:-----------|:------------|:-----------|
+| iPhone         | `true`     | `false`     | `false`    |
+| Android phone  | `true`     | `false`     | `false`    |
+| iPad           | `false`    | `false`     | `true`     |
+| Android tablet | `false`    | `false`     | `true`     |
+| Windows laptop | `false`    | `true`      | `false`    |
+| MacBook        | `false`    | `true`      | `false`    |
+| Unknown        | `false`    | `false`     | `false`    |
+
+Each helper accepts an optional explicit user-agent string. Explicit input does
+not borrow the current browser's platform or touch signals. Without explicit
+input, all three return `false` during SSR when browser signals are unavailable.
+
+Device classification is heuristic and spoofable. It does not use viewport
+width and is not a security API or a replacement for responsive CSS and feature
+detection. `getBrowserInfo().platform` remains a legacy broad grouping that
+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
+number and does not inspect the browser or device.
+
 #### isIOS
 
 Check whether the current browser represents iOS or iPadOS. The current-browser
@@ -1791,10 +1907,10 @@ if (isStandalonePWA()) {
 
 #### getPerformance
 
-Get page load time(`PerformanceNavigationTiming`).
+Get page-load metrics from `PerformanceNavigationTiming`.
 
-This function uses the [`PerformanceNavigationTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming) API to get page load time data.
-The `PerformanceNavigationTiming` API provides more accurate and detailed information about page load time than the deprecated [`PerformanceTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceTiming) API.
+This function rejects when the browser does not provide a navigation entry. It
+does not fall back to the deprecated `PerformanceTiming` API.
 
 Usage:
 

package/README.zh-CN.md

@@ -28,6 +28,12 @@ npm install mazey
 
 你也可以下载 [jsdelivr/lib/mazey.min.js](https://cdn.jsdelivr.net/npm/mazey@latest/lib/mazey.min.js)，并自行托管该文件。
 
+## 浏览器支持
+
+Mazey 支持 Chrome 109 及以上版本、Edge 109 及以上版本、Firefox 115 及以上版本、Safari 16.4 及以上版本、iOS Safari 16.4 及以上版本、Android Chrome 109 及以上版本，以及 Samsung Internet 21 及以上版本。软件包输出可能包含 ES2022 语法，并且不包含 JavaScript polyfill。Internet Explorer、Opera Mini、KaiOS、旧版 Android Browser 和更早的浏览器版本不在支持范围内。
+
+开发和持续集成环境使用 Node.js 22。Mazey 未声明 Node.js 运行时兼容范围。
+
 ## 使用
 
 下面的示例使用一个函数，判断某个值是否适合参与常规计算和比较。
@@ -111,6 +117,9 @@ isNumber(z, { isInfinityAsNumber: true }); // 输出: true
   - [longestComSubsequence](#longestcomsubsequence)
 - [浏览器信息](#浏览器信息)
   - [detectVisitorType](#detectvisitortype)
+  - [isPhone](#isphone)
+  - [isDesktop](#isdesktop)
+  - [isTablet](#istablet)
   - [getBrowserInfo](#getbrowserinfo)
   - [isSafePWAEnv](#issafepwaenv)
   - [isStandalonePWA](#isstandalonepwa)
@@ -1145,6 +1154,70 @@ crawler
 
 > `unknown` 不表示访问者已经通过真人验证。此函数只使用浏览器端启发式规则，不能作为安全边界。请勿单独使用此结果进行身份验证、授权、支付决策、速率限制、欺诈防范或访问控制。验证真实爬虫通常需要服务端请求信息，以及服务提供商规定的验证流程。
 
+#### isPhone
+
+检查当前浏览器是否代表手机或手持设备。此结果不包含平板电脑。
+
+```javascript
+const result = isPhone();
+
+console.log(result);
+```
+
+#### isDesktop
+
+检查当前浏览器是否代表桌面或笔记本电脑。触摸屏 Windows 笔记本电脑仍归类为桌面设备。
+
+```javascript
+const result = isDesktop();
+
+console.log(result);
+```
+
+#### isTablet
+
+检查当前浏览器是否代表平板电脑。此函数支持常规 iPad 和 iPadOS 桌面模式。他还支持不含 `Mobile` 令牌的 Android User-Agent，以及独立的 `Tablet` 令牌。
+
+```javascript
+const result = isTablet();
+
+console.log(result);
+```
+
+可以传入 User-Agent 字符串。此方式适合确定性测试或服务端分类。
+
+```javascript
+const result = isTablet(
+  "Mozilla/5.0 (Linux; Android 14; SM-X710) AppleWebKit/537.36"
+);
+
+console.log(result);
+```
+
+输出：
+
+```text
+true
+```
+
+对于已识别的设备，这 3 个函数使用互斥的设备形态分类：
+
+| 设备             | `isPhone` | `isDesktop` | `isTablet` |
+|:-----------------|:-----------|:------------|:-----------|
+| iPhone           | `true`     | `false`     | `false`    |
+| Android 手机     | `true`     | `false`     | `false`    |
+| iPad             | `false`    | `false`     | `true`     |
+| Android 平板电脑 | `false`    | `false`     | `true`     |
+| Windows 笔记本   | `false`    | `true`      | `false`    |
+| MacBook          | `false`    | `true`      | `false`    |
+| 未知设备         | `false`    | `false`     | `false`    |
+
+每个函数都接受可选的 User-Agent 字符串。显式输入不会读取当前浏览器的平台或触摸信号。SSR 环境无法读取浏览器信号且没有显式输入时，这 3 个函数均返回 `false`。
+
+设备分类使用可伪造的启发式规则，不读取视口宽度。这些函数不能作为安全 API，也不能替代响应式 CSS 和功能检测。`getBrowserInfo().platform` 保留原有的宽泛分类，并将 iOS 和 Android 报告为 `"mobile"`。新函数提供更具体的手机、平板电脑或桌面设备分类。
+
+`isPhone` 用于检查设备形态。独立的 `isMobile` API 是 `isValidPhoneNumber` 的直接别名，用于验证 11 位中国手机号码形式的字符串，不会检查浏览器或设备。
+
 #### getBrowserInfo
 
 获取浏览器信息。
@@ -1219,9 +1292,9 @@ if (isStandalonePWA()) {
 
 #### getPerformance
 
-获取页面加载时间 (`PerformanceNavigationTiming`)。
+通过 `PerformanceNavigationTiming` 获取页面加载指标。
 
-该函数使用 [`PerformanceNavigationTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming) API 获取页面加载数据。与已弃用的 [`PerformanceTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceTiming) API 相比，新 API 提供的数据更准确，也更详细。
+如果浏览器未提供导航条目，该函数返回的 Promise 会进入 rejected 状态。函数不会回退到已弃用的 `PerformanceTiming` API。
 
 用法: