maverick-wave 5.24.0 → 5.25.0

package/.claude/skills/mw-maverick-wave/SKILL.md

@@ -75,6 +75,22 @@ Or from the npm package via SCSS: `@use 'maverick-wave/src/scss/main';`
 (details and configuration in `references/theming.md`). The viewport meta above
 belongs in `src/index.html` there, with `viewport-fit=cover` just the same.
 
+**`main-lean` for a page that uses a handful of components.** The full build is
+~41 kB gzipped and carries all 48 of them. `main-lean` is the same framework
+without any component - tokens, reset, typography, layout, utilities - and the
+components come in one by one next to it:
+
+```scss
+@use 'maverick-wave/src/scss/main-lean' with (
+  $primary-color: #1b1b1d
+);
+@use 'maverick-wave/src/scss/components/buttons';
+@use 'maverick-wave/src/scss/components/cards';
+```
+
+That lands at ~16 kB gzipped plus what the components add (three of them ≈ 19 kB
+in total). The configuration goes on `main-lean`, not on the component imports.
+
 > **Never load `maverick-wave.min.js` in a SPA.** Everything in it is wired up
 > once on `DOMContentLoaded` and writes straight into the DOM. In an Angular
 > app that fires once during bootstrap: components rendered later are never
@@ -166,6 +182,11 @@ between them moved.
 Column grids and most components are mobile-first. The mixins emit range syntax
 (`media-up` is `width >= bp`, `media-down` is `width < bp`), so the two never
 overlap at the breakpoint itself and neither has to stop a fraction short of it.
+Write `media-up`: the base block is the phone and each breakpoint adds to it.
+`media-down` is right in three cases - a rule that sets what the base never sets
+(turned around it would hard-wire an inherited value), a narrow layout that costs
+more properties than the wide one (the navbar sheet, the modal bottom sheet), and
+a class that only ever means "below here", like `mw-hide-mobile`.
 
 **Overriding.** Everything the framework emits sits in
 `@layer mw.reset, mw.base, mw.forms, mw.components, mw.layout, mw.utilities`.
@@ -234,7 +255,8 @@ none of them survive into the compiled CSS. Full list in `references/theming.md`
   zoom. A headline passes `$to: 'xl'`.
 - `fluid-container($min, $max, $from, $to)` - the same ramp in `cqi` against the
   container. Use it instead of `fluid()` inside a `@container` block.
-- `media-up($bp)` / `media-down($bp)` - the breakpoint map as a query.
+- `media-up($bp)` / `media-down($bp)` - the breakpoint map as a query. `media-up`
+  is the default direction, see **Breakpoints** above.
 - `touch-context($bp: 'md')` - coarse pointer _or_ narrow viewport, the condition
   every target-size rule in the framework hangs under.
 - `touch-floor($size: 2.75rem)` - that condition plus a `min-height`.
@@ -299,7 +321,7 @@ feature frame) ·
 `mw-content` ·
 `mw-section` · `mw-section-head` (+ `-title`, `-intro`, `-numbered`, colours) ·
 `mw-page-header` · `mw-grid-*`
-(+ `mw-grid-even`) ·
+(+ `mw-grid-even`, `mw-grid-from-{sm,md,lg,xl}`) ·
 `mw-columns-2/3` · `mw-row-split` · `mw-hero` (+ `mw-scroll-hint`, `-end`) ·
 `mw-parallax` (+ `-media`, `-content`, `-dimmed`, `-sticky`, `-rise`,
 `-slow`, `-pattern`) · `mw-footer`
@@ -312,7 +334,7 @@ feature frame) ·
 `mw-glow-{primary,secondary,info,success,warning,danger}` ·
 `mw-corner-plain` ·
 `mw-aspect-square|video|wide|portrait|photo` · `mw-d-{sm,md,lg,xl}-*` /
-`mw-hide-mobile` / `mw-hide-desktop` · `mw-overflow-*` / `mw-snap-x` ·
+`mw-hide-mobile` / `mw-hide-desktop` / `mw-hide-print` / `mw-print-only` · `mw-overflow-*` / `mw-snap-x` ·
 `mw-reveal` / `mw-reveal-stagger` · spacing, flex, display, text
 
 ## Pitfalls
@@ -477,13 +499,18 @@ feature frame) ·
     directly after the block, so the overlap reads as a surface and not a cut.
     It sits at `:where()` weight, so a plain `box-shadow` of your own on that
     section replaces it.
