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

module tracked_element.mojom;

import "mojo/public/mojom/base/string16.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";

// How should text be sent to a text input?
// Mirror of ui::test::InteractionTestUtil::TextEntryMode
enum TextEntryMode {
  // Replaces all of the existing text with the new text.
  kReplaceAll,
  // Inserts the new text at the current cursor position, replacing any
  // existing selection.
  kInsertOrReplace,
  // Appends the new text to the end of the existing text.
  kAppend
};

// Data that uniquely identifies an element.
struct TrackedElementIdentifier {
  // The name of the ui::ElementIdentifier associated with the element. Must
  // refer to an extant identifier whose name has been added to the lookup.
  string native_identifier;

  // A secondary identifier associated with the element that should be unique to
  // this WebUI and must be unique among elements with the same
  // `native_identifier`. Used to differentiate between elements with the same
  // ui::ElementIdentifier.
  //
  // Should be auto-generated by the TrackedElementManager for new elements
  // where no explicit secondary identifier is specified. May not be empty.
  string secondary_identifier;
};

// Implemented by the browser. This API is exposed to the all WebUI pages, both
// "chrome://" and "chrome-untrusted://". The WebUI notifies the browser of
// changes to tracked elements, such as their visibility and bounds.
interface TrackedElementHandler {
  // Sets the WebUI end of the connection; used to handle requests to update
  // the element initiated by the browser.
  SetManager(pending_remote<TrackedElementManager> observer);

  // Indicates that the ability to highlight the given element has changed.
  TrackedElementCanHighlightChanged(
      TrackedElementIdentifier identifier, bool can_higlight);

  // Indicates that the visibility of the element that the help bubble could be
  // anchored to has changed.
  TrackedElementVisibilityChanged(TrackedElementIdentifier identifier,
                                  bool visible,
                                  gfx.mojom.RectF rect);

  // Notifies that a tracked element has been activated, which will in turn be
  // propagated through the ui::ElementTracker system as an
  // EventType::kActivated.
  TrackedElementActivated(TrackedElementIdentifier identifier);

  // Notifies that a custom event has occurred associated with a particular
  // tracked element, which will in turn be propagated through the
  // ui::ElementTracker system as an EventType::kCustomEvent.
  //
  // The ui::CustomElementEventType will be retrieved using
  // `custom_event_name`.
  TrackedElementCustomEvent(TrackedElementIdentifier identifier,
                            string custom_event_name);
};

// Implemented by WebUI. The browser asks WebUI to update elements in some way.
interface TrackedElementManager {
  // Notifies that an element should be highlighted/unhighlighted to
  // help relate it to a bubble popup.
  OnElementHighlightChanged(TrackedElementIdentifier identifier,
                            bool highlighted);

  // Simulates a click on the element.
  ClickElement(TrackedElementIdentifier identifier) => (bool success);

  // Simulates focusing the element.
  FocusElement(TrackedElementIdentifier identifier) => (bool success);

  // Simulates selecting the n-th tab in a tab collection element.
  SelectTab(TrackedElementIdentifier identifier, uint32 index)
      => (bool success);

  // Simulates selecting the n-th item in a dropdown/combobox element.
  SelectDropdownItem(TrackedElementIdentifier identifier, uint32 index)
      => (bool success);

  // Simulates entering text into an element.
  EnterText(TrackedElementIdentifier identifier, mojo_base.mojom.String16 text,
            TextEntryMode mode) => (bool success);

  // Simulates a "confirm" action (e.g. Enter key) on the element.
  Confirm(TrackedElementIdentifier identifier) => (bool success);
};