@zonetrix/viewer 1.0.0 → 1.1.0

package/README.md

@@ -1,15 +1,22 @@
 # @zonetrix/viewer
 
-Lightweight React component for rendering interactive seat maps. Perfect for booking systems, event ticketing, and venue management.
+Lightweight React component for rendering interactive seat maps in your booking applications, event ticketing systems, and venue management platforms.
+
+## Overview
+
+`@zonetrix/viewer` is a production-ready React component that renders beautiful, interactive seat maps with support for selection, zooming, and real-time state updates. Perfect for theaters, stadiums, cinemas, and event venues.
 
 ## Features
 
-- 🎯 **Read-only rendering** - Display seat maps without editing capabilities
-- 🔄 **Interactive selection** - Click seats to select/deselect
-- 🌐 **API integration** - Load configs from JSON file or API endpoint
-- 🎨 **Customizable** - Override colors and styles
-- 📱 **Responsive** - Works on all screen sizes
-- ⚡ **Lightweight** - Minimal dependencies, small bundle size
+- 🎯 **Read-only Display** - Optimized for end-user viewing and selection
+- 🖱️ **Interactive Selection** - Click seats to select/deselect with visual feedback
+- 🔄 **Real-time Updates** - Support for dynamic seat state changes
+- 🌐 **Flexible Config Loading** - Load from JSON files or API endpoints
+- 🔍 **Mouse Wheel Zoom** - Smooth zoom with configurable limits
+- 🎨 **Customizable Colors** - Override default colors to match your brand
+- 📱 **Responsive** - Works seamlessly across all screen sizes
+- ⚡ **Lightweight** - Minimal dependencies (~95KB gzipped)
+- 🔒 **Type-safe** - Full TypeScript support
 
 ## Installation
 
@@ -21,18 +28,24 @@ yarn add @zonetrix/viewer
 pnpm add @zonetrix/viewer
 ```
 
-## Usage
+### Peer Dependencies
+
+```bash
+npm install react react-dom
+```
+
+## Quick Start
 
-### Basic Example (with JSON file)
+### Basic Usage with JSON Config
 
 ```tsx
 import { SeatMapViewer } from '@zonetrix/viewer';
-import config from './my-venue-config.json';
+import venueConfig from './venue-config.json';
 
