# Story 5.1: Post Creation & Editing

## Epic Reference
**Epic 5:** Posts/Blog System

## User Story
As an **admin**,
I want **to create and edit blog posts with rich text formatting**,
So that **I can publish professional legal content for website visitors**.

## Story Context

### Existing System Integration
- **Integrates with:** posts table
- **Technology:** Livewire Volt, TinyMCE or similar rich text editor
- **Follows pattern:** Admin CRUD pattern
- **Touch points:** Public posts display

## Acceptance Criteria

### Post Creation Form
- [x] Title (required, bilingual: Arabic and English)
- [x] Body content (required, bilingual)
- [x] Status (draft/published)

### Rich Text Editor
- [x] Bold, italic, underline
- [x] Headings (H2, H3)
- [x] Bullet and numbered lists
- [x] Links
- [x] Blockquotes

### Saving Features
- [x] Save as draft functionality
- [x] Preview post before publishing
- [x] Edit published posts
- [x] Auto-save draft periodically (every 60 seconds)
- [x] Immediate publishing (no scheduling)

### Timestamps
- [x] created_at recorded on creation
- [x] updated_at updated on edit

### Quality Requirements
- [x] HTML sanitization for XSS prevention
- [x] Bilingual form labels
- [x] Audit log for create/edit
- [x] Tests for CRUD operations

## Technical Notes

### HTML Sanitization
Use the `mews/purifier` package for HTML sanitization via the `clean()` helper:
```bash
composer require mews/purifier
php artisan vendor:publish --provider="Mews\Purifier\PurifierServiceProvider"
```

Configure `config/purifier.php` to allow only safe rich text tags:
```php
'default' => [
    'HTML.Allowed' => 'h2,h3,p,br,b,strong,i,em,u,ul,ol,li,a[href|title],blockquote',
    'AutoFormat.AutoParagraph' => true,
    'AutoFormat.RemoveEmpty' => true,
],
```

### Database Schema
```php
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title_ar');
    $table->string('title_en');
    $table->text('body_ar');
    $table->text('body_en');
    $table->enum('status', ['draft', 'published'])->default('draft');
    $table->timestamps();
});
```

### Post Model
```php
class Post extends Model
{
    protected $fillable = [
        'title_ar', 'title_en', 'body_ar', 'body_en', 'status',
    ];

    public function getTitleAttribute(): string
    {
        $locale = app()->getLocale();
        return $this->{"title_{$locale}"} ?? $this->title_en;
    }

    public function getBodyAttribute(): string
    {
        $locale = app()->getLocale();
        return $this->{"body_{$locale}"} ?? $this->body_en;
    }

    public function getExcerptAttribute(): string
    {
        return Str::limit(strip_tags($this->body), 150);
    }

    public function scopePublished($query)
    {
        return $query->where('status', 'published');
    }

    public function scopeDraft($query)
    {
        return $query->where('status', 'draft');
    }
}
```

### Volt Component
```php
<?php

use App\Models\Post;
use Livewire\Volt\Component;

new class extends Component {
    public ?Post $post = null;

    public string $title_ar = '';
    public string $title_en = '';
    public string $body_ar = '';
    public string $body_en = '';
    public string $status = 'draft';

    public function mount(?Post $post = null): void
    {
        if ($post?->exists) {
            $this->post = $post;
            $this->fill($post->only([
                'title_ar', 'title_en', 'body_ar', 'body_en', 'status'
            ]));
        }
    }

    public function save(): void
    {
        $validated = $this->validate([
            'title_ar' => ['required', 'string', 'max:255'],
            'title_en' => ['required', 'string', 'max:255'],
            'body_ar' => ['required', 'string'],
            'body_en' => ['required', 'string'],
            'status' => ['required', 'in:draft,published'],
        ]);

        // Sanitize HTML
        $validated['body_ar'] = clean($validated['body_ar']);
        $validated['body_en'] = clean($validated['body_en']);

        if ($this->post) {
            $this->post->update($validated);
            $action = 'update';
        } else {
            $this->post = Post::create($validated);
            $action = 'create';
        }

        // AdminLog model exists from Epic 1 (Story 1.1) - see admin_logs table in schema
        \App\Models\AdminLog::create([
            'admin_id' => auth()->id(),
            'action_type' => $action,
            'target_type' => 'post',
            'target_id' => $this->post->id,
            'ip_address' => request()->ip(),
        ]);

        session()->flash('success', __('messages.post_saved'));
    }

    public function saveDraft(): void
    {
        $this->status = 'draft';
        $this->save();
    }

    public function publish(): void
    {
        $this->status = 'published';
        $this->save();
    }

    public function autoSave(): void
    {
        if ($this->post && $this->status === 'draft') {
            $this->post->update([
                'title_ar' => $this->title_ar,
                'title_en' => $this->title_en,
                'body_ar' => clean($this->body_ar),
                'body_en' => clean($this->body_en),
            ]);
        }
    }

    // Preview opens modal with sanitized rendered content
    public bool $showPreview = false;

    public function preview(): void
    {
        $this->showPreview = true;
    }

    public function closePreview(): void
    {
        $this->showPreview = false;
    }
};
```

