Refactor, cleanup code and add documentaiton

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

@@ -0,0 +1,126 @@
+using Core;
+using Core.SaveLoad;
+using UnityEngine;
+using AppleHills.Core.Settings;
+using Pixelplacement;
+
+namespace UI.CardSystem.StateMachine.States
+{
+    /// <summary>
+    /// Album enlarged state - card is enlarged when clicked from album slot.
+    /// Different from EnlargedNewState as it doesn't show "NEW" badge.
+    /// </summary>
+    public class CardAlbumEnlargedState : AppleState, ICardClickHandler
+    {
+        private CardContext _context;
+        private ICardSystemSettings _settings;
+        private Vector3 _originalScale;
+        private Transform _originalParent;
+        private Vector3 _originalLocalPosition;
+        private Quaternion _originalLocalRotation;
+        private Vector3 _originalWorldPosition;
+        
+        // Events for page to manage backdrop and reparenting
+        public event System.Action<CardAlbumEnlargedState> OnEnlargeRequested;
+        public event System.Action<CardAlbumEnlargedState> OnShrinkRequested;
+        
+        private void Awake()
+        {
+            _context = GetComponentInParent<CardContext>();
+            _settings = GameManager.GetSettingsObject<ICardSystemSettings>();
+        }
+        
+        public override void OnEnterState()
+        {
+            // Ensure card front is visible and facing camera
+            if (_context.CardDisplay != null)
+            {
+                _context.CardDisplay.gameObject.SetActive(true);
+                _context.CardDisplay.transform.localRotation = Quaternion.Euler(0, 0, 0);
+            }
+            
+            // Store original transform for restoration
+            _originalScale = _context.RootTransform.localScale;
+            _originalParent = _context.RootTransform.parent;
+            _originalLocalPosition = _context.RootTransform.localPosition;
+            _originalLocalRotation = _context.RootTransform.localRotation;
+            _originalWorldPosition = _context.RootTransform.position;
+            
+            // Notify page to show backdrop and reparent card to top layer (preserve world transform)
+            OnEnlargeRequested?.Invoke(this);
+            
+            // Animate into center and scale up significantly
+            if (_context.Animator != null)
+            {
+                // Move to center of enlarged container (assumes zero is centered)
+                _context.Animator.AnimateLocalPosition(Vector3.zero, _settings.ScaleDuration);
+                // Enlarge using settings-controlled scale
+                _context.Animator.PlayEnlarge(_settings.AlbumCardEnlargedScale, _settings.ScaleDuration);
+            }
+            
+            Logging.Debug($"[CardAlbumEnlargedState] Card enlarged from album: {_context.CardData?.Name}");
+        }
+        
+        public void OnCardClicked(CardContext context)
+        {
+            // Click to shrink back (play reverse of opening animation)
+            Logging.Debug($"[CardAlbumEnlargedState] Card clicked while enlarged, shrinking back");
+            
+            // Ask page to hide backdrop (state will handle moving back & reparenting)
+            OnShrinkRequested?.Invoke(this);
+            
+            // Animate back to original world position + shrink to original scale
+            float duration = _settings.ScaleDuration;
+            
+            // Move using world-space tween so we land exactly on the original position
+            Tween.Position(context.RootTransform, _originalWorldPosition, duration, 0f, Tween.EaseInOut);
+            
+            if (context.Animator != null)
+            {
+                context.Animator.PlayShrink(_originalScale, duration, onComplete: () =>
+                {
+                    // Reparent back to original hierarchy and restore local transform
+                    context.RootTransform.SetParent(_originalParent, true);
+                    context.RootTransform.localPosition = _originalLocalPosition;
+                    context.RootTransform.localRotation = _originalLocalRotation;
+                    
+                    // Transition back to placed state
+                    context.StateMachine.ChangeState(CardStateNames.PlacedInSlot);
+                });
+            }
+            else
+            {
+                // Fallback if no animator: snap back
+                context.RootTransform.position = _originalWorldPosition;
+                context.RootTransform.SetParent(_originalParent, true);
+                context.RootTransform.localPosition = _originalLocalPosition;
+                context.RootTransform.localRotation = _originalLocalRotation;
+                context.StateMachine.ChangeState(CardStateNames.PlacedInSlot);
+            }
+        }
+        
+        /// <summary>
+        /// Get original parent for restoration
+        /// </summary>
+        public Transform GetOriginalParent() => _originalParent;
+        
+        /// <summary>
+        /// Get original local position for restoration
+        /// </summary>
+        public Vector3 GetOriginalLocalPosition() => _originalLocalPosition;
+        
+        /// <summary>
+        /// Get original local rotation for restoration
+        /// </summary>
+        public Quaternion GetOriginalLocalRotation() => _originalLocalRotation;
+        
+        private void OnDisable()
+        {
+            // Restore original scale when exiting
+            if (_context?.RootTransform != null)
+            {
+                _context.RootTransform.localScale = _originalScale;
+            }
+        }
+    }
+}