is-uikit-components-vue

is-uikit-components-vue

Descripción y propósito

Adaptador centralizado de PrimeVue 4 para la plataforma Interseguro.

• Re-exporta todos los componentes de PrimeVue con prefijo Is* (ej. IsButton, IsDataTable).
• Centraliza la configuración de tema, locale y servicios globales en un único plugin (createIsUiKitPlugin).
• Incluye el preset corporativo de PrimeVue basado en Aura (InterseguroAuraPreset) y el preset de Tailwind CSS (interseguroTailwindPreset), ambos sincronizados desde la misma fuente de verdad de tokens de color.
• Expone componentes propios de la organización bajo el subpath /org.

Versión actual: 2.0.0

Repositorio

is-pkg-crosscore-uikit-lib-vue

Requisitos

Estructura del proyecto

is-pkg-crosscore-uikit-lib-vue/
├── src/
│   ├── adapters/                          # Adaptadores Is* generados automáticamente
│   │   ├── generated.ts                   # Re-exports de componentes PrimeVue con prefijo Is*
│   │   └── eventbus.d.ts                  # Tipado del bus de eventos de PrimeVue
│   ├── org/                               # Componentes propios de Interseguro
│   │   ├── index.ts                       # Barrel de exports del subpath /org
│   │   ├── IsNavMenu.vue                  # Menú de navegación lateral corporativo
│   │   └── NavIcon.vue                    # Icono de opción: URL a SVG o clase PrimeIcons (interno)
│   ├── plugin/                            # Plugin Vue principal
│   │   └── create-is-uikit-plugin.ts      # Factory del plugin e interfaz IsUiKitPluginOptions
│   ├── prime/                             # Configuración de PrimeVue
│   │   ├── default-prime-vue-options.ts   # Opciones por defecto (tema Aura, locale ES)
│   │   └── interseguro-aura-preset.ts     # Preset Aura extendido con paleta corporativa
│   ├── styles/                            # Estilos Is*Style generados automáticamente
│   │   └── generated-styles.ts            # Re-exports de estilos de componentes PrimeVue
│   ├── tailwind/                          # Integración Tailwind CSS
│   │   └── preset.ts                      # Preset Tailwind con paleta corporativa
│   ├── tokens/                            # Tokens de diseño (fuente de verdad)
│   │   └── palette.ts                     # Paleta de colores corporativos de Interseguro
│   └── index.ts                           # Entry point principal de la librería
├── scripts/
│   └── generate-adapters.mjs              # Genera adaptadores Is* leyendo primevue/index.d.ts
├── type-tests/                            # Tests de tipos (deben compilar); barrera de regresión
│   └── imperative-api.ts                  # API imperativa y props reales visibles vía Is*
├── dist/                                  # Salida compilada (generada por vite build)
├── package.json
├── tsconfig.typecheck.json                # tsconfig de npm run typecheck (src + type-tests)
├── vite.config.ts
├── CHANGELOG.md
└── README.md

Quickstart

Instalación

npm install is-uikit-components-vue

Peer dependencies requeridas en el proyecto consumidor:

npm install vue primevue

1. Registrar el plugin en una SPA

// main.ts de cualquier microfrontend o SPA
import { createApp } from 'vue';
import { createIsUiKitPlugin } from 'is-uikit-components-vue';
import App from './App.vue';

const app = createApp(App);
app.use(createIsUiKitPlugin());
app.mount('#app');

2. Integrar con single-spa (handleInstance)

import { createApp, h } from 'vue';
import singleSpaVue from 'single-spa-vue';
import { createIsUiKitPlugin } from 'is-uikit-components-vue';
import App from './App.vue';

const lifecycles = singleSpaVue({
  createApp,
  appOptions: { render: () => h(App) },
  handleInstance: (app) => {
    app.use(createIsUiKitPlugin());
  },
});

export const { bootstrap, mount, unmount } = lifecycles;

3. Sobreescribir configuración por microfrontend

import { createIsUiKitPlugin } from 'is-uikit-components-vue';
import Lara from '@primevue/themes/lara';

