@infinitech.maps/st-map 1.0.18 → 1.0.20

package/README.md

@@ -0,0 +1,436 @@
+# @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`.
+
+## Inicio rápido
+
+### Modo self-contained (recomendado)
+
+El componente carga el mapa automáticamente desde la API usando `apiKey` y `cacheKey`:
+
+```jsx
+import { STMap } from "@infinitech.maps/st-map";
+
+function App() {
+  return (
+    <STMap
+      apiKey="tu-api-key"
+      cacheKey="uuid-del-mapa"
+      onSeatClick={(seat, shape, event, meta) => {
+        console.log(seat.id, seat.price);
+      }}
+      loadingFallback={<p>Cargando mapa...</p>}
+      errorFallback={(error) => <p>Error: {error.message}</p>}
+    />
+  );
+}
+```
+
+### Modo legacy (datos directos)
+
+Para pasar el JSON del mapa directamente:
+
+```jsx
+import { STMap } from "@infinitech.maps/st-map";
+
+function App() {
+  return (
+    <STMap
+      map={mapData}
+      onSeatClick={(seat, shape, event, meta) => {
+        console.log(seat.id, seat.price);
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Props
+
+### Modo self-contained
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `apiKey` | `string` | — | **Requerido.** API key de autenticación. |
+| `cacheKey` | `string` | — | **Requerido.** UUID del mapa en caché. |
+| `baseUrl` | `string` | `"http://localhost:3001"` | URL base del Gateway. |
+| `loadingFallback` | `ReactNode` | `null` | Componente a mostrar mientras carga el mapa. |
+| `errorFallback` | `ReactNode \| (error) => ReactNode` | `null` | Componente o función a mostrar en caso de error. |
+
+### Modo legacy
+
+| Prop | Tipo | Descripción |
+|------|------|-------------|
+| `map` | `object` | Objeto JSON del mapa (formato v2 o legacy). |
+
+### Callbacks
+
+| Prop | Firma | Descripción |
+|------|-------|-------------|
+| `onSeatClick` | `(seat, shape, event, meta) => void` | Clic en un asiento, silla o mesa. |
+| `onSectionClick` | `(shape, event) => void` | Clic en una sección/categoría completa. |
+| `onEmptyAreaClick` | `() => void` | Clic en el área vacía del canvas. |
+| `onReady` | `() => void` | El mapa terminó de renderizar. |
+
+### Personalización visual
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `prices` | `Record<string, number>` | — | Mapa de precios por UUID (ver [Resolución de precios](#resolución-jerárquica-de-precios)). |
+| `selectedSeats` | `string[]` | — | Lista de UUIDs seleccionados (modo controlado). |
+| `reservedSeats` | `string[]` | — | Lista de UUIDs de asientos reservados. |
+| `selectedSeatColor` | `string` | `"#01FFFF"` | Color de asientos seleccionados. |
+| `reservedSeatColor` | `string` | `"#FF0000"` | Color de asientos reservados. |
+| `purchasedSeatColor` | `string` | `"#000000"` | Color de asientos comprados. |
+| `hoverColor` | `string` | `"#444"` | Color al pasar el cursor. |
+| `hoverTransition` | `number` | `0` | Duración de la transición hover en ms. |
+
+---
+
+## Callbacks
+
+### `onSeatClick(seat, shape, event, meta)`
+
+Se invoca al hacer clic en cualquier elemento reservable (asiento, silla o mesa).
+
+| Argumento | Descripción |
+|-----------|-------------|
+| `seat` | Objeto del asiento/mesa seleccionado. Contiene `id` (UUID), `price`, `status`, etc. |
+| `shape` | Objeto de la forma padre (fila, mesa, sector). Contiene `category`, `section`, `sectorName`, etc. |
+| `event` | Evento de Konva (canvas). |
+| `meta` | Metadatos adicionales. Contiene `screenPosition` para posicionar popups. |
+
+#### Propiedades 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ó `prices` y existe un precio. |
+| `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.type` | `string` | Tipo de elemento: `"seat"` o `"table"`. |
+
+##### Propiedades exclusivas de mesas (`seat.type === "table"`)
+
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| `seat.isTable` | `boolean` | `true` cuando es una mesa. |
+| `seat.tableName` | `string` | Nombre de la mesa. |
+| `seat.chairs` | `array` | Lista de sillas de la mesa. |
+| `seat.totalChairs` | `number` | Total de sillas en la mesa. |
+| `seat.vacantCount` | `number` | Cantidad de sillas vacantes. |
+| `seat.reservedCount` | `number` | Cantidad de sillas reservadas. |
+| `seat.purchasedCount` | `number` | Cantidad de sillas compradas. |
+| `seat.available` | `number` | Alias de `vacantCount`. |
+
+#### Propiedad `meta.screenPosition`
+
+Contiene las coordenadas CSS del centro del elemento clicado, útil para posicionar tooltips o popups:
+
+```jsx
+const handleSeatClick = (seat, shape, event, meta) => {
+  // Posicionar un popup sobre el asiento
+  setPopupPosition({
+    x: meta.screenPosition.x,
+    y: meta.screenPosition.y,
+  });
+};
+```
+
+### Ejemplo completo: obtener UUID y precio
+
+```jsx
+import { STMap } from "@infinitech.maps/st-map";
+
+function MapView() {
+  const prices = {
+    "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, meta) => {
+    console.log("UUID:", seat.id);
+    console.log("Precio:", seat.price ?? "Sin precio asignado");
+
+    if (seat.type === "table") {
+      console.log(`Mesa "${seat.tableName}" — ${seat.vacantCount}/${seat.totalChairs} disponibles`);
+    } else {
+      console.log(`Asiento ${seat.name}, fila ${seat.row}`);
+    }
+  };
+
+  return (
+    <STMap
+      apiKey="tu-api-key"
+      cacheKey="uuid-del-mapa"
+      prices={prices}
+      onSeatClick={handleSeatClick}
+    />
+  );
+}
+```
+
+### `onSectionClick(shape, event)`
+
+Se invoca al hacer clic en una sección/categoría completa (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
+<STMap
+  apiKey="tu-api-key"
+  cacheKey="uuid-del-mapa"
+  prices={prices}
+  onSeatClick={handleSeatClick}
+  onSectionClick={(shape, event) => {
+    console.log("UUID sección:", shape.id);
+    console.log("Precio:", shape.price ?? "Sin precio");
+  }}
+/>
+```
+
+---
+
+## 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.
+
+---
+
+## Métodos imperativos (ref)
+
+Usa `ref` para acceder a métodos imperativos del componente:
+
+```jsx
+import { useRef } from "react";
+import { STMap } from "@infinitech.maps/st-map";
+
+function App() {
+  const mapRef = useRef();
+
+  return <STMap ref={mapRef} apiKey="tu-api-key" cacheKey="uuid-del-mapa" />;
+}
+```
+
+### `resolveReservationIds(selections)`
+
+Convierte los elementos clicados en IDs de asientos/sillas individuales listos para la API. Para mesas, extrae los IDs de las sillas vacantes; para asientos, devuelve `[id]`.
+
+```jsx
+const seatIds = mapRef.current.resolveReservationIds([
+  { id: "uuid-mesa", quantity: 3 },   // extrae 3 sillas vacantes
+  { id: "uuid-asiento" },             // devuelve [uuid-asiento]
+]);
+// → ["silla-1", "silla-2", "silla-3", "uuid-asiento"]
+```
+
+| Parámetro | Tipo | Descripción |
+|-----------|------|-------------|
+| `selections` | `Array<{ id: string, quantity?: number }>` | Elementos a resolver. `quantity` solo aplica a mesas. |
+
+### `reserveSelected({ selections, ttlSeconds })`
+
+Resuelve IDs y reserva en una sola llamada. Requiere `apiKey` y `cacheKey`.
+
+```jsx
+const { seatIds } = await mapRef.current.reserveSelected({
+  selections: [{ id: "uuid-mesa", quantity: 2 }],
+  ttlSeconds: 300, // 5 minutos (default)
+});
+```
+
+### `releaseAll({ seatIds })`
+
+Libera asientos (vuelven a estado `"vacant"`). Requiere `apiKey` y `cacheKey`.
+
+```jsx
+await mapRef.current.releaseAll({
+  seatIds: ["silla-1", "silla-2"],
+});
+```
+
+---
+
+## 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
+  apiKey="tu-api-key"
+  cacheKey="uuid-del-mapa"
+  selectedSeats={selected}
+  onSeatClick={handleSeatClick}
+/>
+```
+
+---
+
+## 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:
+
+```js
+// Asientos/mesas
+[ST-Map] Seat click {
+  uuid: "58a5497e-eb75-445a-a89c-dc0fbe652d38",
+  price: 500,
+  row: "A",
+  column: 1,
+  category: "VIP",
+  section: "Sector 1"
+}
+
+// Secciones
+[ST-Map] Section click {
+  uuid: "3b1633c9-57d0-4438-b952-95c213f98e29",
+  price: 200,
+  category: "General",
+  section: "Sector 2"
+}
+```
+
+Si un campo no existe (ej. fila/columna en mesas), se muestra `"N/A"`. Sin precio se muestra `"sin precio"`.
+
+---
+
+## STMapClient
+
+Cliente HTTP para interactuar con la API de gestión de asientos. Funciona de forma independiente, sin necesidad del componente React.
+
+```js
+import { STMapClient } from "@infinitech.maps/st-map";
+
+const client = new STMapClient({ apiKey: "tu-api-key" });
+
+// O con URL personalizada:
+const client = new STMapClient({
+  apiKey: "tu-api-key",
+  baseUrl: "https://gateway.example.com",
+});
+```
+
+### `getMap(cacheKey, options?)`
+
+Carga el mapa desde la API.
+
+```js
+const map = await client.getMap("uuid-del-mapa");
+// Con versión específica:
+const map = await client.getMap("uuid-del-mapa", { version: "v1" });
+```
+
+### `reserve({ cacheKey, seatIds, ttlSeconds?, version? })`
+
+Reserva asientos. Estado → `"reserved"` con expiración.
+
+```js
+const reserved = await client.reserve({
+  cacheKey: "uuid-del-mapa",
+  seatIds: ["seat-1", "seat-2"],
+  ttlSeconds: 300, // 5 minutos (default)
+});
+// → [{ id: "seat-1", status: "reserved", expiredAt: "..." }, ...]
+```
+
+### `purchase({ cacheKey, seatIds, version? })`
+
+Compra asientos. Estado → `"purchased"` (permanente). Funciona sobre asientos vacantes o previamente reservados.
+
+```js
+const purchased = await client.purchase({
+  cacheKey: "uuid-del-mapa",
+  seatIds: ["seat-1"],
+});
+// → [{ id: "seat-1", status: "purchased" }]
+```
+
+### `release({ cacheKey, seatIds, version? })`
+
+Libera asientos. Estado → `"vacant"`. Idempotente: liberar un asiento ya vacante no genera error.
+
+```js
+await client.release({
+  cacheKey: "uuid-del-mapa",
+  seatIds: ["seat-2"],
+});
+// → [{ id: "seat-2", status: "vacant" }]
+```
+
+### `getSeatStatus({ cacheKey, seatIds?, version? })`
+
+Consulta el estado de asientos. Omitir `seatIds` devuelve **todos** los asientos del mapa.
+
+```js
+// Estado de asientos específicos
+const status = await client.getSeatStatus({
+  cacheKey: "uuid-del-mapa",
+  seatIds: ["seat-1", "seat-2"],
+});
+// → [{ id: "seat-1", status: "reserved", expiredAt: "..." }, ...]
+
+// Estado de todos los asientos
+const allStatus = await client.getSeatStatus({
+  cacheKey: "uuid-del-mapa",
+});
+```
+
+### Métodos estáticos
+
+#### `STMapClient.resolveReservationIds(element, quantity?)`
+
+Resuelve los IDs individuales de un elemento devuelto por `onSeatClick`. Para mesas, extrae los IDs de las sillas vacantes; para asientos, devuelve `[id]`.
+
+```js
+const ids = STMapClient.resolveReservationIds(clickedElement, 3);
+await client.reserve({ cacheKey: "uuid-del-mapa", seatIds: ids });
+```
+
+#### `STMapClient.vacantCount(element)`
+
+Devuelve la cantidad de asientos vacantes para un elemento. Asientos individuales devuelven `0` o `1`; mesas devuelven la cantidad de sillas vacantes.
+
+```js
+const available = STMapClient.vacantCount(clickedElement);
+console.log(`${available} lugares disponibles`);
+```