@stacksjs/stx 0.2.155 → 0.2.157

package/dist/forms-validation.d.ts

@@ -1,30 +1,151 @@
-export type { ValidatorFn, AsyncValidatorFn, ValidatorRule, FieldState, FormState };
 /**
- * Define a form with validation schema.
+ * STX Form Validation
+ *
+ * A simple, chainable form validation API.
  *
  * @example
  * ```typescript
- * const form = defineForm({
+ * import { useForm, v } from 'stx'
+ *
+ * const form = useForm({
  *   email: v.required().email(),
  *   password: v.required().min(8),
  *   age: v.number().between(18, 100)
  * })
+ * ```
+ */
+type ValidatorFn = (value: unknown, formValues?: Record<string, unknown>) => true | string;
+type AsyncValidatorFn = (value: unknown, formValues?: Record<string, unknown>) => Promise<true | string>;
+interface ValidatorRule {
+    name: string;
+    validate: ValidatorFn | AsyncValidatorFn;
+    message: string;
+    async?: boolean;
+}
+interface FieldState {
+    value: unknown;
+    errors: string[];
+    touched: boolean;
+    dirty: boolean;
+    valid: boolean;
+    validating: boolean;
+}
+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>;
+}
+declare class Validator {
+    private rules;
+    private defaultValue;
+    private addRule;
+    /** Field is required */
+    required(message?: string): Validator;
+    /** Must be a valid email */
+    email(message?: string): Validator;
+    /** Must be a valid URL */
+    url(message?: string): Validator;
+    /** Minimum length */
+    min(length: number, message?: string): Validator;
+    /** Maximum length */
+    max(length: number, message?: string): Validator;
+    /** Length between min and max */
+    length(min: number, max: number, message?: string): Validator;
+    /** Must match a regex pattern */
+    pattern(regex: RegExp, message?: string): Validator;
+    /** Must contain uppercase letter */
+    hasUppercase(message?: string): Validator;
+    /** Must contain lowercase letter */
+    hasLowercase(message?: string): Validator;
+    /** Must contain a number */
+    hasNumber(message?: string): Validator;
+    /** Must contain a special character */
+    hasSpecial(message?: string): Validator;
+    /** Only alphanumeric characters */
+    alphanumeric(message?: string): Validator;
+    /** Must start with a letter */
+    startsWithLetter(message?: string): Validator;
+    /** No spaces allowed */
+    noSpaces(message?: string): Validator;
+    /** Must be a number */
+    number(message?: string): Validator;
+    /** Must be an integer */
+    integer(message?: string): Validator;
+    /** Must be positive */
+    positive(message?: string): Validator;
+    /** Must be negative */
+    negative(message?: string): Validator;
+    /** Minimum value */
+    minValue(min: number, message?: string): Validator;
+    /** Maximum value */
+    maxValue(max: number, message?: string): Validator;
+    /** Value between min and max */
+    between(min: number, max: number, message?: string): Validator;
+    /** Must match another field's value */
+    matches(fieldName: string, message?: string): Validator;
+    /** Must be one of the given values */
+    oneOf(values: unknown[], message?: string): Validator;
+    /** Must not be one of the given values */
+    notOneOf(values: unknown[], message?: string): Validator;
+    /** Must be a valid date */
+    date(message?: string): Validator;
+    /** Must be before a date */
+    before(date: Date | string, message?: string): Validator;
+    /** Must be after a date */
+    after(date: Date | string, message?: string): Validator;
+    /** Custom validation function */
+    custom(fn: ValidatorFn, message?: string): Validator;
+    /** Async custom validation (e.g., API check) */
+    async(fn: AsyncValidatorFn, message?: string): Validator;
+    /** Conditional validation */
+    when(condition: (value: unknown, formValues: Record<string, unknown>) => boolean, thenValidator: Validator): Validator;
+    /** Get all rules */
+    getRules(): ValidatorRule[];
+    /** Get default value for this validator */
+    getDefaultValue(): unknown;
+    /** Set default value */
+    default(value: unknown): Validator;
+    /** Validate a value */
+    validate(value: unknown, formValues?: Record<string, unknown>): Promise<string[]>;
+    /** Validate synchronously (ignores async rules) */
+    validateSync(value: unknown, formValues?: Record<string, unknown>): string[];
+}
+/**
+ * Starting point for building validation rules.
  *
- * // Access form state
- * form.values.email
- * form.errors.email
- * form.isValid
- *
- * // Validate
- * await form.validate()
- *
- * // Handle submit
- * form.handleSubmit((values) => {
- *   console.log(values)
- * })
+ * @example
+ * ```typescript
+ * v.required().email()
+ * v.required().min(8).hasUppercase()
+ * v.number().between(1, 100)
  * ```
  */
