=== Steve's Gallery Helper ===
Contributors: stevegibbs
Donate link: https://wp.stevegibbs.info
Tags: gallery, lightbox, slideshow, carousel, lightweight, no-jquery
Requires at least: 5.6
Tested up to: 7.0
Stable tag: 1.7.51
Requires PHP: 8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A lightweight, no-jQuery lightbox and image carousel add-on for WordPress's core gallery block.

== Description ==

Gallery Helper extends the native WordPress Gallery block (`core/gallery`) with two premium display modes — **Lightbox** and **Carousel** — without adding any jQuery dependency.

= Lightbox Mode =
Click any gallery image to open it in a full-screen overlay with:
- **Previous / Next navigation** via on-screen buttons, keyboard arrow keys, touch swipe, or mouse drag
- **Automatic slideshow** mode that advances images every 3 seconds (pauses on click)
- **Fade transitions** on swipe gestures for a native feel
- **Accessibility**: ARIA roles, focus trapping, keyboard Escape to close, screen reader support
- **Responsive**: navigation buttons hide on mobile (swipe instead)

= Carousel Mode =
Display your gallery images as a full-height, single-image strip with:
- **Horizontal** orientation (default) or **Vertical** orientation
- **Height-justified, no-cropping** display — each image fills the container height while preserving its natural aspect ratio via `object-fit: contain`
- **Prev / Next** navigation via on-screen buttons, keyboard arrows, mouse drag, or touch swipe
- **Auto-advance** mode with configurable interval (pauses on hover/focus, resumes on leave)
- **Reacts to window resize** — re-centers the current slide
- **Lightbox integration** — when both Carousel and Lightbox are enabled, clicking a carousel image opens the lightbox with full navigation

= Key Design Principles =
- **No jQuery** — uses vanilla JavaScript throughout
- **Lightweight** — CSS and JS only enqueue when a gallery block uses the helper
- **Unobtrusive** — leaves the editor experience untouched; adds a single "Gallery Helper Settings" panel to the block inspector
- **Dynamic content compatible** — uses MutationObserver to support galleries loaded via AJAX, accordions, tabs, or other dynamic UIs

== Installation ==

1. Upload the `steves-gallery-helper` directory to `/wp-content/plugins/`, or upload the zip via **Plugins → Add New → Upload Plugin**.
2. Activate the plugin through the **Plugins** screen.
3. Add a **Gallery** block to any post, page, or custom post type.
4. Open the block settings sidebar and expand **Gallery Helper Settings**.
5. Toggle **Enable Lightbox** and/or set **Display Mode** to **Carousel**.
6. Publish and enjoy.

== Frequently Asked Questions ==

= Does this plugin require jQuery? =
No. All front-end JavaScript is written in vanilla ES5/ES6 — no jQuery dependency.

= Does the carousel work with the lightbox? =
Yes. When both Carousel mode and Lightbox are enabled, clicking any carousel image opens it in the lightbox overlay with full prev/next navigation.

= Does it work with dynamic galleries (e.g. in accordions or tabs)? =
Yes. The plugin uses a MutationObserver to detect galleries added to the DOM after the initial page load.

= Can I sell this plugin? =
This plugin is licensed under GPLv2. You are free to use, modify, and distribute it in accordance with the license terms.

== Usage ==

=== Lightbox ===
1. Add a Gallery block to your content.
2. In the block settings sidebar, locate the **Gallery Helper Settings** panel.
3. Check **Enable Lightbox**.
4. Optional: set **Slideshow Mode** to **Automatic** for auto-advancing images.
5. On the front end, click any gallery image to open the lightbox.

=== Carousel ===
1. Add a Gallery block to your content.
2. In the block settings sidebar, locate the **Gallery Helper Settings** panel.
3. Set **Display Mode** to **Carousel**.
4. Choose **Direction**: Horizontal (side-to-side) or Vertical (top-to-bottom).
5. Optional: enable **Auto-advance** and set the **Interval (ms)** (default 3000).
6. On the front end, the gallery renders as a full-height image strip with prev/next buttons.

=== Dynamic Galleries ===
The plugin automatically handles galleries loaded dynamically (e.g. inside accordion blocks, tabs, AJAX-loaded content). No extra configuration required.

== Screenshots ==

1. Settings are simple and intuitive

== Changelog ==
= 1.7.5 =
* Fixed: small bug in carousel editor.

= 1.7.4 =
* New: Carousel display mode — display gallery images as a horizontal or vertical image strip with prev/next navigation, swipe support, keyboard arrows, and optional auto-advance with configurable interval.
* New: "Display Mode" setting (Grid / Carousel) in the Gallery Helper Settings panel.
* New: "Direction" setting (Horizontal / Vertical) for carousel orientation.
* New: "Auto-advance" toggle and interval control for the carousel.
* New: Carousel integrates with the existing lightbox — enable both for click-to-lightbox from carousel images.
* New: CSS for carousel layout — height-justified, no-cropping image display with responsive breakpoints.
* New: Mouse drag and touch swipe support for carousel navigation.
* Fix: Carousel auto-advance pauses on hover/focus and resumes on mouse leave / focus out.
* Fix: Carousel re-centers current slide on window resize.
* Dev: Replaced function declarations with function expressions inside setupCarousel to avoid hoisting issues.

= 1.7.3 =
* Fixed duplicate event listeners that could cause multiple lightboxes to open.
* Ensured compatibility with galleries inside nested blocks (e.g., Accordions, Details).

= 1.7.2 =
* Fixed enqueue_frontend_assets so plugin files only load when the gallery helper is in use.

= 1.7.0 =
* Added smooth fade transitions for swipe gestures (touch and mouse drag).
* Added grab cursor for desktop mouse swipe indication.
* Improved swipe handling with unified touch/mouse event system.
* Maintained instant navigation for buttons and keyboard controls.

= 1.6.1 =
* Bug fixes and improvements.

= 1.6.0 =
* Added slideshow mode support.
* Improved accessibility features.

= 1.5.0 =
* Initial release with lightbox functionality.

== Upgrade Notice ==

= 1.7.4 =
Adds a new Carousel display mode with horizontal/vertical orientation, auto-advance, and lightbox integration. See the Settings panel in the Gallery block inspector.