<?php

declare(strict_types=1);

namespace Drupal\flowdrop_node_type\Service;

use Drupal\flowdrop_node_type\FlowDropNodeTypeInterface;

/**
 * Interface for the FlowDrop node type manager service.
 */
interface FlowDropNodeTypeManagerInterface {

  /**
   * Get all enabled node types as definition arrays.
   *
   * @return array<int, array<string, mixed>>
   *   Array of node type definition arrays.
   */
  public function getAllNodeTypes(): array;

  /**
   * Get node types filtered by category.
   *
   * @param string $category
   *   The category machine name to filter by.
   *
   * @return array<int, array<string, mixed>>
   *   Array of node type definition arrays in the specified category.
   */
  public function getNodeTypesByCategory(string $category): array;

  /**
   * Get a specific node type by its ID.
   *
   * @param string $id
   *   The node type ID.
   *
   * @return array<string, mixed>|null
   *   The node type definition, or NULL if not found or disabled.
   */
  public function getNodeType(string $id): ?array;

  /**
   * Create a node type from a definition array.
   *
   * @param array<string, mixed> $definition
   *   The node type definition.
   *
   * @return \Drupal\flowdrop_node_type\FlowDropNodeTypeInterface|null
   *   The created entity, or NULL if creation failed.
   */
  public function createNodeType(array $definition): ?FlowDropNodeTypeInterface;

  /**
   * Update an existing node type from a definition array.
   *
   * @param string $id
   *   The node type ID.
   * @param array<string, mixed> $definition
   *   The updated node type definition.
   *
   * @return \Drupal\flowdrop_node_type\FlowDropNodeTypeInterface|null
   *   The updated entity, or NULL if the update failed.
   */
  public function updateNodeType(string $id, array $definition): ?FlowDropNodeTypeInterface;

  /**
   * Delete a node type.
   *
   * @param string $id
   *   The node type ID.
   *
   * @return bool
   *   TRUE on success, FALSE if the entity was not found or deletion failed.
   */
  public function deleteNodeType(string $id): bool;

  /**
   * Import node types from a NodeTypeService mapping array.
   *
   * Creates new node types or updates existing ones based on their IDs.
   *
   * @param array<string, array<string, mixed>> $mapping
   *   Keyed array of node type definitions.
   *
   * @return array<int, array{id: string, action: string, success: bool}>
   *   Result entries for each processed node type.
   */
  public function importFromMapping(array $mapping): array;

  /**
   * Get the visual types available for node rendering.
   *
   * @return array<string, string>
   *   Visual type options keyed by machine name with human-readable labels.
   */
  public function getAvailableVisualTypes(): array;

  /**
   * Get available node categories.
   *
   * @return array<string, string>
   *   Categories keyed by machine name with human-readable labels.
   */
  public function getAvailableCategories(): array;

  /**
   * Search for node types by tags.
   *
   * @param string[] $tags
   *   Tags to search for. A node type matches if it has at least one.
   *
   * @return array<int, array<string, mixed>>
   *   Array of matching node type definition arrays.
   */
  public function searchByTags(array $tags): array;

}
