@keenmate/pure-admin-core 2.3.6 → 2.5.0

package/snippets/toasts.html

@@ -3,17 +3,27 @@
      Pure Admin Visual Framework
      ================================ -->
 
-<!-- Note: Toast containers should be at body level in your layout -->
-<!-- Include these containers once in your main layout -->
-<div id="toast-container-top-right" class="pa-toast-container pa-toast-container--top-right"></div>
-<div id="toast-container-top-center" class="pa-toast-container pa-toast-container--top-center"></div>
-<div id="toast-container-top-left" class="pa-toast-container pa-toast-container--top-left"></div>
-<div id="toast-container-bottom-right" class="pa-toast-container pa-toast-container--bottom-right"></div>
+<!--
+Toast containers live at body level so toasts float above the layout.
+Include one container per position you plan to use (usually all six,
+once, in the app shell).
+
+IMPORTANT: positions use CSS logical property names (start/end), NOT
+left/right, so the UI mirrors correctly in RTL. --top-end is the
+most common "toast in the upper-right" slot in LTR.
+-->
+<div id="toast-container-top-end"      class="pa-toast-container pa-toast-container--top-end"></div>
+<div id="toast-container-top-center"   class="pa-toast-container pa-toast-container--top-center"></div>
+<div id="toast-container-top-start"    class="pa-toast-container pa-toast-container--top-start"></div>
+<div id="toast-container-bottom-end"   class="pa-toast-container pa-toast-container--bottom-end"></div>
 <div id="toast-container-bottom-center" class="pa-toast-container pa-toast-container--bottom-center"></div>
-<div id="toast-container-bottom-left" class="pa-toast-container pa-toast-container--bottom-left"></div>
+<div id="toast-container-bottom-start" class="pa-toast-container pa-toast-container--bottom-start"></div>
 
 
-<!-- TOAST STRUCTURE -->
+<!-- ================================
+     TOAST STRUCTURE — BORDERED VARIANTS
+     Card-background with a coloured border and tinted icon chip.
+     ================================ -->
 
 <!-- Primary Toast -->
 <div class="pa-toast pa-toast--primary pa-toast--show">
@@ -66,9 +76,60 @@
 </div>
 
 
-<!-- TOAST WITH PROGRESS BAR -->
+<!-- ================================
+     FILLED VARIANTS
+     Full-colour background; icon chip is a white-at-20%-alpha pill;
+     __actions separator goes to a 25% white line.
+     ================================ -->
+
+<!-- Filled Primary -->
+<div class="pa-toast pa-toast--filled-primary pa-toast--show">
+  <div class="pa-toast__icon">ℹ️</div>
+  <div class="pa-toast__content">
+    <div class="pa-toast__title">Heads up</div>
+    <div class="pa-toast__message">This is a filled primary toast.</div>
+  </div>
+  <button class="pa-toast__close" aria-label="Close">✕</button>
+</div>
+
+<!-- Filled Success -->
+<div class="pa-toast pa-toast--filled-success pa-toast--show">
+  <div class="pa-toast__icon">✓</div>
+  <div class="pa-toast__content">
+    <div class="pa-toast__title">Saved</div>
+    <div class="pa-toast__message">Changes stored successfully.</div>
+  </div>
+  <button class="pa-toast__close" aria-label="Close">✕</button>
+</div>
+
+<!-- Pattern: pa-toast--filled-{primary|success|danger|warning|info} and pa-toast--filled-color-{1..9} -->
+
+
+<!-- ================================
+     TOAST WITH ACTION BUTTONS
+     __actions sits under a separator — good fit for "Undo" on an
+     optimistic delete, "Retry" on a failed request, etc.
+     ================================ -->
+
+<div class="pa-toast pa-toast--info pa-toast--show">
+  <div class="pa-toast__icon">🗑️</div>
+  <div class="pa-toast__content">
+    <div class="pa-toast__title">Entry removed</div>
+    <div class="pa-toast__message">The record was deleted from the list.</div>
+    <div class="pa-toast__actions">
+      <button class="pa-btn pa-btn--xs pa-btn--secondary">Undo</button>
+    </div>
+  </div>
+  <button class="pa-toast__close" aria-label="Close">✕</button>
+</div>
+
+
+<!-- ================================
+     TOAST WITH AUTO-DISMISS PROGRESS BAR
+     __progress is absolutely positioned along the bottom; JS animates
+     its width from 100% → 0% over the toast's lifetime.
+     ================================ -->
 
