@mdxui/terminal 2.0.0

package/src/forms/schemas.ts

@@ -0,0 +1,403 @@
+/**
+ * @mdxui/terminal Form Zod Schemas
+ *
+ * Zod validation schemas for terminal form components.
+ * These schemas can be used with @hookform/resolvers/zod for
+ * React Hook Form integration.
+ *
+ * @packageDocumentation
+ */
+
+import { z } from 'zod'
+
+// ============================================================================
+// Field Value Schemas
+// ============================================================================
+
+/**
+ * Schema for primitive field values.
+ */
+export const FieldValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.undefined(),
+  z.array(z.string()),
+])
+
+/**
+ * Schema for select option configuration.
+ */
+export const SelectOptionSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+  disabled: z.boolean().optional(),
+  description: z.string().optional(),
+})
+
+/**
+ * Schema for search suggestion configuration.
+ */
+export const SearchSuggestionSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+})
+
+// ============================================================================
+// Field Configuration Schemas
+// ============================================================================
+
+/**
+ * Schema for field input types.
+ */
+export const FieldTypeSchema = z.enum([
+  'text',
+  'email',
+  'password',
+  'number',
+  'checkbox',
+  'textarea',
+  'select',
+])
+
+/**
+ * Schema for field configuration.
+ *
+ * @remarks
+ * Validates the complete structure of a form field configuration.
+ * Use this to validate field configs passed to terminal renderers.
+ */
+export const FieldConfigSchema = z.object({
+  name: z.string().min(1, 'Field name is required'),
+  label: z.string().optional(),
+  type: FieldTypeSchema.optional(),
+  value: FieldValueSchema.optional(),
+  placeholder: z.string().optional(),
+  required: z.boolean().optional(),
+  error: z.string().optional(),
+  valid: z.boolean().optional(),
+  disabled: z.boolean().optional(),
+  readonly: z.boolean().optional(),
+  helperText: z.string().optional(),
+  focused: z.boolean().optional(),
+  cursorPosition: z.number().int().nonnegative().optional(),
+  selectionStart: z.number().int().nonnegative().optional(),
+  selectionEnd: z.number().int().nonnegative().optional(),
+  options: z.array(SelectOptionSchema).optional(),
+})
+
+/**
+ * Schema for field group configuration.
+ */
+export const FieldGroupSchema = z.object({
+  title: z.string(),
+  fields: z.array(FieldConfigSchema),
+  collapsible: z.boolean().optional(),
+  collapsed: z.boolean().optional(),
+})
+
+// ============================================================================
+// Form State Schemas
+// ============================================================================
+
+/**
+ * Schema for complete form state.
+ *
+ * @remarks
+ * Validates the full form configuration including all fields,
+ * groups, and UI state. Use this to validate form configs
+ * passed to the Form renderer.
+ */
+export const FormStateSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  fields: z.array(FieldConfigSchema).optional(),
+  groups: z.array(FieldGroupSchema).optional(),
+  error: z.string().optional(),
+  success: z.string().optional(),
+  loading: z.boolean().optional(),
+  submitLabel: z.string().optional(),
+  cancelLabel: z.string().optional(),
+  submitDisabled: z.boolean().optional(),
+  submitHotkey: z.string().optional(),
+  border: z.boolean().optional(),
+})
+
+// ============================================================================
+// Select State Schema
+// ============================================================================
+
+/**
+ * Schema for select component state.
+ */
+export const SelectStateSchema = z.object({
+  options: z.array(SelectOptionSchema),
+  value: z.union([z.string(), z.array(z.string())]).optional(),
+  label: z.string().optional(),
+  placeholder: z.string().optional(),
+  required: z.boolean().optional(),
+  error: z.string().optional(),
+  valid: z.boolean().optional(),
+  disabled: z.boolean().optional(),
+  open: z.boolean().optional(),
+  multiple: z.boolean().optional(),
+  highlightedIndex: z.number().int().optional(),
+  searchable: z.boolean().optional(),
+  searchValue: z.string().optional(),
+  filteredOptions: z.array(SelectOptionSchema).optional(),
+  loading: z.boolean().optional(),
+})
+
+// ============================================================================
+// Search State Schema
+// ============================================================================
+
+/**
+ * Schema for search component state.
+ */
+export const SearchStateSchema = z.object({
+  value: z.string(),
+  placeholder: z.string().optional(),
+  label: z.string().optional(),
+  disabled: z.boolean().optional(),
+  loading: z.boolean().optional(),
+  error: z.string().optional(),
+  focused: z.boolean().optional(),
+  cursorPosition: z.number().int().nonnegative().optional(),
+  suggestions: z.array(SearchSuggestionSchema).nullable().optional(),
+  showSuggestions: z.boolean().optional(),
+  highlightedIndex: z.number().int().optional(),
+  maxSuggestions: z.number().int().positive().optional(),
+  highlightMatches: z.boolean().optional(),
+  isTyping: z.boolean().optional(),
+})
+
+// ============================================================================
+// Common Validation Schemas
+// ============================================================================
+
+/**
+ * Schema for email validation.
+ */
+export const EmailSchema = z.string().email('Please enter a valid email address')
+
+/**
+ * Schema for password validation with common requirements.
+ */
+export const PasswordSchema = z
+  .string()
+  .min(8, 'Password must be at least 8 characters')
+  .regex(/[A-Z]/, 'Password must contain at least one uppercase letter')
+  .regex(/[a-z]/, 'Password must contain at least one lowercase letter')
+  .regex(/[0-9]/, 'Password must contain at least one number')
+
+/**
+ * Schema for basic password validation (minimum length only).
+ */
+export const SimplePasswordSchema = z
+  .string()
+  .min(8, 'Password must be at least 8 characters')
+
+/**
+ * Schema for username validation.
+ */
+export const UsernameSchema = z
+  .string()
+  .min(3, 'Username must be at least 3 characters')
+  .max(20, 'Username must be at most 20 characters')
+  .regex(/^[a-zA-Z0-9_-]+$/, 'Username can only contain letters, numbers, underscores, and hyphens')
+
+/**
+ * Schema for URL validation.
+ */
+export const UrlSchema = z.string().url('Please enter a valid URL')
+
+/**
+ * Schema for phone number validation (basic).
+ */
+export const PhoneSchema = z
+  .string()
+  .regex(/^\+?[1-9]\d{1,14}$/, 'Please enter a valid phone number')
+
+// ============================================================================
+// Form Schema Builders
+// ============================================================================
+
+/**
+ * Creates a login form schema.
+ *
+ * @param options - Optional customization options
+ * @returns Zod schema for login form validation
+ *
+ * @example
+ * ```tsx
+ * const loginSchema = createLoginSchema()
+ * type LoginForm = z.infer<typeof loginSchema>
+ *
+ * // With remember me
+ * const loginSchemaWithRemember = createLoginSchema({ rememberMe: true })
+ * ```
+ */
+export function createLoginSchema(options?: {
+  rememberMe?: boolean
+  strictPassword?: boolean
+}) {
+  const base = z.object({
+    email: EmailSchema,
+    password: options?.strictPassword ? PasswordSchema : SimplePasswordSchema,
+  })
+
+  if (options?.rememberMe) {
+    return base.extend({
+      rememberMe: z.boolean().optional().default(false),
+    })
+  }
+
+  return base
+}
+
+/**
+ * Creates a registration form schema.
+ *
+ * @param options - Optional customization options
+ * @returns Zod schema for registration form validation
+ *
+ * @example
+ * ```tsx
+ * const registerSchema = createRegistrationSchema({
+ *   confirmPassword: true,
+ *   termsRequired: true,
+ * })
+ * ```
+ */
+export function createRegistrationSchema(options?: {
+  confirmPassword?: boolean
+  termsRequired?: boolean
+  usernameRequired?: boolean
+}) {
+  let schema = z.object({
+    email: EmailSchema,
+    password: PasswordSchema,
+  })
+
+  if (options?.usernameRequired) {
+    schema = schema.extend({
+      username: UsernameSchema,
+    }) as typeof schema
+  }
+
+  if (options?.confirmPassword) {
+    schema = schema.extend({
+      confirmPassword: z.string(),
+    }) as typeof schema
+
+    // Add refinement for password match
+    return schema.refine(
+      (data) => {
+        const d = data as { password: string; confirmPassword?: string }
+        return d.password === d.confirmPassword
+      },
+      {
+        message: 'Passwords do not match',
+        path: ['confirmPassword'],
+      }
+    ).and(
+      options?.termsRequired
+        ? z.object({ acceptTerms: z.literal(true, { errorMap: () => ({ message: 'You must accept the terms' }) }) })
+        : z.object({})
+    )
+  }
+
+  if (options?.termsRequired) {
+    return schema.extend({
+      acceptTerms: z.literal(true, {
+        errorMap: () => ({ message: 'You must accept the terms' }),
+      }),
+    })
+  }
+
+  return schema
+}
+
+/**
+ * Creates a contact form schema.
+ *
+ * @param options - Optional customization options
+ * @returns Zod schema for contact form validation
+ */
+export function createContactSchema(options?: {
+  phoneRequired?: boolean
+  subjectRequired?: boolean
+}) {
+  let schema = z.object({
+    name: z.string().min(1, 'Name is required'),
+    email: EmailSchema,
+    message: z.string().min(10, 'Message must be at least 10 characters'),
+  })
+
+  if (options?.phoneRequired) {
+    schema = schema.extend({
+      phone: PhoneSchema,
+    }) as typeof schema
+  }
+
+  if (options?.subjectRequired) {
+    schema = schema.extend({
+      subject: z.string().min(1, 'Subject is required'),
+    }) as typeof schema
+  }
+
+  return schema
+}
+
+/**
+ * Creates a profile form schema.
+ *
+ * @returns Zod schema for profile form validation
+ */
+export function createProfileSchema() {
+  return z.object({
+    firstName: z.string().min(1, 'First name is required'),
+    lastName: z.string().min(1, 'Last name is required'),
+    email: EmailSchema,
+    bio: z.string().max(500, 'Bio must be at most 500 characters').optional(),
+    website: UrlSchema.optional().or(z.literal('')),
+    location: z.string().optional(),
+    timezone: z.string().optional(),
+  })
+}
+
+/**
+ * Creates a settings form schema for common app settings.
+ *
+ * @returns Zod schema for settings form validation
+ */
+export function createSettingsSchema() {
+  return z.object({
+    emailNotifications: z.boolean().default(true),
+    pushNotifications: z.boolean().default(true),
+    marketingEmails: z.boolean().default(false),
+    theme: z.enum(['light', 'dark', 'system']).default('system'),
+    language: z.string().default('en'),
+  })
+}
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type FieldConfig = z.infer<typeof FieldConfigSchema>
+export type FieldGroup = z.infer<typeof FieldGroupSchema>
+export type FormState = z.infer<typeof FormStateSchema>
+export type SelectOption = z.infer<typeof SelectOptionSchema>
+export type SelectState = z.infer<typeof SelectStateSchema>
+export type SearchSuggestion = z.infer<typeof SearchSuggestionSchema>
+export type SearchState = z.infer<typeof SearchStateSchema>
+export type LoginFormValues = z.infer<ReturnType<typeof createLoginSchema>>
+export type RegistrationFormValues = z.infer<ReturnType<typeof createRegistrationSchema>>
+export type ContactFormValues = z.infer<ReturnType<typeof createContactSchema>>
+export type ProfileFormValues = z.infer<ReturnType<typeof createProfileSchema>>
+export type SettingsFormValues = z.infer<ReturnType<typeof createSettingsSchema>>