dry-ux 1.73.0 → 1.75.0

package/dist/enhanced-inputs/Element.d.ts

@@ -3,17 +3,30 @@ export type InputElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaEl
  * Class representing a generic DOM element with utility methods for manipulation and validation.
  */
 export declare class Element {
-    native: HTMLElement;
+    private readonly _native;
     /**
      * Creates an instance of Element.
      * @param native The native HTML element.
      */
     constructor(native: HTMLElement);
     /**
-     * Gets the value of the input element.
+     * Gets the native HTML element.
+     * @returns The native HTML element.
+     */
+    get native(): HTMLElement;
+    /**
+     * Gets or sets the value of the input element.
+     * @param value Optional value to set for the input element.
+     * If no value is provided, it returns the current value of the input element.
+     * If a value is provided, it sets the input element's value to that value.
+     * This method is useful for both getting and setting the value of input elements.
      * @returns The value of the input element.
      */
-    val(): string;
+    val(value?: string): string | undefined;
+    /**
+     * Clears the inner content of element by setting it to an empty string.
+     */
+    empty(): void;
     /**
      * Checks if the element has a specific class.
      * @param className The class name to check.
@@ -72,34 +85,124 @@ export declare class Element {
      * @returns The native input element.
      */
     get nativeInput(): InputElement;
+    /**
+     * Adds an event listener to the element.
+     * @param type The event type to listen for.
+     * @param handler The event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener, or undefined if the element is not suitable for events.
+     */
+    addEventListener(type: string, handler: (e: Event) => void, once?: boolean): () => void | undefined;
+    /**
+     * Adds a change event listener to the element.
+     * @param handler The event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    change(handler: (e: Event) => void, once?: boolean): () => void | undefined;
+    /**
+     * Adds a click event listener to the element.
+     * @param handler The event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    click(handler: (e: Event) => void, once?: boolean): () => void | undefined;
+    /**
+     * Adds a focus event listener to the element.
+     * @param handler The event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    focus(handler: (e: Event) => void, once?: boolean): () => void | undefined;
+    /**
+     * Adds a blur event listener to the element.
+     * @param handler The event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    blur(handler: (e: Event) => void, once?: boolean): () => void | undefined;
+    /**
+     * Adds a keydown event listener to the element.
+     * @param handler The keyboard event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    keydown(handler: (e: KeyboardEvent) => void, once?: boolean): () => void | undefined;
+    /**
+     * Adds a keyup event listener to the element.
+     * @param handler The keyboard event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    keyup(handler: (e: KeyboardEvent) => void, once?: boolean): () => void | undefined;
     /**
      * Finds an element by its ID.
+     * When called as static method: searches entire document.
+     * When called as instance method: searches within this element's scope.
      * @param id The ID of the element to find.
      * @returns The Element instance if found, null otherwise.
      */
     static byId(id: string): Element | null;
+    /**
+     * Finds an element by its ID within this element's scope.
+     * @param id The ID of the element to find.
+     * @returns The Element instance if found, null otherwise.
+     */
+    byId(id: string): Element | null;
     /**
      * Finds the first element matching the CSS selector.
+     * When called as static method: searches entire document.
+     * When called as instance method: searches within this element's scope.
      * @param selector The CSS selector to match.
      * @returns The Element instance if found, null otherwise.
      */
     static bySelector(selector: string): Element | null;
+    /**
+     * Finds the first element matching the CSS selector within this element's scope.
+     * @param selector The CSS selector to match.
+     * @returns The Element instance if found, null otherwise.
+     */
+    bySelector(selector: string): Element | null;
     /**
      * Finds all elements matching the CSS selector.
+     * When called as static method: searches entire document.
+     * When called as instance method: searches within this element's scope.
      * @param selector The CSS selector to match.
      * @returns An array of Element instances.
      */
     static bySelectorAll(selector: string): Element[];
+    /**
+     * Finds all elements matching the CSS selector within this element's scope.
+     * @param selector The CSS selector to match.
+     * @returns An array of Element instances.
+     */
+    bySelectorAll(selector: string): Element[];
     /**
      * Finds all elements with the specified tag name.
+     * When called as static method: searches entire document.
+     * When called as instance method: searches within this element's scope.
      * @param tagName The tag name to match.
      * @returns An array of Element instances.
      */
     static byTagName(tagName: string): Element[];
+    /**
+     * Finds all elements with the specified tag name within this element's scope.
+     * @param tagName The tag name to match.
+     * @returns An array of Element instances.
+     */
+    byTagName(tagName: string): Element[];
     /**
      * Finds all elements with the specified class name.
+     * When called as static method: searches entire document.
+     * When called as instance method: searches within this element's scope.
      * @param className The class name to match.
      * @returns An array of Element instances.
      */
     static byClassName(className: string): Element[];
+    /**
+     * Finds all elements with the specified class name within this element's scope.
+     * @param className The class name to match.
+     * @returns An array of Element instances.
+     */
+    byClassName(className: string): Element[];
 }

package/dist/enhanced-inputs/Element.js

