mazey 5.2.0 → 5.3.1

package/lib/index.d.ts

@@ -1350,6 +1350,150 @@ declare function sha256Hex(input: string | BufferSource): Promise<string>;
  * @category Util
  */
 declare function isValidDate(value: unknown): boolean;
+/**
+ * Check whether a date is today in the runtime's local timezone.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isToday } from "mazey";
+ *
+ * const ret = isToday(new Date());
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns Whether the value has the current local year, month, and day. Invalid input returns `false`.
+ * @remarks Hours, minutes, seconds, and milliseconds are ignored. Results depend on the runtime's local timezone.
+ * @category Util
+ */
+declare function isToday(date: MazeyDate): boolean;
+/**
+ * Check whether a date is in the current local calendar year.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isThisYear } from "mazey";
+ *
+ * const ret = isThisYear(new Date());
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns Whether the value has the current local year. Invalid input returns `false`.
+ * @remarks Results depend on the runtime's local timezone.
+ * @category Util
+ */
+declare function isThisYear(date: MazeyDate): boolean;
+/**
+ * Check whether a date is in the current local calendar month and year.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isThisMonth } from "mazey";
+ *
+ * const ret = isThisMonth(new Date());
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns Whether the value has the current local year and month. Invalid input returns `false`.
+ * @remarks Results depend on the runtime's local timezone.
+ * @category Util
+ */
+declare function isThisMonth(date: MazeyDate): boolean;
+/**
+ * Check whether a date is in the current Monday-first local calendar week.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isThisWeek } from "mazey";
+ *
+ * const ret = isThisWeek(new Date());
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns Whether the value is in the current local week. Invalid input returns `false`.
+ * @remarks The week begins on Monday and ends before the following Monday. Boundaries use local time and a half-open range.
+ * @category Util
+ */
+declare function isThisWeek(date: MazeyDate): boolean;
+/**
+ * Check whether a date is within the current local clock hour.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { isThisHour } from "mazey";
+ *
+ * const ret = isThisHour(new Date());
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns Whether the value has the current local year, month, day, and hour. Invalid input returns `false`.
+ * @remarks Minutes, seconds, and milliseconds are ignored. Results depend on the runtime's local timezone.
+ * @category Util
+ */
+declare function isThisHour(date: MazeyDate): boolean;
+/**
+ * Format the absolute distance from a date to now in concise English words.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { formatDistanceToNow } from "mazey";
+ *
+ * const ret = formatDistanceToNow(new Date(Date.now() - 60 * 60 * 1000));
+ * console.log(ret);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * about 1 hour
+ * ```
+ *
+ * @param date A `Date`, millisecond timestamp, or string accepted by `isValidDate`.
+ * @returns The absolute approximate distance phrase, or an empty string for invalid input.
+ * @remarks Past and future dates use the same wording without `ago` or `in`. Months and years use fixed approximate durations of 30 and 365 days.
+ * @category Util
+ */
+declare function formatDistanceToNow(date: MazeyDate): string;
 /**
  * Return the formatted date string in the given format.
  *
@@ -3239,6 +3383,165 @@ declare function genBrowserAttrs(prefix?: string, separator?: string): string[];
  */
 declare function isSupportWebp(): Promise<boolean>;
 
