ash/webui/personalization_app/mojom/personalization_app.mojom

// 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 ash.personalization_app.mojom;

import "mojo/public/mojom/base/big_buffer.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "skia/public/mojom/skcolor.mojom";
import "url/mojom/url.mojom";

// This should be kept in sync with |ash::WallpaperLayout|
enum WallpaperLayout {
  // Center the wallpaper on the desktop without scaling it. The wallpaper
  // may be cropped.
  kCenter,
  // Scale the wallpaper (while preserving its aspect ratio) to cover the
  // desktop; the wallpaper may be cropped.
  kCenterCropped,
  // Scale the wallpaper (without preserving its aspect ratio) to match the
  // desktop's size.
  kStretch,
  // Tile the wallpaper over the background without scaling it.
  kTile,
};

// This should be kept in sync with |ash::WallpaperType|
enum WallpaperType {
  kDaily = 0,         // Surprise wallpaper. Changes once a day if enabled.
  kCustomized = 1,    // Selected by user.
  kDefault = 2,       // Default.
  /* kUnknown = 3 */  // Removed.
  kOnline = 4,        // WallpaperInfo.location denotes an URL.
  kPolicy = 5,        // Controlled by policy, can't be changed by the user.
  kThirdParty = 6,    // Current wallpaper is set by a third party app.
  kDevice = 7,        // Current wallpaper is the device policy controlled
                      // wallpaper. It shows on the login screen if the device
                      // is an enterprise managed device.
  kOneShot = 8,       // Current wallpaper is shown one-time only, which doesn't
                      // belong to a particular user and isn't saved to file. It
                      // goes away when another wallpaper is shown or the
                      // browser process exits. Note: the image will never be
                      // blurred or dimmed.
  // kGooglePhotos = 9,    // Deprecated: b/229788402
  kDailyGooglePhotos = 10, // WallpaperInfo.location contains the Google Photos
                           // album id.
  kOnceGooglePhotos = 11,  // WallpaperInfo.location contains the Google Photos
                           // photo id.
};

// The image type specific to online wallpapers. This should be kept in sync
// with |backdrop::Image::ImageType|.
enum OnlineImageType {
  kUnknown = 0,
  kLight = 1,
  kDark = 2,
};

// Values for the user-level setting indicating access to Google Photos data.
enum GooglePhotosEnablementState {
  // Setting could not be retrieved due to a network or server error, or the
  // server returned an unknown setting state.
  kError = 0,

  // An enterprise setting prevents this user from accessing Google Photos data.
  kDisabled = 1,

  // This user can access Google Photos data.
  kEnabled = 2,
};

// WallpaperCollection contains a list of |WallpaperImage| objects.
struct WallpaperCollection {
    // This ID is used as the argument to |FetchImagesForCollection|.
    string id;

    // Name of this collection to be displayed to the user.
    string name;

    // The preview image URLs of this collection.
    array<url.mojom.Url> previews;
};

// Encapsulates metadata for a Google Photos album, which is itself displayed in
// the UI and from which a user may select a photo as their wallpaper.
struct GooglePhotosAlbum {
    // Unique identifier for this album.
    string id;

    // User-generated album title to be displayed.
    string title;

    // Number of photos stored within this album.
    int32 photo_count;

    // URL to the bytes of the album's displayed cover photo.
    url.mojom.Url preview;
};

// Represents the server-provided response to a Google Photos albums request.
struct FetchGooglePhotosAlbumsResponse {
    // List of non-empty Google Photos albums (absent on error).
    array<GooglePhotosAlbum>? albums;

    // Token that allows the client to fetch more albums not returned in the
    // current query (absent if the last of the albums was returned).
    string? resume_token;
};

// Represents a single image that can be set as user wallpaper.
struct WallpaperImage {
    // URL of the image file to be displayed in the UI.
    url.mojom.Url url;

    // Localized attribution text such as "Photo by John Doe".
    array<string> attribution;

    // Unique opaque identifier for this image.
    uint64 asset_id;

    // The identifier of a unit of images e.g. Dark/Light variants of the same
    // wallpaper.
    uint64 unit_id;

    // The type of the online image .i.e kLight, kDark, etc.
    OnlineImageType type;
};

// Encapsulates metadata for a Google Photos photo, which can be displayed as a
// tile in the wallpaper picker UI or chosen as the device wallpaper.
struct GooglePhotosPhoto {
    // Unique identifier for this photo.
    string id;

