=== Responsive Picture Block ===
Contributors: coreessentials
Tags: responsive images, picture element, art direction, gutenberg, block editor, media queries, srcset, sizes, object-fit, aspect-ratio, webp, performance, accessibility
Requires at least: 6.3
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Create truly responsive, **art-directed** images in the block editor. Wrap multiple Image blocks (Desktop/Tablet/Mobile/Custom) and render a single `<picture>` HTML element with correctly ordered `<source media="…">` and editor previews that follow WordPress device switcher. Fully compatible with WordPress Synced Patterns and Overrides.

== Description ==

**Core Essentials – Responsive Picture Block** turns several standard **Image** blocks into one semantic, front-end `<picture>` HTML element. It’s built for **art direction**: choose **different crops, compositions, or formats** for different breakpoints (e.g., a tight mobile crop, a wider desktop crop, or an AVIF/WebP source).

Why this matters:

- **`<picture>` vs `<img srcset>`**  
  `srcset` is great for picking the right **resolution** of the *same* image. But when you need different **content** (crop/ratio/composition) at different viewport widths, you need **art direction** — that’s exactly what `<picture>` does by letting you swap **entire sources** via `<source media="…">`.

- **Editor-first UX**  
  Authors see a single “Responsive Picture (Block)” wrapper, then insert one Image per breakpoint. The plugin mirrors the link /caption from the Desktop image. Per-image design controls (aspect ratio, object-fit, width/height) are respected. The block’s **preview** shows the native **Desktop / Tablet / Mobile** toolbar:  
  - Desktop preview ⇒ show **all** child images  
  - Tablet preview ⇒ show **Tablet**, else **Desktop**, else **Mobile**  
  - Mobile preview ⇒ show **Mobile**, else **Tablet**, else **Desktop**

- **Perfect source ordering**  
  Custom media queries are **auto-sorted** so the correct `<source>` wins (most specific first). Works with `max-width`, `min-width`, and range queries.

### Key Features

- Wraps multiple core **Image** blocks into a single semantic `<picture>`
- Pick **Desktop / Tablet / Mobile / Custom** images (true art direction)
- **Override `media`** per Tablet/Mobile/Custom (e.g., `(max-width: 1200px)`)
- Optional **`sizes` override** per source (advanced bandwidth tuning)
- Allows **width, height, aspect-ratio, object-fit** per breakpoint
- Uses **link + caption** from the Desktop (fallback) image
- Editor **preview** follows WordPress’ device switcher (Desktop/Tablet/Mobile)
- Prevents layout overflow; picture wrapper is fully responsive
- Works with standard WP image sizes and responsive `srcset`
- Lightweight, no front-end JS — pure HTML/CSS on the front end

### Why `<picture>` (Art Direction 101)

When your layout needs **different imagery** across breakpoints (e.g., a vertical crop on phones and a wide landscape on desktops), you’re doing **art direction**. The `<picture>` element enables this by letting the browser **choose an entire source** based on `media` conditions (and even file `type`, like AVIF/WebP), not just a different width of the same file. The result is **better design control** and **faster pages** because each device downloads **only the most appropriate asset** for its layout saving you bandwidth as well as having compositions control.

### Use Cases

