@chill-sharp/ui-core 1.1.12 → 1.1.15

package/.agents/skills/chillsharp-current-user-preferences/SKILL.md

@@ -1,70 +0,0 @@
----
-name: chillsharp-current-user-preferences
-description: Configure, expose, and consume ChillSharp.Auth's cached current-user culture, time zone, date-format, number-format, and theme preferences in server logic and UI clients.
----
-
-# ChillSharp Current User Preferences
-
-Use this skill when a ChillSharp feature needs the authenticated user's display culture, time zone, date format, or number format. It covers server-side lifecycle hooks and UI/client consumption of the authoritative `AuthUser` preferences. Do not use it for browser-only preferences unrelated to `AuthUser`.
-
-## Model
-
-`ChillUserPreferences` is an immutable snapshot with `DisplayCultureName`, `DisplayTimeZone`, `DisplayDateFormat`, `DisplayNumberFormat`, and `PreferredTheme`. The backend stores `PreferredTheme` as an opaque string. In UI Core, unauthenticated users follow browser `prefers-color-scheme`; clients register extra themes with `provideChillSharpUiCore({ additionalThemes: ['theme-name'] })`. Entity hooks read the snapshot synchronously through:
-
-```csharp
-var preferences = context.GetCurrentUserPreferences();
-```
-
-Never load `AuthUser` from an `OnCreate`, `OnUpdate`, or other lifecycle hook merely to obtain these values.
-
-## Auth integration
-
-`AddChillAuthApi` registers `IChillAuthUserPreferencesAccessor` and the singleton `IChillAuthUserPreferencesCache`. Login and token refresh warm the snapshot; `ChillAuthService` refreshes it after an `AuthUser` save and removes it for deleted or renamed external identities.
-
-For a custom host DbContext, inject the scoped accessor and implement the two `IChillContext` methods below. Keep the accessor optional only when the context must also be constructible outside DI, such as for migrations or tests.
-
-```csharp
-private readonly IChillAuthUserPreferencesAccessor? _userPreferencesAccessor;
-
-public ChillUserPreferences GetCurrentUserPreferences() =>
-    _userPreferencesAccessor?.Current ?? ChillUserPreferences.Empty;
-
-public string GetDefaultUserCultureName()
-{
-    var cultureName = GetCurrentUserPreferences().DisplayCultureName;
-    return string.IsNullOrWhiteSpace(cultureName) ? GetPrimaryCultureName() : cultureName;
-}
-```
-
-The accessor is cache-only: when there is no authenticated principal or no warmed snapshot, it returns `ChillUserPreferences.Empty`. Do not add a fallback database query to lifecycle hooks.
-
-## API and client use
-
-The authenticated endpoint `GET /api/chill-auth/current-user-preferences` returns the same `ChillUserPreferences` snapshot as JSON:
-
-```json
-{
-  "displayCultureName": "it-IT",
-  "displayTimeZone": "Europe/Rome",
-  "displayDateFormat": "dd/MM/yyyy",
-  "displayNumberFormat": "N2"
-}
-```
-
-Use this endpoint after authentication and when restoring a session; do not infer the active display culture or time zone from the browser, operating system, token claims, or auth-management user endpoints. The C#, Python, TypeScript, Angular, Vue, and React clients expose it as `GetCurrentUserPreferences`, `get_current_user_preferences`, or `getCurrentUserPreferences`; the Vue and React packages also provide `useCurrentUserPreferences`.
-
-In Angular UI Core, inject `ChillService` and read its `userPreferences` signal (or its `displayCultureName`, `displayTimeZone`, `displayDateFormat`, and `displayNumberFormat` projections). Use these values to select UI language, format and parse dates and numbers, and convert UTC timestamps. Treat all fields as optional and choose an explicit fallback only when needed.
-
-## Entity use
-
-Use `DisplayTimeZone` as an IANA zone identifier only after validating it with the application's time-zone policy. Treat all fields as optional and provide an explicit fallback where one is required.
-
-```csharp
-public override void OnUpdate(IChillContext context)
-{
-    var timeZone = context.GetCurrentUserPreferences().DisplayTimeZone;
-    // Apply application-specific behavior only when timeZone is available.
-}
-```
-
-For full setup and cache behavior, read [CurrentUserPreferences.md](../../../doc/CurrentUserPreferences.md).

