cabloy 5.1.120 → 5.1.122

package/.cabloy-version

@@ -1 +1 @@
-5.1.120
+5.1.122

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 5.1.122
+
+### Features
+
+- Update functionality and dependencies.
+
+## 5.1.121
+
+### Features
+
+- Support embedded layout blocks in forms.
+
+### Improvements
+
+- Update the student selection result item component.
+- Add commerce test coverage for shipment refund race conditions.
+
 ## 5.1.120
 
 ### Features

package/cabloy-docs/frontend/form-layout-guide.md

@@ -13,8 +13,8 @@ Several APIs contain the word “layout,” but they own different concerns:
 
 | Surface                                        | Owns                                                                                                           | Does not own                                              |
 | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| `formLayout`                                   | Field placement, Grid/flow sections, groups, responsive spans, and tabs                                        | Field renderer selection, validation rules, submit policy |
-| `basic-form:blockFormLayout`                   | Resolving and rendering a structural `formLayout` tree in Cabloy Basic                                         | Page-entry or filter actions                              |
+| `formLayout`                                   | Field and renderable-block placement, Grid/flow sections, groups, responsive spans, and tabs                   | Field renderer selection, validation rules, submit policy |
+| `basic-form:blockFormLayout`                   | Resolving and rendering a structural `formLayout` tree in Cabloy Basic, including embedded renderable blocks   | Page-entry or filter action semantics                     |
 | `layout`, `formFieldLayout`, `FormFieldLayout` | One field's label and wrapper presentation: inline/block mode, icons, borders, header/footer, class, and style | Sections, Grid/flow placement, groups, or tabs            |
 
 For example, `formFieldLayout: { inline: false }` makes each field use a block-style wrapper. It does not create a grid. Pair it with `basic-form:blockFormLayout` when the fields also need structural placement.
@@ -63,7 +63,7 @@ Form Layout changes neither readonly behavior nor actions. Create, update, and v
 
 ### Filter form composition
 
-A filter uses the filter block as its host and keeps filter actions as an explicit sibling block:
+A filter uses the filter block as its host. Place Search/Reset inside the structural layout when they should participate in the same Grid or flow as filter fields:
 
 ```tsx
 ZovaRender.block('basic-page:blockFilter', {
@@ -72,16 +72,36 @@ ZovaRender.block('basic-page:blockFilter', {
     ZovaRender.block('basic-form:blockFormLayout', {
       formLayout: {
         children: [
-          /* structural nodes */
+          {
+            type: 'section',
+            layout: 'flow',
+            children: [
+              /* filter fields */
+              {
+                type: 'block',
+                block: ZovaRender.block('basic-page:blockFilterActions'),
+              },
+            ],
+          },
         ],
       },
     }),
-    ZovaRender.block('basic-page:blockFilterActions'),
   ],
 });
 ```
 
