UIViewController lifecycle: the definitive correctness guide

// ✅ Lifecycle logger — paste into any VC for debugging
final class LifecycleVC: UIViewController {
    override func loadView()                           { super.loadView(); print("1 ─ loadView") }
    override func viewDidLoad()                        { super.viewDidLoad(); print("2 ─ viewDidLoad") }
    override func viewWillAppear(_ a: Bool)            { super.viewWillAppear(a); print("3 ─ viewWillAppear") }
    override func viewIsAppearing(_ a: Bool)           { super.viewIsAppearing(a); print("4 ─ viewIsAppearing") }
    override func viewWillLayoutSubviews()             { super.viewWillLayoutSubviews(); print("5 ─ viewWillLayoutSubviews") }
    override func viewDidLayoutSubviews()              { super.viewDidLayoutSubviews(); print("6 ─ viewDidLayoutSubviews") }
    override func viewDidAppear(_ a: Bool)             { super.viewDidAppear(a); print("7 ─ viewDidAppear") }
    override func viewWillDisappear(_ a: Bool)         { super.viewWillDisappear(a); print("8 ─ viewWillDisappear") }
    override func viewDidDisappear(_ a: Bool)          { super.viewDidDisappear(a); print("9 ─ viewDidDisappear") }
    deinit                                             { print("10 ─ deinit") }
}

// ❌ INCORRECT — safe area insets are (0,0,0,0) in viewWillAppear
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    // safeAreaInsets = UIEdgeInsets(top: 0, left: 0, bottom: 0, right: 0) ← WRONG
    let usableHeight = view.bounds.height - view.safeAreaInsets.top - view.safeAreaInsets.bottom
    headerView.frame.size.height = usableHeight * 0.3  // Calculated from zero insets!
}

// ❌ INCORRECT — trait collections may be stale from previous appearance
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    // After iPad Split View resize, this still reports .regular
    // from the PREVIOUS appearance — not the current compact width
    if traitCollection.horizontalSizeClass == .compact {
        enableSingleColumnLayout()  // May never execute!
    }
}

// ✅ CORRECT — viewIsAppearing has accurate geometry and traits
override func viewIsAppearing(_ animated: Bool) {
    super.viewIsAppearing(animated)

    // Safe area insets are real values: e.g. (top: 59, left: 0, bottom: 34, right: 0)
    let usableHeight = view.bounds.height - view.safeAreaInsets.top - view.safeAreaInsets.bottom
    headerView.frame.size.height = usableHeight * 0.3

    // Trait collections are current — reflects iPad Split View state
    if traitCollection.horizontalSizeClass == .compact {
        enableSingleColumnLayout()
    }

    // Scroll to a specific position (requires accurate content size)
    if let selected = tableView.indexPathForSelectedRow {
        tableView.scrollToRow(at: selected, at: .middle, animated: false)
    }
}

// ✅ CORRECT — programmatic view creation; do NOT call super
override func loadView() {
    let root = CustomRootView()
    root.backgroundColor = .systemBackground
    self.view = root  // Required: must assign self.view
}

// ❌ INCORRECT — calling super.loadView() when overriding
override func loadView() {
    super.loadView()          // Creates a default UIView you immediately replace — wasteful
    self.view = CustomRootView()
}

// ❌ INCORRECT — overriding loadView when using Storyboard
override func loadView() {
    view = UIView()           // Prevents Storyboard view from loading!
}

// ❌ INCORRECT — accessing self.view inside loadView
override func loadView() {
    let v = UIView()
    v.addSubview(self.view)   // Triggers loadView again → infinite recursion!
    self.view = v
}

// ❌ INCORRECT — calling loadView() directly
let vc = MyViewController()
vc.loadView()                 // Never do this; use loadViewIfNeeded() if you must

// ✅ CORRECT — add subviews, constraints, data sources; no geometry math
override func viewDidLoad() {
    super.viewDidLoad()
    view.addSubview(tableView)
    NSLayoutConstraint.activate([
        tableView.topAnchor.constraint(equalTo: view.topAnchor),
        tableView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
        tableView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
        tableView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
    ])
    tableView.dataSource = self
    tableView.register(Cell.self, forCellReuseIdentifier: "cell")
}