package/.agents/skills/chillsharp-ui-template/SKILL.md

@@ -1,18 +0,0 @@
----
-name: chillsharp-ui-template
-description: Build and customize Angular ChillSharp client projects from the UI template, including plugins, overrides, i18n, permissions, and runtime configuration.
----
-
-# ChillSharp UI Client Template
-
-Use this skill for work in `chill-sharp-ui-template` or a client repository created from it.
-
-The template owns runtime configuration, branding, routes, client plugins, and overrides. Shared controls, data access, schema rendering, auth, i18n primitives, and permission evaluation belong in `@chill-sharp/ui-core` and the ChillSharp client packages. Do not copy or patch shared package internals.
-
-Keep `provideClientTemplateProviders()` in the app provider chain. Register feature routes in `src/app/core/plugins/register-client-plugins.ts`; register deliberate provider replacements in `src/app/core/overrides/register-client-overrides.ts`. Use public package APIs only.
-
-Treat backend schema as the source of entity/property metadata rather than duplicating it in Angular. Use runtime API configuration from `public/env.js`. Request localized text with an explicit culture and preserve backend fallback behavior. UI permission checks can hide or disable operations, but the protected backend is the enforcement boundary.
-
-Permission-sensitive features must account for `Module -> Entity -> Property`: entity `Query/Create/Update/Delete` is separate from property `See/Modify`. Never infer write access from a visible field.
-
-Add plugins under the client-owned plugin folder, register providers through the override/provider points, keep tenant/feature flags/branding in runtime config, add focused tests, and run `npm run build` after registration changes. This `.agents/skills` directory travels with the template into client repositories.

package/doc/AIAssistedDevelopment/README.md

