@chill-sharp/ui-core 1.1.12

package/doc/MenuGuide/README.md

@@ -0,0 +1,49 @@
+# ChillSharp Menu Guide
+
+Versione italiana: [Italiano](../it/MenuGuide/README.md)
+
+ChillSharp can store an application menu tree in the schema module rather than hard-coding it in the frontend. Menu management is exposed under `/api/chill-schema`.
+
+## Menu item model
+
+Each item has a stable `Guid`, `PositionNo`, `Title`, optional `Description`, optional `Parent`, `ComponentName`, optional `ComponentConfigurationJson`, and optional `MenuHierarchy`.
+
+- `Parent = null` identifies a root item.
+- Children reference their direct parent.
+- Siblings sort by `PositionNo`, then `Title`, then `Guid`.
+- `ComponentName` identifies the client component to open, for example `CRUD`.
+
+```json
+{
+  "Guid": "00000000-0000-0000-0000-000000000000",
+  "PositionNo": 10,
+  "Title": "Posts",
+  "Description": "Open the post management screen",
+  "Parent": null,
+  "ComponentName": "CRUD",
+  "ComponentConfigurationJson": "{\"ChillType\":\"Model.Post\"}",
+  "MenuHierarchy": "CONTENT.POSTS"
+}
+```
+
+## Endpoints
+
+- `GET /api/chill-schema/get-menu` returns root items.
+- `GET /api/chill-schema/get-menu?parentGuid={guid}` returns one item's direct children.
+- `POST /api/chill-schema/set-menu` creates an item when its `Guid` is empty or updates the matching item otherwise. A supplied parent must already exist, and an item cannot be its own parent. Updating an existing item with an empty `MenuHierarchy` preserves its stored value.
+- `DELETE /api/chill-schema/delete-menu?menuItemGuid={guid}` deletes the selected item and its complete descendant subtree.
+
+Load the tree one level at a time: request roots first, then request children as a branch is expanded.
+
+## Visibility with `MenuHierarchy`
+
+`MenuHierarchy` accepts one code or comma-separated codes. ChillSharp merges the comma-separated values from the current user and all active roles into an effective prefix set.
+
+- `*` grants access to every menu item.
+- With no effective prefix, no items are returned, including items whose hierarchy is empty.
+- With at least one effective prefix, items with an empty hierarchy are visible.
+- A populated item hierarchy is visible when it starts with at least one effective prefix.
+
+For example, `CONTENT` grants `CONTENT`, `CONTENT.POSTS`, and `CONTENT.REPORTS.MONTHLY`, but not `ADMIN`. An item can expose more than one branch with `CONTENT, REPORTS.MONTHLY`.
+
+Use stable dot-separated codes such as `ADMIN.USERS`, `CONTENT.POSTS`, and `REPORTS.MONTHLY`.

package/doc/ModelPreparation.md

