@vandenberghinc/volt 1.1.2

package/frontend/src/elements/module.ts

@@ -0,0 +1,184 @@
+/*
+ * Author: Daan van den Bergh
+ * Copyright: © 2022 - 2024 Daan van den Bergh.
+ */
+
+// Import elements create func.
+export * from "./base.js";
+import {
+    VElement,
+    extend as extend_velement,
+    wrapper as _wrapper,
+    create_null as _create_null,
+} from "./base.js"
+
+export namespace Elements {
+    
+    // Get by id.
+    // @note: always use VElement as return type since this is most likely the case and avoids type casting for users.
+    /*  @docs:
+        @nav: Frontend
+        @chapter: Elements
+        @title: Get Element by ID
+        @desc: Get an element by its ID.
+        @param:
+            @name: id
+            @description The ID of the element.
+    */
+    export function get(id: string): VElement {
+        const e = document.getElementById(id);
+        if (e == null) {
+            throw new Error(`Unable to find element with id "${id}".`);
+        }
+        return e as any as VElement;
+    }
+
+    // Get by id (alias).
+    // @note: always use VElement as return type since this is most likely the case and avoids type casting for users.
+    /*  @docs:
+        @nav: Frontend
+        @chapter: Elements
+        @title: Get Element by ID (Alias)
+        @desc: Alias for `get` to get an element by its ID.
+        @param:
+            @name: id
+            @description The ID of the element.
+    */
+    export function get_by_id(id: string): VElement {
+        return Elements.get(id);
+    }
+
+    // Click an element by id.
+    /*  @docs:
+        @nav: Frontend
+        @chapter: Elements
+        @title: Click Element by ID
+        @desc: Programmatically clicks an element by its ID.
+        @param:
+            @name: id
+            @description The ID of the element.
+    */
+    export function click(id: string): void {
+        const element = document.getElementById(id);
+        if (element) {
+            element.click();
+        } else {
+            throw new Error(`Unable to find element with id "${id}".`);
+        }
+    }
+
+    // Register a custom type.
+    /*  @docs:
+        @nav: Frontend
+        @chapter: Elements
+        @title: Register Custom Type
+        @desc: Registers a custom element type.
+        @param:
+            @name: type
+            @description The custom element type (class).
+        @param:
+            @name: tag
+            @description Optional tag name to extend.
+    */
+    export function register_type(type: any, tag?: string): void {
+        (type as any)._is_registered = true;
+        // customElements.define(type.name, type, { extends: tag || (type as any).element_tag });
+        customElements.define("v-" + type.name.toLowerCase(), type, { extends: tag || (type as any).element_tag });
+    }
+
+    // Register decorator.
+    /*  @docs:
+        @nav: Frontend
+        @chapter: Elements
+        @title: Register Decorator
+        @desc: Registers a class as a custom element.
+        @param:
+            @name: constructor
+            @description The class constructor to register.
+    */
+    export function register<T extends { new(...args: any[]): {} }>(constructor: T): void {
+        Elements.register_type(constructor);
+    }
+
+    // Create a constructor wrapper.
+    export const wrapper = _wrapper;
+
+    // Create a shared null element mainly for typescript types.
+    export const create_null = _create_null;
+
+    // Submit multiple elements by id or element.
+    // When one is not filled in then an error is thrown.
+    // When an input is not required, no errors will be thrown.
+    // An object will be returned with each input's id as the key and the input's value as value.
+    // Only supported extended input elements like `ExtendedInput`.
+    /*  @docs:
+        @nav: Frontend
+        @chapter: Elements
+        @title: Submit Elements
+        @desc: Submits multiple elements by ID or reference.
+        @deprecated: true
+        @param:
+            @name: elements
+            @description A list of element IDs or element references to submit.
+    */
+    export function submit(...elements: (string | VElement | HTMLElement)[]): Record<string, any> {
+        const params: Record<string, any> = {};
+        let error;
+        for (let i = 0; i < elements.length; i++) {
+            try {
+                let element = elements[i];
+                if (typeof element === "string") {
+                    element = Elements.get(element);
+                }
+                const id = (element as any).id();
+                if (id == null || id === "") {
+                    continue;
+                }
+                if ((element as any).required() !== true) {
+                    params[id] = (element as any).value();
+                } else {
+                    params[id] = (element as any).submit();
+                }
+            } catch (e) {
+                error = e;
+            }
+        }
+        if (error) {
+            throw error;
+        }
+        return params;
+    }
+
+    // Forward a function to a child so a user can easily create functions on the parent like border_radius() which actually set the border radius of a child.
+    // The new function still returns `this`.
+    /*  @docs:
+        @nav: Frontend
+        @chapter: Elements
+        @title: Forward Function to Child
+        @desc: Forwards a function to a child element.
+        @param:
+            @name: func_name
+            @description The name of the function to forward.
+        @param:
+            @name: child
+            @description The child element or a function that returns the child element.
+    */
+    export function forward_func_to_child(func_name: string, child: any): (val?: any) => any {
+        return function (this: any, val?: any) {
+            if (typeof child === "function") {
+                child = child(this);
+            }
+            if (val == null) {
+                return child[func_name]();
+            }
+            child[func_name](val);
+            return this;
+        };
+    }
+
+    // Update the extend_velement function to use proper types
+    export const extend = extend_velement;
+
+    // Create.
+    // export const create = create_velement;
+};