    // A string which uniquely identifies a Google Photos photo across albums.
    // Note that the same photo appearing in multiple albums will have a unique
    // |id| for each album in which it appears, but the |dedup_key| is shared
    // across albums.
    string? dedup_key;

    // Display name of the photo, derived from the photo's server-side filename.
    string name;

    // Human-readable string representation of the date the photo was
    // taken, e.g., "Monday, March 6, 2008", translated into the user's current
    // locale.
    mojo_base.mojom.String16 date;

    // URL of the image to be displayed in the UI.
    url.mojom.Url url;

    // Location from the photo's Google Photos metadata. Can be a geographic
    // place or a user-assigned alias such as "Home" or "Work".
    string? location;
};

// Represents the server-provided response to a Google Photos photos request.
struct FetchGooglePhotosPhotosResponse {
    // List of photos from the user's Google Photos library (absent on error).
    array<GooglePhotosPhoto>? photos;

    // Token that allows the client to fetch more photos not returned in the
    // current query (absent if the last of the photos was returned).
    string? resume_token;
};

// Represents the response to a daily refresh request.
struct SetDailyRefreshResponse {
  // Indicates whether the request is successful.
  bool success;

  // Indicates whether the request forces the current wallpaper image to
  // refresh.
  bool force_refresh;
};

// Represents the currently selected wallpaper image.
struct CurrentWallpaper {
  // Attribution text such as "Photo by John Doe" or the file name of the local
  // image.
  array<string> attribution;

  // The layout of the image.
  WallpaperLayout layout;

  // The type of the image.
  WallpaperType type;

  // A unique identifier for the image. This is used to identify which
  // |WallpaperImage| or local image the user has selected.
  string key;
};

// Receives updated wallpaper information whenever it is changed.
interface WallpaperObserver {
  // Triggered by |WallpaperControllerObserver::OnWallpaperPreviewEnded|.
  OnWallpaperPreviewEnded();

  // Triggered by |WallpaperControllerObserver::OnWallpaperChanged|. Retrieves
  // updated wallpaper information and calls the observer. |image| will be null
  // if there is an error retrieving wallpaper information.
  OnWallpaperChanged(CurrentWallpaper? image);
};

// Provides APIs to retrieve Wallpaper information. This API is exposed only to
// the Personalization App (chrome://personalization). It is a mojom wrapper for
// APIs found in |backdrop_wallpaper.proto| and |WallpaperController| APIs to
// change the user's wallpaper in Ash.
interface WallpaperProvider {
    // Called to force the browser window to make the native views transparent
    // so that the user can see wallpaper in fullscreen on their desktop. Safe
    // to call multiple times.
    MakeTransparent();

    // Called to reverse `MakeTransparent()`. Being called while exiting
    // fullscreen preview to avoid unexpected transparency. Safe to call
    // multiple times, even before `MakeTransparent()` is called.
    MakeOpaque();

    // Fetch a list of WallpaperCollection objects from the Backdrop API. Will
    // be displayed to the user to allow them to select an individual collection
    // to view in more detail. |collections| will be null on error.
    FetchCollections() => (array<WallpaperCollection>? collections);

    // Fetch a list of WallpaperImage objects from the Backdrop API that can be
    // set as the user's wallpaper. |images| will be null on error.
    FetchImagesForCollection(string collection_id) =>
        (array<WallpaperImage>? images);

    // Fetch the list of albums the user has created in Google Photos. Albums
    // with no photo assets will not be returned. On error, |response.albums|
    // will be absent. |response.resume_token| will be present when there are
    // more results to fetch; |resume_token| will be present when this is a
    // follow-up query to one that indicated there were more results to fetch.
    FetchGooglePhotosAlbums(string? resume_token) =>
        (FetchGooglePhotosAlbumsResponse response);

    // Fetch whether the user is allowed to access Google Photos data.
    FetchGooglePhotosEnabled() => (GooglePhotosEnablementState state);

    // Fetch photo(s) the user has stored in Google Photos. If provided,
    // |item_id| specifies one photo to fetch. If provided, |album_id| specifies
    // an album whose photos are fetched. At most one of |item_id| or |album_id|
    // should be provided. If neither ID is provided, then the user's entire
    // library is fetched. Only visible photos will be returned. On error,
    // |response.photos| will be absent. |response.resume_token| will be present
    // when there are more results to fetch; |resume_token| will be present when
    // this is a follow-up query to one that indicated there were more results
    // to fetch.
    FetchGooglePhotosPhotos(string? item_id, string? album_id,
        string? resume_token) => (FetchGooglePhotosPhotosResponse response);

