Overview

This PR addresses #35 by exposing the IVdomElementTranslator interface and related APIs, enabling users to create custom VDOM element translators. It also replaces the MEF (Managed Extensibility Framework) dependency with the standard Microsoft.Extensions.DependencyInjection service provider for a cleaner, more maintainable architecture.

Motivation

Previously, all VDOM translators were internal and used MEF for discovery, making it impossible for users to extend RazorConsole with custom Spectre.Console renderables. This prevented users from implementing features like overflow handling or other custom components that aren't built into the framework.

Changes

Public APIs

The following APIs are now public and documented:

• VdomSpectreTranslator - Main translator class with public constructor
• IVdomElementTranslator - Standalone interface for implementing custom translators with built-in Priority property
• TranslationContext - Standalone context class for recursive translation of child nodes
• IAnimatedConsoleRenderable - Interface for animated renderables
• Utility methods - All helper methods (GetAttribute, TryConvertChildrenToRenderables, CollectInnerText, etc.) are now public static methods
• All built-in translators - All 20 translator classes are now standalone public classes with their own Priority property

Architecture Improvements

• Standalone translators: All translator classes are now public standalone classes in their own files, no longer nested in VdomSpectreTranslator
• Built-in Priority: IVdomElementTranslator includes a Priority property, eliminating the need for wrapper classes
• Simplified registration: Direct registration without priority wrappers - translators implement their own priority

Service Provider Integration

Replaced MEF with Microsoft.Extensions.DependencyInjection:

• Removed System.Composition package dependency
• Removed all [Export] attributes from translator classes
• Created VdomTranslatorServiceCollectionExtensions with fluent registration API
• Updated AppHost to register default translators via DI
• Updated ConsoleRenderer to receive VdomSpectreTranslator from DI container

Priority-Based Registration

Users can now register custom translators using the standard DI pattern:

var app = AppHost.Create<MyComponent>(builder =>
{
    // Register custom translator (priority comes from the translator's Priority property)
    builder.Services.AddVdomTranslator<OverflowElementTranslator>();
    
    // Or register by instance
    builder.Services.AddVdomTranslator(new MyTranslator());
    
    // Or use a factory with DI
    builder.Services.AddVdomTranslator(sp => 
        new MyTranslator(sp.GetRequiredService<ISomeService>()));
});

Built-in translators use priorities from 10-1000, allowing users to insert custom translators before, between, or after default handlers by implementing the appropriate Priority value.

Example Usage

Creating a custom translator for overflow handling:

public class OverflowElementTranslator : IVdomElementTranslator
{
    public int Priority => 50; // Higher priority than most built-in translators

    public bool TryTranslate(VNode node, TranslationContext context, 
        out IRenderable? renderable)
    {
        renderable = null;
        
        if (node.Kind != VNodeKind.Element || 
            !string.Equals(node.TagName, "div", StringComparison.OrdinalIgnoreCase))
        {
            return false;
        }

        var overflow = VdomSpectreTranslator.GetAttribute(node, "data-overflow");
        if (string.IsNullOrEmpty(overflow))
        {
            return false;
        }

        // Convert children using public utility method
        if (!VdomSpectreTranslator.TryConvertChildrenToRenderables(
            node.Children, context, out var children))
        {
            return false;
        }

        renderable = VdomSpectreTranslator.ComposeChildContent(children);
        return true;
    }
}

Then use it in a Razor component:

<div data-overflow="ellipsis">
    This text will be handled by the custom overflow translator
</div>

Documentation

Added comprehensive documentation for custom translators:

Design Documentation

Created design-doc/custom-translators.md with detailed coverage of:

• Architecture overview and core components
• Complete reference of all 20 built-in translators with priorities
• Step-by-step guide for creating custom translators
• Utility methods reference with examples
• Best practices and advanced scenarios (DI, conditional translation, complex renderables)
• Troubleshooting guide and testing strategies

README Updates

Added Custom Translators section to README.md including:

• Quick-start example for creating a custom translator
• Registration patterns using AddVdomTranslator
• Usage examples in Razor components
• Link to comprehensive design documentation

Testing

• Added CustomTranslatorTests with 3 new tests validating custom translator registration and priority handling
• Created TestHelpers utility for consistent test renderer setup
• All existing tests pass (60 tests → 63 tests)
• Tests run on both .NET 8.0 and .NET 9.0 (126 total test executions)

Breaking Changes

None for users of the public API. The internal MEF-based system has been replaced, but since IVdomElementTranslator was previously internal, no external code should be affected.

Migration Guide

For any internal/custom translators that were using the internal MEF approach:

Before:

[Export(typeof(IVdomElementTranslator))]
internal sealed class MyTranslator : VdomSpectreTranslator.IVdomElementTranslator
{
    public bool TryTranslate(VNode node, VdomSpectreTranslator.TranslationContext context, 
        out IRenderable? renderable)
    {
        // Implementation
    }
}

After:

public sealed class MyTranslator : IVdomElementTranslator
{
    public int Priority => 100; // Define your priority
    
    public bool TryTranslate(VNode node, TranslationContext context, 
        out IRenderable? renderable)
    {
        // Implementation
    }
}

// Register in startup:
services.AddVdomTranslator<MyTranslator>();

Benefits

1. Extensibility - Users can now implement custom Spectre.Console renderables
2. Standard DI - No MEF dependency, uses familiar .NET patterns
3. Priority Control - Fine-grained control over translator ordering via Priority property
4. Cleaner Architecture - Standalone translator classes without nested types
5. Better Testing - Easier to test with standard DI practices
6. Documentation - All public APIs are documented with XML comments, comprehensive design docs, and README examples

Closes #35

Fixes #35

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.