-A nonempty `blocks` list replaces `ZForm`'s automatic body and footer. Therefore a structured filter must explicitly include `basic-page:blockFilterActions`; it owns Search and Reset and keeps the filter's existing normalization and page-query handoff. See [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook#use-blocks-for-a-structural-filter-layout) for the filter ownership model.
+The renderable block node controls only structural placement. `basic-page:blockFilterActions` still owns Search/Reset and obtains the filter command surface from the inherited form scope, preserving normalization and page-query handoff. A nonempty `blocks` list replaces `ZForm`'s automatic body and footer.
+
+The legacy sibling composition remains supported when actions do not need to share a structural section:
+
+```tsx
+blocks: [
+  ZovaRender.block('basic-form:blockFormLayout', { formLayout }),
+  ZovaRender.block('basic-page:blockFilterActions'),
+];
+```
+
+Use either the embedded layout block or the legacy sibling action block, never both; otherwise Search and Reset are rendered twice. Maintained Cabloy Basic list DTOs and current Basic CRUD output prefer the embedded flow, while a bare filter remains the minimal/default form when structural placement is unnecessary. See [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook#use-blocks-for-a-structural-filter-layout) for the filter ownership model.
 
 ## Layout node grammar
 
@@ -90,28 +110,35 @@ A nonempty `blocks` list replaces `ZForm`'s automatic body and footer. Therefore
 ```text
 formLayout
 ├─ field
+├─ block
 ├─ section
-│  └─ field
+│  ├─ field
+│  └─ block
 ├─ group
 │  ├─ field
+│  ├─ block
 │  ├─ group
 │  └─ section
 └─ tabs
    └─ tab
       ├─ field
+      ├─ block
       ├─ group
       └─ section
 ```
 
-| Node      | Key properties                                             | Allowed children         | Use it for                                |
-| --------- | ---------------------------------------------------------- | ------------------------ | ----------------------------------------- |
-| `field`   | required `name`; optional `span`                           | none                     | Place one resolved schema field           |
-| `section` | optional `id`, `title`, `description`, `layout`, `columns` | fields only              | A Grid or wrapping flow field layout      |
-| `group`   | optional `id`, `title`, `description`                      | fields, groups, sections | A semantic, bordered fieldset-style group |
-| `tabs`    | optional `id`                                              | tabs only                | One tab container                         |
-| `tab`     | optional `id`; required `title`                            | fields, groups, sections | One tab panel                             |
+| Node      | Key properties                                             | Allowed children                 | Use it for                                  |
+| --------- | ---------------------------------------------------------- | -------------------------------- | ------------------------------------------- |
+| `field`   | required `name`; optional `span`                           | none                             | Place one resolved schema field             |
+| `block`   | required `block`; optional `span`                          | none                             | Place an existing renderable resource block |
+| `section` | optional `id`, `title`, `description`, `layout`, `columns` | fields and blocks                | A Grid or wrapping flow layout              |
+| `group`   | optional `id`, `title`, `description`                      | fields, blocks, groups, sections | A semantic, bordered fieldset-style group   |
+| `tabs`    | optional `id`                                              | tabs only                        | One tab container                           |
+| `tab`     | optional `id`; required `title`                            | fields, blocks, groups, sections | One tab panel                               |
+
+A section is a layout boundary. It uses the Grid strategy by default; set `layout: 'flow'` for compact, left-packed fields and blocks that wrap at their intrinsic widths. Use a group when the fields need a semantic or visual boundary, and place a section inside that group when it also needs Grid columns or flow placement. There is no separate `row` node: Grid and flow placement create rows automatically.
 
-A section is a layout boundary. It uses the Grid strategy by default; set `layout: 'flow'` for compact, left-packed fields that wrap at their intrinsic widths. Use a group when the fields need a semantic or visual boundary, and place a section inside that group when it also needs Grid columns or flow placement. There is no separate `row` node: Grid and flow placement create rows automatically.
+A `block` node is not a schema field and does not add a request, response, validation, or query value. It wraps an existing `ZovaRender.block(...)` descriptor and renders it with the current form JSX/CEL context. This lets a filter action block participate in a flow section without transferring filter-action behavior into Form Layout.
 
 Nested tabs are not part of the current contract. Likewise, a section cannot contain a group or another section.
 
@@ -286,26 +313,30 @@ ZovaRender.block('basic-page:blockFilter', {
               { type: 'field', name: 'name' },
               { type: 'field', name: 'level' },
               { type: 'field', name: 'createdAt' },
+              {
+                type: 'block',
+                block: ZovaRender.block('basic-page:blockFilterActions'),
+              },
             ],
           },
         ],
       },
     }),
