neogestify-ui-components 1.2.20 → 2.0.0

package/README.md

@@ -290,9 +290,359 @@ const modalRef = useRef<ModalRef>(null);
 </Modal>
 ```
 
-## Showcase / Demo
+---
+
+## VenueMapEditor
+
+Editor de mapas de recintos interactivo basado en SVG puro. Permite diseñar la planta de cualquier espacio (restaurantes, parqueaderos, estadios, oficinas, eventos, etc.) con herramientas de dibujo de paredes, colocación de objetos, múltiples plantas y sistema de librerías de elementos personalizados.
+
+### Importación
+
+```tsx
+import {
+  VenueMapEditor,  // editor completo
+  VenueMapViewer,  // modo solo lectura
+} from 'neogestify-ui-components/VenueMapEditor';
+
+// Tipos TypeScript
+import type {
+  VenueMap, Floor, MapElement,
+  ElementTypeDef, ElementGroup, ElementLibrary,
+  ElementStatus, VenueMapEditorProps,
+} from 'neogestify-ui-components/VenueMapEditor';
+```
+
+---
+
+### Uso básico
+
+El componente funciona sin ninguna prop — crea un mapa vacío con una planta por defecto:
+
+```tsx
+<VenueMapEditor />
+```
+
+Con configuración mínima:
+
+```tsx
+<VenueMapEditor
+  width="100%"
+  height="700px"
+  onChange={(map) => console.log('Mapa actualizado:', map)}
+/>
+```
+
+---
+
+### Cargar y guardar un mapa desde código
+
+El prop `initialMap` acepta un `VenueMap` (del estado de la app, de una API, de `localStorage`, etc.). Cuando el valor cambia por referencia, el editor reinicia su historial al nuevo mapa. El ciclo `onChange → initialMap` es **seguro** — el componente detecta el eco de su propio `onChange` y no genera bucles infinitos.
+
+```tsx
+import { useState, useEffect } from 'react';
+import { VenueMapEditor } from 'neogestify-ui-components/VenueMapEditor';
+import type { VenueMap } from 'neogestify-ui-components/VenueMapEditor';
+
+function App() {
+  const [map, setMap] = useState<VenueMap | undefined>();
+
+  // Carga asíncrona desde API
+  useEffect(() => {
+    fetch('/api/maps/1')
+      .then(r => r.json())
+      .then(setMap);
+  }, []);
+
+  // Guarda automáticamente en cada cambio
+  const handleChange = (updated: VenueMap) => {
+    setMap(updated);
+    fetch('/api/maps/1', {
+      method: 'PUT',
+      body: JSON.stringify(updated),
+    });
+  };
+
+  return (
+    <VenueMapEditor
+      initialMap={map}
+      onChange={handleChange}
+      height="600px"
+    />
+  );
+}
+```
+
+---
+
+### Props
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `initialMap` | `VenueMap` | mapa vacío | Mapa inicial. Se puede actualizar desde fuera para recargar el editor. |
+| `onChange` | `(map: VenueMap) => void` | — | Se llama en cada cambio del estado interno. |
+| `domainConfig` | `DomainConfig` | vacío | Tipos de elementos predefinidos disponibles en la paleta (opcional). |
+| `width` | `string \| number` | `'100%'` | Ancho del componente. |
+| `height` | `string \| number` | `'600px'` | Alto del componente. |
+| `gridSize` | `number` | `20` | Tamaño de la cuadrícula en unidades de canvas. |
+| `showGrid` | `boolean` | `true` | Mostrar/ocultar cuadrícula al iniciar. |
+| `snapToGrid` | `boolean` | `false` | Activar snap de elementos a la cuadrícula. |
+| `readOnly` | `boolean` | `false` | Modo lectura: no se puede editar pero sí hacer pan/zoom. |
+| `fixed` | `boolean` | `false` | Igual que `readOnly` pero además oculta la barra de herramientas. Pensado para el viewer en producción. |
+| `elementStatus` | `ElementStatus[]` | — | Array de estados visuales por elemento (libre, ocupado, reservado, deshabilitado). |
+| `onElementClick` | `(el: MapElement) => void` | — | Callback genérico al hacer click en cualquier elemento (en modo viewer). |
+| `onElementTypeClick` | `Record<string, (el: MapElement) => void>` | — | Callbacks por tipo de elemento. El tipo específico tiene prioridad sobre `onElementClick`. |
+
+---
+
+### Modo Viewer
+
+`VenueMapViewer` es un alias de `VenueMapEditor` con `fixed={true}`. Úsalo para mostrar el mapa en producción con elementos interactivos:
+
+```tsx
+import { VenueMapViewer } from 'neogestify-ui-components/VenueMapEditor';
+import type { ElementStatus } from 'neogestify-ui-components/VenueMapEditor';
+
+const estados: ElementStatus[] = [
+  { elementId: 'mesa-1', status: 'occupied' },
+  { elementId: 'mesa-2', status: 'free' },
+  { elementId: 'mesa-3', status: 'reserved' },
+  { elementId: 'spot-4', status: 'disabled' },
+];
+
+<VenueMapViewer
+  initialMap={myMap}
+  elementStatus={estados}
+  onElementTypeClick={{
+    // El key es el `id` del tipo definido en la librería JSON
+    TABLE_ROUND: (el) => abrirReserva(el.id),
+    TABLE_RECT:  (el) => abrirReserva(el.id),
+    PARKING_SPOT:(el) => asignarEspacio(el.id),
+  }}
+  // Fallback para tipos sin handler específico
+  onElementClick={(el) => console.log('click en', el.type, el.id)}
+/>
+```
+
+**Colores de estado:**
+
+| `status` | Color |
+|----------|-------|
+| `free` | Verde claro |
+| `occupied` | Rojo claro |
+| `reserved` | Amarillo |
+| `disabled` | Gris |
+
+---
+
+### Crear una librería de elementos (JSON)
+
+Los elementos que aparecen en la paleta del editor se definen en archivos JSON que el usuario carga desde el botón **⊞** (Cargar librería) de la barra de herramientas. Una vez cargada, la librería queda **embebida dentro del propio mapa** y se exporta junto a él — no se pierde al reabrir el archivo.
+
+#### Formato del JSON
+
+```json
+{
+  "grupoDeMesas": {
+    "name": "Mesas de restaurante",
+    "objects": [
+      {
+        "id": "TABLE_ROUND_2",
+        "label": "Mesa 2 pers.",
+        "shape": "circle",
+        "defaultWidth": 60,
+        "defaultHeight": 60,
+        "color": "#fef3c7",
+        "strokeColor": "#d97706"
+      },
+      {
+        "id": "TABLE_RECT_4",
+        "label": "Mesa 4 pers.",
+        "shape": "rect",
+        "defaultWidth": 110,
+        "defaultHeight": 70,
+        "color": "#fef3c7",
+        "strokeColor": "#d97706"
+      }
+    ]
+  },
+  "infraestructura": {
+    "name": "Infraestructura",
+    "objects": [
+      {
+        "id": "PILLAR",
+        "label": "Columna",
+        "shape": "circle",
+        "defaultWidth": 25,
+        "defaultHeight": 25,
+        "color": "#e5e7eb",
+        "strokeColor": "#6b7280"
+      },
+      {
+        "id": "ENTRANCE",
+        "label": "Entrada",
+        "shape": "arrow",
+        "defaultWidth": 80,
+        "defaultHeight": 30,
+        "color": "#dcfce7",
+        "strokeColor": "#16a34a"
+      }
+    ]
+  }
+}
+```
+
+#### Propiedades de cada objeto
+
+| Campo | Tipo | Descripción |
+|-------|------|-------------|
+| `id` | `string` | Identificador único del tipo. Debe ser **único en toda la librería**. Se usa como key en `onElementTypeClick`. |
+| `label` | `string` | Nombre visible en la paleta. |
+| `shape` | `"rect" \| "circle" \| "arrow"` | Forma del objeto en el canvas. |
+| `defaultWidth` | `number` | Ancho inicial al colocar el elemento (unidades de canvas ≈ píxeles a zoom 1×). |
+| `defaultHeight` | `number` | Alto inicial. |
+| `color` | `string` | Color de relleno (cualquier valor CSS: `#hex`, `rgb()`, `hsl()`, etc.). |
+| `strokeColor` | `string` | Color del borde. |
+
+#### Formas disponibles
+
+| `shape` | Descripción | Caso de uso típico |
+|---------|-------------|-------------------|
+| `rect` | Rectángulo | Mesas, espacios de parqueo, habitaciones |
+| `circle` | Elipse (círculo si `width === height`) | Mesas redondas, columnas, plantas |
+| `arrow` | Flecha apuntando a la derecha | Entradas, salidas, sentidos de circulación |
+
+#### Varios grupos en un archivo
+
+Un mismo archivo puede tener tantos grupos como necesites. Cada grupo aparece como una sección separada en la paleta. Se pueden cargar múltiples archivos — los grupos se acumulan. Cada grupo importado muestra un botón **×** para eliminarlo.
+
+```json
+{
+  "sillas":     { "name": "Sillas y asientos", "objects": [ ... ] },
+  "servicio":   { "name": "Zona de servicio",  "objects": [ ... ] },
+  "decoracion": { "name": "Decoración",         "objects": [ ... ] }
+}
+```
+
+#### Librería de ejemplo — Parqueadero
+
+```json
+{
+  "spots": {
+    "name": "Espacios",
+    "objects": [
+      { "id": "SPOT",        "label": "Normal",       "shape": "rect",   "defaultWidth": 60,  "defaultHeight": 120, "color": "#dbeafe", "strokeColor": "#3b82f6" },
+      { "id": "SPOT_DISCAP", "label": "Discapacidad", "shape": "rect",   "defaultWidth": 80,  "defaultHeight": 120, "color": "#dcfce7", "strokeColor": "#22c55e" },
+      { "id": "SPOT_EV",     "label": "Carga EV",     "shape": "rect",   "defaultWidth": 65,  "defaultHeight": 120, "color": "#d1fae5", "strokeColor": "#059669" },
+      { "id": "SPOT_MOTO",   "label": "Moto",         "shape": "rect",   "defaultWidth": 35,  "defaultHeight": 75,  "color": "#fef9c3", "strokeColor": "#eab308" }
+    ]
+  },
+  "circulacion": {
+    "name": "Circulación",
+    "objects": [
+      { "id": "ENTRANCE", "label": "Entrada", "shape": "arrow", "defaultWidth": 85, "defaultHeight": 35, "color": "#dcfce7", "strokeColor": "#16a34a" },
+      { "id": "EXIT",     "label": "Salida",  "shape": "arrow", "defaultWidth": 85, "defaultHeight": 35, "color": "#fee2e2", "strokeColor": "#dc2626" },
+      { "id": "LANE",     "label": "Carril",  "shape": "rect",  "defaultWidth": 300,"defaultHeight": 60,  "color": "#f3f4f6", "strokeColor": "#9ca3af" }
+    ]
+  }
+}
+```
+
+---
+
+### Modelo de datos TypeScript
+
+El estado del editor se serializa en un objeto `VenueMap`. Puedes guardarlo en tu base de datos como JSON y restaurarlo con `initialMap`.
+
+```
+VenueMap
+├── id: string
+├── name: string
+├── libraries?: ElementLibrary          ← librerías importadas (embebidas en el mapa)
+└── floors: Floor[]
+    ├── id: string
+    ├── name: string
+    ├── order: number
+    ├── area: FloorArea                 ← forma del piso (rect | polygon)
+    │   ├── shape: 'rect' | 'polygon'
+    │   ├── x?, y?, width?, height?    ← para shape: 'rect'
+    │   └── points?: [number,number][] ← para shape: 'polygon'
+    ├── wallNodes: WallNode[]           ← vértices del grafo de paredes
+    ├── walls: Wall[]                   ← segmentos de pared con grosor y material
+    └── elements: MapElement[]
+        ├── id: string
+        ├── type: string               ← id del ElementTypeDef de la librería
+        ├── x, y, width, height: number
+        ├── rotation: number           ← grados
+        ├── label?: string
+        └── metadata?: Record<string, unknown>  ← datos propios de tu app
+```
 