app.use(createIsUiKitPlugin({
  primeVue: {
    theme: {
      preset: Lara,
      options: { darkModeSelector: '.my-dark' },
    },
  },
  toastService: false,   // deshabilitar servicios que el MF no usa
  dialogService: false,
}));

Configuración esencial

No requiere variables de entorno. La configuración se realiza a través de las opciones del plugin.

Opciones de createIsUiKitPlugin

Exports disponibles

Componentes Is*

Todos los componentes de PrimeVue 4.5.x con prefijo Is. Las props son idénticas a las de PrimeVue; el autocompletado en el IDE es el mismo.

<script setup lang="ts">
import { IsButton, IsInputText, IsDataTable, IsColumn } from 'is-uikit-components-vue';
</script>

<template>
  <IsButton label="Guardar" severity="primary" />
  <IsInputText v-model="valor" placeholder="Escribe aquí..." />
</template>

Cada Is* es el componente de PrimeVue re-exportado con alias, no un wrapper. Por tanto un ref da acceso a su API imperativa completa (toggle, show, hide, $el, exportCSV…), que en componentes como Popover o los menús en modo popup es la única forma de controlarlos:

<script setup lang="ts">
import { ref } from 'vue';
import { IsPopover } from 'is-uikit-components-vue';

const pop = ref<InstanceType<typeof IsPopover>>();
</script>

<template>
  <IsButton label="Más acciones" @click="pop?.toggle($event)" />
  <IsPopover ref="pop">
    <!-- contenido del overlay -->
  </IsPopover>
</template>

Como consecuencia de ser el componente real, el name interno (el que muestra Vue DevTools y el que usa findComponent({ name }) en tests) es el de PrimeVue: Popover, no IsPopover.

Lista completa: Accordion, AccordionContent, AccordionHeader, AccordionPanel, AccordionTab, AutoComplete, Avatar, AvatarGroup, Badge, BadgeDirective, BlockUI, Breadcrumb, Button, ButtonGroup, Calendar, Card, Carousel, CascadeSelect, Checkbox, CheckboxGroup, Chip, Chips, ColorPicker, Column, ColumnGroup, ConfirmDialog, ConfirmPopup, ContextMenu, DataTable, DataView, DatePicker, DeferredContent, Dialog, Divider, Dock, Drawer, Dropdown, DynamicDialog, Fieldset, FileUpload, FloatLabel, Fluid, FocusTrap, Galleria, IconField, IftaLabel, Image, ImageCompare, InlineMessage, Inplace, InputChips, InputGroup, InputGroupAddon, InputIcon, InputMask, InputNumber, InputOtp, InputSwitch, InputText, KeyFilter, Knob, Listbox, MegaMenu, Menu, Menubar, Message, MeterGroup, MultiSelect, OrderList, OrganizationChart, OverlayBadge, OverlayPanel, Paginator, Panel, PanelMenu, Password, PickList, Popover, Portal, ProgressBar, ProgressSpinner, RadioButton, RadioButtonGroup, Rating, Ripple, Row, ScrollPanel, ScrollTop, Select, SelectButton, Sidebar, Skeleton, Slider, SpeedDial, SplitButton, Splitter, SplitterPanel, Step, StepItem, StepList, StepPanel, StepPanels, Stepper, Steps, StyleClass, Tab, TabList, TabMenu, TabPanel, TabPanels, Tabs, TabView, Tag, Terminal, Textarea, TieredMenu, Timeline, Toast, ToggleButton, ToggleSwitch, Toolbar, Tooltip, Tree, TreeSelect, TreeTable, VirtualScroller.

Estilos Is*Style

Objetos de estilo para personalización avanzada (PassThrough API de PrimeVue):

import { IsButtonStyle, IsDataTableStyle } from 'is-uikit-components-vue';

Composables de PrimeVue

import { useConfirm, useDialog, useToast, useStyle } from 'is-uikit-components-vue';

Preset corporativo PrimeVue

import { InterseguroAuraPreset } from 'is-uikit-components-vue';

Directivas

Las directivas se registran manualmente en el componente o globalmente en la app:

