@knighttower/toast/README.md

A dead simple toast library

# x-toast.js Library Documentation

## Introduction

`x-toast.js` is a lightweight toast notification library for JavaScript that allows you to display customizable toast messages in various styles (info, success, warning, error). The library supports custom configuration, animations, and callbacks.

---

## CDN Integration

To use `x-toast.js`, include the following links in your project:

### JS and CSS via Bundle:

```html
<script src="https://cdn.jsdelivr.net/npm/knighttower@latest/packages/toast/dist/browser/bundle.js"></script>
```

### Individual Links:

```html
<script src="https://cdn.jsdelivr.net/npm/knighttower@latest/packages/toast/dist/browser/toast.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/knighttower@latest/packages/toast/dist/browser/style.css">
```

---

## ES Module / Import Usage (with Bundlers)

If you're using a bundler like Vite, Webpack, or Rollup, you can import `x-toast.js` as an ES module.

### Install via npm:

```bash
npm install @knighttower/toast
```

Or from the monorepo:

```bash
npm install knighttower
```

### Import and Usage:

```js
import toast from '@knighttower/toast';

toast.info('This is an info message.');
toast.success('This is a success message.');
toast.warning('This is a warning message.');
toast.error('This is an error message.');
```  

```css
@import '@knighttower/toast/dist/browser/style.css';
```

Optional: Assign to global scope:

```js
window.$toast = toast;
```

---

## Basic Usage

```js
$toast.info('This is an info message.');
$toast.success('This is a success message.');
$toast.warning('This is a warning message.');
$toast.error('This is an error message.');
```

---

## Methods

### 1. `$toast.info(message, duration)`

* Displays an info toast.
* `message` *(String)*: The message text.
* `duration` *(Integer, optional)*: Display time in milliseconds.

### 2. `$toast.success(message, duration)`

* Displays a success toast.

### 3. `$toast.warning(message, duration)`

* Displays a warning toast.

### 4. `$toast.error(message, duration)`

* Displays an error toast.

### 5. `$toast.config(options)`

* Set global configuration options.

**Options:**

```js
$toast.config({
  classname: 'custom-class',
  transition: 'fade',
  position: 'top-left',
  autoClose: true,
  duration: 5000,
  progressBar: true,
  insertBefore: false,
  onShow: function(type) { console.log(`${type} toast shown`); },
  onHide: function(type) { console.log(`${type} toast hidden`); },
});
```

---

## Configurations

| Option         | Type     | Description                                                            | Default Value        |
| -------------- | -------- | ---------------------------------------------------------------------- | -------------------- |
| `classname`    | String   | Additional class name for the toast container.                         | `'x'`                |
| `transition`   | String   | CSS transition name (`fade`, `slide-left-right`, etc.).                | `'slide-left-right'` |
| `position`     | String   | Toast position (`top-right`, `top-left`, etc.).                        | `'top-right'`        |
| `duration`     | Integer  | Duration in milliseconds. `0` = auto duration based on message length. | `3000`               |
| `autoClose`    | Boolean  | Enables/disables automatic closing of the toast message.               | `true`               |
| `progressBar`  | Boolean  | Shows/hides the progress bar. Enabled only if `autoClose` is `true`.   | `true`               |
| `insertBefore` | Boolean  | Adds the new toast before/after existing toasts.                       | `true`               |
| `onShow`       | Function | Callback function executed when the toast appears.                     | `function() {}`      |
| `onHide`       | Function | Callback function executed when the toast disappears.                  | `function() {}`      |

---

## Transitions

| Transition Name    | Description                |
| ------------------ | -------------------------- |
| `fade`             | Fades in/out the toast.    |
| `slide-left-right` | Slides in from the right.  |
| `slide-right-left` | Slides in from the left.   |
| `slide-up-down`    | Slides down from the top.  |
| `slide-down-up`    | Slides up from the bottom. |

---

## Positions

| Position Name  | Location in Viewport |
| -------------- | -------------------- |
| `top-right`    | Top-right corner     |
| `top-left`     | Top-left corner      |
| `bottom-right` | Bottom-right corner  |
| `bottom-left`  | Bottom-left corner   |

---

## Examples

### 1. Simple Notification

```js
$toast.success('Data saved successfully!', 4000);
```

### 2. Custom Configuration

```js
$toast.config({
  position: 'bottom-right',
  transition: 'slide-up-down',
  duration: 5000,
  progressBar: false,
});
$toast.info('This is a custom info message.');
```

### 3. Callback Example

```js
$toast.config({
  onShow: (type) => console.log(`Toast type: ${type} displayed`),
  onHide: (type) => console.log(`Toast type: ${type} hidden`)
});
$toast.warning('Warning with callbacks!');
```

---

## CSS Customization

To customize transitions, follow the naming convention:

* `{transition-name}--init`
* `{transition-name}--show`
* `{transition-name}--hide`

Example:

```css
/* Custom fade transition */
.x-toast.fade--init { opacity: 0; }
.x-toast.fade--show { opacity: 1; transition: opacity 0.5s ease-in; }
.x-toast.fade--hide { opacity: 0; transition: opacity 0.5s ease-out; }
```

---