mazey 4.10.0 → 4.11.0

package/.dockerignore

@@ -0,0 +1,35 @@
+# Git
+**/.git
+**/.gitignore
+
+# Node.js
+**/node_modules
+**/npm-debug.log
+
+# PHP
+**/*.php
+
+# Cache & System Files
+**/.DS_Store
+**/Thumbs.db
+**/.vscode
+**/.idea
+**/.cache
+**/tmp
+**/temp
+**/*.code-workspace
+
+# Docs
+**/documents/**/*.md
+**/documents/**/*.txt
+
+# Cert
+**/cert/**/*.key
+**/cert/**/*.pem
+
+# LOG
+**/var-log-web
+
+# Archives
+**/*.tar.gz
+**/asset_frozen

package/.gitattributes

@@ -0,0 +1,5 @@
+*.ts text eol=lf
+*.js text eol=lf
+*.json text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf

package/.markdownlint.json

@@ -0,0 +1,48 @@
+{
+  "default": true,
+  "MD001": true,
+  "MD003": {
+    "style": "atx"
+  },
+  "MD004": {
+    "style": "dash"
+  },
+  "MD007": {
+    "indent": 2
+  },
+  "MD010": {
+    "code_blocks": false
+  },
+  "MD013": {
+    "line_length": 700,
+    "code_blocks": false,
+    "tables": false
+  },
+  "MD022": {
+    "lines_above": 1,
+    "lines_below": 1
+  },
+  "MD024": {
+    "siblings_only": true
+  },
+  "MD025": {
+    "front_matter_title": ""
+  },
+  "MD026": {
+    "punctuation": ".,;:!?"
+  },
+  "MD029": {
+    "style": "ordered"
+  },
+  "MD033": {
+    "allowed_elements": ["img", "br", "kbd", "sub", "sup"]
+  },
+  "MD036": false,
+  "MD041": false,
+  "MD046": {
+    "style": "fenced"
+  },
+  "MD048": {
+    "style": "backtick"
+  }
+}

package/AGENTS.md

