Merge pull request #80 from rameel/typed-values

config: use typed values for swap and request options

Author: rameel

samples/Ramstack.HtmxToolkit.Demo/Pages/Examples/RequestOptions.cshtml

@@ -13,15 +13,17 @@
 
   <section class="demo-card">
     <div class="demo-card__header">
-      <h2><code>hx-request-timeout</code></h2>
-      <p>The toolkit emits an HTMX 4 <code>hx-config</code> timeout for this report preview.</p>
+      <h2><code>hx-request-*</code></h2>
+      <p>The toolkit emits an HTMX 4 <code>hx-config</code> with a timeout, cache mode, and redirect mode for this report preview.</p>
     </div>
 
     <div class="demo-actions">
       <button hx-get
               hx-page="/Examples/RequestOptions"
               hx-page-handler="Preview"
               hx-request-timeout="2000"
+              hx-request-cache="@HtmxRequestCache.NoCache"
+              hx-request-redirect="@HtmxRequestRedirect.Error"
               hx-target="#preview-result">
         Generate report preview
       </button>

src/Ramstack.HtmxToolkit/Configuration/HtmxV1Config.cs

@@ -182,16 +182,6 @@ public bool? UseTemplateFragments
         set => SetField(ref field, value);
     }
 
-    /// <summary>
-    /// Gets or sets the WebSocket reconnection delay strategy.
-    /// The HTMX default is <c>full-jitter</c>.
-    /// </summary>
-    public string? WsReconnectDelay
-    {
-        get;
-        set => SetField(ref field, value);
-    }
-
     /// <summary>
     /// Gets or sets the type of binary data received over WebSocket connections.
     /// The HTMX default is <see cref="HtmxBinaryType.Blob" />.

src/Ramstack.HtmxToolkit/Configuration/HtmxV2Config.cs

@@ -182,17 +182,6 @@ public string[]? AttributesToSettle
         set => SetField(ref field, value);
     }
 
-    /// <summary>
-    /// Gets or sets the WebSocket reconnection delay strategy.
-    /// The HTMX default is <c>full-jitter</c>.
-    /// </summary>
-    /// <remarks>Requires the HTMX WebSocket extension.</remarks>
-    public string? WsReconnectDelay
-    {
-        get;
-        set => SetField(ref field, value);
-    }
-
     /// <summary>
     /// Gets or sets the type of binary data received over WebSocket connections.
     /// The HTMX default is <see cref="HtmxBinaryType.Blob" />.

src/Ramstack.HtmxToolkit/Configuration/HtmxV4Config.cs

@@ -121,9 +121,13 @@ public string? InlineScriptNonce
     }
 
     /// <summary>
-    /// Gets or sets a comma-separated list of extensions that HTMX is allowed to load.
-    /// The HTMX default is an empty string.
+    /// Gets or sets a comma-separated list of extensions that HTMX is allowed to register.
+    /// The HTMX default is an empty string, which allows all extensions.
     /// </summary>
+    /// <remarks>
+    /// HTMX compares extension names exactly. Whitespace is allowed only after a comma;
+    /// any other whitespace becomes part of a name, so <c>"sse ,ws"</c> does not allow <c>sse</c>.
+    /// </remarks>
     public string? Extensions
     {
         get;

src/Ramstack.HtmxToolkit/Configuration/ResponseHandlingConfig.cs

@@ -1,3 +1,7 @@
+using System.Text.Json.Serialization;
+
+using Ramstack.HtmxToolkit.Internal;
+
 namespace Ramstack.HtmxToolkit.Configuration;
 
 /// <summary>
@@ -37,7 +41,23 @@ public sealed class ResponseHandlingConfig
     public string? Target { get; set; }
 
     /// <summary>
-    /// Gets or sets an alternative swap mechanism for the response.
+    /// Gets or sets an alternative swap style for the response.
+    /// </summary>
+    /// <remarks>
+    /// Reads the style from <see cref="SwapOverrideExpression" />, or returns <see langword="null" />
+    /// if the style is not recognized. Assigning a style replaces the complete expression,
+    /// including any modifiers. Assigning <see langword="null" /> clears the override.
+    /// </remarks>
+    [JsonIgnore]
+    public HtmxSwap? SwapOverride
+    {
+        get => EnumHelper.ParseHtmxSwap(SwapOverrideExpression);
+        set => SwapOverrideExpression = value.GetSwapValue();
+    }
+
+    /// <summary>
+    /// Gets or sets the complete swap override expression, including any swap modifiers.
     /// </summary>
-    public string? SwapOverride { get; set; }
+    [JsonPropertyName("swapOverride")]
+    public string? SwapOverrideExpression { get; set; }
 }

src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs

@@ -1,3 +1,5 @@
+using Ramstack.HtmxToolkit.Internal;
+
 namespace Ramstack.HtmxToolkit;
 
 /// <summary>
@@ -20,8 +22,25 @@ public sealed class HtmxLocationOptions
     /// <summary>
     /// Gets or sets how the response will be swapped relative to the target element.
     /// </summary>
