neiki-gallery 2.0.0 → 3.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 neikiri
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 neikiri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,7 +10,7 @@
   <img src="https://img.shields.io/badge/css-%23663399.svg?style=for-the-badge&logo=css&logoColor=white" alt="CSS">
   <br>
   <img src="https://img.shields.io/badge/License-MIT-2563EB?style=for-the-badge&logo=open-source-initiative&logoColor=white&labelColor=000F15&logoWidth=20" alt="License">
-  <img src="https://img.shields.io/badge/Version-2.0.0-2563EB?style=for-the-badge&logo=semantic-release&logoColor=white&labelColor=000F15&logoWidth=20" alt="Version">
+  <img src="https://img.shields.io/badge/Version-3.0.0-2563EB?style=for-the-badge&logo=semantic-release&logoColor=white&labelColor=000F15&logoWidth=20" alt="Version">
 </p>
 
 <p align="center">
@@ -55,18 +55,43 @@
 - **Multiple instances** — independent galleries on one page
 - **Dark & light themes** — CSS custom properties + accent color system (`--neiki-accent`)
 - **Accessibility** — ARIA attributes, focus management, `prefers-reduced-motion`
-- **Event system** — `open`, `close`, `change`, `filter`, `select`, `slideshowStart`, `slideshowStop`
-- **Cross-browser** — Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
+- **Event system** — `open`, `close`, `change`, `filter`, `select`, `slideshowStart`, `slideshowStop`, `favorite`, `unfavorite`, `infoOpen`, `infoClose`, `print`, `editorOpen`, `editorExport`, `annotateOpen`, `annotateExport`, `append`, `remove`
+- **Blurhash placeholders** — `data-blurhash` attribute decoded into blurred preview (replaces shimmer)
+- **Story mode** — Instagram-like vertical fullscreen viewer with progress bars and tap navigation
+- **Picture-in-Picture** — minimize lightbox to a resizable corner window
+- **Image focus point** — `data-focus="0.3 0.7"` controls `object-position` for smart cropping
+- **EXIF overlay** — camera model, focal length, aperture, shutter speed, ISO from JPEG binary
+- **Color palette extraction** — k-means quantized 5-color palette strip in lightbox
+- **Backdrop tint** — overlay adapts to dominant color of current image
+- **FLIP morph transition** — smooth thumbnail-to-lightbox animation
+- **Virtual scrolling** — `content-visibility` virtualization for large galleries (50+ items)
+- **Drag & drop reorder** — HTML5 drag to reorder grid items
+- **Aspect-ratio skeleton** — `data-width`/`data-height` for placeholder sizing
+- **Web Share API** — native mobile sharing with clipboard fallback
+- **Video & embeds** — auto-detect MP4/WebM/Ogg/MOV/M4V, YouTube and Vimeo URLs in lightbox
+- **Plugin system** — `NeikiGallery.registerPlugin()` with `init`/`open`/`change`/`close`/`destroy` lifecycle hooks
+- **Album groups** — `data-group="album"` links galleries; navigation traverses across all
+- **Favorites** — heart button + localStorage persistence + `B` key shortcut
+- **Info panel** — slide-out sidebar with metadata, EXIF, source URL (`I` key)
+- **Image editor** — rotate / flip / export to PNG via `<canvas>`
+- **Annotation layer** — freehand drawing with color picker, brush size, undo, clear, export
+- **Print** — print current image with caption (`P` key)
+- **Right-click context menu** — open original, copy link, download, share, print, favorite
+- **Infinite scroll** — `loadMore` callback + `append()` / `remove()` API
+- **Keyboard shortcuts overlay** — press `?` to view all shortcuts
+- **System theme detection** — `theme: 'system'` follows OS `prefers-color-scheme`
+- **Kenburns slideshow** — slow zoom-and-pan animation per slide
+- **Configurable counter** — `counterFormat` with `{current}`/`{total}`/`{percent}` tokens
+- **Cross-browser** — Chrome 80+, Firefox 75+, Safari 14+, Edge 80+
 
 ## 🚀 Quick Start
 
 ### CDN (Recommended)
 
-Add these two lines to your HTML — that's all you need:
+Add this single line to your HTML — that's all you need (CSS is included automatically):
 
 ```html
-<link rel="stylesheet" href="http://cdn.neiki.eu/neiki-gallery/neiki-gallery.min.css">
-<script src="http://cdn.neiki.eu/neiki-gallery/neiki-gallery.min.js"></script>
+<script src="https://cdn.neiki.eu/neiki-gallery/neiki-gallery.min.js"></script>
 ```
 
 Then create your gallery markup:
