@umituz/react-native-mascot 1.0.4 → 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.4",
+  "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/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

@@ -1,28 +1,33 @@
 /**
- * MascotService
- * Application service that orchestrates mascot use cases
- * This is the main entry point for all mascot operations
+ * Mascot Service (120 lines)
+ * Core application service for mascot operations
  */
 
 import { Mascot } from '../../domain/entities/Mascot';
-import type { MascotConfig, MascotMood, MascotAppearance, MascotAccessory } from '../../domain/types/MascotTypes';
+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,
-    private readonly _assetManager: IAssetManager
-  ) {}
+    _assetManager: IAssetManager
+  ) {
+    void _assetManager;
+  }
 
   // ✅ Initialization
   async initialize(config: MascotConfig): Promise<void> {
@@ -58,60 +63,67 @@ export class MascotService {
     return this._mascot !== null;
   }
 
-  // ✅ Personality Management
+  // ✅ 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._ensureMascot();
-    this._mascot!.setMood(mood);
+    this._getPersonality().setMood(mood);
     this._notifyChange();
   }
 
   setEnergy(value: number): void {
-    this._ensureMascot();
-    this._mascot!.setEnergy(value);
+    this._getPersonality().setEnergy(value);
     this._notifyChange();
   }
 
   setFriendliness(value: number): void {
-    this._ensureMascot();
-    this._mascot!.setFriendliness(value);
+    this._getPersonality().setFriendliness(value);
     this._notifyChange();
   }
 
   setPlayfulness(value: number): void {
-    this._ensureMascot();
-    this._mascot!.setPlayfulness(value);
+    this._getPersonality().setPlayfulness(value);
     this._notifyChange();
   }
 
-  // ✅ Rich Behaviors
   cheerUp(): void {
-    this._ensureMascot();
-    this._mascot!.cheerUp();
+    this._getPersonality().cheerUp();
     this._notifyChange();
   }
 
   boostEnergy(amount: number): void {
-    this._ensureMascot();
-    this._mascot!.boostEnergy(amount);
+    this._getPersonality().boostEnergy(amount);
     this._notifyChange();
   }
 
-  // ✅ Appearance Management
+  // ✅ Appearance Management (delegated)
   updateAppearance(appearance: Partial<MascotAppearance>): void {
-    this._ensureMascot();
-    this._mascot!.updateAppearance(appearance);
+    this._getAppearance().updateAppearance(appearance);
     this._notifyChange();
   }
 
   setBaseColor(color: string): void {
-    this._ensureMascot();
-    this._mascot!.setBaseColor(color);
+    this._getAppearance().setBaseColor(color);
     this._notifyChange();
   }
 
   setAccentColor(color: string): void {
-    this._ensureMascot();
-    this._mascot!.setAccentColor(color);
+    this._getAppearance().setAccentColor(color);
     this._notifyChange();
   }
 
@@ -121,14 +133,12 @@ export class MascotService {
     color?: string;
     position?: { x: number; y: number };
   }): void {
-    this._ensureMascot();
-    this._mascot!.addAccessory(accessory);
+    this._getAppearance().addAccessory(accessory);
     this._notifyChange();
   }
 
   removeAccessory(accessoryId: string): void {
-    this._ensureMascot();
-    this._mascot!.removeAccessory(accessoryId);
+    this._getAppearance().removeAccessory(accessoryId);
     this._notifyChange();
   }
 
@@ -175,7 +185,7 @@ export class MascotService {
     this._notifyChange();
   }
 
-  // ✅ Observable Pattern for React Integration
+  // ✅ Observable Pattern
   subscribe(listener: () => void): () => void {
     this._changeListeners.add(listener);
     return () => this._changeListeners.delete(listener);
@@ -185,7 +195,6 @@ export class MascotService {
     this._changeListeners.forEach((listener) => listener());
   }
 
-  // ✅ Validation
   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;
+  }
+}

package/src/application/services/StateMachine.ts

