feat: PostBack shim + ScriptManagerShim runtime (Phase 2)

- GetPostBackEventReference() returns working __doPostBack JS string
- GetPostBackClientHyperlink() returns javascript: URL
- GetCallbackEventReference() returns working JS callback bridge
- Created bwfc-postback.js with __doPostBack and callback interop
- PostBackEventArgs for event handling
- ScriptManagerShim with GetCurrent() factory pattern
- WebFormsPageBase postback target registration via JS interop
- Registered ScriptManagerShim in DI

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: csharpfritz

src/BlazorWebFormsComponents.Test/ClientScriptShimTests.cs

@@ -350,43 +350,76 @@ public async Task FlushAsync_ReRegistering_AfterFlush_Works()
 
 	#endregion
 
-	#region Unsupported Methods
+	#region PostBack / Callback Methods
 
-	// NOTE: Exact method signatures depend on Cyclops's implementation.
-	// These tests verify the throw behavior — signatures may need adjustment
-	// once the shim is finalized.
+	// These methods now return working JavaScript strings instead of throwing.
 
 	[Fact]
-	public void GetPostBackEventReference_ThrowsNotSupported()
+	public void GetPostBackEventReference_ReturnsDoPostBackJs()
 	{
 		var shim = CreateShim();
 
-		var ex = Should.Throw<NotSupportedException>(() =>
-			shim.GetPostBackEventReference(null!, "arg"));
+		var result = shim.GetPostBackEventReference(new object(), "arg");
 
-		ex.Message.ShouldNotBeNullOrWhiteSpace();
+		result.ShouldContain("__doPostBack");
+		result.ShouldContain("arg");
 	}
 
 	[Fact]
-	public void GetPostBackClientHyperlink_ThrowsNotSupported()
+	public void GetPostBackEventReference_NullControl_ReturnsUnknownTarget()
 	{
 		var shim = CreateShim();
 
-		var ex = Should.Throw<NotSupportedException>(() =>
-			shim.GetPostBackClientHyperlink(null!, "arg"));
+		var result = shim.GetPostBackEventReference(null!, "arg");
 
-		ex.Message.ShouldNotBeNullOrWhiteSpace();
+		result.ShouldContain("__doPostBack('unknown',");
 	}
 
 	[Fact]
-	public void GetCallbackEventReference_ThrowsNotSupported()
+	public void GetPostBackEventReference_NullArgument_DefaultsToEmpty()
 	{
 		var shim = CreateShim();
 
-		var ex = Should.Throw<NotSupportedException>(() =>
-			shim.GetCallbackEventReference(null!, "arg", "callback", "ctx", "errorCb", false));
+		var result = shim.GetPostBackEventReference(new object(), null!);
 
-		ex.Message.ShouldNotBeNullOrWhiteSpace();
+		result.ShouldContain("__doPostBack(");
+		result.ShouldContain("''");
+	}
+
+	[Fact]
+	public void GetPostBackClientHyperlink_ReturnsJavascriptUrl()
+	{
+		var shim = CreateShim();
+
+		var result = shim.GetPostBackClientHyperlink(new object(), "arg");
+
+		result.ShouldStartWith("javascript:");
+		result.ShouldContain("__doPostBack");
+	}
+
+	[Fact]
+	public void GetCallbackEventReference_ReturnsCallbackJs()
+	{
+		var shim = CreateShim();
+
+		var result = shim.GetCallbackEventReference(
+			new object(), "arg", "onSuccess", "ctx", "onError", false);
+
+		result.ShouldContain("__bwfc_callback");
+		result.ShouldContain("arg");
+		result.ShouldContain("onSuccess");
+		result.ShouldContain("onError");
+	}
+
+	[Fact]
+	public void GetCallbackEventReference_NullCallbacks_UsesNull()
+	{
+		var shim = CreateShim();
+
+		var result = shim.GetCallbackEventReference(
+			new object(), "arg", null!, null, null!, false);
+
+		result.ShouldContain("null");
 	}
 
 	#endregion

src/BlazorWebFormsComponents/ClientScriptShim.cs

@@ -2,6 +2,7 @@
 using System.Collections.Generic;
 using System.Text.RegularExpressions;
 using System.Threading.Tasks;
+using Microsoft.AspNetCore.Components;
 using Microsoft.Extensions.Logging;
 using Microsoft.JSInterop;
 
@@ -192,45 +193,46 @@ public async Task FlushAsync(IJSRuntime jsRuntime)
 		_scriptIncludes.Clear();
 	}
 
-	// ─── Unsupported Methods ───────────────────────────────────────────
+	// ─── PostBack / Callback Methods ──────────────────────────────────
 
 	/// <summary>
