Skip to content
This repository was archived by the owner on Mar 19, 2025. It is now read-only.

dom.md

Latest commit

 

History

History
378 lines (247 loc) · 13.1 KB

dom.md

File metadata and controls

378 lines (247 loc) · 13.1 KB

$dom.component / $dom

Namespace: $dom

This NAMESPACE provides features for DOM elements.

Table of contents

Interfaces

Type Aliases

Functions

Public

add

▸ add(): HTMLElement

Please stop using this

Deprecated

Returns

HTMLElement

assign

▸ assign<EL>(element, ...attrs_array): EL

Procedure for merging object into the element properties. Very simple example: $dom.assign(document.body, { className: "test" }); is equivalent to document.body.className= "test";. It is not deep copy in general, but it supports style, style_vars and dataset objects (see below).

#1: All together

const el= document.body;
const onclick= function(){ console.log(this.dataset.js_param); };
$dom.assign(el, { textContent: "BODY", style: "color: red;", dataset: { js_param: "CLICKED" }, onclick });
//result HTML: <body style="color: red;" data-js_param="CLICKED">BODY</body>
//console output on click: "CLICKED"
$dom.assign(el, { style: { color: "green" } });
//result HTML: <body style="color: green;" data-js_param="CLICKED">BODY</body>
//console output on click: "CLICKED"

\*.classList.toggle

const el= document.body;
$dom.assign(el, { classList: { testClass: -1 } });
//result HTML: <body class="testClass">…</body>
$dom.assign(el, { classList: { testClass: -1 } });
//result HTML: <body class="">…</body>

$dom.assign(el, { classList: { testClass: true } });//or 1
//result HTML: <body class="testClass">…</body>
$dom.assign(el, { classList: { testClass: false } });//or 0
//result HTML: <body class="">…</body>
//...

#3 Links and images

$dom.assign(A_ELEMENT, { href: "www.google.com" });//=> <a href="www.google.com" …
$dom.assign(IMG_ELEMENT, { src: "image.png" });//=> <img src="image.png" …

**#4 data\* and aria\***
$dom.assign(el, { ariaLabel: "The aria-label", dataExample: "data-example" });//=> <body aria-label="The aria-label" data-example="data-example">

Version

2.0.0

Type parameters

Name Type
EL extends HTMLElement

Parameters

Name Type
element EL
...attrs_array T_DOM_ATTRS<EL>[]

Returns

EL

assignNS

▸ assignNS<EL>(namespace_group, element, ...attrs_array): EL

Procedure for merging object into the element properties (see html version assign).

Version

2.0.0

Type parameters

Name Type
EL extends SVGElement

Parameters

Name Type Description
namespace_group string Group representation of namespace, use "SVG" for setting attributes for svgs.
element EL -
...attrs_array T_DOM_ATTRS<EL>[] -

Returns

EL

component

▸ component<K>(tag_name, attrs?, params?): componentOut<K>

This 'functional class' is syntax sugar around document.createElement(NS) and document.createDocumentFragment for creating DOM components and their adding to live DOM in performance friendly way.

So pseudo code:

function Component(…){
	const { add, share }= $dom.component(…Parent Element…);
		add(…Child Element…);
		add(…Child Element…, -1);
			add(…Child Element…);
	…
	return share;
}

Yelds into:

<!--<Component>-->
	<Parent Element>
	 <Child Element></Child Element>
	 <Child Element>
		<Child Element></Child Element>
	 </Child Element>
	…
	</Parent Element>
<!--</Component>-->

Version

2.0.0

Type parameters

Name Type
K extends "" | "symbol" | "object" | "link" | "small" | "sub" | "sup" | "map" | "filter" | "input" | "set" | "code" | "data" | "progress" | "stop" | "track" | "source" | "button" | "address" | "view" | "clipPath" | "font" | "marker" | "mask" | "a" | "abbr" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "blockquote" | "body" | "br" | "canvas" | "caption" | "cite" | "col" | "colgroup" | "datalist" | "dd" | "del" | "details" | "dfn" | "dialog" | "dir" | "div" | "dl" | "dt" | "em" | "embed" | "fieldset" | "figcaption" | "figure" | "footer" | "form" | "frame" | "frameset" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "head" | "header" | "hgroup" | "hr" | "html" | "i" | "iframe" | "img" | "ins" | "kbd" | "label" | "legend" | "li" | "main" | "mark" | "marquee" | "menu" | "meta" | "meter" | "nav" | "noscript" | "ol" | "optgroup" | "option" | "output" | "p" | "param" | "picture" | "pre" | "q" | "rp" | "rt" | "ruby" | "s" | "samp" | "script" | "section" | "select" | "slot" | "span" | "strong" | "style" | "summary" | "table" | "tbody" | "td" | "template" | "textarea" | "tfoot" | "th" | "thead" | "time" | "title" | "tr" | "u" | "ul" | "var" | "video" | "wbr" | "animate" | "animateMotion" | "animateTransform" | "circle" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "svg" | "switch" | "text" | "textPath" | "tspan" | "use" | "<>" | "zzz_text"