package/frontend/src/elements/types.d.ts

@@ -0,0 +1,155 @@
+
+// Add some html properties since VBaseElement wants properties of them all since is is mixed in.
+interface HTMLElement extends VElementExtensions {
+    
+    setAttribute(name: string, value: string | number | boolean): void;
+
+    acceptCharset: any;
+    name: any;
+    hreflang: any;
+    readOnly: any;
+    autoplay: any;
+    maxlength: any;
+    minlength: any;
+    dateTime: any;
+    srcset?: string
+    srclang?: string;
+    srcdoc?: string;
+    novalidate?: boolean;
+    isMap?: boolean;
+    httpEquiv?: string;
+    formAction?: string;
+    rowspan?: number;
+    autocomplete?: "" | "on" | "off";
+    useMap?: string;
+
+    // value(): string; 
+    // value(value: string): this;
+    // type(): string; 
+    // type(value: string): this;
+    // title(): string; 
+    // title(value: string): this;
+    // target(): string; 
+    // target(value: string): this;
+    // pattern(): string; 
+    // pattern(value: string): this;
+    // step(): string; 
+    // step(value: string): this;
+    // start(): number | null; 
+    // start(value: number): this;
+    // multiple(): boolean; 
+    // multiple(value: boolean): this;
+    // checked(): boolean; 
+    // checked(value: boolean): this;
+    // required(): boolean; 
+    // required(value: boolean): this;
+
+    // rows(): null | number 
+    // rows(value: number): this;
+    // span(): null | number 
+    // span(value: number): this;
+
+    // 
+
+    // alt(): string; 
+    // alt(value: string): this;
+    // accept(): string; 
+    // accept(value: string): this;
+    // action(): string; 
+    // action(value: string): this;
+    // enctype(): string; 
+    // enctype(value: string): this;
+    // id(): string; 
+    // id(value: string): this;
+    // lang(): string; 
+    // lang(value: string): this;
+    // max(): string; 
+    // max(value: string): this;
+    // method(): string; 
+    // method(value: string): this;
+    // min(): string; 
+    // min(value: string): this;
+    // placeholder(): string; 
+    // placeholder(value: string): this;
+    // rel(): string; 
+    // rel(value: string): this;
+    // shape(): string; 
+    // shape(value: string): this;
+
+    // download(): string; 
+    // download(value: string): this;
+    // charset(): string;
+    // charset(value: string): this;
+    // cite(): string;
+    // cite(value: string): this;
+    // cols(): null | number 
+    // cols(value: number): this;
+    // colspan(): null | number 
+    // colspan; (value: number): this;
+    // controls(): boolean;
+    // controls(value: boolean): this;
+    // coords(): string;
+    // coords(value: string): this;
+    // data(): string;
+    // data(value: string): this;
+    // async(): boolean;
+    // async(value: boolean): this;
+    // default(): boolean;
+    // default(value: boolean): this;
+    // defer(): boolean;
+    // defer(value: boolean): this;
+    // dir(): string;
+    // dir(value: string): this;
+    // dirname(): string;
+    // dirname(value: string): this;
+    // disabled(): boolean;
+    // disabled(value: boolean): this;
+    // draggable(): boolean;
+    // draggable(value: boolean): this;
+    // for(): string;
+    // for(value: string): this;
+    // headers(): string;
+    // headers(value: string): this;
+    // high(): string;
+    // high(value: string | number): this;
+    // href(): string;
+    // href(value: string): this;
+    // kind(): string;
+    // kind(value: string): this;
+    // label(): string;
+    // label(value: string): this;
+    // loop(): boolean;
+    // loop(value: boolean): this;
+    // low(): string;
+    // low(value: string | number): this;
+    // muted(): boolean;
+    // muted(value: boolean): this;
+    // open(): boolean;
+    // open(value: boolean): this;
+    // optimum(): null | number 
+    // optimum(value: number): this;
+    // poster(): string;
+    // poster(value: string): this;
+    // preload(): string;
+    // preload(value: string): this;
+    // reversed(): boolean;
+    // reversed(value: boolean): this;
+    // sandbox(): string;
+    // sandbox(value: string): this;
+    // scope(): string;
+    // scope(value: string): this;
+    // selected(): boolean;
+    // selected(value: boolean): this;
+    // shape(): string;
+    // shape(value: string): this;
+    // span(): null | number;
+    // span(value: number): this;
+    // size(): null | number;
+    // size(value: number): this;
+    // sizes(): string; 
+    // sizes(value: string): this;
+    // span(): string; 
+    // span(value: string): this;
+    // src(): string; 
+    // src(value: string): this;
+}

