👁 Image
Cyrena.Components.Core 0.5.0

Overview

Cyrena.Components.Core is the Blazor component library providing UI contracts, base classes, and extension methods for building UI components that integrate with Cyréna's kernel-scoped services. Extensions that add UI elements (toolbars, settings pages, shortcuts) must reference this package.

Version: 0.5.0 Target Framework: .NET 10.0 Namespaces: Cyrena.Contracts, Cyrena.Models, Cyrena.Options, Cyrena.Extensions, Cyrena.Attributes, Cyrena.Components.Shared

Contracts

IDisplayService (Kernel-locked)

Service for showing dialogs, toast notifications, and navigation in the Blazor UI.

public interface IDisplayService
{
 Task<DialogResult> ShowModal<TComponent>(ResultDialogOption option, Dialog? dialog = null) 
 where TComponent : IComponent, IResultDialog;
 
 Task<DialogResult> ShowModal(string title, string content, ResultDialogOption? option = null, Dialog? dialog = null);
 
 Task ShowToast(ToastOption option, ToastContainer? toastContainer = null);
 Task ShowErrorToast(string? title = null, string? content = null, bool autoHide = true);
 Task ShowWarnToast(string? title = null, string? content = null, bool autoHide = true);
 Task ShowSuccessToast(string? title = null, string? content = null, bool autoHide = true);
 Task ShowInfoToast(string? title = null, string? content = null, bool autoHide = true);
 
 void NavigateTo(string url);
}

Dependencies: Requires BootstrapBlazor components (Dialog, ToastContainer, ToastOption, ResultDialogOption, DialogResult).

Implementation: DisplayService in Cyrena.Components.Runtime implements this interface.

IShortcut

Defines a keyboard shortcut or quick action that appears in the UI.

public interface IShortcut
{
 string Title { get; }
 string Description { get; }
 string Icon { get; }
 string Color { get; }
 string Category { get; }
 string[] Tags { get; }
 Task OnClick();
}

IToolbarComponent

Defines a component that renders in the chat toolbar.

public interface IToolbarComponent
{
 Type Component { get; }
 ToolbarAlignment Alignment { get; }
}

public enum ToolbarAlignment
{
 Start, End
}

• Component: The Type of the Blazor component to render.
• Alignment: Start (left side) or End (right side) of the toolbar.

IViewStartProvider

Provides optional ViewStart entries for user-configurable starting views.

public interface IViewStartProvider
{
 IEnumerable<ViewStart> Provide();
}

Attributes

KernelInjectAttribute

Indicates that the associated property should have a value injected from the KernelComponentBase.Kernel service provider. Overrides ComponentBase.OnParametersSet.

