From aa1d776702494fbb916311f4a189a0fc551377b8 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sat, 29 Aug 2026 21:58:52 +0500
Subject: [PATCH 01/14] Replace object with strongly-typed value in
 AjaxContext.Values

---
 src/Ramstack.HtmxToolkit/AjaxContext.cs       |   2 +-
 .../AjaxContextJsonSerializerContext.cs       |  25 ++
 .../AjaxContextWrapper.cs                     |   2 +-
 src/Ramstack.HtmxToolkit/HtmxHistoryMode.cs   |   2 -
 src/Ramstack.HtmxToolkit/HtmxResponse.cs      |   6 +-
 src/Ramstack.HtmxToolkit/HtmxValue.cs         | 241 ++++++++++++++++++
 .../HtmxValueJsonConverter.cs                 |  37 +++
 .../Internal/JsonOptions.cs                   |  10 -
 .../Properties/CollectionBuilderAttribute.cs  |  31 +++
 .../HtmxResponseTests.cs                      |  14 +-
 10 files changed, 351 insertions(+), 19 deletions(-)
 create mode 100644 src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs
 create mode 100644 src/Ramstack.HtmxToolkit/HtmxValue.cs
 create mode 100644 src/Ramstack.HtmxToolkit/HtmxValueJsonConverter.cs
 create mode 100644 src/Ramstack.HtmxToolkit/Properties/CollectionBuilderAttribute.cs

diff --git a/src/Ramstack.HtmxToolkit/AjaxContext.cs b/src/Ramstack.HtmxToolkit/AjaxContext.cs
index 3b5a166..b7edbd3 100644
--- a/src/Ramstack.HtmxToolkit/AjaxContext.cs
+++ b/src/Ramstack.HtmxToolkit/AjaxContext.cs
@@ -38,7 +38,7 @@ public sealed class AjaxContext
     /// <summary>
     /// Gets or sets the values to submit with the request.
     /// </summary>
-    public object? Values { get; set; }
+    public IDictionary<string, HtmxValue>? Values { get; set; }
 
     /// <summary>
     /// Gets or sets the headers to include with the request.
diff --git a/src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs b/src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs
new file mode 100644
index 0000000..91b0870
--- /dev/null
+++ b/src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs
@@ -0,0 +1,25 @@
+using System.Text.Json.Serialization;
+
+using Ramstack.HtmxToolkit.Internal;
+
+namespace Ramstack.HtmxToolkit;
+
+/// <summary>
+/// Provides source-generated JSON serialization metadata for AJAX context data.
+/// </summary>
+[JsonSourceGenerationOptions(
+    WriteIndented = false,
+    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+    GenerationMode = JsonSourceGenerationMode.Default)]
+[JsonSerializable(typeof(AjaxContextWrapper))]
+internal partial class AjaxContextJsonSerializerContext : JsonSerializerContext
+{
+    /// <summary>
+    /// Initializes the default serializer context with HTML-safe Unicode encoding.
+    /// </summary>
+    static AjaxContextJsonSerializerContext()
+    {
+        JsonOptions.ConfigureHtmlSafeUnicode(s_defaultOptions);
+        s_defaultContext = new AjaxContextJsonSerializerContext(s_defaultOptions);
+    }
+}
diff --git a/src/Ramstack.HtmxToolkit/AjaxContextWrapper.cs b/src/Ramstack.HtmxToolkit/AjaxContextWrapper.cs
index ea72b15..bd3cbf3 100644
--- a/src/Ramstack.HtmxToolkit/AjaxContextWrapper.cs
+++ b/src/Ramstack.HtmxToolkit/AjaxContextWrapper.cs
@@ -17,7 +17,7 @@ internal readonly struct AjaxContextWrapper
     [JsonPropertyName("handler")] public string? Handler => _context.Handler;
     [JsonPropertyName("target")]  public string? Target => _context.Target;
     [JsonPropertyName("swap")]    public string? Swap => _context.Swap.GetSwapValue();
-    [JsonPropertyName("values")]  public object? Values => _context.Values;
+    [JsonPropertyName("values")]  public IDictionary<string, HtmxValue>? Values => _context.Values;
     [JsonPropertyName("headers")] public IDictionary<string, string>? Headers => _context.Headers;
     [JsonPropertyName("select")]  public string? Select => _context.Select;
 
diff --git a/src/Ramstack.HtmxToolkit/HtmxHistoryMode.cs b/src/Ramstack.HtmxToolkit/HtmxHistoryMode.cs
index 96c07fa..c5eec00 100644
--- a/src/Ramstack.HtmxToolkit/HtmxHistoryMode.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxHistoryMode.cs
@@ -1,5 +1,3 @@
-using System.Text.Json.Serialization;
-
 namespace Ramstack.HtmxToolkit;
 
 /// <summary>
diff --git a/src/Ramstack.HtmxToolkit/HtmxResponse.cs b/src/Ramstack.HtmxToolkit/HtmxResponse.cs
index 83cdaa5..72ce3f6 100644
--- a/src/Ramstack.HtmxToolkit/HtmxResponse.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxResponse.cs
@@ -2,7 +2,6 @@
 using System.Text.Json;
 
 using Microsoft.AspNetCore.Http;
-using Microsoft.Extensions.Primitives;
 
 using Ramstack.HtmxToolkit.Internal;
 
@@ -61,7 +60,10 @@ public HtmxResponse Location(string path, AjaxContext context)
 
         static HtmxResponse LocationImpl(HtmxResponse response, string path, AjaxContext context)
         {
-            var value = JsonSerializer.Serialize(new AjaxContextWrapper(path, context), JsonOptions.PreserveKeyCase);
+            var value = JsonSerializer.Serialize(
+                new AjaxContextWrapper(path, context),
+                AjaxContextJsonSerializerContext.Default.AjaxContextWrapper);
+
             return SetHeader(response, HtmxResponseHeaderNames.Location, value);
         }
     }
