# Toast UI
The toast system allows features to surface a message and an optional action
for users to take. These are short notifications that serve as confirmation of a
successful user action or provide contextual information about a Chrome
initiated action. Each toast must have an icon and a body text; feature teams
can optionally add an action or close button to toasts. Feature teams that want
to introduce a toast will need to introduce a new value to the toast id enum and
create a toast specification that will be registered with the toast registry.

## Getting Started
### 1. Add a new entry to the [ToastId enum](api/toast_id.h)
Each toast should have a unique `ToastId` which is used to identify the
toast and retrieve its corresponding specification.

### 2. Register your ToastSpecification in [ToastService::RegisterToasts()](toast_service.cc)
The toast specification allows features to declare what components they want
the toast to have. All toasts must have an icon and body text when shown, but
have the option to add other components such as an action button, close button,
three dot menu, or set the toast to be persistent.

Note: When registering your ToastSpecification, you can use strings with a
placeholder. However, you must remember to pass in any values you want to use
to replace the placeholders with in `ToastParams` when you trigger your toast.

#### Registering a Default Toast
```
void ToastService::RegisterToast(BrowserWindowInterface* interface) {
  ...
  toast_registry_->RegisterToast(
    ToastId,
    ToastSpecification::Builder(vector_icon, string_id)
        .Build());
}
```

#### Registering a Toast with a Close Button
```
void ToastService::RegisterToast(BrowserWindowInterface* interface) {
  ...
  toast_registry_->RegisterToast(
    ToastId,
    ToastSpecification::Builder(vector_icon, string_id)
        .AddCloseButton()
        .Build());
}
```

#### Registering a Toast with an Action Button
```
void ToastService::RegisterToast(BrowserWindowInterface* interface) {
  ...
  toast_registry_->RegisterToast(
    ToastId,
    ToastSpecification::Builder(vector_icon, string_id)
        .AddActionButton(button_string_id, button_closure)
        .AddCloseButton()
        .Build());
}
```

Note: there are a couple restrictions when declaring a toast specification with
an action button:
1. A toast with an action button must also have a "X" close button.
2. A toast with an action button cannot have a three dot menu.

#### Registering a Toast with a Menu
```
void ToastService::RegisterToast(BrowserWindowInterface* interface) {
  ...
  toast_registry_->RegisterToast(
    ToastId,
    ToastSpecification::Builder(vector_icon, string_id)
        .AddMenu()
        .Build());
}
```
Even though you have registered the toast with the ToastService, when you
trigger the toast, you must remember to pass in a non-null menu model to
populate the menu in `ToastParams` when you trigger your toast.

Also note that toasts with a menu cannot have a "X" close button. If this
behavior is needed, please consult with UX on how to design this in a way
that supports both.

#### Registering a Toast that Persists on Navigation
By default, tab-scoped toasts will disappear when the user navigates to a new
page or switches tabs.

Toasts that persist on navigation are still tab-scoped, meaning they will
disappear if the user switches to a different tab, but they will survive
navigation events (like form submissions) within the same tab. This is
different from global toasts, which are not tied to any specific tab and will
persist across both tab switches and navigations until they are explicitly
closed or time out.

```
void ToastService::RegisterToast(BrowserWindowInterface* interface) {
  ...
  toast_registry_->RegisterToast(
    ToastId,
    ToastSpecification::Builder(vector_icon, string_id)
        .SetPersistOnNavigation()
        .Build());
}
```

### 3. Trigger your Toast
When you want to trigger your toast to show, you will need to retrieve the
[ToastController](toast_controller.h) through
[BrowserWindowFeatures](../browser_window/public/browser_window_features.h) and
call `ToastController::MaybeShowToast(ToastParams params)`.

Note: the ToastController can be null for certain browser types so you must check
if the controller exists before attempting to trigger the toast.

#### Triggering a Toast Without Needing to Replace Placeholder Strings
```
ToastController* const toast_controller = browser_window_features->toast_controller();
if (toast_controller) {
  toast_controller->MaybeShowToast(ToastParams(ToastId));
}
```

#### Triggering a Toast and Replacing Placeholder Strings
```
ToastController* const toast_controller = browser_window_features->toast_controller();
if (toast_controller) {
  ToastParams params = ToastParams(ToastId);
  params.body_string_replacement_params = {string_1, string_2};
  params.action_button_string_replacement_params = {string_3};
  toast_controller->MaybeShowToast(std::move(params));
}
```

#### Triggering a Toast with a Menu
```
ToastController* const toast_controller = browser_window_features->toast_controller();
if (toast_controller) {
  std::unique_ptr<MyCustomMenuModel> menu_model = ...
  ToastParams params = ToastParams(ToastId);
  params.menu_model = std::move(menu_model);
  toast_controller->MaybeShowToast(std::move(params));
}
```

#### Triggering a Toast with a Callback on Close
When the toast gets destroyed, the callback will be called.
```
ToastController* const toast_controller = browser_window_features->toast_controller();
if (toast_controller) {
  ToastParams params = ToastParams(ToastId);
  params.toast_close_callback = base::ScopedClosureRunner(
      base::BindOnce(&MyClass::OnToastClosed,
                     weak_factory_.GetWeakPtr(), extra_variable_1));
  toast_controller->MaybeShowToast(ToastParams(std::move(params)));
}
```

Note: even though you have triggered your toast, there is a chance that users
might not see the toast because another toast immediately triggered after your
toast, thus preempting your toast from being seen by users.