noob-components/.trellis/spec/plugs-element/rule.md

rule

Form validation rule classes extending Element Plus validation schema.

Source

File: plugs/element/rule.ts

---

Overview

All rule classes follow Element Plus rule schema:

{
  required?: boolean;
  trigger?: 'blur' | 'change' | ['blur', 'change'];
  validator?: (rule: any, value: any, callback: Function) => void;
  // ... other Element Plus rule properties
}

All classes include i18n integration via plugs/i18n.

---

SimpleRequired

Validates required fields with optional selection mode for dropdowns.

Signature

export class SimpleRequired {
  required = true;
  trigger = 'blur' | 'change';
  name?: string;
  selection?: boolean;
  validator: (rule, value, callback) => void;
  constructor(name?: string, selection?: boolean);
}

Usage

import { SimpleRequired } from 'plugs/element/rule';

// Text input
new SimpleRequired('Username').validator;
// -> { required: true, trigger: 'blur', ... }

// Dropdown selection
new SimpleRequired('Country', true).validator;
// -> { required: true, trigger: 'change', ... }

Error Messages

Scenario	Message
Empty text input	t('rule.pleaseEnter') + t(this.name).toLowerCase()
Empty dropdown	t('rule.pleaseSelect') + t(this.name).toLowerCase()
Null/undefined	t('rule.notNull')

---

SimpleCharacter

Validates string length constraints.

Signature

export class SimpleCharacter {
  max: number;
  min?: number;
  trigger = 'blur';
  validator: (rule, value, callback) => void;
  constructor(max?: number, min?: number);
}

Usage

import { SimpleCharacter } from 'plugs/element/rule';

new SimpleCharacter(100);        // Max 100 chars
new SimpleCharacter(10, 3);      // 3-10 chars

Error Messages

Scenario	Message Key	Example
Too long	rule.maxLen	'Maximum 100 characters'
Too short	rule.minLen	'Minimum 3 characters'

---

Character

Base class for regex pattern validation.

Signature

export class Character {
  pattern: RegExp;
  trigger = 'blur';
  validator: (rule, value, callback) => void;
  constructor(pattern: RegExp);
}

Usage

import { Character } from 'plugs/element/rule';

new Character(/^[A-Z]{3}$/);  // Exactly 3 uppercase letters

Error Message

t('rule.formatErr') - generic format error when pattern fails.

---

SimpleNumber

Validates integer input with optional range.

Signature

export class SimpleNumber {
  trigger = 'blur';
  min?: number;
  max?: number;
  validator: (rule, value, callback) => void;
  constructor(min?: number, max?: number);
}

Usage

import { SimpleNumber } from 'plugs/element/rule';

new SimpleNumber(1, 100);      // Integer 1-100
new SimpleNumber(0);            // Non-negative integer
new SimpleNumber();             // Any integer

Validation Rules

1. Must match /^(0|-?[1-9]\d*)$/ (integers only, including 0)
2. Range check against this.min and this.max

Error Messages

Scenario	Message
Non-integer	t('rule.pleaseEnter') + t('rule.int').toLowerCase()
Below min	t('rule.min', [this.min])
Above max	t('rule.max', [this.max])

---

Hexadecimal

Validates hexadecimal string input.

Signature

export class Hexadecimal {
  trigger = 'blur';
  min?: number;
  max?: number;
  validator: (rule, value, callback) => void;
  constructor(min?: number, max?: number);
}

Usage

import { Hexadecimal } from 'plugs/element/rule';

new Hexadecimal(6, 8);  // 6-8 character hex string
new Hexadecimal();      // Any length hex string

Pattern

/^[0-9a-fA-F\s]+$/ - allows digits, letters a-f/A-F, and whitespace.

Error Messages

Scenario	Message Key
Invalid characters	rule.hexadecimal
Below min length	rule.minLen
Above max length	rule.maxLen

---

Geographic Coordinates

Longitude

export class Longitude extends Character;

Pattern: /^-?((0|1?[0-7]?[0-9]?)(([.][0-9]{1,6})?)|180(([.][0]{1,6})?))$/ Range: -180 to 180

Latitude

export class Latitude extends Character;

Pattern: /^[\-\+]?((0|([1-8]\d?))(\.\d{1,10})?|90(\.0{1,10})?)$/ Range: -90 to 90

Usage

import { Longitude, Latitude } from 'plugs/element/rule';

{ validator: new Longitude().validator }
{ validator: new Latitude().validator }

---

Network Identifiers

Email

export class Email extends Character;

Pattern: /^([a-zA-Z0-9_\.\-])+\@(([a-zA-Z0-9\-])+\.)+([a-zA-Z0-9]{2,4})+$/

Phone

export class Phone extends Character;

Pattern: /^(0|86|17951)?(13[0-9]|15[012356789]|17[0135678]|18[0-9]|14[57])[0-9]{8}$/ Supports: China mobile numbers with optional prefixes (0, 86, 17951)