-	/// Not supported in Blazor. Throws <see cref="NotSupportedException"/>
-	/// with migration guidance.
+	/// Returns a JavaScript string that triggers a postback, mirroring the
+	/// Web Forms <c>ClientScriptManager.GetPostBackEventReference</c> behavior.
+	/// The returned string calls <c>__doPostBack(eventTarget, eventArgument)</c>,
+	/// which is defined in <c>bwfc-postback.js</c>.
 	/// </summary>
-	/// <exception cref="NotSupportedException">Always thrown.</exception>
+	/// <param name="control">The control initiating the postback (used to resolve an ID).</param>
+	/// <param name="argument">The event argument string.</param>
+	/// <returns>A JavaScript expression string, e.g. <c>__doPostBack('Button1', '')</c>.</returns>
 	public string GetPostBackEventReference(object control, string argument)
 	{
-		throw new NotSupportedException(
-			"GetPostBackEventReference is not supported in Blazor. " +
-			"Use @onclick / EventCallback<T> instead. " +
-			"See: docs/Migration/ClientScriptMigrationGuide.md");
+		var id = ResolveControlId(control);
+		return $"__doPostBack('{EscapeJsString(id)}', '{EscapeJsString(argument ?? string.Empty)}')";
 	}
 
 	/// <summary>
-	/// Not supported in Blazor. Throws <see cref="NotSupportedException"/>
-	/// with migration guidance.
+	/// Returns a <c>javascript:</c> URL that triggers a postback, mirroring
+	/// <c>ClientScriptManager.GetPostBackClientHyperlink</c>.
 	/// </summary>
-	/// <exception cref="NotSupportedException">Always thrown.</exception>
+	/// <param name="control">The control initiating the postback.</param>
+	/// <param name="argument">The event argument string.</param>
+	/// <returns>A <c>javascript:__doPostBack(...)</c> URL string.</returns>
 	public string GetPostBackClientHyperlink(object control, string argument)
 	{
-		throw new NotSupportedException(
-			"GetPostBackClientHyperlink is not supported in Blazor. " +
-			"Use NavigationManager or <a href=\"...\"> instead. " +
-			"See: docs/Migration/ClientScriptMigrationGuide.md");
+		return $"javascript:{GetPostBackEventReference(control, argument)}";
 	}
 
 	/// <summary>
-	/// Not supported in Blazor. Throws <see cref="NotSupportedException"/>
-	/// with migration guidance.
+	/// Returns a JavaScript expression that invokes the BWFC callback bridge,
+	/// mirroring <c>ClientScriptManager.GetCallbackEventReference</c>.
+	/// The returned expression calls <c>__bwfc_callback</c> defined in
+	/// <c>bwfc-postback.js</c>.
 	/// </summary>
-	/// <exception cref="NotSupportedException">Always thrown.</exception>
-	public string GetCallbackEventReference(object control, string argument, string clientCallback, string context, string clientErrorCallback, bool useAsync)
+	public string GetCallbackEventReference(object control, string argument,
+		string clientCallback, string context, string clientErrorCallback, bool useAsync)
 	{
-		throw new NotSupportedException(
-			"GetCallbackEventReference is not supported in Blazor. " +
-			"Use IJSRuntime / EventCallback<T> for JS-to-.NET interop. " +
-			"See: docs/Migration/ClientScriptMigrationGuide.md");
+		var id = ResolveControlId(control);
+		return $"__bwfc_callback('{EscapeJsString(id)}', '{EscapeJsString(argument ?? string.Empty)}', {clientCallback ?? "null"}, '{EscapeJsString(context ?? string.Empty)}', {clientErrorCallback ?? "null"})";
 	}
 
 	// ─── Helpers ───────────────────────────────────────────────────────
@@ -250,4 +252,18 @@ private static string EscapeJsString(string value)
 	{
 		return value.Replace("\\", "\\\\").Replace("'", "\\'");
 	}
+
+	/// <summary>
+	/// Resolves a control reference to an ID string suitable for use in
+	/// JavaScript postback/callback expressions.
+	/// Prefers <see cref="BaseWebFormsComponent.ID"/> when available.
+	/// </summary>
+	private static string ResolveControlId(object control)
+	{
+		if (control is BaseWebFormsComponent bwfc && !string.IsNullOrEmpty(bwfc.ID))
+			return bwfc.ID;
+		if (control is ComponentBase)
+			return control.GetType().Name;
+		return control?.GetType().Name ?? "unknown";
+	}
 }

src/BlazorWebFormsComponents/PostBackEventArgs.cs