Parameters

Name Type Description
tag_name K HTML Element tag name such as p, li, …, also svg, polyline, clipPath, …. Important: You must choose proper params, see namespace_group!
attrs? T_DOM_ATTRS<K> -
params? componentParams -

Returns

componentOut<K>

componentListener

▸ componentListener<K>(event, callback): component_listener

This provide more DRY way to register native events listeners inside component such as click, touchemove, ….

Type parameters

Name Type
K extends keyof DocumentEventMap

Parameters

Name Type Description
event K Browser events
callback (this: T_DOM_ListenersAPI, ev: DocumentEventMap[K]) => any Callback with arguments based on EventTarget.addEventListener().

Returns

component_listener

▸ componentListener<K>(event, ...attrs): component_listener

This provide more DRY way to register events listeners for component such as init, mount, ….

Type parameters

Name Type
K extends keyof T_DOM_ListenersMap

Parameters

Name Type Description
event K Component lifecycle events
...attrs T_DOM_ListenersMap[K] -

Returns

component_listener

▸ componentListener<DATA>(event, data, onUpdate): component_listener

This provide more DRY way to register onupdate handler inside component.

Version

2.0.0

Type parameters

Name Type
DATA extends object

Parameters

Name Type Description
event "update" -
data DATA Inittial data similar to onupdate.
onUpdate (data: DATA) => Omit<HTMLElement, "classList"> & T_DOM_ATTRS_MODIFIED Callback simira to onupdate.

Returns

component_listener

Private

T_DOM_ATTRS

Ƭ Private T_DOM_ATTRS<T>: T extends keyof T_DOM_HETNM ? Omit<T_DOM_HETNM[T], "classList"> & T_DOM_ATTRS_MODIFIED : Omit<T, "classList"> & T_DOM_ATTRS_MODIFIED

Just element attributtes

In most cases, you can use native propertie such as MDN WEB/API/Element and so on (e.g. Text).

There is added support for data[A-Z].*/aria[A-Z].* to be converted to the kebab-case alternatives.

Type parameters

Name Type
T extends keyof T_DOM_HETNM | T_DOM_HETNM[keyof T_DOM_HETNM]

T_DOM_ATTRS_MODIFIED

Ƭ Private T_DOM_ATTRS_MODIFIED: Object

Type declaration

Name Type Description
classList Record<string, -1 | 0 | 1> Provide option to add/remove/toggle CSS clasess (index of object) using 1/0/-1. In fact el.classList.toggle(class_name) for -1 and el.classList.toggle(class_name, Boolean(...)) for others.
style string In fact argumen for *.setAttribute("style", *).

T_DOM_HETNM

Ƭ Private T_DOM_HETNM: HTMLElementTagNameMap & SVGElementTagNameMap & { ``: HTMLElement ; `<>`: `DocumentFragment` ; `zzz_text`: `Text` }

componentOut

Ƭ Private componentOut<T>: T extends "" ? component_empty : component_add<T>

Type parameters

Name Type
T extends keyof T_DOM_HETNM

empty

▸ empty(container): void

Procedure removes all children of container

Parameters

Name Type
container HTMLElement

Returns

void

mount

▸ mount(element_target, type): <T>(element: T) => T

Procedure provide ways to insert elements into DOM in relation to element_target.

Parameters

Name Type
element_target HTMLElement | SVGElement
type "replace" | "after" | "before" | "replaceContent" | "childFirst" | "childLast"

Returns

fn

▸ <T>(element): T

Type parameters
Name Type
T extends HTMLElement | SVGElement | componentOut<keyof T_DOM_HETNM>
Parameters
Name Type
element T
Returns

T