<?php

declare(strict_types=1);

namespace Builder\Core\Foundation\Contracts;

use Builder\Core\Foundation\Concerns\HasTranslations;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Support\Collection;

/**
 * Contract for Eloquent models that support per-locale translations.
 *
 * The standard implementation is the {@see HasTranslations} trait.
 * Use this interface for type-hinting in services and controllers so they
 * remain decoupled from the concrete trait implementation.
 */
interface Translatable
{
    public function getTranslationTable(): string;

    public function getTranslationForeignKey(): string;

    public function translationModelClass(): string;

    /** @return HasMany<Model, Model> */
    public function translations(): HasMany;

    /** @return list<string> */
    public function getTranslatableAttributes(): array;

    public function getTranslation(string $locale): ?Model;

    /** @param array<string, mixed> $attributes */
    public function setTranslation(string $locale, array $attributes): void;

    /** @return Collection<string, Model> */
    public function getTranslations(): Collection;

    public function hasTranslation(string $locale): bool;

    /** @return array<string, string|null> */
    public function hreflangData(string $slugField = 'slug'): array;

    public function canonicalUrl(?string $locale = null, string $slugField = 'slug'): ?string;
}