[AttributeUsage(AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
public sealed class KernelInjectAttribute : Attribute
{
 public object? Key { get; init; }
}

• Key: Optional keyed service key for GetKeyedService resolution.

Usage:

public class MyToolbarComponent : KernelComponentBase
{
 [KernelInject]
 public IChatMessageService ChatService { get; set; } = default!;
 
 [KernelInject(Key = "my-key")]
 public IMyService MyService { get; set; } = default!;
}

Models

KernelComponentBase

Base class for Blazor components that need access to the current Kernel and its services via [KernelInject].

public abstract class KernelComponentBase : ComponentBase
{
 [Parameter]
 [EditorRequired]
 public Kernel Kernel { get; set; } = default!;
}

Components extending this class receive the active kernel instance as a parameter. When Kernel is set, all properties marked with [KernelInject] are automatically resolved from Kernel.Services.

ViewStart

Information for a configurable starting view.

public sealed class ViewStart
{
 public string Href { get; set; } = default!;
 public string Title { get; set; } = default!;
 public string? Description { get; set; }
}

Options

ComponentOptions

Configuration for UI components, particularly settings pages.

public class ComponentOptions
{
 internal List<ComponentMetaData> SettingsComponents { get; set; }
 public ComponentMetaData[] GetSettingsComponents();
}

public record ComponentMetaData(Type Component, string? Section, int Order);

• SettingsComponents: Collection of registered settings component metadata (internal).
• GetSettingsComponents(): Returns all registered settings components as an array.
• ComponentMetaData: Record describing a settings component with its type, section group, and display order.

ComponentOptionsExtensions

Extension methods for registering settings components:

public static class ComponentOptionsExtensions
{
 [Obsolete("Use new section mapping API")]
 public static void AddSettingsComponent<TComponent>(this ComponentOptions options)
 where TComponent : ComponentBase;

 public static void AddSettingsComponent<TComponent>(this ComponentOptions options, string section);

 public static void AddSettingsComponent<TComponent>(this ComponentOptions options, string section, int order);
}

• All overloads prevent duplicate registration by checking if the component type already exists.
• The no-parameter overload is obsolete — use section overloads instead.

CodeLanguages

Maps file extensions to syntax highlighting language identifiers.

public class CodeLanguages
{
 public string GetFileLanguage(string extension);
}

Supported mappings:

• .c, .h → c
• .cpp, .hpp, .ino → cpp
• .cs → csharp
• .razor → html
• .css → css
• .js → javascript
• .md → markdown
• .csproj, .xml → xml
• .json → json
• Default → plaintext

Extension Methods

CyrenaBuilderExtensions

public static class CyrenaBuilderExtensions
{
 [Obsolete("Use new section mapping API")]
 public static CyrenaBuilder AddSettingsComponent<TComponent>(this CyrenaBuilder builder)
 where TComponent : ComponentBase;

 public static CyrenaBuilder AddSettingsComponent<TComponent>(this CyrenaBuilder builder, string section)
 where TComponent : ComponentBase;

 public static CyrenaBuilder AddSettingsComponent<TComponent>(this CyrenaBuilder builder, string section, int order)
 where TComponent : ComponentBase;

 public static CyrenaBuilder AddShortcut<TShortcut>(this CyrenaBuilder builder)
 where TShortcut : class, IShortcut;
}

• AddSettingsComponent: Registers a Blazor component as a settings tab under the specified section with optional order.
• AddShortcut: Registers a shortcut action in the UI as a scoped IShortcut service.

CyrenaKernelBuilderExtensions

public static class CyrenaKernelBuilderExtensions
{
 public static void AddToolbarComponent<TComponent>(this CyrenaKernelBuilder builder, ToolbarAlignment alignment)
 where TComponent : KernelComponentBase;

 [Obsolete]
 public static void AddToolbarComponent<TComponent>(this IKernelBuilder builder, ToolbarAlignment alignment)
 where TComponent : KernelComponentBase;
}

• AddToolbarComponent: Registers a component to render in the chat toolbar for the current kernel/chat.
• The obsolete overload on IKernelBuilder is deprecated; prefer CyrenaKernelBuilder.

ComponentBaseExtensions

public static class ComponentBaseExtensions
{
 public static RenderFragment Render(this ComponentBase cmp, Type type);
 public static RenderFragment Render(this ComponentBase cmp, Type type, Dictionary<string, object?> parameters);
}

Helper methods for dynamically rendering Blazor components from code with optional parameter passing.

Shared Blazor Components

CodeInput.razor

Monaco code editor wrapper (BlazorMonaco) with syntax highlighting, dark theme, and two-way value binding.

Parameters:

• Value / ValueChanged — Two-way bound editor content
• Language — Monaco language mode (default: "plaintext")

ConnectionSelector.razor

Dropdown of available AI connections from all registered IConnectionProvider services.

Parameters:

• Value / ValueChanged — Two-way bound selected connection ID
• Label — Dropdown label (default: "AI Connection")

Behavior: Populates connections on first render and on click. Displays Name (Source) per option.

PluginSelector.razor

Checkbox list for activating/deactivating IAssistantPlugin instances filtered by the current chat's assistant mode.

Parameters:

• Chat (ChatConfiguration, required) — Chat whose PluginIds will be updated

Behavior:

• Filters plugins by mode compatibility
• Required plugins are always selected and disabled
• If Chat.PluginIds is empty, all plugins are selected by default
• Updates Chat.PluginIds on every selection change

Usage for Extension Developers

Reference Cyrena.Components.Core to:

1. Implement IShortcut for quick actions
2. Implement IToolbarComponent for toolbar buttons
3. Extend KernelComponentBase for kernel-aware UI components
4. Use IDisplayService for dialogs and toasts
5. Use [KernelInject] for automatic service injection from kernel scope
6. Register settings components via AddSettingsComponent
7. Register toolbar components via AddToolbarComponent
8. Implement IViewStartProvider for custom starting views

Example - Toolbar Component:

public class MyToolbarComponent : KernelComponentBase 
{ 
 [KernelInject]
 public IChatMessageService ChatService { get; set; } = default!;
}

// In IAssistantPlugin.LoadAsync:
builder.AddToolbarComponent<MyToolbarComponent>(ToolbarAlignment.End);

Example - Shortcut:

public class MyShortcut : IShortcut
{
 public string Title => "My Action";
 public string Description => "Does something";
 public string Icon => "fa-solid fa-star";
 public string Color => "primary";
 public string Category => "My Category";
 public string[] Tags => ["my"];
 public Task OnClick() { ... }
}

// In extension BuildExtension:
builder.AddShortcut<MyShortcut>();

Example - Settings Component:

builder.AddSettingsComponent<MySettingsComponent>("General", 1);

Example - View Start Provider:

public class MyViewStartProvider : IViewStartProvider
{
 public IEnumerable<ViewStart> Provide()
 {
 yield return new ViewStart { Href = "/my-page", Title = "My Page" };
 }
}