@chill-sharp/ui-core 1.1.12

package/doc/README.md

@@ -0,0 +1,228 @@
+# ChillSharp Documentation
+
+Versione italiana: [Italiano](./it/README.md)
+
+This folder contains the reference documentation for ChillSharp.
+
+`doc/HowTo` is intentionally left as the tutorial section. Use it for guided, incremental examples. The rest of this folder is the reference layer: concepts, registration, permissions, auth, and client-generation workflows.
+
+## Documentation Map
+
+- [ModelPreparation.md](./ModelPreparation.md)
+  Prepare an EF Core model so ChillSharp can activate entities, run lifecycle hooks, generate schema metadata, and persist audit fields.
+
+- [ReferenceExistence.md](./ReferenceExistence.md)
+  Check whether an EF Core reference has foreign-key values without loading its related entity, including databases without enforced FK constraints.
+
+- [RegisterContext.md](./RegisterContext.md)
+  Register ChillSharp modules against a host `DbContext` and map the API surface.
+
+- [Configuration/README.md](./Configuration/README.md)
+  Quick reference for the example host configuration options and their environment variables.
+
+- [AttachmentModel/README.md](./AttachmentModel/README.md)
+  Attachment entity model, archive layout, configuration, and upload/download endpoint behavior.
+
+- [DateTimeSerialization.md](./DateTimeSerialization.md)
+  How ChillSharp serializes and parses `DateTimeOffset`, `DateTime`, `DateOnly`, and `TimeOnly`, including comparisons with default ASP.NET Core behavior.
+
+- [DateTimePolicy/README.md](./DateTimePolicy/README.md)
+  Current DTO policy for `DateTime` and `DateTimeOffset`, including configured timezone handling, UTC normalization, and server-managed audit fields.
+
+- [AuthenticationModel/README.md](./AuthenticationModel/README.md)
+  Identity-backed account flows, auth-management endpoints, bootstrap strategies, and protected API setup.
+
+- [CurrentUserPreferences.md](./CurrentUserPreferences.md)
+  Cached authenticated-user culture, time-zone, date-format, and number-format preferences for `IChillContext` and entity lifecycle hooks.
+
+- [MenuGuide/README.md](./MenuGuide/README.md)
+  Backend-managed menu tree, menu endpoints, and `MenuHierarchy` filtering rules.
+
+- [MenuGuide/Relations.md](./MenuGuide/Relations.md)
+  Configure EF Core and ChillSharp schema metadata for one-to-many relations.
+
+- [UiCore/README.md](./UiCore/README.md)
+  Shared Angular UI scope and CRUD menu-task configuration.
+
+- [PermissionModel/README.md](./PermissionModel/README.md)
+  The permission model used by `ChillSharp.Auth`, including precedence, scopes, and how entity/property access is resolved.
+
+- [ComplianceGuide/README.md](./ComplianceGuide/README.md)
+  How ChillSharp supports common security and compliance controls such as validation, least-privilege authorization, and audit metadata.
+
+- [AIAssistedDevelopment/README.md](./AIAssistedDevelopment/README.md)
+  How ChillSharp supports AI-assisted development by reducing repetitive CRUD code, stabilizing the API surface, and keeping model growth more uniform.
+
+- [Mcp/README.md](./Mcp/README.md)
+  Model Context Protocol module, MCP tool behavior, registration, `EnableMCP`, and guidance for preparing an AI-friendly `DbContext`.
+
+- [ClientGeneration/README.md](./ClientGeneration/README.md)
+  Generate client libraries from a ChillSharp host for TypeScript and Python using an OpenAPI document exposed by the host application.
+
+- [ChillSharpClient.md](./ChillSharpClient.md)
+  Use the .NET `ChillSharp.Client` library for core entity operations, auth, schema/menu, i18n, and attachments.
+
+- [../ext/chill-sharp-ts-client/README.md](../ext/chill-sharp-ts-client/README.md)
+  Generic TypeScript client for ChillSharp services.
+
+- [../ext/chill-sharp-react-client/README.md](../ext/chill-sharp-react-client/README.md)
+  React provider and hooks built on top of the generic TypeScript client.
+
+- [../ext/chill-sharp-vue-client/README.md](../ext/chill-sharp-vue-client/README.md)
+  Vue plugin and composables built on top of the generic TypeScript client.
+
+- [../ext/chill-sharp-ng-client/README.md](../ext/chill-sharp-ng-client/README.md)
+  Angular DI helpers and RxJS service built on top of the generic TypeScript client.
+
+- [../ext/chill-sharp-py-client/README.md](../ext/chill-sharp-py-client/README.md)
+  Generic Python client for ChillSharp services.
+
+## Main Modules
+
+- `ChillSharp`
+  Core entity engine, DTO engine, and HTTP API surface.
+
+- `ChillSharp.Schema`
+  Schema generation, persistence, and schema cache.
+
+- `ChillSharp.Attachment`
+  Attachment entity model, archive storage, and upload/download endpoints.
+
+- `ChillSharp.Auth`
+  Authorization model, permission rules, role/user management, and optional ASP.NET Core Identity integration.
+
+- `ChillSharp.I18n`
+  Label and text lookup endpoints plus an in-memory i18n cache.
+
+- `ChillSharp.Client`
+  .NET client for ChillSharp and ChillSharp.Auth endpoints.
+
+- `ChillSharp.Mcp`
+  MCP server module built on the official C# SDK, exposing ChillSharp schema discovery and query tools for AI clients.
+
+- `ext/chill-sharp-ts-client`
+  Generic TypeScript client package.
+
+- `ext/chill-sharp-react-client`
+  React integration package layered on top of the TypeScript client.
+
+- `ext/chill-sharp-vue-client`
+  Vue integration package layered on top of the TypeScript client.
+
+- `ext/chill-sharp-ng-client`
+  Angular integration package layered on top of the TypeScript client.
+
+- `ext/chill-sharp-py-client`
+  Generic Python client package.
+
+## Core Concepts
+
+### `IChillContext`
+
+Your EF Core context must implement `IChillContext`. It defines:
+
+- the Chill type prefix used for dynamic activation
+- the primary and secondary cultures used to interpret schema labels
+- the current user name used by entity audit tracking
+
+Different contexts can coexist with different values. ChillSharp does not assume a single global configuration.
+
+### `ChillEntity`
+
+`ChillEntity` is the recommended base class for model types exposed through ChillSharp. It already provides:
+
+- `Guid`
+- `Position`
+- `Label`, `ShortLabel`, `FullTextContent`
+- `Checksum`, `LastUpdateUser`, `LastUpdate`, `LastUpdateUtcOffset`
+- default lifecycle behavior
+
+Lifecycle hooks are:
+
+- `OnCreate`
+- `OnUpdate`
+- `OnAfterUpdate`
+- `OnDelete`
+- `OnAfterDelete`
+- `OnSelect`
+- `OnInflate`
+- `OnAutocomplete`
+
+### Schema Metadata
+
+`ChillEntityAttribute` and `ChillPropertyAttribute` provide:
+
+- stable unique keys
+- `PrimaryLanguageLabel`
+- `SecondaryLanguageLabel`
+
+When ChillSharp builds a schema, it resolves those labels using:
+
+- `CultureInfo.CurrentUICulture`
+- `IChillContext.GetPrimaryCultureName()`
+- `IChillContext.GetSecondaryCultureName()`
+
+### Audit Fields
+
+After updates, ChillSharp automatically stores:
+
+- `Checksum`
+- `LastUpdateUser`
+- `LastUpdate`
+- `LastUpdateUtcOffset`
+
+The audit logic is enforced through the `IChillEntity` interface path used by `ChillEngine`, so a derived class can override `OnAfterUpdate()` without bypassing the base audit update.
+
+### Query Ordering
+
+`ChillDtoQuery` includes an `Ordering` object that mirrors `Pagination`:
+
+- `PropertyName`
+- `Direction`
+
+If the client does not send an explicit ordering, ChillSharp applies `Position` by default. `Position` is part of both `ChillEntity` and `ChillDtoEntity`, and defaults to `0`.
+
+When `PropertyName` points to a referenced Chill entity, ordering is applied using the referenced entity `Label`. This keeps generic list screens readable without requiring clients to know the foreign-key internals.
+
+## API Surface
+
+The core mapped API is exposed by:
+
+- `app.MapChillApi()`
+
+This maps the Chill API controllers and also includes:
+
+- `/api/chill/query`
+- `/api/chill/lookup`
+- `/api/chill/test`
+- `/api/chill/license`
+
+Depending on which modules are registered, the same host can also expose:
+
+- schema services through `ChillSharp.Schema`
+- attachment upload/download services through `ChillSharp.Attachment`
+- auth/account and permission-management services through `ChillSharp.Auth`
+- i18n text endpoints through `ChillSharp.I18n`
+
+## Reference vs How-To
+
+Use this split consistently:
+
+- `doc/HowTo`
+  Step-by-step tutorials. Keep these focused and task-oriented.
+
+- the rest of `doc/`
+  Reference documentation. Use these files when you need the model, registration, architecture, permission rules, or integration details.
+
+## How-To
+
+The existing tutorials remain unchanged:
+
+- [HowTo/01-simple-blog-sqlite.md](./HowTo/01-simple-blog-sqlite.md)
+- [HowTo/02-blog-schema-labels.md](./HowTo/02-blog-schema-labels.md)
+- [HowTo/03-authentication.md](./HowTo/03-authentication.md)
+- [HowTo/04-blog-posts-one-to-many.md](./HowTo/04-blog-posts-one-to-many.md)
+- [HowTo/05-docker-env-variables.md](./HowTo/05-docker-env-variables.md)
+- [HowTo/06-chunk-transactions-autocomplete.md](./HowTo/06-chunk-transactions-autocomplete.md)
+
+

