# DAM WordPress Plugin - Svelte Admin UI

This document describes the Svelte-based admin UI implementation for the Universal DAM WordPress plugin.

## Setup

### 1. Install Dependencies

```bash
npm install
```

### 2. Development Mode

Start the Vite development server:

```bash
npm run dev
```

The dev server runs on `http://localhost:5173` and provides hot module replacement.

In your WordPress installation, ensure `WP_DEBUG` is enabled to load the Vite dev server instead of built assets.

### 3. Build for Production

Build the optimized production bundle:

```bash
npm run build
```

This will output files to `assets/js/` and `assets/css/` directories.

### 4. Type Checking

Run TypeScript type checking:

```bash
npm run check
```

## Architecture

### Core Files

- **package.json** - NPM dependencies and scripts
- **vite.config.ts** - Vite build configuration
- **tsconfig.json** - TypeScript configuration
- **svelte.config.js** - Svelte preprocessor configuration

### Source Structure

```
src/
├── main.ts                     # Application entry point
├── App.svelte                  # Root Svelte component
├── app.css                     # Global styles
├── lib/
│   ├── types.ts               # TypeScript type definitions
│   ├── api.ts                 # REST API service layer
│   └── components/
│       ├── AssetBrowser.svelte    # Main asset library view
│       ├── AssetCard.svelte       # Individual asset card
│       ├── AssetUpload.svelte     # Drag & drop upload
│       ├── AssetEditor.svelte     # Asset metadata editor
│       ├── AssetPicker.svelte     # Modal asset selector
│       ├── FilterPanel.svelte     # Sidebar filters
│       └── FocalPointPicker.svelte # Visual focal point selector
```

## Components

### AssetBrowser

Main component displaying the asset library with:
- Grid/list view toggle
- Search functionality
- Pagination
- Bulk selection and deletion
- Filter integration

### AssetCard

Displays individual assets with:
- Thumbnail preview
- File metadata (size, dimensions)
- Tag display
- Selection checkbox
- Click to edit

### AssetUpload

Drag and drop upload interface with:
- Multiple file support
- Progress tracking
- Error handling
- Upload queue management

### AssetEditor

Modal editor for asset metadata:
- Title and description
- Tags management
- Image-specific fields (alt text, caption)
- Focal point picker integration
- Credit and copyright info

### AssetPicker

Modal for selecting assets from Gutenberg, ACF, etc:
- Single or multiple selection modes
- MIME type filtering
- Search and filter integration
- Compact grid layout

### FilterPanel

Sidebar filtering with:
- File type filters
- Tag management
- Date range selection
- Clear all filters

### FocalPointPicker

Visual focal point selector for images:
- Click or drag to set point
- Crosshair visualization
- Coordinate display
- Reset to center

## API Integration

The `api.ts` service provides methods for:

- `getAssets(params)` - Fetch assets with filters
- `searchAssets(query, params)` - Search assets
- `getAsset(id)` - Get single asset
- `uploadAsset(file, metadata, onProgress)` - Upload with progress
- `updateAsset(id, metadata)` - Update asset metadata
- `deleteAsset(id)` - Delete asset

All API calls use WordPress REST API with nonce authentication.

## WordPress Integration

### PHP Side

The plugin's `class-plugin.php` file handles:

1. **Development Mode**: Loads Vite dev server at `localhost:5173`
2. **Production Mode**: Loads built assets from `assets/js/`
3. **Configuration**: Passes `damConfig` object to JavaScript:
   ```php
   wp_localize_script('dam-admin-app', 'damConfig', [
       'restUrl' => rest_url('dam/v1'),
       'nonce' => wp_create_nonce('wp_rest'),
       'cdnUrl' => ...,
       'maxFileSize' => ...,
       'allowedMimeTypes' => [...]
   ]);
   ```

### Manual Updates Needed

You'll need to manually update `includes/class-plugin.php`:

1. Change line 89 from:
   ```php
   echo '<div id="dam-admin-app"></div>';
   ```
   to:
   ```php
   echo '<div id="dam-app"></div>';
   ```

2. Change line 147 from:
   ```php
   'apiUrl' => rest_url('dam/v1'),
   ```
   to:
   ```php
   'restUrl' => rest_url('dam/v1'),
   ```

3. Add additional config parameters after line 151:
   ```php
   'cdnUrl' => $this->get_settings()['cdn_url'] ?? '',
   'maxFileSize' => 100 * 1024 * 1024, // 100MB
   'allowedMimeTypes' => [
       'image/jpeg',
       'image/png',
       'image/gif',
       'image/webp',
       'video/mp4',
       'video/webm',
       'audio/mpeg',
       'audio/wav',
       'application/pdf'
   ],
   ```

## Styling

The UI uses WordPress admin color scheme:
- Primary: `#2271b1`
- Text: `#1d2327`
- Border: `#c3c4c7`
- Background: `#f0f0f1`

Styles are scoped to `.dam-app` to avoid conflicts with WordPress admin CSS.

## Features

### Current Features
- Asset browsing with grid/list views
- Search and filtering
- Drag & drop upload with progress
- Asset metadata editing
- Focal point selection for images
- Tag management
- Bulk operations
- Pagination

### Future Enhancements
- Image editing (crop, resize)
- Video thumbnail generation
- AI-powered tagging
- Advanced search (faceted)
- Collections/folders
- Asset versioning
- Usage tracking visualization
- CDN integration

## Build Output

Production build creates:
- `assets/js/dam-admin.js` - Main JavaScript bundle
- `assets/css/dam-admin.css` - Compiled CSS
- `assets/js/manifest.json` - Build manifest for PHP

Files are optimized with:
- Code splitting for better performance
- Tree shaking to remove unused code
- Minification
- Source maps for debugging

## Browser Support

Modern browsers with ES6+ support:
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+

## Development Tips

1. **Hot Module Replacement**: Changes to Svelte files auto-reload in dev mode
2. **TypeScript**: Use strict type checking for better DX
3. **Component Props**: Use Svelte 5's `$props()` rune for type-safe props
4. **Reactive State**: Use `$state()` for reactive variables
5. **Effects**: Use `$effect()` for side effects and lifecycle

## Troubleshooting

### Assets not loading
- Check `WP_DEBUG` is enabled for dev mode
- Verify Vite dev server is running on port 5173
- Check browser console for errors

### Type errors
- Run `npm run check` to see all TypeScript errors
- Ensure `@types` packages are installed

### Build errors
- Clear `node_modules` and reinstall
- Check Node.js version (16+ required)
- Verify all imports are correct

## License

GPL v2 or later
