How can I animate this tableview header Y position change

I agree with Claudio, using the tableHeaderView is probably complicating things as it is not really intended to be manipulated in this way.

Try the below and see if this gets you what you are looking for.

Instead of manipulating the offset of the header, manipulate the height. You can still give the impression of a scroll.

You could also introduce scrollView.panGestureRecognizer.velocity(in: scrollView) if you wanted to apply a threshold so the menu appears only after a particular scroll speed.

class MyTableViewController: UIViewController, UITableViewDelegate, UITableViewDataSource {

  private let data: [Int] = Array(0...99)

  private let menuView: UIView = {
    let view = UIView(frame: .zero)
    view.backgroundColor = .purple
    view.translatesAutoresizingMaskIntoConstraints = false
    return view
  }()

  private lazy var tableView: UITableView = {
    let view = UITableView(frame: .zero)
    view.translatesAutoresizingMaskIntoConstraints = false
    view.dataSource = self
    view.delegate = self
//    view.refreshControl = .init()
    view.contentInsetAdjustmentBehavior = .never
    view.tableFooterView = .init()
    return view
  }()

  var menuViewHeightAnchor: NSLayoutConstraint!
  var tableViewTopAnchor: NSLayoutConstraint!

  override func viewDidLoad() {
    super.viewDidLoad()

    menuViewHeightAnchor = menuView.heightAnchor.constraint(equalToConstant: 120)
    tableViewTopAnchor = tableView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 120)

    edgesForExtendedLayout = []
    [tableView, menuView].forEach(view.addSubview)

    NSLayoutConstraint.activate([
      menuViewHeightAnchor,
      menuView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
      menuView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
      menuView.trailingAnchor.constraint(equalTo: view.trailingAnchor),

      tableViewTopAnchor,
      tableView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
      tableView.bottomAnchor.constraint(equalTo: view.bottomAnchor),
      tableView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
    ])
  }

  func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    return data.count
  }

  func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = UITableViewCell(frame: .zero)
    cell.textLabel?.text = "Cell #\(indexPath.row)"
    return cell
  }

  private var previousOffsetY: CGFloat = 0
  private var velocityThreshold: CGFloat = 500


  func scrollViewDidScroll(_ scrollView: UIScrollView) {
    let offsetY = min(120, max(0, scrollView.contentOffset.y))
    let translation = scrollView.panGestureRecognizer.translation(in: scrollView)
    let velocity = scrollView.panGestureRecognizer.velocity(in: scrollView)

    let offsetYDiff = previousOffsetY - offsetY
    previousOffsetY = offsetY

    let adjustedOffset = menuViewHeightAnchor.constant + offsetYDiff

    tableViewTopAnchor.constant = 120 - max(0, offsetY)
    menuViewHeightAnchor.constant = min(120, adjustedOffset)


    guard offsetY == 120 else { return }

    if translation.y > 0  { // DRAGGED DOWN

      UIView.animate(withDuration: 0.33, animations: {
        self.menuViewHeightAnchor.constant = 120
        self.view.layoutIfNeeded()
      })

    } else if translation.y < 0 { // DRAGGED UP

      UIView.animate(withDuration: 0.33, animations: {
        self.menuViewHeightAnchor.constant = 0
        self.view.layoutIfNeeded()
      })
    }
  }

}

I believe the best approach is by setting the menuView as a subview of the tableViewController, for example on the viewDidLoad method and also adding an inset on the tableView like this:

let menuHeight: CGFloat = 120
var scrollStartingYPoint: CGFloat = 0

private lazy var menuView: UIView = {
  let view = UIView(frame: .zero)
  view.translatesAutoresizingMaskIntoConstraints = false
  view.backgroundColor = .systemPink
  view.heightAnchor.constraint(equalToConstant: menuHeight).isActive = true
  view.widthAnchor.constraint(equalToConstant: 100).isActive = true
  return view
}()

override func viewDidLoad() {
    super.viewDidLoad()
    // Do any additional setup after loading the view.
    view.addSubview(menuView)

    NSLayoutConstraint.activate([
        menuView.leftAnchor.constraint(equalTo: view.leftAnchor),
        menuView.topAnchor.constraint(equalTo: view.topAnchor)
    ])

    edgesForExtendedLayout = []
    extendedLayoutIncludesOpaqueBars = false

    tableView.contentInset.top = menuHeight
}

Then you can add the scrolling logic to show/hide the menu, I've done it a little different than you using the scrollViewWillBeginDragging method to store the initial scroll offset, to then determine the scroll direction and offset:

func scrollViewWillBeginDragging(_ scrollView: UIScrollView) {
    scrollStartingYPoint = scrollView.contentOffset.y
}

func scrollViewDidScroll(_ scrollView: UIScrollView) {
    let tableYScrollOffset = scrollView.contentOffset.y
    let offset = abs(tableYScrollOffset - scrollStartingYPoint)

    if tableYScrollOffset < scrollStartingYPoint { // scrolling down
        if menuView.frame.origin.y >= 0 {
            return
        }

        var translationY = -menuHeight + offset

        if translationY > 0 {
            translationY = 0
        }

        menuView.transform = CGAffineTransform(translationX: 0, y: translationY)
    } else { // scrolling up
        if menuView.frame.origin.y <= -menuHeight {
            return
        }

        var translationY = -offset

        if translationY < -menuHeight {
            translationY = -menuHeight
        }

        menuView.transform = CGAffineTransform(translationX: 0, y: translationY)
    }
}

If you want to animate the presentation of the menu, then you can change the previous code and use your animation code like this:

func scrollViewDidScroll(_ scrollView: UIScrollView) {
    let tableYScrollOffset = scrollView.contentOffset.y
    let offset = abs(tableYScrollOffset - scrollStartingYPoint)

    if tableYScrollOffset < scrollStartingYPoint { // scrolling down
        UIView.animate(withDuration: 0.25, animations: {
          self.menuView.transform = .identity
        })
    } else { // scrolling up
        if menuView.frame.origin.y <= -menuHeight {
            return
        }

        var translationY = -offset

        if translationY < -menuHeight {
            translationY = -menuHeight
        }

        menuView.transform = CGAffineTransform(translationX: 0, y: translationY)
    }
}