Blazor API Review: Forms

Fixes: #12549

Author: Ryan Nowak

src/Components/Components/ref/Microsoft.AspNetCore.Components.netstandard2.0.cs

@@ -419,8 +419,10 @@ public event System.EventHandler<Microsoft.AspNetCore.Components.Forms.Validatio
         public Microsoft.AspNetCore.Components.Forms.FieldIdentifier Field(string fieldName) { throw null; }
         public System.Collections.Generic.IEnumerable<string> GetValidationMessages() { throw null; }
         public System.Collections.Generic.IEnumerable<string> GetValidationMessages(Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier) { throw null; }
+        public System.Collections.Generic.IEnumerable<string> GetValidationMessages(System.Linq.Expressions.Expression<System.Func<object>> accessor) { throw null; }
         public bool IsModified() { throw null; }
         public bool IsModified(in Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier) { throw null; }
+        public bool IsModified(System.Linq.Expressions.Expression<System.Func<object>> accessor) { throw null; }
         public void MarkAsUnmodified() { }
         public void MarkAsUnmodified(in Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier) { }
         public void NotifyFieldChanged(in Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier) { }
@@ -431,24 +433,20 @@ public static partial class EditContextDataAnnotationsExtensions
     {
         public static Microsoft.AspNetCore.Components.Forms.EditContext AddDataAnnotationsValidation(this Microsoft.AspNetCore.Components.Forms.EditContext editContext) { throw null; }
     }
-    public static partial class EditContextExpressionExtensions
+    public sealed partial class FieldChangedEventArgs : System.EventArgs
     {
-        public static System.Collections.Generic.IEnumerable<string> GetValidationMessages(this Microsoft.AspNetCore.Components.Forms.EditContext editContext, System.Linq.Expressions.Expression<System.Func<object>> accessor) { throw null; }
-        public static bool IsModified(this Microsoft.AspNetCore.Components.Forms.EditContext editContext, System.Linq.Expressions.Expression<System.Func<object>> accessor) { throw null; }
-    }
-    public sealed partial class FieldChangedEventArgs
-    {
-        internal FieldChangedEventArgs() { }
+        public FieldChangedEventArgs(in Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier) { }
         public Microsoft.AspNetCore.Components.Forms.FieldIdentifier FieldIdentifier { [System.Runtime.CompilerServices.CompilerGeneratedAttribute]get { throw null; } }
     }
     [System.Runtime.InteropServices.StructLayoutAttribute(System.Runtime.InteropServices.LayoutKind.Sequential)]
-    public readonly partial struct FieldIdentifier
+    public readonly partial struct FieldIdentifier : System.IEquatable<Microsoft.AspNetCore.Components.Forms.FieldIdentifier>
     {
         private readonly object _dummy;
         public FieldIdentifier(object model, string fieldName) { throw null; }
         public string FieldName { [System.Runtime.CompilerServices.CompilerGeneratedAttribute]get { throw null; } }
         public object Model { [System.Runtime.CompilerServices.CompilerGeneratedAttribute]get { throw null; } }
         public static Microsoft.AspNetCore.Components.Forms.FieldIdentifier Create<T>(System.Linq.Expressions.Expression<System.Func<T>> accessor) { throw null; }
+        public bool Equals(Microsoft.AspNetCore.Components.Forms.FieldIdentifier otherIdentifier) { throw null; }
         public override bool Equals(object obj) { throw null; }
         public override int GetHashCode() { throw null; }
     }
@@ -457,24 +455,23 @@ public sealed partial class ValidationMessageStore
         public ValidationMessageStore(Microsoft.AspNetCore.Components.Forms.EditContext editContext) { }
         public System.Collections.Generic.IEnumerable<string> this[Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier] { get { throw null; } }
         public System.Collections.Generic.IEnumerable<string> this[System.Linq.Expressions.Expression<System.Func<object>> accessor] { get { throw null; } }
+        public void Add(in Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier, System.Collections.Generic.IEnumerable<string> messages) { }
         public void Add(in Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier, string message) { }
-        public void AddRange(in Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier, System.Collections.Generic.IEnumerable<string> messages) { }
+        public void Add(System.Linq.Expressions.Expression<System.Func<object>> accessor, System.Collections.Generic.IEnumerable<string> messages) { }
+        public void Add(System.Linq.Expressions.Expression<System.Func<object>> accessor, string message) { }
         public void Clear() { }
         public void Clear(in Microsoft.AspNetCore.Components.Forms.FieldIdentifier fieldIdentifier) { }
+        public void Clear(System.Linq.Expressions.Expression<System.Func<object>> accessor) { }
     }
