BridgeEditor 2.0.0

BridgeEditor

BridgeEditor is an extensible Persian-first rich-text editor for interactive Blazor applications. Version 2 adds application-owned toolbar commands, live content metrics and advisory limits, portable document snapshots, and configurable change debouncing while retaining the complete version 1 API. It also supports RTL and LTR content, responsive and fullscreen editing, configurable toolbars, clean Word/Google Docs paste, advanced tables, safe embeds, validated uploads, browser-local drafts, source mode, lifecycle events, and sanitized HTML output.

Install

dotnet add package BridgeEditor

Import the component namespace in _Imports.razor:

@using BridgeEditor.Components

Reference the packaged static assets in App.razor. The script must load before Blazor starts because the component can initialize during its first interactive render.

<link rel="stylesheet" href="@Assets["_content/BridgeEditor/css/bridge-editor.css"]" />
<script src="@Assets["_content/BridgeEditor/js/bridge-editor.js"]"></script>
<script src="_framework/blazor.web.js"></script>

For a WebAssembly wwwroot/index.html host, use the same _content/BridgeEditor/... paths without the @Assets[...] wrapper.

Usage

<BridgeEditor @ref="editor"
              @bind-Value="html"
              UploadUrl="/api/media/upload"
              VideoUploadUrl="/api/media/upload/video"
              ToolbarPreset="BridgeEditorToolbarPreset.Standard"
              DraftKey="@($"blog-post-{postId}")"
              AutoSaveDelayMilliseconds="2000"
              ChangeDebounceMilliseconds="150"
              MaxWords="1200"
              MaxCharacters="12000"
              MaxImageBytes="@(5 * 1024 * 1024)"
              MaxVideoBytes="@(25 * 1024 * 1024)"
              Placeholder="محتوای خود را اینجا بنویسید…"
              MinHeight="360"
              EnableSourceMode="true"
              OnUploadFailed="HandleUploadFailure" />

@code {
    private BridgeEditor? editor;
    private string? html;

    private void HandleUploadFailure(BridgeEditorUploadEventArgs args)
    {
        // Display or log args.Error.
    }

    private async Task SaveAsync()
    {
        await (editor?.CommitAsync() ?? Task.CompletedTask);
        // Persist html here.
    }
}

UploadUrl is optional. When configured, the editor sends the selected file as a multipart field named file and includes every entry from UploadFields. The field name, credentials, request headers, timeout, accepted MIME types, and client-side image/video size limits are configurable. The endpoint response can be { "location": "/media/file.webp" }, { "url": "/media/file.webp" }, or a JSON string containing the uploaded URL.

DraftKey is also optional. A non-empty, stable key enables debounced autosave in the browser's local storage. RestoreDraftOnInit is opt-in; applications can instead call SaveDraftAsync(), RestoreDraftAsync(), and ClearDraftAsync() explicitly. Drafts are local recovery aids and do not replace server persistence.

Version 2 extensibility

Register application-owned commands without forking the editor toolbar. Labels are rendered as text, command names are normalized, and the callback receives both the command name and the current sanitized HTML.

<BridgeEditor @ref="editor"
              @bind-Value="html"
              CustomCommands="commands"
              OnCustomCommand="HandleCommand"
              OnMetricsChanged="HandleMetrics"
              MaxWords="1200" />

@code {
    private BridgeEditor? editor;
    private string? html;
    private BridgeEditorContentMetrics metrics = new();
    private static readonly BridgeEditorCommandDefinition[] commands =
    [
        new() { Name = "callout", Label = "Callout", Title = "Insert a product callout" }
    ];

    private Task HandleCommand(BridgeEditorCommandEventArgs args)
    {
        // Apply application-specific behavior based on args.Name and args.Html.
        return Task.CompletedTask;
    }

    private void HandleMetrics(BridgeEditorContentMetrics value) => metrics = value;
}

MaxWords and MaxCharacters are advisory: the status bar and OnMetricsChanged report the limit state without silently deleting user content. Use GetMetricsAsync() before persistence when a hard validation rule is required.

