<?php

declare(strict_types=1);

namespace Drupal\sobki_admin\Service;

use Drupal\layout_builder\SectionComponent;
use Drupal\layout_builder\SectionStorageInterface;

/**
 * A helper service that looks up additional information about layout sections.
 *
 * Hopefully we won't need this forever.
 *
 * @see https://www.drupal.org/project/drupal/issues/3279716
 */
interface LayoutContextHelperInterface {

  /**
   * Gets the underlying entity type id of the provided section.
   *
   * @param \Drupal\layout_builder\SectionStorageInterface $section
   *   The section to look up info on.
   *
   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
   *   Should never happen.
   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
   *   Should never happen.
   *
   * @return string|null
   *   The underlying entity type id, or NULL if unavailable.
   */
  public static function getHostEntityTypeId(SectionStorageInterface $section): ?string;

  /**
   * Gets the underlying entity bundle of the provided section.
   *
   * @param \Drupal\layout_builder\SectionStorageInterface $section
   *   The section to look up info on.
   *
   * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
   *   Should never happen.
   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
   *   Should never happen.
   *
   * @return string|null
   *   The underlying entity bundle, or NULL if unavailable.
   */
  public static function getHostEntityBundle(SectionStorageInterface $section): ?string;

  /**
   * Gets the type of the current block that's being edited.
   *
   * If the block renders "block_content", the bundle is returned, otherwise
   * the block's plugin ID is returned.
   *
   * @param \Drupal\layout_builder\SectionComponent $component
   *   The section component that is currently being edited.
   *
   * @throws \Drupal\Core\Entity\EntityStorageException
   *   Should never happen.
   *
   * @return string|null
   *   The type of the current block.
   */
  public static function getBlockType(SectionComponent $component): ?string;

}