-    public static partial class ValidationMessageStoreExpressionExtensions
-    {
-        public static void Add(this Microsoft.AspNetCore.Components.Forms.ValidationMessageStore store, System.Linq.Expressions.Expression<System.Func<object>> accessor, string message) { }
-        public static void AddRange(this Microsoft.AspNetCore.Components.Forms.ValidationMessageStore store, System.Linq.Expressions.Expression<System.Func<object>> accessor, System.Collections.Generic.IEnumerable<string> messages) { }
-        public static void Clear(this Microsoft.AspNetCore.Components.Forms.ValidationMessageStore store, System.Linq.Expressions.Expression<System.Func<object>> accessor) { }
-    }
-    public sealed partial class ValidationRequestedEventArgs
+    public sealed partial class ValidationRequestedEventArgs : System.EventArgs
     {
-        internal ValidationRequestedEventArgs() { }
+        public static readonly new Microsoft.AspNetCore.Components.Forms.ValidationRequestedEventArgs Empty;
+        public ValidationRequestedEventArgs() { }
     }
-    public sealed partial class ValidationStateChangedEventArgs
+    public sealed partial class ValidationStateChangedEventArgs : System.EventArgs
     {
-        internal ValidationStateChangedEventArgs() { }
+        public static readonly new Microsoft.AspNetCore.Components.Forms.ValidationStateChangedEventArgs Empty;
+        public ValidationStateChangedEventArgs() { }
     }
 }
 namespace Microsoft.AspNetCore.Components.Rendering

src/Components/Components/src/Forms/EditContext.cs

@@ -4,6 +4,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Linq.Expressions;
 
 namespace Microsoft.AspNetCore.Components.Forms
 {
@@ -158,6 +159,16 @@ public IEnumerable<string> GetValidationMessages(FieldIdentifier fieldIdentifier
             }
         }
 
+        /// <summary>
+        /// Gets the current validation messages for the specified field.
+        ///
+        /// This method does not perform validation itself. It only returns messages determined by previous validation actions.
+        /// </summary>
+        /// <param name="accessor">Identifies the field whose current validation messages should be returned.</param>
+        /// <returns>The current validation messages for the specified field.</returns>
+        public IEnumerable<string> GetValidationMessages(Expression<Func<object>> accessor)
+            => GetValidationMessages(FieldIdentifier.Create(accessor));
+
         /// <summary>
         /// Determines whether the specified fields in this <see cref="EditContext"/> has been modified.
         /// </summary>
@@ -167,6 +178,14 @@ public bool IsModified(in FieldIdentifier fieldIdentifier)
             ? state.IsModified
             : false;
 
+        /// <summary>
+        /// Determines whether the specified fields in this <see cref="EditContext"/> has been modified.
+        /// </summary>
+        /// <param name="accessor">Identifies the field whose current validation messages should be returned.</param>
+        /// <returns>True if the field has been modified; otherwise false.</returns>
+        public bool IsModified(Expression<Func<object>> accessor)
+            => IsModified(FieldIdentifier.Create(accessor));
+
         /// <summary>
         /// Validates this <see cref="EditContext"/>.
         /// </summary>

src/Components/Components/src/Forms/EditContextDataAnnotationsExtensions.cs

