chromium/third_party/blink/public/mojom/annotation/annotation.mojom

// 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.

module blink.mojom;

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


struct SelectorCreationResult {
  // `host_receiver`: The receiver for the AnnotationAgentHost in the browser
  // that the agent will send messages to, or NullReceiver if a selector
  // could not be created.
  pending_receiver<blink.mojom.AnnotationAgentHost> host_receiver;

  // `agent_remote`: The remote that can be used from the browser to interact
  // with the agent, or NullRemote if a selector could not be created.
  pending_remote<blink.mojom.AnnotationAgent> agent_remote;

  // `serialized_selector`: A string representing a selector that can be used
  //  in the future (via `CreateAgent`) to target the same content. Empty
  //  string if a selector could not be created (e.g. because no text
  //  selection exists, or the selection is too ambiguous).
  string serialized_selector;

  // `selected_text`: The text that's selected by the returned selector. Empty
  //  string if a selector could not be created. This is in UTF-16 since
  //  it'll be displayed in UI which requires UTF-16 encoding.
  mojo_base.mojom.String16 selected_text;
};

enum AnnotationType {
  // Shared highlights are content-less highlights of a document. They are
  // produced using the :~:text= directive in a URL. See also,
  // text_fragment_anchor.cc in Blink and //components/shared_highlighting
  kSharedHighlight,

  // User notes are private notes that a user can make and save on pages they
  // browse. See //components/user_notes
  kUserNote,

  // Finds text in the document. See //chrome/browser/companion/text_finder.
  // The Chrome Companion uses this type of annotation agent to check if a
  // given text exists in the document, and immediately disconnects the agent
  // upon finishing searching to remove the visual highlight effect.
  kTextFinder,
};

// RAII wrapper for managing a single annotation in the renderer from the
// browser process. Closing the message pipe removes the corresponding
// annotation (and host in the browser) from the document.
interface AnnotationAgent {
  // Ensures the content that the agent is attached to is visible and centered
  // in the viewport.
  ScrollIntoView();
};

// Allows the browser process to receive events for a single annotation in the
// renderer.
interface AnnotationAgentHost {
  // Called when the agent finishes an attachment attempt. If the agent was
  // able to find a Range of DOM matching the specified selector,
  // `document_relative_rect` will contain its bounding box, in the document
  // coordinate space. If attachment fails, the rect will be empty.
  DidFinishAttachment(gfx.mojom.Rect document_relative_rect);
};

// Allows the browser process to request creation of an annotation in the
// renderer.
interface AnnotationAgentContainer {
  // Instantiates a new agent in the renderer. The new agent will immediately
  // attempt attachment. Currently, an AnnotationAgent can only perform
  // attachment on creation and if it fails it cannot retry.
  //
  // `host_remote`: A binding to an object in the caller which will receive
  //    events for the agent.
  // `agent_receiver`: A binding that the caller will use to send messages to
  //    and control the life time of the agent.
  // `type`: The use case the annotation agent is being used for.
  // `serialized_selector`: A selector that will be used to attach the agent to
  //    a Range of DOM in the Document.
  CreateAgent(pending_remote<blink.mojom.AnnotationAgentHost> host_remote,
              pending_receiver<blink.mojom.AnnotationAgent> agent_receiver,
              AnnotationType type,
              string serialized_selector);

  // Creates an agent from the document's current text selection and returns
  // the bindings as well as a selector which can be used in the future to
  // target the same content. Performs attachment immediately after returning.
  // If successful, clears the current text selection.
  //
  // Selector creation may fail for a few reasons:
  //    * If there is no text selection in the renderer
  //    * If the selection is degenerate (contains no text).
  //    * The selected text cannot be uniquely identified using a text
  //      selector.
  //    * Generating the selector took too long and timed out.
  //
  // `type`: The use case the annotation agent is being used for.
  //
  // Returns:
  // `result`: The optional creation result struct that includes host_receiver,
  //    agent_remote, serialized_selector, and selected_text,
  //    that will be used by the browser.
  // `error`: The error type that occurred during link generation or kNone on success.
  //    See SharedHighlighting::LinkGenerationError.
  // `ready_status`: The type of generation status. The status indicates
  //    whether the link generated was ready before the request
  //    (preemptive link generation) or after the request.
  //    See SharedHighlighting::LinkGenerationReadyStatus.
  CreateAgentFromSelection(AnnotationType type) => (
      SelectorCreationResult? result,
      LinkGenerationError error,
      LinkGenerationReadyStatus ready_status);
};