DOM Align

Common errors

• TypeError: domAlign is not a function

  cause This error typically occurs when attempting to `require` or import `dom-align` in a CommonJS module context, but the default export is not handled correctly, or the module system is misconfigured for ESM.
  fix If using CommonJS, try `const domAlign = require('dom-align').default;` or ensure your build system (e.g., Webpack, Rollup) correctly transpiles ESM imports. For ESM, ensure you use `import domAlign from 'dom-align';`.

• Cannot read properties of null (reading 'style') or similar 'Cannot read property X of undefined'

  cause This error indicates that either the `source` or `target` HTMLElement passed to `domAlign` is `null` or `undefined`, meaning the element could not be found or was not rendered yet.
  fix Ensure that both `source` and `target` elements exist in the DOM and are valid `HTMLElement` instances before calling `domAlign`. Use `document.getElementById()`, `document.querySelector()`, or a React/Vue ref to reliably get the elements after they are mounted.

Warnings

• gotcha The `sourceNode` must be absolutely positioned and initially placed off-screen (e.g., `left: -9999px; top: -9999px;`) for `dom-align` to calculate its dimensions correctly before applying the alignment, especially when dealing with dynamic content or initial rendering.
  Fix: Ensure `sourceNode.style.position = 'absolute';` and `sourceNode.style.left = '-9999px'; sourceNode.style.top = '-9999px';` are set before calling `domAlign`.
• gotcha When using percentage values in `offset` or `targetOffset`, they are calculated relative to the *sourceNode's* or *targetNode's* dimensions, respectively. Incorrect assumptions about their reference frame can lead to unexpected positioning.
  Fix: Thoroughly test alignment configurations with percentage offsets and inspect the calculated `left` and `top` styles to ensure they match expectations. Refer to the API documentation for precise percentage calculation rules.
• gotcha The `overflow` property's `adjustX` and `adjustY` flags determine if `dom-align` should automatically reposition the source node if it extends beyond the visible viewport. If these are not set to `true`, the source node might be clipped or hidden without adjustment.
  Fix: To enable automatic viewport adjustment, set `overflow: { adjustX: true, adjustY: true }` in your `alignConfig`. Consider `alwaysByViewport: true` if adjustment should always prioritize the viewport.

Install

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

Imports

• domAlign
  wrong:

  const domAlign = require('dom-align');

  correct:

  import domAlign from 'dom-align';

  dom-align is primarily consumed as an ESM default import. Direct CommonJS `require` might lead to `domAlign is not a function` errors in certain module environments.
• AlignConfig
  wrong:

  import { AlignConfig } from 'dom-align';

  correct:

  import type { AlignConfig } from 'dom-align';

  When importing types in TypeScript, always use `import type` to avoid bundling unused runtime code, especially for interface-only declarations.
• AlignResult

  import type { AlignResult } from 'dom-align';

  The `domAlign` function returns an object with alignment results; its type is `AlignResult`. Import it for type-safe usage.

Quickstart

This quickstart demonstrates how to align a 'source' DOM element relative to a 'target' DOM element using `dom-align`. It sets up two basic divs, applies an alignment configuration that includes points, offsets, and overflow adjustments, and then performs the alignment, logging the result.

import domAlign from 'dom-align';

// Create a source and target node for alignment demonstration.
// In a real application, these would be existing DOM elements.
const sourceNode = document.createElement('div');
sourceNode.id = 'sourceNode';
sourceNode.style.cssText = 'position:absolute; left:-9999px; top:-9999px; width:100px; height:50px; background-color:blue; color:white; padding:5px;';
sourceNode.textContent = 'I am the source!';
document.body.appendChild(sourceNode);

const targetNode = document.createElement('div');
targetNode.id = 'targetNode';
targetNode.style.cssText = 'position:relative; margin-top:150px; margin-left:200px; width:200px; height:100px; border:2px solid red; display:inline-block; padding:10px;';
targetNode.textContent = 'I am the target!';
document.body.appendChild(targetNode);

// Define the alignment configuration.
const alignConfig = {
  points: ['tl', 'br'], // Align top-left of sourceNode with bottom-right of targetNode
  offset: [5, 10],       // Offset sourceNode by 5px in x, 10px in y after initial alignment
  targetOffset: ['-10%', '-5%'], // Offset targetNode by -10% of its width, -5% of its height
  overflow: { adjustX: true, adjustY: true }, // Auto-adjust position if sourceNode overflows viewport
};

// Perform the alignment. The function returns an AlignResult object.
const alignResult = domAlign(sourceNode, targetNode, alignConfig);

console.log('Alignment successful:', alignResult.align);
console.log('Adjustments made:', alignResult.overflow);

// To clean up or re-align, you might remove elements or call domAlign again with different configs.
// For demonstration, let's log the final position:
setTimeout(() => {
  console.log(`Source node final position: left=${sourceNode.style.left}, top=${sourceNode.style.top}`);
}, 0);