@@ -74,7 +74,7 @@ private static void ValidateField(EditContext editContext, ValidationMessageStor
 
                 Validator.TryValidateProperty(propertyValue, validationContext, results);
                 messages.Clear(fieldIdentifier);
-                messages.AddRange(fieldIdentifier, results.Select(result => result.ErrorMessage));
+                messages.Add(fieldIdentifier, results.Select(result => result.ErrorMessage));
 
                 // We have to notify even if there were no messages before and are still no messages now,
                 // because the "state" that changed might be the completion of some async validation task

src/Components/Components/src/Forms/EditContextExpressionExtensions.cs

@@ -1,21 +1,27 @@
 // Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
+using System;
+
 namespace Microsoft.AspNetCore.Components.Forms
 {
     /// <summary>
     /// Provides information about the <see cref="EditContext.OnFieldChanged"/> event.
     /// </summary>
-    public sealed class FieldChangedEventArgs
+    public sealed class FieldChangedEventArgs : EventArgs
     {
         /// <summary>
-        /// Identifies the field whose value has changed.
+        /// Creates a new instance of <see cref="FieldChangedEventArgs"/>.
         /// </summary>
-        public FieldIdentifier FieldIdentifier { get; }
-
-        internal FieldChangedEventArgs(in FieldIdentifier fieldIdentifier)
+        /// <param name="fieldIdentifier">The <see cref="Forms.FieldIdentifier"/></param>
+        public FieldChangedEventArgs(in FieldIdentifier fieldIdentifier)
         {
             FieldIdentifier = fieldIdentifier;
         }
+
+        /// <summary>
+        /// Identifies the field whose value has changed.
+        /// </summary>
+        public FieldIdentifier FieldIdentifier { get; }
     }
 }

src/Components/Components/src/Forms/FieldChangedEventArgs.cs

@@ -10,7 +10,7 @@ namespace Microsoft.AspNetCore.Components.Forms
     /// Uniquely identifies a single field that can be edited. This may correspond to a property on a
     /// model object, or can be any other named value.
     /// </summary>
-    public readonly struct FieldIdentifier
+    public readonly struct FieldIdentifier : IEquatable<FieldIdentifier>
     {
         /// <summary>
         /// Initializes a new instance of the <see cref="FieldIdentifier"/> structure.
@@ -68,8 +68,15 @@ public override int GetHashCode()
         /// <inheritdoc />
         public override bool Equals(object obj)
             => obj is FieldIdentifier otherIdentifier
-            && otherIdentifier.Model == Model
-            && string.Equals(otherIdentifier.FieldName, FieldName, StringComparison.Ordinal);
+            && Equals(otherIdentifier);
+
+        /// <inheritdoc />
+        public bool Equals(FieldIdentifier otherIdentifier)
+        {
+            return
+                otherIdentifier.Model == Model &&
+                string.Equals(otherIdentifier.FieldName, FieldName, StringComparison.Ordinal);
+        }
 
         private static void ParseAccessor<T>(Expression<Func<T>> accessor, out object model, out string fieldName)
         {

src/Components/Components/src/Forms/FieldIdentifier.cs

@@ -33,14 +33,30 @@ public ValidationMessageStore(EditContext editContext)
         public void Add(in FieldIdentifier fieldIdentifier, string message)
             => GetOrCreateMessagesListForField(fieldIdentifier).Add(message);
 
+        /// <summary>
+        /// Adds a validation message for the specified field.
+        /// </summary>
+        /// <param name="accessor">Identifies the field for which to add the message.</param>
+        /// <param name="message">The validation message.</param>
+        public void Add(Expression<Func<object>> accessor, string message)
+            => Add(FieldIdentifier.Create(accessor), message);
+
         /// <summary>
         /// Adds the messages from the specified collection for the specified field.
         /// </summary>
         /// <param name="fieldIdentifier">The identifier for the field.</param>
         /// <param name="messages">The validation messages to be added.</param>
-        public void AddRange(in FieldIdentifier fieldIdentifier, IEnumerable<string> messages)
+        public void Add(in FieldIdentifier fieldIdentifier, IEnumerable<string> messages)
             => GetOrCreateMessagesListForField(fieldIdentifier).AddRange(messages);
 
+        /// <summary>
+        /// Adds the messages from the specified collection for the specified field.
+        /// </summary>
+        /// <param name="accessor">Identifies the field for which to add the messages.</param>
+        /// <param name="messages">The validation messages to be added.</param>
+        public void Add(Expression<Func<object>> accessor, IEnumerable<string> messages)
+            => Add(FieldIdentifier.Create(accessor), messages);
+
         /// <summary>
         /// Gets the validation messages within this <see cref="ValidationMessageStore"/> for the specified field.
         ///
@@ -74,6 +90,13 @@ public void Clear()
             _messages.Clear();
         }
 
+        /// <summary>
+        /// Removes all messages within this <see cref="ValidationMessageStore"/> for the specified field.
+        /// </summary>
+        /// <param name="accessor">Identifies the field for which to remove the messages.</param>
+        public void Clear(Expression<Func<object>> accessor)
+            => Clear(FieldIdentifier.Create(accessor));
+
         /// <summary>
         /// Removes all messages within this <see cref="ValidationMessageStore"/> for the specified field.
         /// </summary>

src/Components/Components/src/Forms/ValidationMessageStore.cs

@@ -1,16 +1,24 @@
 // Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
+using System;
+
 namespace Microsoft.AspNetCore.Components.Forms
 {
     /// <summary>
     /// Provides information about the <see cref="EditContext.OnValidationRequested"/> event.
     /// </summary>
-    public sealed class ValidationRequestedEventArgs
+    public sealed class ValidationRequestedEventArgs : EventArgs
     {
-        internal static readonly ValidationRequestedEventArgs Empty = new ValidationRequestedEventArgs();
+        /// <summary>
+        /// Gets a shared empty instance of <see cref="ValidationRequestedEventArgs"/>.
+        /// </summary>
+        public static new readonly ValidationRequestedEventArgs Empty = new ValidationRequestedEventArgs();
 
-        internal ValidationRequestedEventArgs()
+        /// <summary>
+        /// Creates a new instance of <see cref="ValidationRequestedEventArgs"/>.
+        /// </summary>
+        public ValidationRequestedEventArgs()
         {
         }
     }

src/Components/Components/src/Forms/ValidationMessageStoreExpressionExtensions.cs

@@ -1,16 +1,24 @@
 // Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
+using System;
+
 namespace Microsoft.AspNetCore.Components.Forms
 {
     /// <summary>
     /// Provides information about the <see cref="EditContext.OnValidationStateChanged"/> event.
     /// </summary>
-    public sealed class ValidationStateChangedEventArgs
+    public sealed class ValidationStateChangedEventArgs : EventArgs
     {
-        internal static readonly ValidationStateChangedEventArgs Empty = new ValidationStateChangedEventArgs();
+        /// <summary>
+        /// Gets a shared empty instance of <see cref="ValidationStateChangedEventArgs"/>.
+        /// </summary>
+        public new static readonly ValidationStateChangedEventArgs Empty = new ValidationStateChangedEventArgs();
 
-        internal ValidationStateChangedEventArgs()
+        /// <summary>
+        /// Creates a new instance of <see cref="ValidationStateChangedEventArgs" />
+        /// </summary>
+        public ValidationStateChangedEventArgs()
         {
         }
     }