=== PlugVista Carousel Builder Block ===
Contributors: souravws
Donate link: https://sourav.work/
Tags: carousel, slider, gutenberg, block, swiper
Requires at least: 6.1
Tested up to: 6.9
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A carousel slider block with 6 slide effects, built-in lightbox, free mode, keyboard navigation, autoplay, and CSS variable theming.

== Description ==

**PlugVista Carousel Builder Block** adds a powerful and flexible carousel slider to the WordPress block editor. Each slide can hold any Gutenberg block — images, text, buttons, covers, WooCommerce products, and more — giving you complete creative freedom.

= Key Features =

* Use **any Gutenberg block** as slide content
* **6 slide transition effects** — Slide, Fade, Coverflow, Flip, Cube, Cards
* **Built-in Lightbox** — click any image in a slide to open a fullscreen modal with keyboard navigation (Arrow keys, Escape) and captions
* **Free Mode** — physics-based momentum scrolling without snapping, ideal for logo carousels
* **Centered Slides** — display the active slide in the center with partial neighbors visible on both sides
* **Auto Height** — carousel height adapts dynamically to the active slide's content
* **Mousewheel / Trackpad Scroll** — navigate slides by scrolling the mouse wheel or trackpad
* **Keyboard Navigation** — move through slides using the left/right arrow keys
* Navigation arrows (toggleable)
* Pagination dots (toggleable)
* Autoplay with configurable delay, pause-on-hover, and disable-on-interaction options
* Infinite loop sliding
* RTL (right-to-left) language support
* Live multi-column preview in the block editor
* Responsive breakpoints — configure slides-per-view for mobile separately
* CSS variable theming (theme.json compatible)
* On-demand loading — Swiper assets load only on pages that use the carousel
* Public JavaScript API for integration with tabs, accordions, and modals

= Starter Block Patterns =

Three ready-to-use block patterns are included:

* **Full Width Hero Slider** — full-width cover slides with call-to-action buttons
* **Testimonials Slider** — quote blocks with autoplay
* **Logos Carousel** — image-based logo ticker with free mode

= CSS Customization =

Style the carousel using CSS custom properties in your theme's `theme.json` or Additional CSS:

* `--wp--custom--scb--navigation-color` — Arrow color
* `--wp--custom--scb--navigation-hover-color` — Arrow hover color
* `--wp--custom--scb--navigation-size` — Arrow size (height in px)
* `--wp--custom--scb--navigation-sides-offset` — Arrow horizontal offset
* `--wp--custom--scb--navigation-alignfull-color` — Arrow color for full-width carousels
* `--wp--custom--scb--pagination-bullet-active-color` — Active dot color
* `--wp--custom--scb--pagination-bullet-inactive-color` — Inactive dot color
* `--wp--custom--scb--pagination-bullet-size` — Dot diameter
* `--wp--custom--scb--pagination-bottom` — Dot pagination vertical offset

= Public JavaScript API =

Integrate with tabs, accordions, modals, and other dynamic layouts that show/hide content:

`window.PlugVistaCarouselBuilder.init(container);   // Initialize all carousels inside a container`
`window.PlugVistaCarouselBuilder.update(container); // Update/re-initialize existing carousels`

= Third-Party Libraries =

This plugin bundles the following third-party library:

**Swiper** (https://swiperjs.com/)
License: MIT
Copyright: Vladimir Kharlampidi
Source: https://github.com/nolimits4web/swiper

The full Swiper bundle (v11.2.10, ~154 KB) is included and loaded on-demand only on pages that contain a carousel block.

== Installation ==

1. Upload the `plugvista-carousel-builder-block` folder to the `/wp-content/plugins/` directory.
2. Activate the plugin from the **Plugins** screen in WordPress Admin.
3. Open any post or page in the block editor.
4. Click the **+** block inserter and search for **"Carousel"**.
5. Insert the **Sourav Carousel** block. Two default slides will appear.
6. Click inside a slide to add any block content.
7. Use the **Block Settings** panel on the right to configure the carousel.

== Frequently Asked Questions ==

= Can I add different types of content to each slide? =

Yes. Each slide accepts any Gutenberg block — images, text, headings, buttons, covers, embeds, WooCommerce products, and more.

= Is it mobile responsive? =

Yes. The carousel is fully responsive and touch-enabled. You can set a separate slides-per-view value for mobile via the Responsive Settings panel.

= Can I use multiple carousels on the same page? =

Yes. Each carousel block works independently with its own settings. Swiper assets are loaded only once regardless of how many carousels are on the page.

= How does the lightbox work? =

When slides contain `core/image` blocks, clicking any image opens a fullscreen lightbox overlay. Use the left/right arrow keys or on-screen buttons to navigate between images, and press Escape (or click the backdrop) to close.

= How do I customize arrow and dot colors? =

Use CSS custom properties in your theme's `theme.json` under `settings.custom.scb`, or add them to **Appearance > Customize > Additional CSS**.

= Does it work with the Classic Editor? =

No. This plugin requires the block editor (Gutenberg) and is not compatible with the Classic Editor plugin.

= Some themes break the carousel layout. What should I do? =

Some themes apply aggressive flexbox rules to `.entry-content` that conflict with the carousel width. Add the following to **Additional CSS**:

`.entry-content { min-width: 0; width: 100%; }`

= Does this plugin slow down my site? =

No. Swiper assets are loaded on-demand — only on pages that contain a carousel block. There are no external HTTP requests and no tracking of any kind.

== Screenshots ==

1. Carousel block in the WordPress block editor showing the horizontal slide preview.
2. Block settings panel — Carousel Settings with effect selector, autoplay, and navigation options.
3. Block settings panel — Responsive Settings and Advanced options.
4. Frontend carousel with navigation arrows and pagination dots.
5. Built-in lightbox opened from an image slide.
6. Six available slide transition effects.

== Changelog ==

= 1.0.0 =
* Initial release.
* Carousel block accepting any Gutenberg block as slide content.
* Six transition effects: Slide, Fade, Coverflow, Flip, Cube, Cards.
* Built-in lightbox with keyboard navigation, prev/next buttons, captions, and ARIA accessibility.
* Navigation arrows and pagination dots (individually toggleable).
* Autoplay with configurable delay, pause-on-hover, and disable-on-interaction.
* Infinite loop mode with smooth additional-slide buffering.
* Free Mode for momentum-based scrolling without snapping.
* Centered Slides for active-slide-centered layouts.
* Auto Height to match the active slide's content height.
* Mousewheel / trackpad scroll navigation.
* Keyboard arrow-key navigation.
* RTL (right-to-left) support.
* Responsive breakpoints — independent slides-per-view for mobile.
* Live horizontal multi-column preview in the block editor.
* Three starter block patterns: Hero Slider, Testimonials Slider, Logos Carousel.
* CSS custom property theming (theme.json compatible).
* On-demand Swiper asset loading — zero impact on pages without the block.
* Lightweight custom Swiper build (~84 KB) by default; full bundle auto-enabled for advanced effects.
* Public JavaScript API: `window.PlugVistaCarouselBuilder.init()` and `.update()`.
* Admin settings page to force the full Swiper bundle globally.

== Upgrade Notice ==

= 1.0.0 =
Initial release.

== Credits ==

Developed by [Sourav Biswas](https://sourav.work/).

Powered by [Swiper.js](https://swiperjs.com/) — the most modern mobile touch slider, released under the MIT license.