### Template with Rich Text Editor
```blade
{{-- wire:poll.60s triggers autoSave every 60 seconds for draft posts --}}
<div wire:poll.60s="autoSave">
    <div class="grid grid-cols-1 lg:grid-cols-2 gap-6">
        <!-- Arabic Fields -->
        <div class="space-y-4">
            <flux:heading size="sm">{{ __('admin.arabic_content') }}</flux:heading>

            <flux:field>
                <flux:label>{{ __('admin.title') }} (عربي) *</flux:label>
                <flux:input wire:model="title_ar" dir="rtl" />
                <flux:error name="title_ar" />
            </flux:field>

            <flux:field>
                <flux:label>{{ __('admin.body') }} (عربي) *</flux:label>
                <div wire:ignore>
                    <trix-editor
                        x-data
                        x-on:trix-change="$wire.set('body_ar', $event.target.value)"
                        dir="rtl"
                    >{!! $body_ar !!}</trix-editor>
                </div>
                <flux:error name="body_ar" />
            </flux:field>
        </div>

        <!-- English Fields -->
        <div class="space-y-4">
            <flux:heading size="sm">{{ __('admin.english_content') }}</flux:heading>

            <flux:field>
                <flux:label>{{ __('admin.title') }} (English) *</flux:label>
                <flux:input wire:model="title_en" />
                <flux:error name="title_en" />
            </flux:field>

            <flux:field>
                <flux:label>{{ __('admin.body') }} (English) *</flux:label>
                <div wire:ignore>
                    <trix-editor
                        x-data
                        x-on:trix-change="$wire.set('body_en', $event.target.value)"
                    >{!! $body_en !!}</trix-editor>
                </div>
                <flux:error name="body_en" />
            </flux:field>
        </div>
    </div>

    <div class="flex gap-3 mt-6">
        <flux:button wire:click="saveDraft">
            {{ __('admin.save_draft') }}
        </flux:button>
        <flux:button wire:click="preview">
            {{ __('admin.preview') }}
        </flux:button>
        <flux:button variant="primary" wire:click="publish">
            {{ __('admin.publish') }}
        </flux:button>
    </div>

    {{-- Preview Modal --}}
    <flux:modal wire:model="showPreview" class="max-w-4xl">
        <flux:heading>{{ __('admin.preview') }}</flux:heading>
        <div class="mt-4 space-y-6">
            <div class="border-b pb-4">
                <h3 class="font-semibold text-lg mb-2">{{ __('admin.arabic_content') }}</h3>
                <h2 class="text-xl font-bold" dir="rtl">{{ $title_ar }}</h2>
                <div class="prose mt-2" dir="rtl">{!! clean($body_ar) !!}</div>
            </div>
            <div>
                <h3 class="font-semibold text-lg mb-2">{{ __('admin.english_content') }}</h3>
                <h2 class="text-xl font-bold">{{ $title_en }}</h2>
                <div class="prose mt-2">{!! clean($body_en) !!}</div>
            </div>
        </div>
        <div class="mt-6 flex justify-end">
            <flux:button wire:click="closePreview">{{ __('admin.close') }}</flux:button>
        </div>
    </flux:modal>
</div>
```

