chrome/browser/ui/webui/new_tab_page/new_tab_page.mojom

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

module new_tab_page.mojom;

import "chrome/common/search/omnibox.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/text_direction.mojom";
import "mojo/public/mojom/base/time.mojom";
import "skia/public/mojom/skcolor.mojom";
import "url/mojom/url.mojom";


struct OneGoogleBarParts {
  string bar_html;
  string in_head_script;
  string in_head_style;
  string after_bar_script;
  string end_of_body_html;
  string end_of_body_script;
};

struct MostVisitedTile {
  string title;
  mojo_base.mojom.TextDirection title_direction;
  url.mojom.Url url;
  bool is_query_tile;

  // ======= METRICS =======
  // Identifier of most visited entry source (e.g. top sites).
  int32 source;
  // Identifier of most visited entry title source (e.g. page's title tag).
  int32 title_source;
  // Time the most visited entry was generated (e.g. received by a suggestion
  // server).
  mojo_base.mojom.Time data_generation_time;
};

struct MostVisitedInfo {
  bool custom_links_enabled;
  bool visible;
  array<MostVisitedTile> tiles;
};

// A collection of background images.
struct BackgroundCollection {
  // Collection identifier.
  string id;
  // Localized string of the collection name.
  string label;
  // URL to a preview image for the collection. Can point to untrusted content.
  url.mojom.Url preview_image_url;
};

// A background image in a collection.
struct CollectionImage {
  // Human readable attributions of the background image.
  string attribution_1;
  string attribution_2;
  // URL associated with the background image. Used for href.
  url.mojom.Url attribution_url;
  // URL of image. Can point to untrusted content.
  url.mojom.Url image_url;
  // URL to a preview of the image. Can point to untrusted content.
  url.mojom.Url preview_image_url;
};

// Theme settings for the NTP realbox.
struct SearchBoxTheme {
  skia.mojom.SkColor bg;
  skia.mojom.SkColor icon;
  skia.mojom.SkColor icon_selected;
  skia.mojom.SkColor placeholder;
  skia.mojom.SkColor results_bg;
  skia.mojom.SkColor results_bg_hovered;
  skia.mojom.SkColor results_bg_selected;
  skia.mojom.SkColor results_dim;
  skia.mojom.SkColor results_dim_selected;
  skia.mojom.SkColor results_text;
  skia.mojom.SkColor results_text_selected;
  skia.mojom.SkColor results_url;
  skia.mojom.SkColor results_url_selected;
  skia.mojom.SkColor text;
};

// The background image URL and styling.
struct BackgroundImage {
  // URL to the background image. Can point to untrusted content.
  url.mojom.Url url;
  // URL to a higher res background image. Can point to untrusted content.
  url.mojom.Url? url_2x;
  // URL to a logo of the theme. Has chrome:// scheme.
  url.mojom.Url? attribution_url;
  // CSS styling properties set on the background image.
  string? size;
  string? repeat_x;
  string? repeat_y;
  string? position_x;
  string? position_y;
};

// A generic theme.
struct Theme {
  skia.mojom.SkColor background_color;
  skia.mojom.SkColor shortcut_background_color;
  skia.mojom.SkColor shortcut_text_color;
  // True if |shortcut_background_color| is dark.
  bool shortcut_use_white_add_icon;
  // True if the shortcuts titles should be wrapped in a pill.
  bool shortcut_use_title_pill;
  // True if the theme is default.
  bool is_default;
  // True if the theme is dark (e.g. NTP background color is dark).
  bool is_dark;
  // Color of Google logo. If not set show the logo multi-colored.
  skia.mojom.SkColor? logo_color;
  // Selected collection for daily refresh.
  string? daily_refresh_collection_id;
  // The background image.
  BackgroundImage? background_image;
  // Human readable attributions of the background image.
  string? background_image_attribution_1;
  string? background_image_attribution_2;
  // URL associated with the background image. Used for href.
  url.mojom.Url? background_image_attribution_url;

  // Theme settings for the NTP realbox. Matching those of the Omnibox.
  SearchBoxTheme search_box;
};

// Specifies look of the doodle share button.
struct DoodleShareButton {
  // Position in pixels relative to the doodle's upper left corner.
  int32 x;
  int32 y;
  // Button background color.
  skia.mojom.SkColor background_color;
  // Data URL of icon shown on the button.
  url.mojom.Url icon_url;
};

