/**
 * CSS classes can be specified as a string or as an array of strings.
 *
 * For compatibility reasons, every individual string can contain
 * space-separated tokens, which are treated as multiple CSS classes.
 */
type CssClasses = string | string[];
/**
 * Adds all css classes to the given node.
 *
 * @param node a dom node
 * @param classes a series of css classes
 */
declare function addClass(node: HTMLElement, classes: CssClasses): void;
/**
 * Removes all css classes from the given node.
 *
 * @param node a dom node
 * @param classes a series of css classes
 */
declare function removeClass(node: HTMLElement, classes: CssClasses): void;
/**
 * Toggles all css classes on the given node.
 *
 * @param node a dom node
 * @param classes a series of css classes
 */
declare function toggleClass(node: HTMLElement, classes: CssClasses): void;
/**
 * Adds or removes the given css class(es), depending on the value `enabled`.
 * If `enabled` is true, this function ensures that the classes are present.
 * If `enabled` is false, it ensures that the class is *not* present.
 *
 * @param node a dom node
 * @param classes a series of css classes
 * @param enabled whether to add or remove the classes
 */
declare function applyClass(node: HTMLElement, classes: CssClasses, enabled: boolean): void;

/** Configuration of a new node's properties */
interface NodeProperties {
    /**
     * CSS classes for the new html node.
     * Can be either a string or an array of strings.
     */
    class?: CssClasses;
    /**
     * Attributes to be applied to the new html node.
     * Note: all values will be converted to strings, because
     * this is a wrapper around `node.setAttribute()`.
     */
    attrs?: Record<string, string>;
}
/** Configuration options for automatic node insertion. */
interface NodePosition {
    /**
     * If `referenceNode` is specified, the new element will be automatically inserted
     * relative to the specified node. By default, the new node will be inserted as
     * the last child of `referenceNode`.
     *
     * Use the `position` flag to customize the insertion behavior.
     */
    referenceNode: HTMLElement;
    /**
     * Inserts the node at the specified position. The default value is `"last"`.
     *
     * - `"first"`: as the first child of `referenceNode`
     * - `"last"`: as the last child of `referenceNode`
     * - `"only"`: as the only child of `referenceNode` (all other children are removed)
     * - `"replace"`: replaces a given `referenceNode` with the node
     * - `"before"`: the new node is inserted before `referenceNode` (as its neighbor)
     * - `"after"`: the new node is inserted after `referenceNode` (as its neighbor)
     */
    position?: "first" | "last" | "only" | "replace" | "before" | "after";
}
/** Customization options for {@link createElement}. */
type CreateOptions = NodeProperties & (NodePosition | {
    referenceNode?: undefined;
});
type ElementTag = keyof HTMLElementTagNameMap;
type HTMLElementForTag<Tag extends ElementTag> = HTMLElementTagNameMap[Tag];
/**
 * Creates a new HTML node with the given tag.
 *
 * For example, to create new div and insert it as the last element of `parent`:
 * ```ts
 * import { createElement } from "apprt-dom";
 * const parent = document.body;
 * const node = createElement("div", {
 *     class: "app",
 *     referenceNode: parent
 * });
 * ```
 *
 * @param tagName The node's tag, e.g. `"div"`.
 * @param options Additional settings to customize the node creation.
 */
declare function createElement<Tag extends ElementTag>(tagName: Tag, options?: CreateOptions): HTMLElementForTag<Tag>;
declare function createElement(tagName: string, options?: CreateOptions): HTMLElement;
/**
 * Inserts a node at the specified position relative to a another node.
 *
 * For example, to insert a node as the last element of `parent`:
 * ```ts
 * import { insertElement } from "apprt-dom";
 * const node = ...;
 * const parent = document.body;
 * insertElement(node, {
 *     referenceNode: parent,
 *     position: "last"
 * });
 * ```
 * @param node a html node
 * @param options the position options
 */
declare function insertElement(node: HTMLElement, options: NodePosition): void;
/**
 * Destroys a dom node.
 * The node will be removed from its parent and its content will be cleared.
 *
 * Does nothing if `node` is null or undefined.
 *
 * @param node the dom node to destroy
 */
declare function destroyElement(node: HTMLElement | null | undefined): void;

/**
 * Represents the size of an HTML node, including its margin.
 */
interface MarginSize {
    /** The width of the node (in pixels). */
    w: number;
    /** The height of the node (in pixels). */
    h: number;
}
/**
 * MarginBox defines the outer size and top-left position of a domNode.
 * Outer size is the element's size including it's margin.
 */
interface MarginBox extends MarginSize {
    /** The horizontal position (leftmost) of this node (in pixels). */
    l: number;
    /** The vertical position (topmost) of this node (in pixels). */
    t: number;
}
/**
 * Retrieves the MarginBox for a given node.
 *
 * @param node a dom node
 */
declare function getMarginBox(node: HTMLElement): MarginBox;
/**
 * Retrieves the MarginSize for a given node.
 *
 * @param node a dom node
 */
declare function getMarginSize(node: HTMLElement): MarginSize;
/**
 * Sets the MarginBox for a given node.
 *
 * @param node a dom node
 * @param marginBox
 *      Position and dimension for the MarginBox (left, top, width and height).
 *      All properties are optional.
 */
declare function setMarginBox(node: HTMLElement, marginBox: Partial<MarginBox>): void;

export { addClass, applyClass, createElement, destroyElement, getMarginBox, getMarginSize, insertElement, removeClass, setMarginBox, toggleClass };
export type { CreateOptions, CssClasses, ElementTag, MarginBox, MarginSize, NodePosition, NodeProperties };