@keenmate/pure-admin-core 2.4.0 → 2.5.0

package/snippets/alerts.html

@@ -6,42 +6,42 @@
 <!-- BASIC ALERTS -->
 
 <!-- Primary Alert -->
-<div class="pa-alert pa-alert--primary">
+<div class="pa-alert pa-alert--primary" role="alert">
   <strong>Primary!</strong> This is a primary alert — check it out!
 </div>
 
 <!-- Secondary Alert -->
-<div class="pa-alert pa-alert--secondary">
+<div class="pa-alert pa-alert--secondary" role="alert">
   <strong>Secondary!</strong> This is a secondary alert — check it out!
 </div>
 
 <!-- Success Alert -->
-<div class="pa-alert pa-alert--success">
+<div class="pa-alert pa-alert--success" role="alert">
   <strong>Success!</strong> This is a success alert — your operation completed successfully.
 </div>
 
 <!-- Danger Alert -->
-<div class="pa-alert pa-alert--danger">
+<div class="pa-alert pa-alert--danger" role="alert">
   <strong>Danger!</strong> This is a danger alert — something went wrong!
 </div>
 
 <!-- Warning Alert -->
-<div class="pa-alert pa-alert--warning">
+<div class="pa-alert pa-alert--warning" role="alert">
   <strong>Warning!</strong> This is a warning alert — please review before proceeding.
 </div>
 
 <!-- Info Alert -->
-<div class="pa-alert pa-alert--info">
+<div class="pa-alert pa-alert--info" role="alert">
   <strong>Info!</strong> This is an info alert — here's some useful information.
 </div>
 
 <!-- Light Alert -->
-<div class="pa-alert pa-alert--light">
+<div class="pa-alert pa-alert--light" role="alert">
   <strong>Light!</strong> This is a light alert — subtle but important.
 </div>
 
 <!-- Dark Alert -->
-<div class="pa-alert pa-alert--dark">
+<div class="pa-alert pa-alert--dark" role="alert">
   <strong>Dark!</strong> This is a dark alert — for high contrast messaging.
 </div>
 
@@ -49,7 +49,7 @@
 <!-- ALERTS WITH ICONS -->
 
 <!-- Success Alert with Icon -->
-<div class="pa-alert pa-alert--success">
+<div class="pa-alert pa-alert--success" role="alert">
   <span class="pa-alert__icon">✓</span>
   <div class="pa-alert__content">
     <strong>Success!</strong> Your changes have been saved successfully.
@@ -57,7 +57,7 @@
 </div>
 
 <!-- Danger Alert with Icon -->
-<div class="pa-alert pa-alert--danger">
+<div class="pa-alert pa-alert--danger" role="alert">
   <span class="pa-alert__icon">⚠</span>
   <div class="pa-alert__content">
     <strong>Error!</strong> Unable to process your request. Please try again.
@@ -65,7 +65,7 @@
 </div>
 
 <!-- Warning Alert with Icon -->
-<div class="pa-alert pa-alert--warning">
+<div class="pa-alert pa-alert--warning" role="alert">
   <span class="pa-alert__icon">!</span>
   <div class="pa-alert__content">
     <strong>Warning!</strong> Your session will expire in 5 minutes.
@@ -73,7 +73,7 @@
 </div>
 
 <!-- Info Alert with Icon -->
-<div class="pa-alert pa-alert--info">
+<div class="pa-alert pa-alert--info" role="alert">
   <span class="pa-alert__icon">ⓘ</span>
   <div class="pa-alert__content">
     <strong>Information!</strong> New features are now available in your account.
@@ -81,10 +81,17 @@
 </div>
 
 
-<!-- DISMISSIBLE ALERTS -->
+<!--
+DISMISSIBLE ALERTS
+--dismissible adds padding-inline-end so the text doesn't run under the
+close button. It's a spacing modifier, not a structural one — you still
+render __content + __close yourself, and wire dismissal via JS.
+__close uses inset-inline-end (logical) so it lands on the reading-end
+side in both LTR and RTL.
+-->
 
 <!-- Dismissible Success Alert -->
