# Toast

Table of Contents

###### Examples

Basic Usage
Different Positions
Timeouts
Action and Close Buttons

###### JavaScript Reference

Constructor
Static Methods
Requirements
Attributes
Properties
Methods
Events
ToastContainer

### Description

The Toast component provides a way to display short-lived notifications to users. Toasts appear in a corner of the screen, can be configured with different positions, and can optionally include action and close buttons. Toasts can be set to automatically close after a specified timeout or remain until manually dismissed.

### Basic Usage

    <button id="example1">Open Toast</button>
    <script type="module">
      import Toast from '/kempo/components/Toast.js';
      document.getElementById('example1').addEventListener('click', () => {
        Toast.create("Hello World");
      });
    </script>

### Different Positions

Toasts can be positioned in different corners of the screen using the `position` property.

### Timeouts

Toasts can automatically close after a specified timeout (in milliseconds). The default timeout when using `Toast.create` is `5000` (ms), or 5 seconds.

    <button id="example3-1">Open 1 Second Timeout Toast</button>
    <button id="example3-3">Open 3 Second Timeout Toast</button>
    <button id="example3-10">Open 10 Second Timeout Toast</button>
    <script type="module">
      import Toast from '/kempo/components/Toast.js';
      document.getElementById('example3-1').addEventListener('click', () => {
        Toast.create("I will timeout in 1 second", {
          timeout: 1000
        });
      });
      document.getElementById('example3-3').addEventListener('click', () => {
        Toast.create("I will timeout in 3 second", {
          timeout: 3000
        });
      });
      document.getElementById('example3-10').addEventListener('click', () => {
        Toast.create("I will timeout in 10 second", {
          timeout: 10000
        });
      });
    </script>

### Action and Close Buttons

Toasts can have action and close buttons that trigger callbacks when clicked.

    <button id="example4-action">Open Toast with Action</button>
    <button id="example4-close">Open Toast with Close Button</button>
    <button id="example4-action-close">Open Toast with Action and Close Button</button>
    <script type="module">
      import Toast from '/kempo/components/Toast.js';
      document.getElementById('example4-action').addEventListener('click', () => {
        Toast.create("Hello World", {
          timeout: 0,
          action: 'Click Me',
          actionCallback: () => {
            Toast.create("You clicked the action");
          }
        });
      });
      document.getElementById('example4-close').addEventListener('click', () => {
        Toast.create("Hello World", {
          timeout: 0,
          close: '<k-icon name="close"></div>',
          closeCallback: () => {
            Toast.create("You closed the toast");
          }
        });
      });
      document.getElementById('example4-action-close').addEventListener('click', () => {
        Toast.create("Hello World", {
          timeout: 0,
          action: 'Click Me',
          actionCallback: () => {
            Toast.create("You clicked the action");
            return false; // return false to prevent closing
          },
          close: '<k-icon name="close"></div>',
          closeCallback: () => {
            Toast.create("You closed the toast");
          }
        });
      });
    </script>

### Success, Warning and Error

Toasts can be created as a success, warning or error message.

    <button id="example5-success">Success Toast</button>
    <button id="example5-warning">Warning Toast</button>
    <button id="example5-error">Error Toast</button>
    <script type="module">
      import Toast from '/kempo/components/Toast.js';
      document.getElementById('example5-success').addEventListener('click', () => {
        Toast.success("It Worked!");
      });
      document.getElementById('example5-warning').addEventListener('click', () => {
        Toast.warning("Be Careful");
      });
      document.getElementById('example5-error').addEventListener('click', () => {
        Toast.error("That's a very bad idea");
      });
    </script>

## JavaScript Reference

### Constructor

###### Extends Component

##### `new Toast()`
`new Toast(object options)`

#### Parameters

##### `options: object`

An object with the following optional properties:

- `actionCallback: function` - Function to call when the action button is clicked. If this function returns `false`, the toast will not close.
- `actionHtml: string` - HTML content for the action button.
- `closeCallback: function` - Function to call when the toast is closed.
- `closeHtml: string` - HTML content for the close button.
- `timeout: number` - Time in milliseconds before the toast automatically closes. Default is 0 (no auto-close).

### Static Methods

##### `Toast.create(message, options): Toast`

Creates and displays a new toast with the specified message and options. Returns the created Toast instance.

Options include:

- `position: string` - Position of the toast on the screen. Default is 'auto', which uses 'bottom center' on mobile and 'top right' on desktop. Valid positions are: 'top left', 'top center', 'top right', 'bottom left', 'bottom center', 'bottom right'.
- `removeOnClose: boolean` - If true, the toast element will be removed from the DOM when closed. Default is true.
- `timeout: number` - Time in milliseconds before the toast automatically closes. Default is 5000ms (5 seconds).
- `action: string | HTMLElement` - Text or HTML element to use for the action button.
- `actionCallback: function` - Function to call when the action button is clicked. If this function returns `false`, the toast will not close.
- `close: string | HTMLElement` - Text or HTML element to use for the close button.
- `closeCallback: function` - Function to call when the toast is closed.
- `icon: string | HTMLElement` - Text or HTML element to use as an icon in the toast.

##### `Toast.success(message, options): Toast`

Creates and displays a success toast with a check icon and applies a success background style. Accepts the same options as `Toast.create()`.

##### `Toast.warning(message, options): Toast`

Creates and displays a warning toast with a warning icon and applies a warning background style. Accepts the same options as `Toast.create()`.

##### `Toast.error(message, options): Toast`

Creates and displays an error toast with an error icon and applies a danger background style. Accepts the same options as `Toast.create()`.

### Requirements

- Component

### Attributes

##### `action-html: string`

HTML content for the action button.

##### `close-html: string`

HTML content for the close button.

##### `timeout: number`

Time in milliseconds before the toast automatically closes. Default is 0 (no auto-close).

##### `opened: boolean`

Whether the toast is currently open. Default is false.

### Properties

##### `actionCallback: function`

Function to call when the action button is clicked.

##### `closeCallback: function`

Function to call when the toast is closed.

##### `actionHtml: string`

HTML content for the action button.

##### `closeHtml: string`

HTML content for the close button.

##### `timeout: number`

Time in milliseconds before the toast automatically closes.

##### `opened: boolean`

Whether the toast is currently open.

### Methods

##### `open(): void`

Opens the toast. If a timeout is specified, this starts the timer for automatic closing.

##### `close(): void`

Closes the toast and calls the `closeCallback` if provided.

### Events

##### `open`

Fired when the toast is opened.

##### `close`

Fired when the toast is closed.

##### `openchange`

Fired when the toast open state changes (both when opening and closing).

### ToastContainer

The `ToastContainer` is an internal component used to position and display toasts. It is automatically created when `Toast.create()` is called, but can also be used directly.

##### `new ToastContainer(position)`

Creates a new toast container at the specified position.

##### `position: string`

The position of the container on the screen. Valid values are: 'top left', 'top center', 'top right', 'bottom left', 'bottom center', 'bottom right'.