Add jsExtension snippet

javascript/js-extension/README.md

@@ -0,0 +1,96 @@
+# js-extension (JavaScript)
+
+A tiny, dependency‑free utility class with a few DOM and string helpers that I often reach for in small projects and prototypes.
+
+It includes:
+- `addGlobalEventListener` — delegated events with a CSS selector
+- `createElement` — quick DOM element creation with attributes, class, dataset, and text
+- `qs` / `qsa` — short aliases for `querySelector` / `querySelectorAll` with optional parent
+- `strToHtml` — convert an HTML string to a `DocumentFragment`
+- `isJson` — quick check if a string parses as JSON
+- `sleep` — simple delay (`Promise`-based)
+
+## Quick usage
+
+Minimal examples showing what the helpers do. Adjust to your environment as needed.
+
+```js
+// Assume jsExtension is available in scope
+
+// 1) Delegated event listener
+jsExtension.addGlobalEventListener("click", "[data-action=remove]", (e) => {
+  const btn = e.target.closest("[data-action=remove]");
+  btn?.closest(".item")?.remove();
+});
+
+// 2) Create element with attributes, class, dataset, and text
+const card = jsExtension.createElement("div", {
+  class: "card",
+  id: "card-1",
+  dataset: { id: "1", type: "example" },
+  "aria-label": "Example card",
+  text: "Hello!",
+});
+
+// 3) Shorthand query helpers
+const firstItem = jsExtension.qs(".item");
+const allItems = jsExtension.qsa(".item");
+
+// 4) String to HTML fragment
+const frag = jsExtension.strToHtml(`
+  <ul>
+    <li>One</li>
+    <li>Two</li>
+  </ul>
+`);
+document.body.appendChild(frag);
+
+// 5) JSON check
+jsExtension.isJson('{"a":1}'); // true
+jsExtension.isJson('{a:1}');    // false
+
+// 6) Sleep helper
+await jsExtension.sleep(300);
+```
+
+## API
+
+### `addGlobalEventListener(type, selector, callback, options?, parent=document)`
+Adds a single delegated listener on `parent` and runs `callback` when the event target matches `selector` (or is inside an element that matches).
+
+- `type`: string event type, e.g. `"click"`
+- `selector`: CSS selector to match or `closest()` to
+- `callback`: function receiving the event
+- `options`: optional `addEventListener` options
+- `parent`: `HTMLElement | Document` (defaults to `document`)
+
+### `createElement(type, options={}) => HTMLElement`
+Creates an element and applies the provided options.
+Supported option keys:
+- `class`: string — added via `classList.add`
+- `dataset`: object — assigned to `element.dataset[key] = value`
+- `text`: string — sets `textContent`
+- any other key — assigned as attribute: `setAttribute(key, value)`
+
+### `qs(selector, parent=document) => Element|null`
+Shorthand for `parent.querySelector(selector)`. Returns `null` if `parent` is not a `Document`/`HTMLElement`.
+
+### `qsa(selector, parent=document) => NodeList<Element>`
+Shorthand for `parent.querySelectorAll(selector)`. Falls back to `document.querySelectorAll` when `parent` is not a `Document`/`HTMLElement`.
+
+### `strToHtml(str) => DocumentFragment`
+Converts an HTML string into a `DocumentFragment` using `Range#createContextualFragment`.
+
+### `isJson(str) => boolean`
+Returns `true` if `JSON.parse(str)` succeeds; otherwise `false`.
+
+### `sleep(time) => Promise<void>`
+Resolves after `time` milliseconds using `setTimeout`.
+
+## Notes
+- DOM helpers assume a browser environment (i.e., `document` is available).
+- `addGlobalEventListener` uses event delegation; attach it once at a suitable ancestor.
+
+## License
+
+See the repository-level `LICENSE` file.