BridgeEditor 2.2.0

BridgeEditor

BridgeEditor is an extensible Persian-first rich-text editor for interactive Blazor applications. Version 2.2 adds a bilingual UI, reusable content blocks, a searchable media library, Markdown import/export, image preparation, application-owned server revisions, and a configurable .NET sanitizer while preserving the version 1 and 2.0 public contracts. 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, sanitized HTML output, and a bundled Vazirmatn variable font.

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.2 authoring

Set UiCulture="en" for the built-in English UI; Persian remains the backward-compatible default. TranslationOverrides can replace individual built-in strings without forking the JavaScript asset.

Reusable blocks are available from the blocks toolbar item and by typing / in an empty paragraph. BridgeEditor includes info, warning, success, quote, code, and button blocks. Applications can append sanitized templates:

<BridgeEditor @bind-Value="html"
              Templates="templates"
              MediaLibraryItems="media"
              UiCulture="fa" />

@code {
    private static readonly BridgeEditorTemplateDefinition[] templates =
    [
        new()
        {
            Name = "product-highlight",
            Label = "معرفی محصول",
            Category = "فروشگاه",
            Html = "<aside class=\"pe-callout pe-callout--info\"><h3>محصول</h3><p>توضیح</p></aside>"
        }
    ];

    private static readonly BridgeEditorMediaItem[] media =
    [
        new() { Url = "/media/product.webp", Title = "Product", AlternativeText = "Product image" }
    ];
}

SetMediaLibraryAsync(...) refreshes media while an editor instance is running. The image preparation dialog supports center crop ratios, maximum dimensions, output quality, and alternative text. Set OptimizeImagesBeforeUpload="true" to optimize pasted and dropped raster images too; it is off by default so existing upload bytes remain unchanged.

Markdown-looking plain text is recognized in the default clean paste mode. Use PasteMode="BridgeEditorPasteMode.PlainText" or Markdown to force a mode. GetMarkdownAsync() and SetMarkdownAsync(...) provide explicit conversion APIs.

Server revisions

Implement IBridgeEditorRevisionStore with your database or API, then provide a stable document key. BridgeEditor owns debounce and UI; the application owns authorization, persistence, retention, and concurrency policy.

<BridgeEditor @ref="editor"
              @bind-Value="html"
              RevisionStore="revisionStore"
              RevisionDocumentKey="@($"blog:{postId}")"
              RevisionAuthor="@userName"
              AutoSaveServerRevisions="true"
              ServerAutoSaveDelayMilliseconds="5000"
              OnRevisionSaveFailed="HandleRevisionError" />

The built-in history command lists, previews, and restores revisions. Applications can also call SaveServerRevisionAsync() and RestoreServerRevisionAsync(...) directly. A store is optional; when absent, version 2.1 draft behavior is unchanged.

Server sanitization

BridgeEditorHtmlSanitizer parses untrusted HTML with AngleSharp and rebuilds it from an allow-list. It removes dangerous elements, event handlers, unsafe URLs and CSS, restricts embeds to normalized YouTube/Vimeo URLs, and enforces noopener noreferrer for new-tab links.

IBridgeEditorHtmlSanitizer sanitizer = new BridgeEditorHtmlSanitizer(options =>
{
    options.AllowedTags.Add("mark");
});

var safeHtml = sanitizer.Sanitize(untrustedHtml);

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, blocks, media library, revision history when configured, 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, blocks, image, video, media-library, embed, find-replace, history, horizontal-rule, direction, source, fullscreen, and help. Custom command names can also be included when an explicit ToolbarItems allow-list is used.

The font selector includes the bundled Vazirmatn variable font and web-safe fallbacks. Applications that render saved editor HTML on pages where the editor stylesheet is not loaded should provide their own matching @font-face declaration so Vazirmatn-formatted content renders identically outside the editor.

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(...), GetMarkdownAsync(), SetMarkdownAsync(...), CommitAsync(), ExecuteCommandAsync(...), GetMetricsAsync(), ExportDocumentAsync(), ImportDocumentAsync(...)
• Presentation: Direction, UiCulture, TranslationOverrides, Placeholder, AriaLabel, MinHeight, EnableSourceMode, ShowHeader, ShowStatusBar
• Toolbar: ToolbarPreset, ToolbarItems, CustomCommands, OnCustomCommand
• Blocks/media: Templates, IncludeBuiltInTemplates, EnableSlashCommands, MediaLibraryItems, SetMediaLibraryAsync(...), EnableImageEditor, OptimizeImagesBeforeUpload, MaxImageDimension, ImageQuality
• Paste: PasteMode, EnableMarkdownPaste
• 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
• Revisions: RevisionStore, RevisionDocumentKey, RevisionAuthor, AutoSaveServerRevisions, ServerAutoSaveDelayMilliseconds, RevisionHistoryLimit, SaveServerRevisionAsync(), RestoreServerRevisionAsync(...)
• Security: HtmlSanitizer, SanitizeHtml(...)
• Events: OnReady, OnFocus, OnBlur, OnChange, OnMetricsChanged, OnCustomCommand, OnDraftSaved, OnDraftRestored, OnUploadStarted, OnUploadProgress, OnUploadCompleted, OnUploadFailed, OnRevisionSaved, OnRevisionRestored, OnRevisionSaveFailed

Upgrading from 1.x

Version 2.2 preserves the 1.x and 2.0 component parameters, JavaScript asset paths, snapshot schema, HTML contract, and defaults. Existing consumers can update the package without changing markup. Localization, templates, media-library data, Markdown modes, image optimization, and server revisions are additive or 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. BridgeEditorHtmlSanitizer supplies a safe default policy, but authorization and storage validation remain application responsibilities.

License

MIT

BridgeEditor is developed by BridgeGroup. The bundled Vazirmatn font is licensed separately under the SIL Open Font License; see THIRD-PARTY-NOTICES.md in the package.