+/**
+ * A user-selectable color-theme preference.
+ *
+ * @category Browser Information
+ */
+type ThemePreference = "system" | "light" | "dark";
+/**
+ * A concrete color theme that can be applied to a page.
+ *
+ * @category Browser Information
+ */
+type ResolvedTheme = "light" | "dark";
+/**
+ * Human-readable names for supported theme preferences.
+ *
+ * @category Browser Information
+ */
+type ThemePreferenceDisplayName = "System" | "Light" | "Dark";
+/**
+ * The highest-priority source that selected a theme preference.
+ *
+ * @category Browser Information
+ */
+type ThemePreferenceSource = "query" | "storage" | "system" | "fallback";
+/**
+ * Options for {@link resolveThemePreference}.
+ *
+ * @category Browser Information
+ */
+interface ResolveThemePreferenceOptions {
+    /** Project-specific local-storage key, such as `MAZEY_THEME`. */
+    storageKey: string;
+    /** URL query parameter name. Defaults to `theme`. */
+    queryParam?: string;
+    /** URL inspected for a query override. Defaults to `window.location.href` when available. */
+    url?: string | URL;
+    /** Storage used to read a persisted preference. Defaults to `window.localStorage` when available. */
+    storage?: Pick<Storage, "getItem"> | null;
+    /** Media-query implementation. Defaults to `window.matchMedia` when available. */
+    matchMedia?: (query: string) => Pick<MediaQueryList, "matches">;
+    /** Theme used when the system preference is unavailable. Defaults to `light`. */
+    fallback?: ResolvedTheme;
+}
+/**
+ * Options for {@link setThemePreference}.
+ *
+ * @category Browser Information
+ */
+interface SetThemePreferenceOptions {
+    /** Project-specific local-storage key, such as `MAZEY_THEME`. */
+    storageKey: string;
+    /** Supported preference to persist. */
+    preference: ThemePreference;
+    /** Storage used to persist the preference. Defaults to `window.localStorage` when available. */
+    storage?: Pick<Storage, "setItem"> | null;
+}
+/**
+ * Result returned by {@link resolveThemePreference}.
+ *
+ * @category Browser Information
+ */
+interface ThemePreferenceResult {
+    /** Selected user-facing preference. */
+    preference: ThemePreference;
+    /** Effective light or dark theme. */
+    resolvedTheme: ResolvedTheme;
+    /** Human-readable name of the selected preference. */
+    displayName: ThemePreferenceDisplayName;
+    /** Highest-priority source that supplied the selected preference. */
+    source: ThemePreferenceSource;
+}
+/**
+ * Resolve a website theme preference without mutating the DOM or storage.
+ *
+ * Resolution uses four priority levels: a `light` or `dark` URL query
+ * override, a stored `system`/`light`/`dark` preference, the current system
+ * color scheme, and finally a configured `light` or `dark` fallback. The
+ * default query parameter is `theme`, and the storage key must be supplied by
+ * the consuming project. Query `system` and all unsupported values are ignored.
+ *
+ * The result separates the selected preference from the effective theme and
+ * includes its display name (`System`, `Light`, or `Dark`) and source. A stored
+ * `system` preference retains `source: "storage"` while its effective theme is
+ * resolved from the current media query or fallback.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { resolveThemePreference } from "mazey";
+ *
+ * const theme = resolveThemePreference({
+ *   storageKey: "MY_WEBSITE_THEME",
+ * });
+ * console.log(theme.preference);
+ * console.log(theme.resolvedTheme);
+ * console.log(theme.displayName);
+ * console.log(theme.source);
+ * ```
+ *
+ * Possible output:
+ *
+ * ```text
+ * system
+ * dark
+ * System
+ * system
+ * ```
+ *
+ * URL override:
+ *
+ * ```javascript
+ * const theme = resolveThemePreference({
+ *   storageKey: "MY_WEBSITE_THEME",
+ *   url: "https://example.com/?theme=light",
+ * });
+ * ```
+ *
+ * @param options Project storage key and optional URL, storage, media-query, and fallback inputs.
+ * @returns The selected preference, effective theme, display name, and preference source.
+ * @throws {TypeError} If required options or explicitly supplied option values are invalid.
+ * @remarks Safe during SSR and resilient to unavailable or throwing browser APIs. This function does not write storage, mutate the DOM, or add listeners. System resolution reads the current media-query result rather than cached browser information.
+ * @category Browser Information
+ */
+declare function resolveThemePreference(options: ResolveThemePreferenceOptions): ThemePreferenceResult;
+/**
+ * Persist a supported website theme preference.
+ *
+ * The preference is written as the exact lowercase value `system`, `light`,
+ * or `dark` under a project-specific storage key. The function returns
+ * `false` instead of throwing when storage is unavailable, including during
+ * SSR and in privacy-restricted browser environments. It does not resolve or
+ * apply the theme and does not mutate the DOM.
+ *
+ * Usage:
+ *
+ * ```javascript
+ * import { setThemePreference } from "mazey";
+ *
+ * const stored = setThemePreference({
+ *   storageKey: "MY_WEBSITE_THEME",
+ *   preference: "dark",
+ * });
+ * console.log(stored);
+ * ```
+ *
+ * Output:
+ *
+ * ```text
+ * true
+ * ```
+ *
+ * @param options Project storage key, supported preference, and optional storage implementation.
+ * @returns `true` when the preference was written, or `false` when storage is unavailable or rejects the write.
+ * @throws {TypeError} If the options, storage key, preference, or explicitly supplied storage implementation is invalid.
+ * @remarks This function writes only the selected preference. Applying a resolved theme and updating controls remain the consuming project's responsibility.
+ * @category Browser Information
+ */
+declare function setThemePreference(options: SetThemePreferenceOptions): boolean;
+
 /**
  * Create a configurable wrapper around the global `console`.
  *
@@ -3309,5 +3612,5 @@ declare const mazeyCon: Console;
  */
 declare const timeCon: Console;
 
