feat (Components): adds further null checks and docs

Updates all methods to accept a nullable source. This is handled within the methods now.

Updates all the docs to note this will be an empty collection or default if the source parameter is null.

src/Rhythm.Drop.Umbraco.Mapping/Components/MapperContextComponentExtensions.cs

@@ -16,7 +16,10 @@ public static class MapperContextComponentExtensions
     /// <typeparam name="TComponent">The type of the component.</typeparam>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="block">The block to map.</param>
-    /// <returns>A <typeparamref name="TComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="block"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TComponent? MapComponent<TComponent>(this MapperContext mapperContext, IBlockReference<IPublishedElement, IPublishedElement>? block) where TComponent : class, IComponent
     {
         if (block is null)
@@ -32,7 +35,10 @@ public static class MapperContextComponentExtensions
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="block">The block to map.</param>
-    /// <returns>A <see cref="IComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="IComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="block"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static IComponent? MapComponent(this MapperContext mapperContext, IBlockReference<IPublishedElement, IPublishedElement>? block)
     {
         return mapperContext.MapComponent<IComponent>(block);
@@ -44,7 +50,10 @@ public static class MapperContextComponentExtensions
     /// <typeparam name="TComponent">The type of the component.</typeparam>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="element">The element to map.</param>
-    /// <returns>A <typeparamref name="TComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="element"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TComponent? MapComponent<TComponent>(this MapperContext mapperContext, IPublishedElement? element) where TComponent : class, IComponent
     {
         if (element is null)
@@ -60,7 +69,10 @@ public static class MapperContextComponentExtensions
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="element">The element to map.</param>
-    /// <returns>A <see cref="IComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="IComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="element"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static IComponent? MapComponent(this MapperContext mapperContext, IPublishedElement? element)
     {
         return mapperContext.MapComponent<IComponent>(element);
@@ -72,9 +84,17 @@ public static class MapperContextComponentExtensions
     /// <typeparam name="TComponent">The type of the component.</typeparam>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="list">The list to map.</param>
-    /// <returns>A <typeparamref name="TComponent"/> if successful.</returns>
-    public static TComponent? MapComponent<TComponent>(this MapperContext mapperContext, BlockListModel list) where TComponent : class, IComponent
+    /// <returns>
+    /// <para>A <typeparamref name="TComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="list"/> or its first item are <see langword="null"/>.</para>
+    /// </returns>
+    public static TComponent? MapComponent<TComponent>(this MapperContext mapperContext, BlockListModel? list) where TComponent : class, IComponent
     {
+        if (list is null)
+        {
+            return default;
+        }
+
         return mapperContext.MapComponent<TComponent>(list.FirstOrDefault());
     }
 
@@ -83,8 +103,11 @@ public static class MapperContextComponentExtensions
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="list">The list to map.</param>
-    /// <returns>A <see cref="IComponent"/> if successful.</returns>
-    public static IComponent? MapComponent(this MapperContext mapperContext, BlockListModel list)
+    /// <returns>
+    /// <para>A <see cref="IComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="list"/> or its first item are <see langword="null"/>.</para>
+    /// </returns>
+    public static IComponent? MapComponent(this MapperContext mapperContext, BlockListModel? list)
     {
         return mapperContext.MapComponent<IComponent>(list);
     }
@@ -94,7 +117,10 @@ public static class MapperContextComponentExtensions
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="grid">The grid to map.</param>
-    /// <returns>A <see cref="IComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="IComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="grid"/> is null.</para>
+    /// </returns>
     public static IComponent? MapComponent(this MapperContext mapperContext, BlockGridModel? grid)
     {
         return mapperContext.MapComponent<IComponent>(grid);
@@ -105,7 +131,10 @@ public static class MapperContextComponentExtensions
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="grid">The grid to map.</param>
-    /// <returns>A <typeparamref name="TComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="grid"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TComponent? MapComponent<TComponent>(this MapperContext mapperContext, BlockGridModel? grid) where TComponent : class, IComponent
     {
         if (grid is null)

src/Rhythm.Drop.Umbraco.Mapping/Components/MapperContextComponentsExtensions.cs

@@ -16,9 +16,17 @@ public static class MapperContextComponentsExtensions
     /// <typeparam name="TComponent">The type of the component.</typeparam>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="content">The content to map.</param>
-    /// <returns>An array of <see cref="IComponent"/>.</returns>
-    public static TComponent[] MapComponents<TComponent>(this MapperContext mapperContext, IPublishedContent content) where TComponent : class, IComponent
+    /// <returns>
+    /// <para>An array of <see cref="IComponent"/>.</para>
+    /// <para>This method will return an empty collection if <paramref name="content"/> is <see langword="null"/>.</para>
+    /// </returns>
+    public static TComponent[] MapComponents<TComponent>(this MapperContext mapperContext, IPublishedContent? content) where TComponent : class, IComponent
     {
+        if (content is null)
+        {
+            return [];
+        }
+
         var component = mapperContext.Map<TComponent[]>(content);
 
         return component ?? [];
@@ -29,8 +37,11 @@ public static TComponent[] MapComponents<TComponent>(this MapperContext mapperCo
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="content">The content to map.</param>
-    /// <returns>An array of <see cref="IComponent"/>.</returns>
-    public static IComponent[] MapComponents(this MapperContext mapperContext, IPublishedContent content)
+    /// <returns>
+    /// <para>An array of <see cref="IComponent"/>.</para>
+    /// <para>This method will return an empty collection if <paramref name="content"/> is <see langword="null"/>.</para>
+    /// </returns>
+    public static IComponent[] MapComponents(this MapperContext mapperContext, IPublishedContent? content)
     {
         return mapperContext.MapComponents<IComponent>(content);
     }
@@ -41,9 +52,17 @@ public static IComponent[] MapComponents(this MapperContext mapperContext, IPubl
     /// <typeparam name="TComponent">The type of the component.</typeparam>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="list">The list to map.</param>
-    /// <returns>An array of <typeparamref name="TComponent"/>.</returns>
-    public static TComponent[] MapComponents<TComponent>(this MapperContext mapperContext, BlockListModel list) where TComponent : class, IComponent
+    /// <returns>
+    /// <para>An array of <typeparamref name="TComponent"/>.</para>
+    /// <para>This method will return an empty collection if <paramref name="list"/> is <see langword="null"/>.</para>
+    /// </returns>
+    public static TComponent[] MapComponents<TComponent>(this MapperContext mapperContext, BlockListModel? list) where TComponent : class, IComponent
     {
+        if (list is null)
+        {
+            return [];
+        }
+
         var components = new List<TComponent>();
         foreach (var block in list)
         {
@@ -64,8 +83,11 @@ public static TComponent[] MapComponents<TComponent>(this MapperContext mapperCo
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="list">The list to map.</param>
-    /// <returns>An array of <see cref="IComponent"/>.</returns>
-    public static IComponent[] MapComponents(this MapperContext mapperContext, BlockListModel list)
+    /// <returns>
+    /// <para>An array of <see cref="IComponent"/>.</para>
+    /// <para>This method will return an empty collection if <paramref name="list"/> is <see langword="null"/>.</para>
+    /// </returns>
+    public static IComponent[] MapComponents(this MapperContext mapperContext, BlockListModel? list)
     {
         return mapperContext.MapComponents<IComponent>(list);
     }
@@ -74,9 +96,11 @@ public static IComponent[] MapComponents(this MapperContext mapperContext, Block
     /// Maps a <see cref="BlockGridModel"/> to a collection of <see cref="IComponent"/>.
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
-
     /// <param name="grid">The grid to map.</param>
-    /// <returns>An array of <typeparamref name="TComponent"/>.</returns>
+    /// <returns>
+    /// <para>An array of <typeparamref name="TComponent"/>.</para>
+    /// <para>This method will return an empty collection if <paramref name="grid"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TComponent[] MapComponents<TComponent>(this MapperContext mapperContext, BlockGridModel? grid) where TComponent : class, IComponent
     {
         var gridComponent = mapperContext.MapComponent<TComponent>(grid);
@@ -93,7 +117,10 @@ public static TComponent[] MapComponents<TComponent>(this MapperContext mapperCo
     /// </summary>
     /// <param name="mapperContext">The current mapper context.</param>
     /// <param name="grid">The grid to map.</param>
-    /// <returns>An array of <see cref="IComponent"/>.</returns>
+    /// <returns>
+    /// <para>An array of <see cref="IComponent"/>.</para>
+    /// <para>This method will return an empty collection if <paramref name="grid"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static IComponent[] MapComponents(this MapperContext mapperContext, BlockGridModel? grid)
     {
         return mapperContext.MapComponents<IComponent>(grid);

src/Rhythm.Drop.Umbraco.Mapping/Components/UmbracoMapperComponentExtensions.cs

@@ -19,7 +19,10 @@ public static class UmbracoMapperComponentExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="block">The block to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <typeparamref name="TComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="block"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TComponent? MapComponent<TComponent>(this IUmbracoMapper mapper, IBlockReference<IPublishedElement, IPublishedElement>? block, Action<MapperContext>? configureContext = default) where TComponent : class, IComponent
     {
         if (block is null)
@@ -36,7 +39,10 @@ public static class UmbracoMapperComponentExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="block">The block to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <see cref="IComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="IComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="block"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static IComponent? MapComponent(this IUmbracoMapper mapper, IBlockReference<IPublishedElement, IPublishedElement>? block, Action<MapperContext>? configureContext = default)
     {
         return mapper.MapComponent<IComponent>(block, configureContext);
@@ -49,7 +55,10 @@ public static class UmbracoMapperComponentExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="element">The element to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <typeparamref name="TComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="element"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TComponent? MapComponent<TComponent>(this IUmbracoMapper mapper, IPublishedElement? element, Action<MapperContext>? configureContext = default) where TComponent : class, IComponent
     {
         if (element is null)
@@ -66,7 +75,10 @@ public static class UmbracoMapperComponentExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="element">The element to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <see cref="IComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="IComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="element"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static IComponent? MapComponent(this IUmbracoMapper mapper, IPublishedElement? element, Action<MapperContext>? configureContext = default)
     {
         return mapper.MapComponent<IComponent>(element, configureContext);
@@ -79,9 +91,17 @@ public static class UmbracoMapperComponentExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="list">The list to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <typeparamref name="TComponent"/> if successful.</returns>
-    public static TComponent? MapComponent<TComponent>(this IUmbracoMapper mapper, BlockListModel list, Action<MapperContext>? configureContext = default) where TComponent : class, IComponent
+    /// <returns>
+    /// <para>A <typeparamref name="TComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="list"/> or its first item are <see langword="null"/>.</para>
+    /// </returns>
+    public static TComponent? MapComponent<TComponent>(this IUmbracoMapper mapper, BlockListModel? list, Action<MapperContext>? configureContext = default) where TComponent : class, IComponent
     {
+        if (list is null)
+        {
+            return default;
+        }
+
         return mapper.MapComponent<TComponent>(list.FirstOrDefault(), configureContext);
     }
 
@@ -91,8 +111,11 @@ public static class UmbracoMapperComponentExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="list">The list to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <see cref="IComponent"/> if successful.</returns>
-    public static IComponent? MapComponent(this IUmbracoMapper mapper, BlockListModel list, Action<MapperContext>? configureContext = default)
+    /// <returns>
+    /// <para>A <see cref="IComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="list"/> or its first item are <see langword="null"/>.</para>
+    /// </returns>
+    public static IComponent? MapComponent(this IUmbracoMapper mapper, BlockListModel? list, Action<MapperContext>? configureContext = default)
     {
         return mapper.MapComponent<IComponent>(list, configureContext);
     }
@@ -103,7 +126,10 @@ public static class UmbracoMapperComponentExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="grid">The grid to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <see cref="IComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <see cref="IComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="grid"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static IComponent? MapComponent(this IUmbracoMapper mapper, BlockGridModel? grid, Action<MapperContext>? configureContext = default)
     {
         return mapper.MapComponent<IComponent>(grid, configureContext);
@@ -115,7 +141,10 @@ public static class UmbracoMapperComponentExtensions
     /// <param name="mapper">The current umbraco mapper.</param>
     /// <param name="grid">The grid to map.</param>
     /// <param name="configureContext">The optional configure mapper context action.</param>
-    /// <returns>A <typeparamref name="TComponent"/> if successful.</returns>
+    /// <returns>
+    /// <para>A <typeparamref name="TComponent"/> if successful.</para>
+    /// <para>This method will return <see langword="default" /> if <paramref name="grid"/> is <see langword="null"/>.</para>
+    /// </returns>
     public static TComponent? MapComponent<TComponent>(this IUmbracoMapper mapper, BlockGridModel? grid, Action<MapperContext>? configureContext = default) where TComponent : class, IComponent
     {
         if (grid is null)