@codeplex-sac/formularios 0.1.2 → 0.1.5

package/README.md

@@ -0,0 +1,442 @@
+# @codeplex-sac/formularios
+
+Biblioteca de componentes de formulario para aplicaciones React, basada en **Material UI**. Todos los inputs siguen la API en **Español** de la suite `@codeplex-sac/*`.
+
+## Instalación
+
+```bash
+bun add @codeplex-sac/formularios @codeplex-sac/tema @mui/material @emotion/react @emotion/styled
+```
+
+> [!IMPORTANT]
+> Envuelve la aplicación con `CodeplexProveedorTema` de `@codeplex-sac/tema` para que los estilos funcionen correctamente.
+
+---
+
+## Componentes
+
+---
+
+### CodeplexCampoTexto
+
+Entrada de texto con iconos, validación visual y soporte multilinea.
+
+**Ejemplo:**
+```tsx
+import { CodeplexCampoTexto } from '@codeplex-sac/formularios';
+
+export const Ejemplo = () => (
+  <CodeplexCampoTexto
+    etiqueta="Correo electrónico"
+    marcador="usuario@empresa.com"
+    tipo="email"
+    anchoCompleto
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `etiqueta` | `ReactNode` | — | Texto de la etiqueta superior. |
+| `valor` | `string \| number` | — | Valor controlado del input. |
+| `alCambiar` | `ChangeEventHandler` | — | Evento al cambiar el valor. |
+| `marcador` | `string` | — | Texto placeholder. |
+| `tipo` | `string` | `'text'` | Tipo HTML del input (`email`, `password`, `number`…). |
+| `multilinea` | `boolean` | `false` | Activa modo textarea. |
+| `filas` | `number` | — | Número fijo de filas en multilinea. |
+| `filasMinimas` | `number` | — | Mínimo de filas en multilinea autoajustable. |
+| `filasMaximas` | `number` | — | Máximo de filas en multilinea autoajustable. |
+| `iconoInicio` | `ReactNode` | — | Icono al inicio del campo. |
+| `iconoFin` | `ReactNode` | — | Icono al final del campo. |
+| `error` | `boolean` | `false` | Activa estado de error. |
+| `mensajeError` | `ReactNode` | — | Texto de error informativo. |
+| `textoAyuda` | `ReactNode` | — | Texto de ayuda bajo el campo. |
+| `deshabilitado` | `boolean` | `false` | Deshabilita la interacción. |
+| `soloLectura` | `boolean` | `false` | Permite visualizar sin editar. |
+| `anchoCompleto` | `boolean` | `false` | Ocupa el 100% del contenedor. |
+| `alEnfocar` | `FocusEventHandler` | — | Evento al enfocar el campo. |
+| `alDesenfocar` | `FocusEventHandler` | — | Evento al perder el foco. |
+
+---
+
+### CodeplexCampoNumero
+
+Campo numérico con botones de incremento/decremento integrados.
+
+**Ejemplo:**
+```tsx
+import { CodeplexCampoNumero } from '@codeplex-sac/formularios';
+
+export const Ejemplo = () => (
+  <CodeplexCampoNumero
+    etiqueta="Cantidad"
+    minimo={1}
+    maximo={100}
+    paso={1}
+    valor={5}
+    alCambiar={(val) => console.log(val)}
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `etiqueta` | `string` | — | Texto descriptivo del campo. |
+| `valor` | `number` | — | Valor controlado. |
+| `alCambiar` | `(val: number) => void` | — | Callback al cambiar. |
+| `minimo` | `number` | — | Valor mínimo permitido. |
+| `maximo` | `number` | — | Valor máximo permitido. |
+| `paso` | `number` | `1` | Incremento por clic en los controles. |
+| `mostrarControles` | `boolean` | `true` | Muestra botones +/−. |
+| `alineacion` | `'izquierda' \| 'centro' \| 'derecha'` | `'centro'` | Alineación del texto. |
+| `deshabilitado` | `boolean` | `false` | Deshabilita el campo. |
+| `anchoCompleto` | `boolean` | `false` | Ocupa el 100% del contenedor. |
+
+---
+
+### CodeplexSelector
+
+Dropdown con búsqueda, selección múltiple y opción de crear nuevo elemento.
+
+**Ejemplo:**
+```tsx
+import { CodeplexSelector } from '@codeplex-sac/formularios';
+
+const roles = [
+  { valor: 'admin', etiqueta: 'Administrador' },
+  { valor: 'usuario', etiqueta: 'Usuario' },
+];
+
+export const Ejemplo = () => (
+  <CodeplexSelector
+    etiqueta="Rol"
+    opciones={roles}
+    buscable
+    alCambiar={(val) => console.log(val)}
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `etiqueta` | `string` | — | Label del selector. |
+| `opciones` | `{ valor, etiqueta, deshabilitado? }[]` | `[]` | Lista de opciones. |
+| `valor` | `string \| number` | — | Valor seleccionado. |
+| `alCambiar` | `SelectChangeEvent handler` | — | Evento de selección. |
+| `buscable` | `boolean` | `false` | Activa filtro de búsqueda. |
+| `marcador` | `string` | — | Placeholder del buscador. |
+| `textoAyuda` | `ReactNode` | — | Texto informativo bajo el selector. |
+| `mensajeError` | `string` | — | Texto de error. |
+| `alCrearNuevo` | `() => void` | — | Muestra botón "Crear nuevo" al final. |
+| `textoCrearNuevo` | `string` | `'Crear nuevo'` | Texto del botón de creación. |
+| `anchoCompleto` | `boolean` | `false` | Ocupa el 100% del contenedor. |
+
+---
+
+### CodeplexAutocompletado
+
+Selector con búsqueda en tiempo real y soporte para opciones asíncronas.
+
+**Ejemplo:**
+```tsx
+import { CodeplexAutocompletado } from '@codeplex-sac/formularios';
+
+const paises = [
+  { etiqueta: 'Perú', valor: 'PE' },
+  { etiqueta: 'Chile', valor: 'CL' },
+];
+
+export const Ejemplo = () => (
+  <CodeplexAutocompletado
+    etiqueta="País"
+    opciones={paises}
+    alCambiar={(val) => console.log(val)}
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `opciones` | `any[]` | `[]` | Opciones disponibles. |
+| `etiqueta` | `string` | — | Label del campo. |
+| `valor` | `any` | — | Valor seleccionado. |
+| `alCambiar` | `(valor: any) => void` | — | Evento al seleccionar. |
+| `buscable` | `boolean` | `true` | Activa filtrado de opciones. |
+| `multiple` | `boolean` | `false` | Permite selección múltiple. |
+| `deshabilitado` | `boolean` | `false` | Deshabilita el campo. |
+| `anchoCompleto` | `boolean` | `false` | Ocupa el 100% del contenedor. |
+
+---
+
+### CodeplexCasilla
+
+Checkbox personalizado con estados indeterminado y múltiples variantes visuales.
+
+**Ejemplo:**
+```tsx
+import { CodeplexCasilla } from '@codeplex-sac/formularios';
+
+export const Ejemplo = () => (
+  <CodeplexCasilla
+    etiqueta="Acepto los términos y condiciones"
+    seleccionado={false}
+    alCambiar={(_, val) => console.log(val)}
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `etiqueta` | `ReactNode` | — | Texto lateral del checkbox. |
+| `seleccionado` | `boolean` | — | Estado marcado. |
+| `indeterminado` | `boolean` | `false` | Estado parcial (listas padre/hijo). |
+| `tamano` | `'pequeno' \| 'mediano' \| 'grande'` | `'mediano'` | Tamaño visual. |
+| `color` | `'primario' \| 'secundario' \| 'exito' \| 'error' \| 'info' \| 'advertencia'` | `'primario'` | Color al estar marcado. |
+| `variante` | `'estandar' \| 'suave' \| 'borde'` | `'estandar'` | Estilo visual del cuadro. |
+| `posicionEtiqueta` | `'derecha' \| 'izquierda' \| 'arriba' \| 'abajo'` | `'derecha'` | Posición del texto. |
+| `deshabilitado` | `boolean` | `false` | Deshabilita la interacción. |
+| `error` | `boolean` | `false` | Muestra estado de error. |
+| `alCambiar` | `(e, seleccionado: boolean) => void` | — | Callback al cambiar. |
+
+---
+
+### CodeplexGrupoRadio
+
+Conjunto de opciones mutuamente excluyentes con diseño personalizado.
+
+**Ejemplo:**
+```tsx
+import { CodeplexGrupoRadio } from '@codeplex-sac/formularios';
+
+const opciones = [
+  { valor: 'mensual', etiqueta: 'Mensual' },
+  { valor: 'anual', etiqueta: 'Anual' },
+];
+
+export const Ejemplo = () => (
+  <CodeplexGrupoRadio
+    etiqueta="Facturación"
+    opciones={opciones}
+    valor="mensual"
+    alCambiar={(val) => console.log(val)}
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `etiqueta` | `string` | — | Título del grupo. |
+| `opciones` | `{ valor, etiqueta, deshabilitado? }[]` | `[]` | Lista de radios. |
+| `valor` | `any` | — | Valor seleccionado. |
+| `alCambiar` | `(valor: any) => void` | — | Callback al cambiar. |
+| `orientacion` | `'horizontal' \| 'vertical'` | `'vertical'` | Disposición de los radios. |
+| `color` | `'primario' \| 'secundario' \| 'error' \| 'exito' \| 'advertencia' \| 'info'` | `'primario'` | Color del radio activo. |
+| `deshabilitado` | `boolean` | `false` | Deshabilita todo el grupo. |
+
+---
+
+### CodeplexInterruptor
+
+Control de encendido/apagado (Switch) con soporte de etiquetas y colores semánticos.
+
+**Ejemplo:**
+```tsx
+import { CodeplexInterruptor } from '@codeplex-sac/formularios';
+
+export const Ejemplo = () => (
+  <CodeplexInterruptor
+    etiqueta="Notificaciones activas"
+    seleccionado={true}
+    color="exito"
+    alCambiar={(_, val) => console.log(val)}
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `etiqueta` | `ReactNode` | — | Texto o elemento lateral. |
+| `seleccionado` | `boolean` | — | Estado activo/inactivo. |
+| `tamano` | `'pequeno' \| 'mediano'` | `'mediano'` | Tamaño visual. |
+| `color` | `'primario' \| 'secundario' \| 'exito' \| 'error' \| 'advertencia' \| 'info'` | `'primario'` | Color al estar activo. |
+| `posicionEtiqueta` | `'inicio' \| 'fin' \| 'arriba' \| 'abajo'` | `'fin'` | Posición de la etiqueta. |
+| `alCambiar` | `(e, checked: boolean) => void` | — | Callback al cambiar estado. |
+| `deshabilitado` | `boolean` | `false` | Deshabilita el interruptor. |
+| `error` | `boolean` | `false` | Muestra estado de error. |
+| `mensajeError` | `string` | — | Texto de error bajo el control. |
+
+---
+
+### CodeplexDeslizador
+
+Selector de valor o rango numérico con etiqueta de valor flotante.
+
+**Ejemplo:**
+```tsx
+import { CodeplexDeslizador } from '@codeplex-sac/formularios';
+
+export const Ejemplo = () => (
+  <CodeplexDeslizador
+    etiqueta="Porcentaje de descuento"
+    minimo={0}
+    maximo={100}
+    paso={5}
+    valor={25}
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `etiqueta` | `string` | — | Título descriptivo del control. |
+| `valor` | `number \| number[]` | — | Valor actual. |
+| `alCambiar` | `(val: number \| number[]) => void` | — | Callback al mover el control. |
+| `minimo` | `number` | `0` | Límite inferior del rango. |
+| `maximo` | `number` | `100` | Límite superior del rango. |
+| `paso` | `number` | `1` | Incremento mínimo. |
+| `mostrarEtiquetaValor` | `'auto' \| 'siempre' \| 'nunca'` | `'auto'` | Control del globo de valor. |
+| `orientacion` | `'horizontal' \| 'vertical'` | `'horizontal'` | Dirección del slider. |
+| `deshabilitado` | `boolean` | `false` | Deshabilita la interacción. |
+
+---
+
+### CodeplexListaTransferencia
+
+Dos columnas que permiten mover elementos entre listas con búsqueda integrada.
+
+**Ejemplo:**
+```tsx
+import { CodeplexListaTransferencia } from '@codeplex-sac/formularios';
+
+const empleados = [
+  { id: 1, texto: 'Ana García' },
+  { id: 2, texto: 'Carlos López' },
+];
+
+export const Ejemplo = () => (
+  <CodeplexListaTransferencia
+    izquierda={empleados}
+    tituloIzquierda="Disponibles"
+    tituloDerecha="Asignados al proyecto"
+    buscable
+    alCambiar={(izq, der) => console.log(izq, der)}
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `izquierda` | `any[]` | `[]` | Elementos de la columna origen. |
+| `derecha` | `any[]` | `[]` | Elementos de la columna destino. |
+| `tituloIzquierda` | `string` | `'Izquierda'` | Cabecera de la lista origen. |
+| `tituloDerecha` | `string` | `'Derecha'` | Cabecera de la lista destino. |
+| `buscable` | `boolean` | `false` | Muestra filtro de búsqueda en ambas listas. |
+| `alCambiar` | `(izq: any[], der: any[]) => void` | — | Se ejecuta al mover elementos. |
+
+---
+
+### CodeplexAreaTextoAjustable
+
+Textarea que crece automáticamente con el contenido.
+
+**Ejemplo:**
+```tsx
+import { CodeplexAreaTextoAjustable } from '@codeplex-sac/formularios';
+
+export const Ejemplo = () => (
+  <CodeplexAreaTextoAjustable
+    etiqueta="Descripción"
+    filasMinimas={3}
+    filasMaximas={8}
+    anchoCompleto
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `etiqueta` | `string` | — | Label del campo. |
+| `valor` | `string` | — | Valor controlado. |
+| `alCambiar` | `ChangeEventHandler` | — | Evento al cambiar. |
+| `filasMinimas` | `number` | `3` | Altura mínima en filas. |
+| `filasMaximas` | `number` | — | Altura máxima antes de hacer scroll. |
+| `marcador` | `string` | — | Texto placeholder. |
+| `deshabilitado` | `boolean` | `false` | Deshabilita la edición. |
+| `anchoCompleto` | `boolean` | `false` | Ocupa el 100% del contenedor. |
+
+---
+
+### CodeplexCargadorArchivos
+
+Zona de carga de archivos con drag & drop, validación de tipo y tamaño, y lista de archivos cargados.
+
+**Ejemplo:**
+```tsx
+import { CodeplexCargadorArchivos } from '@codeplex-sac/formularios';
+
+export const Ejemplo = () => (
+  <CodeplexCargadorArchivos
+    tiposAceptados={['image/*', '.pdf']}
+    tamanoMaximoMb={5}
+    multiple
+    alCargar={(archivos) => console.log(archivos)}
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `tiposAceptados` | `string[]` | — | MIME types o extensiones permitidas. |
+| `tamanoMaximoMb` | `number` | — | Tamaño máximo por archivo en MB. |
+| `multiple` | `boolean` | `false` | Permite cargar múltiples archivos. |
+| `variante` | `'zona' \| 'compacto' \| 'boton'` | `'zona'` | Presentación del componente. |
+| `alCargar` | `(archivos: File[]) => void` | — | Callback con los archivos validados. |
+| `deshabilitado` | `boolean` | `false` | Deshabilita la zona de carga. |
+
+---
+
+### CodeplexSelectorColor
+
+Selector de color con paleta de swatches, input hex y selector nativo del navegador.
+
+**Ejemplo:**
+```tsx
+import { CodeplexSelectorColor } from '@codeplex-sac/formularios';
+
+export const Ejemplo = () => (
+  <CodeplexSelectorColor
+    valor="#3B82F6"
+    alCambiar={(color) => console.log(color)}
+  />
+);
+```
+
+**Props:**
+| Propiedad | Tipo | Por defecto | Descripción |
+| :--- | :--- | :--- | :--- |
+| `valor` | `string` | `'#000000'` | Color en formato hex. |
+| `alCambiar` | `(color: string) => void` | — | Callback con el nuevo color. |
+| `paleta` | `string[]` | — | Swatches predefinidos. |
+| `variante` | `'emergente' \| 'fija'` | `'emergente'` | Muestra el panel inline o en popup. |
+| `deshabilitado` | `boolean` | `false` | Deshabilita la selección. |
+
+---
+
+## Personalización
+
+Todos los componentes heredan la configuración de `CodeplexProveedorTema`. Los colores, radios y sombras se toman del tema activo.
+
+## Licencia
+
+Propiedad privada de **Codeplex SAC**. Todos los derechos reservados.