Docs update

Author: CrushBy

docs/how-to/en/How-to_Custom_React_views.md

@@ -28,7 +28,7 @@ The value form selects the renderer: a string literal matching `[A-Z][A-Za-z0-9_
 
 ### The component
 
-`OrderBoard` is a named export from a `.jsx` module under `src/main/web`; how the module is compiled and registered is covered in [How-to: Custom client JS modules](How-to_Custom_client_JS_modules.md). The examples here use JSX. For a project [without the build](How-to_Custom_client_JS_modules.md#without-the-build), ship the same component as a `.jsx` file — it is transformed on the server when served; `import` is not available there, so the component works against the platform-provided `window.React` — or write it with `React.createElement` in a plain `.js`. Either file is placed under `src/main/resources/web/init` (auto-loaded) or under `src/main/resources/web` and registered with `onWebClientInit`.
+`OrderBoard` is a named export from a `.jsx` module under `src/main/web`; how the module is compiled and registered is covered in [How-to: Custom client JS modules](How-to_Custom_client_JS_modules.md). The examples here use JSX. For a project [without the build](How-to_Custom_client_JS_modules.md#without-the-build), ship the same component as a `.jsx` file — it is transformed on the server when served; `import` and `export` are not available there, so the `export` keyword is dropped and the component works against the platform-provided `window.React` — or write it with `React.createElement` in a plain `.js`. Either file is placed under `src/main/resources/web/init` (auto-loaded) or under `src/main/resources/web` and registered with `onWebClientInit`.
 
 The component is a plain function that receives `props.data` and `props.controller`:
 

docs/how-to/en/How-to_Custom_view_controller.md

@@ -123,7 +123,7 @@ Passing a handle (`otherRow.objects`) as an FK value silently sets it to `NULL`,
 
 The format is the same in the read direction: an object property's value arrives in the data row as this same numeric id, so it can be compared with the target row's `row.key` (in a single-object group) or passed back as an FK value without conversion.
 
-If the edited property is marked `APPLY` on the form (the edit is applied at once), `changeProperty` commits the change immediately. For a simple edit from a view — a move, a resize, an in-place value edit — this is preferable to a separate server action; the server action (`exec`) stays for what a property change cannot express: creating an object (`NEW`), multi-step logic, opening a form.
+Like a user edit in the standard table, the change is made in the form's [change session](../paradigm/Change_sessions.md): the view sees the new value in `props.data` at once, while it reaches the database when the session is applied — with the Save button or an action with the [`APPLY`](../language/APPLY_operator.md) operator. If the edited property is marked `APPLY` on the form (the edit is applied at once), `changeProperty` commits the change immediately. For a simple edit from a view — a move, a resize, an in-place value edit — this is preferable to a separate server action; the server action (`exec`) stays for what a property change cannot express: creating an object (`NEW`), multi-step logic, opening a form.
 
 ```js
 // move an object to another parent and edit a primitive in one call:

docs/how-to/ru/How-to_Custom_React_views.md