### Trix Editor Setup
Include Trix editor assets in your layout or component:
```blade
{{-- In your layout head --}}
<link rel="stylesheet" href="https://unpkg.com/trix@2.0.0/dist/trix.css">
<script src="https://unpkg.com/trix@2.0.0/dist/trix.umd.min.js"></script>
```

## Definition of Done

- [x] Can create post with bilingual content
- [x] Rich text editor works
- [x] Can save as draft
- [x] Can publish directly
- [x] Can edit existing posts
- [x] Auto-save works for drafts
- [x] Preview modal displays sanitized content
- [x] HTML properly sanitized
- [x] Audit log created
- [x] Tests pass
- [x] Code formatted with Pint

## Test Scenarios

### Unit Tests (Post Model)
```php
test('post has bilingual title accessor', function () {
    $post = Post::factory()->create(['title_ar' => 'عنوان', 'title_en' => 'Title']);
    app()->setLocale('ar');
    expect($post->title)->toBe('عنوان');
    app()->setLocale('en');
    expect($post->title)->toBe('Title');
});

test('post excerpt strips HTML and limits to 150 chars', function () {
    $post = Post::factory()->create(['body_en' => '<p>' . str_repeat('a', 200) . '</p>']);
    expect(strlen($post->excerpt))->toBeLessThanOrEqual(153); // 150 + '...'
    expect($post->excerpt)->not->toContain('<p>');
});

test('published scope returns only published posts', function () {
    Post::factory()->create(['status' => 'draft']);
    Post::factory()->create(['status' => 'published']);
    expect(Post::published()->count())->toBe(1);
});
```

### Feature Tests (Volt Component)
```php
use Livewire\Volt\Volt;

test('admin can create post with valid bilingual content', function () {
    $admin = User::factory()->admin()->create();

    Volt::test('admin.posts.create')
        ->actingAs($admin)
        ->set('title_ar', 'عنوان المقال')
        ->set('title_en', 'Article Title')
        ->set('body_ar', '<p>محتوى المقال</p>')
        ->set('body_en', '<p>Article content</p>')
        ->call('saveDraft')
        ->assertHasNoErrors();

    expect(Post::where('title_en', 'Article Title')->exists())->toBeTrue();
});

test('create post fails with missing required fields', function () {
    $admin = User::factory()->admin()->create();

    Volt::test('admin.posts.create')
        ->actingAs($admin)
        ->set('title_ar', '')
        ->set('title_en', 'Title')
        ->call('save')
        ->assertHasErrors(['title_ar']);
});

test('save draft preserves draft status', function () {
    $admin = User::factory()->admin()->create();

    Volt::test('admin.posts.create')
        ->actingAs($admin)
        ->set('title_ar', 'عنوان')
        ->set('title_en', 'Title')
        ->set('body_ar', 'محتوى')
        ->set('body_en', 'Content')
        ->call('saveDraft');

    expect(Post::first()->status)->toBe('draft');
});

test('publish changes status to published', function () {
    $admin = User::factory()->admin()->create();

    Volt::test('admin.posts.create')
        ->actingAs($admin)
        ->set('title_ar', 'عنوان')
        ->set('title_en', 'Title')
        ->set('body_ar', 'محتوى')
        ->set('body_en', 'Content')
        ->call('publish');

    expect(Post::first()->status)->toBe('published');
});

test('edit existing post updates content', function () {
    $admin = User::factory()->admin()->create();
    $post = Post::factory()->create(['title_en' => 'Original']);

    Volt::test('admin.posts.edit', ['post' => $post])
        ->actingAs($admin)
        ->set('title_en', 'Updated')
        ->call('save')
        ->assertHasNoErrors();

    expect($post->fresh()->title_en)->toBe('Updated');
});

test('auto-save only fires for draft posts', function () {
    $admin = User::factory()->admin()->create();
    $post = Post::factory()->create(['status' => 'published', 'title_en' => 'Original']);

    Volt::test('admin.posts.edit', ['post' => $post])
        ->actingAs($admin)
        ->set('title_en', 'Changed')
        ->call('autoSave');

    // Published post should NOT be auto-saved
    expect($post->fresh()->title_en)->toBe('Original');
});

test('HTML sanitization removes script tags but keeps allowed formatting', function () {
    $admin = User::factory()->admin()->create();

    Volt::test('admin.posts.create')
        ->actingAs($admin)
        ->set('title_ar', 'عنوان')
        ->set('title_en', 'Title')
        ->set('body_ar', '<p>نص</p>')
        ->set('body_en', '<p>Safe</p><script>alert("xss")</script><strong>Bold</strong>')
        ->call('saveDraft');

    $post = Post::first();
    expect($post->body_en)->not->toContain('<script>');
    expect($post->body_en)->toContain('<strong>Bold</strong>');
});

test('admin log created on post create', function () {
    $admin = User::factory()->admin()->create();

    Volt::test('admin.posts.create')
        ->actingAs($admin)
        ->set('title_ar', 'عنوان')
        ->set('title_en', 'Title')
        ->set('body_ar', 'محتوى')
        ->set('body_en', 'Content')
        ->call('saveDraft');

    expect(AdminLog::where('action_type', 'create')->where('target_type', 'post')->exists())->toBeTrue();
});

test('preview modal can be opened and closed', function () {
    $admin = User::factory()->admin()->create();

    Volt::test('admin.posts.create')
        ->actingAs($admin)
        ->assertSet('showPreview', false)
        ->call('preview')
        ->assertSet('showPreview', true)
        ->call('closePreview')
        ->assertSet('showPreview', false);
});
```

