Dommali NPM | npm.io

dommali

a lightweight DOM manipulation library with jQuery-inspired "fluent" API

The use of jQuery makes DOM manipulation code compact and legible - but it is a rather large library with many no longer required features. The idea behind dommali (pronounced "dom-ma-li") is to create a thin layer on top of the API of modern browsers (excluding MS IE and "classic" MS Edge!) that still allows code to be as concise as jQuery would do.

dommali was inspired by nanoJS and femtoJS - and like those, its implementation is so simple that it is not too difficult to add new methods or remove unwanted ones in order to enhance functionality or reduce size.

Important: dommali is no drop-in replacement for jQuery! If you need something like that, look for Zepto.js, Cash, UmbrellaJS, Chibi or similar

The most notable differences between dommali and jQuery (or a look-alike) are:

iterator callback functions do not bind this to the DOM element just processed, instead they get a corresponding dommali object as their first argument - as a consequence, "fat arrow" functions may more easily serve as callbacks
methods retrieving the current size and position of a DOM element have specific names which makes their intention more obvious particularly for casual programmers: f.e., positionInViewport vs. positionInParent vs. positionOnPage
additionally, some methods have names (or synonyms) which indicate whether they return layout or render measures: layout positions and dimensions are used by the browser layout engine and do not consider any CSS transforms applied to DOM elements, whereas render measures take such transforms into account
dommali does not define its own event object - nowadays, creating DOM events is so simple that there is just no need for a wrapper. It does, however, support extraParameters passed when triggering an event and Event data specified while registering an event handler
within asynchronous functions it is possible to waitFor the arrival of an event or to write loops that repeatUntil a given event arrives - both functions may also be provided with a timeout in order to prevent waiting or looping forever
event handler registrations support the special "selector" @this which effectively prevents the handler from being invoked by bubbling events
both event handler management functions and waitFor or repeatUntil support anchored events, i.e., event names followed by a CSS selector which restricts the events to be handled to those triggered on specific elements only
dommali does not support CSS animations but animated CSS transitions - and those are really simple

NPM users: please consider the Github README for the latest description of this package (as updating the docs would otherwise always require a new NPM package version)

Just a small note: if you like this module and plan to use it, consider "starring" this repository (you will find the "Star" button on the top right of this page), so that I know which of my repositories to take most care of.

Overview

Here are the methods provided by dommali in alphabetical order:

Installation

dommali may be used as an ECMAScript module (ESM), a CommonJS or AMD module or from a global variable.

You may either install the package into your build environment using NPM with the command

npm install dommali

or load the plain script file directly

<script src="https://unpkg.com/dommali"></script>

Access

How to access the package depends on the type of module you prefer

ESM (or Svelte): import dommali from 'dommali'
CommonJS: const dommali = require('dommali')
AMD: require(['dommali'], (dommali) => {...})

Alternatively, you may access the global variable dommali directly.

Usage within Svelte

For Svelte, it is recommended to import the package in a module context. From then on, its exports may be used as usual:

<script context="module">
  import dommali from 'dommali'
</script>

<script>
  const $ = dommali // make "dommali" calls look like "jQuery" ones
  $(document.body).html('<h1>Hello, World!</h1>')
</script>

Usage as ECMAscript, CommonJS or AMD Module (or as a global Variable)

Let's assume that you already "required" or "imported" (or simply loaded) the module according to your local environment. In that case, you may use it as follows:

const $ = dommali // make "dommali" calls look like "jQuery" ones
$(document.body).html('<h1>Hello, World!</h1>')

API Reference

Similar to jQuery, dommali objects (i.e., instances of type DOMMaLi) represent collections of zero, one or multiple DOM elements. Internally, these elements may not be listed in document order unless they have been found by a CSS query or retrieved as the children of another element. While dommali objects may represent DOM elements of any type, some methods only work on items of type HTMLElement (other elements will be ignored) - those methods are explicitly marked in their description.

The signatures shown below are those used by TypeScript

Factory Function

