@omnitron-dev/prism 0.1.1

package/dist/forms/index.d.ts

@@ -0,0 +1,562 @@
+import * as z from 'zod';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Schema Utilities
+ *
+ * Pre-built Zod schema helpers for common form field validations.
+ * Designed to work seamlessly with React Hook Form + Zod resolver.
+ *
+ * Features:
+ * - Type-safe schema builders
+ * - Customizable error messages with i18n support
+ * - Common field validations (email, phone, date, file, etc.)
+ * - Nullable input handling
+ * - Slider range validation
+ * - Rich text editor validation
+ *
+ * @module @omnitron-dev/prism/forms
+ */
+
+/**
+ * Common error message configuration.
+ */
+interface SchemaErrorMessages {
+    /** Error message when field is required but empty */
+    required?: string;
+    /** Error message when field format is invalid */
+    invalid?: string;
+}
+/**
+ * Options for file validation.
+ */
+interface FileSchemaOptions extends SchemaErrorMessages {
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Allowed MIME types */
+    accept?: string[];
+}
+/**
+ * Options for slider range validation.
+ */
+interface SliderRangeOptions extends SchemaErrorMessages {
+    /** Minimum value */
+    min: number;
+    /** Maximum value */
+    max: number;
+}
+/**
+ * Pre-built Zod schema helpers for common form validations.
+ *
+ * @example
+ * ```tsx
+ * import { z } from 'zod';
+ * import { schemaUtils } from '@omnitron-dev/prism/forms';
+ *
+ * // Define form schema
+ * const UserSchema = z.object({
+ *   email: schemaUtils.email(),
+ *   phone: schemaUtils.phone(),
+ *   birthDate: schemaUtils.date(),
+ *   avatar: schemaUtils.file(),
+ *   agreeToTerms: schemaUtils.boolean({ error: 'You must accept the terms' }),
+ *   bio: schemaUtils.editor(),
+ * });
+ *
+ * // With custom error messages
+ * const CustomSchema = z.object({
+ *   email: schemaUtils.email({
+ *     required: 'Please enter your email',
+ *     invalid: 'That email doesn\'t look right',
+ *   }),
+ * });
+ * ```
+ */
+declare const schemaUtils: {
+    /**
+     * Email validation schema.
+     * Validates format and provides clear error messages.
+     *
+     * @example
+     * ```tsx
+     * const schema = z.object({
+     *   email: schemaUtils.email(),
+     * });
+     * ```
+     */
+    email: (errors?: SchemaErrorMessages) => z.ZodString;
+    /**
+     * Phone number validation schema.
+     * Basic validation with optional custom validator.
+     *
+     * @example
+     * ```tsx
+     * const schema = z.object({
+     *   phone: schemaUtils.phone({
+     *     isValid: (val) => /^\+?[1-9]\d{1,14}$/.test(val),
+     *   }),
+     * });
+     * ```
+     */
+    phone: (options?: SchemaErrorMessages & {
+        isValid?: (val: string) => boolean;
+    }) => z.ZodString;
+    /**
+     * Date validation schema.
+     * Works with Date objects, timestamps, and ISO strings.
+     * Compatible with date pickers.
+     *
+     * @example
+     * ```tsx
+     * const schema = z.object({
+     *   birthDate: schemaUtils.date(),
+     *   appointmentTime: schemaUtils.date({ required: 'Please select a time' }),
+     * });
+     * ```
+     */
+    date: (errors?: SchemaErrorMessages) => z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate, z.ZodNull]>;
+    /**
+     * Optional date schema (nullable).
+     * For date fields that aren't required.
+     */
+    dateOptional: (errors?: SchemaErrorMessages) => z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate, z.ZodNull]>>;
+    /**
+     * Rich text editor validation schema.
+     * Treats empty paragraphs as empty content.
+     *
+     * @example
+     * ```tsx
+     * const schema = z.object({
+     *   description: schemaUtils.editor(),
+     * });
+     * ```
+     */
+    editor: (error?: string) => z.ZodString;
+    /**
+     * Boolean validation schema.
+     * For checkboxes/switches that must be true (e.g., terms acceptance).
+     *
+     * @example
+     * ```tsx
+     * const schema = z.object({
+     *   agreeToTerms: schemaUtils.boolean({ error: 'You must accept the terms' }),
+     * });
+     * ```
+     */
+    boolean: (options?: {
+        error?: string;
+    }) => z.ZodBoolean;
+    /**
+     * Optional boolean schema.
+     * For optional checkboxes.
+     */
+    booleanOptional: () => z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Nullable input wrapper.
+     * Wraps any schema to handle null values as required errors.
+     *
+     * @example
+     * ```tsx
+     * const schema = z.object({
+     *   country: schemaUtils.nullableInput(
+     *     z.string().min(1),
+     *     { error: 'Please select a country' }
+     *   ),
+     * });
+     * ```
+     */
+    nullableInput: <T extends z.ZodTypeAny>(schema: T, options?: {
+        error?: string;
+    }) => z.ZodNullable<T> & z.ZodType<z.core.output<T> & {}, z.core.input<T> | null, z.core.$ZodTypeInternals<z.core.output<T> & {}, z.core.input<T> | null>>;
+    /**
+     * Single file upload validation.
+     * Supports File objects and URL strings (for existing files).
+     *
+     * @example
+     * ```tsx
+     * const schema = z.object({
+     *   avatar: schemaUtils.file(),
+     *   document: schemaUtils.file({
+     *     maxSize: 5 * 1024 * 1024, // 5MB
+     *     accept: ['application/pdf'],
+     *   }),
+     * });
+     * ```
+     */
+    file: (options?: FileSchemaOptions) => z.ZodUnion<readonly [z.ZodCustom<File, File>, z.ZodString, z.ZodNull]>;
+    /**
+     * Optional single file upload.
+     */
+    fileOptional: (options?: Omit<FileSchemaOptions, "required">) => z.ZodNullable<z.ZodUnion<readonly [z.ZodCustom<File, File>, z.ZodString, z.ZodNull]>>;
+    /**
+     * Multiple file upload validation.
+     *
+     * @example
+     * ```tsx
+     * const schema = z.object({
+     *   images: schemaUtils.files({ minFiles: 1, error: 'Upload at least one image' }),
+     * });
+     * ```
+     */
+    files: (options?: {
+        error?: string;
+        minFiles?: number;
+    }) => z.ZodArray<z.ZodUnion<readonly [z.ZodCustom<File, File>, z.ZodString]>>;
+    /**
+     * Slider range validation.
+     * For dual-thumb sliders with [min, max] value.
+     *
+     * @example
+     * ```tsx
+     * const schema = z.object({
+     *   priceRange: schemaUtils.sliderRange({ min: 0, max: 1000 }),
+     * });
+     * ```
+     */
+    sliderRange: (options: SliderRangeOptions) => z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    /**
+     * URL validation schema.
+     */
+    url: (errors?: SchemaErrorMessages) => z.ZodString;
+    /**
+     * Optional URL schema.
+     */
+    urlOptional: (errors?: SchemaErrorMessages) => z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    /**
+     * Password validation with strength requirements.
+     */
+    password: (options?: {
+        minLength?: number;
+        requireUppercase?: boolean;
+        requireLowercase?: boolean;
+        requireNumber?: boolean;
+        requireSpecial?: boolean;
+        error?: string;
+    }) => z.ZodString;
+    /**
+     * Confirmation field (e.g., confirm password).
+     * Use with z.object().refine() for cross-field validation.
+     */
+    confirm: (fieldName: string, error?: string) => {
+        message: string;
+        path: string[];
+    };
+};
+/**
+ * Test schema validation with multiple values.
+ * Useful for development and debugging.
+ *
+ * @example
+ * ```ts
+ * testSchema(schemaUtils.email(), [
+ *   'valid@email.com',
+ *   'invalid-email',
+ *   '',
+ *   null,
+ * ]);
+ * ```
+ */
+/**
+ * Test results from schema validation.
+ */
+interface SchemaTestResult {
+    value: unknown;
+    success: boolean;
+    data?: unknown;
+    errors?: string[];
+}
+/**
+ * Test a schema against multiple values.
+ * Returns structured results instead of logging to console.
+ * Use testSchemaDebug for console output during development.
+ */
+declare function testSchema<T extends z.ZodTypeAny>(schema: T, values: unknown[]): SchemaTestResult[];
+/**
+ * Test a schema with console output (development only).
+ * This function does nothing in production builds.
+ *
+ * @example
+ * ```ts
+ * testSchemaDebug(schemaUtils.email(), [
+ *   'valid@email.com',
+ *   'invalid-email',
+ *   '',
+ *   null,
+ * ]);
+ * ```
+ */
+declare function testSchemaDebug<T extends z.ZodTypeAny>(schema: T, values: unknown[]): void;
+
+/**
+ * Translation function type.
+ * Compatible with i18next t() function signature.
+ */
+type TranslateFunction = (key: string, options?: Record<string, unknown>) => string;
+/**
+ * Default translation keys for schema error messages.
+ */
+interface SchemaTranslationKeys {
+    'validation.required': string;
+    'validation.email.required': string;
+    'validation.email.invalid': string;
+    'validation.phone.required': string;
+    'validation.phone.invalid': string;
+    'validation.date.required': string;
+    'validation.date.invalid': string;
+    'validation.file.required': string;
+    'validation.file.tooLarge': string;
+    'validation.file.invalidType': string;
+    'validation.boolean.required': string;
+    'validation.editor.required': string;
+    'validation.url.required': string;
+    'validation.url.invalid': string;
+    'validation.password.minLength': string;
+    'validation.password.uppercase': string;
+    'validation.password.lowercase': string;
+    'validation.password.number': string;
+    'validation.password.special': string;
+    'validation.confirm.mismatch': string;
+    [key: string]: string;
+}
+/**
+ * Schema provider configuration.
+ */
+interface SchemaProviderConfig {
+    /**
+     * Translation function from your i18n library.
+     * If not provided, keys will be used as-is.
+     */
+    t?: TranslateFunction;
+    /**
+     * Default locale for error messages.
+     * @default 'en'
+     */
+    locale?: string;
+    /**
+     * Custom error message overrides.
+     */
+    messages?: Partial<SchemaTranslationKeys>;
+}
+/**
+ * Schema context value.
+ */
+interface SchemaContextValue {
+    /**
+     * Translate a validation key.
+     */
+    t: TranslateFunction;
+    /**
+     * Current locale.
+     */
+    locale: string;
+    /**
+     * Get schema helpers with translated messages.
+     */
+    schema: ReturnType<typeof createTranslatedSchemaUtils>;
+}
+/**
+ * Create schema utilities with translated error messages.
+ */
+declare function createTranslatedSchemaUtils(t: TranslateFunction): {
+    /**
+     * Email validation with i18n messages.
+     */
+    email: (options?: {
+        required?: string;
+        invalid?: string;
+    }) => z.ZodString;
+    /**
+     * Phone validation with i18n messages.
+     */
+    phone: (options?: {
+        required?: string;
+        invalid?: string;
+        isValid?: (val: string) => boolean;
+    }) => z.ZodString;
+    /**
+     * Date validation with i18n messages.
+     */
+    date: (options?: {
+        required?: string;
+        invalid?: string;
+    }) => z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate, z.ZodNull]>;
+    /**
+     * Optional date schema.
+     */
+    dateOptional: (options?: {
+        invalid?: string;
+    }) => z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate, z.ZodNull]>>;
+    /**
+     * Boolean (checkbox) validation with i18n messages.
+     */
+    boolean: (options?: {
+        error?: string;
+    }) => z.ZodBoolean;
+    /**
+     * Optional boolean schema.
+     */
+    booleanOptional: () => z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Rich text editor validation with i18n messages.
+     */
+    editor: (options?: {
+        error?: string;
+    }) => z.ZodString;
+    /**
+     * File validation with i18n messages.
+     */
+    file: (options?: {
+        required?: string;
+        tooLarge?: string;
+        invalidType?: string;
+        maxSize?: number;
+        accept?: string[];
+    }) => z.ZodUnion<readonly [z.ZodCustom<File, File>, z.ZodString, z.ZodNull]>;
+    /**
+     * Optional file schema.
+     */
+    fileOptional: (options?: {
+        tooLarge?: string;
+        invalidType?: string;
+        maxSize?: number;
+        accept?: string[];
+    }) => z.ZodNullable<z.ZodUnion<readonly [z.ZodCustom<File, File>, z.ZodString, z.ZodNull]>>;
+    /**
+     * Multiple files validation.
+     */
+    files: (options?: {
+        error?: string;
+        minFiles?: number;
+    }) => z.ZodArray<z.ZodUnion<readonly [z.ZodCustom<File, File>, z.ZodString]>>;
+    /**
+     * URL validation with i18n messages.
+     */
+    url: (options?: {
+        required?: string;
+        invalid?: string;
+    }) => z.ZodString;
+    /**
+     * Optional URL schema.
+     */
+    urlOptional: (options?: {
+        invalid?: string;
+    }) => z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    /**
+     * Password validation with strength requirements.
+     */
+    password: (options?: {
+        minLength?: number;
+        requireUppercase?: boolean;
+        requireLowercase?: boolean;
+        requireNumber?: boolean;
+        requireSpecial?: boolean;
+    }) => z.ZodString;
+    /**
+     * Nullable input wrapper.
+     */
+    nullableInput: <T extends z.ZodTypeAny>(schema: T, options?: {
+        error?: string;
+    }) => z.ZodNullable<T> & z.ZodType<z.core.output<T> & {}, z.core.input<T> | null, z.core.$ZodTypeInternals<z.core.output<T> & {}, z.core.input<T> | null>>;
+    /**
+     * Slider range validation.
+     */
+    sliderRange: (options: {
+        min: number;
+        max: number;
+        invalid?: string;
+    }) => z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    /**
+     * Required string with i18n message.
+     */
+    required: (options?: {
+        error?: string;
+    }) => z.ZodString;
+    /**
+     * Confirmation field helper.
+     */
+    confirm: (fieldName: string, error?: string) => {
+        message: string;
+        path: string[];
+    };
+};
+/**
+ * Provider props.
+ */
+interface SchemaProviderProps extends SchemaProviderConfig {
+    children: ReactNode;
+}
+/**
+ * SchemaProvider - Provides i18n-aware schema validation context.
+ *
+ * @example
+ * ```tsx
+ * // With i18next
+ * import { useTranslation } from 'react-i18next';
+ *
+ * function App() {
+ *   const { t, i18n } = useTranslation();
+ *
+ *   return (
+ *     <SchemaProvider t={t} locale={i18n.language}>
+ *       <MyForm />
+ *     </SchemaProvider>
+ *   );
+ * }
+ *
+ * // In form component
+ * function MyForm() {
+ *   const { schema } = useSchema();
+ *
+ *   const formSchema = z.object({
+ *     email: schema.email(),
+ *     password: schema.password(),
+ *   });
+ *
+ *   // ... form implementation
+ * }
+ * ```
+ */
+declare function SchemaProvider({ children, t: providedT, locale, messages }: SchemaProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access schema context.
+ *
+ * @throws Error if used outside SchemaProvider
+ *
+ * @example
+ * ```tsx
+ * function MyForm() {
+ *   const { schema, t } = useSchema();
+ *
+ *   const formSchema = z.object({
+ *     email: schema.email(),
+ *     name: z.string().min(1, { message: t('validation.required') }),
+ *   });
+ *
+ *   // ... use formSchema with react-hook-form
+ * }
+ * ```
+ */
+declare function useSchema(): SchemaContextValue;
+/**
+ * Hook to access schema context safely (returns null if not in provider).
+ */
+declare function useSchemaOptional(): SchemaContextValue | null;
+/**
+ * Create translated schema utilities without provider.
+ * Useful for server-side validation or standalone usage.
+ *
+ * @example
+ * ```ts
+ * // Server-side validation
+ * const t = (key: string) => translations[key] ?? key;
+ * const schema = createSchemaUtils(t);
+ *
+ * const userSchema = z.object({
+ *   email: schema.email(),
+ * });
+ * ```
+ */
+declare function createSchemaUtils(t?: TranslateFunction): ReturnType<typeof createTranslatedSchemaUtils>;
+
+export { type FileSchemaOptions, type SchemaContextValue, type SchemaErrorMessages, SchemaProvider, type SchemaProviderConfig, type SchemaProviderProps, type SchemaTestResult, type SchemaTranslationKeys, type SliderRangeOptions, type TranslateFunction, createSchemaUtils, schemaUtils, testSchema, testSchemaDebug, useSchema, useSchemaOptional };