@@ -0,0 +1,23 @@
+using System;
+
+namespace BlazorWebFormsComponents;
+
+/// <summary>
+/// Event arguments for postback events, mirroring the Web Forms postback model.
+/// Contains the <see cref="EventTarget"/> (control ID) and <see cref="EventArgument"/>
+/// that were passed to <c>__doPostBack(eventTarget, eventArgument)</c>.
+/// </summary>
+public class PostBackEventArgs : EventArgs
+{
+	/// <summary>The ID of the control that initiated the postback.</summary>
+	public string EventTarget { get; }
+
+	/// <summary>The argument string associated with the postback.</summary>
+	public string EventArgument { get; }
+
+	public PostBackEventArgs(string eventTarget, string eventArgument)
+	{
+		EventTarget = eventTarget;
+		EventArgument = eventArgument;
+	}
+}

src/BlazorWebFormsComponents/ScriptManagerShim.cs

@@ -0,0 +1,66 @@
+using System;
+
+namespace BlazorWebFormsComponents;
+
+/// <summary>
+/// Compatibility shim for <c>System.Web.UI.ScriptManager</c>.
+/// Provides the static <see cref="GetCurrent"/> factory method that Web Forms
+/// code uses to obtain a <c>ScriptManager</c> instance from the page, and
+/// delegates all <c>RegisterXxx</c> calls to <see cref="ClientScriptShim"/>.
+/// </summary>
+public class ScriptManagerShim
+{
+	private readonly ClientScriptShim _clientScript;
+
+	/// <summary>
+	/// Initializes a new instance backed by the specified <see cref="ClientScriptShim"/>.
+	/// </summary>
+	public ScriptManagerShim(ClientScriptShim clientScript)
+	{
+		_clientScript = clientScript ?? throw new ArgumentNullException(nameof(clientScript));
+	}
+
+	/// <summary>
+	/// Static factory matching the Web Forms <c>ScriptManager.GetCurrent(Page)</c> pattern.
+	/// Resolves the <see cref="ClientScriptShim"/> from the page/component instance.
+	/// </summary>
+	/// <param name="page">
+	/// A <see cref="BaseWebFormsComponent"/> or <see cref="WebFormsPageBase"/> instance.
+	/// </param>
+	/// <returns>A <see cref="ScriptManagerShim"/> wrapping the component's ClientScript.</returns>
+	/// <exception cref="InvalidOperationException">
+	/// Thrown when <paramref name="page"/> is not a recognized BWFC type or has no ClientScript.
+	/// </exception>
+	public static ScriptManagerShim GetCurrent(object page)
+	{
+		if (page is BaseWebFormsComponent component && component.ClientScript != null)
+			return new ScriptManagerShim(component.ClientScript);
+		if (page is WebFormsPageBase pageBase && pageBase.ClientScript != null)
+			return new ScriptManagerShim(pageBase.ClientScript);
+
+		throw new InvalidOperationException(
+			"ScriptManager.GetCurrent() requires a component derived from " +
+			"BaseWebFormsComponent or WebFormsPageBase with a registered ClientScriptShim.");
+	}
+
+	// ─── Delegated Registration Methods ───────────────────────────────
+
+	/// <inheritdoc cref="ClientScriptShim.RegisterStartupScript(Type, string, string, bool)"/>
+	public void RegisterStartupScript(Type type, string key, string script, bool addScriptTags)
+		=> _clientScript.RegisterStartupScript(type, key, script, addScriptTags);
+
+	/// <summary>
+	/// Overload accepting a control reference (ignored) to match the Web Forms
+	/// <c>ScriptManager.RegisterStartupScript(Control, Type, String, String, Boolean)</c> signature.
+	/// </summary>
+	public void RegisterStartupScript(object control, Type type, string key, string script, bool addScriptTags)
+		=> _clientScript.RegisterStartupScript(type, key, script, addScriptTags);
+
+	/// <inheritdoc cref="ClientScriptShim.RegisterClientScriptBlock(Type, string, string, bool)"/>
+	public void RegisterClientScriptBlock(Type type, string key, string script, bool addScriptTags)
+		=> _clientScript.RegisterClientScriptBlock(type, key, script, addScriptTags);
+
+	/// <inheritdoc cref="ClientScriptShim.RegisterClientScriptInclude(Type, string, string)"/>
+	public void RegisterClientScriptInclude(Type type, string key, string url)
+		=> _clientScript.RegisterClientScriptInclude(type, key, url);
+}

src/BlazorWebFormsComponents/ServiceCollectionExtensions.cs

@@ -43,6 +43,7 @@ public static IServiceCollection AddBlazorWebFormsComponents(this IServiceCollec
         services.AddScoped<ServerShim>();
         services.AddScoped<CacheShim>();
         services.AddScoped<ClientScriptShim>();
+        services.AddScoped(sp => new ScriptManagerShim(sp.GetRequiredService<ClientScriptShim>()));
 
         var options = new BlazorWebFormsComponentsOptions();
         configure?.Invoke(options);