mazey 5.9.1 → 5.10.0

package/lib/index.d.ts

@@ -277,9 +277,9 @@ declare function calLongestCommonSubsequence(aStr: string, bStr: string): number
  * Usage:
  *
  * ```javascript
- * import { isHit } from "mazey";
+ * import { randomBoolean } from "mazey";
  *
- * const ret = isHit(0.5); // A 50% chance of returning true.
+ * const ret = randomBoolean(0.5); // A 50% chance of returning true.
  * console.log(ret);
  * ```
  *
@@ -295,7 +295,7 @@ declare function calLongestCommonSubsequence(aStr: string, bStr: string): number
  * let trueCount = 0;
  * let falseCount = 0;
  * new Array(1000000).fill(0).forEach(() => {
- *   if (isHit(0.5)) {
+ *   if (randomBoolean(0.5)) {
  *     trueCount++;
  *   } else {
  *     falseCount++;
@@ -314,9 +314,18 @@ declare function calLongestCommonSubsequence(aStr: string, bStr: string): number
  * @returns {boolean} Whether the random value is less than the probability.
  * @category Calculate and Formula
  */
+declare function randomBoolean(rate: number): boolean;
+/**
+ * Deprecated alias of {@link randomBoolean}.
+ *
+ * @deprecated Use `randomBoolean` instead.
+ * @param rate Probability expressed as a value from 0 to 1.
+ * @returns Whether the random value is less than the probability.
+ * @category Calculate and Formula
+ */
 declare function isHit(rate: number): boolean;
 /**
- * Alias of `isHit`.
+ * Compatibility alias of {@link randomBoolean}.
  *
  * @hidden
  */
@@ -535,14 +544,14 @@ declare function formatLocalDateTime(date: Date, options?: {
  */
 declare function subYears(date: Date | number, amount: number): Date;
 /**
- * Get the current timestamp in milliseconds.
+ * Return the current timestamp in milliseconds.
+ *
+ * This compatibility helper delegates to native `Date.now()`.
  *
  * Usage:
  *
  * ```javascript
- * import { mNow } from "mazey";
- *
- * const ret = mNow();
+ * const ret = Date.now();
  * console.log(ret);
  * ```
  *
@@ -553,6 +562,7 @@ declare function subYears(date: Date | number, amount: number): Date;
  * ```
  *
  * @returns {number} The current timestamp in milliseconds.
+ * @deprecated Use `Date.now()` instead.
  * @category Util
  */
 declare function mNow(): number;
@@ -1560,16 +1570,16 @@ declare function isBool(bool: MazeyObject): boolean;
  */
 declare function isBoolean(bool: MazeyObject): boolean;
 /**
- * Verify the validity of a value.
+ * Return whether a value is exactly `undefined` or `null`.
  *
  * Usage:
  *
  * ```javascript
- * import { isUdfOrNul } from "mazey";
+ * import { isNullish } from "mazey";
  *
- * const ret1 = isUdfOrNul(undefined);
- * const ret2 = isUdfOrNul(null);
- * const ret3 = isUdfOrNul("abc");
+ * const ret1 = isNullish(undefined);
+ * const ret2 = isNullish(null);
+ * const ret3 = isNullish("abc");
  * console.log(ret1, ret2, ret3);
  * ```
  *
@@ -1579,8 +1589,20 @@ declare function isBoolean(bool: MazeyObject): boolean;
  * true true false
  * ```
  *
+ * Other falsy values, including `false`, `0`, `NaN`, and an empty string,
+ * return `false`.
+ *
  * @param {MazeyObject} val The value to verify.
- * @returns {boolean} Return TRUE if the object is undefined or null.
+ * @returns {boolean} Whether the value is `undefined` or `null`.
+ * @category Util
+ */
+declare function isNullish(val: MazeyObject): boolean;
+/**
+ * Deprecated alias of {@link isNullish}.
+ *
+ * @deprecated Use `isNullish` instead.
+ * @param val The value to verify.
+ * @returns Whether the value is `undefined` or `null`.
  * @category Util
  */
 declare function isUdfOrNul(val: MazeyObject): boolean;
@@ -2041,11 +2063,12 @@ declare function sha256Hex(input: string | BufferSource): Promise<string>;
  */
 declare function isValidPhoneNumber(mobile: string): boolean;
 /**
- * Alias of {@link isValidPhoneNumber}.
+ * Deprecated alias of {@link isValidPhoneNumber}.
  *
  * 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.
  * @category Util
  */
 declare const isMobile: typeof isValidPhoneNumber;
@@ -2723,9 +2746,9 @@ declare function removeClass(obj: MazeyElement, cls: string): void;
  * Example 1: Add the `<style>` with `id`, and repeated invoking will update the content instead of adding a new one.
  *
  * ```javascript
- * import { addStyle } from "mazey";
+ * import { injectStyle } from "mazey";
  *
- * addStyle(
+ * injectStyle(
  *   "body { background-color: #333; }",
  *   { id: "test" }
  * );
@@ -2740,9 +2763,9 @@ declare function removeClass(obj: MazeyElement, cls: string): void;
  * Example 2: Add the `<style>` without `id`, and repeated invoking will add a new one.
  *
  * ```javascript
- * import { addStyle } from "mazey";
+ * import { injectStyle } from "mazey";
  *
- * addStyle("body { background-color: #444; }");
+ * injectStyle("body { background-color: #444; }");
  * ```
  *
  * Output:
@@ -2751,10 +2774,10 @@ declare function removeClass(obj: MazeyElement, cls: string): void;
  * <style>body { background-color: #444; }</style>
  * ```
  *
- * Example 3: Combine `genStyleString` and `addStyle` to add multiple styles at once.
+ * Example 3: Combine `genStyleString` and `injectStyle` to add multiple styles at once.
  *
  * ```javascript
- * import { genStyleString, addStyle } from "mazey";
+ * import { genStyleString, injectStyle } from "mazey";
  *
  * const xStyle = genStyleString(
  *   ".footer>.x-wish>a:first-child" +
@@ -2773,7 +2796,7 @@ declare function removeClass(obj: MazeyElement, cls: string): void;
  *     "padding-bottom: var(--y-wish-1)",
  *   ]
  * );
- * addStyle(xStyle + yStyle, { id: "z-style" });
+ * injectStyle(xStyle + yStyle, { id: "z-style" });
  * ```
  *
  * Output:
@@ -2788,9 +2811,16 @@ declare function removeClass(obj: MazeyElement, cls: string): void;
  * @returns Whether non-empty CSS text was added or updated.
  * @category DOM
  */
-declare function addStyle(style: string, options?: {
+declare function injectStyle(style: string, options?: {
     id?: string;
 }): boolean;
+/**
+ * Deprecated alias of `injectStyle`.
+ *
+ * @deprecated Use `injectStyle` instead.
+ * @category DOM
+ */
+declare const addStyle: typeof injectStyle;
 /**
  * Sets the width and height of all images on the page based on their `src` attribute.
  * The `src` attribute should contain `width` and/or `height` values in the format "width=100" or "height=100".
@@ -2843,10 +2873,10 @@ declare function setImgWidHeiBySrc(): boolean;
  * #b{color:red;font-size:12px;}
  * ```
  *
- * Example: Combine `genStyleString` and `addStyle` to add multiple styles at once.
+ * Example: Combine `genStyleString` and `injectStyle` to add multiple styles at once.
  *
  * ```javascript
- * import { genStyleString, addStyle } from "mazey";
+ * import { genStyleString, injectStyle } from "mazey";
  *
  * const xStyle = genStyleString(
  *   ".footer>.x-wish>a:first-child" +
@@ -2865,7 +2895,7 @@ declare function setImgWidHeiBySrc(): boolean;
  *     "padding-bottom: var(--y-wish-1)",
  *   ]
  * );
- * addStyle(xStyle + yStyle, { id: "z-style" });
+ * injectStyle(xStyle + yStyle, { id: "z-style" });
  * ```
  *
  * Output:
@@ -2953,12 +2983,12 @@ interface ResolveElementTargetOptions {
 type DomVisibilityTarget = string | Element | Iterable<Element> | ArrayLike<Element> | null | undefined;
 /**
  * Hide every resolved element while preserving its visible inline `display`
- * value for a later call to {@link show}.
+ * value for a later call to {@link showElements}.
  *
  * ```javascript
- * import { hide } from "mazey";
+ * import { hideElements } from "mazey";
  *
- * hide(".notice");
+ * hideElements(".notice");
  * ```
  *
  * @remarks Selectors use the global document. Direct elements and collections
@@ -2968,17 +2998,17 @@ type DomVisibilityTarget = string | Element | Iterable<Element> | ArrayLike<Elem
  * @returns The original target unchanged, to support chaining by the caller.
  * @category DOM
  */
-declare function hide<T extends DomVisibilityTarget>(target: T): T;
+declare function hideElements<T extends DomVisibilityTarget>(target: T): T;
 /**
  * Show every resolved element by restoring a display value preserved by
- * {@link hide}, or by applying the document-aware default for CSS-hidden
+ * {@link hideElements}, or by applying the document-aware default for CSS-hidden
  * elements.
  *
  * ```javascript
- * import { show } from "mazey";
+ * import { showElements } from "mazey";
  *
  * const notices = document.querySelectorAll(".notice");
- * show(notices);
+ * showElements(notices);
  * ```
  *
  * @remarks Selectors use the global document. Direct elements and collections
@@ -2988,6 +3018,24 @@ declare function hide<T extends DomVisibilityTarget>(target: T): T;
  * @returns The original target unchanged, to support chaining by the caller.
  * @category DOM
  */
+declare function showElements<T extends DomVisibilityTarget>(target: T): T;
+/**
+ * Deprecated alias of {@link hideElements}.
+ *
+ * @deprecated Use `hideElements` instead.
+ * @param target Selector, element, iterable, array-like collection, or an empty target.
+ * @returns The original target unchanged.
+ * @category DOM
+ */
+declare function hide<T extends DomVisibilityTarget>(target: T): T;
+/**
+ * Deprecated alias of {@link showElements}.
+ *
+ * @deprecated Use `showElements` instead.
+ * @param target Selector, element, iterable, array-like collection, or an empty target.
+ * @returns The original target unchanged.
+ * @category DOM
+ */
 declare function show<T extends DomVisibilityTarget>(target: T): T;
 /**
  * Resolve an element from a direct element, a selector, an optionally
@@ -3102,17 +3150,17 @@ declare function cancelBubble(e: Event): void;
  */
 declare function getDefineListeners(): DefineListeners;
 /**
- * Add event.
+ * Register a named Mazey event callback.
  *
  * Usage:
  *
  * ```javascript
- * import { addEvent } from "mazey";
+ * import { fireEvent, onEvent } from "mazey";
  *
- * addEvent("test", (e) => {
+ * onEvent("test", (e) => {
  *  console.log("test event:", e);
  * });
- * fireEvent("test");
+ * fireEvent("test", { type: "test" });
  * ```
  *
  * Output:
@@ -3125,7 +3173,14 @@ declare function getDefineListeners(): DefineListeners;
  * @param fn
  * @category Event
  */
-declare function addEvent(type: string, fn: MazeyFn): void;
+declare function onEvent(type: string, fn: MazeyFn): void;
+/**
+ * Deprecated alias of `onEvent`.
+ *
+ * @deprecated Use `onEvent` instead.
+ * @category Event
+ */
+declare const addEvent: typeof onEvent;
 /**
  * Fire/Invoke event.
  *
@@ -4600,5 +4655,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, inRate, invokeEvent, invokeFn, isAndroid, isArray, isBool, isBoolean, isBrowser, isDesktop, isFunction, isHit, isIOS, isJSONString, isJsonString, isLinux, isMacOS, isMobile, isNonEmptyArray, isNonEmptyObject, 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, onURLChange, parseGitHubRepository, parseJsonSafe, parseLocalDateTime, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, resolveElementTarget, resolveLanguagePreference, resolveThemePreference, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLanguagePreference, setLocalJSON, setLocalStorage, setSessionJSON, setSessionStorage, setThemePreference, sha256Hex, show, 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, 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 type { DerivePackageMetadataOptions, DerivedPackageMetadata, DomVisibilityTarget, FormatByteSizeOptions, GitHubRepositoryDetails, InvestmentReturnRate, IsNumberOptions, IsSafePWAEnvOptions, IsStandalonePWAOptions, LocalDateTimePrecision, PWAEnvironment, PackageManager, PackageManifest, PackageManifestAuthor, PreferenceResult, ResolveElementTargetOptions, ResolvedTheme, ServiceWorkerUpdateCallbacks, ServiceWorkerUpdateWatcher, ThemePreference, VisitorType };