Validation System

The validation system checks whether user interactions meet specified criteria, enabling quiz-like experiences and guided tutorials.

Built-in Validators

Position Validator

Validates if a point is within tolerance of a target position.

import { Validators } from '@wangyaoshen/locus-interaction';

const validator = Validators.position([100, 100], 10);
// Returns true if position is within 10 pixels of (100, 100)

const result = validator([105, 105]); // { passed: true, score: 0.95 }

Value Validator

Validates if a numeric value is within tolerance of a target.

import { Validators } from '@wangyaoshen/locus-interaction';

const validator = Validators.value(50, 1);
// Returns true if value is within 1 of 50

const result = validator(50.5); // { passed: true, score: 0.95 }

Range Validator

Validates if a value is within a specified range.

import { Validators } from '@wangyaoshen/locus-interaction';

const validator = Validators.range(0, 100);

validator(50);  // { passed: true }
validator(150); // { passed: false }

Custom Validator

Create custom validation logic.

import { Validators } from '@wangyaoshen/locus-interaction';

const isEven = Validators.custom(
  (n) => n % 2 === 0,
  'Value must be even'
);

isEven(4); // { passed: true }
isEven(5); // { passed: false, message: 'Value must be even' }

Combining Validators

All (AND)

All validators must pass.

import { Validators } from '@wangyaoshen/locus-interaction';

const validator = Validators.all(
  Validators.range(0, 100),
  Validators.custom((n) => n % 2 === 0, 'Must be even'),
);

validator(50); // { passed: true }
validator(51); // { passed: false }
validator(150); // { passed: false }

Any (OR)

At least one validator must pass.

import { Validators } from '@wangyaoshen/locus-interaction';

const validator = Validators.any(
  Validators.value(0, 0.1),
  Validators.value(100, 0.1),
);

validator(0);   // { passed: true }
validator(100); // { passed: true }
validator(50);  // { passed: false }

Using ValidationSystem

The ValidationSystem class provides a higher-level API for validation.

import { ValidationSystem } from '@wangyaoshen/locus-interaction';

const system = new ValidationSystem();

// Validate position
const result = system.validate([105, 105], {
  type: 'position',
  target: [100, 100],
  tolerance: 10,
});

console.log(result.passed); // true
console.log(result.score);  // 0.95 (based on accuracy)

Validation Configuration

interface ValidationConditionConfig {
  type: 'position' | 'value' | 'range' | 'custom';
  target?: Vector2 | number;
  tolerance?: number;
  min?: number;
  max?: number;
  validate?: (value: any) => boolean;
  message?: string;
}

Validation in Sessions

Validation is typically used within interaction sessions:

import { InteractionManager, InteractivePoint } from '@wangyaoshen/locus-interaction';

const point = new InteractivePoint({
  position: [100, 100],
});

const manager = new InteractionManager({
  canvas: canvasElement,
});

manager.registerComponent(point);

manager.startSession({
  id: 'quiz-1',
  components: [point],
  validation: {
    type: 'position',
    target: [200, 200],
    tolerance: 20,
  },
  onSuccess: () => {
    console.log('Correct!');
  },
  onFail: () => {
    console.log('Try again');
  },
});

Feedback System

The feedback system provides visual feedback for validation results.

import { globalFeedback } from '@wangyaoshen/locus-interaction';

// Show success feedback
globalFeedback.success('Correct!');

// Show error feedback
globalFeedback.error('Try again');

// Show hint
globalFeedback.hint('Move the point to the right');

// Listen for feedback events
globalFeedback.addListener((config) => {
  // Render custom feedback UI
  showFeedbackUI(config);
});

Feedback Configuration

interface FeedbackConfig {
  type: 'success' | 'error' | 'hint' | 'info';
  message: string;
  duration?: number;  // Auto-dismiss duration in ms
  position?: 'top' | 'bottom' | 'center';
}