@infinitech.maps/st-map 1.0.18 → 1.0.19

package/README.md

@@ -0,0 +1,226 @@
+# @infinitech.maps/st-map
+
+SDK de React para renderizar mapas interactivos de SmartTicket con selección de asientos, mesas y secciones.
+
+## Instalación
+
+```bash
+npm install @infinitech.maps/st-map
+```
+
+**Peer dependencies:** `react >=18` y `react-dom >=18`.
+
+## Uso básico
+
+```jsx
+import { STMap } from "@infinitech.maps/st-map";
+
+function App() {
+  return (
+    <STMap
+      map={mapData}
+      onSeatClick={(seat, shape, event) => {
+        console.log(seat, shape);
+      }}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `map` | `object` | **Requerido.** Objeto JSON del mapa (formato v2 o legacy). |
+| `onSeatClick` | `(seat, shape, event) => void` | Callback al hacer clic en un asiento, silla o mesa. |
+| `onSectionClick` | `(shape, event) => void` | Callback al hacer clic en una sección/categoría completa. |
+| `prices` | `Record<string, number>` | Mapa de precios por UUID (ver sección de precios). |
+| `selectedSeats` | `string[]` | Lista de UUIDs seleccionados (modo controlado). |
+| `reservedSeats` | `string[]` | Lista de UUIDs de asientos reservados. |
+| `selectedSeatColor` | `string` | Color de asientos seleccionados. Default: `"#01FFFF"`. |
+| `reservedSeatColor` | `string` | Color de asientos reservados. Default: `"#FF0000"`. |
+| `purchasedSeatColor` | `string` | Color de asientos comprados. Default: `"#000000"`. |
+| `hoverColor` | `string` | Color al pasar el cursor. Default: `"#444"`. |
+| `hoverTransition` | `number` | Duración de la transición hover en ms. Default: `0`. |
+| `onReady` | `() => void` | Callback cuando el mapa termina de renderizar. |
+
+---
+
+## Obtener el UUID y precio de un elemento
+
+Al hacer clic en cualquier elemento reservable (asiento, silla o mesa), el SDK invoca el callback `onSeatClick` con tres argumentos. El **UUID** y el **precio** se obtienen del primer argumento (`seat`):
+
+### `onSeatClick(seat, shape, event)`
+
+| Argumento | Descripción |
+|-----------|-------------|
+| `seat` | Objeto del asiento/mesa seleccionado. Contiene `id` (UUID) y `price` (si hay precio asignado). |
+| `shape` | Objeto de la forma padre (fila, mesa, sector). Contiene metadatos como `category`, `section`, `sectorName`, etc. |
+| `event` | Evento de Konva (canvas). |
+
+#### Propiedades clave de `seat`
+
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| `seat.id` | `string` | **UUID** único del elemento seleccionado. |
+| `seat.price` | `number \| undefined` | **Precio** resuelto. Presente solo si se pasó la prop `prices` y existe un precio para este elemento. Si no hay precio, esta propiedad **no existe**. |
+| `seat.name` | `string` | Nombre visible del asiento (ej. `"A01"`). |
+| `seat.row` | `string \| number` | Fila del asiento. |
+| `seat.column` | `number` | Columna del asiento. |
+| `seat.status` | `string` | Estado: `"vacant"`, `"reserved"`, `"purchased"`. |
+| `seat.isTable` | `boolean` | `true` cuando se selecciona una mesa completa (modo mesa). |
+| `seat.tableName` | `string` | Nombre de la mesa (solo si `isTable` es `true`). |
+| `seat.chairs` | `array` | Lista de sillas de la mesa (solo si `isTable` es `true`). |
+| `seat.totalChairs` | `number` | Total de sillas en la mesa (solo si `isTable` es `true`). |
+
+### Ejemplo: obtener UUID y precio
+
+```jsx
+import { STMap } from "@infinitech.maps/st-map";
+
+function MapView({ mapData }) {
+  const prices = {
+    // UUID de categoría, sector o asiento individual → precio
+    "d5195a0a-2e6f-4167-a930-b26440d1e072": 150,  // Categoría "VIP"
+    "702fdfc0-3a10-48a5-861c-0ddddac1bf7f": 50,   // Categoría "General"
+    "58a5497e-eb75-445a-a89c-dc0fbe652d38": 500,   // Asiento específico
+  };
+
+  const handleSeatClick = (seat, shape, event) => {
+    // UUID del elemento
+    const uuid = seat.id;
+
+    // Precio (puede ser undefined si no se configuró)
+    const precio = seat.price;
+
+    console.log("UUID:", uuid);
+    console.log("Precio:", precio !== undefined ? precio : "Sin precio asignado");
+
+    // Ejemplo: agregar al carrito
+    if (seat.isTable) {
+      console.log(`Mesa "${seat.tableName}" con ${seat.totalChairs} sillas`);
+    } else {
+      console.log(`Asiento ${seat.name}, fila ${seat.row}`);
+    }
+  };
+
+  return (
+    <STMap
+      map={mapData}
+      prices={prices}
+      onSeatClick={handleSeatClick}
+    />
+  );
+}
+```
+
+### `onSectionClick(shape, event)`
+
+Para secciones/categorías completas (formas geométricas sin asientos individuales):
+
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| `shape.id` | `string` | **UUID** de la sección. |
+| `shape.price` | `number \| undefined` | **Precio** resuelto (si existe). |
+| `shape.category` | `string` | ID de la categoría. |
+| `shape.categoryName` | `string` | Nombre de la categoría. |
+| `shape.section` | `string` | ID del sector. |
+| `shape.sectorName` | `string` | Nombre del sector. |
+
+```jsx
+const handleSectionClick = (shape, event) => {
+  console.log("UUID sección:", shape.id);
+  console.log("Precio:", shape.price !== undefined ? shape.price : "Sin precio");
+};
+
+<STMap
+  map={mapData}
+  prices={prices}
+  onSeatClick={handleSeatClick}
+  onSectionClick={handleSectionClick}
+/>
+```
+
+---
+
+## Resolución jerárquica de precios
+
+Cuando se pasa la prop `prices`, el SDK resuelve el precio de forma jerárquica buscando en este orden:
+
+1. **Asiento individual** → `prices[seat.id]`
+2. **Sector** → `prices[shape.section]`
+3. **Categoría** → `prices[shape.category]`
+
+El primer match encontrado se asigna como `seat.price` (o `shape.price` en secciones).
+
+Si se proporcionan `prices` pero no se encuentra precio en ningún nivel, el SDK muestra una alerta y **no permite la selección** del elemento.
+
+Si **no** se pasa la prop `prices`, no hay validación de precio y todos los elementos son seleccionables.
+
+---
+
+## Console log integrado
+
+El SDK incluye un log automático en la consola del navegador cada vez que se hace clic en un elemento reservable:
+
+Para **asientos/mesas** (`onSeatClick`):
+```js
+[ST-Map] Seat click {
+  uuid: "58a5497e-eb75-445a-a89c-dc0fbe652d38",
+  price: 500,
+  row: "A",
+  column: 1,
+  category: "VIP",
+  section: "Sector 1"
+}
+```
+
+Para **secciones** (`onSectionClick`):
+```js
+[ST-Map] Section click {
+  uuid: "3b1633c9-57d0-4438-b952-95c213f98e29",
+  price: 200,
+  category: "General",
+  section: "Sector 2"
+}
+```
+
+Si un campo no existe en el elemento (ej. fila/columna en mesas), se muestra `"N/A"`. Si no hay precio, se muestra `"sin precio"`.
+
+Esto facilita la depuración durante el desarrollo.
+
+---
+
+## Selección controlada
+
+Por defecto el SDK gestiona la selección internamente. Para controlarla externamente, pasa `selectedSeats`:
+
+```jsx
+const [selected, setSelected] = useState([]);
+
+const handleSeatClick = (seat) => {
+  setSelected((prev) =>
+    prev.includes(seat.id)
+      ? prev.filter((id) => id !== seat.id)
+      : [...prev, seat.id]
+  );
+};
+
+<STMap
+  map={mapData}
+  selectedSeats={selected}
+  onSeatClick={handleSeatClick}
+/>
+```
+
+---
+
+## STMapClient
+
+Cliente HTTP para interactuar con la API de gestión de asientos:
+
+```js
+import { STMapClient } from "@infinitech.maps/st-map";
+
+const client = new STMapClient({ baseUrl: "https://api.example.com" });
+```