-export declare function defineForm<T extends Record<string, Validator>>(schema: T, initialValues?: Partial<{ [K in keyof T]: unknown }>): FormState<T>;
+export declare const v: Validator;
+export { defineForm, useForm } from './composables/use-form';
 /**
  * Process @error directive in templates
  *
@@ -64,111 +185,5 @@ export declare function processHasErrorsDirective(content: string, context: Reco
  * 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
-// =============================================================================
-// eslint-disable-next-line pickier/no-unused-vars
-declare type ValidatorFn = (value: unknown, formValues?: Record<string, unknown>) => true | string;
-// eslint-disable-next-line pickier/no-unused-vars
-declare type AsyncValidatorFn = (value: unknown, formValues?: Record<string, unknown>) => Promise<true | string>;
-// =============================================================================
-// Validator Class
-// =============================================================================
-declare class Validator {
-  required(message?: string): Validator;
-  email(message?: string): Validator;
-  url(message?: string): 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?: string): Validator;
-  hasUppercase(message?: string): Validator;
-  hasLowercase(message?: string): Validator;
-  hasNumber(message?: string): Validator;
-  hasSpecial(message?: string): Validator;
-  alphanumeric(message?: string): Validator;
-  startsWithLetter(message?: string): Validator;
-  noSpaces(message?: string): Validator;
-  number(message?: string): Validator;
-  integer(message?: string): Validator;
-  positive(message?: string): Validator;
-  negative(message?: string): 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?: string): Validator;
-  before(date: Date | string, message?: string): Validator;
-  after(date: Date | string, message?: string): Validator;
-  custom(fn: ValidatorFn, message?: string): 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[];
-}
-// =============================================================================
-// Re-exports
-// =============================================================================
 export { Validator };
+export type { ValidatorFn, AsyncValidatorFn, ValidatorRule, FieldState, FormState };

package/dist/forms-validation.js

@@ -345,96 +345,7 @@ class Validator {
   }
 }
 export const v = new Validator;
-export function defineForm(schema, initialValues) {
-  const fields = Object.keys(schema), values = {}, errors = {}, touched = {}, dirty = {}, validating = {};
-  for (const field of fields) {
-    values[field] = initialValues?.[field] ?? schema[field].getDefaultValue();
-    errors[field] = [];
-    touched[field] = !1;
-    dirty[field] = !1;
-    validating[field] = !1;
-  }
-  let isValidating = !1;
-  async function validateField(field) {
-    validating[field] = !0;
-    const fieldErrors = await schema[field].validate(values[field], values);
-    errors[field] = fieldErrors;
-    validating[field] = !1;
-    return fieldErrors.length === 0;
-  }
-  async function validate() {
-    isValidating = !0;
-    const results = await Promise.all(fields.map(validateField));
-    isValidating = !1;
-    return results.every(Boolean);
-  }
-  function reset() {
-    for (const field of fields) {
-      values[field] = initialValues?.[field] ?? schema[field].getDefaultValue();
-      errors[field] = [];
-      touched[field] = !1;
-      dirty[field] = !1;
-    }
-  }
-  function setValues(newValues) {
-    for (const field of fields)
-      if (field in newValues) {
-        values[field] = newValues[field];
-        dirty[field] = !0;
-      }
-  }
-  function setFieldValue(field, value) {
-    values[field] = value;
-    dirty[field] = !0;
-  }
-  function setFieldTouched(field, isTouched = !0) {
-    touched[field] = isTouched;
-    if (isTouched)
-      validateField(field);
-  }
-  function getFieldState(field) {
-    return {
-      value: values[field],
-      errors: errors[field],
-      touched: touched[field],
-      dirty: dirty[field],
-      valid: errors[field].length === 0,
-      validating: validating[field]
-    };
-  }
-  function handleSubmit(onSubmit) {
-    return async (e) => {
-      e?.preventDefault?.();
-      for (const field of fields)
-        touched[field] = !0;
-      if (await validate())
-        await onSubmit(values);
-    };
-  }
-  return {
-    values,
-    errors,
-    touched,
-    dirty,
-    get isValid() {
-      return fields.every((f) => errors[f].length === 0);
-    },
-    get isValidating() {
-      return isValidating || fields.some((f) => validating[f]);
-    },
-    get isDirty() {
-      return fields.some((f) => dirty[f]);
-    },
-    validate,
-    validateField,
-    reset,
-    setValues,
-    setFieldValue,
-    setFieldTouched,
-    getFieldState,
-    handleSubmit
-  };
-}
+export { defineForm, useForm } from "./composables/use-form.js";
 export function processErrorDirective(content, context, _filePath) {
   const errorRegex = /@error\s*\(\s*([^)]+)\s*\)([\s\S]*?)@enderror/g;
   return content.replace(errorRegex, (_, fieldPath, body) => {

package/dist/forms.d.ts

@@ -1,4 +1,80 @@
+/**
+ * Module for processing form-related directives.
+ *
+ * Provides directives for building accessible, validated forms:
+ * - `@csrf` - CSRF token hidden input
+ * - `@method('PUT')` - HTTP method spoofing
+ * - `@form` / `@endform` - Form wrapper with auto CSRF
+ * - `@input`, `@textarea`, `@select` - Form controls with validation
+ * - `@checkbox`, `@radio` - Check inputs with state binding
+ * - `@file` - File upload input with accept and multiple support
+ * - `@label` - Associated labels
+ * - `@error` / `@enderror` - Validation error display
+ * - `@validate` - Add validation rules with HTML5 attributes
+ *
+ * ## File Upload Example
+ *
+ * ```html
+ * @file('avatar', { accept: 'image/*' })
+ * @file('documents', { accept: '.pdf,.doc,.docx', multiple: true })
+ * ```
+ *
+ * ## Validation Rules
+ *
+ * Built-in validation rules:
+ * - `required` - Field must have a value
+ * - `email` - Must be valid email format
+ * - `url` - Must be valid URL
+ * - `numeric` - Must be a number
+ * - `integer` - Must be an integer
+ * - `alpha` - Letters only
+ * - `alphanumeric` - Letters and numbers only
+ * - `min:n` - Minimum length/value
+ * - `max:n` - Maximum length/value
+ * - `confirmed` - Must match `{field}_confirmation`
+ * - `in:a,b,c` - Must be one of the values
+ * - `notIn:a,b,c` - Must not be one of the values
+ * - `regex:pattern` - Must match regex
+ * - `date` - Must be valid date
+ * - `before:date` - Must be before date
+ * - `after:date` - Must be after date
+ *
+ * ## Configuration
+ *
+ * CSS class names can be customized via `stx.config.ts`:
+ * ```typescript
+ * export default {
+ *   forms: {
+ *     classes: {
+ *       input: 'my-input',
+ *       inputError: 'my-input--error',
+ *       // ...
+ *     }
+ *   }
+ * }
+ * ```
+ */
 import type { StxOptions } from './types';
