# Brandy Blocks

![Version](https://img.shields.io/badge/version-1.2.2-blue.svg)
![WordPress](https://img.shields.io/badge/WordPress-5.0+-green.svg)
![PHP](https://img.shields.io/badge/PHP-7.0+-purple.svg)
![License](https://img.shields.io/badge/license-GPLv3-red.svg)

Extra Gutenberg blocks and enhancements for the Brandy WordPress theme. This plugin extends the native WordPress block editor with custom blocks, block enhancements, patterns, and e-commerce features.

## 🎯 Overview

**Brandy Blocks** is a comprehensive WordPress plugin developed by [YayCommerce](https://yaycommerce.com/) that provides:

- **30+ Custom Gutenberg Blocks** - Purpose-built blocks for modern website design
- **Block Enhancements** - Extended settings and features for core and WooCommerce blocks
- **Pattern Library** - Pre-designed block patterns with a beautiful browsing interface
- **E-commerce Features** - Wishlist, product comparison, and quick view functionality
- **Responsive Design Tools** - Visibility conditions, responsive layouts, and display settings

## ✨ Features

### Custom Gutenberg Blocks

#### Layout & Structure
- **Container** - Flexible container block with advanced styling options
- **Collapsible** - Accordion/collapsible content sections
- **Modal** - Popup modal dialogs
- **Jump to Section** - Smooth scrolling navigation

#### Content Blocks
- **Button** - Enhanced button with custom styling
- **Icon** - Icon display with extensive icon library support
- **Breadcrumbs** - Customizable breadcrumb navigation
- **Google Map** - Embedded maps with custom styling
- **Count Down** - Countdown timer for events/launches

#### Media & Gallery
- **Media Gallery** - Image gallery in grid or slider layout with PhotoSwipe lightbox (pinch-zoom, swipe, captions) and Embla slider (prev/next, dots, mobile swipe). Static (manual) or dynamic (WP_Query: posts, pages, products) with preset/filter API for custom queries
- **Gallery Item** - Single gallery item: image + optional title/description; works with manual core/image OR dynamic core/post-featured-image; lightbox + slider compatible

#### Testimonials System
- **Testimonials** - Complete testimonials carousel/grid
- **Testimonial Card** - Individual testimonial container
- **Testimonial Avatar** - Author avatar/image
- **Testimonial Name** - Author name
- **Testimonial Content** - Testimonial text content
- **Testimonial Description** - Additional description/role
- **Testimonial Rating** - Star rating display

#### Pricing Components
- **Pricing** - Pricing table container
- **Pricing Card** - Individual pricing plan card

#### Form Builder
- **Form** - Form container with login, reset password, and custom form support
- **Form Input** - Text input field
- **Form Email** - Email input field
- **Form Password** - Password input field
- **Form Phone** - Phone number input field
- **Form Select** - Dropdown select field
- **Form Options** - Radio/checkbox options
- **Form Switcher** - Toggle switcher field
- **Form Submit** - Submit button

#### Post/Blog Features
- **Post Template** - Custom post layout templates
- **Relative Posts** - Related posts display

#### WooCommerce Blocks
- **Add to Wishlist** - Wishlist button for products
- **Add to Compare List** - Product comparison button
- **Compare Products** - Product comparison interface
- **Compare Table** - Comparison table display
- **Quick View Product** - Quick product preview modal
- **Recent Viewed Products** - Recently viewed products carousel

### Block Enhancements

The plugin extends existing WordPress and WooCommerce blocks with additional settings:

- **Block Slider** - Add carousel/slider functionality to any block
- **Display Animation** - Entry animations (fade, slide, zoom, etc.)
- **Display Settings** - Visibility and display options
- **Grid Responsive Layout** - Advanced responsive grid controls
- **Hover Settings** - Hover effects and transitions
- **Override Product Button** - Customize WooCommerce product buttons
- **Product Button Only Icon** - Icon-only product action buttons
- **Responsive Conditions** - Show/hide blocks based on device
- **Style Product Original Price** - Custom styling for sale prices
- **Text Gradient Color** - Gradient text effects
- **Visibility Conditions** - Conditional display logic

### Patterns Library

Interactive pattern library with:
- 140+ pre-designed block patterns
- Beautiful browsing interface built with React & Vite
- Pattern search and filtering
- One-click pattern insertion
- Categories and pagination

### E-commerce Features

#### Wishlist
- Add/remove products to wishlist
- Persistent wishlist storage
- Wishlist page with shortcode support
- AJAX-powered for smooth UX

#### Product Comparison
- Compare multiple products side-by-side
- Synchronized comparison list
- Detailed comparison table
- Add/remove products dynamically

#### Additional Tools
- Breadcrumb navigation
- Product helpers and utilities
- Custom product controllers

## 📋 Requirements

- **WordPress:** 5.0 or higher
- **PHP:** 7.0 or higher
- **Recommended:** Brandy Theme (optional but provides full feature integration)
- **WooCommerce:** Required for e-commerce blocks and features

## 🚀 Installation

### Via WordPress Admin

1. Download the plugin ZIP file
2. Navigate to **Plugins > Add New** in WordPress admin
3. Click **Upload Plugin** and select the ZIP file
4. Click **Install Now** and then **Activate**

### Manual Installation

1. Download and extract the plugin files
2. Upload the `brandy-blocks` folder to `/wp-content/plugins/`
3. Activate the plugin through the **Plugins** menu in WordPress

### Via Composer

```bash
composer require brandy/blocks
```

## 🛠 Development Setup

### Prerequisites

- Node.js (v14 or higher)
- Yarn or npm
- Composer
- PHP 7.0+

### Initial Setup

Clone the repository and initialize the development environment:

```bash
# Run the initialization script
./run.sh dev-init
```

This will:
- Install PHP dependencies via Composer
- Install Node.js dependencies for all sub-packages
- Set up the patterns library
- Configure development tools

### Manual Setup

If you prefer to set up manually:

```bash
# Install PHP dependencies
composer install

# Install PHP coding standards tools
cd tools && composer install && cd ..

# Install root Node dependencies
yarn install

# Install Blocks dependencies
cd inc/Packages && yarn install && cd ../..

# Install Block Enhancements dependencies
cd inc/Externals && yarn install && cd ../..

# Install Patterns Library dependencies
cd apps/patterns-library && yarn install && cd ../..
```

### Development Workflow

Start all development watchers concurrently:

```bash
# Start all dev servers
yarn run dev
# Or
./run.sh dev
```

This runs:
- Block editor development build (watch mode)
- Block enhancements development build (watch mode)
- Patterns library development server (Vite HMR)

### Individual Development

You can also run each part separately:

```bash
# Blocks only
cd inc/Packages
yarn run dev

# Block enhancements only
cd inc/Externals
yarn run dev

# Patterns library only
cd apps/patterns-library
yarn run dev
```

## 📦 Build & Release

### Production Build

Build all assets for production:

```bash
./run.sh release
```

This will:
1. Install all dependencies
2. Build the patterns library (Vite)
3. Build all Gutenberg blocks (wp-scripts)
4. Sync files excluding development files
5. Create a production-ready ZIP file in `/release/`
6. Set development mode to false

The release script uses `.distignore` to exclude development files from the production build.

### Manual Build

```bash
# Build patterns library
cd apps/patterns-library
yarn build

# Build blocks
cd inc/Packages
yarn build

# Build enhancements
cd inc/Externals
yarn build
```

## 🏗 Project Structure

```
brandy-blocks/
├── apps/
│   └── patterns-library/       # React app for pattern browsing
├── assets/
│   ├── css/                    # Plugin styles
│   ├── js/                     # Plugin scripts
│   ├── images/                 # Plugin images
│   ├── dist/                   # Built patterns library
│   └── lib/                    # Third-party libraries (Embla carousel)
├── inc/
│   ├── Admin/                  # Admin interface
│   ├── Core/                   # Core controllers
│   ├── Externals/              # Block enhancements
│   ├── Modules/                # Feature modules
│   ├── Packages/               # Custom blocks
│   │   ├── Blocks/             # Block PHP files
│   │   └── src/blocks/         # Block JSX/React code
│   ├── Patterns/               # Pattern definitions
│   ├── Services/               # Services (Google Maps, etc.)
│   ├── Shortcodes/             # WordPress shortcodes
│   ├── Traits/                 # Reusable PHP traits
│   └── Utils/                  # Helper utilities
├── templates/                   # PHP templates
├── tools/                       # Development tools (PHPCS)
├── vendor/                      # PHP dependencies
├── brandy-blocks.php           # Main plugin file
├── composer.json               # PHP dependencies
├── package.json                # Root Node.js config
└── run.sh                       # Build & dev scripts
```

## ⚙️ Configuration

### Google Maps API

To use the Google Map block:

1. Go to **Settings > Brandy Blocks** in WordPress admin
2. Navigate to the **Google Map** tab
3. Enter your Google Maps API key
4. Save settings

### Development Mode

Development mode is controlled in `brandy-blocks.php`:

```php
define( 'BRANDY_BLOCKS_IS_DEVELOPMENT', true ); // Development
define( 'BRANDY_BLOCKS_IS_DEVELOPMENT', false ); // Production
```

When enabled:
- Asset versions are timestamped (cache busting)
- Useful for development debugging

## 🎨 Using Custom Blocks

### In Block Editor

1. Open the WordPress block editor (Gutenberg)
2. Click the **+** button to add a block
3. Search for "Brandy" to see all Brandy Blocks
4. Select a block to insert it

### Block Categories

Blocks are organized into categories:
- **Brandy** - Core custom blocks
- **Brandy Forms** - Form building blocks
- **Brandy Testimonials** - Testimonial components
- **Brandy Pricing** - Pricing table components
- **Brandy WooCommerce** - E-commerce blocks

### Block Patterns

1. Click the **Patterns** icon in the block editor toolbar
2. Browse the Brandy Patterns library
3. Click any pattern to insert it
4. Customize the pattern blocks as needed

## 🔧 Code Quality & Standards

### PHP Code Standards

The plugin follows WordPress coding standards (WPCS):

```bash
# Check PHP code
cd tools
./vendor/bin/phpcs ../inc

# Auto-fix PHP code
./vendor/bin/phpcbf ../inc
```

Configuration:
- Uses WordPress-Core, WordPress-Docs standards
- PHP 7.0+ compatibility checks
- Located in: `tools/composer.json`

### JavaScript Standards

JavaScript follows WordPress scripting guidelines via `@wordpress/scripts`:

```bash
cd inc/Packages
yarn run lint:js
```

## 🎯 Usage Examples

### Wishlist Shortcode

Display the wishlist page:

```php
[brandy_wishlist]
```

### Breadcrumbs

Display breadcrumbs programmatically:

```php
<?php
use BrandyBlocks\Utils\Breadcrumbs;
Breadcrumbs::render();
?>
```

### Custom Form Types

The Form block supports three types:
- **Login Form** - User authentication
- **Reset Password Form** - Password recovery
- **Custom Form** - Build your own form fields

## 🔌 Hooks & Filters

### Actions

```php
// After plugin initialization
do_action( 'brandy_blocks_loaded' );

// Enqueue custom assets
add_action( 'enqueue_block_assets', 'your_custom_assets' );
```

### Filters

```php
// Modify breadcrumb output
add_filter( 'brandy_breadcrumbs_html', 'your_breadcrumb_filter' );

// Customize fluid font sizes
add_filter( 'wp_theme_json_data_theme', 'your_font_size_filter' );
```

## 🌐 Browser Support

- Chrome (latest 2 versions)
- Firefox (latest 2 versions)
- Safari (latest 2 versions)
- Edge (latest 2 versions)
- Mobile browsers (iOS Safari, Chrome Mobile)

## 🤝 Contributing

### Development Workflow

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/your-feature`
3. Make your changes
4. Test thoroughly
5. Commit with descriptive messages
6. Push to your fork
7. Submit a pull request

### Coding Guidelines

- Follow WordPress coding standards
- Write clean, documented code
- Test on multiple WordPress versions
- Ensure mobile responsiveness
- Add inline documentation

## 📝 Changelog

### Version 1.2.2
- Current stable release
- Enhanced block features
- Improved patterns library
- Bug fixes and optimizations
- **2026-04-29:** Media Gallery dynamic query mode added (post type / preset / custom filter)
- **2026-04-29:** Added Media Grid block (`brandy/media-grid` + `brandy/media-grid-item`) with PhotoSwipe lightbox and Embla slider support

For detailed changelog, see plugin update notes.

## 📄 License

This plugin is licensed under the **GPLv3 or later**.

```
Brandy Blocks - Extra blocks for Brandy theme
Copyright (C) 2024 YayCommerce

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
```

See [LICENSE](https://www.gnu.org/licenses/gpl-3.0.html) for full details.

## 👥 Credits

**Developed by:** [YayCommerce](https://yaycommerce.com/)

**Built with:**
- WordPress Block Editor (Gutenberg)
- React & Vite
- @wordpress/scripts
- Embla Carousel
- PHP CodeSniffer

## 🆘 Support

- **Documentation:** [YayCommerce Docs](https://yaycommerce.com/)
- **Issues:** Report bugs via GitHub issues
- **Community:** WordPress.org support forums
- **Pro Support:** Available for premium customers

## 🔗 Links

- [Plugin Homepage](https://yaycommerce.com/)
- [YayCommerce](https://yaycommerce.com/)
- [WordPress.org](https://wordpress.org/)
- [GitHub Repository](https://github.com/YayCommerce/WooCommerce-Theme)

---

**Made with ❤️ by YayCommerce**