package/doc/ReferenceExistence.md

@@ -0,0 +1,130 @@
+# Checking EF Core Reference Presence Without Loading
+
+Versione italiana: [Italiano](./it/ReferenceExistence.md)
+
+`ChillSharp.EF.ChillEntryExtension.Exist()` answers a small but useful question: does this reference navigation currently have all of its configured foreign-key values?
+
+```csharp
+using ChillSharp.EF;
+
+var hasCustomerReference = context.Entry(order)
+    .Reference(x => x.Customer)
+    .Exist();
+```
+
+The call reads the current values of the FK properties from EF Core's change tracker. With the default argument, it does not query the database and does not load `order.Customer`.
+
+> The extension is named `Exist`, not `Exists`. Its signature is `Exist(bool loadIfExist = false)`.
+
+## When To Use It
+
+Use `Exist()` in model logic that needs to distinguish an absent optional relationship from a relationship that has been assigned, while avoiding an unnecessary load of the principal entity. It is particularly useful in `OnUpdate`, `OnSelect`, or DTO-processing logic where only the branching decision is needed.
+
+```csharp
+public override void OnUpdate(IChillContext context)
+{
+    var db = (AppDbContext)context;
+
+    if (db.Entry(this).Reference(x => x.Customer).Exist())
+    {
+        // A customer FK value has been assigned. Customer is still not loaded.
+        CustomerSummaryRequired = true;
+    }
+    else
+    {
+        CustomerSummaryRequired = false;
+    }
+}
+```
+
+This is preferable to inspecting `Customer != null` when the navigation may simply be unloaded. A null navigation does not distinguish “no relationship” from “relationship not loaded.”
+
+## Optional Loading
+
+Pass `true` only when the next operation actually needs the related entity:
+
+```csharp
+var customerReference = context.Entry(order).Reference(x => x.Customer);
+
+if (customerReference.Exist(loadIfExist: true) && order.Customer is { } customer)
+{
+    // EF Core loaded Customer when it was not already loaded.
+    var customerName = customer.Name;
+}
+```
+
+The behavior is:
+
+| Call | FK values are incomplete or null | FK values are present and navigation is unloaded | Navigation loaded? |
+| --- | --- | --- | --- |
+| `Exist()` | Returns `false` | Returns `true` | No new load |
+| `Exist(true)` | Returns `false` | Returns `true` | Attempts to load the reference |
+
+If the navigation was already loaded, neither form loads it again. Because the result still describes FK values, `Exist(true)` can return `true` while the loaded navigation is null when an FK-less database contains an orphaned value.
+
+## FK-Less Database Does Not Mean Relationship-Less Model
+
+This extension works with a legacy or FK-less database implementation only if EF Core still knows the relationship and its dependent FK properties. A physical database constraint and EF Core relationship metadata are separate concerns.
+
+For example, the database may not enforce a constraint from `Order.CustomerGuid` to `Customer.Guid`, but the EF model still needs the scalar FK and relationship mapping:
+
+```csharp
+public sealed class Order : ChillEntity
+{
+    public Guid? CustomerGuid { get; set; }
+    public Customer? Customer { get; set; }
+}
+
+protected override void OnModelCreating(ModelBuilder modelBuilder)
+{
+    modelBuilder.Entity<Order>()
+        .HasOne(x => x.Customer)
+        .WithMany()
+        .HasForeignKey(x => x.CustomerGuid);
+}
+```
+
+`Exist()` reads `CustomerGuid` through this mapping. A relationship that is not configured in EF Core has no `ReferenceEntry` FK metadata for the extension to inspect; in that case, use the scalar key directly or configure the relationship.
+
+Shadow FK properties are supported as long as EF Core has mapped the navigation. The extension obtains the FK property metadata from the navigation, rather than requiring a public CLR FK property.
+
+## What The Result Means
+
+`Exist()` is a local FK-value presence test. It does not issue an existence query for the principal row.
+
+Consequently:
+
+- `true` means every configured FK component is non-null in the tracked dependent entry.
+- `false` means at least one FK component is null.
+- `true` does not guarantee that the related row exists, especially when the database does not enforce FK constraints or contains legacy orphaned values.
+- `true` does not mean the navigation is loaded.
+
+If the business rule requires proof that a principal row exists, query for it explicitly, for example with `AnyAsync`, or use `Exist(true)` and then handle a null loaded navigation. Prefer the explicit query when you need a server-side existence check without materializing the principal.
+
+```csharp
+var customerRowExists = await context.Set<Customer>()
+    .AnyAsync(x => x.Guid == order.CustomerGuid, cancellationToken);
+```
+
+## Composite Keys And Value Conventions
+
+For a composite FK, `Exist()` returns `true` only when every component is non-null. A partially populated composite key returns `false`.
+
+The extension checks for `null`; it does not validate sentinel values. For example, `Guid.Empty`, `0`, or an empty string is non-null and can therefore produce `true` if that is the value currently stored. Use validation appropriate to the domain when those values mean “unassigned.”
+
+## Preconditions And Failure Modes
+
+The entity must be attached to the same EF Core `DbContext` used to obtain its entry. Call the extension on the dependent-side reference navigation: the entity in the `ReferenceEntry` must own the FK properties that EF Core reports for that navigation. Calling it for a non-reference member, a navigation with no usable FK relationship metadata, or the principal-side navigation of a one-to-one relationship can throw `InvalidOperationException` because those FK properties do not belong to the inspected entry.
+
+Do not use it for collection navigations. A collection needs a different question—whether at least one related row exists—which normally requires a database query.
+
+## Decision Guide
+
+| Need | Use |
+| --- | --- |
+| Determine whether an optional reference has assigned FK values; do not load it | `Reference(...).Exist()` |
+| Load the reference only if FK values are assigned | `Reference(...).Exist(true)` |
+| Prove the principal row exists | An explicit `Any`/`AnyAsync` query |
+| Determine whether a collection has members | A query against the dependent set |
+
+Keep `Exist()` for the narrow FK-presence decision. Its value is that it makes that intent explicit and avoids a related-entity load when the load is unnecessary.

