blue-js

blue-js is a super lightweight commonjs javascript dom & events library

This library is developed and maintained internally at bluegrassdigital

Installation

npm install blue-js

Upgrading from V2

The top level module exports dom , events and ps are gone, all methods are exported directly from the root module, muvh like lodash.

The pubsub implementation ps has been removed as it was somewhat outside the scope of this library - please use something like https://github.com/developit/mitt instead.

API

blue

A collection of dom utility functions

• blue
  • .addClass(el, cls)
  • .each(els, fn)
  • .filter(els, fn) ⇒ Array
  • .getWindowDimensions([w], [d]) ⇒ windowDimensions
  • .hasClass(el, cls)
  • .isHidden(el) ⇒ Boolean
  • .isVisible(el) ⇒ Boolean
  • .onReady(fn)
  • .removeClass(el, cls)
  • .toggleClass(el, cls)
  • .wrap(el, argument1, [argument2])
  • .listen(el, names, fn, capture) ⇒ Object
  • .listenCollection(els, names, fn, capture)
  • .removeListeners(els, names)
  • .trigger(el, name, [data], [eventProps])
  • static
    • .windowDimensions : Object

blue.addClass(el, cls)

Add a class to an element

Param	Type	Description
el	HTMLElement	The dom node
cls	String	The class to add

blue.each(els, fn)

Iterate over a dom NodeList

Param	Type	Description
els	NodeList	The NodeList (created using getElementsByTagName or getElementsByClassName or querySelectorAll) to loop over
fn	function	The function to run against each element. Arguments passed are the same as Array.forEach

blue.filter(els, fn) ⇒ Array

Filters a dom NodeList, returning an array of only those elements which match the predicate function

Returns: Array - A filtered array of dom elements

Param	Type	Description
els	NodeList	The NodeList (created using getElementsByTagName or getElementsByClassName or querySelectorAll) to filter
fn	function	The predicate function to test each Element against

Example
Filter only foo links with class 'bar':

import { filter } from 'blue-js'

const fooLinks = document.querySelectorAll('a.foo')
const filteredLinks = filter(fooLinks, el => dom.hasClass(el, 'bar'))

Filter only visible filteredLinks:

import { filter } from 'blue-js'

const fooLinks = document.querySelectorAll('a.foo')
const newFilteredLinks = filter(filteredLinks, dom.isVisible)

blue.getWindowDimensions([w], [d]) ⇒ windowDimensions

Cross browser funtion for getting the dimensions of the window

Returns: windowDimensions - The window dimensions

Param	Type	Default	Description
[w]	object	window	The window element
[d]	object	document	The document element

blue.hasClass(el, cls)

Check if an element has a class

Param	Type	Description
el	HTMLElement	The dom node
cls	String	The classname to check

blue.isHidden(el) ⇒ Boolean

Check whether an element is hidden

Returns: Boolean - True if el is visibly hidden, otherwise false

Param	Type	Description
el	HTMLElement	The dom node

blue.isVisible(el) ⇒ Boolean

Check whether an element is visible

Returns: Boolean - True if el is visible, otherwise false

Param	Type	Description
el	HTMLElement	The dom node

blue.onReady(fn)

A callback that fires when the document is ready - roughly equaivalent to jQuery document ready

Param	Type	Description
fn	function	The callback to fire

blue.removeClass(el, cls)

Remove a class from an element

Param	Type	Description
el	HTMLElement	The dom node
cls	String	The class to remove

blue.toggleClass(el, cls)

Toggle a class on an element

Param	Type	Description
el	HTMLElement	The dom node
cls	String	The class to toggle

blue.wrap(el, argument1, [argument2])

Wrap an html element with another element or with a wrap function

Param	Type	Description
el	HTMLElement	The dom node
argument1	function | HTMLElement | string	A callback function which is passed el.outerHTML as its only function parameter OR a dom node to wrap around the element OO the first of two string arguments to go before and after the element
[argument2]	string	The string to use for after the dom element (both argument1 and argument2 should be strings)

Example
Using a wrapper function:

import { wrap } from 'blue-js'

const foo = document.querySelector('#foo')
wrap(foo, html => `<div class="wrapper">${html}</div>`)

