@appius-fr/apx 2.3.0 → 2.5.0

package/modules/toast/README.md

@@ -0,0 +1,127 @@
+# APX Toast
+
+A tiny, framework‑agnostic toast library for APX. Minimal CSS, ESM‑first, no globals. DOM is only touched when you actually show a toast (SSR‑safe to import).
+
+## Install / Import
+
+Just import `APX` — the toast CSS is automatically loaded by `modules/toast/toast.mjs`.
+
+```html
+<script type="module">
+  import APX from './APX.mjs';
+  // CSS is auto‑imported; no <link> tag required.
+  // ...
+  APX.toast.success('Ready!');
+ </script>
+```
+
+## Quick start
+
+```js
+// Default manager (lazy)
+APX.toast.success('Saved!');
+APX.toast.warning('Heads up', { durationMs: 4000 });
+APX.toast.danger('Something failed', { durationMs: 0 }); // sticky
+
+// Custom toast
+const ref = APX.toast.show({ message: 'Processing…', type: 'info', durationMs: 0 });
+// Callable shorthand for show:
+APX.toast({ message: 'Hello', type: 'success' });
+ref.update({ message: 'Done', type: 'success', durationMs: 1800 });
+ref.whenClosed().then(() => console.log('closed'));
+
+// Configure defaults at runtime
+APX.toast.configure({ position: 'top-right', maxToasts: 4, dedupe: true });
+```
+
+### Named managers (profiles)
+
+```js
+// Register a named manager
+APX.toast.create('admin', { position: 'bottom-left', ariaLive: 'polite' });
+
+// Use it later
+APX.toast.use('admin').info('Admin ready');
+APX.toast.use('admin').closeAll();
+```
+
+## API overview
+
+- Top‑level (default manager):
+  - `APX.toast.show(opts)`
+  - `APX.toast.info|success|warning|danger(message, opts?)`
+  - `APX.toast.configure(config)`
+  - `APX.toast.closeAll(reason?)`
+  - `APX.toast.create(name, config)` → registers named manager
+  - `APX.toast.use(name)` → returns named manager
+
+- Named manager instance (same surface):
+  - `.show(opts)`, `.info|success|warning|danger(message, opts?)`
+  - `.configure(config)`, `.closeAll(reason?)`
+
+## Options and types
+
+```js
+// ToastConfig (global/manager defaults)
+{
+  position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left', // default 'bottom-right'
+  maxToasts: number,                // default 5
+  defaultDurationMs: number,        // default 5000
+  zIndex: number,                   // default 11000
+  ariaLive: 'polite'|'assertive'|'off', // default 'polite'
+  gap: number,                      // default 8
+  dedupe: boolean,                  // default false
+  containerClass: string,           // extra class on container
+  offset: number                    // px offset from screen edges
+}
+
+// ToastOptions (per toast)
+{
+  message: string | Node,
+  type: 'info'|'success'|'warning'|'danger', // default 'info'
+  durationMs: number,               // default from config; 0 = sticky
+  dismissible: boolean,             // default true
+  id: string,                       // stable id for dedupe updates
+  className: string,                // extra classes on the toast element
+  onClick: (ref, ev) => void,
+  onClose: (ref, reason) => void    // reason: 'timeout'|'close'|'api'|'overflow'
+}
+```
+
+## Theming (minimal CSS)
+
+Override CSS variables to theme without touching markup:
+
+```css
+:root {
+  --apx-toast-gap: 10px;
+  --apx-toast-min-width: 280px;
+  --apx-toast-radius: 8px;
+  --apx-toast-success-bg: #16a34a;
+  --apx-toast-success-fg: #fff;
+}
+```
+
+Class structure (BEM‑like):
+- Container: `APX-toast-container APX-toast-container--{corner}`
+- Toast: `APX-toast APX-toast--{type}`
+- Children: `APX-toast__content`, optional `APX-toast__close`
+- Animations: `APX-toast--enter/--enter-active`, `APX-toast--exit/--exit-active`
+
+## Behavior
+
+- Lazy container creation (first `show`).
+- `maxToasts` enforced; oldest removed with reason `'overflow'`.
+- Hover pauses timer; resumes on mouse leave.
+- `durationMs = 0` makes the toast sticky.
+- If `dedupe: true` and `id` matches an open toast, it updates instead of creating a new one.
+
+## Accessibility & SSR
+
+- Container uses `aria-live` (configurable).
+- Each toast has `role="status"`.
+- ESM only; no DOM access at import time. Safe to import in SSR; DOM is touched only when showing toasts in the browser.
+
+## License
+
+Copyright Appius.

