Better JavaScript interaction
for Blazor

dotnet add package BlazorJS

@using BlazorJS
@using BlazorJS.Attributes
@using BlazorJS.JsInterop

<Scripts src="js/myjsfile.js"></Scripts>

<!-- multiple files, comma separated -->
<Scripts src="js/myjsfile.js, js/myjsfile2.js"></Scripts>

<!-- stylesheets work too, the extension decides -->
<Scripts src="js/myjsfile.js, css/mystyle.css"></Scripts>

<!-- or be explicit about it -->
<Styles src="css/mystyle.css"></Styles>

<Scripts src="js/chart.js"
         SourceLoadBehaviour="LoadBehaviour.OnInitializedAsync"
         UnloadOnDispose="false"
         SourceLoaded="OnScriptLoaded" />

@code {
    private void OnScriptLoaded(string file) => Console.WriteLine($"{file} is ready");
}

await jsRuntime.LoadFilesAsync("js/chart.js", "css/chart.css");
await jsRuntime.UnloadFilesAsync("js/chart.js");

// wait until a global is really there before using it
if (await jsRuntime.WaitForNamespaceAsync("Chart"))
    await jsRuntime.DInvokeVoidAsync(window => window.console.log("Chart is loaded"));

// from a string. The id makes the call repeatable instead of stacking up style tags
await jsRuntime.AddCss(".demo { color: #22d3ee }", "my-styles", skipIfElementExists: true);

// from an <EmbeddedResource> of the calling assembly
await jsRuntime.LoadCss("css/component.css");

// or from a specific assembly
await jsRuntime.LoadCss("css/component.css", typeof(MyComponent).Assembly);

<ItemGroup>
  <EmbeddedResource Include="wwwroot\css\component.css" />
</ItemGroup>

await jsRuntime.DInvokeVoidAsync(window => window.alert("test"));

var answer = await jsRuntime.DInvokeAsync<string>(window => window.prompt("Your name?"));
var title  = await jsRuntime.DInvokeAsync<string>(document => document.title);

// DOES NOT WORK - currentCount is unknown in the browser
await jsRuntime.DInvokeVoidAsync(window => window.alert(currentCount));

// works: the value is a lambda parameter
await jsRuntime.DInvokeVoidAsync((window, c) => window.alert(c), currentCount);
await jsRuntime.DInvokeVoidAsync((window, c, name) => {
    window.alert(c);
    window.console.log(name);
}, currentCount, "Flo");

// works too: JSArgument keeps the original variable names
await jsRuntime.DInvokeVoidAsync(window => window.alert(currentCount + " - " + name),
                                 JSArgument.For(currentCount).And(name));

var hash = await jsRuntime.DInvokeAsync<string>(window =>
{
    window.alert(currentCount);
    return window.location.hash + "_" + currentCount;
}, JSArgument.For(currentCount));

await jsRuntime.DInvokeVoidAsync(document => document.location.hash = hash,
                                 JSArgument.For(hash));

var copied = await jsRuntime.CopyToClipboardAsync("Copied with BlazorJS");
if (!copied)
    await jsRuntime.AlertAsync("The browser refused the copy.");

// reading always needs a secure context and a user permission
var text = await jsRuntime.ReadClipboardAsync();   // null when denied

await jsRuntime.AlertAsync("Saved");
var ok    = await jsRuntime.ConfirmAsync("Delete this item?");
var name  = await jsRuntime.PromptAsync("Your name?", "Flo");

// DOM helpers
var exists  = await jsRuntime.IsElementAvailableAsync("my-element-id");
await jsRuntime.RemoveElementAsync("my-element-id");
var scripts = await jsRuntime.GetLoadedScriptsAsync();

// wait for a global that a third party script defines
var ready = await jsRuntime.WaitForNamespaceAsync("google.maps", TimeSpan.FromSeconds(10),
                                                  TimeSpan.FromMilliseconds(100));

// hit testing for a mouse event
var inside = await jsRuntime.IsEventWithin(mouseArgs, elementReference);

// plain import
var module = await jsRuntime.ImportModuleAsync("./js/mymodule.js");

// import and publish it on window, so plain interop calls can reach it
await jsRuntime.ImportModuleAsAsync("./js/mymodule.js", "MyModule");
await jsRuntime.InvokeVoidAsync("MyModule.doSomething");

// import and immediately create a JS object from an exported factory
var (module, instance) = await jsRuntime.ImportModuleAndCreateJsAsync(
    "./js/mymodule.js", "initialize", elementReference, dotNetReference);

