<?php

declare(strict_types=1);

namespace App\Framework\LiveComponents\Contracts;

/**
 * LifecycleAware Interface
 *
 * Optional interface for LiveComponents that need lifecycle hooks.
 * Components can implement this interface to receive lifecycle callbacks.
 *
 * ⚠️ IMPORTANT: Lifecycle Hooks in Readonly Components
 *
 * Since components are readonly, lifecycle hooks CANNOT modify component state.
 * - All lifecycle hooks return void (no state modification)
 * - State changes ONLY via Actions that return ComponentData
 * - Use lifecycle hooks for side effects only:
 *   - Logging (error_log, logger->info)
 *   - External events (eventBus->dispatch)
 *   - External services (api calls, cache invalidation)
 *   - Resource management (open/close connections, start/stop timers)
 *
 * Usage:
 * ```php
 * final readonly class TimerComponent implements LiveComponentContract, LifecycleAware
 * {
 *     // ✅ CORRECT: Side effects only
 *     public function onMount(): void
 *     {
 *         error_log("Component {$this->id->toString()} mounted");
 *         $this->eventBus->dispatch(new ComponentMountedEvent($this->id));
 *     }
 *
 *     // ❌ WRONG: Cannot mutate state in readonly class
 *     public function onMount(): void
 *     {
 *         $this->data['mounted'] = true;  // PHP Error: Cannot modify readonly property!
 *     }
 *
 *     // ✅ CORRECT: State changes via Actions
 *     public function mount(): ComponentData
 *     {
 *         $state = $this->data->toArray();
 *         $state['mounted'] = true;
 *         return ComponentData::fromArray($state);
 *     }
 * }
 * ```
 *
 * Lifecycle Flow:
 * 1. onMount()   - Called once after component is first created (server-side)
 * 2. onUpdate()  - Called after each action that updates state
 * 3. onDestroy() - Called when component is removed (client-side via JavaScript)
 */
interface LifecycleAware
{
    /**
     * Called once after component is first mounted (server-side)
     *
     * ⚠️ SIDE EFFECTS ONLY - Cannot modify component state!
     *
     * Use for:
     * - Log component mount (error_log, logger)
     * - Dispatch domain events (eventBus->dispatch)
     * - Initialize external resources (open connections, start timers)
     * - Subscribe to external events
     * - Start background processes
     *
     * ❌ DO NOT: Modify $this->data or any component property
     * ✅ DO: External side effects only
     */
    public function onMount(): void;

    /**
     * Called after each state update (server-side)
     *
     * ⚠️ SIDE EFFECTS ONLY - Cannot modify component state!
     *
     * Use for:
     * - Log state transitions
     * - Dispatch state change events
     * - Update external resources (cache, search index)
     * - Sync with external services
     * - Validate state consistency (throw exceptions if invalid)
     *
     * ❌ DO NOT: Modify $this->data or return new state
     * ✅ DO: React to state changes with external side effects
     */
    public function onUpdate(): void;

    /**
     * Called before component is destroyed (client-side)
     *
     * ⚠️ SIDE EFFECTS ONLY - Cannot modify component state!
     *
     * Use for:
     * - Stop timers and background processes
     * - Close database connections
     * - Unsubscribe from events
     * - Cleanup resources
     * - Persist important state to storage
     * - Log component removal
     *
     * ❌ DO NOT: Modify $this->data or expect state changes
     * ✅ DO: Cleanup external resources
     *
     * Note: This hook is primarily called client-side via JavaScript
     * when component element is removed from DOM.
     */
    public function onDestroy(): void;
}
