@tinya-code/gas-admin-ui 0.2.0-alpha.12 → 0.2.0-alpha.13

package/README.md

@@ -310,6 +310,228 @@ The shell starts at `/login` and, once authenticated, shows the sidebar menu and
 
 ---
 
+## Todos los tipos de campo del formulario
+
+Esta es la referencia completa de todos los tipos de campo que puedes declarar en `ResourceSchema.fields`. Cada tipo tiene su propio comportamiento de renderizado, validación y propiedades específicas.
+
+| Tipo | Descripción | Uso típico |
+|------|-------------|------------|
+| `text` | Input de una línea para texto corto | Nombres, slugs, URLs cortas |
+| `textarea` | Área de texto multilínea | Descripciones largas, notas |
+| `slug` | Slug generado automáticamente de otro campo | Identificadores amigables para SEO |
+| `number` | Campo numérico con controles de incremento | Cantidades, precios, edades |
+| `currency` | Campo monetario con formato de moneda | Precios, montos, saldos |
+| `boolean` | Interruptor (toggle) o casilla de verificación | Estados activos/inactivos |
+| `select` | Desplegable con radios para 2-4 opciones o dropdown para más | Estados, categorías pequeñas |
+| `dropdown` | Desplegable nativo (`<select>`) SIEMPRE, sin mutar a radios | Estados con muchas opciones |
+| `rich-select` | Selector visual con tarjetas y preview HTML personalizado | Opciones con iconos, colores, estados visuales |
+| `multiselect` | Selección múltiple de opciones | Tags, etiquetas múltiples |
+| `url` | Campo para URLs válidas | Enlaces externos, sitios web |
+| `email` | Campo de email con validación de formato | Correos electrónicos |
+| `phone` | Campo de teléfono con formato telefónico | Números de teléfono |
+| `date` | Selector de fecha (ISO `YYYY-MM-DD`) | Fechas de nacimiento, citas |
+| `time` | Selector de hora | Horas de apertura, citas |
+| `readonly-text` | Texto de solo lectura que no se envía al back | IDs generados, timestamps |
+| `relation` | Relación con otro recurso (fuente de datos) | Clientes, productos, usuarios relacionados |
+| `image` | Subida y vista previa de imágenes | Logos, fotos de perfil |
+| `file` | Subida de archivos genéricos (PDF, DOCX, etc.) | Documentos, adjuntos |
+| `group` | Grupo de campos con tarjeta, colapsable o inline | Secciones de formulario relacionadas |
+| `list` | Lista repetible de campos (items) | Múltiples direcciones, teléfonos |
+| `string-list` | Lista simple de strings | Tags simples, palabras clave |
+| `key-value` | Tabla de pares clave-valor | Metadatos, configuraciones personalizadas |
+| `color` | Selector de color nativo (`<input type="color">`) | Colores primarios, secundarios, temas |
+
+### Ejemplos por tipo
+
+A continuación verás cómo declarar cada tipo en tu schema, con sus propiedades específicas:
+
+#### `text` — Input de una línea
+
+```ts
+{ key: 'name', type: 'text', label: 'Nombre del Negocio', required: true, validators: { minLength: 2, maxLength: 120 }, section: 'general', width: 6 }
+```
+
+#### `textarea` — Área de texto multilínea
+
+```ts
+{ key: 'description', type: 'textarea', label: 'Descripción', validators: { maxLength: 500 }, section: 'general', width: 12 }
+```
+
+#### `slug` — Identificador amigable
+
+```ts
+{ key: 'slug', type: 'slug', from: 'name', label: 'Slug', required: true, lockAfterCreate: true, section: 'general', width: 6 }
+```
+
+#### `number` — Campo numérico
+
+```ts
+{ key: 'minVisits', type: 'number', label: 'Visitas Mínimas', required: true, min: 0, section: 'general', width: 6 }
+```
+
+#### `currency` — Campo monetario
+
+```ts
+{ key: 'price', type: 'currency', label: 'Precio', validators: { min: 0 }, section: 'pricing', width: 6 }
+```
+
+#### `boolean` — Interruptor / Casilla
+
+```ts
+{ key: 'active', type: 'boolean', label: 'Activo', section: 'general', width: 3 }
+```
+
+#### `select` — Desplegable (radios si 2-4 opciones, dropdown si más)
+
+```ts
+{ key: 'status', type: 'select', label: 'Estado', required: true, options: [
+  { value: 'active', label: 'Activo' },
+  { value: 'inactive', label: 'Inactivo' },
+  { value: 'pending', label: 'Pendiente' },
+], section: 'general', width: 6 }
+```
+
+#### `dropdown` — Desplegable nativo SIEMPRE
+
+```ts
+{ key: 'timezone', type: 'dropdown', label: 'Zona Horaria', required: true, section: 'general', width: 6, default: 'America/Lima', options: [
+  { value: 'America/Lima', label: 'Lima (Perú)' },
+  { value: 'America/Bogota', label: 'Bogotá (Colombia)' },
+  { value: 'America/Mexico_City', label: 'Ciudad de México' },
+], }
+```
+
+#### `rich-select` — Selector visual con tarjetas
+
+```ts
+{ key: 'cardStyle', type: 'rich-select', label: 'Estilo de Tarjeta', cardWidth: 3, section: 'branding', width: 12,
+  options: [
+    { value: 'none', label: 'Ninguno', preview: '<span class="w-8 h-8 bg-amber-300 rounded-sm flex items-center justify-center text-xs font-medium text-amber-900">Ninguna</span>' },
+    { value: 'monthly', label: 'Mensual', preview: '<span class="w-8 h-8 bg-blue-100 rounded-sm flex items-center justify-center text-xs font-medium text-blue-900">Mensual</span>' },
+    { value: 'yearly', label: 'Anual', preview: '<span class="w-8 h-8 bg-green-100 rounded-sm flex items-center justify-center text-xs font-medium text-green-900">Anual</span>' },
+  ], }
+```
+
+#### `multiselect` — Selección múltiple
+
+```ts
+{ key: 'tags', type: 'multiselect', label: 'Etiquetas', section: 'tags', width: 12, options: [
+  { value: 'vip', label: 'Cliente VIP' },
+  { value: 'new', label: 'Cliente Nuevo' },
+  { value: 'inactive', label: 'Inactivo' },
+], }
+```
+
+#### `url` — Campo de URL
+
+```ts
+{ key: 'website', type: 'url', label: 'Sitio Web', placeholder: 'https://ejemplo.com', section: 'contact', width: 12 }
+```
+
+#### `email` — Campo de correo electrónico
+
+```ts
+{ key: 'email', type: 'email', label: 'Correo Electrónico', required: true, section: 'contact', width: 12 }
+```
+
+#### `phone` — Campo de teléfono
+
+```ts
+{ key: 'phone', type: 'phone', label: 'Teléfono', section: 'contact', width: 6 }
+```
+
+#### `date` — Selector de fecha
+
+```ts
+{ key: 'birthDate', type: 'date', label: 'Fecha de Nacimiento', section: 'personal', width: 6 }
+```
+
+#### `time` — Selector de hora
+
+```ts
+{ key: 'openingTime', type: 'time', label: 'Hora de Apertura', section: 'hours', width: 6 }
+```
+
+#### `readonly-text` — Texto de solo lectura
+
+```ts
+{ key: 'memberId', type: 'readonly-text', label: 'ID Membresía', readonly: true, section: 'general', width: 6 }
+```
+
+#### `relation` — Relación con otro recurso
+
+```ts
+{ key: 'clientId', type: 'relation', label: 'Cliente', source: { resource: 'clients', labelField: 'name', valueField: 'membershipId' }, section: 'association', width: 12 }
+```
+
+#### `image` — Subida de imagen
+
+```ts
+{ key: 'logoUrl', type: 'image', label: 'Logo', section: 'branding', width: 12, accept: 'image/*', maxSizeMB: 2 }
+```
+
+#### `file` — Subida de archivo genérico
+
+```ts
+{ key: 'document', type: 'file', label: 'Documento', section: 'files', width: 12, accept: '.pdf,.doc,.docx', maxSizeMB: 5 }
+```
+
+#### `group` — Grupo de campos
+
+```ts
+{ key: 'address', type: 'group', label: 'Dirección', display: 'card', section: 'location', width: 12, fields: [
+  { key: 'street', type: 'text', label: 'Calle', width: 6 },
+  { key: 'city', type: 'text', label: 'Ciudad', width: 6 },
+]},
+```
+
+#### `list` — Lista repetible de items
+
+```ts
+{ key: 'phones', type: 'list', label: 'Teléfonos', itemFields: [
+  { key: 'number', type: 'phone', label: 'Número', width: 6 },
+  { key: 'type', type: 'select', label: 'Tipo', options: [{ value: 'mobile', label: 'Móvil' }, { value: 'home', label: 'Hogar' }], width: 6 },
+], section: 'contact', width: 12 }
+```
+
+#### `string-list` — Lista simple de strings
+
+```ts
+{ key: 'skills', type: 'string-list', label: 'Habilidades', itemType: 'text', section: 'skills', width: 12 }
+```
+
+#### `key-value` — Pares clave-valor
+
+```ts
+{ key: 'metadata', type: 'key-value', label: 'Metadatos', section: 'advanced', width: 12 }
+```
+
+#### `color` — Selector de color
+
+```ts
+{ key: 'colorPrimary', type: 'color', label: 'Color Primario', placeholder: '#4A2C11', section: 'branding', width: 6, default: '#4A2C11' }
+```
+
+### Propiedades comunes a todos los campos
+
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| `key` | `string` | Nombre de la propiedad en el JSON que envía/recibe el back. |
+| `label` | `string` | Rótulo visible para el usuario en el formulario y la ficha. |
+| `help` | `string` | Texto corto de ayuda que se muestra debajo del campo. |
+| `placeholder` | `string` | Texto sugerente que se muestra dentro del input cuando está vacío. |
+| `required` | `boolean` | Si es obligatorio. El back también lo valida (R7.4). |
+| `default` | `any` | Valor por defecto si el registro no trae este campo (ej. `default: 'none'` en un `select`/`dropdown`). |
+| `readonly` | `boolean` | Si el campo es solo lectura (no editable en el formulario). |
+| `width` | `1-12` | Ancho en la grilla del formulario (1–12), igual que un widget del dashboard. |
+| `section` | `string` | Id de la sección/pestaña del layout a la que pertenece (base.md §4). |
+| `description` | `string` | Descripción corta de para qué sirve este campo. Se muestra como tooltip al pasar el cursor sobre el rótulo. |
+| `docLink` | `string` | URL de documentación externa para este campo (se abre al hacer clic en el tooltip). |
+| `validators` | `object` | Reglas de validación (`minLength`, `maxLength`, `pattern`, `min`, `max`, `unique`). |
+| `access` | `object` | Nivel de acceso requerido (`read`, `write`) — solo UX, el back vuelve a verificar en cada petición. |
+
+---
+
 ## Schema examples (real implementations)
 
 The examples below are taken from a production consumer of this library.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinya-code/gas-admin-ui",
-  "version": "0.2.0-alpha.12",
+  "version": "0.2.0-alpha.13",
   "description": "Motor de render Angular para admin CRUD: declará ResourceSchema y el motor dibuja vistas, campos y widgets.",
   "repository": {
     "type": "git",