docs: enhance documentation and features across multiple articles

- Updated threading.md to include ITimer interface and TaskExtensions for better async task handling.
- Added JsonResult for returning JSON with custom status codes in web-mvc.md.
- Introduced AuthenticatedUser and API versioning support in web.md.
- Revised intro.md to reflect updated target frameworks and added new features in various packages.
- Removed obsolete Media Image section from the table of contents.
- Updated docfx.json to target net10.0 and modified templates for a modern look.
- Created a new custom CSS file for improved styling on the landing page.
- Deleted outdated material template files to streamline the documentation structure.
- Adjusted table of contents to point to articles instead of docs.

Author: jamesmcroft

.github/workflows/docs.yml

@@ -37,10 +37,9 @@ jobs:
     - name: Install DocFX
       run: dotnet tool install -g docfx
 
-    - name: Generate DocFX metadata
-      working-directory: docs
-      run: docfx metadata docfx.json
-      continue-on-error: false
+    - name: Restore projects
+      run: dotnet restore
+      working-directory: src
 
     - name: Build DocFX site
       working-directory: docs

docs/articles/features/collections.md

@@ -158,3 +158,81 @@ public async Task ProcessMessagesAsync(IEnumerable<Message> messages, Cancellati
     }
 }
 ```
+
+There is also a `Chunk` extension for `IQueryable<T>` in the `MADE.Collections.QueryableExtensions` class, which splits a query into smaller queries for batch processing.
+
+## Conditionally adding or removing items with AddIf and RemoveIf
+
+The `AddIf` and `RemoveIf` extensions on `IList<T>` allow you to add or remove an item based on a condition function.
+
+```csharp
+public void AddPermissionIfAdmin(IList<Permission> permissions, Permission permission, bool isAdmin)
+{
+    permissions.AddIf(permission, () => isAdmin);
+}
+```
+
+Similarly, `AddRangeIf` and `RemoveRangeIf` extensions allow you to conditionally add or remove a collection of items.
+
+## Inserting items at a sorted position with InsertAtPotentialIndex
+
+The `InsertAtPotentialIndex` extension on `IList<T>` inserts an item at the position determined by a predicate, useful for maintaining sorted collections.
+
+```csharp
+public void InsertSorted(IList<int> sortedList, int value)
+{
+    sortedList.InsertAtPotentialIndex(value, (newItem, existingItem) => newItem > existingItem);
+}
+```
+
+The companion `PotentialIndexOf` extension returns the index without inserting, if you need to determine the position first.
+
+## Shuffling a collection with the Shuffle extension
+
+The `Shuffle` extension randomly reorders the elements of an `IEnumerable<T>`.
+
+```csharp
+var shuffled = myItems.Shuffle();
+```
+
+## Sorting an ObservableCollection with Sort and SortDescending
+
+`ObservableCollection<T>` objects don't have built-in sorting. The `Sort` and `SortDescending` extensions allow you to sort in place while correctly raising collection changed events.
+
+```csharp
+myObservableCollection.Sort(item => item.Name);
+myObservableCollection.SortDescending(item => item.Date);
+```
+
+## Checking if a collection is null or empty with IsNullOrEmpty
+
+The `IsNullOrEmpty` extension on `IEnumerable<T>` provides a quick check for whether a collection is null or contains no items.
+
+```csharp
+if (myItems.IsNullOrEmpty())
+{
+    // No items to process
+}
+```
+
+## Working with dictionaries using DictionaryExtensions
+
+The `MADE.Collections.DictionaryExtensions` class provides extensions for `Dictionary<TKey, TValue>`.
+
+### AddOrUpdate
+
+Adds a value to the dictionary, or updates it if the key already exists.
+
+```csharp
+var settings = new Dictionary<string, string>();
+settings.AddOrUpdate("Theme", "Dark");
+settings.AddOrUpdate("Theme", "Light"); // Updates existing key
+```
+
+### GetValueOrDefault
+
+Gets a value from a dictionary by key, or returns a default value if the key does not exist.
+
+```csharp
+var theme = settings.GetValueOrDefault("Theme", "Light");
+```

docs/articles/features/data-converters.md

@@ -7,17 +7,26 @@ title: Using the Data Converters package
 
 The Data Converters package provides a collection of value converters and extensions to manipulate data in your applications.
 
-## Converting a DateTime to a String using the DateTimeToStringValueConverter
+## Converting a bool to a String using the BooleanToStringValueConverter
 
-Value converters are a common coding practice for building XAML applications that allow values to be bound to a view, converted to a different type and back depending on the binding mode.
+The `MADE.Data.Converters.BooleanToStringValueConverter` converts `bool` values to configurable `String` representations using the `TrueValue` and `FalseValue` properties.
 
-Why should that be limited to just XAML applications though? 
+```csharp
+var converter = new BooleanToStringValueConverter
+{
+    TrueValue = "Yes",
+    FalseValue = "No"
+};
 