// Type of image of an image doodle. Used for metrics logging only.
enum DoodleImageType {
  // Animation of an animated doodle.
  kAnimation,
  // Static preview image of an animated doodle.
  kCta,
  // Image of a static doodle.
  kStatic,
};

// A simple or animated doodle in either dark or light mode.
struct ImageDoodle {
  // Doodle image encoded as data URL.
  url.mojom.Url image_url;
  // URL pointing to animated content (e.g. gif). Only set for animated doodles.
  url.mojom.Url? animation_url;
  // Dimensions of the original image in pixels.
  uint32 width;
  uint32 height;
  // Color of the background the doodle was designed for. If the NTP background
  // differs from that color we show the doodle in a box of that color.
  skia.mojom.SkColor background_color;
  // Specification of the share button.
  DoodleShareButton? share_button;
  // URLs to be pinged when an image has been shown.
  url.mojom.Url image_impression_log_url;
  url.mojom.Url? animation_impression_log_url;
};

// A simple or animated doodle in both dark and light mode.
struct AllModeImageDoodle {
  // Doodles for respective modes.
  ImageDoodle light;
  ImageDoodle? dark;
  // URL opened in new tab when the doodle is clicked.
  url.mojom.Url on_click_url;
  // URL displayed to users, which they can use to share the doodle.
  url.mojom.Url share_url;
};

// An interactive doodle.
struct InteractiveDoodle {
  // URL pointing to doodle page.
  url.mojom.Url url;
  // Initial width and height of the doodle iframe in pixels.
  uint32 width;
  uint32 height;
};

// A doodle. Retrieved from the Google doodle server.
struct Doodle {
  // Set for simple and animated doodles.
  AllModeImageDoodle? image;
  // Set for interactive doodles.
  InteractiveDoodle? interactive;
  // Localized description of the doodle.
  string description;
};

// A channel through which a doodle can be shared.
enum DoodleShareChannel {
  kFacebook,
  kTwitter,
  kEmail,
  kLinkCopy,
};

struct PromoImagePart {
  url.mojom.Url image_url;
  url.mojom.Url target;
};

struct PromoLinkPart {
  string? color;
  string text;
  url.mojom.Url url;
};

struct PromoTextPart {
  string? color;
  string text;
};

union PromoPart {
  PromoImagePart image;
  PromoLinkPart link;
  PromoTextPart text;
};

// Homepage promo used to display a message with a link on the NTP.
struct Promo {
  // A unique identifier for this promo.
  string? id;
  // URL to ping to log a promo impression. May be invalid.
  url.mojom.Url? log_url;
  // Middle slot promo data.
  array<PromoPart> middle_slot_parts;
};

// Action the user performed while using the customize dialog. Used for metrics
// logging only. Actions correspond to items in NTPLoggingEventType.
enum CustomizeDialogAction {
  kCancelClicked,
  kDoneClicked,
  kOpenClicked,
  kBackgroundsBackClicked,
  kBackgroundsNoBackgroundSelected,
  kBackgroundsCollectionOpened,
  kBackgroundsRefreshToggleClicked,
  kBackgroundsImageSelected,
  kBackgroundsUploadFromDeviceClicked,
  kShortcutsCustomLinksClicked,
  kShortcutsMostVisitedClicked,
  kShortcutsVisibilityToggleClicked,
};

// Action the user performed while using voice search. Used for metrics logging
// only. Actions correspond to items in NTPLoggingEventType.
enum VoiceSearchAction {
  kActivateSearchBox,
  kActivateKeyboard,
  kCloseOverlay,
  kQuerySubmitted,
  kSupportLinkClicked,
  kTryAgainLink,
  kTryAgainMicButton,
};

// Errors occurred while using voice search. Errors correspond to items in
// NTPLoggingEventType.
enum VoiceSearchError {
  kAborted,
  kNoSpeech,
  kAudioCapture,
  kNetwork,
  kNotAllowed,
  kLanguageNotSupported,
  kNoMatch,
  kServiceNotAllowed,
  kBadGrammar,
  kOther,
};