@@ -0,0 +1,111 @@
+# AGENTS.md
+
+## Purpose
+
+This repository is a browser-focused utility library published as `mazey`. It is not an application or monorepo. The main job here is maintaining a flat public API of frontend helper functions and shipping it in multiple bundle formats.
+
+## Repo Map
+
+- `src/`: source of truth for the library
+- `types/`: extra global type declarations bundled into `lib/`
+- `test/`: Jest tests, generally one file per source module
+- `examples/`: demo page and TS entry used by the local dev server
+- `scripts/`: Rollup, Webpack, release, and docs helpers
+- `images/`: documentation assets
+- `.github/`: CI/workflows
+
+## Main Entry Points
+
+- Library source entry: `src/index.ts`
+- Published package outputs:
+  - `lib/index.cjs.js`
+  - `lib/index.esm.js`
+  - `lib/mazey.min.js`
+  - `lib/index.d.ts`
+- Dev/demo entry: `examples/index.ts`
+
+`src/index.ts` is intentionally simple: it re-exports all feature modules so consumers import from `"mazey"` and get a flat API.
+
+## Source Modules
+
+- `src/util.ts`: shared utility layer; many other modules depend on this
+- `src/typing.d.ts`: shared internal/public types
+- `src/url.ts`: URL parsing, query helpers, URL transforms, script query inspection
+- `src/dom.ts`: class/style/meta/image DOM helpers
+- `src/event.ts`: custom event registry on `window.MAZEY_DEFINE_LISTENERS`
+- `src/store.ts`: `sessionStorage`, `localStorage`, and cookie helpers
+- `src/load.ts`: dynamic script/CSS/image loading and page-load helpers
+- `src/browser.ts`: browser/platform/PWA detection
+- `src/perf.ts`: Performance API and navigation timing helpers
+- `src/debug.ts`: custom console wrappers
+- `src/calc.ts`: standalone algorithms and probability helpers
+
+## Data Flow
+
+Typical runtime flow:
+
+1. Consumer imports from `mazey`
+2. Package resolves to a built file from `lib/`
+3. Built file originates from `src/index.ts`
+4. `src/index.ts` re-exports functions from the feature modules
+5. Feature modules call browser APIs directly, with light reuse of shared helpers in `util.ts`, `debug.ts`, and `typing.d.ts`
+
+Important internal dependencies:
+
+- `util.ts` is the main shared dependency
+- `typing.d.ts` is imported across modules for signatures and shared types
+- `debug.ts` provides `mazeyCon`, used by modules like `dom.ts` and `browser.ts`
+- `load.ts` depends on `util.ts` and `url.ts`
+- `perf.ts` depends on `util.ts`
+- `browser.ts` depends on `util.ts`
+- `calc.ts` depends on `util.ts`
+
+This is a mostly flat architecture, not a layered service system.
+
+## Build And Dev Flow
+
+- `npm run build`: Rollup bundles `src/index.ts` into CJS, ESM, and IIFE outputs in `lib/`
+- `npm run dev`: Webpack serves `examples/index.ts` via `examples/index.html`
+- `npm test`: Jest suite across `test/`
+- `npm run docs`: TypeDoc using `README.md`
+
+Relevant config files:
+
+- `package.json`
+- `scripts/rollup.config.mjs`
+- `scripts/webpack.config.dev.js`
+- `tsconfig.json`
+
+## Working Style For Agents
+
+- Preserve the flat public API unless there is a strong reason to change it
+- Check `src/index.ts` whenever adding, renaming, or removing exported functions
+- Prefer small, targeted changes; most modules are independent
+- Be careful with browser globals like `window`, `document`, `location`, `navigator`, and `performance`
+- Keep examples and tests aligned with public behavior when you change an exported helper
+- Avoid introducing app-style abstractions unless the repo is clearly moving in that direction
+
+## Common Change Paths
+
+- Add a new utility:
+  - implement in the relevant `src/*.ts`
+  - export via `src/index.ts`
+  - add or update tests under `test/`
+  - ensure build output still succeeds
+
+- Change packaging behavior:
+  - inspect `package.json`
+  - inspect `scripts/rollup.config.mjs`
+  - inspect any generated type outputs in `lib/`
+
+- Change local demo behavior:
+  - inspect `examples/index.ts`
+  - inspect `examples/index.html`
+  - inspect `scripts/webpack.config.dev.js`
+
+## Notes
+
+- The library targets browser environments first
+- Some helpers intentionally cache data on `window`
+- Several functions have compatibility-oriented logic for older browsers
+- The README is broad, but the code in `src/` is the authoritative map of behavior

package/Dockerfile

@@ -0,0 +1,30 @@
+FROM node:22-bookworm
+
+ENV DEBIAN_FRONTEND=noninteractive
+WORKDIR /workspace
+
+# Match ubuntu-latest style tooling needed by your workflow
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    dos2unix \
+    git \
+    ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+
+# Copy repo
+COPY . .
+
+# Simulate workflow env
+ENV NODE_VERSION=22
+ENV PROJECT_NAME=mazey
+ENV GITHUB_ACTOR=local-dev
+
+# Default command runs "test job" behavior
+CMD bash -lc '\
+  set -euo pipefail; \
+  echo "== Install dependencies =="; \
+  npm install; \
+  echo "== Build package =="; \
+  npm run build --if-present; \
+  echo "== Run tests =="; \
+  npm test \
+'

package/README.md