    // Fetch a list of FilePath objects from the local file system. |images|
    // will be null on failure.
    GetLocalImages() => (array<mojo_base.mojom.FilePath>? images);

    // Device default image is a special case of an image stored on disk. It is
    // stored in a special directory and the file is not accessible to the user.
    // If this device has a default image, return a thumbnail representation of
    // it. |data| will be empty url on failure or if the device has no
    // default image.
    GetDefaultImageThumbnail() => (url.mojom.Url data);

    // Fetch a thumbnail data url for the given local image path. |data| will be
    // empty on failure.
    GetLocalImageThumbnail(mojo_base.mojom.FilePath file_path) =>
        (url.mojom.Url data);

    // Binds a listener to start receiving updates on wallpaper changes.
    SetWallpaperObserver(pending_remote<WallpaperObserver> observer);

    // Sets the given backdrop wallpaper as the user's background.
    SelectWallpaper(uint64 image_asset_id, bool preview_mode) =>
        (bool success);

    // Select the device default image as the user's background. Not all devices
    // have a default image.
    SelectDefaultImage() => (bool success);

    // Sets the given local wallpaper as the user's background. Validated
    // against list of file paths returned by |GetLocalImages|.
    SelectLocalImage(mojo_base.mojom.FilePath path, WallpaperLayout layout,
        bool preview_mode) => (bool success);

    // Sets the Google Photos photo with the given id as the wallpaper.
    SelectGooglePhotosPhoto(string id, WallpaperLayout layout,
        bool preview_mode) => (bool success);

    // Sets the Google Photos album with the given id as the daily refresh
    // album. May refresh the current wallpaper image if it is not part of the
    // album.
    SelectGooglePhotosAlbum(string id)
        => (SetDailyRefreshResponse response);

    // Gets the id of the current Google Photos album on daily refresh, or an
    // empty string if Google Photos daily refresh is not active.
    GetGooglePhotosDailyRefreshAlbumId() => (string album_id);

    // Sets the layout for current wallpaper.
    SetCurrentWallpaperLayout(WallpaperLayout layout);

    // Sets and enables daily refresh for the given |collection_id|. May refresh
    // the current wallpaper image if it is not part of the collection.
    SetDailyRefreshCollectionId(string collection_id)
        => (SetDailyRefreshResponse response);

    // Get the daily refresh collection id. It can be empty if daily refresh is
    // not enabled.
    GetDailyRefreshCollectionId() => (string collection_id);

    // Refresh the wallpaper. Noop if daily refresh is not enabled.
    UpdateDailyRefreshWallpaper() => (bool success);

    // Indicates whether the device is in tablet mode.
    IsInTabletMode() => (bool tablet_mode);

    // Confirms the wallpaper being previewed to be set as the actual user
    // wallpaper. Must be called in preview mode.
    ConfirmPreviewWallpaper();

    // Cancels the wallpaper preview and reverts to the user wallpaper. Must be
    // called in preview mode.
    CancelPreviewWallpaper();
};

enum ColorScheme {
  kStatic = 0,
  kTonalSpot = 1,
  kNeutral = 2,
  kExpressive = 3,
  kVibrant = 4,
};

// Receives information whenever there are theme related changes such as color
// mode.
interface ThemeObserver {
  // Triggered by |ColorModeObserver::OnColorModeChanged|. Retrieves information
  // whether dark mode is enabled
  OnColorModeChanged(bool dark_mode_enabled);

  // Notifies the JS side the current state of color mode auto scheduler.
  OnColorModeAutoScheduleChanged(bool enabled);

  //Notifies the JS side about the current state of the color scheme.
  OnColorSchemeChanged(ColorScheme color_scheme);

  // Notifies the JS side about the current state of the static color.
  OnStaticColorChanged(skia.mojom.SkColor? color);
};

// Provides APIs to expose theme settings such dark/light color mode.
interface ThemeProvider {
  // Binds a listener to start receiving updates on color mode changes.
  SetThemeObserver(pending_remote<ThemeObserver> observer);

  // Disables or enables dark color mode.
  SetColorModePref(bool dark_mode_enabled);

  // Disables or enables dark color mode auto scheduler.
  SetColorModeAutoScheduleEnabled(bool enabled);

  // Sets the color scheme for dynamic color.
  // @see //ash/style/color_palette_controller.h
  SetColorScheme(ColorScheme colorScheme);

  // Sets the seed color for dynamic color.
  // @see //ash/style/color_palette_controller.h
  SetStaticColor(skia.mojom.SkColor static_color);