@@ -10,14 +10,31 @@ class Element {
      * @param native The native HTML element.
      */
     constructor(native) {
-        this.native = native;
+        this._native = native;
     }
     /**
-     * Gets the value of the input element.
+     * Gets the native HTML element.
+     * @returns The native HTML element.
+     */
+    get native() {
+        return this._native;
+    }
+    /**
+     * Gets or sets the value of the input element.
+     * @param value Optional value to set for the input element.
+     * If no value is provided, it returns the current value of the input element.
+     * If a value is provided, it sets the input element's value to that value.
+     * This method is useful for both getting and setting the value of input elements.
      * @returns The value of the input element.
      */
-    val() {
-        return this.nativeInput.value;
+    val(value) {
+        return value === undefined ? this.nativeInput.value : (this.nativeInput.value = value);
+    }
+    /**
+     * Clears the inner content of element by setting it to an empty string.
+     */
+    empty() {
+        this.native.innerHTML = "";
     }
     /**
      * Checks if the element has a specific class.
@@ -99,8 +116,81 @@ class Element {
     get nativeInput() {
         return this.native;
     }
+    /**
+     * Adds an event listener to the element.
+     * @param type The event type to listen for.
+     * @param handler The event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener, or undefined if the element is not suitable for events.
+     */
+    addEventListener(type, handler, once) {
+        if ((this.nativeInput instanceof HTMLInputElement ||
+            this.nativeInput instanceof HTMLSelectElement ||
+            this.nativeInput instanceof HTMLTextAreaElement) &&
+            !!type) {
+            const abortController = new AbortController();
+            this.nativeInput.addEventListener("change", handler, { once, signal: abortController.signal });
+            return abortController.abort;
+        }
+    }
+    /**
+     * Adds a change event listener to the element.
+     * @param handler The event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    change(handler, once) {
+        return this.addEventListener("change", handler, once);
+    }
+    /**
+     * Adds a click event listener to the element.
+     * @param handler The event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    click(handler, once) {
+        return this.addEventListener("click", handler, once);
+    }
+    /**
+     * Adds a focus event listener to the element.
+     * @param handler The event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    focus(handler, once) {
+        return this.addEventListener("focus", handler, once);
+    }
+    /**
+     * Adds a blur event listener to the element.
+     * @param handler The event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    blur(handler, once) {
+        return this.addEventListener("blur", handler, once);
+    }
+    /**
+     * Adds a keydown event listener to the element.
+     * @param handler The keyboard event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    keydown(handler, once) {
+        return this.addEventListener("keydown", handler, once);
+    }
+    /**
+     * Adds a keyup event listener to the element.
+     * @param handler The keyboard event handler function.
+     * @param once Whether the event should only fire once.
+     * @returns A function to remove the event listener.
+     */
+    keyup(handler, once) {
+        return this.addEventListener("keyup", handler, once);
+    }
     /**
      * Finds an element by its ID.
+     * When called as static method: searches entire document.
+     * When called as instance method: searches within this element's scope.
      * @param id The ID of the element to find.
      * @returns The Element instance if found, null otherwise.
      */
@@ -108,8 +198,18 @@ class Element {
         const element = document.getElementById(id);
         return element ? new Element(element) : null;
     }
+    /**
+     * Finds an element by its ID within this element's scope.
+     * @param id The ID of the element to find.
+     * @returns The Element instance if found, null otherwise.
+     */
+    byId(id) {
+        return this.bySelector(`#${id}`);
+    }
     /**
      * Finds the first element matching the CSS selector.
+     * When called as static method: searches entire document.
+     * When called as instance method: searches within this element's scope.
      * @param selector The CSS selector to match.
      * @returns The Element instance if found, null otherwise.
      */
@@ -117,29 +217,68 @@ class Element {
         const element = document.querySelector(selector);
         return element ? new Element(element) : null;
     }
+    /**
+     * Finds the first element matching the CSS selector within this element's scope.
+     * @param selector The CSS selector to match.
+     * @returns The Element instance if found, null otherwise.
+     */
+    bySelector(selector) {
+        const element = this.native.querySelector(selector);
+        return element ? new Element(element) : null;
+    }
     /**
      * Finds all elements matching the CSS selector.
+     * When called as static method: searches entire document.
+     * When called as instance method: searches within this element's scope.
      * @param selector The CSS selector to match.
      * @returns An array of Element instances.
      */
     static bySelectorAll(selector) {
         return Array.from(document.querySelectorAll(selector)).map(el => new Element(el));
     }
+    /**
+     * Finds all elements matching the CSS selector within this element's scope.
+     * @param selector The CSS selector to match.
+     * @returns An array of Element instances.
+     */
+    bySelectorAll(selector) {
+        return Array.from(this.native.querySelectorAll(selector)).map(el => new Element(el));
+    }
     /**
      * Finds all elements with the specified tag name.
+     * When called as static method: searches entire document.
+     * When called as instance method: searches within this element's scope.
      * @param tagName The tag name to match.
      * @returns An array of Element instances.
      */
     static byTagName(tagName) {
         return Array.from(document.getElementsByTagName(tagName)).map(el => new Element(el));
     }
+    /**
+     * Finds all elements with the specified tag name within this element's scope.
+     * @param tagName The tag name to match.
+     * @returns An array of Element instances.
+     */
+    byTagName(tagName) {
+        return Array.from(this.native.getElementsByTagName(tagName)).map(el => new Element(el));
+    }
     /**
      * Finds all elements with the specified class name.
+     * When called as static method: searches entire document.
+     * When called as instance method: searches within this element's scope.
      * @param className The class name to match.
      * @returns An array of Element instances.
      */
     static byClassName(className) {
         return Array.from(document.getElementsByClassName(className)).map(el => new Element(el));
     }
+    /**
+     * Finds all elements with the specified class name within this element's scope.
+     * @param className The class name to match.
+     * @returns An array of Element instances.
+     */
+    byClassName(className) {
+        return Array.from(this.native.getElementsByClassName(className)).map(el => new Element(el));
+    }
 }
 exports.Element = Element;

package/dist/helpers/utilities.d.ts

@@ -59,7 +59,7 @@ export declare const toHashCode: (input: string) => number;
  * @param key The key of the parameter.
  * @param value The value of the parameter.
  */
-export declare const insertUrlParam: (key: string, value: any) => void;
+export declare const insertUrlParam: (key: any, value: any) => void;
 /**
  * Inserts multiple URL parameters.
  * @param params An object containing key-value pairs of parameters.
@@ -113,7 +113,20 @@ export declare const usePubSub: <T>() => {
     usePub: () => <TName extends keyof T, TPayload extends T[TName]>(event: TName, data?: TPayload) => void;
     useSub: <TName extends keyof T, TPayload_1 extends T[TName]>(event: TName, callback: (data: TPayload_1) => void) => () => void;
 };
+/**
+ * Hook to get dimensions of an element or the viewport.
+ * @param ref
+ */
 export declare const useDimensions: (ref?: React.MutableRefObject<HTMLElement>) => {
     width: number;
     height: number;
 };
+/**
+ * Hook to get and set URL search parameters.
+ * @template T The type of the URL parameters.
+ * @returns An object containing the current URL parameters and a function to set a parameter.
+ */
+export declare const useSearchParams: <T>() => {
+    params: T;
+    setParam: <TKey extends keyof T, TValue extends T[TKey]>(key: TKey, value: TValue) => void;
+};

package/dist/helpers/utilities.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useDimensions = exports.usePubSub = exports.useIsVisible = exports.tryParseJson = exports.Deferred = exports.getUrlParams = exports.insertUrlParams = exports.insertUrlParam = exports.toHashCode = exports.StorageUtils = exports.fnWithAuthCheck = exports.formatDollar = exports.useCountdown = exports.importStyleSheet = exports.importScript = exports.preventDefault = void 0;
+exports.useSearchParams = exports.useDimensions = exports.usePubSub = exports.useIsVisible = exports.tryParseJson = exports.Deferred = exports.getUrlParams = exports.insertUrlParams = exports.insertUrlParam = exports.toHashCode = exports.StorageUtils = exports.fnWithAuthCheck = exports.formatDollar = exports.useCountdown = exports.importStyleSheet = exports.importScript = exports.preventDefault = void 0;
 const React = require("react");
 /**
  * Returns a function that will call the given handler and prevent the default event behavior.
@@ -282,6 +282,10 @@ const usePubSub = () => {
     return { usePub, useSub };
 };
 exports.usePubSub = usePubSub;
+/**
+ * Hook to get dimensions of an element or the viewport.
+ * @param ref
+ */
 const useDimensions = (ref) => {
     const [size, setSize] = React.useState({ width: 0, height: 0 });
     const element = (ref === null || ref === void 0 ? void 0 : ref.current) || document.documentElement;
@@ -296,3 +300,23 @@ const useDimensions = (ref) => {
     return size;
 };
 exports.useDimensions = useDimensions;
+/**
+ * Hook to get and set URL search parameters.
+ * @template T The type of the URL parameters.
+ * @returns An object containing the current URL parameters and a function to set a parameter.
+ */
+const useSearchParams = () => {
+    const [params, setParams] = React.useState((0, exports.getUrlParams)());
+    /**
+     * Sets a URL parameter and updates the state.
+     */
+    const setParam = React.useCallback((key, value) => {
+        (0, exports.insertUrlParam)(key, value);
+        setParams((0, exports.getUrlParams)());
+    }, []);
+    return {
+        params,
+        setParam,
+    };
+};
+exports.useSearchParams = useSearchParams;

package/dist/index.d.ts

@@ -18,4 +18,4 @@ export { Validation } from "./enhanced-inputs/Validaition";
 export { Viewport } from "./ui-utils/ViewportDetect";
 export * from "./enhanced-inputs/HTMLInputs";
 export * from "./enhanced-inputs/interface";
-export { Element } from "./enhanced-inputs/Element";
+export { Element, InputElement } from "./enhanced-inputs/Element";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dry-ux",
-  "version": "1.73.0",
+  "version": "1.75.0",
   "description": "",
   "main": "dist/index",
   "scripts": {