diff --git a/src/Ramstack.HtmxToolkit/HtmxValue.cs b/src/Ramstack.HtmxToolkit/HtmxValue.cs
new file mode 100644
index 0000000..4bde3b0
--- /dev/null
+++ b/src/Ramstack.HtmxToolkit/HtmxValue.cs
@@ -0,0 +1,241 @@
+using System.Collections;
+using System.Runtime.CompilerServices;
+using System.Text.Json.Serialization;
+
+namespace Ramstack.HtmxToolkit;
+
+/// <summary>
+/// Represents one or more string values for an HTMX request parameter.
+/// </summary>
+/// <remarks>
+/// A single value can be assigned from a string. Multiple values can be specified with a collection expression.
+/// </remarks>
+[CollectionBuilder(typeof(HtmxValue), nameof(Create))]
+[JsonConverter(typeof(HtmxValueJsonConverter))]
+public readonly struct HtmxValue : IReadOnlyList<string>
+{
+    private readonly object? _values;
+
+    /// <inheritdoc />
+    public int Count
+    {
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        get
+        {
+            var values = _values;
+            if (values is null)
+                return 0;
+
+            if (values is string)
+                return 1;
+
+            return Unsafe.As<string[]>(values).Length;
+        }
+    }
+
+    /// <inheritdoc />
+    public string this[int index]
+    {
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        get
+        {
+            var values = _values;
+            if (values is string s)
+            {
+                if (index == 0)
+                    return s;
+            }
+            else if (values is not null)
+            {
+                return Unsafe.As<string[]>(values)[index];
+            }
+
+            return OutOfBounds();
+        }
+    }
+
+    /// <summary>
+    /// Gets the underlying value representation.
+    /// </summary>
+    /// <value>
+    /// <see langword="null"/> when the collection is empty, a <see cref="string"/>
+    /// when it contains one value, or a string array when it contains multiple values.
+    /// </value>
+    public object? Values => _values;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HtmxValue"/> structure with a single value.
+    /// </summary>
+    /// <param name="value">The value to store.</param>
+    public HtmxValue(string value) =>
+        _values = value;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HtmxValue"/> structure with the specified values.
+    /// </summary>
+    /// <param name="values">
+    /// The values to store, or <see langword="null"/> to create an empty instance.
+    /// </param>
+    /// <remarks>
+    /// The specified array is stored directly and is not copied.
+    /// </remarks>
+    public HtmxValue(string[]? values) =>
+        _values = values;
+
+    /// <summary>
+    /// Creates an <see cref="HtmxValue"/> from the specified values.
+    /// </summary>
+    /// <param name="values">The values to include.</param>
+    /// <returns>
+    /// An <see cref="HtmxValue"/> containing the specified values.
+    /// </returns>
+    public static HtmxValue Create(ReadOnlySpan<string> values)
+    {
+        return values.Length switch
+        {
+            0 => default,
+            1 => new HtmxValue(values[0]),
+            _ => new HtmxValue(CreateArray(values))
+        };
+    }
+
+    /// <summary>
+    /// Converts a string to an <see cref="HtmxValue"/>.
+    /// </summary>
+    /// <param name="value">The value to convert.</param>
+    public static implicit operator HtmxValue(string value) =>
+        new(value);
+
+    /// <summary>
+    /// Converts an array of strings to an <see cref="HtmxValue"/>.
+    /// </summary>
+    /// <param name="values">The values to convert.</param>
+    public static implicit operator HtmxValue(string[] values) =>
+        new(values);
+
+    /// <summary>
+    /// Returns an enumerator that iterates through the values.
+    /// </summary>
+    /// <returns>
+    /// An enumerator for the values.
+    /// </returns>
+    public Enumerator GetEnumerator() =>
+        new(this);
+
+    #region IEnumerable: explicit interface implementations
+
+    /// <inheritdoc />
+    IEnumerator<string> IEnumerable<string>.GetEnumerator() =>
+        GetEnumerator();
+
+    /// <inheritdoc />
+    IEnumerator IEnumerable.GetEnumerator() =>
+        GetEnumerator();
+
+    #endregion
+
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private static string OutOfBounds() =>
+        Array.Empty<string>()[0];
+
+    /// <summary>
+    /// Copies the specified read-only span to a new array.
+    /// </summary>
+    /// <param name="s">The values to copy.</param>
+    /// <returns>
+    /// A new array containing the specified values.
+    /// </returns>
+    /// <remarks>
+    /// The JIT compiler inlines the implementation of <see cref="ReadOnlySpan{T}.ToArray"/>
+    /// into its caller, producing a disproportionately large amount of native code at the call site.
+    /// This non-inlined wrapper keeps that implementation out of <see cref="Create"/>.
+    /// </remarks>
+    [MethodImpl(MethodImplOptions.NoInlining)]
+    private static string[] CreateArray(ReadOnlySpan<string> s) =>
+        s.ToArray();
+
+    #region Inner type: Enumerator
+
+    /// <summary>
+    /// Enumerates the strings represented by an <see cref="HtmxValue"/>.
+    /// </summary>
+    public struct Enumerator : IEnumerator<string>
+    {
+        private readonly string[]? _values;
+        private string? _current;
+        private int _index;
+
+        /// <inheritdoc />
+        public readonly string Current => _current!;
+
+        /// <summary>
+        /// Initializes a new enumerator for the specified underlying value representation.
+        /// </summary>
+        /// <param name="value">A single string, an array of strings,
+        /// or <see langword="null"/> for an empty sequence.</param>
+        private Enumerator(object? value)
+        {
+            if (value is string s)
+            {
+                (_values, _current) = (null, s);
+            }
+            else
+            {
+                (_values, _current) = (Unsafe.As<string[]?>(value), null);
+            }
+
+            _index = 0;
+        }
+
+        /// <summary>
+        /// Initializes a new enumerator for the specified <see cref="HtmxValue"/>.
+        /// </summary>
+        /// <param name="value">The value whose strings to enumerate.</param>
+        public Enumerator(HtmxValue value) : this(value._values)
+        {
+        }
+
+        /// <inheritdoc />
+        public bool MoveNext()
+        {
+            var index = _index;
+            if (index < 0)
+                return false;
+
+            var values = _values;
+            if (values is not null)
+            {
+                if ((uint)index < (uint)values.Length)
+                {
+                    _index = index + 1;
+                    _current = values[index];
+                    return true;
+                }
+
+                _index = -1;
+                return false;
+            }
+
+            _index = -1;
+            return _current is not null;
+        }
+
+        /// <inheritdoc />
+        public readonly void Dispose()
+        {
+        }
+
+        #region IEnumerator: explicit interface implementations
+
+        /// <inheritdoc />
+        readonly object IEnumerator.Current => Current;
+
+        /// <inheritdoc />
+        void IEnumerator.Reset() =>
+            throw new NotSupportedException();
+
+        #endregion
+    }
+
+    #endregion
+}
diff --git a/src/Ramstack.HtmxToolkit/HtmxValueJsonConverter.cs b/src/Ramstack.HtmxToolkit/HtmxValueJsonConverter.cs
new file mode 100644
index 0000000..dca590b
--- /dev/null
+++ b/src/Ramstack.HtmxToolkit/HtmxValueJsonConverter.cs
@@ -0,0 +1,37 @@
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Ramstack.HtmxToolkit;
+
+/// <summary>
+/// Represents a JSON converter for <see cref="HtmxValue"/>.
+/// </summary>
+internal sealed class HtmxValueJsonConverter : JsonConverter<HtmxValue>
+{
+    /// <inheritdoc />
+    public override HtmxValue Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
+        throw new NotSupportedException();
+
+    /// <inheritdoc />
+    public override void Write(Utf8JsonWriter writer, HtmxValue value, JsonSerializerOptions options)
+    {
+        var values = value.Values;
+        switch (values)
+        {
+            case string s:
+                writer.WriteStringValue(s);
+                break;
+
+            default:
+                writer.WriteStartArray();
+
+                if (values is not null)
+                    foreach (var s in Unsafe.As<string[]>(values))
+                        writer.WriteStringValue(s);
+
+                writer.WriteEndArray();
+                break;
+        }
+    }
+}
diff --git a/src/Ramstack.HtmxToolkit/Internal/JsonOptions.cs b/src/Ramstack.HtmxToolkit/Internal/JsonOptions.cs
index 4b8e29f..c0fd200 100644
--- a/src/Ramstack.HtmxToolkit/Internal/JsonOptions.cs
+++ b/src/Ramstack.HtmxToolkit/Internal/JsonOptions.cs
@@ -34,14 +34,4 @@ public static void ConfigureHtmlSafeUnicode(JsonSerializerOptions options) =>
         DictionaryKeyPolicy = JsonNamingPolicy.CamelCase,
         WriteIndented = false
     };
-
-    /// <summary>
-    /// JSON serializer options that preserve original property and key casing
-    /// while ignoring properties with <see langword="null"/> values.
-    /// </summary>
-    public static readonly JsonSerializerOptions PreserveKeyCase = new()
-    {
-        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
-        WriteIndented = false
-    };
 }
diff --git a/src/Ramstack.HtmxToolkit/Properties/CollectionBuilderAttribute.cs b/src/Ramstack.HtmxToolkit/Properties/CollectionBuilderAttribute.cs
new file mode 100644
index 0000000..444806b
--- /dev/null
+++ b/src/Ramstack.HtmxToolkit/Properties/CollectionBuilderAttribute.cs
@@ -0,0 +1,31 @@
+#if !NET8_0_OR_GREATER
+namespace System.Runtime.CompilerServices;
+
+/// <summary>
+/// Indicates the method used to build a collection from a collection expression.
+/// </summary>
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Interface, Inherited = false)]
+internal sealed class CollectionBuilderAttribute : Attribute
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CollectionBuilderAttribute"/> class.
+    /// </summary>
+    /// <param name="builderType">The type containing the builder method.</param>
+    /// <param name="methodName">The name of the builder method.</param>
+    public CollectionBuilderAttribute(Type builderType, string methodName)
+    {
+        BuilderType = builderType;
+        MethodName = methodName;
+    }
+
+    /// <summary>
+    /// Gets the type containing the builder method.
+    /// </summary>
+    public Type BuilderType { get; }
+
+    /// <summary>
+    /// Gets the name of the builder method.
+    /// </summary>
+    public string MethodName { get; }
+}
+#endif
diff --git a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
index 0adf4a3..7789e11 100644
--- a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
+++ b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
@@ -57,15 +57,23 @@ public void Location_WithContext_SerializesHandlerValuesAndHeaders()
         context.Response.Htmx(r => r.Location("/bar", new AjaxContext
         {
             Handler = "handleResponse",
-            Values = new Dictionary<string, object> { ["id"] = 42 },
-            Headers = new Dictionary<string, string> { ["X-Test"] = "abc" }
+            Values = new Dictionary<string, HtmxValue>
+            {
+                ["id"] = "42",
+                ["tags"] = ["dotnet", "web"]
+            },
+            Headers = new Dictionary<string, string>
+            {
+                ["X-Test"] = "abc"
+            }
         }));
 
         var header = context.Response.Headers[HtmxResponseHeaderNames.Location].ToString();
         var json = JsonHelper.ParseJson(header);
 
         Assert.That(json["handler"].GetString(), Is.EqualTo("handleResponse"));
-        Assert.That(json["values"].GetProperty("id").GetInt32(), Is.EqualTo(42));
+        Assert.That(json["values"].GetProperty("id").GetString(), Is.EqualTo("42"));
+        Assert.That(json["values"].GetProperty("tags").GetRawText(), Is.EqualTo("[\"dotnet\",\"web\"]"));
         Assert.That(json["headers"].GetProperty("X-Test").GetString(), Is.EqualTo("abc"));
     }
 

From 2a7be65eaa231cffaba2b1c4ad7a98978432bb4c Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sat, 29 Aug 2026 22:19:47 +0500
Subject: [PATCH 02/14] Get rid of AjaxContextWrapper and serialize AjaxContext
 directly