  // Retrieves the color scheme for dynamic color.
  GetColorScheme() => (ColorScheme color_scheme);

  // Retrieves the static seed color for dynamic color.
  GetStaticColor() => (skia.mojom.SkColor? static_color);

  // Returns whether color mode auto scheduler is enabled.
  IsColorModeAutoScheduleEnabled() => (bool enabled);

  // Returns whether dark mode is enabled.
  IsDarkModeEnabled() => (bool dark_mode_enabled);
};

// Contains information about the current user.
struct UserInfo {
  // The display email of the user. It can be empty for guest users.
  string email;

  // The display name of the user.
  string name;
};

// Additional attribution information for several deprecated user image choices.
// These avatars are no longer able to be selected by users, but some users may
// still have one set as their chosen avatar image.
struct DeprecatedSourceInfo {
  // The name of the author that created the avatar image.
  mojo_base.mojom.String16 author;

  // The website of the author.
  url.mojom.Url website;
};

// A default user image stored on the device that can be set as the user's
// device avatar image.
struct DefaultUserImage {
  // A user image is identified by an index.
  int32 index;

  // The title of the image to display to the user.
  mojo_base.mojom.String16 title;

  // A url to display the image. Typically |chrome://theme/IDR_LOGIN_DEFAULT_X|.
  url.mojom.Url url;

  // Additional information about the source of the avatar.
  DeprecatedSourceInfo? source_info;
};

// An empty struct that is just used to indicate the presence of a profile
// image.
struct ProfileImage {};

// An empty struct that is used to signify the user does not have a valid image.
struct InvalidImage {};

// The current image that the user has selected as device avatar.
union UserImage {
  // Set if the user has selected a default (built-in) avatar image.
  DefaultUserImage default_image;

  // Set if the user has selected an external image, usually from file or from
  // webcam capture.
  mojo_base.mojom.BigBuffer external_image;

  // Set if the user has selected their gaia account profile image.
  ProfileImage profile_image;

  // Set if the user does not have a valid image selected or there was an error.
  InvalidImage invalid_image;
};

// Receives necessary information to display and change user image for the
// current user.
interface UserImageObserver {
  // Triggered by |UserManager::Observer::OnUserImageChanged|.
  OnUserImageChanged(UserImage user_image);

  // Triggered by |UserManager::Observer::OnUserProfileImageUpdated|.
  OnUserProfileImageUpdated(url.mojom.Url profile_image);

  // Triggered by
  // |ash::CameraPresenceNotifier::Observer::OnCameraPresenceCheckDone|.
  OnCameraPresenceCheckDone(bool is_camera_present);

  // Triggered by
  // |UserManager::Observer::OnUserImageIsEnterpriseManagedChanged|.
  OnIsEnterpriseManagedChanged(bool is_enterprise_managed);
};

// Provides APIs to view information about the current user. This API is exposed
// only to the Personalization App (chrome://personalization), and is
// implemented by |PersonalizationAppUserProviderImpl| in chrome.
interface UserProvider {
  // Binds an observer for the current user's device image.
  SetUserImageObserver(pending_remote<UserImageObserver> observer);

  // Return information about the current user.
  GetUserInfo() => (UserInfo user_info);

  // Returns an array of default user images to choose from.
  GetDefaultUserImages() => (array<DefaultUserImage> default_user_images);

  // Select one of the default images from the provided default user images.
  SelectDefaultImage(int32 index);

  // Select the downloaded profile image as the user image.
  SelectProfileImage();

  // Set a camera image as the user's device avatar. |data| is a uint8 array of
  // the png data.
  SelectCameraImage(mojo_base.mojom.BigBuffer data);

  // Select one of the available images on disk as user's device image.
  // This opens a file dialog box from which the user can select a file.
  SelectImageFromDisk();

  // When the user has selected camera image or external file image, allow user
  // to quickly reselect that option so it is not lost if they look at images of
  // other types.
  SelectLastExternalUserImage();
};

// The animation theme for screen saver. Should be kept in sync with
// |ash::AmbientAnimationTheme|.
enum AnimationTheme {
  kSlideshow = 0,
  kFeelTheBreeze = 1,
  kFloatOnBy = 2,
};

// The source of the screensaver images come from.
enum TopicSource {
  // Google Photos.
  kGooglePhotos = 0,

  // Art related sources in Backdrop server.
  kArtGallery = 1,
};

// Temperature unit for screensaver weather section.
enum TemperatureUnit {
  kFahrenheit = 0,
  kCelsius = 1,
};

