TenantAtlas/app/Support/Ui/ActionSurface/ActionSurfaceDeclaration.php

<?php

declare(strict_types=1);

namespace App\Support\Ui\ActionSurface;

use App\Support\Ui\ActionSurface\Enums\ActionSurfaceComponentType;
use App\Support\Ui\ActionSurface\Enums\ActionSurfaceProfile;
use App\Support\Ui\ActionSurface\Enums\ActionSurfaceSlot;
use App\Support\Ui\ActionSurface\Enums\ActionSurfaceType;

final class ActionSurfaceDeclaration
{
    private const int BEHAVIOR_AWARE_VERSION = 2;

    private const string LIST_ROW_PRIMARY_ACTION_LIMIT = 'list_row_primary_action_limit';

    private const string PRIMARY_LINK_COLUMN_REASON = 'primary_link_column_reason';

    /**
     * @var array<string, ActionSurfaceSlotRequirement>
     */
    private array $slots = [];

    /**
     * @var array<string, ActionSurfaceExemption>
     */
    private array $exemptions = [];

    /**
     * @var array<string, mixed>
     */
    private array $metadata = [];

    public ActionSurfaceDefaults $defaults;

    public function __construct(
        public readonly int $version,
        public readonly ActionSurfaceComponentType $componentType,
        public readonly ActionSurfaceProfile $profile,
        public readonly ?ActionSurfaceType $surfaceType = null,
        ?ActionSurfaceDefaults $defaults = null,
    ) {
        $this->defaults = $defaults ?? new ActionSurfaceDefaults;
    }

    public static function make(
        ActionSurfaceComponentType $componentType,
        ActionSurfaceProfile $profile,
        ?ActionSurfaceType $surfaceType = null,
        int $version = 1,
    ): self {
        return new self(
            version: self::normalizedVersion($surfaceType, $version),
            componentType: $componentType,
            profile: $profile,
            surfaceType: $surfaceType,
        );
    }

    public static function forResource(
        ActionSurfaceProfile $profile,
        ?ActionSurfaceType $surfaceType = null,
        int $version = 1,
    ): self {
        return self::make(ActionSurfaceComponentType::Resource, $profile, $surfaceType, $version);
    }

    public static function forPage(
        ActionSurfaceProfile $profile,
        ?ActionSurfaceType $surfaceType = null,
        int $version = 1,
    ): self {
        return self::make(ActionSurfaceComponentType::Page, $profile, $surfaceType, $version);
    }

    public static function forRelationManager(
        ActionSurfaceProfile $profile,
        ?ActionSurfaceType $surfaceType = null,
        int $version = 1,
    ): self {
        return self::make(ActionSurfaceComponentType::RelationManager, $profile, $surfaceType, $version);
    }

    public function withSurfaceType(ActionSurfaceType $surfaceType): self
    {
        return $this->replicate(
            surfaceType: $surfaceType,
            version: self::normalizedVersion($surfaceType, $this->version),
        );
    }

    public function withDefaults(ActionSurfaceDefaults $defaults): self
    {
        $this->defaults = $defaults;

        return $this;
    }

    public function setSlot(ActionSurfaceSlot $slot, ActionSurfaceSlotRequirement $requirement): self
    {
        $this->slots[$slot->value] = $requirement;

        return $this;
    }

    public function satisfy(
        ActionSurfaceSlot $slot,
        ?string $details = null,
        bool $requiresTypedConfirmation = false,
    ): self {
        return $this->setSlot($slot, ActionSurfaceSlotRequirement::satisfied($details, $requiresTypedConfirmation));
    }

    public function exempt(
        ActionSurfaceSlot $slot,
        string $reason,
        ?string $trackingRef = null,
        ?string $details = null,
    ): self {
        $this->setSlot($slot, ActionSurfaceSlotRequirement::exempt($details));
        $this->exemptions[$slot->value] = new ActionSurfaceExemption($slot, $reason, $trackingRef);

        return $this;
    }

    public function slot(ActionSurfaceSlot $slot): ?ActionSurfaceSlotRequirement
    {
        return $this->slots[$slot->value] ?? null;
    }

    public function exemption(ActionSurfaceSlot $slot): ?ActionSurfaceExemption
    {
        return $this->exemptions[$slot->value] ?? null;
    }

    public function setMetadata(string $key, mixed $value): self
    {
        $this->metadata[$key] = $value;

        return $this;
    }

    public function metadata(string $key, mixed $default = null): mixed
    {
        return $this->metadata[$key] ?? $default;
    }

    public function withListRowPrimaryActionLimit(int $limit): self
    {
        return $this->setMetadata(self::LIST_ROW_PRIMARY_ACTION_LIMIT, $limit);
    }

    public function listRowPrimaryActionLimit(): ?int
    {
        $limit = $this->metadata(self::LIST_ROW_PRIMARY_ACTION_LIMIT);

        return is_int($limit) ? $limit : null;
    }

    public function withPrimaryLinkColumnReason(string $reason): self
    {
        return $this->setMetadata(self::PRIMARY_LINK_COLUMN_REASON, $reason);
    }

    public function primaryLinkColumnReason(): ?string
    {
        $reason = $this->metadata(self::PRIMARY_LINK_COLUMN_REASON);

        return is_string($reason) ? $reason : null;
    }

    public function requiresBehaviorAwareContract(): bool
    {
        return $this->version >= self::BEHAVIOR_AWARE_VERSION;
    }

    /**
     * @return array<string, ActionSurfaceSlotRequirement>
     */
    public function slots(): array
    {
        return $this->slots;
    }

    /**
     * @return array<string, ActionSurfaceExemption>
     */
    public function exemptions(): array
    {
        return $this->exemptions;
    }

    /**
     * @return array<string, mixed>
     */
    public function metadataValues(): array
    {
        return $this->metadata;
    }

    private static function normalizedVersion(?ActionSurfaceType $surfaceType, int $version): int
    {
        if (! $surfaceType instanceof ActionSurfaceType) {
            return $version;
        }

        return max(self::BEHAVIOR_AWARE_VERSION, $version);
    }

    private function replicate(?ActionSurfaceType $surfaceType, int $version): self
    {
        $declaration = new self(
            version: $version,
            componentType: $this->componentType,
            profile: $this->profile,
            surfaceType: $surfaceType,
            defaults: $this->defaults,
        );

        $declaration->slots = $this->slots;
        $declaration->exemptions = $this->exemptions;
        $declaration->metadata = $this->metadata;

        return $declaration;
    }
}