<?php

declare(strict_types=1);

namespace App\Models\FormBuilder;

use App\Models\Scopes\FormFieldOptionScope;
use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\MorphTo;

/**
 * Relational home for RADIO / SELECT / MULTISELECT / CHECKBOX_LIST option
 * rows. See ARCH-FORM-BUILDER §17.6 (WS-5d) and addendum Q3.
 *
 * Polymorphic owner (`form_field` / `form_field_library` aliases — reused
 * from WS-5a). One row per (owner, value); duplicates are blocked by the
 * `ffo_owner_value_unique` index and at the service level by
 * `FormFieldOptionService::assertSpecsValid`. Per-locale translated labels
 * live on the row in the `translations` JSON bag.
 *
 * @property string                       $id
 * @property string                       $owner_type
 * @property string                       $owner_id
 * @property string                       $value
 * @property string                       $label
 * @property int                          $sort_order
 * @property array<string, string>|null   $translations
 * @property \Illuminate\Support\Carbon   $created_at
 * @property \Illuminate\Support\Carbon   $updated_at
 */
final class FormFieldOption extends Model
{
    use HasFactory;
    use HasUlids;

    protected $table = 'form_field_options';

    protected static function booted(): void
    {
        static::addGlobalScope(new FormFieldOptionScope());
    }

    protected $fillable = [
        'owner_type',
        'owner_id',
        'value',
        'label',
        'sort_order',
        'translations',
    ];

    /** @var array<string, string> */
    protected $casts = [
        'translations' => 'array',
        'sort_order' => 'int',
    ];

    public function owner(): MorphTo
    {
        return $this->morphTo('owner', 'owner_type', 'owner_id');
    }

    /**
     * Single source of truth for the per-row JSON shape consumed by
     * snapshot writer, API resources, and activity-log diff
     * reconstruction. Empty translations bag is omitted (preserves the
     * current contract for monolingual schemas).
     *
     * @return array{value:string,label:string,sort_order:int,translations?:array<string,string>}
     */
    public function toJsonShape(): array
    {
        $shape = [
            'value' => $this->value,
            'label' => $this->label,
            'sort_order' => $this->sort_order,
        ];

        if (is_array($this->translations) && $this->translations !== []) {
            $shape['translations'] = $this->translations;
        }

        return $shape;
    }
}