@nice2dev/spatial-core

Unified spatial/floor-plan/CAD core logic for Nice2Dev UI components.

Overview

@nice2dev/spatial-core provides framework-agnostic core functionality for spatial editing applications:

• Grid System — Snap-to-grid, alignment guides, intelligent snapping
• Spatial Objects — Unified object model for devices, furniture, network equipment
• Floor Plan Model — Walls, rooms, zones, layers, floors
• Measurement — Distance, angle, area calculations with unit conversion
• Serialization — .nsp.json format for saving/loading spatial documents

Installation

npm install @nice2dev/spatial-core
# or
pnpm add @nice2dev/spatial-core

Usage

Grid System

import { 
  snapToGrid, 
  generateAlignmentGuides, 
  performSnap,
  DEFAULT_GRID_CONFIG 
} from '@nice2dev/spatial-core/grid';

// Snap point to grid
const snapped = snapToGrid({ x: 123, y: 456 }, DEFAULT_GRID_CONFIG);

// Generate alignment guides while dragging
const guides = generateAlignmentGuides(draggedBounds, otherObjects, 10);

// Intelligent snap with multiple modes
const result = performSnap(mousePos, targetObjects, gridConfig);

Object Catalog

import { 
  OBJECT_CATALOG, 
  getCatalogByCategory, 
  searchCatalog 
} from '@nice2dev/spatial-core/objects';

// Get all smart home devices
const devices = getCatalogByCategory('smart-home');

// Search catalog
const results = searchCatalog('camera');

Floor Plan

import { 
  createFloorPlanDocument, 
  createFloor, 
  addObjectToLayer,
  calculatePolygonArea 
} from '@nice2dev/spatial-core/floor-plan';

// Create new floor plan
const doc = createFloorPlanDocument('My House', 'floor-plan');

// Add a floor
const floor = createFloor('Ground Floor', 0, { x: 0, y: 0, width: 20, height: 15 });
doc.floors.push(floor);

// Calculate room area
const area = calculatePolygonArea(roomBoundary);

Measurement

import { 
  distance2D, 
  polygonArea, 
  formatLength, 
  autoFormatArea,
  convertLength 
} from '@nice2dev/spatial-core/measurement';

// Calculate distance
const dist = distance2D({ x: 0, y: 0 }, { x: 3, y: 4 }); // 5

// Format with units
const formatted = autoFormatArea(150.5, 'metric'); // "150.50 m²"

// Convert units
const feet = convertLength(10, 'm', 'ft'); // 32.8084

Serialization

import { 
  serialize, 
  deserialize, 
  validate,
  downloadNSP,
  exportFloorToSVG 
} from '@nice2dev/spatial-core/serialization';

// Save document
const json = serialize(document, { pretty: true });

// Load document
const result = deserialize(jsonString);
if (result.success) {
  const doc = result.data;
}

// Validate
const validation = validate(document);
console.log(validation.errors, validation.warnings);

// Download as file
downloadNSP(document, 'my-floor-plan.nsp.json');

// Export to SVG
const svg = exportFloorToSVG(floor, { showGrid: true, showLabels: true });

Document Types

The .nsp.json format supports multiple document types:

| Type | Description | Use Case | |------|-------------|----------| | floor-plan | 2D floor plan | Smart home, building automation | | network-topology | Network diagram | IT infrastructure planning | | infrastructure | Data center layout | Server room, rack planning | | cad | Architectural CAD | Detailed building design | | interior | Interior design | Furniture placement | | game-scene | Game level/scene | Game development |

Object Categories

Unified catalog of placeable objects:

• smart-home — Lights, thermostats, cameras, sensors, locks
• furniture — Sofas, tables, beds, wardrobes, desks
• network — Routers, switches, servers, access points
• infrastructure — Racks, UPS, PDU, cooling units
• building — Walls, doors, windows, stairs
• game — Spawn points, triggers, pickups

License

MIT