@gzl10/nexus-sdk 0.12.7 → 0.13.0

package/dist/fields/index.d.ts

@@ -0,0 +1,1305 @@
+import { i as FieldDefinition } from '../field-CngHXora.js';
+
+/**
+ * ID Field Factory
+ *
+ * Creates ID fields with various generation strategies.
+ */
+
+/**
+ * Supported ID generation strategies.
+ *
+ * | Type     | Size | Format                               | Use case                       |
+ * |----------|------|--------------------------------------|--------------------------------|
+ * | ulid     | 26   | 01ARZ3NDEKTSV4RRFFQ69G5FAV           | Default, sortable by time      |
+ * | cuid2    | 24   | ckopqwooh000001l8c5e0aaaa           | Collision-resistant, random    |
+ * | uuid     | 36   | 550e8400-e29b-41d4-a716-446655440000 | Standard UUID v4               |
+ * | nanoid   | 21   | V1StGXR8_Z5jdHi6B-myT                | URL-safe, compact              |
+ * | auto     | -    | 1, 2, 3...                           | Auto-increment integer         |
+ * | custom   | var  | user-defined                         | Custom string with size        |
+ * | pattern  | var  | TP-2025-000001                       | Sequential with pattern        |
+ */
+type IdType = 'ulid' | 'uuid' | 'nanoid' | 'cuid2' | 'auto' | 'custom' | 'pattern';
+/**
+ * Configuration for pattern-based ID generation.
+ *
+ * Supported tokens:
+ * - `{prefix}` - Static prefix string
+ * - `{suffix}` - Static suffix string
+ * - `{year}` - Current year (4 digits)
+ * - `{year2}` - Current year (2 digits)
+ * - `{month}` - Current month (01-12)
+ * - `{day}` - Current day (01-31)
+ * - `{seq}` - Sequence number (resets per scope)
+ * - `{seq:N}` - Sequence with N-digit padding (e.g., {seq:6} → 000001)
+ *
+ * @example
+ * ```typescript
+ * // TP-2025-000001, TP-2025-000002...
+ * { pattern: '{prefix}-{year}-{seq:6}', prefix: 'TP' }
+ *
+ * // INV-2025-01-0001
+ * { pattern: '{prefix}-{year}-{month}-{seq:4}', prefix: 'INV' }
+ *
+ * // ORD000001
+ * { pattern: '{prefix}{seq:6}', prefix: 'ORD' }
+ *
+ * // Reset sequence yearly
+ * { pattern: '{prefix}-{year}-{seq:6}', prefix: 'TP', resetOn: 'year' }
+ *
+ * // Reset sequence monthly
+ * { pattern: '{prefix}-{year}{month}-{seq:4}', prefix: 'DOC', resetOn: 'month' }
+ * ```
+ */
+interface PatternIdConfig {
+    /**
+     * Pattern template with tokens.
+     * @example '{prefix}-{year}-{seq:6}'
+     */
+    pattern: string;
+    /**
+     * Static prefix value for {prefix} token.
+     * @example 'TP', 'INV', 'ORD'
+     */
+    prefix?: string;
+    /**
+     * Static suffix value for {suffix} token.
+     */
+    suffix?: string;
+    /**
+     * When to reset the sequence counter.
+     * - 'never': Never reset (global sequence)
+     * - 'year': Reset at the start of each year
+     * - 'month': Reset at the start of each month
+     * - 'day': Reset at the start of each day
+     * @default 'never'
+     */
+    resetOn?: 'never' | 'year' | 'month' | 'day';
+    /**
+     * Starting number for the sequence.
+     * @default 1
+     */
+    startAt?: number;
+}
+/**
+ * Configuration for ID fields.
+ */
+interface IdFieldConfig {
+    /** Custom size for 'custom' type (default: 50) */
+    size?: number;
+    /** Custom label (default: 'ID') */
+    label?: string;
+    /** Pattern configuration for 'pattern' type */
+    pattern?: PatternIdConfig;
+}
+/**
+ * Create an ID field with the specified generation strategy.
+ *
+ * @param type - ID generation type (default: 'ulid' - sortable by time)
+ * @param config - Optional configuration for custom IDs
+ *
+ * @example
+ * ```typescript
+ * // ULID (default, sortable by time)
+ * fields: { id: useIdField() }
+ *
+ * // CUID2 (collision-resistant, random)
+ * fields: { id: useIdField('cuid2') }
+ *
+ * // UUID
+ * fields: { id: useIdField('uuid') }
+ *
+ * // Auto-increment
+ * fields: { id: useIdField('auto') }
+ *
+ * // Custom string
+ * fields: { id: useIdField('custom', { size: 50 }) }
+ *
+ * // Pattern-based
+ * fields: { id: useIdField('pattern', { pattern: { pattern: '{prefix}-{year}-{seq:6}', prefix: 'INV' } }) }
+ * ```
+ */
+declare function useIdField(type?: IdType, config?: IdFieldConfig): FieldDefinition;
+
+/**
+ * Shared types for field factories
+ */
+
+/**
+ * Universal field properties that any factory can accept.
+ *
+ * These are FieldDefinition properties that are orthogonal to the
+ * field's core logic (input type, db config, validation) but may
+ * be needed in any context.
+ *
+ * @example
+ * ```typescript
+ * // Hidden field with custom input props
+ * token: useTextField({
+ *   label: 'Token',
+ *   hidden: true,
+ *   inputProps: { monospace: true }
+ * })
+ *
+ * // Disabled field with display customization
+ * scope: useTextField({
+ *   label: 'Scope',
+ *   disabled: true,
+ *   displayProps: { tag: true }
+ * })
+ * ```
+ */
+type FieldOverrides = Partial<Pick<FieldDefinition, 'hidden' | 'disabled' | 'inputProps' | 'displayProps'>>;
+
+/**
+ * Text Field Factories
+ *
+ * Creates text and unique text fields with common configuration patterns.
+ */
+
+/**
+ * Configuration for text fields.
+ */
+interface TextFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** Max string size (default: 255). Also sets validation.max */
+    size?: number;
+    /** Min string length for validation (default: 1 if required, 0 otherwise) */
+    minLength?: number;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Create DB index (default: false) */
+    index?: boolean;
+    /** Unique constraint (default: false) */
+    unique?: boolean;
+    /** Default value */
+    defaultValue?: string;
+    /** Placeholder text */
+    placeholder?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Custom validation rules (merged with auto-generated min/max) */
+    validation?: FieldDefinition['validation'];
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Configuration for unique text fields (omits unique/index/required as they're always true).
+ */
+type TextUniqueFieldConfig = Omit<TextFieldConfig, 'unique' | 'index' | 'required'>;
+/**
+ * Create a text field with common configuration.
+ *
+ * @example
+ * ```typescript
+ * // Simple text field
+ * name: useTextField({
+ *   label: { en: 'Name', es: 'Nombre' },
+ *   required: true
+ * })
+ *
+ * // With size and index
+ * code: useTextField({
+ *   label: { en: 'Code', es: 'Código' },
+ *   size: 50,
+ *   unique: true,
+ *   index: true
+ * })
+ *
+ * // With placeholder and default
+ * slug: useTextField({
+ *   label: { en: 'Slug', es: 'Slug' },
+ *   size: 100,
+ *   placeholder: 'my-post-slug',
+ *   meta: { searchable: true, sortable: true }
+ * })
+ * ```
+ */
+declare function useTextField(config: TextFieldConfig & FieldOverrides): FieldDefinition;
+/**
+ * Create a unique text field (required + unique + index always true).
+ *
+ * @example
+ * ```typescript
+ * // Unique code field
+ * code: useTextUniqueField({
+ *   label: { en: 'Code', es: 'Código' },
+ *   size: 50
+ * })
+ *
+ * // Unique slug
+ * slug: useTextUniqueField({
+ *   label: { en: 'Slug', es: 'Slug' },
+ *   size: 100
+ * })
+ * ```
+ */
+declare function useTextUniqueField(config: TextUniqueFieldConfig): FieldDefinition;
+
+/**
+ * Color Field Factory
+ *
+ * Creates color picker fields for hex color values.
+ */
+
+/**
+ * Configuration for color fields.
+ */
+interface ColorFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Default color value (hex format: #RRGGBB) */
+    defaultValue?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a color field (hex color picker).
+ *
+ * @example
+ * ```typescript
+ * primaryColor: useColorField({
+ *   label: { en: 'Primary Color', es: 'Color Principal' },
+ *   defaultValue: '#3b82f6'
+ * })
+ *
+ * backgroundColor: useColorField({
+ *   label: { en: 'Background', es: 'Fondo' },
+ *   required: true
+ * })
+ * ```
+ */
+declare function useColorField(config: ColorFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Media Field Factories
+ *
+ * Creates image and file fields with storage configuration.
+ */
+
+/**
+ * File size type - accepts bytes (number) or human-readable string ('1MB', '512KB').
+ */
+type FileSize = number | `${number}${'B' | 'KB' | 'MB' | 'GB'}`;
+/**
+ * Parse file size from human-readable string to bytes.
+ *
+ * @example
+ * parseFileSize('1MB')   // 1048576
+ * parseFileSize('512KB') // 524288
+ * parseFileSize(1024)    // 1024 (passthrough)
+ */
+declare function parseFileSize(size: FileSize): number;
+/**
+ * Configuration for image fields.
+ */
+interface ImageFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Accepted MIME types (default: 'image/*') */
+    accept?: string;
+    /** Max file size - number (bytes) or string like '1MB', '512KB' (default: '1MB') */
+    maxSize?: FileSize;
+    /** Storage folder path */
+    folder?: string;
+    /** Mark uploaded files as public (accessible without authentication) */
+    isPublic?: boolean;
+    /** Enable SHA256 hash deduplication (default: false) */
+    dedupe?: boolean;
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create an image field with storage configuration.
+ *
+ * @example
+ * ```typescript
+ * // Simple image field
+ * avatar: useImageField({
+ *   label: { en: 'Avatar', es: 'Avatar' },
+ *   folder: 'avatars'
+ * })
+ *
+ * // With size limit and specific formats
+ * logo: useImageField({
+ *   label: { en: 'Logo', es: 'Logo' },
+ *   accept: 'image/png,image/svg+xml',
+ *   maxSize: '512KB',
+ *   folder: 'branding',
+ *   required: true
+ * })
+ * ```
+ */
+declare function useImageField(config: ImageFieldConfig & FieldOverrides): FieldDefinition;
+/**
+ * Configuration for file fields.
+ */
+interface FileFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Accepted MIME types (default: any file) */
+    accept?: string;
+    /** Max file size - number (bytes) or string like '10MB', '1GB' (default: '10MB') */
+    maxSize?: FileSize;
+    /** Storage folder path */
+    folder?: string;
+    /** Mark uploaded files as public (accessible without authentication) */
+    isPublic?: boolean;
+    /** Enable SHA256 hash deduplication (default: false) */
+    dedupe?: boolean;
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a file field with storage configuration.
+ *
+ * @example
+ * ```typescript
+ * // Any file type
+ * attachment: useFileField({
+ *   label: { en: 'Attachment', es: 'Adjunto' },
+ *   folder: 'attachments'
+ * })
+ *
+ * // PDF only with size limit
+ * document: useFileField({
+ *   label: { en: 'Document', es: 'Documento' },
+ *   accept: 'application/pdf',
+ *   maxSize: '5MB',
+ *   folder: 'documents',
+ *   required: true
+ * })
+ *
+ * // Spreadsheets
+ * report: useFileField({
+ *   label: { en: 'Report', es: 'Informe' },
+ *   accept: '.xlsx,.xls,.csv',
+ *   maxSize: '20MB',
+ *   folder: 'reports'
+ * })
+ * ```
+ */
+declare function useFileField(config: FileFieldConfig & FieldOverrides): FieldDefinition;
+/**
+ * Configuration for multi-image fields (gallery).
+ */
+interface MultiImageFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Accepted MIME types (default: 'image/*') */
+    accept?: string;
+    /** Max file size per image - number (bytes) or string like '1MB', '512KB' (default: '1MB') */
+    maxSize?: FileSize;
+    /** Maximum number of images (default: 10) */
+    maxFiles?: number;
+    /** Storage folder path */
+    folder?: string;
+    /** Mark uploaded files as public (accessible without authentication) */
+    isPublic?: boolean;
+    /** Enable SHA256 hash deduplication (default: false) */
+    dedupe?: boolean;
+    /** Thumbnail sizes to auto-generate */
+    thumbnails?: Array<{
+        width: number;
+        height: number;
+    }>;
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a multi-image field (gallery) with storage configuration.
+ *
+ * @example
+ * ```typescript
+ * // Simple gallery
+ * photos: useMultiImageField({
+ *   label: { en: 'Photos', es: 'Fotos' },
+ *   folder: 'gallery'
+ * })
+ *
+ * // With thumbnails and limits
+ * gallery: useMultiImageField({
+ *   label: { en: 'Gallery', es: 'Galería' },
+ *   maxFiles: 20,
+ *   maxSize: '2MB',
+ *   folder: 'products/gallery',
+ *   thumbnails: [{ width: 200, height: 200 }]
+ * })
+ * ```
+ */
+declare function useMultiImageField(config: MultiImageFieldConfig & FieldOverrides): FieldDefinition;
+/**
+ * Configuration for multi-file fields.
+ */
+interface MultiFileFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Accepted MIME types (default: any file) */
+    accept?: string;
+    /** Max file size per file - number (bytes) or string like '10MB', '1GB' (default: '10MB') */
+    maxSize?: FileSize;
+    /** Maximum number of files (default: 10) */
+    maxFiles?: number;
+    /** Storage folder path */
+    folder?: string;
+    /** Mark uploaded files as public (accessible without authentication) */
+    isPublic?: boolean;
+    /** Enable SHA256 hash deduplication (default: false) */
+    dedupe?: boolean;
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a multi-file field with storage configuration.
+ *
+ * @example
+ * ```typescript
+ * // Any file type
+ * attachments: useMultiFileField({
+ *   label: { en: 'Attachments', es: 'Adjuntos' },
+ *   folder: 'attachments'
+ * })
+ *
+ * // PDF documents with limits
+ * documents: useMultiFileField({
+ *   label: { en: 'Documents', es: 'Documentos' },
+ *   accept: 'application/pdf',
+ *   maxFiles: 5,
+ *   maxSize: '20MB',
+ *   folder: 'documents',
+ *   dedupe: true
+ * })
+ * ```
+ */
+declare function useMultiFileField(config: MultiFileFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * URL Field Factory
+ *
+ * Creates URL input fields with common configuration patterns.
+ */
+
+/**
+ * Configuration for URL fields.
+ */
+interface UrlFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** Max string size (default: 500) */
+    size?: number;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Create DB index (default: false) */
+    index?: boolean;
+    /** Default value */
+    defaultValue?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a URL field with common configuration.
+ *
+ * @example
+ * ```typescript
+ * // Simple URL field
+ * website: useUrlField({
+ *   label: { en: 'Website', es: 'Sitio web' }
+ * })
+ *
+ * // Required with placeholder
+ * callback_url: useUrlField({
+ *   label: { en: 'Callback URL', es: 'URL de callback' },
+ *   required: true,
+ *   placeholder: 'https://example.com/callback'
+ * })
+ * ```
+ */
+declare function useUrlField(config: UrlFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Select Field Factory
+ *
+ * Creates select fields with static options or entity references.
+ */
+
+/**
+ * Option for static select fields.
+ */
+interface SelectOption {
+    value: string;
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Optional icon (Iconify format: mdi:home) */
+    icon?: string;
+}
+/**
+ * Configuration for select fields with static options.
+ */
+interface StaticSelectConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Static options array */
+    options: SelectOption[] | string[];
+    /** Default value */
+    defaultValue?: string;
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Max string size (default: 50) */
+    size?: number;
+    /** Create DB index (default: false) */
+    index?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Configuration for select fields with entity reference.
+ */
+interface RelationSelectConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Related table name */
+    table: string;
+    /** Related column (default: 'id') */
+    column?: string;
+    /** API endpoint to fetch options */
+    endpoint: string;
+    /** Field to use as option value (default: 'id') */
+    valueField?: string;
+    /** Field to use as option label (default: 'name') */
+    labelField?: string;
+    /** On delete behavior (default: 'SET NULL') */
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** ID size - use 26 for ULID, 36 for UUID (default: 26) */
+    size?: number;
+    /** Create DB index (default: true for relations) */
+    index?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a select field with static options.
+ *
+ * @example
+ * ```typescript
+ * // Simple string options
+ * status: useSelectField({
+ *   label: { en: 'Status', es: 'Estado' },
+ *   options: ['draft', 'published', 'archived'],
+ *   defaultValue: 'draft'
+ * })
+ *
+ * // Options with labels
+ * priority: useSelectField({
+ *   label: { en: 'Priority', es: 'Prioridad' },
+ *   options: [
+ *     { value: 'low', label: { en: 'Low', es: 'Baja' } },
+ *     { value: 'medium', label: { en: 'Medium', es: 'Media' } },
+ *     { value: 'high', label: { en: 'High', es: 'Alta' } }
+ *   ],
+ *   defaultValue: 'medium',
+ *   required: true
+ * })
+ * ```
+ */
+declare function useSelectField(config: StaticSelectConfig & FieldOverrides): FieldDefinition;
+/**
+ * Create a select field with entity reference (relation).
+ *
+ * @example
+ * ```typescript
+ * category_id: useSelectField({
+ *   label: { en: 'Category', es: 'Categoría' },
+ *   table: 'categories',
+ *   endpoint: '/categories',
+ *   labelField: 'name'
+ * })
+ *
+ * // With cascade delete
+ * author_id: useSelectField({
+ *   label: { en: 'Author', es: 'Autor' },
+ *   table: 'users',
+ *   endpoint: '/users',
+ *   labelField: 'display_name',
+ *   onDelete: 'CASCADE',
+ *   required: true
+ * })
+ * ```
+ */
+declare function useSelectField(config: RelationSelectConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Textarea Field Factory
+ *
+ * Creates multi-line text fields with common configuration patterns.
+ */
+
+/**
+ * Configuration for textarea fields.
+ */
+interface TextareaFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Default value */
+    defaultValue?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a textarea field with common configuration.
+ *
+ * @example
+ * ```typescript
+ * description: useTextareaField({
+ *   label: { en: 'Description', es: 'Descripción' }
+ * })
+ *
+ * notes: useTextareaField({
+ *   label: { en: 'Notes', es: 'Notas' },
+ *   hint: { en: 'Additional notes', es: 'Notas adicionales' }
+ * })
+ * ```
+ */
+declare function useTextareaField(config: TextareaFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * JSON Field Factory
+ *
+ * Creates JSON fields for storing structured data.
+ */
+
+/**
+ * Configuration for JSON fields.
+ */
+interface JsonFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a JSON field with common configuration.
+ *
+ * @example
+ * ```typescript
+ * metadata: useJsonField({
+ *   label: { en: 'Metadata', es: 'Metadatos' }
+ * })
+ *
+ * config: useJsonField({
+ *   label: { en: 'Configuration', es: 'Configuración' },
+ *   required: true
+ * })
+ * ```
+ */
+declare function useJsonField(config: JsonFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Datetime Field Factory
+ *
+ * Creates datetime fields with common configuration patterns.
+ */
+
+/**
+ * Configuration for datetime fields.
+ */
+interface DatetimeFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a datetime field with common configuration.
+ *
+ * @example
+ * ```typescript
+ * expires_at: useDatetimeField({
+ *   label: { en: 'Expires At', es: 'Expira el' },
+ *   meta: { sortable: true }
+ * })
+ *
+ * completed_at: useDatetimeField({
+ *   label: { en: 'Completed At', es: 'Completado el' },
+ *   meta: { showInForm: false, sortable: true }
+ * })
+ * ```
+ */
+declare function useDatetimeField(config: DatetimeFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Number Field Factory
+ *
+ * Creates integer/number fields with common configuration patterns.
+ */
+
+/**
+ * Configuration for number fields.
+ */
+interface NumberFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** Default value */
+    defaultValue?: number;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Validation min/max */
+    validation?: {
+        min?: number;
+        max?: number;
+    };
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a number (integer) field with common configuration.
+ *
+ * @example
+ * ```typescript
+ * retry_count: useNumberField({
+ *   label: { en: 'Retries', es: 'Reintentos' },
+ *   defaultValue: 3,
+ *   validation: { min: 0, max: 10 }
+ * })
+ *
+ * score: useNumberField({
+ *   label: { en: 'Score', es: 'Puntuación' },
+ *   required: true,
+ *   validation: { min: 1, max: 5 }
+ * })
+ * ```
+ */
+declare function useNumberField(config: NumberFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Switch Field Factory
+ *
+ * Creates boolean toggle/switch fields with common configuration patterns.
+ */
+
+/**
+ * Configuration for switch (boolean) fields.
+ */
+interface SwitchFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Default value (default: false) */
+    defaultValue?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a switch (boolean) field with common configuration.
+ *
+ * @example
+ * ```typescript
+ * is_pinned: useSwitchField({
+ *   label: { en: 'Pinned', es: 'Fijado' }
+ * })
+ *
+ * is_read: useSwitchField({
+ *   label: { en: 'Read', es: 'Leído' },
+ *   defaultValue: false,
+ *   meta: { sortable: true }
+ * })
+ * ```
+ */
+declare function useSwitchField(config: SwitchFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Localized Field Factory
+ *
+ * Creates text fields that store LocalizedString as JSON.
+ * Common in masters for display names: { en: "Euro", es: "Euro" }.
+ */
+
+/**
+ * Configuration for localized text fields.
+ */
+interface LocalizedFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: true — localized fields are almost always required) */
+    required?: boolean;
+    /** Metadata overrides (defaults: searchable true, sortable true) */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a text field that stores a LocalizedString as JSON.
+ *
+ * Unlike useTextField (db: string) or useJsonField (input: json),
+ * this uses input: text + db: json — the UI renders language tabs.
+ *
+ * @example
+ * ```typescript
+ * // Master entity label (most common usage)
+ * label: useLocalizedField({
+ *   label: { en: 'Name', es: 'Nombre' }
+ * })
+ *
+ * // Optional localized field
+ * description: useLocalizedField({
+ *   label: { en: 'Description', es: 'Descripción' },
+ *   required: false
+ * })
+ * ```
+ */
+declare function useLocalizedField(config: LocalizedFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Icon Field Factory
+ *
+ * Creates icon picker fields (Iconify format: mdi:home, ph:star).
+ */
+
+/**
+ * Configuration for icon fields.
+ */
+interface IconFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** Max string size (default: 100) */
+    size?: number;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create an icon picker field.
+ *
+ * @example
+ * ```typescript
+ * icon: useIconField({
+ *   label: { en: 'Icon', es: 'Icono' },
+ *   placeholder: 'mdi:home'
+ * })
+ *
+ * icon: useIconField({
+ *   label: { en: 'Icon', es: 'Icono' },
+ *   required: true,
+ *   placeholder: 'mdi:linkedin'
+ * })
+ * ```
+ */
+declare function useIconField(config: IconFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Email Field Factory
+ *
+ * Creates email input fields with validation and common defaults.
+ */
+
+/**
+ * Configuration for email fields.
+ */
+interface EmailFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: inverted from required) */
+    nullable?: boolean;
+    /** Unique constraint (default: false) */
+    unique?: boolean;
+    /** Placeholder text */
+    placeholder?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create an email field with validation and common defaults.
+ *
+ * @example
+ * ```typescript
+ * email: useEmailField({
+ *   label: { en: 'Email', es: 'Correo' },
+ *   required: true,
+ *   placeholder: 'user@example.com'
+ * })
+ *
+ * dpo_email: useEmailField({
+ *   label: { en: 'DPO Email', es: 'Correo del DPO' },
+ *   hint: { en: 'Data Protection Officer email', es: 'Correo del DPO' }
+ * })
+ * ```
+ */
+declare function useEmailField(config: EmailFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Checkbox Field Factory
+ *
+ * Creates boolean checkbox fields with common configuration patterns.
+ */
+
+/**
+ * Configuration for checkbox (boolean) fields.
+ */
+interface CheckboxFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Default value (default: false) */
+    defaultValue?: boolean;
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a checkbox (boolean) field with common configuration.
+ *
+ * @example
+ * ```typescript
+ * is_active: useCheckboxField({
+ *   label: { en: 'Active', es: 'Activo' },
+ *   defaultValue: true
+ * })
+ *
+ * marketing_opt_in: useCheckboxField({
+ *   label: { en: 'Marketing Opt-in', es: 'Consentimiento marketing' },
+ *   meta: { exportable: true }
+ * })
+ * ```
+ */
+declare function useCheckboxField(config: CheckboxFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Password Field Factory
+ *
+ * Creates password input fields with secure defaults (hidden from display, not searchable).
+ */
+
+/**
+ * Configuration for password fields.
+ */
+interface PasswordFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: inverted from required) */
+    nullable?: boolean;
+    /** Max string size (default: 255) */
+    size?: number;
+    /** Placeholder text */
+    placeholder?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Custom validation rules */
+    validation?: FieldDefinition['validation'];
+    /** Metadata overrides (defaults: searchable=false, showInDisplay=false) */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a password field with secure defaults.
+ *
+ * By default, password fields are NOT searchable and NOT shown in display
+ * components (tables, lists). Override via `meta` if needed.
+ *
+ * @example
+ * ```typescript
+ * password: usePasswordField({
+ *   label: { en: 'Password', es: 'Contraseña' },
+ *   required: true,
+ *   validation: { min: 8 }
+ * })
+ *
+ * auth_pass: usePasswordField({
+ *   label: { en: 'SMTP Password', es: 'Contraseña SMTP' },
+ *   hint: { en: 'Optional', es: 'Opcional' }
+ * })
+ * ```
+ */
+declare function usePasswordField(config: PasswordFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Tags Field Factory
+ *
+ * Creates free-form tags input fields stored as JSON arrays.
+ */
+
+/**
+ * Configuration for tags fields.
+ */
+interface TagsFieldConfig {
+    /** Field label (localized) */
+    label: string | {
+        en: string;
+        es?: string;
+    };
+    /** Help text shown below the input */
+    hint?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Is field required? (default: false) */
+    required?: boolean;
+    /** DB nullable (default: true) */
+    nullable?: boolean;
+    /** Placeholder text */
+    placeholder?: string | {
+        en: string;
+        es?: string;
+    };
+    /** Custom validation rules */
+    validation?: FieldDefinition['validation'];
+    /** Options configuration (endpoint or static list) */
+    options?: FieldDefinition['options'];
+    /** Metadata overrides */
+    meta?: FieldDefinition['meta'];
+}
+/**
+ * Create a tags field stored as JSON array.
+ *
+ * @example
+ * ```typescript
+ * keywords: useTagsField({
+ *   label: { en: 'Keywords', es: 'Palabras clave' }
+ * })
+ *
+ * recipients: useTagsField({
+ *   label: { en: 'To', es: 'Para' },
+ *   required: true,
+ *   placeholder: 'user@example.com',
+ *   validation: { min: 1 }
+ * })
+ * ```
+ */
+declare function useTagsField(config: TagsFieldConfig & FieldOverrides): FieldDefinition;
+
+/**
+ * Common Field Definitions
+ *
+ * Pre-configured field definitions for common use cases.
+ * These fields have their `name` assigned from the key when used.
+ */
+
+/**
+ * Standard ID field (ULID string, 26 chars).
+ * @deprecated Use useIdField() for default or useIdField('ulid') explicitly.
+ */
+declare const idField: FieldDefinition;
+/**
+ * Standard user_id field for ownership.
+ * Uses ULID size (26 chars) to match default ID generation.
+ */
+declare const userIdField: FieldDefinition;
+/**
+ * Standard is_active field.
+ */
+declare const isActiveField: FieldDefinition;
+/**
+ * Standard order field for manual sorting.
+ */
+declare const orderField: FieldDefinition;
+
+export { type CheckboxFieldConfig, type ColorFieldConfig, type DatetimeFieldConfig, type EmailFieldConfig, type FieldOverrides, type FileFieldConfig, type FileSize, type IconFieldConfig, type IdFieldConfig, type IdType, type ImageFieldConfig, type JsonFieldConfig, type LocalizedFieldConfig, type MultiFileFieldConfig, type MultiImageFieldConfig, type NumberFieldConfig, type PasswordFieldConfig, type PatternIdConfig, type RelationSelectConfig, type SelectOption, type StaticSelectConfig, type SwitchFieldConfig, type TagsFieldConfig, type TextFieldConfig, type TextUniqueFieldConfig, type TextareaFieldConfig, type UrlFieldConfig, idField, isActiveField, orderField, parseFileSize, useCheckboxField, useColorField, useDatetimeField, useEmailField, useFileField, useIconField, useIdField, useImageField, useJsonField, useLocalizedField, useMultiFileField, useMultiImageField, useNumberField, usePasswordField, useSelectField, useSwitchField, useTagsField, useTextField, useTextUniqueField, useTextareaField, useUrlField, userIdField };