dommali():DOMMaLireturns a new empty dommali object, i.e., one that represents no DOM element
dommali(startup:Function):typeof DOMMaLiis a shortcut for DOMMaLi.ready(startup) (see below)
dommali(selector:string):DOMMaLireturns a dommali object representing all DOM elements matching the given CSS selector
dommali(html:string):DOMMaLireturns a new dommali object representing all DOM elements created from the given HTML code
dommali(element:Element):DOMMaLireturns a new dommali object representing the given DOM element
dommali(elements:Element[]):DOMMaLireturns a new dommali object representing the given DOM elements (in the given order)
dommali(bridge:DOMMaLi):DOMMaLireturns a duplicate of the given dommali object

Class Methods

DOMMaLi.extraParametersOfEvent(Event:Event):any[]returns the (possible empty) list of additional arguments passed when the given Event was triggered (see trigger)
DOMMaLi.ready(startup:Function):typeof DOMMaLiregisters a function which is to be called as soon as the DOM is ready (i.e., all DOM elements are present although images and other resources may not be completely loaded). If the DOM is ready at the moment the startup functions wants to be registered, it will be invoked immediately. It is safe to register new startup functions at any time - even while they are being executed
DOMMaLi.textHeight(Text:string, TemplateOrSettings?:any):numberreturns the height of a given Text (in pixels) when rendered in a given dommali object, a given DOM element or in its own DOM element with given CSS settings. For that purpose, the optional TemplateOrSettings argument may contain either a dommali object, a DOM element or a plain JavaScript object with one or multiple "relevant" CSS settings. Relevant CSS settings include font-family, font-size, font-weight, font-style, font-variant, font-variant-caps, font-variant-numeric, font-variant-alternates, font-variant-ligatures, font-variant-east-asian, font-stretch, font-kerning, font-size-adjust, font-synthesis, font-language-override, white-space, letter-spacing, word-spacing, text-indent, text-transform, word-break, line-break, line-height and width - other CSS settings will be ignored. Please note, that you may specify a desired text width explicity in order to enforce line wrapping of long texts
DOMMaLi.textWidth(Text:string, TemplateOrSettings?:any):numberreturns the width of a given Text (in pixels) when rendered in a given dommali object, a given DOM element or in its own DOM element with given CSS settings. For that purpose, the optional TemplateOrSettings argument may contain either a dommali object, a DOM element or a plain JavaScript object with one or multiple "relevant" CSS settings. Relevant CSS settings include font-family, font-size, font-weight, font-style, font-variant, font-variant-caps, font-variant-numeric, font-variant-alternates, font-variant-ligatures, font-variant-east-asian, font-stretch, font-kerning, font-size-adjust, font-synthesis, font-language-override, white-space, letter-spacing, word-spacing, text-indent and text-transform - other CSS settings will be ignored

Object Inspection

get length ():numbercontains the number of DOM elements represented by this dommali object
size ():numberreturns the number of DOM elements represented by this dommali object
isEmpty ():booleanreturns true if this dommali object does not represent any DOM element - or false otherwise
subjects ():Element[]returns a copy of the list of DOM elements represented by this dommali object
subject (Index:number):Element|undefinedreturns the single item found at index Index in the list of DOM elements represented by this dommali object - or undefined if no such item exists
indexOf (Value:Element|DOMMaLi):numberlooks for the given DOM element or the first element represented by the given dommali object in the list of DOM elements represented by this dommali object and returns its index - or -1 if the element can not be found

Element Extraction

slice (start?:number, end?:number):DOMMaLireturns a new dommali object representing all items from the list of DOM elements represented by this dommali object starting at index start and ending before index end (or until the end of the list, if end was omitted). If both start and end are missing, this dommali object is simply duplicated
first ():DOMMaLireturns a new dommali object representing the first element from the list of DOM elements represented by this dommali object - or any empty dommali object if this one is empty as well
last ():DOMMaLireturns a new dommali object representing the last element from the list of DOM elements represented by this dommali object - or any empty dommali object if this one is empty as well
eq (Index:number):DOMMaLireturns a new dommali object representing the element at index Index from the list of DOM elements represented by this dommali object - or any empty dommali object if no such element exists

Content Iterators