// ❌ INCORRECT — geometry is not final in viewDidLoad
override func viewDidLoad() {
    super.viewDidLoad()
    // view.bounds is often (0, 0, 320, 480) — storyboard placeholder, not real device size
    let circle = UIView(frame: CGRect(x: 0, y: 0,
        width: view.bounds.width / 2,       // Wrong width!
        height: view.bounds.width / 2))
    circle.layer.cornerRadius = view.bounds.width / 4  // Wrong radius!
    view.addSubview(circle)
}

// ✅ CORRECT — alongside animation (requires transitionCoordinator)
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)

    // Register notifications (balanced with viewDidDisappear)
    NotificationCenter.default.addObserver(
        self, selector: #selector(dataChanged),
        name: .dataDidUpdate, object: nil
    )

    // Animate alongside the push/present transition
    transitionCoordinator?.animate(alongsideTransition: { _ in
        self.navigationController?.navigationBar.tintColor = .systemBlue
    })
}

// ❌ INCORRECT — expensive network call fires on every tab switch
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    // This fires every time user switches tabs, pops back, or dismisses a modal!
    NetworkService.shared.fetchAllUsers { [weak self] users in
        self?.users = users
        self?.tableView.reloadData()
    }
}

// ✅ CORRECT — corner radius that updates whenever bounds change
override func viewDidLayoutSubviews() {
    super.viewDidLayoutSubviews()
    avatarView.layer.cornerRadius = avatarView.bounds.height / 2
    avatarView.layer.shadowPath = UIBezierPath(
        ovalIn: avatarView.bounds
    ).cgPath
}

// ❌ INCORRECT — one-time setup in a method called dozens of times
override func viewDidLayoutSubviews() {
    super.viewDidLayoutSubviews()
    // This creates a new gradient layer on EVERY layout pass!
    let gradient = CAGradientLayer()
    gradient.frame = view.bounds
    gradient.colors = [UIColor.red.cgColor, UIColor.blue.cgColor]
    view.layer.insertSublayer(gradient, at: 0)  // Stacking layers endlessly
}

// ✅ CORRECT — start visible animations after the view is on screen
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    startPulseAnimation()
    analyticsService.trackScreenView("HomeScreen")
}

// ❌ INCORRECT — UI configuration in viewDidAppear causes visible flash
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    // User sees the OLD background first, then it snaps to green
    view.backgroundColor = .systemGreen
}

// ✅ CORRECT — balanced cleanup
override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    view.endEditing(true)               // Resign first responder
    observationTask?.cancel()           // Cancel async work
}

override func viewDidDisappear(_ animated: Bool) {
    super.viewDidDisappear(animated)
    NotificationCenter.default.removeObserver(self)  // Balanced with viewWillAppear
}

// ✅ CORRECT — adding a child view controller
func addContent(_ child: UIViewController) {
    addChild(child)                        // Step 1: parent-child link (auto-calls willMove)
    child.view.frame = view.bounds         // Step 2: size the view
    child.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
    view.addSubview(child.view)            // Step 3: view hierarchy
    child.didMove(toParent: self)          // Step 4: notify completion ← YOU must call this
}

// ✅ CORRECT — removing a child view controller
func removeContent(_ child: UIViewController) {
    child.willMove(toParent: nil)          // Step 1: notify impending removal ← YOU must call
    child.view.removeFromSuperview()       // Step 2: view hierarchy
    child.removeFromParent()               // Step 3: parent-child link (auto-calls didMove)
}

// ❌ INCORRECT — skipping addChild entirely
func addContentBroken(_ child: UIViewController) {
    view.addSubview(child.view)            // Just adding the view
    // Result: child never receives viewWillAppear/viewDidAppear,
    // trait collection changes don't propagate,
    // rotation callbacks are missed,
    // Xcode may throw UIViewControllerHierarchyInconsistency in debug
}

// ❌ INCORRECT — forgetting didMove(toParent:)
func addContentIncomplete(_ child: UIViewController) {
    addChild(child)
    view.addSubview(child.view)
    // Missing: child.didMove(toParent: self)
    // The child's didMove(toParent:) override never fires — any setup there is skipped
}

// ❌ INCORRECT — reversed removal order
func removeContentBackwards(_ child: UIViewController) {
    child.removeFromParent()               // Too early! Calls didMove(toParent: nil) prematurely
    child.view.removeFromSuperview()
    child.willMove(toParent: nil)          // Too late! Child already detached from parent
}

