repository·main·Indexed 19 days ago
https://github.com/victorgarciaesgi/regleA headless, model-based form validation library for Vue 3. Regle provides a type-safe, modular approach to validation that mirrors data model structures, featuring async validation, SSR compatibility, and support for Standard Schema specifications including Zod, Valibot, and ArkType. It includes a core library (@regle/core), a rules package (@regle/rules), and an MCP server (@regle/mcp-server) for AI assistant integration.
The regle-advanced skill provides advanced form validation patterns for Regle in Vue 3. It is designed for complex scenarios such as validating arrays of fields, handling asynchronous or server-side errors, managing form variants (discriminated unions), and implementing cross-component scoped validation.
Requirements:
Regle provides six specialized skills to help AI agents handle different aspects of the library:
regle: Core usage including the useRegle composable, validation properties ($invalid, $dirty, $error, $errors, $pending), error display methods (getErrors, flatErrors), and modifiers (autoDirty, lazy, silent, rewardEarly, validationGroups).regle-rules: Validation rules including built-in rules (required, email, minLength), custom rule creation (createRule), rule wrappers (withMessage, withParams, withAsync, withTooltip), and rule operators (and, or, xor, not, pipe, applyIf, assignIf).regle-advanced: Advanced patterns such as collections ($each), async validation, server errors (externalErrors), form resetting ($reset), global configuration (defineRegleConfig), variants (createVariant), scoped validation (useScopedRegle), and merging Regles (mergeRegles).regle-schemas: Schema integration using useRegleSchema with libraries like Zod, Valibot, or ArkType, and support for the Standard Schema spec (useRules, refineRules, InferInput).regle-typescript: TypeScript integration for type-safe output (InferSafeOutput), typing rules (inferRules), and typing component props (InferRegleRoot, RegleFieldStatus).regle-migrate-vuelidate: A migration guide for porting Vuelidate forms (useVuelidate) to Regle (useRegle or useScopedRegle).Regle is a headless form validation library for Vue.js. It provides a type-safe, model-based, and intuitive API designed as an evolution of Vuelidate. Because it is 'headless', it manages the validation logic and state without forcing a specific UI implementation, allowing you to build any interface you need.
Key features include:
The Regle MCP (Model Context Protocol) server allows AI assistants to interact with Regle's ecosystem. By integrating this server, your AI assistant can access Regle's documentation and API details to help you write validation rules more effectively.
Key capabilities provided to the AI assistant include:
When a form has fields that depend on a condition or a toggle (discriminated unions), use createVariant to declare the different states and narrowVariant to safely access fields within specific UI blocks. This ensures that fields are only accessible when the current state of the form makes them valid, maintaining both runtime safety and TypeScript accuracy.
<template>
<div v-if="narrowVariant(r$, 'type', 'EMAIL')">
<!-- `email` is a known field only in this block -->
<input v-model="r$.email.$value" placeholder='Email'/>
<Errors :errors="r$.email.$errors"/>
</div>
<div v-else-if="narrowVariant(r$, 'type', 'GITHUB')">
<!-- `username` is a known field only in this block -->
<input v-model="r$.username.$value" placeholder='Email'/>
<Errors :errors="r$.username.$errors"/>
</div>
</template>
<script setup lang='ts'>
import { useRegle, createVariant, narrowVariant } from '@regle/core';
const state = ref<FormState>({})
const {r$} = useRegle(state, () => {
const variant = createVariant(state, 'type', [
{type: { literal: literal('EMAIL')}, email: { required, email }},
{type: { literal: literal('GITHUB')}, username: { required }},
{type: { required }},
]);
return {
firstName: { required },
...variant.value,
};
})
</script>When deciding how to combine rules, choose between and and pipe based on how you want errors to be reported and how rules should execute:
| Feature | and | pipe |
|---|---|---|
| Execution | All rules run simultaneously. | Sequential; later rules only run if earlier ones pass. |
| Error Reporting | All errors from all rules are shown at once. | Only the first failing rule in the chain reports an error. |
| Use Case | When you want to show all validation errors immediately. | When you want to avoid running complex rules if simple ones fail. |
When built-in rules from @regle/rules are insufficient, you can create custom rules in two ways:
createRule: Use this function to create reusable rule definitions.Custom rules can also support reactive parameters and asynchronous validation.
Validation groups allow you to group specific fields together to track their combined status (e.g., checking if an entire section of a form is valid). You define groups using the validationGroups function in the third argument of useRegle. You can then access the group status via r$.$groups.<groupName>.$invalid, r$.$groups.<groupName>.$errors, etc.
const { r$ } = useRegle(
{ email: '', user: { firstName: '' } },
{
email: { required },
user: { firstName: { required } },
},
{
validationGroups: (fields) => ({
group1: [fields.email, fields.user.firstName],
}),
}
);
// Access: r$.$groups.group1.$invalid, r$.$groups.group1.$errors, etc.Regle is a lightweight, low-boilerplate alternative to Tanstack Forms for Vue developers.
Rule wrappers allow you to customize or upgrade your rules by injecting or replacing specific properties like error messages, external parameters, or async behavior. They are imported from @regle/rules and can be applied to individual rules within the useRegle configuration object.
import { withMessage } from '@regle/rules';
const { r$ } = useRegle({ name: '' }, {
name: {
customRule: withMessage((value) => !!value, "Custom Error"),
}
});Regle replaces the Vuelidate concept of 'Nested Component Validation' with Scoped Validation. This allows parents to collect validation states from children using scopes.
In the child, use useScopedRegle to define validations within a specific scope.
import { useScopedRegle } from '@regle/core';
// The { namespace: 'foo' } defines the scope name
const { r$ } = useScopedRegle(state, validations, { namespace: 'foo' });In the parent, use useCollectScope to gather validation results from children matching that scope.
import { useCollectScope } from '@regle/core';
// Collect all validation states from children using scope 'foo'
const { r$ } = useCollectScope('foo');Regle provides operators to compose complex validation logic by combining multiple rules or applying them conditionally:
and, or, xor, not.applyIf (apply rules based on a condition), assignIf (assign rules based on a condition).pipe (chain rules sequentially).