forEach (Callback:(Item:DOMMaLi, Index:number, Container:DOMMaLi) => any):DOMMaLiiterates over all DOM elements represented by this dommali object and invokes the given Callback function with the following arguments:a dommali object representing the current DOM element, its index in the list of DOM elements represented by this dommali object and that object itself. In contrast to jQuery and many other similar libraries, this is not bound to the current DOM element - this simplifies the use of "fat arrow" functions as callbacks
filter (Selector:string|String):DOMMaLireturns a new dommali object representing only those DOM elements from this dommali object which match the given CSS selector
filter (Callback:(Item:DOMMaLi, Index:number, Container:DOMMaLi) => boolean):DOMMaLireturns a new dommali object representing only those DOM elements from this dommali object for which the given Callback function returns true. This function is invoked with the following arguments:a dommali object representing the current DOM element, its index in the list of DOM elements represented by this dommali object and that object itself. In contrast to jQuery and many other similar libraries, this is not bound to the current DOM element - this simplifies the use of "fat arrow" functions as callbacks

CSS Queries

matches (Selector:string|String):booleanreturns true if the first DOM element represented by this dommali object matches the given CSS selector - or false otherwise
find (Selector:string|String):DOMMaLireturns a new (and possibly empty) dommali object representing all those DOM elements within the scope of this dommali object that match the given CSS selector
findFirst (Selector:string|String):DOMMaLireturns a new (and possibly empty) dommali object representing the first DOM element within the scope of this dommali object that matches the given CSS selector

Position and Size

positionInViewport ():{ left:number,top:number }|undefinedreturns the rendering position of the first DOM element represented by this dommali object relative to the current viewport (or undefined if this dommali object is empty)
renderPositionInViewport ():{ left:number,top:number }|undefinedis just a synonym for positionInViewport, emphasizing the fact, that the rendering position is returned (which depends of CSS transforms for that DOM element)
positionInParent ():{ left:number,top:number }|undefinedreturns the layout position of the first HTML element represented by this dommali object relative to its "offset parent" (or undefined if either this dommali object is empty, its first element is not an HTML element or no offset parent could be found)
layoutPositionInParent ():{ left:number,top:number }|undefinedis just a synonym for positionInParent, emphasizing the fact, that the layout position is returned (which is independent of any DOM element CSS transforms)
positionOnPage ():{ left:number,top:number }|undefinedreturns the layout position of the first DOM element represented by this dommali object relative to the document (or undefined if this dommali object is empty or its first element is not an HTML element)
layoutPositionOnPage ():{ left:number,top:number }|undefinedis just a synonym for positionOnPage, emphasizing the fact, that the layout position is returned (which is independent of any DOM element CSS transforms)
width (newValue?:number):number|DOMMaLi|undefinedif no newValue is given, this method returns the layout width of the first DOM element represented by this dommali object (or undefined if this dommali object is empty or its first element is not an HTML element). Otherwise, the layout width of all HTML elements represented by this dommali object is set to the newValue pixels
height (newValue?:number):number|DOMMaLi|undefinedif no newValue is given, this method returns the layout height of the first DOM element represented by this dommali object (or undefined if this dommali object is empty or its first element is not an HTML element). Otherwise, the layout height of all HTML elements represented by this dommali object is set to the newValue pixels
layoutWidth (newValue?:number):number|DOMMaLi|undefinedis just a synonym for width, emphasizing the fact, that the layout width is returned or set (which is independent of any DOM element CSS transforms)
layoutHeight (newValue?:number):number|DOMMaLi|undefinedis just a synonym for height, emphasizing the fact, that the layout height is returned or set (which is independent of any DOM element CSS transforms)
outerWidth (newValue?:number):number|DOMMaLi|undefinedis just a synonym for width, emphasizing the fact, that the returned width includes the element's padding and border
outerHeight (newValue?:number):number|DOMMaLi|undefinedis just a synonym for height, emphasizing the fact, that the returned height includes the element's padding and border
renderWidth ():number|undefinedreturns the render width of the first DOM element represented by this dommali object (or undefined if this dommali object is empty). The result is affected by any CSS transforms for that element
renderHeight ():number|undefinedreturns the render height of the first DOM element represented by this dommali object (or undefined if this dommali object is empty). The result is affected by any CSS transforms for that element
innerWidth ():number|undefinedreturns the "inner" layout width of the first DOM element represented by this dommali object (or undefined if this dommali object is empty) without border, padding and scrollbars
innerHeight ():number|undefinedreturns the "inner" layout height of the first DOM element represented by this dommali object (or undefined if this dommali object is empty) without border, padding and scrollbars