---
 src/Ramstack.HtmxToolkit/AjaxContext.cs       |  5 ++-
 .../AjaxContextJsonSerializerContext.cs       |  3 +-
 .../AjaxContextWrapper.cs                     | 34 -------------------
 src/Ramstack.HtmxToolkit/HtmxResponse.cs      |  5 ++-
 4 files changed, 8 insertions(+), 39 deletions(-)
 delete mode 100644 src/Ramstack.HtmxToolkit/AjaxContextWrapper.cs

diff --git a/src/Ramstack.HtmxToolkit/AjaxContext.cs b/src/Ramstack.HtmxToolkit/AjaxContext.cs
index b7edbd3..1c5f12a 100644
--- a/src/Ramstack.HtmxToolkit/AjaxContext.cs
+++ b/src/Ramstack.HtmxToolkit/AjaxContext.cs
@@ -1,3 +1,5 @@
+using System.Text.Json.Serialization;
+
 namespace Ramstack.HtmxToolkit;
 
 /// <summary>
@@ -8,7 +10,7 @@ public sealed class AjaxContext
     /// <summary>
     /// Gets or sets the path used for the AJAX request.
     /// </summary>
-    internal string? Path { get; set; }
+    public string? Path { get; internal set; }
 
     /// <summary>
     /// Gets or sets the source element that initiated the request.
@@ -33,6 +35,7 @@ public sealed class AjaxContext
     /// <summary>
     /// Gets or sets how the response will be swapped relative to the target element.
     /// </summary>
+    [JsonConverter(typeof(HtmxSwapJsonConverter))]
     public HtmxSwap? Swap { get; set; }
 
     /// <summary>
diff --git a/src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs b/src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs
index 91b0870..b8ff5e1 100644
--- a/src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs
+++ b/src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs
@@ -9,9 +9,10 @@ namespace Ramstack.HtmxToolkit;
 /// </summary>
 [JsonSourceGenerationOptions(
     WriteIndented = false,
+    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
     DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
     GenerationMode = JsonSourceGenerationMode.Default)]
-[JsonSerializable(typeof(AjaxContextWrapper))]
+[JsonSerializable(typeof(AjaxContext))]
 internal partial class AjaxContextJsonSerializerContext : JsonSerializerContext
 {
     /// <summary>
diff --git a/src/Ramstack.HtmxToolkit/AjaxContextWrapper.cs b/src/Ramstack.HtmxToolkit/AjaxContextWrapper.cs
deleted file mode 100644
index bd3cbf3..0000000
--- a/src/Ramstack.HtmxToolkit/AjaxContextWrapper.cs
+++ /dev/null
@@ -1,34 +0,0 @@
-using System.Text.Json.Serialization;
-
-using Ramstack.HtmxToolkit.Internal;
-
-namespace Ramstack.HtmxToolkit;
-
-/// <summary>
-/// Represents a wrapper for the <see cref="AjaxContext"/> class, used for serialization.
-/// </summary>
-internal readonly struct AjaxContextWrapper
-{
-    private readonly AjaxContext _context;
-
-    [JsonPropertyName("path")]    public string? Path => _context.Path;
-    [JsonPropertyName("source")]  public string? Source => _context.Source;
-    [JsonPropertyName("event")]   public string? Event => _context.Event;
-    [JsonPropertyName("handler")] public string? Handler => _context.Handler;
-    [JsonPropertyName("target")]  public string? Target => _context.Target;
-    [JsonPropertyName("swap")]    public string? Swap => _context.Swap.GetSwapValue();
-    [JsonPropertyName("values")]  public IDictionary<string, HtmxValue>? Values => _context.Values;
-    [JsonPropertyName("headers")] public IDictionary<string, string>? Headers => _context.Headers;
-    [JsonPropertyName("select")]  public string? Select => _context.Select;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="AjaxContextWrapper"/>.
-    /// </summary>
-    /// <param name="path">The path of the AJAX request.</param>
-    /// <param name="context">The <see cref="AjaxContext"/>.</param>
-    public AjaxContextWrapper(string path, AjaxContext context)
-    {
-        context.Path = path;
-        _context = context;
-    }
-}
diff --git a/src/Ramstack.HtmxToolkit/HtmxResponse.cs b/src/Ramstack.HtmxToolkit/HtmxResponse.cs
index 72ce3f6..26293a5 100644
--- a/src/Ramstack.HtmxToolkit/HtmxResponse.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxResponse.cs
@@ -60,10 +60,9 @@ public HtmxResponse Location(string path, AjaxContext context)
 
         static HtmxResponse LocationImpl(HtmxResponse response, string path, AjaxContext context)
         {
-            var value = JsonSerializer.Serialize(
-                new AjaxContextWrapper(path, context),
-                AjaxContextJsonSerializerContext.Default.AjaxContextWrapper);
+            context.Path = path;
 
+            var value = JsonSerializer.Serialize(context, AjaxContextJsonSerializerContext.Default.AjaxContext);
             return SetHeader(response, HtmxResponseHeaderNames.Location, value);
         }
     }

From 44ca7cc70bb58a984d4ac0bac06b96baad0b5af8 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sat, 29 Aug 2026 22:57:11 +0500
Subject: [PATCH 03/14] Rename HtmxValue to HtmxValues

---
 src/Ramstack.HtmxToolkit/AjaxContext.cs       |  2 +-
 .../{HtmxValue.cs => HtmxValues.cs}           | 40 +++++++++----------
 ...onverter.cs => HtmxValuesJsonConverter.cs} |  8 ++--
 .../HtmxResponseTests.cs                      |  2 +-
 4 files changed, 26 insertions(+), 26 deletions(-)
 rename src/Ramstack.HtmxToolkit/{HtmxValue.cs => HtmxValues.cs} (83%)
 rename src/Ramstack.HtmxToolkit/{HtmxValueJsonConverter.cs => HtmxValuesJsonConverter.cs} (67%)

diff --git a/src/Ramstack.HtmxToolkit/AjaxContext.cs b/src/Ramstack.HtmxToolkit/AjaxContext.cs
index 1c5f12a..d800204 100644
--- a/src/Ramstack.HtmxToolkit/AjaxContext.cs
+++ b/src/Ramstack.HtmxToolkit/AjaxContext.cs
@@ -41,7 +41,7 @@ public sealed class AjaxContext
     /// <summary>
     /// Gets or sets the values to submit with the request.
     /// </summary>
-    public IDictionary<string, HtmxValue>? Values { get; set; }
+    public IDictionary<string, HtmxValues>? Values { get; set; }
 
     /// <summary>
     /// Gets or sets the headers to include with the request.
diff --git a/src/Ramstack.HtmxToolkit/HtmxValue.cs b/src/Ramstack.HtmxToolkit/HtmxValues.cs
similarity index 83%
rename from src/Ramstack.HtmxToolkit/HtmxValue.cs
rename to src/Ramstack.HtmxToolkit/HtmxValues.cs
index 4bde3b0..c8ac9ee 100644
--- a/src/Ramstack.HtmxToolkit/HtmxValue.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxValues.cs
@@ -10,9 +10,9 @@ namespace Ramstack.HtmxToolkit;
 /// <remarks>
 /// A single value can be assigned from a string. Multiple values can be specified with a collection expression.
 /// </remarks>