@@ -0,0 +1,255 @@
+# Preparing A Model For ChillSharp
+
+Versione italiana: [Italiano](./it/ModelPreparation.md)
+
+This document describes the model-side requirements for exposing an EF Core domain model through ChillSharp.
+
+## Goals
+
+After preparation, your model can:
+
+- be activated dynamically by Chill type name
+- be queried and mutated through Chill DTOs
+- expose schema metadata for clients
+- participate in audit-field maintenance
+- use context-specific label cultures and current-user information
+
+## 1. Implement `IChillContext`
+
+Your `DbContext` must implement `IChillContext`.
+
+Required behavior:
+
+```csharp
+public class AppDbContext : DbContext, IChillContext
+{
+    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
+
+    public string GetChillTypePrefix()
+    {
+        return "MyCompany.MyProduct.Data";
+    }
+
+    public string GetPrimaryCultureName()
+    {
+        return "en-US";
+    }
+
+    public string GetSecondaryCultureName()
+    {
+        return "it-IT";
+    }
+
+    public string GetCurrentUserName()
+    {
+        return Environment.UserName;
+    }
+}
+```
+
+### What each method is used for
+
+- `GetChillTypePrefix()`
+  Expands short Chill type names such as `Model.Blog` into fully qualified CLR types.
+
+- `GetPrimaryCultureName()`
+  Defines which culture should use `PrimaryLanguageLabel`.
+
+- `GetSecondaryCultureName()`
+  Defines which culture should use `SecondaryLanguageLabel`.
+
+- `GetCurrentUserName()`
+  Feeds entity audit tracking.
+
+Each context instance can return different values. This is important in multi-tenant or multi-module hosts where more than one Chill context can exist with different language or user settings.
+
+## 2. Use `ChillEntity` For Exposed Entities
+
+The recommended pattern is to inherit from `ChillSharp.EF.ChillEntity`.
+
+```csharp
+using ChillSharp.Annotations;
+using ChillSharp.EF;
+using System.ComponentModel.DataAnnotations;
+
+[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 title",
+        SecondaryLanguageLabel: "Titolo del blog")]
+    public string Title { get; set; } = string.Empty;
+
+    [ChillProperty(
+        UniquePropertyKeyString: "A18E7754-D8F7-45FE-B8A8-EA762A4EC9E6",
+        PrimaryLanguageLabel: "Blog url",
+        SecondaryLanguageLabel: "Url del blog")]
+    public string Url { get; set; } = string.Empty;
+
+    public override string GetLabel(IChillContext context) => Title;
+}
+```
+
+`ChillEntity` already provides:
+
+- `Guid`
+- `Label`
+- `ShortLabel`
+- `FullTextContent`
+- `Checksum`
+- `LastUpdateUser`
+- `LastUpdate`
+- `LastUpdateUtcOffset`
+
+## 3. Annotate Exposed Properties
+
+ChillSharp only treats properties decorated with `[ChillProperty]` as part of the Chill metadata surface.
+
+That affects:
+
+- DTO mapping
+- schema generation
+- checksum calculation
+- label metadata
+
+If a property is not marked with `[ChillProperty]`, it is not part of the standard Chill property surface.
+
+## 4. Understand Lifecycle Hooks
+
+`ChillEngine` drives entity lifecycle methods.
+
+### Create flow
+
+On create, ChillSharp runs:
+
+1. `OnCreate(context)`
+2. `OnUpdate(context)`
+3. save
+4. internal audit update + `OnAfterUpdate(context)`
+5. recompute `Label`, `ShortLabel`, `FullTextContent`
+6. save
+
+### Update flow
+
+On update, ChillSharp runs:
+
+1. `OnUpdate(context)`
+2. save
+3. internal audit update + `OnAfterUpdate(context)`
+4. recompute `Label`, `ShortLabel`, `FullTextContent`
+5. save
+
+### Delete flow
+
+On delete, ChillSharp runs:
+
+1. `OnDelete(context)`
+2. save delete
+3. `OnAfterDelete(context)`
+4. save
+
+## 5. Audit-Field Behavior
+
+`ChillEntity` automatically maintains:
+
+- `Checksum`
+- `LastUpdateUser`
+- `LastUpdate`
+- `LastUpdateUtcOffset`
+
+The checksum is computed from all `[ChillProperty]` values except the audit fields themselves.
+
+Notes:
+
+- scalar values are serialized using invariant culture
+- referenced `IChillEntity` values contribute their `Guid`
+- collections are flattened into a deterministic string sequence before summing bytes
+
+### Why overriding `OnAfterUpdate()` is safe
+
+`ChillEntity` uses an explicit interface implementation for `IChillEntity.OnAfterUpdate(...)`.
+
+`ChillEngine` calls `OnAfterUpdate()` through the interface, so the runtime flow is:
+
+1. update audit fields
+2. call the derived class override of `public virtual OnAfterUpdate(...)`
+
+This means derived entities get a clean override surface while the base audit logic cannot be skipped accidentally.
+
+## 6. Labels And Cultures
+
+`PrimaryLanguageLabel` and `SecondaryLanguageLabel` are not just comments. They are interpreted using the active UI culture and the active `IChillContext`.
+
+Current behavior:
+
+- if the current UI culture matches the context secondary culture, ChillSharp prefers `SecondaryLanguageLabel`
+- if it matches the primary culture, ChillSharp prefers `PrimaryLanguageLabel`
+- otherwise it falls back to primary first, then secondary
+
+This logic is used when schema metadata is generated.
+
+## 7. Queries
+
+Queries should implement `IChillQuery<IChillEntity>` and can also be decorated with `ChillEntityAttribute` and `ChillPropertyAttribute`.
+
+That allows query schemas to be generated exactly like entity schemas.
+
+## 8. Schema Persistence Readiness
+
+If you want persisted schema metadata and schema caching, your context must also implement `IChillSchemaDbContext` and include:
+
+```csharp
+modelBuilder.AddChillSchemaModel();
+```
+
+Then register:
+
+```csharp
+builder.Services.AddChillSchema<AppDbContext>();
+```
+
+## 9. Auth Readiness
+
+If you want ChillSharp auth and permissions, your context must implement `IChillAuthDbContext` and include:
+
+```csharp
+modelBuilder.AddChillAuthModel();
+```
+
+Then register one of:
+
+```csharp
+builder.Services.AddChillAuthApi<AppDbContext>();
+builder.Services.AddChillAuthIdentityApi<AppDbContext, IdentityUser>();
+```
+
+## 10. I18n Readiness
+
+If you want localized text storage and lookup, your context must implement `IChillI18nDbContext` and include:
+
+```csharp
+modelBuilder.AddChillI18nModel();
+```
+
+Then register:
+
+```csharp
+builder.Services.AddChillI18nApi<AppDbContext>();
+```
+
+## 11. Recommendations
+
+- Prefer inheriting from `ChillEntity` instead of implementing `IChillEntity` from scratch.
+- Use stable GUIDs in `UniquePropertyKeyString` and `UniqueEntityKeyString`.
+- Mark only the properties you actually want in the Chill DTO/schema surface.
+- Keep `GetLabel()` and `GetFullTextContent()` cheap enough to run during standard CRUD flows.
+- Return a real request identity from `GetCurrentUserName()` in API hosts.
+- Keep context-specific culture settings on the context, not in static globals.
+