package/frontend/src/modules/array.ts

@@ -0,0 +1,366 @@
+/*
+ * Author: Daan van den Bergh
+ * Copyright: © 2022 - 2024 Daan van den Bergh.
+ */
+
+declare global {
+    interface Array<T> {
+
+        // Append alias for push.
+        append(...items: T[]): number;
+
+        // Get the first item.
+        first(): T | undefined;
+
+        // Get the last item.
+        last(): T | undefined;
+
+        // Iteration functions
+        iterate(handler: (item: T, index: number, array: T[]) => any): any;
+        iterate(start: number, handler: (item: T, index: number, array: T[]) => any): any;
+        iterate(start: number, end: number, handler: (item: T, index: number, array: T[]) => any): any;
+
+        // Asynchronous iteration functions
+        iterate_async(handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any[]>;
+        iterate_async(start: number, handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any[]>;
+        iterate_async(start: number, end: number, handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any[]>;
+
+        iterate_async_await(handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any>;
+        iterate_async_await(start: number, handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any>;
+        iterate_async_await(start: number, end: number, handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any>;
+
+        // Iteration function to build an array by appending returned values
+        iterate_append(handler: (item: T, index: number, array: T[]) => any): any[];
+        iterate_append(start: number, handler: (item: T, index: number, array: T[]) => any): any[];
+        iterate_append(start: number, end: number, handler: (item: T, index: number, array: T[]) => any): any[];
+
+        // Reversed iteration functions
+        iterate_reversed(handler: (item: T, index: number, array: T[]) => any): any;
+        iterate_reversed(start: number, handler: (item: T, index: number, array: T[]) => any): any;
+        iterate_reversed(start: number, end: number, handler: (item: T, index: number, array: T[]) => any): any;
+
+        iterate_reversed_async(handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any[]>;
+        iterate_reversed_async(start: number, handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any[]>;
+        iterate_reversed_async(start: number, end: number, handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any[]>;
+
+        iterate_reversed_async_await(handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any>;
+        iterate_reversed_async_await(start: number, handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any>;
+        iterate_reversed_async_await(start: number, end: number, handler: (item: T, index: number, array: T[]) => Promise<any>): Promise<any>;
+
+        // Drop methods
+        drop(item: T): T[];
+
+        drop_index(index: number): T[];
+
+        // Remove duplicates
+        drop_duplicates(): T[];
+
+        // Limit from end
+        limit_from_end(limit: number): T[];
+
+        // Remove items equal to the specified item
+        remove(item: T): T[];
+
+        // Equality check
+        eq(otherArray: any[]): boolean;
+        eq(x: any, y: any): boolean;
+
+        // Divide into nested arrays
+        divide(x: number): T[][];
+    }
+}
+export {}; // is required.
+
+// Append alias for push.
+Array.prototype.append = Array.prototype.push; 
+
+// Get the first and last item.
+Array.prototype.first = function() {
+    return this[0];
+};
+
+// Get the first and last item.
+Array.prototype.last = function() {
+    return this[this.length - 1];
+};
+
+// Iteration function for arrays.
+Array.prototype.iterate = function(start: any, end?: any, handler?: any): any {
+    if (typeof start === "function") {
+        handler = start;
+        start = null;
+    }
+    if (start == null) {
+        start = 0;
+    }
+    if (end == null) {
+        end = this.length;
+    }
+    for (let i = start; i < end; i++) {    
+        const res = handler(this[i]);
+        if (res != null && !(res instanceof Promise)) {
+            return res;
+        }
+    }
+    return null;
+};
+Array.prototype.iterate_async = function(start: any, end?: any, handler?: any): any {
+    if (typeof start === "function") {
+        handler = start;
+        start = null;
+    }
+    if (start == null) {
+        start = 0;
+    }
+    if (end == null) {
+        end = this.length;
+    }
+    let promises: Promise<any>[] = [];
+    for (let i = start; i < end; i++) {    
+        const res = handler(this[i]);
+        if (res != null && res instanceof Promise) {
+            promises.push(res);
+        }
+    }
+    return promises;
+};
+Array.prototype.iterate_async_await = async function(start: any, end?: any, handler?: any): Promise<any> {
+    if (typeof start === "function") {
+        handler = start;
+        start = null;
+    }
+    if (start == null) {
+        start = 0;
+    }
+    if (end == null) {
+        end = this.length;
+    }
+    for (let i = start; i < end; i++) {    
+        const res = handler(this[i]);
+        if (res != null && res instanceof Promise) {
+            const pres = await res;
+            if (pres != null) {
+                return pres;
+            }
+        }
+    }
+    return null;
+};
+
+// Iteration function for arrays to build an array by another array, it appends all the returned callback values into an array and returns that array. Quite useful for volt.
+Array.prototype.iterate_append = function(start: any, end?: any, handler?: any): any {
+    if (typeof start === "function") {
+        handler = start;
+        start = null;
+    }
+    if (start == null) {
+        start = 0;
+    }
+    if (end == null) {
+        end = this.length;
+    }
+    const items: any[] = [];
+    for (let i = start; i < end; i++) {    
+        items.append(handler(this[i]));
+    }
+    return items;
+};
+
+// Iterate an array reversed.
+Array.prototype.iterate_reversed = function(start: any, end?: any, handler?: any): any {
+    if (handler == null && start != null) {
+        handler = start;
+        start = null;
+    }
+    if (start == null) {
+        start = 0;
+    }
+    if (end == null) {
+        end = this.length;
+    }
+    for (let i = end - 1; i >= start; i--) {    
+        const res = handler(this[i]);
+        if (res != null && !(res instanceof Promise)) {
+            return res;
+        }
+    }
+    return null;
+};
+Array.prototype.iterate_reversed_async = function(start: any, end?: any, handler?: any): any {
+    if (handler == null && start != null) {
+        handler = start;
+        start = null;
+    }
+    if (start == null) {
+        start = 0;
+    }
+    if (end == null) {
+        end = this.length;
+    }
+    let promises: Promise<any>[] = [];
+    for (let i = end - 1; i >= start; i--) {    
+        const res = handler(this[i]);
+        if (res != null && res instanceof Promise) {
+            promises.push(res);
+        }
+    }
+    return promises;
+};
+Array.prototype.iterate_reversed_async_await = async function(start: any, end?: any, handler?: any): Promise<any> {
+    if (handler == null && start != null) {
+        handler = start;
+        start = null;
+    }
+    if (start == null) {
+        start = 0;
+    }
+    if (end == null) {
+        end = this.length;
+    }
+    for (let i = end - 1; i >= start; i--) {    
+        const res = handler(this[i]);
+        if (res != null && res instanceof Promise) {
+            const pres = await res;
+            if (pres != null) {
+                return pres;
+            }
+        }
+    }
+    return null;
+};
+
+// Drop an item by the item itself.
+Array.prototype.drop = function(item) {
+    // @ts-expect-error
+    const dropped = new this.constructor(); // for when a class extends Array.
+    for (let i = 0; i < this.length; i++) {    
+        if (this[i] !== item) {
+            dropped.push(this[i])
+        }
+    }
+    return dropped;
+};
+
+// Drop an item by index.
+Array.prototype.drop_index = function(index) {
+    // @ts-expect-error
+    const dropped = new this.constructor(); // for when a class extends Array.
+    for (let i = 0; i < this.length; i++) {    
+        if (i != index) {
+            dropped.push(this[i])
+        }
+    }
+    return dropped;
+};
+
+// Drop duplicate items from an array.
+Array.prototype.drop_duplicates = function() {
+    return this.reduce((accumulator, val) => {
+        if (!accumulator.includes(val)) {
+            accumulator.push(val);
+        }
+        return accumulator;
+    }, []);
+}
+
+// Limit from end, always creates a new array.
+Array.prototype.limit_from_end = function<T extends any>(limit) {
+    let limited: T[] = [];
+    if (this.length > limit) {
+        for (let i = this.length - limit; i < this.length; i++) {
+            limited.push(this[i]);
+        }
+    } else {
+        for (let i = 0; i < this.length; i++) {
+            limited.push(this[i]);
+        }
+    }
+    return limited;
+}
+
+// Remove all items that equal the item from the array.
+Array.prototype.remove = function<T extends any>(item: T) {
+    let removed: T[] = [];
+    this.iterate((i) => {
+        if (i != item) {
+            removed.push(i);
+        }
+    })
+    return removed;
+};
+
+// Check if an array equals another array.
+// When the second parameter is not passed `this` will be used as `x` and `x` will be used as `y`.
+Array.prototype.eq = function(x?: any[], y?: any[]) {
+    const eq = (x, y) => {
+
+        // Arrays.
+        if (Array.isArray(x)) {
+            if (
+                Array.isArray(y) === false ||
+                x.length !== y.length
+            ) {
+                return false;
+            }
+            for (let i = 0; i < x.length; i++) {
+                if (typeof x[i] === "object" || typeof y[i] === "object") {
+                    const result = eq(x[i], y[i]);
+                    if (result === false) {
+                        return false;
+                    }
+                } else if (x[i] !== y[i]) {
+                    return false;
+                }
+            }
+            return true;
+        }
+
+        // Objects.
+        else if (typeof x === "object") {
+            if (
+                typeof y !== "object" ||
+                Array.isArray(y)
+            ) {
+                return false;
+            }
+            const x_keys = Object.keys(x);
+            const y_keys = Object.keys(y);
+            if (eq(x_keys, y_keys) === false) {
+                return false;
+            }
+            for (let i = 0; i < x_keys.length; i++) {
+                if (typeof x[x_keys[i]] === "object" || typeof y[y_keys[i]] === "object") {
+                    const result = eq(x[x_keys[i]], y[y_keys[i]]);
+                    if (result === false) {
+                        return false;
+                    }
+                } else if (x[x_keys[i]] !== y[y_keys[i]]) {
+                    return false;
+                }
+            }
+            return true;
+        }
+
+        // Others.
+        else if (typeof x !== typeof y) { return false; }
+        return x === y;
+    }
+    if (y == null) {
+        y = x;
+        x = this;
+    }
+    return eq(x, y);
+}
+
+// Divide into nested arrays.
+Array.prototype.divide = function(x) {
+    if (typeof x !== 'number' || x <= 0) {
+        throw new Error('Number of nested arrays must be a positive number');
+    }
+    const result: any[] = [];
+    const nested_len = Math.ceil(this.length / x);
+    for (let i = 0; i < this.length; i += nested_len) {
+        result.push(this.slice(i, i + nested_len));
+    }
+    return result;
+}