-30. **`viewport-fit=cover` belongs in the viewport meta.** The container
+30. **A stored theme needs a script in the `<head>`.** `main.js` runs at the
+    end of the body, so a reader whose choice differs from the OS sees the
+    other theme for one frame. Five inline lines in the head apply it before
+    the first paint - the snippet is in `references/javascript.md`. The theme
+    classes live on `<html>` for exactly this reason.
+31. **`viewport-fit=cover` belongs in the viewport meta.** The container
     gutter, the mobile nav panel and the modal padding all budget for the
     cutout with `env(safe-area-inset-*)`, and iOS resolves every one of those
     to `0` without it - on a notched phone the content then sits under the
     rounded corner. Nothing errors, which is why the shipped JS writes a
     console warning on localhost when the meta is missing.
-31. **Half the layout reads its own width, not the viewport.** `mw-card`,
+32. **Half the layout reads its own width, not the viewport.** `mw-card`,
     `mw-tile`, `mw-stepper`, both timelines and - since 5.13.0 -
     `mw-gallery-container` and `mw-image-slider` are `@container` queries, so
     any of them in a half-width column takes its narrow layout there while the

package/.claude/skills/mw-maverick-wave/references/components.md

@@ -1319,6 +1319,10 @@ edge drops and the key sits 1px lower.
 - The cursor is `default` because a figure is usually not clickable. On `<a>`
   and `<button>` it turns into a pointer automatically; on anything else use
   `mw-info-clickable`.
+- `mw-info-block` is the same surface carrying a paragraph: 68 characters
+  wide, left-aligned, and it does not lift on hover. It sits at the left edge
+  like everything else with running text in it - `mw-info-block-center` puts it
+  back in the middle of its container.
 - `mw-info-mini` is the 20px status dot: sizes `-sm`, `-lg`, `-xl`, colours
   `-primary`, `-secondary`, `-success`, `-warning`, `-danger`, `-info`.
 

package/.claude/skills/mw-maverick-wave/references/javascript.md

@@ -2,15 +2,28 @@
 
 ## What `maverick-wave.min.js` is
 
-One vanilla IIFE, no dependencies, ~24 kB. It queries the DOM **once** on
-`DOMContentLoaded` and attaches listeners. There is no re-init API, no
-`MutationObserver`, no exported module - it is built for a server-rendered or
-static page.
+One vanilla IIFE, no dependencies, ~24 kB. It queries the DOM on
+`DOMContentLoaded` and attaches listeners. No `MutationObserver`, no exported
+module - it is built for a server-rendered or static page.
+
+Markup that arrives later gets wired through the one public entry point:
+
+```js
+window.MaverickWave.init(subtree); // or init() for the whole document
+```
+
+Call it after an htmx swap, after filling a modal from a fetch, or after a view
+transition replaced the body. Every element that already carries listeners is
+skipped, so calling it twice over the same markup does nothing - the components
+are safe to re-run, the document- and window-level behaviour is wired once and
+never again.
+
+What that does **not** make it is a SPA library - see below.
 
 ## Why a SPA must not load it
 
-- It runs once during bootstrap. Anything rendered afterwards - i.e. everything
-  in a routed application - never gets initialised.
+- Anything rendered after bootstrap needs `MaverickWave.init()` by hand, for
+  every subtree, on every render - in a routed application that is all of it.
 - It writes straight into the DOM (class toggles, generated elements, inline
   styles). In Angular that happens outside change detection; in a zoneless app
   the framework never learns about it, and on the next re-render your bindings
@@ -23,6 +36,29 @@ in a Vite entry point. Load the **CSS only** and rebuild the handful of
 behaviours in components. Each one is a few lines - the framework's state
 classes are the entire contract.
 
+## The theme has to be applied before the first paint
+
+`main.js` sits at the end of the body, so a stored choice that differs from the
+operating system reaches the page one frame too late - the reader sees the other
+theme flash. The fix is five lines in the `<head>`, inline and synchronous,
+before the stylesheet has painted anything:
+
+```html
+<script>
+  (function () {
+    var stored = localStorage.getItem('mw-theme');
+    if (stored === 'light' || stored === 'dark') {
+      document.documentElement.classList.add('mw-theme-' + stored);
+    }
+  })();
+</script>
+```
+
+That is also why the toggle writes the class on `<html>` and not on `<body>`:
+in the head there is no body yet. An external file would not help - it paints
+first. With nothing stored, nothing happens here and the page follows the OS on
+its own through `light-dark()`.
+
 ## Behaviour inventory
 
 | Behaviour           | What the shipped JS does                                                                                                                                                                                                                                                        | What to do instead                                                                                                                                                                                                                 |
