Skip to content

Latest commit

 

History

History
438 lines (291 loc) · 13 KB

README.md

File metadata and controls

438 lines (291 loc) · 13 KB
Raw

Odd Camp's JavaScript utilities

A library of ES6 utilities.

Usage

  1. Install with $ yarn add @oddcamp/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:

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");

containsAnyClass(element, classnames)

Check if an element contains at least one classname

Examples:

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

containsAllClasses(element, classnames)

Check if an element contains all classnames

Examples:

containsAllClasses(btn, "btn--green btn--disabled btn--grey");
containsAllClasses(".btn", "btn--green 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}). Data passing doesn't yet 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

Accessibility

Performance

DOM manipulation

Modals

Tooltips

Validation

Forms and inputs

Gesture

Calendar

Scroll

Charts

Browsing experience

Menus

CSS

Video

Polyfils