@tinya-code/gas-admin-ui 0.2.0-alpha.11 → 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/fesm2022/tinya-code-gas-admin-ui.mjs

@@ -4504,6 +4504,96 @@ i0.ɵɵngDeclareClassMetadata({
 		}]
 	}
 });
-export { API_DRIVER, API_URL, ApiError, ApiService, AuthService, COLUMN_FORMAT_TYPES, ComposerHost, ConfirmDialog, DEFAULT_RESPONSE_UNWRAP, Dashboard, DataSourceService, ErrorMapperService, FIREBASE_AUTH_ADAPTER, FieldHost, FormView, GAS_SCHEMAS, ListView, Login, MAX_DEPTH, NotificationService, ResourcePage, SESSION_TOKEN_KEY, SESSION_USER_KEY, SUPPORTED_FIELD_TYPE_LIST, SchemaCompositionError, Sidebar, Toast, UploadService, VALUE_SOURCES, actionType, actionTypes, actionsFor, allSchemas, apiErrorInterceptor, authGuard, buildFormSchema, buildPayload, childTree, columnFormatDescriptors, fieldDescriptors, getAction, getAuth, get as getRenderDescriptor, getSchema, groupTree, interpolateTemplate, isSupported as isRenderSupported, isSupported, isShareAction, isTriggerAction, itemTree, layoutDescriptors, listTree, resource_page_exports as n, provideFirebaseAdapter, provideGasAdmin, provideRenderDescriptors, registerAction, register as registerRenderDescriptor, renderKinds, renewedTokenOf, resolveShare, resourceRoutes, seedModel, setSchemaCatalog, shellRoutes, stringItemTree, composer_host_exports as t, unregister as unregisterRenderDescriptor, validateComposition, viewDescriptors };
+const schemaDescriptions = {
+	key: "Nombre de la propiedad en el JSON que envía/recibe el back.",
+	label: "Rótulo visible para el usuario en el formulario y la ficha.",
+	help: "Texto corto de ayuda que se muestra debajo del campo.",
+	placeholder: "Texto sugerente que se muestra dentro del input cuando está vacío.",
+	required: "Si es obligatorio. El back también lo valida (R7.4).",
+	default: "Valor por defecto si el registro no trae este campo (ej. `default: \"none\"` en un `select`/`dropdown`).",
+	readonly: "Si el campo es solo lectura (no editable en el formulario).",
+	readonlyOn: "Bloquea el campo solo en creación, solo en edición o siempre.",
+	readonlyWhen: "Condición bajo la cual el campo es solo lectura (expresión sobre otros campos).",
+	visibleWhen: "Condición bajo la cual el campo se muestra u oculta.",
+	hiddenOn: "Oculta el campo en creación, en edición o siempre.",
+	dependsOn: "Selección dependiente (guía §1: país → ciudad). Clave del campo padre del mismo nivel.",
+	validators: "Reglas de validación (mínimo, máximo, patrón, unicidad, etc.).",
+	width: "Ancho en la grilla del formulario (1–12), igual que un widget del dashboard.",
+	section: "Id de la sección/pestaña del layout a la que pertenece (base.md §4).",
+	read: "Código de nivel de acceso requerido para leer el campo.",
+	write: "Código de nivel de acceso requerido para escribir el campo.",
+	description: "Descripción corta de para qué sirve este campo. Se muestra como tooltip al pasar el cursor sobre el rótulo.",
+	docLink: "URL de documentación externa para este campo (se abre al hacer clic en el tooltip).",
+	value: "Valor que se envía al back cuando se elige esta opción.",
+	labelOption: "Texto visible de la opción.",
+	disabled: "Si la opción está deshabilitada (no se puede elegir).",
+	type: "Tipo de campo: `text`, `color`, `number`, `currency`, `boolean`, `select`, `dropdown`, `rich-select`, `multiselect`, `url`, `email`, `phone`, `date`, `time`, `readonly-text`, `slug`, `textarea`, `relation`, `image`, `file`, `group`, `list`, `string-list`, `key-value`.",
+	maxLength: "Longitud máxima de caracteres permitida.",
+	pattern: "Expresión regular que debe cumplir el valor.",
+	rows: "Número de filas visibles del textarea.",
+	minWords: "Cantidad mínima de palabras.",
+	maxWords: "Cantidad máxima de palabras.",
+	tokens: "Marcadores insertables como chips bajo el área (plantillas de mensaje).",
+	from: "Campo del registro del que se autogenera el slug.",
+	lockAfterCreate: "Bloquea el campo una vez creado el registro (por defecto: sí).",
+	min: "Valor mínimo permitido.",
+	max: "Valor máximo permitido.",
+	step: "Incremento entre valores permitidos.",
+	decimals: "Número de decimales mostrados.",
+	currencyFrom: "Campo del registro del que se toma la moneda (ej. `currency`).",
+	trueLabel: "Texto que se muestra cuando el valor es verdadero.",
+	falseLabel: "Texto que se muestra cuando el valor es falso.",
+	source: "De dónde salen las opciones: `{ resource, view?, params?, … }` (F8 · R6.5).",
+	resource: "Recurso declarado (`resource.id`): su listado es el de las opciones.",
+	view: "Vista declarada en `resource.views` (opcional): filtra en el back.",
+	params: "Valores interpolados para la vista (`{campo}` ← contexto).",
+	labelField: "Etiqueta por defecto de las filas (si no, `titleField` del recurso).",
+	valueField: "Valor por defecto de las filas (si no, `keyField` del recurso).",
+	secondaryField: "Segundo dato a mostrar junto a la etiqueta (ej. \"Juan Pérez · DNI 123\").",
+	onlyActive: "Cargar solo registros activos (lo exige además la FK en el back).",
+	accept: "Tipos aceptados (ej. `image/*`, `image/png,image/jpeg` o `pdf,docx`).",
+	maxSizeMB: "Tamaño máximo del archivo en megabytes.",
+	aspectRatio: "Relación de aspecto de la vista previa (ej. `16/9`).",
+	previewSize: "Tamaño de la vista previa.",
+	formatCurrency: "Campo del registro del que se toma la moneda (ej. `currency`).",
+	display: "Presentación del grupo: `card`, `collapsible` o `inline`.",
+	fields: "Campos de cada item (cualquier tipo, incluso `group` o `list`).",
+	minItems: "Cantidad mínima de items.",
+	maxItems: "Cantidad máxima de items.",
+	sortable: "Si se puede reordenar (por defecto: sí).",
+	positionField: "Campo donde se guarda el orden dentro de cada item (`position`).",
+	addLabel: "Etiqueta del botón para agregar un item nuevo.",
+	emptyText: "Texto que se muestra cuando no hay items.",
+	itemDisplay: "Cómo se muestra cada item: `card`, `row` o `accordion`.",
+	itemFields: "Campos de cada item (cualquier tipo, incluso `group` o `list`).",
+	itemTitle: "Campo del item usado como título cuando está colapsado.",
+	primaryFirst: "El primer item tiene significado especial (ej. imagen principal).",
+	itemType: "Tipo permitido de cada item (base.md §9: solo `text`, `url` o `email`).",
+	sort: "Si la lista se ordena alfabéticamente o por posición.",
+	filter: "Si el listado permite filtrado por texto.",
+	search: "Campos buscables en el listado.",
+	filters: "Filtros declarados para el listado.",
+	listColumns: "Columnas que se muestran en el listado.",
+	searchable: "Si el campo es buscable.",
+	filterable: "Si el campo es filtrable.",
+	sortableItems: "Si los items de la lista se pueden reordenar.",
+	groupBy: "Campo por el que agrupar los items.",
+	cardWidth: "Ancho de cada tarjeta de opción en la grilla (1–12). Por defecto `4` (3 tarjetas por fila en escritorio).",
+	cardCols: "Cuántas tarjetas mostrar por fila en el punto de ruptura `lg`. Sobrescribe el cálculo automático basado en `cardWidth`.",
+	hintMetric: "Texto secundario bajo la cifra (estático, va en el schema).",
+	unitChart: "Sufijo de las cifras del eje («unidades», «S/»).",
+	segments: "Segmentos de la barra de distribución porcentual.",
+	actions: "Acciones de navegación por fila.",
+	labelAction: "Etiqueta de la acción.",
+	icon: "Icono de la acción.",
+	navigateTo: "Ruta de destino de la acción.",
+	variant: "Variante visual: `primary`, `secondary` u `outline`.",
+	widgets: "Widgets del panel. Se declara en `ResourceSchema.widgets` — no en `fields`, porque un KPI no es un campo.",
+	mobileWidth: "Ancho en la grilla en mobile (1–12). Por defecto `12` (ancho completo, apilado).",
+	sourceWidget: "De dónde saca sus datos: `DataSource` o `{ kind: \"payload\" }`.",
+	hintWidget: "Texto secundario bajo la cifra (estático, va en el schema).",
+	unitWidget: "Sufijo de las cifras del eje."
+};
+export { API_DRIVER, API_URL, ApiError, ApiService, AuthService, COLUMN_FORMAT_TYPES, ComposerHost, ConfirmDialog, DEFAULT_RESPONSE_UNWRAP, Dashboard, DataSourceService, ErrorMapperService, FIREBASE_AUTH_ADAPTER, FieldHost, FormView, GAS_SCHEMAS, ListView, Login, MAX_DEPTH, NotificationService, ResourcePage, SESSION_TOKEN_KEY, SESSION_USER_KEY, SUPPORTED_FIELD_TYPE_LIST, SchemaCompositionError, Sidebar, Toast, UploadService, VALUE_SOURCES, actionType, actionTypes, actionsFor, allSchemas, apiErrorInterceptor, authGuard, buildFormSchema, buildPayload, childTree, columnFormatDescriptors, fieldDescriptors, getAction, getAuth, get as getRenderDescriptor, getSchema, groupTree, interpolateTemplate, isSupported as isRenderSupported, isSupported, isShareAction, isTriggerAction, itemTree, layoutDescriptors, listTree, resource_page_exports as n, provideFirebaseAdapter, provideGasAdmin, provideRenderDescriptors, registerAction, register as registerRenderDescriptor, renderKinds, renewedTokenOf, resolveShare, resourceRoutes, schemaDescriptions, seedModel, setSchemaCatalog, shellRoutes, stringItemTree, composer_host_exports as t, unregister as unregisterRenderDescriptor, validateComposition, viewDescriptors };
 
 //# sourceMappingURL=tinya-code-gas-admin-ui.mjs.map