npm package: @pingu-components/react
Description: React components for accessing pingustar api
Author: Pingustar
Latest version: 2.3.13

# @pingu-components/react

`@pingu-components/react` es una librería de componentes de React 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/react
```

## 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

```jsx
import NewRating from '@pingu-components/react';

<NewRating
  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

```jsx
import ReviewsList from '@pingu-components/react';

<ReviewsList
  id={123}
  productName="IPhone 15"
  token="your-auth-token"
  onClick={(id) => console.log(id)}
/>
```

---

### 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

```jsx
import OverallRating from '@pingu-components/react';

<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

```jsx
import OverallRating from '@pingu-components/react';

<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

```jsx
import OverallRating from '@pingu-components/react';

<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.