# kilToast

**Neon, AI-feel toast notifications** - zero deps, CSS auto-injected, swipe-to-dismiss, progress bar, positions, types, ARIA-friendly.  
Solid by default, with optional `mode: 'simple'` or `mode: 'neutral'` via `kilToast.configure()`.

**Author:** Kilvish (Vasu Birla) **License:** MIT

---

## Install

```bash
npm i kiltoast
```

CDN / self-host:

```html
<script src="/node_modules/kiltoast/kiltoast.min.js"></script>
<!-- or your CDN -->
<script src="https://your.cdn/kiltoast.min.js"></script>
```

> `kiltoast.min.js` attaches a global `window.kilToast`. No build step or CSS file needed.

---

## Quick Start

```html
<script src="kiltoast.min.js"></script>
<script>
  kilToast('Hello world'); // info | center | 2s | solid (adaptive to light/dark)
</script>
```

---

## React / Next.js

### React (Vite / CRA / Next pages router)
```js
import kilToast from 'kiltoast';

export default function SaveButton() {
  return <button onClick={() => kilToast.success('Saved')}>Save</button>;
}
```

### Next.js (App Router)
```js
'use client';
import kilToast from 'kiltoast';

export default function Page() {
  return <button onClick={() => kilToast.info('Welcome')}>Show toast</button>;
}
```

If you must call it from code that can run on the server, lazy-load it on the client:

```js
useEffect(() => {
  import('kiltoast').then(({ default: kt }) => kt.info('Client only'));
}, []);
```

---

## API

### `kilToast(message, options?) -> ToastHandle`
Creates a toast.

**Options (all optional):**
- `position`: `"top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center" | "center"` (default: `"center"`)
- `type`: `"info" | "success" | "warning" | "danger"` (default: `"info"`)
- `duration`: `number` ms (default: `2000`; `0` = sticky)
- `close`: `boolean` show close button (default: `true`)
- `pauseOnHover`: `boolean` (default: `true`)
- `clickToClose`: `boolean` (default: `true`)
- `showProgress`: `boolean` (default: `true`)
- `maxStack`: `number` max visible per position (default: `6`)
- `gap`: `number` px between toasts (default: `10`)
- `offset`: `number` px from screen edge (default: `16`)
- `id`: `string` custom id you assign (used to reference this toast later)
- `replaceId`: `string` id of an existing toast to replace in-place
- `icon`: `string|HTMLElement` override icon (single char or small HTML)
- `html`: `string` set rich HTML content (if given, `message` is ignored)
- `rtl`: `boolean` right-to-left content (default: `false`)

**ToastHandle:**
- `.el`: `HTMLElement` root element
- `.dismiss()`: programmatically close the toast
- `.update({ type?, text?, html?, icon? })`: live-patch content/type/icon

**Helpers:**
```js
kilToast.success(msg, opts?)
kilToast.info(msg, opts?)
kilToast.warning(msg, opts?)
kilToast.danger(msg, opts?)

kilToast.configure(defaults) // set global defaults for future toasts
kilToast.destroyAll()        // remove every toast on the page
```

---

## Usage Examples

### 1) Basic
```html
<script>
  kilToast('Order placed - pay later');   // info, center, 2s
</script>
```

### 2) With options
```js
kilToast('Saved successfully', {
  type: 'success',
  position: 'top-right',
  duration: 3000,
  close: true
});
```

### 3) Type helpers
```js
kilToast.success('Profile updated');
kilToast.warning('Low balance', { position: 'bottom-center' });
kilToast.danger('Payment failed', { duration: 5000 });
kilToast.info('New version available');
```

### 4) Replace by id
Replace a running toast (useful for progress -> success).

```js
// Start sticky "Uploading."
kilToast('Uploading.', {
  id: 'up1',
  type: 'info',
  duration: 0,          // sticky
  showProgress: false,
  close: true
});

// Later: replace in-place
setTimeout(() => {
  kilToast('Upload complete', {
    replaceId: 'up1',
    type: 'success',
    duration: 1800
  });
}, 1200);
```