DOM Hierarchy

parent ():DOMMaLireturns a new dommali object representing the "parent" of the first DOM element represented by this dommali object (or an empty dommali object if this one is empty as well)
closest (Selector:string|String):DOMMaLireturns a new dommali object representing the innermost element among the first DOM element represented by this dommali object and its parents, that matches the given Selector (or an empty dommali object if either this one is empty or no matching DOM element could be found)
isAttached ():booleanreturns true, if the first DOM element represented by this dommali object is part of the document - or false otherwise
contains (Candidate:DOMMaLi):booleanreturns true, if the first DOM element represented by this dommali object contains the first DOM element represented by the given Candidate - or false otherwise
children (Selector?:string|String):DOMMaLiif Selector is missing, this method returns a new dommali object representing all direct "children" of the first DOM element represented by this dommali object. Otherwise, the new dommali object represents only those children which also match the given CSS Selector
firstChild (Selector?:string|String):DOMMaLiif Selector is missing, this method returns a new dommali object representing the first direct "child" of the first DOM element represented by this dommali object. Otherwise, the new dommali object represents the first child which also matches the given CSS Selector
lastChild (Selector?:string|String):DOMMaLiif Selector is missing, this method returns a new dommali object representing the last direct "child" of the first DOM element represented by this dommali object. Otherwise, the new dommali object represents the last child which also matches the given CSS Selector
prev (Selector?:string|String):DOMMaLiif Selector is missing, this method returns a new dommali object representing the immediately preceding "sibling" of the first DOM element represented by this dommali object - i.e., the direct child of that element's parent, which immediately precedes it. Otherwise, the new dommali object represents the nearest preceding "sibling" which also matches the given CSS Selector
next (Selector?:string|String):DOMMaLiif Selector is missing, this method returns a new dommali object representing the immediately following "sibling" of the first DOM element represented by this dommali object - i.e., the direct child of that element's parent, which immediately follows it. Otherwise, the new dommali object represents the nearest following "sibling" which also matches the given CSS Selector

Visibility

show ():DOMMaLimakes all HTML elements represented by this dommali object (potentially) visible by setting their CSS property display to a value different from none - if possible, dommali tries to restore any setting that was active before an element was hidden. Otherwise, it uses the default setting for the given element tag - or block if all fails
hide ():DOMMaLimakes all HTML elements represented by this dommali object invisible by setting their CSS property display to none

Scrolling

scrollLeft (newValue?:number):number|DOMMaLi|undefinedif no newValue is given, this method returns the number of pixels by which the first DOM element represented by this dommali object is scrolled from its left edge (or undefined if this dommali object is empty) Otherwise, it scrolls all DOM elements represented by this dommali object to a position newValue pixels from their left edge
scrollTop (newValue?:number):number|DOMMaLi|undefinedif no newValue is given, this method returns the number of pixels by which the first DOM element represented by this dommali object is scrolled from its top edge (or undefined if this dommali object is empty) Otherwise, it scrolls all DOM elements represented by this dommali object to a position newValue pixels from their top edge
scrollWidth ():number|undefinedreturns the width of the contents of the first DOM element represented by this dommali object (or undefined if this dommali object is empty), including content not visible due to an overflow
scrollHeight ():number|undefinedreturns the height of the contents of the first DOM element represented by this dommali object (or undefined if this dommali object is empty), including content not visible due to an overflow
scrollTo (x:number, y:number, Mode:'instant'|'smooth'|'auto' = 'auto'):DOMMaLiscrolls all DOM elements represented by this dommali object to a position x pixels from their left and y pixels from their top edge. If given, Mode specifies whether the scrolling should animate smoothly or happen instantly in a single jump

CSS Class Management

hasClass (Classes:string):booleanreturns true if the first DOM element represented by this dommali object is associated with all (space-separated) CSS classes given by Classes - or false otherwise
addClass (Classes:string):DOMMaLiassociates all DOM elements represented by this dommali object with the (space-separated) CSS classes given by Classes
toggleClass (Classes:string):DOMMaLitoggles the association of all DOM elements represented by this dommali object with the (space-separated) CSS classes given by Classes
removeClass (Classes:string):DOMMaLiremoves the association of all DOM elements represented by this dommali object with the (space-separated) CSS classes given by Classes