-<div class="pa-alert pa-alert--success pa-alert--dismissible">
+<div class="pa-alert pa-alert--success pa-alert--dismissible" role="alert">
   <div class="pa-alert__content">
     <strong>Well done!</strong> You successfully read this important alert message.
   </div>
@@ -94,7 +101,7 @@
 </div>
 
 <!-- Dismissible Danger Alert -->
-<div class="pa-alert pa-alert--danger pa-alert--dismissible">
+<div class="pa-alert pa-alert--danger pa-alert--dismissible" role="alert">
   <div class="pa-alert__content">
     <strong>Oh snap!</strong> Change a few things and try submitting again.
   </div>
@@ -104,19 +111,50 @@
 </div>
 
 
-<!-- ALERTS WITH ADDITIONAL CONTENT -->
+<!-- ALERTS WITH ADDITIONAL CONTENT
+
+When an alert has a separate title element and body content (paragraph,
+list, actions), use .pa-alert__heading for the title — never roll your
+own <strong> + <p> stack. The heading defaults to the alert's body
+font-size (compact); add --lg when you want the bigger, semibold-block
+treatment for alerts that need deliberate attention.
+
+NB: <strong> is still right for *inline* emphasis on a single-line
+alert ("<strong>Primary!</strong> This is a primary alert"). The
+heading element is for the case where the title sits on its own line
+above body content.
+-->
+
+<!-- Multi-line alert (compact heading — default size) -->
+<div class="pa-alert pa-alert--danger" role="alert">
+  <h4 class="pa-alert__heading">Validation failed</h4>
+  <p class="mb-0">Please fix the errors below.</p>
+</div>
+
+<!-- Same pattern, dismissible -->
+<div class="pa-alert pa-alert--danger pa-alert--dismissible" role="alert">
+  <h4 class="pa-alert__heading">Validation failed</h4>
+  <p class="mb-0">Please fix the errors below.</p>
+  <button class="pa-alert__close" onclick="dismissAlert(this)" aria-label="Close">
+    <span aria-hidden="true">×</span>
+  </button>
+</div>
 
-<!-- Alert with Heading and Paragraph -->
-<div class="pa-alert pa-alert--success">
-  <h4 class="pa-alert__heading">Success!</h4>
+<!-- Punchy heading — adds the --lg modifier for the bigger presentation -->
+<div class="pa-alert pa-alert--success" role="alert">
+  <h4 class="pa-alert__heading pa-alert__heading--lg">Success!</h4>
   <p>Aww yeah, you successfully read this important alert message. This example text is going to run a bit longer so that you can see how spacing within an alert works with this kind of content.</p>
   <hr>
   <p class="mb-0">Whenever you need to, be sure to use margin utilities to keep things nice and tidy.</p>
 </div>
 
-<!-- Alert with List -->
-<div class="pa-alert pa-alert--info">
-  <h4 class="pa-alert__heading">System Update</h4>
+<!-- Alert with List and Actions.
+     .pa-alert__actions sits below a thin divider with symmetric
+     padding — same separator pattern as .pa-toast__actions, so a
+     "System update / Update now" alert has the same visual weight
+     as a custom-action toast. -->
+<div class="pa-alert pa-alert--info" role="alert">
+  <h4 class="pa-alert__heading pa-alert__heading--lg">System Update</h4>
   <p>A new version of the application is available. This update includes:</p>
   <ul class="pa-alert__list">
     <li>Performance improvements</li>
@@ -130,63 +168,65 @@
 </div>
 
 
-<!-- OUTLINE ALERTS -->
+<!-- OUTLINE ALERTS — border-only, transparent background -->
 
 <!-- Outline Primary Alert -->