-The `MADE.Data.Converters.DateTimeToStringValueConverter` works across any .NET application, including your XAML bindings.
+string result = converter.Convert(true); // "Yes"
+bool original = converter.ConvertBack("No"); // false
+```
 
-It converts a `DateTime` value to a `String` using a format parameter. The format parameter must be a valid `DateTime` string format [based on the Microsoft documentation](https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings).
+## Converting a DateTime to a String using the DateTimeToStringValueConverter
+
+The `MADE.Data.Converters.DateTimeToStringValueConverter` converts a `DateTime` value to a `String` using a format parameter. The format parameter must be a valid `DateTime` string format [based on the Microsoft documentation](https://docs.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings).
 
-Below is an example of this in use in any C# application.
+Below is an example of this in use.
 
 ```csharp
 namespace App.Conversions
@@ -41,67 +50,57 @@ namespace App.Conversions
 }
 ```
 
-You can also take advantage of this converter in your XAML applications too.
-
-```xml
-<Page
-    x:Class="App.Conversions.MainPage"
-    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
-    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
-    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
-    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
-    xmlns:converters="using:MADE.Data.Converters"
-    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}"
-    mc:Ignorable="d">
-
-    <Page.Resources>
-        <converters:DateTimeToStringValueConverter x:Key="DateTimeToStringValueConverter" />
-    </Page.Resources>
-
-    <RelativePanel Padding="12">
-        <TextBlock Text="{x:Bind ViewModel.Date, Converter={StaticResource DateTimeToStringValueConverter}, ConverterParameter='g'}" />
-    </RelativePanel>
-</Page>
-```
-
 ## Creating your own custom value converters
 
-If you want to take advantage of what goes into a value converter, you can build your own using the `MADE.Data.Converters.IValueConverter` interface which provides the signatures for the `Convert` and `ConvertBack` methods.
+If you want to take advantage of what goes into a value converter, you can build your own using the `MADE.Data.Converters.IValueConverter<TFrom, TTo>` interface which provides the signatures for the `Convert` and `ConvertBack` methods.
 
 These can be used to convert any type to another. Whatever data conversion you think you may need, you'll be able to build out a value converter to satisfy that need for your project.
 
-You can then build out your own, similar to our `DateTimeToStringValueConverter`.
+If there is a common value converter you think is missing from MADE.NET, [raise a tracking item on GitHub](https://github.com/MADE-Apps/MADE.NET/issues/new/choose) and we'll get it implemented.
 
-```csharp
-namespace MADE.Data.Converters
-{
-    using System;
-    using System.Globalization;
+## DateTime extensions
 
-    public partial class DateTimeToStringValueConverter : IValueConverter<DateTime, string>
-    {
-        public string Convert(DateTime value, object parameter = default)
-        {
-            string format = parameter?.ToString();
-            return !string.IsNullOrWhiteSpace(format)
-                       ? value.ToString(format, CultureInfo.InvariantCulture)
-                       : value.ToString(CultureInfo.InvariantCulture);
-        }
+The `MADE.Data.Converters.Extensions.DateTimeExtensions` class provides a comprehensive set of extensions for working with `DateTime` values:
 
-        public DateTime ConvertBack(string value, object parameter = default)
-        {
-            if (string.IsNullOrWhiteSpace(value))
-            {
-                return DateTime.MinValue;
-            }
+- `ToCurrentAge()` - Calculates an age in years from a date to today.
+- `ToDaySuffix()` - Returns the day suffix (st, nd, rd, th) for a date.
+- `ToNearestHour()` - Rounds a date to the nearest hour.
+- `StartOfDay()` / `EndOfDay()` - Gets the start or end of the day.
+- `StartOfWeek()` / `EndOfWeek()` - Gets the start or end of the week.
+- `StartOfMonth()` / `EndOfMonth()` - Gets the start or end of the month.
+- `StartOfYear()` / `EndOfYear()` - Gets the start or end of the year.
+- `SetTime()` - Overrides the time part of a `DateTime` value (multiple overloads).
 
-            bool parsed = DateTime.TryParse(value, out DateTime dateTime);
-            return parsed ? dateTime : DateTime.MinValue;
-        }
-    }
-}
+## String extensions
+
+The `MADE.Data.Converters.Extensions.StringExtensions` class provides extensions for manipulating `String` values:
+
+- `ToTitleCase()` - Converts a string to title case.
+- `ToDefaultCase()` - Converts a string to default (lower) case.
+- `Truncate()` - Truncates a string to a specified length.
+- `ToBase64()` / `FromBase64()` - Converts to and from Base64 encoding.
+- `ToMemoryStreamAsync()` - Converts a string to a `MemoryStream`.
+- `ToInt()` / `ToNullableInt()` - Parses a string to an integer.
+- `ToFloat()` / `ToNullableFloat()` - Parses a string to a float.
+- `ToDouble()` / `ToNullableDouble()` - Parses a string to a double.
+- `ToBoolean()` - Parses a string to a boolean.
+
+## Boolean extensions
+
+The `MADE.Data.Converters.Extensions.BooleanExtensions` class provides the `ToFormattedString` extension for formatting `bool` values to custom string representations.
+
+```csharp
+bool isActive = true;
+string result = isActive.ToFormattedString("Active", "Inactive"); // "Active"
 ```
 