// a string, the mime type defaults to text/plain
await jsRuntime.SaveFileAsync("notes.txt", "Written by BlazorJS");

// bytes
await jsRuntime.SaveFileAsync("report.pdf", pdfBytes, "application/pdf");

// or a stream, nothing is buffered in memory twice
await using var stream = File.OpenRead(path);
var saved = await jsRuntime.SaveFileAsync("export.csv", stream, "text/csv");

if (!saved)
    Console.WriteLine("The user closed the save dialog.");

private BlazorJSEventInterop<PointerEventArgs> _jsEvent;

protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (!firstRender) return;

    _jsEvent = new BlazorJSEventInterop<PointerEventArgs>(jsRuntime);

    // fires when a click happens OUTSIDE of the given selectors - the dropdown case
    await _jsEvent.OnBlur(OnClickedOutside, ".my-dropdown");

    // or hook any event, optionally scoped to a selector
    await _jsEvent.AddEventListener("keydown", OnKeyDown);
    await _jsEvent.AddEventListener("scroll", OnScroll, ".my-list");
}

private Task OnClickedOutside(PointerEventArgs args) => CloseDropdown();

// always dispose, it removes the listeners in the browser again
public ValueTask DisposeAsync() => _jsEvent.DisposeAsync();

private BlazorJSEventInterop<ElementSizeArgs> _resize;
private BlazorJSEventInterop<ElementVisibilityArgs> _visibility;

protected override async Task OnAfterRenderAsync(bool firstRender)
{
    if (!firstRender) return;

    _resize = new BlazorJSEventInterop<ElementSizeArgs>(jsRuntime);
    await _resize.OnResize(OnResized, ".my-chart");      // no selector = the whole viewport

    _visibility = new BlazorJSEventInterop<ElementVisibilityArgs>(jsRuntime);
    await _visibility.OnVisibilityChanged(LoadMore, "#load-more-marker", threshold: 0.5);
}

private Task OnResized(ElementSizeArgs args)
    => InvokeAsync(() => RedrawChart(args.Width, args.Height));

private async Task LoadMore(ElementVisibilityArgs args)
{
    if (args.IsVisible)
        await LoadNextPage();
}

@inherits BlazorJs.BlazorJsBaseComponent<YourComponent>

<div @ref="ElementReference"></div>

public partial class YourComponent
{
    protected override string ComponentJsFile() => "./js/YourComponent.js";
    protected override string ComponentJsInitializeMethodName() => "initializeYourComponent";

    [Parameter] public string SomeGeneralParam { get; set; }

    [Parameter, ForJs] public int ParamForJs { get; set; } = 100;
    [Parameter, ForJs("differentNameInJs")] public int AnotherParam { get; set; } = 100;

    // called automatically whenever a [ForJs] parameter changed
    protected override async Task OnJsOptionsChanged()
    {
        if (JsReference != null)
            await JsReference.InvokeVoidAsync("setOptions", MyJsOptions());
    }

    private object MyJsOptions() => this.AsJsObject(new { configValueWithoutParam = 123 });

    // by default only ElementReference and the dotnet reference are passed
    public override object[] GetJsArguments()
        => new object[] { ElementReference, CreateDotNetObjectReference(), MyJsOptions() };
}

class YourComponent {
    constructor(elementRef, dotNet, options) {
        this.elementRef = elementRef;
        this.dotnet = dotNet;
        this.createWhatever(options);
    }

    createWhatever(options) {
        console.log(options.paramForJs);          // [ForJs] lowercases the first char
        console.log(options.differentNameInJs);   // unless you name it yourself
        console.log(options.configValueWithoutParam);
    }

    setOptions(options) { /* apply the new options */ }

    // dispose is called by the base component before the reference is released
    dispose() { /* clean up */ }
}

export function initializeYourComponent(elementRef, dotnet, options) {
    return new YourComponent(elementRef, dotnet, options);
}

[Parameter, ForJs] public int Delay { get; set; }                  // -> options.delay
[Parameter, ForJs("speed")] public int AnimationSpeed { get; set; } // -> options.speed

// changes trigger OnJsOptionsChanged but the value is not part of the options object
[Parameter, ForJs(IgnoreOnParams = true)] public bool Refresh { get; set; }

// build the object, optionally merged with values that are not parameters
var options = this.AsJsObject(new { theme = "dark" });

<BrowserDetect @bind-browserInfo="@Info"
               OSVersionUpdate="v => osVersion = v"
               OSArchitectureUpdate="a => architecture = a" />

@code {
    public BrowserInfo Info { get; set; }
}