# Toast Notifications

Toast notifications provide a way to display temporary, non-blocking notifications to users. They are especially useful for providing feedback after user actions like form submissions, API calls, or system events.

## Table of Contents

* [Overview](#overview)
* [Toast Positions](#toast-positions)
* [Usage with Re-Frame](#usage-with-re-frame)
* [Toast Types](#toast-types)
* [Customizing Toasts](#customizing-toasts)
* [Clearing Toasts](#clearing-toasts)
* [Reference](#reference)

## Overview

The toast system in this application uses [re-frame](https://day8.github.io/re-frame/) for state management and [daisyUI](https://daisyui.com/components/toast/) for styling. Toasts can be displayed at different positions on the screen and with different statuses (info, success, warning, error).

The main components of the toast system are:

* `toast-container`: A component that displays all active toasts
* Re-frame events for managing toasts
* Re-frame subscriptions for accessing toast data

## Toast Positions

Toasts can be positioned in 9 different locations on the screen:

```clojure
#{[:top :start] [:top :center] [:top :end]
  [:middle :start] [:middle :center] [:middle :end]
  [:bottom :start] [:bottom :center] [:bottom :end]}
```

The default position is `[:bottom :center]`.

## Usage with Re-Frame

To display a toast notification, dispatch one of the toast events with the appropriate data:

```clojure
;; Basic info toast
(rf/dispatch [:toast/info {:message "Operation completed successfully"}])

;; Success toast with custom position
(rf/dispatch [:toast/success 
              {:message "Item saved successfully" 
               :vertical :top 
               :horizontal :center}])

;; Warning toast
(rf/dispatch [:toast/warning {:message "Please check your input"}])

;; Error toast (stays longer by default)
(rf/dispatch [:toast/error {:message "Failed to connect to server"}])
```

### Toast Data Structure

When dispatching a toast event, you can provide the following parameters:

| Parameter     | Type        | Default                | Description                                       |
| ------------- | ----------- | ---------------------- | ------------------------------------------------- |
| `:message`    | String      | (required)             | The message to display in the toast               |
| `:vertical`   | Keyword     | `:bottom`              | Vertical position (`:top`, `:middle`, `:bottom`)  |
| `:horizontal` | Keyword     | `:center`              | Horizontal position (`:start`, `:center`, `:end`) |
| `:timeout`    | Number (ms) | 5000 (7000 for errors) | Time in milliseconds before toast auto-dismisses  |
| `:id`         | String/UUID | (auto-generated)       | Unique identifier for the toast                   |

## Toast Types

There are four built-in toast types, each with its own color styling:

1. **Info** (`:toast/info`): For general information and neutral messages
2. **Success** (`:toast/success`): For confirming successful operations
3. **Warning** (`:toast/warning`): For non-critical warnings
4. **Error** (`:toast/error`): For error messages (stays visible longer)

## Customizing Toasts

### Custom Timeout

You can customize how long a toast appears by setting the `:timeout` parameter:

```clojure
(rf/dispatch [:toast/info 
              {:message "This will disappear quickly" 
               :timeout 2000}])
```

## Clearing Toasts

### Remove a Single Toast

To remove a single toast programmatically, you need its ID and position:

```clojure
(rf/dispatch [:toast/remove {:id "toast-id" :position [:top :center]}])
```

### Clear All Toasts at a Position

```clojure
(rf/dispatch [:toast/clear-position [:top :center]])
```

### Clear All Toasts

```clojure
(rf/dispatch [:toast/clear-all])
```

## Setting Up the Toast Container

To display toasts in your application, you need to include the toast container component in your app's root component:

```clojure
(ns your-app.core
  (:require
   [re-frame.core :as rf]
   [saas.ui.toasts :as toasts]
   [uix.core :refer [$ defui]]))

(defui main-app []
  ($ :<>
     ;; Your app content
     ($ your-app-component)
     
     ;; Toast container (should be at the root level)
     ($ toasts/toast-container)))
```

## Reference

### Toast Examples

For visual examples of different toast layouts and positions, refer to the toast scenes in the Portfolio:

* [Toast Scenes](https://github.com/shipclojure/shipclojure/blob/main/portfolio/src/saas/components/toast_scenes.cljs)

The portfolio includes examples of:

* Basic toast with alert
* Toasts in all 9 positions
* Interactive examples with buttons that trigger real toasts

### Implementation Details

The toast system is implemented in:

* [saas.ui.toasts](https://github.com/shipclojure/shipclojure/blob/main/src/cljs/saas/ui/toasts.cljs): Contains the re-frame events, subscriptions, and UI components
* [saas.common.ui.core](https://github.com/shipclojure/shipclojure/blob/main/src/cljc/saas/common/ui/core.cljc): Contains the base toast component


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://shipclojure.gitbook.io/shipclojure-docs/frontend/toasts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.