@appius-fr/apx 2.4.0 → 2.5.0

package/modules/toast/toast.mjs

@@ -0,0 +1,374 @@
+// Minimal, framework-agnostic ToastManager for APX
+// ESM-first, no side effects on import. DOM only when used.
+import './css/toast.css';
+
+/**
+ * @typedef {Object} ToastConfig
+ * @property {'bottom-right'|'bottom-left'|'top-right'|'top-left'} [position]
+ * @property {number} [maxToasts]
+ * @property {number} [defaultDurationMs]
+ * @property {number} [zIndex]
+ * @property {'polite'|'assertive'|'off'} [ariaLive]
+ * @property {number} [gap]
+ * @property {boolean} [dedupe]
+ * @property {string} [containerClass]
+ * @property {number} [offset]
+ */
+
+/**
+ * @typedef {Object} ToastOptions
+ * @property {string|Node} message
+ * @property {'info'|'success'|'warning'|'danger'} [type]
+ * @property {number} [durationMs]
+ * @property {boolean} [dismissible]
+ * @property {string} [id]
+ * @property {(ref: ToastRef, ev: MouseEvent) => void} [onClick]
+ * @property {(ref: ToastRef, reason: 'timeout'|'close'|'api'|'overflow') => void} [onClose]
+ * @property {string} [className]
+ */
+
+/**
+ * @typedef {Object} ToastRef
+ * @property {string} id
+ * @property {HTMLElement} el
+ * @property {(reason?: 'api'|'close') => void} close
+ * @property {(partial: Partial<ToastOptions>) => void} update
+ * @property {() => Promise<void>} whenClosed
+ * @property {(event: 'close'|'click', handler: Function) => () => void} on
+ * @property {(event: 'close'|'click', handler: Function) => void} off
+ */
+
+const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
+
+const DEFAULT_CONFIG = {
+    position: 'bottom-right',
+    maxToasts: 5,
+    defaultDurationMs: 5000,
+    zIndex: 11000,
+    ariaLive: 'polite',
+    gap: 8,
+    dedupe: false,
+    containerClass: '',
+    offset: 0
+};
+
+/**
+ * Create an element with classes
+ */
+function createEl(tag, classNames) {
+    const el = document.createElement(tag);
+    if (classNames) {
+        classNames.split(' ').filter(Boolean).forEach(c => el.classList.add(c));
+    }
+    return el;
+}
+
+/**
+ * ToastManager class
+ */
+class ToastManager {
+    /** @param {Partial<ToastConfig>=} config */
+    constructor(config) {
+        /** @type {ToastConfig} */
+        this.config = { ...DEFAULT_CONFIG, ...(config || {}) };
+        /** @type {HTMLElement|null} */
+        this.container = null;
+        /** @type {Map<string, ToastRef>} */
+        this.idToRef = new Map();
+        /** @type {ToastRef[]} */
+        this.open = [];
+    }
+
+    /** @param {Partial<ToastConfig>} config */
+    configure(config) {
+        this.config = { ...this.config, ...(config || {}) };
+        if (this.container) this.applyContainerConfig();
+    }
+
+    /** @param {'polite'|'assertive'|'off'} mode */
+    setAriaLive(mode) { this.configure({ ariaLive: mode }); }
+
+    /** @returns {ToastRef[]} */
+    getOpenToasts() { return this.open.slice(); }
+
+    /** @param {ToastOptions} opts */
+    show(opts) {
+        if (!isBrowser) return /** @type {any} */(null);
+        const options = this.normalizeOptions(opts);
+
+        if (this.config.dedupe && options.id && this.idToRef.has(options.id)) {
+            const ref = this.idToRef.get(options.id);
+            ref.update(options);
+            return ref;
+        }
+
+        this.ensureContainer();
+
+        const toastEl = createEl('div', `APX-toast APX-toast--${options.type}`);
+        toastEl.setAttribute('role', 'status');
+        const toastId = options.id || `t_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        toastEl.dataset.toastId = toastId;
+        if (options.className) toastEl.className += ` ${options.className}`;
+
+        const contentEl = createEl('div', 'APX-toast__content');
+        if (typeof options.message === 'string') {
+            contentEl.textContent = options.message;
+        } else if (options.message) {
+            contentEl.appendChild(options.message);
+        }
+        toastEl.appendChild(contentEl);
+
+        let closeBtn = null;
+        if (options.dismissible !== false) {
+            closeBtn = createEl('button', 'APX-toast__close');
+            closeBtn.setAttribute('aria-label', 'Close');
+            closeBtn.type = 'button';
+            toastEl.appendChild(closeBtn);
+        }
+
+        this.container.appendChild(toastEl);
+
+        // Enter animation
+        toastEl.classList.add('APX-toast--enter');
+        requestAnimationFrame(() => {
+            toastEl.classList.add('APX-toast--enter-active');
+        });
+
+        // Event handling and timers
+        let remaining = options.durationMs;
+        let timerId = null;
+        let startTs = null;
+        const handlers = { click: new Set(), close: new Set() };
+
+        const startTimer = () => {
+            if (!remaining || remaining <= 0) return; // sticky
+            startTs = Date.now();
+            timerId = window.setTimeout(() => ref.close('timeout'), remaining);
+        };
+        const pauseTimer = () => {
+            if (timerId != null) {
+                window.clearTimeout(timerId);
+                timerId = null;
+                if (startTs != null) remaining -= (Date.now() - startTs);
+            }
+        };
+
+        /** @type {ToastRef} */
+        const ref = {
+            id: toastId,
+            el: toastEl,
+            close: (reason) => {
+                cleanup(reason || 'api');
+            },
+            update: (partial) => {
+                const merged = this.normalizeOptions({ ...options, ...partial });
+                // update content
+                if (typeof merged.message === 'string') {
+                    contentEl.textContent = merged.message;
+                } else if (merged.message) {
+                    contentEl.innerHTML = '';
+                    contentEl.appendChild(merged.message);
+                }
+                // update type class
+                ['info','success','warning','danger'].forEach(t => toastEl.classList.remove(`APX-toast--${t}`));
+                toastEl.classList.add(`APX-toast--${merged.type}`);
+                // update classes
+                if (options.className !== merged.className) {
+                    if (options.className) toastEl.classList.remove(...options.className.split(' ').filter(Boolean));
+                    if (merged.className) toastEl.classList.add(...merged.className.split(' ').filter(Boolean));
+                }
+                // update duration logic
+                options.durationMs = merged.durationMs;
+                remaining = merged.durationMs;
+                pauseTimer();
+                startTimer();
+            },
+            whenClosed: () => closedPromise,
+            on: (event, handler) => { handlers[event].add(handler); return () => ref.off(event, handler); },
+            off: (event, handler) => { handlers[event].delete(handler); }
+        };
+
+        const notify = (event, arg) => handlers[event].forEach(fn => { try { fn(arg); } catch (_) {} });
+
+        const closedPromise = new Promise(resolve => {
+            const finish = (reason) => {
+                notify('close', reason);
+                if (typeof options.onClose === 'function') {
+                    try { options.onClose(ref, reason); } catch(_){}
+                }
+                resolve();
+            };
+
+            const cleanup = (reason) => {
+                if (!toastEl) return;
+                pauseTimer();
+                // If overflow, remove immediately to enforce hard cap
+                if (reason === 'overflow') {
+                    if (toastEl.parentElement) toastEl.parentElement.removeChild(toastEl);
+                    const idx = this.open.indexOf(ref);
+                    if (idx >= 0) this.open.splice(idx, 1);
+                    this.idToRef.delete(toastId);
+                    finish(reason);
+                    return;
+                }
+
+                // Otherwise, animate out
+                toastEl.classList.add('APX-toast--exit');
+                requestAnimationFrame(() => toastEl.classList.add('APX-toast--exit-active'));
+
+                const removeEl = () => {
+                    toastEl.removeEventListener('transitionend', removeEl);
+                    if (toastEl.parentElement) toastEl.parentElement.removeChild(toastEl);
+                    const idx = this.open.indexOf(ref);
+                    if (idx >= 0) this.open.splice(idx, 1);
+                    this.idToRef.delete(toastId);
+                    finish(reason);
+                };
+                toastEl.addEventListener('transitionend', removeEl);
+            };
+
+            // attach close behavior
+            ref.close = (reason) => cleanup(reason || 'api');
+        });
+
+        // Click handling
+        toastEl.addEventListener('click', (ev) => {
+            notify('click', ev);
+            if (typeof options.onClick === 'function') {
+                try { options.onClick(ref, ev); } catch(_){}
+            }
+        });
+
+        // Hover pause
+        toastEl.addEventListener('mouseenter', pauseTimer);
+        toastEl.addEventListener('mouseleave', () => startTimer());
+
+        if (closeBtn) closeBtn.addEventListener('click', (ev) => { ev.stopPropagation(); ref.close('close'); });
+
+        // Track
+        this.open.push(ref);
+        this.idToRef.set(toastId, ref);
+
+        // Overflow policy
+        if (this.open.length > this.config.maxToasts) {
+            const oldest = this.open[0];
+            oldest.close('overflow');
+        }
+
+        startTimer();
+        return ref;
+    }
+
+    /**
+     * Convenience helpers
+     */
+    info(message, opts) { return this.show({ ...(opts||{}), message, type: 'info' }); }
+    success(message, opts) { return this.show({ ...(opts||{}), message, type: 'success' }); }
+    warning(message, opts) { return this.show({ ...(opts||{}), message, type: 'warning' }); }
+    danger(message, opts) { return this.show({ ...(opts||{}), message, type: 'danger' }); }
+
+    /** @param {'api'|'overflow'} [reason] */
+    closeAll(reason) {
+        // copy to avoid mutation during iteration
+        const all = this.open.slice();
+        all.forEach(r => r.close(reason || 'api'));
+    }
+
+    /** @param {ToastOptions} opts */
+    normalizeOptions(opts) {
+        const o = { ...opts };
+        if (!o.type) o.type = 'info';
+        if (typeof o.dismissible !== 'boolean') o.dismissible = true;
+        if (typeof o.durationMs !== 'number') o.durationMs = this.config.defaultDurationMs;
+        return o;
+    }
+
+    ensureContainer() {
+        if (this.container || !isBrowser) return;
+        const c = createEl('div', 'APX-toast-container');
+        const pos = this.config.position || 'bottom-right';
+        c.classList.add(`APX-toast-container--${pos}`);
+        if (this.config.containerClass) c.classList.add(this.config.containerClass);
+        c.style.zIndex = String(this.config.zIndex);
+        c.style.gap = `${this.config.gap}px`;
+        if (this.config.offset) {
+            const offset = `${this.config.offset}px`;
+            if (pos.includes('bottom')) c.style.bottom = offset; else c.style.top = offset;
+            if (pos.includes('right')) c.style.right = offset; else c.style.left = offset;
+        }
+        c.setAttribute('aria-live', String(this.config.ariaLive));
+        document.body.appendChild(c);
+        this.container = c;
+        this.applyContainerConfig();
+    }
+
+    applyContainerConfig() {
+        if (!this.container) return;
+        this.container.style.zIndex = String(this.config.zIndex);
+        this.container.style.gap = `${this.config.gap}px`;
+        this.container.setAttribute('aria-live', String(this.config.ariaLive));
+        // Update position class
+        const posClasses = ['bottom-right','bottom-left','top-right','top-left'].map(p => `APX-toast-container--${p}`);
+        this.container.classList.remove(...posClasses);
+        this.container.classList.add(`APX-toast-container--${this.config.position}`);
+    }
+}
+
+/**
+ * @param {Partial<ToastConfig>=} config
+ * @returns {ToastManager}
+ */
+function createToastManager(config) {
+    return new ToastManager(config);
+}
+
+// High-level APX.toast API (default & named managers)
+let _defaultManager = null;
+const _getDefault = () => {
+    if (!_defaultManager) _defaultManager = createToastManager();
+    return _defaultManager;
+};
+
+/**
+ * Toast API surface to be attached as APX.toast.
+ * Callable form proxies to defaultManager.show(opts): APX.toast({...})
+ */
+function toast(opts) {
+    return _getDefault().show(opts);
+}
+
+Object.assign(toast, {
+    /**
+     * Create a manager. If first arg is string, register as named under toast.custom[name]
+     * @param {string|Partial<ToastConfig>} nameOrConfig
+     * @param {Partial<ToastConfig>=} maybeConfig
+     * @returns {ToastManager}
+     */
+    create: (nameOrConfig, maybeConfig) => {
+        if (typeof nameOrConfig === 'string') {
+            const name = nameOrConfig;
+            const manager = new ToastManager({ ...(maybeConfig || {}) });
+            if (!toast.custom) toast.custom = {};
+            toast.custom[name] = manager;
+            return manager;
+        }
+        return new ToastManager({ ...(nameOrConfig || {}) });
+    },
+    /** @type {Record<string, ToastManager>} */
+    custom: {},
+    /** @param {string} name */
+    use: (name) => (toast.custom && toast.custom[name]) || null,
+    Manager: ToastManager,
+    show: (opts) => _getDefault().show(opts),
+    info: (message, opts) => _getDefault().info(message, opts),
+    success: (message, opts) => _getDefault().success(message, opts),
+    warning: (message, opts) => _getDefault().warning(message, opts),
+    danger: (message, opts) => _getDefault().danger(message, opts),
+    configure: (config) => _getDefault().configure(config),
+    setAriaLive: (mode) => _getDefault().setAriaLive(mode),
+    closeAll: (reason) => _getDefault().closeAll(reason),
+    getOpenToasts: () => _getDefault().getOpenToasts()
+});
+
+export default toast;
+export { ToastManager, createToastManager, toast };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appius-fr/apx",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Appius Extended JS - A powerful JavaScript extension library",
   "main": "dist/APX.prod.mjs",
   "module": "dist/APX.prod.mjs",
@@ -30,7 +30,8 @@
     "build": "webpack --config webpack.config.js",
     "build:prod": "webpack --config webpack.prod.config.js",
     "build:dev": "webpack --config webpack.dev.config.js",
-    "build:all": "npm run build && npm run build:prod && npm run build:dev",
+    "build:standalone": "webpack --config webpack.standalone.config.js",
+    "build:all": "npm run build && npm run build:prod && npm run build:dev && npm run build:standalone",
     "prepare": "npm run build:all"
   },
   "repository": {