@ktfth/stickjs 3.0.0

package/stick.js

@@ -0,0 +1,655 @@
+/*!
+ * Stick.js — declarative behavior for HTML elements
+ * https://github.com/kaiquekandykoga/Stickjs
+ *
+ * Syntax:
+ *   data-stick="event:handler:param"
+ *   data-stick-target="#selector"        apply handler to another element
+ *   data-stick-2="event:handler:param"   stack behaviors (up to data-stick-5)
+ *   data-stick-target-2="#other"         per-slot target for data-stick-2
+ *   data-stick-once                      remove listener after first run
+ *   data-stick-debounce="300"            debounce handler by N ms
+ *   data-stick-throttle="300"           throttle handler by N ms
+ *   data-stick-confirm="Are you sure?"   confirmation dialog before handler
+ *   data-stick-key="Enter"              only fire on matching KeyboardEvent.key (comma-separated)
+ *   data-stick-prevent                  always call event.preventDefault() before handler
+ *   data-stick-stop                     always call event.stopPropagation() before handler
+ *   data-stick-passive                   add listener as passive (good for scroll/touch)
+ *   data-stick-capture                   add listener in capture phase
+ *   data-stick-delegate=".item"          event delegation — listen on el, fire for matching children
+ *   data-stick-method="POST"             HTTP method for fetch handler
+ *   data-stick-swap="beforeend"          fetch insertion mode: innerHTML|outerHTML|prepend|append|beforeend|afterbegin|…
+ *   data-stick-loading="Loading…"        button label while fetch is in-flight
+ *   data-stick-headers='{"Authorization":"Bearer token"}' fetch headers (JSON)
+ *   data-stick-json='{"key":"{{value}}"}' send JSON body instead of FormData
+ *
+ * Target selectors (data-stick-target):
+ *   "#id"            querySelector (default)
+ *   "next"           el.nextElementSibling
+ *   "prev"           el.previousElementSibling
+ *   "parent"         el.parentElement
+ *   "closest:sel"    el.closest(sel)
+ *   "self"           el itself (explicit)
+ *   "siblings"       all sibling elements (same parent, excluding el)
+ *   "all:sel"        all elements matching CSS sel (querySelectorAll)
+ *
+ * Param interpolation — use element properties inside param:
+ *   {{value}}   el.value            (input, select, textarea)
+ *   {{text}}    el.textContent
+ *   {{id}}      el.id
+ *   {{name}}    el.name
+ *   {{checked}} el.checked (true/false)
+ *   {{index}}   el's index among parent's children
+ *   {{length}}  el.children.length
+ *   {{chars}}   el.value.length (or textContent.length)
+ *   {{url:key}} URLSearchParams value from current page URL (e.g. {{url:q}} → ?q=value)
+ *   {{data-*}}  any data attribute, e.g. {{data-id}}
+ *   {{attr}}    any attribute, e.g. {{href}}, {{src}}
+ *
+ *   Example: data-stick="input:fetch:/api/search?q={{value}}"
+ *            data-stick="click:dispatch:item-selected:{{data-id}}"
+ *
+ * Synthetic events:
+ *   ready      — fires immediately on bind (before any user interaction)
+ *   intersect  — fires when element enters the viewport (IntersectionObserver)
+ *   watch      — fires immediately, then on every attribute mutation of el (MutationObserver)
+ *
+ * Handler signature:
+ *   Stick.add('name', (el, param, event, target) => { ... })
+ *
+ * API:
+ *   Stick.version          semver string
+ *   Stick.add(name, fn)    register handler (chainable)
+ *   Stick.remove(name)     unregister handler (chainable)
+ *   Stick.use(plugin)      register a plugin: fn(stick) | { install } | { name: fn }
+ *   Stick.debug(true?)     enable verbose console logging (dev mode)
+ *   Stick.unbind(el)       remove all listeners and reset data-stick-bound (chainable)
+ *   Stick.handlers         read-only map of registered handler names → fns
+ *   Stick.init(root?)      scan and bind [data-stick] elements (chainable)
+ *   Stick.observe(root?)   auto-bind new elements via MutationObserver (chainable)
+ *   Stick.parse(value)     parse string → { event, handler, param } | null
+ */
+
+(function (root, factory) {
+  // UMD: works as <script>, CommonJS (require), or ESM (import)
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.Stick = factory();
+  }
+}(typeof window !== 'undefined' ? window : this, function () {
+  'use strict';
+
+  const VERSION     = '3.0.0';
+  const handlers    = {};
+  const listenerMap = new WeakMap(); // el → [{event, fn, options}]
+  let   _debug      = false;
+  const _hooks       = {};
+
+  function emitHook(name, ...args) {
+    (_hooks[name] || []).forEach(fn => {
+      try { fn(...args); } catch (err) { console.error('[Stick] hook "' + name + '" threw:', err); }
+    });
+  }
+
+  // ── helpers ────────────────────────────────────────────────────────
+
+  function debounce(fn, ms) {
+    let t;
+    return function (...args) { clearTimeout(t); t = setTimeout(() => fn.apply(this, args), ms); };
+  }
+
+  function throttle(fn, ms) {
+    let last = 0;
+    return function (...args) {
+      const now = Date.now();
+      if (now - last >= ms) { last = now; fn.apply(this, args); }
+    };
+  }
+
+  function swap(target, html, mode) {
+    switch (mode) {
+      case 'outerHTML':   target.outerHTML = html;                       break;
+      case 'prepend':
+      case 'afterbegin':  target.insertAdjacentHTML('afterbegin',  html); break;
+      case 'append':
+      case 'beforeend':   target.insertAdjacentHTML('beforeend',   html); break;
+      case 'afterend':    target.insertAdjacentHTML('afterend',    html); break;
+      case 'beforebegin': target.insertAdjacentHTML('beforebegin', html); break;
+      default:            target.innerHTML = html;                        break;
+    }
+  }
+
+  // Walk a cloned DocumentFragment and interpolate {{tokens}} in text nodes and attributes
+  function interpolateClone(fragment, sourceEl) {
+    const walk = document.createTreeWalker(fragment, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
+    let node;
+    while ((node = walk.nextNode())) {
+      if (node.nodeType === Node.TEXT_NODE) {
+        if (node.nodeValue.includes('{{')) node.nodeValue = interpolate(node.nodeValue, sourceEl);
+      } else {
+        [...node.attributes].forEach(attr => {
+          if (attr.value.includes('{{')) attr.value = interpolate(attr.value, sourceEl);
+        });
+      }
+    }
+  }
+
+  // Resolve {{token}} placeholders using properties of el
+  function interpolate(param, el) {
+    return param.replace(/\{\{([\w-]+)\}\}/g, (_, key) => {
+      if (key === 'value')   return el.value   ?? '';
+      if (key === 'text')    return el.textContent.trim();
+      if (key === 'id')      return el.id      ?? '';
+      if (key === 'name')    return el.name    ?? '';
+      if (key === 'checked') return String(el.checked ?? false);
+      if (key === 'index')   return el.parentElement ? String([...el.parentElement.children].indexOf(el)) : '0';
+      if (key === 'length')  return String(el.children?.length ?? 0);
+      if (key === 'chars')   return String(el.value != null ? el.value.length : el.textContent.length);
+      if (key.startsWith('url:'))  return (typeof location !== 'undefined' ? new URLSearchParams(location.search).get(key.slice(4)) : null) ?? '';
+      if (key.startsWith('data-')) return el.dataset[toCamel(key.slice(5))] ?? '';
+      return el.getAttribute(key) ?? '';
+    });
+  }
+
+  function toCamel(s) {
+    return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  }
+
+  // Resolve data-stick-target → array of Elements
+  // Keywords: "self" | "next" | "prev" | "parent" | "siblings" | "closest:sel" | "all:sel" | CSS selector
+  function resolveTargets(sel, el) {
+    if (!sel)                       return [el];
+    if (sel === 'self')             return [el];
+    if (sel === 'siblings')         return [...(el.parentElement?.children ?? [])].filter(c => c !== el);
+    if (sel === 'next')             return el.nextElementSibling  ? [el.nextElementSibling]  : [];
+    if (sel === 'prev')             return el.previousElementSibling ? [el.previousElementSibling] : [];
+    if (sel === 'parent')           return el.parentElement ? [el.parentElement] : [];
+    if (sel.startsWith('closest:')) { const f = el.closest(sel.slice(8)); return f ? [f] : []; }
+    if (sel.startsWith('all:'))     return [...document.querySelectorAll(sel.slice(4))];
+    const found = document.querySelector(sel);
+    return found ? [found] : [];
+  }
+
+  function closeGroup(target) {
+    var group = target.dataset && target.dataset.stickGroup;
+    if (!group) return;
+    document.querySelectorAll('[data-stick-group="' + group + '"]').forEach(function(el) {
+      if (el !== target) el.hidden = true;
+    });
+  }
+
+  function transitionShow(target) {
+    var name = target.dataset && target.dataset.stickTransition;
+    if (!name) { target.hidden = false; return; }
+    target.hidden = false;
+    target.classList.add(name + '-enter-active');
+    var done = function() { target.classList.remove(name + '-enter-active'); };
+    target.addEventListener('animationend', done, { once: true });
+    target.addEventListener('transitionend', done, { once: true });
+    // Fallback: if no animation/transition is defined, clean up on next frame
+    requestAnimationFrame(function() {
+      requestAnimationFrame(function() {
+        if (target.classList.contains(name + '-enter-active')) {
+          var cs = getComputedStyle(target);
+          var dur = (parseFloat(cs.animationDuration) || 0) + (parseFloat(cs.transitionDuration) || 0);
+          if (dur === 0) done();
+        }
+      });
+    });
+  }
+
+  function transitionHide(target) {
+    var name = target.dataset && target.dataset.stickTransition;
+    if (!name) { target.hidden = true; return; }
+    target.classList.add(name + '-leave-active');
+    var cleaned = false;
+    var done = function() {
+      if (cleaned) return;
+      cleaned = true;
+      target.classList.remove(name + '-leave-active');
+      target.hidden = true;
+    };
+    target.addEventListener('animationend', done, { once: true });
+    target.addEventListener('transitionend', done, { once: true });
+    // Fallback: if no animation/transition, hide immediately
+    requestAnimationFrame(function() {
+      requestAnimationFrame(function() {
+        if (!cleaned) {
+          var cs = getComputedStyle(target);
+          var dur = (parseFloat(cs.animationDuration) || 0) + (parseFloat(cs.transitionDuration) || 0);
+          if (dur === 0) done();
+        }
+      });
+    });
+  }
+
+  // ── core ──────────────────────────────────────────────────────────
+
+  const Stick = {
+    version: VERSION,
+
+    add(name, fn) {
+      handlers[name] = fn;
+      return this;
+    },
+
+    remove(name) {
+      delete handlers[name];
+      return this;
+    },
+
+    // Register multiple handlers at once.
+    // Accepts: fn(stick), { install(stick) {} }, or { 'name': fn, … }
+    use(plugin) {
+      if (typeof plugin === 'function') plugin(this);
+      else if (plugin && typeof plugin.install === 'function') plugin.install(this);
+      else if (plugin && typeof plugin === 'object') {
+        Object.entries(plugin).forEach(([name, fn]) => this.add(name, fn));
+      }
+      return this;
+    },
+
+    /** Enable/disable verbose console logging. Chainable. */
+    debug(on = true) { _debug = !!on; return this; },
+
+    /** Register a lifecycle hook. Events: 'bind', 'unbind'. Chainable. */
+    on(event, fn) {
+      if (!_hooks[event]) _hooks[event] = [];
+      _hooks[event].push(fn);
+      return this;
+    },
+
+    // Remove all event listeners from el and reset its bound state
+    unbind(el) {
+      const listeners = listenerMap.get(el);
+      if (listeners) {
+        listeners.forEach(({ event, fn, options }) => el.removeEventListener(event, fn, options));
+        listenerMap.delete(el);
+      }
+      el.removeAttribute('data-stick-bound');
+      emitHook('unbind', el);
+      return this;
+    },
+
+    // Read-only view of all registered handlers
+    get handlers() { return Object.freeze({ ...handlers }); },
+
+    parse(value) {
+      if (!value) return null;
+      const i1 = value.indexOf(':');
+      if (i1 === -1) return null;
+      const i2 = value.indexOf(':', i1 + 1);
+      // Allow "event:handler" shorthand — trailing colon is optional when param is empty
+      if (i2 === -1) return {
+        event:   value.slice(0, i1).trim(),
+        handler: value.slice(i1 + 1).trim(),
+        param:   '',
+      };
+      return {
+        event:   value.slice(0, i1).trim(),
+        handler: value.slice(i1 + 1, i2).trim(),
+        param:   value.slice(i2 + 1).trim(),
+      };
+    },
+
+    fire(el, handler, param, event) {
+      if (typeof handlers[handler] !== 'function') {
+        console.warn('[Stick] fire: unknown handler "' + handler + '"');
+        return this;
+      }
+      try {
+        handlers[handler](el, param || '', event || { type: 'fire' }, el);
+      } catch (err) {
+        console.error('[Stick] handler "' + handler + '" threw:', err);
+      }
+      return this;
+    },
+
+    bind(el) {
+      if (el.hasAttribute('data-stick-bound')) return;
+      el.setAttribute('data-stick-bound', '');
+      emitHook('bind', el);
+
+      const once          = 'stickOnce'    in el.dataset;
+      const passive       = 'stickPassive' in el.dataset;
+      const capture       = 'stickCapture' in el.dataset;
+      const alwaysPrevent = 'stickPrevent' in el.dataset;
+      const alwaysStop    = 'stickStop'    in el.dataset;
+      const confirmMsg    = el.dataset.stickConfirm;
+      const keyFilter     = el.dataset.stickKey ? el.dataset.stickKey.split(',').map(k => k.trim()) : null;
+      const delegateSel   = el.dataset.stickDelegate || null;
+      const debounceMs  = parseInt(el.dataset.stickDebounce,  10) || 0;
+      const throttleMs  = parseInt(el.dataset.stickThrottle,  10) || 0;
+
+      // Slot keys and their per-slot target attribute names
+      // data-stick      → data-stick-target   (or data-stick-target-1)
+      // data-stick-2    → data-stick-target-2
+      // data-stick-3    → data-stick-target-3  …
+      // Note: data-stick-2 maps to dataset["stick-2"] (not "stick2")
+      // because the HTML spec only camelCases hyphens before letters, not digits.
+      const slots = [
+        { key: 'stick',   targetKey: 'stickTarget' },
+        { key: 'stick-2', targetKey: 'stickTarget-2' },
+        { key: 'stick-3', targetKey: 'stickTarget-3' },
+        { key: 'stick-4', targetKey: 'stickTarget-4' },
+        { key: 'stick-5', targetKey: 'stickTarget-5' },
+      ];
+
+      slots.forEach(({ key, targetKey }) => {
+        const value = el.dataset[key];
+        if (!value) return;
+
+        const parsed = this.parse(value);
+        if (!parsed) return;
+
+        const { event, handler, param } = parsed;
+
+        if (typeof handlers[handler] !== 'function') {
+          console.warn(`[Stick] unknown handler: "${handler}"`);
+          return;
+        }
+
+        // Per-slot target: data-stick-target-N, fall back to shared data-stick-target
+        const targetSel = el.dataset[targetKey] || el.dataset.stickTarget;
+        const targets   = resolveTargets(targetSel, el);
+        if (targetSel && targets.length === 0) console.warn(`[Stick] target not found: "${targetSel}"`);
+
+        if (_debug) console.log(`[Stick:bind] ${event}:${handler}:${param}`, el, '→ targets', targets);
+
+        if (event === 'ready') {
+          const resolved = interpolate(param, el);
+          if (_debug) console.log(`[Stick:ready] ${handler}`, el, 'param=', resolved);
+          targets.forEach(t => {
+            try {
+              handlers[handler](el, resolved, { type: 'ready' }, t);
+            } catch (err) {
+              console.error(`[Stick] handler "${handler}" threw:`, err);
+            }
+          });
+          return;
+        }
+
+        if (event === 'watch') {
+          // Fire immediately (like ready), then on every attribute mutation of el
+          const fire = () => {
+            const resolved = interpolate(param, el);
+            if (_debug) console.log(`[Stick:watch] ${handler}`, el, 'param=', resolved);
+            targets.forEach(t => {
+              try {
+                handlers[handler](el, resolved, { type: 'watch' }, t);
+              } catch (err) {
+                console.error(`[Stick] handler "${handler}" threw:`, err);
+              }
+            });
+          };
+          fire();
+          new MutationObserver(fire).observe(el, { attributes: true });
+          return;
+        }
+
+        if (event === 'intersect') {
+          const io = new IntersectionObserver((entries, obs) => {
+            entries.forEach((entry) => {
+              if (!entry.isIntersecting) return;
+              if (confirmMsg && !window.confirm(confirmMsg)) return;
+              const resolved = interpolate(param, el);
+              targets.forEach(t => {
+                try {
+                  handlers[handler](el, resolved, { type: 'intersect', entry }, t);
+                } catch (err) {
+                  console.error(`[Stick] handler "${handler}" threw:`, err);
+                }
+              });
+              if (once) obs.unobserve(el);
+            });
+          });
+          io.observe(el);
+          return;
+        }
+
+        let fn = (e) => {
+          // Event delegation: only fire when event.target matches delegateSel
+          let activeEl = el;
+          if (delegateSel) {
+            const matched = e.target instanceof Element ? e.target.closest(delegateSel) : null;
+            if (!matched || !el.contains(matched)) return;
+            activeEl = matched;
+          }
+          if (keyFilter && e.key !== undefined && !keyFilter.includes(e.key)) return;
+          if (alwaysPrevent) e.preventDefault();
+          if (alwaysStop)    e.stopPropagation();
+          if (confirmMsg && !window.confirm(confirmMsg)) return;
+          const resolved = interpolate(param, activeEl);
+          // With delegation, resolve targets fresh from the matched child element
+          const liveTargets = delegateSel ? resolveTargets(targetSel, activeEl) : targets;
+          if (_debug) console.log(`[Stick:fire] ${event}:${handler}`, activeEl, 'param=', resolved, 'targets=', liveTargets);
+          liveTargets.forEach(t => {
+            try {
+              handlers[handler](activeEl, resolved, e, t);
+            } catch (err) {
+              console.error(`[Stick] handler "${handler}" threw:`, err);
+            }
+          });
+        };
+
+        if (debounceMs > 0) fn = debounce(fn, debounceMs);
+        if (throttleMs > 0) fn = throttle(fn, throttleMs);
+
+        const options = { once, passive, capture };
+        if (!listenerMap.has(el)) listenerMap.set(el, []);
+        if (!once) listenerMap.get(el).push({ event, fn, options });
+        el.addEventListener(event, fn, options);
+      });
+    },
+
+    init(root = document) {
+      root.querySelectorAll('[data-stick]').forEach((el) => this.bind(el));
+      return this;
+    },
+
+    observe(root = document.body) {
+      new MutationObserver((mutations) => {
+        mutations.forEach(({ addedNodes }) => {
+          addedNodes.forEach((node) => {
+            if (node.nodeType !== 1) return;
+            if (node.matches('[data-stick]')) this.bind(node);
+            node.querySelectorAll?.('[data-stick]').forEach((el) => this.bind(el));
+          });
+        });
+      }).observe(root, { childList: true, subtree: true });
+      return this;
+    },
+  };
+
+  // ── built-in handlers ─────────────────────────────────────────────
+
+  Stick
+    .add('show',         (el, p, e, t) => {
+      transitionShow(t); closeGroup(t);
+      if (el) el.setAttribute('aria-expanded', 'true');
+    })
+    .add('hide',         (el, p, e, t) => {
+      transitionHide(t);
+      if (el) el.setAttribute('aria-expanded', 'false');
+    })
+    .add('toggle',       (el, p, e, t) => {
+      if (t.hidden) { transitionShow(t); closeGroup(t); }
+      else transitionHide(t);
+      if (el) el.setAttribute('aria-expanded', String(!t.hidden));
+    })
+    .add('add-class',    (el, p, e, t) => { t.classList.add(p); })
+    .add('remove-class', (el, p, e, t) => { t.classList.remove(p); })
+    .add('toggle-class', (el, p, e, t) => { t.classList.toggle(p); })
+    .add('set-text',     (el, p, e, t) => { t.textContent = p; })
+    .add('set-html',     (el, p, e, t) => { t.innerHTML = p; })
+    .add('set-value',    (el, p, e, t) => { t.value = p; })
+    .add('clear',        (el, p, e, t) => { t.textContent = ''; })
+    .add('set-attr',     (el, p, e, t) => { const [a, ...v] = p.split(':'); t.setAttribute(a, v.join(':')); })
+    .add('remove-attr',  (el, p, e, t) => { t.removeAttribute(p); })
+    .add('toggle-attr',  (el, p, e, t) => { t.hasAttribute(p) ? t.removeAttribute(p) : t.setAttribute(p, ''); })
+    .add('set-style',    (el, p, e, t) => { const [prop, ...v] = p.split(':'); t.style[prop] = v.join(':'); })
+    .add('focus',        (el, p, e, t) => { t.focus(); })
+    .add('scroll-to',    (el, p, e, t) => { t.scrollIntoView({ behavior: 'smooth' }); })
+    .add('copy',         (el, p)       => { navigator.clipboard?.writeText(p || el.textContent.trim()); })
+    .add('navigate',     (el, p)       => { window.location.href = p; })
+    .add('open',         (el, p)       => { window.open(p, '_blank', 'noopener'); })
+    .add('back',         ()            => { window.history.back(); })
+    .add('forward',      ()            => { window.history.forward(); })
+    .add('history-push', (el, p)      => { window.history.pushState({}, '', p); })
+    .add('select',       (el, p, e, t) => { t.select?.(); })
+    .add('submit',       (el, p, e, t) => { (t.tagName === 'FORM' ? t : t.closest('form'))?.submit(); })
+    .add('reset',        (el, p, e, t) => { (t.tagName === 'FORM' ? t : t.closest('form'))?.reset(); })
+    .add('prevent',      (el, p, e)    => { e.preventDefault(); })
+    .add('stop',         (el, p, e)    => { e.stopPropagation(); })
+    // DOM mutations
+    .add('remove',       (el, p, e, t) => { t.remove(); })
+    .add('disable',      (el, p, e, t) => { t.disabled = true; })
+    .add('enable',       (el, p, e, t) => { t.disabled = false; })
+    // Checkbox
+    .add('check',        (el, p, e, t) => { t.checked = true; })
+    .add('uncheck',      (el, p, e, t) => { t.checked = false; })
+    .add('toggle-check', (el, p, e, t) => { t.checked = !t.checked; })
+    // Data attributes
+    .add('set-data',     (el, p, e, t) => { const [k, ...v] = p.split(':'); t.dataset[toCamel(k)] = v.join(':'); })
+    // ARIA attributes
+    .add('set-aria', (el, p, e, t) => {
+      const [attr, ...v] = p.split(':');
+      const name = attr.startsWith('aria-') ? attr : 'aria-' + attr;
+      t.setAttribute(name, v.join(':'));
+    })
+    .add('toggle-aria', (el, p, e, t) => {
+      const name = p.startsWith('aria-') ? p : 'aria-' + p;
+      const cur = t.getAttribute(name);
+      t.setAttribute(name, cur === 'true' ? 'false' : 'true');
+    })
+    // Counters — param is optional step (default 1); works on inputs and text nodes
+    .add('increment', (el, p, e, t) => {
+      const step = parseFloat(p) || 1;
+      if (t.matches?.('input,select,textarea')) t.value = String((parseFloat(t.value) || 0) + step);
+      else t.textContent = String((parseFloat(t.textContent) || 0) + step);
+    })
+    .add('decrement', (el, p, e, t) => {
+      const step = parseFloat(p) || 1;
+      if (t.matches?.('input,select,textarea')) t.value = String((parseFloat(t.value) || 0) - step);
+      else t.textContent = String((parseFloat(t.textContent) || 0) - step);
+    })
+    .add('scroll-top',   ()            => { window.scrollTo({ top: 0, behavior: 'smooth' }); })
+    .add('reload',       ()            => { window.location.reload(); })
+    .add('print',        ()            => { window.print(); })
+    // Native <dialog>
+    .add('show-modal',   (el, p, e, t) => { closeGroup(t); t.showModal?.(); })
+    .add('close-modal',  (el, p, e, t) => { t.close?.(p || undefined); })
+    // Timing
+    .add('wait', (el, p, e, t) => {
+      const ms = parseInt(p, 10) || 0;
+      return new Promise(resolve => setTimeout(resolve, ms));
+    })
+    // CSS animation — add class, auto-remove after animationend
+    .add('animate', (el, p, e, t) => {
+      t.classList.add(p);
+      t.addEventListener('animationend', () => t.classList.remove(p), { once: true });
+    })
+    // Template cloning — duplicate <template> content into target; {{tokens}} resolved from el
+    .add('clone-template', (el, p, e, t) => {
+      const tpl = document.querySelector(p);
+      if (!tpl || tpl.tagName !== 'TEMPLATE') {
+        console.warn(`[Stick] clone-template: no <template> at "${p}"`);
+        return;
+      }
+      const clone = tpl.content.cloneNode(true);
+      interpolateClone(clone, el);   // resolve {{tokens}} from trigger element
+      t.appendChild(clone);
+      Stick.init(t);
+    })
+    // Sort target's children by textContent or a data/attribute key (param: "data-price" or "" for text)
+    .add('sort', (el, p, e, t) => {
+      const items = [...t.children];
+      items.sort((a, b) => {
+        const val = (node) => p
+          ? (node.dataset[toCamel(p.replace(/^data-/, ''))] ?? node.getAttribute(p) ?? node.textContent)
+          : node.textContent.trim();
+        return val(a).localeCompare(val(b), undefined, { numeric: true });
+      });
+      items.forEach(i => t.appendChild(i));
+    })
+    // Count matching elements and set target text (param: CSS selector, or empty = target.children.length)
+    .add('count', (el, p, e, t) => {
+      const n = p ? document.querySelectorAll(p).length : (t.children?.length ?? 0);
+      t.textContent = String(n);
+    })
+    // Debug
+    .add('log',          (el, p)       => { console.log('[Stick]', p || el); })
+    .add('alert',        (el, p)       => { window.alert(p); })
+    // Dispatch a custom event — lets components talk without shared state
+    .add('dispatch',     (el, p, e, t) => {
+      t.dispatchEvent(new CustomEvent(p, { bubbles: true, detail: { source: el } }));
+    })
+    .add('emit', (el, p, e, t) => {   // alias for dispatch
+      t.dispatchEvent(new CustomEvent(p, { bubbles: true, detail: { source: el } }));
+    })
+    // LocalStorage
+    .add('store',        (el, p) => {
+      const [key, ...val] = p.split(':');
+      localStorage.setItem(key, val.join(':') || el.value || el.textContent.trim());
+    })
+    .add('restore',      (el, p, e, t) => {
+      const val = localStorage.getItem(p);
+      if (val !== null) t.value !== undefined ? (t.value = val) : (t.textContent = val);
+    })
+    // Network
+    .add('fetch', async (el, param, e, target) => {
+      e?.preventDefault?.();
+      const method   = (el.dataset.stickMethod  || 'GET').toUpperCase();
+      const swapMode =  el.dataset.stickSwap    || 'innerHTML';
+      const loading  =  el.dataset.stickLoading || '';
+      const errorSel =  el.dataset.stickError;
+      const errorEl  =  errorSel ? document.querySelector(errorSel) : null;
+      const prev     = el.textContent;
+
+      let headers = {};
+      try { headers = JSON.parse(el.dataset.stickHeaders || '{}'); } catch (_) {}
+
+      if (loading) el.textContent = loading;
+      el.setAttribute('aria-busy', 'true');
+      if (errorEl) errorEl.hidden = true;
+
+      try {
+        let body;
+        if (method !== 'GET') {
+          const jsonTpl = el.dataset.stickJson;
+          if (jsonTpl) {
+            body = interpolate(jsonTpl, el);
+            headers['Content-Type'] = headers['Content-Type'] || 'application/json';
+          } else {
+            body = new FormData(el.closest('form') || el);
+          }
+        }
+        const res  = await fetch(param, { method, body, headers });
+        if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+        const text = await res.text();
+        swap(target, text, swapMode);
+        Stick.init(target);
+      } catch (err) {
+        console.error('[Stick:fetch]', err);
+        if (errorEl) { errorEl.textContent = err.message; errorEl.hidden = false; }
+        else target.textContent = `Error: ${err.message}`;
+      } finally {
+        if (loading) el.textContent = prev;
+        el.removeAttribute('aria-busy');
+      }
+    });
+
+  // ── auto-init ─────────────────────────────────────────────────────
+
+  if (typeof document !== 'undefined') {
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', () => { Stick.init(); Stick.observe(); });
+    } else {
+      Stick.init();
+      Stick.observe();
+    }
+  }
+
+  return Stick;
+}));