@stacksjs/stx/dist/forms.d.ts

A performant UI Framework. Powered by Bun.

import type { StxOptions } from './types';
/**
 * Process all form-related directives.
 *
 * Processing order:
 * 1. Validation setup (@validate - generates HTML5 attributes)
 * 2. Basic directives (@csrf, @method)
 * 3. Form input directives (@form, @input, @textarea, etc.)
 * 4. Error display directives (@error)
 */
export declare function processForms(template: string, context: Record<string, any>, _filePath: string, options: StxOptions): string;
/**
 * Process basic form directives (@csrf, @method)
 */
export declare function processBasicFormDirectives(template: string, context: Record<string, any>): string;
/**
 * Process form input directives.
 * Handles @form, @input, @textarea, @select, @checkbox, @radio, @label.
 */
export declare function processFormInputDirectives(template: string, context: Record<string, any>, classes?: FormClassConfig): string;
/**
 * Process @error directive for form validation.
 * Renders content only when the specified field has validation errors.
 *
 * @example
 * ```html
 * @error('email')
 *   <span class="error">{{ $message }}</span>
 * @enderror
 * ```
 */
export declare function processErrorDirective(template: string, context: Record<string, any>, _classes?: FormClassConfig): string;
/**
 * Register a custom validation rule.
 *
 * @param name - Rule name
 * @param validator - Validation function returning error message or null
 *
 * @example
 * ```typescript
 * registerValidationRule('phone', (value, params, field) => {
 *   if (!/^\+?[\d\s-]+$/.test(value)) {
 *     return `The ${field} field must be a valid phone number.`
 *   }
 *   return null
 * })
 * ```
 */
export declare function registerValidationRule(name: string, validator: (value: any, params: string[], field: string) => string | null): void;
/**
 * Validate a single field value against rules.
 *
 * @param field - Field name
 * @param value - Field value
 * @param rules - Pipe-separated rules (e.g., 'required|email|max:255')
 * @param context - Context for accessing other field values (for confirmed rule)
 * @returns Validation result
 */
export declare function validateField(field: string, value: any, rules: string, context?: Record<string, any>): FieldValidationResult;
/**
 * Validate multiple fields.
 *
 * @param data - Object with field values
 * @param rules - Object mapping field names to rule strings
 * @returns Object with errors per field (empty if valid)
 *
 * @example
 * ```typescript
 * const errors = validateFields(
 *   { email: 'test', password: '123' },
 *   { email: 'required|email', password: 'required|min:8' }
 * )
 * // => { email: ['The email field must be a valid email address.'], password: ['The password field must be at least 8 characters.'] }
 * ```
 */
export declare function validateFields(data: Record<string, any>, rules: Record<string, string>): Record<string, string[]>;
/**
 * Process @validate directive.
 * Adds validation attributes to the next form element.
 *
 * Usage:
 * ```html
 * @validate('email', 'required|email|max:255')
 * @input('email')
 *
 * @validate('password', 'required|min:8', { message: 'Password too short' })
 * @input('password', '', { type: 'password' })
 * ```
 */
export declare function processValidateDirective(template: string, _context: Record<string, any>): string;
/**
 * Register a custom enhanced validation rule
 */
export declare function registerEnhancedValidationRule(rule: EnhancedValidationRule): void;
/**
 * Validate a single value against enhanced rules
 */
export declare function validateValueEnhanced(value: unknown, rules: string, allValues?: Record<string, unknown>): { valid: boolean, errors: string[] };
/**
 * Validate multiple values with enhanced validation
 */
export declare function validateFormEnhanced(values: Record<string, unknown>, rules: Record<string, string>): { valid: boolean, errors: Record<string, string[]> };
/**
 * Generate client-side validation script for a form
 */
export declare function generateValidationScript(formId: string, rules: Record<string, string>): string;
/**
 * Default form class configuration (Bootstrap-compatible)
 */
export declare const defaultFormClasses: FormClassConfig;
/**
 * Enhanced validation rules registry with full validation support
 */
export declare const enhancedValidationRules: {
  required: { name: 'required'; validate: (value) => unknown; toHtml5: () => unknown; message: 'This field is required' };
  email: { name: 'email'; validate: (value) => unknown };
  url: { name: 'url'; validate: (value) => unknown };
  numeric: { name: 'numeric'; validate: (value) => unknown; toHtml5: () => unknown };
  integer: { name: 'integer'; validate: (value) => unknown; message: 'Please enter a whole number' };
  alpha: { name: 'alpha'; validate: (value) => unknown; toHtml5: () => unknown };
  alphanumeric: { name: 'alphanumeric'; validate: (value) => unknown; toHtml5: () => unknown };
  min: { name: 'min'; validate: (value, params) => unknown };
  max: { name: 'max'; validate: (value, params) => unknown };
  between: { name: 'between'; validate: (value, params) => unknown; toHtml5: unknown };
  confirmed: { name: 'confirmed'; validate: (value, _params, allValues) => unknown };
  in: { name: 'in'; validate: (value, params) => unknown; message: 'Must be one of: {{values}}' };
  notIn: { name: 'notIn'; validate: (value, params) => unknown; message: 'Must not be: {{values}}' };
  regex: { name: 'regex'; validate: (value, params) => unknown };
  date: { name: 'date'; validate: (value) => unknown };
  before: { name: 'before'; validate: (value, params) => unknown };
  after: { name: 'after'; validate: (value, params) => unknown };
  size: { name: 'size'; validate: (value, params) => unknown };
  phone: { name: 'phone'; validate: (value) => unknown }
};
/**
 * Default CSS class names for form elements.
 * Based on Bootstrap conventions but fully customizable.
 */
export declare interface FormClassConfig {
  input: string
  inputError: string
  checkInput: string
  label: string
  errorFeedback: string
}
/**
 * Validation rule definition
 */
export declare interface ValidationRule {
  name: string
  params?: string[]
  message?: string
}
/**
 * Validation result for a single field
 */
export declare interface FieldValidationResult {
  field: string
  valid: boolean
  errors: string[]
}
/**
 * Enhanced validation rule definition with HTML5 support
 */
export declare interface EnhancedValidationRule {
  name: string
  validate: (value: unknown, params: string[], allValues: Record<string, unknown>) => true | string
  toHtml5?: (params: string[]) => string[]
  message: string
}