@vived/core 1.4.2 → 1.4.4

package/README.md

@@ -1,29 +1,151 @@
-# README #
+# @vived/core
 
-This README would normally document whatever steps are necessary to get your application up and running.
+Core Components for VIVED Apps and Hosts
 
-### What is this repository for? ###
+## Overview
 
-* Quick summary
-* Version
-* [Learn Markdown](https://bitbucket.org/tutorials/markdowndemo)
+@vived/core provides foundational architecture components used across VIVED applications. This library implements a component-based architecture pattern that enables building complex applications with proper separation of concerns.
 
-### How do I get set up? ###
+## Installation
 
-* Summary of set up
-* Configuration
-* Dependencies
-* Database configuration
-* How to run tests
-* Deployment instructions
+```bash
+npm install @vived/core
+```
 
-### Contribution guidelines ###
+## Core Concepts
 
-* Writing tests
-* Code review
-* Other guidelines
+The package is built around the "AppObject" architecture, which follows a component-based design pattern:
 
-### Who do I talk to? ###
+### AppObject
 
-* Repo owner or admin
-* Other community or team contact
+- The central entity that acts as a container for components
+- Each AppObject has a unique ID and belongs to an AppObjectRepo
+- Components can be added, removed, and queried
+- AppObjects are observable entities, notifying observers when components change
+
+### AppObjectRepo
+
+- Manages a collection of AppObjects 
+- Provides methods to find, create, and manage AppObjects
+- Handles singleton components across the application
+- Includes logging infrastructure for debugging
+
+### Component Types
+
+The architecture implements a clean separation of concerns through specialized components:
+
+1. **Entity (AppObjectEntity)**
+   - Holds and manages application state
+   - Provides change notifications when state is modified
+
+2. **Presentation Manager (AppObjectPM)**
+   - Manages view models for UI representation
+   - Transforms application state into UI-ready data
+   - Notifies views when view models change
+
+3. **Use Case (AppObjectUC)**
+   - Implements business logic
+   - Coordinates between data layer and presentation
+
+4. **Controller (AppObjectController)**
+   - Handles external inputs (user actions, system events)
+   - Delegates to appropriate use cases
+
+5. **View (AppObjectView)**
+   - UI representation components
+   - Consumes view models and renders UI
+
+## Example Implementation
+
+The package includes a fully implemented `ExampleFeature` that demonstrates the App Object Component architecture. This example demonstrates how to structure your code following the recommended patterns:
+
+### Directory Structure
+- **Entities/** - Domain models for storing and managing state
+- **PMs/** - Presentation Managers that transform data for UI consumption
+- **UCs/** - Use Cases that implement business logic operations
+- **Controllers/** - Simplified API for UI interaction
+- **Adapters/** - Connect UI frameworks to PMs
+- **Mocks/** - Test doubles for unit testing
+
+### Implementation Patterns
+The example demonstrates:
+- Observable entities with memoized properties
+- Presentation managers with view model transformation
+- Use cases that implement business logic
+- Controllers that provide a simple UI-friendly API
+- Component registration and retrieval
+- Singleton component access
+- Test patterns for each component type
+
+### Sample Usage
+
+```typescript
+// Create a repository and an app object
+const repo = makeAppObjectRepo();
+const appObject = repo.getOrCreate("myObject");
+
+// Add an entity component to hold state
+class MyEntity extends AppObjectEntity {
+  private _value = 0;
+  
+  get value() { return this._value; }
+  set value(newValue: number) {
+    this._value = newValue;
+    this.notifyOnChange();
+  }
+}
+
+// Add the entity to the app object
+const entity = new MyEntity(appObject, "MyEntity");
+
+// Create a presentation manager
+class MyPM extends AppObjectPM<{value: number}> {
+  vmsAreEqual(a: {value: number}, b: {value: number}): boolean {
+    return a.value === b.value;
+  }
+  
+  updateViewModel() {
+    const entity = this.getCachedLocalComponent<MyEntity>("MyEntity");
+    if (entity) {
+      this.doUpdateView({value: entity.value});
+    }
+  }
+}
+
+// The architecture enables clean, testable, and maintainable code
+```
+
+Refer to the `ExampleFeature` directory for a complete implementation example that shows the interaction between all component types.
+
+## Value Objects
+
+The package provides immutable value objects for mathematical and graphical operations:
+
+### Geometric & Mathematical Types
+- **Vector2**: 2D vector with operations like addition, dot product, rotation, and unit vector calculation
+- **Vector3**: 3D vector with similar operations plus cross product and coordinate transformations
+- **Quaternion**: For 3D rotations with methods for creation from angles, Euler angles, and matrices plus interpolation
+- **Matrix**: For transformation operations like translation, rotation, and scaling
+- **Angle**: Encapsulates angle values with automatic conversion between degrees and radians
+- **Rectangle**: For 2D rectangular regions with intersection testing
+
+### Parametric Geometry
+- **ParametricLine**: Represents lines with point and direction for intersection calculations
+- **ParametricPlane**: Represents planes with point and normal for 3D geometric operations
+- **LineSegment2D**: Represents finite line segments with intersection testing
+
+### Graphics & Utilities
+- **Color**: RGBA color representation with utility methods for conversion between formats (RGB, Hex, X11 names)
+- **Version**: Semantic versioning implementation with comparison operators
+
+## Utilities
+
+The package also includes various utility functions:
+- Color manipulation (adding alpha to hex, converting alpha to hex)
+- Length converters for different measurement systems
+- Linear interpolation and easing functions
+- Angle conversion between degrees and radians
+- File operations like downloading
+
+## License
+ISC

package/dist/cjs/AppObject/AppObject.js

@@ -3,16 +3,45 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppObject = void 0;
 exports.makeAppObject = makeAppObject;
 const Entities_1 = require("../Entities");
+/**
+ * AppObject is the central class in the VIVED application architecture.
+ * It serves as a container for components that implement the application's functionality.
+ * Each AppObject is identified by a unique ID and registered with an AppObjectRepo.
+ *
+ * AppObjects are observable entities that notify observers when their components change.
+ * This enables reactive programming patterns throughout the application.
+ */
 class AppObject extends Entities_1.ObservableEntity {
 }
 exports.AppObject = AppObject;
+/**
+ * Factory function to create a new AppObject
+ * @param id Unique identifier for the new AppObject
+ * @param repo Repository to register the AppObject with
+ * @returns A new AppObject instance
+ */
 function makeAppObject(id, repo) {
     return new AppObjectImp(id, repo);
 }
+/**
+ * Implementation of the AppObject abstract class
+ * This class handles the component management functionality
+ */
 class AppObjectImp extends AppObject {
+    /**
+     * Checks if a component of the specified type exists
+     * @param type The component type identifier
+     * @returns True if the component exists, false otherwise
+     */
     hasComponent(type) {
         return this.componentLookup.has(type);
     }
+    /**
+     * Adds a component to this AppObject
+     * If a component of the same type already exists, it will be disposed and replaced
+     * Notifies observers after adding the component
+     * @param component The component to add
+     */
     addComponent(component) {
         const currentComponent = this.componentLookup.get(component.type);
         if (currentComponent) {
@@ -22,6 +51,11 @@ class AppObjectImp extends AppObject {
         this.componentLookup.set(component.type, component);
         this.notify();
     }
+    /**
+     * Retrieves a component by type
+     * @param type The component type identifier
+     * @returns The component cast to type T, or undefined if not found
+     */
     getComponent(type) {
         if (this.componentLookup.has(type)) {
             return this.componentLookup.get(type);
@@ -30,6 +64,10 @@ class AppObjectImp extends AppObject {
             return undefined;
         }
     }
+    /**
+     * Removes a component by type and notifies observers
+     * @param type The component type identifier
+     */
     removeComponent(type) {
         const component = this.componentLookup.get(type);
         if (!component)
@@ -37,12 +75,27 @@ class AppObjectImp extends AppObject {
         this.componentLookup.delete(type);
         this.notify();
     }
+    /**
+     * Gets all components attached to this AppObject
+     * @returns Array of all components
+     */
     allComponents() {
         return Array.from(this.componentLookup.values());
     }
+    /**
+     * Creates a new AppObject instance
+     * @param id Unique identifier for this AppObject
+     * @param repo Repository to register with
+     */
     constructor(id, repo) {
         super();
+        /** Map of component types to component instances */
         this.componentLookup = new Map();
+        /**
+         * Cleans up resources by:
+         * 1. Disposing all attached components
+         * 2. Removing this AppObject from its repository
+         */
         this.dispose = () => {
             const components = Array.from(this.componentLookup.values());
             this.componentLookup.clear();

package/dist/cjs/AppObject/AppObject.js.map

@@ -1 +1 @@
-{"version":3,"file":"AppObject.js","sourceRoot":"","sources":["../../../src/AppObject/AppObject.ts"],"names":[],"mappings":";;;AAiBA,sCAEC;AAnBD,0CAA+C;AAI/C,MAAsB,SAAU,SAAQ,2BAAgB;CAWvD;AAXD,8BAWC;AAED,SAAgB,aAAa,CAAC,EAAU,EAAE,IAAmB;IAC3D,OAAO,IAAI,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,YAAa,SAAQ,SAAS;IAMlC,YAAY,CAAC,IAAY;QACvB,OAAO,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAED,YAAY,CAAC,SAA6B;QACxC,MAAM,gBAAgB,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAClE,IAAI,gBAAgB,EAAE,CAAC;YACrB,OAAO,CAAC,IAAI,CACV,yBAAyB,SAAS,CAAC,IAAI,yBAAyB,IAAI,CAAC,EAAE,EAAE,CAC1E,CAAC;YACF,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;QAED,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED,YAAY,CAA+B,IAAY;QACrD,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAM,CAAC;QAC7C,CAAC;aAAM,CAAC;YACN,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,eAAe,CAAC,IAAY;QAC1B,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEjD,IAAI,CAAC,SAAS;YAAE,OAAO;QAEvB,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED,aAAa;QACX,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC;IACnD,CAAC;IAaD,YAAY,EAAU,EAAE,IAAmB;QACzC,KAAK,EAAE,CAAC;QApDF,oBAAe,GAAG,IAAI,GAAG,EAA8B,CAAC;QAyChE,YAAO,GAAG,GAAS,EAAE;YACnB,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC;YAC7D,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;YAC7B,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YAErC,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBACpC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACrC,CAAC;QACH,CAAC,CAAC;QAIA,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF","sourcesContent":["import { ObservableEntity } from \"../Entities\";\r\nimport { AppObjectComponent } from \"./AppObjectComponent\";\r\nimport { AppObjectRepo } from \"./AppObjectRepo\";\r\n\r\nexport abstract class AppObject extends ObservableEntity {\r\n  abstract readonly id: string;\r\n  abstract readonly appObjectRepo: AppObjectRepo;\r\n\r\n  abstract hasComponent(type: string): boolean;\r\n  abstract addComponent(component: AppObjectComponent): void;\r\n  abstract getComponent<T extends AppObjectComponent>(type: string): T | undefined;\r\n  abstract removeComponent(type: string): void;\r\n  abstract allComponents(): AppObjectComponent[];\r\n\r\n  abstract dispose(): void;\r\n}\r\n\r\nexport function makeAppObject(id: string, repo: AppObjectRepo): AppObject {\r\n  return new AppObjectImp(id, repo);\r\n}\r\n\r\nclass AppObjectImp extends AppObject {\r\n  readonly id: string;\r\n  readonly appObjectRepo: AppObjectRepo;\r\n\r\n  private componentLookup = new Map<string, AppObjectComponent>();\r\n\r\n  hasComponent(type: string): boolean {\r\n    return this.componentLookup.has(type);\r\n  }\r\n\r\n  addComponent(component: AppObjectComponent): void {\r\n    const currentComponent = this.componentLookup.get(component.type);\r\n    if (currentComponent) {\r\n      console.warn(\r\n        `[AppObject] Component ${component.type} is being replaced on ${this.id}`\r\n      );\r\n      currentComponent.dispose();\r\n    }\r\n\r\n    this.componentLookup.set(component.type, component);\r\n    this.notify();\r\n  }\r\n\r\n  getComponent<T extends AppObjectComponent>(type: string): T | undefined {\r\n    if (this.componentLookup.has(type)) {\r\n      return this.componentLookup.get(type) as T;\r\n    } else {\r\n      return undefined;\r\n    }\r\n  }\r\n\r\n  removeComponent(type: string): void {\r\n    const component = this.componentLookup.get(type);\r\n\r\n    if (!component) return;\r\n\r\n    this.componentLookup.delete(type);\r\n    this.notify();\r\n  }\r\n\r\n  allComponents(): AppObjectComponent[] {\r\n    return Array.from(this.componentLookup.values());\r\n  }\r\n\r\n\r\n  dispose = (): void => {\r\n    const components = Array.from(this.componentLookup.values());\r\n    this.componentLookup.clear();\r\n    components.forEach(c => c.dispose());\r\n\r\n    if (this.appObjectRepo.has(this.id)) {\r\n      this.appObjectRepo.remove(this.id);\r\n    }\r\n  };\r\n\r\n  constructor(id: string, repo: AppObjectRepo) {\r\n    super();\r\n    this.id = id;\r\n    this.appObjectRepo = repo;\r\n    this.appObjectRepo.add(this);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"AppObject.js","sourceRoot":"","sources":["../../../src/AppObject/AppObject.ts"],"names":[],"mappings":";;;AAgEA,sCAEC;AAlED,0CAA+C;AAI/C;;;;;;;GAOG;AACH,MAAsB,SAAU,SAAQ,2BAAgB;CA4CvD;AA5CD,8BA4CC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,EAAU,EAAE,IAAmB;IAC3D,OAAO,IAAI,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,YAAa,SAAQ,SAAS;IAOlC;;;;OAIG;IACH,YAAY,CAAC,IAAY;QACvB,OAAO,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,SAA6B;QACxC,MAAM,gBAAgB,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAClE,IAAI,gBAAgB,EAAE,CAAC;YACrB,OAAO,CAAC,IAAI,CACV,yBAAyB,SAAS,CAAC,IAAI,yBAAyB,IAAI,CAAC,EAAE,EAAE,CAC1E,CAAC;YACF,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;QAED,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,YAAY,CAA+B,IAAY;QACrD,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAM,CAAC;QAC7C,CAAC;aAAM,CAAC;YACN,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,IAAY;QAC1B,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEjD,IAAI,CAAC,SAAS;YAAE,OAAO;QAEvB,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,aAAa;QACX,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC;IACnD,CAAC;IAiBD;;;;OAIG;IACH,YAAY,EAAU,EAAE,IAAmB;QACzC,KAAK,EAAE,CAAC;QAtFV,oDAAoD;QAC5C,oBAAe,GAAG,IAAI,GAAG,EAA8B,CAAC;QAgEhE;;;;WAIG;QACH,YAAO,GAAG,GAAS,EAAE;YACnB,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC;YAC7D,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;YAC7B,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YAErC,IAAI,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBACpC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACrC,CAAC;QACH,CAAC,CAAC;QASA,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF","sourcesContent":["import { ObservableEntity } from \"../Entities\";\r\nimport { AppObjectComponent } from \"./AppObjectComponent\";\r\nimport { AppObjectRepo } from \"./AppObjectRepo\";\r\n\r\n/**\r\n * AppObject is the central class in the VIVED application architecture.\r\n * It serves as a container for components that implement the application's functionality.\r\n * Each AppObject is identified by a unique ID and registered with an AppObjectRepo.\r\n * \r\n * AppObjects are observable entities that notify observers when their components change.\r\n * This enables reactive programming patterns throughout the application.\r\n */\r\nexport abstract class AppObject extends ObservableEntity {\r\n  /** Unique identifier for this AppObject */\r\n  abstract readonly id: string;\r\n  \r\n  /** Repository that manages this AppObject */\r\n  abstract readonly appObjectRepo: AppObjectRepo;\r\n\r\n  /**\r\n   * Checks if this AppObject has a component of the specified type\r\n   * @param type The component type identifier\r\n   * @returns True if the component exists, false otherwise\r\n   */\r\n  abstract hasComponent(type: string): boolean;\r\n  \r\n  /**\r\n   * Adds a component to this AppObject\r\n   * If a component of the same type already exists, it will be replaced\r\n   * @param component The component to add\r\n   */\r\n  abstract addComponent(component: AppObjectComponent): void;\r\n  \r\n  /**\r\n   * Retrieves a component by type\r\n   * @param type The component type identifier\r\n   * @returns The component cast to type T, or undefined if not found\r\n   */\r\n  abstract getComponent<T extends AppObjectComponent>(type: string): T | undefined;\r\n  \r\n  /**\r\n   * Removes a component by type\r\n   * @param type The component type identifier\r\n   */\r\n  abstract removeComponent(type: string): void;\r\n  \r\n  /**\r\n   * Gets all components attached to this AppObject\r\n   * @returns Array of all components\r\n   */\r\n  abstract allComponents(): AppObjectComponent[];\r\n\r\n  /**\r\n   * Cleans up resources and removes this AppObject from its repository\r\n   */\r\n  abstract dispose(): void;\r\n}\r\n\r\n/**\r\n * Factory function to create a new AppObject\r\n * @param id Unique identifier for the new AppObject\r\n * @param repo Repository to register the AppObject with\r\n * @returns A new AppObject instance\r\n */\r\nexport function makeAppObject(id: string, repo: AppObjectRepo): AppObject {\r\n  return new AppObjectImp(id, repo);\r\n}\r\n\r\n/**\r\n * Implementation of the AppObject abstract class\r\n * This class handles the component management functionality\r\n */\r\nclass AppObjectImp extends AppObject {\r\n  readonly id: string;\r\n  readonly appObjectRepo: AppObjectRepo;\r\n\r\n  /** Map of component types to component instances */\r\n  private componentLookup = new Map<string, AppObjectComponent>();\r\n\r\n  /**\r\n   * Checks if a component of the specified type exists\r\n   * @param type The component type identifier\r\n   * @returns True if the component exists, false otherwise\r\n   */\r\n  hasComponent(type: string): boolean {\r\n    return this.componentLookup.has(type);\r\n  }\r\n\r\n  /**\r\n   * Adds a component to this AppObject\r\n   * If a component of the same type already exists, it will be disposed and replaced\r\n   * Notifies observers after adding the component\r\n   * @param component The component to add\r\n   */\r\n  addComponent(component: AppObjectComponent): void {\r\n    const currentComponent = this.componentLookup.get(component.type);\r\n    if (currentComponent) {\r\n      console.warn(\r\n        `[AppObject] Component ${component.type} is being replaced on ${this.id}`\r\n      );\r\n      currentComponent.dispose();\r\n    }\r\n\r\n    this.componentLookup.set(component.type, component);\r\n    this.notify();\r\n  }\r\n\r\n  /**\r\n   * Retrieves a component by type\r\n   * @param type The component type identifier\r\n   * @returns The component cast to type T, or undefined if not found\r\n   */\r\n  getComponent<T extends AppObjectComponent>(type: string): T | undefined {\r\n    if (this.componentLookup.has(type)) {\r\n      return this.componentLookup.get(type) as T;\r\n    } else {\r\n      return undefined;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Removes a component by type and notifies observers\r\n   * @param type The component type identifier\r\n   */\r\n  removeComponent(type: string): void {\r\n    const component = this.componentLookup.get(type);\r\n\r\n    if (!component) return;\r\n\r\n    this.componentLookup.delete(type);\r\n    this.notify();\r\n  }\r\n\r\n  /**\r\n   * Gets all components attached to this AppObject\r\n   * @returns Array of all components\r\n   */\r\n  allComponents(): AppObjectComponent[] {\r\n    return Array.from(this.componentLookup.values());\r\n  }\r\n\r\n  /**\r\n   * Cleans up resources by:\r\n   * 1. Disposing all attached components\r\n   * 2. Removing this AppObject from its repository\r\n   */\r\n  dispose = (): void => {\r\n    const components = Array.from(this.componentLookup.values());\r\n    this.componentLookup.clear();\r\n    components.forEach(c => c.dispose());\r\n\r\n    if (this.appObjectRepo.has(this.id)) {\r\n      this.appObjectRepo.remove(this.id);\r\n    }\r\n  };\r\n\r\n  /**\r\n   * Creates a new AppObject instance\r\n   * @param id Unique identifier for this AppObject\r\n   * @param repo Repository to register with\r\n   */\r\n  constructor(id: string, repo: AppObjectRepo) {\r\n    super();\r\n    this.id = id;\r\n    this.appObjectRepo = repo;\r\n    this.appObjectRepo.add(this);\r\n  }\r\n}\r\n"]}

package/dist/cjs/AppObject/AppObjectComponent.js

@@ -1,19 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppObjectComponent = exports.AppObjectComponentType = void 0;
+/**
+ * Enumeration of the different types of components in the architecture.
+ * Each type serves a specific purpose in the application structure.
+ */
 var AppObjectComponentType;
 (function (AppObjectComponentType) {
+    /** Stores and manages application state */
     AppObjectComponentType["ENTITY"] = "Entity";
+    /** Transforms application state into view models */
     AppObjectComponentType["PM"] = "Presentation Manager";
+    /** Implements business logic and coordinates between layers */
     AppObjectComponentType["UC"] = "Use Case";
+    /** Handles user inputs and external events */
     AppObjectComponentType["CONTROLLER"] = "Controller";
+    /** Renders UI elements and interacts with the DOM/rendering system */
     AppObjectComponentType["VIEW"] = "View";
+    /** Default type for components that don't fit the standard categories */
     AppObjectComponentType["UNKNOWN"] = "Unknown";
 })(AppObjectComponentType || (exports.AppObjectComponentType = AppObjectComponentType = {}));
+/**
+ * Base class for all components in the AppObject architecture.
+ *
+ * Components attach to AppObjects and provide specific functionality based on their type.
+ * The architecture follows a clean separation of concerns, with each component type
+ * having a well-defined responsibility in the application.
+ *
+ * Components can communicate with each other through various mechanisms:
+ * - Direct access via parent AppObject
+ * - Repository-level singleton access
+ * - Observer patterns for reactive updates
+ */
 class AppObjectComponent {
+    /**
+     * Convenience accessor for the repository containing all AppObjects
+     * @returns The application's AppObjectRepo
+     */
     get appObjects() {
         return this.appObject.appObjectRepo;
     }
+    /**
+     * Retrieves a singleton component of the specified type from the repository
+     * Results are cached for better performance in repeated calls
+     *
+     * @param type The component type identifier to look up
+     * @returns The singleton component cast to type T, or undefined if not found
+     */
     getCachedSingleton(type) {
         if (!this.cachedComponents.has(type)) {
             const component = this.appObjects.getSingleton(type);
@@ -26,6 +59,13 @@ class AppObjectComponent {
         }
         return this.cachedComponents.get(type);
     }
+    /**
+     * Retrieves a component from the same AppObject as this component
+     * Results are cached for better performance in repeated calls
+     *
+     * @param type The component type identifier to look up
+     * @returns The component cast to type T, or undefined if not found
+     */
     getCachedLocalComponent(type) {
         if (!this.cachedComponents.has(type)) {
             const component = this.appObject.getComponent(type);
@@ -38,6 +78,14 @@ class AppObjectComponent {
         }
         return this.cachedComponents.get(type);
     }
+    /**
+     * Retrieves a singleton component from the repository with customizable logging
+     * Unlike getCachedSingleton, results are not cached
+     *
+     * @param type The component type identifier to look up
+     * @param logType The severity level for logging if component isn't found
+     * @returns The singleton component cast to type T, or undefined if not found
+     */
     getSingleton(type, logType = "WARN") {
         const comp = this.appObjects.getSingleton(type);
         if (!comp) {
@@ -56,22 +104,52 @@ class AppObjectComponent {
         }
         return comp;
     }
+    /**
+     * Cleans up resources used by this component
+     * Removes itself from the parent AppObject if it's still attached
+     */
     dispose() {
         if (this.appObject.getComponent(this.type) === this) {
             this.appObject.removeComponent(this.type);
         }
     }
+    /**
+     * Logs an informational message to the application's logging system
+     * Messages are prefixed with the AppObject ID and component type for easier debugging
+     *
+     * @param message The message to log
+     */
     log(message) {
         this.appObjects.submitLog(`${this.appObject.id}/${this.type}`, message);
     }
+    /**
+     * Logs a warning message to the application's logging system
+     * Messages are prefixed with the AppObject ID and component type for easier debugging
+     *
+     * @param message The warning message to log
+     */
     warn(message) {
         this.appObjects.submitWarning(`${this.appObject.id}/${this.type}`, message);
     }
+    /**
+     * Logs an error message to the application's logging system
+     * Messages are prefixed with the AppObject ID and component type for easier debugging
+     *
+     * @param message The error message to log
+     */
     error(message) {
         this.appObjects.submitError(`${this.appObject.id}/${this.type}`, message);
     }
+    /**
+     * Creates a new component and attaches it to the specified AppObject
+     *
+     * @param appObject The parent AppObject this component will be attached to
+     * @param type The unique type identifier for this component
+     */
     constructor(appObject, type) {
+        /** The type category of this component */
         this.componentType = AppObjectComponentType.UNKNOWN;
+        /** Cache for components to avoid repeated lookups */
         this.cachedComponents = new Map();
         this.appObject = appObject;
         this.type = type;

package/dist/cjs/AppObject/AppObjectComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"AppObjectComponent.js","sourceRoot":"","sources":["../../../src/AppObject/AppObjectComponent.ts"],"names":[],"mappings":"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","sourcesContent":["import { AppObject } from \"./AppObject\";\r\nimport { AppObjectRepo } from \"./AppObjectRepo\";\r\n\r\nexport enum AppObjectComponentType {\r\n  ENTITY = \"Entity\",\r\n  PM = \"Presentation Manager\",\r\n  UC = \"Use Case\",\r\n  CONTROLLER = \"Controller\",\r\n  VIEW = \"View\",\r\n  UNKNOWN = \"Unknown\",\r\n}\r\n\r\nexport class AppObjectComponent {\r\n  readonly componentType: AppObjectComponentType = AppObjectComponentType.UNKNOWN;\r\n  readonly type: string;\r\n  readonly appObject: AppObject;\r\n  get appObjects(): AppObjectRepo {\r\n    return this.appObject.appObjectRepo;\r\n  }\r\n\r\n  private cachedComponents = new Map<string, AppObjectComponent>();\r\n  getCachedSingleton<T extends AppObjectComponent>(\r\n    type: string\r\n  ): T | undefined {\r\n    if (!this.cachedComponents.has(type)) {\r\n      const component = this.appObjects.getSingleton(type);\r\n      if (!component) {\r\n        this.warn(\"Unable to get cached singleton type \" + type);\r\n      } else {\r\n        this.cachedComponents.set(type, component);\r\n      }\r\n    }\r\n\r\n    return this.cachedComponents.get(type) as T;\r\n  }\r\n\r\n  getCachedLocalComponent<T extends AppObjectComponent>(\r\n    type: string\r\n  ): T | undefined {\r\n    if (!this.cachedComponents.has(type)) {\r\n      const component = this.appObject.getComponent(type);\r\n\r\n      if (!component) {\r\n        this.warn(\"Unable to get local component of type \" + type);\r\n      } else {\r\n        this.cachedComponents.set(type, component);\r\n      }\r\n    }\r\n\r\n    return this.cachedComponents.get(type) as T;\r\n  }\r\n\r\n  getSingleton<T extends AppObjectComponent>(\r\n    type: string,\r\n    logType: \"LOG\" | \"WARN\" | \"ERROR\" = \"WARN\"\r\n  ): T | undefined {\r\n    const comp = this.appObjects.getSingleton<T>(type);\r\n\r\n    if (!comp) {\r\n      const msg = \"Unable to get singleton type \" + type;\r\n      switch (logType) {\r\n        case \"ERROR\":\r\n          this.error(msg);\r\n          break;\r\n        case \"LOG\":\r\n          this.log(msg);\r\n          break;\r\n        case \"WARN\":\r\n          this.warn(msg);\r\n          break;\r\n      }\r\n    }\r\n\r\n    return comp;\r\n  }\r\n\r\n  dispose() {\r\n    if (this.appObject.getComponent(this.type) === this) {\r\n      this.appObject.removeComponent(this.type);\r\n    }\r\n  }\r\n\r\n  log(message: string) {\r\n    this.appObjects.submitLog(`${this.appObject.id}/${this.type}`, message);\r\n  }\r\n\r\n  warn(message: string) {\r\n    this.appObjects.submitWarning(`${this.appObject.id}/${this.type}`, message);\r\n  }\r\n\r\n  error(message: string) {\r\n    this.appObjects.submitError(`${this.appObject.id}/${this.type}`, message);\r\n  }\r\n\r\n  constructor(appObject: AppObject, type: string) {\r\n    this.appObject = appObject;\r\n    this.type = type;\r\n    appObject.addComponent(this);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"AppObjectComponent.js","sourceRoot":"","sources":["../../../src/AppObject/AppObjectComponent.ts"],"names":[],"mappings":"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","sourcesContent":["import { AppObject } from \"./AppObject\";\r\nimport { AppObjectRepo } from \"./AppObjectRepo\";\r\n\r\n/**\r\n * Enumeration of the different types of components in the architecture.\r\n * Each type serves a specific purpose in the application structure.\r\n */\r\nexport enum AppObjectComponentType {\r\n  /** Stores and manages application state */\r\n  ENTITY = \"Entity\",\r\n  \r\n  /** Transforms application state into view models */\r\n  PM = \"Presentation Manager\",\r\n  \r\n  /** Implements business logic and coordinates between layers */\r\n  UC = \"Use Case\",\r\n  \r\n  /** Handles user inputs and external events */\r\n  CONTROLLER = \"Controller\",\r\n  \r\n  /** Renders UI elements and interacts with the DOM/rendering system */\r\n  VIEW = \"View\",\r\n  \r\n  /** Default type for components that don't fit the standard categories */\r\n  UNKNOWN = \"Unknown\",\r\n}\r\n\r\n/**\r\n * Base class for all components in the AppObject architecture.\r\n * \r\n * Components attach to AppObjects and provide specific functionality based on their type.\r\n * The architecture follows a clean separation of concerns, with each component type\r\n * having a well-defined responsibility in the application.\r\n * \r\n * Components can communicate with each other through various mechanisms:\r\n * - Direct access via parent AppObject\r\n * - Repository-level singleton access\r\n * - Observer patterns for reactive updates\r\n */\r\nexport class AppObjectComponent {\r\n  /** The type category of this component */\r\n  readonly componentType: AppObjectComponentType = AppObjectComponentType.UNKNOWN;\r\n  \r\n  /** Unique type identifier for this specific component */\r\n  readonly type: string;\r\n  \r\n  /** The parent AppObject this component is attached to */\r\n  readonly appObject: AppObject;\r\n  \r\n  /**\r\n   * Convenience accessor for the repository containing all AppObjects\r\n   * @returns The application's AppObjectRepo\r\n   */\r\n  get appObjects(): AppObjectRepo {\r\n    return this.appObject.appObjectRepo;\r\n  }\r\n\r\n  /** Cache for components to avoid repeated lookups */\r\n  private cachedComponents = new Map<string, AppObjectComponent>();\r\n  \r\n  /**\r\n   * Retrieves a singleton component of the specified type from the repository\r\n   * Results are cached for better performance in repeated calls\r\n   * \r\n   * @param type The component type identifier to look up\r\n   * @returns The singleton component cast to type T, or undefined if not found\r\n   */\r\n  getCachedSingleton<T extends AppObjectComponent>(\r\n    type: string\r\n  ): T | undefined {\r\n    if (!this.cachedComponents.has(type)) {\r\n      const component = this.appObjects.getSingleton(type);\r\n      if (!component) {\r\n        this.warn(\"Unable to get cached singleton type \" + type);\r\n      } else {\r\n        this.cachedComponents.set(type, component);\r\n      }\r\n    }\r\n\r\n    return this.cachedComponents.get(type) as T;\r\n  }\r\n\r\n  /**\r\n   * Retrieves a component from the same AppObject as this component\r\n   * Results are cached for better performance in repeated calls\r\n   * \r\n   * @param type The component type identifier to look up\r\n   * @returns The component cast to type T, or undefined if not found\r\n   */\r\n  getCachedLocalComponent<T extends AppObjectComponent>(\r\n    type: string\r\n  ): T | undefined {\r\n    if (!this.cachedComponents.has(type)) {\r\n      const component = this.appObject.getComponent(type);\r\n\r\n      if (!component) {\r\n        this.warn(\"Unable to get local component of type \" + type);\r\n      } else {\r\n        this.cachedComponents.set(type, component);\r\n      }\r\n    }\r\n\r\n    return this.cachedComponents.get(type) as T;\r\n  }\r\n\r\n  /**\r\n   * Retrieves a singleton component from the repository with customizable logging\r\n   * Unlike getCachedSingleton, results are not cached\r\n   * \r\n   * @param type The component type identifier to look up\r\n   * @param logType The severity level for logging if component isn't found\r\n   * @returns The singleton component cast to type T, or undefined if not found\r\n   */\r\n  getSingleton<T extends AppObjectComponent>(\r\n    type: string,\r\n    logType: \"LOG\" | \"WARN\" | \"ERROR\" = \"WARN\"\r\n  ): T | undefined {\r\n    const comp = this.appObjects.getSingleton<T>(type);\r\n\r\n    if (!comp) {\r\n      const msg = \"Unable to get singleton type \" + type;\r\n      switch (logType) {\r\n        case \"ERROR\":\r\n          this.error(msg);\r\n          break;\r\n        case \"LOG\":\r\n          this.log(msg);\r\n          break;\r\n        case \"WARN\":\r\n          this.warn(msg);\r\n          break;\r\n      }\r\n    }\r\n\r\n    return comp;\r\n  }\r\n\r\n  /**\r\n   * Cleans up resources used by this component\r\n   * Removes itself from the parent AppObject if it's still attached\r\n   */\r\n  dispose() {\r\n    if (this.appObject.getComponent(this.type) === this) {\r\n      this.appObject.removeComponent(this.type);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Logs an informational message to the application's logging system\r\n   * Messages are prefixed with the AppObject ID and component type for easier debugging\r\n   * \r\n   * @param message The message to log\r\n   */\r\n  log(message: string) {\r\n    this.appObjects.submitLog(`${this.appObject.id}/${this.type}`, message);\r\n  }\r\n\r\n  /**\r\n   * Logs a warning message to the application's logging system\r\n   * Messages are prefixed with the AppObject ID and component type for easier debugging\r\n   * \r\n   * @param message The warning message to log\r\n   */\r\n  warn(message: string) {\r\n    this.appObjects.submitWarning(`${this.appObject.id}/${this.type}`, message);\r\n  }\r\n\r\n  /**\r\n   * Logs an error message to the application's logging system\r\n   * Messages are prefixed with the AppObject ID and component type for easier debugging\r\n   * \r\n   * @param message The error message to log\r\n   */\r\n  error(message: string) {\r\n    this.appObjects.submitError(`${this.appObject.id}/${this.type}`, message);\r\n  }\r\n\r\n  /**\r\n   * Creates a new component and attaches it to the specified AppObject\r\n   * \r\n   * @param appObject The parent AppObject this component will be attached to\r\n   * @param type The unique type identifier for this component\r\n   */\r\n  constructor(appObject: AppObject, type: string) {\r\n    this.appObject = appObject;\r\n    this.type = type;\r\n    appObject.addComponent(this);\r\n  }\r\n}\r\n"]}

package/dist/cjs/AppObject/AppObjectController.js

@@ -2,9 +2,31 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppObjectController = void 0;
 const AppObjectComponent_1 = require("./AppObjectComponent");
+/**
+ * AppObjectController serves as a base controller class within the application framework.
+ *
+ * Controllers are components that handle logic-related operations for an AppObject,
+ * such as user input processing, state management, or business logic implementation.
+ * Extend this class to create specialized controllers for specific application features.
+ *
+ * @extends AppObjectComponent
+ * @example
+ * ```typescript
+ * class PlayerController extends AppObjectController {
+ *   handleUserInput(input: UserInput) {
+ *     // Process user input to control player object
+ *   }
+ * }
+ * ```
+ */
 class AppObjectController extends AppObjectComponent_1.AppObjectComponent {
     constructor() {
         super(...arguments);
+        /**
+         * The component type identifier used to categorize this component as a controller
+         * This property helps the component system identify and manage controller components.
+         * @readonly
+         */
         this.componentType = AppObjectComponent_1.AppObjectComponentType.CONTROLLER;
     }
 }

package/dist/cjs/AppObject/AppObjectController.js.map

@@ -1 +1 @@
-{"version":3,"file":"AppObjectController.js","sourceRoot":"","sources":["../../../src/AppObject/AppObjectController.ts"],"names":[],"mappings":";;;AAAA,6DAG8B;AAE9B,MAAa,mBAAoB,SAAQ,uCAAkB;IAA3D;;QACW,kBAAa,GAAG,2CAAsB,CAAC,UAAU,CAAC;IAC7D,CAAC;CAAA;AAFD,kDAEC","sourcesContent":["import {\r\n  AppObjectComponent,\r\n  AppObjectComponentType,\r\n} from \"./AppObjectComponent\";\r\n\r\nexport class AppObjectController extends AppObjectComponent {\r\n  readonly componentType = AppObjectComponentType.CONTROLLER;\r\n}\r\n"]}
+{"version":3,"file":"AppObjectController.js","sourceRoot":"","sources":["../../../src/AppObject/AppObjectController.ts"],"names":[],"mappings":";;;AAAA,6DAG8B;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,mBAAoB,SAAQ,uCAAkB;IAA3D;;QACE;;;;WAIG;QACM,kBAAa,GAAG,2CAAsB,CAAC,UAAU,CAAC;IAC7D,CAAC;CAAA;AAPD,kDAOC","sourcesContent":["import {\r\n  AppObjectComponent,\r\n  AppObjectComponentType,\r\n} from \"./AppObjectComponent\";\r\n\r\n/**\r\n * AppObjectController serves as a base controller class within the application framework.\r\n *\r\n * Controllers are components that handle logic-related operations for an AppObject,\r\n * such as user input processing, state management, or business logic implementation.\r\n * Extend this class to create specialized controllers for specific application features.\r\n *\r\n * @extends AppObjectComponent\r\n * @example\r\n * ```typescript\r\n * class PlayerController extends AppObjectController {\r\n *   handleUserInput(input: UserInput) {\r\n *     // Process user input to control player object\r\n *   }\r\n * }\r\n * ```\r\n */\r\nexport class AppObjectController extends AppObjectComponent {\r\n  /**\r\n   * The component type identifier used to categorize this component as a controller\r\n   * This property helps the component system identify and manage controller components.\r\n   * @readonly\r\n   */\r\n  readonly componentType = AppObjectComponentType.CONTROLLER;\r\n}\r\n"]}

package/dist/cjs/AppObject/AppObjectEntity.js

@@ -3,7 +3,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppObjectEntity = void 0;
 const Entities_1 = require("../Entities");
 const AppObjectComponent_1 = require("./AppObjectComponent");
+/**
+ * Entity component that manages application state
+ *
+ * AppObjectEntity is responsible for storing and managing state data within the application.
+ * It uses the observer pattern to notify interested parties of changes to its state.
+ *
+ * In a typical application flow:
+ * 1. Controllers modify entity state in response to user actions
+ * 2. Entities notify observers (typically PMs) of state changes
+ * 3. PMs transform entity state into view models
+ * 4. Views render based on the view models
+ */
 class AppObjectEntity extends AppObjectComponent_1.AppObjectComponent {
+    /**
+     * Cleans up resources and notifies dispose observers
+     *
+     * This method:
+     * 1. Removes the change observer from the parent AppObject
+     * 2. Notifies all dispose observers
+     * 3. Clears all observer lists
+     * 4. Calls the parent class dispose method
+     */
     dispose() {
         this.removeChangeObserver(this.appObject.notify);
         this.onDisposeObserverList.notify();
@@ -11,26 +32,57 @@ class AppObjectEntity extends AppObjectComponent_1.AppObjectComponent {
         this.onDisposeObserverList.clear();
         super.dispose();
     }
+    /**
+     * Creates a new entity component and attaches it to the specified AppObject
+     * Automatically adds the AppObject's notify method as a change observer
+     *
+     * @param appObject The parent AppObject this component will be attached to
+     * @param type The unique type identifier for this component
+     */
     constructor(appObject, type) {
         super(appObject, type);
+        /** Identifies this as an Entity component */
         this.componentType = AppObjectComponent_1.AppObjectComponentType.ENTITY;
+        /** List of observers to notify when this entity is disposed */
         this.onDisposeObserverList = new Entities_1.ObserverList();
+        /**
+         * Adds an observer to be notified when this entity is disposed
+         * @param observer Function to call on disposal
+         */
         this.addOnDisposeObserver = (observer) => {
             this.onDisposeObserverList.add(observer);
         };
+        /**
+         * Removes a previously added dispose observer
+         * @param observer The observer function to remove
+         */
         this.removeOnDisposeObserver = (observer) => {
             this.onDisposeObserverList.remove(observer);
         };
+        /** List of observers to notify when this entity's state changes */
         this.onChangeObserverList = new Entities_1.ObserverList();
+        /**
+         * Adds an observer to be notified when this entity's state changes
+         * @param observer Function to call on state change
+         */
         this.addChangeObserver = (observer) => {
             this.onChangeObserverList.add(observer);
         };
+        /**
+         * Removes a previously added change observer
+         * @param observer The observer function to remove
+         */
         this.removeChangeObserver = (observer) => {
             this.onChangeObserverList.remove(observer);
         };
+        /**
+         * Notifies all change observers that this entity's state has changed
+         * This should be called by derived classes when their state changes
+         */
         this.notifyOnChange = () => {
             this.onChangeObserverList.notify();
         };
+        // When this entity changes, notify the parent AppObject
         this.addChangeObserver(appObject.notify);
     }
 }

package/dist/cjs/AppObject/AppObjectEntity.js.map

@@ -1 +1 @@
-{"version":3,"file":"AppObjectEntity.js","sourceRoot":"","sources":["../../../src/AppObject/AppObjectEntity.ts"],"names":[],"mappings":";;;AAAA,0CAA2C;AAE3C,6DAAkF;AAIlF,MAAa,eAAgB,SAAQ,uCAAkB;IAuBrD,OAAO;QACL,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAEjD,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,CAAC;QACpC,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,qBAAqB,CAAC,KAAK,EAAE,CAAC;QAEnC,KAAK,CAAC,OAAO,EAAE,CAAC;IAClB,CAAC;IAED,YAAY,SAAoB,EAAE,IAAY;QAC5C,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;QAjCf,kBAAa,GAAG,2CAAsB,CAAC,MAAM,CAAC;QAE/C,0BAAqB,GAAG,IAAI,uBAAY,EAAQ,CAAC;QACzD,yBAAoB,GAAG,CAAC,QAAiC,EAAE,EAAE;YAC3D,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC3C,CAAC,CAAC;QACF,4BAAuB,GAAG,CAAC,QAAiC,EAAQ,EAAE;YACpE,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9C,CAAC,CAAC;QAEM,yBAAoB,GAAG,IAAI,uBAAY,EAAQ,CAAC;QACxD,sBAAiB,GAAG,CAAC,QAAiC,EAAQ,EAAE;YAC9D,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC,CAAC;QACF,yBAAoB,GAAG,CAAC,QAAiC,EAAQ,EAAE;YACjE,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7C,CAAC,CAAC;QAEF,mBAAc,GAAG,GAAG,EAAE;YACpB,IAAI,CAAC,oBAAoB,CAAC,MAAM,EAAE,CAAC;QACrC,CAAC,CAAC;QAeA,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;CACF;AAtCD,0CAsCC","sourcesContent":["import { ObserverList } from \"../Entities\";\r\nimport { AppObject } from \"./AppObject\";\r\nimport { AppObjectComponent, AppObjectComponentType } from \"./AppObjectComponent\";\r\n\r\nexport type AppObjectEntityObserver = () => void;\r\n\r\nexport class AppObjectEntity extends AppObjectComponent {\r\n  readonly componentType = AppObjectComponentType.ENTITY;\r\n  \r\n  private onDisposeObserverList = new ObserverList<void>();\r\n  addOnDisposeObserver = (observer: AppObjectEntityObserver) => {\r\n    this.onDisposeObserverList.add(observer);\r\n  };\r\n  removeOnDisposeObserver = (observer: AppObjectEntityObserver): void => {\r\n    this.onDisposeObserverList.remove(observer);\r\n  };\r\n\r\n  private onChangeObserverList = new ObserverList<void>();\r\n  addChangeObserver = (observer: AppObjectEntityObserver): void => {\r\n    this.onChangeObserverList.add(observer);\r\n  };\r\n  removeChangeObserver = (observer: AppObjectEntityObserver): void => {\r\n    this.onChangeObserverList.remove(observer);\r\n  };\r\n\r\n  notifyOnChange = () => {\r\n    this.onChangeObserverList.notify();\r\n  };\r\n\r\n  dispose() {\r\n    this.removeChangeObserver(this.appObject.notify);\r\n\r\n    this.onDisposeObserverList.notify();\r\n    this.onChangeObserverList.clear();\r\n    this.onDisposeObserverList.clear();\r\n\r\n    super.dispose();\r\n  }\r\n\r\n  constructor(appObject: AppObject, type: string) {\r\n    super(appObject, type)\r\n    \r\n    this.addChangeObserver(appObject.notify);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"AppObjectEntity.js","sourceRoot":"","sources":["../../../src/AppObject/AppObjectEntity.ts"],"names":[],"mappings":";;;AAAA,0CAA2C;AAE3C,6DAAkF;AAQlF;;;;;;;;;;;GAWG;AACH,MAAa,eAAgB,SAAQ,uCAAkB;IAkDrD;;;;;;;;OAQG;IACH,OAAO;QACL,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAEjD,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,CAAC;QACpC,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,qBAAqB,CAAC,KAAK,EAAE,CAAC;QAEnC,KAAK,CAAC,OAAO,EAAE,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACH,YAAY,SAAoB,EAAE,IAAY;QAC5C,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;QA5ExB,6CAA6C;QACpC,kBAAa,GAAG,2CAAsB,CAAC,MAAM,CAAC;QAEvD,+DAA+D;QACvD,0BAAqB,GAAG,IAAI,uBAAY,EAAQ,CAAC;QAEzD;;;WAGG;QACH,yBAAoB,GAAG,CAAC,QAAiC,EAAE,EAAE;YAC3D,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC3C,CAAC,CAAC;QAEF;;;WAGG;QACH,4BAAuB,GAAG,CAAC,QAAiC,EAAQ,EAAE;YACpE,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9C,CAAC,CAAC;QAEF,mEAAmE;QAC3D,yBAAoB,GAAG,IAAI,uBAAY,EAAQ,CAAC;QAExD;;;WAGG;QACH,sBAAiB,GAAG,CAAC,QAAiC,EAAQ,EAAE;YAC9D,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC,CAAC;QAEF;;;WAGG;QACH,yBAAoB,GAAG,CAAC,QAAiC,EAAQ,EAAE;YACjE,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7C,CAAC,CAAC;QAEF;;;WAGG;QACH,mBAAc,GAAG,GAAG,EAAE;YACpB,IAAI,CAAC,oBAAoB,CAAC,MAAM,EAAE,CAAC;QACrC,CAAC,CAAC;QA+BA,wDAAwD;QACxD,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;CACF;AAlFD,0CAkFC","sourcesContent":["import { ObserverList } from \"../Entities\";\r\nimport { AppObject } from \"./AppObject\";\r\nimport { AppObjectComponent, AppObjectComponentType } from \"./AppObjectComponent\";\r\n\r\n/**\r\n * Observer function type for entity state changes or disposal\r\n * No parameters are passed to the observer functions\r\n */\r\nexport type AppObjectEntityObserver = () => void;\r\n\r\n/**\r\n * Entity component that manages application state\r\n * \r\n * AppObjectEntity is responsible for storing and managing state data within the application.\r\n * It uses the observer pattern to notify interested parties of changes to its state.\r\n * \r\n * In a typical application flow:\r\n * 1. Controllers modify entity state in response to user actions\r\n * 2. Entities notify observers (typically PMs) of state changes\r\n * 3. PMs transform entity state into view models\r\n * 4. Views render based on the view models\r\n */\r\nexport class AppObjectEntity extends AppObjectComponent {\r\n  /** Identifies this as an Entity component */\r\n  readonly componentType = AppObjectComponentType.ENTITY;\r\n  \r\n  /** List of observers to notify when this entity is disposed */\r\n  private onDisposeObserverList = new ObserverList<void>();\r\n  \r\n  /**\r\n   * Adds an observer to be notified when this entity is disposed\r\n   * @param observer Function to call on disposal\r\n   */\r\n  addOnDisposeObserver = (observer: AppObjectEntityObserver) => {\r\n    this.onDisposeObserverList.add(observer);\r\n  };\r\n  \r\n  /**\r\n   * Removes a previously added dispose observer\r\n   * @param observer The observer function to remove\r\n   */\r\n  removeOnDisposeObserver = (observer: AppObjectEntityObserver): void => {\r\n    this.onDisposeObserverList.remove(observer);\r\n  };\r\n\r\n  /** List of observers to notify when this entity's state changes */\r\n  private onChangeObserverList = new ObserverList<void>();\r\n  \r\n  /**\r\n   * Adds an observer to be notified when this entity's state changes\r\n   * @param observer Function to call on state change\r\n   */\r\n  addChangeObserver = (observer: AppObjectEntityObserver): void => {\r\n    this.onChangeObserverList.add(observer);\r\n  };\r\n  \r\n  /**\r\n   * Removes a previously added change observer\r\n   * @param observer The observer function to remove\r\n   */\r\n  removeChangeObserver = (observer: AppObjectEntityObserver): void => {\r\n    this.onChangeObserverList.remove(observer);\r\n  };\r\n\r\n  /**\r\n   * Notifies all change observers that this entity's state has changed\r\n   * This should be called by derived classes when their state changes\r\n   */\r\n  notifyOnChange = () => {\r\n    this.onChangeObserverList.notify();\r\n  };\r\n\r\n  /**\r\n   * Cleans up resources and notifies dispose observers\r\n   * \r\n   * This method:\r\n   * 1. Removes the change observer from the parent AppObject\r\n   * 2. Notifies all dispose observers\r\n   * 3. Clears all observer lists\r\n   * 4. Calls the parent class dispose method\r\n   */\r\n  dispose() {\r\n    this.removeChangeObserver(this.appObject.notify);\r\n\r\n    this.onDisposeObserverList.notify();\r\n    this.onChangeObserverList.clear();\r\n    this.onDisposeObserverList.clear();\r\n\r\n    super.dispose();\r\n  }\r\n\r\n  /**\r\n   * Creates a new entity component and attaches it to the specified AppObject\r\n   * Automatically adds the AppObject's notify method as a change observer\r\n   * \r\n   * @param appObject The parent AppObject this component will be attached to\r\n   * @param type The unique type identifier for this component\r\n   */\r\n  constructor(appObject: AppObject, type: string) {\r\n    super(appObject, type)\r\n    \r\n    // When this entity changes, notify the parent AppObject\r\n    this.addChangeObserver(appObject.notify);\r\n  }\r\n}\r\n"]}