// Enumeration of UI visibility states.
// This should be kept in sync with |ash:AmbientUiVisibility|.
enum AmbientUiVisibility {
  kShown = 0,
  kPreview = 1,
  kHidden = 2,
  kClosed = 3,
};

// Album metadaba to display. Contains necessary data for both topic sources.
struct AmbientModeAlbum {
  // Unique identifier for this album. It assumes unique id across different
  // topic sources.
  string id;

  // Whether this album is selected.
  bool checked;

  // Title of the settings or the album name of the Google Photos.
  string title;

  string description;

  int32 number_of_photos;

  // Indicates which topic source this album belongs to.
  TopicSource topic_source;

  // The image URL for preview.
  url.mojom.Url url;
};

// Receives information whenever there are ambient mode pref changes.
interface AmbientObserver {
  // Retrieves information whether ambient mode is enabled.
  OnAmbientModeEnabledChanged(bool ambient_mode_enabled);

  // Notifies the JS side the current state of AnimationTheme.
  OnAnimationThemeChanged(AnimationTheme animation_theme);

  // Notifies the JS side about the current state of TopicSource.
  OnTopicSourceChanged(TopicSource topic_source);

  // Notifies the JS side about the current state of TemperatureUnit.
  OnTemperatureUnitChanged(TemperatureUnit temperature_unit);

  // Notifies the JS side about the current albums.
  OnAlbumsChanged(array<AmbientModeAlbum> albums);

  // Notifies the JS side about the previews of the selected Google Photos
  // albums.
  OnGooglePhotosAlbumsPreviewsFetched(array<url.mojom.Url> previews);

  // Notifies the JS side when ambient visibility is changed.
  OnAmbientUiVisibilityChanged(AmbientUiVisibility visibility);
};

// Provides APIs to expose Ambient mode settings.
// Used by the personalization hub WebUI to call into the browser process.
interface AmbientProvider {
  // Boolean pref for whether ambient mode is enabled.
  IsAmbientModeEnabled() => (bool enabled);

  // Enables or disables ambient mode.
  SetAmbientModeEnabled(bool enabled);

  // Binds a listener to start receiving updates on ambient mode pref changes.
  SetAmbientObserver(pending_remote<AmbientObserver> observer);

  // Sets the ambient animation theme.
  SetAnimationTheme(AnimationTheme animation_theme);

  // Sets the ambient mode topic source.
  SetTopicSource(TopicSource topic_source);

  // Sets the ambient mode temperature unit.
  SetTemperatureUnit(TemperatureUnit temperature_unit);

  // Sets one album as selected or not.
  SetAlbumSelected(string id, TopicSource topic_source, bool selected);

  // Record that the user viewed the Ambient mode page.
  SetPageViewed();

  // Request updated Ambient mode settings and albums.
  FetchSettingsAndAlbums();

  // Starts the screen saver preview.
  StartScreenSaverPreview();
};

// The supported preset colors for keyboard backlight.
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
enum BacklightColor {
  kWallpaper = 0,
  kWhite = 1,
  kRed = 2,
  kYellow = 3,
  kGreen = 4,
  kBlue = 5,
  kIndigo = 6,
  kPurple = 7,

  kRainbow = 100,
};

// Hex values of the colors displayed in the rgb keyboard section.
const uint32 kWhiteColor = 0xFFFFFF;
const uint32 kRedColor = 0xEE675C;
const uint32 kYellowColor = 0xFBBC04;
const uint32 kGreenColor = 0x34A853;
const uint32 kBlueColor = 0x00A3C2;
const uint32 kIndigoColor = 0x4285F4;
const uint32 kPurpleColor = 0xB76DF8;

// Receives information whenever there are keyboard backlight related changes
// such as backlight colors.
interface KeyboardBacklightObserver {
  // Notifies the JS side about the current state of the backlight color.
  OnBacklightColorChanged(BacklightColor color);

  // Notifies the JS side the current wallpaper-extracted color.
  OnWallpaperColorChanged(skia.mojom.SkColor wallpaper_color);
};

// Provides APIs to expose keyboard backlight settings.
interface KeyboardBacklightProvider {
  // Binds a listener to start receiving updates on backlight color changes.
  SetKeyboardBacklightObserver(pending_remote<KeyboardBacklightObserver>
      observer);

  // Sets the backlight color.
  SetBacklightColor(BacklightColor backlight_color);

  // Determines whether to show the education nudge.
  ShouldShowNudge() => (bool should_show_nudge);

  // Called when the nudge is shown.
  HandleNudgeShown();
};