height-harmony 1.0.1 → 2.0.0

package/README.md

@@ -1,220 +1,270 @@
 # Height Harmony
 
-A lightweight, zero-dependency JavaScript utility for equalizing element heights.
+**The fastest, smartest equal-height JavaScript utility on the web.**
 
-## Live Demo
+Zero dependencies. ResizeObserver-powered. Automatically responsive. Drop it in and forget it.
+
+[![npm version](https://img.shields.io/badge/npm-v2.0.0-45c4b0?style=flat-square)](https://www.npmjs.com/package/height-harmony)
+[![License: MIT](https://img.shields.io/badge/License-MIT-dafdba?style=flat-square)](LICENSE)
+[![gzip size](https://img.shields.io/badge/gzip-%3C2KB-9aeba3?style=flat-square)](#)
 
 **[View the interactive demo →](https://byronjohnson.github.io/height-harmony/demo/)**
 
+---
+
+## What's New in v2.0
+
+| Feature | v1 | v2 |
+|---|---|---|
+| ResizeObserver (auto-reactive) | ❌ | ✅ |
+| MutationObserver (dynamic content) | ❌ | ✅ |
+| Options object | ❌ | ✅ |
+| `destroy()` / `refresh()` methods | ❌ | ✅ |
+| Breakpoint support | ❌ | ✅ |
+| `data-hh-group` HTML attribute | ❌ | ✅ |
+| ESM + UMD build | ❌ | ✅ |
+| Zero layout thrash | partial | ✅ |
+
+---
+
 ## Installation
 
-### NPM
+### npm / yarn / pnpm
+
 ```bash
 npm install height-harmony
 ```
 
-```javascript
-// ES6 Modules (recommended)
-import heightHarmony from 'height-harmony';
+### CDN (UMD — no bundler needed)
 
-// CommonJS
-const heightHarmony = require('height-harmony');
+```html
+<script src="https://unpkg.com/height-harmony@2/dist/height-harmony-min.js"></script>
+<script>
+  heightHarmony('.card');
+</script>
 ```
 
-### CDN
+### CDN (ES Module)
 
-#### ES Modules (Modern Browsers)
 ```html
 <script type="module">
-    import heightHarmony from 'https://unpkg.com/height-harmony@latest/height-harmony.js';
-    
-    // Use immediately
-    heightHarmony('.my-elements');
+  import heightHarmony from 'https://unpkg.com/height-harmony@2/dist/height-harmony.es.js';
+  heightHarmony('.card');
 </script>
 ```
 
-#### Traditional Script Tag
-```html
-<!-- Latest version -->
-<script src="https://unpkg.com/height-harmony@latest/height-harmony-min.js"></script>
+---
+
+## Quick Start
+
+```javascript
+import heightHarmony from 'height-harmony';
+
+// Basic — equalize all matching elements
+heightHarmony('.card');
 
-<!-- Specific version -->
-<script src="https://unpkg.com/height-harmony@1.0.0/height-harmony-min.js"></script>
+// With options
+heightHarmony('.card', { debounce: 100, breakpoint: 768 });
+
+// Store the instance
+const hh = heightHarmony('.card');
+hh.refresh();  // manual re-trigger
+hh.destroy();  // clean up all observers and remove inline styles
 ```
 
-### Direct Download
-```html
-<!-- ES Modules -->
-<script type="module" src="height-harmony.js"></script>
+---
+
+## API Reference
+
+### `heightHarmony(target, options?)`
+
+**Parameters**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `target` | `string \| NodeList \| HTMLElement[]` | CSS selector string or a collection of elements |
+| `options` | `HeightHarmonyOptions` | *(optional)* Configuration object |
+
+**Returns** `HeightHarmonyInstance`
+
+---
 
-<!-- Traditional script tag -->
-<script src="height-harmony-min.js"></script>
+### Options
+
+```typescript
+interface HeightHarmonyOptions {
+  /**
+   * Milliseconds to debounce ResizeObserver / MutationObserver callbacks.
+   * 0 = no debounce, only requestAnimationFrame (default).
+   * @default 0
+   */
+  debounce?: number;
+
+  /**
+   * Use `min-height` instead of `height`.
+   * Allows elements to grow taller than the maximum if new content is added.
+   * @default false
+   */
+  minHeight?: boolean;
+
+  /**
+   * Viewport width (px) below which harmonizing is disabled.
+   * Set to 768 to let mobile layouts stack naturally.
+   * @default 0 (always on)
+   */
+  breakpoint?: number;
+
+  /**
+   * Whether to auto-watch via ResizeObserver and MutationObserver.
+   * Set to false for fire-and-forget manual mode.
+   * @default true
+   */
+  watch?: boolean;
+
+  /**
+   * Apply a CSS `transition` on height changes for smooth animation.
+   * @default true
+   */
+  transitions?: boolean;
+}
 ```
 
-## Basic Usage
+---
+
+### Instance Methods
+
+#### `.refresh()` → `this`
+
+Manually triggers a height re-calculation. Useful after CSS transitions finish or after content changes you explicitly control.
 
 ```javascript
-// Apply equal heights to elements
-heightHarmony('.card');
-heightHarmony('.feature-box');
+const hh = heightHarmony('.card');
+// ... some time later, after a font loads or animation finishes
+hh.refresh();
 ```
 
-## Version Information
+#### `.destroy()` → `this`
+
+Disconnects all ResizeObserver and MutationObserver instances, removes all inline `height` / `min-height` styles set by this instance, and marks it as destroyed.
 
 ```javascript
-// Check the current version
-console.log(heightHarmony.version); // "1.0.0"
+const hh = heightHarmony('.card');
+// Clean up when a component unmounts (React, Vue, etc.)
+hh.destroy();
 ```
 
-## ES Module Usage
+---
+
+### `heightHarmony.autoInit(options?)`
+
+Scans the entire document for elements with `data-hh-group` attributes and harmonizes each group automatically.
 
-### Browser ES Modules
 ```html
-<!DOCTYPE html>
-<html>
-<head>
-    <script type="module">
-        import heightHarmony from './height-harmony.js';
-        
-        // Initialize when DOM is ready
-        document.addEventListener('DOMContentLoaded', function() {
-            heightHarmony('.card');
-        });
-        
-        // Handle responsive behavior
-        window.addEventListener('resize', function() {
-            heightHarmony('.card');
-        });
-    </script>
-</head>
-<body>
-    <div class="card">Content 1</div>
-    <div class="card">Content 2</div>
-    <div class="card">Content 3</div>
-</body>
-</html>
+<!-- HTML -->
+<div data-hh-group="cards">Card 1 — short content</div>
+<div data-hh-group="cards">Card 2 — a lot more content here...</div>
+<div data-hh-group="sidebar">Widget A</div>
+<div data-hh-group="sidebar">Widget B</div>
 ```
 
-### Node.js / Build Tools
 ```javascript
-// app.js
 import heightHarmony from 'height-harmony';
 
-// In your component
-function initCards() {
-    heightHarmony('.product-card');
-}
-
-// Export for use in other modules
-export { initCards };
+// One call handles all groups
+const instances = heightHarmony.autoInit({ debounce: 100 });
+// Returns an array of HeightHarmonyInstance, one per group
 ```
 
-### Module Bundlers (Webpack, Rollup, etc.)
+---
+
+### `heightHarmony.version`
+
 ```javascript
-// Works seamlessly with modern bundlers
+console.log(heightHarmony.version); // "2.0.0"
+```
+
+---
+
+## Framework Integration
+
+### React
+
+```jsx
+import { useEffect, useRef } from 'react';
 import heightHarmony from 'height-harmony';
 
-// Tree-shaking friendly
-export function createCardGrid() {
-    heightHarmony('.grid-item');
+function CardGrid({ cards }) {
+  useEffect(() => {
+    const hh = heightHarmony('.card', { debounce: 50 });
+    return () => hh.destroy();
+  }, [cards]); // re-run when cards array changes
+
+  return (
+    <div className="grid">
+      {cards.map(card => <div className="card" key={card.id}>{card.content}</div>)}
+    </div>
+  );
 }
 ```
 
-## Responsive Support
+### Vue 3
 
-### ES Modules
 ```javascript
+import { onMounted, onUnmounted, watch } from 'vue';
 import heightHarmony from 'height-harmony';
 
-document.addEventListener('DOMContentLoaded', function() {
-    // Initial harmonization
-    heightHarmony('.card');
-    
-    // Reapply on window resize
-    let resizeTimeout;
-    window.addEventListener('resize', function() {
-        clearTimeout(resizeTimeout);
-        resizeTimeout = setTimeout(function() {
-            heightHarmony('.card');
-        }, 150);
-    });
-    
-    // Handle orientation changes on mobile
-    window.addEventListener('orientationchange', function() {
-        setTimeout(function() {
-            heightHarmony('.card');
-        }, 300);
-    });
-});
+export function useHeightHarmony(selector, options = {}) {
+  let instance = null;
+  onMounted(() => { instance = heightHarmony(selector, options); });
+  onUnmounted(() => { instance?.destroy(); });
+  return { refresh: () => instance?.refresh() };
+}
 ```
 
-### Traditional Script Tag
+### Vanilla JS — DOMContentLoaded
+
 ```javascript
-// Initialize on page load
-document.addEventListener('DOMContentLoaded', function() {
-    heightHarmony('.card');
-});
+import heightHarmony from 'height-harmony';
 
-// Reapply on window resize
-let resizeTimeout;
-window.addEventListener('resize', function() {
-    clearTimeout(resizeTimeout);
-    resizeTimeout = setTimeout(function() {
-        heightHarmony('.card');
-    }, 150);
+document.addEventListener('DOMContentLoaded', () => {
+  heightHarmony('.card');          // ResizeObserver handles everything else
 });
 ```
 
-## Dynamic Content
+---
 
-### ES Modules
-```javascript
-import heightHarmony from 'height-harmony';
+## How It Works
 
-// After adding new content via AJAX/fetch
-function addNewCards(data) {
-    // Add new elements to DOM
-    const container = document.getElementById('card-container');
-    data.forEach(item => {
-        const card = document.createElement('div');
-        card.className = 'card';
-        card.textContent = item.content;
-        container.appendChild(card);
-    });
-    
-    // Harmonize heights after DOM update
-    setTimeout(function() {
-        heightHarmony('.card');
-    }, 10);
-}
-```
+1. **Reset** — Clears inline `height` / `min-height` on all matched elements in a single write pass.
+2. **Measure** — Reads `offsetHeight` for every element in one synchronous batch (no interleaved read/write thrashing).
+3. **Apply** — Sets all elements to the maximum measured height.
+4. **Watch** — `ResizeObserver` re-syncs automatically whenever any element's size changes. `MutationObserver` re-syncs when new elements are added to parent containers.
 
-### Traditional Approach
-```javascript
-// After adding new content
-setTimeout(function() {
-    heightHarmony('.product-card');
-}, 10);
-```
+---
 
-## Browser Compatibility
+## Performance
 
-### ES Modules
-- Chrome 61+
-- Firefox 60+
-- Safari 10.1+
-- Edge 16+
+Height Harmony v2 is carefully engineered to avoid common causes of layout thrashing:
 
-### Traditional Script Tag
-- All modern browsers
-- IE 9+
+- All height reads happen **before** any writes (batch read → batch write)
+- `ResizeObserver` is far more efficient than `window.resize` — it only fires for elements that actually changed
+- `requestAnimationFrame` ensures writes happen at the right point in the browser rendering pipeline
+- A built-in debounce option prevents excessive recalculations during rapid mutations
 
-## How It Works
+---
+
+## Browser Compatibility
+
+| Feature | Chrome | Firefox | Safari | Edge |
+|---|---|---|---|---|
+| ResizeObserver | 64+ | 69+ | 13.1+ | 79+ |
+| MutationObserver | 26+ | 14+ | 7+ | 12+ |
+| ES Modules | 61+ | 60+ | 10.1+ | 16+ |
+
+For very old browsers, Height Harmony automatically falls back to a debounced `window.resize` listener.
 
-1. Resets all element heights to measure natural dimensions
-2. Finds the tallest element in the group
-3. Sets all elements to match the tallest height
+---
 
 ## License
 
-MIT
+[MIT](LICENSE) © Byron Johnson

package/dist/height-harmony-min.js

@@ -1,22 +1,12 @@
-function heightHarmony(selector) {
-  const elements = document.querySelectorAll(selector);
-  if (elements.length === 0) return;
-  elements.forEach((element) => {
-    element.style.height = "0px";
-  });
-  requestAnimationFrame(() => {
-    let maxHeight = 0;
-    elements.forEach((element) => {
-      element.style.height = "";
-      const elementHeight = element.offsetHeight;
-      maxHeight = Math.max(maxHeight, elementHeight);
-    });
-    elements.forEach((element) => {
-      element.style.height = maxHeight + "px";
-    });
-  });
-}
-heightHarmony.version = "1.0.0";
-export {
-  heightHarmony as default
-};
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).heightHarmony={})}(this,function(e){"use strict";
+/**
+   * Height Harmony v2.0.0
+   * The fastest, smartest equal-height JavaScript utility on the web.
+   *
+   * Automatically synchronizes element heights using ResizeObserver and
+   * MutationObserver — no manual resize listeners needed.
+   *
+   * @author Byron Johnson
+   * @license MIT
+   * @see https://byronjohnson.github.io/height-harmony/demo/
+   */function t(e,t){let s=null;return function(...i){null!==s&&clearTimeout(s),t>0?s=setTimeout(()=>{s=null,requestAnimationFrame(()=>e.apply(this,i))},t):requestAnimationFrame(()=>e.apply(this,i))}}class s{constructor(e,s={}){this._target=e,this._opts=Object.assign({debounce:0,minHeight:!1,breakpoint:0,watch:!0,transitions:!0},s),this._destroyed=!1,this._resizeObserver=null,this._mutationObserver=null,this._cleanupFallback=null,this._debouncedSync=t(this._sync.bind(this),this._opts.debounce),this._sync(),this._opts.watch&&this._setupObservers()}refresh(){return this._destroyed||this._sync(),this}destroy(){if(this._destroyed)return this;this._destroyed=!0,this._resizeObserver&&(this._resizeObserver.disconnect(),this._resizeObserver=null),this._mutationObserver&&(this._mutationObserver.disconnect(),this._mutationObserver=null),this._cleanupFallback&&(this._cleanupFallback(),this._cleanupFallback=null);const e=this._opts.minHeight?"min-height":"height";return this._getElements().forEach(t=>{t.style.removeProperty(e),t.style.removeProperty("box-sizing"),this._opts.transitions&&t.style.removeProperty("transition")}),this}_getElements(){return"string"==typeof this._target?Array.from(document.querySelectorAll(this._target)):this._target instanceof NodeList||Array.isArray(this._target)?Array.from(this._target):this._target instanceof HTMLElement?[this._target]:[]}_sync(){if(this._destroyed)return;const e=this._getElements();if(0===e.length)return;if(this._opts.breakpoint>0&&window.innerWidth<this._opts.breakpoint){const t=this._opts.minHeight?"min-height":"height";return void e.forEach(e=>e.style.removeProperty(t))}const t=this._opts.minHeight?"min-height":"height";e.forEach(e=>{e.style.setProperty(t,"","important"),e.style.setProperty("box-sizing","border-box","important")});let s=0;e.forEach(e=>{const t=e.offsetHeight;t>s&&(s=t)}),0!==s&&e.forEach(e=>{this._opts.transitions&&e.style.setProperty("transition",`${t} 0.2s ease`,""),e.style.setProperty(t,`${s}px`,"important")})}_setupObservers(){if("undefined"!=typeof ResizeObserver)this._resizeObserver=new ResizeObserver(e=>{e.length>0&&this._debouncedSync()}),(()=>{this._getElements().forEach(e=>this._resizeObserver.observe(e))})();else{const e=t(this._sync.bind(this),Math.max(this._opts.debounce,150)),s=()=>setTimeout(()=>this._sync(),300);window.addEventListener("resize",e,{passive:!0}),window.addEventListener("orientationchange",s,{passive:!0}),this._cleanupFallback=()=>{window.removeEventListener("resize",e),window.removeEventListener("orientationchange",s)}}if("undefined"!=typeof MutationObserver){const e=this._getElements(),t=new Set(e.map(e=>e.parentElement).filter(Boolean));t.size>0&&(this._mutationObserver=new MutationObserver(e=>{e.some(e=>e.addedNodes.length>0||e.removedNodes.length>0)&&(this._debouncedSync(),this._resizeObserver&&this._getElements().forEach(e=>{try{this._resizeObserver.observe(e)}catch(t){}}))}),t.forEach(e=>{this._mutationObserver.observe(e,{childList:!0,subtree:!1})}))}}}function i(e,t){return new s(e,t)}i.version="2.0.0",i.autoInit=function(e={}){const t=document.querySelectorAll("[data-hh-group]");if(0===t.length)return[];const i=new Map;t.forEach(e=>{const t=e.getAttribute("data-hh-group");i.has(t)||i.set(t,[]),i.get(t).push(e)});const r=[];return i.forEach(t=>{r.push(new s(t,e))}),r},e.HeightHarmonyInstance=s,e.default=i,Object.defineProperties(e,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})});

package/dist/height-harmony.es.js

@@ -0,0 +1,209 @@
+/**
+ * Height Harmony v2.0.0
+ * The fastest, smartest equal-height JavaScript utility on the web.
+ *
+ * Automatically synchronizes element heights using ResizeObserver and
+ * MutationObserver — no manual resize listeners needed.
+ *
+ * @author Byron Johnson
+ * @license MIT
+ * @see https://byronjohnson.github.io/height-harmony/demo/
+ */
+const VERSION = "2.0.0";
+function debounce(fn, wait) {
+  let timer = null;
+  return function debounced(...args) {
+    if (timer !== null) clearTimeout(timer);
+    if (wait > 0) {
+      timer = setTimeout(() => {
+        timer = null;
+        requestAnimationFrame(() => fn.apply(this, args));
+      }, wait);
+    } else {
+      requestAnimationFrame(() => fn.apply(this, args));
+    }
+  };
+}
+class HeightHarmonyInstance {
+  /**
+   * @param {string|NodeList|HTMLElement[]} target  CSS selector or element list
+   * @param {HeightHarmonyOptions} options
+   */
+  constructor(target, options = {}) {
+    this._target = target;
+    this._opts = Object.assign(
+      { debounce: 0, minHeight: false, breakpoint: 0, watch: true, transitions: true },
+      options
+    );
+    this._destroyed = false;
+    this._resizeObserver = null;
+    this._mutationObserver = null;
+    this._cleanupFallback = null;
+    this._debouncedSync = debounce(this._sync.bind(this), this._opts.debounce);
+    this._sync();
+    if (this._opts.watch) {
+      this._setupObservers();
+    }
+  }
+  // ── Public API ──────────────────────────────────────────────────────────────
+  /**
+   * Manually triggers a height re-calculation.
+   * Useful after CSS transitions finish or after content changes you control.
+   * @returns {this}
+   */
+  refresh() {
+    if (this._destroyed) return this;
+    this._sync();
+    return this;
+  }
+  /**
+   * Tears down all observers, removes inline height/transition styles set by
+   * this instance, and marks the instance as destroyed.
+   * @returns {this}
+   */
+  destroy() {
+    if (this._destroyed) return this;
+    this._destroyed = true;
+    if (this._resizeObserver) {
+      this._resizeObserver.disconnect();
+      this._resizeObserver = null;
+    }
+    if (this._mutationObserver) {
+      this._mutationObserver.disconnect();
+      this._mutationObserver = null;
+    }
+    if (this._cleanupFallback) {
+      this._cleanupFallback();
+      this._cleanupFallback = null;
+    }
+    const prop = this._opts.minHeight ? "min-height" : "height";
+    this._getElements().forEach((el) => {
+      el.style.removeProperty(prop);
+      el.style.removeProperty("box-sizing");
+      if (this._opts.transitions) {
+        el.style.removeProperty("transition");
+      }
+    });
+    return this;
+  }
+  // ── Private ─────────────────────────────────────────────────────────────────
+  /**
+   * Resolves the target into an array of HTMLElements.
+   * @returns {HTMLElement[]}
+   */
+  _getElements() {
+    if (typeof this._target === "string") {
+      return Array.from(document.querySelectorAll(this._target));
+    }
+    if (this._target instanceof NodeList || Array.isArray(this._target)) {
+      return Array.from(this._target);
+    }
+    if (this._target instanceof HTMLElement) {
+      return [this._target];
+    }
+    return [];
+  }
+  /**
+   * Core synchronization routine.
+   * Measures natural heights, finds the max, applies it to all elements.
+   */
+  _sync() {
+    if (this._destroyed) return;
+    const elements = this._getElements();
+    if (elements.length === 0) return;
+    if (this._opts.breakpoint > 0 && window.innerWidth < this._opts.breakpoint) {
+      const prop2 = this._opts.minHeight ? "min-height" : "height";
+      elements.forEach((el) => el.style.removeProperty(prop2));
+      return;
+    }
+    const prop = this._opts.minHeight ? "min-height" : "height";
+    elements.forEach((el) => {
+      el.style.setProperty(prop, "", "important");
+      el.style.setProperty("box-sizing", "border-box", "important");
+    });
+    let maxH = 0;
+    elements.forEach((el) => {
+      const h = el.offsetHeight;
+      if (h > maxH) maxH = h;
+    });
+    if (maxH === 0) return;
+    elements.forEach((el) => {
+      if (this._opts.transitions) {
+        el.style.setProperty("transition", `${prop} 0.2s ease`, "");
+      }
+      el.style.setProperty(prop, `${maxH}px`, "important");
+    });
+  }
+  /**
+   * Sets up ResizeObserver to watch each element and MutationObserver to
+   * watch the parent containers for new elements being added.
+   */
+  _setupObservers() {
+    if (typeof ResizeObserver !== "undefined") {
+      this._resizeObserver = new ResizeObserver((entries) => {
+        if (entries.length > 0) {
+          this._debouncedSync();
+        }
+      });
+      const observe = () => {
+        this._getElements().forEach((el) => this._resizeObserver.observe(el));
+      };
+      observe();
+    } else {
+      const handler = debounce(this._sync.bind(this), Math.max(this._opts.debounce, 150));
+      const orientationHandler = () => setTimeout(() => this._sync(), 300);
+      window.addEventListener("resize", handler, { passive: true });
+      window.addEventListener("orientationchange", orientationHandler, { passive: true });
+      this._cleanupFallback = () => {
+        window.removeEventListener("resize", handler);
+        window.removeEventListener("orientationchange", orientationHandler);
+      };
+    }
+    if (typeof MutationObserver !== "undefined") {
+      const elements = this._getElements();
+      const parents = new Set(elements.map((el) => el.parentElement).filter(Boolean));
+      if (parents.size > 0) {
+        this._mutationObserver = new MutationObserver((mutations) => {
+          const hasNewNodes = mutations.some((m) => m.addedNodes.length > 0 || m.removedNodes.length > 0);
+          if (hasNewNodes) {
+            this._debouncedSync();
+            if (this._resizeObserver) {
+              this._getElements().forEach((el) => {
+                try {
+                  this._resizeObserver.observe(el);
+                } catch (_) {
+                }
+              });
+            }
+          }
+        });
+        parents.forEach((parent) => {
+          this._mutationObserver.observe(parent, { childList: true, subtree: false });
+        });
+      }
+    }
+  }
+}
+function heightHarmony(target, opts) {
+  return new HeightHarmonyInstance(target, opts);
+}
+heightHarmony.version = VERSION;
+heightHarmony.autoInit = function autoInit(opts = {}) {
+  const all = document.querySelectorAll("[data-hh-group]");
+  if (all.length === 0) return [];
+  const groups = /* @__PURE__ */ new Map();
+  all.forEach((el) => {
+    const key = el.getAttribute("data-hh-group");
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(el);
+  });
+  const instances = [];
+  groups.forEach((elements) => {
+    instances.push(new HeightHarmonyInstance(elements, opts));
+  });
+  return instances;
+};
+export {
+  HeightHarmonyInstance,
+  heightHarmony as default
+};

package/height-harmony.js

@@ -1,46 +1,316 @@
 /**
- * Sets all matching elements to the same height (the height of the tallest element)
- * @param {string} selector - CSS selector for the elements to harmonize
- * @version 1.0.1
+ * Height Harmony v2.0.0
+ * The fastest, smartest equal-height JavaScript utility on the web.
+ *
+ * Automatically synchronizes element heights using ResizeObserver and
+ * MutationObserver — no manual resize listeners needed.
+ *
+ * @author Byron Johnson
+ * @license MIT
+ * @see https://byronjohnson.github.io/height-harmony/demo/
  */
-function heightHarmony(selector) {
-    // Get all matching elements
-    const elements = document.querySelectorAll(selector);
 
-    // Exit if no elements found
+/**
+ * @typedef {Object} HeightHarmonyOptions
+ * @property {number}  [debounce=0]       - Milliseconds to debounce resize/mutation callbacks (0 = rAF only)
+ * @property {boolean} [minHeight=false]  - Use min-height instead of height, allowing elements to grow taller
+ * @property {number}  [breakpoint=0]     - Disable harmonizing below this viewport width (px); 0 = always on
+ * @property {boolean} [watch=true]       - Auto-watch via ResizeObserver and MutationObserver
+ * @property {boolean} [transitions=true] - Apply CSS transition on height changes for smooth animation
+ */
+
+const VERSION = '2.0.0';
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Creates a debounced version of fn that fires after `wait` ms of inactivity.
+ * If wait === 0 we skip the timeout and only use requestAnimationFrame.
+ * @param {Function} fn
+ * @param {number} wait
+ * @returns {Function}
+ */
+function debounce(fn, wait) {
+  let timer = null;
+  return function debounced(...args) {
+    if (timer !== null) clearTimeout(timer);
+    if (wait > 0) {
+      timer = setTimeout(() => {
+        timer = null;
+        requestAnimationFrame(() => fn.apply(this, args));
+      }, wait);
+    } else {
+      requestAnimationFrame(() => fn.apply(this, args));
+    }
+  };
+}
+
+// ─── HeightHarmonyInstance ───────────────────────────────────────────────────
+
+class HeightHarmonyInstance {
+  /**
+   * @param {string|NodeList|HTMLElement[]} target  CSS selector or element list
+   * @param {HeightHarmonyOptions} options
+   */
+  constructor(target, options = {}) {
+    this._target = target;
+    this._opts = Object.assign(
+      { debounce: 0, minHeight: false, breakpoint: 0, watch: true, transitions: true },
+      options
+    );
+
+    this._destroyed = false;
+    this._resizeObserver = null;
+    this._mutationObserver = null;
+    this._cleanupFallback = null;
+    this._debouncedSync = debounce(this._sync.bind(this), this._opts.debounce);
+
+    // Run immediately
+    this._sync();
+
+    // Set up observers if watching is enabled
+    if (this._opts.watch) {
+      this._setupObservers();
+    }
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────────────
+
+  /**
+   * Manually triggers a height re-calculation.
+   * Useful after CSS transitions finish or after content changes you control.
+   * @returns {this}
+   */
+  refresh() {
+    if (this._destroyed) return this;
+    this._sync();
+    return this;
+  }
+
+  /**
+   * Tears down all observers, removes inline height/transition styles set by
+   * this instance, and marks the instance as destroyed.
+   * @returns {this}
+   */
+  destroy() {
+    if (this._destroyed) return this;
+    this._destroyed = true;
+
+    if (this._resizeObserver) {
+      this._resizeObserver.disconnect();
+      this._resizeObserver = null;
+    }
+    if (this._mutationObserver) {
+      this._mutationObserver.disconnect();
+      this._mutationObserver = null;
+    }
+
+    // Clean up window event listeners added by the ResizeObserver fallback
+    if (this._cleanupFallback) {
+      this._cleanupFallback();
+      this._cleanupFallback = null;
+    }
+
+    // Remove all inline styles we set
+    const prop = this._opts.minHeight ? 'min-height' : 'height';
+    this._getElements().forEach(el => {
+      el.style.removeProperty(prop);
+      el.style.removeProperty('box-sizing');
+      if (this._opts.transitions) {
+        el.style.removeProperty('transition');
+      }
+    });
+
+    return this;
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Resolves the target into an array of HTMLElements.
+   * @returns {HTMLElement[]}
+   */
+  _getElements() {
+    if (typeof this._target === 'string') {
+      return Array.from(document.querySelectorAll(this._target));
+    }
+    if (this._target instanceof NodeList || Array.isArray(this._target)) {
+      return Array.from(this._target);
+    }
+    if (this._target instanceof HTMLElement) {
+      return [this._target];
+    }
+    return [];
+  }
+
+  /**
+   * Core synchronization routine.
+   * Measures natural heights, finds the max, applies it to all elements.
+   */
+  _sync() {
+    if (this._destroyed) return;
+
+    const elements = this._getElements();
     if (elements.length === 0) return;
 
-    // First pass: Reset all heights to 0px to clear any previous styling completely
-    elements.forEach(element => {
-        element.style.height = '0px';
+    // Check breakpoint — disable below threshold
+    if (this._opts.breakpoint > 0 && window.innerWidth < this._opts.breakpoint) {
+      const prop = this._opts.minHeight ? 'min-height' : 'height';
+      elements.forEach(el => el.style.removeProperty(prop));
+      return;
+    }
+
+    const prop = this._opts.minHeight ? 'min-height' : 'height';
+
+    // Step 1: Strip current inline heights so we read natural layout heights
+    elements.forEach(el => {
+      el.style.setProperty(prop, '', 'important');
+      // Ensure border-box so our offsetHeight read is reliable
+      el.style.setProperty('box-sizing', 'border-box', 'important');
+    });
+
+    // Step 2: Force a synchronous layout read (single batch)
+    // We use offsetHeight (includes padding/border, respects box model)
+    let maxH = 0;
+    elements.forEach(el => {
+      const h = el.offsetHeight;
+      if (h > maxH) maxH = h;
+    });
+
+    if (maxH === 0) return;
+
+    // Step 3: Apply the max height to all elements
+    elements.forEach(el => {
+      if (this._opts.transitions) {
+        el.style.setProperty('transition', `${prop} 0.2s ease`, '');
+      }
+      el.style.setProperty(prop, `${maxH}px`, 'important');
     });
+  }
+
+  /**
+   * Sets up ResizeObserver to watch each element and MutationObserver to
+   * watch the parent containers for new elements being added.
+   */
+  _setupObservers() {
+    // ResizeObserver: re-sync whenever any observed element changes size
+    if (typeof ResizeObserver !== 'undefined') {
+      this._resizeObserver = new ResizeObserver(entries => {
+        // Only fire if at least one entry has a real size change
+        if (entries.length > 0) {
+          this._debouncedSync();
+        }
+      });
 
-    // Use requestAnimationFrame for better browser synchronization
-    requestAnimationFrame(() => {
-        // Reset heights to auto to get natural heights
-        let maxHeight = 0;
+      const observe = () => {
+        this._getElements().forEach(el => this._resizeObserver.observe(el));
+      };
 
-        // Find the maximum natural height
-        elements.forEach(element => {
-            // Reset to empty string to get natural height
-            element.style.height = '';
+      observe();
+    } else {
+      // Fallback for browsers without ResizeObserver (very old Safari, etc.)
+      const handler = debounce(this._sync.bind(this), Math.max(this._opts.debounce, 150));
+      const orientationHandler = () => setTimeout(() => this._sync(), 300);
 
-            // Get the element's height
-            const elementHeight = element.offsetHeight;
+      window.addEventListener('resize', handler, { passive: true });
+      window.addEventListener('orientationchange', orientationHandler, { passive: true });
 
-            // Update maxHeight if this element is taller
-            maxHeight = Math.max(maxHeight, elementHeight);
+      // Store cleanup so destroy() can remove both listeners
+      this._cleanupFallback = () => {
+        window.removeEventListener('resize', handler);
+        window.removeEventListener('orientationchange', orientationHandler);
+      };
+    }
+
+    // MutationObserver: re-sync when new children are added to parent containers
+    if (typeof MutationObserver !== 'undefined') {
+      const elements = this._getElements();
+      const parents = new Set(elements.map(el => el.parentElement).filter(Boolean));
+
+      if (parents.size > 0) {
+        this._mutationObserver = new MutationObserver(mutations => {
+          const hasNewNodes = mutations.some(m => m.addedNodes.length > 0 || m.removedNodes.length > 0);
+          if (hasNewNodes) {
+            this._debouncedSync();
+            // Re-observe any new elements (ResizeObserver)
+            if (this._resizeObserver) {
+              this._getElements().forEach(el => {
+                try { this._resizeObserver.observe(el); } catch (_) {}
+              });
+            }
+          }
         });
 
-        // Set all elements to the maximum height
-        elements.forEach(element => {
-            element.style.height = maxHeight + 'px';
+        parents.forEach(parent => {
+          this._mutationObserver.observe(parent, { childList: true, subtree: false });
         });
-    });
+      }
+    }
+  }
 }
 
-// Add version information
-heightHarmony.version = '1.0.0';
+// ─── Public factory function ──────────────────────────────────────────────────
+
+/**
+ * heightHarmony — equalizes the heights of all elements matching `target`.
+ *
+ * @param {string|NodeList|HTMLElement[]} target  - CSS selector or element collection
+ * @param {HeightHarmonyOptions}          [opts]  - Configuration options
+ * @returns {HeightHarmonyInstance}               - Instance with refresh() and destroy() methods
+ *
+ * @example
+ * // Basic usage (same as v1)
+ * heightHarmony('.card');
+ *
+ * @example
+ * // With options
+ * heightHarmony('.card', { debounce: 100, breakpoint: 768 });
+ *
+ * @example
+ * // Store instance for later control
+ * const hh = heightHarmony('.card');
+ * hh.refresh();   // manual re-trigger
+ * hh.destroy();   // clean up observers & styles
+ */
+function heightHarmony(target, opts) {
+  return new HeightHarmonyInstance(target, opts);
+}
+
+// ─── Static metadata ──────────────────────────────────────────────────────────
+
+heightHarmony.version = VERSION;
+
+/**
+ * Auto-initializes all elements with `data-hh-group` attributes.
+ * Groups elements sharing the same data-hh-group value and harmonizes each group.
+ *
+ * Usage in HTML:
+ *   <div data-hh-group="cards">...</div>
+ *   <div data-hh-group="cards">...</div>
+ *
+ * @param {HeightHarmonyOptions} [opts] - Options applied to all groups
+ * @returns {HeightHarmonyInstance[]}   - Array of instances, one per group
+ */
+heightHarmony.autoInit = function autoInit(opts = {}) {
+  const all = document.querySelectorAll('[data-hh-group]');
+  if (all.length === 0) return [];
+
+  /** @type {Map<string, HTMLElement[]>} */
+  const groups = new Map();
+  all.forEach(el => {
+    const key = el.getAttribute('data-hh-group');
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(el);
+  });
+
+  const instances = [];
+  groups.forEach((elements) => {
+    instances.push(new HeightHarmonyInstance(elements, opts));
+  });
+  return instances;
+};
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
 
-// Export the function as the default export
+export { HeightHarmonyInstance };
 export default heightHarmony;

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "height-harmony",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "A lightweight, zero-dependency JavaScript utility for equalizing element heights",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
   "main": "dist/height-harmony-min.js",
-  "module": "height-harmony.js",
+  "module": "dist/height-harmony.es.js",
   "exports": {
     ".": {
-      "import": "./height-harmony.js",
-      "require": "./dist/height-harmony-min.js",
-      "browser": "./dist/height-harmony-min.js"
+      "browser": "./dist/height-harmony-min.js",
+      "import": "./dist/height-harmony.es.js",
+      "require": "./dist/height-harmony-min.js"
     }
   },
   "browser": "dist/height-harmony-min.js",
@@ -17,12 +21,15 @@
   "files": [
     "height-harmony.js",
     "dist/height-harmony-min.js",
+    "dist/height-harmony.es.js",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "build": "vite build",
+    "build:demo": "cp dist/height-harmony-min.js demo/height-harmony-min.js && vite build --config demo/vite.config.js && cp dist/height-harmony-min.js demo-dist/height-harmony-min.js",
+    "build:all": "npm run build && npm run build:demo",
     "dev": "vite build --watch",
     "prepublishOnly": "npm run build"
   },
@@ -37,13 +44,19 @@
   "keywords": [
     "javascript",
     "height",
+    "equal-height",
     "equalize",
     "responsive",
     "css",
     "utility",
     "frontend",
     "dom",
-    "elements"
+    "elements",
+    "resize-observer",
+    "mutation-observer",
+    "auto",
+    "layout",
+    "zero-dependency"
   ],
   "author": "Byron Johnson",
   "license": "MIT",
@@ -52,6 +65,6 @@
     "vite": "^6.3.6"
   },
   "engines": {
-    "node": ">=0.10.0"
+    "node": ">=14.0.0"
   }
-}
+}