+/**
+ * Default CSS class names for form elements.
+ * Based on Bootstrap conventions but fully customizable.
+ */
+export interface FormClassConfig {
+    /** Class for text inputs, textareas, and selects (default: 'form-control') */
+    input: string;
+    /** Class added to inputs with validation errors (default: 'is-invalid') */
+    inputError: string;
+    /** Class for checkboxes and radios (default: 'form-check-input') */
+    checkInput: string;
+    /** Class for labels (default: 'form-label') */
+    label: string;
+    /** Class for error message containers (default: 'invalid-feedback') */
+    errorFeedback: string;
+}
+/**
+ * Default form class configuration (Bootstrap-compatible)
+ */
+export declare const defaultFormClasses: FormClassConfig;
 /**
  * Process all form-related directives.
  *
@@ -30,6 +106,25 @@ export declare function processFormInputDirectives(template: string, context: Re
  * ```
  */
 export declare function processErrorDirective(template: string, context: Record<string, any>, _classes?: FormClassConfig): string;
+/**
+ * Validation rule definition
+ */
+export interface ValidationRule {
+    /** Rule name (e.g., 'required', 'email', 'min') */
+    name: string;
+    /** Rule parameters (e.g., min:5 → params = ['5']) */
+    params?: string[];
+    /** Custom error message */
+    message?: string;
+}
+/**
+ * Validation result for a single field
+ */
+export interface FieldValidationResult {
+    field: string;
+    valid: boolean;
+    errors: string[];
+}
 /**
  * Register a custom validation rule.
  *
@@ -88,6 +183,23 @@ export declare function validateFields(data: Record<string, any>, rules: Record<
  * ```
  */
 export declare function processValidateDirective(template: string, _context: Record<string, any>): string;