@@ -0,0 +1,154 @@
+/**
+ * State Machine (120 lines)
+ * Core state transition logic with validation
+ */
+
+import type { MascotAnimationState } from '../../domain/types/AnimationStateTypes';
+import { AnimationState } from '../../domain/value-objects/AnimationState';
+import { StateTransitions } from './StateTransitions';
+import { StateHistory } from './StateHistory';
+
+export interface StateMachineConfig {
+  enableAutoTransition?: boolean;
+  enableHistoryTracking?: boolean;
+  maxHistorySize?: number;
+  onStateChange?: (from: MascotAnimationState, to: MascotAnimationState) => void;
+}
+
+export class StateMachine {
+  private _currentState: AnimationState;
+  private _previousState: AnimationState | null = null;
+  private readonly _transitions: StateTransitions;
+  private readonly _history: StateHistory;
+  private readonly _config: Required<StateMachineConfig>;
+
+  constructor(
+    initialState: MascotAnimationState = 'idle',
+    config: StateMachineConfig = {}
+  ) {
+    this._currentState = AnimationState.create(initialState);
+    this._transitions = new StateTransitions();
+    this._history = new StateHistory(config.maxHistorySize || 50);
+    this._config = {
+      enableAutoTransition: config.enableAutoTransition ?? true,
+      enableHistoryTracking: config.enableHistoryTracking ?? true,
+      maxHistorySize: config.maxHistorySize ?? 50,
+      onStateChange: config.onStateChange ?? (() => {}),
+    };
+  }
+
+  get currentState(): AnimationState {
+    return this._currentState;
+  }
+
+  get currentStateValue(): MascotAnimationState {
+    return this._currentState.value;
+  }
+
+  get previousState(): AnimationState | null {
+    return this._previousState;
+  }
+
+  get history(): MascotAnimationState[] {
+    return this._history.getStates();
+  }
+
+  transitionTo(
+    newState: MascotAnimationState,
+    triggeredBy: 'user' | 'system' | 'auto-transition' = 'user'
+  ): void {
+    // Validate transition
+    if (!this._transitions.canTransitionTo(this.currentStateValue, newState)) {
+      const validTransitions = this._transitions
+        .getAvailableTransitions(this.currentStateValue)
+        .map((t) => t.to);
+      throw new Error(
+        `Cannot transition from '${this.currentStateValue}' to '${newState}'. ` +
+        `Valid transitions: ${validTransitions.join(', ')}`
+      );
+    }
+
+    // Store previous state
+    this._previousState = this._currentState;
+
+    // Track history
+    if (this._config.enableHistoryTracking) {
+      this._history.add(this.currentStateValue, triggeredBy);
+    }
+
+    // Update state
+    const oldState = this.currentStateValue;
+    this._currentState = AnimationState.create(newState);
+
+    // Notify
+    this._config.onStateChange(oldState, newState);
+
+    // Schedule auto-transition
+    if (this._config.enableAutoTransition && !this._currentState.shouldLoop()) {
+      const next = this._currentState.getNextState();
+      if (next) {
+        this._scheduleAutoTransition(next);
+      }
+    }
+  }
+
+  // Shortcut methods
+  triggerSuccess(): void {
+    this.transitionTo('success', 'system');
+  }
+
+  triggerError(): void {
+    this.transitionTo('error', 'system');
+  }
+
+  startLoading(): void {
+    this.transitionTo('loading', 'system');
+  }
+
+  stopLoading(success: boolean): void {
+    if (this.currentStateValue === 'loading') {
+      this.transitionTo(success ? 'success' : 'error', 'system');
+    }
+  }
+
+  reset(): void {
+    this.transitionTo('idle', 'system');
+  }
+
+  // State queries
+  isLooping(): boolean {
+    return this._currentState.shouldLoop();
+  }
+
+  isIdle(): boolean {
+    return this.currentStateValue === 'idle';
+  }
+
+  isLoading(): boolean {
+    return this.currentStateValue === 'loading';
+  }
+
+  // Auto-transition scheduling
+  private _autoTransitionTimer: NodeJS.Timeout | null = null;
+
+  private _scheduleAutoTransition(targetState: MascotAnimationState): void {
+    const duration = this._currentState.getDuration();
+    const delay = this._currentState.getTransitionDelay(targetState);
+
+    this._autoTransitionTimer = setTimeout(() => {
+      try {
+        this.transitionTo(targetState, 'auto-transition');
+      } catch (error) {
+        console.warn('Auto-transition failed:', error);
+      }
+    }, duration + delay);
+  }
+
+  destroy(): void {
+    if (this._autoTransitionTimer) {
+      clearTimeout(this._autoTransitionTimer);
+    }
+    this._history.clear();
+    this._config.onStateChange = () => {};
+  }
+}

package/src/application/services/StateTransitions.ts

@@ -0,0 +1,73 @@
+/**
+ * State Transitions (80 lines)
+ * Transition rules and validation
+ */
+
+import type { MascotAnimationState } from '../../domain/types/AnimationStateTypes';
+
+export interface StateTransition {
+  from: MascotAnimationState;
+  to: MascotAnimationState;
+  condition?: 'always' | 'on-success' | 'on-error' | 'on-complete';
+  delay?: number;
+}
+
+export class StateTransitions {
+  private readonly _transitions: Map<MascotAnimationState, StateTransition[]>;
+
+  constructor() {
+    this._transitions = new Map();
+    this._initializeTransitions();
+  }
+
+  canTransitionTo(from: MascotAnimationState, to: MascotAnimationState): boolean {
+    const transitions = this._transitions.get(from);
+    if (!transitions) return false;
+    return transitions.some((t) => t.to === to);
+  }
+
+  getAvailableTransitions(state: MascotAnimationState): StateTransition[] {
+    return this._transitions.get(state) || [];
+  }
+
+  getTransitionDelay(from: MascotAnimationState, to: MascotAnimationState): number {
+    const transitions = this._transitions.get(from);
+    const transition = transitions?.find((t) => t.to === to);
+    return transition?.delay || 0;
+  }
+
+  private _initializeTransitions(): void {
+    // Idle transitions
+    this._addTransition('idle', 'loading', 'always');
+    this._addTransition('idle', 'empty', 'always');
+    this._addTransition('idle', 'guide', 'always');
+
+    // Loading transitions
+    this._addTransition('loading', 'success', 'on-success');
+    this._addTransition('loading', 'error', 'on-error');
+
+    // Success transitions
+    this._addTransition('success', 'idle', 'on-complete', 100);
+
+    // Error transitions
+    this._addTransition('error', 'idle', 'on-complete', 100);
+
+    // Empty transitions
+    this._addTransition('empty', 'idle', 'always');
+
+    // Guide transitions
+    this._addTransition('guide', 'idle', 'on-complete', 200);
+  }
+
+  private _addTransition(
+    from: MascotAnimationState,
+    to: MascotAnimationState,
+    condition: StateTransition['condition'] = 'always',
+    delay: number = 0
+  ): void {
+    if (!this._transitions.has(from)) {
+      this._transitions.set(from, []);
+    }
+    this._transitions.get(from)!.push({ from, to, condition, delay });
+  }
+}