@@ -28,7 +28,7 @@ DESIGN orders {
 
 ### Компонент
 
-`OrderBoard` — именованный экспорт из модуля `.jsx` в каталоге `src/main/web`; как этот модуль компилируется и регистрируется, описано в [How-to: Пользовательские клиентские JS-модули](How-to_Custom_client_JS_modules.md). Примеры здесь используют JSX. Для проекта [без сборки](How-to_Custom_client_JS_modules.md#without-the-build) поместите тот же компонент в файл `.jsx` — он преобразуется на сервере при отдаче; `import` там недоступен, поэтому компонент работает с предоставляемым платформой `window.React` — либо напишите его через `React.createElement` в обычном `.js`. Любой из этих файлов кладётся в `src/main/resources/web/init` (автозагрузка) или в `src/main/resources/web` с регистрацией через `onWebClientInit`.
+`OrderBoard` — именованный экспорт из модуля `.jsx` в каталоге `src/main/web`; как этот модуль компилируется и регистрируется, описано в [How-to: Пользовательские клиентские JS-модули](How-to_Custom_client_JS_modules.md). Примеры здесь используют JSX. Для проекта [без сборки](How-to_Custom_client_JS_modules.md#without-the-build) поместите тот же компонент в файл `.jsx` — он преобразуется на сервере при отдаче; `import` и `export` там недоступны, поэтому ключевое слово `export` опускается, а компонент работает с предоставляемым платформой `window.React` — либо напишите его через `React.createElement` в обычном `.js`. Любой из этих файлов кладётся в `src/main/resources/web/init` (автозагрузка) или в `src/main/resources/web` с регистрацией через `onWebClientInit`.
 
 Компонент — это обычная функция, получающая `props.data` и `props.controller`:
 

docs/how-to/ru/How-to_Custom_view_controller.md

@@ -123,7 +123,7 @@ controller.changeProperties(['note', 'qty'], [null, row], ['checked', 5]);
 
 В обратную сторону формат тот же: значение объектного свойства приезжает в строку данных этим же числовым id, поэтому его можно сравнить с `row.key` целевой строки (в группе с одним объектом) или передать обратно значением FK без преобразований.
 
-Если редактируемое свойство помечено на форме модификатором `APPLY` (правка применяется сразу), `changeProperty` фиксирует изменение немедленно. Для простой правки из представления — перенос, изменение размера, правка значения по месту — это предпочтительнее отдельного серверного действия; серверное действие (`exec`) остаётся для того, что правкой свойства не выражается: создания объекта (`NEW`), многошаговой логики, открытия формы.
+Как и правка пользователя в штатной таблице, изменение выполняется в [сессии изменений](../paradigm/Change_sessions.md) формы: представление сразу видит новое значение в `props.data`, а в базу данных оно попадает при применении сессии — кнопкой «Сохранить» либо действием с оператором [`APPLY`](../language/APPLY_operator.md). Если редактируемое свойство помечено на форме модификатором `APPLY` (правка применяется сразу), `changeProperty` фиксирует изменение немедленно. Для простой правки из представления — перенос, изменение размера, правка значения по месту — это предпочтительнее отдельного серверного действия; серверное действие (`exec`) остаётся для того, что правкой свойства не выражается: создания объекта (`NEW`), многошаговой логики, открытия формы.
 
 ```js
 // перенос объекта к другому родителю и правка примитива одним вызовом:

docs/paradigm/en/System_Time.md

@@ -72,7 +72,7 @@ The signatures below use the built-in time classes `DATE`, `TIME`, `DATETIME` (w
 | `subtractSeconds[DATETIME, LONG]` / `subtractSeconds[ZDATETIME, LONG]` | subtract the given number of seconds from a `DATETIME` / `ZDATETIME`, return the same class; PG `$1 - $2 * interval '1 second'`                  |
 | `subtractSeconds[TIME, TIME]` / `subtractSeconds[DATETIME, DATETIME]` / `subtractSeconds[ZDATETIME, ZDATETIME]` | difference of two same-class values in seconds as `INTEGER`, computed as the **second** argument minus the **first** (`subtractSeconds(a, b) = b - a`, positive when `b` is the later value); PG `extract(epoch from (b - a))` |
 | `daysBetweenDates[DATE, DATE]`                            | difference of two dates in days as `INTEGER`, computed as the **first** argument minus the **second** (`daysBetweenDates(a, b) = a - b`, positive when `a` is the later date); PG `$1 - $2`. Note the operand order is the opposite of `subtractSeconds` |
-| `daysInclBetweenDates[DATE, DATE]`                        | inclusive day count between two dates, counting both ends: the **second** argument minus the **first**, plus 1 (`daysInclBetweenDates(a, b) = b - a + 1`) — the opposite operand order from `daysBetweenDates[DATE, DATE]`, since it calls it with the arguments swapped |
+| `daysBetweenDatesIncl[DATE, DATE]`                        | inclusive day count between two dates, counting both ends: the **first** argument minus the **second**, plus 1 (`daysBetweenDatesIncl(a, b) = a - b + 1`) — the same operand order as `daysBetweenDates[DATE, DATE]` |
 | `secondsBetweenDates[DATETIME, DATETIME]`                 | difference of two moments in seconds as `INTEGER`, computed as the **first** argument minus the **second** (`secondsBetweenDates(a, b) = a - b`, positive when `a` is the later moment); PG `extract(epoch from $1) - extract(epoch from $2)` |
 | `dateTimeToDateTime[DATE, TIME]`                          | combines a `DATE` and a `TIME` into a `DATETIME` through a text round-trip; PG `to_timestamp(<date> \|\| <time>, 'YYYY-MM-DDHH24:MI:SS.MS')::timestamp`        |
 | `dateFromYearWeekDay[INTEGER, INTEGER, INTEGER]`          | builds a `DATE` from year, ISO-8601 week number, and ISO day of week (1 = Monday … 7 = Sunday); PG `to_date($1 \|\| ' ' \|\| $2 \|\| ' ' \|\| $3, 'IYYY IW ID')`     |

docs/paradigm/ru/System_Time.md

@@ -72,7 +72,7 @@ title: 'Time'
 | `subtractSeconds[DATETIME, LONG]` / `subtractSeconds[ZDATETIME, LONG]` | вычитают указанное число секунд из `DATETIME` / `ZDATETIME`, возвращают тот же класс; PG `$1 - $2 * interval '1 second'`                         |
 | `subtractSeconds[TIME, TIME]` / `subtractSeconds[DATETIME, DATETIME]` / `subtractSeconds[ZDATETIME, ZDATETIME]` | разность двух значений одного класса в секундах как `INTEGER`, считается как **второй** аргумент минус **первый** (`subtractSeconds(a, b) = b - a`, положительно, когда `b` — более поздняя величина); PG `extract(epoch from (b - a))` |
 | `daysBetweenDates[DATE, DATE]`                            | разность двух дат в днях как `INTEGER`, считается как **первый** аргумент минус **второй** (`daysBetweenDates(a, b) = a - b`, положительно, когда `a` — более поздняя дата); PG `$1 - $2`. Порядок операндов обратен `subtractSeconds` |
-| `daysInclBetweenDates[DATE, DATE]`                        | число дней между двумя датами с учётом обоих концов: **второй** аргумент минус **первый**, плюс 1 (`daysInclBetweenDates(a, b) = b - a + 1`) — порядок операндов обратен `daysBetweenDates[DATE, DATE]`, так как оно вызывается с переставленными аргументами |
+| `daysBetweenDatesIncl[DATE, DATE]`                        | число дней между двумя датами с учётом обоих концов: **первый** аргумент минус **второй**, плюс 1 (`daysBetweenDatesIncl(a, b) = a - b + 1`) — тот же порядок операндов, что у `daysBetweenDates[DATE, DATE]` |
 | `secondsBetweenDates[DATETIME, DATETIME]`                 | разность двух моментов в секундах как `INTEGER`, считается как **первый** аргумент минус **второй** (`secondsBetweenDates(a, b) = a - b`, положительно, когда `a` — более поздний момент); PG `extract(epoch from $1) - extract(epoch from $2)` |
 | `dateTimeToDateTime[DATE, TIME]`                          | собирает `DATETIME` из `DATE` и `TIME` через приведение текста; PG `to_timestamp(<дата> \|\| <время>, 'YYYY-MM-DDHH24:MI:SS.MS')::timestamp`                    |
 | `dateFromYearWeekDay[INTEGER, INTEGER, INTEGER]`          | собирает `DATE` по году, номеру недели ISO 8601 и дню недели ISO (1 = понедельник … 7 = воскресенье); PG `to_date($1 \|\| ' ' \|\| $2 \|\| ' ' \|\| $3, 'IYYY IW ID')` |

docs/rules/en/Rules_properties.md

@@ -47,13 +47,37 @@ title: 'Rules: properties'
    - `(+)` / `(-)` or `GROUP SUM` produces `0`
      (a zero result is returned as `NULL`).
 
-4. The assistant MUST NOT use `GROUP AGGR`
-   inside arbitrary expressions.
-
-   `GROUP AGGR` is allowed only in property definitions.
-
-   When reasoning about it, the assistant MUST treat
-   `GROUP AGGR` as `GROUP MAX`
+4. The assistant MUST NOT use `GROUP` with a `BY` block
+   (including `GROUP AGGR`) inside expressions:
+   in a type cast, in arithmetic
+   (including `(+)` / `(-)`), as an argument
+   of another property, or as an implementation
+   of an abstract property via `+=`.
+
+   Such an operator defines the parameters
+   of its result itself, so it is allowed only
+   as an entire property definition:
+   the right-hand side of a definition via `=`
+   or an inline definition in square brackets;
+   in any other position the platform raises
+   the error `BY clause in GROUP operator
+   cannot be used in expressions`.
+   To use the result in an expression,
+   the assistant SHOULD first rewrite the operator
+   without `BY`, replacing each grouping
+   with an equality condition on an outer parameter
+   (`GROUP SUM f(x) IF g(x) = y`); otherwise,
+   apply the inline form `[GROUP ... BY ...](...)`
+   to arguments or declare a separate property
+   and refer to it.
+
+   The restriction is tied specifically
+   to the `BY` block: `GROUP` without `BY`
+   takes its parameters from the outer context
+   and may be used inside expressions.
+
+   When reasoning about `GROUP AGGR`, the assistant
+   MUST treat it as `GROUP MAX`
    with an additional constraint.
 
 5. The assistant SHOULD avoid unnecessary conditions
@@ -94,6 +118,11 @@ title: 'Rules: properties'
     the name must not be changed — changing `name` is
     forbidden by a system constraint.
 
+    `name` returns the static object's canonical name —
+    `<namespace>_<Class>.<object>`, not the short identifier.
+    When the part after the dot is needed, the assistant
+    SHOULD use `basicName` from the `Utils` system module.
+
 12. Property names SHOULD be concise
     and avoid unnecessary words.
 
@@ -150,21 +179,67 @@ title: 'Rules: properties'
     to the parameters not used in the expressions;
     a mismatch in count or classes is an error.
 
+19. `MAX` and `MIN` are prefix operators over a comma-separated
+    operand list (`MAX a, b`), not infix ones: `a MAX b`
+    does not parse — the platform reports
+    `no viable alternative at input 'MAX'`.
+
+    The operand list extends as far as the expression allows,
+    so everything after the comma belongs to the operator:
+    `MAX a, b * c` is `MAX(a, b * c)`, while `x * MAX a, b`
+    is fine as it stands. Where a following operator must
+    apply to the maximum itself, the operator MUST be
+    parenthesized: `(MAX a, b) * c`.
+
+    These operators compare the operands of a single row;
+    a maximum across rows is `GROUP MAX`.
+
 ## Abstract property rules (`+=`)
 
 1. The value class of a `+=` implementation MUST fit within
    the value class declared on the abstract property; there
    is no implicit cast — an implementation with a wider
    class is rejected at server startup with a
-   "wrong value class of implementation" error.
-
-   An expression that widens the value class — above all
-   string concatenation, which sums the operands' lengths
-   (`ISTRING[326]` against a declared `ISTRING[250]`) —
-   the assistant MUST wrap in an explicit cast to the
-   declared class:
+   "wrong value class of implementation" error, whose
+   `specified` and `expected` lines name the implementation's
+   class and the declared one.
+
+   Arithmetic is what widens the class most often, and it
+   widens further than it looks:
+
+   - `+` and `-` — like `MIN` / `MAX` and the selection
+     operators — take the common ancestor, widening the whole
+     part and the scale independently, so the result can be
+     wider than either operand:
+     `NUMERIC[16,2] + NUMERIC[10,4]` is `NUMERIC[18,4]`;
+   - `*` adds both the whole parts and the scales:
+     `NUMERIC[16,2] * NUMERIC[10,4]` is `NUMERIC[26,6]`;
+   - `/` widens catastrophically: with the default settings
+     its scale is always the maximum `NUMERIC` scale (`32`),
+     so `NUMERIC[16,2] / NUMERIC[16,2]` is `NUMERIC[48,32]`.
+
+   A `GROUP` aggregate mostly keeps the class of what it
+   aggregates — a `GROUP SUM`, `GROUP MAX` or `GROUP LAST`
+   over a `NUMERIC[16,2]` is `NUMERIC[16,2]` — but it carries
+   outward whatever that expression already widened to.
+   `GROUP CONCAT` is the aggregate that widens by itself: its
+   result is a string of unlimited length (`ISTRING` against
+   a declared `ISTRING[250]`). Plain string concatenation
+   widens as well, summing the operands' lengths
+   (`ISTRING[326]` against a declared `ISTRING[250]`).
+
+   Any such expression the assistant MUST wrap in an explicit
+   cast to the declared class:
+   `f(X x) += NUMERIC[16,2](a(x) / b(x));`
    `f(X x) += ISTRING[250](a(x) + b(x));`
 
+   For operands of integer classes the cast MUST go on an
+   operand first, so that the division is not integer
+   division (see rule 16 of the property rules); the result
+   still widens to scale `32` like any other division, so
+   the outer cast is needed as well:
+   `f(X x) += NUMERIC[16,2](NUMERIC[16,2](a(x)) / b(x));`
+
 ## Ordering rules (`ORDER`)
 
 1. Where two rows can share an order key and the answer depends