npm package: @plotinus/matrix-presentation
Description: Auto-magical presentation layer for Matrix Framework components
Latest version: 0.1.2

# @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

```javascript
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

```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:

```javascript
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:

```javascript
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:

```javascript
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:

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

## Benefits

1. **Rapid Development** - See your components working immediately
2. **Better Debugging** - Inspect events and state in real-time
3. **Living Documentation** - UI shows exactly what each component can do
4. **Progressive Enhancement** - Start simple, customize when needed
5. **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+