Kollegorna's JavaScript utilities

A library of ES6 utilities.

• Usage
• Development
• Documentation
• Other resources

Usage

1. Install with $ yarn add @kollegorna/js-utils.

2. Import utils you need to your project, e.g.:

   import { addEventListener } from "js-utils/src/event";

3. Browse Documentation

In order to gain a wider browser support, install and import these polyfills in your project:

• Element.closest / Element.matches
• Nodelist.prototype.forEach
• Element.classList
• CustomEvent

Development

1. Install dependencies with $ yarn
2. Run $ yarn dev when developing. This will:
   • Run the linter for your own good
   • Start server for demos
3. Edit contents of src and make sure the corresponding examples on demo are updated/added

Documentation

animation.js

onCssAnimationEnd(elements, callback [, options = { continuous = false, oncePerElems = true, oncePerAnims = true }])

Fires a callback function when CSS animation ends.

Examples:

onCssAnimationEnd(btn, callbackFunction)
onCssAnimationEnd(btns, callbackFunction, {oncePerAnims = false})
onCssAnimationEnd('.btn', callbackFunction)

onCssTransitionEnd(elements, callback [, options = { continuous = false, oncePerElems = true, oncePerAnims = true }])

Fires a callback function when CSS transition ends

Examples:

onCssTransitionEnd(btn, callbackFunction)
onCssTransitionEnd(btns, callbackFunction, {oncePerElems = false})
onCssTransitionEnd('.btn', callbackFunction)

clearCssAnimationEnd(elements)

Cleans all CSS animation end event listeners

clearCssTransitionEnd(elements)

Cleans all CSS transition end event listeners

attribute.js

addClass(elements, classnames)

An extended implementation of Element.classList.add(): adds classname(s) to single or multiple elements

Examples:

addClass(btn, "btn--green");
addClass(".btn", "btn--disabled btn--grey");

removeClass(elements, classnames)

An extended implementation of Element.classList.remove(): removes classname(s) from single or multiple elements

Examples:

removeClass(btn, "btn--green");
removeClass(".btn", "btn--disabled btn--grey");

toggleClass(elements, classnames [, force = undefined])

An extended implementation of Element.classList.remove(): toggles classname(s) from single or multiple elements

Examples:

toggleClass(btn, "btn--green", true);
toggleClass(".btn", "btn--disabled btn--grey");

cookie.js

getCookieValue(name)

Finds cookie by name and returns its value.

Examples:

getCookieValue("_ga");

event.js

addEventListener(elements, eventNames, callback [, options/useCapture = false])

Attaches the event handler. More about options/useCapture.

Examples:

addEventListener(btns, "click", doIt);
addEventListener([btn1, btn2], "click", doIt);
addEventListener(".btn", "click", doIt);
addEventListener(btn, "click focus", doIt);
addEventListener(btn, "click", doIt, { passive: true });

delegateEventListener(selector, eventNames, callback)

