Minimal DOM Utility Toolbelt

Common errors

• TypeError: Cannot read properties of undefined (reading 'on')

  cause Attempting to call `on(element, 'event', handler)` directly instead of `event.on(...)`.
  fix Correct your event binding to `import { event } from 'min-dom'; event.on(element, 'event', handler);`

• Uncaught SyntaxError: The requested module 'min-dom' does not provide an export named 'default'

  cause Attempting to import `min-dom` with a default import statement (`import MinDom from 'min-dom'`).
  fix Use named imports for all utilities: `import { query, domify } from 'min-dom';`

• Element.closest: The selector is not a valid selector.

  cause Passing an invalid or empty string as the selector argument to `closest` or `query`.
  fix Ensure the selector string is a valid CSS selector and not empty. For example, `closest(element, '.my-class')` is correct, but `closest(element, '')` will fail.

Warnings

• breaking min-dom v5.0.0 updated its internal dependency to `domify@2`, which may introduce breaking changes if you relied on specific internal behaviors or undocumented APIs of `domify` directly. Always review the `domify` changelog when upgrading `min-dom` across major versions.
  Fix: Review the changelog for `domify@2` and `min-dom@5.0.0` to understand potential impacts. Test your application thoroughly after upgrading. If you had custom shims or overrides for `domify`, they might need adjustments.
• gotcha The `event` utility bundles methods `on`, `off`, and `bind`. When listening for events, you must pass the `event` object itself to access these methods, e.g., `event.on(element, 'click', handler)`. Do not destructure `on` directly from `min-dom` as a top-level export.
  Fix: Ensure you are calling `event.on`, `event.off`, or `event.bind` rather than attempting to call `on` or `off` directly if you've destructured `event` or are using an incorrect import pattern.
• gotcha When using `query` or `closest`, providing an invalid selector string (e.g., an empty string or malformed selector) can lead to unexpected behavior or errors, as these methods often rely on native browser APIs like `querySelector` or `closest`.
  Fix: Always validate selector strings before passing them to `query` or `closest`. Ensure they are non-empty and syntactically correct CSS selectors.
• gotcha The `domify` function takes an HTML string. If this string contains untrusted user input, it can lead to Cross-Site Scripting (XSS) vulnerabilities, as the HTML will be parsed and potentially inserted into the DOM.
  Fix: Sanitize any user-provided HTML strings before passing them to `domify`. Consider using a dedicated HTML sanitization library or ensuring that only trusted sources provide the HTML content.

Install

• npm install min-dom npm
• yarn add min-dom yarn
• pnpm add min-dom pnpm

Imports

• query
  wrong:

  const query = require('min-dom').query;

  correct:

  import { query } from 'min-dom';

  min-dom is primarily designed for ESM consumption, though CJS is supported.
• domify
  wrong:

  import domify from 'min-dom/lib/domify';

  correct:

  import { domify } from 'min-dom';

  All core utilities are exported as named exports from the main package entry point.
• event
  wrong:

  import { on } from 'min-dom.event';

  correct:

  import { event } from 'min-dom';

  The `event` object bundles `on`, `off`, and `bind` methods for event handling.
• closest
  wrong:

  import { findClosest } from 'min-dom';

  correct:

  import { closest } from 'min-dom';

  Directly imports the `closest` utility, which leverages native `Element.closest`.

Quickstart

This quickstart demonstrates creating elements with `domify`, querying the DOM using `query`, manipulating CSS classes with `classes`, and handling events with `event.on`/`event.off`.

import { domify, query, classes, event } from 'min-dom';

// 1. Create a DOM element from an HTML string
const myElement = domify('<div class="container"><p id="greeting">Hello, <span class="name">World</span>!</p><button>Click me</button></div>');

// Append it to the body for demonstration
document.body.appendChild(myElement);

// 2. Query for elements within the created element
const greetingParagraph = query('#greeting', myElement);
const nameSpan = query('.name', greetingParagraph);
console.log('Greeting paragraph text:', greetingParagraph.textContent);

// 3. Manipulate classes
classes(myElement).add('active');
classes(myElement).remove('container');
console.log('myElement classes:', myElement.className);

// 4. Attach an event listener
const button = query('button', myElement);
const handler = (e) => {
  console.log('Button clicked!', e.target.tagName);
  classes(button).toggle('clicked');
  event.off(button, 'click', handler); // Remove after first click
};
event.on(button, 'click', handler);

// Clean up after a few seconds
setTimeout(() => {
  if (myElement.parentNode) {
    myElement.parentNode.removeChild(myElement);
    console.log('Element removed from DOM.');
  }
}, 3000);