cabloy 5.1.158 → 5.1.160

package/repo-docs/frontend/table-guide.md

@@ -47,7 +47,7 @@ If you only remember one idea, remember this one:
 That leads to three common authoring surfaces:
 
 - `ZTable` — the root table component
-- schema `rest.table` metadata — the default source of visibility, order, and render decisions
+- schema metadata — `ZovaRender.column(...)` supplies table-column layout/capability metadata, while shared/table-scene overlays supply effective visibility, order, and render metadata
 - `tableCell` beans — the main extension surface for reusable cell rendering
 
 ## One running example through this guide: Student list page
@@ -123,17 +123,12 @@ A practical reading takeaway is:
 
 In the default path, `ZTable` reads table-scene metadata from the row schema.
 
-The key table-facing metadata surface is the schema field `rest.table`, especially values such as:
-
-- `order`
-- `visible`
-- `render`
-- `columnProps`
+The table sees the **effective table metadata**, not only one literal source object. It combines shared field `rest` metadata with the table-scene `rest.table` overlay, then orders the resulting properties by effective `rest.order`.
 
 A simplified mental model is:
 
 ```text
-schema row -> load table properties -> sort by order -> filter by visible -> build columns -> render cells
+schema row -> merge table metadata -> sort by order -> filter by visible -> build columns -> render cells
 ```
 
 That means the default list-page question becomes less:
@@ -146,6 +141,58 @@ and more:
 
 This is why table work often belongs in the broader contract loop when the real source of truth is backend field metadata.
 
