@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
173 lines • 5.85 kB
TypeScript
export type { ValidatorFn, AsyncValidatorFn, ValidatorRule, FieldState, FormState };
/**
* Define a form with validation schema.
*
* @example
* ```typescript
* const form = defineForm({
* email: v.required().email(),
* password: v.required().min(8),
* age: v.number().between(18, 100)
* })
*
* // Access form state
* form.values.email
* form.errors.email
* form.isValid
*
* // Validate
* await form.validate()
*
* // Handle submit
* form.handleSubmit((values) => {
* console.log(values)
* })
* ```
*/
export declare function defineForm<T extends Record<string, Validator>>(schema: T, initialValues?: Partial<{ [K in keyof T]: unknown }>): FormState<T>;
/**
* Process @error directive in templates
*
* @example
* ```html
* @error(form.email)
* <span class="text-red-500">{{ message }}</span>
* @enderror
* ```
*/
export declare function processErrorDirective(content: string, context: Record<string, unknown>, _filePath?: string): string;
/**
* Process @errors directive (shows all errors for a field)
*
* @example
* ```html
* @errors(form.password)
* <li>{{ message }}</li>
* @enderrors
* ```
*/
export declare function processErrorsDirective(content: string, context: Record<string, unknown>, _filePath?: string): string;
/**
* Process @hasErrors directive (conditional block if field has errors)
*
* @example
* ```html
* @hasErrors(form.email)
* <div class="error-container">
* ...
* </div>
* @endhasErrors
* ```
*/
export declare function processHasErrorsDirective(content: string, context: Record<string, unknown>, _filePath?: string): string;
/**
* Process all form validation directives
*/
export declare function processFormValidationDirectives(content: string, context: Record<string, unknown>, filePath?: string): string;
/**
* Starting point for building validation rules.
*
* @example
* ```typescript
* v.required().email()
* v.required().min(8).hasUppercase()
* v.number().between(1, 100)
* ```
*/
export declare const v: Validator;
declare interface ValidatorRule {
name: string
validate: ValidatorFn | AsyncValidatorFn
message: string
async?: boolean
}
declare interface FieldState {
value: unknown
errors: string[]
touched: boolean
dirty: boolean
valid: boolean
validating: boolean
}
declare interface FormState<T extends Record<string, Validator>> {
values: { [K in keyof T]: unknown }
errors: { [K in keyof T]: string[] }
touched: { [K in keyof T]: boolean }
dirty: { [K in keyof T]: boolean }
isValid: boolean
isValidating: boolean
isDirty: boolean
validate: () => Promise<boolean>
validateField: (field: keyof T) => Promise<boolean>
reset: () => void
setValues: (values: Partial<{ [K in keyof T]: unknown }>) => void
setFieldValue: (field: keyof T, value: unknown) => void
setFieldTouched: (field: keyof T, touched?: boolean) => void
getFieldState: (field: keyof T) => FieldState
handleSubmit: (onSubmit: (values: { [K in keyof T]: unknown }) => void | Promise<void>) => (e?: Event) => Promise<void>
}
/**
* STX Form Validation
*
* A simple, chainable form validation API.
*
* @example
* ```typescript
* import { defineForm, v } from 'stx'
*
* const form = defineForm({
* email: v.required().email(),
* password: v.required().min(8),
* age: v.number().between(18, 100)
* })
* ```
*/
// =============================================================================
// Types
// =============================================================================
declare type ValidatorFn = (value: unknown, formValues?: Record<string, unknown>) => true | string
declare type AsyncValidatorFn = (value: unknown, formValues?: Record<string, unknown>) => Promise<true | string>
// =============================================================================
// Validator Class
// =============================================================================
declare class Validator {
private rules: ValidatorRule[];
private defaultValue: unknown;
private addRule(rule: ValidatorRule): Validator;
required(message?: any): Validator;
email(message?: any): Validator;
url(message?: any): Validator;
min(length: number, message?: string): Validator;
max(length: number, message?: string): Validator;
length(min: number, max: number, message?: string): Validator;
pattern(regex: RegExp, message?: any): Validator;
hasUppercase(message?: any): Validator;
hasLowercase(message?: any): Validator;
hasNumber(message?: any): Validator;
hasSpecial(message?: any): Validator;
alphanumeric(message?: any): Validator;
startsWithLetter(message?: any): Validator;
noSpaces(message?: any): Validator;
number(message?: any): Validator;
integer(message?: any): Validator;
positive(message?: any): Validator;
negative(message?: any): Validator;
minValue(min: number, message?: string): Validator;
maxValue(max: number, message?: string): Validator;
between(min: number, max: number, message?: string): Validator;
matches(fieldName: string, message?: string): Validator;
oneOf(values: unknown[], message?: string): Validator;
notOneOf(values: unknown[], message?: string): Validator;
date(message?: any): Validator;
before(date: Date | string, message?: string): Validator;
after(date: Date | string, message?: string): Validator;
custom(fn: ValidatorFn, message?: any): Validator;
async(fn: AsyncValidatorFn, message?: any): Validator;
when(condition: (value: unknown, formValues: Record<string, unknown>) => boolean, thenValidator: Validator): Validator;
getRules(): ValidatorRule[];
getDefaultValue(): unknown;
default(value: unknown): Validator;
validate(value: unknown, formValues?: Record<string, unknown>): Promise<string[]>;
validateSync(value: unknown, formValues?: Record<string, unknown>): string[];
}
export { Validator };