Insertion and Removal

append (Content:string|String|DOMMaLi|Element|Element[]):DOMMaLiif Content contains HTML code, this method inserts the DOM elements repeatedly created based on Content at the end of every DOM element represented by this dommali object - otherwise the DOM elements given by Content are inserted at the end of the first DOM element represented by this dommali object only. Content may contain HTML code, CSS selectors, one or multiple DOM elements or another dommali object
prepend (Content:string|String|DOMMaLi|Element|Element[]):DOMMaLiif Content contains HTML code, this method inserts the DOM elements repeatedly created based on Content at the beginning of every DOM element represented by this dommali object - otherwise the DOM elements given by Content are inserted at the beginning of the first DOM element represented by this dommali object only. Content may contain HTML code, CSS selectors, one or multiple DOM elements or another dommali object
insertAfter (Content:DOMMaLi):DOMMaLiinserts all DOM elements represented by this dommali object after the first DOM element represented by the given Content. Content may contain HTML code, CSS selectors, one or multiple DOM elements or another dommali object
insertBefore (Content:DOMMaLi):DOMMaLiinserts all DOM elements represented by this dommali object before the first DOM element represented by the given Content. Content may contain HTML code, CSS selectors, one or multiple DOM elements or another dommali object
replaceWith (Replacement:string|String|DOMMaLi|Element|Element[]):voidif Content contains HTML code, this method replaces every DOM element represented by this dommali object by the DOM elements repeatedly created based on Content - otherwise the first DOM element represented by this dommali object is replaced by the DOM elements given by Content. Content may contain HTML code, CSS selectors, one or multiple DOM elements or another dommali object
remove ():DOMMaLiremoves all DOM elements represented by this dommali object

Properties

prop (Property:string, newValue?:any):DOMMaLi|any|undefinedif no newValue is given, this method returns the value of property Property of the first DOM element represented by this dommali object (or undefined if this dommali object is empty). Otherwise, property Property of all DOM elements represented by this dommali object is set to newValue
hasProp (Property:string):booleanreturns true if property Property is found in the first DOM element represented by this dommali object - or false otherwise
removeProp (Property:string):DOMMaLiremoves property Property from all DOM elements represented by this dommali object

Data

data (Key:string, newValue?:any):DOMMaLi|any|undefinedif no newValue is given, this method returns the value of data entry Key of the first DOM element represented by this dommali object (or undefined if this dommali object is empty). Otherwise, data entry Key of all DOM elements represented by this dommali object is set to newValue. Data entries are custom values of any JavaScript type stored in DOM elements without polluting their namespace or overwriting DOM element properties or methods
hasData (Key:string):booleanreturns true if data entry Key is found in the first DOM element represented by this dommali object - or false otherwise
removeData (Key:string):DOMMaLiremoves data entry Key from all DOM elements represented by this dommali object

Attributes

attr (Attribute:string, newValue?:any):DOMMaLi|string|undefinedif no newValue is given, this method returns the value of HTML attribute Attribute of the first DOM element represented by this dommali object (or undefined if this dommali object is empty). Otherwise, the HTML attribute Attribute of all DOM elements represented by this dommali object is set to newValue
hasAttr (Attribute:string):booleanreturns true if HTML attribute Attribute is found in the first DOM element represented by this dommali object - or false otherwise
removeAttr (Attribute:string):DOMMaLiremoves HTML attribute Attribute from all DOM elements represented by this dommali object

CSS

css (Property:string|string, newValue?:string):DOMMaLi|string|undefinedif no newValue is given, this method returns the computed value of CSS property Property of the first DOM element represented by this dommali object (or undefined if this dommali object is empty). Otherwise, the CSS property Property of all DOM elements represented by this dommali object is set to newValue
css (PropertyList:string[]):PlainObject|undefinedreturns the computed values of all CSS properties given by PropertyList of the first DOM element represented by this dommali object as a plain JavaScript object with the given property names as keys (or undefined if this dommali object is empty)
css (PropertySet:PlainObject):DOMMaLisets the CSS properties given by the keys of PropertySet of all DOM elements represented by this dommali object to the values specified in PropertySet