package/modules/toast/css/toast.css

@@ -0,0 +1,60 @@
+.APX-toast-container {
+    position: fixed;
+    display: flex;
+    flex-direction: column;
+    gap: var(--apx-toast-gap, 8px);
+    z-index: var(--apx-toast-z-index, 11000);
+    pointer-events: none;
+}
+
+.APX-toast-container--bottom-right { right: 12px; bottom: 12px; align-items: flex-end; }
+.APX-toast-container--bottom-left { left: 12px; bottom: 12px; align-items: flex-start; }
+.APX-toast-container--top-right { right: 12px; top: 12px; align-items: flex-end; }
+.APX-toast-container--top-left { left: 12px; top: 12px; align-items: flex-start; }
+
+.APX-toast {
+    min-width: var(--apx-toast-min-width, 260px);
+    max-width: var(--apx-toast-max-width, 420px);
+    font-size: var(--apx-toast-font-size, 14px);
+    border-radius: var(--apx-toast-radius, 6px);
+    box-shadow: var(--apx-toast-shadow, 0 6px 24px rgba(0,0,0,0.2));
+    padding: var(--apx-toast-padding, 10px 42px 10px 14px);
+    color: #111;
+    background: #eee;
+    pointer-events: auto;
+    position: relative;
+    transition: opacity 180ms ease, transform 180ms ease;
+}
+
+.APX-toast--info { background: var(--apx-toast-info-bg, #0dcaf0); color: var(--apx-toast-info-fg, #052c65); }
+.APX-toast--success { background: var(--apx-toast-success-bg, #198754); color: var(--apx-toast-success-fg, #ffffff); }
+.APX-toast--warning { background: var(--apx-toast-warning-bg, #ffc107); color: var(--apx-toast-warning-fg, #664d03); }
+.APX-toast--danger { background: var(--apx-toast-danger-bg, #dc3545); color: var(--apx-toast-danger-fg, #ffffff); }
+
+.APX-toast__content { line-height: 1.35; }
+
+.APX-toast__close {
+    position: absolute;
+    top: 50%; right: 10px;
+    width: 24px; height: 24px;
+    transform: translateY(-50%);
+    display: inline-flex; align-items: center; justify-content: center;
+    background: transparent; color: currentColor;
+    border: 0; border-radius: 4px; padding: 0; margin: 0;
+    cursor: pointer; appearance: none; -webkit-appearance: none;
+    opacity: .75; transition: opacity 120ms ease;
+}
+.APX-toast__close:hover { opacity: 1; }
+.APX-toast__close:focus { outline: 2px solid rgba(0,0,0,.2); outline-offset: 2px; }
+.APX-toast__close::before {
+    content: '×';
+    font-size: 16px; line-height: 1; text-align: center;
+}
+
+/* Animations */
+.APX-toast--enter { opacity: 0; transform: translateY(8px); }
+.APX-toast--enter.APX-toast--enter-active { opacity: 1; transform: translateY(0); }
+.APX-toast--exit { opacity: 1; transform: translateY(0); }
+.APX-toast--exit.APX-toast--exit-active { opacity: 0; transform: translateY(8px); }
+
+

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.3.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": {