# BlockXpert

**Professional Gutenberg Blocks for WordPress** — Powered by AI and GSAP animations

A comprehensive WordPress plugin featuring 8 production-ready Gutenberg blocks with AI integration, advanced animations, and WooCommerce support.

---

## Features

### AI-Powered Blocks
- **AI FAQ Block** — Automatically generate and manage FAQs using AI
- **AI Recommendations** — Smart content suggestions powered by OpenAI
- **AI Product Recommendations** — Intelligent WooCommerce product recommendations

### Animation & Design Blocks
- **Text Animation** — GSAP-powered animations with 5 easing functions (easeInOut, easeIn, easeOut, linear, bounce)
- **Product Slider** — Smooth GSAP carousel with 500ms transitions and momentum
- **Product Carousel** — Autoplay-enabled product showcase with smooth animations
- **Advanced Post Block** — Multi-layout post display (Grid, Masonry, Slider, Ticker)
- **Post Grid** — Flexible post grid with advanced filtering

### Professional Architecture
- **8 Independent Gutenberg Blocks** — Fully customizable and modular
- **Admin Settings Panel** — Enable/disable blocks with AJAX save (no page reload)
- **Real-time Notifications** — Toast notifications for all user actions
- **Service Architecture** — Dependency injection container and interface-based design
- **REST API** — Full REST API endpoints for programmatic access
- **Caching System** — Built-in performance optimization layer
- **Professional Logging** — File-based logging with rotation
- **WooCommerce Ready** — Full integration and compatibility

---

## Requirements

- **WordPress** 5.8+ (Tested up to 6.7)
- **PHP** 7.4+ (Tested up to 8.3)
- **Node.js** 14+ (for development)
- **npm** or **yarn**

---

## Installation

### Quick Start
```bash
git clone https://github.com/nftushar/blockxpert.git
cd blockxpert
npm install
composer install
npm run build
```

### WordPress Activation
1. Navigate to **Plugins** in WordPress admin
2. Find **BlockXpert** and click **Activate**
3. All 8 blocks are active by default
4. Manage blocks in **Settings → BlockXpert**

---

## Development

### Build Commands
```bash
npm run build              # Development build
npm run build:prod        # Production build (optimized)
npm start                 # Watch mode with auto-rebuild
npm run clean             # Clear build folder
```

### Code Quality
```bash
npm run lint              # Check code quality (ESLint)
npm run format            # Auto-format code (Prettier)
npm run validate          # Run all checks
```

### PHP Dependencies
```bash
composer install          # Install dependencies
composer install --no-dev # Production (no dev dependencies)
```

---

## Project Structure

```
blockxpert/
├── blockxpert.php                    ← Main plugin entry
├── package.json                      ← npm dependencies
├── composer.json                     ← PHP dependencies
├── banner-772x250.png                ← Plugin banner (WordPress.org)
├── icon-128x128.png                  ← Plugin icon
│
├── src/                              ← React/JavaScript source
│   ├── blocks/                       ← 8 Gutenberg blocks
│   │   ├── text-animation/
│   │   ├── product-slider/
│   │   ├── ai-faq/
│   │   ├── post-grid/
│   │   ├── product-carousel/
│   │   ├── advanced-post-block/
│   │   ├── ai-recommendations/
│   │   └── ai-product-recommendations/
│   └── shared/                       ← Reusable utilities
│       ├── components/               ← React components
│       ├── hooks/                    ← Custom hooks
│       ├── services/                 ← API clients
│       ├── context/                  ← Global state
│       └── utils/                    ← Helpers
│
├── includes/                         ← PHP backend
│   ├── classes/                      ← Service classes
│   ├── interfaces/                   ← Service contracts
│   ├── admin/                        ← Admin UI
│   └── assets/                       ← Admin styles/scripts
│
├── build/                            ← Compiled assets
├── vendor/                           ← Composer dependencies
└── languages/                        ← Translation files
```

---

## Block Specifications