@@ -33,11 +69,11 @@ classes are the entire contract.
 | Mobile nav          | Toggles `open` on `mw-menu-btn` and `mw-navbar` plus `mw-nav-open` on `<body>`, writes `aria-expanded` when the button is a `<button>`, closes on anchor click and on Escape (focus returns to the button)                                                                      | One signal, bound to all three - the body class carries the scrim, the scroll lock and the pinning of the bar; reset it on navigation end                                                                                          |
 | Scroll spy          | Sets `mw-active` on `mw-navbar-link` from the scroll position                                                                                                                                                                                                                   | Router-based: `routerLinkActive="mw-active"`                                                                                                                                                                                       |
 | Anchor scrolling    | Intercepts `a[href^="#"]` and runs its own eased scroll - duration scales with distance, capped at 1.4s, cancelled by wheel or touch. Lands on `scroll-padding-top`, moves focus to the target, writes the hash with `replaceState`, and measures a sticky target unpinned      | The router; for in-page anchors `scrollIntoView({ behavior: 'smooth' })` or your own animation                                                                                                                                     |
-| Theme toggle        | `localStorage['mw-theme']`, toggles `mw-theme-light` / `mw-theme-dark` on `<body>` and `mw-active` on the toggle, wrapped in `mw-theme-switching` on `<html>` so the flip starts no transitions. With nothing stored it takes `prefers-color-scheme` and keeps following it     | A theme service - see `examples/angular-services.md`                                                                                                                                                                               |
+| Theme toggle        | `localStorage['mw-theme']`, toggles `mw-theme-light` / `mw-theme-dark` on `<html>` and `mw-active` on the toggle, wrapped in `mw-theme-switching` on `<html>` so the flip starts no transitions. With nothing stored it takes `prefers-color-scheme` and keeps following it     | A theme service - see `examples/angular-services.md`                                                                                                                                                                               |
 | Progress bar        | `IntersectionObserver` sets `width` from `data-value`                                                                                                                                                                                                                           | Bind `[style.width.%]="value()"` on `mw-progress-fill`                                                                                                                                                                             |
 | Slider              | On `input`, sets `--value` (track fill) and `data-value` (badge text)                                                                                                                                                                                                           | Bind `[style.--value.%]` and `[attr.data-value]`                                                                                                                                                                                   |
 | Alerts              | Close button adds `mw-alert-closing` (fade out), then `mw-alert-closed` (`display: none`) after `--mw-duration-base`                                                                                                                                                            | Remove the alert from the list/signal                                                                                                                                                                                              |
-| Checkbox lists      | Adds `mw-selected` to the `li`, emits a `checkboxToggle` event, exposes `window.toggleCheckbox`                                                                                                                                                                                 | `[class.mw-selected]="item.checked"`                                                                                                                                                                                               |
+| Checkbox lists      | Adds `mw-selected` to the `li`, emits a `checkboxToggle` event, exposes `window.mwToggleCheckbox`                                                                                                                                                                               | `[class.mw-selected]="item.checked"`                                                                                                                                                                                               |
 | Gallery             | Generates the dots, moves the track, swipe handling (single finger, dominant axis, passive listeners), writes `mw-gallery-desc`                                                                                                                                                 | Render dots in the template, bind the track transform and `mw-active` on the current dot                                                                                                                                           |
 | Image slider        | Toggles `mw-active` on the overlay image and the control button with the matching `data-index`                                                                                                                                                                                  | Bind `mw-active` from the selected index                                                                                                                                                                                           |
 | Kanban board        | Counts the tickets per lane, moves a card between lanes (`data-kanban-move`) and marks the arrival with `mw-kanban-card-moved-forward` / `-back`, clones `mw-kanban-card-template` on save, derives the next key from `data-kanban-prefix`, toggles `mw-active` on the composer | Keep the tickets in a signal/store and render the lanes from it; `mw-active` on the composer, `mw-kanban-editing` on the ticket it replaces. Neither the `<template>` nor the `mw-kanban-composer-*` hook classes are needed       |

package/.claude/skills/mw-maverick-wave/references/layout.md

@@ -335,7 +335,12 @@ width.
 
 A `mw-container` that contains a `mw-hero` switches to full-bleed, full-height
 mode with the background image from `--mw-hero-background`.
