## Abstract base class for all card containers in the card framework.
##
## CardContainer provides the foundational functionality for managing collections of cards,
## including drag-and-drop operations, position management, and container interactions.
## All specialized containers (Hand, Pile, etc.) extend this class.
##
## Key Features:
## - Card collection management with position tracking
## - Drag-and-drop integration with DropZone system
## - History tracking for undo/redo operations
## - Extensible layout system through virtual methods
## - Visual debugging support for development
##
## Virtual Methods to Override:
## - _card_can_be_added(): Define container-specific rules
## - _update_target_positions(): Implement container layout logic
## - on_card_move_done(): Handle post-movement processing
##
## Usage:
## [codeblock]
## class_name MyContainer
## extends CardContainer
##
## func _card_can_be_added(cards: Array) -> bool:
##     return cards.size() == 1  # Only allow single cards
## [/codeblock]
class_name CardContainer
extends Control

# Static counter for unique container identification
static var next_id: int = 0


@export_group("drop_zone")
## Enables or disables the drop zone functionality.
@export var enable_drop_zone := true
@export_subgroup("Sensor")
## The size of the sensor. If not set, it will follow the size of the card.
@export var sensor_size: Vector2
## The position of the sensor.
@export var sensor_position: Vector2
## The texture used for the sensor.
@export var sensor_texture: Texture
## Determines whether the sensor is visible or not.
## Since the sensor can move following the status, please use it for debugging.
@export var sensor_visibility := false


# Container identification and management
var unique_id: int
var drop_zone_scene = preload("drop_zone.tscn")
var drop_zone: DropZone = null

# Card collection and state
var _held_cards: Array[Card] = []
var _holding_cards: Array[Card] = []

# Scene references
var cards_node: Control
var card_manager: CardManager
var debug_mode := false


func _init() -> void:
	unique_id = next_id
	next_id += 1


func _ready() -> void:
	# Check if 'Cards' node already exists
	if has_node("Cards"):
		cards_node = $Cards
	else:
		cards_node = Control.new()
		cards_node.name = "Cards"
		cards_node.mouse_filter = Control.MOUSE_FILTER_PASS
		add_child(cards_node)
	
	var parent = get_parent()
	if parent is CardManager:
		card_manager = parent
	else:
		push_error("CardContainer should be under the CardManager")
		return
		
	card_manager._add_card_container(unique_id, self)
	
	if enable_drop_zone:
		drop_zone = drop_zone_scene.instantiate()
		add_child(drop_zone)
		drop_zone.init(self, [CardManager.CARD_ACCEPT_TYPE])
		# If sensor_size is not set, they will follow the card size.
		if sensor_size == Vector2(0, 0):
			sensor_size = card_manager.card_size
		drop_zone.set_sensor(sensor_size, sensor_position, sensor_texture, sensor_visibility)
		if debug_mode:
			drop_zone.sensor_outline.visible = true
		else:
			drop_zone.sensor_outline.visible = false


func _exit_tree() -> void:
	if card_manager != null:
		card_manager._delete_card_container(unique_id)


## Adds a card to this container at the specified index.
## @param card: The card to add
## @param index: Position to insert (-1 for end)
func add_card(card: Card, index: int = -1) -> void:
	if index == -1:
		_assign_card_to_container(card)
	else:
		_insert_card_to_container(card, index)
	_move_object(card, cards_node, index)


## Removes a card from this container.
## @param card: The card to remove
## @returns: True if card was removed, false if not found
func remove_card(card: Card) -> bool:
	var index = _held_cards.find(card)
	if index != -1:
		_held_cards.remove_at(index)
	else:
		return false
	update_card_ui()
	return true

## Returns the number of contained cards
func get_card_count() -> int:
	return _held_cards.size()

## Checks if this container contains the specified card.
func has_card(card: Card) -> bool:
	return _held_cards.has(card)


## Removes all cards from this container.
func clear_cards() -> void:
	for card in _held_cards:
		_remove_object(card)
	_held_cards.clear()
	update_card_ui()


## Checks if the specified cards can be dropped into this container.
## Override _card_can_be_added() in subclasses for custom rules.
func check_card_can_be_dropped(cards: Array) -> bool:
	if not enable_drop_zone:
		return false

	if drop_zone == null:
		return false

	if drop_zone.accept_types.has(CardManager.CARD_ACCEPT_TYPE) == false:
		return false
		
	if not drop_zone.check_mouse_is_in_drop_zone():
		return false
		
	return _card_can_be_added(cards)


func get_partition_index() -> int:
	var vertical_index = drop_zone.get_vertical_layers()
	if vertical_index != -1:
		return vertical_index
	var horizontal_index = drop_zone.get_horizontal_layers()
	if horizontal_index != -1:
		return horizontal_index
	return -1


## Shuffles the cards in this container using Fisher-Yates algorithm.
func shuffle() -> void:
	_fisher_yates_shuffle(_held_cards)
	for i in range(_held_cards.size()):
		var card = _held_cards[i]
		cards_node.move_child(card, i)
	update_card_ui()


## Moves cards to this container with optional history tracking.
## @paramcard_container cards: Array of cards to move
## @param index: Target position (-1 for end)
## @param with_history: Whether to record for undo
## @returns: True if move was successful
func move_cards(cards: Array, index: int = -1, with_history: bool = true) -> bool:
	if not _card_can_be_added(cards):
		return false
	# XXX: If the card is already in the container, we don't add it into the history.
	if not cards.all(func(card): return _held_cards.has(card)) and with_history:
		card_manager._add_history(self, cards)
	_move_cards(cards, index)
	return true


