vehicle-path2 1.0.0

package/dist/react/hooks/useAnimation.d.ts

@@ -0,0 +1,43 @@
+import type { Line } from '../../core/types/geometry';
+import type { Vehicle, GotoCommand } from '../../core/types/vehicle';
+import type { TangentMode } from '../../core/types/config';
+import type { VehicleEventEmitter } from '../../utils/event-emitter';
+export interface UseAnimationProps {
+    vehicles: Vehicle[];
+    lines: Line[];
+    vehicleQueues: Map<string, GotoCommand[]>;
+    wheelbase: number;
+    tangentMode: TangentMode;
+    curves: import('../../core/types/geometry').Curve[];
+    eventEmitter?: VehicleEventEmitter;
+}
+/**
+ * Hook for running vehicle animation/simulation.
+ *
+ * This hook handles the actual movement of vehicles along paths.
+ * Call prepare() before starting, then tick() in your animation loop.
+ *
+ * @example
+ * ```typescript
+ * const { movingVehicles, prepare, tick, reset, isMoving } = useAnimation({
+ *   vehicles, lines, vehicleQueues, wheelbase: 30, tangentMode: 'proportional-40', curves
+ * })
+ *
+ * // Start animation
+ * prepare()
+ *
+ * // In animation loop
+ * const animate = () => {
+ *   if (tick(5)) requestAnimationFrame(animate)
+ * }
+ * ```
+ */
+export declare function useAnimation({ vehicles, lines, vehicleQueues, wheelbase, tangentMode, curves, eventEmitter }: UseAnimationProps): {
+    movingVehicles: Vehicle[];
+    prepare: () => boolean;
+    tick: (distance: number) => boolean;
+    reset: () => void;
+    continueVehicle: (vehicleId: string) => boolean;
+    isMoving: () => boolean;
+    isPrepared: boolean;
+};

package/dist/react/hooks/useMovementQueue.d.ts

@@ -0,0 +1,52 @@
+import type { Line, Curve } from '../../core/types/geometry';
+import type { Vehicle, GotoCommand } from '../../core/types/vehicle';
+import type { GotoCommandInput } from '../../core/types/api';
+export interface UseMovementQueueProps {
+    vehicles: Vehicle[];
+    lines: Line[];
+    curves: Curve[];
+}
+export interface UseMovementQueueResult {
+    /** Queue of commands per vehicle */
+    vehicleQueues: Map<string, GotoCommand[]>;
+    /** Queue a movement command for a vehicle */
+    queueMovement: (vehicleId: string, input: GotoCommandInput) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Clear the queue for a specific vehicle or all vehicles */
+    clearQueue: (vehicleId?: string) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Any error from the last operation */
+    error: string | null;
+    /** @internal Load pre-computed queues directly (for bulk loading) */
+    _loadQueues: (queues: Map<string, GotoCommand[]>) => void;
+}
+/**
+ * Hook for managing the queue of movement commands.
+ *
+ * This hook provides a simple API for queuing goto commands at runtime.
+ *
+ * @example
+ * ```typescript
+ * const { vehicleQueues, queueMovement, clearQueue } = useMovementQueue({ vehicles, lines, curves })
+ *
+ * // Queue movements
+ * queueMovement('v1', { targetLineId: 'line002', targetPosition: 0.5 })
+ * queueMovement('v1', {
+ *   targetLineId: 'line003',
+ *   targetPosition: 1.0,
+ *   wait: true,
+ *   payload: { orderId: '123' }
+ * })
+ *
+ * // Clear queue for a specific vehicle
+ * clearQueue('v1')
+ *
+ * // Clear all queues
+ * clearQueue()
+ * ```
+ */
+export declare function useMovementQueue({ vehicles, lines }: UseMovementQueueProps): UseMovementQueueResult;

package/dist/react/hooks/useScene.d.ts