package/doc/RegisterContext.md

@@ -0,0 +1,217 @@
+# Registering A ChillSharp Context
+
+Versione italiana: [Italiano](./it/RegisterContext.md)
+
+This document shows how to wire ChillSharp modules into an ASP.NET Core host.
+
+## Minimal Core API
+
+For the core Chill API only:
+
+```csharp
+using ChillSharp.Api;
+using Microsoft.EntityFrameworkCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddDbContext<AppDbContext>(options =>
+    options.UseSqlite("Data Source=app.db"));
+
+builder.Services.AddChillApi<AppDbContext>();
+
+var app = builder.Build();
+app.MapChillApi();
+app.Run();
+```
+
+Requirements:
+
+- `AppDbContext` must inherit `DbContext`
+- `AppDbContext` must implement `IChillContext`
+
+## What `AddChillApi<TContext>()` Registers
+
+The core registration sets up:
+
+- ChillSharp controllers
+- `IChillContext` resolution from your host context
+- `IChillDtoEngine`
+- optional protected API behavior through `ChillApiOptions`
+
+## Protecting The Core API
+
+If the host already configures authentication and authorization, you can require auth on the Chill API:
+
+```csharp
+builder.Services.AddChillApi<AppDbContext>(options =>
+{
+    options.ProtectedApi = true;
+});
+```
+
+Then use the standard ASP.NET Core middleware:
+
+```csharp
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapChillApi();
+```
+
+## Adding Schema Services
+
+To persist and serve schema metadata:
+
+```csharp
+using ChillSharp.Schema;
+
+builder.Services.AddChillSchema<AppDbContext>();
+```
+
+Context requirements:
+
+- `AppDbContext : IChillSchemaDbContext`
+- `modelBuilder.AddChillSchemaModel()`
+
+`ChillSharp.Schema` also owns the schema cache registration.
+
+## Adding Auth Management
+
+To expose auth-management endpoints without ASP.NET Core Identity account flows:
+
+```csharp
+using ChillSharp.Auth.Api;
+
+builder.Services.AddChillAuthApi<AppDbContext>();
+```
+
+Context requirements:
+
+- `AppDbContext : IChillAuthDbContext`
+- `modelBuilder.AddChillAuthModel()`
+
+This adds endpoints for:
+
+- auth users
+- roles
+- user-role assignments
+- permission rules
+- permission evaluation
+
+## Adding Identity Account Flows
+
+To expose account registration, login, refresh tokens, password change, and password reset:
+
+```csharp
+using ChillSharp.Auth;
+using ChillSharp.Auth.Api;
+using Microsoft.AspNetCore.Identity;
+
+builder.Services.AddIdentityCore<IdentityUser>()
+    .AddEntityFrameworkStores<AppDbContext>()
+    .AddSignInManager()
+    .AddDefaultTokenProviders();
+
+builder.Services.AddAuthentication(ChillAuthIdentityDefaults.AuthenticationScheme)
+    .AddChillAuthBearer();
+
+builder.Services.AddAuthorization();
+
+builder.Services.AddChillApi<AppDbContext, IdentityUser>();
+```
+
+This overload builds on the normal Chill API registration and adds the Identity-backed auth endpoints without requiring a second ChillSharp registration call.
+
+## Adding I18n Services
+
+To expose i18n endpoints:
+
+```csharp
+using ChillSharp.I18n.Api;
+
+builder.Services.AddChillI18nApi<AppDbContext>();
+```
+
+Context requirements:
+
+- `AppDbContext : IChillI18nDbContext`
+- `modelBuilder.AddChillI18nModel()`
+
+The module currently exposes:
+
+- `GET /api/chill-i18n/text/{labelGuid}/{cultureName}`
+- `PUT /api/chill-i18n/text`
+
+## Full Host Example
+
+```csharp
+using ChillSharp.Api;
+using ChillSharp.Auth;
+using ChillSharp.Auth.Api;
+using ChillSharp.I18n.Api;
+using ChillSharp.Schema;
+using Microsoft.AspNetCore.Identity;
+using Microsoft.EntityFrameworkCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddDbContext<AppDbContext>(options =>
+    options.UseSqlite("Data Source=app.db"));
+
+builder.Services.AddIdentityCore<IdentityUser>()
+    .AddEntityFrameworkStores<AppDbContext>()
+    .AddSignInManager()
+    .AddDefaultTokenProviders();
+
+builder.Services.AddAuthentication(ChillAuthIdentityDefaults.AuthenticationScheme)
+    .AddChillAuthBearer();
+builder.Services.AddAuthorization();
+
+builder.Services.AddChillApi<AppDbContext, IdentityUser>(options =>
+{
+    options.ProtectedApi = true;
+});
+builder.Services.AddChillSchema<AppDbContext>();
+
+var app = builder.Build();
+
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapChillApi();
+app.Run();
+```
+
+## Mapping Behavior
+
+`app.MapChillApi()` maps the ChillSharp controllers and helper endpoints. It does not replace standard ASP.NET Core middleware setup. You still need:
+
+- `UseAuthentication()` if auth is enabled
+- `UseAuthorization()` if authorization is enabled
+
+I18n and auth controllers are added through controller discovery when their modules are registered.
+
+## Recommended Startup Order
+
+1. register the EF Core context
+2. register Identity if needed
+3. register authentication and authorization if needed
+4. register `AddChillApi<TContext>()`
+5. register optional modules or use the combined Identity overload
+6. build app
+7. apply middleware
+8. map Chill API
+
+## OpenAPI / Swagger
+
+ChillSharp itself does not force Swagger into your host. If you want OpenAPI output for documentation or client generation, add it in the host application:
+
+```csharp
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+
+var app = builder.Build();
+app.UseSwagger();
+app.UseSwaggerUI();
+```
+
+That is the recommended base for generating TypeScript and Python clients from a ChillSharp host.
+