@chill-sharp/ui-core 1.1.12 → 1.1.15

package/doc/HowTo/05-docker-env-variables.md

@@ -1,274 +0,0 @@
-# HOW-TO: Create a Docker Image and Configure It with Environment Variables
-
-Versione italiana: [Italiano](../it/HowTo/05-docker-env-variables.md)
-
-This example shows how to package a ChillSharp API into a Docker image and configure it at runtime through environment variables instead of hardcoded values.
-
-## Goal
-
-Build one container image that can be reused across environments by changing only environment variables.
-
-## 1. Read configuration from environment-aware `IConfiguration`
-
-ASP.NET Core already maps environment variables into `builder.Configuration`. Use that instead of hardcoding the SQLite path, module toggles, token lifetimes, SMTP settings, or root-user credentials.
-
-For the DTO date/time mapper, ChillSharp also reads `CHILLSHARP_SYSTEM_TIMEZONE` directly from the process environment. It should be an IANA id such as `Europe/Rome`.
-
-This setting is used for ChillSharp `DateTime` handling and for UTC-to-local normalization of some `DateTimeOffset` inputs. `DateOnly` and `TimeOnly` keep normal .NET string output.
-
-`ChillSharp.Attachment` also reads `CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT` directly. In containers, point it at a mounted volume such as `/attachments`.
-
-```csharp
-using ChillSharp.Api;
-using ChillSharp.Auth;
-using ChillSharp.Auth.Api;
-using ChillSharp.Attachment.Services;
-using Microsoft.AspNetCore.Identity;
-using Microsoft.EntityFrameworkCore;
-
-var builder = WebApplication.CreateBuilder(args);
-
-var databasePath = builder.Configuration["CHILLSHARP_DB_PATH"] ?? "/data/blogging.db";
-var attachmentArchiveRoot = builder.Configuration["CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT"] ?? "/attachments";
-
-builder.Services.AddDbContext<BloggingContext>(options =>
-    options.UseSqlite($"Data Source={databasePath}"));
-
-builder.Services.AddIdentityCore<IdentityUser>()
-    .AddEntityFrameworkStores<BloggingContext>()
-    .AddSignInManager()
-    .AddDefaultTokenProviders();
-
-builder.Services.AddAuthentication(ChillAuthIdentityDefaults.AuthenticationScheme)
-    .AddChillAuthBearer();
-
-builder.Services.AddAuthorization();
-
-builder.Services.AddChillApi<BloggingContext>(options =>
-{
-    options.ProtectedApi = GetBool("CHILLSHARP_API_PROTECTED", true);
-    options.ApiBasePath = builder.Configuration["CHILLSHARP_API_BASE_PATH"] ?? "/api";
-    options.EnableSchemaApi = GetBool("CHILLSHARP_ENABLE_SCHEMA", true);
-    options.EnableAuthApi = GetBool("CHILLSHARP_ENABLE_AUTH", true);
-    options.EnableI18nApi = GetBool("CHILLSHARP_ENABLE_I18N", true);
-    options.EnableMcpApi = GetBool("CHILLSHARP_ENABLE_MCP", true);
-    options.EnableAttachmentApi = GetBool("CHILLSHARP_ENABLE_ATTACHMENT", false);
-});
-
-builder.Services.AddChillAuthIdentityApi<BloggingContext, IdentityUser>(options =>
-{
-    // ChillSharp reads these two environment variables as defaults:
-    // CHILLSHARP_AUTH_ACCESS_TOKEN_MINUTES and CHILLSHARP_AUTH_REFRESH_TOKEN_DAYS.
-    // Set them here only when you want this host startup code to control the mapping explicitly.
-    options.AccessTokenLifetime = TimeSpan.FromMinutes(GetInt("CHILLSHARP_AUTH_ACCESS_TOKEN_MINUTES", 20));
-    options.RefreshTokenLifetime = TimeSpan.FromDays(GetInt("CHILLSHARP_AUTH_REFRESH_TOKEN_DAYS", 14));
-    options.ReturnPasswordResetTokensInResponse = GetBool("CHILLSHARP_AUTH_RETURN_PASSWORD_RESET_TOKENS", false);
-    options.SendPasswordResetEmails = GetBool("CHILLSHARP_AUTH_SEND_PASSWORD_RESET_EMAILS", true);
-    options.InitializeRootUserOnStartup = GetBool("CHILLSHARP_AUTH_INITIALIZE_ROOT_USER", true);
-    options.CreateChillAuthUserForRoot = GetBool("CHILLSHARP_AUTH_CREATE_ROOT_AUTH_USER", true);
-    options.PasswordResetEmailSubject = builder.Configuration["CHILLSHARP_AUTH_PASSWORD_RESET_SUBJECT"] ?? "Reset your password";
-    options.PasswordResetUrlBase = builder.Configuration["CHILLSHARP_AUTH_PASSWORD_RESET_URL"];
-    options.SmtpHost = builder.Configuration["CHILLSHARP_SMTP_HOST"];
-    options.SmtpPort = GetInt("CHILLSHARP_SMTP_PORT", 587);
-    options.SmtpEnableSsl = GetBool("CHILLSHARP_SMTP_ENABLE_SSL", true);
-    options.SmtpUserName = builder.Configuration["CHILLSHARP_SMTP_USERNAME"];
-    options.SmtpPassword = builder.Configuration["CHILLSHARP_SMTP_PASSWORD"];
-    options.PasswordResetFromEmail = builder.Configuration["CHILLSHARP_SMTP_FROM_EMAIL"];
-    options.PasswordResetFromDisplayName = builder.Configuration["CHILLSHARP_SMTP_FROM_DISPLAY_NAME"];
-});
-
-builder.Services.Configure<ChillAttachmentOptions>(options =>
-{
-    options.ArchiveRoot = attachmentArchiveRoot;
-});
-
-var app = builder.Build();
-
-app.UseAuthentication();
-app.UseAuthorization();
-
-Directory.CreateDirectory(Path.GetDirectoryName(databasePath)!);
-Directory.CreateDirectory(attachmentArchiveRoot);
-
-using (var scope = app.Services.CreateScope())
-{
-    var db = scope.ServiceProvider.GetRequiredService<BloggingContext>();
-    db.Database.EnsureCreated();
-}
-
-app.MapChillApi();
-app.Run();
-
-bool GetBool(string name, bool defaultValue)
-{
-    return bool.TryParse(builder.Configuration[name], out var value) ? value : defaultValue;
-}
-
-int GetInt(string name, int defaultValue)
-{
-    return int.TryParse(builder.Configuration[name], out var value) ? value : defaultValue;
-}
-```
-
-The MCP and attachment modules are registered by `AddChillApi<TContext>()` only when the `DbContext` implements their required interfaces:
-
-- `ChillSharp.Schema` and `ChillSharp.Mcp`: `IChillSchemaDbContext`
-- `ChillSharp.Auth`: `IChillAuthDbContext`
-- `ChillSharp.I18n`: `IChillI18nDbContext`
-- `ChillSharp.Attachment`: `IChillAttachmentDbContext`
-
-Keep `CHILLSHARP_ENABLE_ATTACHMENT=false` until your context exposes the attachment model and archive storage. Then switch it to `true` and keep `/attachments` mounted.
-
-## 2. Use environment variables for modules and runtime settings
-
-These names are a good container baseline for the current built-in modules:
-
-```text
-CHILLSHARP_DB_PATH
-CHILLSHARP_SYSTEM_TIMEZONE
-CHILLSHARP_API_PROTECTED
-CHILLSHARP_API_BASE_PATH
-CHILLSHARP_ENABLE_SCHEMA
-CHILLSHARP_ENABLE_AUTH
-CHILLSHARP_ENABLE_I18N
-CHILLSHARP_ENABLE_MCP
-CHILLSHARP_ENABLE_ATTACHMENT
-CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT
-```
-
-`CHILLSHARP_ENABLE_*` variables are example-host variables: your app reads them from `IConfiguration` and maps them to `ChillApiOptions`. `CHILLSHARP_API_BASE_PATH` defaults to `/api` and is also read by ChillSharp when you do not set `ChillApiOptions.ApiBasePath` explicitly. `CHILLSHARP_SYSTEM_TIMEZONE`, `CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT`, and the root-user variables below are read directly by ChillSharp services too.
-
-When enabled, the default endpoints include:
-
-```text
-http://localhost:8080/api/chill
-http://localhost:8080/api/chill-auth
-http://localhost:8080/api/chill-attachment
-http://localhost:8080/api/chill-mcp
-```
-
-## 3. Use environment variables for the root user
-
-`AddChillAuthIdentityApi(...)` already knows these variables:
-
-```text
-CHILLSHARP_AUTH_ROOT_USERNAME
-CHILLSHARP_AUTH_ROOT_PASSWORD
-CHILLSHARP_AUTH_ROOT_EMAIL
-CHILLSHARP_AUTH_ROOT_DISPLAY_NAME
-```
-
-When `CreateChillAuthUserForRoot = true`, the root `AuthUser` is also created with `CanManagePermissions = true`.
-
-## 4. Create the Dockerfile
-
-This image builds the application once and runs it with the ASP.NET Core runtime image.
-
-```dockerfile
-FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
-WORKDIR /src
-
-COPY MyBlogApp.csproj ./
-RUN dotnet restore
-
-COPY . ./
-RUN dotnet publish -c Release -o /app/out
-
-FROM mcr.microsoft.com/dotnet/aspnet:8.0
-WORKDIR /app
-
-COPY --from=build /app/out ./
-
-ENV ASPNETCORE_URLS=http://+:8080
-ENV CHILLSHARP_DB_PATH=/data/blogging.db
-ENV CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome
-ENV CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT=/attachments
-
-VOLUME ["/data"]
-VOLUME ["/attachments"]
-EXPOSE 8080
-
-ENTRYPOINT ["dotnet", "MyBlogApp.dll"]
-```
-
-## 5. Build the image
-
-```bash
-docker build -t myblogapp:latest .
-```
-
-## 6. Run the container with environment variables
-
-This example starts the API, persists SQLite data and attachment files in local Docker volumes, and creates the root administrator at startup.
-
-```bash
-docker run --rm -p 8080:8080 \
-  -v myblogapp-data:/data \
-  -v myblogapp-attachments:/attachments \
-  -e CHILLSHARP_DB_PATH=/data/blogging.db \
-  -e CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome \
-  -e CHILLSHARP_API_PROTECTED=true \
-  -e CHILLSHARP_ENABLE_SCHEMA=true \
-  -e CHILLSHARP_ENABLE_AUTH=true \
-  -e CHILLSHARP_ENABLE_I18N=true \
-  -e CHILLSHARP_ENABLE_MCP=true \
-  -e CHILLSHARP_ENABLE_ATTACHMENT=false \
-  -e CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT=/attachments \
-  -e CHILLSHARP_AUTH_ROOT_USERNAME=root \
-  -e CHILLSHARP_AUTH_ROOT_PASSWORD=Pass123$ \
-  -e CHILLSHARP_AUTH_ROOT_EMAIL=root@example.com \
-  -e CHILLSHARP_AUTH_ROOT_DISPLAY_NAME="Root Administrator" \
-  myblogapp:latest
-```
-
-With the values above, the application is then available at:
-
-```text
-http://localhost:8080/api/chill
-http://localhost:8080/api/chill-auth
-http://localhost:8080/api/chill-mcp
-```
-
-Set `CHILLSHARP_ENABLE_ATTACHMENT=true` when the host context implements `IChillAttachmentDbContext`; then the attachment API is available at `http://localhost:8080/api/chill-attachment`.
-
-## 7. Optional `docker compose` example
-
-```yaml
-services:
-  myblogapp:
-    image: myblogapp:latest
-    build: .
-    ports:
-      - "8080:8080"
-    environment:
-      ASPNETCORE_URLS: http://+:8080
-      CHILLSHARP_DB_PATH: /data/blogging.db
-      CHILLSHARP_SYSTEM_TIMEZONE: Europe/Rome
-      CHILLSHARP_API_PROTECTED: "true"
-      CHILLSHARP_API_BASE_PATH: /api
-      CHILLSHARP_ENABLE_SCHEMA: "true"
-      CHILLSHARP_ENABLE_AUTH: "true"
-      CHILLSHARP_ENABLE_I18N: "true"
-      CHILLSHARP_ENABLE_MCP: "true"
-      CHILLSHARP_ENABLE_ATTACHMENT: "false"
-      CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT: /attachments
-      CHILLSHARP_AUTH_ROOT_USERNAME: root
-      CHILLSHARP_AUTH_ROOT_PASSWORD: Pass123$
-      CHILLSHARP_AUTH_ROOT_EMAIL: root@example.com
-      CHILLSHARP_AUTH_ROOT_DISPLAY_NAME: Root Administrator
-    volumes:
-      - myblogapp-data:/data
-      - myblogapp-attachments:/attachments
-
-volumes:
-  myblogapp-data:
-  myblogapp-attachments:
-```
-
-## Notes
-
-- Keep the image generic and push environment-specific values into runtime configuration.
-- Persist SQLite under a mounted volume, otherwise the database is lost when the container is removed.
-- For production, inject secrets through your container platform or secret manager instead of hardcoding them in `docker run` history or `compose` files.
-
-Next example: [Handle a one-to-many Blog-Posts relation and fetch it in one client call](05-blog-posts-one-to-many.md)

