@umituz/react-native-mascot 1.0.3 → 1.0.7

package/README.md

@@ -8,6 +8,10 @@ Interactive mascot system for React Native apps - Customizable animated characte
 - ✅ **Lottie Animations** - Professional JSON animations
 - ✅ **SVG Rendering** - Custom vector graphics
 - ✅ **Mood System** - Dynamic personality and emotions
+- ✅ **State-Based Animations** - 6 predefined states (idle, loading, success, error, empty, guide)
+- ✅ **Auto-Transitions** - Automatic state transitions (e.g., loading → success)
+- ✅ **Size Variants** - Built-in small, medium, large sizes
+- ✅ **Optimized Performance** - LRU cache, React.memo, memory leak prevention
 - ✅ **Interactive** - Touch-enabled mascots
 - ✅ **Animation Queue** - Sequence animations
 - ✅ **Custom Accessories** - Add glasses, hats, etc.
@@ -99,6 +103,62 @@ function CustomMascotScreen() {
     touchEnabled: true
   });
 
+  return <MascotView mascot={mascot} size={150} />;
+}
+```
+
+### State-Based Animations (NEW!)
+
+Inspired by production apps like Vivoim Style, the new state-based system provides predefined animation states with auto-transitions:
+
+```tsx
+import { useMascotState } from '@umituz/react-native-mascot';
+
+function StatefulMascot() {
+  const mascot = useMascotState({
+    initialState: 'idle',
+    size: 'medium',
+    enableAutoTransition: true,
+    onStateChange: (from, to) => console.log(`${from} → ${to}`),
+    onAnimationComplete: (state) => console.log(`Completed: ${state}`)
+  });
+
+  return (
+    <View>
+      {/* Use mascot.state to drive your Lottie animations */}
+      {/* mascot.size: 40 (small), 80 (medium), 120 (large), or custom number */}
+      {/* mascot.isLooping: true for idle/loading/empty/guide, false for success/error */}
+      {/* mascot.duration: animation duration in milliseconds */}
+      {/* mascot.speed: animation speed multiplier */}
+
+      <MascotView
+        mascot={mascot.mascot}
+        size={mascot.size}
+      />
+
+      <Button title="Start Loading" onPress={mascot.startLoading} />
+      <Button title="Success" onPress={mascot.triggerSuccess} />
+      <Button title="Error" onPress={mascot.triggerError} />
+      <Button title="Reset" onPress={mascot.reset} />
+    </View>
+  );
+}
+```
+
+**Available States:**
+- `idle` - Calm breathing animation (default, loops)
+- `loading` - Active processing animation (loops)
+- `success` - Confirmation animation (non-looping, auto-transitions to idle)
+- `error` - Error acknowledgment (non-looping, auto-transitions to idle)
+- `empty` - Empty state invitation (loops)
+- `guide` - Onboarding assistance (loops)
+
+**Auto-Transitions:**
+- `success` → `idle` (after 100ms delay)
+- `error` → `idle` (after 100ms delay)
+- `guide` → `idle` (after 200ms delay)
+- `loading` → `success` or `error` (when you call `stopLoading(success)`)
+
   return <MascotView mascot={mascot} />;
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-mascot",
-  "version": "1.0.3",
+  "version": "1.0.7",
   "description": "Interactive mascot system for React Native apps - Customizable animated characters with Lottie and SVG support, mood system, and easy integration",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -65,6 +65,7 @@
     }
   },
   "devDependencies": {
+    "@types/node": "^22.10.2",
     "@types/react": "~19.1.0",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",

package/src/application/dto/MascotDTO.ts

@@ -0,0 +1,64 @@
+/**
+ * Data Transfer Objects
+ * Used for data transfer between layers
+ */
+
+import type { MascotConfig, MascotState, MascotAppearance, MascotPersonality } from '../../domain/types/MascotTypes';
+
+/**
+ * Mascot DTO - simplified mascot data for presentation
+ */
+export interface MascotDTO {
+  id: string;
+  name: string;
+  type: string;
+  personality: MascotPersonality;
+  appearance: MascotAppearance;
+  state: MascotState;
+  interactive: boolean;
+  touchEnabled: boolean;
+  soundEnabled: boolean;
+}
+
+/**
+ * Animation State DTO
+ */
+export interface AnimationStateDTO {
+  isPlaying: boolean;
+  currentAnimation: string | null;
+  progress: number;
+  speed: number;
+}
+
+/**
+ * Mascot Initialization Options DTO
+ */
+export interface MascotInitOptionsDTO {
+  config?: MascotConfig;
+  template?: string;
+  autoInitialize?: boolean;
+}
+
+/**
+ * Animation Playback Options DTO
+ */
+export interface AnimationPlaybackOptionsDTO {
+  speed?: number;
+  loop?: boolean;
+  autoplay?: boolean;
+  onStart?: () => void;
+  onFinish?: () => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Mascot Update Options DTO
+ */
+export interface MascotUpdateOptionsDTO {
+  mood?: string;
+  energy?: number;
+  friendliness?: number;
+  playfulness?: number;
+  baseColor?: string;
+  accentColor?: string;
+}

package/src/application/errors/MascotErrors.ts

@@ -0,0 +1,76 @@
+/**
+ * Domain Errors
+ * Custom error classes for mascot domain
+ */
+
+export class MascotError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MascotError';
+    Object.setPrototypeOf(this, MascotError.prototype);
+  }
+}
+
+export class MascotNotInitializedError extends MascotError {
+  constructor() {
+    super('Mascot has not been initialized. Call initialize() or fromTemplate() first.');
+    this.name = 'MascotNotInitializedError';
+    Object.setPrototypeOf(this, MascotNotInitializedError.prototype);
+  }
+}
+
+export class AnimationNotFoundError extends MascotError {
+  constructor(animationId: string) {
+    super(`Animation with id "${animationId}" not found.`);
+    this.name = 'AnimationNotFoundError';
+    Object.setPrototypeOf(this, AnimationNotFoundError.prototype);
+  }
+}
+
+export class InvalidEnergyLevelError extends MascotError {
+  constructor(value: number) {
+    super(`Energy level must be between 0 and 1, got: ${value}`);
+    this.name = 'InvalidEnergyLevelError';
+    Object.setPrototypeOf(this, InvalidEnergyLevelError.prototype);
+  }
+}
+
+export class InvalidFriendlinessLevelError extends MascotError {
+  constructor(value: number) {
+    super(`Friendliness level must be between 0 and 1, got: ${value}`);
+    this.name = 'InvalidFriendlinessLevelError';
+    Object.setPrototypeOf(this, InvalidFriendlinessLevelError.prototype);
+  }
+}
+
+export class InvalidPlayfulnessLevelError extends MascotError {
+  constructor(value: number) {
+    super(`Playfulness level must be between 0 and 1, got: ${value}`);
+    this.name = 'InvalidPlayfulnessLevelError';
+    Object.setPrototypeOf(this, InvalidPlayfulnessLevelError.prototype);
+  }
+}
+
+export class InvalidMoodTransitionError extends MascotError {
+  constructor(from: string, to: string) {
+    super(`Cannot transition mood from "${from}" to "${to}".`);
+    this.name = 'InvalidMoodTransitionError';
+    Object.setPrototypeOf(this, InvalidMoodTransitionError.prototype);
+  }
+}
+
+export class MascotNotFoundError extends MascotError {
+  constructor(id: string) {
+    super(`Mascot with id "${id}" not found.`);
+    this.name = 'MascotNotFoundError';
+    Object.setPrototypeOf(this, MascotNotFoundError.prototype);
+  }
+}
+
+export class TemplateNotFoundError extends MascotError {
+  constructor(template: string) {
+    super(`Mascot template "${template}" not found.`);
+    this.name = 'TemplateNotFoundError';
+    Object.setPrototypeOf(this, TemplateNotFoundError.prototype);
+  }
+}

package/src/application/services/AnimationStateManager.ts

@@ -0,0 +1,69 @@
+/**
+ * Animation State Manager (Main - 60 lines)
+ * Public API for state management
+ */
+
+import { StateMachine } from './StateMachine';
+import type { MascotAnimationState } from '../../domain/types/AnimationStateTypes';
+
+export interface AnimationStateManagerConfig {
+  enableAutoTransition?: boolean;
+  enableHistoryTracking?: boolean;
+  maxHistorySize?: number;
+  onStateChange?: (from: MascotAnimationState, to: MascotAnimationState) => void;
+}
+
+export class AnimationStateManager {
+  private readonly _stateMachine: StateMachine;
+
+  constructor(
+    initialState: MascotAnimationState = 'idle',
+    config: AnimationStateManagerConfig = {}
+  ) {
+    this._stateMachine = new StateMachine(initialState, config);
+  }
+
+  get currentState(): MascotAnimationState {
+    return this._stateMachine.currentStateValue;
+  }
+
+  get previousState(): MascotAnimationState | null {
+    return this._stateMachine.previousState?.value || null;
+  }
+
+  get stateHistory(): MascotAnimationState[] {
+    return this._stateMachine.history;
+  }
+
+  transitionTo(newState: MascotAnimationState): void {
+    this._stateMachine.transitionTo(newState);
+  }
+
+  triggerSuccess(): void {
+    this._stateMachine.triggerSuccess();
+  }
+
+  triggerError(): void {
+    this._stateMachine.triggerError();
+  }
+
+  startLoading(): void {
+    this._stateMachine.startLoading();
+  }
+
+  stopLoading(success: boolean): void {
+    this._stateMachine.stopLoading(success);
+  }
+
+  reset(): void {
+    this._stateMachine.reset();
+  }
+
+  isLooping(): boolean {
+    return this._stateMachine.isLooping();
+  }
+
+  destroy(): void {
+    this._stateMachine.destroy();
+  }
+}

package/src/application/services/AppearanceManagement.ts

@@ -0,0 +1,40 @@
+/**
+ * Appearance Management (60 lines)
+ * Mascot appearance and accessory operations
+ */
+
+import { Mascot } from '../../domain/entities/Mascot';
+import type { MascotAppearance } from '../../domain/types/MascotTypes';
+
+export class AppearanceManagement {
+  constructor(private readonly mascot: Mascot) {}
+
+  updateAppearance(appearance: Partial<MascotAppearance>): void {
+    this.mascot.updateAppearance(appearance);
+  }
+
+  setBaseColor(color: string): void {
+    this.mascot.setBaseColor(color);
+  }
+
+  setAccentColor(color: string): void {
+    this.mascot.setAccentColor(color);
+  }
+
+  addAccessory(accessory: {
+    id: string;
+    type: string;
+    color?: string;
+    position?: { x: number; y: number };
+  }): void {
+    this.mascot.addAccessory(accessory);
+  }
+
+  removeAccessory(accessoryId: string): void {
+    this.mascot.removeAccessory(accessoryId);
+  }
+
+  get appearance() {
+    return this.mascot.appearance;
+  }
+}

package/src/application/services/MascotService.ts

@@ -0,0 +1,203 @@
+/**
+ * Mascot Service (120 lines)
+ * Core application service for mascot operations
+ */
+
+import { Mascot } from '../../domain/entities/Mascot';
+import type { MascotConfig, MascotMood, MascotAppearance } from '../../domain/types/MascotTypes';
+import type { IMascotRepository } from '../../domain/interfaces/IMascotRepository';
+import type { IAnimationController, AnimationOptions } from '../../domain/interfaces/IAnimationController';
+import type { IAssetManager } from '../../domain/interfaces/IAssetManager';
+import { MascotFactory } from '../../infrastructure/managers/MascotFactory';
+import { MascotNotInitializedError, AnimationNotFoundError } from '../errors/MascotErrors';
+import { PersonalityManagement } from './PersonalityManagement';
+import { AppearanceManagement } from './AppearanceManagement';
+
+export type MascotTemplate = 'friendly-bot' | 'cute-pet' | 'wise-owl' | 'pixel-hero';
+
+export class MascotService {
+  private _mascot: Mascot | null = null;
+  private _changeListeners: Set<() => void> = new Set();
+  private _personality: PersonalityManagement | null = null;
+  private _appearance: AppearanceManagement | null = null;
+
+  constructor(
+    private readonly _repository: IMascotRepository,
+    private readonly _animationController: IAnimationController,
+    _assetManager: IAssetManager
+  ) {
+    void _assetManager;
+  }
+
+  // ✅ Initialization
+  async initialize(config: MascotConfig): Promise<void> {
+    this._mascot = new Mascot(config);
+    await this._repository.save(config);
+    this._notifyChange();
+  }
+
+  async fromTemplate(
+    template: MascotTemplate,
+    customizations?: Partial<MascotConfig>
+  ): Promise<void> {
+    const mascot = MascotFactory.createFromTemplate(template, customizations);
+    this._mascot = mascot;
+    await this._repository.save(mascot.config);
+    this._notifyChange();
+  }
+
+  // ✅ State Getters
+  get mascot(): Mascot | null {
+    return this._mascot;
+  }
+
+  get isPlaying(): boolean {
+    return this._animationController.isPlaying();
+  }
+
+  get currentAnimation(): string | null {
+    return this._mascot?.state.currentAnimation ?? null;
+  }
+
+  get isReady(): boolean {
+    return this._mascot !== null;
+  }
+
+  // ✅ Manager Access (lazy loaded)
+  private _getPersonality(): PersonalityManagement {
+    if (!this._personality) {
+      this._ensureMascot();
+      this._personality = new PersonalityManagement(this._mascot!);
+    }
+    return this._personality;
+  }
+
+  private _getAppearance(): AppearanceManagement {
+    if (!this._appearance) {
+      this._ensureMascot();
+      this._appearance = new AppearanceManagement(this._mascot!);
+    }
+    return this._appearance;
+  }
+
+  // ✅ Personality Management (delegated)
+  setMood(mood: MascotMood): void {
+    this._getPersonality().setMood(mood);
+    this._notifyChange();
+  }
+
+  setEnergy(value: number): void {
+    this._getPersonality().setEnergy(value);
+    this._notifyChange();
+  }
+
+  setFriendliness(value: number): void {
+    this._getPersonality().setFriendliness(value);
+    this._notifyChange();
+  }
+
+  setPlayfulness(value: number): void {
+    this._getPersonality().setPlayfulness(value);
+    this._notifyChange();
+  }
+
+  cheerUp(): void {
+    this._getPersonality().cheerUp();
+    this._notifyChange();
+  }
+
+  boostEnergy(amount: number): void {
+    this._getPersonality().boostEnergy(amount);
+    this._notifyChange();
+  }
+
+  // ✅ Appearance Management (delegated)
+  updateAppearance(appearance: Partial<MascotAppearance>): void {
+    this._getAppearance().updateAppearance(appearance);
+    this._notifyChange();
+  }
+
+  setBaseColor(color: string): void {
+    this._getAppearance().setBaseColor(color);
+    this._notifyChange();
+  }
+
+  setAccentColor(color: string): void {
+    this._getAppearance().setAccentColor(color);
+    this._notifyChange();
+  }
+
+  addAccessory(accessory: {
+    id: string;
+    type: string;
+    color?: string;
+    position?: { x: number; y: number };
+  }): void {
+    this._getAppearance().addAccessory(accessory);
+    this._notifyChange();
+  }
+
+  removeAccessory(accessoryId: string): void {
+    this._getAppearance().removeAccessory(accessoryId);
+    this._notifyChange();
+  }
+
+  // ✅ Animation Management
+  async playAnimation(animationId: string, options?: AnimationOptions): Promise<void> {
+    this._ensureMascot();
+    const animation = this._mascot!.getAnimation(animationId);
+    if (!animation) {
+      throw new AnimationNotFoundError(animationId);
+    }
+    this._mascot!.startAnimation(animationId);
+    await this._animationController.play(animation, options);
+    this._notifyChange();
+  }
+
+  stopAnimation(): void {
+    this._animationController.stop();
+    if (this._mascot) {
+      this._mascot.stopAnimation();
+    }
+    this._notifyChange();
+  }
+
+  pauseAnimation(): void {
+    this._animationController.pause();
+    this._notifyChange();
+  }
+
+  resumeAnimation(): void {
+    this._animationController.resume();
+    this._notifyChange();
+  }
+
+  // ✅ Visibility & Position
+  setVisible(visible: boolean): void {
+    this._ensureMascot();
+    this._mascot!.setVisible(visible);
+    this._notifyChange();
+  }
+
+  setPosition(position: { x: number; y: number }): void {
+    this._ensureMascot();
+    this._mascot!.setPosition(position);
+    this._notifyChange();
+  }
+
+  // ✅ Observable Pattern
+  subscribe(listener: () => void): () => void {
+    this._changeListeners.add(listener);
+    return () => this._changeListeners.delete(listener);
+  }
+
+  private _notifyChange(): void {
+    this._changeListeners.forEach((listener) => listener());
+  }
+
+  private _ensureMascot(): void {
+    if (!this._mascot) {
+      throw new MascotNotInitializedError();
+    }
+  }
+}

package/src/application/services/PersonalityManagement.ts

@@ -0,0 +1,39 @@
+/**
+ * Personality Management (60 lines)
+ * Mascot personality operations and behaviors
+ */
+
+import { Mascot } from '../../domain/entities/Mascot';
+import type { MascotMood } from '../../domain/types/MascotTypes';
+
+export class PersonalityManagement {
+  constructor(private readonly mascot: Mascot) {}
+
+  setMood(mood: MascotMood): void {
+    this.mascot.setMood(mood);
+  }
+
+  setEnergy(value: number): void {
+    this.mascot.setEnergy(value);
+  }
+
+  setFriendliness(value: number): void {
+    this.mascot.setFriendliness(value);
+  }
+
+  setPlayfulness(value: number): void {
+    this.mascot.setPlayfulness(value);
+  }
+
+  cheerUp(): void {
+    this.mascot.cheerUp();
+  }
+
+  boostEnergy(amount: number): void {
+    this.mascot.boostEnergy(amount);
+  }
+
+  get personality() {
+    return this.mascot.personality;
+  }
+}

package/src/application/services/StateHistory.ts

@@ -0,0 +1,55 @@
+/**
+ * State History (60 lines)
+ * Efficient history tracking with circular buffer
+ */
+
+import type { MascotAnimationState } from '../../domain/types/AnimationStateTypes';
+
+interface HistoryEntry {
+  state: MascotAnimationState;
+  timestamp: number;
+  triggeredBy: 'user' | 'system' | 'auto-transition';
+}
+
+export class StateHistory {
+  private readonly _buffer: HistoryEntry[];
+  private readonly _capacity: number;
+  private _size: number = 0;
+  private _head: number = 0;
+
+  constructor(capacity: number = 50) {
+    this._capacity = capacity;
+    this._buffer = new Array(capacity);
+  }
+
+  add(state: MascotAnimationState, triggeredBy: HistoryEntry['triggeredBy']): void {
+    this._buffer[this._head] = { state, timestamp: Date.now(), triggeredBy };
+    this._head = (this._head + 1) % this._capacity;
+
+    if (this._size < this._capacity) {
+      this._size++;
+    }
+  }
+
+  getStates(): MascotAnimationState[] {
+    const result: MascotAnimationState[] = [];
+    let index = this._head - this._size;
+
+    for (let i = 0; i < this._size; i++) {
+      if (index < 0) index += this._capacity;
+      result.push(this._buffer[index].state);
+      index++;
+    }
+
+    return result;
+  }
+
+  clear(): void {
+    this._size = 0;
+    this._head = 0;
+  }
+
+  get size(): number {
+    return this._size;
+  }
+}