-<div class="pa-alert pa-alert--outline-primary">
+<div class="pa-alert pa-alert--outline-primary" role="alert">
   <strong>Primary Outline!</strong> This is a primary outline alert.
 </div>
 
 <!-- Outline Success Alert -->
-<div class="pa-alert pa-alert--outline-success">
+<div class="pa-alert pa-alert--outline-success" role="alert">
   <strong>Success Outline!</strong> This is a success outline alert.
 </div>
 
 <!-- Outline Danger Alert -->
-<div class="pa-alert pa-alert--outline-danger">
+<div class="pa-alert pa-alert--outline-danger" role="alert">
   <strong>Danger Outline!</strong> This is a danger outline alert.
 </div>
 
 <!-- Outline Warning Alert -->
-<div class="pa-alert pa-alert--outline-warning">
+<div class="pa-alert pa-alert--outline-warning" role="alert">
   <strong>Warning Outline!</strong> This is a warning outline alert.
 </div>
 
 <!-- Outline Info Alert -->
-<div class="pa-alert pa-alert--outline-info">
+<div class="pa-alert pa-alert--outline-info" role="alert">
   <strong>Info Outline!</strong> This is an info outline alert.
 </div>
 
+<!-- Note: no outline variants for secondary / light / dark. -->
+
 
 <!-- THEME COLOR ALERTS (color-1 through color-9) -->
 
 <!-- Theme Color 1 Alert (filled) -->
-<div class="pa-alert pa-alert--color-1">
+<div class="pa-alert pa-alert--color-1" role="alert">
   <strong>Color 1!</strong> Theme color slot 1 alert.
 </div>
 
 <!-- Theme Color 1 Alert (outline) -->
-<div class="pa-alert pa-alert--outline-color-1">
+<div class="pa-alert pa-alert--outline-color-1" role="alert">
   <strong>Color 1 Outline!</strong> Theme color slot 1 outline alert.
 </div>
 
-<!-- Pattern: pa-alert--color-{1-9} and pa-alert--outline-color-{1-9} -->
+<!-- Pattern: pa-alert--color-{1..9} (filled) and pa-alert--outline-color-{1..9} (outline). -->
 
 
 <!-- ALERT SIZES -->
 
 <!-- Small Alert -->
-<div class="pa-alert pa-alert--success pa-alert--sm">
+<div class="pa-alert pa-alert--success pa-alert--sm" role="alert">
   <span class="pa-alert__icon">✓</span> Saved
 </div>
 
 <!-- Default Alert -->
-<div class="pa-alert pa-alert--info">
+<div class="pa-alert pa-alert--info" role="alert">
   <span class="pa-alert__icon">ⓘ</span> Default size alert with standard padding
 </div>
 
 <!-- Large Alert -->
-<div class="pa-alert pa-alert--warning pa-alert--lg">
+<div class="pa-alert pa-alert--warning pa-alert--lg" role="alert">
   <span class="pa-alert__icon">!</span>
   <div class="pa-alert__content">
     <strong>Large Alert!</strong> This is a large alert with increased font size for better prominence.
@@ -194,24 +234,6 @@
 </div>
 
 