// Used by the WebUI page to bootstrap bidirectional communication.
interface PageHandlerFactory {
  // The WebUI page's |BrowserProxy| singleton calls this method when the page
  // is first initialized.
  CreatePageHandler(pending_remote<Page> page,
                    pending_receiver<PageHandler> handler);
};

// Browser-side handler for requests from WebUI page.
interface PageHandler {
  // Adds tile.
  AddMostVisitedTile(url.mojom.Url url, string title) => (bool success);
  // Deletes tile by |url|.
  DeleteMostVisitedTile(url.mojom.Url url);
  // Moves tile identified by url to a new position at index |new_pos|.
  ReorderMostVisitedTile(url.mojom.Url url, uint8 new_pos);
  // Replaces the custom and most-visited tiles with the default tile set.
  RestoreMostVisitedDefaults();
  // Sets the background image and notifies all NTPs of the change.
  SetBackgroundImage(string attribution_1, string attribution_2,
      url.mojom.Url attribution_url, url.mojom.Url image_url);
  // Sets collection id for daily refresh. When |collection_id| is empty, the
  // daily refresh is turned off.
  SetDailyRefreshCollectionId(string collection_id);
  // Clears the background and daily refresh settings.
  SetNoBackgroundImage();
  // Set the visibility and whether custom links are enabled.
  SetMostVisitedSettings(bool customLinksEnabled, bool visible);
  // Undoes the last action done to the tiles (add, delete, reorder, restore or
  // update). Note that only the last action can be undone.
  UndoMostVisitedTileAction();
  // Called to update the tiles.
  UpdateMostVisitedInfo();
  // Updates a tile by url.
  UpdateMostVisitedTile(url.mojom.Url url, url.mojom.Url new_url,
                        string new_title)
      => (bool success);
  // Returns the collections of background images.
  GetBackgroundCollections() => (array<BackgroundCollection> collections);
  // Returns the images of a collection identified by |collection_id|.
  GetBackgroundImages(string collection_id) => (array<CollectionImage> images);
  // Invisibly focuses the omnibox.
  FocusOmnibox();
  // Pastes |text| into the omnibox.
  PasteIntoOmnibox(string text);
  // Gets current doodle if there is one.
  GetDoodle() => (Doodle? doodle);
  // Choose custom background from local file system.
  ChooseLocalCustomBackground() => (bool success);
  // Get the OneGoogleBarParts to be inlined in the NTP. Forwards the query
  // parameters to the endpoint that serves the OneGoogleBar parts with
  // |query_params|.
  GetOneGoogleBarParts(string query_params) => (OneGoogleBarParts? parts);
  // Get the middle slot promo if it exists.
  GetPromo() => (Promo? promo);
  // Called when a module the given id is dismissed.
  OnDismissModule(string module_id);
  // Called when a module the given id is restored.
  OnRestoreModule(string module_id);
  // If |visible| the modules will be shown.
  SetModulesVisible(bool visible);
  // Triggers a call to |SetModulesVisible| with the current visibility setting.
  UpdateModulesVisible();

