<?php

declare(strict_types=1);

namespace App\Framework\LiveComponents\Attributes;

use Attribute;

/**
 * Explicitly disables state encryption for a LiveComponent
 *
 * By default, ALL LiveComponent state data is encrypted for security.
 * This attribute allows opt-out for performance-critical components with non-sensitive data.
 *
 * Framework Principles:
 * - Security by default (encryption is standard)
 * - Explicit opt-out (must consciously disable encryption)
 * - Readonly attribute class
 * - No inheritance
 *
 * ⚠️ WARNING: Only use this for components with:
 * - No personal identifiable information (PII)
 * - No payment information
 * - No health records
 * - No confidential business data
 * - Public or non-sensitive data only
 *
 * Valid Use Cases:
 * - Simple counters (e.g., click counters)
 * - UI state (e.g., accordion open/closed)
 * - Non-sensitive filters (e.g., search filters)
 * - Public data displays
 *
 * Performance Impact:
 * - Saves ~5-10ms per state serialize/deserialize operation
 * - Only use if encryption overhead is measurably problematic
 *
 * Example:
 * ```php
 * #[UnencryptedState(reason: 'Simple counter with no sensitive data')]
 * final readonly class ClickCounterComponent implements LiveComponentContract
 * {
 *     public function __construct(
 *         public CounterState $state
 *     ) {}
 * }
 * ```
 *
 * Security Notes:
 * - This attribute will be logged for security auditing
 * - Requires explicit reason for disabling encryption
 * - Should be reviewed during security audits
 *
 * @see EncryptedStateSerializer For encryption implementation
 */
#[Attribute(Attribute::TARGET_CLASS)]
final readonly class UnencryptedState
{
    /**
     * @param string $reason Required justification for disabling encryption (for security audit trail)
     */
    public function __construct(
        public string $reason
    ) {
        if (empty(trim($reason))) {
            throw new \InvalidArgumentException(
                '#[UnencryptedState] requires explicit reason for disabling encryption. ' .
                'Example: #[UnencryptedState(reason: "Simple counter with no sensitive data")]'
            );
        }
    }
}
