@devstore/html-js/src/index.d.ts

DOM manipulation utils

/*
 * Copyright (C) 2023 svinokot.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 */

export type AttributeValue = string | null | undefined | number | boolean;

export type ValuesSet<T> = Record<string, T> | { [key: string]: T }

export interface Detail<T> {
	value: T;
	prevValue?: T;
}

export type Listener<E extends Event, T> = (event: E, detail: Detail<T>) => void;

export type Comparator<T> = (a: T | undefined, B: T) => boolean;
export type Callback<E extends Element, T> = (element: E, detail: Detail<T>) => void;

export interface PropertyOptions<E extends Element, T> {
	camparator: Comparator<T>;
	callback: Callback<E, T>;
	reflect?: string | boolean;
	value?: T;
}

export type Assembler<E, R, A extends any[]> = (element: E, ...args: A) => R;

export interface Batch<E extends Element> {
	batch: <R, A extends any[]>(assambler: Assembler<E, R, A>, ...args: A) => R[];
	select: (element: E | string, ...selectors: Array<string | E>) => Batch<E>;
	selectall: (element: E | string, ...selectors: Array<string | E>) => Batch<E>;
	append: (elements: E[] | E) => Batch<E>;
	elements: E[];
}

export type SupportedElements = Node | string;

export type RejectValues = false | null | undefined | 0;

export interface PropertyEventOptions<E extends Element, T> extends PropertyOptions<E, T>, EventListenerOptions {}

export function createCustomElement<E extends Element>(name: string): E;

export function getEventPath(event: Event): Element[];

export function get<E extends Element>(id: string): E | undefined;
export function get<E extends Element>(root: Element, id: string): E | undefined;

export function create<E extends Element>(name: string, attributes?: ValuesSet<AttributeValue>, ...classes: Array<string | RejectValues>): E;
export function append<E extends Element>(container: E, ...childs: Array<SupportedElements | RejectValues | NodeListOf<ChildNode> | Array<SupportedElements | RejectValues>>): E;

export function removeChildren<E extends Element>(container: E): E;

export function addClass<E extends Element>(element: E, ...classes: string[]): E;
export function removeClass<E extends Element>(element: E, ...classes: string[]): E;
export function toggleClass<E extends Element>(element: E, ...classes: string[]): E;

export function getAttribute(element: Element, attribute: string): AttributeValue;
export function setAttribute<E extends Element>(element: E, attribute: string, value?: AttributeValue): E;
export function addAttributes<E extends Element>(element: E, attributes: ValuesSet<AttributeValue>): E;
export function removeAttributes<E extends Element>(element: E, ...attributes: string[]): E;
export function hasAttribute(element: Element, attribute: string, ...values: AttributeValue[]): boolean;

export function addListeners<E extends Element>(element: E, events: ValuesSet<Listener<Event, unknown>>, eventOptions?: EventListenerOptions | boolean): E;

export function subscribe<E extends Element | Window | Document | DocumentFragment>(element: E, events: { [key in string]: (e: any, sender: E) => any }, eventOptions?: EventListenerOptions | boolean): () => void;

export function addProperty<E extends Element, T>(element: E, name: string, callbackOrProps: PropertyOptions<E, T> | Callback<E, T>): E;
export function addProperties<E extends Element, T>(element: E, properties: ValuesSet<PropertyOptions<E, T> | Callback<E, T>>): E;

export function addEventProperty<E extends Element, T>(element: E, name: string, props?: PropertyEventOptions<E, T>): E;

export function addEventReflectAttributes<E extends Element>(element: E, ...attributes: string[]): E;

//export function addReaction<E extends Element, T>(element: E, callback: Callback<E, T>, options = _defaultBehaviorOptions): E;

export function setStyle<E extends Element>(element: E, style: string | Record<string, any>): E;

export function select<E extends Element>(element: E | string, ...selectors: Array<string | E>): Batch<E>;
export function selectAll<E extends Element>(element: E | string, ...selectors: Array<string | E>): Batch<E>;

export function batch<R, A extends any[]>(elements: Element[], assambler: (element: Element, ...args: A) => R, ...args: A): R;