@vived/core 2.0.1 → 2.0.2

package/README.md

@@ -4,7 +4,7 @@ Core Components for VIVED Apps and Hosts
 
 ## Overview
 
-@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.
+`@vived/core` provides a comprehensive architecture framework for building scalable, maintainable applications using Clean Architecture principles. The library combines a component-based architecture (AppObject pattern) with reactive entities, immutable value objects, and utility functions optimized for 3D graphics and interactive applications.
 
 ## Installation
 
@@ -12,93 +12,303 @@ Core Components for VIVED Apps and Hosts
 npm install @vived/core
 ```
 
-## Core Concepts
+## Documentation
 
-The package is built around the "AppObject" architecture, which follows a component-based design pattern:
+This package includes comprehensive documentation for each module:
 
-### AppObject
+- **[AppObject Architecture](src/AppObject/README.md)** - Component-based architecture pattern with entities, use cases, presentation managers, views, and controllers
+- **[DomainFactories](src/DomainFactories/README.md)** - Multi-phase initialization system for organizing domain components
+- **[Entities](src/Entities/README.md)** - Observable entities with memoized properties for automatic change detection
+- **[ValueObjects](src/ValueObjects/README.md)** - Immutable mathematical primitives for 3D graphics and geometry
+- **[Utilities](src/Utilities/README.md)** - Helper functions for animations, colors, conversions, and file operations
+- **[Types](src/Types/README.md)** - TypeScript interfaces for adapters and application boundaries
+- **[ExampleFeature](src/ExampleFeature/README.md)** - Complete reference implementation demonstrating best practices
 
-- 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
+## Quick Start
 
-### AppObjectRepo
+### AppObject Architecture
 
-- Manages a collection of AppObjects 
-- Provides methods to find, create, and manage AppObjects
-- Handles singleton components across the application
-- Includes logging infrastructure for debugging
+The core architecture follows Clean Architecture dependency rules with a component-based design:
 
-### Component Types
+```typescript
+import { makeAppObjectRepo } from "@vived/core";
 
-The architecture implements a clean separation of concerns through specialized components:
+// Create the application repository
+const appObjects = makeAppObjectRepo();
 
-1. **Entity (AppObjectEntity)**
-   - Holds and manages application state
-   - Provides change notifications when state is modified
+// Create an AppObject
+const myObject = appObjects.getOrCreate("myObject");
 
-2. **Presentation Manager (AppObjectPM)**
-   - Manages view models for UI representation
-   - Transforms application state into UI-ready data
-   - Notifies views when view models change
+// Add components to it
+const entity = makeMyEntity(myObject);
+const useCase = makeMyUseCase(myObject);
+const presentationManager = makeMyPM(myObject);
+```
+
+**Key Components:**
+- **Entities** - Store and manage domain data with automatic change notifications
+- **Use Cases** - Implement business logic and operations
+- **Presentation Managers** - Transform entity data into view models for UI
+- **Controllers** - Provide simplified APIs for UI interactions
+- **Adapters** - Connect UI frameworks (React, Vue, etc.) to presentation managers
+
+### Domain Factories
+
+Organize features using domain factories with phased initialization:
+
+```typescript
+import { makeDomainFactoryRepo } from "@vived/core";
+
+// Create domain factory repository
+const domainFactoryRepo = makeDomainFactoryRepo(appObjects);
+
+// Create your feature factories
+new MyFeatureDomainFactory(appObjects.getOrCreate("MyFeature"));
+
+// Initialize all features in proper order
+domainFactoryRepo.setupDomain();
+```
+
+### Reactive Entities
+
+Build reactive data models with automatic change detection:
+
+```typescript
+import { MemoizedString, MemoizedNumber, ObservableEntity } from "@vived/core";
+
+class UserEntity extends ObservableEntity
+{
+	private nameProperty = new MemoizedString("", () => this.notify());
+	private ageProperty = new MemoizedNumber(0, () => this.notify());
+	
+	get name() { return this.nameProperty.val; }
+	set name(value: string) { this.nameProperty.val = value; }
+	
+	get age() { return this.ageProperty.val; }
+	set age(value: number) { this.ageProperty.val = value; }
+}
+
+// Changes automatically notify observers
+const user = new UserEntity();
+user.addObserver(() => console.log("User changed!"));
+user.name = "John"; // Triggers notification
+```
 
-3. **Use Case (AppObjectUC)**
-   - Implements business logic
-   - Coordinates between data layer and presentation
+### Value Objects for 3D Graphics
 
-4. **Controller (AppObjectController)**
-   - Handles external inputs (user actions, system events)
-   - Delegates to appropriate use cases
+Work with immutable mathematical primitives:
 
-5. **View (AppObjectView)**
-   - UI representation components
-   - Consumes view models and renders UI
+```typescript
+import { Vector3, Quaternion, Matrix, Color } from "@vived/core";
 
