mazey 4.10.0 → 4.10.2

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/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

@@ -28,7 +28,7 @@ Use Mazey from CDN.
 <script type="text/javascript" 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
 
@@ -77,11 +77,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 +91,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 +361,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 +447,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 +606,7 @@ true true true true false
 
 ### Store
 
-#### Cookie
+#### Cookie Helpers
 
 Handle Cookie.
 
@@ -623,7 +624,7 @@ Output:
 123
 ```
 
-#### Storage
+#### Storage Helpers
 
 Handle Storage (Keep fit for JSON, it can transfer format automatically).
 
@@ -655,62 +656,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