-    ZovaRender.block('basic-page:blockFilterActions'),
   ],
 });
 ```
 
-Here `formFieldLayout.inline: true` controls how each field wrapper is presented. The flow section keeps those compact wrappers left-packed and wraps them when necessary. `basic-page:blockFilterActions` remains required because the custom blocks replace automatic filter body/footer content.
+Here `formFieldLayout.inline: true` controls how each field wrapper is presented. The flow section keeps fields and the action block left-packed and wraps them together when necessary. `basic-page:blockFilterActions` remains required because the custom blocks replace automatic filter body/footer content, but it is now placed through the structural layout rather than as a sibling block.
 
 ## Authoring checklist
 
 1. Start with DTO or resource metadata; do not hand-patch generated `.zova-rest` artifacts.
 2. Use `formLayout` when the requirement is field placement, Grid or flow structure, groups, or tabs.
 3. Use `layout`, `formFieldLayout`, `options`, or provider behaviors when the requirement is one field's wrapper or renderer.
-4. Keep entry actions in page-entry toolbar blocks and filter actions in `basic-page:blockFilterActions`.
-5. Review field names against the scene-specific schema. Unlisted visible fields are appended; unknown and duplicate declarations are silently pruned from the rendered plan.
-6. Use the smallest layout that communicates the form structure; reserve tabs for genuinely separate field groups.
+4. Keep entry actions in page-entry toolbar blocks. Keep filter action semantics in `basic-page:blockFilterActions`; place that block inside Form Layout when the actions must share structural Grid or flow placement with fields.
+5. For maintained Cabloy Basic list filters, prefer one inline flow section that explicitly lists every real filter-schema field in schema order and ends with one embedded `basic-page:blockFilterActions` block. Do not add virtual request fields, alter filter transforms, or combine it with a sibling action block.
+6. Review field names against the scene-specific schema. Unlisted visible fields are appended; unknown and duplicate declarations are silently pruned from the rendered plan.
+7. Use the smallest layout that communicates the form structure; reserve tabs for genuinely separate field groups.
 
 ## Source-reading and verification path
 

package/cabloy-docs/frontend/table-resource-crud-cookbook.md

@@ -107,7 +107,29 @@ A standard resource list page is usually declared through backend-owned block me
 ```tsx
 ZovaRender.block('basic-page:blockPage', {
   blocks: [
-    ZovaRender.block('basic-page:blockFilter'),
+    ZovaRender.block('basic-page:blockFilter', {
+      formFieldLayout: { inline: true },
+      blocks: [
+        ZovaRender.block('basic-form:blockFormLayout', {
+          formLayout: {
+            children: [
+              {
+                type: 'section',
+                layout: 'flow',
+                children: [
+                  { type: 'field', name: 'name' },
+                  { type: 'field', name: 'createdAt' },
+                  {
+                    type: 'block',
+                    block: ZovaRender.block('basic-page:blockFilterActions'),
+                  },
+                ],
+              },
+            ],
+          },
+        }),
+      ],
+    }),
     ZovaRender.block('basic-page:blockToolbarBulk', {
       actions: [ZovaRender.tableActionBulk('basic-table:actionCreate')],
     }),
@@ -117,6 +139,8 @@ ZovaRender.block('basic-page:blockPage', {
 });
 ```
 
+The example follows the current Cabloy Basic CRUD convention: enumerate the real `SelectReq` fields in schema order and embed Search/Reset once so they share the filter flow. A bare `basic-page:blockFilter` remains supported as a minimal/default form, but it delegates placement to the automatic renderer.
+
 That declaration is important because it shows the intended authoring direction clearly:
 
 - backend or shared contract metadata chooses the block composition
@@ -180,7 +204,7 @@ A practical rule is:
 
 ### Use blocks for a structural filter layout
 
-A bare `basic-page:blockFilter` keeps the default schema field rendering and adds Search/Reset controls automatically. For a structured filter, compose the existing form layout block with the filter-specific action block:
+A bare `basic-page:blockFilter` keeps the default schema field rendering and adds Search/Reset controls automatically. For a structured filter whose actions should share the flow with filter fields, embed the existing action block in Form Layout:
 
 ```tsx
 ZovaRender.block('basic-page:blockFilter', {
@@ -196,17 +220,20 @@ ZovaRender.block('basic-page:blockFilter', {
               { type: 'field', name: 'name' },
               { type: 'field', name: 'level' },
               { type: 'field', name: 'createdAt' },
+              {
+                type: 'block',
+                block: ZovaRender.block('basic-page:blockFilterActions'),
+              },
             ],
           },
         ],
       },
     }),
-    ZovaRender.block('basic-page:blockFilterActions'),
   ],
 });
 ```
 
-`basic-form:blockFormLayout` only places schema fields. `basic-page:blockFilterActions` owns Search/Reset placement and invokes the filter command surface supplied through the form scope, so it preserves filter normalization and page-query behavior. A nonempty `blocks` list replaces the automatic body and footer; include the action block explicitly to make the filter operable.
+`basic-form:blockFormLayout` owns structural placement only. `basic-page:blockFilterActions` still owns Search/Reset behavior and invokes the filter command surface supplied through the inherited form scope, preserving filter normalization and page-query behavior. A nonempty `blocks` list replaces the automatic body and footer; include the action block explicitly to make the filter operable. The older sibling action-block composition remains supported, but do not combine it with an embedded action block.
 
 `ZForm.inline` is no longer a form API. Use `formFieldLayout.inline` for field-level compact layout, or use blocks plus `basic-form:blockFormLayout` for structural layout. The flow section above keeps compact filters left-packed and wrapping; use the default Grid section when fields need responsive columns and spans. Read [Form Layout Guide](/frontend/form-layout-guide) for the full node grammar, section layout rules, resolver behavior, tabs, and entry-form composition.
 

package/cabloy-docs/frontend/zova-form-source-reading-map.md

@@ -223,7 +223,7 @@ Use this path when you are asking questions like:
 Use this path when you are asking questions like:
 
 - where does `formLayout` come from in a resource DTO?
-- how are fields, sections, groups, and tabs normalized before rendering?
+- how are fields, embedded blocks, sections, groups, and tabs normalized before rendering?
 - why are omitted visible fields appended or duplicate fields removed?
 - where does Cabloy Basic render responsive grids and tab error badges?
 
@@ -240,15 +240,17 @@ Use this path when you are asking questions like:
 3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/resource/formLayout.ts`
 4. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/formLayout.ts`
 5. `zova/src/suite/cabloy-basic/modules/basic-form/src/component/blockFormLayout/controller.tsx`
-6. `vona/src/suite/a-training/modules/training-student/test/student.test.ts`
+6. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockFilterActions/controller.tsx`
+7. `vona/src/suite/a-training/modules/training-student/test/student.test.ts`
 
 ### What each file clarifies
 
 - the Student DTOs show the entry and filter block composition that supplies layout metadata
 - the OpenAPI type contract defines the legal node grammar and responsive values