@@ -84,16 +109,15 @@ Then create your gallery markup:
 
 That's it — galleries with `data-neiki-gallery` auto-initialize on page load.
 
-> **Unminified files** are also available if you need them for debugging:
+> **Unminified files** are also available if you need them for debugging (require separate CSS):
 > ```
-> http://cdn.neiki.eu/neiki-gallery/neiki-gallery.js
-> http://cdn.neiki.eu/neiki-gallery/neiki-gallery.css
+> https://cdn.neiki.eu/neiki-gallery/neiki-gallery.js
+> https://cdn.neiki.eu/neiki-gallery/neiki-gallery.css
 > ```
 
 > **Pin a specific version** to avoid unexpected changes:
 > ```
-> http://cdn.neiki.eu/neiki-gallery/2.0.0/neiki-gallery.min.js
-> http://cdn.neiki.eu/neiki-gallery/2.0.0/neiki-gallery.min.css
+> https://cdn.neiki.eu/neiki-gallery/3.0.0/neiki-gallery.min.js
 > ```
 
 ### Self-Hosting (Local)
@@ -104,20 +128,26 @@ Download or clone the repository from GitHub:
 git clone https://github.com/neikiri/neiki-gallery.git
 ```
 
-Copy the files from the `dist/` folder into your project and link them directly:
+For production, you only need one file — CSS is already included:
 
 ```html
-<link rel="stylesheet" href="path/to/neiki-gallery.min.css">
 <script src="path/to/neiki-gallery.min.js"></script>
 ```
 
-The `dist/` folder contains both minified and unminified versions:
+For development / debugging, use the unminified versions (requires separate CSS):
+
+```html
+<link rel="stylesheet" href="path/to/neiki-gallery.css">
+<script src="path/to/neiki-gallery.js"></script>
+```
+
+The `dist/` folder contains:
 
 | File | Description |
 |------|-------------|
-| `neiki-gallery.min.js` | Minified JS (production) |
-| `neiki-gallery.min.css` | Minified CSS (production) |
-| `neiki-gallery.js` | Full JS (development / debugging) |
+| `neiki-gallery.min.js` | Minified JS + CSS included (production) |
+| `neiki-gallery.min.css` | Minified CSS standalone (optional) |
+| `neiki-gallery.js` | Full JS without CSS (development / debugging) |
 | `neiki-gallery.css` | Full CSS (development / debugging) |
 
 ### Manual Initialization
@@ -131,14 +161,45 @@ const gallery = new NeikiGallery('#my-gallery', {
   contextualZoom: false,   // zoom to click point
   fullscreen: true,
   transition: 'fade',      // 'fade' | 'slide'
-  theme: 'dark',           // 'dark' | 'light'
+  theme: 'system',         // 'dark' | 'light' | 'system' (auto-detect)  ← v3 default
   hashNavigation: true,
-  stagger: true,           // entrance animation
-  slideshow: false,        // auto-start slideshow on open
-  slideshowInterval: 4000, // ms between slides
-  share: true,             // share/download popup
-  filter: false,           // tag filtering
-  batchSelect: false,      // Shift+click multi-select
+  counter: true,
+  counterFormat: '{current} / {total}',  // v3 — tokens: {current}, {total}, {percent}
+  stagger: true,
+  slideshow: {             // v3 — nested config (boolean still works)
+    interval: 4000,
+    pauseOnHover: true,
+    kenburns: false,
+    direction: 'forward'   // or 'reverse'
+  },
+  share: true,
+  filter: false,
+  batchSelect: false,
+  // v2.1.0
+  focusPoint: true,
+  blurhash: true,
+  exif: false,
+  storyMode: false,
+  pip: false,
+  virtualScroll: false,
+  dragReorder: false,
+  backdropTint: false,
+  morphTransition: false,
+  colorPalette: false,
+  aspectSkeleton: true,
+  // v3.0.0
+  video: true,             // detect MP4 / YouTube / Vimeo
+  plugins: ['watermark', { name: 'analytics', trackingId: 'X' }],
+  group: '',               // album group name (or use data-group)
+  favorites: false,        // ❤️ button + localStorage
+  favoritesKey: '',        // custom localStorage key suffix
+  infoPanel: false,        // sidebar with metadata (I key)
+  contextMenu: false,      // right-click menu on items
+  shortcutsHelp: true,     // overlay on '?' key
+  infiniteScroll: false,   // auto-load more
+  loadMore: null,          // function(currentLength) → array | Promise<array>
+  editor: false,           // crop/rotate/flip toolbar
+  annotate: false          // freehand drawing layer
 });
 ```
 
