config: expose collection options as read-only lists

docs/articles/migrate-to-v2.md

@@ -116,7 +116,7 @@ on `HtmxV1Config` or `HtmxV2Config`. The exceptions are:
 | `include-antiforgery-token`   | `HtmxToolkitOptions.IncludeAntiforgeryToken`, now `true` by default; see the next section                          |
 | `use-template-fragments`      | `HtmxV1Config.UseTemplateFragments` only; HTMX 2.x always parses responses with templates                          |
 | `trigger-specs-cache`         | `TriggerSpecsCacheEnabled` (`bool?`)                                                                               |
-| `methods-that-use-url-params` | `MethodsThatUseUrlParams` (`HttpVerb[]` instead of `string[]`)                                                     |
+| `methods-that-use-url-params` | `MethodsThatUseUrlParams` (`IReadOnlyList<HttpVerb>` instead of `string[]`)                                        |
 | `ws-reconnect-delay`          | Removed: HTMX accepts only a function or the default `"full-jitter"`, and a function cannot be passed through JSON |
 
 For every property, see [HTMX 1.9.x](configuration-v1.md), [HTMX 2.x](configuration-v2.md),

src/Ramstack.HtmxToolkit/Configuration/HtmxConfig.cs

@@ -9,7 +9,8 @@ namespace Ramstack.HtmxToolkit.Configuration;
 /// </summary>
 /// <remarks>
 /// Configuration JSON is cached until a configuration property is assigned.
-/// Changes made in place to arrays, collections, or their items do not invalidate the cache;
+/// Collection properties are read-only lists, so replace a collection by assigning the property.
+/// Changes made in place to an assigned collection or its items do not invalidate the cache;
 /// reassign the containing property after making such changes.
 /// </remarks>
 public abstract class HtmxConfig

src/Ramstack.HtmxToolkit/Configuration/HtmxV1Config.cs

@@ -174,7 +174,7 @@ public string? InlineScriptNonce
     /// Gets or sets the attributes to settle during the settling phase.
     /// The HTMX default is <c>["class", "style", "width", "height"]</c>.
     /// </summary>
-    public string[]? AttributesToSettle
+    public IReadOnlyList<string>? AttributesToSettle
     {
         get;
         set => SetField(ref field, value);
@@ -288,8 +288,8 @@ public bool? GlobalViewTransitions
     /// Gets or sets the HTTP methods that use URL parameters.
     /// The HTMX default is <c>["get"]</c>.
     /// </summary>
-    [JsonConverter(typeof(HttpVerbArrayJsonConverter))]
-    public HttpVerb[]? MethodsThatUseUrlParams
+    [JsonConverter(typeof(HttpVerbListJsonConverter))]
+    public IReadOnlyList<HttpVerb>? MethodsThatUseUrlParams
     {
         get;
         set => SetField(ref field, value);

src/Ramstack.HtmxToolkit/Configuration/HtmxV2Config.cs

@@ -184,7 +184,7 @@ public string? InlineStyleNonce
     /// Gets or sets the attributes to settle during the settling phase.
     /// The HTMX default is <c>["class", "style", "width", "height"]</c>.
     /// </summary>
-    public string[]? AttributesToSettle
+    public IReadOnlyList<string>? AttributesToSettle
     {
         get;
         set => SetField(ref field, value);
@@ -300,8 +300,8 @@ public bool? GlobalViewTransitions
     /// Gets or sets the HTTP methods that use URL parameters.
     /// The HTMX default is <c>["get", "delete"]</c>.
     /// </summary>
-    [JsonConverter(typeof(HttpVerbArrayJsonConverter))]
-    public HttpVerb[]? MethodsThatUseUrlParams
+    [JsonConverter(typeof(HttpVerbListJsonConverter))]
+    public IReadOnlyList<HttpVerb>? MethodsThatUseUrlParams
     {
         get;
         set => SetField(ref field, value);
@@ -344,7 +344,7 @@ public bool? TriggerSpecsCacheEnabled
     /// The HTMX default is <c>[{ code: "204", swap: false }, { code: "[23]..", swap: true },
     /// { code: "[45]..", swap: false, error: true }]</c>.
     /// </summary>
-    public IList<ResponseHandlingConfig>? ResponseHandling
+    public IReadOnlyList<ResponseHandlingConfig>? ResponseHandling
     {
         get;
         set => SetField(ref field, value);

src/Ramstack.HtmxToolkit/Configuration/HtmxV4Config.cs

@@ -197,7 +197,7 @@ public bool? Transitions
     /// Gets or sets the attribute name prefixes to preserve during morphing.
     /// The HTMX default is <c>["data-htmx-powered"]</c>.
     /// </summary>
-    public string[]? MorphIgnore
+    public IReadOnlyList<string>? MorphIgnore
     {
         get;
         set => SetField(ref field, value);
@@ -241,7 +241,7 @@ public int? MorphScanLimit
     /// Although HTMX declares this option as a number array, it converts each entry to a string
     /// at runtime and supports wildcard patterns such as <c>"4xx"</c> and <c>"44x"</c>.
     /// </remarks>
-    public string[]? NoSwap
+    public IReadOnlyList<string>? NoSwap
     {
         get;
         set => SetField(ref field, value);

src/Ramstack.HtmxToolkit/Serialization/HttpVerbArrayJsonConverter.cs → src/Ramstack.HtmxToolkit/Serialization/HttpVerbListJsonConverter.cs

@@ -7,16 +7,16 @@
 namespace Ramstack.HtmxToolkit.Serialization;
 
 /// <summary>
-/// Represents a <see cref="JsonConverter{T}" /> for arrays of <see cref="HttpVerb" /> values.
+/// Represents a <see cref="JsonConverter{T}" /> for lists of <see cref="HttpVerb" /> values.
 /// </summary>
-internal sealed class HttpVerbArrayJsonConverter : JsonConverter<HttpVerb[]>
+internal sealed class HttpVerbListJsonConverter : JsonConverter<IReadOnlyList<HttpVerb>>
 {
     /// <inheritdoc />
-    public override HttpVerb[] Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
+    public override IReadOnlyList<HttpVerb> Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
         throw new NotSupportedException();
 
     /// <inheritdoc />
-    public override void Write(Utf8JsonWriter writer, HttpVerb[] value, JsonSerializerOptions options)
+    public override void Write(Utf8JsonWriter writer, IReadOnlyList<HttpVerb> value, JsonSerializerOptions options)
     {
         // NOTE: value is never null here: null-valued properties are omitted
         // by JsonIgnoreCondition.WhenWritingNull before this converter is invoked.