@plotinus/matrix-presentation

v0.1.2

Published

7 days ago

Auto-magical presentation layer for Matrix Framework components

0High
0Medium
0Low

open-matrix

@matrix/presentation

Auto-magical presentation layer for Matrix Framework components.

Overview

This package provides a parallel presentation layer that automatically creates web components for every Matrix communication component. It enables:

Zero-code UI generation - Every component gets a default UI automatically
Inline HTML DSL - Write DSL directly in HTML, not as JavaScript strings
Full customization - Override default presentation with custom visualizations
Live introspection - See events, commands, and state changes in real-time

How It Works

1. Write Your Communication Component

class WorkerComponent extends IntrospectableBaseCommunicationComponent {
  static dslTag = 'worker';
  static emits = ['Ready', 'JobComplete'];
  static commands = ['ProcessJob', 'Stop'];
  
  constructor(id, eventBus) {
    super(id, eventBus);
    this.setState({ status: 'idle', jobCount: 0 });
  }
  
  handleProcessJob(job) {
    this.setState({ 
      status: 'processing',
      jobCount: this.state.jobCount + 1 
    });
    
    // Process job...
    
    this.emitEvent('JobComplete', { jobId: job.id });
  }
}

// Register it
window.Matrix.register(WorkerComponent);

2. Use Inline DSL in HTML

<!DOCTYPE html>
<html>
<head>
  <script src="matrix.js"></script>
  <script src="matrix-presentation.js"></script>
</head>
<body>
  <!-- Your DSL goes here - NO JavaScript strings! -->
  <matrix-app>
    <coordinator id="coord1">
      <worker id="worker1" onJobComplete="handleComplete" />
      <worker id="worker2" onJobComplete="handleComplete" />
    </coordinator>
  </matrix-app>
  
  <!-- Presentation components appear here automatically -->
  <matrix-presentation-root></matrix-presentation-root>
</body>
</html>

3. Get Automatic UI

Each component automatically gets:

Event buttons - Click to emit any event
Command inputs - Send commands with JSON data
State display - Live view of component state
Activity log - See all events and commands

Custom Presentation

Override the default UI by creating a custom presentation class:

class WorkerPresentationElement extends BasePresentationElement {
  render() {
    super.render(); // Keep default UI
    
    // Add custom visualization
    const customSection = document.createElement('div');
    customSection.innerHTML = `
      <div class="custom-viz">
        <h4>Job Progress</h4>
        <progress value="${this.commComponent.state.jobCount}" max="100"></progress>
        <div>Status: ${this.commComponent.state.status}</div>
      </div>
    `;
    
    this.shadowRoot.appendChild(customSection);
  }
}

// Associate with component
WorkerComponent.presentationClass = WorkerPresentationElement;

Architecture

Parallel Trees

Communication Tree          Presentation Tree
-----------------          -----------------
    Matrix                  <matrix-app>
      |                           |
  Coordinator               <coordinator-presentation>
   /      \                    /                \
Worker1  Worker2     <worker-presentation>  <worker-presentation>

Private Event Channel

Each presentation element has a private channel to its communication component:

_eventEmitted - Notified when component emits any event
_commandReceived - Notified when component receives any command
_stateChanged - Notified when component state changes
_propertyChanged - Notified when specific property changes

API Reference

IntrospectableBaseCommunicationComponent

Extends BaseCommunicationComponent with introspection capabilities:

class MyComponent extends IntrospectableBaseCommunicationComponent {
  static emits = ['Event1', 'Event2'];      // Declare emitted events
  static commands = ['Command1', 'Command2']; // Declare handled commands
  
  handleCommand1(data) {
    // Command handlers are auto-wired
    this.setState({ processing: true });
  }
}

BasePresentationElement

Base class for presentation components:

class CustomPresentation extends BasePresentationElement {
  constructor() {
    super();
    this.config = {
      showEvents: true,
      showCommands: true,
      showState: true,
      showLog: true,
      maxLogEntries: 50
    };
  }
  
  render() {
    // Override to customize
  }
}

MatrixAppElement

The <matrix-app> element that processes inline DSL:

<matrix-app>
  <!-- Your DSL here -->
</matrix-app>

Benefits

Rapid Development - See your components working immediately
Better Debugging - Inspect events and state in real-time
Living Documentation - UI shows exactly what each component can do
Progressive Enhancement - Start simple, customize when needed
True Separation - Presentation never affects communication logic

Browser Support

Requires browsers with:

Custom Elements v1
Shadow DOM v1
ES2020 features

Works in Chrome 90+, Firefox 88+, Safari 14+, Edge 90+