@@ -0,0 +1,78 @@
+import type { Line, Curve } from '../../core/types/geometry';
+import type { SceneConfig, SceneLineInput, SceneConnectionInput, CoordinateInput, ConnectionUpdateInput } from '../../core/types/api';
+export interface UseSceneResult {
+    /** Current lines in the scene */
+    lines: Line[];
+    /** Current curves (connections) in the scene */
+    curves: Curve[];
+    /** Set the entire scene configuration */
+    setScene: (config: SceneConfig) => {
+        success: boolean;
+        errors?: string[];
+    };
+    /** Add a single line to the scene */
+    addLine: (line: SceneLineInput) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Update a line's start and/or end coordinates */
+    updateLine: (lineId: string, updates: {
+        start?: CoordinateInput;
+        end?: CoordinateInput;
+    }) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Remove a line from the scene */
+    removeLine: (lineId: string) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Add a connection between two lines */
+    addConnection: (connection: SceneConnectionInput) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Update a connection's offset values */
+    updateConnection: (fromLineId: string, toLineId: string, updates: ConnectionUpdateInput) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Remove a connection */
+    removeConnection: (fromLineId: string, toLineId: string) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Clear all lines and curves */
+    clear: () => void;
+    /** Any validation errors from the last operation */
+    error: string | null;
+    /** @internal Load pre-computed scene data directly (for bulk loading) */
+    _loadScene: (lines: Line[], curves: Curve[]) => void;
+}
+/**
+ * Hook for managing scene configuration programmatically.
+ *
+ * This hook provides a simple API for creating and managing scenes without DSL.
+ * It's designed to be the backbone of the vehicle-path library.
+ *
+ * @example
+ * ```typescript
+ * const { lines, curves, setScene, addLine } = useScene()
+ *
+ * // Set entire scene at once
+ * setScene({
+ *   lines: [
+ *     { id: 'line001', start: [100, 100], end: [500, 100] },
+ *     { id: 'line002', start: [500, 100], end: [500, 400] }
+ *   ],
+ *   connections: [
+ *     { from: 'line001', to: 'line002' }
+ *   ]
+ * })
+ *
+ * // Or add lines incrementally
+ * addLine({ id: 'line003', start: [500, 400], end: [100, 400] })
+ * ```
+ */
+export declare function useScene(): UseSceneResult;

package/dist/react/hooks/useVehicleSimulation.d.ts

