simplekit-vue

Conjunto de componentes de interfaz para Vue 3, listos para usar con Tailwind CSS. Incluye botones, inputs, selects, cards, modales, sistema de toasts y utilidades de navegación, con tipados completos y build ESM/CJS + d.ts.

La librería está pensada para integrarse en proyectos que ya usan Tailwind. No incluye CSS propio; los componentes usan clases utilitarias de Tailwind para estilado.

Instalación

Instala la librería (Vue 3.4+ requerido):

npm i simplekit-vue
# o
yarn add simplekit-vue
# o
pnpm add simplekit-vue
# o
bun add simplekit-vue

Peer dependencies (algunas son opcionales según el componente que uses):

• vue ^3.4.0
• motion-v (opcional; animaciones como toasts/transiciones)
• clsx (opcional)
• tailwind-merge (opcional)
• vee-validate (opcional; integración de formularios)

Requisitos de estilos:

• Tailwind CSS v4 (o equivalente) configurado en tu proyecto, ya que los componentes están escritos con clases utilitarias.

Uso rápido

<script setup lang="ts">
import { ButtonUI, Card, CardHeader, CardTitle, CardContent } from "simplekit-vue";
</script>

<template>
  <Card class="max-w-sm">
    <CardHeader>
      <CardTitle>Hola</CardTitle>
    </CardHeader>
    <CardContent>
      <ButtonUI color="primary">Acción</ButtonUI>
    </CardContent>
  </Card>
</template>

Matriz de componentes (resumen)

| Categoría | Componentes destacados | | --- | --- | | Formularios | InputUI, TextareaUI, CheckboxUI, SelectUI, RadioGroup, Switch, NumberInput, DatePickerUI, DateRangePicker, TimePickerUI, FileUpload, TagInput, ColorPicker | | Feedback | Alert, ToastProvider, ToastContainer, Skeleton, ConfirmDialog, Modal, Drawer | | Navegación | NavLinkUI, SidebarNavLink, Breadcrumbs, Pagination, Tabs | | Superficie de datos | Card, Table, TableSelection | | Interacción avanzada | CommandPalette, ContextMenu, Popover, Tooltip, Carousel, ImageZoom, TransferList, Timeline |

Íconos en SidebarNavLink

SidebarNavLink usa slots para íconos y descripción:

<script setup lang="ts">
import { SidebarNavLink } from "simplekit-vue";
import { House } from "lucide-vue-next";
</script>

<template>
  <SidebarNavLink to="/" :is-open="true">
    <template #icon>
      <House class="h-4 w-4" />
    </template>

    Inicio

    <template #description>
      Ir a inicio
    </template>
  </SidebarNavLink>
</template>

Sistema de Toasts

Envuelve tu app con el proveedor y monta el contenedor una sola vez.

<!-- App.vue -->
<script setup lang="ts">
import { ToastProvider, ToastContainer } from "simplekit-vue";
import ToastDemo from "./ToastDemo.vue";
</script>

<template>
  <ToastProvider>
    <ToastDemo />
    <ToastContainer />
  </ToastProvider>
</template>

<!-- ToastDemo.vue -->
<script setup lang="ts">
import { ButtonUI, useToastMethods } from "simplekit-vue";

const toast = useToastMethods();
</script>

<template>
  <ButtonUI @click="toast.success('Guardado', 'Cambios aplicados')">
    Mostrar toast
  </ButtonUI>
</template>

Formularios básicos

<script setup lang="ts">
import { InputUI, SelectUI, SelectItem, TextareaUI, CheckboxUI } from "simplekit-vue";
</script>

<template>
  <InputUI label="Nombre" placeholder="Tu nombre" />

  <SelectUI label="Opción">
    <SelectItem value="1">Uno</SelectItem>
    <SelectItem value="2">Dos</SelectItem>
  </SelectUI>

  <TextareaUI label="Mensaje" />
  <CheckboxUI label="Acepto los términos" />
</template>

Integración con vee-validate

La librería exporta helpers en simplekit-vue/integrations para enlazar campos con menos boilerplate.

<script setup lang="ts">
import { InputUI, ButtonUI, useSimpleKitField } from "simplekit-vue";

const emailField = useSimpleKitField<string>("email");

function submit() {
  // Envía tu formulario aquí.
}
</script>

<template>
  <form class="space-y-4" @submit.prevent="submit">
    <InputUI
      label="Email"
      v-bind="emailField.bindings"
      :error-message="emailField.errorMessage"
      placeholder="[email protected]"
    />
    <ButtonUI type="submit">Guardar</ButtonUI>
  </form>
</template>

Navegación

NavLinkUI renderiza <a> por defecto y también permite usar componentes de routing con la prop as.

<script setup lang="ts">
import { NavLinkUI } from "simplekit-vue";
</script>

<template>
  <NavLinkUI href="/">Inicio</NavLinkUI>
</template>

Con vue-router:

<script setup lang="ts">
import { RouterLink } from "vue-router";
import { NavLinkUI } from "simplekit-vue";
</script>

<template>
  <NavLinkUI :as="RouterLink" to="/" :active="true">
    Inicio
  </NavLinkUI>
</template>

SidebarNavLink está acoplado a vue-router y espera to + slots (icon, description) para navegación lateral.

SSR y frameworks (Nuxt/Vite SSR)

• El paquete no inyecta CSS y depende de Tailwind en la app consumidora.
• Componentes interactivos (por ejemplo Modal, Drawer, ToastContainer, CommandPalette) deben montarse en cliente cuando tu framework separa SSR/CSR.
• En Nuxt, usa ClientOnly cuando un componente dependa de APIs del navegador.
• Evita usar window, document o localStorage durante render del servidor en tus wrappers/composables.

Estilos y Tailwind

• Los componentes usan clases de Tailwind; el paquete no inyecta CSS.
• Asegúrate de tener Tailwind configurado en tu app y que tu pipeline procese clases dinámicas (por ejemplo bg-, text-, rounded-, etc.).
• Si deseas replicar los estilos del playground, puedes basarte en tus propios tokens/temas Tailwind.

Tailwind v4: declarar fuentes (@source)

Si usas Tailwind v4, añade en tu hoja de estilos global (por ejemplo src/style.css o src/assets/main.css) las rutas desde donde Tailwind debe escanear clases. Incluye también este paquete para que sus clases se generen correctamente:

/* Dile a Tailwind v4 dónde escanear clases */
@source "./index.html";
@source "./src/**/*.{vue,js,jsx,ts,tsx,html}";

/* Incluye la librería para que sus clases se generen */
@source "./node_modules/simplekit-vue/dist/**/*.{js,cjs}";

Ajusta las rutas relativas según la ubicación de tu CSS global. Por ejemplo, si tu CSS vive en src/styles/globals.css, cambia los prefijos ./ por ../ donde sea necesario.

Tipos y tree-shaking

• Exporta ESM (dist/index.js), CJS (dist/index.cjs) y tipos (dist/index.d.ts).
• sideEffects: false permite tree-shaking.

Desarrollo local (playground)

Este repo incluye un playground con Vite para probar los componentes:

bun run dev      # inicia el playground
bun run build    # genera la librería en dist/

Licencia

Pendiente de definir por el autor.