-function App() {
+function BookingApp() {
   return (
     <SeatMapViewer
-      config={config}
+      config={venueConfig}
       onSeatSelect={(seat) => console.log('Selected:', seat)}
       onSeatDeselect={(seat) => console.log('Deselected:', seat)}
     />
@@ -40,90 +53,237 @@ function App() {
 }
 ```
 
-### With API URL
+### Load Config from API
+
+```tsx
+import { SeatMapViewer } from '@zonetrix/viewer';
+
+function BookingApp() {
+  return (
+    <SeatMapViewer
+      configUrl="https://api.example.com/venues/123/config"
+      onSeatSelect={(seat) => addToCart(seat)}
+      onSeatDeselect={(seat) => removeFromCart(seat)}
+    />
+  );
+}
+```
+
+## Props API
+
+### SeatMapViewerProps
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `SeatMapConfig` | No* | Seat map configuration object |
+| `configUrl` | `string` | No* | URL to fetch configuration from |
+| `reservedSeats` | `string[]` | No | Array of seat IDs/numbers to mark as reserved |
+| `unavailableSeats` | `string[]` | No | Array of seat IDs/numbers to mark as unavailable |
+| `onSeatSelect` | `(seat: SeatData) => void` | No | Callback when a seat is selected |
+| `onSeatDeselect` | `(seat: SeatData) => void` | No | Callback when a seat is deselected |
+| `onSelectionChange` | `(seats: SeatData[]) => void` | No | Callback when selection changes |
+| `colorOverrides` | `Partial<ColorSettings>` | No | Custom colors for seat states |
+| `zoomEnabled` | `boolean` | No | Enable/disable mouse wheel zoom (default: true) |
+| `showSelectedCount` | `boolean` | No | Show selected seats counter (default: true) |
+
+*Note: Either `config` or `configUrl` must be provided.
+
+## Usage Examples
+
+### 1. Booking System with Cart
+
+```tsx
+import { useState } from 'react';
+import { SeatMapViewer } from '@zonetrix/viewer';
+import type { SeatData } from '@zonetrix/viewer';
+
+function TheaterBooking() {
+  const [cart, setCart] = useState<SeatData[]>([]);
+
+  const handleSeatSelect = (seat: SeatData) => {
+    setCart((prev) => [...prev, seat]);
+  };
+
+  const handleSeatDeselect = (seat: SeatData) => {
+    setCart((prev) => prev.filter((s) => s.seatNumber !== seat.seatNumber));
+  };
+
+  const totalPrice = cart.reduce((sum, seat) => sum + (seat.price || 0), 0);
+
+  return (
+    <div>
+      <SeatMapViewer
+        configUrl="https://api.theater.com/venues/main-hall/config"
+        reservedSeats={['A-1', 'A-2', 'B-5']}
+        onSeatSelect={handleSeatSelect}
+        onSeatDeselect={handleSeatDeselect}
+      />
+
+      <div className="cart">
+        <h3>Your Selection</h3>
+        <p>Seats: {cart.map(s => s.seatNumber).join(', ')}</p>
+        <p>Total: ${totalPrice.toFixed(2)}</p>
+        <button onClick={() => checkout(cart)}>Proceed to Checkout</button>
+      </div>
+    </div>
+  );
+}
+```
+
+### 2. Custom Colors (Brand Matching)
 
 ```tsx
 import { SeatMapViewer } from '@zonetrix/viewer';
 
-function App() {
+function BrandedVenue() {
+  const customColors = {
+    seatAvailable: '#10b981',    // Green
+    seatReserved: '#ef4444',     // Red
+    seatSelected: '#3b82f6',     // Blue
+    canvasBackground: '#ffffff', // White
+  };
+
   return (
     <SeatMapViewer
-      configUrl="https://api.example.com/venue/123/config"
+      config={venueConfig}
+      colorOverrides={customColors}
       onSeatSelect={(seat) => console.log('Selected:', seat)}
     />
   );
 }
 ```
 
-### With Seat State Overrides
+### 3. Real-time Updates from API
 
 ```tsx
-import { SeatMapViewer } from '@seat-map-studio/viewer';
+import { useState, useEffect } from 'react';
+import { SeatMapViewer } from '@zonetrix/viewer';
+
+function LiveEventSeating() {
+  const [reservedSeats, setReservedSeats] = useState<string[]>([]);
+
+  // Poll API every 5 seconds for reserved seats
+  useEffect(() => {
+    const interval = setInterval(async () => {
+      const response = await fetch('/api/venue/123/reserved-seats');
+      const data = await response.json();
+      setReservedSeats(data.reserved);
+    }, 5000);
 
-function App() {
-  const [reservedSeats, setReservedSeats] = useState(['A-1', 'A-2', 'B-5']);
-  const [unavailableSeats] = useState(['C-1']);
+    return () => clearInterval(interval);
+  }, []);
 
   return (
     <SeatMapViewer
-      config={config}
+      config={venueConfig}
       reservedSeats={reservedSeats}
-      unavailableSeats={unavailableSeats}
-      onSeatSelect={(seat) => {
-        // Handle seat selection
-      }}
+      onSeatSelect={(seat) => bookSeat(seat)}
     />
   );
 }
 ```
 
-### Custom Colors
+### 4. Tracking Selection Changes
 
 ```tsx
-import { SeatMapViewer } from '@seat-map-studio/viewer';
+import { SeatMapViewer } from '@zonetrix/viewer';
+
+function SelectionTracker() {
+  const handleSelectionChange = (selectedSeats) => {
+    console.log('Current selection:', selectedSeats);
+
+    // Update analytics
+    analytics.track('Seats Selected', {
+      count: selectedSeats.length,
+      seats: selectedSeats.map(s => s.seatNumber),
+    });
+  };
 
-function App() {
   return (
     <SeatMapViewer
-      config={config}
-      colorOverrides={{
-        seatAvailable: '#00ff00',
-        seatSelected: '#0000ff',
-        seatReserved: '#ffff00',
-        seatUnavailable: '#ff0000',
-      }}
+      config={venueConfig}
+      onSelectionChange={handleSelectionChange}
     />
   );
 }
 ```
 
-## API Reference
+### 5. Disable Zoom for Mobile
 
-### Props
+```tsx
+import { SeatMapViewer } from '@zonetrix/viewer';
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `config` | `SeatMapConfig` | - | Seat map configuration object |
-| `configUrl` | `string` | - | URL to fetch configuration from |
-| `reservedSeats` | `string[]` | `[]` | Array of seat IDs/numbers to mark as reserved |
-| `unavailableSeats` | `string[]` | `[]` | Array of seat IDs/numbers to mark as unavailable |
-| `onSeatSelect` | `(seat: SeatData) => void` | - | Called when a seat is selected |
-| `onSeatDeselect` | `(seat: SeatData) => void` | - | Called when a seat is deselected |
-| `onSelectionChange` | `(seats: SeatData[]) => void` | - | Called when selection changes |
-| `colorOverrides` | `Partial<ColorSettings>` | - | Custom color overrides |
-| `showTooltip` | `boolean` | `true` | Show tooltip on hover |
-| `zoomEnabled` | `boolean` | `true` | Enable mouse wheel zoom |
-| `className` | `string` | `''` | Additional CSS classes |
-| `onConfigLoad` | `(config: SeatMapConfig) => void` | - | Called when config is loaded |
-| `onError` | `(error: Error) => void` | - | Called on error |
+function MobileOptimized() {
+  const isMobile = window.innerWidth < 768;
+
+  return (
+    <SeatMapViewer
+      config={venueConfig}
+      zoomEnabled={!isMobile}
+      onSeatSelect={(seat) => handleSelection(seat)}
+    />
+  );
+}
+```
+
+## Configuration Format
+
+The viewer accepts a `SeatMapConfig` object. You can create these configurations using our creator studio or build them programmatically.
+
+### Example Configuration
+
+```json
+{
+  "version": "1.0.0",
+  "metadata": {
+    "name": "Main Auditorium",
+    "venue": "Grand Theater",
+    "capacity": 500,
+    "createdAt": "2025-01-01T00:00:00Z",
+    "updatedAt": "2025-01-01T00:00:00Z"
+  },
+  "canvas": {
+    "width": 1200,
+    "height": 800,
+    "backgroundColor": "#1a1a1a"
+  },
+  "colors": {
+    "canvasBackground": "#1a1a1a",
+    "stageColor": "#808080",
+    "seatAvailable": "#2C2B30",
+    "seatReserved": "#FCEA00",
+    "seatSelected": "#3A7DE5",
+    "seatUnavailable": "#6b7280",
+    "gridLines": "#404040",
+    "currency": "USD"
+  },
+  "seats": [
+    {
+      "id": "seat_001",
+      "position": { "x": 100, "y": 100 },
+      "shape": "rounded-square",
+      "state": "available",
+      "sectionName": "Orchestra",
+      "rowLabel": "A",
+      "columnLabel": "1",
+      "seatNumber": "A-1",
+      "price": 50.00
+    }
+  ],
+  "sections": [],
+  "stages": []
+}
+```
 
-### Types
+## TypeScript Types
+
+### SeatData
 
-#### SeatData
 ```typescript
 interface SeatData {
-  seatState: 'available' | 'reserved' | 'selected' | 'unavailable';
-  shape?: 'circle' | 'square' | 'rounded-square';
+  id: string;
+  state: SeatState;
+  shape?: SeatShape;
   sectionName?: string;
   rowLabel?: string;
   columnLabel?: string;
@@ -132,34 +292,160 @@ interface SeatData {
 }
 ```
 
-#### SeatMapConfig
+### SeatState
+
 ```typescript
-interface SeatMapConfig {
-  version: string;
-  metadata: {
-    name: string;
-    description?: string;
-    createdAt: string;
-    updatedAt: string;
-    venue?: string;
-    capacity?: number;
-  };
-  canvas: {
-    width: number;
-    height: number;
-    backgroundColor: string;
-  };
-  colors: ColorSettings;
-  seats: SerializedSeat[];
-  sections?: SerializedSection[];
-  stages?: SerializedStage[];
+type SeatState = 'available' | 'reserved' | 'selected' | 'unavailable';
+```
+
+### SeatShape
+
+```typescript
+type SeatShape = 'circle' | 'square' | 'rounded-square';
+```
+
+### ColorSettings
+
+```typescript
+interface ColorSettings {
+  canvasBackground: string;
+  stageColor: string;
+  seatAvailable: string;
+  seatReserved: string;
+  seatSelected: string;
+  seatUnavailable: string;
+  gridLines: string;
+  currency: string;
 }
 ```
 
-## Creating Seat Map Configs
+## Seat States Explained
 
-Use [@seat-map-studio/creator](../creator) to visually design and export seat map configurations.
+| State | Description | User Can Select? | Visual |
+|-------|-------------|------------------|--------|
+| `available` | Seat is free and can be selected | ✅ Yes | Default color |
+| `reserved` | Seat is booked by another user | ❌ No | Yellow/Warning color |
+| `selected` | Seat is selected by current user | ✅ Yes (to deselect) | Primary/Blue color |
+| `unavailable` | Seat is blocked (maintenance, etc.) | ❌ No | Gray color |
+
+## Events & Callbacks
+
+### onSeatSelect
+
+Called when a user selects an available seat.
+
+```typescript
+const handleSelect = (seat: SeatData) => {
+  console.log('Seat selected:', seat.seatNumber);
+  console.log('Price:', seat.price);
+  console.log('Section:', seat.sectionName);
+};
+```
+
+### onSeatDeselect
+
+Called when a user deselects a previously selected seat.
+
+```typescript
+const handleDeselect = (seat: SeatData) => {
+  console.log('Seat deselected:', seat.seatNumber);
+};
+```
+
+### onSelectionChange
+
+Called whenever the selection changes (includes all selected seats).
+
+```typescript
+const handleSelectionChange = (selectedSeats: SeatData[]) => {
+  console.log('Total selected:', selectedSeats.length);
+  const total = selectedSeats.reduce((sum, s) => sum + (s.price || 0), 0);
+  console.log('Total price:', total);
+};
+```
+
+## Styling
+
+The component uses inline styles generated from the configuration. To customize the container, wrap it in a styled div:
+
+```tsx
+<div style={{ width: '100%', height: '600px', border: '1px solid #ccc' }}>
+  <SeatMapViewer config={venueConfig} />
+</div>
+```
+
+## Performance Tips
+
+1. **Large Venues** (500+ seats): Consider splitting into sections
+2. **API Loading**: Show a loading spinner while `configUrl` is being fetched
+3. **Mobile**: Disable zoom on mobile devices for better UX
+4. **Memoization**: Wrap callbacks with `useCallback` to prevent unnecessary re-renders
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Common Issues
+
+### Configuration not loading from API
+
+Ensure your API returns valid JSON and has proper CORS headers:
+
+```javascript
+// Server-side (Express example)
+res.setHeader('Access-Control-Allow-Origin', '*');
+res.json(seatMapConfig);
+```
+
+### Seats not responding to clicks
+
+Make sure seat states are correctly set. Only `available` and `selected` seats can be clicked.
+
+### Canvas size issues
+
+The canvas size is determined by the `canvas.width` and `canvas.height` in your configuration. Adjust these values or wrap the component in a responsive container.
+
+## Related Packages
+
+- **[@zonetrix/shared](https://www.npmjs.com/package/@zonetrix/shared)** - Shared types and utilities
+
+## Examples Repository
+
+Check out our [examples repository](https://github.com/fahadkhan1740/seat-map-studio/tree/main/examples) for more use cases:
+
+- Booking system integration
+- API polling for real-time updates
+- Custom theming
+- Mobile-optimized layouts
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
 
 ## License
 
 MIT
+
+## Author
+
+Fahad Khan ([@fahadkhan1740](https://github.com/fahadkhan1740))
+
+## Links
+
+- [npm Package](https://www.npmjs.com/package/@zonetrix/viewer)
+- [GitHub Repository](https://github.com/fahadkhan1740/seat-map-studio)
+- [Documentation](https://github.com/fahadkhan1740/seat-map-studio#readme)
+- [Issue Tracker](https://github.com/fahadkhan1740/seat-map-studio/issues)
+
+## Support
+
+For questions and support:
+- Open an [issue on GitHub](https://github.com/fahadkhan1740/seat-map-studio/issues)
+- Email: fahadkhan1740@outlook.com
+
+---
+
+**Made with ❤️ by Fahad Khan**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zonetrix/viewer",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Lightweight React component for rendering interactive seat maps",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",