import { IsTooltip, IsRipple } from 'is-uikit-components-vue';

app.directive('tooltip', IsTooltip);
app.directive('ripple', IsRipple);

Subpath /org — Componentes de la organización

import { IsNavMenu } from 'is-uikit-components-vue/org';
import type { NavMenuItem } from 'is-uikit-components-vue/org';

Iconos de NavMenuItem.Icono

El campo Icono acepta tres formas y se resuelve en este orden:

const items: NavMenuItem[] = [
  { Titulo: 'Inicio', Icono: 'pi pi-home', /* … */ },
  { Titulo: 'Ajustes', Icono: 'pi-cog', /* … */ },
  { Titulo: 'Pólizas', Icono: '/assets/icons/poliza.svg', /* … */ },
];

Requisito para las clases pi pi-*: la app host debe importar el CSS de PrimeIcons (import 'primeicons/primeicons.css'). La librería no lo empaqueta. Si no está cargado, el icono no resuelve a ningún glifo y se muestra el icono por defecto — sin errores en consola.

Ver src/org/index.ts para agregar nuevos componentes propios de Interseguro.

Subpath /tailwind — Preset Tailwind CSS

Preset de Tailwind con la paleta de colores corporativos, sincronizado con InterseguroAuraPreset (misma fuente de verdad en src/tokens/palette.ts).

// tailwind.config.js del microfrontend
import { interseguroTailwindPreset } from 'is-uikit-components-vue/tailwind';

export default {
  presets: [interseguroTailwindPreset],
  content: ['./src/**/*.{vue,ts}'],
};

Tokens de color disponibles:

Subpath /style.css

Estilos CSS compilados de la librería:

import 'is-uikit-components-vue/style.css';

Scripts de desarrollo

npm run build          # Compila la librería con Vite
npm run build:full     # Regenera adaptadores y compila (generate + build)
npm run generate       # Regenera src/adapters/generated.ts y src/styles/generated-styles.ts
npm run dev            # Compila en modo watch
npm run typecheck      # Verificación de tipos con vue-tsc, incluyendo type-tests/
npm run preview        # Sirve el dist en http://localhost:9010

npm run typecheck usa tsconfig.typecheck.json, que además de src/ incluye type-tests/. Ese directorio son tests de tipos que deben compilar: no hay runner de tests en el repo, así que typecheck es la barrera de regresión y corre en CI antes del build. type-tests/imperative-api.ts cubre que la API imperativa (toggle/show/hide) y las props reales sigan visibles a través de los alias Is*.

Regenerar adaptadores tras actualizar PrimeVue

npm run build:full     # equivalente a: npm run generate && npm run build

Tras regenerar, ejecutar npm run typecheck y revisar el diff de src/adapters/generated.ts: una subida de versión menor de PrimeVue puede añadir o quitar exports.

Publicar en npm

El paquete se publica en el registry público de npm (registry.npmjs.org) con el nombre sin scope is-uikit-components-vue. El campo publishConfig del package.json fija ese registry, así que no depende de la configuración de ~/.npmrc de cada máquina.

# 1. Autenticarse (interactivo: navegador / OTP)
npm login
npm whoami                     # debe responder con tu usuario

# 2. Verificar en limpio
rm -rf dist && npm ci
npm run typecheck              # compila type-tests/ — hace de suite de pruebas
npm run build:full

# 3. Revisar el contenido del tarball ANTES de publicar
npm publish --dry-run          # solo debe listar dist/**, package.json, README.md, CHANGELOG.md

# 4. Publicar (agregar --otp=<código> si la cuenta tiene 2FA)
npm publish

# 5. Verificar y etiquetar
npm view is-uikit-components-vue version dist-tags
git tag v2.0.0 && git push origin v2.0.0

El script prepublishOnly ejecuta automáticamente typecheck y build:full (generate + build) antes de publicar, de modo que un build roto no llega al registry.

npm publish es irreversible: un número de versión no se puede reutilizar y el unpublish solo está permitido durante las primeras 72 horas. El paso 3 (--dry-run) no es opcional.

Compatibilidad