@appius-fr/apx 2.4.0 → 2.5.2

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); }
+
+