Fuente revisada: projects/nebula-ui-kit/src/public-api.ts y projects/nebula-ui-kit/src/lib/
Fecha de corte: 12 de octubre de 2026
Propósito: catálogo transferible para la wiki del kit. Los componentes son standalone; se importan en el componente Angular consumidor o se usan a través de NebulaLayoutHelper cuando pertenecen al motor de formularios.
Instala/importa la librería en la aplicación como cualquier paquete Angular y añade los componentes standalone utilizados al imports del componente que los consume. Los ejemplos siguientes muestran los selectores disponibles; los nombres de inputs y outputs específicos se consultan en los tipos exportados y en la historia indicada para cada grupo.
import { Component } from '@angular/core';
import { ButtonComponent, InputComponent } from 'nebula-ui-kit';
@Component({
standalone: true,
imports: [ButtonComponent, InputComponent],
template: `
<lib-input label="Nombre" placeholder="Escribe un nombre" />
<lib-button variant="primary" (clicked)="guardar()">Guardar</lib-button>
`,
})
export class EjemploComponent {
guardar(): void { /* acción de la aplicación */ }
}
Los nombres de importación del ejemplo son clases exportadas por public-api.ts. Si la aplicación configura traducción, iconos o estilos globales del kit, debe registrar también los proveedores/configuración correspondientes (NEBULA_TRANSLATE, provideNebulaCoreIcons, provideNebulaUIConfig) y los estilos del proyecto.
| Componente | Selector | Uso |
|---|---|---|
| Header | <lib-header> |
Barra superior de la aplicación. Acepta contenido en ranuras como [logo], [title], [toggle], [notifications], [profile] y [acciones]; la aplicación provee esos elementos. La ranura [acciones] va antes de la campana y sirve, por ejemplo, para montar la bandeja de tareas. |
| Sidebar | <lib-sidebar> |
Menú lateral de navegación. Recibe la estructura de menú y emite eventos de navegación/acción; MenuItem.accion permite una acción junto a una opción. |
| Breadcrumb | <lib-breadcrumb> |
Ruta jerárquica de navegación. Recibe sus elementos y comunica la selección según el modelo breadcrumb. |
| Tabs | <lib-tabs> con <lib-tab> |
Pestañas para alternar paneles. El contenido de pestaña se declara con [libTabContent]. En el perfil visual 3.0, añadir ui-3-0 a <html> para el estilo nuevo. |
| Footer | <lib-footer> |
Pie de página compartido; se configura con los datos/textos de la aplicación. |
| Search | <lib-search> |
Campo de búsqueda reutilizable. Puede mostrar limpieza, estado de carga, deshabilitación y demora (debounceMs); se conecta a la búsqueda de la pantalla con sus eventos. |
| Empty | <lib-empty> |
Estado sin resultados o sin contenido. Úsalo cuando la vista no tenga datos; configura mensaje/ilustración/acción según las entradas disponibles. |
| Layout de ejemplo | Sin componente público propio | La composición de dashboard se presenta en layout/layout-composition.stories.ts; arma el layout usando header, sidebar, cards y contenido, no es un componente adicional del API público. |
<lib-header>
<img logo src="assets/logo.svg" alt="Nebula" />
<span title>Administración</span>
<app-bandeja-tareas acciones />
<app-perfil profile />
</lib-header>
| Componente | Selector | Uso |
|---|---|---|
| Botón | <lib-button> |
Acción o envío de formulario. variant define jerarquía/estilo; admite estado loading, disabled, iconos y evento clicked. Para botones solo con icono, asigna ariaLabel. |
| Input | <lib-input> |
Campo de texto, contraseña, correo o número. Se enlaza a formularios Angular; admite etiqueta, placeholder, required, errores, iconos y prefijos/sufijos. |
| Textarea | <lib-textarea> |
Texto multilínea conectado a formularios Angular, con etiqueta, ayuda y validación. |
| Select | <lib-select> |
Selector de una opción de un conjunto; proporciona opciones y valor según el modelo del control. |
| Autocomplete | <lib-autocomplete> |
Búsqueda y selección con sugerencias. Configura carga/opciones, texto a mostrar y eventos de selección. |
| Code Field | <lib-code-field> |
Campo de código con descripción y búsqueda de catálogo; el modo (modo) puede controlar captura de código/descripción. Emite búsqueda y selección. |
| Datepicker | <lib-datepicker> |
Selección de fecha con límites y etiqueta/hint configurables. |
| Auto Datepicker | <lib-auto-datepicker> |
Fecha automática del sistema o captura manual. Emite dateChange; permite límites y personalizar las etiquetas/tooltips de cada modo. |
| Date Range Picker | <lib-date-range-picker> |
Selector visual de fecha inicial/final. Para un campo de formulario con atajos y valor integrado, usa lib-date-range-field. |
| Date Range Field | <lib-date-range-field> |
Rango en un solo campo, con periodos predefinidos y rango personalizado. Integra presets desde date-range-field.presets. |
| Period Field | <lib-period-field> |
Selección de periodo contable por vigencia/mes; el valor persistido es YYYYMM. En el motor se declara como l.periodo(...). |
| Checkbox | <lib-checkbox> |
Control booleano marcado/no marcado, enlazado a formulario. |
| Radio | <lib-radio> |
Selección única entre alternativas. |
| File Upload | <lib-file-upload> |
Selección/carga de archivo desde la interfaz; la aplicación maneja el procesamiento y el servicio destino. |
| Field Label | <lib-field-label> |
Etiqueta externa para controles de formulario reactivo, especialmente cuando se quiere evitar duplicar etiqueta/asterisco del propio control. |
| Form Card | <lib-form-card> |
Contenedor visual de campos o bloques de formulario. |
| Form Density | <lib-form-density> |
Proveedor/contenedor para configurar densidad visual de formularios; también expone servicio de densidad. |
| Grid Form | <lib-grid-form> |
Rejilla responsiva para ubicar controles mediante contenido proyectado. Admite preset, columnas, espacio y etiqueta accesible. |
| Grid Form Item | <lib-grid-form-item> |
Celda/elemento hijo de lib-grid-form, con span/posición configurables. |
| Key Value Grid | <lib-key-value-grid> |
Presenta pares clave/valor de solo lectura a partir de una colección KeyValueItem[]. |
lib-form-layout)Usa FormLayoutComponent cuando la pantalla quiere declarar estructura y campos como datos. La aplicación sigue siendo responsable del FormGroup, validadores, catálogos, reglas de negocio y acciones. El motor resuelve y pinta la distribución.
import { FormBuilder, ReactiveFormsModule } from '@angular/forms';
import { FormLayoutComponent, NebulaLayoutHelper } from 'nebula-ui-kit';
const l = new NebulaLayoutHelper();
layout = l.form('cliente', { template: 'minmax(0, 1fr) 272px' },
l.stack('principal',
l.section('identificacion', 'CLIENTE.IDENTIFICACION', { columns: 2 },
l.field('tipoDocumento', 'CLIENTE.TIPO_DOCUMENTO'),
l.field('numeroDocumento', 'CLIENTE.NUMERO_DOCUMENTO'),
l.full('direccion', { labelKey: 'CLIENTE.DIRECCION' }),
),
),
);
<lib-form-layout [layout]="layout" [form]="form" mode="create" />
El selector alternativo <form-dynamic> pinta el mismo motor. Entradas relevantes: layout (obligatoria), form, mode, loading, modoCarga y errorFn. El helper ofrece métodos para describir ramas, secciones, campos, pestañas, acordeones, lienzo y piezas (form, stack, tabs, accordion, section, field, entre otros). Consulta nebula-layout.helper.ts para la lista completa y firmas.
Otras piezas relacionadas:
<lib-pieza> representa una pieza de contenido del lienzo.<lib-lienzo-ficha> es la plantilla de ficha lista para pintar datos del lienzo.<lib-lienzo-tarea> presenta el detalle visual de una tarea en el lienzo del motor.[libFormField] asocia una plantilla de pantalla con el campo declarado por el layout.pendientesDelMotor(...) devuelve campos obligatorios pendientes; revelarPendientes() marca, navega y enfoca el primer pendiente.| Componente | Selector | Uso |
|---|---|---|
| Table | <lib-table> |
Tabla presentacional con configuración de columnas y datos. Inputs principales: config, data, loading; admite selección, orden, paginación, anchos y orden de columnas. Emite cambios de orden, página, selección, acciones y filas. groupHeader añade encabezados de grupo opcionales. |
| Smart Table | <lib-smart-table> |
Grilla declarativa para listados de servidor: recibe config, página data, totalElements y loading; emite queryChange con criterios de búsqueda/orden/paginación listos para que la pantalla consulte el backend. La tabla no hace la petición HTTP. |
| Smart Table Period | <lib-nst-periodo> |
Control interno usado por lib-smart-table para presentar el periodo declarado; normalmente no se monta de forma aislada. |
| Table Input | <lib-table-input> |
Grilla editable para captura tabular; recibe configuración/filas y emite cambios de fila, celda, orden, selección y acciones. readOnly desactiva la edición. |
| Table Compact | <lib-table-compact> |
Tabla compacta de formularios con configuración TableCompactConfig y datos; emite action, searchInput y changeData. Para personalizar celdas usa ng-template con libTableCompactCell="clave". |
| Table Cell Template | <ng-template libTableCompactCell="campo"> |
Plantilla de celda personalizada perteneciente a lib-table-compact; se declara dentro del componente de tabla. |
| Grid Card | <lib-gridcard> |
Colección de tarjetas de datos. Recibe items, loading y emite cardClick. |
| Card | <lib-card> |
Tarjeta individual, normalmente usada por lib-gridcard o en composición propia. |
| Score Card | <lib-scorecard> |
Tarjeta de indicador/valor resumido, usada dentro de gridcard o directamente si se importa su clase. |
| Table Header (interno) | [lib-table-header] |
Directiva/componente de cabecera empleado por lib-table; no suele montarse directamente. |
| Table Row (interno) | [lib-table-row] |
Fila interna de lib-table; preferir el API público lib-table. |
| Table Cell (interno) | <lib-table-cell> |
Celda interna de tabla; preferir configuración de columnas o plantilla de celda. |
| Table Help Dialog | <lib-table-help-dialog> |
Diálogo interno de ayuda de smart-table; se abre desde la propia grilla. |
columns = [
{ key: 'codigo', label: 'Código', sortable: true },
{ key: 'nombre', label: 'Nombre', sortable: true },
];
rows = [{ codigo: 'A-01', nombre: 'Ejemplo' }];
<lib-table [config]="{ columns }" [data]="rows" (rowClick)="abrir($event)" />
En smart-table, declarar columnas con NebulaColumnHelper/NebulaSmartTableConfig y responder a (queryChange) consultando el servicio de la aplicación. Los criterios IN y NOT_IN reciben valores como arreglos.
| Componente | Selector | Uso |
|---|---|---|
| Alert | <lib-alert> |
Mensaje contextual persistente con nivel/tono y contenido configurables. |
| Toast | <lib-toast> y <lib-toast-container> |
Notificación temporal. En aplicaciones, normalmente se usa NebulaToastService y se monta un contenedor global. |
| Loader | <lib-loader> |
Indicador de carga; puede reemplazarse por esqueleto en vistas que admiten ese modo. |
| Dialog Container | <lib-dialog-container> |
Contenedor de diálogo base. Normalmente se abre con DialogService y se compone con sus slots/directivas. |
| Confirm Dialog | <lib-confirm-dialog> |
Confirmación de una acción (aceptar/cancelar) mediante el servicio de diálogos. |
| Dialog Header/Body/Footer | [libDialogHeader], [libDialogBody], <lib-dialog-footer> o [libDialogFooter] |
Directivas de composición para las zonas de título, cuerpo y acciones de un diálogo. |
La API de apertura, configuración y resultado de diálogos está en DialogService y dialog.models.ts; evita crear contenedores manualmente si un diálogo específico ya ofrece el flujo requerido.
| Componente | Selector | Uso |
|---|---|---|
| Import Dialog | <lib-import-dialog> |
Flujo de selección de archivo, validación, revisión y resultado. La aplicación entrega el origen mediante NEBULA_IMPORT_SOURCE_FACTORY; el kit no realiza HTTP. |
| Export Dialog | <lib-export-dialog> |
Selección/generación y descarga de un archivo; origen por NEBULA_EXPORT_SOURCE_FACTORY. Puede recibir resultado inmediato o una tarea asíncrona (jobId). |
| Task Progress | <lib-task-progress> |
Progreso de una tarea; acepta datos genéricos y emite acciones según el modelo. Puede declararse con l.taskProgress(...) dentro del motor. |
| Execution Log | <lib-execution-log> |
Registro de líneas/estados de ejecución. Puede declararse con l.executionLog(...). |
| Background Tray | <lib-background-tray> |
Bandeja de tareas en segundo plano; se suele insertar en <lib-header> mediante la ranura [acciones]. |
| Task list (motor) | No tiene selector independiente de uso común | Se declara como panel del motor con l.taskList(...); se alimenta desde el estado que provee la pantalla y puede navegar a una tarea. |
Ejemplo de estructura en el motor:
l.section('tareas', 'TAREAS.TITULO', {},
l.taskList('lista', 'TAREAS.BUSCAR', { items: 'tareas', seleccion: 'tareaSeleccionada' }),
l.taskProgress('avance', 'TAREAS.AVANCE', { porcentaje: 'porcentaje', paso: 'paso' }),
l.executionLog('registro', 'TAREAS.REGISTRO', { lineas: 'lineas', enCurso: 'enCurso' }),
);
| Elemento | Selector | Uso |
|---|---|---|
| Badge | <lib-badge> |
Etiqueta corta de estado, categoría o contador. |
| Icon | <lib-icon> |
Icono de la biblioteca de iconos configurada; se usa como elemento visual con nombre/tamaño/estilo. |
| Skeleton | <lib-skeleton> |
Placeholder con forma de contenido mientras se carga. |
| Results Counter | <lib-results-counter> |
Texto/resumen del total de resultados en grillas/listados. |
No son componentes visuales autónomos, pero forman parte del uso habitual y están exportados desde public-api.ts:
[nebulaAccion]: compuerta/directiva para habilitar o condicionar acciones según configuración de permisos.[libDesplazamientoHorizontal]: utilidad para interacción de desplazamiento horizontal.[libTabContent]: marca el panel de contenido de una pestaña.[libFormField]: registra la plantilla de un campo del motor.[logo], [title], [toggle], [notifications], [profile], [acciones]: contenido proyectado para el header.DialogService: abre diálogos y entrega resultados.NebulaToastService: publica notificaciones para el contenedor global.FormatService: formatos reutilizados en tablas y campos.NavigationService: navegación compartida.provideNebulaCoreIcons, provideNebulaUIConfig, NEBULA_TRANSLATE: iconos, configuración visual/textual y traducción de la aplicación.NebulaPreferencesStore: persistencia de preferencias de tabla/densidad.Las historias vivas están junto al código, en projects/nebula-ui-kit/src/lib/components/**/**/*.stories.ts. Algunas rutas útiles:
button/button.stories.ts, input/input.stories.ts, autocomplete/autocomplete.stories.ts, datepicker/datepicker.stories.ts.table/table.stories.ts, table-compact/table-compact.stories.ts, table-input/table-input.stories.ts.form-layout/ (modelos, helper, motor y pruebas), grid-form/grid-form.stories.ts, form-card/form-card.stories.ts.tasks/tasks.stories.ts, import-export/import-export.stories.ts.header, sidebar, tabs, breadcrumb y layout.La lista de exports oficiales está en projects/nebula-ui-kit/src/public-api.ts. Para la documentación de integración, prioriza esos exports; los componentes marcados como internos se mencionan para orientar, pero la aplicación debería preferir el componente compuesto que los contiene.