@vived/core 2.0.1 → 2.0.2

package/src/Types/README.md

@@ -0,0 +1,549 @@
+# Types
+
+The Types folder provides TypeScript type definitions and interfaces that establish contracts for key architectural patterns in the application. These types enable type-safe communication between different layers of the architecture.
+
+## Overview
+
+This module contains:
+- **Function Types** - Type aliases for common function signatures
+- **Adapter Interfaces** - Contracts for connecting UI components to presentation managers
+- **Application Boundaries** - Types defining external application interfaces
+
+## Function Types
+
+### EaseFn
+
+Type definition for easing functions used in animations.
+
+```typescript
+import { EaseFn } from "@vived/core";
+
+type EaseFn = (p: number) => number;
+
+// Implementation example
+const customEase: EaseFn = (p: number) => {
+	// Transform progress value (0-1)
+	return p * p; // Quadratic easing
+};
+
+// Usage with interpolation
+function animate(start: number, end: number, progress: number, ease: EaseFn): number
+{
+	const easedProgress = ease(progress);
+	return start + (end - start) * easedProgress;
+}
+
+// All built-in easing functions match this type
+import { quadInOut, expoOut } from "@vived/core";
+const ease1: EaseFn = quadInOut;
+const ease2: EaseFn = expoOut;
+```
+
+**Contract:**
+- Input: Number from 0 to 1 representing linear progress
+- Output: Number from 0 to 1 representing eased progress
+- Should handle edge cases (values < 0 or > 1)
+
+## Presentation Manager Adapters
+
+Adapters bridge the gap between UI frameworks (React, Vue, Angular, etc.) and the application's presentation layer. They provide a framework-agnostic way to subscribe to view model updates.
+
+### PmAdapter
+
+Interface for connecting UI components to AppObject-specific presentation managers.
+
+```typescript
+import { PmAdapter, AppObjectRepo } from "@vived/core";
+
+// Define your view model type
+interface CounterViewModel
+{
+	count: number;
+	label: string;
+	isEven: boolean;
+}
+
+// Implement the adapter
+class CounterPmAdapter implements PmAdapter<CounterViewModel>
+{
+	// Default view model prevents null/undefined in UI
+	defaultVM: CounterViewModel = {
+		count: 0,
+		label: "Counter",
+		isEven: true
+	};
+
+	subscribe(
+		id: string,
+		appObjects: AppObjectRepo,
+		setVM: (vm: CounterViewModel) => void
+	): void
+	{
+		// Get the specific AppObject
+		const appObject = appObjects.get(id);
+		if (!appObject) return;
+
+		// Get its presentation manager
+		const pm = appObject.getComponent<CounterPM>("CounterPM");
+		if (!pm) return;
+
+		// Subscribe to updates
+		pm.addView(setVM);
+
+		// Provide initial value if available
+		if (pm.lastVM)
+		{
+			setVM(pm.lastVM);
+		}
+	}
+
+	unsubscribe(
+		id: string,
+		appObjects: AppObjectRepo,
+		setVM: (vm: CounterViewModel) => void
+	): void
+	{
+		const appObject = appObjects.get(id);
+		if (!appObject) return;
+
+		const pm = appObject.getComponent<CounterPM>("CounterPM");
+		if (pm)
+		{
+			pm.removeView(setVM);
+		}
+	}
+}
+```
+
+**Usage in React:**
+
+```typescript
+import { useEffect, useState } from "react";
+
+function CounterComponent({ counterId, appObjects }: Props)
+{
+	const adapter = new CounterPmAdapter();
+	const [vm, setVM] = useState(adapter.defaultVM);
+
+	useEffect(() => {
+		// Subscribe when component mounts
+		adapter.subscribe(counterId, appObjects, setVM);
+
+		// Unsubscribe when component unmounts
+		return () => {
+			adapter.unsubscribe(counterId, appObjects, setVM);
+		};
+	}, [counterId]);
+
+	return (
+		<div>
+			<h2>{vm.label}</h2>
+			<p>Count: {vm.count}</p>
+			<p>{vm.isEven ? "Even" : "Odd"}</p>
+		</div>
+	);
+}
+```
+
+**When to use:**
+- Multiple instances of the same UI component
+- Each component subscribes to a different AppObject
+- Dynamic component creation with different data sources
+
+### SingletonPmAdapter
+
+Interface for connecting UI components to singleton presentation managers (only one instance in the application).
+
+```typescript
+import { SingletonPmAdapter, AppObjectRepo } from "@vived/core";
+
+// Define your view model type
+interface GlobalSettingsViewModel
+{
+	theme: "light" | "dark";
+	fontSize: "small" | "medium" | "large";
+	language: string;
+}
+
+// Implement the singleton adapter
+class SettingsPmAdapter implements SingletonPmAdapter<GlobalSettingsViewModel>
+{
+	defaultVM: GlobalSettingsViewModel = {
+		theme: "light",
+		fontSize: "medium",
+		language: "en"
+	};
+
+	subscribe(
+		appObjects: AppObjectRepo,
+		setVM: (vm: GlobalSettingsViewModel) => void
+	): void
+	{
+		// Get the singleton presentation manager
+		const settingsPM = SettingsPM.get(appObjects);
+		if (!settingsPM) return;
+
+		// Subscribe to updates
+		settingsPM.addView(setVM);
+
+		// Provide initial value
+		if (settingsPM.lastVM)
+		{
+			setVM(settingsPM.lastVM);
+		}
+	}
+
+	unsubscribe(
+		appObjects: AppObjectRepo,
+		setVM: (vm: GlobalSettingsViewModel) => void
+	): void
+	{
+		const settingsPM = SettingsPM.get(appObjects);
+		if (settingsPM)
+		{
+			settingsPM.removeView(setVM);
+		}
+	}
+}
+```
+
+**Usage in React:**
+
+```typescript
+import { useEffect, useState } from "react";
+
+function SettingsPanel({ appObjects }: Props)
+{
+	const adapter = new SettingsPmAdapter();
+	const [vm, setVM] = useState(adapter.defaultVM);
+
+	useEffect(() => {
+		// No ID needed - singleton PM
+		adapter.subscribe(appObjects, setVM);
+
+		return () => {
+			adapter.unsubscribe(appObjects, setVM);
+		};
+	}, []); // Empty deps - singleton never changes
+
+	return (
+		<div className={vm.theme}>
+			<select value={vm.fontSize}>
+				<option value="small">Small</option>
+				<option value="medium">Medium</option>
+				<option value="large">Large</option>
+			</select>
+			<select value={vm.language}>
+				<option value="en">English</option>
+				<option value="es">Spanish</option>
+			</select>
+		</div>
+	);
+}
+```
+
+**When to use:**
+- Global application state
+- Settings or configuration that's app-wide
+- Single-instance services (authentication, notifications, etc.)
+
+**Key difference from PmAdapter:**
+- No `id` parameter needed
+- Subscribe directly to singleton PM
+- Simpler API for single-instance scenarios
+
+## Application Boundary Types
+
+### AppBoundary Types
+
+Types defining the contract between embedded applications and their host environments.
+
+```typescript
+import { Handler, Request, VIVEDApp_3 } from "@vived/core";
+
+// Function that handles requests
+type Handler = (request: Request) => void;
+
+// Request structure for communication
+interface Request
+{
+	type: string;      // Action identifier
+	version: number;   // API version
+	payload?: unknown; // Optional data
+}
+
+// Application interface for embedding
+interface VIVEDApp_3
+{
+	// Mount app with bidirectional communication
+	mount(hostRequestHandler: Handler): Handler;
+	
+	// Mount app in development mode
+	mountDev(container: HTMLElement): void;
+}
+```
+
+**Usage - Embedding an Application:**
+
+```typescript
+class MyEmbeddedApp implements VIVEDApp_3
+{
+	mount(hostRequestHandler: Handler): Handler
+	{
+		// Store host's handler for sending requests to host
+		this.hostHandler = hostRequestHandler;
+
+		// Return our handler for receiving requests from host
+		return (request: Request) => {
+			this.handleHostRequest(request);
+		};
+	}
+
+	mountDev(container: HTMLElement): void
+	{
+		// Mount in standalone development mode
+		this.container = container;
+		this.initializeApp();
+	}
+
+	private handleHostRequest(request: Request): void
+	{
+		switch (request.type)
+		{
+			case "LOAD_DATA":
+				this.loadData(request.payload);
+				break;
+			case "UPDATE_SETTINGS":
+				this.updateSettings(request.payload);
+				break;
+		}
+	}
+
+	private sendRequestToHost(type: string, payload?: unknown): void
+	{
+		if (this.hostHandler)
+		{
+			this.hostHandler({
+				type,
+				version: 3,
+				payload
+			});
+		}
+	}
+
+	private hostHandler?: Handler;
+	private container?: HTMLElement;
+}
+```
+
+**Usage - Hosting an Application:**
+
+```typescript
+function embedApplication(app: VIVEDApp_3)
+{
+	// Create handler for app's requests
+	const hostHandler: Handler = (request: Request) => {
+		console.log(`App sent: ${request.type}`, request.payload);
+		
+		switch (request.type)
+		{
+			case "READY":
+				console.log("App is ready");
+				break;
+			case "REQUEST_DATA":
+				sendDataToApp(request.payload);
+				break;
+		}
+	};
+
+	// Mount app and get its handler
+	const appHandler = app.mount(hostHandler);
+
+	// Send request to app
+	appHandler({
+		type: "INITIALIZE",
+		version: 3,
+		payload: { config: {...} }
+	});
+}
+
+// Development mode
+function developApp(app: VIVEDApp_3)
+{
+	const container = document.getElementById("app-root");
+	if (container)
+	{
+		app.mountDev(container);
+	}
+}
+```
+
+## Design Patterns
+
+### Adapter Pattern
+
+The PM adapters implement the Adapter pattern, allowing UI frameworks to work with the application's architecture without tight coupling.
+
+**Benefits:**
+- Framework independence
+- Testable UI logic
+- Consistent data flow
+- Type safety
+
+### Observer Pattern
+
+Adapters facilitate the Observer pattern between presentation managers and UI components:
+
+```typescript
+// PM notifies observers (UI components) when view model changes
+class MyPM extends AppObjectPM<MyViewModel>
+{
+	updateData(newData: Data): void
+	{
+		// Transform data to view model
+		const vm = this.createViewModel(newData);
+		
+		// Notify all subscribed views
+		this.notifyViews(vm);
+	}
+}
+
+// Adapter subscribes UI component as an observer
+adapter.subscribe(id, appObjects, (vm) => {
+	// UI updates automatically when VM changes
+	updateUI(vm);
+});
+```
+
+### Default View Model Pattern
+
+The `defaultVM` property implements the Null Object pattern, providing a safe default state:
+
+```typescript
+// Instead of null checking
+if (vm !== null)
+{
+	render(vm.value);
+}
+
+// Use default VM
+const vm = adapter.defaultVM; // Always defined
+render(vm.value); // Safe
+```
+
+## Best Practices
+
+### Type Safety
+
+Use generics to maintain type safety throughout the adapter chain:
+
+```typescript
+class TypeSafeAdapter implements PmAdapter<MyViewModel>
+{
+	defaultVM: MyViewModel = { /* ... */ };
+	
+	subscribe(
+		id: string,
+		appObjects: AppObjectRepo,
+		setVM: (vm: MyViewModel) => void // Type-safe callback
+	): void { /* ... */ }
+}
+```
+
+### Memory Management
+
+Always unsubscribe to prevent memory leaks:
+
+```typescript
+useEffect(() => {
+	adapter.subscribe(id, appObjects, setVM);
+	
+	// Critical: cleanup on unmount
+	return () => {
+		adapter.unsubscribe(id, appObjects, setVM);
+	};
+}, [id]);
+```
+
+### Error Handling
+
+Adapters should handle missing components gracefully:
+
+```typescript
+subscribe(id: string, appObjects: AppObjectRepo, setVM: (vm: VM) => void): void
+{
+	const appObject = appObjects.get(id);
+	if (!appObject)
+	{
+		console.warn(`AppObject not found: ${id}`);
+		return; // Fail gracefully
+	}
+	
+	const pm = appObject.getComponent<MyPM>("MyPM");
+	if (!pm)
+	{
+		console.warn(`PM not found in AppObject: ${id}`);
+		return;
+	}
+	
+	pm.addView(setVM);
+}
+```
+
+### Singleton Access
+
+Use static accessor methods for singleton PMs:
+
+```typescript
+class MySingletonPM extends AppObjectSingletonPM<VM>
+{
+	static get(appObjects: AppObjectRepo): MySingletonPM | undefined
+	{
+		return getSingletonComponent<MySingletonPM>("MySingletonPM", appObjects);
+	}
+}
+
+// In adapter
+const pm = MySingletonPM.get(appObjects); // Type-safe access
+```
+
+## Use Cases
+
+- **UI Framework Integration** - Connect React/Vue/Angular to presentation layer
+- **Cross-Framework Compatibility** - Write adapters once, use in any framework
+- **Animation Systems** - Type-safe easing functions
+- **Embedded Applications** - Host/guest communication contracts
+- **Global State Management** - Singleton adapters for app-wide state
+- **Component Libraries** - Reusable adapters for common UI patterns
+
+## Testing
+
+Adapters are easily testable in isolation:
+
+```typescript
+describe("CounterPmAdapter", () => {
+	let adapter: CounterPmAdapter;
+	let mockAppObjects: AppObjectRepo;
+	let mockSetVM: jest.Mock;
+
+	beforeEach(() => {
+		adapter = new CounterPmAdapter();
+		mockAppObjects = createMockAppObjectRepo();
+		mockSetVM = jest.fn();
+	});
+
+	it("subscribes to presentation manager", () => {
+		adapter.subscribe("counter-1", mockAppObjects, mockSetVM);
+		
+		// Verify subscription happened
+		expect(mockSetVM).toHaveBeenCalledWith(expect.objectContaining({
+			count: expect.any(Number)
+		}));
+	});
+
+	it("provides default VM", () => {
+		expect(adapter.defaultVM).toBeDefined();
+		expect(adapter.defaultVM.count).toBe(0);
+	});
+});
+```