<?php
declare(strict_types=1);

namespace ProudNerds\Block;


interface Block
{
    public const CATEGORY_SITE = 'proudnerds';
    public const CATEGORY_COMMON = 'common';
    public const CATEGORY_FORMATTING = 'formatting';
    public const CATEGORY_LAYOUT = 'layout';
    public const CATEGORY_WIDGETS = 'widgets';
    public const CATEGORY_EMBED = 'embed';

    public const NAME_PREFIX = 'acf/';

    /**
     * The internal slug name
     *
     * This name is also used to load the template name
     *
     * @return string
     */
    public function getSlug(): string;

    /**
     * The internal  name with acf prefix
     *
     * @return string
     */
    public function getName(): string;

    /**
     * The user-friendly title
     *
     * As shown in the Wordpress 'Add block' menu and when selecting or
     * identifying blocks in the editor.
     */
    public function getTitle(): string;

    /**
     * The user-friendly description
     *
     * This as shown in the sidemenu of the Wordpress admin when the block
     * is selected.
     */
    public function getDescription(): string;

    /**
     * The category slug
     *
     * This is the category in which the block is shown in the 'Add block'
     * menu. You may choose from the Block::CATEGORY_* constants.
     * Use Block::CATEGORY_SITE to use the current site name as category.
     */
    public function getCategory(): string;

    /**
     * The icon
     *
     * This is the DashIcon classname without the 'dashicons-' prefix.
     * This icon is shown in the Wordpress 'Add block' menu.
     * See https://developer.wordpress.org/resource/dashicons/
     *
     * Alternatively, you can return an SVG string.
     */
    public function getIcon(): string;

    /**
     * The icon background color
     *
     * This is a html color name or hex code. This color is shown as background
     * for the block button in the Wordpress 'Add block' menu.
     *
     * Return null to not use a background color.
     */
    public function getIconBackgroundColor(): ?string;

    /**
     * An array of keywords
     *
     * These keywords are used when searching for a block in the Wordpress
     * 'Add block' menu.
     *
     * This is optional, if no keywords are needed, return an empty array.
     */
    public function getKeywords(): array;

    /**
     * Return true if you want the user to have the possibility to edit
     * the variables of the block in-place. By default, you can return false.
     */
    public function hasModeSwitch(): bool;

    /**
     * Return true if you want to enable jsx rendering for this block.
     * This is necessary for blocks that want to support <innerblocks />
     */
    public function enableJSX(): bool;

    /**
     * Update the block context
     *
     * Here, you can add, remove or change the context before it is
     * passed to Twig (within twig, access this context by using
     * {{ block }}
     *
     * @param Context $context
     */
    public function extendContext(Context $context): void;


    /**
     * Set the post types on which this block is available
     *
     * Return an array of post-type strings to only make this block
     * available on those post types.
     * Return null to allow this block on all post types.
     *
     */
    public function getAllowedPostTypes(): ?array;

    /**
     * Set the page templates on which this block is available
     *
     * Return an array of page template filenames to only make this block
     * available on those page templates, e.g.
     * return ['page-contact.php'];
     * Return null to allow this block on all post types.
     *
     */
    public function getAllowedPageTemplates(): ?array;

    /**
     * Is this block active and allowed to be registered?
     *
     * Return false to disable registring this block.
     */
    public function isActive(): bool;
}
