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.