Example
Using an html element:

import { wrap } from 'blue-js'

const foo = document.querySelector('#foo')
const wrapper = document.createElement('div')
wrap(foo, wrapper)

Example
Using two strings:

import { wrap } from 'blue-js'

const foo = document.querySelector('#foo')
wrap(foo, '<div class="wrapper">', '</div>')

blue.listen(el, names, fn, capture) ⇒ Object

Listen for one or more events (custom or standard)

Returns: Object - An object with a remove method to remove the listener later

Param	Type	Description
el	HTMLElement	The dom element
names	String	The event or events (space-separated) to listen for
fn	function	The callback to fire when the event occurs
capture	Boolean	Whether to capture the event or not

Example
Add a listener:

import { listen } from 'blue-js'

const fooLink = document.querySelector('a.foo')

listen(fooLink, 'click', (event) => {
  event.preventDefault()
  const { target } = event
  target.classlist.add('.is-clicked')
})

Example
Remove listener later:

import { listen } from 'blue-js'

const fooLink = document.querySelector('a.foo')

const listener = listen(fooLink, 'click', (event) => {
  event.preventDefault()
  const { target } = event
  target.classlist.add('.is-clicked')
})
//Some time later
listener.remove()

Example
Remove listener immediately:

import { listen } from 'blue-js'

const fooLink = document.querySelector('a.foo')

const listener = listen(fooLink, 'click', (event) => {
  event.preventDefault()
  const { target } = event
  target.classlist.add('.is-clicked')
  listener.remove()
})

blue.listenCollection(els, names, fn, capture)

Same as events.listen, excpet for NodeList rather than a single Element

Param	Type	Description
els	NodeList	The dom collection
names	String	The event or events (space-separated) to listen for
fn	function	The callback to fire when the event occurs
capture	Boolean	Whether to capture the event or not

blue.removeListeners(els, names)

Remove one or more events from one or more targets

Param	Type	Description
els	HTMLElement	The dom element or any iterable containing dom elements (eg. NodeList)
names	String	The event or events (space separated) to remove the listeners for

Example

import { removeListeners } from 'blue-js'

const fooLinks = document.querySelectorAll('a.foo')
removeListeners(fooLinks, 'click mouseenter')

blue.trigger(el, name, [data], [eventProps])

Trigger any event on a dom element, optionally pass data

Param	Type	Description
el	HTMLElement	The dom node
name	String	The event to trigger
[data]	Object	The data to pass along with the event
[eventProps]	Object	Other event properties to override the defaults, which are { bubbles: true, cancelable: true }

Example

import { listen, trigger } from 'blue-js'

const fooLink = document.querySelector('a.foo')
trigger(fooLink, 'Link:Event', { foo: 'bar' })

// Listen for custom event and use the custom data passed to trigger
listen(fooLink, 'Link:Event', event => {
  console.log(event.detail.foo) // -> 'bar'
})

blue.windowDimensions : Object

Kind: static typedef of blue
Properties

Name	Type	Description
width	number	Window width
height	number	Window height

Contributing to blue-js

Standard JS applies

camelCase for function and variable names

Github Flow - branch, submit pull requests

Getting set up

• Pull the repo
• run npm install
• run npm start to run all unit tests, lint the codebase, and build the API docs

---

Contribute

First off, thanks for taking the time to contribute! Now, take a moment to be sure your contributions make sense to everyone else.

Reporting Issues

Found a problem? Want a new feature? First of all see if your issue or idea has already been reported. If it hasn't, just open a new clear and descriptive issue.

Submitting pull requests

Pull requests are the greatest contributions, so be sure they are focused in scope, and do avoid unrelated commits.

• Fork it!
• Clone your fork: git clone https://github.com/<your-username>/blue-js
• Navigate to the newly cloned directory: cd blue-js
• Create a new branch for the new feature: git checkout -b my-new-feature
• Install the tools necessary for development: npm install
• Make your changes.
• npm test to make sure your change doesn't break anything.
• Commit your changes: git commit -am 'Add some feature'
• Push to the branch: git push origin my-new-feature
• Submit a pull request with full remarks documenting your changes.