@@ -0,0 +1,126 @@
+import type { SceneLineInput, CoordinateInput, VehicleInput, VehicleUpdateInput, GotoInput, SimulationConfig, ConnectionUpdateInput } from '../../core/types/api';
+import type { Line, Curve } from '../../core/types/geometry';
+import type { Vehicle, GotoCommand } from '../../core/types/vehicle';
+import type { TangentMode } from '../../core/types/config';
+import type { VehicleEventEmitter } from '../../utils/event-emitter';
+/**
+ * Warning types for edge case detection
+ */
+export interface SimulationWarning {
+    type: 'vehicle_on_removed_line' | 'movement_queue_cleared' | 'orphaned_connection' | 'dsl_parse_error';
+    message: string;
+    details?: {
+        lineId?: string;
+        vehicleId?: string;
+        vehicleIds?: string[];
+        connectionCount?: number;
+        errors?: string[];
+    };
+}
+/**
+ * Result type with warnings for operations that may have side effects
+ */
+export interface SimulationResult {
+    success: boolean;
+    error?: string;
+    warnings?: SimulationWarning[];
+}
+export interface UseVehicleSimulationProps {
+    wheelbase: number;
+    tangentMode?: TangentMode;
+    eventEmitter?: VehicleEventEmitter;
+}
+export interface UseVehicleSimulationResult {
+    lines: Line[];
+    curves: Curve[];
+    vehicles: Vehicle[];
+    movingVehicles: Vehicle[];
+    vehicleQueues: Map<string, GotoCommand[]>;
+    error: string | null;
+    addLine: (line: SceneLineInput) => SimulationResult;
+    updateLine: (lineId: string, updates: {
+        start?: CoordinateInput;
+        end?: CoordinateInput;
+    }) => SimulationResult;
+    removeLine: (lineId: string) => SimulationResult;
+    clearScene: () => void;
+    connect: (fromLineId: string, toLineId: string, options?: {
+        fromOffset?: number;
+        fromIsPercentage?: boolean;
+        toOffset?: number;
+        toIsPercentage?: boolean;
+    }) => SimulationResult;
+    updateConnection: (fromLineId: string, toLineId: string, updates: ConnectionUpdateInput) => SimulationResult;
+    disconnect: (fromLineId: string, toLineId: string) => SimulationResult;
+    addVehicles: (input: VehicleInput | VehicleInput[]) => SimulationResult;
+    updateVehicle: (vehicleId: string, updates: VehicleUpdateInput) => SimulationResult;
+    removeVehicle: (vehicleId: string) => SimulationResult;
+    clearVehicles: () => void;
+    goto: (input: GotoInput) => SimulationResult;
+    clearQueue: (vehicleId?: string) => SimulationResult;
+    prepare: () => boolean;
+    tick: (distance: number) => boolean;
+    reset: () => void;
+    continueVehicle: (vehicleId: string) => boolean;
+    isMoving: () => boolean;
+    loadFromDSL: (dsl: string) => SimulationResult;
+    loadFromJSON: (config: SimulationConfig) => SimulationResult;
+    getVehiclesOnLine: (lineId: string) => Vehicle[];
+    hasVehiclesOnLine: (lineId: string) => boolean;
+}
+/**
+ * Single entrypoint hook for vehicle path simulation.
+ *
+ * This hook provides a clean, DSL-like API that combines all functionality:
+ * scene management, vehicles, movement commands, and animation.
+ *
+ * @example
+ * ```typescript
+ * const sim = useVehicleSimulation({ wheelbase: 30, tangentMode: 'proportional-40' })
+ *
+ * // Scene (mirrors DSL: "line001 : (141, 513) -> (362, 121)")
+ * sim.addLine({ id: 'line001', start: [141, 513], end: [362, 121] })
+ * sim.updateLine('line001', { end: [400, 150] })  // for drag
+ * sim.removeLine('line001')
+ *
+ * // Connection (mirrors DSL: "line001 80% -> line002 20%")
+ * sim.connect('line001', 'line002', { fromOffset: 0.8, toOffset: 0.2 })
+ * sim.connect('line001', 'line002', { fromOffset: 150, fromIsPercentage: false, toOffset: 50, toIsPercentage: false })
+ * sim.disconnect('line001', 'line002')
+ *
+ * // Vehicle (mirrors DSL: "v1 start line001 0")
+ * sim.addVehicles({ id: 'v1', lineId: 'line001', position: 0 })
+ * sim.removeVehicle('v1')
+ *
+ * // Movement (mirrors DSL: "v1 goto line001 100%")
+ * sim.goto({ id: 'v1', lineId: 'line001', position: 1.0 })
+ * sim.goto({ id: 'v1', lineId: 'line001', position: 150, isPercentage: false })
+ *
+ * // Animation
+ * sim.prepare()
+ * sim.tick(5)
+ * sim.reset()
+ *
+ * // DSL Loading
+ * sim.loadFromDSL(\`
+ *   line001 : (0, 0) -> (400, 0)
+ *   v1 start line001 0%
+ *   v1 goto line001 100%
+ * \`)
+ *
+ * // JSON Loading
+ * sim.loadFromJSON({
+ *   lines: [
+ *     { id: 'line001', start: [0, 0], end: [400, 0] },
+ *     { id: 'line002', start: [400, 0], end: [400, 300] }
+ *   ],
+ *   connections: [{ from: 'line001', to: 'line002' }],
+ *   vehicles: [{ id: 'v1', lineId: 'line001', position: 0 }],
+ *   movements: [
+ *     { vehicleId: 'v1', targetLineId: 'line001', targetPosition: 1.0 },
+ *     { vehicleId: 'v1', targetLineId: 'line002', targetPosition: 1.0 }
+ *   ]
+ * })
+ * ```
+ */
+export declare function useVehicleSimulation({ wheelbase, tangentMode, eventEmitter }: UseVehicleSimulationProps): UseVehicleSimulationResult;

package/dist/react/hooks/useVehicles.d.ts

