// Copyright 2026 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef IOS_CHROME_BROWSER_ASSISTANT_UI_ASSISTANT_CONTAINER_DELEGATE_H_
#define IOS_CHROME_BROWSER_ASSISTANT_UI_ASSISTANT_CONTAINER_DELEGATE_H_

#import <Foundation/Foundation.h>

enum class AssistantContainerDetent : NSInteger;
@class AssistantContainerViewController;
enum class AssistantPresentationContext;

// Delegate for the Assistant Container to notify embedders of state changes.
@protocol AssistantContainerDelegate <NSObject>
@optional

#pragma mark - Lifecycle Events

// Called before the container's view appears.
- (void)assistantContainer:(AssistantContainerViewController*)container
        willAppearAnimated:(BOOL)animated;

// Called after the container's view has appeared.
- (void)assistantContainer:(AssistantContainerViewController*)container
         didAppearAnimated:(BOOL)animated;

// Called before the container's view disappears.
- (void)assistantContainer:(AssistantContainerViewController*)container
     willDisappearAnimated:(BOOL)animated;

// Called after the container's view has disappeared.
- (void)assistantContainer:(AssistantContainerViewController*)container
      didDisappearAnimated:(BOOL)animated;

#pragma mark - Sizing and Detents

// Called when the container updates its detent heights.
- (void)assistantContainerDidUpdateDetentHeights:
    (AssistantContainerViewController*)container;

// Called when the container successfully settles on a new detent.
- (void)assistantContainer:(AssistantContainerViewController*)container
           didChangeDetent:(AssistantContainerDetent)newDetent;

// Called continuously when the container's height changes during an interactive
// drag. `percentage` is between 0 (min height) and 1 (max height).
// Values may exceed this range during rubber-banding.
- (void)assistantContainer:(AssistantContainerViewController*)container
    didUpdateExpandPercentage:(CGFloat)percentage;

// Called from within the container's active UIView animation context when
// transitioning to a new height. Animate embedder view properties directly
// inside your implementation of this method to natively inherit the container's
// exact spring animation curve.
// `percentage` is between 0 (min height) and 1 (max height).
- (void)assistantContainer:(AssistantContainerViewController*)container
    animateAlongsideTransitionToPercentage:(CGFloat)percentage;

#pragma mark - Context Changes

// Called when the host environment's presentation context changes.
- (void)assistantContainer:(AssistantContainerViewController*)container
          didChangeContext:(AssistantPresentationContext)newContext;

#pragma mark - Gesture Handling

// Asks the delegate if the container should pause the scroll view for this
// gesture. Return YES to pause the scroll view and allow the container to move.
- (BOOL)assistantContainer:(AssistantContainerViewController*)container
     shouldPauseScrollView:(UIScrollView*)scrollView
                forGesture:(UIGestureRecognizer*)otherGesture;

// Asks the delegate if it should intercept the container's resizing pan
// gesture. This is mainly used to avoid gesture conflicts with the embedder. If
// this returns YES, the container will ignore the gesture. Defaults to NO.
- (BOOL)assistantContainer:(AssistantContainerViewController*)container
    shouldInterceptPanGesture:(UIPanGestureRecognizer*)gesture;

// Called when the container receives an accessibility escape gesture while
// already in the minimized detent.
- (void)assistantContainerDidRequestDismissal:
    (AssistantContainerViewController*)container;

@end

#endif  // IOS_CHROME_BROWSER_ASSISTANT_UI_ASSISTANT_CONTAINER_DELEGATE_H_