@@ -1,185 +0,0 @@
-# AI-Assisted Development Guide
-
-Versione italiana: [Italiano](../it/AIAssistedDevelopment/README.md)
-
-
-This document explains how ChillSharp can help when you build software with AI assistance and still want the codebase to remain structured, stable, and reviewable.
-
-The key idea is simple: AI tools are much more reliable when they work inside a constrained, repetitive, well-defined architecture than when they are asked to manually keep many controllers, DTOs, endpoints, and validation paths in sync.
-
-ChillSharp does not make AI-generated code automatically correct. What it does is reduce the amount of surface area that AI has to generate and maintain.
-
-## Why This Matters
-
-A common failure mode in AI-assisted backend development is that the model touches too many moving parts at once:
-
-- controllers
-- DTO mappings
-- request/response contracts
-- validation logic
-- authorization checks
-- duplicated CRUD behaviors
-
-The more files and custom endpoints you have, the easier it is for AI to introduce accidental interface drift, inconsistent behavior, or broad refactors that were never intended.
-
-ChillSharp reduces that risk by moving a large part of the backend surface into a uniform model-driven runtime.
-
-## How ChillSharp Helps
-
-### 1. Business logic grows inside a structured environment
-
-With ChillSharp, the main extension points are explicit and predictable:
-
-- `ChillEntity`
-- `ChillQuery`
-- `OnValidation()`
-- lifecycle hooks such as `OnCreate()`, `OnUpdate()`, `OnAfterUpdate()`, `OnDelete()`, and `OnSelect()`
-- metadata through `[ChillProperty]` and related annotations
-
-That gives AI a narrower and more structured place to make changes.
-
-Instead of asking an AI model to invent yet another controller, request DTO, response DTO, mapper, validator, and route contract, you can often ask it to:
-
-- add a property
-- add validation
-- add a query filter
-- add lifecycle logic
-- adjust permission rules
-
-This usually produces smaller and safer edits.
-
-### 2. Lower risk of accidental endpoint refactoring
-
-ChillSharp exposes a standard API surface through `app.MapChillApi()`, with stable operations such as:
-
-- `POST /api/chill/query`
-- `POST /api/chill/lookup`
-- `POST /api/chill/find`
-- `POST /api/chill/create`
-- `POST /api/chill/update`
-- `POST /api/chill/delete`
-
-Because the transport surface is centralized, adding or evolving business entities does not require AI to keep rewriting a growing set of per-entity controllers and route definitions.
-
-This reduces a specific AI risk:
-
-- changing endpoint names by accident
-- changing payload shapes inconsistently
-- implementing one endpoint differently from the rest
-- breaking clients through unnecessary API refactors
-
-The interface still evolves when your model evolves, but the CRUD and query mechanics do not have to be re-authored every time.
-
-### 3. Endpoints grow in a uniform way
-
-In a traditional hand-written backend, every new entity tends to create more duplicated API code. Over time, small differences accumulate:
-
-- one controller validates differently
-- another controller returns slightly different payloads
-- another endpoint forgets an authorization check
-- another DTO mapper omits a field
-
-AI tools amplify this problem because they continue the local pattern they see, even when the local pattern is already inconsistent.
-
-ChillSharp pushes the system in the opposite direction: entities and queries plug into the same runtime model, so growth is more uniform by default.
-
-That uniformity helps both:
-
-- human maintainers reviewing AI-produced changes
-- AI tools reasoning over the codebase with less ambiguity
-
-### 4. Smaller program payload for AI tools
-
-When a project relies on many custom CRUD controllers, DTO classes, mapping layers, and repetitive endpoint definitions, AI needs more repository context to make a safe change.
-
-That increases:
-
-- token usage
-- latency
-- cost
-- the chance that the model misses one of the duplicated layers
-
-ChillSharp reduces this burden because much of the repetitive transport logic is already handled by the framework runtime.
-
-In practice this means an AI task can often be solved by reading and changing:
-
-- one entity
-- one query
-- one validation rule
-- one permission definition
-
-instead of a long chain of related files.
-
-### 5. Lower pressure for continuous large-scale refactoring
-
-Without a model-driven framework, teams often ask AI to keep refactoring a growing list of:
-
-- endpoints
-- controllers
-- DTOs
-- validators
-- mappers
-- permission checks
-
-That is expensive and fragile. It also encourages broad automated rewrites that may not deliver business value.
-
-ChillSharp reduces the need for that style of maintenance because the generic CRUD/query surface is already centralized.
-
-That has practical benefits:
-
-- lower AI token consumption
-- fewer broad refactors across repetitive files
-- less review effort for generated code
-- lower compute usage for the same feature work
-
-If you care about both engineering efficiency and energy efficiency, this is one of the strongest arguments for using a uniform runtime instead of a large amount of repeated endpoint boilerplate.
-
-## What ChillSharp Is Good At In AI Workflows
-
-ChillSharp is a good fit when you want AI to help with:
-
-- extending domain entities
-- adding validation rules
-- adding query capabilities
-- exposing model changes through an existing generic API surface
-- keeping permissions and metadata closer to the model
-
-This is usually a better fit than asking AI to repeatedly generate large sets of CRUD infrastructure code.
-
-## What ChillSharp Does Not Solve
-
-ChillSharp does not remove the need for engineering review. In particular, you still need to verify:
-
-- business rules are correct
-- authorization rules are correct
-- exposed properties are intentional
-- model changes do not break consumers
-- AI-generated lifecycle logic is actually safe
-
-ChillSharp reduces duplication and drift. It does not remove the need for judgment.
-
-## Recommended Positioning
-
-If you want a short and defensible way to describe this in documentation or architecture notes, use something like:
-
-"ChillSharp helps AI-assisted development by centralizing repetitive API mechanics into a model-driven runtime. This reduces accidental interface drift, keeps endpoint behavior more uniform, and lowers the amount of code and repository context that AI tools must generate and maintain."
-
-## Practical Checklist
-
-If you want to use ChillSharp as an AI-friendly backend architecture, the baseline is:
-
-1. keep business entities and queries as the main place where feature behavior is defined
-2. use `[ChillProperty]` consistently so the DTO and validation surface remains intentional
-3. prefer `OnValidation()` and lifecycle hooks over ad-hoc controller logic
-4. avoid reintroducing repetitive custom CRUD endpoints unless there is a real need
-5. review model changes carefully because a model-driven surface can affect multiple client operations at once
-6. keep permissions and authentication aligned with the same model-driven approach
-
-## Related Documents
-
-- [../README.md](../README.md)
-- [../RegisterContext.md](../RegisterContext.md)
-- [../ValidationModel/README.md](../ValidationModel/README.md)
-- [../PermissionModel/README.md](../PermissionModel/README.md)
-- [../AuthenticationModel/README.md](../AuthenticationModel/README.md)
-- [../ClientGeneration/README.md](../ClientGeneration/README.md)

