@plotinus/matrix-package-observable-coordinator
Version:
Observable coordinator pattern components using IntrospectableBaseCommunicationComponent and proper presentation architecture
323 lines (319 loc) • 22.7 kB
JavaScript
/**
* ========================================================================================================
* 🎯 APP PRESENTATION ELEMENT - REAL-TIME INTROSPECTION UI COMPONENT
* ========================================================================================================
*
* This custom HTML element demonstrates the PRESENTATION LAYER of the Matrix Framework's
* IntrospectableBaseCommunicationComponent pattern. It provides real-time visualization
* of observable state changes and events from the AppComponent communication layer.
*
* 🔥 INTROSPECTION PATTERNS DEMONSTRATED:
* ────────────────────────────────────────────────────────────────────────────────────────────────────
* • Real-time State Observation: Listens to _stateChanged events for automatic UI updates
* • Property-Level Tracking: Responds to _propertyChanged events for granular change detection
* • Event Emission Monitoring: Observes _eventEmitted events for complete system transparency
* • Two-Way Communication: UI interactions trigger communication component methods
* • Presentation Layer Separation: Pure presentation logic separate from business logic
*
* 🎭 PRESENTATION RESPONSIBILITIES:
* ────────────────────────────────────────────────────────────────────────────────────────────────────
* • Subscribe to introspection events from bound communication component
* • Provide real-time UI updates based on observable state changes
* • Display system status: coordinator readiness, processing state, job completion
* • Offer UI controls for triggering system operations (Start Processing button)
* • Maintain presentation-specific state (log messages, UI interactions)
*
* 🚀 EVENT-DRIVEN UI LIFECYCLE:
* ────────────────────────────────────────────────────────────────────────────────────────────────────
* 1. bindTo() → Subscribe to communication component's introspection events
* 2. onStateChanged() → Re-render UI when observable state changes
* 3. onPropertyChanged() → Update specific UI elements when individual properties change
* 4. User interactions → Trigger communication component methods via direct calls
* 5. Log display → Track all events and state changes for debugging visibility
*
* ========================================================================================================
*/
/**
* 🎯 AppPresentationElement - Custom Element for Observable State Visualization
*
* Extends HTMLElement to provide:
* • Shadow DOM encapsulation for isolated presentation styling
* • Event-driven UI updates based on communication component introspection
* • Real-time logging and state display for system transparency
* • User interaction controls that trigger communication component methods
*/
export class AppPresentationElement extends HTMLElement {
/**
* 🏗️ Element Construction - Setting Up Presentation Infrastructure
* ══════════════════════════════════════════════════════════════════════════════════════════════════
*
* Initializes the custom element with Shadow DOM and presentation-specific state.
* This demonstrates clean separation between presentation state (logMessages)
* and communication component state (managed by AppComponent).
*/
constructor() {
super();
this.logMessages = [];
// 📝 PRESENTATION STATE: UI-specific data separate from communication component
this.logMessages = []; // Array of log messages for UI display
// 🔍 DEBUGGING: Track element lifecycle for transparency
console.log('🏗️ AppPresentationElement: Constructor called');
// 🎭 SHADOW DOM SETUP: Encapsulated styling and structure
this.attachShadow({ mode: 'open' });
// 📋 INITIAL LOG: Track element creation in UI log
this.logToUI('🏗️ AppPresentation element constructed');
}
/**
* 🔗 Component Binding - The Core Introspection Connection
* ══════════════════════════════════════════════════════════════════════════════════════════════════
*
* This method establishes the CRITICAL connection between the presentation layer and the
* communication component's introspection system. It subscribes to three key introspection
* events that enable real-time UI updates based on observable state changes.
*
* INTROSPECTION EVENTS SUBSCRIBED:
* • _stateChanged: Full state object updates (triggers complete UI re-render)
* • _propertyChanged: Individual property updates (triggers targeted UI updates)
* • _eventEmitted: Component event emissions (for debugging and system transparency)
*/
bindTo(commComponent) {
console.log(`🔗 AppPresentation: bindTo() called with:`, commComponent?.id || 'undefined');
this.logToUI(`🔗 bindTo() called with: ${commComponent?.id || 'undefined'}`);
// 🎯 STORE COMMUNICATION COMPONENT REFERENCE: Enable direct method calls from UI
this.commComponent = commComponent;
// 🎧 INTROSPECTION EVENT SUBSCRIPTIONS: The heart of observable UI patterns
// ──────────────────────────────────────────────────────────────────────────────────────────────
if (commComponent.eventBus) {
console.log(`👂 AppPresentation: Setting up event listeners for ${commComponent.id}`);
// 🔄 STATE CHANGE SUBSCRIPTION: Complete state object updates
// ──────────────────────────────────────────────────────────────────────────────────────────
// Triggered when AppComponent calls setState() with full or partial state updates
// Results in complete UI re-render to reflect new system status
commComponent.eventBus.on(`cmp:${commComponent.id}:_stateChanged`, (data) => {
console.log(`🎯 AppPresentation: Received _stateChanged event:`, data);
this.onStateChanged(data.state);
});
// 📝 PROPERTY CHANGE SUBSCRIPTION: Individual property updates
// ──────────────────────────────────────────────────────────────────────────────────────────
// Triggered for each individual property when setState() modifies specific fields
// Enables granular UI updates and detailed change tracking
commComponent.eventBus.on(`cmp:${commComponent.id}:_propertyChanged`, (data) => {
console.log(`🎯 AppPresentation: Received _propertyChanged event:`, data);
this.onPropertyChanged(data.propertyName, data.newValue, data.oldValue);
});
// 📡 EVENT EMISSION SUBSCRIPTION: Component event tracking
// ──────────────────────────────────────────────────────────────────────────────────────────
// Triggered when AppComponent calls emitEvent() for inter-component communication
// Provides complete system transparency for debugging and monitoring
commComponent.eventBus.on(`cmp:${commComponent.id}:_eventEmitted`, (data) => {
console.log(`🎯 AppPresentation: Received _eventEmitted event:`, data);
// Could add UI indicators for events emitted, notifications, etc.
});
console.log(`✅ AppPresentation: Event listeners registered for ${commComponent.id}`);
}
else {
console.warn(`⚠️ AppPresentation: No eventBus found on communication component!`);
}
// 🎨 INITIAL RENDER: Display current state immediately after binding
this.render();
}
/**
* 🎨 UI Rendering - State-Driven Dynamic Display
* ══════════════════════════════════════════════════════════════════════════════════════════════════
*
* This method demonstrates REACTIVE UI PATTERNS where the presentation layer
* automatically updates based on observable state changes from the communication component.
* It transforms abstract state data into visual indicators and user-friendly status displays.
*
* RENDERING PATTERNS DEMONSTRATED:
* • State-to-UI Mapping: Convert boolean/array state to visual status indicators
* • Conditional UI Elements: Show/hide elements based on state values
* • Real-time Data Binding: Automatic UI updates when state changes via introspection
* • Presentation State Integration: Combine communication state with UI-specific data
*/
render() {
console.log(`🎨 AppPresentation: Rendering with current state:`, this.commComponent?.state);
// 🔍 AVOID INFINITE LOOPS: Don't call logToUI here as render() is called from onStateChanged()
// 📊 STATE EXTRACTION: Get current observable state from communication component
const state = this.commComponent?.state || {};
// 🎯 STATE-TO-UI MAPPING: Transform abstract state into visual indicators
// ──────────────────────────────────────────────────────────────────────────────────────────────
const coordinatorStatus = state.coordinatorReady ? '✅ Ready' : '⏳ Waiting';
const processingStatus = state.processingStarted ? '🔄 Processing' : '⏸️ Idle';
const completionStatus = state.systemCompleted ? '✅ Complete' : '🔄 In Progress';
const jobCount = state.completedJobs?.length || 0;
// 🎭 SHADOW DOM CONTENT: Complete UI structure with state-driven content
// ──────────────────────────────────────────────────────────────────────────────────────────────
// This demonstrates how presentation layer renders dynamic content based on
// observable state from communication components, creating a real-time dashboard
this.shadowRoot.innerHTML = `
<style>
/* 🎨 COMPONENT STYLING: Encapsulated styles for presentation layer */
:host { display: block; }
.app {
border: 2px solid #8b5cf6;
padding: 16px;
border-radius: 8px;
background: #1f2937;
color: #e5e7eb;
}
.app h3 { color: #8b5cf6; margin-top: 0; }
.status { margin: 8px 0; padding: 8px; background: #374151; border-radius: 4px; }
.status-item { margin: 4px 0; }
.logger {
background: #111827;
color: #10b981;
padding: 8px;
margin: 8px 0;
border-radius: 4px;
font-family: monospace;
font-size: 11px;
max-height: 150px;
overflow-y: auto;
border: 1px solid #374151;
}
.log-entry { margin: 2px 0; word-break: break-all; }
button {
background: #8b5cf6;
color: white;
border: none;
padding: 8px 16px;
border-radius: 6px;
cursor: pointer;
margin: 4px;
transition: background-color 0.2s;
}
button:hover { background: #7c3aed; }
.jobs { font-family: monospace; font-size: 12px; color: #fbbf24; }
</style>
<div class="app">
<h3>🎯 Observable App: ${this.commComponent?.id}</h3>
<!-- 📊 REAL-TIME STATUS DISPLAY: Observable state visualized as status indicators -->
<div class="status">
<div class="status-item"><strong>Coordinator:</strong> ${coordinatorStatus}</div>
<div class="status-item"><strong>Processing:</strong> ${processingStatus}</div>
<div class="status-item"><strong>System:</strong> ${completionStatus}</div>
<div class="status-item"><strong>Completed Jobs:</strong> ${jobCount}</div>
${state.completedJobs?.length ? `<div class="jobs">Jobs: ${state.completedJobs.join(', ')}</div>` : ''}
</div>
<!-- 📋 INTROSPECTION LOG: Real-time event and state change tracking -->
<div class="logger">
<div style="color: #fbbf24; font-weight: bold;">📋 APP PRESENTATION LOG:</div>
${this.logMessages.map(msg => `<div class="log-entry">${new Date().toLocaleTimeString()}: ${msg}</div>`).join('')}
</div>
<!-- 🚀 UI INTERACTION: Button triggers communication component method -->
<button onclick="this.getRootNode().host.startProcessing()">🚀 Start Processing</button>
<slot></slot>
</div>
`;
}
/**
* 🚀 User Interaction Handler - UI-to-Communication Bridge
* ══════════════════════════════════════════════════════════════════════════════════════════════════
*
* This method demonstrates the TWO-WAY COMMUNICATION pattern where UI interactions
* trigger communication component methods. The presentation layer acts as a bridge
* between user actions and the observable communication layer.
*
* INTERACTION FLOW:
* Button click → startProcessing() → commComponent.handleStartProcessing() → setState() → introspection events → UI updates
*/
startProcessing() {
console.log(`🚀 AppPresentation: Start processing button clicked`);
this.logToUI('🚀 Button clicked!');
// 🎯 UI-TO-COMMUNICATION BRIDGE: Direct method call on communication component
// This triggers the observable state changes that will flow back to the UI via introspection events
this.commComponent?.handleStartProcessing();
}
/**
* 📋 Presentation Logging - UI-Specific State Management
* ══════════════════════════════════════════════════════════════════════════════════════════════════
*
* This method demonstrates PRESENTATION-SPECIFIC STATE management separate from
* communication component observable state. It maintains UI-only data (log messages)
* and provides targeted DOM updates to avoid infinite render loops.
*
* PRESENTATION STATE PATTERNS:
* • UI-Only Data: logMessages array is presentation-specific, not part of communication state
* • Targeted Updates: Update only the logger section to avoid triggering full re-renders
* • Circular Reference Prevention: Careful not to call this from render() method
*/
logToUI(message) {
// 📝 PRESENTATION STATE UPDATE: Add to UI-specific log array
this.logMessages.push(message);
// 🧹 MEMORY MANAGEMENT: Prevent unlimited log accumulation
if (this.logMessages.length > 20)
this.logMessages.shift(); // Keep last 20 messages
// 🎯 TARGETED DOM UPDATE: Update only logger section to avoid infinite render loops
// ──────────────────────────────────────────────────────────────────────────────────────────────
// This demonstrates how to update specific UI sections without triggering
// full re-renders that could cause circular update loops
if (this.shadowRoot?.innerHTML) {
const loggerDiv = this.shadowRoot.querySelector('.logger');
if (loggerDiv) {
loggerDiv.innerHTML = `
<div style="color: #fbbf24; font-weight: bold;">📋 APP PRESENTATION LOG:</div>
${this.logMessages.map(msg => `<div class="log-entry">${new Date().toLocaleTimeString()}: ${msg}</div>`).join('')}
`;
}
}
}
/**
* 🔄 State Change Handler - Observable State Response
* ══════════════════════════════════════════════════════════════════════════════════════════════════
*
* This method is called automatically when the communication component's setState() method
* is called, demonstrating the REACTIVE UI PATTERN core to the Matrix Framework's
* introspection system. It shows how presentation layers stay synchronized with business logic.
*
* INTROSPECTION EVENT FLOW:
* setState() in AppComponent → _stateChanged event → this.onStateChanged() → render() → UI updates
*/
onStateChanged(newState) {
console.log(`🔄 AppPresentation: State changed, re-rendering with state:`, newState);
// 📋 LOG STATE CHANGE: Track state transitions for debugging transparency
this.logToUI(`🔄 State changed: ${JSON.stringify(newState)}`);
// 🎨 TRIGGER RE-RENDER: Update entire UI to reflect new state
// This demonstrates the core reactive pattern where state changes automatically update UI
this.render();
}
/**
* 📝 Property Change Handler - Granular State Tracking
* ══════════════════════════════════════════════════════════════════════════════════════════════════
*
* This method provides GRANULAR CHANGE TRACKING for individual properties within the
* observable state. It's called for each property that changes when setState() is called,
* enabling detailed monitoring and potentially targeted UI updates.
*
* GRANULAR INTROSPECTION PATTERN:
* setState({prop1: val1, prop2: val2}) → triggers onPropertyChanged() twice → individual property tracking
*/
onPropertyChanged(propertyName, newValue, oldValue) {
console.log(`📝 AppPresentation: Property ${propertyName} changed from ${oldValue} to ${newValue}, re-rendering`);
// 📋 LOG PROPERTY CHANGE: Track individual property changes for detailed debugging
this.logToUI(`📝 Property ${propertyName}: ${oldValue} → ${newValue}`);
// 🎨 TRIGGER RE-RENDER: Could be optimized to update only affected UI sections
// This demonstrates the basic reactive pattern; advanced implementations might
// update only the UI elements affected by specific property changes
this.render();
}
/**
* 🔌 DOM Connection Lifecycle - Web Component Integration
* ══════════════════════════════════════════════════════════════════════════════════════════════════
*
* This Web Components lifecycle method is called when the element is added to the DOM.
* It demonstrates the integration between Matrix Framework components and standard
* Web Components lifecycle, ensuring proper initialization and rendering.
*
* WEB COMPONENT LIFECYCLE INTEGRATION:
* Element creation → constructor() → bindTo() → connectedCallback() → DOM ready
*/
connectedCallback() {
console.log('🔌 AppPresentationElement: Connected to DOM');
// 📋 LOG DOM CONNECTION: Track element lifecycle for debugging
this.logToUI('🔌 Connected to DOM');
// 🎨 ENSURE RENDERING: Make sure UI is displayed when element enters DOM
// This provides a safety net for rendering in case bindTo() was called before DOM connection
this.render();
}
}