-If you want to build a XAML specific value converter, you can also apply the `Windows.UI.Xaml.Data.IValueConverter` to your class and implement the additional methods calling directly into your `Convert` and `ConvertBack` methods.
+## Math extensions
 
-If there is a common value converter you think is missing from MADE.NET, [raise a tracking item on GitHub](https://github.com/MADE-Apps/MADE.NET/issues/new/choose) and we'll get it implemented.
+The `MADE.Data.Converters.Extensions.MathExtensions` class provides extensions for common mathematic expressions including `ToRadians` to convert a degrees value to radians.
+
+## Length extensions
+
+The `MADE.Data.Converters.Extensions.LengthExtensions` class provides extensions for converting length values:
+
+- `ToMeters()` - Converts a value from miles to meters.
+- `ToMiles()` - Converts a value from meters to miles.

docs/articles/features/data-efcore.md

@@ -1,6 +1,6 @@
 ---
-uid: package-data-converters
-title: Using the Data Converters package
+uid: package-data-efcore
+title: Using the Data EF Core package
 ---
 
 # Using the Data Entity Framework Core package
@@ -17,9 +17,9 @@ These are:
 - A date the entity was created
 - A date the entity was last updated
 
-This is what the `MADE.Data.EFCore.EntityBase` type provides for you. It even goes as far as to initialize your created and last updated date values for you when you create your object.
+This is what the `MADE.Data.EFCore.EntityBase` type provides for you. It initializes your created and last updated date values when you create your object.
 
-To use it for your own entities, it's as simple as inheriting from the `EntityBase` type.
+To use it for your own entities, inherit from the `EntityBase` type. By default, it uses a `Guid` identifier.
 
 ```csharp
 namespace MyApp.Data
@@ -36,3 +36,70 @@ namespace MyApp.Data
     }
 }
 ```
+
+### Using a custom key type with EntityBase
+
+If you need a different identifier type, use the generic `EntityBase<TKey>`:
+
+```csharp
+public class Product : EntityBase<int>
+{
+    public string Name { get; set; }
+
+    public decimal Price { get; set; }
+}
+```
+
+### Entity interfaces
+
+The following interfaces are available for implementing custom entity types:
+
+- `IDatedEntity` - Defines `CreatedDate` and `UpdatedDate` properties.
+- `IEntityBase<TKey>` - Extends `IDatedEntity` with a typed `Id` property.
+- `IEntityBase` - A convenience interface that uses `Guid` as the key type.
+
+## Configuring entities with EntityBaseExtensions
+
+The `MADE.Data.EFCore.Extensions.EntityBaseExtensions` class provides extensions for configuring entity types in your `DbContext` model builder.
+
+```csharp
+protected override void OnModelCreating(ModelBuilder modelBuilder)
+{
+    // Configures the entity key and UTC date properties for a Guid-based entity
+    modelBuilder.Entity<User>().Configure();
+
+    // For entities with a custom key type
+    modelBuilder.Entity<Product>().ConfigureWithKey<Product, int>();
+}
+```
+
+The `ConfigureDateProperties` extension can be used independently to configure UTC date properties on any entity implementing `IDatedEntity`.
+
+## Storing dates in UTC with UtcDateTimeConverter
+
+The `MADE.Data.EFCore.Converters.UtcDateTimeConverter` helps ensure that entity model dates are stored and read in UTC format.
+
+Use the `IsUtc()` annotation on date properties in your entity configuration, then apply the converter to the model builder:
+
+```csharp
+protected override void OnModelCreating(ModelBuilder modelBuilder)
+{
+    modelBuilder.ApplyUtcDateTimeConverter();
+}
+```
+
+## DbContext extensions
+
+The `MADE.Data.EFCore.Extensions.DbContextExtensions` class provides additional helpers:
+
+- `UpdateAsync<T>` - Updates an entity and saves changes in a single call.
+- `RemoveWhere<T>` - Removes entities from a `DbSet` matching a predicate.
+- `SetEntityDates` - Automatically sets `CreatedDate` and `UpdatedDate` on tracked entities. Best called from an override of `SaveChangesAsync`.
+- `TrySaveChangesAsync` - Attempts to save changes to the database and handles concurrency exceptions.
+
+## Query extensions
+
+The `MADE.Data.EFCore.Extensions.QueryableExtensions` class provides helpers for querying:
+
+- `Page<T>` - Applies skip and take pagination to a query based on page number and page size.
+- `OrderBy<T>` - Dynamically orders query results by a property name string, with optional descending sort.