package/doc/PermissionModel/README.md

@@ -0,0 +1,277 @@
+# Permission Model
+
+Versione italiana: [Italiano](../it/PermissionModel/README.md)
+
+This document describes the authorization model implemented by `ChillSharp.Auth`.
+
+## Purpose
+
+The permission model is designed to answer two questions consistently:
+
+- can the current user perform an entity-level operation
+- can the current user see or modify a specific property
+
+The same model supports both:
+
+- server-side enforcement
+- client-side capability filtering
+
+## Subjects
+
+Permissions can be assigned to:
+
+- a user
+- a role
+
+A user can belong to multiple roles.
+
+## Resource Hierarchy
+
+Permissions are evaluated against a three-level hierarchy:
+
+```text
+Module -> Entity -> Property
+```
+
+### Module
+
+A module is a logical application area, for example:
+
+- `Accounting`
+- `Accounting.General`
+- `Blog`
+- `Blog.Admin`
+
+Module names can be hierarchical.
+
+### Entity
+
+An entity is a Chill entity name inside a module, for example:
+
+- `Blog`
+- `Post`
+- `AuthUser`
+
+### Property
+
+A property is a field on an entity, for example:
+
+- `Title`
+- `Author`
+- `CanManagePermissions`
+
+## Actions
+
+### Entity actions
+
+- `Query`
+- `Create`
+- `Update`
+- `Delete`
+
+### Property actions
+
+- `See`
+- `Modify`
+
+Property permissions refine an already-allowed entity operation. They do not replace entity permissions.
+
+## Effects
+
+Each rule has one effect:
+
+- `Allow`
+- `Deny`
+
+At the same evaluation level, `Deny` wins over `Allow`.
+
+## Precedence
+
+ChillSharp resolves rules in this order:
+
+1. user property rules
+2. user entity rules
+3. user module rules
+4. role property rules
+5. role entity rules
+6. role module rules
+7. default deny
+
+This combines two principles:
+
+- user rules override role rules
+- more specific rules override broader rules
+
+## How Operations Are Evaluated
+
+### Query
+
+To query an entity:
+
+1. the user must have entity `Query`
+2. each returned property must also have `See`
+
+If a property is not allowed, the server can remove, null, or mask it depending on the calling surface and implementation.
+
+### Create
+
+To create an entity:
+
+1. the user must have entity `Create`
+2. each provided property must have `Modify`
+
+### Update
+
+To update an entity:
+
+1. the user must have entity `Update`
+2. each changed property must have `Modify`
+
+### Delete
+
+To delete an entity:
+
+1. the user must have entity `Delete`
+
+Property rules do not matter for delete.
+
+## Default Security Posture
+
+The model is default-deny.
+
+If no rule grants access, access is denied.
+
+This is intentional. It prevents new entities or properties from becoming visible just because they were added to the model.
+
+## Typical Rule Examples
+
+Allow querying all blog entities in a module:
+
+```text
+Allow Query Module=Blog
+```
+
+Allow updating posts:
+
+```text
+Allow Update Module=Blog Entity=Post
+```
+
+Block edits to a sensitive property while allowing broader updates:
+
+```text
+Allow Update Module=Blog Entity=Post
+Deny Modify Module=Blog Entity=Post Property=InternalNotes
+```
+
+## Auth Management API
+
+`ChillSharp.Auth` now exposes a management-oriented API that separates:
+
+- client-side capability evaluation
+- server-side management of users, roles, and permission rules
+
+### `GET chill-auth/get-permissions`
+
+Returns the current logged-in user's authorization data as a structured payload:
+
+- the current auth user
+- the user's direct permissions
+- the user's assigned roles
+- for each assigned role, that role's permissions
+
+Clients should use this payload to evaluate capabilities locally and:
+
+- disable UI actions
+- hide fields
+- decide which editors or actions to render
+
+The old public `evaluate/*` endpoints are removed. Evaluation is now expected to happen in the client libraries or UI layer by applying the same precedence rules described in this document.
+
+### Management Endpoints Requiring `CanManagePermissions`
+
+The following endpoints are reserved for privileged users only:
+
+- `GET chill-auth/get-user-list`
+- `GET chill-auth/get-user`
+- `POST chill-auth/set-user`
+- `GET chill-auth/get-role-list`
+- `GET chill-auth/get-role`
+- `POST chill-auth/set-role`
+
+### `GET chill-auth/get-user-list`
+
+Returns the full user list in a lightweight form suitable for dropdowns and selectors.
+
+### `GET chill-auth/get-user`
+
+Returns a single user as one structured object containing:
+
+- user data
+- assigned roles
+- user-specific permissions
+
+Role permissions are not expanded here because the UI can load them from the related role payload when needed.
+
+### `POST chill-auth/set-user`
+
+Creates or updates a user with:
+
+- the full assigned role list
+- the full list of user-specific permissions
+
+The server synchronizes changes incrementally:
+
+- adds missing roles and removes deleted roles
+- adds missing permissions and removes deleted permissions
+
+It does not clear and recreate the full set blindly.
+
+### `GET chill-auth/get-role-list`
+
+Returns the full role list in a lightweight form suitable for dropdowns and selectors.
+
+### `GET chill-auth/get-role`
+
+Returns a single role as one structured object containing:
+
+- role data
+- role-specific permissions
+- users assigned to the role
+
+### `POST chill-auth/set-role`
+
+Creates or updates a role with:
+
+- the full list of role permissions
+- the full list of users assigned to the role
+
+The server synchronizes changes incrementally:
+
+- adds missing permissions and removes deleted permissions
+- adds missing user-role assignments and removes deleted assignments
+
+It does not clear and recreate the full set blindly.
+
+## Server Enforcement
+
+Clients may evaluate capabilities locally for UX purposes, but the server remains the source of truth.
+
+Entity-level server authorization continues to be enforced through the existing ChillSharp ACL integration. Management endpoints additionally require `CanManagePermissions` when the caller is authenticated.
+
+## Related Runtime Pieces
+
+The permission model is backed by:
+
+- `AuthUser`
+- `AuthRole`
+- `AuthUserRole`
+- `AuthPermissionRule`
+
+Management endpoints are exposed through `ChillSharp.Auth`.
+
+For registration and account flows, see:
+
+- [AuthenticationModel/README.md](../AuthenticationModel/README.md)
+
+