## Dependencies

- **Epic 1:** Database schema, admin authentication

## Estimation

**Complexity:** Medium
**Estimated Effort:** 4-5 hours

---

## Dev Agent Record

### Status
**Ready for Review**

### Agent Model Used
Claude Opus 4.5 (claude-opus-4-5-20251101)

### File List

**New Files:**
- `config/purifier.php` - HTML Purifier configuration for XSS prevention
- `resources/views/livewire/admin/posts/index.blade.php` - Posts listing Volt component
- `resources/views/livewire/admin/posts/create.blade.php` - Post creation Volt component with Trix editor
- `resources/views/livewire/admin/posts/edit.blade.php` - Post editing Volt component with Trix editor
- `lang/en/posts.php` - English translations for posts module
- `lang/ar/posts.php` - Arabic translations for posts module
- `tests/Feature/Admin/PostManagementTest.php` - Feature tests for post CRUD operations (30 tests)

**Modified Files:**
- `app/Models/Post.php` - Added `getExcerpt()` method
- `routes/web.php` - Added admin posts routes
- `lang/en/common.php` - Added 'close' translation
- `lang/ar/common.php` - Added 'close' translation
- `lang/en/enums.php` - Added post_status translations
- `lang/ar/enums.php` - Added post_status translations

### Change Log
1. Published and configured `mews/purifier` for HTML sanitization with allowed tags: h2, h3, p, br, b, strong, i, em, u, ul, ol, li, a[href|title], blockquote
2. Added `getExcerpt()` method to Post model for generating text excerpts
3. Created admin posts index page with filtering by status and search functionality
4. Created admin posts create page with Trix rich text editor, preview modal, and save draft/publish actions
5. Created admin posts edit page with auto-save (60s) for drafts, preview modal, and publish/unpublish actions
6. Added admin posts routes under `/admin/posts` prefix
7. Added bilingual translations (ar/en) for all post-related UI strings
8. Implemented audit logging via AdminLog for create/update actions
9. Wrote comprehensive feature tests covering CRUD, validation, authorization, and HTML sanitization

