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

#ifndef COMPONENTS_USER_EDUCATION_WEBUI_HELP_BUBBLE_HANDLER_H_
#define COMPONENTS_USER_EDUCATION_WEBUI_HELP_BUBBLE_HANDLER_H_

#include <map>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <vector>

#include "base/functional/callback.h"
#include "base/gtest_prod_util.h"
#include "base/memory/raw_ptr.h"
#include "base/memory/weak_ptr.h"
#include "components/user_education/common/help_bubble/help_bubble.h"
#include "components/user_education/common/help_bubble/help_bubble_params.h"
#include "content/public/browser/web_ui_controller.h"
#include "mojo/public/cpp/bindings/receiver.h"
#include "ui/base/interaction/element_identifier.h"
#include "ui/gfx/geometry/rect.h"
#include "ui/gfx/geometry/rect_f.h"
#include "ui/webui/resources/cr_components/help_bubble/help_bubble.mojom.h"
#include "ui/webui/resources/js/tracked_element/tracked_element.mojom-forward.h"
#include "ui/webui/resources/js/tracked_element/tracked_element.mojom.h"

namespace content {
class WebContents;
}  // namespace content

namespace ui {
class TrackedElementHandler;
class TrackedElementWebUI;
}  // namespace ui

namespace user_education {

class HelpBubbleWebUI;

// Base class abstracting away IPC so that handler functionality can be tested
// entirely with mocks.
class HelpBubbleHandlerBase : public help_bubble::mojom::HelpBubbleHandler {
 public:
  // Returns the WebContents associated with the HelpBubbleHandle. The return
  // value must never be null.
  using GetWebContentsCallback =
      base::RepeatingCallback<content::WebContents*()>;

  HelpBubbleHandlerBase(const HelpBubbleHandlerBase&) = delete;
  HelpBubbleHandlerBase(const std::vector<ui::ElementIdentifier>& identifiers,
                        ui::ElementContext context);
  HelpBubbleHandlerBase& operator=(const HelpBubbleHandlerBase&) = delete;
  ~HelpBubbleHandlerBase() override;

  // Returns the context. In the common case, currently this is tied to the
  // WebUIController and not the browser that holds it, as (at least for tab
  // contents) the owning browser can change during the handler's lifespan.
  // For special cases without a WebUIController, the HelpBubbleHandle creator
  // must provide a unique context of their own choosing.
  ui::ElementContext context() const;

  // See `GetWebContentsCallback` above.
  content::WebContents* GetWebContents();

  // Returns whether a help bubble is showing for a given element.
  bool IsHelpBubbleShowingForTesting(ui::ElementIdentifier id) const;

  base::WeakPtr<HelpBubbleHandlerBase> GetWeakPtr() {
    return weak_ptr_factory_.GetWeakPtr();
  }

 protected:
  // Provides reliable access to a HelpBubbleClient. Derived classes should
  // create a ClientProvider and pass it to the HelpBubbleHandlerBase
  // constructor. This ensures that the client can still be accessed even as the
  // derived class is being destructed (for example, telling the help bubble to
  // close).
  class ClientProvider {
   public:
    ClientProvider() = default;
    ClientProvider(const ClientProvider&) = delete;
    ClientProvider& operator=(const ClientProvider&) = delete;
    virtual ~ClientProvider() = default;

    // Returns the client. Should always return a valid value.
    virtual help_bubble::mojom::HelpBubbleClient* GetClient() = 0;
  };

  HelpBubbleHandlerBase(
      std::unique_ptr<ClientProvider> client_provider,
      base::WeakPtr<ui::TrackedElementHandler> tracked_element_handler);

  help_bubble::mojom::HelpBubbleClient* GetClient();
  ClientProvider* client_provider() { return client_provider_.get(); }

  // Override to use mojo error handling; defaults to NOTREACHED().
  virtual void ReportBadMessage(std::string_view error);

 private:
  friend class FloatingWebUIHelpBubbleFactory;
  friend class HelpBubbleFactoryWebUI;
  friend class HelpBubbleWebUI;
  FRIEND_TEST_ALL_PREFIXES(HelpBubbleHandlerTest, ExternalHelpBubbleUpdated);

  struct ElementData;

