# Guidelines for AI Agents

This file explains how code‑generation tools should interact with `ToastManager` when working on the TAF ERP project.

## Use jQuery APIs

`ToastManager` is implemented entirely with jQuery. When extending or consuming it, agents must:

- Use `$(selector)` and `.find()` rather than `document.querySelector`.
- Attach events with `.on()`/`.off()`.
- Retrieve the underlying DOM element with `.get(0)` when raw methods are needed.

Any code that manipulates toast elements should follow this convention to stay consistent with the rest of the project.

## Creating Toasts

Instantiate the manager from `FrontEnd/JsLibs2/core/ToastManager.js`. Options include `position`, `maxToasts`, and `allowHtml`. Always import the enums `TOAST_TYPES` and `TOAST_POSITIONS` to avoid magic strings.

```javascript
import { ToastManager, TOAST_TYPES, TOAST_POSITIONS } from '../JsLibs2/core/ToastManager.js';
const toaster = new ToastManager({ position: TOAST_POSITIONS.TOP_RIGHT });
```

Call `show()`, `confirm()`, `prompt()` or `showCritical()` to display a toast. Each method returns a Promise or toast ID.

## Security Considerations

- HTML content is sanitized using DOMPurify when `allowHtml` is enabled. Agents should not bypass this sanitization.
- Button callbacks are executed in a safe context. Avoid referencing global variables directly from within `onClick` functions.
- The container automatically recreates itself if removed. Agents should not assume it persists between calls.

## Accessibility Rules

- Modal toasts carry `role="dialog"` and `aria-modal="true"` attributes. When adding new templates, include these attributes.
- A live region with `aria-live="polite"` announces toast messages. Ensure that any custom markup places content inside `.toast-content` so screen readers can detect updates.
- Focus should remain within prompts and critical dialogs until resolved. Keyboard shortcuts such as Escape to close and Enter to confirm are handled by `ToastManager`.

## When Extending Functionality

If implementing future features such as toast queuing or drag/swipe gestures, maintain the jQuery style and update `docs/frontend/ToastManager.md` along with unit tests under `tests/js/`.

Before committing generated code, run `./test_setup.sh` followed by `npm test` so CI results are captured in `TEST_RESULTS.md`.