-[CollectionBuilder(typeof(HtmxValue), nameof(Create))]
-[JsonConverter(typeof(HtmxValueJsonConverter))]
-public readonly struct HtmxValue : IReadOnlyList<string>
+[CollectionBuilder(typeof(HtmxValues), nameof(Create))]
+[JsonConverter(typeof(HtmxValuesJsonConverter))]
+public readonly struct HtmxValues : IReadOnlyList<string>
 {
     private readonly object? _values;
 
@@ -64,14 +64,14 @@ public string this[int index]
     public object? Values => _values;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="HtmxValue"/> structure with a single value.
+    /// Initializes a new instance of the <see cref="HtmxValues"/> structure with a single value.
     /// </summary>
     /// <param name="value">The value to store.</param>
-    public HtmxValue(string value) =>
+    public HtmxValues(string value) =>
         _values = value;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="HtmxValue"/> structure with the specified values.
+    /// Initializes a new instance of the <see cref="HtmxValues"/> structure with the specified values.
     /// </summary>
     /// <param name="values">
     /// The values to store, or <see langword="null"/> to create an empty instance.
@@ -79,38 +79,38 @@ public HtmxValue(string value) =>
     /// <remarks>
     /// The specified array is stored directly and is not copied.
     /// </remarks>
-    public HtmxValue(string[]? values) =>
+    public HtmxValues(string[]? values) =>
         _values = values;
 
     /// <summary>
-    /// Creates an <see cref="HtmxValue"/> from the specified values.
+    /// Creates an <see cref="HtmxValues"/> from the specified values.
     /// </summary>
     /// <param name="values">The values to include.</param>
     /// <returns>
-    /// An <see cref="HtmxValue"/> containing the specified values.
+    /// An <see cref="HtmxValues"/> containing the specified values.
     /// </returns>
-    public static HtmxValue Create(ReadOnlySpan<string> values)
+    public static HtmxValues Create(ReadOnlySpan<string> values)
     {
         return values.Length switch
         {
-            0 => default,
-            1 => new HtmxValue(values[0]),
-            _ => new HtmxValue(CreateArray(values))
+            0 => new HtmxValues([]),
+            1 => new HtmxValues(values[0]),
+            _ => new HtmxValues(CreateArray(values))
         };
     }
 
     /// <summary>
-    /// Converts a string to an <see cref="HtmxValue"/>.
+    /// Converts a string to an <see cref="HtmxValues"/>.
     /// </summary>
     /// <param name="value">The value to convert.</param>
-    public static implicit operator HtmxValue(string value) =>
+    public static implicit operator HtmxValues(string value) =>
         new(value);
 
     /// <summary>
-    /// Converts an array of strings to an <see cref="HtmxValue"/>.
+    /// Converts an array of strings to an <see cref="HtmxValues"/>.
     /// </summary>
     /// <param name="values">The values to convert.</param>
-    public static implicit operator HtmxValue(string[] values) =>
+    public static implicit operator HtmxValues(string[] values) =>
         new(values);
 
     /// <summary>
@@ -157,7 +157,7 @@ private static string[] CreateArray(ReadOnlySpan<string> s) =>
     #region Inner type: Enumerator
 
     /// <summary>
-    /// Enumerates the strings represented by an <see cref="HtmxValue"/>.
+    /// Enumerates the strings represented by an <see cref="HtmxValues"/>.
     /// </summary>
     public struct Enumerator : IEnumerator<string>
     {
@@ -188,10 +188,10 @@ private Enumerator(object? value)
         }
 
         /// <summary>
-        /// Initializes a new enumerator for the specified <see cref="HtmxValue"/>.
+        /// Initializes a new enumerator for the specified <see cref="HtmxValues"/>.
         /// </summary>
         /// <param name="value">The value whose strings to enumerate.</param>
-        public Enumerator(HtmxValue value) : this(value._values)
+        public Enumerator(HtmxValues value) : this(value._values)
         {
         }
 
diff --git a/src/Ramstack.HtmxToolkit/HtmxValueJsonConverter.cs b/src/Ramstack.HtmxToolkit/HtmxValuesJsonConverter.cs
similarity index 67%
rename from src/Ramstack.HtmxToolkit/HtmxValueJsonConverter.cs
rename to src/Ramstack.HtmxToolkit/HtmxValuesJsonConverter.cs
index dca590b..fe0ace7 100644
--- a/src/Ramstack.HtmxToolkit/HtmxValueJsonConverter.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxValuesJsonConverter.cs
@@ -5,16 +5,16 @@
 namespace Ramstack.HtmxToolkit;
 
 /// <summary>
-/// Represents a JSON converter for <see cref="HtmxValue"/>.
+/// Represents a JSON converter for <see cref="HtmxValues"/>.
 /// </summary>
-internal sealed class HtmxValueJsonConverter : JsonConverter<HtmxValue>
+internal sealed class HtmxValuesJsonConverter : JsonConverter<HtmxValues>
 {
     /// <inheritdoc />
-    public override HtmxValue Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
+    public override HtmxValues Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
         throw new NotSupportedException();
 
     /// <inheritdoc />
-    public override void Write(Utf8JsonWriter writer, HtmxValue value, JsonSerializerOptions options)
+    public override void Write(Utf8JsonWriter writer, HtmxValues value, JsonSerializerOptions options)
     {
         var values = value.Values;
         switch (values)
diff --git a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
index 7789e11..e5f9329 100644
--- a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
+++ b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
@@ -57,7 +57,7 @@ public void Location_WithContext_SerializesHandlerValuesAndHeaders()
         context.Response.Htmx(r => r.Location("/bar", new AjaxContext
         {
             Handler = "handleResponse",
-            Values = new Dictionary<string, HtmxValue>
+            Values = new Dictionary<string, HtmxValues>
             {
                 ["id"] = "42",
                 ["tags"] = ["dotnet", "web"]

From 5b82c7d48fb04a1c5eecb09a667dfffa4cfe22c0 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sat, 29 Aug 2026 23:29:16 +0500
Subject: [PATCH 04/14] Rename HtmxValues to HtmxFieldValues for clarity

---
 src/Ramstack.HtmxToolkit/AjaxContext.cs       |  4 +-
 .../{HtmxValues.cs => HtmxFieldValues.cs}     | 42 +++++++++----------
 ...ter.cs => HtmxFieldValuesJsonConverter.cs} |  8 ++--
 .../HtmxResponseTests.cs                      |  2 +-
 4 files changed, 28 insertions(+), 28 deletions(-)
 rename src/Ramstack.HtmxToolkit/{HtmxValues.cs => HtmxFieldValues.cs} (81%)
 rename src/Ramstack.HtmxToolkit/{HtmxValuesJsonConverter.cs => HtmxFieldValuesJsonConverter.cs} (65%)

diff --git a/src/Ramstack.HtmxToolkit/AjaxContext.cs b/src/Ramstack.HtmxToolkit/AjaxContext.cs
index d800204..b173925 100644
--- a/src/Ramstack.HtmxToolkit/AjaxContext.cs
+++ b/src/Ramstack.HtmxToolkit/AjaxContext.cs
@@ -39,9 +39,9 @@ public sealed class AjaxContext
     public HtmxSwap? Swap { get; set; }
 
     /// <summary>
-    /// Gets or sets the values to submit with the request.
+    /// Gets or sets the form field values to submit with the request.
     /// </summary>
-    public IDictionary<string, HtmxValues>? Values { get; set; }
+    public IDictionary<string, HtmxFieldValues>? Values { get; set; }
 
     /// <summary>
     /// Gets or sets the headers to include with the request.
diff --git a/src/Ramstack.HtmxToolkit/HtmxValues.cs b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
similarity index 81%
rename from src/Ramstack.HtmxToolkit/HtmxValues.cs
rename to src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
index c8ac9ee..1192038 100644
--- a/src/Ramstack.HtmxToolkit/HtmxValues.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
@@ -5,14 +5,14 @@
 namespace Ramstack.HtmxToolkit;
 
 /// <summary>
-/// Represents one or more string values for an HTMX request parameter.
+/// Represents one or more values for a form field submitted with an HTMX request.
 /// </summary>
 /// <remarks>
 /// A single value can be assigned from a string. Multiple values can be specified with a collection expression.
 /// </remarks>
-[CollectionBuilder(typeof(HtmxValues), nameof(Create))]
-[JsonConverter(typeof(HtmxValuesJsonConverter))]
-public readonly struct HtmxValues : IReadOnlyList<string>
+[JsonConverter(typeof(HtmxFieldValuesJsonConverter))]
+[CollectionBuilder(typeof(HtmxFieldValues), nameof(Create))]
+public readonly struct HtmxFieldValues : IReadOnlyList<string>
 {
     private readonly object? _values;
 
@@ -64,14 +64,14 @@ public string this[int index]
     public object? Values => _values;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="HtmxValues"/> structure with a single value.
+    /// Initializes a new instance of the <see cref="HtmxFieldValues"/> structure with a single value.
     /// </summary>
     /// <param name="value">The value to store.</param>
-    public HtmxValues(string value) =>
+    public HtmxFieldValues(string value) =>
         _values = value;
 
     /// <summary>
-    /// Initializes a new instance of the <see cref="HtmxValues"/> structure with the specified values.
+    /// Initializes a new instance of the <see cref="HtmxFieldValues"/> structure with the specified values.
     /// </summary>
     /// <param name="values">
     /// The values to store, or <see langword="null"/> to create an empty instance.
@@ -79,38 +79,38 @@ public HtmxValues(string value) =>
     /// <remarks>
     /// The specified array is stored directly and is not copied.
     /// </remarks>
-    public HtmxValues(string[]? values) =>
+    public HtmxFieldValues(string[]? values) =>
         _values = values;
 
     /// <summary>
-    /// Creates an <see cref="HtmxValues"/> from the specified values.
+    /// Creates an <see cref="HtmxFieldValues"/> from the specified values.
     /// </summary>
     /// <param name="values">The values to include.</param>
     /// <returns>
-    /// An <see cref="HtmxValues"/> containing the specified values.
+    /// An <see cref="HtmxFieldValues"/> containing the specified values.
     /// </returns>
-    public static HtmxValues Create(ReadOnlySpan<string> values)
+    public static HtmxFieldValues Create(ReadOnlySpan<string> values)
     {
         return values.Length switch
         {
-            0 => new HtmxValues([]),
-            1 => new HtmxValues(values[0]),
-            _ => new HtmxValues(CreateArray(values))
+            0 => new HtmxFieldValues([]),
+            1 => new HtmxFieldValues(values[0]),
+            _ => new HtmxFieldValues(CreateArray(values))
         };
     }
 
     /// <summary>
-    /// Converts a string to an <see cref="HtmxValues"/>.
+    /// Converts a string to an <see cref="HtmxFieldValues"/>.
     /// </summary>
     /// <param name="value">The value to convert.</param>
-    public static implicit operator HtmxValues(string value) =>
+    public static implicit operator HtmxFieldValues(string value) =>
         new(value);
 
     /// <summary>
-    /// Converts an array of strings to an <see cref="HtmxValues"/>.
+    /// Converts an array of strings to an <see cref="HtmxFieldValues"/>.
     /// </summary>
     /// <param name="values">The values to convert.</param>
-    public static implicit operator HtmxValues(string[] values) =>
+    public static implicit operator HtmxFieldValues(string[] values) =>
         new(values);
 
     /// <summary>
@@ -157,7 +157,7 @@ private static string[] CreateArray(ReadOnlySpan<string> s) =>
     #region Inner type: Enumerator
 
     /// <summary>
-    /// Enumerates the strings represented by an <see cref="HtmxValues"/>.
+    /// Enumerates the strings represented by an <see cref="HtmxFieldValues"/>.
     /// </summary>
     public struct Enumerator : IEnumerator<string>
     {
@@ -188,10 +188,10 @@ private Enumerator(object? value)
         }
 
         /// <summary>
-        /// Initializes a new enumerator for the specified <see cref="HtmxValues"/>.
+        /// Initializes a new enumerator for the specified <see cref="HtmxFieldValues"/>.
         /// </summary>
         /// <param name="value">The value whose strings to enumerate.</param>
-        public Enumerator(HtmxValues value) : this(value._values)
+        public Enumerator(HtmxFieldValues value) : this(value._values)
         {
         }
 
diff --git a/src/Ramstack.HtmxToolkit/HtmxValuesJsonConverter.cs b/src/Ramstack.HtmxToolkit/HtmxFieldValuesJsonConverter.cs
similarity index 65%
rename from src/Ramstack.HtmxToolkit/HtmxValuesJsonConverter.cs
rename to src/Ramstack.HtmxToolkit/HtmxFieldValuesJsonConverter.cs
index fe0ace7..98cd0d1 100644
--- a/src/Ramstack.HtmxToolkit/HtmxValuesJsonConverter.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxFieldValuesJsonConverter.cs
@@ -5,16 +5,16 @@
 namespace Ramstack.HtmxToolkit;
 
 /// <summary>
-/// Represents a JSON converter for <see cref="HtmxValues"/>.
+/// Represents a JSON converter for <see cref="HtmxFieldValues"/>.
 /// </summary>
-internal sealed class HtmxValuesJsonConverter : JsonConverter<HtmxValues>
+internal sealed class HtmxFieldValuesJsonConverter : JsonConverter<HtmxFieldValues>
 {
     /// <inheritdoc />
-    public override HtmxValues Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
+    public override HtmxFieldValues Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
         throw new NotSupportedException();
 
     /// <inheritdoc />
-    public override void Write(Utf8JsonWriter writer, HtmxValues value, JsonSerializerOptions options)
+    public override void Write(Utf8JsonWriter writer, HtmxFieldValues value, JsonSerializerOptions options)
     {
         var values = value.Values;
         switch (values)
diff --git a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
index e5f9329..df3541d 100644
--- a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
+++ b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
@@ -57,7 +57,7 @@ public void Location_WithContext_SerializesHandlerValuesAndHeaders()
         context.Response.Htmx(r => r.Location("/bar", new AjaxContext
         {
             Handler = "handleResponse",
-            Values = new Dictionary<string, HtmxValues>
+            Values = new Dictionary<string, HtmxFieldValues>
             {
                 ["id"] = "42",
                 ["tags"] = ["dotnet", "web"]

From c6d1ed8eb3413ca5636b28e5518e227e2c2c5256 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sat, 29 Aug 2026 23:47:42 +0500
Subject: [PATCH 05/14] Clean up

---
 src/Ramstack.HtmxToolkit/HtmxFieldValues.cs | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
index 1192038..281f8f1 100644
--- a/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
@@ -57,25 +57,19 @@ public string this[int index]
     /// <summary>
     /// Gets the underlying value representation.
     /// </summary>
-    /// <value>
-    /// <see langword="null"/> when the collection is empty, a <see cref="string"/>
-    /// when it contains one value, or a string array when it contains multiple values.
-    /// </value>
     public object? Values => _values;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="HtmxFieldValues"/> structure with a single value.
     /// </summary>
     /// <param name="value">The value to store.</param>
-    public HtmxFieldValues(string value) =>
+    public HtmxFieldValues(string? value) =>
         _values = value;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="HtmxFieldValues"/> structure with the specified values.
     /// </summary>
-    /// <param name="values">
-    /// The values to store, or <see langword="null"/> to create an empty instance.
-    /// </param>
+    /// <param name="values">The values to store.</param>
     /// <remarks>
     /// The specified array is stored directly and is not copied.
     /// </remarks>

From 2115123079ecf39b9d8f97e5aaebcac76d2cbbc3 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sun, 30 Aug 2026 00:00:49 +0500
Subject: [PATCH 06/14] Add tests

---
 .../HtmxFieldValuesTests.cs                   | 241 ++++++++++++++++++
 1 file changed, 241 insertions(+)
 create mode 100644 tests/Ramstack.HtmxToolkit.Tests/HtmxFieldValuesTests.cs

diff --git a/tests/Ramstack.HtmxToolkit.Tests/HtmxFieldValuesTests.cs b/tests/Ramstack.HtmxToolkit.Tests/HtmxFieldValuesTests.cs
new file mode 100644
index 0000000..de8bc12
--- /dev/null
+++ b/tests/Ramstack.HtmxToolkit.Tests/HtmxFieldValuesTests.cs
@@ -0,0 +1,241 @@
+using System.Collections;
+using System.Text.Json;
+
+namespace Ramstack.HtmxToolkit.Tests;
+
+[TestFixture]
+public class HtmxFieldValuesTests
+{
+    [Test]
+    public void DefaultValue_IsEmpty()
+    {
+        var value = default(HtmxFieldValues);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(value.Count, Is.Zero);
+            Assert.That(value.Values, Is.Null);
+            Assert.That(value, Is.Empty);
+            Assert.That(value, Is.EquivalentTo(Array.Empty<string>()));
+        });
+    }
+
+    [Test]
+    public void Enumeration_DefaultValue_ForeachCompletesWithoutItems()
+    {
+        var values = default(HtmxFieldValues);
+        var list = new List<string>();
+
+        Assert.DoesNotThrow(() =>
+        {
+            foreach (var item in values)
+                list.Add(item);
+        });
+
+        Assert.That(list, Is.Empty);
+    }
+
+    [Test]
+    public void Constructor_SingleValue_UsesStringRepresentation()
+    {
+        var values = new HtmxFieldValues("value");
+        Assert.That(values, Is.EqualTo(["value"]));
+    }
+
+    [Test]
+    public void Constructor_Array_StoresArrayWithoutCopying()
+    {
+        var source = new[] { "first", "second" };
+        var values = new HtmxFieldValues(source);
+
+        source[1] = "changed";
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(values.Count, Is.EqualTo(2));
+            Assert.That(values.Values, Is.SameAs(source));
+            Assert.That(values[1], Is.EqualTo("changed"));
+            Assert.That(values, Is.EqualTo(source));
+        });
+    }
+
+    [Test]
+    public void Constructor_EmptyArray_PreservesArrayRepresentation()
+    {
+        var source = new string [0];
+        var values = new HtmxFieldValues(source);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(values.Count, Is.Zero);
+            Assert.That(values.Values, Is.SameAs(source));
+            Assert.That(values, Is.Empty);
+        });
+    }
+
+    [Test]
+    public void Constructor_NullArray_IsEmpty()
+    {
+        var values = new HtmxFieldValues((string[]?)null);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(values.Count, Is.Zero);
+            Assert.That(values.Values, Is.Null);
+            Assert.That(values, Is.Empty);
+        });
+    }
+
+    [Test]
+    public void Create_EmptySpan_ReturnsEmptyArrayRepresentation()
+    {
+        var values = HtmxFieldValues.Create(ReadOnlySpan<string>.Empty);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(values.Count, Is.Zero);
+            Assert.That(values.Values, Is.TypeOf<string[]>());
+            Assert.That(values.Values, Is.Empty);
+        });
+    }
+
+    [Test]
+    public void Create_SingleValue_UsesStringRepresentation()
+    {
+        var source = new[] { "single" };
+        var values = HtmxFieldValues.Create(source);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(values.Count, Is.EqualTo(1));
+            Assert.That(values.Values, Is.TypeOf<string>());
+            Assert.That(values[0], Is.EqualTo("single"));
+            Assert.That(values, Is.EqualTo(["single"]));
+        });
+    }
+
+    [Test]
+    public void Create_MultipleValues_CopiesTheSpan()
+    {
+        var source = new[] { "before", "first", "second", "after" };
+        var values = HtmxFieldValues.Create(source.AsSpan());
+        source[1] = "changed";
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(values.Count, Is.EqualTo(4));
+            Assert.That(values.Values, Is.TypeOf<string[]>());
+            Assert.That(values.Values, Is.Not.SameAs(source));
+            Assert.That(values, Is.EqualTo(["before", "first", "second", "after"]));
+        });
+    }
+
+    [Test]
+    public void CollectionExpressions_SelectCompactRepresentations()
+    {
+        HtmxFieldValues empty = [];
+        HtmxFieldValues single = ["one"];
+        HtmxFieldValues multiple = ["one", "two"];
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(empty.Values, Is.TypeOf<string[]>());
+            Assert.That(empty, Is.Empty);
+            Assert.That(single.Values, Is.TypeOf<string>());
+            Assert.That(single, Is.EqualTo(["one"]));
+            Assert.That(multiple.Values, Is.TypeOf<string[]>());
+            Assert.That(multiple, Is.EqualTo(["one", "two"]));
+        });
+    }
+
+    [Test]
+    public void ImplicitConversions_PreserveSourceRepresentations()
+    {
+        var array = new[] { "one", "two" };
+
+        HtmxFieldValues single = "value";
+        HtmxFieldValues multiple = array;
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(single.Values, Is.EqualTo("value"));
+            Assert.That(single, Is.EqualTo(["value"]));
+            Assert.That(multiple.Values, Is.SameAs(array));
+            Assert.That(multiple, Is.EqualTo(array));
+        });
+    }
+
+    [TestCase(-1)]
+    [TestCase(1)]
+    public void Indexer_SingleValueInvalidIndex_ThrowsException(int index)
+    {
+        var values = new HtmxFieldValues("value");
+
+        Assert.Throws<IndexOutOfRangeException>(() => _ = values[index]);
+    }
+
+    [TestCase(-1)]
+    [TestCase(2)]
+    public void Indexer_ArrayInvalidIndex_ThrowsException(int index)
+    {
+        var values = new HtmxFieldValues(["one", "two"]);
+
+        Assert.Throws<IndexOutOfRangeException>(() => _ = values[index]);
+    }
+
+    [Test]
+    public void Enumeration_GenericAndNonGenericInterfaces_ReturnValuesInOrder()
+    {
+        HtmxFieldValues values = ["first", "second", "third"];
+
+        // ReSharper disable once RedundantCast
+        var generic = ((IEnumerable<string>)values).ToArray();
+
+        // ReSharper disable once RedundantCast
+        var nonGeneric = ((IEnumerable)values).Cast<string>().ToArray();
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(generic, Is.EqualTo(["first", "second", "third"]));
+            Assert.That(nonGeneric, Is.EqualTo(generic));
+        });
+    }
+
+    [Test]
+    public void Enumerator_AfterSequenceEnds_RemainsCompleted()
+    {
+        var enumerator = new HtmxFieldValues.Enumerator(["first", "second"]);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(enumerator.MoveNext(), Is.True);
+            Assert.That(enumerator.Current, Is.EqualTo("first"));
+            Assert.That(enumerator.MoveNext(), Is.True);
+            Assert.That(enumerator.Current, Is.EqualTo("second"));
+            Assert.That(enumerator.MoveNext(), Is.False);
+            Assert.That(enumerator.MoveNext(), Is.False);
+        });
+    }
+
+    [Test]
+    public void Enumerator_Reset_ThrowsNotSupportedException()
+    {
+        IEnumerator enumerator = new HtmxFieldValues.Enumerator("value");
+
+        Assert.Throws<NotSupportedException>(enumerator.Reset);
+    }
+
+    [Test]
+    public void JsonSerialization_EmptySingleAndMultipleValues_UsesExpectedShapes()
+    {
+        HtmxFieldValues single = "a\"b";
+        HtmxFieldValues multiple = ["first", "second"];
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(JsonSerializer.Serialize(default(HtmxFieldValues)), Is.EqualTo("[]"));
+            Assert.That(JsonSerializer.Serialize(single), Is.EqualTo("\"a\\u0022b\""));
+            Assert.That(JsonSerializer.Serialize(multiple), Is.EqualTo("[\"first\",\"second\"]"));
+        });
+    }
+}