-## Example Implementation
+// Vector operations
+const position = new Vector3(10, 20, 30);
+const direction = Vector3.Forward();
+const sum = Vector3.Add(position, direction);
 
-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:
+// Rotations with quaternions
+const rotation = Quaternion.FromYawPitchRoll(
+	Angle.FromDegrees(45),
+	Angle.FromDegrees(0),
+	Angle.FromDegrees(0)
+);
+
+// Transformation matrices
+const transform = Matrix.Translation(position);
+const rotationMatrix = Matrix.FromQuaternion(rotation);
+
+// Colors
+const red = Color.RGB(255, 0, 0);
+const transparent = Color.RGBA(0, 0, 0, 128);
+const named = Color.X11("CornflowerBlue");
+```
+
+### Animation Utilities
+
+Create smooth animations with easing functions:
+
+```typescript
+import { LerpNumber, quintInOut } from "@vived/core";
+
+const lerper = new LerpNumber();
+
+// Animate a value from 0 to 100 over 2 seconds
+await lerper.lerp({
+	start: 0,
+	end: 100,
+	durationMS: 2000,
+	ease: quintInOut,
+	update: (value) => {
+		element.style.opacity = value / 100;
+	},
+	onComplete: () => {
+		console.log("Animation complete!");
+	}
+});
+```
+
+### UI Integration with Adapters
+
+Connect your UI framework to the architecture:
+
+```typescript
+import { useEffect, useState } from "react";
+import { myFeatureAdapter } from "@vived/core";
+
+function MyComponent({ id, appObjects })
+{
+	const [viewModel, setViewModel] = useState(myFeatureAdapter.defaultVM);
+	
+	useEffect(() => {
+		// Subscribe to updates
+		myFeatureAdapter.subscribe(id, appObjects, setViewModel);
+		
+		// Cleanup on unmount
+		return () => {
+			myFeatureAdapter.unsubscribe(id, appObjects, setViewModel);
+		};
+	}, [id]);
+	
+	return <div>{viewModel.someProperty}</div>;
+}
+```
 
-### 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
-- **Factory/** - Factories for creating the features at runtime
+## Package Contents
 
-Refer to the `ExampleFeature` directory for a complete implementation example that shows the interaction between all component types.
+### Architecture Components
 
-## Value Objects
+- **AppObject System** - Component container pattern with dependency injection
+- **Entity System** - Observable entities with memoized properties
+- **Repository Pattern** - Manage collections of entities
+- **Use Cases** - Business logic layer
+- **Presentation Managers** - View model transformation layer
+- **Controllers** - Simplified UI interaction APIs
+- **Adapters** - Framework-agnostic UI integration
 
-The package provides immutable value objects for mathematical and graphical operations:
+### Value Objects
 
-### 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
+**Vectors & Geometry:**
+- Vector2, Vector3 - 2D and 3D vectors with full operations
+- Quaternion - 3D rotation representation
+- Matrix - 4x4 transformation matrices
+- Angle - Type-safe angle conversions
+- Rectangle - 2D rectangular bounds
+- LineSegment2D - 2D line segment operations
+- ParametricLine - 3D parametric line representation
+- ParametricPlane - 3D plane representation
 
-### 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:**
+- Color - RGBA color with hex and X11 color support
 
-### Graphics & Utilities
-- **Color**: RGBA color representation with utility methods for conversion between formats (RGB, Hex, X11 names)
-- **Version**: Semantic versioning implementation with comparison operators
+**Versioning:**
+- Version - Semantic version parsing and comparison
 
-## Utilities
+### 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
+**Animation:**
+- LerpNumber - Smooth numeric interpolation
+- Easing functions - 20+ easing functions (quad, cubic, quart, quint, sin, expo, circ)
+- interpolateNumber - Basic numeric interpolation
+
+**Color:**
+- addAlphaToHex - Add transparency to hex colors
+- alphaToHex - Convert alpha values to hex
+
+**Conversion:**
+- degreesToRadians - Angle conversion
+- Length converters - Inches/feet to meters and vice versa
+
+**File Operations:**
+- downloadFile - Trigger browser downloads
+- generateUniqueID - UUID v4 generation
+
+### Types
+
+- PmAdapter - Interface for connecting UI to presentation managers
+- SingletonPmAdapter - Interface for singleton presentation managers
+- EaseFn - Type definition for easing functions
+- AppBoundary - Application embedding interfaces
+
+## Architecture Principles
+
+### Clean Architecture
+
+The library enforces dependency rules where inner layers never depend on outer layers:
+
+```
+UI Layer
+    ↓
+Adapters & Controllers
+    ↓
+Presentation Managers
+    ↓
+Use Cases
+    ↓
+Entities
+```
+
+### Component-Based Design
+
+Everything is a component attached to an AppObject:
+- Promotes composition over inheritance
+- Enables dependency injection
+- Facilitates testing with mock components
+- Supports both instance and singleton patterns
+
+### Reactive by Default
+
+Entities notify observers when they change:
+- Automatic UI updates
+- No manual refresh logic needed
+- Performance optimized with memoization
+
+### Immutable Value Objects
+
+Mathematical primitives are immutable:
+- Thread-safe operations
+- Predictable behavior
+- Easy to reason about
+- Optimal for 3D graphics pipelines
+
+## Example Feature
+
+See [ExampleFeature](src/ExampleFeature/README.md) for a complete, production-ready reference implementation showing:
+- Feature folder structure
+- Entity, Use Case, and PM implementation
+- Controller and Adapter patterns
+- React integration examples
+- Testing strategies
+- Factory-based initialization
+
+## Use Cases
+
+- **3D Graphics Applications** - WebGL, Three.js, Babylon.js applications
+- **VR/AR Experiences** - Interactive virtual environments
+- **Data Visualization** - Charts, graphs, and interactive dashboards
+- **Game Development** - Game engines and interactive experiences
+- **Educational Software** - Interactive learning applications
+- **Configuration Tools** - Complex application settings and preferences
+
+## TypeScript Support
+
+Fully typed with TypeScript definitions included. Supports both ESM and CommonJS:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  }
+}
+```
+
+## Contributing
+
+This is a foundational library for VIVED applications. For detailed architecture decisions and patterns, refer to the comprehensive documentation in each module's README.
 
 ## License
