@zonetrix/shared 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,395 @@
+# @zonetrix/shared
+
+Shared types, utilities, and validation helpers for the Zonetrix seat map ecosystem.
+
+## Overview
+
+`@zonetrix/shared` provides common type definitions, configuration utilities, and validation functions used across all Zonetrix packages. This package ensures type safety and consistency when working with seat map configurations.
+
+## Installation
+
+```bash
+npm install @zonetrix/shared
+# or
+yarn add @zonetrix/shared
+# or
+pnpm add @zonetrix/shared
+```
+
+## Features
+
+- 📘 **TypeScript-first** - Comprehensive type definitions for all seat map entities
+- ✅ **Validation** - Built-in configuration validation
+- 🔧 **Utilities** - Helper functions for config manipulation
+- 🎨 **Default Settings** - Pre-configured color schemes and settings
+- 📦 **Zero dependencies** - Lightweight and fast
+
+## Type Definitions
+
+### Core Types
+
+```typescript
+import {
+  SeatMapConfig,
+  SerializedSeat,
+  SerializedSection,
+  SerializedStage,
+  SeatState,
+  SeatShape,
+  ColorSettings,
+} from '@zonetrix/shared';
+```
+
+#### SeatState
+```typescript
+type SeatState = 'available' | 'reserved' | 'selected' | 'unavailable';
+```
+
+#### SeatShape
+```typescript
+type SeatShape = 'circle' | 'square' | 'rounded-square';
+```
+
+#### SerializedSeat
+```typescript
+interface SerializedSeat {
+  id: string;
+  position: { x: number; y: number };
+  shape: SeatShape;
+  state: SeatState;
+  sectionName?: string;
+  rowLabel?: string;
+  columnLabel?: string;
+  seatNumber?: string;
+  price?: number;
+}
+```
+
+#### ColorSettings
+```typescript
+interface ColorSettings {
+  canvasBackground: string;
+  stageColor: string;
+  seatAvailable: string;
+  seatReserved: string;
+  seatSelected: string;
+  seatUnavailable: string;
+  gridLines: string;
+  currency: string;
+}
+```
+
+#### SeatMapConfig
+```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[];
+}
+```
+
+## Utilities
+
+### Configuration Management
+
+#### createDefaultConfig
+Creates a new seat map configuration with default values.
+
+```typescript
+import { createDefaultConfig } from '@zonetrix/shared';
+
+const config = createDefaultConfig('Grand Theater');
+// Returns a complete SeatMapConfig with default settings
+```
+
+#### updateConfigTimestamp
+Updates the `updatedAt` timestamp in the configuration metadata.
+
+```typescript
+import { updateConfigTimestamp } from '@zonetrix/shared';
+
+const updatedConfig = updateConfigTimestamp(config);
+```
+
+#### cloneConfig
+Deep clones a seat map configuration.
+
+```typescript
+import { cloneConfig } from '@zonetrix/shared';
+
+const clonedConfig = cloneConfig(originalConfig);
+```
+
+### Seat State Management
+
+#### applySeatStateOverrides
+Applies seat state overrides (reserved/unavailable) to a configuration.
+
+```typescript
+import { applySeatStateOverrides } from '@zonetrix/shared';
+
+const updatedConfig = applySeatStateOverrides(
+  config,
+  ['A-1', 'A-2'], // reserved seats
+  ['B-5'] // unavailable seats
+);
+```
+
+#### getSelectedSeats
+Extracts all selected seats from a configuration.
+
+```typescript
+import { getSelectedSeats } from '@zonetrix/shared';
+
+const selectedSeats = getSelectedSeats(config);
+// Returns: SerializedSeat[]
+```
+
+### Statistics
+
+#### calculateCapacity
+Returns the total number of seats in the configuration.
+
+```typescript
+import { calculateCapacity } from '@zonetrix/shared';
+
+const totalSeats = calculateCapacity(config);
+```
+
+#### calculateAvailableSeats
+Returns the number of available seats.
+
+```typescript
+import { calculateAvailableSeats } from '@zonetrix/shared';
+
+const availableCount = calculateAvailableSeats(config);
+```
+
+### Import/Export
+
+#### exportConfigAsJSON
+Converts configuration to JSON string.
+
+```typescript
+import { exportConfigAsJSON } from '@zonetrix/shared';
+
+const jsonString = exportConfigAsJSON(config, true); // pretty print
+```
+
+#### importConfigFromJSON
+Parses JSON string into configuration object.
+
+```typescript
+import { importConfigFromJSON } from '@zonetrix/shared';
+
+const config = importConfigFromJSON(jsonString);
+```
+
+#### downloadConfigAsFile
+Downloads configuration as a JSON file (browser only).
+
+```typescript
+import { downloadConfigAsFile } from '@zonetrix/shared';
+
+downloadConfigAsFile(config, 'venue-config.json');
+```
+
+## Validation
+
+### validateSeatMapConfig
+Validates a seat map configuration and returns detailed results.
+
+```typescript
+import { validateSeatMapConfig } from '@zonetrix/shared';
+
+const result = validateSeatMapConfig(config);
+
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+
+if (result.warnings.length > 0) {
+  console.warn('Validation warnings:', result.warnings);
+}
+```
+
+**ValidationResult:**
+```typescript
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+```
+
+### Helper Functions
+
+#### generateId
+Generates a unique ID for seat map objects.
+
+```typescript
+import { generateId } from '@zonetrix/shared';
+
+const seatId = generateId('seat'); // e.g., "seat_1234567890_abc123def"
+```
+
+#### formatDate
+Formats a date for metadata fields.
+
+```typescript
+import { formatDate } from '@zonetrix/shared';
+
+const timestamp = formatDate(); // ISO 8601 format
+const customDate = formatDate(new Date('2024-01-01'));
+```
+
+## Constants
+
+### DEFAULT_COLORS
+Pre-configured default color scheme.
+
+```typescript
+import { DEFAULT_COLORS } from '@zonetrix/shared';
+
+console.log(DEFAULT_COLORS);
+// {
+//   canvasBackground: '#1a1a1a',
+//   stageColor: '#808080',
+//   seatAvailable: '#2C2B30',
+//   seatReserved: '#FCEA00',
+//   seatSelected: '#3A7DE5',
+//   seatUnavailable: '#6b7280',
+//   gridLines: '#404040',
+//   currency: 'KD'
+// }
+```
+
+## Usage Examples
+
+### Creating and Validating a Configuration
+
+```typescript
+import {
+  createDefaultConfig,
+  validateSeatMapConfig,
+  SerializedSeat,
+} from '@zonetrix/shared';
+
+// Create a new configuration
+const config = createDefaultConfig('Main Auditorium');
+
+// Add seats
+const seat: SerializedSeat = {
+  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,
+};
+
+config.seats.push(seat);
+
+// Validate
+const validation = validateSeatMapConfig(config);
+if (validation.valid) {
+  console.log('Configuration is valid!');
+}
+```
+
+### Managing Seat States
+
+```typescript
+import {
+  applySeatStateOverrides,
+  getSelectedSeats,
+  calculateAvailableSeats,
+} from '@zonetrix/shared';
+
+// Apply overrides from booking system
+const updatedConfig = applySeatStateOverrides(
+  config,
+  bookedSeats,
+  maintenanceSeats
+);
+
+// Get statistics
+const availableCount = calculateAvailableSeats(updatedConfig);
+console.log(`${availableCount} seats available`);
+
+// Get selected seats (for checkout)
+const selectedSeats = getSelectedSeats(updatedConfig);
+const totalPrice = selectedSeats.reduce((sum, seat) => sum + (seat.price || 0), 0);
+```
+
+### Export/Import Workflow
+
+```typescript
+import {
+  exportConfigAsJSON,
+  importConfigFromJSON,
+  downloadConfigAsFile,
+} from '@zonetrix/shared';
+
+// Export to JSON string
+const jsonString = exportConfigAsJSON(config);
+
+// Save to file (browser)
+downloadConfigAsFile(config, 'theater-layout.json');
+
+// Import from JSON
+const loadedConfig = importConfigFromJSON(jsonString);
+```
+
+## TypeScript Support
+
+This package is written in TypeScript and includes full type definitions. All types are exported for use in your applications.
+
+```typescript
+import type {
+  SeatMapConfig,
+  SerializedSeat,
+  SeatState,
+  ValidationResult,
+} from '@zonetrix/shared';
+```
+
+## Related Packages
+
+- **[@zonetrix/viewer](https://www.npmjs.com/package/@zonetrix/viewer)** - Lightweight React component for displaying seat maps
+
+## Contributing
+
+Contributions are welcome! Please ensure all changes include appropriate type definitions and pass validation tests.
+
+## License
+
+MIT
+
+## Author
+
+Fahad Khan ([@fahadkhan1740](https://github.com/fahadkhan1740))
+
+## Links
+
+- [npm Package](https://www.npmjs.com/package/@zonetrix/shared)
+- [GitHub Repository](https://github.com/fahadkhan1740/seat-map-studio)
+- [Documentation](https://github.com/fahadkhan1740/seat-map-studio#readme)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zonetrix/shared",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Shared types and utilities for seat-map-studio packages",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",