From 6381304f07e5bdadd784153fa5b91636d486aa18 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sun, 30 Aug 2026 00:22:28 +0500
Subject: [PATCH 07/14] Rename AjaxContext to HtmxLocationOptions

---
 .../{AjaxContext.cs => HtmxLocationOptions.cs}       |  4 ++--
 ...s => HtmxLocationOptionsJsonSerializerContext.cs} | 10 +++++-----
 src/Ramstack.HtmxToolkit/HtmxResponse.cs             | 12 ++++++------
 .../Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs  | 12 ++++++------
 4 files changed, 19 insertions(+), 19 deletions(-)
 rename src/Ramstack.HtmxToolkit/{AjaxContext.cs => HtmxLocationOptions.cs} (94%)
 rename src/Ramstack.HtmxToolkit/{AjaxContextJsonSerializerContext.cs => HtmxLocationOptionsJsonSerializerContext.cs} (60%)

diff --git a/src/Ramstack.HtmxToolkit/AjaxContext.cs b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
similarity index 94%
rename from src/Ramstack.HtmxToolkit/AjaxContext.cs
rename to src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
index b173925..3505461 100644
--- a/src/Ramstack.HtmxToolkit/AjaxContext.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
@@ -3,9 +3,9 @@
 namespace Ramstack.HtmxToolkit;
 
 /// <summary>