Ipv4

export class Ipv4 extends Character;

Pattern: /^((25[0-5]|2[0-4]\d|[01]?\d\d?)($|(?!\.$)\.)){4}$/

Ipv6

export class Ipv6 extends Character;

Pattern: Full IPv6 regex per RFC 5952.

Usage

import { Email, Phone, Ipv4, Ipv6 } from 'plugs/element/rule';

{ validator: new Email().validator }
{ validator: new Phone().validator }
{ validator: new Ipv4().validator }
{ validator: new Ipv6().validator }

---

IdCard

Chinese Resident ID card number validation.

Signature

export class IdCard {
  trigger = 'blur';
  validator: (rule, value, callback) => void;
}

Validation Steps

1. Format check: /^\d{17}(\d|x)$/i
2. Area code validation: First 2 digits map to Chinese provinces
3. Birthdate validation: Parses and validates YYYY-MM-DD format
4. Checksum: Uses weighted sum algorithm (ISO 7064:1983)

Area Code Map (partial)

const aCity = {
  11: '北京', 12: '天津', 13: '河北', 14: '山西',
  31: '上海', 32: '江苏', 33: '浙江', 34: '安徽',
  51: '四川', 52: '贵州', 53: '云南', 91: '香港', ...
};

Error Messages

Check	Message Key
Invalid format	rule.idCard.format
Unknown area	rule.idCard.area
Invalid birthdate	rule.idCard.birth
Invalid checksum	rule.idCard.error

---

Passwords

SimplePassword

Basic password validation (6-18 chars, no spaces).

export class SimplePassword {
  required = true;
  trigger = 'blur';
  min = 8;
  max = 16;
  validator: (rule, value, callback) => void;
}

Password

Strong password (8-20 chars, must contain 0-9, a-z, A-Z).

export class Password {
  required = true;
  trigger = 'blur';
  min = 8;
  max = 16;
  validator: (rule, value, callback) => void;
}

Pattern: ^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z]).*$

Usage

import { SimplePassword, Password } from 'plugs/element/rule';

{ validator: new SimplePassword().validator }
// Valid: 'abc123', 'password'

{ validator: new Password().validator }
// Valid: 'Pass1234', 'Abc12345'
// Invalid: 'password', '12345678', 'PASSWORD'

Error Messages

Scenario	Message
Empty	t('rule.pleaseEnter') + t('pwd.pwd').toLowerCase()
Length (SimplePassword)	t('pwd.length', [6, 18])
Length (Password)	t('pwd.length', [8, 20])
Missing complexity	t('pwd.required') - "Must contain numbers and uppercase/lowercase"
Has space	t('pwd.noSpace')

---

Username

Alphanumeric username with underscore rules.

export class Username {
  required = true;
  trigger = 'blur';
  min = 4;
  max = 16;
  validator: (rule, value, callback) => void;
}

Rules

1. Length: 4-16 characters
2. Pattern: /^[a-zA-Z0-9]{4,16}$/
3. No leading underscore
4. No consecutive underscores
5. No trailing underscore
6. No spaces

Usage

import { Username } from 'plugs/element/rule';

{ validator: new Username().validator }

Error Messages

Rule	Message Key
Invalid chars/length	rule.username.0
Leading/trailing/consecutive underscores	rule.username.1
Contains space	rule.username.2

---

Name

Chinese and English name validation.

export class Name {
  pattern = new RegExp('^[a-zA-Z\u4e00-\u9fa5]{1,10}$');
  trigger = 'blur';
  validator: (rule, value, callback) => void;
}

Rules

1. Length: 1-10 characters
2. Pattern: Letters and Chinese characters only
3. No numbers, no special characters

Error Message

t('rule.name') - when pattern fails

---

Quick Reference Table

Class	Pattern	Trigger	Use Case
SimpleRequired	-	blur/change	Required fields
SimpleCharacter	length	blur	Text fields with limits
Character	regex	blur	Custom patterns
SimpleNumber	integer + range	blur	Number inputs
Hexadecimal	hex chars	blur	Color codes, offsets
Longitude	-180 to 180	blur	GPS coordinates
Latitude	-90 to 90	blur	GPS coordinates
Email	email format	blur	Email fields
Phone	CN mobile	blur	Phone fields
Ipv4	IPv4 format	blur	IP inputs
Ipv6	IPv6 format	blur	IP inputs
IdCard	CN ID	blur	ID number
SimplePassword	6-18 chars	blur	Basic passwords
Password	8-20 + complexity	blur	Strong passwords
Username	alphanumeric + underscore	blur	Login names
Name	letters + Chinese	blur	Person names

---

Related

• plugs/element/index.ts exports all rule classes
• Uses plugs/i18n for localization
• Validator signature matches Element Plus FormInstance.validate()