@@ -1,5 +1,3 @@
-<!-- markdownlint-disable MD041 -->
-
 English | [简体中文](https://github.com/chengchuu/mazey/blob/main/README_ZH.md)
 
 # Mazey
@@ -25,10 +23,10 @@ npm install mazey --save
 Use Mazey from CDN.
 
 ```html
-<script type="text/javascript" src="//cdn.jsdelivr.net/npm/mazey@latest/lib/mazey.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/mazey@latest/lib/mazey.min.js"></script>
 ```
 
-Of course, you can also download and serve the file [lib/mazey.min.js](https://cdn.jsdelivr.net/npm/mazey@latest/lib/mazey.min.js) yourself.
+Of course, you can also download and serve the file [jsdelivr/lib/mazey.min.js](https://cdn.jsdelivr.net/npm/mazey@latest/lib/mazey.min.js) yourself.
 
 ## Usage
 
@@ -40,20 +38,20 @@ Import from [npm](https://www.npmjs.com/package/mazey).
 import { isNumber } from "mazey";
 
 const x = 123;
-const y = Infinity;
-// <=> typeof x === "number" && !isNaN(x) && isFinite(x)
+const y = "abc";
+const z = Infinity;
 isNumber(x); // Output: true
 isNumber(y); // Output: false
+isNumber(z, { isInfinityAsNumber: true }); // Output: true
 ```
 
 Import from CDN.
 
 ```html
-<script type="text/javascript" src="//cdn.jsdelivr.net/npm/mazey@latest/lib/mazey.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/mazey@latest/lib/mazey.min.js"></script>
 <script>
-  const x = Infinity;
-  // <=> typeof x === "string" && !isNaN(x)
-  mazey.isNumber(x, { isInfinityAsNumber: true }); // Output: true
+  const x = 123;
+  mazey.isNumber(x); // Output: true
 </script>
 ```
 
@@ -77,11 +75,11 @@ There are some examples maintained by hand below. For more information, please c
   - [isValidData](#isvaliddata)
   - [genRndNumString](#genrndnumstring)
   - [formatDate](#formatdate)
+  - [deepCopy](#deepcopy)
   - [debounce](#debounce)
   - [throttle](#throttle)
   - [convertCamelToKebab](#convertcameltokebab)
   - [convertCamelToUnder](#convertcameltounder)
-  - [deepCopy](#deepcopy)
 - [URL](#url)
   - [getQueryParam](#getqueryparam)
   - [getUrlParam](#geturlparam)
@@ -91,11 +89,12 @@ There are some examples maintained by hand below. For more information, please c
   - [isValidUrl](#isvalidurl)
   - [isValidHttpUrl](#isvalidhttpurl)
 - [Store](#store)
-  - [Cookie](#cookie)
-  - [Storage](#storage)
+  - [Cookie Helpers](#cookie-helpers)
+  - [Storage Helpers](#storage-helpers)
 - [DOM](#dom)
+  - [Class Helpers](#class-helpers)
   - [addStyle](#addstyle)
-  - [Class](#class)
+  - [genStyleString](#genstylestring)
   - [newLine](#newline)
 - [Calculate and Formula](#calculate-and-formula)
   - [inRate](#inrate)
@@ -360,6 +359,26 @@ Number formatDate value: 2022-01-11 14:07:15
 Date formatDate value: 02/11/2014
 ```
 
+#### deepCopy
+
+Copy/Clone Object deeply.
+
+Usage:
+
+```javascript
+const ret1 = deepCopy(["a", "b", "c"]);
+const ret2 = deepCopy("abc");
+console.log(ret1);
+console.log(ret2);
+```
+
+Output:
+
+```text
+["a", "b", "c"]
+abc
+```
+
 #### debounce
 
 Debounce
@@ -426,26 +445,6 @@ a_b_c
 a_b_c
 ```
 
-#### deepCopy
-
-Copy/Clone Object deeply.
-
-Usage:
-
-```javascript
-const ret1 = deepCopy(["a", "b", "c"]);
-const ret2 = deepCopy("abc");
-console.log(ret1);
-console.log(ret2);
-```
-
-Output:
-
-```text
-["a", "b", "c"]
-abc
-```
-
 ### URL
 
 #### getQueryParam
@@ -605,7 +604,7 @@ true true true true false
 
 ### Store
 
-#### Cookie
+#### Cookie Helpers
 
 Handle Cookie.
 
@@ -623,7 +622,7 @@ Output:
 123
 ```
 
-#### Storage
+#### Storage Helpers
 
 Handle Storage (Keep fit for JSON, it can transfer format automatically).
 
@@ -655,62 +654,140 @@ Output:
 
 ### DOM
 
+#### Class Helpers
+
+Modify `class`.
+
+Usage:
+
+```javascript
+const dom = document.querySelector("#box");
+
+// Determine `class`
+hasClass(dom, "test");
+// Add `class`
+addClass(dom, "test");
+// Remove `class`
+removeClass(dom, "test");
+```
+
 #### addStyle
 
 Add `<style>` in `<head>`.
 
+Usage:
+
 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";
+
 addStyle(
-  `
-    body {
-      background-color: #333;
-    }
-  `,
-  {
-    id: "test",
-  }
+  "body { background-color: #333; }",
+  { id: "test" }
 );
-// <style id="test">
-//   body {
-//     background-color: #333;
-//   }
-// </style>
+```
+
+Output:
+
+```html
+<style id="test">body { background-color: #333; }</style>
 ```
 
 Example 2: Add the `<style>` without `id`, and repeated invoking will add a new one.
 
 ```javascript
-addStyle(
-  `
-    body {
-      background-color: #444;
-    }
-  `
+import { addStyle } from "mazey";
+
+addStyle("body { background-color: #444; }");
+```
+
+Output:
+
+```html
+<style>body { background-color: #444; }</style>
+```
+
+Example 3: Combine `genStyleString` and `addStyle` to add multiple styles at once.
+
+```javascript
+import { genStyleString, addStyle } from "mazey";
+
+const xStyle = genStyleString(
+  ".footer>.x-wish>a:first-child" +
+  ",div.wish-flex>a[href^='https://github.com/chengchuu']" +
+  ",.m-hide",
+  [ "display: none" ]
+);
+const yStyle = genStyleString(
+  ".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>
-//   body {
-//     background-color: #444;
-//   }
-// </style>
+addStyle(xStyle + yStyle, { id: "z-style" });
 ```
 
-#### Class
+Output:
 
-Modify `class`.
+```html
+<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
+
+Generate the inline style string from the given parameters. The first parameter is the query selector, and the second parameter is the style array.
 
 Usage:
 
 ```javascript
-const dom = document.querySelector("#box");
+const ret1 = genStyleString(".a", [ "color:red" ]);
+const ret2 = genStyleString("#b", [ "color:red", "font-size:12px" ]);
+console.log(ret1);
+console.log(ret2);
+```
 
-// Determine `class`
-hasClass(dom, "test");
-// Add `class`
-addClass(dom, "test");
-// Remove `class`
-removeClass(dom, "test");
+Output:
+
+```text
+.a{color:red;}
+#b{color:red;font-size:12px;}
+```
+
+Example: Combine `genStyleString` and `addStyle` to add multiple styles at once.
+
+```javascript
+import { genStyleString, addStyle } from "mazey";
+
+const xStyle = genStyleString(
+  ".footer>.x-wish>a:first-child" +
+  ",div.wish-flex>a[href^='https://github.com/chengchuu']" +
+  ",.m-hide",
+  [ "display: none" ]
+);
+const yStyle = genStyleString(
+  ".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)",
+  ]
+);
+addStyle(xStyle + yStyle, { id: "z-style" });
+```
+
+Output:
+
+```html
+<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>
 ```
 
 #### newLine

package/lib/global.d.ts

@@ -88,7 +88,5 @@ declare global {
     // LIB
     $: typeof $;
     jQuery: typeof $;
-    // Supply
-    // matchMedia: any;
   }
 }