Merge pull request #25888 from abpframework/salihozkara/lowcode-formula-docs

docs: document Low-Code formula properties

docs/en/low-code/expression-language.md

@@ -0,0 +1,134 @@
+```json
+//[doc-seo]
+{
+    "Description": "Reference for the provider-safe ABP Low-Code expression language used by virtual calculated properties and formula backfills."
+}
+```
+
+# Low-Code Expression Language
+
+The Low-Code expression language is a provider-safe scalar profile used by virtual calculated properties and by the one-time **Formula** option for existing-data backfill. Its syntax is intentionally familiar to Power Fx users, but it is a smaller language designed for server validation and database-provider translation.
+
+Expressions are not JavaScript. They cannot contain arbitrary code, SQL, network calls, browser APIs, side effects, or unsupported Power Fx table and record operations.
+
+An expression can contain up to 4096 characters.
+
+> **Preview:** The language profile is preview functionality. The supported syntax and function set may change before general availability.
+
+## Values and field references
+
+Use invariant numeric literals, quoted strings, Boolean values, and date constructors. Reference a property by name:
+
+```text
+UnitPrice * Quantity
+If(IsActive, "Enabled", "Disabled")
+Date(2026, 8, 4)
+```
+
+Property and local names that are not simple identifiers can be enclosed in single quotes. Escape a single quote by doubling it:
+
+```text
+'Unit Price' * Quantity
+'Manager''s Price' * Quantity
+```
+
+Names and function names are case-insensitive. Fields may be JSON-backed or mapped to database columns.
+
+### Related fields
+
+Use dot notation to traverse a configured foreign key and read a scalar field from the related record:
+
+```text
+CustomerId.CreditLimit
+If(CustomerId.IsPreferred, Amount * 90%, Amount)
+```
+
+Related paths may also contain quoted identifiers. The Designer loads the available fields for each relationship level and applies the backend's configured maximum traversal depth. Missing related values produce a blank result where the expression is nullable.
+
+## Operators
+
+| Purpose | Operators and forms |
+| --- | --- |
+| Arithmetic | `+`, `-`, `*`, `/` |
+| Comparison | `=`, `==`, `<>`, `!=`, `<`, `<=`, `>`, `>=` |
+| Logical | `And(a, b, ...)`, `Or(a, b, ...)`, `Not(a)`, `&&`, `||`, `!` |
+| Text concatenation | `&` |
+| Percentage | `10%` (equivalent to `10 / 100`) |
+
+`<>` and `!=` are equivalent not-equal operators. `=` and `==` are equivalent equality operators. `%` is the postfix percentage operator, not a modulo operator. Use parentheses when combining operations so the intended precedence is explicit.
+
+Division returns a nullable Decimal result because division by zero produces blank rather than forcing client-side evaluation.
+
+## Functions
+
+The current scalar profile supports these functions:
+
+| Category | Functions |
+| --- | --- |
+| Conditional and blank values | `If(condition, trueValue, falseValue)`, `Coalesce(value, fallback)`, `IsBlank(value)` |
+| Logical | `And(condition1, condition2, ...)`, `Or(condition1, condition2, ...)`, `Not(condition)` |
+| Numeric | `Abs(number)`, `Round(number, places)`, `Min(left, right)`, `Max(left, right)` |
+| Text | `Lower(text)`, `Upper(text)`, `Trim(text)`, `Len(text)`, `Left(text, length)`, `Right(text, length)`, `Mid(text, start[, length])` |
+| Date and time | `Year(value)`, `Month(value)`, `Day(value)`, `Date(year, month, day)`, `DateTime(year, month, day, hour, minute, second[, millisecond])` |
+
+Examples:
+
+```text
+If(Len(Name) > 5, "Long", "Short")
+Coalesce(Discount, 0)
+Round(UnitPrice * Quantity, 2)
+FirstName & " " & LastName
+Mid(ProductCode, 2, 3)
+```
+
+`Round` uses midpoint-away-from-zero semantics. `Mid` uses a one-based start position. `Date` and `DateTime` require literal numeric components in the provider-neutral profile. Numeric and date literals use invariant syntax; browser and database locale settings do not change their meaning.
+
+Functions from the full Power Fx language that are not listed here are rejected. For example, `Floor`, `Ceiling`, `Concat`, and `Substring` are not aliases for the supported scalar functions.
+
+## Local values with `With`
+
+Use `With` to define immutable local values and avoid repeating an expression:
+
+```text
+With(
+  {
+    subtotal: UnitPrice * Quantity,
+    rebate: Coalesce(Discount, 0)
+  },
+  If(subtotal > 100, Round(subtotal - rebate, 2), subtotal)
+)
+```
+
+A `With` record supports up to 16 bindings, and `With` expressions can be nested up to 8 levels. A local name must not collide with a property on the current entity. Bindings in the same record do not see one another; nest another `With` when a later value must use an earlier local.
+
+## Where expressions run
+
+For a calculated property, the expression is expanded into the EF Core query. It can therefore participate in provider-side filtering, sorting, paging, count, projection, grouping, and supported aggregates without creating a physical column or loading the complete table into memory.
+
+For an ordinary property mapping that uses **Formula** existing-data backfill, the same scalar profile is compiled into a provider-side update that initializes existing rows once. The mapped property then stores the result; this is separate from a virtual calculated property.
+
+During JSON-to-database mapping, use `Self` to read the property's current JSON value before it is moved to the database column:
+
+```text
+Coalesce(Self, "Unknown")
+Self & " migrated"
+```
+
+Related-record aggregates are not written inside a formula expression. Create a [Rollup Property](formula-properties.md#create-a-rollup-property) for `Count`, `Sum`, `Average`, `Min`, or `Max` over related records.
+
+## Validation errors
+
+The Designer validates syntax, field and related-field references, function arity and argument types, inferred result type, dependency cycles, server-only exposure, and translation by the active database provider. Validation covers transitive calculated dependencies, not only the expression currently being edited.
+
+Common errors include:
+
+* unknown fields or functions
+* incompatible branch or result types
+* a local name that collides with an entity property
+* a circular formula or rollup dependency
+* a related path that exceeds backend query capabilities
+* an operation that the active provider cannot translate
+
+Provider translation failure is a validation error. The runtime does not fall back to evaluating the entire entity set in application memory.
+
+See [Calculated and Rollup Properties](formula-properties.md) for the Designer workflows and query behavior.

docs/en/low-code/formula-properties.md

@@ -0,0 +1,102 @@
+```json
+//[doc-seo]
+{
+    "Description": "Create virtual formula and rollup properties in the ABP Low-Code System with provider-translated expressions and related-record aggregates."
+}
+```
+
+# Calculated and Rollup Properties
+
+Calculated properties are server-authoritative, virtual properties in the Low-Code entity model. They are evaluated as part of the database query and do not create physical database columns.
+
+The Designer supports two kinds of calculated property:
+
+* **Calculated Property** evaluates a scalar formula from fields on the current record, other calculated properties, or fields reached through a foreign key.
+* **Rollup Property** aggregates records from an entity that has a foreign key to the current entity.
+
+Both kinds can participate in filtering, sorting, paging, count, projection, grouping, and supported aggregates while the work remains in the database provider. The complete entity set is not loaded into application memory to calculate the values.
+
+> **Preview:** Calculated properties, rollups, and the expression profile are preview features. Supported operations and provider translation may change before general availability.
+
+## Availability
+
+Calculated and rollup properties can be authored in a writable Runtime JSON-backed layer that supports direct model changes. The corresponding commands are disabled when the selected Designer layer does not support them.
+
+## Create a calculated property
+
+In the Low-Code Designer:
+
+1. Open **Data**, select an entity, and open its **Properties** tab.
+2. Open **Add Property** and select **Calculated Property**.
+3. Enter the property name and an optional display name.
+4. Enter an expression such as `Round(UnitPrice * Quantity, 2)`.
+5. Review the inferred result type and validation result, then select **Create Calculated Property**.
+
+The result type is inferred from the expression. Supported property types are String, Int, Long, Decimal, Money, Boolean, Date, and DateTime. Decimal and Money results can also define display precision, and Money results can define a currency symbol.
+
+Formula properties may use both JSON-backed and database-mapped scalar fields. Use dot notation to read a scalar field through a foreign key:
+
+```text
+CustomerId.CreditLimit
+Round(CustomerId.CreditLimit - CurrentBalance, 2)
+```
+
+The formula editor offers fields, related fields, local values, and supported functions as suggestions. See the [Low-Code Expression Language](expression-language.md) reference for the complete scalar syntax.
+
+Client applications cannot set a calculated property. Enable **Server only** when the result must also be omitted from client-facing metadata and responses. A client-visible formula cannot expose a server-only dependency; a server-only formula may use server-only fields.
+
+## Create a rollup property
+
+A rollup evaluates a correlated aggregate over related records. For example, an `Order` can expose the sum of `OrderItem.LineTotal` values when `OrderItem.OrderId` is a foreign key to `Order`.
+
+`Sum` is a rollup operation, not a function that can be written inside a scalar formula. The relationship is evaluated in the reverse direction: the source entity contains the foreign key that points to the entity receiving the rollup.
+
+1. Open **Add Property** and select **Rollup Property**.
+2. Select the **Source Entity** that contains the related records.
+3. Select the **Relation Field** whose foreign key points to the current entity.
+4. Select an operation: `Count`, `Sum`, `Average`, `Min`, or `Max`.
+5. For every operation except `Count`, select the **Value Field**.
+6. Review validation and select **Create Rollup Property**.
+
+| Operation | Value field | Result |
+| --- | --- | --- |
+| `Count` | Not used | Long |
+| `Sum` | Int, Long, Decimal, or Money | Preserves a compatible numeric range |
+| `Average` | Int, Long, Decimal, or Money | Decimal, or Money for a Money value |
+| `Min` / `Max` | String, Int, Long, Decimal, Money, Boolean, Date, or DateTime | Preserves a compatible scalar type |
+
+A rollup value may be a normal field or a formula property, but it cannot be another rollup. Formulas can reference other calculated properties, including rollup results, and the complete dependency graph is validated for cycles and provider translation.
+
+## Storage and query behavior
+
+Calculated and rollup properties always remain virtual:
+
+* `isMappedToDbField` is false.
+* Values are not stored in JSON or in a physical column.
+* No schema migration, synchronization job, or existing-data backfill is required.
+* Required, unique, default-value, and client-write settings do not apply.
+
+At query time, the EF Core provider expands formulas into SQL-translatable expressions and rollups into correlated aggregate expressions. Calculated dependencies are expanded recursively. Calculations that are not needed by search, filtering, or sorting can be evaluated after page selection while still remaining provider-side.
+
+This is different from the one-time **Formula** option used to backfill an ordinary property while mapping it to a database field. That workflow writes existing rows; a calculated property remains virtual and is evaluated from current data whenever it is queried.
+
+## Validation and dependency safety
+
+Before a calculated property is saved, the Designer validates:
+
+* syntax, field paths, functions, and argument types
+* inferred result type and display metadata
+* direct and transitive dependencies
+* circular dependencies across formulas and rollups
+* server-only dependency exposure
+* translation by the active database provider
+
+Saving publishes the calculated metadata only after the complete affected dependency closure passes provider validation. Renaming or deleting fields that are still referenced is guarded so an existing calculation is not silently broken.
+
+Provider-specific translation remains authoritative. An expression that is syntactically valid but cannot be translated by the active provider is rejected instead of falling back to full-table client-side evaluation.
+
+## Current limitations
+
+Formula expressions are scalar. They do not contain arbitrary aggregate subqueries; use a Rollup Property for a supported related-record aggregate. Arbitrary SQL, JavaScript, network calls, browser APIs, side effects, and unsupported Power Fx table or record operations are not allowed.
+
+Related-field access must follow configured foreign keys and stay within the query capability exposed by the backend. Rollups require a source-side Guid foreign key that points to the entity receiving the rollup.

docs/en/low-code/index.md

@@ -113,6 +113,8 @@ The screens below follow that common designer flow from data to page setup to fo
 
 ![Form setup in the designer](images/designer-forms.png)
 
+For virtual fields calculated from the current record, related records, or related-record aggregates, see [Calculated and Rollup Properties](formula-properties.md). For the provider-safe scalar syntax used by calculated properties and formula backfills, see the [Low-Code Expression Language](expression-language.md) reference.
+
 ## React Runtime
 
 React runtime pages are generated from the same metadata. The examples below show a generated data grid and its create form. The same runtime can render kanban, calendar, gallery, standalone form, and dashboard page definitions.