@hemia/ui-button
Version:
Componente HButton basado en Vuetify para el Design System de Hemia
177 lines (135 loc) • 9.93 kB
Markdown
# @hemia/ui-button
`@hemia/ui-button` es un componente de botón personalizado basado en Vuetify 3 y optimizado para integrarse perfectamente con cualquier proyecto Vue 3 que use Vuetify. Este componente forma parte del Design System de Hemia y está pensado para ser flexible, accesible y altamente configurable.
---
## 🚀 Características
* Componente basado en `v-btn` de Vuetify
* Compatible con todas las props oficiales de Vuetify
* Soporte para slots `prepend`, `append`, `default` y `loader`
* Soporte para `prepend-icon` y `append-icon`
* Estilos adaptables según el tema de Vuetify
* Preparado para ser usado de forma modular o global
---
## 📦 Instalación
```bash
npm install @hemia/ui-button
# o
pnpm add @hemia/ui-button
```
> Asegúrate de tener instalados `vue@^3` y `vuetify@^3` como dependencias del proyecto.
---
## 🧩 Uso
### Registro local
```ts
<script setup lang="ts">
import { HButton } from '@hemia/ui-button';
</script>
<template>
<h-button color="primary">Guardar</h-button>
</template>
```
### Registro global
```ts
import { createApp } from 'vue';
import App from './App.vue';
import HButtonPlugin from '@hemia/ui-button';
const app = createApp(App);
app.use(HButtonPlugin);
```
---
## 💡 Ejemplos
```vue
<h-button color="primary" prepend-icon="mdi-plus">
Crear nuevo
</h-button>
<h-button variant="outlined" size="small" :loading="true">
Guardando...
</h-button>
<h-button icon="mdi-delete" color="error" flat />
```
---
## 🔧 Props soportadas
El componente `HButton` soporta todas las props oficiales de [`v-btn`](https://vuetifyjs.com/en/api/v-btn/), incluyendo las siguientes:
| Propiedad | Tipo | Valor por defecto | Descripción |
| --------------- | -------------------------------------------------------------------- | ----------------- | ---------------------------------------- |
| `active` | `boolean` | `undefined` | Controla el estado activo del botón. |
| `activeColor` | `string` | `undefined` | Color aplicado cuando está activo. |
| `appendIcon` | `IconValue` | `undefined` | Icono al final (usando `v-icon`). |
| `baseColor` | `string` | `undefined` | Color base (cuando no está enfocado). |
| `block` | `boolean` | `false` | Ocupa el 100% del ancho disponible. |
| `border` | `string \| number \| boolean` | `false` | Aplica clases utilitarias de borde. |
| `color` | `string` | `undefined` | Color principal del botón. |
| `density` | `'default' \| 'comfortable' \| 'compact'` | `'default'` | Ajusta la altura vertical. |
| `disabled` | `boolean` | `false` | Desactiva el botón. |
| `elevation` | `string \| number` | `undefined` | Controla la elevación (sombra). |
| `exact` | `boolean` | `false` | Navegación exacta con Vue Router. |
| `flat` | `boolean` | `false` | Elimina sombra del botón. |
| `height` | `string \| number` | `undefined` | Altura del botón. |
| `href` | `string` | `undefined` | Hace que el botón actúe como enlace. |
| `icon` | `IconValue` | `undefined` | Estilo icon-only o ícono principal. |
| `loading` | `boolean \| string` | `false` | Muestra un loader. |
| `location` | `Anchor \| null` | `undefined` | Posicionamiento usando anchor. |
| `maxHeight` | `string \| number` | `undefined` | Altura máxima. |
| `maxWidth` | `string \| number` | `undefined` | Ancho máximo. |
| `minHeight` | `string \| number` | `undefined` | Altura mínima. |
| `minWidth` | `string \| number` | `undefined` | Ancho mínimo. |
| `position` | `'fixed' \| 'static' \| 'relative' \| 'absolute' \| 'sticky'` | `undefined` | Posición CSS. |
| `prependIcon` | `IconValue` | `undefined` | Icono antes del contenido. |
| `readonly` | `boolean` | `false` | Versión de solo lectura (no clicable). |
| `replace` | `boolean` | `false` | Usa `router.replace()` en lugar de push. |
| `ripple` | `boolean \| { class: string; keys: string[] }` | `true` | Efecto ripple. |
| `rounded` | `string \| number \| boolean` | `undefined` | Control del `border-radius`. |
| `selectedClass` | `string` | `undefined` | Clase CSS aplicada si está activo. |
| `size` | `string \| number` | `'default'` | Tamaño del botón. |
| `slim` | `boolean` | `false` | Reduce el padding. |
| `stacked` | `boolean` | `false` | Coloca ícono y texto en columna. |
| `symbol` | `any` | `undefined` | Para grupos como `v-btn-toggle`. |
| `tag` | `string \| Component` | `'button'` | Tag HTML o componente raíz. |
| `text` | `string \| number \| boolean` | `undefined` | Contenido textual alternativo. |
| `theme` | `string` | `undefined` | Tema aplicado al botón. |
| `tile` | `boolean` | `false` | Elimina `border-radius`. |
| `to` | `string \| object` | `undefined` | Enlace interno para Vue Router. |
| `value` | `any` | `undefined` | Valor para selección en grupo. |
| `variant` | `'text' \| 'flat' \| 'elevated' \| 'tonal' \| 'outlined' \| 'plain'` | `'elevated'` | Estilo visual del botón. |
| `width` | `string \| number` | `undefined` | Ancho del botón. |
| `fontSemiBold` | `boolean` | `true` | Si aplica la clase `font-semibold`. |
---
## 🧩 Slots disponibles
| Nombre | Descripción |
| --------- | ----------------------------------------------------------- |
| `default` | Contenido principal del botón (texto, íconos, etc.) |
| `prepend` | Se muestra antes del contenido principal (útil para íconos) |
| `append` | Se muestra después del contenido principal |
| `loader` | Contenido personalizado cuando `loading = true` |
---
## ⚙️ Eventos disponibles
| Evento | Parámetros | Descripción |
| ---------------- | -------------------- | -------------------------------------------------- |
| `click` | `MouseEvent` | Emitido al hacer clic sobre el botón |
| `focus` | `FocusEvent` | Emitido al enfocar el botón |
| `group:selected` | `{ value: boolean }` | Emitido al seleccionar el botón dentro de un grupo |
---
## 📤 Expuestos (internamente por Vuetify)
Cuando se usa en `v-btn-toggle`, Vuetify expone:
```ts
{
group: {
id: string;
isSelected: boolean;
isFirst: boolean;
isLast: boolean;
toggle: () => void;
select: (value: boolean) => void;
selectedClass: string[];
value: unknown;
disabled?: boolean;
...
}
}
```
---
## 🧪 Notas adicionales
* Este componente puede usarse dentro de grupos (`v-btn-toggle`, `v-bottom-navigation`, etc.)
* Todas las props están alineadas con la API oficial de Vuetify 3
---
## 📄 Licencia
MIT — Hemia Technologies