LARC Playground - Unified System

Overview

The new unified playground combines three powerful modes into one cohesive experience:

What's New?

✅ Issues Fixed

🆕 New Features

#### Gallery Mode

• Visual Example Browser - See all 20+ examples in a beautiful grid
• Search & Filter - Find examples quickly
• Quick Actions - Open any example in Builder or Editor with one click
• Preview - Open examples in a new window for fullscreen testing

• Component Palette - Drag components from sidebar
• Visual Canvas - See components render live
• 3-Tab Properties Panel:

• Code Export - Export your creation as standalone HTML

• 3-Pane Code Editor - HTML, CSS, JavaScript tabs
• Live Preview - See changes as you type (1s debounce)
• Auto-run - Changes apply automatically
• Export - Download as standalone HTML file
• Format - Basic code formatting
• Fullscreen Preview - Test in fullscreen mode

File Structure

playground/
├── index-new.html              # New unified playground entry point
├── playground-unified.mjs      # Main controller for all three modes
├── styles/
│   ├── playground-unified.css  # Unified styles for all modes
│   └── playground.css          # Original styles (still used by components)
├── components/                 # Existing components (reused)
│   ├── pg-palette.mjs
│   ├── pg-canvas.mjs
│   ├── pg-properties.mjs
│   ├── pg-exporter.mjs
│   └── pg-bus-monitor.mjs
└── examples.mjs                # 20+ pre-built examples

How to Use

Accessing the Playground

https://larcjs.com/playground/index-new.html

cd /home/cdr/domains/larcjs.com/www/larc/playground
cp index.html index-old.html  # Backup
cp index-new.html index.html  # Replace

Gallery Mode

Builder Mode

Editor Mode

PAN Bus Monitor

Click "PAN Monitor" button in header to see real-time PAN bus messages:

• Message topic and payload
• Timestamp
• Source component
• Helps debug communication between components

Architecture

Mode Management

The PlaygroundUnified class manages all three modes:

class PlaygroundUnified {
  constructor() {
    this.currentMode = 'gallery';  // gallery | builder | editor
    this.examples = getAllExamples();
    this.currentExample = null;
  }

  switchMode(mode) {
    // Update tabs, panels, and load appropriate content
  }
}

Mode Switching Flow

Gallery Example Card
    ↓ "Open in Builder"
Builder Mode (loads example components)
    ↓ Edit properties, add styling
Builder Export
    ↓ Copy HTML
Editor Mode (paste and customize)
    ↓ Add JavaScript, refine CSS
Export Standalone HTML

Component Communication

All modes use the existing PAN bus system:

// Properties panel publishes changes
document.dispatchEvent(new CustomEvent('canvas-changed', {
  bubbles: true
}));

// Canvas listens for component selection
document.addEventListener('component-selected', (e) => {
  this.addComponent(e.detail);
});

Key Improvements

1. Property Updates

• Properties sometimes didn't update
• No visual feedback
• Unclear when changes applied

attachPropertyListeners() {
  this.querySelectorAll('[data-attr]').forEach(input => {
    let eventType = input.type === 'checkbox' ? 'change' :
                   input.tagName === 'TEXTAREA' ? 'blur' : 'input';

    input.addEventListener(eventType, (e) => {
      const attrName = e.target.dataset.attr;
      const value = e.target.type === 'checkbox' ?
                   e.target.checked : e.target.value;

      // Update element immediately
      if (this.selectedElement) {
        if (value === '') {
          this.selectedElement.removeAttribute(attrName);
        } else {
          this.selectedElement.setAttribute(attrName, value);
        }
      }

      // Notify canvas
      document.dispatchEvent(new CustomEvent('canvas-changed'));
    });
  });
}

2. CSS Application

• CSS changes didn't visually apply
• Unclear if styles were saved

attachCSSListeners() {
  applyBtn.addEventListener('click', () => {
    const css = cssEditor.value;
    const componentId = this.selectedElement.dataset.componentId;

    // Store CSS
    this.customCSS.set(componentId, css);

    // Apply immediately via style attribute
    this.selectedElement.style.cssText = css;

    // Show success feedback
    this.showFeedback('Styles applied!', 'success');
  });
}

3. Actions System

• Actions system partially implemented
• No clear indication of active actions

applyAction(action) {
  this.selectedElement.addEventListener(action.event, (e) => {
    switch (action.type) {
      case 'publish':
        // Publish to PAN bus
        document.dispatchEvent(new CustomEvent('pan:publish', {
          detail: {
            topic: action.topic,
            data: { source: this.componentMeta?.name }
          }
        }));
        break;

      case 'console':
        console.log(`[${this.componentMeta?.displayName}]`, action.message);
        break;

      case 'alert':
        alert(action.message);
        break;
    }
  });
}

Actions are immediately attached and work on next event trigger.

Example: Using All Three Modes

Scenario: Creating a Dashboard

document.addEventListener('pan:message', (e) => {
       if (e.detail.topic === 'card.clicked') {
         console.log('Card clicked!', e.detail);
       }
     });

Best Practices

Gallery Mode

• ✅ Use search to find examples quickly
• ✅ Preview examples before opening in Builder
• ✅ Check component list to understand what's included

Builder Mode

• ✅ Always check the Properties tab to see available attributes
• ✅ Use CSS presets as starting points
• ✅ Test actions with PAN Monitor open
• ✅ Export code frequently to save progress

Editor Mode

• ✅ Use HTML tab for structure
• ✅ Use CSS tab for styling
• ✅ Use JS tab for interactivity
• ✅ Wait 1 second after typing for auto-run
• ✅ Use "Format" button to clean up code
• ✅ Export when satisfied with result

Troubleshooting

Properties Not Updating

CSS Not Applying

Actions Not Firing

Editor Preview Not Updating

Migration from Old Playground

If you want to keep both versions:

# Rename old playground
mv index.html index-classic.html

# Use new playground as default
cp index-new.html index.html

# Update links
# index-classic.html = old drag-and-drop only
# index.html = new unified system

Technical Details

Dependencies

• @larcjs/core@3.0.1 - Core PAN bus system
• @larcjs/ui@3.0.1 - UI components
• Existing pg-* components (palette, canvas, properties, etc.)

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

• ES Modules
• Custom Elements v1
• Shadow DOM
• CSS Grid
• Flexbox

Performance

• Gallery mode: Renders 20+ cards efficiently
• Builder mode: Handles 50+ components on canvas
• Editor mode: 1-second debounce for auto-run
• All modes: Minimal memory footprint

Future Enhancements

Potential improvements for future versions:

• [ ] Syntax highlighting in editor (CodeMirror/Monaco)
• [ ] Component search in Builder palette
• [ ] Undo/redo in Builder
• [ ] Save examples to localStorage
• [ ] Share examples via URL
• [ ] Import/export Builder projects
• [ ] Template library expansion
• [ ] Mobile-optimized layout
• [ ] Collaborative editing
• [ ] Video tutorials integration

Support

For issues or questions:

• GitHub: https://github.com/larcjs/larc/issues
• Discord: https://discord.gg/zjUPsWTu
• Documentation: https://larcjs.com/docs/

Contributing

The playground is open source! Contributions welcome:

See CONTRIBUTING.md for guidelines.