maverick-wave 3.2.3 → 3.3.1

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

@@ -0,0 +1,208 @@
+---
+name: maverick-wave
+description: Complete usage guide for the MaverickWave CSS framework - mw-* classes, --mw-* design tokens, grid, components, forms, theming and integration into Angular, other SPAs or plain HTML. Use whenever markup or styles are written in a project that loads maverick-wave (CSS/SCSS/CDN), when a mw-* class or --mw-* token appears, or when a UI has to be built with it.
+---
+
+# MaverickWave
+
+A CSS-only component framework: it ships classes and design tokens, no components,
+no directives, no build-time API. You write plain HTML with `mw-*` classes - in a
+template, a JSX file, a Twig partial, it makes no difference. Everything below is
+therefore framework-neutral; the Angular notes are marked as such because Angular
+is the reference integration.
+
+**One rule dominates all others: only use classes that actually exist.** The
+framework is not utility-complete, invented class names fail silently (no error,
+just unstyled markup). Verify with `grep -o '\.mw-[a-z0-9-]*' dist/maverick-wave.min.css | sort -u`
+or, in the framework repo, `npm run verify`.
+
+## Reference files
+
+Load the one you need - do not read them all up front.
+
+| File                       | Content                                                                                                          |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `references/layout.md`     | Page skeleton, grid, container, section, page header, header/navbar, footer, spacing/flex/display/text utilities |
+| `references/components.md` | Every component: markup, variants, sizes, state classes                                                          |
+| `references/forms.md`      | Inputs, select, textarea, checkbox, radio, toggle, slider, input group, `mw-field` pattern, validation           |
+| `references/theming.md`    | Token model, `color-mix` derivation, light/dark, SCSS configuration, cherry-picking single components            |
+| `references/javascript.md` | What the shipped `main.js` does, why SPAs must not load it, what to implement instead                            |
+
+## Examples
+
+| File                              | Content                                                                                                                |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `examples/angular-list-page.md`   | Full list/CRUD page: page header, meta counters, filter bar, table with status tags, empty state, delete modal, toasts |
+| `examples/angular-form.md`        | Reactive form: `mw-field`, validation states, input groups, numeric input, toggles, form actions                       |
+| `examples/angular-services.md`    | Theme service, toast service, modal/scroll-lock, tabs and accordion without `main.js`                                  |
+| `examples/static-landing-page.md` | Plain HTML page: header, hero, sections, cards, tiles, accordion, footer, theme toggle                                 |
+
+## Setup
+
+### Plain HTML / CDN
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/maverick-wave@3.4.0/maverick-wave.min.css"
+/>
+<link
+  rel="stylesheet"
+  href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css"
+/>
+...
+<script src="https://cdn.jsdelivr.net/npm/maverick-wave@3.4.0/maverick-wave.min.js"></script>
+```
+
+Pin the version. The JS file is optional and only for server-rendered/static pages -
+see below.
+
+### Angular (or any SPA)
+
+```jsonc
+// angular.json
+"styles": ["src/assets/maverick-wave.min.css", "src/styles.scss"]
+// no "scripts" entry - see the warning below
+```
+
+Or from the npm package via SCSS: `@use 'maverick-wave/src/scss/main';`
+(details and configuration in `references/theming.md`).
+
+> **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
+> initialised, and the theme toggle mutates the DOM behind change detection.
+> Reimplement the handful of behaviours in your own components -
+> `references/javascript.md` lists all of them, `examples/angular-services.md`
+> shows the code.
+
+### Icons
+
+The framework styles icon slots but ships no icons. Examples use FontAwesome
+(`<i class="fas fa-save"></i>`); any icon element works - inline SVG, an Angular
+`fa-icon`, a `<span>` with a webfont.
+
+### Fonts
+
+`--mw-font-family-base` defaults to `'Poppins', sans-serif`, but no font is
+bundled. Load it yourself or override the token.
+
+## Naming rules
+
+- Classes: `mw-` prefix, kebab-case: `.mw-button-bar`, `.mw-item-list-compact`
+- Tokens: `--mw-` prefix: `--mw-primary-color`, `--mw-border-accent`
+- Variants are suffixes on the base class: `mw-btn` + `mw-btn-primary`,
+  `mw-alert` + `mw-alert-danger`
+- Colour variant names are the same everywhere: `primary`, `secondary`,
+  `success`, `warning`, `danger`, `info` (plus `muted` on tags). Not every
+  component offers all of them - check `references/components.md`.
+- Size variants: `-sm`, `-lg`, sometimes `-xs` / `-xl`. The unsuffixed class is
+  the medium size.
+
+### State classes are not uniform - this is the single most common source of bugs
+
+| Component                                                         | State class                         |
+| ----------------------------------------------------------------- | ----------------------------------- |
+| Accordion header + content                                        | `active` (no prefix)                |
+| Tabs nav item + panel                                             | `active` (no prefix)                |
+| Navbar link                                                       | `active` (no prefix)                |
+| Timeline step (`mw-timeline-big-step`, `mw-timeline-simple-step`) | `active` (no prefix)                |
+| Image slider overlay image + control button                       | `active` (no prefix)                |
+| Button, pressed/selected look                                     | `active` (no prefix)                |
+| Theme toggle                                                      | `active` (no prefix)                |
+| Burger button + navbar drawer                                     | `open` (no prefix)                  |
+| Gallery dot                                                       | `mw-active`                         |
+| Stepper indicator / label / connector / step                      | `mw-active`, `mw-done`              |
+| Checkbox list item (`li`)                                         | `mw-selected`                       |
+| Modal overlay                                                     | `mw-modal-open`                     |
+| Alert, after dismissal                                            | `mw-alert-closed` (`display: none`) |
+| Field wrapper in error                                            | `mw-field-has-error`                |
+| Single form control in error                                      | `mw-form-element-error`             |
+
+Angular: `[class.active]="isOpen"` and `[class.mw-active]="i === current"` - the
+binding target must match the table exactly.
+
+## Scales
+
+**Spacing** (`mw-m-*`, `mw-p-*`, `mw-gap-*` and every internal value):
+
+| key | 0   | 1   | 2    | 3   | 4    | 5   | 6    | 7    | 8   | 9   | 10  | 11  | 12  | 13  | 14  |
+| --- | --- | --- | ---- | --- | ---- | --- | ---- | ---- | --- | --- | --- | --- | --- | --- | --- |
+| rem | 0   | 0.2 | 0.35 | 0.5 | 0.75 | 1   | 1.35 | 1.75 | 2   | 2.5 | 3.3 | 4.3 | 5.5 | 7   | 9   |
+
+Negative margins exist for keys 1-6 (`mw-mt--3` = -0.5rem). Gap has no negative
+keys at all (negative gap is invalid CSS and is not generated).
+
+**Font sizes** (`mw-text-3xs` … `mw-text-6xl`): `3xs` 0.6, `2xs` 0.7, `xs` 0.8,
+`sm` 0.9, `base` 1, `md` 1.1, `lg` 1.3, `xl` 1.5, `2xl` 1.8, `3xl` 2.2, `4xl` 2.5,
+`5xl` 3, `6xl` 4.3 rem.
+
+**Breakpoints** (max-width, mobile-first markup / desktop-first media queries):
+`xs` 375, `sm` 576, `md` 768, `lg` 992, `xl` 1200, `2xl` 1400 px.
+
+**Radius** (`mw-radius-none|xs|sm|md|lg|xl|2xl|full`): 0, 2, 5, 10, 15, 20, 30 px, 50%.
+
+## Component index
+
+Everything below is documented in `references/components.md` unless marked otherwise.
+
+**Actions** `mw-btn` (+ `primary`, `secondary`, `danger`, `success`, `outline`,
+`link`, `link-muted`, `sm`, `lg`) · `mw-btn-mini` · `mw-button-bar`
+
+**Containers** `mw-card` (+ `simple`, `content`, `lg`, `xl`, `stack`, badge,
+ribbon) · `mw-panel` · `mw-tile` · `mw-accordion` · `mw-tabs` · `mw-modal` ·
+`mw-item-list` family
+
+**Data & status** `mw-table` (+ `subtle`, `sticky-head`, `cards`, `compact`,
+`hover`, responsive wrappers) · `mw-tag` / `mw-tags` · `mw-info` /
+`mw-info-mini` / `mw-info-counter` · `mw-progress-bar` · `mw-rating` ·
+`mw-meta-header` · `mw-stepper` · `mw-timeline-big` / `mw-timeline-simple`
+
+**Feedback** `mw-alert` · `mw-toast-stack` · `mw-empty-state` ·
+`mw-spinner-border` / `mw-spinner-dots` / `mw-spinner-dual-ring` · `mw-skeleton`
+
+**Navigation** `mw-header` + `mw-navbar` · `mw-breadcrumbs` · `mw-pagination` ·
+`mw-section-nav` (`references/layout.md`)
+
+**Media & content** `mw-avatar` (+ `initials`, `group`) · `mw-gallery` ·
+`mw-image-slider` · `mw-blog-post` · `mw-code-block` / `mw-terminal` ·
+`mw-techstack-bucket` · `mw-coming-soon` · `mw-divider` · `mw-list` family
+
+**Forms** (`references/forms.md`) `mw-field` · `mw-input` · `mw-select` ·
+`mw-textarea` · `mw-checkbox` · `mw-radio` · `mw-toggle` · `mw-slider` ·
+`mw-input-group` · `mw-form` / `mw-form-group` / `mw-form-actions` · `mw-login`
+
+**Layout** (`references/layout.md`) `mw-main` · `mw-container` · `mw-content` ·
+`mw-section` · `mw-page-header` · `mw-grid-*` · `mw-hero` · `mw-footer`
+
+## Pitfalls
+
+1. **`<section>` gets no padding by itself.** Since 3.4.0 the bare element
+   selector is gone - write `<section class="mw-section">`. `mw-section-alternate`
+   only paints the pattern, it does not space anything.
+2. **`mw-form` has no padding** (removed in 3.4.0) - it is a flex column with a
+   gap. Safe to put on `mw-modal-body` or `mw-panel-body`.
+3. **Use `mw-btn-danger` for destructive actions**, never `mw-btn-secondary`. The
+   secondary colour is a brand decision and turns yellow, teal or anything else
+   the moment the palette changes.
+4. **One tag or many?** `mw-tag` is a standalone chip and carries its own colour -
+   right for a table cell. `mw-tags` is a container that colours all its
+   `mw-tags-item` children - right for a tag list. Mixing them (`mw-tag` inside
+   `mw-tags`) is wrong.
+5. **A spinner needs a shape class.** `mw-spinner-primary` alone renders nothing;
+   use `mw-spinner-border`, `mw-spinner-dots` or `mw-spinner-dual-ring`.
+6. **Sticky table headers need a height-limited scroll container** -
+   `mw-table-responsive` only scrolls horizontally. Use
+   `mw-table-responsive-scroll` (height via `--mw-table-scroll-height`).
+7. **`--mw-text-muted-color` on a coloured surface is always wrong.** It follows
+   the theme; buttons, table headers and badges do not. Use
+   `--mw-accent-text-color` there, and `opacity` for disabled states.
+8. **`mw-card` already lifts on hover** and `mw-btn` already has `inline-flex`
+   plus a gap for icons. Neither has a modifier class for it - adding one from
+   memory produces markup that does nothing.
+9. **Overriding one root colour is enough.** Hover tones, translucent
+   backgrounds and borders are derived with `color-mix()` at runtime. Setting
+   `--mw-primary-color-hover` by hand is usually a sign the base token was not
+   set.
+10. **Browser floor: `color-mix()`** - Chrome 111+, Safari 16.2+, Firefox 113+.
+    Older browsers get no colours at all, not merely worse ones.

package/.claude/skills/maverick-wave/examples/angular-form.md

@@ -0,0 +1,275 @@
+# Example: reactive form
+
+Every control type in one form, with the error handling the framework expects:
+`mw-field-has-error` on the wrapper, `mw-field-error` for the message. Nothing
+reacts to `ng-invalid` on its own - the bindings below are the whole mechanism.
+
+## Component
+
+```ts
+import {
+  ChangeDetectionStrategy,
+  Component,
+  inject,
+  signal,
+} from '@angular/core';
+import { TitleCasePipe } from '@angular/common';
+import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
+
+@Component({
+  selector: 'app-project-form',
+  imports: [ReactiveFormsModule, TitleCasePipe],
+  templateUrl: './project-form.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ProjectFormComponent {
+  private readonly fb = inject(FormBuilder);
+
+  protected readonly saving = signal(false);
+
+  protected readonly form = this.fb.nonNullable.group({
+    name: ['', [Validators.required, Validators.maxLength(80)]],
+    email: ['', [Validators.required, Validators.email]],
+    budget: [''], // text + inputmode="decimal", parsed on submit
+    type: ['', Validators.required],
+    priority: ['normal'],
+    description: [''],
+    teamSize: [3],
+    notify: [true],
+    terms: [false, Validators.requiredTrue],
+  });
+
+  protected readonly f = this.form.controls;
+
+  // A control shows its error once the user has touched it
+  protected invalid(name: keyof typeof this.f): boolean {
+    const control = this.f[name];
+    return control.invalid && (control.touched || control.dirty);
+  }
+
+  protected submit(): void {
+    if (this.form.invalid) {
+      this.form.markAllAsTouched();
+      return;
+    }
+    this.saving.set(true);
+    // …persist, then this.saving.set(false)
+  }
+}
+```
+
+## Template
+
+```html
+<form class="mw-form" [formGroup]="form" (ngSubmit)="submit()">
+  <!-- Group: base data -->
+  <div class="mw-form-group">
+    <p class="mw-text-muted mw-mb-3">Base data</p>
+
+    <div class="mw-grid-2">
+      <div class="mw-field" [class.mw-field-has-error]="invalid('name')">
+        <label class="mw-field-label mw-required" for="name"
+          >Project name</label
+        >
+        <input id="name" type="text" class="mw-input" formControlName="name" />
+        @if (invalid('name')) {
+        <span class="mw-field-error">
+          <i class="fas fa-exclamation-circle"></i>
+          @if (f.name.hasError('required')) { A name is required. } @else { At
+          most 80 characters. }
+        </span>
+        } @else {
+        <span class="mw-field-hint">Shown in the project list.</span>
+        }
+      </div>
+
+      <div class="mw-field" [class.mw-field-has-error]="invalid('email')">
+        <label class="mw-field-label mw-required" for="email">Contact</label>
+        <div class="mw-input-group">
+          <span class="mw-input-group-prefix"
+            ><i class="fas fa-envelope"></i
+          ></span>
+          <input
+            id="email"
+            type="email"
+            class="mw-input"
+            formControlName="email"
+          />
+        </div>
+        @if (invalid('email')) {
+        <span class="mw-field-error">
+          <i class="fas fa-exclamation-circle"></i> Please enter a valid email
+          address.
+        </span>
+        }
+      </div>
+
+      <!-- Money: text + inputmode, never type="number" -->
+      <div class="mw-field">
+        <label class="mw-field-label" for="budget">Budget</label>
+        <div class="mw-input-group">
+          <span class="mw-input-group-prefix"
+            ><i class="fas fa-euro-sign"></i
+          ></span>
+          <input
+            id="budget"
+            type="text"
+            inputmode="decimal"
+            class="mw-input mw-input-numeric"
+            placeholder="0,00"
+            formControlName="budget"
+          />
+          <span class="mw-input-group-suffix">EUR</span>
+        </div>
+        <span class="mw-field-hint">Comma as decimal separator.</span>
+      </div>
+
+      <div class="mw-field" [class.mw-field-has-error]="invalid('type')">
+        <label class="mw-field-label mw-required" for="type">Type</label>
+        <select id="type" class="mw-select" formControlName="type">
+          <option value="" disabled>Choose…</option>
+          <option value="internal">Internal</option>
+          <option value="customer">Customer project</option>
+        </select>
+        @if (invalid('type')) {
+        <span class="mw-field-error">
+          <i class="fas fa-exclamation-circle"></i> Please choose a type.
+        </span>
+        }
+      </div>
+
+      <!-- Full width inside the two-column grid -->
+      <div class="mw-field" style="grid-column: 1 / -1">
+        <label class="mw-field-label" for="description">Description</label>
+        <textarea
+          id="description"
+          class="mw-textarea mw-textarea-resizable-vertical"
+          rows="4"
+          formControlName="description"
+        ></textarea>
+        <span class="mw-field-hint">Markdown is allowed.</span>
+      </div>
+    </div>
+  </div>
+
+  <!-- Group: settings -->
+  <div class="mw-form-group">
+    <p class="mw-text-muted mw-mb-3">Settings</p>
+
+    <div class="mw-grid-2">
+      <div>
+        <p class="mw-text-muted mw-text-sm mw-mb-2">Priority</p>
+        <div class="mw-radio-group mw-radio-group-inline">
+          @for (option of ['low', 'normal', 'high']; track option) {
+          <label class="mw-radio">
+            <input type="radio" [value]="option" formControlName="priority" />
+            <div class="mw-radio-button"></div>
+            <div class="mw-radio-label">{{ option | titlecase }}</div>
+          </label>
+          }
+        </div>
+      </div>
+
+      <div>
+        <p class="mw-text-muted mw-text-sm mw-mb-2">Notifications</p>
+        <div class="mw-toggle-group">
+          <label class="mw-toggle mw-toggle-success">
+            <input type="checkbox" formControlName="notify" />
+            <div class="mw-toggle-track"></div>
+            <span class="mw-toggle-label">Notify me about changes</span>
+          </label>
+        </div>
+      </div>
+
+      <!-- Slider: both bindings are needed, the framework computes nothing -->
+      <div class="mw-field" style="grid-column: 1 / -1">
+        <label class="mw-field-label" for="team">Team size</label>
+        <div class="mw-slider-container">
+          <div
+            class="mw-slider-value mw-slider-numeric"
+            [attr.data-value]="f.teamSize.value"
+          ></div>
+          <input
+            id="team"
+            type="range"
+            class="mw-slider mw-slider-primary"
+            min="1"
+            max="10"
+            formControlName="teamSize"
+            [style.--value.%]="f.teamSize.value * 10"
+          />
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Single control without a field wrapper -->
+  <div
+    class="mw-checkbox-group"
+    [class.mw-form-element-error]="invalid('terms')"
+  >
+    <label class="mw-checkbox">
+      <input type="checkbox" formControlName="terms" />
+      <div class="mw-checkbox-box"></div>
+      <div class="mw-checkbox-label">I accept the terms.</div>
+    </label>
+  </div>
+
+  <div class="mw-form-actions">
+    <p class="mw-form-actions-hint">Fields marked with * are required.</p>
+    <button type="button" class="mw-btn mw-btn-outline" (click)="form.reset()">
+      Reset
+    </button>
+    <button type="submit" class="mw-btn mw-btn-primary" [disabled]="saving()">
+      @if (saving()) {
+      <span class="mw-spinner-border mw-spinner-sm"></span> Saving… } @else {
+      <i class="fas fa-save"></i> Save }
+    </button>
+  </div>
+</form>
+```
+
+## Notes
+
+- **The error state is two bindings**: `mw-field-has-error` on the wrapper
+  (border and halo) and the `mw-field-error` element (the message). Hint and
+  error should not be visible at the same time.
+- **For a control without a wrapper** - a checkbox group, radio group or slider
+  container - use `mw-form-element-error` instead.
+- **`disabled`/`readonly` are attributes**, not classes. With reactive forms use
+  `control.disable()`; the muted look comes from the `:disabled` selector.
+- **The slider needs two bindings**: `data-value` for the badge text,
+  `--value` for the filled part of the track.
+- **A spinner inside a button** needs its shape class (`mw-spinner-border`) plus
+  a size; the button already provides the gap.
+- Multi-column layout comes from `mw-grid-2` inside the group, a full-width
+  field from `style="grid-column: 1 / -1"`.
+
+## Number formatting
+
+`mw-text-numeric` aligns from the right edge, so it works with both `1,204.50`
+and `1.204,50` - what matters is a constant number of decimals per column. Let
+the pipe do it:
+
+```html
+<td class="mw-text-numeric">
+  {{ invoice.total | currency: 'EUR' : 'symbol' : '1.2-2' }}
+</td>
+<td class="mw-text-numeric">{{ item.amount | number: '1.2-2' }}</td>
+```
+
+```ts
+// app.config.ts
+import { registerLocaleData } from '@angular/common';
+import localeDe from '@angular/common/locales/de';
+
+registerLocaleData(localeDe);
+
+export const appConfig: ApplicationConfig = {
+  providers: [{ provide: LOCALE_ID, useValue: 'de-DE' }],
+};
+```
+
+`'1.2-2'` is the part that keeps the column aligned - it forces exactly two
+decimals. `tabular-nums` only takes effect if the loaded font ships tabular
+figures; the framework bundles no font.