@appius-fr/apx 2.4.0 → 2.5.2

package/modules/toast/toast.mjs

@@ -0,0 +1,1025 @@
+// Minimal, framework-agnostic ToastManager for APX
+// ESM-first, no side effects on import. DOM only when used.
+import './css/toast.css';
+
+/**
+ * @typedef {Object} PositionObject
+ * @property {'sticky'|'relative'|'anchored'} [type]
+ * @property {string} [x]
+ * @property {string} [y]
+ * @property {HTMLElement} [element]
+ * @property {'top'|'right'|'bottom'|'left'|'above'|'below'|'before'|'after'} [placement]
+ * @property {string} [gap]
+ * @property {boolean} [useNativeCSS]
+ */
+
+/**
+ * @typedef {string|PositionObject} Position
+ */
+
+/**
+ * @typedef {Object} ToastConfig
+ * @property {Position} [position]
+ * @property {'up'|'down'|'auto'} [flow] Flow direction for stacking toasts. 'auto' determines based on position. Default: 'auto'
+ * @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]
+ * @property {string} [id]
+ */
+
+/**
+ * @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]
+ * @property {Position} [position]
+ * @property {'up'|'down'|'auto'} [flow] Flow direction for stacking toasts. 'auto' determines based on position. Default: 'auto'
+ */
+
+/**
+ * @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';
+
+// Shared container cache: Map<position, HTMLElement>
+// Containers are shared between managers with the same position
+const _containerCache = new Map();
+
+// Garbage collection: cleanup empty unmanaged containers after a delay
+const GC_DELAY_MS = 20000; // 20 seconds
+let _gcTimeoutId = null;
+
+// Wrapper for all toast containers (keeps DOM clean)
+let _toastWrapper = null;
+
+/**
+ * Get or create the toast containers wrapper
+ * @returns {HTMLElement|null}
+ */
+function getToastWrapper() {
+    if (!isBrowser) return null;
+    
+    if (!_toastWrapper) {
+        _toastWrapper = document.querySelector('.APX-toast-wrapper');
+        if (!_toastWrapper) {
+            _toastWrapper = createEl('div', 'APX-toast-wrapper');
+            _toastWrapper.style.position = 'fixed';
+            _toastWrapper.style.top = '0';
+            _toastWrapper.style.left = '0';
+            _toastWrapper.style.width = '0';
+            _toastWrapper.style.height = '0';
+            _toastWrapper.style.pointerEvents = 'none';
+            _toastWrapper.style.zIndex = '10000'; // Below containers but above most content
+            document.body.appendChild(_toastWrapper);
+        }
+    }
+    
+    return _toastWrapper;
+}
+
+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;
+}
+
+/**
+ * Normalize placement synonyms to CSS values
+ * @param {string} placement
+ * @returns {'top'|'right'|'bottom'|'left'}
+ */
+function normalizePlacement(placement) {
+    const synonyms = {
+        'above': 'top',
+        'below': 'bottom',
+        'before': 'left',
+        'after': 'right'
+    };
+    return synonyms[placement] || placement;
+}
+
+/**
+ * Determine flow direction based on position
+ * @param {Position} position
+ * @returns {'up'|'down'}
+ */
+function determineFlow(position) {
+    if (typeof position === 'string') {
+        // String positions: top = up, bottom = down
+        if (position.includes('top')) return 'up';
+        if (position.includes('bottom')) return 'down';
+        return 'down'; // default
+    }
+    
+    if (typeof position === 'object' && position !== null) {
+        const type = position.type || (position.x || position.y ? 'sticky' : null);
+        
+        if (type === 'sticky' || (!type && (position.x || position.y))) {
+            // Sticky: determine based on y coordinate
+            if (position.y !== undefined) {
+                // If y starts with '-' or is a small value, likely top (up)
+                // If y is a large value or percentage, likely bottom (down)
+                if (position.y.startsWith('-')) {
+                    // Negative = from bottom, so flow down
+                    return 'down';
+                }
+                const num = parseFloat(position.y);
+                if (!isNaN(num)) {
+                    // If y < 50% of viewport height, likely top (up)
+                    // Otherwise likely bottom (down)
+                    if (position.y.includes('%')) {
+                        return num < 50 ? 'up' : 'down';
+                    }
+                    // For px values, assume < 400px is top (up)
+                    return num < 400 ? 'up' : 'down';
+                }
+            }
+            return 'down'; // default
+        }
+        
+        if (type === 'anchored' && position.placement) {
+            // Anchored: placement determines flow
+            const placement = normalizePlacement(position.placement);
+            if (placement === 'top' || placement === 'above') return 'up';
+            if (placement === 'bottom' || placement === 'below') return 'down';
+            // For left/right, default to down
+            return 'down';
+        }
+        
+        if (type === 'relative') {
+            // Relative: determine based on y offset
+            if (position.y !== undefined) {
+                const num = parseFloat(position.y);
+                if (!isNaN(num)) {
+                    // Negative y = above element = flow up
+                    // Positive y = below element = flow down
+                    return num < 0 ? 'up' : 'down';
+                }
+            }
+            return 'down'; // default
+        }
+    }
+    
+    return 'down'; // default
+}
+
+/**
+ * Garbage collection: remove empty unmanaged containers
+ */
+function cleanupEmptyContainers() {
+    if (!isBrowser) return;
+    
+    const containers = document.querySelectorAll('.APX-toast-container:not([data-apx-toast-managed="true"])');
+    containers.forEach(container => {
+        // Check if container is empty (no toasts)
+        if (container.children.length === 0) {
+            const positionKey = container.getAttribute('data-apx-toast-position');
+            if (positionKey) {
+                _containerCache.delete(positionKey);
+            }
+            container.remove();
+        }
+    });
+    
+    // Clean up wrapper if it's empty (all containers removed)
+    if (_toastWrapper && _toastWrapper.children.length === 0) {
+        _toastWrapper.remove();
+        _toastWrapper = null;
+    }
+    
+    _gcTimeoutId = null;
+}
+
+/**
+ * Schedule garbage collection for empty unmanaged containers
+ */
+function scheduleGarbageCollection() {
+    if (_gcTimeoutId) {
+        clearTimeout(_gcTimeoutId);
+    }
+    _gcTimeoutId = setTimeout(cleanupEmptyContainers, GC_DELAY_MS);
+}
+
+/**
+ * Find all scrollable parent elements
+ * @param {HTMLElement} element
+ * @returns {HTMLElement[]}
+ */
+function findScrollableParents(element) {
+    const scrollables = [];
+    let current = element.parentElement;
+    
+    while (current && current !== document.body && current !== document.documentElement) {
+        const style = window.getComputedStyle(current);
+        const overflow = style.overflow + style.overflowY + style.overflowX;
+        
+        if (overflow.includes('scroll') || overflow.includes('auto')) {
+            scrollables.push(current);
+        }
+        
+        current = current.parentElement;
+    }
+    
+    return scrollables;
+}
+
+/**
+ * Hash an element to create a unique identifier
+ * @param {HTMLElement} el
+ * @returns {string}
+ */
+function hashElement(el) {
+    const rect = el.getBoundingClientRect();
+    const str = `${el.tagName}_${rect.left}_${rect.top}_${rect.width}_${rect.height}`;
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return Math.abs(hash).toString(36);
+}
+
+/**
+ * Serialize position options into a unique key
+ * @param {Position} position
+ * @returns {string}
+ */
+function serializePosition(position) {
+    if (typeof position === 'string') {
+        return `s:${position}`;
+    }
+    
+    if (typeof position === 'object' && position !== null) {
+        const parts = [];
+        
+        // Type (default: sticky if x/y provided)
+        const type = position.type || (position.x || position.y ? 'sticky' : null);
+        if (type) parts.push(`t:${type}`);
+        
+        // Coordinates
+        if (position.x !== undefined) parts.push(`x:${position.x}`);
+        if (position.y !== undefined) parts.push(`y:${position.y}`);
+        
+        // For relative/anchored: use element ID or hash
+        if (position.element) {
+            const elementId = position.element.id || 
+                             position.element.dataset?.apxToastAnchorId ||
+                             `el_${hashElement(position.element)}`;
+            parts.push(`el:${elementId}`);
+        }
+        
+        if (position.placement) {
+            // Normalize placement for serialization (use CSS values)
+            const normalized = normalizePlacement(position.placement);
+            parts.push(`p:${normalized}`);
+        }
+        if (position.gap !== undefined) parts.push(`g:${position.gap}`);
+        if (position.useNativeCSS) parts.push(`native:true`);
+        
+        return `o:${parts.join('|')}`;
+    }
+    
+    return 's:bottom-right';
+}
+
+/**
+ * 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;
+        }
+
+        // Determine position and flow for this toast (options take precedence over config)
+        const position = options.position || this.config.position || 'bottom-right';
+        const flow = options.flow !== undefined ? options.flow : (this.config.flow !== undefined ? this.config.flow : 'auto');
+        const finalFlow = flow === 'auto' ? determineFlow(position) : flow;
+        
+        // Ensure default container is set (for backward compatibility)
+        this.ensureContainer();
+
+        const toastEl = createEl('div', `APX-toast APX-toast--${options.type}`);
+        toastEl.setAttribute('role', 'status');
+        // Priority: options.id > config.id > auto-generated
+        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);
+        }
+
+        // Get or create container for this specific position
+        let container = null;
+        let positionUpdateFn = null;
+        let positionCleanup = null;
+        let originalElementStyle = null;
+        
+        if (position && typeof position === 'object' && position !== null) {
+            const type = position.type || (position.x || position.y ? 'sticky' : null);
+            
+            if (position.useNativeCSS && (type === 'relative' || type === 'anchored') && position.element) {
+                // useNativeCSS: true - create container in target element using native CSS
+                const targetEl = position.element;
+                originalElementStyle = targetEl.style.position;
+                targetEl.style.position = 'relative';
+                
+                // Create a container for stacking toasts (reuse if exists)
+                const positionKey = serializePosition(position);
+                let nativeContainer = targetEl.querySelector(`[data-apx-toast-position="${positionKey}"]`);
+                if (!nativeContainer) {
+                    nativeContainer = createEl('div', 'APX-toast-container APX-toast-container-native');
+                    nativeContainer.setAttribute('data-apx-toast-position', positionKey);
+                    nativeContainer.style.position = 'absolute';
+                    nativeContainer.style.zIndex = String(this.config.zIndex);
+                    nativeContainer.style.gap = `${this.config.gap}px`;
+                    nativeContainer.setAttribute('aria-live', String(this.config.ariaLive));
+                    nativeContainer.style.flexDirection = finalFlow === 'up' ? 'column-reverse' : 'column';
+                    
+                    // Apply positioning to container
+                    if (type === 'relative') {
+                        // Relative: use x/y directly
+                        if (position.x !== undefined) {
+                            if (position.x.startsWith('-')) {
+                                nativeContainer.style.right = position.x.substring(1);
+                            } else {
+                                nativeContainer.style.left = position.x;
+                            }
+                        }
+                        if (position.y !== undefined) {
+                            if (position.y.startsWith('-')) {
+                                nativeContainer.style.bottom = position.y.substring(1);
+                            } else {
+                                nativeContainer.style.top = position.y;
+                            }
+                        }
+                    } else if (type === 'anchored') {
+                        // Anchored: position outside the element using 100% (element size) + gap
+                        const placement = normalizePlacement(position.placement);
+                        const gap = position.gap || '1em';
+                        
+                        switch (placement) {
+                            case 'top':
+                                nativeContainer.style.bottom = `calc(100% + ${gap})`;
+                                nativeContainer.style.left = '0';
+                                break;
+                            case 'bottom':
+                                nativeContainer.style.top = `calc(100% + ${gap})`;
+                                nativeContainer.style.left = '0';
+                                break;
+                            case 'left':
+                                nativeContainer.style.right = `calc(100% + ${gap})`;
+                                nativeContainer.style.top = '0';
+                                break;
+                            case 'right':
+                                nativeContainer.style.left = `calc(100% + ${gap})`;
+                                nativeContainer.style.top = '0';
+                                break;
+                        }
+                    }
+                    
+                    targetEl.appendChild(nativeContainer);
+                } else {
+                    // Update flow direction if container exists
+                    nativeContainer.style.flexDirection = finalFlow === 'up' ? 'column-reverse' : 'column';
+                }
+                
+                container = nativeContainer;
+                
+                positionCleanup = () => {
+                    if (targetEl && targetEl.parentElement) {
+                        targetEl.style.position = originalElementStyle || '';
+                        // Remove native container if empty
+                        if (nativeContainer && nativeContainer.children.length === 0) {
+                            const positionKey = nativeContainer.getAttribute('data-apx-toast-position');
+                            if (positionKey) {
+                                _containerCache.delete(positionKey);
+                            }
+                            nativeContainer.remove();
+                        }
+                    }
+                };
+            } else {
+                // Default: get or create container for this position
+                container = this.getContainerForPosition(position, finalFlow);
+                
+                const updateContainerPosition = () => {
+                    const styles = this.calculatePosition(position, container);
+                    Object.assign(container.style, styles);
+                };
+                
+                updateContainerPosition();
+                
+                // For relative/anchored, listen to scroll/resize
+                if ((type === 'relative' || type === 'anchored') && position.element) {
+                    let rafId = null;
+                    let lastUpdate = 0;
+                    const throttleMs = 16; // ~60fps
+                    
+                    const throttledUpdate = () => {
+                        const now = Date.now();
+                        if (now - lastUpdate < throttleMs) {
+                            if (rafId) cancelAnimationFrame(rafId);
+                            rafId = requestAnimationFrame(() => {
+                                updateContainerPosition();
+                                lastUpdate = Date.now();
+                            });
+                        } else {
+                            updateContainerPosition();
+                            lastUpdate = now;
+                        }
+                    };
+                    
+                    // Find all scrollable parents
+                    const scrollableParents = findScrollableParents(position.element);
+                    
+                    // Listen to scroll on window and all scrollable parents
+                    window.addEventListener('scroll', throttledUpdate, { passive: true });
+                    window.addEventListener('resize', throttledUpdate, { passive: true });
+                    
+                    // Listen to scroll on all scrollable parent elements
+                    scrollableParents.forEach(parent => {
+                        parent.addEventListener('scroll', throttledUpdate, { passive: true });
+                    });
+                    
+                    // Watch for element removal
+                    const observer = new MutationObserver(() => {
+                        if (!position.element.parentElement) {
+                            ref.close('api');
+                        }
+                    });
+                    observer.observe(document.body, { childList: true, subtree: true });
+                    
+                    positionUpdateFn = updateContainerPosition;
+                    positionCleanup = () => {
+                        window.removeEventListener('scroll', throttledUpdate);
+                        window.removeEventListener('resize', throttledUpdate);
+                        scrollableParents.forEach(parent => {
+                            parent.removeEventListener('scroll', throttledUpdate);
+                        });
+                        observer.disconnect();
+                        if (rafId) cancelAnimationFrame(rafId);
+                    };
+                }
+            }
+        } else {
+            // String position - get or create container for this position
+            container = this.getContainerForPosition(position, finalFlow);
+        }
+        
+        // Append toast to the appropriate container
+        if (container) {
+            container.appendChild(toastEl);
+        } else {
+            // Fallback to default container
+            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();
+                
+                // Cleanup position listeners and restore styles
+                if (positionCleanup) {
+                    positionCleanup();
+                    positionCleanup = null;
+                }
+                
+                // 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);
+                    
+                    // Schedule garbage collection for unmanaged containers
+                    scheduleGarbageCollection();
+                    
+                    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;
+        // Use id from options if provided, otherwise use id from config, otherwise undefined (will be auto-generated)
+        if (!o.id && this.config.id) o.id = this.config.id;
+        return o;
+    }
+
+    /**
+     * Find or create a container for a specific position
+     * @param {Position} position
+     * @param {'up'|'down'} [flow] Flow direction (already determined, not 'auto')
+     * @param {boolean} [managed] Whether this container is managed by a manager (default: false)
+     * @returns {HTMLElement|null}
+     */
+    getContainerForPosition(position, flow, managed = false) {
+        if (!isBrowser) return null;
+        
+        const positionKey = serializePosition(position);
+        
+        // Flow should already be determined ('up' or 'down'), but fallback to auto if needed
+        const finalFlow = flow && flow !== 'auto' ? flow : determineFlow(position);
+        
+        // 1. Check memory cache
+        let c = _containerCache.get(positionKey);
+        
+        // 2. If not in cache, search in DOM by data attribute
+        if (!c && isBrowser) {
+            c = document.querySelector(`[data-apx-toast-position="${positionKey}"]`);
+            if (c) {
+                _containerCache.set(positionKey, c);
+            }
+        }
+        
+        // 3. If still not found, create new container
+        if (!c) {
+            c = createEl('div', 'APX-toast-container');
+            c.setAttribute('data-apx-toast-position', positionKey);
+            
+            // Mark as managed if created by a manager
+            if (managed) {
+                c.setAttribute('data-apx-toast-managed', 'true');
+            }
+            
+            // Determine position class (for CSS)
+            const posClass = typeof position === 'string' 
+                ? position 
+                : (position.type || 'bottom-right');
+            c.classList.add(`APX-toast-container--${posClass}`);
+            c.setAttribute('aria-live', String(this.config.ariaLive));
+            c.style.zIndex = String(this.config.zIndex);
+            c.style.gap = `${this.config.gap}px`;
+            
+            // Apply flow direction
+            c.style.flexDirection = finalFlow === 'up' ? 'column-reverse' : 'column';
+            
+            // Apply position styles if object position
+            if (typeof position === 'object' && position !== null) {
+                c.style.position = 'fixed';
+                const styles = this.calculatePosition(position, c);
+                Object.assign(c.style, styles);
+            }
+            
+            // Append to wrapper for clean DOM organization
+            const wrapper = getToastWrapper();
+            if (wrapper) {
+                wrapper.appendChild(c);
+            } else {
+                document.body.appendChild(c);
+            }
+            _containerCache.set(positionKey, c);
+        } else {
+            // Update flow direction if container exists (may be shared)
+            c.style.flexDirection = finalFlow === 'up' ? 'column-reverse' : 'column';
+            
+            // If container exists and is now managed, mark it
+            if (managed && !c.hasAttribute('data-apx-toast-managed')) {
+                c.setAttribute('data-apx-toast-managed', 'true');
+            }
+        }
+        
+        return c;
+    }
+
+    ensureContainer() {
+        if (this.container || !isBrowser) return;
+        
+        const position = this.config.position || 'bottom-right';
+        const flow = this.config.flow !== undefined ? this.config.flow : 'auto';
+        // Containers created by ensureContainer are managed
+        this.container = this.getContainerForPosition(position, flow, true);
+        this.applyContainerConfig();
+    }
+
+    applyContainerConfig() {
+        if (!this.container) return;
+        const position = this.config.position || 'bottom-right';
+        const pos = typeof position === 'string' ? position : (position.type || 'bottom-right');
+        
+        // Apply styles (these may be overridden by other managers sharing the container)
+        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 (only for string positions)
+        if (typeof position === 'string') {
+            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--${pos}`);
+        }
+        
+        // Apply container class if specified
+        if (this.config.containerClass) {
+            this.config.containerClass.split(' ').filter(Boolean).forEach(cls => {
+                this.container.classList.add(cls);
+            });
+        }
+        
+        // Apply offset (only for string positions)
+        if (typeof position === 'string') {
+            if (this.config.offset) {
+                const offset = `${this.config.offset}px`;
+                if (pos.includes('bottom')) this.container.style.bottom = offset;
+                else this.container.style.top = offset;
+                if (pos.includes('right')) this.container.style.right = offset;
+                else this.container.style.left = offset;
+            } else {
+                // Reset offset if not specified
+                if (pos.includes('bottom')) this.container.style.bottom = '';
+                else this.container.style.top = '';
+                if (pos.includes('right')) this.container.style.right = '';
+                else this.container.style.left = '';
+            }
+        } else if (typeof position === 'object' && position !== null) {
+            // For object positions, ensure container has position: fixed
+            this.container.style.position = 'fixed';
+        }
+    }
+
+    /**
+     * Calculate position for a container based on position config
+     * @param {Position} position
+     * @param {HTMLElement} containerEl
+     * @returns {{left?: string, top?: string, right?: string, bottom?: string}}
+     */
+    calculatePosition(position, containerEl) {
+        if (typeof position === 'string') {
+            // String positions are handled by container CSS
+            return {};
+        }
+        
+        if (typeof position === 'object' && position !== null) {
+            const type = position.type || (position.x || position.y ? 'sticky' : null);
+            
+            if (type === 'sticky' || (!type && (position.x || position.y))) {
+                // Sticky: fixed position relative to viewport
+                const styles = {};
+                if (position.x !== undefined) {
+                    if (position.x.startsWith('-')) {
+                        styles.right = position.x.substring(1);
+                    } else {
+                        styles.left = position.x;
+                    }
+                }
+                if (position.y !== undefined) {
+                    if (position.y.startsWith('-')) {
+                        styles.bottom = position.y.substring(1);
+                    } else {
+                        styles.top = position.y;
+                    }
+                }
+                return styles;
+            }
+            
+            if (type === 'relative' && position.element) {
+                // Relative: position relative to element with x/y offset
+                // Use fixed positioning, so getBoundingClientRect() is relative to viewport
+                const rect = position.element.getBoundingClientRect();
+                
+                // Parse x/y offsets (can be px, em, etc.)
+                const parseOffset = (val) => {
+                    if (!val) return 0;
+                    const num = parseFloat(val);
+                    if (val.includes('em')) {
+                        // Convert em to px (approximate: 1em = 16px)
+                        return num * 16;
+                    }
+                    return num;
+                };
+                
+                const offsetX = parseOffset(position.x || '0');
+                const offsetY = parseOffset(position.y || '0');
+                
+                const styles = {
+                    left: `${rect.left + offsetX}px`,
+                    top: `${rect.top + offsetY}px`
+                };
+                return styles;
+            }
+            
+            if (type === 'anchored' && position.element) {
+                // Anchored: position relative to element with placement
+                const rect = position.element.getBoundingClientRect();
+                const gap = position.gap || '1em';
+                
+                // Parse gap (can be px, em, etc.)
+                const parseGap = (val) => {
+                    const num = parseFloat(val);
+                    if (val.includes('em')) {
+                        return num * 16; // Approximate: 1em = 16px
+                    }
+                    return num;
+                };
+                
+                const gapPx = parseGap(gap);
+                const styles = {};
+                
+                // Normalize placement synonyms (above/below/before/after) to CSS values
+                const placement = normalizePlacement(position.placement);
+                
+                switch (placement) {
+                    case 'top':
+                        // Toast above element: bottom of toast = top of element - gap
+                        // bottom = viewport height - (element top - gap) = viewport height - element top + gap
+                        styles.bottom = `${window.innerHeight - rect.top + gapPx}px`;
+                        styles.left = `${rect.left}px`;
+                        break;
+                    case 'bottom':
+                        // Toast below element: top of toast = bottom of element + gap
+                        styles.top = `${rect.bottom + gapPx}px`;
+                        styles.left = `${rect.left}px`;
+                        break;
+                    case 'left':
+                        // Toast to the left: right of toast = left of element - gap
+                        styles.right = `${window.innerWidth - rect.left + gapPx}px`;
+                        styles.top = `${rect.top}px`;
+                        break;
+                    case 'right':
+                        // Toast to the right: left of toast = right of element + gap
+                        styles.left = `${rect.right + gapPx}px`;
+                        styles.top = `${rect.top}px`;
+                        break;
+                }
+                return styles;
+            }
+        }
+        
+        return {};
+    }
+}
+
+/**
+ * @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 };