@codeplex-sac/formularios
v1.0.1
Published
Controles de formulario validados para React 19 y MUI v9: campos de texto y numéricos, selectores buscables, buscador con debounce, carga de archivos, color y validadores RUC/DNI.
Readme
@codeplex-sac/formularios
Controles de Formulario Validados, Selectores Remotos y Utilidades Tributarias
Suite de captura de datos para React 19 y MUI v9.5 con densidad base de 40px, búsqueda asíncrona con debounce, selectores buscables, carga de archivos, selector de color y validadores RUC/DNI.
📑 Tabla de Contenidos
- 📦 Requisitos y Dependencias
- 🚀 Instalación
- 🎨 Configuración Inicial
- 🧩 Catálogo de Componentes y API
- CodeplexCampoTexto
- CodeplexCampoNumero
- CodeplexCampoEtiquetado
- CodeplexBuscador
- CodeplexSelector
- CodeplexSelectorBuscable
- CodeplexAutocompletado
- CodeplexCasilla
- CodeplexGrupoRadio
- CodeplexInterruptor
- CodeplexDeslizador
- CodeplexAreaTextoAjustable
- CodeplexListaTransferencia
- CodeplexCargadorArchivos
- CodeplexSelectorColor
- Validadores Tributarios Peruanos (SUNAT / RENIEC)
- ✨ Novedades en v1.0.1
- ♿ Accesibilidad y Rendimiento
- 📄 Licencia
📦 Requisitos y Dependencias
Este paquete está diseñado para proyectos basados en React 19 y Material-UI v9.5:
- Dependencias requeridas / recomendadas:
@codeplex-sac/tema@^1.0.1,@emotion/react@^11.14.0,@emotion/styled@^11.14.0,@mui/icons-material@^9.5.0,@mui/material@^9.5.0,react@^19.0.0,react-dom@^19.0.0
🚀 Instalación
Instala el paquete con tu gestor de paquetes preferido:
# Con Bun (recomendado)
bun add @codeplex-sac/formularios @codeplex-sac/tema@^1.0.1 @emotion/react@^11.14.0 @emotion/styled@^11.14.0 @mui/icons-material@^9.5.0 @mui/material@^9.5.0
# Con NPM
npm install @codeplex-sac/formularios @codeplex-sac/tema@^1.0.1 @emotion/react@^11.14.0 @emotion/styled@^11.14.0 @mui/icons-material@^9.5.0 @mui/material@^9.5.0
# Con PNPM
pnpm add @codeplex-sac/formularios @codeplex-sac/tema@^1.0.1 @emotion/react@^11.14.0 @emotion/styled@^11.14.0 @mui/icons-material@^9.5.0 @mui/material@^9.5.0🎨 Configuración Inicial
Todos los paquetes @codeplex-sac/* consumen los tokens CSS y la paleta MUI v9 del sistema de diseño. Envuelve la raíz de tu aplicación con CodeplexProveedorTema y CodeplexProveedorMui:
import { CodeplexProveedorTema, CodeplexProveedorMui } from '@codeplex-sac/tema';
import { TuVistaPrincipal } from './vistas/principal';
export function App() {
return (
<CodeplexProveedorTema temaPorDefecto="light" capacidad="redSocial">
<CodeplexProveedorMui>
<TuVistaPrincipal />
</CodeplexProveedorMui>
</CodeplexProveedorTema>
);
}Importa las fuentes una sola vez en el punto de entrada de la aplicación (main.tsx). CodeplexProveedorMui no las descarga de Google; sin fuente.css, los iconos de @codeplex-sac/iconos se ven como texto («search», «home»).
import '@codeplex-sac/iconos/fuente.css'; // iconos (Material Symbols Rounded), si usas @codeplex-sac/iconos
import '@fontsource/poppins/500.css'; // titulares de Red Social y de las capacidades
import '@fontsource/inter/400.css'; // texto de Red Social y de las capacidades
import '@fontsource-variable/geist'; // solo con el tema Contaplex-aiFamilias, pesos y el respaldo fuentesGoogle: README de @codeplex-sac/tema, sección «Carga de fuentes».
🧩 Catálogo de Componentes y API
CodeplexCampoTexto
Campo de entrada de texto enterprise con soporte de presets de validación (documento, email, numero, sin-especiales), sanitización automática en tiempo real, restricciones de longitud fija/máxima, búsqueda unificada de DNI (8 dígitos) y RUC (11 dígitos), soporte para autodisparo al desenfocar (onBlur) o presionar Enter/Botón, captura automática de errores de API backend con mensaje de ayuda en rojo, estado de carga con spinner (cargando) y modo área de texto multilínea. Basado en Material UI TextField con la API Codeplex.
Cuándo usar
Úsalo cuando:
- Necesitas un campo de entrada de texto, correo, número o documento con validación y sanitización en tiempo real.
- Creas formularios de consulta o búsqueda de DNI / RUC en APIs de RENIEC, SUNAT o servicios externos.
- Requieres restricciones de caracteres (solo números, sin símbolos especiales, longitud fija/máxima).
- Necesitas feedback visual de carga con bloqueo (
cargando), alertas de error automáticas o campos multilínea.
No lo uses cuando:
- Es un número con controles de incremento/decremento (
+/-) → usaCodeplexCampoNumero. - Es una selección de opciones predefinidas → usa
CodeplexSelectoroCodeplexAutocompletado. - Es una contraseña con botón de mostrar/ocultar ojo → usa el campo tipo password especializado.
Importación
import { CodeplexCampoTexto } from '@codeplex-sac/formularios';
import type {
CodeplexCampoTextoProps,
CodeplexDensidadCampo,
CodeplexEstiloEtiqueta,
CodeplexPosicionEtiqueta,
CodeplexTipoEntradaCampoTexto,
CodeplexDisparoBusqueda,
CodeplexDensidadControl,
} from '@codeplex-sac/formularios';
CodeplexCampoTextotambién se exporta comoCodeplexTextFieldpor compatibilidad.
Ejemplo Mínimo
import { useState } from 'react';
import { CodeplexCampoTexto } from '@codeplex-sac/formularios';
export const EjemploMinimo = () => {
const [nombre, setNombre] = useState('');
return (
<CodeplexCampoTexto
etiqueta="Nombre completo"
valor={nombre}
alCambiar={setNombre}
marcador="Ej: Juan Pérez"
/>
);
};TypeScript Interfaces
/** Contrato de CodeplexCampoTexto; extiende TextFieldProps de MUI omitiendo la API en inglés equivalente. */
export interface CodeplexCampoTextoProps extends Omit<TextFieldProps, 'label' | 'helperText' | 'disabled' | 'readOnly' | 'value' | 'onChange' | 'error' | 'multiline' | 'rows' | 'minRows' | 'maxRows' | 'placeholder' | 'fullWidth' | 'type' | 'onFocus' | 'onBlur' | 'onKeyDown' | 'ref'> {
/** Texto o nodo de la etiqueta */
etiqueta?: React.ReactNode;
/** Texto informativo o de ayuda inferior */
textoAyuda?: React.ReactNode;
/** Valor actual del campo */
valor?: string | number | readonly string[];
/** Callback al cambiar el valor */
alCambiar?: (valor: string) => void;
/**
* Densidad visual y altura total del campo:
* - 'estandar': Altura de 40px (por defecto, canónica de Red Social)
* - 'compacta': Altura de 32px (ideal para tablas o pantallas ultra densas)
* - 'comoda': Altura clásica de MUI (56px)
*/
densidad?: CodeplexDensidadCampo;
/**
* Estilo de la etiqueta:
* - 'flotante': Clásica de Material UI con shrink animado (por defecto)
* - 'superior': Etiqueta fija en la parte superior con asterisco (*) y tipografía de 13px seminegrita
* - 'ninguna': Sin etiqueta visible (usa placeholder)
*/
estiloEtiqueta?: CodeplexEstiloEtiqueta;
/**
* Alias retrocompatible de `estiloEtiqueta` (mismos valores). En Casilla, Radio e Interruptor
* `posicionEtiqueta` indica el lado del control; aquí indica el estilo de la etiqueta.
*/
posicionEtiqueta?: CodeplexPosicionEtiqueta;
/** Marca el campo como obligatorio */
requerido?: boolean;
/** Si es true, añade botón (X) interactivo que limpia el texto en 1 clic */
limpiable?: boolean;
/** Callback ejecutado al hacer clic en el botón de limpiar */
alLimpiar?: () => void;
// Tipos de entrada y validaciones avanzadas
/** Preset de validación: `'texto'`, `'email'`, `'numero'`, `'documento'`, `'sin-especiales'`. */
tipoEntrada?: CodeplexTipoEntradaCampoTexto;
/** Valida que la estructura del texto sea un email válido al desenfocar (`onBlur`). */
soloCorreo?: boolean;
/** Remueve automáticamente cualquier carácter no numérico (`0-9`) mientras el usuario tipea. */
soloNumeros?: boolean;
/** Filtra y remueve símbolos especiales en tiempo real (solo permite letras, dígitos y espacios). */
sinCaracteresEspeciales?: boolean;
// Restricciones de longitud
/** Restringe el campo a una cantidad exacta de dígitos/caracteres (ej. `8` para DNI o `11` para RUC). */
longitudFija?: number;
/** Establece la cantidad máxima de caracteres que se pueden ingresar. */
longitudMaxima?: number;
/** Lista de longitudes que gatillan la búsqueda automática. */
longitudesValidasBusqueda?: number[];
// Eventos de Búsqueda y Estado de Carga (Documento / General)
/**
* Callback de búsqueda ejecutado al presionar Enter, hacer clic en la lupa o desenfocar. Si la
* promesa falla (lanza `Error`), muestra el mensaje en rojo debajo del campo.
*/
alBuscar?: (valor: string) => void | Promise<void>;
/** Configura el trigger de búsqueda: `'completar'`, `'desenfocar'`, `'boton'`, `'enter'` o `'ambos'`. */
dispararBusqueda?: CodeplexDisparoBusqueda;
/** Muestra un botón con icono de lupa al final del campo. */
mostrarBotonBusqueda?: boolean;
/** Activa la búsqueda automática al completar o desenfocar. */
buscarAlCompletar?: boolean;
/** Muestra un spinner `CircularProgress` e inhabilita el campo mientras la consulta está en proceso. */
cargando?: boolean;
/** Milisegundos de espera tras dejar de tipear antes de ejecutar la búsqueda automática. */
tiempoDebounce?: number;
/** Inhabilita la edición del campo de texto. */
deshabilitado?: boolean;
/** Presenta el campo con aspecto de Placa Informativa legible y copiable */
soloLectura?: boolean;
/** Fuerza el estado visual de error (borde rojo). */
error?: boolean;
/** Mensaje de error personalizado a renderizar bajo el input. */
mensajeError?: React.ReactNode;
/** Convierte el campo en un área de texto multilínea (`textarea`). */
multilinea?: boolean;
/** Número fijo de filas para el modo multilínea. */
filas?: number;
/** Altura inicial en filas para área de texto adaptable. */
filasMinimas?: number;
/** Altura máxima en filas para área de texto adaptable. */
filasMaximas?: number;
/** Placeholder informativo dentro del campo. */
marcador?: string;
/** Ocupa el 100% del ancho de su contenedor. */
anchoCompleto?: boolean;
/** Atributo `type` nativo del HTML input (`'text'`, `'password'`, `'email'`, etc.). */
tipo?: React.InputHTMLAttributes<HTMLInputElement>['type'];
/** Icono o elemento decorativo posicionado al inicio del campo (`startAdornment`). */
iconoInicio?: React.ReactNode;
/** Icono o elemento decorativo posicionado al final del campo (`endAdornment`). */
iconoFin?: React.ReactNode;
/** Callback al recibir el foco. */
alEnfocar?: (e: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
/** Callback al perder el foco, ejecutado después de la validación interna. */
alDesenfocar?: (e: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
/** Callback de keydown, ejecutado después del manejo interno de Enter. */
alPresionarTecla?: (e: React.KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
/** Atributos del contenedor externo (la raíz del campo o el envoltorio con etiqueta superior). */
contenedorProps?: React.HTMLAttributes<HTMLDivElement>;
/**
* @deprecated MUI v9 eliminó `InputProps` de `TextField`; usar `slotProps.input`.
* Se conserva por retrocompatibilidad y se fusiona en `slotProps.input`.
*/
InputProps?: Partial<OutlinedInputProps>;
/** Referencia al `<input>` nativo (React 19: `ref` como prop; compatible con React Hook Form). */
ref?: React.Ref<HTMLInputElement>;
}
/** Altura compartida por CampoTexto, CampoNumero y Selector para alinear filas mixtas. */
export type CodeplexDensidadCampo = CodeplexDensidadControl;
/** Estilo de la etiqueta de un campo de entrada. */
export type CodeplexEstiloEtiqueta = 'flotante' | 'superior' | 'ninguna';
/**
* Estilo de la etiqueta de los campos de entrada (`'flotante' | 'superior' | 'ninguna'`).
* Nombre histórico de {@link CodeplexEstiloEtiqueta}; se conserva por retrocompatibilidad.
*/
export type CodeplexPosicionEtiqueta = CodeplexEstiloEtiqueta;
/** Presets de filtrado y validación de la entrada. */
export type CodeplexTipoEntradaCampoTexto =
| 'texto'
| 'email'
| 'numero'
| 'documento'
| 'sin-especiales';
/** Momento en que se ejecuta la validación asíncrona alBuscar. */
export type CodeplexDisparoBusqueda = 'completar' | 'desenfocar' | 'boton' | 'enter' | 'ambos';
/** Densidades admitidas por los campos (CampoTexto, CampoNumero, Selector, Buscador, Autocompletado…). */
export type CodeplexDensidadControl = 'estandar' | 'compacta' | 'comoda';API — Tabla Completa de Props
| Propiedad | Tipo | Por defecto | Requerido | Descripción |
| :--- | :--- | :--- | :---: | :--- |
| etiqueta | React.ReactNode | — | — | Texto o nodo de la etiqueta |
| textoAyuda | React.ReactNode | — | — | Texto informativo o de ayuda inferior |
| valor | string \| number \| readonly string[] | — | — | Valor actual del campo |
| alCambiar | (valor: string) => void | — | — | Callback al cambiar el valor |
| densidad | CodeplexDensidadCampo | 'estandar' | — | Densidad visual y altura total del campo: - 'estandar': Altura de 40px (por defecto, canónica de Red Social) - 'compacta': Altura de 32px (ideal para tablas o pantallas ultra densas) - 'comoda': Altura clásica de MUI (56px) |
| estiloEtiqueta | CodeplexEstiloEtiqueta | — | — | Estilo de la etiqueta: - 'flotante': Clásica de Material UI con shrink animado (por defecto) - 'superior': Etiqueta fija en la parte superior con asterisco (*) y tipografía de 13px seminegrita - 'ninguna': Sin etiqueta visible (usa placeholder) |
| posicionEtiqueta | CodeplexPosicionEtiqueta | — | — | Alias retrocompatible de estiloEtiqueta (mismos valores). En Casilla, Radio e Interruptor posicionEtiqueta indica el lado del control; aquí indica el estilo de la etiqueta. |
| requerido | boolean | false | — | Marca el campo como obligatorio |
| limpiable | boolean | false | — | Si es true, añade botón (X) interactivo que limpia el texto en 1 clic |
| alLimpiar | () => void | — | — | Callback ejecutado al hacer clic en el botón de limpiar |
| tipoEntrada | CodeplexTipoEntradaCampoTexto | 'texto' | — | Preset de validación: 'texto', 'email', 'numero', 'documento', 'sin-especiales'. |
| soloCorreo | boolean | — | — | Valida que la estructura del texto sea un email válido al desenfocar (onBlur). |
| soloNumeros | boolean | — | — | Remueve automáticamente cualquier carácter no numérico (0-9) mientras el usuario tipea. |
| sinCaracteresEspeciales | boolean | — | — | Filtra y remueve símbolos especiales en tiempo real (solo permite letras, dígitos y espacios). |
| longitudFija | number | — | — | Restringe el campo a una cantidad exacta de dígitos/caracteres (ej. 8 para DNI o 11 para RUC). |
| longitudMaxima | number | — | — | Establece la cantidad máxima de caracteres que se pueden ingresar. |
| longitudesValidasBusqueda | number[] | — | — | Lista de longitudes que gatillan la búsqueda automática. |
| alBuscar | (valor: string) => void \| Promise<void> | — | — | Callback de búsqueda ejecutado al presionar Enter, hacer clic en la lupa o desenfocar. Si la promesa falla (lanza Error), muestra el mensaje en rojo debajo del campo. |
| dispararBusqueda | CodeplexDisparoBusqueda | 'ambos' | — | Configura el trigger de búsqueda: 'completar', 'desenfocar', 'boton', 'enter' o 'ambos'. |
| mostrarBotonBusqueda | boolean | — | — | Muestra un botón con icono de lupa al final del campo. |
| buscarAlCompletar | boolean | — | — | Activa la búsqueda automática al completar o desenfocar. |
| cargando | boolean | — | — | Muestra un spinner CircularProgress e inhabilita el campo mientras la consulta está en proceso. |
| tiempoDebounce | number | 500 | — | Milisegundos de espera tras dejar de tipear antes de ejecutar la búsqueda automática. |
| deshabilitado | boolean | — | — | Inhabilita la edición del campo de texto. |
| soloLectura | boolean | — | — | Presenta el campo con aspecto de Placa Informativa legible y copiable |
| error | boolean | — | — | Fuerza el estado visual de error (borde rojo). |
| mensajeError | React.ReactNode | — | — | Mensaje de error personalizado a renderizar bajo el input. |
| multilinea | boolean | — | — | Convierte el campo en un área de texto multilínea (textarea). |
| filas | number | — | — | Número fijo de filas para el modo multilínea. |
| filasMinimas | number | — | — | Altura inicial en filas para área de texto adaptable. |
| filasMaximas | number | — | — | Altura máxima en filas para área de texto adaptable. |
| marcador | string | — | — | Placeholder informativo dentro del campo. |
| anchoCompleto | boolean | — | — | Ocupa el 100% del ancho de su contenedor. |
| tipo | React.InputHTMLAttributes<HTMLInputElement>['type'] | — | — | Atributo type nativo del HTML input ('text', 'password', 'email', etc.). |
| iconoInicio | React.ReactNode | — | — | Icono o elemento decorativo posicionado al inicio del campo (startAdornment). |
| iconoFin | React.ReactNode | — | — | Icono o elemento decorativo posicionado al final del campo (endAdornment). |
| alEnfocar | (e: React.FocusEvent<HTMLInputElement \| HTMLTextAreaElement>) => void | — | — | Callback al recibir el foco. |
| alDesenfocar | (e: React.FocusEvent<HTMLInputElement \| HTMLTextAreaElement>) => void | — | — | Callback al perder el foco, ejecutado después de la validación interna. |
| alPresionarTecla | (e: React.KeyboardEvent<HTMLInputElement \| HTMLTextAreaElement>) => void | — | — | Callback de keydown, ejecutado después del manejo interno de Enter. |
| contenedorProps | React.HTMLAttributes<HTMLDivElement> | — | — | Atributos del contenedor externo (la raíz del campo o el envoltorio con etiqueta superior). |
| InputProps | Partial<OutlinedInputProps> | — | — | Obsoleta. MUI v9 eliminó InputProps de TextField; usar slotProps.input. Se conserva por retrocompatibilidad y se fusiona en slotProps.input. |
| ref | React.Ref<HTMLInputElement> | — | — | Referencia al <input> nativo (React 19: ref como prop; compatible con React Hook Form). |
Además acepta las props de TextFieldProps, excepto disabled, error, fullWidth, helperText, label, maxRows, minRows, multiline, onBlur, onChange, onFocus, onKeyDown, placeholder, readOnly, ref, rows, type, value.
Casos de Uso Reales
1. Búsqueda Unificada de DNI (8 dígitos) y RUC (11 dígitos) con alBuscar
import { useState } from 'react';
import { CodeplexCampoTexto } from '@codeplex-sac/formularios';
export const BusquedaDocumentoCliente = () => {
const [numDocumento, setNumDocumento] = useState('');
const [cliente, setCliente] = useState<any>(null);
const handleBuscar = async (doc: string) => {
// Consulta a API backend
const res = await fetch(`/api/v1/personas/buscar?documento=${doc}`);
if (!res.ok) {
// Al lanzar un Error, CodeplexCampoTexto lo muestra automáticamente en rojo bajo el input
throw new Error(`El documento ${doc} no se encuentra registrado en los padrones de RENIEC/SUNAT.`);
}
const data = await res.json();
setCliente(data);
};
return (
<CodeplexCampoTexto
tipoEntrada="documento"
etiqueta="Buscar DNI (8 dígitos) o RUC (11 dígitos)"
valor={numDocumento}
alCambiar={setNumDocumento}
alBuscar={handleBuscar}
dispararBusqueda="ambos" // Auto-disparo al desenfocar o al pulsar Enter / Botón de la Lupa
/>
);
};2. Sanitización en Tiempo Real (Solo Números o Sin Especiales)
// 1. Campo que bloquea letras y caracteres especiales en tiempo real
<CodeplexCampoTexto
soloNumeros
longitudMaxima={9}
etiqueta="Teléfono Celular"
valor={telefono}
alCambiar={setTelefono}
marcador="999 999 999"
/>
// 2. Campo que remueve símbolos especiales (solo alfanumérico y espacios)
<CodeplexCampoTexto
sinCaracteresEspeciales
etiqueta="Código de Almacén"
valor={codigo}
alCambiar={setCodigo}
marcador="Ej: ALM-2026-X"
/>3. Campo de Correo Electrónico con Validación al Desenfocar (onBlur)
<CodeplexCampoTexto
tipoEntrada="email"
etiqueta="Correo Electrónico Corporativo"
valor={correo}
alCambiar={setCorreo}
marcador="[email protected]"
textoAyuda="Te enviaremos la factura a esta dirección de correo."
/>4. Modo Área de Texto Multilínea Adaptable
<CodeplexCampoTexto
multilinea
filasMinimas={3}
filasMaximas={8}
etiqueta="Observaciones del Pedido"
valor={observaciones}
alCambiar={setObservaciones}
marcador="Ingrese comentarios o instrucciones adicionales..."
/>Accesibilidad y Buenas Prácticas
- Usa
tipoEntrada="email"osoloCorreopara asegurar que el usuario ingrese un correo válido antes de enviar el formulario. - En campos de DNI o RUC, usa
tipoEntrada="documento"para permitir la consulta flexible de ambos tipos de comprobantes sin obligar al usuario a cambiar manualmente de pestaña. - El componente gestiona internamente los atributos
aria-invalidyaria-describedbycomunicando los errores visuales a lectores de pantalla.
CodeplexCampoNumero
Input numérico con controles de incremento/decremento, límites mínimo/máximo, paso configurable y formato de visualización (separador decimal, prefijo, sufijo). Para cantidades, precios, porcentajes y cualquier valor numérico con precisión exacta.
Cuándo usar
Úsalo cuando:
- El usuario ingresa un valor numérico exacto (precio, cantidad, porcentaje, días).
- El valor tiene un rango conocido (mínimo/máximo).
- Quieres controles +/− para incrementar sin usar el teclado.
No lo uses cuando:
- El rango es continuo y la precisión no importa → usa
CodeplexDeslizador. - El valor es texto con números mezclados (número de teléfono, RUC) → usa
CodeplexCampoTexto tipo="tel". - Es un año → usa
CodeplexSelectorFecha.
Importación
import { CodeplexCampoNumero } from '@codeplex-sac/formularios';
import type {
CodeplexCampoNumeroProps,
CodeplexDensidadCampo,
CodeplexEstiloEtiqueta,
CodeplexPosicionEtiqueta,
CodeplexCampoNumeroAlineacion,
CodeplexDensidadControl,
} from '@codeplex-sac/formularios';
CodeplexCampoNumerotambién se exporta comoCodeplexNumberFieldpor compatibilidad.
Ejemplo mínimo
import { useState } from 'react';
import { CodeplexCampoNumero } from '@codeplex-sac/formularios';
export function EjemploMinimo() {
const [cantidad, setCantidad] = useState<number | null>(1);
return (
<CodeplexCampoNumero
etiqueta="Cantidad"
valor={cantidad}
alCambiar={setCantidad}
minimo={1}
maximo={999}
/>
);
}TypeScript Interfaces
/** Extiende TextFieldProps de MUI omitiendo onChange, error y helperText. */
export interface CodeplexCampoNumeroProps extends Omit<TextFieldProps, 'onChange' | 'error' | 'helperText' | 'ref'> {
/** Label del campo. */
etiqueta?: string;
/** Texto de ayuda bajo el campo. */
textoAyuda?: string;
/** Valor mínimo permitido. */
minimo?: number;
/** Valor máximo permitido. */
maximo?: number;
/** Incremento al usar los controles +/−. */
paso?: number;
/** Valor controlado. `null` cuando el campo está vacío. */
valor?: number | null;
/** Valor inicial en modo no controlado. */
valorPorDefecto?: number;
/**
* Densidad visual y altura total del campo numérico:
* - 'estandar': Altura de 40px (por defecto, alineado a Red Social)
* - 'compacta': Altura de 32px
* - 'comoda': Altura clásica de MUI (56px)
*/
densidad?: CodeplexDensidadCampo;
/**
* Estilo de la etiqueta:
* - 'flotante': Clásica de Material UI (por defecto)
* - 'superior': Etiqueta fija en la parte superior con asterisco (*) y tipografía seminegrita
* - 'ninguna': Sin etiqueta visible
*/
estiloEtiqueta?: CodeplexEstiloEtiqueta;
/**
* Alias retrocompatible de `estiloEtiqueta` (mismos valores). En Casilla, Radio e Interruptor
* `posicionEtiqueta` indica el lado del control; aquí indica el estilo de la etiqueta.
*/
posicionEtiqueta?: CodeplexPosicionEtiqueta;
/** Marca el campo como obligatorio */
requerido?: boolean;
/** Alineación del número. Los valores monetarios se alinean a la derecha. */
alineacion?: CodeplexCampoNumeroAlineacion;
/** Muestra los botones +/−. */
mostrarControles?: boolean;
/** Estado de error visual. */
error?: boolean;
/** Texto de error bajo el campo. */
mensajeError?: string;
/** Bloquea el campo y los controles. */
deshabilitado?: boolean;
/** Muestra el valor sin permitir edición. */
soloLectura?: boolean;
/** Ocupa el ancho del contenedor. */
anchoCompleto?: boolean;
/** Callback al cambiar. Recibe `null` si el campo queda vacío. */
alCambiar?: (value: number | null) => void;
/** Se ejecuta al perder el foco. */
alDesenfocar?: TextFieldProps['onBlur'];
/**
* @deprecated MUI v9 eliminó `InputProps` de `TextField`; usar `slotProps.input`.
* Se conserva por retrocompatibilidad y se fusiona en `slotProps.input`.
*/
InputProps?: Partial<OutlinedInputProps>;
/** Referencia al `<input>` nativo (React 19: `ref` como prop; compatible con React Hook Form). */
ref?: React.Ref<HTMLInputElement>;
}
/** Altura compartida por CampoTexto, CampoNumero y Selector para alinear filas mixtas. */
export type CodeplexDensidadCampo = CodeplexDensidadControl;
/** Estilo de la etiqueta de un campo de entrada. */
export type CodeplexEstiloEtiqueta = 'flotante' | 'superior' | 'ninguna';
/**
* Estilo de la etiqueta de los campos de entrada (`'flotante' | 'superior' | 'ninguna'`).
* Nombre histórico de {@link CodeplexEstiloEtiqueta}; se conserva por retrocompatibilidad.
*/
export type CodeplexPosicionEtiqueta = CodeplexEstiloEtiqueta;
export type CodeplexCampoNumeroAlineacion = 'izquierda' | 'centro' | 'derecha';
/** Densidades admitidas por los campos (CampoTexto, CampoNumero, Selector, Buscador, Autocompletado…). */
export type CodeplexDensidadControl = 'estandar' | 'compacta' | 'comoda';API — Tabla Completa de Props
| Propiedad | Tipo | Por defecto | Requerido | Descripción |
| :--- | :--- | :--- | :---: | :--- |
| etiqueta | string | — | — | Label del campo. |
| textoAyuda | string | — | — | Texto de ayuda bajo el campo. |
| minimo | number | — | — | Valor mínimo permitido. |
| maximo | number | — | — | Valor máximo permitido. |
| paso | number | 1 | — | Incremento al usar los controles +/−. |
| valor | number \| null | — | — | Valor controlado. null cuando el campo está vacío. |
| valorPorDefecto | number | — | — | Valor inicial en modo no controlado. |
| densidad | CodeplexDensidadCampo | 'estandar' | — | Densidad visual y altura total del campo numérico: - 'estandar': Altura de 40px (por defecto, alineado a Red Social) - 'compacta': Altura de 32px - 'comoda': Altura clásica de MUI (56px) |
| estiloEtiqueta | CodeplexEstiloEtiqueta | — | — | Estilo de la etiqueta: - 'flotante': Clásica de Material UI (por defecto) - 'superior': Etiqueta fija en la parte superior con asterisco (*) y tipografía seminegrita - 'ninguna': Sin etiqueta visible |
| posicionEtiqueta | CodeplexPosicionEtiqueta | — | — | Alias retrocompatible de estiloEtiqueta (mismos valores). En Casilla, Radio e Interruptor posicionEtiqueta indica el lado del control; aquí indica el estilo de la etiqueta. |
| requerido | boolean | false | — | Marca el campo como obligatorio |
| alineacion | CodeplexCampoNumeroAlineacion | 'centro' | — | Alineación del número. Los valores monetarios se alinean a la derecha. |
| mostrarControles | boolean | true | — | Muestra los botones +/−. |
| error | boolean | — | — | Estado de error visual. |
| mensajeError | string | — | — | Texto de error bajo el campo. |
| deshabilitado | boolean | — | — | Bloquea el campo y los controles. |
| soloLectura | boolean | — | — | Muestra el valor sin permitir edición. |
| anchoCompleto | boolean | false | — | Ocupa el ancho del contenedor. |
| alCambiar | (value: number \| null) => void | — | — | Callback al cambiar. Recibe null si el campo queda vacío. |
| alDesenfocar | TextFieldProps['onBlur'] | — | — | Se ejecuta al perder el foco. |
| InputProps | Partial<OutlinedInputProps> | — | — | Obsoleta. MUI v9 eliminó InputProps de TextField; usar slotProps.input. Se conserva por retrocompatibilidad y se fusiona en slotProps.input. |
| ref | React.Ref<HTMLInputElement> | — | — | Referencia al <input> nativo (React 19: ref como prop; compatible con React Hook Form). |
Además acepta las props de TextFieldProps, excepto error, helperText, onChange, ref.
Casos de uso reales
1. Fila de producto en factura
import { InputAdornment } from '@mui/material';
import { CodeplexCampoNumero } from '@codeplex-sac/formularios';
interface ItemFactura {
descripcion: string;
cantidad: number;
precioUnitario: number;
}
interface FilaProductoFacturaProps {
item: ItemFactura;
alCambiar: (item: ItemFactura) => void;
}
export function FilaProductoFactura({ item, alCambiar }: FilaProductoFacturaProps) {
const subtotal = item.cantidad * item.precioUnitario;
const igv = subtotal * 0.18;
const total = subtotal + igv;
return (
<tr>
<td>{item.descripcion}</td>
<td>
<CodeplexCampoNumero
valor={item.cantidad}
alCambiar={(v) => alCambiar({ ...item, cantidad: v ?? 1 })}
minimo={1}
maximo={9999}
densidad="compacta"
sx={{ width: 120 }}
/>
</td>
<td>
<CodeplexCampoNumero
valor={item.precioUnitario}
alCambiar={(v) => alCambiar({ ...item, precioUnitario: v ?? 0 })}
minimo={0}
paso={0.01}
mostrarControles={false}
alineacion="derecha"
densidad="compacta"
slotProps={{ input: { startAdornment: <InputAdornment position="start">S/</InputAdornment> } }}
/>
</td>
<td style={{ textAlign: 'right' }}>
S/ {subtotal.toLocaleString('es-PE', { minimumFractionDigits: 2 })}
</td>
<td style={{ textAlign: 'right' }}>
S/ {igv.toLocaleString('es-PE', { minimumFractionDigits: 2 })}
</td>
<td style={{ textAlign: 'right', fontWeight: 600 }}>
S/ {total.toLocaleString('es-PE', { minimumFractionDigits: 2 })}
</td>
</tr>
);
}2. Porcentaje de descuento con validación
import { InputAdornment } from '@mui/material';
import { CodeplexCampoNumero } from '@codeplex-sac/formularios';
interface CampoDescuentoProps {
valor: number | null;
alCambiar: (valor: number | null) => void;
}
export function CampoDescuento({ valor, alCambiar }: CampoDescuentoProps) {
const fueraDeRango = valor !== null && (valor < 0 || valor > 100);
return (
<CodeplexCampoNumero
etiqueta="Descuento"
valor={valor}
alCambiar={alCambiar}
minimo={0}
maximo={100}
paso={0.5}
mostrarControles={false}
error={fueraDeRango}
mensajeError={fueraDeRango ? 'El descuento debe estar entre 0 % y 100 %' : undefined}
textoAyuda="Porcentaje sobre el subtotal sin IGV"
alineacion="derecha"
slotProps={{ input: { endAdornment: <InputAdornment position="end">%</InputAdornment> } }}
sx={{ width: 180 }}
/>
);
}3. Días de vencimiento de factura
import { CodeplexCampoNumero } from '@codeplex-sac/formularios';
interface CampoVencimientoProps {
dias: number | null;
alCambiar: (dias: number | null) => void;
}
export function CampoVencimiento({ dias, alCambiar }: CampoVencimientoProps) {
return (
<CodeplexCampoNumero
etiqueta="Plazo de pago (días)"
valor={dias}
alCambiar={alCambiar}
minimo={0}
maximo={365}
paso={15}
textoAyuda="0 = al contado. Los plazos comunes son 15, 30, 45 o 60 días."
sx={{ width: 220 }}
/>
);
}Accesibilidad
- El input es nativo con
type="number";minimoymaximoacotan el valor al salir del campo (se ajusta al límite) y en los controles +/−. - Los controles +/− tienen
aria-label="Aumentar"/aria-label="Disminuir"y quedan fuera del orden de tabulación (tabIndex={-1}). - La
etiquetaestá conectada conhtmlFor/id. aria-invalid="true"se aplica automáticamente cuandoerror={true}.
Errores comunes
✗ No hacer
{/* MAL — usar para RUC, teléfono o código (son textos con dígitos) */}
<CodeplexCampoNumero etiqueta="RUC" valor={ruc} alCambiar={setRuc} />
{/* MAL — no manejar null en el callback */}
<CodeplexCampoNumero alCambiar={(v) => setCantidad(v)} /> // v puede ser null✓ Hacer
{/* BIEN — RUC con CampoTexto */}
<CodeplexCampoTexto etiqueta="RUC" valor={ruc} alCambiar={setRuc} tipo="tel" />
{/* BIEN — manejar null con valor por defecto */}
<CodeplexCampoNumero alCambiar={(v) => setCantidad(v ?? 0)} />Componentes relacionados
| Componente | Cuándo usarlo |
| :--- | :--- |
| CodeplexCampoTexto | Para texto libre, RUC, teléfono, correo. |
| CodeplexDeslizador | Para seleccionar dentro de un rango sin precisión exacta. |
| CodeplexSelectorFecha | Para años, fechas y períodos. |
CodeplexCampoEtiquetado
Envoltura estandarizada de 40px que asocia etiquetas visibles accesibles, asterisco de campo obligatorio, mensajes de ayuda y mensajes de error a cualquier control de formulario.
Importación
import { CodeplexCampoEtiquetado } from '@codeplex-sac/formularios';
import type { CodeplexCampoEtiquetadoProps } from '@codeplex-sac/formularios';TypeScript Interfaces
export interface CodeplexCampoEtiquetadoProps {
/** Texto o nodo de la etiqueta superior */
etiqueta?: React.ReactNode;
/** Marca el campo como obligatorio mostrando un asterisco (*) rojo */
requerido?: boolean;
/** Texto o nodo informativo debajo del control */
textoAyuda?: React.ReactNode;
/** Indica si el campo está en estado de error */
error?: boolean;
/** Mensaje de error a mostrar debajo del control cuando error es true */
mensajeError?: React.ReactNode;
/** Control de formulario envuelto (radio group, switch, dropzone, slider, etc.) */
children: React.ReactNode;
/**
* ID del control que nombra la etiqueta (`<label htmlFor>`). Si se omite, se usa el `id` del
* hijo o se genera uno y se pasa al hijo cuando es un único elemento sin `id`.
*/
id?: string;
/** Clase CSS adicional */
className?: string;
/** Estilos sx de Material UI */
sx?: SxProps<Theme>;
}API — Tabla Completa de Props
CodeplexCampoEtiquetado Wrapper universal para controles de formulario que no poseen etiqueta superior nativa (grupos de radio, checkboxes, switches, selectores de color, dropzones, etc.). Estandariza la tipografía de 13px seminegrita, el asterisco de requerido y los mensajes de error. Accesibilidad: el contenedor es un role="group" nombrado por la etiqueta y descrito por la ayuda o el error; además, la etiqueta apunta con htmlFor al control (su id, el de id o uno generado que se inyecta en el hijo único).
| Propiedad | Tipo | Por defecto | Requerido | Descripción |
| :--- | :--- | :--- | :---: | :--- |
| etiqueta | React.ReactNode | — | — | Texto o nodo de la etiqueta superior |
| requerido | boolean | false | — | Marca el campo como obligatorio mostrando un asterisco (*) rojo |
| textoAyuda | React.ReactNode | — | — | Texto o nodo informativo debajo del control |
| error | boolean | false | — | Indica si el campo está en estado de error |
| mensajeError | React.ReactNode | — | — | Mensaje de error a mostrar debajo del control cuando error es true |
| children | React.ReactNode | — | Sí | Control de formulario envuelto (radio group, switch, dropzone, slider, etc.) |
| id | string | — | — | ID del control que nombra la etiqueta (<label htmlFor>). Si se omite, se usa el id del hijo o se genera uno y se pasa al hijo cuando es un único elemento sin id. |
| className | string | — | — | Clase CSS adicional |
| sx | SxProps<Theme> | — | — | Estilos sx de Material UI |
CodeplexBuscador
Campo de búsqueda interactivo con temporizador de inactividad (debounce) integrado, botón de limpieza instantánea, icono de lupa y accesos rápidos por teclado.
Importación
import { CodeplexBuscador } from '@codeplex-sac/formularios';
import type {
CodeplexBuscadorProps,
CodeplexDensidadCampo,
CodeplexBuscadorForma,
CodeplexDensidadControl,
} from '@codeplex-sac/formularios';Ejemplo Mínimo
import { useState } from 'react';
import { CodeplexBuscador } from '@codeplex-sac/formularios';
export const BuscadorUsuarios = () => {
const [termino, setTermino] = useState('');
return (
<CodeplexBuscador
marcador="Buscar usuario por nombre o correo..."
tiempoDebounce={400}
alCambiar={(texto) => setTermino(texto)}
alBuscar={(texto) => console.log('Búsqueda ejecutada:', texto)}
/>
);
};TypeScript Interfaces
export interface CodeplexBuscadorProps {
/** Valor controlado del texto de búsqueda. Si se omite, el componente gestiona su propio estado. */
valor?: string;
/** Valor inicial en modo no controlado */
valorInicial?: string;
/** Callback inmediato en cada pulsación (sin debounce) */
alCambiar?: (valor: string) => void;
/**
* Callback de búsqueda con debounce. Si devuelve una promesa, el spinner
* permanece visible hasta que se resuelva.
*/
alBuscar?: (termino: string) => void | Promise<void>;
/** Callback ejecutado al limpiar el campo (botón X o tecla Escape) */
alLimpiar?: () => void;
/** Tiempo de espera en milisegundos tras la última pulsación (por defecto 300ms) */
tiempoDebounce?: number;
/** Fuerza el estado de carga externo (ej. consulta remota en curso) */
cargando?: boolean;
/** Texto de marcador (placeholder) */
marcador?: string;
/**
* Densidad visual:
* - 'estandar': 40px (por defecto)
* - 'compacta': 32px
* - 'comoda': 56px
*/
densidad?: CodeplexDensidadCampo;
deshabilitado?: boolean;
/** Expande el buscador al 100% del contenedor. */
anchoCompleto?: boolean;
autoEnfoque?: boolean;
/** Nombre accesible del campo para lectores de pantalla (por defecto 'Buscar') */
etiquetaAccesible?: string;
/**
* Atajo de teclado global que enfoca el campo, escrito con `+` (ej. `"Ctrl+K"`, `"Mod+K"`, `"/"`).
* Modificadores: `Ctrl`, `Alt`, `Mayus`/`Shift`, `Meta`/`Cmd` y `Mod` (Ctrl o ⌘). Se muestra como pista
* mientras el campo está vacío y se anuncia con `aria-keyshortcuts`.
*/
atajo?: string;
/** Muestra la pista visual del `atajo` (por defecto `true`). */
mostrarAtajo?: boolean;
/** Forma del campo: `redondeada` (radio del tema, por defecto) o `pildora`. */
forma?: CodeplexBuscadorForma;
id?: string;
className?: string;
sx?: SxProps<Theme>;
}
/** Altura compartida por CampoTexto, CampoNumero y Selector para alinear filas mixtas. */
export type CodeplexDensidadCampo = CodeplexDensidadControl;
/** Forma de `CodeplexBuscador`. */
export type CodeplexBuscadorForma = 'redondeada' | 'pildora';
/** Densidades admitidas por los campos (CampoTexto, CampoNumero, Selector, Buscador, Autocompletado…). */
export type CodeplexDensidadControl = 'estandar' | 'compacta' | 'comoda';API — Tabla Completa de Props
CodeplexBuscador Barra de búsqueda de una línea (40px por defecto) para cabeceras de tablas y filtros rápidos. Incluye lupa, debounce configurable, spinner de carga (también durante el debounce pendiente), botón (X) reactivo y atajos de teclado: Enter busca al instante y Escape limpia.
| Propiedad | Tipo | Por defecto | Requerido | Descripción |
| :--- | :--- | :--- | :---: | :--- |
| valor | string | — | — | Valor controlado del texto de búsqueda. Si se omite, el componente gestiona su propio estado. |
| valorInicial | string | '' | — | Valor inicial en modo no controlado |
| alCambiar | (valor: string) => void | — | — | Callback inmediato en cada pulsación (sin debounce) |
| alBuscar | (termino: string) => void \| Promise<void> | — | — | Callback de búsqueda con debounce. Si devuelve una promesa, el spinner permanece visible hasta que se resuelva. |
| alLimpiar | () => void | — | — | Callback ejecutado al limpiar el campo (botón X o tecla Escape) |
| tiempoDebounce | number | 300 | — | Tiempo de espera en milisegundos tras la última pulsación (por defecto 300ms) |
| cargando | boolean | false | — | Fuerza el estado de carga externo (ej. consulta remota en curso) |
| marcador | string | 'Buscar...' | — | Texto de marcador (placeholder) |
| densidad | CodeplexDensidadCampo | 'estandar' | — | Densidad visual: - 'estandar': 40px (por defecto) - 'compacta': 32px - 'comoda': 56px |
| deshabilitado | boolean | false | — | — |
| anchoCompleto | boolean | false | — | Expande el buscador al 100% del contenedor. |
| autoEnfoque | boolean | false | — | — |
| etiquetaAccesible | string | 'Buscar' | — | Nombre accesible del campo para lectores de pantalla (por defecto 'Buscar') |
| atajo | string | — | — | Atajo de teclado global que enfoca el campo, escrito con + (ej. "Ctrl+K", "Mod+K", "/"). Modificadores: Ctrl, Alt, Mayus/Shift, Meta/Cmd y Mod (Ctrl o ⌘). Se muestra como pista mientras el campo está vacío y se anuncia con aria-keyshortcuts. |
| mostrarAtajo | boolean | true | — | Muestra la pista visual del atajo (por defecto true). |
| forma | CodeplexBuscadorForma | 'redondeada' | — | Forma del campo: redondeada (radio del tema, por defecto) o pildora. |
| id | string | — | — | — |
| className | string | — | — | — |
| sx | SxProps<Theme> | — | — | — |
Atajo de teclado y forma de píldora
atajo registra un atajo global que enfoca el campo (y selecciona su texto). Se escribe con +:
"Ctrl+K", "Mod+K" (Ctrl en Windows y Linux, ⌘ en macOS) o una sola tecla como "/". Mientras el
campo está vacío se muestra la pista (Ctrl + K); mostrarAtajo={false} la oculta sin quitar el
atajo. forma="pildora" redondea el campo por completo, como en las cabeceras de tablero.
import { CodeplexBuscador } from '@codeplex-sac/formularios';
export const BuscadorCabecera = () => (
<CodeplexBuscador
anchoCompleto
forma="pildora"
atajo="Ctrl+K"
marcador="Buscar comprobantes, clientes, cuentas o reportes…"
alBuscar={(termino) => console.log('Buscar', termino)}
/>
);- Un atajo de una sola tecla sin modificadores (
"/") no actúa si el foco está en otro campo de texto. - El atajo se anuncia con
aria-keyshortcuts(ej.Control+K) y se desactiva condeshabilitado. - El borde lee
--cp-vidrio-borde: con un tema de cristal es el borde de luz; con los opacos, el divisor.
CodeplexSelector
Componente dropdown de selección de opciones enterprise. Soporta selección simple, selección múltiple con chips, búsqueda local en memoria, búsqueda remota / modo servidor (modoServidor) con callback debounced (alBuscar), indicador de carga con spinner (cargando), creación de nuevos registros en caliente (alCrearNuevo) y opciones deshabilitadas. Extiende el componente Select de Material UI con la API Codeplex.
Cuándo usar
Úsalo cuando:
- El usuario debe elegir una o varias opciones de una lista predefinida (5 a 50 opciones) o de una API remota.
- Requieres realizar búsquedas servidor en vivo para autocompletar catálogos extensos (ubigeos, clientes, productos, proveedores) con debounce de 500ms.
- Quieres permitir al usuario agregar una nueva opción inline directamente desde el menú desplegable.
No lo uses cuando:
- Hay menos de 4 opciones simples → usa un grupo de botones de opción (
RadioGroup). - Hay miles de registros y requieres virtualización pesada de listas → usa
CodeplexAutocompletado.
Importación
import { CodeplexSelector } from '@codeplex-sac/formularios';
import type {
CodeplexSelectorProps,
CodeplexSelectorOpcion,
CodeplexDensidadCampo,
CodeplexEstiloEtiqueta,
CodeplexPosicionEtiqueta,
CodeplexSelectorRef,
CodeplexDensidadControl,
} from '@codeplex-sac/formularios';
CodeplexSelectortambién se exporta comoCodeplexSelectpor compatibilidad.
Ejemplo Mínimo
import { useState } from 'react';
import { CodeplexSelector } from '@codeplex-sac/formularios';
const OPCIONES_PAIS = [
{ valor: 'PE', etiqueta: 'Perú' },
{ valor: 'CL', etiqueta: 'Chile' },
{ valor: 'CO', etiqueta: 'Colombia' },
{ valor: 'MX', etiqueta: 'México' },
];
export const EjemploMinimo = () => {
const [pais, setPais] = useState('PE');
return (
<CodeplexSelector
etiqueta="País de Residencia"
opciones={OPCIONES_PAIS}
valor={pais}
alCambiar={(e) => setPais(e.target.value as string)}
/>
);
};TypeScript Interfaces
/** Contrato de CodeplexSelector; extiende SelectProps de MUI (salvo renderValue). */
export interface CodeplexSelectorProps extends Omit<SelectProps, 'renderValue' | 'ref'> {
/** Etiqueta flotante del selector. */
etiqueta?: string;
/** Valor seleccionado en modo controlado. */
valor?: SelectProps['value'];
/** Valor inicial en modo no controlado (alias en español de `defaultValue`). */
valorPorDefecto?: SelectProps['defaultValue'];
/** Arreglo de opciones (`{ valor, etiqueta, deshabilitado }`). */
opciones?: CodeplexSelectorOpcion[];
/** Texto informativo debajo del selector. */
textoAyuda?: ReactNode;
/** Placeholder mostrado cuando no hay ninguna opción seleccionada. */
marcador?: string;
/** Personaliza cómo se pinta el valor seleccionado dentro del campo (sustituye a chips y marcador). */
renderizarValor?: (value: unknown) => ReactNode;
/** Handler invocado al seleccionar una opción. */
alCambiar?: SelectProps['onChange'];
/** Tamaño del componente (`small` para tablas o barras densas). */
tamano?: SelectProps['size'];
/** Muestra un botón al final del menú para crear un nuevo registro en un modal o formulario. */
alCrearNuevo?: () => void;
/** Texto del botón de creación inline. */
textoCrearNuevo?: string;
/** Texto de error a mostrar en color rojo bajo el selector. */
mensajeError?: string;
/** Muestra un campo de búsqueda en la parte superior del menú desplegable. */
buscable?: boolean;
/** Expande el selector al 100% del contenedor. */
anchoCompleto?: boolean;
/**
* Densidad visual y altura total del selector:
* - 'estandar': Altura de 40px (por defecto, canónica de Red Social)
* - 'compacta': Altura de 32px
* - 'comoda': Altura clásica de MUI (56px)
*/
densidad?: CodeplexDensidadCampo;
/**
* Estilo de la etiqueta:
* - 'flotante': Clásica de Material UI (por defecto)
* - 'superior': Etiqueta fija en la parte superior con asterisco (*) y tipografía seminegrita
* - 'ninguna': Sin etiqueta visible
*/
estiloEtiqueta?: CodeplexEstiloEtiqueta;
/**
* Alias retrocompatible de `estiloEtiqueta` (mismos valores). En Casilla, Radio e Interruptor
* `posicionEtiqueta` indica el lado del control; aquí indica el estilo de la etiqueta.
*/
posicionEtiqueta?: CodeplexPosicionEtiqueta;
/** Marca el selector como obligatorio */
requerido?: boolean;
/** Si es true, añade botón (X) para deseleccionar rápidamente */
limpiable?: boolean;
/** Callback posterior a la limpieza con el botón (X). */
alLimpiar?: () => void;
// Modo Servidor y Búsqueda Remota con Debounce
/**
* Activa el modo servidor para desacoplar el filtrado local y gatillar el callback `alBuscar`
* con debounce.
*/
modoServidor?: boolean;
/** Callback de búsqueda remota invocado tras presionar teclas con debounce. */
alBuscar?: (terminoBusqueda: string) => void | Promise<void>;
/** Muestra un spinner de carga dentro del selector mientras la API responde. */
cargando?: boolean;
/** Placeholder del input de búsqueda del menú desplegable. */
marcadorBusqueda?: string;
/** Tiempo de espera en ms tras tipear antes de invocar `alBuscar`. */
tiempoDebounce?: number;
/** Referencia al manejador del input (React 19: `ref` como prop). */
ref?: React.Ref<CodeplexSelectorRef>;
}
/** Elemento de la lista de opciones. */
export interface CodeplexSelectorOpcion {
valor: string | number;
etiqueta: string;
deshabilitado?: boolean;
}
/** Altura compartida por CampoTexto, CampoNumero y Selector para alinear filas mixtas. */
export type CodeplexDensidadCampo = CodeplexDensidadControl;
/** Estilo de la etiqueta de un campo de entrada. */
export type CodeplexEstiloEtiqueta = 'flotante' | 'superior' | 'ninguna';
/**
* Estilo de la etiqueta de los campos de entrada (`'flotante' | 'superior' | 'ninguna'`).
* Nombre histórico de {@link CodeplexEstiloEtiqueta}; se conserva por retrocompatibilidad.
*/
export type CodeplexPosicionEtiqueta = CodeplexEstiloEtiqueta;
/**
* Manejador que MUI `Select` entrega en `inputRef`: no es el `<input>` nativo, sino un objeto con
* `focus()` (lo usa React Hook Form para enfocar errores), el nodo del input oculto y el valor.
*/
export interface CodeplexSelectorRef {
focus: () => void;
node: HTMLInputElement | null;
value: unknown;
}
/** Densidades admitidas por los campos (CampoTexto, CampoNumero, Selector, Buscador, Autocompletado…). */
export type CodeplexDensidadControl = 'estandar' | 'compacta' | 'comoda';API — Tabla Completa de Props
| Propiedad | Tipo | Por defecto | Requerido | Descripción |
| :--- | :--- | :--- | :---: | :--- |
| etiqueta | string | — | — | Etiqueta flotante del selector. |
| valor | SelectProps['value'] | — | — | Valor seleccionado en modo controlado. |
| valorPorDefecto | SelectProps['defaultValue'] | — | — | Valor inicial en modo no controlado (alias en español de defaultValue). |
| opciones | CodeplexSelectorOpcion[] | — | — | Arreglo de opciones ({ valor, etiqueta, deshabilitado }). |
| textoAyuda | ReactNode | — | — | Texto informativo debajo del selector. |
| marcador | string | — | — | Placeholder mostrado cuando no hay ninguna opción seleccionada. |
| renderizarValor | (value: unknown) => ReactNode | — | — | Personaliza cómo se pinta el valor seleccionado dentro del campo (sustituye a chips y marcador). |
| alCambiar | SelectProps['onChange'] | — | — | Handler invocado al seleccionar una opción. |
| tamano | SelectProps['size'] | — | — | Tamaño del componente (small para tablas o barras densas). |
| alCrearNuevo | () => void | — | — | Muestra un botón al final del menú para crear un nuevo registro en un modal o formulario. |
| textoCrearNuevo | string | 'Agregar opción...' | — | Texto del botón de creación inline. |
| mensajeError | string | — | — | Texto de error a mostrar en color rojo bajo el selector. |
| buscable | boolean | — | — | Muestra un campo de búsqueda en la parte superior del menú desplegable. |
| anchoCompleto | boolean | — | — | Expande el selector al 100% del contenedor. |
| densidad | CodeplexDensidadCampo | 'estandar' | — | Densidad visual y altura total del selector: - 'estandar': Altura de 40px (por defecto, canónica de Red Social) - 'compacta': Altura de 32px - 'comoda': Altura clásica de MUI (56px) |
| estiloEtiqueta | CodeplexEstiloEtiqueta | — | — | Estilo de la etiqueta: - 'flotante': Clásica de Material UI (por defecto) - 'superior': Etiqueta fija en la parte superior con asterisco (*) y tipografía seminegrita - 'ninguna': Sin etiqueta visible |
| posicionEtiqueta | CodeplexPosicionEtiqueta | — | — | Alias retrocompatible de estiloEtiqueta (mismos valores). En Casilla, Radio e Interruptor posicionEtiqueta indica el lado del control; aquí indica el estilo de la etiqueta. |
| requerido | boolean | false | — | Marca el selector como obligatorio |
| limpiable | boolean | false | — | Si es true, añade botón (X) para deseleccionar rápidamente |
| alLimpiar | () => void | — | — | Callback posterior a la limpieza con el botón (X). |
| modoServidor | boolean | — | — | Activa el modo servidor para desacoplar el filtrado local y gatillar el callback alBuscar con debounce. |
| alBuscar | (terminoBusqueda: string) => void \| Promise<void> | — | — | Callback de búsqueda remota invocado tras presionar teclas con debounce. |
| cargando | boolean | — | — | Muestra un spinner de carga dentro del selector mientras la API responde. |
| marcadorBusqueda | string | 'Buscar...' | — | Placeholder del input de búsqueda del menú desplegable. |
| tiempoDebounce | number | 500 | — | Tiempo de espera en ms tras tipear antes de invocar alBuscar. |
| ref | React.Ref<CodeplexSelectorRef> | — | — | Referencia al manejador del input (React 19: ref como prop). |
| variant | "filled" \| "outlined" \| "standard" \| undefined | 'outlined' | — | Heredada de FilledSelectProps. |
| multiple | boolean \| undefined | false | — | Heredada de BaseSelectProps. |
Además acepta las props de SelectProps, excepto ref, renderValue.
Casos de Uso Reales
1. Modo Servidor / Búsqueda Remota con Debounce (alBuscar)
import { useState } from 'react';
import { CodeplexSelector } from '@codeplex-sac/formularios';
export const SelectorClienteServidor = () => {
const [clienteId, setClienteId] = useState('');
const [opcionesClientes, setOpcionesClientes] = useState<any[]>([]);
const [cargando, setCargando] = useState(false);
const handleBuscarClientes = async (termino: string) => {
setCargando(true);
try {
const res = await fetch(`/api/v1/clientes?q=${encodeURIComponent(termino)}`);
const data = await res.json();
setOpcionesClientes(
data.map((c: any) => ({ valor: c.id, etiqueta: `${c.ruc} - ${c.razon_social}` }))
);
} finally {
setCargando(false);
}
};
return (
<CodeplexSelector
buscable
modoServidor
cargando={cargando}
alBuscar={handleBuscarClientes}
tiempoDebounce={500}
marcadorBusqueda="Buscar por RUC o Razón Social..."
etiqueta="Cliente / Proveedor"
opciones={opcionesClientes}
valor={clienteId}
alCambiar={(e) => setClienteId(e.target.value as string)}
/>
);
};2. Selección Múltiple con Chips
import { useState } from 'react';
import { CodeplexSelector } from '@codeplex-sac/formularios';
const CATEGORIAS = [
{ valor: 'tec', etiqueta: 'Tecnología' },
{ valor: 'log', etiqueta: 'Logística' },
{ valor: 'fin', etiqueta: 'Finanzas' },
{ valor: 'rrhh', etiqueta: 'Recursos Humanos' },
];
export const SelectorCategoriasMultiples = () => {
const [seleccionados, setSeleccionados] = useState<string[]>(['tec', 'fin']);
return (
<CodeplexSelector
multiple
buscable
etiqueta="Categorías del Proyecto"
opciones={CATEGORIAS}
valor={seleccionados}
alCambiar={(e) => setSeleccionados(e.target.value as string[])}
/>
);
};3. Creación de Nuevas Opciones Inline (alCrearNuevo)
<CodeplexSelector
buscable
etiqueta="Centro de Costos"
opciones={centrosCosto}
valor={centroCostoId}
alCambiar={(e) => setCentroCostoId(e.target.value as string)}
alCrearNuevo={() => abrirModalNuevoCentroCosto()}
textoCrearNuevo="+ Registrar Nuevo Centro de Costo"
/>Ancho completo
Con anchoCompleto (por defecto true) el desplegable ocupa todo el ancho de su contenedor con cualquier estiloEtiqueta, también superior. Usa anchoCompleto={false} para que se ajuste a su contenido.
Accesibilidad y Buenas Prácticas
- Si el catálogo tiene más de 10 elementos, activa siempre
buscablepara que el usuario pueda escribir y filtrar la opción deseada. - En formularios largos, usa
marcador="Seleccione una opción..."para dejar en claro que el usuario aún no ha realizado una selección activa.
CodeplexSelectorBuscable
Selector de selección única que abre un diálogo con barra de búsqueda: consulta las opciones (normalmente remotas) con alBuscar y debounce, y muestra cada resultado como tarjeta (título, subtítulo, ícono y badge) definida por renderizarElemento.
Importación
import { CodeplexSelectorBuscable } from '@codeplex-sac/formularios';
import type {
CodeplexSelectorBuscableProps,
CodeplexElementoBuscable,
CodeplexVarianteBadgeBuscable,
} from '@codeplex-sac/formularios';Ejemplo Mínimo
import { useState } from 'react';
import { CodeplexSelectorBuscable } from '@codeplex-sac/formularios';
interface Departamento {
ubigeo: string;
nombre: string;
}
const DEPARTAMENTOS: Departamento[] = [
{ ubigeo: '15', nombre: 'Lima' },
{ ubigeo: '04', nombre: 'Arequipa' },
{ ubigeo: '08', nombre: 'Cusco' },
];
// Simulates a remote query; in a real app this calls the API.
const buscarDepartamentos = async (consulta: string): Promise<Departamento[]> =>
DEPARTAMENTOS.filter((d) => d.nombre.toLowerCase().includes(consulta.toLowerCase()));
export function SelectorUbicacion() {
const [seleccion, setSeleccion] = useState<Departamento | null>(DEPARTAMENTOS[0]);
return (
<CodeplexSelectorBuscable
etiqueta="Departamento"
valor={seleccion}
alSeleccionar={setSeleccion}
alBuscar={buscarDepartamentos}
renderizarElemento={(d) => ({ titulo: d.nombre, subtitulo: `Ubigeo ${d.ubigeo}` })}
obtenerClave={(d) => d.ubigeo}
limpiable
/>
);
}TypeScript Interfaces
export interface CodeplexSelectorBuscableProps<TElemento> {
/** Etiqueta superior del campo */
etiqueta?: string;
/** Elemento seleccionado actualmente */
valor?: TElemento | null;
/** Callback al seleccionar un elemento o al limpiar (recibe null) */
alSeleccionar: (elemento: TElemento | null) => void;
/** Consulta (normalmente remota) que devuelve los elementos que coinciden con el término */
alBuscar: (consulta: string) => Promise<TElemento[]>;
/** Proyección del elemento a su tarjeta visual (título, subtítulo, icono y badge) */
renderizarElemento: (elemento: TElemento) => CodeplexElementoBuscable;
/** Clave única y estable del elemento. Por defecto se usa el título renderizado. */
obtenerClave?: (elemento: TElemento) => string | number;
/** Marcador del disparador cuando no hay selección */
marcador?: string;
/** Marcador de la caja de búsqueda dentro del diálogo */
marcadorBusqueda?: string;
/** Título del diálogo. Por defecto usa la etiqueta. */
tituloDialogo?: string;
/** Densidad del disparador: 'estandar' (40px, por defecto) o 'compacta' (32px) */
densidad?: 'estandar' | 'compacta';
deshabilitado?: boolean;
/** Muestra botón (X) para quitar la selección */
limpiable?: boolean;
requerido?: boolean;
error?: boolean;
mensajeError?: React.ReactNode;
textoAyuda?: React.ReactNode;
anchoCompleto?: boolean;
/** Tiempo de espera tras la última pulsación antes de consultar (por defecto 300ms) */
tiempoDebounce?: number;
/** Máximo de resultados renderizados; el resto se invita a refinar la búsqueda (por defecto 50) */
limiteResultados?: number;
/** Texto mostrado cuando la consulta no devuelve elementos */
textoSinResultados?: string;
/** Referencia al botón disparador */
ref?: React.Ref<HTMLButtonElement>;
id?: string;
className?: string;
sx?: SxProps<Theme>;
}
/** Representación visual de un elemento en la lista de resultados */
export interface CodeplexElementoBuscable {
titulo: string;
subtitulo?: string;
icono?: React.ReactNode;
etiquetaBadge?: string;
varianteBadge?: CodeplexVarianteBadgeBuscable;
}
export type CodeplexVarianteBadgeBuscable = 'exito' | 'advertencia' | 'error' | 'neutro';
CodeplexSelectorBuscablerecibeCodeplexSelectorBuscableProps<TElemento>.
API — Tabla Completa de Props
CodeplexSelectorBuscable Selector de entidades masivas (> 1,000 registros: clientes por RUC, plan de cuentas, colaboradores). El disparador abre un diálogo modal deslizable con su propia caja de búsqueda con debounce, consulta remota, navegación por teclado (↑ ↓ Enter) y tarjetas enriquecidas con badge de estado. El diálogo solo se monta mientras está abierto.
| Propiedad | Tipo | Por defecto | Requerido | Descripción |
| :--- | :--- | :--- | :---: | :--- |
| etiqueta | string | — | — | Etiqueta superior del campo |
| valor | TElemento \| null | null | — | Elemento seleccionado actualmente |
| alSeleccionar | (elemento: TElemento \| null) => void | — | Sí | Callback al seleccionar un elemento o al limpiar (recibe null) |
| alBuscar | (consulta: string) => Promise<TElemento[]> | — | Sí | Consulta (normalmente remota) que devuelve los elementos que coinciden con el término |
| renderizarElemento | (elemento: TElemento) => CodeplexElementoBuscable | — | Sí | Proyección del elemento a su tarjeta visual (título, subtítulo, icono y badge) |
| obtenerClave | (elemento: TElemento) => string \| number | — | — | Clave única y estable del elemento. Por defecto se usa el título renderizado. |
| marcador | string | 'Seleccionar...' | — | Marcador del disparador cuando no hay selección |
| marcadorBusqueda | string | 'Escriba para buscar...' | — | Marcador de la caja de búsqueda dentro del diálogo |
| tituloDialogo | string | — | — | Título del diálogo. Por defecto usa la etiqueta. |
| densidad | 'estandar' \| 'compacta' | 'estandar' | — | Densidad del disparador: 'estandar' (40px, por defecto) o 'compacta' (32px) |
| deshabilitado | boolean | false | — | — |
| limpiable | boolean | false | — | Muestra botón (X) para quitar la selección |
| requerido | boolean | false | — | — |
| error | boolean | false | — | — |
| mensajeError | React.ReactNode | — | — | — |
| textoAyuda | React.ReactNode | — | — | — |
| anchoCompleto | boolean | false | — | — |
| tiempoDebounce | number | 300 | — | Tiempo de espera tras la última pulsación antes de consultar (por defecto 300ms) |
| limiteResultados | number | 50 | — | Máximo de resultados renderizados; el resto se invita a refinar la búsqueda (por defecto 50) |
| textoSinResultados | string | 'No se encontraron resultados.' | — | Texto mostrado cuando la consulta no devuelve elementos |
| ref | React.Ref<HTMLButtonElement> | — | — | Referencia al botón disparador |
| id | string | — | — | — |
| className | string | — | — | — |
| sx | SxProps<Theme> | — | — | — |
CodeplexAutocompletado
Campo de texto con sugerencias filtradas en tiempo real. Soporta búsqueda asíncrona, selección múltiple con chips, agrupación de opciones y creación de nuevas entradas. Basado en el Autocomplete de MUI.
Cuándo usar
Úsalo cuando:
- El catálogo tiene más de 10 opciones y el usuario necesita buscar por nombre.
- La búsqueda es asíncrona (API del servidor mientras el usuario escribe).
- Quieres selección múltiple con valor
