npm package: @pingu-components/vue
Description: Vue components for accessing pingustar api
Author: Pingustar
Latest version: 1.0.1

# @pingu-components/vue

`@pingu-components/vue` es una librería de componentes de Vue que permite la integración con un servicio de ratings para productos. Esta versión incluye tres componentes públicos: `NewRating`, `ReviewsList`, `OverallRating`, `ReviewDetail` y `NewProduct`.

> **Nota:** Para utilizar estos componentes y obtener ratings visibles, debes contratar el servicio de ratings asociado.

## Instalación

Instala la librería usando npm:

```bash
npm install @pingu-components/vue
```

## Componentes

### 1. NewReview

Permite a los usuarios crear un nuevo rating para un producto específico. Se utiliza proporcionando el `id` del producto y un `token` de autenticación. El `onSubmit` se ejecuta cuando el formulario se envía correctamente.

#### Props

| Prop              | Tipo           | Descripción                                                                                                                | Opcional | Valor por defecto       |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------- |
| `id`              | `number`       | ID interno del producto al que se le agregará un rating.                                                                   | No       | -                       |
| `productName`     | `string`       | Nombre del producto en tu página (se usará para crearlo si no existe en nuestra base de datos)                             | No       | -                       |
| `token`           | `string`       | Token de autenticación para el servicio de ratings.                                                                        | No       | -                       |
| `userWritter`     | `string`       | Es necesario para indicar el nombre de usuario del desarrollador de la Review. Es opcional agregarle el origen luego de un | No       |                         |
| `onSubmit`        | `() => void`   | Callback a ejecutar al enviar el formulario.                                                                               | No       | -                       |
| `size`            | `number`       | Tamaño de las estrellas del rating.                                                                                        | Sí       | `22`                    |
| `bgColor`         | `string`       | Color de fondo del formulario.                                                                                             | Sí       | `'white'`               |
| `textColor`       | `string`       | Color del texto.                                                                                                           | Sí       | `'black'`               |
| `fontFamily`      | `string`       | Familia tipográfica a utilizar.                                                                                            | Sí       | `"'Arial', sans-serif"` |
| `starsColor`      | `string`       | Color de las estrellas.                                                                                                    | Sí       | `'gold'`                |
| `borderColor`     | `string`       | Color del borde de los campos de formulario.                                                                               | Sí       | `'#d1d5db'`             |
| `buttonColor`     | `string`       | Color del botón de envío.                                                                                                  | Sí       | `'blue'`                |
| `buttonTextColor` | `string`       | Color del texto del botón de envío.                                                                                        | Sí       | `'white'`               |
| `skeleton color`  | `string`       | Color de los placeholders de los skeletons de carga.                                                                       | Sí       | `'#d1d5db'`             |
| `language`        | `'en' \| 'es'` | Idioma en el que se mostrará el formulario.                                                                                | Sí       | `'en'`                  |

#### Ejemplo de uso

```vue
<NewReview :id="123" :productName="'IPhone 15'" :token="'your-auth-token'" :onSubmit="() => alert('Review submitted!')" :userWritter="'Jane Doe - PinguStars'" />
```

---

### 2. ReviewsList

Muestra una lista de reviews para un producto dado. También permite personalizar varios aspectos visuales como los colores, tamaños de texto y estrellas.

#### Props