package/doc/AttachmentModel/README.md

@@ -1,173 +0,0 @@
-# Attachment Module
-
-Versione italiana: [Italiano](../it/AttachmentModel/README.md)
-
-
-`ChillSharp.Attachment` adds a built-in attachment entity plus upload and download endpoints backed by a filesystem archive.
-
-## What It Adds
-
-- `Attachment` Chill entity persisted in the `attachment` table
-- generic Chill CRUD support for attachment metadata
-- `GET /api/chill-attachment/attachment/download?guid=...`
-- `POST /api/chill-attachment/attachment/upload`
-
-Because `Attachment` is a real `ChillEntity`, it is also exposed through schema discovery and can be managed through the standard Chill CRUD endpoints once the host `DbContext` implements `IChillAttachmentDbContext`.
-
-The module also exposes an `AttachmentQuery` Chill query type, which client helpers can use to list attachments linked to a target entity.
-
-## Register The Module
-
-Add the module model to your context and expose the `DbSet`:
-
-```csharp
-using ChillSharp.Attachment;
-using ChillSharp.Attachment.Model;
-
-public class AppDbContext : DbContext, IChillContext, IChillAttachmentDbContext
-{
-    public DbSet<Attachment> Attachments => Set<Attachment>();
-
-    protected override void OnModelCreating(ModelBuilder modelBuilder)
-    {
-        base.OnModelCreating(modelBuilder);
-        modelBuilder.AddChillAttachmentModel();
-    }
-
-    public string GetChillTypePrefix() => "MyApp.Data";
-}
-```
-
-When the context implements `IChillAttachmentDbContext`, `services.AddChillApi<AppDbContext>()` automatically registers the attachment endpoints.
-
-## Archive Root Configuration
-
-The module reads the archive root from:
-
-- startup options via `services.Configure<ChillAttachmentOptions>(...)`
-- environment variable `CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT`
-
-Example:
-
-```csharp
-builder.Services.Configure<ChillAttachmentOptions>(options =>
-{
-    options.ArchiveRoot = "/srv/chill/attachments";
-});
-```
-
-Or through environment:
-
-```env
-CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT=/srv/chill/attachments
-```
-
-## Archive Layout
-
-Files are stored under the configured archive root using:
-
-```csharp
-public static string BuildAttachmentPath(
-    string archiveRoot,
-    string attachToChillType,
-    Guid id,
-    string extension,
-    DateTime createdAtUtc)
-```
-
-The resulting layout is:
-
-```text
-{archiveRoot}/{attachToChillType}/{year}/{guid[0..2]}/{guid[2..4]}/{guid}{extension}
-```
-
-Example:
-
-```text
-/srv/chill/attachments/Post/2026/ab/cd/abcd1234....pdf
-```
-
-## Upload Endpoint
-
-`POST /api/chill-attachment/attachment/upload`
-
-Multipart form fields:
-
-- `attachToChillType`
-- `attachToGuid`
-- `title`
-- `description`
-- `public`
-- one or more `file` parts
-
-For each uploaded file the module:
-
-1. creates an `Attachment` Chill entity through `ChillEngine`
-2. stores the physical file in the archive
-3. returns the created attachment DTO payload
-
-## Download Endpoint
-
-`GET /api/chill-attachment/attachment/download?guid={attachmentGuid}`
-
-Behavior:
-
-- loads the `Attachment` entity from the database
-- resolves the archived file path
-- returns the file using the stored original filename and mime type
-- allows anonymous download when `Public == true`
-- requires an authenticated user when `Public == false`
-
-## Client Helpers
-
-### `.NET`
-
-`ChillSharp.Client` now includes attachment helpers:
-
-```csharp
-var post = new ChillDtoEntity
-{
-    Guid = postGuid,
-    ChillType = "Model.Post"
-};
-
-var uploaded = await client.UploadAttachmentAsync(
-    post,
-    File.ReadAllBytes("contract.pdf"),
-    "contract.pdf",
-    "application/pdf",
-    title: "Signed contract",
-    description: "Customer-facing version",
-    isPublic: false);
-
-var attachments = await client.GetAttachmentsAsync(post);
-var fileBytes = await client.DownloadAttachmentAsync(uploaded[0]);
-```
-
-Available overloads cover:
-
-- upload from file path
-- upload from `byte[]`
-- upload from `Stream`
-- download by attachment `Guid`
-- download by attachment `ChillDtoEntity`
-
-### TypeScript / Angular / React / Vue / Python
-
-The generic client libraries under `extra-libs/` expose matching helpers:
-
-- TypeScript: `uploadAttachment()`, `uploadAttachments()`, `getAttachments()`, `downloadAttachment()`
-- Angular: same helpers through `ChillSharpNgClient` as `Observable` wrappers
-- React and Vue: same helpers through the raw client returned by `useChillSharpClient()`
-- Python: `upload_attachment()`, `upload_attachments()`, `get_attachments()`, `download_attachment()`
-
-## Generic CRUD
-
-Attachment metadata remains available through the standard Chill endpoints:
-
-- `POST /api/chill/create`
-- `POST /api/chill/find`
-- `POST /api/chill/update`
-- `POST /api/chill/delete`
-
-Deleting an attachment through ChillSharp also removes the archived file from disk.