-- the resolver reconciles metadata with visible schema fields, generated IDs, and diagnostics
-- the Basic block controller renders sections, groups, tabs, and field spans while delegating widgets to `$$form.renderField(...)`
-- the Student test verifies emitted metadata nesting, columns, spans, and optional IDs; it is not a browser rendering test
+- the resolver reconciles field metadata with visible schema fields, generated IDs, diagnostics, and preserved embedded blocks
+- the Basic block controller renders sections, groups, tabs, field spans, and embedded blocks while delegating fields to `$$form.renderField(...)`
+- `blockFilterActions` shows how a block rendered inside Form Layout reuses the inherited form CEL scope to invoke `$$filter`
+- the Student test verifies emitted metadata nesting, columns, spans, embedded action blocks, and optional IDs; it is not a browser rendering test
 
 ## 8. Resource-driven CRUD page integration
 

package/cabloy-docs/frontend/zova-form-under-the-hood.md

@@ -414,11 +414,14 @@ That means automatic schema-driven rendering is not happening magically in the w
 
 When `ZForm` receives a nonempty block list, the render bean delegates body rendering to those blocks instead of iterating schema fields directly. For Cabloy Basic structural forms, `basic-form:blockFormLayout` resolves `formLayout` against the form's current schema properties and calls `$$form.renderField(...)` for each surviving layout field.
 
+Form Layout also supports a leaf `block` node. It wraps an existing resource block descriptor and the Basic renderer invokes it with the inherited `IJsxRenderContextForm`, including the same JSX runtime and CEL scope. The node has no schema property or field value; for example, a filter can place `basic-page:blockFilterActions` inside a flow section while that action block continues to read `$$filter` from the filter-owned form scope.
+
 This keeps ownership separate:
 
 - the form controller owns schema properties, field state, validation, and field rendering
-- the shared form-layout resolver normalizes field placement metadata
-- the Basic layout block renders sections, groups, grids, and tabs
+- the shared form-layout resolver normalizes field placement metadata while preserving non-field block nodes
+- the Basic layout block renders sections, groups, grids, tabs, and embedded blocks
+- embedded blocks own their behavior; Form Layout owns only their placement
 - field-layout behaviors still own each field wrapper and its visible validation message
 
 Read [Form Layout Guide](/frontend/form-layout-guide) for the DTO authoring grammar, resolver behavior, and Basic-specific responsive/tab behavior.

package/cabloy-docs/fullstack/backend-metadata-to-frontend-table-actions.md

@@ -152,12 +152,12 @@ A practical reading takeaway is:
 
 Table actions do not live in isolation. They appear inside a resource-page block composition.
 
