Props Comunes

Props Comunes

Todos los componentes de formulario comparten un conjunto de propiedades comunes que se pueden utilizar para personalizar su apariencia y comportamiento. Estas propiedades están definidas en BaseFieldProps y están disponibles para todos los tipos de campos.

Props de Etiqueta

Propiedad	Tipo	Requerido	Por defecto	Descripción
label	string	No	-	El texto de la etiqueta para el campo. Puede contener HTML.
hideLabel	boolean	No	false	Si se debe ocultar visualmente la etiqueta (útil para accesibilidad cuando el label se muestra de otra forma)
label_className	string	No	-	Clases CSS adicionales para la etiqueta

Ejemplo de label con HTML

{
  type: "text",
  label: "Acepto los <a href='/terms'>términos y condiciones</a>",
  // ...
}

Props de Layout

Propiedad	Tipo	Requerido	Por defecto	Descripción
layout	FieldLayoutConfig	No	-	Configuración de layout del campo (anchura, orden, visibilidad)
wrapper_className	string	No	-	Clases CSS adicionales para el wrapper del campo (FormItem)

layout - Configuración Semántica

El objeto layout permite controlar el layout del campo de forma semántica:

layout: {
  width?: {
    mobile?: "auto" | "full" | "half" | "third";
    tablet?: "auto" | "full" | "half" | "third";
    desktop?: "auto" | "full" | "half" | "third";
  };
  order?: number;
  visibility?: {
    mobile?: "visible" | "hidden";
    tablet?: "visible" | "hidden";
    desktop?: "visible" | "hidden";
  };
}

width - Anchura Semántica

En lugar de pensar en números de columnas, piensa en términos semánticos:

• "auto": El sistema decide automáticamente (por defecto)
• "full": El campo ocupa todo el ancho disponible (ideal para textareas, date ranges, etc.)
• "half": El campo ocupa la mitad del ancho (ideal para pares como nombre/apellido)
• "third": El campo ocupa un tercio del ancho (ideal para grupos de tres)

Ejemplo de Layout Responsive

{
  type: "text",
  label: "Full Name",
  layout: {
    width: {
      mobile: "full",   // Ancho completo en móvil
      desktop: "half",  // Mitad del ancho en desktop
    }
  }
}

Ejemplo de Campo Siempre Full Width

{
  type: "textarea",
  label: "Biography",
  layout: {
    width: {
      mobile: "full",
      desktop: "full",  // Siempre ancho completo
    }
  }
}

order - Orden Visual

Controla el orden de visualización de los campos:

{
  type: "text",
  label: "First Field",
  layout: {
    order: 1,  // Se mostrará primero
  }
}

visibility - Visibilidad por Breakpoint

Controla la visibilidad del campo en diferentes dispositivos:

{
  type: "text",
  label: "Mobile Only Field",
  layout: {
    visibility: {
      desktop: "hidden",  // Oculto en desktop
    }
  }
}

Props de Input

Propiedad	Tipo	Requerido	Por defecto	Descripción
input_className	string	No	-	Clases CSS adicionales para el input/control
size	"xs" | "sm" | "md" | "lg" | "xl"	No	"md"	Tamaño del campo. Aplica a inputs, textareas y controles similares
icon	ReactNode	No	-	Elemento React para el icono (puede ser de lucide-react, iconify, o cualquier componente)
iconProps	object	No	-	Props adicionales para el icono. Incluye className y cualquier otra prop personalizada
value	unknown	No	-	Valor inicial del campo. El tipo depende del tipo de campo (string, number, boolean, Date, array, etc.)

Ejemplo de Icono

import { Mail } from "lucide-react";

{
  type: "email",
  label: "Email",
  icon: <Mail className="w-4 h-4" />,
  iconProps: {
    className: "text-gray-400"
  }
}

Props de Validación

Propiedad	Tipo	Requerido	Por defecto	Descripción
schema	z.ZodType	Sí	-	Esquema Zod para validación. Requerido para todos los campos
error_className	string	No	-	Clases CSS adicionales para el mensaje de error
helperText	string	No	-	Texto de ayuda que se muestra debajo del campo
helper_className	string	No	-	Clases CSS adicionales para el texto de ayuda
tooltip	string	No	-	Texto de ayuda contextual que se muestra en un tooltip al hacer hover sobre el icono de ayuda

Ejemplo de Validación y Ayuda

import { z } from "zod";

{
  type: "email",
  label: "Email",
  schema: z.string().email("Email inválido"),
  helperText: "Usaremos este email para contactarte",
  tooltip: "El email debe ser válido y único",
  error_className: "text-red-600 font-semibold"
}

Props de Estado

Propiedad	Tipo	Requerido	Por defecto	Descripción
hidden	boolean | ((values: Record<string, unknown>) => boolean)	No	false	Si se debe ocultar el campo. Puede ser un valor booleano o una función que se evalúa dinámicamente
disabled	boolean | ((values: Record<string, unknown>) => boolean)	No	false	Si el campo está deshabilitado. Puede ser un valor booleano o una función que se evalúa dinámicamente
readOnly	boolean | ((values: Record<string, unknown>) => boolean)	No	false	Si el campo es de solo lectura. Puede ser un valor booleano o una función que se evalúa dinámicamente

Ejemplo de Estado Condicional

{
  type: "text",
  label: "Nombre completo",
  // Oculto si el usuario es anónimo
  hidden: (values) => values.userType === "anonymous",
  // Deshabilitado si ya está verificado
  disabled: (values) => values.isVerified === true,
  // Solo lectura si es un campo del sistema
  readOnly: (values) => values.isSystemField === true
}

Orden de Prioridad

Cuando se usan funciones para hidden, disabled o readOnly, estas se evalúan en cada render y tienen acceso a todos los valores actuales del formulario a través del parámetro values.

Notas Importantes

1. schema es requerido: Todos los campos deben tener un esquema Zod definido para la validación
2. label puede ser HTML: El label acepta HTML, útil para enlaces o texto formateado
3. Funciones reactivas: hidden, disabled y readOnly pueden ser funciones que se re-evalúan cuando cambian los valores del formulario
4. Layout semántico: Usa layout.width con valores semánticos ("full", "half", "third") en lugar de números de columnas
5. Breakpoints semánticos: El sistema usa breakpoints semánticos (mobile, tablet, desktop) en lugar de breakpoints técnicos de Tailwind
6. Iconos flexibles: El icono puede ser cualquier ReactNode, permitiendo usar cualquier librería de iconos