-export { addClass, addEvent, addStyle, calLongestCommonSubsequence, calLongestCommonSubstring, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, doFn, extractElementText, fireEvent, floatFixed, floatToPercent, formatDate, formatDurationFromMs, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionStorage, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, inRate, invokeEvent, invokeFn, isArray, isBool, isBoolean, isBrowser, isFunction, isHit, isJSONString, isJsonString, isNonEmptyArray, isNonEmptyObject, isNumber, isPureObject, isSafePWAEnv, isStandalonePWA, isString, isSupportWebp, isSupportedEntryType, isUdfOrNul, isValidCssSelector, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onURLChange, parseGitHubRepository, parseJsonSafe, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLocalStorage, setSessionStorage, sha256Hex, sleep, throttle, timeCon, toJavaScriptGlobalName, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, windowLoaded, zAxiosIsValidRes };
-export type { GitHubRepositoryDetails, IsSafePWAEnvOptions };
+export { addClass, addEvent, addStyle, calLongestCommonSubsequence, calLongestCommonSubstring, camelCase2Underscore, camelCaseToKebabCase, cancelBubble, clearHTML, clearHtml, convert10To26, convertCamelToKebab, convertCamelToUnder, convertHttpToHttps, convertKebabToCamel, convertObjectToQuery, convertToHtmlBreaks, convertUnderToCamel, cutCHSString, cutZHString, debounce, deepCopy, deepCopyObject, deepFreeze, delCookie, doFn, extractElementText, fireEvent, floatFixed, floatToPercent, formatDate, formatDistanceToNow, formatDurationFromMs, genBrowserAttrs, genCustomConsole, genHashCode, genRndNumString, genStyleString, genUniqueNumString, generateCalendarVersion, generateRndNum, generateUniqueNum, getAllQueryParams, getBrowserInfo, getCLS, getCookie, getCurrentVersion, getDateDifference, getDefineListeners, getDomain, getFCP, getFID, getFP, getFileSize, getFriendlyInterval, getHashQueryParam, getLCP, getLocalStorage, getPageMeta, getPerformance, getQueryParam, getScriptQueryParam, getSessionStorage, getTTFB, getUrlFileType, getUrlHost, getUrlParam, getUrlPath, hasClass, inRate, invokeEvent, invokeFn, isArray, isBool, isBoolean, isBrowser, isFunction, isHit, isJSONString, isJsonString, isNonEmptyArray, isNonEmptyObject, isNumber, isPureObject, isSafePWAEnv, isStandalonePWA, isString, isSupportWebp, isSupportedEntryType, isThisHour, isThisMonth, isThisWeek, isThisYear, isToday, isUdfOrNul, isValidCssSelector, isValidData, isValidDate, isValidEmail, isValidHttpUrl, isValidPhoneNumber, isValidUrl, loadCSS, loadImage, loadScript, loadScriptIfUndefined, longestComSubsequence, longestComSubstring, mNow, mTrim, mazeyCon, newLine, onURLChange, parseGitHubRepository, parseJsonSafe, removeClass, removeCookie, removeEvent, removeHTML, removeHtml, repeatUntilConditionMet, replaceHttp, resolveThemePreference, sanitizeInput, setClass, setCookie, setImgSizeBySrc, setImgWidHeiBySrc, setLocalStorage, setSessionStorage, setThemePreference, sha256Hex, sleep, throttle, timeCon, toJavaScriptGlobalName, truncateZHString, unsanitize, unsanitizeInput, updateQueryParam, waitTime, windowLoaded, zAxiosIsValidRes };
+export type { GitHubRepositoryDetails, IsSafePWAEnvOptions, ResolveThemePreferenceOptions, ResolvedTheme, SetThemePreferenceOptions, ThemePreference, ThemePreferenceDisplayName, ThemePreferenceResult, ThemePreferenceSource };