## Restores cards to their original positions with index precision.
## @param cards: Cards to restore
## @param from_indices: Original indices for precise positioning
func undo(cards: Array, from_indices: Array = []) -> void:
	# Validate input parameters
	if not from_indices.is_empty() and cards.size() != from_indices.size():
		push_error("Mismatched cards and indices arrays in undo operation!")
		# Fallback to basic undo
		_move_cards(cards)
		return
	
	# Fallback: add to end if no index info available
	if from_indices.is_empty():
		_move_cards(cards)
		return
	
	# Validate all indices are valid
	for i in range(from_indices.size()):
		if from_indices[i] < 0:
			push_error("Invalid index found during undo: %d" % from_indices[i])
			# Fallback to basic undo
			_move_cards(cards)
			return
	
	# Check if indices are consecutive (bulk move scenario)
	var sorted_indices = from_indices.duplicate()
	sorted_indices.sort()
	var is_consecutive = true
	for i in range(1, sorted_indices.size()):
		if sorted_indices[i] != sorted_indices[i-1] + 1:
			is_consecutive = false
			break
	
	if is_consecutive and sorted_indices.size() > 1:
		# Bulk consecutive restore: maintain original relative order
		var lowest_index = sorted_indices[0]
		
		# Sort cards by their original indices to maintain proper order
		var card_index_pairs = []
		for i in range(cards.size()):
			card_index_pairs.append({"card": cards[i], "index": from_indices[i]})
		
		# Sort by index ascending to maintain original order
		card_index_pairs.sort_custom(func(a, b): return a.index < b.index)
		
		# Insert all cards starting from the lowest index
		for i in range(card_index_pairs.size()):
			var target_index = min(lowest_index + i, _held_cards.size())
			_move_cards([card_index_pairs[i].card], target_index)
	else:
		# Non-consecutive indices: restore individually (original logic)
		var card_index_pairs = []
		for i in range(cards.size()):
			card_index_pairs.append({"card": cards[i], "index": from_indices[i], "original_order": i})
		
		# Sort by index descending, then by original order ascending for stable sorting
		card_index_pairs.sort_custom(func(a, b): 
			if a.index == b.index:
				return a.original_order < b.original_order
			return a.index > b.index
		)
		
		# Restore each card to its original index
		for pair in card_index_pairs:
			var target_index = min(pair.index, _held_cards.size())  # Clamp to valid range
			_move_cards([pair.card], target_index)


func hold_card(card: Card) -> void:
	if _held_cards.has(card):
		_holding_cards.append(card)


func release_holding_cards():
	if _holding_cards.is_empty():
		return
	for card in _holding_cards:
		# Transition from HOLDING to IDLE state
		card.change_state(DraggableObject.DraggableState.IDLE)
	var copied_holding_cards = _holding_cards.duplicate()
	if card_manager != null:
		card_manager._on_drag_dropped(copied_holding_cards)
	_holding_cards.clear()


func get_string() -> String:
	return "card_container: %d" % unique_id


func on_card_move_done(_card: Card):
	pass


func on_card_pressed(_card: Card):
	pass

func _assign_card_to_container(card: Card) -> void:
	if card.card_container != self:
		card.card_container = self
	if not _held_cards.has(card):
		_held_cards.append(card)
	update_card_ui()


func _insert_card_to_container(card: Card, index: int) -> void:
	if card.card_container != self:
		card.card_container = self
	if not _held_cards.has(card):
		if index < 0:
			index = 0
		elif index > _held_cards.size():
			index = _held_cards.size()
		_held_cards.insert(index, card)
	update_card_ui()	


func _move_to_card_container(_card: Card, index: int = -1) -> void:
	if _card.card_container != null:
		_card.card_container.remove_card(_card)
	add_card(_card, index)


func _fisher_yates_shuffle(array: Array) -> void:
	for i in range(array.size() - 1, 0, -1):
		var j = randi() % (i + 1)
		var temp = array[i]
		array[i] = array[j]
		array[j] = temp


func _move_cards(cards: Array, index: int = -1) -> void:
	var cur_index = index
	for i in range(cards.size() - 1, -1, -1):
		var card = cards[i]
		if cur_index == -1:
			_move_to_card_container(card)
		else:
			_move_to_card_container(card, cur_index)
			cur_index += 1


func _card_can_be_added(_cards: Array) -> bool:
	return true


## Updates the visual positions of all cards in this container.
## Call this after modifying card positions or container properties.
func update_card_ui() -> void:
	_update_target_z_index()
	_update_target_positions()


func _update_target_z_index() -> void:
	pass


func _update_target_positions() -> void:
	pass


func _move_object(target: Node, to: Node, index: int = -1) -> void:
	if target.get_parent() == to:
		# If already the same parent, just change the order with move_child
		if index != -1:
			to.move_child(target, index)
		else:
			# If index is -1, move to the last position
			to.move_child(target, to.get_child_count() - 1)
		return

	var global_pos = target.global_position
	if target.get_parent() != null:
		target.get_parent().remove_child(target)
	if index != -1:
		to.add_child(target)
		to.move_child(target, index)
	else:
		to.add_child(target)
	target.global_position = global_pos


func _remove_object(target: Node) -> void:
	var parent = target.get_parent()
	if parent != null:
		parent.remove_child(target)
	target.queue_free()