-`mw-home-content-fade` fades the content in.
+`mw-home-content-fade` fades the content in. `mw-home-start` puts the whole
+block against the left container edge instead of centring it - for a hero that
+points somewhere rather than sitting in the middle. `mw-home` carries the
+container width itself, because the hero container runs the full width of the
+screen; without that the hero content would start at a different edge than
+every section below it.
 
 The image is treated per theme through `--mw-hero-image-filter` - a filter, not
 a tinted overlay: `$hero-filter-dark` (`brightness(0.7)`) against
@@ -489,6 +494,13 @@ row becomes as tall as the tallest instead of as tall as its own contents. For a
 column of cards that should end on one line even when one of them carries an
 extra sentence.
 
+`mw-grid-from-sm|md|lg|xl` is the second modifier: it holds the grid at one
+column until that breakpoint, and the grid's own ramp takes over from there.
+Every ramp turns two-column at `sm`, and 576px is generous for running text
+next to a picture - `mw-grid-2 mw-grid-from-md` is the pair that fixes that.
+It also resets the `mw-reveal-stagger` cycle below the breakpoint, so two cards
+standing above each other do not rise on different beats.
+
 Every one of them has a `-lg` twin with a wider gap (2.5rem instead of 1.35rem):
 `mw-grid-2-lg`, `mw-grid-3-lg`, `mw-grid-4-lg`, `mw-grid-5-lg`, `mw-grid-1-lg`,
 `mw-grid-auto-lg`, `mw-grid-flex-lg`, `mw-grid-lg`.
@@ -543,6 +555,16 @@ applies below that. The pair `mw-d-none mw-d-md-flex` is hidden on a phone and a
 row from a tablet on. `mw-hide-mobile` (gone below md) and `mw-hide-desktop`
 (gone from md up) spell out the two everyone actually reaches for.
 
+**Print** - the framework ships a print stylesheet, so a page that is dark on
+screen comes out of the printer as black on white: the surface, ink, border and
+elevation tokens are redeclared for paper, the fixed chrome (header, ribbon,
+section nav, scroll cue, burger, theme toggle, toasts) is dropped, cards keep a
+hairline instead of a tone, headings do not end a page and cards, rows and
+figures are not torn across one. A link in `mw-prose` or `mw-disclaimer` that
+points at an http(s) address prints its target after the text. `mw-hide-print`
+takes an element off the paper, `mw-print-only` is the note that exists only
+there. Nothing to switch on.
+
 **Text overflow** - `mw-text-truncate` is one line ending in an ellipsis and
 carries `min-width: 0` with it, which is the reason truncation "does not work"
 nine times out of ten inside a flex row. `mw-text-clamp-2` through `-5` is that

package/.claude/skills/mw-maverick-wave/references/theming.md

@@ -396,6 +396,10 @@ Functions read the maps: `spacing('4')`, `font-size('lg')`,
   container widths, not breakpoint names, because a container has none.
 - `media-up($bp)` / `media-down($bp)` - the `$breakpoints` map as range syntax,
   `width >= bp` and `width < bp`, so the two never overlap at the breakpoint.
+  `media-up` is the direction the framework is written in: the base block is the
+  phone and each breakpoint adds to it. `media-down` is for a rule that sets what
+  the base never sets - turned around it would hard-wire an inherited value - and
+  for a narrow layout that costs more properties than the wide one.
 - `touch-context($bp: 'md')` - coarse pointer _or_ narrow viewport. Every
   target-size rule in the framework hangs under it; put your own control under
   the same condition instead of guessing it.
@@ -440,7 +444,7 @@ Give it a layer of its own:
 
 ## Importing only what you need
 
-The full stylesheet is ~281 kB raw / ~40 kB gzipped. Marketing components
+The full stylesheet is ~290 kB raw / ~41 kB gzipped. Marketing components
 (`blog-post`, `gallery`, `content-slider`, `techstack-bucket`, `tiles`,
 `coming-soon`, `ratings`, `home`, `hero`) are dead weight in an application, and
 Angular bundle budgets notice.
@@ -452,6 +456,22 @@ colourless. The cascade layer order comes along on its own: every module loads
 `abstracts`, which declares it, so a hand-picked subset orders itself the same
 way the full build does.
 
