@k37z3r/jbase 2.0.1 → 2.0.3

package/wiki/DATA-Utilities-(Objects).md

@@ -0,0 +1,263 @@
+* [`mergeObjects`](#usage-mergeObjects) | [`pick`](#usage-pick) | [`omit`](#usage-omit)
+* [`get`](#usage-obj-get) | [`set`](#usage-obj-set)
+* [`find.key`](#usage-find-key) | [`find.value`](#usage-find-value) | [`find.at`](#usage-find-at) | [`find.first`](#usage-find-first) | [`find.last`](#usage-find-last)
+
+---
+
+## <a id="usage-mergeObjects"></a>.mergeObjects
+
+**Description**
+Recursively merges one or more source objects into a target object (Deep Merge).
+*Note: This modifies the `target` object in place.*
+
+**Parameters**
+
+* `target` (Object): The target object to receive properties.
+* `...sources` (Object[]): One or more source objects to merge into the target.
+
+**Returns**
+
+* (Object): The modified target object.
+
+**Example**
+
+```javascript
+const defaults = { app: { theme: 'light', debug: false } };
+const config = { app: { debug: true } };
+
+$.data.mergeObjects(defaults, config);
+// defaults is now: { app: { theme: 'light', debug: true } }
+
+```
+
+---
+
+## <a id="usage-pick"></a>.pick
+
+**Description**
+Creates a new object containing *only* the specified keys (Allowlist).
+
+**Parameters**
+
+* `obj` (Object): The source object.
+* `keys` (String[]): An array of keys to keep.
+
+**Returns**
+
+* (Object): A new object with the selected keys.
+
+**Example**
+
+```javascript
+const user = { id: 1, name: 'Alice', role: 'admin' };
+const publicProfile = $.data.pick(user, ['name']);
+// Result: { name: 'Alice' }
+
+```
+
+---
+
+## <a id="usage-omit"></a>.omit
+
+**Description**
+Creates a new object containing all keys *except* the specified ones (Blocklist).
+
+**Parameters**
+
+* `obj` (Object): The source object.
+* `keys` (String[]): An array of keys to remove.
+
+**Returns**
+
+* (Object): A new object without the specified keys.
+
+**Example**
+
+```javascript
+const user = { id: 1, name: 'Alice', password: '123' };
+const safeUser = $.data.omit(user, ['password']);
+// Result: { id: 1, name: 'Alice' }
+
+```
+
+---
+
+## <a id="usage-get"></a>.get
+
+**Description**
+Safely retrieves a value from a nested object using dot-notation. Returns `undefined` if the path does not exist, preventing runtime errors.
+
+**Parameters**
+
+* `obj` (Object): The object to query.
+* `path` (String): The path as a dot-notation string (e.g., `'user.address.city'`).
+
+**Returns**
+
+* (Any): The found value or `undefined`.
+
+**Example**
+
+```javascript
+const val = $.data.get(response, 'data.items.0.id');
+
+```
+
+---
+
+## <a id="usage-set"></a>.set
+
+**Description**
+Sets a value deeply within a nested object. It automatically creates missing intermediate objects if the path doesn't exist.
+
+**Parameters**
+
+* `obj` (Object): The object to modify.
+* `path` (String): The path string (e.g., `'settings.theme.color'`).
+* `value` (Any): The value to set.
+
+**Returns**
+
+* (Void): This function mutates the object and returns nothing.
+
+**Example**
+
+```javascript
+const config = {};
+$.data.set(config, 'database.connection.host', 'localhost');
+// config is now: { database: { connection: { host: 'localhost' } } }
+
+```
+
+---
+
+## <a id="usage-find-at"></a>.find.at
+
+**Description**
+Returns the n-th entry of an object as a `[key, value]` pair. Supports negative indices to count from the end.
+
+**Parameters**
+
+* `obj` (Object): The object to search.
+* `index` (Number): The 0-based index. Negative numbers count from the back.
+
+**Returns**
+
+* ([String, Any] | undefined): A tuple containing the key and value, or undefined.
+
+**Example**
+
+```javascript
+const data = { a: 1, b: 2, c: 3 };
+const entry = $.data.find.at(data, -1);
+// Result: ['c', 3]
+
+```
+
+---
+
+## <a id="usage-find-first"></a>.find.first
+
+**Description**
+Finds the **first** entry where the key or value matches the query.
+
+**Parameters**
+
+* `obj` (Object): The object to search.
+* `query` (String|Number): The search term.
+* `mode` (String, optional): Comparison mode: `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
+* `searchBy` (String, optional): Search by `'key'` or `'value'`. Default is `'key'`.
+
+**Returns**
+
+* ([String, Any] | undefined): The first matching `[key, value]` pair.
+
+**Example**
+
+```javascript
+const config = { admin_id: 10, user_id: 20 };
+// Find first entry where key starts with 'user'
+const match = $.data.find.first(config, 'user', 'startsWith', 'key');
+// Result: ['user_id', 20]
+
+```
+
+---
+
+## <a id="usage-find-last"></a>.find.last
+
+**Description**
+Finds the **last** entry where the key or value matches the query. Useful for prioritized overrides or ordered objects.
+
+**Parameters**
+
+* `obj` (Object): The object to search.
+* `query` (String|Number): The search term.
+* `mode` (String, optional): `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
+* `searchBy` (String, optional): `'key'` or `'value'`. Default is `'key'`.
+
+**Returns**
+
+* ([String, Any] | undefined): The last matching `[key, value]` pair.
+
+**Example**
+
+```javascript
+const files = { 'script.js': 1, 'style.css': 2, 'main.css': 3 };
+// Find last entry where key ends with '.css'
+const match = $.data.find.last(files, '.css', 'endsWith', 'key');
+// Result: ['main.css', 3]
+
+```
+
+---
+
+## <a id="usage-find-key"></a>.find.key
+
+**Description**
+Finds **all keys** in the object that match the query.
+
+**Parameters**
+
+* `obj` (Object): The object to search.
+* `query` (String): The search term.
+* `mode` (String, optional): `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
+
+**Returns**
+
+* (String[]): An array of matching keys.
+
+**Example**
+
+```javascript
+const settings = { theme_dark: true, theme_light: false, lang: 'en' };
+const themes = $.data.find.key(settings, 'theme_', 'startsWith');
+// Result: ['theme_dark', 'theme_light']
+
+```
+
+---
+
+## <a id="usage-find-value"></a>.find.value
+
+**Description**
+Finds **all values** in the object that match the query.
+
+**Parameters**
+
+* `obj` (Object): The object to search.
+* `query` (String): The search term.
+* `mode` (String, optional): `'exact'`, `'contains'`, `'startsWith'`, `'endsWith'`. Default is `'exact'`.
+
+**Returns**
+
+* (Any[]): An array of matching values.
+
+**Example**
+
+```javascript
+const roles = { bob: 'admin', alice: 'editor', john: 'admin' };
+const admins = $.data.find.value(roles, 'admin', 'exact');
+// Result: ['admin', 'admin']
+
+```

package/wiki/DOM-Attributes.md

@@ -0,0 +1,56 @@
+* [`attr`](#usage-attr) | [`val`](#usage-val)
+
+---
+
+## <a id="usage-attr"></a>.attr
+
+**Description**
+Get the value of an attribute for the first element in the set, or set one or more attributes for every matched element.
+
+**Parameters**
+
+* `name` (String): The name of the attribute.
+* `value` (String|Number, optional): The value to set. If omitted, the method acts as a getter.
+
+**Returns**
+
+* (String): Value of the attribute (if getter).
+* (jBase): Current instance for chaining (if setter).
+
+**Example**
+
+```javascript
+// Get href
+const link = $('a.my-link').attr('href');
+
+// Set id and title
+$('.item').attr('id', 'item-1').attr('title', 'Item One');
+
+```
+
+---
+
+## <a id="usage-val"></a>.val
+
+**Description**
+Get the current value of the first element in the set of matched elements or set the value of every matched element.
+
+**Parameters**
+
+* `value` (String|Number, optional): The value to set.
+
+**Returns**
+
+* (String|Number): The value of the input (if getter).
+* (jBase): Current instance (if setter).
+
+**Example**
+
+```javascript
+// Get input value
+const username = $('#username').val();
+
+// Set input value
+$('#username').val('NewUser');
+
+```

package/wiki/DOM-Content.md

@@ -0,0 +1,48 @@
+* [`html`](#usage-html) | [`text`](#usage-text)
+
+---
+
+## <a id="usage-html"></a>.html
+
+**Description**
+Get the HTML contents of the first element in the set or set the HTML contents of every matched element.
+
+**Parameters**
+
+* `content` (String, optional): The HTML string to set.
+
+**Returns**
+
+* (String): Inner HTML (if getter).
+* (jBase): Current instance (if setter).
+
+**Example**
+
+```javascript
+// Set HTML
+$('#container').html('<div class="child">Hello</div>');
+
+```
+
+---
+
+## <a id="usage-text"></a>.text
+
+**Description**
+Get the combined text contents of each element in the set of matched elements, including their descendants, or set the text contents of the matched elements.
+
+**Parameters**
+
+* `content` (String, optional): The text to set.
+
+**Returns**
+
+* (String): Text content (if getter).
+* (jBase): Current instance (if setter).
+
+**Example**
+
+```javascript
+$('h1').text('Welcome to jBase');
+
+```

package/wiki/DOM-Manipulation.md

@@ -0,0 +1,272 @@
+* [`remove`](#usage-remove) | [`empty`](#usage-empty) | [`replaceWithClone`](#usage-replaceWithClone)
+* [`append`](#usage-append) | [`prepend`](#usage-prepend) | [`before`](#usage-before) | [`after`](#usage-after)
+* [`replaceWith`](#usage-replaceWith) | [`appendTo`](#usage-appendTo) | [`prependTo`](#usage-prependTo)
+* [`insertBefore`](#usage-insertBefore) | [`insertAfter`](#usage-insertAfter)
+* [`wrap`](#usage-wrap) | [`unwrap`](#usage-unwrap)
+
+---
+
+## <a id="usage-remove"></a>.remove
+
+**Description**
+Removes the set of matched elements from the DOM.
+
+**Parameters**
+
+* None.
+
+**Returns**
+
+* (jBase): The removed elements (detached).
+
+**Example**
+
+```javascript
+$('.ads').remove();
+
+```
+
+---
+
+## <a id="usage-empty"></a>.empty
+
+**Description**
+Remove all child nodes of the set of matched elements from the DOM.
+
+**Parameters**
+
+* None.
+
+**Returns**
+
+* (jBase): Current instance.
+
+**Example**
+
+```javascript
+// Clears the content of .container but keeps the container itself
+$('.container').empty();
+
+```
+
+---
+
+## <a id="usage-replaceWithClone"></a>.replaceWithClone
+
+**Description**
+Replaces the selected elements with a deep clone of themselves. Useful for stripping event listeners.
+
+**Parameters**
+
+* None.
+
+**Returns**
+
+* (jBase): The new cloned elements.
+
+**Example**
+
+```javascript
+// Removes all events attached to the button by cloning it
+$('button#reset').replaceWithClone();
+
+```
+
+---
+
+## <a id="usage-append"></a>.append
+
+**Description**
+Insert content, specified by the parameter, to the end of each element in the set of matched elements.
+
+**Parameters**
+
+* `content` (String|HTMLElement|jBase): The content to insert.
+
+**Returns**
+
+* (jBase): Current instance.
+
+**Example**
+
+```javascript
+$('.list').append('<li>New Item</li>');
+
+```
+
+---
+
+## <a id="usage-prepend"></a>.prepend
+
+**Description**
+Insert content, specified by the parameter, to the beginning of each element in the set of matched elements.
+
+**Parameters**
+
+* `content` (String|HTMLElement|jBase): The content to insert.
+
+**Returns**
+
+* (jBase): Current instance.
+
+**Example**
+
+```javascript
+$('.list').prepend('<li>First Item</li>');
+
+```
+
+---
+
+## <a id="usage-before"></a>.before
+
+**Description**
+Insert content before each element in the set of matched elements.
+
+**Parameters**
+
+* `content` (String|HTMLElement|jBase): The content to insert.
+
+**Returns**
+
+* (jBase): Current instance.
+
+**Example**
+
+```javascript
+$('#main').before('<div class="header"></div>');
+
+```
+
+---
+
+## <a id="usage-after"></a>.after
+
+**Description**
+Insert content after each element in the set of matched elements.
+
+**Parameters**
+
+* `content` (String|HTMLElement|jBase): The content to insert.
+
+**Returns**
+
+* (jBase): Current instance.
+
+**Example**
+
+```javascript
+$('#main').after('<div class="footer"></div>');
+
+```
+
+---
+
+## <a id="usage-replaceWith"></a>.replaceWith
+
+**Description**
+Replace each element in the set of matched elements with the provided new content.
+
+**Parameters**
+
+* `content` (String|HTMLElement|jBase): The content to insert.
+
+**Returns**
+
+* (jBase): The new content.
+
+**Example**
+
+```javascript
+$('.old-element').replaceWith('<div class="new-element">Updated</div>');
+
+```
+
+---
+
+## <a id="usage-appendTo"></a>.appendTo
+
+**Description**
+Insert every element in the set of matched elements to the end of the target.
+
+**Parameters**
+
+* `target` (String|HTMLElement|jBase): The element to append to.
+
+**Returns**
+
+* (jBase): Current instance.
+
+**Example**
+
+```javascript
+$('<p>Test</p>').appendTo('.container');
+
+```
+
+---
+
+## <a id="usage-prependTo"></a>.prependTo
+
+**Description**
+Insert every element in the set of matched elements to the beginning of the target.
+
+**Parameters**
+
+* `target` (String|HTMLElement|jBase): The target element.
+
+**Returns**
+
+* (jBase): Current instance.
+
+**Example**
+
+```javascript
+$('<p>Intro</p>').prependTo('body');
+
+```
+
+---
+
+## <a id="usage-wrap"></a>.wrap
+
+**Description**
+Wrap an HTML structure around each element in the set of matched elements.
+
+**Parameters**
+
+* `structure` (String): HTML string specifying the structure (e.g., `<div class="wrapper"></div>`).
+
+**Returns**
+
+* (jBase): Current instance.
+
+**Example**
+
+```javascript
+$('.item').wrap('<div class="item-wrapper"></div>');
+
+```
+
+---
+
+## <a id="usage-unwrap"></a>.unwrap
+
+**Description**
+Remove the parents of the set of matched elements from the DOM, leaving the matched elements in their place.
+
+**Parameters**
+
+* None.
+
+**Returns**
+
+* (jBase): Current instance.
+
+**Example**
+
+```javascript
+// Removes the parent <div> but keeps the <span>
+$('span').unwrap();
+
+```

package/wiki/DOM-States.md

@@ -0,0 +1,73 @@
+* [`checked`](#usage-checked) | [`selected`](#usage-selected) | [`disabled`](#usage-disabled)
+
+---
+
+## <a id="usage-checked"></a>.checked
+
+**Description**
+Get the checked state of the first element or set the state for all matched elements.
+
+**Parameters**
+
+* `state` (Boolean, optional): True to check, false to uncheck.
+
+**Returns**
+
+* (Boolean): Current state (if getter).
+* (jBase): Current instance (if setter).
+
+**Example**
+
+```javascript
+if ($('#agree').checked()) {
+    // do something
+}
+$('#agree').checked(true);
+
+```
+
+---
+
+## <a id="usage-selected"></a>.selected
+
+**Description**
+Get the selected state of an option or set it.
+
+**Parameters**
+
+* `state` (Boolean, optional): True to select, false to deselect.
+
+**Returns**
+
+* (Boolean): Current state (if getter).
+* (jBase): Current instance (if setter).
+
+**Example**
+
+```javascript
+$('option[value="de"]').selected(true);
+
+```
+
+---
+
+## <a id="usage-disabled"></a>.disabled
+
+**Description**
+Get the disabled state of an element or set it.
+
+**Parameters**
+
+* `state` (Boolean, optional): True to disable, false to enable.
+
+**Returns**
+
+* (Boolean): Current state (if getter).
+* (jBase): Current instance (if setter).
+
+**Example**
+
+```javascript
+$('button').disabled(true);
+
+```