Delegates the event handler (an equivalent to jQuery's .live()).

Examples:

delegateEventListener(".btn", "click", doIt);
delegateEventListener(".btn", "click focus", doIt);

In order to remove event handler, use document as a target element, e.g.:

delegateEventListener(".btn", "click", doIt); // delegate
removeEventListener(document, "click", doIt); // remove
// removing without using the callback function:
delegateEventListener(".btn", "click.btnDelegate", doIt); // delegate
removeEventListener(document, "click.btnDelegate"); // remove

removeEventListener(elements [, eventName = false, callback = false, options/useCapture = false])

Removes the event handler. More about options/useCapture.

Examples:

removeEventListener(btn); // removes all event hanlders
removeEventListener(btn, "click"); // removes 'click' event handlers
removeEventListener(".btn", "click"); // removes 'click' event handlers
removeEventListener(btn, "click.thisIsNamespace"); // removes 'click.thisIsNamespace' event hanlders handlers
removeEventListener(btn, false, doIt); // removes all event handlers that are equal to 'doIt()'
removeEventListener(btn, "click", doIt); // removes 'click' event handlers that are equal to 'doIt()'
removeEventListener(btn, false, false, { passive: false }); // removes all event handlers that were attached together with the exact provided options

triggerEvent(elements, eventNames [, data = null])

Triggers the event(s). data — data to pass to the event handler ((e) => {e.detail}). Doesn't work with click|focus|blur events.

Examples:

triggerEvent(btn, "click"); // triggers 'click' event
triggerEvent(btn, "click.thisIsNamespace"); // triggers 'click.thisIsNamespace' event
triggerEvent(btn, ".thisIsNamespace"); // triggers all events with 'thisIsNamespace' namespace
triggerEvent(btn, "customEvent"); // triggers custom event
triggerEvent(btn, "customEvent anotherCustomEvent"); // triggers custom event
triggerEvent(btn, "customEvent", "someData"); // triggers custom event and passed data
triggerEvent(btn, "customEvent", { some: "data" }); // triggers custom event and passed data

function.js

debounce(delay, fn)

Debounces execution of a function.

Example:

window.addEventListener(
  "resize",
  debounce(500, () => {
    // do something expensive here
  })
);

throttle(delay, fn)

Throttles execution of a function.

Example:

window.addEventListener(
  "scroll",
  throttle(500, () => {
    // do something expensive here
  })
);

load-script.js

loadScript(src, cache = true)

Loads script file.

Returns: Promise.

Example:

loadScript("jquery.min.js", false)
  .then(() => {
    alert(typeof $);
  })
  .catch(error => {
    alert(`Error: ${error}. Try again.`);
  });

position.js

getOffset(elements)

Returns top/left offsets of an element

Returns: Object.

Example:

getOffset(container);
getOffset(".container");

promise.js

serialPromises(...fns)

Resolves promises sequentially.

Example:

serialPromises(
  () => loadScript("jquery.min.js"),
  () => loadScript("jquery-ui.min.js")
)
  .then(() => {
    $("ul").sortable();
  })
  .catch(error => {
    // error
  });

selector.js

getElements(elements [, source = document])

Accepts String, Element, NodeList, Array and returns Array of elements.

hasClosest(element, matches)

Based on how Element.closest() works. Returns true if element has the closest ancestor (or itself) that matches the matches (element|selector).

getParents(element [, selector = '', until = null])

Returns an Array of parents of element that matches the given selector up until the until matching element|selector.

smart-outline.js

Smart Outline hides the outline when interacting with a mouse and brings it back when interacting with a keyboard.

initSmartOutline([selectors])

Inits Smart Outline. selectors is an array of CSS selectors whose elements to affect. Default value:

```js
[
  'input:focus',
  'button:focus',
  'textarea:focus',
  'select:focus',
]
```

showSmartOutline()

Temporarily reveals outline.

haltSmartOutline()

Halts Smart Outline.

Other resources

For more functionality, consider using these vanilla JavaScript libraries:

Utilities

• https://github.com/lodash/lodash (utility library)
• https://allyjs.io (library simplifying certain accessibility features, functions and behaviors) — https://www.npmjs.com/package/common-tags (commonly used template literal tag functions)
• https://github.com/mynamesleon/aria-tablist (WCAG compliant tablists, also great for accordions)

Accessibility

• https://github.com/davidtheclark/focus-trap (trap focus within a DOM node)
• https://github.com/edenspiekermann/a11y-toggle (accessible content toggles)

Performance

• https://github.com/GoogleChromeLabs/quicklink (faster subsequent page-loads by prefetching in-viewport links during idle time)

DOM manipulation

• https://github.com/Sjeiti/TinySort (a small script that sorts HTML elements)
• https://github.com/RubaXa/Sortable (a library for reorderable drag-and-drop lists)

Modals

• https://github.com/edenspiekermann/a11y-dialog (a very lightweight and flexible accessible modal dialog)
• https://github.com/Ghosh/micromodal (tiny javascript library for creating accessible modal dialogs)

Tooltips

• https://github.com/atomiks/tippyjs (highly customizable vanilla JS tooltip/popover library)
• https://github.com/FezVrasta/popper.js (a kickass library to manage your poppers)

Validation

• https://github.com/chriso/validator.js (string validators and sanitizers)

Forms and inputs

• https://scottaohara.github.io/a11y_styled_form_controls (various styled accessible form controls)
• https://github.com/jshjohnson/Choices (vanilla JS customisable select box/text input plugin)

Gesture

• https://github.com/hammerjs/hammer.js (multi-touch gestures)

Calendar

• https://github.com/dbushell/Pikaday (lightweight, modular CSS datepicker)
• https://github.com/flatpickr/flatpickr (lightweight, powerful javascript datetimepicker with no dependencies)

Scroll

• https://basicscroll.electerious.com (parallax scrolling with CSS variables)
• https://github.com/dbrekalo/whenInViewport (handle elements as they enter viewport)
• https://github.com/KoryNunn/scroll-into-view (scrolls an element into view if possible)
• https://github.com/buzinas/simple-scrollbar (custom scrollbar cross-browser)

Charts

• https://frappe.github.io/charts (simple, responsive, modern charts library)

Browsing experience

• https://github.com/turbolinks/turbolinks (browse the site without "hard refresh")
• https://github.com/luruke/barba.js (fluid and smooth transition between website's pages)

Menus

• https://github.com/osvaldasvalutis/accessiblenav.js (accessible multi-level dropdown menus)

CSS

• https://polished.js.org (a lightweight toolset for writing CSS in JS)

Video

• https://www.npmjs.com/package/fitvids (responsive videos)

Polyfils

• https://www.npmjs.com/package/element-closest (polyfills for Element.closest and Element.matches)
• https://www.npmjs.com/package/nodelist-foreach-polyfill (polyfill for Nodelist.prototype.forEach
• https://www.npmjs.com/package/classlist-polyfill (polyfill for Element.classList)
• https://www.npmjs.com/package/array.findindex (lightweight Array.prototype.findIndex polyfill)
• https://github.com/lazd/scopedQuerySelectorShim (shims that enable the use of :scope)
• https://github.com/github/fetch (a window.fetch JavaScript polyfill)
• https://www.npmjs.com/package/custom-event-polyfill (a polyfill for CustomEvents on IE9+)
• https://www.npmjs.com/package/new-event-polyfill (new Event() polyfill)
• https://github.com/jonathantneal/svg4everybody (adds SVG External Content support to all browsers)
• https://www.npmjs.com/package/smoothscroll-polyfill (Smooth Scroll behavior polyfill)
• https://www.npmjs.com/package/element-dataset (polyfills the HTMLElement.dataset property)
• https://githubengineering.com/removing-jquery-from-github-frontend/#polyfills (a nice list of polyfills)