+**The short way is `main-lean`**: the whole framework minus every component -
+tokens, reset, typography, the complete layout and all utilities, ~98 kB raw /
+~16 kB gzipped. Configure it like `main` and add the components next to it:
+
+```scss
+@use 'maverick-wave/src/scss/main-lean' with (
+  $primary-color: #0f766e
+);
+@use 'maverick-wave/src/scss/components/buttons';
+@use 'maverick-wave/src/scss/components/cards';
+@use 'maverick-wave/src/scss/components/alerts';
+```
+
+Those three land at ~19 kB gzipped against ~41 kB for the full build. Pick the
+files by hand, as below, when you also want to leave parts of the layout out.
+
 ```scss
 // styles.scss - configure first, then pick
 @use 'maverick-wave/src/scss/abstracts/variables' with (

package/CHANGELOG.md

@@ -6,6 +6,20 @@ Patch releases are only for test purposes - here I only document major and minor
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.25.0] - 2026-09-20
+
+### Added
+
+- print stylesheet
+- `main-lean` entry point
+- `mw-home-start` for a hero at the left container edge
+- `mw-grid-from-*` keeps a grid single column up to that breakpoint
+
+### Changed
+
+- more "mobile first" design
+- `mw-home` carries the container width
+
 ## [5.24.0] - 2026-09-20
 
 ### Changed

package/CLAUDE.md

@@ -36,6 +36,10 @@ There are no test or lint scripts.
 - `utilities/` - Spacing, flex, display utility classes
 - `main.scss` - Entry point using `@use`/`@forward` (not `@import`)
 
+**Mobile-first** - The unprefixed block is the phone layout; `media-up($bp)` adds
+to it. `media-down($bp)` only for rules that set what the base never sets, or
+where the narrow layout costs more properties than the wide one.
+
 **JavaScript** (`src/js/main.js`) - Single file. All components auto-initialize on `DOMContentLoaded`. Includes: gallery and image sliders, theme toggle (persisted to localStorage, transitions suppressed during the flip), accordion, mobile nav, progress bar (IntersectionObserver), scroll spy, tabs (which also get their ARIA and arrow-key handling here), alerts/toasts, modals, range inputs, dropdowns, language switcher, checkbox lists, kanban board, calendar.
 
 **HTML showcase** (`index.html` + `src/partials/`) - The top-level `index.html` uses `@@include()` syntax to pull in 63 partials from `src/partials/`. These compile into `dist/index.html`.

package/README.md

@@ -45,12 +45,12 @@ The result is a framework that balances utility with simplicity, offering develo
     <title>My MaverickWave Project</title>
     <link
       rel="stylesheet"
-      href="https://cdn.jsdelivr.net/npm/maverick-wave@5.24.0/maverick-wave.min.css"
+      href="https://cdn.jsdelivr.net/npm/maverick-wave@5.25.0/maverick-wave.min.css"
     />
   </head>
   <body>
     <!-- Your content here -->
-    <script src="https://cdn.jsdelivr.net/npm/maverick-wave@5.24.0/maverick-wave.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/maverick-wave@5.25.0/maverick-wave.min.js"></script>
   </body>
 </html>
 ```
@@ -437,6 +437,8 @@ They exist on the SCSS path only - the compiled CSS carries none of them.
   ignores the reader's font size. The default range stops at `md`, a headline
   passes `$to: 'xl'`.
 - `media-up($bp)` / `media-down($bp)` - the `$breakpoints` map as a query.
+  `media-up` is the direction the framework is written in: the base block is the
+  phone, each breakpoint adds to it.
 - `touch-context($bp: 'md')` - coarse pointer _or_ narrow viewport, the condition
   every target-size rule in the framework hangs under.
 - `touch-floor($size: 2.75rem)` - that condition plus a `min-height`. Not for a

package/index.html

@@ -25,6 +25,19 @@
          cached: the filename never changes, and without it a stale stylesheet
          survives a normal reload -->
     <link rel="stylesheet" href="maverick-wave.min.css?v={{VERSION}}" />
+
+    <!-- Applies a stored theme choice before the first paint. Without it a
+         reader whose choice differs from the OS sees the other theme for a
+         frame, because main.js only runs at the end of the body. Inline and
+         synchronous on purpose - an external file would paint first. -->
+    <script>
+      (function () {
+        var stored = localStorage.getItem('mw-theme');
+        if (stored === 'light' || stored === 'dark') {
+          document.documentElement.classList.add('mw-theme-' + stored);
+        }
+      })();
+    </script>
     <!-- Favicons -->
     <link rel="icon" type="image/svg+xml" href="favicon/favicon.svg" />
     <link