### 5) Global defaults (You can put it in your common footer or header once only)
```js
// Without mode
kilToast.configure({
  position: 'top-right',
  duration: 2500,
  gap: 12,
  offset: 18
});

// With mode: 'simple'
kilToast.configure({
  position: 'top-right',
  duration: 3000,
  gap: 12,
  offset: 18,
  mode: 'simple'  // Simple toasts
});

kilToast.configure({
  position: 'top-right',
  duration: 3000,
  gap: 12,
  offset: 18,
  mode: 'neutral'    // Glass look
});

// This toast uses the new defaults
kilToast('Defaults applied', { type: 'success' });
```

### 6) Programmatic control
```js
const t = kilToast('Syncing.', { duration: 0 }); // sticky

// Update content/type
setTimeout(() => t.update({ type: 'success', text: 'Synced!' }), 800);

// Close when you want
setTimeout(() => t.dismiss(), 1200);
```

### 7) HTML content + custom icon
```js
kilToast('', {
  html: '<b>Heads up:</b> Check <a href="/invoices">Invoices</a> for details.',
  icon: '!',
  type: 'info',
  position: 'bottom-center'
});
```

### 8) Neutral glass background (same look for all types)
```js
kilToast.configure({ mode: 'neutral' });
kilToast('Neutral info',   { type:'info' });
kilToast('Neutral warn',   { type:'warning' });
kilToast('Neutral error',  { type:'danger' });
kilToast('Neutral success',{ type:'success' });
```

---

## Accessibility

- Uses `role="status"` and `aria-live="polite"` to announce messages non-intrusively.
- Close button includes `aria-label="Close"`.
- Pause timer on hover avoids timing stress for screen-magnifier users.

---

## Gestures & Interactions

- Click to close (configurable).
- Swipe/drag to dismiss (touch and mouse).
- Pause on hover (configurable).
- Optional progress bar that counts down the remaining time.

---

## Theming / Styling

All styles are injected once and controlled via CSS variables. The defaults adapt to light and dark via `prefers-color-scheme`. Override after the script if needed:

```css
:root{
  --kil-toast-radius: 14px;
  --kil-toast-info:   #1d4ed8;
  --kil-toast-succ:   #047857;
  --kil-toast-warn:   #ffb300;           /* keep warning readable on light */
  --kil-toast-dang:   #b91c1c;

  /* Fine-tune solid palettes (optional) */
  --kil-toast-solid-info-bg:#e6efff;
  --kil-toast-solid-info-fg:#0b3b8f;
}
```

Available variables (non-exhaustive):
`--kil-toast-font`, `--kil-toast-radius`, `--kil-toast-pad`, `--kil-toast-gap`, `--kil-toast-shadow`,
`--kil-toast-info`, `--kil-toast-succ`, `--kil-toast-warn`, `--kil-toast-dang`,
`--kil-toast-solid-*-bg|fg` for info/succ/warn/dang,
`--kil-toast-glow-info|succ|warn|dang`.

---

## Tips

- **Sticky toasts:** set `duration: 0` and show a close button.
- **Queues:** control stack with `maxStack` (per position). Oldest auto-trims beyond the limit.
- **Global layout:** prefer `kilToast.configure({ position: 'top-right' })` once at app start.
- **Neutral mode:** use `kilToast.configure({ mode: 'neutral' })` for a uniform glass look.
- **Simple mode:** use `kilToast.configure({ mode: 'simple' })` for flat color toasts.

---

## Changelog

- **v1.2.0** - Adaptive light/dark solid by default, optional `mode: 'neutral'`, reduced glow/blur, emoji icons.
- **v1.1.x** - Per-type tinted background mode.
- **v1.0.x** - Initial public release.

---

## License

MIT (c) Kilvish (Vasu Birla)