@@ -0,0 +1,55 @@
+import type { Line } from '../../core/types/geometry';
+import type { Vehicle } from '../../core/types/vehicle';
+import type { VehicleInput, VehicleUpdateInput } from '../../core/types/api';
+export interface UseVehiclesProps {
+    lines: Line[];
+    wheelbase: number;
+}
+export interface UseVehiclesResult {
+    /** Current vehicles in the scene */
+    vehicles: Vehicle[];
+    /** Add one or more vehicles to the scene */
+    addVehicles: (input: VehicleInput | VehicleInput[]) => {
+        success: boolean;
+        errors?: string[];
+    };
+    /** Update a vehicle's position or line (only when idle) */
+    updateVehicle: (vehicleId: string, updates: VehicleUpdateInput) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Remove a vehicle from the scene */
+    removeVehicle: (vehicleId: string) => {
+        success: boolean;
+        error?: string;
+    };
+    /** Clear all vehicles */
+    clear: () => void;
+    /** Any error from the last operation */
+    error: string | null;
+    /** @internal Load pre-computed vehicles directly (for bulk loading) */
+    _loadVehicles: (vehicles: Vehicle[]) => void;
+}
+/**
+ * Hook for managing vehicles programmatically.
+ *
+ * This hook provides a simple API for adding and removing vehicles at runtime.
+ *
+ * @example
+ * ```typescript
+ * const { vehicles, addVehicles, removeVehicle } = useVehicles({ lines, wheelbase: 30 })
+ *
+ * // Add single vehicle
+ * addVehicles({ id: 'v1', lineId: 'line001', position: 0.5 })
+ *
+ * // Add multiple vehicles
+ * addVehicles([
+ *   { id: 'v1', lineId: 'line001', position: 0 },
+ *   { id: 'v2', lineId: 'line002', position: 0.5 }
+ * ])
+ *
+ * // Remove a vehicle
+ * removeVehicle('v1')
+ * ```
+ */
+export declare function useVehicles({ lines, wheelbase }: UseVehiclesProps): UseVehiclesResult;