-Representative shape:
+Representative abbreviated page-chain shape (the filter’s internal Form Layout is omitted here because this page focuses on table actions):
 
 ```tsx
 ZovaRender.block('basic-page:blockPage', {
   blocks: [
-    ZovaRender.block('basic-page:blockFilter'),
+    /* basic-page:blockFilter with its resource-specific filter layout */
     ZovaRender.block('basic-page:blockToolbarBulk', {
       actions: [ZovaRender.tableActionBulk('basic-table:actionCreate')],
     }),

package/e2e/specs/cabloy-basic/basic.spec.ts

@@ -209,6 +209,8 @@ test(
     await expect(name).toBeVisible();
     await expect(level).toBeVisible();
     await expect(dates).toHaveCount(2);
+    await expect(search).toHaveCount(1);
+    await expect(reset).toHaveCount(1);
     await expect(search).toBeVisible();
     await expect(reset).toBeVisible();
 
@@ -223,6 +225,13 @@ test(
     for (const geometry of wideGeometry) {
       expect(geometry.field.right).toBeLessThanOrEqual(geometry.container.right + 1);
     }
+    const actionFlowMatchesFieldFlow = await search.evaluate(element => {
+      const actionFlow = element.parentElement?.parentElement?.parentElement;
+      const fieldFlow = element.closest('section')?.querySelector('label')
+        ?.parentElement?.parentElement;
+      return actionFlow === fieldFlow;
+    });
+    expect(actionFlowMatchesFieldFlow).toBeTruthy();
 
     await page.setViewportSize({ width: 700, height: 900 });
     const drawer = page.locator('.drawer').first();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.120",
+  "version": "5.1.122",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/vona/packages-cli/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.134",
+  "version": "1.1.135",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudBasic/boilerplate/src/dto/{{resourceName}}SelectResItem.tsx_

@@ -14,7 +14,29 @@ export interface IDtoOptions<%=argv.resourceNameCapitalize%>SelectResItem extend
   blocks: [
     ZovaRender.block('basic-page:blockPage', {
       blocks: [
-        ZovaRender.block('basic-page:blockFilter'),
+        ZovaRender.block('basic-page:blockFilter', {
+          formFieldLayout: { inline: true },
+          blocks: [
+            ZovaRender.block('basic-form:blockFormLayout', {
+              formLayout: {
+                children: [
+                  {
+                    type: 'section',
+                    layout: 'flow',
+                    children: [
+                      { type: 'field', name: 'name' },
+                      { type: 'field', name: 'createdAt' },
+                      {
+                        type: 'block',
+                        block: ZovaRender.block('basic-page:blockFilterActions'),
+                      },
+                    ],
+                  },
+                ],
+              },
+            }),
+          ],
+        }),
         ZovaRender.block('basic-page:blockToolbarBulk', {
           actions: [ZovaRender.tableActionBulk('basic-table:actionCreate')],
         }),
@@ -29,7 +51,10 @@ export class Dto<%=argv.resourceNameCapitalize%>SelectResItem extends $Dto.get((
     v.title($locale('Operations')),
     ZovaRender.order(1, 'max'),
     ZovaRender.cell('basic-table:actionOperationsRow', {
-      actions: [ZovaRender.tableActionRow('basic-table:actionUpdate'), ZovaRender.tableActionRow('basic-table:actionDelete')],
+      actions: [
+        ZovaRender.tableActionRow('basic-table:actionUpdate'),
+        ZovaRender.tableActionRow('basic-table:actionDelete'),
+      ],
     }),
   )
   _operationsRow?: unknown;

package/vona/packages-cli/cli-set-api/cli/templates/tools/crudStart/boilerplate/src/dto/{{resourceName}}SelectResItem.tsx_

@@ -14,7 +14,29 @@ export interface IDtoOptions<%=argv.resourceNameCapitalize%>SelectResItem extend
   blocks: [
     ZovaRender.block('start-page:blockPage', {
       blocks: [
-        ZovaRender.block('start-page:blockFilter'),
+        ZovaRender.block('start-page:blockFilter', {
+          formFieldLayout: { inline: true },
+          blocks: [
+            ZovaRender.block('start-form:blockFormLayout', {
+              formLayout: {
+                children: [
+                  {
+                    type: 'section',
+                    layout: 'flow',
+                    children: [
+                      { type: 'field', name: 'name' },
+                      { type: 'field', name: 'createdAt' },
+                      {
+                        type: 'block',
+                        block: ZovaRender.block('start-page:blockFilterActions'),
+                      },
+                    ],
+                  },
+                ],
+              },
+            }),
+          ],
+        }),
         ZovaRender.block('start-page:blockToolbarBulk', {
           actions: [ZovaRender.tableActionBulk('start-table:actionCreate')],
         }),
@@ -28,7 +50,10 @@ export class Dto<%=argv.resourceNameCapitalize%>SelectResItem extends $Dto.get((
     v.title($locale('Operations')),
     ZovaRender.order(1, 'max'),
     ZovaRender.cell('start-table:actionOperationsRow', {
-      actions: [ZovaRender.tableActionRow('start-table:actionUpdate'), ZovaRender.tableActionRow('start-table:actionDelete')],
+      actions: [
+        ZovaRender.tableActionRow('start-table:actionUpdate'),
+        ZovaRender.tableActionRow('start-table:actionDelete'),
+      ],
     }),
   )
   _operationsRow?: unknown;

package/vona/packages-cli/cli-set-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli-set-api",
-  "version": "1.1.132",
+  "version": "1.1.133",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [