history_clusters.mojom | Explore in Territory

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

module history_clusters.mojom;

import "mojo/public/mojom/base/time.mojom";
import "ui/base/mojom/window_open_disposition.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
import "url/mojom/url.mojom";
import "components/history_clusters/public/mojom/history_cluster_types.mojom";

/**
 * The following enums must be kept in sync with their respective variants in
 * //tools/metrics/histograms/metadata/history/histograms.xml and
 * //components/history_clusters/core/cluster_metrics_utils.h
 */

// Actions that can be performed on clusters.
enum ClusterAction {
  kDeleted,
  kOpenedInTabGroup,
  kRelatedSearchClicked,
  kVisitClicked,
};

// Actions that can be performed on related search items.
enum RelatedSearchAction {
  kClicked,
};

// Actions that can be performed on visits.
enum VisitAction {
  kClicked,
  kHidden,
  kDeleted,
};

// Types of visits that can be shown and acted on.
enum VisitType {
  kSRP,
  kNonSRP
};

// Represents a set of Clusters returned by the browser in response to a request
// for Clusters related to a given query or within a given timespan.
struct QueryResult {
  // The query string the Clusters were matched against.
  string query;

  // The Clusters in the result set in reverse chronological order. This is
  // always non-zero length, unless `continuation_end_time` is also null,
  // indicating that we have exhausted History.
  array<Cluster> clusters;

  // True if there is another page of clusters that the UI can request.
  bool can_load_more;

  // True if this result is in response to a "load more" continuation request.
  bool is_continuation;
};

// Browser-side handler for requests from WebUI page.
interface PageHandler {
  // Opens the history cluster specified by url
  OpenHistoryCluster(url.mojom.Url url,
      ui.mojom.ClickModifiers click_modifiers);

  // The ClustersBrowserProxy singleton calls this when it's first initialized.
  SetPage(pending_remote<Page> page);

  // Shows a context menu for the searchbox.
  ShowContextMenuForSearchbox(string query, gfx.mojom.Point point);

  // Shows a context menu for a history cluster item.
  ShowContextMenuForURL(url.mojom.Url url, gfx.mojom.Point point);

  // Notify the backend that the side panel UI is ready to be shown.
  ShowSidePanelUI();

  // Toggles the visibility of the History Clusters. The returned Promise echos
  // the given value for `visible`. The page uses the returned value to update
  // its state once the request is fulfilled by the browser.
  ToggleVisibility(bool visible) => (bool visible);

  // Queries for clusters matching `query`. `begin_time` is an optional
  // param to narrow results to a time window. If true, `recluster` forces
  // reclustering as if `persist_clusters_in_history_db` were false.
  StartQueryClusters(string query, mojo_base.mojom.Time? begin_time,
      bool recluster);

  // Asks the service for more clusters. Call this when the user has scrolled
  // to the bottom of the page. `query` is passed through for sanity checking.
  LoadMoreClusters(string query);

  // Requests to hide the visits by visit IDs. The returned Promise resolves
  // with whether the request succeeded in the History backend layer.
  HideVisits(array<URLVisit> visits) => (bool success);

  // Requests to remove all visits to the specified URLs in the specified
  // timespan in `visits`. This includes the less recent visits to the same set
  // of URLs whose information is preserved in `visits`. The returned Promise
  // resolves with whether the request succeeded in the History backend layer.
  RemoveVisits(array<URLVisit> visits) => (bool success);

  // Requests to open the URLs in `visits` in a new tab group. The new tab group
  // has an optional name `tab_group_name`.
  OpenVisitUrlsInTabGroup(array<URLVisit> visits, string? tab_group_name);

  // Records visit actions.
  RecordVisitAction(VisitAction visit_action,
                    uint32 visit_index,
                    VisitType visit_type);

  // Records related search click action.
  RecordRelatedSearchAction(RelatedSearchAction action, uint32 visit_index);

  // Records cluster actions.
  RecordClusterAction(ClusterAction cluster_action, uint32 cluster_index);

  // Records that the journeys visibility was toggled.
  RecordToggledVisibility(bool visible);
};

// WebUI-side handler for requests from the browser.
interface Page {
  // Called with the results of the last call to `QueryClusters()`. `result`
  // contains the freshest Clusters in reverse chronological order, along with
  // continuation query params meant to be used in the follow-up request to load
  // older Clusters.
  OnClustersQueryResult(QueryResult result);

  // Called when the browser has found a suitable image for `cluster_index`.
  OnClusterImageUpdated(int32 cluster_index, url.mojom.Url image_url);

  // Called with the set of hidden visits when the last accepted call to
  // `HideVisits()` succeeds. `hidden_visits` will be used to update the UI.
  OnVisitsHidden(array<URLVisit> hidden_visits);

  // Called with the set of removed visits when the last accepted call to
  // `RemoveVisits()` succeeds. `removed_visits` will be used to update the UI.
  OnVisitsRemoved(array<URLVisit> removed_visits);

  // Called when History is deleted from a different tab.
  OnHistoryDeleted();

  // Called when the user needs to set `query` for the existing WebUI surface.
  OnQueryChangedByUser(string query);
};
chromium/ui/webui/resources/cr_components/history_clusters/history_clusters.mojom