-/// Represents the context for an AJAX request.
+/// Represents the options for an <c>HX-Location</c> request.
 /// </summary>
-public sealed class AjaxContext
+public sealed class HtmxLocationOptions
 {
     /// <summary>
     /// Gets or sets the path used for the AJAX request.
diff --git a/src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs b/src/Ramstack.HtmxToolkit/HtmxLocationOptionsJsonSerializerContext.cs
similarity index 60%
rename from src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs
rename to src/Ramstack.HtmxToolkit/HtmxLocationOptionsJsonSerializerContext.cs
index b8ff5e1..90e5059 100644
--- a/src/Ramstack.HtmxToolkit/AjaxContextJsonSerializerContext.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxLocationOptionsJsonSerializerContext.cs
@@ -5,22 +5,22 @@
 namespace Ramstack.HtmxToolkit;
 
 /// <summary>
-/// Provides source-generated JSON serialization metadata for AJAX context data.
+/// Provides source-generated JSON serialization metadata for <c>HX-Location</c> options.
 /// </summary>
 [JsonSourceGenerationOptions(
     WriteIndented = false,
     PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
     DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
     GenerationMode = JsonSourceGenerationMode.Default)]
-[JsonSerializable(typeof(AjaxContext))]
-internal partial class AjaxContextJsonSerializerContext : JsonSerializerContext
+[JsonSerializable(typeof(HtmxLocationOptions))]
+internal partial class HtmxLocationOptionsJsonSerializerContext : JsonSerializerContext
 {
     /// <summary>
     /// Initializes the default serializer context with HTML-safe Unicode encoding.
     /// </summary>
-    static AjaxContextJsonSerializerContext()
+    static HtmxLocationOptionsJsonSerializerContext()
     {
         JsonOptions.ConfigureHtmlSafeUnicode(s_defaultOptions);
-        s_defaultContext = new AjaxContextJsonSerializerContext(s_defaultOptions);
+        s_defaultContext = new HtmxLocationOptionsJsonSerializerContext(s_defaultOptions);
     }
 }
diff --git a/src/Ramstack.HtmxToolkit/HtmxResponse.cs b/src/Ramstack.HtmxToolkit/HtmxResponse.cs
index 26293a5..dfa1c8d 100644
--- a/src/Ramstack.HtmxToolkit/HtmxResponse.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxResponse.cs
@@ -50,19 +50,19 @@ public HtmxResponse Location(string value) =>
     /// Sets the <c>HX-Location</c> header to a client-side redirect that does not do a full page reload.
     /// </summary>
     /// <param name="path">The path of the request.</param>
-    /// <param name="context">The AJAX context of the request.</param>
+    /// <param name="options">The options for the <c>HX-Location</c> request.</param>
     /// <returns>
     /// The current <see cref="HtmxResponse"/> instance.
     /// </returns>
-    public HtmxResponse Location(string path, AjaxContext context)
+    public HtmxResponse Location(string path, HtmxLocationOptions options)
     {
-        return LocationImpl(this, path, context);
+        return LocationImpl(this, path, options);
 
-        static HtmxResponse LocationImpl(HtmxResponse response, string path, AjaxContext context)
+        static HtmxResponse LocationImpl(HtmxResponse response, string path, HtmxLocationOptions options)
         {
-            context.Path = path;
+            options.Path = path;
 
-            var value = JsonSerializer.Serialize(context, AjaxContextJsonSerializerContext.Default.AjaxContext);
+            var value = JsonSerializer.Serialize(options, HtmxLocationOptionsJsonSerializerContext.Default.HtmxLocationOptions);
             return SetHeader(response, HtmxResponseHeaderNames.Location, value);
         }
     }
diff --git a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
index df3541d..8545b7d 100644
--- a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
+++ b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
@@ -13,10 +13,10 @@ public void Location_SetsHeader()
     }
 
     [Test]