+    /// <remarks>
+    /// <para>Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x.</para>
+    /// <para>
+    ///   Reads the style from <see cref="SwapExpression" />, or returns <see langword="null" />
+    ///   if the style is not recognized. Assigning a style replaces the complete expression,
+    ///   including any modifiers. Assigning <see langword="null" /> clears the swap.
+    /// </para>
+    /// </remarks>
+    public HtmxSwap? Swap
+    {
+        get => EnumHelper.ParseHtmxSwap(SwapExpression);
+        set => SwapExpression = value.GetSwapValue();
+    }
+
+    /// <summary>
+    /// Gets or sets the complete swap expression, including any swap modifiers.
+    /// </summary>
     /// <remarks>Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x.</remarks>
-    public HtmxSwap? Swap { get; set; }
+    public string? SwapExpression { get; set; }
 
     /// <summary>
     /// Gets or sets the form field values to submit with the request.

src/Ramstack.HtmxToolkit/HtmxRequestCache.cs

@@ -0,0 +1,42 @@
+namespace Ramstack.HtmxToolkit;
+
+/// <summary>
+/// Specifies the Fetch cache mode for an HTMX request.
+/// </summary>
+/// <remarks>Supported only in HTMX 4.x.</remarks>
+public enum HtmxRequestCache
+{
+    /// <summary>
+    /// Uses the browser's normal HTTP cache behavior.
+    /// </summary>
+    Default,
+
+    /// <summary>
+    /// Bypasses the cache and does not store the response in it.
+    /// </summary>
+    NoStore,
+
+    /// <summary>
+    /// Bypasses the cache lookup and updates the cache with the response.
+    /// </summary>
+    Reload,
+
+    /// <summary>
+    /// Revalidates a cached response before using it.
+    /// </summary>
+    NoCache,
+
+    /// <summary>
+    /// Uses a cached response even if stale, or fetches and caches a response on a cache miss.
+    /// </summary>
+    ForceCache,
+
+    /// <summary>
+    /// Uses a cached response even if stale, and fails on a cache miss.
+    /// </summary>
+    /// <remarks>
+    /// Requires the same-origin Fetch mode, which is the HTMX default.
+    /// The request fails if <see cref="Configuration.HtmxV4Config.Mode" /> specifies another mode.
+    /// </remarks>
+    OnlyIfCached
+}

src/Ramstack.HtmxToolkit/HtmxRequestRedirect.cs

@@ -0,0 +1,31 @@
+namespace Ramstack.HtmxToolkit;
+
+/// <summary>
+/// Specifies the Fetch redirect mode for an HTMX request.
+/// </summary>
+/// <remarks>Supported only in HTMX 4.x.</remarks>
+public enum HtmxRequestRedirect
+{
+    /// <summary>
+    /// Follows redirects automatically.
+    /// </summary>
+    Follow,
+
+    /// <summary>
+    /// Fails the request when a redirect is encountered.
+    /// </summary>
+    /// <remarks>
+    /// HTMX raises the <c>htmx:error</c> event and does not swap the response.
+    /// </remarks>
+    Error,
+
+    /// <summary>
+    /// Returns an opaque redirect response instead of following the redirect.
+    /// </summary>
+    /// <remarks>
+    /// The response has status 0, and its headers and body are not accessible.
+    /// HTMX cannot read <c>HX-*</c> response headers, does not treat the response as an error,
+    /// and swaps the empty body into the target.
+    /// </remarks>
+    Manual
+}

src/Ramstack.HtmxToolkit/HtmxResponse.cs

@@ -197,10 +197,10 @@ public HtmxResponse Reselect(string value) =>
         SetHeader(this, HtmxResponseHeaderNames.Reselect, value);
 
     /// <summary>
-    /// Adds a client-side event to the response header selected by <paramref name="trigger" />.
+    /// Adds a client-side event to the response header selected by <paramref name="timing" />.
     /// </summary>
     /// <param name="eventName">The event name to trigger.</param>
-    /// <param name="trigger">The event timing. Defaults to <see cref="HtmxTriggerTiming.Receive" />.</param>
+    /// <param name="timing">The event timing. Defaults to <see cref="HtmxTriggerTiming.Receive" />.</param>
     /// <returns>
     /// The current <see cref="HtmxResponse" /> instance.
     /// </returns>
@@ -209,8 +209,8 @@ public HtmxResponse Reselect(string value) =>
     /// <c>HX-Trigger</c> and runs when the request completes (after the swap whenever one is performed).
     /// See <see href="https://github.com/bigskysoftware/htmx/pull/3900">PR #3900</see>.
     /// </remarks>
-    public HtmxResponse TriggerEvent(string eventName, HtmxTriggerTiming trigger = HtmxTriggerTiming.Receive) =>
-        AddToPendingEvent(this, eventName, "{}", trigger);
+    public HtmxResponse TriggerEvent(string eventName, HtmxTriggerTiming timing = HtmxTriggerTiming.Receive) =>
+        AddToPendingEvent(this, eventName, "{}", timing);
 
     /// <summary>
     /// Adds a client-side event and its detail to the response header selected by

src/Ramstack.HtmxToolkit/Serialization/HtmxLocationOptionsJsonView.cs

@@ -25,10 +25,9 @@ internal readonly struct HtmxLocationOptionsJsonView(string path, HtmxLocationOp
     public string? Target => options.Target;
 
     /// <summary>
-    /// Gets the serialized swap style.
+    /// Gets the swap expression.
     /// </summary>
-    [JsonConverter(typeof(HtmxSwapJsonConverter))]
-    public HtmxSwap? Swap => options.Swap;
+    public string? Swap => options.SwapExpression;
 
     /// <summary>
     /// Gets the form field values.