# ToastManager Quick Start

This guide explains how to use `ToastManager` in TAF's front‑end codebase. New developers should read this after the shorter [ToastManager.md](ToastManager.md) reference.

## Importing

`ToastManager` lives under `FrontEnd/JsLibs2/core/ToastManager.js`. Import it along with the `TOAST_TYPES` and `TOAST_POSITIONS` enums:

```javascript
import { ToastManager, TOAST_TYPES, TOAST_POSITIONS } from '../JsLibs2/core/ToastManager.js';
```

jQuery (`$`) must be loaded globally before the module is executed because every DOM lookup uses jQuery selectors.

## Creating an Instance

```javascript
const toaster = new ToastManager({
  position: TOAST_POSITIONS.BOTTOM_RIGHT,
  maxToasts: 3,             // maximum visible toasts
  allowHtml: false          // disable HTML by default
});
```

- **position** – where the toast container appears. See `TOAST_POSITIONS` for options.
- **maxToasts** – number of toasts that can be on screen. Extra toasts are queued.
- **allowHtml** – when `true` the message string can contain basic HTML. Content is sanitized before insertion.

The manager automatically creates its container the first time you call `show()` or other APIs. If the DOM element is removed, the next call re‑creates it.

## Displaying Toasts

### `show(message, type?, duration?, allowHtml?, buttons?)`

```javascript
toaster.show('Record saved', TOAST_TYPES.SUCCESS, 5000);
```

- **message** – text shown in the toast.
- **type** – one of the values from `TOAST_TYPES` which applies colouring.
- **duration** – milliseconds before auto‑dismiss (default 3000). A progress bar animates using `requestAnimationFrame`.
- **allowHtml** – override instance default for this toast.
- **buttons** – optional array of `{ text, value, onClick }` objects shown as action buttons.

`show()` returns a toast identifier which can be passed to `dismiss(id)` or `update(id, props)` (future features).

### `confirm(options)`

Displays a small dialog with custom buttons and returns a `Promise` that resolves with the clicked button's `value`.

```javascript
const result = await toaster.confirm({
  message: 'Delete selected items?',
  buttons: [
    { text: 'Delete', value: true, class: 'btn-error' },
    { text: 'Cancel', value: false }
  ]
});
```

### `prompt(fields, options)`

Renders a form in the toast and resolves with the field values. Each field object can specify `type` (`text`, `password`, `textarea`, `select`), `name`, `label`, and validation rules.

```javascript
const data = await toaster.prompt([
  { name: 'user', label: 'Username', required: true },
  { name: 'pass', label: 'Password', type: 'password' }
]);
```

### `showCritical(options)`

Creates a full‑screen blocking dialog. This should be used for fatal or user‑fixable errors. Focus is trapped until one of the buttons resolves the promise.

## Styling and Accessibility

Toasts use daisyUI classes for consistent styling. Every modal toast has `role="dialog"` and `aria-modal="true"`. The live region announces new toasts with `aria-live="polite"`.

`showCritical()` remembers the element that was focused beforehand and restores focus when dismissed. Keyboard shortcuts (Escape to close, Enter to confirm) are handled automatically.

## Cleanup

Calling `clearAll()` removes every active toast and cleans up event handlers. Individual toasts can also be dismissed via their returned identifier.

## When Things Go Wrong

If JavaScript removes the toast container from the DOM, the next API call recreates it automatically. Ensure `$` remains available globally or the module will throw errors during initialization.