<?php

namespace App\FieldVisibility;

/**
 * Describes the authoritative set of fields and tabs that may be shown or hidden
 * on an admin edit page for a given entity type.
 */
interface FieldCatalogue
{
    /**
     * The entity slug this catalogue describes (e.g. "vehicle").
     */
    public function entity(): string;

    /**
     * Ordered list of field groups used to organise the editor UI.
     *
     * @return array<int, array{key: string, label: string}>
     */
    public function groups(): array;

    /**
     * The full list of configurable fields/tabs.
     *
     * @return array<int, array{key: string, label: string, group: string, lockable: bool}>
     */
    public function fields(): array;

    /**
     * Keys that may never be hidden (core/required fields).
     *
     * @return list<string>
     */
    public function lockableKeys(): array;

    /**
     * Keys that are allowed to be hidden.
     *
     * @return list<string>
     */
    public function hideableKeys(): array;
}