html (newValue?:string):DOMMaLi|string|undefinedif no newValue is given, this method returns the inner HTML of the first DOM element represented by this dommali object (or undefined if this dommali object is empty). Otherwise, the inner HTML of all DOM elements represented by this dommali object is set to newValue
text (newValue?:string):DOMMaLi|string|undefinedif no newValue is given, this method returns the inner text of the first DOM element represented by this dommali object (or undefined if this dommali object is empty). Otherwise, the inner text of all DOM elements represented by this dommali object is set to newValue
appendText (Value:string):DOMMaLiinserts the text given by Value after the inner text of all DOM elements represented by this dommali object
prependText (Value:string):DOMMaLiinserts the text given by Value before the inner text of all DOM elements represented by this dommali object

Event Handling

on (anchoredEvent:string, Handler:Function):DOMMaLiregisters the given event handler Handler for the event anchoredEvent in all DOM elements represented by this dommali object. Handler will be invoked whenever the given Event is triggered on the given "anchor" as seen from these DOM elements (provided that the event is allowed to "bubble" if the anchor is a descendant of a given DOM object). If Handler returns the explicit value false, Event.stopPropagation() and Event.preventDefault() are called for the current event
on (Events:string, Handler:Function):DOMMaLiregisters the given event handler Handler for every event in the (space-separated) list given by Events in all DOM elements represented by this dommali object. Handler will be invoked whenever one of the given Events is triggered on one of these DOM elements themselves or one of their descendants (if the event is allowed to "bubble"). If Handler returns the explicit value false, Event.stopPropagation() and Event.preventDefault() are called for the current event
on (Events:string, Selector:string|String|null, Handler:Function):DOMMaLiregisters the given event handler Handler as a "delegated event handler" for every event in the (space-separated) list given by Events in all DOM elements represented by this dommali object. Handler will be invoked whenever one of the given Events is triggered on one of these DOM elements themselves or one of their descendants (if the event is allowed to "bubble") - provided that the original event target matches the given CSS Selector. Setting Selector to null simply skips the matching. If Handler returns the explicit value false, Event.stopPropagation() and Event.preventDefault() are called for the current event
on (anchoredEvent:string, Data:any, Handler:Function):DOMMaLiregisters the given event handler Handler for the event anchoredEvent in all DOM elements represented by this dommali object. Handler will be invoked whenever the given Event is triggered on the given "anchor" as seen from these DOM elements (provided that the event is allowed to "bubble" if the anchor is a descendant of a given DOM object). Additionally, property data of the incoming event is set to Data before the registered handler is called. If Handler returns the explicit value false, Event.stopPropagation() and Event.preventDefault() are called for the current event
on (Events:string, Selector:string|String|null, Data:any, Handler:Function):DOMMaLiregisters the given event handler Handler (as a "delegated event handler" if Selector is not null) for every event in the (space-separated) list given by Events in all DOM elements represented by this dommali object. Handler will be invoked whenever one of the given Events is triggered on one of these DOM elements themselves or one of their descendants (if the event is allowed to "bubble") - provided that the original event target matches the given CSS Selector. Additionally, property data of the incoming event is set to Data before the registered handler is called. Setting Selector to null simply skips the matching. If Handler returns the explicit value false, Event.stopPropagation() and Event.preventDefault() are called for the current event
once (Events:string, Handler:Function):DOMMaLibehaves like once(Events,Handler), but automatically unregisters the given Handler upon its first invocation
once (anchoredEvent:string, Handler:Function):DOMMaLibehaves like once(anchoredEvent,Handler), but automatically unregisters the given Handler upon its first invocation
once (Events:string, Selector:string|String|null, Handler:Function):DOMMaLibehaves like once(Events,Selector,Handler), but automatically unregisters the given Handler upon its first invocation
once (anchoredEvent:string, Data:any, Handler:Function):DOMMaLibehaves like once(anchoredEvent,Data,Handler), but automatically unregisters the given Handler upon its first invocation
once (Events:string, Selector:string|String|null, Data:any, Handler:Function):DOMMaLibehaves like once(Events,Selector,Data,Handler), but automatically unregisters the given Handler upon its first invocation
off ():DOMMaLiunregisters all event handlers registered in all DOM elements represented by this dommali object
off (anchoredEvent:string):DOMMaLiunregisters all event handlers registered for the given anchoredEvent in all DOM elements represented by this dommali object
off (Events:string):DOMMaLiunregisters all event handlers registered for every event in the (space-separated) list given by Events in all DOM elements represented by this dommali object
off (Events:string, Selector:string|String|null):DOMMaLiunregisters all event handlers registered as delegated event handlers with CSS selector Selector for every event in the (space-separated) list given by Events in all DOM elements represented by this dommali object
off (anchoredEvent:string, Handler:Function):DOMMaLiunregisters the given Handler registered for the given anchoredEvent in all DOM elements represented by this dommali object
off (Events:string, Selector:string|String|null, Handler:Function):DOMMaLiunregisters the given Handler registered as delegated event handler with CSS selector Selector for every event in the (space-separated) list given by Events in all DOM elements represented by this dommali object
repeatUntil (...anchoredEventsOrTimeoutOrLoopBody:(string|number|Function)[]):Promise<any>returns a promise which resolves after one of the given anchoredEvents has been received or the number of milliseconds given by a Timeout have passed. Until then, the given (asynchronous) LoopBody function will be executed as often as possible. If LoopBody returns any other value but undefined, the loop is terminated and the promise resolves to the loop body's return value. After receiving an event, repeatUntil resolves to that event as soon as LoopBody has finished; in case of a timeout it resolves to the actual number of milliseconds that have passed since the initial invocation (this number is usually slightly higher than the specified timeout) - but again, only after LoopBody has finished. All arguments except LoopBody are optional - calling repeatUntil solely with a LoopBody simply repeatedly executes that function until it returns a value different from undefined (see Notes on repeatUntil)
trigger (Event:string|Event, extraParameters?:any[]):booleanfires the given Event on all DOM elements represented by this dommali object. If Event is given as a string, a CustomEvent of type Event is created and fired. The optional argument extraParameters may be a single value or a list of values which are passed as additional arguments (after the event object itself) to the Handler. trigger returns false if at least one of the invoked event handlers called Event.preventDefault() or true otherwise
waitFor (...anchoredEventsOrTimeout:(string|number)[]):Promise<any>returns a promise which resolves as soon as one of the given anchoredEvents has been received or the number of milliseconds given by a Timeout have passed. All arguments are optional - calling waitFor without any arguments just resolves immediately. After receiving an event, waitFor resolves to that event; in case of a timeout it resolves to the actual number of milliseconds that have passed since the initial invocation (this number is usually slightly higher than the specified timeout) (see Notes on waitFor)