package/doc/AuthenticationModel/README.md

@@ -1,213 +0,0 @@
-# ChillSharp Authentication And Authorization
-
-Versione italiana: [Italiano](../it/AuthenticationModel/README.md)
-
-This document covers the auth module at a reference level. For a guided setup, keep using [doc/HowTo/03-authentication.md](../HowTo/03-authentication.md).
-
-## Module Split
-
-`ChillSharp.Auth` exposes two related but distinct concerns:
-
-- account authentication
-  ASP.NET Core Identity-backed register, login, refresh, password-change, and password-reset flows
-
-- authorization management
-  auth users, roles, role assignments, permission rules, and permission evaluation
-
-## Account Endpoints
-
-Registered through:
-
-```csharp
-builder.Services.AddChillAuthIdentityApi<AppDbContext, IdentityUser>();
-```
-
-Typical routes:
-
-- `/api/chill-auth/account/register`
-- `/api/chill-auth/account/login`
-- `/api/chill-auth/account/refresh`
-- `/api/chill-auth/account/change-password`
-- `/api/chill-auth/account/request-password-reset`
-- `/api/chill-auth/account/reset-password`
-
-These are the routes used internally by `ChillSharpClient`.
-
-`RegisterAuthIdentityRequest` also supports:
-
-- `DisplayName`
-- `DisplayCultureName`
-- `CreateChillAuthUser`
-
-When `CreateChillAuthUser` is enabled and `DisplayCultureName` is provided, the linked `AuthUser` is automatically preset with:
-
-- `DisplayCultureName`
-- `DisplayTimeZone`
-- `DisplayDateFormat`
-- `DisplayNumberFormat`
-
-The server resolves those defaults from the selected culture by using a best-effort time-zone mapping plus the culture date and number separators.
-
-## Authorization Management Endpoints
-
-Registered through:
-
-```csharp
-builder.Services.AddChillAuthApi<AppDbContext>();
-```
-
-Typical route groups:
-
-- `/api/chill-auth/users`
-- `/api/chill-auth/roles`
-- `/api/chill-auth/permissions`
-
-These endpoints manage:
-
-- `AuthUser`
-- `AuthRole`
-- `AuthUserRole`
-- `AuthPermissionRule`
-- permission evaluation results
-
-`AuthUser` now also carries optional UI display preferences:
-
-- `DisplayCultureName`
-- `DisplayTimeZone`
-- `DisplayDateFormat`
-- `DisplayNumberFormat`
-
-`AuthUser` and `AuthRole` also carry:
-
-- `MenuHierarchy`
-
-`MenuHierarchy` is used by the schema menu endpoints to filter which menu nodes are visible to the current user.
-
-- values can be single codes or comma-separated lists
-- user and active role values are merged before filtering
-- `*` means full menu access
-- any other value works as a prefix match, for example `SECTION-A` allows nodes whose menu hierarchy starts with `SECTION-A`
-- an empty merged menu hierarchy set means no menu access
-
-For the full menu-tree model and endpoint behavior, see [MenuGuide/README.md](../MenuGuide/README.md).
-
-## Token Lifetimes
-
-ChillSharp auth account endpoints issue protected bearer access tokens and refresh tokens. These access tokens are not JWTs, but they are used in the same `Authorization: Bearer ...` header shape.
-
-Default lifetimes:
-
-- access token: 20 minutes
-- refresh token: 14 days
-
-Built-in environment variables:
-
-- `CHILLSHARP_AUTH_ACCESS_TOKEN_MINUTES`
-  Positive integer number of minutes before an access token expires.
-- `CHILLSHARP_AUTH_REFRESH_TOKEN_DAYS`
-  Positive integer number of days before a refresh token expires.
-
-These variables are read by `ChillAuthIdentityApiOptions` and `ChillIdentityApiOptions` when the options object is created. Explicit code configuration still wins:
-
-```csharp
-builder.Services.AddChillAuthIdentityApi<AppDbContext, IdentityUser>(options =>
-{
-    options.AccessTokenLifetime = TimeSpan.FromMinutes(30);
-    options.RefreshTokenLifetime = TimeSpan.FromDays(7);
-});
-```
-
-## Context Requirements
-
-The host context must:
-
-- implement `IChillAuthDbContext`
-- include `modelBuilder.AddChillAuthModel()`
-
-For Identity-backed accounts, the context must also be a valid EF store for ASP.NET Core Identity, typically:
-
-```csharp
-public class AppDbContext : IdentityDbContext<IdentityUser>, IChillContext, IChillAuthDbContext
-{
-}
-```
-
-## Root User Bootstrap
-
-`AddChillAuthIdentityApi(...)` can bootstrap a root account on startup.
-
-Supported configuration:
-
-- direct options in code
-- environment variables
-
-Default environment variables:
-
-- `CHILLSHARP_AUTH_ROOT_USERNAME`
-- `CHILLSHARP_AUTH_ROOT_PASSWORD`
-- `CHILLSHARP_AUTH_ROOT_EMAIL`
-- `CHILLSHARP_AUTH_ROOT_DISPLAY_NAME`
-
-When enabled, the bootstrap flow can also create the linked ChillSharp `AuthUser` with permission-management access.
-
-## Permission Management Access
-
-Being authenticated is not enough to manage the auth module.
-
-Auth-management endpoints require a ChillSharp auth user with permission-management rights, typically:
-
-- `CanManagePermissions = true`
-
-This is the critical bootstrap problem for a clean database:
-
-- the first registered Identity user may exist
-- the linked `AuthUser` may exist
-- but no one may yet have rights to manage roles and permissions
-
-That is why root-user bootstrap or another trusted setup path matters.
-
-## Client Usage
-
-Use the normal Chill base URL:
-
-```csharp
-var client = new ChillSharpClient("http://localhost:5000/api/chill");
-```
-
-`ChillSharpClient` automatically switches to `/api/chill-auth/...` for auth methods.
-
-Examples:
-
-- `RegisterAuthAccount`
-- `LoginAuthAccount`
-- `RefreshAuthAccount`
-- `ChangeAuthPassword`
-- `CreateAuthRole`
-- `CreateAuthPermissionRule`
-- `EvaluateAuthEntityPermission`
-
-User list and user detail payloads also expose:
-
-- `DisplayCultureName`
-- `DisplayTimeZone`
-- `DisplayDateFormat`
-- `DisplayNumberFormat`
-
-## Token Handling
-
-`ChillSharpClient` stores:
-
-- access token
-- refresh token
-
-If a refresh token is present, the client can renew the access token automatically during later authenticated calls.
-
-## Relationship With The Permission Model
-
-The exact permission-resolution rules are documented separately in:
-
-- [PermissionModel/README.md](../PermissionModel/README.md)
-
-Use that document for the precedence and scope model. Use this one for registration and runtime auth flow.
-
-