- Hero banners with **different crops** for mobile vs desktop  
- Product images where the **subject framing** changes on small screens  
- Editorial layouts that require **portrait vs landscape** compositions  
- File **format switching** (e.g., AVIF/WebP with PNG/JPEG fallback)

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/` or install via the Plugins screen.
2. Activate **Core Essentials – Responsive Picture Block**.
3. In the block editor, add **Responsive Picture (Block)** and insert one **Image** per breakpoint.

== Usage ==

1. **Insert** the **Responsive Picture (Block)** block.  
2. **Add Image blocks** inside it for: Desktop (fallback), Tablet, Mobile, and/or Custom.  
3. **Select each Image** and open the **Responsive: Breakpoint** panel:
   - **Viewport**: Desktop / Tablet / Mobile / Custom  
   - **Override media query** (Tablet/Mobile): optional (e.g., `(max-width: 1200px)`)  
   - **Custom media query**: required when using the “Custom” viewport  
4. (Optional) Open **Advanced: Sizes override** to set a custom `sizes=""` for that source.  
5. Use the editor’s **Desktop / Tablet / Mobile** preview to check the effective image per breakpoint.  
6. Publish. The front end renders a single `<picture>` with perfectly ordered `<source>` tags and a fallback `<img>`.

== Screenshots ==

1. Block wrapper with Desktop, Tablet, Mobile child options  
2. Front-end markup: `<picture>` with differnt image for mobile
3. Choosing Responsive Picture Block in the block editor  

== Frequently Asked Questions ==

= Does this replace `srcset` / responsive images? =  
No. Each `<source>` (and the fallback `<img>`) still uses WordPress’ native responsive `srcset`. The plugin adds **art direction** by swapping **sources** per breakpoint; `srcset` then chooses the best **resolution** within that source.

= Can I add multiple custom breakpoints? =  
Yes. Add more **Custom** Images with your media queries. The plugin **sorts** them (and Tablet/Mobile) into the correct order so the right source wins.

= Do I need to touch `sizes`? =  
No. It’s optional and only affects **resolution selection** inside a matched source. If you use it, follow the pattern:  
`(media) length, …, fallback-length` (e.g., `(max-width: 1024px) 100vw, 1024px`).

= Accessibility? Alt text? =  
Alt text is taken from the **Desktop Image**, the image; the `<picture>` `<img>` carries it.

= What about aspect ratio and scale? =  
All aspect ratio and scale settings are taken from the individual image, so if your mobile image is 9:16 and desktop image is set to 4:3 both will be respected at their screen sizes.

= Performance and formats? =  
You can upload **AVIF/WebP** assets and still provide a PNG/JPEG fallback in the Desktop image if needed. The browser will pick the **first matching** `<source>` (by `media` and optionally `type`) and an optimal width via `srcset`.

= Does it work with Synced Patterns and Overrides? =  
As of version 1.1.0, the Responsive Picture Block fully supports WordPress Synced Patterns with Overrides. You can:
1. Create a synced pattern containing a Responsive Picture Block
2. Enable overrides on the Desktop, Tablet, and Mobile images
3. Use the pattern across multiple pages
4. Replace images on each page using the standard "Replace" feature
Each page will display different images while maintaining the same responsive structure and design. The Block Bindings API handles all image attributes (id, url, alt, caption) automatically.

== Block Details ==

- Block name: `ce/responsive-picture`  
- Children: one or more `core/image` blocks  
- Front-end HTML output:  
  `
  <picture>
    <source media="(max-width: 767px)" srcset="…" sizes="…">
    <source media="(max-width: 1024px)" srcset="…" sizes="…">
    <!-- custom sources (auto-sorted) -->
    <img src="…" srcset="…" sizes="…" alt="">
  </picture>`

== Changelog ==

= 1.1.1 =
* Fixed: Classes and alignments added to the main block are now included

= 1.1.0 =
* Thanks: Huge thank you to the @spinndevs team for their feedback and functionality suggestions which powered this version
* Added: Full support for WordPress Synced Patterns with Override images per pattern instance
* Added: Block Bindings API integration for pattern overrides (id, url, alt, caption attributes)
* Changed: Default preview mode is now "Show All" for better user experience
* Changed: Auto mode now correctly mirrors frontend behaviour (shows only relevant image / fallback per viewport)
* Improved: Block toolbar simplified to All/Auto toggle (full controls remain in inspector panel)
* Fixed: Floating toolbar now appears correctly when block is selected
* Fixed: Block now properly receives pattern override context via uses_context

= 1.0.0 =
* Initial release