maverick-wave 5.16.0 → 5.19.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "maverick-wave",
-  "version": "5.16.0",
+  "version": "5.19.0",
   "config": {
-    "version_short": "5.16"
+    "version_short": "5.19"
   },
   "description": "A lightweight, modern CSS framework for building responsive websites with elegance and speed.",
   "main": "src/js/main.js",

package/release.sh

@@ -4,6 +4,11 @@ echo "## extract version from package.json"
 VERSION=$(npm pkg get version --workspaces=false | tr -d \")
 echo "## checkout release branch and grab changes from main"
 git checkout release && git merge main --no-commit
+echo "## point the README CDN snippets at this version"
+# The skills pin a major range and need no bump; the README is the place the
+# exact-version advice belongs, and it is the one that kept going stale - 5.0.0
+# shipped with six snippets still on 4.28.0.
+sed -i '' -E "s|maverick-wave@[0-9]+\.[0-9]+\.[0-9]+|maverick-wave@${VERSION}|g" README.md
 echo "## make a new release"
 npm run build && npm run prepack
 echo "## add all changes and push it"

package/scripts/verify.js

@@ -155,22 +155,35 @@ for (const f of ['maverick-wave.min.css', 'maverick-wave.min.js']) {
 }
 
 // --- 5: pinned CDN version -------------------------------------------------
-// Every jsDelivr snippet in the docs pins a version, which is the right advice
-// and the reason it goes stale: 5.0.0 shipped with six snippets still on 4.28.0.
+// Two rules, because the two places are read at different times. The README is
+// where someone decides how to pull the framework in, so it names the exact
+// version - release.sh rewrites it, and this catches a bump that went around the
+// script. The skills are installed outside this repo and never get that rewrite,
+// so they carry a major range; an exact pin there is stale the day the next
+// version ships and nobody notices, which is how 5.0.0 went out with six
+// snippets still on 4.28.0.
 
 const { version } = require(path.join(ROOT, 'package.json'));
+const EXACT_PIN = /maverick-wave@([0-9]+\.[0-9]+\.[0-9]+)/g;
 
-for (const p of [path.join(ROOT, 'README.md'), ...DOCS]) {
+const readme = read(path.join(ROOT, 'README.md'));
+if (readme) {
+  for (const v of new Set(
+    all(readme, EXACT_PIN).filter((v) => v !== version)
+  )) {
+    errors.push(
+      `stale CDN pin in README.md: maverick-wave@${v} - package.json is ${version}`
+    );
+  }
+}
+
+const major = version.split('.')[0];
+for (const p of DOCS) {
   const md = read(p);
   if (!md) continue;
-  const stale = new Set(
-    all(md, /maverick-wave@([0-9]+\.[0-9]+\.[0-9]+)/g).filter(
-      (v) => v !== version
-    )
-  );
-  for (const v of stale) {
+  for (const v of new Set(all(md, EXACT_PIN))) {
     errors.push(
-      `stale CDN pin in ${path.relative(ROOT, p)}: maverick-wave@${v} - package.json is ${version}`
+      `exact CDN pin in ${path.relative(ROOT, p)}: maverick-wave@${v} - a skill carries @${major}, so it never goes stale`
     );
   }
 }

package/src/partials/get-started-container.html

@@ -276,9 +276,11 @@ body {
           <code>DOMContentLoaded</code> and writes straight into the DOM - in a
           SPA everything rendered afterwards stays uninitialized, and the class
           toggles happen behind change detection. Rebuild the behaviors in
-          components; the state classes (<code>active</code>, <code>open</code>,
-          <code>mw-modal-open</code>, <code>mw-selected</code>) are the whole
-          contract.
+          components; the state classes (<code>mw-active</code>,
+          <code>open</code>, <code>mw-selected</code>) are the whole contract. A
+          modal is the exception - write it as a
+          <code>&lt;dialog class="mw-modal"&gt;</code> and the element brings
+          Escape, the focus trap and the scroll lock with it.
         </p>
         <p>
           Alternatively, use the CDN link directly in

package/src/partials/header-container.html

@@ -31,7 +31,7 @@
   <!-- Theme Toggle -->
   <button
     type="button"
-    class="mw-theme-toggle mw-ml-5"
+    class="mw-theme-toggle mw-header-keep mw-ml-5"
     aria-label="Toggle light and dark theme"
   >
     <div class="mw-theme-toggle-slider">
@@ -53,10 +53,20 @@
     <i class="fas fa-palette"></i>
   </button>
 
+  <!-- Login Button - mw-header-keep, so it is there before the bar is -->
+  <button
+    type="button"
+    class="mw-login-btn mw-header-keep"
+    id="login-button"
+    aria-label="Log in"
+  >
+    <i class="fas fa-lock"></i>
+  </button>
+
   <!-- Burger Menu Button -->
   <button
     type="button"
-    class="mw-menu-btn"
+    class="mw-menu-btn mw-header-keep"
     aria-label="Menu"
     aria-expanded="false"
     aria-controls="mw-main-nav"

package/src/partials/modals-container.html

@@ -1,22 +1,25 @@
 <h3 class="mw-section-subtitle">Simple Modals</h3>
 <p class="mw-text-muted mw-mb-6">
-  JavaScript-controlled modals - perfect for e.g. Angular apps using class
-  toggling.
+  A <code>&lt;dialog&gt;</code> carrying the same <code>mw-modal</code> classes.
+  Escape, the focus trap, the inert page behind it and the body scroll lock come
+  from the element - only opening it needs a line of script. The older
+  <code>mw-modal-overlay</code> div is still styled for markup that predates
+  this.
 </p>
 
 <!-- Size Triggers -->
 <h4 class="mw-mb-3">Modal Sizes</h4>
 <div class="mw-grid-4 mw-mb-8">
-  <button onclick="openModal('modal-sm')" class="mw-btn mw-btn-outline">
+  <button data-mw-modal="modal-sm" class="mw-btn mw-btn-outline">
     Small Modal
   </button>
-  <button onclick="openModal('modal-default')" class="mw-btn mw-btn-outline">
+  <button data-mw-modal="modal-default" class="mw-btn mw-btn-outline">
     Default Modal
   </button>
-  <button onclick="openModal('modal-lg')" class="mw-btn mw-btn-outline">
+  <button data-mw-modal="modal-lg" class="mw-btn mw-btn-outline">
     Large Modal
   </button>
-  <button onclick="openModal('modal-xl')" class="mw-btn mw-btn-outline">
+  <button data-mw-modal="modal-xl" class="mw-btn mw-btn-outline">
     XL Modal
   </button>
 </div>
@@ -24,212 +27,160 @@
 <!-- Example Triggers -->
 <h4 class="mw-mb-3">Examples</h4>
 <div class="mw-grid-2 mw-mb-8">
-  <button onclick="openModal('modal-form')" class="mw-btn mw-btn-primary">
+  <button data-mw-modal="modal-form" class="mw-btn mw-btn-primary">
     Open Form Modal
   </button>
   <button data-mw-modal="modal-confirm" class="mw-btn mw-btn-secondary">
-    Open Confirmation (&lt;dialog&gt;)
+    Open Delete Confirmation
   </button>
 </div>
 
+<!-- The close buttons carry no handler - the framework script closes the dialog
+     they sit in - and closedby="any" dismisses it on a backdrop click, so there
+     is no mw-modal-backdrop element either. `data-mw-modal` on a trigger opens
+     the dialog with that id. -->
 <!-- Small Modal -->
-<div id="modal-sm" class="mw-modal-overlay">
-  <div class="mw-modal mw-modal-sm">
-    <div class="mw-modal-header">
-      <h4 class="mw-modal-title">Small Modal</h4>
-      <button onclick="closeModal('modal-sm')" class="mw-modal-close">
-        &#120299;
-      </button>
-    </div>
-    <div class="mw-modal-body">
-      <p class="mw-text-muted">
-        Max-width <strong>370px</strong>. Good for short confirmations or
-        alerts.
-      </p>
-    </div>
-    <div class="mw-modal-footer">
-      <button onclick="closeModal('modal-sm')" class="mw-btn mw-btn-outline">
-        Close
-      </button>
-    </div>
+<dialog id="modal-sm" class="mw-modal mw-modal-sm" closedby="any">
+  <div class="mw-modal-header">
+    <h4 class="mw-modal-title">Small Modal</h4>
+    <button class="mw-modal-close">&#120299;</button>
   </div>
-  <div class="mw-modal-backdrop" onclick="closeModal('modal-sm')"></div>
-</div>
+  <div class="mw-modal-body">
+    <p class="mw-text-muted">
+      Max-width <strong>370px</strong>. Good for short confirmations or alerts.
+    </p>
+  </div>
+  <div class="mw-modal-footer">
+    <button class="mw-modal-close mw-btn mw-btn-outline">Close</button>
+  </div>
+</dialog>
 
 <!-- Default Modal -->
-<div id="modal-default" class="mw-modal-overlay">
-  <div class="mw-modal">
-    <div class="mw-modal-header">
-      <h4 class="mw-modal-title">Default Modal</h4>
-      <button onclick="closeModal('modal-default')" class="mw-modal-close">
-        &#120299;
-      </button>
-    </div>
-    <div class="mw-modal-body">
-      <p class="mw-text-muted">
-        Max-width <strong>520px</strong>. The default size - fits most use
-        cases.
-      </p>
-    </div>
-    <div class="mw-modal-footer">
-      <button
-        onclick="closeModal('modal-default')"
-        class="mw-btn mw-btn-outline"
-      >
-        Cancel
-      </button>
-      <button
-        onclick="closeModal('modal-default')"
-        class="mw-btn mw-btn-primary"
-      >
-        Confirm
-      </button>
-    </div>
+<dialog id="modal-default" class="mw-modal" closedby="any">
+  <div class="mw-modal-header">
+    <h4 class="mw-modal-title">Default Modal</h4>
+    <button class="mw-modal-close">&#120299;</button>
   </div>
-  <div class="mw-modal-backdrop" onclick="closeModal('modal-default')"></div>
-</div>
+  <div class="mw-modal-body">
+    <p class="mw-text-muted">
+      Max-width <strong>520px</strong>. The default size - fits most use cases.
+    </p>
+  </div>
+  <div class="mw-modal-footer">
+    <button class="mw-modal-close mw-btn mw-btn-outline">Cancel</button>
+    <button class="mw-modal-close mw-btn mw-btn-primary">Confirm</button>
+  </div>
+</dialog>
 
 <!-- Large Modal -->
-<div id="modal-lg" class="mw-modal-overlay">
-  <div class="mw-modal mw-modal-lg">
-    <div class="mw-modal-header">
-      <h4 class="mw-modal-title">Large Modal</h4>
-      <button onclick="closeModal('modal-lg')" class="mw-modal-close">
-        &#120299;
-      </button>
-    </div>
-    <div class="mw-modal-body">
-      <p class="mw-text-muted">
-        Max-width <strong>720px</strong>. More room for richer content or forms.
-      </p>
-    </div>
-    <div class="mw-modal-footer">
-      <button onclick="closeModal('modal-lg')" class="mw-btn mw-btn-outline">
-        Cancel
-      </button>
-      <button onclick="closeModal('modal-lg')" class="mw-btn mw-btn-primary">
-        Confirm
-      </button>
-    </div>
+<dialog id="modal-lg" class="mw-modal mw-modal-lg" closedby="any">
+  <div class="mw-modal-header">
+    <h4 class="mw-modal-title">Large Modal</h4>
+    <button class="mw-modal-close">&#120299;</button>
   </div>
-  <div class="mw-modal-backdrop" onclick="closeModal('modal-lg')"></div>
-</div>
+  <div class="mw-modal-body">
+    <p class="mw-text-muted">
+      Max-width <strong>720px</strong>. More room for richer content or forms.
+    </p>
+  </div>
+  <div class="mw-modal-footer">
+    <button class="mw-modal-close mw-btn mw-btn-outline">Cancel</button>
+    <button class="mw-modal-close mw-btn mw-btn-primary">Confirm</button>
+  </div>
+</dialog>
 
 <!-- XL Modal -->
-<div id="modal-xl" class="mw-modal-overlay">
-  <div class="mw-modal mw-modal-xl">
-    <div class="mw-modal-header">
-      <h4 class="mw-modal-title">XL Modal</h4>
-      <button onclick="closeModal('modal-xl')" class="mw-modal-close">
-        &#120299;
-      </button>
-    </div>
-    <div class="mw-modal-body">
-      <p class="mw-text-muted">
-        Max-width <strong>960px</strong>. Use for detail views, data tables, or
-        complex layouts.
-      </p>
-    </div>
-    <div class="mw-modal-footer">
-      <button onclick="closeModal('modal-xl')" class="mw-btn mw-btn-outline">
-        Cancel
-      </button>
-      <button onclick="closeModal('modal-xl')" class="mw-btn mw-btn-primary">
-        Confirm
-      </button>
-    </div>
+<dialog id="modal-xl" class="mw-modal mw-modal-xl" closedby="any">
+  <div class="mw-modal-header">
+    <h4 class="mw-modal-title">XL Modal</h4>
+    <button class="mw-modal-close">&#120299;</button>
   </div>
-  <div class="mw-modal-backdrop" onclick="closeModal('modal-xl')"></div>
-</div>
+  <div class="mw-modal-body">
+    <p class="mw-text-muted">
+      Max-width <strong>960px</strong>. Use for detail views, data tables, or
+      complex layouts.
+    </p>
+  </div>
+  <div class="mw-modal-footer">
+    <button class="mw-modal-close mw-btn mw-btn-outline">Cancel</button>
+    <button class="mw-modal-close mw-btn mw-btn-primary">Confirm</button>
+  </div>
+</dialog>
 
 <!-- Form Modal -->
-<div id="modal-form" class="mw-modal-overlay">
-  <div class="mw-modal mw-modal-lg">
-    <div class="mw-modal-header">
-      <h4 class="mw-modal-title">New Contact</h4>
-      <button onclick="closeModal('modal-form')" class="mw-modal-close">
-        &#120299;
-      </button>
+<dialog id="modal-form" class="mw-modal mw-modal-lg" closedby="any">
+  <div class="mw-modal-header">
+    <h4 class="mw-modal-title">New Contact</h4>
+    <button class="mw-modal-close">&#120299;</button>
+  </div>
+  <div class="mw-modal-body">
+    <div class="mw-grid-2 mw-mb-3">
+      <label for="modal-firstname">
+        <span>First Name</span>
+        <input
+          id="modal-firstname"
+          type="text"
+          class="mw-input"
+          placeholder="Jane"
+        />
+      </label>
+      <label for="modal-lastname">
+        <span>Last Name</span>
+        <input
+          id="modal-lastname"
+          type="text"
+          class="mw-input"
+          placeholder="Doe"
+        />
+      </label>
     </div>
-    <div class="mw-modal-body">
-      <div class="mw-grid-2 mw-mb-3">
-        <label for="modal-firstname">
-          <span>First Name</span>
-          <input
-            id="modal-firstname"
-            type="text"
-            class="mw-input"
-            placeholder="Jane"
-          />
-        </label>
-        <label for="modal-lastname">
-          <span>Last Name</span>
-          <input
-            id="modal-lastname"
-            type="text"
-            class="mw-input"
-            placeholder="Doe"
-          />
-        </label>
-      </div>
-      <div class="mw-mb-3">
-        <label for="modal-email">
-          <span>Email</span>
-          <input
-            id="modal-email"
-            type="email"
-            class="mw-input"
-            placeholder="jane@example.com"
-          />
-        </label>
-      </div>
-      <div class="mw-mb-3">
-        <label for="modal-role">
-          <span>Role</span>
-          <select id="modal-role" class="mw-select">
-            <option value="" disabled selected>Select a role</option>
-            <option>Developer</option>
-            <option>Designer</option>
-            <option>Product Manager</option>
-            <option>Other</option>
-          </select>
-        </label>
-      </div>
-      <div class="mw-mb-3">
-        <label for="modal-notes">
-          <span>Notes</span>
-          <textarea
-            id="modal-notes"
-            rows="3"
-            class="mw-textarea"
-            placeholder="Optional notes..."
-          ></textarea>
-        </label>
-      </div>
-      <label class="mw-toggle">
-        <input type="checkbox" />
-        <div class="mw-toggle-track"></div>
-        <span class="mw-toggle-label">Send welcome email</span>
+    <div class="mw-mb-3">
+      <label for="modal-email">
+        <span>Email</span>
+        <input
+          id="modal-email"
+          type="email"
+          class="mw-input"
+          placeholder="jane@example.com"
+        />
       </label>
     </div>
-    <div class="mw-modal-footer">
-      <button onclick="closeModal('modal-form')" class="mw-btn mw-btn-outline">
-        Cancel
-      </button>
-      <button onclick="closeModal('modal-form')" class="mw-btn mw-btn-primary">
-        Save Contact
-      </button>
+    <div class="mw-mb-3">
+      <label for="modal-role">
+        <span>Role</span>
+        <select id="modal-role" class="mw-select">
+          <option value="" disabled selected>Select a role</option>
+          <option>Developer</option>
+          <option>Designer</option>
+          <option>Product Manager</option>
+          <option>Other</option>
+        </select>
+      </label>
     </div>
+    <div class="mw-mb-3">
+      <label for="modal-notes">
+        <span>Notes</span>
+        <textarea
+          id="modal-notes"
+          rows="3"
+          class="mw-textarea"
+          placeholder="Optional notes..."
+        ></textarea>
+      </label>
+    </div>
+    <label class="mw-toggle">
+      <input type="checkbox" />
+      <div class="mw-toggle-track"></div>
+      <span class="mw-toggle-label">Send welcome email</span>
+    </label>
   </div>
-  <div class="mw-modal-backdrop" onclick="closeModal('modal-form')"></div>
-</div>
+  <div class="mw-modal-footer">
+    <button class="mw-modal-close mw-btn mw-btn-outline">Cancel</button>
+    <button class="mw-modal-close mw-btn mw-btn-primary">Save Contact</button>
+  </div>
+</dialog>
 
 <!-- Confirmation Modal -->
-<!-- Same classes, a <dialog> instead of a div: Escape, the focus trap, the
-     inert page behind it and the scroll lock all come from the element. The
-     close buttons need no onclick - the framework script closes the dialog
-     they sit in - and closedby="any" is what dismisses it on a backdrop
-     click, so there is no mw-modal-backdrop either. -->
 <dialog id="modal-confirm" class="mw-modal mw-modal-sm" closedby="any">
   <div class="mw-modal-header">
     <h4 class="mw-modal-title">Delete Item</h4>

package/src/partials/parallax-container.html

@@ -59,7 +59,14 @@
   the picture, not on a theme surface, and the light theme's shadows are cut for
   paper and vanish there. Pair it with <code>mw-header-reveal</code> on the
   header and the page opens on the picture alone: the bar stays away for the
-  first 130px of scroll and has ridden in by 420px.
+  first 130px of scroll and has ridden in by 420px. A control marked
+  <code>mw-header-keep</code> sits that ride out - it travels the bar's distance
+  the other way and waits at the position it will hold once the bar is there, so
+  a login button is on the picture from the first frame and nothing jumps at the
+  end. On a narrow screen it is how the burger reaches the reader before the bar
+  exists. While it floats it carries a ring and a soft shadow so a dark control
+  still reads on a dark picture, and focus leaves the bar alone - it is on
+  screen already, so a click on the theme toggle no longer hauls the header in.
 </p>
 <p class="mw-text-muted mw-text-measure mw-mb-6">
   Add <code>mw-parallax-rise</code> next to it and the picture lifts by
@@ -119,7 +126,11 @@
     <span class="mw-code-block-language">HTML</span>
   </div>
   <div class="mw-code-container">
-    <pre><code>&lt;header class="mw-header mw-header-reveal"&gt;...&lt;/header&gt;
+    <pre><code>&lt;header class="mw-header mw-header-reveal"&gt;
+  ...
+  &lt;button class="mw-login-btn mw-header-keep"&gt;...&lt;/button&gt;
+  &lt;button class="mw-menu-btn mw-header-keep"&gt;...&lt;/button&gt;
+&lt;/header&gt;
 
 &lt;main class="mw-main"&gt;
   &lt;section class="mw-section mw-parallax-sticky mw-parallax-rise"&gt;

package/src/scss/abstracts/_mixins.scss

@@ -1,4 +1,5 @@
 @use 'sass:map';
+@use 'sass:math';
 @use 'variables' as v;
 @use 'functions' as *;
 
@@ -171,15 +172,27 @@
 // Grows the hit area without touching the silhouette - for a control whose size
 // is the design: a 9px gallery dot, an 18px mini button. Neighbours need a gap
 // of at least twice $grow, or two hit areas overlap and a tap lands on the one
-// next door. Takes ::after, so it is out for anything carrying a `data-tooltip`.
-@mixin hit-area($grow: 6px) {
+// next door.
+//
+// A `data-tooltip` owns both pseudo-elements, so the overlay has nowhere to go
+// and used to land on the arrow, leaving its paint on the trigger as a grey
+// diamond. The selector carries that exclusion rather than a note to callers,
+// who apply this to a class and cannot see which instance has the attribute.
+// Those grow the box instead - it costs the silhouette, but of the two only the
+// target is load-bearing under a thumb.
+@mixin hit-area($grow: 6px, $box: 1.5rem) {
   position: relative;
 
-  &::after {
+  &:not([data-tooltip])::after {
     content: '';
     position: absolute;
     inset: -#{$grow};
   }
+
+  &[data-tooltip] {
+    min-width: $box;
+    min-height: $box;
+  }
 }
 
 // One shape for every scroll container and the page itself
@@ -287,6 +300,19 @@
 $_corner-stretch: 1.5;
 $_corner-opaque: 55%;
 
+// `surface(0)` is the natural way to say "no border to subtract", but a unitless
+// zero makes every `calc(<length> - 0)` below invalid - and an invalid calc takes
+// its whole declaration with it. Losing the radius and the mask leaves the accent
+// as a plain 2px border all the way round the box, which is how a modal ended up
+// framed instead of cornered.
+@function _accent-width($value) {
+  @if math.is-unitless($value) {
+    @return $value * 1px;
+  }
+
+  @return $value;
+}
+
 // What is left of the signature once the silhouette is switched off: the same
 // arc, on one corner, thinner and over a shorter run. The two-corner shape is
 // the loud half and mw-corners-even exists to turn it off - but a surface with
@@ -297,7 +323,8 @@ $_corner-opaque: 55%;
 // it follows --mw-radius-scale down to a square, where the arc becomes a
 // bracket in the corner rather than disappearing.
 @mixin corner-mark($border-width: 1px) {
-  $r: max(0px, calc(#{radius('md')} - #{$border-width}));
+  $width: _accent-width($border-width);
+  $r: max(0px, calc(#{radius('md')} - #{$width}));
 
   content: '';
   position: absolute;
@@ -319,8 +346,9 @@ $_corner-opaque: 55%;
   // max(), not a bare subtraction: --mw-radius-scale can take the radius to 0,
   // and while a negative border-radius is clamped for us, a negative circle in
   // the mask below would throw the whole gradient away and lose the arc.
-  $sharp: max(0px, calc(#{radius-sharp()} - #{$border-width}));
-  $round: max(0px, calc(#{radius('xl')} - #{$border-width}));
+  $width: _accent-width($border-width);
+  $sharp: max(0px, calc(#{radius-sharp()} - #{$width}));
+  $round: max(0px, calc(#{radius('xl')} - #{$width}));
   // Opaque to where the curve ends, fading from there, so the arc runs into the
   // straight edge instead of stopping at the tangent. 1.8 is bounded by the
   // shortest surface: past about 2 the two arcs meet on a 50px box and read as

package/src/scss/components/_modals.scss

@@ -146,6 +146,12 @@
     padding: spacing('0');
     border: none;
     color: inherit;
+    // `.mw-modal` carries `position: relative` from surface(), which is what its
+    // corner accent is drawn against - and being an author rule it beats the UA's
+    // `dialog:modal { position: fixed }`. The dialog then centres itself in the
+    // document rather than the viewport, so on a long page it opens somewhere far
+    // above the fold with only its backdrop to show for it.
+    position: fixed;
     // In the top layer there is nothing left to sit above
     z-index: auto;
     // The UA centres a dialog with auto margins; these keep that while giving
@@ -267,8 +273,13 @@
     justify-content: flex-end;
   }
 
-  // Close button
-  .mw-modal-close {
+  // Close button. `:not(.mw-btn)` because the class is two things at once: the
+  // hook main.js closes a dialog by, and the look of the X in the header. A
+  // footer button that dismisses carries both it and `mw-btn mw-btn-primary` -
+  // and this rule sits after the button styles in the same layer at the same
+  // specificity, so without the guard it wins and paints the primary action in
+  // `background: none`.
+  .mw-modal-close:not(.mw-btn) {
     background: none;
     font-size: font-size('md');
     cursor: pointer;