hcg-toast 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HTML Code Generator (https://www.html-code-generator.com/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# hcg-toast
+
+A lightweight, zero-dependency JavaScript toast / notification library. Show success, error, warning, and info messages with auto-dismiss, sticky toasts, six screen positions, stack limits, pause on hover, optional progress bars, and custom icons.
+
+![hcg-toast — JavaScript toast notifications with success, error, info, and warning types](https://raw.githubusercontent.com/html-code-generator/hcg-toast/main/toast-notification.png)
+
+- Zero dependencies, ~6 KB unminified
+- UMD build - works with `<script>` tags, CommonJS, and bundlers
+- Global API: `toast()` with shorthand helpers and `toast.create()` for custom instances
+- Custom icons via `icon`, `iconHtml`, or hide with `icon: false`
+- Accessible: `role="alert"` / `role="status"` with `aria-live="off"` on non-errors (avoids browser freezes during rapid bursts); errors use `aria-live="assertive"`
+- TypeScript definitions included
+
+## Links
+
+- **Documentation & live demo:** [html-code-generator.com/javascript/toast-notification](https://www.html-code-generator.com/javascript/toast-notification)
+- **npm:** [npmjs.com/package/hcg-toast](https://www.npmjs.com/package/hcg-toast)
+- **GitHub:** [github.com/html-code-generator/hcg-toast](https://github.com/html-code-generator/hcg-toast)
+
+## Demo
+
+Try the [live demo and full documentation](https://www.html-code-generator.com/javascript/toast-notification), or open `index.html` from the GitHub repo over a local server for a working example.
+
+```bash
+npx serve .
+```
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install hcg-toast
+```
+
+Or download `hcg-toast.js` and `hcg-toast.css` and include them on your page:
+
+```html
+<link rel="stylesheet" href="hcg-toast.css">
+<script src="hcg-toast.js"></script>
+```
+
+In a module / Node environment:
+
+```js
+require('hcg-toast/hcg-toast.css');
+const toast = require('hcg-toast');
+```
+
+Or with ESM:
+
+```js
+import toast from 'hcg-toast';
+import 'hcg-toast/hcg-toast.css';
+```
+
+## Usage
+
+### Singleton (default)
+
+```html
+<link rel="stylesheet" href="hcg-toast.css">
+<script src="hcg-toast.js"></script>
+<script>
+    toast.success('Changes saved!');
+    toast.error('Upload failed', { title: 'Error', duration: 6000 });
+    toast.dismiss(id);
+    toast.dismissAll();
+    toast.configure({ position: 'bottom-right', maxToasts: 5 });
+</script>
+```
+
+### Typed helpers
+
+Shorthand methods set the toast type for you so you do not need to pass `type` on every call. Each helper uses the matching icon and accent color.
+
+```js
+toast.success('Profile updated.');
+toast.error('Could not save changes.');
+toast.warning('You have unsaved edits.');
+toast.info('Sync complete.');
+
+// equivalent to toast(message, { type: 'success' })
+toast('Saved!', { type: 'success', title: 'Done' });
+```
+
+Each call to `show()` (or a typed helper) returns a numeric toast `id` you can pass to `dismiss(id)`.
+
+### Custom instance
+
+```js
+const bottomToast = toast.create({
+    position: 'bottom-center',
+    maxToasts: 3,
+});
+
+bottomToast.info('Processing…', { duration: 0, closable: true });
+bottomToast.dismissAll();
+bottomToast.destroy();
+```
+
+### Custom icons
+
+By default each type shows a built-in icon (info, success, warning, error). Override per toast or set a default on the instance:
+
+```js
+// Emoji or text icon
+toast.success('Backup complete.', { icon: '💾' });
+
+// SVG or HTML icon (trusted markup only)
+toast.info('Syncing files…', {
+  iconHtml: '<svg viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M10 3a7 7 0 100 14A7 7 0 0010 3z"/></svg>'
+});
+
+// Hide the icon column
+toast('Plain message.', { icon: false });
+
+// Default icon for all toasts on an instance
+const stars = toast.create({ icon: '⭐' });
+stars.info('You have a new message.');
+```
+
+`iconHtml` takes precedence over `icon` when both are set. Only pass trusted HTML to `iconHtml`.
+
+## Options
+
+| Option           | Type                                      | Default       | Description                                              |
+| ---------------- | ----------------------------------------- | ------------- | -------------------------------------------------------- |
+| `message`        | `string`                                  | required      | Main body text                                           |
+| `title`          | `string`                                  | -             | Optional heading above the message                       |
+| `type`           | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'`  | Toast variant (icon and accent color)                    |
+| `duration`       | `number`                                  | `4000`        | Auto-dismiss delay in ms; `0` = sticky until dismissed   |
+| `closable`       | `boolean`                                 | `true`        | Show a close button                                      |
+| `pauseOnHover`   | `boolean`                                 | `true`        | Pause the auto-dismiss timer while hovered               |
+| `position`       | see below                                 | `'top-right'` | Screen position for this instance's container            |
+| `maxToasts`      | `number`                                  | `5`           | Max visible toasts; oldest dismissed when exceeded (per call or instance default) |
+| `showProgress`   | `boolean`                                 | `true`        | Show a progress bar when `duration > 0`                  |
+| `icon`           | `string \| false`                         | type default  | Custom icon text or emoji; `false` hides the icon        |
+| `iconHtml`       | `string`                                  | -             | Custom icon HTML (e.g. SVG); overrides `icon`            |
+| `ariaLive`       | `'off' \| 'polite' \| 'assertive'`        | `'off'`       | Live region on each toast; errors default to `'assertive'` when unset |
+| `onShow`         | `(toast) => void`                         | -             | Called after the enter class is applied (animation start) |
+| `onDismiss`      | `(toast, reason) => void`                 | -             | Called when removed; `reason`: `'timeout'`, `'close'`, `'api'` |
+
+**Positions:** `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`
+
+## Instance methods
+
+| Method          | Returns        | Description                                           |
+| --------------- | -------------- | ----------------------------------------------------- |
+| `show(msg, opts)` | `number \| null` | Show a toast; returns id                             |
+| `success(msg, opts)` | `number \| null` | Shorthand for `type: 'success'`                   |
+| `error(msg, opts)` | `number \| null` | Shorthand for `type: 'error'`                     |
+| `warning(msg, opts)` | `number \| null` | Shorthand for `type: 'warning'`                 |
+| `info(msg, opts)` | `number \| null` | Shorthand for `type: 'info'`                       |
+| `dismiss(id)`   | `void`         | Remove one toast with exit animation                  |
+| `dismissAll()`  | `void`         | Remove all toasts immediately                       |
+| `configure(opts)` | `void`       | Merge default options for this instance               |
+| `destroy()`     | `void`         | Dismiss all, remove container, detach instance        |
+
+The default singleton exposes the same methods on `toast` itself, plus `toast.create()`. Calling `toast.destroy()` removes the default instance so the next call recreates it.
+
+## Styling
+
+All default styles live in `hcg-toast.css`, using plain single-class selectors and CSS custom properties on `.hcg-toast-container`. Edit that file directly, or override any rule from your own stylesheet (loaded after it). Available class hooks:
+
+- `.hcg-toast-container` - fixed-position stack host (position modifiers: `--top-right`, `--bottom-center`, etc.)
+- `.hcg-toast-item` - individual toast (type modifiers: `--info`, `--success`, `--warning`, `--error`)
+- `.hcg-toast-icon`, `.hcg-toast-body`, `.hcg-toast-title`, `.hcg-toast-message`
+- `.hcg-toast-close` - dismiss button
+- `.hcg-toast-progress-track` / `.hcg-toast-progress` - auto-dismiss track and shrinking bar (shown when `duration > 0` and `showProgress: true`)
+- `.hcg-toast-item--enter` / `.hcg-toast-item--exit` - animation states
+
+```css
+.hcg-toast-container {
+    --hcg-toast-radius: 8px;
+    --hcg-toast-success-accent: #10b981;
+}
+```
+
+## Multiple instances
+
+Create as many toast containers as you need. Each call to `toast.create()` returns a fully independent instance with its own position, defaults, stack, and API. The shared `hcg-toast.css` styles them all, so you only link it once.
+
+```js
+const topRight = toast.create({ position: 'top-right' });
+const bottomCenter = toast.create({ position: 'bottom-center', maxToasts: 2 });
+
+topRight.success('Saved!');
+bottomCenter.info('Syncing…', { duration: 0 });
+
+bottomCenter.destroy();
+```
+
+Notes when running several instances:
+
+- Each instance injects its own `.hcg-toast-container` when first used.
+- `toast.configure()` only affects the default singleton, not custom instances.
+- Call each instance's `destroy()` when removing it permanently.
+
+## Browser support
+
+Works in all modern browsers that support CSS transitions and `requestAnimationFrame` (Chrome, Firefox, Safari, Edge). Respects `prefers-reduced-motion: reduce` by disabling enter/exit and progress animations (the progress track stays visible for timed toasts).
+
+## License
+
+MIT - HTML Code Generator (https://www.html-code-generator.com/)

package/hcg-toast.css

@@ -0,0 +1,254 @@
+/*!
+ * hcg-toast v1.0.0
+ * Default styles for the toast / notification library.
+ * Edit freely or override these rules from your own stylesheet.
+ * @see https://www.html-code-generator.com/javascript/toast-notification
+ * @license MIT
+ */
+
+.hcg-toast-container {
+    --hcg-toast-gap: 10px;
+    --hcg-toast-width: min(360px, calc(100vw - 32px));
+    --hcg-toast-radius: 12px;
+    --hcg-toast-shadow: 0 10px 30px rgba(15, 23, 42, 0.12);
+    --hcg-toast-z: 9999;
+    --hcg-toast-bg: #ffffff;
+    --hcg-toast-border: #e5e7eb;
+    --hcg-toast-text: #1f2937;
+    --hcg-toast-title: #111827;
+    --hcg-toast-muted: #6b7280;
+    --hcg-toast-info-accent: #6366f1;
+    --hcg-toast-success-accent: #059669;
+    --hcg-toast-warning-accent: #d97706;
+    --hcg-toast-error-accent: #dc2626;
+
+    position: fixed;
+    z-index: var(--hcg-toast-z);
+    display: flex;
+    flex-direction: column;
+    gap: var(--hcg-toast-gap);
+    width: var(--hcg-toast-width);
+    pointer-events: none;
+}
+
+.hcg-toast-container--top-left {
+    top: 20px;
+    left: 20px;
+    align-items: flex-start;
+}
+
+.hcg-toast-container--top-center {
+    top: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+    align-items: center;
+}
+
+.hcg-toast-container--top-right {
+    top: 20px;
+    right: 20px;
+    align-items: flex-end;
+}
+
+.hcg-toast-container--bottom-left {
+    bottom: 20px;
+    left: 20px;
+    flex-direction: column-reverse;
+    align-items: flex-start;
+}
+
+.hcg-toast-container--bottom-center {
+    bottom: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+    flex-direction: column-reverse;
+    align-items: center;
+}
+
+.hcg-toast-container--bottom-right {
+    bottom: 20px;
+    right: 20px;
+    flex-direction: column-reverse;
+    align-items: flex-end;
+}
+
+.hcg-toast-item {
+    position: relative;
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+    width: 100%;
+    padding: 14px 16px 16px;
+    background: var(--hcg-toast-bg);
+    border: 1px solid var(--hcg-toast-border);
+    border-radius: var(--hcg-toast-radius);
+    box-shadow: var(--hcg-toast-shadow);
+    color: var(--hcg-toast-text);
+    overflow: hidden;
+    pointer-events: auto;
+    opacity: 0;
+    transform: translateY(-8px) scale(0.98);
+    transition: opacity 0.25s ease, transform 0.25s ease;
+}
+
+.hcg-toast-container--bottom-left .hcg-toast-item,
+.hcg-toast-container--bottom-center .hcg-toast-item,
+.hcg-toast-container--bottom-right .hcg-toast-item {
+    transform: translateY(8px) scale(0.98);
+}
+
+.hcg-toast-item--enter {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+}
+
+.hcg-toast-item--exit {
+    opacity: 0;
+    transform: translateY(-8px) scale(0.98);
+}
+
+.hcg-toast-container--bottom-left .hcg-toast-item--exit,
+.hcg-toast-container--bottom-center .hcg-toast-item--exit,
+.hcg-toast-container--bottom-right .hcg-toast-item--exit {
+    transform: translateY(8px) scale(0.98);
+}
+
+.hcg-toast-icon {
+    flex-shrink: 0;
+    width: 22px;
+    height: 22px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 999px;
+    font-size: 0.78rem;
+    font-weight: 700;
+    line-height: 1;
+    margin-top: 1px;
+}
+
+.hcg-toast-item--info .hcg-toast-icon {
+    color: var(--hcg-toast-info-accent);
+    background: #eef2ff;
+}
+
+.hcg-toast-item--success .hcg-toast-icon {
+    color: var(--hcg-toast-success-accent);
+    background: #ecfdf5;
+}
+
+.hcg-toast-item--warning .hcg-toast-icon {
+    color: var(--hcg-toast-warning-accent);
+    background: #fffbeb;
+}
+
+.hcg-toast-item--error .hcg-toast-icon {
+    color: var(--hcg-toast-error-accent);
+    background: #fef2f2;
+}
+
+.hcg-toast-icon svg {
+    display: block;
+    width: 14px;
+    height: 14px;
+}
+
+.hcg-toast-body {
+    flex: 1;
+    min-width: 0;
+}
+
+.hcg-toast-title {
+    font-size: 0.88rem;
+    font-weight: 700;
+    color: var(--hcg-toast-title);
+    margin-bottom: 2px;
+    line-height: 1.35;
+}
+
+.hcg-toast-message {
+    font-size: 0.86rem;
+    line-height: 1.55;
+    color: var(--hcg-toast-text);
+    word-wrap: break-word;
+}
+
+.hcg-toast-close {
+    flex-shrink: 0;
+    background: none;
+    border: none;
+    color: var(--hcg-toast-muted);
+    cursor: pointer;
+    font-size: 1.15rem;
+    line-height: 1;
+    padding: 2px 4px;
+    border-radius: 6px;
+    transition: color 0.15s, background 0.15s;
+}
+
+.hcg-toast-close:hover {
+    color: #374151;
+    background: #f3f4f6;
+}
+
+.hcg-toast-close:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 3px #c7d2fe;
+}
+
+.hcg-toast-progress-track {
+    position: absolute;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    z-index: 2;
+    height: 5px;
+    background: rgba(15, 23, 42, 0.08);
+    overflow: hidden;
+    pointer-events: none;
+    border-radius: 0 0 calc(var(--hcg-toast-radius) - 1px) calc(var(--hcg-toast-radius) - 1px);
+}
+
+.hcg-toast-progress {
+    height: 100%;
+    width: 100%;
+    transform-origin: left center;
+    pointer-events: none;
+}
+
+.hcg-toast-item--info .hcg-toast-progress {
+    background: var(--hcg-toast-info-accent);
+}
+
+.hcg-toast-item--success .hcg-toast-progress {
+    background: var(--hcg-toast-success-accent);
+}
+
+.hcg-toast-item--warning .hcg-toast-progress {
+    background: var(--hcg-toast-warning-accent);
+}
+
+.hcg-toast-item--error .hcg-toast-progress {
+    background: var(--hcg-toast-error-accent);
+}
+
+@keyframes hcg-toast-progress-shrink {
+    from { transform: scaleX(1); }
+    to { transform: scaleX(0); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .hcg-toast-item {
+        transition: none;
+        transform: none;
+    }
+
+    .hcg-toast-item--enter,
+    .hcg-toast-item--exit {
+        transform: none;
+    }
+
+    .hcg-toast-progress {
+        animation: none;
+    }
+}

package/hcg-toast.d.ts

@@ -0,0 +1,81 @@
+export type HcgToastType = 'info' | 'success' | 'warning' | 'error';
+
+export type HcgToastPosition =
+    | 'top-left'
+    | 'top-center'
+    | 'top-right'
+    | 'bottom-left'
+    | 'bottom-center'
+    | 'bottom-right';
+
+export type HcgToastDismissReason = 'timeout' | 'close' | 'api';
+
+export type HcgToastAriaLive = 'off' | 'polite' | 'assertive';
+
+export interface HcgToastShown {
+    id: number;
+    message: string;
+    title?: string;
+    type: HcgToastType;
+    duration: number;
+    closable: boolean;
+    pauseOnHover: boolean;
+    position: HcgToastPosition;
+    maxToasts: number;
+    showProgress: boolean;
+    icon?: string | false;
+    iconHtml?: string;
+    ariaLive?: HcgToastAriaLive;
+    onShow?: (toast: HcgToastShown) => void;
+    onDismiss?: (toast: HcgToastShown, reason: HcgToastDismissReason) => void;
+}
+
+export interface HcgToastOptions {
+    message?: string;
+    title?: string;
+    type?: HcgToastType;
+    duration?: number;
+    closable?: boolean;
+    pauseOnHover?: boolean;
+    position?: HcgToastPosition;
+    maxToasts?: number;
+    showProgress?: boolean;
+    icon?: string | false;
+    iconHtml?: string;
+    ariaLive?: HcgToastAriaLive;
+    onShow?: (toast: HcgToastShown) => void;
+    onDismiss?: (toast: HcgToastShown, reason: HcgToastDismissReason) => void;
+}
+
+export interface HcgToastInstance {
+    show(message: string, options?: HcgToastOptions): number | null;
+    success(message: string, options?: HcgToastOptions): number | null;
+    error(message: string, options?: HcgToastOptions): number | null;
+    warning(message: string, options?: HcgToastOptions): number | null;
+    info(message: string, options?: HcgToastOptions): number | null;
+    dismiss(id: number): void;
+    dismissAll(): void;
+    configure(options: HcgToastOptions): void;
+    destroy(): void;
+}
+
+export interface HcgToastFn {
+    (message: string, options?: HcgToastOptions): number | null;
+    success(message: string, options?: HcgToastOptions): number | null;
+    error(message: string, options?: HcgToastOptions): number | null;
+    warning(message: string, options?: HcgToastOptions): number | null;
+    info(message: string, options?: HcgToastOptions): number | null;
+    dismiss(id: number): void;
+    dismissAll(): void;
+    configure(options: HcgToastOptions): void;
+    destroy(): void;
+    create(options?: HcgToastOptions): HcgToastInstance;
+}
+
+declare const toast: HcgToastFn;
+
+export default toast;
+
+declare global {
+    const toast: HcgToastFn;
+}

package/hcg-toast.js

@@ -0,0 +1,418 @@
+/*!
+ * hcg-toast v1.0.0
+ * Lightweight vanilla JavaScript toast / notification library. Zero dependencies.
+ * Requires hcg-toast.css for the default styling.
+ * When changing this file, also update README.md and website-page.html.
+ * @see https://www.html-code-generator.com/javascript/toast-notification
+ * @license MIT
+ */
+(function (root, factory) {
+    const api = factory();
+    if (typeof module === 'object' && module.exports) {
+        module.exports = api;
+    } else {
+        root.toast = api;
+    }
+}(
+    typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : this,
+    () => {
+
+        const DEFAULT_DURATION = 4000;
+        const DEFAULT_MAX_TOASTS = 5;
+        const DEFAULT_POSITION = 'top-right';
+        const EXIT_MS = 250;
+
+        const POSITIONS = [
+            'top-left', 'top-center', 'top-right',
+            'bottom-left', 'bottom-center', 'bottom-right',
+        ];
+
+        const TYPE_ICONS = {
+            info: 'ℹ',
+            success: '✓',
+            warning: '⚠',
+            error: '✕',
+        };
+
+        const positionClass = (pos) => `hcg-toast-container--${pos}`;
+
+        const normalizePosition = (value) => (
+            POSITIONS.includes(value) ? value : DEFAULT_POSITION
+        );
+
+        const mergeOptions = (defaults, overrides) => {
+            const merged = { ...defaults, ...overrides };
+            merged.position = normalizePosition(merged.position);
+            return merged;
+        };
+
+        const applyA11y = (el, options) => {
+            const live = options.ariaLive === 'polite' || options.ariaLive === 'assertive' || options.ariaLive === 'off'
+                ? options.ariaLive
+                : (options.type === 'error' ? 'assertive' : 'off');
+            el.setAttribute('role', options.type === 'error' ? 'alert' : 'status');
+            el.setAttribute('aria-live', live);
+        };
+
+        const createToastInstance = (initialOptions = {}) => {
+            let _toastId = 0;
+            let destroyed = false;
+            let container = null;
+            const toasts = new Map();
+
+            let defaults = mergeOptions({
+                type: 'info',
+                duration: DEFAULT_DURATION,
+                closable: true,
+                pauseOnHover: true,
+                position: DEFAULT_POSITION,
+                maxToasts: DEFAULT_MAX_TOASTS,
+                showProgress: true,
+            }, initialOptions);
+
+            let containerListenersAttached = false;
+
+            const getToastEntry = (host, e) => {
+                const item = e.target.closest('.hcg-toast-item');
+                if (!item || !host.contains(item) || item.contains(e.relatedTarget)) return null;
+                return toasts.get(Number(item.dataset.toastId)) || null;
+            };
+
+            const attachContainerListeners = (host) => {
+                if (containerListenersAttached) return;
+                containerListenersAttached = true;
+
+                host.addEventListener('click', (e) => {
+                    if (!e.target.closest('.hcg-toast-close')) return;
+                    const item = e.target.closest('.hcg-toast-item');
+                    if (!item) return;
+                    removeEntry(Number(item.dataset.toastId), 'close');
+                });
+
+                host.addEventListener('mouseover', (e) => {
+                    const entry = getToastEntry(host, e);
+                    if (entry && entry.options.pauseOnHover && entry.options.duration > 0) {
+                        pauseTimer(entry);
+                    }
+                });
+
+                host.addEventListener('mouseout', (e) => {
+                    const entry = getToastEntry(host, e);
+                    if (entry && entry.options.pauseOnHover && entry.options.duration > 0) {
+                        resumeTimer(entry);
+                    }
+                });
+            };
+
+            const cancelEntryFrame = (entry) => {
+                if (entry.rafId != null) {
+                    cancelAnimationFrame(entry.rafId);
+                    entry.rafId = null;
+                }
+            };
+
+            const ensureContainer = () => {
+                if (destroyed) return null;
+                if (container && document.body.contains(container)) {
+                    return container;
+                }
+                container = document.createElement('div');
+                container.className = `hcg-toast-container ${positionClass(defaults.position)}`;
+                document.body.appendChild(container);
+                containerListenersAttached = false;
+                attachContainerListeners(container);
+                return container;
+            };
+
+            const updateContainerPosition = () => {
+                if (!container) return;
+                container.className = `hcg-toast-container ${positionClass(defaults.position)}`;
+            };
+
+            const clearTimer = (entry) => {
+                if (entry.timerId != null) {
+                    clearTimeout(entry.timerId);
+                    entry.timerId = null;
+                }
+            };
+
+            const removeEntry = (id, reason, immediate = false) => {
+                const entry = toasts.get(id);
+                if (!entry || entry.removing) return;
+                entry.removing = true;
+                clearTimer(entry);
+
+                const { el, options } = entry;
+
+                const finish = () => {
+                    cancelEntryFrame(entry);
+                    if (el.parentNode) el.parentNode.removeChild(el);
+                    toasts.delete(id);
+                    if (typeof options.onDismiss === 'function') {
+                        options.onDismiss({ id, ...options }, reason);
+                    }
+                };
+
+                if (immediate) {
+                    finish();
+                    return;
+                }
+
+                el.classList.remove('hcg-toast-item--enter');
+                el.classList.add('hcg-toast-item--exit');
+
+                let done = false;
+                const onEnd = (e) => {
+                    if (e.target !== el || done) return;
+                    done = true;
+                    el.removeEventListener('transitionend', onEnd);
+                    finish();
+                };
+
+                el.addEventListener('transitionend', onEnd);
+                setTimeout(() => {
+                    if (!done) {
+                        done = true;
+                        el.removeEventListener('transitionend', onEnd);
+                        finish();
+                    }
+                }, EXIT_MS + 50);
+            };
+
+            const startProgressAnimation = (entry) => {
+                if (!entry.progressEl) return;
+                const ms = entry.remaining != null ? entry.remaining : entry.options.duration;
+                const bar = entry.progressEl;
+                bar.style.animation = 'none';
+                void bar.offsetWidth;
+                bar.style.animation = `hcg-toast-progress-shrink ${ms}ms linear forwards`;
+            };
+
+            const scheduleDismiss = (entry) => {
+                clearTimer(entry);
+                if (entry.options.duration <= 0 || entry.paused) return;
+
+                const remaining = entry.remaining != null
+                    ? entry.remaining
+                    : entry.options.duration;
+
+                entry.remaining = remaining;
+                entry.timerStarted = Date.now();
+
+                entry.timerId = setTimeout(() => {
+                    removeEntry(entry.id, 'timeout');
+                }, remaining);
+
+                startProgressAnimation(entry);
+            };
+
+            const pauseTimer = (entry) => {
+                if (entry.paused || entry.options.duration <= 0) return;
+                if (entry.timerStarted == null) return;
+                entry.paused = true;
+                clearTimer(entry);
+                const elapsed = Date.now() - entry.timerStarted;
+                entry.remaining = Math.max(0, (entry.remaining ?? entry.options.duration) - elapsed);
+                if (entry.progressEl) {
+                    entry.progressEl.style.animationPlayState = 'paused';
+                }
+            };
+
+            const resumeTimer = (entry) => {
+                if (!entry.paused || entry.options.duration <= 0) return;
+                entry.paused = false;
+                scheduleDismiss(entry);
+            };
+
+            const enforceMaxToasts = (maxToasts) => {
+                while (toasts.size >= maxToasts) {
+                    const oldest = toasts.keys().next().value;
+                    if (oldest == null) break;
+                    removeEntry(oldest, 'api', true);
+                }
+            };
+
+            const buildToastEl = (options, id) => {
+                const el = document.createElement('div');
+                el.className = `hcg-toast-item hcg-toast-item--${options.type}`;
+                applyA11y(el, options);
+                el.dataset.toastId = String(id);
+
+                if (options.icon !== false) {
+                    const iconEl = document.createElement('span');
+                    iconEl.className = 'hcg-toast-icon';
+                    iconEl.setAttribute('aria-hidden', 'true');
+
+                    if (options.iconHtml) {
+                        iconEl.innerHTML = options.iconHtml;
+                    } else if (typeof options.icon === 'string') {
+                        iconEl.textContent = options.icon;
+                    } else {
+                        iconEl.textContent = TYPE_ICONS[options.type] || TYPE_ICONS.info;
+                    }
+
+                    el.appendChild(iconEl);
+                }
+
+                const body = document.createElement('div');
+                body.className = 'hcg-toast-body';
+
+                if (options.title) {
+                    const titleEl = document.createElement('div');
+                    titleEl.className = 'hcg-toast-title';
+                    titleEl.textContent = options.title;
+                    body.appendChild(titleEl);
+                }
+
+                const messageEl = document.createElement('div');
+                messageEl.className = 'hcg-toast-message';
+                messageEl.textContent = options.message;
+                body.appendChild(messageEl);
+
+                el.appendChild(body);
+
+                if (options.closable) {
+                    const closeBtn = document.createElement('button');
+                    closeBtn.type = 'button';
+                    closeBtn.className = 'hcg-toast-close';
+                    closeBtn.setAttribute('aria-label', 'Dismiss notification');
+                    closeBtn.innerHTML = '&times;';
+                    el.appendChild(closeBtn);
+                }
+
+                let progressEl = null;
+                if (options.duration > 0 && options.showProgress) {
+                    const trackEl = document.createElement('div');
+                    trackEl.className = 'hcg-toast-progress-track';
+
+                    progressEl = document.createElement('div');
+                    progressEl.className = 'hcg-toast-progress';
+
+                    trackEl.appendChild(progressEl);
+                    el.appendChild(trackEl);
+                }
+
+                return { el, progressEl };
+            };
+
+            const show = (message, options = {}) => {
+                if (destroyed) return null;
+
+                const merged = mergeOptions(defaults, {
+                    ...options,
+                    message: message != null ? String(message) : options.message,
+                });
+
+                if (!merged.message) return null;
+
+                const host = ensureContainer();
+                if (!host) return null;
+
+                const id = ++_toastId;
+                const { el, progressEl } = buildToastEl(merged, id);
+
+                const entry = {
+                    id,
+                    el,
+                    progressEl,
+                    options: merged,
+                    paused: false,
+                    remaining: merged.duration,
+                    removing: false,
+                    timerId: null,
+                    timerStarted: null,
+                    rafId: null,
+                };
+
+                enforceMaxToasts(merged.maxToasts);
+
+                toasts.set(id, entry);
+                host.appendChild(el);
+
+                entry.rafId = requestAnimationFrame(() => {
+                    entry.rafId = null;
+                    if (!toasts.has(id)) return;
+                    el.classList.add('hcg-toast-item--enter');
+                    if (merged.duration > 0) {
+                        scheduleDismiss(entry);
+                    }
+                    if (typeof merged.onShow === 'function') {
+                        merged.onShow({ id, ...merged });
+                    }
+                });
+
+                return id;
+            };
+
+            const typedShow = (type) => (message, options = {}) => (
+                show(message, { ...options, type })
+            );
+
+            const dismiss = (id) => {
+                if (id == null) return;
+                removeEntry(id, 'api');
+            };
+
+            const dismissAll = () => {
+                [...toasts.keys()].forEach((id) => removeEntry(id, 'api', true));
+            };
+
+            const configure = (partialOptions = {}) => {
+                if (destroyed) return;
+                defaults = mergeOptions(defaults, partialOptions);
+                updateContainerPosition();
+            };
+
+            const destroy = () => {
+                if (destroyed) return;
+                dismissAll();
+                if (container && container.parentNode) {
+                    container.parentNode.removeChild(container);
+                }
+                container = null;
+                containerListenersAttached = false;
+                destroyed = true;
+            };
+
+            return {
+                show,
+                success: typedShow('success'),
+                error: typedShow('error'),
+                warning: typedShow('warning'),
+                info: typedShow('info'),
+                dismiss,
+                dismissAll,
+                configure,
+                destroy,
+            };
+        };
+
+        let defaultInstance = null;
+
+        const getDefaultInstance = () => {
+            if (!defaultInstance) {
+                defaultInstance = createToastInstance();
+            }
+            return defaultInstance;
+        };
+
+        const toastFn = (message, options) => getDefaultInstance().show(message, options);
+
+        toastFn.success = (message, options) => getDefaultInstance().success(message, options);
+        toastFn.error = (message, options) => getDefaultInstance().error(message, options);
+        toastFn.warning = (message, options) => getDefaultInstance().warning(message, options);
+        toastFn.info = (message, options) => getDefaultInstance().info(message, options);
+        toastFn.dismiss = (id) => getDefaultInstance().dismiss(id);
+        toastFn.dismissAll = () => getDefaultInstance().dismissAll();
+        toastFn.configure = (options) => getDefaultInstance().configure(options);
+        toastFn.destroy = () => {
+            if (defaultInstance) {
+                defaultInstance.destroy();
+                defaultInstance = null;
+            }
+        };
+        toastFn.create = (options) => createToastInstance(options);
+
+        return toastFn;
+    }
+));

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "hcg-toast",
+  "version": "1.0.0",
+  "description": "Lightweight vanilla JavaScript toast notification library. Success, error, warning, and info types, auto-dismiss, sticky toasts, six positions, stack limits, pause on hover, and TypeScript definitions. Zero dependencies.",
+  "main": "hcg-toast.js",
+  "types": "hcg-toast.d.ts",
+  "style": "hcg-toast.css",
+  "files": [
+    "hcg-toast.js",
+    "hcg-toast.css",
+    "hcg-toast.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"No tests specified\" && exit 0"
+  },
+  "keywords": [
+    "toast",
+    "notification",
+    "toast-notification",
+    "hcg-toast",
+    "alert",
+    "snackbar",
+    "vanilla-js",
+    "no-dependencies",
+    "accessible",
+    "aria",
+    "typescript"
+  ],
+  "author": "HTML Code Generator (https://www.html-code-generator.com/)",
+  "license": "MIT",
+  "homepage": "https://www.html-code-generator.com/javascript/toast-notification",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/html-code-generator/hcg-toast.git"
+  },
+  "bugs": {
+    "url": "https://github.com/html-code-generator/hcg-toast/issues"
+  }
+}