npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@joinbox/ui-tools

v1.4.0

Published

Provides repeatedly used tools for frontend and UI JS development

Downloads

192

Readme

Tools

Provides some simple and regularily used frontend helpers for JavaScript.

readAttribute

Description

Reads, transforms and validates an attribute from an HTML element.

Usage

import { readAttribute } from '@joinbox/ui-tools';

const element = document.querySelector('div.className');
readAttribute(element, 'attributeName', { transform: (value) => parseInt(value, 10) });

Arguments

Syntax: readAttribute(element, attribute, additionalArguments);

  • element (HTMLElement, required): Element to read attribute from
  • attribute (string, required): Name of the attribute to read
  • additionalArguments (object, optional): Object with properties
    • transform (function, optional), takes value as its only parameter and should return the transformed value. Defaults to (value) => value. In order to check if a boolean attribute is present, use (value) => value !== null.
    • validate (function, optional), takes value as its only parameter (that is the attribute's value after the transform function has been applied) and should return true if the value is valid, else false. Defaults to (value) => value.
    • expectation (string, optional): expected value for the (transformed) value; will be printed in the error message if validate returns false.

Returns

*: Transformed and validated value

Errors

Error if validate function returns false

debounce

Description

Creates a debounced function. Primarily needed for performant scroll (and window resize) operations.

Usage

import { debounce } from '@joinbox/ui-tools';

const callbackFunction = () => { console.log('update'); };
const debouncedFunction = debounce(callbackFunction, 200);
// Will only print a console.log *after* the window has *not* been resized for 200ms
window.addEventListener('resize', debouncedFunction);

Arguments

Syntax: debounce(callback, timeout)

  • callback (function, required): The function that will be executed after the debounce function has not been called for timeout ms.
  • timeout (number, required, in ms). The inactivity timeout in ms after which the `callback`` function will be executed.

Returns

undefined

once

Description

Only executes a given function once for a given element; the execution state (executed or not) is stored on an HTML element and only depends on the provided name, not the function. Needed especially to implement Drupal behaviors.

Usage

import { once } from '@joinbox/ui-tools';

const executeOnlyOnce = () => { console.log('executing'); };
const element = document.querySelector('.executing-element');
once(element, 'example-executer', executeOnlyOnce);

// Will *not* execute executeOnlyOnce because it has been executed for this element before
once(element, 'example-executer', executeOnlyOnce);

// Will *not* execute because the name has been used before
once(element, 'example-executer', () => { console.log('nope') });

// Will execute as executeOnlyOnce has not been executed for this element before
once(document.querySelector('body'), 'example-executer', executeOnlyOnce);

Arguments

Syntax: once(element, name, function)

  • element (HTMLElement, required): The HTML element for which the function should be executed once
  • name (string, required): Name under which the execution state function (executed or not) will be stored on the provided element
  • function (function, required): Function that shall only be executed once

Returns

undefined

measureElement

Description

Gets dimensions of an element (by calling getBoundingClientRect()) on load, window resize and (optionally) intersection. Returns them as an object that updates its values whenever any of the events described happens.

Usage

import { measureElement } from '@joinbox/ui-tools';

const element = document.querySelector('div.className');
const dimensions = measureElement({ element, updateOnIntersection: true });

Arguments

Syntax: measureElement({ element, updateOnIntersection });

  • element (HTMLElement, required): Element to measure
  • updateOnIntersection (boolean, optional): If true, dimensions will update whenever the element becomes visible. Defaults to false.

Returns

object: Object with same properties as DOMRect with values that reflect the element's current dimensions.

Errors

No specific errors