| Prop                 | Tipo                                               | Descripción                                                                                                                                                 | Opcional | Valor por defecto       |
| -------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------- |
| `id`                 | `number`                                           | ID interno del producto para mostrar los reviews.                                                                                                           | No       | -                       |
| `productName`        | `string`                                           | Nombre del producto en tu página (se usará para crearlo si no existe en nuestra base de datos)                                                              | No       | -                       |
| `token`              | `string`                                           | Token de autenticación para el servicio de reviews.                                                                                                         | No       | -                       |
| `imageUrl`           | `string`                                           | URL de la imagen del producto (debe ser público).                                                                                                           | Sí       | -                       |
| `onClick`            | `(id:number) =>void`                               | Comportamiento al clickear una reseña, pensado para navegar a una página con el detalle de la misma o un popUp                                              | No       | -                       |
| `bgColor`            | `string`                                           | Color de fondo de la lista de reviews.                                                                                                                      | Sí       | `'white'`               |
| `borderColor`        | `string`                                           | Color del borde de cada review.                                                                                                                             | Sí       | `'#d1d5db'`             |
| `shadowColor`        | `string`                                           | Color de la sombra cada review                                                                                                                              | Sí       | `'#d1d5db'`             |
| `skeletonColor`      | `string`                                           | Color de los placeholder de los skeletons de carga                                                                                                          | Sí       | `'#d1d5db'`             |
| `buttonsBgColor`     | `string`                                           | Color de los botones de refresh y de paginación                                                                                                             | Sí       | `'gold'`                |
| `buttonTextColor`    | `string`                                           | Color del texto de los botones de refresh y de paginación                                                                                                   | Sí       | `'black'`               |
| `dropdownBgColor`    | `string`                                           | Color de fondo del dropdown de ordenamiento de reviews                                                                                                      | Sí       | `'#d1d5db'`             |
| `dropdownTextColor`  | `string`                                           | Color del texto del dropdown                                                                                                                                | Sí       | `'#4b5563'`             |
| `starsColor`         | `string`                                           | Color de las estrellas del rating.                                                                                                                          | Sí       | `'gold'`                |
| `starsSize`          | `number`                                           | Tamaño de las estrellas.                                                                                                                                    | Sí       | `20`                    |
| `mainTextColor`      | `string`                                           | Color principal del texto (títulos).                                                                                                                        | Sí       | `'black'`               |
| `secondaryTextColor` | `string`                                           | Color secundario del texto (descripciones).                                                                                                                 | Sí       | `'#4b5563'`             |
| `fontFamily`         | `string`                                           | Familia tipográfica a utilizar.                                                                                                                             | Sí       | `"'Arial', sans-serif"` |
| `placeholderAlign`   | `'left' \| 'center' \| 'right' \| 'start' \| 'end` | Alineación de los placeholders en caso de error o componente vacío.                                                                                         | Sí       | `'left'`                |
| `limit`              | `number`                                           | Define el limite para cada API fetch                                                                                                                        | Sí       | `undefined`             |
| `loadMore`           | `page` \| `scroll` \| `none`                       | Define la forma de paginar los productos, en page, son paginas de reviews; en scroll, se recarga al llegar al final del scroll; en none, no hay paginación. | Sí       | `'none'`                |
| `isMobile`           | `boolean`                                          | En caso de ser verdadero, vuelve el componente más adaptable para dispositivos móviles.                                                                     | Sí       | `false`                 |
| `language`           | `'en' \| 'es'`                                     | Idioma en el que se mostrará el formulario.                                                                                                                 | Sí       | `'en'`                  |

#### Ejemplo de uso

```vue
<ReviewsList :id="123" :productName="'Sample Product'" :token="'your-auth-token'" :imageUrl="'/path/to/image.jpg'" :onClick="handleReviewClick" />
```

---

### 3. OverallRating

Muestra el rating promedio de un producto específico.

#### Props

| Prop            | Tipo     | Descripción                                                                                    | Opcional | Valor por defecto       |
| --------------- | -------- | ---------------------------------------------------------------------------------------------- | -------- | ----------------------- |
| `id`            | `number` | ID interno del producto para mostrar el rating general.                                        | No       | -                       |
| `productName`   | `string` | Nombre del producto en tu página (se usará para crearlo si no existe en nuestra base de datos) | No       | -                       |
| `token`         | `string` | Token de autenticación para el servicio de ratings.                                            | No       | -                       |
| `imageUrl`      | `string` | URL de la imagen del producto (debe ser público).                                              | Sí       | -                       |
| `starsSize`     | `number` | Tamaño de las estrellas.                                                                       | Sí       | `20`                    |
| `starsColor`    | `string` | Color de las estrellas del rating.                                                             | Sí       | `'gold'`                |
| `borderColor`   | `string` | Color del borde de las estrellas.                                                              | Sí       | `'#d1d5db'`             |
| `skeletonColor` | `string` | Color de los placeholders de los skeletons de carga.                                           | Sí       | `'#d1d5db'`             |
| `textColor`     | `string` | Color del texto del rating promedio.                                                           | Sí       | `'black'`               |
| `fontFamily`    | `string` | Familia tipográfica a utilizar.                                                                | Sí       | `"'Arial', sans-serif"` |