+## Step 4: Configure physical columns with `ZovaRender.column(...)`
+
+`ZovaRender.column(...)` is a shared Cabloy/Zova schema-metadata API available in both Cabloy Basic and Cabloy Start. It returns a schema transformer that writes column options under `rest.table`; it does **not** register a frontend column or render a cell by itself.
+
+```ts
+@Api.field(
+  v.title($locale('Name')),
+  ZovaRender.column({
+    align: 'left',
+    width: 240,
+    fixed: 'left',
+    enableSorting: true,
+    sortDescFirst: true,
+  }),
+  v.string(),
+)
+name: string;
+```
+
+The current options are:
+
+| Option          | Meaning in the table runtime                                                                                                   |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `order`         | Orders this property among the effective table properties. For shared field order, `ZovaRender.order(...)` is usually clearer. |
+| `align`         | Applies `left`, `center`, or `right` text alignment to the header and cells.                                                   |
+| `width`         | Supplies the TanStack column size and current renderers apply it as pixel width and minimum width.                             |
+| `fixed`         | Pins the column to the `left` or `right`; the table runtime calculates pinning and renderers apply sticky offsets.             |
+| `enableSorting` | Requests a sortable header, subject to the order-schema capability described below.                                            |
+| `sortDescFirst` | Makes the first header toggle descend; it does not change backend order syntax.                                                |
+
+`ZovaRender.column(...)` configures the physical column. `ZovaRender.cell(...)` independently selects the cell renderer and its options. For example, a virtual Operations field can be right-pinned and centered while its content comes from a reusable `tableCell` resource:
+
+```ts
+@Api.field(
+  v.title($locale('Operations')),
+  ZovaRender.order(1, 'max'),
+  ZovaRender.column({ align: 'center', width: 360, fixed: 'right' }),
+  ZovaRender.cell('basic-table:actionOperationsRow', { actions }),
+)
+_operationsRow?: unknown;
+```
+
+The `basic-table:*` renderer key in this example is Cabloy Basic-specific. The `ZovaRender.column(...)` contract itself is shared; use the active edition's renderer keys when selecting a cell resource.
+
+### Enable server-backed sorting
+
+`enableSorting: true` is necessary but not sufficient. The same field, canonical key, or schema alias must also exist in `schemaOrder`; otherwise the table deliberately creates a non-sortable column.
+
+A direct `ZTable` consumer owns and passes `schemaOrder`, controlled `sorting`, and `onSortingChange`. In the standard Cabloy Basic resource-page path, `basic-page:blockTable` passes those values from `basic-page:blockPage`; the page translates one manual table sort into backend `orders` and reloads the resource query. The loaded page is not client-side sorted by TanStack.
+
+For relation-order rewriting, see [Existing Resource Field Update](/backend/resource-field-update#filter-and-sort-a-relation-by-its-display-field). For the resource-page bridge, see [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook).
+
 A practical expression example is a schema-driven cell display that formats the current row value through CEL:
 
 ```text
@@ -156,7 +203,7 @@ In the shared table CEL scope, `getValue(name)` reads the current row value and
 
 For the schema side of that contract, also see [API Schema Guide](/frontend/api-schema-guide).
 
-## Step 4: Use built-in or custom `tableCell` render resources
+## Step 5: Use built-in or custom `tableCell` render resources
 
 A column render is usually chosen through schema metadata such as:
 
@@ -184,7 +231,7 @@ A practical rule is:
 - use built-in `tableCell` resources first
 - add a custom `tableCell` bean only when the business UI really needs module-owned rendering behavior
 
-## Step 5: Create a custom `tableCell` bean
+## Step 6: Create a custom `tableCell` bean
 
 When a built-in renderer is not enough, use the existing CLI-backed scene workflow.
 
@@ -230,7 +277,7 @@ That scaffold is useful because it starts from the correct Zova scene contract:
 
 For the broader scene system behind this decorator, see [Bean Scene Authoring](/frontend/bean-scene-authoring).
 
-## Step 6: Add page-local custom columns with `getColumns(...)`
+## Step 7: Add page-local custom columns with `getColumns(...)`
 
 When most columns should stay schema-driven but one column should be page-local, use `getColumns(...)`.
 
@@ -275,7 +322,7 @@ A practical caveat is:
 
 So a mixed table does **not** mean bypassing Zova. It means extending the existing runtime through its own hooks.
 
-## Step 7: Use resource-driven page blocks for CRUD list pages
+## Step 8: Use resource-driven page blocks for CRUD list pages
 
 For standard resource pages, the more common public surface is not direct `ZTable` usage. It is the block-based page runtime:
 
@@ -299,7 +346,7 @@ This gives you a cohesive CRUD path where:
 
 For the resource ownership side of that page shape, see [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern).
 
-## Step 8: Know when to use `BeanControllerPageTableBase`
+## Step 9: Know when to use `BeanControllerPageTableBase`
 
 If your table belongs directly to a page controller rather than a reusable component controller, the page-oriented base class already exists:
 
@@ -322,15 +369,19 @@ TanStack Table is still important, but the business-facing runtime is controller
 
 For many resource pages, the faster path is to let `rest.table` metadata describe the default columns first.
 
-### Mistake 3: Bypassing `tableCell` beans for reusable cell behavior
+### Mistake 3: Treating `ZovaRender.column(...)` as a cell renderer
+
+`ZovaRender.column(...)` supplies column layout and sorting metadata. Use `ZovaRender.cell(...)` to name the cell render target, and use a `tableCell` bean when that reusable renderer needs module-owned behavior.
+
+### Mistake 4: Bypassing `tableCell` beans for reusable cell behavior
 
 If a renderer should be shared across pages or modules, prefer a `tableCell` resource over repeated page-local callbacks.
 
-### Mistake 4: Treating `controllerRef` like a generic Vue DOM ref
+### Mistake 5: Treating `controllerRef` like a generic Vue DOM ref
 
 `controllerRef` gives you the table controller instance, not a plain DOM element.
 
-### Mistake 5: Rebuilding CRUD list wiring manually when `basic-page` already owns it
+### Mistake 6: Rebuilding CRUD list wiring manually when `basic-page` already owns it
 
 For standard resource pages, prefer the existing block/page runtime before hand-building a custom table flow.
 
@@ -340,12 +391,12 @@ If you want the shortest accurate path to a real business table, use this order:
 
 1. make sure the backend row schema is already the right contract truth
 2. start with a resource page or direct `ZTable`
-3. let schema metadata drive the default columns
-4. reuse built-in `tableCell` renderers first
+3. let schema metadata drive the default columns; add `ZovaRender.column(...)` only where layout, pinning, or sorting metadata is needed
+4. use `ZovaRender.cell(...)` and built-in `tableCell` renderers for cell content first
 5. add page-local `getColumns(...)` only where needed
 6. create custom `tableCell` beans only where the UI becomes business-specific
 7. continue with [TableCell Authoring Cookbook](/frontend/table-cell-cookbook) when you want concrete patterns for custom cell beans and row actions
-8. continue with [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook) when you want the standard resource-page integration path for filter, bulk actions, table, and pager
+8. continue with [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook) when you want the standard resource-page integration path for filter, bulk actions, table, pager, and server sorting
 9. continue with [Zova Table Under the Hood](/frontend/zova-table-under-the-hood) when you want the runtime explanation behind the public authoring surface
 10. continue with [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map) when you need framework-level source details and targeted file-order guidance
 
@@ -359,9 +410,11 @@ When documenting or changing a table workflow, verify in this order:
    npm run zova :create:bean --help
    ```
 
-2. confirm the `tableCell` scene metadata still exists in the current `a-table` module
-3. confirm the runtime claims against the current `a-table`, `basic-table`, and `basic-page` source
-4. if you changed docs, build the docs site:
+2. confirm the `ZovaRender.column(...)` option contract and table-scene metadata merge still match current source
+3. confirm the `tableCell` scene metadata still exists in the current `a-table` module
+4. for sortable resource columns, verify header state, fixed-column layout/overflow where relevant, and the backend `orders` request
+5. confirm the runtime claims against the current `a-table`, `basic-table`, and `basic-page` source
+6. if you changed docs, build the docs site:
 
    ```bash
    npm run docs:build

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

@@ -269,6 +269,8 @@ Its bridge role is very clear:
 - render `ZTable`
 - pass page data into `data`
 - pass row schema into `schema`
+- pass the resource order schema into `schemaOrder`
+- pass controlled `sorting` and `onSortingChange`
 - pass page CEL scope into `tableScope`
 - capture the table controller through `controllerRef`
 
@@ -329,10 +331,13 @@ _operationsRow?: unknown;
 
 This is the practical reverse-sharing model:
 
-- the backend row contract chooses the table cell resource identity
+- `ZovaRender.column(...)` configures physical-column behavior such as alignment, width, pinning, and sorting eligibility
+- `ZovaRender.cell(...)` chooses the table-cell resource identity and its options
 - the frontend table runtime resolves that resource
 - the page block and table block do not need page-local hard-coded row-action wiring
 
+For example, an Operations field can add `ZovaRender.column({ align: 'center', width: 360, fixed: 'right' })` beside the existing `ZovaRender.cell(...)`. `ZovaRender.column(...)` is a shared Basic/Start capability; the `basic-table:*` cell key remains a Cabloy Basic choice.
+
 For the built-in metadata-sharing teaching path, see [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing).
 
 For the forward-chain row-action teaching path, see [Tutorial 5: Backend Contract Sharing](/fullstack/tutorial-5-backend-contract-sharing).
@@ -346,10 +351,24 @@ For standard CRUD list pages, most customization should happen in one of these p
 Use this when:
 
 - a field should change order
+- a column should change alignment, width, or left/right pinning
+- a server-authorized field should expose a sortable header
 - a column should be visible or hidden
 - a field should use a different built-in or custom `tableCell`
 
-This is usually the first and best extension point.
+This is usually the first and best extension point. Use `ZovaRender.column(...)` for the column metadata and `ZovaRender.cell(...)` for the cell renderer; do not treat either helper as a replacement for the other.
+
+### Enable standard resource-page sorting
+
+For a normal Cabloy Basic resource list, backend field metadata can request a sortable column with:
+
+```ts
+ZovaRender.column({ enableSorting: true });
+```
+
+The field must also be present in the resource `schemaOrder`; that order schema remains the authority for whether the header is actually sortable. `blockTable` forwards the order schema plus controlled sorting state into `ZTable`, and `blockPage` turns one header selection into backend `orders` before reloading the resource query. This is server sorting, not local reordering of the current page.
+
+For the full shared `ZovaRender.column(...)` contract, see [Table Guide](/frontend/table-guide#configure-physical-columns-with-zovarendercolumn). For relation-backed order rewriting, see [Existing Resource Field Update](/backend/resource-field-update#filter-and-sort-a-relation-by-its-display-field).
 
 ### Extension point B: backend block composition metadata
 
@@ -505,8 +524,8 @@ If you want the shortest path to a real CRUD list page, use this order:
 1. generate or confirm the backend CRUD contract thread
 2. confirm the resource-owner model already exposes the required schemas and permissions
 3. keep the standard `blockPage -> blockFilter -> blockToolbarBulk -> blockTable -> blockPager` chain
-4. refine backend row metadata for visible columns and row actions
-5. reuse built-in `tableCell` resources first
+4. refine backend row metadata for visible columns, layout/pinning/sort capability through `ZovaRender.column(...)`, and row actions
+5. reuse `ZovaRender.cell(...)` with built-in `tableCell` resources first
 6. add custom `tableCell` resources only where the UI becomes business-specific
 7. change block controllers only when the existing runtime is structurally insufficient
 8. continue with [Table Guide](/frontend/table-guide) for the public `ZTable` surface
@@ -533,6 +552,8 @@ When authoring or documenting a resource CRUD list page, verify in this order:
    - filter works
    - bulk actions render correctly
    - table columns and row actions match metadata
+   - fixed columns, widths, and overflow behave as intended when configured
+   - sortable headers expose the expected state and reload with the intended backend `orders`
    - pager updates the list correctly
 7. if you changed docs, build the docs site:
 

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

@@ -233,7 +233,7 @@ Use this path when you are asking questions like:
 - where does `formLayout` come from in a resource DTO?
 - how are fields, embedded blocks, sections, groups, and tabs normalized before rendering?
 - how do canonical keys, preserved schema aliases, and unique relation-prefix shorthand resolve to one field?
-- why are omitted visible fields appended or duplicate fields removed?
+- why do omitted fields not render, or duplicate fields get removed?
 - where does Cabloy Basic render responsive grids and tab error badges?
 
 ### Read the docs first
@@ -266,7 +266,7 @@ Use this path when you are asking questions like:
 - the resolver filters visible fields, resolves exact canonical keys before unique aliases and unique prefixes, and records duplicate identity and tab paths by canonical key
 - the Basic block controller renders sections, groups, tabs, field spans, and embedded blocks while delegating canonical field names to `$$form.renderField(...)`
 - `blockFilterActions` shows how a block rendered inside Form Layout reuses the inherited form CEL scope to invoke `$$filter`
-- the OpenAPI and Form Layout unit tests verify canonicalization, alias precedence, ambiguity, duplicates, visibility, root append, and tab paths
+- the OpenAPI and Form Layout unit tests verify canonicalization, explicit field inclusion, alias precedence, ambiguity, duplicates, visibility, and tab paths
 - 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/repo-docs/frontend/zova-form-under-the-hood.md

@@ -454,7 +454,7 @@ 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.
 
-For a field declaration, the shared resolver first accepts an exact canonical key, then a uniquely mapped preserved schema alias, and then a unique relation-prefix shorthand. It rewrites an alias or shorthand to the canonical key before calling `$$form.renderField(...)`. Exact canonical keys win over colliding aliases; ambiguous aliases or prefixes are reported as `unknownField`. Duplicate tracking and tab-path bookkeeping use the canonical key, while visible canonical fields not placed by a surviving declaration are appended afterward. See [Form Layout Guide](/frontend/form-layout-guide#how-the-resolver-handles-the-declared-tree) for the full DTO authoring rules.
+For a field declaration, the shared resolver first accepts an exact canonical key, then a uniquely mapped preserved schema alias, and then a unique relation-prefix shorthand. It rewrites an alias or shorthand to the canonical key before calling `$$form.renderField(...)`. Exact canonical keys win over colliding aliases; ambiguous aliases or prefixes are reported as `unknownField`. A configured Form Layout is an explicit allow-list: only fields represented by surviving declarations render. Duplicate tracking and tab-path bookkeeping use the canonical key. See [Form Layout Guide](/frontend/form-layout-guide#how-the-resolver-handles-the-declared-tree) for the full DTO authoring rules.
 
 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.
 

package/repo-docs/frontend/zova-reactivity-under-the-hood.md

@@ -151,6 +151,62 @@ This is one of the most important source-level facts for understanding Zova.
 
 Zova does not require the business author to write `reactive({ ... })` around controller state, because the framework already treats the controller bean as the reactive object.
 
+#### Construction-time `this` and the exposed reactive bean
+
+There is one lifecycle boundary that matters when a callback closes over `this`:
+
+1. the container first constructs the raw class instance with `new BeanClass(...)`;
+2. it then exposes the framework-managed reactive/proxied bean; and
+3. it invokes `__init__()` only after that preparation completes.
+
+That distinction is normally invisible when a controller uses ordinary methods and render-time `this.member` access. It matters for a class-field arrow callback that mutates controller state, because the arrow is created during construction and lexically captures the construction-time raw `this`:
+
+```typescript
+class ControllerPageCounter {
+  count = 0;
+
+  // Avoid for a state-mutating controller callback.
+  onIncrement = () => {
+    this.count++;
+  };
+}
+```
+
+The field can change on the raw instance, but the mutation bypasses the reactive/proxied bean through which render dependencies were collected. Vue therefore receives no invalidation notification. A later update to another dependency can rerender the component and reveal the changed underlying value, which can make this look intermittent.
+
+Prefer an ordinary controller method for a normal TSX action:
+
+```typescript
+class ControllerPageCounter {
+  count = 0;
+
+  increment() {
+    this.count++;
+  }
+
+  protected render() {
+    return <button onClick={() => this.increment()}>Increment</button>;
+  }
+}
+```
+
+If an external API requires a stable stored callback, create that closure in `__init__()` instead. At that point, its lexical `this` is the framework-exposed reactive/proxied bean:
+
+```typescript
+class ControllerPageCounter {
+  count = 0;
+  onIncrement: () => void;
+
+  protected async __init__() {
+    this.onIncrement = () => {
+      this.count++;
+    };
+  }
+}
+```
+
+This is not a rule that arrow functions are generally non-reactive. The narrow hazard is a **class-field arrow callback that captures construction-time `this` and mutates bean state**.
+
 ### 4. `$computed()` is an instance-scoped wrapper around Vue `computed(...)`
 
 In:
@@ -238,21 +294,21 @@ A practical reading takeaway is:
 
 ### 7. Field mutation becomes normal reactive invalidation and rerender
 
-Once the controller bean is reactive and render has read its fields, changes such as:
+Once render has read fields through the framework-exposed reactive/proxied controller, a mutation through that same identity, such as:
 
 ```typescript
 this.count++;
 ```
 
-behave the way a Vue reader would expect at the reactive-engine level:
+behaves the way a Vue reader would expect at the reactive-engine level:
 
 - the field change invalidates dependencies
 - computed values depending on that field are recomputed
 - the next render sees the updated values
 
-So the runtime behavior is still recognizably Vue-like.
+The construction-time class-field arrow case described above is the exception: its raw `this` can change the underlying field without triggering the dependency that render collected through the exposed bean.
 
-The architectural surface is what changed.
+So the runtime behavior is still recognizably Vue-like. The architectural surface, including the bean lifecycle and identity boundary, is what changed.
 
 ## A compact call-flow sketch
 
@@ -260,13 +316,13 @@ The architectural surface is what changed.
 useControllerPage(...)
   -> _useController(...)
   -> ctx.bean._newBeanInner(..., markReactive = true)
-  -> BeanContainer creates controller bean
-  -> BeanContainer applies reactive(...)
-  -> controller __init__ wires $computed / $watch helpers
+  -> BeanContainer constructs the raw controller bean
+  -> BeanContainer exposes the reactive/proxied controller bean
+  -> controller __init__ wires $computed / $watch helpers and any stored callbacks
   -> component render is patched toward controller/render bean
   -> render-time controller data update refreshes page route data
-  -> render reads controller fields
-  -> field mutation invalidates dependencies
+  -> render reads fields through the exposed bean
+  -> mutation through that same identity invalidates dependencies
   -> rerender produces updated UI
 ```
 

package/repo-docs/frontend/zova-table-source-reading-map.md

@@ -120,7 +120,8 @@ Use this path when you are asking questions like:
 Use this path when you are asking questions like:
 
 - how does a row schema become visible columns?
-- where do `visible`, `order`, `render`, and `columnProps` come from?
+- where do `order`, `align`, `width`, `fixed`, `enableSorting`, and `sortDescFirst` come from?
+- where do `visible`, `render`, and `columnProps` come from?
 - how does the table scene differ from form or filter scenes?
 
 ### Read the docs first
@@ -130,17 +131,51 @@ Use this path when you are asking questions like:
 
 ### Then read source in this order
 
+1. `zova/packages-cli/cli-set-front/cli/templates/rest/rest.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/rest.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx`
+5. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx`
+
+### What each file clarifies
+
+- `cli/templates/rest/rest.ts` shows that `ZovaRender.column(...)` writes `ITableColumnOptions` under `rest.table`
+- `types/rest.ts` defines `order`, `align`, `width`, `fixed`, `enableSorting`, and `sortDescFirst`
+- `schema.ts` shows `loadSchemaProperties(...)`, `$ref` resolution, and the merge of shared `rest` metadata with table-scene overlays
+- `controller.tsx` shows `_createProperties()`, `_createTableMeta()`, `_createColumnsMiddle()`, order-schema sorting eligibility, and pinning
+- `render.tsx` shows how effective metadata becomes alignment, dimensions, fixed-column styles, and sortable header DOM
+
+## 4. Column metadata, sortable headers, and resource orders
+
+Use this path when you are asking questions like:
+
+- why did `ZovaRender.column({ enableSorting: true })` not make a header sortable?
+- how do fixed columns become sticky left/right columns?
+- how does one header click become a resource request `orders` value?
+
+### Read the docs first
+
+- [Table Guide](/frontend/table-guide)
+- [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
+- [Existing Resource Field Update](/backend/resource-field-update#filter-and-sort-a-relation-by-its-display-field)
+
+### Then read source in this order
+
 1. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx`
-2. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
-3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/rest.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/render.tsx`
+3. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx`
+4. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
 
 ### What each file clarifies
 
-- `controller.tsx` shows `_createProperties()`, `_createTableMeta()`, and `_createColumnsMiddle()`
-- `schema.ts` shows `loadSchemaProperties(...)`, `$ref` resolution, and scene-specific `rest` overlays
-- `rest.ts` shows the schema extension contract, including `rest.table` and table-related render types
+- `controller.tsx` shows that `enableSorting` also requires the property key or aliases to exist in `schemaOrder`, and shows left/right pinning construction
+- `render.tsx` shows the header toggle, `aria-sort`, indicators, and sticky styles
+- `blockTable/controller.tsx` shows the handoff of `schemaOrder`, controlled sorting, and `onSortingChange`
+- `blockPage/controller.tsx` shows conversion of the single current sort into backend `orders` and query reload
+
+The result is a controlled, manual server-sorting path: the standard resource page does not client-side sort rows that have already been fetched. The `basic-page` files are Cabloy Basic specimens; the metadata API and base Zova Table behavior are shared with Cabloy Start, whose page module paths must be resolved in that edition.
 
-## 4. `tableCell` bean-scene contract and decorator surface
+## 5. `tableCell` bean-scene contract and decorator surface
 
 Use this path when you are asking questions like:
 
@@ -168,7 +203,7 @@ Use this path when you are asking questions like:
 - `package.json` shows `zovaModule.onions.tableCell` and boilerplate metadata
 - the boilerplate files show the intended scaffold shape for normal cells and row-action cells
 
-## 5. Cell render pipeline and CEL/JSX scope
+## 6. Cell render pipeline and CEL/JSX scope
 
 Use this path when you are asking questions like:
 
@@ -193,7 +228,7 @@ Use this path when you are asking questions like:
 - `tableColumn.ts` shows column scope, cell scope, and table column render types
 - `tableCell.ts` shows the render-context contract received by a `tableCell` bean
 
-## 6. Representative built-in cell renderers
+## 7. Representative built-in cell renderers
 
 Use this path when you are asking questions like:
 
@@ -220,7 +255,7 @@ Use this path when you are asking questions like:
 - `tableCell.select.tsx` shows value-to-item mapping
 - `actionOperationsRow.tsx` shows advanced visibility checks, nested action rendering, and permission-aware orchestration
 
-## 7. Custom columns through `getColumns(...)`
+## 8. Custom columns through `getColumns(...)`
 
 Use this path when you are asking questions like:
 
@@ -243,15 +278,15 @@ Use this path when you are asking questions like:
 
 - `types/table.ts` shows `TypeTableGetColumns` and `TypeTableCreateColumnRender`
 - `controller.tsx` shows how custom columns are given `next(...)`, `createColumnRender(...)`, and the table controller itself
-- `basic-table/render.tsx` shows a module-level consumer wrapping `ZTable` rather than replacing its runtime
+- `basic-table/render.tsx` is a Cabloy Basic forwarding wrapper around `ZTable`; it preserves the custom-column hook rather than serving as an executable custom-column specimen
 
-## 8. Resource-page integration
+## 9. Resource-page integration
 
 Use this path when you are asking questions like:
 
 - how does a resource list page feed schema and data into `ZTable`?
-- where do `data`, `schemaRow`, and `tableScope` come from?
-- where should permission-sensitive table refresh be debugged?
+- where do `data`, `schemaRow`, `schemaOrder`, and `tableScope` come from?
+- where should permission-sensitive table refresh or resource sorting be debugged?
 
 ### Read the docs first
 
@@ -266,11 +301,11 @@ Use this path when you are asking questions like:
 
 ### What each file clarifies
 
-- `blockPage/controller.tsx` shows resource ownership, query state, page CEL scope, permissions, and table refresh integration
-- `blockTable/controller.tsx` shows the direct bridge from page block to `ZTable`
+- `blockPage/controller.tsx` shows resource ownership, query state, page CEL scope, permissions, table refresh integration, and `orders` mapping
+- `blockTable/controller.tsx` shows the direct bridge from page block to `ZTable`, including order schema and controlled sorting props
 - the Vona DTO specimen shows the block-based page composition consumed from backend-owned metadata
 
-## 9. Representative specimens to read before editing the framework
+## 10. Representative specimens to read before editing the framework
 
 Use this section when you want one small example before reading framework internals.
 
@@ -288,7 +323,7 @@ Use this section when you want one small example before reading framework intern
 
 Together they give you the public integration, the advanced cell path, and the minimal cell path before you descend into the whole table runtime.
 
-## 10. A compact reading strategy
+## 11. A compact reading strategy
 
 When in doubt, use this order:
 
@@ -301,7 +336,7 @@ When in doubt, use this order:
 
 That order usually gets you to the answer faster than starting from the deepest runtime files first.
 
-## 11. Final takeaway
+## 12. Final takeaway
 
 The fastest way to read Zova Table accurately is not to memorize every file in `a-table`.