@chill-sharp/ui-core 1.1.12

package/doc/HowTo/01-simple-blog-sqlite.md

@@ -0,0 +1,153 @@
+# HOW-TO: Simple Blog API on SQLite
+
+Versione italiana: [Italiano](../it/HowTo/01-simple-blog-sqlite.md)
+
+This example shows the smallest useful ChillSharp setup: one `Blog` entity, one EF Core SQLite context, and a ChillSharp API with no schema label texts in `ChillEntity` or `ChillProperty` attributes.
+
+## Goal
+
+Build a minimal API that can create and read `Blog` entities through ChillSharp.
+
+## 1. Define the entity
+
+Use the parameterless versions of `ChillEntity` and `ChillProperty` when you do not want to provide schema texts yet.
+
+```csharp
+using ChillSharp.Annotations;
+using ChillSharp.EF;
+using System.ComponentModel.DataAnnotations;
+
+namespace MyBlogApp.Model;
+
+[ChillEntity]
+public class Blog : ChillEntity
+{
+    [Key]
+    public override Guid Guid { get; set; }
+
+    [ChillProperty]
+    public string Name { get; set; } = string.Empty;
+
+    [ChillProperty]
+    public string? Url { get; set; }
+
+    public override string GetLabel(IChillContext context) => Name;
+}
+```
+
+## 2. Define a query
+
+`Find` is enough to load one entity by `Guid`, but a query type is still useful when you want normal filtering and projections.
+
+```csharp
+using ChillSharp.Annotations;
+using ChillSharp.EF;
+
+namespace MyBlogApp.Query;
+
+[ChillEntity]
+public class BlogQuery : ChillQuery
+{
+    [ChillProperty]
+    public string? Name { get; set; }
+
+    public override IQueryable<IChillEntity> OnQuery(IChillContext context)
+    {
+        var db = (BloggingContext)context;
+        var query = db.Blogs.AsQueryable();
+
+        if (Guid.HasValue)
+            query = query.Where(x => x.Guid == Guid.Value);
+
+        if (!string.IsNullOrWhiteSpace(Name))
+            query = query.Where(x => x.Name.Contains(Name));
+
+        return query;
+    }
+}
+```
+
+## 3. Create the SQLite context
+
+The context must implement `IChillContext` and return the namespace prefix used by your model and query types.
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using MyBlogApp.Model;
+
+namespace MyBlogApp;
+
+public class BloggingContext : DbContext, IChillContext
+{
+    public DbSet<Blog> Blogs => Set<Blog>();
+
+    public BloggingContext(DbContextOptions<BloggingContext> options) : base(options)
+    {
+    }
+
+    public string GetChillTypePrefix() => "MyBlogApp";
+}
+```
+
+## 4. Register ChillSharp
+
+```csharp
+using ChillSharp.Api;
+using Microsoft.EntityFrameworkCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddDbContext<BloggingContext>(options =>
+    options.UseSqlite("Data Source=blogging.db"));
+
+builder.Services.AddChillApi<BloggingContext>();
+
+var app = builder.Build();
+
+using (var scope = app.Services.CreateScope())
+{
+    var db = scope.ServiceProvider.GetRequiredService<BloggingContext>();
+    db.Database.EnsureCreated();
+}
+
+app.MapChillApi();
+app.Run();
+```
+
+## 5. Create and read a blog with `ChillSharpClient`
+
+```csharp
+using ChillSharp.Client;
+using ChillSharp.Client.Dto;
+
+var client = new ChillSharpClient("http://localhost:5000/api/chill");
+
+var blog = new ChillDtoEntity
+{
+    ChillType = "Model.Blog",
+    Guid = Guid.NewGuid()
+};
+blog.Properties["Name"] = "SQLite Notes";
+blog.Properties["Url"] = "https://example.local/sqlite-notes";
+
+var created = client.Create(blog);
+
+var query = new ChillDtoQuery
+{
+    ChillType = "Query.BlogQuery"
+};
+query.Properties["Guid"] = created.Guid;
+query.ResultProperties = ChillDtoProperty.Build("Guid", "Name", "Url");
+
+var result = client.Query(query);
+var loadedBlog = result.Results.Single();
+Console.WriteLine($"{loadedBlog.GetString("Name")} -> {loadedBlog.GetString("Url")}");
+```
+
+## Notes
+
+- `Model.Blog` and `Query.BlogQuery` are short type names. ChillSharp expands them using `GetChillTypePrefix()`.
+- With parameterless attributes, schema metadata falls back to the CLR type and property names.
+
+Next example: [Add schema labels and read them through ChillSharp](02-blog-schema-labels.md)
+

package/doc/HowTo/02-blog-schema-labels.md

@@ -0,0 +1,140 @@
+# HOW-TO: Add Schema Labels to Blog and Read Them
+
+Versione italiana: [Italiano](../it/HowTo/02-blog-schema-labels.md)
+
+This example updates the previous `Blog` model by adding schema texts to `ChillEntity` and `ChillProperty`, then shows how to read those labels back.
+
+## Goal
+
+Decorate the model with schema metadata and retrieve it through ChillSharp schema services.
+
+## 1. Add labels to the entity and properties
+
+```csharp
+using ChillSharp.Annotations;
+using ChillSharp.EF;
+using System.ComponentModel.DataAnnotations;
+
+namespace MyBlogApp.Model;
+
+[ChillEntity(
+    UniquePropertyKeyString: "4E16F6C0-6B95-4D67-98BC-9F4D0D63EAF1",
+    PrimaryLanguageLabel: "Blog",
+    SecondaryLanguageLabel: "Blog")]
+public class Blog : ChillEntity
+{
+    [Key]
+    public override Guid Guid { get; set; }
+
+    [ChillProperty(
+        UniquePropertyKeyString: "50B1BB6C-D794-41E4-A85C-D4F9D7A6FA7E",
+        PrimaryLanguageLabel: "Blog name",
+        SecondaryLanguageLabel: "Nome blog")]
+    public string Name { get; set; } = string.Empty;
+
+    [ChillProperty(
+        UniquePropertyKeyString: "A18E7754-D8F7-45FE-B8A8-EA762A4EC9E6",
+        PrimaryLanguageLabel: "Blog url",
+        SecondaryLanguageLabel: "Url blog")]
+    public string? Url { get; set; }
+
+    public override string GetLabel(IChillContext context) => Name;
+}
+```
+
+## 2. Enable schema persistence
+
+To expose schema metadata through `get-schema`, the EF Core context must also implement `IChillSchemaDbContext`, add the schema model, and register `AddChillSchema<TContext>()`.
+
+```csharp
+using ChillSharp.Schema;
+using ChillSharp.Schema.Model;
+using Microsoft.EntityFrameworkCore;
+using MyBlogApp.Model;
+
+namespace MyBlogApp;
+
+public class BloggingContext : DbContext, IChillContext, IChillSchemaDbContext
+{
+    public DbSet<Blog> Blogs => Set<Blog>();
+    public DbSet<ChillSchemaEntry> SchemaEntries => Set<ChillSchemaEntry>();
+
+    public BloggingContext(DbContextOptions<BloggingContext> options) : base(options)
+    {
+    }
+
+    public string GetChillTypePrefix() => "MyBlogApp";
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        base.OnModelCreating(modelBuilder);
+        modelBuilder.AddChillSchemaModel();
+    }
+}
+```
+
+Register the schema service together with the API:
+
+```csharp
+using ChillSharp.Api;
+using ChillSharp.Schema;
+using Microsoft.EntityFrameworkCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddDbContext<BloggingContext>(options =>
+    options.UseSqlite("Data Source=blogging.db"));
+
+builder.Services.AddChillApi<BloggingContext>();
+builder.Services.AddChillSchema<BloggingContext>();
+```
+
+## 3. Read schema metadata from a client
+
+`ChillSharpClient.GetSchema(...)` returns property metadata generated from the decorated model.
+
+```csharp
+using ChillSharp.Client;
+
+var client = new ChillSharpClient("http://localhost:5000/api/chill");
+var schema = client.GetSchema("Model.Blog", "default");
+
+var nameProperty = schema?.Properties.Single(x => x.Name == "Name");
+var urlProperty = schema?.Properties.Single(x => x.Name == "Url");
+
+Console.WriteLine(nameProperty?.DisplayName); // Blog name
+Console.WriteLine(urlProperty?.DisplayName);  // Blog url
+```
+
+## 4. Read the entity display name in server-side code
+
+The server-side `ChillSharp.Dto.ChillDtoSchema` also carries the entity-level `DisplayName`, which is populated from `ChillEntityAttribute.PrimaryLanguageLabel`.
+
+```csharp
+using ChillSharp;
+
+public class SchemaDebugService
+{
+    private readonly IChillDtoEngine _dtoEngine;
+
+    public SchemaDebugService(IChillDtoEngine dtoEngine)
+    {
+        _dtoEngine = dtoEngine;
+    }
+
+    public string? GetBlogSchemaDisplayName()
+    {
+        var schema = _dtoEngine.GetSchema("Model.Blog", "default");
+        return schema?.DisplayName;
+    }
+}
+```
+
+## Notes
+
+- Property `DisplayName` comes from `ChillPropertyAttribute.PrimaryLanguageLabel`.
+- Entity `DisplayName` comes from `ChillEntityAttribute.PrimaryLanguageLabel`.
+- If you later call `SetSchema(...)`, persisted schema values can override the generated defaults for a given `ChillType` and `ChillViewCode`.
+
+Next example: [Use authentication with ChillSharp](03-authentication.md)
+

package/doc/HowTo/03-authentication.md

@@ -0,0 +1,218 @@
+# HOW-TO: Use Authentication with ChillSharp
+
+Versione italiana: [Italiano](../it/HowTo/03-authentication.md)
+
+This example shows the smallest useful authentication setup for a ChillSharp API: protect the API, enable the auth module, register an account, log in, and let `ChillSharpClient` reuse and refresh tokens automatically.
+
+## Goal
+
+Expose a protected ChillSharp API backed by ASP.NET Core Identity and authenticate with `ChillSharpClient`.
+
+## 1. Use a context that supports Identity and ChillSharp auth
+
+The context must support your normal ChillSharp model and the auth tables.
+
+```csharp
+using ChillSharp;
+using ChillSharp.Auth;
+using Microsoft.AspNetCore.Identity;
+using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore;
+
+namespace MyBlogApp;
+
+public class BloggingContext : IdentityDbContext<IdentityUser>, IChillContext, IChillAuthDbContext
+{
+    public BloggingContext(DbContextOptions<BloggingContext> options) : base(options)
+    {
+    }
+
+    public string GetChillTypePrefix() => "MyBlogApp";
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        base.OnModelCreating(modelBuilder);
+        modelBuilder.AddChillAuthModel();
+    }
+}
+```
+
+## 2. Register Identity, authentication, and ChillSharp auth services
+
+Protect the normal ChillSharp API and add the auth endpoints on top of it.
+
+```csharp
+using ChillSharp.Api;
+using ChillSharp.Auth;
+using ChillSharp.Auth.Api;
+using Microsoft.AspNetCore.Identity;
+using Microsoft.EntityFrameworkCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddDbContext<BloggingContext>(options =>
+    options.UseSqlite("Data Source=blogging-auth.db"));
+
+builder.Services.AddIdentityCore<IdentityUser>()
+    .AddEntityFrameworkStores<BloggingContext>()
+    .AddSignInManager()
+    .AddDefaultTokenProviders();
+
+builder.Services.AddAuthentication(ChillAuthIdentityDefaults.AuthenticationScheme)
+    .AddChillAuthBearer();
+
+builder.Services.AddAuthorization();
+
+builder.Services.AddChillApi<BloggingContext, IdentityUser>(options =>
+{
+    options.ProtectedApi = true;
+    options.ReturnPasswordResetTokensInResponse = true;
+    options.InitializeRootUserOnStartup = true;
+    options.CreateChillAuthUserForRoot = true;
+    options.RootUserName = "root";
+    options.RootPassword = "Pass123$";
+    options.RootEmail = "root@example.com";
+    options.RootDisplayName = "Root Administrator";
+});
+```
+
+When `CreateChillAuthUserForRoot = true`, startup also creates the linked ChillSharp `AuthUser` and sets `CanManagePermissions = true` for that root user.
+
+You can also provide the same bootstrap values through environment variables instead of hardcoding them:
+
+```text
+CHILLSHARP_AUTH_ROOT_USERNAME=root
+CHILLSHARP_AUTH_ROOT_PASSWORD=Pass123$
+CHILLSHARP_AUTH_ROOT_EMAIL=root@example.com
+CHILLSHARP_AUTH_ROOT_DISPLAY_NAME=Root Administrator
+```
+
+## 3. Enable middleware and map the API
+
+`MapChillApi()` exposes both the normal ChillSharp endpoints and the auth endpoints once the auth services are registered.
+
+```csharp
+var app = builder.Build();
+
+app.UseAuthentication();
+app.UseAuthorization();
+
+using (var scope = app.Services.CreateScope())
+{
+    var db = scope.ServiceProvider.GetRequiredService<BloggingContext>();
+    db.Database.EnsureCreated();
+}
+
+app.MapChillApi();
+app.Run();
+```
+
+## 4. Use the root user to manage permissions
+
+The root-user initializer is the easiest bootstrap path for a new protected system because the linked ChillSharp auth user is created with permission-management enabled.
+
+```csharp
+var rootClient = new ChillSharpClient("http://localhost:5000/api/chill");
+
+var rootLogin = rootClient.LoginAuthAccount(new LoginAuthIdentityRequest
+{
+    UserNameOrEmail = "root",
+    Password = "Pass123$"
+});
+
+var authUsers = rootClient.GetAuthUsers();
+Console.WriteLine(authUsers.Count);
+```
+
+That login can call auth-management endpoints such as users, roles, and permission rules because the generated root `AuthUser` has `CanManagePermissions = true`.
+
+## 5. Register the first normal account
+
+Create the client with the normal Chill base URL. Auth calls automatically switch from `/api/chill` to `/api/chill-auth`.
+
+```csharp
+using ChillSharp.Auth.Contracts;
+using ChillSharp.Client;
+
+var client = new ChillSharpClient("http://localhost:5000/api/chill");
+
+var registerResponse = client.RegisterAuthAccount(new RegisterAuthIdentityRequest
+{
+    UserName = "admin",
+    Email = "admin@example.com",
+    Password = "Pass123$",
+    DisplayName = "Administrator",
+    DisplayCultureName = "it-IT",
+    CreateChillAuthUser = true
+});
+```
+
+After a successful registration, the client stores the returned access token and refresh token internally.
+
+If `DisplayCultureName` is provided and `CreateChillAuthUser = true`, the linked `AuthUser` is initialized with culture-based defaults for:
+
+- `DisplayTimeZone`
+- `DisplayDateFormat`
+- `DisplayNumberFormat`
+
+For example, `it-IT` typically produces presets like:
+
+- `DisplayTimeZone = "W. Europe Standard Time"`
+- `DisplayDateFormat = "DD/MM/YYYY"`
+- `DisplayNumberFormat = "1.000,00"`
+
+These are server-side presets and can be edited later through auth-user management.
+
+## 6. Log in explicitly
+
+If the account already exists, log in with the same `ChillSharpClient`.
+
+```csharp
+var loginResponse = client.LoginAuthAccount(new LoginAuthIdentityRequest
+{
+    UserNameOrEmail = "admin",
+    Password = "Pass123$"
+});
+```
+
+## 7. Call protected endpoints
+
+Once authenticated, the same client can call protected ChillSharp endpoints.
+
+```csharp
+using ChillSharp.Client.Dto;
+
+var query = new ChillDtoQuery
+{
+    ChillType = "Query.BlogQuery"
+};
+query.ResultProperties = ChillDtoProperty.Build("Guid", "Name");
+
+var result = client.Query(query);
+Console.WriteLine(result.Results.Count);
+```
+
+## 8. Let the client refresh tokens automatically
+
+You do not need to manually attach bearer tokens on every request. If the client already has a refresh token, authenticated calls renew the access token when needed.
+
+```csharp
+var roles = client.GetAuthRoles();
+```
+
+You can also refresh explicitly:
+
+```csharp
+var refreshed = client.RefreshAuthAccount();
+```
+
+## Notes
+
+- Use `options.ProtectedApi = true` on `AddChillApi<TContext>(...)` if your ChillSharp endpoints must require authentication.
+- The root user created by `AddChillApi<TContext, TUser>(...)` is the bootstrap administrator path. When `CreateChillAuthUserForRoot = true`, the linked ChillSharp `AuthUser` is created with `CanManagePermissions = true`.
+- `CreateChillAuthUser = true` creates the linked ChillSharp `AuthUser`, but it does not automatically grant admin permissions.
+- `DisplayCultureName` on registration presets `DisplayTimeZone`, `DisplayDateFormat`, and `DisplayNumberFormat` for the linked `AuthUser`.
+- For production, bootstrap the first administrator deliberately, for example through root-user initialization or a trusted install-time flow.
+
+Next example: [Create a Docker image and configure it with environment variables](04-docker-env-variables.md)
+

package/doc/HowTo/04-blog-posts-one-to-many.md

@@ -0,0 +1,194 @@
+# HOW-TO: Handle a One-to-Many Blog-Posts Relation
+
+Versione italiana: [Italiano](../it/HowTo/04-blog-posts-one-to-many.md)
+
+This example extends the blog model with posts and shows how to load one blog together with its posts in a single `ChillSharpClient.Query(...)` call.
+
+## Goal
+
+Model a `Blog` to `Posts` one-to-many relation and project the nested collection from the ChillSharp client.
+
+## 1. Define the entities
+
+```csharp
+using ChillSharp.Annotations;
+using ChillSharp.EF;
+using System.ComponentModel.DataAnnotations;
+
+namespace MyBlogApp.Model;
+
+[ChillEntity]
+public class Blog : ChillEntity
+{
+    [Key]
+    public override Guid Guid { get; set; }
+
+    [ChillProperty]
+    public string Name { get; set; } = string.Empty;
+
+    [ChillProperty]
+    public string? Url { get; set; }
+
+    [ChillProperty]
+    public ICollection<Post>? Posts { get; set; }
+
+    public override string GetLabel(IChillContext context) => Name;
+}
+
+[ChillEntity]
+public class Post : ChillEntity
+{
+    [Key]
+    public override Guid Guid { get; set; }
+
+    [ChillProperty]
+    public Blog? Blog { get; set; }
+
+    [ChillProperty]
+    public DateTime? CreatedAt { get; set; }
+
+    [ChillProperty]
+    public string Title { get; set; } = string.Empty;
+
+    [ChillProperty]
+    public string Content { get; set; } = string.Empty;
+
+    public override void OnCreate(IChillContext context)
+    {
+        base.OnCreate(context);
+        CreatedAt = DateTime.UtcNow;
+    }
+
+    public override string GetLabel(IChillContext context) => Title;
+}
+```
+
+## 2. Add both sets to the context
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using MyBlogApp.Model;
+
+namespace MyBlogApp;
+
+public class BloggingContext : DbContext, IChillContext
+{
+    public DbSet<Blog> Blogs => Set<Blog>();
+    public DbSet<Post> Posts => Set<Post>();
+
+    public BloggingContext(DbContextOptions<BloggingContext> options) : base(options)
+    {
+    }
+
+    public string GetChillTypePrefix() => "MyBlogApp";
+}
+```
+
+## 3. Define a query for blogs
+
+```csharp
+using ChillSharp.Annotations;
+using ChillSharp.EF;
+
+namespace MyBlogApp.Query;
+
+[ChillEntity]
+public class BlogQuery : ChillQuery
+{
+    [ChillProperty]
+    public string? Name { get; set; }
+
+    public override IQueryable<IChillEntity> OnQuery(IChillContext context)
+    {
+        var db = (BloggingContext)context;
+        var query = db.Blogs.AsQueryable();
+
+        if (Guid.HasValue)
+            query = query.Where(x => x.Guid == Guid.Value);
+
+        if (!string.IsNullOrWhiteSpace(Name))
+            query = query.Where(x => x.Name.Contains(Name));
+
+        return query;
+    }
+}
+```
+
+## 4. Create a blog and two posts
+
+The relation is created by sending the parent `Blog` DTO as the `Blog` property of each `Post`.
+
+```csharp
+using ChillSharp.Client;
+using ChillSharp.Client.Dto;
+
+var client = new ChillSharpClient("http://localhost:5000/api/chill");
+
+var blog = new ChillDtoEntity
+{
+    ChillType = "Model.Blog",
+    Guid = Guid.NewGuid()
+};
+blog.Properties["Name"] = "ChillSharp Blog";
+blog.Properties["Url"] = "https://example.local/chillsharp-blog";
+
+var createdBlog = client.Create(blog);
+
+var firstPost = new ChillDtoEntity
+{
+    ChillType = "Model.Post",
+    Guid = Guid.NewGuid()
+};
+firstPost.Properties["Title"] = "First post";
+firstPost.Properties["Content"] = "Hello from ChillSharp";
+firstPost.Properties["Blog"] = createdBlog.Mock();
+client.Create(firstPost);
+
+var secondPost = new ChillDtoEntity
+{
+    ChillType = "Model.Post",
+    Guid = Guid.NewGuid()
+};
+secondPost.Properties["Title"] = "Second post";
+secondPost.Properties["Content"] = "Nested queries are handy";
+secondPost.Properties["Blog"] = createdBlog.Mock();
+client.Create(secondPost);
+```
+
+## 5. Load one blog with its posts in one call
+
+This is the part that matters most for a one-to-many relation: the nested projection is described through `ChillDtoProperty.With(...)`, and the returned collection is read with `GetCollection(...)`.
+
+```csharp
+using ChillSharp.Client.Dto;
+
+var query = new ChillDtoQuery
+{
+    ChillType = "Query.BlogQuery"
+};
+query.Properties["Guid"] = createdBlog.Guid;
+query.ResultProperties = ChillDtoProperty.Build(
+    "Guid",
+    "Name",
+    "Url",
+    ChillDtoProperty.With("Posts", "Guid", "Title", "CreatedAt"));
+
+var queryResult = client.Query(query);
+var loadedBlog = queryResult.Results.Single();
+
+Console.WriteLine(loadedBlog.GetString("Name"));
+
+foreach (var post in loadedBlog.GetCollection("Posts"))
+{
+    Console.WriteLine(post.GetString("Title"));
+}
+```
+
+## What this gives you
+
+- one HTTP call to load the parent entity and the child collection
+- a strongly-typed projection builder on the client side
+- DTO-based relation handling without writing a dedicated controller for `Blog` or `Post`
+
+Next: [Back to the documentation index](../README.md)
+