Portable snapshots include sanitized HTML, plain text, metrics, direction, capture time, and a schema version:

BridgeEditorDocumentSnapshot snapshot = await editor.ExportDocumentAsync();
await editor.ImportDocumentAsync(snapshot);

Toolbar profiles

• Minimal: undo/redo, block type, basic emphasis, lists, link, direction, fullscreen, and help.
• Standard: common CMS authoring commands, nested-list indentation, find/replace, advanced tables, uploads, and safe embeds without unrestricted font/color or HTML source controls.
• Full: every built-in command and the backward-compatible default.

Use ToolbarItems to override the selected profile with an explicit command allow-list:

<BridgeEditor @bind-Value="html"
              ToolbarItems="toolbarItems" />

@code {
    private static readonly string[] toolbarItems =
        ["undo", "redo", "bold", "italic", "link"];
}

Supported built-in toolbar item names are undo, redo, block, bold, italic, underline, strike, unordered-list, ordered-list, indent, outdent, align-right, align-center, align-left, align-justify, font-family, font-size, text-color, background-color, clear-format, link, table, image, video, embed, find-replace, horizontal-rule, direction, source, fullscreen, and help. Custom command names can also be included when an explicit ToolbarItems allow-list is used.

The inline table toolbar can add or delete rows and columns, toggle a header row, add a caption, merge a cell with its next neighbour, split a merged cell, and delete the table. The media toolbar edits alignment, width, title, image alternative text, and caption. Embedded iframes are limited to normalized YouTube and Vimeo URLs and receive restrictive browser attributes.

Interaction and events

ReadOnly keeps selection and copying available while preventing edits. Disabled prevents editing and disables every editor control. Both properties can change while the component is running, or can be changed through SetStateAsync(...).

The component exposes OnReady, OnFocus, OnBlur, OnChange, OnMetricsChanged, OnCustomCommand, OnDraftSaved, OnDraftRestored, OnUploadStarted, OnUploadProgress, OnUploadCompleted, and OnUploadFailed. Upload callbacks receive a BridgeEditorUploadEventArgs value containing file metadata, progress, result URL, and error details.

Public API

• Two-way binding: Value / ValueChanged
• Lifecycle: AutoInit, InitAsync(), DestroyAsync()
• Content: GetHtmlAsync(), SetHtmlAsync(...), CommitAsync(), ExecuteCommandAsync(...), GetMetricsAsync(), ExportDocumentAsync(), ImportDocumentAsync(...)
• Presentation: Direction, Placeholder, AriaLabel, MinHeight, EnableSourceMode, ShowHeader, ShowStatusBar
• Toolbar: ToolbarPreset, ToolbarItems, CustomCommands, OnCustomCommand
• Validation: MaxWords, MaxCharacters, ChangeDebounceMilliseconds, OnMetricsChanged
• State: ReadOnly, Disabled, SetStateAsync(...)
• Drafts: DraftKey, AutoSaveDelayMilliseconds, RestoreDraftOnInit, SaveDraftAsync(), RestoreDraftAsync(), ClearDraftAsync()
• Uploads: UploadUrl, VideoUploadUrl, UploadFields, UploadFieldName, UploadHeaders, UploadWithCredentials, ImageAccept, VideoAccept, MaxImageBytes, MaxVideoBytes, UploadTimeoutMilliseconds
• Events: OnReady, OnFocus, OnBlur, OnChange, OnMetricsChanged, OnCustomCommand, OnDraftSaved, OnDraftRestored, OnUploadStarted, OnUploadProgress, OnUploadCompleted, OnUploadFailed

Upgrading from 1.x

Version 2 preserves the 1.x component parameters, JavaScript asset paths, HTML contract, and defaults. Existing consumers can update the package without changing markup. The new metrics callbacks may run during initialization when subscribed; custom commands and content limits remain opt-in.

Demo and tests

dotnet run --project samples/BridgeEditor.Demo
dotnet test tests/BridgeEditor.Tests

The client-side sanitizer and upload checks are defense in depth for the editing experience. Applications must still validate uploads and sanitize untrusted HTML on the server before storing or rendering it.

License

MIT