// ❌ INCORRECT — redundant willMove call when adding
func addContentRedundant(_ child: UIViewController) {
    child.willMove(toParent: self)         // Unnecessary — addChild does this automatically
    addChild(child)                        // Calls willMove again — child gets notified twice
    view.addSubview(child.view)
    child.didMove(toParent: self)
}

// ✅ CORRECT — transitioning from one child to another
func swap(from oldVC: UIViewController, to newVC: UIViewController) {
    oldVC.willMove(toParent: nil)
    addChild(newVC)

    transition(from: oldVC, to: newVC,
               duration: 0.3,
               options: .transitionCrossDissolve,
               animations: nil) { _ in
        oldVC.removeFromParent()           // Auto-calls didMove(toParent: nil)
        newVC.didMove(toParent: self)
    }
}

// ❌ INCORRECT — missing super
override func viewWillAppear(_ animated: Bool) {
    // No super call → children never receive viewWillAppear
    updateUI()
}

// ✅ CORRECT — always call super
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    updateUI()
}

// ❌ INCORRECT — view is not in the window hierarchy yet
override func viewDidLoad() {
    super.viewDidLoad()
    present(loginVC, animated: true)
    // Console: "whose view is not in the window hierarchy"
}

// ✅ CORRECT — wait until the view is on screen
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    if needsLogin {
        present(loginVC, animated: true)
    }
}

// ✅ Add to every view controller during development
deinit {
    print("✅ \(type(of: self)) deallocated")
}

// ❌ LEAK — strong self in stored closure
class ProfileVC: UIViewController {
    var onUpdate: (() -> Void)?

    override func viewDidLoad() {
        super.viewDidLoad()
        onUpdate = {
            self.refresh()     // self → onUpdate → closure → self
        }
    }
}

// ✅ FIX — weak capture
onUpdate = { [weak self] in
    self?.refresh()
}

// ❌ LEAK — async for-loop never terminates
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    Task {
        for await value in stream.values {
            updateUI(value)    // Holds self alive forever
        }
    }
}

// ✅ FIX — store and cancel the task
private var streamTask: Task<Void, Never>?

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    streamTask = Task { [weak self] in
        for await value in stream.values {
            self?.updateUI(value)
        }
    }
}

override func viewWillDisappear(_ animated: Bool) {
    super.viewWillDisappear(animated)
    streamTask?.cancel()       // Breaks the infinite await
}

// ✅ CORRECT — animate alongside rotation/resize
override func viewWillTransition(
    to size: CGSize,
    with coordinator: UIViewControllerTransitionCoordinator
) {
    super.viewWillTransition(to: size, with: coordinator)  // Required — forwards to children

    let isLandscape = size.width > size.height

    coordinator.animate(alongsideTransition: { [weak self] _ in
        self?.sidebarWidthConstraint.constant = isLandscape ? 320 : 0
        self?.view.layoutIfNeeded()
    }, completion: { [weak self] context in
        if !context.isCancelled {
            self?.updateCellSizes(for: size)
        }
    })
}

// ❌ INCORRECT — missing super; children never learn about size change
override func viewWillTransition(
    to size: CGSize,
    with coordinator: UIViewControllerTransitionCoordinator
) {
    // No super call! Child VCs will not receive the size change notification
    updateLayout(for: size)
}

// ❌ INCORRECT — raw UIView.animate instead of coordinator
override func viewWillTransition(
    to size: CGSize,
    with coordinator: UIViewControllerTransitionCoordinator
) {
    super.viewWillTransition(to: size, with: coordinator)
    // This animation runs on its OWN timeline, out of sync with the rotation
    UIView.animate(withDuration: 0.3) {
        self.sidebarWidthConstraint.constant = size.width > size.height ? 320 : 0
        self.view.layoutIfNeeded()
    }
}

// ✅ CORRECT — alongside animation during a push/present
override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)

    transitionCoordinator?.animate(alongsideTransition: { _ in
        self.dimmingView.alpha = 0.5
    }, completion: { context in
        if context.isCancelled {
            self.dimmingView.alpha = 0.0   // Revert if interactive pop cancelled
        }
    })
}