chromium/chrome/browser/ui/webui/side_panel/customize_chrome/wallpaper_search/wallpaper_search.mojom

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

module side_panel.customize_chrome.mojom;

import "mojo/public/mojom/base/token.mojom";
import "skia/public/mojom/skcolor.mojom";
import "url/mojom/url.mojom";

struct KeyLabel {
  string key;
  string label;
};

// Subject descriptor. Each one is a category of subjects and its
// list of possible values.
struct Group {
  string category;
  array<KeyLabel> descriptor_as;
};

// Style descriptor value, which includes a label and an image.
struct DescriptorB {
  string key;
  string label;
  string image_path;
};

// Color descriptor value of either SkColor or hue.
// Hue is for custom colors and SkColor is for default colors.
union DescriptorDValue {
  skia.mojom.SkColor color;
  float hue;
  DescriptorDName name;
};

// Accepted color names for descriptor d.
enum DescriptorDName {
  kYellow,
};

// Full list of possible subject, style, and mood descriptors for the
// dropdowns in the Wallpaper Search UI.
struct Descriptors {
  array<Group> groups;
  array<DescriptorB> descriptor_b;
  array<KeyLabel> descriptor_c;
};

struct Inspiration {
  mojo_base.mojom.Token id;
  string description;
  url.mojom.Url background_url;
  url.mojom.Url thumbnail_url;
};

struct InspirationDescriptors {
  KeyLabel? subject;
  KeyLabel? style;
  KeyLabel? mood;
  DescriptorDValue? color;
};

struct InspirationGroup {
  InspirationDescriptors descriptors;
  array<Inspiration> inspirations;
};

struct WallpaperSearchResult {
  mojo_base.mojom.Token id;
  string image;
  ResultDescriptors? descriptors;
};

// A set of descriptors related to a single wallpaper search result or A
// set of wallpaper search results.
struct ResultDescriptors {
  string? subject;
  string? style;
  string? mood;
  DescriptorDValue? color;
};

// Wallpaper Search statuses. This enum must match the numbering for
// |NtpWallpaperSearchStatus| in new_tab_page/enums.xml. These values
// are persisted to logs. Entries should not be renumbered, removed or reused.
enum WallpaperSearchStatus {
  kOk,
  // Generic error, not specified.
  kError,
  // Too many requests.
  kRequestThrottled,
  // Browser offline.
  kOffline,
  // User is signed out.
  kSignedOut,
};

// Used by the WebUI page to bootstrap bidirectional communication.
interface WallpaperSearchHandlerFactory {
  // The WebUI calls this method when the page is first initialized.
  CreateWallpaperSearchHandler(pending_remote<WallpaperSearchClient> client,
                pending_receiver<WallpaperSearchHandler> handler);
};

// TODO(b/311697865): Replace with a common UserFeedback enum.
enum UserFeedback {
  kUnspecified,
  kThumbsUp,
  kThumbsDown,
};

// Browser-side handler for requests from WebUI page.
interface WallpaperSearchHandler {
  // Retrieves NTP descriptors.
  GetDescriptors() => (Descriptors? descriptors);

  // Retrieves image URLs of example results.
  GetInspirations() => (array<InspirationGroup>? inspirationGroups);

  // Searches NTP wallpaper for descriptors.
  // Returns list of sanitized image data.
  GetWallpaperSearchResults(ResultDescriptors result_descriptors)
        => (WallpaperSearchStatus status, array<WallpaperSearchResult> results);

  // Tells the handler that wallpaper search results with `result_ids` rendered
  // in the side panel at Unix epoch time stamp `time`.
  SetResultRenderTime(array<mojo_base.mojom.Token> result_ids, double time);

  // Sets the history image identified by `result_id` as the current background
  // image.
  SetBackgroundToHistoryImage(mojo_base.mojom.Token result_id,
      ResultDescriptors descriptors);

  // Sets the inspiration image identified by `id` as the current background
  // image.
  SetBackgroundToInspirationImage(mojo_base.mojom.Token id,
      url.mojom.Url background_url);

  // Sets wallpaper search result identified by `result_id` to background image.
  // `time` is Unix epoch time stamp of when the user selected the respective
  // preview.
  SetBackgroundToWallpaperSearchResult(mojo_base.mojom.Token result_id,
      double time, ResultDescriptors descriptors);

  // Triggers a call to |WallpaperSearchClient.SetHistory|.
  UpdateHistory();

  // Tells the handler to set a UserFeedback option on the latest result.
  SetUserFeedback(UserFeedback selected_option);

  // Opens help article about the feature in a new tab when use clicks
  // "Learn more".
  OpenHelpArticle();

  // Triggers the wallpaper search HaTS survey if eligible.
  LaunchHatsSurvey();
};

// WebUI-side handler for requests from the browser.
interface WallpaperSearchClient {
  // Sets the list of history images.
  // Contains a list of sanitized image data and their ids.
  SetHistory(array<WallpaperSearchResult> history);
};