97 lines
3.3 KiB
Markdown
97 lines
3.3 KiB
Markdown
# 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.
|