package/doc/HowTo/06-chunk-transactions-autocomplete.md

@@ -1,196 +0,0 @@
-# HOW-TO: Use Chunk, Transactions, and Autocomplete
-
-Versione italiana: [Italiano](../it/HowTo/06-chunk-transactions-autocomplete.md)
-
-This example shows how to send multiple ChillSharp operations in one call with `chunk`, how to wrap write operations in one database transaction, and how to use `autocomplete` for entity and query DTOs.
-
-## Goal
-
-Use the core ChillSharp API efficiently when the client must:
-
-- execute several operations in one HTTP request
-- commit a group of writes atomically
-- ask the server to complete or normalize DTO values before saving
-
-## 1. Prepare the client
-
-All examples below use the .NET client and assume the core API is mapped at `/api/chill`.
-
-```csharp
-using ChillSharp.Client;
-using ChillSharp.Client.Dto;
-
-var client = new ChillSharpClient("http://localhost:5000/api/chill");
-```
-
-## 2. Send multiple operations with `chunk`
-
-`chunk` sends a list of `ChillOperation` items to `/api/chill/chunk`.
-Each operation can contain a `Query` or an `Entity`, depending on the `Verb`.
-
-Set `Index` explicitly when execution order matters.
-
-```csharp
-using ChillSharp.Client.Dto;
-
-var firstPost = new ChillDtoEntity
-{
-    ChillType = "Model.Post",
-    Guid = Guid.Parse("11111111-1111-1111-1111-111111111111")
-};
-firstPost.Properties["Title"] = "First";
-firstPost.Properties["Author"] = "Ada";
-
-var secondPost = new ChillDtoEntity
-{
-    ChillType = "Model.Post",
-    Guid = Guid.Parse("22222222-2222-2222-2222-222222222222")
-};
-secondPost.Properties["Title"] = "Second";
-secondPost.Properties["Author"] = "Linus";
-
-var updateFirstPost = new ChillDtoEntity
-{
-    ChillType = "Model.Post",
-    Guid = firstPost.Guid
-};
-updateFirstPost.Properties["Title"] = "First updated";
-
-var operations = client.Chunk(new List<ChillOperation>
-{
-    new() { Index = 0, Verb = ChillOperationVerb.CREATE, Entity = firstPost },
-    new() { Index = 1, Verb = ChillOperationVerb.CREATE, Entity = secondPost },
-    new() { Index = 2, Verb = ChillOperationVerb.UPDATE, Entity = updateFirstPost }
-});
-```
-
-What this gives you:
-
-- one HTTP request instead of three
-- ordered execution through `Index`
-- one combined response containing the processed operations
-
-## 3. Wrap a chunk in one transaction
-
-Use `transaction` and `commit` when all enclosed write operations must succeed or fail together.
-
-```csharp
-var blog = new ChillDtoEntity
-{
-    ChillType = "Model.Blog",
-    Guid = Guid.NewGuid()
-};
-blog.Properties["Name"] = "Batch blog";
-blog.Properties["Url"] = "https://example.local/batch-blog";
-
-var post = new ChillDtoEntity
-{
-    ChillType = "Model.Post",
-    Guid = Guid.NewGuid()
-};
-post.Properties["Title"] = "Batch post";
-post.Properties["Blog"] = blog.Mock();
-
-var transactionalOperations = client.Chunk(new List<ChillOperation>
-{
-    new() { Index = 0, Verb = ChillOperationVerb.TRANSACTION },
-    new() { Index = 1, Verb = ChillOperationVerb.CREATE, Entity = blog },
-    new() { Index = 2, Verb = ChillOperationVerb.CREATE, Entity = post },
-    new() { Index = 3, Verb = ChillOperationVerb.COMMIT }
-});
-```
-
-Use this pattern only for the write operations that must share the same database transaction.
-If one operation fails before `commit`, the transaction is not committed.
-
-## 4. Autocomplete an entity DTO
-
-`autocomplete` uses the same DTO style as `create`, `update`, and `delete`, but it calls `/api/chill/autocomplete`.
-
-For entities, ChillSharp performs `OnAutocomplete(...)` without persisting changes:
-
-- if the entity already exists, it is loaded from the current `DbContext`
-- otherwise it is attached in `Added` state
-- the autocomplete logic runs inside a temporary transaction
-- the transaction is rolled back at the end, so the database is unchanged
-
-This is useful for previewing computed values such as slugs, labels, derived text, or default field combinations.
-
-```csharp
-var draftBlog = new ChillDtoEntity
-{
-    ChillType = "Model.Blog",
-    Guid = Guid.NewGuid()
-};
-draftBlog.Properties["Title"] = "  My first ChillSharp blog  ";
-
-var autocompletedBlog = client.Autocomplete(draftBlog);
-
-Console.WriteLine(autocompletedBlog.GetString("Title"));
-Console.WriteLine(autocompletedBlog.GetString("Url"));
-```
-
-Typical entity-side logic:
-
-```csharp
-public override void OnAutocomplete(IChillContext context)
-{
-    base.OnAutocomplete(context);
-
-    Title = Title?.Trim();
-
-    if (string.IsNullOrWhiteSpace(Url) && !string.IsNullOrWhiteSpace(Title))
-    {
-        Url = "/blogs/" + Title.ToLowerInvariant().Replace(' ', '-');
-    }
-}
-```
-
-## 5. Autocomplete a query DTO
-
-Queries also use `/api/chill/autocomplete`, but they do not participate in the EF Core context transaction flow.
-The query DTO is simply passed through `OnAutocomplete(...)` on the resolved `IChillQuery`.
-
-This is useful for normalizing filters before `Query(...)`, for example:
-
-- trimming text inputs
-- expanding a search box into a full-text field
-- setting default paging or sorting values
-
-```csharp
-var blogQuery = new ChillDtoQuery
-{
-    ChillType = "Query.BlogQuery"
-};
-blogQuery.Properties["Title"] = "  chillsharp  ";
-
-var autocompletedQuery = client.Autocomplete(blogQuery);
-
-Console.WriteLine(autocompletedQuery.GetString("Title"));
-Console.WriteLine(autocompletedQuery.GetString("FullTextSearch"));
-```
-
-Typical query-side logic:
-
-```csharp
-public override void OnAutocomplete(IChillContext context)
-{
-    base.OnAutocomplete(context);
-
-    Title = Title?.Trim();
-
-    if (!string.IsNullOrWhiteSpace(Title))
-    {
-        FullTextSearch = Title;
-    }
-}
-```
-
-## 6. Choose the right API
-
-- use `create`, `update`, and `delete` when the operation must change the database immediately
-- use `chunk` when several operations should travel in one request
-- use `transaction` plus `commit` inside `chunk` when multiple writes must be atomic
-- use `autocomplete` when the server should calculate or normalize values without saving them
-
-Next: [Back to the documentation index](../README.md)