package/dist/react/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * React Layer - React hooks and providers
+ *
+ * This layer provides React-specific integrations for the vehicle-path library.
+ * Use this if you want the complete React experience.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   useVehicleSimulation,
+ *   useScene,
+ *   useVehicles,
+ *   VehicleEventProvider
+ * } from 'vehicle-path/react'
+ * ```
+ */
+export { useVehicleSimulation, type UseVehicleSimulationProps, type UseVehicleSimulationResult, type SimulationWarning, type SimulationResult } from './hooks/useVehicleSimulation';
+/** Hook for managing scene (lines & curves) */
+export { useScene, type UseSceneResult } from './hooks/useScene';
+/** Hook for managing vehicles */
+export { useVehicles, type UseVehiclesResult, type UseVehiclesProps } from './hooks/useVehicles';
+/** Hook for managing the queue of movement commands */
+export { useMovementQueue, type UseMovementQueueResult, type UseMovementQueueProps } from './hooks/useMovementQueue';
+/** Hook for running animation (prepare, tick, reset) */
+export { useAnimation, type UseAnimationProps } from './hooks/useAnimation';
+/**
+ * @deprecated Use `useMovementQueue` instead. This alias will be removed in a future version.
+ */
+export { useMovementQueue as useMovement } from './hooks/useMovementQueue';
+export type { UseMovementQueueResult as UseMovementResult } from './hooks/useMovementQueue';
+export type { UseMovementQueueProps as UseMovementProps } from './hooks/useMovementQueue';
+/**
+ * @deprecated Use `useAnimation` instead. This alias will be removed in a future version.
+ */
+export { useAnimation as useVehicleMovement } from './hooks/useAnimation';
+/**
+ * @deprecated Use `useVehicleSimulation.loadFromDSL()` instead. This hook will be removed in a future version.
+ */
+export { useSceneDefinition } from './dsl-hooks/useSceneDefinition';
+/**
+ * @deprecated Use `useVehicleSimulation.loadFromDSL()` instead. This hook will be removed in a future version.
+ */
+export { useInitialMovement } from './dsl-hooks/useInitialMovement';
+/**
+ * @deprecated Use `useVehicleSimulation.loadFromDSL()` instead. This hook will be removed in a future version.
+ */
+export { useMovementSequence } from './dsl-hooks/useMovementSequence';
+export { useVehicleEventEmitter, useCreateVehicleEventEmitter, useVehicleEvent, VehicleEventContext, VehicleEventProvider, type VehicleEventProviderProps } from './providers/useVehicleEvents';

package/dist/react/providers/useVehicleEvents.d.ts

@@ -0,0 +1,78 @@
+import React, { type ReactNode } from 'react';
+import { VehicleEventEmitter, type VehicleEventType, type VehicleEventCallback, type VehicleEventMap, type VehiclePositionUpdate } from '../../utils/event-emitter';
+/**
+ * React context for VehicleEventEmitter
+ */
+export declare const VehicleEventContext: React.Context<VehicleEventEmitter | null>;
+/**
+ * Hook to access the VehicleEventEmitter instance from context
+ * @returns VehicleEventEmitter instance
+ * @throws Error if used outside of VehicleEventProvider
+ */
+export declare function useVehicleEventEmitter(): VehicleEventEmitter;
+/**
+ * Hook to create a new VehicleEventEmitter instance (for provider)
+ * @returns VehicleEventEmitter instance (stable reference)
+ */
+export declare function useCreateVehicleEventEmitter(): VehicleEventEmitter;
+/**
+ * Hook to subscribe to a vehicle event with automatic cleanup
+ *
+ * @example
+ * ```typescript
+ * useVehicleEvent('commandComplete', (info) => {
+ *   console.log(`Vehicle ${info.vehicleId} arrived!`)
+ *   if (info.payload) {
+ *     // Handle payload
+ *   }
+ * })
+ * ```
+ */
+export declare function useVehicleEvent<K extends VehicleEventType>(event: K, callback: VehicleEventCallback<K>, deps?: React.DependencyList): void;
+/**
+ * Props for VehicleEventProvider
+ */
+export interface VehicleEventProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provider component for VehicleEventEmitter
+ *
+ * This simplifies the setup from:
+ * ```typescript
+ * const emitter = useCreateVehicleEventEmitter()
+ * <VehicleEventContext.Provider value={emitter}>
+ *   <App />
+ * </VehicleEventContext.Provider>
+ * ```
+ *
+ * To just:
+ * ```typescript
+ * <VehicleEventProvider>
+ *   <App />
+ * </VehicleEventProvider>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { VehicleEventProvider, useVehicleEvent } from 'vehicle-path'
+ *
+ * function App() {
+ *   return (
+ *     <VehicleEventProvider>
+ *       <MyComponent />
+ *     </VehicleEventProvider>
+ *   )
+ * }
+ *
+ * function MyComponent() {
+ *   useVehicleEvent('commandComplete', (info) => {
+ *     console.log(`Vehicle ${info.vehicleId} arrived!`)
+ *   })
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+export declare function VehicleEventProvider({ children }: VehicleEventProviderProps): React.ReactElement;
+export type { VehicleEventEmitter, VehicleEventType, VehicleEventCallback, VehicleEventMap, VehiclePositionUpdate };

package/dist/react.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./useVehicleEvents-CBymulau.cjs");exports.VehicleEventContext=e.VehicleEventContext;exports.VehicleEventProvider=e.VehicleEventProvider;exports.useAnimation=e.useAnimation;exports.useCreateVehicleEventEmitter=e.useCreateVehicleEventEmitter;exports.useInitialMovement=e.useInitialMovement;exports.useMovement=e.useMovementQueue;exports.useMovementQueue=e.useMovementQueue;exports.useMovementSequence=e.useMovementSequence;exports.useScene=e.useScene;exports.useSceneDefinition=e.useSceneDefinition;exports.useVehicleEvent=e.useVehicleEvent;exports.useVehicleEventEmitter=e.useVehicleEventEmitter;exports.useVehicleMovement=e.useAnimation;exports.useVehicleSimulation=e.useVehicleSimulation;exports.useVehicles=e.useVehicles;

package/dist/react.js

@@ -0,0 +1,18 @@
+import { V as t, a as i, u as a, b as n, c as u, d as c, d as o, e as v, f as l, g as m, h, i as V, u as r, j as E, k as M } from "./useVehicleEvents-B2JQFNjc.js";
+export {
+  t as VehicleEventContext,
+  i as VehicleEventProvider,
+  a as useAnimation,
+  n as useCreateVehicleEventEmitter,
+  u as useInitialMovement,
+  c as useMovement,
+  o as useMovementQueue,
+  v as useMovementSequence,
+  l as useScene,
+  m as useSceneDefinition,
+  h as useVehicleEvent,
+  V as useVehicleEventEmitter,
+  r as useVehicleMovement,
+  E as useVehicleSimulation,
+  M as useVehicles
+};