-<!-- COMPACT ALERTS -->
-
-<!-- Small Success Alert -->
-<div class="pa-alert pa-alert--success pa-alert--sm">
-  <span class="pa-alert__icon">✓</span> Saved
-</div>
-
-<!-- Small Warning Alert -->
-<div class="pa-alert pa-alert--warning pa-alert--sm">
-  <span class="pa-alert__icon">!</span> Pending
-</div>
-
-<!-- Small Danger Alert -->
-<div class="pa-alert pa-alert--danger pa-alert--sm">
-  <span class="pa-alert__icon">×</span> Failed
-</div>
-
-
 <!-- JAVASCRIPT FOR DISMISSIBLE ALERTS -->
 <script>
 function dismissAlert(button) {
@@ -231,63 +253,210 @@ function dismissAlert(button) {
 
 <!--
 ALERT CLASSES:
-- .pa-alert: Base alert class
-
-VARIANTS (solid background):
-- .pa-alert--primary: Blue alert
-- .pa-alert--secondary: Gray alert
-- .pa-alert--success: Green alert
-- .pa-alert--danger: Red alert
-- .pa-alert--warning: Yellow/orange alert
-- .pa-alert--info: Cyan alert
-- .pa-alert--light: Light gray alert
-- .pa-alert--dark: Dark alert
-
-OUTLINE VARIANTS (border only):
-- .pa-alert--outline-primary: Blue outline
-- .pa-alert--outline-success: Green outline
-- .pa-alert--outline-danger: Red outline
-- .pa-alert--outline-warning: Orange outline
-- .pa-alert--outline-info: Cyan outline
+- .pa-alert: Base alert — flex container, $spacing-sm gap, aligned flex-start
+
+VARIANTS (solid tint background):
+- .pa-alert--primary        accent-tinted
+- .pa-alert--secondary      muted/neutral
+- .pa-alert--success        green
+- .pa-alert--danger         red (also honours $alert-danger-text-transform —
+                            some themes set this to uppercase)
+- .pa-alert--warning        yellow/orange
+- .pa-alert--info           cyan/blue
+- .pa-alert--light          subtle light
+- .pa-alert--dark           subtle dark
+
+OUTLINE VARIANTS (transparent background, coloured border):
+- .pa-alert--outline-primary
+- .pa-alert--outline-success
+- .pa-alert--outline-danger
+- .pa-alert--outline-warning
+- .pa-alert--outline-info
+  (No outline variants for secondary / light / dark.)
 
 THEME COLOR VARIANTS (1-9):
-- .pa-alert--color-{1-9}: Filled theme color slot
-- .pa-alert--outline-color-{1-9}: Outline theme color slot
+- .pa-alert--color-{1-9}           filled theme colour slot
+- .pa-alert--outline-color-{1-9}   outline theme colour slot
 
 SIZES:
-- .pa-alert--sm: Small alert (reduced padding and font)
-- (default): Standard size
-- .pa-alert--lg: Large alert (increased padding and font)
+- .pa-alert--sm            $alert-padding-sm-{v,h} (0.5rem / 1rem),
+                            $alert-font-size-sm
+                            ($font-size-xs = 1.2rem)
+- (default)                $alert-padding-{v,h} (0.75rem / 1.25rem),
+                            $font-size-sm (1.4rem)
+- .pa-alert--lg            $alert-padding-lg-{v,h} (1rem / 1.5rem),
+                            $alert-font-size-lg
+                            ($font-size-base = 1.6rem)
+  V steps 0.5 → 0.75 → 1; H steps 1 → 1.25 → 1.5. Clean 0.25rem
+  increments. Themes can override $alert-padding-{v,h},
+  $alert-padding-{sm,lg}-{v,h}, and $alert-font-size-{sm,lg} in
+  variables/_components.scss to retune the scale.
+  (No --xs / --xl.)
 
 MODIFIERS:
-- .pa-alert--dismissible: Adds padding-right for close button
+- .pa-alert--dismissible   adds padding-inline-end so __close doesn't overlap
+                           content; you still render the button yourself.
+- .pa-alert--multiline     opts out of the default `align-items: center`
+                           and aligns flex children to flex-start. Use when
+                           you have an icon (.pa-alert__icon) next to a
+                           multi-line .pa-alert__content (heading + body +
+                           actions) — without it the icon would sit in the
+                           vertical middle of the content stack instead of
+                           at the top with the heading. Not needed for
+                           structural stacks without an icon (their children
+                           are flex-basis: 100% and each take their own
+                           row anyway).
 
 ELEMENTS:
-- .pa-alert__icon: Icon container (displays to left of content)
-- .pa-alert__content: Content wrapper (used with icon layout)
-- .pa-alert__heading: Alert title/heading (h4)
-- .pa-alert__list: List container (ul) for bullet points
-- .pa-alert__actions: Button container for action buttons
-- .pa-alert__close: Close/dismiss button
+- .pa-alert__icon      leading icon (flex-shrink: 0, font-size-base)
+- .pa-alert__content   content wrapper (flex: 1, min-width: 0). When you
+                       have an icon AND structured content (heading,
+                       paragraph, list, actions), wrap everything that
+                       isn't the icon inside __content — block-flow
+                       inside the wrapper handles vertical stacking.
+                       Drop the wrapper when there's no icon; direct
+                       children work too.
+- .pa-alert__heading   alert title on <h4>; semibold, defaults to the
+                       alert's body font-size (compact look). Add
+                       --lg to bump to font-size-lg for the louder,
+                       deliberate-read presentation. Spacing to the
+                       next element is the alert's flex gap (no
+                       built-in margin-bottom).
+- .pa-alert__list      <ul> inside the alert. Spacing to siblings is
+                       the alert's flex gap (no built-in margin).
+- .pa-alert__actions   button row below a thin divider (border-top +
+                       $spacing-base padding-top). Same separator
+                       pattern as .pa-toast__actions, so action-bearing
+                       alerts and toasts feel visually consistent.
+                       Always renders on its own row — sits at the
+                       bottom of the alert's content stack.
+- .pa-alert__close     absolutely positioned close button on the
+                       inline-end side (logical — RTL-aware).
+
+LAYOUT NOTE:
+The alert is `display: flex; flex-wrap: wrap` with `gap: $spacing-sm`
+and `align-items: center` (so an icon vertically centres against
+single-line __content). Structural children (__heading, __list,
+__actions, top-level <p>, <hr>) are forced to `flex-basis: 100%` so
+they each take their own row. Inline siblings (__icon, __content,
+bare text + <strong>) stay on the flex row.
+
+For the icon + multi-line __content case, add .pa-alert--multiline
+so the icon stops centring against the tall content stack and
+top-aligns with the heading instead.
+
+MARKUP SHAPES — WITH vs WITHOUT ICON:
+The alert has two valid shapes depending on whether you have an icon:
+
+- WITH icon: wrap the rest of the content in .pa-alert__content.
+  .pa-alert is a flex row, the icon is one flex item, __content is
+  the other flex item (flex: 1) that takes the remaining width.
+  Without the wrapper, every word/element next to the icon would
+  become its own flex item and the layout breaks.
+
+    <div class="pa-alert pa-alert--info">
+      <span class="pa-alert__icon">ⓘ</span>
+      <div class="pa-alert__content">
+        <strong>Title</strong> Body text…
+      </div>
+    </div>
+
+- WITHOUT icon: skip __content and put the structural children
+  directly inside .pa-alert. There's no icon to flow around, and
+  __heading / __list / __actions / top-level <p>, <hr> get
+  flex-basis: 100% so each takes its own row anyway. Wrapping them
+  in __content for "consistency" would just add an empty <div>
+  with no visual or semantic gain — and it'd actually move them
+  out of the `> p` / `> hr` selector reach, breaking the layout
+  rules.
+
+    <div class="pa-alert pa-alert--danger">
+      <h4 class="pa-alert__heading">Sync failed</h4>
+      <p class="mb-0">We couldn't reach the server.</p>
+      <div class="pa-alert__actions">…</div>
+    </div>
+
+Same alert system, two markup shapes — pick by whether there's an
+icon to flow around. Both are first-class.
+
+HEADING SIZE — DEFAULT vs --lg:
+- Default: <h4 class="pa-alert__heading">Title</h4> sits at the
+           alert's body font-size + semibold weight. Compact look,
+           good for status banners ("Validation failed", "Saved",
+           "Connection lost") and most title+paragraph cases.
+- --lg:    <h4 class="pa-alert__heading pa-alert__heading--lg">Title</h4>
+           bumps to font-size-lg for the louder, deliberate-read
+           treatment. Use for blocking errors, system updates,
+           quota warnings — alerts the user has to deal with.
+
+INLINE STYLE (no separate title element):
+For single-line alerts where the bold word is just inline emphasis,
+keep using <strong> directly — no heading element involved:
+  <strong>Primary!</strong> This is a primary alert.
+This is a different pattern from .pa-alert__heading. Don't add the
+heading class to inline <strong>s.
+
+AUTOMATIC BEHAVIOUR:
+- When the alert is the first or last child of .pa-card__body, its
+  top/bottom margin collapses — no extra classes needed.
+- <a> inside an alert inherits colour, is underlined, and drops the
+  underline on hover.
+- <hr> inside an alert gets a subtle thin border and tighter margins
+  for in-alert dividers.
+
+ACCESSIBILITY:
+- Add role="alert" on dynamic or dismissible alerts so screen readers
+  announce them as they appear.
 
 STRUCTURE PATTERNS:
 
-Simple alert:
-<div class="pa-alert pa-alert--success">
+Simple inline alert (one line, inline <strong> emphasis):
+<div class="pa-alert pa-alert--success" role="alert">
   <strong>Success!</strong> Message here.
 </div>
 
-Alert with icon:
-<div class="pa-alert pa-alert--success">
+Multi-line alert with default-size heading:
+<div class="pa-alert pa-alert--danger" role="alert">
+  <h4 class="pa-alert__heading">Validation failed</h4>
+  <p class="mb-0">Please fix the errors below.</p>
+</div>
+
+Multi-line alert with --lg heading (deliberate read):
+<div class="pa-alert pa-alert--info" role="alert">
+  <h4 class="pa-alert__heading pa-alert__heading--lg">System update</h4>
+  <p class="mb-0">A new version is available.</p>
+</div>
+
+Alert with icon — single-line content (icon + __content centred):
+<div class="pa-alert pa-alert--success" role="alert">
   <span class="pa-alert__icon">✓</span>
   <div class="pa-alert__content">
     <strong>Success!</strong> Message here.
   </div>
 </div>
 
-Alert with list and actions:
-<div class="pa-alert pa-alert--info">
-  <h4 class="pa-alert__heading">Title</h4>
+Alert with icon — multi-line content (use --multiline so the icon
+sticks to the top with the heading instead of centring against
+the whole stack):
+<div class="pa-alert pa-alert--info pa-alert--multiline" role="alert">
+  <span class="pa-alert__icon">ⓘ</span>
+  <div class="pa-alert__content">
+    <h4 class="pa-alert__heading pa-alert__heading--lg">Heads up</h4>
+    <p class="mb-0">Long body text spans multiple lines…</p>
+  </div>
+</div>
+
+Dismissible alert (no icon — no __content needed):
+<div class="pa-alert pa-alert--danger pa-alert--dismissible" role="alert">
+  <strong>Oh snap!</strong> Something went wrong.
+  <button class="pa-alert__close" aria-label="Close">
+    <span aria-hidden="true">×</span>
+  </button>
+</div>
+
+Alert with heading, list, and actions (--lg heading for prominence):
+<div class="pa-alert pa-alert--info" role="alert">
+  <h4 class="pa-alert__heading pa-alert__heading--lg">Title</h4>
   <p>Description text.</p>
   <ul class="pa-alert__list">
     <li>Item 1</li>
@@ -297,4 +466,10 @@ Alert with list and actions:
     <button class="pa-btn pa-btn--sm pa-btn--primary">Action</button>
   </div>
 </div>
+
+CALLOUT vs ALERT:
+- Alert:   full background tint or outline; supports --dismissible; fits
+           dynamic feedback, notifications, message banners.
+- Callout: documentation-style, left border only, no dismiss; use for
+           static tips/notes/warnings inside content areas.
 -->