### Completion Notes
- Post model already existed with JSON columns for bilingual title/body (different from story's suggested schema with separate columns - existing implementation is better)
- PostFactory and PostStatus enum already existed
- Used Trix editor (as suggested in story) via CDN with file upload toolbar hidden
- Auto-save only triggers for draft posts to prevent accidental changes to published content
- All 671 tests pass (30 new tests added for this story)

---

## QA Results

### Review Date: 2025-12-27

### Reviewed By: Quinn (Test Architect)

### Code Quality Assessment

**Overall Grade: Excellent**

The implementation demonstrates high quality across all dimensions. The code follows established patterns in the codebase, uses appropriate architectural decisions (JSON columns for bilingual content instead of separate columns), and includes comprehensive test coverage with 30 passing tests.

**Key Strengths:**
1. **Architecture**: JSON columns for bilingual content is cleaner than separate `_ar`/`_en` columns
2. **Security**: HTML sanitization via `mews/purifier` is properly configured with appropriate allowed tags
3. **Testing**: Comprehensive 30-test suite covering CRUD, authorization, validation, and model behavior
4. **UX**: Auto-save for drafts (60s interval), preview modal, and proper status management
5. **Bilingual Support**: Complete translations in both English and Arabic for all UI strings

### Refactoring Performed

None required - code quality is excellent as-is.

### Compliance Check

- Coding Standards: ✓ Code follows Laravel/Livewire conventions, uses Volt class-based pattern
- Project Structure: ✓ Files placed correctly in standard locations
- Testing Strategy: ✓ Feature tests using Pest and `Volt::test()` pattern
- All ACs Met: ✓ All 20 acceptance criteria items checked in story file

### Improvements Checklist

No mandatory improvements required. Optional considerations for future:

- [ ] Consider adding delete functionality (not in current AC scope)
- [ ] Consider adding image upload capability for blog posts (not in current AC scope)
- [ ] Consider extracting common Trix editor setup to a reusable Blade component (minor DRY improvement)

### Requirements Traceability

| Acceptance Criteria | Test Coverage | Status |
|---------------------|---------------|--------|
| AC1: Title (bilingual) | `admin can create post with valid bilingual content`, `post has bilingual title accessor` | ✓ |
| AC2: Body content (bilingual) | `admin can create post with valid bilingual content`, `post has bilingual body accessor` | ✓ |
| AC3: Status (draft/published) | `save draft preserves draft status`, `publish changes status to published`, `posts list shows status badges` | ✓ |
| AC4-9: Rich Text Editor (bold, italic, headings, lists, links, blockquotes) | `HTML sanitization removes script tags but keeps allowed formatting` | ✓ |
| AC10: Save as draft | `save draft preserves draft status` | ✓ |
| AC11: Preview post | `preview modal can be opened and closed` | ✓ |
| AC12: Edit published posts | `edit existing post updates content` | ✓ |
| AC13: Auto-save (60s) | `auto-save only fires for draft posts`, `auto-save updates draft posts` | ✓ |
| AC14: Immediate publishing | `publish changes status to published` | ✓ |
| AC15-16: Timestamps | Verified in model via `$timestamps = true` | ✓ |
| AC17: HTML sanitization | `HTML sanitization removes script tags but keeps allowed formatting` | ✓ |
| AC18: Bilingual form labels | Verified in `lang/en/posts.php`, `lang/ar/posts.php` | ✓ |
| AC19: Audit log | `admin log created on post create`, `admin log created on post update` | ✓ |
| AC20: Tests for CRUD | 30 comprehensive tests covering all operations | ✓ |

### Security Review

**Status: PASS**

1. **XSS Prevention**: HTML Purifier configured with strict whitelist (`h2,h3,p,br,b,strong,i,em,u,ul,ol,li,a[href|title],blockquote`)
2. **Authorization**: Admin middleware protects all post management routes
3. **CSRF**: Livewire handles CSRF protection automatically
4. **Input Validation**: Server-side validation rules for all fields
5. **Audit Logging**: All create/update actions logged with IP address

**Security Tests Verified:**
- `non-admin cannot access posts index`
- `non-admin cannot access post creation`
- `non-admin cannot access post edit`
- `guest cannot access posts index`

### Performance Considerations

**Status: PASS**

1. **Auto-save optimization**: Only fires for draft posts, preventing unnecessary database writes
2. **Pagination**: Index page uses Laravel pagination with configurable per-page count
3. **Debounced search**: 300ms debounce on search input prevents excessive queries
4. **No N+1**: No eager loading needed as post data is self-contained

### Files Modified During Review

None - no modifications required.

### Gate Status

Gate: **PASS** → `docs/qa/gates/5.1-post-creation-editing.yml`

### Recommended Status

**✓ Ready for Done**

All acceptance criteria met, comprehensive test coverage (30 tests), proper security measures in place, and code quality is excellent. Story owner may proceed with marking as Done.