  std::unique_ptr<HelpBubbleWebUI> CreateHelpBubble(
      ui::TrackedElementWebUI* element,
      HelpBubbleParams params);
  void OnHelpBubbleClosing(ui::ElementIdentifier anchor_id,
                           const std::string& secondary_id);
  bool ToggleHelpBubbleFocusForAccessibility(ui::ElementIdentifier anchor_id,
                                             const std::string& secondary_id);
  gfx::Rect GetHelpBubbleBoundsInScreen(ui::ElementIdentifier anchor_id,
                                        const std::string& secondary_id) const;
  void OnFloatingHelpBubbleCreated(ui::TrackedElementWebUI* anchor_id,
                                   HelpBubble* help_bubble);
  void OnFloatingHelpBubbleClosed(ui::ElementIdentifier anchor_id,
                                  const std::string& secondary_id,
                                  const HelpBubble* help_bubble,
                                  HelpBubble::CloseReason);

  // mojom::HelpBubbleHandler:
  void HelpBubbleButtonPressed(
      tracked_element::mojom::TrackedElementIdentifierPtr id,
      uint8_t button) final;
  void HelpBubbleClosed(
      tracked_element::mojom::TrackedElementIdentifierPtr id,
      help_bubble::mojom::HelpBubbleClosedReason reason) final;

  ElementData* GetDataByName(
      const tracked_element::mojom::TrackedElementIdentifierPtr& id,
      std::string_view error_prefix,
      ui::ElementIdentifier* found_identifier = nullptr);

  ElementData* GetDataById(ui::ElementIdentifier id,
                           const std::string& secondary_id);
  const ElementData* GetDataById(ui::ElementIdentifier id,
                                 const std::string& secondary_id) const;

  const std::unique_ptr<ClientProvider> client_provider_;
  base::WeakPtr<ui::TrackedElementHandler> tracked_element_handler_;
  std::map<ui::ElementIdentifier, std::map<std::string, ElementData>>
      element_data_;

  base::WeakPtrFactory<HelpBubbleHandlerBase> weak_ptr_factory_{this};
};

// Handler for WebUI that support displaying help bubbles in Polymer.
// The corresponding mojom and mixin files to support help bubbles on the WebUI
// side are located in the project at:
//   //ui/webui/resources/cr_components/help_bubble/
//
// Full usage recommendations can be found in README.md.
//
// SECURITY NOTE: a `HelpBubbleHandler` is owned by a `WebUIController` that
// implements `HelpBubbleHandlerFactory`, and typically has a lifespan limited
// to a subset of the corresponding WebUI page's lifespan. Reloading the page
// can cause it to be discarded and recreated (and a common attack vector is
// triggering a recreate). If a class has a raw_ptr to a
// HelpBubbleHandler[Base], then a test MUST be added to ensure that the class
// releases the reference when the HelpBubbleHandler is destroyed. Tests are
// already provided for `HelpBubbleWebUI` and `TrackedElementWebUI` in
// help_bubble_handler_unittest.cc.
class HelpBubbleHandler : public HelpBubbleHandlerBase {
 public:
  // Create a help bubble handler (called from the HelpBubbleHandlerFactory
  // method). The `identifier` is used to create a placeholder TrackedElement
  // that can be referenced by ElementTracker, InteractionSequence,
  // HelpBubbleFactory, FeaturePromoController, etc.
  //
  // Note: Because WebContents are portable between browser windows, the context
  // of the placeholder element will not match the browser window that initially
  // contains it. This may change in future for WebContents that are embedded in
  // primary or secondary UI rather than in a (movable) tab.
  HelpBubbleHandler(
      mojo::PendingReceiver<help_bubble::mojom::HelpBubbleHandler>
          pending_handler,
      mojo::PendingRemote<help_bubble::mojom::HelpBubbleClient> pending_client,
      base::WeakPtr<ui::TrackedElementHandler> tracked_element_handler);

  ~HelpBubbleHandler() override;

 private:
  class ClientProvider;

  void ReportBadMessage(std::string_view error) override;

  mojo::Receiver<help_bubble::mojom::HelpBubbleHandler> receiver_;
};

}  // namespace user_education

#endif  // COMPONENTS_USER_EDUCATION_WEBUI_HELP_BUBBLE_HANDLER_H_