| Block | Type | Features | Status |
|-------|------|----------|--------|
| Text Animation | Design | GSAP animations, 5 easing functions | ✅ Production |
| Product Slider | WooCommerce | Carousel, momentum transitions | ✅ Production |
| AI FAQ | Content | AI-powered accordion | ✅ Production |
| AI Recommendations | AI | Dynamic suggestions | ✅ Production |
| Post Grid | Posts | Advanced filters and layouts | ✅ Production |
| Product Carousel | WooCommerce | Autoplay, pagination | ✅ Production |
| Advanced Post Block | Posts | Grid, Masonry, Slider, Ticker | ✅ Production |
| AI Product Recommendations | WooCommerce | Smart product filtering | ✅ Production |

---

## GSAP Animations

BlockXpert uses **GSAP 3.14** for smooth, performant animations:

### Text Animation Block
- **5 Easing Functions** — easeInOut, easeIn, easeOut, linear, bounce
- **Real-time Preview** — See animations instantly in editor
- **Customizable Duration** — 100ms to 5000ms animation speed
- **Stagger Support** — Multi-element animations with delays

### Product Blocks
- **500ms Transitions** — Smooth momentum-based slides
- **Hardware Acceleration** — GPU-optimized for performance
- **Touch Support** — Smooth swipe animations on mobile
- **Auto-play** — Interval-based automatic animation

### Performance
- **RequestAnimationFrame Optimized** — 60 FPS smooth animations
- **Lightweight** — GSAP 3 is only ~15KB minified
- **Auto-Cleanup** — Proper animation destruction on unmount
- **GPU Acceleration** — Transform3D for smooth performance

---

## Architecture

### Backend (PHP)
- **Dependency Injection** — Professional service container
- **Service Interfaces** — Clear contracts for extensibility
- **Logger Service** — File-based logging with rotation
- **Cache Layer** — Performance optimization
- **AI Provider Abstraction** — Pluggable AI system support
- **REST API** — WordPress REST API integration

### Frontend (React)
- **8 Independent Blocks** — Full Gutenberg integration
- **GSAP Animations** — Smooth, performant effects
- **React Context** — Global state management
- **Custom Hooks** — useAPI, useCache, useDebounce
- **Error Boundaries** — Reliability and error handling

### Build System
- **Webpack (wp-scripts)** — Optimized bundling
- **SCSS Compilation** — Modern styling
- **Auto Asset Generation** — Automatic bundling
- **Cache Busting** — Invalidation built-in

---

## Configuration

### Admin Settings
Access block settings at **Settings → BlockXpert**:
- Enable/disable individual blocks
- Configure block behavior
- Manage AJAX-based settings
- Real-time notification feedback

### API Endpoints
- `POST /wp-json/blockxpert/v1/save-settings` — Save plugin settings
- Full REST API documentation included

---

## Creating New Blocks

1. Create folder: `src/blocks/my-block/`
2. Copy structure from existing block
3. Edit block files (index.js, block.json, view.js)
4. Build: `npm run build`
5. Test in WordPress editor

---

## Version History

### 1.2.0 - March 28, 2026
**Enhanced Admin UX with AJAX & Real-time Feedback**
- AJAX-based settings save (no page reload)
- Real-time toast notifications
- REST API endpoint for settings
- WordPress 6.7 compatibility
- PHP 8.3 tested and verified

### 1.1.0
- Initial 8 blocks implementation
- AI FAQ and Product Recommendations
- GSAP animations
- Professional logging and caching

### 1.0.0
- Initial release with core blocks

---

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/name`
3. Make your changes
4. Build and test: `npm run build`
5. Format code: `npm run format`
6. Submit a pull request

---

## License

GPL v2 or later — See [LICENSE.txt](LICENSE.txt) for full license

---

## Support

### Troubleshooting
- **Blocks not appearing?** → `npm run clean && npm run build`
- **Build errors?** → Delete node_modules: `rm -rf node_modules && npm install`
- **Admin issues?** → Check PHP error logs

### Resources
- GitHub: https://github.com/nftushar/blockxpert
- Issues: https://github.com/nftushar/blockxpert/issues
- WordPress.org: https://wordpress.org/plugins/blockxpert/

---

**Author:** NF Tushar  
**Status:** ✅ Production Ready  
**Version:** 1.2.0