defmodule ComponentsElixir.Inventory.HierarchicalSchema do
  @moduledoc """
  Behaviour for schemas that implement hierarchical relationships.

  Provides a contract for entities with parent-child relationships,
  ensuring consistent interface across different hierarchical entities.
  """

  @doc """
  Returns the full hierarchical path as a string.
  Example: "Electronics > Components > Resistors"
  """
  @callback full_path(struct()) :: String.t()

  @doc """
  Returns the parent entity or nil if this is a root entity.
  """
  @callback parent(struct()) :: struct() | nil

  @doc """
  Returns the children entities as a list.
  """
  @callback children(struct()) :: [struct()]

  @doc """
  Returns the separator used for path display.
  """
  @callback path_separator() :: String.t()

  @doc """
  Returns the entity type for use with the Hierarchical module.
  """
  @callback entity_type() :: atom()

  defmacro __using__(_opts) do
    quote do
      @behaviour ComponentsElixir.Inventory.HierarchicalSchema
      alias ComponentsElixir.Inventory.Hierarchical
    end
  end
end