-<!-- Toast with Auto-dismiss Progress -->
 <div class="pa-toast pa-toast--primary pa-toast--show">
   <div class="pa-toast__icon">ℹ</div>
   <div class="pa-toast__content">
@@ -80,11 +141,37 @@
 </div>
 
 
-<!-- JAVASCRIPT API -->
+<!-- ================================
+     THEME COLOR SLOT VARIANTS
+     ================================ -->
+
+<!-- Bordered theme-color-1 toast -->
+<div class="pa-toast pa-toast--color-1 pa-toast--show">
+  <div class="pa-toast__icon">●</div>
+  <div class="pa-toast__content">
+    <div class="pa-toast__title">Color 1</div>
+    <div class="pa-toast__message">Border and icon pulled from <code>--pa-color-1</code>.</div>
+  </div>
+  <button class="pa-toast__close" aria-label="Close">✕</button>
+</div>
+
+<!-- Pattern: pa-toast--color-{1..9} (bordered) and pa-toast--filled-color-{1..9} (filled) -->
+
+
+<!-- ================================
+     JAVASCRIPT API
+     The real implementation lives in demo/js/toast-service.js
+     (exposed as window.PureAdmin.toast). Below is a minimal
+     reference for embedding toasts without that service.
+     ================================ -->
+
 <script>
 // Create a toast notification
 function createToast(position, variant, title, message, duration = 5000, showProgress = false, persistent = false) {
+  // position is one of: top-end, top-start, top-center, bottom-end, bottom-start, bottom-center
   const container = document.getElementById(`toast-container-${position}`);
+  if (!container) return;
+
   const toastId = `toast-${Date.now()}-${Math.random()}`;
 
   const toast = document.createElement('div');
@@ -111,44 +198,105 @@ function createToast(position, variant, title, message, duration = 5000, showPro
 
   container.appendChild(toast);
 
-  // Show toast
-  setTimeout(() => {
-    toast.classList.add('pa-toast--show');
-  }, 10);
+  // Flip to show state on the next frame so the transition runs
+  setTimeout(() => toast.classList.add('pa-toast--show'), 10);
 
-  // Progress bar animation
+  // Progress bar animation — width transitions from 100% → 0% over the toast lifetime
   if (showProgress && !persistent) {
     const progress = toast.querySelector('.pa-toast__progress');
     if (progress) {
       progress.style.transition = `width ${duration}ms linear`;
-      setTimeout(() => {
-        progress.style.width = '0%';
-      }, 50);
+      setTimeout(() => { progress.style.width = '0%'; }, 50);
     }
   }
 
-  // Auto-dismiss (only if not persistent)
   if (!persistent) {
-    setTimeout(() => {
-      dismissToast(toastId);
-    }, duration);
+    setTimeout(() => dismissToast(toastId), duration);
   }
 }
 
-// Dismiss a toast
 function dismissToast(toastId) {
   const toast = document.getElementById(toastId);
   if (!toast) return;
-
   toast.classList.remove('pa-toast--show');
   toast.classList.add('pa-toast--hide');
-
-  setTimeout(() => {
-    toast.remove();
-  }, 300);
+  setTimeout(() => toast.remove(), 300);
 }
 
 // Usage examples:
-// createToast('top-right', 'success', 'Success', 'Operation completed!');
-// createToast('top-right', 'warning', 'Warning', 'Please review', 0, false, true); // Persistent
+// createToast('top-end', 'success', 'Saved', 'Operation completed.');
+// createToast('top-end', 'warning', 'Heads up', 'Please review.', 0, false, true); // persistent
 </script>
+
+
+<!-- ================================
+     COMPONENT REFERENCE
+     ================================ -->
+
+<!--
+CONTAINERS:
+- .pa-toast-container                          — fixed, pointer-events: none so toasts through
+- .pa-toast-container--top-end                 — upper inline-end (right in LTR, left in RTL)
+- .pa-toast-container--top-start               — upper inline-start (left in LTR, right in RTL)
+- .pa-toast-container--top-center              — upper centre (translateX)
+- .pa-toast-container--bottom-end              — lower inline-end
+- .pa-toast-container--bottom-start            — lower inline-start
+- .pa-toast-container--bottom-center           — lower centre
+
+(No --*-right / --*-left classes exist. Logical props mirror in RTL.)
+
+TOAST ITEM:
+- .pa-toast             — base toast (card-bg + border + shadow); starts hidden
+- .pa-toast--show       — animation end state: opacity 1, transform: 0 (apply via JS)
+- .pa-toast--hide       — animation exit state: opacity 0, transform: off-axis
+
+BORDERED VARIANTS (coloured border + tinted icon chip):
+- .pa-toast--primary / --success / --danger / --warning / --info
+- .pa-toast--color-{1..9}                     — theme colour slots
+
+FILLED VARIANTS (full-colour background):
+- .pa-toast--filled-primary / -success / -danger / -warning / -info
+- .pa-toast--filled-color-{1..9}
+
+SUB-ELEMENTS:
+- .pa-toast__icon      — leading chip (48×48 default, flex-centered)
+- .pa-toast__content   — flex: 1 column; hosts __title + __message (+ __actions)
+- .pa-toast__title     — bold, text-color-1
+- .pa-toast__message   — text-color-2, line-height-base
+- .pa-toast__actions   — optional button row under a 1px separator (Undo/Retry/etc.)
+- .pa-toast__close     — 32×32 trailing close button (inherits color)
+- .pa-toast__progress  — absolute bar along the bottom edge; JS animates width → 0
+
+RESPONSIVE:
+- Below $mobile-breakpoint the container goes full-width (inset-inline: $spacing-md)
+  and centre positions drop their translateX — so toasts are readable on phones.
+
+PATTERNS:
+
+Bordered toast:
+<div class="pa-toast pa-toast--success pa-toast--show">
+  <div class="pa-toast__icon">✓</div>
+  <div class="pa-toast__content">
+    <div class="pa-toast__title">Saved</div>
+    <div class="pa-toast__message">Entry stored.</div>
+  </div>
+  <button class="pa-toast__close" aria-label="Close">✕</button>
+</div>
+
+Toast with Undo action:
+<div class="pa-toast pa-toast--info pa-toast--show">
+  <div class="pa-toast__content">
+    <div class="pa-toast__title">Entry removed</div>
+    <div class="pa-toast__actions">
+      <button class="pa-btn pa-btn--xs pa-btn--secondary">Undo</button>
+    </div>
+  </div>
+  <button class="pa-toast__close" aria-label="Close">✕</button>
+</div>
+
+Toast with progress bar:
+<div class="pa-toast pa-toast--primary pa-toast--show">
+  …
+  <div class="pa-toast__progress w-100" style="transition: width 5000ms linear;"></div>
+</div>
+-->

package/snippets/tooltips.html

@@ -89,18 +89,25 @@
 <span class="pa-tooltip pa-tooltip--color-9" data-tooltip="Color 9">Color 9</span>
 
 
-<!-- CURSOR MODIFIERS -->
+<!-- CURSOR / UNDERLINE MODIFIERS -->
 
-<!-- Default tooltip (inherits parent cursor - good for clickable elements like buttons, tabs) -->
+<!-- Default tooltip (inherits parent cursor — good for clickable elements like buttons, tabs) -->
 <button class="pa-btn pa-btn--primary pa-tooltip" data-tooltip="Click to view">
   Clickable Item
 </button>
 
-<!-- Help cursor tooltip (question mark cursor - good for informational hints) -->
+<!-- Help cursor tooltip (question-mark cursor — good for informational hints) -->
 <span class="pa-tooltip pa-tooltip--help" data-tooltip="This provides helpful information">
   What's this?
 </span>
 
+<!-- Keyword tooltip (dotted underline + help cursor — good for inline term explanations) -->
+<p>
+  The system uses
+  <span class="pa-tooltip pa-tooltip--keyword" data-tooltip="JSON Web Tokens: a signed claim used for stateless auth">JWT</span>
+  for session authentication.
+</p>
+
 
 <!-- COLORED TOOLTIPS WITH POSITIONS -->
 
@@ -172,6 +179,42 @@
 </span>
 
 
+<!-- ================================
+     JS-PORTAL TOOLTIP (.pa-tooltip-floating)
+     A separate class for tooltips rendered into the body by JS (the
+     tooltips-popovers.js script does this automatically). Use when the
+     trigger sits inside an overflow: hidden container — a CSS tooltip
+     would be clipped; the portal-rendered one escapes the parent.
+
+     Consumers don't author this markup directly — it's emitted by
+     the tooltip JS at runtime. But for framework wrappers (Svelte/Vue/
+     React) that render their own portal tooltip, match this shape:
+     ================================ -->
+
+<div class="pa-tooltip-floating" role="tooltip">
+  Tooltip text here
+</div>
+
+<!-- Floating tooltip with colour / multiline variants -->
+<div class="pa-tooltip-floating pa-tooltip--primary" role="tooltip">Primary</div>
+<div class="pa-tooltip-floating pa-tooltip--success" role="tooltip">Success</div>
+<div class="pa-tooltip-floating pa-tooltip--warning" role="tooltip">Warning</div>
+<div class="pa-tooltip-floating pa-tooltip--danger"  role="tooltip">Danger</div>
+<div class="pa-tooltip-floating pa-tooltip--color-3" role="tooltip">Theme color 3</div>
+
+<div class="pa-tooltip-floating pa-tooltip--multiline" role="tooltip">
+  Long multi-line content that wraps inside the tooltip box.
+</div>
+
+<!--
+If you attach the portal tooltip to an element that ALSO has a
+pa-tooltip CSS class, add pa-tooltip--floating to the element to
+suppress the CSS pseudo tooltip — otherwise you get two tooltips
+stacked over the trigger.
+-->
+<span class="pa-tooltip pa-tooltip--floating" data-tooltip="handled by JS">Trigger</span>
+
+
 <!-- POPOVERS - Basic -->
 
 <!-- Popovers are click-triggered rich content overlays
@@ -394,86 +437,161 @@ document.addEventListener('content-loaded', function() {
 </script>
 
 
-<!-- AVAILABLE CLASSES REFERENCE -->
-<!--
-TOOLTIPS:
-- pa-tooltip (base class, top position by default)
-
-POSITIONS (RTL-aware):
-- pa-tooltip--end (inline-end: right in LTR, left in RTL)
-- pa-tooltip--bottom
-- pa-tooltip--start (inline-start: left in LTR, right in RTL)
-
-VARIANTS:
-- pa-tooltip--primary (primary colored background)
-- pa-tooltip--success (success colored background)
-- pa-tooltip--warning (warning colored background)
-- pa-tooltip--danger (danger colored background)
-- pa-tooltip--color-1 through pa-tooltip--color-9 (theme-defined colors)
-
-MULTILINE:
-- pa-tooltip--multiline (allows text wrapping)
-
-POPOVERS:
-- pa-popover (base container)
-
-POSITIONING (use data-placement attribute, RTL-aware):
-- data-placement="top" (default)
-- data-placement="end" (inline-end: right in LTR, left in RTL)
-- data-placement="bottom"
-- data-placement="start" (inline-start: left in LTR, right in RTL)
-
-SIZES:
-- pa-popover--sm (small)
-- pa-popover--lg (large)
-
-ALIGNMENT:
-- pa-popover--center (centered body text)
-- pa-popover--end (end-aligned body text)
-
-COMPONENTS:
-- pa-popover__trigger (button/trigger element)
-- pa-popover__content (popover container)
-- pa-popover__header (header section)
-- pa-popover__body (content section)
-- pa-popover__close (close button)
-
-FLOATING UI FEATURES:
-- Automatic collision detection
-- Auto-flipping when near viewport edges
-- Smart shift to stay visible
-- No manual positioning needed
-- autoUpdate for automatic repositioning on scroll/resize
--->
+<!-- ================================
+     COMPONENT REFERENCE
+     ================================ -->
 
-<!-- IMPLEMENTATION NOTES -->
 <!--
-REQUIREMENTS:
-- @floating-ui/core and @floating-ui/dom must be loaded
-- tooltips-popovers.js handles all initialization
-- SCSS styles in core-components/_tooltips.scss
-
-FLOATING UI BENEFITS:
-- Tooltips never go off-screen
-- Auto-flip to opposite side if no space
-- Shift horizontally/vertically to stay visible
-- Works with scrolling and resizing
-- Position is calculated dynamically
-
-TOOLTIP BEHAVIOR:
-- Show on mouseenter and focus
-- Hide on mouseleave and blur
+CSS TOOLTIP (.pa-tooltip):
+Pure CSS pseudo-element tooltip — no JS needed for the basic effect.
+Text comes from the `data-tooltip` attribute on the trigger.
+
+Position (logical, RTL-aware):
+- .pa-tooltip           default (top)
+- .pa-tooltip--bottom   below the trigger
+- .pa-tooltip--end      inline-end (right in LTR, left in RTL)
+- .pa-tooltip--start    inline-start (left in LTR, right in RTL)
+
+Colour variants (colour the bubble + arrow):
+- .pa-tooltip--primary / --success / --warning / --danger
+  (--warning uses dark text automatically because yellow-on-white is
+   low-contrast; the others keep --pa-tooltip-text.)
+- .pa-tooltip--color-{1..9}                 theme colour slots
+
+Modifiers:
+- .pa-tooltip--multiline   allow text wrapping (fixed width); default
+                           is single-line with ellipsis overflow.
+- .pa-tooltip--help        cursor: help (? cursor) — informational hints
+- .pa-tooltip--keyword     dotted underline + help cursor — for
+                           term-explanation inline in prose.
+- .pa-tooltip--floating    suppress the CSS pseudo tooltip — used when
+                           a JS portal tooltip (.pa-tooltip-floating)
+                           is showing over the same trigger, to prevent
+                           double tooltips.
+
+Auto-flip (applied at runtime by tooltips-popovers.js when the
+tooltip would overflow the viewport — not typically authored):
+- .pa-tooltip--auto-flip-top     shifted to show above after being
+                                 authored below
+- .pa-tooltip--auto-flip-bottom  inverse
+- .pa-tooltip--auto-flip-start   inverse of --end
+- .pa-tooltip--auto-flip-end     inverse of --start
+  (These are CSS classes the JS toggles dynamically. Safe to author
+   your tooltip with whatever side you prefer and let the JS handle
+   collisions.)
+
+
+JS PORTAL TOOLTIP (.pa-tooltip-floating):
+Separate class for a tooltip element appended to the body by JS. Used
+when the trigger lives inside an `overflow: hidden` ancestor that
+would clip the pseudo-element tooltip. Emitted automatically by
+tooltips-popovers.js; framework wrappers should match this structure:
+
+  <div class="pa-tooltip-floating" role="tooltip">Tooltip text</div>
+
+Variants (compose with the base class):
+- .pa-tooltip--multiline
+- .pa-tooltip--primary / --success / --warning / --danger
+- .pa-tooltip--color-{1..9}
+
+(When using .pa-tooltip-floating against a trigger that also has
+pa-tooltip, add .pa-tooltip--floating to the trigger to hide the
+CSS pseudo — otherwise both tooltips render.)
+
+
+POPOVER (.pa-popover):
+Click-triggered rich-content container. JS-positioned via Floating UI;
+shown/hidden by toggling `data-show` on `__content`.
+
+Structure:
+  .pa-popover[data-placement="top|bottom|start|end"]
+    button.pa-popover__trigger         circular trigger button
+    .pa-popover__content[data-show]    hidden without data-show
+      .pa-popover__header
+        <h4>Title</h4>                 header expects <h4> (styled)
+        button.pa-popover__close       × close button
+      .pa-popover__body
+        <p>, <ul>/<ol>, <a>, <code>    all auto-styled (see below)
+
+Positioning:
+- data-placement="top"      (default)
+- data-placement="bottom"
+- data-placement="end"      inline-end (RTL-aware)
+- data-placement="start"    inline-start (RTL-aware)
+  (Popovers use an attribute, not a class modifier, because positioning
+  is entirely JS-driven — there's no CSS fallback.)
+
+Sizes:
+- .pa-popover--sm
+- (default)
+- .pa-popover--lg
+
+Body alignment:
+- (default)             text-align: start
+- .pa-popover--center   text-align: center on body
+- .pa-popover--end      text-align: end on body (RTL-aware)
+
+Auto-styled inside .pa-popover__body:
+- <p>     spaced paragraphs; last-child bottom margin collapsed
+- <a>     accent colour, underlined, darker on hover
+- <ul>, <ol>   spacing-sm vertical margin, padding-inline-start
+- <code>  monospace, tinted background, small padding
+
+
+FLOATING UI CONTRACT:
+Both .pa-tooltip-floating rendering and .pa-popover positioning are
+driven by @floating-ui/core + @floating-ui/dom. Features the demo
+bundle wires up via tooltips-popovers.js:
+- computePosition() with offset + flip + shift middleware
+- autoUpdate() so tooltips / popovers reposition on scroll + resize
 - Single shared tooltip element (performance)
-- Positioned using computePosition() with flip, shift, offset middleware
-
-POPOVER BEHAVIOR:
-- Show on trigger click
-- Hide on close button click or outside click
-- Use data-placement attribute for positioning (not CSS classes)
-- Positioned using computePosition() with flip, shift, offset middleware
-- autoUpdate ensures automatic repositioning on scroll/resize
-- Uses data-show attribute for visibility control
-- Absolute positioning relative to trigger
 - Only one popover open at a time
-- Proper cleanup of autoUpdate on hide
+- Outside-click and Escape close popovers; close-button does the same
+
+JAVASCRIPT API:
+tooltips-popovers.js exposes:
+  window.PureAdminTooltips.init()           (re-scan DOM)
+  window.PureAdminTooltips.initTooltips()
+  window.PureAdminTooltips.initPopovers()
+  window.PureAdminTooltips.showTooltip(el)
+  window.PureAdminTooltips.hideTooltip()
+
+Call init() after dynamically-inserted content to register new
+triggers. Demo example:
+  document.addEventListener('content-loaded', () => {
+    window.PureAdminTooltips.init();
+  });
+
+
+STRUCTURE PATTERNS:
+
+Simple tooltip:
+<span class="pa-tooltip" data-tooltip="Hello">Hover me</span>
+
+Tooltip on an icon button (bottom, coloured):
+<button class="pa-btn pa-btn--xs pa-btn--icon-only pa-btn--danger pa-tooltip pa-tooltip--bottom" data-tooltip="Delete user">
+  🗑️
+</button>
+
+Keyword tooltip inline in prose (dotted underline):
+<p>
+  Ask for a
+  <span class="pa-tooltip pa-tooltip--keyword" data-tooltip="Web Worker">WW</span>
+  when you need background threads.
+</p>
+
+Rich popover:
+<div class="pa-popover" data-placement="bottom">
+  <button class="pa-popover__trigger">?</button>
+  <div class="pa-popover__content">
+    <div class="pa-popover__header">
+      <h4>Help</h4>
+      <button class="pa-popover__close">×</button>
+    </div>
+    <div class="pa-popover__body">
+      <p>Rich popover with a <a href="#">link</a> and a list:</p>
+      <ul><li>Item A</li><li>Item B</li></ul>
+    </div>
+  </div>
+</div>
 -->