+/**
+ * Enhanced validation rule definition with HTML5 support
+ */
+export interface EnhancedValidationRule {
+    /** Rule name */
+    name: string;
+    /** Validation function - returns true if valid, error message if invalid */
+    validate: (value: unknown, params: string[], allValues: Record<string, unknown>) => true | string;
+    /** HTML5 attribute generator */
+    toHtml5?: (params: string[]) => string[];
+    /** Default error message with {{param}} placeholders */
+    message: string;
+}
+/**
+ * Enhanced validation rules registry with full validation support
+ */
+export declare const enhancedValidationRules: Record<string, EnhancedValidationRule>;
 /**
  * Register a custom enhanced validation rule
  */
@@ -95,76 +207,18 @@ export declare function registerEnhancedValidationRule(rule: EnhancedValidationR
 /**
  * Validate a single value against enhanced rules
  */
-export declare function validateValueEnhanced(value: unknown, rules: string, allValues?: Record<string, unknown>): { valid: boolean, errors: string[] };
+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[]> };
+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: () => readonly ['required']; message: 'This field is required' };
-  email: { name: 'email'; validate: (value) => unknown; toHtml5: () => readonly ['type="email"']; message: 'Please enter a valid email address' };
-  url: { name: 'url'; validate: (value) => unknown; toHtml5: () => readonly ['type="url"']; message: 'Please enter a valid URL' };
-  numeric: { name: 'numeric'; validate: (value) => unknown; toHtml5: () => readonly ['type="number"']; message: 'Please enter a number' };
-  integer: { name: 'integer'; validate: (value) => unknown; toHtml5: () => readonly ['type="number"', 'step="1"']; message: 'Please enter a whole number' };
-  alpha: { name: 'alpha'; validate: (value) => unknown; toHtml5: () => readonly ['pattern="[a-zA-Z]+"']; message: 'Please enter only letters' };
-  alphanumeric: { name: 'alphanumeric'; validate: (value) => unknown; toHtml5: () => readonly ['pattern="[a-zA-Z0-9]+"']; message: 'Please enter only letters and numbers' };
-  min: { name: 'min'; validate: (value, params) => unknown; toHtml5: (params) => readonly [`minlength="${params[0]}"`, `min="${params[0]}"`]; message: 'Must be at least {{param}} characters' };
-  max: { name: 'max'; validate: (value, params) => unknown; toHtml5: (params) => readonly [`maxlength="${params[0]}"`, `max="${params[0]}"`]; message: 'Must be no more than {{param}} characters' };
-  between: { name: 'between'; validate: (value, params) => unknown; toHtml5: (params) => readonly [`minlength="${params[0]}"`, `maxlength="${params[1]}"`]; message: 'Must be between {{min}} and {{max}}' };
-  confirmed: { name: 'confirmed'; validate: (value, _params, allValues) => unknown; message: 'Confirmation does not match' };
-  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; toHtml5: (params) => readonly [`pattern="${params[0]}"`]; message: 'Invalid format' };
-  date: { name: 'date'; validate: (value) => unknown; toHtml5: () => readonly ['type="date"']; message: 'Please enter a valid date' };
-  before: { name: 'before'; validate: (value, params) => unknown; toHtml5: (params) => readonly [`max="${params[0]}"`]; message: 'Must be before {{date}}' };
-  after: { name: 'after'; validate: (value, params) => unknown; toHtml5: (params) => readonly [`min="${params[0]}"`]; message: 'Must be after {{date}}' };
-  size: { name: 'size'; validate: (value, params) => unknown; message: 'Must be exactly {{size}}' };
-  phone: { name: 'phone'; validate: (value) => unknown; toHtml5: () => readonly ['type="tel"', 'pattern="\\+?\\(?\\d{1,4}\\)?[-\\s./\\d]*"']; message: 'Please enter a valid phone number' }
-};
-/**
- * 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
-}