+
 ISC

package/dist/cjs/ExampleFeature/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Controllers
+__exportStar(require("./Controllers/setExampleText"), exports);
+__exportStar(require("./Controllers/toggleExampleBoolean"), exports);
+// Adapters
+__exportStar(require("./Adapters/examplePmAdapter"), exports);
+__exportStar(require("./Adapters/exampleSingletonPmAdapter"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/ExampleFeature/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ExampleFeature/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,cAAc;AACd,+DAA6C;AAC7C,qEAAmD;AAEnD,WAAW;AACX,8DAA4C;AAC5C,uEAAqD","sourcesContent":["// Controllers\r\nexport * from \"./Controllers/setExampleText\";\r\nexport * from \"./Controllers/toggleExampleBoolean\";\r\n\r\n// Adapters\r\nexport * from \"./Adapters/examplePmAdapter\";\r\nexport * from \"./Adapters/exampleSingletonPmAdapter\";\r\n"]}

package/dist/esm/ExampleFeature/index.js

@@ -0,0 +1,7 @@
+// Controllers
+export * from "./Controllers/setExampleText";
+export * from "./Controllers/toggleExampleBoolean";
+// Adapters
+export * from "./Adapters/examplePmAdapter";
+export * from "./Adapters/exampleSingletonPmAdapter";
+//# sourceMappingURL=index.js.map

package/dist/esm/ExampleFeature/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ExampleFeature/index.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AAEnD,WAAW;AACX,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sCAAsC,CAAC","sourcesContent":["// Controllers\r\nexport * from \"./Controllers/setExampleText\";\r\nexport * from \"./Controllers/toggleExampleBoolean\";\r\n\r\n// Adapters\r\nexport * from \"./Adapters/examplePmAdapter\";\r\nexport * from \"./Adapters/exampleSingletonPmAdapter\";\r\n"]}

package/dist/types/ExampleFeature/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./Controllers/setExampleText";
+export * from "./Controllers/toggleExampleBoolean";
+export * from "./Adapters/examplePmAdapter";
+export * from "./Adapters/exampleSingletonPmAdapter";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/ExampleFeature/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ExampleFeature/index.ts"],"names":[],"mappings":"AACA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AAGnD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sCAAsC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vived/core",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Core Components for VIVED Apps and Hosts",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -55,6 +55,7 @@
     "uuid": "^11.1.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/**/README.md"
   ]
 }