alpine-validation-plugin 1.0.0

package/README.md

@@ -0,0 +1,94 @@
+# alpine-validation-plugin
+
+![license](https://img.shields.io/github/license/tmjaga/alpine-validation-plugin)
+![alpine](https://img.shields.io/badge/alpine.js-v3-blue)
+
+A lightweight, class-based form validation plugin for [Alpine.js](https://alpinejs.dev) v3.
+
+---
+
+## Installation
+
+### NPM
+
+```bash
+npm install alpine-validation-plugin
+```
+
+```js
+import Alpine from 'alpinejs';
+import AlpineValidation from 'alpine-validation-plugin';
+
+Alpine.plugin(AlpineValidation);
+Alpine.start();
+```
+
+### CDN
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/tmjaga/alpine-validation-plugin/src/validation-alpine.js"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>
+```
+
+---
+
+## Quick start
+
+Add CSS class names matching the built-in rules to your inputs.  
+Errors are stored reactively and keyed by the input's `name` / `id` / `data-field`.
+
+```html
+<form x-data x-validate="{ live: true }" @submit.prevent="$validate() && save()">
+
+  <input class="req email" name="email" title="Email" />
+  <span x-text="$validation.errors.email" class="text-red-500 text-sm"></span>
+
+  <input class="req int unsigned" name="age" title="Age" />
+  <span x-text="$validation.errors.age" class="text-red-500 text-sm"></span>
+
+  <p x-show="$validation.hasErrors" class="text-red-600">
+    Please fix the errors above.
+  </p>
+
+  <button type="submit" :disabled="$validation.hasErrors">Save</button>
+
+</form>
+```
+
+---
+
+## Built-in rules
+
+| Class | Description |
+|---|---|
+| `req` | Required (whitespace-only counts as empty) |
+| `email` | Valid email address |
+| `int` | Integer (positive or negative) |
+| `float` | Floating point number |
+| `decimal` | Decimal number |
+| `unsigned` | No negative sign allowed |
+| `nonzero` | Value must not be zero |
+
+---
+
+## Live validation modes
+
+| Directive | When errors appear |
+|---|---|
+| `x-validate` | On submit only |
+| `x-validate="{ live: 'input' }"` | From the first keystroke |
+| `x-validate="{ live: true }"` | On blur, then update while typing |
+| `x-validate="{ live: 'blur' }"` | On blur only |
+
+---
+
+## Documentation
+
+Full API reference, all options, custom rules, and examples:  
+**[docs/validation-alpine.md](docs/validation-alpine.md)**
+
+---
+
+## License
+
+MIT

package/docs/validation-alpine.md

@@ -0,0 +1,490 @@
+# Alpine.js Validation Plugin
+
+A lightweight, class-based form validation plugin for Alpine.js v3.  
+Ported from `com.opencode.Validation` (jQuery).
+
+---
+
+## Installation
+
+### NPM / bundler
+
+```js
+// app.js
+import Alpine from 'alpinejs';
+import AlpineValidation from './validation-alpine.js';
+
+Alpine.plugin(AlpineValidation); // must come before Alpine.start()
+Alpine.start();
+```
+
+### CDN
+
+```html
+<script src="validation-alpine.js"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>
+```
+
+---
+
+## Core concept
+
+Validation rules are identified by **CSS class names** on input elements.  
+Add the class to an input and the plugin handles the rest.
+
+```html
+<input class="req email" name="email" />
+<!--         ^^^  ^^^^^
+             |    └─ email format check
+             └─ required field -->
+```
+
+The **field key** used to store errors is resolved in this order:
+
+1. `data-field="..."` attribute
+2. `name="..."` attribute  
+3. `id="..."` attribute
+
+---
+
+## Built-in rules
+
+| Class      | Description                               | Error message                         |
+|------------|-------------------------------------------|---------------------------------------|
+| `req`      | Field is required (trims whitespace)      | `"{title}" is required`               |
+| `email`    | Valid email address                       | `Invalid email address`               |
+| `int`      | Integer (positive or negative)            | `Invalid integer value`               |
+| `float`    | Floating point number                     | `Invalid floating point value`        |
+| `decimal`  | Decimal number                            | `Invalid decimal value`               |
+| `unsigned` | No negative sign allowed                  | `The value cannot be negative`        |
+| `nonzero`  | Value must not be zero                    | `The value cannot be zero`            |
+
+> **`req` + whitespace** — a value of `"   "` (spaces only) is treated as empty.
+
+Multiple rules can be combined on a single input:
+
+```html
+<input class="req int unsigned" name="quantity" title="Quantity" />
+<!-- required + must be integer + cannot be negative -->
+```
+
+---
+
+## Directive: `x-validate`
+
+Place on the `<form>` or any wrapper element that contains the validated inputs.  
+Event listeners are **delegated** to this root element — no per-input attributes needed.
+
+### Modes
+
+#### Submit-only (default)
+
+Validation runs only when `$validate()` is called. No live feedback.
+
+```html
+<form x-data x-validate @submit.prevent="$validate() && save()">
+  <input class="req" name="title" title="Title" />
+  <span x-text="$store.validation.errors.title" class="text-red-500 text-sm"></span>
+  <button type="submit">Save</button>
+</form>
+```
+
+#### `live: 'input'` — validate on every keystroke
+
+Error appears immediately as the user types, from the very first character.  
+Best for strict forms where instant feedback is expected.
+
+```html
+<form x-data x-validate="{ live: 'input' }" @submit.prevent="$validate() && save()">
+  <input class="req int" name="age" title="Age" />
+  <span x-text="$store.validation.errors.age" class="text-red-500 text-sm"></span>
+</form>
+```
+
+#### `live: true` — blur first, then live
+
+Error appears only after the user leaves the field for the first time (`blur`).  
+After that, it updates in real time as the user corrects the value.  
+Recommended default — less aggressive, better UX.
+
+```html
+<form x-data x-validate="{ live: true }" @submit.prevent="$validate() && save()">
+  <input class="req email" name="email" title="Email" />
+  <span x-text="$store.validation.errors.email" class="text-red-500 text-sm"></span>
+</form>
+```
+
+#### `live: 'blur'` — blur only, no keystroke reaction
+
+Error appears when the user leaves the field. Does not update while typing.
+
+```html
+<form x-data x-validate="{ live: 'blur' }" @submit.prevent="$validate() && save()">
+  <input class="req" name="username" title="Username" />
+  <span x-text="$store.validation.errors.username" class="text-red-500 text-sm"></span>
+</form>
+```
+
+### Mode comparison
+
+| | `(none)` | `live: 'input'` | `live: true` | `live: 'blur'` |
+|---|:---:|:---:|:---:|:---:|
+| Error on first keystroke | ✗ | ✓ | ✗ | ✗ |
+| Error on blur | ✗ | ✓ | ✓ | ✓ |
+| Updates while typing after blur | ✗ | ✓ | ✓ | ✗ |
+| Error on submit | ✓ | ✓ | ✓ | ✓ |
+
+---
+
+## Magic: `$validate()`
+
+Runs full validation on the nearest `x-validate` root.  
+Clears previous errors, populates `$validation.errors`, focuses the first invalid field, and returns `true` or `false`.
+
+```html
+<!-- Inline in template -->
+<button @click.prevent="$validate() && save()">Submit</button>
+```
+
+```js
+// Inside Alpine.data()
+Alpine.data('myForm', () => ({
+  submit() {
+    if (!this.$validate()) return; // errors are already reactive
+    fetch('/api/save', { method: 'POST', body: JSON.stringify(this.fields) });
+  },
+}));
+```
+
+---
+
+## Magic: `$validation`
+
+Shorthand for `$store.validation`. Available inside any Alpine component.
+
+### Display errors
+
+```html
+<!-- Error message for a specific field -->
+<span x-text="$validation.errors.email" class="text-red-500 text-sm"></span>
+
+<!-- Show/hide a block when a field has an error -->
+<p x-show="$validation.errors.price" class="text-red-500 text-sm">
+  Please enter a valid price.
+</p>
+
+<!-- Global error banner -->
+<div x-show="$validation.hasErrors" class="rounded bg-red-50 px-4 py-3 text-red-700">
+  Please fix the errors below before saving.
+</div>
+
+<!-- Disable submit button while errors exist -->
+<button :disabled="$validation.hasErrors" type="submit">Save</button>
+```
+
+### Touched state
+
+`touched[fieldKey]` becomes `true` after the user leaves the field at least once.  
+Useful to show errors only after interaction:
+
+```html
+<span x-show="$validation.touched.email && $validation.errors.email"
+      x-text="$validation.errors.email"
+      class="text-red-500 text-sm">
+</span>
+```
+
+### Clear errors
+
+```js
+this.$validation.clearErrors();           // reset all errors and touched state
+this.$validation.clearErrors('email');    // reset only the email field
+```
+
+---
+
+## Store API: `$store.validation`
+
+The same object as `$validation`, accessible from anywhere including outside Alpine components.
+
+| Property / Method | Type | Description |
+|---|---|---|
+| `errors` | `Object` | Reactive map `{ fieldKey: 'error message' }` |
+| `touched` | `Object` | Reactive map `{ fieldKey: true }` |
+| `hasErrors` | `boolean` (getter) | `true` if `errors` has at least one key |
+| `touch(fieldKey, el)` | `void` | Mark field as touched and validate it |
+| `validateField(fieldKey, el)` | `void` | Validate one field, update `errors[fieldKey]` |
+| `validate(root?)` | `boolean` | Validate all fields inside `root`, return pass/fail |
+| `clearErrors(field?)` | `void` | Clear errors (and touched) for one field or all |
+| `addRules(...ruleSets)` | `void` | Add or overwrite rules |
+| `delRules(...classNames)` | `void` | Remove rules by class name |
+| `flushRules()` | `void` | Remove all rules |
+| `addCheck(fn)` | `void` | Register a global error suppressor |
+| `delCheck()` | `void` | Remove the suppressor |
+| `toString()` | `string` | Debug summary of all registered rules |
+
+---
+
+## Adding custom rules
+
+Register custom rules in `app.js` before `Alpine.start()`:
+
+```js
+Alpine.plugin(AlpineValidation);
+
+Alpine.store('validation').addRules({
+  // Regexp rule
+  phone: {
+    regexp: /^\+?\d{10,}$/,
+    msg: 'Please enter a valid phone number',
+  },
+
+  // Function rule — return truthy to trigger an error
+  future: {
+    func: (el) => new Date(el.value) <= new Date(),
+    msg: 'Date must be in the future',
+  },
+
+  // URL
+  url: {
+    regexp: /^https?:\/\/.+\..+/,
+    msg: 'Please enter a valid URL (must start with http:// or https://)',
+  },
+
+  // Slug
+  slug: {
+    regexp: /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+    msg: 'Only lowercase letters, numbers and hyphens allowed',
+  },
+});
+
+Alpine.start();
+```
+
+```html
+<input class="req phone" name="phone" title="Phone number" />
+<span x-text="$validation.errors.phone" class="text-red-500 text-sm"></span>
+
+<input class="req future" name="event_date" title="Event date" type="date" />
+<span x-text="$validation.errors.event_date" class="text-red-500 text-sm"></span>
+```
+
+---
+
+## Removing rules
+
+### `delRules(...classNames)` — remove specific rules
+
+Use when you want to disable one or more built-in rules for your project,
+or remove a custom rule that is no longer needed.
+
+```js
+// Remove a single built-in rule
+Alpine.store('validation').delRules('nonzero');
+
+// Remove multiple rules at once
+Alpine.store('validation').delRules('unsigned', 'nonzero', 'float');
+```
+
+A practical example — your app only works with text fields, so numeric rules are unnecessary:
+
+```js
+Alpine.plugin(AlpineValidation);
+
+// Strip out all numeric rules, keep only req and email
+Alpine.store('validation').delRules('int', 'float', 'decimal', 'unsigned', 'nonzero');
+
+Alpine.start();
+```
+
+Another example — remove a custom rule dynamically based on user role:
+
+```js
+if (window.currentUser?.isAdmin) {
+  // Admins are not required to fill in the phone field
+  Alpine.store('validation').delRules('phone');
+}
+```
+
+### `flushRules()` — remove all rules
+
+Wipes the entire rule set. Useful when you want to start from scratch
+and register only your own custom rules:
+
+```js
+Alpine.plugin(AlpineValidation);
+
+// Remove every built-in rule
+Alpine.store('validation').flushRules();
+
+// Register only what your app actually needs
+Alpine.store('validation').addRules({
+  req:   { req: true },
+  email: { regexp: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, msg: 'Invalid email address' },
+  phone: { regexp: /^\+?\d{10,}$/,               msg: 'Invalid phone number' },
+});
+
+Alpine.start();
+```
+
+---
+
+## Global error suppressor
+
+`addCheck` registers a function called after every rule failure.  
+If it returns `true`, the error is suppressed and the field is treated as valid.
+
+```js
+// Skip validation for fields that are currently hidden
+Alpine.store('validation').addCheck((el, rule) => {
+  return el.closest('[x-show]') !== null && el.offsetParent === null;
+});
+```
+
+```js
+// Allow admins to bypass required fields
+Alpine.store('validation').addCheck((el, rule) => {
+  return rule.req && window.currentUser?.isAdmin === true;
+});
+```
+
+Remove it when no longer needed:
+
+```js
+Alpine.store('validation').delCheck();
+```
+
+---
+
+## Error label resolution for `req`
+
+The error message includes the field label when it can be found.  
+Resolution order:
+
+1. `title="..."` attribute on the input
+2. Text of `<label for="fieldId">` found in the DOM
+3. Fallback generic message
+
+```html
+<!-- Uses title attribute -->
+<input class="req" name="city" title="City" />
+<!-- Error: "City is required" -->
+
+<!-- Uses associated <label> -->
+<label for="country">Country</label>
+<input class="req" id="country" name="country" />
+<!-- Error: "Country is required" -->
+
+<!-- Fallback -->
+<input class="req" name="x" />
+<!-- Error: "Please fill in the required fields." -->
+```
+
+---
+
+## Manual touch (without x-validate live mode)
+
+If you cannot use the directive's live mode, you can attach events manually:
+
+```html
+<input
+  name="title"
+  class="req"
+  @blur="$validation.touch('title', $el)"
+  @input="$validation.touched.title && $validation.touch('title', $el)"
+/>
+```
+
+Or trigger validation programmatically from JS:
+
+```js
+const el = document.getElementById('price');
+this.$validation.validateField('price', el);
+```
+
+---
+
+## Full example (Laravel Blade)
+
+```html
+<div x-data="albumForm()" class="space-y-6 p-6">
+  <form x-validate="{ live: true }" @submit.prevent="submit">
+    @csrf
+
+    {{-- Title --}}
+    <div class="mb-4">
+      <label for="title" class="block text-sm font-bold text-gray-700">
+        {{ __('Album Title') }} <span class="text-red-500">*</span>
+      </label>
+      <input id="title" name="title" class="req"
+             x-model="title" type="text" title="{{ __('Album Title') }}"
+             class="w-full rounded border border-gray-300 px-3 py-2 text-sm" />
+      <p x-show="$validation.errors.title"
+         x-text="$validation.errors.title"
+         class="mt-1 text-sm text-red-500"></p>
+      @error('title')
+        <p class="mt-1 text-sm text-red-500">{{ $message }}</p>
+      @enderror
+    </div>
+
+    {{-- Release year --}}
+    <div class="mb-4">
+      <label for="year" class="block text-sm font-bold text-gray-700">
+        {{ __('Release Year') }}
+      </label>
+      <input id="year" name="year" class="int unsigned"
+             x-model="year" type="text" title="{{ __('Release Year') }}"
+             class="w-full rounded border border-gray-300 px-3 py-2 text-sm" />
+      <p x-show="$validation.errors.year"
+         x-text="$validation.errors.year"
+         class="mt-1 text-sm text-red-500"></p>
+    </div>
+
+    {{-- Global error banner --}}
+    <div x-show="$validation.hasErrors"
+         class="mb-4 rounded bg-red-50 px-4 py-3 text-sm text-red-700">
+      {{ __('Please fix the errors above before saving.') }}
+    </div>
+
+    <button type="submit"
+            :disabled="$validation.hasErrors"
+            class="rounded bg-blue-600 px-4 py-2 text-sm text-white disabled:opacity-50">
+      {{ __('Save') }}
+    </button>
+  </form>
+</div>
+
+<script>
+Alpine.data('albumForm', () => ({
+  title: @json(old('title', $album->title ?? '')),
+  year:  @json(old('year',  $album->year  ?? '')),
+
+  submit() {
+    this.title = this.title.trim();
+    if (!this.$validate()) return;
+    this.$el.closest('form').submit();
+  },
+}));
+</script>
+```
+
+---
+
+## Debugging
+
+```js
+// Print all registered rules
+console.log(Alpine.store('validation').toString());
+
+// Inspect current errors
+console.log(Alpine.store('validation').errors);
+
+// Inspect which fields have been touched
+console.log(Alpine.store('validation').touched);
+```
+
+```html
+<!-- Render errors inline for debugging -->
+<pre x-text="JSON.stringify($store.validation.errors, null, 2)"></pre>
+<pre x-text="JSON.stringify($store.validation.touched, null, 2)"></pre>
+```

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "alpine-validation-plugin",
+  "version": "1.0.0",
+  "description": "Lightweight class-based form validation plugin for Alpine.js v3",
+  "main": "src/validation-alpine.js",
+  "type": "module",
+  "keywords": [
+    "alpinejs",
+    "alpine",
+    "alpine-plugin",
+    "validation",
+    "form-validation",
+    "form",
+    "plugin"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "alpinejs": ">=3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tmjaga/alpine-validation-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tmjaga/alpine-validation-plugin/issues"
+  },
+  "homepage": "https://github.com/tmjaga/alpine-validation-plugin#readme"
+}

package/src/validation-alpine.js

@@ -0,0 +1,376 @@
+/**
+ * Alpine.js Validation Plugin
+ * Converted from com.opencode.Validation (jQuery)
+ *
+ * Usage:
+ *   1. Register the plugin before Alpine.start():
+ *        Alpine.plugin(AlpineValidation)
+ *
+ *   2. Add x-validate to your form (and x-data on the same or a parent element).
+ *
+ *   3. Add CSS class names matching the built-in rules to your inputs.
+ *      Field errors are keyed by the input's name / id / data-field attribute.
+ *
+ * Quick example:
+ *   <form x-data x-validate="{ live: true }" @submit.prevent="$validate() && save()">
+ *     <input class="req email" name="email" title="Email" />
+ *     <span x-text="$store.validation.errors.email"></span>
+ *     <button type="submit">Save</button>
+ *   </form>
+ */
+
+const AlpineValidation = (Alpine) => {
+
+  // ── Built-in rules ───────────────────────────────────────────────────────────
+  //
+  // Each rule is identified by a CSS class name applied to the input element.
+  // A rule object may contain:
+  //   req    {boolean}  — field is required (whitespace-only counts as empty)
+  //   regexp {RegExp}   — value must match this pattern
+  //   func   {Function} — custom check: receives the element, returns truthy on error
+  //   msg    {string}   — error message shown when regexp or func fails
+  //
+  let rules = {
+    req:      { req: true },
+    float:    { regexp: /^[-+]?\d*\.?\d+$/,                msg: 'Invalid floating point value' },
+    int:      { regexp: /^[-+]?\d+$/,                      msg: 'Invalid integer value' },
+    unsigned: { regexp: /^[^-]*$/,                         msg: 'The value cannot be negative' },
+    nonzero:  { func: (el) => parseFloat(el.value) === 0,  msg: 'The value cannot be zero' },
+    decimal:  { regexp: /^[-+]?((\d+(\.\d+)?)|(\.\d+))$/,  msg: 'Invalid decimal value' },
+    email:    { regexp: /^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$/, msg: 'Invalid email address' },
+  };
+
+  let additionalCheck = null;
+
+  // ── Internal helper ──────────────────────────────────────────────────────────
+  // Runs all matching rules against a single element.
+  // Returns the first error message string, or null if the field is valid.
+  function checkElement(el) {
+    const value = el.value;
+
+    for (const [className, rule] of Object.entries(rules)) {
+      if (!el.classList.contains(className)) continue;
+
+      let error = null;
+
+      if (!value || (rule.req && !value.trim())) {
+        // req rule: whitespace-only value is treated as empty
+        if (rule.req) {
+          const labelText =
+            el.title ||
+            (el.id && document.querySelector(`label[for="${el.id}"]`)?.textContent?.trim());
+          error = labelText ? `${labelText} is required` : 'Please fill in the required fields.';
+        }
+      } else if (rule.regexp && !rule.regexp.test(value)) {
+        error = rule.msg || 'Invalid value.';
+      } else if (rule.func) {
+        const result = rule.func(el);
+        if (result) error = rule.msg || result;
+      }
+
+      if (error) {
+        // additionalCheck can suppress the error by returning true
+        if (additionalCheck && additionalCheck(el, rule)) continue;
+        return error; // stop at first error per field
+      }
+    }
+
+    return null;
+  }
+
+  // ── Alpine store: $store.validation ─────────────────────────────────────────
+  Alpine.store('validation', {
+
+    /** Reactive map of field errors: { fieldKey: 'Error message', ... } */
+    errors:  {},
+
+    /** Tracks which fields the user has already interacted with (touched). */
+    touched: {},
+
+    /** True when at least one error is present. */
+    get hasErrors() {
+      return Object.keys(this.errors).length > 0;
+    },
+
+    // ── Live validation ────────────────────────────────────────────────────────
+
+    /**
+     * Mark a field as touched and validate it immediately.
+     *
+     * Called automatically by the x-validate directive when live mode is active.
+     * Can also be called manually when you need fine-grained control:
+     *
+     *   <input name="title"
+     *          @blur="$validation.touch('title', $el)"
+     *          @input="$validation.touched.title && $validation.touch('title', $el)" />
+     *
+     * @param {string} fieldKey  — name / id / data-field value of the input
+     * @param {Element} el       — the input element
+     */
+    touch(fieldKey, el) {
+      this.touched[fieldKey] = true;
+      this.validateField(fieldKey, el);
+    },
+
+    /**
+     * Validate a single field and update errors[fieldKey].
+     * Useful when you want to re-check one field programmatically:
+     *
+     *   this.$validation.validateField('price', document.getElementById('price'));
+     *
+     * @param {string} fieldKey
+     * @param {Element} el
+     */
+    validateField(fieldKey, el) {
+      delete this.errors[fieldKey];
+      const error = checkElement(el);
+      if (error) this.errors[fieldKey] = error;
+    },
+
+    // ── Full validation (submit) ───────────────────────────────────────────────
+
+    /**
+     * Validate all rule-bearing fields inside root.
+     * Clears previous errors, populates errors{} with all failures,
+     * focuses the first invalid field, and returns true/false.
+     *
+     * Called automatically by $validate(). Rarely needed directly.
+     *
+     * @param {Element} root  — defaults to document
+     * @returns {boolean}
+     */
+    validate(root = document) {
+      // Clear all previous errors
+      Object.keys(this.errors).forEach((k) => delete this.errors[k]);
+
+      let valid        = true;
+      let firstInvalid = null;
+
+      for (const [className] of Object.entries(rules)) {
+        root.querySelectorAll(`.${className}`).forEach((el) => {
+          const fieldKey = el.dataset.field || el.name || el.id || null;
+          const error    = checkElement(el);
+
+          if (error) {
+            // Keep the first error per field key
+            if (fieldKey && !this.errors[fieldKey]) this.errors[fieldKey] = error;
+            if (!firstInvalid) firstInvalid = el;
+            valid = false;
+          }
+        });
+      }
+
+      // Focus the first invalid field; switch tab if a tabber is present
+      if (firstInvalid) {
+        const tabber = root.querySelector('#element-tabber');
+        if (tabber) {
+          const tab = firstInvalid.closest('.tabbertab');
+          if (tab) {
+            const tabs  = [...tabber.querySelectorAll(':scope > .tabbertab')];
+            const index = tabs.indexOf(tab);
+            if (index !== -1 && tabber._tabber) tabber._tabber.tabShow(index);
+          }
+        }
+        firstInvalid.focus();
+        if (typeof firstInvalid.select === 'function') firstInvalid.select();
+      }
+
+      return valid;
+    },
+
+    // ── Error management ──────────────────────────────────────────────────────
+
+    /**
+     * Clear errors (and touched state) for one field or all fields.
+     *
+     *   $validation.clearErrors()          // clear everything
+     *   $validation.clearErrors('email')   // clear only email
+     *
+     * @param {string|null} field
+     */
+    clearErrors(field = null) {
+      if (field) {
+        delete this.errors[field];
+        delete this.touched[field];
+      } else {
+        Object.keys(this.errors).forEach((k)  => delete this.errors[k]);
+        Object.keys(this.touched).forEach((k) => delete this.touched[k]);
+      }
+    },
+
+    // ── Rule management ───────────────────────────────────────────────────────
+
+    /**
+     * Add or overwrite one or more rules.
+     *
+     *   $store.validation.addRules({
+     *     phone: { regexp: /^\+?\d{10,}$/, msg: 'Invalid phone number' },
+     *     slug:  { regexp: /^[a-z0-9-]+$/, msg: 'Only lowercase letters, numbers and hyphens' },
+     *   });
+     *
+     * @param {...Object} ruleSets
+     */
+    addRules(...ruleSets) {
+      ruleSets.forEach((set) => Object.assign(rules, set));
+    },
+
+    /**
+     * Remove rules by class name.
+     *
+     *   $store.validation.delRules('nonzero', 'unsigned');
+     *
+     * @param {...string} classNames
+     */
+    delRules(...classNames) {
+      classNames.forEach((name) => delete rules[name]);
+    },
+
+    /** Remove all rules. */
+    flushRules() {
+      rules = {};
+    },
+
+    /**
+     * Register a global additional check.
+     * Called after a rule fails; if it returns true the error is suppressed.
+     *
+     *   $store.validation.addCheck((el, rule) => {
+     *     // e.g. skip validation for hidden fields
+     *     return el.closest('[hidden]') !== null;
+     *   });
+     *
+     * @param {Function} check  — (element, rule) => boolean
+     */
+    addCheck(check) {
+      if (typeof check !== 'function') throw new Error('The check is not a function');
+      if (check.length !== 2)          throw new Error('The check function must have two parameters');
+      additionalCheck = check;
+    },
+
+    /** Remove the global additional check. */
+    delCheck() {
+      additionalCheck = null;
+    },
+
+    /** Return a human-readable summary of all registered rules (useful for debugging). */
+    toString() {
+      return Object.entries(rules)
+        .map(([className, rule]) => {
+          const parts = [];
+          if (rule.req)    parts.push('Required');
+          if (rule.regexp) parts.push(`RegExp: ${rule.regexp}`);
+          if (rule.func)   parts.push('Has check function');
+          if (rule.msg)    parts.push(`Error Message: ${rule.msg}`);
+          return `.${className}: ${parts.join('; ')}`;
+        })
+        .join('\n');
+    },
+  });
+
+  // ── x-validate directive ──────────────────────────────────────────────────────
+  //
+  // Place on the form (or any wrapper element) that contains the validated inputs.
+  //
+  // Modes:
+  //   x-validate                      — submit-only validation
+  //   x-validate="{ live: true }"     — validate on blur + re-validate on every keystroke
+  //   x-validate="{ live: 'blur' }"   — validate on blur only (no keystroke re-validation)
+  //
+  // Event listeners are delegated to the root element, so no per-input attributes needed.
+  //
+  Alpine.directive('validate', (el, { expression }, { evaluateLater, effect, cleanup }) => {
+    el._alpineValidationRoot = el;
+
+    if (!expression) return;
+
+    const store      = Alpine.store('validation');
+    const getOptions = evaluateLater(expression);
+    let   live       = false;
+
+    const onBlur = (e) => {
+      const target = e.target;
+      // Ignore elements that don't carry any validation rule class
+      if (!Object.keys(rules).some((c) => target.classList.contains(c))) return;
+      const field = target.dataset.field || target.name || target.id;
+      if (!field) return;
+      store.touch(field, target);
+    };
+
+    const onInput = (e) => {
+      if (live === 'blur') return; // blur-only mode — ignore keystrokes
+      const target = e.target;
+      if (!Object.keys(rules).some((c) => target.classList.contains(c))) return;
+      const field = target.dataset.field || target.name || target.id;
+      if (!field) return;
+      // live: true     — validate only after the field was blurred at least once
+      // live: 'input'  — validate immediately on every keystroke
+      if (live !== 'input' && !store.touched[field]) return;
+      store.validateField(field, target);
+    };
+
+    effect(() => {
+      getOptions((options) => {
+        live = options?.live ?? false;
+        if (live) {
+          // Delegate to root — no need to attach listeners to individual inputs
+          el.addEventListener('blur',  onBlur,  { capture: true });
+          el.addEventListener('input', onInput, { capture: true });
+        }
+      });
+    });
+
+    // Remove listeners when the component is destroyed
+    cleanup(() => {
+      el.removeEventListener('blur',  onBlur,  { capture: true });
+      el.removeEventListener('input', onInput, { capture: true });
+    });
+  });
+
+  // ── $validate() magic ─────────────────────────────────────────────────────────
+  //
+  // Walks up the DOM to find the nearest x-validate root, then runs full validation.
+  // Returns true if all fields pass, false otherwise.
+  //
+  // Usage in templates:
+  //   <button @click.prevent="$validate() && save()">Submit</button>
+  //
+  // Usage in Alpine.data components:
+  //   submit() {
+  //     if (!this.$validate()) return;
+  //     // ... send data
+  //   }
+  //
+  Alpine.magic('validate', (el) => {
+    return () => {
+      let root = el;
+      while (root && !root.hasAttribute('x-validate')) {
+        root = root.parentElement;
+      }
+      return Alpine.store('validation').validate(root || document);
+    };
+  });
+
+  // ── $validation magic ─────────────────────────────────────────────────────────
+  //
+  // Shorthand for $store.validation. Available inside any Alpine component.
+  //
+  // Usage:
+  //   $validation.errors.email        — error message for the email field
+  //   $validation.hasErrors           — true if any error is present
+  //   $validation.touched.email       — true if email field was blurred at least once
+  //   $validation.clearErrors()       — reset all errors and touched state
+  //   $validation.clearErrors('email')— reset only the email field
+  //
+  Alpine.magic('validation', () => Alpine.store('validation'));
+};
+
+// ── Export ────────────────────────────────────────────────────────────────────
+export default AlpineValidation;
+
+// CDN / global <script> fallback — auto-registers when Alpine is present
+if (typeof window !== 'undefined') {
+  window.AlpineValidation = AlpineValidation;
+  document.addEventListener('alpine:init', () => {
+    if (window.Alpine) window.Alpine.plugin(AlpineValidation);
+  });
+}