chromium/chrome/browser/ui/webui/ash/settings/search/mojom/search.mojom

// Copyright 2020 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.settings.mojom;

import "ash/webui/settings/public/constants/routes.mojom";
import "ash/webui/settings/public/constants/setting.mojom";
import "chrome/browser/ui/webui/ash/settings/search/mojom/search_result_icon.mojom";
import "mojo/public/mojom/base/string16.mojom";

// Describes the type of settings result.
enum SearchResultType {
  // Result corresponding to a Section (top-level item in Settings navigation).
  kSection,

  // Result corresponding to a Subpage (nested full page).
  kSubpage,

  // Result corresponding to an individual setting.
  kSetting,
};

// Default ranking, which is used to break ties when searching for results.
// Manually set by the settings team to ensure that certain results can be
// displayed more prominently.
enum SearchResultDefaultRank {
  kHigh,
  kMedium,
  kLow,
};

// Behavior used when determining whether to return parent results for a query.
// Results are returned based on whether text for those results matches the
// user's query, but we also support returning a result for the parent of the
// original result. In this context, a "parent" refers to a section or subpage
// which contains a child subpage or setting. For example,
// Subpage::kWifiNetworks is a subpage whose parent is Section::kNetwork, and
// Setting::kWifiOnOff is a setting whose parent is Subpage::kWifiNetworks.
enum ParentResultBehavior {
  // Returns parent results as long as the number of maximum results is not
  // exceeded.
  kAllowParentResults,

  // Does not return parent results.
  kDoNotIncludeParentResults,
};

// Identifier for the result; each result describes one section, subpage, or
// setting.
union SearchResultIdentifier {
  chromeos.settings.mojom.Section section;
  chromeos.settings.mojom.Subpage subpage;
  chromeos.settings.mojom.Setting setting;
};

// Search result metadata.
struct SearchResult {
  // String to be displayed as a result in the UI. Meant to be displayed
  // directly (i.e., not an ID but rather the actual text).
  mojo_base.mojom.String16 text;

  // String for the "canonical" version of this result. Some search results use
  // alternate text (e.g., "Monitor" instead of "Display"). Note that it is
  // often the case that |text| and |canonical_text| are the same
  // string.
  mojo_base.mojom.String16 canonical_text;

  // The URL path containing the relevant setting, which may or may not contain
  // URL parameters. For example, the Wi-Fi list settings page is
  // chrome://os-settings/networks?type=WiFi, so the field would be
  // "networks?type=WiFi" for this page.
  string url_path_with_parameters;

  // Icon to display for the search result.
  SearchResultIcon icon;

  // Relevance score, in the range [0, 1]. A score of 1 indicates a perfect
  // string match.
  double relevance_score;

  // List of names of the ancestor sections/subpages for this result. The list
  // contains the Settings app name and, if applicable, the ancestor section and
  // subpage names. Names are all localized String16s which can be displayed in
  // the UI (e.g., as breadcrumbs).
  //
  // Example 1 - Wi-Fi subpage: ["Settings", "Network"]
  // Example 2 - External storage: ["Settings", "Device", "Storage management"]
  array<mojo_base.mojom.String16> settings_page_hierarchy;

  // Default ranking, which is used to break ties when searching for results.
  SearchResultDefaultRank default_rank;

  // True if this result was generated due to a text match; this field can be
  // false if it was constructed due to a ParentResultBehavior.
  bool was_generated_from_text_match;

  // The type and identifier for this search result. The value of the |type|
  // field indicates the union member used by |id|.
  SearchResultType type;
  SearchResultIdentifier id;
};

// Used to observe changes to search results.
interface SearchResultsObserver {
  // Called when the availability of one or more search results has changed. In
  // this context, "availability" refers to whether a search result can be
  // returned based on the user's current state. E.g., "Cellular" results are
  // only shown if the device has an attached modem, so this function would be
  // called whenever the user plugs in or unplugs a USB modem. Clients can use
  // this function to ensure that they do not show "stale" results which are no
  // longer actionable by the user.
  OnSearchResultsChanged();
};

// Provides settings search results. Implemented in the browser process;
// intended to be called from settings JS and Launcher C++.
interface SearchHandler {
  // Searches settings for the given query and returns a list of results, sorted
  // from most relevant to least relevant. An empty array indicates no relevant
  // results.
  //
  // This function returns an array with a maximum size of |max_num_results|,
  // but the array may contain fewer elements if there are fewer results.
  // Clients should never pass a value of 0 for |max_num_results|, since that
  // would return an empty result array.
  Search(mojo_base.mojom.String16 query,
         uint32 max_num_results,
         ParentResultBehavior parent_result_behavior) =>
             (array<SearchResult> results);

  // Adds an observer of search results. Disconnected observers are discarded;
  // to stop observing, close the connection.
  Observe(pending_remote<SearchResultsObserver> observer);
};