Refactor, cleanup code and add documentaiton

Assets/Scripts/CardSystem/StateMachine/States/CardDraggingRevealedState.cs

@@ -0,0 +1,169 @@
+using Core;
+using Core.SaveLoad;
+using UnityEngine;
+
+namespace UI.CardSystem.StateMachine.States
+{
+    /// <summary>
+    /// Dragging revealed state for pending cards after flip.
+    /// Shows card front without badges, handles transition to placement after drag release.
+    /// Queries AlbumViewPage for page flip status instead of tracking state internally.
+    /// </summary>
+    public class CardDraggingRevealedState : AppleState, ICardStateDragHandler
+    {
+        private CardContext _context;
+        private Vector3 _originalScale;
+        
+        // Placement info passed from PendingFaceDownState
+        private AlbumCardSlot _targetSlot;
+        private bool _dragAlreadyEnded = false; // Track if drag ended before we entered this state (instant-release case)
+        
+        private void Awake()
+        {
+            _context = GetComponentInParent<CardContext>();
+        }
+        
+        /// <summary>
+        /// Set target slot from previous state
+        /// Called by PendingFaceDownState before transition
+        /// </summary>
+        public void SetTargetSlot(AlbumCardSlot targetSlot)
+        {
+            _targetSlot = targetSlot;
+        }
+        
+        /// <summary>
+        /// Set flag indicating drag already ended before entering this state
+        /// Called by PendingFaceDownState for instant-release case
+        /// </summary>
+        public void SetDragAlreadyEnded(bool ended)
+        {
+            _dragAlreadyEnded = ended;
+        }
+        
+        public override void OnEnterState()
+        {
+            if (_context == null) return;
+            if (_context.CardDisplay != null)
+            {
+                _context.CardDisplay.gameObject.SetActive(true);
+                _context.CardDisplay.transform.localRotation = Quaternion.Euler(0,0,0);
+            }
+            _originalScale = _context.RootTransform.localScale;
+            _context.RootTransform.localScale = _originalScale * 1.15f;
+            
+            // Check if drag already ended before we entered this state (instant-release case)
+            if (_dragAlreadyEnded)
+            {
+                Logging.Debug("[CardDraggingRevealedState] Drag ended before state entry - handling placement immediately");
+                _dragAlreadyEnded = false; // Clear flag
+                HandlePlacement();
+            }
+        }
+        
+        /// <summary>
+        /// Already in dragging state, nothing to do
+        /// </summary>
+        public bool OnCardDragStarted(CardContext ctx)
+        {
+            return true; // Prevent default DraggingState transition
+        }
+        
+        /// <summary>
+        /// Handle drag end - query AlbumViewPage for page flip status and place accordingly
+        /// </summary>
+        public bool OnCardDragEnded(CardContext ctx)
+        {
+            HandlePlacement();
+            return true;
+        }
+        
+        /// <summary>
+        /// Handle card placement logic - called from OnCardDragEnded or OnEnterState (instant-release)
+        /// </summary>
+        private void HandlePlacement()
+        {
+            if (_targetSlot == null)
+            {
+                Logging.Warning("[CardDraggingRevealedState] No target slot set - cannot place card");
+                // Return to corner
+                _context.StateMachine.ChangeState(CardStateNames.PendingFaceDown);
+                return;
+            }
+            
+            // Query AlbumViewPage for page flip status
+            var albumPage = _context.AlbumViewPage;
+            if (albumPage == null)
+            {
+                Logging.Warning("[CardDraggingRevealedState] AlbumViewPage not injected - placing immediately");
+                TransitionToPlacement(_context);
+                return;
+            }
+
+            // Check if page is still flipping
+            if (albumPage.IsPageFlipping)
+            {
+                // Wait for flip to complete
+                Logging.Debug("[CardDraggingRevealedState] Page still flipping - waiting before placement");
+                StartCoroutine(WaitForPageFlipThenPlace(_context, albumPage));
+            }
+            else
+            {
+                // Flip already done - place immediately
+                Logging.Debug("[CardDraggingRevealedState] Page flip complete - placing card immediately");
+                TransitionToPlacement(_context);
+            }
+        }
+        
+        private System.Collections.IEnumerator WaitForPageFlipThenPlace(CardContext ctx, AlbumViewPage albumPage)
+        {
+            // Wait until page flip completes (max 0.5 seconds timeout)
+            float timeout = 0.5f;
+            float elapsed = 0f;
+            
+            while (albumPage.IsPageFlipping && elapsed < timeout)
+            {
+                yield return null;
+                elapsed += Time.deltaTime;
+            }
+            
+            if (elapsed >= timeout)
+            {
+                Logging.Warning("[CardDraggingRevealedState] Page flip wait timed out");
+            }
+            else
+            {
+                Logging.Debug("[CardDraggingRevealedState] Page flip completed, placing card");
+            }
+            
+            // Now place the card
+            TransitionToPlacement(ctx);
+        }
+        
+        private void TransitionToPlacement(CardContext ctx)
+        {
+            // Pass target slot to PlacedInSlotState
+            var card = ctx.GetComponent<Card>();
+            if (card != null)
+            {
+                var placedState = card.GetStateComponent<CardPlacedInSlotState>(CardStateNames.PlacedInSlot);
+                if (placedState != null)
+                {
+                    placedState.SetPlacementInfo(_targetSlot);
+                }
+            }
+            
+            // Transition to PlacedInSlotState
+            // The state will handle animation and finalization in OnEnterState
+            ctx.StateMachine.ChangeState(CardStateNames.PlacedInSlot);
+        }
+        
+        private void OnDisable()
+        {
+            if (_context?.RootTransform != null)
+            {
+                _context.RootTransform.localScale = _originalScale;
+            }
+        }
+    }
+}