@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

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
• 🏢 Multi-floor Support - Organize seats and stages across multiple floors
• 👁️ Hidden Seats - Support for hidden/invisible seats in layouts
• 📦 Zero dependencies - Lightweight and fast

Type Definitions

Core Types

import {
  SeatMapConfig,
  SerializedSeat,
  SerializedSection,
  SerializedStage,
  SeatState,
  SeatShape,
  ColorSettings,
  FloorConfig,
} from '@zonetrix/shared';

SeatState

type SeatState = 'available' | 'reserved' | 'selected' | 'unavailable' | 'hidden';

SeatShape

type SeatShape = 'circle' | 'square' | 'rounded-square';

SerializedSeat

interface SerializedSeat {
  id: string;
  position: { x: number; y: number };
  shape: SeatShape;
  state: SeatState;
  sectionName?: string;
  rowLabel?: string;
  columnLabel?: string;
  seatNumber?: string;
  price?: number;
  floorId?: string; // Floor reference for multi-floor venues
}

ColorSettings

interface ColorSettings {
  canvasBackground: string;
  stageColor: string;
  seatAvailable: string;
  seatReserved: string;
  seatSelected: string;
  seatUnavailable: string;
  seatHidden: string;
  gridLines: string;
  currency: string;
}

FloorConfig

interface FloorConfig {
  id: string;
  name: string;
  order: number;
  color?: string;
}

SeatMapConfig

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[];
  floors?: FloorConfig[]; // Multi-floor venue support
}

Utilities

Configuration Management

createDefaultConfig

Creates a new seat map configuration with default values.

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.

import { updateConfigTimestamp } from '@zonetrix/shared';

const updatedConfig = updateConfigTimestamp(config);

cloneConfig

Deep clones a seat map configuration.

import { cloneConfig } from '@zonetrix/shared';

const clonedConfig = cloneConfig(originalConfig);

Seat State Management

applySeatStateOverrides

Applies seat state overrides (reserved/unavailable) to a configuration.

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.

import { getSelectedSeats } from '@zonetrix/shared';

const selectedSeats = getSelectedSeats(config);
// Returns: SerializedSeat[]

Statistics

calculateCapacity

Returns the total number of seats in the configuration.

import { calculateCapacity } from '@zonetrix/shared';

const totalSeats = calculateCapacity(config);

calculateAvailableSeats

Returns the number of available seats.

import { calculateAvailableSeats } from '@zonetrix/shared';

const availableCount = calculateAvailableSeats(config);

Import/Export

exportConfigAsJSON

Converts configuration to JSON string.

import { exportConfigAsJSON } from '@zonetrix/shared';

const jsonString = exportConfigAsJSON(config, true); // pretty print

importConfigFromJSON

Parses JSON string into configuration object.

import { importConfigFromJSON } from '@zonetrix/shared';

const config = importConfigFromJSON(jsonString);

downloadConfigAsFile

Downloads configuration as a JSON file (browser only).

import { downloadConfigAsFile } from '@zonetrix/shared';

downloadConfigAsFile(config, 'venue-config.json');

Validation

validateSeatMapConfig

Validates a seat map configuration and returns detailed results.

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:

interface ValidationResult {
  valid: boolean;
  errors: string[];
  warnings: string[];
}

Helper Functions

generateId

Generates a unique ID for seat map objects.

import { generateId } from '@zonetrix/shared';

const seatId = generateId('seat'); // e.g., "seat_1234567890_abc123def"

formatDate

Formats a date for metadata fields.

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.

import { DEFAULT_COLORS } from '@zonetrix/shared';

console.log(DEFAULT_COLORS);
// {
//   canvasBackground: '#1a1a1a',
//   stageColor: '#808080',
//   seatAvailable: '#2C2B30',
//   seatReserved: '#FCEA00',
//   seatSelected: '#3A7DE5',
//   seatUnavailable: '#6b7280',
//   seatHidden: '#4a4a4a',
//   gridLines: '#404040',
//   currency: 'KD'
// }

Usage Examples

Creating and Validating a Configuration

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

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

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.

import type {
  SeatMapConfig,
  SerializedSeat,
  SeatState,
  ValidationResult,
} from '@zonetrix/shared';

Related Packages

• @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)

Links

• npm Package
• GitHub Repository
• Documentation