neiki-gallery 1.0.0

package/dist/neiki-gallery.js

@@ -0,0 +1,955 @@
+/*!
+ * Neiki Gallery v1.0.0
+ * A vanilla JavaScript image gallery / lightbox library.
+ * No dependencies. No frameworks.
+ *
+ * Usage:
+ *   Auto-init: <div data-neiki-gallery>...</div>
+ *   Manual:    new NeikiGallery('#my-gallery', { ... });
+ *
+ * License: MIT
+ */
+(function (root, factory) {
+  if (typeof define === 'function' && define.amd) {
+    define([], factory);
+  } else if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.NeikiGallery = factory();
+  }
+})(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  /* ========================================================================
+     Helpers
+     ======================================================================== */
+
+  var uid = 0;
+
+  /**
+   * Generate a unique ID for each gallery instance.
+   */
+  function nextId() {
+    return ++uid;
+  }
+
+  /**
+   * Merge defaults with user options (shallow).
+   */
+  function mergeOptions(defaults, opts) {
+    var result = {};
+    for (var key in defaults) {
+      if (defaults.hasOwnProperty(key)) {
+        result[key] = defaults[key];
+      }
+    }
+    if (opts) {
+      for (var key in opts) {
+        if (opts.hasOwnProperty(key)) {
+          result[key] = opts[key];
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Query helper.
+   */
+  function $(selector, ctx) {
+    return (ctx || document).querySelector(selector);
+  }
+
+  function $$(selector, ctx) {
+    return Array.prototype.slice.call((ctx || document).querySelectorAll(selector));
+  }
+
+  /**
+   * Create an element with optional class, attributes, and innerHTML.
+   */
+  function createElement(tag, className, attrs, html) {
+    var el = document.createElement(tag);
+    if (className) el.className = className;
+    if (attrs) {
+      for (var k in attrs) {
+        if (attrs.hasOwnProperty(k)) el.setAttribute(k, attrs[k]);
+      }
+    }
+    if (html) el.innerHTML = html;
+    return el;
+  }
+
+  /* ========================================================================
+     SVG Icons
+     ======================================================================== */
+
+  var ICONS = {
+    close: '<svg viewBox="0 0 24 24"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>',
+    prev: '<svg viewBox="0 0 24 24"><polyline points="15 18 9 12 15 6"/></svg>',
+    next: '<svg viewBox="0 0 24 24"><polyline points="9 6 15 12 9 18"/></svg>',
+    fullscreen: '<svg viewBox="0 0 24 24"><polyline points="15 3 21 3 21 9"/><polyline points="9 21 3 21 3 15"/><line x1="21" y1="3" x2="14" y2="10"/><line x1="3" y1="21" x2="10" y2="14"/></svg>',
+    exitFullscreen: '<svg viewBox="0 0 24 24"><polyline points="4 14 10 14 10 20"/><polyline points="20 10 14 10 14 4"/><line x1="14" y1="10" x2="21" y2="3"/><line x1="3" y1="21" x2="10" y2="14"/></svg>'
+  };
+
+  /* ========================================================================
+     Default Options
+     ======================================================================== */
+
+  var DEFAULTS = {
+    layout: 'masonry',       // 'masonry' | 'grid'
+    loop: false,             // infinite loop navigation
+    thumbnails: true,        // show thumbnail strip in lightbox
+    zoom: true,              // allow zoom on click in lightbox
+    fullscreen: true,        // show fullscreen button
+    transition: 'fade',      // 'fade' | 'slide'
+    theme: 'dark',           // 'dark' | 'light'
+    hashNavigation: true,    // deep linking via URL hash
+    counter: true,           // show image counter
+    captions: true,          // show captions
+    preload: 1,              // how many adjacent images to preload
+    lazyLoad: true           // lazy load grid thumbnails
+  };
+
+  /* ========================================================================
+     NeikiGallery Constructor
+     ======================================================================== */
+
+  function NeikiGallery(selectorOrElement, options) {
+    // Allow omitting `new`
+    if (!(this instanceof NeikiGallery)) {
+      return new NeikiGallery(selectorOrElement, options);
+    }
+
+    this._id = nextId();
+    this._events = {};
+    this._isOpen = false;
+    this._currentIndex = 0;
+    this._isZoomed = false;
+    this._isFullscreen = false;
+    this._destroyed = false;
+    this._boundHandlers = {};
+
+    // Resolve the container element
+    if (typeof selectorOrElement === 'string') {
+      this._container = $(selectorOrElement);
+    } else {
+      this._container = selectorOrElement;
+    }
+
+    if (!this._container) {
+      console.warn('NeikiGallery: Container not found for selector "' + selectorOrElement + '"');
+      return;
+    }
+
+    // Read data-* attributes from the container and merge with JS options
+    var dataOpts = this._readDataAttributes();
+    this._options = mergeOptions(DEFAULTS, mergeOptions(dataOpts, options));
+
+    // Parse items from DOM
+    this._items = this._parseItems();
+
+    if (this._items.length === 0) {
+      console.warn('NeikiGallery: No items found in container.');
+      return;
+    }
+
+    // Initialize
+    this._setupGrid();
+    this._setupLazyLoad();
+    this._buildLightbox();
+    this._bindEvents();
+    this._checkHash();
+  }
+
+  /* ========================================================================
+     Prototype — Private Methods
+     ======================================================================== */
+
+  NeikiGallery.prototype._readDataAttributes = function () {
+    var c = this._container;
+    var opts = {};
+    if (c.hasAttribute('data-layout')) opts.layout = c.getAttribute('data-layout');
+    if (c.hasAttribute('data-theme')) opts.theme = c.getAttribute('data-theme');
+    if (c.hasAttribute('data-loop')) opts.loop = c.getAttribute('data-loop') !== 'false';
+    if (c.hasAttribute('data-thumbnails')) opts.thumbnails = c.getAttribute('data-thumbnails') !== 'false';
+    if (c.hasAttribute('data-zoom')) opts.zoom = c.getAttribute('data-zoom') !== 'false';
+    if (c.hasAttribute('data-fullscreen')) opts.fullscreen = c.getAttribute('data-fullscreen') !== 'false';
+    if (c.hasAttribute('data-transition')) opts.transition = c.getAttribute('data-transition');
+    if (c.hasAttribute('data-hash-navigation')) opts.hashNavigation = c.getAttribute('data-hash-navigation') !== 'false';
+    return opts;
+  };
+
+  /**
+   * Parse <a><img></a> children into an items array.
+   */
+  NeikiGallery.prototype._parseItems = function () {
+    var anchors = $$(':scope > a', this._container);
+    var items = [];
+    for (var i = 0; i < anchors.length; i++) {
+      var a = anchors[i];
+      var img = $('img', a);
+      items.push({
+        src: a.getAttribute('href') || (img ? img.getAttribute('src') : ''),
+        thumb: img ? (img.getAttribute('data-src') || img.getAttribute('src')) : '',
+        caption: a.getAttribute('data-caption') || (img ? img.getAttribute('alt') : '') || '',
+        element: a,
+        img: img
+      });
+      // Prevent default link behaviour
+      a.addEventListener('click', function (e) { e.preventDefault(); });
+    }
+    return items;
+  };
+
+  /**
+   * Apply the grid layout class.
+   */
+  NeikiGallery.prototype._setupGrid = function () {
+    this._container.classList.add('neiki-gallery');
+    if (this._options.layout === 'grid') {
+      this._container.classList.add('neiki-gallery--grid');
+      this._container.classList.remove('neiki-gallery--masonry');
+    } else {
+      this._container.classList.add('neiki-gallery--masonry');
+      this._container.classList.remove('neiki-gallery--grid');
+    }
+    // Theme
+    if (this._options.theme) {
+      this._container.setAttribute('data-theme', this._options.theme);
+    }
+  };
+
+  /**
+   * Lazy load grid thumbnails via IntersectionObserver.
+   */
+  NeikiGallery.prototype._setupLazyLoad = function () {
+    var self = this;
+    if (!this._options.lazyLoad || !('IntersectionObserver' in window)) {
+      // Fallback: load all immediately
+      this._items.forEach(function (item) {
+        if (item.img) item.img.classList.add('neiki-loaded');
+      });
+      return;
+    }
+
+    this._observer = new IntersectionObserver(function (entries) {
+      entries.forEach(function (entry) {
+        if (entry.isIntersecting) {
+          var img = entry.target;
+          var lazySrc = img.getAttribute('data-src');
+          if (lazySrc) {
+            img.src = lazySrc;
+            img.removeAttribute('data-src');
+          }
+          img.addEventListener('load', function () {
+            img.classList.add('neiki-loaded');
+          });
+          // Already cached
+          if (img.complete && img.naturalWidth) {
+            img.classList.add('neiki-loaded');
+          }
+          self._observer.unobserve(img);
+        }
+      });
+    }, { rootMargin: '200px' });
+
+    this._items.forEach(function (item) {
+      if (item.img) {
+        // If img already has a real src and is loaded, mark it
+        if (item.img.complete && item.img.naturalWidth) {
+          item.img.classList.add('neiki-loaded');
+        } else {
+          self._observer.observe(item.img);
+          // Also listen for load in case it's not lazy
+          item.img.addEventListener('load', function () {
+            item.img.classList.add('neiki-loaded');
+          });
+        }
+      }
+    });
+  };
+
+  /* ========================================================================
+     Lightbox — Build DOM
+     ======================================================================== */
+
+  NeikiGallery.prototype._buildLightbox = function () {
+    var opts = this._options;
+
+    // Overlay
+    this._lightbox = createElement('div', 'neiki-lightbox neiki-lightbox--' + opts.transition, {
+      role: 'dialog',
+      'aria-modal': 'true',
+      'aria-label': 'Image lightbox',
+      tabindex: '-1'
+    });
+
+    // Apply theme
+    if (opts.theme) {
+      this._lightbox.setAttribute('data-theme', opts.theme);
+    }
+
+    // Top bar (counter)
+    if (opts.counter) {
+      this._topbar = createElement('div', 'neiki-lightbox__topbar');
+      this._counter = createElement('span', 'neiki-lightbox__counter', { 'aria-live': 'polite' });
+      this._topbar.appendChild(this._counter);
+      this._lightbox.appendChild(this._topbar);
+    }
+
+    // Close button
+    this._closeBtn = createElement('button', 'neiki-lightbox__btn neiki-lightbox__close', {
+      'aria-label': 'Close lightbox',
+      type: 'button'
+    }, ICONS.close);
+    this._lightbox.appendChild(this._closeBtn);
+
+    // Fullscreen button
+    if (opts.fullscreen) {
+      this._fsBtn = createElement('button', 'neiki-lightbox__btn neiki-lightbox__fullscreen', {
+        'aria-label': 'Toggle fullscreen',
+        type: 'button'
+      }, ICONS.fullscreen);
+      this._lightbox.appendChild(this._fsBtn);
+    }
+
+    // Prev / Next
+    this._prevBtn = createElement('button', 'neiki-lightbox__btn neiki-lightbox__prev', {
+      'aria-label': 'Previous image',
+      type: 'button'
+    }, ICONS.prev);
+    this._nextBtn = createElement('button', 'neiki-lightbox__btn neiki-lightbox__next', {
+      'aria-label': 'Next image',
+      type: 'button'
+    }, ICONS.next);
+
+    // Stage (image area)
+    this._stage = createElement('div', 'neiki-lightbox__stage');
+
+    // Slide wrapper (for slide transition)
+    this._slideWrapper = createElement('div', 'neiki-lightbox__slide-wrapper');
+
+    // Spinner
+    this._spinner = createElement('div', 'neiki-lightbox__spinner neiki-hidden');
+
+    // Image
+    this._image = createElement('img', 'neiki-lightbox__image', {
+      alt: '',
+      draggable: 'false'
+    });
+
+    this._slideWrapper.appendChild(this._spinner);
+    this._slideWrapper.appendChild(this._image);
+    this._stage.appendChild(this._prevBtn);
+    this._stage.appendChild(this._slideWrapper);
+    this._stage.appendChild(this._nextBtn);
+    this._lightbox.appendChild(this._stage);
+
+    // Caption
+    if (opts.captions) {
+      this._caption = createElement('div', 'neiki-lightbox__caption', { 'aria-live': 'polite' });
+      this._lightbox.appendChild(this._caption);
+    }
+
+    // Thumbnail strip
+    if (opts.thumbnails) {
+      this._thumbsContainer = createElement('div', 'neiki-lightbox__thumbs', {
+        role: 'listbox',
+        'aria-label': 'Image thumbnails'
+      });
+      this._thumbButtons = [];
+      for (var i = 0; i < this._items.length; i++) {
+        var btn = createElement('button', 'neiki-lightbox__thumb', {
+          type: 'button',
+          role: 'option',
+          'aria-label': 'View image ' + (i + 1)
+        });
+        var thumbImg = createElement('img', '', {
+          src: this._items[i].thumb,
+          alt: this._items[i].caption || 'Thumbnail ' + (i + 1),
+          draggable: 'false'
+        });
+        btn.appendChild(thumbImg);
+        this._thumbButtons.push(btn);
+        this._thumbsContainer.appendChild(btn);
+      }
+      this._lightbox.appendChild(this._thumbsContainer);
+    }
+
+    document.body.appendChild(this._lightbox);
+  };
+
+  /* ========================================================================
+     Lightbox — Bind Events
+     ======================================================================== */
+
+  NeikiGallery.prototype._bindEvents = function () {
+    var self = this;
+
+    // Grid item clicks
+    this._items.forEach(function (item, index) {
+      item.element.addEventListener('click', function (e) {
+        e.preventDefault();
+        self.open(index);
+      });
+    });
+
+    // Close button
+    this._closeBtn.addEventListener('click', function () { self.close(); });
+
+    // Nav buttons
+    this._prevBtn.addEventListener('click', function (e) { e.stopPropagation(); self.prev(); });
+    this._nextBtn.addEventListener('click', function (e) { e.stopPropagation(); self.next(); });
+
+    // Fullscreen
+    if (this._fsBtn) {
+      this._fsBtn.addEventListener('click', function (e) {
+        e.stopPropagation();
+        self._toggleFullscreen();
+      });
+    }
+
+    // Zoom on image click
+    if (this._options.zoom) {
+      this._image.addEventListener('click', function (e) {
+        e.stopPropagation();
+        self._toggleZoom();
+      });
+    }
+
+    // Thumbnail clicks
+    if (this._thumbButtons) {
+      this._thumbButtons.forEach(function (btn, idx) {
+        btn.addEventListener('click', function () { self._goTo(idx); });
+      });
+    }
+
+    // Click on stage background to close (but not on image / buttons)
+    this._stage.addEventListener('click', function (e) {
+      if (e.target === self._stage || e.target === self._slideWrapper) {
+        self.close();
+      }
+    });
+
+    // Keyboard
+    this._boundHandlers.keydown = function (e) { self._onKeyDown(e); };
+    document.addEventListener('keydown', this._boundHandlers.keydown);
+
+    // Touch / Swipe
+    this._setupTouch();
+
+    // Hash change
+    if (this._options.hashNavigation) {
+      this._boundHandlers.hashchange = function () { self._onHashChange(); };
+      window.addEventListener('hashchange', this._boundHandlers.hashchange);
+    }
+
+    // Fullscreen change
+    this._boundHandlers.fullscreenchange = function () { self._onFullscreenChange(); };
+    document.addEventListener('fullscreenchange', this._boundHandlers.fullscreenchange);
+    document.addEventListener('webkitfullscreenchange', this._boundHandlers.fullscreenchange);
+  };
+
+  /**
+   * Keyboard handler.
+   */
+  NeikiGallery.prototype._onKeyDown = function (e) {
+    if (!this._isOpen) return;
+
+    switch (e.key) {
+      case 'Escape':
+        e.preventDefault();
+        this.close();
+        break;
+      case 'ArrowLeft':
+        e.preventDefault();
+        this.prev();
+        break;
+      case 'ArrowRight':
+        e.preventDefault();
+        this.next();
+        break;
+      case 'Home':
+        e.preventDefault();
+        this._goTo(0);
+        break;
+      case 'End':
+        e.preventDefault();
+        this._goTo(this._items.length - 1);
+        break;
+      case 'f':
+        e.preventDefault();
+        this._toggleFullscreen();
+        break;
+    }
+  };
+
+  /**
+   * Touch swipe support (pointer events with fallback to touch events).
+   */
+  NeikiGallery.prototype._setupTouch = function () {
+    var self = this;
+    var startX = 0;
+    var startY = 0;
+    var distX = 0;
+    var tracking = false;
+    var threshold = 50;
+
+    function onStart(e) {
+      if (!self._isOpen || self._isZoomed) return;
+      var point = e.touches ? e.touches[0] : e;
+      startX = point.clientX;
+      startY = point.clientY;
+      distX = 0;
+      tracking = true;
+    }
+
+    function onMove(e) {
+      if (!tracking) return;
+      var point = e.touches ? e.touches[0] : e;
+      distX = point.clientX - startX;
+      var distY = point.clientY - startY;
+      // If horizontal swipe is dominant, prevent scroll
+      if (Math.abs(distX) > Math.abs(distY) && Math.abs(distX) > 10) {
+        e.preventDefault();
+      }
+    }
+
+    function onEnd() {
+      if (!tracking) return;
+      tracking = false;
+      if (distX > threshold) {
+        self.prev();
+      } else if (distX < -threshold) {
+        self.next();
+      }
+    }
+
+    this._stage.addEventListener('touchstart', onStart, { passive: true });
+    this._stage.addEventListener('touchmove', onMove, { passive: false });
+    this._stage.addEventListener('touchend', onEnd, { passive: true });
+
+    // Store refs for cleanup
+    this._boundHandlers.touchstart = onStart;
+    this._boundHandlers.touchmove = onMove;
+    this._boundHandlers.touchend = onEnd;
+  };
+
+  /* ========================================================================
+     Lightbox — Navigation Logic
+     ======================================================================== */
+
+  NeikiGallery.prototype._goTo = function (index, skipHash) {
+    if (this._destroyed) return;
+
+    var len = this._items.length;
+
+    // Handle loop / bounds
+    if (this._options.loop) {
+      index = ((index % len) + len) % len;
+    } else {
+      if (index < 0) index = 0;
+      if (index >= len) index = len - 1;
+    }
+
+    if (index === this._currentIndex && this._isOpen && this._image.src) {
+      // Already showing this image
+      return;
+    }
+
+    var prevIndex = this._currentIndex;
+    this._currentIndex = index;
+    var item = this._items[index];
+
+    // Reset zoom
+    if (this._isZoomed) this._toggleZoom();
+
+    // Update nav button visibility when not looping
+    this._updateNavButtons();
+
+    // Show spinner
+    this._spinner.classList.remove('neiki-hidden');
+
+    // Load image
+    var self = this;
+    var img = this._image;
+
+    // Transition class for animation direction (slide)
+    if (this._options.transition === 'slide') {
+      var direction = index > prevIndex ? 1 : -1;
+      // If looping from last to first or vice versa, determine visually correct direction
+      if (this._options.loop) {
+        if (prevIndex === len - 1 && index === 0) direction = 1;
+        if (prevIndex === 0 && index === len - 1) direction = -1;
+      }
+      this._slideWrapper.style.transform = 'translateX(' + (-direction * 40) + 'px)';
+      img.style.opacity = '0';
+      requestAnimationFrame(function () {
+        requestAnimationFrame(function () {
+          self._slideWrapper.style.transform = 'translateX(0)';
+          img.style.opacity = '1';
+        });
+      });
+    } else {
+      // Fade
+      img.classList.add('neiki-entering');
+      img.classList.remove('neiki-active');
+    }
+
+    // Set src
+    img.setAttribute('alt', item.caption || '');
+
+    // Preload into a temp image to catch load event correctly
+    var tempImg = new Image();
+    tempImg.onload = function () {
+      img.src = item.src;
+      self._spinner.classList.add('neiki-hidden');
+      if (self._options.transition === 'fade') {
+        // Small delay to trigger CSS transition
+        requestAnimationFrame(function () {
+          img.classList.remove('neiki-entering');
+          img.classList.add('neiki-active');
+        });
+      }
+    };
+    tempImg.onerror = function () {
+      img.src = item.src; // show broken image
+      self._spinner.classList.add('neiki-hidden');
+      if (self._options.transition === 'fade') {
+        requestAnimationFrame(function () {
+          img.classList.remove('neiki-entering');
+          img.classList.add('neiki-active');
+        });
+      }
+    };
+    tempImg.src = item.src;
+
+    // If already cached, fire immediately
+    if (tempImg.complete) {
+      img.src = item.src;
+      self._spinner.classList.add('neiki-hidden');
+      if (self._options.transition === 'fade') {
+        requestAnimationFrame(function () {
+          img.classList.remove('neiki-entering');
+          img.classList.add('neiki-active');
+        });
+      }
+    }
+
+    // Counter
+    if (this._counter) {
+      this._counter.textContent = (index + 1) + ' / ' + len;
+    }
+
+    // Caption
+    if (this._caption) {
+      this._caption.textContent = item.caption || '';
+    }
+
+    // Active thumbnail
+    if (this._thumbButtons) {
+      this._thumbButtons.forEach(function (btn, idx) {
+        btn.classList.toggle('neiki-thumb--active', idx === index);
+        btn.setAttribute('aria-selected', idx === index ? 'true' : 'false');
+      });
+      // Scroll active thumbnail into view
+      var activeThumb = this._thumbButtons[index];
+      if (activeThumb && this._thumbsContainer) {
+        activeThumb.scrollIntoView({ inline: 'center', block: 'nearest', behavior: 'smooth' });
+      }
+    }
+
+    // Hash
+    if (this._options.hashNavigation && !skipHash) {
+      this._setHash(index);
+    }
+
+    // Preload adjacent
+    this._preloadAdjacent(index);
+
+    // Fire event
+    this._emit('change', index);
+  };
+
+  NeikiGallery.prototype._updateNavButtons = function () {
+    if (this._options.loop) {
+      this._prevBtn.style.display = '';
+      this._nextBtn.style.display = '';
+      return;
+    }
+    this._prevBtn.style.display = this._currentIndex <= 0 ? 'none' : '';
+    this._nextBtn.style.display = this._currentIndex >= this._items.length - 1 ? 'none' : '';
+  };
+
+  /**
+   * Preload adjacent images.
+   */
+  NeikiGallery.prototype._preloadAdjacent = function (index) {
+    var count = this._options.preload || 1;
+    var len = this._items.length;
+    for (var i = 1; i <= count; i++) {
+      var nextIdx = (index + i) % len;
+      var prevIdx = ((index - i) % len + len) % len;
+      if (this._items[nextIdx]) new Image().src = this._items[nextIdx].src;
+      if (this._items[prevIdx]) new Image().src = this._items[prevIdx].src;
+    }
+  };
+
+  /* ========================================================================
+     Zoom
+     ======================================================================== */
+
+  NeikiGallery.prototype._toggleZoom = function () {
+    if (!this._options.zoom) return;
+    this._isZoomed = !this._isZoomed;
+    this._image.classList.toggle('neiki-zoomed', this._isZoomed);
+  };
+
+  /* ========================================================================
+     Fullscreen
+     ======================================================================== */
+
+  NeikiGallery.prototype._toggleFullscreen = function () {
+    if (!this._options.fullscreen) return;
+
+    if (!document.fullscreenElement && !document.webkitFullscreenElement) {
+      var el = this._lightbox;
+      if (el.requestFullscreen) {
+        el.requestFullscreen();
+      } else if (el.webkitRequestFullscreen) {
+        el.webkitRequestFullscreen();
+      }
+    } else {
+      if (document.exitFullscreen) {
+        document.exitFullscreen();
+      } else if (document.webkitExitFullscreen) {
+        document.webkitExitFullscreen();
+      }
+    }
+  };
+
+  NeikiGallery.prototype._onFullscreenChange = function () {
+    this._isFullscreen = !!(document.fullscreenElement || document.webkitFullscreenElement);
+    if (this._fsBtn) {
+      this._fsBtn.innerHTML = this._isFullscreen ? ICONS.exitFullscreen : ICONS.fullscreen;
+    }
+  };
+
+  /* ========================================================================
+     Hash Navigation
+     ======================================================================== */
+
+  NeikiGallery.prototype._setHash = function (index) {
+    if (typeof index === 'number' && this._isOpen) {
+      history.replaceState(null, '', '#neiki-' + this._id + '=' + (index + 1));
+    }
+  };
+
+  NeikiGallery.prototype._clearHash = function () {
+    if (window.location.hash.indexOf('#neiki-' + this._id + '=') === 0) {
+      history.replaceState(null, '', window.location.pathname + window.location.search);
+    }
+  };
+
+  NeikiGallery.prototype._checkHash = function () {
+    if (!this._options.hashNavigation) return;
+    var hash = window.location.hash;
+    var prefix = '#neiki-' + this._id + '=';
+    if (hash.indexOf(prefix) === 0) {
+      var idx = parseInt(hash.substring(prefix.length), 10);
+      if (!isNaN(idx) && idx >= 1 && idx <= this._items.length) {
+        this.open(idx - 1);
+      }
+    }
+  };
+
+  NeikiGallery.prototype._onHashChange = function () {
+    this._checkHash();
+  };
+
+  /* ========================================================================
+     Event Emitter
+     ======================================================================== */
+
+  NeikiGallery.prototype._emit = function (event, data) {
+    var listeners = this._events[event];
+    if (listeners) {
+      listeners.forEach(function (fn) { fn(data); });
+    }
+  };
+
+  /* ========================================================================
+     Public API
+     ======================================================================== */
+
+  /**
+   * Open the lightbox at a given index.
+   */
+  NeikiGallery.prototype.open = function (index) {
+    if (this._destroyed) return;
+    if (typeof index !== 'number') index = 0;
+    if (index < 0) index = 0;
+    if (index >= this._items.length) index = this._items.length - 1;
+
+    this._isOpen = true;
+
+    // Prevent body scroll
+    document.body.style.overflow = 'hidden';
+
+    // Show overlay
+    this._lightbox.classList.add('neiki-lightbox--visible');
+
+    // Focus the lightbox for keyboard events
+    this._lightbox.focus();
+
+    // Force a fresh load (reset current to -1 so _goTo actually proceeds)
+    this._currentIndex = -1;
+    this._goTo(index);
+
+    this._emit('open', index);
+  };
+
+  /**
+   * Close the lightbox.
+   */
+  NeikiGallery.prototype.close = function () {
+    if (!this._isOpen) return;
+    this._isOpen = false;
+
+    // Exit fullscreen if active
+    if (this._isFullscreen) {
+      if (document.exitFullscreen) document.exitFullscreen();
+      else if (document.webkitExitFullscreen) document.webkitExitFullscreen();
+    }
+
+    // Reset zoom
+    if (this._isZoomed) {
+      this._isZoomed = false;
+      this._image.classList.remove('neiki-zoomed');
+    }
+
+    // Restore body scroll
+    document.body.style.overflow = '';
+
+    // Hide overlay
+    this._lightbox.classList.remove('neiki-lightbox--visible');
+
+    // Clear hash
+    if (this._options.hashNavigation) {
+      this._clearHash();
+    }
+
+    this._emit('close');
+  };
+
+  /**
+   * Go to the next image.
+   */
+  NeikiGallery.prototype.next = function () {
+    this._goTo(this._currentIndex + 1);
+  };
+
+  /**
+   * Go to the previous image.
+   */
+  NeikiGallery.prototype.prev = function () {
+    this._goTo(this._currentIndex - 1);
+  };
+
+  /**
+   * Register an event listener.
+   */
+  NeikiGallery.prototype.on = function (event, callback) {
+    if (!this._events[event]) this._events[event] = [];
+    this._events[event].push(callback);
+    return this;
+  };
+
+  /**
+   * Remove an event listener.
+   */
+  NeikiGallery.prototype.off = function (event, callback) {
+    var listeners = this._events[event];
+    if (listeners) {
+      this._events[event] = listeners.filter(function (fn) { return fn !== callback; });
+    }
+    return this;
+  };
+
+  /**
+   * Destroy the gallery instance — remove all DOM, listeners, observers.
+   */
+  NeikiGallery.prototype.destroy = function () {
+    if (this._destroyed) return;
+    this._destroyed = true;
+
+    // Close if open
+    if (this._isOpen) this.close();
+
+    // Remove keyboard listener
+    if (this._boundHandlers.keydown) {
+      document.removeEventListener('keydown', this._boundHandlers.keydown);
+    }
+
+    // Remove hashchange listener
+    if (this._boundHandlers.hashchange) {
+      window.removeEventListener('hashchange', this._boundHandlers.hashchange);
+    }
+
+    // Remove fullscreen listener
+    if (this._boundHandlers.fullscreenchange) {
+      document.removeEventListener('fullscreenchange', this._boundHandlers.fullscreenchange);
+      document.removeEventListener('webkitfullscreenchange', this._boundHandlers.fullscreenchange);
+    }
+
+    // Remove touch listeners
+    if (this._boundHandlers.touchstart) {
+      this._stage.removeEventListener('touchstart', this._boundHandlers.touchstart);
+      this._stage.removeEventListener('touchmove', this._boundHandlers.touchmove);
+      this._stage.removeEventListener('touchend', this._boundHandlers.touchend);
+    }
+
+    // Disconnect intersection observer
+    if (this._observer) {
+      this._observer.disconnect();
+      this._observer = null;
+    }
+
+    // Remove lightbox DOM
+    if (this._lightbox && this._lightbox.parentNode) {
+      this._lightbox.parentNode.removeChild(this._lightbox);
+    }
+
+    // Remove grid classes
+    this._container.classList.remove('neiki-gallery', 'neiki-gallery--masonry', 'neiki-gallery--grid');
+
+    // Clear event listeners
+    this._events = {};
+  };
+
+  /* ========================================================================
+     Auto-Init
+     ======================================================================== */
+
+  function autoInit() {
+    var galleries = $$('[data-neiki-gallery]');
+    galleries.forEach(function (el) {
+      // Don't double-init
+      if (el._neikiGallery) return;
+      el._neikiGallery = new NeikiGallery(el);
+    });
+  }
+
+  // Auto-init when DOM is ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', autoInit);
+  } else {
+    // DOM already loaded (script at bottom or defer)
+    autoInit();
+  }
+
+  // Expose auto-init for dynamic content
+  NeikiGallery.autoInit = autoInit;
+
+  return NeikiGallery;
+});