# Gutenberg Blocks Implementation Guide

## Overview

The Universal DAM WordPress plugin includes two Gutenberg blocks for integrating DAM assets into WordPress content:

1. **DAM Image Block** - Insert individual images from the DAM
2. **DAM Gallery Block** - Create galleries with multiple DAM images

Both blocks use server-side rendering for optimal performance and SEO, and integrate with the DAM picker for asset selection.

## Architecture

### Block Registration Flow

```
WordPress Init
    ↓
PHP: register_block_type() in class-dam-gutenberg.php
    ↓
JavaScript: registerBlockType() in blocks/*/index.js
    ↓
Block appears in Gutenberg editor
```

### Asset Selection Flow

```
User clicks "Select Image/Images"
    ↓
Block calls window.damPickerBridge.openPicker()
    ↓
DAM Picker UI opens (Svelte app)
    ↓
User selects asset(s)
    ↓
Picker dispatches 'dam:assetsSelected' event
    ↓
Bridge calls callback with selected assets
    ↓
Block updates attributes
    ↓
ServerSideRender refreshes preview
```

## Components

### DAM Image Block

**Features:**
- Select single image from DAM
- Alt text for accessibility
- Width and height controls
- Alignment support (left, center, right, wide, full)
- Server-side rendered

**Attributes:**
- assetId (string) - Unique asset identifier
- assetUrl (string) - Asset URL
- alt (string) - Alt text
- width (number) - Image width
- height (number) - Image height
- alignment (string) - Alignment setting

### DAM Gallery Block

**Features:**
- Select multiple images from DAM
- Configurable columns (1-8)
- Grid or masonry layouts
- Image cropping toggle
- Link to full-size option
- Fully responsive

**Attributes:**
- assetIds (array) - Array of asset IDs
- columns (number) - Column count
- imageCrop (boolean) - Crop images to square
- linkTo (string) - Link destination
- galleryLayout (string) - Layout type

## Build Process

### Development
```bash
npm run dev:blocks
```

### Production
```bash
npm run build:blocks
```

### Complete Build
```bash
npm run build
```

## File Structure

```
src/blocks/
├── index.js                    # Entry point
├── dam-image/
│   ├── index.js               # Block registration
│   ├── edit.js                # Editor component
│   ├── editor.scss            # Editor styles
│   └── style.scss             # Frontend styles
└── dam-gallery/
    ├── index.js
    ├── edit.js
    ├── editor.scss
    └── style.scss

src/dam-picker-bridge.js       # Picker integration

includes/class-dam-gutenberg.php  # PHP registration
```

## DAM Picker Bridge

Global interface for blocks to interact with the DAM picker:

```javascript
// Open picker for single selection
window.damPickerBridge.openPicker((assets) => {
    setAttributes({ assetId: assets[0].id });
}, false);

// Open picker for multiple selection
window.damPickerBridge.openPicker((assets) => {
    const ids = assets.map(a => a.id);
    setAttributes({ assetIds: ids });
}, true);
```

## Extending

To add a new block:

1. Create `src/blocks/your-block/` directory
2. Create index.js, edit.js, editor.scss, style.scss
3. Register in PHP (class-dam-gutenberg.php)
4. Add import to src/blocks/index.js
5. Run build

## Testing

Manual testing checklist:
- Block appears in inserter
- Asset selection works
- Preview renders correctly
- Frontend matches editor
- All controls function
- Responsive behavior works