-    public void Location_WithContext_SerializesJson()
+    public void Location_WithOptions_SerializesJson()
     {
         var context = TestHelper.CreateHtmxRequestContext();
-        context.Response.Htmx(r => r.Location("/bar", new AjaxContext
+        context.Response.Htmx(r => r.Location("/bar", new HtmxLocationOptions
         {
             Source = "button",
             Event = "click",
@@ -37,10 +37,10 @@ public void Location_WithContext_SerializesJson()
     }
 
     [Test]
-    public void Location_WithContext_OmitsNullProperties()
+    public void Location_WithOptions_OmitsNullProperties()
     {
         var context = TestHelper.CreateHtmxRequestContext();
-        context.Response.Htmx(r => r.Location("/bar", new AjaxContext()));
+        context.Response.Htmx(r => r.Location("/bar", new HtmxLocationOptions()));
 
         var header = context.Response.Headers[HtmxResponseHeaderNames.Location].ToString();
         var json = JsonHelper.ParseJson(header);
@@ -51,10 +51,10 @@ public void Location_WithContext_OmitsNullProperties()
     }
 
     [Test]
-    public void Location_WithContext_SerializesHandlerValuesAndHeaders()
+    public void Location_WithOptions_SerializesHandlerValuesAndHeaders()
     {
         var context = TestHelper.CreateHtmxRequestContext();
-        context.Response.Htmx(r => r.Location("/bar", new AjaxContext
+        context.Response.Htmx(r => r.Location("/bar", new HtmxLocationOptions
         {
             Handler = "handleResponse",
             Values = new Dictionary<string, HtmxFieldValues>

From 22cc2eb89d1be5be893312bfc2cc959ac8f00fa0 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sun, 30 Aug 2026 00:38:53 +0500
Subject: [PATCH 08/14] Add missing HX-Location options

---
 .../HtmxLocationOptions.cs                    | 16 ++++++++++++++++
 .../HtmxResponseTests.cs                      | 19 +++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
index 3505461..b4d20be 100644
--- a/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
@@ -53,4 +53,20 @@ public sealed class HtmxLocationOptions
     /// Gets or sets a selector used to filter the content to swap from the response.
     /// </summary>
     public string? Select { get; set; }
+
+    /// <summary>
+    /// Gets or sets a selector used to select content for out-of-band swaps from the response.
+    /// </summary>
+    public string? SelectOOB { get; set; }
+
+    /// <summary>
+    /// Gets or sets the path to push into the browser history.
+    /// Set to <c>false</c> to prevent the URL from being pushed.
+    /// </summary>
+    public string? Push { get; set; }
+
+    /// <summary>
+    /// Gets or sets the path that replaces the current URL in the browser history.
+    /// </summary>
+    public string? Replace { get; set; }
 }
diff --git a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
index 8545b7d..34e9e63 100644
--- a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
+++ b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
@@ -77,6 +77,25 @@ public void Location_WithOptions_SerializesHandlerValuesAndHeaders()
         Assert.That(json["headers"].GetProperty("X-Test").GetString(), Is.EqualTo("abc"));
     }
 
+    [Test]
+    public void Location_WithOptions_SerializesHistoryAndOutOfBandOptions()
+    {
+        var context = TestHelper.CreateHtmxRequestContext();
+        context.Response.Htmx(r => r.Location("/bar", new HtmxLocationOptions
+        {
+            SelectOOB = "#alerts",
+            Push = "false",
+            Replace = "/replaced"
+        }));
+
+        var header = context.Response.Headers[HtmxResponseHeaderNames.Location].ToString();
+        var json = JsonHelper.ParseJson(header);
+
+        Assert.That(json["selectOOB"].GetString(), Is.EqualTo("#alerts"));
+        Assert.That(json["push"].GetString(), Is.EqualTo("false"));
+        Assert.That(json["replace"].GetString(), Is.EqualTo("/replaced"));
+    }
+
     [Test]
     public void PushUrl_SetsHeader()
     {

From 7037b95881baaf38d91810c793f0b9d0e2631aa4 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sun, 30 Aug 2026 00:42:28 +0500
Subject: [PATCH 09/14] Add HTMX version support notes to HtmxLocationOptions
 properties

---
 src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
index b4d20be..dc076d5 100644
--- a/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
@@ -10,11 +10,13 @@ public sealed class HtmxLocationOptions
     /// <summary>
     /// Gets or sets the path used for the AJAX request.
     /// </summary>
+    /// <remarks>Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x.</remarks>
     public string? Path { get; internal set; }
 
     /// <summary>
     /// Gets or sets the source element that initiated the request.
     /// </summary>
+    /// <remarks>Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x.</remarks>
     public string? Source { get; set; }
 
     /// <summary>
@@ -30,43 +32,51 @@ public sealed class HtmxLocationOptions
     /// <summary>
     /// Gets or sets the target element into which the response will be swapped.
     /// </summary>
+    /// <remarks>Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x.</remarks>
     public string? Target { get; set; }
 
     /// <summary>
     /// Gets or sets how the response will be swapped relative to the target element.
     /// </summary>
+    /// <remarks>Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x.</remarks>
     [JsonConverter(typeof(HtmxSwapJsonConverter))]
     public HtmxSwap? Swap { get; set; }
 
     /// <summary>
     /// Gets or sets the form field values to submit with the request.
     /// </summary>
+    /// <remarks>Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x.</remarks>
     public IDictionary<string, HtmxFieldValues>? Values { get; set; }
 
     /// <summary>
     /// Gets or sets the headers to include with the request.
     /// Header values must be strings; complex data should be passed as a pre-serialized JSON string.
     /// </summary>
+    /// <remarks>Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x.</remarks>
     public IDictionary<string, string>? Headers { get; set; }
 
     /// <summary>
     /// Gets or sets a selector used to filter the content to swap from the response.
     /// </summary>
+    /// <remarks>Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x.</remarks>
     public string? Select { get; set; }
 
     /// <summary>
     /// Gets or sets a selector used to select content for out-of-band swaps from the response.
     /// </summary>
+    /// <remarks>Supported in HTMX 2.x and HTMX 4.x.</remarks>
     public string? SelectOOB { get; set; }
 
     /// <summary>
     /// Gets or sets the path to push into the browser history.
     /// Set to <c>false</c> to prevent the URL from being pushed.
     /// </summary>
+    /// <remarks>Supported in HTMX 2.x and HTMX 4.x.</remarks>
     public string? Push { get; set; }
 
     /// <summary>
     /// Gets or sets the path that replaces the current URL in the browser history.
     /// </summary>
+    /// <remarks>Supported in HTMX 2.x and HTMX 4.x.</remarks>
     public string? Replace { get; set; }
 }

From 21cc719e0aeedd8eb205535d3a99ac4372405d8e Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sun, 30 Aug 2026 01:26:36 +0500
Subject: [PATCH 10/14] Remove non-serializable HX-Location options

Remove Event and Handler from HtmxLocationOptions. HX-Location is
transported as JSON, while htmx.ajax expects event to be a live browser
Event instance and handler to be a callable JavaScript function.

Serializing either value as a string cannot recreate the expected
runtime object. HTMX 1.x and 2.x invoke handler directly, while HTMX 4.x
no longer supports the handler option.
---
 src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs       | 10 ----------
 tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs |  6 +-----
 2 files changed, 1 insertion(+), 15 deletions(-)

diff --git a/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
index dc076d5..a01f6d7 100644
--- a/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
@@ -19,16 +19,6 @@ public sealed class HtmxLocationOptions
     /// <remarks>Supported in HTMX 1.9.x, HTMX 2.x, and HTMX 4.x.</remarks>
     public string? Source { get; set; }
 
-    /// <summary>
-    /// Gets or sets the event that triggered the request.
-    /// </summary>
-    public string? Event { get; set; }
-
-    /// <summary>
-    /// Gets or sets the name of the client-side callback function that will handle the response HTML.
-    /// </summary>
-    public string? Handler { get; set; }
-
     /// <summary>
     /// Gets or sets the target element into which the response will be swapped.
     /// </summary>
diff --git a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
index 34e9e63..aa8cece 100644
--- a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
+++ b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
@@ -19,7 +19,6 @@ public void Location_WithOptions_SerializesJson()
         context.Response.Htmx(r => r.Location("/bar", new HtmxLocationOptions
         {
             Source = "button",
-            Event = "click",
             Target = "#content",
             Swap = HtmxSwap.OuterHtml,
             Select = "#list"
@@ -30,7 +29,6 @@ public void Location_WithOptions_SerializesJson()
 
         Assert.That(json["path"].GetString(), Is.EqualTo("/bar"));
         Assert.That(json["source"].GetString(), Is.EqualTo("button"));
-        Assert.That(json["event"].GetString(), Is.EqualTo("click"));
         Assert.That(json["target"].GetString(), Is.EqualTo("#content"));
         Assert.That(json["swap"].GetString(), Is.EqualTo("outerHTML"));
         Assert.That(json["select"].GetString(), Is.EqualTo("#list"));
@@ -51,12 +49,11 @@ public void Location_WithOptions_OmitsNullProperties()
     }
 
     [Test]
-    public void Location_WithOptions_SerializesHandlerValuesAndHeaders()
+    public void Location_WithOptions_SerializesValuesAndHeaders()
     {
         var context = TestHelper.CreateHtmxRequestContext();
         context.Response.Htmx(r => r.Location("/bar", new HtmxLocationOptions
         {
-            Handler = "handleResponse",
             Values = new Dictionary<string, HtmxFieldValues>
             {
                 ["id"] = "42",
@@ -71,7 +68,6 @@ public void Location_WithOptions_SerializesHandlerValuesAndHeaders()
         var header = context.Response.Headers[HtmxResponseHeaderNames.Location].ToString();
         var json = JsonHelper.ParseJson(header);
 
-        Assert.That(json["handler"].GetString(), Is.EqualTo("handleResponse"));
         Assert.That(json["values"].GetProperty("id").GetString(), Is.EqualTo("42"));
         Assert.That(json["values"].GetProperty("tags").GetRawText(), Is.EqualTo("[\"dotnet\",\"web\"]"));
         Assert.That(json["headers"].GetProperty("X-Test").GetString(), Is.EqualTo("abc"));

From 90d224cfd4527d0a08c3ac4d24eb998e3ac52a24 Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sun, 30 Aug 2026 01:35:17 +0500
Subject: [PATCH 11/14] Fix accidental public exposure of
 HtmxFieldValues.Values

---
 src/Ramstack.HtmxToolkit/HtmxFieldValues.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
index 281f8f1..477379c 100644
--- a/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
@@ -57,7 +57,7 @@ public string this[int index]
     /// <summary>
     /// Gets the underlying value representation.
     /// </summary>
-    public object? Values => _values;
+    internal object? Values => _values;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="HtmxFieldValues"/> structure with a single value.

From a4ddcfb05ee694568e20568491824c198917954e Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sun, 30 Aug 2026 01:43:58 +0500
Subject: [PATCH 12/14] Allow nullable inputs in HtmxFieldValues implicit
 conversions

---
 src/Ramstack.HtmxToolkit/HtmxFieldValues.cs   | 12 +++----
 .../HtmxFieldValuesTests.cs                   | 33 ++++++++++++++++---
 2 files changed, 35 insertions(+), 10 deletions(-)

diff --git a/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
index 477379c..fc42b3e 100644
--- a/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
@@ -62,14 +62,14 @@ public string this[int index]
     /// <summary>
     /// Initializes a new instance of the <see cref="HtmxFieldValues"/> structure with a single value.
     /// </summary>
-    /// <param name="value">The value to store.</param>
+    /// <param name="value">The value to store, or <see langword="null"/> to represent no values.</param>
     public HtmxFieldValues(string? value) =>
         _values = value;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="HtmxFieldValues"/> structure with the specified values.
     /// </summary>
-    /// <param name="values">The values to store.</param>
+    /// <param name="values">The values to store, or <see langword="null"/> to represent no values.</param>
     /// <remarks>
     /// The specified array is stored directly and is not copied.
     /// </remarks>
@@ -96,15 +96,15 @@ public static HtmxFieldValues Create(ReadOnlySpan<string> values)
     /// <summary>
     /// Converts a string to an <see cref="HtmxFieldValues"/>.
     /// </summary>
-    /// <param name="value">The value to convert.</param>
-    public static implicit operator HtmxFieldValues(string value) =>
+    /// <param name="value">The value to convert, or <see langword="null"/> to represent no values.</param>
+    public static implicit operator HtmxFieldValues(string? value) =>
         new(value);
 
     /// <summary>
     /// Converts an array of strings to an <see cref="HtmxFieldValues"/>.
     /// </summary>
-    /// <param name="values">The values to convert.</param>
-    public static implicit operator HtmxFieldValues(string[] values) =>
+    /// <param name="values">The values to convert, or <see langword="null"/> to represent no values.</param>
+    public static implicit operator HtmxFieldValues(string[]? values) =>
         new(values);
 
     /// <summary>
diff --git a/tests/Ramstack.HtmxToolkit.Tests/HtmxFieldValuesTests.cs b/tests/Ramstack.HtmxToolkit.Tests/HtmxFieldValuesTests.cs
index de8bc12..caee480 100644
--- a/tests/Ramstack.HtmxToolkit.Tests/HtmxFieldValuesTests.cs
+++ b/tests/Ramstack.HtmxToolkit.Tests/HtmxFieldValuesTests.cs
@@ -76,13 +76,19 @@ public void Constructor_EmptyArray_PreservesArrayRepresentation()
     [Test]
     public void Constructor_NullArray_IsEmpty()
     {
-        var values = new HtmxFieldValues((string[]?)null);
+        var single = new HtmxFieldValues((string?)null);
+        var multiple = new HtmxFieldValues((string[]?)null);
 
         Assert.Multiple(() =>
         {
-            Assert.That(values.Count, Is.Zero);
-            Assert.That(values.Values, Is.Null);
-            Assert.That(values, Is.Empty);
+            Assert.That(single.Count, Is.Zero);
+            Assert.That(multiple.Count, Is.Zero);
+
+            Assert.That(single.Values, Is.Null);
+            Assert.That(multiple.Values, Is.Null);
+
+            Assert.That(single, Is.Empty);
+            Assert.That(multiple, Is.Empty);
         });
     }
 
@@ -165,6 +171,25 @@ public void ImplicitConversions_PreserveSourceRepresentations()
         });
     }
 
+    [Test]
+    public void ImplicitConversions_NullSources_AreEmpty()
+    {
+        HtmxFieldValues single = (string?)null;
+        HtmxFieldValues multiple = (string[]?)null;
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(single.Count, Is.Zero);
+            Assert.That(multiple.Count, Is.Zero);
+
+            Assert.That(single.Values, Is.Null);
+            Assert.That(multiple.Values, Is.Null);
+
+            Assert.That(single, Is.Empty);
+            Assert.That(multiple, Is.Empty);
+        });
+    }
+
     [TestCase(-1)]
     [TestCase(1)]
     public void Indexer_SingleValueInvalidIndex_ThrowsException(int index)

From 4f4a072835725e3aa2b64e3884e5defd5f889acc Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sun, 30 Aug 2026 02:00:08 +0500
Subject: [PATCH 13/14] Clean up

---
 src/Ramstack.HtmxToolkit/HtmxFieldValues.cs | 19 +++++--------------
 1 file changed, 5 insertions(+), 14 deletions(-)

diff --git a/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
index fc42b3e..6e908c2 100644
--- a/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxFieldValues.cs
@@ -163,32 +163,23 @@ public struct Enumerator : IEnumerator<string>
         public readonly string Current => _current!;
 
         /// <summary>
-        /// Initializes a new enumerator for the specified underlying value representation.
+        /// Initializes a new enumerator for the specified <see cref="HtmxFieldValues"/>.
         /// </summary>
-        /// <param name="value">A single string, an array of strings,
-        /// or <see langword="null"/> for an empty sequence.</param>
-        private Enumerator(object? value)
+        /// <param name="value">The value whose strings to enumerate.</param>
+        public Enumerator(HtmxFieldValues value)
         {
-            if (value is string s)
+            if (value.Values is string s)
             {
                 (_values, _current) = (null, s);
             }
             else
             {
-                (_values, _current) = (Unsafe.As<string[]?>(value), null);
+                (_values, _current) = (Unsafe.As<string[]?>(value.Values), null);
             }
 
             _index = 0;
         }
 
-        /// <summary>
-        /// Initializes a new enumerator for the specified <see cref="HtmxFieldValues"/>.
-        /// </summary>
-        /// <param name="value">The value whose strings to enumerate.</param>
-        public Enumerator(HtmxFieldValues value) : this(value._values)
-        {
-        }
-
         /// <inheritdoc />
         public bool MoveNext()
         {

From ab020c9eb8878d4dfa930022d5c606910d27f61d Mon Sep 17 00:00:00 2001
From: rameel <rameel-b@hotmail.com>
Date: Sun, 30 Aug 2026 02:04:56 +0500
Subject: [PATCH 14/14] Rename SelectOOB to follow .NET naming conventions

---
 src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs       | 3 ++-
 tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
index a01f6d7..7d96aad 100644
--- a/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
+++ b/src/Ramstack.HtmxToolkit/HtmxLocationOptions.cs
@@ -55,7 +55,8 @@ public sealed class HtmxLocationOptions
     /// Gets or sets a selector used to select content for out-of-band swaps from the response.
     /// </summary>
     /// <remarks>Supported in HTMX 2.x and HTMX 4.x.</remarks>
-    public string? SelectOOB { get; set; }
+    [JsonPropertyName("selectOOB")]
+    public string? SelectOob { get; set; }
 
     /// <summary>
     /// Gets or sets the path to push into the browser history.
diff --git a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
index aa8cece..40860b6 100644
--- a/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
+++ b/tests/Ramstack.HtmxToolkit.Tests/HtmxResponseTests.cs
@@ -79,7 +79,7 @@ public void Location_WithOptions_SerializesHistoryAndOutOfBandOptions()
         var context = TestHelper.CreateHtmxRequestContext();
         context.Response.Htmx(r => r.Location("/bar", new HtmxLocationOptions
         {
-            SelectOOB = "#alerts",
+            SelectOob = "#alerts",
             Push = "false",
             Replace = "/replaced"
         }));