@chill-sharp/ui-core 1.1.12 → 1.1.15

package/doc/README.md

@@ -1,228 +0,0 @@
-# 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

@@ -1,130 +0,0 @@
-# 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

@@ -1,217 +0,0 @@
-# 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.
-