Focus Handling

focus ():DOMMaLigrants the keyboard focus to the first DOM element represented by this dommali object - provided that this is an HTML element and is allowed to be focused. Otherwise, focus does nothing
blur ():DOMMaLiremoves the keyboard focus from the first DOM element represented by this dommali object - provided that this is an HTML element and is currently focused. Otherwise, blur does nothing
hasFocus ():booleanreturns true, if the first DOM element represented by this dommali object currently owns the keyboard focus - or false otherwise
focusedElement ():DOMMaLireturns a (possible empty) dommali object representing the DOM element which currently owns the keyboard focus

CSS Transitions

transition (Settings:PlainObject, Options?:PlainObject):DOMMaLidefines a CSS transition (as specified by the optional Options) for all CSS properties given by the keys of Settings and all HTML elements represented by this dommali object and starts this transition by setting every CSS property to the value given in Settings. Options may customize the transition with a duration (in ms), an initial delay (in ms) and/or an easing function. Additionally, a cleanup option may be defined which, if true, restores the transition settings at the end of a transition to their values before invoking this method

Notes on dommali Event Handling

dommali contains additional support for simplified and streamlined event handling.

Nota bene: waitFor and repeatUntil were inspired by _hyperscript

Anchored Events

Both event handler management functions and waitFor or repeatUntil support "anchored events", i.e., event names followed by a CSS selector which restricts the events to be handled to those triggered on specific elements only. JQuery (and its look-alikes) support this declaration of "delegated event handlers" by means of an additional "selector" argument to functions like on, once or off - dommali additionally allows event name and event target selector to be specified within a single string argument just by separating them with an "at"-character @:

