@webnesting/sanddom

Lightweight DOM utility library. 60+ functions, zero dependencies, tree-shakeable.

Installation

npm install @webnesting/sanddom

Features

• Zero dependencies - No external packages required
• Tree-shakeable - Import only what you need
• TypeScript first - Full type definitions included
• jQuery-like API - Familiar patterns for easy migration
• Cross-frame safe - Works with elements from iframes

Usage

import { qs, qsa, on, addClass, fadeIn } from '@webnesting/sanddom';

// Query elements
const button = qs(document, '.submit-btn');
const items = qsa(document, '.list-item');

// Event handling with auto-cleanup
const dispose = on(button, 'click', (e) => {
  console.log('Clicked!');
});
// Later: dispose() to remove listener

// Class manipulation
addClass(button, 'active', 'primary');

// Animations
fadeIn(button, 400, () => {
  console.log('Fade complete');
});

API Categories

Query & Creation

• qs(root, selector) - Query single element
• qsa(root, selector) - Query all elements
• create(tagName, options) - Create element with classes, attrs, text

Events

• on(target, type, handler) - Add event listener (returns disposer)
• one(target, type, handler) - One-time event listener
• off(target, type, handler) - Remove event listener
• delegate(root, selector, type, handler) - Delegated events
• trigger(el, type, detail) - Dispatch custom event
• onNs(target, 'event.namespace', handler) - Namespaced events
• offNs(target, '.namespace') - Remove by namespace

Traversal

• find(el, selector) / findOne(el, selector)
• closest(el, selector)
• parent(el) / children(el, selector)
• next(el) / prev(el) / siblings(el)
• nextAll(el) / prevAll(el) / parents(el)

Class Manipulation

• addClass(el, ...classes)
• removeClass(el, ...classes)
• hasClass(el, className)
• toggleClass(el, className, force?)

Content

• html(el) / html(el, value)
• text(el) / text(el, value)
• append(parent, ...nodes)
• prepend(parent, ...nodes)
• after(el, ...nodes) / before(el, ...nodes)
• remove(el) / empty(el)
• clone(el, deep?, withData?)

Attributes & Data

• attr(el, name) / attr(el, name, value)
• prop(el, name) / prop(el, name, value)
• setData(el, key, value) / getData(el, key)
• dataAttr(el, key) / dataAttr(el, key, value)

Visibility

• show(el) / hide(el)
• isVisible(el) / isHidden(el)
• toggleVisible(el, condition)

Dimensions & Position

• width(el) / height(el)
• outerWidth(el, includeMargin?) / outerHeight(el, includeMargin?)
• offset(el) / position(el)
• scrollTop(el) / scrollLeft(el)

CSS

• css(el, prop) - Get computed style
• css(el, prop, value) - Set single property
• css(el, { prop: value }) - Set multiple properties

Animations

• animate(el, props, duration?, easing?, complete?)
• fadeIn(el, duration?, complete?)
• fadeOut(el, duration?, complete?)
• slideDown(el, duration?, complete?)
• slideUp(el, duration?, complete?)
• stop(el, jumpToEnd?)
• Promise versions: animateAsync, fadeInAsync, fadeOutAsync, slideDownAsync, slideUpAsync

Form Helpers

• val(el) / val(el, value)
• formVal(el) - Full jQuery .val() parity (checkboxes, radios, multi-select)
• isTag(el, tagName) / isOneOfTags(el, tagNames)
• getInputType(el)
• setSelectValues(el, values) / getSelectValues(el)

Utilities

• wrap(el, wrapper) / unwrap(el)
• first(els) / last(els)
• filter(els, selector) / some(els, selector)
• each(els, fn) / jqEach(els, fn) / jqMap(els, fn)
• debounce(fn, wait) / throttle(fn, wait)
• deepMerge(...objects)
• ready(callback) - DOM ready handler

Debug Logging

Sanddom includes a configurable debug logger for integration with external systems:

import { setDebugLogger } from '@webnesting/sanddom';

// Enable console logging
setDebugLogger((key, data) => console.debug(`[sanddom] ${key}`, data));

// Or integrate with your debug system
setDebugLogger(myDebugLogger);

License

MIT