  // ======= METRICS =======
  // Logs that |tiles| were displayed / updated at |time|. The first instance of
  // this event is used as a proxy for when the NTP has finished loading.
  OnMostVisitedTilesRendered(array<MostVisitedTile> tiles, double time);
  // Logs that the One Google Bar was added to the DOM / loaded in an iframe at
  // |time|.
  OnOneGoogleBarRendered(double time);
  // Logs that the promo iframe was loaded at |time| and pings |log_url| for
  // promo metrics logging.
  OnPromoRendered(double time, url.mojom.Url? log_url);
  // Logs that |tile| at position |index| was triggered to navigate to that
  // most visited entry.
  // |mouse_button| indicates which mouse button was pressed on the entry. See
  // https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
  OnMostVisitedTileNavigation(MostVisitedTile tile,
                        uint32 index,
                        uint8 mouse_button,
                        bool alt_key,
                        bool ctrl_key,
                        bool meta_key,
                        bool shift_key);
  // Logs an action performed in the customize dialog.
  OnCustomizeDialogAction(CustomizeDialogAction action);
  // Logs that the |type| image of an image doodle has been clicked. If set, the
  // |log_url| should be pinged for metrics logging.
  OnDoodleImageClicked(DoodleImageType type, url.mojom.Url? log_url);
  // Logs that the |type| image of an image doodle has been shown at |time|.
  // Returns additional params, which are fetched from |image_url|, we use to
  // perform more doodle logging later. We can't fetch the params in JS because
  // the NTP renderer process does not have network access.
  OnDoodleImageRendered(DoodleImageType type,
                        double time,
                        url.mojom.Url log_url)
      => (string? image_click_params,
          url.mojom.Url? interaction_log_url,
          string? share_id);
  // Logs that the doodle with |doodle_id| has been shared through |channel|.
  // |share_id| comes from a previous call to |OnDoodleImageRendered|.
  OnDoodleShared(DoodleShareChannel channel,
                 string doodle_id,
                 string? share_id);
  // Logs that a link on a promo has been clicked.
  OnPromoLinkClicked();
  // Logs an action performed while using voice search.
  OnVoiceSearchAction(VoiceSearchAction action);
  // Logs an error occurred while using voice search.
  OnVoiceSearchError(VoiceSearchError error);
  // Logs a module impression. Called when a module is loaded and can be seen by
  // the user (scrolled into view).
  OnModuleImpression(string module_id, double time);
  // Logs when a module is loaded with data.
  OnModuleLoaded(string module_id, double time);
  // Logs when a user interacts with a module which will result in a navigation.
  OnModuleUsage(string module_id);
  // Logs that the modules have been shown at |time|.
  OnModulesRendered(double time);
  // Logs that the <ntp-app> element's |ready| callback method was called.
  OnAppRendered(double time);

  // ======= REALBOX =======
  // Queries autocomplete matches from the browser.
  QueryAutocomplete(mojo_base.mojom.String16 input,
                    bool prevent_inline_autocomplete);
  // Cancels the current autocomplete query. Clears the result set if
  // |clear_result| is true.
  StopAutocomplete(bool clear_result);
  // Handles navigation to an autocomplete match (i.e. an item in the realbox's
  // list of matches). Note: |url| is passed solely to verify that the browser
  // and renderer are in sync; don't trust this content or use it for anything
  // other than verification purposes (i.e. is the URL still the same?).
  // TODO(crbug.com/1076604): replace |url| with an unguessable token.
  // |mouse_button| indicates which mouse button was pressed on the match. See
  // https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
  OpenAutocompleteMatch(uint8 line,
                        url.mojom.Url url,
                        bool are_matches_showing,
                        mojo_base.mojom.TimeDelta time_elapsed_since_last_focus,
                        uint8 mouse_button,
                        bool alt_key,
                        bool ctrl_key,
                        bool meta_key,
                        bool shift_key);
  // Deletes the AutocompleteMatch in the current results by |line| number if
  // it is deletable.
  DeleteAutocompleteMatch(uint8 line);
  // Tells the browser to allow suggestions with the given suggestion group ID
  // to appear in the results if they currently are not allowed to or to prevent
  // them from appearing in the results if they are currently permitted to.
  ToggleSuggestionGroupIdVisibility(int32 suggestion_group_id);
  // Logs the time it took in milliseconds since the first character (in a
  // series of characters) was typed until Autocomplete results were painted.
  LogCharTypedToRepaintLatency(mojo_base.mojom.TimeDelta latency);
};

// WebUI-side handler for requests from the browser.
interface Page {
  // Updates the page with most-visited info which includes whether the
  // tiles should be shown, if links can be customized and the tiles.
  SetMostVisitedInfo(MostVisitedInfo info);
  // Sets the current theme.
  SetTheme(Theme theme);
  // If |focused| fakes focus on the fakebox.
  SetFakeboxFocused(bool focused);
  // If |visible| shows the fakebox.
  SetFakeboxVisible(bool visible);
  // Updates the module visibility.
  SetModulesVisible(bool visible);

  // ======= REALBOX =======
  // Updates the NTP realbox with the autocomplete results.
  AutocompleteResultChanged(search.mojom.AutocompleteResult result);
  // Updates the NTP realbox popup with the image or favicon data URL for the
  // given |match_index| and |url| where |url| is an AutocompleteMatch image_url
  // or destination_url for an entity or a navigation suggestion respectively.
  AutocompleteMatchImageAvailable(uint32 match_index,
                                  url.mojom.Url url,
                                  string data_url);
};