help_bubble.mojom

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

module help_bubble.mojom;

import "mojo/public/mojom/base/time.mojom";

// Contains IPC calls that allow the HelpBubbleFactory system to connect to
// the HelpBubbleMixin and HelpBubbleElement component.
//
// The calls here allow User Education systems that use the HelpBubble
// architecture to display help bubbles in WebUI surfaces (including pages like
// Settings and secondary UI elements such as the Sidebar).
//
// Systems expected to use this IPC include FeaturePromo and Tutorials. For
// more detailed usage information, see README.md.

// Where the help bubble floats relative to its anchor.
enum HelpBubbleArrowPosition {
  TOP_LEFT,
  TOP_CENTER,
  TOP_RIGHT,

  BOTTOM_LEFT,
  BOTTOM_CENTER,
  BOTTOM_RIGHT,

  LEFT_TOP,
  LEFT_CENTER,
  LEFT_BOTTOM,

  RIGHT_TOP,
  RIGHT_CENTER,
  RIGHT_BOTTOM,
};

// Reason for dismissing a help bubble
enum HelpBubbleClosedReason {
  // page navigated away, anchor disappeared, etc.
  kPageChanged,
  // user dismissed via button or close-icon
  kDismissedByUser,
  // timeout reached
  kTimedOut,
};

// Simplified version of user_education::HelpBubbleButtonParams.
struct HelpBubbleButtonParams {
  string text;
  bool is_default = false;
};

// Progress indicator for tutorial bubbles.
struct Progress {
  uint8 current;
  uint8 total;
};

// Simplified version of user_education::HelpBubbleParams.
struct HelpBubbleParams {
  // Holds the name of the ElementIdentifier used to identify the help bubble's
  // anchor in C++ code. The HelpBubbleMixin then maps this to a specific HTML
  // element ID.
  string native_identifier;

  HelpBubbleArrowPosition position = HelpBubbleArrowPosition.TOP_CENTER;
  string? title_text;
  string body_text;
  string close_button_alt_text;
  bool force_close_button = false;
  string? body_icon_name;
  string body_icon_alt_text;
  Progress? progress;
  array<HelpBubbleButtonParams> buttons;

  // Auto-dismiss timeout as TimeDelta
  mojo_base.mojom.TimeDelta? timeout;
};

// Used by the controller to bootstrap IPC. Any WebUIController can implement
// this interface to use help bubbles; see README.md for more information.
interface HelpBubbleHandlerFactory {
  // This method is called on bootstrap to create the browser-side handler.
  CreateHelpBubbleHandler(
           pending_remote<HelpBubbleClient> client,
           pending_receiver<HelpBubbleHandler> handler);
};

// Object which handles the C++/browser side of help bubble management for a
// WebUIController.
//
// Help bubbles are anchored to specific elements in the UI, identified by
// ui::ElementIdentifiers. The HelpBubbleMixin maps this to an HTML id within
// its component.
//
// We always use the name of the ElementIdentifier (`native_identifier`) when
// showing a help bubble or when communicating events back to the handler on the
// browser side, because HTML ids can be ambiguous within a document with shadow
// DOMs.
//
// TODO(crbug.com/1376247): consider splitting into ElementTrackerHandler and
// HelpBubbleHandler, with the previous handling show/hide/activated/custom
// events and the latter handling the help bubble itself.
interface HelpBubbleHandler {
  // Indicates that the visibility of the element that the help bubble could be
  // anchored to has changed.
  HelpBubbleAnchorVisibilityChanged(string native_identifier, bool visible);

  // Notifies that a specific element tagged as a help bubble anchor has been
  // activated, which will in turn be propagated through the ui::ElementTracker
  // system as an EventType::kActivated.
  //
  // As with the above methods, the ui::ElementIdentifier will be generated from
  // `native_identifier`.
  HelpBubbleAnchorActivated(string native_identifier);

  // Notifies that a custom event has occurred associated with a particular help
  // bubble anchor, which will in turn be propagated through the
  // ui::ElementTracker system as an EventType::kCustomEvent.
  //
  // As with the above methods, the ui::ElementIdentifier will be generated from
  // `native_identifier` and the ui::CustomElementEventType will be generated
  // from `custom_event_name`.
  HelpBubbleAnchorCustomEvent(string native_identifier,
                              string custom_event_name);

  // Notifies that a button on the help bubble anchored to `native_identifier`
  // has been pressed and the help bubble is closing as a result. The
  // `buttonIndex` parameter will be set to the (0-indexed) index of the button
  // as it was specified in the `HelpBubbleParams.buttons` used to show the help
  // bubble.
  HelpBubbleButtonPressed(string native_identifier, uint8 button_index);

  // Called when the help bubble anchored to `native_identifier` is closed,
  // either because the element it is associated with goes away, the user
  // canceled it (e.g. pressed the [x] button), or the timeout was reached.
  HelpBubbleClosed(string native_identifier, HelpBubbleClosedReason reason);
};

// Represents WebUI component that can display help bubbles. The implementing UI
// should use a HelpBubbleMixin; see README.md for detailed instructions.
interface HelpBubbleClient {
  // Shows a help bubble with parameters defined by `params` attached to
  // `target`.
  ShowHelpBubble(HelpBubbleParams params);

  // Toggles focus to the help bubble anchored to `native_identifier` or to its
  // anchor element.
  ToggleFocusForAccessibility(string native_identifier);

  // Invoked to hide the help bubble anchored to `native_identifier` if it
  // should no longer be shown.
  HideHelpBubble(string native_identifier);
};