-Para ver todos los componentes en acción:
+El campo `metadata` en `MapElement` está disponible para que cada app guarde datos propios por elemento (ej. ID de reserva, capacidad, propietario, estado personalizado).
+
+```tsx
+// Ejemplo: guardar datos de negocio en metadata al crear elementos
+const handleClick = (el: MapElement) => {
+  // El metadata lo pone tu app, no el editor
+  const reservaId = el.metadata?.reservaId as string;
+  abrirModal(reservaId);
+};
+```
+
+---
+
+### Herramientas del editor
+
+| Tecla | Herramienta | Función |
+|-------|-------------|---------|
+| `V` | Seleccionar | Mover, redimensionar y rotar elementos. Arrastra el fondo del piso para moverlo. |
+| `H` | Desplazar | Pan del canvas con click izquierdo. |
+| `W` | Pared | Click fija el inicio; siguiente click termina el segmento (encadenado). Click derecho cancela. |
+| `P` | Colocar | Click en el piso coloca el elemento seleccionado en la paleta. |
+| `E` | Borrar | Click sobre un elemento o pared los elimina. |
+| `Esc` | — | Vuelve a Seleccionar. |
+| `Ctrl+Z / Y` | — | Deshacer / Rehacer. |
+| `Ctrl+D` | — | Duplicar selección. |
+| `Del / Backspace` | — | Eliminar selección. |
+| `+ / -` | — | Zoom in / out. |
+| Rueda ratón | — | Zoom centrado en el cursor. |
+| Click medio + drag | — | Pan del canvas en cualquier modo. |
+
+---
+
+### Gestión de plantas
+
+La barra de pestañas (visible incluso en viewer) permite:
+
+- **Click** → cambiar de planta activa
+- **Doble click** en el nombre → renombrar en línea
+- **◀ ▶** → reordenar la planta activa
+- **×** → eliminar la planta (mínimo 1)
+- **+** → añadir nueva planta
+
+---
+
+### Forma del piso (Rect vs Polígono)
+
+El botón **Rect / Poly** de la barra de herramientas alterna entre:
+
+- **Rect**: rectángulo con 8 handles de redimensión en los bordes y esquinas.
+- **Poly**: polígono libre. Arrastra los vértices (cuadrados azules). Click en el diamante central de una arista añade un vértice. Doble-click en un vértice lo elimina (mínimo 3).
+
+Los elementos y paredes siempre se mantienen dentro del piso al moverlos o colocarlos.
+
+---
+
+### Exportar / Importar el mapa
+
+| Botón | Función |
+|-------|---------|
+| ⬇ Exportar mapa | Descarga el estado actual como `.json` (incluye las librerías embebidas). |
+| ⬆ Importar mapa | Carga un `.json` exportado previamente, reemplazando el mapa actual. |
+| ⊞ Cargar librería | Carga un `.json` de elementos y añade sus grupos a la paleta sin reemplazar los existentes. |
+
+---
+
+## Showcase / Demo
 
 ```bash
 cd showcase

package/dist/components/VenueMapEditor/index.d.mts

@@ -0,0 +1,202 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+import { WheelEvent, MouseEvent } from 'react';
+
+type WallMaterial = 'concrete' | 'brick' | 'glass' | 'drywall' | 'wood';
+type AreaShape = 'rect' | 'polygon';
+type ElementShape = 'rect' | 'circle' | 'arrow' | 'path';
+type ToolMode = 'SELECT' | 'WALL' | 'PLACE' | 'PAN' | 'ERASE';
+interface WallNode {
+    id: string;
+    x: number;
+    y: number;
+}
+interface Wall {
+    id: string;
+    nodeAId: string;
+    nodeBId: string;
+    /** Thickness in canvas px */
+    thickness: number;
+    material: WallMaterial;
+}
+interface MapElement {
+    id: string;
+    /** e.g. 'TABLE_ROUND', 'PARKING_SPOT', 'DOOR' */
+    type: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Rotation in degrees */
+    rotation: number;
+    label?: string;
+    metadata?: Record<string, unknown>;
+}
+interface FloorArea {
+    shape: AreaShape;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    points?: [number, number][];
+}
+interface Floor {
+    id: string;
+    name: string;
+    order: number;
+    area: FloorArea;
+    wallNodes: WallNode[];
+    walls: Wall[];
+    elements: MapElement[];
+}
+interface VenueMap {
+    id: string;
+    name: string;
+    floors: Floor[];
+    /** Custom element libraries imported by the user; persisted with the map. */
+    libraries?: ElementLibrary;
+}
+interface ElementTypeDef {
+    id: string;
+    label: string;
+    shape: ElementShape;
+    defaultWidth: number;
+    defaultHeight: number;
+    /** SVG fill color */
+    color: string;
+    strokeColor: string;
+    /** Emoji or icon name */
+    icon?: string;
+    /**
+     * Raw SVG path `d` attribute for `shape === 'path'`.
+     * Define the path in the coordinate space of `viewBox` (default `"0 0 100 100"`).
+     * It will be automatically scaled to fit the element's `width × height` bounding box.
+     *
+     * @example
+     * // A 5-pointed star in a 100×100 viewBox
+     * svgPath: "M50 5 L61 35 L95 35 L68 57 L79 91 L50 70 L21 91 L32 57 L5 35 L39 35 Z"
+     */
+    svgPath?: string;
+    /**
+     * ViewBox for `svgPath`. Format: `"minX minY width height"`.
+     * Defaults to `"0 0 100 100"` when omitted.
+     */
+    viewBox?: string;
+}
+interface DomainConfig {
+    id: string;
+    name: string;
+    elementTypes: ElementTypeDef[];
+}
+interface ElementGroup {
+    name: string;
+    objects: ElementTypeDef[];
+}
+/** A library JSON file: top-level keys are group IDs. */
+type ElementLibrary = Record<string, ElementGroup>;
+interface ElementStatus {
+    elementId: string;
+    status: 'free' | 'occupied' | 'reserved' | 'disabled';
+    tooltip?: string;
+}
+interface VenueMapEditorProps {
+    /**
+     * Optional built-in element type catalog.
+     * If omitted the palette is empty until the user imports a library JSON.
+     */
+    domainConfig?: DomainConfig;
+    /**
+     * Map to render. When this prop changes (by reference) from outside the
+     * component, the editor resets its history to the new map — allowing the
+     * parent to hydrate the editor from an API or local storage without causing
+     * a render loop (changes made inside the editor that are echoed back via
+     * `onChange` are detected and ignored).
+     */
+    initialMap?: VenueMap;
+    /** Called every time the internal map state changes. */
+    onChange?: (map: VenueMap) => void;
+    width?: string | number;
+    height?: string | number;
+    gridSize?: number;
+    showGrid?: boolean;
+    snapToGrid?: boolean;
+    readOnly?: boolean;
+    /** Viewer-only mode: pan and zoom are allowed but nothing can be edited. */
+    fixed?: boolean;
+    elementStatus?: ElementStatus[];
+    onElementClick?: (element: MapElement) => void;
+    /**
+     * Per-type click handlers active in viewer/fixed mode.
+     * Keys are element type IDs (e.g. `'TABLE_ROUND'`).
+     * When an element is clicked, its type-specific handler fires first;
+     * if none is registered, `onElementClick` is used as fallback.
+     *
+     * @example
+     * ```tsx
+     * <VenueMapViewer
+     *   onElementTypeClick={{
+     *     TABLE_ROUND: (el) => openReservation(el.id),
+     *     CHAIR:       (el) => showInfo(el),
+     *   }}
+     * />
+     * ```
+     */
+    onElementTypeClick?: Record<string, (element: MapElement) => void>;
+}
+type VenueMapViewerProps = VenueMapEditorProps;
+
+declare function VenueMapEditor({ domainConfig, initialMap, onChange, width, height, gridSize, showGrid: showGridProp, snapToGrid: snapEnabled, readOnly, fixed, elementStatus, onElementClick, onElementTypeClick, }: VenueMapEditorProps): react_jsx_runtime.JSX.Element;
+
+declare function VenueMapViewer({ elementStatus, onElementClick, ...rest }: VenueMapViewerProps): react_jsx_runtime.JSX.Element;
+
+interface PaletteGroup {
+    id: string;
+    name: string;
+    /** True for the built-in domain config group; false for imported library groups. */
+    isBase?: boolean;
+    types: ElementTypeDef[];
+}
+
+interface PanZoomState {
+    panX: number;
+    panY: number;
+    zoom: number;
+}
+declare function usePanZoom(initialZoom?: number, leftClickPan?: boolean): {
+    state: PanZoomState;
+    setState: React.Dispatch<React.SetStateAction<PanZoomState>>;
+    isPanning: boolean;
+    handleWheel: (e: WheelEvent<SVGSVGElement>) => void;
+    handleMouseDown: (e: MouseEvent<SVGSVGElement>) => void;
+    handleMouseMove: (e: MouseEvent<SVGSVGElement>) => void;
+    handleMouseUp: (_e: MouseEvent<SVGSVGElement>) => void;
+    handleMouseLeave: () => void;
+    zoomBy: (factor: number, cx?: number, cy?: number) => void;
+    resetView: () => void;
+};
+
+/** Generates a globally-unique id using the Web Crypto API. */
+declare const genId: () => string;
+
+/** Snap a single value to the nearest grid line. */
+declare const snapToGrid: (value: number, gridSize: number) => number;
+/** Snap a 2-D point to the grid if `enabled`, otherwise return it unchanged. */
+declare const snapPoint: (x: number, y: number, gridSize: number, enabled: boolean) => {
+    x: number;
+    y: number;
+};
+/**
+ * Find the closest WallNode within `threshold` canvas units.
+ * Returns the node's id and position, or null when nothing is close enough.
+ */
+declare const findNearestNode: (x: number, y: number, nodes: Array<{
+    id: string;
+    x: number;
+    y: number;
+}>, threshold: number) => {
+    id: string;
+    x: number;
+    y: number;
+} | null;
+
+export { type AreaShape, type DomainConfig, type ElementGroup, type ElementLibrary, type ElementShape, type ElementStatus, type ElementTypeDef, type Floor, type FloorArea, type MapElement, type PaletteGroup, type PanZoomState, type ToolMode, type VenueMap, VenueMapEditor, type VenueMapEditorProps, VenueMapViewer, type VenueMapViewerProps, type Wall, type WallMaterial, type WallNode, findNearestNode, genId, snapPoint, snapToGrid, usePanZoom };