#### Ejemplo de uso

```vue
<OverallRating :id="123" :productName="'IPhone 15'" :token="'your-auth-token'" />
```

### 4. ReviewDetail

Muestra el detalle de una reseña segun su id.

#### Props

| Prop              | Tipo           | Descripción                                                          | Opcional | Valor por defecto       |
| ----------------- | -------------- | -------------------------------------------------------------------- | -------- | ----------------------- |
| `id`              | `number`       | ID de la reseña para mostrar al detalle.                             | No       | -                       |
| `token`           | `string`       | Token de autenticación para el servicio de ratings.                  | No       | -                       |
| `onClose`         | `()=>void`     | Acción a ejecutar luego de cerrar el detalle. Ideal para navegación. | No       | -                       |
| `size`            | `number`       | Tamaño de las estrellas.                                             | Sí       | `20`                    |
| `starsColor`      | `string`       | Color de las estrellas del rating.                                   | Sí       | `'gold'`                |
| `bgColor`         | `string`       | Color de fondo del componente                                        | Sí       | `white`                 |
| `borderColor`     | `string`       | Color del borde de las estrellas.                                    | Sí       | `'#d1d5db'`             |
| `textColor`       | `string`       | Color del texto del rating promedio.                                 | Sí       | `'black'`               |
| `fontFamily`      | `string`       | Familia tipográfica a utilizar.                                      | Sí       | `"'Arial', sans-serif"` |
| `buttonColor`     | `string`       | Color de fondo del botón de agregar producto.                        | Sí       | `blue`                  |
| `buttonTextColor` | `string`       | Color del texto del botón.                                           | Sí       | `white`                 |
| `skeletonColor`   | `string`       | Color de los placeholders de los skeletons de carga.                 | Sí       | `'#d1d5db'`             |
| `language`        | `'en' \| 'es'` | Idioma en el que se mostrará el formulario.                          | Sí       | `'en'`                  |

#### Ejemplo de uso

```vue
<OverallRating id="{123}" token="your-auth-token" />
;
```

### 5. NewProduct

Componente para agregar un nuevo producto a la base de datos.

#### Props

| Prop              | Tipo           | Descripción                                                               | Opcional | Valor por defecto       |
| ----------------- | -------------- | ------------------------------------------------------------------------- | -------- | ----------------------- |
| `id`              | `number`       | ID interno del producto que quieres agregar                               | No       | -                       |
| `email`           | `string`       | Your email so that we know who you are                                    | No       | -                       |
| `token`           | `string`       | Token de autenticación para el servicio de ratings.                       | No       | -                       |
| `onSubmit`        | `() => void`   | Función a ejecutar posterior a agregar el producto. Ideal para navegación | No       | -                       |
| `bgColor`         | `string`       | Color de fondo del componente                                             | Sí       | `white`                 |
| `borderColor`     | `string`       | Color del borde de las estrellas.                                         | Sí       | `'#d1d5db'`             |
| `textColor`       | `string`       | Color del texto del rating promedio.                                      | Sí       | `'black'`               |
| `fontFamily`      | `string`       | Familia tipográfica a utilizar.                                           | Sí       | `"'Arial', sans-serif"` |
| `buttonColor`     | `string`       | Color de fondo del botón de agregar producto.                             | Sí       | `gold`                  |
| `buttonTextColor` | `string`       | Color del texto del botón.                                                | Sí       | `black`                 |
| `skeletonColor`   | `string`       | Color de los placeholders de los skeletons de carga.                      | Sí       | `'#d1d5db'`             |
| `language`        | `'en' \| 'es'` | Idioma en el que se mostrará el formulario.                               | Sí       | `'en'`                  |

#### Ejemplo de uso

```vue
<OverallRating id={123} email="your-mail@example.com" token="your-auth-token" onSubmit={() => console.log('Submitted')} />;
```

---

## Notas adicionales

- Los componentes de esta librería no proporcionarán datos de ratings ni reviews si no tienes contratado el servicio de ratings. Asegúrate de obtener las credenciales de autenticación (`token`) de tu proveedor de ratings para que los componentes funcionen correctamente.
- Personaliza la apariencia de los componentes a través de las props proporcionadas, permitiendo adaptarlos al diseño de tu sitio.