@@ -149,14 +210,50 @@ const gallery = new NeikiGallery('#my-gallery', {
 ```js
 gallery.open(index);          // Open lightbox at image index
 gallery.close();              // Close lightbox
-gallery.next();               // Go to next image
-gallery.prev();               // Go to previous image
+gallery.next();               // Go to next image (group-aware)
+gallery.prev();               // Go to previous image (group-aware)
 gallery.startSlideshow();     // Start autoplay
 gallery.stopSlideshow();      // Stop autoplay
+gallery.pauseSlideshow();     // v3 — pause without emitting stop
 gallery.toggleSlideshow();    // Toggle autoplay
 gallery.filter('landscape');  // Filter by tag (null = show all)
 gallery.getSelected();        // Get batch-selected items
 gallery.clearSelection();     // Clear batch selection
+gallery.getOrder();           // Get current item order (after drag reorder)
+
+// v3.0.0 — Favorites
+gallery.toggleFavorite();     // Toggle favorite for current image
+gallery.isFavorite(index);    // Check if image is favorited
+gallery.getFavorites();       // Get array of favorited image src URLs
+gallery.clearFavorites();     // Remove all favorites
+
+// v3.0.0 — Info panel / overlays
+gallery.toggleInfoPanel(force);     // Toggle info sidebar (force = bool)
+gallery.toggleShortcutsHelp(force); // Toggle keyboard shortcuts overlay
+
+// v3.0.0 — Editor & annotation
+gallery.openEditor();         // Open crop/rotate/flip editor
+gallery.closeEditor();
+gallery.getEditedBlob();      // Last exported edited image as Blob
+
+gallery.openAnnotate();       // Open drawing layer
+gallery.closeAnnotate();
+gallery.getAnnotatedBlob();
+
+// v3.0.0 — Print & dynamic content
+gallery.print(index);         // Print current or specified image
+gallery.append([{src,...}]);  // Append new items at runtime
+gallery.remove(index);        // Remove item by index
+
+// v3.0.0 — Plugin access
+gallery.plugin('watermark');  // Get plugin instance by name
+
+// v3.0.0 — Event helpers
+gallery.on('change', fn);
+gallery.off('change', fn);    // Remove specific listener
+gallery.off('change');        // Remove all listeners for event
+gallery.once('open', fn);     // Auto-removed after first fire
+
 gallery.destroy();            // Remove gallery, clean up all listeners & DOM
 ```
 
@@ -174,8 +271,75 @@ const slider = NeikiGallery.compare('#compare-container', {
 
 slider.setPosition(30);  // Move handle to 30%
 slider.destroy();        // Clean up
+
+// Color palette extraction (v2.1.0)
+NeikiGallery.extractPalette('photo.jpg', 5, (colors) => {
+  console.log(colors); // [{r, g, b, hex}, ...]
+});
+
+// Dominant color (v2.1.0)
+NeikiGallery.extractDominantColor('photo.jpg', (color) => {
+  console.log(color); // {r, g, b, hex}
+});
+
+// EXIF parsing (v2.1.0)
+NeikiGallery.parseExif('photo.jpg', (tags) => {
+  console.log(tags); // {make, model, iso, fNumber, exposure, focalLength}
+});
+
+// Blurhash decoding (v2.1.0)
+const pixels = NeikiGallery.decodeBlurhash('LEHV6nWB2y...', 32, 32);
+
+// Media type detection (v3.0.0)
+NeikiGallery.detectMediaType('https://youtube.com/watch?v=abc'); // 'youtube'
+NeikiGallery.detectMediaType('clip.mp4');                        // 'video'
+NeikiGallery.detectMediaType('photo.jpg');                       // 'image'
+
+// Plugin registration (v3.0.0)
+NeikiGallery.registerPlugin('watermark', (gallery, options) => ({
+  init()   { /* set up DOM, listeners */ },
+  open()   { /* on lightbox open */ },
+  change(d){ /* on slide change, d = {index, item, prevIndex} */ },
+  close()  { /* on lightbox close */ },
+  destroy(){ /* cleanup */ }
+}));
+
+NeikiGallery.unregisterPlugin('watermark');
+NeikiGallery.getRegisteredPlugins();   // ['watermark', ...]
+
+// Version
+console.log(NeikiGallery.version);     // '3.0.0'
+```
+
+### Plugin System
+
+A plugin is a factory function that receives the gallery instance and an options
+object, and returns an object with optional lifecycle methods:
+
+```js
+NeikiGallery.registerPlugin('analytics', (gallery, opts) => ({
+  init() {
+    console.log('[analytics] gallery initialized');
+  },
+  open(data) {
+    track('lightbox_open', { index: data.index });
+  },
+  change(data) {
+    track('slide_view', { src: data.item.src, index: data.index });
+  },
+  close() {
+    track('lightbox_close');
+  },
+  destroy() {
+    console.log('[analytics] cleanup');
+  }
+}));
+
+new NeikiGallery('#g', { plugins: [{ name: 'analytics', sampleRate: 0.5 }] });
 ```
 
+You can access plugin instances on a gallery via `gallery.plugin('analytics')`.
+
 ### Events
 
 ```js
@@ -202,6 +366,23 @@ gallery.on('select', (indices) => {
 gallery.on('slideshowStart', () => {
   console.log('Slideshow started');
 });
+
+gallery.on('reorder', (order) => {
+  console.log('New order:', order);
+});
+
+gallery.on('pipEnter', () => console.log('PiP on'));
+gallery.on('storyEnter', () => console.log('Story opened'));
+
+// v3.0.0 events
+gallery.on('favorite', ({ index, src }) => console.log('★ favorited', src));
+gallery.on('unfavorite', ({ index, src }) => console.log('☆ removed'));
+gallery.on('infoOpen', () => console.log('info panel opened'));
+gallery.on('print', ({ index, src }) => console.log('printed', src));
+gallery.on('editorExport', ({ blob, url }) => console.log('edited blob', url));
+gallery.on('annotateExport', ({ blob, url }) => console.log('annotated', url));
+gallery.on('append', (items) => console.log('appended', items.length));
+gallery.on('remove', ({ index }) => console.log('removed item', index));
 ```
 
 ### Options
@@ -215,18 +396,41 @@ gallery.on('slideshowStart', () => {
 | `contextualZoom` | `boolean` | `false` | Zoom to cursor point instead of center |
 | `fullscreen` | `boolean` | `true` | Show fullscreen button |
 | `transition` | `string` | `'fade'` | `'fade'` or `'slide'` |
-| `theme` | `string` | `'dark'` | `'dark'` or `'light'` |
+| `theme` | `string` | `'system'` | `'dark'` · `'light'` · `'system'` (auto-detect) |
 | `hashNavigation` | `boolean` | `true` | URL hash deep linking |
 | `counter` | `boolean` | `true` | Show image counter |
+| `counterFormat` | `string` | `'{current} / {total}'` | Counter format with `{current}`, `{total}`, `{percent}` tokens |
 | `captions` | `boolean` | `true` | Show image captions |
 | `preload` | `number` | `1` | Adjacent images to preload |
 | `lazyLoad` | `boolean` | `true` | Lazy load grid thumbnails |
 | `stagger` | `boolean` | `true` | Staggered entrance animation |
-| `slideshow` | `boolean` | `false` | Auto-start slideshow on open |
-| `slideshowInterval` | `number` | `4000` | Slideshow interval in ms |
+| `slideshow` | `boolean \| object` | `false` | `true` or `{ interval, pauseOnHover, kenburns, direction }` |
 | `share` | `boolean` | `true` | Show share button in lightbox |
 | `filter` | `boolean` | `false` | Enable tag filtering bar |
 | `batchSelect` | `boolean` | `false` | Enable Shift+click multi-select |
+| `focusPoint` | `boolean` | `true` | Respect `data-focus` for `object-position` |
+| `blurhash` | `boolean` | `true` | Decode `data-blurhash` placeholders |
+| `exif` | `boolean` | `false` | Show EXIF data overlay in lightbox |
+| `storyMode` | `boolean` | `false` | Enable story mode button in toolbar |
+| `pip` | `boolean` | `false` | Enable PiP button in toolbar |
+| `virtualScroll` | `boolean` | `false` | Virtualize grid for 50+ items |
+| `dragReorder` | `boolean` | `false` | Enable drag & drop reorder |
+| `backdropTint` | `boolean` | `false` | Tint overlay with dominant color |
+| `morphTransition` | `boolean` | `false` | FLIP morph from grid to lightbox |
+| `colorPalette` | `boolean` | `false` | Show extracted color palette |
+| `aspectSkeleton` | `boolean` | `true` | Use `data-width`/`data-height` for skeleton |
+| `video` | `boolean` | `true` | Auto-detect MP4 / YouTube / Vimeo URLs |
+| `plugins` | `array` | `null` | Plugins to instantiate; e.g. `['name', { name, ...opts }]` |
+| `group` | `string` | `''` | Album group name (also via `data-group`) |
+| `favorites` | `boolean` | `false` | Heart button + localStorage |
+| `favoritesKey` | `string` | `''` | Custom suffix for localStorage key |
+| `infoPanel` | `boolean` | `false` | Slide-out metadata sidebar |
+| `contextMenu` | `boolean` | `false` | Right-click menu on items |
+| `shortcutsHelp` | `boolean` | `true` | `?` key shortcuts overlay |
+| `infiniteScroll` | `boolean` | `false` | Auto-load more on scroll (with `loadMore`) |
+| `loadMore` | `function` | `null` | `(currentLength) => array \| Promise<array>` |
+| `editor` | `boolean` | `false` | Crop/rotate/flip toolbar |
+| `annotate` | `boolean` | `false` | Freehand drawing layer |
 
 ### Data Attributes
 
@@ -241,12 +445,32 @@ All options can also be set via `data-` attributes on the container:
      data-stagger="true"
      data-slideshow="false"
      data-slideshow-interval="5000"
+     data-slideshow-pause-on-hover="true"
+     data-slideshow-kenburns="true"
+     data-counter-format="{current} of {total}"
      data-share="true"
      data-filter="true"
      data-batch-select="false"
-     data-contextual-zoom="true">
-  <a href="full.jpg" data-tags="landscape,nature" data-size="large">
-    <img src="thumb.jpg" alt="Photo">
+     data-contextual-zoom="true"
+     data-story-mode="false"
+     data-pip="false"
+     data-exif="false"
+     data-backdrop-tint="false"
+     data-morph-transition="false"
+     data-color-palette="false"
+     data-drag-reorder="false"
+     data-virtual-scroll="false"
+     data-aspect-skeleton="true"
+     data-group="vacation"
+     data-favorites="true"
+     data-info-panel="true"
+     data-context-menu="true"
+     data-shortcuts-help="true"
+     data-editor="true"
+     data-annotate="true"
+     data-video="true">
+  <a href="full.jpg" data-tags="landscape,nature" data-size="large" data-width="1200" data-height="800" data-poster="poster.jpg" data-type="image">
+    <img src="thumb.jpg" alt="Photo" data-focus="0.5 0.3" data-blurhash="LEHV6nWB2y...">
   </a>
 </div>
 ```
@@ -283,10 +507,59 @@ Switch themes at runtime by setting `data-theme="light"` or `data-theme="dark"`
 
 | Browser | Version |
 |---------|---------|
-| Chrome | 60+ |
-| Firefox | 55+ |
-| Safari | 12+ |
-| Edge | 79+ |
+| Chrome | 80+ |
+| Firefox | 75+ |
+| Safari | 14+ |
+| Edge | 80+ |
+
+> **v3.0.0** raised the minimum to take advantage of `aspect-ratio`, `backdrop-filter`,
+> stable `IntersectionObserver`, and modern Canvas/Blob APIs. If you need older
+> browser support, pin to v2.1.0.
+
+## 🔁 Migration from v2.x to v3.0.0
+
+**v3.0.0 contains breaking changes.** Most galleries will continue to work, but
+review the following:
+
+### Slideshow config is nested
+
+```js
+// v2.x
+new NeikiGallery('#g', { slideshow: true, slideshowInterval: 5000 });
+
+// v3.0.0 — preferred (fine-grained control)
+new NeikiGallery('#g', {
+  slideshow: { interval: 5000, pauseOnHover: true, kenburns: true }
+});
+
+// v3.0.0 — still works (uses defaults)
+new NeikiGallery('#g', { slideshow: true });
+```
+
+### Default theme is `'system'`
+
+If you relied on the old default `'dark'`, set it explicitly:
+
+```js
+new NeikiGallery('#g', { theme: 'dark' });
+```
+
+### Hash format changed
+
+Old: `#neiki-1=3` → New: `#gallery-id-or-group-name/3`
+
+If you have external links to the old format, update them or set
+`hashNavigation: false` and implement custom routing.
+
+### Counter format
+
+Default output (`"3 / 12"`) is unchanged, but it's now formatted via
+`counterFormat: '{current} / {total}'`. Override with custom tokens.
+
+### Browser support
+
+Minimum Chrome 80+ / Firefox 75+ / Safari 14+ / Edge 80+. If you need older
+browser support, stay on v2.1.0.
 
 ## 📄 License