"event-name@selector"

For this to become possible, however, in dommali the syntax of event names has been narrowed a bit: while HTML actually allows event names in almost any format (including spaces and control characters), dommali defines the following syntax rules:

Event names

have to start with a roman letter (a-z), a dollar sign or an underscore, optionally followed by one or multiple decimal digits (0-9), roman letters (a-z), dollar signs or underscores
optionally followed by one or multiple groups of a single hyphen, dot or colon followed by one or multiple decimal digits (0-9), roman letters (a-z), dollar signs or underscores

The corresponding JavaScript RegExp is /^[a-z$_][a-z$_0-9]*([-.:][a-z$_0-9]+)*@.*$/

In an "anchored event" specification, this event name is followed by an "at" sign and one or multiple CSS selectors. The special "selector" this restricts incoming events to those triggered at the listening element itself. Typical examples look like:

pointerdown@.draggable or
pointermove@this

waitFor

waitFor (...anchoredEventsOrTimeout:(string|number)[]) returns a promise which resolves as soon as one of the given anchoredEvents has been received or the number of milliseconds given by a Timeout have passed.

waitFor has to be invoked as a method on a dommali object as it dynamically registers and unregisters event handlers on its DOM elements.

In an asynchronous function, waitFor is a simple approach to wait for the arrival of an event (as shown in the following example):

const $ = dommali // make "dommali" calls look like "jQuery" ones
$(document.body).waitFor('mousedown','pointerdown',5000).then((Result) => {
  switch (true) {
    case typeof Result === 'number':  ... (handle timeout)
    case Result.type === 'mousedown': ... (handle 'mousedown')
    default:                          ... (handle 'pointerdown')
  }
})

repeatUntil

repeatUntil (...anchoredEventsOrTimeoutOrLoopBody:(string|number|Function)[]) returns a promise which resolves after one of the given anchoredEvents has been received or the number of milliseconds given by a Timeout have passed. Until then, the given (asynchronous) LoopBody function will be executed as often as possible. If LoopBody returns any other value but undefined, the loop is terminated and the promise resolves to the loop body's return value. After receiving an event, repeatUntil resolves to that event as soon as LoopBody has finished without any return value; in case of a timeout it resolves to the actual number of milliseconds that have passed since the initial invocation - but again, only after LoopBody has finished without any return value.

repeatUntil has to be invoked as a method on a dommali object as it dynamically registers and unregisters event handlers on its DOM elements.

In an asynchronous function, repeatUntil may be used to simplify the proper handling of multiple consecutively arriving events. For example, the following code snippet makes all DOM elements with CSS class draggable draggable within their parent:

const $ = dommali // make "dommali" calls look like "jQuery" ones
$(document.body).on('pointerdown@.draggable',async function (Event) { // invocation-specific "this"
  if (Event.button !== 0) { return }

  let $Draggable = $(Event.target)
  let $Container = $Draggable.parent()

  let OffsetX = Event.offsetX + $Container.positionOnPage().left
  let OffsetY = Event.offsetY + $Container.positionOnPage().top

  let PointerId = Event.pointerId
  this.subject(0).setPointerCapture(PointerId)
    let Result = await this.repeatUntil('pointerup', 5000, async () => { // closure "this"
      Event = await this.waitFor('pointermove','pointerup')
      if (Event.type === 'pointermove') {
        $Draggable.css({ left:(Event.pageX-OffsetX)+'px', top:(Event.pageY-OffsetY)+'px' })
      }
    })
  this.subject(0).releasePointerCapture(PointerId)
})

(please note the use of both function and "fat-arrow" literals because of the desired this handling)

Build Instructions

You may easily build this package yourself.

Just install NPM according to the instructions for your platform and follow these steps:

either clone this repository using git or download a ZIP archive with its contents to your disk and unpack it there
open a shell and navigate to the root directory of this repository
run npm install in order to install the complete build environment
execute npm run build to create a new build

You may also look into the author's build-configuration-study for a general description of his build environment.