mazey 5.6.10 → 5.7.0

package/README.md

@@ -121,6 +121,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 +140,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 +1129,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.
@@ -1636,6 +1663,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

package/README.zh-CN.md

@@ -111,6 +111,9 @@ isNumber(z, { isInfinityAsNumber: true }); // 输出: true
   - [longestComSubsequence](#longestcomsubsequence)
 - [浏览器信息](#浏览器信息)
   - [detectVisitorType](#detectvisitortype)
+  - [isPhone](#isphone)
+  - [isDesktop](#isdesktop)
+  - [isTablet](#istablet)
   - [getBrowserInfo](#getbrowserinfo)
   - [isSafePWAEnv](#issafepwaenv)
   - [isStandalonePWA](#isstandalonepwa)
@@ -1145,6 +1148,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
 
 获取浏览器信息。